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