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.

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:

• wc_HmacUpdate
• wc_HmacFinal

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 May be returned when using a FIPS implementation and the key length specified is shorter than the minimum acceptable FIPS standard

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:

• wc_HmacSetKey
• wc_HmacFinal

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:

• wc_HmacSetKey
• wc_HmacUpdate

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

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
}

---

Updated on 2023-03-30 at 08:31:17 +0000