8:35 p.m.
JBoss development,
The document "R3.1 Remote Protocol Specification", was updated Jan 6, 2010
by David Lloyd.
To view the document, visit:
http://community.jboss.org/docs/DOC-14535#cf
Document:
--------------------------------------------------------------
h1. Remote Protocol Specification
h2. Table of Contents
*
#Remote_Protocol_Specification
**
#Table_of_Contents
**
#Overview
**
#Message_Format
***
#Framing
***
#Header
****
#First_and_Last_Markers
****
#End_of_Data_Marker
***
#Flow_Control
**
#Negotiation
**
#Security
***
#Confidentiality
***
#Authentication
**
#Remoting_Clients
**
#Remoting_Requests_And_Replies
h2. Overview
The "remote" protocol is the protocol by which two Remoting 3 endpoints may be
connected to communicate with one another. The protocol requirements are:
1. Security: provide authentication and confidentiality support for clients and servers
2. Concurrency: allow multiple clients and requests to be active concurrently
3. Streaming: allow embedded streams
4. Efficiency: Make requests as compact as possible.
5. Performance: Provide equivalent or better latency characteristics than Remoting 2.
h2. Message Format
h3. Framing
Since the "remote" protocol is a message-oriented protocol, and TCP is a
stream-oriented protocol, an additional level of framing is required. The
"remote" protocol uses a simple length-data framing scheme.
Bit #:
7 6 5 4 3 2 1 0
Byte# +---+---+---+---+---+---+---+---+
0 | Length (MSB) |
+-------------------------------+
1 | Length (LSB) |
+-------------------------------+
2+ | Data ... |
| |
: :
. .
Since every message has a predetermined length, the TCP_NODELAY socket option should
*always* be employed to minimize message transmission latency on send.
h3. Header
All regular messages in the "remote" protocol have a common structure. They are
all preceded by a message header, which associates the message with a specific request,
client, or stream channel.
Bit #:
7 6 5 4 3 2 1 0
Byte# +---+---+---+---+---+---+---+---+
0 | L | F | A | X | S.Ch.ID (MSB) |
+---+---+---+---+---+---+---+---+
1 | Source Channel ID (LSB) |
+---+---+---+---+---+---+---+---+
2 | X | X | D | E | D.Ch.ID (MSB) |
+---+---+---+---+---+---+---+---+
3 | Destination Channel ID (LSB) |
+-------------------------------+
4 | Data... |
: :
. .
The meaning of each field is as follows:
* *X* - Reserved, set to 0 for forward compatibility.
* *L* - "Last", indicates that this message will be the last in the stream;
once
* *F* - "First", indicates that this message is the first message in this
direction for a channel pair.
* *A* - "Acknowledge", indicates that a previously received message should be
acknowledged (see *flow control* for more information).
* *D* - "Data", a marker which indicates that the message contains a data
message (with a length of zero or more).
* *E* - "End-of-data", a marker which indicates the end of a substream.
* *Source Channel ID* - the channel ID of the sender.
* *Destination Channel ID* - the channel ID of the recipient.
A subchannel is uniquely identified by a source/destination channel ID pair, not unlike
how unique TCP connections are identified. This means that more than one source channel
ID can be connected to a destination channel ID, and there can be more than one connection
with the same source ID, so long as the destination channel ID is different between each
connection.
h4. First and Last Markers
The First and Last markers on a message delineate the beginning and ending of a
connection. Once a Last marker is read on the remote side, no further data will be
received on the channel. When a Last marker is both sent and received, the associated
channel ID pair becomes free for reuse.
h4. End of Data Marker
The End-of-data marker does not have a significance to the overall protocol; it is used by
the transport to mark the end of a message. The bit will be set on the last packet of
such a message.
h3. Flow Control
Flow control is accomplished by two mechanisms. The first is a negotiated limit on the
number of allowed concurrent subchannels. When this limit is reached, the peer interested
in establishing a new subchannel is forced to wait. If the peer ignores the subchannel
limit, the connection may be terminated immediately.
The second mechanism is a fixed window size associated with each subchannel. For a
subchannel with a window size of +N+, each peer may send up to +N+ messages on that
subchannel without waiting for an "acknowledge" reply. Further messages may not
be sent until a message is received with the "A" bit set, at which time exactly
one message is considered to be acknowledged. If the window size for a subchannel is
disregarded, the connection may be terminated immediately.
Such an acknowledgement may be sent in conjunction with a data message travelling in the
opposite direction, or it may be sent as a standalone (dataless) message.
h2. Negotiation
In order to reach agreement on what features should be available on the connection
(selecting a marshaller, agreeing on parameters such as class tables and so forth), a
negotiation phase is employed after authentication completes but before requests may be
transferred.
h2. Security
h3. Confidentiality
Confidentiality protection is implemented via TLS. All TLS authentication options are
supported, including but not limited to client authentication via TLS. These connection
parameters may be specified as options when the connection is created.
h3. Authentication
Server authentication occurs naturally via the TLS server certificate validation process.
While clients may also be authenticated via this process, SASL-based authentication is
also performed by the server. If, for some reason, client authentication is not desired
via SASL, then a NULL SASL mechanism should be selected. If both client and server
authentication is desired via SASL, then an appropriate mechanism supporting both should
be chosen.
h2. Remoting Clients
h2. Remoting Requests And Replies
--------------------------------------------------------------