iPXE
hmac_drbg.h
Go to the documentation of this file.
00001 #ifndef _IPXE_HMAC_DRBG_H
00002 #define _IPXE_HMAC_DRBG_H
00003 
00004 /** @file
00005  *
00006  * HMAC_DRBG algorithm
00007  *
00008  */
00009 
00010 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
00011 
00012 #include <stdint.h>
00013 #include <ipxe/crypto.h>
00014 
00015 /** Declare an HMAC_DRBG algorithm
00016  *
00017  * @v hash                      Underlying hash algorithm
00018  * @v max_security_strength     Maxmimum security strength
00019  * @v out_len_bits              Output block length, in bits
00020  * @ret hmac_drbg               HMAC_DRBG algorithm
00021  */
00022 #define HMAC_DRBG( hash, max_security_strength, out_len_bits ) \
00023         ( hash, max_security_strength, out_len_bits )
00024 
00025 /** HMAC_DRBG using SHA-1
00026  *
00027  * The maximum security strength of HMAC_DRBG using SHA-1 is 128 bits
00028  * according to the list of maximum security strengths documented in
00029  * NIST SP 800-57 Part 1 Section 5.6.1 Table 3.
00030  *
00031  * The output block length of HMAC_DRBG using SHA-1 is 160 bits
00032  * according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 2 (NIST SP
00033  * 800-90 Section 10.1 Table 2).
00034  */
00035 #define HMAC_DRBG_SHA1 HMAC_DRBG ( &sha1_algorithm, 128, 160 )
00036 
00037 /** HMAC_DRBG using SHA-224
00038  *
00039  * The maximum security strength of HMAC_DRBG using SHA-224 is 192
00040  * bits according to the list of maximum security strengths documented
00041  * in NIST SP 800-57 Part 1 Section 5.6.1 Table 3.
00042  *
00043  * The output block length of HMAC_DRBG using SHA-224 is 224 bits
00044  * according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 2 (NIST SP
00045  * 800-90 Section 10.1 Table 2).
00046  */
00047 #define HMAC_DRBG_SHA224 HMAC_DRBG ( &sha224_algorithm, 192, 224 )
00048 
00049 /** HMAC_DRBG using SHA-256
00050  *
00051  * The maximum security strength of HMAC_DRBG using SHA-256 is 256
00052  * bits according to the list of maximum security strengths documented
00053  * in NIST SP 800-57 Part 1 Section 5.6.1 Table 3.
00054  *
00055  * The output block length of HMAC_DRBG using SHA-256 is 256 bits
00056  * according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 2 (NIST SP
00057  * 800-90 Section 10.1 Table 2).
00058  */
00059 #define HMAC_DRBG_SHA256 HMAC_DRBG ( &sha256_algorithm, 256, 256 )
00060 
00061 /** HMAC_DRBG using SHA-384
00062  *
00063  * The maximum security strength of HMAC_DRBG using SHA-384 is 256
00064  * bits according to the list of maximum security strengths documented
00065  * in NIST SP 800-57 Part 1 Section 5.6.1 Table 3.
00066  *
00067  * The output block length of HMAC_DRBG using SHA-384 is 384 bits
00068  * according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 2 (NIST SP
00069  * 800-90 Section 10.1 Table 2).
00070  */
00071 #define HMAC_DRBG_SHA384 HMAC_DRBG ( &sha384_algorithm, 256, 384 )
00072 
00073 /** HMAC_DRBG using SHA-512
00074  *
00075  * The maximum security strength of HMAC_DRBG using SHA-512 is 256
00076  * bits according to the list of maximum security strengths documented
00077  * in NIST SP 800-57 Part 1 Section 5.6.1 Table 3.
00078  *
00079  * The output block length of HMAC_DRBG using SHA-512 is 512 bits
00080  * according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 2 (NIST SP
00081  * 800-90 Section 10.1 Table 2).
00082  */
00083 #define HMAC_DRBG_SHA512 HMAC_DRBG ( &sha512_algorithm, 256, 512 )
00084 
00085 /** Underlying hash algorithm
00086  *
00087  * @v hmac_drbg                 HMAC_DRBG algorithm
00088  * @ret hash                    Underlying hash algorithm
00089  */
00090 #define HMAC_DRBG_HASH( hmac_drbg ) \
00091         HMAC_DRBG_EXTRACT_HASH hmac_drbg
00092 #define HMAC_DRBG_EXTRACT_HASH( hash, max_security_strength, out_len_bits ) \
00093         hash
00094 
00095 /** Maximum security strength
00096  *
00097  * @v hmac_drbg                 HMAC_DRBG algorithm
00098  * @ret max_security_strength   Maxmimum security strength
00099  */
00100 #define HMAC_DRBG_MAX_SECURITY_STRENGTH( hmac_drbg ) \
00101         HMAC_DRBG_EXTRACT_MAX_SECURITY_STRENGTH hmac_drbg
00102 #define HMAC_DRBG_EXTRACT_MAX_SECURITY_STRENGTH( hash, max_security_strength, \
00103                                                  out_len_bits ) \
00104         max_security_strength
00105 
00106 /** Output block length, in bits
00107  *
00108  * @v hmac_drbg                 HMAC_DRBG algorithm
00109  * @ret out_len_bits            Output block length, in bits
00110  */
00111 #define HMAC_DRBG_OUTLEN_BITS( hmac_drbg ) \
00112         HMAC_DRBG_EXTRACT_OUTLEN_BITS hmac_drbg
00113 #define HMAC_DRBG_EXTRACT_OUTLEN_BITS( hash, max_security_strength, \
00114                                        out_len_bits ) \
00115         out_len_bits
00116 
00117 /** Output block length, in bytes
00118  *
00119  * @v hmac_drbg                 HMAC_DRBG algorithm
00120  * @ret out_len_bytes           Output block length, in bytes
00121  */
00122 #define HMAC_DRBG_OUTLEN_BYTES( hmac_drbg ) \
00123         ( HMAC_DRBG_OUTLEN_BITS ( hmac_drbg ) / 8 )
00124 
00125 /** Maximum output block length, in bytes
00126  *
00127  * The maximum output block length for HMAC_DRBG is 512 bits for
00128  * SHA-512 according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 2
00129  * (NIST SP 800-90 Section 10.1 Table 2).
00130  */
00131 #define HMAC_DRBG_MAX_OUTLEN_BYTES HMAC_DRBG_OUTLEN_BYTES ( HMAC_DRBG_SHA512 )
00132 
00133 /** Required minimum entropy for instantiate and reseed
00134  *
00135  * @v security_strength         Security strength
00136  * @ret min_entropy             Required minimum entropy
00137  *
00138  * The minimum required entropy for HMAC_DRBG is equal to the security
00139  * strength according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 2
00140  * (NIST SP 800-90 Section 10.1 Table 2).
00141  */
00142 #define HMAC_DRBG_MIN_ENTROPY( security_strength ) (security_strength)
00143 
00144 /** Minimum entropy input length
00145  *
00146  * @v security_strength         Security strength
00147  * @ret min_entropy_len_bytes   Required minimum entropy length (in bytes)
00148  *
00149  * The minimum entropy input length for HMAC_DRBG is equal to the
00150  * security strength according to ANS X9.82 Part 3-2007 Section 10.2.1
00151  * Table 2 (NIST SP 800-90 Section 10.1 Table 2).
00152  */
00153 #define HMAC_DRBG_MIN_ENTROPY_LEN_BYTES( security_strength ) \
00154         ( (security_strength) / 8 )
00155 
00156 /** Maximum entropy input length
00157  *
00158  * The maximum entropy input length for HMAC_DRBG is 2^35 bits
00159  * according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 2 (NIST SP
00160  * 800-90 Section 10.1 Table 2).
00161  *
00162  * We choose to allow up to 32 bytes.
00163  */
00164 #define HMAC_DRBG_MAX_ENTROPY_LEN_BYTES 32
00165 
00166 /** Maximum personalisation string length
00167  *
00168  * The maximum permitted personalisation string length for HMAC_DRBG
00169  * is 2^35 bits according to ANS X9.82 Part 3-2007 Section 10.2.1
00170  * Table 1 (NIST SP 800-90 Section 10.1 Table 2).
00171  *
00172  * We choose to allow up to 2^32-1 bytes (i.e. 2^35-8 bits).
00173  */
00174 #define HMAC_DRBG_MAX_PERSONAL_LEN_BYTES 0xffffffffUL
00175 
00176 /** Maximum additional input length
00177  *
00178  * The maximum permitted additional input length for HMAC_DRBG is 2^35
00179  * bits according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 1
00180  * (NIST SP 800-90 Section 10.1 Table 2).
00181  *
00182  * We choose to allow up to 2^32-1 bytes (i.e. 2^35-8 bits).
00183  */
00184 #define HMAC_DRBG_MAX_ADDITIONAL_LEN_BYTES 0xffffffffUL
00185 
00186 /** Maximum length of generated pseudorandom data per request
00187  *
00188  * The maximum number of bits per request for HMAC_DRBG is 2^19 bits
00189  * according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 1 (NIST SP
00190  * 800-90 Section 10.1 Table 2).
00191  *
00192  * We choose to allow up to 2^16-1 bytes (i.e. 2^19-8 bits).
00193  */
00194 #define HMAC_DRBG_MAX_GENERATED_LEN_BYTES 0x0000ffffUL
00195 
00196 /** Reseed interval
00197  *
00198  * The maximum permitted reseed interval for HMAC_DRBG is 2^48
00199  * according to ANS X9.82 Part 3-2007 Section 10.2.1 Table 2 (NIST SP
00200  * 800-90 Section 10.1 Table 2).  However, the sample implementation
00201  * given in ANS X9.82 Part 3-2007 Annex E.2.1 (NIST SP 800-90 Appendix
00202  * F.2) shows a reseed interval of 10000.
00203  *
00204  * We choose a very conservative reseed interval.
00205  */
00206 #define HMAC_DRBG_RESEED_INTERVAL 1024
00207 
00208 /**
00209  * HMAC_DRBG internal state
00210  *
00211  * This structure is defined by ANS X9.82 Part 3-2007 Section
00212  * 10.2.2.2.1 (NIST SP 800-90 Section 10.1.2.1).
00213  *
00214  * The "administrative information" portions (security_strength and
00215  * prediction_resistance) are design-time constants and so are not
00216  * present as fields in this structure.
00217  */
00218 struct hmac_drbg_state {
00219         /** Current value
00220          *
00221          * "The value V of outlen bits, which is updated each time
00222          * another outlen bits of output are produced"
00223          */
00224         uint8_t value[HMAC_DRBG_MAX_OUTLEN_BYTES];
00225         /** Current key
00226          *
00227          * "The outlen-bit Key, which is updated at least once each
00228          * time that the DRBG mechanism generates pseudorandom bits."
00229          */
00230         uint8_t key[HMAC_DRBG_MAX_OUTLEN_BYTES];
00231         /** Reseed counter
00232          *
00233          * "A counter (reseed_counter) that indicates the number of
00234          * requests for pseudorandom bits since instantiation or
00235          * reseeding"
00236          */
00237         unsigned int reseed_counter;
00238 };
00239 
00240 extern void hmac_drbg_instantiate ( struct digest_algorithm *hash,
00241                                     struct hmac_drbg_state *state,
00242                                     const void *entropy, size_t entropy_len,
00243                                     const void *personal, size_t personal_len );
00244 extern void hmac_drbg_reseed ( struct digest_algorithm *hash,
00245                                struct hmac_drbg_state *state,
00246                                const void *entropy, size_t entropy_len,
00247                                const void *additional, size_t additional_len );
00248 extern int hmac_drbg_generate ( struct digest_algorithm *hash,
00249                                 struct hmac_drbg_state *state,
00250                                 const void *additional, size_t additional_len,
00251                                 void *data, size_t len );
00252 
00253 #endif /* _IPXE_HMAC_DRBG_H */