Migrating to a secure environment

The following section covers the steps required to migrate a non-secure example to one that leverages security through Arm TrustZone on CC13x4 or CC26x4.

Two approaches are presented. The first method consists in leveraging a TI-provided project with Trusted Firmware-M (TF-M) implemented. The second method leads you to modify any CC13x4 or CC26x4 project to enable TF-M.

The first approach (project migration) is recommended when a TF-M version of the example used as base for your project is available in the SDK. For example, if your project is based on the empty example, you migrate your code into the tfm_empty example.

The second approach (consisting in enabling TF-M on an existing project) is applicable on all the CC13x4 or CC26x4 projects.

Project migration

  1. Identify the differences between your project and the unmodified example project in the SDK. These differences include the created files, the altered project configurations, the modified and the changes made in the linker command file. The SysConfig configurations are usually contained in .syscfg files. The linker command file is named differently according to the toolchain used (.cmd for TIClang, .ipcf for IAR or .``lds`` for GCC).

  2. Import the unmodified TF-M version of the example in your development environment (i.e. CCS or IAR).

  3. Implement the differences identified at step #1. Created files can directly be copy-pasted into the newly created project. However, it is recommended to apply the changes in the project configuration, SysConfig and the linker command file line by line to avoid unintentional alteration of the project.

Enable Trusted Firmware-M on an existing project

Several modifications are required in a TF-M disabled project in order to enable TF-M. These modifications should ensure the proper secure software components (secure image, veneers, drivers) are selected and linked. From the developer’s point of view, modifications are required in SysConfig, the Project configuration and in the linker command file.

SysConfig

When configured to do so, SysConfig ensures

  • The secured-implementation of the crypto drivers is used to build the application

  • The linker is configured to use the veneers library

Configuring SysConfig to do so takes to enable TrustZone:

  1. Open the SysConfig file (.syscfg)

  2. Under TI UTILS, enable TrustZone

../_images/sysconfig-enable-TrustZone.png

Figure 175. Enable “TrustZone” using SysConfig

One can review the files generated by SysConfig (especially ti_drivers_config.c and ti_utils_build_linker.cmd.genlibs) and notice the secure driver, secure driver library and veneers are used by the project when TrustZone is enabled.

Project configuration

The project configuration ensures the toolchain (compiler and linker) have the right options, especially when it comes to the predefined symbols and included libraries. The project configuration can be modified by accessing the project properties from your IDE.

  1. Add the following predefined symbols

    • TFM_ENABLED=1

    • MBEDTLS_CONFIG_FILE="<configs/config-tidrivers.h>"

    • -DMBEDTLS_PSA_CRYPTO_CONFIG_FILE="<configs/config-psa-crypto-cc13x4.h>

  2. Add the following include path to the compiler

    • ${COM_TI_SIMPLELINK_CC13XX_CC26XX_SDK_INSTALL_DIR}/source/third_party/tfm/interface/include

    • ${COM_TI_SIMPLELINK_CC13XX_CC26XX_SDK_INSTALL_DIR}/source/third_party/tfm/config

    • ${COM_TI_SIMPLELINK_CC13XX_CC26XX_SDK_INSTALL_DIR}/source/third_party/tfm/secure_fw/include

    • ${COM_TI_SIMPLELINK_CC13XX_CC26XX_SDK_INSTALL_DIR}/tfm_s/build/cc26x4/production_full/Release/export/tfm/inc

    • ${COM_TI_SIMPLELINK_CC13XX_CC26XX_SDK_INSTALL_DIR}/source/third_party/mbedtls/include

    • ${COM_TI_SIMPLELINK_CC13XX_CC26XX_SDK_INSTALL_DIR}/source/third_party/mbedtls/ti

  3. Add the following library include to the linker

    • ${COM_TI_SIMPLELINK_CC13XX_CC26XX_SDK_INSTALL_DIR}/tfm_s

Linker commmand file

The linker command file should ensure

  • The secure image is linked at address 0x00000000. The rest of the flash is for non-secure code.

  • The starting address of application matches the base address of the non-secure application base address defined in the in the TF-M memory layouts.

  • A part of the RAM is reserved for secure operations (the rest of the RAM is for non-secure operations).

To do so, in the linker command file (.cmd for TIClang, .ipcf for IAR or .lds for GCC compiler), modify the following elements:

  1. Set the Flash origin and Flash size / Flash end for the application considering the Flash used by the secure image and secure boot.

    • The starting address of the non-secure application is given by the TF-M memory layouts. The starting address of the non-secure application is 0x00038100 by default.

    • The Flash length should be set to 0xC6F00 and/or the Flash end should be set to 0x000FEFFF. This is to ensure 0x1000 bytes of Flash is left for the Secure Boot.

    For TIClang

    Assuming you are using TIClang toolchain, the following symbols should be changed in the linker command file (.cmd).

    /* #define FLASH_BASE              0x0
   #define FLASH_SIZE              0x100000
   #define RAM_BASE                0x20000000
   #define RAM_SIZE                0x40000 */
#define FLASH_S_BASE            0x0
#define FLASH_SCSIZE            0x38000
#define FLASH_BASE              0x00038100
#define FLASH_SIZE              0xC6F00
#define RAM_BASE                0x2000C000
#define RAM_SIZE                0x30000
    For IAR

    Assuming you are using IAR toolchain, the following symbols should be changed in the linker command file (.ipcf).

    /* define symbol ROM_start__ = 0x00000000;
   define symbol ROM_end__   = 0x000FFFFF;
   define symbol RAM_start__ = 0x20000000;
   define symbol __intvec_start__ = 0x00000000; */
define symbol ROM_start__ = 0x00038100;
define symbol ROM_end__   = 0x000FEFFF;
define symbol RAM_start__ = 0x2000C000;
define symbol __intvec_start__ = 0x00038100;
    For GCC

    Assuming you are using GCC toolchain, the following symbols should be changed in the linker command file (.lds).

    /* FLASH (RX)      : ORIGIN = 0x00000000, LENGTH = 0x000FFFFF */
FLASH (RX)      : ORIGIN = 0x00038100, LENGTH = 0x000C6F00

/* SRAM (RWX)      : ORIGIN = 0x20000000, LENGTH = 0x00040000 */
SEC_SRAM (RWX)  : ORIGIN = 0x20000000, LENGTH = 0x0000C000
SRAM (RWX)      : ORIGIN = 0x2000C000, LENGTH = 0x00034000

/* .resetVecs (0x0) : AT (0x0) { */
.resetVecs (0x00038100) : AT (0x00038100) {

/* UDMACC26XX_CONFIG_BASE = 0x20000400; */
UDMACC26XX_CONFIG_BASE = 0x2000C400;

  2. Ensures the interrupt vectors is linked at 256-byte boundry closest to NS flash base (i.e. at 0x00038100)

  3. Set the RAM origin and RAM size for the application considering the RAM used by the secure image.

    • The RAM base (RAM base) should be set to 0x2000C000 as the RAM starts at 0x20000000 and the secure image uses by default 0x0000C000 bytes of RAM.

    • The remaining RAM size (0x34000) is usable by the application (i.e. the RAM end can be left as it, 0x2003FFFF).

  4. Review one more time the linker command file to make sure nothing is linked at the addresses used by the secure image

Migrating from TFM v1.1 to v1.8

This section is relevant to you if you developed your TFM based application based on SimpleLink F2 SDK 7_10_02 or before. Simplelink F2 SDK 7_40_00 ships with support for TFM v1.8.

These are the steps needed to migrate from TFM v1.1 based application to TFM v1.8.

  1. The secure image is now found in this path: ${COM_TI_SIMPLELINK_CC13XX_CC26XX_SDK_INSTALL_DIR}/tfm_s/build/cc26x4/production_full/Release/outputs/ Ensure you load the secure image from this path.

  2. The KeyStore is now based on mbedTLS v3.4 as opposed to mbedcrypto v3.1. To enable this, update the compiler include paths to these. ${COM_TI_SIMPLELINK_CC13XX_CC26XX_SDK_INSTALL_DIR}/source/third_party/mbedtls/include ${COM_TI_SIMPLELINK_CC13XX_CC26XX_SDK_INSTALL_DIR}/source/third_party/mbedtls/ti

  3. In addition to the keystore paths listed in the previous step. These updates to the paths must be made. Add these new compiler include paths. ${COM_TI_SIMPLELINK_CC13XX_CC26XX_SDK_INSTALL_DIR}/source/third_party/tfm/config ${COM_TI_SIMPLELINK_CC13XX_CC26XX_SDK_INSTALL_DIR}/source/third_party/tfm/secure_fw/include ${COM_TI_SIMPLELINK_CC13XX_CC26XX_SDK_INSTALL_DIR}/tfm_s/build/cc26x4/production_full/Release/export/tfm/inc Remove the following compiler include path. ${COM_TI_SIMPLELINK_CC13XX_CC26XX_SDK_INSTALL_DIR}/fm_s/build/cc26x4/production_full/interface/include

  4. In order to support PSA APIs, a new mbedtls configuration file was added. Add the following predefined symbol to your project. -DMBEDTLS_PSA_CRYPTO_CONFIG_FILE="<configs/config-psa-crypto-cc13x4.h>