You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@teaclave.apache.org by ms...@apache.org on 2020/04/23 22:33:48 UTC
[incubator-teaclave] branch master updated: [docs] Update docs and
add rust guideline (#273)
This is an automated email from the ASF dual-hosted git repository.
mssun pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-teaclave.git
The following commit(s) were added to refs/heads/master by this push:
new bdca4be [docs] Update docs and add rust guideline (#273)
bdca4be is described below
commit bdca4be0a5ab19c375f5c9f452dff5e3c96c9255
Author: Mingshen Sun <bo...@mssun.me>
AuthorDate: Thu Apr 23 15:33:39 2020 -0700
[docs] Update docs and add rust guideline (#273)
* [docs] Update docs and add rust guideline
* [docs] Update README in the tests directory
---
README.md | 2 +-
docs/README.md | 7 +++-
docs/rust-guideline.md | 53 +++++++++++++++++++++++++++++++
docs/{threat_model.md => threat-model.md} | 33 ++++++++++++-------
tests/README.md | 20 +++++++++---
5 files changed, 98 insertions(+), 17 deletions(-)
diff --git a/README.md b/README.md
index bf168d0..a3ec79c 100644
--- a/README.md
+++ b/README.md
@@ -36,7 +36,7 @@ platform, making computation on privacy-sensitive data safe and simple.
### Design
-- [Threat Model](docs/threat_model.md)
+- [Threat Model](docs/threat-model.md)
- [Mutual Attestation: Why and How](docs/mutual-attestation.md)
## Contributing
diff --git a/docs/README.md b/docs/README.md
index d8f8d46..9989ef7 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1 +1,6 @@
-docs
+# Teaclave Documentation
+
+- [My First Function](my-first-function.md)
+- [Threat Model](threat-model.md)
+- [Rust Development Guideline](rust-guideline.md)
+- [Mutual Attestation: Why and How](mutual-attestation.md)
diff --git a/docs/rust-guideline.md b/docs/rust-guideline.md
new file mode 100644
index 0000000..9b8e04e
--- /dev/null
+++ b/docs/rust-guideline.md
@@ -0,0 +1,53 @@
+# Rust Development Guideline
+
+This doc defines some guidelines for developing Teaclave in Rust.
+
+## Style
+
+We use `rustfmt` and `clippy` to format and lint all Rust code. Mostly, we use
+the default configurations, but there are a couple of custom settings and lint
+exceptions. The exceptions should be defined along with the code. Our CI will
+check the format/lint issues and deny all warnings by default. Simply run `make
+format` to format all code and `make CLP=1` to lint code before submitting a PR.
+If you still have some doubts of the `clippy` error, feel free to point out and
+add an exception.
+
+## Elegant APIs
+
+Elegantly designed functions and APIs will make the project readable and
+user-friendly. Basically, we follow naming conventions and API design patterns
+of Rust standard library. There's no official guideline, but here are several
+articles or docs for reference:
+
+ - [Rust API guidelines](https://rust-lang.github.io/api-guidelines/)
+ - [Rust Design Patterns](https://github.com/rust-unofficial/patterns)
+ - [Elegant Library APIs in Rust](https://deterministic.space/elegant-apis-in-rust.html#what-makes-an-api-elegant)
+
+## Unsafe Rust
+
+Using unsafe Rust is extremely dangerous, and may break Rust's strong
+memory-safety guarantees. Therefore, we want to keep unsafe Rust as minimal as
+possible. Sometime (very rare) using unsafe Rust can significant improve
+performance, the unsafe code should *well documented* and *explain the
+rationales*. For contributors and reviewers, pay attention to the unsafe code
+and carefully check whether the pre-conditions and post-conditions are still
+hold.
+
+## Error Handling
+
+Using `unwrap` or `expect` to get a value from an optional type may introduce
+runtime panic. Therefore, properly using the error handling mechanism provided
+by Rust can make the system robust and clean. In some cases, optional value can
+never be `None` internally, `unwrap` can be used with a comment explaining the
+assumptions and reasons. The same rule also applies to `panic` and similar
+functions which may cause runtime panic. One exception is to use `unwrap` and
+`expect` in tests, while `expect` is better because it will show a message to
+help debugging.
+
+## Third-Party Crates
+
+To ensure the security, stability and compatibility of upstream crates, all
+third-party crates (especially for ported SGX-compatible crates) used in
+Teaclave are vendored in the `third_party` directory. Please refer to the
+`crates-sgx` and `crates-io` repo and choose specific versions of vendored
+crates.
diff --git a/docs/threat_model.md b/docs/threat-model.md
similarity index 50%
rename from docs/threat_model.md
rename to docs/threat-model.md
index 2d0e170..4251da3 100644
--- a/docs/threat_model.md
+++ b/docs/threat-model.md
@@ -9,6 +9,10 @@ not, are untrusted. This includes:
- Function provider
- Other data providers
+Specifically, most hardware (memory, disk, motherboard, etc.), operating system
+(both kernel and software in userland), network channels, and provider employees
+are untrusted.
+
Consider the following scenario. A small business needs to employ image
classification techniques in its daily production. However, the business does
not have the capabilities to train a high-quality machine learning model, nor
@@ -25,17 +29,24 @@ from company B, and use the deep learning inference engine provided by company
C. None of these parties need to trust another, yet the computation can commence
with everyone's privacy respected.
-In the settings above, the root of trust converges to Intel and its SGX-enabled
-CPU chips. Before the computation starts, Teaclave is booted as a secure SGX
-enclave on one of these CPUs owned by the cloud service provider. After that,
-each party can **remotely** attest the authenticity of the hardware and the
-integrity of Teaclave platform. Private data are securely provisioned to the
-Teaclave enclave only if the attestation passes. After the provision, no
-privileged software is able to access the memory content owned by the enclave
-from outside.
+In the settings above, the root of trust converges to the enclave manufactures
+(i.e., Intel) and its SGX-enabled CPU chips. Before the computation starts,
+Teaclave is booted as a secure SGX enclave on one of these CPUs owned by the
+cloud service provider. After that, each party can **remotely** attest the
+authenticity of the hardware and the integrity of Teaclave platform through
+attestation service (e.g., Intel Attestation Service). Private data are securely
+provisioned to the Teaclave enclave only if the attestation passes. After the
+provision, no privileged software is able to access the memory content owned by
+the enclave from outside.
The remote attestation functionality implemented by Teaclave is augmented from
-the method described by an Intel [white paper](https://arxiv.org/abs/1801.05863).
-The complicated structure of Teaclave requires additional work for remote
-attestation, which is explained in details via a separate
+the method described by a [white paper](https://arxiv.org/abs/1801.05863). In a
+nutshell, enclaves in Teaclave will establish trusted channel on attested TLS
+for communication. The complicated structure of Teaclave requires additional
+work for remote attestation, which is explained in details via a separate
[documentation](mutual_attestation.md).
+
+Side channels are out of scope for current Teaclave's implementation. While we
+acknowledge that existing enclaves may be vulnerable to various kinds of side
+channel attacks, we will try our best to mitigate existing attacks by adopting
+software hardening.
diff --git a/tests/README.md b/tests/README.md
index 8407b93..7bb0a0d 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -1,10 +1,22 @@
# Tests in Teaclave
+This directory contains all tests in Teaclave including unit tests, integration
+tests, functional tests and some test fixtures.
+
+## Run Tests
+
+To run all tests with our build system:
+
+```
+$ make run-tests
+```
+
+You can also run tests separately:
+
```
-make run-tests
-make run-unit-tests
-make run-integration-tests
-make run-functional-tests
+$ make run-unit-tests
+$ make run-integration-tests
+$ make run-functional-tests # this will start all services in the background automatically
```
## Directory Structure
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@teaclave.apache.org
For additional commands, e-mail: commits-help@teaclave.apache.org