mbed TLS v2.16.3: entropy.h File Reference

mbed TLS v2.16.3

Data Structures | Macros
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
#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

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

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

## ◆ MBEDTLS_ENTROPY_MAX_GATHER

#define MBEDTLS_ENTROPY_MAX_GATHER 128

Maximum amount requested from entropy sources

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

## ◆ MBEDTLS_ENTROPY_MAX_SOURCES

#define MBEDTLS_ENTROPY_MAX_SOURCES 20

Maximum number of sources supported

Definition at line 68 of file entropy.h.

## ◆ MBEDTLS_ENTROPY_SHA512_ACCUMULATOR

#define MBEDTLS_ENTROPY_SHA512_ACCUMULATOR

Definition at line 37 of file entropy.h.

## ◆ MBEDTLS_ENTROPY_SOURCE_MANUAL

#define MBEDTLS_ENTROPY_SOURCE_MANUAL MBEDTLS_ENTROPY_MAX_SOURCES

Definition at line 84 of file entropy.h.

## ◆ MBEDTLS_ENTROPY_SOURCE_STRONG

#define MBEDTLS_ENTROPY_SOURCE_STRONG 1

Entropy source is strong

Definition at line 86 of file entropy.h.

## ◆ MBEDTLS_ENTROPY_SOURCE_WEAK

#define MBEDTLS_ENTROPY_SOURCE_WEAK 0

Entropy source is weak

Definition at line 87 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 57 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 54 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 55 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 56 of file entropy.h.

## ◆ MBEDTLS_ERR_ENTROPY_SOURCE_FAILED

#define MBEDTLS_ERR_ENTROPY_SOURCE_FAILED -0x003C

Critical entropy source failure.

Definition at line 53 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

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

  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_free()

void mbedtls_entropy_free | ( | mbedtls_entropy_context * | ctx | ) |

Free the data in the context.

Parameters

  ctx | Entropy 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

  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_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_init()

void mbedtls_entropy_init | ( | mbedtls_entropy_context * | ctx | ) |

Initialize the context.

Parameters

  ctx | Entropy 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

  ctx | Entropy context
  data | Data to add
  len | Length 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

  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

## ◆ mbedtls_entropy_write_seed_file()

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