share/man/man9/random.9

   1 .\"
   2 .\" Copyright (c) 2015
   3 .\"     Mark R V Murray
   4 .\" Copyright (c) 2000
   5 .\"     The Regents of the University of California.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  17 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  18 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  19 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  20 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  21 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  22 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  23 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  25 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\" "
  29 .Dd July 16, 2015
  30 .Dt RANDOM 9
  31 .Os
  32 .Sh NAME
  33 .Nm arc4rand ,
  34 .Nm arc4random ,
  35 .Nm random ,
  36 .Nm read_random ,
  37 .Nm read_random_uio ,
  38 .Nm srandom
  39 .Nd supply pseudo-random numbers
  40 .Sh SYNOPSIS
  41 .In sys/libkern.h
  42 .Ft void
  43 .Fn srandom "u_long seed"
  44 .Ft u_long
  45 .Fn random "void"
  46 .Ft void
  47 .Fn arc4rand "void *ptr" "u_int length" "int reseed"
  48 .Ft uint32_t
  49 .Fn arc4random "void"
  50 .Pp
  51 .In sys/random.h
  52 .Ft int
  53 .Fn read_random "void *buffer" "int count"
  54 .Ft int
  55 .Fn read_random_uio "struct uio *uio" "bool nonblock"
  56 .Sh DESCRIPTION
  57 The
  58 .Fn random
  59 function will by default produce
  60 a sequence of numbers
  61 that can be duplicated
  62 by calling
  63 .Fn srandom
  64 with some constant
  65 as the
  66 .Fa seed .
  67 The
  68 .Fn srandom
  69 function may be called with any arbitrary
  70 .Fa seed
  71 value to get slightly more unpredictable numbers.
  72 It is important to remember that the
  73 .Fn random
  74 function is entirely predictable,
  75 and is therefore not of use where
  76 knowledge of the sequence of numbers
  77 may be of benefit to an attacker.
  78 .Pp
  79 The
  80 .Fn arc4rand
  81 function will return very good quality random numbers,
  82 better suited
  83 for security-related purposes.
  84 The random numbers from
  85 .Fn arc4rand
  86 are seeded from the entropy device
  87 if it is available.
  88 Automatic reseeds happen
  89 after a certain timeinterval
  90 and after a certain number of bytes
  91 have been delivered.
  92 A forced reseed
  93 can be forced
  94 by passing a non-zero
  95 value in the
  96 .Fa reseed
  97 argument.
  98 .Pp
  99 The
 100 .Fn read_random
 101 function is used to return entropy directly from the entropy device
 102 if it has been loaded.
 103 If the entropy device is not loaded, then
 104 the
 105 .Fa buffer
 106 is ignored
 107 and zero is returned.
 108 The
 109 .Fa buffer
 110 is filled with no more than
 111 .Fa count
 112 bytes.
 113 It is strongly advised that
 114 .Fn read_random
 115 is not used;
 116 instead use
 117 .Fn arc4rand
 118 unless it is
 119 necessary to know
 120 that no entropy
 121 has been returned.
 122 .Pp
 123 The
 124 .Fn read_random_uio
 125 function behaves identically to
 126 .Xr read 2
 127 on
 128 .Pa /dev/random .
 129 The
 130 .Fa uio
 131 argument points to a buffer where random data should be stored.
 132 This function only returns data if the random device is seeded.
 133 It blocks if unseeded,
 134 except when the
 135 .Fa nonblock
 136 argument is true.
 137 .Pp
 138 All the bits returned by
 139 .Fn random ,
 140 .Fn arc4rand ,
 141 .Fn read_random ,
 142 and
 143 .Fn read_random_uio
 144 are usable.
 145 For example,
 146 .Sq Li random()&01
 147 will produce a random binary value.
 148 .Pp
 149 The
 150 .Fn arc4random
 151 is a convenience function which calls
 152 .Fn arc4rand
 153 to return a 32 bit pseudo-random integer.
 154 .Sh RETURN VALUES
 155 The
 156 .Fn random
 157 function uses
 158 a non-linear additive feedback random number generator
 159 employing a default table
 160 of size 31
 161 containing long integers
 162 to return successive pseudo-random
 163 numbers in the range from 0 to
 164 .if t 2\u\s731\s10\d\(mi1.
 165 .if n (2**31)\(mi1.
 166 The period of this random number generator
 167 is very large,
 168 approximately
 169 .if t 16\(mu(2\u\s731\s10\d\(mi1).
 170 .if n 16*((2**31)\(mi1).
 171 .Pp
 172 The
 173 .Fn arc4rand
 174 function uses the RC4 algorithm
 175 to generate successive pseudo-random bytes.
 176 The
 177 .Fn arc4random
 178 function uses
 179 .Fn arc4rand
 180 to generate pseudo-random numbers
 181 in the range from 0 to
 182 .if t 2\u\s732\s10\d\(mi1.
 183 .if n (2**32)\(mi1.
 184 .Pp
 185 The
 186 .Fn read_random
 187 function returns
 188 the number of bytes placed in
 189 .Fa buffer .
 190 .Pp
 191 .Fn read_random_uio
 192 returns zero when successful,
 193 otherwise an error code is returned.
 194 .Sh ERRORS
 195 .Fn read_random_uio
 196 may fail if:
 197 .Bl -tag -width Er
 198 .It Bq Er EFAULT
 199 .Fa uio
 200 points to an invalid memory region.
 201 .It Bq Er EWOULDBLOCK
 202 The random device is unseeded and
 203 .Fa nonblock
 204 is true.
 205 .El
 206 .Sh AUTHORS
 207 .An Dan Moschuk
 208 wrote
 209 .Fn arc4random .
 210 .An Mark R V Murray
 211 wrote
 212 .Fn read_random .