arc4random.3 (6a068746777241722b2b32c5d0bc443a2a64d80b) | arc4random.3 (c1e80940f3b4030df0aaed73028053af057e476d) |
---|---|
1.\" $OpenBSD: arc4random.3,v 1.2 1997/04/27 22:40:25 angelos Exp $ | 1.\" $OpenBSD: arc4random.3,v 1.35 2014/11/25 16:45:24 millert Exp $ 2.\" |
2.\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. --- 15 unchanged lines hidden (view full) --- 25.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 28.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29.\" 30.\" Manual page, using -mandoc macros 31.\" $FreeBSD$ 32.\" | 3.\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. --- 15 unchanged lines hidden (view full) --- 26.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 29.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30.\" 31.\" Manual page, using -mandoc macros 32.\" $FreeBSD$ 33.\" |
33.Dd April 15, 1997 | 34.Dd July 19, 2014 |
34.Dt ARC4RANDOM 3 35.Os 36.Sh NAME 37.Nm arc4random , 38.Nm arc4random_buf , | 35.Dt ARC4RANDOM 3 36.Os 37.Sh NAME 38.Nm arc4random , 39.Nm arc4random_buf , |
39.Nm arc4random_uniform , 40.Nm arc4random_stir , 41.Nm arc4random_addrandom 42.Nd arc4 random number generator | 40.Nm arc4random_uniform 41.Nd random number generator |
43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In stdlib.h 47.Ft uint32_t 48.Fn arc4random "void" 49.Ft void 50.Fn arc4random_buf "void *buf" "size_t nbytes" 51.Ft uint32_t 52.Fn arc4random_uniform "uint32_t upper_bound" | 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In stdlib.h 46.Ft uint32_t 47.Fn arc4random "void" 48.Ft void 49.Fn arc4random_buf "void *buf" "size_t nbytes" 50.Ft uint32_t 51.Fn arc4random_uniform "uint32_t upper_bound" |
53.Ft void 54.Fn arc4random_stir "void" 55.Ft void 56.Fn arc4random_addrandom "unsigned char *dat" "int datlen" | |
57.Sh DESCRIPTION | 52.Sh DESCRIPTION |
53This family of functions provides higher quality data than those 54described in 55.Xr rand 3 , 56.Xr random 3 , 57and 58.Xr rand48 3 . 59.Pp 60Use of these functions is encouraged for almost all random number 61consumption because the other interfaces are deficient in either 62quality, portability, standardization, or availability. 63These functions can be called in almost all coding environments, 64including 65.Xr pthreads 3 66and 67.Xr chroot 2 . 68.Pp 69High quality 32-bit pseudo-random numbers are generated very quickly. 70On each call, a cryptographic pseudo-random number generator is used 71to generate a new result. 72One data pool is used for all consumers in a process, so that consumption 73under program flow can act as additional stirring. 74The subsystem is re-seeded from the kernel random number subsystem using 75.Xr getentropy 2 76on a regular basis, and also upon 77.Xr fork 2 . 78.Pp |
|
58The 59.Fn arc4random | 79The 80.Fn arc4random |
60function uses the key stream generator employed by the 61arc4 cipher, which uses 8*8 8 bit S-Boxes. 62The S-Boxes 63can be in about 64.if t 2\u\s71700\s10\d 65.if n (2**1700) 66states. | 81function returns a single 32-bit value. |
67The 68.Fn arc4random 69function returns pseudo-random numbers in the range of 0 to 70.if t 2\u\s731\s10\d\(mi1, 71.if n (2**32)\(mi1, 72and therefore has twice the range of 73.Xr rand 3 74and 75.Xr random 3 . 76.Pp 77.Fn arc4random_buf | 82The 83.Fn arc4random 84function returns pseudo-random numbers in the range of 0 to 85.if t 2\u\s731\s10\d\(mi1, 86.if n (2**32)\(mi1, 87and therefore has twice the range of 88.Xr rand 3 89and 90.Xr random 3 . 91.Pp 92.Fn arc4random_buf |
78function fills the region | 93fills the region |
79.Fa buf 80of length 81.Fa nbytes | 94.Fa buf 95of length 96.Fa nbytes |
82with ARC4-derived random data. | 97with random data. |
83.Pp 84.Fn arc4random_uniform | 98.Pp 99.Fn arc4random_uniform |
85will return a uniformly distributed random number less than | 100will return a single 32-bit value, uniformly distributed but less than |
86.Fa upper_bound . | 101.Fa upper_bound . |
87.Fn arc4random_uniform 88is recommended over constructions like | 102This is recommended over constructions like |
89.Dq Li arc4random() % upper_bound 90as it avoids "modulo bias" when the upper bound is not a power of two. | 103.Dq Li arc4random() % upper_bound 104as it avoids "modulo bias" when the upper bound is not a power of two. |
91.Pp 92The 93.Fn arc4random_stir 94function reads data from 95.Pa /dev/urandom 96and uses it to permute the S-Boxes via 97.Fn arc4random_addrandom . 98.Pp 99There is no need to call 100.Fn arc4random_stir 101before using 102.Fn arc4random 103functions family, since 104they automatically initialize themselves. | 105In the worst case, this function may consume multiple iterations 106to ensure uniformity; see the source code to understand the problem 107and solution. 108.Sh RETURN VALUES 109These functions are always successful, and no return value is 110reserved to indicate an error. |
105.Sh EXAMPLES 106The following produces a drop-in replacement for the traditional 107.Fn rand 108and 109.Fn random 110functions using 111.Fn arc4random : 112.Pp 113.Dl "#define foo4random() (arc4random() % ((unsigned)RAND_MAX + 1))" 114.Sh SEE ALSO 115.Xr rand 3 , | 111.Sh EXAMPLES 112The following produces a drop-in replacement for the traditional 113.Fn rand 114and 115.Fn random 116functions using 117.Fn arc4random : 118.Pp 119.Dl "#define foo4random() (arc4random() % ((unsigned)RAND_MAX + 1))" 120.Sh SEE ALSO 121.Xr rand 3 , |
116.Xr random 3 , 117.Xr srandomdev 3 | 122.Xr rand48 3 , 123.Xr random 3 |
118.Sh HISTORY | 124.Sh HISTORY |
119.Pa RC4 120has been designed by RSA Data Security, Inc. 121It was posted anonymously 122to the USENET and was confirmed to be equivalent by several sources who 123had access to the original cipher. 124Since 125.Pa RC4 126used to be a trade secret, the cipher is now referred to as 127.Pa ARC4 . | 125These functions first appeared in 126.Ox 2.1 . 127.Pp 128The original version of this random number generator used the 129RC4 (also known as ARC4) algorithm. 130In 131.Ox 5.5 132it was replaced with the ChaCha20 cipher, and it may be replaced 133again in the future as cryptographic techniques advance. 134A good mnemonic is 135.Dq A Replacement Call for Random . 136.Pp 137The 138.Fn arc4random 139random number generator was first introduced in 140.Fx 2.2.6 . 141The ChaCha20 based implementation was introduced in 142.Fx 12.0 , 143with obsolete stir and addrandom interfaces removed at the same time. |