1JITTERENTROPY(3)           Library Functions Manual           JITTERENTROPY(3)
2
3
4

NAME

6       jitterentropy - CPU Jitter Random Number Generator
7

SYNOPSIS

9       #include <jitterentropy.h>
10
11       int jent_entropy_switch_notime_impl(struct jent_notime_thread *new_thread);
12
13       int jent_set_fips_failure_callback(jent_fips_failure_cb cb);
14
15       int jent_entropy_init(void);
16
17       int jent_entropy_init_ex(unsigned int osr, unsigned int flags);
18
19       struct rand_data *jent_entropy_collector_alloc(unsigned int osr,
20                                                      unsigned int flags);
21
22       void jent_entropy_collector_free(struct rand_data *entropy_collector);
23
24       ssize_t jent_read_entropy(struct rand_data *entropy_collector,
25                                 char *data, size_t len);
26
27       ssize_t jent_read_entropy_safe(struct rand_data **entropy_collector,
28                                      char *data, size_t len);
29
30       unsigned int jent_version(void);
31

DESCRIPTION

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
40       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
45       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
49       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
55       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
63       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
72       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
79       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  0
85       here to apply the default oversampling. The call ensures that any value
86       lower than JENT_MIN_OSR is converted to JENT_MIN_OSR automatically.
87
88       The flags value is either zero or one or more of the following flags.
89
90       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
103       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
115       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
123       JENT_FORCE_FIPS
124              Force full FIPS 140 and SP800-90B compliance irrespective of the
125              FIPS setting of the underlying operating system.
126
127       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
139       jent_entropy_collector_free() zeroizes and frees the given  CPU  Jitter
140       entropy collector instance.
141
142       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
160       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
169       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
177       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
181       The function jent_read_entropy_safe()  has  the  same  error  codes  as
182       jent_read_entropy().
183
184       jent_version()  returns the version number of the library as an integer
185       value that is monotonically increasing.
186

FIPS 140-3 Considerations

188       In order for the Jitter RNG to execute compliant to FIPS 140-3  and  by
189       extension also SP800-90B and SP800-90C compliant, the following consid‐
190       erations must be applied:
191
192       Enable FIPS mode
193              The FIPS mode is enabled by using the JENT_FORCE_FIPS flag  dur‐
194              ing  initialization of the Jitter RNG library. On Linux, the the
195              FIPS mode is transparently enabled if the entire operating  sys‐
196              tem was booted in FIPS mode, usually by using the "fips=1" Linux
197              kernel command line parameter.
198
199       Perform heursitic entropy analysis
200              The test tool set provided as part of  the  Jitter  RNG  library
201              source distribution contains the helper to obtain raw noise data
202              at runtime as well as at initialization time  to  calculate  the
203              SP800-90B  entropy rate.  This rate must be above 0.333, the im‐
204              plied heuristic minimum by the Jitter RNG library.
205
206       Resolve insufficient entropy
207              If insufficient  entropy  is  found  during  the  aforementioned
208              SP800-90B  analysis, the test tool set provides a helper to ana‐
209              lyze optimal settings - see the test tool set  for  raw  entropy
210              for  details. The resulting configuration values are expected to
211              be used with the flags parameter of the calls  jent_entropy_col‐
212              lector_alloc()  and  jent_entropy_init_ex().   It is recommended
213              that the function jent_read_entropy_safe() API call is used  for
214              generating random numbers.
215

NOTES

217       In addition to use the generated random bit stream directly for crypto‐
218       graphic operations, the output of jent_read_entropy() can be  used  for
219       seeding a deterministic random number generator.
220

SEE ALSO

222       http://www.chronox.de  provides the design description, the entropy and
223       statistical analyses as well as a number of test cases.
224
225
226
227                                  2021-03-08                  JITTERENTROPY(3)
Impressum