summaryrefslogtreecommitdiffstats
path: root/man4/random.4
diff options
context:
space:
mode:
Diffstat (limited to 'man4/random.4')
-rw-r--r--man4/random.4349
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"