1. CMOX_MAC ¶

1.1. CMOX MAC PUBLIC METHODS ¶

group CMOX_MAC_PUBLIC_METHODS

Functions

cmox_mac_retval_t cmox_mac_cleanup ( cmox_mac_handle_t * P_pThis )

Cleanup the MAC handler.

Parameters :: P_pThis – MAC handler to cleanup
Returns :: cmox_mac_retval_t MAC return value

cmox_mac_retval_t cmox_mac_init ( cmox_mac_handle_t * P_pThis )

Initialize the MAC handle based on the selected algorithm.

Note

The MAC handle must be derived from an algorithm-specific handle using the correct construct

Parameters :: P_pThis – MAC handle to initialize
Returns :: cmox_mac_retval_t Hash return value

cmox_mac_retval_t cmox_mac_setTagLen ( cmox_mac_handle_t * P_pThis , size_t P_tagLen )

Set the size of the tag.

Note

This function is optional when used for HMAC or CMAC algorithms. If not called, the tag length will be set as the default specified by the algorithm (e.g. 16 bytes for CMAC) during the initialization phase.

Note

With KMAC algorithm, this function is mandatory and must be called before the cmox_mac_setKey function

Parameters :

P_pThis – MAC handle to set
P_tagLen – Size in bytes of the tag

Returns :

cmox_mac_retval_t MAC return value

cmox_mac_retval_t cmox_mac_setCustomData ( cmox_mac_handle_t * P_pThis , const uint8_t * P_pCustomData , size_t P_customDataLen )

Set the custom data to be combined with the plaintext for the MAC computation.

Note

This function is useful only for KMAC algorithm. It can be called for other algorithms but will not produce any results

Note

If the KMAC to compute doesn’t need any custom data, this function can be skipped.

Parameters :

P_pThis – MAC handle to use for computing the authenticated tag
P_pCustomData – Buffer of bytes containing the custom data
P_customDataLen – Size in bytes of the custom data

Returns :

cmox_mac_retval_t MAC return value

cmox_mac_retval_t cmox_mac_setKey ( cmox_mac_handle_t * P_pThis , const uint8_t * P_pKey , size_t P_keyLen )

Set the key to be used for computing the authenticated tag.

Note

The KMAC algorithm is specified to be used even without key. However, this function is mandatory to be called with the parameter P_keyLen set to 0.

Parameters :

P_pThis – MAC handle to use for computing the authenticated tag
P_pKey – Buffer of bytes containing the key
P_keyLen – Size in bytes of the key

Returns :

cmox_mac_retval_t MAC return value

cmox_mac_retval_t cmox_mac_append ( cmox_mac_handle_t * P_pThis , const uint8_t * P_pInput , size_t P_inputLen )

Append part or the totality of the plaintext to the MAC handle.

Parameters :

P_pThis – MAC handle to use for computing the authenticated tag
P_pInput – Buffer of bytes containing the data to append
P_inputLen – Size in bytes of the data to append

Returns :

cmox_hash_retval_t MAC return value

cmox_mac_retval_t cmox_mac_generateTag ( cmox_mac_handle_t * P_pThis , uint8_t * P_pTag , size_t * P_pTagLen )

Compute the authenticated tag of the already appended data.

Parameters :

P_pThis – MAC handle where the data has been appended
P_pTag – Buffer of bytes where the authenticated tag will be stored
P_pTagLen – Number of bytes generated by the function. It is an optional parameter and can be set to NULL if not needed.

Returns :

cmox_mac_retval_t MAC return value

cmox_mac_retval_t cmox_mac_verifyTag ( cmox_mac_handle_t * P_pThis , const uint8_t * P_pTag , uint32_t * P_pFaultCheck )

Verify the already appended data with the reference tag.

Note

P_pFaultCheck value, if the parameter is provided, MUST be checked to be equal to the retval, and both MUST be equal to the successful value. P_pFaultCheck MUST be checked only if the main result is successful, and has no relevance if the main result is not successful. Every comparison (both for the return value and for P_pFaultCheck) must be done against the success value, and not comparing the value with the failure value. Indeed, in presence of faults, especially P_pFaultCheck, could be a dirty value.

Parameters :

P_pThis – MAC handle where the data has been appended
P_pTag – Buffer of bytes containing the reference tag
P_pFaultCheck – Optional value to check, together with the retval, to verify if some fault happened

Returns :

cmox_mac_retval_t

cmox_mac_retval_t cmox_mac_compute ( cmox_mac_algo_t P_algo , const uint8_t * P_pInput , size_t P_inputLen , const uint8_t * P_pKey , size_t P_keyLen , const uint8_t * P_pCustomData , size_t P_customDataLen , uint8_t * P_pTag , size_t P_expectedTagLen , size_t * P_pComputedTagLen )

Compute the authenticated tag of a message using a MAC algorithm.

Parameters :

P_algo – Identifier of the hash algorithm to use for the computation. This parameter can be one of the following:
- CMOX_CMAC_AES_ALGO
- CMOX_HMAC_SHA1_ALGO
- CMOX_HMAC_SHA224_ALGO
- CMOX_HMAC_SHA256_ALGO
- CMOX_HMAC_SHA384_ALGO
- CMOX_HMAC_SHA512_ALGO
- CMOX_HMAC_SHA512_224_ALGO
- CMOX_HMAC_SHA512_256_ALGO
- CMOX_HMAC_SM3_ALGO
- CMOX_KMAC_128_ALGO
- CMOX_KMAC_256_ALGO
P_pInput – Buffer of bytes containing the message to process
P_inputLen – Size in bytes of the message to process
P_pKey – Buffer of bytes containing the key
P_keyLen – Size in bytes of the key
P_pCustomData – Buffer of bytes containing the custom data
P_customDataLen – Size in bytes of the custom data
P_pTag – Buffer of bytes where the authenticated tag will be stored
P_expectedTagLen – Size in bytes of the tag to compute
P_pComputedTagLen – Number of bytes generated by the function. It is an optional parameter and can be set to NULL if not needed.

Returns :

cmox_mac_retval_t

cmox_mac_retval_t cmox_mac_verify ( cmox_mac_algo_t P_algo , const uint8_t * P_pInput , size_t P_inputLen , const uint8_t * P_pKey , size_t P_keyLen , const uint8_t * P_pCustomData , size_t P_customDataLen , const uint8_t * P_pReceivedTag , size_t P_receivedTagLen )

Verify the authenticity of a message using a MAC algorithm.

Parameters :

P_algo – Identifier of the hash algorithm to use for the computation. This parameter can be one of the following:
- CMOX_CMAC_AES_ALGO
- CMOX_HMAC_SHA1_ALGO
- CMOX_HMAC_SHA224_ALGO
- CMOX_HMAC_SHA256_ALGO
- CMOX_HMAC_SHA384_ALGO
- CMOX_HMAC_SHA512_ALGO
- CMOX_HMAC_SHA512_224_ALGO
- CMOX_HMAC_SHA512_256_ALGO
- CMOX_HMAC_SM3_ALGO
- CMOX_KMAC_128_ALGO
- CMOX_KMAC_256_ALGO
P_pInput – Buffer of bytes containing the message to process
P_inputLen – Size in bytes of the message to process
P_pKey – Buffer of bytes containing the key
P_keyLen – Size in bytes of the key
P_pCustomData – Buffer of bytes containing the custom data
P_customDataLen – Size in bytes of the custom data
P_pReceivedTag – Buffer of bytes containing the received tag
P_receivedTagLen – Size in bytes of the received tag

Returns :

cmox_mac_retval_t

1.2. CMOX MAC PUBLIC TYPES ¶

group CMOX_MAC_PUBLIC_TYPES

Typedefs

typedef const struct cmox_mac_vtableStruct_st * cmox_mac_vtable_t

MAC Virtual Table.

This type specifies a pointer to the virtual table containing the methods for a particular algorithm (e.g. HMAC-256 or CMAC)

typedef const struct cmox_mac_algoStruct_st * cmox_mac_algo_t

MAC algorithm type.

This type specifies the algorithm to use with the MAC module (e.g. HMAC-SHA256). The type is defined as a pointer to a structure, that contains the functions for the specific algorithm, defined in the library internally

struct cmox_mac_handle_t: #include <cmox_mac.h>

MAC handle structure definition.