Hardware unique key
The hardware unique key library manages symmetric root keys on devices with the Arm CryptoCell security subsystem.
Functionality
Hardware unique keys (HUKs) are device-specific keys that you can use with functions for key derivation to generate other keys. Applications can use the generated keys for symmetric cryptographic operations. By using HUKs, you can let your application use multiple keys without having to store them on the device, as they can be derived from a HUK, using a static label, when needed.
Caution
Use hardware unique keys only for key derivation, never directly for symmetric cryptographic operations.
The nRF Connect SDK supports the following types of HUKs through this library:
HUK type |
Purpose |
Storage location |
Additional notes |
|---|---|---|---|
Master Key Encryption Key (MKEK) |
Deriving Key Encryption Keys (KEKs) for encrypting Internal Trusted Storage (ITS) entries |
- Provided to CryptoCell when it is used
|
Recommended for nRF91 Series devices and nRF5340 |
Master Key for External Storage (MEXT) |
Deriving keys for encrypting data in external non-secure storage (flash) or Protected Storage |
- Provided to CryptoCell when it is used
|
Recommended for nRF91 Series devices and nRF5340 |
CRACEN Isolated Key Generator (IKG) |
Deriving special hardware keys for CRACEN operations |
- Regenerated on each CRACEN power cycle from the IKG seed
- Supported on nRF54L Series devices; see CRACEN Isolated Key Generator
|
|
Device Root Key (KDR) |
Deriving general-purpose keys |
Non-volatile memory locked by ACL |
- Should be written to CryptoCell by the bootloader using the
hw_unique_key_load_kdr() function.The nRF Secure Immutable Bootloader does this automatically if you enable
CONFIG_HW_UNIQUE_KEY in the bootloader image.- Supported on and recommended for nRF52840
|
See the following table for an overview of the key types supported by each device:
Device |
Driver version |
Key Management Unit |
Supported HUK types |
|---|---|---|---|
nRF91 Series |
CryptoCell CC310 |
Yes |
KDR, MKEK, MEXT |
nRF54L Series |
CRACEN |
Yes |
MKEK, MEXT, IKG |
nRF5340 |
CryptoCell CC312 |
Yes |
MKEK, MEXT |
nRF52840 |
CryptoCell CC310 |
No |
KDR only |
In devices with a Key Management Unit (KMU), the keys are either derived or reside in reserved slots in the KMU itself. The KMU can make the keys non-readable and non-writable from the application, while still accessible by the Arm CryptoCell or CRACEN. On the nRF54L Series devices, the keys are derived from the HUKs by the CRACEN driver using the IKG seed.
In devices without a KMU, like nRF52840, the bootloader writes the key to the Arm CryptoCell and locks the flash memory page where the key is stored. In this case, only one key is supported.
Prerequisites
To use hardware unique keys, you must first write them to the KMU or program them in the device firmware if no KMU is present.
You can also write the HUKs by programming the device with a debugger.
See tests/lib/hw_unique_key_tfm/write_kmu.py for an example of programming the KMU with a debugger.
Usage
The library provides a function for writing arbitrary keys and a function for writing random keys.
To use the library, enable the CONFIG_HW_UNIQUE_KEY option for the nRF Secure Immutable Bootloader image.
Additionally, you can enable the CONFIG_HW_UNIQUE_KEY_RANDOM option to enable the hw_unique_key_write_random() function and its dependencies, to generate random keys.
See Configuring and building for information on how to enable the required configuration options.
You can then use the HUKs through the APIs in the CC3xx platform libraries.
You can also derive a key using hw_unique_key_derive_key().
Caution
It is strongly recommended to generate random keys on-chip to avoid any outside knowledge of the keys. If the application needs a specific key that the manufacturer also knows, and this key is also unique to the device, do not provide such a key as a HUK. Instead, encrypt this key with another key derived from a hardware unique key, or store it in its own KMU slot.
API documentation
include/hw_unique_key.hmodules/lib/hw_unique_key/