mirror of https://github.com/mkerrisk/man-pages
233 lines
6.4 KiB
Groff
233 lines
6.4 KiB
Groff
.\" 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
|
|
.\"
|
|
.\" 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 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
|
|
and
|
|
.I /dev/random
|
|
devices, both described in
|
|
.BR random (4).
|
|
These devices have been present on Linux since early times,
|
|
and are also available on many other systems.
|
|
.IP *
|
|
The Linux-specific
|
|
.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
|
|
source in this page)
|
|
or to the same source as
|
|
.I /dev/random
|
|
(called the
|
|
.I random
|
|
source in this page).
|
|
The default is the
|
|
.I urandom
|
|
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
|
|
entropy pool is considered to be initialized.
|
|
.SS Choice of random source
|
|
Unless you are doing long-term key generation (and most likely not even
|
|
then), you probably shouldn't be reading from the
|
|
.IR /dev/random
|
|
device or employing
|
|
.BR getrandom (2)
|
|
with the
|
|
.BR GRND_RANDOM
|
|
flag.
|
|
Instead, either read from the
|
|
.IR /dev/urandom
|
|
device or employ
|
|
.BR getrandom (2)
|
|
without the
|
|
.B GRND_RANDOM
|
|
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 for an indefinite period of time.
|
|
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 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
|
|
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).
|
|
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 lbw14 lbw18
|
|
l l l l.
|
|
Interface Pool T{
|
|
Blocking
|
|
\%behavior
|
|
T} T{
|
|
Behavior when pool is not yet ready
|
|
T}
|
|
T{
|
|
.I /dev/random
|
|
T} T{
|
|
Blocking pool
|
|
T} T{
|
|
If entropy too low, blocks 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 is 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, blocks 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 once is pool ready
|
|
T} T{
|
|
.B EAGAIN
|
|
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
|
|
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 .
|
|
.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,
|
|
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 getauxval (3),
|
|
.BR getentropy (3),
|
|
.BR random (4),
|
|
.BR urandom (4),
|
|
.BR signal (7)
|