AM263Px MCU+ SDK: Security

| AM263Px MCU+ SDK 26.00.00 |

Security

# Introduction

## Getting started

The HSM or Hardware security Module is a subsystem that acts as the secure host by offering security services to the rest of the system. TI offers HS-FS (High Security - Field Securable) as the primary device for the customers. The MCU+ SDK supports HS-FS device type for AM263x/AM263Px. It supports loading the HSM firmware (TIFS-MCU) via SBL (Secondary Boot Loader), which enables access to the hardware resources for cryptographic operations for R5FSS.

### Bootloader_socLoadHsmRtFw

The SBL for AM263x/AM263Px/AM273x/AM261x supports for loading firmware on the HSM. The firmware is provided in an encrypted form at `source/security/security_common/drivers/hsmclient/soc/am263x/hsmRtImg.h`. The function `Bootloader_socLoadHsmRtFw` sends a message to ROM and ROM loads the HSM firmware. After the HSM firmware is loaded and has done its init time operations, it sends a message to the SBL called `HSM_MSG_BOOT_NOTIFY`.

int main()
{
...
Drivers_open();
Bootloader_profileAddProfilePoint("Drivers_open");
DebugP_log("\r\n");
Bootloader_socLoadHsmRtFw(gHsmRtFw, HSMRT_IMG_SIZE_IN_BYTES);
Bootloader_profileAddProfilePoint("LoadHsmRtFw");
DebugP_log("Starting QSPI Bootloader ... \r\n");
...
}

#### HSMRt Firewall Configurations

HSMRt does the following firewall configurations. These configurations gives necessary access of various memory regions to host cores.

Note
  Following configurations are done considering R5FSS0_0 as secure host 0 and R5FSS0_1 as secure host 1.

Firewall/MPU | Programmable Region Num. | Start Address | End Address | AID/privID permissions | SR | SW | SX | UR | UW | UX | NS | Debug | Comments
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
FW HSM_SLV | 0 | 0x44000400 | 0x44000800 | HSM, R5FSS0_0, R5FSS0_1 | 1 | 1 | 0 | 1 | 1 | 0 | 1 | 1 | HSM MBOX region R5->HSM queues
| 1 | 0x44000000 | 0x44000400 | R5FSS0_0, R5FSS0_1 | 1 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | HSM MBOX region HSM->R5 queues
| 2 | 0x40020000 | 0x4011FFFF | R5FSS0_0, R5FSS0_1, R5FSS1_0, R5FSS1_1 | 1 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | MPU Region Space
| 3 | 0x40140000 | 0x4023FFFF | R5FSS0_0, R5FSS0_1, R5FSS1_0, R5FSS1_1 | 1 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | MPU Region Space
| 4 | 0x40260000 | 0x402E03FF | R5FSS0_0, R5FSS0_1, R5FSS1_0, R5FSS1_1 | 1 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | MPU Region Space
FW DTHE_SLV | 0 | 0xCE007000 | 0xCE0073FF | All AIDs can access | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | HSM AES (public context)
| 1 | 0xCE005000 | 0xCE0053FF | All AIDs can acces | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | HSM SHA (public context)
| 2 | 0xCE000000 | 0xCEFFFFFF | HSM | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | HSM DTHE and Crpyto
| 3 | 0xCE000800 | 0xCE000FFF | All AIDs can acces | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | HSM DTHE and Crpyto
FW SCRM2SCRP0 | 0 | 0x50000000 | 0x60000000 | All AIDs can access | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | To access peripheral region master side MPU
| 1 | 0x53600000 | 0x53600400 | All AIDs access revoked except HSM | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | Secure Asset and is protected during runtime
FW SCRM2SCRP1 | 0 | 0x50000000 | 0x60000000 | All AIDs can access | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | To access peripheral region master side MPU
| 1 | 0x53600000 | 0x53600400 | All AIDs access revoked except HSM | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | Secure Asset and is protected during runtime
FW R5SS0_CORE0_AHB_MST | 0 | 0x50000000 | 0x60000000 | All AIDs can access | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | To access peripheral region master side MPU
| 1 | 0x53600000 | 0x53600400 | All AIDs access revoked except HSM | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | Secure Asset and is protected during runtime
FW R5SS0_CORE1_AHB_MST | 0 | 0x50000000 | 0x60000000 | All AIDs can access | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | To access peripheral region master side MPU
| 1 | 0x53600000 | 0x53600400 | All AIDs access revoked except HSM | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | Secure Asset and is protected during runtime
FW R5SS1_CORE0_AHB_MST | 0 | 0x50000000 | 0x60000000 | All AIDs can access | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | To access peripheral region master side MPU
| 1 | 0x53600000 | 0x53600400 | All AIDs access revoked except HSM | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | Secure Asset and is protected during runtime
FW R5SS1_CORE1_AHB_MST | 0 | 0x50000000 | 0x60000000 | All AIDs can access | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | To access peripheral region master side MPU
| 1 | 0x53600000 | 0x53600400 | All AIDs access revoked except HSM | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | Secure Asset and is protected during runtime
FW OSPI0_CFG_SLV | 0 | 0x53800000 | 0x53810000 | All AIDs can access | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | To access peripheral region master side MPU
| 1 | 0x53802000 | 0x53802300 | All AIDs access revoked except HSM | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | Secure Asset and is protected during runtime

#### Default Region Configuration for HSM Memory Validation

The HSM firmware validates memory addresses passed in service requests against pre-configured safe memory regions. The following tables show the default memory regions configured for each device and firmware type.

AM263Px Default Memory Regions

HSFS Firmware

Region Name | Start Address | End Address | Permissions
--- | --- | --- | ---
OC_RAM | 0x70000000 | 0x70300000 | R/W
TCMA | 0x78000000 | 0x78010000 | R/W
TCMB | 0x78100000 | 0x78130000 | R/W

### Resources available

By default, the access to the crypto resources are firewalled on HS-FS devices. The HSM firmware so loaded, bypasses the firewalls and makes the following crypto modules available for the R5FSS to use.

- AES (public context)
- SHA (public context)

This provides ability for the R5F core to be able to do the following computations:

- AES encryption/decryption
- SHA/HMAC hash calculation

SBL should always wait for `HSM_MSG_BOOT_NOTIFY` before using the crypto accelerator because HSM firmware initializes these firewalls. Failing to do so, the SBL or application may run into abort exception while accessing the MMR regions for the crypto accelerator.

### Services

The TIFS-MCU firmware that gets loaded on HSM provides the variety of services. For more information refer HSM client

### Modules

This page links to the HSM client used to access HSM services.

- HSM client

This page links to sub modules that enable authentication, data integrity and its confidentiality with the on-chip hardware accelarators.

The cryptographic accelarator on this device is supported via these modules in the SDK:

- Cryptography Modules
  - DTHE (Data Transform and Hashing Engine)
    - Description of DTHE architecture and APIs available to use AES and SHA engine.

Note
  EDMA support for AES and SHA will be added in future releases. Currently, the drivers only operate in CPU mode of data copy.