mirror of https://github.com/mkerrisk/man-pages
346 lines
10 KiB
Groff
346 lines
10 KiB
Groff
.\" 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 2017-09-15 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
random, urandom \- kernel random number source devices
|
|
.SH SYNOPSIS
|
|
#include <linux/random.h>
|
|
.PP
|
|
.BI "int ioctl(" fd ", RND" request ", " param ");"
|
|
.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"
|