AESGCM driver header.
The Galois Counter Mode (GCM) mode of operation is a generic authenticated encryption with associated data (AEAD) block cipher mode. It can be implemented with any block cipher. AESGCM combines GHASH with the AES block cipher in CTR mode of operation.
This combination of block cipher modes enables GCM to encrypt messages of any length and not only multiples of the block cipher block size.
CTR provides confidentiality. The using GHASH and encrypting the result provides message integrity and authentication.
The AES key is a shared secret between the two parties and has a length of 128, 192, or 256 bits.
The IV is generated by the party performing the authenticated encryption operation. Within the scope of any authenticated encryption key, the IV value must be unique. That is, the set of IV values used with any given key must not contain any duplicate values. Using the same IV for two different messages encrypted with the same key destroys the security properties of GCM.
The optional additional authentication data (AAD) is authenticated but not encrypted. Thus, the AAD is not included in the AES-GCM output. It can be used to authenticate packet headers, timestamps and other metadata.
After the encryption operation, the ciphertext contains the encrypted data and the message authentication code (MAC).
GCM is highly performant for an AEAD mode. Counter with CBC-MAC requires one invocation per block of AAD and two invocations of the block cipher per proccessed block of input; one to compute the CBC-MAC and one to perform CTR. GCM substitutes the block cipher invocation during CBC-MAC computation with computing GHASH over the same input. GHASH is significantly faster per block than AES. In turn, this gives GCM a performance edge over CCM.
In each operation, GCM limits the length of the input and AAD to guarantee its security properties:
The security properties of GCM rely on the MAC size. While MAC lengths of [4, 8, 12, 13, 14, 15, 16] bytes are permitted, it is recommended to use the full 16-byte MAC.
See NIST SP 800-38D for more a more detailed discussion of security considerations.
Before starting a GCM operation, the application must do the following:
The AESGCM_oneStepEncrypt() and AESGCM_oneStepDecrypt() functions perform a GCM operation in a single call.
When performing a decryption operation with AESGCM_oneStepDecrypt(), the MAC is automatically verified.
After the GCM operation completes, the application should either start another operation or close the driver by calling AESGCM_close()
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>
Go to the source code of this file.
Data Structures | |
struct | AESGCM_Operation |
Struct containing the parameters required for encrypting/decrypting and authenticating/verifying a message. More... | |
struct | AESGCM_Config |
AESGCM Global configuration. More... | |
struct | AESGCM_Params |
GCM Parameters. More... | |
Macros | |
#define | AESGCM_STATUS_RESERVED (-32) |
#define | AESGCM_STATUS_SUCCESS (0) |
Successful status code. More... | |
#define | AESGCM_STATUS_ERROR (-1) |
Generic error status code. More... | |
#define | AESGCM_STATUS_RESOURCE_UNAVAILABLE (-2) |
An error status code returned if the hardware or software resource is currently unavailable. More... | |
#define | AESGCM_STATUS_MAC_INVALID (-3) |
An error status code returned if the MAC provided by the application for a decryption operation does not match the one calculated during the operation. More... | |
#define | AESGCM_STATUS_CANCELED (-4) |
The ongoing operation was canceled. More... | |
Typedefs | |
typedef struct AESGCM_Config * | AESGCM_Handle |
A handle that is returned from an AESGCM_open() call. More... | |
typedef struct AESGCM_Config | AESGCM_Config |
AESGCM Global configuration. More... | |
typedef void(* | AESGCM_CallbackFxn) (AESGCM_Handle handle, int_fast16_t returnValue, AESGCM_Operation *operation, AESGCM_OperationType operationType) |
The definition of a callback function used by the AESGCM driver when used in AESGCM_RETURN_BEHAVIOR_CALLBACK. More... | |
Enumerations | |
enum | AESGCM_ReturnBehavior { AESGCM_RETURN_BEHAVIOR_CALLBACK = 1, AESGCM_RETURN_BEHAVIOR_BLOCKING = 2, AESGCM_RETURN_BEHAVIOR_POLLING = 4 } |
The way in which GCM function calls return after performing an encryption + authentication or decryption + verification operation. More... | |
enum | AESGCM_Mode { AESGCM_MODE_ENCRYPT = 1, AESGCM_MODE_DECRYPT = 2 } |
Enum for the direction of the GCM operation. More... | |
enum | AESGCM_OperationType { AESGCM_OPERATION_TYPE_ENCRYPT = 1, AESGCM_OPERATION_TYPE_DECRYPT = 2 } |
Enum for the operation types supported by the driver. More... | |
Functions | |
void | AESGCM_init (void) |
This function initializes the GCM module. More... | |
void | AESGCM_Params_init (AESGCM_Params *params) |
Function to initialize the AESGCM_Params struct to its defaults. More... | |
AESGCM_Handle | AESGCM_open (uint_least8_t index, AESGCM_Params *params) |
This function opens a given GCM peripheral. More... | |
void | AESGCM_close (AESGCM_Handle handle) |
Function to close a GCM peripheral specified by the GCM handle. More... | |
void | AESGCM_Operation_init (AESGCM_Operation *operationStruct) |
Function to initialize an AESGCM_Operation struct to its defaults. More... | |
int_fast16_t | AESGCM_oneStepEncrypt (AESGCM_Handle handle, AESGCM_Operation *operationStruct) |
Function to perform an AESGCM encryption + authentication operation in one call. More... | |
int_fast16_t | AESGCM_oneStepDecrypt (AESGCM_Handle handle, AESGCM_Operation *operationStruct) |
Function to perform an AESGCM decryption + verification operation in one call. More... | |
int_fast16_t | AESGCM_cancelOperation (AESGCM_Handle handle) |
Cancels an ongoing AESGCM operation. More... | |
Variables | |
const AESGCM_Params | AESGCM_defaultParams |
Default AESGCM_Params structure. More... | |
#define AESGCM_STATUS_RESERVED (-32) |
Common AESGCM status code reservation offset. AESGCM driver implementations should offset status codes with AESGCM_STATUS_RESERVED growing negatively.
Example implementation specific status codes:
#define AESGCM_STATUS_SUCCESS (0) |
Successful status code.
Functions return AESGCM_STATUS_SUCCESS if the function was executed successfully.
#define AESGCM_STATUS_ERROR (-1) |
Generic error status code.
Functions return AESGCM_STATUS_ERROR if the function was not executed successfully and no more pertinent error code could be returned.
#define AESGCM_STATUS_RESOURCE_UNAVAILABLE (-2) |
An error status code returned if the hardware or software resource is currently unavailable.
AESGCM 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 AESGCM_STATUS_MAC_INVALID (-3) |
An error status code returned if the MAC provided by the application for a decryption operation does not match the one calculated during the operation.
This code is returned by AESGCM_oneStepDecrypt() if the verification of the MAC fails.
#define AESGCM_STATUS_CANCELED (-4) |
The ongoing operation was canceled.
typedef struct AESGCM_Config* AESGCM_Handle |
A handle that is returned from an AESGCM_open() call.
typedef struct AESGCM_Config AESGCM_Config |
AESGCM Global configuration.
The AESGCM_Config structure contains a set of pointers used to characterize the AESGCM driver implementation.
This structure needs to be defined before calling AESGCM_init() and it must not be changed thereafter.
typedef void(* AESGCM_CallbackFxn) (AESGCM_Handle handle, int_fast16_t returnValue, AESGCM_Operation *operation, AESGCM_OperationType operationType) |
The definition of a callback function used by the AESGCM driver when used in AESGCM_RETURN_BEHAVIOR_CALLBACK.
handle | Handle of the client that started the GCM operation. |
returnValue | The result of the GCM operation. May contain an error code. Informs the application of why the callback function was called. |
operation | A pointer to an operation struct. |
operationType | This parameter determines which operation the callback refers to. |
The way in which GCM function calls return after performing an encryption + authentication or decryption + verification operation.
Not all GCM operations exhibit the specified return behavor. Functions that do not require significant computation and cannot offload that computation to a background thread behave like regular functions. Which functions exhibit the specfied 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.
AESGCM functions exhibiting the specified return behavior have restrictions on the context from which they may be called.
Task | Hwi | Swi | |
---|---|---|---|
AESGCM_RETURN_BEHAVIOR_CALLBACK | X | X | X |
AESGCM_RETURN_BEHAVIOR_BLOCKING | X | ||
AESGCM_RETURN_BEHAVIOR_POLLING | X | X | X |
enum AESGCM_Mode |
enum AESGCM_OperationType |
void AESGCM_init | ( | void | ) |
This function initializes the GCM module.
void AESGCM_Params_init | ( | AESGCM_Params * | params | ) |
Function to initialize the AESGCM_Params struct to its defaults.
params | An pointer to AESGCM_Params structure for initialization |
Defaults values are: returnBehavior = AESGCM_RETURN_BEHAVIOR_BLOCKING callbackFxn = NULL timeout = SemaphoreP_WAIT_FOREVER custom = NULL
AESGCM_Handle AESGCM_open | ( | uint_least8_t | index, |
AESGCM_Params * | params | ||
) |
This function opens a given GCM peripheral.
index | Logical peripheral number for the GCM indexed into the AESGCM_config table |
params | Pointer to an parameter block, if NULL it will use default values. |
void AESGCM_close | ( | AESGCM_Handle | handle | ) |
Function to close a GCM peripheral specified by the GCM handle.
handle | A GCM handle returned from AESGCM_open() |
void AESGCM_Operation_init | ( | AESGCM_Operation * | operationStruct | ) |
Function to initialize an AESGCM_Operation struct to its defaults.
operationStruct | A pointer to an AESGCM_Operation structure for initialization |
Defaults values are all zeros.
int_fast16_t AESGCM_oneStepEncrypt | ( | AESGCM_Handle | handle, |
AESGCM_Operation * | operationStruct | ||
) |
Function to perform an AESGCM encryption + authentication operation in one call.
[in] | handle | A GCM handle returned from AESGCM_open() |
[in] | operationStruct | A pointer to a struct containing the parameters required to perform the operation. |
AESGCM_STATUS_SUCCESS | The operation succeeded. |
AESGCM_STATUS_ERROR | The operation failed. |
AESGCM_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESGCM_STATUS_CANCELED | The operation was canceled. |
int_fast16_t AESGCM_oneStepDecrypt | ( | AESGCM_Handle | handle, |
AESGCM_Operation * | operationStruct | ||
) |
Function to perform an AESGCM decryption + verification operation in one call.
[in] | handle | A GCM handle returned from AESGCM_open() |
[in] | operationStruct | A pointer to a struct containing the parameters required to perform the operation. |
AESGCM_STATUS_SUCCESS | The operation succeeded. |
AESGCM_STATUS_ERROR | The operation failed. |
AESGCM_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESGCM_STATUS_CANCELED | The operation was canceled. |
AESGCM_STATUS_MAC_INVALID | The provided MAC did no match the recomputed one. |
int_fast16_t AESGCM_cancelOperation | ( | AESGCM_Handle | handle | ) |
Cancels an ongoing AESGCM operation.
Asynchronously cancels an AESGCM operation. Only available when using AESGCM_RETURN_BEHAVIOR_CALLBACK or AESGCM_RETURN_BEHAVIOR_BLOCKING. The operation will terminate as though an error occured. The return status code of the operation will be AESGCM_STATUS_CANCELED.
handle | Handle of the operation to cancel |
AESCBC_STATUS_SUCCESS | The operation was canceled. |
AESCBC_STATUS_ERROR | The operation was not canceled. |
const AESGCM_Params AESGCM_defaultParams |
Default AESGCM_Params structure.