Debian Codegraph @

upstream/debian-unstable/man4/random.4

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