feat(protocols): add the IP_Pseudo pseudo-protocol for the IP pseudo-header (#2471)

docs/source/contributing/pep.rst

@@ -889,9 +889,9 @@ from *wrong*, or it will cry wolf on the commonest capture there is —
 model for how to spell "expected, not an error".
 
 Sequenced for **wave 2 or 3**. The cryptographic half could be done sooner since
-ESP has already laid the groundwork, but the checksum half needs the IP
-pseudo-header class defined first, and that is worth doing deliberately rather
-than as a side effect of a checksum patch.
+ESP has already laid the groundwork. The checksum half builds on the IP
+pseudo-header class, :class:`~pcapkit.protocols.misc.checksum.ip_pseudo.IP_Pseudo`
+(:issue:`2471`).
 
 Deterministic Construction Arguments
 ------------------------------------
@@ -1277,12 +1277,14 @@ equally blocked: the cryptographic half (HIP's ``HIP_MAC``/``RVS_HMAC``/
 ``RELAY_HMAC`` and its signature parameters) could start whenever, since
 :class:`~pcapkit.protocols.internet.esp.ESP` has already established both the
 keying-context channel and the report-rather-than-raise policy. The
-one's-complement half (IPv4, TCP, UDP, ICMP/ICMPv6, OSPF) needs the IP
-pseudo-header, and the owner has settled how: a **pseudo-protocol class** for the
-IP family, serving both the parsing and the constructing path, rather than a
-back-reference from a parsed protocol to its parent. So that half is not blocked
-on an open design question -- only on someone defining that class, which is a
-bounded piece of work and the natural first step.
+one's-complement half (IPv4, TCP, UDP, ICMP/ICMPv6, OSPF) is :issue:`2470` and
+:issue:`2472` to :issue:`2475`.
+
+**IP pseudo-header — done** (:issue:`2471`).
+:class:`~pcapkit.protocols.misc.checksum.ip_pseudo.IP_Pseudo` is the
+**pseudo-protocol class** for the IP family the owner settled on, serving both
+the parsing and the constructing path, rather than a back-reference from a
+parsed protocol to its parent.
 
 **Queued for wave 2 or 3 — deterministic construction arguments.** See
 `Deterministic Construction Arguments`_ above: dropping ``make()``'s implicit

docs/source/pcapkit/protocols/index.rst

@@ -38,6 +38,10 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
                PCAPNG
            end
 
+           subgraph checksum [Checksum Pseudo-Headers]
+               IP_Pseudo
+           end
+
            Raw & NoPayload
        end
 
@@ -112,7 +116,7 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
 
        B --> Link & Internet & Transport & Application
 
-       B --> Header & Frame & PCAPNG & Raw & NoPayload
+       B --> Header & Frame & PCAPNG & Raw & NoPayload & IP_Pseudo
        Raw --> FTP_DATA
        ARP --> RARP
        IPv6_Ext --> AH & ESP
@@ -158,6 +162,7 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
        click IPv6-Frag "internet/ipv6_frag.html#pcapkit.protocols.internet.ipv6_frag.IPv6_Frag"
        click IPv6-Opts "internet/ipv6_opts.html#pcapkit.protocols.internet.ipv6_opts.IPv6_Opts"
        click IPv6-Route "internet/ipv6_route.html#pcapkit.protocols.internet.ipv6_route.IPv6_Route"
+       click IP_Pseudo "misc/checksum.html#pcapkit.protocols.misc.checksum.ip_pseudo.IP_Pseudo"
        click IPX "internet/ipx.html#pcapkit.protocols.internet.ipx.IPX"
        click MH "internet/mh.html#pcapkit.protocols.internet.mh.MH"
 

docs/source/pcapkit/protocols/misc/checksum.rst

@@ -0,0 +1,85 @@
+IP Pseudo-Header
+================
+
+.. module:: pcapkit.protocols.misc.checksum.ip_pseudo
+
+:mod:`pcapkit.protocols.misc.checksum.ip_pseudo` contains
+:class:`~pcapkit.protocols.misc.checksum.ip_pseudo.IP_Pseudo` only,
+which implements the pseudo-header of the IP protocol family
+that the upper-layer checksums cover, whose structure is
+described as below:
+
+IPv4 (:rfc:`793#section-3.1`, :rfc:`768`):
+
+======= ========= ========================= ===============================
+Octets      Bits        Name                    Description
+======= ========= ========================= ===============================
+  0           0   ``ip_pseudo.src``           Source Address
+  4          32   ``ip_pseudo.dst``           Destination Address
+  8          64   ``ip_pseudo.zero``          Reserved
+  9          72   ``ip_pseudo.protocol``      Protocol
+  10         80   ``ip_pseudo.len``           Upper-Layer Packet Length
+======= ========= ========================= ===============================
+
+IPv6 (:rfc:`8200#section-8.1`):
+
+======= ========= ========================= ===============================
+Octets      Bits        Name                    Description
+======= ========= ========================= ===============================
+  0           0   ``ip_pseudo.src``           Source Address
+  16        128   ``ip_pseudo.dst``           Destination Address
+  32        256   ``ip_pseudo.len``           Upper-Layer Packet Length
+  36        288   ``ip_pseudo.zero``          Reserved
+  39        312   ``ip_pseudo.protocol``      Next Header
+======= ========= ========================= ===============================
+
+.. autoclass:: pcapkit.protocols.misc.checksum.ip_pseudo.IP_Pseudo
+   :no-members:
+   :show-inheritance:
+
+   .. autoproperty:: name
+   .. autoproperty:: length
+   .. autoproperty:: protocol
+   .. autoproperty:: version
+   .. autoproperty:: src
+   .. autoproperty:: dst
+
+   .. automethod:: read
+   .. automethod:: make
+
+   .. automethod:: _make_data
+   .. automethod:: _source
+   .. automethod:: _destination
+   .. automethod:: _upper_protocol
+   .. automethod:: _upper_length
+
+   .. automethod:: __post_init__
+   .. automethod:: __index__
+
+Header Schemas
+--------------
+
+.. module:: pcapkit.protocols.schema.misc.checksum.ip_pseudo
+
+.. autodata:: pcapkit.protocols.schema.misc.checksum.ip_pseudo.IPV4_PSEUDO_LEN
+.. autodata:: pcapkit.protocols.schema.misc.checksum.ip_pseudo.IPV6_PSEUDO_LEN
+
+.. autoclass:: pcapkit.protocols.schema.misc.checksum.ip_pseudo.IP_Pseudo
+   :members:
+   :show-inheritance:
+
+Auxiliary Functions
+~~~~~~~~~~~~~~~~~~~
+
+.. autofunction:: pcapkit.protocols.schema.misc.checksum.ip_pseudo.is_ipv6
+.. autofunction:: pcapkit.protocols.schema.misc.checksum.ip_pseudo.ip_pseudo_address_selector
+.. autofunction:: pcapkit.protocols.schema.misc.checksum.ip_pseudo.ip_pseudo_zero_selector
+
+Data Models
+-----------
+
+.. module:: pcapkit.protocols.data.misc.checksum.ip_pseudo
+
+.. autoclass:: pcapkit.protocols.data.misc.checksum.ip_pseudo.IP_Pseudo
+   :members:
+   :show-inheritance:

docs/source/pcapkit/protocols/misc/index.rst

@@ -19,3 +19,4 @@ empty payload.
    pcapng
    raw
    null
+   checksum

pcapkit/__init__.py

@@ -119,6 +119,7 @@
 
     'HIP', 'HOPOPT', 'IPv6_Frag', 'IPv6_Ext', 'IPv6_Opts', 'IPv6_Route', 'MH',
                                                             # IPv6 Extension Header
+    'IP_Pseudo',                                            # IP Pseudo-Header
 
     'TCP', 'UDP', 'SCTP',                                   # Transport Layer
 

pcapkit/all.py

@@ -128,6 +128,7 @@
 
     'HIP', 'HOPOPT', 'IPv6_Ext', 'IPv6_Frag', 'IPv6_Opts', 'IPv6_Route', 'MH',
                                                             # IPv6 Extension Header
+    'IP_Pseudo',                                            # IP Pseudo-Header
     'TCP', 'UDP', 'SCTP',                                   # Transport Layer
     'FTP', 'FTP_DATA',                                      # Application Layer
     'HTTP', 'HTTPv1', 'HTTPv2', 'NGAP', 'OSPF', 'RARP', 'DRARP',

pcapkit/protocols/__init__.py

@@ -57,6 +57,9 @@
     'AH', 'ESP', 'ICMP', 'ICMPv4', 'ICMPv6', 'IGMP', 'IGMPv1', 'IGMPv2', 'IGMPv3',
     'IP', 'IPsec', 'IPv4', 'IPv6', 'IPX',
 
+    # IP Pseudo-Header
+    'IP_Pseudo',
+
     # IPv6 Extension Header
     'HIP', 'HOPOPT', 'IPv6_Frag', 'IPv6_Ext', 'IPv6_Opts',
     'IPv6_Route', 'MH',

pcapkit/protocols/data/__init__.py

@@ -115,6 +115,9 @@
     'HOPOPT_LineIdentificationOption', 'HOPOPT_JumboPayloadOption', 'HOPOPT_HomeAddressOption',
     'HOPOPT_IPDFFOption',
 
+    # IP Pseudo-Header
+    'IP_Pseudo',
+
     # Internet Control Message Protocol
     'ICMPv4',
     'ICMPv4_Unknown', 'ICMPv4_Echo', 'ICMPv4_DestinationUnreachable', 'ICMPv4_TimeExceeded',

pcapkit/protocols/data/misc/__init__.py

@@ -76,6 +76,7 @@
 # misc protocols
 from pcapkit.protocols.data.misc.raw import Raw
 from pcapkit.protocols.data.misc.null import NoPayload
+from pcapkit.protocols.data.misc.checksum import IP_Pseudo
 
 __all__ = [
     # PCAP file headers
@@ -105,6 +106,7 @@
     'PCAPNG_CustomBlock', 'PCAPNG_PacketBlock',
 
     # No Payload
+    'IP_Pseudo',
     'NoPayload',
 
     # Raw Packet

pcapkit/protocols/data/misc/checksum/__init__.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+"""data models for checksum pseudo-headers"""
+
+from pcapkit.protocols.data.misc.checksum.ip_pseudo import IP_Pseudo
+
+__all__ = ['IP_Pseudo']

pcapkit/protocols/data/misc/checksum/ip_pseudo.py

@@ -0,0 +1,41 @@
+# -*- coding: utf-8 -*-
+"""data model for the IP pseudo-header"""
+
+from typing import TYPE_CHECKING
+
+from pcapkit.corekit.infoclass import info_final
+from pcapkit.protocols.data.protocol import Protocol
+
+if TYPE_CHECKING:
+    from ipaddress import IPv4Address, IPv6Address
+
+    from typing_extensions import Literal
+
+    from pcapkit.const.reg.transtype import TransType
+
+__all__ = ['IP_Pseudo']
+
+
+@info_final
+class IP_Pseudo(Protocol):
+    """Data model for the IP pseudo-header.
+
+    .. versionadded:: 1.6.0
+
+    """
+
+    #: IP version of the enclosing layer.
+    version: 'Literal[4, 6]'
+    #: Source address.
+    src: 'IPv4Address | IPv6Address'
+    #: Destination address.
+    dst: 'IPv4Address | IPv6Address'
+    #: Upper-layer protocol number.
+    protocol: 'TransType'
+    #: Upper-layer packet length, header included.
+    len: 'int'
+    #: Reserved octets, as parsed.
+    zero: 'bytes'
+
+    if TYPE_CHECKING:
+        def __init__(self, version: 'Literal[4, 6]', src: 'IPv4Address | IPv6Address', dst: 'IPv4Address | IPv6Address', protocol: 'TransType', len: 'int', zero: 'bytes') -> 'None': ...  # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin,line-too-long

pcapkit/protocols/misc/__init__.py

@@ -8,7 +8,8 @@
 :mod:`pcapkit.protocols.misc` contains the auxiliary protocol implementations.
 These include the :class:`~pcapkit.protocols.misc.raw.Raw` class for not-supported
 protocols, the :class:`~pcapkit.protocols.misc.null.NoPayload` class for
-indication of empty payload, and the PCAP and PCAP-NG file format classes.
+indication of empty payload, the PCAP and PCAP-NG file format classes, and the
+checksum pseudo-headers in :mod:`pcapkit.protocols.misc.checksum`.
 
 """
 
@@ -22,6 +23,9 @@
 from pcapkit.protocols.misc.raw import Raw
 from pcapkit.protocols.misc.null import NoPayload
 
+# Checksum Pseudo-Headers
+from pcapkit.protocols.misc.checksum import IP_Pseudo
+
 __all__ = [
     # PCAP Headers
     'Header', 'Frame',
@@ -34,4 +38,7 @@
 
     # Raw Packet
     'Raw',
+
+    # Checksum Pseudo-Headers
+    'IP_Pseudo',
 ]

pcapkit/protocols/misc/checksum/__init__.py

@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+"""Checksum Pseudo-Headers
+=============================
+
+.. module:: pcapkit.protocols.misc.checksum
+
+:mod:`pcapkit.protocols.misc.checksum` contains the pseudo-header protocols
+that upper-layer checksums cover, currently
+:class:`~pcapkit.protocols.misc.checksum.ip_pseudo.IP_Pseudo` only.
+
+"""
+from pcapkit.protocols.misc.checksum.ip_pseudo import IP_Pseudo
+
+__all__ = ['IP_Pseudo']