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.Os 31.Dt RANDOM 9 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. If the entropy device is not loaded, then 90the 91.Fa buffer 92is filled with output generated by 93.Fn random . 94The 95.Fa buffer 96is filled with no more than 97.Fa count 98bytes. It is advised that 99.Fn read_random 100is not used; instead use 101.Fn arc4rand 102.Pp 103All the bits generated by 104.Fn random , 105.Fn arc4rand 106and 107.Fn read_random 108are usable. 109For example, 110.Sq Li random()&01 111will produce a random binary value. 112.Pp 113The 114.Fn arc4random 115is a convenience function which calls 116.Fn arc4rand 117to return a 32 bit pseudo-random integer. 118.Sh RETURN VALUES 119The 120.Fn random 121function 122uses a non-linear additive feedback random number generator employing a 123default table of size 31 long integers to return successive pseudo-random 124numbers in the range from 0 to 125.if t 2\u\s731\s10\d\(mi1. 126.if n (2**31)\(mi1. 127The period of this random number generator is very large, approximately 128.if t 16\(mu(2\u\s731\s10\d\(mi1). 129.if n 16*((2**31)\(mi1). 130.Pp 131The 132.Fn arc4rand 133function uses the RC4 algorithm to generate successive pseudo-random 134bytes. 135The 136.Fn arc4random 137function 138uses 139.Fn arc4rand 140to generate pseudo-random numbers in the range from 0 to 141.if t 2\u\s732\s10\d\(mi1. 142.if n (2**32)\(mi1. 143.Pp 144The 145.Fn read_random 146function returns the number of bytes placed in 147.Fa buffer . 148.Sh AUTHORS 149.An Dan Moschuk 150wrote 151.Fn arc4random . 152.An Mark R V Murray 153wrote 154.Fn read_random . 155