iPXE
entropy.h
Go to the documentation of this file.
00001 #ifndef _IPXE_ENTROPY_H
00002 #define _IPXE_ENTROPY_H
00003 
00004 /** @file
00005  *
00006  * Entropy source
00007  *
00008  */
00009 
00010 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
00011 
00012 #include <stdint.h>
00013 #include <string.h>
00014 #include <assert.h>
00015 #include <ipxe/api.h>
00016 #include <ipxe/hash_df.h>
00017 #include <ipxe/sha256.h>
00018 #include <config/entropy.h>
00019 
00020 /**
00021  * Calculate static inline entropy API function name
00022  *
00023  * @v _prefix           Subsystem prefix
00024  * @v _api_func         API function
00025  * @ret _subsys_func    Subsystem API function
00026  */
00027 #define ENTROPY_INLINE( _subsys, _api_func ) \
00028         SINGLE_API_INLINE ( ENTROPY_PREFIX_ ## _subsys, _api_func )
00029 
00030 /**
00031  * Provide a entropy API implementation
00032  *
00033  * @v _prefix           Subsystem prefix
00034  * @v _api_func         API function
00035  * @v _func             Implementing function
00036  */
00037 #define PROVIDE_ENTROPY( _subsys, _api_func, _func ) \
00038         PROVIDE_SINGLE_API ( ENTROPY_PREFIX_ ## _subsys, _api_func, _func )
00039 
00040 /**
00041  * Provide a static inline entropy API implementation
00042  *
00043  * @v _prefix           Subsystem prefix
00044  * @v _api_func         API function
00045  */
00046 #define PROVIDE_ENTROPY_INLINE( _subsys, _api_func ) \
00047         PROVIDE_SINGLE_API_INLINE ( ENTROPY_PREFIX_ ## _subsys, _api_func )
00048 
00049 /** A noise sample */
00050 typedef uint8_t noise_sample_t;
00051 
00052 /** An entropy sample */
00053 typedef uint8_t entropy_sample_t;
00054 
00055 /** An amount of min-entropy
00056  *
00057  * Expressed as a fixed-point quantity in order to avoid floating
00058  * point calculations.
00059  */
00060 typedef unsigned int min_entropy_t;
00061 
00062 /** Fixed-point scale for min-entropy amounts */
00063 #define MIN_ENTROPY_SCALE ( 1 << 16 )
00064 
00065 /**
00066  * Construct a min-entropy fixed-point value
00067  *
00068  * @v bits              min-entropy in bits
00069  * @ret min_entropy     min-entropy as a fixed-point value
00070  */
00071 #define MIN_ENTROPY( bits ) \
00072         ( ( min_entropy_t ) ( (bits) * MIN_ENTROPY_SCALE ) )
00073 
00074 /* Include all architecture-independent entropy API headers */
00075 #include <ipxe/null_entropy.h>
00076 #include <ipxe/efi/efi_entropy.h>
00077 #include <ipxe/linux/linux_entropy.h>
00078 
00079 /* Include all architecture-dependent entropy API headers */
00080 #include <bits/entropy.h>
00081 
00082 /**
00083  * Enable entropy gathering
00084  *
00085  * @ret rc              Return status code
00086  */
00087 int entropy_enable ( void );
00088 
00089 /**
00090  * Disable entropy gathering
00091  *
00092  */
00093 void entropy_disable ( void );
00094 
00095 /**
00096  * min-entropy per sample
00097  *
00098  * @ret min_entropy     min-entropy of each sample
00099  *
00100  * min-entropy is defined in ANS X9.82 Part 1-2006 Section 8.3 and in
00101  * NIST SP 800-90 Appendix C.3 as
00102  *
00103  *    H_min = -log2 ( p_max )
00104  *
00105  * where p_max is the probability of the most likely sample value.
00106  *
00107  * This must be a compile-time constant.
00108  */
00109 min_entropy_t min_entropy_per_sample ( void );
00110 
00111 /**
00112  * Get noise sample
00113  *
00114  * @ret noise           Noise sample
00115  * @ret rc              Return status code
00116  *
00117  * This is the GetNoise function defined in ANS X9.82 Part 2
00118  * (October 2011 Draft) Section 6.5.2.
00119  */
00120 int get_noise ( noise_sample_t *noise );
00121 
00122 extern int get_entropy_input_tmp ( unsigned int num_samples,
00123                                    uint8_t *tmp, size_t tmp_len );
00124 
00125 /** Use SHA-256 as the underlying hash algorithm for Hash_df
00126  *
00127  * Hash_df using SHA-256 is an Approved algorithm in ANS X9.82.
00128  */
00129 #define entropy_hash_df_algorithm sha256_algorithm
00130 
00131 /** Underlying hash algorithm output length (in bytes) */
00132 #define ENTROPY_HASH_DF_OUTLEN_BYTES SHA256_DIGEST_SIZE
00133 
00134 /**
00135  * Obtain entropy input
00136  *
00137  * @v min_entropy_bits  Minimum amount of entropy, in bits
00138  * @v data              Data buffer
00139  * @v min_len           Minimum length of entropy input, in bytes
00140  * @v max_len           Maximum length of entropy input, in bytes
00141  * @ret len             Length of entropy input, in bytes, or negative error
00142  *
00143  * This is the implementation of the Get_entropy_input function (using
00144  * an entropy source as the source of entropy input and condensing
00145  * each entropy source output after each GetEntropy call) as defined
00146  * in ANS X9.82 Part 4 (April 2011 Draft) Section 13.3.4.2.
00147  *
00148  * To minimise code size, the number of samples required is calculated
00149  * at compilation time.
00150  */
00151 static inline __attribute__ (( always_inline )) int
00152 get_entropy_input ( unsigned int min_entropy_bits, void *data, size_t min_len,
00153                     size_t max_len ) {
00154         size_t tmp_len = ( ( ( min_entropy_bits * 2 ) + 7 ) / 8 );
00155         uint8_t tmp_buf[ tmp_len ];
00156         uint8_t *tmp = ( ( tmp_len > max_len ) ? tmp_buf : data );
00157         double min_samples;
00158         unsigned int num_samples;
00159         unsigned int n;
00160         int rc;
00161 
00162         /* Sanity checks */
00163         linker_assert ( ( min_entropy_per_sample() <=
00164                           MIN_ENTROPY ( 8 * sizeof ( noise_sample_t ) ) ),
00165                         min_entropy_per_sample_is_impossibly_high );
00166         linker_assert ( ( min_entropy_bits <= ( 8 * max_len ) ),
00167                         entropy_buffer_too_small );
00168 
00169         /* Round up minimum entropy to an integral number of bytes */
00170         min_entropy_bits = ( ( min_entropy_bits + 7 ) & ~7 );
00171 
00172         /* Calculate number of samples required to contain sufficient entropy */
00173         min_samples = ( MIN_ENTROPY ( min_entropy_bits ) /
00174                         min_entropy_per_sample() );
00175 
00176         /* Round up to a whole number of samples.  We don't have the
00177          * ceil() function available, so do the rounding by hand.
00178          */
00179         num_samples = min_samples;
00180         if ( num_samples < min_samples )
00181                 num_samples++;
00182         linker_assert ( ( num_samples >= min_samples ), rounding_error );
00183 
00184         /* Floating-point operations are not allowed in iPXE since we
00185          * never set up a suitable environment.  Abort the build
00186          * unless the calculated number of samples is a compile-time
00187          * constant.
00188          */
00189         linker_assert ( __builtin_constant_p ( num_samples ),
00190                         num_samples_not_constant );
00191 
00192         /* (Unnumbered).  The output length of the hash function shall
00193          * meet or exceed the security strength indicated by the
00194          * min_entropy parameter.
00195          */
00196         linker_assert ( ( ( 8 * ENTROPY_HASH_DF_OUTLEN_BYTES ) >=
00197                           min_entropy_bits ), hash_df_algorithm_too_weak );
00198 
00199         /* 1.  If ( min_length > max_length ), then return ( FAILURE, Null ) */
00200         linker_assert ( ( min_len <= max_len ), min_len_greater_than_max_len );
00201 
00202         /* 2.  n = 2 * min_entropy */
00203         n = ( 2 * min_entropy_bits );
00204 
00205         /* 3.  entropy_total = 0
00206          * 4.  tmp = a fixed n-bit value, such as 0^n
00207          * 5.  While ( entropy_total < min_entropy )
00208          *     5.1.  ( status, entropy_bitstring, assessed_entropy )
00209          *           = GetEntropy()
00210          *     5.2.  If status indicates an error, return ( status, Null )
00211          *     5.3.  nonce = MakeNextNonce()
00212          *     5.4.  tmp = tmp XOR df ( ( nonce || entropy_bitstring ), n )
00213          *     5.5.  entropy_total = entropy_total + assessed_entropy
00214          *
00215          * (The implementation of these steps is inside the function
00216          * get_entropy_input_tmp().)
00217          */
00218         linker_assert ( __builtin_constant_p ( tmp_len ),
00219                         tmp_len_not_constant );
00220         linker_assert ( ( n == ( 8 * tmp_len ) ), tmp_len_mismatch );
00221         if ( ( rc = get_entropy_input_tmp ( num_samples, tmp, tmp_len ) ) != 0 )
00222                 return rc;
00223 
00224         /* 6.  If ( n < min_length ), then tmp = tmp || 0^(min_length-n)
00225          * 7.  If ( n > max_length ), then tmp = df ( tmp, max_length )
00226          * 8.  Return ( SUCCESS, tmp )
00227          */
00228         if ( tmp_len < min_len ) {
00229                 /* (Data is already in-place.) */
00230                 linker_assert ( ( data == tmp ), data_not_inplace );
00231                 memset ( ( data + tmp_len ), 0, ( min_len - tmp_len ) );
00232                 return min_len;
00233         } else if ( tmp_len > max_len ) {
00234                 linker_assert ( ( tmp == tmp_buf ), data_inplace );
00235                 hash_df ( &entropy_hash_df_algorithm, tmp, tmp_len,
00236                           data, max_len );
00237                 return max_len;
00238         } else {
00239                 /* (Data is already in-place.) */
00240                 linker_assert ( ( data == tmp ), data_not_inplace );
00241                 return tmp_len;
00242         }
00243 }
00244 
00245 #endif /* _IPXE_ENTROPY_H */