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