Provisioning keys on the nRF54H20 SoC

This guide describes how to provision pre-generated cryptographic keys on an nRF54H20 SoC. It is intended for developers who wish to create a predefined set of keys for their application, made available through PSA Crypto key identifiers.

Prerequisites

To follow this guide, your nRF54H20 device must meet the following requirements:

• On the nRF54H20 DK, you must provision the DK as described in the Getting started with the nRF54H20 DK page.

• On a custom nRF54H20-based device, you must configure, generate, and program the BICR as described in the Configuring your application for a custom PCB page.

Overview

The keys provisioning workflow for the nRF54H20 SoC consists of three main steps:

1. Choosing key identifiers based on the desired properties for each key.

2. Generating the required metadata using a script provided with the nRF Connect SDK.

3. Provisioning the keys to the nRF54H20 SoC.

Choosing a key ID

Key provisioning is supported by the IronSide SE firmware through the IronSide Secure Enclave implementation of the PSA Crypto API. IronSide SE defines two categories of keys that can be provisioned: standard user keys and non-standard revocable keys. These categories are tied to distinct key ID ranges.

User keys

These are the standard persistent keys conforming to the supported version of the PSA Crypto API:

• Minimum ID: 0x00000001 (PSA_KEY_ID_USER_MIN)

• Maximum ID: 0x3FFFFFFF (PSA_KEY_ID_USER_MAX)

To successfully provision user keys, you must first configure cryptographic partitions in your UICR.SECURESTORAGE configuration.

Revocable keys

These are an extension of user keys with special properties for secure provisioning during device manufacturing:

• Minimum ID: 0x40002000

• Maximum ID: 0x4FFFFFFF

Revocable keys can only be provisioned as long as the UICR.LOCK configuration is disabled. Once the UICR is locked, no more keys can be created in this range, which means that when a revocable key is destroyed, it cannot be replaced.

These keys are provisioned into IronSide SE’s internal storage, not the location controlled by UICR.SECURESTORAGE.

Generating key metadata

The PSA Key Attributes generator script is used to generate a JSON file containing the necessary cryptographic keys, BLOBs, and metadata required for provisioning.

Here is an example command to generate metadata for provisioning the public key part of an Ed25519 key, from a pre-existing PEM file, as a revocable key:

python generate_psa_key_attributes.py --usage VERIFY --id 0x40002000 --type ECC_PUBLIC_KEY_TWISTED_EDWARDS --key-bits 255 --algorithm EDDSA_PURE --location LOCATION_LOCAL_STORAGE --key-from-file public_key.pem --file all_keys.json --persistence PERSISTENCE_DEFAULT

The output file (named all_keys.json in the previous example) serves as an input for the next step.

Provisioning the keys

nRF Util provides the nrfutil device x-provision-keys command to provision keys onto the KMU.

The command requires a JSON file with the keys and the key metadata. You can create a JSON file when you run the script with the --file option. You can also create a JSON file from the PEM file you generated earlier with the --key-from-file option. Each next invocation using the same --file option adds multiple keys to the same JSON file.

Each key entry in the JSON file contains the following fields:

“Key entry fields”

Field	Description
metadata	HEX-encoded PSA key attributes
value	Key value (HEX string or TRNG specification)

When you use nRF Util to provision keys, the tool does not validate the JSON file. It functions as a transport layer, transferring the key data to the correct location in the device.

The IronSide SE firmware on the device handles the actual key provisioning using PSA Crypto’s psa_import_key function. Provisioning a key calls the function to import the key:

• The metadata field from the JSON file is used for the function’s attributes argument.

• The value field is passed to the function’s data argument.

• The length of the value field is passed to the function’s data_length argument.

To provision keys onto the KMU, use the following nRF Util command, with the <snr> being the serial number of the device and <key-file> being the name of the key file in the JSON format:

nrfutil device x-provision-keys --serial-number <snr> --key-file <JSON-key-file>

You can call this command multiple times also to provision multiple keys, as long as each key has a different ID that is part of the metadata string.

For more information about this command, see the Provisioning cryptographic keys page in the nRF Util documentation.

Caution

The ERASEALL command destroys all keys stored on the device. Whenever you execute this boot command, you have to provision your keys all over again.