RFC 3423
XACCT's Common Reliable Accounting for Network Element (CRANE) Protocol Specification Version 1.0
RFC 3423 ✨ XACCT's CRANE Protocol, Version 1.0 🎀
Okay bestie, this one is a whole accounting protocol 💅 It's called CRANE, short for Common Reliable Accounting for Network Element. Here's the title block, so you know who wrote it and where it fits:
- RFC number: 3423
- Title: XACCT's Common Reliable Accounting for Network Element (CRANE) Protocol Specification Version 1.0
- Authors: K. Zhang and E. Elkin, both from XACCT Technologies 👑
- Category: Informational 🦋
- Date: November 2002
- Obsoletes / Updates: the title block doesn't list anything it obsoletes or updates 🌸
Status of this Memo 📝
This one is for information only 💜 It's not an Internet standard of any kind. Anyone can share it freely, with no limits on distribution.
Copyright Notice ©️
Copyright (C) The Internet Society (2002). All Rights Reserved.
Abstract 🌈
So CRANE is a protocol for moving data, mostly accounting data, from Network Elements to systems like mediation systems and Business Support Systems (BSS) / Operations Support Systems (OSS). The goal is reliable, efficient delivery, especially when there's a huge amount of accounting data to export from NEs, and the network, storage, and processing resources have to be used wisely 🔥
This document lays out the architecture of the protocol and its message format. Every CRANE implementation MUST support them, no exceptions 🫶
Table of Contents 🗂️
1 Introduction...................................................2
1.1 Specification of Requirements.............................3
1.2 Terminology...............................................3
2 Protocol Overview..............................................5
2.1 CRANE Architecture........................................6
2.2 CRANE over TCP............................................7
2.3 Alternate servers.........................................7
2.4 Templates.................................................9
2.5 Template Transmission and Negotiation....................10
2.6 Changing Templates.......................................11
2.7 Flow Control.............................................12
2.8 The CRANE Client Query Messages..........................13
2.9 CRANE Sessions...........................................13
3 CRANE Message Format..........................................14
4 CRANE 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)................23
4.8 Final Template Data (FINAL TMPL DATA)....................25
4.9 Final Template Data Acknowledge (FINAL TMPL DATA ACK)....26
4.10 Get Sessions (GET SESS).................................26
4.11 Get Sessions Response (GET SESS RSP)....................27
4.12 Get Templates (GET TMPL)................................30
4.13 Get Templates Response(GET TMPL RSP)....................30
4.14 Start Negotiation (START NEGOTIATE).....................33
4.15 Start Negotiation Acknowledge (START NEGOTIATE ACK).....34
4.16 Data (DATA).............................................34
4.17 Data Acknowledge (DATA ACK).............................36
4.18 Error (ERROR)...........................................37
4.19 Status Request (STATUS REQ).............................38
4.20 Status Response (STATUS RSP)............................38
5 Protocol Version Negotiation..................................39
6 Security Considerations.......................................42
7 References....................................................43
8 Acknowledgments...............................................43
9 Authors' Addresses............................................44
10 Full Copyright Statement......................................451. Introduction 🧚
Okay so Network Elements are constantly being asked to send usage info to mediation and business support systems (BSS) so billing can happen 💸 There are already a bunch of ways to do this, but they're starting to struggle with what service providers actually need now.
Some of the old-school export methods are basically relics from the Telco world 🕰️ Usage info usually sits in Network Elements as Log files (like CDR files) and gets shipped to outside systems in batches. Honestly, these methods are reliable, but they don't keep up with the real-time, high-performance vibes that today's fast-moving data networks need 😭
Then there's RADIUS [1], which is super popular and can be used to export usage info. The issue is it can only juggle a few outstanding requests at once, and it isn't very extensible because its command and attribute address space is so limited 🙈 RADIUS also can't send unsolicited messages from a server to a client. If you want the full tea on RADIUS's limitations, check out [3] 🍓
DIAMETER [2] is the newer AAA protocol 🌟 It keeps the basic RADIUS model but fixes several of RADIUS's problems. The current DIAMETER protocol and its extensions focus on Internet and wireless network access, though, and their accounting support is closely tied to authentication and authorization events. DIAMETER is trying to solve a lot of problems in the AAA space, and in doing so it doesn't really deal with some key accounting issues like efficiency and performance 💀
There are also SNMP-based mechanisms, which usually eat up a ton of processing and bandwidth 🍽️
So after all that, it's pretty clear there's a critical need for an accounting protocol that's reliable, fast, efficient, and flexible 🔥 That's where XACCT's CRANE protocol comes in, designed to hit all of those requirements. It's giving main character energy ✨
This document defines the CRANE protocol, which enables efficient and reliable delivery of any data, mainly accounting data from Network Elements to any systems, like mediation systems and BSS/OSS. The protocol is built for the critical job of exporting high volumes of accounting data from NE's while making efficient use of network, storage, and processing resources 💜
This document specifies the architecture of the protocol and the message format. Every CRANE protocol implementation MUST support them 🫶
1.1. Specification of Requirements 📏
Here's the keyword deal: in this document, "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" are to be read as described in BCP 14 [5]. The keywords aren't case sensitive in this document, so they're all the same no matter how they're written 🎀
1.2. Terminology 📚
Let's get the vocabulary down, bestie 🦋
CRANE Protocol
CRANE stands for Common Reliable Accounting for Network Element. The CRANE Protocol may be referred to as CRANE, or just "the Protocol" in this document 💅 It's what runs at the interface(s) between a CRANE client and one or more CRANE servers, for the purpose of delivering accounting data.
Client or CRANE Client
A CRANE Client is the implementation on the data-producing side of the CRANE protocol 📤 It usually lives inside the network element's software, so it can collect accounting data and send it off to a mediation or billing system using the protocol defined here.
Server or CRANE Server
A CRANE Server is the implementation on the data-receiving side of the CRANE protocol 📥 It's usually part of a Business Support System (BSS), like billing, market analysis, or fraud detection, or it's a mediation system. A single CRANE client can be connected to more than one CRANE server to make the usage info export system more robust 🛡️
CRANE Session
A CRANE Session is a logical connection between a CRANE client and one or more CRANE servers, for delivering accounting data 🤝 Multiple sessions MAY be maintained at the same time in a CRANE client or a CRANE server, and Session IDs are how they're told apart 🧩
Server Priority
Each CRANE server gets a Priority value 👑 Accounting data always goes to the server the CRANE client sees as operating, with the highest Priority value (that's the primary server) within a CRANE Session.
Message
A Message is encoded using the rules the CRANE protocol specifies, and it's sent across the interface between a CRANE client and a CRANE server 💌 Every message has a common CRANE header, and it may also carry control or user data payload.
Data Record
A Data Record is a bundle of info the Network Element gathers for various reasons, like accounting 📦 Its structure is defined by a Template.
Template
A Template defines the structure of any kind of Data Record. It spells out the data type, meaning, and location of each field in the record 🗺️
Data Sequence Number (DSN)
This is an accounting Data Record level sequence number. It's attached to all data messages so delivery stays reliable and in sequence 🔢
2. Protocol Overview 🌸
CRANE is designed to deliver accounting data reliably, efficiently, and quickly ⚡ Accounting data is its own beast: records can be pretty big, so supporting fragmentation of large records is required. And since accounting data is worth a lot, quick detection of unresponsive CRANE servers is also required, to keep data loss from happening and add robustness 🫶
Think of CRANE as an application that rides on top of the 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. It's fast and agile, but it gives zero reliability and has no flow control mechanisms 🙈 So the CRANE protocol must not use UDP as its transport layer protocol, to avoid the risk of hurting the networks it runs over 🚫
TCP and SCTP [4] are the two transport layer protocols that meet CRANE's reliability requirement 💖 Either one of them MAY be used to transport CRANE messages. TCP covers some of the requirements but not all of them. For example, it's not great at quick detection of server failure, and TCP is stream oriented rather than record oriented 😭 That's why SCTP [4] is the preferred way to transmit CRANE messages 🦋
Part 1 of 9 done, bestie. Part 2 is coming next! 🌈
2.1 CRANE Architecture ✨
okay so CRANE is an application that runs on top of a reliable transport layer protocol 💅 and that transport layer is the one actually delivering CRANE messages between CRANE clients and CRANE servers 🚚. it MUST support these three things, no cap:
- Reliable, in-sequence message delivery. 💖
- Connection oriented. 🎀
- 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 also support:
- Authentication. 🔐
- Bundling of multiple messages into a single datagram. 🌸
possible transport layer protocols MAY be TCP or SCTP [4]. ngl TCP covers the minimal CRANE requirements, but it's missing some really desirable stuff that SCTP has, like:
- Session level authentication. 👑
- Message based data delivery (as opposed to stream based). ✨
- Fast connection failure detection. ⭐
reliable delivery of accounting data happens at BOTH the transport layer and the CRANE protocol layer 🫶. the transport layer acks help catch lost data packets and unresponsive servers quickly, while CRANE acks a message only after it's been processed and the accounting info is sitting in persistent storage 💜.
since CRANE is all about reliable accounting data, most of the traffic going from a CRANE client to a CRANE server is accounting data 🍓. there are bi-directional control message exchanges too, but they're only a small slice of the traffic, lowkey tiny 🙈.
here's the architecture diagram, it's giving layers 🧚:
+----------------+ +----------------+
| CRANE | | CRANE |+
| User | | User ||+
+----------------+ +----------------+||
| CRANE | ==========> | CRANE |+|
| Client | <---------- | Server ||+
+----------------+ +----------------+||
| Transport | | Transport |+|
| Layer | <---------> | Layer ||+
+----------------+ +----------------+||
| Lower | | Lower |+|
| Layers | <---------> | Layers ||+
+----------------+ +----------------+||
+----------------+|
+----------------+2.2. CRANE over TCP 🎀
TCP can totally be the transport layer for CRANE 🦋. CRANE running over TCP MUST follow these rules:
- The CRANE client MUST accept TCP connections over a specific TCP port.
- The CRANE server MUST connect to the CRANE client, and SHOULD be responsible for reestablishing a connection in case of a failure.
- CRANE messages are written as a stream of bytes into a TCP connection, the size of a CRANE message is specified by the Message Length field in the CRANE message header. 🌈
2.3. Alternate servers 🧚
okay this one is so good ✨. redundant CRANE server configurations MAY be used for better reliability and robustness 💖. CRANE supports delivering accounting data to alternate CRANE servers, which might be part of a mediation system or a BSS 🫶.
a CRANE session can have one or more CRANE servers 👑. the CRANE client is in charge of configuring the network addresses of every CRANE server in the session 💅. each CRANE server gets a Server Priority 💜. the Server Priority shows the CRANE client's preference for which server should get the accounting data 🍓. when picking priorities, think about stuff like geographical distance, communication cost, and CRANE server loading, etc. 🌸. several servers can share the same priority too 🙈. if they do, the CRANE client can randomly pick one of them as the primary server for delivering accounting data 🎲.
load balancing and other fancy features MAY be built in a multi-server setup ✨. configuring the CRANE client happens through the NE's configuration system, and that's outside the scope of this document 📋.
A CRANE client MUST deliver accounting data to its perceived operating CRANE server with the highest priority 👑. if that 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 the client's queue space runs out 😭. an alarm SHOULD be generated to tell the CRANE user about the queue overflow condition 🚨.
delivery SHOULD go back to the higher priority server once it's perceived to be operating again 🔥.
the CRANE protocol doesn't say how a CRANE client should redirect accounting data to other CRANE servers, and that's considered an implementation issue 🙃. BUT the protocol gives all the supporting mechanisms for a multiple-server environment (like the template negotiation process, configuration procedures, etc.) 💖. the transport layer (together with some other means) is responsible for watching server responsiveness and telling the CRANE protocol about any failures 👀. the client MAY choose to switch to an alternate server 🦋.
Implementation Note: The transition to an alternate CRANE server is an implementation issue and SHOULD occur under the following conditions: A) Transport layer notifies the CRANE client 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.
2.4. Templates 🌸
this section is literally the efficiency queen 👑. CRANE gets its efficiency by negotiating a set of Data Templates for a session BEFORE any actual accounting data gets sent 💅. a data template describes the structure of a DATA message payload, meaning the data type, the meaning, and where each field lives in the payload 🧩. once the servers agree on the session templates, they know how to process the DATA messages from a CRANE client 🫶. so the client only sends the actual accounting data without attaching any descriptors, and that cuts down the bytes sent over the links 🚀.
a template is an ordered list of keys 📋. a key is the spec for one field in the template 🔑. it specifies an accounting item that a network element MAY collect and export 📦. the spec MUST include the description and the data type of the accounting item 💜. (for example, 'Number of Sent Bytes' can be a key that's an unsigned integer 32 bits long 🍓). a CRANE client is typically the one that defines keys 🙌.
CRANE supports using several templates at the same time for different accounting records 🌈. keys inside a template can be enabled or disabled ✨. an enabled key means the outgoing data record WILL contain that data item 💖. a disabled key means the outgoing record will leave that data item out 🙈. the enable/disable thing cuts bandwidth needs even more, and it can also reduce processing in network elements because only the data items that are needed get produced 🧠.
in a CRANE session, all the CRANE servers AND the CRANE client MUST use the same set of templates and the same enable/disable status 👯. the templates' configuration and the connectivity to an end application MUST be the same on every server 🫶. before the CRANE client starts sending data according to the templates, it MUST publish the relevant templates to all CRANE servers in the session through user configuration 📣.
the complete set of templates in a CRANE client MUST carry a configuration ID that identifies that template set 🆔. every data record goes out with both the Template ID and the Configuration ID, so the right template can be referenced 🎯. when a server gets a record with an OLDER Configuration ID, it MAY handle that record gracefully by keeping some template history 📚. the transport layer SHOULD make sure a server never gets messages with future configuration IDs 🔮.
2.5 Template Transmission and Negotiation ✨
okay so like I mentioned earlier, all CRANE servers MUST use the same set of templates in a CRANE session 💅 but sometimes the servers don't match (templates count as different if different keys are enabled or disabled, bestie 🙈). When that happens, the client and the server run a negotiation 🤝 and end up agreeing on one set of templates that every CRANE server in the session accepts and uses 🎀
once a CRANE session is up and the server sends a START message saying it's ready to join the session 🚀 the client MUST send the set of templates it wants to use, by sending a TMPL DATA message to the server 📨 and the CRANE server MUST acknowledge that it got the set of templates 💖
templates are negotiable between a CRANE client and its CRANE servers 🦋 a CRANE server MAY propose changes to the templates it got from the client (like enabling some keys and disabling others) or it can just acknowledge the templates as they are. if a template or a key isn't recognised by the server (maybe it got added to the client after the server finished configuring, which happens 😭), the server MAY choose to disable each unknown key or unknown template so it doesn't waste traffic on them 🗑️ a template counts as disabled when all of its keys are disabled ✨ if the CRANE servers sent changes back, the client will send the changed template set to all connected servers (using a FINAL_TMPL_DATA message) 📣 it's the client's job to decide the final set of templates used by a session 👑 at this point each CRANE server MUST accept and acknowledge the templates WITHOUT changing anything, so nobody gets stuck in a deadlock or loop 🔁 and each CRANE server only gets one chance to propose changes during the negotiation 🫶
here's how the template negotiation goes, step by step:
- A) CRANE client sends a
TMPL DATAmessage with a set of templates. - B) CRANE server either responds with the
TMPL DATA ACKmessage with changes in the template set (the process continues in step C), or responds with aFINAL TMPL DATA ACKmessage if no changes are needed (the process continues in step E). - C) CRANE client receives the proposed changes, incorporates them if possible, and then sends a
FINAL TMPL DATAmessage containing the new set of templates to all servers (to deploy the change). - D) CRANE server receives the
FINAL TMPL DATAmessage containing the new set of templates and MUST send aFINAL TMPL DATA ACKmessage to acknowledge the reception of the templates. No changes are allowed at this stage, and the templates the client sent are going to be used. - E) CRANE client receives a
FINAL TMPL DATA ACKmessage from the server and can assume that the server knows which templates to use.
all of these stages only happen when there are multiple CRANE servers whose template sets are different (for example, not all key states match) 🧐 if every CRANE server in a session has exactly the same configuration, they'll all respond with FINAL TMPL DATA ACK and the ping-pong between the client and the servers ends right away ⚡ that's the common case! but if some CRANE servers have a different configuration, the protocol gives you a way to keep everyone consistent 🌈
Implementation Note:TMPL DATAmessages SHOULD be sent only after allDATAmessages with the previous configuration have been acknowledged. This makes sure the server transitions properly to the new configuration. 🧚
2.6 Changing Templates 🔧
even though TMPL DATA messages let you deploy and publicize templates, you still sometimes need to configure the template set 💅 each CRANE server in a CRANE session may change the template set, and this is usually requested by an end-user through a User Interface 🖥️ if end-users want to know which templates are available and what the current template set looks like, they may send a GET TMPL message 👀
to change the templates, these steps happen in order:
- A) The server MUST retrieve the template set that needs changing from the CRANE client by issuing a
GET TMPLmessage. The server can issue aGET TMPLeven if it hasn't sent a START message yet 🙌 - B) Once it gets a
GET TMPLmessage, the client sends back aGET TMPL RSPmessage with the requested data 📬 - C) The server makes the necessary changes to the templates and sends back a
START NEGOTIATIONmessage. This message triggers the CRANE client to ask about the changes the CRANE server made 🔍 - D) Once it gets a
START NEGOTIATEmessage, the client MUST respond with aSTART NEGOTIATE ACKmessage, followed by aTMPL DATAmessage. From this point on, the template negotiation process starts 🎬
2.7 Flow Control 🌊
after templates have been deployed, DATA messages start arriving 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's in-sequence, and out-of-sequence DATA messages should be discarded 🗑️
the CRANE server figures out where the accounting data starts when it gets the first DATA message, either after startup or after a server transition 🕵️ that first DATA message MUST have the 'S' bit (the 'DSN Synchronize' bit) set by the CRANE client. Once the server gets the message with the initial DSN, it MUST accept all in-sequence DATA messages. The DSN MUST be incremented by 1 for each new DATA message the client sends out 🔢
a CRANE server MUST acknowledge that it received and correctly processed DATA messages by sending DATA ACK messages ✅ the DATA ACK MUST contain the DSN of the last processed in-sequence DATA message. If the CRANE server gets an Out Of Sequence DATA message, it MUST also send a DATA ACK message, and that triggers an immediate retransmission of unacknowledged records 🚨
the CRANE client is responsible for delivering all the records 📦 in a redundant server setup, it can happen that one server doesn't get all the records but another redundant CRANE server for the same mediation system gets the rest. For example, server #1 could receive records 3042-3095 and then 3123-..., while server #2 receives records 3096-3122. It's the sender's responsibility to deliver all the records, in-sequence, but not necessarily to the same server 🫠
the billing/mediation system eventually gets all the records, possibly through more than one CRANE server 🧾 the CRANE client MUST pass along all the records it received to the billing/mediation system. This MAY result in duplicate records in the billing/mediation system. If that happens, the DSN MUST be used to remove duplicates 🧹 to help with duplicate removal, whenever a record gets re-sent to another server, its 'Duplicate' bit MUST be set to suggest that this record might be a duplicate 🏷️
Implementation Note: When the number of unacknowledged records reaches a threshold, a timer should be started. When the timer expires, all the unacknowledged records should be transmitted to an alternate server with the'D'bit set in theDATAmessage; if alternate servers aren't available, the records should be retransmitted. CRANE flow control also supports redundant server configurations. A server MUST send aSTARTmessage in order to move to the 'ready' state. In the 'ready' state, the server can receive and process CRANE messages. To leave the 'ready' state and stop the message flows from the client, the server should send aSTOPmessage to the client. 🛑
2.8 The CRANE Client Query Messages 🔎
a CRANE server may ask a CRANE client about its status by sending query messages once it has set up a session with that client 🕊️ a CRANE client that's connected to the server MUST respond with response messages. All the Query Messages MUST be started by a CRANE server 🙋♀️ the CRANE protocol defines three of these Query Message pairs:
- Get Session (
GET SESS) and Get Session Response (GET SESS RSP) - Get Template (
GET TMPL) and Get Template Response (GET TMPL RSP) - Status Request (
STATUS REQ) and Status Response (STATUS RSP)
all the query messages include a Request ID field, which is used for tagging and matching requests with responses 🏷️ this field holds a 16 bit counter that goes up with every request, and it's set by whoever starts the request. Together with the CRANE server's IP address and port number, it makes a unique identifier for each request 🆔 the same value MUST be copied into the Request ID field of the response message, so the response can be matched back to its request 💞
the CRANE client SHOULD collect and send out meta-data about the data it has collected (counters, statistics, and so on) 📊 this is done by creating status templates. They're treated like any other template, except they get marked with a /'Status' bit 🧩 status templates are used with the STATUS REQ and STATUS RSP messages. A server MAY send a STATUS REQ to a CRANE client and receive a STATUS RSP message with the requested data 💌
2.9 CRANE Sessions 🎀
a CRANE client MAY deliver accounting data to different mediation/billing systems by setting up different CRANE sessions 🌸
each session MAY consist of several CRANE servers in a redundant configuration. The session ID embedded in all the CRANE messages lets the right CRANE sessions get linked to the right CRANE users 🪪 all the CRANE processes (template negotiation, configuration, flow control, and so on) should be carried out in the same way in a multi-session scenario 🌈
each session has its own set of templates. These may be the same templates, but the keys could be enabled or disabled differently 🔑 the sessions are configured in the NE, each one with a different session name and an associated Session ID. The session ID is carried in each message so the message can be tied to a specific session 🧷
a CRANE server MAY take part in different sessions. When you configure a server, it needs to know which sessions it takes part in 🧠 the server can send a GET SESS message to get a list of the relevant sessions 📋
3. CRANE Message Format ✨
okay so this is the part where we look at how every CRANE message is actually built 🧩 A CRANE message is an 8 octet header, and then a variable length payload that is aligned to a 32 bit boundary. Some messages don't have a payload at all, so they skip that part 🙈 All the fields are in network byte order and go out 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(MID)| Session ID | Message Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ CRANE Message Payload ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Version: 8 bit unsigned integer
The Version field tells you which CRANE protocol implementation you're dealing with 🎀 This field MUST be set to 1 to mean CRANE protocol Version 1.0. Version 1.0 only supports Ipv4 addressing, but it can still be used to carry info about Ipv6 flows, which is kinda iconic ✨
Message ID (MID): 8 bit unsigned integer
This is the message's type, basically its personality 💅 The message IDs for CRANE Version 1 are:
Message Name Short Name Message ID
--------------------- --------------- ------------
Reserved 0x00
Flow Start START 0x01
Flow Start Acknowledge START ACK 0x02
Flow Stop STOP 0x03
Flow Stop Acknowledge STOP ACK 0x04
Connect CONNECT 0x05
Template Data TMPL DATA 0x10
Template Data Acknowledge TMPL DATA ACK 0x11
Final Template Data FINAL TMPL DATA 0x12
Final Template Data Ack. FINAL TMPL DATA ACK 0x13
Get Sessions GET SESS 0x14
Get Sessions Response GET SESS RSP 0x15
Get Template GET TMPL 0x16
Get Template Response GET TMPL RSP 0x17
Start Negotiation START NEGOTIATE 0x18
Start Negotiation Ack. START NEGOTIATE ACK 0x19
Data DATA 0x20
Data Acknowledge DATA ACK 0x21
Error ERROR 0x23
Status Request STATUS REQ 0x30
Status Response STATUS RSP 0x31Session ID: 8 bit unsigned char
The Session ID field says which session the message belongs to 🦋 The session ID gets ignored for GET SESS and GET SESS RSP messages. If you want the full tea on sessions, check out Section 2.9.
Message Flags: 8 bit unsigned char
The Message Flags field is where options for the message can go 🍓 For CRANE Version 1.0, all the flags are reserved. Unless it says otherwise, flags get set to zero when sent and get ignored when received, so no drama there 🌸
Message Length: 32 bit unsigned integer
This is the total length of the CRANE message in octets, and that includes the header 📏
4. CRANE Messages 💜
This section is all about the CRANE mandatory messages. Every CRANE protocol implementation MUST support them, no exceptions bestie 🫶
4.1 Flow Start (START)
Description
The Flow Start message goes from a CRANE server to a CRANE client to say "hey, I'm ready to receive CRANE 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | MID=0x01 | Session ID | Message Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+4.2 Flow Start Acknowledge (START ACK)
Description
The Flow Start Acknowledge message is how a CRANE client says "got it!" after receiving a START message from a specific CRANE server 💖 It only goes back to that one server, to show the client thinks it's ready to receive CRANE messages. Main character energy 👑
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | MID=0x02 | Session ID | Message Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Client Boot Time |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Client Boot Time: 32 bit unsigned integer
The Client Boot Time field is the timestamp of the client's last startup, counted in seconds from 1970 ⏰ You can combine it with the DSN and the client's IP address to get a system wide unique record identifier. Iconic for tracking 🔍
4.3 Flow Stop (STOP)
Description
The Flow Stop message goes from a CRANE server to a CRANE client to tell it to stop sending data to that server 🛑 It doesn't disconnect the server though. It only stops the client from sending "DATA" messages, so the connection stays alive, just quieter 🤫
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | MID=0x03 | Session ID | Message Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+4.4 Flow Stop Acknowledge (STOP ACK)
Description
The Flow Stop Acknowledgement message is the reply that acknowledges the STOP message from a CRANE 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | MID=0x04 | Session ID | Message Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+4.5 Connect (CONNECT)
Description
The CONNECT message goes from a CRANE server to a CRANE client so the server can identify itself 🪪 This one is the VIP: the message MUST be the first message sent over a transport layer connection between the server and the client. No cutting in line 🙅♀️
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | MID=0x05 | Session ID | Message Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Server Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Server Port | Reserved |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Server Address: 32 bit unsigned integer
The Server Address field is the server's IP address, IPv4 🌐
Server Port: 16 bit unsigned integer
The Server Port field is the server's port number for the transport layer 🔌 Heads up: this port number doesn't have to match the port number the transport layer actually uses 🫣
4.6 Template Data (TMPL DATA) 💖
Description
okay so, bestie, this is the moment the client hands over the whole template wardrobe 👗✨ 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 for the session. It SHOULD also include the template for the status records (See section 2.8) 🎀
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.5 🫶
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | MID=0x10 | Session ID | Message Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Config ID | Flags |E| Number of Templates |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ Template Block ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ ... ... ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ Template Block ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Configuration ID (Config. ID): 8 bit unsigned char
The Configuration ID field identifies the version number associated with a template set. Changes 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 the version number 🔄
Flags: 8 bit unsigned char
The Flags field identifies any options associated to the message.
The flag defined by the CRANE Version 1 is:
The 'E' bit indicates the transmission order of the "DATA" messages. If the field is set to 1, data is in big endian format; otherwise, little endian format is used. 🧠
Number of Templates: 16 bit unsigned integer
The Number of Templates field is the number of Templates (a template is described by a Template Block) specified by the message. 📦
Template Block
The Template Block field is of variable length and aligned to 32 bit boundary. It is the specification of a template. 🎨
Template Block 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Template ID | Number of Keys |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Template Flags |T| Description Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Template Block Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ Description ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ Key Block ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ ... ... ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ Key Block ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Template ID: 16 bit unsigned integer
The Template ID field identifies a specific template. 🪪
Number of Keys: 16 bit unsigned integer
The Number of Keys field is the number of keys included in the template. 🔑
Template Flags: 16 bit unsigned integer
The Template Flags field is composed of flags that indicate different attributes of the template. In CRANE Version 1.0, only the 'T' bit is defined, other bits in the field SHOULD be set to zero by the sender and ignored by the receiver.
The 'T' bit ('Status' bit) indicates that the template is a status template that is used by the STATUS RSP message only. See section 2.8 for more details. 🚩
Description Length: 16 bit unsigned integer
The Description Length field is the length of the Description field. If no description is supplied, the length MUST be 0. 📏
Template Block Length: 32 bit unsigned integer
The Template Block Length is the length of the template block in octets. 🧮
Description: Variable length unsigned char
The Description field contains the text description of the template (e.g., "Aggregated by interface and ToS bits"). It is a variable length field of up to 64Kb long, and padded with 0 to the next 32 bit boundary. 📝
Key Block
A key Block contains the specification of a key within a template. 🗝️
Key Block 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Key ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Key Type ID | Reserved |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Key Attribute Vector |K|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Key ID: 32 bit unsigned integer
The Key ID field identifies the key within a template. See section 2.4 for more details. 🆔
Key Type ID: 16 bit unsigned integer
The Key Type ID field specifies the data type of the key. 🍬
The fixed length data types 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
IP address (Ipv4) 0x0010
IP address (Ipv6) 0x0011
Time_SEC (3) 0x0012
Time_MSEC_64(4) 0x0013
Time_USEC_64 (5) 0x0014
Time_MSEC_32 (6) 0x0015
Time_USEC_32 (7) 0x0016The variable length data types are defined as following:
String (8) 0x400c
Null Terminated String 0x400d
UTF-8 String 0x400e
UTF-16 String 0x400f
Arbitrary Data (BLOB) (9) 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 that comply with the IEEE-754 standard.
(3) Time_SEC is a 32 bit value, most significant octet first - seconds since 00:00:00 GMT, January 1, 1970.
(4) Time_MSEC_64 is a 64 bit value, most significant octet first - milliseconds since 00:00:00 GMT, January 1, 1970.
(5) Time_USEC_64 is a 64 bit value, most significant octet first - microseconds since 00:00:00 GMT, January 1, 1970.
(6) Time_MSEC_32 is a 32 bit value, most significant octet first - milliseconds since 00:00:00 GMT, January 1, 1970.
(7) Time_USEC_32 is a 32 bit value, most significant octet first - microseconds since 00:00:00 GMT, January 1, 1970.
(8) String is prefixed by a 32 bit length field that indicates the length of the string, and followed by ASCII codes of the string characters. This representation MUST only be used for encoding data records in a "DATA" message.
(9) 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 integer
The Key Attribute Vector field indicates different attributes of the key. In CRANE Version 1, only the 'K' bit is defined, other bits in the field SHOULD be set to zero by the sender and ignored by the receiver. 🧩
The 'K' bit ('Disabled bit') is set to 1 when the key is disabled in this template. 🚫
4.7 Template Data Acknowledge (TMPL DATA ACK) ✨
Description
okay so the Template Data Acknowledge message is what a CRANE server sends back to a CRANE client after it gets a TMPL DATA message 💅. It proposes changes to the templates and/or key status changes (enable/disable) for those templates 🔥.
If a CRANE server wants to acknowledge a TMPL DATA message without any changes, it MUST respond with the FINAL TMPL DATA ACK 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | MID=0x11 | Session ID | Message Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Config. ID | Reserved | Number of Template Changes |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ Template Change Block ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ ... ... ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ Template Change Block ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Configuration ID (Config. ID): 8 bit unsigned char
See Section 4.6 🎀. The value MUST be identical to the Config. ID field of the acknowledged TMPL DATA message 💖.
Number of Template Changes: 16 bit unsigned integer
The Number of Template Changes field is the number of changed Templates (a changed template is described by a Template Change Block) specified by 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 ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ ... ... ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ Key Block ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Template ID: 16 bit unsigned integer
See Section 4.6 🧚.
Number of Keys: 16 bit unsigned integer
See Section 4.6 🍓.
Key Block
See Section 4.6, only relevant keys are described 🔍.
4.8 Final Template Data (FINAL TMPL DATA) 💜
Description
The Final Template Data message is sent by a CRANE client to all the CRANE servers in a session, to convey the finalized templates ✨. It's basically the same as the TMPL DATA message, with one big difference: a server must accept the templates in this message 👑.
Message Format
Identical to the TMPL DATA (see section 4.6) 🎀.
Message ID (MID)
0x12 Final Template Data4.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 message 💅. It does not carry any changes to the templates 🙈. Unlike TMPL DATA ACK messages, a FINAL TMPL DATA ACK message indicates the acceptance of the templates for the session ✨.
A server MAY respond with this message to a TMPL DATA (if it does not want any changes in the templates) 🌈. A server MUST respond with this message to a FINAL TMPL DATA 🔥.
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | MID=0x13 | Session ID | Message Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Config. ID | Reserved |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Configuration ID: 8 bit unsigned char
See Section 4.6 🌸. This field MUST copy the configuration ID from the acknowledged message 💖.
4.10 Get Sessions (GET SESS) 🧚
Description
The Get Sessions message is sent by a CRANE server to a CRANE client to query what are the sessions it should participate in 🔍. 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 the server's participation of all the sessions 🫶.
The Session ID field in the CRANE message header MUST be ignored by the receiver 🙈.
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | MID=0x14 | Session ID | Message Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Request ID | Reserved |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Request ID: 16 bit unsigned integer
The Request ID field identifies the specific request issued by the server 🦋. The same Request ID MUST be placed in the responding message in order to associate it with the request 💜.
4.11 Get Sessions Response (GET SESS RSP) 👑
Description
The Get Sessions Response message is sent by a CRANE client to a CRANE server as a reply to a GET SESS request 💅. The message MUST contain all the information related to any session with which the requesting server is associated ✨.
The Session ID field in the common message header MUST be ignored by the receiver 🙈.
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
--+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | MID=0x15 | Session ID | Message Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Request ID | Number of Sessions |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Vendor String Length | Reserved |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-|
| |
~ Vendor String ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ Session Block ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ ... ... ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ Session Block ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Request ID: 16 bit unsigned integer
See Section 4.10 🎀.
Number of Sessions: 16 bit unsigned integer
The Number of Sessions field is the number of session blocks in the message 🌸.
Vendor String Length: 16 bit unsigned integer
The Vendor String Length field is the length of Vendor String field in octet 🔥. 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
The Vendor String field is a variable length field 🌈. It identifies the vendor that created the session ✨. It MUST be padded with 0 to the next 32 bit boundary 🫶. The information differentiates similar templates from different vendors 🦋. The actual format of the information is application specific and outside the scope of this document 🧚.
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
See Section 3 🍓.
Session Name Length: 16 bit unsigned integer
The Session Name Length field is the length of the Session Name field 💖. The field limits the session name strings to 64 Kb long 🌸. As a name is mandatory to differentiate between sessions, this field MUST NOT be 0 🔥.
Session Description Length: 16 bit unsigned integer
okay so the Session Description Length field is the length of the session description 💅 and it caps that description at 64Kb, which is plenty of room 🎀. If no description is supplied, the length MUST be set to 0 ✨.
Session Name: Variable length unsigned char
The Session Name is the name for a session, and it MAY be displayed to end-users 🦋. It MUST be padded with 0 to the next 32 bit boundary 🌸. 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 Session Description is the text description of a session, and it could be displayed to end-users ✨. It MUST be padded with 0 to the next 32 bit boundary 🫶.
4.12. Get Templates (GET TMPL)
Description
The Get Templates message is sent by a CRANE server to a CRANE client to query templates in a 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | MID=0x16 | Session ID | Message Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Request ID | Reserved |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Request ID: 16 bit unsigned integer
See Section 4.10.
4.13. Get Templates Response (GET TMPL RSP)
Description
The Get Templates Response 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | MID=0x17 | Session ID | Message Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Request ID | Number of Templates |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ Template Block ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ ... ... ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ Template Block ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Request ID: 16 bit unsigned integer
See Section 4.10.
Number of Templates: 16 bit unsigned integer
See Section 4.6.
Template Block
Same as the template block defined in the TMPL DATA message (see Section 4.6) 🎀. However, Extended Key Blocks MUST be used instead of Key Blocks 🔥. Extended key Block field provides extensive informational data that MAY be displayed to end-users 💅.
Extended Key Block
The Extended Key Block field provides comprehensive information about a key 📚.
Extended Key Block 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Key ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Key Type ID | Key Name Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Key Label Length | Key Help Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ Key Name ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ Key Label ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ Key Help ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Key Attribute Vector |K|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Key ID: 32 bit unsigned integer
Same as section 4.6.
Key Type ID: 16 bit unsigned integer
Same as section 4.6.
Key Name Length: 16 bit unsigned integer
The Key Name Length field is the length of the Key Name field 📏. The field limits Key Name strings to 64 Kb long. As a name is mandatory to a key, this field MUST NOT be 0 🙈.
Key Label Length: 16 bit unsigned integer
The Key Label Length field is the length of the Key Label field 🏷️. The field limits Key Label strings to 64 Kb long. Length of 0 means that the Label field is to be skipped.
Key Help Length: 16 bit unsigned integer
The Key Help Length field is the length of the Key Help field 🆘. The field limits Key Help strings to 64 Kb long. Length of 0 means that the Help field is to be skipped.
Key Name: Variable length unsigned char
The Key Name field is the name for the key, which could be displayed to end users 🔑. It MUST be padded with 0 to the next 32 bit boundary. Key Name MUST be unique (within the template) and case sensitive 🧐. This field is mandatory and MUST be a part of any Extended Key Block ✨.
Key Label: Variable length unsigned char
The Key Label field is a descriptive label, which could be displayed to end users concerning this key 💬. It MUST be padded with 0 to the next 32 bit boundary. This field SHOULD be a part of any Extended Key Block 💖.
Key Help: Variable length unsigned char
The Key Help field is any Help string that could be displayed to end users concerning this key 🌸. It MUST be padded with 0 to the next 32 bit boundary. This field MAY be a part of any Extended Key Block 🦋.
Key Attribute Vector: 32 bit unsigned integer
Same as section 4.6.
4.14. Start Negotiation (START NEGOTIATE)
Description
The Start Negotiation 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 MAY re-send this message up to 3 times with repeat interval of 5 seconds unless it is acknowledged by the CRANE client ⏰. Otherwise, the CRANE user will be informed 🚨. The client should send TMPL DATA message to the servers after acknowledged the 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | MID=0x18 | Session ID | Message Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+4.15. Start Negotiation Acknowledge (START NEGOTIATE ACK)
Description
The Start Negotiation Acknowledge 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | MID=0x19 | Session ID | Message Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+4.16. Data (DATA)
Description
The DATA message carries actual data records from a CRANE client to a CRANE server 📦. A data record is a structured collection of fields that matches a specific template 🧩.
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | MID=0x20 | Session ID | Message Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Template ID | Config. ID | Flags |D|S|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Data Sequence Number (DSN) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ Record Data ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Template ID: 16 bit unsigned integer
See Section 4.6.
Configuration ID: 8 bit unsigned char
See Section 4.6. The Config. ID field can 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 📜.
Flags: 8 bit unsigned char
The Flags field is composed of flag bits that indicate processing requirements of the data records 🚩. The CRANE Version 1 defined two flags for these purposes. Unless otherwise specified, the other flags are set to zero on transmit and are ignored on receipt 🫧.
The following flags are defined in CRANE Version 1:
- The 'D' bit ('Duplicate' bit): It is set for records that are re-sent to an alternate server after a server transition occurs 🔁. When the same records are sent to different servers, there is a possibility that duplicated data exists. The Status of the 'D' bit will help the billing/mediation system to perform de-duplication if desired 🧾.
The S bit ('DSN Synchronize' bit) 👑 tells you the record is the first one the server gets after data transmission starts (or restarts) to that server. When it's set, the server MUST set the initial DSN to the DSN in that record 🫶. The flag is set to zero by default ✨.
Data Sequence Number: 32 bit unsigned integer 🦋
This is the record sequence number that keeps data in order and helps catch data losses. The DSN MUST be incremented by one for each new record transmitted 💅. Picking the initial DSN number is implementation specific 🙈.
Record Data: Variable Length unsigned octets 🎀
This field carries the actual accounting/billing data, structured according to the template named in the Template ID field 💜.
4.17 Data Acknowledge (DATA ACK) 💌
Description
The Data Acknowledgement message is how a CRANE server says "got it" to 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | MID=0x21 | Session ID | Message Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Data Sequence Number |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Config. ID | Reserved |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Data Sequence Number: 32 bit unsigned integer 🔥
See Section 4.16. It MUST be DSN of the last in-sequence record that was received by the server.
Configuration ID: 8 bit unsigned char
See Section 4.16.
4.18 Error (ERROR) 🚨
Description
The Error message MAY be issued by either a CRANE server or client 🙋♀️. It indicates an error condition that was detected by the sender.
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | MID=0x23 | Session ID | Message Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Timestamp |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Error Code | Description Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ Description ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Timestamp: 32 bit unsigned integer ⏰
The Timestamp field is a timestamp in seconds since 00:00:00 GMT, January 1, 1970.
Error Code: 16 bit unsigned integer 🙈
The Error Code field is a code assigned to an error condition.
The following error codes are defined in CRANE Version 1:
Error Condition Error Code
----------- --------------
Unknown 0Description Length: 16 bit unsigned integer
The Description Length field is the length of the Description field. The field limits Description strings to 64 Kb long. Length of 0 means that the Description field is to be skipped.
Description: Variable Length unsigned char 📝
The Description field is a text description that allows the sender to provide more detailed information about the error condition. It MUST be padded with 0 to the next 32 bit boundary.
4.19 Status Request (STATUS REQ) 📊
Description
CRANE servers MAY inquire general operation status of a client by sending the Status Request message 🔍. The status information SHOULD include a collection of states, counters, accumulators of the data collection functions that reside with the client. The status MAY include more information about the CRANE client itself.
The status reporting mechanism relies on the status template of a session. It is determined similarly as other templates. Without a determined status template, 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | MID=0x30 | Session ID | Message Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+4.20 Status Response (STATUS RSP) 🌈
Description
The Status Response message contains a status report that MUST be compatible with the status template of the session 💖. It is client's response to a STATUS REQ message from a 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | MID=0x31 | Session ID | Message Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Template ID | Reserved |Config. ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Record Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ Record Data ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Template ID: 16 bit unsigned integer
See Section 4.6.
Configuration ID: 8 bit unsigned integer
See Section 4.6. 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 integer
The Record Length field is the length of the Record Data field in octets.
Record Data: Variable Length unsigned octets 🍓
The Record Data field contains the status data that complies with the status template. For more details see section 2.4.
5. Protocol Version Negotiation ✨
okay so CRANE might glow up someday and run over different transport layers 🦋, which means it needs a transport-neutral way to figure out which version everyone speaks. That's the version negotiation mechanism, and it runs over UDP. A CRANE server MAY ask a CRANE client what protocol version and transport layer support it has, by sending a UDP packet on an agreed UDP port. The client MUST respond with a UDP packet that carries the protocol version, the transport type, and the port number used for that specific transport 💅. Protocol Version Negotiation is optional for CRANE Version 1 🌸.
The CRANE server sends this message to ask about the client's protocol support:
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Server Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Server Boot Time |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 'C' | 'R' | 'A' | 'N' |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Server Address:
The Server Address field is the IP address (Ipv4) of the CRANE server 🧚.
Server Boot Time
The Server Boot Time field is the timestamp of the last server startup in seconds from 1970 ⏰.
'C', 'R', 'A', 'N':
The 'C', 'R', 'A', 'N' fields are ASCII encoded characters that identify the CRANE server 🔤.
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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| ... Additional Protocols Info ... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Additional Protocols Info |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Default Protocol Info:
The Default Protocol Info field holds information about the default protocol the client supports. The field is structured as a Protocol Info Block, described below 📦.
Additional Protocols Count: 32 bit unsigned integer
The Additional Protocols Count field says how many additional protocols the client supports. If only the default protocol is supported, the field MUST be set to 0 🙈.
Additional Protocols Info:
The Additional Protocol Info field is an array of Protocol Info Blocks (described below) that contain information about the additional protocols the client supports 🌈.
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 integer
1 means TCP and 2 means SCTP 🚛.
Protocol Version: 32 bit unsigned integer
This is the version number of the CRANE protocol supported over the specific transport layer. The current version is 1 🔥.
Port Number: 16 bit unsigned integer
This is the port number (either an SCTP or a TCP port) used for the protocol 🔌.
6. Security Considerations 🔐💀
okay bestie, this is the serious part, so read it closely 🙈. CRANE can be viewed as an application running over a reliable transport layer, like TCP or SCTP 💜. It's end-to-end, meaning CRANE messages go between clients and servers that are identified by host address and transport protocol port number. Before any CRANE sessions can start, a set of CRANE servers' addresses should be provisioned on a CRANE client 📝. A CRANE server keeps a list of the addresses of the CRANE clients it talks to too. Provisioning is typically done securely through a network management system, and that's how the CRANE end-points can be authenticated and authorized 🛡️. But this scheme is static, so without additional security protections, CRANE is vulnerable to attacks like address spoofing 😱.
The CRANE protocol doesn't offer strong security facilities by itself, so it cannot ensure confidentiality and integrity of CRANE messages 🚨. It is strongly recommended that people using CRANE evaluate their deployment configurations and put appropriate security policies in place 🔥. For example, if CRANE is deployed over a local area network or a dedicated connection that ensures security, no additional security services or procedures may be required. However, if CRANE clients and servers are connected through the Internet, lower layer security services should be invoked 🌐.
To get strong protection for communications between CRANE clients and servers, lower layer security services are strongly recommended 🫶. These lower layer security services are transparent to the CRANE protocols. Security mechanisms may be provided at the IP layer using IPSEC [6], or they may be implemented at the transport layer using TLS [7]. Provisioning of the lower layer security services is out of the scope of this document ✨.
7. References 📚
[1] Rigney, C., Willens, S., Rubens, A. and W. Simpson, "Remote Authentication Dial In User Service (RADIUS)", RFC 2865, June 2000.
[2] Calhoun, P., "DIAMETER Base Protocol", Work in Progress.
[3] Calhoun, P., et. al., "DIAMETER Framework Document", Work in Progress.
[4] Stewart, R., Xie, Q., Morneault, K., Sharp, C., Schwarzbauer, H., Taylor, T., Rytina, I., Kalla, M., Zhang, L. and V. Paxson, "Simple Control Transmission Protocol", RFC 2960, October 2000.
[5] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[6] Kent, S. and R. Atkinson, "Security Architecture for the Internet Protocol", RFC 2401, November 1998.
[7] Dierks, T. and C. Allen, "The TLS Protocol, Version 1.0", RFC 2246, January 1999.
8. Acknowledgments 🫶
Special thanks are due to Tal Givoly and Limor Schweitzer for conceiving the work 💡. Thanks also go to Nir Pedhatzur, Batya Ferder, and Peter Ludemann from XACCT Technologies for accomplishing the first CRANE protocol implementation 👑.
Thanks are also due to Nevil Brownlee for his valuable comments on the work, as well as the IETF IPFIX WG 💖.
9. Authors' Addresses 🦋
Kevin Zhang
10124 Treble Court
Rockville, MD 20850
U.S.A.
Phone +1 301 315 0033
EMail: kevinzhang@ieee.org
Eitan Elkin
XACCT Technologies, Ltd.
www.xacct.com
12 Hachilazon St.
Ramat-Gan, Israel 52522
Phone +1 972 3 576 4111
EMail: eitan@xacct.com10. Full Copyright Statement ⚖️
okay this part is legal stuff, so I'm keeping the exact wording so nothing gets lost 🙈 Copyright statement, verbatim:
Copyright (C) The Internet Society (2002). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE 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.Acknowledgement 💜
Funding for the RFC Editor function is currently provided by the Internet Society 🌸✨
📦 where this page comes from
- ietf: rfc3423 2002-11
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms