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.