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