Kevin Zhang, Eitan Elkin Internet Draft XACCT Technologies Expiration: December 2001 Document: draft-kzhang-crane-protocol-00.txt Category: Standard Track June 2001 Common Reliable Accounting for Network Element (CRANE) Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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. Abstract This document defines the CRANE protocol that enables efficient and reliable delivery of any data, mainly accounting data from Network Elements to any systems, such as mediation systems and BSS/OSS. The protocol is developed to address the critical needs for exporting high volume of accounting data from NEÆs with efficient use of network, storage, and processing resources. This document specifies the architecture of the protocol and the message format, which MUST be supported by all CRANE protocol implementations. Kevin Zhang, et al Expires December 2001 1  Internet Draft The CRANE Protocol May 2001 Table of Contents Abstract..........................................................1 Table of Contents.................................................2 Introduction......................................................3 1.1 Specification of Requirements................................3 1.2 Terminology..................................................4 2 Protocol Overview..............................................6 2.1 Architectural view of CRANE..................................6 2.2 CRANE over TCP...............................................7 2.3 Alternate servers............................................7 2.4 Templates....................................................9 2.4.1 Template Transmission and Negotiation.......................9 2.4.2 Changing Templates.........................................11 2.5 Flow Control................................................12 2.6 Status Reporting............................................13 2.7 Sessions....................................................13 3 Header Format.................................................14 4 Messages......................................................16 4.1 Flow Start (START)..........................................16 4.2 Flow Start Acknowledge (START ACK)..........................16 4.3 Flow Stop (STOP)............................................17 4.4 Flow Stop Acknowledge (STOP ACK)............................17 4.5 Connect (CONNECT)...........................................18 4.6 Template Data (TMPL DATA)...................................18 4.7 Template Data Acknowledge (TMPL DATA ACK)...................22 4.8 Final Template Data (FINAL TMPL DATA).......................24 4.9 Final Template Data Acknowledge (FINAL TMPL DATA ACK).......24 4.10 Get Sessions (GET SESS)....................................25 4.11 Get Sessions Response (GET SESS RSP).......................25 4.12 Get Templates (GET TMPL)...................................27 4.13 Get Templates Response(GET TMPL RSP).......................28 4.14 Start Negotiation (START NEGOTIATE)........................30 4.15 Start Negotiation Acknowledge (START NEGOTIATE ACK)........31 4.16 Data (DATA)................................................31 4.17 Data Acknowledge (DATA ACK)................................33 4.18 Data Not Acknowledge (DATA NACK)...........................34 4.19 Error (ERROR)..............................................34 4.20 Status Request (STATUS REQ)................................35 4.21 Status Response (STATUS RSP)...............................36 5 Protocol Version Negotiation..................................38 6 References....................................................40 7 Acknowledgments...............................................40 8 Author's Address..............................................40 Kevin Zhang, et al Expires December 2001 2  Internet Draft The CRANE Protocol May 2001 Introduction Network Elements need to export usage data to mediation and business support systems (BSS) to facilitate accounting. There is a variety of ways to achieve the goal. All current methods have their advantages and disadvantages and many of them are legacies of older IT technologies or the Telco world. The problem arises when considering the fact that the real-time, high-performance methods (e.g. Cisco, NetFlow) lack any reliability features and the more reliable ones (e.g. RADIUS) are rather slow. SNMP and its derivatives are large processing and bandwidth consumers. The Telco world on the other hand has some solutions such as AMA and AMADNS or plain CDR log files which are backed up and processed in batch. These are reliable methods but do not meet the real-time and high-performance requirement of todayÆs rapidly evolving data networks. Thus, a critical need for a reliable, fast, efficient and flexible accounting protocol exists. There are few protocols that might be used for this purpose, such as RADIUS [1], DIAMETER [2], and various others. All these have their advantages and disadvantages. RADIUS is widely used and offers reliability, but it can handle only a few outstanding requests and is not extensible due to its limited command and attribute address space. RADIUS also does not allow unsolicited messages from a server to a client. A detailed analysis of deficiencies in RADIUS can be found in [3]. DIAMETER retains the basic RADIUS model, and tries to fix flaws in RADIUS. The current DIAMETER protocol only concerns with Internet access, and its support to accounting is closely associated with authentication/authorization events. DIAMETER attempts to solve many problems in the AAA area, by doing so, it does not addresses the efficiency and performance issues needed in an accounting protocol. The proposed CRANE protocol attempts to address the critical need from the industry for reliability, efficiency, high performance, and flexibility in accounting data transfer. 1.1 Specification of Requirements In this document, the keywords ôMUSTö, ôMUST NOTö, ôSHOULDö, ôSHOULD NOTö, and ôMAYö are to be interpreted as described in BCP 14 [5]. These keywords are not case sensitive in this document. Kevin Zhang, et al Expires December 2001 3  Internet Draft The CRANE Protocol May 2001 1.2 Terminology CRANE Protocol CRANE stands for Common Reliable Accounting for Network Element. The CRANE Protocol maybe referred as CRANE, or the Protocol in this document. Client or CRANE Client A client is an implementation on the data producing side of the CRANE protocol, messages and logics. The client is integrated with the network elementÆs software, enabling it to collect and send out accounting data to a mediation/billing system using the protocol defined herein. Server or CRANE Server A Business Support System (BSS) (e.g. CCB, Market Analysis, Fraud detection, etc.), a mediation system, or a part of it that connects to the client to receive accounting data. There could be more than one CRANE server connected to one CRANE client. For redundancy considerations there should be more than one CRANE server connected. Server Priority A CRANE server is assigned with a Priority tag. The accounting data is always delivered to the perceived operating CRANE server (from a CRANE client point of view) with the highest Priority value within a session. CRANE Session A session is a logical connection between a CRANE client and one or more CRANE servers for the purpose of delivering accounting data. Multiple sessions MAY be maintained concurrently in a CRANE client or a CRANE server, they are distinguished by a Session ID. Message The unit of data delivery across the interface between a CRANE client and a CRANE server. It includes the common CRANE header and possible control or user data payload. Data Template The accounting data, which is sent using the CRANE protocol, consists of data messages. The format and structure of the data are defined by a template. The template states the structure, data types and order of the fields in the record. Kevin Zhang, et al Expires December 2001 4  Internet Draft The CRANE Protocol May 2001 Data Record or Record An accounting data record. Records could be long and span multiple messages using fragmentation (handled by the transport layer). Data Sequence Number (DSN) An accounting data level sequence number, which is attached to all data messages to facilitate reliable and sequenced delivery. Kevin Zhang, et al Expires December 2001 5  Internet Draft The CRANE Protocol May 2001 2 Protocol Overview The CRANE protocol is designed to deliver accounting data reliably, efficiently, and quickly. Due to the nature of accounting data, large records often need to be transmitted; thus supporting fragmentation of large records is required. Furthermore, the value associated with accounting data is high; to prevent data loss, quick detection of unresponsive CRANE servers is also required for added robustness. The CRANE protocol can be viewed as an application that uses data transport service provided by lower layer protocols. It relies on a transport layer protocol to deliver reliable, in-sequence data packets. UDP is a simple connectionless transport layer protocol that has advantages of being fast and agile, but it provides no reliability and lacks flow control mechanisms. Hence, The CRANE protocol should not use UDP as the transport layer protocol, unless additional features such as reliability, sequence integrity, and flow control, etc, are provided. TCP and SCTP [4] are two transport layer protocols that fulfill the reliability requirement of CRANE. Either one of them MAY be used to transport CRANE messages. TCP answers some of requirements, but not all (e.g. quick detection of serverÆs failure or the fact that TCP is stream oriented and not record oriented). Therefore, SCTP [5] is the preferred way to transmit CRANE messages. 2.1 Architectural view of CRANE The CRANE protocol is an application running over a reliable transport layer protocol. The transport layer protocol is responsible for delivering CRANE messages between CRANE clients and CRANE servers. It MUST support the following capabilities: 1. Reliable, in-sequence message delivery. 2. Connection oriented. 3. Delivery of messages with a length of up to 2^32 octets (i.e. the transport layer has to support fragmentation of messages when running over IP). The transport layer MAY support: 1. Authentication. 2. Bundling of multiple messages into a single datagram. Possible transport layer protocols MAY be TCP or SCTP [5]. TCP supports the minimal requirements for CRANE, but lacks some desirable capabilities that are available in SCTP, these include: Kevin Zhang, et al Expires December 2001 6  Internet Draft The CRANE Protocol May 2001 1. Session level authentication. 2. Message based data delivery (as opposed to stream based). 3. Fast connection failure detection. Reliable delivery of accounting data is achieved through both the transport layer level and the CRANE protocol level. The transport layer acknowledgements are used to ensure quick detection of lost data packets and unresponsive servers, while the CRANE protocol acknowledges CRANE messages after they have been processed and the accounting information has been placed in persistent storage. Being a reliable protocol for delivering accounting data, traffic flowing from a CRANE client to a CRANE server is mostly accounting data. There are also bi-directional control message exchanges, though they only comprise of small portion of the traffic volume. The following diagram illustrates the CRANE protocol architecture: +----------------+ +----------------+ | CRANE | | CRANE |+ | User | | User ||+ +----------------+ +----------------+|| | CRANE | | CRANE |+| | Client | | Server ||+ +----------------+ +----------------+|| | Transport | ==========> | Transport |+| | Layer Protocol| <--------- | Layer Protocol ||+ +----------------+ +----------------+|| +----------------+| +----------------+ 2.2 CRANE over TCP TCP can be used as a transport layer for the CRANE protocol. CRANE running over TCP MUST observe the following rules: 1. The CRANE Client MUST accept TCP connections over a specific TCP port. 2. The CRANE Server MUST connect to the CRANE client, and SHOULD be responsible for reestablishing a connection in case of a failure. 3. CRANE messages are written as a stream of bytes into a TCP connection, the size of a CRANCE message is specified by the Message Length field of the CRANE message header. 2.3 Alternate servers For purposes of improved reliability and robustness, redundant CRANE server configuration MAY be employed. The CRANE protocol supports delivering accounting data to alternate CRANE servers, which are part of one mediation system. A CRANE session may comprise of one or more CRANE servers. The CRANE client is responsible for configuring network addresses of all CRANE Kevin Zhang, et al Expires December 2001 7  Internet Draft The CRANE Protocol May 2001 servers belonging to the session. A Server Priority is assigned to each CRANE server. The Server Priority reflects the CRANE clientÆs preference regarding which CRANE server should receive accounting data. The assignment of the Server Priority should consider factors such as geographical distance, communication cost, and CRANE Server loading, etc. It is also possible for several CRANE servers to have the same priority. In this case, the CRANE client could randomly choose one of them as the primary server to deliver accounting data. Additional features such as load balancing may be implemented in multi-server environment in the future. The process of configuring CRANE client is carried out using the NE configuration system and is outside the scope of this document. A CRANE client MUST deliver accounting data to its perceived operating CRANE Server with highest priority; if this CRANE server is deemed unreachable, the CRANE client MUST deliver the accounting data to the next highest priority CRANE server that is perceived to be operating. If no perceived operating CRANE servers are available, accounting data MUST be queued in the CRANE client until any CRANE server is available or queue space runs out. Accounting data delivery SHOULD revert to the higher priority server when it is perceived to be operating again. The CRANE protocol does not specify how a CRANE Client should redirect accounting data to various CRANE servers, which is considered an implementation issue. But all the supporting mechanisms are provided by the protocol to work in a multiple- servers environment (All the template negotiation and configuration procedures, etc.). The transport layer (together with some other means) is responsible for monitoring serverÆs responsiveness and notifying CRANE protocol for any failures. The client then may choose to transition to an alternate server. Implementation Note: The transition to an alternate CRANE server is an implementation issue and MUST occur under the following conditions: A) Transport layer notifies that the corresponding port of the CRANE server is unresponsive. B) Total size of unacknowledged accounting records has exceeded a threshold (configurable) for certain duration (configurable). C) A STOP message is received from the active server. D) A lower priority server is the active one and a higher priority server has recovered. Kevin Zhang, et al Expires December 2001 8  Internet Draft The CRANE Protocol May 2001 2.4 Templates The CRANE protocol enables efficient delivery of accounting data. This is achieved by negotiating a set of Data Templates for a session before actual accounting data is delivered. A template describes the order, type and meaning of the fields in the DATA message payload. By agreeing on session templates, CRANE servers understand how to process DATA messages received from a CRANE client. As a result, a CRANE client only needs to deliver actual accounting data without attaching any descriptors of the data; this reduces the amount of bytes sent over communication links. A template is an ordered list of keys. A key specifies an accounting item that a network element MAY collect and export. The specification MUST consist of the description and the data type of the accounting item. (e.g. 'Number of Sent Bytes' can be a key that is an unsigned integer 32 bit long). Keys are typically defined by a CRANE client. The protocol supports usage of several templates concurrently (for different accounting records). Keys contained in a template could be enabled or disabled. An enabled key implies that the outgoing data record will contain the data item, which the key specifies. A disabled key implies that the outgoing record will omit the specified data item. The enabling/disabling mechanism further reduces bandwidth requirement; it could also reduces processing in network elements as only needed data items would be produced. In a CRANE session, all the CRANE servers and the CRANE client MUST use the same set of templates and associated enable/disable status. The templatesÆ configuration and connectivity to the end application MUST be the same in all servers. The CRANE client MUST publish the relevant templates to all CRANE servers in a session through user configuration, before it starts to send data according to the templates. The complete set of templates residing in a CRANE client MUST bear a configuration ID that identifies the template set. Each data record arrives with the Template ID and the Configuration ID, so that the correct template can be referenced. A server, which receives a record with an older Configuration ID, MAY handle the record gracefully by keeping some template history. The transport layer should ensure that a server would not get messages with future configuration IDs. 2.4.1 Template Transmission and Negotiation As stated before, all CRANE servers MUST use the same set of templates in a CRANE session. In case that servers do not share the same set of templates (the templates are considered different if different keys are enabled or disabled), a negotiation process between the client and the server would ultimately determine one set Kevin Zhang, et al Expires December 2001 9  Internet Draft The CRANE Protocol May 2001 of templates that is accepted and used by all the CRANE servers in a session. After a CRANE session is established and the server sent a START message stating that it is ready to take part in the session, the client MUST deliver the set of templates that it intends to use by sending a TMPL DATA message to the server. The CRANE server MUST acknowledge the reception of the set of templates. Templates are negotiable between a CRANE client and CRANE servers. A CRANE server may propose changes to the templates received from a CRANE client (e.g. enabling some keys and disabling others), or it can acknowledge the templates as is. In the case that a template or a key is not recognized by the server (e.g. they might be added to the client after the server configuration has completed), the server MAY choose to disable each unknown key or unknown templates in order to avoid unnecessary traffic. A template is disabled when all the keys are disabled. If changes were received from the CRANE servers, the client will send the changed template set to all connected servers (using FINAL_TMPL_DATA message). It is the clientÆs responsibility to decide what would be the final set of templates used by a session. At this time, each CRANE server MUST accept and acknowledge the templates without changing anything (to avoid deadlock and loop conditions). Each CRANE server is given a single chance to propose any changes during the negotiation process. The template negotiation process is outlined as follows: A) CRANE client sends a TMPL DATA message with a set of templates. B) CRANE server either responds with the TMPL DATA ACK message with changes in the template set (process continues in step C) or responds with FINAL TMPL DATA ACK message if no changes are needed (process continues in step E). C) CRANE client receives proposed changes, incorporates them if possible and then sends a FINAL TMPL DATA message containing the new set of templates to all servers (in order to deploy the change). D) CRANE server receives the FINAL TMPL DATA message containing the new set of templates and MUST send a FINAL TMPL DATA ACK message to acknowledge the reception of the templates. No changes are allowed at this stage and the templates, which the client sent, are going to be used. E) CRANE client receives a FINAL TMPL DATA ACK message from the server and can assume that the server knows which templates to use. All these stages take place only when there are multiple CRANE servers with differences in the template set (e.g. not all key states are identical). If all CRANE servers within a session share the same configuration exactly, all servers will respond with FINAL TMPL DATA ACK and the ping-pong between the client and the servers Kevin Zhang, et al Expires December 2001 10  Internet Draft The CRANE Protocol May 2001 will end immediately. This is the common case, but in case some other CRANE server has a different configuration, the protocol offers the way to maintain consistency among CRANE servers. Implementation Note: TMPL DATA messages SHOULD be sent only after all DATA messages with the previous configuration have been acknowledged. This allows the server to transition properly to the new configuration. 2.4.2 Changing Templates TMPL DATA messages allow for deploying and publicizing templates. Still, a need to configure the template set exists. Each of the CRANE servers in the CRANE session may change the template set, which is typically requested by an end-user through User Interface. The end-users need to know what templates are available and the current template set status. All related messages incorporate a Request ID field for tagging purposes and matching requests and responses. This field contains a 16 bit counter incremented with every request and is set by the initiator of the request. Along with the CRANE serverÆs IP address and port number, this constitutes a unique identifier for a request. This value MUST be copied to Request ID field in the response in order to associate a specific response with a request. The following steps are performed in order to change the templates: A) The server MUST retrieve from CRANE client the template set that requires change by issuing GET TMPL message. The server can issue a GET TMPL even if it did not issue a START message beforehand. B) After received a GET TMPL message, the client sends back a GET TMPL RSP message with the requested data. C) The server makes the necessary changes to the templates and sends back a START NEGOTIATION message. This message triggers the CRANE client to inquire changes made by the CRANE server. D) After received a START NEGOTIATE message, the client MUST respond with START NEGOTIATE ACK message followed by a TMPL DATA message. From this point on, the template negotiation process starts. E) After performed the change, the client MUST update all other CRANE servers in the CRANE session with the updated template set (using FINAL TMPL DATA). Implementation Note: While configuring templates, the client should continue sending accounting data according to the older template structure. Kevin Zhang, et al Expires December 2001 11  Internet Draft The CRANE Protocol May 2001 2.5 Flow Control After templates have been deployed, DATA messages start to arrive at the primary CRANE server (the operational one with the highest priority within the CRANE session). Each DATA message contains a Data Sequence Number (DSN). The primary CRANE server MUST accept the data as long as it is in-sequence. Out-of-sequence DATA messages should be discarded. The CRANE server detects the start of accounting data when it receives the first DATA message either after startup or after a server transition. The first DATA message MUST have the 'S' bit ('DSN Synchronize' bit) set by the CRANE client. Upon reception of the message with initial DSN, the server MUST accept all in-sequence DATA messages. The DSN MUST be incremented by 1 for each new DATA message originated from the client. A CRANE server MUST acknowledge the reception of DATA messages by sending DATA ACK messages. The DATA ACK MUST contain the DSN of the last received in-sequence DATA message. If the CRANE server receives an Out Of Sequence DATA message, it MUST send a DATA NACK message. The DATA NACK message contains the DSN of the last received in-sequence DATA message. It will trigger an immediate retransmission of unacknowledged records. The CRANE client is responsible for delivering all the records. In the case of alternate servers, there could be a scenario when one server does not receive all the sequence of records but another redundant CRANE server for the same mediation system receives the rest of the records. For example, server #1 could receive records 3042-3095 and then 3123-..., with server #2 receiving records 3096- 3122. It is the sender's responsibility to deliver all records, in- sequence, but not to the same server. The billing/mediation system eventually receives all the records, possibly through more than one CRANE server. The CRANE client MUST convey all the records it received to the billing/mediation system. This MAY result in duplicate records in the billing/mediation system. In this case, the DSN MUST be used to remove duplicates. To aid in the process of duplicate removal, whenever a record is re- sent to another server, its 'Duplicate' bit MUST be set to suggest that this record might be a duplicate. Implementation Note: When the amount of unacknowledged records reaches a threshold, a timer should be started. If the timeout occurs, all the unacknowledged records are either retransmitted, if no other CRANE server is available to receive them, or sent to another server (while setting the 'D' bit in each retransmitted DATA). Kevin Zhang, et al Expires December 2001 12  Internet Draft The CRANE Protocol May 2001 The flow control is adapted to the alternate servers scenario. A server MUST send a START message in order to be able to receive any messages (TMPL messages first and then DATA messages). It MUST then receive a START ACK in order to move to a 'ready' state to anticipate CRANE clientÆs messages (TMPL DATA MUST arrive, but there is no commitment to receive DATA messages as this might be a lower priority server). A STOP message tells the client to stop sending messages to that server. The server MAY wait to receive a STOP ACK in order to leave its 'ready' state. 2.6 Status Reporting The CRANE client SHOULD collect and send out meta-data about the data collected (counters, statistics, etc.). This is done by creating status templates, which are treated like any other template, with the exception that these templates are marked with a 'Status' bit. Status templates are used with the set of STATUS REQ and STATUS RSP messages. A server MAY issue a STATUS REQ to a CRANE client and receive a STATUS RSP message with the requested data. 2.7 Sessions A CRANE client MAY deliver accounting data to different mediation/billing systems by establishing different CRANE sessions. Each session MAY consist of several CRANE servers in a redundant configuration. The session ID imbedded in all the CRANE messages enables the correct association of CRANE sessions with CRANE users. All the CRANE processes (e.g. template negotiation, configuration, flow control, etc.) should be carried out in the same way in a multi session scenario. Each session has its set of templates (these are the same templates, but the keys could be enabled or disabled differently). The sessions are configured in the NE, each with a different session name with associated Session IDs. The session ID is carried in each message to associate the message with a specific session. A CRANE server MAY take part in different sessions. When configuring a server, it needs to know which sessions does it participate in. The server can issue a GET SESS message to receive a list of sessions, which it participates in. Kevin Zhang, et al Expires December 2001 13  Internet Draft The CRANE Protocol May 2001 3 Header Format A summary of the CRANE protocol data format is shown below. The fields are transmitted from left to right. 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Version | Message ID | Session ID | Message Flags | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Version: 8 bit unsigned int The field indicates the version number that is associated with the CRANE protocol implementation. This field MUST be set to 1 to indicate CRANE protocol Version 1. Message ID: 8 bit unsigned int The field holds a message Type Code. These message IDs are defined as follow: Message Name Short Name Message ID --------------------- --------------- ------------ Reserved 0x0000 Flow Start START 0x0001 Flow Start Acknowledge START ACK 0x0002 Flow Stop STOP 0x0003 Flow Stop Acknowledge STOP ACK 0x0004 Connect CONNECT 0x0005 Template Data TMPL DATA 0x0010 Template Data Acknowledge TMPL DATA ACK 0x0011 Final Template Data FINAL TMPL DATA 0x0012 Final Template Data Ack. FINAL TMPL DATA ACK 0x0013 Get Sessions GET SESS 0x0014 Get Sessions Response GET SESS RSP 0x0015 Get Template GET TMPL 0x0016 Get Template Response GET TMPL RSP 0x0017 Start Negotiation START NEGOTIATE 0x0018 Start Negotiation Ack. START NEGOTIATE ACK 0x0019 Data DATA 0x0020 Data Acknowledge DATA ACK 0x0021 Data Not Acknowledge DATA NACK 0x0022 Error ERROR 0x0023 Status Request STATUS REQ 0x0030 Status Response STATUS RSP 0x0031 Kevin Zhang, et al Expires December 2001 14  Internet Draft The CRANE Protocol May 2001 Session ID: 8 bit unsigned char The field holds the Session ID that distinguishes messages sent in different CRANE sessions. The session ID is ignored in the case of GET SESS and GET SESS RSP messages. Section 2.7 gives more detailed discussions on sessions and session IDs. Message Flags: 8 bit unsigned char The field is used in order to identify any options. Unless otherwise specified, the flags are set to zero on transmit and are ignored on receipt. Message Length: 32 bit unsigned int The field holds the total length of the message in octet including the header. Kevin Zhang, et al Expires December 2001 15  Internet Draft The CRANE Protocol May 2001 4 Messages This section defines CRANE mandatory messages. They MUST be supported by any CRANE protocol implementation. 4.1 Flow Start (START) Description The Flow Start message is sent from a CRANE server to a CRANE client to indicate that the CRANE server is ready to receive messages. Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Header | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Message Code 0x0001 Flow Start 4.2 Flow Start Acknowledge (START ACK) Description This message is sent by a CRANE client to acknowledge the reception of a START message from a specific CRANE server It is sent only to that server to indicate that the client considers it ready to receive messages. Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Header | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Client Boot Time | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Message Code 0x0002 Flow Start Acknowledge Kevin Zhang, et al Expires December 2001 16  Internet Draft The CRANE Protocol May 2001 Client Boot Time: 32 bit unsigned int The field holds the timestamp of the last client startup in seconds from 1970. This field can be combined along with the DSN and the clientÆs IP address as a system wide unique record identifier. 4.3 Flow Stop (STOP) Description The message is sent from a CRANE server to a CRANE client to instruct it to stop sending data (to that server). The STOP message does not disconnect the server, it only pauses the CRANE client from sending message. Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Header | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Message Code 0x0003 Data Flow Stop 4.4 Flow Stop Acknowledge (STOP ACK) Description The message acknowledges a STOP message issued by a CRANE server. It indicates to the server that it should exit the ôreadyö state. Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Header | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Message Code 0x0004 Flow Stop Acknowledge Kevin Zhang, et al Expires December 2001 17  Internet Draft The CRANE Protocol May 2001 4.5 Connect (CONNECT) Description The message is sent from a CRANE server to a CRANE client to identify itself. The message MUST be the first message sent over a connection between the server and the client. Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Header | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Server Address | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Server Port | Reserved | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Message Code 0x0005 Connect Server Address: 32 bit unsigned int A 32 bit integer identifying the server IP address (IPV4) Server Port: 16 bit unsigned int A 16 bit integer holding the serverÆs port number (the port number specified here doesnÆt necessarily have to match the port number used by the transport layer) 4.6 Template Data (TMPL DATA) Description A CRANE client sends the Template Data message to a CRANE server after a START or a START NEGOTIATE message was received from the server. The message MUST contain all the templates that are going to be used. It SHOULD also include the template for the status records (See section 2.6) The receiving CRANE server MUST acknowledge the message by sending either a TMPL DATA ACK (if template changes are needed) or a FINAL TMPL DATA ACK message. For more information, see section 2.4.1. Kevin Zhang, et al Expires December 2001 18  Internet Draft The CRANE Protocol May 2001 Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Header | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Config ID |E| Flags | Number of Templates | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | ~ Template Block ~ | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Template Block ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Message Code 0x0010 Template Data Configuration ID: 8 bit unsigned char This field holds a version number assigned to a template configuration by a CRANE client when sending a TMPL DATA message. A set of templates constitutes a configuration, which is versioned. Change to any of the templates would result in a new template version, and the version number would be incremented by one. An implementation SHOULD handle rollovers of this field. Flags: 8 bit unsigned char The Flags field is used to identify any options. The following flag is defined by the CRANE protocol: The 'E' bit indicates the endian state of data messages. If set to 1, data is in big endian format, otherwise little endian is used. Number of Templates: 16 bit unsigned int The field holds the number of Templates (described in a Template Block) that are included in the message. Template Block A template Block contains the definition of a specific template. Kevin Zhang, et al Expires December 2001 19  Internet Draft The CRANE Protocol May 2001 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Template ID | Number of Keys | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |S| Template Flags | Description Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Template Block Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | ~ Description ~ | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | ~ Key Block ~ | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Key Block ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Template ID: 16 bit unsigned int Identifies the template to the CRANE server during the data flow. Number of Keys: 16 bit unsigned int Counts the number of keys in this template. Template Flags: 16 bit unsigned int The field contains flags, which indicate different attributes of the template. Unless otherwise specified, the flags are set to zero on transmit and are ignored on receipt. The following flag is defined by the CRANE protocol: The 'S' bit ('Status' bit) indicates that the template is a status template, and correspondingly received data should be treated as status information. See section 2.6 for more details. Description Length: 16 bit unsigned int The field holds the length of a template description (e.g. "Aggregated by interface and ToS bits"). The field limits descriptions to 64Kb long. If no description is supplied, the length MUST be 0. Template Block Length: 32 bit unsigned int The field holds the length of the template block in octets. Kevin Zhang, et al Expires December 2001 20  Internet Draft The CRANE Protocol May 2001 Description: Variable length unsigned char A variable length text field that describes the template, padded to the next 32 bit boundary with 0. Key Block A key Block contains the definition of a specific key within a template. 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Key ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Key Type ID | Reserved | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |D| Key Attribute Vector | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Key ID: 32 bit unsigned int The Key Identifier. See section 2.4 for more details on Keys and Templates. Key Type ID: 16 bit unsigned int It identifies the data type of the key. The data types of fixed length are defined as following: Data Type Data Type ID --------------------- -------------- Boolean (1) 0x0001 Unsigned Integer8 0x0002 Signed Integer8 0x0003 Unsigned Integer16 0x0004 Signed Integer16 0x0005 Unsigned Integer32 0x0006 Signed Integer32 0x0007 Unsigned Integer64 0x0008 Signed Integer64 0x0009 Float (2) 0x000a Double (2) 0x000b The data types of variable length are defined as following: String (3) 0x400c Null Terminated String 0x400d UTF-8 String 0x400e UTF-16 String 0x400f IP address (Ipv4) 0x0010 Kevin Zhang, et al Expires December 2001 21  Internet Draft The CRANE Protocol May 2001 IP address (Ipv6) 0x0011 Time (sec) (4) 0x0012 Time (msec) (5) 0x0013 Time (usec) (6) 0x0014 Arbitrary Data (BLOB) (7) 0x4015 (1) Boolean is represented as a single octet holding 0 for a value of FALSE and 1 for a value of TRUE. (2) Float and Double are single and double precision floating point numbers which comply with the IEEE-754 standard. (3) The String is prefixed by a 32 bit length field that holds the length of the string and followed by ASCII codes for the string characters. This implementation MUST only be used for the data passed and not in the protocol's headers. (4) Time (sec) is a 32 bit value, most significant octet first - seconds since 00:00:00 GMT, January 1, 1970. (5) Time (msec) is a 64 bit value, most significant octet first - milliseconds since 00:00:00 GMT, January 1, 1970. (6) Time (usec) is a 64 bit value, most significant octet first - microseconds since 00:00:00 GMT, January 1, 1970. (7) The arbitrary data is prefixed by a 32 bit length field and followed by the data in binary format. Key Attribute Vector: 32 bit unsigned int It is used to identify any attributes of the key. Unless otherwise specified, the attributes are set to zero on transmit and are ignored on receipt. The following attributes are defined in this document: The 'D' bit ('Disabled bit') is set when the key is disabled in this template. By default the 'D' bit is set to 0. 4.7 Template Data Acknowledge (TMPL DATA ACK) Description The message is sent from a CRANE server to a CRANE client after a TMPL DATA message has been received. It also proposes key status changes (enable/disable) for the templates. If a CRANE server whishes to acknowledge reception of TMPL DATA without changes, it MUST use FINAL TMPL DATA ACK. Kevin Zhang, et al Expires December 2001 22  Internet Draft The CRANE Protocol May 2001 Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Header | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Config. ID | Reserved | Number of Template Changes | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | ~ Template Change Block ~ | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Template Change Block... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Message Code 0x0011 Template Data Acknowledge Configuration ID: 8 bit unsigned char A version number assigned to the template configuration by the client when sending the TMPL DATA message. This field MUST contain the value copied from the acknowledged TMPL DATA. Number of Template Changes: 16 bit unsigned int A counter which counts the number of Template acknowledgment (described as Template Acknowledge Blocks) that is included in the message. Template Change Block 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Template ID | Number of Keys | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | ~ Key Block ~ | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Template ID: 16 bit unsigned int Identifies the template to the CRANE client. Number of Keys: 16 bit unsigned int Holds the number of keys included in the template. Kevin Zhang, et al Expires December 2001 23  Internet Draft The CRANE Protocol May 2001 Key Block Only relevant key ID and the Attribute. See definition at 4.6. 4.8 Final Template Data (FINAL TMPL DATA) Description The message is sent by a CRANE client to all the CRANE servers in a session, to finalize the changes. It is equivalent to the TMPL DATA message, with the only difference that a server must accept the templates in this message. Message Format Identical to the TMPL DATA (see section 4.6) Message Code 0x0012 Final Template Data 4.9 Final Template Data Acknowledge (FINAL TMPL DATA ACK) Description The CRANE server acknowledges reception of the TMPL DATA or FINAL TMPL DATA by sending a Final Template Data Acknowledge, which does not carry any changes. As opposed to TMPL DATA ACK messages which carry change information, FINAL TMPL DATA ACK message means that the server accepted the templates and has no wish to change the keys inside. A server MAY respond with this message to a TMPL DATA (if it has no changes). A server MUST respond with this message to a FINAL TMPL DATA, which means it had its chance to make changes. Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Header | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Config. ID | Reserved | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Message Code 0x0013 Final Template Data Acknowledge Configuration ID: 8 bit unsigned char A version number assigned to the template configuration by the client when sending the TMPL DATA or FINAL TMPL DATA messages. Kevin Zhang, et al Expires December 2001 24  Internet Draft The CRANE Protocol May 2001 This field MUST contain the configuration ID copied from the acknowledged message. 4.10 Get Sessions (GET SESS) Description The message is sent by a CRANE server to a CRANE client to query what are the sessions it should participate. This is typically done just before a UI configuration of the CRANE clientÆs templates. As each session has its own set of templates, there is a need to know what are all the sessions that this server is taking part in. The Session ID field in the common message header MUST be ignored upon reception. Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Header | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Request ID | Reserved | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Message Code 0x0014 Get Sessions Request ID: 16 bit unsigned int A number assigned to the request by the server when sending the GET SESS message. The same Request ID should be placed in the GET SESS RSP message in order to associate it with the request. 4.11 Get Sessions Response (GET SESS RSP) Description The message is sent by a CRANE client to a CRANE server as a reply to a GET SESS request. The message MUST contain all information about any session with which the requesting server is associated. The Session ID field in the common message header MUST be ignored upon reception. Kevin Zhang, et al Expires December 2001 25  Internet Draft The CRANE Protocol May 2001 Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Header | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Request ID | Number of Sessions | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Vendor String Length | Reserved | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-| | | ~ Vendor String ~ | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | ~ Session Block ~ | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Session Block ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Message Code 0x0015 Get Sessions Response Request ID: 16 bit unsigned int Holds a request identifier which MUST be the same as the one placed in the corresponding GET SESS message. Number of Sessions: 16 bit unsigned int Holds the number of session blocks in the message. Vendor String Length: 16 bit unsigned int The field holds the length of vendor string field. The field limits vendor strings to 64Kb long. If no such string is supplied, the length MUST be set to 0. Vendor String: Variable length unsigned char It is a variable length field identifies the vendor that created the session. The information differentiates similar templates of different vendors. The actual format of the information is application specific and outside the scope of this document. Kevin Zhang, et al Expires December 2001 26  Internet Draft The CRANE Protocol May 2001 Session Block 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Session ID | Reserved | Session Name Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Session Description Length | Reserved | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | ~ Session Name ~ | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | ~ Session Description ~ | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Session ID: 8 bit unsigned char It is an identifier of a CRANE session, which MUST be included in all the message exchanges pertaining to the session. Session Name Length: 16 bit unsigned int Holds the length of the Session Name field. As a name is mandatory to differentiate between sessions, this field MUST NOT be 0. Session Description Length: 16 bit unsigned int The field holds the length of a session description. If no description is supplied, the length MUST be set to 0. Session Name: Variable length unsigned char The field contains the name for a session, which MAY be displayed to end-users. Session Name MUST be unique within a CRANE client. This field is mandatory and MUST be a part of any Session Block. Session Description: Variable length unsigned char The field contains descriptions of a session that could also be displayed to end users. 4.12 Get Templates (GET TMPL) Description The message is sent by a CRANE server to a CRANE client to query templates in a session. Kevin Zhang, et al Expires December 2001 27  Internet Draft The CRANE Protocol May 2001 Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Header | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Request ID | Reserved | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Message Code 0x0016 Get Templates Request ID: 16 bit unsigned int A number assigned to the request by the server when sending the GET TMPL message. The same Request ID should be placed in the GET TMPL RSP message in order to associate it with the request. 4.13 Get Templates Response(GET TMPL RSP) Description The message is sent by a CRANE client to a CRANE server as a response to a GET TMPL message. The message SHOULD contain all templates available for the specific session. Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Header | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Request ID | Number of Templates | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | ~ Template Block ~ | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Template Block ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Message Code 0x0017 Get Templates Response Request ID: 16 bit unsigned int Holds a request identifier which MUST be the same as the one placed in the corresponding GET TMPL message. Kevin Zhang, et al Expires December 2001 28  Internet Draft The CRANE Protocol May 2001 Number of Templates: 16 bit unsigned int Holds the number of Templates (described in a Template Block) that are included in the message. Template Block Same as the template block defined in the TMPL DATA message (see section 4.6), only using Extended Key Blocks instead of key blocks. Extended key Blocks contain informational data to display to end-users. Extended Key Block The extended Key Block is similar to the Key Block defined in section 4.6, and this document will only describe the added data. 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Key ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Key Type ID | Key Name Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Key Label Length | Key Help Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | ~ Key Name ~ | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | ~ Key Label ~ | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | ~ Key Help ~ | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |D| Key Attribute Vector | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Key ID: 32 bit unsigned int Same as section 4.6. Key Type ID: 16 bit unsigned int Same as section 4.6. Key Name Length: 16 bit unsigned int Holds the length of the Key Name field. Kevin Zhang, et al Expires December 2001 29  Internet Draft The CRANE Protocol May 2001 Key Label Length: 16 bit unsigned int Holds the length of the Key Label field. Length of 0 means that the Label field is to be skipped. Key Help Length: 16 bit unsigned int Holds the length of the Key Help field. Length of 0 means that the Help field is to be skipped. Key Name: Variable length unsigned char A string which contains a name for the key, which could be displayed to end users. Key Name MUST be unique (within the template) and case sensitive. This field is mandatory and MUST be a part of any Key Block. Key Label: Variable length unsigned char A descriptive label which could be displayed in any UI data entry for this key. This field SHOULD be a part of any Key Block. Key Help: Variable length unsigned char Any Help string that could be displayed to end users concerning this key. This field MAY be a part of any Key Block. Key Attribute Vector: 32 bit unsigned int Same as section 4.6. 4.14 Start Negotiation (START NEGOTIATE) Description The message is sent by a CRANE server after the configuration process has completed. The message should initiate template negotiation by the client with all CRANE servers in a session. The CRANE server should re-send this message up to 3 times with repeat interval of 5 seconds unless it is acknowledged by the CRANE client. Otherwise, the operator will be informed. The client should send TMPL DATA message to the servers after acknowledged the message. Kevin Zhang, et al Expires December 2001 30  Internet Draft The CRANE Protocol May 2001 Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Header | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Message Code 0x0018 Start Negotiation 4.15 Start Negotiation Acknowledge (START NEGOTIATE ACK) Description The message MUST be sent by a CRANE client to the server to acknowledge the reception of the START NEGOTIATE message. Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Header | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Message Code 0x0019 Start Negotiation Acknowledge 4.16 Data (DATA) Description The message carries actual accounting data from a CRANE client to a CRANE server. A record data is a collection of fields that matches a specific template. Kevin Zhang, et al Expires December 2001 31  Internet Draft The CRANE Protocol May 2001 Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Header | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Template ID | Config. ID |S|D| Flags | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Data Sequence Number (DSN) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | ~ Record Data ~ | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Message Code 0x00020 Data Template ID: 16 bit unsigned int The Template ID field identifies the template. Configuration ID: 8 bit unsigned char A version number assigned to the template configuration by the client. The version is needed here to prevent out-of-the-blue messages with outdated templates arriving and erroneously processed. A server MAY keep a short history of templates in order to cope with this scenario. Record Flags: 8 bit unsigned char This field contains flags, which have an impact on the processing of the record. Unless otherwise specified, the flags are set to zero on transmit and are ignored on receipt. The following flags are defined in this document: The 'S' bit ('DSN Synchronize' bit) which when set, indicates that this record is the first one a server receives after starting (or restarting) data transmission to this server, and therefore, the server MUST set the initial DSN to the DSN specified in the record. The flag is set to zero by default. The 'D' bit ('Duplicate' bit) which is set on records that are re-sent to an alternate server, after the current one didn't respond. When the same records are sent to different servers there is a possibility that they might create duplication. The billing/mediation system SHOULD take Kevin Zhang, et al Expires December 2001 32  Internet Draft The CRANE Protocol May 2001 notice that records with the 'D' bit se may be duplicates, and handle these accordingly. Data Sequence Number: 32 bit unsigned int Holds the record sequence number which is used to acknowledge and to order the delivery of data. The initial DSN number should be generated randomly. Record Data: Variable Length unsigned octets The actual accounting/billing data which is transmitted in the same way the template defined it. This is the payload data. 4.17 Data Acknowledge (DATA ACK) Description The message is sent from a CRANE server to acknowledge receipt of records. It acknowledges the maximal in-sequence DSN received. Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Header | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Data Sequence Number | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Config. ID | Reserved | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Message Code 0x00021 Data Acknowledge Data Sequence Number: 32 bit unsigned int The maximal in-sequence DSN that was received by the server. Configuration ID: 8 bit unsigned char A version number assigned to the template configuration by the client. The version is needed here to prevent out-of-the-blue messages with outdated templates arriving and erroneously processed. A server MAY keep a short history of templates in order to cope with this scenario. Kevin Zhang, et al Expires December 2001 33  Internet Draft The CRANE Protocol May 2001 4.18 Data Not Acknowledge (DATA NACK) Description The DATA NACK message is sent from a CRANE server to trigger a retransmission of the records, starting from the next in- sequence record after the specified DSN. The DSN carried in the message is the last in-sequence DSN received by the server. Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Header | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Data Sequence Number | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Config. ID | Reserved | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Message Code 0x00022 Data Not Acknowledged Data Sequence Number: 32 bit unsigned int The maximal in-sequence DSN that was received by the server. Configuration ID: 8 bit unsigned char A version number assigned to the template configuration by the client. The version is needed here to prevent out-of-the-blue messages with outdated templates arriving and erroneously processed. A server MAY keep a short history of templates in order to cope with this scenario. 4.19 Error (ERROR) Description The message is used to indicate an error condition that was detected by the sender. Kevin Zhang, et al Expires December 2001 34  Internet Draft The CRANE Protocol May 2001 Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Header | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Timestamp | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Error Code | Description Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Description ... +-+-+-+-+-+-+-+-+-+-+ Message Code 0x00023 Error Timestamp: 32 bit unsigned int This field contains a timestamp as seconds since 00:00:00 GMT, January 1, 1970. Error Code: 16 bit unsigned int This field contains a code associated a table of different errors. The following codes are defined in this document: Reason Error Code ----------- -------------- Unknown 0 Description Length: 16 bit unsigned int The field specifies the length of the description field. If no description is supplied, this field MUST contains 0. Description: Variable Length unsigned char A variable length text field contains the description that the sender wants to add to the ERROR message. 4.20 Status Request (STATUS REQ) Description The servers MAY ask the client for its status. The status SHOULD include a collection of states, counters, accumulators of the collection part that resides within the client. The Kevin Zhang, et al Expires December 2001 35  Internet Draft The CRANE Protocol May 2001 status MAY include more information on the CRANE client itself. The status reporting mechanism relies on the status template which SHOULD be sent to the CRANE server in the TMPL DATA message. In case no such template exists, no status information can be delivered. Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Header | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Message Code 0x0030 Status Request 4.21 Status Response (STATUS RSP) Description The client responds to a STATUS REQ by sending its status to a server. The message includes a status report that MUST be compatible with a status template that SHOULD have passed beforehand. In case no such template exists, no status information can be delivered. Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Header | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Template ID | Configuration ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Record Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Record Data ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Message Code 0x0031 Status Response Template ID : 16 bit unsigned int The Template ID field identifies the template. Configuration ID: 16 bit unsigned int Kevin Zhang, et al Expires December 2001 36  Internet Draft The CRANE Protocol May 2001 A version number assigned to the template configuration by the client. The version is needed here to prevent out-of-the-blue messages with outdated templates arriving and erroneously processed. A server MAY keep a short history of templates in order to cope with this scenario. Record Length: 32 bit unsigned int Holds the length of the record's data in number of octets Record Data: Variable Length unsigned octets The actual status data that is transmitted in the way defined by the status template. For more details see section 2.6. Kevin Zhang, et al Expires December 2001 37  Internet Draft The CRANE Protocol May 2001 5 Protocol Version Negotiation Since the CRANE protocol may run over different transport layers, a transport neutral version negotiation mechanism running over UDP is defined. A CRANE server MAY query a CRANE client about the protocol version and transport layer being used by the client by sending a datagram on an agreed UDP port. The client MUST answer to this request with a datagram containing the protocol version, the transport type and the port that the client uses for the specific transport. The clientÆs reply to a version negotiation request MUST comply with the following structure: Message Format 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Default Protocol Info | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Additional Protocols Count | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Additional Protocols Info ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Default Protocol Info: The field contains information of the default protocol supported by the client. The field is structured as a Protocol Info Block described below. Additional Protocols Count: 32 bit unsigned int The field specifies the number of additional protocols supported by the client. In the case that only the default protocol is supported, the field MUST be set to 0. Additional Protocols Info: Array of Protocol Info Blocks (described below) contain information about protocols supported by the client. Kevin Zhang, et al Expires December 2001 38  Internet Draft The CRANE Protocol May 2001 Protocol Info Block 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Transport Type | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Protocol Version | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Port Number | Reserved | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Transport Type: 32 bit unsigned int Type of transport: 1 û TCP, 2 û SCTP Protocol Version: 32 bit unsigned int Version number of the CRANE protocol supported over the specific transport layer. Port Number: 16 bit unsigned int Port number (either SCTP or TCP port) used for the protocol Kevin Zhang, et al Expires December 2001 39  Internet Draft The CRANE Protocol May 2001 6 References [1] C. Rigney, et al., "Remote Authentication Dial In User Service (RADIUS)", RFC 2865, June 2000. [2] P. R. Calhoun, et al., "DIAMETER Base Protocol", draft-ietf- aaa-diameter-02.txt, IETF Work in Progress, April 2001. [3] P. R. Calhoun, et al., ôDIAMETER Framework Documentö, draft- ietf-aaa-diameter-framework-01.txt, IETF Work in Progress, March 2001. [4] R. Stewart et al., "Simple Control Transmission Protocol", RFC 2960, October 2000. [5] S. Bradner, ôKey words for use in RFCs to Indicate Requirement Levelsö, BCP 14, RFC 2119, March 1997. 7 Acknowledgments 8 Author's Address Questions about this memo can be directed to: Kevin Zhang (Editor) XACCT Technologies, Inc. 2900 Lakeside Drive Santa Clara, CA 95054 Phone +1 301 455 4802 Email: kevin.zhang@xacct.com Eitan Elkin XACCT Technologies, Ltd. 12 Hachilazon St. Ramat-Gan, Israel 52522 Phone +1 972 3 576 4111 Email: eitan@xacct.com Kevin Zhang, et al Expires December 2001 40