Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
RND(4)		       FreeBSD 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
     devices, 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
     using 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,
     EAGAIN is returned for non-blocking reads, or the read will block for
     blocking 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, degen-
     erating 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 tim-
     ing 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 gener-
     ated an event.  It is for internal use only, and not in any specific rep-
     resentation.  The last_delta and last_delta2 fields hold the last first-
     and second-order deltas.  The total field holds a count of how many bits
     this device 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
		    information 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
		     entropy 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 gener-
		    ator

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 written by Ted Ts'o.

FreeBSD 8.2		       October 12, 1997 		   FreeBSD 8.2

NAME | SYNOPSIS | DESCRIPTION | INTERNAL ENTROPY POOL MANAGEMENT | USER ACCESS | RANDOM SOURCE STRUCTURE | IOCTL | FILES | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=random&sektion=4&manpath=NetBSD+5.1>

home | help