1RANDOM(4) Linux Programmer's Manual RANDOM(4)
2
6 random, urandom - kernel random number source devices
7
9 #include <linux/random.h>
10 int ioctl(fd, RNDrequest, param);
12
14 The character special files /dev/random and /dev/urandom (present since
15 Linux 1.3.30) provide an interface to the kernel's random number gener‐
16 ator. File /dev/random has major device number 1 and minor device num‐
17 ber 8. File /dev/urandom has major device number 1 and minor device
18 number 9.
19 The random number generator gathers environmental noise from device
21 drivers and other sources into an entropy pool. The generator also
22 keeps an estimate of the number of bits of noise in the entropy pool.
23 From this entropy pool random numbers are created.
24 When read, the /dev/random device will only return random bytes within
26 the estimated number of bits of noise in the entropy pool. /dev/random
27 should be suitable for uses that need very high quality randomness such
28 as one-time pad or key generation. When the entropy pool is empty,
29 reads from /dev/random will block until additional environmental noise
30 is gathered.
31 A read from the /dev/urandom device will not block waiting for more
33 entropy. As a result, if there is not sufficient entropy in the
34 entropy pool, the returned values are theoretically vulnerable to a
35 cryptographic attack on the algorithms used by the driver. Knowledge
36 of how to do this is not available in the current unclassified litera‐
37 ture, but it is theoretically possible that such an attack may exist.
38 If this is a concern in your application, use /dev/random instead.
39 Writing to /dev/random or /dev/urandom will update the entropy pool
41 with the data written, but this will not result in a higher entropy
42 count. This means that it will impact the contents read from both
43 files, but it will not make reads from /dev/random faster.
44 Usage
46 If you are unsure about whether you should use /dev/random or
47 /dev/urandom, then probably you want to use the latter. As a general
48 rule, /dev/urandom should be used for everything except long-lived
49 GPG/SSL/SSH keys.
50 If a seed file is saved across reboots as recommended below (all major
52 Linux distributions have done this since 2000 at least), the output is
53 cryptographically secure against attackers without local root access as
54 soon as it is reloaded in the boot sequence, and perfectly adequate for
55 network encryption session keys. Since reads from /dev/random may
56 block, users will usually want to open it in nonblocking mode (or per‐
57 form a read with timeout), and provide some sort of user notification
58 if the desired entropy is not immediately available.
59 The kernel random-number generator is designed to produce a small
61 amount of high-quality seed material to seed a cryptographic pseudo-
62 random number generator (CPRNG). It is designed for security, not
63 speed, and is poorly suited to generating large amounts of random data.
64 Users should be very economical in the amount of seed material that
65 they read from /dev/urandom (and /dev/random); unnecessarily reading
66 large quantities of data from this device will have a negative impact
67 on other users of the device.
68 The amount of seed material required to generate a cryptographic key
70 equals the effective key size of the key. For example, a 3072-bit RSA
71 or Diffie-Hellman private key has an effective key size of 128 bits (it
72 requires about 2^128 operations to break) so a key generator only needs
73 128 bits (16 bytes) of seed material from /dev/random.
74 While some safety margin above that minimum is reasonable, as a guard
76 against flaws in the CPRNG algorithm, no cryptographic primitive avail‐
77 able today can hope to promise more than 256 bits of security, so if
78 any program reads more than 256 bits (32 bytes) from the kernel random
79 pool per invocation, or per reasonable reseed interval (not less than
80 one minute), that should be taken as a sign that its cryptography is
81 not skillfully implemented.
82 Configuration
84 If your system does not have /dev/random and /dev/urandom created
85 already, they can be created with the following commands:
86 mknod -m 644 /dev/random c 1 8
88 mknod -m 644 /dev/urandom c 1 9
89 chown root:root /dev/random /dev/urandom
90 When a Linux system starts up without much operator interaction, the
92 entropy pool may be in a fairly predictable state. This reduces the
93 actual amount of noise in the entropy pool below the estimate. In
94 order to counteract this effect, it helps to carry entropy pool infor‐
95 mation across shut-downs and start-ups. To do this, add the following
96 lines to an appropriate script which is run during the Linux system
97 start-up sequence:
98 echo "Initializing random number generator..."
100 random_seed=/var/run/random-seed
101 # Carry a random seed from start-up to start-up
102 # Load and then save the whole entropy pool
103 if [ -f $random_seed ]; then
104 cat $random_seed >/dev/urandom
105 else
106 touch $random_seed
107 fi
108 chmod 600 $random_seed
109 poolfile=/proc/sys/kernel/random/poolsize
110 [ -r $poolfile ] && bytes=`cat $poolfile` || bytes=512
111 dd if=/dev/urandom of=$random_seed count=1 bs=$bytes
112 Also, add the following lines in an appropriate script which is run
114 during the Linux system shutdown:
115 # Carry a random seed from shut-down to start-up
117 # Save the whole entropy pool
118 echo "Saving random seed..."
119 random_seed=/var/run/random-seed
120 touch $random_seed
121 chmod 600 $random_seed
122 poolfile=/proc/sys/kernel/random/poolsize
123 [ -r $poolfile ] && bytes=`cat $poolfile` || bytes=512
124 dd if=/dev/urandom of=$random_seed count=1 bs=$bytes
125 /proc Interface
127 The files in the directory /proc/sys/kernel/random (present since
128 2.3.16) provide an additional interface to the /dev/random device.
129 The read-only file entropy_avail gives the available entropy. Nor‐
131 mally, this will be 4096 (bits), a full entropy pool.
132 The file poolsize gives the size of the entropy pool. The semantics of
134 this file vary across kernel versions:
135 Linux 2.4: This file gives the size of the entropy pool in
137 bytes. Normally, this file will have the value 512,
138 but it is writable, and can be changed to any value
139 for which an algorithm is available. The choices
140 are 32, 64, 128, 256, 512, 1024, or 2048.
141 Linux 2.6: This file is read-only, and gives the size of the
143 entropy pool in bits. It contains the value 4096.
144 The file read_wakeup_threshold contains the number of bits of entropy
146 required for waking up processes that sleep waiting for entropy from
147 /dev/random. The default is 64. The file write_wakeup_threshold con‐
148 tains the number of bits of entropy below which we wake up processes
149 that do a select(2) or poll(2) for write access to /dev/random. These
150 values can be changed by writing to the files.
151 The read-only files uuid and boot_id contain random strings like
153 6fd5a44b-35f4-4ad4-a9b9-6b9be13e1fe9. The former is generated afresh
154 for each read, the latter was generated once.
155 ioctl(2) interface
157 The following ioctl(2) requests are defined on file descriptors con‐
158 nected to either /dev/random or /dev/urandom. All requests performed
159 will interact with the input entropy pool impacting both /dev/random
160 and /dev/urandom. The CAP_SYS_ADMIN capability is required for all
161 requests except RNDGETENTCNT.
162 RNDGETENTCNT
164 Retrieve the entropy count of the input pool, the contents will
165 be the same as the entropy_avail file under proc. The result
166 will be stored in the int pointed to by the argument.
167 RNDADDTOENTCNT
169 Increment or decrement the entropy count of the input pool by
170 the value pointed to by the argument.
171 RNDGETPOOL
173 Removed in Linux 2.6.9.
174 RNDADDENTROPY
176 Add some additional entropy to the input pool, incrementing the
177 entropy count. This differs from writing to /dev/random or
178 /dev/urandom, which only adds some data but does not increment
179 the entropy count. The following structure is used:
180 struct rand_pool_info {
182 int entropy_count;
183 int buf_size;
184 __u32 buf[0];
185 };
186 Here entropy_count is the value added to (or subtracted from)
188 the entropy count, and buf is the buffer of size buf_size which
189 gets added to the entropy pool.
190 RNDZAPENTCNT, RNDCLEARPOOL
192 Zero the entropy count of all pools and add some system data
193 (such as wall clock) to the pools.
194
196 /dev/random
197 /dev/urandom
198
200 mknod(1)
201 RFC 1750, "Randomness Recommendations for Security"
202
204 This page is part of release 3.53 of the Linux man-pages project. A
205 description of the project, and information about reporting bugs, can
206 be found at http://www.kernel.org/doc/man-pages/.
207Linux 2013-03-15 RANDOM(4)