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