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