iPXE
hmac_drbg.h
Go to the documentation of this file.
1 #ifndef _IPXE_HMAC_DRBG_H
2 #define _IPXE_HMAC_DRBG_H
3 
4 /** @file
5  *
6  * HMAC_DRBG algorithm
7  *
8  */
9 
10 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
11 
12 #include <stdint.h>
13 #include <ipxe/crypto.h>
14 
15 /** Declare an HMAC_DRBG algorithm
16  *
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
21  */
22 #define HMAC_DRBG( hash, max_security_strength, out_len_bits ) \
23  ( hash, max_security_strength, out_len_bits )
24 
25 /** HMAC_DRBG using SHA-1
26  *
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.
30  *
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).
34  */
35 #define HMAC_DRBG_SHA1 HMAC_DRBG ( &sha1_algorithm, 128, 160 )
36 
37 /** HMAC_DRBG using SHA-224
38  *
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.
42  *
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).
46  */
47 #define HMAC_DRBG_SHA224 HMAC_DRBG ( &sha224_algorithm, 192, 224 )
48 
49 /** HMAC_DRBG using SHA-256
50  *
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.
54  *
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).
58  */
59 #define HMAC_DRBG_SHA256 HMAC_DRBG ( &sha256_algorithm, 256, 256 )
60 
61 /** HMAC_DRBG using SHA-384
62  *
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.
66  *
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).
70  */
71 #define HMAC_DRBG_SHA384 HMAC_DRBG ( &sha384_algorithm, 256, 384 )
72 
73 /** HMAC_DRBG using SHA-512
74  *
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.
78  *
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).
82  */
83 #define HMAC_DRBG_SHA512 HMAC_DRBG ( &sha512_algorithm, 256, 512 )
84 
85 /** Underlying hash algorithm
86  *
87  * @v hmac_drbg HMAC_DRBG algorithm
88  * @ret hash Underlying hash algorithm
89  */
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 ) \
93  hash
94 
95 /** Maximum security strength
96  *
97  * @v hmac_drbg HMAC_DRBG algorithm
98  * @ret max_security_strength Maxmimum security strength
99  */
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, \
103  out_len_bits ) \
104  max_security_strength
105 
106 /** Output block length, in bits
107  *
108  * @v hmac_drbg HMAC_DRBG algorithm
109  * @ret out_len_bits Output block length, in bits
110  */
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, \
114  out_len_bits ) \
115  out_len_bits
116 
117 /** Output block length, in bytes
118  *
119  * @v hmac_drbg HMAC_DRBG algorithm
120  * @ret out_len_bytes Output block length, in bytes
121  */
122 #define HMAC_DRBG_OUTLEN_BYTES( hmac_drbg ) \
123  ( HMAC_DRBG_OUTLEN_BITS ( hmac_drbg ) / 8 )
124 
125 /** Maximum output block length, in bytes
126  *
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).
130  */
131 #define HMAC_DRBG_MAX_OUTLEN_BYTES HMAC_DRBG_OUTLEN_BYTES ( HMAC_DRBG_SHA512 )
132 
133 /** Required minimum entropy for instantiate and reseed
134  *
135  * @v security_strength Security strength
136  * @ret min_entropy Required minimum entropy
137  *
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).
141  */
142 #define HMAC_DRBG_MIN_ENTROPY( security_strength ) (security_strength)
143 
144 /** Minimum entropy input length
145  *
146  * @v security_strength Security strength
147  * @ret min_entropy_len_bytes Required minimum entropy length (in bytes)
148  *
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).
152  */
153 #define HMAC_DRBG_MIN_ENTROPY_LEN_BYTES( security_strength ) \
154  ( (security_strength) / 8 )
155 
156 /** Maximum entropy input length
157  *
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).
161  *
162  * We choose to allow up to 32 bytes.
163  */
164 #define HMAC_DRBG_MAX_ENTROPY_LEN_BYTES 32
165 
166 /** Maximum personalisation string length
167  *
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).
171  *
172  * We choose to allow up to 2^32-1 bytes (i.e. 2^35-8 bits).
173  */
174 #define HMAC_DRBG_MAX_PERSONAL_LEN_BYTES 0xffffffffUL
175 
176 /** Maximum additional input length
177  *
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).
181  *
182  * We choose to allow up to 2^32-1 bytes (i.e. 2^35-8 bits).
183  */
184 #define HMAC_DRBG_MAX_ADDITIONAL_LEN_BYTES 0xffffffffUL
185 
186 /** Maximum length of generated pseudorandom data per request
187  *
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).
191  *
192  * We choose to allow up to 2^16-1 bytes (i.e. 2^19-8 bits).
193  */
194 #define HMAC_DRBG_MAX_GENERATED_LEN_BYTES 0x0000ffffUL
195 
196 /** Reseed interval
197  *
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.
203  *
204  * We choose a very conservative reseed interval.
205  */
206 #define HMAC_DRBG_RESEED_INTERVAL 1024
207 
208 /**
209  * HMAC_DRBG internal state
210  *
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).
213  *
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.
217  */
219  /** Current value
220  *
221  * "The value V of outlen bits, which is updated each time
222  * another outlen bits of output are produced"
223  */
225  /** Current key
226  *
227  * "The outlen-bit Key, which is updated at least once each
228  * time that the DRBG mechanism generates pseudorandom bits."
229  */
231  /** Reseed counter
232  *
233  * "A counter (reseed_counter) that indicates the number of
234  * requests for pseudorandom bits since instantiation or
235  * reseeding"
236  */
237  unsigned int reseed_counter;
238 };
239 
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 );
252 
253 #endif /* _IPXE_HMAC_DRBG_H */
uint8_t state
State.
Definition: eth_slow.h:47
#define HMAC_DRBG_MAX_OUTLEN_BYTES
Maximum output block length, in bytes.
Definition: hmac_drbg.h:131
unsigned int reseed_counter
Reseed counter.
Definition: hmac_drbg.h:237
Cryptographic API.
void hmac_drbg_reseed(struct digest_algorithm *hash, struct hmac_drbg_state *state, const void *entropy, size_t entropy_len, const void *additional, size_t additional_len)
Reseed HMAC_DRBG.
Definition: hmac_drbg.c:259
uint16_t additional
Additional sense code and qualifier.
Definition: scsi.h:28
pseudo_bit_t hash[0x00010]
Hash algorithm.
Definition: arbel.h:13
FILE_LICENCE(GPL2_OR_LATER_OR_UBDL)
unsigned char uint8_t
Definition: stdint.h:10
uint8_t value[HMAC_DRBG_MAX_OUTLEN_BYTES]
Current value.
Definition: hmac_drbg.h:224
uint8_t key[HMAC_DRBG_MAX_OUTLEN_BYTES]
Current key.
Definition: hmac_drbg.h:230
HMAC_DRBG internal state.
Definition: hmac_drbg.h:218
void hmac_drbg_instantiate(struct digest_algorithm *hash, struct hmac_drbg_state *state, const void *entropy, size_t entropy_len, const void *personal, size_t personal_len)
Instantiate HMAC_DRBG.
Definition: hmac_drbg.c:210
uint32_t len
Length.
Definition: ena.h:14
A message digest algorithm.
Definition: crypto.h:16
int hmac_drbg_generate(struct digest_algorithm *hash, struct hmac_drbg_state *state, const void *additional, size_t additional_len, void *data, size_t len)
Generate pseudorandom bits using HMAC_DRBG.
Definition: hmac_drbg.c:310
struct arbelprm_port_state_change_st data
Message.
Definition: arbel.h:12