Fix four IPv6 defects (#352, #353, #360, #369)

[JarryShaw]

Four filed IPv6 defects. Two of them silently corrupted data while reporting success, and one turned out to affect the write path as well as the read path.

#352 — fragment offset used as octets, not 8-octet units

read() passed the raw 13-bit wire field straight through, but foundation/reassembly/ip.py indexes the datagram buffer with it directly (datagram[FO:TL-IHL+FO]) while using FO // 8 for the received-bit table. So fragments landed at an eighth of their offsets and the completion check still passed.

On examples/captures/ipv6.pcap: 977 octets before, 4778 after — completed=True either way, which is what made it dangerous. Verified by payload bytes, not just length: sha256 identical to an independent offset×8 reassembly.

_make_data now emits wire units again so Data → make round-trips exactly; this deliberately does not replicate the round-trip asymmetry ipv4.py:504 has. toolkit/scapy.py needed the same scaling at its own site.

#353 — reassembly keyed on the flow label, not the fragment identification

bufid[2] flows into DatagramID.id, so the label both surfaced as the wrong id.id (0 where the fixture carries 110308) and merged unrelated datagrams. On a synthetic two-datagram capture sharing a flow label with ids 1001/2002 interleaved: before, one merged completed=True datagram with index=(1,2,3) mixing both bodies plus an orphan; after, two complete datagrams with payloads exactly equal to the originals. Fixed in the pcap, pcapng and scapy toolkits.

#360 — flow label parsed from bits 8-27 instead of 12-31

Verified against RFC 8200 §3 (Version 4 / Traffic Class 8 / Flow Label 20 ⇒ the label starts at bit 12).

This is worse than the issue reports: BitField uses the same namespace for pre_process, so the overlap corrupted the build path too. At HEAD, class=0x2a, label=0x12345 serialised to 62123450 instead of 62a12345 — traffic class emitted as 0x21, label as 0x23450. pcapkit was writing malformed IPv6 headers, not merely misreading them. One line fixes both directions; I confirmed 62a12345 independently on this branch.

#369 — the IPv6-Opts registry clobbers Pad1

ipv6_opts.py lacked the __enum__ declaration hopopt.py:489 has, so QuickStartOption's subclasses overwrote keys in the parent registry. Two keys, not one as filed: Quick_Start_Request (0) clobbered PadOption, and Report_of_Approved_Rate (8) clobbered _SMFDPDOption. Both now match hopopt.

How #353 and #360 interact

Only through #353's key, and fixing #353 dissolves it. #360 discarded the label's low four bits, so datagrams differing only there collided in the label-keyed buffer — #360 widened #353's collision surface. Once the buffer keys on the identification, the flow label no longer participates in reassembly at all. Independent defects, one amplifying the other.

Existing expectations changed

Four, each of which encoded a bug. In every case the wire value is now pinned alongside the octet value, so the two cannot drift apart again:

	old	new
test_ipv6_extension_runtime.py:119 frag.info.offset	543	4344 (543 × 8)
test_ipv6_extension_unit.py:220 data.offset	12	96
test_ipv6_extension_unit.py:114 _make_data()['offset']	16	2 (16 octets → 2 units)
test_pcap_unit.py:151, test_scapy_unit.py:152 bufid[2]	7	4321

Both toolkit fixtures gained a fragment id (4321) distinct from the flow label (7), plus an assertNotEqual(bufid[2], 7) — a fixture where the two are equal proves nothing.

Verification

New tests/protocols/internet/test_ipv6_reassembly_runtime.py (4 tests, synthetic captures, no fixture dependency): byte-exact 1536-octet payload assertion; the interleaved two-datagram merge with disjoint even/odd alphabets so a merge fails both a byte and a census check; the mirror case (same identification, different labels); and a three-fragment out-of-order datagram, since two fragments can pass by accident and three cannot. Plus 3 unit tests for the label including an exact bit-tiling assertion and a wire round trip, and 2 registry-scoping tests comparing hopopt's and ipv6_opts' registries key for key.

Each fix was reverted individually to confirm the tests catch it. Suite 508 → 517 passed, 315 → 338 subtests; isort diffs byte-identical to HEAD; pylint delta exactly zero (the test was rewritten to snapshot registries with dict(...), which also avoids mutating a defaultdict on a missing-key read).

Audited the whole schema tree for both shapes: IPv6.hextet was the only overlapping BitField namespace and QuickStartOption the only genuine EnumSchema collision — so neither defect is part of a pattern.

Reported, not fixed

• toolkit/dpkt.py:195 reads ipv6_frag.nxt — the next-header field — as the fragment offset. Not merely unscaled; the wrong field entirely. dpkt exposes the offset as frag_off. More severe than IPv6 fragment offset used as octets, not 8-octet units #352 and in no issue. That file was owned by another stream (Fix five dpkt toolkit defects (#351, #370) #385) at the time.
• Pad1 still does not parse, in both modules: PadOption.pad reads a ConditionalField-absent len that holds NoValue, giving struct.error: bad char in struct format. Left alone deliberately — it lives in hopopt.py too, and fixing only my copy would recreate exactly the one-module-diverges asymmetry that caused IPv6-Opts QuickStartOption registry clobbers Pad1 (option type 0) #369. Same family as MH: a Pad1 mobility option crashes parsing with struct.error #355; wants an issue covering both.
• ipv6.py:268 _read_ip_hextet() has a third flow-label bug (version nibble included, 24-bit label). Dead code — its only caller is a test pinning the wrong values.
• toolkit/scapy.py:143 and toolkit/dpkt.py:147 have the same unit defect as IPv6 fragment offset used as octets, not 8-octet units #352 on the IPv4 paths.
• tests/integration/test_reassembly_end_to_end.py:285 has a @unittest.skip for IPv6 fragment offset used as octets, not 8-octet units #352 that these fixes make obsolete. It is in another stream's directory, so untouched — but I verified its assertions pass now ([1448, 1448, 1448, 434], 4778 octets, payload equal to the joined fragments). It can be lifted in a follow-up.

Closes #352, closes #353, closes #360, closes #369.

[Copilot]

🟢 Approval recommended

The fixes are consistent across toolkits/schema/protocol layers and are backed by focused unit + runtime regression tests covering the previously silent corruption cases.

Pull request overview

This pull request fixes four IPv6 correctness defects spanning fragment reassembly (offset units + buffer key), IPv6 flow-label bit layout (read/write symmetry), and IPv6-Opts Quick Start option registry scoping, and adds targeted regression tests to prevent silent data corruption from recurring.

Changes:

• Correct IPv6 Fragment offset handling (wire 8-octet units ↔ internal octets) and ensure Data→make round-trips.
• Fix IPv6 reassembly buffer keying to use Fragment Identification (not flow label) across PCAP/PCAPNG/Scapy toolkits.
• Fix IPv6 flow-label bitfield layout and prevent registry clobbering in IPv6-Opts QuickStartOption via a scoped enum registry; add new unit/runtime tests for all four defects.

File summaries

File	Description
pcapkit/protocols/internet/ipv6_frag.py	Scale fragment offset to octets on read; scale back to wire units in _make_data; clarify offset units in docs.
pcapkit/toolkit/pcap.py	Use IPv6 Fragment Identification (not flow label) for IPv6 reassembly buffer IDs.
pcapkit/toolkit/pcapng.py	Align PCAPNG IPv6 reassembly buffer IDs with Fragment Identification keying.
pcapkit/toolkit/scapy.py	Key on fragment identification and scale Scapy fragment offsets from units to octets for reassembly.
pcapkit/protocols/schema/internet/ipv6.py	Fix flow-label bit range to start at bit 12; add rationale comment tied to BitField semantics + RFC 8200.
pcapkit/protocols/schema/internet/ipv6_opts.py	Add QuickStartOption.__enum__ to prevent option-registry clobbering (Pad1/SMF_DPD).
tests/protocols/internet/test_ipv6_extension_unit.py	Update IPv6-Frag unit expectations (offset scaling + round-trip) and add registry collision guards.
tests/protocols/internet/test_ipv6_extension_runtime.py	Update runtime expectation for IPv6 fragment offset to octets.
tests/protocols/internet/test_ipv6_unit.py	Add flow-label bit-tiling + wire-round-trip tests to guard both parse and build paths.
tests/protocols/internet/test_ipv6_reassembly_runtime.py	Add end-to-end synthetic PCAP reassembly regression tests for offset scaling + identification keying.
tests/toolkit/test_pcap_unit.py	Update toolkit fixtures/assertions for identification keying and octet offsets.
tests/toolkit/test_scapy_unit.py	Update Scapy fixture/assertions for fragment identification and octet-offset scaling.

Review details

• Files reviewed: 12/12 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.