Provisioning the KMU

When you provision the KMU, you store one of the key types supported by the KMU and its metadata in the dedicated slot of RRAM. You can use the keys stored in the KMU to perform cryptographic operations using the CRACEN PSA Crypto driver, either for bootloader or for application purposes.

KMU prerequisites 

If you want to use the keys stored in the KMU using the CRACEN PSA Crypto driver, and especially if you want to handle KMU provisioning for production, you can configure several elements of the KMU slots:

SRC data struct fields for KMU provisioning
Field	Description
VALUE	The key material to be stored in the KMU slot.
RPOLICY	The revocation policy for the key.
DEST	For symmetric encryption/decryption keys, this is the CRACEN Protected RAM address. For asymmetric keys, this is a different RAM location according to usage.
METADATA	Information about the key type and its usage. It is required by the CRACEN driver for the verification of some properties of the key and its intended usage.

Make sure your configuration follows the device datasheet (for example, KMU - Key management unit for nRF54L15) and the CRACEN driver’s expectations. These expectations are different depending on the method you choose to provision keys to the KMU - see the following section.

Application prerequisites 

To use keys stored in the KMU with the CRACEN hardware peripheral and the CRACEN driver, configure the application with the required Kconfig options.

See Configuring Kconfig for information on how to set the required configuration options temporarily or permanently.

Complete the following steps to configure KMU and CRACEN support in your application:

Enable the nRF Security library by setting the CONFIG_NRF_SECURITY Kconfig option to y.
Enable the CRACEN driver by setting the CONFIG_PSA_CRYPTO_DRIVER_CRACEN Kconfig option to y.
Enable support for specific key usage schemes and cryptographic features. See Key types that can be stored in the KMU and Configuring cryptographic features for more information.

Prerequisites for the bootloader 

The bootloader can use multiple key generations for image verification (up to three for nRF54L SoCs). To safeguard against unauthorized provisioning by attackers, you must ensure that all of the key generations used by bootloader are provisioned.

Make sure to provision the relevant key sets before running bootloaders, including the first boot. Failure to do so can lead to unwanted actions by the bootloader on your firmware setup. You might experience the following issues:

The nRF Secure Immutable Bootloader (NSIB) might mark the image as permanently invalid without a key available for verification.

In direct-xip mode, MCUboot might delete the image if no appropriate key is provisioned.

The firmware might simply not boot, indicating a lack of proper key provisioning.

By default, MCUboot uses a single key. You can configure the number of key generations that MCUboot uses for application image verification with the MCUboot-specific CONFIG_BOOT_SIGNATURE_KMU_SLOTS Kconfig option.

NSIB for nRF54L SoCs supports generating and using three keys.

KMU provisioning methods 

You can perform KMU provisioning using the following methods:

KMU provisioning methods
Stage	Provisioning method	CRACEN driver expectations for the KMU slots
Development in the nRF Connect SDK	Provisioning KMU with development tools (west or nRF Util)	VALUE, RPOLICY, DEST, and METADATA are automatically calculated by software or tooling.
Development or production	Provisioning KMU with PSA Crypto API	VALUE, RPOLICY, DEST, and METADATA are automatically calculated by software or tooling.
Production	Provisioning KMU with production tools (tools for register-level programming)	You must manually set VALUE, RPOLICY, DEST, and METADATA according to the table in Setting up KMU metadata and destination addresses for production.

See the following sections for more information about each of these methods.

Generating keys 

You can generate keys using different methods and tools, depending on whether you are in development or in production. For example, you could generate the key on the device at the first reset (during production). You can also use OpenSSL, a Hardware Security Module (HSM), or other methods.

If you need a new key for development, you can generate it using imgtool or another tool that produces the required kind and format of key as a PEM file. For instructions on how to generate a key using imgtool, see the imgtool page in the MCUboot documentation.

See the following example for generating a private key:

imgtool keygen -k my_ed25519_priv_key.pem -t ed25519

Provisioning KMU with development tools 

You can use the following tools to provision keys to the device during development:

west command ncs-provision
nRF Util command nrfutil device x-provision-keys

Both methods allow to upload keys to the device through the Serial Write Debug (SWD) interface.

When you install the nRF Connect SDK, you get both the west command and the nRF Util tool with the nrfutil device command installed with the nRF Connect SDK toolchain bundle.

Provisioning keys to the board 

Before uploading keys, ensure that the SoC is unprovisioned. If the SoC has been previously provisioned and you need to use a different set of keys, you must first erase the SoC. You can use nRF Util’s device command for this purpose:

nrfutil device erase --all

Once you have an unprovisioned SoC, upload keys to the board by running one of the following commands:

  west ncs-provision upload -k ed25519.pem -k ed25519-1.pem -k ed25519-2.pem --keyname UROT_PUBKEY

Parameter -k (-–key) specifies the private key PEM files to be provisioned to the SoC. You can specify up to three keys.
Parameter --keyname specifies the key name for which the key PEM files will be uploaded.
Parameter --dev-id specifies the interface serial number and should be used if multiple J-link interfaces are connected to the development machine.
Parameter -p (--policy) specifies the policy applied to the given set of keys. You can apply the following options:
- lock-last - Uploads the last key as locked, while the preceding keys are revocable. This option is set by default.
- revokable - Enables revocation for each key.
- lock - Sets all keys to be permanent.
Parameter --build-dir specifies the path to a directory where a JSON file for nRF Util tool will be created. If this parameter is not provided, a temporary directory will be used instead.

Parameter -i (--input) specifies path to a YAML file that contains one or more key definitions intended for upload. This file can serve as a substitute for other parameters.

The YAML file should look as follows:

- keyname: UROT_PUBKEY
    keys: ["/path/private-key1.pem", "/path/private-key2.pem"]
    policy: lock
- keyname: APP_PUBKEY
    keys: ["/path/private-key3.pem", "/path/private-key4.pem"]
    policy: lock

Parameter --dry-run specifies that a command should generate a keyfile for nRF Util without actually executing the command.

The script generates the public key for each private key and uploads them to your device. These public keys generate the verification keys for the application image, which are then used by MCUboot for validation. The first key specified in the command is used for signing the application image. Currently, the script supports only ED25519 Keys.

For MCUboot, take note of the following:

UROT_PUBKEY is the key name used by MCUboot.
By default, it uses one key.
It might utilize multiple keys, which is intended for use with key revocation. The number of keys is defined by the CONFIG_BOOT_SIGNATURE_KMU_SLOTS MCUboot’s Kconfig option. You can enable the key revocation mechanism with the CONFIG_BOOT_KEYS_REVOCATION MCUboot’s Kconfig option.
KMU support in its configuration needs to be enabled by setting the SB_CONFIG_MCUBOOT_SIGNATURE_USING_KMU sysbuild Kconfig option. Otherwise, MCUboot will fallback to the compiled-in key.

For NSIB, take note of the following:

BL_PUBKEY is the key name used by NSIB.
It utilizes tree keys, which is intended for use with key revocation.
Keys must be provisioned before any run of the bootloader. For details, see Prerequisites for the bootloader.

To provision one key to the board, run the following command:

  west ncs-provision upload -k ed25519.pem --keyname UROT_PUBKEY

You can use the PSA Key Attributes generator script, similarly to nRF54H20, to generate the JSON file and the metadata from the PEM file you generated earlier.

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.

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.

Alternative provisioning method during development 

To simplify the development process, keys can be generated and then provisioned at the same time as the flashing process. You can provision keys during flashing when the build directory contains the keyfile.json file with commands, such as west flash --recover or west flash --erase. When flashing a project that contains NSIB, you can only use the west flash --recover, as the programming file contains UICR provisioning data as well.

You can generate the keyfile.json file during the build process (for example, when running west build) if the SB_CONFIG_SECURE_BOOT_GENERATE_DEFAULT_KMU_KEYFILE or SB_CONFIG_MCUBOOT_GENERATE_DEFAULT_KEY_FILE Kconfig options are enabled. These options enable, respectively, the NSIB and the MCUboot keys, included in the generated keyfile.json file. This file contains the necessary key provisioning information.

If you set the SB_CONFIG_SECURE_BOOT_SIGNING_KEY_FILE Kconfig option to a PEM key file, that specific file will be used. If not, the build will use the default key named GENERATED_NON_SECURE_SIGN_KEY_PRIVATE.pem, which is located in the build directory. Similarly, MCUboot uses the key file designated by the SB_CONFIG_BOOT_SIGNATURE_KEY_FILE option.

At the end of the described process, the keyfile.json file is generated in the build directory. This file allows key provisioning to occur simultaneously with the flashing process. Alternatively, you can bypass the mentioned Kconfig options and manually place a custom keyfile.json in the build directory.

Provisioning KMU with PSA Crypto API 

You can use the PSA Crypto API to create a provisioning image that provisions keys to the device during development or production.

Detailed steps for creating such a provisioning image for your application are beyond the scope of this guide. Use the guidelines in PSA Crypto API programming model for KMU keys and in the nRF54L Series Production Programming guide.

Provisioning KMU with production tools 

For production, provision the KMU data as described in the nRF54L Series Production Programming guide.

Nordic Semiconductor recommends using other tools than the ones used for provisioning for development. For example, you could use SEGGER J-Link or other debugging tools.

Using other tools means that you need to manually make sure that the values stored in the KMU slot’s METADATA field align with the CRACEN driver’s kmu_metadata data structure’s expectations for different key types. See the following section for more information.

Setting up KMU metadata and destination addresses for production 

The kmu_metadata structure is a 32-bit bitfield defined in the CRACEN driver source code (nrf/subsys/nrf_security/src/drivers/cracen/cracenpsa/src/cracen_psa_kmu.c):

typedef struct kmu_metadata {
	uint32_t metadata_version: 4;
	uint32_t key_usage_scheme: 2;
	uint32_t reserved: 8;
	uint32_t algorithm: 6;
	uint32_t size: 3;
	uint32_t rpolicy: 2;
	uint32_t usage_flags: 7;
} kmu_metadata;

When you configure psa_key_attributes_t, the CRACEN driver converts the attributes to KMU metadata (convert_from_psa_attributes()).

To make sure that this conversion is correct and the provisioning is successful, the key type used and the key you generated need to match the valid configuration ranges.

Common KMU provisioning configuration ranges

The following table shows common KMU provisioning configuration ranges for the nRF54L15 device. The values are provided for the KMU prerequisites (SRC data fields) mentioned at the beginning of this page. The table includes multiple KMU slots that work together for keys larger than 128 bits.

Example KMU provisioning configurations for nRF54L15
Use case	METADATA (KMU slot #0)	DEST (KMU slot #0)	VALUE (KMU slot #0)	RPOLICY (KMU slot #0)	METADATA (KMU slot #1)	DEST (KMU slot #1)	VALUE (KMU slot #1)	RPOLICY (KMU slot #1)
Ed25519 revocable signature verification key (raw public key)	`0x11BA0030`	`0x20000000`	key_data[0..15] inclusive	`0x00000003`	`0xffffffff`	`0x20000010`	key_data[16..31] inclusive	`0x00000003`
Ed25519 read-only signature verification key (raw public key)	`0x113A0030`	`0x20000000`	key_data[0..15] inclusive	`0x00000002`	`0xffffffff`	`0x20000010`	key_data[16..31] inclusive	`0x00000002`
Ed25519 deletable key (sign and verify)	`0x18BA0030`	`0x20000000`	key_data[0..15] inclusive	`0x00000001`	`0xffffffff`	`0x20000010`	key_data[16..31] inclusive	`0x00000001`
AES-CTR 128-bit protected decryption key (revocable)	`0x04960000`	`0x51810040` (protected key RAM)	key_data	`0x00000001`	N/A	N/A	N/A	N/A
AES-CTR 256-bit protected decryption key (revocable)	`0x04C60000`	`0x51810040` (protected key RAM)	key_data[0..15] inclusive	`0x00000001`	`0xffffffff`	`0x51810060` (protected key RAM + 16)	key_data[16..31] inclusive	`0x00000001`

Example conversion

The following example shows how the PSA key attribute values are converted when creating metadata for the Ed25519 revocable signature verification key:

User creates psa_key_attributes_t key attributes for the Ed25519 revocable verification key:

psa_key_attributes_t attr = PSA_KEY_ATTRIBUTES_INIT;
psa_set_key_type(&attr, PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_TWISTED_EDWARDS));
psa_set_key_bits(&attr, 255);
psa_set_key_algorithm(&attr, PSA_ALG_PURE_EDDSA);
psa_set_key_usage_flags(&attr, PSA_KEY_USAGE_VERIFY_HASH);
psa_set_key_lifetime(&attr, PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(
    CRACEN_KEY_PERSISTENCE_REVOKABLE, PSA_KEY_LOCATION_CRACEN_KMU));
psa_set_key_id(&attr, PSA_KEY_ID_FROM_CRACEN_KMU_SLOT(
    CRACEN_KMU_KEY_USAGE_SCHEME_RAW, 226));

The CRACEN driver convert_from_psa_attributes() function converts these PSA attributes to the following kmu_metadata field values:

Metadata fields for Ed25519 revocable verification key
Field	Value	Notes
`metadata_version`	`0`
`key_usage_scheme`	`3`	Raw, extracted from `key_id`
`reserved`	`0`
`algorithm`	`40`	Ed25519
`size`	`3`	255 bits
`rpolicy`	`3`	Revocable
`usage_flags`	`0b0001000`	Bit 3 set for Verify

The metadata bitfields are packed from least-significant bit to most-significant bit:

Bits  0-3:   metadata_version = 0        (0000)
Bits  4-5:   key_usage_scheme = 3        (11)
Bits  6-13:  reserved = 0                (00000000)
Bits 14-19:  algorithm = 40              (101000)
Bits 20-22:  size = 3                    (011)        # Maps to the kmu_metadata_key_bits enum; does not indicate key slots
Bits 23-24:  rpolicy = 3                 (11)
Bits 25-31:  usage_flags = 8             (0001000)

Binary representation:
00010001_10111010_00000000_00110000

Grouped by bytes (MSB first):
00010001 10111010 00000000 00110000

Hexadecimal: 0x11BA0030

The KMU provisioning is executed with the following KMU slot configuration:

KMU slot #0

Field	Value	Notes
METADATA	`0x11BA0030`	Primary KMU slot marker
DEST	`0x20000000`	`kmu_push_area` start address
VALUE	key_data[0..15]	First 16 bytes of the 32-byte Ed25519 public key
RPOLICY	`0x3`	Revocable

KMU slot #1

Field	Value	Notes
METADATA	`0xffffffff`	Secondary KMU slot marker
DEST	`0x20000010`	`kmu_push_area` + 16 bytes
VALUE	key_data[16..31]	Last 16 bytes of the 32-byte Ed25519 public key
RPOLICY	`0x3`	Revocable