Hello all,
Here's one more draft of the random(7) man page for review. I wanted to
recirculate this one more time, because I came up with couple of
questions (shown in FIXMEs below).
Ted, I'd be especially happy if you could take a look at those questions,
but I also welcome any input from others, as well as any further comments
on the remainder of the page.
Rendered version of the page is below; source is attached.
Cheers,
Michael
RANDOM(7) Linux Programmer's Manual RANDOM(7)
NAME
random - overview of interfaces for obtaining randomness
DESCRIPTION
The kernel provides the following interfaces to the kernel's
cryptographically secure pseudorandom number generator
(CSPRNG):
* The /dev/urandom and /dev/random devices, both described in
random(4). These devices have been present on Linux since
early times, and are also available on many other systems.
* The Linux-specific getrandom(2) system call, available since
Linux 3.17. This system call provides access either to the
same source as /dev/urandom (called the urandom source in
this page) or to the same source as /dev/random (called the
random source in this page). The default is the urandom
source; the random source is selected by specifying the
GRND_RANDOM flag to the system call.
Initialization of the entropy pool
The kernel collects bits of entropy from the environment. When
a sufficient number of random bits has been collected, the
entropy pool is considered to be initialized.
Choice of random device
Unless you are doing long-term key generation (and most likely
not even then), you probably shouldn't be using the /dev/random
device or getrandom(2) with the GRND_RANDOM flag.
Instead, use either the /dev/urandom device or getrandom(2)
without the GRND_RANDOM flag. The cryptographic algorithms
used for the urandom source are quite conservative, and so
should be sufficient for all purposes.
The disadvantage of GRND_RANDOM and reads from /dev/random is
that the operation can block for an indefinite period of time.
Furthermore, dealing with the partially fulfilled requests that
can occur when using GRND_RANDOM or when reading from /dev/ran‐
dom increases code complexity.
Usage recommendations
The kernel random-number generator relies on entropy gathered
from device drivers and other sources of environmental noise.
It is designed to produce a small amount of high-quality seed
material to seed a cryptographically secure pseudorandom number
generator (CSPRNG). It is designed for security, not speed,
and is poorly suited to generating large amounts of crypto‐
graphic random data. Users should be economical in the amount
of seed material that they consume via getrandom(2), /dev/uran‐
dom, and /dev/random.
┌─────────────────────────────────────────────────────┐
│FIXME │
├─────────────────────────────────────────────────────┤
│Is it really necessary to avoid consuming large │
│amounts from /dev/urandom? Various sources linked to │
│by https://bugzilla.kernel.org/show_bug.cgi?id=71211 │
│suggest it is not. │
│ │
│And: has the answer to the previous question changed │
│across kernel versions? │
└─────────────────────────────────────────────────────┘
Consuming unnecessarily large quantities of data via these
interfaces will have a negative impact on other consumers of
randomness.
┌─────────────────────────────────────────────────────┐
│FIXME │
├─────────────────────────────────────────────────────┤
│Above: we need to define "negative impact". Is the │
│only negative impact that we may slow readers of │
│/dev/random, since it will block until sufficient │
│entropy has once more accumulated? │
│ │
│And: has the answer to the previous question changed │
│across kernel versions? │
└─────────────────────────────────────────────────────┘
These interfaces should not be used to provide large quantities
of data for Monte Carlo simulations or other programs/algo‐
rithms which are doing probabilistic sampling. Indeed, such
usage will be slow, and is unnecessary, because such applica‐
tions do not need crytographically secure random numbers.
Instead, use these interfaces to provide a small amount of data
used to seed a user-space pseudorandom number generator for use
by such applications.
Comparison between getrandom, /dev/urandom, and /dev/random
The following table summarizes the behavior of the various
interfaces that can be used to obtain randomness. GRND_NON‐
BLOCK is a flag that can be used to control the blocking behav‐
ior of getrandom(2). The final column of the table considers
the case that can occur in early boot time when the entropy
pool is not yet initialized.
┌──────────────┬──────────────┬────────────────┬────────────────────┐
│Interface │ Pool │ Blocking │ Behavior when pool │
│ │ │ behavior │ is not yet ready │
├──────────────┼──────────────┼────────────────┼────────────────────┤
│/dev/random │ Blocking │ If entropy too │ Blocks until │
│ │ pool │ low, blocks │ enough entropy │
│ │ │ until there is │ gathered │
│ │ │ enough entropy │ │
│ │ │ again │ │
├──────────────┼──────────────┼────────────────┼────────────────────┤
│/dev/urandom │ CSPRNG out‐ │ Never blocks │ Returns output │
│ │ put │ │ from uninitialized │
│ │ │ │ CSPRNG (may be low │
│ │ │ │ entropy and │
│ │ │ │ unsuitable for │
│ │ │ │ cryptography) │
├──────────────┼──────────────┼────────────────┼────────────────────┤
│getrandom() │ Same as │ Does not block │ Blocks until pool │
│ │ /dev/urandom │ once is pool │ ready │
│ │ │ ready │ │
├──────────────┼──────────────┼────────────────┼────────────────────┤
│getrandom() │ Same as │ If entropy too │ Blocks until pool │
│GRND_RANDOM │ /dev/random │ low, blocks │ ready │
│ │ │ until there is │ │
│ │ │ enough entropy │ │
│ │ │ again │ │
├──────────────┼──────────────┼────────────────┼────────────────────┤
│getrandom() │ Same as │ Does not block │ EAGAIN │
│GRND_NONBLOCK │ /dev/urandom │ once is pool │ │
│ │ │ ready │ │
├──────────────┼──────────────┼────────────────┼────────────────────┤
│getrandom() │ Same as │ EAGAIN if not │ EAGAIN │
│GRND_RANDOM + │ /dev/random │ enough entropy │ │
│GRND_NONBLOCK │ │ available │ │
└──────────────┴──────────────┴────────────────┴────────────────────┘
Generating cryptographic keys
The amount of seed material required to generate a crypto‐
graphic key equals the effective key size of the key. For
example, a 3072-bit RSA or Diffie-Hellman private key has an
effective key size of 128 bits (it requires about 2^128 opera‐
tions to break) so a key generator needs only 128 bits (16
bytes) of seed material from /dev/random.
While some safety margin above that minimum is reasonable, as a
guard against flaws in the CSPRNG algorithm, no cryptographic
primitive available today can hope to promise more than 256
bits of security, so if any program reads more than 256 bits
(32 bytes) from the kernel random pool per invocation, or per
reasonable reseed interval (not less than one minute), that
should be taken as a sign that its cryptography is not skill‐
fully implemented.
SEE ALSO
getrandom(2), random(4), urandom(4), signal(7)
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
Attachment:
random.7
Description: Unix manual page
