freebsd-skq/share/man/man4/random.4

.\" Copyright (c) 2001-2015	Mark R V Murray.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd April 19, 2019
.Dt RANDOM 4
.Os
.Sh NAME
.Nm random
.Nd the entropy device
.Sh SYNOPSIS
.Cd "options RANDOM_LOADABLE"
.Cd "options RANDOM_ENABLE_ETHER"
.Cd "options RANDOM_ENABLE_UMA"
.Sh DESCRIPTION
The
.Nm
device returns an endless supply of random bytes when read.
.Pp
The generator will start in an
.Em unseeded
state, and will block reads until it is seeded for the first time.
.Pp
To provide prompt access to the random device at boot time,
.Fx
automatically persists some entropy data in
.Pa /boot/entropy
for the loader to provide to the kernel.
Additional entropy is regularly saved in
.Pa /var/db/entropy .
This saved entropy is sufficient to unblock the random device on devices with
writeable media.
.Pp
Embedded applications without writable media must determine their own scheme
for re-seeding the random device on boot, or accept that the device
will remain unseeded and block reads indefinitely.
See
.Sx SECURITY CONSIDERATIONS
for more detail.
.Pp
In addition to
.Xr read 2 ,
the direct output of the abstract kernel entropy device can be read with
.Xr getrandom 2 ,
.Xr getentropy 3 ,
or the
.Xr sysctl 8
pseudo-variable
.Va kern.arandom .
.Pp
To see the current settings of the software
.Nm
device, use the command line:
.Pp
.Dl "sysctl kern.random"
.Pp
which results in something like:
.Bd -literal -offset indent
kern.random.block_seeded_status: 0
kern.random.fortuna.minpoolsize: 64
kern.random.harvest.mask_symbolic: ENABLEDSOURCE,[DISABLEDSOURCE],...,CACHED
kern.random.harvest.mask_bin: 00000010000000111011111
kern.random.harvest.mask: 66015
kern.random.use_chacha20_cipher: 0
kern.random.random_sources: 'Intel Secure Key RNG'
kern.random.initial_seeding.bypass_before_seeding: 1
kern.random.initial_seeding.read_random_bypassed_before_seeding: 0
kern.random.initial_seeding.arc4random_bypassed_before_seeding: 0
kern.random.initial_seeding.disable_bypass_warnings: 0
.Ed
.Pp
Other than
.Va kern.random.block_seeded_status ,
.Va kern.random.fortuna.minpoolsize ,
and
.Va kern.random.harvest.mask ,
all settings are read-only.
.Pp
The
.Pa kern.random.fortuna.minpoolsize
sysctl is used
to set the seed threshold.
A smaller number gives a faster seed,
but a less secure one.
In practice,
values between 64 and 256
are acceptable.
.Pp
The
.Va kern.random.harvest.mask
bitmask is used to select
the possible entropy sources.
A 0 (zero) value means
the corresponding source
is not considered
as an entropy source.
Set the bit to 1 (one)
if you wish to use
that source.
The
.Va kern.random.harvest.mask_bin
and
.Va kern.random.harvest.mask_symbolic
sysctls
can be used to confirm
settings in a human readable form.
Disabled items
in the latter item
are listed in square brackets.
See
.Xr random_harvest 9
for more on the harvesting of entropy.
.Sh FILES
.Bl -tag -width ".Pa /dev/urandom"
.It Pa /dev/random
.It Pa /dev/urandom
.El
.Sh DIAGNOSTICS
The following tunables are related to initial seeding of the
.Nm
device:
.Bl -tag -width 4
.It Va kern.random.initial_seeding.bypass_before_seeding
Defaults to 1 (on).
When set, the system will bypass the
.Nm
device prior to initial seeding.
On is
.Em unsafe ,
but provides availability on many systems that lack early sources
of entropy, or cannot load
.Pa /boot/entropy
sufficiently early in boot for
.Nm
consumers.
When unset (0), the system will block
.Xr read_random 9
and
.Xr arc4random 9
requests if and until the
.Nm
device is initially seeded.
.It Va kern.random.initial_seeding.disable_bypass_warnings
Defaults to 0 (off).
When set non-zero, disables warnings in dmesg when the
.Nm
device is bypassed.
.El
.Pp
The following read-only
.Xr sysctl 8
variables allow programmatic diagnostic of whether
.Nm
device bypass occurred during boot.
If they are set (non-zero), the specific functional unit bypassed the strong
.Nm
device output and either produced no output
.Xr ( read_random 9 )
or seeded itself with minimal, non-cryptographic entropy
.Xr ( arc4random 9 ) .
.Bl -bullet
.It
.Va kern.random.initial_seeding.read_random_bypassed_before_seeding
.It
.Va kern.random.initial_seeding.arc4random_bypassed_before_seeding
.El
.Sh SEE ALSO
.Xr getrandom 2 ,
.Xr arc4random 3 ,
.Xr getentropy 3 ,
.Xr random 3 ,
.Xr sysctl 8 ,
.Xr random 9
.Rs
.%A Ferguson
.%A Schneier
.%A Kohno
.%B Cryptography Engineering
.%I Wiley
.%O ISBN 978-0-470-47424-2
.Re
.Sh HISTORY
A
.Nm
device appeared in
.Fx 2.2 .
The implementation was changed to the
.Em Yarrow algorithm in
.Fx 5.0 .
In
.Fx 11.0 ,
the Fortuna algorithm was introduced as the default.
In
.Fx 12.0 ,
Yarrow was removed entirely.
.Sh AUTHORS
.An -nosplit
The current
.Nm
code was authored by
.An Mark R V Murray ,
with significant contributions from many people.
.Pp
The
.Em Fortuna
algorithm was designed by
.An Niels Ferguson ,
.An Bruce Schneier ,
and
.An Tadayoshi Kohno .
.Sh CAVEATS
When
.Cd "options RANDOM_LOADABLE"
is enabled,
the
.Pa /dev/random
device is not created
until an "algorithm module"
is loaded.
The only module built by default is
.Em random_fortuna .
Loadable random modules
are less efficient
than their compiled-in equivalents.
This is because some functions
must be locked against
load and unload events,
and also must be indirect calls
to allow for removal.
.Pp
When
.Cd "options RANDOM_ENABLE_UMA"
is enabled,
the
.Pa /dev/random
device will obtain entropy
from the zone allocator.
This is a very high rate source with significant performance impact.
Therefore, it is disabled by default.
.Pp
When
.Cd "options RANDOM_ENABLE_ETHER"
is enabled, the
.Nm
device will obtain entropy from
.Vt mbuf
structures passing through the network stack.
This source is both extremely expensive and a poor source of entropy, so it is
disabled by default.
.Sh SECURITY CONSIDERATIONS
The initial seeding
of random number generators
is a bootstrapping problem
that needs very careful attention.
When writable media is available, the
.Em Fortuna
paper describes a robust system for rapidly reseeding the device.
.Pp
In some embedded cases, it may be difficult to find enough randomness to seed a
random number generator until a system is fully operational.
In these cases, is the responsibility of the system architect to ensure that
blocking is acceptable, or that the random device is seeded.
(This advice does not apply to typical consumer systems.)
.Pp
To emulate embedded systems, developers may set the
.Va kern.random.block_seeded_status
tunable to 1 to verify boot does not require early availability of the
.Nm
device.