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 <[email protected]> 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" ] } ],
