custom-tee-storage/README.md

This project provides a simple PoC implementation of a Secure Storage on top of OP-TEE TrustZone based technology.

Main functionality

The project consists of two modules: Trusted Application and Normal World client.

Trusted Application

1. Generate RSA key pair.
2. Serialize / Deserialize RSA key pair into Secure Storage for use across sessions. Access to multiple RSA key pairs is implemented with help of TAG identifiers.
3. A special run-time provided PIN is used for further RSA key pair protection. Provided PIN is used by Trusted Application to derive SessionKey, which is used for encryption / decryption of RSA key pair matherial stored in Secure Storage.
4. RSA key pair data is never exposed outside of Trusted Application.
5. Assuming that correct PIN is known, Client Application can use RSA key pair TAG to encrypt / decrypt arbitrary data.

Normal World client application

1. Provides functional demo for APIs exposed by Trusted Application.

Build instructions

Usually, access to ARM TrustZone powered device is necessary to see GP-TEE based APIs in action. This project benefits heavily from virtualization techniques like Docker and Qemu.

1 Prepare build environment

Run build-docker.sh script.

This operation might take several hours to finish. It will create Ubuntu based container, will install all necessary build tools and dependancies. Lastly, it will git clone OP-TEE repository with ARMv8 build flavour. Check Dockerfile for actual list of performed actions.

2 Execute build environment

Use run-docker.sh script. The script will:

• map src folder bliq_storage inside build environment
• use X11 window forwarding technique, to map two cli named Normal World and Secure World from Docker container onto your host OS

If all went well, you will end up inside an instance of Ubuntu dev environment with cli interface similar to root@80e6b6f27bef:/optee/build#.

X11 window forwarding

Use XQuartz to enable x11 window forwarding on mac.

[!NOTE] Be ware You will always have to run xhost + after a restart of X11 as this is not a persistent setting.

3 Build and run demo application

Typing make run in /optee/build. Will start build for Secure and Normal world parts of OP-TEE OS. After successful build qemu emulator will be executed. Press c to proceed with virtual device execution. On a first run you might need to type boot in Normal World console to start boot process.

After the boot finishes, use Normal World console window to login as root. Then simply type bliq_storage to execute demo app, which was build directly from sources.

Other OP-TEE demo applications are also available. Use tab-key to assist with typing.

Source code overview

bliq_storege\ta

This folder contains sources for the Trusted Part of Bliq Storage application. Check header files to explore high level API exposed by project submodules.

bliq_storage_ta.c

Main entry point for the Trusted Application. Provides high level implementation for the main commands:

• Create Key
• Delete Key
• Check Key
• Encrypt
• Decrypt

It is also worth mentioning, that PIN-derived AES key (which is used for RSA key pair data encryption) lives in Session context, see TA_OpenSessionEntryPoint()

operations.c

Handles AES PIN derivation API, as well as AES encryption / decryption functions for RSA key pair protection.

key_pair.c

Incapsulates set of APIs of underlined GP-TEE APIs, necessary for RSA key pair creating and usage as a handy trunsient object. It also provides endpoints for RSA key-pair encryption and decryption of arbitrary data.

Two functions kp_serialize() and kp_deserilize() might be seen as the sole hard of an entire project. Since they are used for storing / re-storing RSA key pair data* into / from* a flat buffer. The whole application might be seen as a set of derivative / supportive operations build around / on top of these two functions.

bliq_storage/host/main.c

A simple TZ client application, showcasing communication between Normal World and Trusted World applications. A particular use case implementation of APIs defined by bliq_storage\ta\include\bliq_storage_ta.h