Algorithms - HMAC

Functions
WOLFSSL_API int	wc_HmacSetKey (Hmac *, int type, const byte *key, word32 keySz)
	This function initializes an Hmac object, setting its encryption type, key and HMAC length.
WOLFSSL_API int	wc_HmacUpdate (Hmac *, const byte *, word32)
	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.
WOLFSSL_API int	wc_HmacFinal (Hmac *, byte *)
	This function computes the final hash of an Hmac object's message.
WOLFSSL_API int	wolfSSL_GetHmacMaxSize (void)
	This function returns the largest HMAC digest size available based on the configured cipher suites.
WOLFSSL_API 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.

Detailed Description

Function Documentation

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.

Returns

0 Returned upon successfully generating a key with the given inputs

BAD_FUNC_ARG Returned if an invalid hash type is given as argument. Valid types are: MD5, SHA, SHA256, SHA384, SHA512, SHA3-224, SHA3-256, SHA3-384, SHA3-512

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

Parameters

type	hash type to use for the HKDF. Valid types are: MD5, SHA, SHA256, SHA384, SHA512, SHA3-224, SHA3-256, SHA3-384, 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

Example

byte key[] = { // initialize with key };
byte salt[] = { // initialize with salt };
byte derivedKey[MAX_DIGEST_SIZE];
 
int ret = wc_HKDF(SHA512, key, sizeof(key), salt, sizeof(salt),
NULL, 0, derivedKey, sizeof(derivedKey));
if ( ret != 0 ) {
    // error generating derived key
}

See also

wc_HmacSetKey

wc_HmacFinal()

int wc_HmacFinal	(	Hmac *	hmac,
		byte *	hash )

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

Returns

0 Returned on successfully computing the final hash

MEMORY_E Returned if there is an error allocating memory for use with a hashing algorithm

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

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
}

See also

wc_HmacSetKey

wc_HmacUpdate

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.

Returns

0 Returned on successfully initializing the Hmac object

BAD_FUNC_ARG Returned if the input type is invalid. Valid options are: MD5, SHA, SHA256, SHA384, SHA512, SHA3-224, SHA3-256, SHA3-384, SHA3-512

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

Parameters

hmac	pointer to the Hmac object to initialize
type	type specifying which encryption method the Hmac object should use. Valid options are: MD5, SHA, SHA256, SHA384, SHA512, SHA3-224, SHA3-256, SHA3-384, SHA3-512
key	pointer to a buffer containing the key with which to initialize the Hmac object
length	length of the key

Example

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

See also

wc_HmacUpdate

wc_HmacFinal

wc_HmacUpdate()

int wc_HmacUpdate	(	Hmac *	hmac,
		const byte *	msg,
		word32	length )

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.

Returns

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

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

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
}

See also

wc_HmacSetKey

wc_HmacFinal

wolfSSL_GetHmacMaxSize()

int wolfSSL_GetHmacMaxSize

(

void

)

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

Returns

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

Parameters

none	No parameters.

Example

int maxDigestSz = wolfSSL_GetHmacMaxSize();

See also

none