Algorithms - HMAC

Functions

	Name
int	wc_HmacSetKey(Hmac * hmac, int type, const byte * key, word32 keySz) This function initializes an Hmac object, setting its encryption type, key and HMAC length.
int	wc_HmacUpdate(Hmac * hmac, const byte * in, word32 sz) This function updates the message to authenticate using HMAC. It should be called after the Hmac object has been initialized with wc_HmacSetKey. This function may be called multiple times to update the message to hash. After calling wc_HmacUpdate as desired, one should call wc_HmacFinal to obtain the final authenticated message tag.
int	wc_HmacFinal(Hmac * hmac, byte * out) This function computes the final hash of an Hmac object's message.
int	wolfSSL_GetHmacMaxSize(void ) This function returns the largest HMAC digest size available based on the configured cipher suites.
int	wc_HKDF(int type, const byte * inKey, word32 inKeySz, const byte * salt, word32 saltSz, const byte * info, word32 infoSz, byte * out, word32 outSz) This function provides access to a HMAC Key Derivation Function (HKDF). It utilizes HMAC to convert inKey, with an optional salt and optional info into a derived key, which it stores in out. The hash type defaults to MD5 if 0 or NULL is given.
int	wc_HKDF_Extract(int type, const byte * salt, word32 saltSz, const byte * inKey, word32 inKeySz, byte * out) This function provides access to a HMAC Key Derivation Function (HKDF). It utilizes HMAC to convert inKey, with an optional salt into a derived key, which it stores in out. The hash type defaults to MD5 if 0 or NULL is given.
int	wc_HKDF_Extract_ex(int type, const byte * salt, word32 saltSz, const byte * inKey, word32 inKeySz, byte * out, void * heap, int devId) This function provides access to a HMAC Key Derivation Function (HKDF). It utilizes HMAC to convert inKey, with an optional salt into a derived key, which it stores in out. The hash type defaults to MD5 if 0 or NULL is given. This is the _ex version adding heap hint and device identifier.
int	wc_HKDF_Expand(int type, const byte * inKey, word32 inKeySz, const byte * info, word32 infoSz, byte * out, word32 outSz) This function provides access to a HMAC Key Derivation Function (HKDF). It utilizes HMAC to convert inKey, with optional info into a derived key, which it stores in out. The hash type defaults to MD5 if 0 or NULL is given.
int	wc_HKDF_Expand_ex(int type, const byte * inKey, word32 inKeySz, const byte * info, word32 infoSz, byte * out, word32 outSz, void * heap, int devId) This function provides access to a HMAC Key Derivation Function (HKDF). It utilizes HMAC to convert inKey, with optional info into a derived key, which it stores in out. The hash type defaults to MD5 if 0 or NULL is given. This is the _ex version adding heap hint and device identifier.
int	wc_Tls13_HKDF_Extract(byte * prk, const byte * salt, word32 saltLen, byte * ikm, word32 ikmLen, int digest) This function provides access to RFC 5869 HMAC_based Extract_and_Expand Key Derivation Function (HKDF) for TLS v1.3 key derivation.
int	wc_Tls13_HKDF_Extract_ex(byte * prk, const byte * salt, word32 saltLen, byte * ikm, word32 ikmLen, int digest, void * heap, int devId) This function provides access to RFC 5869 HMAC_based Extract_and_Expand Key Derivation Function (HKDF) for TLS v1.3 key derivation. This is the _ex version adding heap hint and device identifier.
int	wc_Tls13_HKDF_Expand_Label_ex(byte * okm, word32 okmLen, const byte * prk, word32 prkLen, const byte * protocol, word32 protocolLen, const byte * label, word32 labelLen, const byte * info, word32 infoLen, int digest, void * heap, int devId) Expand data using HMAC, salt and label and info. TLS v1.3 defines this function for key derivation. This is the _ex version adding heap hint and device identifier.
int	wc_Tls13_HKDF_Expand_Label(byte * okm, word32 okmLen, const byte * prk, word32 prkLen, const byte * protocol, word32 protocolLen, const byte * label, word32 labelLen, const byte * info, word32 infoLen, int digest) Expand data using HMAC, salt and label and info. TLS v1.3 defines this function for key derivation. This is the _ex version adding heap hint and device identifier.
int	wc_Tls13_HKDF_Expand_Label_Alloc(byte * okm, word32 okmLen, const byte * prk, word32 prkLen, const byte * protocol, word32 protocolLen, const byte * label, word32 labelLen, const byte * info, word32 infoLen, int digest, void * heap) This functions is very similar to wc_Tls13_HKDF_Expand_Label(), but it allocates memory if the stack space usually used isn't enough. Expand data using HMAC, salt and label and info. TLS v1.3 defines this function for key derivation. This is the _ex version adding heap hint and device identifier.

Functions Documentation

function wc_HmacSetKey

int wc_HmacSetKey(
    Hmac * hmac,
    int type,
    const byte * key,
    word32 keySz
)

This function initializes an Hmac object, setting its encryption type, key and HMAC length.

Parameters:

hmac pointer to the Hmac object to initialize
type type specifying which encryption method the Hmac object should use. Valid options are: WC_MD5, WC_SHA, WC_SHA256, WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or WC_SHA3_512
key pointer to a buffer containing the key with which to initialize the Hmac object
length length of the key

See:

Return:

0 Returned on successfully initializing the Hmac object
BAD_FUNC_ARG Returned if the input type is invalid (see type param)
MEMORY_E Returned if there is an error allocating memory for the structure to use for hashing
HMAC_MIN_KEYLEN_E Returned when using a FIPS implementation and the key length specified is shorter than the minimum acceptable FIPS standard of 14 bytes

Example

Hmac hmac;
byte key[] = { // initialize with key to use for encryption };
if (wc_HmacSetKey(&hmac, WC_MD5, key, sizeof(key)) != 0) {
    // error initializing Hmac object
}

function wc_HmacUpdate

int wc_HmacUpdate(
    Hmac * hmac,
    const byte * in,
    word32 sz
)

This function updates the message to authenticate using HMAC. It should be called after the Hmac object has been initialized with wc_HmacSetKey. This function may be called multiple times to update the message to hash. After calling wc_HmacUpdate as desired, one should call wc_HmacFinal to obtain the final authenticated message tag.

Parameters:

hmac pointer to the Hmac object for which to update the message
msg pointer to the buffer containing the message to append
length length of the message to append

See:

Return:

0 Returned on successfully updating the message to authenticate
MEMORY_E Returned if there is an error allocating memory for use with a hashing algorithm

Example

Hmac hmac;
byte msg[] = { // initialize with message to authenticate };
byte msg2[] = { // initialize with second half of message };
// initialize hmac
if( wc_HmacUpdate(&hmac, msg, sizeof(msg)) != 0) {
    // error updating message
}
if( wc_HmacUpdate(&hmac, msg2, sizeof(msg)) != 0) {
    // error updating with second message
}

function wc_HmacFinal

int wc_HmacFinal(
    Hmac * hmac,
    byte * out
)

This function computes the final hash of an Hmac object's message.

Parameters:

hmac pointer to the Hmac object for which to calculate the final hash
hash pointer to the buffer in which to store the final hash. Should have room available as required by the hashing algorithm chosen

See:

Return:

0 Returned on successfully computing the final hash
MEMORY_E Returned if there is an error allocating memory for use with a hashing algorithm

Example

Hmac hmac;
byte hash[MD5_DIGEST_SIZE];
// initialize hmac with MD5 as type
// wc_HmacUpdate() with messages

if (wc_HmacFinal(&hmac, hash) != 0) {
    // error computing hash
}

function wolfSSL_GetHmacMaxSize

int wolfSSL_GetHmacMaxSize(
    void 
)

This function returns the largest HMAC digest size available based on the configured cipher suites.

Parameters:

none No parameters.

See: none

Return: Success Returns the largest HMAC digest size available based on the configured cipher suites

Example

int maxDigestSz = wolfSSL_GetHmacMaxSize();

function wc_HKDF

int wc_HKDF(
    int type,
    const byte * inKey,
    word32 inKeySz,
    const byte * salt,
    word32 saltSz,
    const byte * info,
    word32 infoSz,
    byte * out,
    word32 outSz
)

This function provides access to a HMAC Key Derivation Function (HKDF). It utilizes HMAC to convert inKey, with an optional salt and optional info into a derived key, which it stores in out. The hash type defaults to MD5 if 0 or NULL is given.

Parameters:

type hash type to use for the HKDF. Valid types are: WC_MD5, WC_SHA, WC_SHA256, WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or WC_SHA3_512
inKey pointer to the buffer containing the key to use for KDF
inKeySz length of the input key
salt pointer to a buffer containing an optional salt. Use NULL instead if not using a salt
saltSz length of the salt. Use 0 if not using a salt
info pointer to a buffer containing optional additional info. Use NULL if not appending extra info
infoSz length of additional info. Use 0 if not using additional info
out pointer to the buffer in which to store the derived key
outSz space available in the output buffer to store the generated key

See: wc_HmacSetKey

Return:

0 Returned upon successfully generating a key with the given inputs
BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
MEMORY_E Returned if there is an error allocating memory
HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation and the key length specified is shorter than the minimum acceptable FIPS standard

The HMAC configure option is –enable-hmac (on by default) or if building sources directly HAVE_HKDF

Example

byte key[] = { // initialize with key };
byte salt[] = { // initialize with salt };
byte derivedKey[MAX_DIGEST_SIZE];

int ret = wc_HKDF(WC_SHA512, key, sizeof(key), salt, sizeof(salt),
NULL, 0, derivedKey, sizeof(derivedKey));
if ( ret != 0 ) {
    // error generating derived key
}

function wc_HKDF_Extract

int wc_HKDF_Extract(
    int type,
    const byte * salt,
    word32 saltSz,
    const byte * inKey,
    word32 inKeySz,
    byte * out
)

This function provides access to a HMAC Key Derivation Function (HKDF). It utilizes HMAC to convert inKey, with an optional salt into a derived key, which it stores in out. The hash type defaults to MD5 if 0 or NULL is given.

Parameters:

type hash type to use for the HKDF. Valid types are: WC_MD5, WC_SHA, WC_SHA256, WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or WC_SHA3_512
salt pointer to a buffer containing an optional salt. Use NULL instead if not using a salt
saltSz length of the salt. Use 0 if not using a salt
inKey pointer to the buffer containing the key to use for KDF
inKeySz length of the input key
out pointer to the buffer in which to store the derived key

See:

Return:

0 Returned upon successfully generating a key with the given inputs
BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
MEMORY_E Returned if there is an error allocating memory
HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation and the key length specified is shorter than the minimum acceptable FIPS standard

The HMAC configure option is –enable-hmac (on by default) or if building sources directly HAVE_HKDF

Example

byte key[] = { // initialize with key };
byte salt[] = { // initialize with salt };
byte derivedKey[MAX_DIGEST_SIZE];

int ret = wc_HKDF_Extract(WC_SHA512, salt, sizeof(salt), key, sizeof(key),
    derivedKey);
if ( ret != 0 ) {
    // error generating derived key
}

function wc_HKDF_Extract_ex

int wc_HKDF_Extract_ex(
    int type,
    const byte * salt,
    word32 saltSz,
    const byte * inKey,
    word32 inKeySz,
    byte * out,
    void * heap,
    int devId
)

This function provides access to a HMAC Key Derivation Function (HKDF). It utilizes HMAC to convert inKey, with an optional salt into a derived key, which it stores in out. The hash type defaults to MD5 if 0 or NULL is given. This is the _ex version adding heap hint and device identifier.

Parameters:

type hash type to use for the HKDF. Valid types are: WC_MD5, WC_SHA, WC_SHA256, WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or WC_SHA3_512
salt pointer to a buffer containing an optional salt. Use NULL instead if not using a salt
saltSz length of the salt. Use 0 if not using a salt
inKey pointer to the buffer containing the key to use for KDF
inKeySz length of the input key
out pointer to the buffer in which to store the derived key
heap heap hint to use for memory. Can be NULL
devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used

See:

Return:

0 Returned upon successfully generating a key with the given inputs
BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
MEMORY_E Returned if there is an error allocating memory
HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation and the key length specified is shorter than the minimum acceptable FIPS standard

The HMAC configure option is –enable-hmac (on by default) or if building sources directly HAVE_HKDF

Example

byte key[] = { // initialize with key };
byte salt[] = { // initialize with salt };
byte derivedKey[MAX_DIGEST_SIZE];

int ret = wc_HKDF_Extract_ex(WC_SHA512, salt, sizeof(salt), key, sizeof(key),
    derivedKey, NULL, INVALID_DEVID);
if ( ret != 0 ) {
    // error generating derived key
}

function wc_HKDF_Expand

int wc_HKDF_Expand(
    int type,
    const byte * inKey,
    word32 inKeySz,
    const byte * info,
    word32 infoSz,
    byte * out,
    word32 outSz
)

This function provides access to a HMAC Key Derivation Function (HKDF). It utilizes HMAC to convert inKey, with optional info into a derived key, which it stores in out. The hash type defaults to MD5 if 0 or NULL is given.

Parameters:

type hash type to use for the HKDF. Valid types are: WC_MD5, WC_SHA, WC_SHA256, WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or WC_SHA3_512
inKey pointer to the buffer containing the key to use for KDF
inKeySz length of the input key
info pointer to a buffer containing optional additional info. Use NULL if not appending extra info
infoSz length of additional info. Use 0 if not using additional info
out pointer to the buffer in which to store the derived key
outSz space available in the output buffer to store the generated key

See:

Return:

0 Returned upon successfully generating a key with the given inputs
BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
MEMORY_E Returned if there is an error allocating memory
HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation and the key length specified is shorter than the minimum acceptable FIPS standard

The HMAC configure option is –enable-hmac (on by default) or if building sources directly HAVE_HKDF

Example

byte key[] = { // initialize with key };
byte salt[] = { // initialize with salt };
byte derivedKey[MAX_DIGEST_SIZE];

int ret = wc_HKDF_Expand(WC_SHA512, key, sizeof(key), NULL, 0,
    derivedKey, sizeof(derivedKey));
if ( ret != 0 ) {
    // error generating derived key
}

function wc_HKDF_Expand_ex

int wc_HKDF_Expand_ex(
    int type,
    const byte * inKey,
    word32 inKeySz,
    const byte * info,
    word32 infoSz,
    byte * out,
    word32 outSz,
    void * heap,
    int devId
)

This function provides access to a HMAC Key Derivation Function (HKDF). It utilizes HMAC to convert inKey, with optional info into a derived key, which it stores in out. The hash type defaults to MD5 if 0 or NULL is given. This is the _ex version adding heap hint and device identifier.

Parameters:

type hash type to use for the HKDF. Valid types are: WC_MD5, WC_SHA, WC_SHA256, WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or WC_SHA3_512
inKey pointer to the buffer containing the key to use for KDF
inKeySz length of the input key
info pointer to a buffer containing optional additional info. Use NULL if not appending extra info
infoSz length of additional info. Use 0 if not using additional info
out pointer to the buffer in which to store the derived key
outSz space available in the output buffer to store the generated key
heap heap hint to use for memory. Can be NULL
devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used

See:

Return:

0 Returned upon successfully generating a key with the given inputs
BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
MEMORY_E Returned if there is an error allocating memory
HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation and the key length specified is shorter than the minimum acceptable FIPS standard

The HMAC configure option is –enable-hmac (on by default) or if building sources directly HAVE_HKDF

Example

byte key[] = { // initialize with key };
byte salt[] = { // initialize with salt };
byte derivedKey[MAX_DIGEST_SIZE];

int ret = wc_HKDF_Expand_ex(WC_SHA512, key, sizeof(key), NULL, 0,
    derivedKey, sizeof(derivedKey), NULL, INVALID_DEVID);
if ( ret != 0 ) {
    // error generating derived key
}

function wc_Tls13_HKDF_Extract

int wc_Tls13_HKDF_Extract(
    byte * prk,
    const byte * salt,
    word32 saltLen,
    byte * ikm,
    word32 ikmLen,
    int digest
)

This function provides access to RFC 5869 HMAC-based Extract-and-Expand Key Derivation Function (HKDF) for TLS v1.3 key derivation.

Parameters:

prk Generated pseudorandom key
salt salt.
saltLen length of the salt
ikm pointer to putput for keying material
ikmLen length of the input keying material buffer
digest hash type to use for the HKDF. Valid types are: WC_SHA256, WC_SHA384 or WC_SHA512

See:

Return:

0 Returned upon successfully generating a key with the given inputs
BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
MEMORY_E Returned if there is an error allocating memory
HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation and the key length specified is shorter than the minimum acceptable FIPS standard

Example

byte secret[] = { // initialize with random key };
byte salt[] = { // initialize with optional salt };
byte masterSecret[MAX_DIGEST_SIZE];

int ret = wc_Tls13_HKDF_Extract(secret, salt, sizeof(salt), 0,
    masterSecret, sizeof(masterSecret), WC_SHA512);
if ( ret != 0 ) {
    // error generating derived key
}

function wc_Tls13_HKDF_Extract_ex

int wc_Tls13_HKDF_Extract_ex(
    byte * prk,
    const byte * salt,
    word32 saltLen,
    byte * ikm,
    word32 ikmLen,
    int digest,
    void * heap,
    int devId
)

This function provides access to RFC 5869 HMAC-based Extract-and-Expand Key Derivation Function (HKDF) for TLS v1.3 key derivation. This is the _ex version adding heap hint and device identifier.

Parameters:

prk Generated pseudorandom key
salt Salt.
saltLen Length of the salt
ikm Pointer to output for keying material
ikmLen Length of the input keying material buffer
digest Hash type to use for the HKDF. Valid types are: WC_SHA256, WC_SHA384 or WC_SHA512
heap Heap hint to use for memory. Can be NULL
devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used

See:

Return:

0 Returned upon successfully generating a key with the given inputs
BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
MEMORY_E Returned if there is an error allocating memory
HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation and the key length specified is shorter than the minimum acceptable FIPS standard

Example

byte secret[] = { // initialize with random key };
byte salt[] = { // initialize with optional salt };
byte masterSecret[MAX_DIGEST_SIZE];

int ret = wc_Tls13_HKDF_Extract_ex(secret, salt, sizeof(salt), 0,
    masterSecret, sizeof(masterSecret), WC_SHA512, NULL, INVALID_DEVID);
if ( ret != 0 ) {
    // error generating derived key
}

function wc_Tls13_HKDF_Expand_Label_ex

int wc_Tls13_HKDF_Expand_Label_ex(
    byte * okm,
    word32 okmLen,
    const byte * prk,
    word32 prkLen,
    const byte * protocol,
    word32 protocolLen,
    const byte * label,
    word32 labelLen,
    const byte * info,
    word32 infoLen,
    int digest,
    void * heap,
    int devId
)

Expand data using HMAC, salt and label and info. TLS v1.3 defines this function for key derivation. This is the _ex version adding heap hint and device identifier.

Parameters:

okm Generated pseudorandom key - output key material.
okmLen Length of generated pseudorandom key - output key material.
prk Salt - pseudo-random key.
prkLen Length of the salt - pseudo-random key.
protocol TLS protocol label.
protocolLen Length of the TLS protocol label.
info Information to expand.
infoLen Length of the information.
digest Hash type to use for the HKDF. Valid types are: WC_SHA256, WC_SHA384 or WC_SHA512
heap Heap hint to use for memory. Can be NULL
devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used

See:

Return:

0 Returned upon successfully generating a key with the given inputs
BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
MEMORY_E Returned if there is an error allocating memory
HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation and the key length specified is shorter than the minimum acceptable FIPS standard

function wc_Tls13_HKDF_Expand_Label

int wc_Tls13_HKDF_Expand_Label(
    byte * okm,
    word32 okmLen,
    const byte * prk,
    word32 prkLen,
    const byte * protocol,
    word32 protocolLen,
    const byte * label,
    word32 labelLen,
    const byte * info,
    word32 infoLen,
    int digest
)

Expand data using HMAC, salt and label and info. TLS v1.3 defines this function for key derivation. This is the _ex version adding heap hint and device identifier.

Parameters:

okm Generated pseudorandom key - output key material.
okmLen Length of generated pseudorandom key - output key material.
prk Salt - pseudo-random key.
prkLen Length of the salt - pseudo-random key.
protocol TLS protocol label.
protocolLen Length of the TLS protocol label.
info Information to expand.
infoLen Length of the information.
digest Hash type to use for the HKDF. Valid types are: WC_SHA256, WC_SHA384 or WC_SHA512

See:

Return:

0 Returned upon successfully generating a key with the given inputs
BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
MEMORY_E Returned if there is an error allocating memory
HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation and the key length specified is shorter than the minimum acceptable FIPS standard

function wc_Tls13_HKDF_Expand_Label_Alloc

int wc_Tls13_HKDF_Expand_Label_Alloc(
    byte * okm,
    word32 okmLen,
    const byte * prk,
    word32 prkLen,
    const byte * protocol,
    word32 protocolLen,
    const byte * label,
    word32 labelLen,
    const byte * info,
    word32 infoLen,
    int digest,
    void * heap
)

This functions is very similar to wc_Tls13_HKDF_Expand_Label(), but it allocates memory if the stack space usually used isn't enough. Expand data using HMAC, salt and label and info. TLS v1.3 defines this function for key derivation. This is the _ex version adding heap hint and device identifier.

Parameters:

okm Generated pseudorandom key - output key material.
okmLen Length of generated pseudorandom key - output key material.
prk Salt - pseudo-random key.
prkLen Length of the salt - pseudo-random key.
protocol TLS protocol label.
protocolLen Length of the TLS protocol label.
info Information to expand.
infoLen Length of the information.
digest Hash type to use for the HKDF. Valid types are: WC_SHA256, WC_SHA384 or WC_SHA512
heap Heap hint to use for memory. Can be NULL

See:

Return:

0 Returned upon successfully generating a key with the given inputs
BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
MEMORY_E Returned if there is an error allocating memory
HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation and the key length specified is shorter than the minimum acceptable FIPS standard

Updated on 2024-11-22 at 01:12:39 +0000