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

   1 #ifndef _IPXE_DRBG_H
   2 #define _IPXE_DRBG_H
   3
   4 /** @file
   5  *
   6  * DRBG mechanism
   7  *
   8  */
   9
  10 FILE_LICENCE ( GPL2_OR_LATER );
  11
  12 #include <stdint.h>
  13 #include <ipxe/sha256.h>
  14 #include <ipxe/hmac_drbg.h>
  15
  16 /** Choose HMAC_DRBG using SHA-256
  17  *
  18  * HMAC_DRBG using SHA-256 is an Approved algorithm in ANS X9.82.
  19  */
  20 #define HMAC_DRBG_ALGORITHM HMAC_DRBG_SHA256
  21
  22 /** Maximum security strength */
  23 #define DRBG_MAX_SECURITY_STRENGTH \
  24         HMAC_DRBG_MAX_SECURITY_STRENGTH ( HMAC_DRBG_ALGORITHM )
  25
  26 /** Security strength
  27  *
  28  * We choose to operate at a strength of 128 bits.
  29  */
  30 #define DRBG_SECURITY_STRENGTH 128
  31
  32 /** Minimum entropy input length */
  33 #define DRBG_MIN_ENTROPY_LEN_BYTES \
  34         HMAC_DRBG_MIN_ENTROPY_LEN_BYTES ( DRBG_SECURITY_STRENGTH )
  35
  36 /** Maximum entropy input length */
  37 #define DRBG_MAX_ENTROPY_LEN_BYTES HMAC_DRBG_MAX_ENTROPY_LEN_BYTES
  38
  39 /** Maximum personalisation string length */
  40 #define DRBG_MAX_PERSONAL_LEN_BYTES HMAC_DRBG_MAX_PERSONAL_LEN_BYTES
  41
  42 /** Maximum additional input length */
  43 #define DRBG_MAX_ADDITIONAL_LEN_BYTES HMAC_DRBG_MAX_ADDITIONAL_LEN_BYTES
  44
  45 /** Maximum length of generated pseudorandom data per request */
  46 #define DRBG_MAX_GENERATED_LEN_BYTES HMAC_DRBG_MAX_GENERATED_LEN_BYTES
  47
  48 /** A Deterministic Random Bit Generator */
  49 struct drbg_state {
  50         /** Algorithm internal state */
  51         struct hmac_drbg_state internal;
  52         /** Reseed required flag */
  53         int reseed_required;
  54         /** State is valid */
  55         int valid;
  56 };
  57
  58 /**
  59  * Instantiate DRBG algorithm
  60  *
  61  * @v state             Algorithm state
  62  * @v entropy           Entropy input
  63  * @v entropy_len       Length of entropy input
  64  * @v personal          Personalisation string
  65  * @v personal_len      Length of personalisation string
  66  *
  67  * This is the Instantiate_algorithm function defined in ANS X9.82
  68  * Part 3-2007 Section 9.2 (NIST SP 800-90 Section 9.1).
  69  */
  70 static inline void drbg_instantiate_algorithm ( struct drbg_state *state,
  71                                                 const void *entropy,
  72                                                 size_t entropy_len,
  73                                                 const void *personal,
  74                                                 size_t personal_len ) {
  75         hmac_drbg_instantiate ( HMAC_DRBG_HASH ( HMAC_DRBG_ALGORITHM ),
  76                                 &state->internal, entropy, entropy_len,
  77                                 personal, personal_len );
  78 }
  79
  80 /**
  81  * Reseed DRBG algorithm
  82  *
  83  * @v state             Algorithm state
  84  * @v entropy           Entropy input
  85  * @v entropy_len       Length of entropy input
  86  * @v additional        Additional input
  87  * @v additional_len    Length of additional input
  88  *
  89  * This is the Reseed_algorithm function defined in ANS X9.82
  90  * Part 3-2007 Section 9.3 (NIST SP 800-90 Section 9.2).
  91  */
  92 static inline void drbg_reseed_algorithm ( struct drbg_state *state,
  93                                            const void *entropy,
  94                                            size_t entropy_len,
  95                                            const void *additional,
  96                                            size_t additional_len ) {
  97         hmac_drbg_reseed ( HMAC_DRBG_HASH ( HMAC_DRBG_ALGORITHM ),
  98                            &state->internal, entropy, entropy_len,
  99                            additional, additional_len );
 100 }
 101
 102 /**
 103  * Generate pseudorandom bits using DRBG algorithm
 104  *
 105  * @v state             Algorithm state
 106  * @v additional        Additional input
 107  * @v additional_len    Length of additional input
 108  * @v data              Output buffer
 109  * @v len               Length of output buffer
 110  * @ret rc              Return status code
 111  *
 112  * This is the Generate_algorithm function defined in ANS X9.82
 113  * Part 3-2007 Section 9.4 (NIST SP 800-90 Section 9.3).
 114  *
 115  * Note that the only permitted error is "reseed required".
 116  */
 117 static inline int drbg_generate_algorithm ( struct drbg_state *state,
 118                                             const void *additional,
 119                                             size_t additional_len,
 120                                             void *data, size_t len ) {
 121         return hmac_drbg_generate ( HMAC_DRBG_HASH ( HMAC_DRBG_ALGORITHM ),
 122                                     &state->internal, additional,
 123                                     additional_len, data, len );
 124 }
 125
 126 extern int drbg_instantiate ( struct drbg_state *state, const void *personal,
 127                               size_t personal_len );
 128 extern int drbg_reseed ( struct drbg_state *state, const void *additional,
 129                          size_t additional_len );
 130 extern int drbg_generate ( struct drbg_state *state, const void *additional,
 131                            size_t additional_len, int prediction_resist,
 132                            void *data, size_t len );
 133 extern void drbg_uninstantiate ( struct drbg_state *state );
 134
 135 #endif /* _IPXE_DRBG_H */