iPXE
Defines | 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.

Defines

#define ENTROPY_INLINE(_subsys, _api_func)   SINGLE_API_INLINE ( ENTROPY_PREFIX_ ## _subsys, _api_func )
 Calculate static inline entropy API function name.
#define PROVIDE_ENTROPY(_subsys, _api_func, _func)   PROVIDE_SINGLE_API ( ENTROPY_PREFIX_ ## _subsys, _api_func, _func )
 Provide a entropy API implementation.
#define PROVIDE_ENTROPY_INLINE(_subsys, _api_func)   PROVIDE_SINGLE_API_INLINE ( ENTROPY_PREFIX_ ## _subsys, _api_func )
 Provide a static inline entropy API implementation.
#define MIN_ENTROPY_SCALE   ( 1 << 16 )
 Fixed-point scale for min-entropy amounts.
#define MIN_ENTROPY(bits)   ( ( min_entropy_t ) ( (bits) * MIN_ENTROPY_SCALE ) )
 Construct a min-entropy fixed-point value.
#define entropy_hash_df_algorithm   sha256_algorithm
 Use SHA-256 as the underlying hash algorithm for Hash_df.
#define ENTROPY_HASH_DF_OUTLEN_BYTES   SHA256_DIGEST_SIZE
 Underlying hash algorithm output length (in bytes)

Typedefs

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

Functions

 FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
int entropy_enable (void)
 Enable entropy gathering.
void entropy_disable (void)
 Disable entropy gathering.
min_entropy_t min_entropy_per_sample (void)
 min-entropy per sample
int get_noise (noise_sample_t *noise)
 Get noise sample.
int get_entropy_input_tmp (unsigned int num_samples, uint8_t *tmp, size_t tmp_len)
 Obtain entropy input temporary buffer.
static __attribute__ ((always_inline)) int get_entropy_input(unsigned int min_entropy_bits
 Obtain entropy input.

Variables

static void * data
static void size_t min_len

Detailed Description

Entropy source.

Definition in file entropy.h.


Define Documentation

#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.

#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.

#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.

#define MIN_ENTROPY_SCALE   ( 1 << 16 )

Fixed-point scale for min-entropy amounts.

Definition at line 63 of file entropy.h.

#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.

Referenced by __attribute__(), and ENTROPY_INLINE().

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.

Referenced by get_entropy_input_tmp().

Underlying hash algorithm output length (in bytes)

Definition at line 132 of file entropy.h.


Typedef Documentation

A noise sample.

Definition at line 50 of file entropy.h.

An entropy sample.

Definition at line 53 of file entropy.h.

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 ( GPL2_OR_LATER_OR_UBDL  )
int entropy_enable ( void  )

Enable entropy gathering.

Return values:
rcReturn status code

Referenced by entropy_sample_test_exec(), and get_entropy_input_tmp().

void entropy_disable ( void  )

Disable entropy gathering.

Referenced by entropy_sample_test_exec(), and get_entropy_input_tmp().

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__().

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().

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.

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

                                             {
        static unsigned int startup_tested = 0;
        struct {
                uint32_t nonce;
                entropy_sample_t sample;
        } __attribute__ (( packed )) data;;
        uint8_t df_buf[tmp_len];
        unsigned int i;
        int rc;

        /* Enable entropy gathering */
        if ( ( rc = entropy_enable() ) != 0 )
                return rc;

        /* Perform mandatory startup tests, if not yet performed */
        for ( ; startup_tested < startup_test_count() ; startup_tested++ ) {
                if ( ( rc = get_entropy ( &data.sample ) ) != 0 )
                        goto err_get_entropy;
        }

        /* 3.  entropy_total = 0
         *
         * (Nothing to do; the number of entropy samples required has
         * already been precalculated.)
         */

        /* 4.  tmp = a fixed n-bit value, such as 0^n */
        memset ( tmp, 0, tmp_len );

        /* 5.  While ( entropy_total < min_entropy ) */
        while ( num_samples-- ) {
                /* 5.1.  ( status, entropy_bitstring, assessed_entropy )
                 *       = GetEntropy()
                 * 5.2.  If status indicates an error, return ( status, Null )
                 */
                if ( ( rc = get_entropy ( &data.sample ) ) != 0 )
                        goto err_get_entropy;

                /* 5.3.  nonce = MakeNextNonce() */
                data.nonce = make_next_nonce();

                /* 5.4.  tmp = tmp XOR
                 *             df ( ( nonce || entropy_bitstring ), n )
                 */
                hash_df ( &entropy_hash_df_algorithm, &data, sizeof ( data ),
                          df_buf, sizeof ( df_buf ) );
                for ( i = 0 ; i < tmp_len ; i++ )
                        tmp[i] ^= df_buf[i];

                /* 5.5.  entropy_total = entropy_total + assessed_entropy
                 *
                 * (Nothing to do; the number of entropy samples
                 * required has already been precalculated.)
                 */
        }

        /* Disable entropy gathering */
        entropy_disable();

        return 0;

 err_get_entropy:
        entropy_disable();
        return rc;
}
static __attribute__ ( (always_inline)  ) [inline, static]

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.


Variable Documentation

void* data

Definition at line 152 of file entropy.h.

Definition at line 152 of file entropy.h.

Referenced by drbg_instantiate(), and drbg_reseed().