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)
 
    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;
 
    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);
 
#ifdef __cplusplus
}
#endif
 
#endif /* HSM_CLIENT_H_ */