AESCMAC (CMAC and CBC-MAC) driver header.
The Cipher-based Message Authentication Code (CMAC) and Cipher Block Chaining Message Authentication Code (CBC-MAC) are generic block cipher modes of operation. They can be used with any block cipher but this driver implementation uses AES.
Both CMAC and CBC-MAC create a message authentication code from a message of any practical length to provide authenticity and integrity assurances. CMAC is recommended over CBC-MAC because CBC-MAC is not secure for variable length messages.
CBC-MAC is only secure for fixed-length messages. Any single key must only be used for messages of a fixed and known length. The CMAC algorithm, which is based on a variation of CBC-MAC at its core, was developed to address that security deficiency and is the MAC algorithm recommended by NIST.
Before starting a CMAC operation, the application must do the following:
The AESCMAC_oneStepSign and AESCMAC_oneStepVerify functions perform a CMAC operation in a single call. They will always be the most highly optimized routines with the least overhead and the fastest runtime. However, they require all plaintext or ciphertext to be available to the function at the start of the call. All devices support single call operations.
After the CMAC operation completes, the application should either start another operation or close the driver by calling AESCMAC_close().
### Single call CMAC authentication with plaintext CryptoKey in blocking return mode #
### Single call CMAC verification with plaintext CryptoKey in callback return mode #
### Multi-step CMAC signature with plaintext CryptoKey in blocking return mode #
Before starting a CBC-MAC operation, the application must do the following:
The AESCMAC_oneStepSign and AESCMAC_oneStepVerify functions perform a CBC-MAC operation in a single call. They will always be the most highly optimized routines with the least overhead and the fastest runtime. However, they require all plaintext or ciphertext to be available to the function at the start of the call. All devices support single call operations.
After the CBC-MAC operation completes, the application should either start another operation or close the driver by calling AESCMAC_close().
### One step AES CBC-MAC signature with plaintext CryptoKey in blocking return mode #
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/drivers/AESCommon.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>
Go to the source code of this file.
Data Structures | |
struct | AESCMAC_Operation |
Struct containing the parameters required for signing or verifying a message. More... | |
struct | AESCMAC_Params |
AESCMAC Parameters. More... | |
Macros | |
#define | AESCMAC_STATUS_RESERVED AES_STATUS_RESERVED |
#define | AESCMAC_STATUS_SUCCESS AES_STATUS_SUCCESS |
Successful status code. More... | |
#define | AESCMAC_STATUS_ERROR AES_STATUS_ERROR |
Generic error status code. More... | |
#define | AESCMAC_STATUS_RESOURCE_UNAVAILABLE AES_STATUS_RESOURCE_UNAVAILABLE |
An error status code returned if the hardware or software resource is currently unavailable. More... | |
#define | AESCMAC_STATUS_MAC_INVALID AES_STATUS_MAC_INVALID |
The MAC verification failed. More... | |
#define | AESCMAC_STATUS_CANCELED AES_STATUS_CANCELED |
The ongoing operation was canceled. More... | |
#define | AESCMAC_STATUS_KEYSTORE_INVALID_ID AES_STATUS_KEYSTORE_INVALID_ID |
The operation tried to load a key from the keystore using an invalid key ID. More... | |
#define | AESCMAC_STATUS_KEYSTORE_GENERIC_ERROR AES_STATUS_KEYSTORE_GENERIC_ERROR |
The key store module returned a generic error. See key store documentation for additional details. More... | |
#define | AESCMAC_STATUS_UNALIGNED_IO_NOT_SUPPORTED AES_STATUS_UNALIGNED_IO_NOT_SUPPORTED |
The operation does not support non-word-aligned input. More... | |
#define | AESCMAC_OP_CODE_MASK 0x0F /* bits 0-3 */ |
Mask for the operation code. More... | |
#define | AESCMAC_OP_FLAG_SIGN 0x10 /* bit 4 */ |
Flag indicating a sign operation. If this bit is not set, then it is a verify operation. More... | |
#define | AESCMAC_OP_FLAGS_MASK (AESCMAC_OP_FLAG_SIGN | AESCMAC_OP_FLAG_VERIFY) |
Mask for all valid operation flags. More... | |
Typedefs | |
typedef AESCommon_Config | AESCMAC_Config |
CMAC Global configuration. More... | |
typedef AESCMAC_Config * | AESCMAC_Handle |
A handle that is returned from an AESCMAC_open() call. More... | |
typedef void(* | AESCMAC_CallbackFxn) (AESCMAC_Handle handle, int_fast16_t returnValue, AESCMAC_Operation *operation, AESCMAC_OperationType operationType) |
The definition of a callback function used by the AESCMAC driver when used in AESCMAC_RETURN_BEHAVIOR_CALLBACK. More... | |
Enumerations | |
enum | AESCMAC_ReturnBehavior { AESCMAC_RETURN_BEHAVIOR_CALLBACK = AES_RETURN_BEHAVIOR_CALLBACK, AESCMAC_RETURN_BEHAVIOR_BLOCKING = AES_RETURN_BEHAVIOR_BLOCKING, AESCMAC_RETURN_BEHAVIOR_POLLING = AES_RETURN_BEHAVIOR_POLLING } |
The return behavior of AESCMAC functions. More... | |
enum | AESCMAC_OperationalMode { AESCMAC_OPMODE_CMAC = 1, AESCMAC_OPMODE_CBCMAC = 2 } |
Defines the operation modes for the AESCMAC driver. More... | |
enum | AESCMAC_OperationCode { AESCMAC_OP_CODE_ONE_STEP = 0, AESCMAC_OP_CODE_SEGMENTED, AESCMAC_OP_CODE_FINALIZE } |
Enum for the operation codes supported by the driver. More... | |
enum | AESCMAC_OperationType { AESCMAC_OP_TYPE_SIGN = AESCMAC_OP_CODE_ONE_STEP | 0x10, AESCMAC_OP_TYPE_VERIFY = AESCMAC_OP_CODE_ONE_STEP, AESCMAC_OP_TYPE_SEGMENTED_SIGN = AESCMAC_OP_CODE_SEGMENTED | 0x10, AESCMAC_OP_TYPE_SEGMENTED_VERIFY = AESCMAC_OP_CODE_SEGMENTED, AESCMAC_OP_TYPE_FINALIZE_SIGN = AESCMAC_OP_CODE_FINALIZE | 0x10, AESCMAC_OP_TYPE_FINALIZE_VERIFY = AESCMAC_OP_CODE_FINALIZE } |
Enum for the operation types supported by the driver. More... | |
Functions | |
void | AESCMAC_init (void) |
Initializes the CMAC module. More... | |
void | AESCMAC_Params_init (AESCMAC_Params *params) |
Initializes the AESCMAC_Params struct to its defaults. More... | |
void | AESCMAC_Operation_init (AESCMAC_Operation *operation) |
Initializes an AESCMAC_Operation struct to its defaults. More... | |
AESCMAC_Handle | AESCMAC_open (uint_least8_t index, const AESCMAC_Params *params) |
Opens a given AESCMAC peripheral. More... | |
void | AESCMAC_close (AESCMAC_Handle handle) |
Closes a AESCMAC peripheral specified by the CMAC handle. More... | |
int_fast16_t | AESCMAC_setupSign (AESCMAC_Handle handle, const CryptoKey *key) |
Prepares a segmented AESCMAC sign operation. More... | |
int_fast16_t | AESCMAC_setupVerify (AESCMAC_Handle handle, const CryptoKey *key) |
Prepares a segmented AESCMAC verify operation. More... | |
int_fast16_t | AESCMAC_addData (AESCMAC_Handle handle, AESCMAC_Operation *operation) |
Adds data to the current segmented operation. More... | |
int_fast16_t | AESCMAC_finalize (AESCMAC_Handle handle, AESCMAC_Operation *operation) |
Finalizes the current segmented operation. More... | |
int_fast16_t | AESCMAC_oneStepSign (AESCMAC_Handle handle, AESCMAC_Operation *operation, CryptoKey *key) |
Performs a AESCMAC signature in one call. More... | |
int_fast16_t | AESCMAC_oneStepVerify (AESCMAC_Handle handle, AESCMAC_Operation *operation, CryptoKey *key) |
Performs a AESCMAC verification in one call. More... | |
int_fast16_t | AESCMAC_cancelOperation (AESCMAC_Handle handle) |
Cancels an ongoing AESCMAC operation. More... | |
AESCMAC_Handle | AESCMAC_construct (AESCMAC_Config *config, const AESCMAC_Params *params) |
Constructs a new AESCMAC object. More... | |
Variables | |
const AESCMAC_Params | AESCMAC_defaultParams |
Default AESCMAC_Params structure. More... | |
#define AESCMAC_STATUS_RESERVED AES_STATUS_RESERVED |
Common CMAC status code reservation offset. CMAC driver implementations should offset status codes with AESCMAC_STATUS_RESERVED growing negatively.
Example implementation specific status codes:
#define AESCMAC_STATUS_SUCCESS AES_STATUS_SUCCESS |
Successful status code.
Functions return AESCMAC_STATUS_SUCCESS if the function was executed successfully.
#define AESCMAC_STATUS_ERROR AES_STATUS_ERROR |
Generic error status code.
Functions return AESCMAC_STATUS_ERROR if the function was not executed successfully and no more pertinent error code could be returned.
#define AESCMAC_STATUS_RESOURCE_UNAVAILABLE AES_STATUS_RESOURCE_UNAVAILABLE |
An error status code returned if the hardware or software resource is currently unavailable.
CMAC driver implementations may have hardware or software limitations on how many clients can simultaneously perform operations. This status code is returned if the mutual exclusion mechanism signals that an operation cannot currently be performed.
#define AESCMAC_STATUS_MAC_INVALID AES_STATUS_MAC_INVALID |
The MAC verification failed.
Functions return AESCMAC_STATUS_MAC_INVALID if the MAC computed for the provided (key, message) pair did not match the MAC provided.
#define AESCMAC_STATUS_CANCELED AES_STATUS_CANCELED |
The ongoing operation was canceled.
#define AESCMAC_STATUS_KEYSTORE_INVALID_ID AES_STATUS_KEYSTORE_INVALID_ID |
The operation tried to load a key from the keystore using an invalid key ID.
#define AESCMAC_STATUS_KEYSTORE_GENERIC_ERROR AES_STATUS_KEYSTORE_GENERIC_ERROR |
The key store module returned a generic error. See key store documentation for additional details.
#define AESCMAC_STATUS_UNALIGNED_IO_NOT_SUPPORTED AES_STATUS_UNALIGNED_IO_NOT_SUPPORTED |
The operation does not support non-word-aligned input.
AESCMAC driver implementations may have restrictions on the alignment of input data due to performance limitations of the hardware.
#define AESCMAC_OP_CODE_MASK 0x0F /* bits 0-3 */ |
Mask for the operation code.
#define AESCMAC_OP_FLAG_SIGN 0x10 /* bit 4 */ |
Flag indicating a sign operation. If this bit is not set, then it is a verify operation.
#define AESCMAC_OP_FLAGS_MASK (AESCMAC_OP_FLAG_SIGN | AESCMAC_OP_FLAG_VERIFY) |
Mask for all valid operation flags.
typedef AESCommon_Config AESCMAC_Config |
CMAC Global configuration.
The AESCMAC_Config structure contains a set of pointers used to characterize the CMAC driver implementation.
This structure needs to be defined before calling AESCMAC_init() and it must not be changed thereafter.
typedef AESCMAC_Config* AESCMAC_Handle |
A handle that is returned from an AESCMAC_open() call.
typedef void(* AESCMAC_CallbackFxn) (AESCMAC_Handle handle, int_fast16_t returnValue, AESCMAC_Operation *operation, AESCMAC_OperationType operationType) |
The definition of a callback function used by the AESCMAC driver when used in AESCMAC_RETURN_BEHAVIOR_CALLBACK.
handle | Handle of the client that started the AESCMAC operation. |
returnValue | The result of the AESCMAC operation. May contain an error code. Informs the application of why the callback function was called. |
operation | Pointer to an operation struct. |
operationType | Indicates which operation the callback refers to. |
The return behavior of AESCMAC functions.
Not all AESCMAC operations exhibit the specified return behavior. Functions that do not require significant computation and cannot offload that computation to a background thread behave like regular functions. Which functions exhibit the specified return behavior is not implementation dependent. Specifically, a software-backed implementation run on the same CPU as the application will emulate the return behavior while not actually offloading the computation to the background thread.
AESCMAC functions exhibiting the specified return behavior have restrictions on the context from which they may be called.
Task | Hwi | Swi | |
---|---|---|---|
AESCMAC_RETURN_BEHAVIOR_CALLBACK | X | X | X |
AESCMAC_RETURN_BEHAVIOR_BLOCKING | X | ||
AESCMAC_RETURN_BEHAVIOR_POLLING | X | X | X |
Defines the operation modes for the AESCMAC driver.
By default, the driver will use CMAC to sign and verify messages. To use CBC-MAC instead of CMAC, set the operationalMode in AESCMAC_Params accordingly before calling AESCMAC_open or AESCMAC_construct. The operational mode persists throughout the existance of the driver instance.
Enumerator | |
---|---|
AESCMAC_OPMODE_CMAC | CMAC operational mode |
AESCMAC_OPMODE_CBCMAC | CBC-MAC operational mode |
void AESCMAC_init | ( | void | ) |
Initializes the CMAC module.
void AESCMAC_Params_init | ( | AESCMAC_Params * | params | ) |
Initializes the AESCMAC_Params struct to its defaults.
[in] | params | Pointer to AESCMAC_Params structure for initialization |
Defaults values are: returnBehavior = AESCMAC_RETURN_BEHAVIOR_BLOCKING operationalMode = AESCMAC_OPMODE_CMAC callbackFxn = NULL timeout = SemaphoreP_WAIT_FOREVER custom = NULL
void AESCMAC_Operation_init | ( | AESCMAC_Operation * | operation | ) |
Initializes an AESCMAC_Operation struct to its defaults.
[in] | operation | Pointer to an AESCMAC_Operation structure for initialization |
Defaults values are all zeros.
AESCMAC_Handle AESCMAC_open | ( | uint_least8_t | index, |
const AESCMAC_Params * | params | ||
) |
Opens a given AESCMAC peripheral.
[in] | index | Logical peripheral number for the CMAC indexed into the AESCMAC_config table |
[in] | params | Pointer to a parameter block, if NULL it will use default values |
void AESCMAC_close | ( | AESCMAC_Handle | handle | ) |
Closes a AESCMAC peripheral specified by the CMAC handle.
handle | AESCMAC handle |
int_fast16_t AESCMAC_setupSign | ( | AESCMAC_Handle | handle, |
const CryptoKey * | key | ||
) |
Prepares a segmented AESCMAC sign operation.
This function sets up a segmented AESCMAC sign operation. After a segmented operation is setup, it must be completed with AESCMAC_finalize or cancelled with AESCMAC_cancelOperation before another operation can be started.
[in] | handle | AESCMAC handle |
[in] | key | Pointer to a previously initialized CryptoKey. |
AESCMAC_STATUS_SUCCESS | The operation succeeded. Segmented data may now be added. |
AESCMAC_STATUS_ERROR | The operation failed. |
int_fast16_t AESCMAC_setupVerify | ( | AESCMAC_Handle | handle, |
const CryptoKey * | key | ||
) |
Prepares a segmented AESCMAC verify operation.
This function sets up a segmented AESCMAC verify operation. After a segmented operation is setup, it must be completed with AESCMAC_finalize or cancelled with AESCMAC_cancelOperation before another operation can be started.
[in] | handle | AESCMAC handle |
[in] | key | Pointer to a previously initialized CryptoKey. |
AESCMAC_STATUS_SUCCESS | The operation succeeded. Segmented data may now be added. |
AESCMAC_STATUS_ERROR | The operation failed. |
int_fast16_t AESCMAC_addData | ( | AESCMAC_Handle | handle, |
AESCMAC_Operation * | operation | ||
) |
Adds data to the current segmented operation.
The inputLength must be a non-zero multiple of the block size (16-bytes). AESCMAC_addData() may be called an arbitrary number of times before finishing the operation with AESCMAC_finalize().
This function blocks until the final MAC been computed. It returns immediately when AESCMAC_RETURN_BEHAVIOR_CALLBACK is set.
[in] | handle | AESCMAC handle |
[in] | operation | Pointer to CMAC operation structure() |
AESCMAC_STATUS_SUCCESS | The operation succeeded. |
AESCMAC_STATUS_ERROR | The operation failed. |
AESCMAC_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESCMAC_STATUS_UNALIGNED_IO_NOT_SUPPORTED | The input buffer was not word-aligned. |
int_fast16_t AESCMAC_finalize | ( | AESCMAC_Handle | handle, |
AESCMAC_Operation * | operation | ||
) |
Finalizes the current segmented operation.
For sign operations: This function computes and writes back the final MAC mac of length macLength.
For verify operations: This function uses the provided MAC mac to authenticate an input message. The return value indicates whether the authentication was successful.
[in] | handle | AESCMAC handle |
[in] | operation | Pointer to CMAC operation structure() |
AESCMAC_STATUS_SUCCESS | In AESCMAC_RETURN_BEHAVIOR_BLOCKING and AESCMAC_RETURN_BEHAVIOR_POLLING, this means the MAC was generated successfully. In AESCMAC_RETURN_BEHAVIOR_CALLBACK, this means the operation started successfully. |
AESCMAC_STATUS_ERROR | The operation failed. |
AESCMAC_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESCMAC_STATUS_MAC_INVALID | The provided MAC did not match the generated MAC. This return value is only valid for verify operations. |
AESCMAC_STATUS_UNALIGNED_IO_NOT_SUPPORTED | The input buffer was not word-aligned. |
int_fast16_t AESCMAC_oneStepSign | ( | AESCMAC_Handle | handle, |
AESCMAC_Operation * | operation, | ||
CryptoKey * | key | ||
) |
Performs a AESCMAC signature in one call.
This function uses the provided key to authenticate an input message. The resulting output is a message authentication code.
[in] | handle | AESCMAC handle |
[in] | operation | Pointer to AESCMAC operation structure |
[in] | key | Pointer to a previously initialized CryptoKey |
AESCMAC_STATUS_SUCCESS | In AESCMAC_RETURN_BEHAVIOR_BLOCKING and AESCMAC_RETURN_BEHAVIOR_POLLING, this means the MAC was generated successfully. In AESCMAC_RETURN_BEHAVIOR_CALLBACK, this means the operation started successfully. |
AESCMAC_STATUS_ERROR | The operation failed. |
AESCMAC_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESCMAC_STATUS_UNALIGNED_IO_NOT_SUPPORTED | The input buffer was not word-aligned. |
int_fast16_t AESCMAC_oneStepVerify | ( | AESCMAC_Handle | handle, |
AESCMAC_Operation * | operation, | ||
CryptoKey * | key | ||
) |
Performs a AESCMAC verification in one call.
This function verifies that the provided message authentication code matches the one generated by the provided key and input message.
[in] | handle | AESCMAC handle |
[in] | operation | Pointer to AESCMAC operation structure |
[in] | key | Pointer to a previously initialized CryptoKey |
AESCMAC_STATUS_SUCCESS | In AESCMAC_RETURN_BEHAVIOR_BLOCKING and AESCMAC_RETURN_BEHAVIOR_POLLING, this means the MAC was verified successfully. In AESCMAC_RETURN_BEHAVIOR_CALLBACK, this means the operation started successfully. |
AESCMAC_STATUS_ERROR | The operation failed. |
AESCMAC_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESCMAC_STATUS_MAC_INVALID | The provided MAC did not match the generated MAC. This return value is only valid for verify operations. |
AESCMAC_STATUS_UNALIGNED_IO_NOT_SUPPORTED | The input buffer was not word-aligned. |
int_fast16_t AESCMAC_cancelOperation | ( | AESCMAC_Handle | handle | ) |
Cancels an ongoing AESCMAC operation.
Asynchronously cancels an AESCMAC operation. Only available when using AESCMAC_RETURN_BEHAVIOR_CALLBACK. The operation will terminate as though an error occurred. The return status code of the operation will be AESCMAC_STATUS_CANCELED.
[in] | handle | Handle of the operation to cancel |
AESCMAC_STATUS_SUCCESS | The operation was canceled or the operation had already completed. |
AESCMAC_Handle AESCMAC_construct | ( | AESCMAC_Config * | config, |
const AESCMAC_Params * | params | ||
) |
Constructs a new AESCMAC object.
Unlike AESCMAC_open(), AESCMAC_construct() does not require the hwAttrs and object to be allocated in a AESCMAC_Config array that is indexed into. Instead, the AESCMAC_Config, hwAttrs, and object can be allocated at any location. This allows for relatively simple run-time allocation of temporary driver instances on the stack or the heap. The drawback is that this makes it more difficult to write device-agnostic code. If you use an ifdef with DeviceFamily, you can choose the correct object and hwAttrs to allocate. That compilation unit will be tied to the device it was compiled for at this point. To change devices, recompilation of the application with a different DeviceFamily setting is necessary.
config
points to must be zeroed out prior to calling this function. Otherwise, unexpected behavior may ensue.[in] | config | AESCMAC_Config describing the location of the object and hwAttrs. |
[in] | params | AESCMAC_Params to configure the driver instance. |
const AESCMAC_Params AESCMAC_defaultParams |
Default AESCMAC_Params structure.