lib/libc/gen/arc4random.3

   1 .\"     $NetBSD: arc4random.3,v 1.9 2011/02/05 00:24:08 wiz Exp $
   2 .\" $OpenBSD: arc4random.3,v 1.17 2000/12/21 14:07:41 aaron Exp $
   3 .\"
   4 .\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
   5 .\" 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 .\" 3. All advertising materials mentioning features or use of this software
  16 .\"    must display the following acknowledgement:
  17 .\"      This product includes software developed by Niels Provos.
  18 .\" 4. The name of the author may not be used to endorse or promote products
  19 .\"    derived from this software without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  22 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  23 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  24 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  25 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  26 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  30 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31 .\"
  32 .\" Manual page, using -mandoc macros
  33 .\"
  34 .Dd February 4, 2011
  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 uint32_t
  49 .Fn arc4random "void"
  50 .Ft void
  51 .Fn arc4random_buf "void *buffer" "size_t length"
  52 .Ft uint32_t
  53 .Fn arc4random_uniform "uint32_t upper_bound"
  54 .Ft void
  55 .Fn arc4random_stir "void"
  56 .Ft void
  57 .Fn arc4random_addrandom "u_char *dat" "int datlen"
  58 .Sh DESCRIPTION
  59 The
  60 .Fn arc4random
  61 function provides a high quality 32-bit pseudo-random
  62 number very quickly.
  63 .Fn arc4random
  64 seeds itself on a regular basis from the kernel strong random number
  65 subsystem described in
  66 .Xr rnd 4 .
  67 On each call, an ARC4 generator is used to generate a new result.
  68 The
  69 .Fn arc4random
  70 function uses the ARC4 cipher key stream generator,
  71 which uses 8*8 8 bit S-Boxes.
  72 The S-Boxes can be in about (2**1700) states.
  73 .Pp
  74 .Fn arc4random
  75 fits into a middle ground not covered by other subsystems such as
  76 the strong, slow, and resource expensive random
  77 devices described in
  78 .Xr rnd 4
  79 versus the fast but poor quality interfaces described in
  80 .Xr rand 3 ,
  81 .Xr random 3 ,
  82 and
  83 .Xr drand48 3 .
  84 .Pp
  85 The
  86 .Fn arc4random_buf
  87 function fills the
  88 .Fa buffer
  89 with
  90 .Fa length
  91 bytes of ARC4-derived random data.
  92 .Pp
  93 The
  94 .Fn arc4random_uniform
  95 function returns a uniformly distributed random number less than
  96 .Fa upper_bound
  97 avoiding modulo bias when the upper bound is not a power of two.
  98 .Pp
  99 The
 100 .Fn arc4random_stir
 101 function reads data from
 102 .Pa /dev/urandom
 103 and uses it to permute the S-Boxes via
 104 .Fn arc4random_addrandom .
 105 .Pp
 106 There is no need to call
 107 .Fn arc4random_stir
 108 before using
 109 .Fn arc4random ,
 110 since
 111 .Fn arc4random
 112 automatically initializes itself.
 113 .Sh SEE ALSO
 114 .Xr rand 3 ,
 115 .Xr rand48 3 ,
 116 .Xr random 3
 117 .Sh HISTORY
 118 An algorithm called
 119 .Pa RC4
 120 was designed by RSA Data Security, Inc.
 121 It was considered a trade secret, but not trademarked.
 122 Because it was a trade secret, it obviously could not be patented.
 123 A clone of this was posted anonymously to USENET and confirmed to
 124 be equivalent by several sources who had access to the original cipher.
 125 Because of the trade secret situation, RSA Data Security, Inc. can do
 126 nothing about the release of the ARC4 algorithm.
 127 Since
 128 .Pa RC4
 129 used to be a trade secret, the cipher is now referred to as
 130 .Pa ARC4 .
 131 .Pp
 132 These functions first appeared in
 133 .Ox 2.1 .