Provided by: libjitterentropy3-dev_3.6.3-1_amd64 
NAME
jitterentropy - CPU Jitter Random Number Generator
SYNOPSIS
#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);
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_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.
FIPS 140-3 Considerations
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.
NOTES
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.
SEE ALSO
http://www.chronox.de provides the design description, the entropy and statistical analyses as well as a
number of test cases.
2021-03-08 JITTERENTROPY(3)