.\" 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 the
+then), you probably shouldn't be reading from the
.IR /dev/random
-device
-or
+device or employing
.BR getrandom (2)
with the
.BR GRND_RANDOM
flag.
-
-Instead, use either the
+Instead, either read from the
.IR /dev/urandom
-device or
+device or employ
.BR getrandom (2)
without the
.B GRND_RANDOM
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 .
-.\" 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.
-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?
-
-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 will be slow, and is unnecessary,
-because such applications 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.
+.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 lbw15 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
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/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)
projects / thirdparty / man-pages.git / blobdiff