Algorithm - CMAC

Functions

	Name
int	wc_InitCmac(Cmac * cmac, const byte * key, word32 keySz, int type, void * unused) Initialize the Cmac structure with defaults.
int	wc_InitCmac_ex(Cmac * cmac, const byte * key, word32 keySz, int type, void * unused, void * heap, int devId) Initialize the Cmac structure with defaults.
int	wc_CmacUpdate(Cmac * cmac, const byte * in, word32 inSz) Add Cipher-based Message Authentication Code input data.
int	wc_CmacFinalNoFree(Cmac * cmac, byte * out, word32 * outSz) Generate the final result using Cipher-based Message Authentication Code, deferring context cleanup.
int	wc_CmacFinal(Cmac * cmac, byte * out, word32 * outSz) Generate the final result using Cipher_based Message Authentication Code, and clean up the context with wc_CmacFree().
int	wc_CmacFree(Cmac * cmac) Clean up allocations in a CMAC context.
int	wc_AesCmacGenerate(byte * out, word32 * outSz, const byte * in, word32 inSz, const byte * key, word32 keySz) Single shot function for generating a CMAC.
int	wc_AesCmacVerify(const byte * check, word32 checkSz, const byte * in, word32 inSz, const byte * key, word32 keySz) Single shot function for validating a CMAC.
int	wc_CMAC_Grow(Cmac * cmac, const byte * in, int inSz) Only used with WOLFSSL_HASH_KEEP when hardware requires single-shot and the updates must be cached in memory.
int	wc_AesCmacGenerate_ex(Cmac * cmac, byte * out, word32 * outSz, const byte * in, word32 inSz, const byte * key, word32 keySz, void * heap, int devId) Single shot AES-CMAC generation with extended parameters including heap and device ID.
int	wc_AesCmacVerify_ex(Cmac * cmac, const byte * check, word32 checkSz, const byte * in, word32 inSz, const byte * key, word32 keySz, void * heap, int devId) Single shot AES-CMAC verification with extended parameters including heap and device ID.

Functions Documentation

function wc_InitCmac

int wc_InitCmac(
    Cmac * cmac,
    const byte * key,
    word32 keySz,
    int type,
    void * unused
)

Initialize the Cmac structure with defaults.

Parameters:

cmac pointer to the Cmac structure
key key pointer
keySz size of the key pointer (16, 24 or 32)
type Always WC_CMAC_AES = 1
unused not used, exists for potential future use around compatibility

See:

Return: 0 on success

Example

Cmac cmac[1];
ret = wc_InitCmac(cmac, key, keySz, WC_CMAC_AES, NULL);
if (ret == 0) {
    ret = wc_CmacUpdate(cmac, in, inSz);
}
if (ret == 0) {
    ret = wc_CmacFinal(cmac, out, outSz);
}

function wc_InitCmac_ex

int wc_InitCmac_ex(
    Cmac * cmac,
    const byte * key,
    word32 keySz,
    int type,
    void * unused,
    void * heap,
    int devId
)

Initialize the Cmac structure with defaults.

Parameters:

cmac pointer to the Cmac structure
key key pointer
keySz size of the key pointer (16, 24 or 32)
type Always WC_CMAC_AES = 1
unused not used, exists for potential future use around compatibility
heap pointer to the heap hint used for dynamic allocation. Typically used with our static memory option. Can be NULL.
devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used

See:

Return: 0 on success

Example

Cmac cmac[1];
ret = wc_InitCmac_ex(cmac, key, keySz, WC_CMAC_AES, NULL, NULL, INVALID_DEVID);
if (ret == 0) {
    ret = wc_CmacUpdate(cmac, in, inSz);
}
if (ret == 0) {
    ret = wc_CmacFinal(cmac, out, &outSz);
}

function wc_CmacUpdate

int wc_CmacUpdate(
    Cmac * cmac,
    const byte * in,
    word32 inSz
)

Add Cipher-based Message Authentication Code input data.

Parameters:

cmac pointer to the Cmac structure
in input data to process
inSz size of input data

See:

Return: 0 on success

Example

ret = wc_CmacUpdate(cmac, in, inSz);

function wc_CmacFinalNoFree

int wc_CmacFinalNoFree(
    Cmac * cmac,
    byte * out,
    word32 * outSz
)

Generate the final result using Cipher-based Message Authentication Code, deferring context cleanup.

Parameters:

cmac pointer to the Cmac structure
out pointer to return the result
outSz pointer size of output (in/out)

See:

Return: 0 on success

Example

ret = wc_CmacFinalNoFree(cmac, out, &outSz);
(void)wc_CmacFree(cmac);

function wc_CmacFinal

int wc_CmacFinal(
    Cmac * cmac,
    byte * out,
    word32 * outSz
)

Generate the final result using Cipher-based Message Authentication Code, and clean up the context with wc_CmacFree().

Parameters:

cmac pointer to the Cmac structure
out pointer to return the result
outSz pointer size of output (in/out)

See:

Return: 0 on success

Example

ret = wc_CmacFinal(cmac, out, &outSz);

function wc_CmacFree

int wc_CmacFree(
    Cmac * cmac
)

Clean up allocations in a CMAC context.

Parameters:

cmac pointer to the Cmac structure

See:

Return: 0 on success

Example

ret = wc_CmacFinalNoFree(cmac, out, &outSz);
(void)wc_CmacFree(cmac);

function wc_AesCmacGenerate

int wc_AesCmacGenerate(
    byte * out,
    word32 * outSz,
    const byte * in,
    word32 inSz,
    const byte * key,
    word32 keySz
)

Single shot function for generating a CMAC.

Parameters:

out pointer to return the result
outSz pointer size of output (in/out)
in input data to process
inSz size of input data
key key pointer
keySz size of the key pointer (16, 24 or 32)

See: wc_AesCmacVerify

Return: 0 on success

Example

ret = wc_AesCmacGenerate(mac, &macSz, msg, msgSz, key, keySz);

function wc_AesCmacVerify

int wc_AesCmacVerify(
    const byte * check,
    word32 checkSz,
    const byte * in,
    word32 inSz,
    const byte * key,
    word32 keySz
)

Single shot function for validating a CMAC.

Parameters:

check CMAC value to verify
checkSz size of check buffer
in input data to process
inSz size of input data
key key pointer
keySz size of the key pointer (16, 24 or 32)

See: wc_AesCmacGenerate

Return: 0 on success

Example

ret = wc_AesCmacVerify(mac, macSz, msg, msgSz, key, keySz);

function wc_CMAC_Grow

int wc_CMAC_Grow(
    Cmac * cmac,
    const byte * in,
    int inSz
)

Only used with WOLFSSL_HASH_KEEP when hardware requires single-shot and the updates must be cached in memory.

Parameters:

in input data to process
inSz size of input data

Return: 0 on success

Example

ret = wc_CMAC_Grow(cmac, in, inSz)

function wc_AesCmacGenerate_ex

int wc_AesCmacGenerate_ex(
    Cmac * cmac,
    byte * out,
    word32 * outSz,
    const byte * in,
    word32 inSz,
    const byte * key,
    word32 keySz,
    void * heap,
    int devId
)

Single shot AES-CMAC generation with extended parameters including heap and device ID.

Parameters:

cmac Pointer to Cmac structure (can be NULL for one-shot)
out Buffer to store MAC output
outSz Pointer to output size (in/out)
in Input data to authenticate
inSz Length of input data
key AES key
keySz Key size (16, 24, or 32 bytes)
heap Heap hint for memory allocation (can be NULL)
devId Device ID for hardware acceleration (use INVALID_DEVID for software)

See:

Return:

0 on success
BAD_FUNC_ARG if parameters are invalid

Example

byte mac[AES_BLOCK_SIZE];
word32 macSz = sizeof(mac);
byte key[16], msg[64];

int ret = wc_AesCmacGenerate_ex(NULL, mac, &macSz, msg,
                                sizeof(msg), key, sizeof(key),
                                NULL, INVALID_DEVID);

function wc_AesCmacVerify_ex

int wc_AesCmacVerify_ex(
    Cmac * cmac,
    const byte * check,
    word32 checkSz,
    const byte * in,
    word32 inSz,
    const byte * key,
    word32 keySz,
    void * heap,
    int devId
)

Single shot AES-CMAC verification with extended parameters including heap and device ID.

Parameters:

cmac Pointer to Cmac structure (can be NULL for one-shot)
check Expected MAC value to verify
checkSz Size of expected MAC
in Input data to authenticate
inSz Length of input data
key AES key
keySz Key size (16, 24, or 32 bytes)
heap Heap hint for memory allocation (can be NULL)
devId Device ID for hardware acceleration (use INVALID_DEVID for software)

See:

Return:

0 on success
BAD_FUNC_ARG if parameters are invalid
MAC_CMP_FAILED_E if MAC verification fails

Example

byte mac[AES_BLOCK_SIZE];
byte key[16], msg[64];

int ret = wc_AesCmacVerify_ex(NULL, mac, sizeof(mac), msg,
                              sizeof(msg), key, sizeof(key),
                              NULL, INVALID_DEVID);
if (ret == MAC_CMP_FAILED_E) {
    // MAC verification failed
}

Updated on 2025-12-31 at 01:16:03 +0000