share/man/man4/random.4

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