# EH State Configuration And Usage

## Overview

Devices delivered from manufacturing are by default in the Energy Harvesting state (EH_STATE), and therefore, in the corresponding life cycle state LCS_EH.

When in LCS_EH, it is possible to implement a lightweight security model that allows the device to be locked, preventing unauthorized access to the code or stored secrets.

To lock a device in LCS_EH, the device must be provided with a key and the DCU bit values. These two pieces of information combine to ensure that only the required debug facilities are allowed in normal operation, while also allowing the device to be unlocked when the correct key is provided via a defined port.

It is also possible to transition a device from LCS_EH to the more secure life cycle states by revoking the state.

When in LCS_EH, the following facilities are available:

1. Configuration Updates
   - Provide a key to the device, allowing debug access when the device is locked.
     - This is a 128-bit value, which might be unique to each physical device or might be unique to a device model, depending on the choice of the entity controlling this part of the process.
   - Write the debug control unit (DCU) values that specify the features available when the device is locked.
     - This is a 128-bit value.
   - Write a SOC ID to the device; the SOC IDcan be used later for identification.
     - This is a 32-bit value, which can be unique to each device.
2. Revocation
   - Revoke the ability to use the LCS_EH, transitioning the device to the secure life cycle model.

As shown in RSLSec PC-Based Tool, the RSLSec command-line utility can be used for all these tasks.

## Using LCS_EH Features in RSLSec

All LCS_EH features can be accessed using the eh sub-command within RSLSec.

Once the LCS_EH features have been selected then the update, unlock and relock options are available. These are shown below.

High level help in EH state

rslsec eh --help

usage:

RSLSec eh [-h] {update,revoke,unlock,relock} ...

/* EH Mode Operations */

p ositional arguments:

{update,revoke,unlock,relock}

/* Available LCS_EH Operations */

update /* Update the LCS_EH configuration */

revoke /* Revoke LCS_EH, transition to LCS_CM */

unlock /* Unlock a locked device with the key */

relock /* Relock a previously unlocked device */

optional arguments:

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

rslsec eh update --help

usage:

RSLSec eh update [-h] [--out OUT] [--target TARGET] [--write]

[--socid SOCID] [--key KEY KEY KEY KEY][--ndcu NDCU NDCU NDCU NDCU]

/* Update the LCS_EH configuration */

optional arguments:

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

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

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

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

--socid SOCID /* 32 bit SOCID */

--key KEY KEY KEY KEY

/* 128 bit Unlock Key */

--ndcu NDCU NDCU NDCU NDCU

/* 128 bit NDCU Enables

rslsec eh unlock --help

//usage:

RSLSec eh unlock [-h] [--target TARGET] [--write] --key KEY KEY KEY KEY [--dcu DCU DCU DCU DCU]

[--lock LOCK LOCK LOCK LOCK]

//Unlock a locked device with the key

//optional arguments:

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

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

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

--key KEY KEY KEY KEY

/* 128 bit Unlock Key */

--dcu DCU DCU DCU DCU

/* 128 bit nDCU Enables */

--lock LOCK LOCK LOCK LOCK

/* 128 bit DCULock values Enables */

rslsec eh relock --help

usage:

RSLSec eh relock [-h] [--target TARGET] [--write]

/* Relock a previously unlocked device */

optional arguments:

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

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

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

### Updating a device

When updating a device, three possible pieces of information can be written: the key, the nDCU bits, and the SOC ID. Each field is controlled independently, each can be updated in individual operations.

Once a field has been updated, its value must not be changed. Any changes would be detected by the ROM code and would invalidate the LCS_EH state of the device.

--key < 32-bit word > < 32-bit word > < 32-bit word > < 32-bit word >

- The Key
  - This is a 128-bit value provided as four 32-bit words.
  - It is defined by the device manufacturer and can be unique to each device, or can be common across a family of devices.
  - This key is only used to determine whether the device needs to be locked or unlocked, and is not intended for use in any encryption operations.
  - If a device has been locked, a user can unlock the device for debug purposes by providing the key through the dedicated DEU interface.

--ndcu < 32-bit word > < 32-bit word > < 32-bit word > < 32-bit word >

- The DCU Bits
  - This is a 128-bit value provided as four 32-bit words.
  - This is defined as the nDCU bits, so each bit is the inverse of the value that needs to be written to the DCU.
    - For instance, in order to completely lock the device, all enable bits need to be set to zero in the DCU, so this value would be '0xFFFFFFFF 0xFFFFFFFF 0xFFFFFFFF 0xFFFFFFFF'.
  - This is defined by the device manufacturer, but must reflect the DCU bit settings identified in the hardware documentation.
  - Again, this value is used to determine if the device needs to be locked, and if so, what bits need to be set.

--socid < 32-bit word >

- The SOC ID
  - This is a single 32-bit value.
  - This is defined by the device manufacturer, and can be recalled from the device using the DEU socid command.
  - This value is not used internally to the device, it is provided to allow device manufacturers to differentiate individual devices.

### Unlocking a device

Once a device has been locked, the debug port becomes inactive and it is not possible to communicate with the device through them. To unlock a device for allowing debug, additional information must be loaded to it indicating what functionality is required.

To maintain consistency with the ROT_STATE terminology, the data which is loaded to the device in this case is referred to as a debug certificate. It is not signed content or cryptographically secure, but the basic function is analogous to that situation.

There are three parts to the debug certificate in this case.

--key < 32-bit word > < 32-bit word > < 32-bit word > < 32-bit word >

- The Key
  - This is a 128-bit value provided as four 32-bit words.
  - It must match the key written at the device’s locking.

--dcu < 32-bit word > < 32-bit word > < 32-bit word > < 32-bit word >

- The DCU Bits
  - This is a 128-bit value provided as four 32-bit words.
  - This is defined as the DCU bits, not inverted.
    - For example,to completely unlock the device, all enable bits are set to one in the DCU. Therefore, this value would be '0xFFFFFFFF 0xFFFFFFFF 0xFFFFFFFF 0xFFFFFFFF'.

--lock < 32-bit word > < 32-bit word > < 32-bit word > < 32-bit word >

- The DCU Lock bits
  - This is a 128-bit value provided as four 32-bit words.
  - This allows DCU bits to be locked after the ROM has completed. When bits are locked, it is not possible for those bits in the DCU to be changed until the next power cycle.
  - This feature provides for the possibility of leaving some bits unlocked after the boot process; they can be controlled by firmware.
  - Generally this feature is not required; however, it is provided to maintain compatibility with the ROT_STATE behavior.
  - If this option is omitted, the default behavior is to lock all DCU bits on completion of the ROM processing.

### Relocking a device

When relocking a device, no options are required; the actions are performed via the DEU, erasing the loaded debug certificates.

### RSLSec Command Examples for LCS_EH

Examples of updating a device

Starting from a new device, check the SOC ID. It is initially not set, so the value returned is zero.

c:\Development\RSLSec>rslsec util socid

['0x00000000']

Set the SOC ID to some known value, and check that it is written correctly. (Note that the value of 1024 in decimal is shown as 0x400 hex.)

c:\Development\RSLSec>rslsec eh update --socid 1024 --write

c:\Development\RSLSec>rslsec util socid

['0x00000400']

Update the key and nDCU bits.

c:\Development\RSLSec>rslsec eh update --ndcu 0xFFFFFFFF 0xFFFFFFFF 0xFFFFFFFF

0xFFFFFFFF --key 1 2 3 4 --write

The device is now locked, and any attempts to access the debug port result in the debugger failing to connect. An example is shown of attempting to connect using J-Link. The output after this attempt might look slightly different, but the main point is that it has been rendered unable to connect (Cannot connect to target).

J-Link>connect

Please specify device / core. <Default>: RSL15

Type '?' for selection dialog

Device>

Please specify target interface:

J) JTAG (Default)

S) SWD

T) cJTAG

TIF>s

Specify target interface speed [kHz]. <Default>: 4000 kHz

Speed>

Device "RSL15" selected.

Connecting to target via SWD

Found SW-DP with ID 0x0BE12477

AP map detection skipped. Manually configured AP map found.

AP[0]: AHB-AP (IDR: Not set)

AP[0]: Skipped. Invalid implementer code read from CPUIDVal[31:24] = 0x00

Found SW-DP with ID 0x0BE12477

AP map detection skipped. Manually configured AP map found.

AP[0]: AHB-AP (IDR: Not set)

AP[0]: Skipped. Invalid implementer code read from CPUIDVal[31:24] = 0x00

****** Error: Could not find core in Coresight setup

Found SW-DP with ID 0x0BE12477

AP map detection skipped. Manually configured AP map found.

AP[0]: AHB-AP (IDR: Not set)

AP[0]: Skipped. Invalid implementer code read from CPUIDVal[31:24] = 0x00

Found SW-DP with ID 0x0BE12477

AP map detection skipped. Manually configured AP map found.

AP[0]: AHB-AP (IDR: Not set)

AP[0]: Skipped. Invalid implementer code read from CPUIDVal[31:24] = 0x00

Cannot connect to target.

J-Link>

Unlock the device, setting debug port to be open.

c:\Development\RSLSec>rslsec eh unlock --dcu 0x00001FFE 0 0 0 --key 1 2 3 4 --write

Verify that a debug connection can now be established.

J-Link>connect

Device "RSL15" selected.

Connecting to target via SWD

Found SW-DP with ID 0x0BE12477

AP map detection skipped. Manually configured AP map found.

AP[0]: AHB-AP (IDR: Not set)

AP[0]: Core found

AP[0]: AHB-AP ROM base: 0xE00FF000

CPUID register: 0x410FD214. Implementer code: 0x41 (ARM)

Found Cortex-M33 r0p4, Little endian.

FPUnit: 4 code (BP) slots and 0 literal slots

Security extension: implemented

Secure debug: enabled

CoreSight components:

ROMTbl[0] @ E00FF000

ROMTbl[0][0]: E000E000, CID: B105900D, PID: 000BBD21 Cortex-M33

ROMTbl[0][1]: E0001000, CID: B105900D, PID: 000BBD21 DWT

ROMTbl[0][2]: E0002000, CID: B105900D, PID: 000BBD21 FPB

Cortex-M33 identified.

J-Link>

Relock the device. this operation occurs via the DEU, so there is no need for the --write option.

c:\Development\RSLSec>rslsec eh relock

Again, verify that the ports are locked.

J-Link>connect

Device "RSL15" selected.

Connecting to target via SWD

Found SW-DP with ID 0x0BE12477

AP map detection skipped. Manually configured AP map found.

AP[0]: AHB-AP (IDR: Not set)

AP[0]: Skipped. Invalid implementer code read from CPUIDVal[31:24] = 0x00

Found SW-DP with ID 0x0BE12477

AP map detection skipped. Manually configured AP map found.

AP[0]: AHB-AP (IDR: Not set)

AP[0]: Skipped. Invalid implementer code read from CPUIDVal[31:24] = 0x00

****** Error: Could not find core in Coresight setup

Found SW-DP with ID 0x0BE12477

AP map detection skipped. Manually configured AP map found.

AP[0]: AHB-AP (IDR: Not set)

AP[0]: Skipped. Invalid implementer code read from CPUIDVal[31:24] = 0x00

Found SW-DP with ID 0x0BE12477

AP map detection skipped. Manually configured AP map found.

AP[0]: AHB-AP (IDR: Not set)

AP[0]: Skipped. Invalid implementer code read from CPUIDVal[31:24] = 0x00

Cannot connect to target.

J-Link>