Skip to content

Commit

Permalink
doc: tfm: Restructure sections
Browse files Browse the repository at this point in the history 
Move building, configuring and limitations to
appear before background information on TF-M user
guide.

Signed-off-by: Seppo Takalo <[email protected]>
  • Loading branch information
@SeppoTakalo
SeppoTakalo committed Dec 17, 2024
1 parent a953d90 commit 19703da
Showing 1 changed file with 104 additions and 104 deletions.
208 changes: 104 additions & 104 deletions doc/nrf/security/tfm.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,21 @@ The TF-M implementation in |NCS| is demonstrated in the following samples:

In addition, the TF-M implementation is used in all samples and applications in this SDK that support the ``*/ns`` :ref:`variant <app_boards_names>` of the boards, due to :ref:`Cortex-M Security Extensions (CMSE) <app_boards_spe_nspe>` support.

Limitations
===========

The following limitations apply to TF-M and its usage:

* Firmware Update service is not supported.
* The following crypto modules or ciphers are not supported:

* AES output feedback (AES-OFB) mode.
* AES cipher feedback (AES-CFB) mode.

* Isolation level 3 is not supported.
* In Isolation level 2 or higher, the number of peripherals configured as secure in Application Root of Trust (ARoT) is limited by the number of available MPU regions.
* Nordic Semiconductor devices only support the GCC toolchain for building TF-M.

Building
********

Expand Down Expand Up @@ -152,114 +167,12 @@ TF-M is linked as a separate partition in the final binary image. The reserved s
These configuration option allows you to specify the size allocated for the TF-M partition in the final binary image. Default partition sizes vary between device families and are not optimized to any specific use case.

Process to optimize the TF-M size is to first find the minimal set of features to satisfy the application needs and then minimize the allocated partition sizes while still conforming to the alignment and granularity requirements of given hardware.
See :ref:`ug_tfm_partition_alignment_requirements` for more information about the alignment requirements.


.. _tfm_encrypted_its:

Encrypted ITS
=============

TF-M implements a PSA internal trusted storage (ITS) with encryption and authentication.
For more information about the general features of the TF-M ITS service, see `TF-M ITS`_.

To enable TF-M ITS encryption, use the Kconfig option :kconfig:option:`CONFIG_TFM_ITS_ENCRYPTED`.
The ITS encryption is transparent to the user as long as the Master Key Encryption Key (MKEK) is populated before use.

On Nordic Semiconductor devices, the hardware-accelerated AEAD scheme ChaChaPoly1305 is used with a 256 bits key.
This key is derived with a key derivation function (KDF) based on NIST SP 800-108 CMAC.
The input key of the KDF is the MKEK, a symmetric key stored in the Key Management Unit (KMU) of Nordic Semiconductor devices.
The MKEK is protected by the KMU peripheral and its key material cannot be read by software. It can only be used by reference.

The file ID is used as a derivation label for the KDF.
This means that each file ID uses a different AEAD key.
As long as each file has a unique file ID, the key used for encryption and authentication is unique.

To strengthen data integrity, the metadata of the ITS file (creation flags/size) is used as authenticated data in the encryption process.

The nonce for the AEAD operation is generated by concatenating a random 8-byte seed and an increasing 4-byte counter.
The random seed is generated once in the boot process and stays the same until reset.

Logging
*******

TF-M employs two UART interfaces for logging: one for the secure part (MCUboot and TF-M), and one for the non-secure application.
By default, the logs arrive on different COM ports on the host PC.
See the :ref:`ug_tfm_manual_VCOM_connection` for more details.

Alternatively, you can configure the TF-M to connect to the same UART as the application by using the :kconfig:option:`CONFIG_TFM_SECURE_UART0` Kconfig option.
Setting this Kconfig option makes TF-M logs visible on the application's VCOM, without manual connection.

The UART instance used by the application is ``0`` by default, and the TF-M UART instance is ``1``.
By using the :kconfig:option:`CONFIG_TFM_SECURE_UART0`. the TF-M UART instance becomes the same as that of the application's.

.. note::

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
=========================================================

By default, the nRF5340 DK v1.0.0 requires that you connect specific wires on the kit to receive secure logs on the host PC.
Specifically, wire the pins **P0.25** and **P0.26** of the **P2** connector to **RxD** and **TxD** of the **P24** connector respectively.
See :ref:`logging_cpunet` on the Working with nRF5340 DK page for more information.

On the nRF5340 DK v2.0.0, there are only two virtual COM ports available.
By default, one of the ports is used by the non-secure UART0 peripheral from the application and the other by the UART1 peripheral from the network core.

There are several options to get UART output from the secure TF-M:

* Disable the output for the network core and change the pins used by TF-M.
The network core will usually have an |NCS| child image.
To configure a child image, see Configuration of the child image section described in :ref:`ug_nrf5340_multi_image`.
To configure logging in an |NCS| image, see :ref:`ug_logging`.
To change the pins used by TF-M, the RXD (:kconfig:option:`CONFIG_TFM_UART1_RXD_PIN`) and TXD (:kconfig:option:`CONFIG_TFM_UART1_TXD_PIN`) Kconfig options in the application image can be set to **P1.00** (32) and **P1.01** (33).

* The secure and non-secure UART peripherals can be wired to the same pins.
Specifically, physically wire together the pins **P0.25** and **P0.26** to **P0.20** and **P0.22**, respectively.

* If the non-secure application, network core and TF-M outputs are all needed simultaneously, additional UART <-> USB hardware is needed.
A second nRF DK can be used if available.
Pin **P0.25** needs to be wired to the TXD pin, and **P0.26** to the RXD pin of the external hardware.
These pins will provide the secure TF-M output, while the two native COM ports of the DK will be used for the non-secure application and the network core output.

Limitations
***********

The following limitations apply to TF-M and its usage:

* Firmware Update service is not supported.
* The following crypto modules or ciphers are not supported:

* AES output feedback (AES-OFB) mode.
* AES cipher feedback (AES-CFB) mode.

* Isolation level 3 is not supported.
* In Isolation level 2 or higher, the number of peripherals configured as secure in Application Root of Trust (ARoT) is limited by the number of available MPU regions.
* Nordic Semiconductor devices only support the GCC toolchain for building TF-M.
See next section for more information about the alignment requirements.

.. _ug_tfm_partition_alignment_requirements:

TF-M partition alignment requirements
*************************************
=====================================

TF-M requires that secure and non-secure partition addresses must be aligned to the flash region size :kconfig:option:`CONFIG_NRF_TRUSTZONE_FLASH_REGION_SIZE`.
|NCS| ensures that they in fact are aligned and comply with the TF-M requirements.
Expand Down Expand Up @@ -339,3 +252,90 @@ We will decrease the size of the (optional) ``mcuboot_pad`` partition and thus t
app:
address: 0x8000
size: 0x4000
.. _tfm_encrypted_its:

Encrypted ITS
*************

TF-M implements a PSA internal trusted storage (ITS) with encryption and authentication.
For more information about the general features of the TF-M ITS service, see `TF-M ITS`_.

To enable TF-M ITS encryption, use the Kconfig option :kconfig:option:`CONFIG_TFM_ITS_ENCRYPTED`.
The ITS encryption is transparent to the user as long as the Master Key Encryption Key (MKEK) is populated before use.

On Nordic Semiconductor devices, the hardware-accelerated AEAD scheme ChaChaPoly1305 is used with a 256 bits key.
This key is derived with a key derivation function (KDF) based on NIST SP 800-108 CMAC.
The input key of the KDF is the MKEK, a symmetric key stored in the Key Management Unit (KMU) of Nordic Semiconductor devices.
The MKEK is protected by the KMU peripheral and its key material cannot be read by software. It can only be used by reference.

The file ID is used as a derivation label for the KDF.
This means that each file ID uses a different AEAD key.
As long as each file has a unique file ID, the key used for encryption and authentication is unique.

To strengthen data integrity, the metadata of the ITS file (creation flags/size) is used as authenticated data in the encryption process.

The nonce for the AEAD operation is generated by concatenating a random 8-byte seed and an increasing 4-byte counter.
The random seed is generated once in the boot process and stays the same until reset.

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:

Logging
*******

TF-M employs two UART interfaces for logging: one for the secure part (MCUboot and TF-M), and one for the non-secure application.
By default, the logs arrive on different COM ports on the host PC.
See the :ref:`ug_tfm_manual_VCOM_connection` for more details.

Alternatively, you can configure the TF-M to connect to the same UART as the application by using the :kconfig:option:`CONFIG_TFM_SECURE_UART0` Kconfig option.
Setting this Kconfig option makes TF-M logs visible on the application's VCOM, without manual connection.

The UART instance used by the application is ``0`` by default, and the TF-M UART instance is ``1``.
By using the :kconfig:option:`CONFIG_TFM_SECURE_UART0`. the TF-M UART instance becomes the same as that of the application's.

.. note::

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.

Manual connection to Virtual COM ports on the nRF5340 DK
=========================================================

By default, the nRF5340 DK v1.0.0 requires that you connect specific wires on the kit to receive secure logs on the host PC.
Specifically, wire the pins **P0.25** and **P0.26** of the **P2** connector to **RxD** and **TxD** of the **P24** connector respectively.
See :ref:`logging_cpunet` on the Working with nRF5340 DK page for more information.

On the nRF5340 DK v2.0.0, there are only two virtual COM ports available.
By default, one of the ports is used by the non-secure UART0 peripheral from the application and the other by the UART1 peripheral from the network core.

There are several options to get UART output from the secure TF-M:

* Disable the output for the network core and change the pins used by TF-M.
The network core will usually have an |NCS| child image.
To configure a child image, see Configuration of the child image section described in :ref:`ug_nrf5340_multi_image`.
To configure logging in an |NCS| image, see :ref:`ug_logging`.
To change the pins used by TF-M, the RXD (:kconfig:option:`CONFIG_TFM_UART1_RXD_PIN`) and TXD (:kconfig:option:`CONFIG_TFM_UART1_TXD_PIN`) Kconfig options in the application image can be set to **P1.00** (32) and **P1.01** (33).

* The secure and non-secure UART peripherals can be wired to the same pins.
Specifically, physically wire together the pins **P0.25** and **P0.26** to **P0.20** and **P0.22**, respectively.

* If the non-secure application, network core and TF-M outputs are all needed simultaneously, additional UART <-> USB hardware is needed.
A second nRF DK can be used if available.
Pin **P0.25** needs to be wired to the TXD pin, and **P0.26** to the RXD pin of the external hardware.
These pins will provide the secure TF-M output, while the two native COM ports of the DK will be used for the non-secure application and the network core output.

0 comments on commit 19703da

Please sign in to comment.