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