Add a section on different types of randomness, what the library

functions we provide are good for and how /dev/random fits into
this picture.

   Reviewed by:    markm

1 files changed, 121 insertions, 0 deletions

diff --git a/share/man/man4/random.4 b/share/man/man4/random.4
index 66132c4..9a216c3 100644
--- a/share/man/man4/random.4
+++ b/share/man/man4/random.4
@@ -156,11 +156,132 @@ Internal
 .Xr sysctl 3
 handlers force the above variables
 into the stated ranges.
+.Sh RANDOMNESS
+The use of randomness in the field of computing
+is a rather subtle issue because randomness means
+different things to different people.
+Consider generating a password randomly,
+simulating a coin tossing experiment or
+choosing a random back-off period when a server does not respond.
+Each of these tasks requires random numbers,
+but the random numbers in each case have different requirements.
+.Pp
+Generation of passwords, session keys and the like
+requires cryptographic randomness.
+A cryptographic random number generator should be designed
+so that its output is difficult to guess,
+even if a lot of auxiliary information is known
+(such as when it was seeded, subsequent or previous output, ...).
+On
+.Fx ,
+seeding for cryptographic random number generators is provided by the
+.Nm
+device,
+which provides real randomness.
+The
+.Xr arc4random 3
+library call provides a pseudo-random sequence
+which is generally reckoned to be suitable for
+simple cryptographic use.
+The OpenSSL library also provides functions for managing randomness.
+.Pp
+Randomness for simulation is required in engineering or
+scientific software and games.
+The first requirement of these applications is
+that the random numbers produced conform to some well-known,
+usually uniform, distribution.
+The sequence of numbers should also appear numerically uncorrelated,
+as simulation often assumes independence of its random inputs.
+Often it is desirable to reproduce
+the results of a simulation exactly,
+so that if the generator is seeded in the same way
+it should produce the same results.
+A peripheral concern for simulation is
+the speed of a random number generator.
+.Pp
+Another issue in simulation is
+the size of the state associated with the random number generator and
+how frequently it repeats itself.
+For example,
+a program which shuffles a pack of cards should have 52! possible outputs,
+which requires the random number generator to have 52! starting states.
+This means the seed should have at least log_2(52!) ~ 226 bits of state
+if the program is to stand a chance of outputting all possible sequences,
+and the program needs some unbiased way of generating these these bits.
+Again,
+the
+.Nm
+device could be used for seeding here,
+but in practice smaller seeds are usually considered acceptable.
+.Pp
+.Fx
+provides two families of functions which are considered
+suitable for simulation. The
+.Xr random 3
+family of functions provides a random integer
+between 0 to
+.if t 2\u\s731\s10\d\(mi1.
+.if n (2**31)\(mi1.
+The functions
+.Xr srandom 3 ,
+.Xr initstate 3
+and
+.Xr setstate 3
+are provided for deterministically setting
+the state of the generator and
+the function
+.Xr srandomdev 3
+is provided for setting the state the
+.Nm
+device.
+The
+.Xr drand48 3
+family of functions are also provided,
+which provide random floating point numbers in various ranges.
+.Pp
+Randomness as used for collision avoidance,
+for example in certain network protocols,
+has slightly different semantics again.
+It is usually expected that the numbers will be uniform,
+as this produces the lowest chances of collision.
+Here again,
+the seeding of the generator is very important,
+as it is required that different instances of
+the generator produce independent sequences.
+However, the guessability or reproducibility of the sequence is unimportant,
+unlike the previous cases.
+.Pp
+One final consideration for the seeding of random number generators
+is a bootstrapping problem.
+In some cases it may be difficult to find enough randomness to
+seed a random number generator until a system is fully operational,
+but the system requires random numbers to become fully operational.
+There is no substitute for careful thought here,
+but the
+.Fx
+.Nm
+device,
+which is based on the Yarrow system,
+should be of some help in this area.
+.Pp
+.Fx
+does also provide the traditional
+.Xr rand 3
+library call,
+for compatibility purposes.
+However,
+it is known to be poor for simulation and
+absolutely unsuitable for cryptographic purposes,
+so its use is discouraged.
 .Sh FILES
 .Bl -tag -width /dev/random
 .It Pa /dev/random
 .El
 .Sh SEE ALSO
+.Xr arc4random 3 ,
+.Xr drand48 3 ,
+.Xr rand 3 ,
+.Xr random 3 ,
 .Xr sysctl 8
 .Sh HISTORY
 A