Security

Nordic Matter samples leverage Security features supported in the nRF Connect SDK that can be divided into four major categories:

• Cryptography

• Secure processing environment

• Trusted storage

• Securing production devices

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

Cryptography

Depending on the networking backend, the nRF Connect SDK Matter samples currently use the following APIs to implement cryptographic operations:

• PSA Cryptography API for Thread networking. Both Implementations in the nRF Connect SDK are supported, but using TF-M Crypto Service is only possible with Trusted Firmware-M (TF-M).

• Legacy Mbed TLS crypto API for Wi-Fi® networking. Support for PSA Cryptography API for the Wi-Fi backend is planned for a future release.

Both APIs are integrated through the nRF Security library. For an overview of the PSA Crypto API, see the Cryptographic architecture overview page. For an overview of the cryptography layer configuration supported for each nRF Connect SDK Matter-enabled platform, see the Matter platforms security support section.

Secure processing environment

When building for the nRF54L15 DK using the nrf54l15dk/nrf54l15/cpuapp/ns board target, Matter samples can use the secure processing environment with Trusted Firmware-M (TF-M). In such cases, all cryptographic operations within the Matter stack are performed by using the Platform Security Architecture (PSA) API and executed in the secure TF-M environment using the TF-M Crypto Service implementation. The secure materials like Matter Session keys and other keys (except for the DAC private key) can be stored in the TF-M secure storage using the Encrypted ITS or Key Management Unit (KMU).

Matter samples use the full, configurable TF-M build, so you cannot use the minimal build. For more information, see Supported TF-M profiles.

Matter sample partition layout

To configure the partition layout for your application, you can edit the boards/nrf54l15dk_nrf54l15_cpuapp.overlay board file that is available in each sample directory. To read more about the TF-M partitioning, see TF-M 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 Reference Matter memory layouts section.

By default, the DAC private key is stored in the KMU storage while using TF-M. See the DAC in Key Management Unit (KMU) section for more information.

Secure storage

Secure storage in the nRF Connect SDK lets you securely store and manage sensitive data. Currently, all Matter samples in the nRF Connect SDK use the Trusted storage library as the PSA Secure Storage API implementation for all supported platforms. You can find an overview of the PSA Secure Storage configuration supported for each nRF Connect SDK Matter-enabled platform in the Matter platforms security support section.

Note

For the nRF52840 devices, in regards to Matter samples in nRF Connect SDK, AEAD keys are derived using hashes of entry UIDs (CONFIG_TRUSTED_STORAGE_BACKEND_AEAD_KEY_HASH_UID). This approach is less secure than using the Hardware unique key library for key derivation as it only provides integrity of sensitive material. It is also possible to implement a custom AEAD key generation method when the CONFIG_TRUSTED_STORAGE_BACKEND_AEAD_KEY_CUSTOM Kconfig option is selected.

For more details about AEAD key generation and backend configuration, see the Trusted storage readme.

Matter platforms security support

The following table summarizes the current security configuration and features supported for Matter-enabled hardware platforms in the nRF Connect SDK. This is a reference configuration that can be modified in the production firmware by using proper Kconfig settings or implementing custom cryptographic backends.

Matter platforms security support

Platform	Networking backend	Cryptography API	Cryptography backend	ARM TrustZone support	PSA Secure Storage backend
nRF52840 SoC	Thread	PSA Crypto API	Oberon + CryptoCell [1]	No	Trusted Storage library + SHA-256 hash
nRF5340 SoC	Thread	PSA Crypto API	Oberon + CryptoCell [1]	Yes	Trusted Storage library + Hardware Unique Key (HUK)
nRF54L15 SoC	Thread	PSA Crypto API	CRACEN [2]	Yes	Trusted Storage library + Hardware Unique Key (HUK) + Key Management Unit (KMU)
nRF54L15 SoC + Trusted Firmware-M (TF-M)	Thread	PSA Crypto API	CRACEN	Yes	Trusted Firmware-M (TF-M) + Key Management Unit (KMU)
nRF54L10 SoC	Thread	PSA Crypto API	CRACEN [2]	Yes	Hardware Unique Key (HUK) + Key Management Unit (KMU)
nRF54LM20A and nRF54LM20B SoCs	Thread	PSA Crypto API	CRACEN [2]	Yes	Trusted Storage library + Hardware Unique Key (HUK) + Key Management Unit (KMU)

[1] (1,2)

The CryptoCell backend is used in parallel with the Oberon backend. By default, the CryptoCell backend is used only for Random Number Generation (RNG) and the AEAD key derivation driver. To enable the CryptoCell backend for additional operations, set the CONFIG_PSA_CRYPTO_DRIVER_CC3XX Kconfig option to true.

[2] (1,2,3)

The CRACEN backend is used in parallel with the Oberon backend. The CRACEN backend is used by default for any supported cryptographic operations. For all other operations not supported by CRACEN, the Oberon backend is used. 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. See the Cryptographic drivers documentation for more information.

nRF54L Key Management Unit (KMU)

Most nRF54L Series devices include KMU hardware peripheral that can be used to store cryptographic keys in Matter. In this solution, the keys are stored within the available slots in the KMU slots range that are not reserved for current and future nRF Connect SDK use cases.

The default slots range used for Matter is from 100 to 180, excluding the DAC private key. For details on the DAC private key configuration, see DAC in Key Management Unit (KMU). To change the slots range, set the CONFIG_CHIP_KMU_SLOT_RANGE_START and CONFIG_CHIP_KMU_SLOT_RANGE_END Kconfig options. The Raw usage scheme defined in the KMU key usage schemes section is used for all Matter keys.

To use this feature, set the CONFIG_CHIP_STORE_KEYS_IN_KMU Kconfig option to y, and switch to the KMUKeyAllocator by calling the chip::Crypto::SetPSAKeyAllocator method in your code during the Matter stack initialization.

For example:

#include <platform/nrfconnect/KMUKeyAllocator.h>

static KMUKeyAllocator kmuAllocator;
Crypto::SetPSAKeyAllocator(&kmuAllocator);

See the samples/matter/common/src/app/matter_init.cpp file for a usage example.

Due to limited slots available in the KMU, the maximum number of Matter fabric is limited. The following table shows all the crypto materials used in Matter, the number of slots needed for each key and a Kconfig option that can be used to adjust the number of each key type:

KMU slots used by Matter crypto materials

Crypto material in Matter	Key type	Number of slots needed for a key	Multiplication	Minimum number of keys	Kconfig option
Node Operational Certificate (NOC) private key	ECC secp256r1 key pair	2	For each Matter fabric	5 (5 Matter fabrics for each device)	CONFIG_CHIP_MAX_FABRICS
Intermittently Connected Device (ICD) Token	HMAC SHA-256 128-bit keys	1	For each ICD user	10 (2 ICD users for each Matter fabric)	CONFIG_CHIP_ICD_CLIENTS_PER_FABRIC
Intermittently Connected Device (ICD) symmetric Key	AES 128-bit keys	1	For each ICD user	10 (2 ICD users for each Matter fabric)	CONFIG_CHIP_ICD_CLIENTS_PER_FABRIC
Group key [3]	AES 128-bit keys	1	For each group	15 (3 groups for each Matter fabric)	Not a Kconfig option, see CHIP_CONFIG_MAX_GROUP_ENDPOINTS_PER_FABRIC Matter config.
Device Attestation Certificate (DAC) private key	ECC secp256r1 key pair	2	For each device	1	Not configurable

[3]

Group keys are not stored in the KMU yet, but the slots are reserved for the future usage. A key may be shared between multiple groups, so the number of slots needed for group keys may be lower than the number of groups. Three group keys are assumed for each Matter fabric.

The default slots range allows storing more cryptographic materials than the minimum required according to the Matter specification. A minimum of 46 slots is required for cryptographic materials, including the DAC private key to support five fabrics (minimum required by the specification). A single Matter fabric requires at least nine KMU slots.

The default range has been chosen to support up to eight Matter fabrics, 32 ICD keys (16 ICD users), and 24 group keys. You can change the default Kconfig option for each crypto material to adjust the number of slots, but you must ensure that the total number of slots fits within the defined range. If you overlap the slots range, the appropriate compilation error will be shown:

error: "The number of slots exceeds the range of the KMU defined in CONFIG_CHIP_KMU_SLOT_RANGE_START and CONFIG_CHIP_KMU_SLOT_RANGE_END"

For example, to fill the default slots range and support eight Matter fabrics, three group keys per fabric, and two ICD users for each fabric, set the CONFIG_CHIP_MAX_FABRICS Kconfig option to 8.

Slots arrangement within the slot range defined by CONFIG_CHIP_KMU_SLOT_RANGE_START and CONFIG_CHIP_KMU_SLOT_RANGE_END Kconfig options is calculated automatically in the code in the following way:

KMU slots arrangement for Matter crypto materials

Crypto material	Slot range start	Slot range end	Default slot range for eight Matter fabrics to fit the default range (100-180)
Node Operational Certificate (NOC) private key	CONFIG_CHIP_KMU_SLOT_RANGE_START	CONFIG_CHIP_KMU_SLOT_RANGE_START + (CONFIG_CHIP_MAX_FABRICS * 2)	100 - 115
Intermittently Connected Device (ICD) Token + ICD symmetric Key	End of NOC slots	End of NOC slots + (CONFIG_CHIP_ICD_CLIENTS_PER_FABRIC * CONFIG_CHIP_MAX_FABRICS * 2)	116 - 147
Group keys	End of ICD slots	End of ICD slots + (3 * CONFIG_CHIP_MAX_FABRICS)	148 - 171
Device Attestation Certificate (DAC) private key	Configurable with CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_KMU_SLOT_ID	DAC private key start slot + 1 (non-encrypted) or + 3 (encrypted)	176 - 179 (encrypted) or 178 - 179 (non-encrypted)

Important

Once a slot range is defined, it should not be changed during the firmware update process. Changing the slot range will result in loss of all cryptographic materials stored in the KMU. You can safely change slot ranges only when the device is in the factory state and no cryptographic materials are stored in the KMU. Otherwise, to extend the slot range beyond the previously defined range and keep the existing cryptographic materials stored in the KMU, complete the following steps:

1. Locate the src/platform/nrfconnect/KMUKeyAllocator.h file in the Matter repository, or create a new one with the same functionality.

2. Modify the file content to redirect the keys to the new slot range by implementing the GetDacKeyId, GetOpKeyId, and AllocateICDKeyId functions.

3. If you want to use your own implementation of the KMUKeyAllocator, assign it in your application code by calling the Crypto::SetPSAKeyAllocator method.

4. Ensure that you have chosen an available slot range that does not overlap with any existing one.

5. Build your application with the new configuration.

6. Perform a firmware update on the device.

Storing Device Attestation Certificate private key

In Matter samples based on the PSA crypto API, the Device Attestation Certificate’s private key, which exists in the factory data set, can be migrated to secure storage. The secure storage used depends on the platform and the cryptographic backend.

The migration of the DAC private key from the factory data set to secure storage is controlled by the CONFIG_CHIP_CRYPTO_PSA_MIGRATE_DAC_PRIV_KEY Kconfig option and set to y by default.

Currently, this feature is available only for the PSA crypto API. See the following table to learn about the default secure storage backends for the DAC private key and the available secure storage backends for each platform:

Matter secure storage

Platform	Default secure storage backend for DAC private key	Available secure storage backends
nRF52840 SoC	Trusted Storage library + SHA-256 hash (Zephyr Settings)	Trusted Storage library + SHA-256 hash (Zephyr Settings)
nRF5340 SoC	Trusted Storage library + Hardware Unique Key (Zephyr Settings)	Trusted Storage library + Hardware Unique Key (Zephyr Settings), Trusted Storage library + SHA-256 hash (Zephyr Settings)
nRF54L15 SoC	Key Management Unit (KMU)	Key Management Unit (KMU), Trusted Storage library + Hardware Unique Key (Zephyr Settings), Trusted Storage library + SHA-256 hash (Zephyr Settings)
nRF54L15 SoC + Trusted Firmware-M (TF-M)	Key Management Unit (KMU)	Key Management Unit (KMU), Trusted Firmware-M Storage (TF-M)
nRF54L10 SoC	Key Management Unit (KMU)	Key Management Unit (KMU), Trusted Storage library + Hardware Unique Key (Zephyr Settings), Trusted Storage library + SHA-256 hash (Zephyr Settings)

If you migrate the DAC private key to storage based on Zephyr Settings storage, you cannot use the 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 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).

DAC in Trusted Storage library

The Device Attestation Certificates private key can be stored in the Trusted Storage library. The key is encrypted with the AEAD key derived from the Hardware Unique Key (HUK) or a SHA-256 hash. This storage backend is selected by default for all platforms that support the PSA Crypto API, except for the nRF54L Series devices that use Key Management Unit (KMU).

To enable storing the DAC private key in the Trusted Storage library, set the CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_ITS Kconfig option to y. To select which encryption to use, set one of the following Kconfig options:

• To use key derivation from HUK, set CONFIG_TRUSTED_STORAGE_BACKEND_AEAD_KEY_DERIVE_FROM_HUK to y.

• To use key derivation from a SHA-256 hash, set CONFIG_TRUSTED_STORAGE_BACKEND_AEAD_KEY_HASH_UID to y.

Encryption with the AEAD key derived from the Hardware Unique Key (HUK) is available only on the nRF5340 and nRF54L platforms.

DAC in Key Management Unit (KMU)

The Key Management Unit (KMU) is a hardware peripheral that provides secure storage for cryptographic keys. It is available in most of the nRF54L Series SoCs and can be used to store the DAC private key. This storage backend can be used with Trusted Firmware-M (TF-M).

Storing the DAC private key in the KMU is controlled by the CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_KMU Kconfig option and set to y by default.

You can additionally encrypt the DAC private key in the KMU storage by setting the CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_KMU_ENCRYPTED Kconfig option to y. This operation requires two additional KMU slots to store the nonce and the authentication tag, making the total number of slots used four. If the CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_KMU_ENCRYPTED Kconfig option is set to n, then the DAC private key is stored in the KMU without encryption and utilizes two KMU slots.

By default, the DAC private key occupies the last slots dedicated for application purposes. For the non-encrypted version, it occupies the last two slots (178 and 179), and for the encrypted version, it occupies the last four slots (176-179). You can change the default slots by setting the CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_KMU_SLOT_ID Kconfig option to the first slot number of the desired slots, making sure that all slots fit within the possible range. This means you can set it to slot numbers 0-176 for encrypted, or 0-178 for non-encrypted. To read more about KMU slots, see the KMU and CRACEN hardware peripherals overview page.

Securing production devices

When finalizing work on a Matter device, make sure to adopt the following recommendations before sending the device to production.

Enable AP-Protect

Make sure to enable the AP-Protect feature for the production devices to disable the debug functionality.

Several Nordic Semiconductor SoCs or SiPs supported in the nRF Connect SDK offer an implementation of the access port protection mechanism (AP-Protect). When enabled, this mechanism blocks the debugger from read and write access to all CPU registers and memory-mapped addresses. Accessing these registers and addresses again requires disabling the mechanism and erasing the flash.

See Managing access port protection for more information.

Disable debug serial port

Make sure to disable the debug serial port, for example UART, so that logs and shell commands are not accessible for production devices. See the prj_release.conf files in Matter samples for an example of how to disable debug functionalities.