hkdf.h File Reference

HMAC-based Extract-and-Expand Key Derivation Function (HKDF). More...

#include <ipxe/crypto.h>

Go to the source code of this file.

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
	FILE_SECBOOT (PERMITTED)
void	hkdf_extract (struct digest_algorithm *digest, const void *salt, size_t salt_len, const void *ikm, size_t ikm_len, void *prk)
	Extract fixed-length pseudorandom key.
void	hkdf_expand (struct digest_algorithm *digest, const void *prk, const void *info, size_t info_len, void *out, size_t len)
	Expand pseudorandom key.

Detailed Description

HMAC-based Extract-and-Expand Key Derivation Function (HKDF).

Definition in file hkdf.h.

Function Documentation

FILE_LICENCE()

FILE_LICENCE

(

GPL2_OR_LATER_OR_UBDL

)

FILE_SECBOOT()

FILE_SECBOOT

(

PERMITTED

)

References info, info_len, len, and out.

hkdf_extract()

void hkdf_extract ( struct digest_algorithm * digest, const void * salt, size_t salt_len, const void * ikm, size_t ikm_len, void * prk )

extern

Extract fixed-length pseudorandom key.

Parameters

digest	Digest algorithm
salt	Salt value (or NULL)
salt_len	Length of salt value
ikm	Input keying material
ikm_len	Length of input keying material
prk	Pseudorandom key to fill in

The salt and input keying material are allowed to overlap the buffer that will be filled in with the pseudorandom key.

Definition at line 56 of file hkdf.c.

                                {
        uint8_t ctx[ hmac_ctxsize ( digest ) ];
        uint8_t zero[ digest->digestsize ];
 
        /* Use all-zero salt if not specified */
        if ( ! salt ) {
                assert ( salt_len == 0 );
                memset ( zero, 0, sizeof ( zero ) );
                salt = zero;
                salt_len = sizeof ( zero );
        }
 
        /* Calculate pseudorandom key */
        hmac_init ( digest, ctx, salt, salt_len );
        hmac_update ( digest, ctx, ikm, ikm_len );
        hmac_final ( digest, ctx, prk );
}

References assert, ctx, digest_algorithm::digestsize, hmac_ctxsize(), hmac_final(), hmac_init(), hmac_update(), and memset().

Referenced by hkdf_okx(), and tls_generate_ephemeral_master().

hkdf_expand()

void hkdf_expand ( struct digest_algorithm * digest, const void * prk, const void * info, size_t info_len, void * out, size_t len )

extern

Expand pseudorandom key.

Parameters

digest	Digest algorithm
prk	Pseudorandom key
info	Additional information (or NULL)
info_len	Length of additional information
out	Output keying material
len	Length of output keying material

The pseudorandom key and additional information are allowed to overlap the buffer that will be filled in with the output keying material, provided that the length of the output keying material is less than or equal to the length of the pseudorandom key.

In particular, this allows hkdf_expand() to be used to create a new generation of pseudorandom key (i.e. to have the output keying material overwrite the existing pseudorandom key).

Definition at line 95 of file hkdf.c.

                                                                              {
        size_t digestsize = digest->digestsize;
        uint8_t ctx[ hmac_ctxsize ( digest ) ];
        uint8_t hash[digestsize];
        uint8_t index = 0;
        size_t frag_len;
 
        /* Sanity check */
        assert ( len <= ( digestsize * 0xff /* max index */ ) );
 
        /* Construct output keying material */
        while ( len ) {
 
                /* Calculate T(n) */
                hmac_init ( digest, ctx, prk, digestsize );
                if ( index++ )
                        hmac_update ( digest, ctx, hash, digestsize );
                hmac_update ( digest, ctx, info, info_len );
                hmac_update ( digest, ctx, &index, sizeof ( index ) );
                hmac_final ( digest, ctx, hash );
 
                /* Copy to output buffer */
                frag_len = len;
                if ( frag_len > digestsize )
                        frag_len = digestsize;
                memcpy ( out, hash, frag_len );
                out += frag_len;
                len -= frag_len;
        }
}

References assert, ctx, digest_algorithm::digestsize, digestsize, hash, hmac_ctxsize(), hmac_final(), hmac_init(), hmac_update(), index, info, info_len, len, memcpy(), and out.

Referenced by hkdf_okx(), and tls_ephemeral().