]>
Commit | Line | Data |
---|---|---|
0ae2c135 MK |
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> | |
5 | .\" | |
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. | |
10 | .\" | |
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. | |
15 | .\" | |
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. | |
22 | .\" professionally. | |
23 | .\" | |
24 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
25 | .\" the source, must acknowledge the copyright and authors of this work. | |
26 | .\" %%%LICENSE_END | |
27 | .\" | |
983c70fc MK |
28 | .\" The following web page is quite informative: |
29 | .\" http://www.2uo.de/myths-about-urandom/ | |
30 | .\" | |
0ae2c135 MK |
31 | .TH RANDOM 7 2016-11-11 "Linux" "Linux Programmer's Manual" |
32 | .SH NAME | |
33 | random \- overview of interfaces for obtaining randomness | |
34 | .SH DESCRIPTION | |
289b177f MK |
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. | |
39 | ||
40 | The following interfaces provide access to output from the kernel CSPRNG: | |
0ae2c135 MK |
41 | .IP * 3 |
42 | The | |
43 | .I /dev/urandom | |
44 | and | |
45 | .I /dev/random | |
46 | devices, both described in | |
47 | .BR random (4). | |
76d8c32d MK |
48 | These devices have been present on Linux since early times, |
49 | and are also available on many other systems. | |
0ae2c135 | 50 | .IP * |
76d8c32d | 51 | The Linux-specific |
0ae2c135 MK |
52 | .BR getrandom (2) |
53 | system call, available since Linux 3.17. | |
54 | This system call provides access either to the same source as | |
55 | .I /dev/urandom | |
56 | (called the | |
57 | .I urandom | |
dce6b796 | 58 | source in this page) |
0ae2c135 MK |
59 | or to the same source as |
60 | .I /dev/random | |
61 | (called the | |
62 | .I random | |
dce6b796 | 63 | source in this page). |
0ae2c135 MK |
64 | The default is the |
65 | .I urandom | |
dce6b796 | 66 | source; the |
0ae2c135 | 67 | .I random |
dce6b796 | 68 | source is selected by specifying the |
0ae2c135 MK |
69 | .BR GRND_RANDOM |
70 | flag to the system call. | |
71 | .\" | |
72 | .SS Initialization of the entropy pool | |
73 | The kernel collects bits of entropy from the environment. | |
74 | When a sufficient number of random bits has been collected, the | |
0ae2c135 | 75 | entropy pool is considered to be initialized. |
2b44a168 | 76 | .SS Choice of random source |
e919912d | 77 | Unless you are doing long-term key generation (and most likely not even |
7c896e1e | 78 | then), you probably shouldn't be reading from the |
e10dec29 | 79 | .IR /dev/random |
7c896e1e | 80 | device or employing |
0ae2c135 MK |
81 | .BR getrandom (2) |
82 | with the | |
83 | .BR GRND_RANDOM | |
e10dec29 | 84 | flag. |
7c896e1e | 85 | Instead, either read from the |
e10dec29 | 86 | .IR /dev/urandom |
7c896e1e | 87 | device or employ |
0ae2c135 MK |
88 | .BR getrandom (2) |
89 | without the | |
90 | .B GRND_RANDOM | |
e10dec29 | 91 | flag. |
0ae2c135 MK |
92 | The cryptographic algorithms used for the |
93 | .IR urandom | |
dce6b796 | 94 | source are quite conservative, and so should be sufficient for all purposes. |
0ae2c135 MK |
95 | |
96 | The disadvantage of | |
97 | .B GRND_RANDOM | |
98 | and reads from | |
99 | .I /dev/random | |
76d8c32d | 100 | is that the operation can block for an indefinite period of time. |
0ae2c135 MK |
101 | Furthermore, dealing with the partially fulfilled |
102 | requests that can occur when using | |
103 | .B GRND_RANDOM | |
104 | or when reading from | |
105 | .I /dev/random | |
106 | increases code complexity. | |
107 | .\" | |
40f0931c | 108 | .SS Monte Carlo and other probabilistic sampling applications |
289b177f MK |
109 | Using these interfaces to provide large quantities of data for |
110 | Monte Carlo simulations or other programs/algorithms which are | |
111 | doing probabilistic sampling will be slow. | |
112 | Furthermore, it is unnecessary, because such applications do not | |
113 | need cryptographically secure random numbers. | |
114 | Instead, use the interfaces described in this page to obtain | |
115 | a small amount of data to seed a user-space pseudorandom | |
116 | number generator for use by such applications. | |
0ae2c135 MK |
117 | .\" |
118 | .SS Comparison between getrandom, /dev/urandom, and /dev/random | |
119 | The following table summarizes the behavior of the various | |
120 | interfaces that can be used to obtain randomness. | |
121 | .B GRND_NONBLOCK | |
122 | is a flag that can be used to control the blocking behavior of | |
123 | .BR getrandom (2). | |
091ae4d2 MK |
124 | The final column of the table considers the case that can occur |
125 | in early boot time when the entropy pool is not yet initialized. | |
0ae2c135 MK |
126 | .ad l |
127 | .TS | |
128 | allbox; | |
091ae4d2 | 129 | lbw13 lbw12 lbw14 lbw18 |
0ae2c135 MK |
130 | l l l l. |
131 | Interface Pool T{ | |
132 | Blocking | |
133 | \%behavior | |
134 | T} T{ | |
091ae4d2 | 135 | Behavior when pool is not yet ready |
0ae2c135 MK |
136 | T} |
137 | T{ | |
138 | .I /dev/random | |
139 | T} T{ | |
140 | Blocking pool | |
141 | T} T{ | |
cdfedc03 | 142 | If entropy too low, blocks until there is enough entropy again |
0ae2c135 MK |
143 | T} T{ |
144 | Blocks until enough entropy gathered | |
145 | T} | |
146 | T{ | |
147 | .I /dev/urandom | |
148 | T} T{ | |
149 | CSPRNG output | |
150 | T} T{ | |
151 | Never blocks | |
152 | T} T{ | |
153 | Returns output from uninitialized CSPRNG (may be low entropy and unsuitable for cryptography) | |
154 | T} | |
155 | T{ | |
156 | .BR getrandom () | |
157 | T} T{ | |
158 | Same as | |
159 | .I /dev/urandom | |
160 | T} T{ | |
091ae4d2 | 161 | Does not block once is pool ready |
0ae2c135 MK |
162 | T} T{ |
163 | Blocks until pool ready | |
164 | T} | |
165 | T{ | |
166 | .BR getrandom () | |
167 | .B GRND_RANDOM | |
168 | T} T{ | |
169 | Same as | |
170 | .I /dev/random | |
171 | T} T{ | |
cdfedc03 | 172 | If entropy too low, blocks until there is enough entropy again |
0ae2c135 MK |
173 | T} T{ |
174 | Blocks until pool ready | |
175 | T} | |
176 | T{ | |
177 | .BR getrandom () | |
178 | .B GRND_NONBLOCK | |
179 | T} T{ | |
180 | Same as | |
181 | .I /dev/urandom | |
182 | T} T{ | |
091ae4d2 | 183 | Does not block once is pool ready |
0ae2c135 MK |
184 | T} T{ |
185 | .B EAGAIN | |
0ae2c135 MK |
186 | T} |
187 | T{ | |
188 | .BR getrandom () | |
189 | .B GRND_RANDOM | |
190 | + | |
191 | .B GRND_NONBLOCK | |
192 | T} T{ | |
193 | Same as | |
194 | .I /dev/random | |
195 | T} T{ | |
196 | .B EAGAIN | |
197 | if not enough entropy available | |
198 | T} T{ | |
199 | .B EAGAIN | |
0ae2c135 MK |
200 | T} |
201 | .TE | |
202 | .ad | |
203 | .\" | |
204 | .SS Generating cryptographic keys | |
205 | The amount of seed material required to generate a cryptographic key | |
206 | equals the effective key size of the key. | |
207 | For example, a 3072-bit RSA | |
208 | or Diffie-Hellman private key has an effective key size of 128 bits | |
209 | (it requires about 2^128 operations to break) so a key generator | |
210 | needs only 128 bits (16 bytes) of seed material from | |
211 | .IR /dev/random . | |
212 | ||
213 | While some safety margin above that minimum is reasonable, as a guard | |
214 | against flaws in the CSPRNG algorithm, no cryptographic primitive | |
215 | available today can hope to promise more than 256 bits of security, | |
216 | so if any program reads more than 256 bits (32 bytes) from the kernel | |
217 | random pool per invocation, or per reasonable reseed interval (not less | |
218 | than one minute), that should be taken as a sign that its cryptography is | |
219 | .I not | |
220 | skillfully implemented. | |
221 | .\" | |
222 | .SH SEE ALSO | |
223 | .BR getrandom (2), | |
224 | .BR random (4), | |
225 | .BR urandom (4), | |
226 | .BR signal (7) |