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