Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/apache/incubator-teaclave-trustzone-sdk

Teaclave TrustZone SDK enables safe, functional, and ergonomic development of trustlets.
https://github.com/apache/incubator-teaclave-trustzone-sdk

confidential-computing rust secure-computing tee trusted-execution-environment trustzone

Last synced: 1 day ago
JSON representation

Teaclave TrustZone SDK enables safe, functional, and ergonomic development of trustlets.

Lists

README 

        
# Teaclave TrustZone SDK



[![License](https://img.shields.io/badge/license-Apache-green.svg)](LICENSE)

[![Release](https://img.shields.io/github/v/tag/apache/incubator-teaclave-trustzone-sdk?label=release&sort=semver)](https://github.com/apache/incubator-teaclave-trustzone-sdk/releases)

[![Homepage](https://img.shields.io/badge/site-homepage-blue)](https://teaclave.apache.org/)



Teaclave TrustZone SDK (Rust OP-TEE TrustZone SDK) provides abilities to build

safe TrustZone applications in Rust. The SDK is based on the

[OP-TEE](https://www.op-tee.org/) project which follows

[GlobalPlatform](https://globalplatform.org/) [TEE

specifications](https://globalplatform.org/specs-library/tee-internal-core-api-specification/)

and provides ergonomic APIs. In addition, it enables the capability to write

TrustZone applications with Rust's standard library (std) and many third-party

libraries (i.e., crates). Teaclave TrustZone SDK is a sub-project of [Apache

Teaclave (incubating)](https://teaclave.apache.org/).



Teaclave TrustZone SDK provides two development modes for Rust TAs: `no-std` 

(check out the `no-std` branch) and `std` (check out the `master` branch). 

We recommend using `no-std` by default. For a detailed comparison, please refer

to [Comparison](#comparison).



## Table of Contents



- [TA Development Modes](#ta-development-modes)

  - [Comparison](#comparison)

  - [Supported Examples](#supported-examples)

- [Quick Start with the OP-TEE Repo for QEMUv8](#quick-start-with-the-op-tee-repo-for-qemuv8)

- [Getting started](#getting-started)

  - [Environment](#environment)

    - [Develop with QEMUv8](#develop-with-qemuv8)

    - [Develop on other platforms](#develop-on-other-platforms)

  - [Build & Install](#build--install)

  - [Run Rust Applications](#run-rust-applications)

    - [Run Rust Applications in QEMUv8](#run-rust-applications-in-qemuv8)

    - [Run Rust Applications on other platforms](#run-rust-applications-on-other-platforms)

  - [Test](#test)

- [Documentation](#documentation)

- [Publication](#publication)

- [Contributing](#contributing)

- [Community](#community)



## TA Development Modes



### Comparison



#### `no-std`



- **Pros**:

  - Reuses standard Rust tier-1 toolchain targets (`aarch64-unknown-linux-gnu`, 

    `arm-unknown-linux-gnueabihf`).

  - Significant performance improvements.

  - Substantial reduction in binary size.

  

- **Cons**:

  - Limited support for third-party crates. In the no-std mode, Trusted Applications

   (TAs) are unable to utilize crates dependent on the standard library (std).



#### `std`



- **Pros**:

  - Enables the utilization of more third-party crates, including those requiring

    `std`, such as `serde_json` and `rustls`, which are essential for functionality.

  

- **Cons**:

  - Manual porting of `std` with infrequent updates. Currently using `std` version

   `1.56.1` and `Rust` version `nightly-2021-09-20`. (Planned to update)



### Supported Examples



- **Common**: See

  [Overview of OP-TEE Rust Examples](https://teaclave.apache.org/trustzone-sdk-docs/overview-of-optee-rust-examples/).



- **`no-std`**: Excludes `test_serde`, `test_tcp_client`, `test_udp_socket`,

  `test_message_passing_interface`, `test_tls_client`, `test_tls_server`.



## Quick start with the OP-TEE Repo for QEMUv8



Teaclave TrustZone SDK has been integrated into the OP-TEE Repo since OP-TEE

Release 3.15.0 (18/Oct/21). The aarch64 Rust examples are built and installed

into OP-TEE's default filesystem for QEMUv8. Follow [this

documentation](https://optee.readthedocs.io/en/latest/building/optee_with_rust.html)

to set up the OP-TEE repo and try the Rust examples!



UPDATES: The `no-std` TA has replaced the original `std` TAs since OP-TEE 

Release 4.1.0 (19/Jan/24).



## Getting started



### Environment



To get started with Teaclave TrustZone SDK, you could choose either [QEMU for

Armv8-A](#develop-with-qemuv8) (QEMUv8) or [other

platforms](#develop-on-other-platforms) ([platforms OP-TEE

supported](https://optee.readthedocs.io/en/latest/general/platforms.html)) as

your development environment.



#### Develop with QEMUv8



The OP-TEE libraries are needed when building Rust applications, so you should

finish the [Quick start with the OP-TEE Repo for

QEMUv8](#quick-start-with-the-op-tee-repo-for-qemuv8) part first. Then

initialize the building environment in Teaclave TrustZone SDK, build Rust

applications and copy them into the target's filesystem.



Teaclave TrustZone SDK is located in `[YOUR_OPTEE_DIR]/optee_rust/`. Teaclave

TrustZone SDK in OP-TEE repo is pinned to the release version. Alternatively,

you can try the develop version using `git pull`:



```sh

cd [YOUR_OPTEE_DIR]/optee_rust/

git pull github master

```



#### Develop on other platforms



If you are building trusted applications for other platforms ([platforms OP-TEE

supported](https://optee.readthedocs.io/en/latest/general/platforms.html)). QEMU

and the filesystem in the OP-TEE repo are not needed.  You can follow these

steps to clone the project and build applications independently from the

complete OP-TEE repo. In this case, the necessary OP-TEE libraries are

initialized in the setup process.



1. The complete list of prerequisites can be found here: [OP-TEE

Prerequisites](https://optee.readthedocs.io/en/latest/building/prerequisites.html).



``` sh

# install dependencies

sudo apt-get install android-tools-adb android-tools-fastboot autoconf \

  automake bc bison build-essential ccache cscope curl device-tree-compiler \

  expect flex ftp-upload gdisk iasl libattr1-dev libc6:i386 libcap-dev \

  libfdt-dev libftdi-dev libglib2.0-dev libhidapi-dev libncurses5-dev \

  libpixman-1-dev libssl-dev libstdc++6:i386 libtool libz1:i386 make \

  mtools netcat python-crypto python3-crypto python-pyelftools \

  python3-pycryptodome python3-pyelftools python-serial python3-serial \

  rsync unzip uuid-dev xdg-utils xterm xz-utils zlib1g-dev

```



Alternatively, you can use a docker container built with our

[Dockerfile](Dockerfile).



2. After installing dependencies or building the Docker image, fetch the source

   code from the official GitHub repository:



``` sh

# clone the project

git clone https://github.com/apache/incubator-teaclave-trustzone-sdk.git

cd incubator-teaclave-trustzone-sdk

```



### Build & Install



To build the project, the Rust environment and several related submodules are

required.



1. Run the script as follows to install the Rust environment and toolchains:



```sh

./setup.sh

```



2. Build OP-TEE libraries



- for QEMUv8:



By default, the `OPTEE_DIR` is `incubator-teaclave-trustzone-sdk/optee/`.

  OP-TEE submodules (`optee_os` and `optee_client`) will be initialized

automatically by executing:



```

./build_optee_libraries.sh optee/

```



Then the environment should be properly set up before building applications:



``` sh

source environment

```



Note: by default, the target platform is `aarch64`. If you want to build for the

`arm` target, you can setup `ARCH` before the `source environment` command:



```sh

export ARCH=arm

source environment

```



- for other platforms:



You should set these environment variables for building, e.g:



```

export CROSS_COMPILE_HOST="aarch64-linux-gnu-"

export CROSS_COMPILE_TA="arm-linux-gnueabihf-"



export TARGET_HOST="aarch64-unknown-linux-gnu"

export TARGET_TA="arm-unknown-linux-gnueabihf"



export TA_DEV_KIT_DIR=~/optee_os/out/arm-plat-vexpress/export-ta_arm32/

export OPTEE_CLIENT_EXPORT=~/optee_client/out/export/

```



3. Run this command to build all Rust examples:



``` sh

make examples

```



Or build your own CA and TA:



```sh

make -C examples/[YOUR_APPLICATION]

```



Besides, you can collect all example CAs and TAs to

`/incubator-teaclave-trustzone-sdk/out`:



```sh

make examples-install

```



### Run Rust Applications



Considering the platform has been chosen

([QEMUv8](#run-rust-applications-in-qemuv8) or

[other](#run-rust-applications-on-other-platforms)), the ways to run the Rust

applications are different.



#### Run Rust Applications in QEMUv8



1. The shared folder is needed to share CAs and TAs with the QEMU guest system.

Recompile QEMU in OP-TEE to enable QEMU VirtFS:



```sh

(cd $OPTEE_DIR/build && make QEMU_VIRTFS_ENABLE=y qemu)

```



2. Copy all the Rust examples or your own applications to the shared folder:



```sh

mkdir shared_folder

cd [YOUR_OPTEE_DIR]/optee_rust/ && make examples-install)

cp -r [YOUR_OPTEE_DIR]/optee_rust/out/* shared_folder/

```



3. Run QEMU:



```sh

(cd $OPTEE_DIR/build && make run-only QEMU_VIRTFS_ENABLE=y

QEMU_VIRTFS_HOST_DIR=$(pwd)/shared_folder)

```



4. After the QEMU has been booted, you need to mount the shared folder in the

QEMU guest system (username: root), in order to access the compiled CA/TA from

QEMU. Run the command as follows in the QEMU guest terminal:



```sh

mkdir shared && mount -t 9p -o trans=virtio host shared

```



5. Then run CA and TA as [this

documentation](https://optee.readthedocs.io/en/latest/building/optee_with_rust.html)

describes.



#### Run Rust Applications on other platforms



Copy the applications to your platform and run.



### Test



In the `tests/` directory, we offer comprehensive tests for examples. The 

applications can run on a pre-built QEMU image, independently of cloning the 

OP-TEE repo. You can compose a simple test here to validate your application.



## Documentation



- [Overview of OP-TEE Rust

  Examples](https://teaclave.apache.org/trustzone-sdk-docs/overview-of-optee-rust-examples/)

- [Debugging OP-TEE

  TA](https://teaclave.apache.org/trustzone-sdk-docs/debugging-optee-ta.md/)

- [Host API

  Reference](https://teaclave.apache.org/api-docs/trustzone-sdk/optee-teec/)

- [TA API

  Reference](https://teaclave.apache.org/api-docs/trustzone-sdk/optee-utee/)



## Publication



More details about the design and implementation can be found in our paper

published in ACSAC 2020:

[RusTEE: Developing Memory-Safe ARM TrustZone

Applications](https://csis.gmu.edu/ksun/publications/ACSAC20_RusTEE_2020.pdf).

Here is the BiBTeX record for your reference.



```bibtex

@inproceedings{wan20rustee,

    author    = "Shengye Wan and Mingshen Sun and Kun Sun and Ning Zhang and Xu

He",

    title     = "{RusTEE: Developing Memory-Safe ARM TrustZone Applications}",

    booktitle = "Proceedings of the 36th Annual Computer Security Applications

Conference",

    series    = "ACSAC '20",

    year      = "2020",

    month     = "12",

}

```



## Contributing



Teaclave is open source in [The Apache

Way](https://www.apache.org/theapacheway/),

we aim to create a project that is maintained and owned by the community. All

kinds of contributions are welcome.

Thanks to our [contributors](https://teaclave.apache.org/contributors/).



## Community



- Join us on our [mailing

  list](https://lists.apache.org/[email protected]).

- Follow us at [@ApacheTeaclave](https://twitter.com/ApacheTeaclave).

- See [more](https://teaclave.apache.org/community/).