Skip to content

Commit b070048

Browse files
ArekBalysNordicnordicjm
ArekBalysNordic
authored and
nordicjm
committed
doc: Thread: Add security page to Thread docs.
- The new page contains information about the OpenThread security, Secure processing environment, Cryptography, Secure storage, cryptographic materials used in Thread and Platform security support. - Added a release note for KMU support and the new security page. Signed-off-by: Arkadiusz Balys <arkadiusz.balys@nordicsemi.no>
1 parent 3cdffa7 commit b070048

File tree

3 files changed

+218
-1
lines changed

3 files changed

+218
-1
lines changed

‎doc/nrf/protocols/thread/overview/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -29,3 +29,4 @@ You can find more information about OpenThread at `OpenThread.io`_.
2929
ot_memory
3030
power_consumption
3131
commissioning
32+
security

‎doc/nrf/protocols/thread/overview/security.rst

+213
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
.. _ug_ot_thread_security:
2+
3+
OpenThread security
4+
###################
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
This section describes the security features of the |NCS| OpenThread implementation.
11+
By default, the OpenThread stack uses the :ref:`nrf_security` and `Platform Security Architecture (PSA)`_ for cryptographic operations.
12+
13+
Nordic OpenThread samples leverage :ref:`security` features supported in the |NCS| that can be divided into four major categories:
14+
15+
* Secure processing environment
16+
* Cryptography
17+
* Secure storage
18+
* Platform Security Support
19+
20+
For details, see the following sections.
21+
22+
Secure processing environment
23+
*****************************
24+
25+
Depending on the board, Thread samples can use a secure processing environment.
26+
27+
nRF54L with Trusted Firmware-M (TF-M)
28+
=====================================
29+
30+
On the nRF54L15 SoC, Thread samples support :ref:`app_boards_spe_nspe` with Trusted Firmware-M (TF-M).
31+
All cryptographic operations within the Thread stack are performed by utilizing the `Platform Security Architecture (PSA)`_ API and executed in the secure TF-M environment.
32+
The secure materials like Thread network key are stored in the TF-M secure storage using the :ref:`tfm_encrypted_its` module.
33+
34+
To build a Thread sample with the TF-M support, :ref:`build <building>` for the :ref:`board target <app_boards_names>` with the ``/ns`` variant.
35+
36+
For example, to build the Thread CLI sample for the nRF54L15 DK with the TF-M support, run the following command:
37+
38+
.. code-block:: console
39+
40+
west build -p -b nrf54l15dk/nrf54l15/cpuapp/ns samples/openthread/cli
41+
42+
Cryptography
43+
************
44+
45+
The Thread stack uses the PSA Cryptography API for cryptographic operations integrated in the :ref:`nrf_security` library.
46+
This library offers various configuration possibilities and backends that can be employed to implement :ref:`cryptographic operations <security_index>`.
47+
48+
The Thread stack requires the following cryptographic operations:
49+
50+
* True Random Number Generation (TRNG)
51+
* HMAC-SHA-256
52+
* AES-128-CCM
53+
* AES-CMAC-128
54+
* ECDSA-SHA-256
55+
* HKDF-SHA-256
56+
* PBKDF2-AES-CMAC-PRF-128
57+
* TLS-ECJPAKE (TSL 1.2)
58+
59+
Secure storage
60+
**************
61+
62+
The Thread stack uses the PSA Crypto API for key management.
63+
Depending on the platform and configuration, you can use PSA Internal Trusted Storage or CRACEN Key Management Unit (KMU) for storing the Thread cryptographic materials in non-volatile memory.
64+
65+
By default, the Thread stack uses PSA ITS backend for storing the Thread cryptographic materials.
66+
You can enable it by setting the :kconfig:option:`CONFIG_OPENTHREAD_PSA_NVM_BACKEND_ITS` Kconfig option to ``y``.
67+
To store the Thread cryptographic materials in the CRACEN KMU on the supported platforms, set the :kconfig:option:`CONFIG_OPENTHREAD_PSA_NVM_BACKEND_KMU` Kconfig option to ``y``.
68+
69+
PSA Internal Trusted Storage
70+
============================
71+
72+
The PSA Internal Trusted Storage (ITS) is an encrypted storage within the Zephyr settings or dedicated partition that you can use to store the Thread cryptographic materials.
73+
It is accelerated by the hardware through nRF crypto drivers such as CryptoCell or CRACEN.
74+
Thread stack uses PSA ITS range defined by the :kconfig:option:`CONFIG_OPENTHREAD_PSA_ITS_NVM_OFFSET` Kconfig option, and by default it is set to ``0x20000``.
75+
The maximum number of keys that can be stored in the PSA ITS is defined in the :kconfig:option:`CONFIG_OPENTHREAD_PSA_ITS_NVM_MAX_KEYS` Kconfig option, and by default it is set to ``20``.
76+
77+
.. _ug_ot_thread_security_kmu:
78+
79+
CRACEN Key Management Unit
80+
==========================
81+
82+
CRACEN Key Management Unit (KMU) is a hardware-based key storage solution that can be used to store the Thread cryptographic materials.
83+
It is available on the nRF54L Series devices.
84+
It allows storing cryptographic materials in the non-volatile memory and provides a secure way to access them.
85+
To learn more about the CRACEN Key Management Unit (KMU) and its usage, see :ref:`ug_nrf54l_crypto_kmu_cracen_peripherals`.
86+
87+
In this solution, the keys are stored within the available slots in the :ref:`ug_nrf54l_crypto_kmu_slots` range that are not reserved for current and future |NCS| use cases.
88+
The default slots range used for Thread is from ``80`` to ``99``.
89+
To change the starting slot number, set the :kconfig:option:`CONFIG_OPENTHREAD_KMU_SLOT_START` Kconfig option to the desired slot.
90+
The end slot number is calculated as a sum of the starting slot number and the maximum number of keys that can be stored in the PSA ITS defined in the :kconfig:option:`CONFIG_OPENTHREAD_PSA_ITS_NVM_MAX_KEYS` Kconfig option.
91+
The Raw usage scheme defined in the :ref:`ug_nrf54l_crypto_kmu_key_usage_schemes` section is used for all Thread keys.
92+
93+
Key management
94+
==============
95+
96+
In the Thread stack, the following cryptographic materials are stored in the non-volatile memory:
97+
98+
.. list-table:: Thread cryptographic materials
99+
:widths: auto
100+
:header-rows: 1
101+
102+
* - Crypto material
103+
- Description
104+
- Persistence
105+
- Key type and algorithm
106+
- Key size
107+
- Amount
108+
- Number of KMU slots needed for a key [1]_
109+
* - Network key
110+
- An OpenThread network master key.
111+
- Persisted
112+
- Asymmetric HMAC, HMAC-SHA-256
113+
- 128 bits
114+
- 3 (new, active, pending)
115+
- 1
116+
* - PSKc
117+
- A pre-shared key for the Thread network for the device.
118+
The key is derived based on the Commissioning Credential and used as a passphrase input to PAKE cipher suite to establish the shared secret.
119+
- Persisted
120+
- Symmetric AES, AES-128-CCM
121+
- 128 bits
122+
- 3 (new, active, pending)
123+
- 1
124+
* - Service Registration Protocol (SRP) ECC keypair
125+
- An ECC keypair used for Verification and Signing messages between the SRP client and server.
126+
- Persisted
127+
- Asymmetric ECC secp256r1 key pair, ECDSA-SHA-256
128+
- 256 bits
129+
- 1
130+
- 2
131+
* - Message Authentication Code (MAC) key
132+
- A key passed to the MAC layer to protect 802.15.4 data frames, derived from Network key using HKDF.
133+
- Volatile
134+
- Symmetric, HKDF-SHA-256
135+
- 128 bits
136+
- 1
137+
- N/A
138+
* - Mesh Link Establishment (MLE) key
139+
- A key used for the Mesh Link Establishment (MLE) protocol, derived from Network key using HKDF.
140+
- Volatile
141+
- Symmetric, HKDF-SHA-256
142+
- 128 bits
143+
- 1
144+
- N/A
145+
* - PSKd
146+
- A pre-shared key for the Thread network for the commissioner.
147+
- Volatile
148+
- Asymmetric ECC secp256r1 key pair, ECDSA-SHA-256
149+
- 256 bits
150+
- 2
151+
- N/A
152+
* - Commissioning Credential
153+
- A human-readable commissioning credential used to form the PSKc key.
154+
- Volatile
155+
- Password
156+
- 8-255 bytes
157+
- 1
158+
- N/A
159+
* - Key Establishment Key (KEK)
160+
- A key used to secure delivery of the network-wide key and other network parameters to the Joiner.
161+
- Volatile
162+
- Symmetric, HKDF-SHA-256
163+
- 128 bits
164+
- 1
165+
- N/A
166+
167+
.. [1] The KMU slots number is applicable only for the CRACEN KMU backend.
168+
169+
Platform Security Support
170+
*************************
171+
172+
The following table summarizes the current security configuration and features supported for Thread-enabled hardware platforms in the |NCS|.
173+
This is a reference configuration that you can modify in the production firmware by using proper Kconfig settings or implementing custom cryptographic backends.
174+
175+
.. list-table:: Thread platforms security support
176+
:widths: auto
177+
:header-rows: 1
178+
179+
* - Platform
180+
- Networking backend
181+
- Cryptography backend
182+
- ARM TrustZone support
183+
- PSA Secure Storage backend
184+
* - nRF52840 SoC
185+
- Thread
186+
- Oberon + CryptoCell [2]_
187+
- No
188+
- Trusted Storage library + SHA-256 hash
189+
* - nRF5340 SoC
190+
- Thread
191+
- Oberon + CryptoCell [2]_
192+
- Yes
193+
- Trusted Storage library + Hardware Unique Key (HUK)
194+
* - nRF54L15, nRF54L10, nRF54L05 SoCs
195+
- Thread
196+
- CRACEN [3]_
197+
- Yes
198+
- Trusted Storage library + Hardware Unique Key (HUK) + Key Management Unit (KMU)
199+
* - nRF54L15, nRF54L10, nRF54L05 SoCs + Trusted Firmware-M (TF-M)
200+
- Thread
201+
- CRACEN
202+
- Yes
203+
- Trusted Firmware-M (TF-M) + Key Management Unit (KMU)
204+
205+
.. [2] The CryptoCell backend is used in parallel with the Oberon backend.
206+
By default, the CryptoCell backend is used only for the Random Number Generation (RNG) and AEAD key derivation driver.
207+
To enable the CryptoCell backend for additional operations, set the :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_CC3XX` Kconfig option to ``true``.
208+
209+
.. [3] The CRACEN backend is used in parallel with the Oberon backend.
210+
The CRACEN backend is used by default for any supported cryptographic operations.
211+
For all other operations not supported by CRACEN, the Oberon backend is used.
212+
To use the Oberon backend for specific cryptographic operations supported by both drivers, disable those operations in the CRACEN driver, as it takes priority when both are enabled.
213+
See the :ref:`nrf_security_drivers` documentation for more information.

‎doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst

+4-1
Original file line numberDiff line numberDiff line change
@@ -232,7 +232,10 @@ nRF IEEE 802.15.4 radio driver
232232
Thread
233233
------
234234

235-
|no_changes_yet_note|
235+
* Added:
236+
237+
* Support for storing the Thread key materials in the :ref:`ug_ot_thread_security_kmu`.
238+
* The :ref:`ug_ot_thread_security` user guide describing the security features of the |NCS| OpenThread implementation.
236239

237240
Zigbee
238241
------

0 commit comments

Comments
 (0)