sysbuild: Add AP-Protect settings

Add the following sysbuild settings which add corresponding
Kconfig settings for all the images in the build:

- SB_CONFIG_APPROTECT_USE_UICR
- SB_CONFIG_APPROTECT_LOCK
- SB_CONFIG_APPROTECT_USER_HANDLING
- SB_CONFIG_SECURE_APPROTECT_USE_UICR
- SB_CONFIG_SECURE_APPROTECT_LOCK
- SB_CONFIG_SECURE_APPROTECT_USER_HANDLING

Update AP-Protect documentation.

Signed-off-by: Markus Lassila <[email protected]>

Author: MarkusLassila

doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst

@@ -60,6 +60,15 @@ Build and configuration system
 
 * Added the ``SB_CONFIG_MCUBOOT_NRF53_MULTI_IMAGE_UPDATE`` sysbuild Kconfig option that enables updating the network core on the nRF5340 SoC from external flash.
 
+* Added AP-Protect sysbuild Kconfig options to enable the corresponding AP-Protect Kconfig options for all images in the build:
+
+  * ``SB_CONFIG_APPROTECT_LOCK`` for the :kconfig:option:`CONFIG_NRF_APPROTECT_LOCK` Kconfig option.
+  * ``SB_CONFIG_APPROTECT_USER_HANDLING`` for the :kconfig:option:`CONFIG_NRF_APPROTECT_USER_HANDLING` Kconfig option.
+  * ``SB_CONFIG_APPROTECT_USE_UICR`` for the :kconfig:option:`CONFIG_NRF_APPROTECT_USE_UICR` Kconfig option.
+  * ``SB_CONFIG_SECURE_APPROTECT_LOCK`` for the :kconfig:option:`CONFIG_NRF_SECURE_APPROTECT_LOCK` Kconfig option.
+  * ``SB_CONFIG_SECURE_APPROTECT_USER_HANDLING`` for the :kconfig:option:`CONFIG_NRF_SECURE_APPROTECT_USER_HANDLING` Kconfig option.
+  * ``SB_CONFIG_SECURE_APPROTECT_USE_UICR`` for the :kconfig:option:`CONFIG_NRF_SECURE_APPROTECT_USE_UICR` Kconfig option.
+
 * Removed the non-working support for configuring the NSIB signing key through the environmental or command line variable (``SB_SIGNING_KEY_FILE``) along with child image.
 
   .. note::
@@ -1298,6 +1307,7 @@ Documentation
   * The :ref:`dfu_tools_mcumgr_cli` page after it was removed from the Zephyr repository.
   * The :ref:`ug_nrf54h20_suit_soc_binaries` page.
   * The :ref:`ug_nrf54h20_suit_push` page documentating the SUIT push model-based update process.
+  * The :ref:`app_secure_approtect` section to the :ref:`app_approtect` page.
 
 * Restructured the :ref:`app_bootloaders` documentation and combined the DFU and bootloader articles.
   Additionally, created a new bootloader :ref:`bootloader_quick_start`.
@@ -1320,3 +1330,4 @@ Documentation
     This table replaces the subpage that was previously describing these features in more detail and was duplicating information available in other sections.
   * The :ref:`nrf_security_drivers_cracen` section with a reference to the :ref:`ug_nrf54l_cryptography` page.
   * The :ref:`ug_tfm` page with the correct list of samples demonstrating TF-M.
+  * The :ref:`app_approtect_ncs` section on the :ref:`app_approtect` page with details on setting the Kconfig options and register values to enable AP-Protect.

doc/nrf/security/ap_protect.rst

@@ -170,43 +170,144 @@ Based on the available implementation types, you can configure the access port p
 
 .. _app_approtect_ncs_lock:
 
-Enabling AP-Protect with :kconfig:option:`CONFIG_NRF_APPROTECT_LOCK`
-====================================================================
+Enabling software AP-Protect with :kconfig:option:`CONFIG_NRF_APPROTECT_LOCK`
+=============================================================================
+
+Setting the :kconfig:option:`CONFIG_NRF_APPROTECT_LOCK` Kconfig option to ``y`` and compiling the firmware enables the software access protection mechanism for SoCs of the nRF53 Series and the SoC revisions of the nRF52 Series that feature the hardware and software type of AP-Protect.
+
+Enabling the Kconfig option writes the debugger register in the ``SystemInit()`` function to lock the access port protection at every boot.
+In addition to this, the ``UICR.APPROTECT`` register should be written as instructed in :ref:`app_approtect_uicr_approtect`.
+
+.. note::
+    For multi-image builds, this Kconfig option needs to be set for the first image (usually a bootloader).
+    Otherwise, the software AP-Protect will not be sufficient as the debugger can be attached to the device after the first image opens the software AP-Protect with the :kconfig:option:`CONFIG_NRF_APPROTECT_USE_UICR` Kconfig option, which is the default value.
+
+    When using sysbuild, set the ``SB_CONFIG_APPROTECT_LOCK`` sysbuild Kconfig option, which enables the :kconfig:option:`CONFIG_NRF_APPROTECT_LOCK` Kconfig option for all images.
 
-Setting the :kconfig:option:`CONFIG_NRF_APPROTECT_LOCK` Kconfig option to ``y`` and compiling the firmware is enough to enable the access port protection mechanism for SoCs of the nRF53 Series and those SoCs of the nRF52 Series that feature the hardware and software type of AP-Protect.
-The access port protection configured in this way cannot be disabled without erasing the flash.
+.. important::
+    On the nRF91x1 Series devices, the register setting related to the :kconfig:option:`CONFIG_NRF_APPROTECT_LOCK` Kconfig option does not persist in System ON IDLE mode.
+    You must lock the ``UICR.APPROTECT`` register to enable the hardware AP-Protect mechanism as instructed in :ref:`app_approtect_uicr_approtect`.
 
 .. _app_approtect_ncs_user_handling:
 
-Enabling AP-Protect with :kconfig:option:`CONFIG_NRF_APPROTECT_USER_HANDLING`
-=============================================================================
+Enabling software AP-Protect with :kconfig:option:`CONFIG_NRF_APPROTECT_USER_HANDLING`
+======================================================================================
 
-Setting the :kconfig:option:`CONFIG_NRF_APPROTECT_USER_HANDLING` Kconfig option to ``y`` and compiling the firmware allows you to handle the state of AP-Protect at a later stage.
+Setting the :kconfig:option:`CONFIG_NRF_APPROTECT_USER_HANDLING` Kconfig option to ``y`` and compiling the firmware allows you to handle the state of the software AP-Protect at a later stage.
 This option in fact does not touch the mechanism and keeps it closed.
 
 You can use this option for example to implement the authenticated debug and lock.
 See the SoC or SiP hardware documentation for more information.
 
+.. note::
+    For multi-image builds, this Kconfig option has to be set for all images.
+    The default value is to open the device if the ``UICR.APPROTECT`` register is not set.
+    This allows the debugger to be attached to the device.
+
+    When using sysbuild, set the ``SB_CONFIG_APPROTECT_USER_HANDLING`` sysbuild Kconfig option, which enables the :kconfig:option:`CONFIG_NRF_APPROTECT_USER_HANDLING` Kconfig option for all images.
+
 .. _app_approtect_ncs_use_uicr:
 
-Enabling AP-Protect with :kconfig:option:`CONFIG_NRF_APPROTECT_USE_UICR`
-========================================================================
+Enabling software AP-Protect with :kconfig:option:`CONFIG_NRF_APPROTECT_USE_UICR`
+=================================================================================
 
-Setting the :kconfig:option:`CONFIG_NRF_APPROTECT_USE_UICR` Kconfig option to ``y`` and compiling the firmware makes the AP-Protect disabled by default.
+Setting the :kconfig:option:`CONFIG_NRF_APPROTECT_USE_UICR` Kconfig option to ``y`` and compiling the firmware makes the software AP-Protect disabled by default.
 This is the default setting in the |NCS|.
 
 You can start debugging the firmware without additional steps needed.
 
-Once you are done debugging, run the following command to enable the access port protection:
+.. _app_approtect_uicr_approtect:
+
+Enabling hardware AP-Protect by locking the ``UICR.APPROTECT`` register
+=======================================================================
+
+For the devices that are in a production environment, it is highly recommended to lock the ``UICR.APPROTECT`` register to prevent unauthorized access to the device.
+If the access port protection is configured this way, it cannot be disabled without erasing the flash memory.
+
+.. note::
+    This is the only mechanism supported by the nRF52 Series and the nRF9160 devices that do not support both hardware and software AP-Protect.
+
+To lock the ``UICR.APPROTECT`` register, complete the following steps:
 
 .. code-block:: console
 
    nrfjprog --rbp ALL
 
-This command enables the AP-Protect and resets the device.
+This command enables the hardware AP-Protect (and Secure AP-Protect) and resets the device.
+
+.. _app_secure_approtect:
+
+Secure AP-Protect
+=================
+
+With :ref:`Trusted Firmware-M (TF-M) <ug_tfm>` comes :ref:`security by separation <app_boards_spe_nspe>`, enabling a Secure Processing Environment (SPE) that is isolated from the Non-Secure Processing Environment (NSPE).
+TF-M is available for the nRF53 and nRF91 Series devices.
+
+While AP-Protect blocks access to all CPU registers and memories, Secure AP-Protect limits the CPU access to the non-secure side only.
+This allows debugging of the NSPE, while the SPE debugging is blocked.
+
+The following Kconfig options for enabling Secure AP-Protect are available for the nRF91x1 and nRF53 Series devices:
+
+* :kconfig:option:`CONFIG_NRF_SECURE_APPROTECT_LOCK`
+* :kconfig:option:`CONFIG_NRF_SECURE_APPROTECT_USER_HANDLING`
+* :kconfig:option:`CONFIG_NRF_SECURE_APPROTECT_USE_UICR`
+
+In addition, you can enable hardware Secure AP-Protect by setting the ``UICR.SECUREAPPROTECT`` register as instructed in :ref:`app_secure_approtect_uicr_approtect`.
+
+Enabling software Secure AP-Protect with :kconfig:option:`CONFIG_NRF_SECURE_APPROTECT_LOCK`
+-------------------------------------------------------------------------------------------
 
-To enable only the Secure AP-Protect, run the following command:
+Setting the :kconfig:option:`CONFIG_NRF_SECURE_APPROTECT_LOCK` Kconfig option to ``y`` and compiling the firmware enables the secure access protection mechanism for SoCs of the nRF53 Series.
+
+Enabling this Kconfig option writes the secure debugger register in the ``SystemInit()`` function to lock the secure access port protection at every boot.
+In addition to this, the ``UICR.SECUREAPPROTECT`` register should be written as instructed in :ref:`app_secure_approtect_uicr_approtect`.
+
+.. note::
+    For multi-image builds, this Kconfig option needs to be set for the first image (usually a bootloader).
+    Otherwise, the software Secure AP-Protect will not be sufficient as the debugger can be attached to the SPE after the first image opens the software Secure AP-Protect with the :kconfig:option:`CONFIG_NRF_SECURE_APPROTECT_USE_UICR` Kconfig option, which is the default value.
+
+    When using sysbuild, set the sysbuild Kconfig option ``SB_CONFIG_SECURE_APPROTECT_LOCK``, which enables the :kconfig:option:`CONFIG_NRF_SECURE_APPROTECT_LOCK` Kconfig option for all images.
+
+.. important::
+    On the nRF91x1 Series devices, the register setting related to the :kconfig:option:`CONFIG_NRF_SECURE_APPROTECT_LOCK` Kconfig option does not persist in System ON IDLE mode.
+    You must lock the ``UICR.SECUREAPPROTECT`` register to enable the hardware Secure AP-Protect mechanism as instructed in :ref:`app_secure_approtect_uicr_approtect`.
+
+Enabling software Secure AP-Protect with :kconfig:option:`CONFIG_NRF_SECURE_APPROTECT_USER_HANDLING`
+----------------------------------------------------------------------------------------------------
+
+Setting the :kconfig:option:`CONFIG_NRF_SECURE_APPROTECT_USER_HANDLING` Kconfig option to ``y`` and compiling the firmware allows you to handle the state of the software Secure AP-Protect at a later stage.
+This option does not touch the mechanism and keeps it closed.
+
+You can for example use this option to implement an authenticated debug and lock of the SPE.
+See the SoC or SiP hardware documentation for more information.
+
+.. note::
+    For multi-image builds, this Kconfig option needs to be set for all images.
+    The default value is to open the device if the ``UICR.SECUREAPPROTECT`` is not set.
+    This allows the debugger to be attached to the device.
+
+    When using sysbuild, set the ``SB_CONFIG_SECURE_APPROTECT_USER_HANDLING`` sysbuild Kconfig option, which enables the :kconfig:option:`CONFIG_NRF_SECURE_APPROTECT_USER_HANDLING` Kconfig option for all images.
+
+Enabling software Secure AP-Protect with :kconfig:option:`CONFIG_SECURE_NRF_APPROTECT_USE_UICR`
+-----------------------------------------------------------------------------------------------
+
+Setting the :kconfig:option:`CONFIG_NRF_SECURE_APPROTECT_USE_UICR` Kconfig option to ``y`` and compiling the firmware disables the software Secure AP-Protect mechanism by default.
+This is the default setting in the |NCS|.
+
+You can start debugging the SPE without additional steps needed.
+
+.. _app_secure_approtect_uicr_approtect:
+
+Enabling hardware Secure AP-Protect by locking the ``UICR.SECUREAPPROTECT`` register
+------------------------------------------------------------------------------------
+
+To enable only the hardware Secure AP-Protect mechanism, run the following command:
+
+.. note::
+    This is the only mechanism supported for the nRF9160 devices that do not have software support for Secure AP-Protect.
 
 .. code-block:: console
 
    nrfjprog --rbp SECURE
+
+This command enables hardware Secure AP-Protect and resets the device.

samples/tfm/tfm_psa_template/prj.conf

@@ -12,8 +12,6 @@ CONFIG_TFM_EXCEPTION_INFO_DUMP=y
 
 CONFIG_TFM_PARTITION_INITIAL_ATTESTATION=y
 CONFIG_TFM_NRF_PROVISIONING=y
-CONFIG_NRF_APPROTECT_LOCK=y
-CONFIG_NRF_SECURE_APPROTECT_LOCK=y
 
 CONFIG_SECURE_BOOT=y
 CONFIG_BUILD_S1_VARIANT=y

samples/tfm/tfm_psa_template/sysbuild.conf

@@ -9,3 +9,5 @@ SB_CONFIG_SECURE_BOOT_APPCORE=y
 SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y
 SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY=y
 SB_CONFIG_MCUBOOT_UPDATEABLE_IMAGES=2
+SB_CONFIG_APPROTECT_LOCK=y
+SB_CONFIG_SECURE_APPROTECT_LOCK=y

sysbuild/CMakeLists.txt

@@ -490,6 +490,30 @@ function(${SYSBUILD_CURRENT_MODULE_NAME}_pre_cmake)
   if(SB_CONFIG_SDP)
     include_sdp()
   endif()
+
+  foreach(config APPROTECT_USE_UICR APPROTECT_LOCK APPROTECT_USER_HANDLING
+  SECURE_APPROTECT_USE_UICR SECURE_APPROTECT_USER_HANDLING SECURE_APPROTECT_LOCK)
+    if(SB_CONFIG_${config})
+      if(SB_CONFIG_BOOTLOADER_MCUBOOT)
+        set_config_bool(mcuboot CONFIG_NRF_${config} y)
+      endif()
+      if(SB_CONFIG_SECURE_BOOT_APPCORE)
+        set_config_bool(b0 CONFIG_NRF_${config} y)
+      endif()
+      set_config_bool(${DEFAULT_IMAGE} CONFIG_NRF_${config} y)
+    endif()
+  endforeach()
+  if(SB_CONFIG_SUPPORT_NETCORE AND NOT SB_CONFIG_NETCORE_NONE)
+    foreach(config APPROTECT_USE_UICR APPROTECT_LOCK APPROTECT_USER_HANDLING)
+      if(SB_CONFIG_${config})
+        if(SB_CONFIG_SECURE_BOOT_NETCORE)
+          set_config_bool(b0n CONFIG_NRF_${config} y)
+        endif()
+        set_config_bool(${SB_CONFIG_NETCORE_IMAGE_NAME} CONFIG_NRF_${config} y)
+      endif()
+    endforeach()
+  endif()
+
 endfunction(${SYSBUILD_CURRENT_MODULE_NAME}_pre_cmake)
 
 function(${SYSBUILD_CURRENT_MODULE_NAME}_pre_image_cmake)

sysbuild/Kconfig.approtect

@@ -0,0 +1,66 @@
+# Copyright (c) 2024 Nordic Semiconductor
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+
+choice APPROTECT_HANDLING
+	prompt "APPROTECT handling"
+	depends on SOC_SERIES_NRF52X || SOC_SERIES_NRF53X || \
+		   SOC_SERIES_NRF91X
+	default APPROTECT_NO_SYSBUILD
+	help
+	  Specifies how the SystemInit() function of all the images should
+	  handle the APPROTECT mechanism.
+
+config APPROTECT_USE_UICR
+	bool "Use UICR"
+	help
+	  Enable CONFIG_NRF_APPROTECT_USE_UICR in all images.
+
+config APPROTECT_LOCK
+	bool "Lock"
+	help
+	  Enable CONFIG_NRF_APPROTECT_LOCK in all images.
+
+config APPROTECT_USER_HANDLING
+	bool "Allow user handling"
+	depends on !SOC_SERIES_NRF52X
+	help
+	  Enable CONFIG_NRF_APPROTECT_USER_HANDLING in all images.
+
+config APPROTECT_NO_SYSBUILD
+	bool "No sysbuild level configuration"
+	help
+	  Approtect handling is not configured at sysbuild level.
+
+endchoice
+
+choice SECURE_APPROTECT_HANDLING
+	prompt "Secure APPROTECT handling"
+	depends on SOC_NRF5340_CPUAPP || SOC_SERIES_NRF91X
+	default SECURE_APPROTECT_NO_SYSBUILD
+	help
+	  Specifies how the SystemInit() function of all the images should
+	  handle the secure APPROTECT mechanism.
+
+config SECURE_APPROTECT_USE_UICR
+	bool "Use UICR"
+	help
+	  Enable CONFIG_NRF_SECURE_APPROTECT_USE_UICR in all images.
+
+config SECURE_APPROTECT_LOCK
+	bool "Lock"
+	help
+	  Enable CONFIG_NRF_SECURE_APPROTECT_LOCK in all images.
+
+config SECURE_APPROTECT_USER_HANDLING
+	bool "Allow user handling"
+	depends on !SOC_SERIES_NRF52X
+	help
+	  Enable CONFIG_NRF_SECURE_APPROTECT_USER_HANDLING in all images.
+
+config SECURE_APPROTECT_NO_SYSBUILD
+	bool "No sysbuild level configuration"
+	help
+	  Secure approtect handling is not configured at sysbuild level.
+
+endchoice

sysbuild/Kconfig.sysbuild

@@ -80,3 +80,4 @@ rsource "Kconfig.matter"
 rsource "Kconfig.wifi"
 rsource "Kconfig.suit"
 rsource "Kconfig.sdp"
+rsource "Kconfig.approtect"