diff options
Diffstat (limited to '')
| -rw-r--r-- | man4/random.4 | 347 |
1 files changed, 347 insertions, 0 deletions
diff --git a/man4/random.4 b/man4/random.4 new file mode 100644 index 0000000..0f0eb21 --- /dev/null +++ b/man4/random.4 @@ -0,0 +1,347 @@ +.\" Copyright (c) 1997 John S. Kallal (kallal@voicenet.com) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 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 2023-04-18 "Linux man-pages 6.05.01" +.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, +.I /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. +Since Linux 5.6, the +.B O_NONBLOCK +flag is ignored as +.I /dev/random +will no longer block except during early boot process. +In earlier versions, if +.BR open (2) +is called for +.I /dev/random +with the +.B 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 +.I /dev/urandom +will return at most 32\ MB. +A +.BR read (2) +from +.I /dev/random +will return at most 512 bytes +.\" SEC_XFER_SIZE in drivers/char/random.c +(340 bytes before Linux 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 +.I /dev/random +interface is considered a legacy interface, and +.I /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 +.I /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 Linux 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 +.B 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 +.B RNDADDTOENTCNT +Increment or decrement the entropy count of the input pool +by the value pointed to by the argument. +.TP +.B RNDGETPOOL +Removed in Linux 2.6.9. +.TP +.B 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" |