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()
### Multi-step GCM encryption + authentication 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 | AESGCM_OneStepOperation |
Struct containing the parameters required for encrypting/decrypting and authenticating/verifying a message for one-step operations. More... | |
struct | AESGCM_SegmentedAADOperation |
Struct containing the parameters required for authenticating/verifying additional data in a segmented operation. Must be updated for each add AAD step of a segmented operation. More... | |
struct | AESGCM_SegmentedDataOperation |
Struct containing the parameters required for encrypting/decrypting a message in a segmented operation. Must be updated between each add data step of a segmented operation. More... | |
struct | AESGCM_SegmentedFinalizeOperation |
Struct containing the parameters required for finalizing an encryption/decryption and authentication/verification of a message in a segmented operation. More... | |
union | AESGCM_OperationUnion |
Union containing a reference to a one step, segmented AAD, segmented data, or segmented finalize operation. More... | |
struct | AESGCM_Params |
GCM Parameters. More... | |
Macros | |
#define | AESGCM_IV_LENGTH_BYTES 12 |
#define | AESGCM_STATUS_RESERVED AES_STATUS_RESERVED |
#define | AESGCM_STATUS_SUCCESS AES_STATUS_SUCCESS |
Successful status code. More... | |
#define | AESGCM_STATUS_ERROR AES_STATUS_ERROR |
Generic error status code. More... | |
#define | AESGCM_STATUS_RESOURCE_UNAVAILABLE AES_STATUS_RESOURCE_UNAVAILABLE |
An error status code returned if the hardware or software resource is currently unavailable. More... | |
#define | AESGCM_STATUS_CANCELED AES_STATUS_CANCELED |
The ongoing operation was canceled. More... | |
#define | AESGCM_STATUS_MAC_INVALID AES_STATUS_MAC_INVALID |
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_FEATURE_NOT_SUPPORTED AES_STATUS_FEATURE_NOT_SUPPORTED |
The operation requested is not supported on the target hardware. More... | |
#define | AESGCM_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 | AESGCM_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 | AESGCM_STATUS_UNALIGNED_IO_NOT_SUPPORTED AES_STATUS_UNALIGNED_IO_NOT_SUPPORTED |
The operation does not support non-word-aligned input and/or output. More... | |
Typedefs | |
typedef AESCommon_Config | AESGCM_Config |
AESGCM Global configuration. More... | |
typedef AESGCM_Config * | AESGCM_Handle |
A handle that is returned from an AESGCM_open() call. More... | |
typedef AESGCM_OneStepOperation | AESGCM_Operation |
typedef union AESGCM_OperationUnion | AESGCM_OperationUnion |
Union containing a reference to a one step, segmented AAD, segmented data, or segmented finalize operation. More... | |
typedef void(* | AESGCM_CallbackFxn) (AESGCM_Handle handle, int_fast16_t returnValue, AESGCM_OperationUnion *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 = AES_RETURN_BEHAVIOR_CALLBACK, AESGCM_RETURN_BEHAVIOR_BLOCKING = AES_RETURN_BEHAVIOR_BLOCKING, AESGCM_RETURN_BEHAVIOR_POLLING = AES_RETURN_BEHAVIOR_POLLING } |
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, AESGCM_OP_TYPE_ONESTEP_ENCRYPT = 1, AESGCM_OP_TYPE_ONESTEP_DECRYPT = 2, AESGCM_OP_TYPE_AAD_ENCRYPT = 3, AESGCM_OP_TYPE_AAD_DECRYPT = 4, AESGCM_OP_TYPE_DATA_ENCRYPT = 5, AESGCM_OP_TYPE_DATA_DECRYPT = 6, AESGCM_OP_TYPE_FINALIZE_ENCRYPT = 7, AESGCM_OP_TYPE_FINALIZE_DECRYPT = 8 } |
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, const 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... | |
int_fast16_t | AESGCM_setupEncrypt (AESGCM_Handle handle, const CryptoKey *key, size_t totalAADLength, size_t totalPlaintextLength) |
Function to prepare a segmented AESGCM encryption operation. More... | |
int_fast16_t | AESGCM_setupDecrypt (AESGCM_Handle handle, const CryptoKey *key, size_t totalAADLength, size_t totalPlaintextLength) |
Function to prepare a segmented AESGCM decryption operation. More... | |
int_fast16_t | AESGCM_setLengths (AESGCM_Handle handle, size_t aadLength, size_t plaintextLength) |
Function to set the lengths of the message and additional data. More... | |
int_fast16_t | AESGCM_setIV (AESGCM_Handle handle, const uint8_t *iv, size_t ivLength) |
Function to set the initialization vector (IV) for an AES GCM segmented operation. More... | |
int_fast16_t | AESGCM_generateIV (AESGCM_Handle handle, uint8_t *iv, size_t ivSize, size_t *ivLength) |
Function to generate an IV for an AES GCM segmented encryption operation. More... | |
int_fast16_t | AESGCM_addAAD (AESGCM_Handle handle, AESGCM_SegmentedAADOperation *operation) |
Adds a segment of aad with a length in bytes to the generated MAC. More... | |
int_fast16_t | AESGCM_addData (AESGCM_Handle handle, AESGCM_SegmentedDataOperation *operation) |
Adds a segment of data with a length that is a multiple of an AES block-size (16 bytes) to the plaintext/ciphertext output and generated MAC. The length does not have to be a block-size multiple if passing in the last chunk of data. More... | |
int_fast16_t | AESGCM_finalizeEncrypt (AESGCM_Handle handle, AESGCM_SegmentedFinalizeOperation *operation) |
Finalize the MAC and ciphertext. More... | |
int_fast16_t | AESGCM_finalizeDecrypt (AESGCM_Handle handle, AESGCM_SegmentedFinalizeOperation *operation) |
Finalize the MAC and plaintext and verify it. More... | |
void | AESGCM_Operation_init (AESGCM_Operation *operationStruct) |
Function to initialize an AESGCM_Operation struct to its defaults. More... | |
void | AESGCM_OneStepOperation_init (AESGCM_OneStepOperation *operationStruct) |
Function to initialize an AESGCM_OneStepOperation struct to its defaults. More... | |
void | AESGCM_SegmentedAADOperation_init (AESGCM_SegmentedAADOperation *operationStruct) |
Function to initialize an AESGCM_SegmentedAADOperation struct to its defaults. More... | |
void | AESGCM_SegmentedDataOperation_init (AESGCM_SegmentedDataOperation *operationStruct) |
Function to initialize an AESGCM_SegmentedDataOperation struct to its defaults. More... | |
void | AESGCM_SegmentedFinalizeOperation_init (AESGCM_SegmentedFinalizeOperation *operationStruct) |
Function to initialize an AESGCM_SegmentedFinalizeOperation struct to its defaults. More... | |
int_fast16_t | AESGCM_oneStepEncrypt (AESGCM_Handle handle, AESGCM_OneStepOperation *operationStruct) |
Function to perform an AESGCM encryption + authentication operation in one call. More... | |
int_fast16_t | AESGCM_oneStepDecrypt (AESGCM_Handle handle, AESGCM_OneStepOperation *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... | |
AESGCM_Handle | AESGCM_construct (AESGCM_Config *config, const AESGCM_Params *params) |
Constructs a new AESGCM object. More... | |
Variables | |
const AESGCM_Params | AESGCM_defaultParams |
Default AESGCM_Params structure. More... | |
#define AESGCM_IV_LENGTH_BYTES 12 |
#define AESGCM_STATUS_RESERVED AES_STATUS_RESERVED |
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 AES_STATUS_SUCCESS |
Successful status code.
Functions return AESGCM_STATUS_SUCCESS if the function was executed successfully.
#define AESGCM_STATUS_ERROR AES_STATUS_ERROR |
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 AES_STATUS_RESOURCE_UNAVAILABLE |
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_CANCELED AES_STATUS_CANCELED |
The ongoing operation was canceled.
#define AESGCM_STATUS_MAC_INVALID AES_STATUS_MAC_INVALID |
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() or AESGCM_finalizeDecrypt() if the verification of the MAC fails.
#define AESGCM_STATUS_FEATURE_NOT_SUPPORTED AES_STATUS_FEATURE_NOT_SUPPORTED |
The operation requested is not supported on the target hardware.
This code is returned by AES GCM segmented data operations when attempting to use them on device families that do not support segmented operations.
#define AESGCM_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 AESGCM_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 AESGCM_STATUS_UNALIGNED_IO_NOT_SUPPORTED AES_STATUS_UNALIGNED_IO_NOT_SUPPORTED |
The operation does not support non-word-aligned input and/or output.
AESGCM driver implementations may have restrictions on the alignment of input/output data due to performance limitations of the hardware.
typedef AESCommon_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 AESGCM_Config* AESGCM_Handle |
A handle that is returned from an AESGCM_open() call.
typedef union AESGCM_OperationUnion AESGCM_OperationUnion |
Union containing a reference to a one step, segmented AAD, segmented data, or segmented finalize operation.
typedef void(* AESGCM_CallbackFxn) (AESGCM_Handle handle, int_fast16_t returnValue, AESGCM_OperationUnion *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. |
operationUnion | A pointer to an operation union. |
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 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.
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 |
Enum for the operation types supported by the driver.
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, |
const AESGCM_Params * | params | ||
) |
This function opens a given GCM peripheral.
[in] | index | Logical peripheral number for the GCM indexed into the AESGCM_config table |
[in] | 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.
[in] | handle | A GCM handle |
int_fast16_t AESGCM_setupEncrypt | ( | AESGCM_Handle | handle, |
const CryptoKey * | key, | ||
size_t | totalAADLength, | ||
size_t | totalPlaintextLength | ||
) |
Function to prepare a segmented AESGCM encryption operation.
This function sets up a segmented AESGCM encryption operation.
[in] | handle | A GCM handle returned from AESGCM_open() or AESGCM_construct() |
[in] | key | Pointer to a previously initialized CryptoKey. |
[in] | totalAADLength | Total size of the AAD in bytes. This value can be 0 and later provided by AESGCM_setLengths(). |
[in] | totalPlaintextLength | Total size of the plaintext in bytes. This value can be 0 and later provided by AESGCM_setLengths(). |
AESGCM_STATUS_SUCCESS | The operation succeeded. |
AESGCM_STATUS_ERROR | The operation failed. |
AESGCM_STATUS_FEATURE_NOT_SUPPORTED | The operation is not supported in this device. |
int_fast16_t AESGCM_setupDecrypt | ( | AESGCM_Handle | handle, |
const CryptoKey * | key, | ||
size_t | totalAADLength, | ||
size_t | totalPlaintextLength | ||
) |
Function to prepare a segmented AESGCM decryption operation.
This function sets up a segmented AESGCM decryption operation.
[in] | handle | A GCM handle returned from AESGCM_open() or AESGCM_construct() |
[in] | key | Pointer to a previously initialized CryptoKey. |
[in] | totalAADLength | Total size of the AAD in bytes. This value can be 0 and later provided by AESGCM_setLengths(). |
[in] | totalPlaintextLength | Total size of the plaintext in bytes This value can be 0 and later provided by AESGCM_setLengths(). |
AESGCM_STATUS_SUCCESS | The operation succeeded. |
AESGCM_STATUS_ERROR | The operation failed. |
AESGCM_STATUS_FEATURE_NOT_SUPPORTED | The operation is not supported in this device. |
int_fast16_t AESGCM_setLengths | ( | AESGCM_Handle | handle, |
size_t | aadLength, | ||
size_t | plaintextLength | ||
) |
Function to set the lengths of the message and additional data.
This function declares the lengths of the message and additional authenticated data (AAD).
[in] | handle | A GCM handle returned from AESGCM_open() or AESGCM_construct() |
[in] | aadLength | Size of the non-encrypted AAD in bytes |
[in] | plaintextLength | Size of the plaintext to encrypt or the ciphertext to decrypt in bytes |
AESGCM_STATUS_SUCCESS | The operation succeeded. |
AESGCM_STATUS_ERROR | The operation failed. |
AESGCM_STATUS_FEATURE_NOT_SUPPORTED | The operation is not supported in this device. |
int_fast16_t AESGCM_setIV | ( | AESGCM_Handle | handle, |
const uint8_t * | iv, | ||
size_t | ivLength | ||
) |
Function to set the initialization vector (IV) for an AES GCM segmented operation.
[in] | handle | A GCM handle returned from AESGCM_open() or AESGCM_construct() |
[in] | iv | Pointer to the buffer containing the IV |
[in] | ivLength | The length of the IV in bytes |
AESGCM_STATUS_SUCCESS | The operation succeeded. |
AESGCM_STATUS_ERROR | The operation failed. |
AESGCM_STATUS_FEATURE_NOT_SUPPORTED | The operation is not supported in this device. |
int_fast16_t AESGCM_generateIV | ( | AESGCM_Handle | handle, |
uint8_t * | iv, | ||
size_t | ivSize, | ||
size_t * | ivLength | ||
) |
Function to generate an IV for an AES GCM segmented encryption operation.
[in] | handle | A GCM handle returned from AESGCM_open() or AESGCM_construct() |
[in] | iv | Pointer to the buffer where the generated IV is to be written to |
[in] | ivSize | The length of the IV buffer in bytes |
[out] | ivLength | The length of the IV actually written if the operation was successful |
AESGCM_STATUS_SUCCESS | The operation succeeded. |
AESGCM_STATUS_ERROR | The operation failed. |
AESGCM_STATUS_FEATURE_NOT_SUPPORTED | The operation is not supported in this device. |
int_fast16_t AESGCM_addAAD | ( | AESGCM_Handle | handle, |
AESGCM_SegmentedAADOperation * | operation | ||
) |
Adds a segment of aad with a length in bytes to the generated MAC.
AESGCM_addAAD() may be called an arbitrary number of times before continuing the operation with AESGCM_addData(), AESGCM_finalizeEncrypt() or AESGCM_finalizeDecrypt().
This function returns according to the return behavior set when opening the driver.
[in] | handle | A GCM handle returned from AESGCM_open() or AESGCM_construct() |
[in] | operation | Pointer to segmented AAD GCM operation structure |
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_FEATURE_NOT_SUPPORTED | The operation is not supported in this device. |
int_fast16_t AESGCM_addData | ( | AESGCM_Handle | handle, |
AESGCM_SegmentedDataOperation * | operation | ||
) |
Adds a segment of data with a length that is a multiple of an AES block-size (16 bytes) to the plaintext/ciphertext output and generated MAC. The length does not have to be a block-size multiple if passing in the last chunk of data.
AESGCM_addData() may be called an arbitrary number of times before finishing the operation with AESGCM_finalizeEncrypt() or AESGCM_finalizeDecrypt().
This function returns according to the return behavior set when opening the driver.
[in] | handle | A GCM handle returned from AESGCM_open() or AESGCM_construct() |
[in] | operation | Pointer to segmented data GCM operation structure |
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_FEATURE_NOT_SUPPORTED | The operation is not supported in this device. |
int_fast16_t AESGCM_finalizeEncrypt | ( | AESGCM_Handle | handle, |
AESGCM_SegmentedFinalizeOperation * | operation | ||
) |
Finalize the MAC and ciphertext.
This function finalizes the encryption of a dataset earlier provided by calls to AESGCM_addAAD() and AESGCM_addData() and creates a message authentication code. If additional data needs to be encrypted and verified as part of this call, set the operation structure inputLength accordingly.
The resulting output is a message authentication code and ciphertext.
[in] | handle | A GCM handle returned from AESGCM_open() or AESGCM_construct() |
[in] | operation | Pointer to segmented finalize GCM operation structure |
AESGCM_STATUS_SUCCESS | In AESGCM_RETURN_BEHAVIOR_BLOCKING and AESGCM_RETURN_BEHAVIOR_POLLING, this means the MAC was generated successfully. In AESGCM_RETURN_BEHAVIOR_CALLBACK, this means the operation started successfully. |
AESGCM_STATUS_ERROR | The operation failed. |
AESGCM_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESGCM_STATUS_FEATURE_NOT_SUPPORTED | The operation is not supported in this device. |
int_fast16_t AESGCM_finalizeDecrypt | ( | AESGCM_Handle | handle, |
AESGCM_SegmentedFinalizeOperation * | operation | ||
) |
Finalize the MAC and plaintext and verify it.
This function finalizes the decryption of a dataset earlier provided by calls to AESGCM_addAAD() and AESGCM_addData() and verifies a provided message authentication code. If additional data needs to be decrypted and verified as part of this call, set the operation structure inputLength accordingly.
The resulting output is a verification return code and plaintext.
[in] | handle | A GCM handle returned from AESGCM_open() or AESGCM_construct() |
[in] | operation | Pointer to segmented finalize GCM operation structure |
AESGCM_STATUS_SUCCESS | In AESGCM_RETURN_BEHAVIOR_BLOCKING and AESGCM_RETURN_BEHAVIOR_POLLING, this means the MAC was verified successfully. In AESGCM_RETURN_BEHAVIOR_CALLBACK, this means the operation started successfully. |
AESGCM_STATUS_ERROR | The operation failed. |
AESGCM_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESGCM_STATUS_MAC_INVALID | The provided MAC did not match the recomputed one. |
AESGCM_STATUS_FEATURE_NOT_SUPPORTED | The operation is not supported in this device. |
void AESGCM_Operation_init | ( | AESGCM_Operation * | operationStruct | ) |
Function to initialize an AESGCM_Operation struct to its defaults.
[in] | operationStruct | A pointer to an AESGCM_Operation structure for initialization |
Defaults values are all zeros.
void AESGCM_OneStepOperation_init | ( | AESGCM_OneStepOperation * | operationStruct | ) |
Function to initialize an AESGCM_OneStepOperation struct to its defaults.
[in] | operationStruct | A pointer to an AESGCM_OneStepOperation structure for initialization |
Defaults values are all zeros.
void AESGCM_SegmentedAADOperation_init | ( | AESGCM_SegmentedAADOperation * | operationStruct | ) |
Function to initialize an AESGCM_SegmentedAADOperation struct to its defaults.
[in] | operationStruct | A pointer to an AESGCM_SegmentedAADOperation structure for initialization |
Defaults values are all zeros.
void AESGCM_SegmentedDataOperation_init | ( | AESGCM_SegmentedDataOperation * | operationStruct | ) |
Function to initialize an AESGCM_SegmentedDataOperation struct to its defaults.
[in] | operationStruct | A pointer to an AESGCM_SegmentedDataOperation structure for initialization |
Defaults values are all zeros.
void AESGCM_SegmentedFinalizeOperation_init | ( | AESGCM_SegmentedFinalizeOperation * | operationStruct | ) |
Function to initialize an AESGCM_SegmentedFinalizeOperation struct to its defaults.
[in] | operationStruct | A pointer to an AESGCM_SegmentedFinalizeOperation structure for initialization |
Defaults values are all zeros.
int_fast16_t AESGCM_oneStepEncrypt | ( | AESGCM_Handle | handle, |
AESGCM_OneStepOperation * | operationStruct | ||
) |
Function to perform an AESGCM encryption + authentication operation in one call.
[in] | handle | A GCM handle returned from AESGCM_open() or AESGCM_construct() |
[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 or the IV length is not supported. |
AESGCM_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESGCM_STATUS_UNALIGNED_IO_NOT_SUPPORTED | The input and/or output buffer were not word-aligned. |
int_fast16_t AESGCM_oneStepDecrypt | ( | AESGCM_Handle | handle, |
AESGCM_OneStepOperation * | operationStruct | ||
) |
Function to perform an AESGCM decryption + verification operation in one call.
[in] | handle | A GCM handle returned from AESGCM_open() or AESGCM_construct() |
[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 or the IV length is not supported. |
AESGCM_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
AESGCM_STATUS_MAC_INVALID | The provided MAC did no match the recomputed one. |
AESGCM_STATUS_UNALIGNED_IO_NOT_SUPPORTED | The input and/or output buffer were not word-aligned. |
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. The operation will terminate as though an error occurred. The return status code of the operation will be AESGCM_STATUS_CANCELED.
[in] | handle | Handle of the operation to cancel |
AESGCM_STATUS_SUCCESS | The operation was canceled, or the operation had already completed. |
AESGCM_STATUS_ERROR | The driver was not in callback mode, or the operation's output and generated MAC weren't properly cleared. |
AESGCM_Handle AESGCM_construct | ( | AESGCM_Config * | config, |
const AESGCM_Params * | params | ||
) |
Constructs a new AESGCM object.
Unlike AESGCM_open(), AESGCM_construct() does not require the hwAttrs and object to be allocated in a AESGCM_Config array that is indexed into. Instead, the AESGCM_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 | AESGCM_Config describing the location of the object and hwAttrs. |
params | AESGCM_Params to configure the driver instance. |
config
points to must be zeroed out prior to calling this function. Otherwise, unexpected behavior may ensue. const AESGCM_Params AESGCM_defaultParams |
Default AESGCM_Params structure.