How to configure TF-A FIP

1. Article purpose

This section details the TF-A FIP (Trusted Firmware-A Firmware Image Package) binary management for the STM32 MPU boot chain. It explains how to use it in STM32 MPU context and describes the build/update process that is required to deploy it on your target.

2. Overview

As explained in the TF-A Overview, this binary is used by the TF-A BL2 to load and authenticate the next stage binaries. It can contains:

• Boot stage binaries
• Configuration file (Device tree)
• Certificate (X509.3 based) for authentication

3. Package structure

The FIP binary has a specific layout that is parsed by the BL2 during the load processing.

The FIP binary starts with a table of contents (ToC) that is recognized by the BL2. Each entry is identified by its UUID, offset in the package, size and flags. The end-of-ToC marker is used to define the start of the binary section. All the corresponding binaries are appended according to the offset defined in the ToC entry.

This structure is automatically built using the fiptool command. It appends all the binaries and creates the associated ToC.

4. Fiptool command

fiptool is a host tool that must be used to generate the proper FIP binary.

By default, the OpenSTLinux SDK provides the fiptool. You do not need to regenerate it to update (or create) a FIP binary.

fiptool provides a set of useful commands to manage the FIP binary. All options can be listed using the following command:

   fiptool help

• info: The fiptool info provides information on a generated FIP binary

   fiptool info fip.bin 
    Secure Payload BL32 (Trusted OS): offset=0x100, size=0x1347C, cmdline="--tos-fw"
    Non-Trusted Firmware BL33: offset=0x1357C, size=0xEDDE2, cmdline="--nt-fw"
    FW_CONFIG: offset=0x10135E, size=0x226, cmdline="--fw-config"
    HW_CONFIG: offset=0x101584, size=0x1E412, cmdline="--hw-config"
    TOS_FW_CONFIG: offset=0x11F996, size=0x45AC, cmdline="--tos-fw-config"

• update: Update allows one or more images to be replaced in an existing FIP binary

   fiptool update --tos-fw bl32.bin fip.bin

The optional argument below can be used to avoid erasing the initial FIP binary:

   fiptool update --tos-fw bl32.bin --out new_fip.bin fip.bin

• unpack: Extracts all binaries from a FIP binary

   fiptool unpack fip.bin

• remove: Removes a binary from FIP binary

   fiptool remove --tos-fw bl32.bin fip.bin

4.1. Tool generation

The tool is provided within the TF-A sources tools/fiptool . It can be built for Linux^® or Windows^® platforms. A dedicated rule is available to generate the tool:

   make fiptool

It generates the tool under the tools/fiptool/fiptool source path.

4.2. TF-A build

When the TF-A component build process is complete, the FIP binary can be automatically generated. In this case the fiptool is automatically generated too and the FIP binaries are part of the output folder.

5. Cert_create command

When the TRUSTED_BOARD_BOOT feature is enabled, the FIP must contain the binaries and their associated certificate as described in the TBBR Chain of Trust (CoT). These certificates can be created using the cert_create command that is provided in the TF-A sources tools/cert_create .

By default, the OpenSTLinux SDK provides the cert_create. You do not need to regenerate it to regenerate certificates.

The cert_create tool is able to generate the self-signed certificate used to complete the trusted boot chain. It requires a large set of arguments linked to the CoT.

   cert_create --help
  

cert_create creates the certificate if it does not exist yet or uses the available one to generate the CoT. The certificate content must be regenerated if the associated binary has been updated.

5.1. TF-A build

TF-A generic Makefile can help to automatically build the certificate using some dedicated flags that can be enabled to generate the certificate and append them into the FIP:

• GENERATE_COT=1 : Enable the cert_create tool
• ROT_KEY : Specify the root private key to be used

6. FIP binary creation

Below the list of the different ways by which the FIP binary can be generated:

• Using the dedicated fiptool command
• Using the TF-A official Makefile

The FIP binary content may depend on the TRUSTED_BOARD_BOOT feature enable. In this case, a prior certificate generation is mandatory to include them into the FIP binary.

6.1. STM32MP1

The OpenSTLinux boot flow requires the following stages to be loaded:

• BL32: Secure OS and Secure Monitor (it can be eiher SP-MIN or OP-TEE OS)
• BL33: The non-secure firmware (recommended U-Boot)
• HW_config: The OpenSTLinux uses the hw_config as the non-secure device tree
• FW_config: Firmware configuration file listing the previous images and defining their size and the load address

To create the FIP binary, all the following binaries must be built:

• Secure OS or Secure Monitor
  • SP-MIN in case of trusted boot chain*.
  • OP-TEE in case of OP-TEE Secure OS usage.
• U-Boot.
• Firmware configuration file related to the loaded binaries*.

Information

* The build can be made in a single step using the TF-A Makefile

When the TRUSTED_BOARD_BOOT feature is enabled in BL2, the associated certificate must be generated as per the TBBR CoT requirements.

The fiptool is used to create or update a FIP file.

The TF-A Makefile with fip target and some variables uses fiptool to automatically create the new FIP after the TF-A compilation.

With U-Boot as a non-secure firmware, the paths for the files used in next chapters are the following:

Description	Makefile variable	fiptool option	file path for OP-TEE	file path for SP_MIN
Secure OS (OP-TEE) or Secure Monitor (SPMIN)	BL32	--tos-fw	<optee_path>/tee-header_v2.bin	<tfa_path>/bl32.bin
OP-TEE pager	BL32_EXTRA1	--tos-fw-extra1	<optee_path>/tee-pager_v2.bin	-
OPTEE pageable	BL32_EXTRA2	--tos-fw-extra2	<optee_path>/tee-pageable_v2.bin	-
Firmware configuration file	FW_CONFIG	--fw-config	<tfa_path>/fw-config.dtb
U-Boot device tree	BL33_CFG	--hw-config	<u-boot_path>/u-boot.dtb
U-Boot	BL33	--nt-fw	<u-boot_path>/u-boot-nodtb.bin

In the next chapter, all the files are assumed present in the current directory.

6.1.1. Trusted boot chain

6.1.1.1. Non-secure boot

The following command generates the FIP package that is required by the BL2 to boot. You can create the FIP binary by using the fiptool command:

   fiptool create --fw-config fw-config.dtb \
          --hw-config u-boot.dtb \
          --tos-fw-config bl32.dtb \
          --tos-fw bl32.bin \ 
          --nt-fw u-boot-nodtb.bin \
          fip.bin

You can also use the TF-A Makefile:

   make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 \
          BL33=<u-boot_path>/u-boot-nodtb.bin \
          BL33_CFG=<u-boot_path>/u-boot.dtb \
          BL32=<tfa_path>/bl32.bin \
          FW_CONFIG=<tfa_path>/fw-config.dtb \
          DTB_FILE_NAME=<fdt file name>.dtb \
          fip

Adding the AARCH32_SP=sp_min automatically manages the BL32 and FW_CONFIG path:

   make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 \
          AARCH32_SP=sp_min \
          BL33=<u-boot_path>/u-boot-nodtb.bin \
          BL33_CFG=<u-boot_path>/u-boot.dtb \
          DTB_FILE_NAME=<fdt file name>.dtb \
          fip

6.1.1.2. Secure boot

You can create the certificate and FIP binary by using the cert_create and fiptool command:

   cert_create \
          -n --tfw-nvctr 0 --ntfw-nvctr 0 \
          --key-alg ecdsa --hash-alg sha256 \
          --rot-key privateKey.pem \
          --tb-fw bl2.bin \
          --tb-fw-cert tb_fw.crt \
          --tos-fw-config bl32.dtb \
          --fw-config fw-config.dtb \
          --hw-config u-boot.dtb \
          --trusted-key-cert trusted_key.crt \
          --tos-fw-key-cert tos_fw_key.crt \
          --tos-fw-cert tos_fw_content.crt \
          --tos-fw bl32.bin \
          --nt-fw-key-cert nt_fw_key.crt \
          --nt-fw-cert nt_fw_content.crt \
          --nt-fw u-boot-nodtb.bin

You can now generate the FIP trusted package:

   fiptool create \
          --tb-fw-cert tb_fw.crt \
          --fw-config fw-config.dtb \
          --hw-config u-boot.dtb \
          --trusted-key-cert trusted_key.crt \
          --tos-fw-key-cert tos_fw_key.crt \
          --tos-fw-config bl32.dtb \
          --tos-fw-cert tos_fw_content.crt \
          --tos-fw bl32.bin \
          --nt-fw-cert nt_fw_content.crt \
          --nt-fw-key-cert nt_fw_key.crt \
          --nt-fw u-boot-nodtb.bin \
          fip-trusted.bin

You can also use the TF-A Makefile:

   make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 \
          BL33=<u-boot_path>/u-boot-nodtb.bin \
          BL33_CFG=<u-boot_path>/u-boot.dtb \
          BL32=<tfa_path>/bl32.bin \
          FW_CONFIG=<tfa_path>/fw-config.dtb \
          DTB_FILE_NAME=<fdt file name>.dtb \
          TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 ROT_KEY=<path_to_private_key>.pem \
          fip

Adding the AARCH32_SP=sp_min automatically manages the BL32 and FW_CONFIG path:

   make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 \
          AARCH32_SP=sp_min \
          BL33=<u-boot_path>/u-boot-nodtb.bin \
          BL33_CFG=<u-boot_path>/u-boot.dtb \
          DTB_FILE_NAME=<fdt file name>.dtb \
          TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 ROT_KEY=<path_to_private_key>.pem \
          fip

6.1.2. OP-TEE boot chain

6.1.2.1. Non-secure boot

You can create the FIP binary by using the fiptool command:

   fiptool create --fw-config fw-config.dtb \
               --hw-config u-boot.dtb \
               --nt-fw u-boot-nodtb.bin \
               --tos-fw tee-header_v2.bin \
               --tos-fw-extra1 tee-pager_v2.bin \
               --tos-fw-extra2 tee-pageable_v2.bin \
               fip-optee.bin

You can also use the TF-A Makefile:

   make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 \
           BL33=<u-boot_path>/u-boot-nodtb.bin \
           BL33_CFG=<u-boot_path>/u-boot.dtb \
           BL32=<optee_path>/tee-header_v2.bin \
           BL32_EXTRA1=<optee_path>/tee-pager_v2.bin \
           BL32_EXTRA2=<optee_path>/tee-pageable_v2.bin \
           DTB_FILE_NAME=<fdt file name>.dtb \
          FW_CONFIG=<tfa_path>/fw-config.dtb fip

Adding the AARCH32_SP=optee automatically manages the FW_CONFIG path:

   make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 AARCH32_SP=optee \
       BL33=<u-boot_path>/u-boot-nodtb.bin \
       BL33_CFG=<u-boot_path>/u-boot.dtb \
       BL32=<optee_path>/tee-header_v2.bin \
       BL32_EXTRA1=<optee_path>/tee-pager_v2.bin \
       DTB_FILE_NAME=<fdt file name>.dtb \
       BL32_EXTRA2=<optee_path>/tee-pageable_v2.bin fip

6.1.2.2. Secure boot

You can create the certificate and FIP binary by using the cert_create and fiptool command:

   cert_create \
          -n --tfw-nvctr 0 --ntfw-nvctr 0 \
          --key-alg ecdsa --hash-alg sha256 \
          --rot-key privateKey.pem \
          --tb-fw bl2.bin \
          --tb-fw-cert tb_fw.crt \
          --tos-fw tee-header_v2.bin \
          --tos-fw-extra1 tee-pager_v2.bin \
          --tos-fw-extra2 tee-pageable_v2.bin \
          --fw-config fw-config.dtb \
          --hw-config u-boot.dtb \
          --trusted-key-cert trusted_key.crt \
          --tos-fw-key-cert tos_fw_key.crt \
          --tos-fw-cert tos_fw_content.crt \
          --nt-fw-key-cert nt_fw_key.crt \
          --nt-fw-cert nt_fw_content.crt \
          --nt-fw u-boot-nodtb.bin

You can now generate the FIP trusted package:

   fiptool create \
          --tb-fw-cert tb_fw.crt \
          --fw-config fw-config.dtb \
          --hw-config u-boot.dtb \
          --trusted-key-cert trusted_key.crt \
          --tos-fw-key-cert tos_fw_key.crt \
          --tos-fw-cert tos_fw_content.crt \
          --tos-fw tee-header_v2.bin \
          --tos-fw-extra1 tee-pager_v2.bin \
          --tos-fw-extra2 tee-pageable_v2.bin \
          --nt-fw-cert nt_fw_content.crt \
          --nt-fw-key-cert nt_fw_key.crt \
          --nt-fw u-boot-nodtb.bin \
          fip-optee-trusted.bin

You can also use the TF-A Makefile:

   make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 \
           BL33=<u-boot_path>/u-boot-nodtb.bin \
           BL33_CFG=<u-boot_path>/u-boot.dtb \
           BL32=<optee_path>/tee-header_v2.bin \
           BL32_EXTRA1=<optee_path>/tee-pager_v2.bin \
           BL32_EXTRA2=<optee_path>/tee-pageable_v2.bin \
           FW_CONFIG=<tfa_path>/fw-config.dtb \
           DTB_FILE_NAME=<fdt file name>.dtb \
           TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 ROT_KEY=<path_to_private_key>.pem fip

Adding the AARCH32_SP=optee automatically manages the FW_CONFIG path:

   make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 AARCH32_SP=optee \
       BL33=<u-boot_path>/u-boot-nodtb.bin \
       BL33_CFG=<u-boot_path>/u-boot.dtb \
       BL32=<optee_path>/tee-header_v2.bin \
       BL32_EXTRA1=<optee_path>/tee-pager_v2.bin \
       BL32_EXTRA2=<optee_path>/tee-pageable_v2.bin \
       DTB_FILE_NAME=<fdt file name>.dtb \
       TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 ROT_KEY=<path_to_private_key>.pem fip

6.2. Updating the FIP binary

When modifying a component included in the FIP binary, it is possible to update only part of the binary. To do this, use the fiptool update command:

Warning

When updating a binary in the FIP when the TRUSTED_BOARD_BOOT is enabled, the content certificate must be updated too. In this case the cert_create must be called with the previous generated certificate to avoid regenerating the whole CoT.

6.2.1. Updating TF-A SP-MIN

When a modification is made in the SP-MIN binary (or its device tree), the SP-MIN must be updated in the FIP binary:

• Full SP-MIN update

   fiptool update --tos-fw <tfa_path>/bl32.bin --tos-fw-config <tfa_path>/bl32.dtb fip.bin

• SP-MIN core binary

   fiptool update --tos-fw <tfa_path>/bl32.bin fip.bin

• SP-MIN device tree update

   fiptool update --tos-fw-config <tfa_path>/bl32.dtb fip.bin

6.2.2. Updating U-Boot

When a new U-Boot is generated, the FIP must be updated using the following commands:

• Full U-Boot update

   fiptool update --nt-fw <u-boot_path>/u-boot-nodtb.bin --hw-config u-boot.dtb fip.bin

• U-Boot core binary

   fiptool update --nt-fw <u-boot_path>/u-boot-nodtb.bin fip.bin

• U-Boot device tree update

   fiptool update --hw-config u-boot.dtb fip.bin

6.2.3. Updating OP-TEE

The OP-TEE OS rebuild is required to update the FIP package.

Warning

It is recommended to update all OP-TEE OS images rather than just update the required one.

   fiptool update --tos-fw <optee_path>/tee-header_v2.bin \
          --tos-fw-extra1 <optee_path>/tee-pager_v2.bin \
          --tos-fw-extra2 <optee_path>/tee-pageable_v2.bin \
          fip-optee.bin

The OP-TEE OS build process generates the static binary location.
In case of mapping modification, the firmware configuration file must be adapted accordingly

6.2.4. Updating FW_CONFIG

In case of change in the firmware configuration file, you must also update the FIP binary:

   fiptool update --fw-config fw-config.dtb fip.bin

7. Updating the software on board

7.1. Partitioning of binaries

The FIP build provides a binary named fip.bin (or fip-<board-name>-<bootchain>.bin from official release) that MUST be copied to a dedicated partition named "fip".

7.2. Updating via SDCard

If you use an SDCard, simply update the FIP binary by using the dd command on your host.
Plug your SDCard into the computer and copy the binary to the dedicated partition; on an SDCard/USB disk the "fip" partition is partition 3:

 - SDCard: /dev/mmcblkXp3 (where X is the instance number)
 - SDCardvia USB reader: /dev/sdX3 (where X is the instance number)

• Under Linux^®

   dd if=<fip binary file> of=/dev/<device partition> bs=1M conv=fdatasync

Information

To find the partition associated to a specific label, just plug the SDCard/USB disk into your PC and call the following command: ls -l /dev/disk/by-partlabel/ total 0 lrwxrwxrwx 1 root root 10 Jan 17 17:38 bootfs -> ../../mmcblk0p4 lrwxrwxrwx 1 root root 10 Jan 17 17:38 fsbl1 -> ../../mmcblk0p1 FSBL1 (TF-A) lrwxrwxrwx 1 root root 10 Jan 17 17:38 fsbl2 -> ../../mmcblk0p2 FSBL2 (TF-A backup / same content as FSBL) lrwxrwxrwx 1 root root 10 Jan 17 17:38 rootfs -> ../../mmcblk0p5 lrwxrwxrwx 1 root root 10 Jan 17 17:38 fip -> ../../mmcblk0p3 FIP lrwxrwxrwx 1 root root 10 Jan 17 17:38 userfs -> ../../mmcblk0p6

• Under Windows^®

CoreUtils that includes the dd command is available for Windows.

7.3. Updating via USB mass storage on U-boot

See How to use USB mass storage in U-Boot.

Refer to the previous section to put FIP binary into SDCard/USB disk.

7.4. Updating your boot device via STM32CubeProgrammer

Refer to the STM32CubeProgrammer documentation for details on how to update your target.

Trusted Firmware for Arm^® Cortex^®-A

Firmware Image Package is a packaging format used by TF-A

Microprocessor Unit

Boot Loader stage 2

universally unique identifier (https://en.wikipedia.org/wiki/Universally_unique_identifier)

Software development kit (A programming package that enables a programmer to develop applications for a specific platform.)

Boot Loader stage 3-2

Operating System

Boot Loader stage 3-3

Linux^® is a registered trademark of Linus Torvalds.

Chain of Trust

Open Portable Trusted Execution Environment

Das U-Boot -- the Universal Boot Loader (see U-Boot_overview)

Device Tree Binary (or Blob)

Secure Payload minimal

First Stage Boot Loader

Trusted Firmware for Arm^® Cortex^®-A

Firmware Image Package is a packaging format used by TF-A

Microprocessor Unit

Boot Loader stage 2

universally unique identifier (https://en.wikipedia.org/wiki/Universally_unique_identifier)

Software development kit (A programming package that enables a programmer to develop applications for a specific platform.)

Boot Loader stage 3-2

Operating System

Boot Loader stage 3-3

Linux^® is a registered trademark of Linus Torvalds.

Chain of Trust

Open Portable Trusted Execution Environment

Das U-Boot -- the Universal Boot Loader (see U-Boot_overview)

Device Tree Binary (or Blob)

Secure Payload minimal

First Stage Boot Loader

Arm^® is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.

Cortex^®