]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1997 John S. Kallal (kallal@voicenet.com) |
2 | .\" | |
89e3ffe9 | 3 | .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) |
fea681da MK |
4 | .\" This is free documentation; you can redistribute it and/or |
5 | .\" modify it under the terms of the GNU General Public License as | |
6 | .\" published by the Free Software Foundation; either version 2 of | |
7 | .\" the License, or (at your option) any later version. | |
8f8359d8 | 8 | .\" %%%LICENSE_END |
fea681da MK |
9 | .\" |
10 | .\" Some changes by tytso and aeb. | |
11 | .\" | |
8deb0f0d | 12 | .\" 2004-12-16, John V. Belmonte/mtk, Updated init and quit scripts |
704a18f0 | 13 | .\" 2004-04-08, AEB, Improved description of read from /dev/urandom |
9ed0f081 MK |
14 | .\" 2008-06-20, George Spelvin <linux@horizon.com>, |
15 | .\" Matt Mackall <mpm@selenic.com> | |
8deb0f0d | 16 | .\" |
31a1b45e | 17 | .TH RANDOM 4 2017-03-13 "Linux" "Linux Programmer's Manual" |
fea681da MK |
18 | .SH NAME |
19 | random, urandom \- kernel random number source devices | |
5a933be0 EDB |
20 | .SH SYNOPSIS |
21 | #include <linux/random.h> | |
22 | .sp | |
23 | .BI "int ioctl(" fd ", RND" request ", " param ");" | |
fea681da | 24 | .SH DESCRIPTION |
c13182ef | 25 | The character special files \fI/dev/random\fP and |
8478ee02 | 26 | \fI/dev/urandom\fP (present since Linux 1.3.30) |
c13182ef | 27 | provide an interface to the kernel's random number generator. |
af0b0990 MK |
28 | The file |
29 | .I /dev/random\fP | |
30 | has major device number 1 and minor device number 8. | |
31 | The file | |
32 | .I /dev/urandom | |
33 | has major device number 1 and minor device number 9. | |
fea681da | 34 | .LP |
c13182ef MK |
35 | The random number generator gathers environmental noise |
36 | from device drivers and other sources into an entropy pool. | |
37 | The generator also keeps an estimate of the | |
fea681da | 38 | number of bits of noise in the entropy pool. |
82f0a1f9 | 39 | From this entropy pool, random numbers are created. |
c13182ef | 40 | .LP |
724d21bb | 41 | Linux 3.17 and later provides the simpler and safer |
f64f220c | 42 | .BR getrandom (2) |
724d21bb MK |
43 | interface which requires no special files; |
44 | see the | |
45 | .BR getrandom (2) | |
46 | manual page for details. | |
47 | ||
f64f220c MK |
48 | When read, the |
49 | .I /dev/urandom | |
50 | device returns random bytes using a pseudorandom | |
51 | number generator seeded from the entropy pool. | |
6a0c1add | 52 | Reads from this device do not block (i.e., the CPU is not yielded), |
e6e25836 | 53 | but can incur an appreciable delay when requesting large amounts of data. |
daaeba95 MK |
54 | |
55 | When read during early boot time, | |
bb02bcef | 56 | .IR /dev/urandom |
daaeba95 | 57 | may return data prior to the entropy pool being initialized. |
8888079c MK |
58 | .\" This is a real problem; see |
59 | .\" commit 9b4d008787f864f17d008c9c15bbe8a0f7e2fc24 | |
67b7fcba | 60 | If this is of concern in your application, use |
f64f220c | 61 | .BR getrandom (2) |
67b7fcba NM |
62 | or \fI/dev/random\fP instead. |
63 | ||
67b7fcba NM |
64 | The \fI/dev/random\fP device is a legacy interface which dates back to |
65 | a time where the cryptographic primitives used in the implementation | |
f64f220c MK |
66 | of \fI/dev/urandom\fP were not widely trusted. |
67 | It will return random bytes only within the estimated number of | |
68 | bits of fresh noise in the entropy pool, blocking if necessary. | |
c5d010eb | 69 | \fI/dev/random\fP is suitable for applications that need |
67b7fcba | 70 | high quality randomness, and can afford indeterminate delays. |
724d21bb | 71 | |
c13182ef | 72 | When the entropy pool is empty, reads from \fI/dev/random\fP will block |
fea681da | 73 | until additional environmental noise is gathered. |
17344691 HS |
74 | If |
75 | .BR open (2) | |
76 | is called for | |
77 | .I /dev/random | |
724d21bb MK |
78 | with the |
79 | .BR O_NONBLOCK | |
80 | flag, a subsequent | |
17344691 HS |
81 | .BR read (2) |
82 | will not block if the requested number of bytes is not available. | |
e8cc3c09 | 83 | Instead, the available bytes are returned. |
792bb5ad | 84 | If no byte is available, |
17344691 HS |
85 | .BR read (2) |
86 | will return -1 and | |
87 | .I errno | |
88 | will be set to | |
89 | .BR EAGAIN . | |
67b7fcba | 90 | |
724d21bb | 91 | The |
17344691 | 92 | .B O_NONBLOCK |
724d21bb | 93 | flag has no effect when opening |
17344691 HS |
94 | .IR /dev/urandom . |
95 | When calling | |
96 | .BR read (2) | |
792bb5ad MK |
97 | for the device |
98 | .IR /dev/urandom , | |
dbf63eed MK |
99 | reads of up to 256 bytes will return as many bytes as are requested |
100 | and will not be interrupted by a signal handler. | |
101 | Reads with a buffer over this limit may return less than the | |
102 | requested number of bytes or fail with the error | |
4818990d MK |
103 | .BR EINTR , |
104 | if interrupted by a signal handler. | |
866fa681 MK |
105 | |
106 | Since Linux 3.16, | |
107 | .\" commit 79a8468747c5f95ed3d5ce8376a3e82e0c5857fc | |
108 | a | |
109 | .BR read (2) | |
110 | from | |
111 | .IR /dev/urandom | |
112 | will return at most 32 MB. | |
44da0e24 MK |
113 | A |
114 | .BR read (2) | |
115 | from | |
116 | .IR /dev/random | |
117 | will return at most 512 bytes | |
118 | .\" SEC_XFER_SIZE in drivers/char/random.c | |
119 | (340 bytes on Linux kernels before version 2.6.12). | |
866fa681 | 120 | |
5a933be0 EDB |
121 | Writing to \fI/dev/random\fP or \fI/dev/urandom\fP will update the |
122 | entropy pool with the data written, but this will not result in a | |
ece967c9 MK |
123 | higher entropy count. |
124 | This means that it will impact the contents | |
125 | read from both files, but it will not make reads from | |
5a933be0 | 126 | \fI/dev/random\fP faster. |
9ed0f081 | 127 | .SS Usage |
67b7fcba | 128 | The |
9ed0f081 | 129 | .IR /dev/random |
67b7fcba | 130 | interface is considered a legacy interface, and |
724d21bb | 131 | .IR /dev/urandom |
67b7fcba NM |
132 | is preferred and sufficient in all use cases, with the exception of |
133 | applications which require randomness during early boot time; for | |
f64f220c MK |
134 | these applications, |
135 | .BR getrandom (2) | |
136 | must be used instead, | |
137 | because it will block until the entropy pool is initialized. | |
9ed0f081 | 138 | |
a26a0d7b | 139 | If a seed file is saved across reboots as recommended below (all major |
9ed0f081 MK |
140 | Linux distributions have done this since 2000 at least), the output is |
141 | cryptographically secure against attackers without local root access as | |
142 | soon as it is reloaded in the boot sequence, and perfectly adequate for | |
143 | network encryption session keys. | |
e7dfa844 | 144 | Since reads from |
9ed0f081 | 145 | .I /dev/random |
ff40dbb3 | 146 | may block, users will usually want to open it in nonblocking mode |
e7dfa844 MK |
147 | (or perform a read with timeout), |
148 | and provide some sort of user notification if the desired | |
9ed0f081 | 149 | entropy is not immediately available. |
2e1f8bfa | 150 | .\" |
8eb40c9c | 151 | .SS Configuration |
fea681da | 152 | If your system does not have |
c13182ef | 153 | \fI/dev/random\fP and \fI/dev/urandom\fP created already, they |
fea681da MK |
154 | can be created with the following commands: |
155 | ||
156 | .nf | |
6f67e3e3 MK |
157 | mknod \-m 666 /dev/random c 1 8 |
158 | mknod \-m 666 /dev/urandom c 1 9 | |
7295b7ed | 159 | chown root:root /dev/random /dev/urandom |
fea681da | 160 | .fi |
c13182ef MK |
161 | |
162 | When a Linux system starts up without much operator interaction, | |
fea681da | 163 | the entropy pool may be in a fairly predictable state. |
c13182ef MK |
164 | This reduces the actual amount of noise in the entropy pool |
165 | below the estimate. | |
166 | In order to counteract this effect, it helps to carry | |
167 | entropy pool information across shut-downs and start-ups. | |
3f4a2adb | 168 | To do this, add the lines to an appropriate script |
c13182ef | 169 | which is run during the Linux system start-up sequence: |
fea681da MK |
170 | |
171 | .nf | |
7295b7ed MK |
172 | echo "Initializing random number generator..." |
173 | random_seed=/var/run/random-seed | |
174 | # Carry a random seed from start-up to start-up | |
175 | # Load and then save the whole entropy pool | |
176 | if [ \-f $random_seed ]; then | |
177 | cat $random_seed >/dev/urandom | |
178 | else | |
179 | touch $random_seed | |
180 | fi | |
181 | chmod 600 $random_seed | |
182 | poolfile=/proc/sys/kernel/random/poolsize | |
ff76b299 | 183 | [ \-r $poolfile ] && bits=$(cat $poolfile) || bits=4096 |
3f4a2adb | 184 | bytes=$(expr $bits / 8) |
7295b7ed | 185 | dd if=/dev/urandom of=$random_seed count=1 bs=$bytes |
fea681da MK |
186 | .fi |
187 | ||
c13182ef | 188 | Also, add the following lines in an appropriate script which is |
fea681da | 189 | run during the Linux system shutdown: |
c13182ef | 190 | |
fea681da | 191 | .nf |
7295b7ed MK |
192 | # Carry a random seed from shut-down to start-up |
193 | # Save the whole entropy pool | |
194 | echo "Saving random seed..." | |
195 | random_seed=/var/run/random-seed | |
196 | touch $random_seed | |
197 | chmod 600 $random_seed | |
198 | poolfile=/proc/sys/kernel/random/poolsize | |
ff76b299 | 199 | [ \-r $poolfile ] && bits=$(cat $poolfile) || bits=4096 |
3f4a2adb | 200 | bytes=$(expr $bits / 8) |
7295b7ed | 201 | dd if=/dev/urandom of=$random_seed count=1 bs=$bytes |
fea681da | 202 | .fi |
3f4a2adb MK |
203 | |
204 | In the above examples, we assume Linux 2.6.0 or later, where | |
205 | .IR /proc/sys/kernel/random/poolsize | |
206 | returns the size of the entropy pool in bits (see below). | |
388ee0f4 MK |
207 | .\" |
208 | .SS /proc interfaces | |
fea681da MK |
209 | The files in the directory |
210 | .I /proc/sys/kernel/random | |
388ee0f4 | 211 | (present since 2.3.16) provide additional information about the |
8478ee02 | 212 | .I /dev/random |
388ee0f4 MK |
213 | device: |
214 | .TP | |
fea681da | 215 | .I entropy_avail |
05babf32 MK |
216 | This read-only file gives the available entropy, in bits. |
217 | This will be a number in the range 0 to 4096. | |
388ee0f4 | 218 | .TP |
fea681da | 219 | .I poolsize |
388ee0f4 | 220 | This file |
c13182ef | 221 | gives the size of the entropy pool. |
da84883c MK |
222 | The semantics of this file vary across kernel versions: |
223 | .RS | |
388ee0f4 | 224 | .TP |
da84883c MK |
225 | Linux 2.4: |
226 | This file gives the size of the entropy pool in | |
227 | .IR bytes . | |
228 | Normally, this file will have the value 512, but it is writable, | |
229 | and can be changed to any value for which an algorithm is available. | |
230 | The choices are 32, 64, 128, 256, 512, 1024, or 2048. | |
231 | .TP | |
388ee0f4 | 232 | Linux 2.6 and later |
da84883c MK |
233 | This file is read-only, and gives the size of the entropy pool in |
234 | .IR bits . | |
235 | It contains the value 4096. | |
236 | .RE | |
388ee0f4 | 237 | .TP |
fea681da | 238 | .I read_wakeup_threshold |
388ee0f4 | 239 | This file |
fea681da MK |
240 | contains the number of bits of entropy required for waking up processes |
241 | that sleep waiting for entropy from | |
31e9a9ec | 242 | .IR /dev/random . |
fea681da | 243 | The default is 64. |
388ee0f4 | 244 | .TP |
fea681da | 245 | .I write_wakeup_threshold |
388ee0f4 | 246 | This file |
fea681da MK |
247 | contains the number of bits of entropy below which we wake up |
248 | processes that do a | |
5e21af3a | 249 | .BR select (2) |
fea681da | 250 | or |
5e21af3a | 251 | .BR poll (2) |
fea681da | 252 | for write access to |
31e9a9ec | 253 | .IR /dev/random . |
fea681da | 254 | These values can be changed by writing to the files. |
388ee0f4 MK |
255 | .TP |
256 | .IR uuid " and " boot_id | |
257 | These read-only files | |
fea681da MK |
258 | contain random strings like 6fd5a44b-35f4-4ad4-a9b9-6b9be13e1fe9. |
259 | The former is generated afresh for each read, the latter was | |
260 | generated once. | |
388ee0f4 | 261 | .\" |
5a933be0 EDB |
262 | .SS ioctl(2) interface |
263 | The following | |
264 | .BR ioctl (2) | |
265 | requests are defined on file descriptors connected to either \fI/dev/random\fP | |
ece967c9 MK |
266 | or \fI/dev/urandom\fP. |
267 | All requests performed will interact with the input | |
5a933be0 EDB |
268 | entropy pool impacting both \fI/dev/random\fP and \fI/dev/urandom\fP. |
269 | The | |
270 | .B CAP_SYS_ADMIN | |
271 | capability is required for all requests except | |
ece967c9 | 272 | .BR RNDGETENTCNT . |
5a933be0 EDB |
273 | .TP |
274 | .BR RNDGETENTCNT | |
275 | Retrieve the entropy count of the input pool, the contents will be the same | |
276 | as the | |
277 | .I entropy_avail | |
278 | file under proc. | |
279 | The result will be stored in the int pointed to by the argument. | |
280 | .TP | |
281 | .BR RNDADDTOENTCNT | |
ece967c9 MK |
282 | Increment or decrement the entropy count of the input pool |
283 | by the value pointed to by the argument. | |
5a933be0 EDB |
284 | .TP |
285 | .BR RNDGETPOOL | |
286 | Removed in Linux 2.6.9. | |
287 | .TP | |
288 | .BR RNDADDENTROPY | |
ece967c9 MK |
289 | Add some additional entropy to the input pool, |
290 | incrementing the entropy count. | |
291 | This differs from writing to \fI/dev/random\fP or \fI/dev/urandom\fP, | |
292 | which only adds some | |
293 | data but does not increment the entropy count. | |
294 | The following structure is used: | |
5a933be0 | 295 | .IP |
7b512dff MK |
296 | .nf |
297 | struct rand_pool_info { | |
298 | int entropy_count; | |
299 | int buf_size; | |
300 | __u32 buf[0]; | |
301 | }; | |
302 | .fi | |
5a933be0 EDB |
303 | .IP |
304 | Here | |
305 | .I entropy_count | |
988bd008 | 306 | is the value added to (or subtracted from) the entropy count, and |
5a933be0 EDB |
307 | .I buf |
308 | is the buffer of size | |
309 | .I buf_size | |
310 | which gets added to the entropy pool. | |
311 | .TP | |
312 | .BR RNDZAPENTCNT ", " RNDCLEARPOOL | |
313 | Zero the entropy count of all pools and add some system data (such as | |
314 | wall clock) to the pools. | |
379df7a0 MK |
315 | .SH NOTES |
316 | For an overview and comparison of the various interfaces that | |
317 | can be used to obtain randomness, see | |
318 | .BR random (7). | |
f64f220c | 319 | .SH BUGS |
debb291e | 320 | During early boot time, reads from |
f64f220c MK |
321 | .I /dev/urandom |
322 | may return data prior to the entropy pool being initialized. | |
fea681da MK |
323 | .SH FILES |
324 | /dev/random | |
325 | .br | |
326 | /dev/urandom | |
dc919d09 MK |
327 | .\" .SH AUTHOR |
328 | .\" The kernel's random number generator was written by | |
329 | .\" Theodore Ts'o (tytso@athena.mit.edu). | |
47297adb | 330 | .SH SEE ALSO |
59732c2a | 331 | .BR mknod (1), |
379df7a0 MK |
332 | .BR getrandom (2), |
333 | .BR random (7) | |
59732c2a | 334 | |
331da7c3 | 335 | RFC\ 1750, "Randomness Recommendations for Security" |