Entropy Source Common

Common definitions and functions for entropy sources. More...

Detailed Description

Common definitions and functions for entropy sources.

Modules
	Entropy Source compile configurations

Files
file	entropy_source.h

Data Structures
struct	entropy_source_tests_rep_t
	Data structure for Repetition Count Test (NIST SP 800-90B 4.4.1). More...
struct	entropy_source_tests_prop_t
	Data structure for Adaptive Proportion Test (NIST SP 800-90B 4.4.2). More...

Macros
#define	ENTROPY_SOURCE_HMIN_SCALE(x)   ((x * (1UL << 16)))
	Scale Min.
#define	ENTROPY_SOURCE_HMIN_SCALE_BACK(x)   ((float)x / (1UL << 16))
	Scale internal fixed point Min.

Typedefs
typedef int(*	entropy_source_sample_func_t) (uint8_t *sample)
	Get one sample of the entropy source.

Enumerations
enum	entropy_source_error_t {   ENTROPY_SOURCE_OK = 0 , ENTROPY_SOURCE_ERR_INIT = -1 , ENTROPY_SOURCE_ERR_CONFIG = -2 , ENTROPY_SOURCE_ERR_TEST_REP = -3 ,   ENTROPY_SOURCE_ERR_TEST_PROP = -4 , ENTROPY_SOURCE_ERR_TEST_BOTH = -5 , ENTROPY_SOURCE_ERR_COND = -6 }
	Entropy source error codes. More...

Functions
int	entropy_source_neumann_unbias (entropy_source_sample_func_t func, uint8_t *out, size_t len)
	Applies von Neumann unbiasing.
static uint32_t	entropy_source_test_rep_cutoff (uint32_t entropy_per_sample)
	Calculate cutoff value for Repetition Count Test (NIST SP 800-90B 4.4.1)
static int	entropy_source_test_prop_cutoff (uint32_t entropy_per_sample)
	Calculate cutoff value for Adaptive Proportion Test (NIST SP 800-90B 4.4.2)
static void	entropy_source_test_rep_init (entropy_source_tests_rep_t *state, uint16_t c_rep)
	Initialize structure for Repetition Count Test.
static void	entropy_source_test_prop_init (entropy_source_tests_prop_t *state, uint16_t c_prop)
	Initialize structure for Adaptive Proportion Test.
int	entropy_source_test_rep (entropy_source_tests_rep_t *state, uint8_t sample)
	Performs Repetition Count Test (NIST SP 800-90B 4.4.1).
int	entropy_source_test_prop (entropy_source_tests_prop_t *state, uint8_t sample)
	Performs Adaptive Proportion Test (NIST SP 800-90B 4.4.2).
static int	entropy_source_test (entropy_source_tests_rep_t *state_rep, entropy_source_tests_prop_t *state_prop, uint8_t sample)
	Convenience function to perform entropy_source_test_rep and entropy_source_test_prop.

Macro Definition Documentation

ENTROPY_SOURCE_HMIN_SCALE

#define ENTROPY_SOURCE_HMIN_SCALE

(

x

)

((x * (1UL << 16)))

Scale Min.

Entropy to fixed point integer to avoid float. The entropy per sample (8 Byte) of a noise source can likely be smaller than 1 bit.

Definition at line 70 of file entropy_source.h.

ENTROPY_SOURCE_HMIN_SCALE_BACK

#define ENTROPY_SOURCE_HMIN_SCALE_BACK

(

x

)

((float)x / (1UL << 16))

Scale internal fixed point Min.

Entropy back to float. This macro is not required and only there for convenience.

Definition at line 76 of file entropy_source.h.

Typedef Documentation

entropy_source_sample_func_t

typedef int(* entropy_source_sample_func_t) (uint8_t *sample)

Get one sample of the entropy source.

This function is typically used by the entropy source internally. A conditioning component might need an interface to request a variable number of samples, e.g., depending on the contained amount of entropy.

Parameters

[out]

sample

pointer to write sample to.

Returns

ENTROPY_SOURCE_OK on success

negative entropy_source_error_t code on error

Definition at line 120 of file entropy_source.h.

Enumeration Type Documentation

entropy_source_error_t

enum entropy_source_error_t

Entropy source error codes.

Enumerator
ENTROPY_SOURCE_OK	Success.
ENTROPY_SOURCE_ERR_INIT	Source initialization error.
ENTROPY_SOURCE_ERR_CONFIG	Source configuration error.
ENTROPY_SOURCE_ERR_TEST_REP	Repetition count test error.
ENTROPY_SOURCE_ERR_TEST_PROP	Adaptive proportion test error.
ENTROPY_SOURCE_ERR_TEST_BOTH	Repetition count and Adaptive proportion test error.
ENTROPY_SOURCE_ERR_COND	Conditioning error.

Definition at line 35 of file entropy_source.h.

Function Documentation

entropy_source_neumann_unbias()

int entropy_source_neumann_unbias	(	entropy_source_sample_func_t	func,
		uint8_t *	out,
		size_t	len
	)

Applies von Neumann unbiasing.

This function requests as many samples needed to create len unbiased bytes using func. The algorithm compares bits of consecutive samples. Only bit changes will be considered for the output value. An abort criterium stops sampling after (len * CONFIG_ENTROPY_SOURCE_NEUMANN_ABORT) iterations.

Warning

This function has a non-deterministic runtime.

Parameters

[in]	func	pointer to entropy_source_sample_func_t function that returns samples
[out]	out	pointer to write unbiased bytes to
[in]	len	number of bytes to generate

Returns

ENTROPY_SOURCE_OK on success

negative entropy_source_error_t code on error

entropy_source_test()

static int entropy_source_test ( entropy_source_tests_rep_t *  state_rep, entropy_source_tests_prop_t *  state_prop, uint8_t  sample  )

inlinestatic

Convenience function to perform entropy_source_test_rep and entropy_source_test_prop.

This function will not block the sampling. It only indicates detected errors.

Parameters

[in,out]	state_rep	Repetition Count test structure of one entropy source.
[in,out]	state_prop	Adaptive Proportion test structure of one entropy source.
[in]	sample	Current sample.

Returns

ENTROPY_SOURCE_OK on success

negative entropy_source_error_t code on error

Definition at line 280 of file entropy_source.h.

entropy_source_test_prop()

int entropy_source_test_prop	(	entropy_source_tests_prop_t *	state,
		uint8_t	sample
	)

Performs Adaptive Proportion Test (NIST SP 800-90B 4.4.2).

This function will not block the sampling. It only indicates detected errors.

Parameters

[in,out]	state	Test structure of one entropy source.
[in]	sample	current sample.

Returns

ENTROPY_SOURCE_OK on success

ENTROPY_SOURCE_ERR_TEST_PROP on detected weakness

entropy_source_test_prop_cutoff()

static int entropy_source_test_prop_cutoff ( uint32_t  entropy_per_sample )

inlinestatic

Calculate cutoff value for Adaptive Proportion Test (NIST SP 800-90B 4.4.2)

Parameters

[in]

entropy_per_sample

Estimated min. entropy of one sample scaled by ENTROPY_SOURCE_HMIN_SCALE()

Returns

Cutoff value

ENTROPY_SOURCE_ERR_CONFIG if parameter invalid

Definition at line 177 of file entropy_source.h.

entropy_source_test_prop_init()

static void entropy_source_test_prop_init ( entropy_source_tests_prop_t *  state, uint16_t  c_prop  )

inlinestatic

Initialize structure for Adaptive Proportion Test.

Parameters

[in,out]	state	Test structure of one entropy source.
[in]	c_prop	Cutoff value calculated by entropy_source_test_prop_cutoff.

Definition at line 227 of file entropy_source.h.

entropy_source_test_rep()

int entropy_source_test_rep	(	entropy_source_tests_rep_t *	state,
		uint8_t	sample
	)

Performs Repetition Count Test (NIST SP 800-90B 4.4.1).

This function will not block sampling. It only indicates detected errors.

Parameters

[in,out]	state	Test structure of one entropy source.
[in]	sample	Current sample.

Returns

ENTROPY_SOURCE_OK on success

ENTROPY_SOURCE_ERR_TEST_REP on detected weakness

entropy_source_test_rep_cutoff()

static uint32_t entropy_source_test_rep_cutoff ( uint32_t  entropy_per_sample )

inlinestatic

Calculate cutoff value for Repetition Count Test (NIST SP 800-90B 4.4.1)

C = 1 + ( (-log2 a) / H)

C: Cutoff value. H: Min. entropy of the source SP800-90B EntropyAssessment. a: Probability of type I error. We assume 2^(-20).

Parameters

[in]

entropy_per_sample

Estimated min. entropy of one sample scaled by ENTROPY_SOURCE_HMIN_SCALE()

Returns

Cutoff threshold

Definition at line 161 of file entropy_source.h.

entropy_source_test_rep_init()

static void entropy_source_test_rep_init ( entropy_source_tests_rep_t *  state, uint16_t  c_rep  )

inlinestatic

Initialize structure for Repetition Count Test.

Parameters

[in,out]	state	Test structure of one entropy source.
[in]	c_rep	Cutoff value calculated by entropy_source_test_rep_cutoff.

Definition at line 210 of file entropy_source.h.