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

FreeBSD Manual Pages

  
 
  

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

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

SYNOPSIS
     pseudo-device rnd

DESCRIPTION
     The rnd pseudo-device has three purposes.	On read, it returns crypto-
     graphically strong	random data from a generator keyed from	the kernel en-
     tropy pool.  On write, data may be	added to the entropy pool.  By ioctl,
     the behavior of the entropy pool (which sources are used; how their en-
     tropy is estimated, etc.) may be controlled.

     The kernel	uses event timing information collected	from many devices, and
     mixes this	into an	entropy	pool.  This pool is used to key	a stream gen-
     erator (the CTR_DRBG generator specified by NIST SP 800-90) which is used
     to	generate values	returned to userspace when the pseudo-device is	read.

     The pseudodevice is cloning, which	means that each	time it	is opened, a
     new instance of the stream	generator may be created.  Interposing a
     stream generator between the entropy pool and readers in this manner pro-
     tects readers from	each other (each reader's random stream	is generated
     from a unique key)	and protects all users of the entropy pool from	any
     attack which might	correlate its successive outputs to each other,	such
     as	iterative guessing attacks.

     Certain programs make very	short reads from /dev/urandom each time	they
     begin execution.  One program with	this behavior is perl(1).  If such a
     program is	run repeatedly (for example from a network service or shell
     script), the resulting repeated keying of the stream generator can
     quickly drain the entropy pool dry.  As an	optimization for such cases, a
     separate per-CPU instance of the stream generator is used to handle reads
     from /dev/urandom which are smaller than the key length of	the underlying
     cipher.  Any read of a larger size	causes an immediate allocation of a
     private instance of the stream generator for the reader.  Since all
     stream generators are automatically rekeyed upon use when sufficient en-
     tropy is available, the shared short-request generators do	still offer
     some protection against other consumers of	/dev/urandom, though less than
     is	provided for consumers making larger requests.

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

     Reading from /dev/random provides information-theoretic properties	desir-
     able for some callers: it will guarantee that the stream generator	never
     outputs more bits than the	length of its key, which may in	some sense
     mean that all the entropy provided	to it by the entropy pool is "pre-
     served" in	its output.

     Reading from /dev/random may return EAGAIN	(for non-blocking reads),
     block, or return less data	than requested,	if the pool does not have suf-
     ficient entropy to	provide	a new key for the stream generator when	suffi-
     cient bits	have been read to require rekeying.

     Reading from /dev/urandom will return as many values as requested.	 The
     stream generator may be initially keyed from the entropy pool even	if the
     pool's estimate of	its own	entropy	is less	than the number	of bits	in the
     stream generator's	key.  If this occurs, the generator will be rekeyed
     with fresh	entropy	from the pool as soon as sufficient entropy becomes
     available.	 The generator will also be rekeyed whenever the pool's	en-
     tropy estimate exceeds the	size of	the pool's internal state (when	the
     pool "is full").

     In	some sense, this data is not as	good as	reading	from /dev/random, for
     at	least two reasons.  First, the generator may initially be keyed	from a
     pool that has never had as	many bits of entropy mixed into	it as there
     are bits in the generator's key.  Second, the generator may produce many
     more bits of output than are contained in its own key, though it will
     never produce more	output on one key than is allowed by the CTR_DRBG
     specification.

     However, reading large amounts of data from a single opened instance of
     /dev/urandom will not deplete the kernel entropy pool, as it would	with
     some other	implementations.  This preserves entropy for other callers and
     will produce a more fair distribution of the available entropy over many
     potential readers on the same system.

     Users of these interfaces must carefully consider their application's ac-
     tual security requirements	and the	characteristics	of the system on which
     they are reading from the pseudodevice.  For many applications, the de-
     pletion of	the entropy pool caused	by the /dev/random pseudodevice's con-
     tinual rekeying of	the stream generator will cause	application behavior
     (or, perhaps more precisely, nonbehavior) which is	less secure than rely-
     ing on the	/dev/urandom interface,	which is guaranteed to rekey the
     stream generator as often as it can.

     Excessive use of /dev/random can deplete the entropy pool (or, at least,
     its estimate of how many bits of entropy it "contains") and reduce	secu-
     rity for other consumers of randomness both in userspace and within the
     kernel. Some system administrators	may wish therefore to remove the
     /dev/random device	node and replace it with a second copy of the node for
     the nonblocking /dev/urandom device.

     In	any event, as the Linux	manual page notes, one should be very suspi-
     cious of any application which attempts to	read more than 32 bytes	(256
     bits) from	the blocking /dev/random pseudodevice, since no	practical
     cryptographic algorithm in	current	use is believed	to have	a security
     strength greater than 256 bits.

     Writing to	either device node will	mix the	data written into the entropy
     pool, but will have no effect on the pool's entropy estimate.  The
     ioctl(2) interface	to the device may be used -- once only,	and only when
     the system	is in insecure mode at security	level 0	or lower -- to add
     data with an explicit entropy estimate.

IOCTL INTERFACE
     Various ioctl(2) functions	are available to control device	behavior,
     gather statistics,	and add	data to	the entropy pool.  These are all de-
     fined in the <sys/rnd.h> file, along with the data	types and constants.
     The structures and	ioctl functions	are also listed	below.

DATA TYPES
     Each source has a state structure which summarizes	the kernel's state for
     that entropy source.

	   typedef struct {
		   char		   name[16];
		   uint32_t	   total;
		   uint32_t	   type;
		   uint32_t	   flags;
	   } rndsource_t;
     The name field holds the device name, as known to the kernel.  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 de-
		    vice.

     RND_TYPE_RNG   The	device is a random number generator.

     RND_TYPE_SKEW  The	"device" is a measurement of the skew between two
		    clocks, such as a periodic device interrupt	and the	system
		    timecounter, a timecounter and an audio codec, or some
		    other source of pairs of events where each member of each
		    pair is derived from a different instance of some recur-
		    ring physical process.

     RND_TYPE_ENV   The	device is an environmental sensor such as a tempera-
		    ture sensor	or a fan speed sensor.

     RND_TYPE_VM    The	"device" consists of timings of	virtual	memory system
		    events.

     RND_TYPE_POWER
		    The	device is a sensor returning changes in	the power
		    state of the system, such as battery charge	state or A/C
		    adapter state.

     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.

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

     RNDGETPOOLSTAT  (rndpoolstat_t)

			   typedef struct
			   {
				   uint32_t	   poolsize;
				   uint32_t	   threshold;
				   uint32_t	   maxentropy;

				   uint32_t	   added;
				   uint32_t	   curentropy;
				   uint32_t	   removed;
				   uint32_t	   discarded;
				   uint32_t	   generated;
			   } rndpoolstat_t;

		     Return statistics on the current state of the random col-
		     lection pool.

     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_SAVEWORDS *	sizeof(uint32_t)];
			   } rnddata_t;

FILES
     /dev/random    Returns ``good'' values only
     /dev/urandom   Always returns data.

SEE ALSO
     rndctl(8),	rnd(9)

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

AUTHORS
     This implementation was written by	Thor Lancelot Simon.  It retains some
     code (particularly	for the	ioctl interface) from the earlier implementa-
     tion by Michael Graff <explorer@flame.org>.

BSD			       December	17, 2011			   BSD

NAME | SYNOPSIS | DESCRIPTION | USER ACCESS | IOCTL INTERFACE | DATA TYPES | FILES | SEE ALSO | HISTORY | AUTHORS

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

home | help