This is an automated email from the ASF dual-hosted git repository. kittohoward pushed a commit to branch dta_alphadocs in repository https://gitbox.apache.org/repos/asf/incubator-milagro.git
commit c8dbe11b2e7cc4c44328ce7df3cdd90dbb95b16a Author: howardkitto <[email protected]> AuthorDate: Thu Aug 29 15:28:32 2019 +0100 alpha release first version --- docs/api-details/api.md | 30 +++++++- docs/d-ta-overview.md | 11 +-- docs/dta-details/quickstart.md | 94 +++++++------------------- website/sidebars.json | 23 ++----- website/static/swagger/btc-api.yaml | 1 - website/static/swagger/dta-api.yaml | 1 - website/static/swagger/encryptastring-api.yaml | 1 - website/static/swagger/index.html | 6 +- 8 files changed, 66 insertions(+), 101 deletions(-) diff --git a/docs/api-details/api.md b/docs/api-details/api.md index 2e71961..dc15a4b 100644 --- a/docs/api-details/api.md +++ b/docs/api-details/api.md @@ -4,4 +4,32 @@ title: API sidebar_label: API --- -[API](/swagger/index.html) \ No newline at end of file +Open-api specifications are provided for the core "vanilla" Milagro 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://github.com/apache/incubator-milagro-dta/blob/develop/pkg/bitcoinplugin/open-api.yaml) +* [Safeguard Secret API](https://raw.githubusercontent.com/apache/incubator-milagro-dta/develop/pkg/safeguardsecret/safeguardsecret-api.yaml) + +## Testing The API + +(This assumes that your local DTA is running on port 8888 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. + +Have fun! + + + diff --git a/docs/d-ta-overview.md b/docs/d-ta-overview.md index 6837aa9..d3193ba 100644 --- a/docs/d-ta-overview.md +++ b/docs/d-ta-overview.md @@ -5,19 +5,22 @@ sidebar_label: D-TA Overview --- # Introduction +Milagro D-TA is a colaborative key management server -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. +Milagro D-TA facilitates secure and auditable communication between someone who 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, 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: +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. + +This system can be imagined like a "network HSM". Here is a VERY simplified overview of the process:  ## Milagro DTA Security -The **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. 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 **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 DTA should secure seeds in an HSM using a PKCS#11 interface. -We hope that many custodial services will adopt Milagro as a communication protocol and that they will bring a profusion of security paradigms and that 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 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 DTA Communication Protocol Milagro DTA provides a secure, distributed method of communication between beneficiaries, principals and fiduciaries. It aims to solve the following problems: diff --git a/docs/dta-details/quickstart.md b/docs/dta-details/quickstart.md index f11ea25..1a9273b 100644 --- a/docs/dta-details/quickstart.md +++ b/docs/dta-details/quickstart.md @@ -3,105 +3,57 @@ id: quickstart title: Quick Start sidebar_label: Quick Start --- -Milagro DTA is designed to be built into the workflow of any organisation that needs to trust another organisation to manage encryption keys. It provides a [simple REST api](/swagger/index.html) "out-of-the-box" that can easily be integrated with an existing back office system, called from a front-end application or called from CURL, Postman, Swagger etc. -## Install AMCL -Milagro D-TA uses the Apache Milagrio Cryptography Library, so this must installed first +## 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, Master Fiduciary and Beneficiary. ``` -git clone https://github.com/apache/incubator-milagro-crypto-c.git +git clone https://github.com/apache/incubator-milagro-dta.git -cd incubator-milagro-crypto-c +cd incubator-milagro-dta -mkdir build +docker build -t milagrodta . -cd build +docker run -it -p 5558:5556 milagrodta -brew install cmake (or apt install cmake) - -cmake -D CMAKE_BUILD_TYPE=Release -D BUILD_SHARED_LIBS=ON -D AMCL_CHUNK=64 -D AMCL_CURVE="BLS383" AMCL_CURVE="BLS381" AMCL_CURVE="SECP256K1" -D AMCL_RSA="" -D BUILD_PYTHON=OFF -D BUILD_WCC=OFF -D BUILD_MPIN=ON -D BUILD_X509=OFF -D CMAKE_INSTALL_PREFIX=/usr/local .. - -sudo make install - -``` - -## Install Milagro D-TA from Source -There are two primary roles in a D-TA workflow: the Principal and the Master Fiduciary, as a quick start you can configure one D-TA to provide both roles. (Obviously for a more thorough evaluation configure two servers) - -*GITLAB VERSION* - -1. Install [the latest version of Go](https://golang.org/dl/) - -2. Clone the D-TA source code and build it - -``` -cd ~/go/src - -git clone https://gitlab.com/howardkitto/milagro-custody - -./build.sh - -``` - -3. Initialise the config - -This will put the config and data files in ~/.milagro - -``` -target/setvice init ``` -4. Configure the D-TA - -For quick start a single server is Principal and fiduciary (as described above). -[Click here to find out more about the configuration options](api-details/configuration.md) - -Use an editor of your choice, I'm using nano +Now you can test if the D-TA is running by hitting `http://localhost:8888/v1/status` -``` -nano ~/.milagro/config.yaml - -``` -Give the node a name e.g. testNode by editing the following line: -``` -nodeName: "testNode" +You should see something like... ``` -5. Start the node for the first time. This will generate an identity for the node -``` -target/service daemon -``` -6. Configure the Master Ficuciary -The D-Ta is currently running as a principal, and has also configured itself to be the master fiduciary. `masterFiduciaryServer: http://localhost:5556`. - -However before it can work properly we need to configure the Master Fiduciaries NoeId to be the same as the principal's +{ +"application": "Milagro Distributed Trust", +"timeStamp": "2019-08-29T11:11:15.9089824Z", +"apiVersion": "v1", +"nodeCID": "QmckgCeQRenUk7WHPcD5fxjLxScxyKp5QY1P7GW69NZnR1", +"extensionVendor": "Milagro", +"plugin": "milagro" +} ``` -nano ~/.milagro/config.yaml -copy the value of nodeID into masterFiduciaryNodeID e.g. +## Hitting the API -masterFiduciaryNodeID: QmfWg5GffUEzwahd9hkvdnqTGQs5PfusoEpx3kSDSdG4ze -nodeID: QmfWg5GffUEzwahd9hkvdnqTGQs5PfusoEpx3kSDSdG4ze -``` +The details of the API can be [seen here...](/swagger/index.html) -## Hitting the API +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. **Secret Endpoints** - 1. Creates orders for new secrets +2. **Order Endpoints** + 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 the Principal DTA to communicate with the Fiduciary DTA +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 -The details of the API can be [seen here...](/swagger/index.html) ### Example - To create a new Identity ``` -curl -X POST "http://localhost:5556/identity"; -H "accept: application/json" -H "Content-Type: application/json" -d "{\"name\":\"thisNode\"}" +curl -X POST "http://localhost:8888/v1/identity"; -H "accept: application/json" -H "Content-Type: application/json" -d "{\"name\":\"thisNode\"}" ``` diff --git a/website/sidebars.json b/website/sidebars.json index 8e753b8..04099f2 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -16,28 +16,15 @@ "Distributed Trust Authority": [ "d-ta-overview", + "dta-details/quickstart", + "api-details/api", { "type":"subcategory", "label":"D-TA Details", - "ids":[ "dta-details/quickstart", - "dta-details/identity-documents", - "dta-details/encrypted-envelope", - "dta-details/ipfs"] - }, - { - "type":"subcategory", - "label":"Set Up Instructions", - "ids":["api-details/configuration", - "api-details/authentication", - "api-details/api"] - }, - { - "type":"subcategory", - "label":"D-TA Plugins", - "ids":["dta-plugins/plugins-overview", "dta-plugins/plugin-dev-guide" - ] + "ids":[ + ] } - ], + ], "ZKP-MFA Clients/Servers": [ "zkp-mfa-overview", "zkp-mfa-api" diff --git a/website/static/swagger/btc-api.yaml b/website/static/swagger/btc-api.yaml deleted file mode 120000 index 104b687..0000000 --- a/website/static/swagger/btc-api.yaml +++ /dev/null @@ -1 +0,0 @@ -/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/dta-api.yaml b/website/static/swagger/dta-api.yaml deleted file mode 120000 index 393be79..0000000 --- a/website/static/swagger/dta-api.yaml +++ /dev/null @@ -1 +0,0 @@ -/Users/howardkitto/go/src/github.com/apache/incubator-milagro-dta/open-api.yaml \ No newline at end of file diff --git a/website/static/swagger/encryptastring-api.yaml b/website/static/swagger/encryptastring-api.yaml deleted file mode 120000 index 3f69414..0000000 --- a/website/static/swagger/encryptastring-api.yaml +++ /dev/null @@ -1 +0,0 @@ -/Users/howardkitto/go/src/github.com/apache/incubator-milagro-dta/pkg/encryptastring/encryptastring-api.yaml \ No newline at end of file diff --git a/website/static/swagger/index.html b/website/static/swagger/index.html index 8bcd2b9..3b4eb60 100755 --- a/website/static/swagger/index.html +++ b/website/static/swagger/index.html @@ -39,10 +39,8 @@ window.onload = function() { // Begin Swagger UI call region const ui = SwaggerUIBundle({ - // url: "https://raw.githubusercontent.com/apache/incubator-milagro-dta/howardkitto-patch-1/open-api.yaml";, - // url: "encryptastring-api.yaml", - url: "dta-api.yaml", - // url: "btc-api.yaml", + url: "https://raw.githubusercontent.com/apache/incubator-milagro-dta/develop/open-api.yaml";, + // url: "open-api.yaml", dom_id: '#swagger-ui', deepLinking: true, presets: [
