random(7)

NAME

random, urandom, rng — strong random number generator

SYNOPSIS

#include <sys/random.h>

DESCRIPTION

The character special files /dev/random and /dev/urandom provide an interface to the kernel-resident random number generator, rng. A read() from /dev/random is potentially blocking. A read() from /dev/urandom is always nonblocking. Data from /dev/urandom can potentially have lower entropy than data from /dev/random.

The rng module is a dynamically loadable kernel module (DLKM). That is, it can be dynamically unconfigured or reconfigured by an administrator with root authority without rebooting the system.

A sequence from rng has unlimited entropy. In contrast, a sequence generated computationally by a pseudorandom number generator, such as random(3M), has limited entropy, derived only from its initial seed. The rng module should be considered a quality source for randomness. It has passed extensive statistical testing, including the NIST (National Institute of Standards and Technology) tests for randomness.

The rng module uses the uncertainty in completion times of interrupt threads triggered by external events. The rng module extracts a sequence of bits from the interrupt time stamps. Any existing bit bias is removed to yield a sequence with uniform distribution of 0's and 1's. The resulting sequence is divided between the holding buffers for the special files /dev/random and /dev/urandom. For each read() on /dev/random and /dev/urandom, data is retrieved from the corresponding holding buffer. A hash function based on AES (Advanced Encryption Standard) is applied and the result is placed in the buffer provided by the user. All requests on the holding buffers are serialized to ensure that returned random data is not shared between different requests even for simultaneous requests on a multiprocessor system.

There is no write() function associated with either /dev/random or /dev/urandom, and both devices are read-only by all users. A single ioctl() is defined for /dev/random to facilitate independent verification of rng production.

The file /usr/include/sys/random.h contains the following definitions:

/* The maximum request size, for read() or ioctl(), in bytes   */
#define RNG_READMAX    256

/* ioctl() to retrieve data from the entropy collector directly*/
#define RNG_GETRAW     _IOR('Q', 0, uint8_t[RNG_READMAX])

If a read() request is for more than RNG_READMAX bytes, it is treated as if it was for exactly RNG_READMAX bytes. This holds for both /dev/random and /dev/urandom.

Specific Information About /dev/random

When there are a large number of requests on /dev/random within a short time interval, the demand on the holding buffer can exceed the rate at which data is supplied by rng. A read() on the /dev/random device blocks the requesting thread if the random data stored in the holding buffer is too low to complete the request. The thread blocks until the holding buffer has been updated with enough random data to complete the request.

For /dev/random open() flags, only O_NONBLOCK and O_NDELAY have device-specific actions. If neither of these flags is set, a read() on /dev/random will block until the amount of data requested, up to RNG_READMAX bytes, can be returned. When the requested number of bytes is not available and either of the above flags are set, read() returns immediately. If the O_NONBLOCK flag is set, read() returns -1 and errno is set to EAGAIN. If O_NONBLOCK is not set and O_NDELAY is set, read() returns zero.

The RNG_GETRAW ioctl() permits an application with superuser privilege to fetch RNG_READMAX bytes of data directly from the /dev/random holding buffer, after bias has been removed but before the AES hash. This interface is not intended to be used for cryptographic applications, rather, for statistical testing of the randomness of the data in the /dev/random holding buffer. This RNG_GETRAW ioctl() blocks for the same reason as a read on /dev/random. If the requesting thread does not have superuser authority, EACCES is returned.

Specific Information About /dev/urandom

To address the limited random data collection rate problem, the /dev/urandom device is strictly nonblocking. The /dev/urandom holding buffer is regularly updated with random data, yet a high number of reads can decrease the entropy in its holding buffer. Under this conditions, the entropy of the data from /dev/urandom will be slightly lower that the one from /dev/random, yet /dev/urandom can still be considered a good source of random numbers.

There are no open() flags that result in device-specific actions with /dev/urandom read().

ERRORS

EAGAIN: For /dev/random read(), O_NONBLOCK was set when /dev/random was opened, and there is insufficient content in the holding buffer to complete the request.
EACCES: For the /dev/random RNG_GETRAW ioctl(), the requesting thread did not have superuser authority.

AUTHOR

The random number generator was developed by HP.

For bias removal, the generator uses an algorithm by Dr. Yuval Perez, University of California.

The secure hashing uses an AES implementation provided by Dr. Brian Gladman, UK.

The NIST statistical tests are available at http://csrc.nist.gov/rng.

FILES

/dev/random

/dev/urandom

random(7)

Technical documentation

» Table of Contents

» Index