docs(protocols): version directives and accurate prose for the internet layer (#1103)

docs/source/pcapkit/protocols/internet/ah.rst

@@ -14,7 +14,7 @@ Octets      Bits        Name                    Description
 ======= ========= ======================= ===================================
   0           0   ``ah.next``               Next Header
   1           8   ``ah.length``             Payload Length
-  2          16                             Reserved (must be zero)
+  2          16   ``ah.reserved``           Reserved (must be zero)
   4          32   ``ah.spi``                Security Parameters Index (SPI)
   8          64   ``ah.seq``                Sequence Number Field
   12         96   ``ah.icv``                Integrity Check Value (ICV)

docs/source/pcapkit/protocols/internet/esp.rst

@@ -37,6 +37,8 @@ negotiated out of band. Therefore:
   ``Pad Length``, and dispatches the recovered plaintext to the next layer
   using ``Next Header`` -- so an ESP tunnelled TCP segment decodes as TCP.
 
+.. versionadded:: 1.5.0
+
 .. autoclass:: pcapkit.protocols.internet.esp.ESP
    :no-members:
    :show-inheritance:

docs/source/pcapkit/protocols/internet/hip.rst

@@ -14,11 +14,11 @@ Octets      Bits        Name                    Description
 ======= ========= ====================== ==================================
   0           0   ``hip.next``              Next Header
   1           8   ``hip.length``            Header Length
-  2          16                             Reserved (``\x00``)
+  2          16   ``hip.packet_fixed``      Reserved (``\x00``)
   2          17   ``hip.type``              Packet Type
   3          24   ``hip.version``           Version
-  3          28                             Reserved
-  3          31                             Reserved (``\x01``)
+  3          28   ``hip.reserved``          Reserved
+  3          31   ``hip.version_fixed``     Reserved (``\x01``)
   4          32   ``hip.chksum``            Checksum
   6          48   ``hip.control``           Controls
   8          64   ``hip.shit``              Sender's Host Identity Tag

docs/source/pcapkit/protocols/internet/hopopt.rst

@@ -13,7 +13,7 @@ described as below:
 Octets      Bits        Name                    Description
 ======= ========= =================== =================================
   0           0   ``hopopt.next``             Next Header
-  1           8   ``hopopt.length``           Header Extensive Length
+  1           8   ``hopopt.length``           Header Extension Length
   2          16   ``hopopt.options``          Options
 ======= ========= =================== =================================
 
@@ -22,6 +22,7 @@ Octets      Bits        Name                    Description
    :show-inheritance:
 
    .. autoproperty:: name
+   .. autoproperty:: alias
    .. autoproperty:: length
    .. autoproperty:: payload
    .. autoproperty:: protocol

docs/source/pcapkit/protocols/internet/internet.rst

@@ -15,6 +15,7 @@ which is a base class for internet layer protocols, eg. :class:`~pcapkit.protoco
    .. autoproperty:: layer
 
    .. automethod:: register
+   .. automethod:: from_data
 
    .. automethod:: _decode_next_layer
    .. automethod:: _import_next_layer

docs/source/pcapkit/protocols/internet/ip.rst

@@ -7,9 +7,8 @@ IP - Internet Protocol
 :class:`~pcapkit.protocols.internet.ip.IP` only,
 which is a base class for Internet Protocol (IP)
 protocol family [*]_, eg.
-:class:`~pcapkit.protocols.internet.ipv4.IPv4`,
-:class:`~pcapkit.protocols.internet.ipv6.IPv6`, and
-:class:`~pcapkit.protocols.internet.ipsec.IPsec`.
+:class:`~pcapkit.protocols.internet.ipv4.IPv4` and
+:class:`~pcapkit.protocols.internet.ipv6.IPv6`.
 
 .. autoclass:: pcapkit.protocols.internet.ip.IP
    :no-members:

docs/source/pcapkit/protocols/internet/ipsec.rst

@@ -14,9 +14,6 @@ Security (IPsec) protocol family [*]_, eg.
    :no-members:
    :show-inheritance:
 
-   :param \*args: Arbitrary positional arguments.
-   :param \*\*kwargs: Arbitrary keyword arguments.
-
    .. automethod:: id
 
 .. rubric:: Footnotes

docs/source/pcapkit/protocols/internet/ipv6.rst

@@ -41,6 +41,7 @@ Octets      Bits        Name                    Description
    .. automethod:: _make_data
 
    .. automethod:: _decode_next_layer
+   .. automethod:: _import_next_layer
 
    .. automethod:: __index__
 
@@ -84,6 +85,12 @@ Type Stubs
 
       Flow label.
 
+Auxiliary Functions
+~~~~~~~~~~~~~~~~~~~
+
+.. autofunction:: pcapkit.protocols.schema.internet.ipv6.jumbo_payload_length
+.. autofunction:: pcapkit.protocols.schema.internet.ipv6.jumbogram_error
+
 Data Models
 -----------
 

docs/source/pcapkit/protocols/internet/ipv6_frag.rst

@@ -9,16 +9,16 @@ only, which implements extractor for Fragment Header for
 IPv6 (IPv6-Frag) [*]_, whose structure is described as
 below:
 
-======= ========= ==================== =======================
+======= ========= ========================= =======================
 Octets      Bits        Name                    Description
-======= ========= ==================== =======================
+======= ========= ========================= =======================
   0           0   ``frag.next``               Next Header
-  1           8                               Reserved
+  1           8   ``frag.reserved_octet``     Reserved
   2          16   ``frag.offset``             Fragment Offset
-  3          29                               Reserved
+  3          29   ``frag.reserved``           Reserved
   3          31   ``frag.mf``                 More Flag
   4          32   ``frag.id``                 Identification
-======= ========= ==================== =======================
+======= ========= ========================= =======================
 
 .. autoclass:: pcapkit.protocols.internet.ipv6_frag.IPv6_Frag
    :no-members:

docs/source/pcapkit/protocols/internet/ipv6_opts.rst

@@ -13,7 +13,7 @@ as below:
 Octets      Bits        Name                    Description
 ======= ========= =================== =================================
   0           0   ``opts.next``             Next Header
-  1           8   ``opts.length``           Header Extensive Length
+  1           8   ``opts.length``           Header Extension Length
   2          16   ``opts.options``          Options
 ======= ========= =================== =================================
 
@@ -22,6 +22,7 @@ Octets      Bits        Name                    Description
    :show-inheritance:
 
    .. autoproperty:: name
+   .. autoproperty:: alias
    .. autoproperty:: length
    .. autoproperty:: payload
    .. autoproperty:: protocol

docs/source/pcapkit/protocols/internet/ipv6_route.rst

@@ -12,7 +12,7 @@ only, which implements extractor for Routing Header for IPv6
 Octets      Bits        Name                    Description
 ======= ========= ==================== ===============================
   0           0   ``route.next``            Next Header
-  1           8   ``route.length``          Header Extensive Length
+  1           8   ``route.length``          Header Extension Length
   2          16   ``route.type``            Routing Type
   3          24   ``route.seg_left``        Segments Left
   4          32   ``route.data``            Type-Specific Data

pcapkit/protocols/internet/ah.py

@@ -5,7 +5,7 @@
 .. module:: pcapkit.protocols.internet.ah
 
 :mod:`pcapkit.protocols.internet.ah` contains
-:class:`~pcapkit.protocols.internet.AH` only,
+:class:`~pcapkit.protocols.internet.ah.AH` only,
 which implements extractor for Authentication
 Header (AH) [*]_, whose structure is described
 as below:
@@ -15,7 +15,7 @@
 ======= ========= ======================= ===================================
   0           0   ``ah.next``               Next Header
   1           8   ``ah.length``             Payload Length
-  2          16                             Reserved (must be zero)
+  2          16   ``ah.reserved``           Reserved (must be zero)
   4          32   ``ah.spi``                Security Parameters Index (SPI)
   8          64   ``ah.seq``                Sequence Number Field
   12         96   ``ah.icv``                Integrity Check Value (ICV)
@@ -65,6 +65,11 @@ class AH(IPsec[Data_AH, Schema_AH], IPv6_Ext[Data_AH, Schema_AH],
     :class:`~pcapkit.protocols.internet.ipsec.IPsec` comes first so that its
     :meth:`~pcapkit.protocols.internet.ipsec.IPsec.id` takes precedence.
 
+    .. versionchanged:: 1.5.0
+
+       A rebuild writes the reserved field back as captured rather than as
+       zero (:issue:`1327`).
+
     """
 
     ##########################################################################

pcapkit/protocols/internet/esp.py

@@ -160,6 +160,8 @@
 
 .. [*] https://en.wikipedia.org/wiki/IPsec
 
+.. versionadded:: 1.5.0
+
 """
 import enum
 import hashlib
@@ -502,7 +504,8 @@ class SecurityAssociation:
             unless ``salt`` is given separately.
         salt: AEAD salt, when not appended to ``encryption_key``.
         integrity: Integrity algorithm, c.f. :meth:`IntegritySuite.get`. Must
-            be :attr:`Integrity.NONE` for an AEAD suite, which provides its own.
+            be :attr:`Integrity.NONE <pcapkit.const.esp.integrity.Integrity.NONE>`
+            for an AEAD suite, which provides its own.
         integrity_key: Integrity key.
         icv_length: Override for the ICV length, in octets. Needed for the
             long standing implementation bug noted in :rfc:`8221` §6, where
@@ -984,9 +987,11 @@ class ESP(IPsec[Data_ESP, Schema_ESP], IPv6_Ext[Data_ESP, Schema_ESP],
     next-layer protocol in IPv4, so it also travels directly as an IPv4
     payload, which is what qualifies it for a base besides
     :class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext`.
-    :attr:`payload` and :attr:`protochain` come from
-    :class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext`; :attr:`protocol`
-    is spelled out below for the reason given there.
+    :attr:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.payload` and
+    :attr:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.protochain` come from
+    :class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext`; ``protocol`` is
+    spelled out here for the reason given on
+    :attr:`IPv6_Ext.protocol <pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.protocol>`.
 
     Note:
         :rfc:`8200#section-4.5` says outright that ESP "is not considered an

pcapkit/protocols/internet/hip.py

@@ -15,11 +15,11 @@
 ======= ========= ====================== ==================================
   0           0   ``hip.next``              Next Header
   1           8   ``hip.length``            Header Length
-  2          16                             Reserved (``\\x00``)
+  2          16   ``hip.packet_fixed``      Reserved (``\\x00``)
   2          17   ``hip.type``              Packet Type
   3          24   ``hip.version``           Version
   3          28   ``hip.reserved``          Reserved
-  3          31                             Reserved (``\\x01``)
+  3          31   ``hip.version_fixed``     Reserved (``\\x01``)
   4          32   ``hip.chksum``            Checksum
   6          48   ``hip.control``           Controls
   8          64   ``hip.shit``              Sender's Host Identity Tag
@@ -300,6 +300,8 @@ class HIP(IPv6_Ext[Data_HIP, Schema_HIP], Internet[Data_HIP, Schema_HIP],
          - Parameter Parser
        * - :attr:`~pcapkit.const.hip.parameter.Parameter.ESP_INFO`
          - :meth:`~pcapkit.protocols.internet.hip.HIP._read_param_esp_info`
+       * - :attr:`~pcapkit.const.hip.parameter.Parameter.R1_Counter`
+         - :meth:`~pcapkit.protocols.internet.hip.HIP._read_param_r1_counter`
        * - :attr:`~pcapkit.const.hip.parameter.Parameter.R1_COUNTER`
          - :meth:`~pcapkit.protocols.internet.hip.HIP._read_param_r1_counter`
        * - :attr:`~pcapkit.const.hip.parameter.Parameter.LOCATOR_SET`
@@ -395,6 +397,20 @@ class HIP(IPv6_Ext[Data_HIP, Schema_HIP], Internet[Data_HIP, Schema_HIP],
        * - :attr:`~pcapkit.const.hip.parameter.Parameter.RELAY_HMAC`
          - :meth:`~pcapkit.protocols.internet.hip.HIP._read_param_relay_hmac`
 
+    .. versionchanged:: 1.5.0
+
+       * Parameters dispatch through :attr:`__parameter__` rather than by
+         method name (:issue:`429`).
+       * A parameter is padded to the record length :rfc:`7401` gives
+         (:issue:`651`), and ``PUZZLE``, ``SOLUTION``, ``R1_COUNTER`` and
+         ``LOCATOR_SET`` are sized as the RFCs give them (:issue:`608`,
+         :issue:`653` to :issue:`655`, :issue:`672`, :issue:`679`).
+       * A rebuild reproduces the Header Length, a packet with no parameters,
+         the ``PUZZLE`` lifetime, the reserved, padding and Locator flag bits,
+         and the two fixed header bits (:issue:`1313`, :issue:`1314`,
+         :issue:`1323`, :issue:`1328`, :issue:`1365`, :issue:`1417`,
+         :issue:`1459`).
+
     """
 
     ##########################################################################
@@ -3526,7 +3542,8 @@ def _make_param_solution(self, code: 'Enum_Parameter', param: 'Optional[Data_Sol
                 rewriting it, and to that mandated zero otherwise. Pass it
                 explicitly to override either -- notably to write the conformant
                 zero over a non-conformant one received from a peer, which is
-                otherwise unreachable because :class:`Data_SolutionParameter` is
+                otherwise unreachable because
+                :class:`~pcapkit.protocols.data.internet.hip.SolutionParameter` is
                 immutable
             opaque: opaque data
             random: random #I value
@@ -4996,6 +5013,7 @@ def _make_param_echo_response_unsigned(self, code: 'Enum_Parameter', param: 'Opt
             code: parameter code
             param: parameter data
             version: HIP protocol version
+            opaque: opaque data
 
         Returns:
             HIP parameter schema.

pcapkit/protocols/internet/hopopt.py

@@ -184,6 +184,19 @@ class HOPOPT(IPv6_Ext[Data_HOPOPT, Schema_HOPOPT],
          - :meth:`~pcapkit.protocols.internet.hopopt.HOPOPT._read_opt_ip_dff`
          - :meth:`~pcapkit.protocols.internet.hopopt.HOPOPT._make_opt_ip_dff`
 
+    .. versionchanged:: 1.5.0
+
+       * The ILNP nonce is sized with a ceiling rather than a floor
+         (:issue:`601`).
+       * The RPL option keeps its reserved flag bits on rebuild and accepts
+         :rfc:`6553` sub-TLVs (:issue:`1199`).
+       * A rebuild reproduces the option area byte for byte: its padding, a
+         PadN with no data, the SMF_DPD, CALIPSO, PDM and ILNP Nonce options,
+         and unassigned Quick-Start function codes (:issue:`1200`,
+         :issue:`1228`, :issue:`1229`, :issue:`1232` to :issue:`1234`,
+         :issue:`1237`); a CALIPSO option keeps its trailing pad and its
+         length (:issue:`1403`).
+
     """
 
     ##########################################################################

pcapkit/protocols/internet/internet.py

@@ -94,6 +94,12 @@ class Internet(ProtocolBase[_PT, _ST], Generic[_PT, _ST]):  # pylint: disable=ab
        * - :attr:`~pcapkit.const.reg.transtype.TransType.OSPFIGP`
          - :class:`pcapkit.protocols.application.ospf.OSPF`
 
+    .. versionchanged:: 1.5.0
+
+       A layer parsed as an IPv6 extension header keeps only its own octets in
+       :attr:`data`, so that ``from_data(info).data`` rebuilds it exactly
+       (:issue:`1446`).
+
     """
 
     ##########################################################################

pcapkit/protocols/internet/ip.py

@@ -29,7 +29,7 @@ class IP(Internet[_PT, _ST], Generic[_PT, _ST]):  # pylint: disable=abstract-met
     """Base class for the IP protocol family.
 
     - Internet Protocol version 4 (:class:`~pcapkit.protocols.internet.ipv4.IPv4`) [:rfc:`791`]
-    - Internet Protocol version 6 (:class:`~pcapkit.protocols.internet.ipv6.IPv6`) [:rfc:`2460`]
+    - Internet Protocol version 6 (:class:`~pcapkit.protocols.internet.ipv6.IPv6`) [:rfc:`8200`]
 
     The IPsec protocols (:class:`~pcapkit.protocols.internet.ah.AH` and
     :class:`~pcapkit.protocols.internet.esp.ESP`) derive from

pcapkit/protocols/internet/ipv4.py

@@ -13,25 +13,25 @@
 ======= ========= ====================== =============================================
 Octets      Bits        Name                    Description
 ======= ========= ====================== =============================================
-  0           0   ``ip.version``              Version (``4``)
-  0           4   ``ip.hdr_len``              Internal Header Length (IHL)
-  1           8   ``ip.tos.pre``              ToS Precedence
-  1          11   ``ip.tos.del``              ToS Delay
-  1          12   ``ip.tos.thr``              ToS Throughput
-  1          13   ``ip.tos.rel``              ToS Reliability
-  1          14   ``ip.tos.ecn``              Explicit Congestion Notification (ECN)
-  2          16   ``ip.len``                  Total Length
-  4          32   ``ip.id``                   Identification
-  6          48                               Reserved Bit (must be ``\\x00``)
-  6          49   ``ip.flags.df``             Don't Fragment (DF)
-  6          50   ``ip.flags.mf``             More Fragments (MF)
-  6          51   ``ip.offset``               Fragment Offset
-  8          64   ``ip.ttl``                  Time To Live (TTL)
-  9          72   ``ip.protocol``             Protocol (Transport Layer)
-  10         80   ``ip.checksum``             Header Checksum
-  12         96   ``ip.src``                  Source IP Address
-  16        128   ``ip.dst``                  Destination IP Address
-  20        160   ``ip.options``              IP Options (if IHL > ``5``)
+  0           0   ``ipv4.version``        Version (``4``)
+  0           4   ``ipv4.hdr_len``        Internet Header Length (IHL)
+  1           8   ``ipv4.tos.pre``        Precedence
+  1          11   ``ipv4.tos.del``        Delay
+  1          12   ``ipv4.tos.thr``        Throughput
+  1          13   ``ipv4.tos.rel``        Reliability
+  1          14   ``ipv4.tos.ecn``        Explicit Congestion Notification (ECN)
+  2          16   ``ipv4.len``            Total Length
+  4          32   ``ipv4.id``             Identification
+  6          48                           Reserved Bit (must be ``\\x00``)
+  6          49   ``ipv4.flags.df``       Don't Fragment (DF)
+  6          50   ``ipv4.flags.mf``       More Fragments (MF)
+  6          51   ``ipv4.offset``         Fragment Offset
+  8          64   ``ipv4.ttl``            Time To Live (TTL)
+  9          72   ``ipv4.protocol``       Protocol (Transport Layer)
+  10         80   ``ipv4.checksum``       Header Checksum
+  12         96   ``ipv4.src``            Source IP Address
+  16        128   ``ipv4.dst``            Destination IP Address
+  20        160   ``ipv4.options``        IP Options (if IHL > ``5``)
 ======= ========= ====================== =============================================
 
 .. [*] https://en.wikipedia.org/wiki/IPv4
@@ -186,6 +186,26 @@ class IPv4(IP[Data_IPv4, Schema_IPv4],
          - :meth:`~pcapkit.protocols.internet.ipv4.IPv4._read_opt_qs`
          - :meth:`~pcapkit.protocols.internet.ipv4.IPv4._make_opt_qs`
 
+    .. versionchanged:: 1.5.0
+
+       * Options dispatch through :attr:`__option__` rather than by method
+         name (:issue:`429`).
+       * A rebuild keeps the fragment offset in 8-octet units, and a header
+         without options rebuilds (:issue:`494`).
+       * A rebuild from :meth:`from_data` keeps the Total Length a truncated
+         capture declares (:issue:`1155`), and the octets past it as
+         :attr:`~pcapkit.protocols.schema.internet.ipv4.IPv4.trailer`
+         (:issue:`1209`).
+       * A header length declared past the data raises
+         :exc:`~pcapkit.utilities.exceptions.ProtocolError` on read
+         (:issue:`1404`).
+       * A rebuild reproduces the option area, the route and timestamp slots,
+         the SEC and TS fields and the reserved bits byte for byte
+         (:issue:`1316` to :issue:`1322`, :issue:`1326`, :issue:`1349`,
+         :issue:`1391` to :issue:`1393`).
+       * The TS option's maker takes an address as a string as well
+         (:issue:`1402`).
+
     """
 
     ##########################################################################
@@ -1665,6 +1685,8 @@ def _make_opt_ts(self, kind: 'Enum_OptionNumber', option: 'Optional[Data_TSOptio
             kind: option type code
             option: option data
             counts: maximum number of timestamps to record
+            overflow: overflow count, i.e. the number of modules that could not
+                register a timestamp (:rfc:`791#section-3.1`)
             timestamp: list of timestamps, i.e. the slots before the pointer, or
                 a mapping of the addresses to their timestamps; an address may
                 be anything :func:`~pcapkit.corekit.fields.ipaddress.parse_ip_address`