]>
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 | .\" | |
31a1b45e | 31 | .TH RANDOM 7 2017-03-13 "Linux" "Linux Programmer's Manual" |
0ae2c135 MK |
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. | |
a721e8b2 | 39 | .PP |
289b177f | 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 | |
1b9d5819 | 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. | |
f1397035 MK |
71 | (The |
72 | .BR getentropy (3) | |
73 | function provides a slightly more portable interface on top of | |
74 | .BR getrandom (2).) | |
0ae2c135 MK |
75 | .\" |
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 | |
0ae2c135 | 79 | entropy pool is considered to be initialized. |
2b44a168 | 80 | .SS Choice of random source |
e919912d | 81 | Unless you are doing long-term key generation (and most likely not even |
7c896e1e | 82 | then), you probably shouldn't be reading from the |
e10dec29 | 83 | .IR /dev/random |
7c896e1e | 84 | device or employing |
0ae2c135 MK |
85 | .BR getrandom (2) |
86 | with the | |
87 | .BR GRND_RANDOM | |
e10dec29 | 88 | flag. |
7c896e1e | 89 | Instead, either read from the |
e10dec29 | 90 | .IR /dev/urandom |
7c896e1e | 91 | device or employ |
0ae2c135 MK |
92 | .BR getrandom (2) |
93 | without the | |
94 | .B GRND_RANDOM | |
e10dec29 | 95 | flag. |
0ae2c135 MK |
96 | The cryptographic algorithms used for the |
97 | .IR urandom | |
dce6b796 | 98 | source are quite conservative, and so should be sufficient for all purposes. |
a721e8b2 | 99 | .PP |
0ae2c135 MK |
100 | The disadvantage of |
101 | .B GRND_RANDOM | |
102 | and reads from | |
103 | .I /dev/random | |
76d8c32d | 104 | is that the operation can block for an indefinite period of time. |
0ae2c135 MK |
105 | Furthermore, dealing with the partially fulfilled |
106 | requests that can occur when using | |
107 | .B GRND_RANDOM | |
108 | or when reading from | |
109 | .I /dev/random | |
110 | increases code complexity. | |
111 | .\" | |
40f0931c | 112 | .SS Monte Carlo and other probabilistic sampling applications |
289b177f MK |
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. | |
0ae2c135 MK |
121 | .\" |
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. | |
125 | .B GRND_NONBLOCK | |
126 | is a flag that can be used to control the blocking behavior of | |
127 | .BR getrandom (2). | |
091ae4d2 MK |
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. | |
0ae2c135 MK |
130 | .ad l |
131 | .TS | |
132 | allbox; | |
091ae4d2 | 133 | lbw13 lbw12 lbw14 lbw18 |
0ae2c135 MK |
134 | l l l l. |
135 | Interface Pool T{ | |
136 | Blocking | |
137 | \%behavior | |
138 | T} T{ | |
091ae4d2 | 139 | Behavior when pool is not yet ready |
0ae2c135 MK |
140 | T} |
141 | T{ | |
142 | .I /dev/random | |
143 | T} T{ | |
144 | Blocking pool | |
145 | T} T{ | |
cdfedc03 | 146 | If entropy too low, blocks until there is enough entropy again |
0ae2c135 MK |
147 | T} T{ |
148 | Blocks until enough entropy gathered | |
149 | T} | |
150 | T{ | |
151 | .I /dev/urandom | |
152 | T} T{ | |
153 | CSPRNG output | |
154 | T} T{ | |
155 | Never blocks | |
156 | T} T{ | |
157 | Returns output from uninitialized CSPRNG (may be low entropy and unsuitable for cryptography) | |
158 | T} | |
159 | T{ | |
160 | .BR getrandom () | |
161 | T} T{ | |
162 | Same as | |
163 | .I /dev/urandom | |
164 | T} T{ | |
091ae4d2 | 165 | Does not block once is pool ready |
0ae2c135 MK |
166 | T} T{ |
167 | Blocks until pool ready | |
168 | T} | |
169 | T{ | |
170 | .BR getrandom () | |
171 | .B GRND_RANDOM | |
172 | T} T{ | |
173 | Same as | |
174 | .I /dev/random | |
175 | T} T{ | |
cdfedc03 | 176 | If entropy too low, blocks until there is enough entropy again |
0ae2c135 MK |
177 | T} T{ |
178 | Blocks until pool ready | |
179 | T} | |
180 | T{ | |
181 | .BR getrandom () | |
182 | .B GRND_NONBLOCK | |
183 | T} T{ | |
184 | Same as | |
185 | .I /dev/urandom | |
186 | T} T{ | |
091ae4d2 | 187 | Does not block once is pool ready |
0ae2c135 MK |
188 | T} T{ |
189 | .B EAGAIN | |
0ae2c135 MK |
190 | T} |
191 | T{ | |
192 | .BR getrandom () | |
193 | .B GRND_RANDOM | |
194 | + | |
195 | .B GRND_NONBLOCK | |
196 | T} T{ | |
197 | Same as | |
198 | .I /dev/random | |
199 | T} T{ | |
200 | .B EAGAIN | |
201 | if not enough entropy available | |
202 | T} T{ | |
203 | .B EAGAIN | |
0ae2c135 MK |
204 | T} |
205 | .TE | |
206 | .ad | |
207 | .\" | |
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 | |
215 | .IR /dev/random . | |
a721e8b2 | 216 | .PP |
0ae2c135 MK |
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 | |
223 | .I not | |
224 | skillfully implemented. | |
225 | .\" | |
226 | .SH SEE ALSO | |
227 | .BR getrandom (2), | |
7c28a0b6 | 228 | .BR getauxval (3), |
933ab9c7 | 229 | .BR getentropy (3), |
0ae2c135 MK |
230 | .BR random (4), |
231 | .BR urandom (4), | |
232 | .BR signal (7) |