.. _spe_nspe_architecture: SPE/NSPE Architecture and Advanced Build Options ################################################# Overview ******** The SPE (Secure Processing Environment) and NSPE (Non-Secure Processing Environment) architecture is an advanced security feature for Atmosic ARM Cortex-M based SoCs with TrustZone-M technology. This document describes the SPE/NSPE architecture and advanced build configurations for developers who require this level of security separation. For most applications, the recommended approach is to use single images built in a similar fashion with other SOC platforms. This document is provided for reference and for applications that specifically require SPE/NSPE separation. .. attention:: In previous SDK releases, building an NSPE images required the use of ``_ns`` designated board variants. This is no longer required and such board files may be deprecated and removed in the SDK. Developers can use the standard board without the ``_ns`` designation with the SPE and MCUBOOT images, however additional device tree flags are required when building the user application that will operate in the non-secure domain. SPE/NSPE Architecture ********************* The SPE/NSPE architecture separates an application into two security domains: - **SPE (Secure Processing Environment)**: A lightweight secure application that runs in the secure domain and provides security services to the non-secure application. - **NSPE (Non-Secure Processing Environment)**: The main application that runs in the non-secure domain and can call secure services through Non-Secure Callable (NSC) APIs. The non-secure application operates in a separate memory space (NS) and is isolated by TrustZone. The NSPE can have a significant attack surface since it runs the full application stack and interacts with the outside world through wireless interfaces and I/O devices. The PSA (Platform Security Architecture, https://www.psacertified.org/) trade group defines the SPE/NSPE application architecture and its benefits for securing IoT products. Information about the SPE can be found in the :doc:`SPE sample <../openair/samples/spe/README.rst>` Board Variants ************** When building SPE/NSPE applications, the build system will use a single board (e.g., ``ATMEVK-3330e-QN-6``) for both SPE and NSPE image builds. If MCUBOOT is used the additional ``mcuboot`` variant must be supplied (e.g., ``ATMEVK-3330e-QN-6@mcuboot``) The SPE and NSPE are separate Zephyr applications requiring different board and system resources (secure versus non-secure). The MCUBOOT application image also uses the same board file since the resource requirements are similar to the SPE. MCUBOOT specific board overlays are provided to configure resource settings appropriate for MCUBOOT. Building SPE/NSPE Applications ******************************* Sysbuild ======== Sysbuild is the recommended method for building SPE/NSPE applications. Sysbuild will build each domain and manage device tree configurations for the non-secure image. The SPE/NSPE application can specify SPE use using the ``SB_CONFIG_SPE=y`` in the application ``.yaml`` file:: my_application: sysbuild: true extra_args: - SB_CONFIG_SPE=y my_application.mcuboot: sysbuild: true extra_args: - SB_CONFIG_SPE=y - SB_CONFIG_BOOTLOADER_MCUBOOT=y - SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y Building -------- Building the application with a SPE (non-MCUBOOT): .. code-block:: bash west build -p always --sysbuild -b -T my_application Build the application with a SPE with MCUBOOT support: .. code-block:: bash west build -p always --sysbuild -b @mcuboot -T my_application.mcuboot Flashing -------- Flash all images (supports MCUBOOT images as well): .. code-block:: bash west flash --skip-rebuild --build-dir --verify --device= [--jlink] --erase_all --fast_load Manual Build ============ The following instructions are made available for manually building and flashing the SPE and NSPE. It is highly recommended to use sysbuild to manage mult-image builds as the sysbuild build manages all flags through sysbuild YAML files and does not require extensive command line options and avoids misconfiguration. Build Commands for SPE and NSPE ------------------------------- The SPE needs to be built first and its build output supplied to the application during its build process. Nonsecure callable API invocations in NSPE code are resolved by references to the SPE image. The variables used in this section:: : openair/samples/spe : bootloader/mcuboot/boot/zephyr : openair/samples/hello_world : ATMEVK-3330-QN-6 Build the SPE: .. code-block:: bash west build -p -s -b -d build/spe Build the NSPE (user application) with the same board: .. code-block:: bash west build -p -s -b -d build/ -- -DCONFIG_SPE_PATH=\"build/spe\" -DDTS_EXTRA_CPPFLAGS="-DATM_NS_APP" The NSPE build requires the DTS option ``-DATM_NS_APP`` to configure the device tree as a non-secure application. When building with MCUBOOT append the ``@mcuboot`` variant to the for both the SPE and NSPE images. This will apply additional board overlays to configure the system partition layout for MCUBOOT and over-the-air upgrades. It is highly recommended to switch to the sysbuild method when using MCUBOOT:: .. code-block:: bash west build -p -s -b @mcuboot -d build/ -- -DCONFIG_SPE_PATH=\"build/spe\" -DDTS_EXTRA_CPPFLAGS="-DATM_NS_APP" When MCUBOOT is used, the MCUBOOT application forms an additional application image. MCUBOOT requires the partition layout to include the SPE+NSPE as a merged image in SLOT0 (primary slot). MCUBOOT is unaware that a SPE is in use, however it should see the same partition layout as the SPE and the NSPE when built. Set the option ``-DATM_SPE_APP`` when building MCUBOOT. Note that the SPE sample application automatically sets this option since it must always use a SPE-enabled partition layout. .. code-block:: bash west build -p -s -b @mcuboot_bl -d build/mcuboot -- -DDTS_EXTRA_CPPFLAGS="-DATM_USE_SPE" Flash Commands for SPE and NSPE ------------------------------- Flash the SPE and the application separately: .. code-block:: bash west flash --skip-rebuild --device --verify [--jlink] --build-dir build/spe --noreset --erase_flash --fast_load west flash --skip-rebuild --device --verify [--jlink] --build-dir build/ --fast_load Optionally flash MCUBOOT: .. code-block:: bash west flash --skip-rebuild --device --verify [--jlink] --build-dir build/mcuboot --fast_load NSC API Development Guidelines ******************************* The example SPE is sufficient to bootstrap any NSPE application. An example custom NSC function example is provided in the `openair/samples/spe/src/cust_sec_func/` folder. NSC APIs are used to add services implemented in the SPE. When developing custom NSC APIs in the SPE environment, the following guidelines should be followed: 1. NSC functions must be declared with the ``__attribute__((cmse_nonsecure_entry))`` attribute 2. NSC functions should have simple signatures with limited parameter passing 3. NSC functions should validate all inputs from the non-secure domain 4. NSC functions should not expose sensitive secure data to the non-secure domain 5. NSC function implementations should be placed in dedicated source files for clarity