Skip to content

Commit caa1b04

Browse files
JarryShawJarryShaw
authored
feat(internet): implement ICMP and ICMPv6 under an abstract ICMP base (#2446)
1 parent c6b3848 commit caa1b04

78 files changed

Lines changed: 5295 additions & 74 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ its own parser.
5757
6
5858
>>> frame = extraction.frame[0]
5959
>>> str(frame.protochain)
60-
'Ethernet:IPv6:IPv6_ICMP'
60+
'Ethernet:IPv6:ICMPv6'
6161
>>> frame.info.time
6262
datetime.datetime(2017, 11, 19, 15, 49, 5, 471719, tzinfo=datetime.timezone.utc)
6363
>>> frame.payload.payload.src

‎docs/source/contributing/pep.rst‎

Lines changed: 30 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -41,20 +41,23 @@ one. Grouped by each TCP/IP layer and ordered by protocol name alphabetically,
4141
the ones outstanding are,
4242

4343
* Link Layer: DSL, EAPOL, FDDI, ISDN, NDP, PPP
44-
* Internet Layer: ECN, ICMP, ICMPv6, Shim6
44+
* Internet Layer: ECN, Shim6
4545
* Transport Layer: DCCP, RSVP
4646
* Application Layer: BGP, DHCP, DHCPv6, DNS, IMAP, LDAP, MQTT, NNTP,
4747
NTP, ONC/RPC, POP, QUIC, RIP, RTP, SIP, SMTP, SNMP, SSH, Telnet,
4848
XMPP
4949

5050
Several of these come in pairs that want a shared abstract base rather than two
5151
independent implementations, in the way
52-
:class:`~pcapkit.protocols.internet.ip.IP` already covers its family: ICMP
53-
with ICMPv6, and TLS/SSL with DTLS. **Done** for TLS/SSL with DTLS:
54-
:class:`~pcapkit.protocols.application.ssl.SSL` is the shared record-layer base
55-
of :class:`~pcapkit.protocols.application.tls.TLS` and
52+
:class:`~pcapkit.protocols.internet.ip.IP` and
53+
:class:`~pcapkit.protocols.internet.icmp.ICMP` already cover their families:
54+
IP and IPsec, and TLS/SSL with DTLS. **Done** for TLS/SSL
55+
with DTLS: :class:`~pcapkit.protocols.application.ssl.SSL` is the shared
56+
record-layer base of :class:`~pcapkit.protocols.application.tls.TLS` and
5657
:class:`~pcapkit.protocols.application.dtls.DTLS` -- see the `DTLS`_ section
57-
below.
58+
below. Neighbor Discovery (:rfc:`4861`, the ``NDP`` above) and Multicast
59+
Listener Discovery (:rfc:`9777`), both carried in ICMPv6, are not implemented,
60+
nor is ICMP/ICMPv6 checksum computation or verification (:issue:`2470`).
5861
:class:`~pcapkit.protocols.link.vlan.VLAN` is the closer precedent for a pair
5962
whose *layout* is identical -- it holds the whole of the tag, and
6063
:class:`~pcapkit.protocols.link.c_tag.C_Tag` and
@@ -362,8 +365,9 @@ Follow-ups to the bindings above:
362365
port number. That depends on the proxy identifying the version positively
363366
instead of guessing, since a guess path is wrong on non-HTTP input.
364367

365-
Beyond those, the gaps most likely to be met in a real capture are ICMP (1)
366-
and ICMPv6 (58) on the internet layer, each of which has a stub.
368+
**Done.** ICMP (1), ICMPv6 (58) and IGMP (2) -- the internet layer gaps most
369+
likely to be met in a real capture -- are all now implemented; ECN and Shim6
370+
above remain the open ones.
367371

368372
PCAPNG Support
369373
--------------
@@ -1082,11 +1086,19 @@ post-wave-1 consistency sweep described under `Release Plan — 1.5.0 in Two
10821086
Steps`_ above.
10831087

10841088
**Wave 2 — the protocol pairs that want a shared abstract base**, per `More
1085-
Protocols, More!!!`_ above: **ICMP with ICMPv6** and **TLS/SSL with DTLS**,
1086-
plus **IGMP** and **DCCP** on their own. These are grouped because the shared-base
1087-
question is the design work and doing either half of a pair alone would answer it
1088-
twice. **DCCP** is the transport-layer implementation, tracked by :issue:`2489`, and
1089-
blocked on :issue:`2479` for its pseudo-header checksum.
1089+
Protocols, More!!!`_ above: **TLS/SSL with DTLS** and **IGMP** and **DCCP** on
1090+
their own. These are grouped because the shared-base question is the design work
1091+
and doing either half of a pair alone would answer it twice. **DCCP** is the
1092+
transport-layer implementation, tracked by :issue:`2489`, and blocked on
1093+
:issue:`2479` for its pseudo-header checksum.
1094+
1095+
**Done within wave 2 — ICMP/ICMPv6 shared base.** :class:`~pcapkit.protocols.internet.icmp.ICMP`
1096+
is the abstract base :class:`~pcapkit.protocols.internet.icmpv4.ICMPv4` and
1097+
:class:`~pcapkit.protocols.internet.icmpv6.ICMPv6` share for selector composition
1098+
(:issue:`2436`); each implements its own message-type parsing independently rather than
1099+
through a shared method body. The two are distinguished by whether they carry pseudo-header
1100+
checksums (ICMPv6 does; ICMPv4 does not) and parse without checksum computation or verification
1101+
(:issue:`2470`).
10901102

10911103
**IGMP v1/v2 — done within wave 2** (:issue:`2439`).
10921104
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
11321144
is wanted instead of
11331145
:meth:`~pcapkit.protocols.protocol.Protocol._decode_next_layer`. It is
11341146
sequenced *after* wave 2 rather than by preference: the multicast options embed
1135-
:rfc:`3810` MLD, which rides in **ICMPv6**, and :rfc:`3376` **IGMPv3** group
1136-
records — ICMPv6 a wave 2 deliverable, IGMPv3 :issue:`2448`. Landing the
1147+
:rfc:`9777` MLD (which obsoletes :rfc:`3810`; :rfc:`2710` for MLDv1), which
1148+
rides in **ICMPv6**, and :rfc:`3376` **IGMPv3** group records. ICMPv6 and
1149+
IGMPv1/v2 are both wave 2 deliverables, now done; MLD itself remains a
1150+
follow-up to ICMPv6 (see `More Protocols, More!!!`_ above), and IGMPv3 is
1151+
:issue:`2448` -- neither is part of wave 2's own scope. Landing the
11371152
registry first would give a dispatch table with nothing but
11381153
:class:`~pcapkit.protocols.misc.raw.Raw` to register. The
11391154
counter-argument is real though, and worth weighing rather than dismissing: changing the

‎docs/source/demo.rst‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -72,8 +72,8 @@ Here are some usage samples:
7272
7373
$ pcapkit-cli in --auto-extension --format plist --verbose
7474
🚨 Loading file 'in.pcap'
75-
Frame 1: Ethernet:IPv6:IPv6_ICMP
76-
Frame 2: Ethernet:IPv6:IPv6_ICMP
75+
Frame 1: Ethernet:IPv6:ICMPv6
76+
Frame 2: Ethernet:IPv6:ICMPv6
7777
Frame 3: Ethernet:IPv4:TCP
7878
Frame 4: Ethernet:IPv4:TCP
7979
Frame 5: Ethernet:IPv4:TCP
@@ -93,8 +93,8 @@ Here are some usage samples:
9393
9494
$ pcapkit-cli in --auto-extension --output out.json --format json --verbose
9595
🚨 Loading file 'in.pcap'
96-
Frame 1: Ethernet:IPv6:IPv6_ICMP
97-
Frame 2: Ethernet:IPv6:IPv6_ICMP
96+
Frame 1: Ethernet:IPv6:ICMPv6
97+
Frame 2: Ethernet:IPv6:ICMPv6
9898
Frame 3: Ethernet:IPv4:TCP
9999
Frame 4: Ethernet:IPv4:TCP
100100
Frame 5: Ethernet:IPv4:TCP
@@ -107,8 +107,8 @@ Here are some usage samples:
107107
108108
$ pcapkit-cli in.pcap --output out.txt --format tree --verbose
109109
🚨 Loading file 'in.pcap'
110-
Frame 1: Ethernet:IPv6:IPv6_ICMP
111-
Frame 2: Ethernet:IPv6:IPv6_ICMP
110+
Frame 1: Ethernet:IPv6:ICMPv6
111+
Frame 2: Ethernet:IPv6:ICMPv6
112112
Frame 3: Ethernet:IPv4:TCP
113113
Frame 4: Ethernet:IPv4:TCP
114114
Frame 5: Ethernet:IPv4:TCP

‎docs/source/ext.rst‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,12 @@ The protocol classes :mod:`pcapkit` ships:
6868
+ + + +-------------------------------------------------------------+
6969
| | | | :class:`pcapkit.protocols.internet.esp.ESP` |
7070
+ +----------------+-----------------------+-------------------------------------------------------------+
71+
| | | :class:`pcapkit.protocols.internet.icmp.ICMP` |
72+
+ + +-----------------------+-------------------------------------------------------------+
73+
| | ICMP Family | :class:`pcapkit.protocols.internet.icmpv4.ICMPv4` |
74+
+ + +-----------------------+-------------------------------------------------------------+
75+
| | | :class:`pcapkit.protocols.internet.icmpv6.ICMPv6` |
76+
+ +----------------+-----------------------+-------------------------------------------------------------+
7177
| | :class:`pcapkit.protocols.internet.ipx.IPX` |
7278
+ +----------------+-----------------------+-------------------------------------------------------------+
7379
| | :class:`pcapkit.protocols.internet.hip.HIP` |
@@ -375,6 +381,10 @@ writes them:
375381
| | :class:`~pcapkit.protocols.internet.mh.MH` | :attr:`MH.__option__ <pcapkit.protocols.internet.mh.MH.__option__>` | :func:`~pcapkit.foundation.registry.protocols.register_mh_option` |
376382
+ + +-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+
377383
| | | :attr:`MH.__extension__ <pcapkit.protocols.internet.mh.MH.__extension__>` | :func:`~pcapkit.foundation.registry.protocols.register_mh_extension` |
384+
+ +------------------------------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+
385+
| | :class:`~pcapkit.protocols.internet.icmpv4.ICMPv4` | :attr:`ICMPv4.__type__ <pcapkit.protocols.internet.icmpv4.ICMPv4.__type__>` | :meth:`~pcapkit.protocols.internet.icmpv4.ICMPv4.register_type` |
386+
+ +------------------------------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+
387+
| | :class:`~pcapkit.protocols.internet.icmpv6.ICMPv6` | :attr:`ICMPv6.__type__ <pcapkit.protocols.internet.icmpv6.ICMPv6.__type__>` | :meth:`~pcapkit.protocols.internet.icmpv6.ICMPv6.register_type` |
378388
+-------------------+------------------------------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+
379389
| | | :attr:`TCP.__option__ <pcapkit.protocols.transport.tcp.TCP.__option__>` | :func:`~pcapkit.foundation.registry.protocols.register_tcp_option` |
380390
+ Transport Layer + :class:`~pcapkit.protocols.transport.tcp.TCP` +-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+

‎docs/source/pcapkit/const/icmp.rst‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
========================================================================
2+
:class:`~pcapkit.protocols.internet.icmpv4.ICMPv4` Constant Enumerations
3+
========================================================================
4+
5+
.. module:: pcapkit.const.icmp
6+
7+
This module contains all constant enumerations of
8+
:class:`~pcapkit.protocols.internet.icmpv4.ICMPv4` implementations. Available
9+
enumerations include:
10+
11+
.. list-table::
12+
13+
* - :class:`ICMP_Type <pcapkit.const.icmp.type.Type>`
14+
- ICMP Type Numbers [*]_
15+
* - :class:`ICMP_DestinationUnreachableCode <pcapkit.const.icmp.destination_unreachable_code.DestinationUnreachableCode>`
16+
- ICMP Destination Unreachable Codes [*]_
17+
* - :class:`ICMP_TimeExceededCode <pcapkit.const.icmp.time_exceeded_code.TimeExceededCode>`
18+
- ICMP Time Exceeded Codes [*]_
19+
* - :class:`ICMP_ParameterProblemCode <pcapkit.const.icmp.parameter_problem_code.ParameterProblemCode>`
20+
- ICMP Parameter Problem Codes [*]_
21+
22+
ICMP Type Numbers
23+
=================
24+
25+
.. module:: pcapkit.const.icmp.type
26+
27+
This module contains the constant enumeration for **ICMP Type Numbers**,
28+
which is automatically generated from :class:`pcapkit.vendor.icmp.type.Type`.
29+
30+
.. autoclass:: pcapkit.const.icmp.type.Type
31+
:members:
32+
:undoc-members:
33+
:show-inheritance:
34+
35+
ICMP Destination Unreachable Codes
36+
===================================
37+
38+
.. module:: pcapkit.const.icmp.destination_unreachable_code
39+
40+
This module contains the constant enumeration for **ICMP Destination
41+
Unreachable Codes**, which is automatically generated from
42+
:class:`pcapkit.vendor.icmp.destination_unreachable_code.DestinationUnreachableCode`.
43+
44+
.. autoclass:: pcapkit.const.icmp.destination_unreachable_code.DestinationUnreachableCode
45+
:members:
46+
:undoc-members:
47+
:show-inheritance:
48+
49+
ICMP Time Exceeded Codes
50+
=========================
51+
52+
.. module:: pcapkit.const.icmp.time_exceeded_code
53+
54+
This module contains the constant enumeration for **ICMP Time Exceeded
55+
Codes**, which is automatically generated from
56+
:class:`pcapkit.vendor.icmp.time_exceeded_code.TimeExceededCode`.
57+
58+
.. autoclass:: pcapkit.const.icmp.time_exceeded_code.TimeExceededCode
59+
:members:
60+
:undoc-members:
61+
:show-inheritance:
62+
63+
ICMP Parameter Problem Codes
64+
==============================
65+
66+
.. module:: pcapkit.const.icmp.parameter_problem_code
67+
68+
This module contains the constant enumeration for **ICMP Parameter Problem
69+
Codes**, which is automatically generated from
70+
:class:`pcapkit.vendor.icmp.parameter_problem_code.ParameterProblemCode`.
71+
72+
.. autoclass:: pcapkit.const.icmp.parameter_problem_code.ParameterProblemCode
73+
:members:
74+
:undoc-members:
75+
:show-inheritance:
76+
77+
.. rubric:: Footnotes
78+
79+
.. [*] https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xhtml#icmp-parameters-types
80+
.. [*] https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xhtml#icmp-parameters-codes
81+
.. [*] https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xhtml#icmp-parameters-codes
82+
.. [*] https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xhtml#icmp-parameters-codes

‎docs/source/pcapkit/const/icmpv6.rst‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
=========================================================================
2+
:class:`~pcapkit.protocols.internet.icmpv6.ICMPv6` Constant Enumerations
3+
=========================================================================
4+
5+
.. module:: pcapkit.const.icmpv6
6+
7+
This module contains all constant enumerations of
8+
:class:`~pcapkit.protocols.internet.icmpv6.ICMPv6` implementations. Available
9+
enumerations include:
10+
11+
.. list-table::
12+
13+
* - :class:`ICMPv6_Type <pcapkit.const.icmpv6.type.Type>`
14+
- ICMPv6 Type Numbers [*]_
15+
* - :class:`ICMPv6_DestinationUnreachableCode <pcapkit.const.icmpv6.destination_unreachable_code.DestinationUnreachableCode>`
16+
- ICMPv6 Destination Unreachable Codes [*]_
17+
* - :class:`ICMPv6_TimeExceededCode <pcapkit.const.icmpv6.time_exceeded_code.TimeExceededCode>`
18+
- ICMPv6 Time Exceeded Codes [*]_
19+
* - :class:`ICMPv6_ParameterProblemCode <pcapkit.const.icmpv6.parameter_problem_code.ParameterProblemCode>`
20+
- ICMPv6 Parameter Problem Codes [*]_
21+
22+
ICMPv6 Type Numbers
23+
====================
24+
25+
.. module:: pcapkit.const.icmpv6.type
26+
27+
This module contains the constant enumeration for **ICMPv6 Type Numbers**,
28+
which is automatically generated from :class:`pcapkit.vendor.icmpv6.type.Type`.
29+
30+
.. autoclass:: pcapkit.const.icmpv6.type.Type
31+
:members:
32+
:undoc-members:
33+
:show-inheritance:
34+
35+
ICMPv6 Destination Unreachable Codes
36+
======================================
37+
38+
.. module:: pcapkit.const.icmpv6.destination_unreachable_code
39+
40+
This module contains the constant enumeration for **ICMPv6 Destination
41+
Unreachable Codes**, which is automatically generated from
42+
:class:`pcapkit.vendor.icmpv6.destination_unreachable_code.DestinationUnreachableCode`.
43+
44+
.. autoclass:: pcapkit.const.icmpv6.destination_unreachable_code.DestinationUnreachableCode
45+
:members:
46+
:undoc-members:
47+
:show-inheritance:
48+
49+
ICMPv6 Time Exceeded Codes
50+
============================
51+
52+
.. module:: pcapkit.const.icmpv6.time_exceeded_code
53+
54+
This module contains the constant enumeration for **ICMPv6 Time Exceeded
55+
Codes**, which is automatically generated from
56+
:class:`pcapkit.vendor.icmpv6.time_exceeded_code.TimeExceededCode`.
57+
58+
.. autoclass:: pcapkit.const.icmpv6.time_exceeded_code.TimeExceededCode
59+
:members:
60+
:undoc-members:
61+
:show-inheritance:
62+
63+
ICMPv6 Parameter Problem Codes
64+
================================
65+
66+
.. module:: pcapkit.const.icmpv6.parameter_problem_code
67+
68+
This module contains the constant enumeration for **ICMPv6 Parameter
69+
Problem Codes**, which is automatically generated from
70+
:class:`pcapkit.vendor.icmpv6.parameter_problem_code.ParameterProblemCode`.
71+
72+
.. autoclass:: pcapkit.const.icmpv6.parameter_problem_code.ParameterProblemCode
73+
:members:
74+
:undoc-members:
75+
:show-inheritance:
76+
77+
.. rubric:: Footnotes
78+
79+
.. [*] https://www.iana.org/assignments/icmpv6-parameters/icmpv6-parameters.xhtml#icmpv6-parameters-types
80+
.. [*] https://www.iana.org/assignments/icmpv6-parameters/icmpv6-parameters.xhtml#icmpv6-parameters-type-1
81+
.. [*] https://www.iana.org/assignments/icmpv6-parameters/icmpv6-parameters.xhtml#icmpv6-parameters-type-3
82+
.. [*] https://www.iana.org/assignments/icmpv6-parameters/icmpv6-parameters.xhtml#icmpv6-parameters-type-4

‎docs/source/pcapkit/const/index.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,8 @@ Internet Layer
8080

8181
esp
8282
hip
83+
icmp
84+
icmpv6
8385
igmp
8486
ipv4
8587
ipv6

‎docs/source/pcapkit/foundation/registry.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,8 @@ Internet Layer Registries
9090

9191
.. autofunction:: pcapkit.foundation.registry.protocols.register_ipv4_option
9292

93+
.. autofunction:: pcapkit.foundation.registry.protocols.register_icmp_type
94+
9395
.. autofunction:: pcapkit.foundation.registry.protocols.register_hip_parameter
9496

9597
.. autofunction:: pcapkit.foundation.registry.protocols.register_hopopt_option

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

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,12 +83,16 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
8383
end
8484

8585
subgraph internet [Internet Layer]
86-
Internet --> IPX & IP & IPsec & IPv6_Ext & IGMP
86+
Internet --> IPX & IP & ICMP & IPsec & IPv6_Ext & IGMP
8787

8888
subgraph ip [IP Family]
8989
IP --> IPv4 & IPv6
9090
end
9191

92+
subgraph icmp [ICMP Family]
93+
ICMP --> ICMPv4 & ICMPv6
94+
end
95+
9296
subgraph ipsec [IPsec Family]
9397
IPsec --> AH & ESP
9498
end
@@ -143,6 +147,9 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
143147
click IGMPv1 "internet/igmpv1.html#pcapkit.protocols.internet.igmpv1.IGMP"
144148
click IGMPv2 "internet/igmpv2.html#pcapkit.protocols.internet.igmpv2.IGMP"
145149
click HOPOPT "internet/hopopt.html#pcapkit.protocols.internet.hopopt.HOPOPT"
150+
click ICMP "internet/icmp.html#pcapkit.protocols.internet.icmp.ICMP"
151+
click ICMPv4 "internet/icmpv4.html#pcapkit.protocols.internet.icmpv4.ICMPv4"
152+
click ICMPv6 "internet/icmpv6.html#pcapkit.protocols.internet.icmpv6.ICMPv6"
146153
click IP "internet/ip.html#pcapkit.protocols.internet.ip.IP"
147154
click IPsec "internet/ipsec.html#pcapkit.protocols.internet.ipsec.IPsec"
148155
click IPv4 "internet/ipv4.html#pcapkit.protocols.internet.ipv4.IPv4"

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

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
ICMP - Internet Control Message Protocol
2+
========================================
3+
4+
.. module:: pcapkit.protocols.internet.icmp
5+
6+
:mod:`pcapkit.protocols.internet.icmp` contains
7+
:class:`~pcapkit.protocols.internet.icmp.ICMP` only,
8+
which is a base class for Internet Control Message
9+
Protocol (ICMP) protocol family [*]_, e.g.
10+
:class:`~pcapkit.protocols.internet.icmpv4.ICMPv4` and
11+
:class:`~pcapkit.protocols.internet.icmpv6.ICMPv6`.
12+
13+
.. autoclass:: pcapkit.protocols.internet.icmp.ICMP
14+
:no-members:
15+
:show-inheritance:
16+
17+
.. automethod:: id
18+
19+
.. rubric:: Footnotes
20+
21+
.. [*] https://en.wikipedia.org/wiki/Internet_Control_Message_Protocol

0 commit comments

Comments
 (0)