1 /** 2 * \file ctr_drbg.h 3 * 4 * \brief This file contains CTR_DRBG definitions and functions. 5 * 6 * CTR_DRBG is a standardized way of building a PRNG from a block-cipher 7 * in counter mode operation, as defined in <em>NIST SP 800-90A: 8 * Recommendation for Random Number Generation Using Deterministic Random 9 * Bit Generators</em>. 10 * 11 * The Mbed TLS implementation of CTR_DRBG uses AES-256 (default) or AES-128 12 * as the underlying block cipher. 13 * 14 * \warning Using 128-bit keys for CTR_DRBG limits the security of generated 15 * keys and operations that use random values generated to 128-bit security. 16 */ 17 /* 18 * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved 19 * SPDX-License-Identifier: Apache-2.0 20 * 21 * Licensed under the Apache License, Version 2.0 (the "License"); you may 22 * not use this file except in compliance with the License. 23 * You may obtain a copy of the License at 24 * 25 * http://www.apache.org/licenses/LICENSE-2.0 26 * 27 * Unless required by applicable law or agreed to in writing, software 28 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 29 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 30 * See the License for the specific language governing permissions and 31 * limitations under the License. 32 * 33 * This file is part of Mbed TLS (https://tls.mbed.org) 34 */ 35 36 #ifndef MBEDTLS_CTR_DRBG_H 37 #define MBEDTLS_CTR_DRBG_H 38 39 #include "aes.h" 40 41 #if defined(MBEDTLS_THREADING_C) 42 #include "threading.h" 43 #endif 44 45 #define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034 /**< The entropy source failed. */ 46 #define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036 /**< The requested random buffer length is too big. */ 47 #define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038 /**< The input (entropy + additional data) is too large. */ 48 #define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A /**< Read or write error in file. */ 49 50 #define MBEDTLS_CTR_DRBG_BLOCKSIZE 16 /**< The block size used by the cipher. */ 51 52 #if defined(MBEDTLS_CTR_DRBG_USE_128_BIT_KEY) 53 #define MBEDTLS_CTR_DRBG_KEYSIZE 16 /**< The key size used by the cipher (compile-time choice: 128 bits). */ 54 #else 55 #define MBEDTLS_CTR_DRBG_KEYSIZE 32 /**< The key size used by the cipher (compile-time choice: 256 bits). */ 56 #endif 57 58 #define MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 ) /**< The key size for the DRBG operation, in bits. */ 59 #define MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE ) /**< The seed length, calculated as (counter + AES key). */ 60 61 /** 62 * \name SECTION: Module settings 63 * 64 * The configuration options you can set for this module are in this section. 65 * Either change them in config.h or define them using the compiler command 66 * line. 67 * \{ 68 */ 69 70 #if !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN) 71 #if defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256) 72 #define MBEDTLS_CTR_DRBG_ENTROPY_LEN 48 73 /**< The amount of entropy used per seed by default: 74 * <ul><li>48 with SHA-512.</li> 75 * <li>32 with SHA-256.</li></ul> 76 */ 77 #else 78 #define MBEDTLS_CTR_DRBG_ENTROPY_LEN 32 79 /**< Amount of entropy used per seed by default: 80 * <ul><li>48 with SHA-512.</li> 81 * <li>32 with SHA-256.</li></ul> 82 */ 83 #endif 84 #endif 85 86 #if !defined(MBEDTLS_CTR_DRBG_RESEED_INTERVAL) 87 #define MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000 88 /**< The interval before reseed is performed by default. */ 89 #endif 90 91 #if !defined(MBEDTLS_CTR_DRBG_MAX_INPUT) 92 #define MBEDTLS_CTR_DRBG_MAX_INPUT 256 93 /**< The maximum number of additional input Bytes. */ 94 #endif 95 96 #if !defined(MBEDTLS_CTR_DRBG_MAX_REQUEST) 97 #define MBEDTLS_CTR_DRBG_MAX_REQUEST 1024 98 /**< The maximum number of requested Bytes per call. */ 99 #endif 100 101 #if !defined(MBEDTLS_CTR_DRBG_MAX_SEED_INPUT) 102 #define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384 103 /**< The maximum size of seed or reseed buffer. */ 104 #endif 105 106 /* \} name SECTION: Module settings */ 107 108 #define MBEDTLS_CTR_DRBG_PR_OFF 0 109 /**< Prediction resistance is disabled. */ 110 #define MBEDTLS_CTR_DRBG_PR_ON 1 111 /**< Prediction resistance is enabled. */ 112 113 #ifdef __cplusplus 114 extern "C" { 115 #endif 116 117 /** 118 * \brief The CTR_DRBG context structure. 119 */ 120 typedef struct mbedtls_ctr_drbg_context 121 { 122 unsigned char counter[16]; /*!< The counter (V). */ 123 int reseed_counter; /*!< The reseed counter. */ 124 int prediction_resistance; /*!< This determines whether prediction 125 resistance is enabled, that is 126 whether to systematically reseed before 127 each random generation. */ 128 size_t entropy_len; /*!< The amount of entropy grabbed on each 129 seed or reseed operation. */ 130 int reseed_interval; /*!< The reseed interval. */ 131 132 mbedtls_aes_context aes_ctx; /*!< The AES context. */ 133 134 /* 135 * Callbacks (Entropy) 136 */ 137 int (*f_entropy)(void *, unsigned char *, size_t); 138 /*!< The entropy callback function. */ 139 140 void *p_entropy; /*!< The context for the entropy function. */ 141 142 #if defined(MBEDTLS_THREADING_C) 143 mbedtls_threading_mutex_t mutex; 144 #endif 145 } 146 mbedtls_ctr_drbg_context; 147 148 /** 149 * \brief This function initializes the CTR_DRBG context, 150 * and prepares it for mbedtls_ctr_drbg_seed() 151 * or mbedtls_ctr_drbg_free(). 152 * 153 * \param ctx The CTR_DRBG context to initialize. 154 */ 155 void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx ); 156 157 /** 158 * \brief This function seeds and sets up the CTR_DRBG 159 * entropy source for future reseeds. 160 * 161 * \note Personalization data can be provided in addition to the more generic 162 * entropy source, to make this instantiation as unique as possible. 163 * 164 * \param ctx The CTR_DRBG context to seed. 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 * \param p_entropy The entropy context. 169 * \param custom Personalization data, that is device-specific 170 identifiers. Can be NULL. 171 * \param len The length of the personalization data. 172 * 173 * \return \c 0 on success. 174 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure. 175 */ 176 int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx, 177 int (*f_entropy)(void *, unsigned char *, size_t), 178 void *p_entropy, 179 const unsigned char *custom, 180 size_t len ); 181 182 /** 183 * \brief This function clears CTR_CRBG context data. 184 * 185 * \param ctx The CTR_DRBG context to clear. 186 */ 187 void mbedtls_ctr_drbg_free( mbedtls_ctr_drbg_context *ctx ); 188 189 /** 190 * \brief This function turns prediction resistance on or off. 191 * The default value is off. 192 * 193 * \note If enabled, entropy is gathered at the beginning of 194 * every call to mbedtls_ctr_drbg_random_with_add(). 195 * Only use this if your entropy source has sufficient 196 * throughput. 197 * 198 * \param ctx The CTR_DRBG context. 199 * \param resistance #MBEDTLS_CTR_DRBG_PR_ON or #MBEDTLS_CTR_DRBG_PR_OFF. 200 */ 201 void mbedtls_ctr_drbg_set_prediction_resistance( mbedtls_ctr_drbg_context *ctx, 202 int resistance ); 203 204 /** 205 * \brief This function sets the amount of entropy grabbed on each 206 * seed or reseed. The default value is 207 * #MBEDTLS_CTR_DRBG_ENTROPY_LEN. 208 * 209 * \param ctx The CTR_DRBG context. 210 * \param len The amount of entropy to grab. 211 */ 212 void mbedtls_ctr_drbg_set_entropy_len( mbedtls_ctr_drbg_context *ctx, 213 size_t len ); 214 215 /** 216 * \brief This function sets the reseed interval. 217 * The default value is #MBEDTLS_CTR_DRBG_RESEED_INTERVAL. 218 * 219 * \param ctx The CTR_DRBG context. 220 * \param interval The reseed interval. 221 */ 222 void mbedtls_ctr_drbg_set_reseed_interval( mbedtls_ctr_drbg_context *ctx, 223 int interval ); 224 225 /** 226 * \brief This function reseeds the CTR_DRBG context, that is 227 * extracts data from the entropy source. 228 * 229 * \param ctx The CTR_DRBG context. 230 * \param additional Additional data to add to the state. Can be NULL. 231 * \param len The length of the additional data. 232 * 233 * \return \c 0 on success. 234 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure. 235 */ 236 int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx, 237 const unsigned char *additional, size_t len ); 238 239 /** 240 * \brief This function updates the state of the CTR_DRBG context. 241 * 242 * \param ctx The CTR_DRBG context. 243 * \param additional The data to update the state with. 244 * \param add_len Length of \p additional in bytes. This must be at 245 * most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT. 246 * 247 * \return \c 0 on success. 248 * \return #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if 249 * \p add_len is more than 250 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT. 251 * \return An error from the underlying AES cipher on failure. 252 */ 253 int mbedtls_ctr_drbg_update_ret( mbedtls_ctr_drbg_context *ctx, 254 const unsigned char *additional, 255 size_t add_len ); 256 257 /** 258 * \brief This function updates a CTR_DRBG instance with additional 259 * data and uses it to generate random data. 260 * 261 * \note The function automatically reseeds if the reseed counter is exceeded. 262 * 263 * \param p_rng The CTR_DRBG context. This must be a pointer to a 264 * #mbedtls_ctr_drbg_context structure. 265 * \param output The buffer to fill. 266 * \param output_len The length of the buffer. 267 * \param additional Additional data to update. Can be NULL. 268 * \param add_len The length of the additional data. 269 * 270 * \return \c 0 on success. 271 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or 272 * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure. 273 */ 274 int mbedtls_ctr_drbg_random_with_add( void *p_rng, 275 unsigned char *output, size_t output_len, 276 const unsigned char *additional, size_t add_len ); 277 278 /** 279 * \brief This function uses CTR_DRBG to generate random data. 280 * 281 * \note The function automatically reseeds if the reseed counter is exceeded. 282 * 283 * \param p_rng The CTR_DRBG context. This must be a pointer to a 284 * #mbedtls_ctr_drbg_context structure. 285 * \param output The buffer to fill. 286 * \param output_len The length of the buffer. 287 * 288 * \return \c 0 on success. 289 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or 290 * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure. 291 */ 292 int mbedtls_ctr_drbg_random( void *p_rng, 293 unsigned char *output, size_t output_len ); 294 295 296 #if ! defined(MBEDTLS_DEPRECATED_REMOVED) 297 #if defined(MBEDTLS_DEPRECATED_WARNING) 298 #define MBEDTLS_DEPRECATED __attribute__((deprecated)) 299 #else 300 #define MBEDTLS_DEPRECATED 301 #endif 302 /** 303 * \brief This function updates the state of the CTR_DRBG context. 304 * 305 * \deprecated Superseded by mbedtls_ctr_drbg_update_ret() 306 * in 2.16.0. 307 * 308 * \note If \p add_len is greater than 309 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, only the first 310 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used. 311 * The remaining Bytes are silently discarded. 312 * 313 * \param ctx The CTR_DRBG context. 314 * \param additional The data to update the state with. 315 * \param add_len Length of \p additional data. 316 */ 317 MBEDTLS_DEPRECATED void mbedtls_ctr_drbg_update( 318 mbedtls_ctr_drbg_context *ctx, 319 const unsigned char *additional, 320 size_t add_len ); 321 #undef MBEDTLS_DEPRECATED 322 #endif /* !MBEDTLS_DEPRECATED_REMOVED */ 323 324 #if defined(MBEDTLS_FS_IO) 325 /** 326 * \brief This function writes a seed file. 327 * 328 * \param ctx The CTR_DRBG context. 329 * \param path The name of the file. 330 * 331 * \return \c 0 on success. 332 * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error. 333 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on 334 * failure. 335 */ 336 int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path ); 337 338 /** 339 * \brief This function reads and updates a seed file. The seed 340 * is added to this instance. 341 * 342 * \param ctx The CTR_DRBG context. 343 * \param path The name of the file. 344 * 345 * \return \c 0 on success. 346 * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error. 347 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or 348 * #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG on failure. 349 */ 350 int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path ); 351 #endif /* MBEDTLS_FS_IO */ 352 353 /** 354 * \brief The CTR_DRBG checkup routine. 355 * 356 * \return \c 0 on success. 357 * \return \c 1 on failure. 358 */ 359 int mbedtls_ctr_drbg_self_test( int verbose ); 360 361 /* Internal functions (do not call directly) */ 362 int mbedtls_ctr_drbg_seed_entropy_len( mbedtls_ctr_drbg_context *, 363 int (*)(void *, unsigned char *, size_t), void *, 364 const unsigned char *, size_t, size_t ); 365 366 #ifdef __cplusplus 367 } 368 #endif 369 370 #endif /* ctr_drbg.h */ 371