share/man/man4/random.4

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