README.md
1# Teaclave TrustZone SDK
2
3Teaclave TrustZone SDK (Rust OP-TEE TrustZone SDK) provides abilities to build
4safe TrustZone applications in Rust. The SDK is based on the
5[OP-TEE](https://www.op-tee.org/) project which follows
6[GlobalPlatform](https://globalplatform.org/) TEE specifications and provides
7ergonomic APIs. In addition, it enables capability to write TrustZone
8applications with Rust's standard library and many third-party libraries (i.e.,
9crates). Teaclave TrustZone SDK is a sub-project of [Apache Teaclave (incubating)](https://teaclave.apache.org/).
10
11## Getting started
12
13To get started, you need to clone the project, initialize related submodules,
14and install building dependencies (The complete list of prerequisites can be found here: [OP-TEE Prerequisites](https://optee.readthedocs.io/en/latest/building/prerequisites.html)).
15Alternatively, you can use a docker container built with our [Dockerfile](Dockerfile).
16
17``` sh
18# install dependencies
19$ sudo apt-get install android-tools-adb android-tools-fastboot autoconf \
20 automake bc bison build-essential ccache cscope curl device-tree-compiler \
21 expect flex ftp-upload gdisk iasl libattr1-dev libc6:i386 libcap-dev \
22 libfdt-dev libftdi-dev libglib2.0-dev libhidapi-dev libncurses5-dev \
23 libpixman-1-dev libssl-dev libstdc++6:i386 libtool libz1:i386 make \
24 mtools netcat python-crypto python3-crypto python-pyelftools \
25 python3-pycryptodome python3-pyelftools python-serial python3-serial \
26 rsync unzip uuid-dev xdg-utils xterm xz-utils zlib1g-dev
27
28# clone the project
29$ git clone git@github.com:apache/incubator-teaclave-trustzone-sdk.git
30$ cd incubator-teaclave-trustzone-sdk
31# initialize related submodules and install Rust environment
32$ ./setup.sh
33```
34
35By default, the `OPTEE_DIR` is `incubator-teaclave-trustzone-sdk/optee/`.
36``` sh
37# initialize OP-TEE submodule
38$ git submodule update --init -- optee
39```
40If you already have [OP-TEE repository](https://github.com/OP-TEE)
41cloned, you can set OP-TEE root directory:
42
43``` sh
44$ export OPTEE_DIR=path/to/your/optee/root/directory
45```
46
47Note that your OPTEE root directory should have `build/`, `optee_os/` and
48`optee_client/` as sub-directory.
49
50Before building examples, the environment should be properly setup.
51
52``` sh
53$ source environment
54```
55
56By default, the target platform is `aarch64`. If you want to build for the `arm`
57target, you can setup `ARCH` before source the environment like this:
58
59```sh
60$ export ARCH=arm
61$ source environment
62```
63
64Then, download ARM toolchains and build OP-TEE libraries. Note that the OP-TEE
65target is QEMUv8, and you can modify the Makefile to other targets accordingly.
66
67``` sh
68$ make optee
69```
70
71At last, you can get started with our examples.
72
73``` sh
74$ make examples
75```
76
77Please read detailed
78[instructions](https://teaclave.apache.org/trustzone-sdk-docs/getting-started-with-optee-for-qemu-armv8/)
79to run these examples on OP-TEE for QEMU. For other supported devices, please find
80more documents [here](https://optee.readthedocs.io/en/latest/general/platforms.html).
81
82## Contributing
83
84Teaclave TrustZone SDK is open source in [The Apache Way](https://www.apache.org/theapacheway/),
85we aim to create a project that is maintained and owned by the community. All
86kinds of contributions are welcome. Thanks to our [contributors](https://teaclave.apache.org/contributors/).
87
88## Publication
89
90More details about the design and implementation can be found in our paper
91published in ACSAC 2020:
92[RusTEE: Developing Memory-Safe ARM TrustZone Applications](https://csis.gmu.edu/ksun/publications/ACSAC20_RusTEE_2020.pdf).
93Here is the BiBTeX record for your reference.
94
95```
96@inproceedings{wan20rustee,
97 author = "Shengye Wan and Mingshen Sun and Kun Sun and Ning Zhang and Xu He",
98 title = "{RusTEE: Developing Memory-Safe ARM TrustZone Applications}",
99 booktitle = "Proceedings of the 36th Annual Computer Security Applications Conference",
100 series = "ACSAC '20",
101 year = "2020",
102 month = "12",
103}
104```
105
106## License
107
108Teaclave TrustZone SDK is distributed under the Apache License (Version 2.0).
109See [LICENSE](LICENSE) for details.
110