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