| .\" Copyright (c) 1997 John S. Kallal (kallal@voicenet.com) |
| .\" |
| .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) |
| .\" This is free documentation; you can redistribute it and/or |
| .\" modify it under the terms of the GNU General Public License as |
| .\" published by the Free Software Foundation; either version 2 of |
| .\" the License, or (at your option) any later version. |
| .\" %%%LICENSE_END |
| .\" |
| .\" Some changes by tytso and aeb. |
| .\" |
| .\" 2004-12-16, John V. Belmonte/mtk, Updated init and quit scripts |
| .\" 2004-04-08, AEB, Improved description of read from /dev/urandom |
| .\" 2008-06-20, George Spelvin <linux@horizon.com>, |
| .\" Matt Mackall <mpm@selenic.com> |
| .\" |
| .TH RANDOM 4 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| random, urandom \- kernel random number source devices |
| .SH SYNOPSIS |
| .nf |
| #include <linux/random.h> |
| .PP |
| .BI "int ioctl(" fd ", RND" request ", " param ");" |
| .fi |
| .SH DESCRIPTION |
| The character special files \fI/dev/random\fP and |
| \fI/dev/urandom\fP (present since Linux 1.3.30) |
| provide an interface to the kernel's random number generator. |
| The file |
| .I /dev/random |
| has major device number 1 and minor device number 8. |
| The file |
| .I /dev/urandom |
| has major device number 1 and minor device number 9. |
| .PP |
| The random number generator gathers environmental noise |
| from device drivers and other sources into an entropy pool. |
| The generator also keeps an estimate of the |
| number of bits of noise in the entropy pool. |
| From this entropy pool, random numbers are created. |
| .PP |
| Linux 3.17 and later provides the simpler and safer |
| .BR getrandom (2) |
| interface which requires no special files; |
| see the |
| .BR getrandom (2) |
| manual page for details. |
| .PP |
| When read, the |
| .I /dev/urandom |
| device returns random bytes using a pseudorandom |
| number generator seeded from the entropy pool. |
| Reads from this device do not block (i.e., the CPU is not yielded), |
| but can incur an appreciable delay when requesting large amounts of data. |
| .PP |
| When read during early boot time, |
| .IR /dev/urandom |
| may return data prior to the entropy pool being initialized. |
| .\" This is a real problem; see |
| .\" commit 9b4d008787f864f17d008c9c15bbe8a0f7e2fc24 |
| If this is of concern in your application, use |
| .BR getrandom (2) |
| or \fI/dev/random\fP instead. |
| .PP |
| The \fI/dev/random\fP device is a legacy interface which dates back to |
| a time where the cryptographic primitives used in the implementation |
| of \fI/dev/urandom\fP were not widely trusted. |
| It will return random bytes only within the estimated number of |
| bits of fresh noise in the entropy pool, blocking if necessary. |
| \fI/dev/random\fP is suitable for applications that need |
| high quality randomness, and can afford indeterminate delays. |
| .PP |
| When the entropy pool is empty, reads from \fI/dev/random\fP will block |
| until additional environmental noise is gathered. |
| If |
| .BR open (2) |
| is called for |
| .I /dev/random |
| with the |
| .BR O_NONBLOCK |
| flag, a subsequent |
| .BR read (2) |
| will not block if the requested number of bytes is not available. |
| Instead, the available bytes are returned. |
| If no byte is available, |
| .BR read (2) |
| will return \-1 and |
| .I errno |
| will be set to |
| .BR EAGAIN . |
| .PP |
| The |
| .B O_NONBLOCK |
| flag has no effect when opening |
| .IR /dev/urandom . |
| When calling |
| .BR read (2) |
| for the device |
| .IR /dev/urandom , |
| reads of up to 256 bytes will return as many bytes as are requested |
| and will not be interrupted by a signal handler. |
| Reads with a buffer over this limit may return less than the |
| requested number of bytes or fail with the error |
| .BR EINTR , |
| if interrupted by a signal handler. |
| .PP |
| Since Linux 3.16, |
| .\" commit 79a8468747c5f95ed3d5ce8376a3e82e0c5857fc |
| a |
| .BR read (2) |
| from |
| .IR /dev/urandom |
| will return at most 32\ MB. |
| A |
| .BR read (2) |
| from |
| .IR /dev/random |
| will return at most 512 bytes |
| .\" SEC_XFER_SIZE in drivers/char/random.c |
| (340 bytes on Linux kernels before version 2.6.12). |
| .PP |
| Writing to \fI/dev/random\fP or \fI/dev/urandom\fP will update the |
| entropy pool with the data written, but this will not result in a |
| higher entropy count. |
| This means that it will impact the contents |
| read from both files, but it will not make reads from |
| \fI/dev/random\fP faster. |
| .SS Usage |
| The |
| .IR /dev/random |
| interface is considered a legacy interface, and |
| .IR /dev/urandom |
| is preferred and sufficient in all use cases, with the exception of |
| applications which require randomness during early boot time; for |
| these applications, |
| .BR getrandom (2) |
| must be used instead, |
| because it will block until the entropy pool is initialized. |
| .PP |
| If a seed file is saved across reboots as recommended below, |
| the output is |
| cryptographically secure against attackers without local root access as |
| soon as it is reloaded in the boot sequence, and perfectly adequate for |
| network encryption session keys. |
| (All major Linux distributions have saved the seed file across reboots |
| since 2000 at least.) |
| Since reads from |
| .I /dev/random |
| may block, users will usually want to open it in nonblocking mode |
| (or perform a read with timeout), |
| and provide some sort of user notification if the desired |
| entropy is not immediately available. |
| .\" |
| .SS Configuration |
| If your system does not have |
| \fI/dev/random\fP and \fI/dev/urandom\fP created already, they |
| can be created with the following commands: |
| .PP |
| .in +4n |
| .EX |
| mknod \-m 666 /dev/random c 1 8 |
| mknod \-m 666 /dev/urandom c 1 9 |
| chown root:root /dev/random /dev/urandom |
| .EE |
| .in |
| .PP |
| When a Linux system starts up without much operator interaction, |
| the entropy pool may be in a fairly predictable state. |
| This reduces the actual amount of noise in the entropy pool |
| below the estimate. |
| In order to counteract this effect, it helps to carry |
| entropy pool information across shut-downs and start-ups. |
| To do this, add the lines to an appropriate script |
| which is run during the Linux system start-up sequence: |
| .PP |
| .in +4n |
| .EX |
| echo "Initializing random number generator..." |
| random_seed=/var/run/random\-seed |
| # Carry a random seed from start\-up to start\-up |
| # Load and then save the whole entropy pool |
| if [ \-f $random_seed ]; then |
| cat $random_seed >/dev/urandom |
| else |
| touch $random_seed |
| fi |
| chmod 600 $random_seed |
| poolfile=/proc/sys/kernel/random/poolsize |
| [ \-r $poolfile ] && bits=$(cat $poolfile) || bits=4096 |
| bytes=$(expr $bits / 8) |
| dd if=/dev/urandom of=$random_seed count=1 bs=$bytes |
| .EE |
| .in |
| .PP |
| Also, add the following lines in an appropriate script which is |
| run during the Linux system shutdown: |
| .PP |
| .in +4n |
| .EX |
| # Carry a random seed from shut\-down to start\-up |
| # Save the whole entropy pool |
| echo "Saving random seed..." |
| random_seed=/var/run/random\-seed |
| touch $random_seed |
| chmod 600 $random_seed |
| poolfile=/proc/sys/kernel/random/poolsize |
| [ \-r $poolfile ] && bits=$(cat $poolfile) || bits=4096 |
| bytes=$(expr $bits / 8) |
| dd if=/dev/urandom of=$random_seed count=1 bs=$bytes |
| .EE |
| .in |
| .PP |
| In the above examples, we assume Linux 2.6.0 or later, where |
| .IR /proc/sys/kernel/random/poolsize |
| returns the size of the entropy pool in bits (see below). |
| .\" |
| .SS /proc interfaces |
| The files in the directory |
| .I /proc/sys/kernel/random |
| (present since 2.3.16) provide additional information about the |
| .I /dev/random |
| device: |
| .TP |
| .I entropy_avail |
| This read-only file gives the available entropy, in bits. |
| This will be a number in the range 0 to 4096. |
| .TP |
| .I poolsize |
| This file |
| gives the size of the entropy pool. |
| The semantics of this file vary across kernel versions: |
| .RS |
| .TP |
| Linux 2.4: |
| This file gives the size of the entropy pool in |
| .IR bytes . |
| Normally, this file will have the value 512, but it is writable, |
| and can be changed to any value for which an algorithm is available. |
| The choices are 32, 64, 128, 256, 512, 1024, or 2048. |
| .TP |
| Linux 2.6 and later: |
| This file is read-only, and gives the size of the entropy pool in |
| .IR bits . |
| It contains the value 4096. |
| .RE |
| .TP |
| .I read_wakeup_threshold |
| This file |
| contains the number of bits of entropy required for waking up processes |
| that sleep waiting for entropy from |
| .IR /dev/random . |
| The default is 64. |
| .TP |
| .I write_wakeup_threshold |
| This file |
| contains the number of bits of entropy below which we wake up |
| processes that do a |
| .BR select (2) |
| or |
| .BR poll (2) |
| for write access to |
| .IR /dev/random . |
| These values can be changed by writing to the files. |
| .TP |
| .IR uuid " and " boot_id |
| These read-only files |
| contain random strings like 6fd5a44b-35f4-4ad4-a9b9-6b9be13e1fe9. |
| The former is generated afresh for each read, the latter was |
| generated once. |
| .\" |
| .SS ioctl(2) interface |
| The following |
| .BR ioctl (2) |
| requests are defined on file descriptors connected to either \fI/dev/random\fP |
| or \fI/dev/urandom\fP. |
| All requests performed will interact with the input |
| entropy pool impacting both \fI/dev/random\fP and \fI/dev/urandom\fP. |
| The |
| .B CAP_SYS_ADMIN |
| capability is required for all requests except |
| .BR RNDGETENTCNT . |
| .TP |
| .BR RNDGETENTCNT |
| Retrieve the entropy count of the input pool, the contents will be the same |
| as the |
| .I entropy_avail |
| file under proc. |
| The result will be stored in the int pointed to by the argument. |
| .TP |
| .BR RNDADDTOENTCNT |
| Increment or decrement the entropy count of the input pool |
| by the value pointed to by the argument. |
| .TP |
| .BR RNDGETPOOL |
| Removed in Linux 2.6.9. |
| .TP |
| .BR RNDADDENTROPY |
| Add some additional entropy to the input pool, |
| incrementing the entropy count. |
| This differs from writing to \fI/dev/random\fP or \fI/dev/urandom\fP, |
| which only adds some |
| data but does not increment the entropy count. |
| The following structure is used: |
| .IP |
| .in +4n |
| .EX |
| struct rand_pool_info { |
| int entropy_count; |
| int buf_size; |
| __u32 buf[0]; |
| }; |
| .EE |
| .in |
| .IP |
| Here |
| .I entropy_count |
| is the value added to (or subtracted from) the entropy count, and |
| .I buf |
| is the buffer of size |
| .I buf_size |
| which gets added to the entropy pool. |
| .TP |
| .BR RNDZAPENTCNT ", " RNDCLEARPOOL |
| Zero the entropy count of all pools and add some system data (such as |
| wall clock) to the pools. |
| .SH FILES |
| .I /dev/random |
| .br |
| .I /dev/urandom |
| .SH NOTES |
| For an overview and comparison of the various interfaces that |
| can be used to obtain randomness, see |
| .BR random (7). |
| .SH BUGS |
| During early boot time, reads from |
| .I /dev/urandom |
| may return data prior to the entropy pool being initialized. |
| .\" .SH AUTHOR |
| .\" The kernel's random number generator was written by |
| .\" Theodore Ts'o (tytso@athena.mit.edu). |
| .SH SEE ALSO |
| .BR mknod (1), |
| .BR getrandom (2), |
| .BR random (7) |
| .PP |
| RFC\ 1750, "Randomness Recommendations for Security" |