hmac_drbg.h

00001 /**
00002  * \file hmac_drbg.h
00003  *
00004  * \brief HMAC_DRBG (NIST SP 800-90A)
00005  *
00006  *  Copyright (C) 2014, Brainspark B.V.
00007  *
00008  *  This file is part of PolarSSL (http://www.polarssl.org)
00009  *  Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>
00010  *
00011  *  All rights reserved.
00012  *
00013  *  This program is free software; you can redistribute it and/or modify
00014  *  it under the terms of the GNU General Public License as published by
00015  *  the Free Software Foundation; either version 2 of the License, or
00016  *  (at your option) any later version.
00017  *
00018  *  This program is distributed in the hope that it will be useful,
00019  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00020  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00021  *  GNU General Public License for more details.
00022  *
00023  *  You should have received a copy of the GNU General Public License along
00024  *  with this program; if not, write to the Free Software Foundation, Inc.,
00025  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
00026  */
00027 #ifndef POLARSSL_HMAC_DRBG_H
00028 #define POLARSSL_HMAC_DRBG_H
00029 
00030 #include "md.h"
00031 
00032 /*
00033  * Error codes
00034  */
00035 #define POLARSSL_ERR_HMAC_DRBG_REQUEST_TOO_BIG              -0x0003  /**< Too many random requested in single call. */
00036 #define POLARSSL_ERR_HMAC_DRBG_INPUT_TOO_BIG                -0x0005  /**< Input too large (Entropy + additional). */
00037 #define POLARSSL_ERR_HMAC_DRBG_FILE_IO_ERROR                -0x0007  /**< Read/write error in file. */
00038 #define POLARSSL_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED        -0x0009  /**< The entropy source failed. */
00039 
00040 /**
00041  * \name SECTION: Module settings
00042  *
00043  * The configuration options you can set for this module are in this section.
00044  * Either change them in config.h or define them on the compiler command line.
00045  * \{
00046  */
00047 
00048 #if !defined(POLARSSL_HMAC_DRBG_RESEED_INTERVAL)
00049 #define POLARSSL_HMAC_DRBG_RESEED_INTERVAL   10000   /**< Interval before reseed is performed by default */
00050 #endif
00051 
00052 #if !defined(POLARSSL_HMAC_DRBG_MAX_INPUT)
00053 #define POLARSSL_HMAC_DRBG_MAX_INPUT         256     /**< Maximum number of additional input bytes */
00054 #endif
00055 
00056 #if !defined(POLARSSL_HMAC_DRBG_MAX_REQUEST)
00057 #define POLARSSL_HMAC_DRBG_MAX_REQUEST       1024    /**< Maximum number of requested bytes per call */
00058 #endif
00059 
00060 #if !defined(POLARSSL_HMAC_DRBG_MAX_SEED_INPUT)
00061 #define POLARSSL_HMAC_DRBG_MAX_SEED_INPUT    384     /**< Maximum size of (re)seed buffer */
00062 #endif
00063 
00064 /* \} name SECTION: Module settings */
00065 
00066 #define POLARSSL_HMAC_DRBG_PR_OFF   0   /**< No prediction resistance       */
00067 #define POLARSSL_HMAC_DRBG_PR_ON    1   /**< Prediction resistance enabled  */
00068 
00069 #ifdef __cplusplus
00070 extern "C" {
00071 #endif
00072 
00073 /**
00074  * HMAC_DRBG context.
00075  */
00076 typedef struct
00077 {
00078     /* Working state: the key K is not stored explicitely,
00079      * but is implied by the HMAC context */
00080     md_context_t md_ctx ;                    /*!< HMAC context (inc. K)  */
00081     unsigned char V[POLARSSL_MD_MAX_SIZE];  /*!< V in the spec          */
00082     int reseed_counter ;                     /*!< reseed counter         */
00083 
00084     /* Administrative state */
00085     size_t entropy_len ;         /*!< entropy bytes grabbed on each (re)seed */
00086     int prediction_resistance;  /*!< enable prediction resistance (Automatic
00087                                      reseed before every random generation) */
00088     int reseed_interval ;        /*!< reseed interval   */
00089 
00090     /* Callbacks */
00091     int (*f_entropy)(void *, unsigned char *, size_t); /*!< entropy function */
00092     void *p_entropy ;            /*!< context for the entropy function        */
00093 } hmac_drbg_context;
00094 
00095 /**
00096  * \brief               HMAC_DRBG initialisation
00097  *
00098  * \param ctx           HMAC_DRBG context to be initialised
00099  * \param md_info       MD algorithm to use for HMAC_DRBG
00100  * \param f_entropy     Entropy callback (p_entropy, buffer to fill, buffer
00101  *                      length)
00102  * \param p_entropy     Entropy context
00103  * \param custom        Personalization data (Device specific identifiers)
00104  *                      (Can be NULL)
00105  * \param len           Length of personalization data
00106  *
00107  * \note                The "security strength" as defined by NIST is set to:
00108  *                      128 bits if md_alg is SHA-1,
00109  *                      192 bits if md_alg is SHA-224,
00110  *                      256 bits if md_alg is SHA-256 or higher.
00111  *                      Note that SHA-256 is just as efficient as SHA-224.
00112  *
00113  * \return              0 if successful, or
00114  *                      POLARSSL_ERR_MD_BAD_INPUT_DATA, or
00115  *                      POLARSSL_ERR_MD_ALLOC_FAILED, or
00116  *                      POLARSSL_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED.
00117  */
00118 int hmac_drbg_init( hmac_drbg_context *ctx,
00119                     const md_info_t * md_info,
00120                     int (*f_entropy)(void *, unsigned char *, size_t),
00121                     void *p_entropy,
00122                     const unsigned char *custom,
00123                     size_t len );
00124 
00125 /**
00126  * \brief               Initilisation of simpified HMAC_DRBG (never reseeds).
00127  *                      (For use with deterministic ECDSA.)
00128  *
00129  * \param ctx           HMAC_DRBG context to be initialised
00130  * \param md_info       MD algorithm to use for HMAC_DRBG
00131  * \param data          Concatenation of entropy string and additional data
00132  * \param data_len      Length of data in bytes
00133  *
00134  * \return              0 if successful, or
00135  *                      POLARSSL_ERR_MD_BAD_INPUT_DATA, or
00136  *                      POLARSSL_ERR_MD_ALLOC_FAILED.
00137  */
00138 int hmac_drbg_init_buf( hmac_drbg_context *ctx,
00139                         const md_info_t * md_info,
00140                         const unsigned char *data, size_t data_len );
00141 
00142 /**
00143  * \brief               Enable / disable prediction resistance (Default: Off)
00144  *
00145  * Note: If enabled, entropy is used for ctx->entropy_len before each call!
00146  *       Only use this if you have ample supply of good entropy!
00147  *
00148  * \param ctx           HMAC_DRBG context
00149  * \param resistance    POLARSSL_HMAC_DRBG_PR_ON or POLARSSL_HMAC_DRBG_PR_OFF
00150  */
00151 void hmac_drbg_set_prediction_resistance( hmac_drbg_context *ctx,
00152                                           int resistance );
00153 
00154 /**
00155  * \brief               Set the amount of entropy grabbed on each reseed
00156  *                      (Default: given by the security strength, which
00157  *                      depends on the hash used, see \c hmac_drbg_init() )
00158  *
00159  * \param ctx           HMAC_DRBG context
00160  * \param len           Amount of entropy to grab, in bytes
00161  */
00162 void hmac_drbg_set_entropy_len( hmac_drbg_context *ctx,
00163                                 size_t len );
00164 
00165 /**
00166  * \brief               Set the reseed interval
00167  *                      (Default: POLARSSL_HMAC_DRBG_RESEED_INTERVAL)
00168  *
00169  * \param ctx           HMAC_DRBG context
00170  * \param interval      Reseed interval
00171  */
00172 void hmac_drbg_set_reseed_interval( hmac_drbg_context *ctx,
00173                                     int interval );
00174 
00175 /**
00176  * \brief               HMAC_DRBG update state
00177  *
00178  * \param ctx           HMAC_DRBG context
00179  * \param additional    Additional data to update state with, or NULL
00180  * \param add_len       Length of additional data, or 0
00181  *
00182  * \note                Additional data is optional, pass NULL and 0 as second
00183  *                      third argument if no additional data is being used.
00184  */
00185 void hmac_drbg_update( hmac_drbg_context *ctx,
00186                        const unsigned char *additional, size_t add_len );
00187 
00188 /**
00189  * \brief               HMAC_DRBG reseeding (extracts data from entropy source)
00190  *
00191  * \param ctx           HMAC_DRBG context
00192  * \param additional    Additional data to add to state (Can be NULL)
00193  * \param len           Length of additional data
00194  *
00195  * \return              0 if successful, or
00196  *                      POLARSSL_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
00197  */
00198 int hmac_drbg_reseed( hmac_drbg_context *ctx,
00199                       const unsigned char *additional, size_t len );
00200 
00201 /**
00202  * \brief               HMAC_DRBG generate random with additional update input
00203  *
00204  * Note: Automatically reseeds if reseed_counter is reached or PR is enabled.
00205  *
00206  * \param p_rng         HMAC_DRBG context
00207  * \param output        Buffer to fill
00208  * \param output_len    Length of the buffer
00209  * \param additional    Additional data to update with (can be NULL)
00210  * \param add_len       Length of additional data (can be 0)
00211  *
00212  * \return              0 if successful, or
00213  *                      POLARSSL_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED, or
00214  *                      POLARSSL_ERR_HMAC_DRBG_REQUEST_TOO_BIG, or
00215  *                      POLARSSL_ERR_HMAC_DRBG_INPUT_TOO_BIG.
00216  */
00217 int hmac_drbg_random_with_add( void *p_rng,
00218                                unsigned char *output, size_t output_len,
00219                                const unsigned char *additional,
00220                                size_t add_len );
00221 
00222 /**
00223  * \brief               HMAC_DRBG generate random
00224  *
00225  * Note: Automatically reseeds if reseed_counter is reached or PR is enabled.
00226  *
00227  * \param p_rng         HMAC_DRBG context
00228  * \param output        Buffer to fill
00229  * \param out_len       Length of the buffer
00230  *
00231  * \return              0 if successful, or
00232  *                      POLARSSL_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED, or
00233  *                      POLARSSL_ERR_HMAC_DRBG_REQUEST_TOO_BIG
00234  */
00235 int hmac_drbg_random( void *p_rng, unsigned char *output, size_t out_len );
00236 
00237 /**
00238  * \brief               Free an HMAC_DRBG context
00239  *
00240  * \param ctx           HMAC_DRBG context to free.
00241  */
00242 void hmac_drbg_free( hmac_drbg_context *ctx );
00243 
00244 #if defined(POLARSSL_FS_IO)
00245 /**
00246  * \brief               Write a seed file
00247  *
00248  * \param ctx           HMAC_DRBG context
00249  * \param path          Name of the file
00250  *
00251  * \return              0 if successful, 1 on file error, or
00252  *                      POLARSSL_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
00253  */
00254 int hmac_drbg_write_seed_file( hmac_drbg_context *ctx, const char *path );
00255 
00256 /**
00257  * \brief               Read and update a seed file. Seed is added to this
00258  *                      instance
00259  *
00260  * \param ctx           HMAC_DRBG context
00261  * \param path          Name of the file
00262  *
00263  * \return              0 if successful, 1 on file error,
00264  *                      POLARSSL_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED or
00265  *                      POLARSSL_ERR_HMAC_DRBG_INPUT_TOO_BIG
00266  */
00267 int hmac_drbg_update_seed_file( hmac_drbg_context *ctx, const char *path );
00268 #endif /* POLARSSL_FS_IO */
00269 
00270 
00271 #if defined(POLARSSL_SELF_TEST)
00272 /**
00273  * \brief               Checkup routine
00274  *
00275  * \return              0 if successful, or 1 if the test failed
00276  */
00277 int hmac_drbg_self_test( int verbose );
00278 #endif
00279 
00280 #ifdef __cplusplus
00281 }
00282 #endif
00283 
00284 #endif /* hmac_drbg.h */
00285 
00286