doc: describe new provisioning module and security

[KRKNWK-19108] [KRKNWK-18440] Signed-off-by: Krzysztof Taborowski <[email protected]> Co-authored-by: Anna Wojdyło <[email protected]>
nrfconnect · Sep 13, 2024 · 34856b2 · 34856b2
1 parent ae13e3c
commit 34856b2
Show file tree

Hide file tree

Showing 10 changed files with 97 additions and 11 deletions.
diff --git a/Kconfig b/Kconfig
@@ -18,7 +18,7 @@ config SIDEWALK_SUBGHZ_SUPPORT
 	bool "Enable Sub-GHz link type support in Sidewalk libraries"
 	default y
 	help
-	  Use Sidewalk with support for BLE, LoRa and FSK
+	  Use Sidewalk with support for BLE, LoRa and FSK.
 
 if SIDEWALK_SUBGHZ_SUPPORT
 
@@ -27,7 +27,7 @@ config SIDEWALK_SUBGHZ_TRIM_CAP_VAL
 	range 0x0 0xFFFF
 	default 0x1212
 	help
-	  The value of the trim cap. Default value works for Semtech SX1262 shield 
+	  The value of the trim cap. Default value works for Semtech SX1262 shield.
 
 endif 
 
@@ -94,7 +94,7 @@ config SIDEWALK_HEAP_SIZE
 config SIDEWALK_TRACE_HEAP
 	bool "Trace allocation and free of Sidewalk heap"
 	help
-	  Add debug log to every alloc and free operation on Sidewalk heap
+	  Add debug log to every alloc and free operation on Sidewalk heap.
 
 config SID_HAL_PROTOCOL_MEMORY_SZ
 	int
@@ -218,7 +218,7 @@ config DEPRECATED_SIDEWALK_MFG_STORAGE
 	imply FLASH
 	help
 	  Previous Sidewalk manufacturing storage module
-	  This implementation is DEPRECATED
+	  This implementation is DEPRECATED.
 
 config SIDEWALK_MFG_STORAGE_SUPPORT_HEX_v7
 	bool "Enable support for old Sidewalk manufaturing hex format"
@@ -227,12 +227,17 @@ config SIDEWALK_MFG_STORAGE_SUPPORT_HEX_v7
 	help
 	  Sidewalk manifactuing module uses version 8, with tlv format
 	  Old fromats - version7 and before, are based on memory offsets
-	  and will be supported after enablig this configuration
+	  and will be supported after enabling this configuration.
 
 config SIDEWALK_CRYPTO_PSA_KEY_STORAGE
 	bool "Enable psa crypto storage for persistent Sidewalk keys [EXPERIMENTAL]"
 	default SIDEWALK
 	select EXPERIMENTAL
+	help
+	  Use secure key storage for persistent Sidewalk keys.
+	  Once you flash the firmware with this config enabled,
+	  it must be enabled in every subsequent build.
+	  Otherwise, the keys will not be found and Sidewalk will not start.
 
 config SIDEWALK_PAL_RADIO_SOURCE
 	bool "Build sub-GHz radio driver from sources [EXPERIMENTAL]"

diff --git a/doc/includes/include_building_and_running.txt b/doc/includes/include_building_and_running.txt
@@ -4,7 +4,7 @@ This sample can be found under :file:`samples/sid_end_device`.
    Before you flash your Sidewalk sample, make sure you have completed the following:
 
       * You downloaded the Sidewalk repository and updated west according to the :ref:`dk_building_sample_app` section.
-      * You provisioned your device during the :ref:`setting_up_sidewalk_product`.
+      * You provisioned your device during the :ref:`setting_up_sidewalk_prototype`.
 
    This step needs to be completed only once.
    You do not have to repeat it for every sample rebuild.

diff --git a/doc/includes/include_kconfig_common.txt b/doc/includes/include_kconfig_common.txt
@@ -21,6 +21,10 @@
 
 * ``CONFIG_SIDEWALK_ON_DEV_CERT`` -- Enables the on-device certification Shell.
 
+* ``SIDEWALK_CRYPTO_PSA_KEY_STORAGE`` - Enables secure storage for persistent Sidewalk keys.
+
+* ``SIDEWALK_MFG_STORAGE_SUPPORT_HEX_v7`` - Enables support for Sidewalk manufacturing HEX in version 7 and below.
+
 * ``CONFIG_SID_END_DEVICE_AUTO_START`` -- Enables an automatic Sidewalk initialization and start.
 
 * ``CONFIG_SID_END_DEVICE_AUTO_CONN_REQ`` -- Enables an automatic connection request before sending a message.

diff --git a/doc/links.rst b/doc/links.rst
@@ -24,6 +24,8 @@
 .. _NCS testing applications: https://docs.nordicsemi.com/bundle/ncs-2.7.0/page/nrf/test_and_optimize.html
 .. _Installing the nRF Connect SDK: https://docs.nordicsemi.com/bundle/ncs-2.7.0/page/nrf/installation/install_ncs.html
 .. _Board Configurator: https://docs.nordicsemi.com/bundle/nrf-connect-board-configurator/page/index.html
+.. _Hardware unique key: https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/libraries/security/hw_unique_key.html#lib-hw-unique-key
+.. _Hardware flash write protection: https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/libraries/security/bootloader/fprotect.html
 
 .. ncs fixed links(do not update them)
 

diff --git a/doc/releases_and_migration.rst b/doc/releases_and_migration.rst
@@ -21,4 +21,5 @@ See information about the latest release notes and the available migration guide
    :glob:
    :caption: Migration guides:
 
+   releases_and_migration/migration_guide_v280.rst
    releases_and_migration/migration_guide_v260.rst
diff --git a/doc/releases_and_migration/migration_guide_v280.rst b/doc/releases_and_migration/migration_guide_v280.rst
@@ -0,0 +1,60 @@
+.. _migration_guide_v280:
+
+Migration guide for the v2.8.0 of the nRF Connect SDK
+*****************************************************
+
+.. contents::
+   :local:
+   :depth: 2
+
+Starting with the v2.8.0 release of the `nRF Connect SDK`_, there is a new Sidewalk provisioning module.
+For an overview of changes, read the following sections.
+
+Reasons for change
+==================
+
+The new provisioning module enhances security by:
+
+* Moving non-volatile Sidewalk keys to secure key storage.
+* Protecting the manufacturing data partition from write operations.
+* Always using the Key-Value Store version of manufacturing data.
+
+Security enhancements details
+=============================
+
+Access to the manufacturing data is unified within the application, ensuring consistency for prototyping and manufacturing flows.
+The MFG parser module is launched at initialization and writes the manufacturing data to flash (secure key storage) in the same way as the device certification module.
+The process is triggered only once, at the first application start after flashing the :file:`Nordic_MFG.hex` file.
+The following logs are generated:
+
+.. code-block:: console
+
+   [00:00:00.004,502] <inf> sid_mfg: Need to parse mfg data
+   [00:00:00.009,993] <inf> sid_mfg_parser_v8: MFG_ED25519 import success
+   [00:00:00.014,900] <inf> sid_mfg_parser_v8: MFG_SECP_256R1 import success
+   [00:00:00.054,505] <inf> sid_mfg: Successfully parsed mfg data
+
+The secure key storage is based on the `Hardware unique key`_ security library.
+After keys are imported into secure key storage, it is impossible to read their raw values.
+Therefore, once secure key storage is enabled in the firmware, it must remain enabled in all subsequent firmware versions. 
+This feature is enabled by default in all Sidewalk samples.
+
+The hardware flash write protection is based on the `Hardware flash write protection`_ security library.
+The protection is applied during Sidewalk initialization and remains irreversible until reset.
+This feature is disabled in the :ref:`variant_sidewalk_dut` sample to allow writing of manufacturing data using on-device certification commands.
+
+Aligning your application to the new model
+==========================================
+
+The new provisioning module implementation includes the following changes:
+
+* In the :file:`app_mfg_config.h` file, the function ``app_mfg_cfg_is_valid()`` was renamed to ``app_mfg_cfg_is_empty()``.
+
+* The ``CONFIG_SIDEWALK_MFG_STORAGE_SUPPORT_HEX_v7`` Kconfig option adds support for older Sidewalk manufacturing HEX formats (version 7 and below). 
+  You can disable this configuration when using the latest manufacturing flash.
+
+Using old provisioning module
+=============================
+
+It is recommended to use the new provisioning module implementation. 
+However, you can still enable the old module using the ``CONFIG_DEPRECATED_SIDEWALK_MFG_STORAGE`` Kconfig option. 
diff --git a/doc/samples/sid_end_device.rst b/doc/samples/sid_end_device.rst
@@ -129,6 +129,18 @@ For example:
     Selecting a build type is optional.
     However, if the build type is not selected, the ``debug`` build type is used by default.
 
+Secure Key Storage support
+==========================
+
+The Sidewalk Platform Abstraction Layer for nRF Connect SDK supports a secure key storage mechanism for Sidewalk keys,
+ensuring they are stored persistently and confidentially.
+The feature is enabled by default with the ``CONFIG_SIDEWALK_CRYPTO_PSA_KEY_STORAGE`` Kconfig option.
+
+.. note::
+
+   Once secure keys are moved to secure key storage, it is impossible to retrieve them in plain text.
+   Therefore, you must not update your firmware to versions that do not support secure key storage.
+
 Device Firmware Upgrade support
 ===============================
 

diff --git a/doc/samples/variants/hello.rst b/doc/samples/variants/hello.rst
@@ -357,7 +357,7 @@ Receiving message from AWS MQTT
 
    * ``<wireless-device-id>`` is the Wireless Device ID of your Sidewalk Device.
 
-     You can find it in the :file:`WirelessDevice.json` file, generated with the :file:`Nordic_MFG.hex` file during :ref:`setting_up_sidewalk_product`.
+     You can find it in the :file:`WirelessDevice.json` file, generated with the :file:`Nordic_MFG.hex` file during :ref:`setting_up_sidewalk_prototype`.
      If you have sent a message before, you can also find your Wireless Device ID in the messages sent from your device to AWS.
 
    * ``<payload-data>`` is base64 encoded.

diff --git a/doc/setting_up_sidewalk_environment/setting_up_environment.rst b/doc/setting_up_sidewalk_environment/setting_up_environment.rst
@@ -14,4 +14,4 @@ Once completed, you will be able to run a sample application and test it with Si
    requirements.rst
    setting_up_hardware.rst
    setting_up_sdk.rst
-   setting_up_sidewalk_product.rst
+   setting_up_sidewalk_prototype.rst
diff --git a/...vironment/setting_up_sidewalk_product.rst → ...ronment/setting_up_sidewalk_prototype.rst b/...vironment/setting_up_sidewalk_product.rst → ...ronment/setting_up_sidewalk_prototype.rst
@@ -1,14 +1,16 @@
-.. _setting_up_sidewalk_product:
+.. _setting_up_sidewalk_prototype:
 
-Setting up your Sidewalk product
-################################
+Setting up your Sidewalk prototype
+##################################
 
 .. contents::
    :local:
    :depth: 2
 
 To correctly set up your Sidewalk device, first you have to onboard it.
 Complete the `Onbarding your Sidewalk devices`_ steps described in the Amazon Sidewalk documentation.
+This section details the prototyping flow for onboarding your Sidewalk devices. 
+In this flow, you will provision devices individually, allowing you to learn more about prototyping your application.
 
 Generate provisioning
 *********************