ecrypted envelope
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 @@
# 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 an HSM using a PKCS#11 interface. (We aim to publish a PKCS11 driver in a subsequent release)
+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 in an HSM using a PKCS#11 interface. (We aim to publish a PKCS11 driver in a subsequent release)
## 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 @@
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 @@
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 and reducing round trips to IPFS.
+
+
+
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 @@
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 @@
* `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 @@
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",
