Polish README.md (#361)
diff --git a/.asf.yaml b/.asf.yaml
new file mode 100644
index 0000000..65c4fcb
--- /dev/null
+++ b/.asf.yaml
@@ -0,0 +1,25 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+github:
+ description: "Apache Teaclave (incubating) SGX SDK helps developers to write Intel SGX applications in the Rust programming language, and also known as Rust SGX SDK."
+ homepage: https://teaclave.apache.org
+ labels:
+ - universal-secure-computing
+ - confidential-computing
+ - trusted-execution-environment
+ - tee
+ - sgx
+ - rust
diff --git a/Readme.md b/README.md
similarity index 88%
rename from Readme.md
rename to README.md
index 1c0f1c3..e534c50 100644
--- a/Readme.md
+++ b/README.md
@@ -1,20 +1,22 @@
-
-
-[](https://gitter.im/rust-sgx-sdk/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
-
# Teaclave SGX SDK
-The Teaclave SGX SDK (also known as the Rust SGX SDK) helps developers write Intel SGX applications in the Rust programming language. <sup>[[1]](documents/ccsp17.pdf) [[2]](https://dingelish.com/ccs19.pdf)</sup> Please read our documentation for SDK crates which can be found [here](https://teaclave.apache.org/api-docs/sgx-sdk/sgx_tstd/index.html.) or can be autogenerated with `cargo doc`.
-To help users understand our project and know how to use it, we are writing some [wiki](https://teaclave.apache.org/sgx-sdk-docs/) articles. Please contact us on our [mailing list](https://teaclave.apache.org/community/#mailing-lists) if you'd like to see other topics. We'll add it as soon as possible.
+[](LICENSE)
+[](https://teaclave.apache.org/)
-# Getting Started
-The SDK container can either be built from source or pulled from docker hub and run as a docker container.
+Apache Teaclave (incubating) SGX SDK helps developers to write Intel SGX
+applications in the Rust programming language, and also known as Rust SGX SDK.
-## Configuration
+## Getting Started
-The docker image now supports Intel ME. If you need it, please refer to the sgxtime [readme](documents/sgxtime.md) for instructions.
+The SDK container can either be built from source or pulled from docker hub and
+run as a docker container.
-## Prerequisites
+### Configuration
+
+The docker image now supports Intel ME. If you need it, please refer to the
+sgxtime [readme](documents/sgxtime.md) for instructions.
+
+### Prerequisites
* #### Docker
* #### Intel SGX OOT 2.11.0 Driver or DCAP 1.36.2 Driver
@@ -26,7 +28,7 @@
**Note**: if you are running our SDK on a machine without SGX support, you will still need the simulation versions of the Intel PSW and SDK.
-## Pulling a Pre-Built Docker Container
+### Pulling a Pre-Built Docker Container
It is assumed that the user has [correctly installed docker](https://docs.docker.com/get-docker/). We provide 5 containers:
@@ -43,7 +45,9 @@
$ docker pull baiduxlab/sgx-rust
```
To run the container, we recommend that you download our samplecode
-### Running with Intel SGX Drivers:
+
+#### Running with Intel SGX Drivers:
+
We recommend starting by using the github repository as a first volume to run the container on:
```
$ git clone https://github.com/apache/incubator-teaclave-sgx-sdk.git
@@ -74,7 +78,7 @@
```
We recommend you look at other files in the `samplecode` folder to familiarize yourself with programming in our SDK.
-### Running without Intel SGX Drivers:
+#### Running without Intel SGX Drivers:
**Note**: Intel provides a simulation mode so you can develop on regular machines, by building the enclave app using the libraries sgx_urts_sim, lsgx_uae_service_sim, sgx_trts_sim, sgx_tservice_sim.
@@ -102,11 +106,11 @@
# ./app
```
-## Building a Docker Image
+### Building a Docker Image
Make sure Intel SGX SDK is properly installed and service started on the host OS. Then `cd dockerfile` and run `docker build -t rust-sgx-docker -f Dockerfile.1604.nightly .` to build.
-# Code Samples
+## Code Samples
We provide eighteen code samples to help developers understand how to write Enclave code in Rust. These samples are located in the `samplecode` directory.
@@ -162,7 +166,7 @@
* `tcmalloc` shows how to link Rust-SGX enclave with tcmalloc (provided by Intel SGX SDK), and test its performance with different kinds of workload.
</details>
-# Tips for writing enclaves in Rust
+## Tips for writing enclaves in Rust
<details>
<summary>See tips</summary>
@@ -180,22 +184,18 @@
* For dynamic-length array, the only way is to use raw pointers in Rust. There are several functions to get/set data using raw pointers such as [`offset`](https://doc.rust-lang.org/1.9.0/std/primitive.pointer.html#method.offset) method. One can also use [`slice::from_raw_parts`](https://doc.rust-lang.org/std/slice/fn.from_raw_parts.html) to convert the array to a slice.
* For Fixed-length array, the above method is acceptable. And according to discussions in [issue 30382](https://github.com/rust-lang/rust/issues/30382) and [issue 31227](https://github.com/rust-lang/rust/issues/31227), thin-pointers (such as fixed-length array) are FFI-safe for now, but undocumented. In the sample codes, we use fixed-length arrays for passing and returning some fixed-length data.
-
-## Non-bypassable Security Paradigm (NbSP)
-
-* To achieve better security, we recommend developers to apply [Non-bypassable Security Paradigm (NbSP)](https://github.com/apache/teaclave-sgx-sdk/blob/master/documents/nbsp.pdf) to the system design and implementation.
</details>
-# Releases
-## Latest: v1.1.3
+## Pre-Apache Releases
+
+### Latest: v1.1.3
Supports Intel SGX SDK v2.12, and Rust nightly-2020-10-25. Added support to Ubuntu 20.04. **We strongly recommend users to upgrade to Intel SGX SDK v2.12 and drivers to DCAP 1.36.2 and OOT 2.11.0.** [release_notes](release_notes.md).
-
<details>
<summary>Version 1.1.2</summary>
-## v1.1.2
+### v1.1.2
Supports Intel SGX SDK v2.9.1, and Rust nightly-2020-04-07. v1.1.2 provides a handy crate `sgx_signal`, which enables signal capture. One can easily find the place where exception happens and finally triggered `ud2`. And we added `Backtrace::capture` in sgx_tstd. With the help of Intel SGX SDk v2.9.1's patch, dtor of thread local storage finally works on regular SGX thread and pthread thread. Removed sgx_core_futures since Rust is supporting `async`/`await` in `no_std` environment. Please refer to [release_notes](release_notes.md) for more details.
</details>
@@ -203,7 +203,7 @@
<details>
<summary>Version 1.1.1</summary>
-## v1.1.1
+### v1.1.1
Supports Intel SGX SDK v2.9, and Rust nightly-2020-03-12. v1.1.1 contains a bunch of bug fix and new proc macro `sgx_align` to help with aligning given structure. For LVI migigation, it only works on C/C++ parts (EDL headers/Intel's libs) and supports both two modes: `MITIGATION-CVE-2020-0551=LOAD` or `MITIGATION-CVE-2020-0551=CF`. To enable it, one need `env "MITIGATION-CVE-2020-0551=LOAD"` to set this environment variable. For detailed information, please refer to [release_notes](release_notes.md) for more details.
</details>
@@ -211,7 +211,7 @@
<details>
<summary>Version 1.1.0</summary>
-## v1.1.0
+### v1.1.0
Supports Intel SGX SDK v2.7.1, and Rust nightly-2019-11-25. v1.1.0 brings up dynamic static supports by `thread::spawn`, and almost everything of `std::sync`. Also v1.1.0 benefits from Intel SGX SDK's aligned memory allocation primitives to mitigate [INTEL-SA-00219](https://github.com/apache/incubator-mesatee-sgx/wiki/Mitigation-of-Intel-SA-00219-in-Rust-SGX). Besides, we enabled [`is_x86_feature_detected!`](https://github.com/apache/incubator-mesatee-sgx/wiki/%60is_x86_feature_detected%60-in-Rust-SGX-SDK) by parsing a hidden global CPU feature indicator initialized by Intel SGX urts/trts. And we provided Dockerfile for Fedora 27. For detailed information, please refer to [release_notes](release_notes.md) for more details.
</details>
@@ -219,7 +219,7 @@
<details>
<summary>Version 1.0.9</summary>
-## v1.0.9 Release
+### v1.0.9 Release
Supports Intel SGX SDK v2.6, and Rust nightly-2019-08-01. Bumps everything to edition. Removed third_party directory since we have all of those dependencies forked and maintained with merge bot. Since Intel SGX SDK v2.6 imports some breaking changes in global thread metata, thread local features of v1.0.9 is not works on Intel SGX SDK v2.5. EDL and common headers are changed respectively. For detailed information, please refer to [release_notes](release_notes.md) for more details.
</details>
@@ -227,7 +227,7 @@
<details>
<summary>Version 1.0.8</summary>
-## v1.0.8 Release
+### v1.0.8 Release
Supports the most recent Rust nightly (nightly-2019-05-22) and Rust stable (stable-2019-05-14). Code coverage support has been added to sgx_cov. Bug fixes in memory allocator and panicking routines. New third party libraries to support kvdb-memorydb. Please refer to [release_notes](release_notes.md) for more details.
</details>
@@ -235,7 +235,7 @@
<details>
<summary>Version 1.0.7</summary>
-## v1.0.7 Release
+### v1.0.7 Release
Supports Intel SGX SDK v2.5. Master branch supports Rust nightly build (nightly-2019-04-26) and stable branch supports Rust stable build (stable-2019-04-25). Refactored `sgx_tstd` to support `mio`. More sample codes added, including Java/Go clients for ue-ra (Thanks to @bradyjoestar)!. And we are maintaining forks of popular crates on Github organization [mesalock-linux](https://github.com/mesalock-linux). The ported crates are syncing with the original crates with the help of [Pull](https://pull.now.sh) bot and we manually port almost all tests from the original crates to test if the ported crate works well in SGX. Please refer to [release_notes](release_notes.md) for further details.
@@ -260,59 +260,61 @@
<details>
<summary>Version 1.0.6</summary>
-## v1.0.6 Release
+### v1.0.6 Release
Fix bugs in sgx_alloc, sgx_types, ucd-generate and improve sgx_tunittest. Added rust-base58. Thanks to @elichai, @cbeck88, @brenzi and @nhynes.
</details>
<details>
<summary>Version 1.0.5</summary>
-## v1.0.5 Release
+### v1.0.5 Release
This version supports Rust nightly build (nightly-2019-01-28, v1.34.0) in the master branch and the most recent stable build (stable-2019-01-16, v1.32.0) in the rust-stable branch. It supports the latest Intel SGX SDK **v2.4.0** and Ubuntu Linux 16.04+18.04. We provide support to Intel's Protected Code Loader. We provide sgx_ucrypto and sgx_crypto_helper for using SGX-style crypto primitives in untrusted app and RSA keypair serialization/deserialization in both trusted and untrusted programs. We re-organize ocall related interfaces and provide them in a new crate sgx_libc with a bunch of new ocall functions. In addition, we port net2 to SGX. Please refer to [release_notes](release_notes.md) for further details.
</details>
<details>
<summary>Version 1.0.4</summary>
-## v1.0.4 Release
+### v1.0.4 Release
This version supports Rust nightly build (nightly-2018-10-01) in the master branch and the most recent stable build (stable-2018-09-25) in the rust-stable branch. It supports the latest Intel SGX SDK **v2.3.1** and Ubuntu Linux 18.04. It now contains further third party libraries including: bit-vec, chrono, erased-serde, fxhash, nan-preserving-float, num-bigint, quick-error, raft-rs, time, webpki-roots, and yasna. Some third party libraries, like untrusted, parity-wasm and lazy-static, are removed because they support `no_std` and can be used directly from crates.io. We strongly recommend developers upgrade to v1.0.4 and use the most recent Rust release to build it due to the [Security advisory for the standard library](https://blog.rust-lang.org/2018/09/21/Security-advisory-for-std.html). Please refer to [release_notes](release_notes.md) for further details.
</details>
<details>
<summary>Version 1.0.1</summary>
-## v1.0.1 Release
+### v1.0.1 Release
This version supports the Rust nightly build (nightly-2018-07-16) in master branch and the most recent Rust stable build (stable-2018-07-10). And it supports the latest Intel SGX SDK **v2.2**. New third party libraries include: bytes, http, iovec, rust-crypto, rust-fnv and rust-threshold-secret-sharing. New code sample 'secretsharing' and 'rust-threshold-secret-sharing' is provided by @davidp94. Please refer to [release_notes](release_notes.md) for further details.
</details>
<details>
<summary>Version 1.0.0</summary>
-## v1.0.0 Release
+### v1.0.0 Release
We proudly announce v1.0.0 of rust-sgx-sdk! We port Parity's [Webassembly Interpreter](https://github.com/paritytech/wasmi) to Intel SGX and provide a full functional in-enclave [wasmi sample](samplecode/wasmi), and a [sample solution](samplecode/psi) of two-party private-set-intersection resisting side-channel attacks! From this version, we start to support most recent stable branch of Rust instead of nightly for better stability and future production use. Thus, the [stable branch](https://github.com/apache/teaclave-sgx-sdk/tree/rust-stable) of v1.0.0 supports the most recent Rust stable toolchain (1.26.0 stable-2018-05-07), while the master only supports Rust nightly toolchain of nightly-2018-04-11. Please refer to [release_notes](release_notes.md) for further details.
</details>
<details>
<summary>Version 0.9.8</summary>
-## v0.9.8 Release
+### v0.9.8 Release
This version provides security updates regards to recent Spectre attacks in Intel SGX, and supports **Rust stable (2018-03-01)** (in branch named 'rust-stable'). It contains support of [Intel SGX SDK 2.1.2](https://download.01.org/intel-sgx/linux-2.1.2/) and a series of API functions to stop speculative execution on demand. In addition, we provide a ported version of [rust-protobuf](https://crates.io/crates/protobuf) v1.4.4. Please refer to [release_notes](release_notes.md) for further details.
</details>
<details>
<summary>Version 0.9.7</summary>
-## v0.9.7 Release
+### v0.9.7 Release
This version provides a new namespace: `sgx_tstd::untrusted`, including `sgx_tstd::untrusted::fs` `sgx_tstd::untrusted::time` and `sgx_tstd::untrusted::path`, providing supports to operation to ocalls in a **untrusted** namespace. The **untrusted** namespace is always enabled no matter `untrusted_*` is set or not. We **urge** the developers to use the `sgx_tstd::untrusted` namespace to port their crates, instead of using the `untrusted_` series of features. Also, we renamed the `untrusted_net` feature to `net` for feature name unification. Please refer to [release_notes](release_notes.md) for further details.
</details>
-# License
+## Contributing
-The Apache Teaclave Rust-SGX SDK is provided under the Apache license. Please refer to the [License file](LICENSE) for details.
+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. Read this [document](CONTRIBUTING.md) to
+learn more about how to contribute. Thanks to our
+[contributors](https://teaclave.apache.org/contributors/).
-# Authors
+## Community
-Ran Duan, Long Li, Chan Zhao, Shi Jia, Yu Ding, Yulong Zhang, Huibo Wang, Yueqiang Cheng, Lenx Wei, Tanghui Chen
-
-# Contacts
-
-Yu Ding, dingelish@gmail.com
+- Join us on our [mailing list](https://lists.apache.org/list.html?dev@teaclave.apache.org).
+- Follow us at [@ApacheTeaclave](https://twitter.com/ApacheTeaclave).
+- See [more](https://teaclave.apache.org/community/).
diff --git a/documents/README.md b/documents/README.md
index 3975c5c..93cae1c 100644
--- a/documents/README.md
+++ b/documents/README.md
@@ -4,33 +4,29 @@
# Teaclave SGX SDK Documentation
-Welcome to the Teaclave Rust-SGX SDK[[1]](documents/ccsp17.pdf) [[2]](https://dingelish.com/ccs19.pdf) documentation wiki. To help users understand our project and know how to use it, we are writing some articles. Please join our [mailing list](https://teaclave.apache.org/community/#mailing-lists) if you'd like to see other topics. We'll add it as soon as possible.
-
-Please read our documentation for SDK crates which can be found [here]( https://teaclave.apache.org/api-docs/sgx-sdk/sgx_tstd/index.html) or can be autogenerated with `cargo doc`.
-
## Development
-* [Setting up your Development Environment](/documents/environment-setup.md)
-* [Rust SGX Applications in Mesalock Linux](/documents/sgx_in_mesalock_linux.md)
-* [`is_x86_feature_detected` in Teaclave SGX SDK](/documents/is_x86_feature_detected-in-sgx-sdk.md)
-* [Developing with Visual Studio Code](/documents/developing-with-vscode.md)
-* [Debugging a Local Enclave in Docker](/documents/debugging-a-local-rust-sgx-enclave-in-docker-with-sgx-gdb.md)
-* [Public Cloud Rust SGX Development](/documents/public-cloud-for-rust-sgx-development.md)
-* [The World of Forked Crates](/documents/the-world-of-forked-crates.md)
+* [Setting up your Development Environment](environment-setup.md)
+* [Rust SGX Applications in Mesalock Linux](sgx_in_mesalock_linux.md)
+* [`is_x86_feature_detected` in Teaclave SGX SDK](is_x86_feature_detected-in-sgx-sdk.md)
+* [Developing with Visual Studio Code](developing-with-vscode.md)
+* [Debugging a Local Enclave in Docker](debugging-a-local-rust-sgx-enclave-in-docker-with-sgx-gdb.md)
+* [Public Cloud Rust SGX Development](public-cloud-for-rust-sgx-development.md)
+* [The World of Forked Crates](the-world-of-forked-crates.md)
## Tutorials
-* [Acquiring Trusted Timestamp from Intel ME in SGX enclave](/documents/sgxtime.md)
-* [Performance Optimization Tips](/documents/performance-optimization-tops.md)
-* [Using `gdb` in Ubuntu 18 VSCode for Remote Debugging](/documents/setup-gdb-7.11-on-ubuntu-18.04-for-vscode---sgx-remote-debugging.md)
-* [Using `gdb` in VSCode for Graphic Developing (Not in Docker)](/documents/use-vscode---rls---rust-analysis---sgx-gdb-for-graphic-developing-(not-in-docker))
+* [Acquiring Trusted Timestamp from Intel ME in SGX enclave](sgxtime.md)
+* [Performance Optimization Tips](performance-optimization-tops.md)
+* [Using `gdb` in Ubuntu 18 VSCode for Remote Debugging](setup-gdb-7.11-on-ubuntu-18.04-for-vscode---sgx-remote-debugging.md)
+* [Using `gdb` in VSCode for Graphic Developing (Not in Docker)](use-vscode---rls---rust-analysis---sgx-gdb-for-graphic-developing-(not-in-docker))
## Security
-* [Everything about CVE-2020-5499](/documents/everything-about-cve-2020-5499.md)
-* [Non-Bypassable Security Protocol](/documents/nbsp.pdf)
-* [Mitigation of Intel SA 00219 in Rust-SGX](/documents/mitigation-of-intel-sa-00219-in-rust-sgx.md)
+* [Everything about CVE-2020-5499](everything-about-cve-2020-5499.md)
+* [Non-Bypassable Security Protocol](nbsp.pdf)
+* [Mitigation of Intel SA 00219 in Rust-SGX](mitigation-of-intel-sa-00219-in-rust-sgx.md)
## Applications
-* [Fast and Trustworthy Gradient Boosting Decision Tree](/documents/gbdt.pdf)
+* [Fast and Trustworthy Gradient Boosting Decision Tree](https://www.ieee-security.org/TC/SP2019/posters/hotcrp_sp19posters-final11.pdf)
diff --git a/documents/gbdt.pdf b/documents/gbdt.pdf
deleted file mode 100644
index c5ef7cc..0000000
--- a/documents/gbdt.pdf
+++ /dev/null
Binary files differ
diff --git a/rustsgx.png b/rustsgx.png
deleted file mode 100644
index 707ffd6..0000000
--- a/rustsgx.png
+++ /dev/null
Binary files differ
