Trusted Firmware-M (TF-M)

Supported ICs

Ameba SoC

RTL8721Dx

RTL8726E

RTL8720E

RTL8730E

Supported

Y

N

N

N

Introduction

The security services are grouped into individual secure partitions by category in the Trusted Firmware-M (TF-M). A secure partition is the operational unit within the TF-M, possessing its own resources and a unique execution thread. Also, a secure partition is the basic unit for scheduling and isolation of the secure partitions.

../../_images/tf_m_secure_partition.png

Secure partitions

The following secure partitions are provided in the SDK by default:

  • Secure partition providing protected storage services (Protected Storage and Internal Trusted Storage)

  • Secure partition providing crypto services

  • Secure partition providing initial attestation

Secure services are upgradable code that implements a set of services available to non-secure applications at runtime, and manages critical assets isolated from non-secure applications. Non-secure applications cannot access to any critical assets directly but can invoke secure services that use these critical assets.

The secure partition implements the isolation of PSA Root of Trust (PRoT) and Application Root of Trust Service (ARoT) by Memory Protection Unit (MPU), with PRoT running in privileged mode and ARoT running in unprivileged mode. This corresponds to at least PSA isolation level 2.

../../_images/tf_m_prot_arot.png

PRoT and ARoT

The TF-M Profile Medium is used in SDK to implement PSA isolation level 2, which defines the following feature set:

  • Firmware Framework

    • Inter-Process Communication (IPC) model

    • Isolation level 2

  • Internal Trusted Storage (ITS)

  • Crypto

    • Supports both symmetric cryptography and asymmetric cryptography

    • Asymmetric key based cipher suite suggested in TLS/DTLS profiles for IoT and CoAP, including

      • Authenticated Encryption with Associated Data (AEAD) algorithm

      • Asymmetric key algorithm based signature and verification

      • Public-key cryptography based key exchange

      • Hash function

      • HMAC for default Pseudorandom Function (PRF)

    • Asymmetric digital signature and verification for Initial Attestation Token (IAT)

  • Initial Attestation

    • Asymmetric key algorithm based Initial Attestation

  • Protected Storage (PS) if off-chip storage device is integrated

    • Data confidentiality

    • Data integrity

    • Rollback protection

Crypto Service

As suggested in CoAP, TF-M Profile Medium selects TLS_ECDHE_ECDSA_WITH_AES_128_CCM as reference by default, which requires:

  • ECDHE_ECDSA as key exchange algorithm.

  • AES-128-CCM (AES CCM mode with 128-bit key) as AEAD algorithm. Platforms can implement AES-128-CCM with truncated authentication tag to achieve less network bandwidth.

  • SHA256 as Hash function.

  • HMAC as Message Authentication Code algorithm.

Users can modify the default algorithm in ${CMAKE_SOURCE_DIR}\lib\ext\mbedcrypto\mbedcrypto_config\tfm_mbedcrypto_config_profile_medium.h file, where ${CMAKE_SOURCE_DIR} is {SDK}\component\soc\common\trusted-firmware-m\.

Refer to Chapter 10 Cryptographic operation reference in IHI0086-PSA_Certified_Crypto_API-1.1.2.pdf for more usage.

Initial Attestation

ECC curve secp256r1 should be supported.

Refer to Chapter 4 API reference in IHI0085-PSA_Certified_Attestation_API-1.0.3.pdf for more usage.

TF-M APIs

The following secure services are provided in the current SDK:

Partition

Privileged:sup:[1]

Model:sup:[1]

Crypto

PRoT

SFN

Initial attestation

PRoT

SFN

Internal trusted storage

PRoT

SFN

Protected storage

ARoT

SFN

Platform

PRoT

SFN

NS agent:sup:[2]

PRoT

IPC

Note

[1] The difference between Privileged and Model is:

  • Privileged:

    • In the Secure World, if an ARoT partition needs to access the system resources, it can only do this by calling the APIs provided by PRoT.

    • In the Non-Secure World, secure services can only be used by calling the PSA APIs.

  • Model:

    • One partition must work under as one of the runtime models: Inter-process communication (IPC) model or Secure Function (SFN) model.

    • For IPC model partition service, there is one thread inside the partition that keeps waiting for signals. SPM converts the service accessing information from the client API call into messages, asserts a signal to the partition, finds out the corresponding partition, and replies partition service returned result to the client. To accomplish this, users need to call psa_connect() to establish a connection with the partition that provides the service, then call psa_call() to execute the specified service, and finally call psa_close() to disconnect the connection. Since the service accesses can be converted to messages and data is processed in local buffer, multiple service accesses can be handled concurrently.

    • For SFN model partition service, users only need to call psa_call() to execute the specified service, which is similar to calling library functions.

[2] The NS agent is a special partition that does not provide any services. The TF-M will jump to the Non-Secure World via NS agent partition after the TF-M initialization is completed.

After the TF-M build is successful, the SDK will automatically copy the API source code provided by each partition under {SDK}\amebadplus_gcc_project\project_km4\asdk\build_tfm\install\interface\src\ to {SDK}\amebadplus_gcc_project\project_km4\ src_tfm\interface\src, so that the Non-Secure World can call these APIs directly because the API source code will also be compiled automatically.

The tfm_psa_ns_api.c file under {SDK}\amebadplus_gcc_project\project_km4\src_tfm\interface\src\ calls the Non-Secure Callable (NSC) APIs provided by TF-M for data interaction. The following sections illustrate the details of these NSC APIs.

tfm_psa_framework_version_veneer

Items

Description

Introduction

Retrieve the version of the PSA Framework API that is implemented.

Parameters

None

Return

The version of the PSA Framework

tfm_psa_version_veneer

Items

Description

Introduction

Retrieve the version of an RoT Service or indicate that it is not present on this system.

Parameters
sid:

the ID of secure service

Return

The return value > 0 means the version of the implemented RoT Service

tfm_psa_connect_veneer

Items

Description

Introduction

Connect to an RoT Service by its SID and Requested version of the RoT Service

Parameters
sid:

the ID of secure service

version:

the version of the implemented RoT Service

Return

The handle to connect

tfm_psa_call_veneer

Items

Description

Introduction

Call a secure function referenced by a connection handle

Parameters
handle:

the handle to connect

ctrl_param:

combined in uint32_t, includes request type

in_vec:

point to the array of input/ref psa_invec structures

out_vec:

point to the array of output/ref psa_outvec structures

Return

The psa_status_t structure

  • 0: success

  • Others: Fail

tfm_psa_close_veneer

Items

Description

Introduction

Close connection to secure function referenced by a connection handle.

Parameters
handle:

the handle to connection

Return

None

Protected Storage Service

  • Protected Storage (PS): The TF-M PS service implements PSA PS APIs that allow data to be encrypted and the results to be written to potentially untrusted storage. As a reference, the PS service uses the AES-CCM algorithm based on the AEAD encryption to protect the integrity and validity of the data.

  • Internal Trusted Storage (ITS): The TF-M ITS service implements the PSA ITS APIs to allow writing data to the built-in Flash memory area. The implemention in the current SDK is to use AES-GCM algorithm provided by IPSEC_S, with File ID as the IV and a derived key as the AAD to protect the integrity and confidentiality of the data.

Refer to Chapter 5 API Reference in IHI0087-PSA_Certified_Secure_Storage_API-1.0.2.pdf for more usage.

TF-M OTP

Realtek provides Read Protection (RDP) based on PSA isolation level 1. With the implementation of TF-M, the original Read Protection implementation is called RDP_BASIC, and Read Protection implementation with TF-M is called RDP_TFM. The OTP bit is the same for both RDP_BASIC and RDP_TFM. After enabling RDP, users need to choose whether to enable RDP_BASIC or RDP_TFM.

----TrustZone by RDP or TFM----

      ( ) RDP_BASIC
      (X) RDP_TFM

Name

Address

Size

Description

RDP_EN_PHY

Physical 0x368[5]

1 bit

When either of these two bits is programmed, RDP is enabled.

When the device is in the development or debugging stage, it is recommended to program the RDP_EN_LOG bit, which can be disabled afterward.

When the device is in the MP stage, it is recommended to program the RDP_EN_PHY bit to enable RDP permanently.

RDP_EN_LOG

Logical 0x3[4]

(for test)

1 bit

S_IPSEC_Key1 (RDP)

Physical 0x200 ~ 0x21F

32 bytes

Used to store RDP key. For example, the RDP key is 11223344556677889900aabbccddeeff11223344556677889900aabbccddeeff, value 0x11

needs to be programmed into eFuse 0x200, 0x22 into 0x201, and so on.

S_IPSEC_Key1_R_Protection_EN

Physical 0x365[3]

1 bit

When programmed, S_IPSEC_Key1 cannot be read out except for IPSEC-S.

S_IPSEC_Key1_W_Forbidden_EN

Physical 0x365[4]

1 bit

When programmed, S_IPSEC_Key1 cannot be modified anymore.

  • When RDP_BASIC is enabled, the bootloader directly jumps to the Non-Secure World after loading the image.

  • While RDP_TFM is enabled, the bootloader jumps to the TF-M first, and then jumps to the Non-Secure World after finishing the secure services initialization in the TF-M.

../../_images/boot_flow_with_tf_m.svg

Boot flow with TF-M

How to Build TF-M

Caution

  • In order to simplify the operation steps, when in the device-development stage, both step 3 and RDP key programming in step 1 can be skipped, which means that the RDP image would be stored in plaintext and the bootloader would not decrypt it. This method should be used only in device-development stage!

  • Carefully use the efuse wraw command, and it cannot be changed once written. Do not power off or reset during writing!

The following steps illustrate how to enable RDP.

  1. Program RDP-related OTP bits after the system boots up.

    1. RDP enable bit

      • When in the device-development stage, it is recommended to program RDP_EN_LOG bit, which can be disabled afterward. Use efuse rmap first to check value in 0x3, then enable RDP_EN_LOG bit (0x3[4]).

        efuse rmap
EFUSE[000]: ff ff 00 00 ff ff ff ff ff ff ff ff ff ff ff ff
EFUSE[010]: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
EFUSE[020]: fe fe fe fe fd fe fc fc fc fb fc ff ff ff ff ff
EFUSE[030]: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff

efuse wmap 0x3 1 10

      • When in the device-MP stage, the RDP_EN_PHY bit should be programmed to enable RDP permanently.

        efuse rraw
RawMap[350]: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
RawMap[360]: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
RawMap[370]: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
RawMap[380]: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff

efuse wraw 0x368 1 DF

    2. RDP key

      When in the device-MP stage, RDP key must be programmed. Using the following command to program RDP key:

      efuse wraw 0x200 0x20 11223344556677889900aabbccddeeff11223344556677889900aabbccddeeff

      RDP key length must be 32 bytes. Key value is defined by users, here we take this for example.

    3. Other security-related bits

      For MP devices, some security-related bits should also be programmed for security reasons, such as key read/write protection bits, S_IPSEC_Key1_R_Protection_EN/S_IPSEC_Key1_W_Forbidden_EN bits, etc.

  2. Enable TF-M in SDK

    1. Switch to the directory: {SDK}\amebadplus_gcc_project

    2. Type command make menuconfig and select CONFIG TrustZone > Enable TrustZone > TrustZone by RDP or TFM in order

    Note

    To perform the regression test or API test on TF-M, enable the TFM Test Suite and select the appropriate test items as needed.

    • Regression test: including TF-M secure regression tests (cmake -DTEST_S=ON) and TFM non-secure regression tests (cmake -DTEST_NS=ON)

    • API test: including tests for STORAGE, CRYPTO, and INITIAL_ATTESTATION

  1. Modify KM4 secure image manifest configuration

    The KM4 secure image manifest configuration file is {SDK}\amebadplus_gcc_project\manifest.json.

    1. Set RDP_EN to 1.

    2. Fill in RDP_IV, which must be 8 bytes, and another 8 bytes is RSIP_IV in app section.

    3. Fill in RDP_KEY, which must be 32 bytes and equal to the key programmed into OTP in Step 1.

    "//": "cert/app share IMG_ID/IMG_VER, rdp img is in app",
"app":
{
   "IMG_ID": "1",
   "IMG_VER_MAJOR": 1,
   "IMG_VER_MINOR": 1,
   "SEC_EPOCH": 1,

   "HASH_ALG": "sha256",

   "RSIP_IV": "213253647586a7b8",
},

"SECURE_BOOT_EN": 0,
"//": "HASH_ALG: sha256/sha384/sha512/hmac256/hmac384/hmac512, hamc need key",
"HMAC_KEY": "9874918301909234686574856692873911223344556677889900aabbccddeeff",

"RSIP_EN": 0,
"//": "RSIP_MODE: 1 is XTS(CTR+ECB), 0 is CTR",
"RSIP_MODE": 1,
"CTR_KEY": "6AA34203018334474B25A0600996CA0968AA6228B886FF234B4EB9628B703C0A",
"ECB_KEY": "E2A0D6500BBF1DD8DC212098C230EB731ECE3A81AA11D0E6E538FA36BBA4FF6E",

"//": "Actual RDP IV is 16Byte which is composed by app RSIP_IV[7:0] + RDP_IV[15:8]",
"RDP_EN": 0,
"RDP_IV": "0123456789abcdef",
"RDP_KEY": "11223344556677889900aabbccddeeff11223344556677889900aabbccddeeff"

  2. Rebuild the project using make command to generate encrypted KM4 secure image automatically as the following table, then download them into Flash.

    Project

    Encrypted image

    Download address

    km4_bootloader

    km4_boot_all.bin

    0x0800_0000

    cert.bin

    km0_km4_app.bin

    0x0801_4000

    km0_application

    km0_km4_app.bin

    0x0801_4000

    km4_application (non-secure)

    km0_km4_app.bin

    0x0801_4000

    km4 secure image

    km0_km4_app.bin

    0x0801_4000

    Note

    The IMG3 will be overflow when building TF-M with the default layout in the current SDK, refer to Section Advanced Usages to modify the layout.

  3. Reset the device.

    When the RDP image is loaded successfully, the following logs will show:

    ROM:[V1.0]
FLASH RATE:1, Pinmux:1
IMG1(OTA1) VALID, ret: 0
IMG1 ENTRY[3000ad39:0]
[KM4] [MODULE_BOOT-LEVEL_INFO]:IMG1 ENTER MSP:[30009fe4]
[KM4] [MODULE_BOOT-LEVEL_INFO]:IMG1 SECURE STATE: 1
[KM4] [MODULE_BOOT-LEVEL_INFO]:Flash ID: c8-65-17
[KM4] [MODULE_BOOT-LEVEL_INFO]:Flash Read 4IO
[KM4] FLASH HandShake[0x1 OK]
[KM4] [MODULE_BOOT-LEVEL_INFO]:KM0 XIP IMG[0c000000:5020]
...
[KM4] [MODULE_BOOT-LEVEL_INFO]:IMG2 BOOT from OTA 1
[KM4] [MODULE_BOOT-LEVEL_INFO]:RDP EN
[KM4] [MODULE_BOOT-LEVEL_INFO]:DEC KM4 IMG3[30075000:5a0]
[KM4] [MODULE_BOOT-LEVEL_INFO]:DEC KM4 NSC[20070000:1320]
[KM4] [MODULE_BOOT-LEVEL_INFO]:IMG3 BOOT from OTA 0
[KM4] [MODULE_BOOT-LEVEL_INFO]:Start NonSecure @ 0xe000115 ...
[KM4] [MODULE_BOOT-LEVEL_INFO]:Start TFM @ 0x30071031 ...
[KM0] [MODULE_BOOT-LEVEL_INFO]:KM0 BOOT UP
[KM4] [MODULE_BOOT-LEVEL_INFO]:VTOR: 20005000, VTOR_NS:0
[KM0] [MODULE_BOOT-LEVEL_INFO]:KM0 APP_START
[KM4] [MODULE_BOOT-LEVEL_INFO]:KM4 APP START
...
[KM4] [MODULE_BOOT-LEVEL_INFO]:KM4 MAIN
[KM4] [MODULE_BOOT-LEVEL_INFO]:KM4 START SCHEDULER

    Note

    The RDP function would not check the authentication of the image. In order to avoid the image being tampering, secure boot function should be used to authenticate it. Refer to Chapter Secure Boot.

How to Adjust TrustZone Secure Area Size

  1. Config TF-M code location:

    1. Switch to the directory: {SDK}\amebadplus_gcc_project

    2. Type command make menuconfig and select CONFIG TrustZone > CONFIG Link Option > IMG3(SecureImage) running on PSRAM or SRAM? in order

    ../../_images/tf_m_code_config.png

  2. Adjust the size of TrustZone Secure Area by modify the flollowing macros (the total size of TZ_NSC_SIZE/TZ_ENTRY_SIZE/TZ_S_SIZE should be a multiple of 4KB).

../../_images/tf_m_amebadplus_layout_ld.png

amebaDplus_layout.ld file

How to Create a New Partition

  1. Add a new partition folder under {SDK}\component\soc\common\trusted-firmware-m\secure_fw\partitions\.

    For example, add a partition_example folder if you want to create a new example parition, refer to Rules for Creating New Files in partition_example Folder.

  2. Add the following codes to {SDK}\component\soc\common\trusted-firmware-m\config\profile\profile_medium.cmake to determine whether to enable the example_partition or not when compiling TF-M (default enable).

    ############################ PARTITION CONFIGURATION  ##########################

set(TFM_PARTITION_CRYPTO                   ON    CACHE BOOL "Enable Crypto partition")
set(TFM_PARTITION_INTERNAL_TRUSTED_STORAGE ON    CACHE BOOL "Enable Internal Trusted Storage partition")
set(TFM_PARTITION_PLATFORM                 ON    CACHE BOOL "Enable the TF-M Platform partition")
set(TFM_PARTITION_EXAMPLE                  OFF    CACHE BOOL "Enable the TF-M Example partition")
set(TFM_PARTITION_PROTECTED_STORAGE        ON    CACHE BOOL "Enable Protected Storage partition")
set(TFM_PARTITION_INITIAL_ATTESTATION      ON    CACHE BOOL "Enable Initial Attestation partition")
set(SYMMETRIC_INITIAL_ATTESTATION          OFF   CACHE BOOL "Use symmetric crypto for inital attestation")
set(TFM_PARTITION_FIRMWARE_UPDATE          OFF   CACHE BOOL "Enable firmware update partition")

  3. Add the following codes to {SDK}\component\soc\common\trusted-firmware-m\secure_fw\partitions\CMakeLists.txt to compile the source files under partition_example folder.

    add_subdirectory(lib/runtime)
add_subdirectory(crypto)
add_subdirectory(initial_attestation)
add_subdirectory(protected_storage)
add_subdirectory(internal_trusted_storage)
add_subdirectory(platform)
add_subdirectory(partition_example)
add_subdirectory(firmware_update)
add_subdirectory(ns_agent_tz)
add_subdirectory(ns_agent_mailbox)
if (CONFIG_TFM_SPM_BACKEND_IPC)

  4. Add the following codes to {SDK}\component\soc\common\trusted-firmware-m\secure_fw\CMakeLists.txt to add the compile path.

    target_include_directories(tfm_config
   INTERFACE
      ${CMAKE_CURRENT_SOURCE_DIR}/include
      ${CMAKE_CURRENT_SOURCE_DIR}/partitions/crypto
      ${CMAKE_CURRENT_SOURCE_DIR}/partitions/firmware_update
      ${CMAKE_CURRENT_SOURCE_DIR}/partitions/initial_attestation
      ${CMAKE_CURRENT_SOURCE_DIR}/partitions/internal_trusted_storage
      ${CMAKE_CURRENT_SOURCE_DIR}/partitions/platform
      ${CMAKE_CURRENT_SOURCE_DIR}/partitions/partition_example
      ${CMAKE_CURRENT_SOURCE_DIR}/partitions/protected_storage
      ${CMAKE_CURRENT_SOURCE_DIR}/spm/include
      ${CMAKE_BINARY_DIR}/generated/interface/include
)

  5. Add the following codes to {SDK}/component/soc/common/trusted-firmware-m/tools/tfm_manifest_list.yaml

    • Specify partition ID (pid), where pid needs to be unique

    • tfm_partition_example.yaml: used to automaticlly generate the load_info_tfm_partition_example.c file, which is located at {SDK}\amebadplus_gcc_project\project_km4\asdk\build_tfm\generated\secure_fw\partitions\partition_example\auto_generated .

    {
   "description": "TFM partition example Partition",
   "manifest": "../secure_fw/partitions/partition_example/tfm_partition_example.yaml",
   "output path": "secure_fw/partitions/ partition_example",
   "conditional": "TFM_PARTITION_EXAMPLE",
   "version_major": 0,
   "version_minor": 1,
   "pid": 300,
   "linker_pattern": {
   "library_list": [
      "*tfm_*partition_example.*"
      ]
   }
}

Rules for Creating New Files in partition_example Folder

The partition_example folder under the path {SDK}\component\soc\common\trusted-firmware-m\secure_fw\partitions\partition_ example contains at least the following files:

  • CMakeLists.txt

  • tfm_partition_example.yaml

  • partition_example.c

  • partition_example.h

CMakeLists.txt

The CMakeLists.txt file specify how to compile, where,

target_sources:

the compiled source files

target_include_directories:

the path to the compiled source files

if (NOT TFM_PARTITION_EXAMPLE)
   return()
endif()

cmake_minimum_required(VERSION 3.15)
cmake_policy(SET CMP0079 NEW)

add_library(tfm_psa_rot_partition_example STATIC)

target_sources(tfm_psa_rot_partition_example PRIVATE
   partition_example.c
)

# The generated sources
target_sources(tfm_psa_rot_partition_example
   PRIVATE
      ${CMAKE_BINARY_DIR}/generated/secure_fw/partitions/partition_example/auto_generated/intermedia_tfm_partition_example.c
)
target_sources(tfm_partitions
   INTERFACE
      ${CMAKE_BINARY_DIR}/generated/secure_fw/partitions/partition_example/auto_generated/load_info_tfm_partition_example.c
)

# Set include directory
target_include_directories(tfm_psa_rot_partition_example
   PRIVATE
      $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
      ${CMAKE_BINARY_DIR}/generated/secure_fw/partitions/partition_example
)
target_include_directories(tfm_partitions
   INTERFACE
      ${CMAKE_BINARY_DIR}/generated/secure_fw/partitions/partition_example
)

target_link_libraries(tfm_psa_rot_partition_example
   PRIVATE
      platform_s
      tfm_config
      tfm_sprt
)

tfm_partition_example.yaml

The tfm_partition_example.yaml file specify how to generate the file load_info_tfm_partition_example.c

sid:

needs to be unique

stateless_handle:

must be less than 32 and needs to be unique

TFM_PARTITION_EXAMPLE_SERVICE determines the name of .sfn, that is the default value of .sfn in the automaticlly generated file load_info_tfm_partition_example.c

{
   "psa_framework_version": 1.1,
   "name": "TFM_SP_PARTITION_EXAMPLE",
   "type": "PSA-ROT",
   "priority": "NORMAL",
   "model": "SFN",
   "entry_init": "tfm_example_init",
   "stack_size": "PLATFORM_SP_STACK_SIZE",
   "services": [
      {
         "name": "TFM_PARTITION_EXAMPLE_SERVICE",
         "sid": "0x00000090",
         "non_secure_clients": true,
         "connection_based": false,
         "stateless_handle": 16,
         "minor_version": 1,
         "minor_policy": "STRICT"
      },
   ],
}

.services = {
   {
      .name_strid = STRING_PTR_TO_STRID("TFM_PARTITION_EXAMPLE_SERVICE"),
      .sfn        = ENTRY_TO_POSITION(tfm_partition_example_service_sfn),
      .signal     = 1,

      .sid        = 0x00000090,
      .flags      = 0
                  | SERVICE_FLAG_NS_ACCESSIBLE
                  | SERVICE_FLAG_STATELESS | 0xf
                  | SERVICE_VERSION_POLICY_STRICT,
      .version    = 1,
   }
},

partition_example.c

The partition_example.c file needs to implement the entry function and provide functions for stateless SFN services.

  • tfm_example_init: corresponds to entry_init in tfm_partition_example.yaml

  • tfm_partition_example_service_sfn: corresponds to name of services in tfm_partition_example.yaml

psa_status_t tfm_partition_example_service_sfn(const psa_msg_t *msg)
{
   switch (msg->type) {
   case TFM_EXAMPLE_API_ID_IOCTL:
      return example_ioctl_psa_api(msg);
   default:
      return PSA_ERROR_NOT_SUPPORTED;
   }

   return PSA_ERROR_GENERIC_ERROR;
}

psa_status_t tfm_example_init(void)
{
   /* Initialize the non-volatile counters */

   return PSA_SUCCESS;
}

Providing TF-M APIs to Other Partitions

Add the following files under the folder {SDK}\component\soc\common\trusted-firmware-m\interface\:

  • {SDK}\component\soc\common\trusted-firmware-m\interface\src\tfm_example_api.c

  • {SDK}\component\soc\common\trusted-firmware-m\interface\include\tfm_example_api.h

The handle parameter used by function psa_call in tfm_example_api.c is automatically generated by TF-M. That is, in the file \interface\include\psa_manifest\sid.h, the type parameter corresponds to the type of msg->type in the file partition_example.c.

  • TF-M APIs used by Non-Secure World: Add the following codes to {SDK}\component\soc\common\trusted-firmware-m\cmake\ install.cmake, and compile the project to provide the APIs used by Non-Secure World.

####################### export headers #########################################

if(TFM_PARTITION_EXAMPLE)
      install(FILES       ${INTERFACE_INC_DIR}/tfm_example_api.h
               DESTINATION ${INSTALL_INTERFACE_INC_DIR})
endif()

if(TFM_PARTITION_PLATFORM)
   install(FILES       ${INTERFACE_INC_DIR}/tfm_platform_api.h
            DESTINATION ${INSTALL_INTERFACE_INC_DIR})
endif()

####################### export sources #########################################

if(TFM_PARTITION_EXAMPLE)
   install(FILES       ${INTERFACE_SRC_DIR}/tfm_example_api.c
            DESTINATION ${INSTALL_INTERFACE_SRC_DIR})
endif()

if(TFM_PARTITION_PLATFORM)
   install(FILES       ${INTERFACE_SRC_DIR}/tfm_platform_api.c
            DESTINATION ${INSTALL_INTERFACE_SRC_DIR})
endif()

  • TF-M APIs used by Secure World: Add the following codes to {SDK}\component\soc\common\trusted-firmware-m\interface\ CMakeLists.txt, after that you can use the example APIs in Secure World.

###################### PSA api (S lib) #########################################

target_sources(tfm_sprt
   PRIVATE
      $<$<BOOL:${TFM_PARTITION_INITIAL_ATTESTATION}>:${CMAKE_CURRENT_SOURCE_DIR}/src/tfm_attest_api.c>
      $<$<BOOL:${TFM_PARTITION_CRYPTO}>:${CMAKE_CURRENT_SOURCE_DIR}/src/tfm_crypto_api.c>
      $<$<BOOL:${TFM_PARTITION_FIRMWARE_UPDATE}>:${CMAKE_CURRENT_SOURCE_DIR}/src/tfm_fwu_api.c>
      $<$<BOOL:${TFM_PARTITION_INTERNAL_TRUSTED_STORAGE}>:${CMAKE_CURRENT_SOURCE_DIR}/src/tfm_its_api.c>
      $<$<BOOL:${TFM_PARTITION_EXAMPLE}>:${CMAKE_CURRENT_SOURCE_DIR}/src/tfm_example_api.c>
      $<$<BOOL:${TFM_PARTITION_PLATFORM}>:${CMAKE_CURRENT_SOURCE_DIR}/src/tfm_platform_api.c>
      $<$<BOOL:${TFM_PARTITION_PROTECTED_STORAGE}>:${CMAKE_CURRENT_SOURCE_DIR}/src/tfm_ps_api.c>
      ${CMAKE_CURRENT_SOURCE_DIR}/src/tfm_psa_call_pack.c
)

Flash Layout of TF-M

Item

Physical address

Size

Description

Mandatory?

PS_AREA

0x081F_4000

20KB

Storing data for the partition service of Protected Storage

√

ITS_AREA

0x081F_9000

16KB

Storing data for the partition service Internal Trusted Storage

√

OTP_NV_COUNTERS

0x081F_D000

8KB

Storing data for the partition service of platform, in which 4K is for main data and the other 4K is for backup data

Note

This partition stores a 32-byte Integration Attestation Key (IAK). Therefore, the SDK uses the GCM algorithm to ensure integrity and confidentiality,

employing a derived key as the IV value and the anti-rollback version number as the Additional Authenticated Data (AAD), to prevent new data in this

partition from being replaced by old data. (when the version is upgraded, remerber to update the data in this partition first before updating the anit-rollback version number)

√

PSA API Test

0x081F_F000

4KB

Storing intermediate results during the PSA API Test process

X

  • If users need to modify the size of the corresponding Flash region, modify the file {SDK}\component\soc\common\trusted-firmware-m\platform\ext\target\realtek\amebadplus\partition\flash_layout.h

#define FLASH_PS_AREA_OFFSET           (0x001F4000)
#define FLASH_PS_AREA_SIZE             (0x5000)   /* 20KB */
#define FLASH_ITS_AREA_OFFSET          (FLASH_PS_AREA_OFFSET + \FLASH_PS_AREA_SIZE)
#define FLASH_ITS_AREA_SIZE             (0x4000)   /* 16KB */
#define FLASH_OTP_NV_COUNTERS_AREA_OFFSET (FLASH_ITS_AREA_OFFSET + \FLASH_ITS_AREA_SIZE)
// 0x1FD000
#define FLASH_OTP_NV_COUNTERS_AREA_SIZE   (FLASH_AREA_IMAGE_SECTOR_SIZE * 2) /* 8KB */
#define FLASH_OTP_NV_COUNTERS_SECTOR_SIZE FLASH_AREA_IMAGE_SECTOR_SIZE

  • If users need to modify the location of the PSA API Test, modify the file {SDK}\component\soc\common\trusted-firmware-m\lib\ext\psa_arch_tests-src\api-tests\platform\targets\tgt_dev_apis_tfm_amebadplus\target.cfg

// Range of 1KB Non-volatile memory to preserve data over reset. Ex, NVRAM and FLASH
nvmem.num =1;
nvmem.0.start = 0x001FF000;
/*Shall reserve 4KB for sector erase, offset based on flash die */
nvmem.0.end = 0x001FF3FF;
nvmem.0.permission = TYPE_READ_WRITE;