hsmclient.h

Go to the documentation of this file.

/*
 *  Copyright (C) 2022-24 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 HSM_CLIENT_H_
#define HSM_CLIENT_H_
 
#ifdef __cplusplus
extern "C"
{
#endif
 
/* Header file for HSM client driver */
#include <stdint.h>
#include <security_common/drivers/secure_ipc_notify/sipc_notify.h>
#include <security_common/drivers/hsmclient/hsmclient_msg.h>
#include <security_common/drivers/hsmclient/utils/hsmclient_utils.h>
#include <kernel/dpl/SemaphoreP.h>
 
#define LABEL_AND_CONTEXT_LEN_MAX 48U
 
#define HSMRT_LOAD_NOT_REQUESTED (0U)
 
#define HSMRT_LOAD_REQUESTED (1U)
 
#define HSMRT_LOAD_FAILED (2U)
 
#define HSMRT_LOAD_SUCCEEDED (3U)
 
/* 
 * -------------------------------------------------------------------------
 * Algorithm selectors — used in CryptoServiceReq_t.algoId
 * -------------------------------------------------------------------------
 */
#define HSM_CRYPTO_SVC_MAC_CMAC  (0x0001U)
 
#define HSM_CRYPTO_SVC_MAC_HMAC  (0x0002U)
 
#define HSM_CRYPTO_SVC_MAC_GMAC  (0x0003U)
 
/* 
 * -------------------------------------------------------------------------
 * Hash mode selectors for HMAC — used in HMACArgs_t.hashMode
 * -------------------------------------------------------------------------
 */
#define HSM_CRYPTO_HMAC_SHA256  (0x6U)  /* matches DTHE_SHA_ALGO_SHA256 */
 
#define HSM_CRYPTO_HMAC_SHA512  (0x4U)  /* matches DTHE_SHA_ALGO_SHA512 */
 
/* 
 * -------------------------------------------------------------------------
 * Sub-service selectors — used in CryptoServiceReq_t.subSvcId
 * -------------------------------------------------------------------------
 */
#define HSM_CRYPTO_SVC_MAC_GENERATE  (0x0001U)
 
#define HSM_CRYPTO_SVC_MAC_VERIFY    (0x0002U)
 
/* 
 * -------------------------------------------------------------------------
 * Service macros — used in DeviceConfigRead_t
 * -------------------------------------------------------------------------
 */
#define DEVICE_CONFIG_TYPE_SAFETY       (0U)
 
#define DEVICE_CONFIG_TYPE_SECURITY     (1U)
 
#define DEVICE_CONFIG_TYPE_DEBUG        (2U)
 
#define DEVICE_CONFIG_TYPE_ALL          (0xFFU)
 
#define SIZE_OF_SAFETY_DEVICE_CONFIG       (8U)
 
#define SIZE_OF_SECURITY_DEVICE_CONFIG     (44U)
 
#define SIZE_OF_DEBUG_DEVICE_CONFIG        (16U)
 
    typedef union HsmVer_t_
    {
        uint64_t HsmrtVer ;
        struct
        {
            uint8_t PatchVer; 
            uint8_t MinorVer; 
            uint8_t MajorVer; 
            uint8_t ApiVer;   
            uint8_t SocType;  
            uint8_t BinType;  
            uint8_t HsmType;  
            uint8_t DevType;  
        } VerStruct;
#if defined(_TMS320C6X)
    } __attribute__((packed)) HsmVer_t_;
#else
} __attribute__((packed)) HsmVer_t;
#endif
 
    typedef struct HsmClient_t_
    {
        SemaphoreP_Object Semaphore; 
        HsmMsg_t ReqMsg;             
        HsmMsg_t RespMsg;            
        uint8_t RespFlag;            
        uint8_t ClientId;            
    } HsmClient_t;
 
    typedef struct NvmOtpRead_t_
    {
        uint32_t rowData; 
        uint16_t rowIdx;  
        uint8_t rsvd[2];  
    } NvmOtpRead_t;
 
    typedef struct NvmOtpRowWrite_t_
    {
        uint32_t rowData;    
        uint32_t rowBitMask; 
        uint16_t rowIdx;     
        uint8_t rsvd[2];     
    } NvmOtpRowWrite_t;
 
    typedef struct NvmOtpRowCount_t_
    {
        uint32_t rowCount; 
        uint8_t rowSize;   
        uint8_t rsvd[3];   
    } NvmOtpRowCount_t;
 
    typedef struct NvmOtpRowProt_t_
    {
        uint16_t rowidx;   
        uint8_t readProt;  
        uint8_t writeProt; 
    } NvmOtpRowProt_t;
 
    typedef struct keywriter_cert_header_t_
    {
        uint8_t *certAddress;   /*For holding cerificate address*/
        uint32_t certSize;      /*Cerificate size*/
        uint32_t debugResponse; /*Debug response*/
        uint32_t reserved;      /*reserved for future use*/
    } KeyWriterCertHeader_t;
 
    typedef struct FirewallRegionReq_t_
    {
        uint16_t firewallId;           
        uint16_t region;               
        uint32_t permissionAttributes; 
        uint32_t startAddress;         
        uint32_t endAddress;           
    } FirewallRegionReq_t;
 
    typedef struct FirewallReq_t_
    {
        uint16_t regionCount;                   
        uint16_t crcArr;                        
        FirewallRegionReq_t *FirewallRegionArr; 
        uint16_t statusFirewallRegionArr;       
    } FirewallReq_t;
 
    typedef struct FirewallIntrReq_t_
    {
        uint16_t firewallId;                
        uint8_t interruptEnable;            
        uint8_t interruptEnableClear;       
        uint8_t interruptEnableStatusClear; 
        uint8_t faultClear;                 
    } FirewallIntrReq_t;
 
    typedef struct SWRev_t_
    {
        uint32_t revValue; 
        uint8_t revId;     
        uint8_t rsvd[3];   
    } SWRev_t;
 
    typedef struct DKEK_t_
    {
        uint8_t label_length;                                 
        uint8_t context_length;                               
        uint8_t label_and_context[LABEL_AND_CONTEXT_LEN_MAX]; 
        uint32_t dkek[8];                                     
    } DKEK_t;
 
    typedef struct RNGReq_t_
    {
        uint8_t *resultPtr;        
        uint32_t resultLength;    
        uint8_t DRBGMode;          
        uint32_t *seedValue;       
        uint8_t seedSizeInDWords;  
        uint8_t reserved;          
    } RNGReq_t;
 
    typedef struct SecureBoot_Stream_t_
    {
        uint8_t *dataIn;        
        uint32_t dataLen;       
        uint8_t canBeEncrypted; 
    } __attribute__((packed)) SecureBoot_Stream_t;
 
    typedef struct FirmwareUpdateReq_t_
    {
        uint8_t *pStartAddress;             /* Start address of data to be programmed in flash memory */
        uint32_t dataLength;                /* Length of data to be programmed in flash memory */
        void *pDecryptionBuffer;            /* Address of Scratchpad memory to be used to decrypt image, valid only for HsmClient_firmwareUpdate_CodeVerify API */
        uint32_t decryptionBufferLength;    /* Length of Scratchpad memory to be used to decrypt image, valid only for HsmClient_firmwareUpdate_CodeVerify API */
    } FirmwareUpdateReq_t;
 
 
typedef struct OTFA_Region_t
{
    uint8_t   authMode ;         /* mode of authentication - disable-0/GMAC-1/CMAC-2 ; */
    uint8_t   encMode ;          /* mode of decryption - disable-0 or AES_CTR-1 */
    uint16_t  reservedArea ;     /* reserved to align with 4kB structure */
    uint32_t  regionStAddr ;     /* start address of the flash region for which the configuration should apply */
    uint32_t  regionSize ;       /* size of the flash region in kB for which the configuration should apply */
    uint8_t   authKeyID ;        /* Keyring ID of key to be used for authentication */    
    uint8_t   encrKeyID ;        /* Keyring ID of key to be used for encryption */
    uint8_t   encrKeyFetchMode ; /* specify which 16 bytes of DSMEK are to be used - 1 for fist 16/2 for last 16/ 3 for XOR of both */
    uint8_t   authAesKey [16] ;  /* actual key value to be written to the register for authentication ; fetched from keyring */
    uint8_t   encrAesKey [16] ;  /* actual key value to be written to the register for decryption ; fetched from keyring */
    uint8_t   regionIV[16] ;     /* IV to be used for encryption */
}OTFA_Region_t ;
 
typedef struct OTFA_readRegion_t
{
    uint8_t   regionNumber ;    /* Index of the region - 0/1/2/3 */
    uint8_t   authMode ;        /* mode of authentication - disable-0/GMAC-1/CMAC-2 ; */
    uint8_t   encMode ;         /* mode of decryption - disable-0 or AES_CTR-1 */
    uint8_t   authKeyHash[64] ; /* hash of the authentication key stored in OTFA register */
    uint8_t   encKeyHash[64] ;  /* hash of the encryption key stored in OTFA register */
    uint32_t  regionStAddr ;    /* start address of the flash region for which the configuration should apply */
    uint32_t  regionSize ;      /* size of the flash region in kB for which the configuration should apply */
    uint16_t  regionIV[16] ;    /* IV to be used for encryption */
}OTFA_readRegion_t ;
 
typedef struct OTFA_Config_t
{
    OTFA_Region_t  OTFA_Reg[4] ;    /* array of all registers' information of 4 OTFA Regions */
    uint8_t        numRegions ;     /* number of OTFA regions to be configured */
    uint8_t        keySize   ;      /* options - 128/256 */
    uint8_t        macSize   ;      /* options - 4/8/12/16 */
    uint8_t        masterEnable ;   /* specifies whether OTFA IP has to be enabled/disabled ; 0 or 1 */
}OTFA_Config_t ;
 
typedef struct SecCfgValidate_t_
{
    uint8_t *pCertAddress;  
    uint32_t certType;      
} SecCfgValidate_t;
 
typedef struct FlashBankCopy_t_
{
    uint8_t cpuFlashBankType;  
} FlashBankCopy_t;
 
typedef struct CryptoServiceReq_t_
{
    uint32_t  algoId;     
    uint32_t  subSvcId;   
    uint32_t  keyId;      
    uint32_t  errCode;    
    void     *ptrArgs;    
} CryptoServiceReq_t;
 
typedef struct CMACArgs_t_
{
    uint8_t  *ptrData;   
    uint32_t  dataLen;   
    uint8_t  *ptrTag;    
} CMACArgs_t;
 
typedef struct HMACArgs_t_
{
    uint32_t  hashMode;  
    uint8_t  *ptrData;   
    uint32_t  dataLen;   
    uint8_t  *ptrTag;    
} HMACArgs_t;
 
typedef struct GMACArgs_t_
{
    uint8_t  *ptrData;   
    uint32_t  dataLen;   
    uint8_t  *ptrTag;    
    uint8_t  *ptrIV;     
    uint32_t  ivLen;     
} GMACArgs_t;
 
typedef struct BankSwapReq_t_
{
    uint8_t c29CpuId;           
    uint8_t syncFlag;           
    uint32_t timeout;           
    uint32_t c29CpuBankSwapVal; 
} BankSwapReq_t;
 
/*
 * @brief
 * Safety configuration structure containing safety-related device information.
 * Total size: SIZE_OF_SAFETY_DEVICE_CONFIG (8 bytes)
 */
typedef struct DeviceConfigSafety_t_
{
    uint32_t dedFotaInfo;      
    uint32_t hsmPbistStatus;   
} DeviceConfigSafety_t;
 
typedef struct DeviceConfigSecurity_t_
{
#if defined (SOC_F29H85X)
    uint32_t c29Cpu2SecCfgValidationStatus; 
    uint32_t c29Cpu3SecCfgValidationStatus; 
    uint32_t certSwRevSSU;                  
    uint32_t certSwRevR5SBL;                
    uint32_t certSwRevHSM;                  
    uint32_t certSwRevApp;                  
#elif defined (SOC_F29P32X)
    uint32_t c29Cpu2SecCfgValidationStatus; 
    uint32_t reserved1;                     
    uint32_t certSwRevSSU;                  
    uint32_t certSwRevR5SBL;                
    uint32_t certSwRevHSM;                  
    uint32_t certSwRevApp;                  
#else
    uint32_t reserved1;                     
    uint32_t reserved2;                     
    uint32_t reserved3;                     
    uint32_t reserved4;                     
    uint32_t reserved5;                     
    uint32_t reserved6;                     
#endif
    uint32_t bootRetryCounts;               
    uint32_t hsmFirmwareUpdateStatus;       
    uint32_t sblFirmwareUpdateStatus;       
    uint32_t hostCpu1FirmwareUpdateStatus;  
    uint32_t hostCpu2FirmwareUpdateStatus;  
} DeviceConfigSecurity_t;
 
typedef struct DeviceConfigDebug_t_
{
    uint32_t publicDebugStatus;             
    uint32_t publicRegisterAccessStatus;    
    uint32_t secureDebugStatus;             
    uint32_t secureRegisterAccessStatus;    
} DeviceConfigDebug_t;
 
typedef struct DeviceConfigRead_t_
{
    uint32_t configType;            
    uint32_t *configData;           
    uint32_t configSize;            
    uint16_t configDataCRC;         
} DeviceConfigRead_t;
 
    int32_t HsmClient_checkAndWaitForBootNotification(void);
 
    int32_t HsmClient_init(SIPC_Params *params);
 
    void HsmClient_deInit(void);
 
void HsmClient_SecureBootQueueInit(uint32_t configured_hsm_client_msg_queue_size);
int32_t HsmClient_getVersion(HsmClient_t *HsmClient ,
                                        HsmVer_t* verId,uint32_t timeToWaitInTick);
 
    int32_t HsmClient_getUID(HsmClient_t *HsmClient,
                             uint8_t *uid, uint32_t timeout);
 
    int32_t HsmClient_openDbgFirewall(HsmClient_t *HsmClient,
                                      uint8_t *cert,
                                      uint32_t cert_size,
                                      uint32_t timeout);
 
    int32_t HsmClient_importKeyring(HsmClient_t *HsmClient,
                                    uint8_t *cert,
                                    uint32_t cert_size,
                                    uint32_t timeout);
 
    int32_t HsmClient_readOTPRow(HsmClient_t *HsmClient,
                                 NvmOtpRead_t *readRow);
 
    int32_t HsmClient_writeOTPRow(HsmClient_t *HsmClient,
                                  NvmOtpRowWrite_t *writeRow);
 
    int32_t HsmClient_lockOTPRow(HsmClient_t *HsmClient,
                                 NvmOtpRowProt_t *rowProt);
 
    int32_t HsmClient_getOTPRowCount(HsmClient_t *HsmClient,
                                     NvmOtpRowCount_t *rowCount);
 
    int32_t HsmClient_getOTPRowProtection(HsmClient_t *HsmClient,
                                          NvmOtpRowProt_t *rowProt);
 
    int32_t HsmClient_procAuthBoot(HsmClient_t *HsmClient,
                                   uint8_t *cert,
                                   uint32_t cert_size,
                                   uint32_t timeout);
 
    int32_t HsmClient_procAuthBootStart(HsmClient_t *HsmClient,
                                        SecureBoot_Stream_t *secureBootInfo);
 
    int32_t HsmClient_procAuthBootUpdate(HsmClient_t *HsmClient,
                                         SecureBoot_Stream_t *secureBootInfo);
 
    int32_t HsmClient_procAuthBootFinish(HsmClient_t *HsmClient,
                                         SecureBoot_Stream_t *secureBootInfo);
 
    int32_t HsmClient_setFirewall(HsmClient_t *HsmClient,
                                  FirewallReq_t *FirewallReqObj,
                                  uint32_t timeout);
    int32_t HsmClient_FirewallIntr(HsmClient_t *HsmClient,
                                   FirewallIntrReq_t *FirewallIntrReqObj,
                                   uint32_t timeout);
 
    int32_t HsmClient_keyWriter(HsmClient_t *HsmClient,
                                KeyWriterCertHeader_t *certHeader,
                                uint32_t timeout);
 
    int32_t HsmClient_readSWRev(HsmClient_t *HsmClient,
                                SWRev_t *readSWRev);
 
    int32_t HsmClient_writeSWRev(HsmClient_t *HsmClient,
                                 SWRev_t *writeSWRev);
 
    int32_t HsmClient_getDKEK(HsmClient_t *HsmClient,
                              DKEK_t *getDKEK,
                              uint32_t timeout);
    int32_t HsmClient_register(HsmClient_t *HsmClient, uint8_t clientId);
 
    void HsmClient_unregister(HsmClient_t *HsmClient, uint8_t clientId);
 
    int32_t HsmClient_waitForBootNotify(HsmClient_t *HsmClient, uint32_t timeToWaitInTicks);
 
    int32_t Hsmclient_loadHSMRtFirmware(HsmClient_t *gHSMClient, const uint8_t *pHSMRt_firmware);
 
    int32_t Hsmclient_loadHSMRtFirmwareNonBlocking(const uint8_t *pHSMRt_firmware);
 
    int32_t HsmClient_getRandomNum(HsmClient_t *HsmClient,
                                   RNGReq_t *getRandomNum);
 
    int32_t HsmClient_firmwareUpdate_CertProcess(HsmClient_t *HsmClient,
                                                 FirmwareUpdateReq_t *pFirmwareUpdateObject);
 
    int32_t HsmClient_firmwareUpdate_CodeProgram(HsmClient_t *HsmClient,
                                                 FirmwareUpdateReq_t *pFirmwareUpdateObject);
 
    int32_t HsmClient_firmwareUpdate_CodeVerify(HsmClient_t *HsmClient,
                                                FirmwareUpdateReq_t *pFirmwareUpdateObject);
 
    int32_t HsmClient_VerifyROTSwitchingCertificate(HsmClient_t *HsmClient,
                                  uint8_t *cert,
                                  uint32_t cert_size,
                                  uint32_t timeout);
 
    int32_t HsmClient_UpdateKeyRevsion(HsmClient_t *HsmClient,
                                       uint32_t timeout);
 
int32_t HsmClient_configOTFARegions(HsmClient_t* HsmClient,
                                        OTFA_Config_t* OTFA_ConfigInfo,
                                        uint32_t timeout);
 
int32_t HsmClient_readOTFARegions(HsmClient_t* HsmClient,
                                        OTFA_readRegion_t* OTFA_readRegion,
                                        uint32_t timeout);
 
int32_t HsmClient_secCfgValidate(HsmClient_t *HsmClient,
                                 SecCfgValidate_t *pSecCfgParams,
                                 uint32_t timeout);
 
int32_t HsmClient_activeToDormantBankCopy(HsmClient_t *HsmClient,
                                          FlashBankCopy_t *pFlashBankCopyObject,
                                          uint32_t timeout);
 
int32_t HsmClient_SecCfgUpdate(HsmClient_t *HsmClient,
                                            FirmwareUpdateReq_t *pFirmwareUpdateObject);
 
int32_t HsmClient_getDeviceConfig(HsmClient_t *HsmClient,
                                   DeviceConfigRead_t *pDeviceConfigObject,
                                   uint32_t timeout);
 
int32_t HsmClient_CryptoService(HsmClient_t *HsmClient,
                                 CryptoServiceReq_t *svcReq,
                                 uint32_t timeout);
 
int32_t HsmClient_runTimeBankSwap(HsmClient_t *HsmClient,
                            BankSwapReq_t *pBankSwapObject);
 
#ifdef __cplusplus
}
#endif
 
#endif /* HSM_CLIENT_H_ */