Cryptographic applications often need random data that will be as difficult as possible for a hostile eavesdropper to guess. The pseudo-random number generators provided by the GNU C Library (see Pseudo-Random Numbers) are not suitable for this purpose. They produce output that is statistically random, but fails to be unpredictable. Cryptographic applications require a cryptographic random number generator (CRNG), also known as a cryptographically strong pseudo-random number generator (CSPRNG) or a deterministic random bit generator (DRBG).
Currently, the GNU C Library does not provide a cryptographic random number generator, but it does provide functions that read cryptographically strong random data from a randomness source supplied by the operating system. This randomness source is a CRNG at heart, but it also continually “re-seeds” itself from physical sources of randomness, such as electronic noise and clock jitter. This means applications do not need to do anything to ensure that the random numbers it produces are different on each run.
The catch, however, is that these functions will only produce relatively short random strings in any one call. Often this is not a problem, but applications that need more than a few kilobytes of cryptographically strong random data should call these functions once and use their output to seed a CRNG.
Most applications should use getentropy. The getrandom
function is intended for low-level applications which need additional
control over blocking behavior.
int getentropy (void *buffer, size_t length) ¶| MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.
This function writes exactly length bytes of random data to the
array starting at buffer. length can be no more than 256.
On success, it returns zero. On failure, it returns -1, and
errno is set to indicate the problem. Some of the possible
errors are listed below.
ENOSYSThe operating system does not implement a randomness source, or does not support this way of accessing it. (For instance, the system call used by this function was added to the Linux kernel in version 3.17.)
EFAULTThe combination of buffer and length arguments specifies an invalid memory range.
EIOlength is larger than 256, or the kernel entropy pool has suffered a catastrophic failure.
A call to getentropy can only block when the system has just
booted and the randomness source has not yet been initialized.
However, if it does block, it cannot be interrupted by signals or
thread cancellation. Programs intended to run in very early stages of
the boot process may need to use getrandom in non-blocking mode
instead, and be prepared to cope with random data not being available
at all.
The getentropy function is declared in the header file
sys/random.h. It is derived from OpenBSD.
ssize_t getrandom (void *buffer, size_t length, unsigned int flags) ¶| MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.
This function writes up to length bytes of random data to the array starting at buffer. The flags argument should be either zero, or the bitwise OR of some of the following flags:
GRND_RANDOMUse the /dev/random (blocking) source instead of the /dev/urandom (non-blocking) source to obtain randomness.
If this flag is specified, the call may block, potentially for quite some time, even after the randomness source has been initialized. If it is not specified, the call can only block when the system has just booted and the randomness source has not yet been initialized.
GRND_NONBLOCKInstead of blocking, return to the caller immediately if no data is available.
GRND_INSECUREWrite random data that may not be cryptographically secure.
Unlike getentropy, the getrandom function is a
cancellation point, and if it blocks, it can be interrupted by
signals.
On success, getrandom returns the number of bytes which have
been written to the buffer, which may be less than length. On
error, it returns -1, and errno is set to indicate the
problem. Some of the possible errors are:
ENOSYSThe operating system does not implement a randomness source, or does not support this way of accessing it. (For instance, the system call used by this function was added to the Linux kernel in version 3.17.)
EAGAINNo random data was available and GRND_NONBLOCK was specified in
flags.
EFAULTThe combination of buffer and length arguments specifies an invalid memory range.
EINTRThe system call was interrupted. During the system boot process, before the kernel randomness pool is initialized, this can happen even if flags is zero.
EINVALThe flags argument contains an invalid combination of flags.
The getrandom function is declared in the header file
sys/random.h. It is a GNU extension.