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_init(void);
12
13       struct rand_data *jent_entropy_collector_alloc(unsigned int osr,
14                                                      unsigned int flags);
15
16       void jent_entropy_collector_free(struct rand_data *entropy_collector);
17
18       ssize_t jent_read_entropy(struct rand_data *entropy_collector,
19                                 char *data, size_t len);
20
21       unsigned int jent_version(void);
22

DESCRIPTION

24       The jitterentropy library provides a source of good entropy by collect‐
25       ing CPU executing time jitter. The entropy in the  CPU  execution  time
26       jitter is magnified by the CPU Jitter Random Number Generator.  The CPU
27       Jitter Random Number Generator uses the CPU execution timing jitter  to
28       generate  a  bit  stream which complies with different statistical mea‐
29       surements that determine the bit stream is random.
30
31       The CPU Jitter Random Number Generator delivers entropy  which  follows
32       information  theoretical  requirements.  Based on these studies and the
33       implementation, the caller can assume that one bit  of  data  extracted
34       from the CPU Jitter Random Number Generator holds one bit of entropy.
35
36       The  CPU Jitter Random Number Generator provides a decentralized source
37       of entropy where the caller does not need to rely on a centrally  main‐
38       tained source of entropy like /dev/random or /dev/urandom.
39
40       jent_entropy_init() initializes the CPU Jitter Random Number Generator.
41       The function performs statistical tests to verify that  the  underlying
42       system  offers  the  properties  needed  for  measuring  and collecting
43       entropy.  If the initialization is successful, which implies  that  the
44       statistical  tests  indicate  the underlying system is appropriate, the
45       call returns with 0.  A return code other than 0  indicates  a  failure
46       where the calling application MUST NOT use the CPU Jitter Random Number
47       Generator.
48
49       jent_entropy_collector_alloc() allocates a CPU Jitter entropy collector
50       instance and returns the handle to the caller. If the allocation fails,
51       including memory constraints, the  call  returns  NULL.   The  function
52       requires  two  arguments,  the oversampling rate osr and a set of flags
53       with flags.  The osr value defines the amount of oversampling performed
54       by  the entropy collector. Usually, a caller wants to provide the value
55       1 here to not perform oversampling. The value 0 is converted into  a  1
56       automatically by the entropy collector.
57
58       The  flags  value is either zero or one or more of the following flags.
59       If the system is constrained with memory,  the  flag  JENT_DISABLE_MEM‐
60       ORY_ACCESS  disables the allocation of that memory and therefore memory
61       accesses. But that also implies that  the  entropy  collection  process
62       only  relies  on the complexity of the CPU. Note, if somebody knows all
63       details of that CPU complexity, that person may potentially reduce  the
64       entropy  delivered  by  the CPU complexity. If that person can push the
65       generated entropy below a threshold, the CPU Jitter random number  gen‐
66       erator  starts overestimating entropy from the noise source. Thus, dis‐
67       abling memory accesses and relying only on the  CPU  complexity  should
68       only be done if you really know what you are doing.
69
70       jent_entropy_collector_free()  zeroizes  and frees the given CPU Jitter
71       entropy collector instance.
72
73       jent_read_entropy() generates a random bit stream and returns it to the
74       caller.  entropy_collector is the CPU Jitter entropy collector instance
75       which shall be used to obtain random numbers.  data is the  destination
76       memory  location  where the random bit stream is written to. The memory
77       must have already been allocated by the caller.  len is a length  value
78       provided  by  the  caller indicating the number of bytes the CPU Jitter
79       Random Number Generator shall generate.  The  caller  can  provide  any
80       value  greater than 0. The caller must ensure that data is at least als
81       big as len indicates. The function returns the number of  bytes  gener‐
82       ated  when  the  request  is  successfully  completed.  If the function
83       returns the error code -1 then the caller handed in  a  non-initialized
84       (i.e.  NULL  value)  for  the  entropy collector. The return code of -2
85       indicates the SP800-90B repetition count  online  health  test  failed.
86       The  error code of -3 specifies that the Chi-Squared online health test
87       failed.  When either online health test fails the Jitter RNG  will  not
88       have any data provided in data.  If either SP800-90B health test fails,
89       the entropy collector instance will remain in error state. To  recover,
90       the entropy collector instance MUST be deallocated and a fresh instance
91       must be allocated.
92
93       jent_version() returns the version number of the library as an  integer
94       value that is monotonically increasing.
95

NOTES

97       The  CPU  Jitter random number generator MUST NOT be compiled with com‐
98       piler optimizations. A pre-processor check enforces this requirement.
99
100       The random bit stream generated by jent_read_entropy() is NOT processed
101       by  a  cryptographically  secure whitening function. Nonetheless, it is
102       believed that the output can be used as a source for  cryptographically
103       secure key material or other cryptographically sensitive data.
104
105       In addition to use the generated random bit stream directly for crypto‐
106       graphic operations, the output of jent_read_entropy() can be  used  for
107       seeding a deterministic random number generator, or perform a post pro‐
108       cessing with a cryptographically secure whitening function.
109

SEE ALSO

111       http://www.chronox.de provides the design description, the entropy  and
112       statistical analyses as well as a number of test cases.
113
114
115
116                                  2013-05-06                  JITTERENTROPY(3)
Impressum