Internet DRAFT - draft-gfn-race
draft-gfn-race
Network Working Group C. Kilkenny
Internet-Draft Global Financial Networks Limited
Document: draft-gfn-race-00.txt July 2000
Expires: January 9, 2001
RACE Protocol Draft Version 1.3
Status of this Memo
This document is an Internet-Draft and is NOT offered in accordance
with Section 10 of RFC2026, and the author does not provide the IETF
with any rights other than to publish as an Internet-Draft.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other documents
at any time. It is inappropriate to use Internet-Drafts as
reference material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
Copyright Notice
Copyright (C) 1998-2000, Global Financial Networks Limited. All
Rights Reserved.
THE PRESENTATION, DISTRIBUTION OR OTHER DISSEMINATION OF THE
INFORMATION CONTAINED HEREIN BY GLOBAL FINANCIAL NETWORKS LIMITED IS
NOT A LICENSE, EITHER EXPRESSLY OR IMPLIEDLY, TO ANY INTELLECTUAL
PROPERTY OWNED OR CONTROLLED BY GLOBAL FINANCIAL NETWORKS LIMITED.
THIS DOCUMENT AND THE INFORMATION CONTAINED HEREIN IS PROVIDED ON AN
"AS IS" BASIS AND GLOBAL FINANCIAL NETWORKS LIMITED DISCLAIMS ALL
WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE
ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE.
IN NO EVENT WILL GLOBAL FINANCIAL NETWORKS LIMITED BE LIABLE TO ANY
OTHER PARTY FOR THE COST OF PROCURING SUBSTITUTE GOODS OR SERVICES,
LOST PROFITS, LOSS OF USE, LOSS OF DATA, OR ANY INCIDENTAL,
CONSEQUENTIAL, DIRECT, INDIRECT, OR SPECIAL DAMAGES WHETHER UNDER
CONTRACT, TORT, WARRANTY, OR OTHERWISE, ARISING IN ANY WAY OUT OF
THIS OR ANY OTHER AGREEMENT RELATING TO THIS DOCUMENT, WHETHER OR
NOT SUCH PARTY HAD ADVANCE NOTICE OF THE POSSIBILITY OF SUCH
DAMAGES.
C. Kilkenny Expires January 9, 2001 [Page 1]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
Abstract
This document describes the Rapid Application Communication and
Emulation (RACE) Protocol. RACE provides a general framework for
inter-application communication, messaging, and interoperability.
C. Kilkenny Expires January 9, 2001 [Page 2]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
Table of Contents
1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . 4
1.2 Motivation . . . . . . . . . . . . . . . . . . . . . . . 4
1.3 General Considerations . . . . . . . . . . . . . . . . . 6
2. Basic Protocol . . . . . . . . . . . . . . . . . . . . . . . . 8
2.1 Dialogue . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2 Packet Usage . . . . . . . . . . . . . . . . . . . . . . 11
2.3 Service and Application Identifiers . . . . . . . . . . . 13
2.4 Reply and Disconnect Codes . . . . . . . . . . . . . . . 13
3. Protocol Options . . . . . . . . . . . . . . . . . . . . . . . 14
3.1 MODE [Mode of Message Transfer] . . . . . . . . . . . . . 14
3.2 NOREPLY . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.3 WINDOW . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.4 SEQNO [Sequence Number] . . . . . . . . . . . . . . . . . 20
3.5 PDE [Possible Duplicate Emission] . . . . . . . . . . . . 22
3.6 RREF [Receiver Reference] . . . . . . . . . . . . . . . . 24
3.7 LGIAUTH [Login Authentication] . . . . . . . . . . . . . 26
3.8 MSGAUTH [Message Authentication] . . . . . . . . . . . . 28
3.9 LGRP [Logical Grouping] . . . . . . . . . . . . . . . . . 30
3.10 MSGLEN [Message Length] . . . . . . . . . . . . . . . . . 32
3.11 BATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3.12 NOM [Number of Messages] . . . . . . . . . . . . . . . . 36
3.13 BIGFOOT [Big Code Numbering] . . . . . . . . . . . . . . 38
4. Packet Syntax . . . . . . . . . . . . . . . . . . . . . . . . 41
4.1 CONNECT . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.2 DO . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.3 DONT . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.4 WILL . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.5 WONT . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.6 HERE-IS . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.7 READY . . . . . . . . . . . . . . . . . . . . . . . . . . 45
4.8 DISCONNECT . . . . . . . . . . . . . . . . . . . . . . . 45
4.9 MESSAGE . . . . . . . . . . . . . . . . . . . . . . . . . 46
4.10 MESSAGE-REPLY . . . . . . . . . . . . . . . . . . . . . . 47
5. Field Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 49
6. Reply Codes . . . . . . . . . . . . . . . . . . . . . . . . . 52
7. Disconnect Codes . . . . . . . . . . . . . . . . . . . . . . . 53
8. Sample Transmission . . . . . . . . . . . . . . . . . . . . . 57
C. Kilkenny Expires January 9, 2001 [Page 3]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
1. Overview
1.1 Introduction
The Rapid Application Communication and Emulation (RACE) Protocol is
a general framework for inter-application communication, messaging,
and interoperability. The intent of the protocol is to provide a
common interface and facilitate general application-to-application
message transfer.
The RACE Protocol provides a simple, extendable and efficient method
of connecting applications and transferring messages. Applications
assume a basic protocol and can negotiate protocol options in order
to alter the protocol during communication. Applications can be
rapidly integrated, because implementation is straightforward and on
a need only basis. Any complex communication requirement can be
supported, because the protocol is open-ended. For example, the
protocol can support secure data transmission, windowing, data
compression, etc. RACE enables powerful functions by combining
simple protocol options. The protocol is efficient and can achieve
maximum transfer rates.
RACE does not define an application message standard nor does it
interfere with application message objects. Any binary data and,
thereby, any application message can be passed over RACE.
Application level protocols can be layered upon or mapped to RACE,
with or without RACE providing message replies.
Negotiated options facilitate protocol mapping and allow otherwise
incompatible applications to agree a common protocol. Once mapped to
RACE, a protocol can be easily spoken by applications and can be
mapped to other protocols. By decoupling the application from its
messaging, RACE provides a single gateway to multiple protocols and
application interfaces. Communication can be changed without
altering the application whatsoever.
RACE assists in replacing and emulating applications. Once message
syntax has been defined, an application can be replaced and
emulated. RACE does not perform message translation itself, but it
does enable messaging applications and adapters to be used as a
commodity. The RACE approach gives "plug-and-play", which cannot be
achieved using a standard application program interface (API) alone.
RACE offers a fundamental standard, in conjunction with XML, for e-
commerce and application integration. It works well over corporate
networks and the Internet, and gives the kind of flexibility and
throughput, which todayÆs SMTP mail and HTTP systems do not provide.
1.2 Motivation
There is no current standard for inter-application communication.
C. Kilkenny Expires January 9, 2001 [Page 4]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
Messaging has grown enormously and messaging middleware is now
accepted as a key technology. Message queuing middleware (MQM),
which provides asynchronous "put" and "get" services, has become
commonplace. Message brokering (MB) systems are numerous and
beginning to take over the roles of routing, workflow management and
data mapping from legacy applications. The role of middleware has
changed, paving the way for completely new approaches. The growth in
messaging is driven by the need for automation, globalisation, e-
commerce and real-time settlement.
There is an obvious need to standardise inter-application
communication. The number of applications, which need to communicate
with one another, have increased dramatically and integration work
is spiralling out of control. Deployment of MQM and MB systems
creates just as many integration issues as the systems were supposed
to resolve. It is clear that just one messaging middleware solution
is not enough. Customers are frustrated and often feel deceived by
the cost and delay of integration. They want interoperable
applications, which can work together immediately and which can be
used as a commodity.
MQM and MB systems cannot offer a standard for inter-application
communication, because they are proprietary and require an expensive
store and forward infrastructure. Message queuing systems are needed
for queuing, but they are not a standard for connectivity. Off-the-
shelf applications cannot support every system and users cannot be
expected to adopt a single system. Organisations merge and need to
communicate with one another. MQM and MB systems need to communicate
with one another. Often, it is unrealistic to use a third system,
when direct application communication is sufficient.
Standards bodies have been formed in order to address these issues,
but it is too early to expect any conclusive recommendations. The
general approach being taken is to standardise the application
programming interface (API), but whilst this makes sense, it does
not provide a "plug-and-play" solution. "Put" and "get" APIs do not
necessarily lend themselves to "send" and "receive". Run-time
libraries need to be installed and tested before applications can
communicate differently. In some cases, applications may need to be
compiled and linked again. A standard API will also vary with
different programming languages and computing platforms.
What is needed is a common protocol (RACE), in addition to a common
API. A protocol, like an API, is a specification, which can be open
and standard. It does not involve the cost of store and forward for
implementation. A standard protocol allows applications to
communicate with new applications without changing the application
itself. A simple protocol allows easy implementation by the masses.
A flexible protocol facilitates interoperability with other
protocols and messaging adapters.
Existing protocols were not designed for open messaging and are not
appropriate. The Remote Procedure Call (RPC) protocol is intended
for calling remote procedures and allows applications to be
C. Kilkenny Expires January 9, 2001 [Page 5]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
distributed. RPC is a good application communication protocol, but
it lacks the fundamental ability to negotiate. The TELNET Protocol
negotiates, but it is designed for a completely different purpose,
namely to replace and emulate dedicated terminals. There is no
notion of a message in TELNET. Other protocols, which deal with
object definition and content, are a layered function and not the
plumbing standard.
1.3 General Considerations
The RACE Protocol is normally implemented as a Transmission Control
Protocol (TCP) connection, but it can be used on any similar data
transport. RACE assumes a reliable bi-directional asynchronous 8-bit
ordered byte stream. It does not employ TCP Urgent data. For TCP
usage, an assigned port number will be requested in due course.
RACE is a communication protocol between two applications. In order
to form a RACE connection using TCP, one application, known as the
Data Terminal Equipment (DTE), initiates a connect to a second
application, known as the Data Communications Equipment (DCE), which
listens on an assigned port. The DTE (the connecting application)
and DCE (the listening application) can reside on any computer
system or the same computer system. The DTE and DCE can be the same
application. The computer systems where the DTE and DCE applications
reside are known as the DTE host and DCE host respectively.
In practise, a DCE host may service multiple DCE applications on a
single TCP port. In this case, a daemon or server process is needed
on the DCE host. The RACE protocol lends itself to this kind of
concurrency between different DCE applications, but the
implementation of the daemon and the definition of the interface
between daemon and application are outside the scope of this
document. By convention, the DCE daemon is called RACED.
Once connected over TCP, the DTE and DCE applications assume a basic
protocol. The basic protocol allows for connection, negotiation of
protocol options, rudimentary message transfer, and disconnection.
The basic protocol is simple, but it does compromise communication.
In order to deviate from the basic protocol, the DTE can initiate
the negotiation of one or more protocol options. This allows the
actual protocol to be agreed at run-time, giving "plug-and-play".
Each protocol option is documented and assigned a unique number.
Some protocol options use parameters in order to negotiate different
values and usage.
The basic protocol uses one-sided negotiation for simplicity and in
order to avoid infinite negotiation loops. This does not prevent
two-sided negotiation being agreed. The basic protocol allows
parameter data to be included in the initial negotiation sequence,
so that only one round trip is normally required. The basic protocol
limits negotiation to the beginning of the session, so that message
transfer is constant. This does not prevent subsequent negotiation
C. Kilkenny Expires January 9, 2001 [Page 6]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
being agreed. If either DTE or DCE does not agree with the
negotiation result, it can disconnect before entering into message
transfer.
RACE uses varying length packets to transfer data and control
information. These packets are designed for efficient transmission
and can be assembled and interpreted in a straightforward manner.
RACE facilitates assigning names for layered protocols and
applications. Names can have 1 to 64 characters, which gives much
wider scope for naming than TCP port numbers do.
C. Kilkenny Expires January 9, 2001 [Page 7]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
2. Basic Protocol
2.1 Dialogue
By default, RACE is a unidirectional message transfer protocol. On
one side is DTE and on the other side is DCE. Messages are prepared
by DTE and transferred to DCE for interpretation.
The protocol involves five distinct phases:
Phase 1: Connection
After TCP connection, the DTE sends CONNECT in order to specify a
target DCE service and application. If the DCE can accept the
connection, it replies READY. Otherwise, the DCE replies
DISCONNECT, which indicates the reason for exiting (APPNOTAVA,
APPBUSY, etc).
If the DCE has responded DISCONNECT, the DCE and DTE should close
the link, as a corresponding DISCONNECT is not expected from DTE.
Phase 2: Option Negotiation
Once the DCE has accepted the connection, protocol options are
negotiated in the DTEÆs order of preference. If the DTE does not
have any protocol options to negotiate, it can skip the
negotiation phase altogether.
For each supported option, the DTE can either offer it, request
it, or both offer and request it, depending upon the option
specification. In order to offer an option, the DTE sends WILL.
If the DCE would like the DTE to perform the specified option, it
responds DO. Otherwise, it responds DONT. In order to request an
option, the DTE sends DO. If the DCE can perform the specified
option, it responds WILL. Otherwise, it returns WONT.
The DCE need only respond DONT/WONT if it does not support a
protocol option.
Option parameters, if required, are included in DO/WILL according
to the option specification. Once an option has been agreed, it
can be negotiated further using HERE-IS according to the option
specification.
The DTE can send multiple DO/WILL/HERE-IS packets without waiting
for a corresponding DO/DONT/WILL/WONT/HERE-IS packet from the
DCE. However, the DTE must be careful of the order of negotiation
as some options depend upon other options. The DTE should only
send one DO/WILL packet for each supported option unless the
option specifies otherwise.
Negotiation is complete once the DTE has received a
DO/WILL/DONT/WONT reply for each DO/WILL request and any
additional negotiation is complete.
C. Kilkenny Expires January 9, 2001 [Page 8]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
Phase 3: Ready, Ready
In order to end negotiation and enter into message transfer, the
DTE sends READY. If the DCE is satisfied with negotiation, it
replies READY and the two enter into message transfer. Otherwise,
if the DCE does not wish to proceed after receipt of READY, it
replies DISCONNECT instead of READY, which indicates the reason
for exiting (INSNEGOPT).
If the DTE does not wish to proceed after negotiation, it sends
DISCONNECT instead of READY, which indicates the reason for
exiting (INSNEGOPT).
If DCE or DTE has sent DISCONNECT, the DTE and DCE should close
the link, as a corresponding DISCONNECT is not expected.
Phase 4: Message Transfer
For each message to be transferred, the DTE assembles and sends a
MESSAGE and waits for a corresponding MESSAGE-REPLY before going
onto the next message. If the DCE accepts the message, the DCE
responds with a positive MESSAGE-REPLY (SUCCESS). Otherwise, the
DCE responds with a negative MESSAGE-REPLY and details the reason
(INVMSG, ...). The DCE continues servicing incoming messages even
if it rejects some or all of them. The DCE should only use
MESSAGE-REPLY to reject a message and not DISCONNECT.
In the case of an authentication failure, resource failure, etc.,
the DCE may need to abort the connection by sending DISCONNECT.
Phase 5: Shutdown
At some point, either party will want to close the connection.
For unidirectional connections, the message sender will typically
initiate this after transferring its messages, unless a "keep
alive" timer is in effect.
In order to accomplish a graceful shutdown, either DTE or DCE can
send DISCONNECT with code SUCCESS. Upon receipt of DISCONNECT
with code SUCCESS, the other party should complete its processing
and return a corresponding DISCONNECT with code SUCCESS. On
receipt of or after sending the second DISCONNECT, the link can
be closed.
If the DCE has requested shutdown and no DISCONNECT has been
received, it should continue to accept messages and return
replies for a reasonable amount of time. If the DTE receives
DISCONNECT while waiting for a message reply, it should continue
to wait for the message reply and then send a corresponding
DISCONNECT. The DTE should only request shutdown when no message
reply is outstanding and it should not then go onto sending
additional messages.
C. Kilkenny Expires January 9, 2001 [Page 9]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
It should be noted that the shutdown mechanism introduces a
packet, which can be initiated by DCE in the basic protocol. In
addition, the DTE or DCE can abort the connection using
DISCONNECT at any time. Therefore, the DTE needs to be ready to
handle this event.
For example, a basic session:
DTE DCE
--- ---
CONNECT("race$generic","TESTAPPL",) -->
<-- READY()
READY() -->
<-- READY()
MESSAGE("Hello World!") -->
<-- MESSAGE-REPLY(SUCCESS)
DISCONNECT(SUCCESS) -->
<-- DISCONNECT(SUCCESS)
For example, a typical bi-directional session:
DTE DCE
--- ---
CONNECT("race$generic","TESTAPPL",) -->
<-- READY()
DO(MODE,BIDIRECTIONAL) -->
<-- WILL(MODE,BIDIRECTIONAL)
WILL(WINDOW,3) -->
DO(WINDOW,3) -->
<-- DONT(WINDOW)
<-- WONT(WINDOW)
READY() -->
<-- READY()
MESSAGE("1ST CLIENT MSG") -->
<-- MESSAGE-REPLY(SUCCESS)
MESSAGE("2ND CLIENT MSG") --> <-- MESSAGE("1ST HOST MSG")
<-- MESSAGE-REPLY(SUCCESS)
MESSAGE-REPLY(SUCCESS) -->
DISCONNECT(SUCCESS) --> <-- MESSAGE("2ND HOST MSG")
MESSAGE-REPLY(SUCCESS) -->
<-- DISCONNECT(SUCCESS)
For example, the DTE rejects option negotiation:
DTE DCE
--- ---
CONNECT("race$generic","TESTAPPL",) -->
<-- READY()
DO(MODE,OUTPUT) -->
<-- WONT(MODE)
DISCONNECT(INSNEGOPT) -->
C. Kilkenny Expires January 9, 2001 [Page 10]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
For example, the DCE rejects option negotiation:
DTE DCE
--- ---
CONNECT("race$generic","TESTAPPL",)
<-- READY()
READY() -->
<-- DISCONNECT(INSNEGOPT)
In these examples, the MODE and WINDOW protocol options and bi-
directional message transfer are not part of the basic protocol. The
basic protocol only includes the ability to negotiate and not the
options themselves or their associated protocol.
In the event of an unexpected error, like timeout or a protocol
error, the program should, if possible, send DISCONNECT in order to
detail the error and then close the link. A corresponding DISCONNECT
is only expected or sent during the shutdown phase, when DISCONNECT
contains SUCCESS. A corresponding DISCONNECT is not expected unless
message transfer has been agreed, even if DISCONNECT contains
SUCCESS.
2.2 Packet Usage
All RACE packets begin with a packet code and end in the End-Of-
Packet (EOP) sequence. A packet code is a single byte, which
indicates the start of the packet and the packet type. The EOP
sequence consists of the Interpret-As-Command (IAC) byte, value 255,
followed by the EOP byte, value 254. For example,
<200><255><064>Hello World.<255><254>
Here, <200> indicates the start of the packet and identifies it
as a MESSAGE packet. "<255><064>Hello World." is the contents of
the packet. <255><254> indicates the end of the packet.
Most packets comprise of a varying number of variable length fields.
Each field is prefixed by a two-byte sequence and terminated by
either another field prefix or the EOP sequence. A field prefix
consists of the IAC byte followed by a field identifier, whose byte
value is predefined and in the range 0 to 253 inclusive. An optional
field may be omitted. A field may have zero length, in which case
only the field prefix is specified. For example,
<192><255><031>race$generic<255><032>TESTAPPL<255><254>
Here, <192> indicates the start of the packet and identifies it
as a CONNECT packet. <255><031> indicates the start of field 31,
which contains the target service identifier "race$generic".
<255><032> indicates the end of field 31 and the start of field
C. Kilkenny Expires January 9, 2001 [Page 11]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
32, which contains the target application name "TESTAPPL".
<255><254> indicates the end of packet and the end of field 32.
Option negotiation packets, DO/WILL/DONT/WONT/HERE-IS, do not follow
this field prefix notation. Instead, the option code and option
parameters are implicitly identified by position. The option code is
the second byte in the packet and the option parameters, when
included, immediately follow (normally at the third byte) and are
terminated by the EOP sequence. For example,
<193><041><255><254>
Here, <193> identifies a DO packet. The option code <041> is the
second byte in the packet. If present, the option parameters
follow after the option code, but in this example there are no
parameters.
Within a packet, data is eight bit binary data. If byte 255 is used,
it must be doubled in order to prevent misinterpretation. This is
true for both option negotiation packets and packets that use field
prefix notation. Doubling data byte 255 will realign subsequent data
and increase the packet length (during transmission, before
interpretation). For example,
<200><255><064>Data byte "<255><255>" must be doubled.<255><254>
Fields can be embedded within a field or within option negotiation
parameters. For this to work, the IAC byte of each sub-field prefix
has to be doubled so that a first level parser can treat it as
binary data. For each layer of embodiment, the IAC bytes of each
sub-field prefix must be doubled. Consider,
<193><116>
<255><255><031>
<255><255><255><255><020>abcd
<255><255><255><255><021>efgh
<255><255><032>ijkl<255><254>
Here, <193> identifies a DO packet. The option code is the second
byte (116) and the option parameters start at the third byte
until the EOP sequence. <255><255><031> identifies the first
parameter sub-field and <255><255><032> identifies the second
parameter sub-field. The first parameter sub-field, field 31,
contains two more sub-fields, identified by
<255><255><255><255><020> and <255><255><255><255><021>. The two
sub-fields of field 31, fields 20 and 21, contain "abcd" and
"efgh" respectively. The second parameter sub-field, field 32,
contains "ijkl". Notice how the first level uses two IAC bytes
and the second level uses four IAC bytes. This example does not
follow a valid option specification and is only included for
illustration.
RACE does not dictate a maximum packet length. All packets, except
the MESSAGE and MESSAGE-REPLY packets (where the length is
C. Kilkenny Expires January 9, 2001 [Page 12]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
application specific), have a defined maximum length. An option
specification may be drawn up in the future in order for
applications to agree a maximum message length.
2.3 Service and Application Identifiers
The CONNECT packet contains the target service identifier and the
target application identifier. The service identifier identifies the
type of service, while the application identifier identifies the
application name or service instance.
Service identifiers and application names prefixed by "race$" are
reserved for the RACE protocol. Service identifiers and application
names prefixed by a "$" are reserved for assigned names. Currently,
only one RACE service is defined:
race$generic - Generic messaging application
Other services may be added in the future. Future services may
assume a different basic protocol.
2.4 Reply and Disconnect Codes
Code values are used in MESSAGE-REPLY and DISCONNECT in order to
return status information. A code is an unsigned short integer (in
network byte order) as described later in this document.
Applications must be ready to handle codes, which have not yet been
defined, in order to support future versions of the protocol. The
general code, ERROR, can be used to describe an unrecognised code.
When the code is SUCCESS, it can be omitted from MESSAGE-REPLY or
DISCONNECT in order to increase performance. If omitted, SUCCESS is
assumed. For example, <201><255><254> is equivalent to
<201><255><021><000><000><000><000><255><254>.
C. Kilkenny Expires January 9, 2001 [Page 13]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
3. Protocol Options
This chapter contains the RACE protocol option specifications. The
following protocol options are defined:
NAME CODE DESCRIPTION
MODE 33 MODE OF MESSAGE TRANSFER
NOREPLY 34 NO MESSAGE REPLIES
WINDOW 37 MESSAGE WINDOWING
SEQNO 38 SEQUENCE NUMBERING
PDE 53 POSSIBLE DUPLICATE EMISSION FLAG
RREF 54 RECEIVER REFERENCE
LGIAUTH 65 LOGIN AUTHENTICATION
MSGAUTH 66 MESSAGE AUTHENTICATION
LGRP 72 LOGICAL GROUPING
MSGLEN 78 MESSAGE LENGTH
BATCH 41 BATCH FILE TRANSFER
NOM 42 NUMBER OF MESSAGES
BIGFOOT 82 BIG CODE NUMBERING
Protocol options may be defined in the near future for:
- Encryption
- Data compression
- Checksum calculation
- Polling of messages and files (client/server, get/put)
- Block transfer of messages and files
- Multiplexing
3.1 MODE [Mode of Message Transfer]
Identification
Name: MODE, Code = 33
Dependencies: n/a
Overview
The MODE protocol option enables the transfer of messages from
DCE to DTE or bi-directional message transfer. By default, the
basic protocol only supports unidirectional message transfer from
DTE to DCE.
This option uses the following terminology in order to describe
the direction of message transfer:
- INPUT : One way from DTE to DCE (the default)
- OUTPUT : One way from DCE to DTE
- BIDIRECTIONAL : Two way (either direction independently)
OUTPUT (from DCE to DTE) and BIDIRECTIONAL message transfer are
similar to INPUT (from DTE to DCE) message transfer. Once message
transfer has been agreed, either party can send messages
C. Kilkenny Expires January 9, 2001 [Page 14]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
depending upon the agreed mode. For OUTPUT message transfer, the
DCE and DTE switch roles in sending and receiving messages. For
BIDIRECTIONAL message transfer, each direction works
independently and both DCE and DTE can send and receive. The
rules of the basic protocol need to be followed in order to
achieve graceful shutdown: the sender behaves like the DTE in the
basic protocol and the receiver like the DCE in the basic
protocol.
If a message is received in the wrong direction, the receiving
application should disconnect with code PRTCOLERR. This option
will affect other protocol options, which are dependent upon the
direction of message transfer.
Motivation
Inter-application communication often requires OUTPUT and
BIDIRECTIONAL message transfer, in addition to INPUT message
transfer. The MODE protocol option extends the basic protocol in
order to support this functionality.
Negotiation
DTE and DCE may support one or more modes (INPUT, OUTPUT or
BIDIRECTIONAL). The resultant mode is obtained by negotiating the
supported modes in DTEÆs order of preference. Initially, INPUT is
assumed. Then, the two negotiate and assume the final mode
returned by DCE.
If the DTE only supports INPUT message transfer, INPUT is assumed
and negotiation does not take place.
If the DTE would like to use BIDIRECTIONAL message transfer, it
sends "DO MODE BIDIRECTIONAL":
<193><033><003><255><254> -->
If the DCE supports BIDIRECTIONAL message transfer, it responds
"WILL MODE BIDIRECTIONAL" and BIDIRECTIONAL message transfer
becomes agreed:
<-- <195><033><003><255><254>
Otherwise, if the DCE does not support BIDIRECTIONAL message
transfer, it responds "WONT MODE" and INPUT message transfer
remains agreed:
<-- <196><033><255><254>
If the DTE or DCE does not support BIDIRECTIONAL message transfer
and the DTE would like to use OUTPUT message transfer, the DTE
sends "DO MODE OUTPUT":
<193><033><002><255><254> -->
C. Kilkenny Expires January 9, 2001 [Page 15]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
If the DCE supports OUTPUT message transfer, it responds "WILL
MODE OUTPUT" and OUTPUT message transfer becomes agreed:
<-- <195><033><002><255><254>
Otherwise, if the DCE does not support OUTPUT message transfer,
it responds "WONT MODE" and INPUT message transfer remains
agreed:
<-- <196><033><255><254>
If the application does not support the resultant mode, it should
disconnect using code INSNEGOPT.
Parameters
{mode}
Mode is an unsigned byte, which indicates the direction of
message transfer. Possible values are 3 for BIDIRECTIONAL or 2
for OUTPUT. Any other value is invalid.
Examples
DTE supports BIDIRECTIONAL, OUTPUT and INPUT; DCE supports
OUTPUT; they agree OUTPUT.
<193><033><003><255><254> -->
<-- <196><033><255><254>
<193><033><002><255><254> -->
<-- <195><033><002><255><254>
DTE supports OUTPUT; DCE does not understand the MODE option and
only supports INPUT; they agree INPUT. The DTE subsequently
disconnects.
<193><033><002><255><254> -->
<-- <196><033><255><254>
DTE supports BIDIRECTIONAL; DCE supports INPUT; they agree INPUT.
The DTE subsequently disconnects.
<193><033><003><255><254> -->
<-- <196><033><255><254>
DTE supports INPUT; DCE supports BIDIRECTIONAL; they agree INPUT.
The DCE subsequently disconnects.
Negotiation does not take place.
Two negotiations are rarely needed, since the DTE normally
supports just one mode of message transfer.
C. Kilkenny Expires January 9, 2001 [Page 16]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
3.2 NOREPLY
Identification
Name: NOREPLY, Code = 34
Dependencies: MODE
Overview
The NOREPLY protocol option turns off message replies. In the
basic protocol, a MESSAGE-REPLY is expected for every MESSAGE
sent. When this option is in effect, message replies are not
used.
This option can be used with any mode (INPUT, OUTPUT or
BIDIRECTIONAL). With BIDIRECTIONAL message transfer, applications
can provide synchronisation at the application level. With INPUT
or OUTPUT message transfer, applications fire and forget. If
delivery confirmation is not required, message transfer without
RACE or application level replies may prove efficient.
It should be noted that a DISCONNECT packet may be waiting in a
packet stream.
If a message reply is received and replies have been disabled,
the receiving application should disconnect with code PRTCOLERR.
This option will affect other protocol options, which are
dependent upon the existence of message replies. The MODE option
should be negotiated before the NOREPLY option.
Motivation
Many application level protocols use application specific replies
and some applications fire and forget messages. In conjunction
with the MODE option, this option extends RACE to a wide variety
of applications and application level protocols. When given the
choice though, it is preferable to map an application level
protocol with RACE message replies rather than layer an
application level protocol without RACE message replies.
Negotiation
NOREPLY is negotiated separately for input and output message
transfer.
If the DTE would like to disable message replies (for the input
stream), it sends "DO NOREPLY":
<193><034><255><254> -->
If the DCE can disable message replies (for the input stream), it
responds "WILL NOREPLY":
<-- <195><034><255><254>
C. Kilkenny Expires January 9, 2001 [Page 17]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
Otherwise, if the DCE cannot disable message replies (for the
input stream), it responds "WONT NOREPLY":
<-- <196><034><255><254>
If the DTE can disable message replies (for the output stream),
it sends "WILL NOREPLY":
<195><034><255><254> -->
If the DCE would like to disable message replies (for the output
stream), it responds "DO NOREPLY":
<-- <193><034><255><254>
Otherwise, if the DCE does not want to disable message replies
(for the output stream), it responds "DONT NOREPLY":
<-- <194><034><255><254>
Parameters
None.
Examples
Mode is BIDIRECTIONAL; DTE and DCE agree to turn off message
replies:
<193><034><255><254> -->
<195><034><255><254> -->
<-- <195><034><255><254>
<-- <193><034><255><254>
Mode is BIDIRECTIONAL; DTE wants to turn off message replies, but
DCE needs them enabled. Message replies are disabled for the
input stream and enabled for the output stream:
<193><034><255><254> -->
<195><034><255><254> -->
<-- <195><034><255><254>
<-- <194><034><255><254>
3.3 WINDOW
Identification
Name: WINDOW, Code = 37
Dependencies: MODE, NOREPLY
Overview
C. Kilkenny Expires January 9, 2001 [Page 18]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
The WINDOW protocol option permits more than one message to be
sent without waiting for a message reply. The term window refers
to the number of outstanding messages for which a message reply
has not been received.
A small window of about three greatly increases performance. A
large window does not give much improvement. A window of one
represents the default behaviour of the basic protocol.
If replies have been disabled, this option has no effect.
If the link fails, the other application may not have received
more than one message in the window.
Motivation
By default, a message reply has to be received before the next
message can be sent. This wastes time. Data transfer is much
faster if multiple messages can be prepared and sent before a
reply is received. This allows the receiver to process messages
whilst the sender is preparing and sending messages, and messages
or message replies are in transit.
Negotiation
WINDOW is negotiated separately for input and output message
transfer.
If the DTE would like to use a window size greater than one (for
the input stream), it sends "DO WINDOW" and specifies the desired
window size:
<193><037>{window-size}<255><254> -->
If the DCE supports windowing (for the input stream), it responds
"WILL WINDOW" with the actual window size. The actual window size
should be lower than or equal to the requested window size:
<-- <195><037>{window-size}<255><254>
Otherwise, if the DCE does not support a window greater than one
(for the input stream), it responds "WONT WINDOW":
<-- <196><037><255><254>
If the DTE supports windowing (for the output stream), it sends
"WILL WINDOW" with its maximum window size:
<195><037>{window-size}<255><254> -->
If the DCE would like to use a window size greater than one (for
the output stream), it responds "DO WINDOW" with the actual
window size. The actual window size must be lower than or equal
to the offered window size.
C. Kilkenny Expires January 9, 2001 [Page 19]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
<-- <193><037>{window-size}<255><254>
Otherwise, if the DCE does not want to use windowing (for the
output stream), it responds "DONT WINDOW":
<-- <194><037><255><254>
If either party does not support windowing, a window size of one
is assumed (the default).
Parameters
{window-size}
The window size is an unsigned byte containing any value in the
range 1 to 127 inclusive. Values outside the range are not
allowed.
Examples
Mode is INPUT; DTE wants an input window of 10; DCE supports an
input window of 3. They agree to use an input window of 3.
<193><037><010><255><254> -->
<-- <195><037><003><255><254>
Mode is OUTPUT; DTE supports an output window of 2; DCE does not
understand this option and only supports an output window of 1.
They agree to use an output window of 1.
<195><037><002><255><254> -->
<-- <194><037><255><254>
Mode is BIDIRECTIONAL; DTE supports an input window of 3 and an
output window of 3; DCE supports an input window of 2 and an
output window of 1. They agree to use an input window of 2 and an
output window of 1.
<193><037><003><255><254> -->
<195><037><003><255><254> -->
<-- <195><037><002><255><254>
<-- <193><037><001><255><254> (DONT can also be used here)
3.4 SEQNO [Sequence Number]
Identification
Name: SEQNO, Code = 38
Dependencies: MODE, NOREPLY
Overview
C. Kilkenny Expires January 9, 2001 [Page 20]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
The Sequence Number (SEQNO) protocol option allows messages and
message replies to be numbered in the order in which they are
transmitted. If agreed, the sending party must include an
incremental sequence number with every message sent and the
receiving party must include the same sequence number in each
corresponding message reply. It is the responsibility of the
message receiver to check the sequence numbering of messages and
it is the responsibility of the message sender to check the
sequence numbering of message replies.
F10 is included in the MESSAGE and MESSAGE-REPLY packets in order
to detail the sequence number. F10 contains an unsigned short
integer in network byte order. Sequence numbers start at one at
the beginning of a new connection, increment by one, and wrap
back to one upon reaching 65,536 (i.e. 65,536, 131,071, ...
become 1). Zero is not a valid sequence number. Data byte 255
must be doubled. Each party maintains a separate sequence number
counter for each direction of message transfer. For example,
<200><255><010><000><021><255><064>MY MESSAGE<255><254> -->
<-- <201><255><010><000><021><255><254>
Here, the message and the positive message reply have sequence
number twenty-one.
Sequence numbers are only used to check the sequencing of
messages and message replies during a connection. There is no
point in storing the sequence number with the message after
transmission or upon receipt.
If an invalid sequence number is encountered for a message or a
message reply, the application, which detected the error, should
disconnect with code INVSEQNO.
Motivation
Sequence numbering is not generally necessary, because RACE
assumes a reliable transport. Message replies are returned in the
order in which messages are received. However, it is often asked
or expected for a RACE connection to support sequence numbering.
So, this option allows for it. By default, sequence numbering is
not used in order to keep transmissions efficient.
Negotiation
If the DTE can offer sequence numbering (for all directions of
message transfer), it sends "WILL SEQNO":
<195><038><255><254> -->
If the DCE wants sequence numbering (for all directions of
message transfer), it replies "DO SEQNO":
<-- <193><038><255><254>
C. Kilkenny Expires January 9, 2001 [Page 21]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
Otherwise, the DCE replies "DONT SEQNO":
<-- <194><038><255><254>
If the DTE wants sequence numbering (for all directions of
message transfer), it sends "DO SEQNO" instead of "WILL SEQNO":
<193><038><255><254> -->
If the DCE can offer sequence numbering (for all directions of
message transfer), it replies "WILL SEQNO":
<-- <195><038><255><254>
Otherwise, the DCE replies "WONT SEQNO":
<-- <196><038><255><254>
In order to keep transmissions efficient, applications need only
offer SEQNO, but not request it.
Parameters
None.
Examples
Both DTE and DCE support sequence numbering, but neither mandate
sequence numbering. Sequence numbering is not used.
<195><038><255><254> -->
<-- <194><038><255><254>
DTE mandates sequence numbering, but DCE does not support it.
Sequence numbering is not used.
<193><038><255><254> -->
<-- <196><038><255><254>
DTE supports sequence numbering and DCE mandates it. Sequence
numbering is used.
<195><038><255><254> -->
<-- <193><038><255><254>
3.5 PDE [Possible Duplicate Emission]
Identification
Name: PDE, Code = 53
Dependencies: MODE
C. Kilkenny Expires January 9, 2001 [Page 22]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
Overview
The Possible Duplicate Emission (PDE) protocol option allows use
of a PDE flag. Once enabled, the sender must include the PDE flag
with messages, which may have already been sent. Likewise, the
receiver must treat messages as possible duplicates if the PDE
flag is present.
F65 is included in the MESSAGE packet in order to indicate the
PDE flag. F65 is an unsigned byte containing a binary one. For
example,
<200><255><064>Testing 123<255><065><001><255><254>
The presence of F65 indicates that this MESSAGE is a possible
duplicate emission.
An application should only agree to use the PDE flag if it can
properly detect or process the PDE flag. If F65 is encountered
when this option is not in effect, the receiving application
should disconnect with code INVPKTFID.
Motivation
This option facilitates the detection of duplicate transmissions.
Some application level protocols support the use of a PDE flag.
This option allows RACE to be better mapped to these protocols.
Negotiation
PDE is negotiated separately for input and output message
transfer.
If the DTE can provide the PDE flag (for the input stream), it
sends "WILL PDE":
<195><053><255><254> -->
If the PDE information is useful to the DCE (for the input
stream), it responds "DO PDE":
<-- <193><053><255><254>
Otherwise, if the DCE does not want to receive PDE information
(for the input stream), it responds "DONT PDE":
<-- <194><053><255><254>
If the PDE information is useful to the DTE (for the output
stream), it sends "DO PDE":
<193><053><255><254> -->
C. Kilkenny Expires January 9, 2001 [Page 23]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
If the DCE can provide the PDE flag (for the output stream), it
responds "WILL PDE":
<-- <195><053><255><254>
Otherwise, if the DCE cannot provide the PDE flag (for the output
stream), it responds "WONT PDE":
<-- <196><053><255><254>
Parameters
None.
Examples
Mode is BIDIRECTIONAL; Both DTE and DCE support PDE.
<195><053><255><254> -->
<193><053><255><254> -->
<-- <193><053><255><254>
<-- <195><053><255><254>
Mode is INPUT; DTE supports PDE, but DCE does not.
<195><053><255><254> -->
<-- <194><053><255><254>
3.6 RREF [Receiver Reference]
Identification
Name: RREF, Code = 54
Dependencies: MODE, NOREPLY
Overview
The Receiver Reference (RREF) protocol option allows the message
sender to get a unique identifier from the receiver for each
message sent. This assists in investigation and reconciliation.
Once agreed, the message receiver returns a unique message
reference for every message using the MESSAGE-REPLY packet.
F24 is included in the MESSAGE-REPLY packet in order to return
the unique message reference. F24 may contain 1 to 64 ASCII
characters, byte value 32 through 126 inclusive. As a matter of
good practise, it is recommended to keep the reference to
alphanumeric characters without leading or training spaces. For
example,
<201><255><024>DEF200105106E059<255><254>
C. Kilkenny Expires January 9, 2001 [Page 24]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
F24 in this MESSAGE-REPLY packet contains "DEF200105106E059",
which uniquely identifies the received message.
If a message is rejected, a unique message reference is still
expected. If the receiving application does not allocate
references for rejected messages, a pseudo reference should be
used. For example, use the date and a counter that spans the day
and is specific to the connection. References should be unique
even if multiple application instances are used or different
connections share the same application.
If replies have been disabled, this option has no effect.
Motivation
Many applications store transactions using a primary key or a
transaction reference number. Sometimes, this information is
needed by the sending application for subsequent investigation
and reconciliation. A unique message reference is evidence that
message transfer has taken place.
Negotiation
RREF is negotiated separately for input and output message
transfer.
If the DTE would like to receive RREF (for the input stream), it
sends "DO RREF":
<193><054><255><254> -->
If the DCE can supply RREF (for the input stream), it responds
"WILL RREF":
<-- <195><054><255><254>
Otherwise, if the DCE cannot supply RREF (for the input stream),
it responds "WONT RREF":
<-- <196><054><255><254>
If the DTE can supply RREF (for the output stream), it sends
"WILL RREF":
<195><054><255><254> -->
If the DCE would like to receive RREF (for the output stream), it
responds "DO RREF":
<-- <193><054><255><254>
Otherwise, if the DCE does not want to receive RREF (for the
output stream), it responds "DONT RREF":
C. Kilkenny Expires January 9, 2001 [Page 25]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
<-- <194><054><255><254>
Parameters
None.
Examples
Mode is BIDIRECTIONAL; DTE wants RREF, but canÆt offer it; DCE
doesnÆt want RREF, but can offer it.
<193><054><255><254> -->
<-- <195><054><255><254>
Mode is INPUT; DTE wants RREF; DCE doesnÆt support this option
and canÆt offer it:
<193><054><255><254> -->
<-- <196><054><255><254>
Mode is OUTPUT; DTE can offer RREF; DCE doesnÆt want RREF.
<195><054><255><254> -->
<-- <194><054><255><254>
3.7 LGIAUTH [Login Authentication]
Identification
Name = LGIAUTH, Code = 65
Dependencies: n/a
Overview
The Login Authentication (LGIAUTH) protocol option allows
applications to authenticate each other when the connection is
opened. The authentication keys and identification of the
authentication algorithm are agreed and distributed by some other
means.
Both applications can be authenticated separately. The requesting
application sends a string to the other application for
authentication. The other application calculates and returns an
authentication code. The requesting application then calculates
the authentication code again and compares it with the received
authentication code. If the codes match, authentication passes.
If authentication fails, the application, which expected to
receive an authentication code, can either abort the connection
immediately or wait until the end of negotiation. In either case,
the authenticating application should send DISCONNECT with code
LGIFAIL.
C. Kilkenny Expires January 9, 2001 [Page 26]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
Motivation
By default, a RACE connection is not secure. This option allows
two co-operating applications to authenticate access.
Negotiation
If the DTE can supply login authentication, it sends "WILL
LGIAUTH":
<195><065><255><254> -->
If the DCE would like to receive login authentication, it
responds "DO LGIAUTH" with a string for the DTE to authenticate:
<-- <193><065>{auth-str}<255><254>
Otherwise, if the DCE does not want to receive login
authentication, it responds "DONT LGIAUTH":
<-- <194><065><255><254>
If the DCE has agreed to receive login authentication, the DTE
then sends "HERE-IS LGIAUTH" with its computed authentication
code for the supplied authentication string:
<197><065>{auth-code}<255><254> -->
If the DTE would like to receive login authentication, it sends
"DO LGIAUTH" with a string for the DCE to authenticate:
<193><065>{auth-str}<255><254> -->
If the DCE can supply login authentication, it responds "WILL
LGIAUTH" and then sends "HERE-IS LGIAUTH" with its computed
authentication code for the supplied authentication string:
<-- <195><065><255><254>
<-- <197><065><{auth-code}<255><254>
Otherwise, if the DCE cannot supply login information, it
responds "WONT LGIAUTH":
<-- <196><065><255><254>
Parameters
{auth-str}
Authentication string may contain 1 to 1024 unsigned bytes
depending upon the authentication algorithm. Data byte 255 must
be doubled.
{auth-code}
C. Kilkenny Expires January 9, 2001 [Page 27]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
Authentication code may contain 1 to 64 unsigned bytes depending
upon the authentication algorithm. Data byte 255 must be doubled.
Examples
DTE supplies login authentication to DCE:
<195><065><255><254> -->
<-- <193><065>TIMESTAMP NOW IS 2010082810560203<255><254>
<197><065>E06720587801C331<255><254> -->
DTE supplies login authentication to DCE, but DCE does not want
it:
<195><065><255><254> -->
<-- <194><065><255><254>
3.8 MSGAUTH [Message Authentication]
Identification
Name: MSGAUTH, Code = 66
Dependencies: MODE
Overview
The Message Authentication (MSGAUTH) protocol option allows
applications to authenticate messages. The authentication keys
and identification of the authentication algorithm are agreed and
distributed by some other means.
Once agreed, the applications calculate a message authentication
code (MAC) for every message, based upon the contents of the
message, the keys and the algorithm. A separate key or the same
key can be used for sending and receiving. The sending
application calculates the MAC and adds it to the MESSAGE packet.
The receiving application calculates the MAC again and compares
it with the MAC in the received MESSAGE packet. If they match,
the message passes authentication. Otherwise, the message fails
authentication and is not processed. The MSGAUTH protocol option
allows co-operating applications to check the authenticity and
integrity of messages. It does not guarantee confidentiality.
F66 is included in the MESSAGE packet in order to add the
authentication code. F66 contains 1 to 64 unsigned bytes
depending upon the authentication algorithm. For example,
<200><255><064>Hello World!
<255><066><134><161><003><255><255><201><193><255><254>
This message contains a 48-bit authentication code, hex value
"86A103FFC9C1".
C. Kilkenny Expires January 9, 2001 [Page 28]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
If authentication fails, the message should not be processed. The
receiving application should abort the connection by sending
DISCONNECT with code AUTFAIL.
Motivation
By default, a RACE connection is not secure. This option allows
two co-operating applications to check the authenticity and
integrity of messages.
Negotiation
If the DTE can supply message authentication (for the input
stream), it sends "WILL MSGAUTH":
<195><066><255><254> -->
If the DCE would like to authenticate messages (for the input
stream), it responds "DO MSGAUTH":
<-- <193><066><255><254>
Otherwise, if the DCE does not want to authenticate messages (for
the input stream), it responds "DONT MSGAUTH":
<-- <194><066><255><254>
If the DTE would like to authenticate messages (for the output
stream), it sends "DO MSGAUTH":
<193><066><255><254> -->
If the DCE can supply message authentication (for the output
stream), it responds "WILL MSGAUTH":
<-- <195><066><255><254>
Otherwise, if the DTE cannot supply message authentication (for
the output stream), it responds "WONT MSGAUTH":
<-- <196><066><255><254>
Parameters
None.
Examples
DTE and DCE agree to authenticate messages for the input stream:
<195><066><255><254> -->
<-- <193><066><255><254>
DTE and DCE agree to authenticate messages in both directions:
C. Kilkenny Expires January 9, 2001 [Page 29]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
<195><066><255><254> -->
<193><066><255><254> -->
<-- <193><066><255><254>
<-- <195><066><255><254>
DTE would like to authenticate messages in both directions, but
DCE does not understand this option:
<195><066><255><254> -->
<193><066><255><254> -->
<-- <194><066><255><254>
<-- <196><066><255><254>
3.9 LGRP [Logical Grouping]
Identification
Name = LGRP, Code = 72
Dependencies: MODE
Overview
The Logical Grouping (LGRP) protocol option allows messages to be
grouped and processed as a single unit of work. Once enabled, the
sender can group consecutive messages together or continue to
send individual messages like in the basic protocol.
F67 is included in the MESSAGE packet in order to add the logical
grouping information. F67 contains the logical group position, as
an unsigned byte. It is included in the first and last messages
in order to delimit the beginning and end of a group. The first
message is assigned position 1 and the last message is assigned
position 2. F67 is not used in intermediate messages. Sequence
numbering within a logical group is not used, because a reliable
connection is assumed. For example,
<200><255><064>MSG-1<255><067><001><255><254>
<200><255><064>MSG-2<255><254>
<200><255><064>MSG-3<255><254>
<200><255><064>MSG-4<255><067><002><255><254>
<200><255><064>MSG-5<255><254>
<200><255><064>MSG-6<255><067><001><255><254>
<200><255><064>MSG-7<255><254>
<200><255><064>MSG-8<255><067><002><255><254>
This input contains three logical groups. The first group
contains four messages (MSG-1, MSG-2, MSG-3 and MSG-4). The
second group contains only one message (MSG-5). The third
group contains three messages (MSG-6, MSG-7 and MSG-8).
If a logical group contains only one message, F67 is not used and
a single message is put as per the basic protocol. Message
C. Kilkenny Expires January 9, 2001 [Page 30]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
replies, if enabled, are expected for every message sent.
Windowing is allowed. A logical group becomes acknowledged after
the last message in the group has been acknowledged. The group is
then processed as a single unit of work. If one or more messages
in a logical group are rejected, the whole group is rejected and
subsequently not processed. The LGRP protocol option does not
alter the use of the SEQNO protocol option.
Motivation
It is sometimes necessary or practical to group messages together
in order to process them as a logical whole. For example, if
messages are read from a batch file, it is desirable to deliver
them together. If a group of messages form a transaction, they
need to be processed together so that, if one part fails, the
whole transaction can be rolled back.
Negotiation
Usage of logical grouping is negotiated separately for input and
output message transfer.
If the DTE would like to use logical grouping (for the input
stream), it sends "DO LGRP":
<193><072><255><254> -->
If the DCE supports logical grouping (for the input stream), it
replies "WILL LGRP":
<-- <195><072><255><254>
Otherwise, if the DCE does not support logical grouping (for the
input stream), it replies "WONT LGRP":
<-- <196><072><255><254>
If the DTE supports logical grouping (for the output stream), it
sends "WILL LGRP":
<195><072><255><254> -->
If the DCE would like to use logical grouping (for the output
stream), it replies "DO LGRP":
<-- <193><072><255><254>
Otheriwse, if the DCE does not want to use logical grouping (for
the output stream), it replies "DONT LGRP":
<-- <194><072><255><254>
Parameters
C. Kilkenny Expires January 9, 2001 [Page 31]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
None.
Examples
Mode is BIDIRECTIONAL; Both DTE and DCE support LGRP.
<193><072><255><254> -->
<195><072><255><254> -->
<-- <195><072><255><254>
<-- <193><072><255><254>
Mode is INPUT; DTE supports LGRP, but DCE does not.
<193><072><255><254> -->
<-- <196><072><255><254>
3.10 MSGLEN [Message Length]
Identification
Name: MSGLEN, Code = 78
Dependencies: MODE
Overview
The Message Length (MSGLEN) protocol option allows the message
length to be included in a MESSAGE packet. Depending upon
negotiation, the message length can be included either before or
after F64 (the message contents).
F63 is included in the MESSAGE packet in order to add the message
length. F63 is an unsigned long integer in network byte order.
So, the maximum message length is 4,294,967,295 bytes (4GB) when
this option is in effect. For example,
The message length prefixed:
<200><255><063><000><000><000><016>
<255><064>I HAVE 16 BYTES.<255><254>
The message length suffixed:
<200><255><064>I HAVE 16 BYTES.
<255><063><000><000><000><016><255><254>
If the message receiver detects that the actual message length
does not match the message length specified in F63, it should
disconnect with code INVMSGLEN.
Motivation
If the message length is sent with the message, the receiving
application can check the actual message length. If the message
C. Kilkenny Expires January 9, 2001 [Page 32]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
length is included before the message content, the receiving
application can allocate space for the message in advance. For
large message transfers, this can increase performance, because
the receiving application can pre-allocate contiguous space.
However, it may be difficult for the sending application to know
the message length in advance or it may hinder performance for
the sending application to determine the message length in
advance. In addition, the size of F63 can degrade performance
when many small messages are being transferred.
Negotiation
If the DTE can provide the message length (for the input stream),
it sends "WILL MSGLEN" and whether it can prefix or suffix it (1,
2):
<195><078>{prefix-suffix}<255><254> -->
If the DCE would like to receive the message length (for the
input stream), it replies "DO MSGLEN" and whether to prefix or
suffix it (1, 2). The DCE can only ask for the message length to
be prefixed if the DTE has offered to prefix it. The DCE can ask
for the message length to be suffixed in either case.
<-- <193><078>{prefix-suffix}<255><254>
Otherwise, if the DCE does not want to receive the message length
(for the input stream), it replies "DONT MSGLEN":
<-- <194><078><255><254>
If the DTE would like to receive the message length (for the
output stream), it sends "DO MSGLEN" and whether to prefix or
suffix it (1, 2):
<193><078>{prefix-suffix}<255><254> -->
If the DCE can provide the message length (for the output
stream), it replies "WILL MSGLEN" and whether it can prefix or
suffix it (1, 2). The DCE should only offer to prefix the message
length if the DTE has requested it to be prefixed. If the DTE has
requested the message length to be prefixed and the DCE can only
suffix it, the DCE should agree to suffix it. The DTE can then
determine how it wants to proceed.
<-- <195><078><{prefix-suffix}<255><254>
Otherwise, if the DCE cannot provide the message length (for the
output stream), it replies "WONT MSGLEN":
<-- <196><078><255><254>
Parameters
C. Kilkenny Expires January 9, 2001 [Page 33]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
{prefix-suffix}
The prefix-suffix parameter is an unsigned byte containing 1 to
prefix or 2 to suffix.
Examples
Mode is BIDIRECTIONAL; DTE can prefix MSGLEN and would like to
receive MSGLEN prefixed; DCE can prefix MSGLEN, but is not
interested in receiving it; they agree to prefix MSGLEN from DCE
to DTE.
<195><078><001><255><254> -->
<193><078><001><255><254> -->
<-- <194><078><255><254>
<-- <195><078><001><255><254>
Mode is INPUT; DTE can suffix MSGLEN; DCE would like to receive
MSGLEN prefixed; they agree not to use MSGLEN (because the DTE
cannot prefix it).
<195><078><002><255><254> -->
<-- <194><078><255><254>
3.11 BATCH
Identification
Name: BATCH, Code = 41
Dependencies: MODE
Overview
The BATCH protocol option supports the transfer of data files
between applications. Typically, messages are written to the
batch file by one program and then the batch file is transferred
to another program.
BATCH disables standard message transfer and enables batch file
transfer. The MESSAGE packet is used to convey the batch file and
the MESSAGE-REPLY packet for acknowledgement. The contents are
transferred using F64 and the header is prefixed using F91 and
F92. F91 is mandatory and details the filename. F92 is optional
and details the creation date and time of the file in Greenish
Meantime.
If possible, the MSGLEN protocol option should be negotiated in
order to include F63, the file size. If F63 is included, the
receiving application can check the size of the received file. If
F63 is included before the file contents, the receiving
application can pre-allocate contiguous space and speed up the
file transfer. The maximum file size is 4,294,967,295 bytes
(4GB).
C. Kilkenny Expires January 9, 2001 [Page 34]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
The data file can contain any binary data. Data byte 255 must be
doubled.
For example, a file transfer:
<200><255><091>PX2061.DAT<255><092>2002101510241600
<255><064>HERE ARE THE FILE CONTENTS.<255><254> -->
<-- <201><255><254>
File PX2061.DAT, created at 10:24am on the 15th October 2002,
is transferred.
The BATCH protocol option should be negotiated before the MODE
protocol option.
Motivation
Many existing or simple systems use batch files for message
processing and transfer.
Negotiation
BATCH usage is the same for input and output data transfer. Once
enabled, batch file transfer replaces standard message transfer.
If the DTE would like to use batch, it sends "DO BATCH":
<193><041><255><254> -->
If the DCE supports batch, it replies "WILL BATCH":
<-- <195><041><255><254>
Otherwise, if the DCE does not support batch, it replies "WONT
BATCH":
<-- <196><041><255><254>
If the DTE can offer batch, it sends "WILL BATCH":
<195><041><255><254> -->
If the DCE would like to use batch, it replies "DO BATCH":
<-- <193><041><255><254>
Otherwise, if the DCE does not want to use batch, it replies
"DONT BATCH":
<-- <194><041><255><254>
Parameters
C. Kilkenny Expires January 9, 2001 [Page 35]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
None.
Examples
DTE would like to use BATCH; DCE supports BATCH; they agree to
use BATCH.
<193><041><255><254> -->
<-- <195><041><255><254>
DTE would like to use BATCH; DCE does not support BATCH; they do
not use BATCH.
<193><041><255><254> -->
<-- <196><041><255><254>
3.12 NOM [Number of Messages]
Identification
Name: NOM, Code = 42
Dependencies: MODE
Overview
The Number of Messages (NOM) option allows either party to
determine the number of messages that are waiting to be
downloaded at the time of negotiation.
If the DTE wants to know or can offer the number of pending
messages, it negotiates with the DCE. If agreed, the DTE sends
its number of pending messages and/or the DCE sends its number of
pending messages.
It should be noted that the number of messages returned using
this protocol option may be less than or more than the actual
number of messages transferred.
Motivation
Sometimes, it is desirable to display or know the number of
messages that are waiting to be downloaded before they are
actually downloaded. This option allows the number of messages to
be known before data transfer is agreed and entered into. If no
messages are pending, this option allows the other party to
quickly disconnect, as it would otherwise have to wait for a
timer to expire.
For example, consider a message output program with user
intervention. The message output program connects to an output
message queue and retrieves the number of pending messages. It
displays the number of messages to the user and asks whether the
user wishes to download the messages. If the user agrees, the
C. Kilkenny Expires January 9, 2001 [Page 36]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
program enters into message transfer. Otherwise, the program
disconnects. In this example, the program will need to watch that
the connection does not timeout if the user does not respond
immediately.
Negotiation
If the DTE wants to know the number of pending messages (for the
output stream), it sends "DO NOM":
<193><042><255><254> -->
If the DCE can offer the number of pending messages (for the
output stream), it replies "WILL NOM" and then sends "HERE-IS
NOM":
<-- <195><042><255><254>
<-- <197><042>{number-of-messages}<255><254>
Otherwise, if the DCE cannot offer the number of pending messages
(for the output stream), it replies "WONT NOM":
<-- <196><042><255><254>
If the DTE can offer the number of pending messages (for the
input stream), it sends "WILL NOM":
<195><042><255><254> -->
If the DCE would like to know the number of pending messages (for
the input stream), it replies "DO NOM":
<-- <193><042><255><254>
The DTE then sends "HERE-IS NOM" with the number of messages:
<197><042><{number-of-messages}<255><254>
Otherwise, if the DCE does not want to know the number of pending
messages (for the input stream), it replies "DONT NOM":
<-- <194><042><255><254>
Parameters
{number-of-messages}
The number of pending messages is an unsigned long integer in
network byte order. If a party supports this option but cannot
determine the number of messages, it returns a value of minus one
(4,294,967,295) as the number of pending messages. If a party has
no messages to send, the queue is empty, or mode does not permit
sending messages, it returns a value of zero as the number of
pending messages. If a party has 4,294,967,295 or more messages
to send, it returns a value of 4,294,967,295 as the number of
C. Kilkenny Expires January 9, 2001 [Page 37]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
pending messages. I.e. it cannot determine the number of pending
messages. Data byte 255 must be doubled.
Examples
Mode is OUTPUT; DCE agrees to give DTE the number of pending
messages.
<193><042><255><254> -->
<-- <195><042><255><254>
.
.
.
<-- <197><042><000><000><000><000><255><254>
In this case, the DCE has no messages to transfer to DTE.
3.13 BIGFOOT [Big Code Numbering]
Identification
Name: BIGFOOT, Code = 82
Dependencies: n/a
Overview
The Big Code Numbering (BIGFOOT) protocol option extends the
basic protocol in order to support a greater number of packet,
field and option codes.
When this option is in effect, identification of packets, fields
and options can span one or two bytes. A value of 253 in the
first byte indicates that the next two bytes contain the code
number in network byte order.
For example, consider the following WILL packet:
<195><253><003><002><255><254>
This WILL packet identifies option code 770 and does not
contain any parameter data.
For example, consider the following MESSAGE packet:
<200><255><064>HELLO<255><253><201><255>C256<255><254>
This MESSAGE packet contains two field ids: 64 and 51711.
Field 64 contains "HELLO". Field 51711 contains "C256". Note
how byte <255> is not doubled within the FID.
For example, consider the following packet:
<253><001><021><255><254>
C. Kilkenny Expires January 9, 2001 [Page 38]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
This packet has packet id 277, but does not contain any fields
or data.
Under this scheme, code values 253, 254 and 255 can be
represented using the 2-byte code value. For example,
<253><000><253>.
This option gives 65,536 possible code values for fields, options
and packets. Within the 2-byte code value, byte value 255 should
not be doubled.
Motivation
It is quite likely that the number of codes offered by a single
byte will be exhausted some time in the future. This option
recommends a preferred method for higher code numbering.
Negotiation
If the DTE can offer big code numbering, it sends "WILL BIGFOOT":
<195><082><255><254> -->
If the DCE would like to use big code numbering, it replies "DO
BIGFOOT":
<-- <193><082><255><254>
Otherwise, if the DCE does not want to use big code numbering, it
replies "DONT BIGFOOT":
<-- <194><082><255><254>
If the DTE would like to use big code numbering, it sends "DO
BIGFOOT":
<193><082><255><254> -->
If the DCE can offer big code numbering, it replies "WILL
BIGFOOT":
<-- <195><082><255><254>
Otherwise, if the DCE cannot offer big code numbering, it replies
"WONT BIGFOOT":
<-- <196><082><255><254>
The DTE need only negotiate this option if it plans to use higher
numbered codes.
Parameters
C. Kilkenny Expires January 9, 2001 [Page 39]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
None.
Examples
DTE and DCE agree to use big code numbering.
<193><082><255><254> -->
<-- <195><082><255><254>
C. Kilkenny Expires January 9, 2001 [Page 40]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
4. Packet Syntax
The following packet codes are defined:
NAME CODE MEANING
CONNECT 192 Connect request
DO 193 Request / agree protocol option
DONT 194 Deny protocol option
WILL 195 Offer / agree protocol option
WONT 196 Refuse protocol option
HERE-IS 197 Sub negotiation
READY 198 Ready
DISCONNECT 199 Quit / shutdown request
MESSAGE 200 Data message
MESSAGE-REPLY 201 Logical reply
This chapter describes each packet.
All other codes are reserved for future use.
The following codes have specific meaning when prefixed by the IAC
byte within a RACE packet:
NAME CODE MEANING
END-OF-PACKET 254 End of packet (EOP).
IAC 255 Data byte 255.
FIELD-IDENTITY 000...253 Field id and separation (FID).
The next chapter describes each field.
Not all of the field identity codes are used. Unused field
identity codes are reserved for future use, which includes usage
other than for field identification.
The packet descriptions now follow.
4.1 CONNECT
CONNECT is sent by DTE in order to specify and connect to a target
DCE service and application.
SYNTAX MEANING
------ -------
<192> Start of packet (192)
<255><031>{service-id} F31 - Target service
[<255><032>{appl-id} F32 - Target application
[<255><033>{appl-id}]] F33 - User identifier
C. Kilkenny Expires January 9, 2001 [Page 41]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
<255><254> EOP - End of packet
Description
See the basic protocol.
4.2 DO
DO is sent by DTE in order to request a protocol option according to
the option specification.
DO is sent by DCE, after receipt of WILL, in order to accept or
negotiate a protocol option further according to the option
specification.
SYNTAX MEANING
------ -------
<193> Start of packet (193)
{opt-code} Option code
[{opt-params}] Option parameters
<255><254> EOP - End of packet
Description
The DTE can send DO during option negotiation subject to the
option specification. The DCE can only send DO after receipt of
WILL from DTE.
This packet does not use field notation. If field identifiers are
needed for option parameters, the IAC byte should be doubled. For
example, specify field 22 as <255><255><022>. Then, the default
parser will interpret the field identification as data and pass
<255><022> on as data for further interpretation. A secondary
parser can then interpret <255><022> as a valid field identifier.
{opt-code}, by position (2nd byte)
Option code as an unsigned byte, value 0-255. Data byte 255 must
be doubled.
{opt-params}, by position (after {opt-code})
Option specific parameters in order to sub-negotiate the option.
Depending upon the option specification, this argument is
optional and contains a varying number of data bytes. Data byte
<255> must be doubled.
4.3 DONT
C. Kilkenny Expires January 9, 2001 [Page 42]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
DONT is sent by DCE after receipt of WILL, in order to reject the
option specified by WILL.
SYNTAX MEANING
------ -------
<194> Start of packet (194)
{opt-code} Option code
<255><254> EOP - End of packet
Description
This packet does not use field notation.
{opt-code}, by position (2nd byte)
Option code as an unsigned byte, value 0-255. Data byte 255 must
be doubled.
4.4 WILL
WILL is sent by DTE in order to offer a protocol option according to
the option specification.
WILL is sent by DCE, after receipt of DO, in order to accept or
negotiate a protocol option further according to the option
specification.
SYNTAX MEANING
------ -------
<195> Start of packet (195)
{opt-code} Option code
[{opt-params}] Option parameters
<255><254> EOP - End of packet
Description
The DTE can send WILL during option negotiation subject to the
option specification. The DCE can only send WILL after receipt of
DO from DTE.
This packet does not use field notation. If field identifiers are
needed for option parameters, the IAC byte should be doubled. For
example, specify field 22 as <255><255><022>. Then, the default
parser will interpret the field identification as data and pass
<255><022> on as data for further interpretation. A secondary
parser can then interpret <255><022> as a valid field identifier.
{opt-code}, by position (2nd byte)
C. Kilkenny Expires January 9, 2001 [Page 43]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
Option code as an unsigned byte, value 0-255. Data byte 255 must
be doubled.
{opt-params}, by position (after {opt-code})
Option specific parameters in order to sub-negotiate the option.
Depending upon the option specification, this argument is
optional and contains a varying number of data bytes. Data byte
<255> must be doubled.
4.5 WONT
WONT is sent by DCE after receipt of DO, in order to reject the
option specified by DO.
SYNTAX MEANING
------ -------
<196> Start of packet (196)
{opt-code} Option code
<255><254> EOP - End of packet
Description
This packet does not use field notation.
{opt-code}, by position (2nd byte)
Option code as an unsigned byte, value 0-255. Data byte 255 must
be doubled.
4.6 HERE-IS
HERE-IS is sent by DTE or DCE in order to negotiate an option
further according to an option specification. The option must have
been agreed before HERE-IS can be used.
SYNTAX MEANING
------ -------
<197> Start of packet (197)
{opt-code} Option code
[{opt-params}] Option parameters
<255><254> EOP - End of packet
Description
This packet does not use field notation. If field identifiers are
needed for option parameters, the IAC byte should be doubled. For
C. Kilkenny Expires January 9, 2001 [Page 44]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
example, specify field 22 as <255><255><022>. Then, the default
parser will interpret the field identification as data and pass
<255><022> on as data for further interpretation. A secondary
parser can then interpret <255><022> as a valid field identifier.
{opt-code}, by position (2nd byte)
Option code as an unsigned byte, value 0-255. Data byte 255 must
be doubled.
{opt-params}, by position (after {opt-code})
Option specific parameters in order to sub-negotiate the option.
Depending upon the option specification, this argument is
optional and contains a varying number of data bytes. Data byte
<255> must be doubled.
4.7 READY
READY is sent by DCE after receipt of CONNECT in order to accept the
connection.
READY is sent by DTE after negotiation in order to indicate that it
has finished and is agreeable to option negotiation.
READY is sent by DCE after receipt of READY in order to indicate
that it is agreeable to option negotiation. DTE and DCE immediately
enter into data transfer after the DCE has sent this packet
following negotiation.
SYNTAX MEANING
------ -------
<198> Start of packet (198)
<255><254> EOP - End of packet
Description
See the basic protocol.
4.8 DISCONNECT
DISCONNECT is sent by DTE or DCE to request shutdown of the link.
DISCONNECT is sent by DTE at the end of option negotiation in order
to reject negotiation and close the link.
DISCONNECT is sent by DCE after receipt CONNECT or READY, in order
to reject a connect request or negotiation, and close the link.
DISCONNECT is also sent by DTE or DCE after a protocol or unexpected
error.
C. Kilkenny Expires January 9, 2001 [Page 45]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
SYNTAX MEANING
------ -------
<199> Start of packet (199)
[<255><021>{code} F21 - Disconnect code
[<255><023>{text}]] F23 - Additional information
<255><254> EOP - End of packet
Description
When used to initiate or complete shutdown, DISCONNECT must
convey SUCCESS (0). Otherwise, DISCONNECT is interpreted as an
exception and blocks further communication.
F21, the disconnect code argument, can be omitted when its value
is SUCCESS (0). When omitted, SUCCESS (0) is assumed. If F23 is
present, F21 must also be present.
4.9 MESSAGE
MESSAGE is sent in order to transfer an application data message.
SYNTAX MEANING
------ -------
<200> Start of packet (200)
[<255><010>{seqno}] F10 - Sequence number
[<255><091>{fname} F91 - Filename
[<255><092>{fstamp}]] F92 - File creation date and time
[<255><063>{msglen}] F63 - Message length (prefixed)
<255><064>{msg} F64 - Message
[<255><063>{msglen}] F63 - Message length (suffixed)
[<255><065>{pde}] F65 - PDE flag
[<255><066>{mac}] F66 - MAC
[<255><067>{lgrp}] F67 - LGRP position
<255><254> EOP - End of packet
Description
C. Kilkenny Expires January 9, 2001 [Page 46]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
By default, messages are sent from DTE to DCE. The MODE protocol
option modifies this behaviour by allowing output (from DCE to
DTE) and bi-directional message transfer.
The SEQNO protocol option determines the usage of F10. When SEQNO
is enabled, F10 is mandatory. Otherwise, F10 should not be
present.
The PDE protocol option determines the usage of F65. When PDE is
enabled for the direction of message transfer, F65 may be present
in order to indicate a possible duplicate emission.
The MAC protocol option determines the usage of F66. When MAC is
enabled for the direction of message transfer, F66 is mandatory.
Otherwise, F66 should not be present.
The LGRP protocol option determines the usage of F67. When LGRP
is enabled for the direction of message transfer, F67 may be
present in order to indicate the beginning or end of a logical
group.
The MSGLEN protocol option determines the usage of F63. When
MSGLEN is enabled for the direction of message transfer, F63 is
mandatory and details the message length. Depending upon
negotiation of MSGLEN, F63 is either expected before or after
F64, the message contents.
The BATCH protocol option determines the usage of F91 and F92.
When BATCH is enabled, F91 is mandatory and F92 may be optionally
present. Otherwise, F91 and F92 should not be present. When BATCH
is enabled, F64 is the contents of the file rather than a
specific application message.
4.10 MESSAGE-REPLY
MESSAGE-REPLY is sent after receipt of MESSAGE in order to indicate
successful or unsuccessful interpretation of the data message.
SYNTAX MEANING
------ -------
<201> Start of packet (201)
[<255><010>{seqno}] F10 - Sequence number
[<255><021>{code} F21 - Reply code
[<255><023>{text}]] F23 - Additional information
[<255><024>{umr}] F24 - RREF
<255><254> EOP - End of packet
C. Kilkenny Expires January 9, 2001 [Page 47]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
Description
Code SUCCESS indicates a positive message reply and that the
message was accepted. Otherwise, the reply is negative and the
message was not accepted.
By default, message replies are returned from DCE to DTE. The
NOREPLY and MODE protocol options modify this behaviour. NOREPLY
turns off message replies. MODE allows message replies to be
returned from DTE to DCE or in both directions depending upon the
direction of message transfer.
The RREF protocol option determines the usage of F24. When RREF
is enabled for the direction of message transfer, F24 is
mandatory and contains a unique message reference. Otherwise, F24
should not be present.
The SEQNO protocol option determines the usage of F10. When SEQNO
is enabled, F10 is mandatory. Otherwise, F10 should not be
present.
F21, the reply code argument, can be omitted when its value is
SUCCCESS (0), in order to increase performance. When omitted,
SUCCESS is assumed. If F23 is present, F21 must also be present.
C. Kilkenny Expires January 9, 2001 [Page 48]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
5. Field Syntax
F10, SEQUENCE NUMBER
Usage: SEQNO (MESSAGE, MESSAGE-REPLY)
Format: unsigned short int (in network byte order)
Detail: Sequence numbers are applied to both messages and message
replies. Separate counters are used for input and output message
transfer. Sequence numbers start at one at the beginning of a new
connection, increment by one, and wrap back to one upon reaching
65,536 (i.e. 65,536, 131,071, ... become 1). Zero is not a valid
sequence number.
F21, REPLY OR DISCONNECT CODE
Usage: BASIC (DISCONNECT, MESSAGE-REPLY)
Format: unsigned short int (in network byte order)
Detail: See later in this documentation for details of reply and
disconnect codes and their meanings. If F21 is omitted in
DISCONNECT or MESSAGE-REPLY, SUCCESS is assumed.
F23, ADDITIONAL INFORMATION
Usage: BASIC (DISCONNECT, MESSAGE-REPLY)
Format: char [256]
Detail: Additional information is used to supplement the code in
F21. This field contains 1 to 256 bytes and is application
specific. Typically, ASCII, byte value 32 to 126 inclusive, is
used.
F24, UNIQUE MESSAGE REFERENCE (UMR)
Usage: RREF (MESSAGE-REPLY)
Format: char [32]
Detail: The unique message reference (UMR) is comprised of 1 to
64 ASCII characters, byte value 32 through 126 inclusive. As a
matter of good practise, it is recommended to keep the reference
to alphanumeric characters without leading, trailing or embedded
spaces.
F31, TARGET SERVICE
Usage: BASIC (CONNECT)
Format: char [64]
C. Kilkenny Expires January 9, 2001 [Page 49]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
Detail: The DCE service identifier (protocol type). The
identifier comprises 1 to 64 ASCII characters, byte value 32 to
126 inclusive.
F32, TARGET APPLICATION
Usage: BASIC (CONNECT)
Format: char [64]
Detail: The DCE application name (daemon, connection point, I/O
queue name). The identifier comprises 1 to 64 ASCII characters,
byte value 32 to 126 inclusive.
F33, USER IDENTIFIER
Usage: BASIC (CONNECT)
Format: char [64]
Detail: The DTE application name (user identifier, connection
point, I/O queue name). The identifier comprises 1 to 64 ASCII
characters, byte value 32 to 126 inclusive, like F32.
F63, MESSAGE LENGTH
Usage: MSGLEN (MESSAGE)
Format: unsigned long int (in network byte order)
Detail: The length of F64, the content of the message.
F64, APPLICATION DATA MESSAGE
Usage: BASIC (MESSAGE)
Format: unsigned char []
Detail: A varying number of unsigned bytes, which are application
specific. If the MSGLEN protocol option is in effect, the maximum
message length is 4,294,967,295 bytes (4GB).
F65, POSSIBLE DUPLICATE EMISSION (PDE) FLAG
Usage: PDE (MESSAGE)
Format: unsigned char
Detail: F65 indicates a possible duplicate emission (PDE). It
should contain a single byte, binary value one.
F66, MESSAGE AUTHENTICATION CODE (MAC)
Usage: MAC (MESSAGE)
C. Kilkenny Expires January 9, 2001 [Page 50]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
Format: unsigned char [64]
Detail: F66 contains 1 to 64 unsigned bytes depending upon the
authentication algorithm.
F67, LOGICAL GROUPING (LGRP) POSITION
Usage: LGRP (MESSAGE)
Format: unsigned char
Detail: The first message in a logical group is assigned position
one and the last message is assigned position two. F67 is not
used for intermediate messages. If a logical group contains only
one message, F67 is not used and a single message is put as per
the basic protocol.
F91, FILENAME
Usage: BATCH (MESSAGE)
Format: char [64]
Detail: The filename of the batch file. F91 contains 1 to 64
ASCII characters, limited to the following: lowercase and
uppercase letters; digits; the dollar character; the underscore
character; and the period (full stop) character. The period
character should only occur once in the filename and is used to
separate the name from the type suffix.
F92, FILE CREATION DATE AND TIME STAMP
Usage: BATCH (MESSAGE)
Format: char [16]
Detail: The creation date and time stamp of the batch file in
Greenish Meantime. The stamp is 16 ASCII digits, format
YYYYMMDDHHMMSSNN, where YYYYMMDD represents the year, month and
day, and HHMMSSNN represents the hour, minute, second and
hundredth second. If part of the stamp cannot be determined, for
example the hundredth second, it should be filled with ASCII
zero.
N.B. DATA BYTE <255> MUST BE DOUBLED.
C. Kilkenny Expires January 9, 2001 [Page 51]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
6. Reply Codes
The following codes have been defined for MESSAGE-REPLY. Your
application should be ready to support other codes, which have not
yet been defined, in order to support future versions of the
protocol.
0 SUCCESS, Normal successful completion
Description: A valid message was received, interpreted and
processed. This may include safe-storage for subsequent
processing. SUCCESS is assumed when MESSAGE-REPLY does not
contain a reply code.
Action: The sending application can now update the message as
sent. Responsibility for the message passes to the receiving
application.
1001 ERROR, Error
Description: This error code should not be sent in MESSAGE-
REPLY. Rather, it is used to describe an unknown error code
(not currently defined in this section) to the user or calling
software.
Action: Consider updating your software to support the latest
protocol version.
2001 INVMSG, Invalid message
Description: An invalid message was received and, therefore,
could not be processed.
Action: Check the message for errors. If OK, review the logic
of the receiving application. Check F23 for additional
information.
C. Kilkenny Expires January 9, 2001 [Page 52]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
7. Disconnect Codes
The following codes have been defined for DISCONNECT. Your
application should be ready to support other codes, which have not
yet been defined, in order to support future versions of the
protocol.
0 SUCCESS, Normal successful completion
Description: Either DTE or DCE has completed its processing
and is requesting or confirming shutdown of the link. SUCCESS
is assumed when DISCONNECT does not contain a disconnect code.
Action: If initiating shutdown, wait for a corresponding
DISCONNECT packet in order to close the link. Upon receipt of
a shutdown request, complete any processing and return a
corresponding DISCONNECT packet. The link can then be closed.
1001 ERROR, Error
Description: This error code should not be sent in DISCONNECT.
Rather, it is used to describe an unknown error code (not
currently defined in this section) to the user or calling
software.
Action: Consider updating your software to support the latest
protocol version.
3014 SRVNOTAVL, Service not available
Description: The DCE received a CONNECT request, but the
requested service was not available or unsupported.
Action: Check the name of the service and whether it is
supported.
3025 APPNOTAVL, Application not available
Description: The DCE received a CONNECT request, but the
requested application was not available or did not exist.
Action: Check the name of the target application.
3036 APPBUSY, Application busy, retry later
Description: The DCE received a CONNECT request, but the
requested application is currently busy.
Action: If the DCE application is shared, close the link and
try again (possibly after a short delay). If the DCE
application is not shared, check that another DTE instance is
not running.
3047 APPNOTRDY, Application not ready, retry later
C. Kilkenny Expires January 9, 2001 [Page 53]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
Description: The DCE received a CONNECT request, but the
requested application is not currently listening for new
connections.
Action: Close the connection and try again (using a short
delay and a maximum number of retries).
3058 LGIFAIL, Login failure
Description: Either DTE or DCE could not continue, because the
login information was incorrect or insufficient.
Action: Check the login information, authentication keys,
authentication algorithm, and supported protocol options.
3069 AUTFAIL, Authentication failure
Description: Either DTE or DCE could not continue, because
message authentication failed.
Action: Check the authentication keys, algorithm, and
supported protocol options.
3080 INSNEGOPT, Insufficient negotiated options
Description: Either DTE or DCE cannot continue with the
negotiated protocol options. I.e. One party needed one or more
protocol features, which the other party did not support.
Action: The applications are incompatible. Change one of the
applications.
3091 RESFAIL, Resource failure
Description: A message was received, but a resource failed,
which prevented the message from being processed. For example,
the receiving application might have run out of disk space or
memory. The message may or may not be valid. The message may
or may not have been processed.
Action: An operator will most probably need to investigate why
the receiving application failed. Reopen the link once the
receiving application has been fixed.
3102 PRTCOLERR, Protocol error
Description: The application received a known packet type, but
the packet was unexpected. For example, if the DTE was
expecting READY or DISCONNECT, and received a MESSAGE, this
would constitute a protocol error.
Action: Check your application for programming errors.
C. Kilkenny Expires January 9, 2001 [Page 54]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
3113 INVPKTTYP, Invalid packet type
Description: The application received an invalid packet type.
I.e. the first byte of the packet was not a valid packet
identifier.
Action: Check your application for programming errors. Check
that the underlying transport is reliable.
3124 PKTOVFBUF, Packet overflows buffer
Description: The application received a packet, which exceeded
its internal buffer size.
Action: Specify a smaller packet or increase the internal
buffer size of the application. If a message is bigger than
the maximum message length (defined at application level),
INVMSG should be returned by MESSAGE-REPLY rather than
PKTOVFBUF by DISCONNECT. Ideally, applications should not
restrict the packet size.
3135 TOOMANFLD, Too many fields in packet
Description: The other application received a packet, which
had too many packet fields for its internal buffers.
Action: Typically, this is an indication of a programming
error, which has resulted in too many fields. Check your
application. If the packet is correct, increase the internal
buffers of the other application.
3146 INVPKTFID, Invalid packet field identifier
Description: The other application received a packet, which
contained an invalid field identifier.
Action: Check the applications for programming errors. Check
that the underlying transport is reliable.
3157 INVPKTSYN, Invalid packet syntax
Description: The other application received a packet, which
had invalid syntax. For example, a field was not properly
formatted, was out of order or was missing.
Action: Check the applications for programming errors.
3168 TIMEOUT, Timeout
Description: The other application was expecting a packet, but
did not receive one within its timeout period.
C. Kilkenny Expires January 9, 2001 [Page 55]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
Action: Check your application for programming errors. Check
that the timeout period is sufficient for the applications,
the underlying transport and the network.
3179 INVSEQNO, Invalid sequence number
Description: The SEQNO protocol option was agreed and a
message or message reply was encountered, which had an invalid
sequence number.
Action: Check the programs for sequencing errors.
3190 INVMSGLEN, Invalid message length
Description: The MSGLEN protocol option was agreed and the
message length in F63 did not agree with the actual message
length in F64.
Action: Check for programming errors. Check that the
underlying transport is reliable. If a message is bigger than
the maximum message length (defined at application level),
INVSG should be returned by MESSAGE-REPLY rather than
INVMSGLEN by DISCONNECT.
C. Kilkenny Expires January 9, 2001 [Page 56]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
8. Sample Transmission
Here is a sample communication between two applications. The DTE
connects for output message transfer and downloads one message. The
DTE then initiates a graceful shutdown.
t1: <192><255><031>race$generic<255><032>TESTAPPL<255><254>
c1: <198><255><254>
t2: <193><033><002><255><254>
<193><053><255><254>
<195><054><255><254>
c2: <195><033><002><255><254>
<195><053><255><254>
<194><054><255><254>
t3: <198><255><254>
c3: <198><255><254>
c4: <200><255><064>HELLO WORLD.<255><254>
t4: <201><255><254>
t5: <199><255><254>
c5: <199><255><254>
This can be summarised as follows:
t1: DTE sends CONNECT, target service "race$generic", target
application "TESTAPPL"
c1: DCE responds READY
t2: DTE sends DO MODE OUTPUT, DO PDE, WILL RREF
c2: DCE responds WILL MODE OUTPUT, WILL PDE, DONT RREF
t3: DTE can continue with or without RREF, so it sends READY
c3: DCE responds READY
c4: DCE sends its first MESSAGE ("HELLO WORLD.").
t4: DTE returns a positive acknowledgement.
t5: After a keep alive timer expires, DTE requests shutdown.
c5: DCE confirms shutdown.
C. Kilkenny Expires January 9, 2001 [Page 57]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
Security Considerations
The current protocol specification caters for both connection and
message authentication, but it does state any authentication
algorithm or key values. Authentication codes are limited to 512
bits unless negotiated otherwise. Peers can agree the algorithm and
key values outside the scope of this document.
The protocol can be extended in order to support any number of
security features (independent of the end application). For example,
it would be relatively straightforward to encrypt the data and,
thereby, cater for confidentiality and additional data integrity.
References
[1] Postel, J., "Simple Mail Transfer Protocol", RFC 821,
USC/Information Sciences Institute, August 1982.
[2] Postel, J., Reynolds, J., "TELNET Protocol Specification", RFC
854, USC/Information Sciences Institute, May 1983.
[3] Postel, J., Reynolds, J., "TELNET Option Specifications", RFC
855, USC/Information Sciences Institute, May 1983.
[4] Butler, M., Postel, J., Chase, D., Goldberger, J., Reynolds,
J., "Post Office Protocol - Version 2", RFC 937,
USC/Information Sciences Institute, February 1985.
[5] Postel, J., Reynolds, J., "File Transfer Protocol (FTP)", RFC
959, USC/Information Sciences Institute, October 1985.
[6] Sun Microsystems, Inc., "RPC: Remote Procedure Call Protocol
Specification Version 2", RFC 1057, June 1988.
[7] Bernstein, D., "The Q Method of Implementing TELNET Option
Negotiation", RFC 1143, February 1990.
[8] Reynolds, J., Postel, J., "Assigned Numbers", RFC 1700, STD 2,
USC/Information Sciences Institute, October 1994.
[9] Gwinn, A., "Simple Network Paging Protocol - Version 3 - Two-
Way Enhanced", RFC 1861, Southern Methodist University,
October 1995.
Acknowledgments
Global Financial Networks wishes to thank to those who have
contributed to this draft specification.
C. Kilkenny Expires January 9, 2001 [Page 58]
Internet-Draft RACE Protocol Draft Version 1.3 July 2000
Author's Addresses
Charles Kilkenny
Global Financial Networks Limited
The Leys
2c Leyton Road
Harpenden
Hertfordshire AL5 2TL
United Kingdom
Phone: +44 (0)1582 467 486
Email: kilkenny@gfn.co.uk
C. Kilkenny Expires January 9, 2001 [Page 59]
