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