ctr_drbg.h

00001 /**
00002  * \file ctr_drbg.h
00003  *
00004  * \brief CTR_DRBG based on AES-256 (NIST SP 800-90)
00005  *
00006  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
00007  *  SPDX-License-Identifier: Apache-2.0
00008  *
00009  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00010  *  not use this file except in compliance with the License.
00011  *  You may obtain a copy of the License at
00012  *
00013  *  http://www.apache.org/licenses/LICENSE-2.0
00014  *
00015  *  Unless required by applicable law or agreed to in writing, software
00016  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00017  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00018  *  See the License for the specific language governing permissions and
00019  *  limitations under the License.
00020  *
00021  *  This file is part of mbed TLS (https://tls.mbed.org)
00022  */
00023 #ifndef MBEDTLS_CTR_DRBG_H
00024 #define MBEDTLS_CTR_DRBG_H
00025 
00026 #include "aes.h"
00027 
00028 #if defined(MBEDTLS_THREADING_C)
00029 #include "mbedtls/threading.h"
00030 #endif
00031 
00032 #define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED        -0x0034  /**< The entropy source failed. */
00033 #define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG              -0x0036  /**< Too many random requested in single call. */
00034 #define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG                -0x0038  /**< Input too large (Entropy + additional). */
00035 #define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR                -0x003A  /**< Read/write error in file. */
00036 
00037 #define MBEDTLS_CTR_DRBG_BLOCKSIZE          16      /**< Block size used by the cipher                  */
00038 #define MBEDTLS_CTR_DRBG_KEYSIZE            32      /**< Key size used by the cipher                    */
00039 #define MBEDTLS_CTR_DRBG_KEYBITS            ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 )
00040 #define MBEDTLS_CTR_DRBG_SEEDLEN            ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE )
00041                                             /**< The seed length (counter + AES key)            */
00042 
00043 /**
00044  * \name SECTION: Module settings
00045  *
00046  * The configuration options you can set for this module are in this section.
00047  * Either change them in config.h or define them on the compiler command line.
00048  * \{
00049  */
00050 
00051 #if !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN)
00052 #if defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256)
00053 #define MBEDTLS_CTR_DRBG_ENTROPY_LEN        48      /**< Amount of entropy used per seed by default (48 with SHA-512, 32 with SHA-256) */
00054 #else
00055 #define MBEDTLS_CTR_DRBG_ENTROPY_LEN        32      /**< Amount of entropy used per seed by default (48 with SHA-512, 32 with SHA-256) */
00056 #endif
00057 #endif
00058 
00059 #if !defined(MBEDTLS_CTR_DRBG_RESEED_INTERVAL)
00060 #define MBEDTLS_CTR_DRBG_RESEED_INTERVAL    10000   /**< Interval before reseed is performed by default */
00061 #endif
00062 
00063 #if !defined(MBEDTLS_CTR_DRBG_MAX_INPUT)
00064 #define MBEDTLS_CTR_DRBG_MAX_INPUT          256     /**< Maximum number of additional input bytes */
00065 #endif
00066 
00067 #if !defined(MBEDTLS_CTR_DRBG_MAX_REQUEST)
00068 #define MBEDTLS_CTR_DRBG_MAX_REQUEST        1024    /**< Maximum number of requested bytes per call */
00069 #endif
00070 
00071 #if !defined(MBEDTLS_CTR_DRBG_MAX_SEED_INPUT)
00072 #define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT     384     /**< Maximum size of (re)seed buffer */
00073 #endif
00074 
00075 /* \} name SECTION: Module settings */
00076 
00077 #define MBEDTLS_CTR_DRBG_PR_OFF             0       /**< No prediction resistance       */
00078 #define MBEDTLS_CTR_DRBG_PR_ON              1       /**< Prediction resistance enabled  */
00079 
00080 #ifdef __cplusplus
00081 extern "C" {
00082 #endif
00083 
00084 /**
00085  * \brief          CTR_DRBG context structure
00086  */
00087 typedef struct
00088 {
00089     unsigned char counter[16];  /*!<  counter (V)       */
00090     int reseed_counter;         /*!<  reseed counter    */
00091     int prediction_resistance;  /*!<  enable prediction resistance (Automatic
00092                                       reseed before every random generation)  */
00093     size_t entropy_len;         /*!<  amount of entropy grabbed on each
00094                                       (re)seed          */
00095     int reseed_interval;        /*!<  reseed interval   */
00096 
00097     mbedtls_aes_context aes_ctx;        /*!<  AES context       */
00098 
00099     /*
00100      * Callbacks (Entropy)
00101      */
00102     int (*f_entropy)(void *, unsigned char *, size_t);
00103 
00104     void *p_entropy;            /*!<  context for the entropy function */
00105 
00106 #if defined(MBEDTLS_THREADING_C)
00107     mbedtls_threading_mutex_t mutex;
00108 #endif
00109 }
00110 mbedtls_ctr_drbg_context;
00111 
00112 /**
00113  * \brief               CTR_DRBG context initialization
00114  *                      Makes the context ready for mbedtls_ctr_drbg_seed() or
00115  *                      mbedtls_ctr_drbg_free().
00116  *
00117  * \param ctx           CTR_DRBG context to be initialized
00118  */
00119 void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx );
00120 
00121 /**
00122  * \brief               CTR_DRBG initial seeding
00123  *                      Seed and setup entropy source for future reseeds.
00124  *
00125  * Note: Personalization data can be provided in addition to the more generic
00126  *       entropy source to make this instantiation as unique as possible.
00127  *
00128  * \param ctx           CTR_DRBG context to be seeded
00129  * \param f_entropy     Entropy callback (p_entropy, buffer to fill, buffer
00130  *                      length)
00131  * \param p_entropy     Entropy context
00132  * \param custom        Personalization data (Device specific identifiers)
00133  *                      (Can be NULL)
00134  * \param len           Length of personalization data
00135  *
00136  * \return              0 if successful, or
00137  *                      MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
00138  */
00139 int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx,
00140                    int (*f_entropy)(void *, unsigned char *, size_t),
00141                    void *p_entropy,
00142                    const unsigned char *custom,
00143                    size_t len );
00144 
00145 /**
00146  * \brief               Clear CTR_CRBG context data
00147  *
00148  * \param ctx           CTR_DRBG context to clear
00149  */
00150 void mbedtls_ctr_drbg_free( mbedtls_ctr_drbg_context *ctx );
00151 
00152 /**
00153  * \brief               Enable / disable prediction resistance (Default: Off)
00154  *
00155  * Note: If enabled, entropy is used for ctx->entropy_len before each call!
00156  *       Only use this if you have ample supply of good entropy!
00157  *
00158  * \param ctx           CTR_DRBG context
00159  * \param resistance    MBEDTLS_CTR_DRBG_PR_ON or MBEDTLS_CTR_DRBG_PR_OFF
00160  */
00161 void mbedtls_ctr_drbg_set_prediction_resistance( mbedtls_ctr_drbg_context *ctx,
00162                                          int resistance );
00163 
00164 /**
00165  * \brief               Set the amount of entropy grabbed on each (re)seed
00166  *                      (Default: MBEDTLS_CTR_DRBG_ENTROPY_LEN)
00167  *
00168  * \param ctx           CTR_DRBG context
00169  * \param len           Amount of entropy to grab
00170  */
00171 void mbedtls_ctr_drbg_set_entropy_len( mbedtls_ctr_drbg_context *ctx,
00172                                size_t len );
00173 
00174 /**
00175  * \brief               Set the reseed interval
00176  *                      (Default: MBEDTLS_CTR_DRBG_RESEED_INTERVAL)
00177  *
00178  * \param ctx           CTR_DRBG context
00179  * \param interval      Reseed interval
00180  */
00181 void mbedtls_ctr_drbg_set_reseed_interval( mbedtls_ctr_drbg_context *ctx,
00182                                    int interval );
00183 
00184 /**
00185  * \brief               CTR_DRBG reseeding (extracts data from entropy source)
00186  *
00187  * \param ctx           CTR_DRBG context
00188  * \param additional    Additional data to add to state (Can be NULL)
00189  * \param len           Length of additional data
00190  *
00191  * \return              0 if successful, or
00192  *                      MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
00193  */
00194 int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx,
00195                      const unsigned char *additional, size_t len );
00196 
00197 /**
00198  * \brief               CTR_DRBG update state
00199  *
00200  * \param ctx           CTR_DRBG context
00201  * \param additional    Additional data to update state with
00202  * \param add_len       Length of additional data
00203  *
00204  * \note                If add_len is greater than MBEDTLS_CTR_DRBG_MAX_SEED_INPUT,
00205  *                      only the first MBEDTLS_CTR_DRBG_MAX_SEED_INPUT bytes are used,
00206  *                      the remaining ones are silently discarded.
00207  */
00208 void mbedtls_ctr_drbg_update( mbedtls_ctr_drbg_context *ctx,
00209                       const unsigned char *additional, size_t add_len );
00210 
00211 /**
00212  * \brief               CTR_DRBG generate random with additional update input
00213  *
00214  * Note: Automatically reseeds if reseed_counter is reached.
00215  *
00216  * \param p_rng         CTR_DRBG context
00217  * \param output        Buffer to fill
00218  * \param output_len    Length of the buffer
00219  * \param additional    Additional data to update with (Can be NULL)
00220  * \param add_len       Length of additional data
00221  *
00222  * \return              0 if successful, or
00223  *                      MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED, or
00224  *                      MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG
00225  */
00226 int mbedtls_ctr_drbg_random_with_add( void *p_rng,
00227                               unsigned char *output, size_t output_len,
00228                               const unsigned char *additional, size_t add_len );
00229 
00230 /**
00231  * \brief               CTR_DRBG generate random
00232  *
00233  * Note: Automatically reseeds if reseed_counter is reached.
00234  *
00235  * \param p_rng         CTR_DRBG context
00236  * \param output        Buffer to fill
00237  * \param output_len    Length of the buffer
00238  *
00239  * \return              0 if successful, or
00240  *                      MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED, or
00241  *                      MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG
00242  */
00243 int mbedtls_ctr_drbg_random( void *p_rng,
00244                      unsigned char *output, size_t output_len );
00245 
00246 #if defined(MBEDTLS_FS_IO)
00247 /**
00248  * \brief               Write a seed file
00249  *
00250  * \param ctx           CTR_DRBG context
00251  * \param path          Name of the file
00252  *
00253  * \return              0 if successful,
00254  *                      MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, or
00255  *                      MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
00256  */
00257 int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
00258 
00259 /**
00260  * \brief               Read and update a seed file. Seed is added to this
00261  *                      instance
00262  *
00263  * \param ctx           CTR_DRBG context
00264  * \param path          Name of the file
00265  *
00266  * \return              0 if successful,
00267  *                      MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error,
00268  *                      MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
00269  *                      MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG
00270  */
00271 int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
00272 #endif /* MBEDTLS_FS_IO */
00273 
00274 /**
00275  * \brief               Checkup routine
00276  *
00277  * \return              0 if successful, or 1 if the test failed
00278  */
00279 int mbedtls_ctr_drbg_self_test( int verbose );
00280 
00281 /* Internal functions (do not call directly) */
00282 int mbedtls_ctr_drbg_seed_entropy_len( mbedtls_ctr_drbg_context *,
00283                                int (*)(void *, unsigned char *, size_t), void *,
00284                                const unsigned char *, size_t, size_t );
00285 
00286 #ifdef __cplusplus
00287 }
00288 #endif
00289 
00290 #endif /* ctr_drbg.h */