From 2c38619b524c7d3ada336fc2aa3afcbb7dbff0f5 Mon Sep 17 00:00:00 2001
From: Poul-Henning Kamp <phk@FreeBSD.org>
Date: Fri, 11 Oct 2002 13:13:08 +0000
Subject: Slight overhaul of arc4random() and friends.

One bug fixed:  Use getmicrouptime() to trigger reseeds so that we
cannot be tricked by a clock being stepped backwards.

Express parameters in natural units and with natural names.

Don't use struct timeval more than we need to.

Various stylistic and readability polishing.

Introduce arc4rand(void *ptr, u_int len, int reseed) function which
returns a stream of pseudo-random bytes, observing the automatic
reseed criteria as well as allowing forced reseeds.

Rewrite arc4random() in terms of arc4rand().

Sponsored by:   DARPA & NAI Labs.
---
 share/man/man9/random.9 | 30 ++++++++++++++++++++++++------
 1 file changed, 24 insertions(+), 6 deletions(-)

(limited to 'share')

diff --git a/share/man/man9/random.9 b/share/man/man9/random.9
index 734e58336b56..98d0ffab684f 100644
--- a/share/man/man9/random.9
+++ b/share/man/man9/random.9
@@ -41,6 +41,8 @@
 .Fn srandom "u_long seed"
 .Ft u_long
 .Fn random "void"
+.Ft void
+.Fn arc4rand "void *ptr" "u_int length" "int reseed"
 .Ft u_int32_t
 .Fn arc4random "void"
 .Pp
@@ -68,12 +70,17 @@ function is entirely predictable, and is therefore not of use where
 knowledge of the sequence of numbers may be of benefit to an attacker.
 .Pp
 The
-.Fn arc4random
+.Fn arc4rand
 function will return very good quality random numbers, slightly better
 suited for security-related purposes.
 The random numbers from
-.Fn arc4random
+.Fn arc4rand
 are seeded from the entropy device if it is available.
+Automatic reseeds happen after a certain timeinterval and after a
+certain number of bytes have been delivered.
+A forced reseed can be forced by passing a non-zero value in the
+.Ar reseed
+argument.
 .Pp
 The
 .Fn read_random
@@ -90,16 +97,22 @@ is filled with no more than
 bytes. It is advised that
 .Fn read_random
 is not used; instead use
-.Fn arc4random .
+.Fn arc4rand 
 .Pp
 All the bits generated by
 .Fn random ,
-.Fn arc4random
+.Fn arc4rand
 and
 .Fn read_random
 are usable.  For example,
 .Sq Li random()&01
 will produce a random binary value.
+.Pp
+The
+.Fn arc4random
+is a convenience function which calls
+.Fn arc4rand
+to return a 32 bit pseudo-random integer.
 .Sh RETURN VALUES
 The
 .Fn random
@@ -114,10 +127,15 @@ The period of this random number generator is very large, approximately
 .if n 16*((2**31)\(mi1).
 .Pp
 The
+.Fn arc4rand
+function uses the RC4 algorithm to generate successive pseudo-random
+bytes.
+The
 .Fn arc4random
 function
-uses the RC4 algorithm to generate successive pseudo-random
-numbers in the range from 0 to
+uses 
+.Fn arc4rand
+to generate pseudo-random numbers in the range from 0 to
 .if t 2\u\s732\s10\d\(mi1.
 .if n (2**32)\(mi1.
 .Pp
-- 
cgit v1.3