1JITTERENTROPY(3) Library Functions Manual JITTERENTROPY(3)
2
6 jitterentropy - CPU Jitter Random Number Generator
7
9 #include <jitterentropy.h>
10 int jent_entropy_init(void);
12 struct rand_data *jent_entropy_collector_alloc(unsigned int osr,
14 unsigned int flags);
15 void jent_entropy_collector_free(struct rand_data *entropy_collector);
17 ssize_t jent_read_entropy(struct rand_data *entropy_collector,
19 char *data, size_t len);
20 unsigned int jent_version(void);
22
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 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 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 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 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 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 jent_entropy_collector_free() zeroizes and frees the given CPU Jitter
71 entropy collector instance.
72 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 jent_version() returns the version number of the library as an integer
94 value that is monotonically increasing.
95
97 The CPU Jitter random number generator MUST NOT be compiled with com‐
98 piler optimizations. A pre-processor check enforces this requirement.
99 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 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
111 http://www.chronox.de provides the design description, the entropy and
112 statistical analyses as well as a number of test cases.
113 2013-05-06 JITTERENTROPY(3)