hmac_drbg.h

00001 /**
00002  * \file hmac_drbg.h
00003  *
00004  * \brief The HMAC_DRBG pseudorandom generator.
00005  *
00006  * This module implements the HMAC_DRBG pseudorandom generator described
00007  * in <em>NIST SP 800-90A: Recommendation for Random Number Generation Using
00008  * Deterministic Random Bit Generators</em>.
00009  */
00010 /*
00011  *  Copyright (C) 2006-2019, ARM Limited, All Rights Reserved
00012  *  SPDX-License-Identifier: Apache-2.0
00013  *
00014  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00015  *  not use this file except in compliance with the License.
00016  *  You may obtain a copy of the License at
00017  *
00018  *  http://www.apache.org/licenses/LICENSE-2.0
00019  *
00020  *  Unless required by applicable law or agreed to in writing, software
00021  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00022  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00023  *  See the License for the specific language governing permissions and
00024  *  limitations under the License.
00025  *
00026  *  This file is part of mbed TLS (https://tls.mbed.org)
00027  */
00028 #ifndef MBEDTLS_HMAC_DRBG_H
00029 #define MBEDTLS_HMAC_DRBG_H
00030 
00031 #if !defined(MBEDTLS_CONFIG_FILE)
00032 #include "mbedtls/config.h"
00033 #else
00034 #include MBEDTLS_CONFIG_FILE
00035 #endif
00036 
00037 #include "mbedtls/md.h"
00038 
00039 #if defined(MBEDTLS_THREADING_C)
00040 #include "mbedtls/threading.h"
00041 #endif
00042 
00043 /*
00044  * Error codes
00045  */
00046 #define MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG              -0x0003  /**< Too many random requested in single call. */
00047 #define MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG                -0x0005  /**< Input too large (Entropy + additional). */
00048 #define MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR                -0x0007  /**< Read/write error in file. */
00049 #define MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED        -0x0009  /**< The entropy source failed. */
00050 
00051 /**
00052  * \name SECTION: Module settings
00053  *
00054  * The configuration options you can set for this module are in this section.
00055  * Either change them in config.h or define them on the compiler command line.
00056  * \{
00057  */
00058 
00059 #if !defined(MBEDTLS_HMAC_DRBG_RESEED_INTERVAL)
00060 #define MBEDTLS_HMAC_DRBG_RESEED_INTERVAL   10000   /**< Interval before reseed is performed by default */
00061 #endif
00062 
00063 #if !defined(MBEDTLS_HMAC_DRBG_MAX_INPUT)
00064 #define MBEDTLS_HMAC_DRBG_MAX_INPUT         256     /**< Maximum number of additional input bytes */
00065 #endif
00066 
00067 #if !defined(MBEDTLS_HMAC_DRBG_MAX_REQUEST)
00068 #define MBEDTLS_HMAC_DRBG_MAX_REQUEST       1024    /**< Maximum number of requested bytes per call */
00069 #endif
00070 
00071 #if !defined(MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT)
00072 #define MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT    384     /**< Maximum size of (re)seed buffer */
00073 #endif
00074 
00075 /* \} name SECTION: Module settings */
00076 
00077 #define MBEDTLS_HMAC_DRBG_PR_OFF   0   /**< No prediction resistance       */
00078 #define MBEDTLS_HMAC_DRBG_PR_ON    1   /**< Prediction resistance enabled  */
00079 
00080 #ifdef __cplusplus
00081 extern "C" {
00082 #endif
00083 
00084 /**
00085  * HMAC_DRBG context.
00086  */
00087 typedef struct mbedtls_hmac_drbg_context
00088 {
00089     /* Working state: the key K is not stored explicitly,
00090      * but is implied by the HMAC context */
00091     mbedtls_md_context_t md_ctx ;                    /*!< HMAC context (inc. K)  */
00092     unsigned char V [MBEDTLS_MD_MAX_SIZE];  /*!< V in the spec          */
00093     int reseed_counter ;                     /*!< reseed counter         */
00094 
00095     /* Administrative state */
00096     size_t entropy_len ;         /*!< entropy bytes grabbed on each (re)seed */
00097     int prediction_resistance ;  /*!< enable prediction resistance (Automatic
00098                                      reseed before every random generation) */
00099     int reseed_interval ;        /*!< reseed interval   */
00100 
00101     /* Callbacks */
00102     int (*f_entropy )(void *, unsigned char *, size_t); /*!< entropy function */
00103     void *p_entropy ;            /*!< context for the entropy function        */
00104 
00105 #if defined(MBEDTLS_THREADING_C)
00106     mbedtls_threading_mutex_t mutex;
00107 #endif
00108 } mbedtls_hmac_drbg_context;
00109 
00110 /**
00111  * \brief               HMAC_DRBG context initialization.
00112  *
00113  * This function makes the context ready for mbedtls_hmac_drbg_seed(),
00114  * mbedtls_hmac_drbg_seed_buf() or mbedtls_hmac_drbg_free().
00115  *
00116  * \param ctx           HMAC_DRBG context to be initialized.
00117  */
00118 void mbedtls_hmac_drbg_init( mbedtls_hmac_drbg_context *ctx );
00119 
00120 /**
00121  * \brief               HMAC_DRBG initial seeding.
00122  *
00123  * Set the initial seed and set up the entropy source for future reseeds.
00124  *
00125  * A typical choice for the \p f_entropy and \p p_entropy parameters is
00126  * to use the entropy module:
00127  * - \p f_entropy is mbedtls_entropy_func();
00128  * - \p p_entropy is an instance of ::mbedtls_entropy_context initialized
00129  *   with mbedtls_entropy_init() (which registers the platform's default
00130  *   entropy sources).
00131  *
00132  * You can provide a personalization string in addition to the
00133  * entropy source, to make this instantiation as unique as possible.
00134  *
00135  * \note                By default, the security strength as defined by NIST is:
00136  *                      - 128 bits if \p md_info is SHA-1;
00137  *                      - 192 bits if \p md_info is SHA-224;
00138  *                      - 256 bits if \p md_info is SHA-256, SHA-384 or SHA-512.
00139  *                      Note that SHA-256 is just as efficient as SHA-224.
00140  *                      The security strength can be reduced if a smaller
00141  *                      entropy length is set with
00142  *                      mbedtls_hmac_drbg_set_entropy_len() afterwards.
00143  *
00144  * \note                The entropy length for the initial seeding is
00145  *                      the security strength (converted from bits to bytes).
00146  *                      You can set a different entropy length for subsequent
00147  *                      seeding by calling mbedtls_hmac_drbg_set_entropy_len()
00148  *                      after this function.
00149  *
00150  * \note                During the initial seeding, this function calls
00151  *                      the entropy source to obtain a nonce
00152  *                      whose length is half the entropy length.
00153  *
00154  * \param ctx           HMAC_DRBG context to be seeded.
00155  * \param md_info       MD algorithm to use for HMAC_DRBG.
00156  * \param f_entropy     The entropy callback, taking as arguments the
00157  *                      \p p_entropy context, the buffer to fill, and the
00158  *                      length of the buffer.
00159  *                      \p f_entropy is always called with a length that is
00160  *                      less than or equal to the entropy length.
00161  * \param p_entropy     The entropy context to pass to \p f_entropy.
00162  * \param custom        The personalization string.
00163  *                      This can be \c NULL, in which case the personalization
00164  *                      string is empty regardless of the value of \p len.
00165  * \param len           The length of the personalization string.
00166  *                      This must be at most #MBEDTLS_HMAC_DRBG_MAX_INPUT
00167  *                      and also at most
00168  *                      #MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT - \p entropy_len * 3 / 2
00169  *                      where \p entropy_len is the entropy length
00170  *                      described above.
00171  *
00172  * \return              \c 0 if successful.
00173  * \return              #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info is
00174  *                      invalid.
00175  * \return              #MBEDTLS_ERR_MD_ALLOC_FAILED if there was not enough
00176  *                      memory to allocate context data.
00177  * \return              #MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
00178  *                      if the call to \p f_entropy failed.
00179  */
00180 int mbedtls_hmac_drbg_seed( mbedtls_hmac_drbg_context *ctx,
00181                     const mbedtls_md_info_t * md_info,
00182                     int (*f_entropy)(void *, unsigned char *, size_t),
00183                     void *p_entropy,
00184                     const unsigned char *custom,
00185                     size_t len );
00186 
00187 /**
00188  * \brief               Initilisation of simpified HMAC_DRBG (never reseeds).
00189  *
00190  * This function is meant for use in algorithms that need a pseudorandom
00191  * input such as deterministic ECDSA.
00192  *
00193  * \param ctx           HMAC_DRBG context to be initialised.
00194  * \param md_info       MD algorithm to use for HMAC_DRBG.
00195  * \param data          Concatenation of the initial entropy string and
00196  *                      the additional data.
00197  * \param data_len      Length of \p data in bytes.
00198  *
00199  * \return              \c 0 if successful. or
00200  * \return              #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info is
00201  *                      invalid.
00202  * \return              #MBEDTLS_ERR_MD_ALLOC_FAILED if there was not enough
00203  *                      memory to allocate context data.
00204  */
00205 int mbedtls_hmac_drbg_seed_buf( mbedtls_hmac_drbg_context *ctx,
00206                         const mbedtls_md_info_t * md_info,
00207                         const unsigned char *data, size_t data_len );
00208 
00209 /**
00210  * \brief               This function turns prediction resistance on or off.
00211  *                      The default value is off.
00212  *
00213  * \note                If enabled, entropy is gathered at the beginning of
00214  *                      every call to mbedtls_hmac_drbg_random_with_add()
00215  *                      or mbedtls_hmac_drbg_random().
00216  *                      Only use this if your entropy source has sufficient
00217  *                      throughput.
00218  *
00219  * \param ctx           The HMAC_DRBG context.
00220  * \param resistance    #MBEDTLS_HMAC_DRBG_PR_ON or #MBEDTLS_HMAC_DRBG_PR_OFF.
00221  */
00222 void mbedtls_hmac_drbg_set_prediction_resistance( mbedtls_hmac_drbg_context *ctx,
00223                                           int resistance );
00224 
00225 /**
00226  * \brief               This function sets the amount of entropy grabbed on each
00227  *                      reseed.
00228  *
00229  * The default value is set by mbedtls_hmac_drbg_seed().
00230  *
00231  * \note                mbedtls_hmac_drbg_seed() always sets the entropy length
00232  *                      to the default value based on the chosen MD algorithm,
00233  *                      so this function only has an effect if it is called
00234  *                      after mbedtls_hmac_drbg_seed().
00235  *
00236  * \param ctx           The HMAC_DRBG context.
00237  * \param len           The amount of entropy to grab, in bytes.
00238  */
00239 void mbedtls_hmac_drbg_set_entropy_len( mbedtls_hmac_drbg_context *ctx,
00240                                 size_t len );
00241 
00242 /**
00243  * \brief               Set the reseed interval.
00244  *
00245  * The reseed interval is the number of calls to mbedtls_hmac_drbg_random()
00246  * or mbedtls_hmac_drbg_random_with_add() after which the entropy function
00247  * is called again.
00248  *
00249  * The default value is #MBEDTLS_HMAC_DRBG_RESEED_INTERVAL.
00250  *
00251  * \param ctx           The HMAC_DRBG context.
00252  * \param interval      The reseed interval.
00253  */
00254 void mbedtls_hmac_drbg_set_reseed_interval( mbedtls_hmac_drbg_context *ctx,
00255                                     int interval );
00256 
00257 /**
00258  * \brief               This function updates the state of the HMAC_DRBG context.
00259  *
00260  * \param ctx           The HMAC_DRBG context.
00261  * \param additional    The data to update the state with.
00262  *                      If this is \c NULL, there is no additional data.
00263  * \param add_len       Length of \p additional in bytes.
00264  *                      Unused if \p additional is \c NULL.
00265  *
00266  * \return              \c 0 on success, or an error from the underlying
00267  *                      hash calculation.
00268  */
00269 int mbedtls_hmac_drbg_update_ret( mbedtls_hmac_drbg_context *ctx,
00270                        const unsigned char *additional, size_t add_len );
00271 
00272 /**
00273  * \brief               This function reseeds the HMAC_DRBG context, that is
00274  *                      extracts data from the entropy source.
00275  *
00276  * \param ctx           The HMAC_DRBG context.
00277  * \param additional    Additional data to add to the state.
00278  *                      If this is \c NULL, there is no additional data
00279  *                      and \p len should be \c 0.
00280  * \param len           The length of the additional data.
00281  *                      This must be at most #MBEDTLS_HMAC_DRBG_MAX_INPUT
00282  *                      and also at most
00283  *                      #MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT - \p entropy_len
00284  *                      where \p entropy_len is the entropy length
00285  *                      (see mbedtls_hmac_drbg_set_entropy_len()).
00286  *
00287  * \return              \c 0 if successful.
00288  * \return              #MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
00289  *                      if a call to the entropy function failed.
00290  */
00291 int mbedtls_hmac_drbg_reseed( mbedtls_hmac_drbg_context *ctx,
00292                       const unsigned char *additional, size_t len );
00293 
00294 /**
00295  * \brief   This function updates an HMAC_DRBG instance with additional
00296  *          data and uses it to generate random data.
00297  *
00298  * This function automatically reseeds if the reseed counter is exceeded
00299  * or prediction resistance is enabled.
00300  *
00301  * \param p_rng         The HMAC_DRBG context. This must be a pointer to a
00302  *                      #mbedtls_hmac_drbg_context structure.
00303  * \param output        The buffer to fill.
00304  * \param output_len    The length of the buffer in bytes.
00305  *                      This must be at most #MBEDTLS_HMAC_DRBG_MAX_REQUEST.
00306  * \param additional    Additional data to update with.
00307  *                      If this is \c NULL, there is no additional data
00308  *                      and \p add_len should be \c 0.
00309  * \param add_len       The length of the additional data.
00310  *                      This must be at most #MBEDTLS_HMAC_DRBG_MAX_INPUT.
00311  *
00312  * \return              \c 0 if successful.
00313  * \return              #MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
00314  *                      if a call to the entropy source failed.
00315  * \return              #MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG if
00316  *                      \p output_len > #MBEDTLS_HMAC_DRBG_MAX_REQUEST.
00317  * \return              #MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG if
00318  *                      \p add_len > #MBEDTLS_HMAC_DRBG_MAX_INPUT.
00319  */
00320 int mbedtls_hmac_drbg_random_with_add( void *p_rng,
00321                                unsigned char *output, size_t output_len,
00322                                const unsigned char *additional,
00323                                size_t add_len );
00324 
00325 /**
00326  * \brief   This function uses HMAC_DRBG to generate random data.
00327  *
00328  * This function automatically reseeds if the reseed counter is exceeded
00329  * or prediction resistance is enabled.
00330  *
00331  * \param p_rng         The HMAC_DRBG context. This must be a pointer to a
00332  *                      #mbedtls_hmac_drbg_context structure.
00333  * \param output        The buffer to fill.
00334  * \param out_len       The length of the buffer in bytes.
00335  *                      This must be at most #MBEDTLS_HMAC_DRBG_MAX_REQUEST.
00336  *
00337  * \return              \c 0 if successful.
00338  * \return              #MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
00339  *                      if a call to the entropy source failed.
00340  * \return              #MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG if
00341  *                      \p out_len > #MBEDTLS_HMAC_DRBG_MAX_REQUEST.
00342  */
00343 int mbedtls_hmac_drbg_random( void *p_rng, unsigned char *output, size_t out_len );
00344 
00345 /**
00346  * \brief               Free an HMAC_DRBG context
00347  *
00348  * \param ctx           The HMAC_DRBG context to free.
00349  */
00350 void mbedtls_hmac_drbg_free( mbedtls_hmac_drbg_context *ctx );
00351 
00352 #if ! defined(MBEDTLS_DEPRECATED_REMOVED)
00353 #if defined(MBEDTLS_DEPRECATED_WARNING)
00354 #define MBEDTLS_DEPRECATED    __attribute__((deprecated))
00355 #else
00356 #define MBEDTLS_DEPRECATED
00357 #endif
00358 /**
00359  * \brief               This function updates the state of the HMAC_DRBG context.
00360  *
00361  * \deprecated          Superseded by mbedtls_hmac_drbg_update_ret()
00362  *                      in 2.16.0.
00363  *
00364  * \param ctx           The HMAC_DRBG context.
00365  * \param additional    The data to update the state with.
00366  *                      If this is \c NULL, there is no additional data.
00367  * \param add_len       Length of \p additional in bytes.
00368  *                      Unused if \p additional is \c NULL.
00369  */
00370 MBEDTLS_DEPRECATED void mbedtls_hmac_drbg_update(
00371     mbedtls_hmac_drbg_context *ctx,
00372     const unsigned char *additional, size_t add_len );
00373 #undef MBEDTLS_DEPRECATED
00374 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
00375 
00376 #if defined(MBEDTLS_FS_IO)
00377 /**
00378  * \brief               This function writes a seed file.
00379  *
00380  * \param ctx           The HMAC_DRBG context.
00381  * \param path          The name of the file.
00382  *
00383  * \return              \c 0 on success.
00384  * \return              #MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR on file error.
00385  * \return              #MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED on reseed
00386  *                      failure.
00387  */
00388 int mbedtls_hmac_drbg_write_seed_file( mbedtls_hmac_drbg_context *ctx, const char *path );
00389 
00390 /**
00391  * \brief               This function reads and updates a seed file. The seed
00392  *                      is added to this instance.
00393  *
00394  * \param ctx           The HMAC_DRBG context.
00395  * \param path          The name of the file.
00396  *
00397  * \return              \c 0 on success.
00398  * \return              #MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR on file error.
00399  * \return              #MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED on
00400  *                      reseed failure.
00401  * \return              #MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG if the existing
00402  *                      seed file is too large.
00403  */
00404 int mbedtls_hmac_drbg_update_seed_file( mbedtls_hmac_drbg_context *ctx, const char *path );
00405 #endif /* MBEDTLS_FS_IO */
00406 
00407 
00408 #if defined(MBEDTLS_SELF_TEST)
00409 /**
00410  * \brief               The HMAC_DRBG Checkup routine.
00411  *
00412  * \return              \c 0 if successful.
00413  * \return              \c 1 if the test failed.
00414  */
00415 int mbedtls_hmac_drbg_self_test( int verbose );
00416 #endif
00417 
00418 #ifdef __cplusplus
00419 }
00420 #endif
00421 
00422 #endif /* hmac_drbg.h */