1.\" Copyright (c) 2001-2013 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 12, 2013 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 47The software generator will start in an 48.Em unseeded 49state, and will block reads until 50it is (re)seeded. 51This may cause trouble at system boot 52when keys and the like 53are generated from 54/dev/random 55so steps should be taken to ensure a 56reseed as soon as possible. 57The 58.Xr sysctl 8 59controlling the 60.Em seeded 61status (see below) may be used 62if security is not an issue 63or for convenience 64during setup or development. 65.Pp 66This initial seeding 67of random number generators 68is a bootstrapping problem 69that needs very careful attention. 70In some cases, 71it may be difficult 72to find enough randomness 73to seed a random number generator 74until a system is fully operational, 75but the system requires random numbers 76to become fully operational. 77It is (or more accurately should be) 78critically important that the 79.Nm 80device is seeded 81before the first time it is used. 82In the case where a dummy or "blocking-only" 83device is used, 84it is the responsibility 85of the system architect 86to ensure that no blocking reads 87hold up critical processes. 88.Pp 89To see the current settings of the software 90.Nm 91device, use the command line: 92.Pp 93.Dl sysctl kern.random 94.Pp 95which results in something like: 96.Bd -literal -offset indent 97kern.random.adaptors: yarrow,dummy 98kern.random.active_adaptor: yarrow 99kern.random.yarrow.gengateinterval: 10 100kern.random.yarrow.bins: 10 101kern.random.yarrow.fastthresh: 96 102kern.random.yarrow.slowthresh: 128 103kern.random.yarrow.slowoverthresh: 2 104kern.random.sys.seeded: 1 105kern.random.sys.harvest.ethernet: 1 106kern.random.sys.harvest.point_to_point: 1 107kern.random.sys.harvest.interrupt: 1 108kern.random.sys.harvest.swi: 1 109.Ed 110.Pp 111Other than 112.Dl kern.random.adaptors 113all settings are read/write. 114.Pp 115The 116.Va kern.random.sys.seeded 117variable indicates whether or not the 118.Nm 119device is in an acceptably secure state 120as a result of reseeding. 121If set to 0, 122the device will block (on read) 123until the next reseed 124as a result of entropy harvesting. 125A reseed will set the value to 1 (non-blocking). 126.Pp 127The 128.Va kern.random.sys.harvest.ethernet 129variable is used to select LAN traffic as an entropy source. 130A 0 (zero) value means that LAN traffic 131is not considered as an entropy source. 132Set the variable to 1 (one) 133if you wish to use LAN traffic for entropy harvesting. 134.Pp 135The 136.Va kern.random.sys.harvest.point_to_point 137variable is used to select serial line traffic as an entropy source. 138(Serial line traffic includes PPP, SLIP and all tun0 traffic.) 139A 0 (zero) value means such traffic 140is not considered as an entropy source. 141Set the variable to 1 (one) 142if you wish to use it for entropy harvesting. 143.Pp 144The 145.Va kern.random.sys.harvest.interrupt 146variable is used to select hardware interrupts 147as an entropy source. 148A 0 (zero) value means hardware interrupts 149are not considered as an entropy source. 150Set the variable to 1 (one) 151if you wish to use them for entropy harvesting. 152All hardware interrupt harvesting is set up by the 153individual device drivers. 154.Pp 155The 156.Va kern.random.sys.harvest.swi 157variable is used to select software interrupts 158as an entropy source. 159A 0 (zero) value means software interrupts 160are not considered as an entropy source. 161Set the variable to 1 (one) 162if you wish to use them for entropy harvesting. 163.Pp 164The other variables are explained in the paper describing the 165.Em Yarrow 166algorithm at 167.Pa http://www.schneier.com/yarrow.html . 168.Pp 169These variables are all limited 170in terms of the values they may contain: 171.Bl -tag -width "kern.random.yarrow.gengateinterval" -compact -offset indent 172.It Va kern.random.yarrow.gengateinterval 173.Bq 4..64 174.It Va kern.random.yarrow.bins 175.Bq 2..16 176.It Va kern.random.yarrow.fastthresh 177.Bq 64..256 178.It Va kern.random.yarrow.slowthresh 179.Bq 64..256 180.It Va kern.random.yarrow.slowoverthresh 181.Bq 1..5 182.El 183.Pp 184Internal 185.Xr sysctl 3 186handlers force the above variables 187into the stated ranges. 188.Sh RANDOMNESS 189The use of randomness in the field of computing 190is a rather subtle issue because randomness means 191different things to different people. 192Consider generating a password randomly, 193simulating a coin tossing experiment or 194choosing a random back-off period when a server does not respond. 195Each of these tasks requires random numbers, 196but the random numbers in each case have different requirements. 197.Pp 198Generation of passwords, session keys and the like 199requires cryptographic randomness. 200A cryptographic random number generator should be designed 201so that its output is difficult to guess, 202even if a lot of auxiliary information is known 203(such as when it was seeded, subsequent or previous output, and so on). 204On 205.Fx , 206seeding for cryptographic random number generators is provided by the 207.Nm 208device, 209which provides real randomness. 210The 211.Xr arc4random 3 212library call provides a pseudo-random sequence 213which is generally reckoned to be suitable for 214simple cryptographic use. 215The OpenSSL library also provides functions for managing randomness 216via functions such as 217.Xr RAND_bytes 3 218and 219.Xr RAND_add 3 . 220Note that OpenSSL uses the 221.Nm 222device for seeding automatically. 223.Pp 224Randomness for simulation is required in engineering or 225scientific software and games. 226The first requirement of these applications is 227that the random numbers produced conform to some well-known, 228usually uniform, distribution. 229The sequence of numbers should also appear numerically uncorrelated, 230as simulation often assumes independence of its random inputs. 231Often it is desirable to reproduce 232the results of a simulation exactly, 233so that if the generator is seeded in the same way, 234it should produce the same results. 235A peripheral concern for simulation is 236the speed of a random number generator. 237.Pp 238Another issue in simulation is 239the size of the state associated with the random number generator, and 240how frequently it repeats itself. 241For example, 242a program which shuffles a pack of cards should have 52!\& possible outputs, 243which requires the random number generator to have 52!\& starting states. 244This means the seed should have at least log_2(52!) ~ 226 bits of state 245if the program is to stand a chance of outputting all possible sequences, 246and the program needs some unbiased way of generating these bits. 247Again, 248the 249.Nm 250device could be used for seeding here, 251but in practice, smaller seeds are usually considered acceptable. 252.Pp 253.Fx 254provides two families of functions which are considered 255suitable for simulation. 256The 257.Xr random 3 258family of functions provides a random integer 259between 0 to 260.if t 2\u\s731\s10\d\(mi1. 261.if n (2**31)\(mi1. 262The functions 263.Xr srandom 3 , 264.Xr initstate 3 265and 266.Xr setstate 3 267are provided for deterministically setting 268the state of the generator and 269the function 270.Xr srandomdev 3 271is provided for setting the state via the 272.Nm 273device. 274The 275.Xr drand48 3 276family of functions are also provided, 277which provide random floating point numbers in various ranges. 278.Pp 279Randomness that is used for collision avoidance 280(for example, in certain network protocols) 281has slightly different semantics again. 282It is usually expected that the numbers will be uniform, 283as this produces the lowest chances of collision. 284Here again, 285the seeding of the generator is very important, 286as it is required that different instances of 287the generator produce independent sequences. 288However, the guessability or reproducibility of the sequence is unimportant, 289unlike the previous cases. 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 . 327Significant infrastructure work was done by Arthur Mesh. 328.Pp 329The author gratefully acknowledges 330significant assistance from VIA Technologies, Inc. 331