AESCTR.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       AESCTR.h
 *
 * @brief      AESCTR driver header
 *
 * @anchor ti_drivers_AESCTR_Overview
 * <h3> Overview </h3>
 * The Counter (CTR) mode of operation is a generic block cipher mode of operation
 * that can be used with any block cipher including AES which is used in this
 * implementation.
 *
 * CTR mode encrypts and decrypts messages. It is not required for the message
 * length to be evenly divisible by the cipher block size. This also means
 * that padding the message is not required.
 *
 * <h3> Operation </h3>
 * CTR encryption and decryption perform the following steps:
 *     -# Set the counter value to the initial counter value
 *     -# Encrypt the counter value under the symmetric key
 *     -# XOR the encrypted counter value with the input block (plaintext or ciphertext)
 *     -# Increment the counter value. Interpret the byte array as a big-endian number.
 *     -# Repeat steps 2 to 4 until the input is completely processed. If the
 *        input is not evenly divisible by the block size, XOR the last
 *        (u = input length % block size) input bytes with the most significant
 *        u bytes of the last encrypted counter value.
 *
 * CTR performs the same steps regardless of whether it is used to
 * encrypt or decrypt a message. The input merely changes.
 *
 * <h3> Choosing Initial Counter Values </h3>
 * CTR requires that each counter value used to encrypt a block of a message
 * is unique for each key used. If this requirement is not kept, the
 * confidentiality of that message block may be compromised.
 *
 * There are two general strategies when choosing the initial counter value
 * of a CTR operation to ensure this requirement holds.
 *
 * The first is to choose an initial counter value for the first message
 * and increment the initial counter value for a subsequent message by
 * by message length % block length (16-bytes for AES). This effectively
 * turns a sequence of messages into one long message. If 0 is chosen
 * as the initial counter value, up to 2^128 - 1 blocks may be encrypted before
 * key rotation is mandatory.
 *
 * The second is to split the initial counter value into a nonce and
 * counter section. The nonce of length n bits must be unique per message.
 * This allows for up to 2^n - 1 messages to be encrypted before
 * key rotation is required. The counter section of length c is incremented
 * as usual. This limits messages to a length of at most 2^c - 1 blocks.
 * n and c must be chosen such that n + c = block length in bits
 * (128 bits for AES) holds.
 *
 * @anchor ti_drivers_AESCTR_Usage
 * <h3> Usage </h3>
 * <h4> Before starting a CTR operation </h4>
 *
 * Before starting a CTR operation, the application must do the following:
 *     - Call #AESCTR_init() to initialize the driver
 *     - Call #AESCTR_Params_init() to initialize the #AESCTR_Params to default values.
 *     - Modify the #AESCTR_Params as desired
 *     - Call #AESCTR_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 AESCTR 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 a single-step AESCTR operation using #AESCTR_OneStepOperation_init()
 *       which is equivalent to the deprecated #AESCTR_Operation_init(). If it's
 *       a segmented AESCTR operation, use #AESCTR_SegmentedOperation_init() instead.
 *       Then set all the fields of the one-step or segmented operation struct accordingly.
 *
 * <h4> Starting a CTR operation </h4>
 *
 * The AESCTR_oneStepEncrypt() and AESCTR_oneStepDecrypt() functions perform a CTR operation
 * in a single call.
 *
 * <h4> After the CTR operation completes </h4>
 *
 * After the CTR operation completes, the application should either start
 * another operation or close the driver by calling #AESCTR_close().
 *
 * @anchor ti_drivers_AESCTR_Synopsis
 * ## Synopsis
 *
 * @anchor ti_drivers_AESCTR_Synopsis_Code
 * @code
 *
 * // Import AESCTR Driver definitions
 * #include <ti/drivers/AESCTR.h>
 *
 * // Define name for AESCTR channel index
 * #define AESCTR_INSTANCE 0
 *
 * AESCTR_init();
 *
 * handle = AESCTR_open(AESCTR_INSTANCE, NULL);
 *
 * // Initialize symmetric key
 * CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
 *
 * // Set up AESCTR_Operation
 * AESCTR_OneStepOperation_init(&operation);
 * operation.key               = &cryptoKey;
 * operation.input             = plaintext;
 * operation.output            = ciphertext;
 * operation.inputLength       = sizeof(plaintext);
 * operation.initialCounter    = initialCounter;
 *
 * encryptionResult = AESCTR_oneStepEncrypt(handle, &operation);
 *
 * AESCTR_close(handle);
 * @endcode
 *
 * @anchor ti_drivers_AESCTR_Examples
 * <h4> Examples </h4>
 *
 * <h5> One step CTR encryption with plaintext CryptoKey in blocking return mode </h5>
 * @code
 *
 * #include <ti/drivers/AESCTR.h>
 * #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
 *
 * ...
 *
 *     AESCTR_Handle handle;
 *     CryptoKey cryptoKey;
 *     int_fast16_t encryptionResult;
 *
 *     // For example purposes only. Generate IVs in a non-static way in practice.
 *     // Test vector from NIST SP 800-38A
 *     uint8_t initialCounter[16] =    {0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7,
 *                                      0xf8, 0xf9, 0xfa, 0xfb, 0xfc, 0xfd, 0xfe, 0xff};
 *     uint8_t plaintext[64] =         {0x6b, 0xc1, 0xbe, 0xe2, 0x2e, 0x40, 0x9f, 0x96,
 *                                      0xe9, 0x3d, 0x7e, 0x11, 0x73, 0x93, 0x17, 0x2a,
 *                                      0xae, 0x2d, 0x8a, 0x57, 0x1e, 0x03, 0xac, 0x9c,
 *                                      0x9e, 0xb7, 0x6f, 0xac, 0x45, 0xaf, 0x8e, 0x51,
 *                                      0x30, 0xc8, 0x1c, 0x46, 0xa3, 0x5c, 0xe4, 0x11,
 *                                      0xe5, 0xfb, 0xc1, 0x19, 0x1a, 0x0a, 0x52, 0xef,
 *                                      0xf6, 0x9f, 0x24, 0x45, 0xdf, 0x4f, 0x9b, 0x17,
 *                                      0xad, 0x2b, 0x41, 0x7b, 0xe6, 0x6c, 0x37, 0x10};
 *     uint8_t ciphertext[sizeof(plaintext)];
 *     uint8_t keyingMaterial[16] =    {0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6,
 *                                      0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf, 0x4f, 0x3c};
 *
 *     handle = AESCTR_open(0, NULL);
 *
 *     if (handle == NULL) {
 *         // handle error
 *         while(1);
 *     }
 *
 *     CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
 *
 *     AESCTR_OneStepOperation operation;
 *     AESCTR_OneStepOperation_init(&operation);
 *
 *     operation.key               = &cryptoKey;
 *     operation.input             = plaintext;
 *     operation.output            = ciphertext;
 *     operation.inputLength       = sizeof(plaintext);
 *     operation.initialCounter    = initialCounter;
 *
 *     encryptionResult = AESCTR_oneStepEncrypt(handle, &operation);
 *
 *     if (encryptionResult != AESCTR_STATUS_SUCCESS) {
 *         // handle error
 *         while(1);
 *     }
 *
 *     // The ciphertext should be the following after the encryption operation:
 *     // 0x87, 0x4d, 0x61, 0x91, 0xb6, 0x20, 0xe3, 0x26,
 *     // 0x1b, 0xef, 0x68, 0x64, 0x99, 0x0d, 0xb6, 0xce,
 *     // 0x98, 0x06, 0xf6, 0x6b, 0x79, 0x70, 0xfd, 0xff,
 *     // 0x86, 0x17, 0x18, 0x7b, 0xb9, 0xff, 0xfd, 0xff,
 *     // 0x5a, 0xe4, 0xdf, 0x3e, 0xdb, 0xd5, 0xd3, 0x5e,
 *     // 0x5b, 0x4f, 0x09, 0x02, 0x0d, 0xb0, 0x3e, 0xab,
 *     // 0x1e, 0x03, 0x1d, 0xda, 0x2f, 0xbe, 0x03, 0xd1,
 *     // 0x79, 0x21, 0x70, 0xa0, 0xf3, 0x00, 0x9c, 0xee
 *
 *     AESCTR_close(handle);
 *
 * @endcode
 *
 * <h4> The following code snippet is for CC27XX devices only and leverages the HSM which is a seperate Hardware
 * Accelerator </h4>
 *
 * <h5> One step CTR encryption with plaintext CryptoKey in blocking return mode using the HSM accelerator </h5>
 * @code
 *
 * #include <ti/drivers/AESCTR.h>
 * #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
 *
 * ...
 *
 *     AESCTR_Handle handle;
 *     CryptoKey cryptoKey;
 *     int_fast16_t encryptionResult;
 *
 *     // For example purposes only. Generate IVs in a non-static way in practice.
 *     // Test vector from NIST SP 800-38A
 *     uint8_t initialCounter[16] =    {0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7,
 *                                      0xf8, 0xf9, 0xfa, 0xfb, 0xfc, 0xfd, 0xfe, 0xff};
 *     uint8_t plaintext[64] =         {0x6b, 0xc1, 0xbe, 0xe2, 0x2e, 0x40, 0x9f, 0x96,
 *                                      0xe9, 0x3d, 0x7e, 0x11, 0x73, 0x93, 0x17, 0x2a,
 *                                      0xae, 0x2d, 0x8a, 0x57, 0x1e, 0x03, 0xac, 0x9c,
 *                                      0x9e, 0xb7, 0x6f, 0xac, 0x45, 0xaf, 0x8e, 0x51,
 *                                      0x30, 0xc8, 0x1c, 0x46, 0xa3, 0x5c, 0xe4, 0x11,
 *                                      0xe5, 0xfb, 0xc1, 0x19, 0x1a, 0x0a, 0x52, 0xef,
 *                                      0xf6, 0x9f, 0x24, 0x45, 0xdf, 0x4f, 0x9b, 0x17,
 *                                      0xad, 0x2b, 0x41, 0x7b, 0xe6, 0x6c, 0x37, 0x10};
 *     uint8_t ciphertext[sizeof(plaintext)];
 *     uint8_t keyingMaterial[16] =    {0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6,
 *                                      0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf, 0x4f, 0x3c};
 *
 *     handle = AESCTR_open(0, NULL);
 *
 *     if (handle == NULL) {
 *         // handle error
 *         while(1);
 *     }
 *
 *     CryptoKeyPlaintextHSM_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
 *
 *     AESCTR_OneStepOperation operation;
 *     AESCTR_OneStepOperation_init(&operation);
 *
 *     operation.key               = &cryptoKey;
 *     operation.input             = plaintext;
 *     operation.output            = ciphertext;
 *     operation.inputLength       = sizeof(plaintext);
 *     operation.initialCounter    = initialCounter;
 *
 *     encryptionResult = AESCTR_oneStepEncrypt(handle, &operation);
 *
 *     if (encryptionResult != AESCTR_STATUS_SUCCESS) {
 *         // handle error
 *         while(1);
 *     }
 *
 *     // The ciphertext should be the following after the encryption operation:
 *     // 0x87, 0x4d, 0x61, 0x91, 0xb6, 0x20, 0xe3, 0x26,
 *     // 0x1b, 0xef, 0x68, 0x64, 0x99, 0x0d, 0xb6, 0xce,
 *     // 0x98, 0x06, 0xf6, 0x6b, 0x79, 0x70, 0xfd, 0xff,
 *     // 0x86, 0x17, 0x18, 0x7b, 0xb9, 0xff, 0xfd, 0xff,
 *     // 0x5a, 0xe4, 0xdf, 0x3e, 0xdb, 0xd5, 0xd3, 0x5e,
 *     // 0x5b, 0x4f, 0x09, 0x02, 0x0d, 0xb0, 0x3e, 0xab,
 *     // 0x1e, 0x03, 0x1d, 0xda, 0x2f, 0xbe, 0x03, 0xd1,
 *     // 0x79, 0x21, 0x70, 0xa0, 0xf3, 0x00, 0x9c, 0xee
 *
 *     AESCTR_close(handle);
 *
 * @endcode
 *
 * <h5> One step CTR decryption with plaintext CryptoKey in callback return mode </h5>
 * @code
 *
 * #include <ti/drivers/AESCTR.h>
 * #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
 *
 * ...
 *
 *
 * void ctrCallback(AESCTR_Handle handle,
 *                  int_fast16_t returnValue,
 *                  AESCTR_OperationUnion *operation,
 *                  AESCTR_OperationType operationType) {
 *
 *     if (returnValue != AESCTR_STATUS_SUCCESS) {
 *         // handle error
 *         while(1);
 *     }
 * }
 * AESCTR_Operation operation;
 *
 * void ctrStartFunction(void) {
 *     uint8_t initialCounter[16] =  {0x00, 0xE0, 0x01, 0x7B, 0x27, 0x77, 0x7F, 0x3F,
 *                                    0x4A, 0x17, 0x86, 0xF0, 0x00, 0x00, 0x00, 0x01};
 *     uint8_t ciphertext[] =        {0xC1, 0xCF, 0x48, 0xA8, 0x9F, 0x2F, 0xFD, 0xD9,
 *                                    0xCF, 0x46, 0x52, 0xE9, 0xEF, 0xDB, 0x72, 0xD7,
 *                                    0x45, 0x40, 0xA4, 0x2B, 0xDE, 0x6D, 0x78, 0x36,
 *                                    0xD5, 0x9A, 0x5C, 0xEA, 0xAE, 0xF3, 0x10, 0x53,
 *                                    0x25, 0xB2, 0x07, 0x2F};
 *     uint8_t keyingMaterial[] =    {0x76, 0x91, 0xBE, 0x03, 0x5E, 0x50, 0x20, 0xA8,
 *                                    0xAC, 0x6E, 0x61, 0x85, 0x29, 0xF9, 0xA0, 0xDC};
 *     uint8_t plaintext[sizeof(ciphertext)];
 *
 *     AESCTR_Handle handle;
 *     AESCTR_Params params;
 *     CryptoKey cryptoKey;
 *     int_fast16_t decryptionResult;
 *
 *     AESCTR_OneStepOperation operation;
 *
 *     AESCTR_Params_init(&params);
 *     params.returnBehavior = AESCTR_RETURN_BEHAVIOR_CALLBACK;
 *     params.callbackFxn = ctrCallback;
 *
 *     handle = AESCTR_open(0, &params);
 *
 *     if (handle == NULL) {
 *         // handle error
 *         while(1);
 *     }
 *
 *     CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
 *
 *     AESCTR_OneStepOperation_init(&operation); // Optional as all struct members will be set before use.
 *
 *     operation.key               = &cryptoKey;
 *     operation.input             = ciphertext;
 *     operation.output            = plaintext;
 *     operation.inputLength       = sizeof(ciphertext);
 *     operation.initialCounter    = initialCounter;
 *
 *     decryptionResult = AESCTR_oneStepDecrypt(handle, &operation);
 *
 *     if (decryptionResult != AESCTR_STATUS_SUCCESS) {
 *         // handle error
 *         while(1);
 *     }
 *
 *     // do other things while CTR operation completes in the background
 *
 *     // After the operation completes and the callback is invoked, the resultant
 *     // plaintext should be:
 *     // 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,
 *     // 0x20, 0x21, 0x22, 0x23
 *
 *     AESCTR_close(handle);
 * }
 *
 * @endcode
 *
 *  <h5> Multi-step AES CTR encrypt with plaintext CryptoKey in polling return mode </h5>
 *  @code
 *
 *  #include <ti/drivers/AESCTR.h>
 *  #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
 *
 *  #define AES_BLOCK_SIZE 16  // bytes
 *  ...
 *
 *  AESCTR_Params params;
 *  AESCTR_Handle handle;
 *  CryptoKey cryptoKey;
 *  int_fast16_t retVal;
 *
 *  // For example purposes only.
 *  uint8_t plaintext[36] =    {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,
 *                              0x20, 0x21, 0x22, 0x23};
 *  uint8_t initialCounter[] = {0x00, 0xE0, 0x01, 0x7B, 0x27, 0x77, 0x7F, 0x3F,
 *                              0x4A, 0x17, 0x86, 0xF0, 0x00, 0x00, 0x00, 0x01};
 *  uint8_t keyingMaterial[] = {0x76, 0x91, 0xBE, 0x03, 0x5E, 0x50, 0x20, 0xA8,
 *                              0xAC, 0x6E, 0x61, 0x85, 0x29, 0xF9, 0xA0, 0xDC};
 *  uint8_t ciphertext[sizeof(plaintext)];
 *
 *  AESCTR_Params_init(&params)
 *  params.returnBehavior = AESCTR_RETURN_BEHAVIOR_POLLING;
 *
 *  handle = AESCTR_open(0, &params);
 *
 *  if (handle == NULL) {
 *      // handle error
 *  }
 *
 *  CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
 *
 *  AESCTR_SegmentedOperation operation;
 *  AESCTR_SegmentedOperation_init(&operation); // Optional as all struct members will be set before use.
 *
 *  retVal = AESCTR_setupEncrypt(handle, &cryptoKey, initialCounter);
 *
 *  if (retVal != AESCTR_STATUS_SUCCESS) {
 *      // handle error
 *  }
 *
 *  operation.input        = plaintext;
 *  operation.inputLength  = AES_BLOCK_SIZE;  // Only block multiple lengths are permitted when adding data.
 *  operation.output       = ciphertext;
 *
 *  retVal = AESCTR_addData(handle, &operation);
 *
 *  if (retVal != AESCTR_STATUS_SUCCESS) {
 *      // handle error
 *  }
 *
 *  operation.input        = plaintext + AES_BLOCK_SIZE;
 *  operation.inputLength  = sizeof(plaintext) - AES_BLOCK_SIZE;  // Non-block multiple length permitted during
 * finalization. operation.output       = ciphertext + AES_BLOCK_SIZE;
 *
 *  retVal = AESCTR_finalize(handle, &operation);
 *
 *  if (retVal != AESCTR_STATUS_SUCCESS) {
 *      // handle error
 *  }
 *
 *  // Upon successful return, the resulting ciphertext should be:
 *  //   0xC1, 0xCF, 0x48, 0xA8, 0x9F, 0x2F, 0xFD, 0xD9,
 *  //   0xCF, 0x46, 0x52, 0xE9, 0xEF, 0xDB, 0x72, 0xD7,
 *  //   0x45, 0x40, 0xA4, 0x2B, 0xDE, 0x6D, 0x78, 0x36,
 *  //   0xD5, 0x9A, 0x5C, 0xEA, 0xAE, 0xF3, 0x10, 0x53,
 *  //   0x25, 0xB2, 0x07, 0x2F
 *
 *  AESCTR_close(handle);
 *
 *  @endcode
 */

#ifndef ti_drivers_AESCTR__include
#define ti_drivers_AESCTR__include

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

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

#ifdef __cplusplus
extern "C" {
#endif

#define AESCTR_STATUS_RESERVED AES_STATUS_RESERVED

#define AESCTR_STATUS_SUCCESS AES_STATUS_SUCCESS

#define AESCTR_STATUS_ERROR AES_STATUS_ERROR

#define AESCTR_STATUS_RESOURCE_UNAVAILABLE AES_STATUS_RESOURCE_UNAVAILABLE

#define AESCTR_STATUS_CANCELED AES_STATUS_CANCELED

#define AESCTR_STATUS_FEATURE_NOT_SUPPORTED AES_STATUS_FEATURE_NOT_SUPPORTED

#define AESCTR_STATUS_KEYSTORE_INVALID_ID AES_STATUS_KEYSTORE_INVALID_ID

#define AESCTR_STATUS_KEYSTORE_GENERIC_ERROR AES_STATUS_KEYSTORE_GENERIC_ERROR

#define AESCTR_STATUS_UNALIGNED_IO_NOT_SUPPORTED AES_STATUS_UNALIGNED_IO_NOT_SUPPORTED

typedef enum
{
    AESCTR_RETURN_BEHAVIOR_CALLBACK = AES_RETURN_BEHAVIOR_CALLBACK,
    AESCTR_RETURN_BEHAVIOR_BLOCKING = AES_RETURN_BEHAVIOR_BLOCKING,
    AESCTR_RETURN_BEHAVIOR_POLLING  = AES_RETURN_BEHAVIOR_POLLING,
} AESCTR_ReturnBehavior;

typedef struct
{
    const CryptoKey *key;          
    const uint8_t *input;          
    uint8_t *output;               
    const uint8_t *initialCounter; 
    size_t inputLength;            
} AESCTR_OneStepOperation;

typedef struct
{
    const uint8_t *input; 
    uint8_t *output;      
    size_t inputLength;   
} AESCTR_SegmentedOperation;

typedef AESCTR_OneStepOperation AESCTR_Operation;

typedef union
{
    AESCTR_OneStepOperation oneStepOperation;     /* One-step operation element of the operation union */
    AESCTR_SegmentedOperation segmentedOperation; /* Segmented operation element of the operation union */
} AESCTR_OperationUnion;

typedef enum
{
    AESCTR_MODE_ENCRYPT = 1,
    AESCTR_MODE_DECRYPT = 2,
} AESCTR_Mode;

#define AESCTR_OP_MODE_MASK 0x0F

#define AESCTR_OP_FLAG_SEGMENTED 0x10 /* bit 4 */

#define AESCTR_OP_FLAG_FINALIZE 0x20 /* bit 5 */

#define AESCTR_OP_FLAGS_MASK (AESCTR_OP_FLAG_SEGMENTED | AESCTR_OP_FLAG_FINALIZE)

typedef enum
{
    AESCTR_OPERATION_TYPE_ENCRYPT           = AESCTR_MODE_ENCRYPT,
    AESCTR_OPERATION_TYPE_DECRYPT           = AESCTR_MODE_DECRYPT,
    AESCTR_OPERATION_TYPE_ENCRYPT_SEGMENTED = (AESCTR_MODE_ENCRYPT | AESCTR_OP_FLAG_SEGMENTED),
    AESCTR_OPERATION_TYPE_DECRYPT_SEGMENTED = (AESCTR_MODE_DECRYPT | AESCTR_OP_FLAG_SEGMENTED),
    AESCTR_OPERATION_TYPE_ENCRYPT_FINALIZE  = (AESCTR_MODE_ENCRYPT | AESCTR_OP_FLAG_FINALIZE),
    AESCTR_OPERATION_TYPE_DECRYPT_FINALIZE  = (AESCTR_MODE_DECRYPT | AESCTR_OP_FLAG_FINALIZE),
} AESCTR_OperationType;

typedef AESCommon_Config AESCTR_Config;

typedef AESCTR_Config *AESCTR_Handle;

typedef void (*AESCTR_CallbackFxn)(AESCTR_Handle handle,
                                   int_fast16_t returnValue,
                                   AESCTR_OperationUnion *operation,
                                   AESCTR_OperationType operationType);

typedef struct
{
    AESCTR_ReturnBehavior returnBehavior; 
    AESCTR_CallbackFxn callbackFxn;       
    uint32_t timeout;                     
    void *custom;                         
} AESCTR_Params;

extern const AESCTR_Params AESCTR_defaultParams;

void AESCTR_init(void);

void AESCTR_Params_init(AESCTR_Params *params);

AESCTR_Handle AESCTR_open(uint_least8_t index, const AESCTR_Params *params);

void AESCTR_close(AESCTR_Handle handle);

int_fast16_t AESCTR_setupEncrypt(AESCTR_Handle handle, const CryptoKey *key, const uint8_t *initialCounter);

int_fast16_t AESCTR_setupDecrypt(AESCTR_Handle handle, const CryptoKey *key, const uint8_t *initialCounter);

int_fast16_t AESCTR_addData(AESCTR_Handle handle, AESCTR_SegmentedOperation *operation);

int_fast16_t AESCTR_finalize(AESCTR_Handle handle, AESCTR_SegmentedOperation *operation);

void AESCTR_Operation_init(AESCTR_Operation *operation);

void AESCTR_OneStepOperation_init(AESCTR_OneStepOperation *operation);

void AESCTR_SegmentedOperation_init(AESCTR_SegmentedOperation *operation);

int_fast16_t AESCTR_oneStepEncrypt(AESCTR_Handle handle, AESCTR_OneStepOperation *operation);

int_fast16_t AESCTR_oneStepDecrypt(AESCTR_Handle handle, AESCTR_OneStepOperation *operation);

int_fast16_t AESCTR_cancelOperation(AESCTR_Handle handle);

AESCTR_Handle AESCTR_construct(AESCTR_Config *config, const AESCTR_Params *params);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_AESCTR__include */