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

1 files changed, 45 insertions, 63 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 .