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

NAME
     rnd -- in kernel entropy collection and random number generation

SYNOPSIS
     pseudo-device rnd

DESCRIPTION
     The rnd pseudo-device uses event timing information collected from many de-
     vices,  and  mixes  this into an entropy pool.  This pool is stirred with a
     cryptographically strong hash function when  data	is  extracted  from  the
     pool.

INTERNAL ENTROPY POOL MANAGEMENT
     When  a  hardware event occurs (such as completion of a hard drive transfer
     or an interrupt from a network device)  a	timestamp  is  generated.   This
     timestamp	is  compared  to the previous timestamp recorded for the device,
     and the first, second, and third order differentials are calculated.

     If any of these differentials is zero, no entropy is assumed to  have  been
     gathered.	 If  all  are non-zero, one bit is assumed.  Next, data is mixed
     into the entropy pool using an LFSR (linear feedback shift register).

     To extract data from the entropy  pool,  a  cryptographically  strong  hash
     function  is used.  The output of this hash is mixed back into the pool us-
     ing the LFSR, and then folded in half before being returned to the caller.

     Mixing the actual hash into the pool causes the next extraction to return a
     different value, even if no timing events were added to the pool.	 Folding
     the data in half prevents the caller to derive the actual hash of the pool,
     preventing some attacks.

USER ACCESS
     User code can obtain random values from the kernel in two ways.

     Reading  from  /dev/random will only return values while sufficient entropy
     exists in the internal pool.  When sufficient entropy does not  exist,  EA-
     GAIN  is returned for non-blocking reads, or the read will block for block-
     ing reads.

     Reading from /dev/urandom will return as many  values  as	requested,  even
     when  the	entropy pool is empty.	This data is not as good as reading from
     /dev/random since when the pool is empty, data is still returned,	degener-
     ating to a pseudo-random generator.

     Writing  to either device will mix the data written into the pool using the
     LFSR as above, without modifying the entropy estimation for the pool.

RANDOM SOURCE STRUCTURE
     Each source has a state structure which the kernel uses to hold the  timing
     information and other state for that source.

	   typedef struct {
		   char 	   name[16];
		   uint32_t	  last_time;
		   uint32_t	  last_delta;
		   uint32_t	  last_delta2;
		   uint32_t	  total;
		   uint32_t	  type;
		   uint32_t	   flags;
	   } rndsource_t;

     This  structure  holds  the  internal  representation  of a device's timing
     state.  The name field holes the device name, as known to the kernel.   The
     last_time	entry is the timestamp of the last time this device generated an
     event.  It is for internal use only, and not in  any  specific  representa-
     tion.   The last_delta and last_delta2 fields hold the last first- and sec-
     ond-order deltas.	The total field holds a count of how many bits this  de-
     vice has potentially generated.  This is not the same as how many bits were
     used from it.  The type field holds the device type.

     Currently, these types are defined:

     RND_TYPE_DISK  The device is a physical hard drive.

     RND_TYPE_NET   The  device  is a network interface.  By default, timing in-
		    formation is collected from this source type, but entropy is
		    not estimated.

     RND_TYPE_TAPE  The device is a tape device.

     RND_TYPE_TTY   The device is a terminal, mouse, or other user input device.

     RND_TYPE_RNG   The device is a random number generator.

     flags is a bitfield.

     RND_FLAG_NO_ESTIMATE  Do not assume any entropy is in the	timing	informa-
			   tion.

     RND_FLAG_NO_COLLECT   Do not even add timing information to the pool.

IOCTL
     Various ioctl(2) functions are available to control device behavior, gather
     statistics, and add data to the entropy pool.  These are all defined in the
     <sys/rnd.h> file, along with the data types and constants.

     RNDGETENTCNT    (uint32_t) Return the current entropy count (in bits).

     RNDGETSRCNUM    (rndstat_t)

			   typedef struct {
				   uint32_t	  start;
				   uint32_t	  count;
				   rndsource_t	   source[RND_MAXSTATCOUNT];
			   } rndstat_t;

		     Return data for sources, starting at start and returning at
		     most count sources.

		     The  values  returned are actual in-kernel snapshots of the
		     entropy status for devices.  Leaking  the	internal  timing
		     information will weaken security.

     RNDGETSRCNAME   (rndstat_name_t)

			   typedef struct {
				   char 	   name[16];
				   rndsource_t	   source;
			   } rndstat_name_t;

		     Return the device state for a named device.

     RNDCTL	     (rndctl_t)

			   typedef struct {
				   char 	   name[16];
				   uint32_t	  type;
				   uint32_t	  flags;
				   uint32_t	  mask;
			   } rndctl_t;

		     Change  bits  in  the device state information.  If type is
		     0xff, only the device name stored in name is used.   If  it
		     is  any  other value, all devices of type type are altered.
		     This allows all network interfaces to be disabled	for  en-
		     tropy collection with one call, for example.  The flags and
		     mask  work  together  to  change flag bits.  The mask field
		     specifies which bits in flags are to be set or cleared.

     RNDADDDATA      (rnddata_t)

			   typedef struct {
				   uint32_t	  len;
				   uint32_t	  entropy;
				   u_char	   data[RND_POOLWORDS * 4];
			   } rnddata_t;

FILES
     /dev/random    Returns ``good'' values only
     /dev/urandom   Always returns data, degenerates to a pseudo-random  genera-
		    tor

SEE ALSO
     rndctl(8), rnd(9)

HISTORY
     The random device was first made available in NetBSD 1.3.

AUTHORS
     This implementation was written by Michael Graff <explorer@flame.org> using
     ideas and algorithms gathered from many sources, including the driver writ-
     ten by Ted Ts'o.

NetBSD 5.1			October 12, 1997			  RND(4)

home | help