Skip to content

Commit 7cad837

Browse files
ArekBalysNordicArekBalysNordic
committed
docs: Describe KRKNWK-22680 and v1.0.1 ITS fallback for DAC key
Document the v1.0.0 nRF54L issue where the DAC private key could be stored in PSA ITS instead of CRACEN KMU, and how v1.0.1 restores KMU defaults on NCS v3.4.x. Update migration guidance, known issues, and release notes for CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_KMU_ITS_FALLBACK (default): units that already have the key in ITS can run KMU-default firmware, attest with the ITS copy, and re-provision later when KMU-only storage is required. Split KRKNWK-22680 guidance by where the key was first migrated (KMU vs ITS) so KMU-backed devices are directed to Path A instead of ITS Kconfig that cannot access a KMU-resident key. Signed-off-by: Arkadiusz Balys <arkadiusz.balys@nordicsemi.no>
1 parent 4811a05 commit 7cad837

7 files changed

Lines changed: 214 additions & 6 deletions

File tree

‎docs/_extensions/page_filter.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -197,10 +197,10 @@ def page_filter_install(
197197
if visitor.found_filter_dropdown:
198198
app.add_css_file("page_filter.css")
199199
app.add_js_file("page_filter.mjs", type="module")
200-
filename = app.builder.script_files[-1]
200+
script = app.builder.script_files[-1]
201201

202202
page_depth = len(Path(pagename).parents) - 1
203-
body = f"import setupFiltering from './{page_depth * '../'}{filename}'; "
203+
body = f"import setupFiltering from './{page_depth * '../'}{script.filename}'; "
204204
for dropdown in visitor.found_filter_dropdown:
205205
body += f"setupFiltering('{dropdown.name}'"
206206
if dropdown.container_element and dropdown.filter_tags:

‎docs/known_issues.rst‎

Lines changed: 68 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,12 @@ Known issues
55

66
.. contents::
77
:local:
8-
:depth: 2
8+
:depth: 3
99

10-
Known issues listed on this page are valid for the current state of development.
11-
Items can have one or both of the following entries:
10+
Known issues listed on this page *and* tagged with the :ref:`latest release version <release_notes>` are valid for the current state of development.
11+
Use the drop-down filter to see known issues for previous releases and check if they are still valid.
12+
13+
A known issue can list one or both of the following entries:
1214

1315
* **Affected platforms:**
1416

@@ -18,3 +20,66 @@ Items can have one or both of the following entries:
1820

1921
Some known issues have a workaround.
2022
Sometimes, they are discovered later and added over time.
23+
24+
.. version-filter::
25+
:container: dl/dt
26+
:tags: [("wontfix", "Won't fix")]
27+
28+
.. page-filter::
29+
:name: issues
30+
31+
wontfix Won't fix
32+
33+
List of known issues for |addon|
34+
********************************
35+
36+
.. _ncs_matter_known_issue_dac_priv_key_its_kmu:
37+
38+
.. rst-class:: simple v1-0-0
39+
40+
KRKNWK-22680: DAC private key stored in PSA ITS instead of CRACEN KMU on nRF54L
41+
On nRF54L Series SoCs with a Key Management Unit (KMU), |addon| v1.0.0 selects PSA Internal Trusted Storage (ITS) by default as the DAC private key backend instead of the CRACEN KMU.
42+
The Matter Kconfig defaults depend on the ``CRACEN_KMU`` symbol, which is not defined in |NCS| v3.4.0.
43+
The build therefore silently falls back to :kconfig:option:`CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_ITS`, while the documentation describes KMU storage as the default (see :ref:`matter_platforms_security_dac_priv_key_kmu`).
44+
45+
On the first boot with factory data, ``FactoryDataProvider`` moves the DAC private key out of the factory data partition exactly once.
46+
The key cannot be exported or copied to another backend.
47+
48+
When commissioning or attestation may fail
49+
50+
* KMU - ITS mismatch (recoverable with a fixed firmware):
51+
The device previously ran in-tree |NCS| Matter firmware (up to |NCS| v3.4.0) that stored the DAC private key in the KMU, and was updated over SMP or Matter OTA to |addon| v1.0.0 firmware that looks for the key in ITS.
52+
Existing Matter fabrics continue to work, but **new commissioning fails** after a factory reset or when adding another administrator.
53+
Device attestation fails with an Operational Credentials error (for example ``OpCreds: Failed AttestationRequest request with IM error 0x01 (err = ac)``).
54+
This path is **deterministic** on every affected nRF54L device when migrating from pre–|addon| Matter releases.
55+
56+
* ITS - KMU mismatch (commissioning failure on v1.0.0; mitigated in v1.0.1):
57+
The device **first booted** with |addon| v1.0.0 (or any firmware that stored the DAC key in ITS).
58+
|addon| v1.0.0 firmware that defaults to KMU storage cannot use that key; commissioning fails the same way as the KMU→ITS case.
59+
|addon| v1.0.1 and newer sdk-connectedhomeip revisions can boot with KMU migration selected when :kconfig:option:`CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_KMU_ITS_FALLBACK` is enabled (default): the ITS copy is used for attestation signing and a warning is logged.
60+
Automatic migration from ITS to KMU is still not supported.
61+
If such a device receives a **factory reset** while :kconfig:option:`CONFIG_CHIP_FACTORY_RESET_ERASE_SETTINGS` is enabled and the DAC key exists only in ITS, the settings partition is erased together with the ITS copy of the DAC private key, and the **DAC private key is permanently lost**.
62+
The device can no longer pass device attestation until it is re-provisioned with new factory data.
63+
64+
**Affected platforms:** nRF54L15 and nRF54LM20A/B Series SoCs
65+
66+
**Workaround:**
67+
68+
Pick the step that matches where the DAC private key was stored on **first** migration (see :ref:`migration_101`).
69+
70+
* **Key in CRACEN KMU** (typical after in-tree |NCS| Matter, then a broken update to |addon| v1.0.0):
71+
Deploy |addon| v1.0.1 or newer firmware with KMU migration selected (``CRACEN_LIB_KMU`` defaults restored).
72+
Do **not** force :kconfig:option:`CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_ITS`; ITS storage cannot read a KMU-resident key and commissioning stays broken.
73+
See :ref:`migration_101` Path A.
74+
75+
* **Key in PSA ITS** (typical when |addon| v1.0.0 completed the first migration on nRF54L):
76+
Deploy |addon| v1.0.1 or newer with :kconfig:option:`CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_KMU_ITS_FALLBACK` left enabled (default) so attestation uses the ITS copy, or keep an explicit ITS migration destination until re-provisioning:
77+
78+
.. code-block:: kconfig
79+
80+
CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_ITS=y
81+
# CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_KMU is not set
82+
83+
See :ref:`migration_101` Path B.
84+
85+
* Before updating firmware on nRF54L series devices, confirm the effective backend in the build output (``CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_ITS`` vs ``CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_KMU`` in :file:`build/*/zephyr/.config`).

‎docs/migration/migration_guide_v1.0.1.rst‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
:orphan:
2+
3+
.. _migration_101:
4+
5+
Migration notes for |addon| v1.0.1
6+
##################################
7+
8+
.. contents::
9+
:local:
10+
:depth: 3
11+
12+
This document describes changes required or recommended for migrating your Matter application from |addon| v1.0.0 to v1.0.1.
13+
14+
.. _migration_101_required:
15+
16+
Required changes
17+
****************
18+
19+
Identify where the DAC private key is stored
20+
============================================
21+
22+
Use the **first firmware** that completed factory-data migration on each device, not the Kconfig defaults of your current project alone.
23+
24+
+---------------------------+---------------------------------------------------------------------+
25+
| First boot that migrated | DAC private key location |
26+
| the DAC key | |
27+
+===========================+=====================================================================+
28+
| In-tree |NCS| Matter | CRACEN KMU (expected on nRF54L with factory data) |
29+
| (through |NCS| v3.4.0) | |
30+
+---------------------------+---------------------------------------------------------------------+
31+
| |addon| v1.0.0 on nRF54L | PSA ITS (:kconfig:option:`CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_ITS`) |
32+
+---------------------------+---------------------------------------------------------------------+
33+
34+
You can confirm the **current** firmware intent in :file:`build/<image>/zephyr/.config`:
35+
36+
* :kconfig:option:`CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_KMU=y` - firmware migrates new keys to KMU.
37+
* :kconfig:option:`CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_ITS=y` - firmware migrates new keys to ITS.
38+
* :kconfig:option:`CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_KMU_ITS_FALLBACK=y` - when KMU is selected, an existing ITS copy may still be used for signing (default in v1.0.1).
39+
40+
Choose a migration path
41+
=======================
42+
43+
Path A — Device previously on in-tree |NCS| Matter (key in KMU), updated to v1.0.0
44+
----------------------------------------------------------------------------------
45+
46+
**Symptom:** Re-commissioning after performing factory reset fails after DFU.
47+
Attestation errors such as ``OpCreds: Failed AttestationRequest request with IM error 0x01 (err = ac)`` occur.
48+
Existing Matter fabrics may still operate.
49+
50+
**Action:** Deploy |addon| v1.0.1 (or newer) firmware with KMU defaults restored.
51+
52+
Path B — Product shipped or first flashed with |addon| v1.0.0 on nRF54L series device (key in ITS)
53+
--------------------------------------------------------------------------------------------------
54+
55+
Until each unit is re-provisioned with new factory data (new DAC key and certificates), choose one of the following for **every** firmware image you ship to those devices.
56+
57+
**Option 1 — KMU defaults with ITS fallback (recommended for v1.0.1+ field updates):**
58+
59+
Use the normal nRF54L KMU migration settings and leave the :kconfig:option:`CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_KMU_ITS_FALLBACK` Kconfig option set to ``y`` (default).
60+
Commissioning and device attestation keep working because the stack detects the ITS copy at boot and uses it for signing while logging a warning.
61+
Plan re-provisioning when you want the key stored in KMU only.
62+
63+
**Option 2 — Explicit ITS backend:**
64+
65+
Keep the migration destination aligned with where the key already lives:
66+
67+
.. code-block:: kconfig
68+
69+
CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_ITS=y
70+
# CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_KMU is not set
71+
72+
Add this to :file:`prj.conf` or a board overlay and verify it in the merged :file:`.config` after building.
73+
74+
**Do not:**
75+
76+
* Disable :kconfig:option:`CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_KMU_ITS_FALLBACK` on KMU-default v1.0.1 firmware for these units unless you intend boot to stop until the ITS copy is removed or the device is re-provisioned.
77+
78+
* Perform a factory reset on firmware that erases settings (:kconfig:option:`CONFIG_CHIP_FACTORY_RESET_ERASE_SETTINGS`) while the DAC key exists only in ITS.
79+
That can **permanently erase** the DAC private key.
80+
81+
Path C — New development on v1.0.1+
82+
-----------------------------------
83+
84+
No Kconfig changes are required for new nRF54L devices that will boot v1.0.1 first: KMU remains the default when :kconfig:option:`CONFIG_CRACEN_LIB_KMU` is available.
85+
See :ref:`matter_platforms_security_dac_priv_key` for backend options.
86+
87+
Recommended validation
88+
======================
89+
90+
After changing DAC storage settings or migration firmware on nRF54L hardware:
91+
92+
#. Build and inspect :file:`build/<app>/zephyr/.config` for the expected :kconfig:option:`CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_*` symbol.
93+
#. On a test device, run through factory reset (if applicable) and full Matter commissioning, including device attestation.
94+
#. When migrating from older |NCS| Matter releases, include commissioning **after** SMP or Matter OTA in your release test plan (not only the DFU step).

‎docs/migration_guides.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
.. _migration_guides:
2+
3+
Migration notes
4+
###############
5+
6+
The |addon| provides migration notes for major releases to assist your transition from the previous release.
7+
8+
.. note::
9+
While all breaking changes are documented, the migration guides might not include the detailed migration steps for your use case.
10+
If you need help, contact Nordic Semiconductor through `DevZone`_.
11+
12+
.. toctree::
13+
:maxdepth: 1
14+
:glob:
15+
:caption: Matter add-on version migration notes
16+
17+
Matter add-on version migration notes
18+
*************************************
19+
20+
* :ref:`migration_101`
21+
* :ref:`migration_200`

‎docs/release_notes.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,4 +37,5 @@ The Matter fork in the |NCS| (``sdk-connectedhomeip``) contains all commits from
3737
:caption: Contents
3838
:glob:
3939

40+
release_notes/release_notes_v101.rst
4041
release_notes/release_notes_v100.rst

‎docs/release_notes/release_notes_v101.rst‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
.. _release_notes_v101:
2+
3+
Release notes for |addon| v1.0.1
4+
################################
5+
6+
This page tracks changes and updates as compared to the latest official release.
7+
For more information refer to the following section.
8+
For the list of potential issues, see the :ref:`ncs_matter_known_issues` page.
9+
10+
Devices that first ran |addon| v1.0.0 on nRF54L hardware may have the DAC private key in PSA ITS; v1.0.1 can still commission those units when ITS fallback is enabled (default)—see :ref:`migration_101` before changing Kconfig or provisioning flows on production units.
11+
12+
Changelog
13+
*********
14+
15+
* Fixed the issue where on nRF54L Series SoCs, |addon| v1.0.0 could store the Device Attestation Certificate (DAC) private key in PSA ITS instead of the CRACEN Key Management Unit (KMU) when built against |NCS| ``v3.4.0`` release.
16+
Matter Kconfig used the ``CRACEN_KMU`` symbol, which is undefined in that |NCS| ``v3.4.0`` release, so the build silently selected :kconfig:option:`CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_ITS`.
17+
That broke device attestation and re-commissioning after SMP or Matter OTA from in-tree |NCS| Matter firmware that had already moved the DAC key to the KMU.
18+
See :ref:`ncs_matter_known_issue_dac_priv_key_its_kmu`.
19+
20+
* Added boot-time handling when KMU migration is configured but the DAC private key is still present in PSA ITS.
21+
With :kconfig:option:`CONFIG_CHIP_CRYPTO_PSA_DAC_PRIV_KEY_KMU_ITS_FALLBACK` enabled (default), the device logs a warning, continues boot, and signs device attestation with the ITS key.
22+
With fallback disabled, boot stops instead of failing attestation later or risking silent misconfiguration.
23+
Automatic migration from ITS to KMU is not supported; re-provision when the key should live in KMU only (see :ref:`migration_101`).

‎docs/versions.json‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
11
[
2-
"1.0.0"
2+
"1.0.99",
3+
"1.0.1",
4+
"1.0.0",
5+
"1.0.99-preview-thread-hdr",
6+
"1.0.99-preview-nrf7120"
37
]

0 commit comments

Comments
 (0)