Loading...
Searching...
No Matches
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]samplepointer 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

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]funcpointer to entropy_source_sample_func_t function that returns samples
[out]outpointer to write unbiased bytes to
[in]lennumber 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_repRepetition Count test structure of one entropy source.
[in,out]state_propAdaptive Proportion test structure of one entropy source.
[in]sampleCurrent 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]stateTest structure of one entropy source.
[in]samplecurrent 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_sampleEstimated 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]stateTest structure of one entropy source.
[in]c_propCutoff 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]stateTest structure of one entropy source.
[in]sampleCurrent 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_sampleEstimated 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]stateTest structure of one entropy source.
[in]c_repCutoff value calculated by entropy_source_test_rep_cutoff.

Definition at line 210 of file entropy_source.h.