Main index | Section 9 | Options |

#include <sys/libkern.h>

#include <sys/random.h>

#include <sys/libkern.h>

The
`arc4random()`
and
`arc4random_buf()`
functions will return very good quality random numbers, suited for
security-related purposes.
Both are wrappers around the underlying
`arc4rand()`
interface.
`arc4random()`
returns a 32-bit random value, while
`arc4random_buf()`
fills
ptr
with
len
bytes of random data.

The
`arc4rand()`
CSPRNG
is seeded from the
random(4)
kernel abstract entropy device.
Automatic reseeding happens at unspecified time and bytes (of output)
intervals.
A reseed can be forced by passing a non-zero
reseed
value.

The
`read_random()`
function is used to read entropy directly from the kernel abstract entropy
device.
`read_random()`
blocks if and until the entropy device is seeded.
The provided
buffer
is filled with no more than
count
bytes.
It is strongly advised that
`read_random()`
is not used directly;
instead, use the
`arc4rand()`
family of functions.

The
`is_random_seeded()`
function can be used to check in advance if
`read_random()`
will block.
(If random is seeded, it will not block.)

The
`read_random_uio()`
function behaves identically to
read(2)
on
` /dev/random`.
The
uio
argument points to a buffer where random data should be stored.
If
nonblock
is true and the random device is not seeded, this function does not return any
data.
Otherwise, this function may block interruptibly until the random device is seeded.
If the function is interrupted before the random device is seeded, no data is
returned.

The legacy
`random()`
function will produce a sequence of numbers that can be duplicated by calling
`srandom()`
with some constant as the
seed.
The legacy
`srandom()`
function may be called with any
seed
value.
It is strongly advised that the
`random()`
function not be used to generate random numbers.
See
SECURITY CONSIDERATIONS.

The
`arc4rand()`
function uses the Chacha20 algorithm to generate a pseudo-random sequence of
bytes.
The
`arc4random()`
function uses
`arc4rand()`
to generate pseudo-random numbers
in the range from 0 to
2^{32}-1.

The
`read_random()`
function returns
the number of bytes placed in
buffer.

`read_random_uio()`
returns zero when successful,
otherwise an error code is returned.

The legacy
`random()`
function uses
a non-linear additive feedback random number generator
employing a default table
of size 31
containing long integers
to return successive pseudo-random
numbers in the range from 0 to
2^{31}-1.
The period of this random number generator
is very large,
approximately
16µ(2^{31}-1).

[EFAULT]
| |

uio points to an invalid memory region. | |

[EWOULDBLOCK]
| |

The random device is unseeded and nonblock is true. | |

Do not use
`random()`
or
`srandom()`
in new code.

It is important to remember that the
`random()`
function is entirely predictable.
It is easy for attackers to predict future output of
`random()`
by recording some generated values.
We cannot emphasize strongly enough that
`random()`
must not be used to generate values that are intended to be unpredictable.

RANDOM (9) | April 16, 2019 |

Main index | Section 9 | Options |

Please direct any comments about this manual page service to Ben Bullock. Privacy policy.

“ | As soon as we started programming, we found to our surprise that it wasn't as easy to get programs right as we had thought. Debugging had to be discovered. I can remember the exact instant when I realized that a large part of my life from then on was going to be spent in finding mistakes in my own programs. | ” |

— Maurice Wilkes |