qemu/roms/ipxe/src/include/ipxe/hmac_drbg.h

   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 );
  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 */