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