You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@milagro.apache.org by ki...@apache.org on 2019/08/20 14:18:31 UTC
[incubator-milagro] branch dta/overview updated (88e804a -> 519c551)
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 88e804a various docs
new 151a9fd plugin overview
new 7a35ef2 init developers guide
new 4f2c837 update quick-start
new 4a10dcc update quick-start
new 519c551 updated link to open api spec
The 5 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/d-ta-overview.md | 2 +-
docs/dta-details/quickstart.md | 81 ++++-
docs/dta-plugins/d-ta-plugins.md | 63 ++++
docs/dta-plugins/plugin-dev-guide.md | 44 +++
package-lock.json | 3 +
website/sidebars.json | 10 +-
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 +-
website/static/swagger/open-api.yaml | 411 +++++++++++++++++++++++++
website/static/swagger/working.yanl | 389 +++++++++++++++++++++++
12 files changed, 992 insertions(+), 20 deletions(-)
create mode 100644 docs/dta-plugins/d-ta-plugins.md
create mode 100644 docs/dta-plugins/plugin-dev-guide.md
create mode 100644 package-lock.json
create mode 120000 website/static/swagger/btc-api.yaml
create mode 120000 website/static/swagger/dta-api.yaml
create mode 120000 website/static/swagger/encryptastring-api.yaml
create mode 100644 website/static/swagger/open-api.yaml
create mode 100644 website/static/swagger/working.yanl
[incubator-milagro] 03/05: update quick-start
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 4f2c8378d87d14ecef7a68a1d2e57ae4316f323c
Author: howardkitto <ki...@gmail.com>
AuthorDate: Mon Aug 12 11:28:12 2019 +0100
update quick-start
---
docs/d-ta-overview.md | 2 +-
docs/dta-details/quickstart.md | 79 ++++-
docs/dta-plugins/d-ta-plugins.md | 6 +-
docs/dta-plugins/plugin-dev-guide.md | 39 ++-
website/sidebars.json | 2 +-
website/static/swagger/index.html | 7 +-
website/static/swagger/open-api.yaml | 634 ++++++++++++++++++-----------------
7 files changed, 443 insertions(+), 326 deletions(-)
diff --git a/docs/d-ta-overview.md b/docs/d-ta-overview.md
index b5d4886..6f4cb5f 100644
--- a/docs/d-ta-overview.md
+++ b/docs/d-ta-overview.md
@@ -1,7 +1,7 @@
---
id: d-ta-overview
title: Decentralized Trust Authority Overview
-sidebar_label: D-TA Node Overview
+sidebar_label: D-TA Overview
---
# Introduction
diff --git a/docs/dta-details/quickstart.md b/docs/dta-details/quickstart.md
index 07f0e9e..f0e89f6 100644
--- a/docs/dta-details/quickstart.md
+++ b/docs/dta-details/quickstart.md
@@ -3,38 +3,85 @@ 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 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, called from a front-end application or called from CURL, Postman, Swagger etc.
+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.
-## Configure a Pair
-In order to see Milagro in action you need a pair of servers: a Principal and Fiduciary.
+## Install AMCL
+Milagro D-TA uses the Apache Milagrio Cryptography Library. Before install D-TA AMCL must be installed.
-1. Download and install the Milagro DTA by following these instructions...TBD
-2. By default the server will startup on port 5555, start one node on using this default port, this will be the Fiduciary (custody server)
+```
+git clone git@github.com:apache/incubator-milagro-crypto-c.git
+
+cd incubator-milagro-crypto-c
+
+mkdir build
+
+cd build
+
+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)
-`./milagrodta`
+*GITLAB VERSION*
-3. We will change the config for the Principal (client) node. [Click here to find out more about the configuration options](api-details/configuration.md) If you are building from source the easiest way to change the config is via the configuration file e.g.
+1. Install [the latest version of Go](https://golang.org/dl/)
+
+2. Clone the D-TA source code and build it
```
-/cmd/service/flags.go
+cd ~/go/src
-listen_addr : 5556 /* Choose a port for this server*/
+git clone https://gitlab.com/howardkitto/milagro-custody
-custody_server: http://localhost:5556 /*Point to the Fiduciary (custody) server*/
+./build.sh
```
-Or use command line options like this...
+
+3. Initialise the config
+
+This will put the config and data files in ~/.milagro
+
```
-$ ./milagro-dta -listen-addr :5556 -custody-server http://localhost:5555
+target/setvice init
```
-## Bootstrapping An Identity
+4. Configure the D-TA
-In order to run a Milagro DTA Node it needs to be configured with an identity. 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 by entering a name string.
+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
-(If the server is being restarted it will allow you to select a previously created ID)
+```
+nano ~/.milagro/config.yaml
+
+```
+Give the node a name e.g. testNode by editing the following line:
+```
+nodeName: "testNode"
+
+```
+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
+
+```
+nano ~/.milagro/config.yaml
+
+copy the value of nodeID into masterFiduciaryNodeID e.g.
+
+masterFiduciaryNodeID: QmfWg5GffUEzwahd9hkvdnqTGQs5PfusoEpx3kSDSdG4ze
+nodeID: QmfWg5GffUEzwahd9hkvdnqTGQs5PfusoEpx3kSDSdG4ze
+```
## Hitting the API
diff --git a/docs/dta-plugins/d-ta-plugins.md b/docs/dta-plugins/d-ta-plugins.md
index b8ab7b1..97f1f9a 100644
--- a/docs/dta-plugins/d-ta-plugins.md
+++ b/docs/dta-plugins/d-ta-plugins.md
@@ -9,7 +9,7 @@ Out-of-the-box Milagro D-TA doesn't do much: a Principal gets a public key from
Out of the box Milagro 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 genarates 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 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).
***A Note About Security***
@@ -20,11 +20,11 @@ The Milagro D-TA plugin framework has been designed with following assumptions:
* **Compile-Time**
- Milagro D-TAs are compiled into the Milagro Code - 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...
+ 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 using run time plugins using shared objects using the [Go Plugin Package](https://golang.org/pkg/plugin/) however this presented significant security challenges. We would very much like explorte this idea further with the developer community.
+ 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**
diff --git a/docs/dta-plugins/plugin-dev-guide.md b/docs/dta-plugins/plugin-dev-guide.md
index 7c5df05..4e8354e 100644
--- a/docs/dta-plugins/plugin-dev-guide.md
+++ b/docs/dta-plugins/plugin-dev-guide.md
@@ -3,5 +3,42 @@ 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.
+
+**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
-how to do it
\ No newline at end of file
diff --git a/website/sidebars.json b/website/sidebars.json
index ccf5603..8e753b8 100644
--- a/website/sidebars.json
+++ b/website/sidebars.json
@@ -13,7 +13,7 @@
"amcl-c-api",
"amcl-javascript-api"
],
- "D-TA Node":
+ "Distributed Trust Authority":
[
"d-ta-overview",
{
diff --git a/website/static/swagger/index.html b/website/static/swagger/index.html
index f38264e..15c64da 100755
--- a/website/static/swagger/index.html
+++ b/website/static/swagger/index.html
@@ -39,8 +39,11 @@
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: "./open-api.yaml",
+ url: "https://raw.githubusercontent.com/apache/incubator-milagro-dta/master/open-api.yaml",
+ url: "./encryptastring-api.yaml",
+ // url: "./open-api.yaml",
+ // url: "dta-api.yaml",
+ // url: "btc-api.yaml",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
diff --git a/website/static/swagger/open-api.yaml b/website/static/swagger/open-api.yaml
index 380ef94..877f6a0 100644
--- a/website/static/swagger/open-api.yaml
+++ b/website/static/swagger/open-api.yaml
@@ -1,7 +1,7 @@
openapi: 3.0.0
info:
description: Milagro Secure - distributed / decentralized core security services.
- title: Apache Milagro Server
+ title: Apache Milagro Server - here
contact:
email: howard@qredo.com
license:
@@ -23,109 +23,28 @@ paths:
type: object
properties:
name:
- required: true
type: string
- x-go-name: Name
- example: thisNode
- responses:
- '200':
- description: Successful operation
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/Identity'
- 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/IdentityList'
- /identity/{idDocAddress}:
- get:
- tags:
- - identity
- summary: Get a single identity
- description: Use a known idDocumentAddress to access a single ID document
- operationId: getIdentityByID
- security:
- - bearerAuth: []
- parameters:
- - name: idDocAddress
- in: path
- description: IPFS hash address of user id doc
- required: true
- schema:
- type: string
+ example: ExampleNodeName
responses:
'200':
description: Successful Operation
content:
application/json:
schema:
- $ref: '#/components/schemas/Identity'
- /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
- x-go-name: BeneficiaryIDDocumentCID
- example: '"kjhdhdjd"'
- coin:
- type: integer
- format: int64
- x-go-name: Coin
- example: 2
- x-go-name: Body
- responses:
- '200':
- $ref: '#/components/schemas/safesecret'
+ $ref: '#/components/schemas/CreateIdentityResponse'
+ '400':
+ description: Invalid Request
+ content:
+ text/plain:
+ schema:
+ type: string
get:
- summary: Get a list of secrets
+ summary: Get a list of identities
tags:
- - order
- operationId: getsafes
- security:
- - bearerAuth: []
+ - identity
+ operationId: getIdentities
+# security:
+# - bearerAuth: []
parameters:
- name: page
in: query
@@ -145,27 +64,28 @@ paths:
schema:
type: string
enum:
- - dateCreated
- - dateModified
- - -dateCreated
- - -dateModified
+ - dateCreatedAsc
+ - dateCreatedDesc
responses:
'200':
- description: Successful operation
+ description: Successful Operation
content:
application/json:
schema:
- $ref: '#/components/schemas/Arrayofsafesecrets'
- /order/{orderAddress}:
+ $ref: '#/components/schemas/IdentityListResponse'
+ '400':
+ description: Invalid Request
+ content:
+ text/plain:
+ schema:
+ type: string
+ /identity/{IDDocumentCID}:
get:
- summary: Get details of a secret in custody
+ summary: Get Details of an Identity
tags:
- - order
- operationId: getsafe
- security:
- - bearerAuth: []
- parameters:
- - name: safesecretAddress
+ - identity
+ parameters:
+ - name: IDDocumentCID
in: path
description: IPFS hash address of safe secret doc
required: true
@@ -173,209 +93,319 @@ paths:
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: QmYXqQnEFHD3eRUAuMx6oTQb4ybAdWMnmhgUjuZ9QoAYMr
- BeneficiaryIDDocumentCID:
- type: string
- example: QmYDqFaJvjHYsypfPXahyV4TayGoLWuzS8ZcD73jtT2Hkv
- 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
+ description: Successful Operation
content:
application/json:
schema:
- $ref: '#/components/schemas/SystemHealth'
+ $ref: '#/components/schemas/Identity'
+ '400':
+ description: Invalid Request
+ content:
+ text/plain:
+ schema:
+ type: string
+
servers:
- - url: 'http://localhost:5555'
- url: 'http://localhost:5556'
-# security:
-# - bearerAuth: []
+ - url: 'http://localhost:5555'
components:
- securitySchemes:
- bearerAuth:
- type: http
- scheme: bearer
- bearerFormat: JWT
+# securitySchemes:
+# bearerAuth:
+# type: http
+# scheme: bearer
+# bearerFormat: JWT
schemas:
- Identity:
- type: object
- properties:
- idDocumentAddress:
- type: string
- AuthenticationReference:
- type: string
- BenListenerWalletAddress:
- type: string
- BenSASPubKey:
- type: string
- BenECAddPubKey:
- type: string
- SikePublicKey:
- type: string
- PicnicPublicKey:
- type: string
- Handle:
- type: string
- Email:
- type: string
- Username:
- type: string
- Timestamp:
- type: integer
- IdentityList:
- type: object
- items:
- $ref: '#/components/schemas/IdentityArray'
- IdentityArray:
- type: array
- items:
- $ref: '#/components/schemas/Identity'
- safesecret:
- type: object
- properties:
- safesecretAddress:
- type: string
- Arrayofsafesecrets:
- type: array
- items:
- $ref: '#/components/schemas/safesecret'
- keysecret:
- type: object
- properties:
- secretDocAddress:
- type: string
- SystemHealth:
- type: object
- properties:
- timeStamp:
- type: string
- testString:
- type: string
+ 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
- - 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
+
+# /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: 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
[incubator-milagro] 04/05: update quick-start
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 4a10dcc5cf0762d50315319345d699568d931acd
Author: howardkitto <ki...@gmail.com>
AuthorDate: Mon Aug 12 11:28:26 2019 +0100
update quick-start
---
website/static/swagger/btc-api.yaml | 1 +
website/static/swagger/dta-api.yaml | 1 +
website/static/swagger/encryptastring-api.yaml | 1 +
website/static/swagger/working.yanl | 389 +++++++++++++++++++++++++
4 files changed, 392 insertions(+)
diff --git a/website/static/swagger/btc-api.yaml b/website/static/swagger/btc-api.yaml
new file mode 120000
index 0000000..104b687
--- /dev/null
+++ b/website/static/swagger/btc-api.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/dta-api.yaml b/website/static/swagger/dta-api.yaml
new file mode 120000
index 0000000..393be79
--- /dev/null
+++ b/website/static/swagger/dta-api.yaml
@@ -0,0 +1 @@
+/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
new file mode 120000
index 0000000..3f69414
--- /dev/null
+++ b/website/static/swagger/encryptastring-api.yaml
@@ -0,0 +1 @@
+/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/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
[incubator-milagro] 05/05: updated link to open api spec
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 519c5510ddb30af35192014ea76f0aa99c04eab1
Author: howardkitto <ki...@gmail.com>
AuthorDate: Tue Aug 20 15:18:20 2019 +0100
updated link to open api spec
---
docs/dta-details/quickstart.md | 6 ++++--
website/static/swagger/index.html | 4 ++--
2 files changed, 6 insertions(+), 4 deletions(-)
diff --git a/docs/dta-details/quickstart.md b/docs/dta-details/quickstart.md
index f0e89f6..f11ea25 100644
--- a/docs/dta-details/quickstart.md
+++ b/docs/dta-details/quickstart.md
@@ -6,10 +6,10 @@ 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. Before install D-TA AMCL must be installed.
+Milagro D-TA uses the Apache Milagrio Cryptography Library, so this must installed first
```
-git clone git@github.com:apache/incubator-milagro-crypto-c.git
+git clone https://github.com/apache/incubator-milagro-crypto-c.git
cd incubator-milagro-crypto-c
@@ -17,6 +17,8 @@ mkdir build
cd build
+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
diff --git a/website/static/swagger/index.html b/website/static/swagger/index.html
index 15c64da..27eaea1 100755
--- a/website/static/swagger/index.html
+++ b/website/static/swagger/index.html
@@ -39,8 +39,8 @@
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: "./encryptastring-api.yaml",
+ url: "https://raw.githubusercontent.com/apache/incubator-milagro-dta/howardkitto-patch-1/open-api.yaml",
+ // url: "./encryptastring-api.yaml",
// url: "./open-api.yaml",
// url: "dta-api.yaml",
// url: "btc-api.yaml",
[incubator-milagro] 01/05: plugin overview
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 151a9fd957ce5d5d87c091819c47ccb8e37994d0
Author: howardkitto <ki...@gmail.com>
AuthorDate: Wed Jul 24 16:31:14 2019 +0100
plugin overview
---
docs/dta-plugins/d-ta-plugins.md | 52 +++++
package-lock.json | 3 +
website/sidebars.json | 6 +
website/static/swagger/index.html | 3 +-
website/static/swagger/open-api.yaml | 381 +++++++++++++++++++++++++++++++++++
5 files changed, 444 insertions(+), 1 deletion(-)
diff --git a/docs/dta-plugins/d-ta-plugins.md b/docs/dta-plugins/d-ta-plugins.md
new file mode 100644
index 0000000..610d89b
--- /dev/null
+++ b/docs/dta-plugins/d-ta-plugins.md
@@ -0,0 +1,52 @@
+---
+id: plugins-overview
+title: D-TA Plugins Overview
+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 highly secure, and fully auditable way). However this basic capability unlocks a huge range of potential uses cases, some of which related to the Prinicpal - what the keys can be used for, and some relate to the Master Fiduciary - how the seret key is kept safe (a.k.a. custody). Open source "vanilla" M [...]
+
+Out of the box Milagro comes with two plugins:
+1. Encrypter - 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 genarates a Bitcoin address and the constructs the corresponding secret key only when it is needed (this is a neat trick using eliptic curve magic).
+
+## This is Not Secure
+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 becasue the key pair seed is stored only in the Master Fiduciaries database.
+
+## Approach
+The Milagro D-TA plugin framework has been designed with the following constrains:
+* **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 - so it doesn't do that! (We'd really appreciate you thoughts about that). Ofcourse 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* the Milagro would just become a cool implementation of [ [...]
+ * **Let's Talk** As a community we're excited to add new features to Milagro D-TA. Propose your new end point 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)
+
+* **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:
+ ```
+ POST /order
+
+ Request
+ {
+ "beneficiaryIDDocumentCID" : "IPFSAddress",
+ "extensions":{
+ "plainText":"encryptme"
+ }
+ }
+
+ Response
+ {
+ "OrderPart1CID" : "IPFSAddress",
+ "OrderPart2CID" : "IPFSAddress",
+ "Commitment" : "IPFSAddress",
+ "CreatedAt" : 1563982017,
+ "extensions" : {
+ "cyphertext":"iAmEncrypted"
+ }
+ }
+ ```
+
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 3eb2f13..aa6ad78 100644
--- a/website/sidebars.json
+++ b/website/sidebars.json
@@ -30,6 +30,12 @@
"ids":["api-details/configuration",
"api-details/authentication",
"api-details/api"]
+ },
+ {
+ "type":"subcategory",
+ "label":"D-TA Plugins",
+ "ids":["dta-plugins/plugins-overview"
+ ]
}
],
"ZKP-MFA Clients/Servers": [
diff --git a/website/static/swagger/index.html b/website/static/swagger/index.html
index 9a4cfb4..f38264e 100755
--- a/website/static/swagger/index.html
+++ b/website/static/swagger/index.html
@@ -39,7 +39,8 @@
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/master/open-api.yaml",
+ url: "./open-api.yaml",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
diff --git a/website/static/swagger/open-api.yaml b/website/static/swagger/open-api.yaml
new file mode 100644
index 0000000..380ef94
--- /dev/null
+++ b/website/static/swagger/open-api.yaml
@@ -0,0 +1,381 @@
+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:
+ required: true
+ type: string
+ x-go-name: Name
+ example: thisNode
+ responses:
+ '200':
+ description: Successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Identity'
+ 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/IdentityList'
+ /identity/{idDocAddress}:
+ get:
+ tags:
+ - identity
+ summary: Get a single identity
+ description: Use a known idDocumentAddress to access a single ID document
+ operationId: getIdentityByID
+ security:
+ - bearerAuth: []
+ parameters:
+ - name: idDocAddress
+ in: path
+ description: IPFS hash address of user id doc
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Identity'
+ /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
+ x-go-name: BeneficiaryIDDocumentCID
+ example: '"kjhdhdjd"'
+ coin:
+ type: integer
+ format: int64
+ x-go-name: Coin
+ example: 2
+ 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: QmYXqQnEFHD3eRUAuMx6oTQb4ybAdWMnmhgUjuZ9QoAYMr
+ BeneficiaryIDDocumentCID:
+ type: string
+ example: QmYDqFaJvjHYsypfPXahyV4TayGoLWuzS8ZcD73jtT2Hkv
+ 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'
+servers:
+ - url: 'http://localhost:5555'
+ - url: 'http://localhost:5556'
+# security:
+# - bearerAuth: []
+components:
+ securitySchemes:
+ bearerAuth:
+ type: http
+ scheme: bearer
+ bearerFormat: JWT
+ schemas:
+ Identity:
+ type: object
+ properties:
+ idDocumentAddress:
+ type: string
+ AuthenticationReference:
+ type: string
+ BenListenerWalletAddress:
+ type: string
+ BenSASPubKey:
+ type: string
+ BenECAddPubKey:
+ type: string
+ SikePublicKey:
+ type: string
+ PicnicPublicKey:
+ type: string
+ Handle:
+ type: string
+ Email:
+ type: string
+ Username:
+ type: string
+ Timestamp:
+ type: integer
+ IdentityList:
+ type: object
+ items:
+ $ref: '#/components/schemas/IdentityArray'
+ IdentityArray:
+ type: array
+ items:
+ $ref: '#/components/schemas/Identity'
+ safesecret:
+ type: object
+ properties:
+ safesecretAddress:
+ type: string
+ Arrayofsafesecrets:
+ type: array
+ items:
+ $ref: '#/components/schemas/safesecret'
+ keysecret:
+ type: object
+ properties:
+ secretDocAddress:
+ type: string
+ SystemHealth:
+ type: object
+ properties:
+ timeStamp:
+ type: string
+ testString:
+ type: string
+tags:
+ - name: identity
+ description: Actors in the system
+ externalDocs:
+ url: 'https://milagro.apache.org/docs/milagro-intro/'
+ description: Apache Milagro Docs
+ - 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
[incubator-milagro] 02/05: init developers guide
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 7a35ef207b7c75452082191c0d43fe34bc86be0f
Author: howardkitto <ki...@gmail.com>
AuthorDate: Wed Jul 24 16:57:29 2019 +0100
init developers guide
---
docs/dta-plugins/d-ta-plugins.md | 41 +++++++++++++++++++++++-------------
docs/dta-plugins/plugin-dev-guide.md | 7 ++++++
website/sidebars.json | 4 ++--
3 files changed, 35 insertions(+), 17 deletions(-)
diff --git a/docs/dta-plugins/d-ta-plugins.md b/docs/dta-plugins/d-ta-plugins.md
index 610d89b..b8ab7b1 100644
--- a/docs/dta-plugins/d-ta-plugins.md
+++ b/docs/dta-plugins/d-ta-plugins.md
@@ -4,24 +4,35 @@ title: D-TA Plugins Overview
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 highly secure, and fully auditable way). However this basic capability unlocks a huge range of potential uses cases, some of which related to the Prinicpal - what the keys can be used for, and some relate to the Master Fiduciary - how the seret key is kept safe (a.k.a. custody). Open source "vanilla" M [...]
+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 "vanil [...]
Out of the box Milagro comes with two plugins:
-1. Encrypter - 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 genarates a Bitcoin address and the constructs the corresponding secret key only when it is needed (this is a neat trick using eliptic curve magic).
+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
-## This is Not Secure
-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 becasue the key pair seed is stored only in the Master Fiduciaries database.
+2. **BitCoin Address** - uses the public key to genarates a Bitcoin address and the constructs the corresponding secret key only when it is needed (this is a neat trick using eliptic 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 Master Fiduciary's onboard database - there are obviously better ways do this, contact a Milagro D-TA compatible Custodial Service Provider to find out how...
## Approach
-The Milagro D-TA plugin framework has been designed with the following constrains:
+The Milagro D-TA plugin framework has been designed with following assumptions:
+
+* **Compile-Time**
+
+ Milagro D-TAs are compiled into the Milagro Code - 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 using run time plugins using shared objects using the [Go Plugin Package](https://golang.org/pkg/plugin/) however this presented significant security challenges. We would very much like explorte this idea further with the developer community.
+
* **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 - so it doesn't do that! (We'd really appreciate you thoughts about that). Ofcourse if you run a pair of servers as Principal and Master Fiduciary then they can each run different plugins
+ 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
* **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* the Milagro would just become a cool implementation of [ [...]
- * **Let's Talk** As a community we're excited to add new features to Milagro D-TA. Propose your new end point as a feature (or even submit a PR) and we'll collectively consider adding it
+ 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 [...]
+ * **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)
* **Extensions**
@@ -33,19 +44,19 @@ The Milagro D-TA plugin framework has been designed with the following constrain
Request
{
"beneficiaryIDDocumentCID" : "IPFSAddress",
- "extensions":{
+ "extensions" : {
"plainText":"encryptme"
}
}
Response
{
- "OrderPart1CID" : "IPFSAddress",
- "OrderPart2CID" : "IPFSAddress",
- "Commitment" : "IPFSAddress",
- "CreatedAt" : 1563982017,
+ "orderPart1CID" : "IPFSAddress",
+ "orderPart2CID" : "IPFSAddress",
+ "commitment" : "IPFSAddress",
+ "createdAt" : 1563982017,
"extensions" : {
- "cyphertext":"iAmEncrypted"
+ "cypherText":"iAmEncrypted"
}
}
```
diff --git a/docs/dta-plugins/plugin-dev-guide.md b/docs/dta-plugins/plugin-dev-guide.md
new file mode 100644
index 0000000..7c5df05
--- /dev/null
+++ b/docs/dta-plugins/plugin-dev-guide.md
@@ -0,0 +1,7 @@
+---
+id: plugin-dev-guide
+title: D-TA Plugins Developers Guide
+sidebar_label: Developers Guide
+---
+
+how to do it
\ No newline at end of file
diff --git a/website/sidebars.json b/website/sidebars.json
index aa6ad78..ccf5603 100644
--- a/website/sidebars.json
+++ b/website/sidebars.json
@@ -18,7 +18,7 @@
"d-ta-overview",
{
"type":"subcategory",
- "label":"DTA Details",
+ "label":"D-TA Details",
"ids":[ "dta-details/quickstart",
"dta-details/identity-documents",
"dta-details/encrypted-envelope",
@@ -34,7 +34,7 @@
{
"type":"subcategory",
"label":"D-TA Plugins",
- "ids":["dta-plugins/plugins-overview"
+ "ids":["dta-plugins/plugins-overview", "dta-plugins/plugin-dev-guide"
]
}
],