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