diff --git a/CODEOWNERS b/CODEOWNERS index 091029f64da0..2124e3cea572 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -253,6 +253,7 @@ /doc/nrf/samples/esb.rst @nrfconnect/ncs-si-muffin-doc /doc/nrf/samples/fast_pair.rst @nrfconnect/ncs-si-bluebagel-doc /doc/nrf/samples/gazell.rst @nrfconnect/ncs-si-muffin-doc +/doc/nrf/samples/ironside_se.rst @nrfconnect/ncs-aurora-doc /doc/nrf/samples/keys.rst @nrfconnect/ncs-aegir-doc /doc/nrf/samples/matter.rst @nrfconnect/ncs-matter-doc /doc/nrf/samples/mesh.rst @nrfconnect/ncs-paladin-doc diff --git a/doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_ironside.rst b/doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_ironside.rst index 157653b8c4ee..ff5428a3b887 100644 --- a/doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_ironside.rst +++ b/doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_ironside.rst @@ -7,22 +7,173 @@ IronSide Secure Element :local: :depth: 2 -The IronSide Secure Element (|ISE|) is a firmware for the :ref:`Secure Domain ` of the nRF54H20 SoC that provides security features based on the :ref:`PSA Crypto API `, part of the :ref:`PSA Certified Security Framework `. +The IronSide Secure Element (|ISE|) is a firmware for the :ref:`Secure Domain ` of the nRF54H20 SoC that provides security features based on the :ref:`PSA Certified Security Framework `. |ISE| provides the following features: * Global memory configuration * Peripheral configuration (through UICR.PERIPHCONF) * Boot commands (ERASEALL, DEBUGWAIT) +* An alternative boot path with a Secondary firmware * CPUCONF service * Update service * PSA Crypto service - see also :ref:`ug_crypto_architecture_implementation_standards_ironside` +* PSA Internal Trusted Storage service -Distribution -************ +.. _ug_nrf54h20_ironside_se_programming: -The |ISE| is provided as a precompiled binary, which is part of the nRF54H20 SoC bundle and is provided independently from the |NCS| release cycle. -For more information, see :ref:`abi_compatibility`. +Programming |ISE| on the nRF54H20 SoC +************************************* + +|ISE| is included in the nRF54H20 SoC binaries. +The nRF54H20 SoC binaries are released independently from the |NCS| release cycle and are bundled in a ZIP archive that contains the following components: + +.. list-table:: + :header-rows: 1 + :widths: auto + + * - Component + - File + - Description + * - IronSide SE update firmware + - :file:`ironside_se_update.hex` + - The main |ISE| firmware + * - IronSide SE Recovery update firmware + - :file:`ironside_se_recovery_update.hex` + - The recovery firmware + * - Update application + - :file:`update_application.hex` + - The application firmware used to trigger the update process + +The bundle ZIP file follows the naming convention :file:`_soc_binaries_v.zip`. + +For more information on the nRF54H20 SoC binaries, see :ref:`nRF54H20 SoC binaries`. +For instructions on how to program the nRF54H20 SoC binaries, see :ref:`ug_nrf54h20_SoC_binaries`. + +By default, the nRF54H20 SoC uses the following memory and access configurations: + +* MRAMC configuration: MRAM operates in Direct Write mode. +* MPC configuration: All memory not reserved by Nordic firmware is accessible with read, write, and execute (RWX) permissions by any domain. +* TAMPC configuration: The access port (AP) for the application core is enabled and available, allowing direct programming of all the memory not reserved by Nordic firmware in the default configuration. + +.. note:: + Access to external memory (EXMIF) requires a non-default configuration of the GPIO.CTRLSEL register. + +Global domain memory can be protected from write operations by configuring UICR registers. +To remove these protections and disable all other protection mechanisms enforced through UICR settings, perform an ``ERASEALL`` operation. + +.. _ug_nrf54h20_ironside_se_update: + +Updating |ISE| +************** + +|NCS| supports two methods for updating the |ISE| firmware on the nRF54H20 SoC: + +* Using the ``west`` command. + You can use the ``west`` command provided by the |NCS| to install the firmware update. + For step-by-step instructions, see :ref:`ug_nrf54h20_ironside_se_update_west`. + +* Updating the SoC binaries manually. + Alternatively, you can perform the update by manually executing the same steps carried out by the ``west`` command. + For step-by-step instructions, see :ref:`ug_nrf54h20_ironside_se_update_manual`. + +.. caution:: + You cannot update the nRF54H20 SoC binaries from a SUIT-based (up to 0.9.6) to an IronSide-SE-based (2x.x.x) version. + +.. _ug_nrf54h20_ironside_se_update_west: + +Updating using west +=================== + +To update the |ISE| firmware, you can use the ``west ncs-ironside-se-update`` command with the following syntax: + +.. code-block:: console + + west ncs-ironside-se-update --zip --allow-erase + +The command accepts the following main options: + +* ``--zip`` (required) - Sets the path to the nRF54H20 SoC binaries ZIP file. +* ``--allow-erase`` (required) - Enables erasing the device during the update process. +* ``--serial`` - Specifies the serial number of the target device. +* ``--firmware-slot`` - Updates only a specific firmware slot (``uslot`` for |ISE| or ``rslot`` for |ISE| Recovery). +* ``--wait-time`` - Specifies the timeout in seconds to wait for the device to boot (default: 2.0 seconds). + +.. _ug_nrf54h20_ironside_se_update_manual: + +Updating manually +================= + +The manual update process involves the following steps: + +1. Executing the update application. + The update application runs on the application core and communicates with the |ISE| update service. + It reads the update firmware from memory and passes the update blob metadata to the |ISE|. + +#. Preparing the update. + The |ISE| validates the update parameters and writes the update metadata to the Secure Information Configuration Registers (SICR). + +#. Installing the update. + After a reset, the Secure Domain ROM (SDROM) detects the pending update through the SICR registers, verifies the update firmware signature, and installs the new firmware. + +#. Completing the update. + The system boots with the updated |ISE| firmware, and the update status can be read to verify successful installation. + +Updating manually using nRF Util +-------------------------------- + +You can use nRF Util instead of ``west ncs-ironside-se-update``. +To perform the manual update process using nRF Util's `device command `_ command, complete the following steps: + +1. Extract the update bundle: + + .. code-block:: console + + unzip -d /tmp/update_dir + +#. Erase non-volatile memory: + + .. code-block:: console + + nrfutil device recover --serial-number --x-sdfw-variant ironside + +#. Program the update application: + + .. code-block:: console + + nrfutil device program --firmware /tmp/update_dir/update/update_application.hex --serial-number --x-sdfw-variant ironside + +#. Program the |ISE| update firmware: + + .. code-block:: console + + nrfutil device program --options chip_erase_mode=ERASE_NONE --firmware /tmp/update_dir/update/ironside_se_update.hex --serial-number --x-sdfw-variant ironside + +#. Reset to execute the update service: + + .. code-block:: console + + nrfutil device reset --serial-number --x-sdfw-variant ironside + +#. Reset to trigger the installation of the update: + + .. code-block:: console + + nrfutil device reset --reset-kind RESET_VIA_SECDOM --serial-number --x-sdfw-variant ironside + +#. Program the |ISE| Recovery update firmware (if updating both slots): + + .. code-block:: console + + nrfutil device program --options chip_erase_mode=ERASE_NONE --firmware /tmp/update_dir/update/ironside_se_recovery_update.hex --serial-number --x-sdfw-variant ironside + +#. Repeat steps 5 and 6 to complete the update of the recovery firmware (if updating both slots). + +#. Erase the update application: + + .. code-block:: console + + nrfutil device erase --all --serial-number --x-sdfw-variant ironside .. _ug_nrf54h20_ironside_se_uicr: @@ -58,8 +209,7 @@ The following UICR fields are supported: | UICR.PERIPHCONF | Points to an array of key-value entries used to initialize approved | | | global peripherals. | +----------------------+---------------------------------------------------------------------+ -| UICR.MPCCONF | Points to an array of memory-protection entries used to configure | -| | global memory regions. | +| UICR.MPCCONF | Not supported yet. | +----------------------+---------------------------------------------------------------------+ | UICR.WDTSTART | Configures automatic start of a local watchdog timer before the | | | application core is booted, providing early system protection. | @@ -75,6 +225,124 @@ The following UICR fields are supported: If no UICR values are programmed, |ISE| applies a set of default configurations. Applications that do not require custom settings can rely on these defaults without modifying the UICR. +UICR image generation +===================== + +The UICR image is an automatically created build artifact that generates the UICR content and peripheral configuration (PERIPHCONF) entries. + +What is the UICR image +---------------------- + +The UICR image consists of several components: + +* UICR configuration - The main UICR structure containing version information, security settings, memory protection, and boot configuration +* PERIPHCONF entries - Peripheral configuration data extracted from the devicetree that defines peripheral access permissions and pin multiplexing + +The UICR image is generated as a HEX file. +The UICR HEX file is automatically programmed when using ``west flash`` and is located at ``build/uicr/zephyr/zephyr.hex`` relative to your project's build directory. + +UICR image generation process +----------------------------- + +The following steps process describe the UICR image generation process: + +1. Devicetree analysis: The build system analyzes all devicetrees in the sysbuild build to identify peripheral usage and pin assignments across all images. +2. PERIPHCONF generation: Python scripts generate C source code containing UICR configuration macros based on the devicetree. +3. Compilation: The generated C code is compiled into ELF binaries containing PERIPHCONF sections. +4. ELF extraction: The UICR generator extracts PERIPHCONF data from ELF files and merges them together. +5. Kconfig extraction: The UICR generator uses an application-specific UICR Kconfig to populate the UICR entries. +6. HEX file creation: Three HEX files are generated for different purposes (merged, UICR-only, PERIPHCONF-only.) + +Configuring the UICR sysbuild image +----------------------------------- + +Applications that use UICR features must place a :file:`sysbuild/uicr.conf` Kconfig fragment file in their project directory to configure the Kconfig of the UICR image. + +The following code snippet shows an example configuration for secondary firmware support in :file:`sysbuild/uicr.conf`: + +.. code-block:: kconfig + + # Configuration overlay for uicr image + # Enable UICR.SECONDARY.ENABLE + CONFIG_GEN_UICR_SECONDARY=y + +For more examples of UICR configuration, see :ref:`ironside_se`: + +* :ref:`secondary_boot_sample` - Basic secondary firmware configuration +* :ref:`secondary_boot_trigger_lockup_sample` - Secondary firmware with automatic triggers + +UICR Kconfig configuration options +---------------------------------- + +The UICR Kconfig options are listed below, and are defined with more detailed Kconfig help texts in :file:`zephyr/soc/nordic/common/uicr/gen_uicr/Kconfig`. + +.. list-table:: UICR Kconfig Options + :widths: 50 50 + :header-rows: 1 + + * - Kconfig option + - Description + * - :kconfig:option:`CONFIG_GEN_UICR_GENERATE_PERIPHCONF` + - Generate a PERIPHCONF hex in addition to the UICR hex + * - :kconfig:option:`CONFIG_GEN_UICR_SECURESTORAGE` + - Enable UICR.SECURESTORAGE + * - :kconfig:option:`CONFIG_GEN_UICR_LOCK` + - Enable UICR.LOCK + * - :kconfig:option:`CONFIG_GEN_UICR_ERASEPROTECT` + - Enable UICR.ERASEPROTECT + * - :kconfig:option:`CONFIG_GEN_UICR_APPROTECT_APPLICATION_PROTECTED` + - Protect application domain access port + * - :kconfig:option:`CONFIG_GEN_UICR_APPROTECT_RADIOCORE_PROTECTED` + - Protect radio core access port + * - :kconfig:option:`CONFIG_GEN_UICR_APPROTECT_CORESIGHT_PROTECTED` + - Disable CoreSight subsystem + * - :kconfig:option:`CONFIG_GEN_UICR_PROTECTEDMEM` + - Enable UICR.PROTECTEDMEM + * - :kconfig:option:`CONFIG_GEN_UICR_PROTECTEDMEM_SIZE_BYTES` + - Protected memory size in bytes + * - :kconfig:option:`CONFIG_GEN_UICR_WDTSTART` + - Enable UICR.WDTSTART + * - :kconfig:option:`CONFIG_GEN_UICR_WDTSTART_INSTANCE_WDT0` + - Use watchdog timer instance 0 + * - :kconfig:option:`CONFIG_GEN_UICR_WDTSTART_INSTANCE_WDT1` + - Use watchdog timer instance 1 + * - :kconfig:option:`CONFIG_GEN_UICR_WDTSTART_CRV` + - Initial Counter Reload Value (CRV) for the watchdog timer + * - :kconfig:option:`CONFIG_GEN_UICR_SECONDARY` + - Enable UICR.SECONDARY.ENABLE + * - :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_GENERATE_PERIPHCONF` + - Generate SECONDARY.PERIPHCONF hex alongside UICR + * - :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_PROCESSOR_APPLICATION` + - Boot secondary firmware on the APPLICATION processor + * - :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_PROCESSOR_RADIOCORE` + - Boot secondary firmware on the RADIOCORE processor + * - :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_TRIGGER` + - Enable UICR.SECONDARY.TRIGGER + * - :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_TRIGGER_APPLICATIONWDT0` + - Trigger on Application domain watchdog 0 reset + * - :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_TRIGGER_APPLICATIONWDT1` + - Trigger on Application domain watchdog 1 reset + * - :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_TRIGGER_APPLICATIONLOCKUP` + - Trigger on Application domain CPU lockup reset + * - :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_TRIGGER_RADIOCOREWDT0` + - Trigger on Radio core watchdog 0 reset + * - :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_TRIGGER_RADIOCOREWDT1` + - Trigger on Radio core watchdog 1 reset + * - :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_TRIGGER_RADIOCORELOCKUP` + - Trigger on Radio core CPU lockup reset + * - :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_WDTSTART` + - Enable UICR.SECONDARY.WDTSTART + * - :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_WDTSTART_INSTANCE_WDT0` + - Use watchdog timer instance 0 for secondary firmware + * - :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_WDTSTART_INSTANCE_WDT1` + - Use watchdog timer instance 1 for secondary firmware + * - :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_WDTSTART_CRV` + - Secondary initial Counter Reload Value (CRV) for the watchdog timer + * - :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_PROTECTEDMEM` + - Enable UICR.SECONDARY.PROTECTEDMEM + * - :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_PROTECTEDMEM_SIZE_BYTES` + - Secondary protected memory size in bytes + UICR.VERSION ============ @@ -86,64 +354,59 @@ This versioning scheme allows IronSide to support multiple UICR formats, enablin UICR.LOCK ========= -Enabling UICR.LOCK locks the entire contents of the NVR0 page located in MRAM10. +Enabling :kconfig:option:`CONFIG_GEN_UICR_LOCK` locks the entire contents of the NVR0 page located in MRAM10. This includes all values in both the UICR and the BICR (the Board Information Configuration Registers). -When UICR.LOCK is enabled, you can modify the UICR only by performing an ERASEALL operation. +When :kconfig:option:`CONFIG_GEN_UICR_LOCK` is enabled, you can modify the UICR only by performing an ERASEALL operation. .. note:: - While BICR is not erased during an ERASEALL operation, executing ERASEALL lifts the UICR.LOCK restriction, allowing write access to BICR. + While BICR is not erased during an ERASEALL operation, executing ERASEALL lifts the :kconfig:option:`CONFIG_GEN_UICR_LOCK` restriction, allowing write access to BICR. Locking is enforced through an integrity check and by configuring the NVR page as read-only in the MRAMC. -If the integrity check fails, the application is booted with the application domain's CPUWAIT set. +If the integrity check fails, the application CPU subsystem will still be given clock and power, but the CPU will be stalled and prevented from executing instructions. It is not possible to boot the vendor-specified recovery firmware if the integrity check fails. +.. _ug_nrf54h20_ironside_se_uicr_approtect: + UICR.APPROTECT ============== -UICR.APPROTECT controls debugger and access-port permissions through the TAMPC peripheral. -The configuration consists of separate registers for each access port, allowing independent control over debugging capabilities for different processor domains and CoreSight access. - The UICR.APPROTECT configuration consists of the following sub-registers: -UICR.APPROTECT.APPLICATION +:kconfig:option:`CONFIG_GEN_UICR_APPROTECT_APPLICATION_PROTECTED` Controls access port protection for the application domain processor. This setting determines whether the debugger can access the application domain memory, registers, and debug features. -UICR.APPROTECT.RADIOCORE +:kconfig:option:`CONFIG_GEN_UICR_APPROTECT_RADIOCORE_PROTECTED` Controls access port protection for the radio core processor. This setting determines whether the debugger can access the radio core memory, registers, and debug features. -UICR.APPROTECT.CORESIGHT +:kconfig:option:`CONFIG_GEN_UICR_APPROTECT_CORESIGHT_PROTECTED` Controls access port protection for the CoreSight debug infrastructure. This setting determines whether system-level trace features are accessible. -Each of these sub-registers accepts the following values: - -* ``UICR_MAGIC_ERASE_VALUE`` - Full debug access is enabled, allowing unrestricted use of debugging tools and memory access. -* ``UICR_PROTECTED`` - Debug access is disabled, preventing debugger connection and protecting the device from unauthorized access. - .. note:: - To fully protect a production device, set all three sub-registers (APPLICATION, RADIOCORE, and CORESIGHT) to ``UICR_PROTECTED``. + To fully protect a production device, enable all three Kconfig options. UICR.ERASEPROTECT ================= -Enabling UICR.ERASEPROTECT blocks the ERASEALL operation. +Enabling :kconfig:option:`CONFIG_GEN_UICR_ERASEPROTECT` blocks the ERASEALL operation. However, it does not prevent erase operations initiated through other means, such as writing erase values via a debugger. .. note:: - If this configuration is enabled and UICR.LOCK is also set, it is no longer possible to modify the UICR in any way. + If this configuration is enabled and :kconfig:option:`CONFIG_GEN_UICR_LOCK` is also set, it is no longer possible to modify the UICR in any way. Therefore, this configuration should only be enabled during the final stages of production. UICR.PROTECTEDMEM ================= -In the UICR.PROTECTEDMEM field, you can specify a memory region that will have its integrity ensured by |ISE|. -This memory can contain immutable bootloaders, UICR.PERIPHCONF entries, UICR.MPCCONF entries, or any other data that should be immutable. +Enabling :kconfig:option:`CONFIG_GEN_UICR_PROTECTEDMEM` enables UICR.PROTECTEDMEM. +UICR.PROTECTEDMEM can be used to specify a memory region that will have its integrity ensured by |ISE|. +This memory can contain immutable bootloaders, UICR.PERIPHCONF entries, or any other data that should be immutable. By ensuring the integrity of this memory region, |ISE| extends the Root of Trust to any immutable bootloader located in this region. -The value in this field specifies the number of 4 kB blocks, starting from the lowest MRAM address of the application-owned memory. +The memory region always starts at the lowest MRAM address of the application-owned memory and has an application-specific size specified in :kconfig:option:`CONFIG_GEN_UICR_PROTECTEDMEM_SIZE_BYTES`. UICR.PERIPHCONF =============== @@ -383,22 +646,22 @@ See the following table for a mapping between the devicetree input used by ``nrf UICR.WDTSTART ============= -UICR.WDTSTART configures the automatic start of a local watchdog timer before the application core is booted. +:kconfig:option:`CONFIG_GEN_UICR_WDTSTART` enables the automatic start of a local watchdog timer before the application core is booted. This provides early system protection ensuring that the system can recover from early boot failures. The UICR.WDTSTART configuration consists of three sub-registers: -UICR.WDTSTART.ENABLE +:kconfig:option:`CONFIG_GEN_UICR_WDTSTART` Controls whether the watchdog timer automatic start feature is enabled. -UICR.WDTSTART.INSTANCE +:kconfig:option:`CONFIG_GEN_UICR_WDTSTART_INSTANCE_WDT0` / :kconfig:option:`CONFIG_GEN_UICR_WDTSTART_INSTANCE_WDT1` Specifies which watchdog timer instance to configure and start. The following are valid values: * ``WDT0`` - Use watchdog timer instance 0 * ``WDT1`` - Use watchdog timer instance 1 -UICR.WDTSTART.CRV +:kconfig:option:`CONFIG_GEN_UICR_WDTSTART_CRV` Sets the initial Counter Reload Value (CRV) for the watchdog timer. This value determines the watchdog timeout period. The CRV must be at least 15 (0xF) to ensure proper watchdog operation. @@ -406,7 +669,7 @@ UICR.WDTSTART.CRV UICR.SECURESTORAGE ================== -UICR.SECURESTORAGE configures the secure storage system used by |ISE| for persistent storage of cryptographic keys and trusted data. +:kconfig:option:`CONFIG_GEN_UICR_SECURESTORAGE` enables the secure storage system used by |ISE| for persistent storage of cryptographic keys and trusted data. The secure storage is divided into separate partitions for different services and processor domains. The total size of all configurations specified in ``UICR.SECURESTORAGE.*`` must be aligned to a 4 KB boundary. For more information, see :ref:`ug_nrf54h20_ironside_se_secure_storage`. @@ -441,7 +704,7 @@ UICR.SECURESTORAGE.ITS UICR.SECONDARY ============== -UICR.SECONDARY configures the secondary firmware boot system, which allows |ISE| to boot alternative firmware in response to specific conditions or triggers. +:kconfig:option:`CONFIG_GEN_UICR_SECONDARY` configures the secondary firmware boot system, which allows |ISE| to boot alternative firmware in response to specific conditions or triggers. This feature enables a recovery firmware setup through a dual-firmware configuration that includes both main and recovery firmware. The UICR.SECONDARY configuration consists of multiple sub-registers organized into functional groups: @@ -480,161 +743,15 @@ UICR.SECONDARY.TRIGGER * ``RADIOCORELOCKUP`` - Radio core CPU lockup reset UICR.SECONDARY.PROTECTEDMEM - Identical to UICR.PROTECTEDMEM, but applies to the secondary firmware. + Identical to :kconfig:option:`CONFIG_GEN_UICR_PROTECTEDMEM`, but applies to the secondary firmware. UICR.SECONDARY.WDTSTART - Identical to UICR.WDTSTART, but applies to the secondary firmware boot process. + Identical to :kconfig:option:`CONFIG_GEN_UICR_WDTSTART`, but applies to the secondary firmware boot process. Note that if RADIOCORE is specified in ``UICR.SECONDARY.PROCESSOR``, the WDT instances used are the ones in the radio core. UICR.SECONDARY.PERIPHCONF Identical to UICR.PERIPHCONF, but applies to the secondary firmware boot process. -UICR.SECONDARY.MPCCONF - Identical to UICR.MPCCONF, but applies to the secondary firmware boot process. - -.. _ug_nrf54h20_ironside_se_programming: - -Programming |ISE| on the nRF54H20 SoC -************************************* - -|ISE| is included in the nRF54H20 SoC binaries. -The nRF54H20 SoC binaries are bundled in a ZIP archive that contains the following components: - -* *IronSide SE update firmware* (:file:`ironside_se_update.hex`) - The main |ISE| firmware -* *IronSide SE Recovery update firmware* (:file:`ironside_se_recovery_update.hex`) - The recovery firmware -* The update application (:file:`update_application.hex`) - The application firmware used to trigger the update process -* Additional metadata and manifest files required for the update process - -The bundle ZIP file follows the naming convention :file:`_soc_binaries_v.zip`. - -For more information on the nRF54H20 SoC binaries, see :ref:`nRF54H20 SoC binaries`. -For instructions on how to program the nRF54H20 SoC binaries, see :ref:`ug_nrf54h20_SoC_binaries`. - -By default, the nRF54H20 SoC uses the following memory and access configurations: - -* *MRAMC configuration*: MRAM operates in *Direct Write mode*. -* *MPC configuration*: All memory not reserved by Nordic firmware is accessible with read, write, and execute (RWX) permissions by any domain. -* *TAMPC configuration*: The Access Port (AP) for the application core is enabled and available, allowing direct programming of all the memory not reserved by Nordic firmware in the default configuration. - -.. note:: - Access to external memory (EXMIF) requires a non-default configuration of the GPIO.CTRLSEL register. - -Global domain memory can be protected from write operations by configuring UICR registers. -To remove these protections and disable all other protection mechanisms enforced through UICR settings, perform an ``ERASEALL`` operation. - -.. _ug_nrf54h20_ironside_se_update: - -Updating |ISE| -************** - -|NCS| supports two methods for updating the |ISE| firmware on the nRF54H20 SoC: - -* Using the ``west`` command. - You can use the ``west`` command provided by the |NCS| to install the firmware update. - For step-by-step instructions, see :ref:`ug_nrf54h20_ironside_se_update_west`. - -* Updating the SoC binaries manually. - Alternatively, you can perform the update by manually executing the same steps carried out by the ``west`` command. - For step-by-step instructions, see :ref:`ug_nrf54h20_ironside_se_update_manual`. - -.. caution:: - You cannot update the nRF54H20 SoC binaries from a SUIT-based (up to 0.9.6) to an IronSide-SE-based (2x.x.x) version. - -.. _ug_nrf54h20_ironside_se_update_west: - -Updating using west -=================== - -To update the |ISE| firmware, you can use the ``west ncs-ironside-se-update`` command with the following syntax: - -.. code-block:: console - - west ncs-ironside-se-update --zip --allow-erase - -The command accepts the following main options: - -* ``--zip`` (required) - Sets the path to the nRF54H20 SoC binaries ZIP file. -* ``--allow-erase`` (required) - Enables erasing the device during the update process. -* ``--serial`` - Specifies the serial number of the target device. -* ``--firmware-slot`` - Updates only a specific firmware slot (``uslot`` for |ISE| or ``rslot`` for |ISE| Recovery). -* ``--wait-time`` - Specifies the timeout in seconds to wait for the device to boot (default: 2.0 seconds). - -.. _ug_nrf54h20_ironside_se_update_manual: - -Updating manually -================= - -The manual update process involves the following steps: - -1. Executing the update application. - The update application runs on the application core and communicates with the |ISE| update service. - It reads the update firmware from memory and passes the update blob metadata to the |ISE|. - -#. Preparing the update. - The |ISE| validates the update parameters and writes the update metadata to the Secure Information Configuration Registers (SICR). - -#. Installing the update. - After a reset, the Secure Domain ROM (SDROM) detects the pending update through the SICR registers, verifies the update firmware signature, and installs the new firmware. - -#. Completing the update. - The system boots with the updated |ISE| firmware, and the update status can be read to verify successful installation. - -Updating manually using nrfutil -------------------------------- - -``nrfutil`` commands can replicate the functionality of ``west ncs-ironside-se-update``. -To perform the manual update process using ``nrfutil`` commands, complete the following steps: - -1. Extract the update bundle: - - .. code-block:: console - - unzip -d /tmp/update_dir - -#. Erase non-volatile memory: - - .. code-block:: console - - nrfutil device recover --serial-number --x-sdfw-variant ironside - -#. Program the update application: - - .. code-block:: console - - nrfutil device program --firmware /tmp/update_dir/update/update_application.hex --serial-number --x-sdfw-variant ironside - -#. Program the |ISE| update firmware: - - .. code-block:: console - - nrfutil device program --options chip_erase_mode=ERASE_NONE --firmware /tmp/update_dir/update/ironside_se_update.hex --serial-number --x-sdfw-variant ironside - -#. Reset to execute the update service: - - .. code-block:: console - - nrfutil device reset --serial-number --x-sdfw-variant ironside - -#. Reset to trigger the installation of the update: - - .. code-block:: console - - nrfutil device reset --reset-kind RESET_VIA_SECDOM --serial-number --x-sdfw-variant ironside - -#. Program the |ISE| Recovery update firmware (if updating both slots): - - .. code-block:: console - - nrfutil device program --options chip_erase_mode=ERASE_NONE --firmware /tmp/update_dir/update/ironside_se_recovery_update.hex --serial-number --x-sdfw-variant ironside - - Then repeat steps 5 and 6. - -#. Erase the update application: - - .. code-block:: console - - nrfutil device erase --all --serial-number --x-sdfw-variant ironside - .. _ug_nrf54h20_ironside_se_debug: @@ -655,17 +772,16 @@ This prevents the CPU from executing any instructions until a debugger manually Protecting the device ********************* -To protect the nRF54H20 SoC in a production-ready device, you must enable the following UICR-based security mechanisms: +To protect the nRF54H20 SoC in a production-ready device, you must enable the following UICR-based security mechanisms. +For information on how to configure these UICR settings, see :ref:`ug_nrf54h20_ironside_se_uicr`. -* UICR.APPROTECT - Disables all debug and AP access. +* :kconfig:option:`CONFIG_GEN_UICR_APPROTECT_APPLICATION_PROTECTED` - Disables all debug and AP access. It restricts debugger and access-port (AP) permissions, preventing unauthorized read/write access to memory and debug interfaces. -* UICR.LOCK - Freezes non-volatile configuration registers. +* :kconfig:option:`CONFIG_GEN_UICR_LOCK` - Freezes non-volatile configuration registers. It locks the UICR, ensuring that no further UICR writes are possible without issuing an `ERASEALL` command. -* UICR.PROTECTEDMEM - Enforces integrity checks on critical code and data. +* :kconfig:option:`CONFIG_GEN_UICR_PROTECTEDMEM` - Enforces integrity checks on critical code and data. It defines a trailing region of application-owned MRAM whose contents are integrity-checked at each boot, extending the root of trust to your immutable bootloader or critical data. -* UICR.MPCCONF - Configures memory protection for the bootloader region. - It should be used to set RX-only (read and execute) permissions on the PROTECTEDMEM region containing the bootloader, preventing unauthorized modification while allowing execution. -* UICR.ERASEPROTECT - Prevent bulk erasure of protected memory. +* :kconfig:option:`CONFIG_GEN_UICR_ERASEPROTECT` - Prevent bulk erasure of protected memory. It blocks all `ERASEALL` operations on NVR0, preserving UICR settings even if an attacker attempts a full-chip erase. @@ -776,7 +892,7 @@ Secondary firmware ****************** The secondary firmware feature provides an alternative boot path that can be triggered implicitly or explicitly. -It can be used for different purposes, some examples are DFU applications in systems that don't use dual banking, recovery firmware, and analysis firmware. +It can be used for different purposes, some examples are recovery firmware, analysis firmware, and DFU applications in systems that don't use dual banking. For more information on the boot sequence, see :ref:`ug_nrf54h20_architecture_boot`. @@ -787,17 +903,50 @@ For more information on the boot sequence, see :ref:`ug_nrf54h20_architecture_bo The term "secondary slot" and "secondary image" are used in the MCUboot context. This usage is unrelated to the "secondary firmware" described in this section. -Sample -====== +.. _ug_nrf54h20_ironside_se_secondary_conf_trigger: -For an example of how to create a secondary image with automatic triggers, see the :ref:`secondary_boot_trigger_lockup_sample` sample. +Configuration +============= -.. _ug_nrf54h20_ironside_se_secondary_conf_trigger: +To enable secondary firmware support, you must complete the following steps: + +1. **Enable UICR secondary configuration**: Add the following to your ``sysbuild/uicr.conf`` file: + + .. code-block:: kconfig + + CONFIG_GEN_UICR_SECONDARY=y + +2. **Create a secondary firmware Zephyr image**: Create a separate Zephyr application for your secondary firmware (e.g., in a ``secondary/`` directory). + +3. **Add secondary image to sysbuild**: Include the secondary image as an external project in your ``sysbuild.cmake`` file: + + .. code-block:: cmake -Configuration and triggering -============================= + ExternalZephyrProject_Add( + APPLICATION secondary + SOURCE_DIR ${APP_DIR}/secondary + ) -Configuring a secondary firmware is optional and is done through the ``UICR.SECONDARY`` fields. +4. **Configure secondary firmware**: The secondary firmware image itself must enable the appropriate Kconfig option to indicate it's a secondary firmware. Add the following to your secondary firmware's ``prj.conf``: + + .. code-block:: kconfig + + CONFIG_IS_IRONSIDE_SE_SECONDARY_IMAGE=y + +5. **Optional: Configure automatic triggers**: If you want automatic triggering based on reset reasons, add trigger options to your ``sysbuild/uicr.conf``: + + .. code-block:: kconfig + + CONFIG_GEN_UICR_SECONDARY_TRIGGER=y + CONFIG_GEN_UICR_SECONDARY_TRIGGER_APPLICATIONLOCKUP=y + +For more examples of secondary firmware configuration, see the samples in :file:`nrf/samples/ironside_se/`: + +* :ref:`secondary_boot_sample` - Basic secondary firmware configuration +* :ref:`secondary_boot_trigger_lockup_sample` - Secondary firmware with automatic triggers + +Triggering +========== The secondary firmware can be triggered automatically, through ``CTRLAP.BOOTMODE`` or through an IPC service (``ironside_bootmode`` service). Any component that communicates with |ISE| over IPC can leverage this service. @@ -805,18 +954,18 @@ Setting bit 5 in ``CTRLAP.BOOTMODE`` will also trigger secondary firmware. |ISE| automatically triggers the secondary firmware in any of the following situations: -* The integrity check of the memory specified in ``UICR.PROTECTEDMEM`` fails. -* Any boot failure occurs, such as missing primary firmware or failure to apply ``UICR.PERIPHCONF`` or ``UICR.MPCCONF`` configurations. +* The integrity check of the memory specified in :kconfig:option:`CONFIG_GEN_UICR_PROTECTEDMEM` fails. +* Any boot failure occurs, such as missing primary firmware or failure to apply ``UICR.PERIPHCONF`` configurations. * A local domain is reset with a reason configured to trigger the secondary firmware. -* Secondary firmware will be booted by |ISE| if one of the triggers configured in ``UICR.SECONDARY.TRIGGER.RESETREAS`` occurs. +* Secondary firmware will be booted by |ISE| if one of the triggers configured in :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_TRIGGER` and related options occurs. -The secondary firmware can be protected using ``UICR.SECONDARY.PROTECTEDMEM`` for integrity checking, and can be updated by other components when protection is not enabled. +The secondary firmware can be protected using :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_PROTECTEDMEM` for integrity checking, and can be updated by other components when protection is not enabled. Protection ========== -The secondary firmware can be protected through integrity checks by enabling ``UICR.SECONDARY.PROTECTEDMEM``. -The ``PERIPHCONF`` entries for the secondary firmware can also be placed in memory covered by ``UICR.SECONDARY.PROTECTEDMEM`` to create a fully immutable secondary firmware and configuration. +The secondary firmware can be protected through integrity checks by enabling :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_PROTECTEDMEM`. +The ``PERIPHCONF`` entries for the secondary firmware can also be placed in memory covered by :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_PROTECTEDMEM` to create a fully immutable secondary firmware and configuration. If the integrity check of the memory specified in this configuration fails, the secondary firmware will not be booted. Instead, |ISE| will attempt to boot the primary firmware, and information about the failure is available in the boot report and boot status. @@ -825,8 +974,8 @@ Update ====== As with the primary firmware, |ISE| does not facilitate updating the secondary firmware. -The secondary image can be updated by other components as long as ``UICR.SECONDARY.PROTECTEDMEM`` is not set. -Using the secondary firmware as a bootloader capable of validating and updating a second image enables updating firmware in the secondary boot flow while having secure boot enabled through ``UICR.SECONDARY.PROTECTEDMEM``. +The secondary image can be updated by other components as long as :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_PROTECTEDMEM` is not set. +Using the secondary firmware as a bootloader capable of validating and updating a second image enables updating firmware in the secondary boot flow while having secure boot enabled through :kconfig:option:`CONFIG_GEN_UICR_SECONDARY_PROTECTEDMEM`. @@ -879,13 +1028,13 @@ For more information, see :ref:`abi_compatibility`. Secure Storage ************** -|ISE| provides secure storage functionality through the UICR.SECURESTORAGE configuration. +|ISE| provides secure storage functionality through the :kconfig:option:`CONFIG_GEN_UICR_SECURESTORAGE` configuration. This feature enables applications to store sensitive data in dedicated, encrypted storage regions that are protected by device-unique keys and access controls. UICR.SECURESTORAGE Configuration ================================ -The UICR.SECURESTORAGE field configures secure storage regions for PSA Crypto keys and PSA Internal Trusted Storage (ITS) data. +The :kconfig:option:`CONFIG_GEN_UICR_SECURESTORAGE` field configures secure storage regions for PSA Crypto keys and PSA Internal Trusted Storage (ITS) data. To leverage this secure storage functionality, applications must set the key location to ``PSA_KEY_LOCATION_LOCAL_STORAGE`` (``0x000000``). The secure storage configuration includes two separate storage regions: @@ -1093,13 +1242,13 @@ When executed, the ``ERASEALL`` command performs the following operations: .. note:: Page 1 of the MRAM10 NVR is preserved and not erased. -To explicitly permit the ``ERASEALL`` command, disable erase protection by clearing the UICR.ERASEPROTECT field in the application's UICR. +To explicitly permit the ``ERASEALL`` command, disable erase protection by clearing the :kconfig:option:`CONFIG_GEN_UICR_ERASEPROTECT` field in the application's UICR. Erase protection prevents unauthorized device repurposing. -In production-ready devices, enabling both access-port protection (UICR.APPROTECT) and erase protection (UICR.ERASEPROTECT) prevents the device from re-entering the *configuration* state using a debugger. +In production-ready devices, enabling both access-port protection (:kconfig:option:`CONFIG_GEN_UICR_APPROTECT_APPLICATION_PROTECTED`) and erase protection (:kconfig:option:`CONFIG_GEN_UICR_ERASEPROTECT`) prevents the device from re-entering the *configuration* state using a debugger. .. note:: - When an ``ERASEALL`` request is blocked by UICR.ERASEPROTECT, CTRLAP.BOOTSTATUS.CMDERROR is set to ``0x1``. + When an ``ERASEALL`` request is blocked by :kconfig:option:`CONFIG_GEN_UICR_ERASEPROTECT`, CTRLAP.BOOTSTATUS.CMDERROR is set to ``0x1``. ``DEBUGWAIT`` command ===================== diff --git a/doc/nrf/samples.rst b/doc/nrf/samples.rst index a3203f99b230..065e18443aa3 100644 --- a/doc/nrf/samples.rst +++ b/doc/nrf/samples.rst @@ -48,6 +48,7 @@ General information about samples in the |NCS| samples/bl samples/cellular samples/crypto + samples/ironside_se samples/debug samples/dect samples/dfu diff --git a/doc/nrf/samples/ironside_se.rst b/doc/nrf/samples/ironside_se.rst new file mode 100644 index 000000000000..668aeaee1ee8 --- /dev/null +++ b/doc/nrf/samples/ironside_se.rst @@ -0,0 +1,19 @@ +.. _ironside_se: + +IronSide Secure Element samples +############################### + +This section lists the available |NCS| samples that use special features provided by the :ref:`IronSide Secure Element in the nRF Connect SDK `. + +.. include:: ../samples.rst + :start-after: samples_general_info_start + :end-before: samples_general_info_end + +|filter_samples_by_board| + +.. toctree:: + :maxdepth: 1 + :caption: Subpages + :glob: + + ../../../samples/ironside_se/*/README diff --git a/doc/nrf/security.rst b/doc/nrf/security.rst index d9f4d2467b40..65a4779c5e9f 100644 --- a/doc/nrf/security.rst +++ b/doc/nrf/security.rst @@ -11,15 +11,17 @@ The features are made available either as built-ins in modules, drivers, and sub The |NCS| |release| allows you to develop applications with the following versions of security components: -.. list-table:: |NCS|, TF-M, and Mbed TLS versions +.. list-table:: |NCS|, TF-M, IronSide Secure Element, and Mbed TLS versions :header-rows: 1 :widths: auto * - |NCS| release - TF-M version + - IronSide Secure Element version - Mbed TLS version * - |release| - v2.1.2 + - v23.0.2+17 - 3.6.4 .. security_components_ver_table_end @@ -42,42 +44,55 @@ Expand the following section to see the table listing versions of different secu * - |NCS| release - TF-M version + - IronSide Secure Element version - Mbed TLS version * - Upcoming release (currently on the ``main`` branch of `sdk-nrf`_) - v2.2.0 + - v23.0.2+17 - 3.6.4 * - v3.1.0, v3.1.1 - v2.1.2 + - v20.0.0+1 - 3.6.4 * - v3.0.0 (up to v3.0.2) - v2.1.1 + - n/a - 3.6.3 * - v2.9.0 (up to v2.9.2) - v2.1.1 + - n/a - 3.6.2 * - v2.8.0 - v2.1.1 + - n/a - 3.6.2 * - v2.7.0 - v2.0.0 + - n/a - 3.5.2 * - v2.6.0 (up to v2.6.4) - v2.0.0 + - n/a - 3.5.2 * - v2.5.0 (up to v2.5.3) - v1.8.0 + - n/a - 3.3.0 * - v2.4.0 (up to v2.4.4) - v1.7.0 + - n/a - 3.3.0 * - v2.3.0 - v1.6.0 + - n/a - 3.1.0 * - v2.2.0 - v1.6.0 + - n/a - 3.1.0 * - v2.1.0 (up to v2.1.4) - v1.6.0 + - n/a - 3.1.0 The following table lists the available general security features. diff --git a/doc/nrf/security/ap_protect.rst b/doc/nrf/security/ap_protect.rst index d02bc85b85a8..c8c383b029a6 100644 --- a/doc/nrf/security/ap_protect.rst +++ b/doc/nrf/security/ap_protect.rst @@ -32,7 +32,7 @@ For detailed information, refer to the hardware documentation. - Default factory state - How to enable - How to disable - * - Hardware + * - Hardware and IronSide SE - Disabled - Writing ``Enabled`` to ``UICR.APPROTECT`` and performing a reset. - Issuing an ``ERASEALL`` command using CTRL-AP. @@ -86,10 +86,10 @@ See the related hardware documentation for more information about which implemen - `Debugger access protection for nRF9160`_ - Also :ref:`supports Secure AP-Protect ` * - nRF54H20 + - ✔ - n/a - n/a - - n/a - - Uses the :ref:`lifecycle state management ` mechanism exclusively + - See :ref:`UICR.APPROTECT `. * - nRF54L15 - n/a - ✔ @@ -167,7 +167,7 @@ Based on the available implementation types, you can configure the access port p - Description of the AP-Protect state - AP-Protect implementation type * - Locked - - All Series and devices + - All Series and devices except nRF54H20 - :kconfig:option:`CONFIG_NRF_APPROTECT_LOCK` (:kconfig:option:`CONFIG_NRF_SECURE_APPROTECT_LOCK` for Secure AP-Protect) - In this state, CPU uses the MDK system start-up file to enable and lock AP-Protect. UICR is not modified. - Hardware and software diff --git a/doc/nrf/security/psa_certified_api_overview.rst b/doc/nrf/security/psa_certified_api_overview.rst index d1fea73b0443..77fa5571c2c9 100644 --- a/doc/nrf/security/psa_certified_api_overview.rst +++ b/doc/nrf/security/psa_certified_api_overview.rst @@ -66,7 +66,7 @@ The following table provides an overview of the PSA Certified APIs support statu | `PSA Certified Crypto API 1.0.0`_ for builds with TF-M * - `PSA Certified Attestation API`_ - Supported - - `PSA Certified Attestation API 1.0`_ + - `PSA Certified Attestation API 1.0`_ (not supported for IronSide Secure Element firmware for nRF54H20) * - `PSA Certified Secure Storage API`_ - Supported - `PSA Certified Secure Storage API 1.0`_