PolarSSL is now part of ARM Official announcement and rebranded as mbed TLS.

API Documentation (Doxygen generated)

These pages are generated with doxygen directly from the source code!

entropy.h File Reference

Entropy accumulator implementation. More...

#include "config.h"
#include <stddef.h>
#include "sha512.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
 Critical entropy source failure. More...
 
#define MBEDTLS_ERR_ENTROPY_MAX_SOURCES   -0x003E
 No more sources can be added. More...
 
#define MBEDTLS_ERR_ENTROPY_NO_SOURCES_DEFINED   -0x0040
 No sources have been added to poll. More...
 
#define MBEDTLS_ERR_ENTROPY_NO_STRONG_SOURCE   -0x003D
 No strong sources have been added to poll. More...
 
#define MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR   -0x003F
 Read/write error in file. More...
 
#define MBEDTLS_ENTROPY_BLOCK_SIZE   64
 Block size of entropy accumulator (SHA-512) More...
 
#define MBEDTLS_ENTROPY_MAX_SEED_SIZE   1024
 Maximum size of seed we read from seed file. More...
 
#define MBEDTLS_ENTROPY_SOURCE_MANUAL   MBEDTLS_ENTROPY_MAX_SOURCES
 
#define MBEDTLS_ENTROPY_SOURCE_STRONG   1
 Entropy source is strong. More...
 
#define MBEDTLS_ENTROPY_SOURCE_WEAK   0
 Entropy source is weak. More...
 
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. More...
 
#define MBEDTLS_ENTROPY_MAX_GATHER   128
 Maximum amount requested from entropy sources. More...
 

Typedefs

typedef int(* mbedtls_entropy_f_source_ptr )(void *data, unsigned char *output, size_t len, size_t *olen)
 Entropy poll callback pointer. 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_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. More...
 
int mbedtls_entropy_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   64

Block size of entropy accumulator (SHA-512)

Definition at line 78 of file entropy.h.

#define MBEDTLS_ENTROPY_MAX_GATHER   128

Maximum amount requested from entropy sources.

Definition at line 72 of file entropy.h.

#define MBEDTLS_ENTROPY_MAX_SEED_SIZE   1024

Maximum size of seed we read from seed file.

Definition at line 83 of file entropy.h.

#define MBEDTLS_ENTROPY_MAX_SOURCES   20

Maximum number of sources supported.

Definition at line 68 of file entropy.h.

#define MBEDTLS_ENTROPY_SHA512_ACCUMULATOR

Definition at line 37 of file entropy.h.

#define MBEDTLS_ENTROPY_SOURCE_MANUAL   MBEDTLS_ENTROPY_MAX_SOURCES

Definition at line 84 of file entropy.h.

#define MBEDTLS_ENTROPY_SOURCE_STRONG   1

Entropy source is strong.

Definition at line 86 of file entropy.h.

#define MBEDTLS_ENTROPY_SOURCE_WEAK   0

Entropy source is weak.

Definition at line 87 of file entropy.h.

#define MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR   -0x003F

Read/write error in file.

Definition at line 57 of file entropy.h.

#define MBEDTLS_ERR_ENTROPY_MAX_SOURCES   -0x003E

No more sources can be added.

Definition at line 54 of file entropy.h.

#define MBEDTLS_ERR_ENTROPY_NO_SOURCES_DEFINED   -0x0040

No sources have been added to poll.

Definition at line 55 of file entropy.h.

#define MBEDTLS_ERR_ENTROPY_NO_STRONG_SOURCE   -0x003D

No strong sources have been added to poll.

Definition at line 56 of file entropy.h.

#define MBEDTLS_ERR_ENTROPY_SOURCE_FAILED   -0x003C

Critical entropy source failure.

Definition at line 53 of file entropy.h.

Typedef Documentation

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

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
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 MBEDTSL_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
ctxEntropy 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
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
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
void mbedtls_entropy_init ( mbedtls_entropy_context ctx)

Initialize the context.

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