home | help 
RANDOM(4)		     Kernel Interfaces Manual		       RANDOM(4)

NAME
     random -- the entropy device

SYNOPSIS
     device random

DESCRIPTION
     The  random device returns an endless supply of random bytes when read.  It
     also accepts and reads data as any ordinary (and willing)	file,  but  dis-
     cards  data  written to it.  The device will probe for certain hardware en-
     tropy sources, and use these in preference to the fallback, which is a gen-
     erator implemented in software.

     If the device is using the software generator, writing data to random would
     perturb the internal state.  This perturbation of the internal state is the
     only userland method of introducing extra entropy into the device.  If  the
     writer  has superuser privilege, then closing the device after writing will
     make the software generator reseed itself.  This can be used for extra  se-
     curity,  as  it  immediately  introduces any/all new entropy into the PRNG.
     The hardware generators will generate sufficient quantities of entropy, and
     will therefore ignore user-supplied input.  The software random device  may
     be controlled with sysctl(8).

     To  see the current settings of the software random device, use the command
     line:

	   sysctl kern.random

     which results in something like:

	   kern.random.sys.seeded: 1
	   kern.random.sys.harvest.ethernet: 1
	   kern.random.sys.harvest.point_to_point: 1
	   kern.random.sys.harvest.interrupt: 1
	   kern.random.sys.harvest.swi: 0
	   kern.random.yarrow.gengateinterval: 10
	   kern.random.yarrow.bins: 10
	   kern.random.yarrow.fastthresh: 192
	   kern.random.yarrow.slowthresh: 256
	   kern.random.yarrow.slowoverthresh: 2

     (These would not be seen if a hardware generator is present.)

     All settings are read/write.

     The kern.random.sys.seeded variable indicates whether or not the random de-
     vice is in an acceptably secure state as a result of reseeding.  If set  to
     0, the device will block (on read) until the next reseed (which can be from
     an  explicit  write,  or as a result of entropy harvesting).  A reseed will
     set the value to 1 (non-blocking).

     The kern.random.sys.harvest.ethernet variable is used to select LAN traffic
     as an entropy source.  A 0 (zero) value means that LAN traffic is not  con-
     sidered  as  an entropy source.  Set the variable to 1 (one) if you wish to
     use LAN traffic for entropy harvesting.

     The kern.random.sys.harvest.point_to_point variable is used to select  ser-
     ial  line traffic as an entropy source.  (Serial line traffic includes PPP,
     SLIP and all tun0 traffic.)  A 0 (zero) value means  such	traffic  is  not
     considered  as  an entropy source.  Set the variable to 1 (one) if you wish
     to use it for entropy harvesting.

     The kern.random.sys.harvest.interrupt variable is used to	select	hardware
     interrupts  as  an  entropy source.  A 0 (zero) value means hardware inter-
     rupts are not considered as an entropy source.  Set the variable to 1 (one)
     if you wish to use them for entropy  harvesting.	All  hardware  interrupt
     harvesting is setup by the individual device drivers.

     The  kern.random.sys.harvest.swi variable is used to select software inter-
     rupts as an entropy source.  A 0 (zero) value means software interrupts are
     not considered as an entropy source.  Set the variable to 1  (one)  if  you
     wish to use them for entropy harvesting.

     The  other variables are explained in the paper describing the Yarrow algo-
     rithm at http://www.counterpane.com/yarrow.html.

     These variables are all limited in terms of the values they may contain:
	   kern.random.yarrow.gengateinterval  [4..64]
	   kern.random.yarrow.bins	       [2..16]
	   kern.random.yarrow.fastthresh       [64..256]
	   kern.random.yarrow.slowthresh       [64..256]
	   kern.random.yarrow.slowoverthresh   [1..5]

     Internal sysctl(3) handlers force	the  above  variables  into  the  stated
     ranges.

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.

     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	informa-
     tion  is  known (such as when it was seeded, subsequent or previous output,
     and so on).  On FreeBSD, seeding for cryptographic random number generators
     is provided by the random device,	which  provides  real  randomness.   The
     arc4random(3)  library call provides a pseudo-random sequence which is gen-
     erally reckoned to be suitable for simple cryptographic use.   The  OpenSSL
     library  also provides functions for managing randomness via functions such
     as RAND_bytes(3) and RAND_add(3).	Note that OpenSSL uses the random device
     for seeding automatically.

     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  genera-
     tor.

     Another  issue  in  simulation is the size of the state associated with the
     random number generator, and how frequently it repeats itself.   For  exam-
     ple, a program which shuffles a pack of cards should have 52! possible out-
     puts,  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 se-
     quences, and the program needs some unbiased way of generating these  bits.
     Again,  the  random device could be used for seeding here, but in practice,
     smaller seeds are usually considered acceptable.

     FreeBSD provides two families of functions which  are  considered	suitable
     for  simulation.  The random(3) family of functions provides a random inte-
     ger between 0 to (2**31)-1.  The  functions  srandom(3),  initstate(3)  and
     setstate(3)  are  provided  for  deterministically setting the state of the
     generator and the function srandomdev(3) is provided for setting the  state
     via  the  random  device.	The drand48(3) family of functions are also pro-
     vided, which provide random floating point numbers in various ranges.

     Randomness that is 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 im-
     portant,  as  it is required that different instances of the generator pro-
     duce independent sequences.  However, the guessability  or  reproducibility
     of the sequence is unimportant, unlike the previous cases.

     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 opera-
     tional, but the system requires random numbers to become fully operational.
     There is no substitute for careful thought here, but the FreeBSD random de-
     vice,  which  is based on the Yarrow system, should be of some help in this
     area.

     FreeBSD does also provide the traditional rand(3) library call, for compat-
     ibility purposes.	However, it is known to be poor for simulation	and  ab-
     solutely unsuitable for cryptographic purposes, so its use is discouraged.

FILES
     /dev/random

SEE ALSO
     arc4random(3),  drand48(3), rand(3), RAND_add(3), RAND_bytes(3), random(3),
     sysctl(8)

HISTORY
     A random device appeared in FreeBSD 2.2.  The early version was taken  from
     Theodore Ts'o's entropy driver for Linux.	The current software implementa-
     tion,  introduced in FreeBSD 5.0, is a complete rewrite by Mark R V Murray,
     and is an implementation of the Yarrow algorithm by Bruce Schneier, et  al.
     The  only	hardware  implementation  currently  is  for the VIA C3 Nehemiah
     (stepping 3 or greater) CPU.  More will be added in the future.

     The author gratefully acknowledges significant assistance	from  VIA  Tech-
     nologies, Inc.

FreeBSD 6.3			  July 19, 2006 		       RANDOM(4)
home | help