random: Changes to original Jitter RNG implementation
[libgcrypt.git] / random / jitterentropy.h
1 /*
2  * Non-physical true random number generator based on timing jitter.
3  *
4  * Copyright Stephan Mueller <smueller@chronox.de>, 2014
5  *
6  * License
7  * =======
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions
11  * are met:
12  * 1. Redistributions of source code must retain the above copyright
13  *    notice, and the entire permission notice in its entirety,
14  *    including the disclaimer of warranties.
15  * 2. Redistributions in binary form must reproduce the above copyright
16  *    notice, this list of conditions and the following disclaimer in the
17  *    documentation and/or other materials provided with the distribution.
18  * 3. The name of the author may not be used to endorse or promote
19  *    products derived from this software without specific prior
20  *    written permission.
21  *
22  * ALTERNATIVELY, this product may be distributed under the terms of
23  * the GNU General Public License, in which case the provisions of the GPL are
24  * required INSTEAD OF the above restrictions.  (This clause is
25  * necessary due to a potential bad interaction between the GPL and
26  * the restrictions contained in a BSD-style copyright.)
27  *
28  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
29  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
30  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ALL OF
31  * WHICH ARE HEREBY DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE
32  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
33  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
34  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
35  * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
36  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
37  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
38  * USE OF THIS SOFTWARE, EVEN IF NOT ADVISED OF THE POSSIBILITY OF SUCH
39  * DAMAGE.
40  */
41
42 #ifndef GCRYPT_JITTERENTROPY_H
43 #define GCRYPT_JITTERENTROPY_H
44
45 /* #ifdef __KERNEL__ */
46 /* #include "jitterentropy-base-kernel.h" */
47 /* #else */
48 /* #include "jitterentropy-base-user.h" */
49 /* #endif /\* __KERNEL__ *\/ */
50
51 /* Statistical data from the entropy source */
52 struct entropy_stat {
53         unsigned int bitslot[64];       /* Counter for the bits set per bit
54                                            position in ->data */
55         unsigned int bitvar[64];        /* Counter for the number of bit
56                                            variations per bit position in
57                                            ->data */
58         unsigned int enable_bit_test;   /* enable bit test
59                                            this flag is vital for the accuracy
60                                            of the statistic tests: when we
61                                            do the time measurements, we want
62                                            the observed entropy collection
63                                            loop executed as fast as the
64                                            unmeasured loop, i.e. without
65                                            the bit statistic logic; on the
66                                            other hand, the bit statistics
67                                            test is not interested in exact
68                                            timing */
69         u64 collection_begin;           /* timer for beginning of one
70                                            entropy collection round */
71         u64 collection_end;             /* timer for end of one round */
72         u64 old_delta;                  /* Time delta of previous round to
73                                            calculate delta of deltas */
74         unsigned int setbits;           /* see _jent_calc_statistic */
75         unsigned int varbits;           /* see _jent_calc_statistic */
76         unsigned int obsbits;           /* see _jent_calc_statistic */
77         unsigned int collection_loop_cnt;       /* Collection loop counter */
78 };
79
80 /* The entropy pool */
81 struct rand_data
82 {
83         /* all data values that are vital to maintain the security
84          * of the RNG are marked as SENSITIVE. A user must not
85          * access that information while the RNG executes its loops to
86          * calculate the next random value. */
87         u64 data;               /* SENSITIVE Actual random number */
88         u64 prev_time;          /* SENSITIVE Previous time stamp */
89 #define DATA_SIZE_BITS ((sizeof(u64)) * 8)
90         u64 last_delta;         /* SENSITIVE stuck test */
91         int64_t last_delta2;    /* SENSITIVE stuck test */
92         unsigned int osr;       /* Oversample rate */
93         unsigned int stir:1;            /* Post-processing stirring */
94         unsigned int disable_unbias:1;  /* Deactivate Von-Neuman unbias */
95 #define JENT_MEMORY_BLOCKS 64
96 #define JENT_MEMORY_BLOCKSIZE 32
97 #define JENT_MEMORY_ACCESSLOOPS 128
98 #define JENT_MEMORY_SIZE (JENT_MEMORY_BLOCKS*JENT_MEMORY_BLOCKSIZE)
99         unsigned char *mem;     /* Memory access location with size of
100                                  * memblocks * memblocksize */
101         unsigned int memlocation; /* Pointer to byte in *mem */
102         unsigned int memblocks; /* Number of memory blocks in *mem */
103         unsigned int memblocksize; /* Size of one memory block in bytes */
104         unsigned int memaccessloops; /* Number of memory accesses per random
105                                       * bit generation */
106 #ifdef CONFIG_CRYPTO_CPU_JITTERENTROPY_STAT
107         struct entropy_stat entropy_stat;
108 #endif
109 };
110
111 /* Flags that can be used to initialize the RNG */
112 #define JENT_DISABLE_STIR (1<<0) /* Disable stirring the entropy pool */
113 #define JENT_DISABLE_UNBIAS (1<<1) /* Disable the Von-Neuman Unbiaser */
114 #define JENT_DISABLE_MEMORY_ACCESS (1<<2) /* Disable memory access for more
115                                              entropy, saves MEMORY_SIZE RAM for
116                                              entropy collector */
117
118 #define DRIVER_NAME     "jitterentropy"
119
120 /* -- BEGIN Main interface functions -- */
121
122 /* Number of low bits of the time value that we want to consider */
123 /* get raw entropy */
124 static int jent_read_entropy (struct rand_data *ec,
125                               char *data, size_t len);
126
127 /* initialize an instance of the entropy collector */
128 static struct rand_data *jent_entropy_collector_alloc (unsigned int osr,
129                                                          unsigned int flags);
130
131 /* clearing of entropy collector */
132 static void jent_entropy_collector_free (struct rand_data *ent_coll);
133
134 /* initialization of entropy collector */
135 static int jent_entropy_init (void);
136
137 /* return version number of core library */
138 /* unsigned int jent_version(void); */
139
140 /* -- END of Main interface functions -- */
141
142 /* -- BEGIN error codes for init function -- */
143 /* FIXME!!! */
144 #define ENOTIME         1 /* Timer service not available */
145 #define ECOARSETIME     2 /* Timer too coarse for RNG */
146 #define ENOMONOTONIC    3 /* Timer is not monotonic increasing */
147 #define EMINVARIATION   4 /* Timer variations too small for RNG */
148 #define EVARVAR         5 /* Timer does not produce variations of variations
149                              (2nd derivation of time is zero) */
150 #define EMINVARVAR      6 /* Timer variations of variations is too small */
151 #define EPROGERR        7 /* Programming error */
152
153 /* -- BEGIN statistical test functions only complied with CONFIG_CRYPTO_CPU_JITTERENTROPY_STAT -- */
154
155 #ifdef CONFIG_CRYPTO_CPU_JITTERENTROPY_STAT
156
157 static void jent_init_statistic(struct rand_data *entropy_collector);
158 static void jent_calc_statistic(struct rand_data *entropy_collector,
159                           struct entropy_stat *stat, unsigned int loop_cnt);
160 static void jent_bit_count (struct rand_data *entropy_collector, u64 prev_data);
161
162 static void jent_gen_entropy_stat (struct rand_data *entropy_collector,
163                                    struct entropy_stat *stat);
164 static void jent_lfsr_time_stat(struct rand_data *ec, u64 *fold, u64 *loop_cnt);
165 static u64 jent_lfsr_var_stat(struct rand_data *ec, unsigned int min);
166
167 #else /* CONFIG_CRYPTO_CPU_JITTERENTROPY_STAT */
168
169 # define jent_init_statistic(x)       do { } while (0)
170 # define jent_calc_statistic(x, y, z) do { } while (0)
171 # define jent_bit_count(x,y)          do { (void)(y); } while (0)
172
173 #endif /* CONFIG_CRYPTO_CPU_JITTERENTROPY_STAT */
174
175 /* -- END of statistical test function -- */
176
177 #endif /* GCRYPT_JITTERENTROPY_H */