1 files changed, 83 insertions, 27 deletions

diff --git a/src/lib/libc/stdlib/rand48.3 b/src/lib/libc/stdlib/rand48.3
index a4473185de..dce8c0dd18 100644
--- a/src/lib/libc/stdlib/rand48.3
+++ b/src/lib/libc/stdlib/rand48.3
@@ -9,9 +9,9 @@
 .\" of any kind. I shall in no event be liable for anything that happens
 .\" to anyone/anything when using this software.
 .\"
-.\"     $OpenBSD: rand48.3,v 1.16 2014/11/25 17:26:34 millert Exp $
+.\"     $OpenBSD: rand48.3,v 1.17 2014/12/08 21:45:20 deraadt Exp $
 .\"
-.Dd $Mdocdate: November 25 2014 $
+.Dd $Mdocdate: December 8 2014 $
 .Dt RAND48 3
 .Os
 .Sh NAME
@@ -22,8 +22,11 @@
 .Nm mrand48 ,
 .Nm jrand48 ,
 .Nm srand48 ,
+.Nm srand48_deterministic ,
 .Nm seed48 ,
+.Nm seed48_deterministic ,
 .Nm lcong48
+.Nm lcong48_deterministic
 .Nd pseudo-random number generators and initialization routines
 .Sh SYNOPSIS
 .In stdlib.h
@@ -41,31 +44,56 @@
 .Fn jrand48 "unsigned short xseed[3]"
 .Ft void
 .Fn srand48 "long seed"
+.Ft void
+.Fn srand48_deterministic "long seed"
 .Ft "unsigned short *"
 .Fn seed48 "unsigned short xseed[3]"
+.Ft "unsigned short *"
+.Fn seed48_deterministic "unsigned short xseed[3]"
 .Ft void
 .Fn lcong48 "unsigned short p[7]"
+.Ft void
+.Fn lcong48_deterministic "unsigned short p[7]"
 .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 rand48
-family of functions generates pseudo-random numbers using a linear
-congruential algorithm working on integers 48 bits in size.
-The particular formula employed is
-r(n+1) = (a * r(n) + c) mod m
-where the default values are
-for the multiplicand a = 0xfdeece66d = 25214903917 and
-the addend c = 0xb = 11.
-The modulus is always fixed at m = 2 ** 48.
-r(n) is called the seed of the random number generator.
+To satisfy portable code,
+.Fn srand48 ,
+.Fn seed48 ,
+or
+.Fn lcong48
+should be called to initialize the subsystem.
+In
+.Ox
+the
+seeding parameters are ignored, and strong random number results will be
+provided from
+.Xr arc4random 3.
+In other systems, the
+parameters prime a simplistic deterministic algorithm.
 .Pp
-For all the six generator routines described next, the first
-computational step is to perform a single iteration of the algorithm.
+If the standardized behavior is required then
+.Fn srand48_deterministic ,
+.Fn seed48_deterministic ,
+and
+.Fn lcong48_deterministic
+can be substituted for
+.Fn srand48 ,
+.Fn seed48 ,
+and
+.Fn lcong48 .
+That will cause subsequent
+calls to
+.Fn drand48 ,
+.Fn lrand48 ,
+and
+.Fn jrand48
+to return results using the deterministic algorithm.
 .Pp
 .Fn drand48
 and
@@ -91,6 +119,21 @@ return values of type long in the range
 [-2**31, 2**31-1].
 The high-order (32) bits of r(n+1) are loaded into the returned value.
 .Pp
+In the deterministic mode, the
+.Fn rand48
+family of functions generates numbers using a linear congruential
+algorithm working on integers 48 bits in size.
+The particular formula employed is
+r(n+1) = (a * r(n) + c) mod m
+where the default values are
+for the multiplicand a = 0xfdeece66d = 25214903917 and
+the addend c = 0xb = 11.
+The modulus is always fixed at m = 2 ** 48.
+r(n) is called the seed of the random number generator.
+.Pp
+For all the six generator routines described next, the first
+computational step is to perform a single iteration of the algorithm.
+.Pp
 .Fn drand48 ,
 .Fn lrand48 ,
 and
@@ -110,7 +153,7 @@ holds the least significant bits.
 .Pp
 All functions share the same multiplicand and addend.
 .Pp
-.Fn srand48
+.Fn srand48_deterministic
 is used to initialize the internal buffer r(n) of
 .Fn drand48 ,
 .Fn lrand48 ,
@@ -121,7 +164,7 @@ of r(n), with the lower 16 bits of r(n) arbitrarily being set to 0x330e.
 Additionally, the constant multiplicand and addend of the algorithm are
 reset to the default values given above.
 .Pp
-.Fn seed48
+.Fn seed48_deterministic
 also initializes the internal buffer r(n) of
 .Fn drand48 ,
 .Fn lrand48 ,
@@ -131,14 +174,14 @@ but here all 48 bits of the seed can be specified in an array of 3 shorts,
 where the zeroth member specifies the lowest bits.
 Again, the constant multiplicand and addend of the algorithm are
 reset to the default values given above.
-.Fn seed48
+.Fn seed48_deterministic
 returns a pointer to an array of 3 shorts which contains the old seed.
 This array is statically allocated, so its contents are lost after
 each new call to
-.Fn seed48 .
+.Fn seed48_deterministic .
 .Pp
 Finally,
-.Fn lcong48
+.Fn lcong48_deterministic
 allows full control over the multiplicand and addend used in
 .Fn drand48 ,
 .Fn erand48 ,
@@ -169,14 +212,27 @@ The
 .Fn drand48 ,
 .Fn erand48 ,
 .Fn jrand48 ,
-.Fn lcong48 ,
 .Fn lrand48 ,
 .Fn mrand48 ,
-.Fn nrand48 ,
-.Fn seed48 ,
 and
-.Fn srand48
+.Fn nrand48 ,
 functions conform to
 .St -p1003.1-2008 .
+.Pp
+The
+.Fn seed48 ,
+.Fn srand48 ,
+and
+.Fn lcong48
+function do not conform to
+.St -ansiC ,
+intentionally.
+.Pp
+The
+.Fn seed48_deterministic ,
+.Fn srand48_deterministic ,
+and
+.Fn lcong48_deterministic
+functions are OpenBSD extensions.
 .Sh AUTHORS
 .An Martin Birgmeier