--- name: "arc4random_buf" section: "3bsd" platform: "linux" package: "libbsd" version: "0.12.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/arc4random/3bsd" --- # arc4random\_buf(3bsd) random number generator Part of [arc4random(3bsd)](/arc4random/3bsd.md). ## NAME **arc4random**, **arc4random\_uniform**, **arc4random\_buf**, **arc4random\_stir**, **arc4random\_addrandom** – random number generator ## LIBRARY library “libbsd” ## SYNOPSIS **#include \** (See [libbsd(7)](/libbsd/7.md) for include usage.) *uint32\_t*\ **arc4random**(*void*); *uint32\_t*\ **arc4random\_uniform**(*uint32\_t bound*); *void*\ **arc4random\_buf**(*void \*buf*, *size\_t len*); *void*\ **arc4random\_stir**(*void*); *void*\ **arc4random\_addrandom**(*unsigned char \*buf*, *int len*); ## DESCRIPTION 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)](/rand/3.md) and [random(3)](/random/3.md), 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)](/pthread_atfork/3.md), and the per-thread PRNG state is zeroed on fork in the child via [minherit(2)](/minherit/2.md) 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. ## SEE ALSO [rand(3)](/rand/3.md), [random(3)](/random/3.md), rnd(4), cprng(9) Daniel J. Bernstein, *ChaCha, a variant of Salsa20*, 2008-01-28, Document ID: 4027b5256e17b9796842e6d0f68b0b5e, http://cr.yp.to/papers.html#chacha. ## HISTORY These functions first appeared in OpenBSD 2.1, FreeBSD 3.0, NetBSD 1.6, and DragonFly 1.0. The functions **arc4random**(), **arc4random\_buf**() and **arc4random\_uniform**() appeared in glibc 2.36. ## BUGS There is no way to get deterministic, reproducible results out of **arc4random** for testing purposes. The name ‘arc4random’ was chosen for hysterical raisins -- it was originally implemented using the RC4 stream cipher, which has been known since shortly after it was published in 1994 to have observable biases in the output, and is now known to be broken badly enough 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. The signature of **arc4random\_addrandom**() is silly. There is no reason to require casts or accept negative lengths: it should take a *void* *\** buffer and a *size\_t* length. But it's too late to change that now. **arc4random\_uniform**() does not help to choose integers in \[0, *n*) uniformly at random when *n* \> 2^32. The security model of **arc4random** is stronger than many applications need, and stronger than other operating systems provide. For example, applications encrypting messages with random, but not secret, initialization vectors need only prevent an adversary from guessing future outputs, since past outputs will have been published already. On the one hand, **arc4random** could be marginally faster if it were not necessary to prevent an adversary who sees the state from predicting past outputs. On the other hand, there are applications in the wild that use **arc4random** to generate key material, such as OpenSSH, so for the sake of NetBSD users it would be imprudent to weaken the security model. On the third hand, relying on the security model of **arc4random** in NetBSD may lead you to an unpleasant surprise on another operating system whose implementation of **arc4random** has a weaker security model. One may be tempted to create new APIs to accommodate different security models and performance constraints without unpleasant surprises on different operating systems. This should not be done lightly, though, because there are already too many different choices, and too many opportunities for programmers to reach for one and pick the wrong one.