netprotocols 1.0.1__tar.gz → 1.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. {netprotocols-1.0.1 → netprotocols-1.1.0}/ARCHITECTURE.md +15 -0
  2. {netprotocols-1.0.1 → netprotocols-1.1.0}/CHANGELOG.md +25 -0
  3. {netprotocols-1.0.1 → netprotocols-1.1.0}/PKG-INFO +9 -9
  4. {netprotocols-1.0.1 → netprotocols-1.1.0}/README.md +8 -8
  5. {netprotocols-1.0.1 → netprotocols-1.1.0}/pyproject.toml +2 -1
  6. {netprotocols-1.0.1 → netprotocols-1.1.0}/scripts/capture_fixtures_supplement.sh +0 -0
  7. {netprotocols-1.0.1 → netprotocols-1.1.0}/scripts/check_fixtures.py +6 -3
  8. {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/__init__.py +15 -1
  9. {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/_enums.py +8 -0
  10. netprotocols-1.1.0/src/netprotocols/checksum.py +158 -0
  11. netprotocols-1.1.0/src/netprotocols/layer3/__init__.py +19 -0
  12. {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/layer3/ip.py +32 -4
  13. netprotocols-1.1.0/src/netprotocols/layer3/ipv6_ext.py +253 -0
  14. netprotocols-1.1.0/src/netprotocols/packet.py +88 -0
  15. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/MANIFEST.md +15 -13
  16. netprotocols-1.1.0/tests/fixtures/ipv6_fragments.pcap +0 -0
  17. netprotocols-1.1.0/tests/fixtures/ipv6_mld.pcap +0 -0
  18. netprotocols-1.1.0/tests/fixtures/staging/ipv6_fragments.pcap +0 -0
  19. netprotocols-1.1.0/tests/fixtures/staging/ipv6_mld.pcap +0 -0
  20. netprotocols-1.1.0/tests/test_checksum.py +239 -0
  21. netprotocols-1.1.0/tests/test_fuzz.py +182 -0
  22. netprotocols-1.1.0/tests/test_ipv6_ext.py +177 -0
  23. {netprotocols-1.0.1 → netprotocols-1.1.0}/uv.lock +84 -1
  24. netprotocols-1.0.1/src/netprotocols/layer3/__init__.py +0 -4
  25. netprotocols-1.0.1/src/netprotocols/packet.py +0 -48
  26. {netprotocols-1.0.1 → netprotocols-1.1.0}/.github/workflows/ci.yml +0 -0
  27. {netprotocols-1.0.1 → netprotocols-1.1.0}/.github/workflows/release.yml +0 -0
  28. {netprotocols-1.0.1 → netprotocols-1.1.0}/.gitignore +0 -0
  29. {netprotocols-1.0.1 → netprotocols-1.1.0}/LICENSE +0 -0
  30. {netprotocols-1.0.1 → netprotocols-1.1.0}/scripts/capture_fixtures.sh +0 -0
  31. {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/_base.py +0 -0
  32. {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/layer2/__init__.py +0 -0
  33. {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/layer2/arp.py +0 -0
  34. {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/layer2/ethernet.py +0 -0
  35. {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/layer3/icmp.py +0 -0
  36. {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/layer4/__init__.py +0 -0
  37. {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/layer4/tcp.py +0 -0
  38. {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/layer4/udp.py +0 -0
  39. {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/py.typed +0 -0
  40. {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/utils/__init__.py +0 -0
  41. {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/utils/exceptions.py +0 -0
  42. {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/utils/ipv4.py +0 -0
  43. {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/utils/mac.py +0 -0
  44. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/conftest.py +0 -0
  45. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/arp_exchange.pcap +0 -0
  46. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/icmpv4_echo_lo.pcap +0 -0
  47. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/icmpv4_external.pcap +0 -0
  48. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/icmpv4_ttl_exceeded.pcap +0 -0
  49. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/icmpv6_echo_lo.pcap +0 -0
  50. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/ipv4_fragments.pcap +0 -0
  51. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/ipv6_ndp_mld.pcap +0 -0
  52. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/staging/arp_exchange.pcap +0 -0
  53. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/staging/icmpv4_echo_lo.pcap +0 -0
  54. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/staging/icmpv4_external.pcap +0 -0
  55. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/staging/icmpv4_ttl_exceeded.pcap +0 -0
  56. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/staging/icmpv6_echo_lo.pcap +0 -0
  57. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/staging/ipv4_fragments.pcap +0 -0
  58. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/staging/ipv6_ndp_mld.pcap +0 -0
  59. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/staging/tcp_http.pcap +0 -0
  60. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/staging/tcp_https.pcap +0 -0
  61. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/staging/udp_dns.pcap +0 -0
  62. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/tcp_http.pcap +0 -0
  63. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/tcp_https.pcap +0 -0
  64. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/udp_dns.pcap +0 -0
  65. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/test_arp.py +0 -0
  66. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/test_contract.py +0 -0
  67. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/test_corpus.py +0 -0
  68. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/test_ethernet.py +0 -0
  69. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/test_icmp.py +0 -0
  70. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/test_ip.py +0 -0
  71. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/test_packet.py +0 -0
  72. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/test_tcp.py +0 -0
  73. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/test_udp.py +0 -0
  74. {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/test_utils.py +0 -0
@@ -115,8 +115,23 @@ flowchart LR
115
115
  I6 -->|58| IC6[ICMPv6]
116
116
  I6 -->|6| T
117
117
  I6 -->|17| U
118
+ I6 -->|0, 43, 44, 60| X[IPv6 extension headers]
119
+ X --> X
120
+ X -->|58| IC6
121
+ X -->|6| T
122
+ X -->|17| U
118
123
  ```
119
124
 
125
+ IPv6 extension headers (Hop-by-Hop Options, Routing, Fragment,
126
+ Destination Options) chain like any other protocol — each names what
127
+ follows via `next_header` — and may stack. Two guardrails: the
128
+ registry hands them out only inside an IPv6 chain (a garbage IPv4
129
+ packet with `protocol=0` cannot conjure a Hop-by-Hop layer), and a
130
+ Fragment header chains onward only when `fragment_offset == 0` — a
131
+ non-first fragment carries a slice from the middle of the original
132
+ payload, so no upper-layer header exists at its start. The same
133
+ offset rule applies to fragmented IPv4.
134
+
120
135
  The numbers on the arrows are the wire values — EtherTypes out of
121
136
  Ethernet, IP protocol numbers out of IPv4/IPv6 — and they live in
122
137
  [`_enums.py`](src/netprotocols/_enums.py) as `EtherType` and
@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [1.1.0] - 2026-08-29
9
+
10
+ ### Added
11
+ - **IPv6 extension headers** (RFC 8200 §4.3-4.6): `IPv6HopByHopOptions`,
12
+ `IPv6Routing`, `IPv6Fragment`, `IPv6DestinationOptions`. The decode
13
+ chain now reaches ICMPv6/TCP/UDP behind them (MLD reports decode
14
+ fully). Extension headers dispatch only inside an IPv6 chain, and a
15
+ Fragment header chains onward only from the first fragment.
16
+ - **Checksums** (`netprotocols.checksum`): `internet_checksum()`
17
+ (RFC 1071), `compute()`/`verify()` covering the IPv4 header checksum,
18
+ ICMPv4, and TCP/UDP/ICMPv6 with IPv4/IPv6 pseudo-headers, and
19
+ `Packet.with_checksums()` for filling a whole stack on encode. The
20
+ UDP-only zero substitution is confined to the UDP arm.
21
+ - **Property-based fuzzing** of the decode path (hypothesis, dev-only):
22
+ decode() raises nothing outside `ProtocolError` for any input; the
23
+ chain walk never consumes past the frame; constrained round trips.
24
+ - `IPProtocol` gains `HOPOPT`, `IPV6_ROUTE`, `IPV6_FRAG`,
25
+ `IPV6_DSTOPTS` with display names.
26
+
27
+ ### Development
28
+ - The real-capture fixture corpus grew to 65 frames across 12
29
+ scenarios (MLD behind hop-by-hop, IPv6 fragment pairs); checksum
30
+ tests recompute every verifiable corpus frame to its captured wire
31
+ value.
32
+
8
33
  ## [1.0.1] - 2026-08-29
9
34
 
10
35
  ### Fixed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: netprotocols
3
- Version: 1.0.1
3
+ Version: 1.1.0
4
4
  Summary: Low-level implementations of common networking protocols
5
5
  Project-URL: Homepage, https://github.com/EONRaider/NETProtocols
6
6
  Project-URL: Repository, https://github.com/EONRaider/NETProtocols
@@ -67,7 +67,11 @@ Requires Python 3.12+. Fully typed (`py.typed`, mypy strict).
67
67
  | 2 | Ethernet II | `Ethernet` | IEEE 802.3 |
68
68
  | 2 | ARP | `ARP` | RFC 826, IPv4-over-Ethernet binding |
69
69
  | 3 | IPv4 | `IPv4` | RFC 791, IHL/options aware |
70
- | 3 | IPv6 | `IPv6` | RFC 8200, fixed header |
70
+ | 3 | IPv6 | `IPv6` | RFC 8200 |
71
+ | 3 | IPv6 Hop-by-Hop Options | `IPv6HopByHopOptions` | RFC 8200 §4.3 |
72
+ | 3 | IPv6 Routing | `IPv6Routing` | RFC 8200 §4.4 |
73
+ | 3 | IPv6 Fragment | `IPv6Fragment` | RFC 8200 §4.5, first-fragment chaining |
74
+ | 3 | IPv6 Destination Options | `IPv6DestinationOptions` | RFC 8200 §4.6 |
71
75
  | 3 | ICMPv4 | `ICMPv4` | RFC 792, 8-byte header |
72
76
  | 3 | ICMPv6 | `ICMPv6` | RFC 4443, 8-byte header |
73
77
  | 4 | TCP | `TCP` | RFC 9293, data-offset/options aware |
@@ -127,8 +131,9 @@ frame = Packet(
127
131
  raw = bytes(frame) # ready for a raw socket
128
132
  ```
129
133
 
130
- Checksums are carried verbatim in both directions: the library neither
131
- computes nor verifies them (planned — see the roadmap).
134
+ Checksums are computed and verified on request — never silently:
135
+ `compute()`/`verify()` in `netprotocols.checksum`, and
136
+ `Packet.with_checksums()` to fill a whole stack before sending.
132
137
 
133
138
  ## Display helpers
134
139
 
@@ -150,12 +155,7 @@ network traffic monitor built on it.
150
155
 
151
156
  ## Roadmap
152
157
 
153
- - IPv6 extension headers (hop-by-hop, routing, fragment, destination
154
- options) — today the decode chain ends at `IPv6` for traffic behind
155
- them (e.g. MLD).
156
158
  - 802.1Q VLAN tags, DNS, DHCP, IGMP, GRE.
157
- - Checksum computation on encode and verification flags on decode.
158
- - Fuzzing of the decode path.
159
159
 
160
160
  ## Contributing
161
161
 
@@ -42,7 +42,11 @@ Requires Python 3.12+. Fully typed (`py.typed`, mypy strict).
42
42
  | 2 | Ethernet II | `Ethernet` | IEEE 802.3 |
43
43
  | 2 | ARP | `ARP` | RFC 826, IPv4-over-Ethernet binding |
44
44
  | 3 | IPv4 | `IPv4` | RFC 791, IHL/options aware |
45
- | 3 | IPv6 | `IPv6` | RFC 8200, fixed header |
45
+ | 3 | IPv6 | `IPv6` | RFC 8200 |
46
+ | 3 | IPv6 Hop-by-Hop Options | `IPv6HopByHopOptions` | RFC 8200 §4.3 |
47
+ | 3 | IPv6 Routing | `IPv6Routing` | RFC 8200 §4.4 |
48
+ | 3 | IPv6 Fragment | `IPv6Fragment` | RFC 8200 §4.5, first-fragment chaining |
49
+ | 3 | IPv6 Destination Options | `IPv6DestinationOptions` | RFC 8200 §4.6 |
46
50
  | 3 | ICMPv4 | `ICMPv4` | RFC 792, 8-byte header |
47
51
  | 3 | ICMPv6 | `ICMPv6` | RFC 4443, 8-byte header |
48
52
  | 4 | TCP | `TCP` | RFC 9293, data-offset/options aware |
@@ -102,8 +106,9 @@ frame = Packet(
102
106
  raw = bytes(frame) # ready for a raw socket
103
107
  ```
104
108
 
105
- Checksums are carried verbatim in both directions: the library neither
106
- computes nor verifies them (planned — see the roadmap).
109
+ Checksums are computed and verified on request — never silently:
110
+ `compute()`/`verify()` in `netprotocols.checksum`, and
111
+ `Packet.with_checksums()` to fill a whole stack before sending.
107
112
 
108
113
  ## Display helpers
109
114
 
@@ -125,12 +130,7 @@ network traffic monitor built on it.
125
130
 
126
131
  ## Roadmap
127
132
 
128
- - IPv6 extension headers (hop-by-hop, routing, fragment, destination
129
- options) — today the decode chain ends at `IPv6` for traffic behind
130
- them (e.g. MLD).
131
133
  - 802.1Q VLAN tags, DNS, DHCP, IGMP, GRE.
132
- - Checksum computation on encode and verification flags on decode.
133
- - Fuzzing of the decode path.
134
134
 
135
135
  ## Contributing
136
136
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "netprotocols"
3
- version = "1.0.1"
3
+ version = "1.1.0"
4
4
  description = "Low-level implementations of common networking protocols"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -29,6 +29,7 @@ Changelog = "https://github.com/EONRaider/NETProtocols/blob/master/CHANGELOG.md"
29
29
 
30
30
  [dependency-groups]
31
31
  dev = [
32
+ "hypothesis>=6.100",
32
33
  "mypy>=1.14",
33
34
  "pytest>=8.3",
34
35
  "pytest-cov>=6.0",
@@ -134,10 +134,13 @@ def check_frame(frame: bytes, stats: Counter) -> list[str]:
134
134
  ext_len = (upper[1] + 1) * 8
135
135
  next_header, upper = upper[0], upper[ext_len:]
136
136
  if next_header == 44 and len(upper) >= 8:
137
- stats["ipv6-fragment"] += 1
138
137
  if struct.unpack_from("!H", upper, 2)[0] & 0xFFF8:
139
- return failures
140
- next_header, upper = upper[0], upper[8:]
138
+ stats["ipv6-fragment"] += 1
139
+ return failures # non-first fragment: no upper header
140
+ stats["ipv6-first-fragment"] += 1
141
+ # The upper-layer checksum spans the reassembled datagram,
142
+ # not this fragment's slice: nothing verifiable here.
143
+ return failures
141
144
  upper_len = len(upper)
142
145
  if next_header == 58 and upper_len >= 4:
143
146
  stats["icmpv6"] += 1
@@ -12,10 +12,17 @@ from netprotocols._enums import (
12
12
  EtherType,
13
13
  IPProtocol,
14
14
  )
15
+ from netprotocols.checksum import compute, internet_checksum, verify
15
16
  from netprotocols.layer2.arp import ARP
16
17
  from netprotocols.layer2.ethernet import Ethernet
17
18
  from netprotocols.layer3.icmp import ICMPv4, ICMPv6
18
19
  from netprotocols.layer3.ip import IPv4, IPv6
20
+ from netprotocols.layer3.ipv6_ext import (
21
+ IPv6DestinationOptions,
22
+ IPv6Fragment,
23
+ IPv6HopByHopOptions,
24
+ IPv6Routing,
25
+ )
19
26
  from netprotocols.layer4.tcp import TCP
20
27
  from netprotocols.layer4.udp import UDP
21
28
  from netprotocols.packet import Packet
@@ -30,7 +37,7 @@ from netprotocols.utils.exceptions import (
30
37
  from netprotocols.utils.ipv4 import validate_ipv4_addr
31
38
  from netprotocols.utils.mac import random_mac, validate_mac_addr
32
39
 
33
- __version__ = "1.0.1"
40
+ __version__ = "1.1.0"
34
41
 
35
42
  __all__ = [
36
43
  "ARP",
@@ -45,6 +52,10 @@ __all__ = [
45
52
  "IPProtocol",
46
53
  "IPv4",
47
54
  "IPv6",
55
+ "IPv6DestinationOptions",
56
+ "IPv6Fragment",
57
+ "IPv6HopByHopOptions",
58
+ "IPv6Routing",
48
59
  "InvalidFieldError",
49
60
  "InvalidIPv4AddressError",
50
61
  "InvalidMACAddressError",
@@ -54,7 +65,10 @@ __all__ = [
54
65
  "ProtocolError",
55
66
  "TruncatedHeaderError",
56
67
  "__version__",
68
+ "compute",
69
+ "internet_checksum",
57
70
  "random_mac",
58
71
  "validate_ipv4_addr",
59
72
  "validate_mac_addr",
73
+ "verify",
60
74
  ]
@@ -36,11 +36,15 @@ class IPProtocol(IntEnum):
36
36
  ``next_header``, so a single registry serves both.
37
37
  """
38
38
 
39
+ HOPOPT = 0x00
39
40
  ICMP = 0x01
40
41
  IGMP = 0x02
41
42
  TCP = 0x06
42
43
  UDP = 0x11
44
+ IPV6_ROUTE = 0x2B
45
+ IPV6_FRAG = 0x2C
43
46
  IPV6_ICMP = 0x3A
47
+ IPV6_DSTOPTS = 0x3C
44
48
 
45
49
  @property
46
50
  def display_name(self) -> str:
@@ -48,11 +52,15 @@ class IPProtocol(IntEnum):
48
52
 
49
53
 
50
54
  _IP_PROTOCOL_NAMES = {
55
+ IPProtocol.HOPOPT: "IPv6 Hop-by-Hop Options",
51
56
  IPProtocol.ICMP: "ICMP",
52
57
  IPProtocol.IGMP: "IGMP",
53
58
  IPProtocol.TCP: "TCP",
54
59
  IPProtocol.UDP: "UDP",
60
+ IPProtocol.IPV6_ROUTE: "IPv6 Routing",
61
+ IPProtocol.IPV6_FRAG: "IPv6 Fragment",
55
62
  IPProtocol.IPV6_ICMP: "IPv6-ICMP",
63
+ IPProtocol.IPV6_DSTOPTS: "IPv6 Destination Options",
56
64
  }
57
65
 
58
66
 
@@ -0,0 +1,158 @@
1
+ """Internet checksum computation and verification (RFC 1071).
2
+
3
+ The primitive, :func:`internet_checksum`, returns the raw ones'-
4
+ complement result — ``0x0000`` is a legal return value, and TCP, ICMP,
5
+ and the IPv4 header checksum legitimately transmit it. The famous
6
+ ``0x0000 → 0xFFFF`` substitution is a **UDP-only transmit rule**
7
+ (RFC 768; RFC 8200 §8.1) and lives solely in the UDP arm of
8
+ :func:`compute`.
9
+
10
+ Length fields are trusted, not reconciled: UDP uses ``layer.length``
11
+ for the pseudo-header, TCP uses ``layer.header_len + len(payload)``,
12
+ and nothing checks ``IPv4.total_length`` against the payload you pass.
13
+ Feed these helpers the payload exactly as it appears on the wire.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import struct
19
+
20
+ from netprotocols._base import (
21
+ Protocol,
22
+ ipv4_to_bytes,
23
+ ipv6_to_bytes,
24
+ )
25
+ from netprotocols._enums import IPProtocol
26
+ from netprotocols.layer3.icmp import ICMPv4, ICMPv6
27
+ from netprotocols.layer3.ip import IPv4, IPv6
28
+ from netprotocols.layer4.tcp import TCP
29
+ from netprotocols.layer4.udp import UDP
30
+ from netprotocols.utils.exceptions import InvalidFieldError
31
+
32
+ __all__ = ["compute", "internet_checksum", "verify"]
33
+
34
+
35
+ def internet_checksum(data: bytes | memoryview) -> int:
36
+ """The RFC 1071 checksum of ``data``: the ones' complement of the
37
+ ones'-complement sum of its 16-bit words (odd lengths are padded
38
+ with a zero byte).
39
+
40
+ Returns the raw result: ``0x0000`` is a legal value here. Protocol
41
+ rules such as UDP's zero substitution belong to :func:`compute`.
42
+ """
43
+ if len(data) % 2:
44
+ data = bytes(data) + b"\x00"
45
+ words: tuple[int, ...] = struct.unpack(f"!{len(data) // 2}H", data)
46
+ total = sum(words)
47
+ while total >> 16:
48
+ total = (total & 0xFFFF) + (total >> 16)
49
+ return ~total & 0xFFFF
50
+
51
+
52
+ def _pseudo_header(ip: IPv4 | IPv6, protocol: int, length: int) -> bytes:
53
+ """The pseudo-header prepended to transport checksums.
54
+
55
+ IPv4 (RFC 793/768): src, dst, zero byte, protocol, 16-bit length.
56
+ IPv6 (RFC 8200 §8.1): src, dst, 32-bit length, three zero bytes,
57
+ next-header.
58
+ """
59
+ if isinstance(ip, IPv4):
60
+ return (
61
+ ipv4_to_bytes(ip.src)
62
+ + ipv4_to_bytes(ip.dst)
63
+ + struct.pack("!BBH", 0, protocol, length)
64
+ )
65
+ return (
66
+ ipv6_to_bytes(ip.src)
67
+ + ipv6_to_bytes(ip.dst)
68
+ + struct.pack("!IBBBB", length, 0, 0, 0, protocol)
69
+ )
70
+
71
+
72
+ def _require_ip(layer: Protocol, ip: IPv4 | IPv6 | None) -> IPv4 | IPv6:
73
+ if ip is None:
74
+ raise InvalidFieldError(
75
+ f"Computing a {type(layer).__name__} checksum requires the "
76
+ f"enclosing IPv4/IPv6 layer (its pseudo-header covers the "
77
+ f"addresses)"
78
+ )
79
+ return ip
80
+
81
+
82
+ def _zeroed(layer_bytes: bytes, checksum_offset: int) -> bytes:
83
+ return (
84
+ layer_bytes[:checksum_offset]
85
+ + b"\x00\x00"
86
+ + layer_bytes[checksum_offset + 2 :]
87
+ )
88
+
89
+
90
+ def compute(
91
+ layer: Protocol,
92
+ *,
93
+ ip: IPv4 | IPv6 | None = None,
94
+ payload: bytes = b"",
95
+ ) -> int:
96
+ """The correct checksum field value for ``layer``.
97
+
98
+ :param layer: The header to checksum. ``IPv4`` covers its own
99
+ header only (options included; ``ip``/``payload`` ignored);
100
+ ``ICMPv4`` covers header plus ``payload`` (no pseudo-header);
101
+ ``TCP``, ``UDP``, and ``ICMPv6`` prepend the pseudo-header
102
+ built from ``ip``.
103
+ :param ip: The enclosing IP layer, required for TCP/UDP/ICMPv6.
104
+ :param payload: The bytes following ``layer`` on the wire.
105
+ :raises InvalidFieldError: For layers without a checksum field, or
106
+ a missing ``ip`` where the pseudo-header needs one.
107
+ """
108
+ if isinstance(layer, IPv4):
109
+ return internet_checksum(_zeroed(bytes(layer), 10))
110
+ if isinstance(layer, ICMPv4):
111
+ return internet_checksum(_zeroed(bytes(layer), 2) + payload)
112
+ if isinstance(layer, ICMPv6):
113
+ enclosing = _require_ip(layer, ip)
114
+ segment = _zeroed(bytes(layer), 2) + payload
115
+ return internet_checksum(
116
+ _pseudo_header(enclosing, IPProtocol.IPV6_ICMP, len(segment))
117
+ + segment
118
+ )
119
+ if isinstance(layer, TCP):
120
+ enclosing = _require_ip(layer, ip)
121
+ segment = _zeroed(bytes(layer), 16) + payload
122
+ return internet_checksum(
123
+ _pseudo_header(enclosing, IPProtocol.TCP, len(segment)) + segment
124
+ )
125
+ if isinstance(layer, UDP):
126
+ enclosing = _require_ip(layer, ip)
127
+ datagram = _zeroed(bytes(layer), 6) + payload
128
+ raw = internet_checksum(
129
+ _pseudo_header(enclosing, IPProtocol.UDP, layer.length) + datagram
130
+ )
131
+ # UDP-only transmit rule: 0 means "no checksum", so a computed
132
+ # 0x0000 is sent as 0xFFFF (RFC 768; mandatory path RFC 8200).
133
+ return raw or 0xFFFF
134
+ raise InvalidFieldError(
135
+ f"{type(layer).__name__} has no checksum field to compute"
136
+ )
137
+
138
+
139
+ def verify(
140
+ layer: Protocol,
141
+ *,
142
+ ip: IPv4 | IPv6 | None = None,
143
+ payload: bytes = b"",
144
+ ) -> bool:
145
+ """Whether ``layer``'s checksum field matches a recomputation.
146
+
147
+ A UDP-over-IPv4 checksum of ``0`` means "no checksum in use" and
148
+ verifies as True (over IPv6 the checksum is mandatory and ``0`` is
149
+ invalid).
150
+ """
151
+ if (
152
+ isinstance(layer, UDP)
153
+ and layer.checksum == 0
154
+ and not isinstance(ip, IPv6)
155
+ ):
156
+ return True
157
+ wire: int = layer.checksum # type: ignore[attr-defined]
158
+ return compute(layer, ip=ip, payload=payload) == wire
@@ -0,0 +1,19 @@
1
+ from netprotocols.layer3.icmp import ICMPv4, ICMPv6
2
+ from netprotocols.layer3.ip import IPv4, IPv6
3
+ from netprotocols.layer3.ipv6_ext import (
4
+ IPv6DestinationOptions,
5
+ IPv6Fragment,
6
+ IPv6HopByHopOptions,
7
+ IPv6Routing,
8
+ )
9
+
10
+ __all__ = [
11
+ "ICMPv4",
12
+ "ICMPv6",
13
+ "IPv4",
14
+ "IPv6",
15
+ "IPv6DestinationOptions",
16
+ "IPv6Fragment",
17
+ "IPv6HopByHopOptions",
18
+ "IPv6Routing",
19
+ ]
@@ -23,20 +23,48 @@ from netprotocols.utils.ipv4 import validate_ipv4_addr
23
23
  __all__ = ["IPv4", "IPv6"]
24
24
 
25
25
 
26
- def _ip_protocol_class(number: int) -> type[Protocol] | None:
26
+ #: Numbers that only make sense inside an IPv6 chain (RFC 8200 §4.1):
27
+ #: extension headers follow the IPv6 fixed header or one another, never
28
+ #: an IPv4 header.
29
+ _IPV6_ONLY_NUMBERS = frozenset(
30
+ {
31
+ IPProtocol.HOPOPT,
32
+ IPProtocol.IPV6_ROUTE,
33
+ IPProtocol.IPV6_FRAG,
34
+ IPProtocol.IPV6_DSTOPTS,
35
+ }
36
+ )
37
+
38
+
39
+ def _ip_protocol_class(number: int, *, ipv6: bool) -> type[Protocol] | None:
27
40
  """Map an IP protocol number to the class that decodes its payload.
28
41
 
29
42
  The number space is shared between IPv4 ``protocol`` and IPv6
30
43
  ``next_header`` (the values are disjoint), so both classes dispatch
31
- through this single registry.
44
+ through this single registry — but the IPv6 extension headers are
45
+ handed out only when the caller is part of an IPv6 chain
46
+ (``ipv6=True``): a garbage IPv4 packet with ``protocol=0`` must not
47
+ decode a Hop-by-Hop layer.
32
48
  """
33
49
  from netprotocols.layer3.icmp import ICMPv4, ICMPv6
50
+ from netprotocols.layer3.ipv6_ext import (
51
+ IPv6DestinationOptions,
52
+ IPv6Fragment,
53
+ IPv6HopByHopOptions,
54
+ IPv6Routing,
55
+ )
34
56
  from netprotocols.layer4.tcp import TCP
35
57
  from netprotocols.layer4.udp import UDP
36
58
 
59
+ if not ipv6 and number in _IPV6_ONLY_NUMBERS:
60
+ return None
37
61
  mapping: dict[int, type[Protocol]] = {
62
+ IPProtocol.HOPOPT: IPv6HopByHopOptions,
38
63
  IPProtocol.ICMP: ICMPv4,
64
+ IPProtocol.IPV6_ROUTE: IPv6Routing,
65
+ IPProtocol.IPV6_FRAG: IPv6Fragment,
39
66
  IPProtocol.IPV6_ICMP: ICMPv6,
67
+ IPProtocol.IPV6_DSTOPTS: IPv6DestinationOptions,
40
68
  IPProtocol.TCP: TCP,
41
69
  IPProtocol.UDP: UDP,
42
70
  }
@@ -180,7 +208,7 @@ class IPv4(Protocol):
180
208
  """
181
209
  if self.fragment_offset > 0:
182
210
  return None
183
- return _ip_protocol_class(self.protocol)
211
+ return _ip_protocol_class(self.protocol, ipv6=False)
184
212
 
185
213
  @property
186
214
  def protocol_name(self) -> str:
@@ -258,7 +286,7 @@ class IPv6(Protocol):
258
286
  )
259
287
 
260
288
  def next_protocol(self) -> type[Protocol] | None:
261
- return _ip_protocol_class(self.next_header)
289
+ return _ip_protocol_class(self.next_header, ipv6=True)
262
290
 
263
291
  @property
264
292
  def next_header_name(self) -> str: