sdk/include/reactos/libs/mbedtls/hmac_drbg.h

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