gen/FreeBSD/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 .\"
  33 .Dd April 15, 1997
  34 .Dt ARC4RANDOM 3
  35 .Os
  36 .Sh NAME
  37 .Nm arc4random ,
  38 .Nm arc4random_buf ,
  39 .Nm arc4random_uniform ,
  40 .Nm arc4random_stir ,
  41 .Nm arc4random_addrandom
  42 .Nd arc4 random number generator
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In stdlib.h
  47 .Ft u_int32_t
  48 .Fn arc4random "void"
  49 .Ft void
  50 .Fn arc4random_buf "void *buf" "size_t nbytes"
  51 .Ft u_int32_t
  52 .Fn arc4random_uniform "u_int32_t upper_bound"
  53 .Ft void
  54 .Fn arc4random_stir "void"
  55 .Ft void
  56 .Fn arc4random_addrandom "unsigned char *dat" "int datlen"
  57 .Sh DESCRIPTION
  58 The
  59 .Fn arc4random
  60 function uses the key stream generator employed by the
  61 arc4 cipher, which uses 8*8 8 bit S-Boxes.
  62 The S-Boxes
  63 can be in about
  64 .if t 2\u\s71700\s10\d
  65 .if n (2**1700)
  66 states.
  67 The
  68 .Fn arc4random
  69 function returns pseudo-random numbers in the range of 0 to
  70 .if t 2\u\s731\s10\d\(mi1,
  71 .if n (2**32)\(mi1,
  72 and therefore has twice the range of
  73 .Xr rand 3
  74 and
  75 .Xr random 3 .
  76 .Pp
  77 .Fn arc4random_buf
  78 function fills the region
  79 .Fa buf
  80 of length
  81 .Fa nbytes
  82 with ARC4-derived random data.
  83 .Pp
  84 .Fn arc4random_uniform
  85 will return a uniformly distributed random number less than
  86 .Fa upper_bound .
  87 .Fn arc4random_uniform
  88 is recommended over constructions like
  89 .Dq Li arc4random() % upper_bound
  90 as it avoids "modulo bias" when the upper bound is not a power of two.
  91 .Pp
  92 The
  93 .Fn arc4random_stir
  94 function reads data from
  95 .Pa /dev/urandom
  96 and uses it to permute the S-Boxes via
  97 .Fn arc4random_addrandom .
  98 .Pp
  99 There is no need to call
 100 .Fn arc4random_stir
 101 before using
 102 .Fn arc4random
 103 functions family, since
 104 they automatically initialize themselves.
 105 .Sh EXAMPLES
 106 The following produces a drop-in replacement for the traditional
 107 .Fn rand
 108 and
 109 .Fn random
 110 functions using
 111 .Fn arc4random :
 112 .Pp
 113 .Dl "#define foo4random() (arc4random() % ((unsigned)RAND_MAX + 1))"
 114 .Sh SEE ALSO
 115 .Xr rand 3 ,
 116 .Xr random 3 ,
 117 .Xr srandomdev 3
 118 .Sh HISTORY
 119 .Pa RC4
 120 has been designed by RSA Data Security, Inc.
 121 It was posted anonymously
 122 to the USENET and was confirmed to be equivalent by several sources who
 123 had access to the original cipher.
 124 Since
 125 .Pa RC4
 126 used to be a trade secret, the cipher is now referred to as
 127 .Pa ARC4 .