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 <[email protected]> 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 [email protected]: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: [email protected] 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
