tfm: Improve use-case for missing provisioning

Add documentation for TF-M provisioning and error messages for
missing provisioning with CONFIG_TFM_NRF_PROVISIONING.

Signed-off-by: Markus Lassila <[email protected]>

Author: MarkusLassila

doc/nrf/libraries/security/identity_key.rst

@@ -11,7 +11,7 @@ The identity key library manages an asymmetric key used for identity services on
 It's used to provision identity keys and can only be used by a Zephyr image in Secure Processing Environment (SPE).
 It is not supported from images for Non-Secure Processing Environment (NSPE), from a Trusted Firmware-M image, or from MCUboot.
 
-The identity key is equivalent to the Initial Attestation Key (IAK), as described in the ARM Platform Security Model 1.1, when Trusted Firmware-M (TF-M) is enabled.
+The identity key is equivalent to the Initial Attestation Key (IAK), as described in the `ARM Platform Security Model 1.1`_, when Trusted Firmware-M (TF-M) is enabled.
 TF-M has access to the identity key using internal APIs and does not need to use this library.
 
 Functionality

doc/nrf/links.txt

@@ -1417,6 +1417,7 @@
 .. _`GNU Arm Embedded Toolchain`: https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads
 .. _`IDAU`: https://developer.arm.com/docs/100690/latest/attribution-units-sau-and-idau
 .. _`ARM CoreSight`: https://developer.arm.com/documentation/100536/0302
+.. _`ARM Platform Security Model 1.1`: https://developer.arm.com/documentation/den0128/0101b/
 
 .. ### Source: etsi.org
 

doc/nrf/security/tfm.rst

@@ -126,6 +126,22 @@ By using the :kconfig:option:`CONFIG_TFM_SECURE_UART0`. the TF-M UART instance b
 
   When the TF-M and application use the same UART, the TF-M will disable logging after it has booted and it will only re-enable it again to log a fatal error.
 
+Provisioning
+************
+
+For the devices that need provisioning, TF-M implements the following Platform Root of Trust (PRoT) Security Lifecycle states that conform to the `ARM Platform Security Model 1.1`_:
+
+* Device Assembly and Test
+* PRoT Provisioning
+* Secured
+
+The device starts in the **Device Assembly and Test** state.
+The :ref:`provisioning_image` sample shows how to move the device from the **Device Assembly and Test** state to the **PRoT Provisioning** state, and how to provision the device with hardware unique keys (HUKs) and an identity key.
+
+To move the device from the **PRoT Provisioning** state to the **Secured** state, set the :kconfig:option:`CONFIG_TFM_NRF_PROVISIONING` Kconfig option for your application.
+In the first boot, TF-M will ensure that the keys are stored in the Key Management Unit (KMU) and move the device to the **Secured** state.
+The :ref:`tfm_psa_template` sample shows how to achieve this.
+
 .. _ug_tfm_manual_VCOM_connection:
 
 Manual connection to Virtual COM ports on the nRF5340 DK

modules/trusted-firmware-m/Kconfig

@@ -468,8 +468,8 @@ config TFM_NRF_PROVISIONING
 	select SECURE_BOOT_STORAGE
 	help
 	  Provision the TF-M image. When enabled, TF-M must be in the PSA
-	  provisioning lifecycle state in order to boot. See provisioning
-	  guide for more details.
+	  provisioning lifecycle state in order to boot. Find more information
+	  about provisioning in Running applications with Trusted Firmware-M.
 
 config TFM_PSA_FRAMEWORK_HAS_MM_IOVEC
 	bool

modules/trusted-firmware-m/tfm_boards/common/tfm_hal_platform.c

@@ -147,6 +147,8 @@ enum tfm_hal_status_t tfm_hal_platform_init(void)
 	enum tfm_security_lifecycle_t lcs = tfm_attest_hal_get_security_lifecycle();
 
 	if (lcs != TFM_SLC_PSA_ROT_PROVISIONING && lcs != TFM_SLC_SECURED) {
+		SPMLOG_ERRMSGVAL("Invalid LCS: ", lcs);
+		SPMLOG_DBGMSG("Ensure that the device has been provisioned.\r\n");
 		return TFM_HAL_ERROR_BAD_STATE;
 	}
 #endif /* defined(NRF_PROVISIONING) */

samples/tfm/provisioning_image/README.rst

@@ -11,7 +11,7 @@ Running the provisioning image sample will initialize the provisioning process o
 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).
+For more information about the PRoT security lifecycle, see `ARM Platform Security Model 1.1`_.
 
 When built for the nrf5340dk/nrf5340/cpuapp target, this image by default also includes the :ref:`provisioning_image_net_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.
@@ -34,7 +34,7 @@ The sample also requires the following libraries to generate and store the maste
 Overview
 ********
 
-The PSA security model defines the PRoT security lifecycle states.
+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.