messaging subsystem directly. Instead you will build on top of the <aclass="reference internal"href="flow-state-machines.html"><spanclass="doc">flow framework</span></a>,
which adds a layer on top of raw messaging to manage multi-step flows and let you think in terms of identities
<trclass="field-odd field"><thclass="field-name"><codeclass="docutils literal"><spanclass="pre">p2p.inbound</span></code>:</th><tdclass="field-body">The node listens for messages sent from other peer nodes on this queue. Only clients who are authenticated to be
nodes on the same network are given permission to send. Messages which are routed internally are also sent to this
queue (e.g. two flows on the same node communicating with each other).</td>
<trclass="field-even field"><td> </td><tdclass="field-body">These are a set of private queues only available to the node which it uses to route messages destined to other peers.
The queue name ends in the base 58 encoding of the peer’s identity key. There is at most one queue per peer. The broker
creates a bridge from this queue to the peer’s <codeclass="docutils literal"><spanclass="pre">p2p.inbound</span></code> queue, using the network map service to lookup the
<trclass="field-odd field"><td> </td><tdclass="field-body">These are private queues the node may use to route messages to services. The queue name ends in the base 58 encoding
of the service’s owning identity key. There is at most one queue per service identity (but note that any one service
may have several identities). The broker creates bridges to all nodes in the network advertising the service in
question. When a session is initiated with a service counterparty the handshake is pushed onto this queue, and a
corresponding bridge is used to forward the message to an advertising peer’s p2p queue. Once a peer is picked the
<trclass="field-even field"><td> </td><tdclass="field-body">This is another private queue just for the node which functions in a similar manner to the <codeclass="docutils literal"><spanclass="pre">internal.peers.*</span></code> queues
except this is used to form a connection to the network map node. The node running the network map service is treated
differently as it provides information about the rest of the network.</td>
</tr>
<trclass="field-odd field"><thclass="field-name"><codeclass="docutils literal"><spanclass="pre">rpc.requests</span></code>:</th><tdclass="field-body">RPC clients send their requests here, and it’s only open for sending by clients authenticated as RPC users.</td>
<trclass="field-even field"><td> </td><tdclass="field-body">RPC clients are given permission to create a temporary queue incorporating their username (<codeclass="docutils literal"><spanclass="pre">$user</span></code>) and sole
permission to receive messages from it. RPC requests are required to include a random number (<codeclass="docutils literal"><spanclass="pre">$random</span></code>) from
which the node is able to construct the queue the user is listening on and send the response to that. This mechanism
prevents other users from being able listen in on the responses.</td>
</tr>
</tbody>
</table>
</div>
<divclass="section"id="security">
<h2>Security<aclass="headerlink"href="#security"title="Permalink to this headline">¶</a></h2>
<p>Clients attempting to connect to the node’s broker fall in one of four groups:</p>
<olclass="arabic simple">
<li>Anyone connecting with the username <codeclass="docutils literal"><spanclass="pre">SystemUsers/Node</span></code> is treated as the node hosting the broker, or a logical
component of the node. The TLS certificate they provide must match the one broker has for the node. If that’s the case
they are given full access to all valid queues, otherwise they are rejected.</li>
<li>Anyone connecting with the username <codeclass="docutils literal"><spanclass="pre">SystemUsers/Peer</span></code> is treated as a peer on the same Corda network as the node. Their
TLS root CA must be the same as the node’s root CA - the root CA is the doorman of the network and having the same root CA
implies we’ve been let in by the same doorman. If they are part of the same network then they are only given permission
to send to our <codeclass="docutils literal"><spanclass="pre">p2p.inbound</span></code> queue, otherwise they are rejected.</li>
<li>Every other username is treated as a RPC user and authenticated against the node’s list of valid RPC users. If that
is successful then they are only given sufficient permission to perform RPC, otherwise they are rejected.</li>
<li>Clients connecting without a username and password are rejected.</li>
</ol>
<p>Artemis provides a feature of annotating each received message with the validated user. This allows the node’s messaging
service to provide authenticated messages to the rest of the system. For the first two client types described above the
validated user is the X.500 subject DN of the client TLS certificate and we assume the common name is the legal name of
the peer. This allows the flow framework to authentically determine the <codeclass="docutils literal"><spanclass="pre">Party</span></code> initiating a new flow. For RPC clients
the validated user is the username itself and the RPC framework uses this to determine what permissions the user has.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last"><codeclass="docutils literal"><spanclass="pre">Party</span></code> lookup is currently done by the legal name which isn’t guaranteed to be unique. A future version will
use the full X.500 name as it can provide additional structures for uniqueness.</p>
<h2>Messaging types<aclass="headerlink"href="#messaging-types"title="Permalink to this headline">¶</a></h2>
<p>Every <codeclass="docutils literal"><spanclass="pre">Message</span></code> object has an associated <em>topic</em> and may have a <em>session ID</em>. These are wrapped in a <codeclass="docutils literal"><spanclass="pre">TopicSession</span></code>.
An implementation of <codeclass="docutils literal"><spanclass="pre">MessagingService</span></code> can be used to create messages and send them. You can get access to the
messaging service via the <codeclass="docutils literal"><spanclass="pre">ServiceHub</span></code> object that is provided to your app. Endpoints on the network are
identified at the lowest level using <codeclass="docutils literal"><spanclass="pre">SingleMessageRecipient</span></code> which may be e.g. an IP address, or in future
versions perhaps a routing path through the network.</p>
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.
