.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
-.TH RANDOM 7 2016-11-11 "Linux" "Linux Programmer's Manual"
+.\" The following web page is quite informative:
+.\" http://www.2uo.de/myths-about-urandom/
+.\"
+.TH RANDOM 7 2017-03-13 "Linux" "Linux Programmer's Manual"
.SH NAME
random \- overview of interfaces for obtaining randomness
.SH DESCRIPTION
-The kernel provides the following interfaces to the kernel's
-cryptographically secure pseudorandom number generator (CSPRNG):
+The kernel random-number generator relies on entropy gathered from
+device drivers and other sources of environmental noise to seed
+a cryptographically secure pseudorandom number generator (CSPRNG).
+It is designed for security, rather than speed.
+.PP
+The following interfaces provide access to output from the kernel CSPRNG:
.IP * 3
The
.I /dev/urandom
.I /dev/random
devices, both described in
.BR random (4).
-These devices have been present on Linux since early times.
+These devices have been present on Linux since early times,
+and are also available on many other systems.
.IP *
-The
+The Linux-specific
.BR getrandom (2)
system call, available since Linux 3.17.
This system call provides access either to the same source as
source in this page).
The default is the
.I urandom
-source; the
+source; the
.I random
source is selected by specifying the
.BR GRND_RANDOM
flag to the system call.
+(The
+.BR getentropy (3)
+function provides a slightly more portable interface on top of
+.BR getrandom (2).)
.\"
.SS 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
-.I urandom
entropy pool is considered to be initialized.
-.SS Choice of random device
+.SS Choice of random source
Unless you are doing long-term key generation (and most likely not even
-then), you probably shouldn't be using
+then), you probably shouldn't be reading from the
+.IR /dev/random
+device or employing
.BR getrandom (2)
with the
.BR GRND_RANDOM
-flag or the
-.IR /dev/random
-device.
-
-Instead, use either
+flag.
+Instead, either read from the
+.IR /dev/urandom
+device or employ
.BR getrandom (2)
without the
.B GRND_RANDOM
-flag or the
-.IR /dev/urandom
-device.
+flag.
The cryptographic algorithms used for the
.IR urandom
source are quite conservative, and so should be sufficient for all purposes.
-
+.PP
The disadvantage of
.B GRND_RANDOM
and reads from
.I /dev/random
-is that the operation can block.
+is that the operation can block for an indefinite period of time.
Furthermore, dealing with the partially fulfilled
requests that can occur when using
.B GRND_RANDOM
.I /dev/random
increases code complexity.
.\"
-.SS 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 cryptographic random data.
-Users should be economical in the amount of seed
-material that they consume via
-.BR getrandom (2),
-.IR /dev/urandom ,
-and
-.IR /dev/random .
-Consuming unnecessarily large quantities of data via these interfaces
-will have a negative impact on other consumers of randomness.
-
-These interfaces should not be used to provide large quantities
-of data for Monte Carlo simulations or other
-programs/algorithms which are doing probabilistic sampling.
-Indeed, such usage is unnecessary (and will be slow).
-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.
+.SS Monte Carlo and other probabilistic sampling applications
+Using these interfaces to provide large quantities of data for
+Monte Carlo simulations or other programs/algorithms which are
+doing probabilistic sampling will be slow.
+Furthermore, it is unnecessary, because such applications do not
+need cryptographically secure random numbers.
+Instead, use the interfaces described in this page to obtain
+a small amount of data to seed a user-space pseudorandom
+number generator for use by such applications.
.\"
.SS Comparison between getrandom, /dev/urandom, and /dev/random
The following table summarizes the behavior of the various
.B GRND_NONBLOCK
is a flag that can be used to control the blocking behavior of
.BR 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.
.ad l
.TS
allbox;
-lbw13 lbw12 lbw16 lbw18
+lbw13 lbw12 lbw14 lbw18
l l l l.
Interface Pool T{
Blocking
\%behavior
T} T{
-Behavior in early boot time
+Behavior when pool is not yet ready
T}
T{
.I /dev/random
T} T{
Blocking pool
T} T{
-If entropy too low, block until there is enough entropy again
+If entropy too low, blocks until there is enough entropy again
T} T{
Blocks until enough entropy gathered
T}
Same as
.I /dev/urandom
T} T{
-Does not block once pool ready
+Does not block once is pool ready
T} T{
Blocks until pool ready
T}
Same as
.I /dev/random
T} T{
-If entropy too low, block until there is enough entropy again
+If entropy too low, blocks until there is enough entropy again
T} T{
Blocks until pool ready
T}
Same as
.I /dev/urandom
T} T{
-Does not block
+Does not block once is pool ready
T} T{
.B EAGAIN
-if pool not ready
T}
T{
.BR getrandom ()
if not enough entropy available
T} T{
.B EAGAIN
-if pool not ready
T}
.TE
.ad
(it requires about 2^128 operations to break) so a key generator
needs only 128 bits (16 bytes) of seed material from
.IR /dev/random .
-
+.PP
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,
.\"
.SH SEE ALSO
.BR getrandom (2),
+.BR getauxval (3),
+.BR getentropy (3),
.BR random (4),
.BR urandom (4),
.BR signal (7)