TF-M: Provisioning image
Running the provisioning image sample will initialize the provisioning process of a device in a manner compatible with Trusted Firmware-M (TF-M). This sample does not include a TF-M image, it is a Zephyr image intended to be flashed, run, and erased before the TF-M image is flashed.
After completion, the device is in the Platform Root-of-Trust (PRoT) security lifecycle state called PRoT Provisioning. For more information about the PRoT security lifecycle, see ARM Platform Security Model 1.1.
When built for the nrf5340dk/nrf5340/cpuapp board target, this image by default also includes the TF-M: Provisioning image for network core sample as an image for the network core (nrf5340dk/nrf5340/cpunet board target).
The image demonstrates how to disable the debugging access on the network core by writing to the UICR.APPROTECT register.
Relationship to the TF-M application
Provisioning is a one-time operation that must be completed before a TF-M application (such as TF-M: PSA template) runs for the first time. It generates and stores the device-unique key material (on nRF54L Series devices, the CRACEN IKG seed) and advances the PSA security lifecycle state from Device Assembly and Test to PRoT Provisioning. Because this step generates secret key material and permanently changes the lifecycle state, it is delivered as a dedicated image rather than built into the application.
Keeping provisioning in a separate image lets you:
Provision devices in a secure or otherwise controlled environment (for example, a trusted production line), and program the application firmware later in a different, less-trusted environment.
Erase and re-provision a development device without rebuilding the application.
The typical development flow is:
Build this provisioning image, flash it, and let it run once (see Building and running). The device transitions to the PRoT Provisioning state.
Build and flash your TF-M application, for example TF-M: PSA template. On the first boot, TF-M completes provisioning by advancing the lifecycle state to Secured.
On nRF54L Series devices, applications such as TF-M: PSA template build this provisioning image for you by default as a build-only sub-image, which is the recommended way to provision the device when building those applications. Building the provisioning image standalone, as described here, is mainly useful for provisioning devices independently of the application. See Provisioning image built with the application (nRF54L).
Note
After the device has been provisioned, program the application with a plain west flash command.
Using --erase or --recover wipes the provisioned keys and lifecycle state, and you must repeat the provisioning step.
Requirements
The following development kits are supported:
Hardware platforms |
PCA |
Board name |
|
|---|---|---|---|
PCA10153 |
|
||
PCA10090 |
|
||
PCA10171 |
|
||
PCA10188 |
|
||
PCA10184 |
|
||
PCA10156 |
|
||
PCA10095 |
|
The sample requires Hardware unique key. On nRF5340 and nRF91x Series devices, it also requires Identity key.
On nRF54L Series devices, no separate identity key is stored. The Initial Attestation Key (IAK) is sourced from CRACEN.
Note
After provisioning, do not erase the OTP (for example, by using ERASEALL).
Erasing the OTP removes the provisioned keys and lifecycle state.
Overview
The Platform Security Architecture (PSA) security model defines the PRoT security lifecycle states. This sample performs the transition from the PRoT security lifecycle state Device Assembly and Test to the PRoT Provisioning state.
PRoT Provisioning is a state where the device platform security parameters are generated. This enables a TF-M image to transition to the PRoT security lifecycle state Secured at a later stage.
The sample performs the following operations:
The device is verified to be in the Device Assembly and Test state.
The device is transitioned to the PRoT Provisioning state.
Hardware unique key (HUK) material is provisioned:
On nRF5340 and nRF91x Series devices, random MKEK and MEXT keys are generated and stored in the key management unit (KMU).
On nRF54L Series devices, the system writes a random IKG seed to CRACEN KMU slots 183-185. MKEK, MEXT, and other HUK-derived keys are not stored. Instead, CRACEN IKG derives these keys on demand from the seed.
On nRF5340 and nRF91x Series devices, the system generates a random secp256r1 identity key. The system stores this key in the KMU, encrypted with the MKEK, and uses it as the Initial Attestation Key (IAK).
On nRF54L Series devices, the IAK is the identity key of the CRACEN IKG. The system does not write a separate identity key. For more information about how TF-M uses the IAK, see PSA Attestation API.
The implementation ID is written to OTP.
On nRF54L Series devices, nRF Secure Immutable Bootloader (NSIB, also called b0) validates firmware against a key stored in the CRACEN KMU, rather than in the OTP PROVISION region used on nRF5340.
This NSIB public key corresponds to the application’s signing key, so it is provisioned from a keyfile.json generated by the application build (for example, TF-M: PSA template), not by this sample.
The west flash --recover command uses that file with nrfutil device x-provision-keys to write the NSIB Ed25519 public key to KMU slot 242 before b0 runs for the first time.
Configuration
See Configuring and building for information about how to permanently or temporarily change the configuration.
Building and running
This sample can be found under samples/tfm/provisioning_image in the nRF Connect SDK folder structure.
To build the sample, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.
Note
When building repository applications in the SDK repositories, building with sysbuild is enabled by default.
If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.
On nRF54L Series devices, the NSIB public key must also be provisioned to the CRACEN KMU before the application can boot.
Because this key belongs to the application, provision it from the application build rather than from a standalone build of this sample.
The recommended flow builds this provisioning image together with the application and flashes it with west flash --recover, using the keyfile.json generated by the application.
See Provisioning image built with the application (nRF54L).
If the provisioned key does not match the key used to sign the image chain, b0 rejects MCUboot with error -102 (ESIGINV).
Testing
After programming the sample, the following output is displayed in the console on nRF5340 and nRF91x Series devices:
Successfully verified PSA lifecycle state ASSEMBLY!
Successfully switched to PSA lifecycle state PROVISIONING!
Generating random HUK keys (including MKEK)
Writing the identity key to KMU
Success!
On nRF54L Series devices, the identity key step is omitted:
Successfully verified PSA lifecycle state ASSEMBLY!
Successfully switched to PSA lifecycle state PROVISIONING!
Generating random HUK keys (including MKEK)
Success!
If an error occurs, the sample logs a Failure: ... message describing the failed step and stops without printing Success!.
Note
The device cannot transition from PRoT Provisioning back to Device Assembly and Test.
To run the sample again, reset the OTP by using west flash --erase (nRF5340 and nRF91x Series) or west flash --recover (nRF54L Series).
Both operations wipe all provisioned keys, so you must repeat the full sequence.
Dependencies
The following libraries are used:
Identity key (nRF5340 and nRF91x only)