doc: matter: Add TF-M to Matter documentation and HW requirements

- Added information about TF-M to Matter documentation. - Updated the hardware requirements for Matter products and added nRF54L15 + TF-M variant with partitioning description. Signed-off-by: Arkadiusz Balys <[email protected]>
nrfconnect · Oct 31, 2024 · d67ed70 · d67ed70
1 parent 658d36e
commit d67ed70
Show file tree

Hide file tree

Showing 2 changed files with 81 additions and 11 deletions.
diff --git a/doc/nrf/protocols/matter/end_product/security.rst b/doc/nrf/protocols/matter/end_product/security.rst
@@ -7,14 +7,39 @@ Security
    :local:
    :depth: 3
 
-Nordic Matter samples leverage security features supported in the |NCS| that can be divided into three major categories:
+Nordic Matter samples leverage :ref:`security` features supported in the |NCS| that can be divided into four major categories:
 
+* Secure processing environment
 * Cryptography
 * Trusted storage
 * Securing production devices
 
 In the following sections you will learn more details about each listed category.
 
+Secure processing environment
+*****************************
+
+Depending on the board, Matter samples can use a secure processing environment.
+
+nRF54L with Trusted Firmware-M (TF-M)
+=====================================
+
+On the nRF54L SoC, Matter samples support :ref:`app_boards_spe_nspe` with Trusted Firmware-M (TF-M).
+All cryptographic operations within the Matter stack are performed by utilizing the `Platform Security Architecture (PSA)`_ API and executed in the secure TF-M environment.
+The secure materials like Matter Session keys, DAC private key and other keys, are stored in the TF-M secure storage using the :ref:`tfm_encrypted_its` module.
+Matter samples use the full TF-M library, so you cannot use the :ref:`tfm_minimal_build` version of TF-M.
+
+To build a Matter sample with the TF-M support, :ref:`build <building>` for the :ref:`board target <app_boards_names>` with the ``/ns`` variant.
+
+To configure partition layout for your application, you can edit the :file:`pm_static_nrf54l15dk_nrf54l15_cpuapp_ns.yml` file that is available in each sample directory.
+To read more about the TF-M partitioning, see :ref:`ug_tfm_partition_alignment_requirements`.
+While using TF-M, the application partition size and available RAM space for the application is lower than without TF-M.
+You must keep this in mind and calculate the available space for the application partition.
+The recommended values are provided in the :ref:`ug_matter_hw_requirements_layouts` section.
+
+In addition, you can store the DAC private key in the KMU storage while using TF-M.
+To learn how to do it, see the :ref:`matter_platforms_security_dac_priv_key_kmu` section.
+
 Cryptography
 ************
 
@@ -150,24 +175,30 @@ See the following table to learn about the default secure storage backends for t
      - Default secure storage backend for DAC private key
      - Available secure storage backends
    * - nRF52840 SoC
-     - Trusted Storage library + SHA-256 hash
-     - Trusted Storage library + SHA-256 hash
+     - Trusted Storage library + SHA-256 hash (Zephyr Settings)
+     - Trusted Storage library + SHA-256 hash (Zephyr Settings)
    * - nRF5340 SoC
-     - Trusted Storage library + Hardware Unique Key (HUK)
-     - | Trusted Storage library + Hardware Unique Key (HUK),
-       | Trusted Storage library + SHA-256 hash
+     - Trusted Storage library + Hardware Unique Key (Zephyr Settings)
+     - | Trusted Storage library + Hardware Unique Key (Zephyr Settings),
+       | Trusted Storage library + SHA-256 hash (Zephyr Settings)
    * - nRF5340 SoC + nRF7002 companion IC
      - Not available
      - Not available
    * - nRF54L15 SoC
-     - Trusted Storage library + Hardware Unique Key (HUK)
+     - Trusted Storage library + Hardware Unique Key
      - | Key Management Unit (KMU),
-       | Trusted Storage library + Hardware Unique Key (HUK),
-       | Trusted Storage library + SHA-256 hash
+       | Trusted Storage library + Hardware Unique Key (Zephyr Settings),
+       | Trusted Storage library + SHA-256 hash (Zephyr Settings)
    * - nRF54L15 SoC + Trusted Firmware-M (TF-M)
-     - Trusted Firmware-M (TF-M) Storage
+     - Trusted Firmware-M Storage (TF-M)
      - | Key Management Unit (KMU),
-       | Trusted Firmware-M (TF-M) Storage
+       | Trusted Firmware-M Storage (TF-M)
+
+If you migrate the DAC private key to storage based on Zephyr Settings storage, you cannot use the :kconfig:option:`CONFIG_CHIP_FACTORY_RESET_ERASE_SETTINGS` Kconfig option.
+This is because the factory reset feature will erase the secure storage, including the DAC private key, which has been removed from the factory data.
+In this case, the DAC private key will be lost, and the device will not be able to authenticate to the network.
+
+You can use the :kconfig:option:`CONFIG_CHIP_FACTORY_RESET_ERASE_SETTINGS` Kconfig option if you store the DAC private key in the KMU or TF-M secure storage (available on nRF54L SoCs only).
 
 .. _matter_platforms_security_dac_priv_key_its:
 

diff --git a/doc/nrf/protocols/matter/getting_started/hw_requirements.rst b/doc/nrf/protocols/matter/getting_started/hw_requirements.rst
@@ -665,6 +665,45 @@ For more information about configuration of memory layouts in Matter, see :ref:`
         | Static RAM (sram_primary)                     | 0kB (0x0)           | 256kB (0x40000)   |-                    |-                |-                |
         +-----------------------------------------------+---------------------+-------------------+---------------------+-----------------+-----------------+
 
+   .. tab:: nRF54L15 DK with TF-M
+
+      The following table lists memory requirements for samples running on the :ref:`nRF54L15 DK with CMSE enabled <app_boards_spe_nspe_cpuapp_ns>` (:ref:`nrf54l15dk/nrf54l15/cpuapp/ns <zephyr:nrf54l15dk_nrf54l15>`).
+
+      Application core flash (size: 0x17D000 = 1524kB)
+
+        +-----------------------------------------+---------------------+-------------------+---------------------+-----------------+-------------------+
+        | Partition                               | Offset              | Size              | Partition elements  | Element offset  | Element size      |
+        +=========================================+=====================+===================+=====================+=================+===================+
+        | Bootloader (mcuboot)                    | 0kB (0x0)           | 48kB (0xC000)     |-                    |-                |-                  |
+        +-----------------------------------------+---------------------+-------------------+---------------------+-----------------+-------------------+
+        | Secure part (tfm_secure)                | 48kB (0xc000)       | 128kB (0x20000)   | mcuboot_pad         | 48kB (0xc000)   | 2k (0x800)        |
+        |                                         |                     |                   +---------------------+-----------------+-------------------+
+        |                                         |                     |                   | tfm                 | 50kB (0xc800)   | 126kB (0x1f800)   |
+        +-----------------------------------------+---------------------+-------------------+---------------------+-----------------+-------------------+
+        | Non-Secure part (tfm_nonsecure)         | 176kB (0x2C000)     | 1272kB (0x13E000) | app                 | 176kB (0x2C000) | 1272kB (0x13E000) |
+        +-----------------------------------------+---------------------+-------------------+---------------------+-----------------+-------------------+
+        | Factory data (factory_data)             | 1448kB (0x16A000)   | 4kB (0x1000)      |-                    |-                |-                  |
+        +-----------------------------------------+---------------------+-------------------+---------------------+-----------------+-------------------+
+        | Non-volatile storage (settings_storage) | 1452kB (0x16B000)   | 40kB (0xa000)     |-                    |-                |-                  |
+        +-----------------------------------------+---------------------+-------------------+---------------------+-----------------+-------------------+
+        | TFM storage (tfm_storage)               | 1492kB (0x175000)   | 32kB (0x8000)     | tfm_its             | 8kB (0x175000)  | 8kB (0x2000)      |
+        |                                         |                     |                   +---------------------+-----------------+-------------------+
+        |                                         |                     |                   | tfm_otp_nv_counters | 8kB (0x177000)  | 8kB (0x2000)      |
+        |                                         |                     |                   +---------------------+-----------------+-------------------+
+        |                                         |                     |                   | tfm_ps              | 16kB (0x179000) | 16kB (0x4000)     |
+        +-----------------------------------------+---------------------+-------------------+---------------------+-----------------+-------------------+
+
+      Application core SRAM primary (size: 0x40000 = 256kB)
+        SRAM is located at the address ``0x20000000`` in the memory address space of the application.
+
+        +-----------------------------------------------+---------------------+-------------------+---------------------+-----------------+-----------------+
+        | Partition                                     | Offset              | Size              | Partition elements  | Element offset  | Element size    |
+        +===============================================+=====================+===================+=====================+=================+=================+
+        | Secure Static RAM (sram_secure)               | 0kB (0x0)           | 256kB (0xF000)    |-                    |-                |-                |
+        +-----------------------------------------------+---------------------+-------------------+---------------------+-----------------+-----------------+
+        | Non-Secure Static RAM (sram_nonsecure)        | 256kB (0xF000)      | 196kB (0x31000)   |-                    |-                |-                |
+        +-----------------------------------------------+---------------------+-------------------+---------------------+-----------------+-----------------+
+
 ..
 
 You can generate :ref:`Partition Manager's ASCII representation <pm_partition_reports>` of these tables by running the following command for your respective *board_target*: