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.
static void hmac_drbg_update_value (struct digest_algorithm *hash, struct hmac_drbg_state *state)
 Update the HMAC_DRBG value.
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.
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.
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.
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.

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 ( 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 
) [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.

References assert, context, digest_algorithm::ctxsize, DBGC, DBGC_HDA, digest_algorithm::digestsize, hmac_final(), hmac_init(), hmac_update(), hmac_drbg_state::key, digest_algorithm::name, NULL, and hmac_drbg_state::value.

Referenced by hmac_drbg_update().

                                                          {
        uint8_t context[ hash->ctxsize ];
        size_t out_len = hash->digestsize;

        DBGC ( state, "HMAC_DRBG_%s %p provided data :\n", hash->name, state );
        DBGC_HDA ( state, 0, data, len );

        /* Sanity checks */
        assert ( hash != NULL );
        assert ( state != NULL );
        assert ( ( data != NULL ) || ( len == 0 ) );
        assert ( ( single == 0x00 ) || ( single == 0x01 ) );

        /* K = HMAC ( K, V || single || provided_data ) */
        hmac_init ( hash, context, state->key, &out_len );
        assert ( out_len == hash->digestsize );
        hmac_update ( hash, context, state->value, out_len );
        hmac_update ( hash, context, &single, sizeof ( single ) );
        hmac_update ( hash, context, data, len );
        hmac_final ( hash, context, state->key, &out_len, state->key );
        assert ( out_len == hash->digestsize );

        DBGC ( state, "HMAC_DRBG_%s %p K = HMAC ( K, V || %#02x || "
               "provided_data ) :\n", hash->name, state, single );
        DBGC_HDA ( state, 0, state->key, out_len );
}
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.

References assert, context, digest_algorithm::ctxsize, DBGC, DBGC_HDA, digest_algorithm::digestsize, hmac_final(), hmac_init(), hmac_update(), hmac_drbg_state::key, digest_algorithm::name, NULL, and hmac_drbg_state::value.

Referenced by hmac_drbg_generate(), and hmac_drbg_update().

                                                                     {
        uint8_t context[ hash->ctxsize ];
        size_t out_len = hash->digestsize;

        /* Sanity checks */
        assert ( hash != NULL );
        assert ( state != NULL );

        /* V = HMAC ( K, V ) */
        hmac_init ( hash, context, state->key, &out_len );
        assert ( out_len == hash->digestsize );
        hmac_update ( hash, context, state->value, out_len );
        hmac_final ( hash, context, state->key, &out_len, state->value );
        assert ( out_len == hash->digestsize );

        DBGC ( state, "HMAC_DRBG_%s %p V = HMAC ( K, V ) :\n",
               hash->name, state );
        DBGC_HDA ( state, 0, state->value, out_len );
}
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.

References assert, DBGC, hmac_drbg_update_key(), hmac_drbg_update_value(), digest_algorithm::name, and NULL.

Referenced by hmac_drbg_generate(), and hmac_drbg_reseed().

                                                              {

        DBGC ( state, "HMAC_DRBG_%s %p update\n", hash->name, state );

        /* Sanity checks */
        assert ( hash != NULL );
        assert ( state != NULL );
        assert ( ( data != NULL ) || ( len == 0 ) );

        /* 1.  K = HMAC ( K, V || 0x00 || provided_data ) */
        hmac_drbg_update_key ( hash, state, data, len, 0x00 );

        /* 2.  V = HMAC ( K, V ) */
        hmac_drbg_update_value ( hash, state );

        /* 3.  If ( provided_data = Null ), then return K and V */
        if ( ! len )
                return;

        /* 4.  K = HMAC ( K, V || 0x01 || provided_data ) */
        hmac_drbg_update_key ( hash, state, data, len, 0x01 );

        /* 5.  V = HMAC ( K, V ) */
        hmac_drbg_update_value ( hash, state );

        /* 6.  Return K and V */
}
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.

References assert, DBGC, digest_algorithm::digestsize, hmac_drbg_reseed(), hmac_drbg_state::key, memset(), digest_algorithm::name, NULL, and hmac_drbg_state::value.

Referenced by drbg_instantiate_algorithm().

                                                                        {
        size_t out_len = hash->digestsize;

        DBGC ( state, "HMAC_DRBG_%s %p instantiate\n", hash->name, state );

        /* Sanity checks */
        assert ( hash != NULL );
        assert ( state != NULL );
        assert ( entropy != NULL );
        assert ( ( personal != NULL ) || ( personal_len == 0 ) );

        /* 1.  seed_material = entropy_input || nonce ||
         *     personalisation_string
         */

        /* 2.  Key = 0x00 00..00 */
        memset ( state->key, 0x00, out_len );

        /* 3.  V = 0x01 01...01 */
        memset ( state->value, 0x01, out_len );

        /* 4.  ( Key, V ) = HMAC_DBRG_Update ( seed_material, Key, V )
         * 5.  reseed_counter = 1
         * 6.  Return V, Key and reseed_counter as the
         *     initial_working_state
         */
        hmac_drbg_reseed ( hash, state, entropy, entropy_len,
                           personal, personal_len );
}
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.

References assert, DBGC, DBGC_HDA, hmac_drbg_update(), memcpy(), digest_algorithm::name, NULL, and hmac_drbg_state::reseed_counter.

Referenced by drbg_reseed_algorithm(), and hmac_drbg_instantiate().

                                                                        {
        uint8_t seed_material[ entropy_len + additional_len ];

        DBGC ( state, "HMAC_DRBG_%s %p (re)seed\n", hash->name, state );

        /* Sanity checks */
        assert ( hash != NULL );
        assert ( state != NULL );
        assert ( entropy != NULL );
        assert ( ( additional != NULL ) || ( additional_len == 0 ) );

        /* 1.  seed_material = entropy_input || additional_input */
        memcpy ( seed_material, entropy, entropy_len );
        memcpy ( ( seed_material + entropy_len ), additional, additional_len );
        DBGC ( state, "HMAC_DRBG_%s %p seed material :\n", hash->name, state );
        DBGC_HDA ( state, 0, seed_material, sizeof ( seed_material ) );

        /* 2.  ( Key, V ) = HMAC_DBRG_Update ( seed_material, Key, V ) */
        hmac_drbg_update ( hash, state, seed_material,
                           sizeof ( seed_material ) );

        /* 3.  reseed_counter = 1 */
        state->reseed_counter = 1;

        /* 4.  Return V, Key and reseed_counter as the new_working_state */
}
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.

References assert, data, DBGC, DBGC_HDA, digest_algorithm::digestsize, ESTALE, HMAC_DRBG_RESEED_INTERVAL, hmac_drbg_update(), hmac_drbg_update_value(), len, memcpy(), digest_algorithm::name, NULL, hmac_drbg_state::reseed_counter, and hmac_drbg_state::value.

Referenced by drbg_generate_algorithm().

                                                  {
        size_t out_len = hash->digestsize;
        void *orig_data = data;
        size_t orig_len = len;
        size_t frag_len;

        DBGC ( state, "HMAC_DRBG_%s %p generate\n", hash->name, state );

        /* Sanity checks */
        assert ( hash != NULL );
        assert ( state != NULL );
        assert ( data != NULL );
        assert ( ( additional != NULL ) || ( additional_len == 0 ) );

        /* 1.  If reseed_counter > reseed_interval, then return an
         *     indication that a reseed is required
         */
        if ( state->reseed_counter > HMAC_DRBG_RESEED_INTERVAL ) {
                DBGC ( state, "HMAC_DRBG_%s %p reseed interval exceeded\n",
                       hash->name, state );
                return -ESTALE;
        }

        /* 2.  If additional_input != Null, then
         *     ( Key, V ) = HMAC_DRBG_Update ( additional_input, Key, V )
         */
        if ( additional_len )
                hmac_drbg_update ( hash, state, additional, additional_len );

        /* 3.  temp = Null
         * 4.  While ( len ( temp ) < requested_number_of_bits ) do:
         */
        while ( len ) {

                /* 4.1  V = HMAC ( Key, V ) */
                hmac_drbg_update_value ( hash, state );

                /* 4.2.  temp = temp || V
                 * 5.    returned_bits = Leftmost requested_number_of_bits
                 *       of temp
                 */
                frag_len = len;
                if ( frag_len > out_len )
                        frag_len = out_len;
                memcpy ( data, state->value, frag_len );
                data += frag_len;
                len -= frag_len;
        }

        /* 6.  ( Key, V ) = HMAC_DRBG_Update ( additional_input, Key, V ) */
        hmac_drbg_update ( hash, state, additional, additional_len );

        /* 7.  reseed_counter = reseed_counter + 1 */
        state->reseed_counter++;

        DBGC ( state, "HMAC_DRBG_%s %p generated :\n", hash->name, state );
        DBGC_HDA ( state, 0, orig_data, orig_len );

        /* 8.  Return SUCCESS, returned_bits, and the new values of
         *     Key, V and reseed_counter as the new_working_state
         */
        return 0;
}