1 files changed, 56 insertions, 54 deletions

diff --git a/src/lib/libc/stdlib/random.3 b/src/lib/libc/stdlib/random.3
index b3bc560ad3..ad92b60387 100644
--- a/src/lib/libc/stdlib/random.3
+++ b/src/lib/libc/stdlib/random.3
@@ -25,14 +25,15 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"     $OpenBSD: random.3,v 1.26 2014/11/25 17:40:38 millert Exp $
+.\"     $OpenBSD: random.3,v 1.27 2014/12/08 21:45:20 deraadt Exp $
 .\"
-.Dd $Mdocdate: November 25 2014 $
+.Dd $Mdocdate: December 8 2014 $
 .Dt RANDOM 3
 .Os
 .Sh NAME
 .Nm random ,
 .Nm srandom ,
+.Nm srandom_deterministic ,
 .Nm srandomdev ,
 .Nm initstate ,
 .Nm setstate
@@ -44,6 +45,8 @@
 .Ft void
 .Fn srandom "unsigned int seed"
 .Ft void
+.Fn srandom_deterministic "unsigned int seed"
+.Ft void
 .Fn srandomdev void
 .Ft char *
 .Fn initstate "unsigned int seed" "char *state" "size_t n"
@@ -51,58 +54,48 @@
 .Fn setstate "char *state"
 .Sh DESCRIPTION
 .Bf -symbolic
-This interface is not cryptographically secure, so consider using
-.Xr arc4random 3
-instead.
+Standards insist that this interface return deterministic results.
+Unsafe usage is very common, so
+.Ox
+changed the subsystem to return non-deterministic results by default.
 .Ef
 .Pp
-The
-.Fn random
-function uses a non-linear additive feedback random number generator employing
-a default table of size 31 long integers to return successive pseudo-random
-numbers in the range from 0 to (2**31)\-1.
-The period of this random number generator is very large, approximately
-16*((2**31)\-1).
-.Pp
-The
-.Fn random
-and
+To satisfy portable code,
 .Fn srandom
-functions have (almost) the same calling sequence and initialization
-properties as
-.Xr rand 3 Ns / Ns Xr srand 3 .
-The difference is that
-.Xr rand
-produces a much less random sequence \(em in fact, the low dozen bits
-generated by rand go through a cyclic pattern.
-All the bits generated by
+or
+.Fn srandomdev
+may be called to initialize the subsystem.
+In
+.Ox
+the
+.Ar seed
+variable is ignored, and strong random number results will be provided from
+.Xr arc4random 3.
+In other systems, the
+.Ar seed
+variable primes a simplistic deterministic algorithm.
+.Pp
+If the standardized behavior is required
+.Fn srandom_deterministic
+can be substituted for
+.Fn srandom ,
+then subsequent
 .Fn random
-are usable.
-For example,
-.Sq Li random()&01
-will produce a random binary
-value.
+calls will return results using the deterministic algorithm.
 .Pp
-Like
-.Xr rand 3 ,
+In non-deterministic (default) mode, the
 .Fn random
-will by default produce a sequence of numbers that can be duplicated
-by calling
-.Fn srandom
-with
-.Ql 1
-as the seed.
+function returns results from
+.Xr arc4random 3
+in the range from 0 to (2**31)\-1.
 .Pp
-The
-.Fn srandomdev
-routine switches to an algorithm using state derived from
-random numbers obtained from the kernel.
-Note that this particular seeding procedure can generate
-states which are impossible to reproduce by calling
-.Fn srandom
-with any value, since the succeeding terms in the
-state buffer are no longer derived from the LC algorithm applied to
-a fixed seed.
+In deterministic mode, the
+.Fn random
+function uses a non-linear additive feedback random number generator employing
+a default table of size 31 long integers to return successive pseudo-random
+numbers in the range from 0 to (2**31)\-1.
+The period of this random number generator is very large, approximately
+16*((2**31)\-1), but the results are a deterministic sequence from the seed.
 .Pp
 The
 .Fn initstate
@@ -151,9 +144,12 @@ and
 is that the size of the state array does not have to be remembered after
 it is initialized.
 .Pp
-With 256 bytes of state information, the period of the random number
-generator is greater than 2**69
-which should be sufficient for most purposes.
+Use of
+.Fn srandom_deterministic ,
+.Fn initstate ,
+or
+.Fn setstate
+forces the subsystem into deterministic mode.
 .Sh DIAGNOSTICS
 If
 .Fn initstate
@@ -169,7 +165,6 @@ messages are printed on the standard error output.
 .Sh STANDARDS
 The
 .Fn random ,
-.Fn srandom ,
 .Fn initstate ,
 and
 .Fn setstate
@@ -177,14 +172,21 @@ functions conform to
 .St -xpg4.2 .
 .Pp
 The
+.Fn srandom
+function does not conform to
+.St -xpg4.2 ,
+intentionally.
+.Pp
+The
 .Fn srandomdev
 function is an extension.
+.Pp
+The
+.Fn srandom_deterministic
+function is an OpenBSD extension.
 .Sh HISTORY
 These
 functions appeared in
 .Bx 4.2 .
 .Sh AUTHORS
 .An Earl T. Cohen
-.Sh BUGS
-The historical implementation used to have very weak seeding.
-As a result, the random sequence did not vary much with the seed.