1. Introduction

Scope

This application note describes the addition of the Cryptographic service Load Key Slot, it will go through the integration and configuration of BSW Components(Csm, CryIf and Crypto)

required for this service.

Definitions and Abbreviations

Csm: AUTOSAR Basic Software Module Crypto Service Manage

CryIf: AUTOSAR Basic Software Module Crypto Interface

Crypto: Crypto Driver

Hsm: Hardware Security Module

SHE: Security Hardware Extension

Toolchain

It is assumed you are using the RTA-CAR 8.0.1 toolchain:

2. Prerequisites

In order to successfully follow this guide, you must have the RTA-CAR toolchain installed and you must be familiar with the AUTOSAR specifications, terminology and methodology.

It is recommended that Crypto Stack configuration is added to an existing project, with ASW and a System Configuration.

Hint: The AUTOSAR explanatory AUTOSAR_EXP_UtilizationOfCryptoServices.pdf can be used as a starting point to learn about the Crypto Stack.

3. Add the Crypto BSW Components to BSW Modules

Csm

• In the ECU Navigator, right click on Bsw Modules and select Create Service → Create Csm

• In "New AR Element Creation" popup(see next image), put the name of the module in the Csm field
• Select Create New AR Package
• Put the file name as Csm_EcucValues.arxml

• In CsmGeneral Container set the parameter CsmMainFunctionPeriod to the value needed, 0.01 in our case
• Set "CsmRbAutoFillConfig" to "True" as it will enable the Csm generator to automatically fill missing configuration parameters and connection in CryIf and Crypto components.

CryIf

• Right click on Bsw Modules/Other Modules
• Select Create CryIf

• Fill the "New AR element creation" similar to what we have done for Csm

Crypto Driver

• Right click on Bsw Modules/Other Modules

• Select Create Crypto

• In "New AR Element Creation" popup(see next image), put the name rba_CryptoHSM
• select Create New AR Package
• put the file name as rba_CryptoHSM_EcucValues.arxml

• Open rba_CryptoHSM by double clicking on it.
• In "CryptoGeneral" keep the default values, they will work for our use case, we will only need to configure the parameter CryptoMainFunctionPeriod to 0.01(100ms).

3. Configure Load Key Slot Service in the Crypto BSW Components

• First we need to create a Csm Primitive, primitives are linked to the Crypto Driver that will execute them, in our use case we are using the HSM and accordingly we shall set the parameter CsmRbAutoConfigCryptoSelect to rba_CryptoHSM.

• Right click on the newly created container CsmPrimitives, select New Child → CsmRbSheLoadKeySlot

• Create a call back to be used by CryptoHSM when operation is completed

• Create Csm Queue, no need to set the parameter "CsmChannelRef" as it will be automatically set during the RTA-BSW CodeGen phase. Set "CsmQueuesize" to 1.

• Create Csm Job by updating the filed that appear once you select CsmJob container

• Name the Job She_Key_Load
• Set CsmJobInterfaceUsePort to CRYPTO_USE_PORT_OPTIMIZED
• Set CsmJobPrimitiveCallbackUpdateNotification to false
• Set CsmJobPriority to 0
• set CsmProcessingMode to CRYPTO_PROCESSING_ASYNC
• set CsmRbJobRteQLength to 1
• In the references select the callback, primitive and queue created in the previous steps

• Now we will need to do RTA-BSW CodeGen for Csm, CryIf and rba_CryptoHSM, note that any needed configuration in CryIf and rba_CryptoHSM will be carried forward from Csm in the CodeGen process, there is no need to do them yourself.

After a successful CodeGen the files in the following document are generated:

file_list.txt

Let's check the service ports available in Csm component

• first right click on the project's root node and select refresh
• Open AR Explorer and expand the node Component → Csm

you shall find one P Port and one R Port

4. BswM Configuration for Crypto Stack Initialization

• For adding and creating Actions in BswM see the workflow, we will add 4 Action items of the type BswMUserCallout.

• Each action will have one of the following APIs

Csm_Init()

CryIf_Init()

CsaiHSM_Startup()

rba_CryptoHSM_Init()

• See below image as an example of CsmInit Action

• The Actions will be mapped to the Action List "BswM_AL_BswModules_InitListReadAll" which is triggered after NvM_ReadAll is done.

• Under BswMGeneral/BswMUserIncludeFiles add the header files for the APIs(Csm.h,CryIf.h and rba_CryptoHSM.h)

• Now Run Code Generate for RTA-BSW making sure that BswM is selected.

5. Create an Os Counter

The CycurHSM requires a counter for its own measurements, we will create one through the OS

In ECU Navigator, select BSW Modules/Rte Os/Os and in the Bsw Editor select OsCounters and add a new counter

• We will name it "Os_Csai_Counter"
• Set OsCounterMaxAllowedValue to 65535
• Set OsCounterMinCycle to 1
• Set OsCounterTicksPerBase to 1
• Set OsCounterType to SOFTWARE
• Set OsSecondsPerTick to 0.001

6. Composition, EcuExtract and RTE Instances Configuration

• Add Csm Prototype to the TopLevelComposition

• Open SWC to ECU Mapping Editor to assign the Csm component to your ECU

• Drag CPT_Csm from the right side and drop it on the required ECU Instance on the the left

•  Create an ECU Extract to reflect the change

• Since we are integrating to an already established project we are not creating a new extract, we are just updating it.

• Completion dialog

• Go to ECU Navigator, select Bsw Modules → RTE OS → RTE
• Right click on "RteBswModuleInstances"

• In "RteBswImplementationRef" select Csm.

• Do the same steps to add RteBswModuleInstance for rba_CryptoHSM.

7. Map Csm and rba_CryptoHSM events to tasks

• Double click EcucValueCollection then select Entity to Task Mapping

• Drag the Unmapped Entities for Csm and rba_CryptoHSM and drop them on your BSW Task

• Before RTE Generation we need to define a SwAddressing Method

• In the "New AR Element Creation" put "HSM_SHARED_VAR" in the field "SwAddrMethods"

• Select "Use Existing AR Packages"  then select the "SwAddrMethods" node under "rba_CUCELSwAddrMethod_BSWMD.arxml" and click Finish.

• Double click on the newly created element.
• Set ShortName to HSM_SHARED_VAR.
• Set MemoryAllocationKeywordPolicy to ADDR-METHOD-SHORT-NAME-AND-ALIGNMENT.
• Set SectionInitializationPolicy to INIT.
• Set SectionType to VAR.

• In the RTA Code Genereator select RTA-RTE, and in the tab "Include AR Files"
• Select BSWMD files for Csm and rba_CryptoHSM
• Select SWCD file for Csm
• Select EcucValues files for Csm, CryIf and rba_CryptoHSM
• Then Select Run

8. CycurHSM Integration

Description

We are using CycurHSM_TC27x_V2.7.1.r1. CycurHSM is the HSM Firmware and the Host Drivers. Host Drivers enables communication between our AUTOSAR SW and the HSM Firmware.

HSM Firmware is a binary file that we will flash on our target's HSM, the Host Drivers shall be integrated to our SW to enable the communication with the HSM.

Host Drivers

• Make sure that the files in are included in the build environment
• The folders containing the Host Drivers are "\Implementation\HSM_HOST_Drivers\ecy_hsm" and "\20_Implementation\HSM_HOST_Drivers\ecy_hsm_TC27x_HT"
• For correct memory sections evaluation in the file \Implementation\HSM_HOST_Drivers\ecy_hsm_TC27x_HT\api\rba_Reg_attrb.h we shall add the definition "#define _HIGHTEC_C_IFXHSMHIGH_" in the file  \Implementation\RTA-SK\src\bsw\Compiler\integration\Compiler_Cfg.h.

Flashing HSM

• The HSM binary is in the path \Implementation\HSM_HOST_Drivers\hsm_bin with the name HSM_sig.hex.

• In the path \Implementation\HSM_HOST_Drivers\hsm_t32_flash_script the file Tc27x-hsm.cmm shall be used to flash the HSM.

Linker File Update

• We will need to update the linker file to assign the sections .hsm_shared and .hsm_shared_ro to CPU0_DMI_DSPR, these sections are used by the Host Driver's MemMap to allocate variables in CPU0_DMI_DSPR.
• Define BRIDGE as this identifier used by the Host Drivers implementation →  "BRIDGE = 0xF0040008;"
• This is already handled in the Starter Kit's linker file \Implementation\Build\linkscript_HighTec.ld.

MCAL Stub File

• We will use the Gpt_Cbk_Notification in the file \Implementation\MCAL\Integration\Stubs.c to increment the Os Counter "Os_Csai_Counter" that we created earlier.
• The Os Counter is needed to provide time measurements that required by the HSM. The measurements are taken using the APIs Callout_GetCounterValue() and Callout_GetElapsedCounterValue(), both APIs are provided to the Host Driver in it s configuration
• The API CsaiHSM_Startup() contains the sequence required to check that HSM is up and running in the APP mode and configure the communication with HSM via the Host Driver.