1 /** 2 * \file hmac_drbg.h 3 * 4 * \brief The HMAC_DRBG pseudorandom generator. 5 * 6 * This module implements the HMAC_DRBG pseudorandom generator described 7 * in <em>NIST SP 800-90A: Recommendation for Random Number Generation Using 8 * Deterministic Random Bit Generators</em>. 9 */ 10 /* 11 * Copyright The Mbed TLS Contributors 12 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 13 */ 14 #ifndef MBEDTLS_HMAC_DRBG_H 15 #define MBEDTLS_HMAC_DRBG_H 16 17 #if !defined(MBEDTLS_CONFIG_FILE) 18 #include "mbedtls/config.h" 19 #else 20 #include MBEDTLS_CONFIG_FILE 21 #endif 22 23 #include "mbedtls/md.h" 24 25 #if defined(MBEDTLS_THREADING_C) 26 #include "mbedtls/threading.h" 27 #endif 28 29 /* 30 * Error codes 31 */ 32 /** Too many random requested in single call. */ 33 #define MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG -0x0003 34 /** Input too large (Entropy + additional). */ 35 #define MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG -0x0005 36 /** Read/write error in file. */ 37 #define MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR -0x0007 38 /** The entropy source failed. */ 39 #define MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED -0x0009 40 41 /** 42 * \name SECTION: Module settings 43 * 44 * The configuration options you can set for this module are in this section. 45 * Either change them in config.h or define them on the compiler command line. 46 * \{ 47 */ 48 49 #if !defined(MBEDTLS_HMAC_DRBG_RESEED_INTERVAL) 50 #define MBEDTLS_HMAC_DRBG_RESEED_INTERVAL 10000 /**< Interval before reseed is performed by default */ 51 #endif 52 53 #if !defined(MBEDTLS_HMAC_DRBG_MAX_INPUT) 54 #define MBEDTLS_HMAC_DRBG_MAX_INPUT 256 /**< Maximum number of additional input bytes */ 55 #endif 56 57 #if !defined(MBEDTLS_HMAC_DRBG_MAX_REQUEST) 58 #define MBEDTLS_HMAC_DRBG_MAX_REQUEST 1024 /**< Maximum number of requested bytes per call */ 59 #endif 60 61 #if !defined(MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT) 62 #define MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT 384 /**< Maximum size of (re)seed buffer */ 63 #endif 64 65 /** \} name SECTION: Module settings */ 66 67 #define MBEDTLS_HMAC_DRBG_PR_OFF 0 /**< No prediction resistance */ 68 #define MBEDTLS_HMAC_DRBG_PR_ON 1 /**< Prediction resistance enabled */ 69 70 #ifdef __cplusplus 71 extern "C" { 72 #endif 73 74 /** 75 * HMAC_DRBG context. 76 */ 77 typedef struct mbedtls_hmac_drbg_context { 78 /* Working state: the key K is not stored explicitly, 79 * but is implied by the HMAC context */ 80 mbedtls_md_context_t md_ctx; /*!< HMAC context (inc. K) */ 81 unsigned char V[MBEDTLS_MD_MAX_SIZE]; /*!< V in the spec */ 82 int reseed_counter; /*!< reseed counter */ 83 84 /* Administrative state */ 85 size_t entropy_len; /*!< entropy bytes grabbed on each (re)seed */ 86 int prediction_resistance; /*!< enable prediction resistance (Automatic 87 reseed before every random generation) */ 88 int reseed_interval; /*!< reseed interval */ 89 90 /* Callbacks */ 91 int (*f_entropy)(void *, unsigned char *, size_t); /*!< entropy function */ 92 void *p_entropy; /*!< context for the entropy function */ 93 94 #if defined(MBEDTLS_THREADING_C) 95 /* Invariant: the mutex is initialized if and only if 96 * md_ctx->md_info != NULL. This means that the mutex is initialized 97 * during the initial seeding in mbedtls_hmac_drbg_seed() or 98 * mbedtls_hmac_drbg_seed_buf() and freed in mbedtls_ctr_drbg_free(). 99 * 100 * Note that this invariant may change without notice. Do not rely on it 101 * and do not access the mutex directly in application code. 102 */ 103 mbedtls_threading_mutex_t mutex; 104 #endif 105 } mbedtls_hmac_drbg_context; 106 107 /** 108 * \brief HMAC_DRBG context initialization. 109 * 110 * This function makes the context ready for mbedtls_hmac_drbg_seed(), 111 * mbedtls_hmac_drbg_seed_buf() or mbedtls_hmac_drbg_free(). 112 * 113 * \note The reseed interval is #MBEDTLS_HMAC_DRBG_RESEED_INTERVAL 114 * by default. Override this value by calling 115 * mbedtls_hmac_drbg_set_reseed_interval(). 116 * 117 * \param ctx HMAC_DRBG context to be initialized. 118 */ 119 void mbedtls_hmac_drbg_init(mbedtls_hmac_drbg_context *ctx); 120 121 /** 122 * \brief HMAC_DRBG initial seeding. 123 * 124 * Set the initial seed and set up the entropy source for future reseeds. 125 * 126 * A typical choice for the \p f_entropy and \p p_entropy parameters is 127 * to use the entropy module: 128 * - \p f_entropy is mbedtls_entropy_func(); 129 * - \p p_entropy is an instance of ::mbedtls_entropy_context initialized 130 * with mbedtls_entropy_init() (which registers the platform's default 131 * entropy sources). 132 * 133 * You can provide a personalization string in addition to the 134 * entropy source, to make this instantiation as unique as possible. 135 * 136 * \note By default, the security strength as defined by NIST is: 137 * - 128 bits if \p md_info is SHA-1; 138 * - 192 bits if \p md_info is SHA-224; 139 * - 256 bits if \p md_info is SHA-256, SHA-384 or SHA-512. 140 * Note that SHA-256 is just as efficient as SHA-224. 141 * The security strength can be reduced if a smaller 142 * entropy length is set with 143 * mbedtls_hmac_drbg_set_entropy_len(). 144 * 145 * \note The default entropy length is the security strength 146 * (converted from bits to bytes). You can override 147 * it by calling mbedtls_hmac_drbg_set_entropy_len(). 148 * 149 * \note During the initial seeding, this function calls 150 * the entropy source to obtain a nonce 151 * whose length is half the entropy length. 152 */ 153 #if defined(MBEDTLS_THREADING_C) 154 /** 155 * \note When Mbed TLS is built with threading support, 156 * after this function returns successfully, 157 * it is safe to call mbedtls_hmac_drbg_random() 158 * from multiple threads. Other operations, including 159 * reseeding, are not thread-safe. 160 */ 161 #endif /* MBEDTLS_THREADING_C */ 162 /** 163 * \param ctx HMAC_DRBG context to be seeded. 164 * \param md_info MD algorithm to use for HMAC_DRBG. 165 * \param f_entropy The entropy callback, taking as arguments the 166 * \p p_entropy context, the buffer to fill, and the 167 * length of the buffer. 168 * \p f_entropy is always called with a length that is 169 * less than or equal to the entropy length. 170 * \param p_entropy The entropy context to pass to \p f_entropy. 171 * \param custom The personalization string. 172 * This can be \c NULL, in which case the personalization 173 * string is empty regardless of the value of \p len. 174 * \param len The length of the personalization string. 175 * This must be at most #MBEDTLS_HMAC_DRBG_MAX_INPUT 176 * and also at most 177 * #MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT - \c entropy_len * 3 / 2 178 * where \c entropy_len is the entropy length 179 * described above. 180 * 181 * \return \c 0 if successful. 182 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info is 183 * invalid. 184 * \return #MBEDTLS_ERR_MD_ALLOC_FAILED if there was not enough 185 * memory to allocate context data. 186 * \return #MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED 187 * if the call to \p f_entropy failed. 188 */ 189 int mbedtls_hmac_drbg_seed(mbedtls_hmac_drbg_context *ctx, 190 const mbedtls_md_info_t *md_info, 191 int (*f_entropy)(void *, unsigned char *, size_t), 192 void *p_entropy, 193 const unsigned char *custom, 194 size_t len); 195 196 /** 197 * \brief Initialisation of simplified HMAC_DRBG (never reseeds). 198 * 199 * This function is meant for use in algorithms that need a pseudorandom 200 * input such as deterministic ECDSA. 201 */ 202 #if defined(MBEDTLS_THREADING_C) 203 /** 204 * \note When Mbed TLS is built with threading support, 205 * after this function returns successfully, 206 * it is safe to call mbedtls_hmac_drbg_random() 207 * from multiple threads. Other operations, including 208 * reseeding, are not thread-safe. 209 */ 210 #endif /* MBEDTLS_THREADING_C */ 211 /** 212 * \param ctx HMAC_DRBG context to be initialised. 213 * \param md_info MD algorithm to use for HMAC_DRBG. 214 * \param data Concatenation of the initial entropy string and 215 * the additional data. 216 * \param data_len Length of \p data in bytes. 217 * 218 * \return \c 0 if successful. or 219 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info is 220 * invalid. 221 * \return #MBEDTLS_ERR_MD_ALLOC_FAILED if there was not enough 222 * memory to allocate context data. 223 */ 224 int mbedtls_hmac_drbg_seed_buf(mbedtls_hmac_drbg_context *ctx, 225 const mbedtls_md_info_t *md_info, 226 const unsigned char *data, size_t data_len); 227 228 /** 229 * \brief This function turns prediction resistance on or off. 230 * The default value is off. 231 * 232 * \note If enabled, entropy is gathered at the beginning of 233 * every call to mbedtls_hmac_drbg_random_with_add() 234 * or mbedtls_hmac_drbg_random(). 235 * Only use this if your entropy source has sufficient 236 * throughput. 237 * 238 * \param ctx The HMAC_DRBG context. 239 * \param resistance #MBEDTLS_HMAC_DRBG_PR_ON or #MBEDTLS_HMAC_DRBG_PR_OFF. 240 */ 241 void mbedtls_hmac_drbg_set_prediction_resistance(mbedtls_hmac_drbg_context *ctx, 242 int resistance); 243 244 /** 245 * \brief This function sets the amount of entropy grabbed on each 246 * seed or reseed. 247 * 248 * See the documentation of mbedtls_hmac_drbg_seed() for the default value. 249 * 250 * \param ctx The HMAC_DRBG context. 251 * \param len The amount of entropy to grab, in bytes. 252 */ 253 void mbedtls_hmac_drbg_set_entropy_len(mbedtls_hmac_drbg_context *ctx, 254 size_t len); 255 256 /** 257 * \brief Set the reseed interval. 258 * 259 * The reseed interval is the number of calls to mbedtls_hmac_drbg_random() 260 * or mbedtls_hmac_drbg_random_with_add() after which the entropy function 261 * is called again. 262 * 263 * The default value is #MBEDTLS_HMAC_DRBG_RESEED_INTERVAL. 264 * 265 * \param ctx The HMAC_DRBG context. 266 * \param interval The reseed interval. 267 */ 268 void mbedtls_hmac_drbg_set_reseed_interval(mbedtls_hmac_drbg_context *ctx, 269 int interval); 270 271 /** 272 * \brief This function updates the state of the HMAC_DRBG context. 273 * 274 * \note This function is not thread-safe. It is not safe 275 * to call this function if another thread might be 276 * concurrently obtaining random numbers from the same 277 * context or updating or reseeding the same context. 278 * 279 * \param ctx The HMAC_DRBG context. 280 * \param additional The data to update the state with. 281 * If this is \c NULL, there is no additional data. 282 * \param add_len Length of \p additional in bytes. 283 * Unused if \p additional is \c NULL. 284 * 285 * \return \c 0 on success, or an error from the underlying 286 * hash calculation. 287 */ 288 int mbedtls_hmac_drbg_update_ret(mbedtls_hmac_drbg_context *ctx, 289 const unsigned char *additional, size_t add_len); 290 291 /** 292 * \brief This function reseeds the HMAC_DRBG context, that is 293 * extracts data from the entropy source. 294 * 295 * \note This function is not thread-safe. It is not safe 296 * to call this function if another thread might be 297 * concurrently obtaining random numbers from the same 298 * context or updating or reseeding the same context. 299 * 300 * \param ctx The HMAC_DRBG context. 301 * \param additional Additional data to add to the state. 302 * If this is \c NULL, there is no additional data 303 * and \p len should be \c 0. 304 * \param len The length of the additional data. 305 * This must be at most #MBEDTLS_HMAC_DRBG_MAX_INPUT 306 * and also at most 307 * #MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT - \c entropy_len 308 * where \c entropy_len is the entropy length 309 * (see mbedtls_hmac_drbg_set_entropy_len()). 310 * 311 * \return \c 0 if successful. 312 * \return #MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED 313 * if a call to the entropy function failed. 314 */ 315 int mbedtls_hmac_drbg_reseed(mbedtls_hmac_drbg_context *ctx, 316 const unsigned char *additional, size_t len); 317 318 /** 319 * \brief This function updates an HMAC_DRBG instance with additional 320 * data and uses it to generate random data. 321 * 322 * This function automatically reseeds if the reseed counter is exceeded 323 * or prediction resistance is enabled. 324 * 325 * \note This function is not thread-safe. It is not safe 326 * to call this function if another thread might be 327 * concurrently obtaining random numbers from the same 328 * context or updating or reseeding the same context. 329 * 330 * \param p_rng The HMAC_DRBG context. This must be a pointer to a 331 * #mbedtls_hmac_drbg_context structure. 332 * \param output The buffer to fill. 333 * \param output_len The length of the buffer in bytes. 334 * This must be at most #MBEDTLS_HMAC_DRBG_MAX_REQUEST. 335 * \param additional Additional data to update with. 336 * If this is \c NULL, there is no additional data 337 * and \p add_len should be \c 0. 338 * \param add_len The length of the additional data. 339 * This must be at most #MBEDTLS_HMAC_DRBG_MAX_INPUT. 340 * 341 * \return \c 0 if successful. 342 * \return #MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED 343 * if a call to the entropy source failed. 344 * \return #MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG if 345 * \p output_len > #MBEDTLS_HMAC_DRBG_MAX_REQUEST. 346 * \return #MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG if 347 * \p add_len > #MBEDTLS_HMAC_DRBG_MAX_INPUT. 348 */ 349 int mbedtls_hmac_drbg_random_with_add(void *p_rng, 350 unsigned char *output, size_t output_len, 351 const unsigned char *additional, 352 size_t add_len); 353 354 /** 355 * \brief This function uses HMAC_DRBG to generate random data. 356 * 357 * This function automatically reseeds if the reseed counter is exceeded 358 * or prediction resistance is enabled. 359 */ 360 #if defined(MBEDTLS_THREADING_C) 361 /** 362 * \note When Mbed TLS is built with threading support, 363 * it is safe to call mbedtls_ctr_drbg_random() 364 * from multiple threads. Other operations, including 365 * reseeding, are not thread-safe. 366 */ 367 #endif /* MBEDTLS_THREADING_C */ 368 /** 369 * \param p_rng The HMAC_DRBG context. This must be a pointer to a 370 * #mbedtls_hmac_drbg_context structure. 371 * \param output The buffer to fill. 372 * \param out_len The length of the buffer in bytes. 373 * This must be at most #MBEDTLS_HMAC_DRBG_MAX_REQUEST. 374 * 375 * \return \c 0 if successful. 376 * \return #MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED 377 * if a call to the entropy source failed. 378 * \return #MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG if 379 * \p out_len > #MBEDTLS_HMAC_DRBG_MAX_REQUEST. 380 */ 381 int mbedtls_hmac_drbg_random(void *p_rng, unsigned char *output, size_t out_len); 382 383 /** 384 * \brief This function resets HMAC_DRBG context to the state immediately 385 * after initial call of mbedtls_hmac_drbg_init(). 386 * 387 * \param ctx The HMAC_DRBG context to free. 388 */ 389 void mbedtls_hmac_drbg_free(mbedtls_hmac_drbg_context *ctx); 390 391 #if !defined(MBEDTLS_DEPRECATED_REMOVED) 392 #if defined(MBEDTLS_DEPRECATED_WARNING) 393 #define MBEDTLS_DEPRECATED __attribute__((deprecated)) 394 #else 395 #define MBEDTLS_DEPRECATED 396 #endif 397 /** 398 * \brief This function updates the state of the HMAC_DRBG context. 399 * 400 * \deprecated Superseded by mbedtls_hmac_drbg_update_ret() 401 * in 2.16.0. 402 * 403 * \param ctx The HMAC_DRBG context. 404 * \param additional The data to update the state with. 405 * If this is \c NULL, there is no additional data. 406 * \param add_len Length of \p additional in bytes. 407 * Unused if \p additional is \c NULL. 408 */ 409 MBEDTLS_DEPRECATED void mbedtls_hmac_drbg_update( 410 mbedtls_hmac_drbg_context *ctx, 411 const unsigned char *additional, size_t add_len); 412 #undef MBEDTLS_DEPRECATED 413 #endif /* !MBEDTLS_DEPRECATED_REMOVED */ 414 415 #if defined(MBEDTLS_FS_IO) 416 /** 417 * \brief This function writes a seed file. 418 * 419 * \param ctx The HMAC_DRBG context. 420 * \param path The name of the file. 421 * 422 * \return \c 0 on success. 423 * \return #MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR on file error. 424 * \return #MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED on reseed 425 * failure. 426 */ 427 int mbedtls_hmac_drbg_write_seed_file(mbedtls_hmac_drbg_context *ctx, const char *path); 428 429 /** 430 * \brief This function reads and updates a seed file. The seed 431 * is added to this instance. 432 * 433 * \param ctx The HMAC_DRBG context. 434 * \param path The name of the file. 435 * 436 * \return \c 0 on success. 437 * \return #MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR on file error. 438 * \return #MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED on 439 * reseed failure. 440 * \return #MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG if the existing 441 * seed file is too large. 442 */ 443 int mbedtls_hmac_drbg_update_seed_file(mbedtls_hmac_drbg_context *ctx, const char *path); 444 #endif /* MBEDTLS_FS_IO */ 445 446 447 #if defined(MBEDTLS_SELF_TEST) 448 /** 449 * \brief The HMAC_DRBG Checkup routine. 450 * 451 * \return \c 0 if successful. 452 * \return \c 1 if the test failed. 453 */ 454 int mbedtls_hmac_drbg_self_test(int verbose); 455 #endif 456 457 #ifdef __cplusplus 458 } 459 #endif 460 461 #endif /* hmac_drbg.h */ 462