Entropy accumulator implementation. More...

#include "mbedtls/private_access.h"
#include "mbedtls/build_info.h"
#include <stddef.h>
#include "mbedtls/sha256.h"
#include "mbedtls/threading.h"

Include dependency graph for entropy.h:

Go to the source code of this file.

Data Structures
struct	mbedtls_entropy_source_state
	Entropy source state. More...

struct	mbedtls_entropy_context
	Entropy context structure. More...

Macros
#define	MBEDTLS_ENTROPY_SHA256_ACCUMULATOR

#define	MBEDTLS_ERR_ENTROPY_SOURCE_FAILED -0x003C

#define	MBEDTLS_ERR_ENTROPY_MAX_SOURCES -0x003E

#define	MBEDTLS_ERR_ENTROPY_NO_SOURCES_DEFINED -0x0040

#define	MBEDTLS_ERR_ENTROPY_NO_STRONG_SOURCE -0x003D

#define	MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR -0x003F

#define	MBEDTLS_ENTROPY_BLOCK_SIZE 32

#define	MBEDTLS_ENTROPY_MAX_SEED_SIZE 1024

#define	MBEDTLS_ENTROPY_SOURCE_MANUAL MBEDTLS_ENTROPY_MAX_SOURCES

#define	MBEDTLS_ENTROPY_SOURCE_STRONG 1

#define	MBEDTLS_ENTROPY_SOURCE_WEAK 0

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.
#define	MBEDTLS_ENTROPY_MAX_SOURCES 20

#define	MBEDTLS_ENTROPY_MAX_GATHER 128

Typedefs
typedef int(*	mbedtls_entropy_f_source_ptr )(void data, unsigned char output, size_t len, size_t *olen)
	Entropy poll callback pointer. More...

typedef struct mbedtls_entropy_source_state	mbedtls_entropy_source_state
	Entropy source state. More...

typedef struct mbedtls_entropy_context	mbedtls_entropy_context
	Entropy context structure. More...

Functions
void	mbedtls_entropy_init (mbedtls_entropy_context *ctx)
	Initialize the context. More...

void	mbedtls_entropy_free (mbedtls_entropy_context *ctx)
	Free the data in the context. More...

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) More...

int	mbedtls_entropy_gather (mbedtls_entropy_context *ctx)
	Trigger an extra gather poll for the accumulator (Thread-safe if MBEDTLS_THREADING_C is enabled) More...

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) More...

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) More...

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

int	mbedtls_entropy_write_seed_file (mbedtls_entropy_context ctx, const char path)
	Write a seed file. More...

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

int	mbedtls_entropy_self_test (int verbose)
	Checkup routine. More...

int	mbedtls_entropy_source_self_test (int verbose)
	Checkup routine. More...

Detailed Description

Entropy accumulator implementation.

Definition in file entropy.h.

Macro Definition Documentation

#define MBEDTLS_ENTROPY_BLOCK_SIZE 32

Block size of entropy accumulator (SHA-256)

Definition at line 77 of file entropy.h.

#define MBEDTLS_ENTROPY_MAX_GATHER 128

Maximum amount requested from entropy sources

Definition at line 69 of file entropy.h.

#define MBEDTLS_ENTROPY_MAX_SEED_SIZE 1024

Maximum size of seed we read from seed file

Definition at line 80 of file entropy.h.

#define MBEDTLS_ENTROPY_MAX_SOURCES 20

Maximum number of sources supported

Definition at line 65 of file entropy.h.

#define MBEDTLS_ENTROPY_SHA256_ACCUMULATOR

Definition at line 35 of file entropy.h.

#define MBEDTLS_ENTROPY_SOURCE_MANUAL MBEDTLS_ENTROPY_MAX_SOURCES

Definition at line 81 of file entropy.h.

#define MBEDTLS_ENTROPY_SOURCE_STRONG 1

Entropy source is strong

Definition at line 83 of file entropy.h.

#define MBEDTLS_ENTROPY_SOURCE_WEAK 0

Entropy source is weak

Definition at line 84 of file entropy.h.

#define MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR -0x003F

Read/write error in file.

Definition at line 54 of file entropy.h.

#define MBEDTLS_ERR_ENTROPY_MAX_SOURCES -0x003E

No more sources can be added.

Definition at line 48 of file entropy.h.

#define MBEDTLS_ERR_ENTROPY_NO_SOURCES_DEFINED -0x0040

No sources have been added to poll.

Definition at line 50 of file entropy.h.

#define MBEDTLS_ERR_ENTROPY_NO_STRONG_SOURCE -0x003D

No strong sources have been added to poll.

Definition at line 52 of file entropy.h.

#define MBEDTLS_ERR_ENTROPY_SOURCE_FAILED -0x003C

Critical entropy source failure.

Definition at line 46 of file entropy.h.

Typedef Documentation

typedef struct mbedtls_entropy_context mbedtls_entropy_context

Entropy context structure.

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

Entropy poll callback pointer.

Parameters

data	Callback-specific data pointer
output	Data to fill
len	Maximum size to provide
olen	The actual amount of bytes put into the buffer (Can be 0)

Returns: 0 if no critical failures occurred, MBEDTLS_ERR_ENTROPY_SOURCE_FAILED otherwise

Definition at line 101 of file entropy.h.

typedef struct mbedtls_entropy_source_state mbedtls_entropy_source_state

Entropy source state.

Function Documentation

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

void mbedtls_entropy_free ( mbedtls_entropy_context * ctx )

Free the data in the context.

Parameters

ctx	Entropy context to free

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_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

void mbedtls_entropy_init ( mbedtls_entropy_context * ctx )

Initialize the context.

Parameters

ctx	Entropy context to initialize

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

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_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_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

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation