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 July 16, 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 read_random_uio , 38.Nm srandom 39.Nd supply pseudo-random numbers 40.Sh SYNOPSIS 41.In sys/libkern.h 42.Ft void 43.Fn srandom "u_long seed" 44.Ft u_long 45.Fn random "void" 46.Ft void 47.Fn arc4rand "void *ptr" "u_int length" "int reseed" 48.Ft uint32_t 49.Fn arc4random "void" 50.Pp 51.In sys/random.h 52.Ft int 53.Fn read_random "void *buffer" "int count" 54.Ft int 55.Fn read_random_uio "struct uio *uio" "bool nonblock" 56.Sh DESCRIPTION 57The 58.Fn random 59function will by default produce 60a sequence of numbers 61that can be duplicated 62by calling 63.Fn srandom 64with some constant 65as the 66.Fa seed . 67The 68.Fn srandom 69function may be called with any arbitrary 70.Fa seed 71value to get slightly more unpredictable numbers. 72It is important to remember that the 73.Fn random 74function is entirely predictable, 75and is therefore not of use where 76knowledge of the sequence of numbers 77may be of benefit to an attacker. 78.Pp 79The 80.Fn arc4rand 81function will return very good quality random numbers, 82better suited 83for security-related purposes. 84The random numbers from 85.Fn arc4rand 86are seeded from the entropy device 87if it is available. 88Automatic reseeds happen 89after a certain timeinterval 90and after a certain number of bytes 91have been delivered. 92A forced reseed 93can be forced 94by passing a non-zero 95value in the 96.Fa reseed 97argument. 98.Pp 99The 100.Fn read_random 101function is used to return entropy directly from the entropy device 102if it has been loaded. 103If the entropy device is not loaded, then 104the 105.Fa buffer 106is ignored 107and zero is returned. 108The 109.Fa buffer 110is filled with no more than 111.Fa count 112bytes. 113It is strongly advised that 114.Fn read_random 115is not used; 116instead use 117.Fn arc4rand 118unless it is 119necessary to know 120that no entropy 121has been returned. 122.Pp 123The 124.Fn read_random_uio 125function behaves identically to 126.Xr read 2 127on 128.Pa /dev/random . 129The 130.Fa uio 131argument points to a buffer where random data should be stored. 132This function only returns data if the random device is seeded. 133It blocks if unseeded, 134except when the 135.Fa nonblock 136argument is true. 137.Pp 138All the bits returned by 139.Fn random , 140.Fn arc4rand , 141.Fn read_random , 142and 143.Fn read_random_uio 144are usable. 145For example, 146.Sq Li random()&01 147will produce a random binary value. 148.Pp 149The 150.Fn arc4random 151is a convenience function which calls 152.Fn arc4rand 153to return a 32 bit pseudo-random integer. 154.Sh RETURN VALUES 155The 156.Fn random 157function uses 158a non-linear additive feedback random number generator 159employing a default table 160of size 31 161containing long integers 162to return successive pseudo-random 163numbers in the range from 0 to 164.if t 2\u\s731\s10\d\(mi1. 165.if n (2**31)\(mi1. 166The period of this random number generator 167is very large, 168approximately 169.if t 16\(mu(2\u\s731\s10\d\(mi1). 170.if n 16*((2**31)\(mi1). 171.Pp 172The 173.Fn arc4rand 174function uses the RC4 algorithm 175to generate successive pseudo-random bytes. 176The 177.Fn arc4random 178function uses 179.Fn arc4rand 180to generate pseudo-random numbers 181in the range from 0 to 182.if t 2\u\s732\s10\d\(mi1. 183.if n (2**32)\(mi1. 184.Pp 185The 186.Fn read_random 187function returns 188the number of bytes placed in 189.Fa buffer . 190.Pp 191.Fn read_random_uio 192returns zero when successful, 193otherwise an error code is returned. 194.Sh ERRORS 195.Fn read_random_uio 196may fail if: 197.Bl -tag -width Er 198.It Bq Er EFAULT 199.Fa uio 200points to an invalid memory region. 201.It Bq Er EWOULDBLOCK 202The random device is unseeded and 203.Fa nonblock 204is true. 205.El 206.Sh AUTHORS 207.An Dan Moschuk 208wrote 209.Fn arc4random . 210.An Mark R V Murray 211wrote 212.Fn read_random . 213