share/man/man9/random.9

   1 .\"
   2 .\" Copyright (c) 2000
   3 .\"     The Regents of the University of California.  All rights reserved.
   4 .\"
   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 .\"
  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 .\" $FreeBSD$
  28 .\" "
  29 .Dd September 25, 2000
  30 .Dt RANDOM 9
  31 .Os
  32 .Sh NAME
  33 .Nm arc4rand ,
  34 .Nm arc4random ,
  35 .Nm random ,
  36 .Nm read_random ,
  37 .Nm srandom
  38 .Nd supply pseudo-random numbers
  39 .Sh SYNOPSIS
  40 .In sys/libkern.h
  41 .Ft void
  42 .Fn srandom "u_long seed"
  43 .Ft u_long
  44 .Fn random "void"
  45 .Ft void
  46 .Fn arc4rand "void *ptr" "u_int length" "int reseed"
  47 .Ft u_int32_t
  48 .Fn arc4random "void"
  49 .Pp
  50 .In sys/random.h
  51 .Ft int
  52 .Fn read_random "void *buffer" "int count"
  53 .Sh DESCRIPTION
  54 The
  55 .Fn random
  56 function will by default produce a sequence of numbers that can be duplicated
  57 by calling
  58 .Fn srandom
  59 with
  60 .Ql 1
  61 as the
  62 .Fa seed .
  63 The
  64 .Fn srandom
  65 function may be called with any arbitrary
  66 .Fa seed
  67 value to get slightly more unpredictable numbers.
  68 It is important to remember that the
  69 .Fn random
  70 function is entirely predictable, and is therefore not of use where
  71 knowledge of the sequence of numbers may be of benefit to an attacker.
  72 .Pp
  73 The
  74 .Fn arc4rand
  75 function will return very good quality random numbers, slightly better
  76 suited for security-related purposes.
  77 The random numbers from
  78 .Fn arc4rand
  79 are seeded from the entropy device if it is available.
  80 Automatic reseeds happen after a certain timeinterval and after a
  81 certain number of bytes have been delivered.
  82 A forced reseed can be forced by passing a non-zero value in the
  83 .Fa reseed
  84 argument.
  85 .Pp
  86 The
  87 .Fn read_random
  88 function is used to return entropy directly from the entropy device
  89 if it has been loaded.
  90 If the entropy device is not loaded, then
  91 the
  92 .Fa buffer
  93 is filled with output generated by
  94 .Fn random .
  95 The
  96 .Fa buffer
  97 is filled with no more than
  98 .Fa count
  99 bytes.
 100 It is advised that
 101 .Fn read_random
 102 is not used; instead use
 103 .Fn arc4rand
 104 .Pp
 105 All the bits generated by
 106 .Fn random ,
 107 .Fn arc4rand
 108 and
 109 .Fn read_random
 110 are usable.
 111 For example,
 112 .Sq Li random()&01
 113 will produce a random binary value.
 114 .Pp
 115 The
 116 .Fn arc4random
 117 is a convenience function which calls
 118 .Fn arc4rand
 119 to return a 32 bit pseudo-random integer.
 120 .Sh RETURN VALUES
 121 The
 122 .Fn random
 123 function
 124 uses a non-linear additive feedback random number generator employing a
 125 default table of size 31 long integers to return successive pseudo-random
 126 numbers in the range from 0 to
 127 .if t 2\u\s731\s10\d\(mi1.
 128 .if n (2**31)\(mi1.
 129 The period of this random number generator is very large, approximately
 130 .if t 16\(mu(2\u\s731\s10\d\(mi1).
 131 .if n 16*((2**31)\(mi1).
 132 .Pp
 133 The
 134 .Fn arc4rand
 135 function uses the RC4 algorithm to generate successive pseudo-random
 136 bytes.
 137 The
 138 .Fn arc4random
 139 function
 140 uses
 141 .Fn arc4rand
 142 to generate pseudo-random numbers in the range from 0 to
 143 .if t 2\u\s732\s10\d\(mi1.
 144 .if n (2**32)\(mi1.
 145 .Pp
 146 The
 147 .Fn read_random
 148 function returns the number of bytes placed in
 149 .Fa buffer .
 150 .Sh AUTHORS
 151 .An Dan Moschuk
 152 wrote
 153 .Fn arc4random .
 154 .An Mark R V Murray
 155 wrote
 156 .Fn read_random .