3.13.0 16/Apr/21 OP-TEE 3.12.0 20/Jan/21 OP-TEE 3.11.0 16/Oct/20 OP-TEE 3.10.0 21/Aug/20
Total Page:16
File Type:pdf, Size:1020Kb
OP-TEE Documentation TrustedFirmware.org Apr 30, 2021 Contents 1 Getting started 3 1.1 About OP-TEE..............................................3 1.2 Coding standards.............................................4 1.3 Contribute................................................5 1.4 Contact..................................................8 1.5 License headers.............................................9 1.6 Platforms supported........................................... 10 1.7 Presentations............................................... 11 1.8 Releases................................................. 13 2 Architecture 17 2.1 Core................................................... 17 2.2 Cryptographic implementation...................................... 37 2.3 Device Tree................................................ 40 2.4 File structure............................................... 41 2.5 GlobalPlatform API........................................... 43 2.6 Libraries................................................. 53 2.7 Porting guidelines............................................ 53 2.8 Secure boot................................................ 59 2.9 Secure storage.............................................. 60 2.10 Trusted Applications........................................... 67 2.11 Virtualization............................................... 77 3 Build and run 81 3.1 Prerequisites............................................... 81 3.2 Device specific information....................................... 82 3.3 AOSP................................................... 103 3.4 Linux kernel TEE framework...................................... 106 3.5 OP-TEE gits............................................... 106 3.6 Toolchains................................................ 136 3.7 Trusted Applications........................................... 137 3.8 StandAloneMM............................................. 144 4 Debugging techniques 147 4.1 Abort dumps / call stack......................................... 147 4.2 Benchmark framework.......................................... 149 4.3 Ftrace................................................... 152 i 4.4 Gprof................................................... 153 5 Frequently Asked Questions 155 5.1 Abbreviations............................................... 157 5.2 Architecture............................................... 157 5.3 Board support.............................................. 159 5.4 Building................................................. 159 5.5 Certification and security reviews.................................... 160 5.6 Contribution............................................... 161 5.7 Interfaces................................................. 162 5.8 Hardware and peripherals........................................ 163 5.9 License.................................................. 163 5.10 Promotion................................................ 163 5.11 Security vulnerabilities.......................................... 164 5.12 Source code............................................... 164 5.13 Testing.................................................. 164 5.14 Trusted Applications........................................... 165 ii OP-TEE Documentation This is the official location for OP-TEE documentation. Contents 1 OP-TEE Documentation 2 Contents CHAPTER 1 Getting started This contains general information about OP-TEE, how to get in contact, how to contribute, how to report security issues etc. It is intended for people who are new to OP-TEE. 1.1 About OP-TEE OP-TEE is a Trusted Execution Environment (TEE) designed as companion to a non-secure Linux kernel running on Arm; Cortex-A cores using the TrustZone technology. OP-TEE implements TEE Internal Core API v1.1.x which is the API exposed to Trusted Applications and the TEE Client API v1.0, which is the API describing how to communicate with a TEE. Those APIs are defined in the GlobalPlatform API specifications. The non-secure OS is referred to as the Rich Execution Environment (REE) in TEE specifications. It is typically a Linux OS flavor as a GNU/Linux distribution or the AOSP. OP-TEE is designed primarily to rely on the Arm TrustZone technology as the underlying hardware isolation mech- anism. However, it has been structured to be compatible with any isolation technology suitable for the TEE concept and goals, such as running as a virtual machine or on a dedicated CPU. The main design goals for OP-TEE are: • Isolation - the TEE provides isolation from the non-secure OS and protects the loaded Trusted Applications (TAs) from each other using underlying hardware support, • Small footprint - the TEE should remain small enough to reside in a reasonable amount of on-chip memory as found on Arm based systems, • Portability - the TEE aims at being easily pluggable to different architectures and available HW and has to support various setups such as multiple client OSes or multiple TEEs. 1.1.1 OP-TEE components OP-TEE is divided in various components: • A secure privileged layer, executing at Arm secure PL-1 (v7-A) or EL-1 (v8-A) level. 3 OP-TEE Documentation • A set of secure user space libraries designed for Trusted Applications needs. • A Linux kernel TEE framework and driver (merged to the official tree in v4.12). • A Linux user space library designed upon the GlobalPlatform TEE Client API specifications. • A Linux user space supplicant daemon (tee-supplicant) responsible for remote services expected by the TEE OS. • A test suite (xtest), for doing regression testing and testing the consistency of the API implementations. • An example git containing a couple of simple host- and TA-examples. • And some build scripts, debugging tools to ease its integration and the development of Trusted Applications and secure services. These components are available from several git repositories. The main ones are build, optee_os, optee_client, optee_test, optee_examples and the Linux kernel TEE framework. 1.1.2 History OP-TEE was initially developed by ST-Ericsson (and later on by STMicroelectronics), but this was before OP-TEE got the name “OP-TEE” and was turned into an open source project. Back then it was a closed source and a proprietary TEE project. In 2013, ST-Ericsson obtained GlobalPlatform’s compliance qualification with this implementation, proving that the APIs were behaving as expected according to the GlobalPlatform specifications. Later on the same year (2013) Linaro was about to form Security Working Group (SWG) and one of the initial key tasks for SWG was to work on an open source TEE project. After talking to various TEE vendors Linaro ended up working with STMicroelectronics TEE project. But before being able to open source it there was a need to replace some proprietary components with open source components. For a couple of months Linaro/SWG together with engineers from STMicroelectronics re-wrote major parts (crypto library, secure monitor, build system etc), cleaned up the project by enforcing Coding standards, running checkpatch etc. June 12 2014 was the day when OP-TEE was “born” as an open source project. At that day the OP-TEE team pushed the first commit to GitHub. A bit after this Linaro also made a press release about this. That press release contains a bit more information. At the first year as an open source project it was owned by STMicroelectronics but maintained by Linaro and STMicroelectronics. In 2015 there was an ownership transfer of OP-TEE from STMicroelectronics to Linaro. In September 2019, ownership was transferred from Linaro to the TrustedFirmware.org project (see _blogpost for more information). Maintenance is a shared responsibility between the members for TrustedFirmware.org and some community maintainers representing other companies who are using OP-TEE. 1.2 Coding standards In this project we are trying to adhere to the same coding convention as used in the Linux kernel (see CodingStyle). We achieve this by running checkpatch from Linux kernel. However there are a few exceptions that we had to make since the code also follows GlobalPlatform standards. The exceptions are as follows: 1. CamelCase for GlobalPlatform types is allowed. 2. We do not run checkpatch on third party code that we might use in this project, such as LibTomCrypt, MPA, newlib etc. The reason for that and not doing checkpatch fixes for third party code is because we would probably deviate too much from upstream and therefore it would be hard to rebase against those projects later on and we don’t expect that it is easy to convince other software projects to change coding style. 3. All variables shall be initialized to a well known value in one or another way. The reason for that is that we have had potential security issues in the past that originated from not having variables initialized with a well defined value. We have also investigate various toolchain flags that are supposed to help out finding uninitialized 4 Chapter 1. Getting started OP-TEE Documentation variables. Unfortunately our conclusion is that you cannot trust the compilers here, since there are corner cases where compilers cannot reliably give a warning. Variables are initialized according to these general guidelines: • Scalars (and types like time_t which are standardized as scalars) are initialized with 0, unless another value makes more sense. • For optee_client we need maximum portability. So use { 0 } for struct types where the first element is known to be a scalar and memset() otherwise unless there is a good reason not to do so. •