| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 1 | /** | 
|  | 2 | * \file ctr_drbg.h | 
|  | 3 | * | 
| Gilles Peskine | ec51dd1 | 2019-09-30 15:01:02 +0200 | [diff] [blame] | 4 | * \brief    This file contains definitions and functions for the | 
|  | 5 | *           CTR_DRBG pseudorandom generator. | 
| Rose Zadik | c9474eb | 2018-03-27 10:58:22 +0100 | [diff] [blame] | 6 | * | 
| Rose Zadik | f25eb6e | 2018-04-16 14:51:52 +0100 | [diff] [blame] | 7 | * CTR_DRBG is a standardized way of building a PRNG from a block-cipher | 
|  | 8 | * in counter mode operation, as defined in <em>NIST SP 800-90A: | 
|  | 9 | * Recommendation for Random Number Generation Using Deterministic Random | 
|  | 10 | * Bit Generators</em>. | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 11 | * | 
| Nir Sonnenschein | eb73f7a | 2018-07-30 17:46:49 +0300 | [diff] [blame] | 12 | * The Mbed TLS implementation of CTR_DRBG uses AES-256 (default) or AES-128 | 
| Gilles Peskine | d0c64c8 | 2019-10-03 14:20:46 +0200 | [diff] [blame] | 13 | * (if \c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is enabled at compile time) | 
| Gilles Peskine | dddda81 | 2019-10-03 14:22:04 +0200 | [diff] [blame] | 14 | * as the underlying block cipher, with a derivation function. | 
| Gilles Peskine | dddda81 | 2019-10-03 14:22:04 +0200 | [diff] [blame] | 15 | * | 
| Gilles Peskine | e9a3454 | 2019-10-22 20:43:24 +0200 | [diff] [blame] | 16 | * The security strength as defined in NIST SP 800-90A is | 
|  | 17 | * 128 bits when AES-128 is used (\c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY enabled) | 
|  | 18 | * and 256 bits otherwise, provided that #MBEDTLS_CTR_DRBG_ENTROPY_LEN is | 
| Bence Szépkúti | bb0cfeb | 2021-05-28 09:42:25 +0200 | [diff] [blame] | 19 | * kept at its default value (and not overridden in mbedtls_config.h) and that the | 
| Gilles Peskine | e9a3454 | 2019-10-22 20:43:24 +0200 | [diff] [blame] | 20 | * DRBG instance is set up with default parameters. | 
|  | 21 | * See the documentation of mbedtls_ctr_drbg_seed() for more | 
|  | 22 | * information. | 
| Darryl Green | a40a101 | 2018-01-05 15:33:17 +0000 | [diff] [blame] | 23 | */ | 
|  | 24 | /* | 
| Bence Szépkúti | 1e14827 | 2020-08-07 13:07:28 +0200 | [diff] [blame] | 25 | *  Copyright The Mbed TLS Contributors | 
| Manuel Pégourié-Gonnard | 37ff140 | 2015-09-04 14:21:07 +0200 | [diff] [blame] | 26 | *  SPDX-License-Identifier: Apache-2.0 | 
|  | 27 | * | 
|  | 28 | *  Licensed under the Apache License, Version 2.0 (the "License"); you may | 
|  | 29 | *  not use this file except in compliance with the License. | 
|  | 30 | *  You may obtain a copy of the License at | 
|  | 31 | * | 
|  | 32 | *  http://www.apache.org/licenses/LICENSE-2.0 | 
|  | 33 | * | 
|  | 34 | *  Unless required by applicable law or agreed to in writing, software | 
|  | 35 | *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT | 
|  | 36 | *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | 
|  | 37 | *  See the License for the specific language governing permissions and | 
|  | 38 | *  limitations under the License. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 39 | */ | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 40 |  | 
| Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 41 | #ifndef MBEDTLS_CTR_DRBG_H | 
|  | 42 | #define MBEDTLS_CTR_DRBG_H | 
| Mateusz Starzyk | 846f021 | 2021-05-19 19:44:07 +0200 | [diff] [blame] | 43 | #include "mbedtls/private_access.h" | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 44 |  | 
| Bence Szépkúti | c662b36 | 2021-05-27 11:25:03 +0200 | [diff] [blame] | 45 | #include "mbedtls/build_info.h" | 
| Andrzej Kurek | c470b6b | 2019-01-31 08:20:20 -0500 | [diff] [blame] | 46 |  | 
| Jaeden Amero | c49fbbf | 2019-07-04 20:01:14 +0100 | [diff] [blame] | 47 | #include "mbedtls/aes.h" | 
| Manuel Pégourié-Gonnard | 4011eb4 | 2023-03-21 17:10:45 +0100 | [diff] [blame] | 48 | #include "entropy.h" | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 49 |  | 
| Manuel Pégourié-Gonnard | 0a4fb09 | 2015-05-07 12:50:31 +0100 | [diff] [blame] | 50 | #if defined(MBEDTLS_THREADING_C) | 
| Jaeden Amero | c49fbbf | 2019-07-04 20:01:14 +0100 | [diff] [blame] | 51 | #include "mbedtls/threading.h" | 
| Manuel Pégourié-Gonnard | 0a4fb09 | 2015-05-07 12:50:31 +0100 | [diff] [blame] | 52 | #endif | 
|  | 53 |  | 
| Gilles Peskine | d297157 | 2021-07-26 18:48:10 +0200 | [diff] [blame] | 54 | /** The entropy source failed. */ | 
|  | 55 | #define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED        -0x0034 | 
|  | 56 | /** The requested random buffer length is too big. */ | 
|  | 57 | #define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG              -0x0036 | 
|  | 58 | /** The input (entropy + additional data) is too large. */ | 
|  | 59 | #define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG                -0x0038 | 
|  | 60 | /** Read or write error in file. */ | 
|  | 61 | #define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR                -0x003A | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 62 |  | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 63 | #define MBEDTLS_CTR_DRBG_BLOCKSIZE          16 /**< The block size used by the cipher. */ | 
| Nir Sonnenschein | ce266e4 | 2018-08-29 10:11:46 +0300 | [diff] [blame] | 64 |  | 
| Nir Sonnenschein | 43e4ff0 | 2018-09-03 14:15:46 +0300 | [diff] [blame] | 65 | #if defined(MBEDTLS_CTR_DRBG_USE_128_BIT_KEY) | 
| Gilles Peskine | 08875d4 | 2019-09-24 14:40:40 +0200 | [diff] [blame] | 66 | #define MBEDTLS_CTR_DRBG_KEYSIZE            16 | 
|  | 67 | /**< The key size in bytes used by the cipher. | 
|  | 68 | * | 
|  | 69 | * Compile-time choice: 16 bytes (128 bits) | 
| Gilles Peskine | d0c64c8 | 2019-10-03 14:20:46 +0200 | [diff] [blame] | 70 | * because #MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is enabled. | 
| Gilles Peskine | 08875d4 | 2019-09-24 14:40:40 +0200 | [diff] [blame] | 71 | */ | 
| Nir Sonnenschein | eb73f7a | 2018-07-30 17:46:49 +0300 | [diff] [blame] | 72 | #else | 
| Gilles Peskine | 08875d4 | 2019-09-24 14:40:40 +0200 | [diff] [blame] | 73 | #define MBEDTLS_CTR_DRBG_KEYSIZE            32 | 
|  | 74 | /**< The key size in bytes used by the cipher. | 
|  | 75 | * | 
|  | 76 | * Compile-time choice: 32 bytes (256 bits) | 
| Gilles Peskine | d0c64c8 | 2019-10-03 14:20:46 +0200 | [diff] [blame] | 77 | * because \c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is disabled. | 
| Gilles Peskine | 08875d4 | 2019-09-24 14:40:40 +0200 | [diff] [blame] | 78 | */ | 
| Nir Sonnenschein | a4588d4 | 2018-07-30 16:59:36 +0300 | [diff] [blame] | 79 | #endif | 
| Nir Sonnenschein | 43e4ff0 | 2018-09-03 14:15:46 +0300 | [diff] [blame] | 80 |  | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 81 | #define MBEDTLS_CTR_DRBG_KEYBITS            (MBEDTLS_CTR_DRBG_KEYSIZE * 8)   /**< The key size for the DRBG operation, in bits. */ | 
|  | 82 | #define MBEDTLS_CTR_DRBG_SEEDLEN            (MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE)   /**< The seed length, calculated as (counter + AES key). */ | 
| Paul Bakker | 9bcf16c | 2013-06-24 19:31:17 +0200 | [diff] [blame] | 83 |  | 
| Paul Bakker | 088c5c5 | 2014-04-25 11:11:10 +0200 | [diff] [blame] | 84 | /** | 
|  | 85 | * \name SECTION: Module settings | 
|  | 86 | * | 
|  | 87 | * The configuration options you can set for this module are in this section. | 
| Bence Szépkúti | bb0cfeb | 2021-05-28 09:42:25 +0200 | [diff] [blame] | 88 | * Either change them in mbedtls_config.h or define them using the compiler command | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 89 | * line. | 
| Paul Bakker | 088c5c5 | 2014-04-25 11:11:10 +0200 | [diff] [blame] | 90 | * \{ | 
|  | 91 | */ | 
|  | 92 |  | 
| Gilles Peskine | dddda81 | 2019-10-03 14:22:04 +0200 | [diff] [blame] | 93 | /** \def MBEDTLS_CTR_DRBG_ENTROPY_LEN | 
|  | 94 | * | 
|  | 95 | * \brief The amount of entropy used per seed by default, in bytes. | 
|  | 96 | */ | 
| Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 97 | #if !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN) | 
| Manuel Pégourié-Gonnard | 4011eb4 | 2023-03-21 17:10:45 +0100 | [diff] [blame] | 98 | #if defined(MBEDTLS_ENTROPY_SHA512_ACCUMULATOR) | 
|  | 99 | /** This is 48 bytes because the entropy module uses SHA-512. | 
| Gilles Peskine | 08875d4 | 2019-09-24 14:40:40 +0200 | [diff] [blame] | 100 | */ | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 101 | #define MBEDTLS_CTR_DRBG_ENTROPY_LEN        48 | 
| Gilles Peskine | dddda81 | 2019-10-03 14:22:04 +0200 | [diff] [blame] | 102 |  | 
| Manuel Pégourié-Gonnard | 4011eb4 | 2023-03-21 17:10:45 +0100 | [diff] [blame] | 103 | #else /* MBEDTLS_ENTROPY_SHA512_ACCUMULATOR */ | 
| Gilles Peskine | dddda81 | 2019-10-03 14:22:04 +0200 | [diff] [blame] | 104 |  | 
| Manuel Pégourié-Gonnard | 4011eb4 | 2023-03-21 17:10:45 +0100 | [diff] [blame] | 105 | /** This is 32 bytes because the entropy module uses SHA-256. | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 106 | */ | 
| Gilles Peskine | dddda81 | 2019-10-03 14:22:04 +0200 | [diff] [blame] | 107 | #if !defined(MBEDTLS_CTR_DRBG_USE_128_BIT_KEY) | 
|  | 108 | /** \warning To achieve a 256-bit security strength, you must pass a nonce | 
|  | 109 | *           to mbedtls_ctr_drbg_seed(). | 
|  | 110 | */ | 
|  | 111 | #endif /* !defined(MBEDTLS_CTR_DRBG_USE_128_BIT_KEY) */ | 
| Gilles Peskine | 08875d4 | 2019-09-24 14:40:40 +0200 | [diff] [blame] | 112 | #define MBEDTLS_CTR_DRBG_ENTROPY_LEN        32 | 
| Manuel Pégourié-Gonnard | 4011eb4 | 2023-03-21 17:10:45 +0100 | [diff] [blame] | 113 | #endif /* MBEDTLS_ENTROPY_SHA512_ACCUMULATOR */ | 
| Gilles Peskine | dddda81 | 2019-10-03 14:22:04 +0200 | [diff] [blame] | 114 | #endif /* !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN) */ | 
| Paul Bakker | 088c5c5 | 2014-04-25 11:11:10 +0200 | [diff] [blame] | 115 |  | 
| Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 116 | #if !defined(MBEDTLS_CTR_DRBG_RESEED_INTERVAL) | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 117 | #define MBEDTLS_CTR_DRBG_RESEED_INTERVAL    10000 | 
|  | 118 | /**< The interval before reseed is performed by default. */ | 
| Paul Bakker | 088c5c5 | 2014-04-25 11:11:10 +0200 | [diff] [blame] | 119 | #endif | 
|  | 120 |  | 
| Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 121 | #if !defined(MBEDTLS_CTR_DRBG_MAX_INPUT) | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 122 | #define MBEDTLS_CTR_DRBG_MAX_INPUT          256 | 
|  | 123 | /**< The maximum number of additional input Bytes. */ | 
| Paul Bakker | 088c5c5 | 2014-04-25 11:11:10 +0200 | [diff] [blame] | 124 | #endif | 
|  | 125 |  | 
| Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 126 | #if !defined(MBEDTLS_CTR_DRBG_MAX_REQUEST) | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 127 | #define MBEDTLS_CTR_DRBG_MAX_REQUEST        1024 | 
|  | 128 | /**< The maximum number of requested Bytes per call. */ | 
| Paul Bakker | 088c5c5 | 2014-04-25 11:11:10 +0200 | [diff] [blame] | 129 | #endif | 
|  | 130 |  | 
| Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 131 | #if !defined(MBEDTLS_CTR_DRBG_MAX_SEED_INPUT) | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 132 | #define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT     384 | 
| Gilles Peskine | 08875d4 | 2019-09-24 14:40:40 +0200 | [diff] [blame] | 133 | /**< The maximum size of seed or reseed buffer in bytes. */ | 
| Paul Bakker | 088c5c5 | 2014-04-25 11:11:10 +0200 | [diff] [blame] | 134 | #endif | 
|  | 135 |  | 
| Andrzej Kurek | 38d4fdd | 2021-12-28 16:22:52 +0100 | [diff] [blame] | 136 | /** \} name SECTION: Module settings */ | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 137 |  | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 138 | #define MBEDTLS_CTR_DRBG_PR_OFF             0 | 
|  | 139 | /**< Prediction resistance is disabled. */ | 
|  | 140 | #define MBEDTLS_CTR_DRBG_PR_ON              1 | 
|  | 141 | /**< Prediction resistance is enabled. */ | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 142 |  | 
|  | 143 | #ifdef __cplusplus | 
|  | 144 | extern "C" { | 
|  | 145 | #endif | 
|  | 146 |  | 
| Gilles Peskine | 6997166 | 2019-10-23 19:39:36 +0200 | [diff] [blame] | 147 | #if MBEDTLS_CTR_DRBG_ENTROPY_LEN >= MBEDTLS_CTR_DRBG_KEYSIZE * 3 / 2 | 
|  | 148 | /** The default length of the nonce read from the entropy source. | 
|  | 149 | * | 
|  | 150 | * This is \c 0 because a single read from the entropy source is sufficient | 
|  | 151 | * to include a nonce. | 
|  | 152 | * See the documentation of mbedtls_ctr_drbg_seed() for more information. | 
|  | 153 | */ | 
|  | 154 | #define MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN 0 | 
|  | 155 | #else | 
|  | 156 | /** The default length of the nonce read from the entropy source. | 
|  | 157 | * | 
|  | 158 | * This is half of the default entropy length because a single read from | 
|  | 159 | * the entropy source does not provide enough material to form a nonce. | 
|  | 160 | * See the documentation of mbedtls_ctr_drbg_seed() for more information. | 
|  | 161 | */ | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 162 | #define MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN (MBEDTLS_CTR_DRBG_ENTROPY_LEN + 1) / 2 | 
| Gilles Peskine | 6997166 | 2019-10-23 19:39:36 +0200 | [diff] [blame] | 163 | #endif | 
|  | 164 |  | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 165 | /** | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 166 | * \brief          The CTR_DRBG context structure. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 167 | */ | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 168 | typedef struct mbedtls_ctr_drbg_context { | 
| Mateusz Starzyk | 846f021 | 2021-05-19 19:44:07 +0200 | [diff] [blame] | 169 | unsigned char MBEDTLS_PRIVATE(counter)[16];  /*!< The counter (V). */ | 
|  | 170 | int MBEDTLS_PRIVATE(reseed_counter);         /*!< The reseed counter. | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 171 | * This is the number of requests that have | 
|  | 172 | * been made since the last (re)seeding, | 
|  | 173 | * minus one. | 
|  | 174 | * Before the initial seeding, this field | 
|  | 175 | * contains the amount of entropy in bytes | 
|  | 176 | * to use as a nonce for the initial seeding, | 
|  | 177 | * or -1 if no nonce length has been explicitly | 
|  | 178 | * set (see mbedtls_ctr_drbg_set_nonce_len()). | 
|  | 179 | */ | 
| Mateusz Starzyk | 846f021 | 2021-05-19 19:44:07 +0200 | [diff] [blame] | 180 | int MBEDTLS_PRIVATE(prediction_resistance);  /*!< This determines whether prediction | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 181 | resistance is enabled, that is | 
|  | 182 | whether to systematically reseed before | 
|  | 183 | each random generation. */ | 
| Mateusz Starzyk | 846f021 | 2021-05-19 19:44:07 +0200 | [diff] [blame] | 184 | size_t MBEDTLS_PRIVATE(entropy_len);         /*!< The amount of entropy grabbed on each | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 185 | seed or reseed operation, in bytes. */ | 
| Mateusz Starzyk | 846f021 | 2021-05-19 19:44:07 +0200 | [diff] [blame] | 186 | int MBEDTLS_PRIVATE(reseed_interval);        /*!< The reseed interval. | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 187 | * This is the maximum number of requests | 
|  | 188 | * that can be made between reseedings. */ | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 189 |  | 
| Mateusz Starzyk | 846f021 | 2021-05-19 19:44:07 +0200 | [diff] [blame] | 190 | mbedtls_aes_context MBEDTLS_PRIVATE(aes_ctx);        /*!< The AES context. */ | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 191 |  | 
|  | 192 | /* | 
|  | 193 | * Callbacks (Entropy) | 
|  | 194 | */ | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 195 | int(*MBEDTLS_PRIVATE(f_entropy))(void *, unsigned char *, size_t); | 
|  | 196 | /*!< The entropy callback function. */ | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 197 |  | 
| Mateusz Starzyk | 846f021 | 2021-05-19 19:44:07 +0200 | [diff] [blame] | 198 | void *MBEDTLS_PRIVATE(p_entropy);            /*!< The context for the entropy function. */ | 
| Manuel Pégourié-Gonnard | 0a4fb09 | 2015-05-07 12:50:31 +0100 | [diff] [blame] | 199 |  | 
|  | 200 | #if defined(MBEDTLS_THREADING_C) | 
| Gilles Peskine | da290f9 | 2021-02-09 18:44:02 +0100 | [diff] [blame] | 201 | /* Invariant: the mutex is initialized if and only if f_entropy != NULL. | 
|  | 202 | * This means that the mutex is initialized during the initial seeding | 
|  | 203 | * in mbedtls_ctr_drbg_seed() and freed in mbedtls_ctr_drbg_free(). | 
|  | 204 | * | 
|  | 205 | * Note that this invariant may change without notice. Do not rely on it | 
|  | 206 | * and do not access the mutex directly in application code. | 
|  | 207 | */ | 
| Mateusz Starzyk | 846f021 | 2021-05-19 19:44:07 +0200 | [diff] [blame] | 208 | mbedtls_threading_mutex_t MBEDTLS_PRIVATE(mutex); | 
| Manuel Pégourié-Gonnard | 0a4fb09 | 2015-05-07 12:50:31 +0100 | [diff] [blame] | 209 | #endif | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 210 | } | 
| Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 211 | mbedtls_ctr_drbg_context; | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 212 |  | 
|  | 213 | /** | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 214 | * \brief               This function initializes the CTR_DRBG context, | 
|  | 215 | *                      and prepares it for mbedtls_ctr_drbg_seed() | 
|  | 216 | *                      or mbedtls_ctr_drbg_free(). | 
| Manuel Pégourié-Gonnard | 8d128ef | 2015-04-28 22:38:08 +0200 | [diff] [blame] | 217 | * | 
| Gavin Acquroff | 6aceb51 | 2020-03-01 17:06:11 -0800 | [diff] [blame] | 218 | * \note                The reseed interval is | 
|  | 219 | *                      #MBEDTLS_CTR_DRBG_RESEED_INTERVAL by default. | 
|  | 220 | *                      You can override it by calling | 
|  | 221 | *                      mbedtls_ctr_drbg_set_reseed_interval(). | 
|  | 222 | * | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 223 | * \param ctx           The CTR_DRBG context to initialize. | 
| Manuel Pégourié-Gonnard | 8d128ef | 2015-04-28 22:38:08 +0200 | [diff] [blame] | 224 | */ | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 225 | void mbedtls_ctr_drbg_init(mbedtls_ctr_drbg_context *ctx); | 
| Manuel Pégourié-Gonnard | 8d128ef | 2015-04-28 22:38:08 +0200 | [diff] [blame] | 226 |  | 
|  | 227 | /** | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 228 | * \brief               This function seeds and sets up the CTR_DRBG | 
|  | 229 | *                      entropy source for future reseeds. | 
| Paul Bakker | 9af723c | 2014-05-01 13:03:14 +0200 | [diff] [blame] | 230 | * | 
| Gilles Peskine | 223deea | 2019-09-24 14:48:53 +0200 | [diff] [blame] | 231 | * A typical choice for the \p f_entropy and \p p_entropy parameters is | 
|  | 232 | * to use the entropy module: | 
|  | 233 | * - \p f_entropy is mbedtls_entropy_func(); | 
|  | 234 | * - \p p_entropy is an instance of ::mbedtls_entropy_context initialized | 
|  | 235 | *   with mbedtls_entropy_init() (which registers the platform's default | 
|  | 236 | *   entropy sources). | 
|  | 237 | * | 
| Gilles Peskine | 50ed86b | 2019-10-04 12:15:55 +0200 | [diff] [blame] | 238 | * The entropy length is #MBEDTLS_CTR_DRBG_ENTROPY_LEN by default. | 
|  | 239 | * You can override it by calling mbedtls_ctr_drbg_set_entropy_len(). | 
| Gilles Peskine | ec51dd1 | 2019-09-30 15:01:02 +0200 | [diff] [blame] | 240 | * | 
| Gilles Peskine | e9a3454 | 2019-10-22 20:43:24 +0200 | [diff] [blame] | 241 | * The entropy nonce length is: | 
|  | 242 | * - \c 0 if the entropy length is at least 3/2 times the entropy length, | 
|  | 243 | *   which guarantees that the security strength is the maximum permitted | 
|  | 244 | *   by the key size and entropy length according to NIST SP 800-90A §10.2.1; | 
|  | 245 | * - Half the entropy length otherwise. | 
|  | 246 | * You can override it by calling mbedtls_ctr_drbg_set_nonce_len(). | 
| Gilles Peskine | 6997166 | 2019-10-23 19:39:36 +0200 | [diff] [blame] | 247 | * With the default entropy length, the entropy nonce length is | 
|  | 248 | * #MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN. | 
|  | 249 | * | 
| Gilles Peskine | 9be5098 | 2019-10-22 18:42:27 +0200 | [diff] [blame] | 250 | * You can provide a nonce and personalization string in addition to the | 
| Gilles Peskine | 223deea | 2019-09-24 14:48:53 +0200 | [diff] [blame] | 251 | * entropy source, to make this instantiation as unique as possible. | 
| Gilles Peskine | 9be5098 | 2019-10-22 18:42:27 +0200 | [diff] [blame] | 252 | * See SP 800-90A §8.6.7 for more details about nonces. | 
| Gilles Peskine | 223deea | 2019-09-24 14:48:53 +0200 | [diff] [blame] | 253 | * | 
| Gilles Peskine | 9be5098 | 2019-10-22 18:42:27 +0200 | [diff] [blame] | 254 | * The _seed_material_ value passed to the derivation function in | 
|  | 255 | * the CTR_DRBG Instantiate Process described in NIST SP 800-90A §10.2.1.3.2 | 
|  | 256 | * is the concatenation of the following strings: | 
|  | 257 | * - A string obtained by calling \p f_entropy function for the entropy | 
|  | 258 | *   length. | 
| Gilles Peskine | e9a3454 | 2019-10-22 20:43:24 +0200 | [diff] [blame] | 259 | */ | 
| Gilles Peskine | 6997166 | 2019-10-23 19:39:36 +0200 | [diff] [blame] | 260 | #if MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN == 0 | 
| Gilles Peskine | e9a3454 | 2019-10-22 20:43:24 +0200 | [diff] [blame] | 261 | /** | 
|  | 262 | * - If mbedtls_ctr_drbg_set_nonce_len() has been called, a string | 
|  | 263 | *   obtained by calling \p f_entropy function for the specified length. | 
|  | 264 | */ | 
|  | 265 | #else | 
|  | 266 | /** | 
|  | 267 | * - A string obtained by calling \p f_entropy function for the entropy nonce | 
|  | 268 | *   length. If the entropy nonce length is \c 0, this function does not | 
|  | 269 | *   make a second call to \p f_entropy. | 
|  | 270 | */ | 
|  | 271 | #endif | 
| Gilles Peskine | f305d92 | 2021-02-09 18:44:18 +0100 | [diff] [blame] | 272 | #if defined(MBEDTLS_THREADING_C) | 
|  | 273 | /** | 
|  | 274 | * \note                When Mbed TLS is built with threading support, | 
|  | 275 | *                      after this function returns successfully, | 
|  | 276 | *                      it is safe to call mbedtls_ctr_drbg_random() | 
|  | 277 | *                      from multiple threads. Other operations, including | 
|  | 278 | *                      reseeding, are not thread-safe. | 
|  | 279 | */ | 
|  | 280 | #endif /* MBEDTLS_THREADING_C */ | 
| Gilles Peskine | e9a3454 | 2019-10-22 20:43:24 +0200 | [diff] [blame] | 281 | /** | 
| Gilles Peskine | 9be5098 | 2019-10-22 18:42:27 +0200 | [diff] [blame] | 282 | * - The \p custom string. | 
|  | 283 | * | 
|  | 284 | * \note                To achieve the nominal security strength permitted | 
|  | 285 | *                      by CTR_DRBG, the entropy length must be: | 
|  | 286 | *                      - at least 16 bytes for a 128-bit strength | 
|  | 287 | *                      (maximum achievable strength when using AES-128); | 
|  | 288 | *                      - at least 32 bytes for a 256-bit strength | 
|  | 289 | *                      (maximum achievable strength when using AES-256). | 
|  | 290 | * | 
|  | 291 | *                      In addition, if you do not pass a nonce in \p custom, | 
|  | 292 | *                      the sum of the entropy length | 
| Gilles Peskine | e9a3454 | 2019-10-22 20:43:24 +0200 | [diff] [blame] | 293 | *                      and the entropy nonce length must be: | 
| Gilles Peskine | 9be5098 | 2019-10-22 18:42:27 +0200 | [diff] [blame] | 294 | *                      - at least 24 bytes for a 128-bit strength | 
|  | 295 | *                      (maximum achievable strength when using AES-128); | 
|  | 296 | *                      - at least 48 bytes for a 256-bit strength | 
|  | 297 | *                      (maximum achievable strength when using AES-256). | 
|  | 298 | * | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 299 | * \param ctx           The CTR_DRBG context to seed. | 
| Gilles Peskine | bd326f9 | 2019-10-28 17:33:07 +0100 | [diff] [blame] | 300 | *                      It must have been initialized with | 
|  | 301 | *                      mbedtls_ctr_drbg_init(). | 
|  | 302 | *                      After a successful call to mbedtls_ctr_drbg_seed(), | 
|  | 303 | *                      you may not call mbedtls_ctr_drbg_seed() again on | 
|  | 304 | *                      the same context unless you call | 
|  | 305 | *                      mbedtls_ctr_drbg_free() and mbedtls_ctr_drbg_init() | 
|  | 306 | *                      again first. | 
| Gilles Peskine | f305d92 | 2021-02-09 18:44:18 +0100 | [diff] [blame] | 307 | *                      After a failed call to mbedtls_ctr_drbg_seed(), | 
|  | 308 | *                      you must call mbedtls_ctr_drbg_free(). | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 309 | * \param f_entropy     The entropy callback, taking as arguments the | 
|  | 310 | *                      \p p_entropy context, the buffer to fill, and the | 
| Gilles Peskine | 08875d4 | 2019-09-24 14:40:40 +0200 | [diff] [blame] | 311 | *                      length of the buffer. | 
| Gilles Peskine | 50ed86b | 2019-10-04 12:15:55 +0200 | [diff] [blame] | 312 | *                      \p f_entropy is always called with a buffer size | 
| Gilles Peskine | 9be5098 | 2019-10-22 18:42:27 +0200 | [diff] [blame] | 313 | *                      less than or equal to the entropy length. | 
| Gilles Peskine | ec51dd1 | 2019-09-30 15:01:02 +0200 | [diff] [blame] | 314 | * \param p_entropy     The entropy context to pass to \p f_entropy. | 
| Gilles Peskine | 217b815 | 2019-10-01 18:39:45 +0200 | [diff] [blame] | 315 | * \param custom        The personalization string. | 
|  | 316 | *                      This can be \c NULL, in which case the personalization | 
|  | 317 | *                      string is empty regardless of the value of \p len. | 
|  | 318 | * \param len           The length of the personalization string. | 
| Gilles Peskine | 944bc58 | 2019-09-24 14:48:30 +0200 | [diff] [blame] | 319 | *                      This must be at most | 
|  | 320 | *                      #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT | 
|  | 321 | *                      - #MBEDTLS_CTR_DRBG_ENTROPY_LEN. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 322 | * | 
| Rose Zadik | c9474eb | 2018-03-27 10:58:22 +0100 | [diff] [blame] | 323 | * \return              \c 0 on success. | 
|  | 324 | * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 325 | */ | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 326 | int mbedtls_ctr_drbg_seed(mbedtls_ctr_drbg_context *ctx, | 
|  | 327 | int (*f_entropy)(void *, unsigned char *, size_t), | 
|  | 328 | void *p_entropy, | 
|  | 329 | const unsigned char *custom, | 
|  | 330 | size_t len); | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 331 |  | 
|  | 332 | /** | 
| Gavin Acquroff | 6aceb51 | 2020-03-01 17:06:11 -0800 | [diff] [blame] | 333 | * \brief               This function resets CTR_DRBG context to the state immediately | 
|  | 334 | *                      after initial call of mbedtls_ctr_drbg_init(). | 
| Paul Bakker | fff0366 | 2014-06-18 16:21:25 +0200 | [diff] [blame] | 335 | * | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 336 | * \param ctx           The CTR_DRBG context to clear. | 
| Paul Bakker | fff0366 | 2014-06-18 16:21:25 +0200 | [diff] [blame] | 337 | */ | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 338 | void mbedtls_ctr_drbg_free(mbedtls_ctr_drbg_context *ctx); | 
| Paul Bakker | fff0366 | 2014-06-18 16:21:25 +0200 | [diff] [blame] | 339 |  | 
|  | 340 | /** | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 341 | * \brief               This function turns prediction resistance on or off. | 
|  | 342 | *                      The default value is off. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 343 | * | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 344 | * \note                If enabled, entropy is gathered at the beginning of | 
| Gilles Peskine | ec51dd1 | 2019-09-30 15:01:02 +0200 | [diff] [blame] | 345 | *                      every call to mbedtls_ctr_drbg_random_with_add() | 
|  | 346 | *                      or mbedtls_ctr_drbg_random(). | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 347 | *                      Only use this if your entropy source has sufficient | 
|  | 348 | *                      throughput. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 349 | * | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 350 | * \param ctx           The CTR_DRBG context. | 
|  | 351 | * \param resistance    #MBEDTLS_CTR_DRBG_PR_ON or #MBEDTLS_CTR_DRBG_PR_OFF. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 352 | */ | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 353 | void mbedtls_ctr_drbg_set_prediction_resistance(mbedtls_ctr_drbg_context *ctx, | 
|  | 354 | int resistance); | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 355 |  | 
|  | 356 | /** | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 357 | * \brief               This function sets the amount of entropy grabbed on each | 
| Gilles Peskine | 50ed86b | 2019-10-04 12:15:55 +0200 | [diff] [blame] | 358 | *                      seed or reseed. | 
| Gilles Peskine | ec51dd1 | 2019-09-30 15:01:02 +0200 | [diff] [blame] | 359 | * | 
|  | 360 | * The default value is #MBEDTLS_CTR_DRBG_ENTROPY_LEN. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 361 | * | 
| Gilles Peskine | dddda81 | 2019-10-03 14:22:04 +0200 | [diff] [blame] | 362 | * \note                The security strength of CTR_DRBG is bounded by the | 
|  | 363 | *                      entropy length. Thus: | 
|  | 364 | *                      - When using AES-256 | 
|  | 365 | *                        (\c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is disabled, | 
|  | 366 | *                        which is the default), | 
|  | 367 | *                        \p len must be at least 32 (in bytes) | 
|  | 368 | *                        to achieve a 256-bit strength. | 
|  | 369 | *                      - When using AES-128 | 
|  | 370 | *                        (\c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is enabled) | 
|  | 371 | *                        \p len must be at least 16 (in bytes) | 
|  | 372 | *                        to achieve a 128-bit strength. | 
| Gilles Peskine | 223deea | 2019-09-24 14:48:53 +0200 | [diff] [blame] | 373 | * | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 374 | * \param ctx           The CTR_DRBG context. | 
| Gilles Peskine | 08875d4 | 2019-09-24 14:40:40 +0200 | [diff] [blame] | 375 | * \param len           The amount of entropy to grab, in bytes. | 
| Gilles Peskine | 9be5098 | 2019-10-22 18:42:27 +0200 | [diff] [blame] | 376 | *                      This must be at most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT | 
|  | 377 | *                      and at most the maximum length accepted by the | 
|  | 378 | *                      entropy function that is set in the context. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 379 | */ | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 380 | void mbedtls_ctr_drbg_set_entropy_len(mbedtls_ctr_drbg_context *ctx, | 
|  | 381 | size_t len); | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 382 |  | 
|  | 383 | /** | 
| Gilles Peskine | 9be5098 | 2019-10-22 18:42:27 +0200 | [diff] [blame] | 384 | * \brief               This function sets the amount of entropy grabbed | 
|  | 385 | *                      as a nonce for the initial seeding. | 
|  | 386 | * | 
|  | 387 | * Call this function before calling mbedtls_ctr_drbg_seed() to read | 
|  | 388 | * a nonce from the entropy source during the initial seeding. | 
|  | 389 | * | 
|  | 390 | * \param ctx           The CTR_DRBG context. | 
|  | 391 | * \param len           The amount of entropy to grab for the nonce, in bytes. | 
|  | 392 | *                      This must be at most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT | 
|  | 393 | *                      and at most the maximum length accepted by the | 
|  | 394 | *                      entropy function that is set in the context. | 
|  | 395 | * | 
|  | 396 | * \return              \c 0 on success. | 
|  | 397 | * \return              #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if \p len is | 
|  | 398 | *                      more than #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT. | 
|  | 399 | * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED | 
|  | 400 | *                      if the initial seeding has already taken place. | 
|  | 401 | */ | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 402 | int mbedtls_ctr_drbg_set_nonce_len(mbedtls_ctr_drbg_context *ctx, | 
|  | 403 | size_t len); | 
| Gilles Peskine | 9be5098 | 2019-10-22 18:42:27 +0200 | [diff] [blame] | 404 |  | 
|  | 405 | /** | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 406 | * \brief               This function sets the reseed interval. | 
| Gilles Peskine | ec51dd1 | 2019-09-30 15:01:02 +0200 | [diff] [blame] | 407 | * | 
|  | 408 | * The reseed interval is the number of calls to mbedtls_ctr_drbg_random() | 
|  | 409 | * or mbedtls_ctr_drbg_random_with_add() after which the entropy function | 
|  | 410 | * is called again. | 
|  | 411 | * | 
|  | 412 | * The default value is #MBEDTLS_CTR_DRBG_RESEED_INTERVAL. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 413 | * | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 414 | * \param ctx           The CTR_DRBG context. | 
|  | 415 | * \param interval      The reseed interval. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 416 | */ | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 417 | void mbedtls_ctr_drbg_set_reseed_interval(mbedtls_ctr_drbg_context *ctx, | 
|  | 418 | int interval); | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 419 |  | 
|  | 420 | /** | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 421 | * \brief               This function reseeds the CTR_DRBG context, that is | 
|  | 422 | *                      extracts data from the entropy source. | 
| Paul Bakker | 9af723c | 2014-05-01 13:03:14 +0200 | [diff] [blame] | 423 | * | 
| Gilles Peskine | f305d92 | 2021-02-09 18:44:18 +0100 | [diff] [blame] | 424 | * \note                This function is not thread-safe. It is not safe | 
|  | 425 | *                      to call this function if another thread might be | 
|  | 426 | *                      concurrently obtaining random numbers from the same | 
|  | 427 | *                      context or updating or reseeding the same context. | 
|  | 428 | * | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 429 | * \param ctx           The CTR_DRBG context. | 
| Gilles Peskine | 10f16ac | 2019-10-01 18:30:02 +0200 | [diff] [blame] | 430 | * \param additional    Additional data to add to the state. Can be \c NULL. | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 431 | * \param len           The length of the additional data. | 
| Gilles Peskine | 944bc58 | 2019-09-24 14:48:30 +0200 | [diff] [blame] | 432 | *                      This must be less than | 
|  | 433 | *                      #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - \c entropy_len | 
|  | 434 | *                      where \c entropy_len is the entropy length | 
|  | 435 | *                      configured for the context. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 436 | * | 
| Rose Zadik | c9474eb | 2018-03-27 10:58:22 +0100 | [diff] [blame] | 437 | * \return              \c 0 on success. | 
|  | 438 | * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 439 | */ | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 440 | int mbedtls_ctr_drbg_reseed(mbedtls_ctr_drbg_context *ctx, | 
|  | 441 | const unsigned char *additional, size_t len); | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 442 |  | 
|  | 443 | /** | 
| Rose Zadik | c9474eb | 2018-03-27 10:58:22 +0100 | [diff] [blame] | 444 | * \brief              This function updates the state of the CTR_DRBG context. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 445 | * | 
| Gilles Peskine | f305d92 | 2021-02-09 18:44:18 +0100 | [diff] [blame] | 446 | * \note                This function is not thread-safe. It is not safe | 
|  | 447 | *                      to call this function if another thread might be | 
|  | 448 | *                      concurrently obtaining random numbers from the same | 
|  | 449 | *                      context or updating or reseeding the same context. | 
|  | 450 | * | 
| Rose Zadik | c9474eb | 2018-03-27 10:58:22 +0100 | [diff] [blame] | 451 | * \param ctx          The CTR_DRBG context. | 
| Gilles Peskine | 08875d4 | 2019-09-24 14:40:40 +0200 | [diff] [blame] | 452 | * \param additional   The data to update the state with. This must not be | 
| Gilles Peskine | 10f16ac | 2019-10-01 18:30:02 +0200 | [diff] [blame] | 453 | *                     \c NULL unless \p add_len is \c 0. | 
| Andrzej Kurek | c470b6b | 2019-01-31 08:20:20 -0500 | [diff] [blame] | 454 | * \param add_len      Length of \p additional in bytes. This must be at | 
|  | 455 | *                     most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT. | 
| Rose Zadik | c9474eb | 2018-03-27 10:58:22 +0100 | [diff] [blame] | 456 | * | 
| Andrzej Kurek | c470b6b | 2019-01-31 08:20:20 -0500 | [diff] [blame] | 457 | * \return             \c 0 on success. | 
|  | 458 | * \return             #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if | 
|  | 459 | *                     \p add_len is more than | 
|  | 460 | *                     #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT. | 
|  | 461 | * \return             An error from the underlying AES cipher on failure. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 462 | */ | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 463 | int mbedtls_ctr_drbg_update(mbedtls_ctr_drbg_context *ctx, | 
|  | 464 | const unsigned char *additional, | 
|  | 465 | size_t add_len); | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 466 |  | 
|  | 467 | /** | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 468 | * \brief   This function updates a CTR_DRBG instance with additional | 
|  | 469 | *          data and uses it to generate random data. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 470 | * | 
| Gilles Peskine | 2d8f069 | 2019-10-01 18:31:28 +0200 | [diff] [blame] | 471 | * This function automatically reseeds if the reseed counter is exceeded | 
|  | 472 | * or prediction resistance is enabled. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 473 | * | 
| Gilles Peskine | f305d92 | 2021-02-09 18:44:18 +0100 | [diff] [blame] | 474 | * \note                This function is not thread-safe. It is not safe | 
|  | 475 | *                      to call this function if another thread might be | 
|  | 476 | *                      concurrently obtaining random numbers from the same | 
|  | 477 | *                      context or updating or reseeding the same context. | 
|  | 478 | * | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 479 | * \param p_rng         The CTR_DRBG context. This must be a pointer to a | 
|  | 480 | *                      #mbedtls_ctr_drbg_context structure. | 
|  | 481 | * \param output        The buffer to fill. | 
| Gilles Peskine | ec51dd1 | 2019-09-30 15:01:02 +0200 | [diff] [blame] | 482 | * \param output_len    The length of the buffer in bytes. | 
| Gilles Peskine | 10f16ac | 2019-10-01 18:30:02 +0200 | [diff] [blame] | 483 | * \param additional    Additional data to update. Can be \c NULL, in which | 
| Gilles Peskine | 08875d4 | 2019-09-24 14:40:40 +0200 | [diff] [blame] | 484 | *                      case the additional data is empty regardless of | 
|  | 485 | *                      the value of \p add_len. | 
|  | 486 | * \param add_len       The length of the additional data | 
| Gilles Peskine | 10f16ac | 2019-10-01 18:30:02 +0200 | [diff] [blame] | 487 | *                      if \p additional is not \c NULL. | 
| Gilles Peskine | 944bc58 | 2019-09-24 14:48:30 +0200 | [diff] [blame] | 488 | *                      This must be less than #MBEDTLS_CTR_DRBG_MAX_INPUT | 
|  | 489 | *                      and less than | 
|  | 490 | *                      #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - \c entropy_len | 
|  | 491 | *                      where \c entropy_len is the entropy length | 
|  | 492 | *                      configured for the context. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 493 | * | 
| Rose Zadik | c9474eb | 2018-03-27 10:58:22 +0100 | [diff] [blame] | 494 | * \return    \c 0 on success. | 
|  | 495 | * \return    #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 496 | *            #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 497 | */ | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 498 | int mbedtls_ctr_drbg_random_with_add(void *p_rng, | 
|  | 499 | unsigned char *output, size_t output_len, | 
|  | 500 | const unsigned char *additional, size_t add_len); | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 501 |  | 
|  | 502 | /** | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 503 | * \brief   This function uses CTR_DRBG to generate random data. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 504 | * | 
| Gilles Peskine | 2d8f069 | 2019-10-01 18:31:28 +0200 | [diff] [blame] | 505 | * This function automatically reseeds if the reseed counter is exceeded | 
|  | 506 | * or prediction resistance is enabled. | 
| Gilles Peskine | f305d92 | 2021-02-09 18:44:18 +0100 | [diff] [blame] | 507 | */ | 
|  | 508 | #if defined(MBEDTLS_THREADING_C) | 
|  | 509 | /** | 
|  | 510 | * \note                When Mbed TLS is built with threading support, | 
|  | 511 | *                      it is safe to call mbedtls_ctr_drbg_random() | 
|  | 512 | *                      from multiple threads. Other operations, including | 
|  | 513 | *                      reseeding, are not thread-safe. | 
|  | 514 | */ | 
|  | 515 | #endif /* MBEDTLS_THREADING_C */ | 
|  | 516 | /** | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 517 | * \param p_rng         The CTR_DRBG context. This must be a pointer to a | 
|  | 518 | *                      #mbedtls_ctr_drbg_context structure. | 
|  | 519 | * \param output        The buffer to fill. | 
| Gilles Peskine | 944bc58 | 2019-09-24 14:48:30 +0200 | [diff] [blame] | 520 | * \param output_len    The length of the buffer in bytes. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 521 | * | 
| Rose Zadik | c9474eb | 2018-03-27 10:58:22 +0100 | [diff] [blame] | 522 | * \return              \c 0 on success. | 
|  | 523 | * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 524 | *                      #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 525 | */ | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 526 | int mbedtls_ctr_drbg_random(void *p_rng, | 
|  | 527 | unsigned char *output, size_t output_len); | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 528 |  | 
| Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 529 | #if defined(MBEDTLS_FS_IO) | 
| Paul Bakker | fc754a9 | 2011-12-05 13:23:51 +0000 | [diff] [blame] | 530 | /** | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 531 | * \brief               This function writes a seed file. | 
| Paul Bakker | fc754a9 | 2011-12-05 13:23:51 +0000 | [diff] [blame] | 532 | * | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 533 | * \param ctx           The CTR_DRBG context. | 
|  | 534 | * \param path          The name of the file. | 
| Paul Bakker | fc754a9 | 2011-12-05 13:23:51 +0000 | [diff] [blame] | 535 | * | 
| Rose Zadik | c9474eb | 2018-03-27 10:58:22 +0100 | [diff] [blame] | 536 | * \return              \c 0 on success. | 
| Rose Zadik | f25eb6e | 2018-04-16 14:51:52 +0100 | [diff] [blame] | 537 | * \return              #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error. | 
| Gilles Peskine | ec51dd1 | 2019-09-30 15:01:02 +0200 | [diff] [blame] | 538 | * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on reseed | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 539 | *                      failure. | 
| Paul Bakker | fc754a9 | 2011-12-05 13:23:51 +0000 | [diff] [blame] | 540 | */ | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 541 | int mbedtls_ctr_drbg_write_seed_file(mbedtls_ctr_drbg_context *ctx, const char *path); | 
| Paul Bakker | fc754a9 | 2011-12-05 13:23:51 +0000 | [diff] [blame] | 542 |  | 
|  | 543 | /** | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 544 | * \brief               This function reads and updates a seed file. The seed | 
|  | 545 | *                      is added to this instance. | 
| Paul Bakker | fc754a9 | 2011-12-05 13:23:51 +0000 | [diff] [blame] | 546 | * | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 547 | * \param ctx           The CTR_DRBG context. | 
|  | 548 | * \param path          The name of the file. | 
| Paul Bakker | fc754a9 | 2011-12-05 13:23:51 +0000 | [diff] [blame] | 549 | * | 
| Rose Zadik | c9474eb | 2018-03-27 10:58:22 +0100 | [diff] [blame] | 550 | * \return              \c 0 on success. | 
|  | 551 | * \return              #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error. | 
| Gilles Peskine | ec51dd1 | 2019-09-30 15:01:02 +0200 | [diff] [blame] | 552 | * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on | 
|  | 553 | *                      reseed failure. | 
|  | 554 | * \return              #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if the existing | 
|  | 555 | *                      seed file is too large. | 
| Paul Bakker | fc754a9 | 2011-12-05 13:23:51 +0000 | [diff] [blame] | 556 | */ | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 557 | int mbedtls_ctr_drbg_update_seed_file(mbedtls_ctr_drbg_context *ctx, const char *path); | 
| Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 558 | #endif /* MBEDTLS_FS_IO */ | 
| Paul Bakker | fc754a9 | 2011-12-05 13:23:51 +0000 | [diff] [blame] | 559 |  | 
| Andrzej Kurek | c470b6b | 2019-01-31 08:20:20 -0500 | [diff] [blame] | 560 | #if defined(MBEDTLS_SELF_TEST) | 
|  | 561 |  | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 562 | /** | 
| Rose Zadik | 2f8163d | 2018-01-25 21:55:14 +0000 | [diff] [blame] | 563 | * \brief               The CTR_DRBG checkup routine. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 564 | * | 
| Rose Zadik | c9474eb | 2018-03-27 10:58:22 +0100 | [diff] [blame] | 565 | * \return              \c 0 on success. | 
|  | 566 | * \return              \c 1 on failure. | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 567 | */ | 
| Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 568 | int mbedtls_ctr_drbg_self_test(int verbose); | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 569 |  | 
| Andrzej Kurek | c470b6b | 2019-01-31 08:20:20 -0500 | [diff] [blame] | 570 | #endif /* MBEDTLS_SELF_TEST */ | 
|  | 571 |  | 
| Paul Bakker | 0e04d0e | 2011-11-27 14:46:59 +0000 | [diff] [blame] | 572 | #ifdef __cplusplus | 
|  | 573 | } | 
|  | 574 | #endif | 
|  | 575 |  | 
|  | 576 | #endif /* ctr_drbg.h */ |