AESCommonXXF3.h

Go to the documentation of this file.

/*
 * Copyright (c) 2021-2025, 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.
 */
#ifndef ti_drivers_aescommon_AESCommonXXF3__include
#define ti_drivers_aescommon_AESCommonXXF3__include

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

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

#include <ti/drivers/dpl/HwiP.h>

#include <ti/devices/DeviceFamily.h>
#include DeviceFamily_constructPath(inc/hw_types.h)

#ifdef __cplusplus
extern "C" {
#endif

/*
 * Unaligned input/output pointer arguments are not supported by default
 * because the performance will be up to 5x slower. Enabling unaligned I/O
 * is strongly discouraged.
 */
#ifndef AESCommonXXF3_UNALIGNED_IO_SUPPORT_ENABLE
    #define AESCommonXXF3_UNALIGNED_IO_SUPPORT_ENABLE 0
#endif

/* DMA Channel Numbers */
#define DMA_CH4 4U
#define DMA_CH5 5U

/* DMA Channel 4 is reserved for AES Channel A (input) */
#define AESCommonXXF3_DMA_CHA_BITMASK ((uint32_t)1U << DMA_CH4)
/* DMA Channel 5 is reserved for AES Channel B (output) */
#define AESCommonXXF3_DMA_CHB_BITMASK ((uint32_t)1U << DMA_CH5)

/* Max key length supported by HSM - needed for KeyStore material retrieval */
#define AESCommonXXF3_256_KEY_LENGTH_BYTES (256U / 8U)

#if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC35XX)
    /* For CC27XX and CC23XX devices, below AES defines come from driverlib headers.
     * For CC35XX devices, driverlib does NOT contain these defines.
     * So, below defines are added.
     */
    #define AES_BLOCK_SIZE                          16U 
    #define AES_BLOCK_SIZE_WORDS                    (AES_BLOCK_SIZE / 4U)
    #define AES_BLOCK_SIZE_MULTIPLE_MASK            0xFFFFFFF0U
    #define AES_BLOCK_SIZE_MULTIPLE_LENGTH(len)     ((len)&AES_BLOCK_SIZE_MULTIPLE_MASK)
    #define AES_NON_BLOCK_SIZE_MULTIPLE_MASK        0x0000000FU
    #define AES_NON_BLOCK_SIZE_MULTIPLE_LENGTH(len) ((len)&AES_NON_BLOCK_SIZE_MULTIPLE_MASK)

    #define AES_IV_LENGTH_BYTES  AES_BLOCK_SIZE
    #define AES_TAG_LENGTH_BYTES AES_BLOCK_SIZE

    #define AES_128_KEY_LENGTH_BYTES (128U / 8U)

    #define IS_WORD_ALIGNED(ptr) (((uintptr_t)(ptr) << 30) == 0U)
#endif

typedef struct
{
    uint8_t intPriority;
} AESCommonXXF3_HWAttrs;

typedef struct
{
    uint32_t semaphoreTimeout;
    CryptoKey key;
    volatile int_fast16_t returnStatus;
    AES_ReturnBehavior returnBehavior;
    bool isOpen;
    volatile bool cryptoResourceLocked;
    volatile bool operationInProgress;
    volatile bool powerConstraintSet;
} AESCommonXXF3_Object;

void AESCommonXXF3_init(void);

int_fast16_t AESCommonXXF3_construct(AESCommonXXF3_Object *object, AES_ReturnBehavior returnBehavior, uint32_t timeout);
void AESCommonXXF3_loadKey(const CryptoKey *key);
#if (ENABLE_KEY_STORAGE == 1)
    /* Due to circular include dependencies, these types are defined here instead of retrieved via an include */
    #ifndef KeyStore_PSA_Algorithm
typedef uint32_t KeyStore_PSA_Algorithm;
    #endif
    #ifndef KeyStore_PSA_KeyUsage
typedef uint32_t KeyStore_PSA_KeyUsage;
    #endif

int_fast16_t AESCommonXXF3_loadKeyFromKeyStore(const CryptoKey *key,
                                               uint32_t *keyAssetID,
                                               KeyStore_PSA_Algorithm targetAlg,
                                               KeyStore_PSA_KeyUsage targetUsage);
#endif /* ENABLE_KEY_STORAGE */

void AESCommonXXF3_setupOperation(CryptoKey *key, uint32_t autoCfgVal);
void AESCommonXXF3_close(AESCommonXXF3_Object *object);
int_fast16_t AESCommonXXF3_setOperationInProgress(AESCommonXXF3_Object *object);
__STATIC_INLINE void AESCommonXXF3_clearOperationInProgress(AESCommonXXF3_Object *object)
{
    object->operationInProgress = false;
}
void AESCommonXXF3_cleanup(AESCommonXXF3_Object *object);
int_fast16_t AESCommonXXF3_setupSegmentedOperation(AESCommonXXF3_Object *object, const CryptoKey *key);
bool AESCommonXXF3_isDMALengthValid(const void *input, const void *output, size_t length);
void AESCommonXXF3_configInputDMA(const void *input, size_t inputLength);
void AESCommonXXF3_configOutputDMA(void *output, size_t outputLength);
void AESCommonXXF3_cancelDMA(bool cancelChannelB);
void AESCommonXXF3_cancelOperation(AESCommonXXF3_Object *object, bool cancelDMAChannelB);
void AESCommonXXF3_setupHwi(HwiP_Fxn hwiFxn, uintptr_t hwiFxnArg, uint8_t intPriority);
void AESCommonXXF3_cleanupHwi(AESCommonXXF3_Object *object);
void AESCommonXXF3_setupDMA(AESCommonXXF3_Object *object, uint32_t dmaConfig);
#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_aescommon_AESCommonXXF3__include */