Skip to content

Commit d67ed70

Browse files
ArekBalysNordicrlubos
ArekBalysNordic
authored and
rlubos
committed
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]>
1 parent 658d36e commit d67ed70

File tree

2 files changed

+81
-11
lines changed

2 files changed

+81
-11
lines changed

‎doc/nrf/protocols/matter/end_product/security.rst‎

Lines changed: 42 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,39 @@ Security
77
:local:
88
:depth: 3
99

10-
Nordic Matter samples leverage security features supported in the |NCS| that can be divided into three major categories:
10+
Nordic Matter samples leverage :ref:`security` features supported in the |NCS| that can be divided into four major categories:
1111

12+
* Secure processing environment
1213
* Cryptography
1314
* Trusted storage
1415
* Securing production devices
1516

1617
In the following sections you will learn more details about each listed category.
1718

19+
Secure processing environment
20+
*****************************
21+
22+
Depending on the board, Matter samples can use a secure processing environment.
23+
24+
nRF54L with Trusted Firmware-M (TF-M)
25+
=====================================
26+
27+
On the nRF54L SoC, Matter samples support :ref:`app_boards_spe_nspe` with Trusted Firmware-M (TF-M).
28+
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.
29+
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.
30+
Matter samples use the full TF-M library, so you cannot use the :ref:`tfm_minimal_build` version of TF-M.
31+
32+
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.
33+
34+
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.
35+
To read more about the TF-M partitioning, see :ref:`ug_tfm_partition_alignment_requirements`.
36+
While using TF-M, the application partition size and available RAM space for the application is lower than without TF-M.
37+
You must keep this in mind and calculate the available space for the application partition.
38+
The recommended values are provided in the :ref:`ug_matter_hw_requirements_layouts` section.
39+
40+
In addition, you can store the DAC private key in the KMU storage while using TF-M.
41+
To learn how to do it, see the :ref:`matter_platforms_security_dac_priv_key_kmu` section.
42+
1843
Cryptography
1944
************
2045

@@ -150,24 +175,30 @@ See the following table to learn about the default secure storage backends for t
150175
- Default secure storage backend for DAC private key
151176
- Available secure storage backends
152177
* - nRF52840 SoC
153-
- Trusted Storage library + SHA-256 hash
154-
- Trusted Storage library + SHA-256 hash
178+
- Trusted Storage library + SHA-256 hash (Zephyr Settings)
179+
- Trusted Storage library + SHA-256 hash (Zephyr Settings)
155180
* - nRF5340 SoC
156-
- Trusted Storage library + Hardware Unique Key (HUK)
157-
- | Trusted Storage library + Hardware Unique Key (HUK),
158-
| Trusted Storage library + SHA-256 hash
181+
- Trusted Storage library + Hardware Unique Key (Zephyr Settings)
182+
- | Trusted Storage library + Hardware Unique Key (Zephyr Settings),
183+
| Trusted Storage library + SHA-256 hash (Zephyr Settings)
159184
* - nRF5340 SoC + nRF7002 companion IC
160185
- Not available
161186
- Not available
162187
* - nRF54L15 SoC
163-
- Trusted Storage library + Hardware Unique Key (HUK)
188+
- Trusted Storage library + Hardware Unique Key
164189
- | Key Management Unit (KMU),
165-
| Trusted Storage library + Hardware Unique Key (HUK),
166-
| Trusted Storage library + SHA-256 hash
190+
| Trusted Storage library + Hardware Unique Key (Zephyr Settings),
191+
| Trusted Storage library + SHA-256 hash (Zephyr Settings)
167192
* - nRF54L15 SoC + Trusted Firmware-M (TF-M)
168-
- Trusted Firmware-M (TF-M) Storage
193+
- Trusted Firmware-M Storage (TF-M)
169194
- | Key Management Unit (KMU),
170-
| Trusted Firmware-M (TF-M) Storage
195+
| Trusted Firmware-M Storage (TF-M)
196+
197+
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.
198+
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.
199+
In this case, the DAC private key will be lost, and the device will not be able to authenticate to the network.
200+
201+
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).
171202

172203
.. _matter_platforms_security_dac_priv_key_its:
173204

‎doc/nrf/protocols/matter/getting_started/hw_requirements.rst‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -665,6 +665,45 @@ For more information about configuration of memory layouts in Matter, see :ref:`
665665
| Static RAM (sram_primary) | 0kB (0x0) | 256kB (0x40000) |- |- |- |
666666
+-----------------------------------------------+---------------------+-------------------+---------------------+-----------------+-----------------+
667667

668+
.. tab:: nRF54L15 DK with TF-M
669+
670+
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>`).
671+
672+
Application core flash (size: 0x17D000 = 1524kB)
673+
674+
+-----------------------------------------+---------------------+-------------------+---------------------+-----------------+-------------------+
675+
| Partition | Offset | Size | Partition elements | Element offset | Element size |
676+
+=========================================+=====================+===================+=====================+=================+===================+
677+
| Bootloader (mcuboot) | 0kB (0x0) | 48kB (0xC000) |- |- |- |
678+
+-----------------------------------------+---------------------+-------------------+---------------------+-----------------+-------------------+
679+
| Secure part (tfm_secure) | 48kB (0xc000) | 128kB (0x20000) | mcuboot_pad | 48kB (0xc000) | 2k (0x800) |
680+
| | | +---------------------+-----------------+-------------------+
681+
| | | | tfm | 50kB (0xc800) | 126kB (0x1f800) |
682+
+-----------------------------------------+---------------------+-------------------+---------------------+-----------------+-------------------+
683+
| Non-Secure part (tfm_nonsecure) | 176kB (0x2C000) | 1272kB (0x13E000) | app | 176kB (0x2C000) | 1272kB (0x13E000) |
684+
+-----------------------------------------+---------------------+-------------------+---------------------+-----------------+-------------------+
685+
| Factory data (factory_data) | 1448kB (0x16A000) | 4kB (0x1000) |- |- |- |
686+
+-----------------------------------------+---------------------+-------------------+---------------------+-----------------+-------------------+
687+
| Non-volatile storage (settings_storage) | 1452kB (0x16B000) | 40kB (0xa000) |- |- |- |
688+
+-----------------------------------------+---------------------+-------------------+---------------------+-----------------+-------------------+
689+
| TFM storage (tfm_storage) | 1492kB (0x175000) | 32kB (0x8000) | tfm_its | 8kB (0x175000) | 8kB (0x2000) |
690+
| | | +---------------------+-----------------+-------------------+
691+
| | | | tfm_otp_nv_counters | 8kB (0x177000) | 8kB (0x2000) |
692+
| | | +---------------------+-----------------+-------------------+
693+
| | | | tfm_ps | 16kB (0x179000) | 16kB (0x4000) |
694+
+-----------------------------------------+---------------------+-------------------+---------------------+-----------------+-------------------+
695+
696+
Application core SRAM primary (size: 0x40000 = 256kB)
697+
SRAM is located at the address ``0x20000000`` in the memory address space of the application.
698+
699+
+-----------------------------------------------+---------------------+-------------------+---------------------+-----------------+-----------------+
700+
| Partition | Offset | Size | Partition elements | Element offset | Element size |
701+
+===============================================+=====================+===================+=====================+=================+=================+
702+
| Secure Static RAM (sram_secure) | 0kB (0x0) | 256kB (0xF000) |- |- |- |
703+
+-----------------------------------------------+---------------------+-------------------+---------------------+-----------------+-----------------+
704+
| Non-Secure Static RAM (sram_nonsecure) | 256kB (0xF000) | 196kB (0x31000) |- |- |- |
705+
+-----------------------------------------------+---------------------+-------------------+---------------------+-----------------+-----------------+
706+
668707
..
669708
670709
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*:

0 commit comments

Comments
 (0)