33.5 Generating Unpredictable Bytes

Some cryptographic applications (such as session key generation) need unpredictable bytes.

In general, application code should use a deterministic random bit generator, which could call the getentropy function described below internally to obtain randomness to seed the generator. The getrandom function is intended for low-level applications which need additional control over the blocking behavior.

Function: int getentropy (void *buffer, size_t length)

| MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function writes length bytes of random data to the array starting at buffer, which must be at most 256 bytes long. The function returns zero on success. On failure, it returns -1 and errno is updated accordingly.

The getentropy function is declared in the header file sys/random.h. It is derived from OpenBSD.

The getentropy function is not a cancellation point. A call to getentropy can block if the system has just booted and the kernel entropy pool has not yet been initialized. In this case, the function will keep blocking even if a signal arrives, and return only after the entropy pool has been initialized.

The getentropy function can fail with several errors, some of which are listed below.

ENOSYS

The kernel does not implement the required system call.

EFAULT

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

EIO

More than 256 bytes of randomness have been requested, or the buffer could not be overwritten with random data for an unspecified reason.

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 length bytes of random data to the array starting at buffer. On success, this function returns the number of bytes which have been written to the buffer (which can be less than length). On error, -1 is returned, and errno is updated accordingly.

The getrandom function is declared in the header file sys/random.h. It is a GNU extension.

The following flags are defined for the flags argument:

GRND_RANDOM

Use the /dev/random (blocking) pool instead of the /dev/urandom (non-blocking) pool to obtain randomness. If the GRND_RANDOM flag is specified, the getrandom function can block even after the randomness source has been initialized.

GRND_NONBLOCK

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

The getrandom function is a cancellation point.

Obtaining randomness from the /dev/urandom pool (i.e., a call without the GRND_RANDOM flag) can block if the system has just booted and the pool has not yet been initialized.

The getrandom function can fail with several errors, some of which are listed below. In addition, the function may not fill the buffer completely and return a value less than length.

ENOSYS

The kernel does not implement the getrandom system call.

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.