Example program to test AES-GCM functionality. Used for a workshop

Dependencies:   mbed

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers ctr_drbg.h Source File

ctr_drbg.h

Go to the documentation of this file.
00001 /**
00002  * \file ctr_drbg.h
00003  *
00004  * \brief CTR_DRBG based on AES-256 (NIST SP 800-90)
00005  *
00006  *  Copyright (C) 2006-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_CTR_DRBG_H
00028 #define POLARSSL_CTR_DRBG_H
00029 
00030 #include <string.h>
00031 
00032 #include "aes.h"
00033 
00034 #define POLARSSL_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED        -0x0034  /**< The entropy source failed. */
00035 #define POLARSSL_ERR_CTR_DRBG_REQUEST_TOO_BIG              -0x0036  /**< Too many random requested in single call. */
00036 #define POLARSSL_ERR_CTR_DRBG_INPUT_TOO_BIG                -0x0038  /**< Input too large (Entropy + additional). */
00037 #define POLARSSL_ERR_CTR_DRBG_FILE_IO_ERROR                -0x003A  /**< Read/write error in file. */
00038 
00039 #define CTR_DRBG_BLOCKSIZE          16      /**< Block size used by the cipher                  */
00040 #define CTR_DRBG_KEYSIZE            32      /**< Key size used by the cipher                    */
00041 #define CTR_DRBG_KEYBITS            ( CTR_DRBG_KEYSIZE * 8 )
00042 #define CTR_DRBG_SEEDLEN            ( CTR_DRBG_KEYSIZE + CTR_DRBG_BLOCKSIZE )
00043                                             /**< The seed length (counter + AES key)            */
00044 
00045 /**
00046  * \name SECTION: Module settings
00047  *
00048  * The configuration options you can set for this module are in this section.
00049  * Either change them in config.h or define them on the compiler command line.
00050  * \{
00051  */
00052 
00053 #if !defined(CTR_DRBG_ENTROPY_LEN)
00054 #if defined(POLARSSL_SHA512_C) && !defined(POLARSSL_ENTROPY_FORCE_SHA256)
00055 #define CTR_DRBG_ENTROPY_LEN        48      /**< Amount of entropy used per seed by default (48 with SHA-512, 32 with SHA-256) */
00056 #else
00057 #define CTR_DRBG_ENTROPY_LEN        32      /**< Amount of entropy used per seed by default (48 with SHA-512, 32 with SHA-256) */
00058 #endif
00059 #endif
00060 
00061 #if !defined(CTR_DRBG_RESEED_INTERVAL)
00062 #define CTR_DRBG_RESEED_INTERVAL    10000   /**< Interval before reseed is performed by default */
00063 #endif
00064 
00065 #if !defined(CTR_DRBG_MAX_INPUT)
00066 #define CTR_DRBG_MAX_INPUT          256     /**< Maximum number of additional input bytes */
00067 #endif
00068 
00069 #if !defined(CTR_DRBG_MAX_REQUEST)
00070 #define CTR_DRBG_MAX_REQUEST        1024    /**< Maximum number of requested bytes per call */
00071 #endif
00072 
00073 #if !defined(CTR_DRBG_MAX_SEED_INPUT)
00074 #define CTR_DRBG_MAX_SEED_INPUT     384     /**< Maximum size of (re)seed buffer */
00075 #endif
00076 
00077 /* \} name SECTION: Module settings */
00078 
00079 #define CTR_DRBG_PR_OFF             0       /**< No prediction resistance       */
00080 #define CTR_DRBG_PR_ON              1       /**< Prediction resistance enabled  */
00081 
00082 #ifdef __cplusplus
00083 extern "C" {
00084 #endif
00085 
00086 /**
00087  * \brief          CTR_DRBG context structure
00088  */
00089 typedef struct
00090 {
00091     unsigned char counter[16];  /*!<  counter (V)       */
00092     int reseed_counter;         /*!<  reseed counter    */
00093     int prediction_resistance;  /*!<  enable prediction resistance (Automatic
00094                                       reseed before every random generation)  */
00095     size_t entropy_len;         /*!<  amount of entropy grabbed on each
00096                                       (re)seed          */
00097     int reseed_interval;        /*!<  reseed interval   */
00098 
00099     aes_context aes_ctx;        /*!<  AES context       */
00100 
00101     /*
00102      * Callbacks (Entropy)
00103      */
00104     int (*f_entropy)(void *, unsigned char *, size_t);
00105 
00106     void *p_entropy;            /*!<  context for the entropy function */
00107 }
00108 ctr_drbg_context;
00109 
00110 /**
00111  * \brief               CTR_DRBG initialization
00112  *
00113  * Note: Personalization data can be provided in addition to the more generic
00114  *       entropy source to make this instantiation as unique as possible.
00115  *
00116  * \param ctx           CTR_DRBG context to be initialized
00117  * \param f_entropy     Entropy callback (p_entropy, buffer to fill, buffer
00118  *                      length)
00119  * \param p_entropy     Entropy context
00120  * \param custom        Personalization data (Device specific identifiers)
00121  *                      (Can be NULL)
00122  * \param len           Length of personalization data
00123  *
00124  * \return              0 if successful, or
00125  *                      POLARSSL_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
00126  */
00127 int ctr_drbg_init( ctr_drbg_context *ctx,
00128                    int (*f_entropy)(void *, unsigned char *, size_t),
00129                    void *p_entropy,
00130                    const unsigned char *custom,
00131                    size_t len );
00132 
00133 /**
00134  * \brief               Enable / disable prediction resistance (Default: Off)
00135  *
00136  * Note: If enabled, entropy is used for ctx->entropy_len before each call!
00137  *       Only use this if you have ample supply of good entropy!
00138  *
00139  * \param ctx           CTR_DRBG context
00140  * \param resistance    CTR_DRBG_PR_ON or CTR_DRBG_PR_OFF
00141  */
00142 void ctr_drbg_set_prediction_resistance( ctr_drbg_context *ctx,
00143                                          int resistance );
00144 
00145 /**
00146  * \brief               Set the amount of entropy grabbed on each (re)seed
00147  *                      (Default: CTR_DRBG_ENTROPY_LEN)
00148  *
00149  * \param ctx           CTR_DRBG context
00150  * \param len           Amount of entropy to grab
00151  */
00152 void ctr_drbg_set_entropy_len( ctr_drbg_context *ctx,
00153                                size_t len );
00154 
00155 /**
00156  * \brief               Set the reseed interval
00157  *                      (Default: CTR_DRBG_RESEED_INTERVAL)
00158  *
00159  * \param ctx           CTR_DRBG context
00160  * \param interval      Reseed interval
00161  */
00162 void ctr_drbg_set_reseed_interval( ctr_drbg_context *ctx,
00163                                    int interval );
00164 
00165 /**
00166  * \brief               CTR_DRBG reseeding (extracts data from entropy source)
00167  *
00168  * \param ctx           CTR_DRBG context
00169  * \param additional    Additional data to add to state (Can be NULL)
00170  * \param len           Length of additional data
00171  *
00172  * \return              0 if successful, or
00173  *                      POLARSSL_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
00174  */
00175 int ctr_drbg_reseed( ctr_drbg_context *ctx,
00176                      const unsigned char *additional, size_t len );
00177 
00178 /**
00179  * \brief               CTR_DRBG update state
00180  *
00181  * \param ctx           CTR_DRBG context
00182  * \param additional    Additional data to update state with
00183  * \param add_len       Length of additional data
00184  */
00185 void ctr_drbg_update( ctr_drbg_context *ctx,
00186                       const unsigned char *additional, size_t add_len );
00187 
00188 /**
00189  * \brief               CTR_DRBG generate random with additional update input
00190  *
00191  * Note: Automatically reseeds if reseed_counter is reached.
00192  *
00193  * \param p_rng         CTR_DRBG context
00194  * \param output        Buffer to fill
00195  * \param output_len    Length of the buffer
00196  * \param additional    Additional data to update with (Can be NULL)
00197  * \param add_len       Length of additional data
00198  *
00199  * \return              0 if successful, or
00200  *                      POLARSSL_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED, or
00201  *                      POLARSSL_ERR_CTR_DRBG_REQUEST_TOO_BIG
00202  */
00203 int ctr_drbg_random_with_add( void *p_rng,
00204                               unsigned char *output, size_t output_len,
00205                               const unsigned char *additional, size_t add_len );
00206 
00207 /**
00208  * \brief               CTR_DRBG generate random
00209  *
00210  * Note: Automatically reseeds if reseed_counter is reached.
00211  *
00212  * \param p_rng         CTR_DRBG context
00213  * \param output        Buffer to fill
00214  * \param output_len    Length of the buffer
00215  *
00216  * \return              0 if successful, or
00217  *                      POLARSSL_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED, or
00218  *                      POLARSSL_ERR_CTR_DRBG_REQUEST_TOO_BIG
00219  */
00220 int ctr_drbg_random( void *p_rng,
00221                      unsigned char *output, size_t output_len );
00222 
00223 #if defined(POLARSSL_FS_IO)
00224 /**
00225  * \brief               Write a seed file
00226  *
00227  * \param ctx           CTR_DRBG context
00228  * \param path          Name of the file
00229  *
00230  * \return              0 if successful,
00231  *                      POLARSSL_ERR_CTR_DRBG_FILE_IO_ERROR on file error, or
00232  *                      POLARSSL_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
00233  */
00234 int ctr_drbg_write_seed_file( ctr_drbg_context *ctx, const char *path );
00235 
00236 /**
00237  * \brief               Read and update a seed file. Seed is added to this
00238  *                      instance
00239  *
00240  * \param ctx           CTR_DRBG context
00241  * \param path          Name of the file
00242  *
00243  * \return              0 if successful,
00244  *                      POLARSSL_ERR_CTR_DRBG_FILE_IO_ERROR on file error,
00245  *                      POLARSSL_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
00246  *                      POLARSSL_ERR_CTR_DRBG_INPUT_TOO_BIG
00247  */
00248 int ctr_drbg_update_seed_file( ctr_drbg_context *ctx, const char *path );
00249 #endif /* POLARSSL_FS_IO */
00250 
00251 /**
00252  * \brief               Checkup routine
00253  *
00254  * \return              0 if successful, or 1 if the test failed
00255  */
00256 int ctr_drbg_self_test( int verbose );
00257 
00258 /* Internal functions (do not call directly) */
00259 int ctr_drbg_init_entropy_len( ctr_drbg_context *,
00260                                int (*)(void *, unsigned char *, size_t), void *,
00261                                const unsigned char *, size_t, size_t );
00262 
00263 #ifdef __cplusplus
00264 }
00265 #endif
00266 
00267 #endif /* ctr_drbg.h */
00268 
00269