more updates
diff --git a/README.md b/README.md
index 8f4835f..8cce7f8 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@
* [Milagro Crypto C Library](https://github.com/apache/incubator-milagro-crypto-c)
* [Milagro Crypto JavaScript Library](https://github.com/apache/incubator-milagro-javascript)
-For the time being, only the C and JavaScript libraries are being supported going forward.
+For the time being, only the C, JavaScript & Rust libraries are being supported going forward.
Website Detail
============================
diff --git a/docs/d-ta-overview.md b/docs/d-ta-overview.md
index 921d3b3..ad957a5 100644
--- a/docs/d-ta-overview.md
+++ b/docs/d-ta-overview.md
@@ -5,25 +5,25 @@
---
# Introduction
-Milagro D-TA is a colaborative key management server
+The Apache Milagro (Incubating) Decentralized Trust Authority (D-TA) is a collaborative key management server.
-Milagro D-TA facilitates secure and auditable communication between someone who wants to use a key pair (the Principal) and service providers who can keep secret keys safe (Master Fiduciary). It is written in Go and uses REST services based on the GoKit microservices framework, it uses IPFS to create a shared immutable log of transactions and relies on Milagro-Crypto-C for it's crypto.
+The D-TA facilitates secure and auditable communication between someone who wants to use a key pair (the Principal) and service providers who can keep secret keys safe (Master Fiduciary). It is written in Go and uses REST services based on the GoKit microservices framework, it uses IPFS to create a shared immutable log of transactions and relies on Milagro-Crypto-C for it's crypto.
## Safeguarding Secrets
-In order to safeguard a secret using Milagro D-TA a minimum of two roles are required: a client (refered to as the Principal) and a server (refered to as a Master Fiduciary). In addition a third party can be nominated as the ultimate recipient of the secret (refered to as the Beneficiary). You can run a single D-TA to provide all three roles if you want to see it in action. See the [quick start guide](/docs/dta-details/quickstart) for instructions on how to do that.
+In order to safeguard a secret using the D-TA a minimum of two roles are required: a client (refered to as the Principal) and a server (refered to as a Master Fiduciary). In addition a third party can be nominated as the ultimate recipient of the secret (refered to as the Beneficiary). You can run a single D-TA to provide all three roles if you want to see it in action. See the [quick start guide](/docs/dta-details/quickstart) for instructions on how to do that.
This system can be imagined like a "network HSM". Here is a VERY simplified overview of the process:
## Milagro D-TA Security
-The **Seed** is the focus of the system - Milagro D-TA provides a method for Principals to communicate with Master Fiduciares who can secure their secret keys, it does not prescribe how the securing should be done. The most basic implementation of Milagro D-TA should secure seeds in an HSM using a PKCS#11 interface.
+The **Seed** is the focus of the system - the D-TA provides a method for Principals to communicate with Master Fiduciares who can secure their secret keys, it does not prescribe how the securing should be done. The most basic implementation of a D-TA should secure seeds in an HSM using a PKCS#11 interface.
-We hope that many custodial services will adopt Milagro D-TA as a communication protocol and that they will bring a profusion of security paradigms, by working together we can make a dynamic market place for custodial services and together make the Internet a safer place.
+We hope that many custodial services will adopt the Milagro D-TA as a communication protocol and that they will bring a profusion of security paradigms, by working together we can make a dynamic market place for custodial services and together make the Internet a safer place.
## The Milagro D-TA Communication Protocol
-Milagro D-TA provides a secure, distributed method of communication between beneficiaries, principals and fiduciaries. It aims to solve the following problems:
+The D-TA provides a secure, distributed method of communication between beneficiaries, principals and fiduciaries. It aims to solve the following problems:
1. How can actors in the system be identified and trusted?
diff --git a/docs/dta-details/api.md b/docs/dta-details/api.md
index 8ff77a8..6f5eadf 100644
--- a/docs/dta-details/api.md
+++ b/docs/dta-details/api.md
@@ -4,7 +4,7 @@
sidebar_label: API
---
-Open-api specifications are provided for the core "vanilla" Milagro HTTP REST services and for both the shipped plugins: Bitcoin Address and Safeguard Secret
+Open-api specifications are provided for the core "vanilla" Milagro D-TA HTTP REST services and for both the shipped plugins: Bitcoin Address and Safeguard Secret
* [Standard API](https://raw.githubusercontent.com/apache/incubator-milagro-dta/develop/open-api.yaml) Here it is in a [Swagger UI](/swagger/index.html)
* [Bitcoin Plugin API](https://raw.githubusercontent.com/apache/incubator-milagro-dta/develop/pkg/bitcoinplugin/open-api.yaml)
diff --git a/docs/dta-details/configuration.md b/docs/dta-details/configuration.md
index cf077e5..e300711 100644
--- a/docs/dta-details/configuration.md
+++ b/docs/dta-details/configuration.md
@@ -107,7 +107,7 @@
```
:::note By default a D-TA will be both a principal and master fiduciary.
:::
-* **nodename** - set your DT-A node name (nodeName) here. By default, a random name with be generated.
+* **nodename** - set your DT-A node name (nodeName) here. By default, a random name with be generated if none is specified.
* **service** - use this flag to set which plugin to use. Default is "milagro". Currently available plugins are "bitcoinwallet" and "safeguardsecret".
* **interactive** - use this flag to prompt for values for the other flags. For example, to set the name (nodeName) of this DT-A to "alice", the identity (nodeID) of the external fiduciary to "QmR7JfvEwTbSkBZuRLdDcRTpZik2ZAuHnn9BA7giX7oJNK", the endpoint of the master fiduciary to "http://123.456.789.1:5556" and to use the "bitcoinwallet" plugin:
diff --git a/docs/dta-details/d-ta-plugins.md b/docs/dta-details/d-ta-plugins.md
index 97f1f9a..239c2dc 100644
--- a/docs/dta-details/d-ta-plugins.md
+++ b/docs/dta-details/d-ta-plugins.md
@@ -4,12 +4,12 @@
sidebar_label: Plugins Overview
---
-Out-of-the-box Milagro D-TA doesn't do much: a Principal gets a public key from a Master Fiduciary and at a later date can request the corresponding secret key. (Although it does this in a hard-to-hack, and fully auditable way). However this basic capability unlocks a huge range of potential uses cases. Some use cases relate to the Prinicpal i.e. what the keys can be used for, and some relate to the Master Fiduciary i.e. how the seret key is kept safe (a.k.a. custody). Open source "vanilla" Milagro is an attempt to engage a wider community to make the communication between these parties as robust as possible, the plugin framework enables developers to extend Milagro's core capability and apply it to solve real world problems.
+The out-of-the-box Milagro D-TA doesn't do much: a Principal gets a public key from a Master Fiduciary and at a later date can request the corresponding secret key. (Although it does this in a hard-to-hack, and fully auditable way). However this basic capability unlocks a huge range of potential uses cases. Some use cases relate to the Prinicpal i.e. what the keys can be used for, and some relate to the Master Fiduciary i.e. how the seret key is kept safe (a.k.a. custody). Th open source "vanilla" Milagro is an attempt to engage a wider community to make the communication between these parties as robust as possible, the plugin framework enables developers to extend the Milagro D-TA's core capability and apply it to solve real world problems.
-Out of the box Milagro comes with two plugins:
+Out of the box the Milagro D-TA comes with two plugins:
1. **EncryptAThing** - allows the principal to use the public key to encrypt a string, then get the secret key back from the Master Fiduciary D-TA and decrypt it
-2. **BitCoin Address** - uses the public key to genarate a Bitcoin address and the constructs the corresponding secret key only when it is needed (this is a neat trick using eliptic curve magic).
+2. **BitCoin Address** - uses the public key to generate a Bitcoin address and then constructs the corresponding secret key only when it is needed (this is a neat trick using elliptic curve magic).
***A Note About Security***
@@ -28,16 +28,16 @@
* **One-at-a-Time**
- Each Milagro server can only run one plugin at a time. We considered how to allow multiple plugins to interoperate but this produces significant operational and security concerns. (We'd really appreciate your thoughts about that). Of course if you run a pair of servers as Principal and Master Fiduciary then they can each run different plugins
+ Each Milagro D-TA server can only run one plugin at a time. We considered how to allow multiple plugins to interoperate but this produces significant operational and security concerns. (We'd really appreciate your thoughts about that). Of course if you run a pair of servers as Principal and Master Fiduciary then they can each run different plugins
* **No New Endpoints**
- You can only write plugins to support the [Standard Endpoints](http://localhost:3000/swagger/). This probably seems quite restrictive but we think it is important that Milagro D-TA operates within a defined scope and in a predictable way. Milagro D-TA is about the distributed management of key pairs, we are concerned that if the plugin framework allowed developers to add endpoints such as *GET fastfood/burger?orderby=mostTasty* then Milagro would just become a cool implementation of [Go kit](https://gokit.io/) and it would become impossible for users and integrators to predict what it will do. **However...**
- * **Let's Talk** As a community we're excited to add new features to Milagro D-TA. Propose your new endpoint as a feature (or even submit a PR) and we'll collectively consider adding it
- * **Let's Fork** Go ahead and fork the Milagro D-TA. (But remember that Milagro D-TA is basically a communication protcol so keep it compatible with other Milagro users)
+ You can only write plugins to support the [Standard Endpoints](http://localhost:3000/swagger/). This probably seems quite restrictive but we think it is important that Milagro D-TA operates within a defined scope and in a predictable way. The Milagro D-TA is about the distributed management of key pairs, we are concerned that if the plugin framework allowed developers to add endpoints such as *GET fastfood/burger?orderby=mostTasty* then Milagro would just become a cool implementation of [Go kit](https://gokit.io/) and it would become impossible for users and integrators to predict what it will do. **However...**
+ * **Let's Talk** As a community we're excited to add new features to the Milagro D-TA. Propose your new endpoint as a feature (or even submit a PR) and we'll collectively consider adding it
+ * **Let's Fork** Go ahead and fork the Milagro D-TA. (But remember that the Milagro D-TA is basically a communication protcol so keep it compatible with other Milagro users)
* **Extensions**
- Although we restrict what endpoints Milagro provides we give you a highly flexible way to define what data each endpoint accepts and returns via the **extensions** JSON prop. For example the encryptAThing plugin extends the POST /order endpoint like this:
+ Although we restrict what endpoints Milagro provides we give you a highly flexible way to define what data each endpoint accepts and returns via the **extensions** JSON prop. For example the safeguardsecret plugin extends the POST /order endpoint like this:
```
POST /order
diff --git a/docs/dta-details/encrypted-envelope.md b/docs/dta-details/encrypted-envelope.md
index f27f46c..c44acc2 100644
--- a/docs/dta-details/encrypted-envelope.md
+++ b/docs/dta-details/encrypted-envelope.md
@@ -4,9 +4,9 @@
sidebar_label: Encrypted Envelope
---
-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.
+The Milagro D-TA 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. The Milagro D-TA provides a this mechansim using an "encrypted envelope" format.
-:::tip Milagro DTA Encrypted Evelope format is conceptually similar to S/Mime
+:::tip The Milagro D-TA Encrypted Evelope format is conceptually similar to S/Mime
For more information about S/MIME[click here](https://en.wikipedia.org/wiki/S/MIME)
:::
@@ -24,14 +24,17 @@
:::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).
+At the time of writing the Milagro D-TA uses a cryptography library from 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
+However this are currently under review
+:::
+
+:::note digital signatures
+Currently, the Milagro D-TA uses [BLS signatures](https://en.wikipedia.org/wiki/Boneh–Lynn–Shacham) to sign encrypted envelopes.
:::
## 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.
+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. In this way an immutable copy of each transaction is maintained, but the intended recipients can view the entire 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 0182f0c..6550b62 100644
--- a/docs/dta-details/identity-documents.md
+++ b/docs/dta-details/identity-documents.md
@@ -15,13 +15,14 @@
:::
The definition of an identity document is:
-```
+```json
message IDDocument {
- string AuthenticationReference = 2 ;
- bytes SikePublicKey = 3 ;
- bytes PicnicPublicKey = 4 ;
- string Username = 5 ;
- int64 Timestamp = 6 ;
+ string IDDocumentCID = 2 ;
+ string AuthenticationReference = 3 ;
+ string BeneficiaryECPublicKey = 4 ;
+ string SikePublicKey = 5 ;
+ string BlsPublicKey = 6 ;
+ int64 Timestamp = 7 ;
}
```
@@ -32,12 +33,12 @@
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:
-```
+```json
//IdentitySecrets - keys required for decryption and signing
type IdentitySecrets struct {
Name string `json:"name"`
Seed string `json:"seed"`
SikeSecretKey string `json:"sikeSecretKey"`
- PicnicSecretKey string `json:"picnicSecretKey"`
+ BlsSecretKey string `json:"BlsSecretKey"`
}
```
\ No newline at end of file
diff --git a/docs/dta-details/ipfs.md b/docs/dta-details/ipfs.md
index ba296f5..5396d18 100644
--- a/docs/dta-details/ipfs.md
+++ b/docs/dta-details/ipfs.md
@@ -4,7 +4,7 @@
sidebar_label: IPFS
---
-Milagro DTA aims to provide and auditable record of all interactions between actors in the system. It is vital that all the actors in the system can refer to an agreed record of these transactions in case of dispute or in response to requests from third parties such as law enforcement, audit or compliance. Milagro creates immutable, secure and attributable records of every interaction that occurs in the lifecycle of the actors and their dealings with secrets. We do this using the Inter Planetary File System - [IPFS](https://ipfs.io/).
+The Milagro D-TA aims to provide an auditable record of all interactions between actors in the system. It is vital that all the actors in the system can refer to an agreed record of these transactions in case of dispute or in response to requests from third parties such as law enforcement, audit or compliance. The Milagro D-TA creates immutable, secure and attributable records of every interaction that occurs in the lifecycle of the actors and their dealings with secrets. We do this using the Inter Planetary File System - [IPFS](https://ipfs.io/).
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.
diff --git a/docs/dta-details/quickstart.md b/docs/dta-details/quickstart.md
index 041bcaa..df25f69 100644
--- a/docs/dta-details/quickstart.md
+++ b/docs/dta-details/quickstart.md
@@ -38,11 +38,11 @@
## Plugins
-Milagro D-TA comes with two aditional plugins out-of-the box, which are intended to demonstrate how it can be extended.
+The Milagro D-TA comes with two aditional plugins out-of-the box, which are intended to demonstrate how it can be extended.
**To Run Safeguard Secret**
-The Safeguard Secret plugin encrypts a string with the public key and decrypts it when the Master Feducuiary returns the secret key.
+The Safeguard Secret plugin encrypts a string with the public key and decrypts it when the Master Fiducuiary returns the secret key.
```
docker run -it -p 5556:5556 milagrodta -service safeguardsecret
@@ -61,7 +61,7 @@
The details of the API can be [seen here...](/swagger/index.html)
-Milagro D-TA can easily be integrated with an existing back office system, called from a front-end application or called from CURL, Postman, Swagger etc.
+The Milagro D-TA can easily be integrated with an existing back office system, called from a front-end application or called from CURL, Postman, Swagger etc.
The API has three parts to it:
@@ -70,7 +70,7 @@
1. Creates orders for new public keys
2. Requests for secret keys to be revealed (redeemed)
3. Allows orders to be searched and listed
-3. **Fulfillment RPC** - these are the server-to-server remnote procedure calls that enable a Principal D-TA to communicate with a Master Fiduciary D-TA
+3. **Fulfillment RPC** - these are the server-to-server remote procedure calls that enable a Principal D-TA to communicate with a Master Fiduciary D-TA
### Example - To create a new Identity
diff --git a/website/sidebars.json b/website/sidebars.json
index 1e436f7..26455c4 100644
--- a/website/sidebars.json
+++ b/website/sidebars.json
@@ -18,7 +18,12 @@
"d-ta-overview",
"dta-details/quickstart",
"dta-details/api",
- "dta-details/configuration"
+ "dta-details/configuration",
+ "dta-details/identity-documents",
+ "dta-details/encrypted-envelope",
+ "dta-details/ipfs",
+ "dta-details/plugins-overview",
+ "dta-details/authentication"
],
"ZKP-MFA Clients/Servers": [
"zkp-mfa-overview",
