Unpredictable Bytes (The GNU C Library)

### 34.1 Generating Unpredictable Bytes ¶

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.

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.

  `GRND_INSECURE`

    Write 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:

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