X-Git-Url: https://git.saurik.com/apple/libc.git/blobdiff_plain/1f2f436a38f7ae2d39a943ad2898d8fed4ed2e58..HEAD:/gen/FreeBSD/arc4random.3

diff --git a/gen/FreeBSD/arc4random.3 b/gen/FreeBSD/arc4random.3
index 44015af..a6b7f3d 100644
--- a/gen/FreeBSD/arc4random.3
+++ b/gen/FreeBSD/arc4random.3
@@ -1,4 +1,5 @@
-.\" $OpenBSD: arc4random.3,v 1.2 1997/04/27 22:40:25 angelos Exp $
+.\" $OpenBSD: arc4random.3,v 1.34 2014/07/19 16:11:16 naddy Exp $
+.\"
 .\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
 .\" All rights reserved.
 .\"
@@ -28,100 +29,72 @@
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
 .\" Manual page, using -mandoc macros
-.\" $FreeBSD: src/lib/libc/gen/arc4random.3,v 1.18 2008/07/22 11:33:49 ache Exp $
 .\"
-.Dd April 15, 1997
+.Dd July 30, 2015
 .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
-.Sh LIBRARY
-.Lb libc
+.Nm arc4random_uniform
+.Nd random number generator
 .Sh SYNOPSIS
 .In stdlib.h
-.Ft u_int32_t
+.Ft uint32_t
 .Fn arc4random "void"
 .Ft void
 .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 "unsigned char *dat" "int datlen"
+.Ft uint32_t
+.Fn arc4random_uniform "uint32_t upper_bound"
 .Sh DESCRIPTION
-The
-.Fn arc4random
-function uses the key stream generator employed by the
-arc4 cipher, which uses 8*8 8 bit S-Boxes.
-The S-Boxes
-can be in about
-.if t 2\u\s71700\s10\d
-.if n (2**1700)
-states.
-The
-.Fn arc4random
-function returns pseudo-random numbers in the range of 0 to
-.if t 2\u\s731\s10\d\(mi1,
-.if n (2**32)\(mi1,
-and therefore has twice the range of
-.Xr rand 3
+.Pp
+These functions use a cryptographic pseudo-random number generator to generate
+high quality random bytes very quickly.  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 on a regular basis, and also upon 
+.Xr fork 2 .
+.Pp
+This family of functions provides higher quality random data than those
+described in
+.Xr rand 3 ,
+.Xr random 3 ,
 and
-.Xr random 3 .
+.Xr rand48 3 .
+They can be called in almost all environments, including
+.Xr chroot 2 ,
+and their use is encouraged over all other standard library functions for
+random numbers.
+.Pp
+.Fn arc4random
+returns a single 32-bit value.
 .Pp
 .Fn arc4random_buf
-function fills the region
+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.
-.Pp
-The
-.Fn arc4random_stir
-function reads data from
-.Pa /dev/urandom
-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
-functions family, since
-they automatically initialize themselves.
-.Sh EXAMPLES
-The following produces a drop-in replacement for the traditional
-.Fn rand
-and
-.Fn random
-functions using
-.Fn arc4random :
-.Pp
-.Dl "#define foo4random() (arc4random() % ((unsigned)RAND_MAX + 1))"
+In the worst case, this function may require multiple iterations
+to ensure uniformity.
+.Sh RETURN VALUES
+These functions are always successful, and no return value is
+reserved to indicate an error.
 .Sh SEE ALSO
 .Xr rand 3 ,
+.Xr rand48 3 ,
 .Xr random 3 ,
-.Xr srandomdev 3
+.Xr random 4
 .Sh HISTORY
-.Pa RC4
-has been designed by RSA Data Security, Inc.
-It was posted anonymously
-to the USENET and was confirmed to be equivalent by several sources who
-had access to the original cipher.
-Since
-.Pa RC4
-used to be a trade secret, the cipher is now referred to as
-.Pa ARC4 .
+The original version of this random number generator used the RC4 (also known
+as ARC4) algorithm.  In OS X 10.12 it was replaced with the NIST-approved AES
+cipher, and it may be replaced again in the future as cryptographic techniques
+advance.  A good mnemonic is
+.Dq A Replacement Call for Random .