| 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" |