git.zerfleddert.de Git - proxmark3-svn/blob - common/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 as the underlying
  12  * block cipher.
  13  */
  14 /*
  15  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  16  *  SPDX-License-Identifier: GPL-2.0
  17  *
  18  *  This program is free software; you can redistribute it and/or modify
  19  *  it under the terms of the GNU General Public License as published by
  20  *  the Free Software Foundation; either version 2 of the License, or
  21  *  (at your option) any later version.
  22  *
  23  *  This program is distributed in the hope that it will be useful,
  24  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  25  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  26  *  GNU General Public License for more details.
  27  *
  28  *  You should have received a copy of the GNU General Public License along
  29  *  with this program; if not, write to the Free Software Foundation, Inc.,
  30  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  31  *
  32  *  This file is part of Mbed TLS (https://tls.mbed.org)
  33  */
  34
  35 #ifndef MBEDTLS_CTR_DRBG_H
  36 #define MBEDTLS_CTR_DRBG_H
  37
  38 #include "aes.h"
  39
  40 #if defined(MBEDTLS_THREADING_C)
  41 #include "threading.h"
  42 #endif
  43
  44 #define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED        -0x0034  /**< The entropy source failed. */
  45 #define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG              -0x0036  /**< The requested random buffer length is too big. */
  46 #define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG                -0x0038  /**< The input (entropy + additional data) is too large. */
  47 #define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR                -0x003A  /**< Read or write error in file. */
  48
  49 #define MBEDTLS_CTR_DRBG_BLOCKSIZE          16 /**< The block size used by the cipher. */
  50 #define MBEDTLS_CTR_DRBG_KEYSIZE            32 /**< The key size used by the cipher. */
  51 #define MBEDTLS_CTR_DRBG_KEYBITS            ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 ) /**< The key size for the DRBG operation, in bits. */
  52 #define MBEDTLS_CTR_DRBG_SEEDLEN            ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE ) /**< The seed length, calculated as (counter + AES key). */
  53
  54 /**
  55  * \name SECTION: Module settings
  56  *
  57  * The configuration options you can set for this module are in this section.
  58  * Either change them in config.h or define them using the compiler command
  59  * line.
  60  * \{
  61  */
  62
  63 #if !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN)
  64 #if defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256)
  65 #define MBEDTLS_CTR_DRBG_ENTROPY_LEN        48
  66 /**< The amount of entropy used per seed by default:
  67  * <ul><li>48 with SHA-512.</li>
  68  * <li>32 with SHA-256.</li></ul>
  69  */
  70 #else
  71 #define MBEDTLS_CTR_DRBG_ENTROPY_LEN        32
  72 /**< Amount of entropy used per seed by default:
  73  * <ul><li>48 with SHA-512.</li>
  74  * <li>32 with SHA-256.</li></ul>
  75  */
  76 #endif
  77 #endif
  78
  79 #if !defined(MBEDTLS_CTR_DRBG_RESEED_INTERVAL)
  80 #define MBEDTLS_CTR_DRBG_RESEED_INTERVAL    10000
  81 /**< The interval before reseed is performed by default. */
  82 #endif
  83
  84 #if !defined(MBEDTLS_CTR_DRBG_MAX_INPUT)
  85 #define MBEDTLS_CTR_DRBG_MAX_INPUT          256
  86 /**< The maximum number of additional input Bytes. */
  87 #endif
  88
  89 #if !defined(MBEDTLS_CTR_DRBG_MAX_REQUEST)
  90 #define MBEDTLS_CTR_DRBG_MAX_REQUEST        1024
  91 /**< The maximum number of requested Bytes per call. */
  92 #endif
  93
  94 #if !defined(MBEDTLS_CTR_DRBG_MAX_SEED_INPUT)
  95 #define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT     384
  96 /**< The maximum size of seed or reseed buffer. */
  97 #endif
  98
  99 /* \} name SECTION: Module settings */
 100
 101 #define MBEDTLS_CTR_DRBG_PR_OFF             0
 102 /**< Prediction resistance is disabled. */
 103 #define MBEDTLS_CTR_DRBG_PR_ON              1
 104 /**< Prediction resistance is enabled. */
 105
 106 #ifdef __cplusplus
 107 extern "C" {
 108 #endif
 109
 110 /**
 111  * \brief          The CTR_DRBG context structure.
 112  */
 113 typedef struct mbedtls_ctr_drbg_context
 114 {
 115     unsigned char counter[16];  /*!< The counter (V). */
 116     int reseed_counter;         /*!< The reseed counter. */
 117     int prediction_resistance;  /*!< This determines whether prediction
 118                                      resistance is enabled, that is
 119                                      whether to systematically reseed before
 120                                      each random generation. */
 121     size_t entropy_len;         /*!< The amount of entropy grabbed on each
 122                                      seed or reseed operation. */
 123     int reseed_interval;        /*!< The reseed interval. */
 124
 125     mbedtls_aes_context aes_ctx;        /*!< The AES context. */
 126
 127     /*
 128      * Callbacks (Entropy)
 129      */
 130     int (*f_entropy)(void *, unsigned char *, size_t);
 131                                 /*!< The entropy callback function. */
 132
 133     void *p_entropy;            /*!< The context for the entropy function. */
 134
 135 #if defined(MBEDTLS_THREADING_C)
 136     mbedtls_threading_mutex_t mutex;
 137 #endif
 138 }
 139 mbedtls_ctr_drbg_context;
 140
 141 /**
 142  * \brief               This function initializes the CTR_DRBG context,
 143  *                      and prepares it for mbedtls_ctr_drbg_seed()
 144  *                      or mbedtls_ctr_drbg_free().
 145  *
 146  * \param ctx           The CTR_DRBG context to initialize.
 147  */
 148 void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx );
 149
 150 /**
 151  * \brief               This function seeds and sets up the CTR_DRBG
 152  *                      entropy source for future reseeds.
 153  *
 154  * \note Personalization data can be provided in addition to the more generic
 155  *       entropy source, to make this instantiation as unique as possible.
 156  *
 157  * \param ctx           The CTR_DRBG context to seed.
 158  * \param f_entropy     The entropy callback, taking as arguments the
 159  *                      \p p_entropy context, the buffer to fill, and the
 160                         length of the buffer.
 161  * \param p_entropy     The entropy context.
 162  * \param custom        Personalization data, that is device-specific
 163                         identifiers. Can be NULL.
 164  * \param len           The length of the personalization data.
 165  *
 166  * \return              \c 0 on success.
 167  * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
 168  */
 169 int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx,
 170                    int (*f_entropy)(void *, unsigned char *, size_t),
 171                    void *p_entropy,
 172                    const unsigned char *custom,
 173                    size_t len );
 174
 175 /**
 176  * \brief               This function clears CTR_CRBG context data.
 177  *
 178  * \param ctx           The CTR_DRBG context to clear.
 179  */
 180 void mbedtls_ctr_drbg_free( mbedtls_ctr_drbg_context *ctx );
 181
 182 /**
 183  * \brief               This function turns prediction resistance on or off.
 184  *                      The default value is off.
 185  *
 186  * \note                If enabled, entropy is gathered at the beginning of
 187  *                      every call to mbedtls_ctr_drbg_random_with_add().
 188  *                      Only use this if your entropy source has sufficient
 189  *                      throughput.
 190  *
 191  * \param ctx           The CTR_DRBG context.
 192  * \param resistance    #MBEDTLS_CTR_DRBG_PR_ON or #MBEDTLS_CTR_DRBG_PR_OFF.
 193  */
 194 void mbedtls_ctr_drbg_set_prediction_resistance( mbedtls_ctr_drbg_context *ctx,
 195                                          int resistance );
 196
 197 /**
 198  * \brief               This function sets the amount of entropy grabbed on each
 199  *                      seed or reseed. The default value is
 200  *                      #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
 201  *
 202  * \param ctx           The CTR_DRBG context.
 203  * \param len           The amount of entropy to grab.
 204  */
 205 void mbedtls_ctr_drbg_set_entropy_len( mbedtls_ctr_drbg_context *ctx,
 206                                size_t len );
 207
 208 /**
 209  * \brief               This function sets the reseed interval.
 210  *                      The default value is #MBEDTLS_CTR_DRBG_RESEED_INTERVAL.
 211  *
 212  * \param ctx           The CTR_DRBG context.
 213  * \param interval      The reseed interval.
 214  */
 215 void mbedtls_ctr_drbg_set_reseed_interval( mbedtls_ctr_drbg_context *ctx,
 216                                    int interval );
 217
 218 /**
 219  * \brief               This function reseeds the CTR_DRBG context, that is
 220  *                      extracts data from the entropy source.
 221  *
 222  * \param ctx           The CTR_DRBG context.
 223  * \param additional    Additional data to add to the state. Can be NULL.
 224  * \param len           The length of the additional data.
 225  *
 226  * \return              \c 0 on success.
 227  * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
 228  */
 229 int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx,
 230                      const unsigned char *additional, size_t len );
 231
 232 /**
 233  * \brief              This function updates the state of the CTR_DRBG context.
 234  *
 235  * \note               If \p add_len is greater than
 236  *                     #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, only the first
 237  *                     #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used.
 238  *                     The remaining Bytes are silently discarded.
 239  *
 240  * \param ctx          The CTR_DRBG context.
 241  * \param additional   The data to update the state with.
 242  * \param add_len      Length of \p additional data.
 243  *
 244  */
 245 void mbedtls_ctr_drbg_update( mbedtls_ctr_drbg_context *ctx,
 246                       const unsigned char *additional, size_t add_len );
 247
 248 /**
 249  * \brief   This function updates a CTR_DRBG instance with additional
 250  *          data and uses it to generate random data.
 251  *
 252  * \note    The function automatically reseeds if the reseed counter is exceeded.
 253  *
 254  * \param p_rng         The CTR_DRBG context. This must be a pointer to a
 255  *                      #mbedtls_ctr_drbg_context structure.
 256  * \param output        The buffer to fill.
 257  * \param output_len    The length of the buffer.
 258  * \param additional    Additional data to update. Can be NULL.
 259  * \param add_len       The length of the additional data.
 260  *
 261  * \return    \c 0 on success.
 262  * \return    #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
 263  *            #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
 264  */
 265 int mbedtls_ctr_drbg_random_with_add( void *p_rng,
 266                               unsigned char *output, size_t output_len,
 267                               const unsigned char *additional, size_t add_len );
 268
 269 /**
 270  * \brief   This function uses CTR_DRBG to generate random data.
 271  *
 272  * \note    The function automatically reseeds if the reseed counter is exceeded.
 273  *
 274  * \param p_rng         The CTR_DRBG context. This must be a pointer to a
 275  *                      #mbedtls_ctr_drbg_context structure.
 276  * \param output        The buffer to fill.
 277  * \param output_len    The length of the buffer.
 278  *
 279  * \return              \c 0 on success.
 280  * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
 281  *                      #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
 282  */
 283 int mbedtls_ctr_drbg_random( void *p_rng,
 284                      unsigned char *output, size_t output_len );
 285
 286 #if defined(MBEDTLS_FS_IO)
 287 /**
 288  * \brief               This function writes a seed file.
 289  *
 290  * \param ctx           The CTR_DRBG context.
 291  * \param path          The name of the file.
 292  *
 293  * \return              \c 0 on success.
 294  * \return              #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
 295  * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on
 296  *                      failure.
 297  */
 298 int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
 299
 300 /**
 301  * \brief               This function reads and updates a seed file. The seed
 302  *                      is added to this instance.
 303  *
 304  * \param ctx           The CTR_DRBG context.
 305  * \param path          The name of the file.
 306  *
 307  * \return              \c 0 on success.
 308  * \return              #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
 309  * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
 310  *                      #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG on failure.
 311  */
 312 int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
 313 #endif /* MBEDTLS_FS_IO */
 314
 315 /**
 316  * \brief               The CTR_DRBG checkup routine.
 317  *
 318  * \return              \c 0 on success.
 319  * \return              \c 1 on failure.
 320  */
 321 int mbedtls_ctr_drbg_self_test( int verbose );
 322
 323 /* Internal functions (do not call directly) */
 324 int mbedtls_ctr_drbg_seed_entropy_len( mbedtls_ctr_drbg_context *,
 325                                int (*)(void *, unsigned char *, size_t), void *,
 326                                const unsigned char *, size_t, size_t );
 327
 328 #ifdef __cplusplus
 329 }
 330 #endif
 331
 332 #endif /* ctr_drbg.h */