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.\" $FreeBSD$ 33.\" 34.Dd April 13, 2020 35.Dt ARC4RANDOM 3 36.Os 37.Sh NAME 38.Nm arc4random , 39.Nm arc4random_buf , 40.Nm arc4random_uniform 41.Nd random number generator 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" 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 pthread 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 75.Xr random 4 76subsystem using 77.Xr getentropy 3 78on a regular basis, and also upon 79.Xr fork 2 . 80.Pp 81The 82.Fn arc4random 83function returns a single 32-bit value. 84The 85.Fn arc4random 86function returns pseudo-random numbers in the range of 0 to 87.if t 2\u\s731\s10\d\(mi1, 88.if n (2**32)\(mi1, 89and therefore has twice the range of 90.Xr rand 3 91and 92.Xr random 3 . 93.Pp 94.Fn arc4random_buf 95fills the region 96.Fa buf 97of length 98.Fa nbytes 99with random data. 100.Pp 101.Fn arc4random_uniform 102will return a single 32-bit value, uniformly distributed but less than 103.Fa upper_bound . 104This is recommended over constructions like 105.Dq Li arc4random() % upper_bound 106as it avoids "modulo bias" when the upper bound is not a power of two. 107In the worst case, this function may consume multiple iterations 108to ensure uniformity; see the source code to understand the problem 109and solution. 110.Sh RETURN VALUES 111These functions are always successful, and no return value is 112reserved to indicate an error. 113.Sh EXAMPLES 114The following produces a drop-in replacement for the traditional 115.Fn rand 116and 117.Fn random 118functions using 119.Fn arc4random : 120.Pp 121.Dl "#define foo4random() (arc4random_uniform(RAND_MAX + 1))" 122.Sh SEE ALSO 123.Xr rand 3 , 124.Xr rand48 3 , 125.Xr random 3 126.Rs 127.%A Daniel J. Bernstein 128.%T ChaCha, a variant of Salsa20 129.%D 2008-01-28 130.%O Document ID: 4027b5256e17b9796842e6d0f68b0b5e 131.%U http://cr.yp.to/papers.html#chacha 132.Re 133.Sh HISTORY 134These functions first appeared in 135.Ox 2.1 . 136.Pp 137The original version of this random number generator used the 138RC4 (also known as ARC4) algorithm. 139In 140.Ox 5.5 141it was replaced with the ChaCha20 cipher, and it may be replaced 142again in the future as cryptographic techniques advance. 143A good mnemonic is 144.Dq A Replacement Call for Random . 145.Pp 146The 147.Fn arc4random 148random number generator was first introduced in 149.Fx 2.2.6 . 150The ChaCha20 based implementation was introduced in 151.Fx 12.0 , 152with obsolete stir and addrandom interfaces removed at the same time. 153