man: Switch arc4random(3bsd) man page from OpenBSD to NetBSD

This gets rid of the last BSD-4-clause licensed file in the project.

The man page will probably need to be adapted to the current
implementation, but that can be done piecemeal afterwards.

Closes: #7

COPYING

@@ -6,37 +6,6 @@ Copyright:
  Copyright © 2004-2006, 2008-2022 Guillem Jover <guillem@hadrons.org>
 License: BSD-3-clause
 
-Files:
- man/arc4random.3bsd
-Copyright:
- Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
- All rights reserved.
-License: BSD-4-clause-Niels-Provos
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
- 1. Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimer.
- 2. Redistributions in binary form must reproduce the above copyright
-    notice, this list of conditions and the following disclaimer in the
-    documentation and/or other materials provided with the distribution.
- 3. All advertising materials mentioning features or use of this software
-    must display the following acknowledgement:
-      This product includes software developed by Niels Provos.
- 4. The name of the author may not be used to endorse or promote products
-    derived from this software without specific prior written permission.
- .
- THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
- IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
- IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
- INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
- NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
- THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
 Files:
  include/bsd/err.h
  include/bsd/stdlib.h
@@ -202,6 +171,7 @@ License: BSD-5-clause-Peter-Wemm
 
 Files:
  include/bsd/stringlist.h
+ man/arc4random.3bsd
  man/fmtcheck.3bsd
  man/humanize_number.3bsd
  man/stringlist.3bsd
@@ -216,6 +186,12 @@ Copyright:
  Copyright © 2013 John-Mark Gurney <jmg@FreeBSD.org>
  All rights reserved.
  .
+ Copyright © 2014 The NetBSD Foundation, Inc.
+ All rights reserved.
+ .
+ Some code was derived from software contributed to The NetBSD Foundation
+ by Taylor R. Campbell.
+ .
  Some code was contributed to The NetBSD Foundation by Allen Briggs.
  .
  Some code was contributed to The NetBSD Foundation by Luke Mewburn.

man/arc4random.3bsd

@@ -1,8 +1,11 @@
-.\" $OpenBSD: arc4random.3,v 1.37 2019/09/29 16:30:35 jmc Exp $
+.\"	$NetBSD: arc4random.3,v 1.21 2016/07/15 21:19:19 wiz Exp $
 .\"
-.\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
+.\" Copyright (c) 2014 The NetBSD Foundation, Inc.
 .\" All rights reserved.
 .\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Taylor R. Campbell.
+.\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
 .\" are met:
@@ -11,32 +14,26 @@
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\"    must display the following acknowledgement:
-.\"      This product includes software developed by Niels Provos.
-.\" 4. The name of the author may not be used to endorse or promote products
-.\"    derived from this software without specific prior written permission.
 .\"
-.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
-.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
-.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
-.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.\" Manual page, using -mandoc macros
+.Dd November 16, 2014
-.\"
-.Dd $Mdocdate: September 29 2019 $
 .Dt arc4random 3bsd
 .Os
 .Sh NAME
 .Nm arc4random ,
-.Nm arc4random_buf ,
 .Nm arc4random_uniform ,
+.Nm arc4random_buf ,
 .Nm arc4random_stir ,
 .Nm arc4random_addrandom
 .Nd random number generator
@@ -51,102 +48,281 @@
 for include usage.)
 .Ft uint32_t
 .Fn arc4random "void"
-.Ft void
-.Fn arc4random_buf "void *buf" "size_t nbytes"
 .Ft uint32_t
-.Fn arc4random_uniform "uint32_t upper_bound"
+.Fn arc4random_uniform "uint32_t bound"
+.Ft void
+.Fn arc4random_buf "void *buf" "size_t len"
 .Ft void
 .Fn arc4random_stir "void"
 .Ft void
-.Fn arc4random_addrandom "unsigned char *dat" "int datlen"
+.Fn arc4random_addrandom "unsigned char *buf" "int len"
 .Sh DESCRIPTION
-This family of functions provides higher quality data than those
+The
-described in
+.Nm
-.Xr rand 3 ,
+family of functions provides a cryptographic pseudorandom number
+generator automatically seeded from the system entropy pool and safe to
+use from multiple threads.
+.Nm
+is designed to prevent an adversary from guessing outputs,
+unlike
+.Xr rand 3
+and
 .Xr random 3 ,
-and
+and is faster and more convenient than reading from
-.Xr rand48 3 .
+.Pa /dev/urandom
+directly.
 .Pp
-Use of these functions is encouraged for almost all random number
-consumption because the other interfaces are deficient in either
-quality, portability, standardization, or availability.
-These functions can be called in almost all coding environments,
-including
-.Xr pthreads 3
-and
-.Xr chroot 2 .
-.Pp
-High quality 32-bit pseudo-random numbers are generated very quickly.
-On each call, a cryptographic pseudo-random number generator is used
-to generate a new result.
-One data pool is used for all consumers in a process, so that consumption
-under program flow can act as additional stirring.
-The subsystem is re-seeded from the kernel random number subsystem using
-.Xr getentropy 2
-on a regular basis, and also upon
-.Xr fork 2 .
-.Pp
-The
 .Fn arc4random
-function returns a single 32-bit value.
+returns an integer in [0, 2^32) chosen independently with uniform
-.Pp
+distribution.
-The
-.Fn arc4random_buf
-function fills the region
-.Fa buf
-of length
-.Fa nbytes
-with random data.
 .Pp
 .Fn arc4random_uniform
-will return a single 32-bit value, uniformly distributed but less than
+returns an integer in [0,
-.Fa upper_bound .
+.Fa bound )
-This is recommended over constructions like
+chosen independently with uniform distribution.
-.Dq Li arc4random() % upper_bound
-as it avoids "modulo bias" when the upper bound is not a power of two.
-In the worst case, this function may consume multiple iterations
-to ensure uniformity; see the source code to understand the problem
-and solution.
 .Pp
+.Fn arc4random_buf
+stores
+.Fa len
+bytes into the memory pointed to by
+.Fa buf ,
+each byte chosen independently from [0, 256) with uniform
+distribution.
+.Pp
+.Fn arc4random_stir
+draws entropy from the operating system and incorporates it into the
+library's PRNG state to influence future outputs.
+.Pp
+.Fn arc4random_addrandom
+incorporates
+.Fa len
+bytes, which must be nonnegative, from the buffer
+.Fa buf ,
+into the library's PRNG state to influence future outputs.
+.Pp
+It is not necessary for an application to call
+.Fn arc4random_stir
+or
+.Fn arc4random_addrandom
+before calling other
+.Nm
+functions.
+The first call to any
+.Nm
+function will initialize the PRNG state unpredictably from the system
+entropy pool.
+.Sh SECURITY MODEL
 The
-.Fn arc4random_stir
+.Nm
-function reads data from
+functions provide the following security properties against three
-.Xr getentropy 2
+different classes of attackers, assuming enough entropy is provided by
-and uses it to re-seed the subsystem via
+the operating system:
-.Fn arc4random_addrandom .
+.Bl -enum -offset abcd
+.It
+An attacker who has seen some outputs of any of the
+.Nm
+functions cannot predict past or future unseen outputs.
+.It
+An attacker who has seen the library's PRNG state in memory cannot
+predict past outputs.
+.It
+An attacker who has seen one process's PRNG state cannot predict past
+or future outputs in other processes, particularly its parent or
+siblings.
+.El
+.Pp
+One
+.Sq output
+means the result of any single request to an
+.Nm
+function, no matter how short it is.
+.Pp
+The second property is sometimes called
+.Sq forward secrecy ,
+.Sq backtracking resistance ,
+or
+.Sq key erasure after each output .
+.Sh IMPLEMENTATION NOTES
+The
+.Nm
+functions are currently implemented using the ChaCha20 pseudorandom
+function family.
+For any 32-byte string
+.Fa s ,
+.Pf ChaCha20_ Fa s
+is a function from 16-byte strings to 64-byte strings.
+It is conjectured that if
+.Fa s
+is chosen with uniform distribution, then the distribution on
+.Pf ChaCha20_ Fa s
+is indistinguishable to a computationally bounded adversary from a
+uniform distribution on all functions from 16-byte strings to 64-byte
+strings.
+.Pp
+The PRNG state is a 32-byte ChaCha20 key
+.Fa s .
+Each request to
+an
+.Nm
+function
+.Bl -bullet -offset abcd -compact
+.It
+computes the 64-byte quantity
+.Fa x
+=
+.Pf ChaCha20_ Fa s Ns Pq 0 ,
+.It
+splits
+.Fa x
+into two 32-byte quantities
+.Fa s'
+and
+.Fa k ,
+.It
+replaces
+.Fa s
+by
+.Fa s' ,
+and
+.It
+uses
+.Fa k
+as output.
+.El
 .Pp
-There is no need to call
-.Fn arc4random_stir
-before using
 .Fn arc4random
-functions family, since
+yields the first four bytes of
-they automatically initialize themselves.
+.Fa k
-.Sh RETURN VALUES
+as output directly.
-These functions are always successful, and no return value is
+.Fn arc4random_buf
-reserved to indicate an error.
+either yields up to 32 bytes of
+.Fa k
+as output directly, or, for longer
+requests, uses
+.Fa k
+as a ChaCha20 key and yields the concatenation
+.Pf ChaCha20_ Fa k Ns Pq 0
+||
+.Pf ChaCha20_ Fa k Ns Pq 1
+|| ... as output.
+.Fn arc4random_uniform
+repeats
+.Fn arc4random
+until it obtains an integer in [2^32 %
+.Fa bound ,
+2^32), and reduces that modulo
+.Fa bound .
+.Pp
+The PRNG state is per-thread, unless memory allocation fails inside the
+library, in which case some threads may share global PRNG state with a
+mutex.
+The global PRNG state is zeroed on fork in the parent via
+.Xr pthread_atfork 3 ,
+and the per-thread PRNG state is zeroed on fork in the child via
+.Xr minherit 2
+with
+.Dv MAP_INHERIT_ZERO ,
+so that the child cannot reuse or see the parent's PRNG state.
+The PRNG state is reseeded automatically from the system entropy pool
+on the first use of an
+.Nm
+function after zeroing.
+.Pp
+The first use of an
+.Nm
+function may abort the process in the highly unlikely event that
+library initialization necessary to implement the security model fails.
+Additionally,
+.Fn arc4random_stir
+and
+.Fn arc4random_addrandom
+may abort the process in the highly unlikely event that the operating
+system fails to provide entropy.
 .Sh SEE ALSO
 .Xr rand 3 ,
-.Xr rand48 3 ,
+.Xr random 3 ,
-.Xr random 3
+.Xr rnd 4 ,
-.Sh HISTORY
+.Xr cprng 9
-These functions first appeared in
+.Rs
-.Ox 2.1 ,
+.%A Daniel J. Bernstein
-.Fx 3.0 ,
+.%T ChaCha, a variant of Salsa20
-.Nx 1.6 ,
+.%D 2008-01-28
-and
+.%O Document ID: 4027b5256e17b9796842e6d0f68b0b5e
-.Dx 1.0 .
+.%U http://cr.yp.to/papers.html#chacha
-The functions
+.Re
-.Fn arc4random ,
+.Sh BUGS
-.Fn arc4random_buf
+There is no way to get deterministic, reproducible results out of
-and
+.Nm
-.Fn arc4random_uniform
+for testing purposes.
-appeared in glibc 2.36.
 .Pp
-The original version of this random number generator used the
+The name
-RC4 (also known as ARC4) algorithm.
+.Sq arc4random
-In
+was chosen for hysterical raisins -- it was originally implemented
-.Ox 5.5
+using the RC4 stream cipher, which has been known since shortly after
-it was replaced with the ChaCha20 cipher, and it may be replaced
+it was published in 1994 to have observable biases in the output, and
-again in the future as cryptographic techniques advance.
+is now known to be broken badly enough to admit practical attacks in
-A good mnemonic is
+the real world.
-.Dq A Replacement Call for Random .
+.\" Bob Jenkins, sci.crypt post dated 1994-09-16, message-id
+.\" <359qjg$55v$1@mhadg.production.compuserve.com>,
+.\" https://groups.google.com/d/msg/sci.crypt/JsO3xEATGFA/-wO4ttv7BCYJ
+.\"
+.\" Andrew Roos, `A Class of Weak Keys in the RC4 Stream Cipher',
+.\" sci.crypt posts dated 1995-09-22, message-ids
+.\" <43u1eh$1j3@hermes.is.co.za> and <44ebge$llf@hermes.is.co.za>.
+.\"
+.\" Paul Crowley, `Small bias in RC4 experimentally verified', March
+.\" 1998, http://www.ciphergoth.org/crypto/rc4/
+Unfortunately, the library found widespread adoption and the name stuck
+before anyone recognized that it was silly.
+.Pp
+The signature of
+.Fn arc4random_addrandom
+is silly.
+There is no reason to require casts or accept negative lengths:
+it should take a
+.Vt void *
+buffer and a
+.Vt size_t
+length.
+But it's too late to change that now.
+.Pp
+.Fn arc4random_uniform
+does not help to choose integers in [0,
+.Fa n )
+uniformly at random when
+.Fa n
+> 2^32.
+.Pp
+The security model of
+.Nm
+is stronger than many applications need, and stronger than other
+operating systems provide.
+For example, applications encrypting messages with random, but not
+secret, initialization vectors need only prevent an adversary from
+guessing future outputs, since past outputs will have been published
+already.
+.Pp
+On the one hand,
+.Nm
+could be marginally faster if it were not necessary to prevent an
+adversary who sees the state from predicting past outputs.
+On the other hand, there are applications in the wild that use
+.Nm
+to generate key material, such as OpenSSH, so for the sake of
+.Nx
+users it would be imprudent to weaken the security model.
+On the third hand, relying on the security model of
+.Nm
+in
+.Nx
+may lead you to an unpleasant surprise on another operating system
+whose implementation of
+.Nm
+has a weaker security model.
+.Pp
+One may be tempted to create new APIs to accommodate different
+security models and performance constraints without unpleasant
+surprises on different operating systems.
+This should not be done lightly, though, because there are already too
+many different choices, and too many opportunities for programmers to
+reach for one and pick the wrong one.