Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
AESGCM.h File Reference

Detailed Description

AESGCM driver header.


Warning
This is a beta API. It may change in future releases.

Overview

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.

Security Considerations

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.

Usage

Before starting a GCM operation

Before starting a GCM operation, the application must do the following:

Starting a GCM operation

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

After the GCM operation completes, the application should either start another operation or close the driver by calling AESGCM_close()

Synopsis

// Import AESGCM Driver definitions
// Define name for AESGCM channel index
#define AESGCM_INSTANCE 0
handle = AESGCM_open(AESGCM_INSTANCE, NULL);
// Initialize symmetric key
CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
// Set up AESGCM_Operation
operation.key = &cryptoKey;
operation.aad = aad;
operation.aadLength = sizeof(aad);
operation.input = plaintext;
operation.output = ciphertext;
operation.inputLength = sizeof(plaintext);
operation.nonce = nonce;
operation.nonceLength = sizeof(nonce);
operation.mac = mac;
operation.macLength = sizeof(mac);
encryptionResult = AESGCM_oneStepEncrypt(handle, &operation);
AESGCM_close(handle);

Examples

Single call GCM encryption + authentication with plaintext CryptoKey in blocking return mode
...
AESGCM_Handle handle;
CryptoKey cryptoKey;
int_fast16_t encryptionResult;
uint8_t iv[12] = "12-byte IV ";
uint8_t aad[] = "This string will be authenticated but not encrypted.";
uint8_t plaintext[] = "This string will be encrypted and authenticated.";
uint8_t mac[16];
uint8_t ciphertext[sizeof(plaintext)];
uint8_t keyingMaterial[32] = {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F,
0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
0x18, 0x19, 0x1A, 0x1B, 0x1C, 0x1D, 0x1E, 0x1F};
handle = AESGCM_open(0, NULL);
if (handle == NULL) {
// handle error
}
CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
AESGCM_Operation operation;
operation.key = &cryptoKey;
operation.aad = aad;
operation.aadLength = sizeof(aad);
operation.input = plaintext;
operation.output = ciphertext;
operation.inputLength = sizeof(plaintext);
operation.iv = iv;
operation.ivLength = 12;
operation.mac = mac;
operation.macLength = sizeof(mac);
encryptionResult = AESGCM_oneStepEncrypt(handle, &operation);
if (encryptionResult != AESGCM_STATUS_SUCCESS) {
// handle error
}
AESGCM_close(handle);
Single call GCM decryption + verification with plaintext CryptoKey in callback return mode
...
// The following test vector is Packet Vector 1 from RFC 3610 of the IETF.
uint8_t iv[] = {0x1f, 0x80, 0x3c, 0x52, 0xca, 0xc4, 0x97, 0xe1,
0x55, 0xaa, 0x55, 0x2d};
uint8_t aad[] = {0x3b, 0xba, 0x31, 0x28, 0x9d, 0x05, 0xf5, 0x0f,
0xed, 0x6c, 0x53, 0x35, 0x3c, 0x1f, 0x74, 0xd8,
0x28, 0xa9, 0x96, 0xb8, 0xd6, 0x84, 0xfe, 0x64,
0x7f, 0x7c, 0x40, 0xc0, 0xd5, 0x68, 0x8c, 0x89,
0x68, 0x1a, 0x33, 0xb1, 0x0c, 0xb7, 0x14, 0xb6,
0x49, 0x0b, 0xdf, 0x1f, 0x16, 0x60, 0x60, 0xa7};
uint8_t mac[] = {0x39, 0x03, 0xe4, 0xdc, 0xa4, 0xe7, 0xc8, 0x21,
0x62, 0x1a, 0xbb, 0xb2, 0x37, 0x2c, 0x97};
uint8_t ciphertext[] = {0xf8, 0x7e, 0xf7, 0x99, 0x4a, 0x86, 0xf3, 0xe9,
0xa3, 0xab, 0x6a, 0x6f, 0x2d, 0x34, 0x3b, 0xbd};
uint8_t keyingMaterial[] = {0x4f, 0xd7, 0xf2, 0x09, 0xdf, 0xb0, 0xdf, 0xbd,
0xd9, 0x8d, 0x2d, 0xb4, 0x98, 0x66, 0x4c, 0x88};
uint8_t plaintext[sizeof(ciphertext)];
// The plaintext should be the following after the decryption operation:
// 0x17, 0x9d, 0xcb, 0x79, 0x5c, 0x09, 0x8f, 0xc5, 0x31, 0x4b, 0xde, 0x0d, 0x39, 0x9d, 0x7a, 0x10
void gcmCallback(AESGCM_Handle handle,
int_fast16_t returnValue,
AESGCM_Operation *operation,
AESGCM_OperationType operationType) {
if (returnValue != AESGCM_STATUS_SUCCESS) {
// handle error
}
}
AESGCM_Operation operation;
CryptoKey cryptoKey;
void gcmStartFunction(void) {
AESGCM_Handle handle;
AESGCM_Params params;
int_fast16_t decryptionResult;
params.callbackFxn = gcmCallback;
handle = AESGCM_open(0, &params);
if (handle == NULL) {
// handle error
}
CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
AESGCM_Operation_init(&operation);
operation.key = &cryptoKey;
operation.aad = aad;
operation.aadLength = sizeof(aad);
operation.input = ciphertext;
operation.output = plaintext;
operation.inputLength = sizeof(ciphertext);
operation.iv = iv;
operation.mac = mac;
operation.macLength = sizeof(mac);
decryptionResult = AESGCM_oneStepDecrypt(handle, &operation);
if (decryptionResult != AESGCM_STATUS_SUCCESS) {
// handle error
}
// do other things while GCM operation completes in the background
}
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>
Include dependency graph for AESGCM.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  AESGCM_Config
 AESGCM Global configuration. More...
 
struct  AESGCM_Operation
 Struct containing the parameters required for encrypting/decrypting and authenticating/verifying a message. 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 AESGCM_ConfigAESGCM_Handle
 A handle that is returned from an AESGCM_open() call. 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, 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...
 
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...
 
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...
 

Macro Definition Documentation

§ AESGCM_STATUS_RESERVED

#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 AESGCMXYZ_STATUS_ERROR0 AESGCM_STATUS_RESERVED - 0
#define AESGCMXYZ_STATUS_ERROR1 AESGCM_STATUS_RESERVED - 1
#define AESGCMXYZ_STATUS_ERROR2 AESGCM_STATUS_RESERVED - 2

§ AESGCM_STATUS_SUCCESS

#define AESGCM_STATUS_SUCCESS   (0)

Successful status code.

Functions return AESGCM_STATUS_SUCCESS if the function was executed successfully.

§ AESGCM_STATUS_ERROR

#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.

§ AESGCM_STATUS_RESOURCE_UNAVAILABLE

#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.

§ AESGCM_STATUS_MAC_INVALID

#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.

§ AESGCM_STATUS_CANCELED

#define AESGCM_STATUS_CANCELED   (-4)

The ongoing operation was canceled.

Typedef Documentation

§ AESGCM_Handle

A handle that is returned from an AESGCM_open() call.

§ AESGCM_CallbackFxn

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.

Parameters
handleHandle of the client that started the GCM operation.
returnValueThe result of the GCM operation. May contain an error code. Informs the application of why the callback function was called.
operationA pointer to an operation struct.
operationTypeThis parameter determines which operation the callback refers to.

Enumeration Type Documentation

§ AESGCM_ReturnBehavior

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
Enumerator
AESGCM_RETURN_BEHAVIOR_CALLBACK 

The function call will return immediately while the GCM operation goes on in the background. The registered callback function is called after the operation completes. The context the callback function is called (task, HWI, SWI) is implementation-dependent.

AESGCM_RETURN_BEHAVIOR_BLOCKING 

The function call will block while the GCM operation goes on in the background. GCM operation results are available after the function returns.

AESGCM_RETURN_BEHAVIOR_POLLING 

The function call will continuously poll a flag while GCM operation goes on in the background. GCM operation results are available after the function returns.

§ AESGCM_Mode

Enum for the direction of the GCM operation.

Enumerator
AESGCM_MODE_ENCRYPT 
AESGCM_MODE_DECRYPT 

§ AESGCM_OperationType

Enum for the operation types supported by the driver.

Enumerator
AESGCM_OPERATION_TYPE_ENCRYPT 
AESGCM_OPERATION_TYPE_DECRYPT 

Function Documentation

§ AESGCM_init()

void AESGCM_init ( void  )

This function initializes the GCM module.

Precondition
The AESGCM_config structure must exist and be persistent before this function can be called. This function must also be called before any other GCM driver APIs. This function call does not modify any peripheral registers.

§ AESGCM_Params_init()

void AESGCM_Params_init ( AESGCM_Params params)

Function to initialize the AESGCM_Params struct to its defaults.

Parameters
paramsAn pointer to AESGCM_Params structure for initialization

Defaults values are: returnBehavior = AESGCM_RETURN_BEHAVIOR_BLOCKING callbackFxn = NULL timeout = SemaphoreP_WAIT_FOREVER custom = NULL

§ AESGCM_open()

AESGCM_Handle AESGCM_open ( uint_least8_t  index,
const AESGCM_Params params 
)

This function opens a given GCM peripheral.

Precondition
GCM controller has been initialized using AESGCM_init()
Parameters
indexLogical peripheral number for the GCM indexed into the AESGCM_config table
paramsPointer to an parameter block, if NULL it will use default values.
Returns
An AESGCM_Handle on success or a NULL on an error or if it has been opened already.
See also
AESGCM_init()
AESGCM_close()

§ AESGCM_close()

void AESGCM_close ( AESGCM_Handle  handle)

Function to close a GCM peripheral specified by the GCM handle.

Precondition
AESGCM_open() has to be called first.
Parameters
handleA GCM handle returned from AESGCM_open()
See also
AESGCM_open()

§ AESGCM_Operation_init()

void AESGCM_Operation_init ( AESGCM_Operation operationStruct)

Function to initialize an AESGCM_Operation struct to its defaults.

Parameters
operationStructA pointer to an AESGCM_Operation structure for initialization

Defaults values are all zeros.

§ AESGCM_oneStepEncrypt()

int_fast16_t AESGCM_oneStepEncrypt ( AESGCM_Handle  handle,
AESGCM_Operation operationStruct 
)

Function to perform an AESGCM encryption + authentication operation in one call.

Note
None of the buffers provided as arguments may be altered by the application during an ongoing operation. Doing so can yield corrupted ciphertext or incorrect authentication.
Precondition
AESGCM_open() and AESGCM_Operation_init() have to be called first.
Parameters
[in]handleA GCM handle returned from AESGCM_open()
[in]operationStructA pointer to a struct containing the parameters required to perform the operation.
Return values
AESGCM_STATUS_SUCCESSThe operation succeeded.
AESGCM_STATUS_ERRORThe operation failed.
AESGCM_STATUS_RESOURCE_UNAVAILABLEThe required hardware resource was not available. Try again later.
AESGCM_STATUS_CANCELEDThe operation was canceled.
See also
AESGCM_oneStepDecrypt()

§ AESGCM_oneStepDecrypt()

int_fast16_t AESGCM_oneStepDecrypt ( AESGCM_Handle  handle,
AESGCM_Operation operationStruct 
)

Function to perform an AESGCM decryption + verification operation in one call.

Note
None of the buffers provided as arguments may be altered by the application during an ongoing operation. Doing so can yield corrupted plaintext or incorrectly failed verification.
Precondition
AESGCM_open() and AESGCM_Operation_init() have to be called first.
Parameters
[in]handleA GCM handle returned from AESGCM_open()
[in]operationStructA pointer to a struct containing the parameters required to perform the operation.
Return values
AESGCM_STATUS_SUCCESSThe operation succeeded.
AESGCM_STATUS_ERRORThe operation failed.
AESGCM_STATUS_RESOURCE_UNAVAILABLEThe required hardware resource was not available. Try again later.
AESGCM_STATUS_CANCELEDThe operation was canceled.
AESGCM_STATUS_MAC_INVALIDThe provided MAC did no match the recomputed one.
See also
AESGCM_oneStepEncrypt()

§ AESGCM_cancelOperation()

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.

Parameters
handleHandle of the operation to cancel
Return values
AESCBC_STATUS_SUCCESSThe operation was canceled.
AESCBC_STATUS_ERRORThe operation was not canceled.

§ AESGCM_construct()

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.

Parameters
configAESGCM_Config describing the location of the object and hwAttrs.
paramsAESGCM_Params to configure the driver instance.
Returns
Returns a AESGCM_Handle on success or NULL on failure.
Precondition
The object struct config points to must be zeroed out prior to calling this function. Otherwise, unexpected behavior may ensue.

Variable Documentation

§ AESGCM_defaultParams

const AESGCM_Params AESGCM_defaultParams

Default AESGCM_Params structure.

See also
AESGCM_Params_init()
© Copyright 1995-2019, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale