This is an automated email from the ASF dual-hosted git repository. yuanz pushed a commit to branch release-v0.2.0 in repository https://gitbox.apache.org/repos/asf/incubator-teaclave-trustzone-sdk.git
commit f896ba7e851e256e42a085586aa0ac7ac07549c9 Author: Yuan Zhuang <[email protected]> AuthorDate: Sat Mar 19 00:18:20 2022 +0800 Polish documentation and fix typo (#64) --- README.md | 194 ++++++++++++++++++---- docs/README.md | 1 - docs/getting-started-with-optee-for-qemu-armv8.md | 104 ------------ optee-teec/src/error.rs | 6 +- 4 files changed, 164 insertions(+), 141 deletions(-) diff --git a/README.md b/README.md index 0c025c5..08bd56f 100644 --- a/README.md +++ b/README.md @@ -10,47 +10,169 @@ safe TrustZone applications in Rust. The SDK is based on the [GlobalPlatform](https://globalplatform.org/) TEE specifications and provides ergonomic APIs. In addition, it enables capability to write TrustZone applications with Rust's standard library and many third-party libraries (i.e., -crates). Teaclave TrustZone SDK is a sub-project of [Apache Teaclave (incubating)](https://teaclave.apache.org/). +crates). Teaclave TrustZone SDK is a sub-project of [Apache Teaclave +(incubating)](https://teaclave.apache.org/). ## Getting started -#### 1. Clone the project and install building dependencies +### Quick start with the OP-TEE Repo for QEMUv8 -The complete list of prerequisites can be found here: [OP-TEE Prerequisites](https://optee.readthedocs.io/en/latest/building/prerequisites.html). +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! -Alternatively, you can use a docker container built with our [Dockerfile](Dockerfile). +### Develop your trusted applications in Rust + +The OP-TEE libraries are needed when building Rust applications, so you should +finish the `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. + +#### 1. Update the project + +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`: + +``` +$ cd [YOUR_OPTEE_DIR]/optee_rust/ +$ git pull github master +``` + +#### 2. Install Rust environment and initialize related submodules + +* Set the OP-TEE root directory: + +``` sh +$ export OPTEE_DIR=[YOUR_OPTEE_DIR] +``` + +* Run the script as follows to install Rust environment and initialize + submodules: + +``` +$ ./setup.sh +``` + +#### 3. Set environment variables + +Before building examples, the environment should be properly setup. + +``` sh +$ source environment +``` + +By default, the target platform is `aarch64`. If you want to build for the `arm` +target, you can setup `ARCH` before `source environment`: + +```sh +$ export ARCH=arm +$ source environment +``` + +#### 4. Build Rust applications + +Run this command to build all Rust examples: + +``` sh +$ make examples +``` + +Or build your own CA and TA: + +``` +$ make -C examples/[YOUR_APPLICATION] +``` + +#### 5. Run Rust applications + +The shared folder is needed to share CAs and TAs with the QEMU guest system. +Recompile QEMU in OP-TEE to enable QEMU virtfs: + +``` +$ (cd $OPTEE_DIR/build && make QEMU_VIRTFS_ENABLE=y qemu) +``` + +Note: the path `/project/root/dir/` should be replaced as the root directory of +your local project "Teaclave TrustZone SDK". Copy all the Rust examples or your +own applications to the shared folder: + +```sh +$ mkdir shared_folder +$ (cd /project/root/dir/ && make examples-install) +$ cp -r /project/root/dir/out/* shared_folder/ +``` + +Run QEMU. + +```sh +$ (cd $OPTEE_DIR/build && make run-only QEMU_VIRTFS_ENABLE=y +QEMU_VIRTFS_HOST_DIR=$(pwd)/shared_folder) +``` + +After the QEMU has been booted, you need to mount the shared folder in 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 +``` + +Then run CA and TA as +[this documentation](https://optee.readthedocs.io/en/latest/building/optee_with_rust.html) + describes. + +## Use OP-TEE libraries as submodules + +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 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. Clone the project and install building dependencies + +The complete list of prerequisites can be found here: [OP-TEE +Prerequisites](https://optee.readthedocs.io/en/latest/building/prerequisites.html). + +Alternatively, you can use a docker container built with our +[Dockerfile](Dockerfile). ``` 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 + 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 # clone the project $ git clone [email protected]:apache/incubator-teaclave-trustzone-sdk.git $ cd incubator-teaclave-trustzone-sdk ``` -#### 2. Install Rust environment and initialize related submodules +#### 2. Set your OP-TEE directory -* By default, the `OPTEE_DIR` is `incubator-teaclave-trustzone-sdk/optee/`.If you already have [OP-TEE repository](https://github.com/OP-TEE) -cloned, you can set OP-TEE root directory: +* By default, the `OPTEE_DIR` is + `incubator-teaclave-trustzone-sdk/optee/`.OP-TEE submodules (`optee_os`, +`optee_client` and` build`) will be initialized automatically in `setup.sh`. If +you already have [OP-TEE repository](https://github.com/OP-TEE) cloned +somewhere, you can set OP-TEE root directory: ``` sh -$ export OPTEE_DIR=path/to/your/optee/root/directory +$ export OPTEE_DIR=[YOUR_OPTEE_DIR] ``` Note that your OPTEE root directory should have `build/`, `optee_os/` and `optee_client/` as sub-directory. - - -* Run the script as follows to install Rust environment and set up submodules in `optee/` and `rust/`. +* Run the script as follows to install Rust environment and set up submodules. ``` $ ./setup.sh @@ -65,7 +187,7 @@ $ source environment ``` By default, the target platform is `aarch64`. If you want to build for the `arm` -target, you can setup `ARCH` before source the environment like this: +target, you can setup `ARCH` before `source environment` like this: ```sh $ export ARCH=arm @@ -97,31 +219,35 @@ $ make examples-install #### 6. Run Rust examples -Please read detailed -[instructions](https://teaclave.apache.org/trustzone-sdk-docs/getting-started-with-optee-for-qemu-armv8/) -to run these examples on OP-TEE for QEMU. For other supported devices, please find -more documents [here](https://optee.readthedocs.io/en/latest/general/platforms.html). +Copy the applications to your platform and run. + ## Documentation -- [Getting Started with OPTEE for QEMU ARMv8](https://teaclave.apache.org/trustzone-sdk-docs/getting-started-with-optee-for-qemu-armv8/) -- [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/) +- [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). +[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. ``` @inproceedings{wan20rustee, - author = "Shengye Wan and Mingshen Sun and Kun Sun and Ning Zhang and Xu He", + 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", + booktitle = "Proceedings of the 36th Annual Computer Security Applications +Conference", series = "ACSAC '20", year = "2020", month = "12", @@ -130,13 +256,15 @@ Here is the BiBTeX record for your reference. ## Contributing -Teaclave is open source in [The Apache Way](https://www.apache.org/theapacheway/), +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]). +- 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/). diff --git a/docs/README.md b/docs/README.md index cf8bcfa..a0455cf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,6 +4,5 @@ permalink: /trustzone-sdk-docs # Teaclave TrustZone SDK Documentation -* [Getting Started with OPTEE for QEMU ARMv8](getting-started-with-optee-for-qemu-armv8.md) * [Overview of OP-TEE Rust Examples](overview-of-optee-rust-examples.md) * [Debugging OP-TEE TA](debugging-optee-ta.md) diff --git a/docs/getting-started-with-optee-for-qemu-armv8.md b/docs/getting-started-with-optee-for-qemu-armv8.md deleted file mode 100644 index c95781c..0000000 --- a/docs/getting-started-with-optee-for-qemu-armv8.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -permalink: /trustzone-sdk-docs/getting-started-with-optee-for-qemu-armv8 ---- - -# Getting Started with OP-TEE for QEMU ARMv8 - -This tutorial summarizes the necessary steps of preparing an OP-TEE enabled -QEMU environment and executing the compiled programs of our SDK. You may also -check [OP-TEE documentation](https://optee.readthedocs.io/en/latest/building/devices/qemu.html#qemu-v8) -to find more information about setting up the QEMU or introduction of OP-TEE -project. - -To run examples on the QEMU ARMv8 emulator, we need first build OP-TEE for QEMU -ARMv8. You can install dependencies with this -[instruction](https://optee.readthedocs.io/en/latest/building/prerequisites.html) -or use our [Dockerfile](https://github.com/apache/incubator-teaclave-trustzone-sdk/blob/master/Dockerfile). - -Download OP-TEE for QEMU ARMv8 source code. - -```sh -$ mkdir -p ~/bin -$ curl https://storage.googleapis.com/git-repo-downloads/repo-1 > ~/bin/repo && chmod a+x ~/bin/repo -$ export PATH=~/bin:$PATH -$ mkdir optee-qemuv8-3.14.0 && cd optee-qemuv8-3.14.0 && \ - repo init -u https://github.com/OP-TEE/manifest.git -m qemu_v8.xml -b 3.14.0 && \ - repo sync -j4 --no-clone-bundle -``` - -Build OP-TEE for QEMU ARMv8 and images. - -```sh -$ cd build -$ make -j2 toolchains && \ - make QEMU_VIRTFS_ENABLE=y CFG_TEE_RAM_VA_SIZE=0x00300000 -``` - -Create a shared folder to share example host apps and TAs with QEMU guest system. - -Note: the path `/project/root/dir/` should be replaced as the root directory of your local project "rust-optee-trustzone-sdk". -```sh -$ mkdir shared_folder -$ (cd /project/root/dir/ && make examples-install) -$ cp -r /project/root/dir/out/* shared_folder/ -``` - -Run QEMU. - -```sh -$ make run-only QEMU_VIRTFS_ENABLE=y QEMU_VIRTFS_HOST_DIR=$(pwd)/shared_folder -``` - -After the QEMU has been booted, you need to mount the shared folder in QEMU guest system (username: root), in order to access the compiled CA/TA from QEMU. - -```sh -$ mkdir shared && mount -t 9p -o trans=virtio host shared -``` - -Also, the passed-in TA should be copied to the corresponding directory for the secure-world to execute. - -```sh -$ cd shared && cp ta/*.ta /lib/optee_armtz/ -``` - -Execute host apps. - -```sh -$ cd host -$ ./hello_world -original value is 29 -inc value is 129 -dec value is 29 -Success -``` - -Note that if you are under a environment without GUI, you please comment out the following code in `qemu_v8.mk` and use `nc` instead. - -``` -diff --git a/qemu_v8.mk b/qemu_v8.mk -index 8271590..1c4a91b 100644 ---- a/qemu_v8.mk -+++ b/qemu_v8.mk -@@ -163,9 +163,9 @@ run-only: - ln -sf $(ROOT)/out-br/images/rootfs.cpio.gz $(BINARIES_PATH)/ - $(call check-terminal) - $(call run-help) -- $(call launch-terminal,54320,"Normal World") -- $(call launch-terminal,54321,"Secure World") -- $(call wait-for-ports,54320,54321) -+ # $(call launch-terminal,54320,"Normal World") -+ # $(call launch-terminal,54321,"Secure World") -+ # $(call wait-for-ports,54320,54321) - cd $(BINARIES_PATH) && $(QEMU_PATH)/aarch64-softmmu/qemu-system-aarch64 \ - -nographic \ - -serial tcp:localhost:54320 -serial tcp:localhost:54321 \ -``` - -Before start QEMU, run two `nc` to listen port `54320` and `54321`. - -``` -$ nc -l 127.0.0.1 -p 54320 -$ nc -l 127.0.0.1 -p 54321 -``` - -Then open QEMU by `make run-only`, and start by input `c`. diff --git a/optee-teec/src/error.rs b/optee-teec/src/error.rs index c8b26b9..f8a4380 100644 --- a/optee-teec/src/error.rs +++ b/optee-teec/src/error.rs @@ -68,7 +68,7 @@ pub enum ErrorKind { /// Expected data was missing. NoData = 0xFFFF000B, /// System ran out of resources. - OutOfMEmory = 0xFFFF000C, + OutOfMemory = 0xFFFF000C, /// The system is busy working on something else. Busy = 0xFFFF000D, /// Communication with a remote party failed. @@ -104,7 +104,7 @@ impl ErrorKind { "The requested operation is valid but is not supported in this implementation." } ErrorKind::NoData => "Expected data was missing.", - ErrorKind::OutOfMEmory => "System ran out of resources.", + ErrorKind::OutOfMemory => "System ran out of resources.", ErrorKind::Busy => "The system is busy working on something else.", ErrorKind::Communication => "Communication with a remote party failed.", ErrorKind::Security => "A security fault was detected.", @@ -157,7 +157,7 @@ impl Error { raw::TEEC_ERROR_NOT_IMPLEMENTED => ErrorKind::NotImplemented, raw::TEEC_ERROR_NOT_SUPPORTED => ErrorKind::NotSupported, raw::TEEC_ERROR_NO_DATA => ErrorKind::NoData, - raw::TEEC_ERROR_OUT_OF_MEMORY => ErrorKind::OutOfMEmory, + raw::TEEC_ERROR_OUT_OF_MEMORY => ErrorKind::OutOfMemory, raw::TEEC_ERROR_BUSY => ErrorKind::Busy, raw::TEEC_ERROR_COMMUNICATION => ErrorKind::Communication, raw::TEEC_ERROR_SECURITY => ErrorKind::Security, --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
