lib/libc/gen/arc4random.3

   1 .\" $OpenBSD: arc4random.3,v 1.2 1997/04/27 22:40:25 angelos Exp $
   2 .\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. All advertising materials mentioning features or use of this software
  14 .\"    must display the following acknowledgement:
  15 .\"      This product includes software developed by Niels Provos.
  16 .\" 4. The name of the author may not be used to endorse or promote products
  17 .\"    derived from this software without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  20 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  21 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  22 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  23 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  24 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  28 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .\" Manual page, using -mandoc macros
  31 .\" $FreeBSD: src/lib/libc/gen/arc4random.3,v 1.18 2008/07/22 11:33:49 ache Exp $
  32 .\" $DragonFly: src/lib/libc/gen/arc4random.3,v 1.6 2007/06/15 10:10:13 swildner Exp $
  33 .\"
  34 .Dd April 15, 1997
  35 .Dt ARC4RANDOM 3
  36 .Os
  37 .Sh NAME
  38 .Nm arc4random ,
  39 .Nm arc4random_buf ,
  40 .Nm arc4random_uniform ,
  41 .Nm arc4random_stir ,
  42 .Nm arc4random_addrandom
  43 .Nd arc4 random number generator
  44 .Sh LIBRARY
  45 .Lb libc
  46 .Sh SYNOPSIS
  47 .In stdlib.h
  48 .Ft u_int32_t
  49 .Fn arc4random "void"
  50 .Ft void
  51 .Fn arc4random_buf "void *buf" "size_t nbytes"
  52 .Ft u_int32_t
  53 .Fn arc4random_uniform "u_int32_t upper_bound"
  54 .Ft void
  55 .Fn arc4random_stir "void"
  56 .Ft void
  57 .Fn arc4random_addrandom "uint8_t *dat" "size_t datlen"
  58 .Sh DESCRIPTION
  59 The
  60 .Fn arc4random
  61 function uses the key stream generator employed by the
  62 arc4 cipher, which uses 8*8 8 bit S-Boxes.
  63 The S-Boxes
  64 can be in about
  65 .if t 2\u\s71700\s10\d
  66 .if n (2**1700)
  67 states.
  68 The
  69 .Fn arc4random
  70 function returns pseudo-random numbers in the range of 0 to
  71 .if t 2\u\s731\s10\d\(mi1,
  72 .if n (2**32)\(mi1,
  73 and therefore has twice the range of
  74 .Xr rand 3
  75 and
  76 .Xr random 3 .
  77 .Pp
  78 .Fn arc4random_buf
  79 function fills the region
  80 .Fa buf
  81 of length
  82 .Fa nbytes
  83 with ARC4-derived random data.
  84 .Pp
  85 .Fn arc4random_uniform
  86 will return a uniformly distributed random number less than
  87 .Fa upper_bound .
  88 .Fn arc4random_uniform
  89 is recommended over constructions like
  90 .Dq Li arc4random() % upper_bound
  91 as it avoids "modulo bias" when the upper bound is not a power of two.
  92 .Pp
  93 The
  94 .Fn arc4random_stir
  95 function reads data from
  96 .Pa /dev/urandom
  97 and uses it to permute the S-Boxes via
  98 .Fn arc4random_addrandom .
  99 .Pp
 100 There is no need to call
 101 .Fn arc4random_stir
 102 before using
 103 .Fn arc4random
 104 functions family, since
 105 they automatically initialize themselves.
 106 .Sh EXAMPLES
 107 The following produces a drop-in replacement for the traditional
 108 .Fn rand
 109 and
 110 .Fn random
 111 functions using
 112 .Fn arc4random :
 113 .Pp
 114 .Dl "#define foo4random() (arc4random() % ((unsigned)RAND_MAX + 1))"
 115 .Sh SEE ALSO
 116 .Xr rand 3 ,
 117 .Xr random 3 ,
 118 .Xr srandomdev 3 ,
 119 .Xr urandom 4
 120 .Sh HISTORY
 121 .Tn RC4
 122 has been designed by RSA Data Security, Inc.
 123 It was posted anonymously
 124 to the USENET and was confirmed to be equivalent by several sources who
 125 had access to the original cipher.
 126 Since
 127 .Tn RC4
 128 used to be a trade secret, the cipher is now referred to as
 129 .Tn ARC4 .