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. The file /dev/random has major device number 1 and minor device
17 number 8. The file /dev/urandom has major device number 1 and minor
18 device 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 Linux 3.17 and later provides the simpler and safer getrandom(2) inter‐
26 face which requires no special files; see the getrandom(2) manual page
27 for details.
28 When read, the /dev/urandom device returns random bytes using a pseudo‐
30 random number generator seeded from the entropy pool. Reads from this
31 device do not block (i.e., the CPU is not yielded), but can incur an
32 appreciable delay when requesting large amounts of data.
33 When read during early boot time, /dev/urandom may return data prior to
35 the entropy pool being initialized. If this is of concern in your
36 application, use getrandom(2) or /dev/random instead.
37 The /dev/random device is a legacy interface which dates back to a time
39 where the cryptographic primitives used in the implementation of
40 /dev/urandom were not widely trusted. It will return random bytes only
41 within the estimated number of bits of fresh noise in the entropy pool,
42 blocking if necessary. /dev/random is suitable for applications that
43 need high quality randomness, and can afford indeterminate delays.
44 When the entropy pool is empty, reads from /dev/random will block until
46 additional environmental noise is gathered. If open(2) is called for
47 /dev/random with the O_NONBLOCK flag, a subsequent read(2) will not
48 block if the requested number of bytes is not available. Instead, the
49 available bytes are returned. If no byte is available, read(2) will
50 return -1 and errno will be set to EAGAIN.
51 The O_NONBLOCK flag has no effect when opening /dev/urandom. When
53 calling read(2) for the device /dev/urandom, reads of up to 256 bytes
54 will return as many bytes as are requested and will not be interrupted
55 by a signal handler. Reads with a buffer over this limit may return
56 less than the requested number of bytes or fail with the error EINTR,
57 if interrupted by a signal handler.
58 Since Linux 3.16, a read(2) from /dev/urandom will return at most
60 32 MB. A read(2) from /dev/random will return at most 512 bytes (340
61 bytes on Linux kernels before version 2.6.12).
62 Writing to /dev/random or /dev/urandom will update the entropy pool
64 with the data written, but this will not result in a higher entropy
65 count. This means that it will impact the contents read from both
66 files, but it will not make reads from /dev/random faster.
67 Usage
69 The /dev/random interface is considered a legacy interface, and
70 /dev/urandom is preferred and sufficient in all use cases, with the
71 exception of applications which require randomness during early boot
72 time; for these applications, getrandom(2) must be used instead,
73 because it will block until the entropy pool is initialized.
74 If a seed file is saved across reboots as recommended below (all major
76 Linux distributions have done this since 2000 at least), the output is
77 cryptographically secure against attackers without local root access as
78 soon as it is reloaded in the boot sequence, and perfectly adequate for
79 network encryption session keys. Since reads from /dev/random may
80 block, users will usually want to open it in nonblocking mode (or per‐
81 form a read with timeout), and provide some sort of user notification
82 if the desired entropy is not immediately available.
83 Configuration
85 If your system does not have /dev/random and /dev/urandom created
86 already, they can be created with the following commands:
87 mknod -m 666 /dev/random c 1 8
89 mknod -m 666 /dev/urandom c 1 9
90 chown root:root /dev/random /dev/urandom
91 When a Linux system starts up without much operator interaction, the
93 entropy pool may be in a fairly predictable state. This reduces the
94 actual amount of noise in the entropy pool below the estimate. In
95 order to counteract this effect, it helps to carry entropy pool infor‐
96 mation across shut-downs and start-ups. To do this, add the lines to
97 an appropriate script which is run during the Linux system start-up
98 sequence:
99 echo "Initializing random number generator..."
101 random_seed=/var/run/random-seed
102 # Carry a random seed from start-up to start-up
103 # Load and then save the whole entropy pool
104 if [ -f $random_seed ]; then
105 cat $random_seed >/dev/urandom
106 else
107 touch $random_seed
108 fi
109 chmod 600 $random_seed
110 poolfile=/proc/sys/kernel/random/poolsize
111 [ -r $poolfile ] && bits=$(cat $poolfile) || bits=4096
112 bytes=$(expr $bits / 8)
113 dd if=/dev/urandom of=$random_seed count=1 bs=$bytes
114 Also, add the following lines in an appropriate script which is run
116 during the Linux system shutdown:
117 # Carry a random seed from shut-down to start-up
119 # Save the whole entropy pool
120 echo "Saving random seed..."
121 random_seed=/var/run/random-seed
122 touch $random_seed
123 chmod 600 $random_seed
124 poolfile=/proc/sys/kernel/random/poolsize
125 [ -r $poolfile ] && bits=$(cat $poolfile) || bits=4096
126 bytes=$(expr $bits / 8)
127 dd if=/dev/urandom of=$random_seed count=1 bs=$bytes
128 In the above examples, we assume Linux 2.6.0 or later, where
130 /proc/sys/kernel/random/poolsize returns the size of the entropy pool
131 in bits (see below).
132 /proc interfaces
134 The files in the directory /proc/sys/kernel/random (present since
135 2.3.16) provide additional information about the /dev/random device:
136 entropy_avail
138 This read-only file gives the available entropy, in bits. This
139 will be a number in the range 0 to 4096.
140 poolsize
142 This file gives the size of the entropy pool. The semantics of
143 this file vary across kernel versions:
144 Linux 2.4:
146 This file gives the size of the entropy pool in bytes.
147 Normally, this file will have the value 512, but it is
148 writable, and can be changed to any value for which an
149 algorithm is available. The choices are 32, 64, 128,
150 256, 512, 1024, or 2048.
151 Linux 2.6 and later:
153 This file is read-only, and gives the size of the entropy
154 pool in bits. It contains the value 4096.
155 read_wakeup_threshold
157 This file contains the number of bits of entropy required for
158 waking up processes that sleep waiting for entropy from
159 /dev/random. The default is 64.
160 write_wakeup_threshold
162 This file contains the number of bits of entropy below which we
163 wake up processes that do a select(2) or poll(2) for write
164 access to /dev/random. These values can be changed by writing
165 to the files.
166 uuid and boot_id
168 These read-only files contain random strings like
169 6fd5a44b-35f4-4ad4-a9b9-6b9be13e1fe9. The former is generated
170 afresh for each read, the latter was generated once.
171 ioctl(2) interface
173 The following ioctl(2) requests are defined on file descriptors con‐
174 nected to either /dev/random or /dev/urandom. All requests performed
175 will interact with the input entropy pool impacting both /dev/random
176 and /dev/urandom. The CAP_SYS_ADMIN capability is required for all
177 requests except RNDGETENTCNT.
178 RNDGETENTCNT
180 Retrieve the entropy count of the input pool, the contents will
181 be the same as the entropy_avail file under proc. The result
182 will be stored in the int pointed to by the argument.
183 RNDADDTOENTCNT
185 Increment or decrement the entropy count of the input pool by
186 the value pointed to by the argument.
187 RNDGETPOOL
189 Removed in Linux 2.6.9.
190 RNDADDENTROPY
192 Add some additional entropy to the input pool, incrementing the
193 entropy count. This differs from writing to /dev/random or
194 /dev/urandom, which only adds some data but does not increment
195 the entropy count. The following structure is used:
196 struct rand_pool_info {
198 int entropy_count;
199 int buf_size;
200 __u32 buf[0];
201 };
202 Here entropy_count is the value added to (or subtracted from)
204 the entropy count, and buf is the buffer of size buf_size which
205 gets added to the entropy pool.
206 RNDZAPENTCNT, RNDCLEARPOOL
208 Zero the entropy count of all pools and add some system data
209 (such as wall clock) to the pools.
210
212 /dev/random
213 /dev/urandom
214
216 For an overview and comparison of the various interfaces that can be
217 used to obtain randomness, see random(7).
218
220 During early boot time, reads from /dev/urandom may return data prior
221 to the entropy pool being initialized.
222
224 mknod(1), getrandom(2), random(7)
225 RFC 1750, "Randomness Recommendations for Security"
227
229 This page is part of release 5.02 of the Linux man-pages project. A
230 description of the project, information about reporting bugs, and the
231 latest version of this page, can be found at
232 https://www.kernel.org/doc/man-pages/.
233Linux 2017-09-15 RANDOM(4)