From 3d08cd331c1adcf0d917392f7e527b3f00511748 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 24 May 2024 06:52:22 +0200 Subject: Merging upstream version 6.8. Signed-off-by: Daniel Baumann --- man/man7/random.7 | 213 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 213 insertions(+) create mode 100644 man/man7/random.7 (limited to 'man/man7/random.7') diff --git a/man/man7/random.7 b/man/man7/random.7 new file mode 100644 index 0000000..4eb4bae --- /dev/null +++ b/man/man7/random.7 @@ -0,0 +1,213 @@ +'\" t +.\" Copyright (C) 2008, George Spelvin , +.\" and Copyright (C) 2008, Matt Mackall +.\" and Copyright (C) 2016, Laurent Georget +.\" and Copyright (C) 2016, Nikos Mavrogiannopoulos +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" The following web page is quite informative: +.\" http://www.2uo.de/myths-about-urandom/ +.\" +.TH random 7 2024-05-02 "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) -- cgit v1.2.3