iPXE
Functions
hmac_drbg.c File Reference

HMAC_DRBG algorithm. More...

#include <stdint.h>
#include <string.h>
#include <errno.h>
#include <assert.h>
#include <ipxe/crypto.h>
#include <ipxe/hmac.h>
#include <ipxe/hmac_drbg.h>

Go to the source code of this file.

Functions

 FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
 
static void hmac_drbg_update_key (struct digest_algorithm *hash, struct hmac_drbg_state *state, const void *data, size_t len, const uint8_t single)
 Update the HMAC_DRBG key. More...
 
static void hmac_drbg_update_value (struct digest_algorithm *hash, struct hmac_drbg_state *state)
 Update the HMAC_DRBG value. More...
 
static void hmac_drbg_update (struct digest_algorithm *hash, struct hmac_drbg_state *state, const void *data, size_t len)
 Update HMAC_DRBG internal state. More...
 
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. More...
 
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. More...
 
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. More...
 

Detailed Description

HMAC_DRBG algorithm.

This algorithm is designed to comply with ANS X9.82 Part 3-2007 Section 10.2.2.2. This standard is not freely available, but most of the text appears to be shared with NIST SP 800-90, which can be downloaded from

http://csrc.nist.gov/publications/nistpubs/800-90/SP800-90revised_March2007.pdf

Where possible, references are given to both documents. In the case of any disagreement, ANS X9.82 takes priority over NIST SP 800-90. (In particular, note that some algorithms that are Approved by NIST SP 800-90 are not Approved by ANS X9.82.)

Definition in file hmac_drbg.c.

Function Documentation

◆ FILE_LICENCE()

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL  )

◆ hmac_drbg_update_key()

static void hmac_drbg_update_key ( struct digest_algorithm hash,
struct hmac_drbg_state state,
const void *  data,
size_t  len,
const uint8_t  single 
)
static

Update the HMAC_DRBG key.

Parameters
hashUnderlying hash algorithm
stateHMAC_DRBG internal state
dataProvided data
lenLength of provided data
singleSingle byte used in concatenation

This function carries out the operation

K = HMAC ( K, V || single || provided_data )

as used by hmac_drbg_update()

Definition at line 78 of file hmac_drbg.c.

81  {
82  uint8_t context[ hash->ctxsize ];
83  size_t out_len = hash->digestsize;
84 
85  DBGC ( state, "HMAC_DRBG_%s %p provided data :\n", hash->name, state );
86  DBGC_HDA ( state, 0, data, len );
87 
88  /* Sanity checks */
89  assert ( hash != NULL );
90  assert ( state != NULL );
91  assert ( ( data != NULL ) || ( len == 0 ) );
92  assert ( ( single == 0x00 ) || ( single == 0x01 ) );
93 
94  /* K = HMAC ( K, V || single || provided_data ) */
95  hmac_init ( hash, context, state->key, &out_len );
96  assert ( out_len == hash->digestsize );
97  hmac_update ( hash, context, state->value, out_len );
98  hmac_update ( hash, context, &single, sizeof ( single ) );
99  hmac_update ( hash, context, data, len );
100  hmac_final ( hash, context, state->key, &out_len, state->key );
101  assert ( out_len == hash->digestsize );
102 
103  DBGC ( state, "HMAC_DRBG_%s %p K = HMAC ( K, V || %#02x || "
104  "provided_data ) :\n", hash->name, state, single );
105  DBGC_HDA ( state, 0, state->key, out_len );
106 }
uint8_t state
State.
Definition: eth_slow.h:47
void hmac_final(struct digest_algorithm *digest, void *digest_ctx, void *key, size_t *key_len, void *hmac)
Finalise HMAC.
Definition: hmac.c:115
#define DBGC(...)
Definition: compiler.h:505
assert((readw(&hdr->flags) &(GTF_reading|GTF_writing))==0)
#define DBGC_HDA(...)
Definition: compiler.h:506
pseudo_bit_t hash[0x00010]
Hash algorithm.
Definition: arbel.h:13
unsigned char uint8_t
Definition: stdint.h:10
uint32_t len
Length.
Definition: ena.h:14
void hmac_init(struct digest_algorithm *digest, void *digest_ctx, void *key, size_t *key_len)
Initialise HMAC.
Definition: hmac.c:80
struct arbelprm_port_state_change_st data
Message.
Definition: arbel.h:12
static void hmac_update(struct digest_algorithm *digest, void *digest_ctx, const void *data, size_t len)
Update HMAC.
Definition: hmac.h:21
#define NULL
NULL pointer (VOID *)
Definition: Base.h:362

References assert(), data, DBGC, DBGC_HDA, hash, hmac_final(), hmac_init(), hmac_update(), len, NULL, and state.

Referenced by hmac_drbg_update().

◆ hmac_drbg_update_value()

static void hmac_drbg_update_value ( struct digest_algorithm hash,
struct hmac_drbg_state state 
)
static

Update the HMAC_DRBG value.

Parameters
hashUnderlying hash algorithm
stateHMAC_DRBG internal state
dataProvided data
lenLength of provided data
singleSingle byte used in concatenation

This function carries out the operation

V = HMAC ( K, V )

as used by hmac_drbg_update() and hmac_drbg_generate()

Definition at line 123 of file hmac_drbg.c.

124  {
125  uint8_t context[ hash->ctxsize ];
126  size_t out_len = hash->digestsize;
127 
128  /* Sanity checks */
129  assert ( hash != NULL );
130  assert ( state != NULL );
131 
132  /* V = HMAC ( K, V ) */
133  hmac_init ( hash, context, state->key, &out_len );
134  assert ( out_len == hash->digestsize );
135  hmac_update ( hash, context, state->value, out_len );
136  hmac_final ( hash, context, state->key, &out_len, state->value );
137  assert ( out_len == hash->digestsize );
138 
139  DBGC ( state, "HMAC_DRBG_%s %p V = HMAC ( K, V ) :\n",
140  hash->name, state );
141  DBGC_HDA ( state, 0, state->value, out_len );
142 }
uint8_t state
State.
Definition: eth_slow.h:47
void hmac_final(struct digest_algorithm *digest, void *digest_ctx, void *key, size_t *key_len, void *hmac)
Finalise HMAC.
Definition: hmac.c:115
#define DBGC(...)
Definition: compiler.h:505
assert((readw(&hdr->flags) &(GTF_reading|GTF_writing))==0)
#define DBGC_HDA(...)
Definition: compiler.h:506
pseudo_bit_t hash[0x00010]
Hash algorithm.
Definition: arbel.h:13
unsigned char uint8_t
Definition: stdint.h:10
void hmac_init(struct digest_algorithm *digest, void *digest_ctx, void *key, size_t *key_len)
Initialise HMAC.
Definition: hmac.c:80
static void hmac_update(struct digest_algorithm *digest, void *digest_ctx, const void *data, size_t len)
Update HMAC.
Definition: hmac.h:21
#define NULL
NULL pointer (VOID *)
Definition: Base.h:362

References assert(), DBGC, DBGC_HDA, hash, hmac_final(), hmac_init(), hmac_update(), NULL, and state.

Referenced by hmac_drbg_generate(), and hmac_drbg_update().

◆ hmac_drbg_update()

static void hmac_drbg_update ( struct digest_algorithm hash,
struct hmac_drbg_state state,
const void *  data,
size_t  len 
)
static

Update HMAC_DRBG internal state.

Parameters
hashUnderlying hash algorithm
stateHMAC_DRBG internal state
dataProvided data
lenLength of provided data

This is the HMAC_DRBG_Update function defined in ANS X9.82 Part 3-2007 Section 10.2.2.2.2 (NIST SP 800-90 Section 10.1.2.2).

The key and value are updated in-place within the HMAC_DRBG internal state.

Definition at line 158 of file hmac_drbg.c.

160  {
161 
162  DBGC ( state, "HMAC_DRBG_%s %p update\n", hash->name, state );
163 
164  /* Sanity checks */
165  assert ( hash != NULL );
166  assert ( state != NULL );
167  assert ( ( data != NULL ) || ( len == 0 ) );
168 
169  /* 1. K = HMAC ( K, V || 0x00 || provided_data ) */
170  hmac_drbg_update_key ( hash, state, data, len, 0x00 );
171 
172  /* 2. V = HMAC ( K, V ) */
174 
175  /* 3. If ( provided_data = Null ), then return K and V */
176  if ( ! len )
177  return;
178 
179  /* 4. K = HMAC ( K, V || 0x01 || provided_data ) */
180  hmac_drbg_update_key ( hash, state, data, len, 0x01 );
181 
182  /* 5. V = HMAC ( K, V ) */
184 
185  /* 6. Return K and V */
186 }
uint8_t state
State.
Definition: eth_slow.h:47
#define DBGC(...)
Definition: compiler.h:505
static void hmac_drbg_update_key(struct digest_algorithm *hash, struct hmac_drbg_state *state, const void *data, size_t len, const uint8_t single)
Update the HMAC_DRBG key.
Definition: hmac_drbg.c:78
assert((readw(&hdr->flags) &(GTF_reading|GTF_writing))==0)
static void hmac_drbg_update_value(struct digest_algorithm *hash, struct hmac_drbg_state *state)
Update the HMAC_DRBG value.
Definition: hmac_drbg.c:123
pseudo_bit_t hash[0x00010]
Hash algorithm.
Definition: arbel.h:13
uint32_t len
Length.
Definition: ena.h:14
struct arbelprm_port_state_change_st data
Message.
Definition: arbel.h:12
#define NULL
NULL pointer (VOID *)
Definition: Base.h:362

References assert(), data, DBGC, hash, hmac_drbg_update_key(), hmac_drbg_update_value(), len, NULL, and state.

Referenced by hmac_drbg_generate(), and hmac_drbg_reseed().

◆ hmac_drbg_instantiate()

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.

Parameters
hashUnderlying hash algorithm
stateHMAC_DRBG internal state to be initialised
entropyEntropy input
entropy_lenLength of entropy input
personalPersonalisation string
personal_lenLength of personalisation string

This is the HMAC_DRBG_Instantiate_algorithm function defined in ANS X9.82 Part 3-2007 Section 10.2.2.2.3 (NIST SP 800-90 Section 10.1.2.3).

The nonce must be included within the entropy input (i.e. the entropy input must contain at least 3/2 * security_strength bits of entropy, as per ANS X9.82 Part 3-2007 Section 8.4.2 (NIST SP 800-90 Section 8.6.7).

The key, value and reseed counter are updated in-place within the HMAC_DRBG internal state.

Definition at line 210 of file hmac_drbg.c.

213  {
214  size_t out_len = hash->digestsize;
215 
216  DBGC ( state, "HMAC_DRBG_%s %p instantiate\n", hash->name, state );
217 
218  /* Sanity checks */
219  assert ( hash != NULL );
220  assert ( state != NULL );
221  assert ( entropy != NULL );
222  assert ( ( personal != NULL ) || ( personal_len == 0 ) );
223 
224  /* 1. seed_material = entropy_input || nonce ||
225  * personalisation_string
226  */
227 
228  /* 2. Key = 0x00 00..00 */
229  memset ( state->key, 0x00, out_len );
230 
231  /* 3. V = 0x01 01...01 */
232  memset ( state->value, 0x01, out_len );
233 
234  /* 4. ( Key, V ) = HMAC_DBRG_Update ( seed_material, Key, V )
235  * 5. reseed_counter = 1
236  * 6. Return V, Key and reseed_counter as the
237  * initial_working_state
238  */
239  hmac_drbg_reseed ( hash, state, entropy, entropy_len,
240  personal, personal_len );
241 }
uint8_t state
State.
Definition: eth_slow.h:47
#define DBGC(...)
Definition: compiler.h:505
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
assert((readw(&hdr->flags) &(GTF_reading|GTF_writing))==0)
pseudo_bit_t hash[0x00010]
Hash algorithm.
Definition: arbel.h:13
#define NULL
NULL pointer (VOID *)
Definition: Base.h:362
void * memset(void *dest, int character, size_t len) __nonnull

References assert(), DBGC, hash, hmac_drbg_reseed(), memset(), NULL, and state.

Referenced by drbg_instantiate_algorithm().

◆ hmac_drbg_reseed()

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.

Parameters
hashUnderlying hash algorithm
stateHMAC_DRBG internal state
entropyEntropy input
entropy_lenLength of entropy input
additionalAdditional input
additional_lenLength of additional input

This is the HMAC_DRBG_Reseed_algorithm function defined in ANS X9.82 Part 3-2007 Section 10.2.2.2.4 (NIST SP 800-90 Section 10.1.2.4).

The key, value and reseed counter are updated in-place within the HMAC_DRBG internal state.

Definition at line 259 of file hmac_drbg.c.

262  {
263  uint8_t seed_material[ entropy_len + additional_len ];
264 
265  DBGC ( state, "HMAC_DRBG_%s %p (re)seed\n", hash->name, state );
266 
267  /* Sanity checks */
268  assert ( hash != NULL );
269  assert ( state != NULL );
270  assert ( entropy != NULL );
271  assert ( ( additional != NULL ) || ( additional_len == 0 ) );
272 
273  /* 1. seed_material = entropy_input || additional_input */
274  memcpy ( seed_material, entropy, entropy_len );
275  memcpy ( ( seed_material + entropy_len ), additional, additional_len );
276  DBGC ( state, "HMAC_DRBG_%s %p seed material :\n", hash->name, state );
277  DBGC_HDA ( state, 0, seed_material, sizeof ( seed_material ) );
278 
279  /* 2. ( Key, V ) = HMAC_DBRG_Update ( seed_material, Key, V ) */
280  hmac_drbg_update ( hash, state, seed_material,
281  sizeof ( seed_material ) );
282 
283  /* 3. reseed_counter = 1 */
284  state->reseed_counter = 1;
285 
286  /* 4. Return V, Key and reseed_counter as the new_working_state */
287 }
uint8_t state
State.
Definition: eth_slow.h:47
#define DBGC(...)
Definition: compiler.h:505
void * memcpy(void *dest, const void *src, size_t len) __nonnull
uint16_t additional
Additional sense code and qualifier.
Definition: scsi.h:28
assert((readw(&hdr->flags) &(GTF_reading|GTF_writing))==0)
#define DBGC_HDA(...)
Definition: compiler.h:506
pseudo_bit_t hash[0x00010]
Hash algorithm.
Definition: arbel.h:13
unsigned char uint8_t
Definition: stdint.h:10
static void hmac_drbg_update(struct digest_algorithm *hash, struct hmac_drbg_state *state, const void *data, size_t len)
Update HMAC_DRBG internal state.
Definition: hmac_drbg.c:158
#define NULL
NULL pointer (VOID *)
Definition: Base.h:362

References additional, assert(), DBGC, DBGC_HDA, hash, hmac_drbg_update(), memcpy(), NULL, and state.

Referenced by drbg_reseed_algorithm(), and hmac_drbg_instantiate().

◆ hmac_drbg_generate()

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.

Parameters
hashUnderlying hash algorithm
stateHMAC_DRBG internal state
additionalAdditional input
additional_lenLength of additional input
dataOutput buffer
lenLength of output buffer
Return values
rcReturn status code

This is the HMAC_DRBG_Generate_algorithm function defined in ANS X9.82 Part 3-2007 Section 10.2.2.2.5 (NIST SP 800-90 Section 10.1.2.5).

Requests must be for an integral number of bytes.

The key, value and reseed counter are updated in-place within the HMAC_DRBG internal state.

Note that the only permitted error is "reseed required".

Definition at line 310 of file hmac_drbg.c.

313  {
314  size_t out_len = hash->digestsize;
315  void *orig_data = data;
316  size_t orig_len = len;
317  size_t frag_len;
318 
319  DBGC ( state, "HMAC_DRBG_%s %p generate\n", hash->name, state );
320 
321  /* Sanity checks */
322  assert ( hash != NULL );
323  assert ( state != NULL );
324  assert ( data != NULL );
325  assert ( ( additional != NULL ) || ( additional_len == 0 ) );
326 
327  /* 1. If reseed_counter > reseed_interval, then return an
328  * indication that a reseed is required
329  */
330  if ( state->reseed_counter > HMAC_DRBG_RESEED_INTERVAL ) {
331  DBGC ( state, "HMAC_DRBG_%s %p reseed interval exceeded\n",
332  hash->name, state );
333  return -ESTALE;
334  }
335 
336  /* 2. If additional_input != Null, then
337  * ( Key, V ) = HMAC_DRBG_Update ( additional_input, Key, V )
338  */
339  if ( additional_len )
340  hmac_drbg_update ( hash, state, additional, additional_len );
341 
342  /* 3. temp = Null
343  * 4. While ( len ( temp ) < requested_number_of_bits ) do:
344  */
345  while ( len ) {
346 
347  /* 4.1 V = HMAC ( Key, V ) */
349 
350  /* 4.2. temp = temp || V
351  * 5. returned_bits = Leftmost requested_number_of_bits
352  * of temp
353  */
354  frag_len = len;
355  if ( frag_len > out_len )
356  frag_len = out_len;
357  memcpy ( data, state->value, frag_len );
358  data += frag_len;
359  len -= frag_len;
360  }
361 
362  /* 6. ( Key, V ) = HMAC_DRBG_Update ( additional_input, Key, V ) */
363  hmac_drbg_update ( hash, state, additional, additional_len );
364 
365  /* 7. reseed_counter = reseed_counter + 1 */
366  state->reseed_counter++;
367 
368  DBGC ( state, "HMAC_DRBG_%s %p generated :\n", hash->name, state );
369  DBGC_HDA ( state, 0, orig_data, orig_len );
370 
371  /* 8. Return SUCCESS, returned_bits, and the new values of
372  * Key, V and reseed_counter as the new_working_state
373  */
374  return 0;
375 }
uint8_t state
State.
Definition: eth_slow.h:47
#define DBGC(...)
Definition: compiler.h:505
void * memcpy(void *dest, const void *src, size_t len) __nonnull
uint16_t additional
Additional sense code and qualifier.
Definition: scsi.h:28
assert((readw(&hdr->flags) &(GTF_reading|GTF_writing))==0)
#define DBGC_HDA(...)
Definition: compiler.h:506
static void hmac_drbg_update_value(struct digest_algorithm *hash, struct hmac_drbg_state *state)
Update the HMAC_DRBG value.
Definition: hmac_drbg.c:123
#define HMAC_DRBG_RESEED_INTERVAL
Reseed interval.
Definition: hmac_drbg.h:206
pseudo_bit_t hash[0x00010]
Hash algorithm.
Definition: arbel.h:13
uint32_t len
Length.
Definition: ena.h:14
struct arbelprm_port_state_change_st data
Message.
Definition: arbel.h:12
static void hmac_drbg_update(struct digest_algorithm *hash, struct hmac_drbg_state *state, const void *data, size_t len)
Update HMAC_DRBG internal state.
Definition: hmac_drbg.c:158
#define NULL
NULL pointer (VOID *)
Definition: Base.h:362
#define ESTALE
Stale file handle.
Definition: errno.h:659

References additional, assert(), data, DBGC, DBGC_HDA, ESTALE, hash, HMAC_DRBG_RESEED_INTERVAL, hmac_drbg_update(), hmac_drbg_update_value(), len, memcpy(), NULL, and state.

Referenced by drbg_generate_algorithm().