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 EfuseRead_t_
{
    uint32_t rowData ;     
    uint8_t  rowIdx ;      
    uint8_t  rsvd[3];      
} EfuseRead_t;
 
typedef struct EfuseRowWrite_t_
{
    uint32_t  rowData ;           
    uint32_t  rowBitMask ;        
    uint8_t   rowIdx ;            
    uint8_t   rsvd[3];            
} EfuseRowWrite_t;
 
typedef struct EfuseRowCount_t_
{
    uint32_t rowCount ;     
    uint8_t  rowSize ;      
    uint8_t  rsvd[3];       
} EfuseRowCount_t;
 
typedef struct EfuseRowProt_t_
{
    uint8_t  rowidx ;         
    uint8_t  readProt ;       
    uint8_t  writeProt ;      
    uint8_t  rsvd[1];         
} EfuseRowProt_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* resultLengthPtr; 
    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;        
    uint32_t dataLength;            
    uint32_t bankMode;              
} FirmwareUpdateReq_t;
 
int32_t HsmClient_checkAndWaitForBootNotification(void);
 
int32_t HsmClient_init(SIPC_Params* params);
 
void HsmClient_deInit(void);
 
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,
                                        EfuseRead_t* readRow);
 
int32_t HsmClient_writeOTPRow(HsmClient_t* HsmClient,
                                        EfuseRowWrite_t* writeRow);
 
int32_t HsmClient_lockOTPRow(HsmClient_t* HsmClient,
                                        EfuseRowProt_t* rowProt);
 
int32_t HsmClient_getOTPRowCount(HsmClient_t* HsmClient,
                                        EfuseRowCount_t* rowCount);
 
int32_t HsmClient_getOTPRowProtection(HsmClient_t* HsmClient,
                                        EfuseRowProt_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);
#ifdef __cplusplus
}
#endif
 
#endif /* HSM_CLIENT_H_ */