hmac_drbg.h

00001 /**
00002  * \file hmac_drbg.h
00003  *
00004  * \brief HMAC_DRBG (NIST SP 800-90A)
00005  */
00006 /*
00007  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
00008  *  SPDX-License-Identifier: Apache-2.0
00009  *
00010  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00011  *  not use this file except in compliance with the License.
00012  *  You may obtain a copy of the License at
00013  *
00014  *  http://www.apache.org/licenses/LICENSE-2.0
00015  *
00016  *  Unless required by applicable law or agreed to in writing, software
00017  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00018  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00019  *  See the License for the specific language governing permissions and
00020  *  limitations under the License.
00021  *
00022  *  This file is part of mbed TLS (https://tls.mbed.org)
00023  */
00024 #ifndef MBEDTLS_HMAC_DRBG_H
00025 #define MBEDTLS_HMAC_DRBG_H
00026 
00027 #include "md.h"
00028 
00029 #if defined(MBEDTLS_THREADING_C)
00030 #include "mbedtls/threading.h"
00031 #endif
00032 
00033 /*
00034  * Error codes
00035  */
00036 #define MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG              -0x0003  /**< Too many random requested in single call. */
00037 #define MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG                -0x0005  /**< Input too large (Entropy + additional). */
00038 #define MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR                -0x0007  /**< Read/write error in file. */
00039 #define MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED        -0x0009  /**< The entropy source failed. */
00040 
00041 /**
00042  * \name SECTION: Module settings
00043  *
00044  * The configuration options you can set for this module are in this section.
00045  * Either change them in config.h or define them on the compiler command line.
00046  * \{
00047  */
00048 
00049 #if !defined(MBEDTLS_HMAC_DRBG_RESEED_INTERVAL)
00050 #define MBEDTLS_HMAC_DRBG_RESEED_INTERVAL   10000   /**< Interval before reseed is performed by default */
00051 #endif
00052 
00053 #if !defined(MBEDTLS_HMAC_DRBG_MAX_INPUT)
00054 #define MBEDTLS_HMAC_DRBG_MAX_INPUT         256     /**< Maximum number of additional input bytes */
00055 #endif
00056 
00057 #if !defined(MBEDTLS_HMAC_DRBG_MAX_REQUEST)
00058 #define MBEDTLS_HMAC_DRBG_MAX_REQUEST       1024    /**< Maximum number of requested bytes per call */
00059 #endif
00060 
00061 #if !defined(MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT)
00062 #define MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT    384     /**< Maximum size of (re)seed buffer */
00063 #endif
00064 
00065 /* \} name SECTION: Module settings */
00066 
00067 #define MBEDTLS_HMAC_DRBG_PR_OFF   0   /**< No prediction resistance       */
00068 #define MBEDTLS_HMAC_DRBG_PR_ON    1   /**< Prediction resistance enabled  */
00069 
00070 #ifdef __cplusplus
00071 extern "C" {
00072 #endif
00073 
00074 /**
00075  * HMAC_DRBG context.
00076  */
00077 typedef struct
00078 {
00079     /* Working state: the key K is not stored explicitely,
00080      * but is implied by the HMAC context */
00081     mbedtls_md_context_t md_ctx ;                    /*!< HMAC context (inc. K)  */
00082     unsigned char V[MBEDTLS_MD_MAX_SIZE];  /*!< V in the spec          */
00083     int reseed_counter ;                     /*!< reseed counter         */
00084 
00085     /* Administrative state */
00086     size_t entropy_len ;         /*!< entropy bytes grabbed on each (re)seed */
00087     int prediction_resistance;  /*!< enable prediction resistance (Automatic
00088                                      reseed before every random generation) */
00089     int reseed_interval ;        /*!< reseed interval   */
00090 
00091     /* Callbacks */
00092     int (*f_entropy)(void *, unsigned char *, size_t); /*!< entropy function */
00093     void *p_entropy ;            /*!< context for the entropy function        */
00094 
00095 #if defined(MBEDTLS_THREADING_C)
00096     mbedtls_threading_mutex_t mutex;
00097 #endif
00098 } mbedtls_hmac_drbg_context;
00099 
00100 /**
00101  * \brief               HMAC_DRBG context initialization
00102  *                      Makes the context ready for mbedtls_hmac_drbg_seed(),
00103  *                      mbedtls_hmac_drbg_seed_buf() or
00104  *                      mbedtls_hmac_drbg_free().
00105  *
00106  * \param ctx           HMAC_DRBG context to be initialized
00107  */
00108 void mbedtls_hmac_drbg_init( mbedtls_hmac_drbg_context *ctx );
00109 
00110 /**
00111  * \brief               HMAC_DRBG initial seeding
00112  *                      Seed and setup entropy source for future reseeds.
00113  *
00114  * \param ctx           HMAC_DRBG context to be seeded
00115  * \param md_info       MD algorithm to use for HMAC_DRBG
00116  * \param f_entropy     Entropy callback (p_entropy, buffer to fill, buffer
00117  *                      length)
00118  * \param p_entropy     Entropy context
00119  * \param custom        Personalization data (Device specific identifiers)
00120  *                      (Can be NULL)
00121  * \param len           Length of personalization data
00122  *
00123  * \note                The "security strength" as defined by NIST is set to:
00124  *                      128 bits if md_alg is SHA-1,
00125  *                      192 bits if md_alg is SHA-224,
00126  *                      256 bits if md_alg is SHA-256 or higher.
00127  *                      Note that SHA-256 is just as efficient as SHA-224.
00128  *
00129  * \return              0 if successful, or
00130  *                      MBEDTLS_ERR_MD_BAD_INPUT_DATA, or
00131  *                      MBEDTLS_ERR_MD_ALLOC_FAILED, or
00132  *                      MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED.
00133  */
00134 int mbedtls_hmac_drbg_seed( mbedtls_hmac_drbg_context *ctx,
00135                     const mbedtls_md_info_t * md_info,
00136                     int (*f_entropy)(void *, unsigned char *, size_t),
00137                     void *p_entropy,
00138                     const unsigned char *custom,
00139                     size_t len );
00140 
00141 /**
00142  * \brief               Initilisation of simpified HMAC_DRBG (never reseeds).
00143  *                      (For use with deterministic ECDSA.)
00144  *
00145  * \param ctx           HMAC_DRBG context to be initialised
00146  * \param md_info       MD algorithm to use for HMAC_DRBG
00147  * \param data          Concatenation of entropy string and additional data
00148  * \param data_len      Length of data in bytes
00149  *
00150  * \return              0 if successful, or
00151  *                      MBEDTLS_ERR_MD_BAD_INPUT_DATA, or
00152  *                      MBEDTLS_ERR_MD_ALLOC_FAILED.
00153  */
00154 int mbedtls_hmac_drbg_seed_buf( mbedtls_hmac_drbg_context *ctx,
00155                         const mbedtls_md_info_t * md_info,
00156                         const unsigned char *data, size_t data_len );
00157 
00158 /**
00159  * \brief               Enable / disable prediction resistance (Default: Off)
00160  *
00161  * Note: If enabled, entropy is used for ctx->entropy_len before each call!
00162  *       Only use this if you have ample supply of good entropy!
00163  *
00164  * \param ctx           HMAC_DRBG context
00165  * \param resistance    MBEDTLS_HMAC_DRBG_PR_ON or MBEDTLS_HMAC_DRBG_PR_OFF
00166  */
00167 void mbedtls_hmac_drbg_set_prediction_resistance( mbedtls_hmac_drbg_context *ctx,
00168                                           int resistance );
00169 
00170 /**
00171  * \brief               Set the amount of entropy grabbed on each reseed
00172  *                      (Default: given by the security strength, which
00173  *                      depends on the hash used, see \c mbedtls_hmac_drbg_init() )
00174  *
00175  * \param ctx           HMAC_DRBG context
00176  * \param len           Amount of entropy to grab, in bytes
00177  */
00178 void mbedtls_hmac_drbg_set_entropy_len( mbedtls_hmac_drbg_context *ctx,
00179                                 size_t len );
00180 
00181 /**
00182  * \brief               Set the reseed interval
00183  *                      (Default: MBEDTLS_HMAC_DRBG_RESEED_INTERVAL)
00184  *
00185  * \param ctx           HMAC_DRBG context
00186  * \param interval      Reseed interval
00187  */
00188 void mbedtls_hmac_drbg_set_reseed_interval( mbedtls_hmac_drbg_context *ctx,
00189                                     int interval );
00190 
00191 /**
00192  * \brief               HMAC_DRBG update state
00193  *
00194  * \param ctx           HMAC_DRBG context
00195  * \param additional    Additional data to update state with, or NULL
00196  * \param add_len       Length of additional data, or 0
00197  *
00198  * \note                Additional data is optional, pass NULL and 0 as second
00199  *                      third argument if no additional data is being used.
00200  */
00201 void mbedtls_hmac_drbg_update( mbedtls_hmac_drbg_context *ctx,
00202                        const unsigned char *additional, size_t add_len );
00203 
00204 /**
00205  * \brief               HMAC_DRBG reseeding (extracts data from entropy source)
00206  *
00207  * \param ctx           HMAC_DRBG context
00208  * \param additional    Additional data to add to state (Can be NULL)
00209  * \param len           Length of additional data
00210  *
00211  * \return              0 if successful, or
00212  *                      MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
00213  */
00214 int mbedtls_hmac_drbg_reseed( mbedtls_hmac_drbg_context *ctx,
00215                       const unsigned char *additional, size_t len );
00216 
00217 /**
00218  * \brief               HMAC_DRBG generate random with additional update input
00219  *
00220  * Note: Automatically reseeds if reseed_counter is reached or PR is enabled.
00221  *
00222  * \param p_rng         HMAC_DRBG context
00223  * \param output        Buffer to fill
00224  * \param output_len    Length of the buffer
00225  * \param additional    Additional data to update with (can be NULL)
00226  * \param add_len       Length of additional data (can be 0)
00227  *
00228  * \return              0 if successful, or
00229  *                      MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED, or
00230  *                      MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG, or
00231  *                      MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG.
00232  */
00233 int mbedtls_hmac_drbg_random_with_add( void *p_rng,
00234                                unsigned char *output, size_t output_len,
00235                                const unsigned char *additional,
00236                                size_t add_len );
00237 
00238 /**
00239  * \brief               HMAC_DRBG generate random
00240  *
00241  * Note: Automatically reseeds if reseed_counter is reached or PR is enabled.
00242  *
00243  * \param p_rng         HMAC_DRBG context
00244  * \param output        Buffer to fill
00245  * \param out_len       Length of the buffer
00246  *
00247  * \return              0 if successful, or
00248  *                      MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED, or
00249  *                      MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG
00250  */
00251 int mbedtls_hmac_drbg_random( void *p_rng, unsigned char *output, size_t out_len );
00252 
00253 /**
00254  * \brief               Free an HMAC_DRBG context
00255  *
00256  * \param ctx           HMAC_DRBG context to free.
00257  */
00258 void mbedtls_hmac_drbg_free( mbedtls_hmac_drbg_context *ctx );
00259 
00260 #if defined(MBEDTLS_FS_IO)
00261 /**
00262  * \brief               Write a seed file
00263  *
00264  * \param ctx           HMAC_DRBG context
00265  * \param path          Name of the file
00266  *
00267  * \return              0 if successful, 1 on file error, or
00268  *                      MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
00269  */
00270 int mbedtls_hmac_drbg_write_seed_file( mbedtls_hmac_drbg_context *ctx, const char *path );
00271 
00272 /**
00273  * \brief               Read and update a seed file. Seed is added to this
00274  *                      instance
00275  *
00276  * \param ctx           HMAC_DRBG context
00277  * \param path          Name of the file
00278  *
00279  * \return              0 if successful, 1 on file error,
00280  *                      MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED or
00281  *                      MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG
00282  */
00283 int mbedtls_hmac_drbg_update_seed_file( mbedtls_hmac_drbg_context *ctx, const char *path );
00284 #endif /* MBEDTLS_FS_IO */
00285 
00286 
00287 #if defined(MBEDTLS_SELF_TEST)
00288 /**
00289  * \brief               Checkup routine
00290  *
00291  * \return              0 if successful, or 1 if the test failed
00292  */
00293 int mbedtls_hmac_drbg_self_test( int verbose );
00294 #endif
00295 
00296 #ifdef __cplusplus
00297 }
00298 #endif
00299 
00300 #endif /* hmac_drbg.h */