diff options
Diffstat (limited to 'man4/random.4')
| -rw-r--r-- | man4/random.4 | 349 |
1 files changed, 0 insertions, 349 deletions
diff --git a/man4/random.4 b/man4/random.4 deleted file mode 100644 index 7a1d15d..0000000 --- a/man4/random.4 +++ /dev/null @@ -1,349 +0,0 @@ -.\" 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-10-31 "Linux man-pages 6.7" -.SH NAME -random, urandom \- kernel random number source devices -.SH SYNOPSIS -.nf -#include <linux/random.h> -.P -.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. -.P -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. -.P -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. -.P -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. -.P -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. -.P -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. -.P -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 . -.P -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. -.P -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). -.P -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. -.P -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: -.P -.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 -.P -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: -.P -.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 -.P -Also, add the following lines in an appropriate script which is -run during the Linux system shutdown: -.P -.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 -.P -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 -.B RNDZAPENTCNT -.TQ -.B 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) -.P -RFC\ 1750, "Randomness Recommendations for Security" |