From fec5ed6077d6d9e983b4d783b2bd5d6af17c8830 Mon Sep 17 00:00:00 2001 From: Karl Zhang Date: Fri, 8 May 2020 08:22:52 -0500 Subject: [PATCH] trusted-firmware-m: Add initial plumbing for TFM This commits adds a config option to build a PSA trusted-firmware-m (TF-M) application image for the secure processing environment, and configures the Zephyr application image for the non-secure processing environment. The secure and non-secure environment images will be linked together via the veneer function table that is produced as an artifact of the TF-M build process. Signed-off-by: Karl Zhang --- modules/Kconfig | 1 + modules/Kconfig.tfm | 40 ++++++ samples/index.rst | 1 + samples/tfm_integration/tfm_integration.rst | 139 ++++++++++++++++++++ west.yml | 3 + 5 files changed, 184 insertions(+) create mode 100644 modules/Kconfig.tfm create mode 100644 samples/tfm_integration/tfm_integration.rst diff --git a/modules/Kconfig b/modules/Kconfig index 57072d104bf..c1786441fcd 100644 --- a/modules/Kconfig +++ b/modules/Kconfig @@ -23,6 +23,7 @@ source "modules/Kconfig.simplelink" source "modules/Kconfig.st" source "modules/Kconfig.stm32" source "modules/Kconfig.syst" +source "modules/Kconfig.tfm" source "modules/Kconfig.tinycbor" source "modules/Kconfig.tinycrypt" source "modules/Kconfig.vega" diff --git a/modules/Kconfig.tfm b/modules/Kconfig.tfm new file mode 100644 index 00000000000..3e61a7123a6 --- /dev/null +++ b/modules/Kconfig.tfm @@ -0,0 +1,40 @@ +# TF-M/PSA Related + +# Copyright (c) 2019, 2020 Linaro Limited +# SPDX-License-Identifier: Apache-2.0 + +config BUILD_WITH_TFM + bool "Build with TF-M as the Secure Execution Environment" + depends on TRUSTED_EXECUTION_NONSECURE + help + When enabled, this option instructs the Zephyr build process to + additionaly generate a TF-M image for the Secure Execution + environment, along with the Zephyr image. The Zephyr image + itself is to be executed in the Non-Secure Processing Environment. + The required dependency on TRUSTED_EXECUTION_NONSECURE + ensures that the Zephyr image is built as a Non-Secure image. Both + TF-M and Zephyr images, as well as the veneer object file that links + them, are generated during the normal Zephyr build process. + + Note: + Building with the "_nonsecure" BOARD variant (e.g. + "mps2_an521_nonsecure") ensures that + CONFIG_TRUSTED_EXECUTION_NONSECURE ie enabled. + +config TFM_KEY_FILE_S + string "Path to private key used to sign secure firmware images." + depends on BUILD_WITH_TFM + default "${ZEPHYR_BASE}/../modules/tee/tfm/trusted-firmware-m/bl2/ext/mcuboot/root-rsa-3072.pem" + help + The path and filename for the .pem file containing the private key + that should be used by the BL2 bootloader when signing secure + firmware images. + +config TFM_KEY_FILE_NS + string "Path to private key used to sign non-secure firmware images." + depends on BUILD_WITH_TFM + default "${ZEPHYR_BASE}/../modules/tee/tfm/trusted-firmware-m/bl2/ext/mcuboot/root-rsa-3072_1.pem" + help + The path and filename for the .pem file containing the private key + that should be used by the BL2 bootloader when signing non-secure + firmware images. diff --git a/samples/index.rst b/samples/index.rst index ce1d6f08f97..deccd1cb1bf 100644 --- a/samples/index.rst +++ b/samples/index.rst @@ -26,6 +26,7 @@ Samples and Demos video/* scheduler/* smp/* + tfm_integration/tfm_integration.rst .. comment To add a new sample document, please use the template available under diff --git a/samples/tfm_integration/tfm_integration.rst b/samples/tfm_integration/tfm_integration.rst new file mode 100644 index 00000000000..20a8b084536 --- /dev/null +++ b/samples/tfm_integration/tfm_integration.rst @@ -0,0 +1,139 @@ +.. _tfm_integration-samples: + +TFM Integration Samples +####################### + +.. toctree:: + :maxdepth: 1 + :glob: + + */* + +Trusted Firmware-M (TF-M) +######################### + +Overview +******** +These TF-M integration examples can be used with a supported Armv8-M board, and +demonstrate how the TF-M APIs can be used with Zephyr. + +Trusted Firmware Platform Security Architecture (PSA) APIs are used for the +secure processing environment (S), with Zephyr running in the non-secure +processing environment (NS). + +As part of the standard build process, the secure bootloader (BL2) is normally +built, in addition to the TF-M S and Zephyr NS binary images. The S and NS +images are then merged and signed using the private signing keys, whose public +key values are stored in the secure bootloader. This allows the application +images to be verified and either accepted or rejected during the image +verification process at startup, based on a pair of private keys that you +control. + +What is Trusted Firmware-M (TF-M)? +********************************** + +Trusted Firmware-M (TF-M) is the reference implementation of `Platform Security +Architecture (PSA) `_. + +TF-M provides a highly configurable set of software components to create a +Trusted Execution Environment. This is achieved by a set of secure run time +services such as Secure Storage, Cryptography, Audit Logs and Attestation. +Additionally, secure boot in TF-M ensures integrity of run time software and +supports firmware upgrade. + +The current TF-M implementation specifically targets TrustZone for ARMv8-M. + +Trusted Firmware M source code is available at +`git.trustedfirmware.org `_, although a fork +of this source code is maintained by the Zephyr Project as a module for +convenience sake at +``_. + +For further information consult the official `TF-M documentation`_ + +.. _TF-M documentation: + https://ci.trustedfirmware.org/job/tf-m-build-test-nightly/lastSuccessfulBuild/artifact/build-docs/tf-m_documents/install/doc/user_guide/html/index.html + +TF-M Requirements +***************** + +The following Python modules are required when building TF-M binaries: + +* cryptography +* pyasn1 +* pyyaml +* cbor>=1.0.0 + +You can install them via: + + .. code-block:: bash + + $ pip3 install --user cryptography pyasn1 pyyaml cbor>=1.0.0 + +They are used by TF-M's signing utility to prepare firmware images for +validation by the bootloader. + +Part of the process of generating binaries for QEMU and merging signed +secure and non-secure binaries on certain platforms also requires the use of +the ``srec_cat`` utility. + +This can be installed on Linux via: + + .. code-block:: bash + + $ sudo apt-get install srecord + +And on OS X via: + + .. code-block:: bash + + $ brew install srecord + +For Windows-based systems, please make sure you have a copy of the utility +available on your system path. See, for example: +`SRecord for Windows `_ + +Signing Images +============== + +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 at startup using +the corresponding public key, which is stored inside the secure bootloader +firmware image. + +By default, ``tfm/bl2/ext/mcuboot/root-rsa-3072.pem`` is used to sign secure +images, and ``tfm/bl2/ext/mcuboot/root-rsa-3072_1.pem`` is used to sign +non-secure images. Theses default .pem keys keys can be overridden using the +``CONFIG_TFM_KEY_FILE_S`` and ``CONFIG_TFM_KEY_FILE_NS`` values. + +The ``imgtool.py`` script from TF-M signs the TF-M + Zephyr binary using the +.pem private key.. + +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 + + $ cd $ZEPHYR_BASE/../modules/tee/tfm/trusted-firmware-m/bl2/ext/mcuboot/scripts + $ chmod +x imgtool.py + $ ./imgtool.py keygen -k root-rsa-3072.pem -t rsa-3072 + $ ./imgtool.py keygen -k root-rsa-3072_1.pem -t rsa-3072 + +You can then replace the .pem file in ``[TF-M_PATH]/bl2/ext/mcuboot/`` with +the newly generated .pem files, and rebuild the bootloader so that it uses the +public key extracted from this new key file when validating firmware images. + +Alternatively, 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 +``CONFIG_TFM_KEY_FILE_S`` and ``CONFIG_TFM_KEY_FILE_NS`` config values. + + .. 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! + +.. _PSA Certified Level 1: + https://www.psacertified.org/security-certification/psa-certified-level-1/ diff --git a/west.yml b/west.yml index e1133638485..fc5e07804a7 100644 --- a/west.yml +++ b/west.yml @@ -130,6 +130,9 @@ manifest: - name: edtt path: tools/edtt revision: c39888ff74acf421eeff9a7514fa9b172c3373f7 + - name: trusted-firmware-m + path: modules/tee/tfm + revision: 7de2daa1967b2dc12cbe0fcc0171ac3064ea596b self: path: zephyr