Unix/Linux Go Back    


NetBSD 6.1.5 - man page for rnd (netbsd section 4)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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 cryptographically strong ran-
     dom data from a generator keyed from the kernel entropy 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 entropy 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 generator (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 protects 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 genera-
     tor 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 entropy is avail-
     able, the shared short-request generators do still offer some protection against other con-
     sumers 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 desirable for some call-
     ers: 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 "preserved" 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 sufficient entropy to provide a new key for
     the stream generator when sufficient 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 entropy 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 rea-
     sons.  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 genera-
     tor 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 pre-
     serves 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 actual security
     requirements and the characteristics of the system on which they are reading from the pseu-
     dodevice.	For many applications, the depletion of the entropy pool caused by the
     /dev/random pseudodevice's continual rekeying of the stream generator will cause application
     behavior (or, perhaps more precisely, nonbehavior) which is less secure than relying 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 security 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 suspicious of any applica-
     tion 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 defined 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 information is col-
		    lected 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.

     RND_TYPE_SKEW  The "device" is a measurement of the skew between two clocks, such as a peri-
		    odic 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 recurring physical process.

     RND_TYPE_ENV   The device is an environmental sensor such as a temperature 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 information.

     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 collection 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 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_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 implementation by Michael Graff
     <explorer@flame.org>.

BSD					December 17, 2011				      BSD
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 02:05 PM.