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 /** 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>
77 #include <ipxe/linux/linux_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 */
109 min_entropy_t min_entropy_per_sample ( void );
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
get_entropy_input(unsigned int min_entropy_bits,void * data,size_t min_len,size_t max_len)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 );
155 uint8_t tmp_buf[ tmp_len ];
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 */
163 linker_assert ( ( min_entropy_per_sample() <=
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 */
173 min_samples = ( MIN_ENTROPY ( min_entropy_bits ) /
174 min_entropy_per_sample() );
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 */
179 num_samples = min_samples;
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 */
196 linker_assert ( ( ( 8 * ENTROPY_HASH_DF_OUTLEN_BYTES ) >=
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 );
235 hash_df ( &entropy_hash_df_algorithm, tmp, tmp_len,
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 */
246