]>
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 | .\" |
45186a5d | 12 | .TH RANDOM 4 2021-03-22 "Linux man-pages (unreleased)" |
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. |
4e8e3916 GZ |
71 | Since Linux 5.6, the |
72 | .B O_NONBLOCK | |
73 | flag is ignored as | |
74 | .I /dev/random | |
75 | will no longer block except during early boot process. | |
226cd95d | 76 | In earlier versions, if |
17344691 HS |
77 | .BR open (2) |
78 | is called for | |
79 | .I /dev/random | |
724d21bb | 80 | with the |
1ae6b2c7 | 81 | .B O_NONBLOCK |
724d21bb | 82 | flag, a subsequent |
17344691 HS |
83 | .BR read (2) |
84 | will not block if the requested number of bytes is not available. | |
e8cc3c09 | 85 | Instead, the available bytes are returned. |
792bb5ad | 86 | If no byte is available, |
17344691 | 87 | .BR read (2) |
0a23e9aa | 88 | will return \-1 and |
17344691 HS |
89 | .I errno |
90 | will be set to | |
91 | .BR EAGAIN . | |
2d444feb | 92 | .PP |
724d21bb | 93 | The |
17344691 | 94 | .B O_NONBLOCK |
724d21bb | 95 | flag has no effect when opening |
17344691 HS |
96 | .IR /dev/urandom . |
97 | When calling | |
98 | .BR read (2) | |
792bb5ad MK |
99 | for the device |
100 | .IR /dev/urandom , | |
dbf63eed MK |
101 | reads of up to 256 bytes will return as many bytes as are requested |
102 | and will not be interrupted by a signal handler. | |
103 | Reads with a buffer over this limit may return less than the | |
104 | requested number of bytes or fail with the error | |
4818990d MK |
105 | .BR EINTR , |
106 | if interrupted by a signal handler. | |
2d444feb | 107 | .PP |
866fa681 MK |
108 | Since Linux 3.16, |
109 | .\" commit 79a8468747c5f95ed3d5ce8376a3e82e0c5857fc | |
110 | a | |
111 | .BR read (2) | |
112 | from | |
1ae6b2c7 | 113 | .I /dev/urandom |
c4b7e5ac | 114 | will return at most 32\ MB. |
44da0e24 MK |
115 | A |
116 | .BR read (2) | |
117 | from | |
1ae6b2c7 | 118 | .I /dev/random |
44da0e24 MK |
119 | will return at most 512 bytes |
120 | .\" SEC_XFER_SIZE in drivers/char/random.c | |
121 | (340 bytes on Linux kernels before version 2.6.12). | |
2d444feb | 122 | .PP |
5a933be0 EDB |
123 | Writing to \fI/dev/random\fP or \fI/dev/urandom\fP will update the |
124 | entropy pool with the data written, but this will not result in a | |
ece967c9 MK |
125 | higher entropy count. |
126 | This means that it will impact the contents | |
127 | read from both files, but it will not make reads from | |
5a933be0 | 128 | \fI/dev/random\fP faster. |
9ed0f081 | 129 | .SS Usage |
67b7fcba | 130 | The |
1ae6b2c7 | 131 | .I /dev/random |
67b7fcba | 132 | interface is considered a legacy interface, and |
1ae6b2c7 | 133 | .I /dev/urandom |
67b7fcba NM |
134 | is preferred and sufficient in all use cases, with the exception of |
135 | applications which require randomness during early boot time; for | |
f64f220c MK |
136 | these applications, |
137 | .BR getrandom (2) | |
138 | must be used instead, | |
139 | because it will block until the entropy pool is initialized. | |
2d444feb | 140 | .PP |
136b7eaf MK |
141 | If a seed file is saved across reboots as recommended below, |
142 | the output is | |
9ed0f081 MK |
143 | cryptographically secure against attackers without local root access as |
144 | soon as it is reloaded in the boot sequence, and perfectly adequate for | |
145 | network encryption session keys. | |
136b7eaf MK |
146 | (All major Linux distributions have saved the seed file across reboots |
147 | since 2000 at least.) | |
e7dfa844 | 148 | Since reads from |
9ed0f081 | 149 | .I /dev/random |
ff40dbb3 | 150 | may block, users will usually want to open it in nonblocking mode |
e7dfa844 MK |
151 | (or perform a read with timeout), |
152 | and provide some sort of user notification if the desired | |
9ed0f081 | 153 | entropy is not immediately available. |
2e1f8bfa | 154 | .\" |
8eb40c9c | 155 | .SS Configuration |
fea681da | 156 | If your system does not have |
c13182ef | 157 | \fI/dev/random\fP and \fI/dev/urandom\fP created already, they |
fea681da | 158 | can be created with the following commands: |
2d444feb | 159 | .PP |
9c40f2b9 MK |
160 | .in +4n |
161 | .EX | |
162 | mknod \-m 666 /dev/random c 1 8 | |
163 | mknod \-m 666 /dev/urandom c 1 9 | |
164 | chown root:root /dev/random /dev/urandom | |
165 | .EE | |
166 | .in | |
2d444feb | 167 | .PP |
c13182ef | 168 | When a Linux system starts up without much operator interaction, |
fea681da | 169 | the entropy pool may be in a fairly predictable state. |
c13182ef MK |
170 | This reduces the actual amount of noise in the entropy pool |
171 | below the estimate. | |
172 | In order to counteract this effect, it helps to carry | |
173 | entropy pool information across shut-downs and start-ups. | |
3f4a2adb | 174 | To do this, add the lines to an appropriate script |
c13182ef | 175 | which is run during the Linux system start-up sequence: |
2d444feb | 176 | .PP |
9c40f2b9 MK |
177 | .in +4n |
178 | .EX | |
179 | echo "Initializing random number generator..." | |
d064d41a MK |
180 | random_seed=/var/run/random\-seed |
181 | # Carry a random seed from start\-up to start\-up | |
9c40f2b9 MK |
182 | # Load and then save the whole entropy pool |
183 | if [ \-f $random_seed ]; then | |
184 | cat $random_seed >/dev/urandom | |
185 | else | |
186 | touch $random_seed | |
187 | fi | |
188 | chmod 600 $random_seed | |
189 | poolfile=/proc/sys/kernel/random/poolsize | |
190 | [ \-r $poolfile ] && bits=$(cat $poolfile) || bits=4096 | |
191 | bytes=$(expr $bits / 8) | |
192 | dd if=/dev/urandom of=$random_seed count=1 bs=$bytes | |
193 | .EE | |
194 | .in | |
2d444feb | 195 | .PP |
c13182ef | 196 | Also, add the following lines in an appropriate script which is |
fea681da | 197 | run during the Linux system shutdown: |
2d444feb | 198 | .PP |
9c40f2b9 MK |
199 | .in +4n |
200 | .EX | |
d064d41a | 201 | # Carry a random seed from shut\-down to start\-up |
9c40f2b9 MK |
202 | # Save the whole entropy pool |
203 | echo "Saving random seed..." | |
d064d41a | 204 | random_seed=/var/run/random\-seed |
9c40f2b9 MK |
205 | touch $random_seed |
206 | chmod 600 $random_seed | |
207 | poolfile=/proc/sys/kernel/random/poolsize | |
208 | [ \-r $poolfile ] && bits=$(cat $poolfile) || bits=4096 | |
209 | bytes=$(expr $bits / 8) | |
210 | dd if=/dev/urandom of=$random_seed count=1 bs=$bytes | |
211 | .EE | |
212 | .in | |
2d444feb | 213 | .PP |
3f4a2adb | 214 | In the above examples, we assume Linux 2.6.0 or later, where |
1ae6b2c7 | 215 | .I /proc/sys/kernel/random/poolsize |
3f4a2adb | 216 | returns the size of the entropy pool in bits (see below). |
388ee0f4 MK |
217 | .\" |
218 | .SS /proc interfaces | |
fea681da MK |
219 | The files in the directory |
220 | .I /proc/sys/kernel/random | |
388ee0f4 | 221 | (present since 2.3.16) provide additional information about the |
8478ee02 | 222 | .I /dev/random |
388ee0f4 MK |
223 | device: |
224 | .TP | |
fea681da | 225 | .I entropy_avail |
05babf32 MK |
226 | This read-only file gives the available entropy, in bits. |
227 | This will be a number in the range 0 to 4096. | |
388ee0f4 | 228 | .TP |
fea681da | 229 | .I poolsize |
388ee0f4 | 230 | This file |
c13182ef | 231 | gives the size of the entropy pool. |
da84883c MK |
232 | The semantics of this file vary across kernel versions: |
233 | .RS | |
388ee0f4 | 234 | .TP |
da84883c MK |
235 | Linux 2.4: |
236 | This file gives the size of the entropy pool in | |
237 | .IR bytes . | |
238 | Normally, this file will have the value 512, but it is writable, | |
239 | and can be changed to any value for which an algorithm is available. | |
240 | The choices are 32, 64, 128, 256, 512, 1024, or 2048. | |
241 | .TP | |
0f1e6153 | 242 | Linux 2.6 and later: |
da84883c MK |
243 | This file is read-only, and gives the size of the entropy pool in |
244 | .IR bits . | |
245 | It contains the value 4096. | |
246 | .RE | |
388ee0f4 | 247 | .TP |
fea681da | 248 | .I read_wakeup_threshold |
388ee0f4 | 249 | This file |
fea681da MK |
250 | contains the number of bits of entropy required for waking up processes |
251 | that sleep waiting for entropy from | |
31e9a9ec | 252 | .IR /dev/random . |
fea681da | 253 | The default is 64. |
388ee0f4 | 254 | .TP |
fea681da | 255 | .I write_wakeup_threshold |
388ee0f4 | 256 | This file |
fea681da MK |
257 | contains the number of bits of entropy below which we wake up |
258 | processes that do a | |
5e21af3a | 259 | .BR select (2) |
fea681da | 260 | or |
5e21af3a | 261 | .BR poll (2) |
fea681da | 262 | for write access to |
31e9a9ec | 263 | .IR /dev/random . |
fea681da | 264 | These values can be changed by writing to the files. |
388ee0f4 MK |
265 | .TP |
266 | .IR uuid " and " boot_id | |
267 | These read-only files | |
fea681da MK |
268 | contain random strings like 6fd5a44b-35f4-4ad4-a9b9-6b9be13e1fe9. |
269 | The former is generated afresh for each read, the latter was | |
270 | generated once. | |
388ee0f4 | 271 | .\" |
5a933be0 EDB |
272 | .SS ioctl(2) interface |
273 | The following | |
274 | .BR ioctl (2) | |
275 | requests are defined on file descriptors connected to either \fI/dev/random\fP | |
ece967c9 MK |
276 | or \fI/dev/urandom\fP. |
277 | All requests performed will interact with the input | |
5a933be0 EDB |
278 | entropy pool impacting both \fI/dev/random\fP and \fI/dev/urandom\fP. |
279 | The | |
280 | .B CAP_SYS_ADMIN | |
281 | capability is required for all requests except | |
ece967c9 | 282 | .BR RNDGETENTCNT . |
5a933be0 | 283 | .TP |
1ae6b2c7 | 284 | .B RNDGETENTCNT |
5a933be0 EDB |
285 | Retrieve the entropy count of the input pool, the contents will be the same |
286 | as the | |
287 | .I entropy_avail | |
288 | file under proc. | |
289 | The result will be stored in the int pointed to by the argument. | |
290 | .TP | |
1ae6b2c7 | 291 | .B RNDADDTOENTCNT |
ece967c9 MK |
292 | Increment or decrement the entropy count of the input pool |
293 | by the value pointed to by the argument. | |
5a933be0 | 294 | .TP |
1ae6b2c7 | 295 | .B RNDGETPOOL |
5a933be0 EDB |
296 | Removed in Linux 2.6.9. |
297 | .TP | |
1ae6b2c7 | 298 | .B RNDADDENTROPY |
ece967c9 MK |
299 | Add some additional entropy to the input pool, |
300 | incrementing the entropy count. | |
301 | This differs from writing to \fI/dev/random\fP or \fI/dev/urandom\fP, | |
302 | which only adds some | |
303 | data but does not increment the entropy count. | |
304 | The following structure is used: | |
5a933be0 | 305 | .IP |
010c75a2 MK |
306 | .in +4n |
307 | .EX | |
308 | struct rand_pool_info { | |
309 | int entropy_count; | |
310 | int buf_size; | |
311 | __u32 buf[0]; | |
312 | }; | |
313 | .EE | |
314 | .in | |
5a933be0 EDB |
315 | .IP |
316 | Here | |
317 | .I entropy_count | |
988bd008 | 318 | is the value added to (or subtracted from) the entropy count, and |
5a933be0 EDB |
319 | .I buf |
320 | is the buffer of size | |
321 | .I buf_size | |
322 | which gets added to the entropy pool. | |
323 | .TP | |
324 | .BR RNDZAPENTCNT ", " RNDCLEARPOOL | |
325 | Zero the entropy count of all pools and add some system data (such as | |
326 | wall clock) to the pools. | |
f2910c72 | 327 | .SH FILES |
323e1feb | 328 | .I /dev/random |
f2910c72 | 329 | .br |
323e1feb | 330 | .I /dev/urandom |
379df7a0 MK |
331 | .SH NOTES |
332 | For an overview and comparison of the various interfaces that | |
333 | can be used to obtain randomness, see | |
334 | .BR random (7). | |
f64f220c | 335 | .SH BUGS |
debb291e | 336 | During early boot time, reads from |
f64f220c MK |
337 | .I /dev/urandom |
338 | may return data prior to the entropy pool being initialized. | |
dc919d09 MK |
339 | .\" .SH AUTHOR |
340 | .\" The kernel's random number generator was written by | |
341 | .\" Theodore Ts'o (tytso@athena.mit.edu). | |
47297adb | 342 | .SH SEE ALSO |
59732c2a | 343 | .BR mknod (1), |
379df7a0 MK |
344 | .BR getrandom (2), |
345 | .BR random (7) | |
2d444feb | 346 | .PP |
331da7c3 | 347 | RFC\ 1750, "Randomness Recommendations for Security" |