.\" 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 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. .\" .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 source 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 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)