teaclave-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ms...@apache.org
Subject [incubator-teaclave] branch master updated: [docs] Update docs and add rust guideline (#273)
Date Thu, 23 Apr 2020 22:33:48 GMT
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 <bob@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 @@
+# 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
+## 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
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
 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
+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

View raw message