services/tfm/build.html · services/tfm/build.rst 공식 원문 ↗

Zephyr 3.7.0 · TF-M · Build and Signing

TF-M Build System

Secure boot, TF-M, Zephyr image를 함께 build하고 검증 가능한 배포 image로 만듭니다.

Official pathservices/tfm/build.html
Source fileservices/tfm/build.rst
Source versionZephyr 3.7.0
TranslationFull · reviewed

본문 기준: Zephyr 3.7.0 LTS3 · 이후 유지보수 패치는 별도입니다.

Part 1

요약·해설

_ns target의 automatic build, image property, BL2 signing key 교체, merged HEX와 footprint report를 설명합니다.

Images

BL2 · TF-M · Zephyr

Trust

Production signing keys

Reports

Secure RAM · ROM

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기
원문 SHA-256 1636E04D2A47EC883AAA9E67C5A4FC34296FDB4EB1F7D14C25EA28FAC81E3A7E
.. _tfm_build_system:

TF-M Build System
#################

When building a valid ``_ns`` board target, TF-M will be built in the
background, and linked with the Zephyr non-secure application. No knowledge
of TF-M's build system is required in most cases, and the following will
build a TF-M and Zephyr image pair, and run it in qemu with no additional
steps required:

   .. code-block:: bash

     $ west build -p auto -b mps2_an521_ns samples/tfm_integration/psa_protected_storage/ -t run

The outputs and certain key steps in this build process are described here,
however, since you will need to understand and interact with the outputs, and
deal with signing the secure and non-secure images before deploying them.

Images Created by the TF-M Build
********************************

The TF-M build system creates the following executable files:

* tfm_s - TF-M secure firmware
* tfm_ns - TF-M non-secure app (only used by regression tests).
* bl2 - TF-M MCUboot, if enabled

For each of these, it creates .bin, .hex, .elf, and .axf files.

The TF-M build system also creates signed variants of tfm_s and tfm_ns, and a
file which combines them:

* tfm_s_signed
* tfm_ns_signed
* tfm_s_ns_signed

For each of these, only .bin files are created.

The TF-M non-secure app is discarded in favor of Zephyr non-secure app except
when running the TF-M regression test suite.

The Zephyr build system usually signs both tfm_s and the Zephyr non-secure app itself.
See below for details.

The 'tfm' target contains properties for all these paths.
For example, the following will resolve to ``<path>/tfm_s.hex``:

   .. code-block::

      $<TARGET_PROPERTY:tfm,TFM_S_HEX_FILE>

See the top level CMakeLists.txt file in the tfm module for an overview of all
the properties.

Signing Images
**************

When :kconfig:option:`CONFIG_TFM_BL2` is set to ``y``, TF-M uses a secure bootloader
(BL2) and firmware images must be signed with a private key. The firmware image
is validated by the bootloader during updates using the corresponding public
key, which is stored inside the secure bootloader firmware image.

By default, ``<tfm-dir>/bl2/ext/mcuboot/root-rsa-3072.pem`` is used to sign secure
images, and ``<tfm-dir>/bl2/ext/mcuboot/root-rsa-3072_1.pem`` is used to sign
non-secure images. These default .pem keys can (and **should**) be overridden
using the :kconfig:option:`CONFIG_TFM_KEY_FILE_S` and
:kconfig:option:`CONFIG_TFM_KEY_FILE_NS` config flags.

To satisfy `PSA Certified Level 1`_ requirements, **You MUST replace
the default .pem file with a new key pair!**

To generate a new public/private key pair, run the following commands:

   .. code-block:: bash

     $ imgtool keygen -k root-rsa-3072_s.pem -t rsa-3072
     $ imgtool keygen -k root-rsa-3072_ns.pem -t rsa-3072

You can then place the new .pem files in an alternate location, such as your
Zephyr application folder, and reference them in the ``prj.conf`` file via the
:kconfig:option:`CONFIG_TFM_KEY_FILE_S` and :kconfig:option:`CONFIG_TFM_KEY_FILE_NS` config
flags.

   .. warning::

     Be sure to keep your private key file in a safe, reliable location! If you
     lose this key file, you will be unable to sign any future firmware images,
     and it will no longer be possible to update your devices in the field!

After the built-in signing script has run, it creates a ``tfm_merged.hex``
file that contains all three binaries: bl2, tfm_s, and the zephyr app. This
hex file can then be flashed to your development board or run in QEMU.

.. _PSA Certified Level 1:
  https://www.psacertified.org/security-certification/psa-certified-level-1/

Custom CMake arguments
======================

When building a Zephyr application with TF-M it might be necessary to control
the CMake arguments passed to the TF-M build.

Zephyr TF-M build offers several Kconfig options for controlling the build, but
doesn't cover every CMake argument supported by the TF-M build system.

The ``TFM_CMAKE_OPTIONS`` property on the ``zephyr_property_target`` can be used
to pass custom CMake arguments to the TF-M build system.

To pass the CMake argument ``-DFOO=bar`` to the TF-M build system, place the
following CMake snippet in your CMakeLists.txt file.

   .. code-block:: cmake

     set_property(TARGET zephyr_property_target
                  APPEND PROPERTY TFM_CMAKE_OPTIONS
                  -DFOO=bar
     )

.. note::
   The ``TFM_CMAKE_OPTIONS`` is a list so it is possible to append multiple
   options. Also CMake generator expressions are supported, such as
   ``$<1:-DFOO=bar>``

Since ``TFM_CMAKE_OPTIONS`` is a list argument it will be expanded before it is
passed to the TF-M build system.
Options that have list arguments must therefore be properly escaped to avoid
being expanded as a list.

   .. code-block:: cmake

     set_property(TARGET zephyr_property_target
                  APPEND PROPERTY TFM_CMAKE_OPTIONS
                  -DFOO="bar\\\;baz"
     )

Footprint and Memory Usage
**************************

The build system offers targets to view and analyse RAM and ROM usage in generated images.
The tools run on the final images and give information about size of symbols and code being used in both RAM and ROM.
For more information on these tools look here: :ref:`footprint_tools`

Use the ``tfm_ram_report`` to get the RAM report for TF-M secure firmware (tfm_s).

.. zephyr-app-commands::
    :tool: all
    :app: samples/hello_world
    :board: mps2_an521_ns
    :goals: tfm_ram_report

Use the ``tfm_rom_report`` to get the ROM report for TF-M secure firmware (tfm_s).

.. zephyr-app-commands::
    :tool: all
    :app: samples/hello_world
    :board: mps2_an521_ns
    :goals: tfm_rom_report

Use the ``bl2_ram_report`` to get the RAM report for TF-M MCUboot, if enabled.

.. zephyr-app-commands::
    :tool: all
    :app: samples/hello_world
    :board: mps2_an521_ns
    :goals: bl2_ram_report

Use the ``bl2_rom_report`` to get the ROM report for TF-M MCUboot, if enabled.

.. zephyr-app-commands::
    :tool: all
    :app: samples/hello_world
    :board: mps2_an521_ns
    :goals: bl2_rom_report

Part 3

한국어 전문 번역

유효한 _ns board target을 build하면 TF-M이 background external project로 함께 build되고 Zephyr non-secure application과 연결됩니다. 보통 TF-M build system을 따로 알 필요 없이 다음 명령 하나로 TF-M·Zephyr image pair를 만들고 QEMU에서 실행할 수 있습니다.

$ west build -p auto -b mps2_an521_ns samples/tfm_integration/psa_protected_storage/ -t run

배포 단계에서는 build output을 찾아 secure·non-secure image에 production key로 서명해야 하므로, 아래 file 종류와 signing 흐름은 이해해야 합니다.

Images Created by the TF-M Build

TF-M build system은 세 종류의 executable을 만듭니다. tfm_s는 TF-M secure firmware, tfm_ns는 regression test에서만 쓰는 TF-M non-secure app, bl2는 활성화했을 때의 TF-M MCUboot입니다. 각각 .bin, .hex, .elf, .axf 형식이 생성됩니다.

또한 tfm_s_signed, tfm_ns_signed, 두 image를 합친 tfm_s_ns_signed의 signed variant를 만들며 이들은 .bin만 생성합니다. 일반 application에서는 TF-M의 non-secure app을 버리고 Zephyr non-secure app을 사용합니다. 예외는 TF-M regression test suite입니다.

Zephyr build system은 보통 tfm_s와 Zephyr non-secure app을 직접 서명합니다. CMake의 tfm target에는 산출물 path property가 있으며 다음 generator expression은 <path>/tfm_s.hex로 평가됩니다.

$<TARGET_PROPERTY:tfm,TFM_S_HEX_FILE>

전체 property 목록은 TF-M module의 top-level CMakeLists.txt에서 확인합니다.

TF-M와 Zephyr image build · signing · merge
BL2선택 secure bootloader · public key 내장
secure boot
tfm_sSecure Processing Environment image
PSA API boundary
Zephyr NSNon-secure application image
sign · combine
tfm_merged.hexBoard flash 또는 QEMU용 최종 image

Signing Images

CONFIG_TFM_BL2=y이면 TF-M은 secure bootloader BL2를 사용하므로 firmware image를 private key로 서명해야 합니다. Bootloader는 secure image 안에 저장된 대응 public key로 boot와 update 시 signature를 검증합니다.

기본 secure signing key는 <tfm-dir>/bl2/ext/mcuboot/root-rsa-3072.pem, non-secure key는 root-rsa-3072_1.pem입니다. 이 sample key는 CONFIG_TFM_KEY_FILE_S와 CONFIG_TFM_KEY_FILE_NS로 반드시 production key로 교체해야 합니다. PSA Certified Level 1 요구사항도 새 key pair 사용을 요구합니다.

RSA-3072 public/private key pair는 다음처럼 생성합니다.

$ imgtool keygen -k root-rsa-3072_s.pem -t rsa-3072
$ imgtool keygen -k root-rsa-3072_ns.pem -t rsa-3072

생성한 PEM을 application folder 같은 별도 위치에 두고 prj.conf에서 두 Kconfig option으로 지정합니다.

내장 signing script가 끝나면 BL2, tfm_s, Zephyr app을 모두 포함한 tfm_merged.hex를 만듭니다. 이 file을 development board에 flash하거나 QEMU에서 실행합니다.

Custom CMake arguments

Zephyr가 제공하는 Kconfig만으로 TF-M build의 모든 CMake argument를 제어할 수는 없습니다. 이때 zephyr_property_target의 TFM_CMAKE_OPTIONS property에 custom option을 append합니다.

예를 들어 TF-M에 -DFOO=bar를 전달하려면 application CMakeLists.txt에 다음을 넣습니다.

set_property(TARGET zephyr_property_target
             APPEND PROPERTY TFM_CMAKE_OPTIONS
             -DFOO=bar
)

TFM_CMAKE_OPTIONS는 list이므로 여러 option을 append할 수 있고 $<1:-DFOO=bar> 같은 generator expression도 지원합니다. 다만 TF-M에 넘기기 전에 CMake list가 확장되므로, option 값 자체가 list라면 semicolon을 escape해야 합니다.

set_property(TARGET zephyr_property_target
             APPEND PROPERTY TFM_CMAKE_OPTIONS
             -DFOO="bar\\\;baz"
)

Footprint and Memory Usage

최종 image의 RAM·ROM 사용량과 symbol·code size를 분석하는 build target을 제공합니다. TF-M secure firmware의 RAM은 tfm_ram_report, ROM은 tfm_rom_report로 확인합니다.

west build -b mps2_an521_ns samples/hello_world
west build -t tfm_ram_report
# Use cmake to configure a Ninja-based buildsystem:
cmake -Bbuild -GNinja -DBOARD=mps2_an521_ns samples/hello_world

# Now run the build tool on the generated build system:
ninja -Cbuild tfm_ram_report
west build -b mps2_an521_ns samples/hello_world
west build -t tfm_rom_report
# Use cmake to configure a Ninja-based buildsystem:
cmake -Bbuild -GNinja -DBOARD=mps2_an521_ns samples/hello_world

# Now run the build tool on the generated build system:
ninja -Cbuild tfm_rom_report

BL2가 활성화된 경우 secure bootloader의 RAM은 bl2_ram_report, ROM은 bl2_rom_report로 확인합니다.

west build -b mps2_an521_ns samples/hello_world
west build -t bl2_ram_report
# Use cmake to configure a Ninja-based buildsystem:
cmake -Bbuild -GNinja -DBOARD=mps2_an521_ns samples/hello_world

# Now run the build tool on the generated build system:
ninja -Cbuild bl2_ram_report
west build -b mps2_an521_ns samples/hello_world
west build -t bl2_rom_report
# Use cmake to configure a Ninja-based buildsystem:
cmake -Bbuild -GNinja -DBOARD=mps2_an521_ns samples/hello_world

# Now run the build tool on the generated build system:
ninja -Cbuild bl2_rom_report

Source

출처

영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.