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 */ 218 struct hmac_drbg_state { 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 */ 224 uint8_t value[HMAC_DRBG_MAX_OUTLEN_BYTES]; 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 */ 230 uint8_t key[HMAC_DRBG_MAX_OUTLEN_BYTES]; 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 */ 254