1.\" $NetBSD: entropy.7,v 1.4 2022/03/20 18:19:58 riastradh 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 January 4, 2021 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.Pq Xr swapctl 8 , using So Li vm.swap_encrypt=1 Sc ; see Xr sysctl 7 66cannot be recovered by forensic tools after shutdown. 67.El 68.\"""""""""""""""""""""""""""""""""""""" 69.Ss Entropy in Nx 70.Nx 71gathers samples from various kinds of entropy sources, including: 72.Bl -bullet -compact 73.It 74hardware random number generators 75.It 76network traffic timing 77.It 78user input (keystrokes, mouse movements, etc.) 79.It 80disk I/O latency 81.It 82environment sensors 83.Pq Xr envsys 4 84.El 85The samples are mixed together with cryptography to yield unpredictable 86secrets through 87.Pa /dev/urandom 88.Pq see Xr rnd 4 89and related interfaces used by programs like 90.Xr ssh 1 , 91Firefox, and so on. 92.Pp 93.Nx 94also stores a random seed at 95.Pa /var/db/entropy-file 96to carry unpredictable secrets over from one boot to the next, as long 97as the medium remains secret and can be updated on boot. 98The seed is maintained automatically by 99.Pa /etc/rc.d/random_seed 100.Pq see Xr rc.conf 5 . 101.\"""""""""""""""""""""""""""""""""""""" 102.Ss Ensuring enough entropy 103Entropy is measured in bits, and only 256 bits of entropy are needed 104for security, thanks to modern cryptography. 105.Pp 106To detect potentially insecure systems, 107.Nx 108records how many bits it needs to achieve the full 256 bits, exposed 109via the 110.Xr sysctl 7 111variable 112.Li kern.entropy.needed , 113and takes measures to alert the operator if there isn't definitely 114enough for security: 115.Bl -bullet 116.It 117.Nx 118issues warnings on the console if there's not enough entropy when 119programs need it; see 120.Xr rnd 4 . 121.It 122The daily security report includes an alert if there's not enough 123entropy; see 124.Xr security.conf 5 . 125.It 126The operator can set 127.Sq Li entropy=check 128in 129.Xr rc.conf 5 130so that 131.Nx 132will refuse to boot to multiuser unless there is enough entropy, or set 133.Sq Li entropy=wait 134so that 135.Nx 136will wait for entropy before booting to multiuser (with the caveat that 137it may cause boot to hang forever). 138.El 139.Pp 140Since it is difficult to confidently model the unpredictability of most 141physical systems, only devices specifically designed to be hardware 142random number generators count toward 143.Nx Ns 's 144estimate of the entropy. 145.Pp 146Many new computers have hardware random number generators, such as 147RDRAND/RDSEED in Intel/AMD CPUs, or ARMv8.5-RNDRRS; 148.Xr virtio 4 Ns -based 149virtualization platforms such as QEMU can expose entropy from the host 150with 151.Xr viornd 4 ; 152bootloader firmware such as UEFI may also expose an underlying 153platform's random number generator. 154.Pp 155However, many older computers have no reliable entropy sources. 156Some have the hardware, but have it off by default, such as a disabled 157.Xr tpm 4 . 158On computers with no built-in reliable entropy source, you may wish to 159transfer a seed from another computer with 160.Xr rndctl 8 , 161or manually enter samples into 162.Pa /dev/urandom 163\(em see below. 164.\"""""""""""""""""""""""""""""""""""""" 165.Ss Adding entropy 166.Pp 167You can manually save and load seeds with the 168.Xr rndctl 8 169tool. 170For example, you might use 171.Dl rndctl -S seed 172to save a seed from one machine, transfer it \(em over a medium where 173you are confident there are no eavesdroppers \(em to another machine, 174and load it with 175.Dl rndctl -L seed 176on the target machine; then run 177.Dl /etc/rc.d/random_seed stop 178on the target machine to ensure that the entropy will be saved for next 179boot, even if the system later crashes or otherwise shuts down 180uncleanly. 181.Ic rndctl -S 182records the number of bits of entropy in the seed so that 183.Ic rndctl -L 184can count it. 185.Pp 186Users can write data to 187.Pa /dev/urandom 188to be mixed together with all other samples. 189For example, no matter what entropy sources are built into a computer, 190you can ensure it has enough entropy (as long as there are no 191surveillance cameras watching you) by flipping a coin 256 times and 192running: 193.Dl echo thttthhhhttththtttht... > /dev/urandom 194Then run 195.Dl /etc/rc.d/random_seed stop 196to ensure that the effort will be saved for next boot. 197.Pp 198Inputs from the superuser (uid 0) to 199.Pa /dev/urandom 200count toward the system's entropy estimate, at the maximum rate of one 201bit of entropy per bit of data; inputs from unprivileged users will 202affect subsequent outputs but will be counted as having zero entropy. 203.Pp 204After adding entropy, 205.Sy make sure to regenerate any long-term keys 206that might be predictable because they were previously generated with 207too little entropy. 208For example, if 209.Sq Li sshd=YES 210is enabled in 211.Pa /etc/rc.conf , 212then 213.Nx 214will automatically generate ssh host keys on boot; if they were 215generated with too little entropy, then you may wish to delete them and 216create new ones before allowing anyone to log in via 217.Xr ssh 1 . 218.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 219.Sh DIAGNOSTICS 220.Nx 221may print the following warnings to the console: 222.Bl -diag -offset indent 223.It WARNING: system needs entropy for security; see entropy(7) 224Some process tried to draw use entropy from 225.Nx , 226e.g. to generate a key for cryptography, before enough inputs from 227reliable entropy sources have been obtained. 228The entropy may be low enough that an adversary could guess keys by 229brute force. 230.Pp 231This message is rate-limited, so if you have added entropy and want to 232verify that the problem is resolved, you should consult the 233.Dv kern.entropy.needed 234.Xr sysctl 7 235variable to confirm it is zero, rather than just look for the absence 236of this message; see 237.Xr rnd 4 238for details. 239.El 240.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 241.Sh SEE ALSO 242.Xr getrandom 2 , 243.Xr arc4random 3 , 244.Xr rnd 4 , 245.Xr rc.conf 5 , 246.Xr rc 8 , 247.Xr rndctl 8 248.Rs 249.%A Nadia Heninger 250.%A Zakir Durumeric 251.%A Eric Wustrow 252.%A J. Alex Halderman 253.%T Mining Your Ps and Qs: Detection of Widespread Weak Keys in Network Devices 254.%B Proceedings of the 21st USENIX Security Symposium 255.%I USENIX 256.%D August 2012 257.%P 205-220 258.%U https://www.usenix.org/conference/usenixsecurity12/technical-sessions/presentation/heninger 259.%U https://factorable.net/ 260.Re 261.Rs 262.%T openssl \(em predictable random number generator 263.%I Debian Security Advisory 264.%O DSA-1571-1 265.%D 2008-05-13 266.%U https://www.debian.org/security/2008/dsa-1571.html 267.Re 268.Rs 269.%T Features/VirtIORNG 270.%I QEMU Wiki 271.%U https://wiki.qemu.org/Features/VirtIORNG 272.%D 2016-10-17 273.Re 274