AESECB.h

Go to the documentation of this file.

/*
 * Copyright (c) 2017-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       AESECB.h
 *
 *  @brief      AESECB driver header
 *
 *  @anchor ti_drivers_AESECB_Overview
 *  # Overview #
 *  The Electronic Code Book (ECB) mode of operation is a generic
 *  encryption block cipher mode. It can be used with any block cipher.
 *  AESECB encrypts or decrypts one or multiple blocks of plaintext or ciphertext
 *  using the Advanced Encryption Standard (AES) block cipher.
 *  Each input block is individually encrypted or decrypted. This means that
 *  blocks of ciphertext can be decrypted individually and out of order.
 *  Encrypting the same plaintext using the same key yields identical ciphertext.
 *  This raises several security issues. For this reason, ECB is not recommended
 *  unless interfacing with legacy systems which cannot be updated
 *  or where a standard specifies its use. Better alternatives would be an
 *  authenticated encryption with associated data (AEAD) mode such as
 *  CCM or GCM.
 *
 *  The AES key is a shared secret between the two parties and has a length
 *  of 128, 192, or 256 bits.
 *
 *  @anchor ti_drivers_AESECB_Usage
 *  # Usage #
 *
 *  ## Before starting an ECB operation #
 *
 *  Before starting an ECB operation, the application must do the following:
 *      - Call AESECB_init() to initialize the driver
 *      - Call AESECB_Params_init() to initialize the AESECB_Params to default values.
 *      - Modify the AESECB_Params as desired
 *      - Call AESECB_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 AESECB 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 AESECB_Operation using AESECB_Operation_init() and set all
 *        length, key, and buffer fields.
 *
 *  ## Starting an ECB operation #
 *
 *  The AESECB_oneStepEncrypt and AESECB_oneStepDecrypt functions do an ECB operation in a single call.
 *  They will always be the most highly optimized routines with the least overhead and the fastest
 *  runtime. Since ECB plaintext blocks are simply encrypted with the block cipher block by block,
 *  there is no difference in the ciphertext between encrypting two blocks in one go or encrypting
 *  each block individually.
 *
 *  ## Device-Specific Requirements #
 *
 *  For CC27XX devices, ECB operations leveraging the HSM engine
 *  (key encoding suffixed with _HSM) have the following requirements:
 *      - Output buffer address must be 32-bit aligned.
 *
 *  ## After the ECB operation completes #
 *
 *  After the ECB operation completes, the application should either start another operation
 *  or close the driver by calling AESECB_close()
 *
 *  @anchor ti_drivers_AESECB_Synopsis
 *  ## Synopsis
 *  @anchor ti_drivers_AESECB_Synopsis_Code
 *  @code
 *  // Import AESECB Driver definitions
 *  #include <ti/drivers/AESECB.h>
 *
 *  AESECB_init();
 *
 *  // Define name for AESECB channel index
 *  #define AESECB_INSTANCE 0
 *
 *  handle = AESECB_open(AESECB_INSTANCE, NULL);
 *
 *  // Initialize symmetric key
 *  CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
 *
 *  // Set up AESECB_Operation
 *  AESECB_Operation_init(&operation);
 *  operation.key               = &cryptoKey;
 *  operation.input             = plaintext;
 *  operation.output            = ciphertext;
 *  // Input length must be a non-zero multiple of block-size (16 bytes)
 *  // for one-step operations. The user or application should take care of
 *  // necessary padding.
 *  operation.inputLength       = sizeof(plaintext);
 *
 *  encryptionResult = AESECB_oneStepEncrypt(handle, &operation);
 *
 *  AESECB_close(handle);
 *  @endcode
 *
 *  @anchor ti_drivers_AESECB_Examples
 *
 *  ## Examples
 *
 *  ### Encryption of multiple plaintext blocks in blocking mode #
 *  @code
 *
 *  #include <ti/drivers/AESECB.h>
 *  #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
 *
 *  ...
 *
 *  AESECB_Handle handle;
 *  CryptoKey cryptoKey;
 *  int_fast16_t encryptionResult;
 *  uint8_t plaintext[] = {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};
 *  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 = AESECB_open(0, NULL);
 *
 *  if (handle == NULL) {
 *      // handle error
 *  }
 *
 *  CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
 *
 *      AESECB_Operation operation;
 *      AESECB_Operation_init(&operation);
 *
 *      operation.key               = &cryptoKey;
 *      operation.input             = plaintext;
 *      operation.output            = ciphertext;
 *      // Input length must be a non-zero multiple of block-size (16 bytes)
 *      // for one-step operations. The user or application should take care of
 *      // necessary padding.
 *      operation.inputLength       = sizeof(plaintext);
 *
 *  encryptionResult = AESECB_oneStepEncrypt(handle, &operation);
 *
 *  if (encryptionResult != AESECB_STATUS_SUCCESS) {
 *      // handle error
 *  }
 *
 *  // The resultant ciphertext should be:
 *  // 0x3a, 0xd7, 0x7b, 0xb4, 0x0d, 0x7a, 0x36, 0x60,
 *  // 0xa8, 0x9e, 0xca, 0xf3, 0x24, 0x66, 0xef, 0x97,
 *  // 0xf5, 0xd3, 0xd5, 0x85, 0x03, 0xb9, 0x69, 0x9d,
 *  // 0xe7, 0x85, 0x89, 0x5a, 0x96, 0xfd, 0xba, 0xaf
 *
 *
 *  AESECB_close(handle);
 *
 *  @endcode
 *
 *  ### One step ECB decryption in callback mode #
 *  @code
 *
 *  #include <ti/drivers/AESECB.h>
 *  #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
 *
 *  ...
 *
 *  uint8_t ciphertext[]                    = {0xf3, 0xee, 0xd1, 0xbd, 0xb5, 0xd2, 0xa0, 0x3c,
 *                                             0x06, 0x4b, 0x5a, 0x7e, 0x3d, 0xb1, 0x81, 0xf8};
 *  uint8_t keyingMaterial[32]              = {0x60, 0x3d, 0xeb, 0x10, 0x15, 0xca, 0x71, 0xbe,
 *                                             0x2b, 0x73, 0xae, 0xf0, 0x85, 0x7d, 0x77, 0x81,
 *                                             0x1f, 0x35, 0x2c, 0x07, 0x3b, 0x61, 0x08, 0xd7,
 *                                             0x2d, 0x98, 0x10, 0xa3, 0x09, 0x14, 0xdf, 0xf4};
 *  uint8_t plaintext[sizeof(ciphertext)];
 *
 *  // The plaintext should be the following after the decryption operation:
 *  // 0x6b, 0xc1, 0xbe, 0xe2, 0x2e, 0x40, 0x9f, 0x96,
 *  // 0xe9, 0x3d, 0x7e, 0x11, 0x73, 0x93, 0x17, 0x2a,
 *
 *
 *  void ecbCallback(AESECB_Handle handle,
 *                   int_fast16_t returnValue,
 *                   AESECB_Operation *operation,
 *                   AESECB_OperationType operationType) {
 *
 *      if (returnValue != AESECB_STATUS_SUCCESS) {
 *          // handle error
 *      }
 *  }
 *
 *  AESECB_Operation operation;
 *
 *  void ecbStartFunction(void) {
 *      AESECB_Handle handle;
 *      AESECB_Params params;
 *      CryptoKey cryptoKey;
 *      int_fast16_t decryptionResult;
 *
 *      AESECB_Params_init(&params);
 *      params.returnBehavior = AESECB_RETURN_BEHAVIOR_CALLBACK;
 *      params.callbackFxn = ecbCallback;
 *
 *      handle = AESECB_open(0, &params);
 *
 *      if (handle == NULL) {
 *          // handle error
 *      }
 *
 *      CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
 *
 *      AESECB_Operation_init(&operation);
 *
 *      operation.key               = &cryptoKey;
 *      operation.input             = plaintext;
 *      operation.output            = ciphertext;
 *      // Input length must be a non-zero multiple of block-size (16 bytes)
 *      // for one-step operations. The user or application should take care of
 *      // necessary padding.
 *      operation.inputLength       = sizeof(plaintext);
 *
 *      decryptionResult = AESECB_oneStepDecrypt(handle, &operation);
 *
 *      if (decryptionResult != AESECB_STATUS_SUCCESS) {
 *          // handle error
 *      }
 *
 *      // do other things while ECB operation completes in the background
 *
 *  }
 *
 *  @endcode
 *
 *  ### Multi-step ECB encryption in blocking mode #
 *  @code
 *
 *  #include <ti/drivers/AESECB.h>
 *  #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
 *
 *  #define AES_BLOCK_SIZE  16      // bytes
 *
 *  ...
 *
 *  AESECB_Handle handle;
 *  CryptoKey cryptoKey;
 *  int_fast16_t encryptionResult;
 *  int_fast16_t setupEncryptionResult;
 *  int_fast16_t finalizeEncryptionResult;
 *  uint8_t plaintext[] = {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};
 *  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 = AESECB_open(0, NULL);
 *
 *  if (handle == NULL) {
 *      // handle error
 *  }
 *
 *  CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
 *
 *  setupEncryptionResult = AESECB_setupEncrypt(handle, &cryptoKey);
 *  if (setupEncryptionResult != AESECB_STATUS_SUCCESS) {
 *      // handle error
 *  }
 *
 *  AESECB_Operation operation;
 *  AESECB_Operation_init(&operation);
 *
 *  // No need to set operation.key for multi-step operations.
 *  operation.input             = plaintext;
 *  operation.output            = ciphertext;
 *  // Input length must be a non-zero multiple of block-size (16 bytes) for calling
 *  // #AESECB_addData(). The user or application should take care of necessary padding
 *  // if the final block of data is being added for the entire segmented operation.
 *  operation.inputLength       = AES_BLOCK_SIZE;
 *
 *  encryptionResult = AESECB_addData(handle, &operation);
 *  if (encryptionResult != AESECB_STATUS_SUCCESS) {
 *      // handle error
 *  }
 *
 *  // No need to set operation.key for multi-step operations.
 *  operation.input             = plaintext + AES_BLOCK_SIZE;
 *  operation.output            = ciphertext + AES_BLOCK_SIZE;
 *  // Input length must either be a non-zero multiple of block-size (16 bytes)
 *  // for calling #AESECB_finalize(), or it could be zero in case of finalizing without
 *  // any more data. The user or application should take care of necessary padding
 *  // for the last block of data.
 *  operation.inputLength       = AES_BLOCK_SIZE;
 *
 *  finalizeEncryptionResult = AESECB_finalize(handle, &operation);
 *  if (finalizeEncryptionResult != AESECB_STATUS_SUCCESS) {
 *      // handle error
 *  }
 *
 *  // The resultant ciphertext should be:
 *  // 0x3a, 0xd7, 0x7b, 0xb4, 0x0d, 0x7a, 0x36, 0x60,
 *  // 0xa8, 0x9e, 0xca, 0xf3, 0x24, 0x66, 0xef, 0x97,
 *  // 0xf5, 0xd3, 0xd5, 0x85, 0x03, 0xb9, 0x69, 0x9d,
 *  // 0xe7, 0x85, 0x89, 0x5a, 0x96, 0xfd, 0xba, 0xaf
 *
 *
 *  AESECB_close(handle);
 *
 *  }
 *
 *  @endcode
 *
 *  ### Multi-step ECB decryption in callback mode #
 *  @code
 *
 *  #include <ti/drivers/AESECB.h>
 *  #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
 *
 *  #define AES_BLOCK_SIZE  16      // bytes
 *
 *  ...
 *  uint8_t ciphertext[]                    = {0xf3, 0xee, 0xd1, 0xbd, 0xb5, 0xd2, 0xa0, 0x3c,
 *                                             0x06, 0x4b, 0x5a, 0x7e, 0x3d, 0xb1, 0x81, 0xf8};
 *  uint8_t keyingMaterial[32]              = {0x60, 0x3d, 0xeb, 0x10, 0x15, 0xca, 0x71, 0xbe,
 *                                             0x2b, 0x73, 0xae, 0xf0, 0x85, 0x7d, 0x77, 0x81,
 *                                             0x1f, 0x35, 0x2c, 0x07, 0x3b, 0x61, 0x08, 0xd7,
 *                                             0x2d, 0x98, 0x10, 0xa3, 0x09, 0x14, 0xdf, 0xf4};
 *  uint8_t plaintext[sizeof(ciphertext)];
 *
 *  // The plaintext should be the following after the decryption operation:
 *  // 0x6b, 0xc1, 0xbe, 0xe2, 0x2e, 0x40, 0x9f, 0x96,
 *  // 0xe9, 0x3d, 0x7e, 0x11, 0x73, 0x93, 0x17, 0x2a,
 *
 *
 *  void ecbCallback(AESECB_Handle handle,
 *                   int_fast16_t returnValue,
 *                   AESECB_Operation *operation,
 *                   AESECB_OperationType operationType) {
 *
 *      if (returnValue != AESECB_STATUS_SUCCESS) {
 *          // handle error
 *      }
 *  }
 *
 *  AESECB_Operation operation;
 *
 *  void ecbStartFunction(void) {
 *      AESECB_Handle handle;
 *      AESECB_Params params;
 *      CryptoKey cryptoKey;
 *      int_fast16_t decryptionResult;
 *      int_fast16_t setupDecryptionResult;
 *      int_fast16_t finalizeDecryptionResult;
 *
 *      AESECB_Params_init(&params);
 *      params.returnBehavior = AESECB_RETURN_BEHAVIOR_CALLBACK;
 *      params.callbackFxn = ecbCallback;
 *
 *      handle = AESECB_open(0, &params);
 *
 *      if (handle == NULL) {
 *          // handle error
 *      }
 *
 *      CryptoKeyPlaintext_initKey(&cryptoKey, keyingMaterial, sizeof(keyingMaterial));
 *
 *      setupDecryptionResult = AESECB_setupDecrypt(handle, &cryptoKey);
 *      if (setupDecryptionResult != AESECB_STATUS_SUCCESS) {
 *          // handle error
 *      }
 *
 *      AESECB_Operation_init(&operation);
 *
 *      // No need to set operation.key for multi-step operations.
 *      operation.input             = plaintext;
 *      operation.output            = ciphertext;
 *      // Input length must be a non-zero multiple of block-size (16 bytes) for calling
 *      // #AESECB_addData(). The user or application should take care of necessary padding
 *      // if the final block of data is being added for the entire segmented operation.
 *      operation.inputLength       = AES_BLOCK_SIZE;
 *
 *      decryptionResult = AESECB_addData(handle, &operation);
 *      if (decryptionResult != AESECB_STATUS_SUCCESS) {
 *          // handle error
 *      }
 *
 *      // do other things while ECB operation completes in the background
 *
 *      // Input length must either be a non-zero multiple of block-size (16 bytes)
 *      // for calling #AESECB_finalize(), or it could be zero in case of finalizing without
 *      // any more data as shown in this example. There's no more data involved and padding
 *      // is not applicable for this finalization operation.
 *      operation.inputLength       = 0;
 *
 *      finalizeDecryptionResult = AESECB_finalize(handle, &operation);
 *      if (finalizeDecryptionResult != AESECB_STATUS_SUCCESS) {
 *          // handle error
 *      }
 *
 *  }
 *
 *  @endcode
 */

#ifndef ti_drivers_AESECB__include
#define ti_drivers_AESECB__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

#define AESECB_STATUS_RESERVED AES_STATUS_RESERVED

#define AESECB_STATUS_SUCCESS AES_STATUS_SUCCESS

#define AESECB_STATUS_ERROR AES_STATUS_ERROR

#define AESECB_STATUS_RESOURCE_UNAVAILABLE AES_STATUS_RESOURCE_UNAVAILABLE

#define AESECB_STATUS_CANCELED AES_STATUS_CANCELED

#define AESECB_STATUS_FEATURE_NOT_SUPPORTED AES_STATUS_FEATURE_NOT_SUPPORTED

#define AESECB_STATUS_KEYSTORE_INVALID_ID AES_STATUS_KEYSTORE_INVALID_ID

#define AESECB_STATUS_KEYSTORE_GENERIC_ERROR AES_STATUS_KEYSTORE_GENERIC_ERROR

#define AESECB_STATUS_UNALIGNED_IO_NOT_SUPPORTED AES_STATUS_UNALIGNED_IO_NOT_SUPPORTED

typedef AESCommon_Config AESECB_Config;

typedef AESECB_Config *AESECB_Handle;

typedef enum
{
    AESECB_RETURN_BEHAVIOR_CALLBACK = AES_RETURN_BEHAVIOR_CALLBACK,
    AESECB_RETURN_BEHAVIOR_BLOCKING = AES_RETURN_BEHAVIOR_BLOCKING,
    AESECB_RETURN_BEHAVIOR_POLLING  = AES_RETURN_BEHAVIOR_POLLING,
} AESECB_ReturnBehavior;

typedef enum
{
    AESECB_MODE_ENCRYPT = 1,
    AESECB_MODE_DECRYPT = 2,
} AESECB_Mode;

typedef struct
{
    CryptoKey *key;     
    uint8_t *input;     
    uint8_t *output;    
    size_t inputLength; 
} AESECB_Operation;

typedef enum
{
    AESECB_OPERATION_TYPE_ENCRYPT                    = 1,
    AESECB_OPERATION_TYPE_DECRYPT                    = 2,
    AESECB_OPERATION_TYPE_ENCRYPT_SEGMENTED          = 3,
    AESECB_OPERATION_TYPE_DECRYPT_SEGMENTED          = 4,
    AESECB_OPERATION_TYPE_FINALIZE_ENCRYPT_SEGMENTED = 5,
    AESECB_OPERATION_TYPE_FINALIZE_DECRYPT_SEGMENTED = 6
} AESECB_OperationType;

typedef void (*AESECB_CallbackFxn)(AESECB_Handle handle,
                                   int_fast16_t returnValue,
                                   AESECB_Operation *operation,
                                   AESECB_OperationType operationType);

typedef struct
{
    AESECB_ReturnBehavior returnBehavior; 
    AESECB_CallbackFxn callbackFxn;       
    uint32_t timeout;                     
    void *custom;                         
} AESECB_Params;

extern const AESECB_Params AESECB_defaultParams;

void AESECB_init(void);

void AESECB_Params_init(AESECB_Params *params);

AESECB_Handle AESECB_open(uint_least8_t index, const AESECB_Params *params);

void AESECB_close(AESECB_Handle handle);

void AESECB_Operation_init(AESECB_Operation *operationStruct);

int_fast16_t AESECB_oneStepEncrypt(AESECB_Handle handle, AESECB_Operation *operation);

int_fast16_t AESECB_oneStepDecrypt(AESECB_Handle handle, AESECB_Operation *operation);

int_fast16_t AESECB_setupEncrypt(AESECB_Handle handle, const CryptoKey *key);

int_fast16_t AESECB_setupDecrypt(AESECB_Handle handle, const CryptoKey *key);

int_fast16_t AESECB_addData(AESECB_Handle handle, AESECB_Operation *operation);

int_fast16_t AESECB_finalize(AESECB_Handle handle, AESECB_Operation *operation);

int_fast16_t AESECB_cancelOperation(AESECB_Handle handle);

AESECB_Handle AESECB_construct(AESECB_Config *config, const AESECB_Params *params);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_AESECB__include */