ctr_drbg.h

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