Building and configuring TF-M

TF-M is one of the images that are built as part of a multi-image application.

To add TF-M to your build, enable the CONFIG_BUILD_WITH_TFM configuration option by adding it to your prj.conf file.

Note

If you use menuconfig to enable CONFIG_BUILD_WITH_TFM, you must also enable its dependencies.

By default, TF-M is built with the configurable version on all devices except the Thingy:91 and the Thingy:91 X which default to the minimal version.

Board targets supported by TF-M 

The boards supported by the SDK distinguish entries according to which CPU is to be targeted (for multi-core SoCs) and whether the security by separation is to be used or not (addition of the */ns variant if it is used). To build with TF-M in the nRF Connect SDK, you must use a board target with the */ns variant.

The following table lists the board targets that you can use to build with TF-M. See Board support for the complete list of boards and board targets supported by the SDK.

Board targets supported by TF-M
Hardware platform	PCA number	Board name	TF-M board target
nRF9161 DK	PCA10153	nrf9161dk	`nrf9161dk/nrf9161/ns`
nRF9160 DK	PCA10090	nrf9160dk	`nrf9160dk/nrf9160/ns`
nRF9151 DK	PCA10171	nrf9151dk	`nrf9151dk/nrf9151/ns`
nRF9131 EK	PCA10165	nrf9131ek	`nrf9131ek/nrf9131/ns`
nRF54LV10 DK	PCA10188	`nrf54lv10dk`	`nrf54lv10dk/nrf54lv10a/cpuapp/ns`
nRF54LM20 DK	PCA10184	nrf54lm20dk	`nrf54lm20dk/nrf54lm20a/cpuapp/ns` `nrf54lm20dk/nrf54lm20b/cpuapp/ns`
nRF54L15 DK	PCA10156	nrf54l15dk	`nrf54l15dk/nrf54l15/cpuapp/ns`
nRF54L10 emulated on the nRF54L15 DK	PCA10156	nrf54l10dk/nrf54l10	`nrf54l15dk/nrf54l10/cpuapp/ns`
nRF5340 DK	PCA10095	nrf5340dk	`nrf5340dk/nrf5340/cpuapp/ns`
Thingy:53	PCA20053	thingy53	`thingy53/nrf5340/cpuapp/ns`
nRF7002 DK	PCA10143	nrf7002dk	`nrf7002dk/nrf5340/cpuapp/ns`
Thingy:91	PCA20035	thingy91	`thingy91/nrf9160/ns`
Thingy:91 X	PCA20065	thingy91x	`thingy91x/nrf9151/ns`

Enabling secure services 

To enable the secure services in TF-M, you must use the TF-M Crypto Service PSA Crypto API implementation.

Complete the following steps to enable the secure services in TF-M:

Enable CONFIG_NRF_SECURITY to use the PSA Crypto APIs through nRF Security.
Enable the CONFIG_BUILD_WITH_TFM configuration option by adding it to your prj.conf file.
Configure PSA Crypto API Kconfig options.
Build the application with Minimal build or Configurable build.

After building the application, the TF-M secure image enables the use of the hardware acceleration, while the Kconfig configurations in the nRF Security subsystem control the features enabled in TF-M.

See Crypto service for more information about the TF-M Crypto partition.

Note

Depending on the implementation you are using, the nRF Connect SDK build system uses different versions of the PSA Crypto API.

PSA Crypto API versions by implementation
Implementation	PSA Crypto API version
Oberon PSA Crypto	v1.4.0
TF-M Crypto Service	v1.4.1
IronSide Secure Enclave	v1.3.1

Minimal build 

The default configuration of TF-M has all supported features enabled, which results in a significant memory footprint. For this reason, the nRF Connect SDK provides a minimal version of the TF-M secure application, which shows how to configure a reduced version of TF-M.

The secure services supported by the minimal version allow for:

Generating random numbers using the random generator available in the device (see psa_generate_random() in crypto.h).
Using the platform services with tfm_platform_api.h from the non-secure side (except the tfm_platform_nv_counter_* functions). This includes sending platform-specific service requests using tfm_ioctl_core_api.h and tfm_ioctl_api.h.
Reading secure memory from the non-secure application (strictly restricted to a list of allowed addresses). Depending on the device, this lets you read metadata in the bootloader, verify FICR or UICR values, or access a peripheral that is secure-only.
Rebooting from the non-secure side.

The minimal build uses an image of 32 kB. It is set with the CONFIG_TFM_PROFILE_TYPE_MINIMAL Kconfig option that is enabled by default on the Thingy:91 and Thingy:91 X devices.

With the minimal build, the configuration of TF-M is severely limited. The only configurable option is to enable a security service for cryptographic hashes. For example, you can enable the PSA_WANT_ALG_SHA_256 Kconfig option to provide SHA-256 support using TF-M.

Configurable build 

The configurable build is the full TF-M implementation that lets you configure all of its features. It does not have the constraints of the minimal build.

To enable the configurable, full TF-M build, make sure the following Kconfig options are configured:

CONFIG_BUILD_WITH_TFM is enabled
CONFIG_TFM_PROFILE_TYPE_NOT_SET is enabled

For description of the build profiles, see TF-M Profiles. It is not recommended to use predefined TF-M profiles as they might result in a larger memory footprint than necessary.

When the CONFIG_TFM_PROFILE_TYPE_NOT_SET Kconfig option is enabled, the build process will not set a specific TF-M profile type. This allows for a more flexible configuration where individual TF-M features can be enabled or disabled as needed. It also provides more control over the build process and allows for a more fine-grained configuration of the TF-M secure image.

To configure the features of the TF-M secure image, you must choose which TF-M partitions and which secure services to include in the build.

Note

A “TF-M partition” in this context refers to a secure partition within the Trusted Firmware-M architecture. These partitions are isolated from each other and from the non-secure application code. A service running inside TF-M would typically be implemented within one of these secure partitions.

Each service can be a separate partition, or multiple related services might be grouped into a single partition. The partition provides the execution environment for the service. It handles secure function calls and ensures that the service’s code and data are protected from unauthorized access.

Following are the available Kconfig options for TF-M partitions:

Available TF-M Partitions
Option name	Description	Default value	Dependencies
`CONFIG_TFM_PARTITION_PLATFORM`	Provides Platform service.	Enabled
`CONFIG_TFM_PARTITION_CRYPTO`	Provides Crypto service.	Enabled
`CONFIG_TFM_PARTITION_PROTECTED_STORAGE`	Provides Protected Storage service.	Enabled	PLATFORM, CRYPTO
`CONFIG_TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`	Provides Internal Trusted Storage service.	Enabled
`CONFIG_TFM_PARTITION_INITIAL_ATTESTATION`	Provides Initial Attestation service.	Disabled	CRYPTO

Secure Partition Manager backend configuration 

TF-M’s Secure Partition Manager (SPM) backend may also be configured, depending on the isolation requirements of the application.

Note

Do not confuse TF-M’s Secure Partition Manager with Secure Partition Manager that was removed in the nRF Connect SDK v2.1.0. See also Migrating from Secure Partition Manager to Trusted Firmware-M in the nRF Connect SDK v2.0.0 documentation.

SPM backends
Option	Description	Allowed isolation levels
`CONFIG_TFM_SFN`	With SFN, the Secure Partition is made up of a collection of callback functions that implement secure services.	Level 1
`CONFIG_TFM_IPC`	With IPC, each Secure Partition processes signals in any order, and can defer responding to a message while continuing to process other signals.	Levels 1, 2 and 3

To control the number of logging messages, set the CONFIG_TFM_SPM_LOG_LEVEL Kconfig option. To disable logging, set the CONFIG_TFM_LOG_LEVEL_SILENCE option.

The size of TF-M partitions is affected by multiple configuration options and hardware-related options. The code and memory size of TF-M increases when more services are enabled, but the selected hardware also places limitations on how the separation of secure and non-secure is made.

TF-M is linked as a separate partition in the final binary image. The reserved sizes of its RAM and flash partitions are configured by the CONFIG_PM_PARTITION_SIZE_TFM and CONFIG_PM_PARTITION_SIZE_TFM_SRAM options. These configuration options allow you to specify the size allocated for the TF-M partition in the final binary image. Default partition sizes vary between device families and are not optimized to any specific use case.

To optimize the TF-M size, find the minimal set of features to satisfy the application needs and then minimize the allocated partition sizes while still conforming to the alignment and granularity requirements of given hardware.

TF-M partition alignment requirements 

TF-M requires that secure and non-secure partition addresses must be aligned to the flash region size CONFIG_NRF_TRUSTZONE_FLASH_REGION_SIZE. The nRF Connect SDK ensures that they in fact are aligned and comply with the TF-M requirements.

The following differences apply to the device families:

On nRF53 and nRF91 Series devices, TF-M uses the SPU to enforce the security policy between the partitions, so the CONFIG_NRF_TRUSTZONE_FLASH_REGION_SIZE Kconfig option is set to the SPU flash region size.
On nRF54L15 devices, TF-M uses the MPC to enforce the security policy between the partitions, so the CONFIG_NRF_TRUSTZONE_FLASH_REGION_SIZE Kconfig option is set to the MPC region size.

Region limits on different hardware
Family	RAM granularity	ROM granularity
nRF91 Series	8 kB	32 kB
nRF53 Series	8 kB	16 kB
nRF54 Series	4 kB	4 kB

Partition alignment granularity on different nRF devices

The imaginary example above shows a worst-case scenario in the nRF91 Series where the flash region size is 32 kB and both the TF-M binary and secure storage are 12 kB. This leaves a significant amount of unused space in the flash region. In a real-world scenario, the size of the TF-M binary and secure storage is usually much larger.

When the Partition Manager is enabled, it will take into consideration the alignment requirements. But when the static partitions are used, the user is responsible for following the alignment requirements.

Example of aligning partitions with flash regions

Note

If you are experiencing any partition alignment issues when using the Partition Manager, check the known issues page on the main branch.

You need to align the tfm_nonsecure, tfm_storage, and nonsecure_storage partitions with the TrustZone flash region size. Both the partition start address and the partition size need to be aligned with the flash region size CONFIG_NRF_TRUSTZONE_FLASH_REGION_SIZE.

Note

The tfm_nonsecure partition is placed after the tfm_secure partition, thus the end address of the tfm_secure partition is the same as the start address of the tfm_nonsecure partition. As a result, altering the size of the tfm_secure partition affects the start address of the tfm_nonsecure partition.

The following static partition snippet shows a non-aligned configuration for nRF5340 which has a TrustZone flash region size CONFIG_NRF_TRUSTZONE_FLASH_REGION_SIZE of 0x4000.

tfm_secure:
  address: 0x4000
  size: 0x4200
  span: [mcuboot_pad, tfm]
mcuboot_pad:
  address: 0x4000
  size: 0x200
tfm:
  address: 0x4200
  size: 0x4000
tfm_nonsecure:
  address: 0x8200
  size: 0x4000
  span: [app]
app:
  address: 0x8200
  size: 0x4000

In the above example, the tfm_nonsecure partition starts at address 0x8200, which is not aligned with the requirement of 0x4000. Since tfm_secure spans the mcuboot_pad and tfm partitions, you can decrease the size of any of them by 0x200 to fix the alignment issue. Decrease the size of the (optional) mcuboot_pad partition, and thus the size of the tfm_secure partition, as follows:

tfm_secure:
  address: 0x4000
  size: 0x4000
  span: [mcuboot_pad, tfm]
mcuboot_pad:
  address: 0x4000
  size: 0x0
tfm:
  address: 0x4000
  size: 0x4000
tfm_nonsecure:
  address: 0x8000
  size: 0x4000
  span: [app]
app:
  address: 0x8000
  size: 0x4000

Analyzing `tfm_secure` partition size 

You can analyze the size of the tfm_secure partition from the build output:

[71/75] Linking C executable bin/tfm_s.axf
Memory region   Used Size  Region Size  %age Used
   FLASH:       31972 B       256 KB     12.20%
   RAM:         4804 B        88 KB      5.33%

The example shows that the CONFIG_PM_PARTITION_SIZE_TFM Kconfig option for the tfm_secure partition is set to 256 kB and the TF-M binary uses 32 kB of the available space. Similarly, the CONFIG_PM_PARTITION_SIZE_TFM_SRAM option for the tfm_secure partition is set to 88 kB and the TF-M binary uses 5 kB of the available space. You can use this information to optimize the size of the TF-M, as long as it is within the alignment requirements explained in the previous section.

Tools for analyzing the `tfm_secure` partition size 

The TF-M build system is compatible with Zephyr’s Footprint and Memory Usage tools that let you generate RAM and ROM usage reports (using Dedicated image build targets). You can use the reports to analyze the memory usage of the different TF-M partitions and see how changing the Kconfig options affects the memory usage.

Depending on your development environment, you can generate memory reports for TF-M in the following ways:

You can use the Memory report feature in the nRF Connect for VS Code to check the size and percentage of memory that each symbol uses on your device for RAM, ROM, and partitions (when applicable).

You can use the Dedicated image build targets tfm_ram_report and tfm_rom_report targets for analyzing the memory usage of the TF-M partitions inside the tfm_secure partition. For example, after building the TF-M Hello World sample for the nrf9151dk/nrf9151/ns board target, you can run the following commands from your application root directory to generate the RAM memory report for TF-M in the terminal:

west build -d build/tfm_hello_world -t tfm_ram_report

For more information about the tfm_ram_report and tfm_rom_report targets, refer to the TF-M Build System documentation.