1 .\" Copyright (C) 2008, George Spelvin <linux@horizon.com>,
2 .\" and Copyright (C) 2008, Matt Mackall <mpm@selenic.com>
3 .\" and Copyright (C) 2016, Laurent Georget <laurent.georget@supelec.fr>
4 .\" and Copyright (C) 2016, Nikos Mavrogiannopoulos <nmav@redhat.com>
6 .\" %%%LICENSE_START(VERBATIM)
7 .\" Permission is granted to make and distribute verbatim copies of this
8 .\" manual provided the copyright notice and this permission notice are
9 .\" preserved on all copies.
11 .\" Permission is granted to copy and distribute modified versions of
12 .\" this manual under the conditions for verbatim copying, provided that
13 .\" the entire resulting derived work is distributed under the terms of
14 .\" a permission notice identical to this one.
16 .\" Since the Linux kernel and libraries are constantly changing, this
17 .\" manual page may be incorrect or out-of-date. The author(s) assume.
18 .\" no responsibility for errors or omissions, or for damages resulting.
19 .\" from the use of the information contained herein. The author(s) may.
20 .\" not have taken the same level of care in the production of this.
21 .\" manual, which is licensed free of charge, as they might when working.
24 .\" Formatted or processed versions of this manual, if unaccompanied by
25 .\" the source, must acknowledge the copyright and authors of this work.
28 .\" The following web page is quite informative:
29 .\" http://www.2uo.de/myths-about-urandom/
31 .TH RANDOM 7 2017-03-13 "Linux" "Linux Programmer's Manual"
33 random \- overview of interfaces for obtaining randomness
35 The kernel random-number generator relies on entropy gathered from
36 device drivers and other sources of environmental noise to seed
37 a cryptographically secure pseudorandom number generator (CSPRNG).
38 It is designed for security, rather than speed.
40 The following interfaces provide access to output from the kernel CSPRNG:
46 devices, both described in
48 These devices have been present on Linux since early times,
49 and are also available on many other systems.
53 system call, available since Linux 3.17.
54 This system call provides access either to the same source as
59 or to the same source as
68 source is selected by specifying the
70 flag to the system call.
73 function provides a slightly more portable interface on top of
76 .SS Initialization of the entropy pool
77 The kernel collects bits of entropy from the environment.
78 When a sufficient number of random bits has been collected, the
79 entropy pool is considered to be initialized.
80 .SS Choice of random source
81 Unless you are doing long-term key generation (and most likely not even
82 then), you probably shouldn't be reading from the
89 Instead, either read from the
96 The cryptographic algorithms used for the
98 source are quite conservative, and so should be sufficient for all purposes.
104 is that the operation can block for an indefinite period of time.
105 Furthermore, dealing with the partially fulfilled
106 requests that can occur when using
110 increases code complexity.
112 .SS Monte Carlo and other probabilistic sampling applications
113 Using these interfaces to provide large quantities of data for
114 Monte Carlo simulations or other programs/algorithms which are
115 doing probabilistic sampling will be slow.
116 Furthermore, it is unnecessary, because such applications do not
117 need cryptographically secure random numbers.
118 Instead, use the interfaces described in this page to obtain
119 a small amount of data to seed a user-space pseudorandom
120 number generator for use by such applications.
122 .SS Comparison between getrandom, /dev/urandom, and /dev/random
123 The following table summarizes the behavior of the various
124 interfaces that can be used to obtain randomness.
126 is a flag that can be used to control the blocking behavior of
128 The final column of the table considers the case that can occur
129 in early boot time when the entropy pool is not yet initialized.
133 lbw13 lbw12 lbw14 lbw18
139 Behavior when pool is not yet ready
146 If entropy too low, blocks until there is enough entropy again
148 Blocks until enough entropy gathered
157 Returns output from uninitialized CSPRNG (may be low entropy and unsuitable for cryptography)
165 Does not block once is pool ready
167 Blocks until pool ready
176 If entropy too low, blocks until there is enough entropy again
178 Blocks until pool ready
187 Does not block once is pool ready
201 if not enough entropy available
208 .SS Generating cryptographic keys
209 The amount of seed material required to generate a cryptographic key
210 equals the effective key size of the key.
211 For example, a 3072-bit RSA
212 or Diffie-Hellman private key has an effective key size of 128 bits
213 (it requires about 2^128 operations to break) so a key generator
214 needs only 128 bits (16 bytes) of seed material from
217 While some safety margin above that minimum is reasonable, as a guard
218 against flaws in the CSPRNG algorithm, no cryptographic primitive
219 available today can hope to promise more than 256 bits of security,
220 so if any program reads more than 256 bits (32 bytes) from the kernel
221 random pool per invocation, or per reasonable reseed interval (not less
222 than one minute), that should be taken as a sign that its cryptography is
224 skillfully implemented.