ctr_drbg.h

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