# Secure RoT Resources

Certain configuration items are required for supporting the correct operation of the Secure RoT.

These are split into three broad categories, as follows:

- Configuration items held in secure NVM storage
- Certificates and other configuration items supporting secure boot
- Certificates required to support secure debug

Understanding how these items relate to each other, and what is needed at which stage of the product life cycle, is important to your implementation of the security system.

## NVM Storage

The NVM is protected by the Arm CryptoCell-312 security block; only certain parts of the NVM can be read or written at any given point in the device life cycle.

This is normally managed during device provisioning either from LCS_CM → LCS_DM, or from LCS_DM → LCS_SE.

The "Asset Storage in NVM" table describes the assets that are stored in NVM.

Table: Asset Storage in NVM
Item name | Size (bits) | Written By | Description
--- | --- | --- | ---
Hardware Unique Key (HUK) | 256 | ICV | The HUK is a unique 256-bit value calculated during device provisioning. It is never directly visible to application code or provided outside of the device, but can be used to derive other unique keys.
Kpicv | 128 | ICV | This is the ICV provisioning key, used to encrypt assets that need to be decrypted securely on the device. It is a 128-bit AES key provided by the ICV.
Kceicv | 128 | ICV | This is the ICV code encryption key. It is used to decrypt any code tha is stored encrypted and must be decrypted prior to use. This is a 128-bit AES key provided by the ICV.
ICV Flags | 32 | ICV | These are flag bits used to indicate if the ICV provisioning process has completed.
HBK0 | 128 | ICV | This is a 128-bit hash value of the public key associated with the ICV. This is used to determine the ICV Root of Trust for any key certificate provided to the system. The hash value is a 128-bit truncated SHA-256 calculation of the public key.
HBK1 | 128 | OEM | This is a 128-bit hash value of the public key associated with the OEM. This is used to determine the OEM Root of Trust for any key certificate provided to the system. The hash value is a 128-bit truncated SHA-256 calculation of the public key.
Kcp | 128 | OEM | This is the OEM provisioning key, used to encrypt assets that need to be decrypted securely on the device. It is a 128-bit AES key provided by the OEM.
Kce | 128 | OEM | This is the OEM code encryption key. It is used to decrypt any code that is stored encrypted and must be decrypted prior to use. This is a 128-bit AES key provided by the OEM.
OEM Flags | 32 | OEM | These flag bits are used to indicate if the OEM provisioning process has completed.
HBK0 Minimum Version | 64 | ICV | This contains 64 bits, which can be used to provide anti-rollback protection for the ICV RoT. This is initialized during ICV provisioning and then updated when newer firmware is loaded to the device by the ICV.
HBK1 Minimum Version | 96 | OEM | This contains 96 bits which can be used to provide anti-rollback protection for the OEM RoT. This is initialized during OEM provisioning and then updated when newer firmware is loaded to the device by the OEM.
Configuration Flags | 32 | ICV | These ICV configuration flags are set up during ICV provisioning.
DCU Lock Mask | 128 | ICV/OEM | The specific user-supplied DCU lock bits are set according to ICV or OEM provisioning. The first 64 bits are owned by the ICV. The second 64 bits are owned by the OEM.

### Additional Information

For both the ICV and OEM provisioning operations, the following items are required:

1. RSA Public/Private key pair
   - This forms the basis of the secure boot and secure debug processes.
   - The truncated SHA-256 of the public key is stored in the HBK0/1 locations in the NVM.
   - The private key is used to sign the first key certificate in the secure chain of trust.
   - This RSA key pair belongs to either the ICV or OEM, and the private key must be kept secure.
2. A 128-bit AES provisioning key
   - This is required if any secure asset provisioning is performed.
3. A 128-bit AES code encryption key
   - This is required if there is any code decrypted as part of the secure boot process.
   - If all code is unencrypted and executing from flash, this may be omitted.

The RSLSec tool, which is explained in detail in a later part of the document, can be used to generate all of these keys and hashes if required.

## Secure Provisioning

A user may need to secure the keys and hashes before loading them to the device. For instance, if a third party is performing the provisioning of the device, it is necessary to provision it without revealing the keys to the third party. In this case, the RTL key (Krtl) can be used to securely wrap the various assets before provisioning them.

This Krtl is a common key embedded in the hardware of the device and is never visible to application firmware. This is the same key in all RSL15 devices.

IMPORTANT: This key value can be provided by onsemi in an encrypted form on request.

The Krtl is only used when provisioning the devices. After provisioning, the Krtl is no longer necessary when using the device.

## Application Certificates and Configuration Items

In order to configure an application for use, it must be securely signed, and appropriate key and content certificates must be provided.

RSL15 uses a proprietary format for the certificates in the Root of Trust. These are similar in content to standard X.509 certificates, but are in a more compact form, with only the core information.

### Key Certificate Generation

A key certificate securely provides a public key hash for the next certificate in the chain. The next certificate might be another key certificate, or a content certificate describing an application; in either case, the process is the same.

To create a new key certificate, the following items are required:

1. The RSA key pair to sign the key certificate in privacy-enhanced mail (PEM) format
   - If the private key is encrypted, the password of the PEM file is also needed.
2. The public key of the next certificate in the chain of trust, again in PEM format

### Content Certificate Generation

A content certificate describes an application image. It defines the areas of program memory that must be verified and authenticated, and defines whether any of the application is encrypted and needs to be loaded to RAM prior to execution.

To create a new content certificate where the application, or part of the application, is stored unencrypted and executes from flash memory, the following items are required:

1. The RSA key pair to sign the key certificate in PEM format
   - If the private key is encrypted, the password of the PEM file is also needed.
2. The image that is executed when the content certificate has been verified and authenticated

To create a new content certificate where the application is stored encrypted in flash and needs to be decrypted into RAM for execution, the following items are required:

1. The RSA key pair to sign the key certificate in PEM format
   - If the private key is encrypted, the password of the PEM file is also needed.
2. The image that is executed when the content certificate has been verified and authenticated
3. The AES key used for performing the encryption operation, with the password if required
4. A mapping table to allow the translation of flash addresses to RAM, used when decrypting and loading the image

Execution of encrypted images in this way is possible, but less practical due to the relative flash and RAM sizes. Generally, the application is stored in plain text in flash and executed directly from there.

### Application Signing

A secure application can be thought of as having the following components:

- A configuration block which can be used to locate the various certificates associated with the RoT
- One or two key certificates which are used to authenticate the application
- A single content certificate which is used to verify and authenticate the image being loaded
- The application image itself

All of these component parts are combined into a single load module which can be stored in the flash of the device.

The configuration block holds the base addresses of each of the key and content certificates and for the purposes of RSL15 is always stored at a fixed location in flash. The certificates and application may reside anywhere in the free flash memory.

## Debug Certificates and SOC ID

In order to unlock the debug features of a device, another form of debug certificate must be presented to the ROM during system power-up.

Again, the debug certificate is verified using the RoT associated with the certificate. This makes it possible to have debug certificates with different properties provided by different owners of the RoT.

There are two forms of debug certificate used in the system, and one of each is required for enabling the debug facilities.

- Debug enabler certificate

- This certificate is specified for a distinct RoT owner, and must match the RoT owner that is specified in the first key certificate establishing the RoT.
- The debug enabler certificate is provided by the owner of the RoT and identifies the specific debug features that can be opened by a developer.
  - Debug facilities are controlled by the debug control unit (DCU), and specific bits are set in the debug mask to enable those features during debug.
  - The debug enabler certificate also allows the owner of the RoT to lock specific bits of the DCU so that they cannot be re-opened after the boot process has completed. This ensures that any items the ICV or OEM do not want to provide access to can be locked out regardless of the developer’s wishes.
  - Debug enabler certificates are also associated with a specific LCS, and they limit the effect of the certificate to devices which are that specific LCS. This allows an enable certificate to be safely issued for LCS_DM, as it cannot be used to open a secure device.
- The debug enabler certificate is also used to specify the transition to RMA for a given device.
- This is a general certificate, applying to a range of devices that have the same RoT, so a single enabler certificate can be used with multiple discrete devices.

- Debug developer certificate

- The debug developer certificate is used to open up the debug port on a specific device.
- It references an enabler certificate, and can open up DCU bits which have not been locked by the enabler certificate.
  - This allows only a subset of the features provided by the enabler certificate to be used by a developer.
  - Different enabler certificates can be provided to different developers, giving them different limitations of access.
- The debug developer certificate references a device by its SOC ID.
  - This is a unique value for a given device, which can be retrieved from the device to create the certificate.

As an example of the relationship between the enabler and developer certificates, consider a device that is secured, with the debug port locked.

The "Unlocking the Debug Port on a Secure Device" figure demonstrates the unlocking process:

Figure: Unlocking the Debug Port on a Secure Device

Points to Note:

- The RoT Hash HBK0 refers to the ICV key pair used to sign the first key certificate.
- This is the same HBK ID indicated in the debug enabler certificate.
  - If the RoT keys used to sign the key certificate do not match the HBK ID, the enabler certificate is invalid.
- The SOC ID of the device is used in the debug developer certificate to allow the device to unlock.
  - If the SOC ID does not match, the device does not unlock.
- The debug mask applied to the device is the logical AND of the debug masks defined in the enabler certificate and the developer certificate.
  - Only bits allowed by the enabler certificate can be enabled by the developer.
  - The resultant mask enabled in the "Unlocking the Debug Port on a Secure Device" figure example is 0xF0F00000 0x00000000 0x00000000 0x00000000.