entropy.h File Reference

Entropy accumulator implementation. More...

`#include "config.h"`
`#include <stddef.h>`
`#include "sha256.h"`
`#include "threading.h"`
`#include "havege.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
| 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 32
| Block size of entropy accumulator (SHA-256) 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.

Copyright (C) 2006-2015, ARM Limited, All Rights Reserved SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This file is part of mbed TLS (https://tls.mbed.org)

Definition in file entropy.h.

## Macro Definition Documentation

#define MBEDTLS_ENTROPY_BLOCK_SIZE 32

Block size of entropy accumulator (SHA-256)

Definition at line 79 of file entropy.h.

#define MBEDTLS_ENTROPY_MAX_GATHER 128

Maximum amount requested from entropy sources.

Definition at line 71 of file entropy.h.

#define MBEDTLS_ENTROPY_MAX_SEED_SIZE 1024

Maximum size of seed we read from seed file.

Definition at line 82 of file entropy.h.

#define MBEDTLS_ENTROPY_MAX_SOURCES 20

Maximum number of sources supported.

Definition at line 67 of file entropy.h.

#define MBEDTLS_ENTROPY_SHA256_ACCUMULATOR

Definition at line 39 of file entropy.h.

#define MBEDTLS_ENTROPY_SOURCE_MANUAL MBEDTLS_ENTROPY_MAX_SOURCES

Definition at line 83 of file entropy.h.

#define MBEDTLS_ENTROPY_SOURCE_STRONG 1

Entropy source is strong.

Definition at line 85 of file entropy.h.

#define MBEDTLS_ENTROPY_SOURCE_WEAK 0

Entropy source is weak.

Definition at line 86 of file entropy.h.

#define MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR -0x003F

Read/write error in file.

Definition at line 56 of file entropy.h.

#define MBEDTLS_ERR_ENTROPY_MAX_SOURCES -0x003E

No more sources can be added.

Definition at line 53 of file entropy.h.

#define MBEDTLS_ERR_ENTROPY_NO_SOURCES_DEFINED -0x0040

No sources have been added to poll.

Definition at line 54 of file entropy.h.

#define MBEDTLS_ERR_ENTROPY_NO_STRONG_SOURCE -0x003D

No strong sources have been added to poll.

Definition at line 55 of file entropy.h.

#define MBEDTLS_ERR_ENTROPY_SOURCE_FAILED -0x003C

Critical entropy source failure.

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

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

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

  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.

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