AM261x MCU+ SDK: hsmclient.c File Reference

| AM261x MCU+ SDK 26.00.00 |

Macros | Functions | Variables
hsmclient.c File Reference

## Macros
#define | GET_CACHE_ALIGNED_SIZE(x) ((x + CacheP_CACHELINE_ALIGNMENT) & ~(CacheP_CACHELINE_ALIGNMENT - 1))
| Macro calculates the cache-aligned size for a given buffer or data structure. More...

## Functions
void | Hsmclient_updateBootNotificationRegister (void)
static uint16_t | crc16_ccit (uint8_t *data, uint16_t length)
| Calculate crc16_ccit for a given data. More...
static int32_t | HsmClient_SendAndRecv (HsmClient_t *HsmClient, uint32_t timeout)
| Generic send and receive message api. More...
static int32_t | HsmClient_EnqueueAndSendMsg (HsmMsg_t message)
| Generic send message api which enqueus the message in HSM client message queue and tries to send the message via SIPC. This API is non blocking in nature. More...
static int32_t | HsmClient_EnqueueAndSendMsgBlocking (HsmMsg_t message)
| Generic send message api which enqueus the message in HSM client message queue and ensures all the messages present in the queue are sent via SIPC. This API is blocking in nature. More...
static int32_t | HsmClient_waitForAllResponses ()
| Generic api which waits for all responses to be received. More...
void | HsmClient_isr (uint8_t remoteCoreId, uint8_t localClientId, uint8_t remoteClientId, uint8_t *msgValue, void *args)
int32_t | HsmClient_checkAndWaitForBootNotification (void)
| This API waits for HSMRT load if requested and then waits for boot notification. In case of failure in HSMRT load it returns SystemP_FAILURE. More...
int32_t | HsmClient_register (HsmClient_t *HsmClient, uint8_t clientId)
| register a client to a particular ClientId More...
int32_t | HsmClient_init (SIPC_Params *params)
| Initialize the HSM client for current core. More...
void | HsmClient_SecureBootQueueInit (uint32_t configured_hsm_client_msg_queue_size)
| Customize the size of the HSM client message queue. More...
void | HsmClient_deinit (void)
void | HsmClient_unregister (HsmClient_t *HsmClient, uint8_t clientId)
| unregister a client to a particular ClientId More...
int32_t | HsmClient_getVersion (HsmClient_t *HsmClient, HsmVer_t *hsmVer, uint32_t timeout)
| populates the current HSMRT version Id by default the hsm flag is set to HSM_FLAG_AOP for this service More...
int32_t | HsmClient_getUID (HsmClient_t *HsmClient, uint8_t *uid, uint32_t timeout)
| The service issued to HSM Server populates the Device UID by default the hsm flag is set to HSM_FLAG_AOP for this service. More...
int32_t | HsmClient_openDbgFirewall (HsmClient_t *HsmClient, uint8_t *cert, uint32_t cert_size, uint32_t timeout)
| The service issued to HSM Server verifies the certificate and by default the hsm flag is set to HSM_FLAG_AOP for this service. More...
int32_t | HsmClient_importKeyring (HsmClient_t *HsmClient, uint8_t *cert, uint32_t cert_size, uint32_t timeout)
| The service issued to HSM Server verifies the certificate and imports the keys from the certificate. More...
int32_t | HsmClient_readOTPRow (HsmClient_t *HsmClient, NvmOtpRead_t *readRow)
| The service issued to HSM Server retrieves the data of GP OTP row based on row index provided as param. More...
int32_t | HsmClient_writeOTPRow (HsmClient_t *HsmClient, NvmOtpRowWrite_t *writeRow)
| The service issued to HSM Server writes the data to extended OTP efuse row based on row index provided as param. More...
int32_t | HsmClient_lockOTPRow (HsmClient_t *HsmClient, NvmOtpRowProt_t *protRow)
| The service issued to HSM Server sets the protection status bit of the specified row to 1. This API is not valid for F29H85x. More...
int32_t | HsmClient_getOTPRowCount (HsmClient_t *HsmClient, NvmOtpRowCount_t *rowCount)
| The service issued to HSM Server retrieves the count of extended OTP rows. More...
int32_t | HsmClient_getOTPRowProtection (HsmClient_t *HsmClient, NvmOtpRowProt_t *rowProt)
| The service issued to HSM Server retrieves the extended otp efuse row protection status. This API is not valid for F29H85x. More...
int32_t | HsmClient_procAuthBoot (HsmClient_t *HsmClient, uint8_t *cert, uint32_t cert_size, uint32_t timeout)
| The service issued to HSM Server helps with extended secure boot for applications. More...
int32_t | HsmClient_procAuthBootStart (HsmClient_t *HsmClient, SecureBoot_Stream_t *secureBootInfo)
| The service issued to HSM Server helps with extended secure boot for applications. More...
int32_t | HsmClient_procAuthBootUpdate (HsmClient_t *HsmClient, SecureBoot_Stream_t *secureBootInfo)
| The service issued to HSM Server helps with extended secure boot for applications. More...
int32_t | HsmClient_procAuthBootFinish (HsmClient_t *HsmClient, SecureBoot_Stream_t *secureBootInfo)
| The service issued to HSM Server helps with extended secure boot for applications. More...
int32_t | HsmClient_setFirewall (HsmClient_t *HsmClient, FirewallReq_t *FirewallReqObj, uint32_t timeout)
| The service issued to HSM Server sets the firewall for the given firewall id and region. More...
int32_t | HsmClient_FirewallIntr (HsmClient_t *HsmClient, FirewallIntrReq_t *FirewallIntrReqObj, uint32_t timeout)
| The service issued to HSM Server sets the firewall interrupt request for the given firewall id. More...
int32_t | HsmClient_getDKEK (HsmClient_t *HsmClient, DKEK_t *getDKEK, uint32_t timeout)
| The service issued to HSM Server retrieves the derived KEK based on identifier as param. More...
int32_t | HsmClient_keyWriter (HsmClient_t *HsmClient, KeyWriterCertHeader_t *certHeader, uint32_t timeout)
| The service issued to HSM Server verifies the certificate and process the keywriter operations,. More...
int32_t | HsmClient_readSWRev (HsmClient_t *HsmClient, SWRev_t *readSWRev)
| The service issued to HSM Server retrieves the SWRevision value based on identifier as param. More...
int32_t | HsmClient_writeSWRev (HsmClient_t *HsmClient, SWRev_t *writeSWRev)
| The service issued to HSM Server writes the SWRevision value based on identifier as param. More...
int32_t | HsmClient_getRandomNum (HsmClient_t *HsmClient, RNGReq_t *getRandomNum)
| Returns the Random Number Generated. More...
int32_t | HsmClient_firmwareUpdate_CertProcess (HsmClient_t *HsmClient, FirmwareUpdateReq_t *pFirmwareUpdateObject)
| service request issued to HSM server to parse the certificate to validate authenticity and identify the firmware component undergoing update This service is valid only for F29H85x SOC More...
int32_t | HsmClient_firmwareUpdate_CodeProgram (HsmClient_t *HsmClient, FirmwareUpdateReq_t *pFirmwareUpdateObject)
| service request issued to HSM server to program the incoming firmware to device dormant banks This service is valid only for F29H85x SOC More...
int32_t | HsmClient_firmwareUpdate_CodeVerify (HsmClient_t *HsmClient, FirmwareUpdateReq_t *pFirmwareUpdateObject)
| service request issued to HSM server to decrypt the firmware programmed in dormant flash bank in place, perform integrity checks on the decrypted firmware and program the certificate in flash memory This service is valid only for F29H85x SOC More...
int32_t | HsmClient_SecCfgUpdate (HsmClient_t *HsmClient, FirmwareUpdateReq_t *pFirmwareUpdateObject)
| Client request to update device Sec-Cfg Valid only for F29x family of devices. More...
int32_t | HsmClient_VerifyROTSwitchingCertificate (HsmClient_t *HsmClient, uint8_t *cert, uint32_t cert_size, uint32_t timeout)
| service request issued to HSM server to validate RoT Switching Certificate More...
int32_t | HsmClient_UpdateKeyRevsion (HsmClient_t *HsmClient, uint32_t timeout)
| service request issued to HSM server to update key revision to 0x2 which changes the root of trust key from secondary keys to back up keys. More...
int32_t | HsmClient_configOTFARegions (HsmClient_t *HsmClient, OTFA_Config_t *OTFA_ConfigInfo, uint32_t timeout)
| Client request to configure the OTFA regions. More...
int32_t | HsmClient_readOTFARegions (HsmClient_t *HsmClient, OTFA_readRegion_t *OTFA_readRegion, uint32_t timeout)
| Client request to read the OTFA regions. More...
int32_t | HsmClient_secCfgValidate (HsmClient_t *HsmClient, SecCfgValidate_t *pSecCfgParams, uint32_t timeout)
| Client request to validate sec-cfg Valid only for F29x family of devices. More...
int32_t | HsmClient_CryptoService (HsmClient_t *HsmClient, CryptoServiceReq_t *svcReq, uint32_t timeout)
| Submit a generic crypto service request to the HSM. Set svcReq->algoId to the algorithm (HSM_CRYPTO_SVC_MAC_CMAC, etc.) and svcReq->subSvcId to the operation (HSM_CRYPTO_SVC_MAC_GENERATE, etc.). Set svcReq->keyId to the keyring index and point svcReq->ptrArgs at the corresponding args struct (e.g. CMACArgs_t). More...
int32_t | HsmClient_activeToDormantBankCopy (HsmClient_t *HsmClient, FlashBankCopy_t *pFlashBankCopyObject, uint32_t timeout)
| Client request to copy active flash bank contents to dormant flash bank Valid only for F29x family of devices. More...
int32_t | HsmClient_runTimeBankSwap (HsmClient_t *HsmClient, BankSwapReq_t *pBankSwapObject)
| Client request to Swap C29 CPU flash banks Valid only for F29x family of devices. More...
int32_t | HsmClient_getDeviceConfig (HsmClient_t *HsmClient, DeviceConfigRead_t *pDeviceConfigObject, uint32_t timeout)
| Client request to get device configuration from HSM This is a blocking call that waits for HSM response. More...

## Variables
volatile uint32_t | gHsmrtLoadStatus = HSMRT_LOAD_NOT_REQUESTED
| Maximum size of the HSM client message queue For Streaming Secure Boot, the break up is as follows, 1 start message (includes the certificate) + 1 finish message + 1 ELF Header Buffer update message + 1 PHT Buffer update message 1024 ELF segment update messages (including the two note segments) More...
static volatile int32_t | gSecureBootStatus = SystemP_SUCCESS
static volatile int32_t | gBootNotificationReceived = SystemP_FAILURE
static int32_t | gLastSentIndex = -1
static int32_t | gLastEnqueuedIndex = -1
static int32_t | gNum_HsmRequestSent = 0
static volatile int32_t | gNum_HsmResponseReceived = 0
static uint32_t | hsm_client_msg_queue_size = 64U
HsmMsg_t | gHsmClientMsgQueue []

## Macro Definition Documentation

## ◆ GET_CACHE_ALIGNED_SIZE

#define GET_CACHE_ALIGNED_SIZE | ( |  | x | ) | ((x + CacheP_CACHELINE_ALIGNMENT) & ~(CacheP_CACHELINE_ALIGNMENT - 1))

Macro calculates the cache-aligned size for a given buffer or data structure.

## Function Documentation

## ◆ Hsmclient_updateBootNotificationRegister()

void Hsmclient_updateBootNotificationRegister | ( | void |  | ) |

## ◆ crc16_ccit()

static uint16_t crc16_ccit | ( | uint8_t * | data,
|  | uint16_t | length
| ) |  |
| static

Calculate crc16_ccit for a given data.

Parameters

  data | data pointer
  length | data length

Returns
  16 bit crc calculated from given data.

## ◆ HsmClient_SendAndRecv()

static int32_t HsmClient_SendAndRecv | ( | HsmClient_t * | HsmClient,
|  | uint32_t | timeout
| ) |  |
| static

Generic send and receive message api.

Parameters

  HsmClient | client type
  timeout | time to wait for interrupt from HSM before throwing timeout exception.

Returns
  SystemP_SUCCESS if transaction is successful else SystemP_FAILURE.

## ◆ HsmClient_EnqueueAndSendMsg()

static int32_t HsmClient_EnqueueAndSendMsg | ( | HsmMsg_t | message | ) |
| static

Generic send message api which enqueus the message in HSM client message queue and tries to send the message via SIPC. This API is non blocking in nature.

Parameters

  message | message that needs to be sent to the HSM core.

Returns
  SystemP_SUCCESS if transaction is successful else SystemP_FAILURE.

## ◆ HsmClient_EnqueueAndSendMsgBlocking()

static int32_t HsmClient_EnqueueAndSendMsgBlocking | ( | HsmMsg_t | message | ) |
| static

Generic send message api which enqueus the message in HSM client message queue and ensures all the messages present in the queue are sent via SIPC. This API is blocking in nature.

Parameters

  message | message that needs to be sent to the HSM core

Returns
  SystemP_SUCCESS if transaction is successful else SystemP_FAILURE.

## ◆ HsmClient_waitForAllResponses()

static int32_t HsmClient_waitForAllResponses | ( |  | ) |
| static

Generic api which waits for all responses to be received.

Returns
  SystemP_SUCCESS if all responses are successful else SystemP_FAILURE.

## ◆ HsmClient_isr()

void HsmClient_isr | ( | uint8_t | remoteCoreId,
|  | uint8_t | localClientId,
|  | uint8_t | remoteClientId,
|  | uint8_t * | msgValue,
|  | void * | args
| ) |  |

## ◆ HsmClient_deinit()

void HsmClient_deinit | ( | void |  | ) |

## Variable Documentation

## ◆ gHsmrtLoadStatus

volatile uint32_t gHsmrtLoadStatus = HSMRT_LOAD_NOT_REQUESTED

Maximum size of the HSM client message queue For Streaming Secure Boot, the break up is as follows, 1 start message (includes the certificate) + 1 finish message + 1 ELF Header Buffer update message + 1 PHT Buffer update message 1024 ELF segment update messages (including the two note segments)

- PT note for boot sequence info
- PT note containing Random string for decryption verification

## ◆ gSecureBootStatus

volatile int32_t gSecureBootStatus = SystemP_SUCCESS
| static

## ◆ gBootNotificationReceived

volatile int32_t gBootNotificationReceived = SystemP_FAILURE
| static

## ◆ gLastSentIndex

int32_t gLastSentIndex = -1
| static

## ◆ gLastEnqueuedIndex

int32_t gLastEnqueuedIndex = -1
| static

## ◆ gNum_HsmRequestSent

int32_t gNum_HsmRequestSent = 0
| static

## ◆ gNum_HsmResponseReceived

volatile int32_t gNum_HsmResponseReceived = 0
| static

## ◆ hsm_client_msg_queue_size

uint32_t hsm_client_msg_queue_size = 64U
| static

## ◆ gHsmClientMsgQueue

HsmMsg_t gHsmClientMsgQueue[]
| extern