ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-02-15 15:12:46 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Docs: misc markup fixes to corda-bridge-component.rst

Browse Source
This commit is contained in:
Mike Hearn 2018-06-11 15:03:47 +01:00 committed by Mike Hearn
parent cb50e58367
commit b9156baa0b
1 changed files with 50 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
docs/source/corda-bridge-component.rst
View File

@ -5,10 +5,10 @@ Corda Bridge Component Overview
Introduction Introduction
------------ ------------
The Corda ``bridge``/``float`` component is designed for enterprise deployments and acts as an application level The Corda bridge/float component is designed for enterprise deployments and acts as an application level
firewall and protocol break on all internet facing endpoints. The ``corda-bridgeserver.jar`` encapsulates the peer firewall and protocol break on all internet facing endpoints. The ``corda-bridgeserver.jar`` encapsulates the peer
network functionality of the basic Corda ``node``, so that this can be operated separately from the security sensitive network functionality of the basic Corda node, so that this can be operated separately from the security sensitive
JVM runtime of the ``node``. This gives separation of functionality and ensures that the legal identity keys are not JVM runtime of the node. This gives separation of functionality and ensures that the legal identity keys are not
used in the same process as the internet TLS connections. Also, it adds support for enterprise deployment requirements, used in the same process as the internet TLS connections. Also, it adds support for enterprise deployment requirements,
such as High Availability (HA) and SOCKS proxy support. such as High Availability (HA) and SOCKS proxy support.
@ -16,108 +16,108 @@ This document is intended to provide an overview of the architecture and options
Terminology Terminology
----------- -----------
The component referred to here as the ``bridge`` is the library of code responsible for managing outgoing links to peer The component referred to here as the *bridge* is the library of code responsible for managing outgoing links to peer
nodes and implements the AMQP 1.0 protocol over TLS 1.0 between peers to provide reliable flow message delivery. This nodes and implements the AMQP 1.0 protocol over TLS 1.0 between peers to provide reliable flow message delivery. This
component can be run as a simple integrated feature of the ``node``. However, for enhanced security and features on R3 component can be run as a simple integrated feature of the node. However, for enhanced security and features in Corda
Enterprise Corda the in-node version should be turned off and a standalone and HA version can be run from the Enterprise, the in-node version should be turned off and a standalone and HA version can be run from the
``corda-bridgeserver.jar``, possibly integrating with a SOCKS proxy too. ``corda-bridgeserver.jar``, possibly integrating with a SOCKS proxy.
The ``float`` component refers to the inbound socket listener, packet filtering and DMZ compatible component. In the The *float* component refers to the inbound socket listener, packet filtering and DMZ compatible component. In the
simple all-in-one ``node`` all inbound peer connections terminate directly onto an embedded Artemis broker component simple all-in-one node all inbound peer connections terminate directly onto an embedded Artemis broker component
hosted within the ``node``. The connection authentication and packet the filtering is managed directly via Artemis hosted within the node. The connection authentication and packet the filtering is managed directly via Artemis
permission controls managed directly inside the ``node`` JVM. For R3 Enterprise Corda deployments we provide a more permission controls managed directly inside the node JVM. For Corda Enterprise deployments we provide a more
secure and configurable isolation component that is available using code inside ``corda-bridgeserver.jar``. This secure and configurable isolation component that is available using code inside ``corda-bridgeserver.jar``. This
component is designed to provide a clear protocol break and thus prevents the ``node`` and Artemis server ever being component is designed to provide a clear protocol break and thus prevents the node and Artemis server ever being
directly exposed to peers. For simpler deployments with no DMZ the ``float`` and ``bridge`` logic can also be run as a directly exposed to peers. For simpler deployments with no DMZ the float and bridge logic can also be run as a
single application behind the firewall, but still protecting the ``node`` and hosted Artemis. In future we may also host single application behind the firewall, but still protecting the node and hosted Artemis. In future we may also host
the Artemis server out of process and shared across nodes, but this will be transparent to peers as the interchange the Artemis server out of process and shared across nodes, but this will be transparent to peers as the interchange
protocol will continue to be AMQP 1.0 over TLS. protocol will continue to be AMQP 1.0 over TLS.
.. Note:: All deployment modes of the ``bridge``, ``float``, or all-in-one ``node`` are transparently interoperable, if correctly configured. .. Note:: All deployment modes of the bridge, float, or all-in-one node are transparently interoperable, if correctly configured.
Message Path Between Peer Nodes Message Path Between Peer Nodes
------------------------------- -------------------------------
When a flow within a ``node`` needs to send a message to a peer there is a carefully orchestrated sequence of steps to ensure When a flow within a node needs to send a message to a peer there is a carefully orchestrated sequence of steps to ensure
correct secure routing based upon the network map information and to ensure safe, restartable delivery to the remote flow. correct secure routing based upon the network map information and to ensure safe, restartable delivery to the remote flow.
Adding the ``bridge`` and ``float`` to this process adds some extra steps and security checking of the messages. Adding the bridge and float to this process adds some extra steps and security checking of the messages.
The complete sequence is therefore: The complete sequence is therefore:
1. The flow calls ``send``, or ``sendAndReceive`` to propagate a message to a peer. This leads to checkpointing 1. The flow calls ``send``, or ``sendAndReceive`` to propagate a message to a peer. This leads to checkpointing
of the flow fiber within the ``StateMachine`` and posting the message to the internal ``MessagingService``. This ensures that of the flow fiber within the ``StateMachine`` and posting the message to the internal ``MessagingService``. This ensures that
the send activity will be retried if there are any errors before further durable transmission of the message. the send activity will be retried if there are any errors before further durable transmission of the message.
2. The ``MessagingService`` checks if this is a new destination ``node`` and if an existing out queue and bridge exists in Artemis. 2. The ``MessagingService`` checks if this is a new destination node and if an existing out queue and bridge exists in Artemis.
If the durable out queue does not exist then this will need to be created in Artemis: If the durable out queue does not exist then this will need to be created in Artemis:
a. First the durable queue needs to be created in the peer-to-peer Artemis. Each queue is uniquely named based upon the hash of the a. First the durable queue needs to be created in the peer-to-peer Artemis. Each queue is uniquely named based upon the hash of the
legal identity ``PublicKey`` of the target ``node``. legal identity ``PublicKey`` of the target node.
b. Once the queue creation is complete a bridge creation request is also published onto the Artemis bus via the bridge control protocol. b. Once the queue creation is complete a bridge creation request is also published onto the Artemis bus via the bridge control protocol.
This message uses information from the network map to link the out queue to the target host and port and TLS credentials. This message uses information from the network map to link the out queue to the target host and port and TLS credentials.
The flow does not need to wait for any response at this point and can carry on to send messages to the Artemis out queue. The flow does not need to wait for any response at this point and can carry on to send messages to the Artemis out queue.
c. The message when received by the ``bridge`` process opens a TLS connection to the remote peer (optionally, this c. The message when received by the bridge process opens a TLS connection to the remote peer (optionally, this
connection can be made via a SOCKS4/5 proxy). On connect the two ends of the TLS link exchange certificate details connection can be made via a SOCKS4/5 proxy). On connect the two ends of the TLS link exchange certificate details
and confirm that the certificate path is anchored at the network root certificate and that the X500 subject matches and confirm that the certificate path is anchored at the network root certificate and that the X500 subject matches
the expected target as specified in the create bridge message using details contained in the network map. the expected target as specified in the create bridge message using details contained in the network map.
The links are long lived so as to reduce the setup cost of the P2P messaging. The links are long lived so as to reduce the setup cost of the P2P messaging.
In future, there may also be DOS protection measures applied. In future, there may also be denial-of-service protection measures applied.
d. If the outgoing TLS 1.2 link is created successfully then the ``bridge`` opens a consumer on the Artemis out queue. d. If the outgoing TLS 1.2 link is created successfully then the bridge opens a consumer on the Artemis out queue.
The pending messages will then be transferred to the remote destination using AMQP 1.0, with final removal from the The pending messages will then be transferred to the remote destination using AMQP 1.0, with final removal from the
out queue only occurring when the remote end fully acknowledges safe message receipt. This ensures at least once out queue only occurring when the remote end fully acknowledges safe message receipt. This ensures at least once
delivery semantics. delivery semantics.
e. Note that at startup of either the ``node``, or the ``bridge`` the bridge control protocol resynchronises the bridging state, e. Note that at startup of either the node or the bridge, the bridge control protocol resynchronises the bridging state,
so that all out queues have an active bridge. so that all out queues have an active bridge.
3. Assuming an out queue exists the message can be posted to Artemis and the ``bridge`` should eventually deliver this 3. Assuming an out queue exists the message can be posted to Artemis and the bridge should eventually deliver this
message to the remote system. message to the remote system.
4. On receipt of a message acknowledge from Artemis the ``StateMachine`` can continue flow if it is not awaiting a response 4. On receipt of a message acknowledge from Artemis the ``StateMachine`` can continue flow if it is not awaiting a response
i.e. a ``send`` operation. Otherwise it remains suspended waiting for the reply. i.e. a ``send`` operation. Otherwise it remains suspended waiting for the reply.
5. The receiving end of the ``bridge`` TLS/AMQP 1.0 link might be the Artemis broker of a remote ``node``, 5. The receiving end of the bridge TLS/AMQP 1.0 link might be the Artemis broker of a remote node,
but for now we assume it is an enterprise deployment that is using a ``float`` process running behind a firewall. but for now we assume it is an enterprise deployment that is using a float process running behind a firewall.
The receiver will already have confirmed the validity of the TLS originator when it accepted the TLS handshake. The receiver will already have confirmed the validity of the TLS originator when it accepted the TLS handshake.
However, the ``float`` does some further basic checking of received messages and their associated headers. However, the float does some further basic checking of received messages and their associated headers.
For instance the message must be targeted at an inbox address and must be below the network parameters defined ``maxMessageSize``. For instance the message must be targeted at an inbox address and must be below the network parameters defined ``maxMessageSize``.
6. Having passed initial checks on the message the ``float`` bundles up the message and originator as a payload to be 6. Having passed initial checks on the message the float bundles up the message and originator as a payload to be
sent across the DMZ internal firewall. This inbound message path uses a separate AMQP 1.0/TLS control tunnel. sent across the DMZ internal firewall. This inbound message path uses a separate AMQP 1.0/TLS control tunnel.
(N.B. This link is initiated from the local master ``bridge`` in the trusted zone to the ``float`` in the DMZ. This allows a (N.B. This link is initiated from the local master bridge in the trusted zone to the float in the DMZ. This allows a
simple firewall rule to be configured which blocks any attempts to probe the internal network from the DMZ.) simple firewall rule to be configured which blocks any attempts to probe the internal network from the DMZ.)
Once the message is forwarded the ``float`` keeps track of the delivery acknowledgements, Once the message is forwarded the float keeps track of the delivery acknowledgements,
so that the original sender will consume the message in the source queue, only on final delivery to the peer inbox. so that the original sender will consume the message in the source queue, only on final delivery to the peer inbox.
Any disconnections, or problems will send a reject status leading to redelivery from source. Any disconnections, or problems will send a reject status leading to redelivery from source.
7. The ``bridge`` process having now received custody of the message does further checks that the message is good. At the 7. The bridge process having now received custody of the message does further checks that the message is good. At the
minute the checks are essentially of well formedness of the message and that the source and destination are valid. minute the checks are essentially of well formedness of the message and that the source and destination are valid.
However, future enhancements may include deep inspection of the message payload for CorDapp blacklisting, and other purposes. However, future enhancements may include deep inspection of the message payload for CorDapp blacklisting, and other purposes.
Any problems and the message is acknowledged to prevent further redelivery, logged to audit and dropped. Any problems and the message is acknowledged to prevent further redelivery, logged to audit and dropped.
8. Assuming this is a normal message it is passed onto the Artemis inbox and on acknowledgment of delivery 8. Assuming this is a normal message it is passed onto the Artemis inbox and on acknowledgment of delivery
is cascaded back. Thus, Artemis acknowledgement, leads to acknowledgement of the tunnel AMQP packet, is cascaded back. Thus, Artemis acknowledgement, leads to acknowledgement of the tunnel AMQP packet,
which acknowledges the AMQP back to the sending ``bridge`` and that finally marks the Artemis out queue item as consumed. which acknowledges the AMQP back to the sending bridge and that finally marks the Artemis out queue item as consumed.
To prevent this leading to very slow one after the other message delivery the AMQP channels using sliding window flow control. To prevent this leading to very slow one after the other message delivery the AMQP channels using sliding window flow control.
(Currently, a practical default is set internally and the window size is not user configurable.) (Currently, a practical default is set internally and the window size is not user configurable.)
9. The ``MessagingService`` on the peer ``node`` will pick up the message from inbox on Artemis, carry out any necessary 9. The ``MessagingService`` on the peer node will pick up the message from inbox on Artemis, carry out any necessary
deduplication. This deduplication is needed as the distributed restartable logic of the Corda wire protocol only deduplication. This deduplication is needed as the distributed restartable logic of the Corda wire protocol only
offers 'at least once' delivery guarantees. offers 'at least once' delivery guarantees.
The resulting unique messages are then passed to the ``StateMachine`` so that the remote flow can be woken up. The resulting unique messages are then passed to the ``StateMachine`` so that the remote flow can be woken up.
10. The reply messages use the authenticated originator flag attached by the ``float`` to route the replies back to the 10. The reply messages use the authenticated originator flag attached by the float to route the replies back to the
correct originator. correct originator.
.. Note:: That the message reply path is not via the inbound path, but instead is via a separately validated route .. Note:: That the message reply path is not via the inbound path, but instead is via a separately validated route
from the local ``bridge`` to the original ``node``'s ``float`` and then on to the original ``node`` via Artemis. from the local bridge to the original node's float and then on to the original node via Artemis.
Operating modes of the Bridge and Float Operating modes of the Bridge and Float
--------------------------------------- ---------------------------------------
Embedded Developer Node (node + artemis + internal bridge, no float, no DMZ) Embedded Developer Node (node + artemis + internal bridge, no float, no DMZ)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The simplest development deployment of the bridge is to just use the embedded Peer-to-Peer Artemis with the node as TLS endpoint The simplest development deployment of the bridge is to just use the embedded Peer-to-Peer Artemis with the node as TLS endpoint
and to have the outgoing packets use the internal bridge functionality. Typically this should only be used for easy development, and to have the outgoing packets use the internal bridge functionality. Typically this should only be used for easy development,
@ -131,13 +131,13 @@ Node + Bridge (no float, no DMZ)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The next simplest deployment is to turn off the built in bridge using the ``externalBridge`` enterprise config property The next simplest deployment is to turn off the built in bridge using the ``externalBridge`` enterprise config property
and to run a single combined ``bridge``/``float`` process. This might be suitable for a test environment, to conserve VM's. and to run a single combined bridge/float process. This might be suitable for a test environment, to conserve VM's.
.. note:: Note that to run the ``bridge`` and the ``node`` on the same machine there could be a port conflict with a naive setup, .. note:: Note that to run the bridge and the node on the same machine there could be a port conflict with a naive setup,
but by using the ``messagingServerAddress`` property to specify the bind address and port plus setting but by using the ``messagingServerAddress`` property to specify the bind address and port plus setting
``messagingServerExternal = false`` ``messagingServerExternal = false``
the embedded Artemis P2P broker can be set to listen on a different port rather than the advertised ``p2paddress`` port. the embedded Artemis P2P broker can be set to listen on a different port rather than the advertised ``p2paddress`` port.
Then configure an all-in-one ``bridge`` to point at this ``node``: Then configure an all-in-one bridge to point at this node:
.. image:: resources/bridge/simple_bridge.png .. image:: resources/bridge/simple_bridge.png
:scale: 100% :scale: 100%
@ -147,12 +147,12 @@ DMZ ready (node + bridge + float)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To familiarize oneself with the a more complete deployment including a DMZ and separated inbound and outbound paths To familiarize oneself with the a more complete deployment including a DMZ and separated inbound and outbound paths
the ``bridgeMode`` property in the ``bridge.conf`` should be set to ``BridgeInner`` for the ``bridge`` and the ``bridgeMode`` property in the ``bridge.conf`` should be set to ``BridgeInner`` for the bridge and
``FloatOuter`` for the DMZ ``float``. The diagram below shows such a non-HA deployment. This would not be recommended ``FloatOuter`` for the DMZ float. The diagram below shows such a non-HA deployment. This would not be recommended
for production, unless used as part of a cold DR type standby. for production, unless used as part of a cold DR type standby.
.. note:: Note that whilst the ``bridge`` needs access to the official TLS private .. note:: Note that whilst the bridge needs access to the official TLS private
key, the tunnel link should use a private set of link specific keys and certificates. The ``float`` will be provisioned key, the tunnel link should use a private set of link specific keys and certificates. The float will be provisioned
dynamically with the official TLS key when activated via the tunnel and this key will never be stored in the DMZ: dynamically with the official TLS key when activated via the tunnel and this key will never be stored in the DMZ:
.. image:: resources/bridge/bridge_and_float.png .. image:: resources/bridge/bridge_and_float.png
@ -163,7 +163,7 @@ DMZ ready with outbound SOCKS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Some organisations require dynamic outgoing connections to operate via a SOCKS proxy. The code supports this option Some organisations require dynamic outgoing connections to operate via a SOCKS proxy. The code supports this option
by adding extra information to the ``outboundConfig`` section of the ``bridge`` process. An simplified example deployment is shown here by adding extra information to the ``outboundConfig`` section of the bridge process. An simplified example deployment is shown here
to highlight the option: to highlight the option:
.. image:: resources/bridge/bridge_with_socks.png .. image:: resources/bridge/bridge_with_socks.png
@ -173,12 +173,12 @@ to highlight the option:
Full production HA DMZ ready mode (hot/cold node, hot/warm bridge) Full production HA DMZ ready mode (hot/cold node, hot/warm bridge)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Finally, we show a full HA solution as recommended for production. This does require adding an external ``Zookeeper`` Finally, we show a full HA solution as recommended for production. This does require adding an external Zookeeper
cluster to provide ``bridge`` master selection and extra instances of the ``bridge`` and ``float``. This allows cluster to provide bridge master selection and extra instances of the bridge and float. This allows
hot-warm operation of all the ``bridge`` and ``float`` instances. The R3 enterprise Corda ``node`` should be run as hot-cold HA too. hot-warm operation of all the bridge and float instances. The Corda Enterprise node should be run as hot-cold HA too.
Highlighted in the diagram is the addition of the ``haConfig`` section to point at ``zookeeper`` and also the use of secondary Highlighted in the diagram is the addition of the ``haConfig`` section to point at ``zookeeper`` and also the use of secondary
addresses in the ``alternateArtemisAddresses`` to allow ``node`` failover and in the ``floatAddresses`` to point at a addresses in the ``alternateArtemisAddresses`` to allow node failover and in the ``floatAddresses`` to point at a
pool of DMZ ``float`` processes.: pool of DMZ float processes.:
.. image:: resources/bridge/ha_bridge_float.png .. image:: resources/bridge/ha_bridge_float.png
:scale: 100% :scale: 100%