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. For example, 109.Sq Li random()&01 110will produce a random binary value. 111.Pp 112The 113.Fn arc4random 114is a convenience function which calls 115.Fn arc4rand 116to return a 32 bit pseudo-random integer. 117.Sh RETURN VALUES 118The 119.Fn random 120function 121uses a non-linear additive feedback random number generator employing a 122default table of size 31 long integers to return successive pseudo-random 123numbers in the range from 0 to 124.if t 2\u\s731\s10\d\(mi1. 125.if n (2**31)\(mi1. 126The period of this random number generator is very large, approximately 127.if t 16\(mu(2\u\s731\s10\d\(mi1). 128.if n 16*((2**31)\(mi1). 129.Pp 130The 131.Fn arc4rand 132function uses the RC4 algorithm to generate successive pseudo-random 133bytes. 134The 135.Fn arc4random 136function 137uses 138.Fn arc4rand 139to generate pseudo-random numbers in the range from 0 to 140.if t 2\u\s732\s10\d\(mi1. 141.if n (2**32)\(mi1. 142.Pp 143The 144.Fn read_random 145function returns the number of bytes placed in 146.Fa buffer . 147.Sh AUTHORS 148.An Dan Moschuk 149wrote 150.Fn arc4random . 151.An Mark R V Murray 152wrote 153.Fn read_random . 154