F29H85x-SDK  26.00.00
 
HSM client

Table of Contents

Note
In the following document and in TIFS-MCU document the term used to refer to the Firmware which runs on HSM core is TIFS-MCU Firmware. Please note that the terms 1.**HSMRt Firmware** and 2.**HSMRt** are synonymous to TIFS-MCU Firmware.

Introduction

  • The objective of HSM client is to provide APIs for accessing HSM services. Below given model explains the use of HSM client graphically. It uses SIPC Notify driver as a low level message passing mechanism to talk to HSM M4 core. HSM client APIs can be used with either FreeRTOS or noRTOS application.
  • The HSM Server provides APIs that will read the incoming request in the form of SIPC message and provide appropriate service based on it. The application which uses HSM server is also known as TIFS-MCU (HSM runtime firmware). 

HSM CLIENT communication model
  • Along side providing services at runtime TIFS-MCU also enables secure boot flow. It is responsible for authenticating C29 application images and sends a notification to flash kernel if it is a valid app image , later HSM will program the C29 applications to respective flash memories.
  • The trusted C29 cores which can communicate with HSM are known as Secure hosts.
Note
All the services described in the page below apart from HSM Client Key Writer Service are valid only for HS-FS device states.
  • Following services are supported in f29h85x SDK
    • BootNotify Service -: A special message sent by TIFS-MCU Firmware to indicate C29 Application that TIFS-MCU boot was successful.
    • GetVersion Service -: Get The current version of TIFS-MCU Firmware.
    • GetUID Service -: For HS-SE device only. Get the unique ID of the device.
    • Get Device Config Service -: For HS-SE device only. Get the Device Configuration from the device.
    • Debug Service -: For HS-SE device only. By default debug port for all C29 and HSM is closed. Secure C29s can request debug port access via runtime Debug services.
    • Get DKEK Service -: For HS-SE device only. Get Derived KEK.
    • Get Random Number Service -: Get the random number as generated by TRNG engine.
    • Key Writer Service -: For converting device from HSFS to HSKP.
    • Firmware Update Certificate Process Service -: Process the certificate of incoming firmware for validation.
    • Firmware Update Code Program Service -: Program flash memory with incoming firmware.
    • Firmware Update Code Verify Service -: Verify new firmware programmed in flash memory.
    • Verify RoT Switching Certificate Service -: For HS-SE device only. Validate the RoT Switching Certificate to temporarily switch to backup keys.
    • Update Key Revision Service -: For HS-SE device only. Permanently switch the RoT to backup keys.
    • Read OTP Row Service -: For HS-SE device only. Read data from Extended OTP row.
    • Write OTP Row Service -: For HS-SE device only. Write data to Extended OTP row.
    • Get OTP Row Count Service -: For HS-SE device only. Get the count of Extended OTP rows.
    • Read SW Revision Service -: For HS-SE device only. Read software revision value for SBL, HSM, APP, or SECCFG.
    • Write SW Revision Service -: For HS-SE device only. Write software revision value for anti-rollback protection.
    • Proc Auth Boot Service -: For HS-SE device only. Authenticate application binaries for C29 CPUs and HSM CPU.
    • Sec-Cfg Validation Service -: For HS-SE device only. Authenticate SSU configurations for C29 CPUs.
    • Active to Dormant Bank Copy Service -: For HS-SE device only. Copy contents of active flash bank to dormant flash bank.
    • Crypto Service - MAC Service -: For HS-SE device only. Compute or verify a Message Authentication Code (MAC) using a keyring-stored key. Supports AES-CMAC, HMAC-SHA256, HMAC-SHA512, and GMAC algorithms via a single unified API.

HSM Client message format.

  • Which public cores are going to be secure hosts will be decided by sysconfig configurations of TIFS-MCU at compile time and user has to make sure that similar configurations is done on the C29 side as well.
  • Below mentioned is the Message structure defined by SIPC Notify driver. HSM client populates a SIPC message with relevant parameters and sends this message to HSM Server.

SIPC message structure

Message structure description.

  • DestClientID -: Client Id to which a message is going to be sent. In case of C29 -> HSM ( C29 send message to HSM ) this field will always be equal to 1 because TIFS-MCU is a NORTOS application and only one client is required.
  • SrcClientID -: Client Id from which a message is going to be sent. In case of HSM -> C29( HSM send message to C29 ) this field will always be equal to 1.
  • flags -: Used for ACK and NACK response signals based on weather a request has been processed correctly or not.
    • Client side signals 1. AOP -> ACK on process 2. NOP -> No ACK on process
    • Server side signals 1. ACK -> request processed successfully 2. NACK -> request process failure.
  • Service_type -: Type of a requested service.
  • Pointer_to_args -: Pointer to the arguments required by a particular service.
  • CRC16(args) -: CRC16 to check the integrity of arguments.
  • CRC16(msg) -: CRC16 to check the integrity of message.
  • The argument will reside in LDAx and only its pointer is going to be passed in the message itself. When HSM receive the message it reads the argument content from LDAx RAM and process it. Thus other information needed by HSM server can be passed along with the message through HSM MBOX.
    Note
    It is strongly suggested that user application must cleary define a boundary between secure C29 CPU and non secure C29 CPU core's LDAx RAM memory so that non secure core cannot access the parameters of HSM message.

HSM client Initialization.

  • User needs to add an instance of HSM client in Secure C29's sysconfig configuration.
  • Select the Secure_host_id for the current secure C29 core.
    Note
    Make sure that SIPC Message Queue Depth, Number of secure Hosts fields are configured same as in HSM Server's sysconfig.
    HSM Client sysconfig
  • Based on the selected configuration HsmClient_init() will be called during system_init(). HsmClient_init() will set the necessary meta data and calls SIPC_init() function.
  • Refer to sysconfig generated file ti_drivers_config.c for more details.
  • After initialization user needs to instantiate HsmClient_t and use HsmClient_register() to register a client with a unique client Id.
  • There can be at max 2 distinct registered clients at a time. If user tries to register any more clients HsmClient_register() api will return Failure.
  • The idea here is that every C29 Core has to register a unique client Id to request services from HSM Server.
  • Note
    If user is not using sysconfig then it is important to call HsmClient_init() with appropriate SIPC_Params before any service function calls.

HSM Client generic service flow.

  • Below mentioned are the generic steps that every service request made by HSM client follows except HSM_MSG_BOOT_NOTIFY

HSM Client generic service flow
  • First instantiate HsmClient_t and register this client object using HsmClient_register().
  • populate ReqMsg field of HsmClient_t with appropriate paramters.
    • ReqMsg → destClientId = 0
    • ReqMsg → srcClientId = current client ID.
    • ReqMsg → serType = supported service MACRO.
    • ReqMsg → flags = AOP if ack is expected otherwise NAOP
    • ReqMsg → args = pointer to message structure based on service type.
    • ReqMsg → crcArgs = crc of args which is in OCRAM
    • ReqMsg → crcMsg = crc of the ReqMsg without crcMsg field.
  • Use SIPC_sendMsg() Api to send the 13 byte message to HSM.
  • If HSM_FLAG_AOP flag is selected then pend on HsmClient_t::Semaphore till timeout exception occurs or a Response message is received. If HSM_FLAG_NAOP flag is passed then server will not respond with message.
  • HsmClient_isr() will receive the response message and copy the same in to HsmClient_t::RespMsg and post the semaphore. As this ISR is blocking we want to quickly read the message and exit it.
  • check RespMsg integrity i.e CRC16 for HSM message and CRC16 for args. if integrity check fails then return SystemP_FAILURE.
  • If HSM_FLAG_ACK is received then returns SystemP_SUCCESS else SystemP_FAILURE.

HSM Client Load TIFS-MCU API and BootNotify message.

  • HSM client Module is used by Flash Kernel to program TIFS-MCU Fiwmware on HSM core.
  • C29 Application instantiates HSM client Module via sysconfig and calls HsmClient_loadHSMRtFirmware() which will load the TIFS-MCU Firmware.
  • After loading TIFS-MCU Firmware C29 Application application will wait for a HSM_MSG_BOOT_NOTIFY message from HSM server. This messages indicates that TIFS-MCU load is successfull and HSM Server is now ready to take requests from Secure C29 cores.
  • SBL will call HsmClient_waitForBootNotify() API which waits till it receives BootNotify message.
  • Similarly on the HSM side once the TIFS-MCU initialization sequence completes it calls HsmServer_sendBootNotify() API to send a BootNotify message.
  • Boot Notify sequence Flow chart.

Boot Notify sequence Flow chart
  • HsmClient_waitForBootNotify() API takes two parameters one of them is timeToWaitInTicks, This parameter defines how long SBL will wait for HSM_MSG_BOOT_NOTIFY message .User can change this parameter in SBL source code as per need.
    Note
    Currently the HsmClient_waitForBootNotify()'s timeToWaitInTicks paramter is set to SystemP_WAIT_FOREVER i.e C29 application will keep waiting for HSM_MSG_BOOT_NOTIFY message indefinitely.
  • refer BOOTFLOW_GUIDE for more information on SBL(Secondary Boot loader)

HSM Client GetVersion Service.

  • This service is used to get the current version of TIFS-MCU Firmware running on HSM core.
  • User needs to instantiate HsmVer_t object and call HsmClient_getVersion() API to get the current TIFS-MCU's version.
  • Refer to HsmVer_t_ for the description of different fields that defines a unique TIFS-MCU Firmware version. If User needs to know just the unique 64 bit version ID then, user should read HsmVer_t_::HsmrtVer a 64 bit field which combines all the different fields of HsmVer_t_.
  • HsmClient_getVersion() API takes timeToWaitInTicks parameter as input which dictates how long application will wait for the response from HSM core. If the timeout exception occurs HsmClient_getVersion() API return SystemP_TIMEOUT.

Example Usage

  • Please refer to examples provided in TIFS-MCU package.

Get Version

HSM Client GetUID Service.

  • This service is available HS-SE devices.
  • This service is used to get UID or Unique ID of the device running TIFS_MCU Firmware.
  • UID is a 64 byte unique ID for a device which user needs to instantiate as an uint8_t * object and call HsmClient_getUID() API to get the device UID.

Example Usage

  • Please refer to examples provided in TIFS-MCU package.

Get UID

Get Device Config Service.

  • This service is available HS-SE devices.
  • This service is used to get Device Configuration set during the boot/run time of the device.
  • There are different categories of configuration that includes "Safety", "Security" and "Debug" config which user needs to instantiate as an DeviceConfigRead_t * object and call HsmClient_getDeviceConfig() API to get the device configurations.

Example Usage

  • Please refer to examples provided in TIFS-MCU package.

Get Device Configuration

HSM Client Open Debug Firewall Service.

  • This service is available on HS-SE devices.
  • The service issued to HSM Server verifies the certificate and by default the hsm flag is set to HSM_FLAG_AOP for this service.
  • Create certificate with full enable or public enable by using scritpts, send certificate via xmodem. Call HsmClient_openDbgFirewall() Api to use debug Services.

Debug authentication

HSM Client Get Derived KEK Service.

  • This service is available on HS-SE devices.
  • The service issued to HSM Server retrieves the derived KEK based on identifier as param.
  • User needs to instantiate DKEK_t object and call HsmClient_getDKEK() API to get KEK.

DKEK service

HSM Client Key Writer Service.

  • This service is available on HS-FS devices.
  • The service issued to HSM Server to transition device from HSFS to HSSE.
  • User needs to instantiate certificate and call HsmClient_keyWriter() API to convert device from HSFS to HSKP.

HSM Client Get Random Number Service.

  • This service is used to generate random number.
  • User needs to instantiate RNGReq_t object and populate resultLengthPtr, give inputs for DRBG Mode. Along with this the user needs to give seedValue and seedSize in words when DRBG Mode is enabled.
  • Once the request is processed, HSM populates resultPtr. Depending on the inputs given by the user the desired length the resultPtr stores the random number For example if a getRandomNum request is sent without DRBG Mode and desired length as 32 then the resultPtr stores eight 4 bytes random number without seedValue and seedSize inputs. However there are certain checks over the inputs given by the user for example the desired length should be less than equal to 128 and should be a multiple of 16. The seedSize should be less than or equal to 12 and right inputs for enabling and disabling should be given.
  • The status of HsmClient_getRandomNum will return SystemP_SUCCESS only when all parameters requested were configured by HSM.
  • Example getRandomNum output
    Demo Get Random Number log

HSM Client Firmware Update Certificate Process Service.

Note
Please note that this service is only valid for F29H85x

HSM Client Firmware Update Code Program Service.

Note
Please note that this service is only valid for F29H85x

HSM Client Firmware Update Code Verify Service.

Note
Please note that this service is only valid for F29H85x

HSM Client Verify RoT Switching Certificate

  • This service is available on HS_SE devices.
  • The service issued to HSM Server to validate the RoT Switching Certificate. Once the certificate is validated, the RoT will switch to backup keys temporily (current power cycle).
  • This then can be used to authenticate images against backup keys.
  • To permanently switch to backup keys, the HsmClient_UpdateKeyRevsion() API is invoked

HSM Client Update Key Revision

  • For F29H85x devices it is recommended to update the firmware and SECCFG (mandatory) with backup keys before issuing this command. For more information, refer to TIFS-MCU documentation.
  • This service is available on HS_SE devices.
  • This service is responsible for switching the RoT to backup keys permanently.

HSM Client Read OTP Row Service.

  • This service is available on HS-SE devices.
  • The service issued to HSM Server retrieves the data of Extended OTP row based on row index provided as param.
  • User needs to instantiate NvmOtpRead_t object and call HsmClient_readOTPRow() API to get the data of Extended OTP row.

HSM Client Write OTP Row Service.

  • This service is available on HS-SE devices.
  • The service issued to HSM Server writes the data to Extended OTP efuse row based on row index provided as param.
  • User needs to instantiate NvmOtpRowWrite_t object and call HsmClient_writeOTPRow() API to writes the data to Extended OTP row.

HSM Client Get OTP Row Count Service.

  • This service is available on HS-SE devices.
  • The service issued to HSM Server retrieves the count of Extended OTP rows.
  • User needs to instantiate NvmOtpRowCount_t object and call HsmClient_getOTPRowCount() API to to get the Extended OTP rows.

HSM Client Read SW Revision Service.

  • This service is available on HS-SE devices.
  • The service issued to HSM Server retrieves the Software Revision value based on the revision identifier.
    Component Revision Identifier Value
    SWREV SBL 0x33
    SWREV HSM 0x55
    SWREV APP 0xAA
    SWREV SECCFG 0xFF
  • User needs to instantiate SWRev_t object and call HsmClient_readSWRev() API to read SW revision.

HSM Client Write SW Revision Service.

  • This service is available on HS-SE devices.
  • The service issued to HSM Server is responsible for updating the software revision of HSM, SBL, SECCFG and Application.
  • User needs to instantiate SWRev_t object and call HsmClient_writeSWRev() API to write SW revision.
  • The SW revision change is a permanent change in the NVM OTP. Any revision less than the programmed revision will not be allowed to boot. Make sure the SECCCFG programmed should have the SW Revision greater than the programmed revision.
  • For F29H85x devices it is recommended to update the firmware and SECCFG (mandatory) with the greater SW revision before issuing this command. For more information, refer to TIFS-MCU documentation.

HSM Client Proc Auth Boot Service.

  • This service is available on HS-SE devices.
  • The service issued to HSM Server is responsible for authenticating application binaries for C29 CPU1, C29 CPU2, C29 CPU3 and HSM CPU.
  • The customer root of trust keys can be used for this purpose.
  • Once the request is processed, HSM responds with an ACK or NACK depending on whether or not the application binary authentication was successful.
  • The service will also unhalt C29 CPU2 (if not in lockstep), as well as C29 CPU3 upon successful authentication of the application binaries (if C29 CPU2 and C29 CPU3 are halted at run time by HSM firware) provided the SSU configurations have benn validated successfuly as well.
  • The service should ideally be called after HsmClient_secCfgValidate in case application binaries for C29 CPU2 or C29 CPU3 are to be validated and C29 CPU2 (in split mode) and C29 CPU3 are halted at init time by HSM runtime firmware.
  • The status of HsmClient_procAuthBoot() will return SystemP_SUCCESS only when the application binary is validated by HSM, else it will return SystemP_FAILURE.

HSM Client Sec-Cfg validation Service.

  • This service is available on HS-SE devices.
  • The service issued to HSM Server is responsible for authenticating SSU configurations for C29 CPU1, C29 CPU2 and C29 CPU3.
  • The customer root of trust keys can be used for this purpose.
  • The service can be used to either validate the SSU configurations programmed in flash or new secure configurations stored elsewhere.
  • Once the request is processed, HSM responds with an ACK or NACK depending on whether or not the SSU configuration binary authentication was successful.
  • The status of HsmClient_secCfgValidate() will return SystemP_SUCCESS only when the SSU configuration binary is validated by HSM, else it will return SystemP_FAILURE.

HSM Client Active to dormant bank copy Service.

  • This service is available on HS-SE devices.
  • The service issued to HSM Server is responsible for copying the contents of the active flash bank to the dormant flash bank for C29 CPU1, C29 CPU3 and HSM CPU.
  • This service should ideally be called on the next reset after a firmware update when the new firmware is executing to ensure that both the active as well the dormant flash banks contain the same firmware images.
  • This service should only be invoked in BANKMODE1 or BANKMODE3 for C29 CPU's, else HSM will decline this service.
  • This service can be invoked in any BANKMODE for HSM CPU.
  • The status of HsmClient_activeToDormantBankCopy() will return SystemP_SUCCESS only when the contents of the active flash bank are copies to the dormant flash bank, else it will return SystemP_FAILURE.

HSM Client Crypto Service - MAC service.

  • This service is available on HS-SE devices.
  • The service issued to HSM Server computes or verifies a Message Authentication Code (MAC) using a symmetric key from the HSM keyring. Supported algorithms are AES-CMAC (16-byte tag), HMAC-SHA256 (32-byte tag), HMAC-SHA512 (64-byte tag), and GMAC (16-byte tag, requires a 12-byte IV).
  • User needs to instantiate a CryptoServiceReq_t object, set algoId to the desired algorithm (HSM_CRYPTO_SVC_MAC_CMAC, HSM_CRYPTO_SVC_MAC_HMAC, or HSM_CRYPTO_SVC_MAC_GMAC), set subSvcId to HSM_CRYPTO_SVC_MAC_GENERATE or HSM_CRYPTO_SVC_MAC_VERIFY, set keyId to the keyring index, and point ptrArgs at the corresponding args struct (CMACArgs_t, HMACArgs_t, or GMACArgs_t). Then call HsmClient_CryptoService().
  • On a generate request, HSM writes the computed tag to ptrTag on ACK. On a verify request, HSM computes the tag internally and compares it against the caller-supplied ptrTag, returning ACK on match and NACK on mismatch.

HSM Client Sec-Cfg Update Service.

  • This service is available on HS-SE devices.
  • The service issued to HSM Server is responsible for parsing the certificate in order to validate the authenticity of the Sec-Cfg, populate address where the incoming sec-cfg is to be programmed, perform integrity check on the encrypted firmware, de-crypt firmware, perform integrity check on the decrypted firmware, program sec-cfg at the appropriate location in flash memory and program the sec-cfg certificate in the appropriate location.
  • This service is expected to be called only once to update all 3 Sec-Cfg's for F29H85x. The service will update Sec-Cfg for all 3 CPUs, hence the Sec-Cfg image should be of 12 KB containing configurations for all 3 CPUs.
  • This service supports Sec-Cfg provisioning of C29 CPU1, CPU2 and CPU3 in peripheral boot mode in all BANKMODES.
  • This service supportsSec-Cfg updates of C29 CPU1, CPU2 and CPU3 in flash boot mode in all BANKMODES.
  • This service can be invoked in any BANKMODE.
  • The status of HsmClient_SecCfgUpdate() will return SystemP_SUCCESS when Sec-Cfg programming is successful, else it will return SystemP_FAILURE.

HSM Client Run Time Bank Swap Service.

  • This service is available on HS-SE devices. This service is used for swapping C29 flash banks at run time without decrementing counter in flash and restarting the device.
  • The service issued to HSM Server and is responsible swapping C29 flash banks at run time without restarting the device.
  • This service is expected to be called during secure live firmware updates and fallback mechanisms to boot previous flash images in case of flash bank failures.
  • This service is valid for C29 CPU1 in BANKMODE1 and BANKMODE3 only.
  • This service is valid for C29 CPU3 in BANKMODE3 only.
  • The status of HsmClient_runTimeBankSwap() will return SystemP_SUCCESS when the request made to HSM is valid and HSM is ready to swap flash banks, else it will return SystemP_FAILURE.

APIs for HSMCLIENT