hmac.h

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:

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:

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

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
}

Source code


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

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

int wc_HmacFinal(Hmac* hmac, byte* out);

int wolfSSL_GetHmacMaxSize(void);

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

Updated on 2023-11-01 at 01:22:35 +0000