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