ARC4RANDOM(3) BSD Programmer's Manual ARC4RANDOM(3)
arc4random, arc4random_buf, arc4random_uniform, arc4random_stir,
arc4random_addrandom, arc4random_push, arc4random_pushb,
arc4random_pushb_fast, arc4random_pushk - arcfour based stretching random
number generator
#include <stdlib.h>
u_int32_t
arc4random(void);
void
arc4random_buf(void *buf, size_t nbytes);
u_int32_t
arc4random_uniform(u_int32_t upper_bound);
void
arc4random_stir(void);
void
arc4random_addrandom(u_char *dat, int datlen);
void (deprecated)
arc4random_push(int value);
uint32_t (deprecated)
arc4random_pushb(const void *buf, size_t len);
uint32_t (deprecated)
arc4random_pushk(const void *buf, size_t len);
void
arc4random_pushb_fast(const void *buf, size_t len);
The arc4random() function provides a high quality 32-bit pseudo-random
number very quickly. arc4random() seeds itself on a regular basis from
the kernel strong random number subsystem described in random(4). On each
call, an aRC4 generator is used to generate a new result. The
arc4random() function uses the aRC4 cipher key stream generator, which
uses 8*8 8-bit S-Boxes. The S-Boxes can be in about (2**1684) states. To-
gether with the counters, this amounts to about 212 octets of entropy.
arc4random() fits into a middle ground not covered by other subsystems
such as the strong, slow, and resource expensive random devices described
in random(4) versus the fast but poor quality interfaces described in
rand(3), random(3), and drand48(3).
arc4random_buf() fills the region buf of length nbytes with aRC4-derived
random data.
arc4random_uniform() will return a uniformly distributed random number
less than upper_bound. arc4random_uniform() is recommended over construc-
tions like "arc4random() % upper_bound" as it avoids "modulo bias" when
the upper bound is not a power of two.
The arc4random_stir() function collects data from the user-space SRNG and
queued for upload, sends it to the kernel and receives new entropic data
using sysctl(3) from kern.arandom and uses it to permute the S-Boxes.
There is no need to call arc4random_stir() before using arc4random(),
since arc4random() automatically initialises itself. Explicit calls will,
however, trigger kernel pushing after arc4random_pushb_fast() has been
used to queue some data for doing so.
The arc4random_pushb_fast() function will queue the data passed for
upload on the next stir using a (non-cryptographic) hash algorithm, which
is only used for collapsing/compressing the data into the queue buffer.
The deprecated arc4random_push() function behaves the same, except in-
stead of being passed a buffer and its size for pushing, it takes a
direct numeric argument. The deprecated arc4random_pushk() and
arc4random_pushb() functions do exactly the same, namely call
arc4random_pushb_fast() and then call arc4random() and return its return
value.
The arc4random_addrandom() function implements an old, discouraged, API
with which the S-Boxes can be permuted directly from user-specified data.
If merely desiring to add entropy to the pool, use arc4random_pushb_fast
instead, which is much faster, unless you really want to do a KSA.
These functions are always successful, and no return value is reserved to
indicate an error.
rand(3), rand48(3), random(3), random(9)
An algorithm called RC4 was designed by RSA Data Security, Inc. It was
considered a trade secret. Because it was a trade secret, it obviously
could not be patented. A clone of this was posted anonymously to USENET
and confirmed to be equivalent by several sources who had access to the
original cipher. Because of the trade secret situation, RSA Data Securi-
ty, Inc. could do nothing about the release of the 'Alleged RC4' algo-
rithm. Since RC4 was trademarked, the cipher is now referred to as aRC4.
These functions first appeared in OpenBSD 2.1. arc4random_push() first
appeared in MirBSD #8. arc4random_pushb() first appeared in MirBSD #10.
arc4random_pushk() and arc4random_pushb_fast() first appeared in
MirBSD #11. All these functions were rewritten for MirBSD #11 and macros
for every function are now defined for easy existence checks.
MirBSD #10-current March 1, 2019 1