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 JENT_DISABLE_STIR disables the use of the stirring function with the
60 newly generated random number before it is given to the caller. The
61 stirring function mixes the random numbers a bit as a precautionary
62 measure. This function should be enabled when using the output of the
63 CPU Jitter RNG directly. On the other hand, when using the output to
64 seed a deterministic RNG, the mixing function is not needed as the
65 deterministic RNG acts already as cryptographic whitening function to
66 the data produced by the CPU Jitter RNG. The stirring function is
67 enabled per default. The Von-Neumann unbias operation can be disabled
68 using the JENT_DISABLE_UNBIAS flag. The Von-Neumann unbias operation is
69 enabled per default. Per default, the CPU Jitter entropy collection
70 process performs memory accesses as a source of entropy. These memory
71 accesses are mathematically modelled to contain entropy. In addition,
72 the CPU state itself delivers entropy which, however, depends on the
73 CPU complexity. The memory size is defined with the JENT_MEMORY_SIZE
74 macro. If the system is constrained with memory, the flag JENT_DIS‐
75 ABLE_MEMORY_ACCESS disables the allocation of that memory and therefore
76 memory accesses. But that also implies that the entropy collection
77 process only relies on the complexity of the CPU. Note, if somebody
78 knows all details of that CPU complexity, that person may potentially
79 reduce the entropy delivered by the CPU complexity. If that person can
80 push the generated entropy below a threshold, the CPU Jitter random
81 number generator starts overestimating entropy from the noise source.
82 Thus, disabling memory accesses and relying only on the CPU complexity
83 should only be done if you really know what you are doing.
84 jent_entropy_collector_free() zeroizes and frees the given CPU Jitter
86 entropy collector instance.
87 jent_read_entropy() generates a random bit stream and returns it to the
89 caller. entropy_collector is the CPU Jitter entropy collector instance
90 which shall be used to obtain random numbers. data is the destination
91 memory location where the random bit stream is written to. The memory
92 must have already been allocated by the caller. len is a length value
93 provided by the caller indicating the number of bytes the CPU Jitter
94 Random Number Generator shall generate. The caller can provide any
95 value greater than 0. The caller must ensure that data is at least als
96 big as len indicates. The function returns the number of bytes gener‐
97 ated when the request is successfully completed. The return code of -1
98 indicates the FIPS 140-2 self-test failed, if the FIPS 140-2 mode is
99 activated. In this case the code will not generate any entropy any more
100 for the given entropy collector. The only way to reset this condition
101 is to deallocate the entropy collector and create a new instance. If
102 the function returns the error code -2 then the caller handed in a non-
103 initialized (i.e. NULL value) for the entropy collector.
104 jent_version() returns the version number of the library as an integer
106 value that is monotonically increasing.
107
109 The CPU Jitter random number generator MUST NOT be compiled with com‐
110 piler optimizations. A pre-processor check enforces this requirement.
111 The random bit stream generated by jent_read_entropy() is NOT processed
113 by a cryptographically secure whitening function. Nonetheless, it is
114 believed that the output can be used as a source for cryptographically
115 secure key material or other cryptographically sensitive data.
116 In addition to use the generated random bit stream directly for crypto‐
118 graphic operations, the output of jent_read_entropy() can be used for
119 seeding a deterministic random number generator, or perform a post pro‐
120 cessing with a cryptographically secure whitening function.
121
123 http://www.chronox.de provides the design description, the entropy and
124 statistical analyses as well as a number of test cases.
125 2013-05-06 JITTERENTROPY(3)