iPXE
drbg.h
Go to the documentation of this file.
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_OR_UBDL );
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 */
52  /** Reseed required flag */
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 ) {
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 ) {
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 ) {
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 */
int hmac_drbg_generate(struct digest_algorithm *hash, struct hmac_drbg_state *state, const void *additional, size_t additional_len, void *data, size_t len)
Generate pseudorandom bits using HMAC_DRBG.
Definition: hmac_drbg.c:310
int reseed_required
Reseed required flag.
Definition: drbg.h:53
uint8_t state
State.
Definition: eth_slow.h:47
void hmac_drbg_instantiate(struct digest_algorithm *hash, struct hmac_drbg_state *state, const void *entropy, size_t entropy_len, const void *personal, size_t personal_len)
Instantiate HMAC_DRBG.
Definition: hmac_drbg.c:210
static void drbg_instantiate_algorithm(struct drbg_state *state, const void *entropy, size_t entropy_len, const void *personal, size_t personal_len)
Instantiate DRBG algorithm.
Definition: drbg.h:70
struct hmac_drbg_state internal
Algorithm internal state.
Definition: drbg.h:51
int drbg_instantiate(struct drbg_state *state, const void *personal, size_t personal_len)
Instantiate DRBG.
Definition: drbg.c:78
void hmac_drbg_reseed(struct digest_algorithm *hash, struct hmac_drbg_state *state, const void *entropy, size_t entropy_len, const void *additional, size_t additional_len)
Reseed HMAC_DRBG.
Definition: hmac_drbg.c:259
A Deterministic Random Bit Generator.
Definition: drbg.h:49
void drbg_uninstantiate(struct drbg_state *state)
Uninstantiate DRBG.
Definition: drbg.c:423
#define HMAC_DRBG_HASH(hmac_drbg)
Underlying hash algorithm.
Definition: hmac_drbg.h:90
#define HMAC_DRBG_ALGORITHM
Choose HMAC_DRBG using SHA-256.
Definition: drbg.h:20
static void drbg_reseed_algorithm(struct drbg_state *state, const void *entropy, size_t entropy_len, const void *additional, size_t additional_len)
Reseed DRBG algorithm.
Definition: drbg.h:92
int valid
State is valid.
Definition: drbg.h:55
uint16_t additional
Additional sense code and qualifier.
Definition: scsi.h:28
static int drbg_generate_algorithm(struct drbg_state *state, const void *additional, size_t additional_len, void *data, size_t len)
Generate pseudorandom bits using DRBG algorithm.
Definition: drbg.h:117
HMAC_DRBG internal state.
Definition: hmac_drbg.h:218
int drbg_generate(struct drbg_state *state, const void *additional, size_t additional_len, int prediction_resist, void *data, size_t len)
Generate pseudorandom bits using DRBG.
Definition: drbg.c:283
uint32_t len
Length.
Definition: ena.h:14
struct arbelprm_port_state_change_st data
Message.
Definition: arbel.h:12
int drbg_reseed(struct drbg_state *state, const void *additional, size_t additional_len)
Reseed DRBG.
Definition: drbg.c:190
SHA-256 algorithm.
FILE_LICENCE(GPL2_OR_LATER_OR_UBDL)
HMAC_DRBG algorithm.