iPXE
Data Structures | Macros | Typedefs | Functions
entropy.h File Reference

Entropy source. More...

#include <stdint.h>
#include <string.h>
#include <assert.h>
#include <ipxe/hash_df.h>
#include <ipxe/sha256.h>
#include <ipxe/tables.h>
#include <config/entropy.h>

Go to the source code of this file.

Data Structures

struct  entropy_repetition_count_test
 Repetition count test state. More...
 
struct  entropy_adaptive_proportion_test
 Adaptive proportion test state. More...
 
struct  entropy_startup_test
 Startup test state. More...
 
struct  entropy_source
 An entropy source. More...
 

Macros

#define MIN_ENTROPY_SCALE   ( 1 << 16 )
 Fixed-point scale for min-entropy amounts. More...
 
#define MIN_ENTROPY(bits)   ( ( min_entropy_t ) ( (bits) * MIN_ENTROPY_SCALE ) )
 Construct a min-entropy fixed-point value. More...
 
#define ENTROPY_SOURCES   __table ( struct entropy_source, "entropy_sources" )
 Entropy source table. More...
 
#define __entropy_source(order)   __table_entry ( ENTROPY_SOURCES, order )
 Declare an entropy source. More...
 
#define ENTROPY_PREFERRED   01
 Preferred entropy source. More...
 
#define ENTROPY_NORMAL   02
 Normal entropy source. More...
 
#define ENTROPY_FALLBACK   03
 Fallback entropy source. More...
 
#define entropy_hash_df_algorithm   sha256_algorithm
 Use SHA-256 as the underlying hash algorithm for Hash_df. More...
 
#define ENTROPY_HASH_DF_OUTLEN_BYTES   SHA256_DIGEST_SIZE
 Underlying hash algorithm output length (in bytes) More...
 
#define ADAPTIVE_PROPORTION_WINDOW_SIZE   64
 Window size for the adaptive proportion test. More...
 
#define APC_N_H(n, h)   ( ( (n) << 8 ) | (h) )
 Combine adaptive proportion test window size and min-entropy. More...
 
#define APC_TABLE_ROW(h, c16, c64, c256, c4096, c65536)
 Define a row of the adaptive proportion cutoff table. More...
 
#define APC_NA   0
 Value used to represent "N/A" in adaptive proportion cutoff table. More...
 

Typedefs

typedef uint8_t noise_sample_t
 A noise sample. More...
 
typedef uint8_t entropy_sample_t
 An entropy sample. More...
 
typedef unsigned int min_entropy_t
 An amount of min-entropy. More...
 

Functions

 FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
 
int get_entropy_input_tmp (min_entropy_t min_entropy, uint8_t *tmp, size_t tmp_len)
 Obtain entropy input temporary buffer. More...
 
static int get_noise (struct entropy_source *source, noise_sample_t *noise)
 Get noise sample. More...
 
static int get_entropy_input (unsigned int min_entropy_bits, void *data, size_t min_len, size_t max_len)
 Obtain entropy input. More...
 
static unsigned int entropy_repetition_count_cutoff (min_entropy_t min_entropy_per_sample)
 Calculate cutoff value for the repetition count test. More...
 
static unsigned int entropy_adaptive_proportion_cutoff_lookup (unsigned int n, unsigned int h)
 Look up value in adaptive proportion test cutoff table. More...
 
static unsigned int entropy_adaptive_proportion_cutoff (min_entropy_t min_entropy_per_sample)
 Calculate cutoff value for the adaptive proportion test. More...
 
static unsigned int entropy_startup_test_count (unsigned int repetition_count_cutoff, unsigned int adaptive_proportion_cutoff)
 Calculate number of samples required for startup tests. More...
 
static void entropy_init (struct entropy_source *source, min_entropy_t min_entropy_per_sample)
 Initialise entropy source. More...
 
int entropy_enable (struct entropy_source *source)
 Enable entropy gathering. More...
 
void entropy_disable (struct entropy_source *source)
 Disable entropy gathering. More...
 

Detailed Description

Entropy source.

Definition in file entropy.h.

Macro Definition Documentation

◆ MIN_ENTROPY_SCALE

#define MIN_ENTROPY_SCALE   ( 1 << 16 )

Fixed-point scale for min-entropy amounts.

Definition at line 34 of file entropy.h.

◆ MIN_ENTROPY

#define MIN_ENTROPY (   bits)    ( ( min_entropy_t ) ( (bits) * MIN_ENTROPY_SCALE ) )

Construct a min-entropy fixed-point value.

Parameters
bitsmin-entropy in bits
Return values
min_entropymin-entropy as a fixed-point value

Definition at line 42 of file entropy.h.

◆ ENTROPY_SOURCES

#define ENTROPY_SOURCES   __table ( struct entropy_source, "entropy_sources" )

Entropy source table.

Definition at line 169 of file entropy.h.

◆ __entropy_source

#define __entropy_source (   order)    __table_entry ( ENTROPY_SOURCES, order )

Declare an entropy source.

Definition at line 172 of file entropy.h.

◆ entropy_hash_df_algorithm

#define entropy_hash_df_algorithm   sha256_algorithm

Use SHA-256 as the underlying hash algorithm for Hash_df.

Hash_df using SHA-256 is an Approved algorithm in ANS X9.82.

Definition at line 192 of file entropy.h.

◆ ENTROPY_HASH_DF_OUTLEN_BYTES

#define ENTROPY_HASH_DF_OUTLEN_BYTES   SHA256_DIGEST_SIZE

Underlying hash algorithm output length (in bytes)

Definition at line 195 of file entropy.h.

◆ ADAPTIVE_PROPORTION_WINDOW_SIZE

#define ADAPTIVE_PROPORTION_WINDOW_SIZE   64

Window size for the adaptive proportion test.

ANS X9.82 Part 2 (October 2011 Draft) Section 8.5.2.1.3.1.1 allows five possible window sizes: 16, 64, 256, 4096 and 65536.

We expect to generate relatively few (<256) entropy samples during a typical iPXE run; the use of a large window size would mean that the test would never complete a single cycle. We use a window size of 64, which is the smallest window size that permits values of H_min down to one bit per sample.

Definition at line 353 of file entropy.h.

◆ APC_N_H

#define APC_N_H (   n,
  h 
)    ( ( (n) << 8 ) | (h) )

Combine adaptive proportion test window size and min-entropy.

Parameters
nN (window size)
hH (min-entropy)
Return values
n_h(N,H) combined value

Definition at line 362 of file entropy.h.

◆ APC_TABLE_ROW

#define APC_TABLE_ROW (   h,
  c16,
  c64,
  c256,
  c4096,
  c65536 
)
Value:
case APC_N_H ( 16, h ) : return c16; \
case APC_N_H ( 64, h ) : return c64; \
case APC_N_H ( 256, h ) : return c256; \
case APC_N_H ( 4096, h ) : return c4096; \
case APC_N_H ( 65536, h ) : return c65536;
uint32_t h
Definition: sha256.c:35
#define APC_N_H(n, h)
Combine adaptive proportion test window size and min-entropy.
Definition: entropy.h:362
return
Definition: natsemi.h:326

Define a row of the adaptive proportion cutoff table.

Parameters
hH (min-entropy)
c16Cutoff for N=16
c64Cutoff for N=64
c256Cutoff for N=256
c4096Cutoff for N=4096
c65536Cutoff for N=65536

Definition at line 374 of file entropy.h.

◆ APC_NA

#define APC_NA   0

Value used to represent "N/A" in adaptive proportion cutoff table.

Definition at line 382 of file entropy.h.

Typedef Documentation

◆ noise_sample_t

A noise sample.

Definition at line 21 of file entropy.h.

◆ entropy_sample_t

An entropy sample.

Definition at line 24 of file entropy.h.

◆ min_entropy_t

typedef unsigned int min_entropy_t

An amount of min-entropy.

Expressed as a fixed-point quantity in order to avoid floating point calculations.

Definition at line 31 of file entropy.h.

Function Documentation

◆ FILE_LICENCE()

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL  )

◆ get_entropy_input_tmp()

int get_entropy_input_tmp ( min_entropy_t  min_entropy,
uint8_t tmp,
size_t  tmp_len 
)

Obtain entropy input temporary buffer.

Parameters
min_entropyMin-entropy required
tmpTemporary buffer
tmp_lenLength of temporary buffer
Return values
rcReturn status code

This is (part of) the implementation of the Get_entropy_input function (using an entropy source as the source of entropy input and condensing each entropy source output after each GetEntropy call) as defined in ANS X9.82 Part 4 (April 2011 Draft) Section 13.3.4.2.

Definition at line 425 of file entropy.c.

426  {
427  struct entropy_source *source;
428  struct {
429  uint32_t nonce;
430  entropy_sample_t sample;
431  } __attribute__ (( packed )) data;;
432  uint8_t df_buf[tmp_len];
433  min_entropy_t entropy_total;
434  unsigned int num_samples;
435  unsigned int i;
436  int rc;
437 
438  /* Enable entropy gathering */
439  if ( ( rc = entropy_enable_working ( &source ) ) != 0 )
440  goto err_enable_working;
441 
442  /* Sanity checks */
443  assert ( source->startup_test.count > 0 );
444  assert ( source->startup_test.tested >= source->startup_test.count );
445 
446  /* 3. entropy_total = 0 */
447  entropy_total = MIN_ENTROPY ( 0 );
448 
449  /* 4. tmp = a fixed n-bit value, such as 0^n */
450  memset ( tmp, 0, tmp_len );
451 
452  /* 5. While ( entropy_total < min_entropy ) */
453  for ( num_samples = 0 ; entropy_total < min_entropy ; num_samples++ ) {
454  /* 5.1. ( status, entropy_bitstring, assessed_entropy )
455  * = GetEntropy()
456  * 5.2. If status indicates an error, return ( status, Null )
457  */
458  if ( ( rc = get_entropy ( source, &data.sample ) ) != 0 )
459  goto err_get_entropy;
460 
461  /* 5.3. nonce = MakeNextNonce() */
462  data.nonce = make_next_nonce();
463 
464  /* 5.4. tmp = tmp XOR
465  * df ( ( nonce || entropy_bitstring ), n )
466  */
467  hash_df ( &entropy_hash_df_algorithm, &data, sizeof ( data ),
468  df_buf, sizeof ( df_buf ) );
469  for ( i = 0 ; i < tmp_len ; i++ )
470  tmp[i] ^= df_buf[i];
471 
472  /* 5.5. entropy_total = entropy_total + assessed_entropy */
473  entropy_total += source->min_entropy_per_sample;
474  }
475 
476  /* Disable entropy gathering */
477  entropy_disable ( source );
478 
479  DBGC ( source, "ENTROPY %s gathered %d bits in %d samples\n",
480  source->name, ( min_entropy / MIN_ENTROPY_SCALE ), num_samples );
481  return 0;
482 
483  err_get_entropy:
484  entropy_disable ( source );
485  assert ( source->rc == rc );
486  err_enable_working:
487  return rc;
488 }
#define __attribute__(x)
Definition: compiler.h:10
int rc
Failure status (if any)
Definition: entropy.h:143
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
unsigned int tested
Number of startup tests performed.
Definition: entropy.h:106
#define MIN_ENTROPY_SCALE
Fixed-point scale for min-entropy amounts.
Definition: entropy.h:34
#define DBGC(...)
Definition: compiler.h:505
min_entropy_t min_entropy_per_sample
min-entropy per sample
Definition: entropy.h:131
An entropy source.
Definition: entropy.h:116
const char * name
Name.
Definition: entropy.h:118
static uint32_t make_next_nonce(void)
Create next nonce value.
Definition: entropy.c:402
unsigned long tmp
Definition: linux_pci.h:53
assert((readw(&hdr->flags) &(GTF_reading|GTF_writing))==0)
struct entropy_startup_test startup_test
Startup test state.
Definition: entropy.h:137
void hash_df(struct digest_algorithm *hash, const void *input, size_t input_len, void *output, size_t output_len)
Distribute entropy throughout a buffer.
Definition: hash_df.c:84
unsigned char uint8_t
Definition: stdint.h:10
static int entropy_enable_working(struct entropy_source **source)
Enable first working entropy source.
Definition: entropy.c:365
static int get_entropy(struct entropy_source *source, entropy_sample_t *entropy)
Get entropy sample.
Definition: entropy.c:225
unsigned int uint32_t
Definition: stdint.h:12
#define MIN_ENTROPY(bits)
Construct a min-entropy fixed-point value.
Definition: entropy.h:42
unsigned int min_entropy_t
An amount of min-entropy.
Definition: entropy.h:31
uint8_t entropy_sample_t
An entropy sample.
Definition: entropy.h:24
unsigned int count
Number of startup tests required for one full cycle.
Definition: entropy.h:112
uint8_t data[48]
Additional event data.
Definition: ena.h:22
#define entropy_hash_df_algorithm
Use SHA-256 as the underlying hash algorithm for Hash_df.
Definition: entropy.h:192
void entropy_disable(struct entropy_source *source)
Disable entropy gathering.
Definition: entropy.c:385
struct ntlm_nonce nonce
Server nonce.
Definition: ntlm.h:18
void * memset(void *dest, int character, size_t len) __nonnull

References __attribute__, assert(), entropy_startup_test::count, data, DBGC, entropy_disable(), entropy_enable_working(), entropy_hash_df_algorithm, get_entropy(), hash_df(), make_next_nonce(), memset(), MIN_ENTROPY, entropy_source::min_entropy_per_sample, MIN_ENTROPY_SCALE, entropy_source::name, nonce, entropy_source::rc, rc, entropy_source::startup_test, entropy_startup_test::tested, and tmp.

Referenced by get_entropy_input().

◆ get_noise()

int get_noise ( struct entropy_source source,
noise_sample_t noise 
)
inlinestatic

Get noise sample.

Parameters
sourceEntropy source
Return values
noiseNoise sample
rcReturn status code

This is the GetNoise function defined in ANS X9.82 Part 2 (October 2011 Draft) Section 6.5.2.

Definition at line 208 of file entropy.h.

208  {
209 
210  return source->get_noise ( noise );
211 }
int(* get_noise)(noise_sample_t *noise)
Get noise sample.
Definition: entropy.h:165

References entropy_source::get_noise.

Referenced by entropy_sample(), and get_entropy().

◆ get_entropy_input()

static int get_entropy_input ( unsigned int  min_entropy_bits,
void *  data,
size_t  min_len,
size_t  max_len 
)
inlinestatic

Obtain entropy input.

Parameters
min_entropy_bitsMinimum amount of entropy, in bits
dataData buffer
min_lenMinimum length of entropy input, in bytes
max_lenMaximum length of entropy input, in bytes
Return values
lenLength of entropy input, in bytes, or negative error

This is the implementation of the Get_entropy_input function (using an entropy source as the source of entropy input and condensing each entropy source output after each GetEntropy call) as defined in ANS X9.82 Part 4 (April 2011 Draft) Section 13.3.4.2.

This function is inlined since the entropy amount and length inputs are always compile-time constants.

Definition at line 231 of file entropy.h.

232  {
233  size_t tmp_len = ( ( ( min_entropy_bits * 2 ) + 7 ) / 8 );
234  uint8_t tmp_buf[ tmp_len ];
235  uint8_t *tmp = ( ( tmp_len > max_len ) ? tmp_buf : data );
236  unsigned int n;
237  int rc;
238 
239  /* Sanity check */
240  build_assert ( min_entropy_bits <= ( 8 * max_len ) );
241 
242  /* Round up minimum entropy to an integral number of bytes */
243  min_entropy_bits = ( ( min_entropy_bits + 7 ) & ~7 );
244 
245  /* (Unnumbered). The output length of the hash function shall
246  * meet or exceed the security strength indicated by the
247  * min_entropy parameter.
248  */
250  min_entropy_bits );
251 
252  /* 1. If ( min_length > max_length ), then return ( FAILURE, Null ) */
253  build_assert ( min_len <= max_len );
254 
255  /* 2. n = 2 * min_entropy */
256  n = ( 2 * min_entropy_bits );
257 
258  /* 3. entropy_total = 0
259  * 4. tmp = a fixed n-bit value, such as 0^n
260  * 5. While ( entropy_total < min_entropy )
261  * 5.1. ( status, entropy_bitstring, assessed_entropy )
262  * = GetEntropy()
263  * 5.2. If status indicates an error, return ( status, Null )
264  * 5.3. nonce = MakeNextNonce()
265  * 5.4. tmp = tmp XOR df ( ( nonce || entropy_bitstring ), n )
266  * 5.5. entropy_total = entropy_total + assessed_entropy
267  *
268  * (The implementation of these steps is inside the function
269  * get_entropy_input_tmp().)
270  */
271  build_assert ( __builtin_constant_p ( tmp_len ) );
272  build_assert ( n == ( 8 * tmp_len ) );
273  if ( ( rc = get_entropy_input_tmp ( MIN_ENTROPY ( min_entropy_bits ),
274  tmp, tmp_len ) ) != 0 ) {
275  return rc;
276  }
277 
278  /* 6. If ( n < min_length ), then tmp = tmp || 0^(min_length-n)
279  * 7. If ( n > max_length ), then tmp = df ( tmp, max_length )
280  * 8. Return ( SUCCESS, tmp )
281  */
282  if ( tmp_len < min_len ) {
283  /* (Data is already in-place.) */
284  build_assert ( data == tmp );
285  memset ( ( data + tmp_len ), 0, ( min_len - tmp_len ) );
286  return min_len;
287  } else if ( tmp_len > max_len ) {
288  build_assert ( tmp == tmp_buf );
290  data, max_len );
291  return max_len;
292  } else {
293  /* (Data is already in-place.) */
294  build_assert ( data == tmp );
295  return tmp_len;
296  }
297 }
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
uint16_t max_len
Maximum length (in bytes)
Definition: ntlm.h:18
unsigned long tmp
Definition: linux_pci.h:53
#define build_assert(condition)
Assert a condition at build time (after dead code elimination)
Definition: assert.h:76
int get_entropy_input_tmp(min_entropy_t min_entropy, uint8_t *tmp, size_t tmp_len)
Obtain entropy input temporary buffer.
Definition: entropy.c:425
#define ENTROPY_HASH_DF_OUTLEN_BYTES
Underlying hash algorithm output length (in bytes)
Definition: entropy.h:195
void hash_df(struct digest_algorithm *hash, const void *input, size_t input_len, void *output, size_t output_len)
Distribute entropy throughout a buffer.
Definition: hash_df.c:84
unsigned char uint8_t
Definition: stdint.h:10
#define MIN_ENTROPY(bits)
Construct a min-entropy fixed-point value.
Definition: entropy.h:42
uint8_t data[48]
Additional event data.
Definition: ena.h:22
#define entropy_hash_df_algorithm
Use SHA-256 as the underlying hash algorithm for Hash_df.
Definition: entropy.h:192
void * memset(void *dest, int character, size_t len) __nonnull

References build_assert, data, entropy_hash_df_algorithm, ENTROPY_HASH_DF_OUTLEN_BYTES, get_entropy_input_tmp(), hash_df(), max_len, memset(), MIN_ENTROPY, rc, and tmp.

Referenced by drbg_instantiate(), and drbg_reseed().

◆ entropy_repetition_count_cutoff()

static unsigned int entropy_repetition_count_cutoff ( min_entropy_t  min_entropy_per_sample)
inlinestatic

Calculate cutoff value for the repetition count test.

Parameters
min_entropy_per_sampleMin-entropy per sample
Return values
cutoffCutoff value

This is the cutoff value for the Repetition Count Test defined in ANS X9.82 Part 2 (October 2011 Draft) Section 8.5.2.1.2.

Definition at line 309 of file entropy.h.

309  {
310  double max_repetitions;
311  unsigned int cutoff;
312 
313  /* The cutoff formula for the repetition test is:
314  *
315  * C = ( 1 + ( -log2(W) / H_min ) )
316  *
317  * where W is set at 2^(-30) (in ANS X9.82 Part 2 (October
318  * 2011 Draft) Section 8.5.2.1.3.1).
319  */
320  max_repetitions = ( 1 + ( MIN_ENTROPY ( 30 ) /
321  min_entropy_per_sample ) );
322 
323  /* Round up to a whole number of repetitions. We don't have
324  * the ceil() function available, so do the rounding by hand.
325  */
326  cutoff = max_repetitions;
327  if ( cutoff < max_repetitions )
328  cutoff++;
329  build_assert ( cutoff >= max_repetitions );
330 
331  /* Floating-point operations are not allowed in iPXE since we
332  * never set up a suitable environment. Abort the build
333  * unless the calculated number of repetitions is a
334  * compile-time constant.
335  */
336  build_assert ( __builtin_constant_p ( cutoff ) );
337 
338  return cutoff;
339 }
#define build_assert(condition)
Assert a condition at build time (after dead code elimination)
Definition: assert.h:76
#define MIN_ENTROPY(bits)
Construct a min-entropy fixed-point value.
Definition: entropy.h:42

References build_assert, and MIN_ENTROPY.

Referenced by entropy_init().

◆ entropy_adaptive_proportion_cutoff_lookup()

static unsigned int entropy_adaptive_proportion_cutoff_lookup ( unsigned int  n,
unsigned int  h 
)
inlinestatic

Look up value in adaptive proportion test cutoff table.

Parameters
nN (window size)
hH (min-entropy)
Return values
cutoffCutoff

This is the table of cutoff values defined in ANS X9.82 Part 2 (October 2011 Draft) Section 8.5.2.1.3.1.2.

Definition at line 395 of file entropy.h.

395  {
396  switch ( APC_N_H ( n, h ) ) {
397  APC_TABLE_ROW ( 1, APC_NA, 51, 168, 2240, 33537 );
398  APC_TABLE_ROW ( 2, APC_NA, 35, 100, 1193, 17053 );
399  APC_TABLE_ROW ( 3, 10, 24, 61, 643, 8705 );
400  APC_TABLE_ROW ( 4, 8, 16, 38, 354, 4473 );
401  APC_TABLE_ROW ( 5, 6, 12, 25, 200, 2321 );
402  APC_TABLE_ROW ( 6, 5, 9, 17, 117, 1220 );
403  APC_TABLE_ROW ( 7, 4, 7, 15, 71, 653 );
404  APC_TABLE_ROW ( 8, 4, 5, 9, 45, 358 );
405  APC_TABLE_ROW ( 9, 3, 4, 7, 30, 202 );
406  APC_TABLE_ROW ( 10, 3, 4, 5, 21, 118 );
407  APC_TABLE_ROW ( 11, 2, 3, 4, 15, 71 );
408  APC_TABLE_ROW ( 12, 2, 3, 4, 11, 45 );
409  APC_TABLE_ROW ( 13, 2, 2, 3, 9, 30 );
410  APC_TABLE_ROW ( 14, 2, 2, 3, 7, 21 );
411  APC_TABLE_ROW ( 15, 1, 2, 2, 6, 15 );
412  APC_TABLE_ROW ( 16, 1, 2, 2, 5, 11 );
413  APC_TABLE_ROW ( 17, 1, 1, 2, 4, 9 );
414  APC_TABLE_ROW ( 18, 1, 1, 2, 4, 7 );
415  APC_TABLE_ROW ( 19, 1, 1, 1, 3, 6 );
416  APC_TABLE_ROW ( 20, 1, 1, 1, 3, 5 );
417  default:
418  return APC_NA;
419  }
420 }
uint32_t h
Definition: sha256.c:35
#define APC_N_H(n, h)
Combine adaptive proportion test window size and min-entropy.
Definition: entropy.h:362
#define APC_TABLE_ROW(h, c16, c64, c256, c4096, c65536)
Define a row of the adaptive proportion cutoff table.
Definition: entropy.h:374
#define APC_NA
Value used to represent "N/A" in adaptive proportion cutoff table.
Definition: entropy.h:382

References APC_N_H, APC_NA, APC_TABLE_ROW, and h.

Referenced by entropy_adaptive_proportion_cutoff().

◆ entropy_adaptive_proportion_cutoff()

static unsigned int entropy_adaptive_proportion_cutoff ( min_entropy_t  min_entropy_per_sample)
inlinestatic

Calculate cutoff value for the adaptive proportion test.

Parameters
min_entropy_per_sampleMin-entropy per sample
Return values
cutoffCutoff value

This is the cutoff value for the Adaptive Proportion Test defined in ANS X9.82 Part 2 (October 2011 Draft) Section 8.5.2.1.3.1.2.

Definition at line 432 of file entropy.h.

432  {
433  unsigned int h;
434  unsigned int n;
435  unsigned int cutoff;
436 
437  /* Look up cutoff value in cutoff table */
439  h = ( min_entropy_per_sample / MIN_ENTROPY_SCALE );
441 
442  /* Fail unless cutoff value is a compile-time constant */
443  build_assert ( __builtin_constant_p ( cutoff ) );
444 
445  /* Fail if cutoff value is N/A */
446  build_assert ( cutoff != APC_NA );
447 
448  return cutoff;
449 }
#define MIN_ENTROPY_SCALE
Fixed-point scale for min-entropy amounts.
Definition: entropy.h:34
uint32_t h
Definition: sha256.c:35
#define build_assert(condition)
Assert a condition at build time (after dead code elimination)
Definition: assert.h:76
static unsigned int entropy_adaptive_proportion_cutoff_lookup(unsigned int n, unsigned int h)
Look up value in adaptive proportion test cutoff table.
Definition: entropy.h:395
#define ADAPTIVE_PROPORTION_WINDOW_SIZE
Window size for the adaptive proportion test.
Definition: entropy.h:353
#define APC_NA
Value used to represent "N/A" in adaptive proportion cutoff table.
Definition: entropy.h:382

References ADAPTIVE_PROPORTION_WINDOW_SIZE, APC_NA, build_assert, entropy_adaptive_proportion_cutoff_lookup(), h, and MIN_ENTROPY_SCALE.

Referenced by entropy_init().

◆ entropy_startup_test_count()

static unsigned int entropy_startup_test_count ( unsigned int  repetition_count_cutoff,
unsigned int  adaptive_proportion_cutoff 
)
inlinestatic

Calculate number of samples required for startup tests.

Parameters
repetition_count_cutoffRepetition count test cutoff value
adaptive_proportion_cutoffAdaptive proportion test cutoff value
Return values
num_samplesNumber of samples required

ANS X9.82 Part 2 (October 2011 Draft) Section 8.5.2.1.5 requires that at least one full cycle of the continuous tests must be performed at start-up.

Definition at line 463 of file entropy.h.

464  {
465  unsigned int num_samples;
466 
467  /* At least max(N,C) samples shall be generated by the noise
468  * source for start-up testing.
469  */
470  num_samples = repetition_count_cutoff;
471  if ( num_samples < adaptive_proportion_cutoff )
472  num_samples = adaptive_proportion_cutoff;
473  build_assert ( __builtin_constant_p ( num_samples ) );
474 
475  return num_samples;
476 }
#define build_assert(condition)
Assert a condition at build time (after dead code elimination)
Definition: assert.h:76

References build_assert.

Referenced by entropy_init().

◆ entropy_init()

static void entropy_init ( struct entropy_source source,
min_entropy_t  min_entropy_per_sample 
)
inlinestatic

Initialise entropy source.

Parameters
sourceEntropy source
min_entropy_per_sampleMin-entropy per sample

The cutoff value calculations for the repetition count test and the adaptive proportion test are provided as static inline functions since the results will always be compile-time constants.

Definition at line 489 of file entropy.h.

490  {
491  unsigned int repetition_count_cutoff;
492  unsigned int adaptive_proportion_cutoff;
493  unsigned int startup_test_count;
494 
495  /* Sanity check */
496  build_assert ( min_entropy_per_sample > MIN_ENTROPY ( 0 ) );
497  build_assert ( min_entropy_per_sample <=
498  MIN_ENTROPY ( 8 * sizeof ( noise_sample_t ) ) );
499 
500  /* Calculate test cutoff values */
501  repetition_count_cutoff =
502  entropy_repetition_count_cutoff ( min_entropy_per_sample );
503  adaptive_proportion_cutoff =
504  entropy_adaptive_proportion_cutoff ( min_entropy_per_sample );
505  startup_test_count =
506  entropy_startup_test_count ( repetition_count_cutoff,
507  adaptive_proportion_cutoff );
508 
509  /* Record min-entropy per sample and test cutoff values */
510  source->min_entropy_per_sample = min_entropy_per_sample;
511  source->repetition_count_test.cutoff = repetition_count_cutoff;
512  source->adaptive_proportion_test.cutoff = adaptive_proportion_cutoff;
513  source->startup_test.count = startup_test_count;
514 }
static unsigned int entropy_adaptive_proportion_cutoff(min_entropy_t min_entropy_per_sample)
Calculate cutoff value for the adaptive proportion test.
Definition: entropy.h:432
static unsigned int entropy_startup_test_count(unsigned int repetition_count_cutoff, unsigned int adaptive_proportion_cutoff)
Calculate number of samples required for startup tests.
Definition: entropy.h:463
min_entropy_t min_entropy_per_sample
min-entropy per sample
Definition: entropy.h:131
struct entropy_repetition_count_test repetition_count_test
Repetition count test state.
Definition: entropy.h:133
struct entropy_startup_test startup_test
Startup test state.
Definition: entropy.h:137
static unsigned int entropy_repetition_count_cutoff(min_entropy_t min_entropy_per_sample)
Calculate cutoff value for the repetition count test.
Definition: entropy.h:309
#define build_assert(condition)
Assert a condition at build time (after dead code elimination)
Definition: assert.h:76
#define MIN_ENTROPY(bits)
Construct a min-entropy fixed-point value.
Definition: entropy.h:42
struct entropy_adaptive_proportion_test adaptive_proportion_test
Adaptive proportion test state.
Definition: entropy.h:135
unsigned int count
Number of startup tests required for one full cycle.
Definition: entropy.h:112
uint8_t noise_sample_t
A noise sample.
Definition: entropy.h:21
unsigned int cutoff
C = the cutoff value above which the repetition test should fail.
Definition: entropy.h:65
unsigned int cutoff
C = the cutoff value above which the repetition test should fail.
Definition: entropy.h:94

References entropy_source::adaptive_proportion_test, build_assert, entropy_startup_test::count, entropy_repetition_count_test::cutoff, entropy_adaptive_proportion_test::cutoff, entropy_adaptive_proportion_cutoff(), entropy_repetition_count_cutoff(), entropy_startup_test_count(), MIN_ENTROPY, entropy_source::min_entropy_per_sample, entropy_source::repetition_count_test, and entropy_source::startup_test.

Referenced by efi_entropy_enable(), efirng_enable(), rdrand_entropy_enable(), and rtc_entropy_enable().

◆ entropy_enable()

int entropy_enable ( struct entropy_source source)

Enable entropy gathering.

Parameters
sourceEntropy source
Return values
rcReturn status code

Definition at line 302 of file entropy.c.

302  {
303  int rc;
304 
305  /* Refuse to enable a previously failed source */
306  if ( ( rc = source->rc ) != 0 )
307  return rc;
308 
309  /* Enable entropy source */
310  if ( ( rc = source->enable() ) != 0 ) {
311  DBGC ( source, "ENTROPY %s could not enable: %s\n",
312  source->name, strerror ( rc ) );
313  source->rc = rc;
314  return rc;
315  }
316 
317  /* Sanity check */
318  assert ( source->min_entropy_per_sample > 0 );
319 
320  /* Initialise test state if this source has not previously been used */
321  if ( source->startup_test.tested == 0 ) {
322  repetition_count_test_init ( source );
324  startup_test_init ( source );
325  }
326 
327  DBGC ( source, "ENTROPY %s enabled\n", source->name );
328  return 0;
329 }
int rc
Failure status (if any)
Definition: entropy.h:143
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
unsigned int tested
Number of startup tests performed.
Definition: entropy.h:106
int(* enable)(void)
Enable entropy gathering.
Definition: entropy.h:150
#define DBGC(...)
Definition: compiler.h:505
min_entropy_t min_entropy_per_sample
min-entropy per sample
Definition: entropy.h:131
static void adaptive_proportion_test_init(struct entropy_source *source)
Initialise adaptive proportion test.
Definition: entropy.c:128
const char * name
Name.
Definition: entropy.h:118
assert((readw(&hdr->flags) &(GTF_reading|GTF_writing))==0)
struct entropy_startup_test startup_test
Startup test state.
Definition: entropy.h:137
static void startup_test_init(struct entropy_source *source)
Initialise startup test.
Definition: entropy.c:265
static void repetition_count_test_init(struct entropy_source *source)
Initialise repetition count test.
Definition: entropy.c:58
char * strerror(int errno)
Retrieve string representation of error number.
Definition: strerror.c:78

References adaptive_proportion_test_init(), assert(), DBGC, entropy_source::enable, entropy_source::min_entropy_per_sample, entropy_source::name, entropy_source::rc, rc, repetition_count_test_init(), entropy_source::startup_test, startup_test_init(), strerror(), and entropy_startup_test::tested.

Referenced by entropy_enable_and_test(), and entropy_sample().

◆ entropy_disable()

void entropy_disable ( struct entropy_source source)

Disable entropy gathering.

Parameters
sourceEntropy source

Definition at line 385 of file entropy.c.

385  {
386 
387  /* Disable entropy gathering, if applicable */
388  if ( source->disable )
389  source->disable();
390 
391  DBGC ( source, "ENTROPY %s disabled\n", source->name );
392 }
void(* disable)(void)
Disable entropy gathering.
Definition: entropy.h:155
#define DBGC(...)
Definition: compiler.h:505
const char * name
Name.
Definition: entropy.h:118

References DBGC, entropy_source::disable, and entropy_source::name.

Referenced by entropy_enable_and_test(), entropy_sample(), and get_entropy_input_tmp().