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 <[email protected]>
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/[email protected]).
+- 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: [email protected]
For additional commands, e-mail: [email protected]
