netprotocols 2.4.0__tar.gz → 2.6.0__tar.gz

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

@@ -140,7 +140,10 @@ the same three rules (spelled out in [`_base.py`](src/netprotocols/_base.py)):
 1. **It receives the entire remaining buffer** — everything from the
    start of its header to the end of the captured frame — and parses
    the fixed portion with `_struct.unpack_from`. A buffer too short
-   for the fixed portion raises `TruncatedHeaderError`.
+   for the fixed portion raises `TruncatedHeaderError`. One enclosing
+   length shortens that buffer in a walk: after an Ethernet or VLAN
+   header holding an IEEE 802.3 Length, every later layer's buffer ends
+   where the Length ends the LLC PDU (see *802.3 framing* below).
 2. **Variable-length headers finish the job themselves.** IPv4 reads
    its IHL and TCP reads its data offset, sanity-checks it (5–15, and
    the declared bytes must exist in the buffer — a header that *lies*
@@ -151,7 +154,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 +188,113 @@ 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.
+`STP` is the same case at layer 2: a BPDU has no length field, but its
+BPDU Type gives its exact length (4, 35 or 36 octets), so it leaves
+whatever follows undecoded, including the extra octets of a PDU longer
+than its BPDU, which a receiver ignores (§14.4 of the IEEE 802.1 draft
+the module cites). See
+[`layer2/stp.py`](src/netprotocols/layer2/stp.py)'s module docstring.
+
+`LLDP` has no length for the whole LLDPDU either, but bounds itself
+by its last TLV: its TLVs each carry a Length, and the End of LLDPDU
+TLV ends the walk, so it obeys rule 3 like a header with a length
+field and leaves Ethernet's padding and an FCS undecoded. A TLV whose
+Length runs past the buffer raises `TruncatedHeaderError`, as a lying
+length does in rule 2. Wireshark's dissector notes that 802.1AB-2016
+made the End TLV optional, so an LLDPDU that reaches the end of the
+buffer without one decodes too; there nothing marks where a trailer
+starts, so the walk reads one as TLVs: two or more zero bytes read as
+an End TLV, and other bytes as another TLV or a framing error. The
+mandatory Chassis ID, Port ID and Time To Live TLVs are read by
+accessors from the first three positions, which answer `None` rather
+than raise when the order is broken, since that is not framing. See
+[`layer2/lldp.py`](src/netprotocols/layer2/lldp.py)'s module
+docstring.
+
+**802.3 framing.** Bytes 12-13 of an Ethernet header are a type or a
+length (IEEE 802.3 Clause 3.2.6): from 0x0600 an EtherType, up to 1500
+the length of an IEEE 802.2 LLC PDU, and undefined between, where the
+walk ends. `Ethernet.ethertype` holds the raw value either way, and
+`VLAN` reads the 2 bytes after a tag the same way. Neither `LLC` nor
+`SNAP` has a length of its own, and a short PDU arrives padded to
+Ethernet's minimum, often with an FCS after it; STP's BPDUs are that
+short, and CDP's checksum covers exactly its PDU. So the Length is the
+one enclosing length `decode_frame()` honours: after a header that
+holds one (a class setting `_BOUNDS_PAYLOAD`, answering
+`_payload_extent()`, both private while #235 settles the public form),
+it ends the buffer it hands every later layer at the PDU's end. A
+bound past the end of the frame bounds nothing, so a frame a snap
+length cut decodes what was captured; a later, looser bound never
+widens an earlier one; and a Length shorter than the LLC header leaves
+`LLC.decode()` too few bytes, so the walk raises
+`TruncatedHeaderError`. IPv4's, IPv6's and UDP's lengths are still not
+honoured (#235), so padding behind a short IPv4 packet in Ethernet II
+framing reaches its last layer as before. A third-party tag header
+(an E-tag, a VN-tag) can answer `LLC` from its own `next_protocol()`,
+but can bound the PDU after it only through that private hook, pending
+#235. Called directly,
+`LLC.decode()` has no Length to go by and leaves the rest of its buffer
+to the caller, who can slice `frame[14 : 14 + eth.length]`. See
+[`layer2/llc.py`](src/netprotocols/layer2/llc.py)'s module docstring.
+
+`CDP`, which SNAP dispatches at OUI 00-00-0C PID 0x2000, is the first
+decoder behind that bound. It has no length of its own: its TLVs run to
+the end of the PDU, and its checksum covers the whole PDU, so in a walk
+it decodes the PDU and nothing else. Its `decode()` walks TLVs
+to the end of the buffer it is handed and stops early, without
+raising, only where every byte left is zero, so Ethernet's zero padding
+is left undecoded when it is called directly; rule 3 holds for those
+zeros only, as for SCTP. Otherwise a TLV Length below 4 raises
+`InvalidFieldError`, 1-3 bytes left after the last TLV raise
+`TruncatedHeaderError`, and so does a TLV whose Length runs past the
+buffer, in a walk too, where those bytes are inside the 802.3 Length.
+Wireshark's dissector instead stops at a Length below 4 whatever
+follows, and marks 1-3 bytes left malformed even when they are zero.
+The zero rule has one blind spot: zeros after the last TLV but inside
+the 802.3 Length belong to the PDU the sender declared, yet a walk
+leaves them undecoded without raising, so `consumed` stopping short of
+the Length's end is the only structural signal. `verify()` sums the
+bytes decoded, without them; where the TLVs end at an odd offset on a
+nonzero byte and the sender summed the whole Length, it returns
+`False`.
+`scripts/check_fixtures.py` rejects such a frame, and Wireshark marks
+1-3 such zeros malformed and shows 4 or more as a TLV of invalid
+Length 0.
+See [`layer2/cdp.py`](src/netprotocols/layer2/cdp.py)'s module
+docstring.
+
 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 +326,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,24 +363,66 @@ 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`, `MPLS` and `LLC` are the three exceptions: they answer from
+decode context rather than from a wire field alone. 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. An MPLS label stack carries
+a packet but no field naming its protocol (see *MPLS: dispatch by
+convention* below), so `MPLS.next_protocol()` infers one, partly from
+the first byte after the stack. SAP 0x42 carries GARP's PDUs (Protocol
+Identifier 0x0001) beside STP's BPDUs (0x0000), so `LLC.decode()`
+records, for a DSAP 0x42 PDU it would dispatch, whether the two octets
+after its Control are present and not 0x0000, and `LLC.next_protocol()`
+then answers `None`, whatever `llc.dsap` holds at 0x42; fewer than two
+octets still reach `STP`, which reports the truncation. Only the bytes
+can say, and `next_protocol()` is handed none, so each `decode()`
+records what it saw 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 headers compare equal
+however they were found, and can still chain differently. The rules of
+the decode contract hold for all three unchanged; see *Port-based
+dispatch is best-effort* below,
+[`_base.py`](src/netprotocols/_base.py)'s *Decode context in
+next_protocol*, the module docstrings of
+[`layer7/bgp.py`](src/netprotocols/layer7/bgp.py) and
+[`layer2/mpls.py`](src/netprotocols/layer2/mpls.py), and
+[`layer2/llc.py`](src/netprotocols/layer2/llc.py)'s *DSAP 0x42*.
+
 ```mermaid
 flowchart LR
   E[Ethernet] -->|0x0806| A[ARP]
   E -->|0x0800| I4[IPv4]
   E -->|0x86DD| I6[IPv6]
   E -->|0x8100, 0x88A8, 0x9100| V[VLAN tag]
+  E -->|length ≤ 1500| L[LLC]
+  V -->|length ≤ 1500| L
+  L -->|DSAP 0xAA, SSAP 0xAA, UI| SN[SNAP]
+  L -->|DSAP 0x42, UI or I, Protocol ID 0| STP[STP BPDU]
+  SN -->|OUI 00-00-00 or 00-00-F8, PID 0x0806| A
+  SN -->|OUI 00-00-00 or 00-00-F8, PID 0x0800| I4
+  SN -->|OUI 00-00-0C, PID 0x2000| CDP[CDP]
   V -->|0x8100, 0x88A8, 0x9100| V
   V -->|0x0806| A
   V -->|0x0800| I4
   V -->|0x86DD| I6
+  E -->|0x8847, 0x8848| M[MPLS label stack]
+  V -->|0x8847, 0x8848| M
+  M -->|bottom label 0, or first nibble 4| I4
+  M -->|bottom label 2, or first nibble 6| I6
+  E -->|0x88CC| LD[LLDP]
+  V -->|0x88CC| LD
   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
@@ -290,8 +446,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 +469,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.
 
@@ -325,13 +491,45 @@ bitfields — `pcp`, `dei`, `vid` — as dataclass fields validated in
 property (the same pattern `IPv6` uses for `version` /
 `traffic_class` / `flow_label`).
 
+**MPLS: dispatch by convention.** An MPLS label stack (RFC 3032) sits
+where a VLAN tag does, after Ethernet's EtherType (0x8847, or 0x8848
+for a multicast frame whose top label is upstream-assigned, RFC 5332),
+and decodes as one `MPLS` layer however many 4-byte entries it holds:
+the stack ends at the entry with its Bottom of Stack bit set, so it
+bounds itself, and a deep stack counts once against `max_depth`. What
+it does not have is a field naming the packet it carries. RFC 3032
+§2.2 leaves that to the binding of the label popped at the egress,
+which a capture never shows, so `MPLS.next_protocol()` follows a
+convention. A bottom label reserved for a payload settles it — 0, IPv4
+Explicit NULL, is IPv4 and 2, IPv6 Explicit NULL, is IPv6, whatever
+the bytes say, while 13 (GAL) and 14 (OAM Alert) are followed by a
+channel header or an OAM message and stop the walk. Otherwise the
+first nibble after the stack is read as an IP version, 4 or 6, as
+routers that load-balance IP over MPLS do (RFC 4928); anything else, a
+pseudowire control word's 0 among them, stops the walk. The class
+comes from the `ethertype` table at 0x0800 or 0x86DD, so a `registry`
+or `decode_as` override reaches the labelled packet too. The nibble is
+a guess, as a port is: an Ethernet pseudowire sent without a control
+word, whose inner destination MAC address happens to begin with 4 or
+6, decodes as an IP header, which is the misreading RFC 4928 and RFC
+4385's control word exist to prevent. GRE dispatches its Protocol Type
+through the `ethertype` table too, so MPLS in GRE (RFC 4023) reaches
+`MPLS` with no code of its own. See
+[`layer2/mpls.py`](src/netprotocols/layer2/mpls.py)'s module
+docstring.
+
 The numbers on the arrows are the wire values — EtherTypes out of
-Ethernet, IP protocol numbers out of IPv4/IPv6 — and they live in
+Ethernet, IP protocol numbers out of IPv4/IPv6; MPLS's arrows, which
+no wire field names, are the convention above — 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
@@ -344,11 +542,13 @@ packet = decode_frame(frame)          # Packet(Ethernet(...), IPv4(...), TCP(...
 Underneath it is the loop the two answers imply:
 
 ```python
-layers, cursor, protocol = [], 0, start
+layers, cursor, end, protocol = [], 0, len(frame), start
 while protocol is not None:
-    header = protocol.decode(frame[cursor:])
+    header = protocol.decode(frame[cursor:end])
     layers.append(header)
     cursor += header.header_len
+    if header._BOUNDS_PAYLOAD:  # an 802.3 Length (see above)
+        end = _bounded(header, cursor, end)
     protocol = header.next_protocol(registry)
 ```
 
@@ -365,12 +565,14 @@ Wrapping each frame in a `memoryview` internally measured *slower*
 **Where do those arrows live?** Not in the protocol classes. Every
 one of them is a row in a dispatch table owned by
 [`registry.py`](src/netprotocols/registry.py), and `next_protocol()`
-is a single `dict.get` against one of five tables named after the wire
+is a single `dict.get` against one of seven tables named after the wire
 field they dispatch on:
 
 | Table | Dispatches on | Read by |
 |---|---|---|
-| `ethertype` | Ethernet II EtherType | `Ethernet`, `VLAN`, `GRE` |
+| `ethertype` | Ethernet II EtherType (from Ethernet and VLAN, 0x0600 and up only; from GRE and SNAP, any value) | `Ethernet`, `VLAN`, `GRE`, `SNAP` (OUI 00-00-00, 00-00-F8); `MPLS` at 0x0800 and 0x86DD, by convention |
+| `llc.dsap` | IEEE 802.2 LLC DSAP | `LLC` |
+| `llc.snap` | SNAP `(oui << 16) \| pid`, any other OUI | `SNAP` |
 | `ip.proto` | IPv4 `protocol` | `IPv4`, `AH` |
 | `ip.proto.v6` | IPv6 `next_header` | `IPv6`, extension headers, `AHv6` |
 | `udp.port` | UDP well-known port | `UDP` |
@@ -379,7 +581,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 +589,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
@@ -405,16 +620,18 @@ 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, a proprietary
-telemetry header — is one registration away from participating in
+protocol this library does not implement — a proprietary telemetry
+header, say, sent under 0x88B5, which IANA's EtherType registry lists
+as "IEEE Std 802 - Local Experimental Ethertype", so no built-in
+decoder holds it — is one registration away from participating in
 frame walks like any built-in:
 
 ```python
 from netprotocols import Protocol
 from netprotocols.registry import register
 
-@register("ethertype", 0x8847)
-class MPLS(Protocol):
+@register("ethertype", 0x88B5)
+class Telemetry(Protocol):
     ...
 ```
 
@@ -437,19 +654,23 @@ 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 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
+comes out of a table, never from an import. Three 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.
+quotes, which is not dispatch; `layer7/vxlan.py` names `Ethernet`
+directly, because a VXLAN payload is always an Ethernet frame; and
+`layer2/ethernet.py` names `LLC`, because whatever an 802.3 Length's
+value, an LLC header follows it. None can form a cycle: `ip.py` and
+`llc.py` import no other layer module, and `ethernet.py` imports only
+`llc.py`.
 
 ## Port-based dispatch is best-effort
 
-The `ethertype` and `ip.proto` tables dispatch on a single
-authoritative field: it exists to say what follows. The two port
-tables break that model, and differ in kind rather than just in name.
+The `ethertype`, `llc.*` and `ip.proto` tables dispatch on a single
+authoritative field: it exists to say what follows (MPLS, which looks
+up the `ethertype` table by convention, is the exception described
+above). The two port tables break that model, and differ in kind
+rather than just in name.
 A port is a *guess* — any service may run on any port, and the
 discriminator is split across the source and destination ports.
 Dispatch therefore checks the destination port first (a request
@@ -501,6 +722,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 +795,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 +834,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,27 +879,37 @@ 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 (CDP's odd-byte sum among them),
+│                   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)
+├── layer2/         ethernet.py, arp.py, vlan.py (802.1Q / 802.1ad),
+│                   llc.py (802.2 LLC + SNAP, after an 802.3 Length),
+│                   cdp.py (Cisco Discovery Protocol, after SNAP),
+│                   lldp.py (LLDP, IEEE 802.1AB),
+│                   mpls.py (MPLS label stack: MPLS + MPLSLabel),
+│                   stp.py (802.1D / 802.1w BPDUs)
 ├── 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),