1 #ifndef _IPXE_ENTROPY_H
2 #define _IPXE_ENTROPY_H
10 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL
);
16 #include <ipxe/hash_df.h>
17 #include <ipxe/sha256.h>
18 #include <config/entropy.h>
21 * Calculate static inline entropy API function name
23 * @v _prefix Subsystem prefix
24 * @v _api_func API function
25 * @ret _subsys_func Subsystem API function
27 #define ENTROPY_INLINE( _subsys, _api_func ) \
28 SINGLE_API_INLINE ( ENTROPY_PREFIX_ ## _subsys, _api_func )
31 * Provide a entropy API implementation
33 * @v _prefix Subsystem prefix
34 * @v _api_func API function
35 * @v _func Implementing function
37 #define PROVIDE_ENTROPY( _subsys, _api_func, _func ) \
38 PROVIDE_SINGLE_API ( ENTROPY_PREFIX_ ## _subsys, _api_func, _func )
41 * Provide a static inline entropy API implementation
43 * @v _prefix Subsystem prefix
44 * @v _api_func API function
46 #define PROVIDE_ENTROPY_INLINE( _subsys, _api_func ) \
47 PROVIDE_SINGLE_API_INLINE ( ENTROPY_PREFIX_ ## _subsys, _api_func )
50 typedef uint8_t noise_sample_t
;
52 /** An entropy sample */
53 typedef uint8_t entropy_sample_t
;
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>
60 /* Include all architecture-dependent entropy API headers */
61 #include <bits/entropy.h>
64 * Enable entropy gathering
66 * @ret rc Return status code
68 int entropy_enable ( void );
71 * Disable entropy gathering
74 void entropy_disable ( void );
77 * min-entropy per sample
79 * @ret min_entropy min-entropy of each sample
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
84 * H_min = -log2 ( p_max )
86 * where p_max is the probability of the most likely sample value.
88 * This must be a compile-time constant.
90 double min_entropy_per_sample ( void );
95 * @ret noise Noise sample
96 * @ret rc Return status code
98 * This is the GetNoise function defined in ANS X9.82 Part 2
99 * (October 2011 Draft) Section 6.5.2.
101 int get_noise ( noise_sample_t
*noise
);
103 extern int get_entropy_input_tmp ( unsigned int num_samples
,
104 uint8_t *tmp
, size_t tmp_len
);
106 /** Use SHA-256 as the underlying hash algorithm for Hash_df
108 * Hash_df using SHA-256 is an Approved algorithm in ANS X9.82.
110 #define entropy_hash_df_algorithm sha256_algorithm
112 /** Underlying hash algorithm output length (in bytes) */
113 #define ENTROPY_HASH_DF_OUTLEN_BYTES SHA256_DIGEST_SIZE
116 * Obtain entropy input
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
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.
129 * To minimise code size, the number of samples required is calculated
130 * at compilation time.
132 static inline __attribute__ (( always_inline
)) int
133 get_entropy_input ( unsigned int min_entropy_bits
, void *data
, size_t min_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
);
139 unsigned int num_samples
;
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
);
150 /* Round up minimum entropy to an integral number of bytes */
151 min_entropy_bits
= ( ( min_entropy_bits
+ 7 ) & ~7 );
153 /* Calculate number of samples required to contain sufficient entropy */
154 min_samples
= ( ( min_entropy_bits
* 1.0 ) / min_entropy_per_sample() );
156 /* Round up to a whole number of samples. We don't have the
157 * ceil() function available, so do the rounding by hand.
159 num_samples
= min_samples
;
160 if ( num_samples
< min_samples
)
162 linker_assert ( ( num_samples
>= min_samples
), rounding_error
);
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
169 linker_assert ( __builtin_constant_p ( num_samples
),
170 num_samples_not_constant
);
172 /* (Unnumbered). The output length of the hash function shall
173 * meet or exceed the security strength indicated by the
174 * min_entropy parameter.
176 linker_assert ( ( ( 8 * ENTROPY_HASH_DF_OUTLEN_BYTES
) >=
177 min_entropy_bits
), hash_df_algorithm_too_weak
);
179 /* 1. If ( min_length > max_length ), then return ( FAILURE, Null ) */
180 linker_assert ( ( min_len
<= max_len
), min_len_greater_than_max_len
);
182 /* 2. n = 2 * min_entropy */
183 n
= ( 2 * min_entropy_bits
);
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 )
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
195 * (The implementation of these steps is inside the function
196 * get_entropy_input_tmp().)
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 )
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 )
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
) );
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
,
219 /* (Data is already in-place.) */
220 linker_assert ( ( data
== tmp
), data_not_inplace
);
225 #endif /* _IPXE_ENTROPY_H */