1 #ifndef _IPXE_HMAC_DRBG_H
2 #define _IPXE_HMAC_DRBG_H
10 FILE_LICENCE ( GPL2_OR_LATER );
13 #include <ipxe/crypto.h>
15 /** Declare an HMAC_DRBG algorithm
17 * @v hash Underlying hash algorithm
18 * @v max_security_strength Maxmimum security strength
19 * @v out_len_bits Output block length, in bits
20 * @ret hmac_drbg HMAC_DRBG algorithm
22 #define HMAC_DRBG( hash, max_security_strength, out_len_bits ) \
23 ( hash, max_security_strength, out_len_bits )
25 /** HMAC_DRBG using SHA-1
27 * The maximum security strength of HMAC_DRBG using SHA-1 is 128 bits
28 * according to the list of maximum security strengths documented in
29 * NIST SP 800-57 Part 1 Section 5.6.1 Table 3.
31 * The output block length of HMAC_DRBG using SHA-1 is 160 bits
32 * according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 2 (NIST SP
33 * 800-90 Section 10.1 Table 2).
35 #define HMAC_DRBG_SHA1 HMAC_DRBG ( &sha1_algorithm, 128, 160 )
37 /** HMAC_DRBG using SHA-224
39 * The maximum security strength of HMAC_DRBG using SHA-224 is 192
40 * bits according to the list of maximum security strengths documented
41 * in NIST SP 800-57 Part 1 Section 5.6.1 Table 3.
43 * The output block length of HMAC_DRBG using SHA-224 is 224 bits
44 * according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 2 (NIST SP
45 * 800-90 Section 10.1 Table 2).
47 #define HMAC_DRBG_SHA224 HMAC_DRBG ( &sha224_algorithm, 192, 224 )
49 /** HMAC_DRBG using SHA-256
51 * The maximum security strength of HMAC_DRBG using SHA-256 is 256
52 * bits according to the list of maximum security strengths documented
53 * in NIST SP 800-57 Part 1 Section 5.6.1 Table 3.
55 * The output block length of HMAC_DRBG using SHA-256 is 256 bits
56 * according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 2 (NIST SP
57 * 800-90 Section 10.1 Table 2).
59 #define HMAC_DRBG_SHA256 HMAC_DRBG ( &sha256_algorithm, 256, 256 )
61 /** HMAC_DRBG using SHA-384
63 * The maximum security strength of HMAC_DRBG using SHA-384 is 256
64 * bits according to the list of maximum security strengths documented
65 * in NIST SP 800-57 Part 1 Section 5.6.1 Table 3.
67 * The output block length of HMAC_DRBG using SHA-384 is 384 bits
68 * according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 2 (NIST SP
69 * 800-90 Section 10.1 Table 2).
71 #define HMAC_DRBG_SHA384 HMAC_DRBG ( &sha384_algorithm, 256, 384 )
73 /** HMAC_DRBG using SHA-512
75 * The maximum security strength of HMAC_DRBG using SHA-512 is 256
76 * bits according to the list of maximum security strengths documented
77 * in NIST SP 800-57 Part 1 Section 5.6.1 Table 3.
79 * The output block length of HMAC_DRBG using SHA-512 is 512 bits
80 * according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 2 (NIST SP
81 * 800-90 Section 10.1 Table 2).
83 #define HMAC_DRBG_SHA512 HMAC_DRBG ( &sha512_algorithm, 256, 512 )
85 /** Underlying hash algorithm
87 * @v hmac_drbg HMAC_DRBG algorithm
88 * @ret hash Underlying hash algorithm
90 #define HMAC_DRBG_HASH( hmac_drbg ) \
91 HMAC_DRBG_EXTRACT_HASH hmac_drbg
92 #define HMAC_DRBG_EXTRACT_HASH( hash, max_security_strength, out_len_bits ) \
95 /** Maximum security strength
97 * @v hmac_drbg HMAC_DRBG algorithm
98 * @ret max_security_strength Maxmimum security strength
100 #define HMAC_DRBG_MAX_SECURITY_STRENGTH( hmac_drbg ) \
101 HMAC_DRBG_EXTRACT_MAX_SECURITY_STRENGTH hmac_drbg
102 #define HMAC_DRBG_EXTRACT_MAX_SECURITY_STRENGTH( hash, max_security_strength, \
104 max_security_strength
106 /** Output block length, in bits
108 * @v hmac_drbg HMAC_DRBG algorithm
109 * @ret out_len_bits Output block length, in bits
111 #define HMAC_DRBG_OUTLEN_BITS( hmac_drbg ) \
112 HMAC_DRBG_EXTRACT_OUTLEN_BITS hmac_drbg
113 #define HMAC_DRBG_EXTRACT_OUTLEN_BITS( hash, max_security_strength, \
117 /** Output block length, in bytes
119 * @v hmac_drbg HMAC_DRBG algorithm
120 * @ret out_len_bytes Output block length, in bytes
122 #define HMAC_DRBG_OUTLEN_BYTES( hmac_drbg ) \
123 ( HMAC_DRBG_OUTLEN_BITS ( hmac_drbg ) / 8 )
125 /** Maximum output block length, in bytes
127 * The maximum output block length for HMAC_DRBG is 512 bits for
128 * SHA-512 according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 2
129 * (NIST SP 800-90 Section 10.1 Table 2).
131 #define HMAC_DRBG_MAX_OUTLEN_BYTES HMAC_DRBG_OUTLEN_BYTES ( HMAC_DRBG_SHA512 )
133 /** Required minimum entropy for instantiate and reseed
135 * @v security_strength Security strength
136 * @ret min_entropy Required minimum entropy
138 * The minimum required entropy for HMAC_DRBG is equal to the security
139 * strength according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 2
140 * (NIST SP 800-90 Section 10.1 Table 2).
142 #define HMAC_DRBG_MIN_ENTROPY( security_strength ) (security_strength)
144 /** Minimum entropy input length
146 * @v security_strength Security strength
147 * @ret min_entropy_len_bytes Required minimum entropy length (in bytes)
149 * The minimum entropy input length for HMAC_DRBG is equal to the
150 * security strength according to ANS X9.82 Part 3-2007 Section 10.2.1
151 * Table 2 (NIST SP 800-90 Section 10.1 Table 2).
153 #define HMAC_DRBG_MIN_ENTROPY_LEN_BYTES( security_strength ) \
154 ( (security_strength) / 8 )
156 /** Maximum entropy input length
158 * The maximum entropy input length for HMAC_DRBG is 2^35 bits
159 * according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 2 (NIST SP
160 * 800-90 Section 10.1 Table 2).
162 * We choose to allow up to 32 bytes.
164 #define HMAC_DRBG_MAX_ENTROPY_LEN_BYTES 32
166 /** Maximum personalisation string length
168 * The maximum permitted personalisation string length for HMAC_DRBG
169 * is 2^35 bits according to ANS X9.82 Part 3-2007 Section 10.2.1
170 * Table 1 (NIST SP 800-90 Section 10.1 Table 2).
172 * We choose to allow up to 2^32-1 bytes (i.e. 2^35-8 bits).
174 #define HMAC_DRBG_MAX_PERSONAL_LEN_BYTES 0xffffffffUL
176 /** Maximum additional input length
178 * The maximum permitted additional input length for HMAC_DRBG is 2^35
179 * bits according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 1
180 * (NIST SP 800-90 Section 10.1 Table 2).
182 * We choose to allow up to 2^32-1 bytes (i.e. 2^35-8 bits).
184 #define HMAC_DRBG_MAX_ADDITIONAL_LEN_BYTES 0xffffffffUL
186 /** Maximum length of generated pseudorandom data per request
188 * The maximum number of bits per request for HMAC_DRBG is 2^19 bits
189 * according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 1 (NIST SP
190 * 800-90 Section 10.1 Table 2).
192 * We choose to allow up to 2^16-1 bytes (i.e. 2^19-8 bits).
194 #define HMAC_DRBG_MAX_GENERATED_LEN_BYTES 0x0000ffffUL
198 * The maximum permitted reseed interval for HMAC_DRBG is 2^48
199 * according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 2 (NIST SP
200 * 800-90 Section 10.1 Table 2). However, the sample implementation
201 * given in ANS X9.82 Part 3-2007 Annex E.2.1 (NIST SP 800-90 Appendix
202 * F.2) shows a reseed interval of 10000.
204 * We choose a very conservative reseed interval.
206 #define HMAC_DRBG_RESEED_INTERVAL 1024
209 * HMAC_DRBG internal state
211 * This structure is defined by ANS X9.82 Part 3-2007 Section
212 * 10.2.2.2.1 (NIST SP 800-90 Section 10.1.2.1).
214 * The "administrative information" portions (security_strength and
215 * prediction_resistance) are design-time constants and so are not
216 * present as fields in this structure.
218 struct hmac_drbg_state {
221 * "The value V of outlen bits, which is updated each time
222 * another outlen bits of output are produced"
224 uint8_t value[HMAC_DRBG_MAX_OUTLEN_BYTES];
227 * "The outlen-bit Key, which is updated at least once each
228 * time that the DRBG mechanism generates pseudorandom bits."
230 uint8_t key[HMAC_DRBG_MAX_OUTLEN_BYTES];
233 * "A counter (reseed_counter) that indicates the number of
234 * requests for pseudorandom bits since instantiation or
237 unsigned int reseed_counter;
240 extern void hmac_drbg_instantiate ( struct digest_algorithm *hash,
241 struct hmac_drbg_state *state,
242 const void *entropy, size_t entropy_len,
243 const void *personal, size_t personal_len );
244 extern void hmac_drbg_reseed ( struct digest_algorithm *hash,
245 struct hmac_drbg_state *state,
246 const void *entropy, size_t entropy_len,
247 const void *additional, size_t additional_len );
248 extern int hmac_drbg_generate ( struct digest_algorithm *hash,
249 struct hmac_drbg_state *state,
250 const void *additional, size_t additional_len,
251 void *data, size_t len );
253 #endif /* _IPXE_HMAC_DRBG_H */