This project provides a simple PoC implementation of a Secure Storage on top of [OP-TEE](https://optee.readthedocs.io/en/latest/general/about.html) 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](https://www.xquartz.org/) to enable x11 window forwarding on [mac](https://gist.github.com/sorny/969fe55d85c9b0035b0109a31cbcb088).

> [!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](https://github.com/linaro-swg/optee_examples) 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`