1 files changed, 213 insertions, 0 deletions
diff --git a/man/man7/random.7 b/man/man7/random.7
new file mode 100644
index 000000000..5062b1900
--- /dev/null
+++ b/man/man7/random.7
@@ -0,0 +1,213 @@
+'\" t
+.\" 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>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" The following web page is quite informative:
+.\" http://www.2uo.de/myths-about-urandom/
+.\"
+.TH random 7 (date) "Linux man-pages (unreleased)"
+.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.
+.P
+The following interfaces provide access to output from the kernel CSPRNG:
+.IP \[bu] 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 \[bu]
+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
+.B 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
+.I /dev/random
+device or employing
+.BR getrandom (2)
+with the
+.B GRND_RANDOM
+flag.
+Instead, either read from the
+.I /dev/urandom
+device or employ
+.BR getrandom (2)
+without the
+.B GRND_RANDOM
+flag.
+The cryptographic algorithms used for the
+.I urandom
+source are quite conservative, and so should be sufficient for all purposes.
+.P
+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\[ha]128 operations to break) so a key generator
+needs only 128 bits (16 bytes) of seed material from
+.IR /dev/random .
+.P
+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)