File entropy.h

Entropy accumulator implementation.

SECTION: Module settings

The configuration options you can set for this module are in this section. Either change them in mbedtls_config.h or define them on the compiler command line.

MBEDTLS_ENTROPY_MAX_SOURCES

Maximum number of sources supported

MBEDTLS_ENTROPY_MAX_GATHER

Maximum amount requested from entropy sources

Defines

MBEDTLS_ENTROPY_SHA256_ACCUMULATOR
MBEDTLS_ENTROPY_MD
MBEDTLS_ENTROPY_BLOCK_SIZE

Block size of entropy accumulator (SHA-256)

MBEDTLS_ERR_ENTROPY_SOURCE_FAILED

Critical entropy source failure.

MBEDTLS_ERR_ENTROPY_MAX_SOURCES

No more sources can be added.

MBEDTLS_ERR_ENTROPY_NO_SOURCES_DEFINED

No sources have been added to poll.

MBEDTLS_ERR_ENTROPY_NO_STRONG_SOURCE

No strong sources have been added to poll.

MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR

Read/write error in file.

MBEDTLS_ENTROPY_MAX_SEED_SIZE

Maximum size of seed we read from seed file

MBEDTLS_ENTROPY_SOURCE_MANUAL
MBEDTLS_ENTROPY_SOURCE_STRONG

Entropy source is strong

MBEDTLS_ENTROPY_SOURCE_WEAK

Entropy source is weak

Typedefs

typedef int (*mbedtls_entropy_f_source_ptr)(void *data, unsigned char *output, size_t len, size_t *olen)

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 struct mbedtls_entropy_source_state mbedtls_entropy_source_state

Entropy source state.

typedef struct mbedtls_entropy_context mbedtls_entropy_context

Entropy context structure.

Functions

void mbedtls_entropy_init(mbedtls_entropy_context *ctx)

Initialize the context.

Parameters

ctx – Entropy context to initialize

void mbedtls_entropy_free(mbedtls_entropy_context *ctx)

Free the data in the context.

Parameters

ctx – Entropy context to free

int mbedtls_entropy_add_source(mbedtls_entropy_context *ctx, mbedtls_entropy_f_source_ptr f_source, void *p_source, size_t threshold, int strong)

Adds an entropy source to poll (Thread-safe if MBEDTLS_THREADING_C is enabled)

Parameters

  • ctx – Entropy context

  • f_source – Entropy function

  • p_source – Function data

  • threshold – Minimum required from source before entropy is released ( with mbedtls_entropy_func() ) (in bytes)

  • 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.

Returns

0 if successful or MBEDTLS_ERR_ENTROPY_MAX_SOURCES

int mbedtls_entropy_gather(mbedtls_entropy_context *ctx)

Trigger an extra gather poll for the accumulator (Thread-safe if MBEDTLS_THREADING_C is enabled)

Parameters

ctx – Entropy context

Returns

0 if successful, or MBEDTLS_ERR_ENTROPY_SOURCE_FAILED

int mbedtls_entropy_func(void *data, unsigned char *output, size_t len)

Retrieve entropy from the accumulator (Maximum length: MBEDTLS_ENTROPY_BLOCK_SIZE) (Thread-safe if MBEDTLS_THREADING_C is enabled)

Parameters

  • data – Entropy context

  • output – Buffer to fill

  • len – Number of bytes desired, must be at most MBEDTLS_ENTROPY_BLOCK_SIZE

Returns

0 if successful, or MBEDTLS_ERR_ENTROPY_SOURCE_FAILED

int mbedtls_entropy_update_manual(mbedtls_entropy_context *ctx, const unsigned char *data, size_t len)

Add data to the accumulator manually (Thread-safe if MBEDTLS_THREADING_C is enabled)

Parameters

  • ctx – Entropy context

  • data – Data to add

  • len – Length of data

Returns

0 if successful

int mbedtls_entropy_update_nv_seed(mbedtls_entropy_context *ctx)

Trigger an update of the seed file in NV by using the current entropy pool.

Parameters

ctx – Entropy context

Returns

0 if successful

int mbedtls_entropy_write_seed_file(mbedtls_entropy_context *ctx, const char *path)

Write a seed file.

Parameters

  • ctx – Entropy context

  • path – Name of the file

Returns

0 if successful, MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR on file error, or MBEDTLS_ERR_ENTROPY_SOURCE_FAILED

int mbedtls_entropy_update_seed_file(mbedtls_entropy_context *ctx, const char *path)

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.

Parameters

  • ctx – Entropy context

  • path – Name of the file

Returns

0 if successful, MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR on file error, MBEDTLS_ERR_ENTROPY_SOURCE_FAILED

int mbedtls_entropy_self_test(int verbose)

Checkup routine. 

            This module self-test also calls the entropy self-test,
            mbedtls_entropy_source_self_test();
Returns

0 if successful, or 1 if a test failed

int mbedtls_entropy_source_self_test(int verbose)

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.
Returns

0 if successful, or 1 if a test failed

struct mbedtls_entropy_source_state
#include <entropy.h>

Entropy source state.

Public Members

mbedtls_entropy_f_source_ptr private_f_source

The entropy source callback

void *private_p_source

The callback data pointer

size_t private_size

Amount received in bytes

size_t private_threshold

Minimum bytes required before release

int private_strong

Is the source strong?

struct mbedtls_entropy_context
#include <entropy.h>

Entropy context structure.

Public Members

mbedtls_md_context_t private_accumulator
int private_accumulator_started
int private_source_count
mbedtls_entropy_source_state private_source[MBEDTLS_ENTROPY_MAX_SOURCES]
mbedtls_threading_mutex_t private_mutex

mutex

int private_initial_entropy_run