jitterentropy - Man Page

#include <jitterentropy.h>

int jent_entropy_switch_notime_impl(struct jent_notime_thread *new_thread);

int jent_set_fips_failure_callback(jent_fips_failure_cb cb);

int jent_entropy_init(void);

int jent_entropy_init_ex(unsigned int osr, unsigned int flags);

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);

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

#define JENT_MAJVERSION x

#define JENT_MINVERSION y

#define JENT_PATCHLEVEL z

#define JENT_VERSION (...)

unsigned int jent_version(void);

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_switch_notime_impl() allows the caller to set a thread handler that is used by the Jitter RNG if it operates in the timer-less mode. See jitterentropy.h for a documentation of new_thread. This function must be called before jent_entropy_init() as after this call, the change of the thread handler is denied.

jent_set_fips_failure_callback() allows the caller to set a callback that is invoked by the Jitter RNG when a health test failure is detected. The callback specified with the parameter cb to the API function receives the Jitter RNG state with the parameter ec and the FIPS health test failure with the parameter health_failure. his function must be called before jent_entropy_init() as after this call, the change of the callback is denied.

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_init_ex() behaves identically to jent_entropy_init() except that it allows the caller to provide the osr and flags parameters which should be identical to the subsequent invocation of jent_entropy_collector_alloc(). When specifying an oversampling rate osr different than the default, the startup test honor this value and adjust the self-test cut-off thresholds to the same values as used at runtime.

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 0 here to apply the default oversampling. The call ensures that any value lower than JENT_MIN_OSR is converted to JENT_MIN_OSR automatically.

The flags value is either zero or one or more of the following flags.

JENT_DISABLE_MEMORY_ACCESS

If the system is constrained with memory, this flag 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_FORCE_INTERNAL_TIMER

This flag can be used to force the Jitter RNG to use the internal high-resolution timer instead of using the hardware time stamp. Commonly, the startup self test performed with jent_entropy_init() uses the hardware timer with precedence if it is identified to be appropriate for entropy collection. If the internal timer is not compiled, requesting this flag returns an error. Even though a separate thread is spawned to provide a high-resolution time stamp, this entire operation is completely thread-safe as all relevant data is maintained as part of the entropy_collector data structure.

JENT_DISABLE_INTERNAL_TIMER

This flag can be used to ensure that the internal timer is not used. If this flag is used together with JENT_FORCE_INTERNAL_TIMER this is treated as an error and the allocation returns NULL. Also, in case jent_entropy_init() detects that the internal timer shall be used but the disable flag is set, the allocation returns NULL.

JENT_FORCE_FIPS

Force full FIPS 140 and SP800-90B compliance irrespective of the FIPS setting of the underlying operating system.

JENT_MAX_MEMSIZE_*

Define the maximum amount of memory that the Jitter RNG will use for its operation supporting the collection of raw noise. Without using one of these flags, the Jitter RNG uses a built-in limit. The larger the amount of memory is the more entropy is collected. Yet, the default value is safe on most CPUs. If you have memory pressure but the entropy rate of your CPU is sufficient a lower memory size may be used. Contrary when having sufficient memory but insufficient entropy, larger memory sizes may be specified. In any case, the Jitter RNG uses at most as much memory as the sum of the CPU's data caches.

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 SP800-90B adaptive proportion online health test failed. -4 marks that the internal timer generator cannot be initialized. -5 specifies that the LAG predictor health test failed. -6 indicates that the Repetitive Count Test (RCT) failed permanently. -7 indicates that the Adaptive Proportion Test (APT) failed permanently. -8 indicates that the LAG prediction test failed permanently.

When either online health test fails the Jitter RNG will not have any data provided in data. 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. It is recommended that you increase the osr value at least by one when newly allocating the Jitter RNG with jent_entropy_collector_alloc() which implies that the health tests are less sensitive due to the fact that the assumed entropy rate of the noise source is lower.

jent_read_entropy_safe() is a service function to and therefore operates identically to jent_read_entropy() with the exception that it automatically re-allocates the entropy collector if a health test failure is observed. Before reallocation, a new power-on health test is performed. The allocation of the new entropy collector automatically increases the OSR by one. This is done based on the idea that a health test failure indicates that the assumed entropy rate is too high.

Note the function returns with an health test error if the OSR is getting too large. If an error is returned by this function, the Jitter RNG is not safe to be used on the current system.

The function jent_read_entropy_safe() has the same error codes as jent_read_entropy().

JENT_MAJVERSION indicates API / ABI incompatible changes, functional changes that require consumer to be updated.

JENT_MINVERSION indicates API compatible, ABI may change, functional enhancements only, consumer can be left unchanged if enhancements are not considered.

JENT_PATCHLEVEL indicates API / ABI compatible, no functional changes, no enhancements, bug fixes only. Also, the entropy collection is not changed in any way that would necessitate a re-assessment.

JENT_VERSION the version number of the library as an integer value that is monotonically increasing. The version numbers are multiples of 100. For example, version 1.2.3 is converted to 1020300 -- the last two digits are reserved for future use.

jent_version() returns JENT_VERSION.

In order for the Jitter RNG to execute compliant to FIPS 140-3 and by extension also SP800-90B and SP800-90C compliant, the following considerations must be applied:

Enable FIPS mode

The FIPS mode is enabled by using the JENT_FORCE_FIPS flag during initialization of the Jitter RNG library. On Linux, the the FIPS mode is transparently enabled if the entire operating system was booted in FIPS mode, usually by using the "fips=1" Linux kernel command line parameter.

Perform heursitic entropy analysis

The test tool set provided as part of the Jitter RNG library source distribution contains the helper to obtain raw noise data at runtime as well as at initialization time to calculate the SP800-90B entropy rate. This rate must be above 0.333, the implied heuristic minimum by the Jitter RNG library.

Resolve insufficient entropy

If insufficient entropy is found during the aforementioned SP800-90B analysis, the test tool set provides a helper to analyze optimal settings - see the test tool set for raw entropy for details. The resulting configuration values are expected to be used with the flags parameter of the calls jent_entropy_collector_alloc() and jent_entropy_init_ex(). It is recommended that the function jent_read_entropy_safe() API call is used for generating random numbers.

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.

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