Merge pull request #22 from apache/develop
Dev -> Master
diff --git a/README.md b/README.md
index 40a2445..0f45c43 100644
--- a/README.md
+++ b/README.md
@@ -5,18 +5,15 @@
Milagro is a set of crypto libraries and core security infrastructure applications, built for decentralized networks yet suitable for enterprises.
-Milagro has several repos. The application repos are being overhauled to reflect new, modern architectures. Expect these to be merged into a Milagro ZKP-MFA server repo, and a Milagro Decentralized Trust Authority (D-TA) repo. More detail is available at:
-
-* [Milagro JIRA](https://issues.apache.org/jira/projects/MILAGRO/issues/MILAGRO-18?filter=allopenissues)
-* [Milagro Wiki](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=115529045)
-
-The most current libraries are the core crypto libraries:
+Milagro has several repos. The C and JavaScript versions of the core cryptographic libraries have had major releases, and are production ready, while the Rust version is under development:
* [Milagro Crypto C Library](https://github.com/apache/incubator-milagro-crypto-c)
* [Milagro Crypto JavaScript Library](https://github.com/apache/incubator-milagro-javascript)
* [Milagro Crypto Rust Library](https://github.com/apache/incubator-milagro-crypto-rust/)
-For the time being, only the C and JavaScript libraries are being supported going forward.
+Applications being developed on these cryptographic libraries include the Milagro ZKP-MFA server and the Milagro Decentralized Trust Authority (D-TA). The Milagro D-TA is now at an alpha release stage.
+
+* [Apache Milagro Decentralized Trust Authority](https://github.com/apache/incubator-milagro-dta)
What's New
============================
diff --git a/docs/contributor-guide.md b/docs/contributor-guide.md
index 69d5015..17d459b 100644
--- a/docs/contributor-guide.md
+++ b/docs/contributor-guide.md
@@ -5,10 +5,23 @@
---
# Become a contributor
+## Apache Milagro Mailing List
-<p>Keeping with our spartan theme, for now, it's best to send an email to <a href="mailto:dev-subscribe@milagro.apache.org?Subject=Subscribe" target="_top">dev-subscribe @ milagro.apache.org</a> to join our mailing list.</p>
+If you'd like to contribute, the first step is to subscribe to our developer's mailing list. Please send an email to:
-More information will be available here shortly.
+<a href="mailto:dev-subscribe@milagro.apache.org?Subject=Subscribe" target="_top">dev-subscribe @ milagro.apache.org</a>
+
+## Issues
+
+Our current GitHub repositories are:
+
+* https://github.com/apache/incubator-milagro - used to build this website.
+* https://github.com/apache/incubator-milagro-crypto-c - standards compliant cryptographic library written in C.
+* https://github.com/apache/incubator-milagro-crypto-js - standards compliant cryptographic library written in JavaScript.
+* https://github.com/apache/incubator-milagro-crypto-rust - standards compliant cryptographic library written in Rust.
+* https://github.com/apache/incubator-milagro-dta - Milagro Decentralized Trust Authority (D-TA) - a collaborative key management server.
+
+Please use the "Issues" tab on these repos to report any bugs or feature requests.
<!--
Supported admonition types are: caution, note, important, tip, warning.
diff --git a/docs/d-ta-overview.md b/docs/d-ta-overview.md
index 861f91a..2e80e12 100644
--- a/docs/d-ta-overview.md
+++ b/docs/d-ta-overview.md
@@ -1,14 +1,66 @@
---
id: d-ta-overview
title: Decentralized Trust Authority Overview
-sidebar_label: D-TA Node Overview
+sidebar_label: D-TA Overview
---
+### VERSION: ALPHA RELEASE
-:::tip WE NEED HELP DOCUMENTING!
-Interested in becoming a contributor? Milagro is looking for you.
-[CONTRIBUTOR'S GUIDE](/docs/contributor-guide.html).
+:::important The Alpha Release of the D-TA is not for production use.
:::
-<!--
-Supported admonition types are: caution, note, important, tip, warning.
--->
\ No newline at end of file
+#### Release Schedule:
+
+Beta Release: 1st week October 2019
+
+RC1 Release: 1st week November 2019
+
+# Introduction
+The Apache Milagro (Incubating) Decentralized Trust Authority (D-TA) is a collaborative key management server. It has two primary functions.
+
+1. **Issue** shares of identity-based Type-3 pairing secrets for initializing zero-knowledge proof multi-factor authentication (ZKP-MFA) networks of clients and authentication servers.
+2. **Safeguards** shares of generic secrets, acting independently but in conjunction with other D-TA nodes, for the benefit of other D-TA nodes.
+
+In the use case where it issues shares, the D-TA holds nothing except for its Master Secret and acts as a distributed private key generation server. In the use case where it is safeguarding shares of secrets, it is up to the application developer to implement back-end application logic to hold those shares securely. Examples include using Hardware Security Modules (HSMs) via an on-board PKCS#11 implementation to create a realm of key encryption keys, or multi-party computation through BLS signature aggregation.
+
+# Roles
+
+Operators of Decentralized Trust Authorities are segmented into three roles.
+
+1. **Principals** - These entities operate a Milagro D-TA node to securely communicate with other D-TA nodes (Fiduciaries), employing them to issues shares of secrets or safeguard shares of secrets.
+
+2. **Fiduciaries** - These entities operate \\( 1 + n \\) Milagro D-TAs to issue shares of secrets or safeguard shares of secrets.
+
+3. **Beneficiaries** - These entities receive shares of secrets from Fiduciaries.
+
+A D-TA facilitates secure and auditable communication between entities and service providers who can keep shares of secret keys safe (Fiduciaries). The D-TA is written in Go and uses REST services based on the GoKit microservices framework. The D-TA uses IPFS to create a shared immutable log of transactions and relies on Milagro-Crypto-C for it's crypto. Future release candidates will incorporate Tendermint for consensus protocol.
+
+# Safeguarding Secrets
+
+In order to safeguard a secret using the D-TA a minimum of two roles are required: a client (Principal) and a server (Fiduciary). In addition a third party can be nominated as the ultimate recipient of the secret (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". Below is a VERY simplified overview of the process:
+
+
+
+## Milagro D-TA Security
+The **Seed** is the focus of the system - the D-TA provides a method for Principals to communicate with Fiduciaries who can secure their secrets, 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 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
+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?
+
+ **Answer:** [Identity Documents](dta-details/identity-documents.md)
+2. How can records of interactions between actors in the system be trusted and verified?
+
+ **Answer:** [Encrypted Envelopes](dta-details/encrypted-envelope.md) via [IPFS](dta-details/ipfs.md)
+
+3. How can different custodial services provide their own "special security sauce"?
+
+ **Answer:** [Plugins](dta-details/d-ta-plugins.md)
+
+A more complete view of the Milagro D-TA ecosystem is shown below
+
+
\ No newline at end of file
diff --git a/docs/dta-details/api.md b/docs/dta-details/api.md
new file mode 100644
index 0000000..f5fc86f
--- /dev/null
+++ b/docs/dta-details/api.md
@@ -0,0 +1,38 @@
+---
+id: api
+title: API
+sidebar_label: API
+---
+
+Open-API specifications are provided for the core "vanilla" Milagro D-TA HTTP REST services and for both the shipped plugins: Bitcoin Wallet Security and Safeguard Secret.
+
+* [Standard API](https://raw.githubusercontent.com/apache/incubator-milagro-dta/develop/open-api.yaml) The [Swagger UI is available at this link.](/swagger/index.html)
+* [Bitcoin Wallet Security Plugin API](https://raw.githubusercontent.com/apache/incubator-milagro-dta/develop/pkg/bitcoinplugin/open-api.yaml)
+* [Safeguard Secret API](https://raw.githubusercontent.com/apache/incubator-milagro-dta/develop/pkg/safeguardsecret/open-api.yaml)
+
+
+## Testing The API
+
+This assumes that your local DTA is running on port 5556 as described in the [quick start guide](/docs/dta-details/quickstart).
+
+Instructions for installing Swagger UI can be found [here](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/installation.md).
+
+For example...
+
+```
+docker pull swaggerapi/swagger-ui
+
+docker run -p 80:8080 swaggerapi/swagger-ui
+
+```
+
+In your browser hit http://localhost:80
+
+Paste the URL of one of the API docs above into the text box at the top of the screen.
+
+Please let us know your comments by subscribing to dev@milagro.apache.org by sending an email to dev-subscribe@milagro.apache.org.
+
+
+
+
+
diff --git a/docs/dta-details/authentication.md b/docs/dta-details/authentication.md
new file mode 100644
index 0000000..48153c6
--- /dev/null
+++ b/docs/dta-details/authentication.md
@@ -0,0 +1,24 @@
+---
+id: authentication
+title: Authentication
+sidebar_label: Authentication
+---
+When you first install a Milagro D-TA, the API endpoints are not authenticated by default. In other words, any simple CURL command will elicit the expected response. Milagro D-TAs support the [oAuth bearer token authentication](https://tools.ietf.org/html/rfc6750) out of the box.
+
+:::caution
+We strong recommend that you ***do not*** run a Milagro D-TA instance without authentication.
+:::
+
+To configure authentication all that is required is a standard OAuth 2.0 service. If you do not have an OAuth service currently running in your own infrastructure, we recommend any of these fine service providers who will be able to authenticate your API users.
+* [AWS Cognito](https://aws.amazon.com/cognito/)
+* [Azure Active Directory](https://azure.microsoft.com/en-gb/services/active-directory/)
+* [AuthO](https://auth0.com/)
+
+## Configuration
+
+Please see [Configuration](configuration.md) for details on how to configure config.yaml to support OAuth.
+
+
+
+
+
diff --git a/docs/dta-details/configuration.md b/docs/dta-details/configuration.md
new file mode 100644
index 0000000..e300711
--- /dev/null
+++ b/docs/dta-details/configuration.md
@@ -0,0 +1,130 @@
+---
+id: configuration
+title: Configuration
+sidebar_label: Configuration
+---
+The Milagro D-TA can be configured either by editing its configuration file or using command line flags.
+
+:::important running a D-TA as a principal with an external master fiduciary (as described below) is not currently supported but will be in the next release.
+:::
+
+## Configuration File
+The config file is located in `~/.milagro/config.yaml`
+
+:::important this configuration method is not yet supported when running in Docker. Please use the command line flags described below.
+:::
+
+The default values are shown below with some explanatory comments:
+```json
+// http ports
+http:
+ listenAddr: :5556
+ metricsAddr: :5557
+
+// You can secure the endpoints with an oAuth 2.0 compatible identity provider
+ oidcProvider: ""
+ oidcClientID: ""
+ oidcClientKey: ""
+
+// If the endpoints are accessed from a web app put address here
+ corsAllow: http://localhost:3000
+
+node:
+
+// D-TA can be "principal", "master fiduciary" or "multi"
+ nodeType: multi
+
+// If D-TA is running as principal tell it where its Master Fiduciary is
+// (if nodeType is "multi" use localhost on same port)
+ masterFiduciaryServer: http://localhost:5556
+
+// IPFS Hash Address of Master Fiduciary's Identity document
+// (if nodeType is "multi"use nodeID (see below))
+ masterFiduciaryNodeID: QmfZkZ8WR9N2nVg8rktbR2n7hBFN3HmYuFJeVuS3gcT3Mz
+
+// IPFS Hash Address of this node's identity document
+// (created and logged to stdout on startup)
+ nodeID: QmfZkZ8WR9N2nVg8rktbR2n7hBFN3HmYuFJeVuS3gcT3Mz
+
+// String used to refer to this node
+ nodeName: 17c9f630d2e098e4
+
+// Uses embedded "bolt" DB by defaultD-TA
+// (In productiion you should use external highly available database)
+ dataStore: embedded
+
+// configure logs
+log:
+ format: text
+ level: info
+
+// IPFS - by default D-TA connects to private IPFS network
+ connector: embedded
+ bootstrap:
+ - /ip4/34.252.47.231/tcp/4001/ipfs/QmcEPkctfqQs6vbvTD8EdJmzy4zouAtrV8AwjLbGhbURep
+ listenAddress: /ip4/0.0.0.0/tcp/4001
+ apiAddress: http://localhost:5001
+
+// Define the plugin to be used. Default is "milagro". Currently available alternative plugins are "bitcoinwallet" and "safeguardsecret"
+plugins:
+ service: milagro
+```
+## Command Line Flags
+
+To view available service commands:
+
+```json
+ ./milagro
+Milagro DTA
+USAGE
+ milagro <command> [options]
+
+COMMANDS
+ init Initialize configuration
+ daemon Starts the milagro daemon
+```
+
+To view the available initialization option flags, use the `-help` flag:
+
+### INIT
+
+```json
+./milagro init -help
+Usage of init:
+ -interactive
+ Interactive setup
+ -masterfiduciarynode string
+ Master fiduciary node
+ -nodename string
+ Node name
+ -service string
+ Service plugin (default "milagro")
+```
+
+* **masterfiduciarynode** - if you want to use an external master fiduciary, use this flag to set its identity (nodeID) and endpoint separated with a comma. For example:
+```json
+QmR7JfvEwTbSkBZuRLdDcRTpZik2ZAuHnn9BA7giX7oJNK,http://123.456.789.1:5556
+```
+:::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 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:
+
+```json
+./milagro init -interactive
+What is your node name?. Leave blank to generate a random name: alice
+What is your Master Fiduciary DTA’s node name? Leave blank to use this DTA as the Master Fiduciary: QmR7JfvEwTbSkBZuRLdDcRTpZik2ZAuHnn9BA7giX7oJNK
+What is your Master Fiduciary DTA’s address?: http://123.456.789.1:5556
+What plugin do you want to install? (B)itcoin wallet address generator or (S)afeguard secret. Leave blank for no plugin: B
+```
+
+### DAEMON
+```json
+./milagro daemon -help
+Usage of daemon:
+ -service string
+ Service plugin (default "bitcoinwallet")
+```
+* **service** - use this flag to set which plugin to use. Default is "milagro". Currently available plugins are "bitcoinwallet" and "safeguardsecret".
+
diff --git a/docs/dta-details/d-ta-plugins.md b/docs/dta-details/d-ta-plugins.md
new file mode 100644
index 0000000..a4d9091
--- /dev/null
+++ b/docs/dta-details/d-ta-plugins.md
@@ -0,0 +1,67 @@
+---
+id: plugins-overview
+title: D-TA Plugins Overview
+sidebar_label: Plugins Overview
+---
+
+The out-of-the-box Milagro D-TA doesn't do much: a Principal's D-TA gets a public key from a Fiduciary's D-TA, and at a later date, can request the corresponding secret key. It is simple conceptually, but the core operation 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 Principal i.e. what the keys can be used for, and some relate to the Fiduciary i.e. how the secret key is kept safe (a.k.a. custody).
+
+The open source "vanilla" Milagro is an attempt to engage a wider community to make the communication between these parties as robust as possible, and 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 the Milagro D-TA comes with two plugins:
+1. **Safeguard Secret** - allows the Principal to use a public key obtained from the Fiduciary's D-TA to encrypt a string using ECIES, then obtain the secret key back from the Fiduciary's D-TA to decrypt the same string.
+
+2. **Bitcoin Wallet Security** - 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***
+
+The point of these plugins is to show you how the framework works and encourage you to develop your own. They do not (out of the box) provide a secure way to store your secret keys. The key pair seed is stored only in the Fiduciary's onboard database - this is not how you should be doing it in production. Future releases will provide guidance on securing these seeds via PKCS#11 integrations and tie-ins to service providers.
+
+## Approach
+The Milagro D-TA plugin framework has been designed with following assumptions:
+
+* **Compile-Time**
+
+ Milagro D-TA plugins are compiled into the Milagro D-TA - to include one you simply clone the plugin into to the pkg directory and pass a reference to the plugin as a build directive like this...
+ ```
+ go build -tags "plugin encryptAThing" -o target/service github.com/apache/incubator-milagro-dta/cmd/service
+ ```
+ We considered run-time plugins using shared objects via the [Go Plugin Package](https://golang.org/pkg/plugin/) however this presented significant security challenges. We would very much like explore this idea further with the developer community.
+
+* **One-at-a-Time**
+
+ 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. Of course if you run a pair of servers, (example: as Principal and 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. 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 protocol 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 Safeguard Secret plugin extends the POST /order endpoint like this:
+ ```
+ POST /order
+
+ Request
+ {
+ "beneficiaryIDDocumentCID" : "IPFSAddress",
+ "extensions" : {
+ "plainText":"encryptme"
+ }
+ }
+
+ Response
+ {
+ "orderPart1CID" : "IPFSAddress",
+ "orderPart2CID" : "IPFSAddress",
+ "commitment" : "IPFSAddress",
+ "createdAt" : 1563982017,
+ "extensions" : {
+ "cypherText":"iAmEncrypted"
+ }
+ }
+ ```
+
diff --git a/docs/dta-details/encrypted-envelope.md b/docs/dta-details/encrypted-envelope.md
new file mode 100644
index 0000000..e4d7dc6
--- /dev/null
+++ b/docs/dta-details/encrypted-envelope.md
@@ -0,0 +1,42 @@
+---
+id: encrypted-envelope
+title: Encrypted Envelope
+sidebar_label: Encrypted Envelope
+---
+
+The Milagro D-TA enables Principals (who require secrets to be safeguarded) to communicate with Fiduciaries who provide custodian services for those secrets. To facilitate these transactions communication between the parties must be secure i.e., must have privacy, authentication, non-repudiation and message integrity. The Milagro D-TA delivers this using its "Encrypted Envelope" messaging format.
+
+:::tip The Milagro D-TA Encrypted Envelope format is conceptually similar to S/MIME and its cryptographic message format.
+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 is encrypted with an AES key.
+3. The AES key for decrypting ciphertext is "encapsulated" i.e. encrypted using each recipient's public key.
+4. The sender signs the message.
+5. The message 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 verify the signature and then read the message.
+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 the Milagro D-TA implements cryptographic routines from the [NIST Post-Quantum Cryptography Standardization Project](https://csrc.nist.gov/Projects/Post-Quantum-Cryptography/Round-2-Submissions).
+* [SIKE](https://sike.org/) - key encapsulation
+This implementation is currently under review.
+:::
+
+:::note digital signatures
+Milagro D-TAs use [BLS signatures](https://en.wikipedia.org/wiki/Boneh–Lynn–Shacham) to sign encrypted envelopes.
+:::
+
+## Multipart Messages
+The Milagro D-TA's Encrypted Envelopes are designed to facilitate a dialogue between the Principal, Fiduciary and Beneficiaries. Requests and responses are appended to the original document and published back to IPFS which 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. Each message 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
new file mode 100644
index 0000000..181b904
--- /dev/null
+++ b/docs/dta-details/identity-documents.md
@@ -0,0 +1,41 @@
+---
+id: identity-documents
+title: Identity Documents
+sidebar_label: Identity Documents
+---
+The first problem that a Milagro D-TA aims to solve is how entities in the system can identify and trust each other. In order to participate in the Milagro D-TA ecosystem each entity must publish a set of public keys into IPFS. The IPFS hash for an identity documents is then the ID for each entity running a D-TA.
+
+In order to create an identity document Milagro D-TA provides the following endpoint.
+
+[POST: /identity](http://localhost:3000/swagger/index.html#/identity/createIdentity) - An Identity Document contains public keys for signing and key encapsulation.
+
+:::note The Milagro DTA communication protocol uses protobufs for serialization.
+[Click here for more information about Protocol Buffers](https://developers.google.com/protocol-buffers/).
+:::
+
+The definition of an identity document is:
+```json
+message IDDocument {
+ string IDDocumentCID = 2 ;
+ string AuthenticationReference = 3 ;
+ string BeneficiaryECPublicKey = 4 ;
+ string SikePublicKey = 5 ;
+ string BlsPublicKey = 6 ;
+ int64 Timestamp = 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 the RC1 release these will be 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"`
+ BlsSecretKey string `json:"BlsSecretKey"`
+}
+```
\ No newline at end of file
diff --git a/docs/dta-details/ipfs.md b/docs/dta-details/ipfs.md
new file mode 100644
index 0000000..1e8d510
--- /dev/null
+++ b/docs/dta-details/ipfs.md
@@ -0,0 +1,13 @@
+---
+id: ipfs
+title: IPFS
+sidebar_label: IPFS
+---
+
+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 organizations. The Milagro D-TA creates immutable, secure and attributable records of every interaction that occurs in the lifecycle of entities 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, an immutability and peer-to-peer consensus is achieved.
+
+:::note We appreciate feedback regarding this approach.
+For more complex consensus requirements, the Milagro D-TA will be implementing [Tendermint](https://tendermint.com/) in following releases.
+:::
diff --git a/docs/dta-details/plugin-dev-guide.md b/docs/dta-details/plugin-dev-guide.md
new file mode 100644
index 0000000..83a6f69
--- /dev/null
+++ b/docs/dta-details/plugin-dev-guide.md
@@ -0,0 +1,65 @@
+---
+id: plugin-dev-guide
+title: D-TA Plugins Developers Guide
+sidebar_label: Developers Guide
+---
+We have provided a template plugin that provides the same functionality as out-of-the-box milagro.
+
+## Developer Notes
+
+You need to install protobufs
+
+If you change the portobufs definition run
+
+$ protoc -I=. --go_out=. ./docs.proto
+
+To add a new endpoint to the goKit Microservices framework
+
+1. First define the contract in milagro/pkg/milagroservice/proto.go
+
+Add structs for http transport
+Add responses to milagro/swagger/swagger.config,yaml
+
+2. Add and endpoint definition
+
+milagro/pkg/milagroendpoints/endpoints.go
+
+3. Create a handler factory
+
+**Thise instructions still aren't perfect**
+
+1. Clone the repo and make sure that it works by following the [Quick Start](/docs/dta-details/quickstart) instructions
+2. Copy the plugin template
+```
+cp -r pkg/plugintemplate pkg/encryptastring
+```
+3. Rename the package and service
+on a mac you could do this...
+```
+sed -i "" "s/template/encryptastring/g" pkg/encryptastring/service.go
+```
+4. Now create a plugin regsitration file
+```
+sed -i "" "s/plugintemplate/encryptastring/g" plugins/encryptastring.go
+sed -i "" "s/pluginTemplate/encryptAString/g" plugins/encryptastring.go
+```
+5. Update the Config File
+```
+nano ~/.milagro/config.yaml
+
+update....
+
+plugins:
+ service: encryptastring
+
+```
+6. See your plugin in action!
+```
+go build -o target/service github.com/apache/incubator-milagro-dta/cmd/service
+target/service
+```
+Point your browser at:
+http://localhost:5555/status
+
+you should see
+
diff --git a/docs/dta-details/quickstart.md b/docs/dta-details/quickstart.md
new file mode 100644
index 0000000..e8ef3dd
--- /dev/null
+++ b/docs/dta-details/quickstart.md
@@ -0,0 +1,88 @@
+---
+id: quickstart
+title: Quick Start
+sidebar_label: Quick Start
+---
+
+## Docker
+The easiest way to see a D-TA in action is to run it in a Docker container. The default settings will run a single D-TA that acts as Principal, Fiduciary and Beneficiary. The default settings include an embedded IPFS node connected to a private IPFS network and an embedded "Bolt" database. This will get you up and running quickly but is **not for production use!**
+
+Please see the repo's [README](https://github.com/apache/incubator-milagro-dta) for alternative build instructions.
+
+```
+git clone https://github.com/apache/incubator-milagro-dta.git
+
+cd incubator-milagro-dta
+
+docker build -t milagrodta .
+
+docker run -it -p 5556:5556 milagrodta
+
+```
+
+Now you can test if the D-TA is running by hitting [http://localhost:5556/v1/status](http://localhost:5556/v1/status)
+
+You should see something like...
+
+```
+{
+"application": "Milagro Distributed Trust",
+"timeStamp": "2019-08-29T11:11:15.9089824Z",
+"apiVersion": "v1",
+"nodeCID": "QmckgCeQRenUk7WHPcD5fxjLxScxyKp5QY1P7GW69NZnR1",
+"extensionVendor": "Milagro",
+"plugin": "milagro"
+}
+
+```
+
+## Plugins
+
+The Milagro D-TA comes with two additional plugins out-of-the box, which are intended to demonstrate how it can be extended.
+
+### Safeguard Secret
+
+The Safeguard Secret plugin encrypts a string with the public key using [ECIES](https://medium.com/asecuritysite-when-bob-met-alice/generating-an-encryption-key-without-a-pass-phrase-meet-ecies-bbea1787d846) and decrypts it when the Fiduciary's D-TA returns the secret key.
+
+**To Run Safeguard Secret**
+```
+docker run -it -p 5556:5556 milagrodta -service safeguardsecret
+```
+### Bitcoin Wallet Security
+
+A Bitcoin Wallet uses a public key (derived from a private key) to create a Bitcoin address. To spend funds from that address, the private key is needed. Insufficient security of private keys has let to billions of dollars in theft. The Principal's Bitcoin Wallet Security plugin receives one half of the public key from the Fiduciary to ultimately create the wallet address. To spend the funds, the Fiduciary D-TA returns a secret to the Beneficiary's D-TA. A process adds this secret to one that is resident within the Principal's D-TA to materialize the wallet's private key.
+
+**To Run Bitcoin Wallet Security**
+```
+docker run -it -p 5556:5556 milagrodta -service bitcoinwallet
+```
+
+You can confirm that the plugins have loaded by hitting [http://localhost:5556/v1/status](http://localhost:5556/v1/status)
+
+## D-TA API
+
+A Swagger description of the API is accessed [via this link.](/swagger/index.html)
+
+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:
+
+1. **Identity Endpoints** - that support creation and retrieval of [identity documents](dta-details/identity-documents.md)
+2. **Order Endpoints**
+ 1. Creates orders for new public keys
+ 2. Requests for secret keys to be transferred
+ 3. Allows orders to be searched and listed
+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
+
+```
+curl -X POST "http://localhost:5556/v1/identity" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"name\":\"thisNode\"}"
+```
+
+
+
+
+
+
+
diff --git a/docs/milagro-intro.md b/docs/milagro-intro.md
index c9fba87..fdab6f6 100644
--- a/docs/milagro-intro.md
+++ b/docs/milagro-intro.md
@@ -16,13 +16,13 @@
Pairings map pairs of points on an elliptic curve into the multiplicative group of a finite field. Their unique properties have enabled many new cryptographic protocols that had not previously been feasible.
-[Pairing-Based Cryptography (PBC)](https://en.wikipedia.org/wiki/Pairing-based_cryptography) is emerging as a solution to complex problems that proved intractable to the standard mathematics of Public-Key Cryptography such as Identity-Based Encryption, whereby the identity of a client can be used as their public key.
+[Pairing-Based Cryptography (PBC)](https://en.wikipedia.org/wiki/Pairing-based_cryptography) is emerging as a solution to complex problems that proved intractable to the standard mathematics of Public-Key Cryptography such as Identity-Based Encryption (IBE), whereby the identity of a client can be used as their public key.
-In certain use cases, this removes the need for a PKI infrastructure eliminates the root key 'single point of compromise' weakness, as the main reason to issue certificates is used to bind a public / private key pair to an identity.
+In certain use cases, this removes the need for a PKI infrastructure as the main reason to issue certificates is to bind a public / private key pair to an identity - a function not required when using IBE.
Removing the certificate management burden enables the identity management and key lifecycle to take place within the decentralized cryptosystem itself.
-As a result, Milagro's decentralized cryptosystem design goals seek to deliver products that are easier to scale and manage that traditional PKI, and are a seamless fit for today's decentralized networks and distributed systems.
+As a result, Milagro's decentralized cryptosystem design goals seek to deliver products that are easier to scale and manage than traditional PKI, eliminate root key 'single point of compromise' weaknesses and are a seamless fit for today's decentralized networks and distributed systems.
## Pairings Go Mainstream
diff --git a/package-lock.json b/package-lock.json
new file mode 100644
index 0000000..48e341a
--- /dev/null
+++ b/package-lock.json
@@ -0,0 +1,3 @@
+{
+ "lockfileVersion": 1
+}
diff --git a/website/sidebars.json b/website/sidebars.json
index ca7db59..4124073 100644
--- a/website/sidebars.json
+++ b/website/sidebars.json
@@ -9,52 +9,26 @@
],
"AMCL Library":
[
- "amcl-overview",
- "amcl-c-api",
- "amcl-javascript-api",
-
- {
- "type": "subcategory",
- "label": "",
- "ids": [
- "cryptojs/aes",
- "cryptojs/big",
- "cryptojs/bls",
- "cryptojs/bls192",
- "cryptojs/bls256",
- "cryptojs/dbig",
- "cryptojs/ecdh",
- "cryptojs/ecp",
- "cryptojs/ecp2",
- "cryptojs/ecp4",
- "cryptojs/ecp8",
- "cryptojs/ff",
- "cryptojs/fp",
- "cryptojs/fp2",
- "cryptojs/fp4",
- "cryptojs/fp8",
- "cryptojs/fp12",
- "cryptojs/fp16",
- "cryptojs/fp24",
- "cryptojs/fp48",
- "cryptojs/gcm",
- "cryptojs/hash256",
- "cryptojs/hash384",
- "cryptojs/hash512",
- "cryptojs/mpin",
- "cryptojs/mpin192",
- "cryptojs/mpin256",
- "cryptojs/pair",
- "cryptojs/pair192",
- "cryptojs/pair256",
- "cryptojs/rand",
- "cryptojs/rsa",
- "cryptojs/sha3",
- "cryptojs/unit64"
- ]
- }
-
+ "amcl-overview",
+ "amcl-c-api",
+ "amcl-javascript-api"
],
+ "Decentralized Trust Authority":
+ [
+ "d-ta-overview",
+ "dta-details/quickstart",
+ "dta-details/api",
+ "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",
+ "zkp-mfa-api"
+ ],
"Project Info": [
"contributor-guide",
"downloads",
diff --git a/website/static/img/dta/Envelope.png b/website/static/img/dta/Envelope.png
new file mode 100644
index 0000000..28f8ff4
--- /dev/null
+++ b/website/static/img/dta/Envelope.png
Binary files differ
diff --git a/website/static/img/dta/RC1-Ecosystem.png b/website/static/img/dta/RC1-Ecosystem.png
new file mode 100644
index 0000000..33826c0
--- /dev/null
+++ b/website/static/img/dta/RC1-Ecosystem.png
Binary files differ
diff --git a/website/static/img/dta/RC1-Overview-1.png b/website/static/img/dta/RC1-Overview-1.png
new file mode 100644
index 0000000..5fdfa85
--- /dev/null
+++ b/website/static/img/dta/RC1-Overview-1.png
Binary files differ
diff --git a/website/static/img/dta/RC1.png b/website/static/img/dta/RC1.png
new file mode 100644
index 0000000..30d7d16
--- /dev/null
+++ b/website/static/img/dta/RC1.png
Binary files differ
diff --git a/website/static/img/dta/initID.png b/website/static/img/dta/initID.png
new file mode 100644
index 0000000..713c6dd
--- /dev/null
+++ b/website/static/img/dta/initID.png
Binary files differ
diff --git a/website/static/swagger/btc.yaml b/website/static/swagger/btc.yaml
new file mode 120000
index 0000000..104b687
--- /dev/null
+++ b/website/static/swagger/btc.yaml
@@ -0,0 +1 @@
+/Users/howardkitto/go/src/github.com/apache/incubator-milagro-dta/pkg/bitcoinplugin/open-api.yaml
\ No newline at end of file
diff --git a/website/static/swagger/index.html b/website/static/swagger/index.html
index 9a4cfb4..1eda16a 100755
--- a/website/static/swagger/index.html
+++ b/website/static/swagger/index.html
@@ -39,7 +39,7 @@
window.onload = function() {
// Begin Swagger UI call region
const ui = SwaggerUIBundle({
- url: "https://raw.githubusercontent.com/apache/incubator-milagro-dta/master/open-api.yaml",
+ url: "https://raw.githubusercontent.com/apache/incubator-milagro-dta/develop/open-api.yaml",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
diff --git a/website/static/swagger/working.yanl b/website/static/swagger/working.yanl
new file mode 100644
index 0000000..951972b
--- /dev/null
+++ b/website/static/swagger/working.yanl
@@ -0,0 +1,389 @@
+openapi: 3.0.0
+info:
+ description: Milagro Secure - distributed / decentralized core security services.
+ title: Apache Milagro Server
+ contact:
+ email: howard@qredo.com
+ license:
+ name: Apache Milagro
+ version: 0.0.1
+paths:
+ /identity:
+ post:
+ summary: Create an identity document
+ tags:
+ - identity
+ operationId: createIdentity
+ # security:
+ # - bearerAuth: []
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: ExampleNodeName
+ responses:
+ '200':
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateIdentityResponse'
+ '400':
+ description: Invalid Request
+ content:
+ text/plain:
+ schema:
+ type: string
+ get:
+ summary: Get a list of identities
+ tags:
+ - identity
+ operationId: getIdentities
+# security:
+# - bearerAuth: []
+ parameters:
+ - name: page
+ in: query
+ description: current page
+ schema:
+ type: integer
+ default: 0
+ - name: perPage
+ in: query
+ description: number of items to show
+ schema:
+ type: integer
+ default: 10
+ - name: sortBy
+ in: query
+ description: Sort By field. Prefix with "-" for descending
+ schema:
+ type: string
+ enum:
+ - dateCreatedAsc
+ - dateCreatedDesc
+ responses:
+ '200':
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/IdentityListResponse'
+ '400':
+ description: Invalid Request
+ content:
+ text/plain:
+ schema:
+ type: string
+servers:
+ - url: 'http://localhost:5556'
+ - url: 'http://localhost:5555'
+components:
+# securitySchemes:
+# bearerAuth:
+# type: http
+# scheme: bearer
+# bearerFormat: JWT
+ schemas:
+ CreateIdentityResponse:
+ type: object
+ properties:
+ IDDocumentCID:
+ type: string
+ IdentityListResponse:
+ type: object
+ properties:
+ IDDocumentList:
+ type: array
+ items:
+ $ref: '#/components/schemas/Identity'
+ Identity:
+ type: object
+ properties:
+ IDDocumentCID:
+ type: string
+ AuthenticationReference:
+ type: string
+ BeneficiaryECPublicKey:
+ type: string
+ SikePublicKey:
+ type: string
+ BlsPublicKey:
+ type: string
+ Timestamp:
+ type: integer
+tags:
+ - name: identity
+ description: Actors in the system
+ externalDocs:
+ url: 'https://milagro.apache.org/docs/milagro-intro/'
+ description: Apache Milagro Docs
+
+# /order:
+# post:
+# summary: Create an order for a new secret
+# tags:
+# - order
+# operationId: createsafe
+# # security:
+# # - bearerAuth: []
+# requestBody:
+# content:
+# application/json:
+# schema:
+# type: object
+# properties:
+# BeneficiaryIDDocumentCID:
+# type: string
+# example: /ipfs/QmUV8LRzTxV4ozHKKAi68wQXBirSjYn4VEtEjEtqusqAQi
+# Extension:
+# type: object
+# ref: '#/component/schemas/Encryptastringreq'
+
+# x-go-name: Body
+# responses:
+# '200':
+# $ref: '#/components/schemas/safesecret'
+ # get:
+ # summary: Get a list of secrets
+ # tags:
+ # - order
+ # operationId: getsafes
+ # security:
+ # - bearerAuth: []
+ # parameters:
+ # - name: page
+ # in: query
+ # description: current page
+ # schema:
+ # type: integer
+ # default: 0
+ # - name: perPage
+ # in: query
+ # description: number of items to show
+ # schema:
+# type: integer
+# default: 10
+# - name: sortBy
+# in: query
+# description: Sort By field. Prefix with "-" for descending
+# schema:
+# type: string
+# enum:
+# - dateCreated
+# - dateModified
+# - -dateCreated
+# - -dateModified
+# responses:
+# '200':
+# description: Successful operation
+# content:
+# application/json:
+# schema:
+# $ref: '#/components/schemas/Arrayofsafesecrets'
+# /order/{orderAddress}:
+# get:
+# summary: Get details of a secret in custody
+# tags:
+# - order
+# operationId: getsafe
+# security:
+# - bearerAuth: []
+# parameters:
+# - name: safesecretAddress
+# in: path
+# description: IPFS hash address of safe secret doc
+# required: true
+# schema:
+# type: string
+# responses:
+# '200':
+# $ref: '#/components/schemas/safesecret'
+# /order/secret:
+# post:
+# summary: Release secret
+# tags:
+# - order
+# operationId: createkey
+# # security:
+# # - bearerAuth: []
+# requestBody:
+# content:
+# application/json:
+# schema:
+# type: object
+# properties:
+# OrderPart2CID:
+# type: string
+# example: /ipfs/QmYcXqMSosRg1XX7P7TqcfNRwqUzdfi2mms6Q9c31QjeYX
+# BeneficiaryIDDocumentCID:
+# type: string
+# example: /ipfs/QmUV8LRzTxV4ozHKKAi68wQXBirSjYn4VEtEjEtqusqAQi
+# responses:
+# '200':
+# $ref: '#/components/schemas/keysecret'
+# /order/pairing:
+# post:
+# summary: Generate and issue a type-3 pairing key
+# tags:
+# - order
+# operationId: createsafe
+# # security:
+# # - bearerAuth: []
+# requestBody:
+# content:
+# application/json:
+# schema:
+# type: object
+# properties:
+# beneficiaryIDDOC:
+# type: string
+# x-go-name: BeneficiaryIDDOC
+# example: '"kjhdhdjd"'
+# coin:
+# type: integer
+# format: int64
+# x-go-name: Coin
+# example: 2
+# x-go-name: Body
+# responses:
+# '200':
+# $ref: '#/components/schemas/safesecret'
+# /fulfill/order:
+# post:
+# summary: Create Public Address
+# tags:
+# - fulfill
+# operationId: fulfillsafe
+# requestBody:
+# content:
+# application/json:
+# schema:
+# type: object
+# properties:
+# safeDocAddress:
+# type: string
+# x-go-name: safeDocAddress
+# example: Qme5S5xVfGYF46oftiLQDevPAGSKy1aggdtrZvvEdiXuqM
+# x-go-name: Body
+# responses:
+# '200':
+# $ref: '#/components/schemas/safesecret'
+# /fulfill/order/secret:
+# post:
+# summary: Return Private Key
+# tags:
+# - fulfill
+# operationId: fulfillkey
+# requestBody:
+# content:
+# application/json:
+# schema:
+# type: object
+# properties:
+# safeDocAddress:
+# type: string
+# x-go-name: keyDocAddress
+# example: Qme5S5xVfGYF46oftiLQDevPAGSKy1aggdtrZvvEdiXuqM
+# x-go-name: Body
+# responses:
+# '200':
+# $ref: '#/components/schemas/safesecret'
+# /fulfill/order/pairing:
+# post:
+# summary: Return mPIN Key
+# tags:
+# - fulfill
+# operationId: fulfillkey
+# requestBody:
+# content:
+# application/json:
+# schema:
+# type: object
+# properties:
+# safeDocAddress:
+# type: string
+# x-go-name: keyDocAddress
+# example: Qme5S5xVfGYF46oftiLQDevPAGSKy1aggdtrZvvEdiXuqM
+# x-go-name: Body
+# responses:
+# '200':
+# $ref: '#/components/schemas/safesecret'
+# /status:
+# get:
+# description: Test Server Health
+# tags:
+# - system
+# operationId: healthcheck
+# responses:
+# '200':
+# description: Successful operation
+# content:
+# application/json:
+# schema:
+# $ref: '#/components/schemas/SystemHealth'
+
+# # security:
+# # - bearerAuth: []
+# components:
+
+
+# Encryptastringreq:
+# type: object
+# properties:
+# plaintext:
+# type: string
+# example: Howard is the greatest
+# CypherText:
+# type: object
+# properties:
+# cypherText:
+# type: string
+# example: 493b17182bb90f3375f77871c05b5b8fd33df23b3b08f128ae50af5e388cafdf
+# t:
+# type: string
+# example: 7b8a80d5a7249fb11a800c69
+# v:
+# type: string
+# example: 044706cdf65b943980c91e86625515d5ac98dc475c0b6097e97dcf826b2b0e414a911920cd37d437b80174a48b24ac4c82aeefbea847082bed8566ef84e9abc031
+
+# safesecret:
+# type: object
+# properties:
+# safesecretAddress:
+# type: string
+# Arrayofsafesecrets:
+# type: array
+# items:
+# $ref: '#/components/schemas/safesecret'
+# keysecret:
+# type: object
+# properties:
+# secretDocAddress:
+# type: string
+# cypherText:
+# type: object
+# items:
+# $ref: "#/components/schemas/cypherText"
+# SystemHealth:
+# type: object
+# properties:
+# timeStamp:
+# type: string
+# testString:
+# type: string
+
+# - name: order
+# description: Send Requests to Principal Node
+# externalDocs:
+# url: 'https://milagro.apache.org/docs/milagro-intro/'
+# description: Apache Milagro Docs
+# - name: fulfill
+# description: Actions performed by the Fiduciary node
+# externalDocs:
+# url: 'https://milagro.apache.org/docs/milagro-intro/'
+# description: Apache Milagro Docs
\ No newline at end of file
