1.\" Copyright (c) 2001 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 7, 2013 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.Sh DESCRIPTION 35The 36.Nm 37device 38returns an endless supply of random bytes when read. 39It also accepts and reads data 40as any ordinary (and willing) file, 41but discards data written to it. 42The device will probe for 43certain hardware entropy sources, 44and use these in preference to the fallback, 45which is a generator implemented in software. 46If the kernel environment MIB's 47.Va hw.nehemiah_rng_enable 48or 49.Va hw.ivy_rng_enable 50are set to 51.Dq Li 0 , 52the associated hardware entropy source will be ignored. 53.Pp 54If the device is using 55the software generator, 56writing data to 57.Nm 58would perturb the internal state. 59This perturbation of the internal state 60is the only userland method of introducing 61extra entropy into the device. 62If the writer has superuser privilege, 63then closing the device after writing 64will make the software generator reseed itself. 65This can be used for extra security, 66as it immediately introduces any/all new entropy 67into the PRNG. 68The hardware generators will generate 69sufficient quantities of entropy, 70and will therefore ignore user-supplied input. 71The software 72.Nm 73device may be controlled with 74.Xr sysctl 8 . 75.Pp 76To see the current settings of the software 77.Nm 78device, use the command line: 79.Pp 80.Dl sysctl kern.random 81.Pp 82which results in something like: 83.Bd -literal -offset indent 84kern.random.adaptors: yarrow 85kern.random.sys.seeded: 1 86kern.random.sys.harvest.ethernet: 1 87kern.random.sys.harvest.point_to_point: 1 88kern.random.sys.harvest.interrupt: 1 89kern.random.sys.harvest.swi: 0 90kern.random.yarrow.gengateinterval: 10 91kern.random.yarrow.bins: 10 92kern.random.yarrow.fastthresh: 192 93kern.random.yarrow.slowthresh: 256 94kern.random.yarrow.slowoverthresh: 2 95.Ed 96.Pp 97(These would not be seen if a 98hardware generator is present.) 99.Pp 100Other than 101.Dl kern.random.adaptors 102all settings are read/write. 103.Pp 104The 105.Va kern.random.sys.seeded 106variable indicates whether or not the 107.Nm 108device is in an acceptably secure state 109as a result of reseeding. 110If set to 0, the device will block (on read) until the next reseed 111(which can be from an explicit write, 112or as a result of entropy harvesting). 113A reseed will set the value to 1 (non-blocking). 114.Pp 115The 116.Va kern.random.sys.harvest.ethernet 117variable is used to select LAN traffic as an entropy source. 118A 0 (zero) value means that LAN traffic 119is not considered as an entropy source. 120Set the variable to 1 (one) 121if you wish to use LAN traffic for entropy harvesting. 122.Pp 123The 124.Va kern.random.sys.harvest.point_to_point 125variable is used to select serial line traffic as an entropy source. 126(Serial line traffic includes PPP, SLIP and all tun0 traffic.) 127A 0 (zero) value means such traffic 128is not considered as an entropy source. 129Set the variable to 1 (one) 130if you wish to use it for entropy harvesting. 131.Pp 132The 133.Va kern.random.sys.harvest.interrupt 134variable is used to select hardware interrupts 135as an entropy source. 136A 0 (zero) value means hardware interrupts 137are not considered as an entropy source. 138Set the variable to 1 (one) 139if you wish to use them for entropy harvesting. 140All hardware interrupt harvesting is set up by the 141individual device drivers. 142.Pp 143The 144.Va kern.random.sys.harvest.swi 145variable is used to select software interrupts 146as an entropy source. 147A 0 (zero) value means software interrupts 148are not considered as an entropy source. 149Set the variable to 1 (one) 150if you wish to use them for entropy harvesting. 151.Pp 152The other variables are explained in the paper describing the 153.Em Yarrow 154algorithm at 155.Pa http://www.schneier.com/yarrow.html . 156.Pp 157These variables are all limited 158in terms of the values they may contain: 159.Bl -tag -width "kern.random.yarrow.gengateinterval" -compact -offset indent 160.It Va kern.random.yarrow.gengateinterval 161.Bq 4..64 162.It Va kern.random.yarrow.bins 163.Bq 2..16 164.It Va kern.random.yarrow.fastthresh 165.Bq 64..256 166.It Va kern.random.yarrow.slowthresh 167.Bq 64..256 168.It Va kern.random.yarrow.slowoverthresh 169.Bq 1..5 170.El 171.Pp 172Internal 173.Xr sysctl 3 174handlers force the above variables 175into the stated ranges. 176.Sh RANDOMNESS 177The use of randomness in the field of computing 178is a rather subtle issue because randomness means 179different things to different people. 180Consider generating a password randomly, 181simulating a coin tossing experiment or 182choosing a random back-off period when a server does not respond. 183Each of these tasks requires random numbers, 184but the random numbers in each case have different requirements. 185.Pp 186Generation of passwords, session keys and the like 187requires cryptographic randomness. 188A cryptographic random number generator should be designed 189so that its output is difficult to guess, 190even if a lot of auxiliary information is known 191(such as when it was seeded, subsequent or previous output, and so on). 192On 193.Fx , 194seeding for cryptographic random number generators is provided by the 195.Nm 196device, 197which provides real randomness. 198The 199.Xr arc4random 3 200library call provides a pseudo-random sequence 201which is generally reckoned to be suitable for 202simple cryptographic use. 203The OpenSSL library also provides functions for managing randomness 204via functions such as 205.Xr RAND_bytes 3 206and 207.Xr RAND_add 3 . 208Note that OpenSSL uses the 209.Nm 210device for seeding automatically. 211.Pp 212Randomness for simulation is required in engineering or 213scientific software and games. 214The first requirement of these applications is 215that the random numbers produced conform to some well-known, 216usually uniform, distribution. 217The sequence of numbers should also appear numerically uncorrelated, 218as simulation often assumes independence of its random inputs. 219Often it is desirable to reproduce 220the results of a simulation exactly, 221so that if the generator is seeded in the same way, 222it should produce the same results. 223A peripheral concern for simulation is 224the speed of a random number generator. 225.Pp 226Another issue in simulation is 227the size of the state associated with the random number generator, and 228how frequently it repeats itself. 229For example, 230a program which shuffles a pack of cards should have 52!\& possible outputs, 231which requires the random number generator to have 52!\& starting states. 232This means the seed should have at least log_2(52!) ~ 226 bits of state 233if the program is to stand a chance of outputting all possible sequences, 234and the program needs some unbiased way of generating these bits. 235Again, 236the 237.Nm 238device could be used for seeding here, 239but in practice, smaller seeds are usually considered acceptable. 240.Pp 241.Fx 242provides two families of functions which are considered 243suitable for simulation. 244The 245.Xr random 3 246family of functions provides a random integer 247between 0 to 248.if t 2\u\s731\s10\d\(mi1. 249.if n (2**31)\(mi1. 250The functions 251.Xr srandom 3 , 252.Xr initstate 3 253and 254.Xr setstate 3 255are provided for deterministically setting 256the state of the generator and 257the function 258.Xr srandomdev 3 259is provided for setting the state via the 260.Nm 261device. 262The 263.Xr drand48 3 264family of functions are also provided, 265which provide random floating point numbers in various ranges. 266.Pp 267Randomness that is used for collision avoidance 268(for example, in certain network protocols) 269has slightly different semantics again. 270It is usually expected that the numbers will be uniform, 271as this produces the lowest chances of collision. 272Here again, 273the seeding of the generator is very important, 274as it is required that different instances of 275the generator produce independent sequences. 276However, the guessability or reproducibility of the sequence is unimportant, 277unlike the previous cases. 278.Pp 279One final consideration for the seeding of random number generators 280is a bootstrapping problem. 281In some cases, it may be difficult to find enough randomness to 282seed a random number generator until a system is fully operational, 283but the system requires random numbers to become fully operational. 284There is no substitute for careful thought here, 285but the 286.Fx 287.Nm 288device, 289which is based on the Yarrow system, 290should be of some help in this area. 291.Pp 292.Fx 293does also provide the traditional 294.Xr rand 3 295library call, 296for compatibility purposes. 297However, 298it is known to be poor for simulation and 299absolutely unsuitable for cryptographic purposes, 300so its use is discouraged. 301.Sh FILES 302.Bl -tag -width ".Pa /dev/random" 303.It Pa /dev/random 304.El 305.Sh SEE ALSO 306.Xr arc4random 3 , 307.Xr drand48 3 , 308.Xr rand 3 , 309.Xr RAND_add 3 , 310.Xr RAND_bytes 3 , 311.Xr random 3 , 312.Xr sysctl 8 313.Sh HISTORY 314A 315.Nm 316device appeared in 317.Fx 2.2 . 318The early version was taken from Theodore Ts'o's entropy driver for Linux. 319The current software implementation, 320introduced in 321.Fx 5.0 , 322is a complete rewrite by 323.An Mark R V Murray , 324and is an implementation of the 325.Em Yarrow 326algorithm by Bruce Schneier, 327.Em et al . 328The only hardware implementations 329currently are for the 330.Tn VIA C3 Nehemiah 331(stepping 3 or greater) 332CPU 333and the 334.Tn Intel 335.Dq Bull Mountain 336.Em RdRand 337instruction and underlying random number generator (RNG). 338More will be added in the future. 339.Pp 340The author gratefully acknowledges 341significant assistance from VIA Technologies, Inc. 342