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

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias <christia@softlab.ntua.gr>
©1996-2014 Modified for NetBSD by Kimmo Suominen