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