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_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.Pp 136The 137.Va kern.random.nist_healthtest_enabled 138tunable can be used to enable the entropy source health tests outlined 139in section 4 of NIST Special Publication 800-90B. 140When enabled, all entropy sources will be subject to the repetition 141count and adaptive proportion tests described in that document. 142If one of the tests fails, the source will be disabled, i.e., all 143subsequent entropy samples from that source will be discarded. 144The implementation performs startup testing, during which entropy 145sources are discarded. 146.Sh FILES 147.Bl -tag -width ".Pa /dev/urandom" 148.It Pa /dev/random 149.It Pa /dev/urandom 150.El 151.Sh DIAGNOSTICS 152The following tunables are related to initial seeding of the 153.Nm 154device: 155.Bl -tag -width 4 156.It Va kern.random.initial_seeding.bypass_before_seeding 157Defaults to 1 (on). 158When set, the system will bypass the 159.Nm 160device prior to initial seeding. 161On is 162.Em unsafe , 163but provides availability on many systems that lack early sources 164of entropy, or cannot load 165.Pa /boot/entropy 166sufficiently early in boot for 167.Nm 168consumers. 169When unset (0), the system will block 170.Xr read_random 9 171and 172.Xr arc4random 9 173requests if and until the 174.Nm 175device is initially seeded. 176.It Va kern.random.initial_seeding.disable_bypass_warnings 177Defaults to 0 (off). 178When set non-zero, disables warnings in dmesg when the 179.Nm 180device is bypassed. 181.El 182.Pp 183The following read-only 184.Xr sysctl 8 185variables allow programmatic diagnostic of whether 186.Nm 187device bypass occurred during boot. 188If they are set (non-zero), the specific functional unit bypassed the strong 189.Nm 190device output and either produced no output 191.Xr ( read_random 9 ) 192or seeded itself with minimal, non-cryptographic entropy 193.Xr ( arc4random 9 ) . 194.Bl -bullet 195.It 196.Va kern.random.initial_seeding.read_random_bypassed_before_seeding 197.It 198.Va kern.random.initial_seeding.arc4random_bypassed_before_seeding 199.El 200.Sh SEE ALSO 201.Xr getrandom 2 , 202.Xr arc4random 3 , 203.Xr getentropy 3 , 204.Xr random 3 , 205.Xr sysctl 8 , 206.Xr random 9 207.Rs 208.%A Ferguson 209.%A Schneier 210.%A Kohno 211.%B Cryptography Engineering 212.%I Wiley 213.%O ISBN 978-0-470-47424-2 214.Re 215.Sh HISTORY 216A 217.Nm 218device appeared in 219.Fx 2.2 . 220The implementation was changed to the 221.Em Yarrow algorithm in 222.Fx 5.0 . 223In 224.Fx 11.0 , 225the Fortuna algorithm was introduced as the default. 226In 227.Fx 12.0 , 228Yarrow was removed entirely. 229.Sh AUTHORS 230.An -nosplit 231The current 232.Nm 233code was authored by 234.An Mark R V Murray , 235with significant contributions from many people. 236.Pp 237The 238.Em Fortuna 239algorithm was designed by 240.An Niels Ferguson , 241.An Bruce Schneier , 242and 243.An Tadayoshi Kohno . 244.Sh CAVEATS 245When 246.Cd "options RANDOM_LOADABLE" 247is enabled, 248the 249.Pa /dev/random 250device is not created 251until an "algorithm module" 252is loaded. 253The only module built by default is 254.Em random_fortuna . 255Loadable random modules 256are less efficient 257than their compiled-in equivalents. 258This is because some functions 259must be locked against 260load and unload events, 261and also must be indirect calls 262to allow for removal. 263.Pp 264When 265.Cd "options RANDOM_ENABLE_UMA" 266is enabled, 267the 268.Pa /dev/random 269device will obtain entropy 270from the zone allocator. 271This is a very high rate source with significant performance impact. 272Therefore, it is disabled by default. 273.Pp 274When 275.Cd "options RANDOM_ENABLE_ETHER" 276is enabled, the 277.Nm 278device will obtain entropy from 279.Vt mbuf 280structures passing through the network stack. 281This source is both extremely expensive and a poor source of entropy, so it is 282disabled by default. 283.Sh SECURITY CONSIDERATIONS 284The initial seeding 285of random number generators 286is a bootstrapping problem 287that needs very careful attention. 288When writable media is available, the 289.Em Fortuna 290paper describes a robust system for rapidly reseeding the device. 291.Pp 292In some embedded cases, it may be difficult to find enough randomness to seed a 293random number generator until a system is fully operational. 294In these cases, is the responsibility of the system architect to ensure that 295blocking is acceptable, or that the random device is seeded. 296(This advice does not apply to typical consumer systems.) 297.Pp 298To emulate embedded systems, developers may set the 299.Va kern.random.block_seeded_status 300tunable to 1 to verify boot does not require early availability of the 301.Nm 302device. 303