Copyright (c) 2014 The NetBSD Foundation, Inc.
All rights reserved.
This code is derived from software contributed to The NetBSD Foundation
by Taylor R. Campbell.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.Dd November 16, 2014 .Dt ARC4RANDOM 3 .Os .Sh NAME .Nm arc4random , .Nm arc4random_uniform , .Nm arc4random_buf , .Nm arc4random_stir , .Nm arc4random_addrandom .Nd random number generator .Sh LIBRARY .Lb libc .Sh SYNOPSIS n stdlib.h .Ft uint32_t .Fn arc4random "void" .Ft uint32_t .Fn arc4random_uniform "uint32_t bound" .Ft void .Fn arc4random_buf "void *buf" "size_t len" .Ft void .Fn arc4random_stir "void" .Ft void .Fn arc4random_addrandom "unsigned char *buf" "int len" .Sh DESCRIPTION The .Nm family of functions provides a cryptographic pseudorandom number generator automatically seeded from the system entropy pool and safe to use from multiple threads. .Nm is faster and more convenient than reading from
p .Fn arc4random returns an integer in [0, 2^32) chosen independently with uniform distribution.
p .Fn arc4random_uniform returns an integer in [0, .Fa bound ) chosen independently with uniform distribution.
p .Fn arc4random_buf stores .Fa len bytes into the memory pointed to by .Fa buf , each byte chosen independently from [0, 256) with uniform distribution.
p .Fn arc4random_stir draws entropy from the operating system and incorporates it into the library's PRNG state to influence future outputs.
p .Fn arc4random_addrandom incorporates .Fa len bytes, which must be nonnegative, from the buffer .Fa buf , into the library's PRNG state to influence future outputs.
p It is not necessary for an application to call .Fn arc4random_stir or .Fn arc4random_addrandom before calling other .Nm functions. The first call to any .Nm function will initialize the PRNG state unpredictably from the system entropy pool. .Sh SECURITY MODEL The .Nm functions provides the following security properties against three different classes of attackers, assuming that the state of the operating system's entropy pool is unknown to the attacker: l -bullet -offset abcd -compact t An attacker who has seen some outputs of any of the .Nm functions cannot predict past or future unseen outputs. t An attacker who has seen the library's PRNG state in memory cannot predict past outputs. t An attacker who has seen one process's PRNG state cannot predict past or future outputs in other processes, particularly its parent or siblings. .El .Sh IMPLEMENTATION NOTES The .Nm functions are currently implemented using the ChaCha20 pseudorandom function family. For any 32-byte string .Fa s ,
f ChaCha20_ Fa s is a function from 16-byte strings to 64-byte strings. It is conjectured that if .Fa s is chosen with uniform distribution, then the distribution on
f ChaCha20_ Fa s is indistinguishable to a computationally bounded adversary from a uniform distribution on all functions from 16-byte strings to 64-byte strings.
p The PRNG state is a 32-byte ChaCha20 key .Fa s . Each request to an .Nm function l -bullet -offset abcd -compact t computes the 64-byte quantity .Fa x =
f ChaCha20_ Fa s Ns (0), t splits .Fa x into two 32-byte quantities .Fa s' and .Fa k , t replaces .Fa s by .Fa s' , and t uses .Fa k as output. .El
p .Fn arc4random yields the first four bytes of .Fa k as output directly. .Fn arc4random_buf either yields up to 32 bytes of .Fa k as output directly, or, for longer requests, uses .Fa k as a ChaCha20 key and yields the concatenation
f ChaCha20_ Fa k Ns (0) ||
f ChaCha20_ Fa k Ns (1) || ... as output. .Fn arc4random_uniform repeats .Fn arc4random until it obtains an integer in [2^32 % .Fa bound , 2^32), and reduces that modulo .Fa bound .
p The PRNG state is per-thread, unless memory allocation fails inside the library, in which case some threads may share global PRNG state with a mutex. The global PRNG state is zeroed on fork in the parent via .Xr pthread_atfork 3 , and the per-thread PRNG state is zeroed on fork in the child via .Xr minherit 2 with .Dv MAP_INHERIT_ZERO , so that the child cannot reuse or see the parent's PRNG state. The PRNG state is reseeded automatically from the system entropy pool on the first use of an .Nm function after zeroing.
p The first use of an .Nm function may abort the process in the highly unlikely event that library initialization necessary to implement the security model fails. Additionally, .Fn arc4random_stir and .Fn arc4random_addrandom may abort the process in the highly unlikely event that the operating system fails to provide entropy. .Sh SEE ALSO .Xr rand 3 , .Xr random 3 , .Xr cprng 9 .Rs .%A Daniel J. Bernstein .%T ChaCha, a variant of Salsa20 .%D 2008-01-28 .%O Document ID: 4027b5256e17b9796842e6d0f68b0b5e .%U http://cr.yp.to/papers.html#chacha .Re .Sh BUGS There is no way to get deterministic, reproducible results out of .Nm for testing purposes.
p The name .Sq arc4random was chosen for hysterical raisins, because it was originally implemented using the RC4 stream cipher, which is now known to be badly enough biased to admit practical attacks in the real world. Unfortunately, the library found widespread adoption and the name stuck before anyone recognized that it was silly.
p The signature of .Fn arc4random_addrandom is silly. There is no reason to require casts or accept negative lengths: it should take a .Vt void * buffer and a .Vt size_t length. But it's too late to change that now.
p .Fn arc4random_uniform does not help to choose integers in [0, n) uniformly at random when n > 2^32.