---

33.2 Generating Unpredictable Bytes

Cryptographic applications often need some random data that will be as difficult as possible for a hostile eavesdropper to guess. For instance, encryption keys should be chosen at random, and the “salt” strings used by crypt (see Passphrase Storage) should also be chosen at random.

Some pseudo-random number generators do not provide unpredictable-enough output for cryptographic applications; see Pseudo-Random Numbers. Such applications need to use a cryptographic random number generator (CRNG), also sometimes called a cryptographically strong pseudo-random number generator (CSPRNG) or 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 random data from a randomness source supplied by the operating system. The 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.

Function: 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.

ENOSYS

The 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.)

EFAULT

The combination of buffer and length arguments specifies an invalid memory range.

EIO

length 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.

Function: 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_RANDOM

Use 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_NONBLOCK

Instead of blocking, return to the caller immediately if no data is available.

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:

ENOSYS

The 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.)

EAGAIN

No random data was available and GRND_NONBLOCK was specified in flags.

EFAULT

The combination of buffer and length arguments specifies an invalid memory range.

EINTR

The system call was interrupted. During the system boot process, before the kernel randomness pool is initialized, this can happen even if flags is zero.

EINVAL

The 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.