entropy.h File Reference

Entropy accumulator implementation. More...

#include "config.h"
#include <stddef.h>
#include "sha512.h"

Include dependency graph for entropy.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

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

Copyright (C) 2006-2016, 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)

Macro Definition Documentation

MBEDTLS_ENTROPY_BLOCK_SIZE

#define MBEDTLS_ENTROPY_BLOCK_SIZE   64

Block size of entropy accumulator (SHA-512)

MBEDTLS_ENTROPY_MAX_GATHER

#define MBEDTLS_ENTROPY_MAX_GATHER   128

Maximum amount requested from entropy sources

MBEDTLS_ENTROPY_MAX_SEED_SIZE

#define MBEDTLS_ENTROPY_MAX_SEED_SIZE   1024

Maximum size of seed we read from seed file

MBEDTLS_ENTROPY_MAX_SOURCES

#define MBEDTLS_ENTROPY_MAX_SOURCES   20

Maximum number of sources supported

MBEDTLS_ENTROPY_SHA512_ACCUMULATOR

#define MBEDTLS_ENTROPY_SHA512_ACCUMULATOR

MBEDTLS_ENTROPY_SOURCE_MANUAL

#define MBEDTLS_ENTROPY_SOURCE_MANUAL   MBEDTLS_ENTROPY_MAX_SOURCES

MBEDTLS_ENTROPY_SOURCE_STRONG

#define MBEDTLS_ENTROPY_SOURCE_STRONG   1

Entropy source is strong

MBEDTLS_ENTROPY_SOURCE_WEAK

#define MBEDTLS_ENTROPY_SOURCE_WEAK   0

Entropy source is weak

MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR

#define MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR   -0x003F

Read/write error in file.

MBEDTLS_ERR_ENTROPY_MAX_SOURCES

#define MBEDTLS_ERR_ENTROPY_MAX_SOURCES   -0x003E

No more sources can be added.

MBEDTLS_ERR_ENTROPY_NO_SOURCES_DEFINED

#define MBEDTLS_ERR_ENTROPY_NO_SOURCES_DEFINED   -0x0040

No sources have been added to poll.

MBEDTLS_ERR_ENTROPY_NO_STRONG_SOURCE

#define MBEDTLS_ERR_ENTROPY_NO_STRONG_SOURCE   -0x003D

No strong sources have been added to poll.

MBEDTLS_ERR_ENTROPY_SOURCE_FAILED

#define MBEDTLS_ERR_ENTROPY_SOURCE_FAILED   -0x003C

Critical entropy source failure.

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

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

Here is the caller graph for this function:

mbedtls_entropy_free()

void mbedtls_entropy_free

(

mbedtls_entropy_context *

ctx

)

Free the data in the context.

Parameters

ctx	Entropy context to free

Here is the call graph for this function:

Here is the caller graph for this function:

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

Here is the call graph for this function:

Here is the caller graph for this function:

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

Here is the call graph for this function:

Here is the caller graph for this function:

mbedtls_entropy_init()

void mbedtls_entropy_init

(

mbedtls_entropy_context *

ctx

)

Initialize the context.

Parameters

ctx	Entropy context to initialize

Here is the call graph for this function:

Here is the caller graph for this function:

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

Here is the call graph for this function:

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

Here is the call graph for this function:

Here is the caller graph for this function:

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

Here is the call graph for this function:

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

Here is the call graph for this function:

Here is the caller graph for this function: