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 54The 55.Fn random 56function will by default produce a sequence of numbers that can be duplicated 57by calling 58.Fn srandom 59with 60.Ql 1 61as the 62.Fa seed . 63The 64.Fn srandom 65function may be called with any arbitrary 66.Fa seed 67value to get slightly more unpredictable numbers. 68It is important to remember that the 69.Fn random 70function is entirely predictable, and is therefore not of use where 71knowledge of the sequence of numbers may be of benefit to an attacker. 72.Pp 73The 74.Fn arc4rand 75function will return very good quality random numbers, slightly better 76suited for security-related purposes. 77The random numbers from 78.Fn arc4rand 79are seeded from the entropy device if it is available. 80Automatic reseeds happen after a certain timeinterval and after a 81certain number of bytes have been delivered. 82A forced reseed can be forced by passing a non-zero value in the 83.Fa reseed 84argument. 85.Pp 86The 87.Fn read_random 88function is used to return entropy directly from the entropy device 89if it has been loaded. 90If the entropy device is not loaded, then 91the 92.Fa buffer 93is filled with output generated by 94.Fn random . 95The 96.Fa buffer 97is filled with no more than 98.Fa count 99bytes. 100It is advised that 101.Fn read_random 102is not used; instead use 103.Fn arc4rand 104.Pp 105All the bits generated by 106.Fn random , 107.Fn arc4rand 108and 109.Fn read_random 110are usable. 111For example, 112.Sq Li random()&01 113will produce a random binary value. 114.Pp 115The 116.Fn arc4random 117is a convenience function which calls 118.Fn arc4rand 119to return a 32 bit pseudo-random integer. 120.Sh RETURN VALUES 121The 122.Fn random 123function 124uses a non-linear additive feedback random number generator employing a 125default table of size 31 long integers to return successive pseudo-random 126numbers in the range from 0 to 127.if t 2\u\s731\s10\d\(mi1. 128.if n (2**31)\(mi1. 129The 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 133The 134.Fn arc4rand 135function uses the RC4 algorithm to generate successive pseudo-random 136bytes. 137The 138.Fn arc4random 139function 140uses 141.Fn arc4rand 142to 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 146The 147.Fn read_random 148function returns the number of bytes placed in 149.Fa buffer . 150.Sh AUTHORS 151.An Dan Moschuk 152wrote 153.Fn arc4random . 154.An Mark R V Murray 155wrote 156.Fn read_random . 157