rnd(4) - NetBSD Manual Pages

Command: Section: Arch: Collection:  
RND(4)                  NetBSD 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 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 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 entropy 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 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 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 actual security requirements and the characteristics of the system on which they are reading from the pseudodevice. 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 behav- ior (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 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 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 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. 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 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 implementa- tion by Michael Graff <explorer@flame.org>. NetBSD 6.0 December 17, 2011 NetBSD 6.0
Powered by man-cgi (2024-03-20). Maintained for NetBSD by Kimmo Suominen. Based on man-cgi by Panagiotis Christias.