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