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 August 17, 2015 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.Sh DESCRIPTION 36The 37.Nm 38device 39returns an endless supply of random bytes when read. 40It also accepts and reads data 41as any ordinary file. 42.Pp 43The generator will start in an 44.Em unseeded 45state, and will block reads until 46it is seeded for the first time. 47This may cause trouble at system boot 48when keys and the like 49are generated from 50.Xr random 4 51so steps should be taken to ensure a 52seeding as soon as possible. 53.Pp 54It is also possible 55to read random bytes 56by using the KERN_ARND sysctl. 57On the command line 58this could be done by 59.Pp 60.Dl "sysctl -x -B 16 kern.arandom" 61.Pp 62This sysctl will not return 63random bytes unless 64the 65.Xr random 4 66device is seeded. 67.Pp 68This initial seeding 69of random number generators 70is a bootstrapping problem 71that needs very careful attention. 72In some cases, 73it may be difficult 74to find enough randomness 75to seed a random number generator 76until a system is fully operational, 77but the system requires random numbers 78to become fully operational. 79It is (or more accurately should be) 80critically important that the 81.Nm 82device is seeded 83before the first time it is used. 84In the case where a dummy or "blocking-only" 85device is used, 86it is the responsibility 87of the system architect 88to ensure that no blocking reads 89hold up critical processes. 90.Pp 91To see the current settings of the software 92.Nm 93device, use the command line: 94.Pp 95.Dl "sysctl kern.random" 96.Pp 97which results in something like: 98.Bd -literal -offset indent 99kern.random.fortuna.minpoolsize: 64 100kern.random.harvest.mask_symbolic: [HIGH_PERFORMANCE], ... ,CACHED 101kern.random.harvest.mask_bin: 00111111111 102kern.random.harvest.mask: 511 103kern.random.random_sources: 'Intel Secure Key RNG' 104.Ed 105.Pp 106Other than 107.Dl kern.random.fortuna.minpoolsize 108and 109.Dl kern.random.harvest.mask 110all settings are read-only. 111.Pp 112The 113.Pa kern.random.fortuna.minpoolsize 114sysctl is used 115to set the seed threshhold. 116A smaller number gives a faster seed, 117but a less secure one. 118In practice, 119values between 64 and 256 120are acceptable. 121.Pp 122The 123.Va kern.random.harvest.mask 124bitmask is used to select 125the possible entropy sources. 126A 0 (zero) value means 127the corresponding source 128is not considered 129as an entropy source. 130Set the bit to 1 (one) 131if you wish to use 132that source. 133The 134.Va kern.random.harvest.mask_bin 135and 136.Va kern.random.harvest.mask_symbolic 137sysctls 138can be used to confirm 139that the choices are correct. 140Note that disabled items 141in the latter item 142are listed in square brackets. 143See 144.Xr random_harvest 9 145for more on the harvesting of entropy. 146.Pp 147When 148.Cd "options RANDOM_LOADABLE" 149is used, 150the 151.Pa /dev/random 152device is not created 153until an "algorithm module" 154is loaded. 155Two of these modules 156are built by default, 157.Em random_fortuna 158and 159.Em random_yarrow . 160The 161.Em random_yarrow 162module is deprecated, 163and will be removed in 164.Fx 12. 165Use of the Yarrow algorithm 166is not encouraged, 167but while still present 168in the kernel source, 169it can be selected with the 170.Cd "options RANDOM_YARROW" 171kernel option. 172Note that these loadable modules 173are slightly less efficient 174than their compiled-in equivalents. 175This is because some functions 176must be locked against 177load and unload events, 178and also must be indirect calls 179to allow for removal. 180.Sh RANDOMNESS 181The use of randomness in the field of computing 182is a rather subtle issue because randomness means 183different things to different people. 184Consider generating a password randomly, 185simulating a coin tossing experiment or 186choosing a random back-off period when a server does not respond. 187Each of these tasks requires random numbers, 188but the random numbers in each case have different requirements. 189.Pp 190Generation of passwords, session keys and the like 191requires cryptographic randomness. 192A cryptographic random number generator should be designed 193so that its output is difficult to guess, 194even if a lot of auxiliary information is known 195(such as when it was seeded, subsequent or previous output, and so on). 196On 197.Fx , 198seeding for cryptographic random number generators is provided by the 199.Nm 200device, 201which provides real randomness. 202The 203.Xr arc4random 3 204library call provides a pseudo-random sequence 205which is generally reckoned to be suitable for 206simple cryptographic use. 207The OpenSSL library also provides functions for managing randomness 208via functions such as 209.Xr RAND_bytes 3 210and 211.Xr RAND_add 3 . 212Note that OpenSSL uses the 213.Nm 214device for seeding automatically. 215.Pp 216Randomness for simulation is required in engineering or 217scientific software and games. 218The first requirement of these applications is 219that the random numbers produced conform to some well-known, 220usually uniform, distribution. 221The sequence of numbers should also appear numerically uncorrelated, 222as simulation often assumes independence of its random inputs. 223Often it is desirable to reproduce 224the results of a simulation exactly, 225so that if the generator is seeded in the same way, 226it should produce the same results. 227A peripheral concern for simulation is 228the speed of a random number generator. 229.Pp 230Another issue in simulation is 231the size of the state associated with the random number generator, and 232how frequently it repeats itself. 233For example, 234a program which shuffles a pack of cards should have 52!\& possible outputs, 235which requires the random number generator to have 52!\& starting states. 236This means the seed should have at least log_2(52!) ~ 226 bits of state 237if the program is to stand a chance of outputting all possible sequences, 238and the program needs some unbiased way of generating these bits. 239Again, 240the 241.Nm 242device could be used for seeding here, 243but in practice, smaller seeds are usually considered acceptable. 244.Pp 245.Fx 246provides two families of functions which are considered 247suitable for simulation. 248The 249.Xr random 3 250family of functions provides a random integer 251between 0 to 252.if t 2\u\s731\s10\d\(mi1. 253.if n (2**31)\(mi1. 254The functions 255.Xr srandom 3 , 256.Xr initstate 3 257and 258.Xr setstate 3 259are provided for deterministically setting 260the state of the generator and 261the function 262.Xr srandomdev 3 263is provided for setting the state via the 264.Nm 265device. 266The 267.Xr drand48 3 268family of functions are also provided, 269which provide random floating point numbers in various ranges. 270.Pp 271Randomness that is used for collision avoidance 272(for example, in certain network protocols) 273has slightly different semantics again. 274It is usually expected that the numbers will be uniform, 275as this produces the lowest chances of collision. 276Here again, 277the seeding of the generator is very important, 278as it is required that different instances of 279the generator produce independent sequences. 280However, the guessability or reproducibility of the sequence is unimportant, 281unlike the previous cases. 282.Pp 283.Fx 284does also provide the traditional 285.Xr rand 3 286library call, 287for compatibility purposes. 288However, 289it is known to be poor for simulation and 290absolutely unsuitable for cryptographic purposes, 291so its use is discouraged. 292.Sh FILES 293.Bl -tag -width ".Pa /dev/random" 294.It Pa /dev/random 295.El 296.Sh SEE ALSO 297.Xr arc4random 3 , 298.Xr drand48 3 , 299.Xr rand 3 , 300.Xr RAND_add 3 , 301.Xr RAND_bytes 3 , 302.Xr random 3 , 303.Xr sysctl 8 , 304.Xr random 9 305.Rs 306.%A Ferguson 307.%A Schneier 308.%A Kohno 309.%B Cryptography Engineering 310.%I Wiley 311.%O ISBN 978-0-470-47424-2 312.Re 313.Sh HISTORY 314A 315.Nm 316device appeared in 317.Fx 2.2 . 318The current software implementation, 319introduced in 320.Fx 10.0 , 321is by 322.An Mark R V Murray , 323and is an implementation of the 324.Em Fortuna 325algorithm by Ferguson 326.Em et al . 327It replaces the previous 328.Em Yarrow 329implementation, 330introduced in 331.Fx 5.0 . 332The Yarrow algorithm 333is no longer supported 334by its authors, 335and is therefore deprecated. 336