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