JITTERENTROPY(3)

NAME
jitterentropy - CPU Jitter Random Number Generator

SYNOPSIS
#include <jitterentropy.h>

int jent_entropy_init(void);

struct rand_data *jent_entropy_collector_alloc(unsigned int osr,
                                               unsigned int flags);

void jent_entropy_collector_free(struct rand_data *entropy_collector);

ssize_t jent_read_entropy(struct rand_data *entropy_collector,
                          char *data, size_t len);

unsigned int jent_version(void);

DESCRIPTION
The jitterentropy library provides a source of good entropy by collecting CPU executing time jitter. The entropy in the CPU execution time jitter is magnified by the CPU Jitter Random Number Generator. The CPU Jitter Random Number Generator uses the CPU execution timing jitter to generate a bit stream which complies with different statistical measurements that determine the bit stream is random.

The CPU Jitter Random Number Generator delivers entropy which follows information theoretical requirements. Based on these studies and the implementation, the caller can assume that one bit of data extracted from the CPU Jitter Random Number Generator holds one bit of entropy.

The CPU Jitter Random Number Generator provides a decentralized source of entropy where the caller does not need to rely on a centrally maintained source of entropy like /dev/random or /dev/urandom.

jent_entropy_init() initializes the CPU Jitter Random Number Generator. The function performs statistical tests to verify that the underlying system offers the properties needed for measuring and collecting entropy. If the initialization is successful, which implies that the statistical tests indicate the underlying system is appropriate, the call returns with 0. A return code other than 0 indicates a failure where the calling application MUST NOT use the CPU Jitter Random Number Generator.

jent_entropy_collector_alloc() allocates a CPU Jitter entropy collector instance and returns the handle to the caller. If the allocation fails, including memory constraints, the call returns NULL. The function requires two arguments, the oversampling rate osr and a set of flags with flags. The osr value defines the amount of oversampling performed by the entropy collector. Usually, a caller wants to provide the value 1 here to not perform oversampling. The value 0 is converted into a 1 automatically by the entropy collector.

The flags value is either zero or one or more of the following flags. If the system is constrained with memory, the flag JENT_DISABLE_MEMORY_ACCESS disables the allocation of that memory and therefore memory accesses. But that also implies that the entropy collection process only relies on the complexity of the CPU. Note, if somebody knows all details of that CPU complexity, that person may potentially reduce the entropy delivered by the CPU complexity. If that person can push the generated entropy below a threshold, the CPU Jitter random number generator starts overestimating entropy from the noise source. Thus, disabling memory accesses and relying only on the CPU complexity should only be done if you really know what you are doing.

jent_entropy_collector_free() zeroizes and frees the given CPU Jitter entropy collector instance.

jent_read_entropy() generates a random bit stream and returns it to the caller. entropy_collector is the CPU Jitter entropy collector instance which shall be used to obtain random numbers. data is the destination memory location where the random bit stream is written to. The memory must have already been allocated by the caller. len is a length value provided by the caller indicating the number of bytes the CPU Jitter Random Number Generator shall generate. The caller can provide any value greater than 0. The caller must ensure that data is at least als big as len indicates. The function returns the number of bytes generated when the request is successfully completed. If the function returns the error code -1 then the caller handed in a non-initialized (i.e. NULL value) for the entropy collector. The return code of -2 indicates the SP800-90B repetition count online health test failed. The error code of -3 specifies that the Chi-Squared online health test failed. When either online health test fails the Jitter RNG will not have any data provided in data. If either SP800-90B health test fails, the entropy collector instance will remain in error state. To recover, the entropy collector instance MUST be deallocated and a fresh instance must be allocated.

jent_version() returns the version number of the library as an integer value that is monotonically increasing.

NOTES
The CPU Jitter random number generator MUST NOT be compiled with compiler optimizations. A pre-processor check enforces this requirement.

The random bit stream generated by jent_read_entropy() is NOT processed by a cryptographically secure whitening function. Nonetheless, it is believed that the output can be used as a source for cryptographically secure key material or other cryptographically sensitive data.

In addition to use the generated random bit stream directly for cryptographic operations, the output of jent_read_entropy() can be used for seeding a deterministic random number generator, or perform a post processing with a cryptographically secure whitening function.

SEE ALSO
http://www.chronox.de provides the design description, the entropy and statistical analyses as well as a number of test cases.