83 lines
4.4 KiB
Markdown
83 lines
4.4 KiB
Markdown
|
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`
|
|||
|
|
|