optee_examples¶

This document describes the sample applications that are included in the OP-TEE, that aim to showcase specific functionality and use cases.

For sake of simplicity, all OP-TEE example test application are prefixed with optee_example_. All of them works as standalone host and Trusted Application and can be found in separate directories.

git location¶

https://github.com/linaro-swg/optee_examples

License¶

The software is provided under the BSD 2-Clause license.

Build instructions¶

You can build the code in this git only or build it as part of the entire system, i.e. as a part of a full OP-TEE developer setup. For the latter, please refer to instructions at the build page. For standalone builds we currently support building with both CMake as well as with regular GNU Makefiles. However, since the both the host and the Trusted Applications have dependencies to files in optee_client (libteec.so and headers) as well as optee_os (TA-devkit), one must first build those and then refer to various files. Below we will show to to build the hello_world example for Armv7-A using regular GNU Make.

Configure the toolchain¶

First step is to download and configure a toolchain, see the Toolchains page for instructions.

Build the dependencies¶

Then you must build optee_os as well as optee_client first. Build instructions for them can be found on their respective pages.

Clone optee_examples¶

$ git clone https://github.com/linaro-swg/optee_examples.git

Build using GNU Make¶

Host application¶

$ cd optee_examples/hello_world/host
$ make \
    CROSS_COMPILE=arm-linux-gnueabihf- \
    TEEC_EXPORT=<optee_client>/out/export/usr \
    --no-builtin-variables

With this you end up with a binary optee_example_hello_world in the host folder where you did the build.

Trusted Application¶

$ cd optee_examples/hello_world/ta
$ make \
    CROSS_COMPILE=arm-linux-gnueabihf- \
    PLATFORM=vexpress-qemu_virt \
    TA_DEV_KIT_DIR=<optee_os>/out/arm/export-ta_arm32

With this you end up with a files named uuid.{ta,elf,dmp,map} etc in the ta folder where you did the build.

Note

For a 64-bit builds (or any other toolchain) you will need to change CROSS_COMPILE (and also use a PLATFORM corresponding to an Armv8-A configuration).

Coding standards¶

See Coding standards.

Example applications¶

acipher¶

Application name UUID

optee_example_acipher a734eed9-d6a1-4244-aa50-7c99719e7b7b

Generates an RSA key pair of specified size and encrypts a supplied string with it using the GlobalPlatform TEE Internal Core API.

aes¶

Application name UUID

optee_example_aes 5dbac793-f574-4871-8ad3-04331ec17f24

Runs an AES encryption and decryption from a TA using the GlobalPlatform TEE Internal Core API. Non secure test application provides the key, initial vector and ciphered data.

hello_world¶

Application name UUID

optee_example_hello_world 8aaaf200-2450-11e4-abe2-0002a5d5c51b

This is a very simple Trusted Application to answer a hello command and incrementing an integer value.

hotp¶

Application name UUID

optee_example_hotp 484d4143-2d53-4841-3120-4a6f636b6542

HMAC based One Time Password in OP-TEE

HMAC based One Time Passwords or shortly just ‘HOTP’ has been around for many years and was initially defined in RFC4226 back in 2005. Since then it has been a popular choice for doing two factor authentication. With the implementation here we are showing how one could leverage OP-TEE for generating such HMAC based One Time Passwords in a secure manner.

Client (OP-TEE) / Server solution¶

The most common way of using HOTP is in a client/server setup, where the client needs to authenticate itself to be able to get access to some resources on the server. In those cases the server will ask for an One Time Password, the client will generate that and send it over to the server and if the server is OK with the password it will grant access to the client.

Technically how it is working is that the server and the client needs to agree on shared key (’K’) and also start from the same counter (’C’). How that is done in practice is another topic, but RFC4226 has some discussion about it. You should at least have a secure channel between the client and the server when sharing the key, but even better would be if you could establish a secure channel all the way down to the TEE (currently we have TCP/UDP support in OP-TEE, but not TLS).

When both the server and the client knows about and use the same key and counter they can start doing client authentication using HOTP. In short what happens is that both the client and the server computes the same HOTP and the server compares the result of both computations (which should be the same to grant access). How that could work can be seen in the sequence diagram below.

In the current implementation we have OP-TEE acting as a client and the server is a remote service running somewhere else. There is no server implemented, but that should be pretty easy to add in a real scenario. The important thing here is to be able to register the shared key in the TEE and to get HOTP values from the TEE on request.

Since the current implementation works as a client we do not need to think about implementing the look-ahead synchronization window (’s’) nor do we have to think about adding throttling (which prevents/slows down brute force attacks).

Sequence diagram - Client / Server¶

../../../_images/sequence_diagram_01.png

Client / Server (OP-TEE)?¶

Even though the current implementation works as a HOTP client, there is nothing saying that the implementation cannot be updated to also work as the validating server. One could for example have a simple device (a [security token] only generating one time passwords) and use the TEE as a validating service to open up other secure services.

random¶

Application name UUID

optee_example_random b6c53aba-9669-4668-a7f2-205629d00f86

Generates a random UUID using capabilities of TEE API (TEE_GenerateRandom()).

secure_storage¶

Application name UUID

optee_example_secure_storage f4e750bb-1437-4fbf-8785-8d3580c34994

A Trusted Application to read/write raw data into the OP-TEE secure storage using the GlobalPlatform TEE Internal Core API.