| .\" 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> |
| .\" |
| .\" %%%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 |
| .\" |
| .\" The following web page is quite informative: |
| .\" http://www.2uo.de/myths-about-urandom/ |
| .\" |
| .TH RANDOM 7 2017-03-13 "Linux" "Linux Programmer's Manual" |
| .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 * 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 * |
| 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 |
| .BR 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 |
| .IR /dev/random |
| device or employing |
| .BR getrandom (2) |
| with the |
| .BR GRND_RANDOM |
| flag. |
| Instead, either read from the |
| .IR /dev/urandom |
| device or employ |
| .BR getrandom (2) |
| without the |
| .B GRND_RANDOM |
| flag. |
| The cryptographic algorithms used for the |
| .IR 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^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) |