corda/docs/source/corda-bridge-component.rst

Corda Bridge Component Overview
===============================

.. contents::

Introduction
------------
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
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
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.

This document is intended to provide an overview of the architecture and options available.

Terminology
-----------
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
component can be run as a simple integrated feature of the ``node``. However, for enhanced security and features on R3
Enterprise Corda 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.

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
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
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
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
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.

.. Note:: All deployment modes of the ``bridge``, ``float``, or all-in-one ``node`` are transparently interoperable, if correctly configured.

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
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.
The complete sequence is therefore:

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
     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.
     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
          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.
          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.

     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
          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 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.

     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
          out queue only occurring when the remote end fully acknowledges safe message receipt. This ensures at least once
          delivery semantics.

     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.

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.

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.

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.
     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.
     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
     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
     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,
     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.

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.
     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.

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,
     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.
     (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
     deduplication. This deduplication is needed as the distributed restartable logic of the Corda wire protocol only
     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.

10.  The reply messages use the authenticated originator flag attached by the ``float`` to route the replies back to the
     correct originator.

     .. 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.

Operating modes of the Bridge and Float
---------------------------------------

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
and to have the outgoing packets use the internal bridge functionality. Typically this should only be used for easy development,
or for organisations evaluating on Open Source Corda, where this is the only available option:

.. image:: resources/bridge/node_embedded_bridge.png
     :scale: 100%
     :align: center

Node + Bridge (no float, no DMZ)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.

 .. 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
            ``messagingServerExternal = false``
            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``:

.. image:: resources/bridge/simple_bridge.png
     :scale: 100%
     :align: center

DMZ ready (node + bridge + float)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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
``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.

.. 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
        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
     :scale: 100%
     :align: center

DMZ ready with outbound SOCKS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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
to highlight the option:

.. image:: resources/bridge/bridge_with_socks.png
     :scale: 100%
     :align: center

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``
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.
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
pool of DMZ ``float`` processes.:

.. image:: resources/bridge/ha_bridge_float.png
     :scale: 100%
     :align: center