From 0ae2c1356d3aa3e67591dc528933a311b1a8ec80 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Fri, 11 Nov 2016 22:23:39 +0100 Subject: [PATCH] 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 --- man7/random.7 | 236 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 236 insertions(+) create mode 100644 man7/random.7 diff --git a/man7/random.7 b/man7/random.7 new file mode 100644 index 000000000..87e013d7c --- /dev/null +++ b/man7/random.7 @@ -0,0 +1,236 @@ +.\" Copyright (C) 2008, George Spelvin , +.\" and Copyright (C) 2008, Matt Mackall +.\" and Copyright (C) 2016, Laurent Georget +.\" and Copyright (C) 2016, Nikos Mavrogiannopoulos +.\" +.\" %%%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)