diff options
Diffstat (limited to 'upstream/debian-bookworm/man7/random.7')
| -rw-r--r-- | upstream/debian-bookworm/man7/random.7 | 213 |
1 files changed, 213 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man7/random.7 b/upstream/debian-bookworm/man7/random.7 new file mode 100644 index 00000000..2e0698b8 --- /dev/null +++ b/upstream/debian-bookworm/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 2023-02-10 "Linux man-pages 6.03" +.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 \[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. +.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\[ha]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) |