update documentation for these functions. They now state the case regarding

pthreads and chroot, and safe initialization without /dev/random and such
junk.  If you are in control of an arc4random in another library, please look
at these pages and get caught up.
ok various

2 files changed, 67 insertions, 70 deletions

diff --git a/lib/libc/crypt/arc4random.3 b/lib/libc/crypt/arc4random.3
index 3cc26bbf185..c74c9cc1219 100644
--- a/lib/libc/crypt/arc4random.3
+++ b/lib/libc/crypt/arc4random.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: arc4random.3,v 1.29 2013/06/05 03:39:22 tedu Exp $
+.\" $OpenBSD: arc4random.3,v 1.30 2013/10/21 20:35:09 deraadt Exp $
 .\"
 .\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
 .\" All rights reserved.
@@ -30,16 +30,14 @@
 .\"
 .\" Manual page, using -mandoc macros
 .\"
-.Dd $Mdocdate: June 5 2013 $
+.Dd $Mdocdate: October 21 2013 $
 .Dt ARC4RANDOM 3
 .Os
 .Sh NAME
 .Nm arc4random ,
 .Nm arc4random_buf ,
-.Nm arc4random_uniform ,
-.Nm arc4random_stir ,
-.Nm arc4random_addrandom
-.Nd arc4 random number generator
+.Nm arc4random_uniform
+.Nd random number generator
 .Sh SYNOPSIS
 .In stdlib.h
 .Ft u_int32_t
@@ -48,65 +46,54 @@
 .Fn arc4random_buf "void *buf" "size_t nbytes"
 .Ft u_int32_t
 .Fn arc4random_uniform "u_int32_t upper_bound"
-.Ft void
-.Fn arc4random_stir "void"
-.Ft void
-.Fn arc4random_addrandom "u_char *dat" "int datlen"
 .Sh DESCRIPTION
-The
-.Fn arc4random
-function provides a high quality 32-bit pseudo-random
-number very quickly.
-.Fn arc4random
-seeds itself on a regular basis from the kernel strong random number
-subsystem described in
-.Xr random 4 .
-On each call, an ARC4 generator is used to generate a new result.
-The
-.Fn arc4random
-function uses the ARC4 cipher key stream generator,
-which uses 8*8 8-bit S-Boxes.
-The S-Boxes can be in about (2**1700) states.
-.Pp
-.Fn arc4random
-provides a cryptographically secure pseudo-random number generator,
-as opposed to the fast but poor quality interfaces described in
+This family of functions provides higher quality data than those
+described in
 .Xr rand 3 ,
 .Xr random 3 ,
 and
 .Xr drand48 3 .
 .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 sysctl 3
+on a regular basis, and also upon
+.Xr fork 2 .
+.Pp
+The
+.Fn arc4random
+function returns a single 32-bit value.
+.Pp
 .Fn arc4random_buf
 fills the region
 .Fa buf
 of length
 .Fa nbytes
-with ARC4-derived random data.
+with random data.
 .Pp
 .Fn arc4random_uniform
-will return a uniformly distributed random number less than
+will return a single 32-bit value, uniformly distributed but less than
 .Fa upper_bound .
-.Fn arc4random_uniform
-is recommended over constructions like
+This is recommended over constructions like
 .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
-The
-.Fn arc4random_stir
-function reads data using
-.Xr sysctl 3
-from
-.Va kern.arandom
-and uses it to permute the S-Boxes via
-.Fn arc4random_addrandom .
-.Pp
-There is no need to call
-.Fn arc4random_stir
-before using
-.Fn arc4random ,
-since
-.Fn arc4random
-automatically initializes itself.
 .Sh RETURN VALUES
 These functions are always successful, and no return value is
 reserved to indicate an error.
@@ -115,21 +102,16 @@ reserved to indicate an error.
 .Xr rand48 3 ,
 .Xr random 3
 .Sh HISTORY
-An algorithm called
-.Pa RC4
-was designed by RSA Data Security, Inc.
-It was considered a trade secret.
-Because it was a trade secret, it obviously could not be patented.
-A clone of this was posted anonymously to USENET and confirmed to
-be equivalent by several sources who had access to the original cipher.
-Because of the trade secret situation, RSA Data Security, Inc. could
-do nothing about the release of the
-.Ql Alleged RC4
-algorithm.
-Since
-.Pa RC4
-was trademarked, the cipher is now referred to as
-.Pa ARC4 .
 .Pp
 These functions first appeared in
 .Ox 2.1 .
+.Pp
+The original version of this random number generator used the
+RC4 (also known as ARC4) algorithm.
+In
+.Ox 5.5 ,
+it was replaced with the ChaCha20 cipher, and it may be replaced
+again in the future as cryptographic techniques advance.
+techniques advance.
+A good mnemonic is
+.Dq A Replacement Call for Random .
diff --git a/share/man/man9/arc4random.9 b/share/man/man9/arc4random.9
index 4c276435f35..98fc8f61368 100644
--- a/share/man/man9/arc4random.9
+++ b/share/man/man9/arc4random.9
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: arc4random.9,v 1.6 2013/06/04 19:27:03 schwarze Exp $
+.\"	$OpenBSD: arc4random.9,v 1.7 2013/10/21 20:35:09 deraadt Exp $
 .\"
 .\" Copyright (c) 1996,2000 Michael Shalayeff
 .\" All rights reserved.
@@ -23,7 +23,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 4 2013 $
+.Dd $Mdocdate: October 21 2013 $
 .Dt ARC4RANDOM 9
 .Os
 .Sh NAME
@@ -53,6 +53,13 @@
 .Fn arc4random_uniform "u_int32_t upper_bound"
 .Sh DESCRIPTION
 The
+.Fn add_random
+functions below insert random input into a confusing mesh of
+hash functions to create a pool to be used by the
+.Pa arc4random
+series of functions.
+.Pp
+The
 .Fn add_mouse_randomness ,
 .Fn add_tty_randomness ,
 .Fn add_net_randomness ,
@@ -61,9 +68,8 @@ and
 .Fn add_audio_randomness
 routines are used to
 supply data for the random data source device for further processing.
-The processing involves calculating inter-event timedelta and measuring
-entropy contained in the resulting delta-T; the argument data supplied
-is just mixed into the pool and does not increase the entropy counter.
+The processing involves calculating inter-event timedelta and inserting
+it into a pool which is cryptographically mixed multiple times.
 .Pp
 .Fn add_true_randomness
 does not involve the usual timing calculations,
@@ -78,13 +84,22 @@ mostly by means of timing the random driver's operations.
 .Fn arc4random
 and
 .Fn arc4random_buf
-provide random numbers.
-They may be called safely in any kernel context.
+provide random numbers and are intended to be called in any
+circumstance where random numbers are required.
 .Pp
 .Fn arc4random_uniform
 will return a uniformly distributed random number less than
 .Fa upper_bound ,
 avoiding "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 ,
+.Fn arc4random_buf ,
+and
+.Fn arc4random_uniform
+may be called in nearly any kernel context.
 .Sh SEE ALSO
 .Xr arc4random 3 ,
 .Xr pchb 4 ,