Documentation

Documentation

Includes

config.h

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

MBEDTLS_CONFIG_FILE

#include MBEDTLS_CONFIG_FILE
#include MBEDTLS_CONFIG_FILE

stddef.h

#include <stddef.h>
#include 

sha512.h

#include "sha512.h"
#include "sha512.h"

sha256.h

#include "sha256.h"
#include "sha256.h"

threading.h

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

havege.h

#include "havege.h"
#include "havege.h"

Macros

Marco MBEDTLS_ENTROPY_H

#define MBEDTLS_ENTROPY_H


      

Marco MBEDTLS_ENTROPY_SHA512_ACCUMULATOR

#define MBEDTLS_ENTROPY_SHA512_ACCUMULATOR


      

Marco MBEDTLS_ENTROPY_SHA256_ACCUMULATOR

#define MBEDTLS_ENTROPY_SHA256_ACCUMULATOR


      

Marco MBEDTLS_ERR_ENTROPY_SOURCE_FAILED

#define MBEDTLS_ERR_ENTROPY_SOURCE_FAILED                -3C /**< Critical entropy source failure. */


      

Marco MBEDTLS_ERR_ENTROPY_MAX_SOURCES

#define MBEDTLS_ERR_ENTROPY_MAX_SOURCES                  -3E /**< No more sources can be added. */


      

Marco MBEDTLS_ERR_ENTROPY_NO_SOURCES_DEFINED

#define MBEDTLS_ERR_ENTROPY_NO_SOURCES_DEFINED           -64 /**< No sources have been added to poll. */


      

Marco MBEDTLS_ERR_ENTROPY_NO_STRONG_SOURCE

#define MBEDTLS_ERR_ENTROPY_NO_STRONG_SOURCE             -3D /**< No strong sources have been added to poll. */


      

Marco MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR

#define MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR                -63 /**< Read/write error in file. */


      

Marco MBEDTLS_ENTROPY_MAX_SOURCES

#define MBEDTLS_ENTROPY_MAX_SOURCES    20     /**< Maximum number of sources supported */


      

Marco MBEDTLS_ENTROPY_MAX_GATHER

#define MBEDTLS_ENTROPY_MAX_GATHER     128    /**< Maximum amount requested from entropy sources */


      

Marco MBEDTLS_ENTROPY_BLOCK_SIZE

#define MBEDTLS_ENTROPY_BLOCK_SIZE     64     /**< Block size of entropy accumulator (SHA-512) */


      

Marco MBEDTLS_ENTROPY_BLOCK_SIZE

#define MBEDTLS_ENTROPY_BLOCK_SIZE     32     /**< Block size of entropy accumulator (SHA-256) */


      

Marco MBEDTLS_ENTROPY_MAX_SEED_SIZE

#define MBEDTLS_ENTROPY_MAX_SEED_SIZE  1024   /**< Maximum size of seed we read from seed file */


      

Marco MBEDTLS_ENTROPY_SOURCE_MANUAL

#define MBEDTLS_ENTROPY_SOURCE_MANUAL  MBEDTLS_ENTROPY_MAX_SOURCES


      

Marco MBEDTLS_ENTROPY_SOURCE_STRONG

#define MBEDTLS_ENTROPY_SOURCE_STRONG  1      /**< Entropy source is strong   */


      

Marco MBEDTLS_ENTROPY_SOURCE_WEAK

#define MBEDTLS_ENTROPY_SOURCE_WEAK    0      /**< Entropy source is weak     */

      

Functions

Func mbedtls_entropy_init

void mbedtls_entropy_init( mbedtls_entropy_context *ctx );
/**
 * \brief           Initialize the context
 *
 * \param ctx       Entropy context to initialize
 */

Func mbedtls_entropy_free

void mbedtls_entropy_free( mbedtls_entropy_context *ctx );
/**
 * \brief           Free the data in the context
 *
 * \param ctx       Entropy context to free
 */

Func mbedtls_entropy_add_source

int mbedtls_entropy_add_source( mbedtls_entropy_context *ctx,
                       mbedtls_entropy_f_source_ptr f_source, void *p_source,
                       size_t threshold, int strong );
/**
 * \brief           Adds an entropy source to poll
 *                  (Thread-safe if MBEDTLS_THREADING_C is enabled)
 *
 * \param ctx       Entropy context
 * \param f_source  Entropy function
 * \param p_source  Function data
 * \param threshold Minimum required from source before entropy is released
 *                  ( with mbedtls_entropy_func() ) (in bytes)
 * \param strong    MBEDTLS_ENTROPY_SOURCE_STRONG or
 *                  MBEDTLS_ENTROPY_SOURCE_WEAK.
 *                  At least one strong source needs to be added.
 *                  Weaker sources (such as the cycle counter) can be used as
 *                  a complement.
 *
 * \return          0 if successful or MBEDTLS_ERR_ENTROPY_MAX_SOURCES
 */

Func mbedtls_entropy_gather

int mbedtls_entropy_gather( mbedtls_entropy_context *ctx );
/**
 * \brief           Trigger an extra gather poll for the accumulator
 *                  (Thread-safe if MBEDTLS_THREADING_C is enabled)
 *
 * \param ctx       Entropy context
 *
 * \return          0 if successful, or MBEDTLS_ERR_ENTROPY_SOURCE_FAILED
 */

Func mbedtls_entropy_func

int mbedtls_entropy_func( void *data, unsigned char *output, size_t len );
/**
 * \brief           Retrieve entropy from the accumulator
 *                  (Maximum length: MBEDTLS_ENTROPY_BLOCK_SIZE)
 *                  (Thread-safe if MBEDTLS_THREADING_C is enabled)
 *
 * \param data      Entropy context
 * \param output    Buffer to fill
 * \param len       Number of bytes desired, must be at most MBEDTLS_ENTROPY_BLOCK_SIZE
 *
 * \return          0 if successful, or MBEDTLS_ERR_ENTROPY_SOURCE_FAILED
 */

Func mbedtls_entropy_update_manual

int mbedtls_entropy_update_manual( mbedtls_entropy_context *ctx,
                          const unsigned char *data, size_t len );
/**
 * \brief           Add data to the accumulator manually
 *                  (Thread-safe if MBEDTLS_THREADING_C is enabled)
 *
 * \param ctx       Entropy context
 * \param data      Data to add
 * \param len       Length of data
 *
 * \return          0 if successful
 */

Func mbedtls_entropy_update_nv_seed

int mbedtls_entropy_update_nv_seed( mbedtls_entropy_context *ctx );
/**
 * \brief           Trigger an update of the seed file in NV by using the
 *                  current entropy pool.
 *
 * \param ctx       Entropy context
 *
 * \return          0 if successful
 */

Func mbedtls_entropy_write_seed_file

int mbedtls_entropy_write_seed_file( mbedtls_entropy_context *ctx, const char *path );
/**
 * \brief               Write a seed file
 *
 * \param ctx           Entropy context
 * \param path          Name of the file
 *
 * \return              0 if successful,
 *                      MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR on file error, or
 *                      MBEDTLS_ERR_ENTROPY_SOURCE_FAILED
 */

Func mbedtls_entropy_update_seed_file

int mbedtls_entropy_update_seed_file( mbedtls_entropy_context *ctx, const char *path );
/**
 * \brief               Read and update a seed file. Seed is added to this
 *                      instance. No more than MBEDTLS_ENTROPY_MAX_SEED_SIZE bytes are
 *                      read from the seed file. The rest is ignored.
 *
 * \param ctx           Entropy context
 * \param path          Name of the file
 *
 * \return              0 if successful,
 *                      MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR on file error,
 *                      MBEDTLS_ERR_ENTROPY_SOURCE_FAILED
 */

Func mbedtls_entropy_self_test

int mbedtls_entropy_self_test( int verbose );
/**
 * \brief          Checkup routine
 *
 *                 This module self-test also calls the entropy self-test,
 *                 mbedtls_entropy_source_self_test();
 *
 * \return         0 if successful, or 1 if a test failed
 */

Func mbedtls_entropy_source_self_test

int mbedtls_entropy_source_self_test( int verbose );
/**
 * \brief          Checkup routine
 *
 *                 Verifies the integrity of the hardware entropy source
 *                 provided by the function 'mbedtls_hardware_poll()'.
 *
 *                 Note this is the only hardware entropy source that is known
 *                 at link time, and other entropy sources configured
 *                 dynamically at runtime by the function
 *                 mbedtls_entropy_add_source() will not be tested.
 *
 * \return         0 if successful, or 1 if a test failed
 */

Vars

Consts

Types

Typedefs

Typedef mbedtls_entropy_f_source_ptr

typedef int (*mbedtls_entropy_f_source_ptr)(void *data, unsigned char *output, size_t len,
                           size_t *olen);
/**
 * \brief           Entropy poll callback pointer
 *
 * \param data      Callback-specific data pointer
 * \param output    Data to fill
 * \param len       Maximum size to provide
 * \param olen      The actual amount of bytes put into the buffer (Can be 0)
 *
 * \return          0 if no critical failures occurred,
 *                  MBEDTLS_ERR_ENTROPY_SOURCE_FAILED otherwise
 */

Typedef mbedtls_entropy_source_state;

typedef struct mbedtls_entropy_source_state
{
   mbedtls_entropy_f_source_ptr   f_source;  /**< The entropy source callback */
   void *         p_source;  /**< The callback data pointer */
   size_t         size;      /**< Amount received in bytes */
   size_t         threshold; /**< Minimum bytes required before release */
   int            strong;    /**< Is the source strong? */
}
mbedtls_entropy_source_state;
/**
 * \brief           Entropy source state
 */

Typedef mbedtls_entropy_context;

typedef struct mbedtls_entropy_context
{
   int accumulator_started;
#if defined(MBEDTLS_ENTROPY_SHA512_ACCUMULATOR)
   mbedtls_sha512_context accumulator;
#else
   mbedtls_sha256_context accumulator;
#endif
   int            source_count;
   mbedtls_entropy_source_state   source[MBEDTLS_ENTROPY_MAX_SOURCES];
#if defined(MBEDTLS_HAVEGE_C)
   mbedtls_havege_state   havege_data;
#endif
#if defined(MBEDTLS_THREADING_C)
   mbedtls_threading_mutex_t mutex;   /*!< mutex                  */
#endif
#if defined(MBEDTLS_ENTROPY_NV_SEED)
   int initial_entropy_run;
#endif
}
mbedtls_entropy_context;
/**
 * \brief           Entropy context structure
 */