.\" Copyright (c) 2013 - 2024 by Stephan Mueller (smueller@chronox.de) .\" .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. .TH JITTERENTROPY 3 2021-03-08 .SH NAME jitterentropy \- CPU Jitter Random Number Generator .SH SYNOPSIS .nf .B #include .sp .BI "int jent_entropy_switch_notime_impl(struct jent_notime_thread *" new_thread ); .sp .BI "int jent_set_fips_failure_callback(jent_fips_failure_cb " cb "); .sp .BI "int jent_entropy_init(" void "); .sp .BI "int jent_entropy_init_ex(unsigned int " osr ", unsigned int " flags ); .sp .BI "struct rand_data *jent_entropy_collector_alloc(unsigned int " osr ", .BI " unsigned int " flags ); .sp .BI "void jent_entropy_collector_free(struct rand_data *" entropy_collector ); .sp .BI "ssize_t jent_read_entropy(struct rand_data *" entropy_collector ", .BI " char *" data ", size_t " len ); .sp .BI "ssize_t jent_read_entropy_safe(struct rand_data **" entropy_collector ", .BI " char *" data ", size_t " len ); .sp .BI "#define JENT_MAJVERSION x" .sp .BI "#define JENT_MINVERSION y" .sp .BI "#define JENT_PATCHLEVEL z" .sp .BI "#define JENT_VERSION (...)" .sp .BI "unsigned int jent_version(" void "); .fi .SH DESCRIPTION The .I 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. .LP 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. .LP 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 .IR /dev/random or .IR /dev/urandom . .LP .BR 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 .IR jitterentropy.h for a documentation of .IR new_thread . This function must be called before .BR jent_entropy_init () as after this call, the change of the thread handler is denied. .LP .BR 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 .BR cb to the API function receives the Jitter RNG state with the parameter .BR ec and the FIPS health test failure with the parameter .BR health_failure . his function must be called before .BR jent_entropy_init () as after this call, the change of the callback is denied. .LP .BR 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 .IR 0 . A return code other than .IR 0 indicates a failure where the calling application .B MUST NOT use the CPU Jitter Random Number Generator. .LP .BR jent_entropy_init_ex () behaves identically to .BR jent_entropy_init () except that it allows the caller to provide the .IR osr and .IR flags parameters which should be identical to the subsequent invocation of .BR jent_entropy_collector_alloc (). When specifying an oversampling rate .IR 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. .LP .BR 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 .IR NULL . The function requires two arguments, the oversampling rate .IR osr and a set of flags with .IR flags . The .IR 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 .B JENT_MIN_OSR is converted to .B JENT_MIN_OSR automatically. .LP The .IR flags value is either zero or one or more of the following flags. .TP .B 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. .TP .B 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 .BR 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 .IR entropy_collector data structure. .TP .B 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 .B JENT_FORCE_INTERNAL_TIMER this is treated as an error and the allocation returns NULL. Also, in case .BR jent_entropy_init () detects that the internal timer shall be used but the disable flag is set, the allocation returns NULL. .TP .B JENT_FORCE_FIPS Force full FIPS 140 and SP800-90B compliance irrespective of the FIPS setting of the underlying operating system. .TP .B 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. .LP .BR jent_entropy_collector_free() zeroizes and frees the given CPU Jitter entropy collector instance. .LP .BR jent_read_entropy () generates a random bit stream and returns it to the caller. .IR entropy_collector is the CPU Jitter entropy collector instance which shall be used to obtain random numbers. .IR data is the destination memory location where the random bit stream is written to. The memory must have already been allocated by the caller. .IR 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 .IR data is at least als big as .IR len indicates. The function returns the number of bytes generated when the request is successfully completed. If the function returns the error code .IR -1 then the caller handed in a non-initialized (i.e. NULL value) for the entropy collector. The return code of .IR -2 indicates the SP800-90B repetition count online health test failed. The error code of .IR -3 specifies that the SP800-90B adaptive proportion online health test failed. .IR -4 marks that the internal timer generator cannot be initialized. .IR -5 specifies that the LAG predictor health test failed. .IR -6 indicates that the Repetitive Count Test (RCT) failed permanently. .IR -7 indicates that the Adaptive Proportion Test (APT) failed permanently. .IR -8 indicates that the LAG prediction test failed permanently. .LP When either online health test fails the Jitter RNG will not have any data provided in .IR data . The entropy collector instance will remain in error state. To recover, the entropy collector instance .B MUST be deallocated and a fresh instance must be allocated. It is recommended that you increase the .IR osr value at least by one when newly allocating the Jitter RNG with .BR 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. .LP .BR jent_read_entropy_safe () is a service function to and therefore operates identically to .BR 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. .LP 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. .LP The function .BR jent_read_entropy_safe () has the same error codes as .BR jent_read_entropy (). .LP .BR JENT_MAJVERSION indicates API / ABI incompatible changes, functional changes that require consumer to be updated. .LP .BR JENT_MINVERSION indicates API compatible, ABI may change, functional enhancements only, consumer can be left unchanged if enhancements are not considered. .LP .BR 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. .LP .BR 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. .LP .BR jent_version () returns .BR JENT_VERSION. .PP .SH 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: .TP .B Enable FIPS mode The FIPS mode is enabled by using the .IR 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. .TP .B 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. .TP .B 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 .IR flags parameter of the calls .BR jent_entropy_collector_alloc () and .BR jent_entropy_init_ex () . It is recommended that the function .BR jent_read_entropy_safe () API call is used for generating random numbers. .PP .SH NOTES In addition to use the generated random bit stream directly for cryptographic operations, the output of .BR jent_read_entropy () can be used for seeding a deterministic random number generator. .PP .SH SEE ALSO http://www.chronox.de provides the design description, the entropy and statistical analyses as well as a number of test cases.