doc: add application development section

doc/application_development/application_development.rst

@@ -0,0 +1,15 @@
+.. _application_development:
+
+Application development
+#######################
+
+This section explores advanced topics to help you develop Sidewalk applications suitable for production use.
+Use it after setting up the development environment and running the :ref:`sidewalk_end_device` sample.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Subpages:
+
+   sidewalk_configuration.rst
+   secure_storage.rst
+   bootloader_configuration.rst

doc/application_development/bootloader_configuration.rst

@@ -0,0 +1,61 @@
+.. _bootloader_configuration:
+
+Bootloader configuration
+########################
+
+This page covers the current bootloader configuration recommendations for Sidewalk products based on nRF Connect SDK.
+When migrating existing products, check the migration guides and release notes for compatibility information.
+
+Secure bootloader chain
+************************
+
+Implement a secure boot chain with one of the following layouts, as described in the `Secure bootloader chain`_ documentation:
+
+* Non-upgradable MCUboot used as the immutable bootloader, with its flash region locked from modification.
+  Enable MCUboot with the sysbuild Kconfig option ``SB_CONFIG_BOOTLOADER_MCUBOOT=y``.
+* An immutable first-stage bootloader, `nRF Secure Immutable Bootloader (NSIB)`_, followed by upgradable MCUboot as the second-stage bootloader.
+  This layout allows both application updates and MCUboot updates while keeping an immutable root of trust.
+  Enable it with the sysbuild Kconfig options ``SB_CONFIG_SECURE_BOOT_APPCORE=y`` and ``SB_CONFIG_BOOTLOADER_MCUBOOT=y``.
+
+In either case, make sure the first-stage bootloader is locked from modification.
+On the nRF54L Series platforms, use the ``UICR.BOOTCONF`` register to lock the bootloader area.
+
+Image signature verification
+****************************
+
+Prefer Ed25519 signature type for application image verification in MCUboot.
+
+Enable Ed25519 for MCUboot with the sysbuild Kconfig option ``SB_CONFIG_BOOT_SIGNATURE_TYPE_ED25519=y``.
+In a :file:`Kconfig.sysbuild` file, this is selected through the ``BOOT_SIGNATURE_TYPE`` choice.
+
+MCUboot public key storage
+**************************
+
+Store public keys used for application image verification in the Key Management Unit (KMU).
+This avoids compiling the active verification key directly into the bootloader image and supports the key revocation policy.
+
+Enable the following sysbuild Kconfig options:
+
+* ``SB_CONFIG_MCUBOOT_SIGNATURE_USING_KMU=y``
+* ``SB_CONFIG_MCUBOOT_GENERATE_DEFAULT_KEY_FILE=y`` to generate the default KMU provisioning file from the configured signing key at build time.
+
+Optionally, configure the following MCUboot image Kconfig options:
+
+* ``CONFIG_BOOT_SIGNATURE_KMU_SLOTS=<count>`` to support multiple verification key generations.
+* ``CONFIG_BOOT_KEYS_REVOCATION=y`` to revoke older key generations after a valid update signed with a newer key.
+
+Downgrade protection
+********************
+
+Enable downgrade protection so an attacker cannot install older firmware that reintroduces fixed vulnerabilities.
+Use one of the following approaches:
+
+* Software-based MCUboot downgrade protection.
+  Enable overwrite-only mode with the sysbuild Kconfig option ``SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY=y`` and enable downgrade checks with the MCUboot Kconfig option ``CONFIG_MCUBOOT_DOWNGRADE_PREVENTION=y``.
+  Set the application image version with ``CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION`` as part of the release process.
+* Hardware-based downgrade protection using a monotonic counter.
+  Enable the downgrade protection with the sysbuild Kconfig option ``SB_CONFIG_MCUBOOT_HARDWARE_DOWNGRADE_PREVENTION=y``.
+  Configure the number of available hardware counter slots with the sysbuild Kconfig option ``SB_CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_SLOTS``, and the current counter value with the sysbuild Kconfig option ``SB_CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_VALUE``.
+
+The hardware-based approach provides stronger protection against downgrade attacks, but it limits the number of firmware updates to the number of available hardware counter slots.
+For that reason, it should be enabled with caution, depending on the expected firmware update frequency.

doc/application_development/secure_storage.rst

@@ -0,0 +1,73 @@
+.. _secure_storage:
+
+Secure storage
+##############
+
+The Sidewalk Platform Abstraction Layer for nRF Connect SDK supports a trusted storage mechanism to securely store persistent Sidewalk keys.
+The feature is enabled by default with the ``CONFIG_SIDEWALK_CRYPTO_PSA_KEY_STORAGE`` Kconfig option.
+
+You can configure the trusted storage to store the keys in one of the following locations:
+
+* Key Management Unit (KMU) - Enabled by default with the ``CONFIG_SIDEWALK_CRYPTO_PSA_KEY_STORAGE_KMU`` Kconfig option.
+* Settings partition - Used when the KMU option is disabled.
+
+Persistent Sidewalk keys
+************************
+
+The Sidewalk stack uses two classes of persistent keys:
+
+* Device identity private keys provisioned through the Sidewalk manufacturing page or generated by the on-device certification flow.
+  These keys correspond to the manufacturing store ``SID_PAL_MFG_STORE_DEVICE_PRIV_ED25519`` and ``SID_PAL_MFG_STORE_DEVICE_PRIV_P256R1`` values.
+* Runtime Sidewalk protocol master keys written by the Sidewalk stack through the Platform Abstraction Layer (PAL) key-value storage interface.
+  These keys are symmetric keys used to derive traffic keys for the network, application, and device-to-device (D2D) layers.
+
+The table below lists the persistent Sidewalk keys and their usage.
+
+.. list-table:: Persistent Sidewalk keys
+   :header-rows: 1
+   :widths: 30 22 32 16
+
+   * - PSA key ID
+     - Key type
+     - Use
+     - KMU slot usage
+   * - ``SID_CRYPTO_MFG_ED25519_PRIV_KEY_ID``
+     - ED25519 private key
+     - Device identity key: proof of possession of the Ed25519 device certificate during registration and certification.
+       Used to sign messages with ECDSA.
+     - Two slots, starting at offset 0.
+   * - ``SID_CRYPTO_MFG_SECP_256R1_PRIV_KEY_ID``
+     - secp256r1 private key
+     - Device identity key: proof of possession of the P-256 device certificate during registration and certification.
+       Used to sign messages with ECDSA.
+     - Two slots, starting at offset 2.
+   * - ``SID_CRYPTO_KV_WAN_MASTER_KEY_ID``
+     - AES-128 key
+     - Network Primary Key, used to derive network-layer keys for TXID obfuscation, network payload encryption, time synchronization authentication, and join response protection.
+       The key derivation is based on the CMAC algorithm.
+     - One slot at offset 4.
+   * - ``SID_CRYPTO_KV_APP_KEY_KEY_ID``
+     - AES-128 key
+     - Application Primary Key, used to derive application-layer keys for Endpoint-to-Application Server payload encryption and application registration.
+       The key derivation is based on the CMAC algorithm.
+     - One slot at offset 5.
+   * - ``SID_CRYPTO_KV_D2D_KEY_ID``
+     - AES-128 key
+     - D2D Primary Key, used to derive D2D keys for encrypted communication between the Amazon Sidewalk Mobile SDK and the Endpoint.
+       The key derivation is based on the CMAC algorithm.
+     - One slot at offset 6.
+
+Recommended configuration
+*************************
+
+When developing new products, make sure you have the following Kconfig options enabled to use the KMU as the key storage location:
+
+* ``CONFIG_SIDEWALK_CRYPTO_PSA_KEY_STORAGE=y``
+* ``CONFIG_SIDEWALK_CRYPTO_PSA_KEY_STORAGE_KMU=y``
+
+If you use the KMU for other purposes, and the default Sidewalk KMU slot range overlaps with other product keys, you can configure the start slot with the ``CONFIG_SIDEWALK_CRYPTO_PSA_KEY_STORAGE_KMU_SLOT_START`` Kconfig option to avoid conflicts.
+
+.. note::
+   Keep ``CONFIG_SIDEWALK_CRYPTO_PSA_KEY_STORAGE_KMU=n`` only for already-provisioned products that stored Sidewalk keys with an earlier firmware version.
+   Changing the storage backend changes where the keys are stored and which PSA key IDs are used, so existing keys will not be found.
+   Refer to the migration guides for more details.

doc/application_development/sidewalk_configuration.rst

@@ -0,0 +1,44 @@
+.. _sidewalk_configuration:
+
+Sidewalk configuration
+######################
+
+This page describes the most important Kconfig options for configuring Sidewalk features.
+Sample-specific options, such as application variant selection and automatic start behavior, are documented in the :ref:`sidewalk_end_device` sample variants.
+
+Core protocol support
+*********************
+
+* ``CONFIG_SIDEWALK`` - Enables Amazon Sidewalk support.
+
+* ``CONFIG_SIDEWALK_DFU`` - Enables the Sidewalk Device Firmware Update (DFU) support.
+
+* ``CONFIG_SIDEWALK_DFU_SERVICE_BLE`` - Enables the Zephyr SMP service over Bluetooth LE for new firmware image upload.
+
+* ``CONFIG_SIDEWALK_MFG_STORAGE_SUPPORT_HEX_v7`` - Enables support for Sidewalk manufacturing HEX formats version 7 and earlier.
+  Use this option only when the application needs to consume legacy manufacturing data format.
+
+* ``CONFIG_SIDEWALK_ON_DEV_CERT`` - Enables the on-device certification shell.
+
+Physical link selection
+***********************
+
+* ``CONFIG_SIDEWALK_SUBGHZ_SUPPORT`` - Enables Sidewalk libraries with Bluetooth LE, LoRa, and FSK support.
+  Disabling this option results in using Sidewalk libraries with only Bluetooth LE support.
+  While this results in a smaller memory footprint for the application, it also limits its functionality, as connectivity over LoRa or FSK is not available.
+  The option is enabled by default when the devicetree selects a LoRa transceiver.
+
+* ``CONFIG_SIDEWALK_LINK_MASK`` - Selects the default physical link type used when Sidewalk starts.
+  The following choices are available:
+
+  * ``CONFIG_SIDEWALK_LINK_MASK_BLE`` - Select the Bluetooth LE link.
+
+  * ``CONFIG_SIDEWALK_LINK_MASK_FSK`` - Select the Sub-GHz link for FSK.
+
+  * ``CONFIG_SIDEWALK_LINK_MASK_LORA`` - Select the Sub-GHz link for LoRa.
+
+Secure storage
+**************
+
+Use ``CONFIG_SIDEWALK_CRYPTO_PSA_KEY_STORAGE`` to enable secure storage for persistent Sidewalk keys.
+For recommended persistent key storage settings, see :ref:`secure_storage`.

doc/includes/include_kconfig_common.txt

@@ -1,11 +1,3 @@
-* ``CONFIG_SIDEWALK`` -- Enables support for the Sidewalk protocol and its dependencies.
-
-* ``CONFIG_SIDEWALK_SUBGHZ_SUPPORT`` -- Enables using Sidewalk libraries with Bluetooth LE, LoRa and FSK support.
-  Disabling this option results in using Sidewalk libraries with only Bluetooth LE support.
-  While this results in a smaller memory footprint for the application, it also limits its functionality, as connectivity over LoRa or FSK is not available.
-
-* ``CONFIG_SIDEWALK_DFU`` -- Enables the nRF Connect SDK bootloader and DFU service over Bluetooth LE.
-
 * Application variant is selected by the ``SID_END_DEVICE`` Kconfig choice (mutually exclusive options below).
 
    * ``CONFIG_SID_END_DEVICE_HELLO`` -- Enables the Hello Sidewalk application.
@@ -19,23 +11,9 @@
 * ``CONFIG_SID_END_DEVICE_CLI`` -- Enables Sidewalk CLI.
   To see the list of available commands, flash the sample and type ``sid help``.
 
-* ``CONFIG_SIDEWALK_ON_DEV_CERT`` -- Enables the on-device certification Shell.
-
-* ``CONFIG_SIDEWALK_CRYPTO_PSA_KEY_STORAGE`` - Enables secure storage for persistent Sidewalk keys.
-
-* ``CONFIG_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.
   If needed, the Bluetooth LE connection request is sent automatically.
 
 * ``CONFIG_SID_END_DEVICE_PERSISTENT_LINK_MASK`` - Enables persistent link mask.
-
-* ``CONFIG_SIDEWALK_LINK_MASK`` - Choose the default physical link type for Sidewalk connection to start with
-
-   * ``CONFIG_SIDEWALK_LINK_MASK_BLE`` -- Choose Bluetooth Low Energy link.
-
-   * ``CONFIG_SIDEWALK_LINK_MASK_FSK`` -- Choose Sub-GHz link for FSK.
-
-   * ``CONFIG_SIDEWALK_LINK_MASK_LORA`` -- Choose Sub-GHz link for LORA.

doc/index.rst

@@ -43,6 +43,7 @@ Browse the content by referring to the following pages:
 
    setting_up_sidewalk_environment/setting_up_environment.rst
    samples/samples_list.rst
+   application_development/application_development.rst
    location_services.rst
    testing.rst
    compatibility_matrix.rst

doc/links.rst

@@ -28,6 +28,7 @@
 .. _nRF Connect SDK software maturity levels documentation: https://docs.nordicsemi.com/bundle/ncs-3.3.0/page/nrf/releases_and_maturity/software_maturity.html
 .. _Migrating partition configuration from Partition Manager to devicetree (DTS): https://docs.nordicsemi.com/bundle/ncs-3.3.0/page/nrf/releases_and_maturity/migration/migration_partitions.html
 .. _nRF Secure Immutable Bootloader (NSIB): https://docs.nordicsemi.com/bundle/ncs-3.3.0/page/nrf/samples/bootloader/README.html
+.. _Secure bootloader chain: https://docs.nordicsemi.com/bundle/ncs-3.3.0/page/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader.html
 
 .. nordicsemi.com
 

doc/samples/sid_end_device.rst

@@ -147,17 +147,7 @@ Secure Key Storage support
 ==========================
 
 The Sidewalk Platform Abstraction Layer for nRF Connect SDK supports a trusted storage mechanism to securely store non-volatile Sidewalk keys.
-The feature is enabled by default with the ``CONFIG_SIDEWALK_CRYPTO_PSA_KEY_STORAGE`` Kconfig option.
-
-Configure the trusted storage to store the keys in one of the following locations:
-
-* Key Management Unit (KMU) - Enabled by default with the ``CONFIG_SIDEWALK_CRYPTO_PSA_KEY_STORAGE_KMU`` Kconfig option.
-* Settings partition - Used when the KMU option is disabled.
-
-.. note::
-
-   Once keys are moved to the trusted storage, you cannot read them back and move into MFG storage.
-   For this reason, do not update your firmware to versions that do not support the trusted storage, or use a different storage backend.
+Read :ref:`secure_storage` for more details.
 
 Device Firmware Upgrade support
 ===============================

samples/sid_end_device/Kconfig.sysbuild

@@ -18,6 +18,12 @@ choice MCUBOOT_MODE
 	default MCUBOOT_MODE_OVERWRITE_ONLY
 endchoice
 
+config MCUBOOT_SIGNATURE_USING_KMU
+	default y
+
+config MCUBOOT_GENERATE_DEFAULT_KEY_FILE
+	default y
+
 config DFU_MULTI_IMAGE_PACKAGE_BUILD
 	default y