feat(internet): implement ICMP and ICMPv6 under an abstract ICMP base

README.md

@@ -57,7 +57,7 @@ its own parser.
 6
 >>> frame = extraction.frame[0]
 >>> str(frame.protochain)
-'Ethernet:IPv6:IPv6_ICMP'
+'Ethernet:IPv6:ICMPv6'
 >>> frame.info.time
 datetime.datetime(2017, 11, 19, 15, 49, 5, 471719, tzinfo=datetime.timezone.utc)
 >>> frame.payload.payload.src

docs/source/contributing/pep.rst

@@ -41,20 +41,23 @@ one. Grouped by each TCP/IP layer and ordered by protocol name alphabetically,
 the ones outstanding are,
 
 * Link Layer: DSL, EAPOL, FDDI, ISDN, NDP, PPP
-* Internet Layer: ECN, ICMP, ICMPv6, Shim6
+* Internet Layer: ECN, Shim6
 * Transport Layer: DCCP, RSVP
 * Application Layer: BGP, DHCP, DHCPv6, DNS, IMAP, LDAP, MQTT, NNTP,
   NTP, ONC/RPC, POP, QUIC, RIP, RTP, SIP, SMTP, SNMP, SSH, Telnet,
   XMPP
 
 Several of these come in pairs that want a shared abstract base rather than two
 independent implementations, in the way
-:class:`~pcapkit.protocols.internet.ip.IP` already covers its family: ICMP
-with ICMPv6, and TLS/SSL with DTLS. **Done** for TLS/SSL with DTLS:
-:class:`~pcapkit.protocols.application.ssl.SSL` is the shared record-layer base
-of :class:`~pcapkit.protocols.application.tls.TLS` and
+:class:`~pcapkit.protocols.internet.ip.IP` and
+:class:`~pcapkit.protocols.internet.icmp.ICMP` already cover their families:
+IP and IPsec, and TLS/SSL with DTLS. **Done** for TLS/SSL
+with DTLS: :class:`~pcapkit.protocols.application.ssl.SSL` is the shared
+record-layer base of :class:`~pcapkit.protocols.application.tls.TLS` and
 :class:`~pcapkit.protocols.application.dtls.DTLS` -- see the `DTLS`_ section
-below.
+below. Neighbor Discovery (:rfc:`4861`, the ``NDP`` above) and Multicast
+Listener Discovery (:rfc:`9777`), both carried in ICMPv6, are not implemented,
+nor is ICMP/ICMPv6 checksum computation or verification (:issue:`2470`).
 :class:`~pcapkit.protocols.link.vlan.VLAN` is the closer precedent for a pair
 whose *layout* is identical -- it holds the whole of the tag, and
 :class:`~pcapkit.protocols.link.c_tag.C_Tag` and
@@ -362,8 +365,9 @@ Follow-ups to the bindings above:
   port number. That depends on the proxy identifying the version positively
   instead of guessing, since a guess path is wrong on non-HTTP input.
 
-Beyond those, the gaps most likely to be met in a real capture are ICMP (1)
-and ICMPv6 (58) on the internet layer, each of which has a stub.
+**Done.** ICMP (1), ICMPv6 (58) and IGMP (2) -- the internet layer gaps most
+likely to be met in a real capture -- are all now implemented; ECN and Shim6
+above remain the open ones.
 
 PCAPNG Support
 --------------
@@ -1082,11 +1086,19 @@ post-wave-1 consistency sweep described under `Release Plan — 1.5.0 in Two
 Steps`_ above.
 
 **Wave 2 — the protocol pairs that want a shared abstract base**, per `More
-Protocols, More!!!`_ above: **ICMP with ICMPv6** and **TLS/SSL with DTLS**,
-plus **IGMP** and **DCCP** on their own. These are grouped because the shared-base
-question is the design work and doing either half of a pair alone would answer it
-twice. **DCCP** is the transport-layer implementation, tracked by :issue:`2489`, and
-blocked on :issue:`2479` for its pseudo-header checksum.
+Protocols, More!!!`_ above: **TLS/SSL with DTLS** and **IGMP** and **DCCP** on
+their own. These are grouped because the shared-base question is the design work
+and doing either half of a pair alone would answer it twice. **DCCP** is the
+transport-layer implementation, tracked by :issue:`2489`, and blocked on
+:issue:`2479` for its pseudo-header checksum.
+
+**Done within wave 2 — ICMP/ICMPv6 shared base.** :class:`~pcapkit.protocols.internet.icmp.ICMP`
+is the abstract base :class:`~pcapkit.protocols.internet.icmpv4.ICMPv4` and
+:class:`~pcapkit.protocols.internet.icmpv6.ICMPv6` share for selector composition
+(:issue:`2436`); each implements its own message-type parsing independently rather than
+through a shared method body. The two are distinguished by whether they carry pseudo-header
+checksums (ICMPv6 does; ICMPv4 does not) and parse without checksum computation or verification
+(:issue:`2470`).
 
 **IGMP v1/v2 — done within wave 2** (:issue:`2439`).
 The versioned classes :class:`IGMPv1 <pcapkit.protocols.internet.igmpv1.IGMP>` and
@@ -1132,8 +1144,11 @@ above, which describes the payloads in question and why a registry of their own
 is wanted instead of
 :meth:`~pcapkit.protocols.protocol.Protocol._decode_next_layer`. It is
 sequenced *after* wave 2 rather than by preference: the multicast options embed
-:rfc:`3810` MLD, which rides in **ICMPv6**, and :rfc:`3376` **IGMPv3** group
-records — ICMPv6 a wave 2 deliverable, IGMPv3 :issue:`2448`. Landing the
+:rfc:`9777` MLD (which obsoletes :rfc:`3810`; :rfc:`2710` for MLDv1), which
+rides in **ICMPv6**, and :rfc:`3376` **IGMPv3** group records. ICMPv6 and
+IGMPv1/v2 are both wave 2 deliverables, now done; MLD itself remains a
+follow-up to ICMPv6 (see `More Protocols, More!!!`_ above), and IGMPv3 is
+:issue:`2448` -- neither is part of wave 2's own scope. Landing the
 registry first would give a dispatch table with nothing but
 :class:`~pcapkit.protocols.misc.raw.Raw` to register. The
 counter-argument is real though, and worth weighing rather than dismissing: changing the

docs/source/demo.rst

@@ -72,8 +72,8 @@ Here are some usage samples:
 
       $ pcapkit-cli in --auto-extension --format plist --verbose
       🚨 Loading file 'in.pcap'
-      Frame   1: Ethernet:IPv6:IPv6_ICMP
-      Frame   2: Ethernet:IPv6:IPv6_ICMP
+      Frame   1: Ethernet:IPv6:ICMPv6
+      Frame   2: Ethernet:IPv6:ICMPv6
       Frame   3: Ethernet:IPv4:TCP
       Frame   4: Ethernet:IPv4:TCP
       Frame   5: Ethernet:IPv4:TCP
@@ -93,8 +93,8 @@ Here are some usage samples:
 
       $ pcapkit-cli in --auto-extension --output out.json --format json --verbose
       🚨 Loading file 'in.pcap'
-      Frame   1: Ethernet:IPv6:IPv6_ICMP
-      Frame   2: Ethernet:IPv6:IPv6_ICMP
+      Frame   1: Ethernet:IPv6:ICMPv6
+      Frame   2: Ethernet:IPv6:ICMPv6
       Frame   3: Ethernet:IPv4:TCP
       Frame   4: Ethernet:IPv4:TCP
       Frame   5: Ethernet:IPv4:TCP
@@ -107,8 +107,8 @@ Here are some usage samples:
 
       $ pcapkit-cli in.pcap --output out.txt --format tree --verbose
       🚨 Loading file 'in.pcap'
-      Frame   1: Ethernet:IPv6:IPv6_ICMP
-      Frame   2: Ethernet:IPv6:IPv6_ICMP
+      Frame   1: Ethernet:IPv6:ICMPv6
+      Frame   2: Ethernet:IPv6:ICMPv6
       Frame   3: Ethernet:IPv4:TCP
       Frame   4: Ethernet:IPv4:TCP
       Frame   5: Ethernet:IPv4:TCP

docs/source/ext.rst

@@ -68,6 +68,12 @@ The protocol classes :mod:`pcapkit` ships:
 +                                                                  +                +                       +-------------------------------------------------------------+
 |                                                                  |                |                       | :class:`pcapkit.protocols.internet.esp.ESP`                 |
 +                                                                  +----------------+-----------------------+-------------------------------------------------------------+
+|                                                                  |                | :class:`pcapkit.protocols.internet.icmp.ICMP`                                       |
++                                                                  +                +-----------------------+-------------------------------------------------------------+
+|                                                                  | ICMP Family    | :class:`pcapkit.protocols.internet.icmpv4.ICMPv4`                                   |
++                                                                  +                +-----------------------+-------------------------------------------------------------+
+|                                                                  |                | :class:`pcapkit.protocols.internet.icmpv6.ICMPv6`                                   |
++                                                                  +----------------+-----------------------+-------------------------------------------------------------+
 |                                                                  | :class:`pcapkit.protocols.internet.ipx.IPX`                                                          |
 +                                                                  +----------------+-----------------------+-------------------------------------------------------------+
 |                                                                  | :class:`pcapkit.protocols.internet.hip.HIP`                                                          |
@@ -375,6 +381,10 @@ writes them:
 |                   | :class:`~pcapkit.protocols.internet.mh.MH`                 | :attr:`MH.__option__ <pcapkit.protocols.internet.mh.MH.__option__>`                           | :func:`~pcapkit.foundation.registry.protocols.register_mh_option`          |
 +                   +                                                            +-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+
 |                   |                                                            | :attr:`MH.__extension__ <pcapkit.protocols.internet.mh.MH.__extension__>`                     | :func:`~pcapkit.foundation.registry.protocols.register_mh_extension`       |
++                   +------------------------------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+
+|                   | :class:`~pcapkit.protocols.internet.icmpv4.ICMPv4`         | :attr:`ICMPv4.__type__ <pcapkit.protocols.internet.icmpv4.ICMPv4.__type__>`                   | :meth:`~pcapkit.protocols.internet.icmpv4.ICMPv4.register_type`            |
++                   +------------------------------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+
+|                   | :class:`~pcapkit.protocols.internet.icmpv6.ICMPv6`         | :attr:`ICMPv6.__type__ <pcapkit.protocols.internet.icmpv6.ICMPv6.__type__>`                   | :meth:`~pcapkit.protocols.internet.icmpv6.ICMPv6.register_type`            |
 +-------------------+------------------------------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+
 |                   |                                                            | :attr:`TCP.__option__ <pcapkit.protocols.transport.tcp.TCP.__option__>`                       | :func:`~pcapkit.foundation.registry.protocols.register_tcp_option`         |
 + Transport Layer   + :class:`~pcapkit.protocols.transport.tcp.TCP`              +-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+

docs/source/pcapkit/const/icmp.rst

@@ -0,0 +1,82 @@
+========================================================================
+:class:`~pcapkit.protocols.internet.icmpv4.ICMPv4` Constant Enumerations
+========================================================================
+
+.. module:: pcapkit.const.icmp
+
+This module contains all constant enumerations of
+:class:`~pcapkit.protocols.internet.icmpv4.ICMPv4` implementations. Available
+enumerations include:
+
+.. list-table::
+
+   * - :class:`ICMP_Type <pcapkit.const.icmp.type.Type>`
+     - ICMP Type Numbers [*]_
+   * - :class:`ICMP_DestinationUnreachableCode <pcapkit.const.icmp.destination_unreachable_code.DestinationUnreachableCode>`
+     - ICMP Destination Unreachable Codes [*]_
+   * - :class:`ICMP_TimeExceededCode <pcapkit.const.icmp.time_exceeded_code.TimeExceededCode>`
+     - ICMP Time Exceeded Codes [*]_
+   * - :class:`ICMP_ParameterProblemCode <pcapkit.const.icmp.parameter_problem_code.ParameterProblemCode>`
+     - ICMP Parameter Problem Codes [*]_
+
+ICMP Type Numbers
+=================
+
+.. module:: pcapkit.const.icmp.type
+
+This module contains the constant enumeration for **ICMP Type Numbers**,
+which is automatically generated from :class:`pcapkit.vendor.icmp.type.Type`.
+
+.. autoclass:: pcapkit.const.icmp.type.Type
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ICMP Destination Unreachable Codes
+===================================
+
+.. module:: pcapkit.const.icmp.destination_unreachable_code
+
+This module contains the constant enumeration for **ICMP Destination
+Unreachable Codes**, which is automatically generated from
+:class:`pcapkit.vendor.icmp.destination_unreachable_code.DestinationUnreachableCode`.
+
+.. autoclass:: pcapkit.const.icmp.destination_unreachable_code.DestinationUnreachableCode
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ICMP Time Exceeded Codes
+=========================
+
+.. module:: pcapkit.const.icmp.time_exceeded_code
+
+This module contains the constant enumeration for **ICMP Time Exceeded
+Codes**, which is automatically generated from
+:class:`pcapkit.vendor.icmp.time_exceeded_code.TimeExceededCode`.
+
+.. autoclass:: pcapkit.const.icmp.time_exceeded_code.TimeExceededCode
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ICMP Parameter Problem Codes
+==============================
+
+.. module:: pcapkit.const.icmp.parameter_problem_code
+
+This module contains the constant enumeration for **ICMP Parameter Problem
+Codes**, which is automatically generated from
+:class:`pcapkit.vendor.icmp.parameter_problem_code.ParameterProblemCode`.
+
+.. autoclass:: pcapkit.const.icmp.parameter_problem_code.ParameterProblemCode
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. rubric:: Footnotes
+
+.. [*] https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xhtml#icmp-parameters-types
+.. [*] https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xhtml#icmp-parameters-codes
+.. [*] https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xhtml#icmp-parameters-codes
+.. [*] https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xhtml#icmp-parameters-codes

docs/source/pcapkit/const/icmpv6.rst

@@ -0,0 +1,82 @@
+=========================================================================
+:class:`~pcapkit.protocols.internet.icmpv6.ICMPv6` Constant Enumerations
+=========================================================================
+
+.. module:: pcapkit.const.icmpv6
+
+This module contains all constant enumerations of
+:class:`~pcapkit.protocols.internet.icmpv6.ICMPv6` implementations. Available
+enumerations include:
+
+.. list-table::
+
+   * - :class:`ICMPv6_Type <pcapkit.const.icmpv6.type.Type>`
+     - ICMPv6 Type Numbers [*]_
+   * - :class:`ICMPv6_DestinationUnreachableCode <pcapkit.const.icmpv6.destination_unreachable_code.DestinationUnreachableCode>`
+     - ICMPv6 Destination Unreachable Codes [*]_
+   * - :class:`ICMPv6_TimeExceededCode <pcapkit.const.icmpv6.time_exceeded_code.TimeExceededCode>`
+     - ICMPv6 Time Exceeded Codes [*]_
+   * - :class:`ICMPv6_ParameterProblemCode <pcapkit.const.icmpv6.parameter_problem_code.ParameterProblemCode>`
+     - ICMPv6 Parameter Problem Codes [*]_
+
+ICMPv6 Type Numbers
+====================
+
+.. module:: pcapkit.const.icmpv6.type
+
+This module contains the constant enumeration for **ICMPv6 Type Numbers**,
+which is automatically generated from :class:`pcapkit.vendor.icmpv6.type.Type`.
+
+.. autoclass:: pcapkit.const.icmpv6.type.Type
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ICMPv6 Destination Unreachable Codes
+======================================
+
+.. module:: pcapkit.const.icmpv6.destination_unreachable_code
+
+This module contains the constant enumeration for **ICMPv6 Destination
+Unreachable Codes**, which is automatically generated from
+:class:`pcapkit.vendor.icmpv6.destination_unreachable_code.DestinationUnreachableCode`.
+
+.. autoclass:: pcapkit.const.icmpv6.destination_unreachable_code.DestinationUnreachableCode
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ICMPv6 Time Exceeded Codes
+============================
+
+.. module:: pcapkit.const.icmpv6.time_exceeded_code
+
+This module contains the constant enumeration for **ICMPv6 Time Exceeded
+Codes**, which is automatically generated from
+:class:`pcapkit.vendor.icmpv6.time_exceeded_code.TimeExceededCode`.
+
+.. autoclass:: pcapkit.const.icmpv6.time_exceeded_code.TimeExceededCode
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ICMPv6 Parameter Problem Codes
+================================
+
+.. module:: pcapkit.const.icmpv6.parameter_problem_code
+
+This module contains the constant enumeration for **ICMPv6 Parameter
+Problem Codes**, which is automatically generated from
+:class:`pcapkit.vendor.icmpv6.parameter_problem_code.ParameterProblemCode`.
+
+.. autoclass:: pcapkit.const.icmpv6.parameter_problem_code.ParameterProblemCode
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. rubric:: Footnotes
+
+.. [*] https://www.iana.org/assignments/icmpv6-parameters/icmpv6-parameters.xhtml#icmpv6-parameters-types
+.. [*] https://www.iana.org/assignments/icmpv6-parameters/icmpv6-parameters.xhtml#icmpv6-parameters-type-1
+.. [*] https://www.iana.org/assignments/icmpv6-parameters/icmpv6-parameters.xhtml#icmpv6-parameters-type-3
+.. [*] https://www.iana.org/assignments/icmpv6-parameters/icmpv6-parameters.xhtml#icmpv6-parameters-type-4

docs/source/pcapkit/const/index.rst

@@ -80,6 +80,8 @@ Internet Layer
 
    esp
    hip
+   icmp
+   icmpv6
    igmp
    ipv4
    ipv6

docs/source/pcapkit/foundation/registry.rst

@@ -90,6 +90,8 @@ Internet Layer Registries
 
 .. autofunction:: pcapkit.foundation.registry.protocols.register_ipv4_option
 
+.. autofunction:: pcapkit.foundation.registry.protocols.register_icmp_type
+
 .. autofunction:: pcapkit.foundation.registry.protocols.register_hip_parameter
 
 .. autofunction:: pcapkit.foundation.registry.protocols.register_hopopt_option

docs/source/pcapkit/protocols/index.rst

@@ -83,12 +83,16 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
        end
 
        subgraph internet [Internet Layer]
-           Internet --> IPX & IP & IPsec & IPv6_Ext & IGMP
+           Internet --> IPX & IP & ICMP & IPsec & IPv6_Ext & IGMP
 
            subgraph ip [IP Family]
                IP --> IPv4 & IPv6
            end
 
+           subgraph icmp [ICMP Family]
+               ICMP --> ICMPv4 & ICMPv6
+           end
+
            subgraph ipsec [IPsec Family]
                IPsec --> AH & ESP
            end
@@ -143,6 +147,9 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
        click IGMPv1 "internet/igmpv1.html#pcapkit.protocols.internet.igmpv1.IGMP"
        click IGMPv2 "internet/igmpv2.html#pcapkit.protocols.internet.igmpv2.IGMP"
        click HOPOPT "internet/hopopt.html#pcapkit.protocols.internet.hopopt.HOPOPT"
+       click ICMP "internet/icmp.html#pcapkit.protocols.internet.icmp.ICMP"
+       click ICMPv4 "internet/icmpv4.html#pcapkit.protocols.internet.icmpv4.ICMPv4"
+       click ICMPv6 "internet/icmpv6.html#pcapkit.protocols.internet.icmpv6.ICMPv6"
        click IP "internet/ip.html#pcapkit.protocols.internet.ip.IP"
        click IPsec "internet/ipsec.html#pcapkit.protocols.internet.ipsec.IPsec"
        click IPv4 "internet/ipv4.html#pcapkit.protocols.internet.ipv4.IPv4"

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

@@ -0,0 +1,21 @@
+ICMP - Internet Control Message Protocol
+========================================
+
+.. module:: pcapkit.protocols.internet.icmp
+
+:mod:`pcapkit.protocols.internet.icmp` contains
+:class:`~pcapkit.protocols.internet.icmp.ICMP` only,
+which is a base class for Internet Control Message
+Protocol (ICMP) protocol family [*]_, e.g.
+:class:`~pcapkit.protocols.internet.icmpv4.ICMPv4` and
+:class:`~pcapkit.protocols.internet.icmpv6.ICMPv6`.
+
+.. autoclass:: pcapkit.protocols.internet.icmp.ICMP
+   :no-members:
+   :show-inheritance:
+
+   .. automethod:: id
+
+.. rubric:: Footnotes
+
+.. [*] https://en.wikipedia.org/wiki/Internet_Control_Message_Protocol