qemu/roms/ipxe/src/include/ipxe/entropy.h

   1 #ifndef _IPXE_ENTROPY_H
   2 #define _IPXE_ENTROPY_H
   3
   4 /** @file
   5  *
   6  * Entropy source
   7  *
   8  */
   9
  10 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
  11
  12 #include <stdint.h>
  13 #include <string.h>
  14 #include <assert.h>
  15 #include <ipxe/api.h>
  16 #include <ipxe/hash_df.h>
  17 #include <ipxe/sha256.h>
  18 #include <config/entropy.h>
  19
  20 /**
  21  * Calculate static inline entropy API function name
  22  *
  23  * @v _prefix           Subsystem prefix
  24  * @v _api_func         API function
  25  * @ret _subsys_func    Subsystem API function
  26  */
  27 #define ENTROPY_INLINE( _subsys, _api_func ) \
  28         SINGLE_API_INLINE ( ENTROPY_PREFIX_ ## _subsys, _api_func )
  29
  30 /**
  31  * Provide a entropy API implementation
  32  *
  33  * @v _prefix           Subsystem prefix
  34  * @v _api_func         API function
  35  * @v _func             Implementing function
  36  */
  37 #define PROVIDE_ENTROPY( _subsys, _api_func, _func ) \
  38         PROVIDE_SINGLE_API ( ENTROPY_PREFIX_ ## _subsys, _api_func, _func )
  39
  40 /**
  41  * Provide a static inline entropy API implementation
  42  *
  43  * @v _prefix           Subsystem prefix
  44  * @v _api_func         API function
  45  */
  46 #define PROVIDE_ENTROPY_INLINE( _subsys, _api_func ) \
  47         PROVIDE_SINGLE_API_INLINE ( ENTROPY_PREFIX_ ## _subsys, _api_func )
  48
  49 /** A noise sample */
  50 typedef uint8_t noise_sample_t;
  51
  52 /** An entropy sample */
  53 typedef uint8_t entropy_sample_t;
  54
  55 /* Include all architecture-independent entropy API headers */
  56 #include <ipxe/null_entropy.h>
  57 #include <ipxe/efi/efi_entropy.h>
  58 #include <ipxe/linux/linux_entropy.h>
  59
  60 /* Include all architecture-dependent entropy API headers */
  61 #include <bits/entropy.h>
  62
  63 /**
  64  * Enable entropy gathering
  65  *
  66  * @ret rc              Return status code
  67  */
  68 int entropy_enable ( void );
  69
  70 /**
  71  * Disable entropy gathering
  72  *
  73  */
  74 void entropy_disable ( void );
  75
  76 /**
  77  * min-entropy per sample
  78  *
  79  * @ret min_entropy     min-entropy of each sample
  80  *
  81  * min-entropy is defined in ANS X9.82 Part 1-2006 Section 8.3 and in
  82  * NIST SP 800-90 Appendix C.3 as
  83  *
  84  *    H_min = -log2 ( p_max )
  85  *
  86  * where p_max is the probability of the most likely sample value.
  87  *
  88  * This must be a compile-time constant.
  89  */
  90 double min_entropy_per_sample ( void );
  91
  92 /**
  93  * Get noise sample
  94  *
  95  * @ret noise           Noise sample
  96  * @ret rc              Return status code
  97  *
  98  * This is the GetNoise function defined in ANS X9.82 Part 2
  99  * (October 2011 Draft) Section 6.5.2.
 100  */
 101 int get_noise ( noise_sample_t *noise );
 102
 103 extern int get_entropy_input_tmp ( unsigned int num_samples,
 104                                    uint8_t *tmp, size_t tmp_len );
 105
 106 /** Use SHA-256 as the underlying hash algorithm for Hash_df
 107  *
 108  * Hash_df using SHA-256 is an Approved algorithm in ANS X9.82.
 109  */
 110 #define entropy_hash_df_algorithm sha256_algorithm
 111
 112 /** Underlying hash algorithm output length (in bytes) */
 113 #define ENTROPY_HASH_DF_OUTLEN_BYTES SHA256_DIGEST_SIZE
 114
 115 /**
 116  * Obtain entropy input
 117  *
 118  * @v min_entropy_bits  Minimum amount of entropy, in bits
 119  * @v data              Data buffer
 120  * @v min_len           Minimum length of entropy input, in bytes
 121  * @v max_len           Maximum length of entropy input, in bytes
 122  * @ret len             Length of entropy input, in bytes, or negative error
 123  *
 124  * This is the implementation of the Get_entropy_input function (using
 125  * an entropy source as the source of entropy input and condensing
 126  * each entropy source output after each GetEntropy call) as defined
 127  * in ANS X9.82 Part 4 (April 2011 Draft) Section 13.3.4.2.
 128  *
 129  * To minimise code size, the number of samples required is calculated
 130  * at compilation time.
 131  */
 132 static inline __attribute__ (( always_inline )) int
 133 get_entropy_input ( unsigned int min_entropy_bits, void *data, size_t min_len,
 134                     size_t max_len ) {
 135         size_t tmp_len = ( ( ( min_entropy_bits * 2 ) + 7 ) / 8 );
 136         uint8_t tmp_buf[ tmp_len ];
 137         uint8_t *tmp = ( ( tmp_len > max_len ) ? tmp_buf : data );
 138         double min_samples;
 139         unsigned int num_samples;
 140         unsigned int n;
 141         int rc;
 142
 143         /* Sanity checks */
 144         linker_assert ( ( min_entropy_per_sample() <=
 145                           ( 8 * sizeof ( noise_sample_t ) ) ),
 146                         min_entropy_per_sample_is_impossibly_high );
 147         linker_assert ( ( min_entropy_bits <= ( 8 * max_len ) ),
 148                         entropy_buffer_too_small );
 149
 150         /* Round up minimum entropy to an integral number of bytes */
 151         min_entropy_bits = ( ( min_entropy_bits + 7 ) & ~7 );
 152
 153         /* Calculate number of samples required to contain sufficient entropy */
 154         min_samples = ( ( min_entropy_bits * 1.0 ) / min_entropy_per_sample() );
 155
 156         /* Round up to a whole number of samples.  We don't have the
 157          * ceil() function available, so do the rounding by hand.
 158          */
 159         num_samples = min_samples;
 160         if ( num_samples < min_samples )
 161                 num_samples++;
 162         linker_assert ( ( num_samples >= min_samples ), rounding_error );
 163
 164         /* Floating-point operations are not allowed in iPXE since we
 165          * never set up a suitable environment.  Abort the build
 166          * unless the calculated number of samples is a compile-time
 167          * constant.
 168          */
 169         linker_assert ( __builtin_constant_p ( num_samples ),
 170                         num_samples_not_constant );
 171
 172         /* (Unnumbered).  The output length of the hash function shall
 173          * meet or exceed the security strength indicated by the
 174          * min_entropy parameter.
 175          */
 176         linker_assert ( ( ( 8 * ENTROPY_HASH_DF_OUTLEN_BYTES ) >=
 177                           min_entropy_bits ), hash_df_algorithm_too_weak );
 178
 179         /* 1.  If ( min_length > max_length ), then return ( FAILURE, Null ) */
 180         linker_assert ( ( min_len <= max_len ), min_len_greater_than_max_len );
 181
 182         /* 2.  n = 2 * min_entropy */
 183         n = ( 2 * min_entropy_bits );
 184
 185         /* 3.  entropy_total = 0
 186          * 4.  tmp = a fixed n-bit value, such as 0^n
 187          * 5.  While ( entropy_total < min_entropy )
 188          *     5.1.  ( status, entropy_bitstring, assessed_entropy )
 189          *           = GetEntropy()
 190          *     5.2.  If status indicates an error, return ( status, Null )
 191          *     5.3.  nonce = MakeNextNonce()
 192          *     5.4.  tmp = tmp XOR df ( ( nonce || entropy_bitstring ), n )
 193          *     5.5.  entropy_total = entropy_total + assessed_entropy
 194          *
 195          * (The implementation of these steps is inside the function
 196          * get_entropy_input_tmp().)
 197          */
 198         linker_assert ( __builtin_constant_p ( tmp_len ),
 199                         tmp_len_not_constant );
 200         linker_assert ( ( n == ( 8 * tmp_len ) ), tmp_len_mismatch );
 201         if ( ( rc = get_entropy_input_tmp ( num_samples, tmp, tmp_len ) ) != 0 )
 202                 return rc;
 203
 204         /* 6.  If ( n < min_length ), then tmp = tmp || 0^(min_length-n)
 205          * 7.  If ( n > max_length ), then tmp = df ( tmp, max_length )
 206          * 8.  Return ( SUCCESS, tmp )
 207          */
 208         if ( tmp_len < min_len ) {
 209                 /* (Data is already in-place.) */
 210                 linker_assert ( ( data == tmp ), data_not_inplace );
 211                 memset ( ( data + tmp_len ), 0, ( min_len - tmp_len ) );
 212                 return min_len;
 213         } else if ( tmp_len > max_len ) {
 214                 linker_assert ( ( tmp == tmp_buf ), data_inplace );
 215                 hash_df ( &entropy_hash_df_algorithm, tmp, tmp_len,
 216                           data, max_len );
 217                 return max_len;
 218         } else {
 219                 /* (Data is already in-place.) */
 220                 linker_assert ( ( data == tmp ), data_not_inplace );
 221                 return tmp_len;
 222         }
 223 }
 224
 225 #endif /* _IPXE_ENTROPY_H */