iPXE
entropy.h
Go to the documentation of this file.
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 */
51 
52 /** An entropy sample */
54 
55 /** An amount of min-entropy
56  *
57  * Expressed as a fixed-point quantity in order to avoid floating
58  * point calculations.
59  */
60 typedef unsigned int min_entropy_t;
61 
62 /** Fixed-point scale for min-entropy amounts */
63 #define MIN_ENTROPY_SCALE ( 1 << 16 )
64 
65 /**
66  * Construct a min-entropy fixed-point value
67  *
68  * @v bits min-entropy in bits
69  * @ret min_entropy min-entropy as a fixed-point value
70  */
71 #define MIN_ENTROPY( bits ) \
72  ( ( min_entropy_t ) ( (bits) * MIN_ENTROPY_SCALE ) )
73 
74 /* Include all architecture-independent entropy API headers */
75 #include <ipxe/null_entropy.h>
76 #include <ipxe/efi/efi_entropy.h>
78 
79 /* Include all architecture-dependent entropy API headers */
80 #include <bits/entropy.h>
81 
82 /**
83  * Enable entropy gathering
84  *
85  * @ret rc Return status code
86  */
87 int entropy_enable ( void );
88 
89 /**
90  * Disable entropy gathering
91  *
92  */
93 void entropy_disable ( void );
94 
95 /**
96  * min-entropy per sample
97  *
98  * @ret min_entropy min-entropy of each sample
99  *
100  * min-entropy is defined in ANS X9.82 Part 1-2006 Section 8.3 and in
101  * NIST SP 800-90 Appendix C.3 as
102  *
103  * H_min = -log2 ( p_max )
104  *
105  * where p_max is the probability of the most likely sample value.
106  *
107  * This must be a compile-time constant.
108  */
110 
111 /**
112  * Get noise sample
113  *
114  * @ret noise Noise sample
115  * @ret rc Return status code
116  *
117  * This is the GetNoise function defined in ANS X9.82 Part 2
118  * (October 2011 Draft) Section 6.5.2.
119  */
120 int get_noise ( noise_sample_t *noise );
121 
122 extern int get_entropy_input_tmp ( unsigned int num_samples,
123  uint8_t *tmp, size_t tmp_len );
124 
125 /** Use SHA-256 as the underlying hash algorithm for Hash_df
126  *
127  * Hash_df using SHA-256 is an Approved algorithm in ANS X9.82.
128  */
129 #define entropy_hash_df_algorithm sha256_algorithm
130 
131 /** Underlying hash algorithm output length (in bytes) */
132 #define ENTROPY_HASH_DF_OUTLEN_BYTES SHA256_DIGEST_SIZE
133 
134 /**
135  * Obtain entropy input
136  *
137  * @v min_entropy_bits Minimum amount of entropy, in bits
138  * @v data Data buffer
139  * @v min_len Minimum length of entropy input, in bytes
140  * @v max_len Maximum length of entropy input, in bytes
141  * @ret len Length of entropy input, in bytes, or negative error
142  *
143  * This is the implementation of the Get_entropy_input function (using
144  * an entropy source as the source of entropy input and condensing
145  * each entropy source output after each GetEntropy call) as defined
146  * in ANS X9.82 Part 4 (April 2011 Draft) Section 13.3.4.2.
147  *
148  * To minimise code size, the number of samples required is calculated
149  * at compilation time.
150  */
151 static inline __attribute__ (( always_inline )) int
152 get_entropy_input ( unsigned int min_entropy_bits, void *data, size_t min_len,
153  size_t max_len ) {
154  size_t tmp_len = ( ( ( min_entropy_bits * 2 ) + 7 ) / 8 );
156  uint8_t *tmp = ( ( tmp_len > max_len ) ? tmp_buf : data );
157  double min_samples;
158  unsigned int num_samples;
159  unsigned int n;
160  int rc;
161 
162  /* Sanity checks */
164  MIN_ENTROPY ( 8 * sizeof ( noise_sample_t ) ) ),
165  min_entropy_per_sample_is_impossibly_high );
166  linker_assert ( ( min_entropy_bits <= ( 8 * max_len ) ),
167  entropy_buffer_too_small );
168 
169  /* Round up minimum entropy to an integral number of bytes */
170  min_entropy_bits = ( ( min_entropy_bits + 7 ) & ~7 );
171 
172  /* Calculate number of samples required to contain sufficient entropy */
175 
176  /* Round up to a whole number of samples. We don't have the
177  * ceil() function available, so do the rounding by hand.
178  */
180  if ( num_samples < min_samples )
181  num_samples++;
182  linker_assert ( ( num_samples >= min_samples ), rounding_error );
183 
184  /* Floating-point operations are not allowed in iPXE since we
185  * never set up a suitable environment. Abort the build
186  * unless the calculated number of samples is a compile-time
187  * constant.
188  */
189  linker_assert ( __builtin_constant_p ( num_samples ),
190  num_samples_not_constant );
191 
192  /* (Unnumbered). The output length of the hash function shall
193  * meet or exceed the security strength indicated by the
194  * min_entropy parameter.
195  */
197  min_entropy_bits ), hash_df_algorithm_too_weak );
198 
199  /* 1. If ( min_length > max_length ), then return ( FAILURE, Null ) */
200  linker_assert ( ( min_len <= max_len ), min_len_greater_than_max_len );
201 
202  /* 2. n = 2 * min_entropy */
203  n = ( 2 * min_entropy_bits );
204 
205  /* 3. entropy_total = 0
206  * 4. tmp = a fixed n-bit value, such as 0^n
207  * 5. While ( entropy_total < min_entropy )
208  * 5.1. ( status, entropy_bitstring, assessed_entropy )
209  * = GetEntropy()
210  * 5.2. If status indicates an error, return ( status, Null )
211  * 5.3. nonce = MakeNextNonce()
212  * 5.4. tmp = tmp XOR df ( ( nonce || entropy_bitstring ), n )
213  * 5.5. entropy_total = entropy_total + assessed_entropy
214  *
215  * (The implementation of these steps is inside the function
216  * get_entropy_input_tmp().)
217  */
218  linker_assert ( __builtin_constant_p ( tmp_len ),
219  tmp_len_not_constant );
220  linker_assert ( ( n == ( 8 * tmp_len ) ), tmp_len_mismatch );
221  if ( ( rc = get_entropy_input_tmp ( num_samples, tmp, tmp_len ) ) != 0 )
222  return rc;
223 
224  /* 6. If ( n < min_length ), then tmp = tmp || 0^(min_length-n)
225  * 7. If ( n > max_length ), then tmp = df ( tmp, max_length )
226  * 8. Return ( SUCCESS, tmp )
227  */
228  if ( tmp_len < min_len ) {
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 ) {
234  linker_assert ( ( tmp == tmp_buf ), data_inplace );
236  data, max_len );
237  return max_len;
238  } else {
239  /* (Data is already in-place.) */
240  linker_assert ( ( data == tmp ), data_not_inplace );
241  return tmp_len;
242  }
243 }
244 
245 #endif /* _IPXE_ENTROPY_H */
void entropy_disable(void)
Disable entropy gathering.
int rc
Definition: entropy.h:160
iPXE internal APIs
return tmp_len
Definition: entropy.h:241
static void size_t size_t max_len
Definition: entropy.h:153
int get_entropy_input_tmp(unsigned int num_samples, uint8_t *tmp, size_t tmp_len)
Obtain entropy input temporary buffer.
Definition: entropy.c:419
min_entropy_t min_entropy_per_sample(void)
min-entropy per sample
unsigned int num_samples
Definition: entropy.h:158
int get_noise(noise_sample_t *noise)
Get noise sample.
Hash-based derivation function (Hash_df)
x86-specific entropy API implementations
min_entropy_bits
Definition: entropy.h:170
/dev/random-based entropy source
Entropy API configuration.
Assertions.
Nonexistent entropy source.
static __attribute__((always_inline)) int get_entropy_input(unsigned int min_entropy_bits
Obtain entropy input.
static void size_t min_len
Definition: entropy.h:152
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)
#define ENTROPY_HASH_DF_OUTLEN_BYTES
Underlying hash algorithm output length (in bytes)
Definition: entropy.h:132
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
EFI entropy source.
unsigned char uint8_t
Definition: stdint.h:10
#define MIN_ENTROPY(bits)
Construct a min-entropy fixed-point value.
Definition: entropy.h:71
unsigned int min_entropy_t
An amount of min-entropy.
Definition: entropy.h:60
uint8_t entropy_sample_t
An entropy sample.
Definition: entropy.h:53
FILE_LICENCE(GPL2_OR_LATER_OR_UBDL)
uint8_t noise_sample_t
A noise sample.
Definition: entropy.h:50
#define entropy_hash_df_algorithm
Use SHA-256 as the underlying hash algorithm for Hash_df.
Definition: entropy.h:129
double min_samples
Definition: entropy.h:157
unsigned int n
Definition: entropy.h:159
SHA-256 algorithm.
static void * data
Definition: entropy.h:152
String functions.
void * memset(void *dest, int character, size_t len) __nonnull