Functions
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. More...
 
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. More...
 
WOLFSSL_API int wc_HmacFinal (Hmac *, byte *)
 This function computes the final hash of an Hmac object's message. More...
 
WOLFSSL_API int wolfSSL_GetHmacMaxSize (void)
 This function returns the largest HMAC digest size available based on the configured cipher suites. More...
 
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. More...
 

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, BLAKE2B_ID
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
typehash type to use for the HKDF. Valid types are: MD5, SHA, SHA256, SHA384, SHA512, BLAKE2B_ID
inKeypointer to the buffer containing the key to use for KDF
inKeySzlength of the input key
saltpointer to a buffer containing an optional salt. Use NULL instead if not using a salt
saltSzlength of the salt. Use 0 if not using a salt
infopointer to a buffer containing optional additional info. Use NULL if not appending extra info
infoSzlength of additional info. Use 0 if not using additional info
outpointer to the buffer in which to store the derived key
outSzspace 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
hmacpointer to the Hmac object for which to calculate the final hash
hashpointer 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, BLAKE2B_ID
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
hmacpointer to the Hmac object to initialize
typetype specifying which encryption method the Hmac object should use. Valid options are: MD5, SHA, SHA256, SHA384, SHA512, BLAKE2B_ID
keypointer to a buffer containing the key with which to initialize the Hmac object
lengthlength 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
hmacpointer to the Hmac object for which to update the message
msgpointer to the buffer containing the message to append
lengthlength 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
noneNo parameters.

Example

int maxDigestSz = wolfSSL_GetHmacMaxSize();
See also
none