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