random: Update jitterentropy to 2.1.0.
[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 _JITTERENTROPY_H
43 #define _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 /* The entropy pool */
52 struct rand_data
53 {
54         /* all data values that are vital to maintain the security
55          * of the RNG are marked as SENSITIVE. A user must not
56          * access that information while the RNG executes its loops to
57          * calculate the next random value. */
58         uint64_t data;          /* SENSITIVE Actual random number */
59         uint64_t old_data;      /* SENSITIVE Previous random number */
60         uint64_t prev_time;     /* SENSITIVE Previous time stamp */
61 #define DATA_SIZE_BITS ((sizeof(uint64_t)) * 8)
62         uint64_t last_delta;    /* SENSITIVE stuck test */
63         int64_t last_delta2;    /* SENSITIVE stuck test */
64         unsigned int osr;       /* Oversample rate */
65         int fips_enabled;       /* FIPS enabled? */
66         unsigned int stir:1;            /* Post-processing stirring */
67         unsigned int disable_unbias:1;  /* Deactivate Von-Neuman unbias */
68 #define JENT_MEMORY_BLOCKS 64
69 #define JENT_MEMORY_BLOCKSIZE 32
70 #define JENT_MEMORY_ACCESSLOOPS 128
71 #define JENT_MEMORY_SIZE (JENT_MEMORY_BLOCKS*JENT_MEMORY_BLOCKSIZE)
72         unsigned char *mem;     /* Memory access location with size of
73                                  * memblocks * memblocksize */
74         unsigned int memlocation; /* Pointer to byte in *mem */
75         unsigned int memblocks; /* Number of memory blocks in *mem */
76         unsigned int memblocksize; /* Size of one memory block in bytes */
77         unsigned int memaccessloops; /* Number of memory accesses per random
78                                       * bit generation */
79 };
80
81 /* Flags that can be used to initialize the RNG */
82 #define JENT_DISABLE_STIR (1<<0) /* Disable stirring the entropy pool */
83 #define JENT_DISABLE_UNBIAS (1<<1) /* Disable the Von-Neuman Unbiaser */
84 #define JENT_DISABLE_MEMORY_ACCESS (1<<2) /* Disable memory access for more
85                                              entropy, saves MEMORY_SIZE RAM for
86                                              entropy collector */
87
88 /* -- BEGIN Main interface functions -- */
89
90 #ifndef JENT_STUCK_INIT_THRES
91 /*
92  * Per default, not more than 90% of all measurements during initialization
93  * are allowed to be stuck.
94  *
95  * It is allowed to change this value as required for the intended environment.
96  */
97 #define JENT_STUCK_INIT_THRES(x) (x/10 * 9)
98 #endif
99
100 #ifdef JENT_PRIVATE_COMPILE
101 # define JENT_PRIVATE_STATIC static
102 #else /* JENT_PRIVATE_COMPILE */
103 # define JENT_PRIVATE_STATIC
104 #endif
105
106 /* Number of low bits of the time value that we want to consider */
107 /* get raw entropy */
108 JENT_PRIVATE_STATIC
109 ssize_t jent_read_entropy(struct rand_data *ec, char *data, size_t len);
110 /* initialize an instance of the entropy collector */
111 JENT_PRIVATE_STATIC
112 struct rand_data *jent_entropy_collector_alloc(unsigned int osr,
113                                                unsigned int flags);
114 /* clearing of entropy collector */
115 JENT_PRIVATE_STATIC
116 void jent_entropy_collector_free(struct rand_data *entropy_collector);
117
118 /* initialization of entropy collector */
119 JENT_PRIVATE_STATIC
120 int jent_entropy_init(void);
121
122 /* return version number of core library */
123 JENT_PRIVATE_STATIC
124 unsigned int jent_version(void);
125
126 /* -- END of Main interface functions -- */
127
128 /* -- BEGIN error codes for init function -- */
129 #define ENOTIME         1 /* Timer service not available */
130 #define ECOARSETIME     2 /* Timer too coarse for RNG */
131 #define ENOMONOTONIC    3 /* Timer is not monotonic increasing */
132 #define EMINVARIATION   4 /* Timer variations too small for RNG */
133 #define EVARVAR         5 /* Timer does not produce variations of variations
134                              (2nd derivation of time is zero) */
135 #define EMINVARVAR      6 /* Timer variations of variations is too small */
136 #define EPROGERR        7 /* Programming error */
137 #define ESTUCK          8 /* Too many stuck results during init. */
138
139 /* -- BEGIN statistical test functions only complied with CONFIG_CRYPTO_CPU_JITTERENTROPY_STAT -- */
140
141 #ifdef CONFIG_CRYPTO_CPU_JITTERENTROPY_STAT
142 JENT_PRIVATE_STATIC
143 uint64_t jent_lfsr_var_stat(struct rand_data *ec, unsigned int min);
144 #endif /* CONFIG_CRYPTO_CPU_JITTERENTROPY_STAT */
145
146 /* -- END of statistical test function -- */
147
148 #endif /* _JITTERENTROPY_H */