1.\" $NetBSD: entropy.7,v 1.10 2023/07/20 04:16:14 gutteridge Exp $ 2.\" 3.\" Copyright (c) 2021 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd June 30, 2023 28.Dt ENTROPY 7 29.Os 30.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 31.Sh NAME 32.Nm entropy 33.Nd random unpredictable secrets needed for security 34.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 35.Sh DESCRIPTION 36Computers need random unpredictable secrets for the security of 37software such as web browsers and 38.Xr ssh 1 . 39.Pp 40Computers are designed to behave in highly predictable ways, so they 41rely on observations of random physical phenomena around them, called 42.Nm entropy sources , 43to derive unpredictable secrets for cryptography. 44.Pp 45While some computers have reliable entropy sources such as hardware 46random number generators based on thermal noise in silicon circuits, 47others may require operator intervention for security. 48.\"""""""""""""""""""""""""""""""""""""" 49.Ss Threats 50.Bl -bullet 51.It 52Web browsers and programs such as 53.Xr ssh 1 54rely on unpredictable secrets in cryptography to prevent eavesdropping 55and detect tampering of sessions over the network. 56.It 57.Xr ssh-keygen 1 58relies on unpredictable secrets to create keys that allow you to log in 59but keep out malicious adversaries; if an adversary could guess the key 60then they could impersonate you. 61.It 62.Nx 63relies on unpredictable secrets to make sure that private user data 64stored on nonvolatile media when memory is scarce 65.Po 66.Xr swapctl 8 , 67using 68.Ql vm.swap_encrypt=1 ; 69see 70.Xr sysctl 7 71.Pc 72cannot be recovered by forensic tools after shutdown. 73.El 74.\"""""""""""""""""""""""""""""""""""""" 75.Ss Entropy in NetBSD 76.Nx 77gathers samples from various kinds of entropy sources, including: 78.Bl -bullet -compact 79.It 80hardware random number generators 81.It 82network traffic timing 83.It 84user input (keystrokes, mouse movements, etc.) 85.It 86disk I/O latency 87.It 88environment sensors 89.Pq Xr envsys 4 90.El 91The samples are mixed together with cryptography to yield unpredictable 92secrets through 93.Pa /dev/urandom 94.Pq see Xr rnd 4 95and related interfaces used by programs like 96.Xr ssh 1 , 97Firefox, and so on. 98.Pp 99.Nx 100also stores a random seed at 101.Pa /var/db/entropy-file 102to carry unpredictable secrets over from one boot to the next, as long 103as the medium remains secret and can be updated on boot. 104The seed is maintained automatically by 105.Pa /etc/rc.d/random_seed 106.Pq see Xr rc.conf 5 . 107.\"""""""""""""""""""""""""""""""""""""" 108.Ss Ensuring enough entropy 109Entropy is measured in bits, and only 256 bits of entropy are needed 110for security, thanks to modern cryptography. 111.Pp 112To detect potentially insecure systems, 113.Nx 114takes measures to alert the operator if there isn't definitely enough 115for security: 116.Bl -bullet 117.It 118.Nx 119issues warnings on the console if there's not enough entropy when 120programs need it; see 121.Xr rnd 4 . 122.It 123The 124.Xr motd 5 125has a warning if there was not enough entropy when network daemons such as 126.Xr sshd 8 127first generated keys. 128.It 129The daily security report includes an alert if there's still not enough 130entropy; see 131.Xr security.conf 5 . 132.El 133.Pp 134Since it is hard to know how unpredictable most physical systems are, 135only devices specifically designed to be hardware random number 136generators, or a seed file stored on disk, count toward these alerts. 137.Pp 138At boot, 139.Nx 140will wait, when 141.Ql entropy=wait 142is set in 143.Xr rc.conf 5 , 144or fail to single-user mode, when 145.Ql entropy=check 146is set, if there is not enough entropy from 147.Em any 148sources, including devices not designed to be unpredictable, such as 149the CPU cycle counter sampled by a periodic timer, provided the samples 150pass a simple filter called the 151.Sq entropy estimator , 152like other operating systems. 153Sources known to be predictable, which could give a false sense of 154security, can be disabled from unblocking boot by setting 155.Li rndctl_flags 156in 157.Xr rc.conf 5 . 158.Pp 159Many new computers have hardware random number generators, such as 160RDRAND/RDSEED in Intel/AMD CPUs, or ARMv8.5-RNDRRS; 161.Xr virtio 4 Ns -based 162virtualization platforms such as QEMU can expose entropy from the host 163with 164.Xr viornd 4 ; 165bootloader firmware such as UEFI may also expose an underlying 166platform's random number generator. 167.Pp 168However, many older computers have no reliable entropy sources. 169Some have the hardware, but have it off by default, such as a disabled 170.Xr tpm 4 . 171On computers with no built-in reliable entropy source, you may wish to 172transfer a seed from another computer with 173.Xr rndctl 8 , 174or manually enter samples into 175.Pa /dev/urandom 176\(em see below. 177.\"""""""""""""""""""""""""""""""""""""" 178.Ss Adding entropy 179.Pp 180You can manually save and load seeds with the 181.Xr rndctl 8 182tool. 183For example, you might use 184.Dl rndctl -S seed 185to save a seed from one machine, transfer it \(em over a medium where 186you are confident there are no eavesdroppers \(em to another machine, 187and load it with 188.Dl rndctl -L seed 189on the target machine; then run 190.Dl /etc/rc.d/random_seed stop 191on the target machine to ensure that the entropy will be saved for next 192boot, even if the system later crashes or otherwise shuts down 193uncleanly. 194.Ic rndctl -S 195records the number of bits of entropy in the seed so that 196.Ic rndctl -L 197can count it. 198.Pp 199Users can write data to 200.Pa /dev/urandom 201to be mixed together with all other samples. 202For example, no matter what entropy sources are built into a computer, 203you can ensure it has enough entropy (as long as there are no 204surveillance cameras watching you) by flipping a coin 256 times and 205running: 206.Dl echo thttthhhhttththtttht... > /dev/urandom 207Then run 208.Dl /etc/rc.d/random_seed stop 209to ensure that the effort will be saved for next boot. 210.Pp 211Inputs from the superuser (uid 0) to 212.Pa /dev/urandom 213count toward the system's entropy estimate, at the maximum rate of one 214bit of entropy per bit of data; inputs from unprivileged users will 215affect subsequent outputs but will be counted as having zero entropy. 216.Pp 217After adding entropy, 218.Sy make sure to regenerate any long-term keys 219that might be predictable because they were previously generated with 220too little entropy. 221For example, if 222.Ql sshd=YES 223is enabled in 224.Pa /etc/rc.conf , 225then 226.Nx 227will automatically generate ssh host keys on boot; if they were 228generated with too little entropy, then you may wish to delete them and 229create new ones before allowing anyone to log in via 230.Xr ssh 1 . 231.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 232.Sh DIAGNOSTICS 233.Nx 234may print the following warnings to the console: 235.Bl -diag 236.It WARNING: system needs entropy for security; see entropy(7) 237Some process tried to draw use entropy from 238.Nx , 239e.g. to generate a key for cryptography, before enough inputs from 240reliable entropy sources have been obtained. 241The entropy may be low enough that an adversary could guess keys by 242brute force. 243.Pp 244This message is rate-limited, so if you have added entropy and want to 245verify that the problem is resolved, you should consult the 246.Dv kern.entropy.needed 247.Xr sysctl 7 248variable to confirm it is zero, rather than just look for the absence 249of this message; see 250.Xr rnd 4 251for details. 252.El 253.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 254.Sh SEE ALSO 255.Xr getrandom 2 , 256.Xr arc4random 3 , 257.Xr rnd 4 , 258.Xr rc.conf 5 , 259.Xr rc 8 , 260.Xr rndctl 8 261.Rs 262.%A Nadia Heninger 263.%A Zakir Durumeric 264.%A Eric Wustrow 265.%A J. Alex Halderman 266.%T Mining Your Ps and Qs: Detection of Widespread Weak Keys in Network Devices 267.%B Proceedings of the 21st USENIX Security Symposium 268.%I USENIX 269.%D August 2012 270.%P 205-220 271.%U https://www.usenix.org/conference/usenixsecurity12/technical-sessions/presentation/heninger 272.%U https://factorable.net/ 273.Re 274.Rs 275.%T openssl \(em predictable random number generator 276.%I Debian Security Advisory 277.%O DSA-1571-1 278.%D 2008-05-13 279.%U https://www.debian.org/security/2008/dsa-1571.html 280.Re 281.Rs 282.%T Features/VirtIORNG 283.%I QEMU Wiki 284.%U https://wiki.qemu.org/Features/VirtIORNG 285.%D 2016-10-17 286.Re 287