diff --git a/doc/nrf/protocols/matter/end_product/security.rst b/doc/nrf/protocols/matter/end_product/security.rst index 9c19f80f3e98..0156b50161f3 100644 --- a/doc/nrf/protocols/matter/end_product/security.rst +++ b/doc/nrf/protocols/matter/end_product/security.rst @@ -161,6 +161,80 @@ This is a reference configuration that can be modified in the production firmwar 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 :ref:`nrf_security_drivers` documentation for more information. +.. _matter_platforms_security_kmu: + +nRF54L15 Key Management Unit (KMU) +================================== + +nRF54l15 devices contains :ref:`ug_nrf54l_crypto_kmu_cracen_peripherals` that can be used to store cryptographic keys in Matter. +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. + +The default slots range used for Matter is from ``100`` to ``180``, not including the DAC private key. +To see configuration for DAC private key, see the :ref:`matter_platforms_security_dac_priv_key_kmu`. +You can change the slots range by setting the :kconfig:option:`CONFIG_CHIP_KMU_SLOT_RANGE_START` and :kconfig:option:`CONFIG_CHIP_KMU_SLOT_RANGE_END` Kconfig options. +For now, we use the Raw usage scheme defined in the :ref:`ug_nrf54l_crypto_kmu_key_usage_schemes` section. + +To use this feature set the :kconfig:option:`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: + +.. code-block:: cpp + + #include + + static KMUKeyAllocator kmuAllocator; + Crypto::SetPSAKeyAllocator(&kmuAllocator); + +See the :file:`samples/matter/common/src/app/matter_init.cpp` to see an usage example. + +Due to limited slots available in the KMU, the maximum number of Matter fabric is limited. +The following table shows the current number of slots used by Matter: + +.. list-table:: KMU slots used by Matter crypto materials + :widths: auto + :header-rows: 1 + + * - Crypto material in Matter + - Key type + - Number of slots needed per key + - Multiplication + - Minimal keys amount + * - Node Operational Certificate (NOC) private key + - ECC secp256r1 key pair + - 2 + - Per Matter Fabric + - 5 (5 Matter fabrics per device) + * - Intermittently Connected Device (ICD) Token + - HMAC SHA-256 128-bit keys + - 1 + - Per ICD user + - 10 (2 ICD users per Matter Fabric) + * - Intermittently Connected Device (ICD) symmetric Key + - AES 128-bit keys + - 1 + - Per ICD user + - 10 (2 ICD users per Matter Fabric) + * Device Attestation Certificate (DAC) private key + - ECC secp256r1 key pair + - 2 + - Per device + - 1 + * - Group key [3]_ + - AES 128-bit keys + - 1 + - Per group + - 15 (3 groups per Matter Fabric) + +.. [3] Group keys are not stored in the KMU yet, but it is planned to be stored in the future. + 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. + We assume 3 grup keys per Matter Fabric. + +According to the table you can calculate the maximum number of Matter fabrics that can be stored in the KMU. +The minimal number of slots needed for the crypto materials is 46, including the DAC private key. +A single Matter fabric requires at least 9 KMU slots. +The default values for the KMU slots range allows to store 8 Matter Fabrics. +You can extend the range, but you must ensure that the range does not overlap with the reserved slots. + .. _matter_platforms_security_dac_priv_key: Storing Device Attestation Certificate private key diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst index f12d1c20388c..52a094b6d986 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst @@ -163,6 +163,7 @@ Matter * A description for the new :ref:`ug_matter_gs_tools_matter_west_commands_append` within the :ref:`ug_matter_gs_tools_matter_west_commands` page. * New arguments to the :ref:`ug_matter_gs_tools_matter_west_commands_zap_tool_gui` to provide a custom cache directory and add new clusters to Matter Data Model. * :ref:`ug_matter_debug_snippet`. + * Storing Matter key materials in the :ref:`matter_platforms_security_kmu`. * Disabled the :ref:`mpsl` before performing factory reset to speed up the process. diff --git a/samples/matter/common/src/app/matter_init.cpp b/samples/matter/common/src/app/matter_init.cpp index 13509b04f5e4..1a51bb5ec508 100644 --- a/samples/matter/common/src/app/matter_init.cpp +++ b/samples/matter/common/src/app/matter_init.cpp @@ -46,6 +46,10 @@ #include #endif +#ifdef CONFIG_CHIP_STORE_KEYS_IN_KMU +#include +#endif + #include #include #include @@ -72,6 +76,10 @@ Clusters::NetworkCommissioning::Instance Nrf::Matter::InitData::sWiFiCommissioni chip::Crypto::PSAOperationalKeystore Nrf::Matter::InitData::sOperationalKeystoreDefault{}; #endif +#ifdef CONFIG_CHIP_STORE_KEYS_IN_KMU +chip::DeviceLayer::KMUSessionKeystore Nrf::Matter::InitData::sKMUSessionKeystoreDefault{}; +#endif + #ifdef CONFIG_CHIP_FACTORY_DATA FactoryDataProvider Nrf::Matter::InitData::sFactoryDataProviderDefault{}; #endif @@ -87,6 +95,9 @@ Nrf::Matter::InitData sLocalInitData{ .mNetworkingInstance = nullptr, #endif #ifdef CONFIG_CHIP_CRYPTO_PSA .mOperationalKeyStore = nullptr, +#endif +#ifdef CONFIG_CHIP_STORE_KEYS_IN_KMU + .mSessionKeystore = nullptr, #endif .mPreServerInitClbk = nullptr, .mPostServerInitClbk = nullptr }; @@ -277,6 +288,13 @@ void DoInitChipServer(intptr_t /* unused */) sLocalInitData.mServerInitParams->operationalKeystore = sLocalInitData.mOperationalKeyStore; #endif +/* Set KMUKeyAllocator for devices that supports KMU */ +#ifdef CONFIG_CHIP_STORE_KEYS_IN_KMU + static KMUKeyAllocator kmuAllocator; + Crypto::SetPSAKeyAllocator(&kmuAllocator); + sLocalInitData.mServerInitParams->sessionKeystore = sLocalInitData.mSessionKeystore; +#endif + VerifyOrReturn(sLocalInitData.mServerInitParams, LOG_ERR("No valid server initialization parameters")); sInitResult = sLocalInitData.mServerInitParams->InitializeStaticResourcesBeforeServerInit(); VerifyInitResultOrReturn(sInitResult, "InitializeStaticResourcesBeforeServerInit() failed"); diff --git a/samples/matter/common/src/app/matter_init.h b/samples/matter/common/src/app/matter_init.h index 8a5d31da6f3f..3c3b1ae9171c 100644 --- a/samples/matter/common/src/app/matter_init.h +++ b/samples/matter/common/src/app/matter_init.h @@ -23,6 +23,10 @@ #include #endif +#ifdef CONFIG_CHIP_STORE_KEYS_IN_KMU +#include +#endif + #ifdef CONFIG_CHIP_FACTORY_DATA #include #else @@ -58,6 +62,10 @@ struct InitData { #ifdef CONFIG_CHIP_CRYPTO_PSA /** @brief Pointer to the user provided OperationalKeystore implementation. */ chip::Crypto::OperationalKeystore *mOperationalKeyStore{ &sOperationalKeystoreDefault }; +#endif +#ifdef CONFIG_CHIP_STORE_KEYS_IN_KMU + /** @brief Pointer to the user provided SessionKeystore implementation. */ + chip::Crypto::SessionKeystore *mSessionKeystore{ &sKMUSessionKeystoreDefault }; #endif /** @brief Custom code to execute in the Matter main event loop before the server initialization. */ CustomInit mPreServerInitClbk{ nullptr }; @@ -77,6 +85,9 @@ struct InitData { #ifdef CONFIG_CHIP_CRYPTO_PSA static chip::Crypto::PSAOperationalKeystore sOperationalKeystoreDefault; #endif +#ifdef CONFIG_CHIP_STORE_KEYS_IN_KMU + static chip::DeviceLayer::KMUSessionKeystore sKMUSessionKeystoreDefault; +#endif }; /** diff --git a/west.yml b/west.yml index a492179cdd65..12e902261f67 100644 --- a/west.yml +++ b/west.yml @@ -157,7 +157,7 @@ manifest: - name: matter repo-path: sdk-connectedhomeip path: modules/lib/matter - revision: cb40b0d0dcc8135c7cf9dc78f2b47d89404047ad + revision: pull/539/head west-commands: scripts/west/west-commands.yml submodules: - name: nlio