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’s Platform Security Model 1.1 defined in the Platform Security Architecture (PSA).

When built for the nrf5340dk/nrf5340/cpuapp target, this image by default also includes the TF-M: Provisioning image for network core sample as a child image for the network core (nrf5340dk/nrf5340/cpunet target). The child image demonstrates how to disable the debugging access on the network core by writing to the UICR.APPROTECT register.

Requirements

The following development kits are supported:

Hardware platforms

PCA

Board name

Board target

nRF9161 DK

PCA10153

nrf9161dk

nrf9161dk/nrf9161

nRF9160 DK

PCA10090

nrf9160dk

nrf9160dk/nrf9160

nRF9151 DK

PCA10171

nrf9151dk

nrf9151dk/nrf9151

nRF5340 DK

PCA10095

nrf5340dk

nrf5340dk/nrf5340/cpuapp

The sample also requires the following libraries to generate and store the master key encryption key (MKEK) and the identity key into the key management unit (KMU):

Note

Once the required identity key is provisioned on the device, the UICR should not be erased by ERASEALL for example, as that removes the identity key from the system.

Overview

The 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:

  1. The device is verified to be in the Device Assembly and Test state.

  2. The device is transitioned to the PRoT Provisioning state.

  3. Random hardware unique keys (HUKs) are generated and stored in the key management unit (KMU).

  4. A random identity key of type secp256r1 is generated and stored in the KMU.

  5. The identity key is verified to be stored in the KMU.

The hardware unique keys (HUKs) include the master key encryption key (MKEK) and the master key for encrypting external storage (MEXT).

The identity key is stored in the KMU in encrypted form using the master key encryption key (MKEK). The identity key is used as the Initial Attestation Key (IAK) as described in the PSA security model.

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.

Testing

After programming the sample, the following output is displayed in the console:

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!

If an error occurs, the sample prints a message and raises a kernel panic.

Note

The device cannot transition from the PRoT security lifecycle state PRoT Provisioning to the Device Assembly and Test state. To reproduce the sample, you must program the device with the --erase option to erase the flash memory.

Dependencies

The following libraries are used: