arc4random3bsd

Usage

Library

library “libbsd”

Overview

The arc4random family of functions provides a cryptographic pseudorandom number generator automatically seeded from the system entropy pool and safe to use from multiple threads. arc4random is designed to prevent an adversary from guessing outputs, unlike rand(3) and random(3), and is faster and more convenient than reading from /dev/urandom directly.

arc4random() returns an integer in [0, 2^32) chosen independently with uniform distribution.

arc4random_uniform() returns an integer in [0, bound) chosen independently with uniform distribution.

arc4random_buf() stores len bytes into the memory pointed to by buf, each byte chosen independently from [0, 256) with uniform distribution.

arc4random_stir() draws entropy from the operating system and incorporates it into the library's PRNG state to influence future outputs.

arc4random_addrandom() incorporates len bytes, which must be nonnegative, from the buffer buf, into the library's PRNG state to influence future outputs.

It is not necessary for an application to call arc4random_stir() or arc4random_addrandom() before calling other arc4random functions. The first call to any arc4random function will initialize the PRNG state unpredictably from the system entropy pool.

Security model

The arc4random functions provide the following security properties against three different classes of attackers, assuming enough entropy is provided by the operating system:

1. An attacker who has seen some outputs of any of the arc4random functions cannot predict past or future unseen outputs.

2. An attacker who has seen the library's PRNG state in memory cannot predict past outputs.

3. An attacker who has seen one process's PRNG state cannot predict past or future outputs in other processes, particularly its parent or siblings.

One ‘output’ means the result of any single request to an arc4random function, no matter how short it is.

The second property is sometimes called ‘forward secrecy’, ‘backtracking resistance’, or ‘key erasure after each output’.

Implementation notes

The arc4random functions are currently implemented using the ChaCha20 pseudorandom function family. For any 32-byte string s, ChaCha20_s is a function from 16-byte strings to 64-byte strings. It is conjectured that if s is chosen with uniform distribution, then the distribution on ChaCha20_s is indistinguishable to a computationally bounded adversary from a uniform distribution on all functions from 16-byte strings to 64-byte strings.

The PRNG state is a 32-byte ChaCha20 key s. Each request to an arc4random function

• computes the 64-byte quantity x = ChaCha20_s(0),

• splits x into two 32-byte quantities s' and k,

• replaces s by s', and

• uses k as output.

arc4random() yields the first four bytes of k as output directly. arc4random_buf() either yields up to 32 bytes of k as output directly, or, for longer requests, uses k as a ChaCha20 key and yields the concatenation ChaCha20_k(0) || ChaCha20_k(1) || ... as output. arc4random_uniform() repeats arc4random() until it obtains an integer in [2^32 % bound, 2^32), and reduces that modulo bound.

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 pthread_atfork(3), and the per-thread PRNG state is zeroed on fork in the child via minherit(2) with 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 arc4random function after zeroing.

The first use of an arc4random function may abort the process in the highly unlikely event that library initialization necessary to implement the security model fails. Additionally, arc4random_stir() and arc4random_addrandom() may abort the process in the highly unlikely event that the operating system fails to provide entropy.