Documentation

Documentation

Includes

config.h

#include "config.h"
#include "config.h"

MBEDTLS_CONFIG_FILE

#include MBEDTLS_CONFIG_FILE
#include MBEDTLS_CONFIG_FILE

aes.h

#include "aes.h"
#include "aes.h"

threading.h

#include "threading.h"
#include "threading.h"

Macros

Marco MBEDTLS_CTR_DRBG_H

#define MBEDTLS_CTR_DRBG_H


      

Marco MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED

#define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED       -52 /**< The entropy source failed. */


      

Marco MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG

#define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG             -54 /**< The requested random buffer length is too big. */


      

Marco MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG

#define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG               -56 /**< The input (entropy + additional data) is too large. */


      

Marco MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR

#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR               -3A /**< Read or write error in file. */


      

Marco MBEDTLS_CTR_DRBG_BLOCKSIZE

#define MBEDTLS_CTR_DRBG_BLOCKSIZE         16 /**< The block size used by the cipher. */


      

Marco MBEDTLS_CTR_DRBG_KEYSIZE

#define MBEDTLS_CTR_DRBG_KEYSIZE           16 /**< The key size used by the cipher (compile-time choice: 128 bits). */


      

Marco MBEDTLS_CTR_DRBG_KEYSIZE

#define MBEDTLS_CTR_DRBG_KEYSIZE           32 /**< The key size used by the cipher (compile-time choice: 256 bits). */


      

Marco MBEDTLS_CTR_DRBG_KEYBITS

#define MBEDTLS_CTR_DRBG_KEYBITS           ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 ) /**< The key size for the DRBG operation, in bits. */


      

Marco MBEDTLS_CTR_DRBG_SEEDLEN

#define MBEDTLS_CTR_DRBG_SEEDLEN           ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE ) /**< The seed length, calculated as (counter + AES key). */


      

Marco MBEDTLS_CTR_DRBG_ENTROPY_LEN

#define MBEDTLS_CTR_DRBG_ENTROPY_LEN       48


      

Marco MBEDTLS_CTR_DRBG_ENTROPY_LEN

#define MBEDTLS_CTR_DRBG_ENTROPY_LEN       32


      

Marco MBEDTLS_CTR_DRBG_RESEED_INTERVAL

#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL   10000


      

Marco MBEDTLS_CTR_DRBG_MAX_INPUT

#define MBEDTLS_CTR_DRBG_MAX_INPUT         256


      

Marco MBEDTLS_CTR_DRBG_MAX_REQUEST

#define MBEDTLS_CTR_DRBG_MAX_REQUEST       1024


      

Marco MBEDTLS_CTR_DRBG_MAX_SEED_INPUT

#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT    384


      

Marco MBEDTLS_CTR_DRBG_PR_OFF

#define MBEDTLS_CTR_DRBG_PR_OFF            0


      

Marco MBEDTLS_CTR_DRBG_PR_ON

#define MBEDTLS_CTR_DRBG_PR_ON             1
/**< Prediction resistance is disabled. */

Marco MBEDTLS_DEPRECATED

#define MBEDTLS_DEPRECATED   __attribute__((deprecated))


      

Marco MBEDTLS_DEPRECATED

#define MBEDTLS_DEPRECATED

      

Functions

Func mbedtls_ctr_drbg_init

void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx );
/**
 * \brief               This function initializes the CTR_DRBG context,
 *                      and prepares it for mbedtls_ctr_drbg_seed()
 *                      or mbedtls_ctr_drbg_free().
 *
 * \param ctx           The CTR_DRBG context to initialize.
 */

Func mbedtls_ctr_drbg_seed

int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx,
                  int (*f_entropy)(void *, unsigned char *, size_t),
                  void *p_entropy,
                  const unsigned char *custom,
                  size_t len );
/**
 * \brief               This function seeds and sets up the CTR_DRBG
 *                      entropy source for future reseeds.
 *
 * \note Personalization data can be provided in addition to the more generic
 *       entropy source, to make this instantiation as unique as possible.
 *
 * \param ctx           The CTR_DRBG context to seed.
 * \param f_entropy     The entropy callback, taking as arguments the
 *                      \p p_entropy context, the buffer to fill, and the
                        length of the buffer.
 * \param p_entropy     The entropy context.
 * \param custom        Personalization data, that is device-specific
                        identifiers. Can be NULL.
 * \param len           The length of the personalization data.
 *
 * \return              \c 0 on success.
 * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
 */

Func mbedtls_ctr_drbg_free

void mbedtls_ctr_drbg_free( mbedtls_ctr_drbg_context *ctx );
/**
 * \brief               This function clears CTR_CRBG context data.
 *
 * \param ctx           The CTR_DRBG context to clear.
 */

Func mbedtls_ctr_drbg_set_prediction_resistance

void mbedtls_ctr_drbg_set_prediction_resistance( mbedtls_ctr_drbg_context *ctx,
                                        int resistance );
/**
 * \brief               This function turns prediction resistance on or off.
 *                      The default value is off.
 *
 * \note                If enabled, entropy is gathered at the beginning of
 *                      every call to mbedtls_ctr_drbg_random_with_add().
 *                      Only use this if your entropy source has sufficient
 *                      throughput.
 *
 * \param ctx           The CTR_DRBG context.
 * \param resistance    #MBEDTLS_CTR_DRBG_PR_ON or #MBEDTLS_CTR_DRBG_PR_OFF.
 */

Func mbedtls_ctr_drbg_set_entropy_len

void mbedtls_ctr_drbg_set_entropy_len( mbedtls_ctr_drbg_context *ctx,
                              size_t len );
/**
 * \brief               This function sets the amount of entropy grabbed on each
 *                      seed or reseed. The default value is
 *                      #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
 *
 * \param ctx           The CTR_DRBG context.
 * \param len           The amount of entropy to grab.
 */

Func mbedtls_ctr_drbg_set_reseed_interval

void mbedtls_ctr_drbg_set_reseed_interval( mbedtls_ctr_drbg_context *ctx,
                                  int interval );
/**
 * \brief               This function sets the reseed interval.
 *                      The default value is #MBEDTLS_CTR_DRBG_RESEED_INTERVAL.
 *
 * \param ctx           The CTR_DRBG context.
 * \param interval      The reseed interval.
 */

Func mbedtls_ctr_drbg_reseed

int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx,
                    const unsigned char *additional, size_t len );
/**
 * \brief               This function reseeds the CTR_DRBG context, that is
 *                      extracts data from the entropy source.
 *
 * \param ctx           The CTR_DRBG context.
 * \param additional    Additional data to add to the state. Can be NULL.
 * \param len           The length of the additional data.
 *
 * \return              \c 0 on success.
 * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
 */

Func mbedtls_ctr_drbg_update_ret

int mbedtls_ctr_drbg_update_ret( mbedtls_ctr_drbg_context *ctx,
                                const unsigned char *additional,
                                size_t add_len );
/**
 * \brief              This function updates the state of the CTR_DRBG context.
 *
 * \param ctx          The CTR_DRBG context.
 * \param additional   The data to update the state with.
 * \param add_len      Length of \p additional in bytes. This must be at
 *                     most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
 *
 * \return             \c 0 on success.
 * \return             #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if
 *                     \p add_len is more than
 *                     #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
 * \return             An error from the underlying AES cipher on failure.
 */

Func mbedtls_ctr_drbg_random_with_add

int mbedtls_ctr_drbg_random_with_add( void *p_rng,
                             unsigned char *output, size_t output_len,
                             const unsigned char *additional, size_t add_len );
/**
 * \brief   This function updates a CTR_DRBG instance with additional
 *          data and uses it to generate random data.
 *
 * \note    The function automatically reseeds if the reseed counter is exceeded.
 *
 * \param p_rng         The CTR_DRBG context. This must be a pointer to a
 *                      #mbedtls_ctr_drbg_context structure.
 * \param output        The buffer to fill.
 * \param output_len    The length of the buffer.
 * \param additional    Additional data to update. Can be NULL.
 * \param add_len       The length of the additional data.
 *
 * \return    \c 0 on success.
 * \return    #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
 *            #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
 */

Func mbedtls_ctr_drbg_random

int mbedtls_ctr_drbg_random( void *p_rng,
                    unsigned char *output, size_t output_len );
/**
 * \brief   This function uses CTR_DRBG to generate random data.
 *
 * \note    The function automatically reseeds if the reseed counter is exceeded.
 *
 * \param p_rng         The CTR_DRBG context. This must be a pointer to a
 *                      #mbedtls_ctr_drbg_context structure.
 * \param output        The buffer to fill.
 * \param output_len    The length of the buffer.
 *
 * \return              \c 0 on success.
 * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
 *                      #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
 */

Func mbedtls_ctr_drbg_write_seed_file

int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
/**
 * \brief               This function writes a seed file.
 *
 * \param ctx           The CTR_DRBG context.
 * \param path          The name of the file.
 *
 * \return              \c 0 on success.
 * \return              #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
 * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on
 *                      failure.
 */

Func mbedtls_ctr_drbg_update_seed_file

int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
/**
 * \brief               This function reads and updates a seed file. The seed
 *                      is added to this instance.
 *
 * \param ctx           The CTR_DRBG context.
 * \param path          The name of the file.
 *
 * \return              \c 0 on success.
 * \return              #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
 * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
 *                      #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG on failure.
 */

Func mbedtls_ctr_drbg_self_test

int mbedtls_ctr_drbg_self_test( int verbose );
/**
 * \brief               The CTR_DRBG checkup routine.
 *
 * \return              \c 0 on success.
 * \return              \c 1 on failure.
 */

Func mbedtls_ctr_drbg_seed_entropy_len

int mbedtls_ctr_drbg_seed_entropy_len( mbedtls_ctr_drbg_context *,
                              int (*)(void *, unsigned char *, size_t), void *,
                              const unsigned char *, size_t, size_t );
/* Internal functions (do not call directly) */

Vars

Variable MBEDTLS_DEPRECATED

MBEDTLS_DEPRECATED void mbedtls_ctr_drbg_update(
   mbedtls_ctr_drbg_context *ctx,
   const unsigned char *additional,
   size_t add_len );
/**
 * \brief              This function updates the state of the CTR_DRBG context.
 *
 * \deprecated         Superseded by mbedtls_ctr_drbg_update_ret()
 *                     in 2.16.0.
 *
 * \note               If \p add_len is greater than
 *                     #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, only the first
 *                     #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used.
 *                     The remaining Bytes are silently discarded.
 *
 * \param ctx          The CTR_DRBG context.
 * \param additional   The data to update the state with.
 * \param add_len      Length of \p additional data.
 */

Consts

Types

Typedefs

Typedef mbedtls_ctr_drbg_context;

typedef struct mbedtls_ctr_drbg_context
{
   unsigned char counter[16]; /*!< The counter (V). */
   int reseed_counter;        /*!< The reseed counter. */
   int prediction_resistance; /*!< This determines whether prediction
                                     resistance is enabled, that is
                                     whether to systematically reseed before
                                     each random generation. */
   size_t entropy_len;        /*!< The amount of entropy grabbed on each
                                     seed or reseed operation. */
   int reseed_interval;       /*!< The reseed interval. */

   mbedtls_aes_context aes_ctx;       /*!< The AES context. */

   /*
     * Callbacks (Entropy)
     */
   int (*f_entropy)(void *, unsigned char *, size_t);
                               /*!< The entropy callback function. */

   void *p_entropy;           /*!< The context for the entropy function. */

#if defined(MBEDTLS_THREADING_C)
   mbedtls_threading_mutex_t mutex;
#endif
}
mbedtls_ctr_drbg_context;
/**
 * \brief          The CTR_DRBG context structure.
 */