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