lib/libc/gen/arc4random.3

   1 .\" $OpenBSD: arc4random.3,v 1.35 2014/11/25 16:45:24 millert Exp $
   2 .\"
   3 .\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"      This product includes software developed by Niels Provos.
  17 .\" 4. The name of the author may not be used to endorse or promote products
  18 .\"    derived from this software without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  21 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  22 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  23 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  24 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  25 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  29 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30 .\"
  31 .\" Manual page, using -mandoc macros
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd March 21, 2019
  35 .Dt ARC4RANDOM 3
  36 .Os
  37 .Sh NAME
  38 .Nm arc4random ,
  39 .Nm arc4random_buf ,
  40 .Nm arc4random_uniform
  41 .Nd random number generator
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .In stdlib.h
  46 .Ft uint32_t
  47 .Fn arc4random "void"
  48 .Ft void
  49 .Fn arc4random_buf "void *buf" "size_t nbytes"
  50 .Ft uint32_t
  51 .Fn arc4random_uniform "uint32_t upper_bound"
  52 .Sh DESCRIPTION
  53 This family of functions provides higher quality data than those
  54 described in
  55 .Xr rand 3 ,
  56 .Xr random 3 ,
  57 and
  58 .Xr rand48 3 .
  59 .Pp
  60 Use of these functions is encouraged for almost all random number
  61 consumption because the other interfaces are deficient in either
  62 quality, portability, standardization, or availability.
  63 These functions can be called in almost all coding environments,
  64 including
  65 .Xr pthreads 3
  66 and
  67 .Xr chroot 2 .
  68 .Pp
  69 High quality 32-bit pseudo-random numbers are generated very quickly.
  70 On each call, a cryptographic pseudo-random number generator is used
  71 to generate a new result.
  72 One data pool is used for all consumers in a process, so that consumption
  73 under program flow can act as additional stirring.
  74 The subsystem is re-seeded from the kernel random number subsystem using
  75 .Xr getentropy 2
  76 on a regular basis, and also upon
  77 .Xr fork 2 .
  78 .Pp
  79 The
  80 .Fn arc4random
  81 function returns a single 32-bit value.
  82 The
  83 .Fn arc4random
  84 function returns pseudo-random numbers in the range of 0 to
  85 .if t 2\u\s731\s10\d\(mi1,
  86 .if n (2**32)\(mi1,
  87 and therefore has twice the range of
  88 .Xr rand 3
  89 and
  90 .Xr random 3 .
  91 .Pp
  92 .Fn arc4random_buf
  93 fills the region
  94 .Fa buf
  95 of length
  96 .Fa nbytes
  97 with random data.
  98 .Pp
  99 .Fn arc4random_uniform
 100 will return a single 32-bit value, uniformly distributed but less than
 101 .Fa upper_bound .
 102 This is recommended over constructions like
 103 .Dq Li arc4random() % upper_bound
 104 as it avoids "modulo bias" when the upper bound is not a power of two.
 105 In the worst case, this function may consume multiple iterations
 106 to ensure uniformity; see the source code to understand the problem
 107 and solution.
 108 .Sh RETURN VALUES
 109 These functions are always successful, and no return value is
 110 reserved to indicate an error.
 111 .Sh EXAMPLES
 112 The following produces a drop-in replacement for the traditional
 113 .Fn rand
 114 and
 115 .Fn random
 116 functions using
 117 .Fn arc4random :
 118 .Pp
 119 .Dl "#define foo4random() (arc4random_uniform(RAND_MAX + 1))"
 120 .Sh SEE ALSO
 121 .Xr rand 3 ,
 122 .Xr rand48 3 ,
 123 .Xr random 3
 124 .Sh HISTORY
 125 These functions first appeared in
 126 .Ox 2.1 .
 127 .Pp
 128 The original version of this random number generator used the
 129 RC4 (also known as ARC4) algorithm.
 130 In
 131 .Ox 5.5
 132 it was replaced with the ChaCha20 cipher, and it may be replaced
 133 again in the future as cryptographic techniques advance.
 134 A good mnemonic is
 135 .Dq A Replacement Call for Random .
 136 .Pp
 137 The
 138 .Fn arc4random
 139 random number generator was first introduced in
 140 .Fx 2.2.6 .
 141 The ChaCha20 based implementation was introduced in
 142 .Fx 12.0 ,
 143 with obsolete stir and addrandom interfaces removed at the same time.