entropy.h File Reference

Entropy accumulator implementation. More...

#include <string.h>
#include "config.h"
#include "sha512.h"
#include "havege.h"

Include dependency graph for entropy.h:

Go to the source code of this file.

Data Structures
struct	source_state
	Entropy source state. More...
struct	entropy_context
	Entropy context structure. More...

Macros
#define	POLARSSL_ENTROPY_SHA512_ACCUMULATOR
#define	POLARSSL_ERR_ENTROPY_SOURCE_FAILED   -0x003C
	Critical entropy source failure.
#define	POLARSSL_ERR_ENTROPY_MAX_SOURCES   -0x003E
	No more sources can be added.
#define	POLARSSL_ERR_ENTROPY_NO_SOURCES_DEFINED   -0x0040
	No sources have been added to poll.
#define	POLARSSL_ERR_ENTROPY_FILE_IO_ERROR   -0x0058
	Read/write error in file.

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	ENTROPY_MAX_SOURCES   20
	Maximum number of sources supported.
#define	ENTROPY_MAX_GATHER   128
	Maximum amount requested from entropy sources.
#define	ENTROPY_BLOCK_SIZE   64
	Block size of entropy accumulator (SHA-512)
#define	ENTROPY_MAX_SEED_SIZE   1024
	Maximum size of seed we read from seed file.
#define	ENTROPY_SOURCE_MANUAL   ENTROPY_MAX_SOURCES
typedef int(*	f_source_ptr) (void *data, unsigned char *output, size_t len, size_t *olen)
	Entropy poll callback pointer.
void	entropy_init (entropy_context *ctx)
	Initialize the context.
void	entropy_free (entropy_context *ctx)
	Free the data in the context.
int	entropy_add_source (entropy_context *ctx, f_source_ptr f_source, void *p_source, size_t threshold)
	Adds an entropy source to poll (Thread-safe if POLARSSL_THREADING_C is enabled)
int	entropy_gather (entropy_context *ctx)
	Trigger an extra gather poll for the accumulator (Thread-safe if POLARSSL_THREADING_C is enabled)
int	entropy_func (void *data, unsigned char *output, size_t len)
	Retrieve entropy from the accumulator (Maximum length: ENTROPY_BLOCK_SIZE) (Thread-safe if POLARSSL_THREADING_C is enabled)
int	entropy_update_manual (entropy_context *ctx, const unsigned char *data, size_t len)
	Add data to the accumulator manually (Thread-safe if POLARSSL_THREADING_C is enabled)
int	entropy_write_seed_file (entropy_context *ctx, const char *path)
	Write a seed file.
int	entropy_update_seed_file (entropy_context *ctx, const char *path)
	Read and update a seed file.
int	entropy_self_test (int verbose)
	Checkup routine.

Detailed Description

Entropy accumulator implementation.

Copyright (C) 2006-2014, Brainspark B.V.

This file is part of PolarSSL (http://www.polarssl.org) Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

Definition in file entropy.h.

Macro Definition Documentation

ENTROPY_BLOCK_SIZE

#define ENTROPY_BLOCK_SIZE   64

Block size of entropy accumulator (SHA-512)

Definition at line 80 of file entropy.h.

ENTROPY_MAX_GATHER

#define ENTROPY_MAX_GATHER   128

Maximum amount requested from entropy sources.

Definition at line 74 of file entropy.h.

ENTROPY_MAX_SEED_SIZE

#define ENTROPY_MAX_SEED_SIZE   1024

Maximum size of seed we read from seed file.

Definition at line 85 of file entropy.h.

ENTROPY_MAX_SOURCES

#define ENTROPY_MAX_SOURCES   20

Maximum number of sources supported.

Definition at line 70 of file entropy.h.

ENTROPY_SOURCE_MANUAL

#define ENTROPY_SOURCE_MANUAL   ENTROPY_MAX_SOURCES

Definition at line 86 of file entropy.h.

POLARSSL_ENTROPY_SHA512_ACCUMULATOR

#define POLARSSL_ENTROPY_SHA512_ACCUMULATOR

Definition at line 40 of file entropy.h.

POLARSSL_ERR_ENTROPY_FILE_IO_ERROR

#define POLARSSL_ERR_ENTROPY_FILE_IO_ERROR   -0x0058

Read/write error in file.

Definition at line 59 of file entropy.h.

POLARSSL_ERR_ENTROPY_MAX_SOURCES

#define POLARSSL_ERR_ENTROPY_MAX_SOURCES   -0x003E

No more sources can be added.

Definition at line 57 of file entropy.h.

POLARSSL_ERR_ENTROPY_NO_SOURCES_DEFINED

#define POLARSSL_ERR_ENTROPY_NO_SOURCES_DEFINED   -0x0040

No sources have been added to poll.

Definition at line 58 of file entropy.h.

POLARSSL_ERR_ENTROPY_SOURCE_FAILED

#define POLARSSL_ERR_ENTROPY_SOURCE_FAILED   -0x003C

Critical entropy source failure.

Definition at line 56 of file entropy.h.

Typedef Documentation

f_source_ptr

typedef int(* 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, POLARSSL_ERR_ENTROPY_SOURCE_FAILED otherwise

Definition at line 103 of file entropy.h.

Function Documentation

entropy_add_source()

int entropy_add_source	(	entropy_context *	ctx,
		f_source_ptr	f_source,
		void *	p_source,
		size_t	threshold )

Adds an entropy source to poll (Thread-safe if POLARSSL_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 entropy_func() )

Returns

0 if successful or POLARSSL_ERR_ENTROPY_MAX_SOURCES

entropy_free()

void entropy_free

(

entropy_context *

ctx

)

Free the data in the context.

Parameters

ctx	Entropy context to free

entropy_func()

int entropy_func	(	void *	data,
		unsigned char *	output,
		size_t	len )

Retrieve entropy from the accumulator (Maximum length: ENTROPY_BLOCK_SIZE) (Thread-safe if POLARSSL_THREADING_C is enabled)

Parameters

data	Entropy context
output	Buffer to fill
len	Number of bytes desired, must be at most ENTROPY_BLOCK_SIZE

Returns

0 if successful, or POLARSSL_ERR_ENTROPY_SOURCE_FAILED

entropy_gather()

int entropy_gather

(

entropy_context *

ctx

)

Trigger an extra gather poll for the accumulator (Thread-safe if POLARSSL_THREADING_C is enabled)

Parameters

ctx	Entropy context

Returns

0 if successful, or POLARSSL_ERR_ENTROPY_SOURCE_FAILED

entropy_init()

void entropy_init

(

entropy_context *

ctx

)

Initialize the context.

Parameters

ctx	Entropy context to initialize

entropy_self_test()

int entropy_self_test

(

int

verbose

)

Checkup routine.

Returns

0 if successful, or 1 if a test failed

entropy_update_manual()

int entropy_update_manual	(	entropy_context *	ctx,
		const unsigned char *	data,
		size_t	len )

Add data to the accumulator manually (Thread-safe if POLARSSL_THREADING_C is enabled)

Parameters

ctx	Entropy context
data	Data to add
len	Length of data

Returns

0 if successful

entropy_update_seed_file()

int entropy_update_seed_file	(	entropy_context *	ctx,
		const char *	path )

Read and update a seed file.

Seed is added to this instance. No more than 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, POLARSSL_ERR_ENTROPY_FILE_IO_ERROR on file error, POLARSSL_ERR_ENTROPY_SOURCE_FAILED

entropy_write_seed_file()

int entropy_write_seed_file	(	entropy_context *	ctx,
		const char *	path )

Write a seed file.

Parameters

ctx	Entropy context
path	Name of the file

Returns

0 if successful, POLARSSL_ERR_ENTROPY_FILE_IO_ERROR on file error, or POLARSSL_ERR_ENTROPY_SOURCE_FAILED