AM263Px MCU+ SDK: APIs for HSMCLIENT

| AM263Px MCU+ SDK 26.00.00 |

Data Structures | Functions | Enumerations | Macros
APIs for HSMCLIENT
APIs for SOC Specific Device Drivers

## Introduction

See HSM client for more details.

## Data Structures
union | HsmVer_t
| type for reading HSMRt version. More...
struct | HsmClient_t
| This is a HSMClient type which holds the information needed by hsm client to communicate with HSM . More...
struct | NvmOtpRead_t
| This is an NvmOtpRead type which holds the information of NvmOtp row index and row data corresponding to it . For F29H85x, the rowdIdx corresponds to the Flash Offsets. For AM26x, the rowIdx corresponds to efuse row offsets. More...
struct | NvmOtpRowWrite_t
| This is an NvmOtpRowWrite type which holds the information regarding programming NvmOtp row. For F29H85x, the rowdIdx corresponds to the Flash Offsets. For AM26x, the rowIdx corresponds to efuse row offsets. More...
struct | NvmOtpRowCount_t
| This is an NvmOtpRowCount type which holds the information regarding NvmOtp row count and size of each row in bits. More...
struct | NvmOtpRowProt_t
| This is a NvmOtpRowProt type which holds the information of NvmOtp row index and protection status corresponding to the row index. This structure is not valid for f29h85x. More...
struct | KeyWriterCertHeader_t
| This is a keywriter_cert_header type which holds the information of customer key certificate and debug responce. More...
struct | FirewallRegionReq_t
| This is a FirewallRegionReq type which holds the information of Firewall region configuration. More...
struct | FirewallReq_t
| This is a FirewallReq_t type which holds the information of Firewall configuration. More...
struct | FirewallIntrReq_t
| This is a FirewallIntrReq type which holds the information of MPU Firewall request for interrupt enable, interrupt enable clear, interrupt enable status clear and fault clear. More...
struct | SWRev_t
| This is SWRev type which holds the information regarding Revision identifier and value corresponding to it . More...
struct | DKEK_t
| This is DKEK type which holds the label and context for derivation. This also holds the 256 derived KEK value which is returned by TIFS. More...
struct | RNGReq_t
| This is RNG type which holds the resultPtr for derivation which is returned by TIFS. This also holds the resultLength and DRBG Mode along with seedValue and seedSize. More...
struct | SecureBoot_Stream_t_
| This is the SecureBoot Stream type which holds the data for a specific bootloader to HSM call. This packet is needed by HSM the to do the required operation. More...
struct | FirmwareUpdateReq_t
| This is Firmware Update request structure passed to HSM core via SIPC as argument, these parameters are required by the service handler. More...
struct | OTFA_Region_t
| This is the OTFA Region structure which holds individual region specific information to be written to corresponding OTFA registers. In AM263Px and AM261x, there are 4 OTFA regions. More...
struct | OTFA_readRegion_t
| This is the OTFA Region structure which holds individual region specific information to be read from OTFA registers. More...
struct | OTFA_Config_t
| This is the entire OTFA structure which holds all regions' information 4 regions in AM263Px and AM261x. More...
struct | SecCfgValidate_t
| This is Sec-Cfg validation request structure passed to HSM core via SIPC as argument, these parameters are required by the service handler. Valid only for F29x family of devices. More...
struct | FlashBankCopy_t
| This is active bank to dormant bank copy request structure passed to HSM core via SIPC as argument, these parameters are required by the service handler. Valid only for F29x family of devices. More...
struct | CryptoServiceReq_t
| Outer request struct for HSM_MSG_CRYPTO_SERVICE. Note: These services are only available in HSSE mode. More...
struct | CMACArgs_t
| Args for CMAC generate and verify Note: These services are only available in HSSE mode. More...
struct | HMACArgs_t
| Args for HMAC generate and verify Note: These services are only available in HSSE mode. More...
struct | GMACArgs_t
| Args for GMAC generate and verify Note: These services are only available in HSSE mode. More...
struct | BankSwapReq_t
| This is bank swap request structure passed to HSM core via SIPC as argument, these parameters are required by the service handler. Valid only for F29x family of devices. More...
struct | DeviceConfigSafety_t
struct | DeviceConfigSecurity_t
| Security configuration structure containing security-related device information. More...
struct | DeviceConfigDebug_t
| Debug status structure containing debug access information. Total size: SIZE_OF_DEBUG_DEVICE_CONFIG (16 bytes) More...
struct | DeviceConfigRead_t
| This is device configuration read request structure passed to HSM core via SIPC as argument, these parameters are required by the service handler. More...
struct | HsmMsg_t_
| HSM client / server message format struct. More...

## Functions
union HsmVer_t_ | __attribute__ ((packed)) HsmVer_t
| type for reading HSMRt version. More...
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_init (SIPC_Params *params)
| Initialize the HSM client for current core. More...
void | HsmClient_deInit (void)
| De 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...
int32_t | HsmClient_getVersion (HsmClient_t *HsmClient, HsmVer_t *verId, uint32_t timeToWaitInTick)
| 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 *rowProt)
| 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_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_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_register (HsmClient_t *HsmClient, uint8_t clientId)
| register a client to a particular ClientId More...
void | HsmClient_unregister (HsmClient_t *HsmClient, uint8_t clientId)
| unregister a client to a particular ClientId More...
int32_t | HsmClient_waitForBootNotify (HsmClient_t *HsmClient, uint32_t timeToWaitInTicks)
| Current core will wait for bootnotify message from HSM core. More...
int32_t | Hsmclient_loadHSMRtFirmware (HsmClient_t *gHSMClient, const uint8_t *pHSMRt_firmware)
| Loads the HSMRt firmware. This is typically called by SBL. More...
int32_t | Hsmclient_loadHSMRtFirmwareNonBlocking (const uint8_t *pHSMRt_firmware)
| Loads the HSMRt firmware but does wait for ROM response and boot notification. This is typically called by SBL. 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_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_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_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_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...
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_runTimeBankSwap (HsmClient_t *HsmClient, BankSwapReq_t *pBankSwapObject)
| Client request to Swap C29 CPU flash banks Valid only for F29x family of devices. More...

## Enumerations
enum | HSM_ClientIds_t { HSM_BOOT_NOTIFY_CLIENT_ID = 0, HSM_CLIENT_ID_1, HSM_CLIENT_ID_2, HSM_CLIENT_ID_3, HSM_CLIENT_ID_4 }

## Macros
#define | LABEL_AND_CONTEXT_LEN_MAX 48U
#define | HSMRT_LOAD_NOT_REQUESTED (0U)
| HSMRT load has not been requested. More...
#define | HSMRT_LOAD_REQUESTED (1U)
| HSMRT load has been requested. More...
#define | HSMRT_LOAD_FAILED (2U)
| HSMRT load has failed. More...
#define | HSMRT_LOAD_SUCCEEDED (3U)
| HSMRT load has succeeded. More...
#define | HSM_CRYPTO_SVC_MAC_CMAC (0x0001U)
| Algorithm: AES-CMAC. More...
#define | HSM_CRYPTO_SVC_MAC_HMAC (0x0002U)
| Algorithm: HMAC. More...
#define | HSM_CRYPTO_SVC_MAC_GMAC (0x0003U)
| Algorithm: GMAC. More...
#define | HSM_CRYPTO_HMAC_SHA256 (0x6U) /* matches DTHE_SHA_ALGO_SHA256 */
| HMAC with SHA-256 (32-byte tag) More...
#define | HSM_CRYPTO_HMAC_SHA512 (0x4U) /* matches DTHE_SHA_ALGO_SHA512 */
| HMAC with SHA-512 (64-byte tag) More...
#define | HSM_CRYPTO_SVC_MAC_GENERATE (0x0001U)
| MAC: compute tag and write to ptrTag (used for CMAC, HMAC, GMAC) More...
#define | HSM_CRYPTO_SVC_MAC_VERIFY (0x0002U)
| MAC: compute tag and compare against ptrTag (used for CMAC, HMAC, GMAC) More...
#define | DEVICE_CONFIG_TYPE_SAFETY (0U)
| Safety configuration (dedFotaInfo, hsmPbistStatus) More...
#define | DEVICE_CONFIG_TYPE_SECURITY (1U)
| Security configuration (SecCfg validation, SW revisions, boot retry counts) More...
#define | DEVICE_CONFIG_TYPE_DEBUG (2U)
| Debug configuration (TBD) More...
#define | DEVICE_CONFIG_TYPE_ALL (0xFFU)
| All configuration types. More...
#define | SIZE_OF_SAFETY_DEVICE_CONFIG (8U)
| Size of Safety configuration data in bytes (2 uint32_t values) More...
#define | SIZE_OF_SECURITY_DEVICE_CONFIG (44U)
| Size of security configuration data in bytes (11 uint32_t values) More...
#define | SIZE_OF_DEBUG_DEVICE_CONFIG (16U)
| Size of Debug configuration data in bytes (4 uint32_t values) More...
#define | HSM_MSG_GET_VERSION (0x0002)
| GetVersion service type ID. More...
#define | HSM_MSG_BOOT_NOTIFY (0x000A)
| Boot Notify service type ID. More...
#define | HSM_MSG_GET_DEVICE_CONFIG (0x000B)
| Get device configuration from HSM. More...
#define | HSM_MSG_GET_UID (0x9021)
| Get UID service type ID. More...
#define | HSM_MSG_OPEN_DBG_FIREWALLS (0x900C)
| Open Debug Firewalls service type ID. More...
#define | HSM_MSG_READ_OTP_ROW (0x9022)
| Read Extended otp row type ID. More...
#define | HSM_MSG_WRITE_OTP_ROW (0x9023)
| Write Extended otp row type ID. More...
#define | HSM_MSG_PROT_OTP_ROW (0x9024)
| Protect Extended otp row type ID. More...
#define | HSM_MSG_GET_OTP_ROW_PROT (0x9026)
| Get Extended otp row protection type ID. More...
#define | HSM_MSG_GET_OTP_ROW_COUNT (0x9027)
| Get Extended otp row count service type ID. More...
#define | HSM_MSG_PROC_AUTH_BOOT (0xC120)
| Secure Boot service type ID. More...
#define | HSM_MSG_PROC_AUTH_BOOT_START (0xC12A)
| Secure Boot Streaming Start service type ID. More...
#define | HSM_MSG_PROC_AUTH_BOOT_UPDATE (0xC12B)
| Secure Boot Streaming Update service type ID. More...
#define | HSM_MSG_PROC_AUTH_BOOT_FINISH (0xC12C)
| Secure Boot Streaming Finish service type ID. More...
#define | HSM_MSG_SET_FIREWALL (0x9000U)
| Set Firewall service type ID. More...
#define | HSM_MSG_SET_FIREWALL_INTR (0x9002)
| Set Firewall Interrupt service type ID. More...
#define | HSM_KEYWRITER_SEND_CUST_KEY_CERT (0x9028)
| send KeyWriter customer key certificate More...
#define | HSM_MSG_READ_SWREV (0x9033)
| Read Software Revision service type ID. More...
#define | HSM_MSG_WRITE_SWREV (0x9032)
| Write Software Revision service type ID. More...
#define | HSM_MSG_GET_DKEK (0x9029)
| Get DKEK service type ID. More...
#define | HSM_MSG_GET_RAND (0x9001)
| Get RNG service type ID. More...
#define | HSM_MSG_KEYRING_IMPORT (0x9039)
| Get KEYRING import service type ID. More...
#define | HSM_MSG_FW_UPDATE_CERT_PROCESS (0x9040)
| Process certificate during firmware update/code provisioning. More...
#define | HSM_MSG_FW_UPDATE_CODE_PROGRAM (0x9041)
| Program firmware during firmware update/code provisioning. More...
#define | HSM_MSG_FW_UPDATE_CODE_VERIFY (0x9043)
| Program firmware during firmware update/code provisioning. More...
#define | HSM_MSG_VERIFY_ROT_CERT (0x9044)
| Veriy RoT Switching Certificate Service type ID. More...
#define | HSM_MSG_UPDATE_KEY_REV (0x9045)
| Update Key Revision Service type ID. More...
#define | HSM_MSG_CONFIGURE_OTFA (0x9056)
| Configure OTFA service ID. More...
#define | HSM_MSG_READ_OTFA (0x9057)
| Read OTFA service ID. More...
#define | HSM_MSG_PROC_AUTH_BOOT_SEC_CFG (0x9058)
| Validate Sec-Cfg service ID. More...
#define | HSM_MSG_FLASH_BANK_COPY (0x9059)
| Copy active flash bank contents to dormant flash bank. More...
#define | HSM_MSG_FW_UPDATE_SECCFG (0x905AU)
| Program Sec-Cfg to SOC non main flash. More...
#define | HSM_MSG_BANK_SWAP (0x905BU)
| Swap C29 CPU-1/3 flash banks. More...
#define | HSM_MSG_CRYPTO_SERVICE (0xA001U)
| Generic Crypto service ID. More...
#define | HSM_FLAG_AOP (0x11)
| HSM FLAG used by HSM client to indicate that it expects ACK messasge from HSM and will wait for a response message. More...
#define | HSM_FLAG_NAOP (0x22)
| HSM FLAG used by HSM client to indicate that it does not expects an ACK messasge from HSM and will not wait for a response message. More...
#define | HSM_FLAG_ACK (0xAA)
| HSM FLAG used by HSM server to indicate that the request has been processed. More...
#define | HSM_FLAG_NACK (0x55)
| HSM FLAG used by HSM server to indicate that the request has not been processed. More...
#define | HSM_CLIENT_ID (0x01)
| HSM server SIPC client Id. More...
#define | HSM_UID_SIZE (64U)
| UID or Unique ID is a device specific ID of 64 bytes. More...
#define | HSM_DBG_CERT_SIZE (4096U)
| Maximum Certificate Size allowed for Debug Open. More...
#define | HSM_KEYRING_CERT_SIZE (10280U)
| Maximum Certificate Size allowed for Keyring Import. More...
#define | HSM_FIRMWARE_CHUNK_SIZE (16384U)
| Maximum firmware Size allowed for code provisioning. More...
#define | CERT_TYPE_SECCFG_CPU1 (0x3U)
| Certificate type for C29 CPU1 Sec-cfg. More...
#define | CERT_TYPE_SECCFG_CPU2 (0x5U)
| Certificate type for C29 CPU2 Sec-cfg. More...
#define | CERT_TYPE_SECCFG_CPU3 (0x6U)
| Certificate type for C29 CPU3 Sec-cfg. More...
#define | C29_CPU1_FLASH_BANK (0x1U)
| C29 CPU1 macro to be used while requesting active to dormant flash bank copy or C29 CPU flash bank swap services. Valid only for F29x family of devices. More...
#define | C29_CPU3_FLASH_BANK (0x3U)
| C29 CPU3 macro to be used while requesting active to dormant flash bank copy or C29 CPU flash bank swap services. Valid only for F29x family of devices. More...
#define | HSM_CPU_FLASH_BANK (0x0U)
| HSM CPU macro to be used while requesting active to dormant flash bank copy Valid only for F29x family of devices. More...
#define | LFU_BANK_SWAP_READY (0x5AU)
| MACRO used by HSM for LFU synchronizsation. More...

## Macro Definition Documentation

## ◆ LABEL_AND_CONTEXT_LEN_MAX

#define LABEL_AND_CONTEXT_LEN_MAX 48U

## ◆ HSMRT_LOAD_NOT_REQUESTED

#define HSMRT_LOAD_NOT_REQUESTED (0U)

HSMRT load has not been requested.

## ◆ HSMRT_LOAD_REQUESTED

#define HSMRT_LOAD_REQUESTED (1U)

HSMRT load has been requested.

## ◆ HSMRT_LOAD_FAILED

#define HSMRT_LOAD_FAILED (2U)

HSMRT load has failed.

## ◆ HSMRT_LOAD_SUCCEEDED

#define HSMRT_LOAD_SUCCEEDED (3U)

HSMRT load has succeeded.

## ◆ HSM_CRYPTO_SVC_MAC_CMAC

#define HSM_CRYPTO_SVC_MAC_CMAC (0x0001U)

Algorithm: AES-CMAC.

## ◆ HSM_CRYPTO_SVC_MAC_HMAC

#define HSM_CRYPTO_SVC_MAC_HMAC (0x0002U)

Algorithm: HMAC.

## ◆ HSM_CRYPTO_SVC_MAC_GMAC

#define HSM_CRYPTO_SVC_MAC_GMAC (0x0003U)

Algorithm: GMAC.

## ◆ HSM_CRYPTO_HMAC_SHA256

#define HSM_CRYPTO_HMAC_SHA256 (0x6U) /* matches DTHE_SHA_ALGO_SHA256 */

HMAC with SHA-256 (32-byte tag)

## ◆ HSM_CRYPTO_HMAC_SHA512

#define HSM_CRYPTO_HMAC_SHA512 (0x4U) /* matches DTHE_SHA_ALGO_SHA512 */

HMAC with SHA-512 (64-byte tag)

## ◆ HSM_CRYPTO_SVC_MAC_GENERATE

#define HSM_CRYPTO_SVC_MAC_GENERATE (0x0001U)

MAC: compute tag and write to ptrTag (used for CMAC, HMAC, GMAC)

## ◆ HSM_CRYPTO_SVC_MAC_VERIFY

#define HSM_CRYPTO_SVC_MAC_VERIFY (0x0002U)

MAC: compute tag and compare against ptrTag (used for CMAC, HMAC, GMAC)

## ◆ DEVICE_CONFIG_TYPE_SAFETY

#define DEVICE_CONFIG_TYPE_SAFETY (0U)

Safety configuration (dedFotaInfo, hsmPbistStatus)

## ◆ DEVICE_CONFIG_TYPE_SECURITY

#define DEVICE_CONFIG_TYPE_SECURITY (1U)

Security configuration (SecCfg validation, SW revisions, boot retry counts)

## ◆ DEVICE_CONFIG_TYPE_DEBUG

#define DEVICE_CONFIG_TYPE_DEBUG (2U)

Debug configuration (TBD)

## ◆ DEVICE_CONFIG_TYPE_ALL

#define DEVICE_CONFIG_TYPE_ALL (0xFFU)

All configuration types.

## ◆ SIZE_OF_SAFETY_DEVICE_CONFIG

#define SIZE_OF_SAFETY_DEVICE_CONFIG (8U)

Size of Safety configuration data in bytes (2 uint32_t values)

## ◆ SIZE_OF_SECURITY_DEVICE_CONFIG

#define SIZE_OF_SECURITY_DEVICE_CONFIG (44U)

Size of security configuration data in bytes (11 uint32_t values)

## ◆ SIZE_OF_DEBUG_DEVICE_CONFIG

#define SIZE_OF_DEBUG_DEVICE_CONFIG (16U)

Size of Debug configuration data in bytes (4 uint32_t values)

## ◆ HSM_MSG_GET_VERSION

#define HSM_MSG_GET_VERSION (0x0002)

GetVersion service type ID.

## ◆ HSM_MSG_BOOT_NOTIFY

#define HSM_MSG_BOOT_NOTIFY (0x000A)

Boot Notify service type ID.

## ◆ HSM_MSG_GET_DEVICE_CONFIG

#define HSM_MSG_GET_DEVICE_CONFIG (0x000B)

Get device configuration from HSM.

## ◆ HSM_MSG_GET_UID

#define HSM_MSG_GET_UID (0x9021)

Get UID service type ID.

## ◆ HSM_MSG_OPEN_DBG_FIREWALLS

#define HSM_MSG_OPEN_DBG_FIREWALLS (0x900C)

Open Debug Firewalls service type ID.

## ◆ HSM_MSG_READ_OTP_ROW

#define HSM_MSG_READ_OTP_ROW (0x9022)

Read Extended otp row type ID.

## ◆ HSM_MSG_WRITE_OTP_ROW

#define HSM_MSG_WRITE_OTP_ROW (0x9023)

Write Extended otp row type ID.

## ◆ HSM_MSG_PROT_OTP_ROW

#define HSM_MSG_PROT_OTP_ROW (0x9024)

Protect Extended otp row type ID.

## ◆ HSM_MSG_GET_OTP_ROW_PROT

#define HSM_MSG_GET_OTP_ROW_PROT (0x9026)

Get Extended otp row protection type ID.

## ◆ HSM_MSG_GET_OTP_ROW_COUNT

#define HSM_MSG_GET_OTP_ROW_COUNT (0x9027)

Get Extended otp row count service type ID.

## ◆ HSM_MSG_PROC_AUTH_BOOT

#define HSM_MSG_PROC_AUTH_BOOT (0xC120)

Secure Boot service type ID.

## ◆ HSM_MSG_PROC_AUTH_BOOT_START

#define HSM_MSG_PROC_AUTH_BOOT_START (0xC12A)

Secure Boot Streaming Start service type ID.

## ◆ HSM_MSG_PROC_AUTH_BOOT_UPDATE

#define HSM_MSG_PROC_AUTH_BOOT_UPDATE (0xC12B)

Secure Boot Streaming Update service type ID.

## ◆ HSM_MSG_PROC_AUTH_BOOT_FINISH

#define HSM_MSG_PROC_AUTH_BOOT_FINISH (0xC12C)

Secure Boot Streaming Finish service type ID.

## ◆ HSM_MSG_SET_FIREWALL

#define HSM_MSG_SET_FIREWALL (0x9000U)

Set Firewall service type ID.

## ◆ HSM_MSG_SET_FIREWALL_INTR

#define HSM_MSG_SET_FIREWALL_INTR (0x9002)

Set Firewall Interrupt service type ID.

## ◆ HSM_KEYWRITER_SEND_CUST_KEY_CERT

#define HSM_KEYWRITER_SEND_CUST_KEY_CERT (0x9028)

send KeyWriter customer key certificate

## ◆ HSM_MSG_READ_SWREV

#define HSM_MSG_READ_SWREV (0x9033)

Read Software Revision service type ID.

## ◆ HSM_MSG_WRITE_SWREV

#define HSM_MSG_WRITE_SWREV (0x9032)

Write Software Revision service type ID.

## ◆ HSM_MSG_GET_DKEK

#define HSM_MSG_GET_DKEK (0x9029)

Get DKEK service type ID.

## ◆ HSM_MSG_GET_RAND

#define HSM_MSG_GET_RAND (0x9001)

Get RNG service type ID.

## ◆ HSM_MSG_KEYRING_IMPORT

#define HSM_MSG_KEYRING_IMPORT (0x9039)

Get KEYRING import service type ID.

## ◆ HSM_MSG_FW_UPDATE_CERT_PROCESS

#define HSM_MSG_FW_UPDATE_CERT_PROCESS (0x9040)

Process certificate during firmware update/code provisioning.

## ◆ HSM_MSG_FW_UPDATE_CODE_PROGRAM

#define HSM_MSG_FW_UPDATE_CODE_PROGRAM (0x9041)

Program firmware during firmware update/code provisioning.

## ◆ HSM_MSG_FW_UPDATE_CODE_VERIFY

#define HSM_MSG_FW_UPDATE_CODE_VERIFY (0x9043)

Program firmware during firmware update/code provisioning.

## ◆ HSM_MSG_VERIFY_ROT_CERT

#define HSM_MSG_VERIFY_ROT_CERT (0x9044)

Veriy RoT Switching Certificate Service type ID.

## ◆ HSM_MSG_UPDATE_KEY_REV

#define HSM_MSG_UPDATE_KEY_REV (0x9045)

Update Key Revision Service type ID.

## ◆ HSM_MSG_CONFIGURE_OTFA

#define HSM_MSG_CONFIGURE_OTFA (0x9056)

Configure OTFA service ID.

## ◆ HSM_MSG_READ_OTFA

#define HSM_MSG_READ_OTFA (0x9057)

Read OTFA service ID.

## ◆ HSM_MSG_PROC_AUTH_BOOT_SEC_CFG

#define HSM_MSG_PROC_AUTH_BOOT_SEC_CFG (0x9058)

Validate Sec-Cfg service ID.

## ◆ HSM_MSG_FLASH_BANK_COPY

#define HSM_MSG_FLASH_BANK_COPY (0x9059)

Copy active flash bank contents to dormant flash bank.

## ◆ HSM_MSG_FW_UPDATE_SECCFG

#define HSM_MSG_FW_UPDATE_SECCFG (0x905AU)

Program Sec-Cfg to SOC non main flash.

## ◆ HSM_MSG_BANK_SWAP

#define HSM_MSG_BANK_SWAP (0x905BU)

Swap C29 CPU-1/3 flash banks.

## ◆ HSM_MSG_CRYPTO_SERVICE

#define HSM_MSG_CRYPTO_SERVICE (0xA001U)

Generic Crypto service ID.

## ◆ HSM_FLAG_AOP

#define HSM_FLAG_AOP (0x11)

HSM FLAG used by HSM client to indicate that it expects ACK messasge from HSM and will wait for a response message.

## ◆ HSM_FLAG_NAOP

#define HSM_FLAG_NAOP (0x22)

HSM FLAG used by HSM client to indicate that it does not expects an ACK messasge from HSM and will not wait for a response message.

## ◆ HSM_FLAG_ACK

#define HSM_FLAG_ACK (0xAA)

HSM FLAG used by HSM server to indicate that the request has been processed.

## ◆ HSM_FLAG_NACK

#define HSM_FLAG_NACK (0x55)

HSM FLAG used by HSM server to indicate that the request has not been processed.

## ◆ HSM_CLIENT_ID

#define HSM_CLIENT_ID (0x01)

HSM server SIPC client Id.

## ◆ HSM_UID_SIZE

#define HSM_UID_SIZE (64U)

UID or Unique ID is a device specific ID of 64 bytes.

## ◆ HSM_DBG_CERT_SIZE

#define HSM_DBG_CERT_SIZE (4096U)

Maximum Certificate Size allowed for Debug Open.

## ◆ HSM_KEYRING_CERT_SIZE

#define HSM_KEYRING_CERT_SIZE (10280U)

Maximum Certificate Size allowed for Keyring Import.

## ◆ HSM_FIRMWARE_CHUNK_SIZE

#define HSM_FIRMWARE_CHUNK_SIZE (16384U)

Maximum firmware Size allowed for code provisioning.

## ◆ CERT_TYPE_SECCFG_CPU1

#define CERT_TYPE_SECCFG_CPU1 (0x3U)

Certificate type for C29 CPU1 Sec-cfg.

## ◆ CERT_TYPE_SECCFG_CPU2

#define CERT_TYPE_SECCFG_CPU2 (0x5U)

Certificate type for C29 CPU2 Sec-cfg.

## ◆ CERT_TYPE_SECCFG_CPU3

#define CERT_TYPE_SECCFG_CPU3 (0x6U)

Certificate type for C29 CPU3 Sec-cfg.

## ◆ C29_CPU1_FLASH_BANK

#define C29_CPU1_FLASH_BANK (0x1U)

C29 CPU1 macro to be used while requesting active to dormant flash bank copy or C29 CPU flash bank swap services. Valid only for F29x family of devices.

## ◆ C29_CPU3_FLASH_BANK

#define C29_CPU3_FLASH_BANK (0x3U)

C29 CPU3 macro to be used while requesting active to dormant flash bank copy or C29 CPU flash bank swap services. Valid only for F29x family of devices.

## ◆ HSM_CPU_FLASH_BANK

#define HSM_CPU_FLASH_BANK (0x0U)

HSM CPU macro to be used while requesting active to dormant flash bank copy Valid only for F29x family of devices.

## ◆ LFU_BANK_SWAP_READY

#define LFU_BANK_SWAP_READY (0x5AU)

MACRO used by HSM for LFU synchronizsation.

## Enumeration Type Documentation

## ◆ HSM_ClientIds_t

enum HSM_ClientIds_t

Enumerator
HSM_BOOT_NOTIFY_CLIENT_ID |
HSM_CLIENT_ID_1 |
HSM_CLIENT_ID_2 |
HSM_CLIENT_ID_3 |
HSM_CLIENT_ID_4 |

## Function Documentation

## ◆ __attribute__()

union HsmVer_t_ __attribute__ | ( | (packed) |  | ) |

type for reading HSMRt version.

HSM client / server message format struct.

This is the SecureBoot Stream type which holds the data for a specific bootloader to HSM call. This packet is needed by HSM the to do the required operation.

## ◆ HsmClient_checkAndWaitForBootNotification()

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.

Returns
  1. SystemP_SUCCESS if HSMRT load is successful.
  2. SystemP_FAILURE if HSMRT load fails.

## ◆ HsmClient_init()

int32_t HsmClient_init | ( | SIPC_Params * | params | ) |

Initialize the HSM client for current core.

Parameters

  params | [IN] SIPC_notify params.

Returns
  1. SystemP_SUCCESS if init sequence successful.
  2. SystemP_FAILURE if init sequence fails.

## ◆ HsmClient_deInit()

void HsmClient_deInit | ( | void |  | ) |

De initialize the HSM client for current core.

## ◆ HsmClient_SecureBootQueueInit()

void HsmClient_SecureBootQueueInit | ( | uint32_t | configured_hsm_client_msg_queue_size | ) |

Customize the size of the HSM client message queue.

Parameters

  configured_hsm_client_msg_queue_size | Desired size of the HSM client message queue passed by the user.

## ◆ HsmClient_getVersion()

int32_t HsmClient_getVersion | ( | HsmClient_t * | HsmClient,
|  | HsmVer_t * | verId,
|  | uint32_t | timeToWaitInTick
| ) |  |

populates the current HSMRT version Id by default the hsm flag is set to HSM_FLAG_AOP for this service

Parameters

  timeToWaitInTick | [IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)
  HsmClient | [IN] Client object which is using this getversion API.
  verId | [OUT] populates HsmVer_t struct which describes current version. This object's memory address needs to be cache aligned.

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.
  3. SystemP_TIMEOUT if timeout exception occours.

## ◆ HsmClient_getUID()

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.

Parameters

  timeout | [IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)
  HsmClient | [IN] Client object which is using this getUID API.
  uid | [OUT] populates UID value.

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.
  3. SystemP_TIMEOUT if timeout exception occours.

## ◆ HsmClient_openDbgFirewall()

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.

Parameters

  timeout | [IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)
  HsmClient | [IN] Client object which is using this openDbgFirewalls API.
  cert | [IN] point to the location of certificate in the device memory.
  cert_size | [IN] size of certificate.

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.
  3. SystemP_TIMEOUT if timeout exception occours.

## ◆ HsmClient_importKeyring()

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.

Parameters

  timeout | [IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)
  HsmClient | [IN] Client object which is using this importKeyring API.
  cert | [IN] point to the location of certificate in the device memory.
  cert_size | [IN] size of certificate.

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.
  3. SystemP_TIMEOUT if timeout exception occours.

## ◆ HsmClient_readOTPRow()

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.

Parameters

  HsmClient | [IN] HsmClient object.
  readRow | [IN] populates NvmOtpRead_t struct with rowData corresponding to rowIdx.

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.

## ◆ HsmClient_writeOTPRow()

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.

Parameters

  HsmClient | [IN] HsmClient object.
  writeRow | [IN] populates NvmOtpRowWrite_t struct with rowData corresponding to rowIdx.

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.

## ◆ HsmClient_lockOTPRow()

int32_t HsmClient_lockOTPRow | ( | HsmClient_t * | HsmClient,
|  | NvmOtpRowProt_t * | rowProt
| ) |  |

The service issued to HSM Server sets the protection status bit of the specified row to 1. This API is not valid for F29H85x.

Parameters

  HsmClient | [IN] HsmClient object.
  rowProt | [IN] Pointer to NvmOtpRowProt_t struct which contains the row index and row protection status

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.

## ◆ HsmClient_getOTPRowCount()

int32_t HsmClient_getOTPRowCount | ( | HsmClient_t * | HsmClient,
|  | NvmOtpRowCount_t * | rowCount
| ) |  |

The service issued to HSM Server retrieves the count of extended OTP rows.

Parameters

  HsmClient | [IN] HsmClient object.
  rowCount | [IN] Pointer to NvmOtpRowCount_t struct which is populated by HSM server with row count and row size

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.

## ◆ HsmClient_getOTPRowProtection()

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.

Parameters

  HsmClient | [IN] HsmClient object.
  rowProt | [IN] Pointer to NvmOtpRowProt_t struct which is populated by HSM server with row protection status

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.

## ◆ HsmClient_procAuthBoot()

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.

Parameters

  timeout | [IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)
  HsmClient | [IN] Client object which is using this openDbgFirewalls API.
  cert | [IN] point to the location of certificate in the device memory.
  cert_size | [IN] size of certificate.

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.
  3. SystemP_TIMEOUT if timeout exception occours.

## ◆ HsmClient_procAuthBootStart()

int32_t HsmClient_procAuthBootStart | ( | HsmClient_t * | HsmClient,
|  | SecureBoot_Stream_t * | secureBootInfo
| ) |  |

The service issued to HSM Server helps with extended secure boot for applications.

Parameters

  HsmClient | [IN] Client object which is using this openDbgFirewalls API.
  secureBootInfo | [IN] pointer to the secure boot information object in shared memory.

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.
  3. SystemP_TIMEOUT if timeout exception occours.

## ◆ HsmClient_procAuthBootUpdate()

int32_t HsmClient_procAuthBootUpdate | ( | HsmClient_t * | HsmClient,
|  | SecureBoot_Stream_t * | secureBootInfo
| ) |  |

The service issued to HSM Server helps with extended secure boot for applications.

Parameters

  HsmClient | [IN] Client object which is using this openDbgFirewalls API.
  secureBootInfo | [IN] pointer to the secure boot information object in shared memory.

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.
  3. SystemP_TIMEOUT if timeout exception occours.

## ◆ HsmClient_procAuthBootFinish()

int32_t HsmClient_procAuthBootFinish | ( | HsmClient_t * | HsmClient,
|  | SecureBoot_Stream_t * | secureBootInfo
| ) |  |

The service issued to HSM Server helps with extended secure boot for applications.

Parameters

  HsmClient | [IN] Client object which is using this openDbgFirewalls API.
  secureBootInfo | [IN] pointer to the secure boot information object in shared memory

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.
  3. SystemP_TIMEOUT if timeout exception occours.

## ◆ HsmClient_setFirewall()

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.

Parameters

  timeout | [IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)
  HsmClient | [IN] HsmClient object.
  FirewallReqObj | [IN] Pointer to FirewallReq_t struct which contains information required for HSM to process set firewall request.

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.
  3. SystemP_TIMEOUT if timeout exception occours.

## ◆ HsmClient_FirewallIntr()

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.

Parameters

  timeout | [IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)
  HsmClient | [IN] HsmClient object.
  FirewallIntrReqObj | [IN] Pointer to FirewallIntrReq_t struct which contains information required for HSM to process firewall interrupt request.

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.
  3. SystemP_TIMEOUT if timeout exception occours.

## ◆ HsmClient_keyWriter()

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,.

Parameters

  HsmClient | [IN] Client object which is using this API.
  certHeader | [IN] point to the location of certificate in the device memory. This object's memory address needs to be cache aligned.
  timeout | [IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.
  3. SystemP_TIMEOUT if timeout exception occours.

## ◆ HsmClient_readSWRev()

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.

Parameters

  HsmClient | [IN] HsmClient object.
  readSWRev | [IN] populates SWRev_t struct with SWRev value corresponding to identifier.

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.

## ◆ HsmClient_writeSWRev()

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.

Parameters

  HsmClient | [IN] HsmClient object.
  writeSWRev | [IN] updates the SWRev efuses with SWRev value corresponding to identifier.

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.

## ◆ HsmClient_getDKEK()

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.

The service issued to HSM Server retrieves the derived KEK.

Parameters

  timeout | [IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)
  HsmClient | [IN] HsmClient object.
  getDKEK | [IN] Pointer to DKEK_t which contains the request structure for Derived KEK.

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.

## ◆ HsmClient_register()

int32_t HsmClient_register | ( | HsmClient_t * | HsmClient,
|  | uint8_t | clientId
| ) |  |

register a client to a particular ClientId

Parameters

  HsmClient | [IN] HsmClient object.
  clientId | [IN] enable HSM <--> R5 communication for given clientID

Returns
  1. SystemP_SUCCESS if clientId is available
  2. SystemP_FAILURE if clientId is not available or already in use.

## ◆ HsmClient_unregister()

void HsmClient_unregister | ( | HsmClient_t * | HsmClient,
|  | uint8_t | clientId
| ) |  |

unregister a client to a particular ClientId

Parameters

  HsmClient | [IN] HsmClient object
  clientId | [IN] disable HSM <--> R5 communication for given clientId

## ◆ HsmClient_waitForBootNotify()

int32_t HsmClient_waitForBootNotify | ( | HsmClient_t * | HsmClient,
|  | uint32_t | timeToWaitInTicks
| ) |  |

Current core will wait for bootnotify message from HSM core.

Parameters

  HsmClient | [IN] HsmClient object
  timeToWaitInTicks | [IN] amount of time to block waiting for semaphore to be available, in units of SystemP_timeout if timeout exception occours.system ticks (see KERNEL_DPL_CLOCK_PAGE)

Returns
  1. SystemP_SUCCESS -: when BootNotify received
  2. SystemP_FAILURE -: if faulty msg received

## ◆ Hsmclient_loadHSMRtFirmware()

int32_t Hsmclient_loadHSMRtFirmware | ( | HsmClient_t * | gHSMClient,
|  | const uint8_t * | pHSMRt_firmware
| ) |  |

Loads the HSMRt firmware. This is typically called by SBL.

Parameters

  gHSMClient | [IN] Pointer to registered HSM Client
  pHSMRt_firmware | [IN] Pointer to signed HSMRt binary

Returns
  SystemP_SUCCESS on success, else SystemP_FAILURE

## ◆ Hsmclient_loadHSMRtFirmwareNonBlocking()

int32_t Hsmclient_loadHSMRtFirmwareNonBlocking | ( | const uint8_t * | pHSMRt_firmware | ) |

Loads the HSMRt firmware but does wait for ROM response and boot notification. This is typically called by SBL.

Parameters

  pHSMRt_firmware | [IN] Pointer to signed HSMRt binary

Returns
  SystemP_SUCCESS on success, else SystemP_FAILURE

## ◆ HsmClient_getRandomNum()

int32_t HsmClient_getRandomNum | ( | HsmClient_t * | HsmClient,
|  | RNGReq_t * | getRandomNum
| ) |  |

Returns the Random Number Generated.

Parameters

  HsmClient | [IN] HsmClient object
  getRandomNum | [IN] Pointer to RNGReq_t which contains the request structure for Random Number Generated.

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.

## ◆ HsmClient_firmwareUpdate_CertProcess()

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

Parameters

  HsmClient | [IN] Client object which is using this API.
  pFirmwareUpdateObject | [IN] Pointer to arguments to be passed to HSM core via SIPC.

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.
  3. SystemP_TIMEOUT if timeout exception occours.

## ◆ HsmClient_firmwareUpdate_CodeProgram()

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

Parameters

  HsmClient | [IN] Client object which is using this API.
  pFirmwareUpdateObject | [IN] Pointer to arguments to be passed to HSM core via SIPC.

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.
  3. SystemP_TIMEOUT if timeout exception occours.

## ◆ HsmClient_firmwareUpdate_CodeVerify()

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

Parameters

  HsmClient | [IN] Client object which is using this API.
  pFirmwareUpdateObject | [IN] Pointer to arguments to be passed to HSM core via SIPC.

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.
  3. SystemP_TIMEOUT if timeout exception occours.

## ◆ HsmClient_VerifyROTSwitchingCertificate()

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

Parameters

  timeout | [IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)
  HsmClient | [IN] Client object which is using this RoT Switching API.
  cert | [IN] point to the location of certificate in the device memory.
  cert_size | [IN] size of certificate.

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.
  3. SystemP_TIMEOUT if timeout exception occours.

## ◆ HsmClient_UpdateKeyRevsion()

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.

Parameters

  timeout | [IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)
  HsmClient | [IN] Client object which is using this RoT Switching API.

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.
  3. SystemP_TIMEOUT if timeout exception occours.

## ◆ HsmClient_configOTFARegions()

int32_t HsmClient_configOTFARegions | ( | HsmClient_t * | HsmClient,
|  | OTFA_Config_t * | OTFA_ConfigInfo,
|  | uint32_t | timeout
| ) |  |

Client request to configure the OTFA regions.

Parameters

  HsmClient | [IN] HsmClient object
  OTFA_ConfigInfo | [IN] OTFA Config Info
  timeout | [IN] timeout

Returns
  1. SystemP_SUCCESS if returns successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.

## ◆ HsmClient_readOTFARegions()

int32_t HsmClient_readOTFARegions | ( | HsmClient_t * | HsmClient,
|  | OTFA_readRegion_t * | OTFA_readRegion,
|  | uint32_t | timeout
| ) |  |

Client request to read the OTFA regions.

Parameters

  HsmClient | [IN] HsmClient object
  OTFA_readRegion | [IN] OTFA Read Region
  timeout | [IN] timeout

Returns
  1. SystemP_SUCCESS if reading done successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.

## ◆ HsmClient_secCfgValidate()

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.

Parameters

  HsmClient | [IN] HsmClient object
  pSecCfgParams | [IN] Sec-Cfg object
  timeout | [IN] timeout

Returns
  1. SystemP_SUCCESS if validation done successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.

## ◆ HsmClient_activeToDormantBankCopy()

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.

Parameters

  HsmClient | [IN] HsmClient object
  pFlashBankCopyObject | [IN] Flash Bank copy object
  timeout | [IN] timeout

Returns
  1. SystemP_SUCCESS if copy done successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.

## ◆ HsmClient_SecCfgUpdate()

int32_t HsmClient_SecCfgUpdate | ( | HsmClient_t * | HsmClient,
|  | FirmwareUpdateReq_t * | pFirmwareUpdateObject
| ) |  |

Client request to update device Sec-Cfg Valid only for F29x family of devices.

Parameters

  HsmClient | [IN] HsmClient object
  pFirmwareUpdateObject | [IN] Pointer to arguments to be passed to HSM core via SIPC.

Returns
  1. SystemP_SUCCESS if copy done successfully
  2. SystemP_FAILURE if NACK message is received or client id not registered.

## ◆ HsmClient_getDeviceConfig()

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.

Parameters

  HsmClient | [IN] HsmClient object
  pDeviceConfigObject | [IN] Pointer to device config read request structure
  timeout | [IN] Timeout in system ticks

Returns
  1. SystemP_SUCCESS if operation successful
  2. SystemP_FAILURE if NACK received or client not registered
  3. SystemP_TIMEOUT if timeout occurs

## ◆ HsmClient_CryptoService()

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).

Parameters

  HsmClient | [IN] HsmClient object
  svcReq | [IN/OUT] Pointer to CryptoServiceReq_t; for generate operations, output is written to ptrTag on success
  timeout | [IN] Timeout in ticks (SystemP_WAIT_FOREVER to block)

Returns
  SystemP_SUCCESS on ACK, SystemP_FAILURE on NACK or error.

## ◆ HsmClient_runTimeBankSwap()

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.

Parameters

  HsmClient | [IN] HsmClient object
  pBankSwapObject | [IN] Pointer to arguments to be passed to HSM core via SIPC.

Returns
  1. SystemP_SUCCESS if message sent successfully
  2. SystemP_FAILURE if message not sent.