From 743f514fd95ff053738b4c08c24eebe9123c41ef Mon Sep 17 00:00:00 2001 From: Viktor Kolomeyko Date: Mon, 22 Jan 2018 15:33:04 +0000 Subject: [PATCH] High Level Design decisions for Business Network (#369) * ENT-1331: Placeholder for design decisions previously discussed. * ENT-1331: Describe TLS approach. * ENT-1331: Describe Membership approach. * ENT-1331: Describe Node vs. CordApp membership approaches. * ENT-1331: Including remarks/corrections from @josecoll * ENT-1331: Including remarks/corrections from @josecoll, part 2 --- .../decisions/nodeVsCorDapp.md | 62 ++++++++++++++++ .../decisions/tlsVsMembership.md | 71 +++++++++++++++++++ docs/source/design/businessNetwork/design.md | 5 ++ 3 files changed, 138 insertions(+) create mode 100644 docs/source/design/businessNetwork/decisions/nodeVsCorDapp.md create mode 100644 docs/source/design/businessNetwork/decisions/tlsVsMembership.md diff --git a/docs/source/design/businessNetwork/decisions/nodeVsCorDapp.md b/docs/source/design/businessNetwork/decisions/nodeVsCorDapp.md new file mode 100644 index 0000000000..28a16e8c9b --- /dev/null +++ b/docs/source/design/businessNetwork/decisions/nodeVsCorDapp.md @@ -0,0 +1,62 @@ +![Corda](https://www.corda.net/wp-content/uploads/2016/11/fg005_corda_b.png) + +-------------------------------------------- +Design Decision: Business Network Membership control: Node level or CorDapp level? +============================================ + +## Background / Context + +During discussion of [Business Networks](../design.md) document multiple people voiced concerns +about Business Network membership for different CorDapps deployed on the Corda Node. + +## Options Analysis + +### 1. One set of Business Networks for the whole Node + +The idea is that a Node has knowledge of what Business Networks it is a member of. E.g. a Node will be notified by one or +many BN operator node(s) of it's membership. Configurability and management of Membership is the responsibility of the +BN Operator node with updates are pushed to member Nodes. +In other words, Business Network membership is enforced on the Node level +and **all** the CorDapps installed on a node can communicate with **all** the Business Networks node been included into. + +#### Advantages + +1. Business Network remote communication API will become node level API and it will be a single API to use; +2. The change in Business Network composition will be quickly propagated to all the peer nodes via push mechanism. + +#### Disadvantages + +1. A set of CorDapps may need to be split and hosted by multiple Corda Nodes. A member will need to run a separate +Corda Node for every Business Network it wants to participate in; + + Deployment of a node may be a big deal as it requires new X.500 name, Node registration through + Doorman, separate production process monitoring, etc. + +2. BNO node will have to know about Corda member nodes to push Business Network information to them. Not only this + requires a uniform remote API that every node will have to support, but also member nodes' IP addresses + (which may change from time to time) should be known to BNO node. This might be problematic as with maximum privacy + enforced member node may not be listed on the NetworkMap. + +### 2. Allow CorDapps to specify Business Network name + +The idea is that every CorDapp will be able to specify which Business Network(s) it can work with. +Upon Corda Node start-up (or CorDapp re-load) CorDapps will be inspected to establish super-set of Business Networks +for the current Node run. +After that a call will be made to each of the BNO nodes to inform about Node's IP address such that the node can be +communicated with. + +#### Advantages +1. Flexibility for different CorDapps to work with multiple Business Network(s) which do not have to be aligned; +2. No need for multiple Nodes - a single Node may host many CorDapps which belong to many Business Networks. + +#### Disadvantages +1. Difficult to know upfront which set of Business Networks a Corda Node is going to connect to. + It is entirely dependant on which CorDapps are installed on the Node. + + This can be mitigated by explicitly white-listing Business Networks in Node configuration, such that only intersection + of Business Network name set obtained from CorDapps and Node configuration will be the resulting set of Business Networks + a Node can connect to. + +## Recommendation and justification + +This is a key decision for Technical Design and will be discussed during next Business Network working group meeting. \ No newline at end of file diff --git a/docs/source/design/businessNetwork/decisions/tlsVsMembership.md b/docs/source/design/businessNetwork/decisions/tlsVsMembership.md new file mode 100644 index 0000000000..35cf7b33cf --- /dev/null +++ b/docs/source/design/businessNetwork/decisions/tlsVsMembership.md @@ -0,0 +1,71 @@ +![Corda](https://www.corda.net/wp-content/uploads/2016/11/fg005_corda_b.png) + +-------------------------------------------- +Design Decision: Using TLS signing vs. Membership lists for Business Network composition. +============================================ + +## Background / Context + +As per High Level Design document for [Business Networks](../design.md), there has to be a mechanism established +for composition of the Business Network. + +## Options Analysis + +### 1. Use Transport Layer Security (TLS) signing + +The idea is to employ Public/Private keys mechanism and certification path to be able to prove that certain +member belongs to a Business Network. +Simplified approach can be as follows: +1. NodeA wants to perform communication with NodeB on the assumption that they both belong to the same +Business Network (BN1); +2. During initial handshake each node presents a certificate signed by BNO node confirming that given +node indeed belongs to the said BN1; +3. Nodes cross-check the certificates to ensure that signature is indeed valid. + +#### Advantages + +1. Complete de-centralization. +Even if BNO node is down, as long as it is public key known - signature can be verified. +2. Approach can scale to a great majority of the nodes. + +#### Disadvantages + +1. Revocation of membership becomes problematic; +This could be mitigated by introducing some form of a "blacklist" or by issuing certificates with expiration. But this will +add pressure on BNO node to be more available in order to be able to re-new certificates. +2. Privacy requirement will not be achieved. +Both NodeA and NodeB will have to advertise themselves on the global Network Map, which might be undesired. +3. Cannot produce a list of BN participants; +Since BN participation is established after certificate is checked, it is not quite possible to establish +composition of the Business Network without talking to **each** node in the whole universe of the Compatibility Zone (CZ). + +This has been discussed with Mike Hearn in great details on [this PR](https://github.com/corda/enterprise/pull/101#pullrequestreview-77476717). + +### 2. Make BNO node maintain membership list for Business Network + +The idea is that BNO node will hold a "golden" copy of Business Network membership list and will vend +content to the parties who are entitled to know BN composition. +That said, if an outsider makes an enquiry about composition of Business Network, such request is likely +to be rejected. + +#### Advantages +1. Satisfies all the requirements know so far for Business Network functionality, including: +* Joining/leaving Business Network; +* Privacy; + Privacy is enforced by BNO node that is only going to vend membership information to the parties that need to know. + Also member node no longer has to register with global NetworkMap and may register with BNO instead. +* Ability to discover Business Network peers; +* BNO owner has ultimate control as for how membership information is stored (e.g. DB or CSV file). + +#### Disadvantages +1. BNO node gains a critical role and must be highly available for flows to work within Business Network. +2. When the Business Network will be expanding BNO node need to be reasonably performant to cope with the load. +This can be mitigated by holding local caches of Business Network membership on the Node side to make requests +to BNO node less frequent. +3. There is no pub-sub facility which would allow a member node to learn about new nodes joining Business Network. +But at all times it is possible to approach BNO node and download complete list of current Business Network members. + +## Recommendation and justification + +Proceed with Option 2 after discussion with Mike Hearn and Richard Brown on [this PR](https://github.com/corda/enterprise/pull/101). +The PR was about having Proof of Concept implementation for Business Networks to demonstrate how it might work. \ No newline at end of file diff --git a/docs/source/design/businessNetwork/design.md b/docs/source/design/businessNetwork/design.md index 9667482ac8..3639c34a4e 100644 --- a/docs/source/design/businessNetwork/design.md +++ b/docs/source/design/businessNetwork/design.md @@ -103,6 +103,11 @@ The following requirements are addressed as follows: ## Design Decisions +| Description | Recommendation | Approval | +| ---------------------------------------- | --------------- | ----------------------- | +| [TLS vs. Membership](decisions/tlsVsMembership.md) | Proceed with Membership | Mike Hearn | +| [BN membership: Node vs. CorDapp](decisions/nodeVsCorDapp.md) | TBD | TBD | + * Per [New Network Map](https://r3-cev.atlassian.net/wiki/spaces/AWG/pages/127710793/New+Network+Map): * R3 will serve a file containing NetworkParameters to all members of the Corda Connect Compatibility Zone, made publicly available via CDN. *NetworkParameters are only served by the network map and cannot be overwritten by BNOs*.