iPXE
Macros | Typedefs | Functions | Variables
entropy.h File Reference

Entropy source. More...

#include <stdint.h>
#include <string.h>
#include <assert.h>
#include <ipxe/api.h>
#include <ipxe/hash_df.h>
#include <ipxe/sha256.h>
#include <config/entropy.h>
#include <ipxe/null_entropy.h>
#include <ipxe/efi/efi_entropy.h>
#include <ipxe/linux/linux_entropy.h>
#include <bits/entropy.h>

Go to the source code of this file.

Macros

#define ENTROPY_INLINE(_subsys, _api_func)   SINGLE_API_INLINE ( ENTROPY_PREFIX_ ## _subsys, _api_func )
 Calculate static inline entropy API function name. More...
 
#define PROVIDE_ENTROPY(_subsys, _api_func, _func)   PROVIDE_SINGLE_API ( ENTROPY_PREFIX_ ## _subsys, _api_func, _func )
 Provide a entropy API implementation. More...
 
#define PROVIDE_ENTROPY_INLINE(_subsys, _api_func)   PROVIDE_SINGLE_API_INLINE ( ENTROPY_PREFIX_ ## _subsys, _api_func )
 Provide a static inline entropy API implementation. More...
 
#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_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...
 

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 entropy_enable (void)
 Enable entropy gathering. More...
 
void entropy_disable (void)
 Disable entropy gathering. More...
 
min_entropy_t min_entropy_per_sample (void)
 min-entropy per sample More...
 
int get_noise (noise_sample_t *noise)
 Get noise sample. More...
 
int get_entropy_input_tmp (unsigned int num_samples, uint8_t *tmp, size_t tmp_len)
 Obtain entropy input temporary buffer. More...
 
static __attribute__ ((always_inline)) int get_entropy_input(unsigned int min_entropy_bits
 Obtain entropy input. More...
 
 linker_assert ((min_entropy_per_sample()<=MIN_ENTROPY(8 *sizeof(noise_sample_t))), min_entropy_per_sample_is_impossibly_high)
 
 linker_assert ((min_entropy_bits<=(8 *max_len)), entropy_buffer_too_small)
 
 if (num_samples< min_samples) num_samples++
 
 linker_assert ((num_samples >=min_samples), rounding_error)
 
 linker_assert (__builtin_constant_p(num_samples), num_samples_not_constant)
 
 linker_assert (((8 *ENTROPY_HASH_DF_OUTLEN_BYTES) >=min_entropy_bits), hash_df_algorithm_too_weak)
 
 linker_assert ((min_len<=max_len), min_len_greater_than_max_len)
 
 linker_assert (__builtin_constant_p(tmp_len), tmp_len_not_constant)
 
 linker_assert ((n==(8 *tmp_len)), tmp_len_mismatch)
 
 if ((rc=get_entropy_input_tmp(num_samples, tmp, tmp_len)) !=0) return rc
 
else if (tmp_len > max_len)
 

Variables

static void * data
 
static void size_t min_len
 
static void size_t size_t max_len
 
uint8_t tmp_buf [tmp_len]
 
uint8_ttmp = ( ( tmp_len > max_len ) ? tmp_buf : data )
 
double min_samples
 
unsigned int num_samples = min_samples
 
unsigned int n = ( 2 * min_entropy_bits )
 
int rc
 
 min_entropy_bits = ( ( min_entropy_bits + 7 ) & ~7 )
 
 else
 
return tmp_len
 

Detailed Description

Entropy source.

Definition in file entropy.h.

Macro Definition Documentation

◆ ENTROPY_INLINE

#define ENTROPY_INLINE (   _subsys,
  _api_func 
)    SINGLE_API_INLINE ( ENTROPY_PREFIX_ ## _subsys, _api_func )

Calculate static inline entropy API function name.

Parameters
_prefixSubsystem prefix
_api_funcAPI function
Return values
_subsys_funcSubsystem API function

Definition at line 27 of file entropy.h.

◆ PROVIDE_ENTROPY

#define PROVIDE_ENTROPY (   _subsys,
  _api_func,
  _func 
)    PROVIDE_SINGLE_API ( ENTROPY_PREFIX_ ## _subsys, _api_func, _func )

Provide a entropy API implementation.

Parameters
_prefixSubsystem prefix
_api_funcAPI function
_funcImplementing function

Definition at line 37 of file entropy.h.

◆ PROVIDE_ENTROPY_INLINE

#define PROVIDE_ENTROPY_INLINE (   _subsys,
  _api_func 
)    PROVIDE_SINGLE_API_INLINE ( ENTROPY_PREFIX_ ## _subsys, _api_func )

Provide a static inline entropy API implementation.

Parameters
_prefixSubsystem prefix
_api_funcAPI function

Definition at line 46 of file entropy.h.

◆ MIN_ENTROPY_SCALE

#define MIN_ENTROPY_SCALE   ( 1 << 16 )

Fixed-point scale for min-entropy amounts.

Definition at line 63 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 71 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 129 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 132 of file entropy.h.

Typedef Documentation

◆ noise_sample_t

A noise sample.

Definition at line 50 of file entropy.h.

◆ entropy_sample_t

An entropy sample.

Definition at line 53 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 60 of file entropy.h.

Function Documentation

◆ FILE_LICENCE()

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL  )

◆ entropy_enable()

int entropy_enable ( void  )

Enable entropy gathering.

Return values
rcReturn status code

Referenced by entropy_sample_test_exec(), and get_entropy_input_tmp().

◆ entropy_disable()

void entropy_disable ( void  )

Disable entropy gathering.

Referenced by entropy_sample_test_exec(), and get_entropy_input_tmp().

◆ min_entropy_per_sample()

min_entropy_t min_entropy_per_sample ( void  )

min-entropy per sample

Return values
min_entropymin-entropy of each sample

min-entropy is defined in ANS X9.82 Part 1-2006 Section 8.3 and in NIST SP 800-90 Appendix C.3 as

H_min = -log2 ( p_max )

where p_max is the probability of the most likely sample value.

This must be a compile-time constant.

Referenced by __attribute__().

◆ get_noise()

int get_noise ( noise_sample_t noise)

Get noise sample.

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.

Referenced by entropy_sample_test_exec(), and get_entropy().

◆ get_entropy_input_tmp()

int get_entropy_input_tmp ( unsigned int  num_samples,
uint8_t tmp,
size_t  tmp_len 
)

Obtain entropy input temporary buffer.

Parameters
num_samplesNumber of entropy samples
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.

To minimise code size, the number of samples required is calculated at compilation time.

Definition at line 419 of file entropy.c.

420  {
421  static unsigned int startup_tested = 0;
422  struct {
423  uint32_t nonce;
424  entropy_sample_t sample;
425  } __attribute__ (( packed )) data;;
426  uint8_t df_buf[tmp_len];
427  unsigned int i;
428  int rc;
429 
430  /* Enable entropy gathering */
431  if ( ( rc = entropy_enable() ) != 0 )
432  return rc;
433 
434  /* Perform mandatory startup tests, if not yet performed */
435  for ( ; startup_tested < startup_test_count() ; startup_tested++ ) {
436  if ( ( rc = get_entropy ( &data.sample ) ) != 0 )
437  goto err_get_entropy;
438  }
439 
440  /* 3. entropy_total = 0
441  *
442  * (Nothing to do; the number of entropy samples required has
443  * already been precalculated.)
444  */
445 
446  /* 4. tmp = a fixed n-bit value, such as 0^n */
447  memset ( tmp, 0, tmp_len );
448 
449  /* 5. While ( entropy_total < min_entropy ) */
450  while ( num_samples-- ) {
451  /* 5.1. ( status, entropy_bitstring, assessed_entropy )
452  * = GetEntropy()
453  * 5.2. If status indicates an error, return ( status, Null )
454  */
455  if ( ( rc = get_entropy ( &data.sample ) ) != 0 )
456  goto err_get_entropy;
457 
458  /* 5.3. nonce = MakeNextNonce() */
459  data.nonce = make_next_nonce();
460 
461  /* 5.4. tmp = tmp XOR
462  * df ( ( nonce || entropy_bitstring ), n )
463  */
464  hash_df ( &entropy_hash_df_algorithm, &data, sizeof ( data ),
465  df_buf, sizeof ( df_buf ) );
466  for ( i = 0 ; i < tmp_len ; i++ )
467  tmp[i] ^= df_buf[i];
468 
469  /* 5.5. entropy_total = entropy_total + assessed_entropy
470  *
471  * (Nothing to do; the number of entropy samples
472  * required has already been precalculated.)
473  */
474  }
475 
476  /* Disable entropy gathering */
477  entropy_disable();
478 
479  return 0;
480 
481  err_get_entropy:
482  entropy_disable();
483  return rc;
484 }
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
void entropy_disable(void)
Disable entropy gathering.
return tmp_len
Definition: entropy.h:241
static __attribute__((always_inline))
Calculate cutoff value for the repetition count test.
Definition: entropy.c:61
unsigned int num_samples
Definition: entropy.h:158
static uint32_t make_next_nonce(void)
Create next nonce value.
Definition: entropy.c:393
int entropy_enable(void)
Enable entropy gathering.
uint8_t * tmp
Definition: entropy.h:156
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
unsigned int uint32_t
Definition: stdint.h:12
uint8_t entropy_sample_t
An entropy sample.
Definition: entropy.h:53
static int get_entropy(entropy_sample_t *entropy)
Get entropy sample.
Definition: entropy.c:333
#define entropy_hash_df_algorithm
Use SHA-256 as the underlying hash algorithm for Hash_df.
Definition: entropy.h:129
struct arbelprm_port_state_change_st data
Message.
Definition: arbel.h:12
struct ntlm_nonce nonce
Server nonce.
Definition: ntlm.h:18
void * memset(void *dest, int character, size_t len) __nonnull

References __attribute__(), data, entropy_disable(), entropy_enable(), entropy_hash_df_algorithm, get_entropy(), hash_df(), make_next_nonce(), memset(), nonce, num_samples, rc, tmp, and tmp_len.

◆ __attribute__()

static __attribute__ ( (always_inline)  )
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.

To minimise code size, the number of samples required is calculated at compilation time.

◆ linker_assert() [1/8]

linker_assert ( (min_entropy_per_sample()<=MIN_ENTROPY(8 *sizeof(noise_sample_t)))  ,
min_entropy_per_sample_is_impossibly_high   
)

Referenced by if().

◆ linker_assert() [2/8]

linker_assert ( (min_entropy_bits<=(8 *max_len))  ,
entropy_buffer_too_small   
)

◆ if() [1/3]

if ( )

Definition at line 228 of file entropy.h.

228  {
229  /* (Data is already in-place.) */
230  linker_assert ( ( data == tmp ), data_not_inplace );
231  memset ( ( data + tmp_len ), 0, ( min_len - tmp_len ) );
232  return min_len;
233  } else if ( tmp_len > max_len ) {
return tmp_len
Definition: entropy.h:241
static void size_t size_t max_len
Definition: entropy.h:153
static void size_t min_len
Definition: entropy.h:152
linker_assert((min_entropy_per_sample()<=MIN_ENTROPY(8 *sizeof(noise_sample_t))), min_entropy_per_sample_is_impossibly_high)
uint8_t * tmp
Definition: entropy.h:156
static void * data
Definition: entropy.h:152
void * memset(void *dest, int character, size_t len) __nonnull

References data, linker_assert(), memset(), min_len, tmp, and tmp_len.

◆ linker_assert() [3/8]

linker_assert ( (num_samples >=min_samples ,
rounding_error   
)

◆ linker_assert() [4/8]

linker_assert ( __builtin_constant_p(num_samples ,
num_samples_not_constant   
)

◆ linker_assert() [5/8]

linker_assert ( ((8 *ENTROPY_HASH_DF_OUTLEN_BYTES) >=min_entropy_bits ,
hash_df_algorithm_too_weak   
)

◆ linker_assert() [6/8]

linker_assert ( (min_len<=max_len ,
min_len_greater_than_max_len   
)

◆ linker_assert() [7/8]

linker_assert ( __builtin_constant_p(tmp_len ,
tmp_len_not_constant   
)

◆ linker_assert() [8/8]

linker_assert ( (n==(8 *tmp_len))  ,
tmp_len_mismatch   
)

◆ if() [2/3]

◆ if() [3/3]

else if ( tmp_len  ,
max_len   
)

Definition at line 233 of file entropy.h.

233  {
234  linker_assert ( ( tmp == tmp_buf ), data_inplace );
236  data, max_len );
237  return max_len;
238  } else {
return tmp_len
Definition: entropy.h:241
static void size_t size_t max_len
Definition: entropy.h:153
uint8_t tmp_buf[tmp_len]
Definition: entropy.h:155
linker_assert((min_entropy_per_sample()<=MIN_ENTROPY(8 *sizeof(noise_sample_t))), min_entropy_per_sample_is_impossibly_high)
uint8_t * tmp
Definition: entropy.h:156
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
#define entropy_hash_df_algorithm
Use SHA-256 as the underlying hash algorithm for Hash_df.
Definition: entropy.h:129
static void * data
Definition: entropy.h:152

Variable Documentation

◆ data

void* data

Definition at line 152 of file entropy.h.

Referenced by if().

◆ min_len

void size_t min_len

Definition at line 152 of file entropy.h.

Referenced by drbg_instantiate(), drbg_reseed(), if(), and iob_pad().

◆ max_len

void size_t size_t max_len

◆ tmp_buf

uint8_t tmp_buf[tmp_len]

Definition at line 155 of file entropy.h.

Referenced by vcprintf().

◆ tmp

unsigned long tmp = ( ( tmp_len > max_len ) ? tmp_buf : data )

Definition at line 156 of file entropy.h.

Referenced by __attribute__(), a3c90x_hw_start(), aes_setkey(), aoedev_close(), ar5008_hw_spur_mitigate(), ar9002_hw_spur_mitigate(), atadev_close(), ath5k_combine_pwr_to_pdadc_curves(), ath5k_get_linear_pcdac_min(), ath9k_hw_gpio_cfg_output_mux(), base64_encode(), bigint_mod_exp_raw(), bigint_mod_exp_sample(), bigint_mod_multiply_raw(), bigint_mod_multiply_sample(), bios_ansi_seq(), cachedhcp_init(), cert_exec(), cms_free(), destroy_menu(), downloader_vredirect(), efi_block_describe(), efi_connect_controller_wrapper(), efi_local_open_path(), efi_open_attributes_name(), efi_pecoff_debug_name(), efi_pxe_udp_close(), efi_snp_flush(), efi_snp_hii_store(), ehci_companion(), eisabus_remove(), eoib_flush_peers(), eoib_remove(), epic100_open(), expand_settings(), fc_peer_login(), fc_peer_logout(), fc_port_close(), fc_port_login(), fc_port_logout(), fc_ulp_login(), fc_ulp_logout(), fcpdev_close(), fdt_path(), fetch_numeric_setting(), fetch_setting(), fiber_autoneg(), free_memblock(), free_parameters(), free_tls(), generic_settings_clear(), get_entropy_input_tmp(), ib_count_ports(), ib_destroy_mi(), if(), image_select(), imgmulti_exec(), inline_list_contains(), intf_shutdown(), intfs_vrestart(), intfs_vshutdown(), iob_concatenate(), ipoib_flush_remac(), ipoib_remove(), ipv4_create_routes(), ipv6_create_all_routes(), ipv6_sock_aton(), ipv6_table_del(), isabus_remove(), isapnpbus_remove(), iscsi_vredirect(), list_check_contents(), list_test_exec(), mac_address_from_string_specs(), mcabus_remove(), mlx_pci_config(), neighbour_flush(), net80211_free_wlanlist(), net80211_process_ie(), netvsc_recv_data(), nii_pci_close(), ntlm_append_string(), ntlm_authenticate(), parse_setting_tag(), parse_uri(), pci_read_config(), pcibus_remove(), peerdisc_discovered(), peerdisc_free(), peermux_block_stat(), posix_file_free(), process_script(), pxenv_udp_close(), remove_devices(), reprioritise_settings(), rsa_alloc(), rtl8225_rf_set_tx_power(), rtl8225z2_rf_set_tx_power(), scsidev_close(), settings_name(), srpdev_close(), t509bus_remove(), tcp_close(), tcp_process_tx_queue(), tftp_uri(), tg3_nvram_read_using_eeprom(), tg3_reset_hw(), TLan_MiiReadReg(), TLan_SetMulticastList(), tls_newdata_process_header(), tls_p_hash_va(), tls_prf(), tulip_probe(), unregister_usb(), uri_format_okx(), usb_flush(), usb_remove_all(), usbkbd_consume(), velocity_reset(), velocity_set_link(), vmbus_probe_channels(), vmbus_remove_channels(), vmbus_xfer_page_iobufs(), wpa_stop(), x509_free_chain(), xcm_list(), xenbus_remove(), xenstore_request(), xfer_vredirect(), and xsigo_ib_remove().

◆ min_samples

min_samples
Initial value:
min_entropy_t min_entropy_per_sample(void)
min-entropy per sample
min_entropy_bits
Definition: entropy.h:170
#define MIN_ENTROPY(bits)
Construct a min-entropy fixed-point value.
Definition: entropy.h:71

Definition at line 157 of file entropy.h.

◆ num_samples

num_samples = min_samples

Definition at line 158 of file entropy.h.

Referenced by get_entropy_input_tmp().

◆ n

n = ( 2 * min_entropy_bits )

◆ rc

int rc

Definition at line 160 of file entropy.h.

◆ min_entropy_bits

min_entropy_bits = ( ( min_entropy_bits + 7 ) & ~7 )

Definition at line 170 of file entropy.h.

◆ else

else
Initial value:
{
linker_assert ( ( data == tmp ), data_not_inplace )
linker_assert((min_entropy_per_sample()<=MIN_ENTROPY(8 *sizeof(noise_sample_t))), min_entropy_per_sample_is_impossibly_high)
uint8_t * tmp
Definition: entropy.h:156
static void * data
Definition: entropy.h:152

Definition at line 238 of file entropy.h.

◆ tmp_len

return tmp_len

Definition at line 241 of file entropy.h.

Referenced by get_entropy_input_tmp(), if(), and rsa_alloc().