1 /** 2 * \file entropy.h 3 * 4 * \brief Entropy accumulator implementation 5 */ 6 /* 7 * Copyright The Mbed TLS Contributors 8 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 9 */ 10 #ifndef MBEDTLS_ENTROPY_H 11 #define MBEDTLS_ENTROPY_H 12 13 #if !defined(MBEDTLS_CONFIG_FILE) 14 #include "mbedtls/config.h" 15 #else 16 #include MBEDTLS_CONFIG_FILE 17 #endif 18 19 #include <stddef.h> 20 21 #if defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256) 22 #include "mbedtls/sha512.h" 23 #define MBEDTLS_ENTROPY_SHA512_ACCUMULATOR 24 #else 25 #if defined(MBEDTLS_SHA256_C) 26 #define MBEDTLS_ENTROPY_SHA256_ACCUMULATOR 27 #include "mbedtls/sha256.h" 28 #endif 29 #endif 30 31 #if defined(MBEDTLS_THREADING_C) 32 #include "mbedtls/threading.h" 33 #endif 34 35 #if defined(MBEDTLS_HAVEGE_C) 36 #include "mbedtls/havege.h" 37 #endif 38 39 /** Critical entropy source failure. */ 40 #define MBEDTLS_ERR_ENTROPY_SOURCE_FAILED -0x003C 41 /** No more sources can be added. */ 42 #define MBEDTLS_ERR_ENTROPY_MAX_SOURCES -0x003E 43 /** No sources have been added to poll. */ 44 #define MBEDTLS_ERR_ENTROPY_NO_SOURCES_DEFINED -0x0040 45 /** No strong sources have been added to poll. */ 46 #define MBEDTLS_ERR_ENTROPY_NO_STRONG_SOURCE -0x003D 47 /** Read/write error in file. */ 48 #define MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR -0x003F 49 50 /** 51 * \name SECTION: Module settings 52 * 53 * The configuration options you can set for this module are in this section. 54 * Either change them in config.h or define them on the compiler command line. 55 * \{ 56 */ 57 58 #if !defined(MBEDTLS_ENTROPY_MAX_SOURCES) 59 #define MBEDTLS_ENTROPY_MAX_SOURCES 20 /**< Maximum number of sources supported */ 60 #endif 61 62 #if !defined(MBEDTLS_ENTROPY_MAX_GATHER) 63 #define MBEDTLS_ENTROPY_MAX_GATHER 128 /**< Maximum amount requested from entropy sources */ 64 #endif 65 66 /** \} name SECTION: Module settings */ 67 68 #if defined(MBEDTLS_ENTROPY_SHA512_ACCUMULATOR) 69 #define MBEDTLS_ENTROPY_BLOCK_SIZE 64 /**< Block size of entropy accumulator (SHA-512) */ 70 #else 71 #define MBEDTLS_ENTROPY_BLOCK_SIZE 32 /**< Block size of entropy accumulator (SHA-256) */ 72 #endif 73 74 #define MBEDTLS_ENTROPY_MAX_SEED_SIZE 1024 /**< Maximum size of seed we read from seed file */ 75 #define MBEDTLS_ENTROPY_SOURCE_MANUAL MBEDTLS_ENTROPY_MAX_SOURCES 76 77 #define MBEDTLS_ENTROPY_SOURCE_STRONG 1 /**< Entropy source is strong */ 78 #define MBEDTLS_ENTROPY_SOURCE_WEAK 0 /**< Entropy source is weak */ 79 80 #ifdef __cplusplus 81 extern "C" { 82 #endif 83 84 /** 85 * \brief Entropy poll callback pointer 86 * 87 * \param data Callback-specific data pointer 88 * \param output Data to fill 89 * \param len Maximum size to provide 90 * \param olen The actual amount of bytes put into the buffer (Can be 0) 91 * 92 * \return 0 if no critical failures occurred, 93 * MBEDTLS_ERR_ENTROPY_SOURCE_FAILED otherwise 94 */ 95 typedef int (*mbedtls_entropy_f_source_ptr)(void *data, unsigned char *output, size_t len, 96 size_t *olen); 97 98 /** 99 * \brief Entropy source state 100 */ 101 typedef struct mbedtls_entropy_source_state { 102 mbedtls_entropy_f_source_ptr f_source; /**< The entropy source callback */ 103 void *p_source; /**< The callback data pointer */ 104 size_t size; /**< Amount received in bytes */ 105 size_t threshold; /**< Minimum bytes required before release */ 106 int strong; /**< Is the source strong? */ 107 } 108 mbedtls_entropy_source_state; 109 110 /** 111 * \brief Entropy context structure 112 */ 113 typedef struct mbedtls_entropy_context { 114 int accumulator_started; /* 0 after init. 115 * 1 after the first update. 116 * -1 after free. */ 117 #if defined(MBEDTLS_ENTROPY_SHA512_ACCUMULATOR) 118 mbedtls_sha512_context accumulator; 119 #elif defined(MBEDTLS_ENTROPY_SHA256_ACCUMULATOR) 120 mbedtls_sha256_context accumulator; 121 #endif 122 int source_count; /* Number of entries used in source. */ 123 mbedtls_entropy_source_state source[MBEDTLS_ENTROPY_MAX_SOURCES]; 124 #if defined(MBEDTLS_HAVEGE_C) 125 mbedtls_havege_state havege_data; 126 #endif 127 #if defined(MBEDTLS_THREADING_C) 128 mbedtls_threading_mutex_t mutex; /*!< mutex */ 129 #endif 130 #if defined(MBEDTLS_ENTROPY_NV_SEED) 131 int initial_entropy_run; 132 #endif 133 } 134 mbedtls_entropy_context; 135 136 /** 137 * \brief Initialize the context 138 * 139 * \param ctx Entropy context to initialize 140 */ 141 void mbedtls_entropy_init(mbedtls_entropy_context *ctx); 142 143 /** 144 * \brief Free the data in the context 145 * 146 * \param ctx Entropy context to free 147 */ 148 void mbedtls_entropy_free(mbedtls_entropy_context *ctx); 149 150 /** 151 * \brief Adds an entropy source to poll 152 * (Thread-safe if MBEDTLS_THREADING_C is enabled) 153 * 154 * \param ctx Entropy context 155 * \param f_source Entropy function 156 * \param p_source Function data 157 * \param threshold Minimum required from source before entropy is released 158 * ( with mbedtls_entropy_func() ) (in bytes) 159 * \param strong MBEDTLS_ENTROPY_SOURCE_STRONG or 160 * MBEDTLS_ENTROPY_SOURCE_WEAK. 161 * At least one strong source needs to be added. 162 * Weaker sources (such as the cycle counter) can be used as 163 * a complement. 164 * 165 * \return 0 if successful or MBEDTLS_ERR_ENTROPY_MAX_SOURCES 166 */ 167 int mbedtls_entropy_add_source(mbedtls_entropy_context *ctx, 168 mbedtls_entropy_f_source_ptr f_source, void *p_source, 169 size_t threshold, int strong); 170 171 /** 172 * \brief Trigger an extra gather poll for the accumulator 173 * (Thread-safe if MBEDTLS_THREADING_C is enabled) 174 * 175 * \param ctx Entropy context 176 * 177 * \return 0 if successful, or MBEDTLS_ERR_ENTROPY_SOURCE_FAILED 178 */ 179 int mbedtls_entropy_gather(mbedtls_entropy_context *ctx); 180 181 /** 182 * \brief Retrieve entropy from the accumulator 183 * (Maximum length: MBEDTLS_ENTROPY_BLOCK_SIZE) 184 * (Thread-safe if MBEDTLS_THREADING_C is enabled) 185 * 186 * \param data Entropy context 187 * \param output Buffer to fill 188 * \param len Number of bytes desired, must be at most MBEDTLS_ENTROPY_BLOCK_SIZE 189 * 190 * \return 0 if successful, or MBEDTLS_ERR_ENTROPY_SOURCE_FAILED 191 */ 192 int mbedtls_entropy_func(void *data, unsigned char *output, size_t len); 193 194 /** 195 * \brief Add data to the accumulator manually 196 * (Thread-safe if MBEDTLS_THREADING_C is enabled) 197 * 198 * \param ctx Entropy context 199 * \param data Data to add 200 * \param len Length of data 201 * 202 * \return 0 if successful 203 */ 204 int mbedtls_entropy_update_manual(mbedtls_entropy_context *ctx, 205 const unsigned char *data, size_t len); 206 207 #if defined(MBEDTLS_ENTROPY_NV_SEED) 208 /** 209 * \brief Trigger an update of the seed file in NV by using the 210 * current entropy pool. 211 * 212 * \param ctx Entropy context 213 * 214 * \return 0 if successful 215 */ 216 int mbedtls_entropy_update_nv_seed(mbedtls_entropy_context *ctx); 217 #endif /* MBEDTLS_ENTROPY_NV_SEED */ 218 219 #if defined(MBEDTLS_FS_IO) 220 /** 221 * \brief Write a seed file 222 * 223 * \param ctx Entropy context 224 * \param path Name of the file 225 * 226 * \return 0 if successful, 227 * MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR on file error, or 228 * MBEDTLS_ERR_ENTROPY_SOURCE_FAILED 229 */ 230 int mbedtls_entropy_write_seed_file(mbedtls_entropy_context *ctx, const char *path); 231 232 /** 233 * \brief Read and update a seed file. Seed is added to this 234 * instance. No more than MBEDTLS_ENTROPY_MAX_SEED_SIZE bytes are 235 * read from the seed file. The rest is ignored. 236 * 237 * \param ctx Entropy context 238 * \param path Name of the file 239 * 240 * \return 0 if successful, 241 * MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR on file error, 242 * MBEDTLS_ERR_ENTROPY_SOURCE_FAILED 243 */ 244 int mbedtls_entropy_update_seed_file(mbedtls_entropy_context *ctx, const char *path); 245 #endif /* MBEDTLS_FS_IO */ 246 247 #if defined(MBEDTLS_SELF_TEST) 248 /** 249 * \brief Checkup routine 250 * 251 * This module self-test also calls the entropy self-test, 252 * mbedtls_entropy_source_self_test(); 253 * 254 * \return 0 if successful, or 1 if a test failed 255 */ 256 int mbedtls_entropy_self_test(int verbose); 257 258 #if defined(MBEDTLS_ENTROPY_HARDWARE_ALT) 259 /** 260 * \brief Checkup routine 261 * 262 * Verifies the integrity of the hardware entropy source 263 * provided by the function 'mbedtls_hardware_poll()'. 264 * 265 * Note this is the only hardware entropy source that is known 266 * at link time, and other entropy sources configured 267 * dynamically at runtime by the function 268 * mbedtls_entropy_add_source() will not be tested. 269 * 270 * \return 0 if successful, or 1 if a test failed 271 */ 272 int mbedtls_entropy_source_self_test(int verbose); 273 #endif /* MBEDTLS_ENTROPY_HARDWARE_ALT */ 274 #endif /* MBEDTLS_SELF_TEST */ 275 276 #ifdef __cplusplus 277 } 278 #endif 279 280 #endif /* entropy.h */ 281