Frequently Asked Questions

Table of Contents


Abbreviations

OP-TEE:Open Portable TEE
TA:Trusted Application
TEE:Trusted Execution Environment
TZASC:TrustZone Address Space Controller
TZPC:TrustZone Protection Controller

Architecture

Q: Which platforms/architectures are supported?

  • The Platforms supported page lists all platforms and architectures currently supported in the official tree.

Q: Are 32-bit as well as 64-bit support?

  • Both 32- and 64-bit are fully supported for all OP-TEE components.

Q: What’s the maximum size for heap and stack? Can it be changed?

  • Yes, it can be changed. In the current setup (for vexpress for example), there are 32MB DDR dedicated for OP-TEE. 1MB for TEE RAM and 1MB for PUB RAM, this leaves 30MB for Trusted Applications. In the Trusted Applications, you set TA_STACK_SIZE and TA_DATA_SIZE. Typically, we set stack to 2KB and data to 32K. But you are free to adjust those according to the amount of memory you have available. If you need them to be bigger than 1MB then you also must adjust TA’s MMU L1 table accordingly, since default section mapping is 1MB.

Q: What is the size of OP-TEE itself?

  • As of 2016.01, optee_os is about 244KB (release build). It is preferred to run optee_os entierly in SRAM, but if there is not enough room, DRAM can be used and protected with TZASC. We are also looking into the possibility of creating a ‘minimal’ OP-TEE, i.e. a limited OP-TEE usable even in a very memory constrained environment, by eliminating as many memory-hungry parts as possible. There is however no ETA for this at the moment.

  • You can check the memory usage by using the make mem_usage target in optee_os, for example:

    $ make ... mem_usage
    # Which will output a file with the figures here:
    # out/arm/core/tee.mem_usage
    

    You will of course get different sizes depending on what compile time flags you have enabled when running make mem_usage.

Q: Can NEON optimizations be done in OP-TEE?

  • Yes (for additional information, please also see Issue#953)

Q: Can I use C++ libraries in OP-TEE?

  • C++ libraries are currently not supported. Technically, it is possible but will require a fair amount of work to implement, especially more so if exceptions are required. There are currently no plans to do this.
  • See Issue#2628 for related information.

Q: Would using malloc() in OP-TEE give physically contiguous memory?

  • malloc() in OP-TEE currently gives physically contiguous memory. It is not guaranteed as it is not mentioned anywhere in the documentation, but in practice the heap only has physically contiguous memory in the pool(s). The heap in OP-TEE is normally quite small, ~24KiB, and could be a bit fragmented.

Q: Can I limit what CPUs / cores OP-TEE runs on?

  • Currently it’s up to the kernel to decide which core it runs on, i.e, it will be the same core as the one initiating the SMC in Linux. Please also see Issue#1194.

Q: How is OP-TEE being scheduled?

  • OP-TEE does not have its own scheduler, instead it is being scheduled by Linux kernel. For more information, please see Issue#1036 and Issue#1183.

Board support

Q: How do I port OP-TEE to another platform?

  • Start by reading the Porting guidelines.

  • See the Presentations page. There might be some interesting information in the “LCU14-302 How To Port OP-TEE To Another Platform” deck and video. Beware that the presentation is more than five years old, so even though it is a good source, there might be parts that are not relevant any longer.

  • As a good example for


Building

Q: I got build errors running latest, why?

  • What did you try to build? Only optee_os? A full OP-TEE developer setup using QEMU, HiKey, RPi3, Juno using repo? AOSP? OpenEmbedded? What we build on daily basis are the OP-TEE developer setups (see Platforms supported by build.git) , but other builds like AOSP and OpenEmbedded are builds that we try from time to time, but we have no CI/regression testing configured for those builds.
  • By running latest instead of stable also comes with a risk of getting build errors due to version and/or interdependency skew which can result in build error. Now, such issues most often affects running xtest and not the building. If you however clean all gits and do a repo sync -d. Then we’re almost 100% sure you will get back to a working state again, since as mentioned in next bullet, we build (and run xtest) on all QEMU on all patches sent to OP-TEE.
  • Every pull request in OP-TEE are tested on hardware (see Q: How are you testing OP-TEE?).

Q: I got build errors running stable tag x.y.z, why?

  • Stable releases are quite well tested both in terms of building for all supported platforms and running xtest on all platforms, so if you cannot get that to build and run, then there is a great chance you have something wrong on your side. All platforms that has been tested on a stable release can be found in CHANGELOG.md file. Having that said, we do make mistakes on stable builds also from time to time.

Q: I get gcc XYZ or g++ XYZ compiler error messages?

  • Most likely you’re trying to build OP-TEE using the regular x86 compiler and not the using the Arm toolchain. Please install the Prerequisites and make sure you have gotten and installed the Arm toolchains as described at the Toolchains page. (for additional information, please see Issue#846).

Q: I found this build.git, what is that?

  • build is a git that is used in conjunction with the manifest to create full OP-TEE developer builds. It contains helper makefiles that makes it easy to get OP-TEE up and running on the setups that are using repo.

Q: When running make from build.git it fails to download the toolchains?

  • We try to stay somewhat up to date with running recent GCC versions. But just like everywhere else on the net things moves around. In some cases like Issue#1195, the URL was changed without us noticing it. If you find and fix such an issue, please send the fix as pull request and we will be happy to merge it.

Q: How can I build LLVM compiler-rt with BTI enabled ?

  • Download the llvm-12 sources either from the releases page or you can checkout the “release/12.x” from llvm’s github. (12 to match your chosen clang version).

  • Make a build directory and cd into that.

  • Run this cmake command to configure a standalone build of compiler-rt.

    cmake -G Ninja <llvm sources>/compiler-rt/ -DCMAKE_BUILD_TYPE=Release \
        -DLLVM_CONFIG_PATH=<path to>/llvm-config" \
        -DCMAKE_CXX_FLAGS="-mbranch-protection=bti" \
        -DCMAKE_C_FLAGS="-mbranch-protection=bti" \
        -DCMAKE_ASM_FLAGS="-mbranch-protection=bti" \
        -DCOMPILER_RT_BUILD_SANITIZERS=OFF \
        -DCOMPILER_RT_BUILD_XRAY=OFF \
        -DCOMPILER_RT_BUILD_LIBFUZZER=OFF \
        -DCOMPILER_RT_BUILD_PROFILE=OFF \
        -DCOMPILER_RT_BUILD_MEMPROF=OFF
    

    Replace the path to llvm-config with the path to the clang install you want to use to compile. What this does is enable BTI protection for c/cxx/assembly files (all the types in compiler-rt) and disable some parts of the build that you wouldn’t need. If you need more components you can find cmake options for them in compiler-rt/CMakeLists.txt.

    Once you’ve built that you will find the libraries in <build folder>/lib/linux. You can verify that each object in the builtins has the BTI marker by doing the following:

    /build-llvm-aarch64/lib/linux$ mkdir tmp && cd tmp
    /build-llvm-aarch64/lib/linux/tmp$ cp ../libclang_rt.builtins-aarch64.a .
    /build-llvm-aarch64/lib/linux/tmp$ ar x libclang_rt.builtins-aarch64.a
    /build-llvm-aarch64/lib/linux/tmp$ rm libclang_rt.builtins-aarch64.a
    /build-llvm-aarch64/lib/linux/tmp$ for i in *.o; do echo "$i:" &&
    readelf -a $i | grep -i bti ; done
    

    This should find a BTI line for every file.

    $ for i in *.o; do echo "$i:" && readelf -a $i | grep -i bti ; done | wc -l
      502
    $ ls | wc -l
      251
    

    251 * 2 = 502 so all objects in the archive are bti compatible.

    How you take this set of libraries and integrate it into your overall build system is up to you. The major thing to note is that the name of the library does not change when you enable BTI protection

Q: How can I build GCC with BTI enabled?

  • A GCC toolchain with BTI enabled can easily be built using Crosstool-NG:

    $ git clone https://github.com/crosstool-ng/crosstool-ng
    $ cd crosstool-ng
    $ ./bootstrap && ./configure --enable-local && make
    $ ./ct-ng aarch64-unknown-linux-gnu
    $ cat >>.config <<_EOF_
    CT_CC_GCC_EXTRA_CONFIG_ARRAY="--enable-standard-branch-protection"
    CT_CC_GCC_CORE_EXTRA_CONFIG_ARRAY="--enable-standard-branch-protection"
    _EOF_
    $ ./ct-ng build.$(nproc)
    

    The above commands will install the new toolchain in ~/x-tools/aarch64-unknown-linux-gnu. You can then use this toolchain to build and run OP-TEE for QEMU v8 with full BTI support by adding a few arguments to the make run command:

    $ make CFG_CORE_BTI=y CFG_TA_BTI=y CFG_USER_TA_TARGETS=ta_arm64 \
      AARCH64_CROSS_COMPILE=~/x-tools/aarch64-unknown-linux-gnu/bin/aarch64-linux-gnu- \
      run
    

Q: What is the quickest and easiest way to try OP-TEE?

  • That would be running it on QEMU on a local PC. To do that you would need to:

  • By summarizing the above, you would need to:
    $ sudo apt-get install [pre-reqs]
    $ mkdir optee-qemu && cd optee-qemu
    $ repo init -u https://github.com/OP-TEE/manifest.git
    $ repo sync
    $ cd build
    $ make toolchains -j2
    $ make run
    QEMU console:         (qemu) c
    Normal world shell:   # xtest
    

Certification and security reviews

Q: Will TrustedFirmware.org be involved in GlobalPlatform certification/qualification?

  • No, not as of now. Most often certification is performed using a certain software version and on a unique device. I.e., it is the combination software + hardware that gets certified. This is typically something that the SoC or OEM needs to do on their own.
  • But it is worth mentioning that since OP-TEE is coming from a proprietary TEE solution that was GlobalPlatform certified on some products in the past and we regularly have people from some member companies running the extended test suite from GlobalPlatform we know that the gap to become GlobalPlatform certified/qualified isn’t that big.

Q: Has any test lab been testing OP-TEE?

  • Applus Laboratories have done some side-channel attack testing and fault injection testing on OP-TEE using the HiKey 620 device. Their findings and fixes can be found at the Security Advisories page at optee.org.
  • Riscure did a mini-audit of OP-TEE which generated a couple of patches (see PR#2745). The Security Advisories page at optee.org will be updated with more information regarding that in the future.

Q: Have there been any code audit / code review done?

  • Full audit? No! But in the past Linaro have been collaborating with Riscure trying to identify and fix potential security issues. There has also been some companies that have done audits internally and they have then shared the result with us and where relevant, we have created patches resolving the issues reported to us (see Q: Has any test lab been testing OP-TEE?).
  • Code review, yes! Every single patch going into OP-TEE has been reviewed in a pull request on GitHub. We more or less have a requirement that every patch going into OP-TEE shall at least have one “Reviewed-by” tag in the patch.
  • Third party / test lab code review, no! Again some companies have reviewed internally and shared the result with us, but other than that no (see related Q: Has any test lab been testing OP-TEE?)

Contribution

Q: How do I contribute?

Q: Where can I get help?

Q: I’m new to OP-TEE but I would like to help out, what can I do?

  • We always need help with code reviews, feel free to review any of the open OP-TEE OS Pull Requests. Please also note that there could be open pull request in the other OP-TEE gits that needs reviews too.
  • We always need help answering all the questions asked at OP-TEE OS Issues.
  • If you want to try to solve a bug, please have a look at the OP-TEE OS Bugs or the OP-TEE OS Enhancements.
  • Documentation tends to become obsolete if not maintained on regular basis. We try to do our best, but we’re not perfect. Please have a look at optee_docs and try to update where you find gaps.
  • Enable repo for the device in manifest and build (and also Platforms supported) currently not using repo.
  • If you would like to implement a bigger feature, please reach out to us (see Contact) and we can discuss what is most relevant to look into for the moment. If you already have an idea, feel free to send the proposal to us.

Interfaces

Q: Which API’s have been implemented in OP-TEE?

  • GlobalPlatform (see GlobalPlatform API for more details).
    • GlobalPlatform’s TEE Client API v1.1 specification
    • GlobalPlatform’s TEE Internal Core API v1.1 specification.
    • GlobalPlatform’s Secure Elements v1.0 (now deprecated, see git log).
    • GlobalPlatform’s Socket API v1.0 (TCP and UDP, but not TLS).
  • AOSP Keymaster (v3) and AOSP Gatekeeper (see AOSP for more details).
  • Android Verified Boot 2.0 (AVB 2.0)

Q: Which Linux kernel version supports <some OP-TEE feature>?

  • The OP-TEE Linux driver is maintained in the official Linux tree at kernel.org under drivers/tee. This is normally where you find the latest code. That being said, some platforms need minor customizations, such as device tree updates, in order to be used in the OP-TEE developer builds (manifest files). That is why the linaro-swg kernel branch optee is used in the manifest files. It is rebased onto upstream on a regular basis.

  • Older kernels may lack support for newer OP-TEE features. In order to assess in which kernel version some commit has been introduced, you may use the following shell command:

    $ cd linux
    $ git log --no-merges --oneline drivers/tee | \
      while read hash sub; do \
        name=$(git name-rev --tags --name-only $hash | sed 's/\([^~]*\)~.*/[\1]/'); \
        printf "%-20s %s %s\n" "$name" "$hash" "$sub"; \
      done
    

    The output looks like this:

    [v5.12-rc4]          6417f03132a6 module: remove never implemented MODULE_SUPPORTED_DEVICE
    [v5.12-rc1-dontuse]  67bc80975279 optee: simplify i2c access
    [v5.12-rc1-dontuse]  958567600517 tee: optee: remove need_resched() before cond_resched()
    [v5.12-rc1-dontuse]  617d8e8b347e optee: sync OP-TEE headers
    [v5.12-rc1-dontuse]  bed13b5fc4f3 tee: optee: fix 'physical' typos
    [v5.12-rc1-dontuse]  fda90b29e271 drivers: optee: use flexible-array member instead of zero-length array
    [v5.11-rc6]          dcb3b06d9c34 tee: optee: replace might_sleep with cond_resched
    [v5.10-rc6]          853735e40424 optee: add writeback to valid memory type
    [v5.11-rc1]          a24d22b225ce crypto: sha - split sha.h into sha1.h and sha2.h
    [v5.10-rc5]          be353be27874 tee: amdtee: synchronize access to shm list
    ...
    

Hardware and peripherals

Q: Can I use my own hardware IP for crypto acceleration?

  • Yes, OP-TEE has a Crypto Abstraction Layer (see Cryptographic implementation that was designed mainly to make it easy to add support for hardware crypto acceleration. There you will find information about the abstraction layer itself and what you need to do to be able to support new software/hardware “drivers” in OP-TEE.

License

Q: Under what license is OP-TEE released?

  • The software is mostly provided under the BSD 2-Clause license.
  • The TEE kernel driver is released under GPLv2 for obvious reasons.
  • xtest (optee_test) uses BSD 2-Clause for code running in secure world (Trusted Applications etc) and GPLv2 for code running in normal world (client code).

Q: GlobalPlatform click-through license

  • Since OP-TEE is a GlobalPlatform based TEE which implements the APIs as specified by GlobalPlatform one has to accept, the click-through license which is presented when trying to download the GlobalPlatform API specifications before start using OP-TEE.

Q: I’ve modified OP-TEE by using code with non BSD 2-Clause license, will you accept it?

  • That is something we deal with case by case. But as a general answer, if it does not contaminate the BSD 2-Clause license we will accept it. Reach out to us (see Contact) and we will take it from there.

Promotion

Q: I want to get my company logo on op-tee.org, how?

  • If your company has done significant contributions to OP-TEE, then please Contact us and we will do our best to include your company. Pay attention to that we will review this on regular basis and inactive supporting companies might be removed in the future again.


Source code

Q: Where is the source code?

Q: Where do I download the test suite called xtest?

Q: Where is the Linux kernel TEE driver?

  • You can find both the generic TEE framework including the OP-TEE driver included in the official Linux kernel project since v4.12. Having that said, we “buffer up” pending patches on a our Linux kernel TEE framework branch. I.e., that is where we keep new features being developed for OP-TEE. In the long run we aim to completely stop using our own branch and just send all patches to the official Linux kernel tree directly. But as of now we cannot do that.

Testing

Q: How are you testing OP-TEE?

  • There is a test suite called xtest that tests the complete TEE-solution to ensure that the communication between all architectural layers is working as it should. The test suite also tests the majority of the GlobalPlatform TEE Internal Core API. It has close to 50,000 and ever increasing test cases, and is also extendable to include the official GlobalPlatform test suite (see Extended test (GlobalPlatform tests)).
  • Every pull request in OP-TEE are built for a multitude of different platforms automatically using Azure DevOps pipelines and IBART. Please have a look there to see whether it failed building on the platform you’re using before submitting any issue about build errors.
  • For more information see optee_test.

Trusted Applications

Q: How do I write a Trusted Application (TA)?

  • Have a look at the Trusted Applications page as well as the optee_examples page. Those provides guidelines and examples on how to implement basic Trusted Applications.
  • If you want to see more advanced uses cases of Trusted Applications, then we encourage that you have a look at the Trusted Applications optee_test.

Q: Where should I put my compiled Trusted Application on the device?

  • /lib/optee_armtz, that is the default location where tee-supplicant will look for Trusted Applications.

Q: What is a Pseudo TA and how do I write one?

  • A Pseudo TA is an OP-TEE firmware service offered through the generic API used to invoke Trusted Applications. Pseudo TA interface and services all runs in TEE kernel / core context. I.e., it will have access to the same functions, memory and hardware etc as the TEE core itself. If we’re talking ARMv8-A it is running in S-EL1.

Q: How can I extend the GlobalPlatform Internal Core API?

Q: How are Trusted Applications verified?

  • Please see the section Trusted Application private/public keypair in the Porting guidelines.
  • Alternatively one can also build a Trusted Application and embed its raw binary content into the OP-TEE firmware binary. At runtime, if invoked, the Trusted Application will be loaded from the OP-TEE firmware image instead of being fetched from the normal world and authenticated in the secure world (see Early TA for more information).

Q: Is multi-core TA supported?

  • Yes, you can have two or more TAs running simultaneously. Please see also Issue#1194.

Q: Is multi-threading supported in a TA?

  • No, there is no such concept as pthreads or similar. I.e, you cannot spawn thread from a TA. If you need to run tasks in parallel, then you should probably look into running two TAs or more simultaneously and then let them communicate with each other using the TA2TA interface.

Q: How can I use or call OP-TEE from native Android (apk) applications?

  • Use the Java Native Interface (JNI).

  • First get familiar with sample_hellojni.html and make sure you can run the sample. After that, replace the C-side Implementation with for example hello_world or one of the other examples in optee_examples.

    Note

    Note that hello_world and other binaries in optee_examples are built as executables, and have to be modified to be built as a .so shared library instead so that it can be loaded by the Java-side Implementation.

  • Note that *.apk apps by default have no access to the TEE driver. See Issue#903 for details. The workaround is to disable SELinux before launching any *.apk app that calls into OP-TEE. The solution is to create/write SELinux domains/rules to allow any required access, but since this is not a TEE-related issue, it is left as an exercise for the users.

  • For a reference implementation contributed by one of our community users, see optee_android_hello_world_example.

Q: I’ve heard that there is a Widevine and PlayReady TA, how do I get access?

  • TrustedFirmware have no such implementation, but Linaro do have reference implementations for that that they share with their members who have signed the WMLA and NDA/MLA with Google and Microsoft. So the advice is to reach out to Linaro if you have questions about that.