TF-M Services

As explained in the Configurable build section, TF-M is built from a set of services that are isolated from each other. Services can be enabled or disabled based on the application requirements. Following sections describe the available TF-M services and their purpose.

Platform service 

The platform service is the mandatory implementation of the Platform RoT Services. It provides platform-specific services to other TF-M partitions and to a non-secure application. To enable the platform service, set the CONFIG_TFM_PARTITION_PLATFORM Kconfig option.

For user applications placed in the Non-Secure Processing Environment, you can set the CONFIG_TFM_ALLOW_NON_SECURE_FAULT_HANDLING Kconfig option, which enables more detailed error descriptions of faults from the application with the Zephyr fault handler.

The platform service also exposes the following nRF Connect SDK specific APIs for the non-secure application:

/* Search for the fw_info structure in firmware image located at address. */
int tfm_platform_firmware_info(uint32_t fw_address, struct fw_info *info);

/* Check if S0 is the active B1 slot. */
int tfm_platform_s0_active(uint32_t s0_address, uint32_t s1_address, bool *s0_active);

/* Writes a word to the secure memory as long as the address permissions allow it. */
enum tfm_platform_err_t tfm_platform_mem_write32(uint32_t addr, uint32_t value, uint32_t mask, uint32_t *result);

/* Reads data from the secure memory as long as the address range permissions allow it. */
enum tfm_platform_err_t tfm_platform_mem_read(void *destination, uint32_t addr, size_t len, uint32_t *result);

See TF-M input/output control (IOCTL) for more information about APIs available for the non-secure application.

For more information about the general features of the TF-M Platform partition, see TF-M Platform.

System Reset service 

The System Reset service is one of the default TF-M platform services that has a specific implementation for the nRF Connect SDK. It allows to perform a system reset through the TF-M platform service using the tfm_hal_system_reset() function.

This service is enabled when you enable the CONFIG_TFM_PARTITION_PLATFORM Kconfig option.

System OFF service 

The System OFF service is one of the TF-M platform services specific to the nRF Connect SDK. It allows the non-secure application to request the system to enter the System OFF mode using a secure service call.

The System OFF mode is part of the power and clock management system and is available on selected Nordic Semiconductor devices, including the nRF54L Series devices that support TF-M. For more details about the System OFF mode, see the device datasheet, for example the nRF54L15 Power and clock management page.

To enable the System OFF service in the nRF Connect SDK, enable the CONFIG_TFM_NRF_SYSTEM_OFF_SERVICE Kconfig option.

Zephyr’s System Off sample demonstrates how to use the System OFF service.

Internal Trusted Storage service 

The Internal Trusted Storage (ITS) service is one of Platform RoT Services. It implements the PSA Internal Trusted Storage APIs (PSA Certified Secure Storage API 1.0) to achieve confidentiality, authenticity and encryption in rest (optional).

To enable the ITS service, set the CONFIG_TFM_PARTITION_INTERNAL_TRUSTED_STORAGE Kconfig option.

ITS is meant to be used by other TF-M partitions. It must not be accessed directly by a user application placed in the Non-Secure Processing Environment. If you want the user application to access the contents of the partition, use the Protected Storage service.

This service is enabled as the default storage mechanism when you enable the Crypto service service. If you are using a device with the Key Management Unit (KMU), you can disable the Internal Trusted Storage service and start using KMU instead to save memory.

For more information about the general features of the TF-M ITS service, see TF-M ITS.

Encrypted ITS 

TF-M ITS encryption is a data protection mechanism in Internal Trusted Storage. It provides transparent encryption using a Master Key Encryption Key (MKEK) stored in hardware, with unique encryption keys derived for each file.

To enable TF-M ITS encryption, set the CONFIG_TFM_ITS_ENCRYPTED Kconfig option.

On Nordic Semiconductor devices, the hardware-accelerated AEAD scheme ChaChaPoly1305 is used with a 256-bit key. This key is derived with a key derivation function (KDF) based on NIST SP 800-108 CMAC. The input key of the KDF is the MKEK, a symmetric key stored in the Key Management Unit (KMU) of Nordic Semiconductor devices. The MKEK is protected by the KMU peripheral and its key material cannot be read by the software. It can only be used by reference.

The file ID is used as a derivation label for the KDF. This means that each file ID uses a different AEAD key. As long as each file has a unique file ID, the key used for encryption and authentication is unique.

To strengthen data integrity, the metadata of the ITS file (creation flags or size, or both) is used as authenticated data in the encryption process.

The nonce for the AEAD operation is generated by concatenating a random 8-byte seed and an increasing 4-byte counter. The random seed is generated once in the boot process and stays the same until reset.

Sizing the Internal Trusted Storage 

The RAM and flash usage of the ITS service are included in the tfm_secure partition. The storage itself is a separate tfm_its partition.

When using the Partition Manager, you can configure the size of the tfm_its with the CONFIG_PM_PARTITION_SIZE_TFM_INTERNAL_TRUSTED_STORAGE Kconfig option. The resulting partition is visible in the partitions.yml file in the build directory:

EMPTY_2:
  address: 0xea000
  end_address: 0xf0000
  placement:
    after:
    - tfm_its
  region: flash_primary
  size: 0x6000
tfm_its:
  address: 0xe8000
  end_address: 0xea000
  inside:
  - tfm_storage
  placement:
    align:
      start: 0x8000
    before:
    - tfm_otp_nv_counters
  region: flash_primary
  size: 0x2000

The Partition Manager can only align the start address of the tfm_its partition with the flash region size (see TF-M partition alignment requirements). If the size of the tfm_its does not equal the flash region size, the Partition Manager allocates an additional empty partition to fill the gap. See the Example of PS sizing with static partitions for an example on how to optimize the size of the tfm_its partition by manual configuration.

TF-M does not guarantee in build time that the tfm_its partition can hold the assets that are configured with the CONFIG_TFM_ITS_NUM_ASSETS and CONFIG_TFM_ITS_MAX_ASSET_SIZE options. Depending on the available flash size, the ITS can use one or two flash pages (4 KB) for ensuring power failure safe operations. In addition, ITS stores the bookkeeping information for the assets in the flash memory and the bookkeeping size scales with the configured number of assets. This can leave a very small amount of space for the actual assets.

It is recommended to test the ITS with the intended assets to ensure that the assets fit in the available space.

Crypto service 

The TF-M Crypto Service is one of Platform RoT Services. It implements the PSA Crypto APIs (PSA Certified Crypto API 1.4.0) and provides cryptographic services to other TF-M partitions and to the non-secure application.

To enable the crypto service, set the CONFIG_TFM_PARTITION_CRYPTO Kconfig option.

You can configure the service directly using the CONFIG_TFM_CRYPTO_* Kconfig options found in the zephyr/modules/trusted-firmware-m/Kconfig.tfm.crypto file. However, it is recommended to use the CONFIG_PSA_WANT_* Kconfig options to enable the required algorithms and key types. These will enable the required CONFIG_TFM_CRYPTO_* Kconfig options.

TF-M uses hardware unique keys when the PSA Crypto key derivation APIs are used, and psa_key_derivation_setup is called with the algorithm TFM_CRYPTO_ALG_HUK_DERIVATION.

When enabled, the Crypto service by default uses the Internal Trusted Storage service to store the keys and other sensitive data. If you are using a device with the Key Management Unit (KMU), you can disable the Internal Trusted Storage service and start using KMU instead to save memory.

For more information about the general features of the Crypto partition, see TF-M Crypto.

Protected Storage service 

The Protected Storage (PS) service is one of possible Application RoT Services. It implements the PSA Protected Storage APIs (PSA Certified Secure Storage API 1.0).

To enable the PS service, set the CONFIG_TFM_PARTITION_PROTECTED_STORAGE Kconfig option.

The PS service uses the ITS service to achieve confidentiality and authenticity. In addition, it provides encryption, authentication, and rollback protection.

A user application placed in the Non-Secure Processing Environment should use the PS partition for storing sensitive data.

For more information about the general features of the TF-M PS service, see TF-M PS.

Sizing the Protected Storage partition 

The RAM and flash usage of the PS service are included in the tfm_secure partition. The storage itself is a separate tfm_ps partition. Additionally, the PS partition requires non-volatile counters for rollback protection. Those are stored in the tfm_otp_nv_counters partition.

When using the Partition Manager, the size of the tfm_ps is configured with the CONFIG_PM_PARTITION_SIZE_TFM_PROTECTED_STORAGE Kconfig option. The size of the tfm_otp_nv_counters is configured with the CONFIG_PM_PARTITION_SIZE_TFM_OTP_NV_COUNTERS Kconfig option.

Resulting partitions are visible in the partitions.yml file in the build directory:

EMPTY_0:
  address: 0xfc000
  end_address: 0x100000
  placement:
    after:
    - tfm_ps
  region: flash_primary
  size: 0x4000
EMPTY_1:
  address: 0xf2000
  end_address: 0xf8000
  placement:
    after:
    - tfm_otp_nv_counters
  region: flash_primary
  size: 0x6000
tfm_otp_nv_counters:
  address: 0xf0000
  end_address: 0xf2000
  inside:
  - tfm_storage
  placement:
    align:
      start: 0x8000
    before:
    - tfm_ps
  region: flash_primary
  size: 0x2000
tfm_ps:
  address: 0xf8000
  end_address: 0xfc000
  inside:
  - tfm_storage
  placement:
    align:
      start: 0x8000
    before:
    - end
  region: flash_primary
  size: 0x4000

Similarly to Sizing the Internal Trusted Storage, the Partition Manager can only align the start addresses of the partitions with the flash region size. The Partition Manager allocates an additional empty partition to fill the gaps.

See Example of PS sizing with static partitions for an example on how to optimize the size of the partitions by manual configuration.

TF-M does not guarantee in build time that the tfm_ps partition can hold the assets that are configured with the CONFIG_TFM_PS_NUM_ASSETS and CONFIG_TFM_PS_MAX_ASSET_SIZE options. The PS partition uses the ITS internally to store the assets in tfm_ps. This means that some of the flash space is reserved for the ITS functionality. Additionally, the PS service stores the file metadata in object tables, which also consumes flash space. The size of the object table scales with the number of configured assets and two object tables (old and new) are required when performing PS operations. This might leave a very small amount of space for the actual assets.

It is highly recommended to test the PS with the intended assets to ensure that the assets fit in the available space.

Example of PS sizing with static partitions 

With devices where ROM granularity is higher than the flash page size (nRF53 Series and nRF91 Series), it might be useful to configure the tfm_its, tfm_ps and tfm_otp_nv_counters partitions as static partitions. For example, when these three partitions are combined into a single tfm_storage partition, only the tfm_storage partition needs to be aligned with the flash region size. This allows potential optimizations in the flash memory usage.

You can start by copying the default configuration from the partitions.yml file in the build directory as the pm_static.yml file in the application directory. The following snippet shows the meaningful parts of the default configuration for the tfm_its, tfm_ps and tfm_otp_nv_counters partitions in the nRF9151 SoC:

EMPTY_0:
  address: 0xfc000
  end_address: 0x100000
  placement:
    after:
    - tfm_ps
  region: flash_primary
  size: 0x4000
EMPTY_1:
  address: 0xf2000
  end_address: 0xf8000
  placement:
    after:
    - tfm_otp_nv_counters
  region: flash_primary
  size: 0x6000
EMPTY_2:
  address: 0xea000
  end_address: 0xf0000
  placement:
    after:
    - tfm_its
  region: flash_primary
  size: 0x6000
app:
  address: 0x40000
  end_address: 0xe8000
  region: flash_primary
  size: 0xa8000
tfm_nonsecure:
  address: 0x40000
  end_address: 0xe8000
  orig_span: &id004
  - app
  region: flash_primary
  size: 0xa8000
  span: *id004
tfm_its:
  address: 0xe8000
  end_address: 0xea000
  inside:
  - tfm_storage
  placement:
    align:
      start: 0x8000
    before:
    - tfm_otp_nv_counters
  region: flash_primary
  size: 0x2000
tfm_otp_nv_counters:
  address: 0xf0000
  end_address: 0xf2000
  inside:
  - tfm_storage
  placement:
    align:
      start: 0x8000
    before:
    - tfm_ps
  region: flash_primary
  size: 0x2000
tfm_ps:
  address: 0xf8000
  end_address: 0xfc000
  inside:
  - tfm_storage
  placement:
    align:
      start: 0x8000
    before:
    - end
  region: flash_primary
  size: 0x4000
tfm_storage:
  address: 0xe8000
  end_address: 0xfc000
  orig_span: &id006
  - tfm_ps
  - tfm_its
  - tfm_otp_nv_counters
  region: flash_primary
  size: 0x14000
  span: *id006

The tfm_storage partition that holds the tfm_its, tfm_ps and tfm_otp_nv_counters partitions must be aligned with the flash region size, so that you can configure it as secure. After removing the empty partitions, unnecessary alignments and adjusting the sizes of the partitions, the same information in the pm_static.yml file should look like this:

app:
  address: 0x40000
  end_address: 0xf8000
  region: flash_primary
  size: 0xb8000
tfm_nonsecure:
  address: 0x40000
  end_address: 0xf8000
  orig_span: &id004
  - app
  region: flash_primary
  size: 0xb8000
  span: *id004
tfm_its:
  address: 0xf8000
  end_address: 0xfa000
  inside:
  - tfm_storage
  placement:
    before:
    - tfm_otp_nv_counters
  region: flash_primary
  size: 0x2000
tfm_otp_nv_counters:
  address: 0xfa000
  end_address: 0xfc000
  inside:
  - tfm_storage
  placement:
    before:
    - tfm_ps
  region: flash_primary
  size: 0x2000
tfm_storage:
  address: 0xf8000
  end_address: 0x100000
  orig_span: &id006
  - tfm_ps
  - tfm_its
  - tfm_otp_nv_counters
  region: flash_primary
  size: 0x8000
  span: *id006

The tfm_storage partition is still aligned with the flash region size and the tfm_its, tfm_ps and tfm_otp_nv_counters partitions are placed inside it. The available space for the non-secure application has increased by 0x10000 bytes.

Note

For devices that are intended for production and meant to be updated in the field, you should always use static partitions to ensure that the partitions are not moved around in the flash memory.

Initial Attestation service 

The Initial Attestation service implements the PSA Initial Attestation APIs (PSA Certified Attestation API 1.0). The service allows the device to prove its identity to a remote entity.

To enable the Initial Attestation service, set the CONFIG_TFM_PARTITION_INITIAL_ATTESTATION Kconfig option.

The TF-M: PSA template sample demonstrates how to use the Initial Attestation service.

The Initial Attestation service is not enabled by default. Keep it disabled unless you need attestation.

For more information about the general features of the TF-M Initial Attestation service, see TF-M Attestation.