1.\" Copyright (c) 2001-2015 Mark R V Murray. All rights reserved. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 15.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 22.\" SUCH DAMAGE. 23.\" 24.\" $FreeBSD$ 25.\" 26.Dd April 19, 2019 27.Dt RANDOM 4 28.Os 29.Sh NAME 30.Nm random 31.Nd the entropy device 32.Sh SYNOPSIS 33.Cd "options RANDOM_LOADABLE" 34.Cd "options RANDOM_ENABLE_ETHER" 35.Cd "options RANDOM_ENABLE_UMA" 36.Sh DESCRIPTION 37The 38.Nm 39device returns an endless supply of random bytes when read. 40.Pp 41The generator will start in an 42.Em unseeded 43state, and will block reads until it is seeded for the first time. 44.Pp 45To provide prompt access to the random device at boot time, 46.Fx 47automatically saves some entropy data in 48.Pa /boot/entropy 49for the 50.Xr loader 8 51to provide to the kernel. 52Additional entropy is regularly saved in 53.Pa /var/db/entropy . 54This saved entropy is sufficient to unblock the random device on devices with 55writeable media. 56.Pp 57Embedded applications without writable media must determine their own scheme 58for re-seeding the random device on boot, or accept that the device 59will remain unseeded and block reads indefinitely. 60See 61.Sx SECURITY CONSIDERATIONS 62for more detail. 63.Pp 64In addition to 65.Xr read 2 , 66the direct output of the abstract kernel entropy device can be read with 67.Xr getrandom 2 , 68.Xr getentropy 3 , 69or the 70.Xr sysctl 8 71pseudo-variable 72.Va kern.arandom . 73.Pp 74To see the current settings of the software 75.Nm 76device, use the command line: 77.Pp 78.Dl "sysctl kern.random" 79.Pp 80which results in something like: 81.Bd -literal -offset indent 82kern.random.block_seeded_status: 0 83kern.random.fortuna.minpoolsize: 64 84kern.random.harvest.mask_symbolic: ENABLEDSOURCE,[DISABLEDSOURCE],...,CACHED 85kern.random.harvest.mask_bin: 00000010000000111011111 86kern.random.harvest.mask: 66015 87kern.random.use_chacha20_cipher: 0 88kern.random.random_sources: 'Intel Secure Key RNG' 89kern.random.initial_seeding.bypass_before_seeding: 1 90kern.random.initial_seeding.read_random_bypassed_before_seeding: 0 91kern.random.initial_seeding.arc4random_bypassed_before_seeding: 0 92kern.random.initial_seeding.disable_bypass_warnings: 0 93.Ed 94.Pp 95Other than 96.Va kern.random.block_seeded_status , 97.Va kern.random.fortuna.minpoolsize , 98and 99.Va kern.random.harvest.mask , 100all settings are read-only via 101.Xr sysctl 8 . 102.Pp 103The 104.Pa kern.random.fortuna.minpoolsize 105sysctl is used 106to set the seed threshold. 107A smaller number gives a faster seed, 108but a less secure one. 109In practice, 110values between 64 and 256 111are acceptable. 112.Pp 113The 114.Va kern.random.harvest.mask 115bitmask is used to select 116the possible entropy sources. 117A 0 (zero) value means 118the corresponding source 119is not considered 120as an entropy source. 121Set the bit to 1 (one) 122if you wish to use 123that source. 124The 125.Va kern.random.harvest.mask_bin 126and 127.Va kern.random.harvest.mask_symbolic 128sysctls 129can be used to confirm 130settings in a human readable form. 131Disabled items 132in the latter 133are listed in square brackets. 134See 135.Xr random_harvest 9 136for more on the harvesting of entropy. 137.Sh FILES 138.Bl -tag -width ".Pa /dev/urandom" 139.It Pa /dev/random 140.It Pa /dev/urandom 141.El 142.Sh DIAGNOSTICS 143The following tunables are related to initial seeding of the 144.Nm 145device: 146.Bl -tag -width 4 147.It Va kern.random.initial_seeding.bypass_before_seeding 148Defaults to 1 (on). 149When set, the system will bypass the 150.Nm 151device prior to initial seeding. 152On is 153.Em unsafe , 154but provides availability on many systems that lack early sources 155of entropy, or cannot load 156.Pa /boot/entropy 157sufficiently early in boot for 158.Nm 159consumers. 160When unset (0), the system will block 161.Xr read_random 9 162and 163.Xr arc4random 9 164requests if and until the 165.Nm 166device is initially seeded. 167.It Va kern.random.initial_seeding.disable_bypass_warnings 168Defaults to 0 (off). 169When set non-zero, disables warnings in dmesg when the 170.Nm 171device is bypassed. 172.El 173.Pp 174The following read-only 175.Xr sysctl 8 176variables allow programmatic diagnostic of whether 177.Nm 178device bypass occurred during boot. 179If they are set (non-zero), the specific functional unit bypassed the strong 180.Nm 181device output and either produced no output 182.Xr ( read_random 9 ) 183or seeded itself with minimal, non-cryptographic entropy 184.Xr ( arc4random 9 ) . 185.Bl -bullet 186.It 187.Va kern.random.initial_seeding.read_random_bypassed_before_seeding 188.It 189.Va kern.random.initial_seeding.arc4random_bypassed_before_seeding 190.El 191.Sh SEE ALSO 192.Xr getrandom 2 , 193.Xr arc4random 3 , 194.Xr getentropy 3 , 195.Xr random 3 , 196.Xr sysctl 8 , 197.Xr random 9 198.Rs 199.%A Ferguson 200.%A Schneier 201.%A Kohno 202.%B Cryptography Engineering 203.%I Wiley 204.%O ISBN 978-0-470-47424-2 205.Re 206.Sh HISTORY 207A 208.Nm 209device appeared in 210.Fx 2.2 . 211The implementation was changed to the 212.Em Yarrow algorithm in 213.Fx 5.0 . 214In 215.Fx 11.0 , 216the Fortuna algorithm was introduced as the default. 217In 218.Fx 12.0 , 219Yarrow was removed entirely. 220.Sh AUTHORS 221.An -nosplit 222The current 223.Nm 224code was authored by 225.An Mark R V Murray , 226with significant contributions from many people. 227.Pp 228The 229.Em Fortuna 230algorithm was designed by 231.An Niels Ferguson , 232.An Bruce Schneier , 233and 234.An Tadayoshi Kohno . 235.Sh CAVEATS 236When 237.Cd "options RANDOM_LOADABLE" 238is enabled, 239the 240.Pa /dev/random 241device is not created 242until an "algorithm module" 243is loaded. 244The only module built by default is 245.Em random_fortuna . 246Loadable random modules 247are less efficient 248than their compiled-in equivalents. 249This is because some functions 250must be locked against 251load and unload events, 252and also must be indirect calls 253to allow for removal. 254.Pp 255When 256.Cd "options RANDOM_ENABLE_UMA" 257is enabled, 258the 259.Pa /dev/random 260device will obtain entropy 261from the zone allocator. 262This is a very high rate source with significant performance impact. 263Therefore, it is disabled by default. 264.Pp 265When 266.Cd "options RANDOM_ENABLE_ETHER" 267is enabled, the 268.Nm 269device will obtain entropy from 270.Vt mbuf 271structures passing through the network stack. 272This source is both extremely expensive and a poor source of entropy, so it is 273disabled by default. 274.Sh SECURITY CONSIDERATIONS 275The initial seeding 276of random number generators 277is a bootstrapping problem 278that needs very careful attention. 279When writable media is available, the 280.Em Fortuna 281paper describes a robust system for rapidly reseeding the device. 282.Pp 283In some embedded cases, it may be difficult to find enough randomness to seed a 284random number generator until a system is fully operational. 285In these cases, is the responsibility of the system architect to ensure that 286blocking is acceptable, or that the random device is seeded. 287(This advice does not apply to typical consumer systems.) 288.Pp 289To emulate embedded systems, developers may set the 290.Va kern.random.block_seeded_status 291tunable to 1 to verify boot does not require early availability of the 292.Nm 293device. 294