Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions docs/source/contributing/pep.rst
Original file line number Diff line number Diff line change
Expand Up @@ -298,8 +298,8 @@ small part of each is bound to a dissector; everything else resolves to
complaint and yields nothing useful.

* :class:`~pcapkit.const.reg.linktype.LinkType` --
``NULL``, ``ETHERNET``, ``LOOP``, ``LINUX_SLL``, ``IPV4``, ``IPV6`` and
``LINUX_SLL2``, declared identically
``NULL``, ``ETHERNET``, ``IEEE802_11``, ``FRELAY``, ``LOOP``, ``LINUX_SLL``,
``IEEE802_11_RADIOTAP``, ``IPV4``, ``IPV6`` and ``LINUX_SLL2``, declared identically
in :class:`~pcapkit.protocols.misc.pcap.frame.Frame` and
:class:`~pcapkit.protocols.misc.pcapng.PCAPNG`, which also read ``RAW`` as
``IPV4`` or ``IPV6`` by its version nibble.
Expand Down Expand Up @@ -961,9 +961,11 @@ offload heuristic on :issue:`2470`.
clear is :attr:`~pcapkit.corekit.checksum.internet.ChecksumStatus.NOT_COMPUTED`,
and ``make()`` computes one when ``checksum_present`` asks without giving it.
Neither GRE nor the Linux cooked-capture header carries a length, so a GRE frame
the capture cut short is
:attr:`~pcapkit.corekit.checksum.internet.ChecksumStatus.INVALID`. Settled at
implementation (:issue:`2618`).
the capture cut short there is
:attr:`~pcapkit.corekit.checksum.internet.ChecksumStatus.INVALID`, settled at
implementation (:issue:`2618`); behind IPv4 or IPv6, which state the payload
length, it is :attr:`~pcapkit.corekit.checksum.internet.ChecksumStatus.TRUNCATED`
(:issue:`2649`).
* **DCCP covers what its Checksum Coverage gives** (:rfc:`4340#section-9.2`), over
a pseudo-header that carries the whole packet's length, as TCP's does, so a
fragment is
Expand Down
5 changes: 3 additions & 2 deletions docs/source/pcapkit/protocols/link/frad.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,9 @@ FRAD - Frame Relay Access Device
:mod:`pcapkit.protocols.link.frad` contains
:class:`~pcapkit.protocols.link.frad.FRAD`
only, which implements the extractor for Frame Relay's multiprotocol
encapsulation [*]_, as seen on a ``LINKTYPE_LINUX_SLL``/``LINKTYPE_LINUX_SLL2``
capture whose ``arphrd_type`` is ``ARPHRD_FRAD``. Its structure, the Q.922
encapsulation [*]_, as seen on a ``LINKTYPE_FRELAY`` capture, or on a
``LINKTYPE_LINUX_SLL``/``LINKTYPE_LINUX_SLL2`` capture whose ``arphrd_type`` is
``ARPHRD_FRAD``. Its structure, the Q.922
LAPF address onward with no trailing FCS, is described as below:

.. table::
Expand Down
18 changes: 13 additions & 5 deletions docs/source/pcapkit/protocols/link/gre.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,14 @@ GRE - Generic Routing Encapsulation
:class:`~pcapkit.protocols.link.gre.GRE`
only, which implements the extractor for the Generic Routing Encapsulation
base header [*]_ plus the optional Key and Sequence Number extensions [*]_, as
seen on a ``LINKTYPE_LINUX_SLL``/``LINKTYPE_LINUX_SLL2`` capture whose
``arphrd_type`` is ``ARPHRD_IPGRE`` or ``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:
reached through IP protocol number 47 behind any layer sharing
:attr:`Internet.__proto__ <pcapkit.protocols.internet.internet.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:

.. table::

Expand Down Expand Up @@ -47,6 +50,11 @@ 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 (:issue:`1581`), and IPv4
reassembly of an outer datagram fragmented in transit yields a parsed GRE
layer.

.. autoclass:: pcapkit.protocols.link.gre.GRE
:no-members:
:show-inheritance:
Expand Down
5 changes: 5 additions & 0 deletions examples/generators/dispatch_families/internet.py
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
4, # IPv4
6, # TCP
17, # UDP
47, # GRE
50, # ESP
51, # AH
89, # OSPFIGP
Expand Down Expand Up @@ -79,6 +80,9 @@ def _payload(code: 'int') -> 'bytes':
if code == TransType.IPv6_Frag:
from pcapkit.protocols.internet.ipv6_frag import IPv6_Frag
return bytes(IPv6_Frag(next=17, id=1, offset=0, mf=False, payload=_udp(9999)))
if code == TransType.GRE:
from pcapkit.protocols.link.gre import GRE
return bytes(GRE(protocol_type=0x0800, payload=_ip4(6, _tcp(9999))))
if code == TransType.ESP:
from pcapkit.protocols.internet.esp import ESP
return bytes(ESP(spi=0x1234, seq=1, payload=b'\x01\x02\x03\x04'))
Expand Down Expand Up @@ -164,6 +168,7 @@ def _build(code: 'int') -> 'Any':
'internet/IPv6_ICMP': ('pcapkit.protocols.internet.icmpv6', 'ICMPv6'),
'internet/IPv6_Route': ('pcapkit.protocols.internet.ipv6_route', 'IPv6_Route'),
'internet/IPv6_Frag': ('pcapkit.protocols.internet.ipv6_frag', 'IPv6_Frag'),
'internet/GRE': ('pcapkit.protocols.link.gre', 'GRE'),
'internet/ESP': ('pcapkit.protocols.internet.esp', 'ESP'),
'internet/AH': ('pcapkit.protocols.internet.ah', 'AH'),
'internet/IGMP': ('pcapkit.protocols.internet.igmp', 'IGMP'),
Expand Down
5 changes: 5 additions & 0 deletions examples/generators/dispatch_families/linktype.py
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,9 @@ def _payload(code: 'Any') -> 'tuple[bytes, bool]':
return _wlan_ack(), False
if code == LinkType.IEEE802_11_RADIOTAP:
return _radiotap(_wlan_ack()), False
if code == LinkType.FRELAY: # direct NLPID 0xCC, IPv4
from pcapkit.protocols.link.frad import FRAD
return bytes(FRAD(nlpid=0xCC, payload=_ip4(6, _tcp(9999)))), False
raise LookupError(f'linktype: no payload builder for {code!r}') # pragma: no cover


Expand Down Expand Up @@ -110,6 +113,7 @@ def _pcapng_build(code: 'Any') -> 'Any':
'pcap-frame/LINUX_SLL2': ('pcapkit.protocols.link', 'LinuxSLL2'),
'pcap-frame/IEEE802_11': ('pcapkit.protocols.link', 'IEEE802_11'),
'pcap-frame/IEEE802_11_RADIOTAP': ('pcapkit.protocols.link', 'Radiotap'),
'pcap-frame/FRELAY': ('pcapkit.protocols.link', 'FRAD'),

# -- PCAPNG.__proto__ (LinkType) --------------------------------------------
'pcapng-frame/NULL': ('pcapkit.protocols.link', 'Loopback'),
Expand All @@ -121,4 +125,5 @@ def _pcapng_build(code: 'Any') -> 'Any':
'pcapng-frame/LINUX_SLL2': ('pcapkit.protocols.link', 'LinuxSLL2'),
'pcapng-frame/IEEE802_11': ('pcapkit.protocols.link', 'IEEE802_11'),
'pcapng-frame/IEEE802_11_RADIOTAP': ('pcapkit.protocols.link', 'Radiotap'),
'pcapng-frame/FRELAY': ('pcapkit.protocols.link', 'FRAD'),
}
5 changes: 5 additions & 0 deletions pcapkit/protocols/internet/internet.py
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,8 @@ class Internet(ProtocolBase[_PT, _ST], Generic[_PT, _ST]): # pylint: disable=ab
- :class:`pcapkit.protocols.internet.ipv6_route.IPv6_Route`
* - :attr:`~pcapkit.const.reg.transtype.TransType.IPv6_Frag`
- :class:`pcapkit.protocols.internet.ipv6_frag.IPv6_Frag`
* - :attr:`~pcapkit.const.reg.transtype.TransType.GRE`
- :class:`pcapkit.protocols.link.gre.GRE`
* - :attr:`~pcapkit.const.reg.transtype.TransType.ESP`
- :class:`pcapkit.protocols.internet.esp.ESP`
* - :attr:`~pcapkit.const.reg.transtype.TransType.AH`
Expand Down Expand Up @@ -134,6 +136,9 @@ class Internet(ProtocolBase[_PT, _ST], Generic[_PT, _ST]): # pylint: disable=ab
Enum_TransType.IPv6_ICMP: ModuleDescriptor('pcapkit.protocols.internet.icmpv6', 'ICMPv6'),
Enum_TransType.IPv6_Route: ModuleDescriptor('pcapkit.protocols.internet.ipv6_route', 'IPv6_Route'),
Enum_TransType.IPv6_Frag: ModuleDescriptor('pcapkit.protocols.internet.ipv6_frag', 'IPv6_Frag'),
# NOTE: a tunnel is placed by its payload, so GRE lives under ``protocols.link``;
# see :doc:`/contributing/conventions/protocol-layer-placement`.
Enum_TransType.GRE: ModuleDescriptor('pcapkit.protocols.link.gre', 'GRE'),
Enum_TransType.ESP: ModuleDescriptor('pcapkit.protocols.internet.esp', 'ESP'),
Enum_TransType.AH: ModuleDescriptor('pcapkit.protocols.internet.ah', 'AH'),
Enum_TransType.IGMP: ModuleDescriptor('pcapkit.protocols.internet.igmp', 'IGMP'),
Expand Down
1 change: 1 addition & 0 deletions pcapkit/protocols/link/frad.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
:mod:`pcapkit.protocols.link.frad` contains
:class:`~pcapkit.protocols.link.frad.FRAD` only, which implements the
extractor for Frame Relay's multiprotocol encapsulation [*]_, as seen on a
``LINKTYPE_FRELAY`` capture, or on a
``LINKTYPE_LINUX_SLL``/``LINKTYPE_LINUX_SLL2`` capture whose ``arphrd_type``
is ``ARPHRD_FRAD`` -- :class:`~pcapkit.protocols.link.linux_sll.LinuxSLL`
dispatches here instead of falling back to
Expand Down
12 changes: 9 additions & 3 deletions pcapkit/protocols/link/gre.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,13 @@
:mod:`pcapkit.protocols.link.gre` contains
:class:`~pcapkit.protocols.link.gre.GRE` only, which implements the extractor
for the Generic Routing Encapsulation base header [:rfc:`2784`] plus the
optional Key and Sequence Number extensions [:rfc:`2890`], as seen on a
optional Key and Sequence Number extensions [:rfc:`2890`]. It is reached
through IP protocol number 47 behind any layer sharing
:attr:`Internet.__proto__ <pcapkit.protocols.internet.internet.Internet.__proto__>`,
IPv4 and IPv6 among them, and on a
``LINKTYPE_LINUX_SLL``/``LINKTYPE_LINUX_SLL2`` capture whose ``arphrd_type``
is ``ARPHRD_IPGRE`` or ``ARPHRD_IP6GRE`` -- both land on this one class:
is ``ARPHRD_IPGRE`` or ``ARPHRD_IP6GRE`` -- ``ARPHRD_IPGRE`` and
``ARPHRD_IP6GRE`` both land on this one class:
:class:`~pcapkit.protocols.link.linux_sll.LinuxSLL` dispatches here instead
of falling back to :class:`~pcapkit.protocols.misc.raw.Raw` for either case;
see :attr:`LinuxSLL.__proto__ <pcapkit.protocols.link.linux_sll.LinuxSLL.__proto__>`. The
Expand Down Expand Up @@ -359,7 +363,9 @@ def __index__(cls) -> 'Enum_TransType': # pylint: disable=invalid-index-returne

Returns:
Numeral registry index of the protocol in `IANA`_ protocol
numbers.
numbers, which
:attr:`Internet.__proto__ <pcapkit.protocols.internet.internet.Internet.__proto__>`
is keyed by.
:attr:`LinuxSLL.__proto__ <pcapkit.protocols.link.linux_sll.LinuxSLL.__proto__>`
names its own keys for this class,
:attr:`~pcapkit.const.linux.arphrd.ARPHRD.IPGRE` and
Expand Down
3 changes: 3 additions & 0 deletions pcapkit/protocols/misc/pcap/frame.py
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,8 @@ class Frame(ProtocolBase[Data_Frame, Schema_Frame],
- :class:`pcapkit.protocols.link.ethernet.Ethernet`
* - :attr:`pcapkit.const.reg.linktype.LinkType.IEEE802_11`
- :class:`pcapkit.protocols.link.ieee802_11.IEEE802_11`
* - :attr:`pcapkit.const.reg.linktype.LinkType.FRELAY`
- :class:`pcapkit.protocols.link.frad.FRAD`
* - :attr:`pcapkit.const.reg.linktype.LinkType.LOOP`
- :class:`pcapkit.protocols.link.loopback.Loopback`
* - :attr:`pcapkit.const.reg.linktype.LinkType.LINUX_SLL`
Expand Down Expand Up @@ -119,6 +121,7 @@ class Frame(ProtocolBase[Data_Frame, Schema_Frame],
Enum_LinkType.NULL: ModuleDescriptor('pcapkit.protocols.link', 'Loopback'),
Enum_LinkType.ETHERNET: ModuleDescriptor('pcapkit.protocols.link', 'Ethernet'),
Enum_LinkType.IEEE802_11: ModuleDescriptor('pcapkit.protocols.link', 'IEEE802_11'),
Enum_LinkType.FRELAY: ModuleDescriptor('pcapkit.protocols.link', 'FRAD'),
Enum_LinkType.LOOP: ModuleDescriptor('pcapkit.protocols.link', 'Loopback'),
Enum_LinkType.LINUX_SLL: ModuleDescriptor('pcapkit.protocols.link', 'LinuxSLL1'),
Enum_LinkType.IEEE802_11_RADIOTAP: ModuleDescriptor('pcapkit.protocols.link', 'Radiotap'),
Expand Down
3 changes: 3 additions & 0 deletions pcapkit/protocols/misc/pcapng.py
Original file line number Diff line number Diff line change
Expand Up @@ -482,6 +482,8 @@ class PCAPNG(ProtocolBase[Data_PCAPNG, Schema_PCAPNG],
- :class:`pcapkit.protocols.link.ethernet.Ethernet`
* - :attr:`pcapkit.const.reg.linktype.LinkType.IEEE802_11`
- :class:`pcapkit.protocols.link.ieee802_11.IEEE802_11`
* - :attr:`pcapkit.const.reg.linktype.LinkType.FRELAY`
- :class:`pcapkit.protocols.link.frad.FRAD`
* - :attr:`pcapkit.const.reg.linktype.LinkType.LOOP`
- :class:`pcapkit.protocols.link.loopback.Loopback`
* - :attr:`pcapkit.const.reg.linktype.LinkType.LINUX_SLL`
Expand Down Expand Up @@ -776,6 +778,7 @@ class PCAPNG(ProtocolBase[Data_PCAPNG, Schema_PCAPNG],
Enum_LinkType.NULL: ModuleDescriptor('pcapkit.protocols.link', 'Loopback'),
Enum_LinkType.ETHERNET: ModuleDescriptor('pcapkit.protocols.link', 'Ethernet'),
Enum_LinkType.IEEE802_11: ModuleDescriptor('pcapkit.protocols.link', 'IEEE802_11'),
Enum_LinkType.FRELAY: ModuleDescriptor('pcapkit.protocols.link', 'FRAD'),
Enum_LinkType.LOOP: ModuleDescriptor('pcapkit.protocols.link', 'Loopback'),
Enum_LinkType.LINUX_SLL: ModuleDescriptor('pcapkit.protocols.link', 'LinuxSLL1'),
Enum_LinkType.IEEE802_11_RADIOTAP: ModuleDescriptor('pcapkit.protocols.link', 'Radiotap'),
Expand Down
7 changes: 4 additions & 3 deletions pcapkit/protocols/schema/link/frad.py
Original file line number Diff line number Diff line change
Expand Up @@ -72,9 +72,10 @@ class FRAD(Schema):
"""Header schema for a Frame Relay Access Device (FRAD) frame.

The frame is Frame Relay's multiprotocol encapsulation [:rfc:`2427`,
obsoleting :rfc:`1490`] as presented to a ``LINKTYPE_LINUX_SLL``/
``LINKTYPE_LINUX_SLL2`` capture whose ``arphrd_type`` is ``ARPHRD_FRAD``:
the Q.922 LAPF address onward, with no trailing FCS.
obsoleting :rfc:`1490`] as presented to a ``LINKTYPE_FRELAY`` capture,
or to a ``LINKTYPE_LINUX_SLL``/``LINKTYPE_LINUX_SLL2`` capture whose
``arphrd_type`` is ``ARPHRD_FRAD``: the Q.922 LAPF address onward, with no
trailing FCS.

"""

Expand Down
6 changes: 3 additions & 3 deletions pcapkit/protocols/schema/link/gre.py
Original file line number Diff line number Diff line change
Expand Up @@ -43,9 +43,9 @@ class GRE(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 presented to a ``LINKTYPE_LINUX_SLL``/
``LINKTYPE_LINUX_SLL2`` capture whose ``arphrd_type`` is ``ARPHRD_IPGRE``
or ``ARPHRD_IP6GRE``.
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``.

"""

Expand Down
Loading
Loading