1JITTERENTROPY(3) Library Functions Manual JITTERENTROPY(3)
2
6 jitterentropy - CPU Jitter Random Number Generator
7
9 #include <jitterentropy.h>
10 int jent_entropy_switch_notime_impl(struct jent_notime_thread *new_thread);
12 int jent_set_fips_failure_callback(jent_fips_failure_cb cb);
14 int jent_entropy_init(void);
16 int jent_entropy_init_ex(unsigned int osr, unsigned int flags);
18 struct rand_data *jent_entropy_collector_alloc(unsigned int osr,
20 unsigned int flags);
21 void jent_entropy_collector_free(struct rand_data *entropy_collector);
23 ssize_t jent_read_entropy(struct rand_data *entropy_collector,
25 char *data, size_t len);
26 ssize_t jent_read_entropy_safe(struct rand_data **entropy_collector,
28 char *data, size_t len);
29 unsigned int jent_version(void);
31
33 The jitterentropy library provides a source of good entropy by collect‐
34 ing CPU executing time jitter. The entropy in the CPU execution time
35 jitter is magnified by the CPU Jitter Random Number Generator. The CPU
36 Jitter Random Number Generator uses the CPU execution timing jitter to
37 generate a bit stream which complies with different statistical mea‐
38 surements that determine the bit stream is random.
39 The CPU Jitter Random Number Generator delivers entropy which follows
41 information theoretical requirements. Based on these studies and the
42 implementation, the caller can assume that one bit of data extracted
43 from the CPU Jitter Random Number Generator holds one bit of entropy.
44 The CPU Jitter Random Number Generator provides a decentralized source
46 of entropy where the caller does not need to rely on a centrally main‐
47 tained source of entropy like /dev/random or /dev/urandom.
48 jent_entropy_switch_notime_impl() allows the caller to set a thread
50 handler that is used by the Jitter RNG if it operates in the timer-less
51 mode. See jitterentropy.h for a documentation of new_thread. This
52 function must be called before jent_entropy_init() as after this call,
53 the change of the thread handler is denied.
54 jent_set_fips_failure_callback() allows the caller to set a callback
56 that is invoked by the Jitter RNG when a health test failure is de‐
57 tected. The callback specified with the parameter cb to the API func‐
58 tion receives the Jitter RNG state with the parameter ec and the FIPS
59 health test failure with the parameter health_failure. his function
60 must be called before jent_entropy_init() as after this call, the
61 change of the callback is denied.
62 jent_entropy_init() initializes the CPU Jitter Random Number Generator.
64 The function performs statistical tests to verify that the underlying
65 system offers the properties needed for measuring and collecting en‐
66 tropy. If the initialization is successful, which implies that the
67 statistical tests indicate the underlying system is appropriate, the
68 call returns with 0. A return code other than 0 indicates a failure
69 where the calling application MUST NOT use the CPU Jitter Random Number
70 Generator.
71 jent_entropy_init_ex() behaves identically to jent_entropy_init() ex‐
73 cept that it allows the caller to provide the osr and flags parameters
74 which should be identical to the subsequent invocation of jent_en‐
75 tropy_collector_alloc(). When specifying an oversampling rate osr dif‐
76 ferent than the default, the startup test honor this value and adjust
77 the self-test cut-off thresholds to the same values as used at runtime.
78 jent_entropy_collector_alloc() allocates a CPU Jitter entropy collector
80 instance and returns the handle to the caller. If the allocation fails,
81 including memory constraints, the call returns NULL. The function re‐
82 quires two arguments, the oversampling rate osr and a set of flags with
83 flags. The osr value defines the amount of oversampling performed by
84 the entropy collector. Usually, a caller wants to provide the value 1
85 here to not perform oversampling. The value 0 is converted into a 1 au‐
86 tomatically by the entropy collector.
87 The flags value is either zero or one or more of the following flags.
89 JENT_DISABLE_MEMORY_ACCESS
91 If the system is constrained with memory, this flag disables the
92 allocation of that memory and therefore memory accesses. But
93 that also implies that the entropy collection process only re‐
94 lies on the complexity of the CPU. Note, if somebody knows all
95 details of that CPU complexity, that person may potentially re‐
96 duce the entropy delivered by the CPU complexity. If that person
97 can push the generated entropy below a threshold, the CPU Jitter
98 random number generator starts overestimating entropy from the
99 noise source. Thus, disabling memory accesses and relying only
100 on the CPU complexity should only be done if you really know
101 what you are doing.
102 JENT_FORCE_INTERNAL_TIMER
104 This flag can be used to force the Jitter RNG to use the inter‐
105 nal high-resolution timer instead of using the hardware time
106 stamp. Commonly, the startup self test performed with jent_en‐
107 tropy_init() uses the hardware timer with precedence if it is
108 identified to be appropriate for entropy collection. If the in‐
109 ternal timer is not compiled, requesting this flag returns an
110 error. Even though a separate thread is spawned to provide a
111 high-resolution time stamp, this entire operation is completely
112 thread-safe as all relevant data is maintained as part of the
113 entropy_collector data structure.
114 JENT_DISABLE_INTERNAL_TIMER
116 This flag can be used to ensure that the internal timer is not
117 used. If this flag is used together with JENT_FORCE_INTER‐
118 NAL_TIMER this is treated as an error and the allocation returns
119 NULL. Also, in case jent_entropy_init() detects that the inter‐
120 nal timer shall be used but the disable flag is set, the alloca‐
121 tion returns NULL.
122 JENT_FORCE_FIPS
124 Force full FIPS 140 and SP800-90B compliance irrespective of the
125 FIPS setting of the underlying operating system.
126 JENT_MAX_MEMSIZE_*
128 Define the maximum amount of memory that the Jitter RNG will use
129 for its operation supporting the collection of raw noise. With‐
130 out using one of these flags, the Jitter RNG uses a built-in
131 limit. The larger the amount of memory is the more entropy is
132 collected. Yet, the default value is safe on most CPUs. If you
133 have memory pressure but the entropy rate of your CPU is suffi‐
134 cient a lower memory size may be used. Contrary when having suf‐
135 ficient memory but insufficient entropy, larger memory sizes may
136 be specified. In any case, the Jitter RNG uses at most as much
137 memory as the sum of the CPU's data caches.
138 jent_entropy_collector_free() zeroizes and frees the given CPU Jitter
140 entropy collector instance.
141 jent_read_entropy() generates a random bit stream and returns it to the
143 caller. entropy_collector is the CPU Jitter entropy collector instance
144 which shall be used to obtain random numbers. data is the destination
145 memory location where the random bit stream is written to. The memory
146 must have already been allocated by the caller. len is a length value
147 provided by the caller indicating the number of bytes the CPU Jitter
148 Random Number Generator shall generate. The caller can provide any
149 value greater than 0. The caller must ensure that data is at least als
150 big as len indicates. The function returns the number of bytes gener‐
151 ated when the request is successfully completed. If the function re‐
152 turns the error code -1 then the caller handed in a non-initialized
153 (i.e. NULL value) for the entropy collector. The return code of -2 in‐
154 dicates the SP800-90B repetition count online health test failed. The
155 error code of -3 specifies that the SP800-90B adaptive proportion on‐
156 line health test failed. -4 marks that the internal timer generator
157 cannot be initialized. -5 specifies that the LAG predictor health test
158 failed.
159 When either online health test fails the Jitter RNG will not have any
161 data provided in data. The entropy collector instance will remain in
162 error state. To recover, the entropy collector instance MUST be deallo‐
163 cated and a fresh instance must be allocated. It is recommended that
164 you increase the osr value at least by one when newly allocating the
165 Jitter RNG with jent_entropy_collector_alloc() which implies that the
166 health tests are less sensitive due to the fact that the assumed en‐
167 tropy rate of the noise source is lower.
168 jent_read_entropy_safe() is a service function to and therefore oper‐
170 ates identically to jent_read_entropy() with the exception that it au‐
171 tomatically re-allocates the entropy collector if a health test failure
172 is observed. Before reallocation, a new power-on health test is per‐
173 formed. The allocation of the new entropy collector automatically in‐
174 creases the OSR by one. This is done based on the idea that a health
175 test failure indicates that the assumed entropy rate is too high.
176 Note the function returns with an health test error if the OSR is get‐
178 ting too large. If an error is returned by this function, the Jitter
179 RNG is not safe to be used on the current system.
180 The function jent_read_entropy_safe() has the same error codes as
182 jent_read_entropy().
183 jent_version() returns the version number of the library as an integer
185 value that is monotonically increasing.
186
188 In addition to use the generated random bit stream directly for crypto‐
189 graphic operations, the output of jent_read_entropy() can be used for
190 seeding a deterministic random number generator.
191
193 http://www.chronox.de provides the design description, the entropy and
194 statistical analyses as well as a number of test cases.
195 2021-03-08 JITTERENTROPY(3)