HSM client

Table of Contents

• Introduction
• HSM Client message format.
  • Message structure description.
• HSM client Initialization.
• HSM Client generic service flow.
• HSM Client Load TIFS-MCU API and BootNotify message.
• HSM Client GetVersion Service.
  • Example Usage
• HSM Client GetUID Service.
  • Example Usage
• HSM Client SetFirewall Service.
• HSM Client Set Firewall Interrupt Service.
• HSM Client Open Debug Firewall Service.
• HSM Client Read OTP Row Service.
• HSM Client Write OTP Row Service.
• HSM Client Lock OTP Row Service.
• HSM Client Get OTP Row Count Service.
• HSM Client Get OTP Row Protection Service.
• HSM Client Proc Auth Boot Service.
• HSM Client Read SW Revision Service.
• HSM Client Write SW Revision Service.
• HSM Client Get Derived KEK Service.
• HSM Client Key Writer Service.
• HSM Client Get Random Number Service.
• HSM Client Import Keyring Service.
• APIs

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 decrypting and authenticating R5Fs application images and sends a notification to SBL if it is a valid app image , later SBL will boot the R5 applications to respective cores.
• The trusted R5Fs cores which can communicate with HSM are known as Secure hosts.

Note

For HS-SE device specific services, please contact your TI representative to get access to TIFS-MCU add-on package.

• Following services are supported in MCU+SDK v9.1.0
  • BootNotify Service -: A special message sent by TIFS-MCU Firmware to indicate SBL that TIFS-MCU boot was successful.
  • GetVersion Service -: Get The current version of TIFS-MCU Firmware.
  • GetUID Service -: Get the unique ID of the device.
  • Debug Service -: For HS-SE device only. By default debug port for all R5F and HSM is closed. Secure R5Fs can request debug port access via runtime Debug services.
  • Firewall Service -: Configures the MPU firewall configuration.
  • Set Firewall Interrupt Service -: Configures the MPU firewall interrupt.
  • Read OTP Row Data Service -: For HS-SE device only. Get the data from Extended OTP row.
  • Write OTP Row Data Service -: For HS-SE device only. Write the data to Extended OTP row.
  • Lock OTP Row Service -: For HS-SE device only. Lock the Extended OTP row.
  • Get OTP Row Count Service -: For HS-SE device only. Get the count from Extended OTP row.
  • Get OTP Row Protection Service -: For HS-SE device only. Get the row protection info from Extended OTP row.
  • Proc Auth Boot Service -: For HS-SE device only. Perform secure boot checks for application images.
  • Read SW Revision Service -: For HS-SE device only. Get the software revision for SBL, HSM, Application.
  • Write SW Revision Service -: For HS-SE device only. write the software revision for SBL, HSM, Application.
  • Get DKEK Service -: For HS-SE device only. Get Derived KEK.
  • Get Random Number Service -: Get the random number as generated by TRNG engine.
  • Import Keyring Service -: For HS-SE device only. Import keyring in TIFS-MCU.
  • Key Writer Service -: For converting device from HSFS to HSSE.

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 R5F 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 R5F -> HSM ( R5 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 -> R5F( HSM send message to R5 ) 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 OCRAM and only its pointer is going to be passed in the message itself. When HSM receive the message it reads the argument content from OCRAM 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 R5FSS and non secure R5FSS core's OCRAM memory so that non secure core cannot access the parameters of HSM message. One way to define such boundary is to protect some predefined memory region in OCRAM with firewalls so that only secure cores can access this particular memory region.

HSM client Initialization.

• User needs to add an instance of HSM client in Secure R5F's sysconfig configuration.
• Select the Secure_host_id for the current secure R5F 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 32 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 RTOS task 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 SBL to load TIFS-MCU Fiwmware on HSM core.
• SBL includes hsmRtImg.h file which contains TIFS-MCU Firmware in byte format, next the TIFS-MCU will be built along with SBL application.
• SBL instantiates HSM client Module via sysconfig and calls HsmClient_loadHSMRtFirmware() which will load the TIFS-MCU Firmware.
• After loading TIFS-MCU Firmware SBL 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 R5F 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 SBL will keep waiting for HSM_MSG_BOOT_NOTIFY message indefinitely.

• refer Understanding the bootflow and bootloaders 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

• Demo code for HsmClient_init(). This will be autogenerated by sysconfig.

/*
 * HSM Client
 */
 
/* memory assigned for each R5x <-> HSM channel */
uint8_t gQueue_R5ToHsm[SIPC_NUM_R5_CORES][SIPC_QUEUE_LENGTH*SIPC_MSG_SIZE] __attribute__((aligned(8),section(".bss.sipc_hsm_queue_mem")));
uint8_t gQueue_HsmToR5[SIPC_NUM_R5_CORES][SIPC_QUEUE_LENGTH*SIPC_MSG_SIZE] __attribute__((aligned(8),section(".bss.sipc_r5f_queue_mem")));
 
void HsmClient_config(void)
{
    SIPC_Params sipcParams;
    int32_t status;
 
    /* initialize parameters to default */
    SIPC_Params_init(&sipcParams);
 
    sipcParams.ipcQueue_eleSize_inBytes = SIPC_MSG_SIZE;
    sipcParams.ipcQueue_length = SIPC_QUEUE_LENGTH ;
    /* list the cores that will do SIPC communication with this core
    * Make sure to NOT list 'self' core in the list below
    */
    sipcParams.numCores = 1;
    sipcParams.coreIdList[0] = CORE_INDEX_HSM;
 
    /* This is HSM -> R5F queue */
    sipcParams.tx_SipcQueues[CORE_INDEX_HSM] = (uintptr_t)gQueue_HsmToR5[0] ;
    sipcParams.rx_SipcQueues[CORE_INDEX_HSM] = (uintptr_t)gQueue_R5ToHsm[0] ;
    sipcParams.secHostCoreId[CORE_INDEX_SEC_MASTER_0] = CORE_ID_R5FSS0_0;
 
    /* initialize the HsmClient module */
    status = HsmClient_init(&sipcParams);
    DebugP_assert(status==SystemP_SUCCESS);

• Registering HsmClient_t with client ID and requesting current TIFS-MCU Version.

 
#define APP_CLIENT_ID                  (0x02)
 
/* Demo Application code on R5 */
void HsmClientApp_start(void)
{
    int32_t status ;
    HsmClient_t client ;
    HsmVer_t *hsmVer = malloc(sizeof(HsmVer_t)) ;
    uint32_t CycleCounterA = 0, CycleCounterB = 0, TotalTimeInNsec;
 
    status = HsmClient_register(&client,APP_CLIENT_ID);
    DebugP_assert(status == SystemP_SUCCESS);
 
    status = HsmClient_getVersion(&client,hsmVer,SystemP_WAIT_FOREVER);
    DebugP_assert(status == SystemP_SUCCESS);
 
    /* print version */
    DebugP_log("[HSM CLIENT] HSMRT 64bit version string = 0x00%llx",hsmVer->HsmrtVer);
    DebugP_log("\r\n[HSM_CLIENT] HSMRt Version \r\n\
                    [Device Type]   = 0x%x\r\n\
                    [Bin Type]      = 0x%x\r\n\
                    [Soc Type]      = 0x%x\r\n\
                    [Arch Num]      = 0x%x\r\n\
                    [Api Version]   = 0x%x\r\n\
                    [Major Version] = 0x%x\r\n\
                    [Minor Version] = 0x%x\r\n\
                    [Patch Version] = 0x%x\r\n",\
                    hsmVer->VerStruct.DevType,hsmVer->VerStruct.BinType,hsmVer->VerStruct.SocType,hsmVer->VerStruct.ApiVer,hsmVer->VerStruct.MajorVer,hsmVer->VerStruct.MinorVer,hsmVer->VerStruct.PatchVer);
}
 

• Example UART getVersion output.
  

  Get Version UART log

HSM Client GetUID Service.

• This service is available on both HS-FS and 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

• Registering HsmClient_t with client ID and requesting device UID.

 
#define APP_CLIENT_ID                 (0x02)
#define HSM_UID_SIZE                  (64U)
 
/* Demo Application code on R5 */
void HsmClientApp_start(void)
{
    int32_t status ;
    HsmClient_t client ;
    uint8_t *uid = malloc(HSM_UID_SIZE) ;
 
    status = HsmClient_register(&client,APP_CLIENT_ID);
    DebugP_assert(status == SystemP_SUCCESS);
 
    /* Send Request for UID to HSM Server */
    status = HsmClient_getUID(&client, (uint8_t *)uid, SystemP_WAIT_FOREVER);
 
    /* print UID */
    DebugP_log("\r\n [HSM CLIENT] Device UID is : ");
    for(uint8_t i = 0; i<HSM_UID_SIZE; i++)
    {
        DebugP_log("%02X", uid[i]);
    }
}
 

HSM Client SetFirewall Service.

Note

For boot time firewall configuration, Please refer HSMRt Firewall Configurations

• This service is used to configure MPU firewall regions.
• User needs to instantiate FirewallReq_t object and populate regionCount and FirewallRegionArr. FirewallRegionArr is an array of mpu firewall regions(FirewallRegionReq_t) to be configured. User can configure 16 MPU firewall configurations in one request and hence the size of array can not be more than 16.
• Once the request is processed, HSM populates statusFirewallRegionArr. Each bit of statusFirewallRegionArr represents the status of each region request from FirewallRegionArr. If some region configuration request was not honoured then the corresponding bit position in statusFirewallRegionArr as returned from HSM is 0, otherwise one. For example if a setFirewall request is sent for configuring 6 mpu regions and out of which 1st and 6th region request were illegal configuration then HSM will populate the statusFirewallRegionArr with 0xFFDE (1111 1111 1101 1110).
• If status of HsmClient_setFirewall will return SystemP_SUCCESS only when all regions requested were configured by HSM.
• User can use sysconfig for generation of region configurations and can use the array directly for instantiating FirewallReq_t object.
  

  Sysconfig interface for generating region configurations
• Region to be configured should be 1KB (0x400) aligned and 1KB is the minimum granularity supported for the protected memory map targets size.
  • Start Address should be a multiple of 1KB (0x400)
  • (End Address + 1) should be a multiple of 1KB (0x400)
• Each Configurable System MPU region details , Configuration address, number of programmable regions are captured in the table below
• TOP_EFUSE_FARM is a non-configurable region and runtime firewall service request will be NACKed if the TOP_EFUSE_FARM falls in any region request.

   
  /* Demo Application code on R5 */
  void HsmClientApp_start(void)
  {
      int32_t status ;
      HsmClient_t client ;
      /* struct instance used for sending set firewall request */
      FirewallReq_t FirewallReqObj;
   
      status = HsmClient_register(&client,APP_CLIENT_ID);
      DebugP_assert(status == SystemP_SUCCESS);
   
      /* region count and region configuration array is generated via sysconfig and is used
          for populating  FirewallReqObj*/
      FirewallReqObj.regionCount = FIREWALL_ARRAY0_NUM_REGIONS;
      FirewallReqObj.FirewallRegionArr = gMpuFirewallRegionConfig_0;
   
      DebugP_log("\r\n [HSM CLIENT] Sending SET FIREWALL Request to HSM Server..");
      /* This requests configures the region and allow all permissions to only R5FSS0_0 */
      status = HsmClient_setFirewall(&client,&FirewallReqObj,SystemP_WAIT_FOREVER);
   
      /* print statusFirewallRegionArr */
      DebugP_log("\r\n [HSM CLIENT] statusFirewallRegionArr : 0x%x\r\n ", FirewallReqObj.statusFirewallRegionArr);
  }
   

• Example UART getVersion output.
  

  Demo Set Firewall UART log

HSM Client Set Firewall Interrupt Service.

• This service is available on both HSFS and HS-SE devices.
• The service issued to HSM Server is responsible for the 4 operations mentioned below:
  • Interrupt enable for protection and address violation
  • Clearing Interrupt enable.
  • Clearing Interrupt status.
  • Clearing the current fault so that another can be captured.
• User needs to instantiate FirewallIntrReq_t object and call HsmClient_FirewallIntr() API to to sets firewall interrupt.

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.

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 EfuseRead_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 EfuseRowWrite_t object and call HsmClient_writeOTPRow() API to writes the data to Extended OTP row.

HSM Client Lock OTP Row Service.

• This service is available on HS-SE devices.
• The service issued to HSM Server sets the protection status bit of the specified row to 1.
• User needs to instantiate EfuseRowProt_t object and call HsmClient_lockOTPRow() API to lock the 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 EfuseRowCount_t object and call HsmClient_getOTPRowCount() API to to get the Extended OTP rows.

HSM Client Get OTP Row Protection Service.

• This service is available on HS-SE devices.
• The service issued to HSM Server retrieves the Extended OTP efuse row protection status.
• User needs to instantiate EfuseRowProt_t object and call HsmClient_getOTPRowProtection() API to to get Extended OTP efuse row protection status.

HSM Client Proc Auth Boot Service.

• This service is available on HS-SE devices.
• The service issued to HSM Server by SBL.
• User needs to instantiate certificate and call HsmClient_procAuthBoot() API to to perform proc auth boot.

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

• 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 and Application.
• User needs to instantiate SWRev_t object and call HsmClient_writeSWRev() API to write SW revision.

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.

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

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 Import Keyring Service.

• This service is available on HS_SE devices.
• The service issued to HSM Server by SBL.
• This service is responsible for importing keyring.
• Once the request, HSM will parse the sent X.509 certificate and populate the keyring in HSM secure ram.

APIs

APIs for HSMCLIENT