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 April 16, 2019
  30 .Dt RANDOM 9
  31 .Os
  32 .Sh NAME
  33 .Nm arc4rand ,
  34 .Nm arc4random ,
  35 .Nm arc4random_buf ,
  36 .Nm is_random_seeded ,
  37 .Nm random ,
  38 .Nm read_random ,
  39 .Nm read_random_uio ,
  40 .Nm srandom
  41 .Nd supply pseudo-random numbers
  42 .Sh SYNOPSIS
  43 .In sys/libkern.h
  44 .Ft uint32_t
  45 .Fn arc4random "void"
  46 .Ft void
  47 .Fn arc4random_buf "void *ptr" "size_t len"
  48 .Ft void
  49 .Fn arc4rand "void *ptr" "u_int length" "int reseed"
  50 .Pp
  51 .In sys/random.h
  52 .Ft bool
  53 .Fn is_random_seeded "void"
  54 .Ft void
  55 .Fn read_random "void *buffer" "int count"
  56 .Ft int
  57 .Fn read_random_uio "struct uio *uio" "bool nonblock"
  58 .Ss LEGACY ROUTINES
  59 .In sys/libkern.h
  60 .Ft void
  61 .Fn srandom "u_long seed"
  62 .Ft u_long
  63 .Fn random "void"
  64 .Sh DESCRIPTION
  65 The
  66 .Fn arc4random
  67 and
  68 .Fn arc4random_buf
  69 functions will return very good quality random numbers, suited for
  70 security-related purposes.
  71 Both are wrappers around the underlying
  72 .Fn arc4rand
  73 interface.
  74 .Fn arc4random
  75 returns a 32-bit random value, while
  76 .Fn arc4random_buf
  77 fills
  78 .Fa ptr
  79 with
  80 .Fa len
  81 bytes of random data.
  82 .Pp
  83 The
  84 .Fn arc4rand
  85 CSPRNG
  86 is seeded from the
  87 .Xr random 4
  88 kernel abstract entropy device.
  89 Automatic reseeding happens at unspecified time and bytes (of output)
  90 intervals.
  91 A reseed can be forced by passing a non-zero
  92 .Fa reseed
  93 value.
  94 .Pp
  95 The
  96 .Fn read_random
  97 function is used to read entropy directly from the kernel abstract entropy
  98 device.
  99 .Fn read_random
 100 blocks if and until the entropy device is seeded.
 101 The provided
 102 .Fa buffer
 103 is filled with no more than
 104 .Fa count
 105 bytes.
 106 It is strongly advised that
 107 .Fn read_random
 108 is not used directly;
 109 instead, use the
 110 .Fn arc4rand
 111 family of functions.
 112 .Pp
 113 The
 114 .Fn is_random_seeded
 115 function can be used to check in advance if
 116 .Fn read_random
 117 will block.
 118 (If random is seeded, it will not block.)
 119 .Pp
 120 The
 121 .Fn read_random_uio
 122 function behaves identically to
 123 .Xr read 2
 124 on
 125 .Pa /dev/random .
 126 The
 127 .Fa uio
 128 argument points to a buffer where random data should be stored.
 129 If
 130 .Fa nonblock
 131 is true and the random device is not seeded, this function does not return any
 132 data.
 133 Otherwise, this function may block interruptibly until the random device is seeded.
 134 If the function is interrupted before the random device is seeded, no data is
 135 returned.
 136 .Pp
 137 The legacy
 138 .Fn random
 139 function will produce a sequence of numbers that can be duplicated by calling
 140 .Fn srandom
 141 with some constant as the
 142 .Fa seed .
 143 The legacy
 144 .Fn srandom
 145 function may be called with any
 146 .Fa seed
 147 value.
 148 It is strongly advised that the
 149 .Fn random
 150 function not be used to generate random numbers.
 151 See
 152 .Sx SECURITY CONSIDERATIONS .
 153 .Sh RETURN VALUES
 154 The
 155 .Fn arc4rand
 156 function uses the Chacha20 algorithm to generate a pseudo-random sequence of
 157 bytes.
 158 The
 159 .Fn arc4random
 160 function uses
 161 .Fn arc4rand
 162 to generate pseudo-random numbers
 163 in the range from 0 to
 164 .if t 2\u\s732\s10\d\(mi1.
 165 .if n (2**32)\(mi1.
 166 .Pp
 167 The
 168 .Fn read_random
 169 function returns
 170 the number of bytes placed in
 171 .Fa buffer .
 172 .Pp
 173 .Fn read_random_uio
 174 returns zero when successful,
 175 otherwise an error code is returned.
 176 .Pp
 177 The legacy
 178 .Fn random
 179 function uses
 180 a non-linear additive feedback random number generator
 181 employing a default table
 182 of size 31
 183 containing long integers
 184 to return successive pseudo-random
 185 numbers in the range from 0 to
 186 .if t 2\u\s731\s10\d\(mi1.
 187 .if n (2**31)\(mi1.
 188 The period of this random number generator
 189 is very large,
 190 approximately
 191 .if t 16\(mu(2\u\s731\s10\d\(mi1).
 192 .if n 16*((2**31)\(mi1).
 193 .Sh ERRORS
 194 .Fn read_random_uio
 195 may fail if:
 196 .Bl -tag -width Er
 197 .It Bq Er EFAULT
 198 .Fa uio
 199 points to an invalid memory region.
 200 .It Bq Er EWOULDBLOCK
 201 The random device is unseeded and
 202 .Fa nonblock
 203 is true.
 204 .El
 205 .Sh AUTHORS
 206 .An Dan Moschuk
 207 wrote
 208 .Fn arc4random .
 209 .An Mark R V Murray
 210 wrote
 211 .Fn read_random .
 212 .Sh SECURITY CONSIDERATIONS
 213 Do not use
 214 .Fn random
 215 or
 216 .Fn srandom
 217 in new code.
 218 .Pp
 219 It is important to remember that the
 220 .Fn random
 221 function is entirely predictable.
 222 It is easy for attackers to predict future output of
 223 .Fn random
 224 by recording some generated values.
 225 We cannot emphasize strongly enough that
 226 .Fn random
 227 must not be used to generate values that are intended to be unpredictable.