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