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