AESGCM.h

Go to the documentation of this file.

/*
 * Copyright (c) 2018-2024, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!****************************************************************************
 *
 * @file       AESGCM.h
 *
 * @brief      AESGCM driver header
 *
 * @anchor ti_drivers_AESGCM_Overview
 * ### 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:
 *     - inputLength <= 2^36 - 32 bytes
 *     - aadLength <= 2^61 - 1 bytes
 *
 * 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.
 *
 * @anchor ti_drivers_AESGCM_Usage
 * ### Usage #
 *
 * #### Before starting a GCM operation #
 *
 * Before starting a GCM operation, the application must do the following:
 *     - Call AESGCM_init() to initialize the driver
 *     - Call AESGCM_Params_init() to initialize the #AESGCM_Params to default values.
 *     - Modify the #AESGCM_Params as desired
 *     - Call AESGCM_open() to open an instance of the driver
 *     - Initialize a CryptoKey. These opaque data structures are representations
 *       of keying material and its storage. Depending on how the keying material
 *       is stored (RAM or flash, key store), the CryptoKey must be
 *       initialized differently. The AESGCM API can handle all types of CryptoKey.
 *       However, not all device-specific implementations support all types of CryptoKey.
 *       Devices without a key store will not support CryptoKeys with keying material
 *       stored in a key store for example.
 *       All devices support plaintext CryptoKeys.
 *     - Initialize the appropriate AESGCM operation struct using the relevant
 *       operation init functions and set all fields. For example, one-step (one-shot
 *       or single call) operations should initialize AESGCM_Operation or
 *       AESGCM_OneStepOperation using AESGCM_Operation_init() or
 *       AESGCM_OneStepOperation_init(). For multi-step (segmented or multiple call)
 *       operations, AESGCM_SegmentedAADOperation must be initialized and set when
 *       processing AAD. AESGCM_SegmentedDataOperation must be initialized and set when
 *       dealing with payload data (plaintext or ciphertext). AESGCM_SegmentedFinalizeOperation
 *       must be initialized and set when finalizing the segmented operation.
 *
 *  ## Device-Specific Requirements #
 *
 *  For CC27XX devices, GCM operations leveraging the HSM engine
 *  (key encoding suffixed with _HSM) have the following requirements:
 *      - Output buffer address must be 32-bit aligned.
 *      - Input length must be a block-size (16-byte) multiple.
 *
 * #### 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()
 *
 * @anchor ti_drivers_AESGCM_Synopsis
 * ## Synopsis
 *
 * @anchor ti_drivers_AESGCM_Synopsis_Code
 * @code
 *
 * // Import AESGCM Driver definitions
 * #include <ti/drivers/AESGCM.h>
 *
 * // Define name for AESGCM channel index
 * #define AESGCM_INSTANCE 0
 *
 * AESGCM_init();
 *
 * handle = AESGCM_open(AESGCM_INSTANCE, NULL);
 *
 * // Initialize symmetric key
 * CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
 *
 * // Set up AESGCM_OneStepOperation
 * AESGCM_OneStepOperation_init(&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          = sizeof(iv);
 * operation.mac               = mac;
 * operation.macLength         = sizeof(mac);
 *
 * encryptionResult = AESGCM_oneStepEncrypt(handle, &operation);
 *
 * AESGCM_close(handle);
 * @endcode
 *
 * @anchor ti_drivers_AESGCM_Examples
 * #### Examples
 *
 * ##### Single call GCM encryption + authentication with plaintext CryptoKey in blocking return mode #
 *
 * @code
 *
 * #include <ti/drivers/AESGCM.h>
 * #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
 *
 * ...
 *
 * 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_OneStepOperation operation;
 * AESGCM_OneStepOperation_init(&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);
 *
 * @endcode
 *
 * <h4> The following code snippet is for CC27XX devices only and leverages the HSM which is a seperate Hardware
 * Accelerator </h4>
 *
 * ##### Single call GCM encryption + authentication with plaintext CryptoKey in blocking return mode
 * for the HSM accelerator #
 *
 * @code
 *
 * #include <ti/drivers/AESGCM.h>
 * #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
 *
 * ...
 *
 * 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
 * }
 *
 * CryptoKeyPlaintextHSM_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
 *
 * AESGCM_OneStepOperation operation;
 * AESGCM_OneStepOperation_init(&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);
 *
 * @endcode
 *
 * ##### Single call GCM decryption + verification with plaintext CryptoKey in callback return mode #
 *
 * @code
 *
 * #include <ti/drivers/AESGCM.h>
 * #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
 *
 * ...
 *
 * // 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_OperationUnion *operation,
 *                  AESGCM_OperationType operationType) {
 *
 *     if (returnValue != AESGCM_STATUS_SUCCESS) {
 *         // handle error
 *     }
 * }
 *
 * AESGCM_OneStepOperation operation;
 * CryptoKey cryptoKey;
 *
 * void gcmStartFunction(void) {
 *     AESGCM_Handle handle;
 *     AESGCM_Params params;
 *     int_fast16_t decryptionResult;
 *
 *     AESGCM_Params_init(&params);
 *     params.returnBehavior = AESGCM_RETURN_BEHAVIOR_CALLBACK;
 *     params.callbackFxn = gcmCallback;
 *
 *     handle = AESGCM_open(0, &params);
 *
 *     if (handle == NULL) {
 *         // handle error
 *     }
 *
 *     CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
 *
 *     AESGCM_OneStepOperation_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.ivLength          = sizeof(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
 *
 * }
 *
 * @endcode
 *
 * ### Multi-step GCM encryption + authentication with plaintext CryptoKey in blocking return mode #
 * @code
 *
 * #include <ti/drivers/AESGCM.h>
 * #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
 *
 * ...
 *
 * #define AES_BLOCK_SIZE      16 // bytes
 *
 * AESGCM_Handle handle;
 * CryptoKey cryptoKey;
 * int_fast16_t encryptionResult;
 *
 * uint8_t keyingMaterial[32]  = {0x58, 0x53, 0xc0, 0x20, 0x94, 0x6b, 0x35, 0xf2,
 *                                0xc5, 0x8e, 0xc4, 0x27, 0x15, 0x2b, 0x84, 0x04,
 *                                0x20, 0xc4, 0x00, 0x29, 0x63, 0x6a, 0xdc, 0xbb,
 *                                0x02, 0x74, 0x71, 0x37, 0x8c, 0xfd, 0xde, 0x0f};
 * uint8_t aad[20]             = {0x13, 0x89, 0xb5, 0x22, 0xc2, 0x4a, 0x77, 0x41,
 *                                0x81, 0x70, 0x05, 0x53, 0xf0, 0x24, 0x6b, 0xba,
 *                                0xbd, 0xd3, 0x8d, 0x6f};
 * uint8_t plaintext[32]       = {0xce, 0x74, 0x58, 0xe5, 0x6a, 0xef, 0x90, 0x61,
 *                                0xcb, 0x0c, 0x42, 0xec, 0x23, 0x15, 0x56, 0x5e,
 *                                0x61, 0x68, 0xf5, 0xa6, 0x24, 0x9f, 0xfd, 0x31,
 *                                0x61, 0x0b, 0x6d, 0x17, 0xab, 0x64, 0x93, 0x5e};
 * uint8_t iv[12]              = {0xee, 0xc3, 0x13, 0xdd, 0x07, 0xcc, 0x1b, 0x3e,
 *                                0x6b, 0x06, 0x8a, 0x47};
 * uint8_t mac[16];
 * uint8_t ciphertext[sizeof(plaintext)];
 *
 * // The ciphertext should be the following after the encryption operation:
 * //  {0xea, 0xdc, 0x3b, 0x87, 0x66, 0xa7, 0x7d, 0xed,
 * //  0x1a, 0x58, 0xcb, 0x72, 0x7e, 0xca, 0x2a, 0x97,
 * //  0x90, 0x49, 0x6c, 0x29, 0x86, 0x54, 0xcd, 0xa7,
 * //  0x8f, 0xeb, 0xf0, 0xda, 0x16, 0xb6, 0x90, 0x3b}
 *
 * handle = AESGCM_open(0, NULL);
 *
 * if (handle == NULL) {
 *     // handle error
 * }
 *
 * CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
 *
 * encryptionResult = AESGCM_setupEncrypt(handle, &cryptoKey, sizeof(aad), sizeof(plaintext));
 * if (decryptionResult != AESGCM_STATUS_SUCCESS) {
 *     // handle error
 * }
 *
 * encryptionResult = AESGCM_setIV(handle, iv, sizeof(iv));
 * if (encryptionResult != AESGCM_STATUS_SUCCESS) {
 *     // handle error
 * }
 *
 * AESGCM_SegmentedAADOperation segmentedAADOperation;
 * AESGCM_SegmentedAADOperation_init(&segmentedAADOperation);
 * segmentedAADOperation.aad = aad;
 *  // One should pass in data that is a block-sized multiple length
 *  // until passing in the last segment of data.
 *  // In that case, the input length simply needs to be a non-zero value.
 * segmentedAADOperation.aadLength = sizeof(aad);
 *
 * encryptionResult = AESGCM_addAAD(handle, &segmentedAADOperation);
 * if (encryptionResult != AESGCM_STATUS_SUCCESS) {
 *     // handle error
 * }
 *
 * AESGCM_SegmentedDataOperation segmentedDataOperation;
 * AESGCM_SegmentedDataOperation_init(&segmentedDataOperation);
 * segmentedDataOperation.input = plaintext;
 * segmentedDataOperation.output = ciphertext;
 *  // One should pass in data that is a block-sized multiple length
 *  // until passing in the last segment of data.
 *  // In that case, the input length simply needs to be a non-zero value.
 * segmentedDataOperation.inputLength = AES_BLOCK_SIZE;
 *
 * encryptionResult = AESGCM_addData(handle, &segmentedDataOperation);
 * if (encryptionResult != AESGCM_STATUS_SUCCESS) {
 *     // handle error
 * }
 *
 * AESGCM_SegmentedFinalizeOperation segmentedFinalizeOperation;
 * AESGCM_SegmentedFinalizeOperation_init(&egmentedFinalizeOperation);
 * segmentedFinalizeOperation.input = plaintext + AES_BLOCK_SIZE;
 * segmentedFinalizeOperation.output = ciphertext + AES_BLOCK_SIZE;
 * segmentedFinalizeOperation.inputLength = AES_BLOCK_SIZE;
 * segmentedFinalizeOperation.mac = mac;
 * segmentedFinalizeOperation.macLength = sizeof(mac);
 * encryptionResult = AESGCM_finalizeEncrypt(handle, &segmentedFinalizeOperation);
 *
 * if (encryptionResult != AESGCM_STATUS_SUCCESS) {
 *     // handle error
 * }
 *
 * AESGCM_close(handle);
 *
 * @endcode
 *
 * ### Multi-step GCM decryption + verification with plaintext CryptoKey in callback return mode #
 * @code
 *
 * #include <ti/drivers/AESGCM.h>
 * #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
 *
 * ...
 *
 * #define AES_BLOCK_SIZE      16 // bytes
 *
 * uint8_t iv[]                         = {0x7f, 0xc2, 0x5c, 0x0c, 0x7a, 0x65, 0xb9, 0x50,
 *                                         0x00, 0x23, 0xd0, 0x58};
 * uint8_t aad[]                        = {0x9e, 0xca, 0x27, 0x10, 0xbc, 0x1c, 0xaa, 0x99,
 *                                         0x50, 0x2d, 0xe3, 0x0f, 0x08, 0x94, 0x30, 0x69,
 *                                         0x7a, 0xee, 0xfc, 0x03};
 * uint8_t mac[]                        = {0x77, 0xb6, 0x4e, 0x40};
 * uint8_t ciphertext[]                 = {0xbd, 0xb4, 0x3f, 0x90, 0xf1, 0x6e, 0x26, 0xdc,
 *                                         0xff, 0x60, 0xdb, 0x92, 0xb9, 0x6c, 0x4a, 0x2f};
 *  uint8_t keyingMaterial[]            = {0xfb, 0x96, 0x31, 0x2b, 0xdb, 0x8a, 0x22, 0xf1,
 *                                         0x6f, 0xad, 0xc4, 0x23, 0x69, 0x4f, 0x45, 0x70};
 *  uint8_t plaintext[sizeof(ciphertext)];
 *
 *  // The plaintext should be the following after the decryption operation:
 *  //  {0xae, 0xe4, 0x16, 0xa2, 0x1f, 0x0e, 0x98, 0x3f,
 *  //  0xd7, 0x05, 0x20, 0xb8, 0xce, 0xdb, 0x24, 0xe5}
 *
 * void gcmCallback(AESGCM_Handle handle,
 *                  int_fast16_t returnValue,
 *                  AESGCM_OperationUnion *operation,
 *                  AESGCM_OperationType operationType) {
 *
 *     if (returnValue != AESGCM_STATUS_SUCCESS) {
 *         // handle error
 *     }
 *
 *     if(operationType == AESGCM_OPERATION_TYPE_DECRYPT ||
 *        operationType == AESGCM_OPERATION_TYPE_ENCRYPT)
 *     {
 *         // Callback fxn only used for one-shot operations
 *         // Use operation->oneStepOperation
 *     }
 *     else if(operationType == AESGCM_OP_TYPE_AAD_DECRYPT ||
 *             operationType == AESGCM_OP_TYPE_AAD_ENCRYPT)
 *     {
 *         // Callback fxn only used for segmented AAD operations
 *         // Use operation->segmentedAADOperation
 *     }
 *     else if(operationType == AESGCM_OP_TYPE_DATA_DECRYPT ||
 *             operationType == AESGCM_OP_TYPE_DATA_ENCRYPT)
 *     {
 *         // Callback fxn only used for segmented data operations
 *         // Use operation->segmentedDataOperation
 *     }
 *     else
 *     {
 *         // Callback fxn only used for segmented finalize operations
 *         // Use operation->segmentedFinalizeOperation
 *     }
 * }
 *
 * void gcmStartFunction(void) {
 *     AESGCM_Handle handle;
 *     AESGCM_Params params;
 *     CryptoKey cryptoKey;
 *     int_fast16_t decryptionResult;
 *
 *     AESGCM_Params_init(&params);
 *     params.returnBehavior = AESGCM_RETURN_BEHAVIOR_CALLBACK;
 *     params.callbackFxn = gcmCallback;
 *
 *     handle = AESGCM_open(0, &params);
 *
 *     if (handle == NULL) {
 *         // handle error
 *     }
 *
 *     CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
 *
 *     decryptionResult = AESGCM_setupDecrypt(handle, &cryptoKey, 0, 0);
 *     if (decryptionResult != AESGCM_STATUS_SUCCESS) {
 *         // handle error
 *     }
 *
 *     // setLengths must be called if the AAD and input lengths aren't provided in setupXXXX.
 *     decryptionResult = AESGCM_setLengths(handle, sizeof(aad), sizeof(ciphertext));
 *     if (decryptionResult != AESGCM_STATUS_SUCCESS) {
 *         // handle error
 *     }
 *
 *     decryptionResult = AESGCM_setIV(handle, iv, sizeof(iv));
 *     if (decryptionResult != AESGCM_STATUS_SUCCESS) {
 *         // handle error
 *     }
 *
 *     AESGCM_SegmentedAADOperation segmentedAADOperation;
 *     AESGCM_SegmentedAADOperation_init(&segmentedAADOperation);
 *     segmentedAADOperation.aad = aad;
 *     segmentedAADOperation.aadLength = sizeof(aad);
 *
 *     decryptionResult = AESGCM_addAAD(handle, &segmentedAADOperation);
 *     if (decryptionResult != AESGCM_STATUS_SUCCESS) {
 *         // handle error
 *     }
 *
 *     AESGCM_SegmentedDataOperation segmentedDataOperation;
 *     AESGCM_SegmentedDataOperation_init(&segmentedDataOperation);
 *     segmentedDataOperation.input = ciphertext;
 *     segmentedDataOperation.output = plaintext;
 *     segmentedDataOperation.inputLength = AES_BLOCK_SIZE;
 *
 *     decryptionResult = AESGCM_addData(handle, &segmentedDataOperation);
 *     if (decryptionResult != AESGCM_STATUS_SUCCESS) {
 *         // handle error
 *     }
 *
 *     AESGCM_SegmentedFinalizeOperation segmentedFinalizeOperation;
 *     AESGCM_SegmentedFinalizeOperation_init(&egmentedFinalizeOperation);
 *     segmentedFinalizeOperation.input = ciphertext;
 *     segmentedFinalizeOperation.output = plaintext;
 *
 *     // You can finalize with no new data
 *     segmentedFinalizeOperation.inputLength = 0;
 *     segmentedFinalizeOperation.mac = mac;
 *     segmentedFinalizeOperation.macLength = sizeof(mac);
 *
 *     decryptionResult = AESGCM_finalizeDecrypt(handle, &segmentedFinalizeOperation);
 *     if (decryptionResult != AESGCM_STATUS_SUCCESS) {
 *         // handle error
 *     }
 *
 *     // do other things while GCM operation completes in the background
 *
 * }
 *
 * @endcode
 */

#ifndef ti_drivers_AESGCM__include
#define ti_drivers_AESGCM__include

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

#include <ti/drivers/AESCommon.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Only IVs with a length of 12 bytes are supported for now */
#define AESGCM_IV_LENGTH_BYTES 12

#define AESGCM_STATUS_RESERVED AES_STATUS_RESERVED

#define AESGCM_STATUS_SUCCESS  AES_STATUS_SUCCESS

#define AESGCM_STATUS_ERROR AES_STATUS_ERROR

#define AESGCM_STATUS_RESOURCE_UNAVAILABLE AES_STATUS_RESOURCE_UNAVAILABLE

#define AESGCM_STATUS_CANCELED AES_STATUS_CANCELED

#define AESGCM_STATUS_MAC_INVALID AES_STATUS_MAC_INVALID

#define AESGCM_STATUS_FEATURE_NOT_SUPPORTED AES_STATUS_FEATURE_NOT_SUPPORTED

#define AESGCM_STATUS_KEYSTORE_INVALID_ID AES_STATUS_KEYSTORE_INVALID_ID

#define AESGCM_STATUS_KEYSTORE_GENERIC_ERROR AES_STATUS_KEYSTORE_GENERIC_ERROR

#define AESGCM_STATUS_UNALIGNED_IO_NOT_SUPPORTED AES_STATUS_UNALIGNED_IO_NOT_SUPPORTED

typedef AESCommon_Config AESGCM_Config;
typedef AESGCM_Config *AESGCM_Handle;

typedef enum
{
    AESGCM_RETURN_BEHAVIOR_CALLBACK = AES_RETURN_BEHAVIOR_CALLBACK,
    AESGCM_RETURN_BEHAVIOR_BLOCKING = AES_RETURN_BEHAVIOR_BLOCKING,
    AESGCM_RETURN_BEHAVIOR_POLLING  = AES_RETURN_BEHAVIOR_POLLING,
} AESGCM_ReturnBehavior;

typedef enum
{
    AESGCM_MODE_ENCRYPT = 1,
    AESGCM_MODE_DECRYPT = 2,
} AESGCM_Mode;

typedef struct
{
    CryptoKey *key;             
    uint8_t *aad;               
    uint8_t *input;             
    uint8_t *output;            
    uint8_t *iv;                
    uint8_t *mac;               
    size_t aadLength;           
    size_t inputLength;         
    uint8_t ivLength;           
    uint8_t macLength;          
    bool ivInternallyGenerated; 
} AESGCM_OneStepOperation;

typedef struct
{
    uint8_t *aad;     
    size_t aadLength; 
} AESGCM_SegmentedAADOperation;

typedef struct
{
    uint8_t *input;     
    uint8_t *output;    
    size_t inputLength; 
} AESGCM_SegmentedDataOperation;

typedef struct
{
    uint8_t *input;     
    uint8_t *output;    
    uint8_t *mac;       
    size_t inputLength; 
    uint8_t macLength;  
} AESGCM_SegmentedFinalizeOperation;

typedef AESGCM_OneStepOperation AESGCM_Operation;

typedef union AESGCM_OperationUnion
{
    AESGCM_OneStepOperation oneStepOperation;             /* One-step operation element of the operation union */
    AESGCM_SegmentedAADOperation segmentedAADOperation;   /* Segmented AAD operation element of the operation union */
    AESGCM_SegmentedDataOperation segmentedDataOperation; /* Segmented data operation element of the operation union */
    AESGCM_SegmentedFinalizeOperation segmentedFinalizeOperation; /* Segmented finalize operation element of the
                                                                     operation union */
} AESGCM_OperationUnion;

typedef enum
{
    AESGCM_OPERATION_TYPE_ENCRYPT   = 1, /* Fields 1 and 2 are for backward compatibility */
    AESGCM_OPERATION_TYPE_DECRYPT   = 2,
    AESGCM_OP_TYPE_ONESTEP_ENCRYPT  = 1, /* Names changed to _OP_TYPE_ to avoid MISRA deviation from first 31 chars not
                                            being unique */
    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,
} AESGCM_OperationType;

typedef void (*AESGCM_CallbackFxn)(AESGCM_Handle handle,
                                   int_fast16_t returnValue,
                                   AESGCM_OperationUnion *operation,
                                   AESGCM_OperationType operationType);

typedef struct
{
    AESGCM_ReturnBehavior returnBehavior; 
    AESGCM_CallbackFxn callbackFxn;       
    uint32_t timeout;                     
    void *custom;                         
} AESGCM_Params;

extern const AESGCM_Params AESGCM_defaultParams;

void AESGCM_init(void);

void AESGCM_Params_init(AESGCM_Params *params);

AESGCM_Handle AESGCM_open(uint_least8_t index, const AESGCM_Params *params);

void AESGCM_close(AESGCM_Handle handle);

int_fast16_t AESGCM_setupEncrypt(AESGCM_Handle handle,
                                 const CryptoKey *key,
                                 size_t totalAADLength,
                                 size_t totalPlaintextLength);

int_fast16_t AESGCM_setupDecrypt(AESGCM_Handle handle,
                                 const CryptoKey *key,
                                 size_t totalAADLength,
                                 size_t totalPlaintextLength);

int_fast16_t AESGCM_setLengths(AESGCM_Handle handle, size_t aadLength, size_t plaintextLength);

int_fast16_t AESGCM_setIV(AESGCM_Handle handle, const uint8_t *iv, size_t ivLength);

int_fast16_t AESGCM_generateIV(AESGCM_Handle handle, uint8_t *iv, size_t ivSize, size_t *ivLength);

int_fast16_t AESGCM_addAAD(AESGCM_Handle handle, AESGCM_SegmentedAADOperation *operation);

int_fast16_t AESGCM_addData(AESGCM_Handle handle, AESGCM_SegmentedDataOperation *operation);

int_fast16_t AESGCM_finalizeEncrypt(AESGCM_Handle handle, AESGCM_SegmentedFinalizeOperation *operation);

int_fast16_t AESGCM_finalizeDecrypt(AESGCM_Handle handle, AESGCM_SegmentedFinalizeOperation *operation);

void AESGCM_Operation_init(AESGCM_Operation *operationStruct);

void AESGCM_OneStepOperation_init(AESGCM_OneStepOperation *operationStruct);

void AESGCM_SegmentedAADOperation_init(AESGCM_SegmentedAADOperation *operationStruct);

void AESGCM_SegmentedDataOperation_init(AESGCM_SegmentedDataOperation *operationStruct);

void AESGCM_SegmentedFinalizeOperation_init(AESGCM_SegmentedFinalizeOperation *operationStruct);

int_fast16_t AESGCM_oneStepEncrypt(AESGCM_Handle handle, AESGCM_OneStepOperation *operationStruct);

int_fast16_t AESGCM_oneStepDecrypt(AESGCM_Handle handle, AESGCM_OneStepOperation *operationStruct);

int_fast16_t AESGCM_cancelOperation(AESGCM_Handle handle);

AESGCM_Handle AESGCM_construct(AESGCM_Config *config, const AESGCM_Params *params);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_AESGCM__include */