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:
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
}
Updated on 2023-09-21 at 01:14:17 +0000