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: Polish and improve documentation (#315)
Date Mon, 25 May 2020 23:31:49 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 87524d5  Polish and improve documentation (#315)
87524d5 is described below

commit 87524d53e244f8b1176c75751d078e663ef12881
Author: Mingshen Sun <bob@mssun.me>
AuthorDate: Mon May 25 16:31:41 2020 -0700

    Polish and improve documentation (#315)
---
 CONTRIBUTORS.md       | 56 +++++++++++++++++++++++++++++++++++++--------------
 README.md             |  8 +++++++-
 config/README.md      |  4 +++-
 executor/README.md    |  5 +++++
 function/README.md    | 24 ++++++++++++++++++++++
 services/README.md    | 15 ++++++++------
 tests/README.md       |  6 +++++-
 third_party/README.md | 40 +++++++++++++++++-------------------
 8 files changed, 112 insertions(+), 46 deletions(-)

diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
index c8709cd..13bc525 100644
--- a/CONTRIBUTORS.md
+++ b/CONTRIBUTORS.md
@@ -13,18 +13,21 @@ Everyone is more than welcome to contribute and make the project better.
 Teaclave is now part of the Apache Incubator. We are fortunate to have the
 following mentors.
 
-- Felix Cheung	
-- Furkan Kamaci	
-- Jianyong Dai	
-- Luciano Resende	
-- Matt Sicker	
+- Felix Cheung
+- Furkan Kamaci
+- Jianyong Dai
+- Luciano Resende
+- Matt Sicker
 - Zhijie Shen
 
 ## Committers
 
 Committers are people who have made substantial contribution to the project and
-being active. Podling Project Management Committee (PPMC) helps to govern the
-project and is directly responsible for the oversight of Teaclave.
+being active. In committers, the role of
+[Podling Project Management Committee](https://incubator.apache.org/guides/ppmc.html)
+(PPMC) is to help to govern the project and is directly responsible for the
+oversight of Teaclave. Please contact the community if you'd like to become a
+member of regular committers or PPMC of Teaclave.
 
 - [Mingshen Sun](https://github.com/mssun) (PPMC)
 - [Pei Wang](https://github.com/uraj) (PPMC)
@@ -38,11 +41,34 @@ project and is directly responsible for the oversight of Teaclave.
 
 ## Contributors
 
-- [Full list of contributors](https://github.com/apache/incubator-teaclave/graphs/contributors)
(please also add yourself to the list below)
-- [Hongbin Mao](https://github.com/hello2mao)
-- [Meng Yang](https://github.com/m3ngyang)
-- [Sammy](https://github.com/sammyne)
-- [T0day](https://github.com/hi-T0day)
-- [devashishdxt](https://github.com/devashishdxt)
-- [luoyanhua2011](https://github.com/luoyanhua2011)
-- [zEqueue](https://github.com/z1queue)
+Teaclave is a community project and is very thankful for the many community
+contributions it receives.
+
+List of external contributors of Teaclave and Teaclave SGX SDK (in alphabetical order):
+  - [Akhil Velagapudi](https://github.com/akhilles)
+  - [David Phan](https://github.com/davidp94)
+  - [Elichai Turkel](https://github.com/elichai)
+  - [Greg Kapka](https://github.com/gskapka)
+  - [Hongbin Mao](https://github.com/hello2mao)
+  - [Jackson Owens](https://github.com/jbowens)
+  - [Jimmy Casey](https://github.com/jimmycasey)
+  - [Jun Jiang](https://github.com/jasl)
+  - [LookForAdmin](https://github.com/60ke)
+  - [Meng Yang](https://github.com/m3ngyang)
+  - [Nick Hynes](https://github.com/nhynes)
+  - [Sammy](https://github.com/sammyne)
+  - [Shi Wenbin](https://github.com/bradyjoestar)
+  - [Sythanos](https://github.com/sythanos)
+  - [T0day](https://github.com/hi-T0day)
+  - [akoskinas](https://github.com/akoskinas)
+  - [devashishdxt](https://github.com/devashishdxt)
+  - [garbageslam](https://github.com/garbageslam)
+  - [lhf](https://github.com/EighteenZi)
+  - [luoyanhua2011](https://github.com/luoyanhua2011)
+  - [piotr-roslaniec](https://github.com/piotr-roslaniec)
+  - [volcano](https://github.com/volcano0dr)
+  - [zEqueue](https://github.com/z1queue)
+
+More people tracked in GitHub:
+  - [Teaclave](https://github.com/apache/incubator-teaclave/graphs/contributors)
+  - [Teaclave SGX SDK](https://github.com/apache/incubator-teaclave-sgx-sdk/graphs/contributors)
diff --git a/README.md b/README.md
index adb6a2a..e0ee3f3 100644
--- a/README.md
+++ b/README.md
@@ -47,17 +47,23 @@ platform, making computation on privacy-sensitive data safe and simple.
 - [Teaclave Services](services)
 - [Teaclave Worker](worker)
 - [Function Executors](executor)
+- [Built-in Functions](function)
 - [Configurations in Teaclave](config)
 - [Data Center Attestation Service](dcap)
+- [Command Line Tool](cli)
 - [Keys and Certificates](keys)
 - [Dockerfile and Compose File](docker)
+- [Test Harness and Test Cases](tests)
+- [Third-Party Dependency Vendoring](third_party)
 
 ## Contributing
 
 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.
+kinds of contributions are welcome. Thanks to our [contributors](CONTRIBUTORS.md).
 
 ## Community
 
 - 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](COMMUNITY.md).
diff --git a/config/README.md b/config/README.md
index 1d7eec6..7ab0591 100644
--- a/config/README.md
+++ b/config/README.md
@@ -17,7 +17,9 @@ certificate of attestation service used for verifying attestation report,
 auditors' public keys for verification of enclave information, and topological
 graph of connections between services for mutual attestation. More detailed
 explanation of configurations can be seen in the
-[`build.config.toml`](build.config.toml) file.
+[`build.config.toml`](build.config.toml) file. We also implement a
+[`config_gen`](config_gen) tool to generate hard-coded configurations in Rust
+from the user-defined config in TOML at compilation time.
 
 Note that it is very *important* to define these configurations in build time,
 because they are part of Teaclave's *trusted computing base* (TCB) and will be
diff --git a/executor/README.md b/executor/README.md
index 774eb1e..5e1369b 100644
--- a/executor/README.md
+++ b/executor/README.md
@@ -20,3 +20,8 @@ In Teaclave, there are two executors to native and Python functions.
 - **MesaPy Executor**: The MesaPy executor provides a Python interpreter in SGX.
   User-defined Python functions can be executed in the MesaPy executor. The
   executor also provides interfaces to fetch and store data through the runtime.
+
+To add a new executor, you can implement the `TeaclaveExecutor` trait (basically
+implement the `execute` function). Then, register the executor in the Teaclave
+worker. At last, the execution service will dispatch functions to the specific
+executor.
diff --git a/function/README.md b/function/README.md
new file mode 100644
index 0000000..10938ee
--- /dev/null
+++ b/function/README.md
@@ -0,0 +1,24 @@
+---
+permalink: /function
+---
+
+# Built-in Functions
+
+Since Teaclave is a FaaS-like platform, users can define and register customized
+functions (e.g., written in Python). To make data computation more easier and
+faster (in native speed), the platform also provide some commonly used functions
+written in Rust. We call them built-in functions. These functions can be
+selectively compiled in the *built-in executor* with a "builtin" prefix in the
+function names. Users can selectively invoke these build-in functions by their
+names.
+
+Currently, we have these built-in functions:
+  - `builtin-echo`: Return the original input message.
+  - `builtin-gbdt-train`: Use input data to train a GBDT model.
+  - `builtin-gbdt-predict`: GBDT prediction with input model and input test data.
+  - `bulitin-logistic-regression-train`: Use input data to train a LR model.
+  - `builtin-logistic-regression-predict`: LR prediction with input model and input test
data.
+  
+The function arguments are in JSON format and can be serialized to a Rust struct
+very easily. You can learn more about supported arguments in the implementation
+of a specific built-in function.
diff --git a/services/README.md b/services/README.md
index 0d5efda..b4c63d2 100644
--- a/services/README.md
+++ b/services/README.md
@@ -28,8 +28,10 @@ a safe and secure FaaS platform.
   function, execution data, and task information in the platform. Here, we
   deploy a key-value database (an implementation of LevelDB) in TEE and use
   protected file system (secured by the enclave) for data persistence.
-- **Access Control Service**: Provides a flexible access control configurations
-  to support access control rules for multi-party secure computation.
+- **Access Control Service**: Provides a flexible access control domain specific
+  language to support access control rules for multi-party secure computation.
+  The access control engine is written in Python and evaluated in SGX. Please
+  read [this document](/docs/access-control.md) to learn more about the design of it.
 - **Scheduler Service**: Schedules staged task ready for execution to a proper
   execution node with desirable capabilities.
 - **Execution Service**: A host of different executors interacting with the
@@ -37,12 +39,13 @@ a safe and secure FaaS platform.
   instances (or nodes) with different capabilities deployed in a cloud
   infrastructure.
   
-## Protocols
+## RPC and Protocols
 
 We use ProtoBuf to define messages and RPC interfaces of the Teaclave services.
-Utility functions, traits, and structures will be automatically generated to
-help implementing services to handle requests and send responses. You can find
-detailed protocol definitions in the [`proto` files](./proto/src/proto).
+You can find detailed protocol definitions in the [`proto` files](./proto/src/proto).
+In addition, utility functions, traits, and structures will be automatically
+generated to help implementing services to handle requests and send responses.
+This is done by a build time tool called [`proto_gen`](./proto/proto_gen).
 
 ## Topology
 
diff --git a/tests/README.md b/tests/README.md
index 7bb0a0d..500079a 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -1,4 +1,8 @@
-# Tests in Teaclave
+---
+permalink: /tests
+---
+
+# Test Harness and Test Cases
 
 This directory contains all tests in Teaclave including unit tests, integration
 tests, functional tests and some test fixtures.
diff --git a/third_party/README.md b/third_party/README.md
index 9c56e53..9e60ed2 100644
--- a/third_party/README.md
+++ b/third_party/README.md
@@ -1,25 +1,21 @@
-# Dependencies and Rust Packages (Crates) Vendoring
+---
+permalink: /third-party
+---
 
-In order to ease auditing, ensure product stability, as well as reduce the
-possibility of the [supply chain
-attack](https://en.wikipedia.org/wiki/Supply_chain_attack), we vendored all TEE
-dependencies here.  During the build process, the trusted components will only
-consumes packages from this designated repository and will not download any code
-from external sources such as [crates.io](https://crates.io).
+# Third-Party Dependency Vendoring
 
-## To Add A New Vendored Dependency
+For Teaclave, since all SGX/enclave dependencies are part of trusted computing base (TCB),
+in order to ease auditing, ensure product stability, as well as reduce the
+possibility of the [supply chain attack](https://en.wikipedia.org/wiki/Supply_chain_attack),
+we vendored all TEE dependencies here. During the build process, both the
+untrusted (i.e., the app part) and trusted components (i.e., the enclave part)
+will only consume packages from this designated repository and will not
+download any code from external package registry such as
+[crates.io](https://crates.io).
 
-If a crate is not available in the vendor directory, it can to be added with
-the following steps:
-
-1. Add the crates you need in the corresponding Cargo.toml (e.g.
-   [crates-sgx/Cargo.toml](https://github.com/mesalock-linux/crates-sgx/blob/master/Cargo.toml))
-and update the crate list in the README.txt (e.g.
-[crates-sgx/README.txt](https://github.com/mesalock-linux/crates-sgx/blob/master/README.txt)).
-2. Run ``cargo build`` and ensure that it passes.
-3. Run ``cargo vendor`` and update the config file (e.g. crates-sgx/config).
-   You may also utilize
-[crates-sgx/Makefile](https://github.com/mesalock-linux/crates-sgx/blob/master/Makefile)
-for automation.
-4. ``git add/commit`` the changes of
-   Cargo.toml/Cargo.lock/config/README.txt/vendor and submit a pull request.
+Basically, we have these submodules:
+  - `crates-io`: Rust crates vendored from crates.io for non-SGX components.
+  - `crates-sgx`: Vendored crates ported for SGX (i.e., using Teaclave SGX SDK).
+  - `mesapy`: a Python interpreter targeting SGX.
+  - `rust-sgx-sdk`: Teaclave SGX SDK for standard libraries and Rust bindings of
+    SGX libraries.


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@teaclave.apache.org
For additional commands, e-mail: commits-help@teaclave.apache.org


Mime
View raw message