1 .\" Copyright (c) 1997 John S. Kallal (kallal@voicenet.com)
3 .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
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.
10 .\" Some changes by tytso and aeb.
12 .\" 2004-12-16, John V. Belmonte/mtk, Updated init and quit scripts
13 .\" 2004-04-08, AEB, Improved description of read from /dev/urandom
14 .\" 2008-06-20, George Spelvin <linux@horizon.com>,
15 .\" Matt Mackall <mpm@selenic.com>
16 .\" Add a Usage subsection that recommends most users to use
17 .\" /dev/urandom, and emphasizes parsimonious usage of /dev/random.
19 .TH RANDOM 4 2015-02-01 "Linux" "Linux Programmer's Manual"
21 random, urandom \- kernel random number source devices
23 #include <linux/random.h>
25 .BI "int ioctl(" fd ", RND" request ", " param ");"
27 The character special files \fI/dev/random\fP and
28 \fI/dev/urandom\fP (present since Linux 1.3.30)
29 provide an interface to the kernel's random number generator.
30 File \fI/dev/random\fP has major device number 1
31 and minor device number 8.
32 File \fI/dev/urandom\fP has major device number 1 and minor device number 9.
34 The random number generator gathers environmental noise
35 from device drivers and other sources into an entropy pool.
36 The generator also keeps an estimate of the
37 number of bits of noise in the entropy pool.
38 From this entropy pool random numbers are created.
40 When read, the \fI/dev/random\fP device will only return random bytes
41 within the estimated number of bits of noise in the entropy
43 \fI/dev/random\fP should be suitable for uses that need very
44 high quality randomness such as one-time pad or key generation.
45 When the entropy pool is empty, reads from \fI/dev/random\fP will block
46 until additional environmental noise is gathered.
55 will not block if the requested number of bytes is not available.
56 Instead, the available bytes are returned.
57 If no byte is available
64 A read from the \fI/dev/urandom\fP device will not block
65 waiting for more entropy.
66 If there is not sufficient entropy, a pseudorandom number generator is used
67 to create the requested bytes.
68 As a result, in this case the returned values are theoretically vulnerable to a
69 cryptographic attack on the algorithms used by the driver.
70 Knowledge of how to do this is not available in the current unclassified
71 literature, but it is theoretically possible that such an attack may
73 If this is a concern in your application, use \fI/dev/random\fP
76 has no effect when opening
82 signals will not be handled until after the requested random bytes
85 Writing to \fI/dev/random\fP or \fI/dev/urandom\fP will update the
86 entropy pool with the data written, but this will not result in a
88 This means that it will impact the contents
89 read from both files, but it will not make reads from
90 \fI/dev/random\fP faster.
92 If you are unsure about whether you should use
96 then probably you want to use the latter.
99 should be used for everything except long-lived GPG/SSL/SSH keys.
101 If a seed file is saved across reboots as recommended below (all major
102 Linux distributions have done this since 2000 at least), the output is
103 cryptographically secure against attackers without local root access as
104 soon as it is reloaded in the boot sequence, and perfectly adequate for
105 network encryption session keys.
108 may block, users will usually want to open it in nonblocking mode
109 (or perform a read with timeout),
110 and provide some sort of user notification if the desired
111 entropy is not immediately available.
113 The kernel random-number generator is designed to produce a small
114 amount of high-quality seed material to seed a
115 cryptographic pseudo-random number generator (CPRNG).
116 It is designed for security, not speed, and is poorly
117 suited to generating large amounts of random data.
118 Users should be very economical in the amount of seed
119 material that they read from
123 unnecessarily reading large quantities of data from this device will have
124 a negative impact on other users of the device.
126 The amount of seed material required to generate a cryptographic key
127 equals the effective key size of the key.
128 For example, a 3072-bit RSA
129 or Diffie-Hellman private key has an effective key size of 128 bits
130 (it requires about 2^128 operations to break) so a key generator only
131 needs 128 bits (16 bytes) of seed material from
134 While some safety margin above that minimum is reasonable, as a guard
135 against flaws in the CPRNG algorithm, no cryptographic primitive
136 available today can hope to promise more than 256 bits of security,
137 so if any program reads more than 256 bits (32 bytes) from the kernel
138 random pool per invocation, or per reasonable reseed interval (not less
139 than one minute), that should be taken as a sign that its cryptography is
141 skillfully implemented.
143 If your system does not have
144 \fI/dev/random\fP and \fI/dev/urandom\fP created already, they
145 can be created with the following commands:
148 mknod \-m 644 /dev/random c 1 8
149 mknod \-m 644 /dev/urandom c 1 9
150 chown root:root /dev/random /dev/urandom
153 When a Linux system starts up without much operator interaction,
154 the entropy pool may be in a fairly predictable state.
155 This reduces the actual amount of noise in the entropy pool
157 In order to counteract this effect, it helps to carry
158 entropy pool information across shut-downs and start-ups.
159 To do this, add the following lines to an appropriate script
160 which is run during the Linux system start-up sequence:
163 echo "Initializing random number generator..."
164 random_seed=/var/run/random-seed
165 # Carry a random seed from start-up to start-up
166 # Load and then save the whole entropy pool
167 if [ \-f $random_seed ]; then
168 cat $random_seed >/dev/urandom
172 chmod 600 $random_seed
173 poolfile=/proc/sys/kernel/random/poolsize
174 [ \-r $poolfile ] && bytes=\`cat $poolfile\` || bytes=512
175 dd if=/dev/urandom of=$random_seed count=1 bs=$bytes
178 Also, add the following lines in an appropriate script which is
179 run during the Linux system shutdown:
182 # Carry a random seed from shut-down to start-up
183 # Save the whole entropy pool
184 echo "Saving random seed..."
185 random_seed=/var/run/random-seed
187 chmod 600 $random_seed
188 poolfile=/proc/sys/kernel/random/poolsize
189 [ \-r $poolfile ] && bytes=\`cat $poolfile\` || bytes=512
190 dd if=/dev/urandom of=$random_seed count=1 bs=$bytes
193 The files in the directory
194 .I /proc/sys/kernel/random
195 (present since 2.3.16) provide an additional interface to the
201 gives the available entropy.
202 Normally, this will be 4096 (bits),
207 gives the size of the entropy pool.
208 The semantics of this file vary across kernel versions:
212 This file gives the size of the entropy pool in
214 Normally, this file will have the value 512, but it is writable,
215 and can be changed to any value for which an algorithm is available.
216 The choices are 32, 64, 128, 256, 512, 1024, or 2048.
219 This file is read-only, and gives the size of the entropy pool in
221 It contains the value 4096.
225 .I read_wakeup_threshold
226 contains the number of bits of entropy required for waking up processes
227 that sleep waiting for entropy from
231 .I write_wakeup_threshold
232 contains the number of bits of entropy below which we wake up
239 These values can be changed by writing to the files.
245 contain random strings like 6fd5a44b-35f4-4ad4-a9b9-6b9be13e1fe9.
246 The former is generated afresh for each read, the latter was
248 .SS ioctl(2) interface
251 requests are defined on file descriptors connected to either \fI/dev/random\fP
252 or \fI/dev/urandom\fP.
253 All requests performed will interact with the input
254 entropy pool impacting both \fI/dev/random\fP and \fI/dev/urandom\fP.
257 capability is required for all requests except
261 Retrieve the entropy count of the input pool, the contents will be the same
265 The result will be stored in the int pointed to by the argument.
268 Increment or decrement the entropy count of the input pool
269 by the value pointed to by the argument.
272 Removed in Linux 2.6.9.
275 Add some additional entropy to the input pool,
276 incrementing the entropy count.
277 This differs from writing to \fI/dev/random\fP or \fI/dev/urandom\fP,
279 data but does not increment the entropy count.
280 The following structure is used:
283 struct rand_pool_info {
292 is the value added to (or subtracted from) the entropy count, and
294 is the buffer of size
296 which gets added to the entropy pool.
298 .BR RNDZAPENTCNT ", " RNDCLEARPOOL
299 Zero the entropy count of all pools and add some system data (such as
300 wall clock) to the pools.
306 .\" The kernel's random number generator was written by
307 .\" Theodore Ts'o (tytso@athena.mit.edu).
312 RFC\ 1750, "Randomness Recommendations for Security"
314 This page is part of release 3.79 of the Linux
317 A description of the project,
318 information about reporting bugs,
319 and the latest version of this page,
321 \%http://www.kernel.org/doc/man\-pages/.