sa2ul.h

Go to the documentation of this file.

/*
 *  Copyright (C) 2021-2025 Texas Instruments Incorporated
 *
 *  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 SA2UL_H_
#define SA2UL_H_
 
/* ========================================================================== */
/*                             Include Files                                  */
/* ========================================================================== */
 
#include <string.h>
#include <drivers/udma.h>
#include <security_common/drivers/crypto/pka/hw_include/cslr_cp_ace.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ========================================================================== */
/*                           Macros & Typedefs                                */
/* ========================================================================== */
 
#define SA2UL_MAX_HASH_SIZE_BYTES       (64U)
 
#define SA2UL_MAX_KEY_SIZE_BYTES        (32U)
 
#define SA2UL_MAX_IV_SIZE_BYTES         (16U)
 
#define SA2UL_MAX_IV_SIZE_BYTES_GCM     (12U)
 
#define SA2UL_NUMBER_OF_RINGS           (3U)
 
#define SA2UL_CACHELINE_ALIGNMENT       (16U)
 
#define SA2UL_SECCTX_SIZE               (256U)
 
#define SA2UL_INSTANCES_MAX             (4U)
 
#define SA2UL_RING_N_ELEMS              (8U)
 
#define SA2UL_SW_RING_NUM               (304U)
 
#define SA2UL_MAX_INPUT_LENGTH_ENC      (0xFFFFU)
 
#define SA2UL_MAX_INPUT_LENGTH_AUTH     (0x3FFFFFU)
 
#define SA2UL_MAX_AAD_SIZE_BYTES        (16U)
 
#define SA2UL_GHASH_LENGTH_BYTES        (16U)
 
#define SA2UL_HASH_ALG_NULL             (0x10U)
 
#define SA2UL_HASH_ALG_SHA1             (0x12U)
 
#define SA2UL_HASH_ALG_SHA2_256         (0x14U)
 
#define SA2UL_HASH_ALG_SHA2_512         (0x16U)
 
#define SA2UL_OP_ENC                    (0x01U)
 
#define SA2UL_OP_AUTH                   (0x02U)
 
#define SA2UL_OP_ENC_THEN_AUTH          (0x03U)
 
#define SA2UL_OP_AUTH_THEN_ENC          (0x04U)
 
#define SA2UL_ENGINE_CODE_DEFAULT_ENGINE_ID             (0U)
 
#define SA2UL_ENGINE_CODE_ENCRYPTION_MODULE_P1          (2U)
 
#define SA2UL_ENGINE_CODE_ENCRYPTION_MODULE_P2          (3U)
 
#define SA2UL_ENGINE_CODE_AUTHENTICATION_MODULE_P1      (4U)
 
#define SA2UL_ENGINE_CODE_AUTHENTICATION_MODULE_P2      (5U)
 
#define SA2UL_ENGINE_CODE_DEFAULT_EGRESS_PORT           (20U)
 
#define SA2UL_ENC_ALG_AES               (0x0U)
 
#define SA2UL_ENC_ALG_TDES              (0x1U)
 
#define SA2UL_ENC_ALG_MAX               (0x2U)
 
#define SA2UL_ENC_DIR_ENCRYPT           (0x0U)
 
#define SA2UL_ENC_DIR_DECRYPT           (0x1U)
 
#define SA2UL_ENC_MODE_ECB              (0x0U)
 
#define SA2UL_ENC_MODE_CBC              (0x1U)
 
#define SA2UL_ENC_MODE_GCM              (0x2U)
 
#define SA2UL_ENC_MODE_MAX              (0x3U)
 
#define SA2UL_ENC_KEYSIZE_128           (0x0U)
 
#define SA2UL_ENC_KEYSIZE_192           (0x1U)
 
#define SA2UL_ENC_KEYSIZE_256           (0x2U)
 
#define SA2UL_ENC_KEYSIZE_MAX           (0x3U)
 
#define SA2UL_ENC_KEYSIZE_BITS(k)       (128u + (64u * (k)))
/* ========================================================================== */
/*                         Structure Declarations                             */
/* ========================================================================== */
 
typedef void *SA2UL_Handle;
 
typedef struct
{
    uint8_t                 opType;
    uint8_t                 hashAlg;
    uint8_t                 encAlg;
    uint8_t                 encDirection;
    uint8_t                 encMode;
    uint8_t                 key[SA2UL_MAX_KEY_SIZE_BYTES];
    uint8_t                 encKeySize;
    uint32_t                inputLen;
    uint8_t                 iv[SA2UL_MAX_IV_SIZE_BYTES];
    uint8_t                 aad[SA2UL_MAX_AAD_SIZE_BYTES];
    uint8_t                 ghash[SA2UL_GHASH_LENGTH_BYTES];
    uint32_t                aadLen;
} SA2UL_ContextParams;
 
typedef struct
{
    uint32_t                reserved;
} SA2UL_Params;
 
typedef struct
{
    SA2UL_Handle            handle;
    SA2UL_Params            prms;
    uint32_t                isOpen;
    CSL_Cp_aceRegs          *pSaRegs;
    uint32_t                psilInst;
    uint32_t                ringaccChnls[SA2UL_NUMBER_OF_RINGS];
    uint32_t                udmapTxChnum;
    uint32_t                udmapRxChnum[2];
    uint32_t                udmapRxFlownum;
    /*
     * UDMA objects and druver handles
     */
    Udma_ChObject           udmaTxChObj;
    Udma_ChObject           udmaRxChObj[2];
    Udma_FlowObject         udmaFlowObj;
    Udma_RingObject         udmaRingObj[2];
    Udma_EventObject        udmaEvtObj;
    Udma_EventObject        udmaEvtObj0;
    Udma_DrvHandle          drvHandle;
    Udma_ChHandle           rxChHandle[2];
    Udma_ChHandle           txChHandle;
    Udma_FlowHandle         rxFlowHandle;
    Udma_RingHandle         rxFreeRingHandle;
    Udma_RingHandle         rxRingHandle;
    Udma_RingHandle         txComplRingHandle;
    Udma_RingHandle         txRingHandle;
    Udma_EventHandle        rxEvtHandle;
    /*
     * sa2ul storage Queue params
     */
    uint32_t                storageQueueHead;
    uint32_t                storageQueueTail;
    uint32_t                storageQueueFree;
    uint64_t                storageQueue[SA2UL_RING_N_ELEMS];
    /*
     * memory for SA2UL security context
     *
     * Caller must allocate SA2UL_SECCTX_SIZE bytes of 128-byte aligned
     * memory for this.
     */
    uint8_t                 sa2ulContextId[SA2UL_INSTANCES_MAX];
    uint8_t                 contextId;
} SA2UL_Object;
 
typedef struct
{
    /*
     * SOC configuration
     */
    uint32_t                saBaseAddr;
    uint32_t                txPsilThreadId;
    uint32_t                rxPsil0ThreadId;
    uint32_t                rxPsil1ThreadId;
    uint32_t                rxRingMemAddr;
    uint32_t                txRingMemAddr;
    uint32_t                numDesc;
    uint32_t                descSize;
    uint32_t                descMemAddr;
    uint32_t                descMemSize;
    uint32_t                udmaSaTxGroupNum;
    uint32_t                udmaSaRxGroupNum;
    uint32_t                ringCnt;
    uint32_t                udmaHandle;
    uint32_t                contextIdStart;
    uint32_t                contextIdMaxNum;
    uint32_t                txRingNumInt;
    uint32_t                rxRingNumInt;
    uint32_t                swRingNumInt;
    uint32_t                privId;
    uint32_t                priv;
    uint32_t                secure;
} SA2UL_Attrs;
 
typedef struct
{
    SA2UL_Attrs             *attrs;
    SA2UL_Object            *object;
} SA2UL_Config;
 
typedef struct
{
    uint8_t                 sopOffset;
    uint8_t                 middleOffset;
    uint8_t                 eopOffset;
    uint8_t                 nMCInstrs;
    const uint8_t          *mcInstrs;
}SA2UL_MCEData;
 
typedef struct 
{
    uint32_t                authCtx1;
    uint32_t                reserved0;
    uint32_t                authenticationLengthHi;
    uint32_t                authenticationLengthLo;
    uint32_t                reserved1[4];
    uint32_t                authenticationKeyValueL[8];
    uint32_t                oPadL[8];
    uint32_t                authenticationKeyValueH[8];
    uint32_t                oPadH[8];
}SA2UL_SecCtxAuth;
 
typedef struct
{
    uint32_t                scctl1;
    uint32_t                scctl2;
    uint32_t                scptrH;
    uint32_t                scptrL;
}SA2UL_Scctl;
 
typedef struct 
{
    uint32_t                encrCtl;
    uint32_t                modeCtrlInstrs[6];
    uint32_t                hwCtrlWord;
    uint32_t                encKeyValue[8];
    uint32_t                encAux1[8];
    uint32_t                encAux2[4];
    uint32_t                encAux3[4];
    uint32_t                encAux4[4];
    uint8_t                 preCryptoData[15];
}SA2UL_SecCtxEnc;
 
typedef struct 
{
    SA2UL_Scctl      scctl;
    uint32_t         unused[12];
    union
    {
        SA2UL_SecCtxAuth  auth;
        SA2UL_SecCtxEnc   enc;
    } u;
}SA2UL_SecCtx;
 
typedef struct
{
    SA2UL_SecCtx            secCtx;
    uint8_t                 res[32];
    uint8_t                 secCtxId;
    SA2UL_Handle            handle;
    SA2UL_ContextParams     ctxPrms;
    uint32_t                totalLengthInBytes;
    uint8_t                 computedHash[SA2UL_MAX_HASH_SIZE_BYTES];
    uint32_t                computationStatus;
    uint32_t                txBytesCnt;
    uint32_t                rxBytesCnt;
    uint32_t                sa2ulErrCnt;
} SA2UL_ContextObject;
 
/* ========================================================================== */
/*                            Global Variables                                */
/* ========================================================================== */
 
extern SA2UL_Config         gSa2ulConfig[];
extern uint32_t             gSa2ulConfigNum;
extern uint32_t             gSa2ulEngineEnableMask;
 
/* ========================================================================== */
/*                          Function Declarations                             */
/* ========================================================================== */
 
/* None */
 
/* ========================================================================== */
/*                       Static Function Definitions                          */
/* ========================================================================== */
 
void SA2UL_init(void);
 
void SA2UL_deinit(void);
 
int32_t SA2UL_engineEnable(int32_t hwEnableMask);
 
int32_t SA2UL_engineDisable(int32_t hwDisableMask);
 
SA2UL_Handle SA2UL_open(uint32_t index, const SA2UL_Params *params);
 
void SA2UL_close(SA2UL_Handle handle);
 
int32_t SA2UL_contextAlloc(SA2UL_Handle handle, SA2UL_ContextObject *ctxObj, const SA2UL_ContextParams *ctxPrms);
 
int32_t SA2UL_contextFree(SA2UL_ContextObject *pCtxObj);
 
int32_t SA2UL_contextProcess(SA2UL_ContextObject *ctxObj, const uint8_t *input, uint32_t ilen, uint8_t *output);
 
static inline void SA2UL_Params_init(SA2UL_Params *prms);
 
static inline void SA2UL_ContextParams_init(SA2UL_ContextParams *ctxPrms);
 
/* ========================================================================== */
/*                       Static Function Definitions                          */
/* ========================================================================== */
 
static inline void SA2UL_Params_init(SA2UL_Params *prms)
{
    if(prms != NULL)
    {
        prms->reserved                        = 0;
    }
}
 
static inline void SA2UL_ContextParams_init(SA2UL_ContextParams *ctxPrms)
{
    if(ctxPrms != NULL)
    {
        memset(ctxPrms, 0, sizeof(*ctxPrms));
    }
}
 
#ifdef __cplusplus
}
#endif
 
#endif /* SA2UL_H_ */