FreeBSD Manual Pages
JITTERENTROPY(3) Library Functions Manual JITTERENTROPY(3) 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 collect- ing 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 mea- surements 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 main- tained 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 de- tected. The callback specified with the parameter cb to the API func- tion 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 en- tropy. 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() ex- cept that it allows the caller to provide the osr and flags parameters which should be identical to the subsequent invocation of jent_en- tropy_collector_alloc(). When specifying an oversampling rate osr dif- ferent 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 re- quires 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 re- lies on the complexity of the CPU. Note, if somebody knows all details of that CPU complexity, that person may potentially re- duce 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 inter- nal high-resolution timer instead of using the hardware time stamp. Commonly, the startup self test performed with jent_en- tropy_init() uses the hardware timer with precedence if it is identified to be appropriate for entropy collection. If the in- ternal 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_INTER- NAL_TIMER this is treated as an error and the allocation returns NULL. Also, in case jent_entropy_init() detects that the inter- nal timer shall be used but the disable flag is set, the alloca- tion 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. With- out 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 suffi- cient a lower memory size may be used. Contrary when having suf- ficient 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 gener- ated when the request is successfully completed. If the function re- turns 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 in- dicates the SP800-90B repetition count online health test failed. The error code of -3 specifies that the SP800-90B adaptive proportion on- line 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 per- manently. -7 indicates that the Adaptive Proportion Test (APT) failed permanently. -8 indicates that the LAG prediction test failed perma- nently. 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 deallo- cated 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 en- tropy rate of the noise source is lower. jent_read_entropy_safe() is a service function to and therefore oper- ates identically to jent_read_entropy() with the exception that it au- tomatically re-allocates the entropy collector if a health test failure is observed. Before reallocation, a new power-on health test is per- formed. The allocation of the new entropy collector automatically in- creases 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 get- ting 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 dig- its 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 consid- erations must be applied: Enable FIPS mode The FIPS mode is enabled by using the JENT_FORCE_FIPS flag dur- ing initialization of the Jitter RNG library. On Linux, the the FIPS mode is transparently enabled if the entire operating sys- tem 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 im- plied 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 ana- lyze 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_col- lector_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 crypto- graphic 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)
NAME | SYNOPSIS | DESCRIPTION | FIPS 140-3 Considerations | NOTES | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=jitterentropy&sektion=3&manpath=FreeBSD+Ports+15.0.quarterly>