Skip to content

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 2022-12-06 at 08:30:53 +0000