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:32 UTC
[incubator-milagro] 01/05: plugin overview
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