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 SPE sample

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):

west build -p always --sysbuild <application> -b <board> -T my_application

Build the application with a SPE with MCUBOOT support:

west build -p always --sysbuild <application> -b <board>@mcuboot -T my_application.mcuboot

Flashing

Flash all images (supports MCUBOOT images as well):

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:

<SPE>: openair/samples/spe
<MCUBOOT>: bootloader/mcuboot/boot/zephyr
<APP>: openair/samples/hello_world
<BOARD>: ATMEVK-3330-QN-6

Build the SPE:

west build -p -s <SPE> -b <BOARD> -d build/spe

Build the NSPE (user application) with the same board:

west build -p -s <APP> -b <BOARD> -d build/<APP> -- -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 <BOARD> 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 <APP> -b <BOARD>@mcuboot -d build/<APP> – -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.

west build -p -s <MCUBOOT> -b <BOARD>@mcuboot_bl -d build/mcuboot -- -DDTS_EXTRA_CPPFLAGS="-DATM_USE_SPE"

Flash Commands for SPE and NSPE

Flash the SPE and the application separately:

west flash --skip-rebuild --device <DEVICE_ID> --verify [--jlink] --build-dir build/spe --noreset --erase_flash --fast_load
west flash --skip-rebuild --device <DEVICE_ID> --verify [--jlink] --build-dir build/<APP> --fast_load

Optionally flash MCUBOOT:

west flash --skip-rebuild --device <DEVICE_ID> --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