docs(protocols): fourth whole-repo pass over internet (#1103)

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

@@ -5,7 +5,7 @@ AH - Authentication Header
 
 :mod:`pcapkit.protocols.internet.ah` contains
 :class:`~pcapkit.protocols.internet.ah.AH` only,
-which implements extractor for Authentication
+which implements the extractor for Authentication
 Header (AH) [*]_, whose structure is described
 as below:
 

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

@@ -5,7 +5,7 @@ ESP - Encapsulating Security Payload
 
 :mod:`pcapkit.protocols.internet.esp` contains
 :class:`~pcapkit.protocols.internet.esp.ESP`,
-which implements extractor for Encapsulating
+which implements the extractor for Encapsulating
 Security Payload (ESP) [*]_, and the security association, algorithm and
 status types documented below. The ESP structure is described as below:
 
@@ -132,6 +132,8 @@ are the same member. The registry spells the "no integrity algorithm"
 transform ``NONE`` rather than ``AUTH_NONE``, and :attr:`Integrity.NONE
 <pcapkit.const.esp.integrity.Integrity.NONE>` follows it.
 
+.. _esp-algorithm-support:
+
 Algorithm Support
 -----------------
 
@@ -206,6 +208,31 @@ MD5, DES-MAC, KPDK-MD5       MUST NOT            **no**       registered, delibe
 "MD5, DES-MAC, KPDK-MD5" above covers ``AUTH_HMAC_MD5_96``,
 ``AUTH_HMAC_MD5_128``, ``AUTH_DES_MAC`` and ``AUTH_KPDK_MD5``.
 
+Each implemented suite applies its algorithm with the parameters below, as
+:data:`~pcapkit.protocols.internet.esp.CIPHER_SUITES` and
+:data:`~pcapkit.protocols.internet.esp.INTEGRITY_SUITES` record them. Lengths
+and sizes are in octets.
+
+========================== =========== ============== ============== ============== ============== =============== =========================
+Encryption                 ``is_aead`` ``iv_length``  ``block_size`` ``icv_length`` ``key_sizes``  ``salt_length`` ``requires_cryptography``
+========================== =========== ============== ============== ============== ============== =============== =========================
+``ENCR_NULL``              no          0              1              0              0              0               no
+``ENCR_AES_CBC``           no          16             16             0              16, 24, 32     0               yes
+``ENCR_AES_GCM_8``         yes         8              1              8              16, 24, 32     4               yes
+``ENCR_AES_GCM_12``        yes         8              1              12             16, 24, 32     4               yes
+``ENCR_AES_GCM_16``        yes         8              1              16             16, 24, 32     4               yes
+========================== =========== ============== ============== ============== ============== =============== =========================
+
+========================== ============== ============== ==============
+Integrity                  ``digest``     ``icv_length`` ``key_size``
+========================== ============== ============== ==============
+``NONE``                   :data:`None`   0              0
+``AUTH_HMAC_SHA1_96``      ``sha1``       12             20
+``AUTH_HMAC_SHA2_256_128`` ``sha256``     16             32
+``AUTH_HMAC_SHA2_384_192`` ``sha384``     24             48
+``AUTH_HMAC_SHA2_512_256`` ``sha512``     32             64
+========================== ============== ============== ==============
+
 .. autoclass:: pcapkit.protocols.internet.esp.CipherSuite
    :members:
    :undoc-members:

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

@@ -5,7 +5,7 @@ HIP - Host Identity Protocol
 
 :mod:`pcapkit.protocols.internet.hip` contains
 :class:`~pcapkit.protocols.internet.hip.HIP` only,
-which implements extractor for Host Identity
+which implements the extractor for Host Identity
 Protocol (HIP) [*]_, whose structure is described
 as below:
 
@@ -14,11 +14,11 @@ Octets      Bits        Name                    Description
 ======= ========= ====================== ==================================
   0           0   ``hip.next``              Next Header
   1           8   ``hip.length``            Header Length
-  2          16   ``hip.packet_fixed``      Reserved (``\x00``)
+  2          16   ``hip.packet_fixed``      Fixed Bit (``0``)
   2          17   ``hip.type``              Packet Type
   3          24   ``hip.version``           Version
   3          28   ``hip.reserved``          Reserved
-  3          31   ``hip.version_fixed``     Reserved (``\x01``)
+  3          31   ``hip.version_fixed``     Fixed Bit (``1``)
   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

@@ -5,7 +5,7 @@ HOPOPT - IPv6 Hop-by-Hop Options
 
 :mod:`pcapkit.protocols.internet.hopopt` contains
 :class:`~pcapkit.protocols.internet.hopopt.HOPOPT`
-only, which implements extractor for IPv6 Hop-by-Hop
+only, which implements the extractor for IPv6 Hop-by-Hop
 Options header (HOPOPT) [*]_, whose structure is
 described as below:
 
@@ -148,18 +148,10 @@ Header Schemas
    :members:
    :show-inheritance:
 
-.. autoclass:: pcapkit.protocols.schema.internet.hopopt.RPLFlags
-   :members:
-   :show-inheritance:
-
 .. autoclass:: pcapkit.protocols.schema.internet.hopopt.MPLOption
    :members:
    :show-inheritance:
 
-.. autoclass:: pcapkit.protocols.schema.internet.hopopt.MPLFlags
-   :members:
-   :show-inheritance:
-
 .. autoclass:: pcapkit.protocols.schema.internet.hopopt.ILNPOption
    :members:
    :show-inheritance:
@@ -180,10 +172,6 @@ Header Schemas
    :members:
    :show-inheritance:
 
-.. autoclass:: pcapkit.protocols.schema.internet.hopopt.DFFFlags
-   :members:
-   :show-inheritance:
-
 Type Stubs
 ~~~~~~~~~~
 
@@ -196,17 +184,14 @@ Type Stubs
    :show-inheritance:
 
 .. autoclass:: pcapkit.protocols.schema.internet.hopopt.RPLFlags
-   :no-index:
    :members:
    :show-inheritance:
 
 .. autoclass:: pcapkit.protocols.schema.internet.hopopt.MPLFlags
-   :no-index:
    :members:
    :show-inheritance:
 
 .. autoclass:: pcapkit.protocols.schema.internet.hopopt.DFFFlags
-   :no-index:
    :members:
    :show-inheritance:
 

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

@@ -5,7 +5,7 @@ IPv4 - Internet Protocol version 4
 
 :mod:`pcapkit.protocols.internet.ipv4` contains
 :class:`~pcapkit.protocols.internet.ipv4.IPv4` only,
-which implements extractor for Internet Protocol
+which implements the extractor for Internet Protocol
 version 4 (IPv4) [*]_, whose structure is described
 as below:
 

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

@@ -5,7 +5,7 @@ IPv6 - Internet Protocol version 6
 
 :mod:`pcapkit.protocols.internet.ipv6` contains
 :class:`~pcapkit.protocols.internet.ipv6.IPv6` only,
-which implements extractor for Internet Protocol
+which implements the extractor for Internet Protocol
 version 6 (IPv6) [*]_, whose structure is described
 as below:
 

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

@@ -1,4 +1,4 @@
-IPv6_Ext - IPv6 Extension Header
+IPv6-Ext - IPv6 Extension Header
 ================================
 
 .. module:: pcapkit.protocols.internet.ipv6_ext
@@ -27,12 +27,9 @@ Octets      Bits        Name                    Description
 ======= ========= ===================== =====================================
 
 so those two octets are parseable without knowing anything else about the
-header. The module docstring in :file:`pcapkit/protocols/internet/ipv6_ext.py`
-holds the closed exception table (``IPv6-Frag`` and ``AH`` each use their own
-length rule; ``ESP`` has a dedicated parser whose own info reports no next header
-rather than lacking one, and ``253`` and ``254`` have no dedicated parser at all,
-so none of them ever reaches this class), the ways this class is
-dispatched to, and why an overrun stops the walk instead of clipping it.
+header. The sections below the class give the headers that depart from that
+rule, the ways this class is dispatched to, and why an overrun stops the walk
+instead of clipping it.
 
 .. autoclass:: pcapkit.protocols.internet.ipv6_ext.IPv6_Ext
    :no-members:
@@ -54,6 +51,127 @@ dispatched to, and why an overrun stops the walk instead of clipping it.
    .. automethod:: __post_init__
    .. automethod:: __index__
 
+.. _ipv6-ext-length-rules:
+
+Length Rules
+------------
+
+:rfc:`6564#section-5` is explicit that the generic layout is **not
+retroactive** -- it applies only to newly defined extension headers -- which is
+why the pre-existing headers need the closed exception table below rather than
+being assumed to conform. (:rfc:`8200#section-4.8` restates the layout without
+a MUST and mislabels the generic length field as the length of the Destination
+Options header; cite :rfc:`6564#section-4` instead.)
+
+The exception table, verified against IANA's ``protocol-numbers-1.csv``
+*IPv6 Extension Header* column and each cited RFC:
+
+===================================================================== =================================================
+Header(s)                                                             Length rule
+===================================================================== =================================================
+``HOPOPT``, ``IPv6-Route``, ``IPv6-Opts``, ``MH``, ``HIP``, ``Shim6`` ``(octet[1] + 1) * 8`` -- the :rfc:`6564`
+                                                                      generic rule
+``IPv6-Frag``                                                         constant ``8``; octet[1] is Reserved, not a
+                                                                      length (:rfc:`8200#section-4.5`)
+``AH``                                                                ``(octet[1] + 2) * 4`` -- :rfc:`4302#section-2.2`
+                                                                      counts in 4-octet units with a bias of 2,
+                                                                      not :rfc:`6564`'s 8-octet units and bias of 1
+``ESP``                                                               terminal -- has a dedicated, registered parser
+                                                                      (:class:`~pcapkit.protocols.internet.esp.ESP`),
+                                                                      but its Next Header byte is inside the
+                                                                      encrypted trailer (:rfc:`4303`), so the walk
+                                                                      cannot step past it on the wire
+``253``, ``254``                                                      terminal -- no dedicated parser exists, so no
+                                                                      next header field is ever read at all, either
+===================================================================== =================================================
+
+This table classifies by *wire format* alone, over every code
+:class:`~pcapkit.const.ipv6.extension_header.ExtensionHeader` enumerates,
+which match IANA's *IPv6 Extension Header Types* registry exactly
+(:issue:`925`).
+
+``Shim6`` conforms to the generic rule (:rfc:`5533`) but has no dedicated parser class; see
+:ref:`ipv6-ext-entry-paths` for how it reaches this class by direct dispatch.
+
+:rfc:`8200#section-4.5` sets Encapsulating Security Payload aside: ESP is not
+an extension header, and the RFC lists it among upper-layer headers.
+:rfc:`4303` puts its Next Header inside the encrypted trailer, with no length
+field in the cleartext part. 253 and 254 are reserved for private
+experimentation (:rfc:`3692`) with no wire format at all. None of them is
+reachable through this class, by construction; see
+:meth:`IPv6._import_next_layer
+<pcapkit.protocols.internet.ipv6.IPv6._import_next_layer>`. Each still enters
+:meth:`IPv6._decode_next_layer
+<pcapkit.protocols.internet.ipv6.IPv6._decode_next_layer>`'s walk, being a real
+:class:`~pcapkit.const.ipv6.extension_header.ExtensionHeader` member, but they
+part ways there. ``ESP`` resolves to its own dedicated parser, which decodes
+any plaintext it recovers itself and whose info carries a ``next`` of
+:data:`None` whenever the payload stays opaque, so the walk ends the ordinary
+way with ``ExtensionHeader(None)`` failing at the top of the next iteration.
+``253`` and ``254`` have no dedicated parser and resolve to plain
+:class:`~pcapkit.protocols.misc.raw.Raw`, whose info has no ``next``
+*attribute*. For these two, and any future IANA code without an
+implementation, the walk stops on a *structural* check (does the parsed layer
+carry a ``next`` at all?) rather than on a list of codes.
+
+.. _ipv6-ext-entry-paths:
+
+Entry Paths
+-----------
+
+This class is reached in these ways:
+
+1. **An unrecognised protocol number.**
+   :attr:`~pcapkit.const.ipv6.extension_header.ExtensionHeader.Shim6` is a real
+   IANA extension header (:rfc:`5533`) with no dedicated parser, so
+   :meth:`Internet._lookup_next_layer <pcapkit.protocols.internet.internet.Internet._lookup_next_layer>`
+   would default it to plain :class:`~pcapkit.protocols.misc.raw.Raw`. That
+   has no ``next`` field, so the walk in
+   :meth:`IPv6._decode_next_layer <pcapkit.protocols.internet.ipv6.IPv6._decode_next_layer>` would
+   crash on it (:issue:`891`). This module registers this class for that code
+   instead, at the bottom of the module, so dispatch reaches a working generic
+   parser directly. The registration is global, shared by every
+   :class:`~pcapkit.protocols.internet.internet.Internet` subclass, so
+   :meth:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.__post_init__` gates on ``version == 6`` to
+   keep it from also activating for an IPv4 payload that carries protocol
+   number 140; see its docstring.
+2. **A recognised header whose own parser raises.** ``HOPOPT``,
+   ``IPv6-Route``, ``IPv6-Opts``, ``MH``, ``HIP``, ``IPv6-Frag`` and ``AH`` all
+   have dedicated classes. When one of *those* raises,
+   :func:`~pcapkit.corekit.decorators.beholder`
+   (:meth:`Protocol._import_next_layer <pcapkit.protocols.protocol.ProtocolBase._import_next_layer>`)
+   would substitute plain :class:`~pcapkit.protocols.misc.raw.Raw`, which loses
+   ``next`` and crashes the walk as in path 1.
+   :meth:`IPv6._import_next_layer <pcapkit.protocols.internet.ipv6.IPv6._import_next_layer>` catches
+   the failure itself, one layer in from ``beholder``, and substitutes this
+   class: the bad header costs only itself, not the rest of the chain.
+
+.. _ipv6-ext-overrun-guard:
+
+The Overrun Guard
+-----------------
+
+The house convention for a declared length that does not fit what remains
+is warn-and-clip: emit a warning naming what was declared against what is
+left, then read only what is left. See
+:func:`pcapkit.protocols.schema.misc.pcapng.bounded_area` and
+:meth:`pcapkit.protocols.misc.pcapng.PCAPNG.read`.
+
+This class follows that convention's *warning*
+(:class:`~pcapkit.utilities.warnings.SchemaWarning`) and deliberately diverges
+on the *action*. Clipping is right when the declared length only governs how
+much of the current object to read, since there is always a well-defined
+"what is left" to fall back to. Here the declared length also decides *where
+the next header starts*; a clipped skip distance points at whatever bytes
+end the buffer, which are not a header. Continuing from there would
+fabricate a layer and record a false entry in
+:class:`~pcapkit.corekit.protochain.ProtoChain`, which reads as a parsed fact
+rather than a guess. So :meth:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.read` warns in the same
+wording as the sites above, then **stops the walk**: this instance absorbs
+every remaining octet and reports :data:`None` for ``next``, which the
+caller's loop already reads as "no more extension headers". The chain ends
+honestly at the bad header instead of inventing what follows it.
+
 Header Schemas
 --------------
 

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

@@ -5,7 +5,7 @@ IPv6-Frag - Fragment Header for IPv6
 
 :mod:`pcapkit.protocols.internet.ipv6_frag` contains
 :class:`~pcapkit.protocols.internet.ipv6_frag.IPv6_Frag`
-only, which implements extractor for Fragment Header for
+only, which implements the extractor for Fragment Header for
 IPv6 (IPv6-Frag) [*]_, whose structure is described as
 below:
 

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

@@ -5,7 +5,7 @@ IPv6-Opts - Destination Options for IPv6
 
 :mod:`pcapkit.protocols.internet.ipv6_opts` contains
 :class:`~pcapkit.protocols.internet.ipv6_opts.IPv6_Opts`
-only, which implements extractor for Destination Options
+only, which implements the extractor for Destination Options
 for IPv6 (IPv6-Opts) [*]_, whose structure is described
 as below:
 
@@ -148,18 +148,10 @@ Header Schemas
    :members:
    :show-inheritance:
 
-.. autoclass:: pcapkit.protocols.schema.internet.ipv6_opts.RPLFlags
-   :members:
-   :show-inheritance:
-
 .. autoclass:: pcapkit.protocols.schema.internet.ipv6_opts.MPLOption
    :members:
    :show-inheritance:
 
-.. autoclass:: pcapkit.protocols.schema.internet.ipv6_opts.MPLFlags
-   :members:
-   :show-inheritance:
-
 .. autoclass:: pcapkit.protocols.schema.internet.ipv6_opts.ILNPOption
    :members:
    :show-inheritance:
@@ -180,10 +172,6 @@ Header Schemas
    :members:
    :show-inheritance:
 
-.. autoclass:: pcapkit.protocols.schema.internet.ipv6_opts.DFFFlags
-   :members:
-   :show-inheritance:
-
 Type Stubs
 ~~~~~~~~~~
 
@@ -196,17 +184,14 @@ Type Stubs
    :show-inheritance:
 
 .. autoclass:: pcapkit.protocols.schema.internet.ipv6_opts.RPLFlags
-   :no-index:
    :members:
    :show-inheritance:
 
 .. autoclass:: pcapkit.protocols.schema.internet.ipv6_opts.MPLFlags
-   :no-index:
    :members:
    :show-inheritance:
 
 .. autoclass:: pcapkit.protocols.schema.internet.ipv6_opts.DFFFlags
-   :no-index:
    :members:
    :show-inheritance:
 

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

@@ -5,7 +5,7 @@ IPv6-Route - Routing Header for IPv6
 
 :mod:`pcapkit.protocols.internet.ipv6_route` contains
 :class:`~pcapkit.protocols.internet.ipv6_route.IPv6_Route`
-only, which implements extractor for Routing Header for IPv6
+only, which implements the extractor for Routing Header for IPv6
 (IPv6-Route) [*]_, whose structure is described as below:
 
 ======= ========= ==================== ===============================

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

@@ -5,7 +5,7 @@ IPX - Internetwork Packet Exchange
 
 :mod:`pcapkit.protocols.internet.ipx` contains
 :class:`~pcapkit.protocols.internet.ipx.IPX` only,
-which implements extractor for Internetwork Packet
+which implements the extractor for Internetwork Packet
 Exchange (IPX) [*]_, whose structure is described
 as below: