diff options
Diffstat (limited to 'static/netbsd/man7/entropy.7')
| -rw-r--r-- | static/netbsd/man7/entropy.7 | 286 |
1 files changed, 286 insertions, 0 deletions
diff --git a/static/netbsd/man7/entropy.7 b/static/netbsd/man7/entropy.7 new file mode 100644 index 00000000..c67d5293 --- /dev/null +++ b/static/netbsd/man7/entropy.7 @@ -0,0 +1,286 @@ +.\" $NetBSD: entropy.7,v 1.10 2023/07/20 04:16:14 gutteridge 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 June 30, 2023 +.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 +.Po +.Xr swapctl 8 , +using +.Ql vm.swap_encrypt=1 ; +see +.Xr sysctl 7 +.Pc +cannot be recovered by forensic tools after shutdown. +.El +.\"""""""""""""""""""""""""""""""""""""" +.Ss Entropy in NetBSD +.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 +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 +.Xr motd 5 +has a warning if there was not enough entropy when network daemons such as +.Xr sshd 8 +first generated keys. +.It +The daily security report includes an alert if there's still not enough +entropy; see +.Xr security.conf 5 . +.El +.Pp +Since it is hard to know how unpredictable most physical systems are, +only devices specifically designed to be hardware random number +generators, or a seed file stored on disk, count toward these alerts. +.Pp +At boot, +.Nx +will wait, when +.Ql entropy=wait +is set in +.Xr rc.conf 5 , +or fail to single-user mode, when +.Ql entropy=check +is set, if there is not enough entropy from +.Em any +sources, including devices not designed to be unpredictable, such as +the CPU cycle counter sampled by a periodic timer, provided the samples +pass a simple filter called the +.Sq entropy estimator , +like other operating systems. +Sources known to be predictable, which could give a false sense of +security, can be disabled from unblocking boot by setting +.Li rndctl_flags +in +.Xr rc.conf 5 . +.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 \(em over a medium where +you are confident there are no eavesdroppers \(em 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 later 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 +.Ql 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 DIAGNOSTICS +.Nx +may print the following warnings to the console: +.Bl -diag +.It WARNING: system needs entropy for security; see entropy(7) +Some process tried to draw use entropy from +.Nx , +e.g. to generate a key for cryptography, before enough inputs from +reliable entropy sources have been obtained. +The entropy may be low enough that an adversary could guess keys by +brute force. +.Pp +This message is rate-limited, so if you have added entropy and want to +verify that the problem is resolved, you should consult the +.Dv kern.entropy.needed +.Xr sysctl 7 +variable to confirm it is zero, rather than just look for the absence +of this message; see +.Xr rnd 4 +for details. +.El +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.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 |