OP-TEE configuration switches

Applicable for

STM32MP13x lines, STM32MP15x lines, STM32MP25x lines

---

1. Purpose

This article describes the configuration switches used in OP-TEE OS component.

2. Overview

OP-TEE is presented in OP-TEE overview and How to configure OP-TEE articles.

OP-TEE OS build sequence is based on GNU Makefile files. OP-TEE configuration is set straight from the OP-TEE build process and in based on shell envrionment variables, also used as Makefile variables as shown in the build command lines below:

 make PLATFORM=stm32mp1-135F_DK

 make PLATFORM=stm32mp1-135F_DK CFG_TEE_CORE_DEBUG=y

 CFG_TEE_CORE_DEBUG=y make PLATFORM=stm32mp1-135F_DK

 make PLATFORM=stm32mp1 CFG_EMBED_DTB_SOURCE_FILE=stm32mp135f-dk.dts

The above make command lines should be enought to build your target boot firmware images.

This article presents many of the OP-TEE configuration switches that can be tuned for a given target. This article does not present all OP-TEE configuration switches. Almost all OP-TEE configuration siwtches are prefixed CFG_.

Usually the first OP-TEE configuration switches one tunes are debug mode (CFG_TEE_CORE_DEBUG=y|n), log trace level (CFG_TEE_CORE_LOG_LEVEL=[0|1|2|3|] and the enable of disable of either CFG_STM32_RESOURCE_MANAGEMENT_PROFILE or CFG_STM32_SECURE_SERVICE_PROFILE. Each platform has a preset of default values for some configuraion swithes.

2.1. Main configuration switches

Some configuration switches are required to build OP-TEE OS, they define the target platform and the target board (that is the device tree source file to use for that platform):

• PLATFORM=<platform>
  • Ex: PLATFORM=stm32mp1 for STM32MP1 series
  • Ex: PLATFORM=stm32mp2 for STM32MP2 series
• CFG_EMBED_DTB_SOURCE_FILE=<device-tree-source-file>: in-tree (core/arch/arm/dts/ ) device tree filename with its .dts extension.
  • Ex: CFG_EMBED_DTB_SOURCE_FILE=stm32mp157f-dk2.dts

Note that some couples of platform/device-tree source file are predefined in OP-TEE OS source tree. They can be used as an alternative to CFG_EMBED_DTB_SOURCE_FILE, using configuration switch PLATFORM with a platform flavor suffix. For example:

• PLATFORM=stm32mp1-157F_EV1
  is an equivalent for PLATFORM=stm32mp1 CFG_EMBED_DTB_SOURCE_FILE=stm32mp157f-ev1.dts.
• PLATFORM=stm32mp1-135F_DK
  is an equivalent for PLATFORM=stm32mp1 CFG_EMBED_DTB_SOURCE_FILE=stm32mp135f-dk.dts.
• PLATFORM=stm32mp2-257F_DK
  is an equivalent for PLATFORM=stm32mp2 CFG_EMBED_DTB_SOURCE_FILE=stm32mp257f-dk.dts.

We mention here also the cross compilation prefix, as alternative to generic CROSS_COMPILE:

• CROSS_COMPILE32:
  CROSS_COMPILE64:
  OP-TEE cross-compilation toolchain is set from CROSS_COMPILE however, for 64bit targets, OP-TEE can host both 32bit and 64bit Trsuted Applications. To build the former, CROSS_COMPILE32 shall be set. CROSS_COMPILE64 is used for 64bit build or build makefiles fallback to CROSS_COMPILE.

STM32MPU OP-TEE proposes 2 configuration profiles: resource manager or secure services:

• CFG_STM32MP_PROFILE=resource-manager
• CFG_STM32MP_PROFILE=secure-services

On STM32MPU platforms, the default select profile depends on the target:
- STM32MP13x lines  since OSTLv5.1: CFG_STM32MP_PROFILE=secure-services
- STM32MP15x lines  since OSTLv5.1: CFG_STM32MP_PROFILE=resource-manager
- STM32MP25x lines  since OSTLv5.1: CFG_STM32MP_PROFILE=secure-services

2.2. OP-TEE core generic switches

Below are some OP-TEE generic optional directives commonly used, described in OP-TEE OS mk/config.mk file:

• CFG_CORE_HEAP_SIZE=<VALUE>: define the byte size of OP-TEE core memory allocation pool
• CFG_NUM_THREADS=<VALUE>: define the number of TEE threads provisioned in OP-TEE
• CFG_REE_FS={n|y}: disable/enable OP-TEE REE filsystem based secure storage area
• CFG_RPMB_FS={n|y}: disable/enable OP-TEE eMMC/RPMB based secure storage area
• CFG_RPMB_FS_DEV_ID=<VALUE>: define the mmcblk block device used by REE for eMMC/RPMB accesses
  (e.g. "1" on stm32mp157x-ev1 boards)
• CFG_WITH_USER_TA={n|y}: disable/enable support for Trusted Applications in OP-TEE secure memory (default is y)
• CFG_WITH_PAGER={n|y}: disable/enable OP-TEE core "pager" mode, allowing OP-TEE is execute in a size constrained internal RAM for few hundreds of kBytes. The feature is used only on STM32MP15x lines  when secure services are enabled.
• CFG_PAGED_USER_TA={n|y}: disable/enable support for paged Trusted Applications when CFG_WITH_PAGER is enabled.

On Armv8-A paltforms, OP-TEE can be built in 64bit (CFG_ARM64_core=y) or in 32bit mode (CFG_ARM32_core=y).

When CFG_STM32_SECURE_SERVICE_PROFILE is enabled, the above switches related to secure services are defautl enabled. Alternatively, when CFG_STM32_RESOURCE_MANAGER_PROFILE is enabled, the above switches related to secure services are disabled.

2.3. Resource management service configuration switches

In both Resource Management profile and Secure Service profile, OP-TEE embeds resource management services that are default enabled in STM32MP software delivery. Each can be individually disabled using their related configuration switch:

• CFG_DEVICE_ENUM_PTA={y|n}. Enumeration of registered embedded secure service to Linux kernel. Default enabled.
• CFG_HWRNG_PTA={y|n}. Default enabled in Secure Service profile.
• CFG_RTC_PTA={y|n}
• CFG_SCMI_PTA={y|n}: Default enabled on STM32MPU OpenSTLinux platforms to manage clock, reset, power and voltage domains, and more.

2.5. = Generic switches for secure services

• CFG_REE_FS={n|y}: disable/enable OP-TEE REE filsystem based secure storage area
• CFG_RPMB_FS={n|y}: disable/enable OP-TEE eMMC/RPMB based secure storage area
• CFG_RPMB_FS_DEV_ID=<VALUE>: define the mmcblk block device used by REE for eMMC/RPMB accesses
  (e.g. "1" on stm32mp157x-ev1 boards)
• CFG_WITH_PAGER={n|y}: disable/enable OP-TEE core "pager" mode, allowing OP-TEE is execute in a size constrained internal RAM for few hundreds of kBytes. The feature is used only on STM32MP15x lines  when secure services are enabled.

2.5.1. Trusted applications

• CFG_WITH_USER_TA={n|y}: disable/enable support for Trusted Applications in OP-TEE secure memory (default is y)
• CFG_PAGED_USER_TA={n|y}: disable/enable support for paged Trusted Applications when CFG_WITH_PAGER is enabled.
• CFG_USER_TA_TARGETS=ta_arm64\ ta_arm32
  CFG_USER_TA_TARGETS=ta_arm64
  CFG_USER_TA_TARGETS=ta_arm32
  Defines whether a 64bit core support 32bit and/or 64 Trusted Applications.

2.5.2. BSEC secure fuse

• CFG_STM32_BSEC=y|n: STM32 BSEC2 OTP access interface driver.
  CFG_STM32_BSEC3=y|n: STM32 BSEC3 OTP access interface driver.
  The below config switches require that one of CFG_STM32_BSEC and CFG_STM32_BSEC3 is enabled and its driver probed.
  • CFG_STM32_BSEC_WRITE=y|n: Allow burning OTP fuses.
  • CFG_STM32MP_PROVISIONING=y|n: Secure Service for burning secure OTP fuses.
  • CFG_BSEC_PTA=y|n: STM32 BSEC secure words access services

2.5.3. Other services

• CFG_STM32MP_REMOTEPROC=y: Secure service for attesting secure loading and boot of the Cortex-M remote processor, if available. When enabled, it enforces CFG_REMOTEPROC_PTA=y.
• CFG_ATTESTATION_PTA={y|n} Default disabled. Can be used to ask OP-TEE to certify the Trusted Application state.
  • CFG_ATTESTATION_PTA_KEY_SIZE=3072: RSA key size used for the attestation.
• CFG_SECSTOR_TA_MGMT_PTA={y|n}: Default enabled to allow Installation of TA images in the OP-TEE secure persistent storage.
• CFG_SYSTEM_PTA={y|n}. Default enabled for TAs to interact with OP-TEE core.
• CFG_PKCS11_TA=y|n This switch does not change OP-TEE OS but is exported to OP-TEE Test for regression test support.

2.6. STM32 driver configuration switches

STM32MPU variants: inherited from the Device Tree File name, or set by build environment.
The following switches are exclusive: only one can be enabled:
CFG_STM32MP13={y|n}, CFG_STM32MP15={y|n}, CFG_STM32MP25={y|n}.

• Clocks, reset conrtoller, voltage regulatos, pinmuxing and GPIOs based on STM32 intefraces:
  • CFG_STM32MP{15|13|25}_CLK=y|n, CFG_STM32MP_CLK_CORE=y|n: Clock framework for STM32MPU varriants.
  • 'CFG_STM32MP{15|13|25}_RSTCTRL=y|n
• CFG_STM32_IWDG=y
  • 'CFG_STM32_GPIO=y; CFG_STM32_UART=y,
    CFG_STM32_LPTIMER=y, CFG_STM32_I2C=y, CFG_STM32_HASH=y, ...

• STM32MP resource access firewals support:
  • CFG_STM32_FIREWALL=y
  • CFG_STM32_ETZPC=y: Firewall enforced enabled in MP13 and MP15 Secure Service profile.
  • CFG_STM32_IAC=y, CFG_STM32_{RIF|RIFSC|RISAB|RISAF}=y :
    Firewall enforced enabled in MP25 Secure Service profile.

• STM32MP cyrptographic hadrware assitance:
  
  • CFG_STM32_CRYPTO_DRIVER=y: Disable in Resource Management profile, enabled in Secure Service profile.
  • CFG_STM32_{CRYP|PKA|SAES|RNG}{{=}]y Support to related STM32 IP interface. Selectively enabled in Secure service profile for applicable platforms.

• Media that requires a secure or low power assitance.
  CFG_STM32_OMM=y, CFG_STM32_FMC=y, CFG_STM32_HPDMA=y
• Remote processor management:
  CFG_STM32_HSEM=y, CFG_STM32_IPCC=y
• Tampering and monitor
  CFG_STM32_TAMP=y, CFG_STM32_TAMP_NVRAM=y, CFG_STM32_HSE_MONITORING=y.
• Low power modes resources
  CFG_STM32_VREFBUF=y, CFG_STPMIC2=y, CFG_STM32_EXTI=y,* CFG_STM32_CPU_OPP=y
• Debug related:
  CFG_STM32_EARLY_CONSOLE_UART={0|1|..}

2.7. Cryptographic operation configuration

Main switches:

• CFG_CRYPTO=y|n
  CFG_CRYPTOLIB_NAME=tomcrypt, alternatively CFG_CRYPTOLIB_NAME=mbedtls
  CFG_CRYPTOLIB_DIR=core/lib/libtomcrypt (resp. CFG_CRYPTOLIB_DIR=lib/mbedtls)
  Target software crypto library embedded in OP-TEE core. Default is libtomcrypt and its internal path.

For all the crypto algorithms listed below, all those that are enabled by do not have HW assistance are processed by the software crypto library of OP-TEE, either [[1]] or [[2]].

Digest and hashing functions:
CFG_STM32_HASH enforce MD5, SHA*, SHA3_*, and SHAKE*.

• CFG_CRYPTO_[MD5|SHA1|SHA224|SHA256|SHA384]=y|n
• CFG_CRYPTO_SHA3_[224|384|512]=y|n
• CFG_CRYPTO_SHA512|SHA512_256]=y|n
• CFG_CRYPTO_SHAKE[128|256]=y|n
• CFG_CRYPTO_SM3]=y|n

Symmetric cryptographic algorithms:
CFG_STM32_CRYP enforce AES ECB/CBC/CTR/GCM/CCM and DES/TDES EBC/CBC.
CFG_STM32_SAES enforce AES ECB/CBC/CTR/GCM/CCM.

• CFG_CRYPTO_AES=y|n:
• CFG_CRYPTO_AES_GCM_FROM_CRYPTOLIB=y|n
• CFG_CRYPTO_DES=y|n
• CFG_CRYPTO_SM4=y|n
• CFG_CRYPTO_HMAC=y|n

and their related modes (when applicable):

• CFG_CRYPTO_ECB=y|n
• CFG_CRYPTO_CBC=y|n
• CFG_CRYPTO_CBC_MAC=y|n
  • CFG_CRYPTO_CBC_MAC_BUNDLE_BLOCKS=64
• CFG_CRYPTO_[CCM|CMAC|CTR|CTS|GCM|XTS]=y|n

Key derivation support:

• CFG_CRYPTO_HKDF=y|n
• CFG_CRYPTO_PBKDF2=y|n
• CFG_CRYPTO_CONCAT_KDF=y|n
• CFG_CRYPTO_HW_PBKDF2=y|n

Asymmetric cryptographic algorithms:
CFG_STM32_PKA=y enables ECC operations.

• CFG_CRYPTO_[DH|DSA|RSA|RSASSA_NA1]={y|n}
• CFG_CRYPTO_[ECC|ED25519|X25519]={y|n}
• CFG_CRYPTO_SM2_[DSA|KEP|PKE]={y|n}

Generic crypto framework configuration switches:

• CFG_WITH_SOFTWARE_PRNG={y|n}
  y: Random bytes are generated software (fortuna) processing / n: a hardware source.
  CFG_HWRNG_PTA=y requires CFG_WITH_SOFTWARE_PRNG=n
• CFG_CRYPTO_SIZE_OPTIMIZATION={y|n}

2.8. Debug related configuraiton switches

OP-TEE generic optional debugging and test directives commonly used, described in OP-TEE OS mk/config.mk file:

• CFG_TEE_CORE_DEBUG=n|y: disable/enable debug support (including assert() with NDEBUG)
• CFG_TEE_CORE_LOG_LEVEL={0|1|2|3|4}: define OP-TEE core trace level (0: no trace, 4: overflow of traces) (default is 2: info)
• CFG_TEE_CORE_TA_LEVEL={0|1|2|3|4}: define OP-TEE Trusted Applications (TAs) trace level (default is 1: error)
• CFG_TEE_CORE_TA_TRACE=n|y: disable/enable TAs trace message at define OP-TEE core level (default is y)
• CFG_STM32_EARLY_CONSOLE_UART={0|1|2|...}: define the USART instance used for early console trace messages (default is 4)
• CFG_CC_OPT_LEVEL=[s|0|1|2]' sets GCC/Clang optimization level. Default is s for speed.
• CFG_UNWIND=n|y: disable/enable stack unwind debug trace messages
• CFG_ENABLE_EMBEDDED_TESTS=n|y; disable/enable embedded test, used by xtest tool (default is y)
• CFG_WITH_STATS=n|y: disable/enable OP-TEE statistics retrieve from the Stats PTA service.
• CFG_WERROR=n|y: disable/enable build error trigger on OP-TEE build warning occurences.
• CFG_TA_GPROF_SUPPORT=n|y: disable/enable profiling of Trusted Application implementation based on gprof standard tool
• CFG_FTRACE_SUPPORT=n|y: disable/enable function trace support in Trusted Applications based on ftrace standard tool
• CFG_SYSCALL_FTRACE=n|y: disable/enable support for ftrace syscall graph generation

Information on configuration switches CFG_TEE_CORE_DEBUG, CFG_TEE_CORE_LOG_LEVEL and CFG_UNWIND can be found in the How_to_debug_OP-TEE article.

Open portable trusted execution environment

Operating system

Trusted execution environment

Device tree binary (or Blob)

File system or filesystem, method and data structure that the operating system uses to control how data is stored and retrieved -NEW

Former spelling for e•MMC ('e' in italic)

Trusted application

Random access memory (Early computer memories generally hadserial access. Memories where any given address can be accessed when desired were then called "random access" to distinguish them from the memories where contents can only be accessed in a fixed order. The term is used today for volatile random-acces ssemiconductor memories.)

Pseudo Trusted Application

Linux^® is a registered trademark of Linus Torvalds.

Real time clock

System control and management interface

Boot and Security and OTP control

One time programmed

Cortex^®

Independent watchdog

General-purpose input/output (A realization of open ended transmission between devices on an embedded level. These pins available on a processor can be programmed to be used to either accept input or provide output to external devices depending on user desires and applications requirements.)

Universal asynchronous receiver/transmitter

Inter-integrated circuit (Bi-directional 2-wire bus standard for efficient inter-IC control.)

Extended trustzone protection controller

Illegal ACcesses - NEW

Resource Isolation Framework

Resource Isolation Framework Security Controller - NEW

Resource Isolation Slave unit for Address space protection (Block-based) - NEW

Resource Isolation Slave unit for Address space protection (Full version) - NEW

Cryptographic processor

Random number generator

Hardware semaphore

Inter-processor communication controller

Tamper

High speed external oscillator (STM32 clock source)

Voltage reference buffer (STM32 specific)

External interrupt

Central processing unit

Operating performance point (link to voltage and frequency scaling)

Message digest 5

Secure hash algorithm

Advanced encryption standard

Data encryption standard

Triple data encryption standard

Hash-based Message authentication code

Compatibility test suite (Android specific) or clear to send (in UART context)

Elliptic curve cryptography

Error correction capability

Universal synchronous/asynchronous receiver/transmitter