third_party/mbedtls/repo/include/mbedtls/ctr_drbg.h

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