src/libpolarssl/ctr_drbg.h

   1 /**
   2  * \file ctr_drbg.h
   3  *
   4  * \brief CTR_DRBG based on AES-256 (NIST SP 800-90)
   5  *
   6  *  Copyright (C) 2006-2014, Brainspark B.V.
   7  *
   8  *  This file is part of PolarSSL (http://www.polarssl.org)
   9  *  Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>
  10  *
  11  *  All rights reserved.
  12  *
  13  *  This program is free software; you can redistribute it and/or modify
  14  *  it under the terms of the GNU General Public License as published by
  15  *  the Free Software Foundation; either version 2 of the License, or
  16  *  (at your option) any later version.
  17  *
  18  *  This program is distributed in the hope that it will be useful,
  19  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  *  GNU General Public License for more details.
  22  *
  23  *  You should have received a copy of the GNU General Public License along
  24  *  with this program; if not, write to the Free Software Foundation, Inc.,
  25  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  26  */
  27 #ifndef POLARSSL_CTR_DRBG_H
  28 #define POLARSSL_CTR_DRBG_H
  29
  30 #include <string.h>
  31
  32 #include "aes.h"
  33
  34 #define POLARSSL_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED        -0x0034  /**< The entropy source failed. */
  35 #define POLARSSL_ERR_CTR_DRBG_REQUEST_TOO_BIG              -0x0036  /**< Too many random requested in single call. */
  36 #define POLARSSL_ERR_CTR_DRBG_INPUT_TOO_BIG                -0x0038  /**< Input too large (Entropy + additional). */
  37 #define POLARSSL_ERR_CTR_DRBG_FILE_IO_ERROR                -0x003A  /**< Read/write error in file. */
  38
  39 #define CTR_DRBG_BLOCKSIZE          16      /**< Block size used by the cipher                  */
  40 #define CTR_DRBG_KEYSIZE            32      /**< Key size used by the cipher                    */
  41 #define CTR_DRBG_KEYBITS            ( CTR_DRBG_KEYSIZE * 8 )
  42 #define CTR_DRBG_SEEDLEN            ( CTR_DRBG_KEYSIZE + CTR_DRBG_BLOCKSIZE )
  43                                             /**< The seed length (counter + AES key)            */
  44
  45 /**
  46  * \name SECTION: Module settings
  47  *
  48  * The configuration options you can set for this module are in this section.
  49  * Either change them in config.h or define them on the compiler command line.
  50  * \{
  51  */
  52
  53 #if !defined(CTR_DRBG_ENTROPY_LEN)
  54 #if defined(POLARSSL_SHA512_C) && !defined(POLARSSL_ENTROPY_FORCE_SHA256)
  55 #define CTR_DRBG_ENTROPY_LEN        48      /**< Amount of entropy used per seed by default (48 with SHA-512, 32 with SHA-256) */
  56 #else
  57 #define CTR_DRBG_ENTROPY_LEN        32      /**< Amount of entropy used per seed by default (48 with SHA-512, 32 with SHA-256) */
  58 #endif
  59 #endif
  60
  61 #if !defined(CTR_DRBG_RESEED_INTERVAL)
  62 #define CTR_DRBG_RESEED_INTERVAL    10000   /**< Interval before reseed is performed by default */
  63 #endif
  64
  65 #if !defined(CTR_DRBG_MAX_INPUT)
  66 #define CTR_DRBG_MAX_INPUT          256     /**< Maximum number of additional input bytes */
  67 #endif
  68
  69 #if !defined(CTR_DRBG_MAX_REQUEST)
  70 #define CTR_DRBG_MAX_REQUEST        1024    /**< Maximum number of requested bytes per call */
  71 #endif
  72
  73 #if !defined(CTR_DRBG_MAX_SEED_INPUT)
  74 #define CTR_DRBG_MAX_SEED_INPUT     384     /**< Maximum size of (re)seed buffer */
  75 #endif
  76
  77 /* \} name SECTION: Module settings */
  78
  79 #define CTR_DRBG_PR_OFF             0       /**< No prediction resistance       */
  80 #define CTR_DRBG_PR_ON              1       /**< Prediction resistance enabled  */
  81
  82 #ifdef __cplusplus
  83 extern "C" {
  84 #endif
  85
  86 /**
  87  * \brief          CTR_DRBG context structure
  88  */
  89 typedef struct
  90 {
  91     unsigned char counter[16];  /*!<  counter (V)       */
  92     int reseed_counter;         /*!<  reseed counter    */
  93     int prediction_resistance;  /*!<  enable prediction resistance (Automatic
  94                                       reseed before every random generation)  */
  95     size_t entropy_len;         /*!<  amount of entropy grabbed on each
  96                                       (re)seed          */
  97     int reseed_interval;        /*!<  reseed interval   */
  98
  99     aes_context aes_ctx;        /*!<  AES context       */
 100
 101     /*
 102      * Callbacks (Entropy)
 103      */
 104     int (*f_entropy)(void *, unsigned char *, size_t);
 105
 106     void *p_entropy;            /*!<  context for the entropy function */
 107 }
 108 ctr_drbg_context;
 109
 110 /**
 111  * \brief               CTR_DRBG initialization
 112  *
 113  * Note: Personalization data can be provided in addition to the more generic
 114  *       entropy source to make this instantiation as unique as possible.
 115  *
 116  * \param ctx           CTR_DRBG context to be initialized
 117  * \param f_entropy     Entropy callback (p_entropy, buffer to fill, buffer
 118  *                      length)
 119  * \param p_entropy     Entropy context
 120  * \param custom        Personalization data (Device specific identifiers)
 121  *                      (Can be NULL)
 122  * \param len           Length of personalization data
 123  *
 124  * \return              0 if successful, or
 125  *                      POLARSSL_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
 126  */
 127 int ctr_drbg_init( ctr_drbg_context *ctx,
 128                    int (*f_entropy)(void *, unsigned char *, size_t),
 129                    void *p_entropy,
 130                    const unsigned char *custom,
 131                    size_t len );
 132
 133 /**
 134  * \brief               Enable / disable prediction resistance (Default: Off)
 135  *
 136  * Note: If enabled, entropy is used for ctx->entropy_len before each call!
 137  *       Only use this if you have ample supply of good entropy!
 138  *
 139  * \param ctx           CTR_DRBG context
 140  * \param resistance    CTR_DRBG_PR_ON or CTR_DRBG_PR_OFF
 141  */
 142 void ctr_drbg_set_prediction_resistance( ctr_drbg_context *ctx,
 143                                          int resistance );
 144
 145 /**
 146  * \brief               Set the amount of entropy grabbed on each (re)seed
 147  *                      (Default: CTR_DRBG_ENTROPY_LEN)
 148  *
 149  * \param ctx           CTR_DRBG context
 150  * \param len           Amount of entropy to grab
 151  */
 152 void ctr_drbg_set_entropy_len( ctr_drbg_context *ctx,
 153                                size_t len );
 154
 155 /**
 156  * \brief               Set the reseed interval
 157  *                      (Default: CTR_DRBG_RESEED_INTERVAL)
 158  *
 159  * \param ctx           CTR_DRBG context
 160  * \param interval      Reseed interval
 161  */
 162 void ctr_drbg_set_reseed_interval( ctr_drbg_context *ctx,
 163                                    int interval );
 164
 165 /**
 166  * \brief               CTR_DRBG reseeding (extracts data from entropy source)
 167  *
 168  * \param ctx           CTR_DRBG context
 169  * \param additional    Additional data to add to state (Can be NULL)
 170  * \param len           Length of additional data
 171  *
 172  * \return              0 if successful, or
 173  *                      POLARSSL_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
 174  */
 175 int ctr_drbg_reseed( ctr_drbg_context *ctx,
 176                      const unsigned char *additional, size_t len );
 177
 178 /**
 179  * \brief               CTR_DRBG update state
 180  *
 181  * \param ctx           CTR_DRBG context
 182  * \param additional    Additional data to update state with
 183  * \param add_len       Length of additional data
 184  */
 185 void ctr_drbg_update( ctr_drbg_context *ctx,
 186                       const unsigned char *additional, size_t add_len );
 187
 188 /**
 189  * \brief               CTR_DRBG generate random with additional update input
 190  *
 191  * Note: Automatically reseeds if reseed_counter is reached.
 192  *
 193  * \param p_rng         CTR_DRBG context
 194  * \param output        Buffer to fill
 195  * \param output_len    Length of the buffer
 196  * \param additional    Additional data to update with (Can be NULL)
 197  * \param add_len       Length of additional data
 198  *
 199  * \return              0 if successful, or
 200  *                      POLARSSL_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED, or
 201  *                      POLARSSL_ERR_CTR_DRBG_REQUEST_TOO_BIG
 202  */
 203 int ctr_drbg_random_with_add( void *p_rng,
 204                               unsigned char *output, size_t output_len,
 205                               const unsigned char *additional, size_t add_len );
 206
 207 /**
 208  * \brief               CTR_DRBG generate random
 209  *
 210  * Note: Automatically reseeds if reseed_counter is reached.
 211  *
 212  * \param p_rng         CTR_DRBG context
 213  * \param output        Buffer to fill
 214  * \param output_len    Length of the buffer
 215  *
 216  * \return              0 if successful, or
 217  *                      POLARSSL_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED, or
 218  *                      POLARSSL_ERR_CTR_DRBG_REQUEST_TOO_BIG
 219  */
 220 int ctr_drbg_random( void *p_rng,
 221                      unsigned char *output, size_t output_len );
 222
 223 #if defined(POLARSSL_FS_IO)
 224 /**
 225  * \brief               Write a seed file
 226  *
 227  * \param ctx           CTR_DRBG context
 228  * \param path          Name of the file
 229  *
 230  * \return              0 if successful,
 231  *                      POLARSSL_ERR_CTR_DRBG_FILE_IO_ERROR on file error, or
 232  *                      POLARSSL_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
 233  */
 234 int ctr_drbg_write_seed_file( ctr_drbg_context *ctx, const char *path );
 235
 236 /**
 237  * \brief               Read and update a seed file. Seed is added to this
 238  *                      instance
 239  *
 240  * \param ctx           CTR_DRBG context
 241  * \param path          Name of the file
 242  *
 243  * \return              0 if successful,
 244  *                      POLARSSL_ERR_CTR_DRBG_FILE_IO_ERROR on file error,
 245  *                      POLARSSL_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
 246  *                      POLARSSL_ERR_CTR_DRBG_INPUT_TOO_BIG
 247  */
 248 int ctr_drbg_update_seed_file( ctr_drbg_context *ctx, const char *path );
 249 #endif /* POLARSSL_FS_IO */
 250
 251 /**
 252  * \brief               Checkup routine
 253  *
 254  * \return              0 if successful, or 1 if the test failed
 255  */
 256 int ctr_drbg_self_test( int verbose );
 257
 258 /* Internal functions (do not call directly) */
 259 int ctr_drbg_init_entropy_len( ctr_drbg_context *,
 260                                int (*)(void *, unsigned char *, size_t), void *,
 261                                const unsigned char *, size_t, size_t );
 262
 263 #ifdef __cplusplus
 264 }
 265 #endif
 266
 267 #endif /* ctr_drbg.h */