nRF54L Series cryptography

The cryptographic peripherals of the nRF54L Series are supported through a set of standard PSA Crypto APIs, with some additional vendor-specific extensions.

The nRF Security library offers a set of nRF Security drivers. On the nRF54L devices, in addition to the nrf_oberon driver covering the software-based cryptography implementations, the CRACEN driver (nrf_cracen) provides entropy and hardware-accelerated cryptography using the Crypto Accelerator Engine (CRACEN) peripheral. The CRACEN PSA driver supports the following:

  • Executing cryptographic operations using the CRACEN peripheral.

  • Importing, using, and revoking keys stored in the Key Management Unit (KMU).

  • Pushing symmetric keys directly from the KMU to the CRACEN symmetric engine, without exposing the key material to the CPU.

  • Using isolated keys derived from CRACEN’s Isolated Key Generator (IKG) for encryption and signing purposes.

The keys that are stored in the KMU or generated by the IKG are referenced using the built-in keys that are key IDs in the range from MBEDTLS_PSA_KEY_ID_BUILTIN_MIN to and including MBEDTLS_PSA_KEY_ID_BUILTIN_MAX.

KMU and CRACEN peripherals

The nRF54L Series Crypto Accelerator Engine (CRACEN) and the Key Management Unit (KMU) peripherals, along with the CRACEN PSA driver, are central when ensuring that the assets of an nRF54L device are protected. While CRACEN is not accessed by the CPU and typically not directly used by the end-users and their applications, the KMU provides operations to import, use, revoke, and/or delete assets. Only the KMU is able to push assets to CRACEN’s protected RAM and the SEED register.

The KMU can store cryptographic keys and 384-bit random seeds for the IKG in key storage slots. The CRACEN PSA driver exposes the KMU operations through standard PSA Crypto API calls, with some vendor-specific extensions. The following KMU operations are supported:

  • Importing/provisioning keys to KMU slots.

  • Deleting a key from the KMU, allowing the underlying storage location to be reused.

  • Revoking a key from the KMU, preventing reuse of the underlying key slots.

  • Directly pushing symmetric keys to CRACEN’s engine for symmetric crypto operations, without exposing the key material to the CPU.

  • Directly pushing a 384-bit seed to CRACEN’s IKG to derive isolated keys.

  • Pushing asymmetric keys to CPU RAM before loading them into CRACEN’s engine for asymmetric operations.

Additionally, the CRACEN PSA driver supports storing encrypted keys in KMU slots, transparently decrypting them to a temporary RAM location before using them in cryptographic operations.

KMU slots

The KMU is partitioned into 256 numbered slots, each capable of storing 128 bits of key material, a 32-bit target push address and 32 bits of metadata. Storing keys that are larger than 128 bits is supported by using multiple, consecutive slots.

The application can use the KMU slots to store key data for their own purposes. Some KMU slots are reserved for current and future nRF Connect SDK use cases. The following table gives an overview of the KMU slots and their usage:

List of reserved KMU slots
Reserved KMU slots
(range inclusive)
nRF Connect SDK usage
Description

180-182

Reserved

–

183-185

IKG seed

384-bit random seed to generate keys using the CRACEN IKG.

186-225

Reserved

–

226-227

UROT_PUBKEY_0
Revokable firmware image key for upgradable bootloader, generation 0.
ED25519 public key.

228-229

UROT_PUBKEY_1
Revokable firmware image key for upgradable bootloader, generation 1.
ED25519 public key.

230-231

UROT_PUBKEY_2
Revokable firmware image key for upgradable bootloader, generation 2.
ED25519 public key.

232-241

Reserved

–

242-243

BL_PUBKEY_0
Revokable firmware image key for immutable bootloader, generation 0.
ED25519 public key.

244-245

BL_PUBKEY_1
Revokable firmware image key for immutable bootloader, generation 1.
ED25519 public key.

246-247

BL_PUBKEY_2
Revokable firmware image key for immutable bootloader, generation 2.
ED25519 public key.

248-255

Reserved

–

CRACEN Isolated Key Generator

CRACEN’s Isolated Key Generator (IKG) can derive three keys from a 384-bit seed value.

IKG-generated keys are also called special hardware keys. These keys are typically not meant for application use. They are not accessible by any CPU, but they can be used for cryptographic operations by CRACEN, provided directly to the cryptographic engine as a hardware signal. IKG keys are not retained, and have to be regenerated for every CRACEN power cycle.

The 384-bit seed value is provisioned to the device or generated automatically during the first boot of the device using the CRACEN Random Number Generator (RNG), and then stored in the KMU. Before the keys can be generated, the seed is pushed by the KMU to the SEED register, and then validated. Generating keys without the valid seed will fail.

IKG keys are also accessed using the standard PSA Crypto APIs, and are referenced by special built-in key IDs.

Key type

Key ID

Description

ECC secp256r1

CRACEN_BUILTIN_IDENTITY_KEY_ID

Used for signing/verification.

AES 256-bit

CRACEN_BUILTIN_MKEK_ID

Used for encryption/decryption or key derivation.

AES 256-bit

CRACEN_BUILTIN_MEXT_ID

Used for encryption/decryption or key derivation.

The keys are not exportable, except for the public key associated with the asymmetric key.

Programming model for referencing keys

The keys which are stored in the KMU can be used by most cryptographic functions and key management functions in the PSA Crypto API (see PSA Certified Crypto API 1.2.1), with a built-in key ID representing a particular KMU slot.

To identify that the KMU is used as a persistent storage backend for a specific psa_key_id_t, you need to create a psa_key_attributes_t structure and set the required attributes from the list below.

Attribute (setter function)

Parameters

Description

key_type (psa_set_key_type)

A supported key type.

Sets the key type and size.

See Supported key types for overview of the supported key types for each driver.

key_bits (psa_set_key_bits)

A supported key size for the key type.

Sets the key type and size.

See Supported key types for overview of the supported key types for each driver.

key lifetime (psa_set_key_lifetime)

PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(persistence, location) where persistence is set to one of the following: PSA_KEY_PERSISTENCE_DEFAULT, PSA_KEY_PERSISTENCE_READ_ONLY, CRACEN_KEY_PERSISTENCE_REVOKABLE, and location must be PSA_KEY_LOCATION_CRACEN_KMU

CRACEN_KEY_PERSISTENCE_REVOKABLE is a custom persistence mode, which will revoke the key slots when the key is destroyed.

PSA_KEY_PERSISTENCE_DEFAULT should be used by applications that have no specific needs beyond what is met by implementation-specific features.

PSA_KEY_PERSISTENCE_READ_ONLY is for read-only or write-once keys. A key with this persistence level cannot be destroyed. Keys that are read-only due to policy restrictions, rather than physical limitations, should not have this persistence level.

key_id (psa_set_key_id)

PSA_KEY_HANDLE_FROM_CRACEN_KMU_SLOT(kmu_usage_scheme, kmu_slot_nr)

For correct kmu_usage_scheme values, see KMU key usage schemes.

For correct kmu_slot_nr values, see KMU slots.

key_usage (psa_set_key_usage_flags)

Standard PSA Crypto key usage flags

PSA_KEY_USAGE_EXPORT and PSA_KEY_USAGE_COPY are not allowed for keys with the usage scheme CRACEN_KEY_USAGE_SCHEME_PROTECTED.

KMU key usage schemes

To see what key types are supported with Protected, Encrypted and Raw usage schemes, refer to the table under Supported key types.

The following list shows available schemes that determine how the keys are used:

Scheme name

Macro name

Description

Protected

CRACEN_KMU_KEY_USAGE_SCHEME_PROTECTED

The keys will be pushed to a RAM only accessible by the CRACEN.

Encrypted

CRACEN_KMU_KEY_USAGE_SCHEME_ENCRYPTED

The keys are encrypted, and are decrypted on-the-fly to a CPU-accessible RAM location before being used by the CRACEN.

Encrypted keys require two additional KMU slots to store the authentication nonce and tag.

Raw

CRACEN_KMU_KEY_USAGE_SCHEME_RAW

The keys are stored as plain text and pushed to a CPU-accessible RAM location before being used by the CRACEN.

Seed

CRACEN_KMU_KEY_USAGE_SCHEME_SEED

The slots will be pushed to CRACEN’s SEED registers.

This scheme is typically not meant for the application use.

It is only used for the platform keys, CRACEN_BUILTIN_IDENTITY_KEY_ID, CRACEN_BUILTIN_MKEK_ID or CRACEN_BUILTIN_MEXT_ID.

Supported key types

The following table lists all key types that can be stored in the KMU, indicating which usage schemes (Protected, Encrypted, and Raw) support them and the number of key slots they require.

Supported key types

Key type

PSA key attributes

KMU slots [1]

Protected

Encrypted

Raw

AES 128-bit keys
key_type: PSA KEY_TYPE_AES
key_bits: 128

1

Yes

Yes

Yes

AES 192-bit and 256-bit keys
key_type: PSA_KEY_TYPE_AES
key_bits: 192
key_bits: 256

2

Yes

Yes

Yes

ChaCha20-Poly1305

key_type: PSA_KEY_TYPE_CHACHA20

2

No

Yes

Yes

ECC secp256r1 key pair
key_type: PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1)
key_bits: 256

2

No

Yes

Yes

ECC secp256r1 public key
key_type: PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_SECP_R1)
key_bits: 256

4

No

Yes

Yes

Ed25519 key pair
key_type: PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_TWISTED_EDWARDS)
key_bits: 255

2

No

Yes

Yes

ED25519 public key
key_type: PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_TWISTED_EDWARDS)
key bits: 255

2

No

Yes

Yes

Storing keys in KMU

Applications can store keys in KMU slots using the standard PSA cryptographic key management operations psa_import_key, psa_generate_key or psa_copy_key. Additionally, the KMU slots can be provisioned using the nRF Util development tool.

Note

If a power failure occurs during provisioning of a key with persistence PSA_KEY_PERSISTENCE_READ_ONLY or CRACEN_KEY_PERSISTENCE_REVOKABLE, it might not be possible to recover the key slot. Provisioning of read-only keys should be restricted to controlled environments (production environments).

You might encounter the following KMU-specific error codes when storing keys in KMU:

  • PSA_ERROR_ALREADY_EXIST: One of the required key slots has already been provisioned.

  • PSA_ERROR_NOT_SUPPORTED: Unsupported key type.

Removing or revoking keys from KMU

Keys are deleted or revoked using the psa_destroy_key function. Calling the psa_destroy_key function on keys that have the persistence CRACEN_KEY_PERSISTENCE_REVOKABLE, will mark the associated KMU slots as revoked, preventing the slots from being reused for new keys.

Using KMU keys

Keys stored in the KMU can be used in standard PSA cryptographic operations for encryption, decryption, signing a hash or a message, and verifying a hash or a message, given that the corresponding PSA_KEY_USAGE_* flags are set.

Keys with the usage schemes Protected (CRACEN_KMU_KEY_USAGE_SCHEME_PROTECTED) and Seed (CRACEN_KMU_KEY_USAGE_SCHEME_SEED) can push data from the slots directly to CRACEN registers that are not accessible by the CPU. These usage schemes are supported for pushing symmetric keys used for cipher operations, and for seeds used by the CRACEN IKG.

Keys with the usage scheme Raw (CRACEN_KMU_KEY_USAGE_SCHEME_RAW), such as symmetric keys, are temporarily pushed to a RAM location by the CRACEN driver, and then loaded by CRACEN into the asymmetric engine before running operations like sign or verify.

Key slots with the usage scheme Encrypted (CRACEN_KMU_KEY_USAGE_SCHEME_ENCRYPTED) also have to be decrypted to a temporary push location in RAM before they are used by CRACEN, which is handled by the CRACEN driver.

When the application is built with TF-M, this temporary push location is protected inside the secure processing environment to avoid exposing the key material to the non-secure application. If TF-M is not used, the keys are pushed to a reserved RAM area at location 0x20000000-0x20000064 (kmu_push_area).

You might encounter the following KMU-specific error codes when using the KMU keys:

  • PSA_ERROR_INVALID_HANDLE: Attempting an operation on an empty KMU slot.

  • PSA_ERROR_NOT_PERMITTED: Attempting an operation on a revoked key.

  • PSA_ERROR_HARDWARE_FAILURE: The key slot has invalid data.

  • PSA_ERROR_CORRUPTION_DETECTED: The key slot has invalid data.

Configuration

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

The CRACEN peripheral does not require any configuration. Its operation is ensured by hardware.

The following Kconfig options are used to enable support for KMU:

The following code block shows how KMU support is enabled:

CONFIG_NRF_SECURITY=y
CONFIG_MBEDTLS_PSA_CRYPTO_C=y
CONFIG_PSA_CRYPTO_DRIVER_CRACEN=y

As an example, enabling support for the Encrypted key usage scheme (CRACEN_KMU_KEY_USAGE_SCHEME_ENCRYPTED) is done using the following Kconfig options:

Enabling support for the Encrypted key usage scheme looks as shown in the following code block:

CONFIG_PSA_WANT_KEY_TYPE_AES=y
CONFIG_PSA_WANT_AES_KEY_SIZE_256=y
CONFIG_PSA_WANT_ALG_ECB_NO_PADDING=y
CONFIG_PSA_WANT_ALG_CMAC=y
CONFIG_PSA_WANT_ALG_SP800_108_COUNTER_CMAC=y
CONFIG_PSA_WANT_ALG_GCM=y

The configuration is enabling the key type (AES) and the key size (256 bits) supported by the Encrypted usage scheme as explained in the Supported key types section, and in addition enabling the following cryptographic features supported by the CRACEN driver:

  • Cipher mode: AES ECB (Electronic CodeBook) mode, no padding

  • Message Authentication Code (MAC) cipher: cipher-based MAC (CMAC) cipher

  • Key derivation function (KDF) support: SP800-108 CMAC in counter mode

  • Authenticated Encryption with Associated Data (AEAD) cipher: GCM (Galois Counter Mode) cipher