1.\" $OpenBSD: arc4random.3,v 1.37 2019/09/29 16:30:35 jmc Exp $ 2.\" 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. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by Niels Provos. 17.\" 4. The name of the author may not be used to endorse or promote products 18.\" derived from this software without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 21.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 22.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 23.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 24.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 25.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 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.\" 33.Dd April 13, 2020 34.Dt ARC4RANDOM 3 35.Os 36.Sh NAME 37.Nm arc4random , 38.Nm arc4random_buf , 39.Nm arc4random_uniform 40.Nd random number generator 41.Sh LIBRARY 42.Lb libc 43.Sh SYNOPSIS 44.In stdlib.h 45.Ft uint32_t 46.Fn arc4random "void" 47.Ft void 48.Fn arc4random_buf "void *buf" "size_t nbytes" 49.Ft uint32_t 50.Fn arc4random_uniform "uint32_t upper_bound" 51.Sh DESCRIPTION 52This family of functions provides higher quality data than those 53described in 54.Xr rand 3 , 55.Xr random 3 , 56and 57.Xr rand48 3 . 58.Pp 59Use of these functions is encouraged for almost all random number 60consumption because the other interfaces are deficient in either 61quality, portability, standardization, or availability. 62These functions can be called in almost all coding environments, 63including 64.Xr pthread 3 65and 66.Xr chroot 2 . 67.Pp 68High quality 32-bit pseudo-random numbers are generated very quickly. 69On each call, a cryptographic pseudo-random number generator is used 70to generate a new result. 71One data pool is used for all consumers in a process, so that consumption 72under program flow can act as additional stirring. 73The subsystem is re-seeded from the kernel 74.Xr random 4 75subsystem using 76.Xr getentropy 3 77on a regular basis, and also upon 78.Xr fork 2 . 79.Pp 80The 81.Fn arc4random 82function returns a single 32-bit value. 83The 84.Fn arc4random 85function returns pseudo-random numbers in the range of 0 to 86.if t 2\u\s731\s10\d\(mi1, 87.if n (2**32)\(mi1, 88and therefore has twice the range of 89.Xr rand 3 90and 91.Xr random 3 . 92.Pp 93.Fn arc4random_buf 94fills the region 95.Fa buf 96of length 97.Fa nbytes 98with random data. 99.Pp 100.Fn arc4random_uniform 101will return a single 32-bit value, uniformly distributed but less than 102.Fa upper_bound . 103This is recommended over constructions like 104.Dq Li arc4random() % upper_bound 105as it avoids "modulo bias" when the upper bound is not a power of two. 106In the worst case, this function may consume multiple iterations 107to ensure uniformity; see the source code to understand the problem 108and solution. 109.Sh RETURN VALUES 110These functions are always successful, and no return value is 111reserved to indicate an error. 112.Sh EXAMPLES 113The following produces a drop-in replacement for the traditional 114.Fn rand 115and 116.Fn random 117functions using 118.Fn arc4random : 119.Pp 120.Dl "#define foo4random() (arc4random_uniform(RAND_MAX + 1))" 121.Sh SEE ALSO 122.Xr rand 3 , 123.Xr rand48 3 , 124.Xr random 3 125.Rs 126.%A Daniel J. Bernstein 127.%T ChaCha, a variant of Salsa20 128.%D 2008-01-28 129.%O Document ID: 4027b5256e17b9796842e6d0f68b0b5e 130.%U http://cr.yp.to/papers.html#chacha 131.Re 132.Sh HISTORY 133These functions first appeared in 134.Ox 2.1 . 135.Fn arc4random 136first appeared in 137.Fx 3.0 . 138.Fn arc4random_buf 139and 140.Fn arc4random_uniform 141first appeared in 142.Fx 8.0 . 143.Fn arc4random_stir 144was removed in 145.Fx 12.0 . 146.Pp 147The original version of this random number generator used the 148RC4 (also known as ARC4) algorithm. 149In 150.Ox 5.5 151it was replaced with the ChaCha20 cipher, and it may be replaced 152again in the future as cryptographic techniques advance. 153A good mnemonic is 154.Dq A Replacement Call for Random . 155.Pp 156The 157.Fn arc4random 158random number generator was first introduced in 159.Fx 2.2.6 . 160The ChaCha20 based implementation was introduced in 161.Fx 12.0 , 162with obsolete stir and addrandom interfaces removed at the same time. 163