NAME

poll_entropy_src, get_error_message - cross-platform cryptographically secure random number generation

SYNOPSIS

#include "entropy_src.h"

int poll_entropy_src(void *data, unsigned char *output, size_t ilen,
                     size_t *olen);

const char* get_error_message(ErrorCode code);

DESCRIPTION

The poll_entropy_src interface provides a robust, portable, and secure method for generating high-quality random bytes for cryptographic operations.

It uses a tiered strategy to ensure the best available entropy source is always used on any given platform, prioritizing modern, dedicated OS system calls over older mechanisms. This ensures maximum security and reliability while maintaining broad compatibility with modern and legacy systems.

IMPLEMENTATION STRATEGY

The implementation uses the following tiers, from highest to lowest priority:

Tier 1: Modern System Calls

The preferred method on modern Unix-like systems. These are direct, efficient, and safe kernel interfaces.
- getrandom(2) on Linux (Kernel 3.17+)
- arc4random_buf(3) on macOS (10.12+), FreeBSD, and OpenBSD
Tier 2: High-Level Cryptographic APIs

Used on platforms that provide a dedicated crypto API, or as a fallback.
- BCryptGenRandom(3) on Windows (primary method)
- SecRandomCopyBytes(3) on macOS (fallback)
Tier 3: Legacy Device Files

The universal fallback for ensuring broad compatibility.
- /dev/urandom (primary fallback)
- /dev/random (legacy fallback for very old systems)

FUNCTIONS

poll_entropy_src

Generates a specified number of cryptographically secure random bytes by polling the best available system source. It writes the generated bytes into the provided output buffer.
get_error_message

Takes an ErrorCode value returned by poll_entropy_src on failure and returns a constant, human-readable string describing the error.

PARAMETERS

data

A pointer for API compatibility, primarily for use in callback-style interfaces. This implementation does not use this parameter, and callers should pass NULL.
output

Pointer to the buffer where the random bytes will be stored.
ilen

The number of random bytes to generate.
olen

Pointer to a uvast variable where the function will store the actual number of bytes that were successfully generated.

RETURN VALUES

On success, poll_entropy_src returns 0. On failure, it returns a negative ErrorCode value.

0 - Success.
-1 (INVALID_ARGUMENTS) - A required pointer was NULL or `ilen` was 0.
-2 (ERROR_GETRANDOM_FAILED) - The getrandom() syscall failed on Linux.
-3 (ERROR_BCRYPT_FAILED) - The BCryptGenRandom function failed on Windows.
-4 (ERROR_SECRANDOM_FAILED) - The SecRandomCopyBytes function failed on macOS.
-5 (ERROR_OPENING_ENTROPY_SOURCE) - [Fallback] Could not open an entropy device file.
-6 (ERROR_READING_ENTROPY_SOURCE) - [Fallback] Could not read from an entropy device file.

EXAMPLES

To generate 32 bytes of random data:

unsigned char buffer[32];
uvast bytes_generated;
int result = poll_entropy_src(NULL, buffer, sizeof(buffer), &bytes_generated);

if (result == 0 && bytes_generated == sizeof(buffer)) {
    // Successfully generated 32 random bytes, now use buffer.
} else {
    // Handle error...
    fprintf(stderr, "Error: %s\n", get_error_message(result));
}

BUGS

Report bugs to <https://github.com/nasa-jpl/ION-DTN/issues>.