# RoT Secure Mode Configuration And Usage

This section details the steps required to establish a secure Root of Trust in a new device that has had its EH signature revoked.

## Provisioning Process

Provisioning a device involves updating the specific fields in the NVM that cause life cycle state transitions. Provisioning is used to move a device in ROT_STATE from LCS_CM to LCS_DM, and then to LS_SE. Transitioning to RMA is outside the scope of the provisioning process.

Provisioning normally happens in two places:

1. The ICV (initial chip vendor) owner uses the Krtl of the device to provision some secret information to the NVM and transition the device from LCS_CM to LCS_DM.
2. The OEM owner requires a safe form of the Krtl to provision their own secrets to the device, and to transition it from LCS_DM to LCS_SE.

The "Provisioning Process Overview" figure demonstrates this process.

Figure: Provisioning Process Overview

The approach shown in the "Provisioning Process Overview" figure is the general case where the ICV, OEM, and onsemi are different parties. It is equally feasible for the three roles to be performed by a single party, but the processes involved must be the same.

## Required Assets When Securing A Device

The "Secure State Transitioning through Full Life Cycle" figure describes the steps and required assets used when transitioning a secure device through the full life cycle.

Figure: Secure State Transitioning through Full Life Cycle

## Initial Resource Creation

### Key Generation and Usage

This documentation uses specific names for the different keys used in the secure RoT process.

The processes involved in creating a 3072-bit RSA key, or a 128-bit AES key, are the same regardless of the end usage of the key, so these techniques can be used to create keys for other uses as well.

This section focuses on the highlighted part of the "Initial Resource Creation" figure.

Figure: Initial Resource Creation

### Asset Organization for Demonstration

For the purpose of this document, assets refers to any binary object that might be used to support the secure Roots of Trust.

Some of the items this can include are listed below:

- Encryption Keys
- Signatures for content
- Certificates
- Application binary images

To make the references to these assets easier to understand in the example extracts, the following folder structure is assumed:

Example Folder Structure

./assets /* Top level folder containing all assets */

/apps /* Applications folder which contains test */

/* applications to be signed */

/RSL15 /* Definition of the device type for the */

/* applications */

/default /* The default application folder which */

/* contains unencrypted applications signed with */

/* specific keys */

/encrypted /* The encrypted application folder which */

/* contains encrypted applications, again */

/* signed with specific keys */

/... /* The ... indicates there may be more folders of */

/* a similar form */

/...

/cert /* Top level folder containing generated */

/* certificates */

/hbk0 /* Folder containing certificates associated with */

/* HBK0 */

/...

/hbk1 /* Folder containing certificates associated with */

/* HBK1 */

/...

/keys /* Top level folder for generated keys, the */

/* following folder indicate some of the keys that */

/* are supported */

/hbk0 /* hbk0 & hbk1 comprise RSA 3072-bit public */

/* private key pairs with their associated hash */

/* values */

/hbk1

/kce /* kce, kceicv, kcp, kpicv are 128-bit AES keys */

/kceicv

/kcp

/kpicv

/* version in the device */

/...

### Root of Trust Key Pair

A Root of Trust uses a hash of an RSA 3072-bit public key as the basis for all authentication operations.

In order to create a suitable RSA key pair with the associated hashes, the RSLSec tool can be used as shown in the following example:

Creation of RSA Key Pairs

C:\Development\RSLSec>rslsec trust make --help

usage:

RSLSec trust make [-h] [--target <TARGET>] [--name <NAME>]

[--phrase <PHRASE>]

{hbk,hbk0,hbk1,kpicv,kceicv,kcp,kce} folder

positional arguments:

{hbk,hbk0,hbk1,kpicv,kceicv,kcp,kce}

/* Define which key to make */

folder /* Define the folder to which the files need to be written */

optional arguments:

-h, --help /* show this help message and exit */

--target <TARGET> /* Target connection [RSL15] */

--name <NAME> /* Define the name associated with the various files */

--phrase <PHRASE> /* Define the passphrase associated with the private key */

C:\Development\RSLSec>rslsec trust make hbk0 ./assets/keys/hbk0

C:\Development\RSLS

Where:

- hbk0 defines the type of key that is being made, in this case specifying that a RoT RSA key pair with associated hash is being created, associated with HBK0.
  - For RoT RSA key pairs, the valid values are hbk0, hbk1, and hbk, depending on the end use of the key pair.
- No passphrase has been provided for the private key; therefore, a random passphrase is generated and used.
- The various generated files are stored in the specified folder ./assets/keys/hbk0.
  - hbk0.prv.pem: Holds the generated private key in an encrypted PEM file
  - hbk0.pub.pem: Holds the public key associated with the generated private key, again in PEM format
  - hbk0.pwd: Holds the passphrase required to use the private key
  - hbk0.sha.bin: Contains the truncated SHA-256 signature of the public key
  - hbk0.sha.txt: Contains a textual form of the binary signature file

The generation of a 3072-bit RSA key pair is a long process, which can take several minutes to complete.

### Provisioning and Code Encryption Keys

Provisioning and code encryption keys are defined as 128-bit AES keys, and can be created in exactly the same way as the RSA keys defined above.

Generation of code encryption and provisioning keys for the CMPU provisioning process takes the following form:

Creation of AES Keys

C:\Development\RSLSec>rslsec trust make kpicv ./assets/keys/kpicv

C:\Development\RSLSec>rslsec trust make kceicv ./assets/keys/kceicv

Where:

- kpicv / kceicv define the types of keys being generated.
  - For AES keys, the valid values are kpicv, kceicv, kcp and kce.
- Again. no passphrase has been supplied, so the tool generates a random passphrase to be used when securing the keys.
- The various generated files aare placed in the specified folders,'./assets/keys/kpicv and ./assets/keys/kceicv
  - kpicv.bin / kceicv.bin: 128-bit AES key stored as a binary object
  - kpicv.enc / kceicv.enc: The same key stored in a secure form, encrypted with the passphrase
  - kpicv.pwd / kceicv.pwd: The passphrase to be used to decrypt the secure AES key file
  - kpicv.txt / kceicv.txt: The AES key in a human readable form

## Provisioning CM to DM

This section covers the highlighted area in the "ICV Provisioning" figure:

Figure: ICV Provisioning

As previously mentioned, the process to go from LCS_CM to LCS_DM requires specific data to be written to the NVM of the device. This is indicated in the diagram in Provisioning Process, and is as follows:

- Kpicv
- Kceicv
- HBK0
- There could be additional metadata such as minimum software versions and initial DCU states included here, but the default values are enough for this example.

The process for obtaining this data is described in detail in Initial Resource Creation. However, the specific commands are repeated below, to demonstrate the full process.

/* Revoke the EH_STATE to switch to LCS_CM */

C:\Development\RSLSec>rslsec eh revoke --write --target RSL15

/* Create a new HBK0, Kpicv and Kceicv */

C:\Development\RSLSec>rslsec trust make hbk0 ./assets/keys/hbk0

C:\Development\RSLSec>rslsec trust make kpicv ./assets/keys/kpicv

C:\Development\RSLSec>rslsec trust make kceicv ./assets/keys/kceicv

/* locks the debug port. The names and paths could change as relevant to the */ /* assets used. */

C:\Development\RSLSec>rslsec icv provision --hbk0 ./assets/keys/hbk0/hbk0.sha.bin --kpicv ./assets/keys/kpicv/kpicv.enc --kpicvpwd ./assets/keys/kpicv/kpicv.pwd --kceicv ./assets/keys/kceicv/kceicv.enc --kceicvpwd ./assets/keys/kceicv/kceicv.pwd --write --target RSL15

Full details of the icv provision command can be found below:

C:\Development\RSLSec>rslsec icv provision --help

usage: RSLSec icv provision [-h] [--out OUT] [--target TARGET] [--write]

[--krtl KRTL] [--hbk0 HBK0] [--kpicv KPICV]

[--kceicv KCEICV] [--krtlpwd KRTLPWD]

[--kpicvpwd KPICVPWD] [--kceicvpwd KCEICVPWD]

[--minversion MINVERSION] [--config CONFIG]

[--dcu DCU DCU DCU DCU]

optional arguments:

-h, --help /* Show this help message and exit */

--out OUT /* File to which the loadable package needs to be written */

--target TARGET /* Target connection [RSL15] */

--write /* Update the attached target with the given options */

--hbk0 HBK0 /* File containing the 128 bit unique HBK0 */

--kpicv KPICV /* File containing the 128 bit provisioning key */

--kceicv KCEICV /* File containing the 128 bit code encryption key */

--krtlpwd KRTLPWD /* File containing the password to unencrypt the Krtl */

--kpicvpwd KPICVPWD /* File containing the password to unencrypt the Kpicv */

--kceicvpwd KCEICVPWD

/* File containing the password to unencrypt the Kceicv */

--minversion MINVERSION

/* ICV Minimum software version */

--config CONFIG /* ICV user config word */

--dcu DCU DCU DCU DCU

/* ICV default DCU values */

The flags used for ICV provisioning are shown in the "IVC Provisioning Flags" table.

Table: IVC Provisioning Flags
Flag | Type | Description
--- | --- | ---
--out | File name | The name of a file to which the configuration data is written Not required for provisioning operations, but provided to allow the information to be stored for later use if needed
--target | Device name | The name of the device being provisioned (generally RSL15)
--write | N/A | Instructs the tool to update the connected device by writing the configuration information to the NVM
--hbk0 | File name | File containing the 128-bit hash value of the public key associated with the Root of Trust
--kpicv & --kpicvpwd | File names | Specifies two files, one containing the encrypted Kcpicv and the second containing the passphrase to decrypt the key for use
--kceicv & --kceicvpwd | File names | Specifies two files, one containing the encrypted Kceicv and the second containing the passphrase to decrypt the key for use
--minversion | Integer <64 | Defines the minimum version of the firmware that can be used on the device
--config | 32-bit integer | Defines the ICV configuration word
--dcu | 4 * 32-bit integer | Defines the values of 128-bit DCU Default: 0x00001FFE, 0x00001FFE, 0x00000000, 0x00000000

## Unlocking a Device Using Debug Certificates

When a device is in LCS_DM or LCS_SE, the default behavior is to have the debug port locked, providing no access to the device.

To access a locked device, debug certificates must be provided, which grant specific access rights to the debug port and additional features controlled by the DCU.

This process is outlined Debug Certificate Loading Process And Constraints.

The following section demonstrates in more detail the actual process involved using the RSLSec tool.

### Overview of Required Assets

In order to create and use a valid debug certificate a number of assets are required:

1. The public/private RSA key pair associated with the specific Root of Trust (Root of Trust Key)
2. A debug enabler key, used to create and sign the debug enabler certificate (Debug Enabler Key)
3. When unlocking secure devices, the SOC ID of the device must be known. This is allocated during ICV provisioning and must be requested from the device to be unlocked.
4. A debug developer key, used to create and sign the debug developer certificate (Debug Developer Key)

The "Debug Certificate Chain" figure shows how these components relate to each other.

Figure: Debug Certificate Chain

It is possible for the owner of each of these keys to be different, and as such, to have no knowledge of the private key or the others. For instance, the entity providing the debug enabler certificate can provide their public key to the owner of the Root of Trust to have them provide the first level key certificate. This maintains the security of the RoT private keys.

In addition, a developer public key can be incorporated into an enablement certificate, allowing generate developer certificates to be generated for multiple devices. In each case the private keys are kept secure within their domain, but the full chain of trust can be authenticated.

### Creation of Keys, Certificates and Unlocking

#### LCS_DM

Each of the three required keys can be generated in exactly the same way. The device has already been provisioned, so the HBK0 is already known, but the debug enabler and debug developer keys need to be created.

Once the keys are available, a key certificate, debug enabler certificate, and debug developer certificate are required.

Creation of debug certificates and unlocking of a device in LCS_DM

/* Create a debug enabler RSA key */

C:\Development\RSLSec>rslsec trust make hbk0 ./assets/keys/hbk0_deb_en

/* Create a debug developer RSA key pair */

C:\Development\RSLSec>rslsec trust make hbk0 ./assets/keys/hbk0_deb_dev

/* Create the first key certificate */

C:\Development\RSLSec>rslsec trust cert key --out ./assets/cert/hbk0/key_0.crt --hbk hbk0 --keypair ./assets/keys/hbk0/hbk0.prv.pem --pwd ./assets/keys/hbk0/hbk0.pwd --pubkey ./assets/keys/hbk0_deb_en/hbk0_deb_en.pub.pem

/* Create the debug enabler certificate */

C:\Development\RSLSec>rslsec trust cert enabler --out ./assets/cert/hbk0/dbg_en_dm.crt --keypair ./assets/keys/hbk0_deb_en/hbk0_deb_en.prv.pem --pwd ./assets/keys/hbk0_deb_en/hbk0_deb_en.pwd --pubkey ./assets/keys/hbk0_deb_dev/hbk0_deb_dev.pub.pem --keycert ./assets/cert/hbk0/key_0.crt --hbk hbk0 --lcs dm

/* Create the debug developer certificate */

C:\Development\RSLSec>rslsec trust cert developer --out ./assets/cert/hbk0/dbg_dev_dm.crt --keypair ./assets/keys/hbk0_deb_dev/hbk0_deb_dev.prv.pem --pwd ./assets/keys/hbk0_deb_dev/hbk0_deb_dev.pwd --enabler ./assets/cert/hbk0/dbg_en_dm.crt

/* And unlock the device */

C:\Development\RSLSec>rslsec secure unlock --cert ./assets/cert/hbk0/dbg_dev_dm.crt --target RSL15

#### LCS_SE

When creating a debug certificate for a device in LCS_SE, the debug developer certificate requires the SOC ID of the device.

Creation of debug certificates and unlocking of a device in LCS_SE (Using HBK0)

/* Create a debug enabler RSA key */

C:\Development\RSLSec>rslsec trust make hbk0 ./assets/keys/hbk0_deb_en

/* Create a debug developer RSA key pair */

C:\Development\RSLSec>rslsec trust make hbk0 ./assets/keys/hbk0_deb_dev

/* Create the first key certificate */

C:\Development\RSLSec>rslsec trust cert key --out ./assets/cert/hbk0/key_0.crt --hbk hbk0 --keypair ./assets/keys/hbk0/hbk0.prv.pem --pwd ./assets/keys/hbk0/hbk0.pwd --pubkey ./assets/keys/hbk0_deb_en/hbk0_deb_en.pub.pem

/* Create the debug enabler certificate */

C:\Development\RSLSec>rslsec trust cert enabler --out ./assets/cert/hbk0/dbg_en_se.crt --keypair ./assets/keys/hbk0_deb_en/hbk0_deb_en.prv.pem --pwd ./assets/keys/hbk0_deb_en/hbk0_deb_en.pwd --pubkey ./assets/keys/hbk0_deb_dev/hbk0_deb_dev.pub.pem --keycert ./assets/cert/hbk0/key_0.crt --hbk hbk0 --lcs se

/* Query the SOC ID from the device */

C:\Development\RSLSec>rslsec util socid --target RSL15

[0xnnnnnnnn 0xnnnnnnnn 0xnnnnnnnn 0xnnnnnnnn 0xnnnnnnnn 0xnnnnnnnn 0xnnnnnnnn 0xnnnnnnnn]

/* Create the debug developer certificate */

C:\Development\RSLSec>rslsec trust cert developer --socid 0xnnnnnnnn 0xnnnnnnnn 0xnnnnnnnn 0xnnnnnnnn 0xnnnnnnnn 0xnnnnnnnn 0xnnnnnnnn 0xnnnnnnnn --out ./assets/cert/hbk0/dbg_dev_se.crt --keypair ./assets/keys/hbk0_deb_dev/hbk0_deb_dev.prv.pem --pwd ./assets/keys/hbk0_deb_dev/hbk0_deb_dev.pwd --enabler ./assets/cert/hbk0/dbg_en_se.crt

/* And unlock the device */

C:\Development\RSLSec>rslsec secure unlock --cert ./assets/cert/hbk0/dbg_dev_se.crt --target RSL15

Using the HBK1, the Root of Trust is very similar, but uses the --hbk1 flag where appropriate and is derived from a chain of trust starting at the HBK1 RSA keys.

## Provisioning DM to SE

The process for moving a device from LCS_DM to LCS_SE (secure) is similar to that used when transitioning from LCS_CM to LCS_DM, as seen in the highlighted portion of the "OEM Provisioning" figure.

Figure: OEM Provisioning

In this case, the specific data items that need to be provisioned to the device are:

- Kcp
- Kce
- HBK1
- Potentially, additional metadata such as minimum software versions and initial DCU states, but the default values are enough for this example

This stage might be performed by a party other than the owner of the ICV RoT.

Other than this initial stage, the process is similar to the LCS_CM → LCS_DM sequence:

- Create the HBK1 RSA key pair and SHA256 hash value.
- Create a OEM_WRAP_REQUEST RSA key pair and SHA256 hash value.
- Create the 128-bit AES keys for code encryption and provisioning.
- Request a wrapped key from the ICV and use that wrapped key to provision the OEM assets.
  - This locks the device.
- Create the debug enabler and debug developer RSA key pairs and SHA256 hash values.
- Create the key certificate using the HBK1 key pair.
- Create the debug enabler certificate using the enable key pair.
- Read the SOC ID from the device to be unlocked.
- Create the debug developer certificate using the developer key pair and the SOC ID.
- Unlock the device using the debug certificate.

This process is shown below:

OEM Provisioning Process

/* Make folders for some of the keys and certificate needed */

C:\Development\RSLSec>mkdir assets\cert\hbk1

/* Create the Root of Trust RSA key pair and associated hash files */

C:\Development\RSLSec>rslsec trust make hbk1 ./assets/keys/hbk1

/* Create a wrapping key for the HBK1 wrap request */

C:\Development\RSLSec>rslsec trust make hbk1 ./assets/keys/oem_wrap_request

/* Create the provisioning and code encryption AES keys */

C:\Development\RSLSec>rslsec trust make kcp ./assets/keys/kcp

C:\Development\RSLSec>rslsec trust make kce ./assets/keys/kce

/* Provision the ICV assets to the device */

C:\Development\RSLSec>rslsec oem provision --hbk1 ./assets/keys/hbk1/hbk1.sha.bin --kcp ./assets/keys/kcp/kcp.enc --kcppwd ./assets/keys/kcp/kcp.pwd --kce ./assets/keys/kce/kce.enc --kcepwd ./assets/keys/kce/kce.pwd --write --target RSL15

/* The device is in LCS_SE and has its debug port locked */

/* Create RSA keys for use when creating the debug enabler and developer certificates */

C:\Development\RSLSec>rslsec trust make hbk0 ./assets/keys/hbk1_deb_en

C:\Development\RSLSec>rslsec trust make hbk0 ./assets/keys/hbk1_deb_dev

/* Fetch the SOC ID and store it in a file */

C:\Development\RSLSec>rslsec util socid --target RSL15 > socid.txt

/* Create a key certificate using the Root of Trust hash, and chain the enabler */

/* and developer certificates from that */

C:\Development\RSLSec>rslsec trust cert key --out ./assets/cert/hbk1/key_0.crt --hbk hbk1 --keypair ./assets/keys/hbk1/hbk1.prv.pem --pwd ./assets/keys/hbk1/hbk1.pwd --pubkey ./assets/keys/hbk1_deb_en/hbk1_deb_en.pub.pem

C:\Development\RSLSec>rslsec trust cert enabler --out ./assets/cert/hbk1/dbg_en_se.crt --keypair ./assets/keys/hbk1_deb_en/hbk1_deb_en.prv.pem --pwd ./assets/keys/hbk1_deb_en/hbk1_deb_en.pwd --pubkey ./assets/keys/hbk1_deb_dev/hbk1_deb_dev.pub.pem --keycert ./assets/cert/hbk1/key_0.crt --hbk hbk1 --lcs se

C:\Development\RSLSec>rslsec trust cert developer --socidFile socid.txt --out ./assets/cert/hbk1/dbg_dev_se.crt --keypair ./assets/keys/hbk1_deb_dev/hbk1_deb_dev.prv.pem --pwd ./assets/keys/hbk1_deb_dev/hbk1_deb_dev.pwd --enabler ./assets/cert/hbk1/dbg_en_se.crt

/* Now unlock the device using the newly created certificate */

C:\Development\RSLSec>rslsec secure unlock --cert ./assets/cert/hbk1/dbg_dev_se.crt --target RSL15

Full details of the oem provision command can be found below:

C:\Development\RSLSec>rslsec oem provision --help

usage: RSLSec oem provision [-h] [--out OUT] [--target TARGET] [--write]

[--hbk HBK | --hbk1 HBK1] [--kcp KCP] [--kce KCE]

[--kcppwd KCPPWD] [--kcepwd KCEPWD] [--minversion MINVERSION]

[--dcu DCU DCU DCU DCU]

optional arguments:

-h, --help /* show this help message and exit */

--out OUT /* File to which the loadable package needs to be written */

--target TARGET /* Target connection [RSL15] */

--write /* Update the attached target with the given options */

--hbk HBK /* File containing the HBK */

--hbk1 HBK1 /* File containing the HBK1 */

--kcp KCP /* File containing the 128 bit provisioning key */

--kce KCE /* File containing the 128 bit code encryption key */

--kcppwd KCPPWD /* File containing the password to unencrypt the Kcp */

--kcepwd KCEPWD /* File containing the password to unencrypt the Kce */

--minversion MINVERSION

/* OEM Minimum software version */

--dcu DCU DCU DCU DCU

/* OEM default DCU values */

The flags used for OEM provisioning are shown in the "OEM Provisioning Flags" table.

Table: OEM Provisioning Flags
Flag | Type | Description
--- | --- | ---
--out | File name | This flag is used to provide the name of a file to which the configuration data needs to be written. It is not required for provisioning operations, but is provided to allow the information to be stored for later use if needed.
--target | Device name | This is the name of the device being provisioned; generally RSL15.
--write | n/a | This flag instructs the tool to update the connected device by writing the configuration information to the NVM.
--hbk, --hbk1 | File name | This is the file containing the 128-bit hash value of the public key associated with the Root of Trust (256 bit if --hbk using single RoT) .
--kcp & --kcppwd | File names | This specifies two files: the first containing the encrypted Kcp, and the second containing the passphrase to decrypt the key for use.
--kce & --kcepwd | File names | This specifies two files: the first containing the encrypted Kce, and the second containing the passphrase to decrypt the key for use.
--minversion | Integer <96 | This defines the minimum version of the firmware that can be used on the device.
--config | 32-bit integer | This defines the ICV configuration word.
--dcu | 4 * 32-bit integer | This defines the values of 128-bit DCU. Default: 0x00001FFE, 0x00001FFE, 0x00000000, 0x00000000

## Transition to LCS_RMA

Transitioning to LCS_RMA is required when devices need to be returned to the manufacturer due to device failure. This process involves erasing secret information on the device, and opens the debug port to allow fault analysis. Since the device could contain secret information from both the ICV and OEM Roots of Trust, specific signed certificates from both parties must be present to erase the secret information and to unlock the debug port. These certificates are authenticated against the specified RoT in the same way as normal debug certificates.

The same process is followed for both roots of trust:

1. A special debug enabler certificate is created, indicating that the RMA switch is allowed on any devices with the RoT hashes (HBK0/HBK1).
2. A special debug developer certificate is created, indicating which specific device can be transitioned to LCS_RMA.
3. The certificate is loaded to the device in the same way as other debug certificates, and the device performs a power on reset.

The transition to RMA occurs only when both of the Roots of Trust provide a suitable debug certificate.

The process is outlined below:

/* You can reuse the key certificates generated during the initial */

/* provisioning of both ICV and OEM assets. */

/* Make sure you know the SOC ID of the device. */

C:\Development\RSLSec>rslsec util socid --target RSL15 > socid.txt

/* Create the HBK0 debug enabler and developer keys to support the transition. */

C:\Development\RSLSec>rslsec trust cert enabler --out ./assets/cert/hbk0/rma_en_se.crt --keypair ./assets/keys/hbk0_deb_en/hbk0_deb_en.prv.pem --pwd ./assets/keys/hbk0_deb_en/hbk0_deb_en.pwd --pubkey ./assets/keys/hbk0_deb_dev/hbk0_deb_dev.pub.pem --keycert ./assets/cert/hbk0/key_0.crt --hbk hbk0 --lcs se --rma --target RSL15

C:\Development\RSLSec>rslsec trust cert developer --socidFile socid.txt --out ./assets/cert/hbk0/rma_dev_se.crt --keypair ./assets/keys/hbk0_deb_dev/hbk0_deb_dev.prv.pem --pwd ./assets/keys/hbk0_deb_dev/hbk0_deb_dev.pwd --enabler ./assets/cert/hbk0/rma_en_se.crt

/* Create the HBK1 debug enabler and developer keys to support the transition. */

C:\Development\RSLSec>rslsec trust cert enabler --out ./assets/cert/hbk1/rma_en_se.crt --keypair ./assets/keys/hbk1_deb_en/hbk1_deb_en.prv.pem --pwd ./assets/keys/hbk1_deb_en/hbk1_deb_en.pwd --pubkey ./assets/keys/hbk1_deb_dev/hbk1_deb_dev.pub.pem --keycert ./assets/cert/hbk1/key_0.crt --hbk hbk1 --lcs se --rma --target RSL15

C:\Development\RSLSec>rslsec trust cert developer --socidFile socid.txt --out ./assets/cert/hbk1/rma_dev_se.crt --keypair ./assets/keys/hbk1_deb_dev/hbk1_deb_dev.prv.pem --pwd ./assets/keys/hbk1_deb_dev/hbk1_deb_dev.pwd --enabler ./assets/cert/hbk1/rma_en_se.crt

/* Apply the certificates. Note that the order is important. */

C:\Development\RSLSec>rslsec secure unlock --cert ./assets/cert/hbk1/rma_dev_se.crt --target RSL15

/* Finally erase the certificates by relocking the device. As the device is */

/* now in LCS_RMA, the debug port remains open. */

C:\Development\RSLSec>rslsec secure relock --target RSL15

On completion of this process, the device is unlocked and the ICV/OEM provisioning and code encryption keys are erased.

## Creating and Executing a Secure Application

### Creating a Secure Application

The Root of Trust provides mechanisms to ensure that an application being executed by the ROM meets criteria for it to be verified and authenticated. The mechanisms, criteria and procedure are explained here.

Verification of an application ensures that the delivered image has not been corrupted in transit or changed in any way. This is done by calculating the SHA256 signature of the application and comparing it with that provided by the associated content certificate. In addition, the minimum software version of the application must be greater than or equal to that defined in the NVM for the particular Root of Trust. This is an anti-rollback measure allowing older images to be disabled.

Authentication of applications ensures that the delivered image has been created by the correct author, i.e., the owner of the Root of Trust private keys. This is done by ensuring that the chain of trust defined by the key and the content certificates can be cryptographically proven to have been signed by the Root of Trust private key associated with the stored HBK0/1 hash values.

### Creating and Executing a Secure Application

A secure application can be any application that normally executes on RSL15, with the qualification that it is accompanied by a suitable application configuration element and a Root of Trust chain embedded in one of the Roots of Trust in the system: HBK0 or HBK1.

The "Secure Application Layouts" figure shows two possible layouts of a secure application in flash memory.

Figure: Secure Application Layouts

As can be seen from the diagram, the only fixed data is the application configuration sector, which holds the locations of the certificates and program start address. The certificates and program can be placed anywhere in flash, as long as the appropriate addresses are set up correctly.

Any applications started by the ROM in LCS_DM or LCS_SE must have associated Root of Trust certificate chains and be correctly configured for the ROM to be able to execute them. If this information is not available, the ROM cannot start an application, and instead executes a failure state.

### Creating a Secure Application in LCS_DM using HBK0

The process of creating a secure application is the same, regardless of the HBK hash used or the life cycle state.

In LCS_DM, only the HBK0 hash has been provisioned to the device, so this is used to demonstrate the process.

The following actions need to be performed:

- Two RSA keys are required to generate the key certificate chain.
- Two key certificates are required to establish the Root of Trust certificate chain.
  - The first key certificate is signed by the Root of Trust key HBK0 and provides the key 1 public key.
  - The second key certificate is signed by the key 1 and provides the key 2 public key.
- The content certificate defines the loadable, verified, and authenticated sections of the binary image.
  - The content certificate is signed by key 2.
- The two key certificates, the content certificate, and the application image are combined with a loadable application configuration block to create the loadable binary.

/* This assumes the device has been transitioned to LCS_DM, and */ /* suitable debug certificates have been loaded to unlock the device. */ /* It makes use of previously created HBK0 Root of Trust certificates. */

/* Create the key certificates */

C:\Development\RSLSec>rslsec trust make hbk0 ./assets/keys/hbk0_key_1

C:\Development\RSLSec>rslsec trust make hbk0 ./assets/keys/hbk0_key_2

/* Create the key certificates */

C:\Development\RSLSec>rslsec trust cert key --out ./assets/cert/hbk0/key_1.crt --hbk hbk0 --keypair ./assets/keys/hbk0/hbk0.prv.pem --pwd ./assets/keys/hbk0/hbk0.pwd --pubkey ./assets/keys/hbk0_key_1/hbk0_key_1.pub.pem

C:\Development\RSLSec>rslsec trust cert key --out ./assets/cert/hbk0/key_2.crt --hbk hbk0 --keypair ./assets/keys/hbk0_key_1/hbk0_key_1.prv.pem --pwd ./assets/keys/hbk0_key_1/hbk0_key_1.pwd --pubkey ./assets/keys/hbk0_key_2/hbk0_key_2.pub.pem

/* Create the content certificate */

C:\Development\RSLSec>rslsec trust cert content --out ./assets/cert/hbk0/content.crt --keypair ./assets/keys/hbk0_key_2/hbk0_key_2.prv.pem --pwd ./assets/keys/hbk0_key_2/hbk0_key_2.pwd --image ./images/RSL15/blinky/blinky.hex --key1 --key2 --target RSL15

/* Pack the signed image with the certificates */

C:\Development\RSLSec>mkdir .\assets\apps

C:\Development\RSLSec>mkdir .\assets\apps\RSL15

C:\Development\RSLSec>mkdir .\assets\apps\RSL15\hbk0

C:\Development\RSLSec>rslsec trust pack --out ./assets/apps/RSL15/hbk0/blinky.hex --key1 ./assets/cert/hbk0/key_1.crt --key2 ./assets/cert/hbk0/key_2.crt --content ./assets/cert/hbk0/content.crt --image ./images/RSL15/blinky/blinky.hex --target RSL15 --firstKeyAddress 0x00159000 --secondKeyAddress 0x00159400 --contentAddress 0x00159800

/* Load the image */

C:\Development\RSLSec>rslsec util load ./assets/apps/RSL15/hbk0/blinky.hex --target RSL15 --write

### Creating a Secure Application in LCS_SE using HBK1

In LCS_SE, the HBK0 and HBK1 hashes have been provisioned to the device so either can be used to authenticate an application. In this example the HBK1 is used.

The following actions need to be performed:

- Two RSA keys are needed to generate the key certificate chain.
- Two key certificates are required to establish the Root of Trust certificate chain.
  - The first key certificate is signed by the Root of Trust key HBK1 and provides the key 1 public key.
  - The second key certificate is signed by the key 1 and provides the key 2 public key.
- The content certificate defines the loadable, verified and authenticated sections of the binary image.
  - The content certificate is signed by key 2.
  - At the time of creating the content certificate, you need to specify whether key certificate 1 and key certificate 2 are going to be used. This information is required during certificate creation to make sure that the certificate size is correct.
- The two key certificates, the content certificate, and the application image are combined with a loadable application configuration block to create the loadable binary.

/* This assumes the device has been transitioned to LCS_SE, and suitable */

/* devbug certificates have been loaded to unlock the device. */

/* It makes use of previously created HBK1 Root of Trust certificates. */ /* Create RSA keys to be used when creating the three certificate RoT chain. */

C:\Development\RSLSec>rslsec trust make hbk1 ./assets/keys/hbk1_key_1

C:\Development\RSLSec>rslsec trust make hbk1 ./assets/keys/hbk1_key_2

/* Create the key certificates */

C:\Development\RSLSec>rslsec trust cert key --out ./assets/cert/hbk1/key_1.crt --hbk hbk1 --keypair ./assets/keys/hbk1/hbk1.prv.pem --pwd ./assets/keys/hbk1/hbk1.pwd --pubkey ./assets/keys/hbk1_key_1/hbk1_key_1.pub.pem>

C:\Development\RSLSec>rslsec trust cert key --out ./assets/cert/hbk1/key_2.crt --hbk hbk1 --keypair ./assets/keys/hbk1_key_1/hbk1_key_1.prv.pem --pwd ./assets/keys/hbk1_key_1/hbk1_key_1.pwd --pubkey ./assets/keys/hbk1_key_2/hbk1_key_2.pub.pem

/* Create the content certificate */

C:\Development\RSLSec>rslsec trust cert content --out ./assets/cert/hbk1/content.crt --keypair ./assets/keys/hbk1_key_2/hbk1_key_2.prv.pem --pwd ./assets/keys/hbk1_key_2/hbk1_key_2.pwd --image ./images/RSL15/blinky/blinky.hex --key1 --key2 --target RSL15

/* Pack the signed image with the certificates */

C:\Development\RSLSec>mkdir .\assets\apps\RSL15\hbk1

C:\Development\RSLSec>rslsec trust pack --out ./assets/apps/RSL15/hbk1/blinky.hex --key1 ./assets/cert/hbk1/key_1.crt --key2 ./assets/cert/hbk1/key_2.crt --content ./assets/cert/hbk1/content.crt --image ./images/RSL15/blinky/blinky.hex --target RSL15 --firstKeyAddress 0x00159000 --secondKeyAddress 0x00159400 --contentAddress 0x00159800

/* Load the image */

C:\Development\RSLSec>rslsec util load ./assets/apps/RSL15/hbk1/blinky.hex --target RSL15 --write

LCS_SE and HBK0/HBK1

In LCS_SE, it is possible to boot from either Root of Trust, so an application signed with HBK0 can still be executed successfully in LCS_SE.

One or two key certificates

The descriptions above show the process when two key certificates are used to provide additional protection to the Root of Trust keys. It is also possible to use a single key certificate, signed with the HBK0/1, and provide the public key of the key pair used to sign the content certificate. This mode is valid and results in fast power-up times from a power on reset condition. If you are only using one key certificate, you need to set --key1 or --key 2 to false when generating the content certificate. --key1 and --key2 are used during the generation of the content certificate to set the certificate size.