1.\" $NetBSD: entropy.7,v 1.3 2021/01/15 15:17:09 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 over a medium where you 173are confident there are no eavesdroppers to another machine, and load 174it 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 crashes or otherwise shuts down uncleanly. 180.Ic rndctl -S 181records the number of bits of entropy in the seed so that 182.Ic rndctl -L 183can count it. 184.Pp 185Users can write data to 186.Pa /dev/urandom 187to be mixed together with all other samples. 188For example, no matter what entropy sources are built into a computer, 189you can ensure it has enough entropy (as long as there are no 190surveillance cameras watching you) by flipping a coin 256 times and 191running: 192.Dl echo thttthhhhttththtttht... > /dev/urandom 193Then run 194.Dl /etc/rc.d/random_seed stop 195to ensure that the effort will be saved for next boot. 196.Pp 197Inputs from the superuser (uid 0) to 198.Pa /dev/urandom 199count toward the system's entropy estimate, at the maximum rate of one 200bit of entropy per bit of data; inputs from unprivileged users will 201affect subsequent outputs but will be counted as having zero entropy. 202.Pp 203After adding entropy, 204.Sy make sure to regenerate any long-term keys 205that might be predictable because they were previously generated with 206too little entropy. 207For example, if 208.Sq Li sshd=YES 209is enabled in 210.Pa /etc/rc.conf , 211then 212.Nx 213will automatically generate ssh host keys on boot; if they were 214generated with too little entropy, then you may wish to delete them and 215create new ones before allowing anyone to log in via 216.Xr ssh 1 . 217.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 218.Sh SEE ALSO 219.Xr getrandom 2 , 220.Xr arc4random 3 , 221.Xr rnd 4 , 222.Xr rc.conf 5 , 223.Xr rc 8 , 224.Xr rndctl 8 225.Rs 226.%A Nadia Heninger 227.%A Zakir Durumeric 228.%A Eric Wustrow 229.%A J. Alex Halderman 230.%T Mining Your Ps and Qs: Detection of Widespread Weak Keys in Network Devices 231.%B Proceedings of the 21st USENIX Security Symposium 232.%I USENIX 233.%D August 2012 234.%P 205-220 235.%U https://www.usenix.org/conference/usenixsecurity12/technical-sessions/presentation/heninger 236.%U https://factorable.net/ 237.Re 238.Rs 239.%T openssl \(em predictable random number generator 240.%I Debian Security Advisory 241.%O DSA-1571-1 242.%D 2008-05-13 243.%U https://www.debian.org/security/2008/dsa-1571.html 244.Re 245.Rs 246.%T Features/VirtIORNG 247.%I QEMU Wiki 248.%U https://wiki.qemu.org/Features/VirtIORNG 249.%D 2016-10-17 250.Re 251