Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 349 insertions, 0 deletions

diff --git a/man/man4/random.4 b/man/man4/random.4
new file mode 100644
index 0000000..78fe128
--- /dev/null
+++ b/man/man4/random.4
@@ -0,0 +1,349 @@
+.\" 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 2024-05-02 "Linux man-pages (unreleased)"
+.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"