share/man/man4/random.4

   1 .\" Copyright (c) 2001-2015     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 June 30, 2015
  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 file.
  41 .Pp
  42 The generator will start in an
  43 .Em unseeded
  44 state, and will block reads until
  45 it is seeded for the first time.
  46 This may cause trouble at system boot
  47 when keys and the like
  48 are generated from
  49 .Xr random 4
  50 so steps should be taken to ensure a
  51 seeding as soon as possible.
  52 .Pp
  53 It is also possible
  54 to read random bytes
  55 by using the KERN_ARND sysctl.
  56 On the command line
  57 this could be done by
  58 .Pp
  59 .Dl "sysctl -x -B 16 kern.arandom"
  60 .Pp
  61 This sysctl will not return
  62 random bytes unless
  63 the
  64 .Xr random 4
  65 device is seeded.
  66 .Pp
  67 This initial seeding
  68 of random number generators
  69 is a bootstrapping problem
  70 that needs very careful attention.
  71 In some cases,
  72 it may be difficult
  73 to find enough randomness
  74 to seed a random number generator
  75 until a system is fully operational,
  76 but the system requires random numbers
  77 to become fully operational.
  78 It is (or more accurately should be)
  79 critically important that the
  80 .Nm
  81 device is seeded
  82 before the first time it is used.
  83 In the case where a dummy or "blocking-only"
  84 device is used,
  85 it is the responsibility
  86 of the system architect
  87 to ensure that no blocking reads
  88 hold up critical processes.
  89 .Pp
  90 To see the current settings of the software
  91 .Nm
  92 device, use the command line:
  93 .Pp
  94 .Dl "sysctl kern.random"
  95 .Pp
  96 which results in something like:
  97 .Bd -literal -offset indent
  98 kern.random.fortuna.minpoolsize: 64
  99 kern.random.harvest.mask_symbolic: [HIGH_PERFORMANCE], ... ,CACHED
 100 kern.random.harvest.mask_bin: 00111111111
 101 kern.random.harvest.mask: 511
 102 kern.random.random_sources: 'Intel Secure Key RNG'
 103 .Ed
 104 .Pp
 105 Other than
 106 .Dl kern.random.fortuna.minpoolsize
 107 and
 108 .Dl kern.random.harvest.mask
 109 all settings are read-only.
 110 .Pp
 111 The
 112 .Pa kern.random.fortuna.minpoolsize
 113 sysctl is used
 114 to set the seed threshhold.
 115 A smaller number gives a faster seed,
 116 but a less secure one.
 117 In practice,
 118 values between 64 and 256
 119 are acceptable.
 120 .Pp
 121 The
 122 .Va kern.random.harvest.mask
 123 bitmask is used to select
 124 the possible entropy sources.
 125 A 0 (zero) value means
 126 the corresponding source
 127 is not considered
 128 as an entropy source.
 129 Set the bit to 1 (one)
 130 if you wish to use
 131 that source.
 132 The
 133 .Va kern.random.harvest.mask_bin
 134 and
 135 .Va kern.random.harvest.mask_symbolic
 136 sysctl
 137 can be used confirm
 138 that your choices are correct.
 139 Note that disabled items
 140 in the latter item
 141 are listed in square brackets.
 142 See
 143 .Xr random_harvest 9
 144 for more on the harvesting of entropy.
 145 .Sh RANDOMNESS
 146 The use of randomness in the field of computing
 147 is a rather subtle issue because randomness means
 148 different things to different people.
 149 Consider generating a password randomly,
 150 simulating a coin tossing experiment or
 151 choosing a random back-off period when a server does not respond.
 152 Each of these tasks requires random numbers,
 153 but the random numbers in each case have different requirements.
 154 .Pp
 155 Generation of passwords, session keys and the like
 156 requires cryptographic randomness.
 157 A cryptographic random number generator should be designed
 158 so that its output is difficult to guess,
 159 even if a lot of auxiliary information is known
 160 (such as when it was seeded, subsequent or previous output, and so on).
 161 On
 162 .Fx ,
 163 seeding for cryptographic random number generators is provided by the
 164 .Nm
 165 device,
 166 which provides real randomness.
 167 The
 168 .Xr arc4random 3
 169 library call provides a pseudo-random sequence
 170 which is generally reckoned to be suitable for
 171 simple cryptographic use.
 172 The OpenSSL library also provides functions for managing randomness
 173 via functions such as
 174 .Xr RAND_bytes 3
 175 and
 176 .Xr RAND_add 3 .
 177 Note that OpenSSL uses the
 178 .Nm
 179 device for seeding automatically.
 180 .Pp
 181 Randomness for simulation is required in engineering or
 182 scientific software and games.
 183 The first requirement of these applications is
 184 that the random numbers produced conform to some well-known,
 185 usually uniform, distribution.
 186 The sequence of numbers should also appear numerically uncorrelated,
 187 as simulation often assumes independence of its random inputs.
 188 Often it is desirable to reproduce
 189 the results of a simulation exactly,
 190 so that if the generator is seeded in the same way,
 191 it should produce the same results.
 192 A peripheral concern for simulation is
 193 the speed of a random number generator.
 194 .Pp
 195 Another issue in simulation is
 196 the size of the state associated with the random number generator, and
 197 how frequently it repeats itself.
 198 For example,
 199 a program which shuffles a pack of cards should have 52!\& possible outputs,
 200 which requires the random number generator to have 52!\& starting states.
 201 This means the seed should have at least log_2(52!) ~ 226 bits of state
 202 if the program is to stand a chance of outputting all possible sequences,
 203 and the program needs some unbiased way of generating these bits.
 204 Again,
 205 the
 206 .Nm
 207 device could be used for seeding here,
 208 but in practice, smaller seeds are usually considered acceptable.
 209 .Pp
 210 .Fx
 211 provides two families of functions which are considered
 212 suitable for simulation.
 213 The
 214 .Xr random 3
 215 family of functions provides a random integer
 216 between 0 to
 217 .if t 2\u\s731\s10\d\(mi1.
 218 .if n (2**31)\(mi1.
 219 The functions
 220 .Xr srandom 3 ,
 221 .Xr initstate 3
 222 and
 223 .Xr setstate 3
 224 are provided for deterministically setting
 225 the state of the generator and
 226 the function
 227 .Xr srandomdev 3
 228 is provided for setting the state via the
 229 .Nm
 230 device.
 231 The
 232 .Xr drand48 3
 233 family of functions are also provided,
 234 which provide random floating point numbers in various ranges.
 235 .Pp
 236 Randomness that is used for collision avoidance
 237 (for example, in certain network protocols)
 238 has slightly different semantics again.
 239 It is usually expected that the numbers will be uniform,
 240 as this produces the lowest chances of collision.
 241 Here again,
 242 the seeding of the generator is very important,
 243 as it is required that different instances of
 244 the generator produce independent sequences.
 245 However, the guessability or reproducibility of the sequence is unimportant,
 246 unlike the previous cases.
 247 .Pp
 248 .Fx
 249 does also provide the traditional
 250 .Xr rand 3
 251 library call,
 252 for compatibility purposes.
 253 However,
 254 it is known to be poor for simulation and
 255 absolutely unsuitable for cryptographic purposes,
 256 so its use is discouraged.
 257 .Sh FILES
 258 .Bl -tag -width ".Pa /dev/random"
 259 .It Pa /dev/random
 260 .El
 261 .Sh SEE ALSO
 262 .Xr arc4random 3 ,
 263 .Xr drand48 3 ,
 264 .Xr rand 3 ,
 265 .Xr RAND_add 3 ,
 266 .Xr RAND_bytes 3 ,
 267 .Xr random 3 ,
 268 .Xr sysctl 8 ,
 269 .Xr random 9
 270 .Rs
 271 .%A Ferguson
 272 .%A Schneier
 273 .%A Kohno
 274 .%B Cryptography Engineering
 275 .%I Wiley
 276 .%O ISBN 978-0-470-47424-2
 277 .Re
 278 .Sh HISTORY
 279 A
 280 .Nm
 281 device appeared in
 282 .Fx 2.2 .
 283 The current software implementation,
 284 introduced in
 285 .Fx 10.0 ,
 286 is by
 287 .An Mark R V Murray ,
 288 and is an implementation of the
 289 .Em Fortuna
 290 algorithm by Ferguson
 291 .Em et al .
 292 It replaces the previous
 293 .Em Yarrow
 294 implementation,
 295 introduced in
 296 .Fx 5.0 .
 297 The older
 298 .Em Yarrow
 299 algorithm remains available
 300 as a compile-time fallback.