netprotocols 2.4.0__tar.gz → 2.5.0__tar.gz

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

@@ -151,7 +151,7 @@ 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`.
 
-**Two protocols vary this.** The first is text framing. `HTTP` has no
+**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
@@ -185,6 +185,39 @@ 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
 `bytes`, so no decoded object ever aliases the buffer it came from.
@@ -216,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
@@ -249,6 +286,22 @@ 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
   E[Ethernet] -->|0x0806| A[ARP]
@@ -263,10 +316,12 @@ flowchart LR
   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
@@ -290,8 +345,15 @@ flowchart LR
   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,
@@ -306,12 +368,15 @@ 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 is the
-one header that 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. ESP, the other IPsec header,
+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.
 
@@ -330,8 +395,12 @@ 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, 132
-is SCTP — no collisions; 51 is AH in both, decoded by a class of each
-family's own).
+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
@@ -379,7 +448,7 @@ field they dispatch on:
 `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,
-except at a key `ip.proto.v6` owns itself (51, below); registering in
+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`
@@ -387,14 +456,27 @@ 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 pair is wired: `AHv6` is registered in `ip.proto.v6` first,
-then `AH` in `ip.proto`, and the parent write is not inherited over a
+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 in `ip.proto` (`override=True`)
+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 at
-those keys alone.
+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
@@ -501,6 +583,54 @@ 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
@@ -526,9 +656,12 @@ bytes instead.
 
 Every class also works in reverse. Constructors take the friendly
 forms (string addresses, integer fields) and validate some of them in
-`__post_init__`: Ethernet, ARP and IPv4 check address formats (IPv6
-and DHCP do not, so a malformed address there fails only in
-`bytes()`), and IPv4's IHL and TCP's data offset must agree with
+`__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
@@ -562,19 +695,41 @@ 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.) 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.
 
@@ -585,14 +740,14 @@ 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, SCTP's crc32c,
-│                   compute, verify
+│                   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
@@ -600,12 +755,16 @@ src/netprotocols/
 ├── layer3/         ip.py (IPv4 + IPv6), icmp.py (ICMPv4 + ICMPv6),
 │                   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, sctp.py, _ports.py (port-table
 │                   dispatch)
 ├── layer7/         dns.py, dhcp.py, http.py (the HTTP/1.1 grammar
-│                   and the HTTP codec class), vxlan.py
+│                   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),

{netprotocols-2.4.0 → netprotocols-2.5.0}/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.5.0] - 2026-10-25
+
+### Added
+
+- **`VRRP` and `VRRPv6`: the Virtual Router Redundancy Protocol, VRRPv2 (RFC 3768) and VRRPv3 (RFC 5798) (#181).** IP protocol 112 (`IPProtocol.VRRP`, "VRRP") now dispatches to `netprotocols.VRRP` from IPv4 and to its subclass `VRRPv6` from IPv6 and its extension headers. One class decodes both versions and branches on the version nibble: the fixed fields `version`, `type`, `vrid`, `priority`, `count_ip_addrs` and `checksum`, the 16 bits between Count and Checksum kept raw as `adver_word` and read through per-version accessors that return `None` where the version has no such field (`auth_type`/`auth_type_name` and `adver_int` in seconds for VRRPv2; `reserved` and `max_adver_int` in centiseconds for VRRPv3; `advertisement_interval` in seconds for either), the virtual `addresses`, and VRRPv2's 8 bytes of `auth_data` (the null-padded password under Auth Type 1, keepalived's `auth_type PASS`). The address width depends on the IP family, not on anything in the header, which is why the class comes as a pair: `VRRP` reads 4-byte addresses and `VRRPv6` 16-byte ones, and `VRRPv6` accepts VRRPv3 only, since RFC 3768 defines VRRPv2 for IPv4 alone. VRRP has no length field, but the version and count give its exact length, which is `header_len`, so Ethernet padding and an FCS after the message are left undecoded and `bytes(VRRP.decode(x)) == x[:header_len]`. A version other than 2 or 3 raises `InvalidFieldError` (`field="version"`, `offset=0`), because the version decides the layout; an unknown type, a priority of 0 (a master resigning), a count of 0 and the reserved bits are carried verbatim. A count, or VRRPv2's authentication data, past the buffer raises `TruncatedHeaderError` (`field="count_ip_addrs"` or `"auth_data"`). Construction also checks `count_ip_addrs == len(addresses)`, the authentication data's length against the version (8 bytes or none), and that `type` fits its nibble. The walk ends at VRRP. Registering over protocol 112 in `ip.proto` reaches IPv4 only, as for AH's 51; `_defaults.FAMILY_SPECIFIC_NUMBERS` now names both.
+- **VRRP checksums in `compute`/`verify`/`Packet.with_checksums()`.** The internet checksum of the whole message with the checksum field zeroed: alone for VRRPv2 (RFC 3768 §5.3.8, `ip` not needed), behind the IP pseudo-header with protocol 112 for VRRPv3 over IPv4 and IPv6 (`ip` required). `payload` is ignored, as for IGMP. Over IPv6 that is RFC 5798 §5.2.8's rule; over IPv4, §5.2.8 cites only RFC 2460's pseudo-header, which is IPv6's, and the IPv4 one is what keepalived 2.2.8 sends by default. RFC 9568 §5.2.8, which obsoletes RFC 5798, leaves the pseudo-header out over IPv4, as keepalived's `v3_checksum_as_v2` option does, and `verify()` returns `False` for such an advert.
+- **`RIP`: the Routing Information Protocol, versions 1 and 2 (RFC 1058, RFC 2453, #182).** UDP port 520 dispatches, best-effort like every port entry, to the new `netprotocols.RIP` (also `netprotocols.layer7.RIP`), which decodes the 4-byte header into `command`, `version` and `reserved` (bytes 2-3: must be zero in RFC 1058 and RFC 2453, RFC 1388's Routing Domain) and keeps everything after it as raw `body`, so `bytes(RIP.decode(x)) == x`. `entries` parses the 20-byte entries on demand: a route is a `RIPEntry` (`afi`, `route_tag`, `address`, `subnet_mask`, `next_hop`, `metric`; RIPv1 zeroes the v2-only fields, which are kept verbatim either way), and an entry with AFI 0xFFFF is a `RIPAuthentication` (`auth_type`, the raw 16 `data` bytes, and `password` for type 2, or `packet_length`, `key_id`, `auth_data_len` and `sequence_number` for RFC 4822's type 3), never a route; `routes` and `authentication` select them. RIP has no length field and the walk does not trim to UDP's (#235), so the entries end at the RFC 4822 authentication trailer, which the first entry's Packet Length locates when the bytes there start with the trailer's `0xFFFF 0x0001` (`authentication_trailer`, raw, to the end of the body: Auth Data Len does not size it, since BIRD declares 20 for a 16-byte MD5 digest and 32 for a 32-byte HMAC-SHA-256 one), or at the last whole entry, with anything shorter than an entry after it — an entry cut by a snap length, or an Ethernet FCS — in `remainder`; past the header neither decode nor any accessor raises. Against a wrong port guess, `decode()` rejects a version other than 1 or 2 and command 0 (`InvalidFieldError`), which 99.2% of random datagrams fail; construction accepts them. The other commands, TraceOn to Update Acknowledge (`command_name`, with IANA's names), and RIPv1 messages with nonzero must-be-zero fields decode. RIPng (RFC 2080, UDP 521, the IPv6 protocol) is not decoded; RIP itself has no IPv6 form.
+- **`OSPF`: OSPFv2 (RFC 2328), IP protocol 89 (#183).** IPv4 protocol 89 (`IPProtocol.OSPF`, "OSPF") now dispatches to `netprotocols.OSPF` (also `netprotocols.layer3.OSPF`), which decodes the 24-byte common header — `version`, `type`, `packet_length`, `router_id`, `area_id`, `checksum`, `instance_id` and `au_type` (one byte each: RFC 6549 §2 split RFC 2328's 16-bit AuType into an Instance ID and an 8-bit AuType), the raw 8-byte `authentication` — and keeps the message as raw `body`, so `bytes(OSPF.decode(x)) == x[:header_len]` by construction. One accessor per message type parses the body on demand and returns `None` for the other types: `hello` (`OSPFHello`: network mask, hello and dead intervals, options, priority, DR, BDR and the neighbor list), `database_description` (`OSPFDatabaseDescription`: interface MTU, options, the I/M/MS flags, DD sequence number and its `OSPFLSAHeader`s), `ls_requests` (`OSPFLSRequest`s), `lsas` (a Link State Update's `OSPFLSA`s, each a decoded 20-byte `OSPFLSAHeader` and a raw `body`) and `ls_acknowledgments` (`OSPFLSAHeader`s). **LSA bodies are not decoded**: the Router, Network, Summary and AS-external (and other) LSA contents stay raw `bytes`, as follow-up work. `decode()` and the constructor check each known message's framing (whole neighbors, LSA headers and requests; an update's LSA count and lengths walking its body exactly), raising `InvalidFieldError` with `field="body"` otherwise, so no accessor raises; a type outside 1-5 keeps its body as is. Packet Length bounds the packet: below 24 raises `InvalidFieldError`, past the buffer `TruncatedHeaderError`. Under cryptographic authentication (AuType 2) the digest after the packet, Auth Data Len bytes, is kept in `auth_trailer` and counted in `header_len`, with `key_id`, `auth_data_len` and `crypto_sequence_number` accessors; AuType 3 (RFC 7474, extended sequence numbers) is framed the same way, its trailer the 64-bit sequence number and the digest, which Auth Data Len counts together, and the same accessors read its 32-bit Key ID and 64-bit sequence number; nothing else after the packet is consumed, so an RFC 5613 LLS block, Ethernet padding or an FCS is left after the OSPF layer. Records have `__bytes__`, so a packet can be built from them, and display helpers (`type_name`, `au_type_name`, `options_str`, `flags_str`, `ls_type_name`, hex strings). Only version 2 decodes: OSPFv3 (RFC 5340), which IPv6 carries under the same number, is not implemented, so `ip.proto.v6` withholds protocol 89 (`_defaults.IPV4_ONLY_NUMBERS`) and an IPv6 packet with next header 89 still ends its walk at the IPv6 header; `OSPF.decode()` rejects version 3 with `InvalidFieldError` (`field="version"`) for a caller who sends it there anyway. The registry gains the private mechanism for that: a withheld key owns no class, inheritance skips it as it skips an override, `derive()` copies it, and a registration made directly in the child table fills it.
+- **OSPF checksums in `netprotocols.checksum` (the new functions are also exported from `netprotocols`).** `compute(ospf)` is the internet checksum of the packet with its checksum field zeroed and its Authentication field left out (RFC 2328 §D.4.1), no pseudo-header (`ip` and `payload` are ignored); under cryptographic authentication (AuType 2 or 3), which computes none (§D.4.3; RFC 7474 §5 keeps that for AuType 3), `compute()` raises `InvalidFieldError`, `verify()` returns `True` (the digest, which this library cannot check without the key, protects the packet) and `Packet.with_checksums()` leaves the field alone. New `fletcher_checksum(data, offset)` computes the ISO 8473 Fletcher checksum field (RFC 905 Annex B), raising `ValueError` unless the 2-byte field at `offset` lies inside `data`. `lsa_checksum(lsa)` generates an `OSPFLSA`'s LS Checksum, over the LSA but its LS Age (RFC 2328 §12.1.7), and `verify_lsa(lsa)` checks it as RFC 905 B.4 does, by both running sums being zero, so a field stored with `0x00` where the generator writes `0xff` (equal modulo 255) verifies too, plus RFC 2328 §12.1.7's rule that the LS Checksum cannot be zero: a field of `0x0000` fails even where those sums are zero.
+- **PIM-SM (#184): `netprotocols.PIM`, layer 3, RFC 7761.** IP protocol 103 (`IPProtocol.PIM`, "PIM") now dispatches from IPv4 and IPv6, extension headers included, to one `PIM` class for both families, which decodes the 4-byte common header (`version`, `type`, `reserved`, `checksum`) and keeps the rest as raw `body`, so `bytes(PIM.decode(x)) == x[:header_len]` holds by construction. `PIM.message` dispatches on `type`, through a parser table in the shape of IGMP's message types, to a typed message parsed on demand: `PIMHello` (type 0; its option TLVs as `PIMHelloOption(type, value)` with `type_name`, plus `holdtime`, `lan_prune_delay` (`PIMLANPruneDelay`), `dr_priority`, `generation_id` and `address_list` read from them), `PIMRegister` (1; the B and N bits and the encapsulated packet, which `encapsulated` decodes in a lax walk from its IP header), `PIMRegisterStop` (2), `PIMJoinPrune` (3, and Graft and Graft-Ack, 6 and 7, which share its format; `PIMGroupSet`s of joined and pruned sources) and `PIMAssert` (5). Bootstrap (4), Candidate-RP-Advertisement (8), State Refresh (9) and other types decode with their body raw, and `message` is `None` for them; `type_name` names types 0-12 (DF Election, ECMP Redirect and PIM Flooding Mechanism, 10-12, from the IANA registry). Encoded-Unicast, Encoded-Group and Encoded-Source addresses (§4.9.1) are `PIMEncodedUnicast`, `PIMEncodedGroup` (with `bidirectional`, `admin_scope`) and `PIMEncodedSource` (with `sparse`, `wildcard`, `rpt`), sized by their own address family, so an IPv6-encoded message decodes whatever IP family carries it; only native IPv4 and IPv6 encodings are supported, and any other family or encoding (RFC 5384's join-attribute Encoded-Source included) makes `message` raise `InvalidFieldError`. Every typed message, option and address has a `bytes()`, so a message can be built from them. PIM has no length field, and the walk does not trim to the IP length, so `decode` bounds the message by its own structure: Join/Prune, Graft, Graft-Ack, Register-Stop and Assert end where their counts and addresses say, leaving any trailer (Ethernet padding, an FCS) undecoded; a Hello's options are walked and a run of zero bytes where the next option would start is left undecoded as padding; a Register's data packet and the raw types' bodies run to the end of the buffer. Past the header `decode` never raises: a body its parser cannot read (cut short, an unknown address family, a nonzero trailer after a Hello that does not walk) is kept whole, for `message` to raise on. A version other than 2 raises `InvalidFieldError` (`field="version"`) from `decode` and the constructor.
+- **PIM checksums in `compute`/`verify`/`Packet.with_checksums()`.** `compute(pim, ip=...)` is the internet checksum over the whole message, or over a Register's first 8 bytes (RFC 7761 §4.9.3), with the IPv6 pseudo-header (next header 103, the covered length) in front over IPv6 and none over IPv4; `ip` is required, since the family decides which. `verify()` also accepts a Register whose checksum covers the whole message, which §4.9.3 says should be accepted "for interoperability reasons"; `with_checksums()` fills PIM layers like the transports, so it rewrites such a Register to the 8-byte form.
+- **`BGP`: BGP-4 messages (RFC 4271) over TCP port 179 (#185).** TCP port 179 now dispatches, best-effort like every port entry, to `netprotocols.BGP` (also `netprotocols.layer7.BGP`), one message per instance: the 19-byte common header as `marker`, `length` and `type`, and the body kept raw in `body`, so `bytes(BGP.decode(x)) == x[:header_len]`, where `header_len` is the message's Length, not the buffer. Decode applies RFC 4271 §6.1's header checks — an all-ones Marker, a Type of 1-5 (OPEN, UPDATE, NOTIFICATION, KEEPALIVE, ROUTE-REFRESH) and that type's Length bounds (KEEPALIVE exactly 19, OPEN 29-4096, UPDATE and ROUTE-REFRESH from 23 and NOTIFICATION from 21, up to the 65535 of RFC 8654's extended messages) — and raises `TruncatedHeaderError` for a message the buffer cuts short. Accessors parse the body on demand and return `None` for other types: `version`, `my_as`, `hold_time`, `bgp_identifier`, `optional_parameters` (`BGPOptionalParameter`, either the RFC 4271 encoding or RFC 9072's extended one, flagged by `extended_optional_parameters` and recorded on each parameter as `extended_length`, which sets the width of the Parameter Length `bytes(parameter)` writes and is part of its equality; Capabilities named, its value raw) for OPEN; `withdrawn_routes` and `nlri` (`BGPPrefix`, IPv4, bit lengths up to 32) and `path_attributes` (`BGPPathAttribute`: flags, type code and raw `data`, the Attribute Length one or two bytes by the Extended Length flag; ORIGIN, NEXT_HOP, MULTI_EXIT_DISC and LOCAL_PREF values decoded in `value`, and every permanent type code in the IANA BGP Path Attributes registry named, its value kept raw) for UPDATE; `error_code`, `error_subcode`, `error_data`, their names as the IANA BGP Parameters registry (fetched 2026-10-25) assigns them (error codes 0-9 and the subcodes of every code with a subcode registry, RFC 4271 §4.5's "Unspecific" 0 for the codes without one), and an RFC 9003 `shutdown_communication` (strict UTF-8, `None` when absent or invalid) for NOTIFICATION. A malformed body raises `InvalidFieldError` from its accessor, not from decode. ROUTE-REFRESH's body stays raw. A TCP segment holding several messages decodes as one `BGP` layer each: `next_protocol()` answers `BGP` while another message begins in the same segment, which `decode()` records outside the instance's comparison and hash. A message the segment cuts raises `TruncatedHeaderError` (lax mode keeps the messages before it), a segment that starts inside one fails the Marker check, and reassembly stays the caller's, as for `HTTP`. Each message being a layer, a segment of more than 29 messages exceeds the default `max_depth`, so valid traffic can raise `MaxDepthExceededError` (or, lax, stop short): a 1448-byte segment holds up to 76 KEEPALIVEs or 30 one-prefix UPDATEs, and GRO, TSO, loopback and jumbo-frame captures carry larger segments. The module docstring, `walk.py`, ARCHITECTURE.md and `docs/CLAIMS.md` §5.7 document it and the two ways past it: a larger `max_depth`, or a second walk with `decode_frame(frame[packet.consumed:], start=BGP)`. Out of scope and left raw, as #185 asks: AS_PATH (its AS number width, 2 or 4 bytes, is negotiated in the OPENs), capability values, ADD-PATH path identifiers, ROUTE-REFRESH's fields and the MP_REACH/MP_UNREACH attributes that carry IPv6 routes. The capture host has no IPv6, so BGP over IPv6 is tested with constructed frames.
+
+### Development
+
+- **Every comparative number the README quotes was re-measured for this release** (Rule 4 of `docs/CLAIMS.md`), on the same machine class as 2.4.0's figures but on the 265-frame corpus Tier 2 grew from 140, against `dpkt 1.9.8` and `scapy 2.8.0`. **The README's "within 15% of dpkt on decode" no longer holds and is replaced**: dpkt decodes the corpus 1.30× faster (1.27-1.30× over three runs), while netprotocols stays 3.4× ahead of scapy. A file-by-file A/B against the 2.4.0 tree puts the gap in the five new routing captures, on which dpkt takes about two thirds of netprotocols' time, while the 140 frames 2.4.0 was measured on still read within 10% of dpkt on both trees, so it is the workload rather than a regression; why dpkt is faster on those protocols was not profiled. Encode is 4.62× ahead of dpkt, import 70.0 ms (from 55.0 ms, the five new modules) against `scapy.all`'s 396.9 ms, and the wheel is 176.5 KiB, 15.3× smaller than scapy 2.8.0's 2.63 MiB. Decode depth against dpkt is 79 of 265 frames deeper, the 40 new ones being the BGP and RIP frames, which dpkt leaves as raw bytes. `docs/CLAIMS.md` records each run, the per-file table and the A/B, and renames claim 1.2 for the figure it now holds.
+- **The decode benchmark baseline is re-recorded on the 265-frame corpus.** `benchmarks/baseline.json` was recorded at 2.2.1 on the 97-frame corpus (6.5677 normalized); it now holds 2.5.0 on 265 frames, 5.4344 normalized (97,453 f/s, 30 repetitions, best of 9, CPython 3.12.3), via `scripts/benchmark.py --update-baseline`. The corpus `--check` walks grew with Tier 1 and Tier 2 captures that cost more per frame than the old ones, so normalized throughput fell with the workload: the same library code read -14.1% on master (`03387af`) and -17.1% (-16.5% on the re-measure) on the release PR, either side of the 15% gate on runner noise alone, and the file-by-file A/B of 2.4.0 against 2.5.0 in `docs/CLAIMS.md` shows no regression beyond that harness's noise on the 140 frames 2.4.0 had. Re-anchoring accepts the drift since 2.2.1: the gate now guards against regressions relative to 2.5.0 on this corpus.
+- **A real BGP capture joins the corpus: `bgp.pcap`, 19 frames (265 across 27 scenarios), and its whole session goes into `tests/fixtures/bgp/`.** `scripts/capture_fixtures_bgp.sh` runs three BIRD 2.14 speakers in netns on one bridge, an eBGP and an iBGP session, with offload disabled, through OPENs, KEEPALIVEs, UPDATEs (five prefixes each with its own MED, 600 /24s that BIRD packs into a few UPDATEs, some longer than a segment), a withdrawal and a Cease NOTIFICATION with an RFC 9003 shutdown communication. It reassembles each direction to assert what was announced and withdrawn, prefix by prefix, and that the capture holds a segment of several whole messages, one of whole messages then a cut one, and one starting inside a message; it writes every frame to `bgp/bgp_session.pcap` (94 frames, outside the corpus globs) and the frames whose payload is whole messages to `bgp.pcap`. `scripts/check_fixtures.py` needed no change: it verifies the TCP checksums that cover the BGP payload. The corpus's deepest chain is now 10 layers (a segment of 7 UPDATEs); `walk.py` and `docs/CLAIMS.md` §5.7 say so. `tests/test_fuzz.py` gains BGP accessor-safety and built-UPDATE properties.
+- **A real PIM-SM capture joins the corpus: `pim.pcap`, 13 frames (246 across 26 scenarios).** `scripts/capture_fixtures_pim.sh` runs two FRR 8.4 routers (zebra + pimd) between a multicast source and an IGMPv3 receiver, four netns over three veth pairs, with static RPs on opposite routers for two groups so that a (*,G) tree and a Register exchange both cross the captured link, then has the receiver leave and stops one pimd. It keeps the first frame of each of 13 kinds — Hellos with Holdtime, LAN Prune Delay, DR Priority, Generation ID and Address List options, a Holdtime-0 goodbye, a data Register and a Null-Register, a Register-Stop, and Join/Prune messages with joined and pruned (*,G), (S,G) and (S,G,rpt) entries — and fails unless it saw all of them. FRR sums its Registers' checksums over the first 8 bytes. `scripts/check_fixtures.py` verifies every PIM checksum (IPv4, and IPv6 with its pseudo-header), accepts either Register form, and checks the Register's encapsulated packet in turn, skipping only a Null-Register's zero dummy IPv4 header checksum, which RFC 7761 says a receiver must not check; an IPv6 Null-Register's dummy PIM header (version 0, after the dummy IPv6 header) is checked by its own checksum over the dummy header's source and group, as §4.9.3 asks, rather than as a PIM message; `tests/test_pim.py` runs it on the frames and on tampered copies. The capture host has no IPv6, so PIM over IPv6 is covered by constructed frames whose pseudo-header checksums the test computes itself; Assert, Graft and the raw types are covered by constructed messages, and real frames are tested with zero padding and a 4-byte trailer appended. PIM joins the fuzz suite (`ALL_PROTOCOLS`, a round-trip strategy, an accessor-safety property and trailer properties), the truncation and damaged-payload contract tests, the corpus checksum cases and the corpus coverage set.
+- **`_tlv.walk_kind_length_value` takes a `width`** (default 1), the size of the kind and length fields, so PIM Hello options (2-byte type and length) walk through it. The floor and overrun message are now derived once per call, which takes the walker from radon C (13) to B (10); a seeded 3000-case comparison against a verbatim copy of the previous walker pins every byte-wide caller (TCP, IPv4, IPv6 options) to identical results and errors. `checksum.compute()`'s PIM arm is one call to a `_pim_checksum` helper, beside the `_pseudo_header_checksum` helper the ICMPv6, TCP and UDP arms already use, so `compute()` stays at radon B. The scoped mutation runs on `netprotocols._tlv.*` and `netprotocols.checksum.*` leave no survivor beyond the one already allowlisted.
+- **A real OSPFv2 capture joins the corpus: `ospf.pcap`, 54 frames (233 across 25 scenarios).** `scripts/capture_fixtures_ospf.sh` runs FRR 8.4's `zebra` and `ospfd` in two netns over a veth pair and captures three adjacencies in turn, one per AuType (none, simple password, keyed MD5), each with every message type: Hellos, the Database Description exchange, Link State Requests, Link State Updates carrying router, network and AS-external LSAs, and Link State Acknowledgments. The script fails unless each adjacency holds exactly 6 Hellos, 5 Database Descriptions, 2 requests, 2 acknowledgments and six LSAs (two router LSAs from each router, A's network and AS-external LSAs) in 3 or 4 updates, and no frame carries data after its packet (FRR sent no LLS). The test password and MD5 key are published in `tests/fixtures/MANIFEST.md`. `scripts/check_fixtures.py` verifies, with its own implementations, every AuType 0/1 packet checksum, the AuType 1 password, every AuType 2 keyed-MD5 digest (and that its packet checksum is zero) and every LSA's Fletcher checksum, in RFC 905 B.4's verification form plus RFC 2328 §12.1.7's rule that it is never zero; it reads AuType from header byte 15, past RFC 6549's Instance ID. `tests/test_ospf.py` loads the checker and holds it to failing a flipped body byte, LSA byte, password byte, digest byte, key ID and checksum, two swapped LSA bytes (which move only one Fletcher sum), a change that moves only the other, and an LS Checksum of `0x0000` whose sums are zero, and to passing a valid frame with a nonzero Instance ID. The kernel had no IPv6, so OSPFv3 over IPv6 is covered by a constructed frame, as are LLS blocks, padding and FCS trailers. `OSPF` joins the fuzz suite (`ALL_PROTOCOLS`, a round-trip strategy built from the message records, and an accessor-safety property that also feeds OSPF-shaped buffers), the truncation and lying-length contract tests, the corpus checksum cases and the corpus coverage set. The registry tests now hold `ip.proto` and `ip.proto.v6` to differing at the IPv6-only numbers, at 51, and at 89, which only `ip.proto` holds.
+- **A real RIP capture joins the corpus: `rip.pcap`, 21 frames (179 across 24 scenarios).** `scripts/capture_fixtures_rip.sh` runs two BIRD 2.14 routers in two netns over a veth pair through five scenarios — RIPv1 broadcast, RIPv2 multicast, a plain-text password, keyed MD5 and HMAC-SHA-256 — and keeps a fixed, asserted selection of each: every router's first Request and first Response, and one whole-table periodic update with poisoned-reverse routes. `scripts/check_fixtures.py` now verifies each RFC 4822 digest with the published test keys (`rip-keyed-md5`, `rip-hmac-sha256`), fails on a Key ID with no published key (`rip-unknown-sa`) or a missing trailer header (`rip-trailer`), and counts RIP datagrams (`rip`); its VXLAN peeling moves into `_check_vxlan`. `RIP` joins the fuzz suite (`ALL_PROTOCOLS`, a round-trip strategy, and a property that decode and every accessor are total and that entries, trailer and remainder tile the body), the contract tests (truncation, a trailer and a cut entry under strict and lax walks) and the corpus coverage set.
+- **A real VRRP capture joins the corpus: `vrrp.pcap`, 18 frames (158 across 23 scenarios).** `scripts/capture_fixtures_vrrp.sh` runs keepalived 2.2.8 as two routers in two netns over a veth pair through four virtual routers: VRRPv2 with `auth_type PASS` and two addresses, failing over from A to B with a priority-0 advert from each; VRRPv2 without authentication; VRRPv3 with one address, failing over the same way; and VRRPv3 unicast with three addresses and a 0.5 s interval. A master advertises for as long as it runs, so the script drives each step by watching the capture, keeps each router's first two live adverts and its resignation per segment, and fails unless the kept frames are exactly those 18. keepalived builds each IPv4 header (`IP_HDRINCL`) and every VRRP byte; the kernel fills the IPv4 header checksum. `scripts/check_fixtures.py` verifies every VRRP checksum independently (no pseudo-header for VRRPv2, the IPv4 or IPv6 one for VRRPv3), and fails a message whose length disagrees with its version and count or the IP payload, a version other than 2 or 3, and VRRPv2 over IPv6. veth does not pad, so Ethernet padding, a nonzero trailer and VRRPv3 over IPv6 (the capture host has no IPv6) are covered by constructed frames in `tests/test_vrrp.py`, whose checksums it computes itself and also runs through `check_fixtures.py`, as it does tampered copies of the capture. `VRRP` and `VRRPv6` join the fuzz suite (`ALL_PROTOCOLS`, round-trip strategies, an accessor property, a padding and trailer property), the truncation contract test, the corpus coverage set and `tests/test_checksum.py`; `checksum.compute()`'s UDP arm moves into a helper, as GRE's and SCTP's did, to keep its complexity where it was.
+
 ## [2.4.0] - 2026-10-25
 
 ### Added

{netprotocols-2.4.0 → netprotocols-2.5.0}/CONTRIBUTING.md

@@ -39,14 +39,14 @@ is 80; Markdown is excluded from linting.
 src/netprotocols/
   _base.py        the Protocol base class and the decode contract
   _enums.py       EtherType / IPProtocol / ARP* registries + display names
-  checksum.py     RFC 1071 internet checksum, SCTP's CRC32c,
-                  compute()/verify()
+  checksum.py     RFC 1071 internet checksum, SCTP's CRC32c, the
+                  Fletcher checksum of OSPF's LSAs, compute()/verify()
   packet.py       Packet: an ordered stack of headers, with_checksums()
   layer2/         Ethernet, VLAN, ARP
   layer3/         IPv4, IPv6, IPv6 extension headers, ICMPv4/v6, IGMP,
-                  GRE, IPsec ESP and AH
+                  GRE, IPsec ESP and AH, VRRP, OSPFv2, PIM
   layer4/         TCP, UDP, SCTP (+ port-based dispatch)
-  layer7/         DNS, DHCP, HTTP, VXLAN
+  layer7/         DNS, DHCP, HTTP, VXLAN, RIP, BGP
   utils/          exceptions, MAC/IPv4 helpers
 tests/            unit tests, corpus invariants, fuzzing, fixtures/
 scripts/          fixture capture + validation
@@ -61,7 +61,9 @@ subclass of `ProtocolError` (never a bare `struct.error` or
 `ValueError`) on malformed input. (SCTP, which has no length field
 and a CRC32c that trailing zeros change, finds its own extent instead:
 it leaves only zero padding after it undecoded, and keeps any other
-trailing or unparseable bytes in its `chunks` rather than raising.)
+trailing or unparseable bytes in its `chunks` rather than raising.
+PIM, which has no length field either, ends a message where its own
+structure does and keeps a body it cannot parse whole, likewise.)
 The authoritative description lives in the module docstring of
 [`src/netprotocols/_base.py`](src/netprotocols/_base.py) — read it
 before adding a protocol.

{netprotocols-2.4.0 → netprotocols-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: netprotocols
-Version: 2.4.0
+Version: 2.5.0
 Summary: Low-level implementations of common networking protocols
 Project-URL: Homepage, https://github.com/EONRaider/NETProtocols
 Project-URL: Repository, https://github.com/EONRaider/NETProtocols
@@ -76,31 +76,33 @@ Requires Python 3.12+. Fully typed (`py.typed`, mypy strict).
 
 ## Why NETProtocols
 
-Measured against `dpkt 1.9.8` and `scapy 2.8.0` on the 140-frame corpus
+Measured against `dpkt 1.9.8` and `scapy 2.8.0` on the 265-frame corpus
 of real captured traffic (CPython 3.12.3, x86-64 Linux; re-measured for
-2.4.0 on 2026-10-25 — see [docs/CLAIMS.md](docs/CLAIMS.md) for every
+2.5.0 on 2026-10-25 — see [docs/CLAIMS.md](docs/CLAIMS.md) for every
 number below, its reproduction command, and its caveats):
 
-- **Within 15% of dpkt on decode, 4.1× faster than scapy** —
+- **3.4× faster than scapy on decode; dpkt is 1.3× faster** —
   `uv run --group bench python scripts/benchmark.py --compare`. dpkt is
-  the faster of the two comparators, and on this corpus it and
-  netprotocols are at parity, the sign of the gap flipping between
-  runs. The gap moves both ways as this library and dpkt each change, and this
-  file's job is to say so honestly rather than only when it's
+  the faster of the two comparators. On the 140 frames the corpus held
+  at 2.4.0 the two are still within 10% of each other; the
+  routing captures 2.5.0 added (OSPF, BGP, PIM, RIP, VRRP) are where
+  dpkt pulls ahead, taking about two thirds of netprotocols' time on
+  them. The gap moves both ways as this library and dpkt each change,
+  and this file's job is to say so honestly rather than only when it's
   flattering.
-- **Decodes further into the stack than dpkt on 39 of those 140
-  frames** — DNS, DHCP and VXLAN-tunnelled payloads that dpkt leaves as
-  raw bytes, and 802.1Q tags it folds into the Ethernet header,
-  netprotocols decodes as layers of their own. A throughput number
-  means little without knowing how much work it bought.
-- **4.2× faster than dpkt at re-encoding** (`bytes(header)`,
+- **Decodes further into the stack than dpkt on 79 of those 265
+  frames** — BGP, RIP, DNS, DHCP and VXLAN-tunnelled payloads that dpkt
+  leaves as raw bytes, and 802.1Q tags it folds into the Ethernet
+  header, netprotocols decodes as layers of their own. A throughput
+  number means little without knowing how much work it bought.
+- **4.6× faster than dpkt at re-encoding** (`bytes(header)`,
   `scripts/benchmark_encode.py`) — the other half of "codec" that
   nobody else benchmarks.
-- **Imports in 55 ms; `scapy.all` takes 428+ ms** (`scripts/benchmark_import.py`),
+- **Imports in 70 ms; `scapy.all` takes 397+ ms** (`scripts/benchmark_import.py`),
   and never touches the host doing it — importing scapy populates live
   interface and routing tables as a side effect of the import
   statement.
-- **A 124.4 KiB wheel against scapy's 2.63 MiB** — 21.7× smaller.
+- **A 176.5 KiB wheel against scapy's 2.63 MiB** — 15.3× smaller.
 - **Regression-gated in CI, which — as far as we could establish by
   auditing ten comparable Python packet libraries' CI configurations
   (dpkt, scapy, pypacker, construct, pcapkit, dnspython, pyshark,
@@ -178,12 +180,17 @@ ip.proto                  → error: "IPv4" has no attribute
 | 3 | IP-in-IP | `IPv4`, `IPv6` | RFC 2003/4213/2473, IP protocols 4 and 41; no header of its own, so the outer IP header dispatches straight to the inner one |
 | 3 | IPsec ESP | `ESP` | RFC 4303, IP protocol 50; SPI and sequence number decoded, the protected remainder kept as opaque `ciphertext` — the chain ends here by design, since without the Security Association nothing says where the Next Header is |
 | 3 | IPsec AH | `AH`, `AHv6` | RFC 4302, IP protocol 51; fixed fields decoded and the ICV kept raw (never verified), then the payload chains onward by `next_header` through the outer IP family's table — `AHv6`, an `AH` subclass, is what IPv6 dispatches to |
+| 3 | OSPFv2 | `OSPF` | RFC 2328, IP protocol 89 over IPv4; the 24-byte header, then Hello, Database Description, LS Request, LS Update and LS Acknowledgment parsed by typed accessors; LSA headers decoded, LSA bodies kept raw; packet checksum and LSA Fletcher checksum compute/verify. OSPFv3 (RFC 5340, IPv6) is not decoded: IPv6 protocol 89 ends the walk |
+| 3 | PIM-SM | `PIM` | RFC 7761, IP protocol 103 from IPv4 and IPv6; common header + message-type dispatch: Hello options, Register (encapsulated packet decodable), Register-Stop, Join/Prune (also Graft/Graft-Ack), Assert parsed on demand; other types kept raw; checksum compute/verify, IPv6 pseudo-header included |
+| 3 | VRRP | `VRRP`, `VRRPv6` | RFC 3768 (VRRPv2) and RFC 5798 (VRRPv3), IP protocol 112; one class branches on the version nibble (VRRPv2's Auth Type, Adver Int and authentication data; VRRPv3's Max Adver Int) and decodes the virtual-address list at the width of the IP family that carried it — `VRRPv6`, a `VRRP` subclass, is what IPv6 dispatches to; checksum compute/verify |
 | 4 | TCP | `TCP` | RFC 9293, data-offset/options aware |
 | 4 | UDP | `UDP` | RFC 768 |
 | 4 | SCTP | `SCTP` | RFC 9260, IP protocol 132; common header + chunk list (`SCTPChunk`) parsed on demand; CRC32c compute/verify |
 | 7 | DNS | `DNS` | RFC 1035, over UDP and TCP (`DNSOverTCP` length shim); on-demand name decompression + resource-record parsing |
 | 7 | DHCP | `DHCP` | RFC 2131/2132, over UDP 67/68; TLV options parsed on demand |
 | 7 | VXLAN | `VXLAN` | RFC 7348, over UDP 4789; the payload is a whole Ethernet frame, which walks on through the EtherType table |
+| 7 | RIP | `RIP` | RFC 1058/2453, RIPv1 and RIPv2 over UDP 520; route entries (`RIPEntry`) and the authentication entry (`RIPAuthentication`: plain-text password, RFC 4822 keyed MD5/HMAC-SHA) parsed on demand; RIPng is not decoded |
+| 7 | BGP-4 | `BGP` | RFC 4271, over TCP 179; one layer per message, chaining to the next in the same segment; OPEN fields and optional parameters, UPDATE withdrawn routes, path attributes (`BGPPathAttribute`, ORIGIN/NEXT_HOP/MED/LOCAL_PREF values decoded) and NLRI (`BGPPrefix`), NOTIFICATION codes; KEEPALIVE and ROUTE-REFRESH; no reassembly |
 | 7 | HTTP/1.1 | `HTTP` | RFC 9112/9110; one message per decode from a buffer you reassembled; ambiguities reported as anomalies; not port-dispatched |
 
 ## Decoding a captured frame
@@ -458,7 +465,9 @@ raw = bytes(frame)  # ready for a raw socket
 
 Checksums are computed and verified on request — never silently:
 `compute()`/`verify()` in `netprotocols.checksum` (the internet
-checksum, and SCTP's CRC32c via `crc32c()`), and
+checksum, VRRP's with or without its pseudo-header by version, PIM's,
+and SCTP's CRC32c via `crc32c()`; OSPF's LSA checksums via
+`lsa_checksum()`/`verify_lsa()`), and
 `Packet.with_checksums()` to fill a whole stack before sending.
 
 ## Display helpers
@@ -497,7 +506,13 @@ and SCTP
 [#231](https://github.com/EONRaider/NETProtocols/pull/231),
 [#232](https://github.com/EONRaider/NETProtocols/pull/232),
 [#233](https://github.com/EONRaider/NETProtocols/pull/233),
-[#234](https://github.com/EONRaider/NETProtocols/pull/234)) — as 2.4.0
+[#234](https://github.com/EONRaider/NETProtocols/pull/234)) — as 2.4.0,
+and the second — VRRP, RIP, OSPF, PIM and BGP
+([#243](https://github.com/EONRaider/NETProtocols/pull/243),
+[#245](https://github.com/EONRaider/NETProtocols/pull/245),
+[#246](https://github.com/EONRaider/NETProtocols/pull/246),
+[#247](https://github.com/EONRaider/NETProtocols/pull/247),
+[#248](https://github.com/EONRaider/NETProtocols/pull/248)) — as 2.5.0
 (see [CHANGELOG.md](CHANGELOG.md)).
 
 The roadmap before it, the post-1.3.0
@@ -524,7 +539,7 @@ released as
 2.1.0's and 1.3.1/1.4.0's work shipped folded into 2.0.0 and 2.2.0
 rather than as their own versions, but the roadmap's original "only at
 a major version bump" release policy wasn't actually held to: 2.0.0,
-2.2.0, 2.2.1, 2.3.0 and now 2.4.0 are all on PyPI, and the comparative claims above
+2.2.0, 2.2.1, 2.3.0, 2.4.0 and now 2.5.0 are all on PyPI, and the comparative claims above
 draw on the finished tree. The wave before that one — TCP
 and IPv4 option parsing, ICMP message bodies, NDP, IPv6
 extension-header TLV options, the GRE checksum arm, a DNS-over-TCP
@@ -537,7 +552,7 @@ Development uses [uv](https://docs.astral.sh/uv/): `uv sync`, then
 `uv run pytest`, `uv run mypy`, and `uv run ruff check` — all three are
 enforced by CI; the test suite runs across Python 3.12–3.14, while
 `mypy` and `ruff check` run on 3.12. The test suite is anchored by a
-140-frame corpus of real captured traffic across 22 scenarios
+265-frame corpus of real captured traffic across 27 scenarios
 ([tests/fixtures/MANIFEST.md](tests/fixtures/MANIFEST.md), which says
 which layers a script built rather than the kernel) plus
 property-based fuzzing of the decode path. See