GRE - Generic Routing Encapsulation¶

pcapkit.protocols.link.gre contains GRE only, which implements the extractor for the Generic Routing Encapsulation base header [*] plus the optional Key and Sequence Number extensions [†], as reached through IP protocol number 47 behind any layer sharing Internet.__proto__, IPv4 and IPv6 among them, or as seen on a LINKTYPE_LINUX_SLL/LINKTYPE_LINUX_SLL2 capture whose arphrd_type is ARPHRD_IPGRE or ARPHRD_IP6GRE – ARPHRD_IPGRE and ARPHRD_IP6GRE both land on this one class, the “IP”/”IP6” distinction being only which outer IP version the tunnel carries. Its structure, with every optional field present, is described as below:

Octets	Bits	Name	Description
0	0	`gre.checksum_present`	Checksum Present (`C`)
0	2	`gre.key_present`	Key Present (`K`), RFC 2890
0	3	`gre.sequence_present`	Sequence Number Present (`S`), RFC 2890
0	13	`gre.version`	Version Number (`0`)
2	16	`gre.protocol_type`	Protocol Type (EtherType)
4	32	`gre.checksum`	Checksum, present only if `C`
6	48	`gre.reserved1`	Reserved1, present only if `C`
8/4	64	`gre.key`	Key, present only if `K`, RFC 2890
12/8/4	96	`gre.sequence_number`	Sequence Number, present only if `S`, RFC 2890

C, K and S each gate their own field independently, so the header is 4, 8, 12 or 16 octets depending on which are set. The Protocol Type field is an EtherType, dispatched onward through Link.__proto__, the same family registry Ethernet, VLAN and LinuxSLL already share – unlike FRAD, this class keeps no registry of its own. A nonzero Version Number (RFC 2637’s “Enhanced GRE”/PPTP, version 1) is a different, incompatible protocol and is refused rather than misread; see the module docstring’s Scope section.

Flow tracing and TCP reassembly follow the tunnel’s inner flow, keyed by the IP header nearest the TCP segment as for any tunnel (#1581), and IPv4 reassembly of an outer datagram fragmented in transit yields a parsed GRE layer.

class pcapkit.protocols.link.gre.GRE(file=None, length=None, **kwargs)[source]¶

Bases: Link[GRE, GRE]

This class implements Generic Routing Encapsulation (GRE).

The Protocol Type field is dispatched as an EtherType through Link.__proto__, exactly as VLAN resolves its own type field – so, unlike FRAD, this class declares no registry of its own.

The checksum, present when C is set, is verified on read under CHECKSUM_VERIFY, and computed by make() when checksum_present asks for one without giving it. Neither this header nor the Linux cooked-capture header before it states a length, so the message runs to the end of its frame. A frame the capture cut short, holding fewer octets than its original length, reads as TRUNCATED, as frame_length tells it (#2653), and so does a header the data ends inside (#2689). The header records such a cut, so the message rebuilt on its own reads as cut too (#2711).

property name: Literal['Generic Routing Encapsulation']¶: Name of current protocol.

property alias: Literal['GRE']¶: Acronym of corresponding protocol.

property length: int¶: Header length of current protocol.

property protocol: EtherType¶: Name of next layer protocol.

classmethod id()[source]¶

Index ID of the protocol.

Return type:: tuple[Literal['GRE']]

read(length=None, **kwargs)[source]¶

Read Generic Routing Encapsulation (GRE) frame.

Structure of a GRE frame, with every optional field present; see the module docstring for the full diagram:

 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|C| |K|S| Reserved0       | Ver |         Protocol Type         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Parameters:

length (int | None) – Length of packet data.
**kwargs (Any) – Arbitrary keyword arguments.

Return type:

GRE

Returns:

Parsed packet data.

Raises:

ProtocolError – If the Version Number is not 0 – see the module docstring’s Scope section.

make(checksum=None, reserved1=None, checksum_present=None, key=None, sequence_number=None, reserved=0, version=0, protocol_type=EtherType.Internet_Protocol_version_4, payload=b'', **kwargs)[source]¶

Make (construct) packet data.

The presence of each optional field is inferred from whether its value is given, as L2TPv2.make infers S from whether ns/nr are given: passing checksum sets C, key sets K, and sequence_number sets S. C can be set without a checksum too, through checksum_present, as L2TPv2’s length_flag sets L without a length.

Parameters:

checksum (int | None) – Checksum; setting this also sets C. If None with C set, computed over the header and payload (RFC 2784 Section 2.5) when CHECKSUM_COMPUTE is on, zero when it is off.
reserved1 (int | None) – Reserved1; only meaningful, and only accepted, when C is set. Defaults to 0 when C is set and this is not.
checksum_present (bool | None) – Whether C is set, and the Checksum and Reserved1 fields present. When None, C is set if checksum is given.
key (int | None) – Key, RFC 2890; setting this also sets K.
sequence_number (int | None) – Sequence Number, RFC 2890; setting this also sets S.
reserved (int) – Reserved bits of the flags word, in their on-wire positions (bit 1 and bits 4-12, i.e. within 0x4FF8).
version (Literal[0]) – Version Number; RFC 2784 fixes this at 0.
protocol_type (EtherType | int) – Protocol Type: the EtherType of the encapsulated payload.
payload (bytes | ProtocolBase | Schema) – Payload data.
**kwargs (Any) – Arbitrary keyword arguments.

Return type:

GRE

Returns:

Constructed packet data.

Raises:

ProtocolError – If checksum or reserved1 is given with C clear; if reserved sets a bit outside 0x4FF8; if version does not fit in 3 bits; if protocol_type is a name, a bool, or a member or code its field cannot carry; or if checksum, key or sequence_number is given but does not fit the width of its field (16 bits for checksum, 32 bits for key and sequence_number).

__length_hint__()[source]¶

Return an estimated length for the object.

The longest form – every optional field present, 16 octets – per the reason L2TPv2.__length_hint__ gives for a variable-length header: the shortest form would reject a fully captured longer header as too short.

Return type:: Literal[16]

classmethod __index__()[source]¶

Numeral registry index of the protocol.

Return type:: TransType
Returns:: Numeral registry index of the protocol in IANA protocol numbers, which Internet.__proto__ is keyed by. LinuxSLL.__proto__ names its own keys for this class, IPGRE and IP6GRE (The Registry Index).

classmethod _make_data(data)[source]¶

Create key-value pairs from data for protocol construction.

Parameters:: data (GRE) – protocol data
Return type:: dict[str, Any]
Returns:: Key-value pairs for protocol construction.

Header Schemas¶

class pcapkit.protocols.schema.link.gre.GRE(flags=NO_VALUE, protocol_type=NO_VALUE, checksum=NO_VALUE, reserved1=NO_VALUE, key=NO_VALUE, sequence_number=NO_VALUE, payload=NO_VALUE, *, __packet__=None, **kwargs)[source]¶

Bases: Schema

Header schema for a Generic Routing Encapsulation (GRE) frame.

The base header [RFC 2784] plus the optional Key and Sequence Number extensions [RFC 2890], as carried under IP protocol number 47, or as presented to a LINKTYPE_LINUX_SLL/LINKTYPE_LINUX_SLL2 capture whose arphrd_type is ARPHRD_IPGRE or ARPHRD_IP6GRE.

flags: FlagsType = <BitField flags>¶: Flags and version.

protocol_type: EtherType = <EnumField protocol_type>¶: Protocol Type – the EtherType of the encapsulated payload.

checksum: int | None = <ConditionalField checksum>¶: Checksum, present only when flags.checksum_present is set.

reserved1: int | None = <ConditionalField reserved1>¶: Reserved1, present only when flags.checksum_present is set.

key: int | None = <ConditionalField key>¶: Key, present only when flags.key_present is set, RFC 2890.

sequence_number: int | None = <ConditionalField sequence_number>¶: Sequence Number, present only when flags.sequence_present is set, RFC 2890.

payload: bytes = <PayloadField payload>¶: Payload.

Data Models¶

class pcapkit.protocols.data.link.gre.GRE(checksum_present, key_present, sequence_present, reserved, version, protocol_type, checksum, reserved1, key, sequence_number, len)[source]¶

Bases: Protocol

Data model for a Generic Routing Encapsulation (GRE) frame.

checksum_present: bool¶: Checksum Present bit (C), RFC 2784.

key_present: bool¶: Key Present bit (K), RFC 2890.

sequence_present: bool¶: Sequence Number Present bit (S), RFC 2890.

reserved: int¶: Reserved bits of the flags word outside C/K/S/Ver, in their on-wire positions (i.e. masked by 0x4FF8). RFC 2784 calls the whole 12-bit span (before RFC 2890 carved K/S out of it) Reserved0 and requires it sent as zero; carried verbatim so a rebuild reproduces the word as it arrived.

version: int¶: Version Number; RFC 2784 requires this to be 0.

protocol_type: EtherType¶: Protocol Type – the EtherType of the encapsulated payload.

checksum: int | None¶: Checksum, present only when checksum_present is set.

reserved1: int | None¶: Reserved1, present only when checksum_present is set; RFC 2784 requires it sent as zero, carried verbatim.

key: int | None¶: Key, present only when key_present is set, RFC 2890.

sequence_number: int | None¶: Sequence Number, present only when sequence_present is set, RFC 2890.

len: int¶: Header length, in octets – 4, plus 4 more for each of checksum_present, key_present and sequence_present that is set.

checksum_status: ChecksumStatus¶: Outcome of verifying checksum, present only when CHECKSUM_VERIFY is on; NOT_COMPUTED when checksum_present is clear.

Footnotes