RFC 2890

Key and Sequence Number Extensions to GRE 💖

Okay bestie, this one is RFC 2890 🎀 It was written by Gopal Dommety (G. Dommety) at Cisco Systems and dated September 2000. It's a Standards Track document, so it's an actual spec for the Network Working Group, not just an idea doc. The title block doesn't list anything it obsoletes or updates ✨

Status of this Memo

So this doc specifies an Internet standards track protocol for the Internet community, and it's asking for discussion and suggestions for improvements 🦋 If you want the current standardization state and status of this protocol, check the "Internet Official Protocol Standards" (STD 1) 📜 Distribution of this memo is unlimited, so share away 💅

Copyright Notice

Copyright (C) The Internet Society (2000). All Rights Reserved. 🌈

Abstract

GRE (Generic Routing Encapsulation) is a protocol for encapsulating an arbitrary protocol over another arbitrary network layer protocol 🧚 This document adds extensions where two fields, Key and Sequence Number, can optionally be carried in the GRE Header [1]. ✨

1. Introduction 🎀

The current GRE spec [1] is the one that lets you encapsulate an arbitrary protocol over another arbitrary network layer protocol 💖 This document is the glow-up. It adds two fields, Key and Sequence Number, that can optionally ride along in the GRE Header [1] 💅

The Key field is for identifying an individual traffic flow inside a tunnel. The Sequence Number field keeps packets in order within the GRE Tunnel. Iconic behavior, honestly 😭

1.1. Specification Language

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [3]. These are the official requirement words, so they get to keep their capitals 🔥

Beyond those, this doc uses one more term to spell out how strict a requirement is:

Silently discard : Okay so this means the implementation drops the datagram without any further processing, and it doesn't tell the sender there was an error 🙈 The implementation SHOULD provide the capability of logging the error, including the contents of the discarded datagram, and SHOULD record the event in a statistics counter 📊

2. Extensions to GRE Header 🦋

The GRE packet header[1] looks like this right now:

 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|C|       Reserved0       | Ver |         Protocol Type         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|      Checksum (optional)      |       Reserved1 (Optional)    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

The proposed GRE header is the main character glow-up, and it looks like this 💖

 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|C| |K|S| Reserved0       | Ver |         Protocol Type         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|      Checksum (optional)      |       Reserved1 (Optional)    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                         Key (optional)                        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                 Sequence Number (Optional)                    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Key Present (bit 2)

If the Key Present bit is set to 1, the Key field is present in the GRE header 🔑 If it isn't set, the Key field isn't in the GRE header at all.

Sequence Number Present (bit 3)

If the Sequence Number Present bit is set to 1, the Sequence Number field is present 🔢 If it isn't set, the Sequence Number field isn't in the GRE header.

The Key and Sequence Present bits were picked to be compatible with RFC 1701 [2], so the vibes stay consistent 🫶

2.1. Key Field (4 octets)

The Key field is a four octet number that the encapsulator inserts 🔑 How the encapsulator gets this Key is out of scope for this document, so that's a different story 🙈 The Key is for identifying an individual traffic flow within a tunnel. For example, packets might need to be routed based on context info that isn't in the encapsulated data. The Key field carries that context and defines a logical traffic flow between the encapsulator and the decapsulator 🌸 Packets in the same traffic flow all get the same Key value, and the decapsulating tunnel endpoint figures out which flow a packet belongs to by looking at the Key Field value 👑

2.2. Sequence Number (4 octets)

The Sequence Number field is a four byte field, and the encapsulator inserts it when the Sequence Number Present bit is set 🔢 The receiver MUST use it to figure out the order packets were sent from the encapsulator 😭 The point of the Sequence field is to give you unreliable but in-order delivery. If the Key Present bit (bit 2) is set, the sequence number is specific to the traffic flow identified by the Key field 🎀 Also, packets without the sequence bit set can be mixed in with packets that have it set 🦋

Here's the number math, bestie 🧮 The sequence number goes from 0 to (232)-1. The very first datagram gets sequence number 0. It's a free running counter, so it wraps around modulo 232 💫 The receiver keeps track of the sequence number of the last packet it successfully decapsulated. When the GRE tunnel gets set up, that value should be set to (2**32)-1 ✨

If the decapsulator gets an out-of-sequence packet, it SHOULD be silently discarded 🙈 A packet counts as out-of-sequence if its sequence number is less than or equal to the sequence number of the last successfully decapsulated packet. A received sequence number also counts as less than or equal to the last successfully received one if it falls in the range from that last number and the 2**31-1 values before it, inclusive 🧠

If the received packet is in-sequence, it gets successfully decapsulated 💅 An in-sequence packet is one whose sequence number is exactly 1 greater than the last successfully decapsulated packet (modulo 2**32). It also counts as in-sequence if the sequence number field isn't present at all, meaning the S bit isn't set 🫶

If the packet is neither in-sequence nor out-of-sequence, that means there's a sequence number gap 🕳️ The receiver is allowed to do a small amount of buffering to try to recover the original order of the transmitted packets 🧺 In that case the packet can go into a buffer sorted by sequence number. When an in-sequence packet arrives and gets decapsulated, the receiver should check the head of the buffer to see whether the next in-sequence packet has already shown up. If it has, the receiver should decapsulate it, along with any following in-sequence packets that are also in the buffer 🏃‍♀️ The "last successfully decapsulated sequence number" then gets set to the last packet that came out of the buffer 💖

No matter what, a packet should not wait in the buffer for more than OUTOFORDER_TIMER milliseconds 😭 If a packet has been waiting that long, the receiver MUST immediately go through the buffer in sorted order, decapsulating packets (and ignoring any sequence number gaps) until no packet left in the buffer has been waiting longer than OUTOFORDER_TIMER milliseconds 🚨 The "last successfully decapsulated sequence number" then gets set to the last packet decapsulated this way ⏱️

The receiver can also cap how many packets live in any per-flow buffer. Packets with the same Key Field value belong to the same flow 🌊 If a new packet would push a buffer past MAX_PERFLOW_BUFFER packets, the packet at the head of that buffer gets decapsulated right away, no matter its sequence number 🙅‍♀️ The "last successfully decapsulated sequence number" is then set to that packet's sequence number, and the newly arrived packet can go into the buffer 🎀

Real talk: the sequence number is how you detect lost packets and/or restore the original order of packets that got reordered in transport (with buffering) 🕵️‍♀️ You gotta use the sequence number option thoughtfully. In particular, it's a good idea to avoid using it when tunneling protocols that already have higher layer in-order delivery mechanisms, or that can handle out-of-order delivery 🙈 If the protocol carried in the GRE tunnel only needs in-sequence delivery at certain moments, then only the corresponding packets encapsulated in a GRE header can have the sequence bit set 💜

The decapsulator MAY reorder out-of-sequence packets for better performance and tolerance to reordering in the network 🚀 A small reordering buffer (MAX_PERFLOW_BUFFER) can really help when the higher layer uses stateful compression or encryption 🔐 Stateful compression or encryption gets reset by packet loss, so tolerating a little reordering in the network through buffering can help performance 🌈

✨ Part 1 of 2. Section 3 (Security Considerations) and everything after it is coming in the next part 🎀

Full Copyright Statement 💖

Okay bestie, the legal bit! 📜 Copyright (C) The Internet Society (2000). All Rights Reserved. ✨

So here's the deal: this document and its translations can be copied and handed out to other people. You can also make derivative works that comment on or explain it, or that help people implement it. Those can be prepared, copied, published and distributed, in whole or in part, with no restrictions of any kind, as long as the above copyright notice and this paragraph are on every copy and every derivative work. 🦋

BUT (and this is a big but 🙈) the document itself can't be changed in any way. You can't remove the copyright notice or the references to the Internet Society or other Internet organizations. The only exceptions are when you need it for developing Internet standards, in which case you have to follow the copyright procedures in the Internet Standards process, or when you're translating it into a language other than English. 🌸

The permissions above are perpetual, which means forever. The Internet Society, its successors or assigns will not revoke them. 💜

Now the disclaimer, which is kind of serious 😭. This document and the info in it 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. No promises, no cap, just vibes. 💀

---

Acknowledgement 🫶

Funding for the RFC Editor function is currently provided by the Internet Society. Shoutout to them for keeping the lights on, periodt! 🌈