.\"	$NetBSD: entropy.7,v 1.3 2021/01/15 15:17:09 riastradh Exp $
.\"
.\" Copyright (c) 2021 The NetBSD Foundation, Inc.
.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
.\"
.Dd January 4, 2021
.Dt ENTROPY 7
.Os
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh NAME
.Nm entropy
.Nd random unpredictable secrets needed for security
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh DESCRIPTION
Computers need random unpredictable secrets for the security of
software such as web browsers and
.Xr ssh 1 .
.Pp
Computers are designed to behave in highly predictable ways, so they
rely on observations of random physical phenomena around them, called
.Nm entropy sources ,
to derive unpredictable secrets for cryptography.
.Pp
While some computers have reliable entropy sources such as hardware
random number generators based on thermal noise in silicon circuits,
others may require operator intervention for security.
.\""""""""""""""""""""""""""""""""""""""
.Ss Threats
.Bl -bullet
.It
Web browsers and programs such as
.Xr ssh 1
rely on unpredictable secrets in cryptography to prevent eavesdropping
and detect tampering of sessions over the network.
.It
.Xr ssh-keygen 1
relies on unpredictable secrets to create keys that allow you to log in
but keep out malicious adversaries; if an adversary could guess the key
then they could impersonate you.
.It
.Nx
relies on unpredictable secrets to make sure that private user data
stored on nonvolatile media when memory is scarce
.Pq Xr swapctl 8 , using So Li vm.swap_encrypt=1 Sc ; see Xr sysctl 7
cannot be recovered by forensic tools after shutdown.
.El
.\""""""""""""""""""""""""""""""""""""""
.Ss Entropy in Nx
.Nx
gathers samples from various kinds of entropy sources, including:
.Bl -bullet -compact
.It
hardware random number generators
.It
network traffic timing
.It
user input (keystrokes, mouse movements, etc.)
.It
disk I/O latency
.It
environment sensors
.Pq Xr envsys 4
.El
The samples are mixed together with cryptography to yield unpredictable
secrets through
.Pa /dev/urandom
.Pq see Xr rnd 4
and related interfaces used by programs like
.Xr ssh 1 ,
Firefox, and so on.
.Pp
.Nx
also stores a random seed at
.Pa /var/db/entropy-file
to carry unpredictable secrets over from one boot to the next, as long
as the medium remains secret and can be updated on boot.
The seed is maintained automatically by
.Pa /etc/rc.d/random_seed
.Pq see Xr rc.conf 5 .
.\""""""""""""""""""""""""""""""""""""""
.Ss Ensuring enough entropy
Entropy is measured in bits, and only 256 bits of entropy are needed
for security, thanks to modern cryptography.
.Pp
To detect potentially insecure systems,
.Nx
records how many bits it needs to achieve the full 256 bits, exposed
via the
.Xr sysctl 7
variable
.Li kern.entropy.needed ,
and takes measures to alert the operator if there isn't definitely
enough for security:
.Bl -bullet
.It
.Nx
issues warnings on the console if there's not enough entropy when
programs need it; see
.Xr rnd 4 .
.It
The daily security report includes an alert if there's not enough
entropy; see
.Xr security.conf 5 .
.It
The operator can set
.Sq Li entropy=check
in
.Xr rc.conf 5
so that
.Nx
will refuse to boot to multiuser unless there is enough entropy, or set
.Sq Li entropy=wait
so that
.Nx
will wait for entropy before booting to multiuser (with the caveat that
it may cause boot to hang forever).
.El
.Pp
Since it is difficult to confidently model the unpredictability of most
physical systems, only devices specifically designed to be hardware
random number generators count toward
.Nx Ns 's
estimate of the entropy.
.Pp
Many new computers have hardware random number generators, such as
RDRAND/RDSEED in Intel/AMD CPUs, or ARMv8.5-RNDRRS;
.Xr virtio 4 Ns -based
virtualization platforms such as QEMU can expose entropy from the host
with
.Xr viornd 4 ;
bootloader firmware such as UEFI may also expose an underlying
platform's random number generator.
.Pp
However, many older computers have no reliable entropy sources.
Some have the hardware, but have it off by default, such as a disabled
.Xr tpm 4 .
On computers with no built-in reliable entropy source, you may wish to
transfer a seed from another computer with
.Xr rndctl 8 ,
or manually enter samples into
.Pa /dev/urandom
\(em see below.
.\""""""""""""""""""""""""""""""""""""""
.Ss Adding entropy
.Pp
You can manually save and load seeds with the
.Xr rndctl 8
tool.
For example, you might use
.Dl rndctl -S seed
to save a seed from one machine, transfer it over a medium where you
are confident there are no eavesdroppers to another machine, and load
it with
.Dl rndctl -L seed
on the target machine; then run
.Dl /etc/rc.d/random_seed stop
on the target machine to ensure that the entropy will be saved for next
boot, even if the system crashes or otherwise shuts down uncleanly.
.Ic rndctl -S
records the number of bits of entropy in the seed so that
.Ic rndctl -L
can count it.
.Pp
Users can write data to
.Pa /dev/urandom
to be mixed together with all other samples.
For example, no matter what entropy sources are built into a computer,
you can ensure it has enough entropy (as long as there are no
surveillance cameras watching you) by flipping a coin 256 times and
running:
.Dl echo thttthhhhttththtttht... > /dev/urandom
Then run
.Dl /etc/rc.d/random_seed stop
to ensure that the effort will be saved for next boot.
.Pp
Inputs from the superuser (uid 0) to
.Pa /dev/urandom
count toward the system's entropy estimate, at the maximum rate of one
bit of entropy per bit of data; inputs from unprivileged users will
affect subsequent outputs but will be counted as having zero entropy.
.Pp
After adding entropy,
.Sy make sure to regenerate any long-term keys
that might be predictable because they were previously generated with
too little entropy.
For example, if
.Sq Li sshd=YES
is enabled in
.Pa /etc/rc.conf ,
then
.Nx
will automatically generate ssh host keys on boot; if they were
generated with too little entropy, then you may wish to delete them and
create new ones before allowing anyone to log in via
.Xr ssh 1 .
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh SEE ALSO
.Xr getrandom 2 ,
.Xr arc4random 3 ,
.Xr rnd 4 ,
.Xr rc.conf 5 ,
.Xr rc 8 ,
.Xr rndctl 8
.Rs
.%A Nadia Heninger
.%A Zakir Durumeric
.%A Eric Wustrow
.%A J. Alex Halderman
.%T Mining Your Ps and Qs: Detection of Widespread Weak Keys in Network Devices
.%B Proceedings of the 21st USENIX Security Symposium
.%I USENIX
.%D August 2012
.%P 205-220
.%U https://www.usenix.org/conference/usenixsecurity12/technical-sessions/presentation/heninger
.%U https://factorable.net/
.Re
.Rs
.%T openssl \(em predictable random number generator
.%I Debian Security Advisory
.%O DSA-1571-1
.%D 2008-05-13
.%U https://www.debian.org/security/2008/dsa-1571.html
.Re
.Rs
.%T Features/VirtIORNG
.%I QEMU Wiki
.%U https://wiki.qemu.org/Features/VirtIORNG
.%D 2016-10-17
.Re