extlibs/mbedtls/mbedtls/include/mbedtls/hmac_drbg.h

   1 /**
   2  * \file hmac_drbg.h
   3  *
   4  * \brief HMAC_DRBG (NIST SP 800-90A)
   5  *
   6  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
   7  *  SPDX-License-Identifier: Apache-2.0
   8  *
   9  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
  10  *  not use this file except in compliance with the License.
  11  *  You may obtain a copy of the License at
  12  *
  13  *  http://www.apache.org/licenses/LICENSE-2.0
  14  *
  15  *  Unless required by applicable law or agreed to in writing, software
  16  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  17  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  *  See the License for the specific language governing permissions and
  19  *  limitations under the License.
  20  *
  21  *  This file is part of mbed TLS (https://tls.mbed.org)
  22  */
  23 #ifndef MBEDTLS_HMAC_DRBG_H
  24 #define MBEDTLS_HMAC_DRBG_H
  25
  26 #include "md.h"
  27
  28 #if defined(MBEDTLS_THREADING_C)
  29 #include "mbedtls/threading.h"
  30 #endif
  31
  32 /*
  33  * Error codes
  34  */
  35 #define MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG              -0x0003  /**< Too many random requested in single call. */
  36 #define MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG                -0x0005  /**< Input too large (Entropy + additional). */
  37 #define MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR                -0x0007  /**< Read/write error in file. */
  38 #define MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED        -0x0009  /**< The entropy source failed. */
  39
  40 /**
  41  * \name SECTION: Module settings
  42  *
  43  * The configuration options you can set for this module are in this section.
  44  * Either change them in config.h or define them on the compiler command line.
  45  * \{
  46  */
  47
  48 #if !defined(MBEDTLS_HMAC_DRBG_RESEED_INTERVAL)
  49 #define MBEDTLS_HMAC_DRBG_RESEED_INTERVAL   10000   /**< Interval before reseed is performed by default */
  50 #endif
  51
  52 #if !defined(MBEDTLS_HMAC_DRBG_MAX_INPUT)
  53 #define MBEDTLS_HMAC_DRBG_MAX_INPUT         256     /**< Maximum number of additional input bytes */
  54 #endif
  55
  56 #if !defined(MBEDTLS_HMAC_DRBG_MAX_REQUEST)
  57 #define MBEDTLS_HMAC_DRBG_MAX_REQUEST       1024    /**< Maximum number of requested bytes per call */
  58 #endif
  59
  60 #if !defined(MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT)
  61 #define MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT    384     /**< Maximum size of (re)seed buffer */
  62 #endif
  63
  64 /* \} name SECTION: Module settings */
  65
  66 #define MBEDTLS_HMAC_DRBG_PR_OFF   0   /**< No prediction resistance       */
  67 #define MBEDTLS_HMAC_DRBG_PR_ON    1   /**< Prediction resistance enabled  */
  68
  69 #ifdef __cplusplus
  70 extern "C" {
  71 #endif
  72
  73 /**
  74  * HMAC_DRBG context.
  75  */
  76 typedef struct
  77 {
  78     /* Working state: the key K is not stored explicitely,
  79      * but is implied by the HMAC context */
  80     mbedtls_md_context_t md_ctx;                    /*!< HMAC context (inc. K)  */
  81     unsigned char V[MBEDTLS_MD_MAX_SIZE];  /*!< V in the spec          */
  82     int reseed_counter;                     /*!< reseed counter         */
  83
  84     /* Administrative state */
  85     size_t entropy_len;         /*!< entropy bytes grabbed on each (re)seed */
  86     int prediction_resistance;  /*!< enable prediction resistance (Automatic
  87                                      reseed before every random generation) */
  88     int reseed_interval;        /*!< reseed interval   */
  89
  90     /* Callbacks */
  91     int (*f_entropy)(void *, unsigned char *, size_t); /*!< entropy function */
  92     void *p_entropy;            /*!< context for the entropy function        */
  93
  94 #if defined(MBEDTLS_THREADING_C)
  95     mbedtls_threading_mutex_t mutex;
  96 #endif
  97 } mbedtls_hmac_drbg_context;
  98
  99 /**
 100  * \brief               HMAC_DRBG context initialization
 101  *                      Makes the context ready for mbedtls_hmac_drbg_seed(),
 102  *                      mbedtls_hmac_drbg_seed_buf() or
 103  *                      mbedtls_hmac_drbg_free().
 104  *
 105  * \param ctx           HMAC_DRBG context to be initialized
 106  */
 107 void mbedtls_hmac_drbg_init( mbedtls_hmac_drbg_context *ctx );
 108
 109 /**
 110  * \brief               HMAC_DRBG initial seeding
 111  *                      Seed and setup entropy source for future reseeds.
 112  *
 113  * \param ctx           HMAC_DRBG context to be seeded
 114  * \param md_info       MD algorithm to use for HMAC_DRBG
 115  * \param f_entropy     Entropy callback (p_entropy, buffer to fill, buffer
 116  *                      length)
 117  * \param p_entropy     Entropy context
 118  * \param custom        Personalization data (Device specific identifiers)
 119  *                      (Can be NULL)
 120  * \param len           Length of personalization data
 121  *
 122  * \note                The "security strength" as defined by NIST is set to:
 123  *                      128 bits if md_alg is SHA-1,
 124  *                      192 bits if md_alg is SHA-224,
 125  *                      256 bits if md_alg is SHA-256 or higher.
 126  *                      Note that SHA-256 is just as efficient as SHA-224.
 127  *
 128  * \return              0 if successful, or
 129  *                      MBEDTLS_ERR_MD_BAD_INPUT_DATA, or
 130  *                      MBEDTLS_ERR_MD_ALLOC_FAILED, or
 131  *                      MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED.
 132  */
 133 int mbedtls_hmac_drbg_seed( mbedtls_hmac_drbg_context *ctx,
 134                     const mbedtls_md_info_t * md_info,
 135                     int (*f_entropy)(void *, unsigned char *, size_t),
 136                     void *p_entropy,
 137                     const unsigned char *custom,
 138                     size_t len );
 139
 140 /**
 141  * \brief               Initilisation of simpified HMAC_DRBG (never reseeds).
 142  *                      (For use with deterministic ECDSA.)
 143  *
 144  * \param ctx           HMAC_DRBG context to be initialised
 145  * \param md_info       MD algorithm to use for HMAC_DRBG
 146  * \param data          Concatenation of entropy string and additional data
 147  * \param data_len      Length of data in bytes
 148  *
 149  * \return              0 if successful, or
 150  *                      MBEDTLS_ERR_MD_BAD_INPUT_DATA, or
 151  *                      MBEDTLS_ERR_MD_ALLOC_FAILED.
 152  */
 153 int mbedtls_hmac_drbg_seed_buf( mbedtls_hmac_drbg_context *ctx,
 154                         const mbedtls_md_info_t * md_info,
 155                         const unsigned char *data, size_t data_len );
 156
 157 /**
 158  * \brief               Enable / disable prediction resistance (Default: Off)
 159  *
 160  * Note: If enabled, entropy is used for ctx->entropy_len before each call!
 161  *       Only use this if you have ample supply of good entropy!
 162  *
 163  * \param ctx           HMAC_DRBG context
 164  * \param resistance    MBEDTLS_HMAC_DRBG_PR_ON or MBEDTLS_HMAC_DRBG_PR_OFF
 165  */
 166 void mbedtls_hmac_drbg_set_prediction_resistance( mbedtls_hmac_drbg_context *ctx,
 167                                           int resistance );
 168
 169 /**
 170  * \brief               Set the amount of entropy grabbed on each reseed
 171  *                      (Default: given by the security strength, which
 172  *                      depends on the hash used, see \c mbedtls_hmac_drbg_init() )
 173  *
 174  * \param ctx           HMAC_DRBG context
 175  * \param len           Amount of entropy to grab, in bytes
 176  */
 177 void mbedtls_hmac_drbg_set_entropy_len( mbedtls_hmac_drbg_context *ctx,
 178                                 size_t len );
 179
 180 /**
 181  * \brief               Set the reseed interval
 182  *                      (Default: MBEDTLS_HMAC_DRBG_RESEED_INTERVAL)
 183  *
 184  * \param ctx           HMAC_DRBG context
 185  * \param interval      Reseed interval
 186  */
 187 void mbedtls_hmac_drbg_set_reseed_interval( mbedtls_hmac_drbg_context *ctx,
 188                                     int interval );
 189
 190 /**
 191  * \brief               HMAC_DRBG update state
 192  *
 193  * \param ctx           HMAC_DRBG context
 194  * \param additional    Additional data to update state with, or NULL
 195  * \param add_len       Length of additional data, or 0
 196  *
 197  * \note                Additional data is optional, pass NULL and 0 as second
 198  *                      third argument if no additional data is being used.
 199  */
 200 void mbedtls_hmac_drbg_update( mbedtls_hmac_drbg_context *ctx,
 201                        const unsigned char *additional, size_t add_len );
 202
 203 /**
 204  * \brief               HMAC_DRBG reseeding (extracts data from entropy source)
 205  *
 206  * \param ctx           HMAC_DRBG context
 207  * \param additional    Additional data to add to state (Can be NULL)
 208  * \param len           Length of additional data
 209  *
 210  * \return              0 if successful, or
 211  *                      MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
 212  */
 213 int mbedtls_hmac_drbg_reseed( mbedtls_hmac_drbg_context *ctx,
 214                       const unsigned char *additional, size_t len );
 215
 216 /**
 217  * \brief               HMAC_DRBG generate random with additional update input
 218  *
 219  * Note: Automatically reseeds if reseed_counter is reached or PR is enabled.
 220  *
 221  * \param p_rng         HMAC_DRBG context
 222  * \param output        Buffer to fill
 223  * \param output_len    Length of the buffer
 224  * \param additional    Additional data to update with (can be NULL)
 225  * \param add_len       Length of additional data (can be 0)
 226  *
 227  * \return              0 if successful, or
 228  *                      MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED, or
 229  *                      MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG, or
 230  *                      MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG.
 231  */
 232 int mbedtls_hmac_drbg_random_with_add( void *p_rng,
 233                                unsigned char *output, size_t output_len,
 234                                const unsigned char *additional,
 235                                size_t add_len );
 236
 237 /**
 238  * \brief               HMAC_DRBG generate random
 239  *
 240  * Note: Automatically reseeds if reseed_counter is reached or PR is enabled.
 241  *
 242  * \param p_rng         HMAC_DRBG context
 243  * \param output        Buffer to fill
 244  * \param out_len       Length of the buffer
 245  *
 246  * \return              0 if successful, or
 247  *                      MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED, or
 248  *                      MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG
 249  */
 250 int mbedtls_hmac_drbg_random( void *p_rng, unsigned char *output, size_t out_len );
 251
 252 /**
 253  * \brief               Free an HMAC_DRBG context
 254  *
 255  * \param ctx           HMAC_DRBG context to free.
 256  */
 257 void mbedtls_hmac_drbg_free( mbedtls_hmac_drbg_context *ctx );
 258
 259 #if defined(MBEDTLS_FS_IO)
 260 /**
 261  * \brief               Write a seed file
 262  *
 263  * \param ctx           HMAC_DRBG context
 264  * \param path          Name of the file
 265  *
 266  * \return              0 if successful, 1 on file error, or
 267  *                      MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
 268  */
 269 int mbedtls_hmac_drbg_write_seed_file( mbedtls_hmac_drbg_context *ctx, const char *path );
 270
 271 /**
 272  * \brief               Read and update a seed file. Seed is added to this
 273  *                      instance
 274  *
 275  * \param ctx           HMAC_DRBG context
 276  * \param path          Name of the file
 277  *
 278  * \return              0 if successful, 1 on file error,
 279  *                      MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED or
 280  *                      MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG
 281  */
 282 int mbedtls_hmac_drbg_update_seed_file( mbedtls_hmac_drbg_context *ctx, const char *path );
 283 #endif /* MBEDTLS_FS_IO */
 284
 285
 286 #if defined(MBEDTLS_SELF_TEST)
 287 /**
 288  * \brief               Checkup routine
 289  *
 290  * \return              0 if successful, or 1 if the test failed
 291  */
 292 int mbedtls_hmac_drbg_self_test( int verbose );
 293 #endif
 294
 295 #ifdef __cplusplus
 296 }
 297 #endif
 298
 299 #endif /* hmac_drbg.h */