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.
- {netprotocols-1.0.1 → netprotocols-1.1.0}/ARCHITECTURE.md +15 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/CHANGELOG.md +25 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/PKG-INFO +9 -9
- {netprotocols-1.0.1 → netprotocols-1.1.0}/README.md +8 -8
- {netprotocols-1.0.1 → netprotocols-1.1.0}/pyproject.toml +2 -1
- {netprotocols-1.0.1 → netprotocols-1.1.0}/scripts/capture_fixtures_supplement.sh +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/scripts/check_fixtures.py +6 -3
- {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/__init__.py +15 -1
- {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/_enums.py +8 -0
- netprotocols-1.1.0/src/netprotocols/checksum.py +158 -0
- netprotocols-1.1.0/src/netprotocols/layer3/__init__.py +19 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/layer3/ip.py +32 -4
- netprotocols-1.1.0/src/netprotocols/layer3/ipv6_ext.py +253 -0
- netprotocols-1.1.0/src/netprotocols/packet.py +88 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/MANIFEST.md +15 -13
- netprotocols-1.1.0/tests/fixtures/ipv6_fragments.pcap +0 -0
- netprotocols-1.1.0/tests/fixtures/ipv6_mld.pcap +0 -0
- netprotocols-1.1.0/tests/fixtures/staging/ipv6_fragments.pcap +0 -0
- netprotocols-1.1.0/tests/fixtures/staging/ipv6_mld.pcap +0 -0
- netprotocols-1.1.0/tests/test_checksum.py +239 -0
- netprotocols-1.1.0/tests/test_fuzz.py +182 -0
- netprotocols-1.1.0/tests/test_ipv6_ext.py +177 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/uv.lock +84 -1
- netprotocols-1.0.1/src/netprotocols/layer3/__init__.py +0 -4
- netprotocols-1.0.1/src/netprotocols/packet.py +0 -48
- {netprotocols-1.0.1 → netprotocols-1.1.0}/.github/workflows/ci.yml +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/.github/workflows/release.yml +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/.gitignore +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/LICENSE +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/scripts/capture_fixtures.sh +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/_base.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/layer2/__init__.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/layer2/arp.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/layer2/ethernet.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/layer3/icmp.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/layer4/__init__.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/layer4/tcp.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/layer4/udp.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/py.typed +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/utils/__init__.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/utils/exceptions.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/utils/ipv4.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/src/netprotocols/utils/mac.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/conftest.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/arp_exchange.pcap +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/icmpv4_echo_lo.pcap +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/icmpv4_external.pcap +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/icmpv4_ttl_exceeded.pcap +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/icmpv6_echo_lo.pcap +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/ipv4_fragments.pcap +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/ipv6_ndp_mld.pcap +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/staging/arp_exchange.pcap +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/staging/icmpv4_echo_lo.pcap +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/staging/icmpv4_external.pcap +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/staging/icmpv4_ttl_exceeded.pcap +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/staging/icmpv6_echo_lo.pcap +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/staging/ipv4_fragments.pcap +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/staging/ipv6_ndp_mld.pcap +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/staging/tcp_http.pcap +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/staging/tcp_https.pcap +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/staging/udp_dns.pcap +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/tcp_http.pcap +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/tcp_https.pcap +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/fixtures/udp_dns.pcap +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/test_arp.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/test_contract.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/test_corpus.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/test_ethernet.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/test_icmp.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/test_ip.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/test_packet.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/test_tcp.py +0 -0
- {netprotocols-1.0.1 → netprotocols-1.1.0}/tests/test_udp.py +0 -0
- {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
|
|
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
|
|
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
|
|
131
|
-
|
|
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
|
|
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
|
|
106
|
-
|
|
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
|
|
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",
|
|
File without changes
|
|
@@ -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
|
-
|
|
140
|
-
|
|
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
|
|
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
|
-
|
|
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:
|