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 * Modifications by the Fuchsia Authors, 2017 42 * ======= 43 * 44 * - Remove references to jitterentropy-base-{kernel,user}.h. 45 * - Add __BEGIN/END_CDECLS. 46 * - Add #include lines for required system libraries. 47 * - Remove CONFIG_CRYPTO_CPU_JITTERENTROPY_STAT flag. 48 * - Add jent_entropy_collector_init declaration. 49 * - Moved comment for jent_lfsr_var_stat from jitterentropy-base.c to here. 50 */ 51 52 #ifndef _JITTERENTROPY_H 53 #define _JITTERENTROPY_H 54 55 #include <zircon/compiler.h> 56 #include <stdbool.h> 57 #include <stdint.h> 58 #include <sys/types.h> 59 60 __BEGIN_CDECLS; 61 62 /* The entropy pool */ 63 struct rand_data 64 { 65 /* all data values that are vital to maintain the security 66 * of the RNG are marked as SENSITIVE. A user must not 67 * access that information while the RNG executes its loops to 68 * calculate the next random value. */ 69 uint64_t data; /* SENSITIVE Actual random number */ 70 uint64_t old_data; /* SENSITIVE Previous random number */ 71 uint64_t prev_time; /* SENSITIVE Previous time stamp */ 72 #define DATA_SIZE_BITS ((sizeof(uint64_t)) * 8) 73 uint64_t last_delta; /* SENSITIVE stuck test */ 74 int64_t last_delta2; /* SENSITIVE stuck test */ 75 unsigned int osr; /* Oversample rate */ 76 int fips_enabled; /* FIPS enabled? */ 77 unsigned int stir:1; /* Post-processing stirring */ 78 unsigned int disable_unbias:1; /* Deactivate Von-Neuman unbias */ 79 #define JENT_MEMORY_BLOCKS 64 80 #define JENT_MEMORY_BLOCKSIZE 32 81 #define JENT_MEMORY_ACCESSLOOPS 128 82 #define JENT_MEMORY_SIZE (JENT_MEMORY_BLOCKS*JENT_MEMORY_BLOCKSIZE) 83 unsigned char *mem; /* Memory access location with size of 84 * memblocks * memblocksize */ 85 unsigned int memlocation; /* Pointer to byte in *mem */ 86 unsigned int memblocks; /* Number of memory blocks in *mem */ 87 unsigned int memblocksize; /* Size of one memory block in bytes */ 88 unsigned int memaccessloops; /* Number of memory accesses per random 89 * bit generation */ 90 }; 91 92 /* Flags that can be used to initialize the RNG */ 93 #define JENT_DISABLE_STIR (1<<0) /* Disable stirring the entropy pool */ 94 #define JENT_DISABLE_UNBIAS (1<<1) /* Disable the Von-Neuman Unbiaser */ 95 #define JENT_DISABLE_MEMORY_ACCESS (1<<2) /* Disable memory access for more 96 entropy, saves MEMORY_SIZE RAM for 97 entropy collector */ 98 99 /* -- BEGIN Main interface functions -- */ 100 101 #ifndef JENT_STUCK_INIT_THRES 102 /* 103 * Per default, not more than 90% of all measurements during initialization 104 * are allowed to be stuck. 105 * 106 * It is allowed to change this value as required for the intended environment. 107 */ 108 #define JENT_STUCK_INIT_THRES(x) (x/10 * 9) 109 #endif 110 111 #ifdef JENT_PRIVATE_COMPILE 112 # define JENT_PRIVATE_STATIC static 113 #else /* JENT_PRIVATE_COMPILE */ 114 # define JENT_PRIVATE_STATIC 115 #endif 116 117 /* Number of low bits of the time value that we want to consider */ 118 /* get raw entropy */ 119 JENT_PRIVATE_STATIC 120 ssize_t jent_read_entropy(struct rand_data *ec, char *data, size_t len); 121 /* initialize an instance of the entropy collector */ 122 JENT_PRIVATE_STATIC 123 struct rand_data *jent_entropy_collector_alloc(unsigned int osr, 124 unsigned int flags); 125 /* clearing of entropy collector */ 126 JENT_PRIVATE_STATIC 127 void jent_entropy_collector_free(struct rand_data *entropy_collector); 128 129 /* initialization of entropy collector */ 130 JENT_PRIVATE_STATIC 131 int jent_entropy_init(void); 132 133 /* return version number of core library */ 134 JENT_PRIVATE_STATIC 135 unsigned int jent_version(void); 136 137 /* -- END of Main interface functions -- */ 138 139 /* -- BEGIN error codes for init function -- */ 140 #define ENOTIME 1 /* Timer service not available */ 141 #define ECOARSETIME 2 /* Timer too coarse for RNG */ 142 #define ENOMONOTONIC 3 /* Timer is not monotonic increasing */ 143 #define EMINVARIATION 4 /* Timer variations too small for RNG */ 144 #define EVARVAR 5 /* Timer does not produce variations of variations 145 (2nd derivation of time is zero) */ 146 #define EMINVARVAR 6 /* Timer variations of variations is too small */ 147 #define EPROGERR 7 /* Programming error */ 148 #define ESTUCK 8 /* Too many stuck results during init. */ 149 150 /* -- BEGIN statistical test functions only complied with CONFIG_CRYPTO_CPU_JITTERENTROPY_STAT -- */ 151 152 /* 153 * Statistical test: return the time duration for the folding operation. If 154 * lfsr_loops_override/mem_loops_override is non-zero, perform the given number 155 * of LFSR/memaccess ops. Otherwise, allow the loop count shuffling to define 156 * the number of LFSR/memaccess ops. 157 */ 158 JENT_PRIVATE_STATIC 159 uint64_t jent_lfsr_var_stat(struct rand_data *ec, 160 unsigned int lfsr_loops_override, 161 unsigned int mem_loops_override); 162 163 /* -- END of statistical test function -- */ 164 165 /* -- BEGIN Zircon interface -- */ 166 167 /* Initialize an entropy collector using already allocated memory. This function 168 * is to jent_entropy_collector_alloc as placement new is to regular new in C++. 169 * 170 * |ec| is the entropy collector to initialize. |mem| points to a block of 171 * |mem_size| bytes used for memory access loops (to generate CPU instruction 172 * time variation). 173 * 174 * The memory will be logically divided into |mem_block_count| blocks of size 175 * |mem_block_size|; it is an error if the product of these two values is larger 176 * than |mem_size|. Ideally, the mem_block_* parameters should be configured for 177 * each target, or at least each architecture. The entropy collector will 178 * perform at least |mem_loops| memory access loops to generate variations. 179 * 180 * The |stir| flag controls whether to stir a deterministic constant into the 181 * entropy pool, which does not destroy entropy but may whiten it. 182 */ 183 void jent_entropy_collector_init( 184 struct rand_data* ec, uint8_t* mem, size_t mem_size, 185 unsigned int mem_block_size, unsigned int mem_block_count, 186 unsigned int mem_loops, bool stir); 187 188 /* -- END of Zircon interface -- */ 189 190 __END_CDECLS; 191 192 #endif /* _JITTERENTROPY_H */ 193