Trusty TEE

In this document

Trusty is a set of software components supporting a Trusted Execution Environment (TEE) on mobile devices.

Trusty consists of:

  • An operating system (the Trusty OS) that runs on a processor intended to provide a TEE
  • Drivers for the Android kernel (Linux) to facilitate communication with applications running under the Trusty OS
  • A set of libraries for Android systems software to facilitate communication with trusted applications executed within the Trusty OS using the kernel drivers

Important: Trusty and the Trusty API are subject to change.

For information about the Trusty API, see the API Reference.

Uses and examples

Any TEE OS (not just Trusty) can be used for TEE implementations.

A TEE processor is typically a separate microprocessor in the system or a virtualized instance of the main processor. The TEE processor is isolated from the rest of the system using memory and I/O protection mechanisms supported by the hardware.

TEE processors have become a mainstay in today's mobile devices. The main processor on these devices is considered "untrusted" and cannot access certain areas of RAM, hardware registers and fuses where secret data (such as device-specific cryptographic keys) is stored by the manufacturer. Software running on the main processor delegates any operations that require use of secret data to the TEE processor.

The most widely known example of this in the Android ecosystem is the DRM framework for protected content. Software running on the TEE processor can access device-specific keys required to decrypt protected content. The main processor sees only the encrypted content, providing a high level of security and protection against software-based attacks.

There are many other uses for a TEE such as mobile payments, secure banking, full-disk encryption, multi-factor authentication, device reset protection, replay-protected persistent storage, wireless display ("cast") of protected content, secure PIN and fingerprint processing, and even malware detection.

Trusty provides APIs for developing two classes of applications:

  • Trusted applications or services that run on the TEE processor
  • Normal/untrusted applications that run on the main processor and use services provided by Trusted applications

Software running on the main processor can use Trusty APIs to connect to trusted applications and exchange arbitrary messages with them, just like a network service over IP. It is up to the application to determine the data format and semantics of these messages using an app-level protocol. Reliable delivery of messages is guaranteed by the underlying Trusty infrastructure (in the form of drivers running on the main processor), and the communication is completely asynchronous.

Trusted applications and services

Trusted applications run as isolated processes under the Trusty OS kernel. Each process runs in its own virtual memory sandbox utilizing the MMU capabilities of the TEE processor. The kernel schedules these processes using a priority-based, round-robin scheduler driven by a secure timer tick. In the current version of Trusty, all Trusty applications share the same priority.

Applications for the Trusty OS can be written in C/C++ (C++ support is limited), and they have access to a small C library. The main() function currently does not take any arguments. System call stubs are provided in native assembly code as part of this library, so system calls can be accessed by name.

Language and threading support

All Trusty applications are single-threaded; multithreading in Trusty userspace currently is unsupported.

Application structure

Trusty applications initialize once during load and reside in memory until the TEE processor is reset. Trusty currently does not support dynamic loading and unloading of applications.

Trusted applications are written as event-driven servers waiting for commands from other applications or from applications running on the main processor. Trusted applications can also be clients of other trusted server applications. Events described in the following API sections will be delivered to trusted applications by the Trusty kernel.

Third-party Trusty applications

Currently all Trusty applications are developed by a single party and packaged with the Trusty kernel image. The entire image is signed and verified by the bootloader during boot. Third-party application development is not supported in this version of Trusty.

Although the Trusty OS enables the development of new applications, doing so must be exercised with extreme care; each new application increases the area of the trusted computing base (TCB) of the system. Trusted applications can access device secrets and can perform computations or data transformations using them.

The ability to develop new applications that run in the TEE opens up many possibilities for innovation. However, due to the very definition of TEE, these applications cannot be distributed without some form of trust attached. Typically this comes in the form of a digital signature by an entity trusted by the user of the product on which the application runs.

Downloading and building Trusty

You can find the Trusty implementation in the Android Open Source Project (AOSP) here:
https://android-review.googlesource.com/#/admin/projects/?filter=trusty

The Trusty kernel branches on AOSP are here:
https://android.googlesource.com/kernel/common/+/android-trusty-3.10
https://android.googlesource.com/kernel/common/+/android-trusty-3.18

To make Trusty, run the following commands (assuming the Android toolchain is already in the path):

$ repo init -u https://android.googlesource.com/trusty/manifest
$ repo sync
$ make -j24 generic-arm64

You may select another supported build target from: device/*/*/project/*