iPXE
drbg.h
Go to the documentation of this file.
00001 #ifndef _IPXE_DRBG_H
00002 #define _IPXE_DRBG_H
00003 
00004 /** @file
00005  *
00006  * DRBG mechanism
00007  *
00008  */
00009 
00010 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
00011 
00012 #include <stdint.h>
00013 #include <ipxe/sha256.h>
00014 #include <ipxe/hmac_drbg.h>
00015 
00016 /** Choose HMAC_DRBG using SHA-256
00017  *
00018  * HMAC_DRBG using SHA-256 is an Approved algorithm in ANS X9.82.
00019  */
00020 #define HMAC_DRBG_ALGORITHM HMAC_DRBG_SHA256
00021 
00022 /** Maximum security strength */
00023 #define DRBG_MAX_SECURITY_STRENGTH \
00024         HMAC_DRBG_MAX_SECURITY_STRENGTH ( HMAC_DRBG_ALGORITHM )
00025 
00026 /** Security strength
00027  *
00028  * We choose to operate at a strength of 128 bits.
00029  */
00030 #define DRBG_SECURITY_STRENGTH 128
00031 
00032 /** Minimum entropy input length */
00033 #define DRBG_MIN_ENTROPY_LEN_BYTES \
00034         HMAC_DRBG_MIN_ENTROPY_LEN_BYTES ( DRBG_SECURITY_STRENGTH )
00035 
00036 /** Maximum entropy input length */
00037 #define DRBG_MAX_ENTROPY_LEN_BYTES HMAC_DRBG_MAX_ENTROPY_LEN_BYTES
00038 
00039 /** Maximum personalisation string length */
00040 #define DRBG_MAX_PERSONAL_LEN_BYTES HMAC_DRBG_MAX_PERSONAL_LEN_BYTES
00041 
00042 /** Maximum additional input length */
00043 #define DRBG_MAX_ADDITIONAL_LEN_BYTES HMAC_DRBG_MAX_ADDITIONAL_LEN_BYTES
00044 
00045 /** Maximum length of generated pseudorandom data per request */
00046 #define DRBG_MAX_GENERATED_LEN_BYTES HMAC_DRBG_MAX_GENERATED_LEN_BYTES
00047 
00048 /** A Deterministic Random Bit Generator */
00049 struct drbg_state {
00050         /** Algorithm internal state */
00051         struct hmac_drbg_state internal;
00052         /** Reseed required flag */
00053         int reseed_required;
00054         /** State is valid */
00055         int valid;
00056 };
00057 
00058 /**
00059  * Instantiate DRBG algorithm
00060  *
00061  * @v state             Algorithm state
00062  * @v entropy           Entropy input
00063  * @v entropy_len       Length of entropy input
00064  * @v personal          Personalisation string
00065  * @v personal_len      Length of personalisation string
00066  *
00067  * This is the Instantiate_algorithm function defined in ANS X9.82
00068  * Part 3-2007 Section 9.2 (NIST SP 800-90 Section 9.1).
00069  */
00070 static inline void drbg_instantiate_algorithm ( struct drbg_state *state,
00071                                                 const void *entropy,
00072                                                 size_t entropy_len,
00073                                                 const void *personal,
00074                                                 size_t personal_len ) {
00075         hmac_drbg_instantiate ( HMAC_DRBG_HASH ( HMAC_DRBG_ALGORITHM ),
00076                                 &state->internal, entropy, entropy_len,
00077                                 personal, personal_len );
00078 }
00079 
00080 /**
00081  * Reseed DRBG algorithm
00082  *
00083  * @v state             Algorithm state
00084  * @v entropy           Entropy input
00085  * @v entropy_len       Length of entropy input
00086  * @v additional        Additional input
00087  * @v additional_len    Length of additional input
00088  *
00089  * This is the Reseed_algorithm function defined in ANS X9.82
00090  * Part 3-2007 Section 9.3 (NIST SP 800-90 Section 9.2).
00091  */
00092 static inline void drbg_reseed_algorithm ( struct drbg_state *state,
00093                                            const void *entropy,
00094                                            size_t entropy_len,
00095                                            const void *additional,
00096                                            size_t additional_len ) {
00097         hmac_drbg_reseed ( HMAC_DRBG_HASH ( HMAC_DRBG_ALGORITHM ),
00098                            &state->internal, entropy, entropy_len,
00099                            additional, additional_len );
00100 }
00101 
00102 /**
00103  * Generate pseudorandom bits using DRBG algorithm
00104  *
00105  * @v state             Algorithm state
00106  * @v additional        Additional input
00107  * @v additional_len    Length of additional input
00108  * @v data              Output buffer
00109  * @v len               Length of output buffer
00110  * @ret rc              Return status code
00111  *
00112  * This is the Generate_algorithm function defined in ANS X9.82
00113  * Part 3-2007 Section 9.4 (NIST SP 800-90 Section 9.3).
00114  *
00115  * Note that the only permitted error is "reseed required".
00116  */
00117 static inline int drbg_generate_algorithm ( struct drbg_state *state,
00118                                             const void *additional,
00119                                             size_t additional_len,
00120                                             void *data, size_t len ) {
00121         return hmac_drbg_generate ( HMAC_DRBG_HASH ( HMAC_DRBG_ALGORITHM ),
00122                                     &state->internal, additional,
00123                                     additional_len, data, len );
00124 }
00125 
00126 extern int drbg_instantiate ( struct drbg_state *state, const void *personal,
00127                               size_t personal_len );
00128 extern int drbg_reseed ( struct drbg_state *state, const void *additional,
00129                          size_t additional_len );
00130 extern int drbg_generate ( struct drbg_state *state, const void *additional,
00131                            size_t additional_len, int prediction_resist,
00132                            void *data, size_t len );
00133 extern void drbg_uninstantiate ( struct drbg_state *state );
00134 
00135 #endif /* _IPXE_DRBG_H */