2016-11-11 21:23:39 +00:00
|
|
|
.\" Copyright (C) 2008, George Spelvin <linux@horizon.com>,
|
|
|
|
.\" and Copyright (C) 2008, Matt Mackall <mpm@selenic.com>
|
|
|
|
.\" and Copyright (C) 2016, Laurent Georget <laurent.georget@supelec.fr>
|
|
|
|
.\" and Copyright (C) 2016, Nikos Mavrogiannopoulos <nmav@redhat.com>
|
|
|
|
.\"
|
|
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of
|
|
|
|
.\" this manual under the conditions for verbatim copying, provided that
|
|
|
|
.\" the entire resulting derived work is distributed under the terms of
|
|
|
|
.\" a permission notice identical to this one.
|
|
|
|
.\"
|
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume.
|
|
|
|
.\" no responsibility for errors or omissions, or for damages resulting.
|
|
|
|
.\" from the use of the information contained herein. The author(s) may.
|
|
|
|
.\" not have taken the same level of care in the production of this.
|
|
|
|
.\" manual, which is licensed free of charge, as they might when working.
|
|
|
|
.\" professionally.
|
|
|
|
.\"
|
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\" %%%LICENSE_END
|
|
|
|
.\"
|
|
|
|
.TH RANDOM 7 2016-11-11 "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):
|
|
|
|
.IP * 3
|
|
|
|
The
|
|
|
|
.I /dev/urandom
|
|
|
|
and
|
|
|
|
.I /dev/random
|
|
|
|
devices, both described in
|
|
|
|
.BR random (4).
|
|
|
|
These devices have been present on Linux since early times.
|
|
|
|
.IP *
|
|
|
|
The
|
|
|
|
.BR getrandom (2)
|
|
|
|
system call, available since Linux 3.17.
|
|
|
|
This system call provides access either to the same source as
|
|
|
|
.I /dev/urandom
|
|
|
|
(called the
|
|
|
|
.I urandom
|
2016-11-11 21:36:09 +00:00
|
|
|
source in this page)
|
2016-11-11 21:23:39 +00:00
|
|
|
or to the same source as
|
|
|
|
.I /dev/random
|
|
|
|
(called the
|
|
|
|
.I random
|
2016-11-11 21:36:09 +00:00
|
|
|
source in this page).
|
2016-11-11 21:23:39 +00:00
|
|
|
The default is the
|
|
|
|
.I urandom
|
2016-11-11 21:36:09 +00:00
|
|
|
source; the
|
2016-11-11 21:23:39 +00:00
|
|
|
.I random
|
2016-11-11 21:36:09 +00:00
|
|
|
source is selected by specifying the
|
2016-11-11 21:23:39 +00:00
|
|
|
.BR GRND_RANDOM
|
|
|
|
flag to the system call.
|
|
|
|
.\"
|
|
|
|
.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
|
|
|
|
Unless you are doing long-term key generation (and perhaps not even
|
|
|
|
then), you probably shouldn't be using
|
|
|
|
.BR getrandom (2)
|
|
|
|
with the
|
|
|
|
.BR GRND_RANDOM
|
|
|
|
flag or the
|
|
|
|
.IR /dev/random
|
|
|
|
device.
|
|
|
|
|
|
|
|
Instead, use either
|
|
|
|
.BR getrandom (2)
|
|
|
|
without the
|
|
|
|
.B GRND_RANDOM
|
|
|
|
flag or the
|
|
|
|
.IR /dev/urandom
|
|
|
|
device.
|
|
|
|
The cryptographic algorithms used for the
|
|
|
|
.IR urandom
|
2016-11-11 21:36:09 +00:00
|
|
|
source are quite conservative, and so should be sufficient for all purposes.
|
2016-11-11 21:23:39 +00:00
|
|
|
|
|
|
|
The disadvantage of
|
|
|
|
.B GRND_RANDOM
|
|
|
|
and reads from
|
|
|
|
.I /dev/random
|
|
|
|
is that the operation can block.
|
|
|
|
Furthermore, dealing with the partially fulfilled
|
|
|
|
requests that can occur when using
|
|
|
|
.B GRND_RANDOM
|
|
|
|
or when reading from
|
|
|
|
.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 very 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 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.
|
|
|
|
.B GRND_NONBLOCK
|
|
|
|
is a flag that can be used to control the blocking behavior of
|
|
|
|
.BR getrandom (2).
|
|
|
|
.ad l
|
|
|
|
.TS
|
|
|
|
allbox;
|
|
|
|
lbw13 lbw12 lbw16 lbw18
|
|
|
|
l l l l.
|
|
|
|
Interface Pool T{
|
|
|
|
Blocking
|
|
|
|
\%behavior
|
|
|
|
T} T{
|
|
|
|
Behavior in early boot time
|
|
|
|
T}
|
|
|
|
T{
|
|
|
|
.I /dev/random
|
|
|
|
T} T{
|
|
|
|
Blocking pool
|
|
|
|
T} T{
|
|
|
|
If entropy too low, block until there is enough entropy again
|
|
|
|
T} T{
|
|
|
|
Blocks until enough entropy gathered
|
|
|
|
T}
|
|
|
|
T{
|
|
|
|
.I /dev/urandom
|
|
|
|
T} T{
|
|
|
|
CSPRNG output
|
|
|
|
T} T{
|
|
|
|
Never blocks
|
|
|
|
T} T{
|
|
|
|
Returns output from uninitialized CSPRNG (may be low entropy and unsuitable for cryptography)
|
|
|
|
T}
|
|
|
|
T{
|
|
|
|
.BR getrandom ()
|
|
|
|
T} T{
|
|
|
|
Same as
|
|
|
|
.I /dev/urandom
|
|
|
|
T} T{
|
|
|
|
Does not block once pool ready
|
|
|
|
T} T{
|
|
|
|
Blocks until pool ready
|
|
|
|
T}
|
|
|
|
T{
|
|
|
|
.BR getrandom ()
|
|
|
|
.B GRND_RANDOM
|
|
|
|
T} T{
|
|
|
|
Same as
|
|
|
|
.I /dev/random
|
|
|
|
T} T{
|
|
|
|
If entropy too low, block until there is enough entropy again
|
|
|
|
T} T{
|
|
|
|
Blocks until pool ready
|
|
|
|
T}
|
|
|
|
T{
|
|
|
|
.BR getrandom ()
|
|
|
|
.B GRND_NONBLOCK
|
|
|
|
T} T{
|
|
|
|
Same as
|
|
|
|
.I /dev/urandom
|
|
|
|
T} T{
|
|
|
|
Does not block
|
|
|
|
T} T{
|
|
|
|
.B EAGAIN
|
|
|
|
if pool not ready
|
|
|
|
T}
|
|
|
|
T{
|
|
|
|
.BR getrandom ()
|
|
|
|
.B GRND_RANDOM
|
|
|
|
+
|
|
|
|
.B GRND_NONBLOCK
|
|
|
|
T} T{
|
|
|
|
Same as
|
|
|
|
.I /dev/random
|
|
|
|
T} T{
|
|
|
|
.B EAGAIN
|
|
|
|
if not enough entropy available
|
|
|
|
T} T{
|
|
|
|
.B EAGAIN
|
|
|
|
if pool not ready
|
|
|
|
T}
|
|
|
|
.TE
|
|
|
|
.ad
|
|
|
|
.\"
|
|
|
|
.SS Generating cryptographic keys
|
|
|
|
The amount of seed material required to generate a cryptographic 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 operations to break) so a key generator
|
|
|
|
needs only 128 bits (16 bytes) of seed material from
|
|
|
|
.IR /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
|
|
|
|
.I not
|
|
|
|
skillfully implemented.
|
|
|
|
.\"
|
|
|
|
.SH SEE ALSO
|
|
|
|
.BR getrandom (2),
|
|
|
|
.BR random (4),
|
|
|
|
.BR urandom (4),
|
|
|
|
.BR signal (7)
|