feat: added TLV Types 246/247 behind the pnet backend, with nix U-flag fallback, and updated README and CHANGELOG.

Author: asmie

CHANGELOG.md

@@ -5,6 +5,64 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **draft-ietf-ippm-stamp-ext-hdr Reflected Fixed / IPv6 Extension Header Data
+  TLVs (Types 247 / 246)**: let the sender ask the reflector to echo the raw
+  bytes of the received IP fixed header (Type 247 — 20 B IPv4 or 40 B IPv6)
+  and IPv6 Hop-by-Hop / Destination Options extension headers (Type 246),
+  which allows end-to-end diagnostics of DSCP remarking, TTL decrement,
+  Flow Label rewriting, and in-path tampering with IPv6 options.
+  - New typed TLVs `ReflectedFixedHdrTlv` and `ReflectedIpv6ExtHdrTlv`
+    implementing `TypedTlv`, plus `TlvType::ReflectedFixedHdr` /
+    `ReflectedIpv6ExtHdr` enum variants and length validation that treats
+    the Value as variable-length (empty = sender request, populated =
+    reflector response).
+  - New `CapturedHeaders` struct threaded through `ProcessingContext` so the
+    reflector's TLV processing can see the raw IP-layer bytes captured at
+    receive time.
+  - New `TlvList::process_reflected_headers()` invoked from
+    `apply_semantic_tlv_processing` — copies captured bytes into the TLV or
+    sets the U-flag when the backend cannot observe the IP layer.
+  - `pnet` backend populates `CapturedHeaders` from `Ipv4Packet` / `Ipv6Packet`
+    and walks Hop-by-Hop (NextHeader=0) / Destination Options (NextHeader=60)
+    in wire format (NextHeader byte + HdrExtLen byte + body, per RFC 8200);
+    non-options headers (Routing, Fragment, ESP, AH) stop the walk, matching
+    the draft's scope. For IPv4 only the fixed 20-byte header is copied —
+    IPv4 options are intentionally dropped.
+  - `nix` backend passes `captured_headers: None` unconditionally; the
+    reflector echoes the TLV empty with the U-flag set per RFC 8972 §4.2
+    and emits a one-time log warning suggesting a rebuild with
+    `--features ttl-pnet` if header reflection is genuinely required. An
+    empty Value on an IPv4 packet or an IPv6 packet without extension
+    headers is legitimate and does **not** set the U-flag.
+  - Sender CLI: `--reflected-fixed-hdr`, `--reflected-ipv6-ext-hdr` (plus
+    matching `FileConfiguration` TOML fields). Sender attaches empty-request
+    TLVs; reflector fills them on the pnet backend or U-flags them on nix.
+
+### Changed
+
+- **Shared `build_local_addresses` between backends**: the interface-address
+  enumeration used for Destination Node Address TLV matching (RFC 9503 §4)
+  was duplicated in `receiver/nix.rs` and `receiver/pnet.rs` with platform-
+  specific implementations. Consolidated into a single
+  `receiver::build_local_addresses()` with `cfg(unix)` / `cfg(not(unix))`
+  internals — `nix::ifaddrs::getifaddrs` on Unix, `pnet::datalink::interfaces`
+  on Windows. Removes ~60 lines of near-duplicate code and a class of
+  drift bugs.
+
+### Documentation
+
+- README gained a **Receiver Backends** section explaining the two capture
+  paths (nix UDP socket + cmsg vs pnet datalink capture), why `nix` stays
+  the default on Linux/macOS (unprivileged execution, no libpcap runtime
+  dependency, kernel-side UDP demultiplex, firewall integration, kernel-
+  handled checksums / fragmentation / ARP, socket observability), and what
+  the tradeoff is (TLV 246/247 only on the pnet backend; two capture loops
+  to maintain).
+
 ## [0.6.0] - 2026-04-22
 
 ### Added

README.md

@@ -19,6 +19,7 @@ stamp-suite is a Rust implementation of the Simple Two-Way Active Measurement Pr
 - RFC 9534 Micro-session ID TLV for LAG per-member-link measurement
 - Reflected Test Packet Control TLV (draft-ietf-ippm-asymmetrical-pkts-14, Type 12) for asymmetrical reply measurement
 - Bit Error Rate TLVs (draft-gandhi-ippm-stamp-ber-05, Types 240/241/242) for residual BER measurement against a known padding pattern
+- Reflected Fixed/IPv6 Extension Header Data TLVs (draft-ietf-ippm-stamp-ext-hdr, Types 247/246) for header-transparency diagnostics — feature-gated to the pnet backend, gracefully U-flagged on the default nix backend
 - Class of Service (CoS) TLV support with DSCP/ECN measurement (RFC 8972 §5.2)
 - Location, Timestamp Info, Direct Measurement, Access Report, and Follow-Up Telemetry TLVs
 - HMAC authentication support
@@ -78,6 +79,90 @@ nix develop
 | `metrics` | Enable Prometheus metrics endpoint |
 | `snmp` | Enable SNMP AgentX sub-agent (Unix only) |
 
+### Receiver Backends
+
+The reflector has two receive-path backends. They differ in how they extract
+per-packet metadata (TTL, DSCP/ECN, destination address, raw IP headers), not in
+STAMP protocol behaviour — both go through the same `process_stamp_packet`
+pipeline.
+
+**`nix` backend (default on Linux and macOS)**
+
+Binds a normal `tokio::net::UdpSocket` and attaches `IP_RECVTTL`,
+`IP_RECVTOS`, and `IP_PKTINFO` (with IPv6 equivalents) so the kernel hands
+per-packet metadata through `recvmsg` control messages. The kernel performs UDP
+demultiplexing and checksum validation; userspace only sees traffic destined
+for the bound port.
+
+**`pnet` backend (default on Windows, opt-in elsewhere)**
+
+Captures frames at the datalink layer via libpcap / Npcap, parses Ethernet /
+IPv4 / IPv6 / UDP manually, and sends replies through a separate `UdpSocket`.
+Sees full IP headers, including IPv6 extension headers.
+
+#### Why nix is the default where it works
+
+Picking `pnet` everywhere would simplify the codebase slightly (one capture
+loop instead of two), but it would regress every Linux/macOS deployment on
+several independent axes:
+
+1. **Privileges.** The `nix` backend runs as an unprivileged user — it binds a
+   UDP port and that is it. The `pnet` backend needs `CAP_NET_RAW` (or
+   `setcap cap_net_raw=eip` on the binary, or plain root). That matters for
+   container images, systemd hardening, CI runners, SaaS deployments, and
+   anywhere security policy limits capabilities.
+
+2. **Runtime dependencies.** `nix` only needs libc. `pnet` links against
+   libpcap on Unix and Npcap on Windows; these must be installed out-of-band
+   before the binary will start. A statically-linked `nix` build drops into
+   minimal containers and immutable OS images without extra packaging work.
+
+3. **Kernel packet filtering.** With `nix`, the kernel demultiplexes UDP by
+   destination port before userspace wakes up — stamp-suite only ever sees
+   its own traffic. With `pnet`, every frame on the interface reaches
+   userspace; we then discard everything that is not UDP to our port. On a
+   10 Gb/s link carrying unrelated traffic this wastes CPU and causes
+   scheduling jitter that pollutes delay measurements.
+
+4. **Interaction with the host firewall.** `nix` goes through the normal
+   socket path, so `iptables` / `nftables` INPUT rules and per-socket
+   accounting behave exactly as the operator expects. `pnet` bypasses INPUT
+   on receive and can bypass OUTPUT on raw send, so host-level policy is
+   silently skipped.
+
+5. **Kernel does the heavy lifting.** `nix` lets the kernel handle UDP
+   checksum, fragmentation, path MTU discovery, ICMP unreachable, ARP /
+   NDP for the next hop, and routing-table changes. A pnet-everywhere
+   design would have to re-implement or work around each of these.
+
+6. **Observability.** The `nix` backend has a real socket visible to
+   `ss -u`, `netstat`, `lsof`, tracing tools, and systemd socket accounting.
+   The pnet backend has none of these handles.
+
+#### Tradeoff
+
+Keeping two backends has a real cost: packet-processing changes that touch
+the capture path have to be mirrored in both files. We mitigate this by
+keeping all STAMP-level logic (TLV parsing, HMAC, Return Path handling,
+session tracking, counter updates) in `receiver/mod.rs` — the two backends
+differ only in how they capture packets and whether they send over an async
+tokio socket or a blocking std socket.
+
+The other consequence is that a handful of features that genuinely require
+raw IP-header visibility — currently just the Reflected Fixed Header Data
+(Type 247) and Reflected IPv6 Extension Header Data (Type 246) TLVs from
+draft-ietf-ippm-stamp-ext-hdr — are only populated on the pnet backend.
+On the nix backend the reflector echoes the TLV with the U-flag set per
+RFC 8972 §4.2, and logs a one-time warning suggesting a rebuild with
+`--features ttl-pnet` if header reflection is actually needed. This
+follows the draft's own "may be unsupported by the reflector" semantics,
+so the sender sees a spec-compliant response either way.
+
+If you specifically need TLV 246/247 reflection, or you want to craft
+outgoing packets with non-default IPv6 extension headers, build with
+`--no-default-features --features ttl-pnet` and accept the tradeoffs
+above.
+
 ## Usage
 
 ### Session-Reflector (Server)
@@ -418,8 +503,10 @@ The implementation supports RFC 8972 TLV (Type-Length-Value) extensions, which a
 | 240 | BER Bit Pattern in Padding | Repeated bit pattern carried alongside Extra Padding (draft-gandhi-ippm-stamp-ber-05) | Experimental |
 | 241 | BER Bit Error Count | u32 error-bit count, computed by reflector | Experimental |
 | 242 | BER Max Bit Error Burst Size | u32 longest consecutive error run, computed by reflector | Experimental |
+| 246 | Reflected IPv6 Extension Header Data | Reflects received IPv6 Hop-by-Hop / Destination Options headers (draft-ietf-ippm-stamp-ext-hdr) | Experimental (pnet backend only) |
+| 247 | Reflected Fixed Header Data | Reflects the raw 20-byte IPv4 or 40-byte IPv6 fixed header (draft-ietf-ippm-stamp-ext-hdr) | Experimental (pnet backend only) |
 
-**Status**: Full = structured parsing, validation, and reflector field population. Experimental = implements an active IETF draft; wire format and type numbers for BER (240/241/242) are TBD in the draft (experimental-range picks) while Reflected Control (Type 12) is IANA-assigned. SR-MPLS/SRv6 forwarding is echoed with U-flag (actual segment routing is out of scope for userspace UDP).
+**Status**: Full = structured parsing, validation, and reflector field population. Experimental = implements an active IETF draft; wire format and type numbers for BER (240/241/242) and ext-hdr reflection (246/247) are TBD in the draft (experimental-range picks) while Reflected Control (Type 12) is IANA-assigned. SR-MPLS/SRv6 forwarding is echoed with U-flag (actual segment routing is out of scope for userspace UDP). Types 246/247 require raw IP-header visibility which the default `nix` UDP-socket backend cannot provide; on that backend they are echoed with the U-flag set and a one-time warning is logged — see [Receiver Backends](#receiver-backends) for why the default remains `nix`.
 
 ### TLV Handling Modes
 
@@ -606,6 +693,49 @@ stamp-suite --remote-addr 192.168.1.100 --ber --ber-pattern aa55 --ber-padding-s
 
 The reflector XORs the received padding against the expected pattern (from the Bit Pattern TLV, or 0xFF00 if absent), counts error bits and the longest consecutive error run across byte boundaries, and writes the results into Types 241 and 242. Per draft §3, duplicate BER TLVs or a missing companion Extra Padding TLV cause the reflector to set the U-flag on all BER TLVs and skip the computation.
 
+### Reflected Fixed / IPv6 Extension Header Data TLVs (draft-ietf-ippm-stamp-ext-hdr)
+
+Two experimental TLVs let the sender ask the reflector to echo the bytes of the
+received IP headers — useful for diagnosing DSCP remarking, TTL decrement,
+Flow Label rewriting, or tampering with IPv6 Hop-by-Hop / Destination Options
+by intermediate routers.
+
+| Type | Name | Content |
+|------|------|---------|
+| 246 | Reflected IPv6 Extension Header Data | Concatenated Hop-by-Hop (NextHeader 0) and Destination Options (NextHeader 60) extension headers, each prefixed with its NextHeader byte and HdrExtLen byte as they appeared on the wire |
+| 247 | Reflected Fixed Header Data | Raw 20-byte IPv4 or 40-byte IPv6 fixed header as received |
+
+Type numbers are TBD in the draft; this implementation uses 246/247 from RFC
+8972's experimental range.
+
+```bash
+# Ask the reflector to reflect the IPv4/IPv6 fixed header
+stamp-suite --remote-addr 192.168.1.100 --reflected-fixed-hdr
+
+# IPv6 test with reflected extension headers
+stamp-suite --remote-addr 2001:db8::1 --reflected-ipv6-ext-hdr
+```
+
+**Backend requirement:** these TLVs require the reflector to copy raw IP-header
+bytes into the response, which is only possible when the reflector captures at
+the datalink layer. Only the `pnet` backend can do this (see
+[Receiver Backends](#receiver-backends)).
+
+- On the **pnet** backend (Windows default, or `--features ttl-pnet` on Unix):
+  the reflector populates the TLV Value with the captured bytes. For IPv4
+  packets the TLV is truncated to the fixed 20-byte header, so IPv4 options
+  are not reflected.
+- On the **nix** backend (Linux/macOS default): the kernel hides raw IP
+  headers from the application, so the reflector has nothing to copy. The
+  TLVs are echoed with an empty Value and the U-flag set per RFC 8972 §4.2,
+  and a one-time warning is logged telling the operator to rebuild with
+  `--features ttl-pnet` if header reflection is required. The sender sees a
+  protocol-compliant response either way.
+- A sender-requested Type 246 TLV on an IPv4 packet, or on an IPv6 packet
+  without any extension headers, legitimately produces an empty Value — this
+  is **not** the same as the U-flag case and is treated as a valid "no data"
+  response.
+
 ## Prometheus Metrics
 
 When built with `--features metrics`, the reflector can expose Prometheus metrics:

src/configuration.rs

@@ -326,6 +326,22 @@ pub struct Configuration {
     /// Ignored unless `--reflected-control-count` > 1.
     #[clap(long, default_value_t = 1_000_000)]
     pub reflected_control_interval_ns: u32,
+
+    /// Request that the reflector copy the received IP fixed header
+    /// (IPv4: 20 bytes, IPv6: 40 bytes) back via TLV Type 247
+    /// (draft-ietf-ippm-stamp-ext-hdr §4). Reflectors built with the
+    /// `ttl-nix` backend cannot observe the IP header and will echo the
+    /// TLV with the U-flag set.
+    #[clap(long)]
+    pub reflected_fixed_hdr: bool,
+
+    /// Request that the reflector copy IPv6 Hop-by-Hop and Destination
+    /// Options extension headers back via TLV Type 246
+    /// (draft-ietf-ippm-stamp-ext-hdr §3). Reflectors built with the
+    /// `ttl-nix` backend cannot observe extension headers and will echo
+    /// the TLV with the U-flag set.
+    #[clap(long)]
+    pub reflected_ipv6_ext_hdr: bool,
 }
 
 impl Configuration {
@@ -602,6 +618,8 @@ impl Configuration {
         merge!(reflected_control_count);
         merge!(reflected_control_length);
         merge!(reflected_control_interval_ns);
+        merge!(reflected_fixed_hdr);
+        merge!(reflected_ipv6_ext_hdr);
     }
 }
 
@@ -678,6 +696,8 @@ pub struct FileConfiguration {
     pub reflected_control_count: Option<u16>,
     pub reflected_control_length: Option<u16>,
     pub reflected_control_interval_ns: Option<u32>,
+    pub reflected_fixed_hdr: Option<bool>,
+    pub reflected_ipv6_ext_hdr: Option<bool>,
 }
 
 /// Checks if authenticated mode is enabled.

src/receiver/mod.rs

@@ -68,6 +68,61 @@ use crate::{
     },
 };
 
+/// Returns the list of local IP addresses used for Destination Node Address
+/// TLV matching (RFC 9503 §4).
+///
+/// When `bind_addr` is a wildcard (`0.0.0.0` or `::`), enumerates every
+/// interface address on the system. Otherwise returns just `bind_addr`.
+///
+/// Interface enumeration uses the `nix` crate on Unix and `pnet::datalink` on
+/// Windows — both produce the same logical output.
+pub fn build_local_addresses(bind_addr: std::net::IpAddr) -> Vec<std::net::IpAddr> {
+    let is_wildcard = match bind_addr {
+        std::net::IpAddr::V4(v4) => v4.is_unspecified(),
+        std::net::IpAddr::V6(v6) => v6.is_unspecified(),
+    };
+    if !is_wildcard {
+        return vec![bind_addr];
+    }
+
+    let addrs = enumerate_interface_addresses();
+    if addrs.is_empty() {
+        log::warn!(
+            "Could not enumerate local addresses; Destination Node Address matching may fail"
+        );
+        vec![bind_addr]
+    } else {
+        addrs
+    }
+}
+
+#[cfg(unix)]
+fn enumerate_interface_addresses() -> Vec<std::net::IpAddr> {
+    let mut addrs = Vec::new();
+    if let Ok(ifaddrs) = ::nix::ifaddrs::getifaddrs() {
+        for ifaddr in ifaddrs {
+            if let Some(addr) = ifaddr.address {
+                if let Some(v4) = addr.as_sockaddr_in() {
+                    addrs.push(std::net::IpAddr::V4(v4.ip()));
+                } else if let Some(v6) = addr.as_sockaddr_in6() {
+                    addrs.push(std::net::IpAddr::V6(v6.ip()));
+                }
+            }
+        }
+    }
+    addrs
+}
+
+#[cfg(not(unix))]
+fn enumerate_interface_addresses() -> Vec<std::net::IpAddr> {
+    // Windows has no `getifaddrs`; fall back to pnet's datalink enumeration.
+    // pnet is always a build dependency on Windows (default ttl-pnet backend).
+    pnet::datalink::interfaces()
+        .into_iter()
+        .flat_map(|iface| iface.ips.into_iter().map(|n| n.ip()))
+        .collect()
+}
+
 /// Loads the HMAC key from configuration (hex string or file).
 pub fn load_hmac_key(conf: &Configuration) -> Option<HmacKey> {
     if let Some(ref hex_key) = conf.hmac_key {
@@ -494,6 +549,28 @@ pub struct ProcessingContext<'a> {
     pub sender_port: u16,
     /// Reflector member link ID for Micro-session ID TLV (RFC 9534 §3.2).
     pub reflector_member_link_id: Option<u16>,
+    /// Raw bytes of the received IP fixed header and IPv6 extension headers,
+    /// for draft-ietf-ippm-stamp-ext-hdr Reflected Fixed/Ext Header TLVs
+    /// (Types 247/246). `None` on backends that cannot observe the IP layer
+    /// (UDP-socket `nix` backend): the reflector then echoes the TLV with the
+    /// U-flag set.
+    pub captured_headers: Option<&'a CapturedHeaders>,
+}
+
+/// Raw IP-layer bytes captured at receive time for reflecting back to the
+/// sender via TLV Types 246 and 247 (draft-ietf-ippm-stamp-ext-hdr).
+///
+/// Populated only by backends that capture at the datalink layer (pnet).
+/// UDP-socket backends (nix) cannot observe these bytes and leave the
+/// struct unset; the reflector sets the U-flag on any 246/247 request.
+#[derive(Debug, Clone, Default)]
+pub struct CapturedHeaders {
+    /// Raw IP fixed header (20 bytes for IPv4, 40 bytes for IPv6).
+    pub fixed_header: Vec<u8>,
+    /// Concatenated IPv6 Hop-by-Hop (NextHeader 0) and Destination Options
+    /// (NextHeader 60) extension headers, each prefixed with its NextHeader
+    /// byte and HdrLen byte, exactly as received on the wire.
+    pub ipv6_ext_headers: Vec<u8>,
 }
 
 /// Processes a STAMP packet and returns the response.
@@ -960,6 +1037,22 @@ fn apply_semantic_tlv_processing(
     // compute Bit Error Count and Max Burst against the companion Extra Padding.
     tlvs.process_ber();
 
+    // Process Reflected Fixed / IPv6 Extension Header TLVs
+    // (draft-ietf-ippm-stamp-ext-hdr §§3–4). If the backend captured raw IP
+    // bytes, copy them into the TLV Value; otherwise set the U-flag per
+    // RFC 8972 §4.2 and echo an empty TLV. A nix UDP-socket backend hands us
+    // `captured_headers = None`, so this correctly advertises "unsupported"
+    // to senders that requested header reflection.
+    let (captured_fixed, captured_ext): (Option<&[u8]>, Option<&[u8]>) = match ctx.captured_headers
+    {
+        Some(h) => (
+            Some(h.fixed_header.as_slice()),
+            Some(h.ipv6_ext_headers.as_slice()),
+        ),
+        None => (None, None),
+    };
+    tlvs.process_reflected_headers(captured_fixed, captured_ext);
+
     // Process Reflected Test Packet Control TLV (draft-ietf-ippm-asymmetrical-pkts §3).
     // We don't honour the requested per-packet length in this implementation — if the
     // sender asks for a specific length we set the C flag on the echoed TLV to indicate
@@ -1284,6 +1377,7 @@ mod tests {
             local_addresses: &[],
             sender_port: 0,
             reflector_member_link_id: None,
+            captured_headers: None,
         }
     }