The first post in this series was a primer to basic terms and concepts in the context of Trusted Execution Environments using Arm TrustZone. We also saw answers to some questions that any beginner may have. Towards the end of the post, we saw an introduction to the OP-TEE project and why someone should consider using OP-TEE to implement a Trusted Execution Environment (TEE) for their system.
In case you missed it, this is where you could find the first part!
In this post, we talk more about OP-TEE. More specifically, we talk about the various components of OP-TEE and their roles. We also touch upon the GlobalPlatform Trusted Execution Environment (TEE) specification and how it is related to OP-TEE.
You can click on any of the below items to navigate this post.
OP-TEE – Components
As we saw in the last post, Linaro has been maintaining OP-TEE since 2014. Github has been the home of OP-TEE for a very long time and is a very actively maintained software offering.
The below diagram shows the various components of the OP-TEE project.
Let us now take a look at what each component’s role in the OP-TEE project is.
OP-TEE OS
This repository contains the source code for the operating system for the trusted world. The OP-TEE OS can execute TAs or Trusted Applications that will be executing secure software securely.
Why do we need a TEE? A very typical use-case of a Trusted Application running within a TEE is to perform cryptographic operations – especially those that involve using a private key to sign or decrypt sensitive payloads. Other use-cases require secure key storage as well as secure data storage. Another evolving requirement is the very act of protecting a sensitive algorithm that is an intellectual property that you want to protect. DRM (Digital Rights Management) is another upcoming use-case.
What can the OP-TEE OS do you you as a developer? Let us look at this from the developer’s angle. If one had to guess what the OP-TEE OS can do for you, one only needs to look at what all of these TAs require in common.
- Memory Segregation: They would need a way to establish memory boundaries between the rich world and the trusted world.
- Inter-world Communication: They would need a way to receive data, interrupts and events from the rich world to know why, how and what to do.
- Crypto and Storage: They would need a way to facilitate the cryptography and the secure storage stuff.
- Standardised API: They need an inter-operable implementation of the software protocol between the rich and trusted world. Also, there needs to be a way to specify how a TA should respond to a requested functionality so that the rich world can parse it.
- Authenticated TA Execution: Considering we will be executing an application in the trusted world, one would want that the TA itself should be trusted. Authenticating a TA before passing control to it would be a fantastic feature.
OP-TEE OS supports all of the above requirements. Of course, OP-TEE OS can do a lot more for you as a developer. However, items in the above list are at the heart of a lot of TAs and what they need!
OP-TEE Client
This repository contains the source code for implementing the TEE client. More specifically, one of the build outputs of this client code is a TEE client library which should be linked to the rich world application that wants to talk to the TEE. The rich world application talks to the TEE running with the OPTEE-OS through a daemon application named the tee-supplicant. This tee-supplicant daemon has to be launched just once and can facilitate communication between multiple rich world applications to multiple TAs.
The below diagram illustrates the interactions that the OS and the Client code facilitate.
Note: In the below diagram, the linuxdriver is built using the mainlined driver rather than the (now) deprecated linuxdriver repo in the OP-TEE project.
OP-TEE Test Suite
This repository contains a comprehensive test suite to “test” your implementation of OP-TEE for your platform. This test suite runs thousands of tests and sub-tests. More the number of successes, better is your implementation of the TEE on your chosen platform. Ideally, 100% success of the test suite indicates that your implementation of OP-TEE on the platform is correct and can be used for application development.
Do contribute back to the OP-TEE project so that others can benefit from your port on the new platform!
Linux Driver
This repository contains the linux driver that would enable the rich world to talk to the trusted world.
This is now DEPRECATED so you should not use it. Linaro directly upstreams the latest driver code to the mainline linux kernel.
OP-TEE Documentation
This repository contains the documentation as well as the scripts required to build the documentation in the form of HTML pages that you can refer to during your development. It would be very prudent to build the documentation before doing anything else with the source code.
The steps to build the documentation are given in the official OP-TEE documentation here!
OP-TEE Website
As a developer, you don’t care too much about this repository. It contains the the Jekyll static website files for OP-TEE.org website.
Build
This repository contains the makefiles and scripts that you would need to do the actual build for a particular platform for which you want to build OP-TEE for. This is perhaps the most critical piece of software for you as a developer. Once you have selected the platform for your OP-TEE build, it is a good idea to come to this repository and check out what the Makefile and build process for your platform would look like.
We will analyse the build process for a given platform in a future post.
Manifest
✅ All developers – especially beginners – should START here! ✅
This repository contains the various manifest configurations for all official platforms supported by Linaro. These manifest configurations not only contain details about where to find the OP-TEE source code but also any other third-party code that would be necessary to generate a working image for that platform.
We will use the manifest repo in our next post to build a working OP-TEE image for the Raspberry Pi 3 platform.
Global Platform TEE Specification
In the OPTEE-OS section above, we saw that one of the key requirements is to have inter-operability of the implementation. Since the OS offers so many myriad functionalities and services, there has to be a well-defined way for requesting and consuming these functionalities and services.
Global Platform is a global body that comes out with certification and specifications for a large number of industry standards and trends. For the TEE implementation, Global Platform creates and maintains specifications for TEE OS and Client implementations. These specifications talk about everything from variable types, data structures, functions as well as expected return values in case of successful and failed operations. There are also recommendations made for handling unused, unimplemented or completely absent features. Check out the Global Platform specifications for TEE here!
As mentioned in the OP-TEE documentation, OP-TEE project implements the TEE Internal Core API v1.1.x (OS) and the TEE Client API v1.0 (Client).
Conclusion
In this post, we learnt about the organisation of the OP-TEE project and also about the roles of the individual components. We also learnt about the interactions between the OS and the Client at a high-level. Finally, we talked a little bit about Global Platform and which specification versions are implemented in the OP-TEE OS and Client source code.
In the next post, we will create our first ever linux image with OP-TEE support. We will choose the ever-so-popular Raspberry Pi platform to build this image for and also execute the test suite once the image has been booted up. See you in the next post!