AM263Px MCU+ SDK: hsmclient.h File Reference

| AM263Px MCU+ SDK 26.00.00 |

Data Structures | Macros | Functions | Variables
hsmclient.h File Reference

Go to the source code of this file.

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

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

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

## Variables
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
uint8_t * | dataIn
uint32_t | dataLen
uint8_t | canBeEncrypted

## Variable Documentation

## ◆ HsmrtVer

uint64_t HsmrtVer

< A 64 bit unique Version number

## ◆ PatchVer

uint8_t PatchVer

## ◆ MinorVer

uint8_t MinorVer

patch Version number refer HSMRT_PATCH_VER in TIFS Docs

## ◆ MajorVer

uint8_t MajorVer

HSMRt minor version number refer HSMRT_MINOR_VER in TIFS Docs

## ◆ ApiVer

uint8_t ApiVer

HSMRt major version number refer HSMRT_MAJOR_VER in TIFS Docs

## ◆ SocType

uint8_t SocType

HSMRt API version number refer HSMRT_APIS_VER in TIFS Docs

## ◆ BinType

uint8_t BinType

HSMRt Soc type ID refer HSMRT_SOC_TYPE in TIFS Docs

## ◆ HsmType

uint8_t HsmType

HSMRt Binary type ID refer HSMRT_BIN_TYPE in TIFS Docs

## ◆ DevType

uint8_t DevType

HSM Architecture version

## ◆ VerStruct

struct { ... } VerStruct

## ◆ dataIn

uint8_t* dataIn

Pointer to the data in shared memory.

## ◆ dataLen

uint32_t dataLen

Size of the data.

## ◆ canBeEncrypted

uint8_t canBeEncrypted

Whether this data could be encrypted or not.