netprotocols 2.3.0__tar.gz → 2.5.0__tar.gz

{netprotocols-2.3.0 → netprotocols-2.5.0}/.github/workflows/mutation.yml

@@ -49,6 +49,19 @@ jobs:
           key: mutmut-nightly-${{ github.run_id }}
           restore-keys: |
             mutmut-nightly-
+      # The restored cache also carries mutants/mutmut-stats.json, the
+      # map from each function to the tests that call it. When that map
+      # exists, mutmut 3.8 re-traces only tests it has never seen, so a
+      # function added since the cached run (a new helper called only
+      # by existing tests) maps to no tests and every one of its
+      # mutants reads "no tests"; so does an existing test edited to
+      # call a function it didn't before. Without the map, mutmut
+      # traces the configured test selection in full, which costs one
+      # traced pytest pass. Nothing else is lost: with the positional
+      # filters below, mutmut re-runs every in-scope mutant regardless
+      # of a cached result.
+      - name: Drop the cached function-to-test map
+        run: rm -f mutants/mutmut-stats.json
       - name: Install the project with dev dependencies
         run: uv sync --group dev --frozen
       # File-level scope (src/netprotocols/checksum.py, _tlv.py,

{netprotocols-2.3.0 → netprotocols-2.5.0}/ARCHITECTURE.md

@@ -151,16 +151,72 @@ the same three rules (spelled out in [`_base.py`](src/netprotocols/_base.py)):
    how many bytes this header consumed — a *property*, so IPv4 answers
    `ihl * 4` and TCP answers `data_offset * 4`.
 
-**Text framing is the one variation.** `HTTP` has no fixed portion to
-unpack: `decode()` scans for the empty line that ends the head, then
-for the end the head's framing gives the body, so rule 1 is a scan
-rather than an unpack and `header_len` covers the whole message, not a
-`_struct` size. Its `decode()` also takes keyword-only context the
-bytes cannot carry — `request_method` (a response to `HEAD`, or a 2xx
-to `CONNECT`, has no body whatever its headers say) and `closed` (the
-buffer ends where the connection did) — and `request_method` is stored,
-but normalized: kept only when it changes the framing, so two messages
-with equal bytes and equal framing compare equal.
+**Three protocols vary this.** The first is text framing. `HTTP` has no
+fixed portion to unpack: `decode()` scans for the empty line that ends
+the head, then for the end the head's framing gives the body, so rule 1
+is a scan rather than an unpack and `header_len` covers the whole
+message, not a `_struct` size. Its `decode()` also takes keyword-only
+context the bytes cannot carry — `request_method` (a response to `HEAD`,
+or a 2xx to `CONNECT`, has no body whatever its headers say) and
+`closed` (the buffer ends where the connection did) — and
+`request_method` is stored, but normalized: kept only when it changes
+the framing, so two messages with equal bytes and equal framing compare
+equal.
+
+The second is `SCTP`. Like ICMPv4, ICMPv6 and IGMP it has no length of
+its own: the packet is the whole IP payload, and the walk does not trim
+a frame to the IP header's declared length. Those three keep the whole
+buffer, Ethernet's zero padding included: ICMPv4's and IGMP's internet
+checksum is unchanged by appended zero bytes, and an IPv6 frame carrying
+ICMPv6 is never short enough to be padded. SCTP's CRC32c does change
+when zero bytes are appended, so `decode()` walks the chunk headers to
+find where the packet ends and leaves a run of zero bytes where the next
+chunk would start undecoded, since that cannot begin a chunk and is what
+an Ethernet sender normally pads a short frame with. Rule 3 holds for
+those zeros; any other trailing bytes become part of the packet. Past
+the 12-byte common header `decode()` never raises, like the three it
+resembles: a remainder the walk cannot parse — a chunk cut by a snap
+length, an IP fragment or an ICMP error's quote, or a nonzero trailer
+such as an Ethernet FCS, which cannot be told from a broken chunk — is
+kept verbatim in `chunks`, the ports and verification tag still decode,
+and `verify()` returns `False`. `parsed_chunks` raises only when the
+remainder does not walk: a trailer that happens to (an FCS whose bytes
+read as a chunk header) parses as a phantom chunk, so `verify()` is the
+reliable signal. See
+[`layer4/sctp.py`](src/netprotocols/layer4/sctp.py)'s module docstring.
+
+The third is `PIM`. It has no length either, and bounds itself by its
+own structure:
+a Join/Prune, Register-Stop or Assert ends where its counts and
+encoded addresses say, so anything after it is left undecoded, and a
+Hello, whose options run to the end of the message, leaves a run of
+zero bytes where the next option would start, as SCTP leaves one where
+a chunk would. A Register's encapsulated packet runs to the end of the
+buffer, which its checksum, over the first 8 bytes only, does not
+cover. Past the 4-byte header it never raises either: a body its
+parser cannot read is kept whole, for `PIM.message` to report. See
+[`layer3/pim.py`](src/netprotocols/layer3/pim.py)'s module docstring.
+
+`RIP` has the same problem one layer up: its 20-byte entries fill the
+rest of the UDP datagram, and the walk does not trim to UDP's length
+either. It keeps the whole buffer after its 4-byte header, as ICMPv4
+and IGMP do, leaving no trailing bytes, so `bytes(RIP.decode(x)) == x`.
+Its accessors read whole entries, up to the RFC 4822 authentication
+trailer that the first entry's Packet Length locates (when the bytes
+there start as a trailer does, `0xFFFF 0x0001`), and report what
+is left, fewer than 20 bytes, as `remainder`: an entry a snap length
+cut, or a trailer such as an Ethernet FCS, which only the UDP length
+could tell apart. Past the header neither `decode()` nor any accessor
+raises. Ethernet's zero padding reaches only a message with no entries,
+since one entry already fills the minimum frame. See
+[`layer7/rip.py`](src/netprotocols/layer7/rip.py)'s module docstring.
+
+`VRRP` has no length field either, but needs no walk: its version and
+address count give its exact length (8 bytes, the addresses, and
+VRRPv2's 8 bytes of authentication data), so it obeys rule 3 like a
+header with a length field and leaves Ethernet's padding undecoded. It
+must: a VRRPv3 advert for one IPv4 address is 12 bytes, padded on the
+wire, and VRRPv3's pseudo-header carries the message's length.
 
 Decoding accepts `bytes` or `memoryview`. Views are a decode-time
 transient only: every stored field is a scalar or materialized
@@ -193,15 +249,19 @@ except ProtocolError as e:
     print(e.protocol, e.field, e.offset, e.frame_offset, e.expected, e.actual)
 ```
 
-`offset` is relative to whatever buffer the error was found in: the
-`data` argument of a `decode()` call when `field` is `None` or names a
-fixed-header value, or the attribute `field` names when it's a raw
-`bytes` field parsed on demand (`options`, `body`, `sections`) — a TCP
-option error's `offset` is relative to `header.options`, not to the
-frame. `decode_frame` is the only code holding the cursor needed to
-rebase a layer's own offset to the whole frame, so it does — the
-result lands in `frame_offset`, left `None` by a bare
-`SomeClass.decode()` call with no frame to rebase against. A
+`offset` is relative to whatever buffer the error was found in. An
+error raised by `decode()` is relative to that call's `data` argument,
+whatever `field` names: OSPF's framing errors name `field="body"` (or
+`"auth_trailer"`) and still count from the start of the OSPF header,
+which is what lets `decode_frame` rebase them. An error raised later,
+by an accessor that parses a raw `bytes` attribute on demand
+(`options`, `body`, `sections`, `chunks`), is relative to that
+attribute — a TCP option error's `offset` is relative to
+`header.options`, an ICMPv6 NDP option's or an IGMPv3 group record's
+to `body`, not to the frame. `decode_frame` is the only code holding
+the cursor needed to rebase a layer's own offset to the whole frame,
+so it does — the result lands in `frame_offset`, left `None` by a
+bare `SomeClass.decode()` call with no frame to rebase against. A
 `__post_init__` validation error (values, not bytes) leaves `offset`
 `None` too; there is nothing to be positioned in. `HTTP` is the
 exception on both counts: its `field` names a grammar element
@@ -219,8 +279,28 @@ holds unchanged.
 A captured frame is a chain of headers, each one naming what it
 carries. In this library that fact is typed: every decoded header
 answers `next_protocol()` with the *class* that decodes its payload,
-or `None` when the chain ends (nothing encapsulated, or a protocol
-this library doesn't implement yet).
+or `None` when the chain ends (nothing encapsulated, a protocol this
+library doesn't implement yet, or a payload no header names in the
+clear — ESP's Next Header sits in its protected trailer, encrypted
+unless the Security Association uses a confidentiality-free transform
+(e.g. NULL, RFC 2410, or AES-GMAC, RFC 4543), and at an offset only
+the SA determines, so the decoder never reads it).
+
+`BGP` is the one exception, and it answers from decode context rather
+than from a wire field. A BGP message carries no payload: a TCP segment
+can hold several messages back to back, each decoded as its own layer,
+so `BGP.next_protocol()` names the next message *beside* it — `BGP`
+when the bytes after this message begin another one, `None` when they
+do not. Only those bytes can say which, and `next_protocol()` is handed
+none, so `decode()` records the answer on the instance in a field kept
+out of the dataclass's comparison and hash (`compare=False`, the
+mechanism `HTTP` uses for its `_message` parse cache). Two equal
+messages compare equal however they were found, and can still chain
+differently. The rules of the decode contract hold for it unchanged;
+see *Port-based dispatch is best-effort* below,
+[`_base.py`](src/netprotocols/_base.py)'s *Decode context in
+next_protocol*, and
+[`layer7/bgp.py`](src/netprotocols/layer7/bgp.py)'s module docstring.
 
 ```mermaid
 flowchart LR
@@ -235,14 +315,45 @@ flowchart LR
   I4 -->|1| IC4[ICMPv4]
   I4 -->|6| T[TCP]
   I4 -->|17| U[UDP]
+  I4 -->|132| S[SCTP]
+  I4 -->|103| P[PIM]
   I6 -->|58| IC6[ICMPv6]
   I6 -->|6| T
   I6 -->|17| U
+  I6 -->|132| S
+  I6 -->|103| P
+  I4 -->|4| I4
+  I4 -->|41| I6
+  I6 -->|4| I4
+  I6 -->|41| I6
+  I4 -->|50| ESP[ESP]
+  I6 -->|50| ESP
   I6 -->|0, 43, 44, 60| X[IPv6 extension headers]
   X --> X
   X -->|58| IC6
   X -->|6| T
   X -->|17| U
+  X -->|132| S
+  X -->|50| ESP
+  I4 -->|51| AH[AH]
+  AH -->|6| T
+  AH -->|17| U
+  AH -->|50| ESP
+  I6 -->|51| AH6[AHv6]
+  X -->|51| AH6
+  AH6 -->|0, 43, 44, 60| X
+  AH6 -->|6| T
+  AH6 -->|17| U
+  AH6 -->|50| ESP
+  I4 -->|89| OSPF[OSPFv2]
+  I4 -->|112| VR[VRRP]
+  I6 -->|112| VR6[VRRPv6]
+  X -->|112| VR6
+  U -->|4789| VX[VXLAN]
+  VX -->|always| E
+  U -->|520| R[RIP]
+  T -->|179| BGP[BGP message]
+  BGP -->|another message in the segment| BGP
 ```
 
 IPv6 extension headers (Hop-by-Hop Options, Routing, Fragment,
@@ -255,6 +366,20 @@ non-first fragment carries a slice from the middle of the original
 payload, so no upper-layer header exists at its start. The same
 offset rule applies to fragmented IPv4.
 
+IPsec's AH chains the same way, through its own `next_header`, onward
+to anything the IP header before it could have carried (the diagram
+draws only the transport, ESP and extension-header edges). It comes as
+a pair for that reason: `AH` after IPv4 and `AHv6` after IPv6 have one
+wire format but dispatch through their own family's table, so IPv4 →
+AH → `0` stops rather than conjuring a Hop-by-Hop layer, while IPv6 →
+AH → Destination Options — an order RFC 8200 §4.1 permits — keeps
+decoding. VRRP is the other pair, for a different reason: it ends the
+walk, but its list of virtual addresses is 4 bytes an entry after IPv4
+and 16 after IPv6, which nothing in the VRRP header says, so `VRRP`
+reads the one and its subclass `VRRPv6` the other. ESP, the other IPsec header,
+ends the walk: what it carries is named only inside its protected
+trailer.
+
 VLAN tags chain the same way: a tag's `next_protocol` dispatches the
 inner EtherType through the same registry Ethernet uses, so a QinQ
 (`0x88A8`) or legacy double-tagged (`0x9100`) frame decodes as one
@@ -269,8 +394,13 @@ The numbers on the arrows are the wire values — EtherTypes out of
 Ethernet, IP protocol numbers out of IPv4/IPv6 — and they live in
 [`_enums.py`](src/netprotocols/_enums.py) as `EtherType` and
 `IPProtocol`. IPv4 and IPv6 share one registry because the number
-space is shared (1 is ICMPv4, 58 is ICMPv6, 6 is TCP, 17 is UDP — no
-collisions).
+space is shared (1 is ICMPv4, 58 is ICMPv6, 6 is TCP, 17 is UDP, 132
+is SCTP, 103 is PIM — no collisions; 51 is AH and 112 is VRRP in
+both, each decoded by a class of each family's own). 89 is the
+exception: it is OSPF in both families, but OSPFv2 (RFC 2328) after
+IPv4 and OSPFv3 (RFC 5340), a different wire format, after IPv6, and
+this library decodes only OSPFv2, so `OSPF` is reached from IPv4
+alone.
 
 A complete frame walk is a five-line loop — which is exactly why it
 ships as [`decode_frame()`](src/netprotocols/walk.py) rather than as
@@ -310,22 +440,54 @@ field they dispatch on:
 | Table | Dispatches on | Read by |
 |---|---|---|
 | `ethertype` | Ethernet II EtherType | `Ethernet`, `VLAN`, `GRE` |
-| `ip.proto` | IPv4 `protocol` | `IPv4` |
-| `ip.proto.v6` | IPv6 `next_header` | `IPv6`, extension headers |
+| `ip.proto` | IPv4 `protocol` | `IPv4`, `AH` |
+| `ip.proto.v6` | IPv6 `next_header` | `IPv6`, extension headers, `AHv6` |
 | `udp.port` | UDP well-known port | `UDP` |
 | `tcp.port` | TCP well-known port | `TCP` |
 
 `ip.proto.v6` **inherits** `ip.proto`: the two share a number space
 but not a table, because the four extension headers must be reachable
-only inside an IPv6 chain. Registering in `ip.proto` reaches both;
-registering in `ip.proto.v6` reaches the v6 chain alone. Inheritance
+only inside an IPv6 chain. Registering in `ip.proto` reaches both,
+except at a key `ip.proto.v6` owns itself (51 and 112, below); registering in
+`ip.proto.v6` reaches the v6 chain alone. Inheritance
 is resolved when you register, not when you look up, so the gating
 costs nothing on the hot path — an IPv4 packet with `protocol=0`
 cannot conjure a Hop-by-Hop layer because the table it reads has no
 entry for `0`.
 
+A child's own registration also *shadows* the inherited entry, which
+is how AH's and VRRP's pairs are wired: `AHv6` is registered in
+`ip.proto.v6` first, then `AH` in `ip.proto` (and `VRRPv6`, then
+`VRRP`, likewise), and the parent write is not inherited over a
+key the child already owns. That works the other way round too: a
+third party replacing protocol 51 or 112 in `ip.proto` (`override=True`)
+changes IPv4 dispatch only, and must register in `ip.proto.v6` as well
+to reach IPv6. `_defaults.FAMILY_SPECIFIC_NUMBERS` names the numbers
+wired this way, and the tests hold the two tables to differing only at
+those keys, the IPv6-only numbers and the IPv4-only one below.
+
+A child can also own a key with no class. Protocol 89 is OSPFv2 in
+`ip.proto` and would be inherited into `ip.proto.v6`, where it means
+OSPFv3, so every OSPFv3 packet would fail to decode as OSPFv2; instead
+the defaults withhold 89 from `ip.proto.v6` (`_defaults.IPV4_ONLY_NUMBERS`)
+before registering `OSPF` in `ip.proto`. A withheld key is skipped by
+inheritance as an override is, so an IPv6 packet with next header 89
+ends its walk at the IPv6 header, as it did before `OSPF` existed, and
+a later write to `ip.proto` does not reach it; an OSPFv3 decoder
+registered directly in `ip.proto.v6` fills it. `OSPF.decode()` also
+rejects any version but 2, for a caller who sends it OSPFv3 on purpose
+(`start=` or `decode_as`).
+
+A row need not name a class of its own. IP-in-IP (protocols 4 and 41)
+has no header between the outer IP header and the inner one, so its
+rows in `ip.proto` point straight at `IPv4` and `IPv6`, and a tunneled
+packet walks `IPv4 → IPv4 → …` with no marker layer, as in scapy and
+dpkt. Anything that needs "the" IP header of a transport layer must
+therefore take the nearest one before it, as `Packet.with_checksums()`
+and `Packet.flow_key()` do, not the first.
+
 **Extending the walk without forking.** The tables are public. A
-protocol this library does not implement — MPLS, VXLAN, a proprietary
+protocol this library does not implement — MPLS, a proprietary
 telemetry header — is one registration away from participating in
 frame walks like any built-in:
 
@@ -355,8 +517,15 @@ registrations live together in
 [`_defaults.py`](src/netprotocols/_defaults.py), whose imports sit
 inside `install()` and run once from `__init__.py` after every
 protocol class exists. Shared enums stay in the dependency-free
-`_enums.py`. The layer modules bind their table at import and never
-import each other's classes at all.
+`_enums.py`. The layer modules bind their table at import, and every
+class a header chooses by a field value (EtherType, IP protocol, port)
+comes out of a table, never from an import. Two modules do import
+another's class, where there is no field to look up. `layer3/icmp.py`
+names `IPv4` and `IPv6` to start the walk of the packet an ICMP error
+quotes, which is not dispatch, and `layer7/vxlan.py` names `Ethernet`
+directly, because a VXLAN payload is always an Ethernet frame. Neither
+can form a cycle: `ip.py` and `ethernet.py` import no other layer
+module.
 
 ## Port-based dispatch is best-effort
 
@@ -372,14 +541,104 @@ fourth layer; on TCP, port 53 names `DNSOverTCP`, a shim that consumes
 the 2-byte length prefix (RFC 1035 §4.2.2) and chains onward, so the
 walk stays uniform.
 
-Because the guess can be wrong, the application class validates
-strictly on decode: a non-DNS datagram that happens to use port 53
-raises a `ProtocolError`, which the ordinary decode-error path absorbs
-(the chain keeps the layers it did decode and records the failure). So
-a mis-dispatch degrades to a diagnosed frame, never to garbage. This
-is why the port tables can be opened to third parties as safely as the
-authoritative ones: a wrong registration costs a diagnosed frame, not
-a wrong answer.
+VXLAN on UDP 4789 (RFC 7348) is the one port entry whose payload is a
+whole Ethernet frame. `VXLAN.next_protocol()` always answers
+`Ethernet`, and the walk carries on from there exactly as it does at
+the start of a frame — the inner frame's VLAN tags, ARP, IPv4 or IPv6
+dispatch through the same `ethertype` table, and the registry a caller
+passed reaches them too. The walker needed no change for this:
+`start=` only chooses the first class, and every later one comes from
+the previous header's `next_protocol()`, whatever its layer. An
+encapsulating endpoint normally sends to 4789, the IANA port (RFC 7348
+§5), from a source port hashed from the inner flow, so the
+destination-first lookup finds VXLAN even when that hash lands on
+another registered port. The same precedence means a DNS reply to a
+client whose ephemeral port happens to be 4789 dispatches to VXLAN,
+never to DNS (and is then rejected at the I flag about half the time).
+Only 4789 is registered, and Linux still gives a vxlan device `dstport`
+8472, the port it used before IANA assigned one, when `ip link add`
+names none, so a capture from such a device needs
+`decode_as={"udp.port": {8472: VXLAN}}`. An ICMP echo tunnelled through
+VXLAN walks seven layers (`Ethernet → IPv4 → UDP → VXLAN → Ethernet →
+IPv4 → ICMPv4`), and a hostile frame nested in itself gains four per
+level until `max_depth` stops it.
+
+Because the guess can be wrong, each application class validates on
+decode, but it can only reject what its format lets it tell apart from
+noise, and for most formats that is little. DNS needs only its 12-byte
+header and DHCP its 236-byte fixed part; past that, almost any bytes
+decode cleanly as either, and even a datagram to port 53 with no
+payload at all, padded to Ethernet's 60-byte minimum, decodes the
+padding as a DNS header. VXLAN can reject more, because its header has
+one bit it requires: the I flag, which random bytes leave clear half the
+time. Over 10,000 random 300-byte UDP payloads per port, decoded with
+`decode_frame(..., lax=True)`, the walk ended with `stopped_by` set for
+50.1% of those sent to 4789 and for none of those sent to 53 or 67.
+With lengths drawn uniformly from 0-600 bytes instead, in frames not
+padded to Ethernet's minimum, the figures are about 52%, 2% and 39%,
+and every DNS and DHCP rejection is a payload too short for the fixed
+header; padded to the minimum, as on the wire, the DNS figure falls to
+0%, since the padding itself decodes as a DNS header. The VXLAN
+header cannot reject more than it does: RFC 7348 says to ignore its
+reserved bits, so rejecting those would refuse real traffic, such as
+the Group Based Policy extension's.
+
+RIP on UDP 520 rejects the most, because two of its four header bytes
+have values no RIP message carries: `RIP.decode()` requires version 1
+or 2 and a nonzero command, which 510 of the 65,536 two-byte prefixes
+satisfy, so about 99.2% of random datagrams are rejected. Measured the
+same way, the walk stopped for about 99.2% in each case: the 300-byte
+payloads sent to 520, and the 0-600 byte ones unpadded and padded, the
+differences between them within sampling noise; an empty datagram
+padded to the minimum is rejected too, since the padding reads as
+version 0. It goes no further. The obsolete and extension commands
+(TraceOn, TraceOff, the triggered and update messages) decode, and so
+does a RIPv1 message with nonzero must-be-zero fields, which RFC 1058
+tells a receiver to ignore but a decoder should show. Past the header,
+any 20 bytes are an entry.
+
+BGP on TCP 179 (RFC 4271) has the strongest guard of any port entry:
+every message opens with a 16-byte Marker of all ones, which random
+bytes match once in 2^128, and then a Length and Type whose bounds
+depend on each other (§6.1). Measured the same way, over 10,000 random
+300-byte payloads and 10,000 of uniformly random length 0-600, padded
+or not, every walk to port 179 ended with `stopped_by` set and none
+decoded a BGP layer; with the Marker forced to all ones, the Length and
+Type checks alone still rejected 9,998 to 10,000 of 10,000 random
+300-byte payloads (`random.Random` seeds 0-4). What the port cannot tell the decoder is where a message
+starts: TCP cuts its byte stream where it likes, so a segment can hold
+several messages, the tail of one, or the head of the next. Each
+message decodes as one `BGP` layer, and `BGP.next_protocol()` answers
+`BGP` while another message begins in the same segment. It is handed no
+bytes, so `BGP.decode()` records the answer on the instance, in a field
+outside its comparison and hash (see *Walking a frame* above). A
+segment that ends inside a message raises `TruncatedHeaderError` at
+that message (lax mode keeps the ones before it); one that begins
+inside a message fails the Marker check, or raises
+`TruncatedHeaderError` if it is shorter than a header; a bare ACK, like
+one on port 53, sends an empty payload into the decoder. A segment of many small messages is a deep
+chain, and here `max_depth` bounds correctness, not just cost: the
+default leaves room for 29 messages after Ethernet, IPv4 and TCP, and
+valid segments hold more. A 1448-byte one holds 76 KEEPALIVEs or 30
+one-prefix UPDATEs, and a capture taken with GRO or TSO on, over
+loopback or on a jumbo-frame link sees segments of up to 64 KB, so a
+strict walk raises `MaxDepthExceededError` on valid traffic and a lax
+one stops with `stopped_by` set and `consumed` short of the frame. A
+larger `max_depth` or a second walk,
+`decode_frame(frame[packet.consumed:], start=BGP)`, decodes the rest;
+the busiest segment of the captured session in the corpus, taken with
+offload off, carries 7. Reassembling
+the stream is the caller's, as it is for `HTTP` below: see
+[`layer7/bgp.py`](src/netprotocols/layer7/bgp.py)'s module docstring.
+
+A rejected guess takes the ordinary decode-error path: the chain keeps
+the layers it did decode and records the failure. An accepted one
+yields a layer that decoded cleanly and is wrong, and nothing in the
+`Packet` says so. A caller who needs certainty does not leave it to the
+port: `decode_as` or a derived `Registry` names the class for a port
+the caller knows, overriding the default for that walk. Third-party
+entries in the port tables carry the same risk and no more: a wrong
+registration costs what a wrong guess does.
 
 `HTTP` is deliberately absent from the `tcp.port` table. The unit a
 datagram protocol decodes is the payload; HTTP's is a message, which
@@ -396,10 +655,17 @@ bytes instead.
 ## The encode side, and the round-trip guarantee
 
 Every class also works in reverse. Constructors take the friendly
-forms (string addresses, integer fields), validate them in
-`__post_init__` (address formats; and IHL/data-offset must agree with
-`len(options)` — you cannot construct a self-contradictory header),
-and `bytes()` re-emits the exact on-wire form.
+forms (string addresses, integer fields) and validate some of them in
+`__post_init__`: Ethernet, ARP and IPv4 check address formats (IPv6,
+DHCP, VRRP and OSPF do not, so a malformed address there fails only
+in `bytes()`; for OSPF's `router_id`, `area_id` and its records'
+address fields, such as an LSA header's `advertising_router`, that
+is the `OSError` from `socket.inet_pton`), and IPv4's IHL and TCP's
+data offset must agree with
+`len(options)`. For a valid header, `bytes()` re-emits the exact
+on-wire form. Constructors do not check everything decode does, so
+some headers can be built that decode would never produce (see
+below).
 
 The test suite enforces the round trip in both directions for every
 protocol:
@@ -409,14 +675,60 @@ Protocol.decode(bytes(header)) == header        # object → wire → object
 bytes(Protocol.decode(raw)) == raw[:header_len] # wire → object → wire
 ```
 
+The first holds for canonical headers, the ones decode itself
+produces, when decode is given the context it produced them with
+(HTTP's `request_method` and `closed`). A constructor accepts more
+than that, and for those headers the first line can fail: spellings
+are normalised on the way back (a MAC written with dashes decodes with
+colons, an IPv6 address decodes compressed); GRE's optional `fields`
+must agree with its flag bits; and VXLAN accepts a clear I flag on
+purpose, so that a test of another stack can send one, though
+`VXLAN.decode()` rejects it as its guard against a wrong port guess
+(see *Port-based dispatch is best-effort*). The round-trip property
+tests generate canonical headers only: addresses spelled as decode
+spells them, GRE fields sized from its flags, VXLAN with the I flag
+set, and HTTP messages that either need no context or are decoded with
+the context they carry.
+
 One deliberate boundary: **decode and encode carry checksums
 verbatim** — exactly what you want when faithfully re-encoding
 captured traffic. Computing and verifying them is explicit, via
 `netprotocols.checksum`: `compute()`/`verify()` handle the IPv4 header
 checksum, ICMPv4, and TCP/UDP/ICMPv6 with their IPv4/IPv6
-pseudo-headers, and `Packet.with_checksums(payload)` fills a whole
+pseudo-headers, PIM (the pseudo-header over IPv6 only, a Register's
+first 8 bytes only), and `Packet.with_checksums(payload)` fills a whole
 stack before sending. (The RFC 768 subtlety lives where it belongs:
-the `0x0000 → 0xFFFF` substitution applies to UDP alone.)
+the `0x0000 → 0xFFFF` substitution applies to UDP alone.) SCTP is the
+one transport that does not use the internet checksum: its CRC32c
+(`crc32c()`, RFC 9260 Appendix A) covers the whole packet with no
+pseudo-header, and goes on the wire least significant byte first, so
+`compute()` returns it byte-swapped to match the field as decoded.
+VRRP's checksum is the internet checksum of the message alone in
+VRRPv2 and behind the IP pseudo-header in VRRPv3. RFC 5798 §5.2.8
+cites only IPv6's pseudo-header; adding IPv4's too is keepalived's
+default, and `compute()`'s. RFC 9568, which obsoletes RFC 5798, leaves
+it out over IPv4, and `verify()` returns `False` for an advert
+checksummed that way.
+
+That is also why `SCTP.decode()` bounds its own extent (see "The decode
+contract" above): otherwise Ethernet's padding would land inside the
+CRC's span, and a packet under 46 bytes from a real NIC would fail to
+verify.
+
+OSPF carries two checksums. The packet's is the internet checksum of
+the whole packet but its 64-bit Authentication field, with no
+pseudo-header, and `compute()` covers only the packet's own bytes, so
+an RFC 5613 LLS block after it never enters; under cryptographic
+authentication (AuType 2, or 3 from RFC 7474) none is computed (the
+digest protects the packet), so `compute()` raises, `verify()` returns
+`True` and `with_checksums()` leaves the field alone. Each LSA's LS
+Checksum is an ISO 8473 Fletcher checksum of the LSA but its LS Age;
+an LSA is not a layer, so it has functions of its own:
+`lsa_checksum()` generates the field with `fletcher_checksum()`, and
+`verify_lsa()` checks it the way RFC 905 B.4 does, by both running sums
+being zero, so a byte stored as `0x00` where the generator writes
+`0xff` passes; and, since RFC 2328 §12.1.7 says the field cannot be
+zero, it fails a field of `0x0000` even where those sums are zero.
 
 `Packet` is the thin composition layer: it holds an ordered tuple of
 headers and `bytes(packet)` joins them, ready for a raw socket.
@@ -428,24 +740,31 @@ src/netprotocols/
 ├── __init__.py     public API re-exports, __version__, registry install
 ├── _base.py        Protocol ABC, decode contract, address helpers
 ├── _tlv.py         walk_kind_length_value(): shared TCP/IPv4/IPv6
-│                   options TLV walker
+│                   options and PIM Hello options TLV walker
 ├── _enums.py       EtherType, IPProtocol, ARPOperation (imports nothing)
 ├── registry.py     public dispatch tables: register(), Registry
 ├── walk.py         decode_frame(): the shipped chain walker
 ├── _defaults.py    the built-in decoder map, installed at import
 ├── packet.py       Packet composition, with_checksums(), flow_key()
-├── checksum.py     RFC 1071: internet_checksum, compute, verify
+├── checksum.py     RFC 1071 internet_checksum, SCTP's crc32c,
+│                   compute, verify, OSPF's LSA Fletcher checksum
 ├── flow.py         FlowKey, flow_key(): canonical bidirectional keys
 ├── pcap.py         read_captures()/read_pcap()/read_pcapng(): classic
 │                   pcap and pcapng readers, from bytes not filenames
 ├── layer2/         ethernet.py, arp.py, vlan.py (802.1Q / 802.1ad)
 ├── layer3/         ip.py (IPv4 + IPv6), icmp.py (ICMPv4 + ICMPv6),
-│                   igmp.py, gre.py,
+│                   igmp.py, gre.py, esp.py (IPsec ESP),
+│                   ah.py (IPsec AH: AH + AHv6),
+│                   ospf.py (OSPFv2: OSPF + its message records),
+│                   pim.py (PIM-SM),
+│                   vrrp.py (VRRPv2/v3: VRRP + VRRPv6),
 │                   ipv6_ext.py (Hop-by-Hop, Routing, Fragment,
 │                   Destination Options)
-├── layer4/         tcp.py, udp.py, _ports.py (port-table dispatch)
+├── layer4/         tcp.py, udp.py, sctp.py, _ports.py (port-table
+│                   dispatch)
 ├── layer7/         dns.py, dhcp.py, http.py (the HTTP/1.1 grammar
-│                   and the HTTP codec class)
+│                   and the HTTP codec class), vxlan.py, rip.py
+│                   (RIPv1 + RIPv2), bgp.py (BGP-4 messages)
 └── utils/          validators (mac.py, ipv4.py), exceptions.py
 tests/              one file per protocol + test_contract.py
                     (truncation, lying lengths, chain walks),