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 15, 2019 27.Dt RANDOM 4 28.Os 29.Sh NAME 30.Nm random 31.Nd the entropy device 32.Sh SYNOPSIS 33.Cd "device random" 34.Cd "options RANDOM_LOADABLE" 35.Cd "options RANDOM_ENABLE_ETHER" 36.Cd "options RANDOM_ENABLE_UMA" 37.Sh DESCRIPTION 38The 39.Nm 40device returns an endless supply of random bytes when read. 41.Pp 42The generator will start in an 43.Em unseeded 44state, and will block reads until it is seeded for the first time. 45.Pp 46To provide prompt access to the random device at boot time, 47.Fx 48automatically persists some entropy data in 49.Pa /boot/entropy 50for the loader to 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' 88.Ed 89.Pp 90Other than 91.Va kern.random.block_seeded_status , 92.Va kern.random.fortuna.minpoolsize , 93and 94.Va kern.random.harvest.mask , 95all settings are read-only. 96.Pp 97The 98.Pa kern.random.fortuna.minpoolsize 99sysctl is used 100to set the seed threshold. 101A smaller number gives a faster seed, 102but a less secure one. 103In practice, 104values between 64 and 256 105are acceptable. 106.Pp 107The 108.Va kern.random.harvest.mask 109bitmask is used to select 110the possible entropy sources. 111A 0 (zero) value means 112the corresponding source 113is not considered 114as an entropy source. 115Set the bit to 1 (one) 116if you wish to use 117that source. 118The 119.Va kern.random.harvest.mask_bin 120and 121.Va kern.random.harvest.mask_symbolic 122sysctls 123can be used to confirm 124settings in a human readable form. 125Disabled items 126in the latter item 127are listed in square brackets. 128See 129.Xr random_harvest 9 130for more on the harvesting of entropy. 131.Sh FILES 132.Bl -tag -width ".Pa /dev/urandom" 133.It Pa /dev/random 134.It Pa /dev/urandom 135.El 136.Sh SEE ALSO 137.Xr getrandom 2 , 138.Xr arc4random 3 , 139.Xr getentropy 3 , 140.Xr random 3 , 141.Xr sysctl 8 , 142.Xr random 9 143.Rs 144.%A Ferguson 145.%A Schneier 146.%A Kohno 147.%B Cryptography Engineering 148.%I Wiley 149.%O ISBN 978-0-470-47424-2 150.Re 151.Sh HISTORY 152A 153.Nm 154device appeared in 155.Fx 2.2 . 156The implementation was changed to the 157.Em Yarrow algorithm in 158.Fx 5.0 . 159In 160.Fx 11.0 , 161the Fortuna algorithm was introduced as the default. 162In 163.Fx 12.0 , 164Yarrow was removed entirely. 165.Sh AUTHORS 166.An -nosplit 167The current 168.Nm 169code was authored by 170.An Mark R V Murray , 171with significant contributions from many people. 172.Pp 173The 174.Em Fortuna 175algorithm was designed by 176.An Niels Ferguson , 177.An Bruce Schneier , 178and 179.An Tadayoshi Kohno . 180.Sh CAVEATS 181When 182.Cd "options RANDOM_LOADABLE" 183is enabled, 184the 185.Pa /dev/random 186device is not created 187until an "algorithm module" 188is loaded. 189The only module built by default is 190.Em random_fortuna . 191Loadable random modules 192are less efficient 193than their compiled-in equivalents. 194This is because some functions 195must be locked against 196load and unload events, 197and also must be indirect calls 198to allow for removal. 199.Pp 200When 201.Cd "options RANDOM_ENABLE_UMA" 202is enabled, 203the 204.Pa /dev/random 205device will obtain entropy 206from the zone allocator. 207This is a very high rate source with significant performance impact. 208Therefore, it is disabled by default. 209.Pp 210When 211.Cd "options RANDOM_ENABLE_ETHER" 212is enabled, the 213.Nm 214device will obtain entropy from 215.Vt mbuf 216structures passing through the network stack. 217This source is both extremely expensive and a poor source of entropy, so it is 218disabled by default. 219.Sh SECURITY CONSIDERATIONS 220The initial seeding 221of random number generators 222is a bootstrapping problem 223that needs very careful attention. 224When writable media is available, the 225.Em Fortuna 226paper describes a robust system for rapidly reseeding the device. 227.Pp 228In some embedded cases, it may be difficult to find enough randomness to seed a 229random number generator until a system is fully operational. 230In these cases, is the responsibility of the system architect to ensure that 231blocking is acceptable, or that the random device is seeded. 232(This advice does not apply to typical consumer systems.) 233.Pp 234To emulate embedded systems, developers may set the 235.Va kern.random.block_seeded_status 236tunable to 1 to verify boot does not require early availability of the 237.Nm 238device. 239