]>
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 | .\" |
4b8c67d9 | 17 | .TH RANDOM 4 2017-09-15 "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> | |
68e4db0a | 22 | .PP |
5a933be0 | 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 | 28 | The file |
11bda441 | 29 | .I /dev/random |
af0b0990 MK |
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. | |
dd3568a1 | 34 | .PP |
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. |
dd3568a1 | 40 | .PP |
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. | |
2d444feb | 47 | .PP |
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. |
2d444feb | 54 | .PP |
daaeba95 | 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 | 62 | or \fI/dev/random\fP instead. |
2d444feb | 63 | .PP |
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. |
2d444feb | 71 | .PP |
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 . | |
2d444feb | 90 | .PP |
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. | |
2d444feb | 105 | .PP |
866fa681 MK |
106 | Since Linux 3.16, |
107 | .\" commit 79a8468747c5f95ed3d5ce8376a3e82e0c5857fc | |
108 | a | |
109 | .BR read (2) | |
110 | from | |
111 | .IR /dev/urandom | |
c4b7e5ac | 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). | |
2d444feb | 120 | .PP |
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. | |
2d444feb | 138 | .PP |
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 | 154 | can be created with the following commands: |
2d444feb | 155 | .PP |
9c40f2b9 MK |
156 | .in +4n |
157 | .EX | |
158 | mknod \-m 666 /dev/random c 1 8 | |
159 | mknod \-m 666 /dev/urandom c 1 9 | |
160 | chown root:root /dev/random /dev/urandom | |
161 | .EE | |
162 | .in | |
2d444feb | 163 | .PP |
c13182ef | 164 | When a Linux system starts up without much operator interaction, |
fea681da | 165 | the entropy pool may be in a fairly predictable state. |
c13182ef MK |
166 | This reduces the actual amount of noise in the entropy pool |
167 | below the estimate. | |
168 | In order to counteract this effect, it helps to carry | |
169 | entropy pool information across shut-downs and start-ups. | |
3f4a2adb | 170 | To do this, add the lines to an appropriate script |
c13182ef | 171 | which is run during the Linux system start-up sequence: |
2d444feb | 172 | .PP |
9c40f2b9 MK |
173 | .in +4n |
174 | .EX | |
175 | echo "Initializing random number generator..." | |
176 | random_seed=/var/run/random-seed | |
177 | # Carry a random seed from start-up to start-up | |
178 | # Load and then save the whole entropy pool | |
179 | if [ \-f $random_seed ]; then | |
180 | cat $random_seed >/dev/urandom | |
181 | else | |
182 | touch $random_seed | |
183 | fi | |
184 | chmod 600 $random_seed | |
185 | poolfile=/proc/sys/kernel/random/poolsize | |
186 | [ \-r $poolfile ] && bits=$(cat $poolfile) || bits=4096 | |
187 | bytes=$(expr $bits / 8) | |
188 | dd if=/dev/urandom of=$random_seed count=1 bs=$bytes | |
189 | .EE | |
190 | .in | |
2d444feb | 191 | .PP |
c13182ef | 192 | Also, add the following lines in an appropriate script which is |
fea681da | 193 | run during the Linux system shutdown: |
2d444feb | 194 | .PP |
9c40f2b9 MK |
195 | .in +4n |
196 | .EX | |
197 | # Carry a random seed from shut-down to start-up | |
198 | # Save the whole entropy pool | |
199 | echo "Saving random seed..." | |
200 | random_seed=/var/run/random-seed | |
201 | touch $random_seed | |
202 | chmod 600 $random_seed | |
203 | poolfile=/proc/sys/kernel/random/poolsize | |
204 | [ \-r $poolfile ] && bits=$(cat $poolfile) || bits=4096 | |
205 | bytes=$(expr $bits / 8) | |
206 | dd if=/dev/urandom of=$random_seed count=1 bs=$bytes | |
207 | .EE | |
208 | .in | |
2d444feb | 209 | .PP |
3f4a2adb MK |
210 | In the above examples, we assume Linux 2.6.0 or later, where |
211 | .IR /proc/sys/kernel/random/poolsize | |
212 | returns the size of the entropy pool in bits (see below). | |
388ee0f4 MK |
213 | .\" |
214 | .SS /proc interfaces | |
fea681da MK |
215 | The files in the directory |
216 | .I /proc/sys/kernel/random | |
388ee0f4 | 217 | (present since 2.3.16) provide additional information about the |
8478ee02 | 218 | .I /dev/random |
388ee0f4 MK |
219 | device: |
220 | .TP | |
fea681da | 221 | .I entropy_avail |
05babf32 MK |
222 | This read-only file gives the available entropy, in bits. |
223 | This will be a number in the range 0 to 4096. | |
388ee0f4 | 224 | .TP |
fea681da | 225 | .I poolsize |
388ee0f4 | 226 | This file |
c13182ef | 227 | gives the size of the entropy pool. |
da84883c MK |
228 | The semantics of this file vary across kernel versions: |
229 | .RS | |
388ee0f4 | 230 | .TP |
da84883c MK |
231 | Linux 2.4: |
232 | This file gives the size of the entropy pool in | |
233 | .IR bytes . | |
234 | Normally, this file will have the value 512, but it is writable, | |
235 | and can be changed to any value for which an algorithm is available. | |
236 | The choices are 32, 64, 128, 256, 512, 1024, or 2048. | |
237 | .TP | |
0f1e6153 | 238 | Linux 2.6 and later: |
da84883c MK |
239 | This file is read-only, and gives the size of the entropy pool in |
240 | .IR bits . | |
241 | It contains the value 4096. | |
242 | .RE | |
388ee0f4 | 243 | .TP |
fea681da | 244 | .I read_wakeup_threshold |
388ee0f4 | 245 | This file |
fea681da MK |
246 | contains the number of bits of entropy required for waking up processes |
247 | that sleep waiting for entropy from | |
31e9a9ec | 248 | .IR /dev/random . |
fea681da | 249 | The default is 64. |
388ee0f4 | 250 | .TP |
fea681da | 251 | .I write_wakeup_threshold |
388ee0f4 | 252 | This file |
fea681da MK |
253 | contains the number of bits of entropy below which we wake up |
254 | processes that do a | |
5e21af3a | 255 | .BR select (2) |
fea681da | 256 | or |
5e21af3a | 257 | .BR poll (2) |
fea681da | 258 | for write access to |
31e9a9ec | 259 | .IR /dev/random . |
fea681da | 260 | These values can be changed by writing to the files. |
388ee0f4 MK |
261 | .TP |
262 | .IR uuid " and " boot_id | |
263 | These read-only files | |
fea681da MK |
264 | contain random strings like 6fd5a44b-35f4-4ad4-a9b9-6b9be13e1fe9. |
265 | The former is generated afresh for each read, the latter was | |
266 | generated once. | |
388ee0f4 | 267 | .\" |
5a933be0 EDB |
268 | .SS ioctl(2) interface |
269 | The following | |
270 | .BR ioctl (2) | |
271 | requests are defined on file descriptors connected to either \fI/dev/random\fP | |
ece967c9 MK |
272 | or \fI/dev/urandom\fP. |
273 | All requests performed will interact with the input | |
5a933be0 EDB |
274 | entropy pool impacting both \fI/dev/random\fP and \fI/dev/urandom\fP. |
275 | The | |
276 | .B CAP_SYS_ADMIN | |
277 | capability is required for all requests except | |
ece967c9 | 278 | .BR RNDGETENTCNT . |
5a933be0 EDB |
279 | .TP |
280 | .BR RNDGETENTCNT | |
281 | Retrieve the entropy count of the input pool, the contents will be the same | |
282 | as the | |
283 | .I entropy_avail | |
284 | file under proc. | |
285 | The result will be stored in the int pointed to by the argument. | |
286 | .TP | |
287 | .BR RNDADDTOENTCNT | |
ece967c9 MK |
288 | Increment or decrement the entropy count of the input pool |
289 | by the value pointed to by the argument. | |
5a933be0 EDB |
290 | .TP |
291 | .BR RNDGETPOOL | |
292 | Removed in Linux 2.6.9. | |
293 | .TP | |
294 | .BR RNDADDENTROPY | |
ece967c9 MK |
295 | Add some additional entropy to the input pool, |
296 | incrementing the entropy count. | |
297 | This differs from writing to \fI/dev/random\fP or \fI/dev/urandom\fP, | |
298 | which only adds some | |
299 | data but does not increment the entropy count. | |
300 | The following structure is used: | |
5a933be0 | 301 | .IP |
010c75a2 MK |
302 | .in +4n |
303 | .EX | |
304 | struct rand_pool_info { | |
305 | int entropy_count; | |
306 | int buf_size; | |
307 | __u32 buf[0]; | |
308 | }; | |
309 | .EE | |
310 | .in | |
5a933be0 EDB |
311 | .IP |
312 | Here | |
313 | .I entropy_count | |
988bd008 | 314 | is the value added to (or subtracted from) the entropy count, and |
5a933be0 EDB |
315 | .I buf |
316 | is the buffer of size | |
317 | .I buf_size | |
318 | which gets added to the entropy pool. | |
319 | .TP | |
320 | .BR RNDZAPENTCNT ", " RNDCLEARPOOL | |
321 | Zero the entropy count of all pools and add some system data (such as | |
322 | wall clock) to the pools. | |
f2910c72 | 323 | .SH FILES |
323e1feb | 324 | .I /dev/random |
f2910c72 | 325 | .br |
323e1feb | 326 | .I /dev/urandom |
379df7a0 MK |
327 | .SH NOTES |
328 | For an overview and comparison of the various interfaces that | |
329 | can be used to obtain randomness, see | |
330 | .BR random (7). | |
f64f220c | 331 | .SH BUGS |
debb291e | 332 | During early boot time, reads from |
f64f220c MK |
333 | .I /dev/urandom |
334 | may return data prior to the entropy pool being initialized. | |
dc919d09 MK |
335 | .\" .SH AUTHOR |
336 | .\" The kernel's random number generator was written by | |
337 | .\" Theodore Ts'o (tytso@athena.mit.edu). | |
47297adb | 338 | .SH SEE ALSO |
59732c2a | 339 | .BR mknod (1), |
379df7a0 MK |
340 | .BR getrandom (2), |
341 | .BR random (7) | |
2d444feb | 342 | .PP |
331da7c3 | 343 | RFC\ 1750, "Randomness Recommendations for Security" |