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