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