git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/mbedtls/include/mbedtls/ctr_drbg.h

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