You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@milagro.apache.org by ki...@apache.org on 2019/07/02 09:42:30 UTC
[incubator-milagro] branch dta/overview updated (93b5c0f -> e4b09f1)
This is an automated email from the ASF dual-hosted git repository.
kittohoward pushed a change to branch dta/overview
in repository https://gitbox.apache.org/repos/asf/incubator-milagro.git.
from 93b5c0f signed commit
new 409a6cd ecrypted envelope
new e4b09f1 ecrypted envelope
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
docs/api-details/configuration.md | 10 ++++++++++
docs/d-ta-overview.md | 20 ++++----------------
docs/dta-details/authentication.md | 20 --------------------
docs/dta-details/encrypted-envelope.md | 32 +++++++++++++++++++++++++++++++-
docs/dta-details/identity-documents.md | 4 ++--
docs/dta-details/usage.md | 22 ++++++++++++++++++++++
docs/dta-details/why-ipfs.md | 4 ++--
website/sidebars.json | 13 +++++++++----
website/static/img/dta/Envelope.png | Bin 0 -> 18988 bytes
9 files changed, 80 insertions(+), 45 deletions(-)
create mode 100644 docs/api-details/configuration.md
delete mode 100644 docs/dta-details/authentication.md
create mode 100644 docs/dta-details/usage.md
create mode 100644 website/static/img/dta/Envelope.png
[incubator-milagro] 01/02: ecrypted envelope
Posted by ki...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
kittohoward pushed a commit to branch dta/overview
in repository https://gitbox.apache.org/repos/asf/incubator-milagro.git
commit 409a6cd91f86903665f6a1344bb6f717a36f226a
Author: howardkitto <ki...@gmail.com>
AuthorDate: Tue Jul 2 10:41:56 2019 +0100
ecrypted envelope
---
docs/d-ta-overview.md | 20 ++++----------------
docs/dta-details/authentication.md | 20 --------------------
docs/dta-details/encrypted-envelope.md | 32 +++++++++++++++++++++++++++++++-
docs/dta-details/identity-documents.md | 4 ++--
docs/dta-details/why-ipfs.md | 4 ++--
website/sidebars.json | 13 +++++++++----
6 files changed, 48 insertions(+), 45 deletions(-)
diff --git a/docs/d-ta-overview.md b/docs/d-ta-overview.md
index 1f5a852..5fb14bb 100644
--- a/docs/d-ta-overview.md
+++ b/docs/d-ta-overview.md
@@ -6,16 +6,16 @@ sidebar_label: D-TA Node Overview
# Introduction
-Apache Milagro Distributed Trust Authority is a server application that enables you to generate and secure secret keys using the Milagro Cryptographic libraries. Securing of secret keys (Safeguarding) is enabled in RC1 - and is the focus of this documentation. In future releases we aim to enable a wide range of keys to be generated including Type-3 Pairing Keys that can be used to authorise MPIN authentication servers and as client secrets.
+Apache Milagro Distributed Trust Authority is a server application that enables you to generate and secure secret keys using the Milagro Cryptographic libraries. Securing of secret keys (Safeguarding) is enabled in RC1 - and is the focus of this documentation. In future releases we aim to enable a wide range of keys to be generated including Type-3 Pairing Keys that can authorise MPIN authentication servers and can be used as client secrets.
## Safeguarding Secrets
-In order to safeguard a secret, a pair of Milagro DTA servers is required: a client (refered to as the Principal) and a server (refered to as a Fiduciary). In addition a third party can be nominated as the ultimate recipient of the secret (refered to as the Beneficiary). This system can be imagined like a "network HSM". Here is a VERY simplified version of the process:
+In order to safeguard a secret, a pair of Milagro DTA servers is required: a client (refered to as the Principal) and a server (refered to as a Fiduciary). In addition a third party can be nominated as the ultimate recipient of the secret (refered to as the Beneficiary). This system can be imagined like a "network HSM". Here is a VERY simplified overview of the process:
## Milagro DTA Security
-The key seed is the focus of the system - Milagro DTA aims to provide a method for communicating with organisations who provide services for securing seeds (Custodians), it does not prescribe how the securing should be done. We hope that many custodial services will adopt Milagro as a communication protocol and that they will bring a proffusion of security paradigms: working together we can make the Internet a safer place. The most basic implementation of Milagro should secure seeds in a [...]
+The key seed is the focus of the system - Milagro DTA aims to provide a method for communicating with organisations who provide services for securing seeds (Custodians), it does not prescribe how the securing should be done. We hope that many custodial services will adopt Milagro as a communication protocol and that they will bring a proffusion of security paradigms: working together we can make the Internet a safer place. The most basic implementation of Milagro DTA should secure seeds [...]
## The Milagro DTA Communication Protocol
Milagro DTA provides a secure, distributed method of communication between beneficiaries, principals and fiduciaries. It aims to solve the following problems:
@@ -35,16 +35,4 @@ Milagro DTA provides a secure, distributed method of communication between benef
A more complete view of the Milagro DTA ecosystem is shown below
-
-
-
-
-
-:::tip WE NEED HELP DOCUMENTING!
-Interested in becoming a contributor? Milagro is looking for you.
-[CONTRIBUTOR'S GUIDE](/docs/contributor-guide.html).
-:::
-
-<!--
-Supported admonition types are: caution, note, important, tip, warning.
--->
\ No newline at end of file
+
\ No newline at end of file
diff --git a/docs/dta-details/authentication.md b/docs/dta-details/authentication.md
deleted file mode 100644
index 0382b5a..0000000
--- a/docs/dta-details/authentication.md
+++ /dev/null
@@ -1,20 +0,0 @@
----
-id: authentication
-title: Authentication
-sidebar_label: Authentication
----
-Just testing
-
-Milagro DTA's endpoints are "in the clear" by default but if you set these flags you can have the endpoints authenticate against your oAuth provider of choice.
-
-This will secure the REST API endpoints /identity and /order
-
-The RPC endpoints /fulfill are protected using the Milagro communication protocol (oAuth is not required)
-
-```
-config.yaml
-
-oidc_provider: URL for oAuth endpoint
-oidc_client_id: _your server secret_
-
-```
\ No newline at end of file
diff --git a/docs/dta-details/encrypted-envelope.md b/docs/dta-details/encrypted-envelope.md
index 758db63..f27f46c 100644
--- a/docs/dta-details/encrypted-envelope.md
+++ b/docs/dta-details/encrypted-envelope.md
@@ -4,4 +4,34 @@ title: Encrypted Envelope
sidebar_label: Encrypted Envelope
---
-Protobuf, encryption s-mime etc...
\ No newline at end of file
+Milagro DTA enables Principals (who required secrets to be safeguarded) to communicate with Fiduciaries (who provide a Custodial servce). To facilitate this transaction communication between the parties must be secure i.e. can only be read by the intended recipient and attibutable i.e. can be cryptographically verified to have been signed by known actors. Milagro DTA provides a this mechansim using an "encrypted envelope" format.
+
+:::tip Milagro DTA Encrypted Evelope format is conceptually similar to S/Mime
+For more information about S/MIME[click here](https://en.wikipedia.org/wiki/S/MIME)
+:::
+
+## Overview
+
+1. The message consists of a header and body
+2. The message body can be plain text or encrypted with an aes key.
+3. The aes key for decrypting cyphertext is "encapsulated" i.e. encrypted using each recipient's public key
+4. The sender signs the message
+5. The meassge header contains a list of each recipient's encrypted version of the key
+6. The message is pushed to IPFS and the IPFS address hash is sent to the recipients
+7. The recipients read the message and verify the signature
+7. Only recipients with the matching secret keys can decrypt the aes key and use it to read the encrypted message bodies
+
+
+
+:::note Post Quantum Cryptography
+At the time of writing Milagro DTA uses two cryptography libraries from submissions to the [NIST Post-Quantum Cryptography Standardisation Project](https://csrc.nist.gov/Projects/Post-Quantum-Cryptography/Round-2-Submissions).
+* [SIKE](https://sike.org/) - key encapsulation
+* [Picnic](https://microsoft.github.io/Picnic/) - digital signatures
+However these are currently under review
+:::
+
+## Multpart Messages
+The Milagro DTA encrypted envelope is designed to facilitate a dialogue between the Principal and Fiduciary. Requests and responses are appended to the original document and published back to IPFS wich returns new HASH address. I this way an immutable copy of each transaction is maintained, but the intended recipients can view the intire history of the transaction (if they have the required decryption keys) can be seen within each update, providing additional assurance and verification a [...]
+
+
+
diff --git a/docs/dta-details/identity-documents.md b/docs/dta-details/identity-documents.md
index 472b172..87c88d6 100644
--- a/docs/dta-details/identity-documents.md
+++ b/docs/dta-details/identity-documents.md
@@ -3,7 +3,7 @@ id: identity-documents
title: Identity Documents
sidebar_label: Identity Documents
---
-The first problem that Milagro-DTA aims to solve is how actors in the system can identify and trust each other. In order to participate in the Milagro DTA safeguarding process each actor must publish a set of public keys into IPFS. The IPFS hash for an identity documents is then the ID for each actor.
+The first problem that Milagro DTA aims to solve is how actors in the system can identify and trust each other. In order to participate in the Milagro DTA safeguarding process each actor must publish a set of public keys into IPFS. The IPFS hash for an identity documents is then the ID for each actor.
In order to create an identity document Milagro DTA provides the following endpoint.
@@ -27,7 +27,7 @@ message IDDocument {
* `AuthenticationReference` refers to Milagro's out of the box [oAuth integration](authentication.md)
-The node that is used to create an identity document will store the seed and secret keys associated with the Identity. In RC1 these are store as a JSON file in the key value store:
+The node that is used to create an identity document will store the seed and secret keys associated with the Identity. In RC1 these are stored as a JSON file in the key value store:
```
//IdentitySecrets - keys required for decryption and signing
diff --git a/docs/dta-details/why-ipfs.md b/docs/dta-details/why-ipfs.md
index 9e5f752..627934f 100644
--- a/docs/dta-details/why-ipfs.md
+++ b/docs/dta-details/why-ipfs.md
@@ -8,6 +8,6 @@ Milagro DTA aims to provide and auditable record of all interactions between act
IPFS is a globally distributed peer-to-peer file system - think GitHub meets BitTorrent. When a file is written (SET) into your local IPFS node a hash of the document is returned, you can then GET the document using that address. If somebody else who is running an IPFS tries to GET the same hash address the file will be pulled from your node to theirs. If the document is changed in way the hash will change. In this way a immutability and peer-to-peer consensus is achieved.
-:::Note: We appreciate feedback regarding this approach
+:::note We appreciate feedback regarding this approach
If more complex multi-party consensus is required we could implement something like [Paxos](https://understandingpaxos.wordpress.com/), [Raft](https://raft.github.io/), [Tendermint](https://tendermint.com/)
-
+:::
diff --git a/website/sidebars.json b/website/sidebars.json
index efde24d..2e84d86 100644
--- a/website/sidebars.json
+++ b/website/sidebars.json
@@ -19,12 +19,17 @@
{
"type":"subcategory",
"label":"DTA Details",
- "ids":[ "dta-details/identity-documents",
+ "ids":[ "dta-details/usage",
+ "dta-details/identity-documents",
"dta-details/encrypted-envelope",
- "dta-details/why-ipfs",
- "dta-details/authentication"]
+ "dta-details/why-ipfs"
+ ]
},
- "d-ta-api"
+ {
+ "type":"subcategory",
+ "label":"Set Up Instructions",
+ "ids":["api-details/configuration"]
+ }
],
"ZKP-MFA Clients/Servers": [
"zkp-mfa-overview",
[incubator-milagro] 02/02: ecrypted envelope
Posted by ki...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
kittohoward pushed a commit to branch dta/overview
in repository https://gitbox.apache.org/repos/asf/incubator-milagro.git
commit e4b09f1b76b0cc2cf0c4434b6702172f886a9c03
Author: howardkitto <ki...@gmail.com>
AuthorDate: Tue Jul 2 10:42:15 2019 +0100
ecrypted envelope
---
docs/api-details/configuration.md | 10 ++++++++++
docs/dta-details/usage.md | 22 ++++++++++++++++++++++
website/static/img/dta/Envelope.png | Bin 0 -> 18988 bytes
3 files changed, 32 insertions(+)
diff --git a/docs/api-details/configuration.md b/docs/api-details/configuration.md
new file mode 100644
index 0000000..6f7b9f6
--- /dev/null
+++ b/docs/api-details/configuration.md
@@ -0,0 +1,10 @@
+---
+id: configuration
+title: Configuration
+sidebar_label: Configuration
+---
+Config file
+
+Flags
+
+Env vars
\ No newline at end of file
diff --git a/docs/dta-details/usage.md b/docs/dta-details/usage.md
new file mode 100644
index 0000000..e0184f6
--- /dev/null
+++ b/docs/dta-details/usage.md
@@ -0,0 +1,22 @@
+---
+id: usage
+title: Using Milagro DTA
+sidebar_label: Using Milagro DTA
+---
+Milagro DTA is designed to be built into the workflow of any organisation that needs to entrust another organisation to store the secret part of a key pair securely. It provides a [simple REST api](/swagger/index.html) "out-of-the-box" that can easily be integrated with an existing back office system or attached to a front-end application (or called from CURL, Postman, Swagger etc. if you just want to see what it does).
+
+The API has three parts to it:
+
+1. _Identity Endpoints_ - that support creation and retrieval of identity documents
+2. Secret Endpoints
+ 1. Creates orders for new secrets
+ 2. Requets for existing secret keys to be revealed (redeemed)
+ 3. Allows orders to be searched and listed
+3. Fulfilment RPC - these are the server-to-server calls that enable the Principal DTA to communicate with the Fiduciary
+
+## Bootstrapping An Identity
+
+In order to run a Milagro DTA Node it needs to be configured with an idenity. This is usually passed to the node via one of the [configuration options](api-details/configuration.md), however if you are running a server for the first time it will prompt you to create a new one.
+
+
+
diff --git a/website/static/img/dta/Envelope.png b/website/static/img/dta/Envelope.png
new file mode 100644
index 0000000..28f8ff4
Binary files /dev/null and b/website/static/img/dta/Envelope.png differ