Entropy Accumulator

Data Structures
struct	mbedtls_entropy_source_state
	Entropy source state. More...
struct	mbedtls_entropy_context
	Entropy context structure. More...

Macros
#define	MBEDTLS_ERR_ENTROPY_SOURCE_FAILED   -0x003C
	Critical entropy source failure.
#define	MBEDTLS_ERR_ENTROPY_MAX_SOURCES   -0x003E
	No more sources can be added.
#define	MBEDTLS_ERR_ENTROPY_NO_SOURCES_DEFINED   -0x0040
	No sources have been added to poll.
#define	MBEDTLS_ERR_ENTROPY_NO_STRONG_SOURCE   -0x003D
	No strong sources have been added to poll.
#define	MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR   -0x003F
	Read/write error in file.
#define	MBEDTLS_ENTROPY_BLOCK_SIZE   32
	Block size of entropy accumulator (SHA-256)
#define	MBEDTLS_ENTROPY_MAX_SEED_SIZE   1024
	Maximum size of seed we read from seed file.
#define	MBEDTLS_ENTROPY_SOURCE_STRONG   1
	Entropy source is strong
#define	MBEDTLS_ENTROPY_SOURCE_WEAK   0
	Entropy source is weak
#define	MBEDTLS_ENTROPY_MIN_PLATFORM   32
	Minimum for platform source
#define	MBEDTLS_ENTROPY_MIN_HAVEGE   32
	Minimum for HAVEGE
#define	MBEDTLS_ENTROPY_MIN_HARDCLOCK   4
	Minimum for mbedtls_timing_hardclock()
#define	MBEDTLS_ENTROPY_MIN_HARDWARE   32
	Minimum for the hardware source.

Typedefs
typedef int(*	mbedtls_entropy_f_source_ptr) (void *data, unsigned char *output, size_t len, size_t *olen)
	Entropy poll callback pointer.
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.
void	mbedtls_entropy_free (mbedtls_entropy_context *ctx)
	Free the data in the context.
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)
int	mbedtls_entropy_gather (mbedtls_entropy_context *ctx)
	Trigger an extra gather poll for the accumulator (Thread-safe if MBEDTLS_THREADING_C is enabled)
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)
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)
int	mbedtls_platform_entropy_poll (void *data, unsigned char *output, size_t len, size_t *olen)
	Entropy poll callback that provides 0 entropy.

SECTION: Module settings
The configuration options you can set for this module are in this section. Either change them in config.h or define them on the compiler command line.
#define	MBEDTLS_ENTROPY_MAX_SOURCES   20
	Maximum number of sources supported.
#define	MBEDTLS_ENTROPY_MAX_GATHER   128
	Maximum amount requested from entropy sources.

Detailed Description

Macro Definition Documentation

MBEDTLS_ERR_ENTROPY_SOURCE_FAILED

#define MBEDTLS_ERR_ENTROPY_SOURCE_FAILED   -0x003C

Critical entropy source failure.

Definition at line 58 of file entropy.h.

MBEDTLS_ERR_ENTROPY_MAX_SOURCES

#define MBEDTLS_ERR_ENTROPY_MAX_SOURCES   -0x003E

No more sources can be added.

Definition at line 59 of file entropy.h.

MBEDTLS_ERR_ENTROPY_NO_SOURCES_DEFINED

#define MBEDTLS_ERR_ENTROPY_NO_SOURCES_DEFINED   -0x0040

No sources have been added to poll.

Definition at line 60 of file entropy.h.

MBEDTLS_ERR_ENTROPY_NO_STRONG_SOURCE

#define MBEDTLS_ERR_ENTROPY_NO_STRONG_SOURCE   -0x003D

No strong sources have been added to poll.

Definition at line 61 of file entropy.h.

MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR

#define MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR   -0x003F

Read/write error in file.

Definition at line 62 of file entropy.h.

MBEDTLS_ENTROPY_MAX_SOURCES

#define MBEDTLS_ENTROPY_MAX_SOURCES   20

Maximum number of sources supported.

Definition at line 73 of file entropy.h.

MBEDTLS_ENTROPY_MAX_GATHER

#define MBEDTLS_ENTROPY_MAX_GATHER   128

Maximum amount requested from entropy sources.

Definition at line 77 of file entropy.h.

MBEDTLS_ENTROPY_BLOCK_SIZE

#define MBEDTLS_ENTROPY_BLOCK_SIZE   32

Block size of entropy accumulator (SHA-256)

Definition at line 85 of file entropy.h.

MBEDTLS_ENTROPY_MAX_SEED_SIZE

#define MBEDTLS_ENTROPY_MAX_SEED_SIZE   1024

Maximum size of seed we read from seed file.

Definition at line 88 of file entropy.h.

MBEDTLS_ENTROPY_SOURCE_STRONG

#define MBEDTLS_ENTROPY_SOURCE_STRONG   1

Entropy source is strong

Definition at line 91 of file entropy.h.

MBEDTLS_ENTROPY_SOURCE_WEAK

#define MBEDTLS_ENTROPY_SOURCE_WEAK   0

Entropy source is weak

Definition at line 92 of file entropy.h.

MBEDTLS_ENTROPY_MIN_PLATFORM

#define MBEDTLS_ENTROPY_MIN_PLATFORM   32

Minimum for platform source

Definition at line 45 of file entropy_poll.h.

MBEDTLS_ENTROPY_MIN_HAVEGE

#define MBEDTLS_ENTROPY_MIN_HAVEGE   32

Minimum for HAVEGE

Definition at line 46 of file entropy_poll.h.

MBEDTLS_ENTROPY_MIN_HARDCLOCK

#define MBEDTLS_ENTROPY_MIN_HARDCLOCK   4

Minimum for mbedtls_timing_hardclock()

Definition at line 47 of file entropy_poll.h.

MBEDTLS_ENTROPY_MIN_HARDWARE

#define MBEDTLS_ENTROPY_MIN_HARDWARE   32

Minimum for the hardware source.

Definition at line 49 of file entropy_poll.h.

Typedef Documentation

mbedtls_entropy_f_source_ptr

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 109 of file entropy.h.

mbedtls_entropy_source_state

typedef struct mbedtls_entropy_source_state mbedtls_entropy_source_state

Entropy source state.

mbedtls_entropy_context

typedef struct mbedtls_entropy_context mbedtls_entropy_context

Entropy context structure.

Function Documentation

mbedtls_entropy_init()

void mbedtls_entropy_init

(

mbedtls_entropy_context *

ctx

)

Initialize the context.

Parameters

ctx	Entropy context to initialize

mbedtls_entropy_free()

void mbedtls_entropy_free

(

mbedtls_entropy_context *

ctx

)

Free the data in the context.

Parameters

ctx	Entropy context to free

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
	)

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

mbedtls_entropy_gather()

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

mbedtls_entropy_func()

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

mbedtls_entropy_update_manual()

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

mbedtls_platform_entropy_poll()

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

Entropy poll callback that provides 0 entropy.

Platform-specific entropy poll callback