Mbed TLS v2.28.9
Loading...
Searching...
No Matches
entropy.h File Reference

Entropy accumulator implementation. More...

#include "mbedtls/config.h"
#include <stddef.h>
#include "mbedtls/sha512.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_SHA512_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   64
 
#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 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.
 
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_entropy_write_seed_file (mbedtls_entropy_context *ctx, const char *path)
 Write a seed file.
 
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.
 
int mbedtls_entropy_self_test (int verbose)
 Checkup routine.
 

Detailed Description

Entropy accumulator implementation.

Definition in file entropy.h.

Macro Definition Documentation

◆ MBEDTLS_ENTROPY_BLOCK_SIZE

#define MBEDTLS_ENTROPY_BLOCK_SIZE   64

Block size of entropy accumulator (SHA-512)

Definition at line 69 of file entropy.h.

◆ MBEDTLS_ENTROPY_MAX_GATHER

#define MBEDTLS_ENTROPY_MAX_GATHER   128

Maximum amount requested from entropy sources

Definition at line 63 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 74 of file entropy.h.

◆ MBEDTLS_ENTROPY_MAX_SOURCES

#define MBEDTLS_ENTROPY_MAX_SOURCES   20

Maximum number of sources supported

Definition at line 59 of file entropy.h.

◆ MBEDTLS_ENTROPY_SHA512_ACCUMULATOR

#define MBEDTLS_ENTROPY_SHA512_ACCUMULATOR

Definition at line 23 of file entropy.h.

◆ MBEDTLS_ENTROPY_SOURCE_MANUAL

#define MBEDTLS_ENTROPY_SOURCE_MANUAL   MBEDTLS_ENTROPY_MAX_SOURCES

Definition at line 75 of file entropy.h.

◆ MBEDTLS_ENTROPY_SOURCE_STRONG

#define MBEDTLS_ENTROPY_SOURCE_STRONG   1

Entropy source is strong

Definition at line 77 of file entropy.h.

◆ MBEDTLS_ENTROPY_SOURCE_WEAK

#define MBEDTLS_ENTROPY_SOURCE_WEAK   0

Entropy source is weak

Definition at line 78 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 48 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 42 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 44 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 46 of file entropy.h.

◆ MBEDTLS_ERR_ENTROPY_SOURCE_FAILED

#define MBEDTLS_ERR_ENTROPY_SOURCE_FAILED   -0x003C

Critical entropy source failure.

Definition at line 40 of file entropy.h.

Typedef Documentation

◆ mbedtls_entropy_context

typedef struct mbedtls_entropy_context mbedtls_entropy_context

Entropy context structure.

◆ 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
dataCallback-specific data pointer
outputData to fill
lenMaximum size to provide
olenThe 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 95 of file entropy.h.

◆ mbedtls_entropy_source_state

typedef struct mbedtls_entropy_source_state mbedtls_entropy_source_state

Entropy source state.

Function Documentation

◆ 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
ctxEntropy context
f_sourceEntropy function
p_sourceFunction data
thresholdMinimum required from source before entropy is released ( with mbedtls_entropy_func() ) (in bytes)
strongMBEDTLS_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_free()

void mbedtls_entropy_free ( mbedtls_entropy_context * ctx)

Free the data in the context.

Parameters
ctxEntropy context to free

◆ 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
dataEntropy context
outputBuffer to fill
lenNumber of bytes desired, must be at most MBEDTLS_ENTROPY_BLOCK_SIZE
Returns
0 if successful, or MBEDTLS_ERR_ENTROPY_SOURCE_FAILED

◆ 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
ctxEntropy context
Returns
0 if successful, or MBEDTLS_ERR_ENTROPY_SOURCE_FAILED

◆ mbedtls_entropy_init()

void mbedtls_entropy_init ( mbedtls_entropy_context * ctx)

Initialize the context.

Parameters
ctxEntropy context to initialize

◆ mbedtls_entropy_self_test()

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

◆ 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
ctxEntropy context
dataData to add
lenLength of data
Returns
0 if successful

◆ mbedtls_entropy_update_seed_file()

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
ctxEntropy context
pathName of the file
Returns
0 if successful, MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR on file error, MBEDTLS_ERR_ENTROPY_SOURCE_FAILED

◆ mbedtls_entropy_write_seed_file()

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

Write a seed file.

Parameters
ctxEntropy context
pathName of the file
Returns
0 if successful, MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR on file error, or MBEDTLS_ERR_ENTROPY_SOURCE_FAILED