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]