123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245 |
- #ifndef _IPXE_ENTROPY_H
- #define _IPXE_ENTROPY_H
-
- /** @file
- *
- * Entropy source
- *
- */
-
- FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
-
- #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>
-
- /**
- * Calculate static inline entropy API function name
- *
- * @v _prefix Subsystem prefix
- * @v _api_func API function
- * @ret _subsys_func Subsystem API function
- */
- #define ENTROPY_INLINE( _subsys, _api_func ) \
- SINGLE_API_INLINE ( ENTROPY_PREFIX_ ## _subsys, _api_func )
-
- /**
- * Provide a entropy API implementation
- *
- * @v _prefix Subsystem prefix
- * @v _api_func API function
- * @v _func Implementing function
- */
- #define PROVIDE_ENTROPY( _subsys, _api_func, _func ) \
- PROVIDE_SINGLE_API ( ENTROPY_PREFIX_ ## _subsys, _api_func, _func )
-
- /**
- * Provide a static inline entropy API implementation
- *
- * @v _prefix Subsystem prefix
- * @v _api_func API function
- */
- #define PROVIDE_ENTROPY_INLINE( _subsys, _api_func ) \
- PROVIDE_SINGLE_API_INLINE ( ENTROPY_PREFIX_ ## _subsys, _api_func )
-
- /** A noise sample */
- typedef uint8_t noise_sample_t;
-
- /** An entropy sample */
- typedef uint8_t entropy_sample_t;
-
- /** An amount of min-entropy
- *
- * Expressed as a fixed-point quantity in order to avoid floating
- * point calculations.
- */
- typedef unsigned int min_entropy_t;
-
- /** Fixed-point scale for min-entropy amounts */
- #define MIN_ENTROPY_SCALE ( 1 << 16 )
-
- /**
- * Construct a min-entropy fixed-point value
- *
- * @v bits min-entropy in bits
- * @ret min_entropy min-entropy as a fixed-point value
- */
- #define MIN_ENTROPY( bits ) \
- ( ( min_entropy_t ) ( (bits) * MIN_ENTROPY_SCALE ) )
-
- /* Include all architecture-independent entropy API headers */
- #include <ipxe/null_entropy.h>
- #include <ipxe/efi/efi_entropy.h>
- #include <ipxe/linux/linux_entropy.h>
-
- /* Include all architecture-dependent entropy API headers */
- #include <bits/entropy.h>
-
- /**
- * Enable entropy gathering
- *
- * @ret rc Return status code
- */
- int entropy_enable ( void );
-
- /**
- * Disable entropy gathering
- *
- */
- void entropy_disable ( void );
-
- /**
- * min-entropy per sample
- *
- * @ret min_entropy min-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.
- */
- min_entropy_t min_entropy_per_sample ( void );
-
- /**
- * Get noise sample
- *
- * @ret noise Noise sample
- * @ret rc Return status code
- *
- * This is the GetNoise function defined in ANS X9.82 Part 2
- * (October 2011 Draft) Section 6.5.2.
- */
- int get_noise ( noise_sample_t *noise );
-
- extern int get_entropy_input_tmp ( unsigned int num_samples,
- uint8_t *tmp, size_t tmp_len );
-
- /** Use SHA-256 as the underlying hash algorithm for Hash_df
- *
- * Hash_df using SHA-256 is an Approved algorithm in ANS X9.82.
- */
- #define entropy_hash_df_algorithm sha256_algorithm
-
- /** Underlying hash algorithm output length (in bytes) */
- #define ENTROPY_HASH_DF_OUTLEN_BYTES SHA256_DIGEST_SIZE
-
- /**
- * Obtain entropy input
- *
- * @v min_entropy_bits Minimum amount of entropy, in bits
- * @v data Data buffer
- * @v min_len Minimum length of entropy input, in bytes
- * @v max_len Maximum length of entropy input, in bytes
- * @ret len Length 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.
- */
- static inline __attribute__ (( always_inline )) int
- get_entropy_input ( unsigned int min_entropy_bits, void *data, size_t min_len,
- size_t max_len ) {
- size_t tmp_len = ( ( ( min_entropy_bits * 2 ) + 7 ) / 8 );
- uint8_t tmp_buf[ tmp_len ];
- uint8_t *tmp = ( ( tmp_len > max_len ) ? tmp_buf : data );
- double min_samples;
- unsigned int num_samples;
- unsigned int n;
- int rc;
-
- /* Sanity checks */
- 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 );
-
- /* Round up minimum entropy to an integral number of bytes */
- min_entropy_bits = ( ( min_entropy_bits + 7 ) & ~7 );
-
- /* Calculate number of samples required to contain sufficient entropy */
- min_samples = ( MIN_ENTROPY ( min_entropy_bits ) /
- min_entropy_per_sample() );
-
- /* Round up to a whole number of samples. We don't have the
- * ceil() function available, so do the rounding by hand.
- */
- num_samples = min_samples;
- if ( num_samples < min_samples )
- num_samples++;
- linker_assert ( ( num_samples >= min_samples ), rounding_error );
-
- /* Floating-point operations are not allowed in iPXE since we
- * never set up a suitable environment. Abort the build
- * unless the calculated number of samples is a compile-time
- * constant.
- */
- linker_assert ( __builtin_constant_p ( num_samples ),
- num_samples_not_constant );
-
- /* (Unnumbered). The output length of the hash function shall
- * meet or exceed the security strength indicated by the
- * min_entropy parameter.
- */
- linker_assert ( ( ( 8 * ENTROPY_HASH_DF_OUTLEN_BYTES ) >=
- min_entropy_bits ), hash_df_algorithm_too_weak );
-
- /* 1. If ( min_length > max_length ), then return ( FAILURE, Null ) */
- linker_assert ( ( min_len <= max_len ), min_len_greater_than_max_len );
-
- /* 2. n = 2 * min_entropy */
- n = ( 2 * min_entropy_bits );
-
- /* 3. entropy_total = 0
- * 4. tmp = a fixed n-bit value, such as 0^n
- * 5. While ( entropy_total < min_entropy )
- * 5.1. ( status, entropy_bitstring, assessed_entropy )
- * = GetEntropy()
- * 5.2. If status indicates an error, return ( status, Null )
- * 5.3. nonce = MakeNextNonce()
- * 5.4. tmp = tmp XOR df ( ( nonce || entropy_bitstring ), n )
- * 5.5. entropy_total = entropy_total + assessed_entropy
- *
- * (The implementation of these steps is inside the function
- * get_entropy_input_tmp().)
- */
- 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;
-
- /* 6. If ( n < min_length ), then tmp = tmp || 0^(min_length-n)
- * 7. If ( n > max_length ), then tmp = df ( tmp, max_length )
- * 8. Return ( SUCCESS, tmp )
- */
- if ( tmp_len < min_len ) {
- /* (Data is already in-place.) */
- linker_assert ( ( data == tmp ), data_not_inplace );
- memset ( ( data + tmp_len ), 0, ( min_len - tmp_len ) );
- return min_len;
- } else if ( tmp_len > max_len ) {
- linker_assert ( ( tmp == tmp_buf ), data_inplace );
- hash_df ( &entropy_hash_df_algorithm, tmp, tmp_len,
- data, max_len );
- return max_len;
- } else {
- /* (Data is already in-place.) */
- linker_assert ( ( data == tmp ), data_not_inplace );
- return tmp_len;
- }
- }
-
- #endif /* _IPXE_ENTROPY_H */
|