mirror of https://github.com/mkerrisk/man-pages
random.7: New page providing an overview of interfaces for obtaining randomness
Ccontains material extracted from getrandom(2) and random(4), as well as new material. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk
parent
6a0c1add49
commit
0ae2c1356d
|
|
@ -0,0 +1,236 @@
|
|||
.\" 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
|
||||
pool in this page)
|
||||
or to the same source as
|
||||
.I /dev/random
|
||||
(called the
|
||||
.I random
|
||||
pool in this page).
|
||||
The default is the
|
||||
.I urandom
|
||||
pool; the
|
||||
.I random
|
||||
pool is selected by specifying the
|
||||
.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
|
||||
pool are quite conservative, and so should be sufficient for all purposes.
|
||||
|
||||
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)
|
||||
Loading…
Reference in New Issue