[incubator-teaclave] branch master updated: Add access control docs (#313)

[ms...@apache.org]

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 e8b6879  Add access control docs (#313)
e8b6879 is described below

commit e8b6879442e0aa62dd687231262f8eeb98c92f72
Author: Pei Wang <ur...@gmail.com>
AuthorDate: Fri May 22 21:26:07 2020 -0700

    Add access control docs (#313)
---
 README.md              |   1 +
 docs/access-control.md | 115 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 116 insertions(+)

diff --git a/README.md b/README.md
index 47b7126..adb6a2a 100644
--- a/README.md
+++ b/README.md
@@ -40,6 +40,7 @@ platform, making computation on privacy-sensitive data safe and simple.
 
 - [Threat Model](docs/threat-model.md)
 - [Mutual Attestation: Why and How](docs/mutual-attestation.md)
+- [Access Control](docs/access-control.md)
 
 ### Codebase
 
diff --git a/docs/access-control.md b/docs/access-control.md
new file mode 100644
index 0000000..6ab2c2a
--- /dev/null
+++ b/docs/access-control.md
@@ -0,0 +1,115 @@
+---
+permalink: /docs/access-control
+---
+
+# Access Control in Teaclave
+Access control in multi-party computation, by its nature, is set-centric.
+Unlike in traditional settings where only one entitiy, group, or role is
+involved in an action, in multi-party computation tasks an access is aproved or
+denified by combinging the decisions of all stakeholders. Ownership is also
+set-like, because the result of a joint computation task very likely belongs to
+all parties that have provided data.
+
+We found that access control models in conventional systems like RBAC and ABAC
+are not powerful enough to govern data usages in Teaclave. Therefore, we
+invented our own access control model and mechanism.
+
+## Model
+The access control model of Teaclave is configured through the file
+[model.conf](../../services/access_control/model.conf).  The file has three
+sections:
+  - requests
+  - terms
+  - matchers
+
+Before diving into the details about how our access control model works, we
+recommend readers learn about [logic
+programming](https://en.wikipedia.org/wiki/Logic_programming) first, because
+our model configuration language is actually a home-baked tiny logic
+programming language.
+
+### request
+A request is a query that should be answered by the access control service. The
+response is either "approved" or "denied." A request is defined as a tuple of
+any arity. For example,
+
+```
+[requests]
+task_access_data = task, data
+```
+
+defines a request called `task_access_data` which contains two fields named
+`usr` and `data`. This request can mean a task with the id `task` wants to
+access a piece of data hosted by Teaclave whose id is `data`.
+
+### term
+Terms are relations over certain domains. Each term can be viewed as a table
+storing facts about the entities revelant to the access control logic. For
+example, 
+
+```
+[terms]
+data_owner = data, usr
+task_participant = task, usr
+```
+
+For the `task_access_data` request, there are three relevant domains: `data`,
+`usr`, and `task`. Furthermore, two relations are required by Teaclave to make
+a decision, which are
+
+  - `data_owner` relation over (`data` X `usr`), denoting which user owns
+    a piece of data.
+  - `task_participant` relation over (`task` X `usr`), denoting which
+    users are the participants of a joint computation task.
+
+An instance of the database describing the two terms could be
+
+```
+data_owner data_1, usr_1
+data_owner data_2, usr_1
+data_owner data_2, usr_2
+
+task_participant task_1 usr_1
+task_participant task_1 usr_2
+```
+
+The facts stored in this database instance indicate that `data_1` is owned
+exclusively by `usr_1`, while `data_2` is owned by `usr_1` and `usr_2`
+together. The facts also indicates that `task_1` has two participants, i.e.,
+`usr_1` and `usr_2`.
+
+### matcher
+The core logic used by Teaclave to resolve a request is defined as a matcher.
+We define the matcher for `task_access_data` request as the following
+
+```
+[matcher]
+task_access_data = data_owner(task_access_data.data, _) <= task_participant(task_access_data.task, _)
+```
+
+`data_owner(task_access_data.data, _)` and
+`task_participant(task_access_data.task, _)` are term queries. The return value
+of `data_owner(task_access_data.data, _)` is a subset of the `usr` domain,
+where each value `u` in the fact meets the condition that
+
+```
+data_owern task_access_data.data u
+```
+
+is in the terms database. `_` is called the query wild card and `<=` is the
+subset operator. Therefore, the matcher basically means that, *the request for
+`task` to access `data` is approved only if all owners of `data` are have
+articipated in `task`*.
+
+## Implementation
+The access control module of Teaclave is implemented as a standalone service.
+Other components should send RPC requests to the service and get access control
+decisions as RPC responses.
+
+The model configuration parser and request resolution engine are written in
+Python, powered by MesaPy. The access control service of Teaclave is a nice
+showcase of what MesaPy is capable of.
+
+The implementation is purely experimental at this point. The performance is not
+optimized and the engine is likely not robust enough to avoid crashes while
+dealing with badly shaped requests. Contributions are welcome!


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