Skip to content

Navigation Menu

Sign in
Sign up

Commit 0c2021e

Browse files
thatSFguyclaude
andcommitted
Correct §2.1 flag byte: bit 7 is IFAC, not part of header_type
Reverts the wrong normative claim added in 8c4d550. The official manual §4.6.3 documents byte 1 as ifac_flag(7) | header_type(6) | context_flag(5) | propagation_type(4) | dest_type(3-2) | packet_type(1-0). Upstream confirms: - RNS/Packet.py:246 — `(self.flags & 0b01000000) >> 6` parses header_type as a 1-bit field at position 6. - RNS/Transport.py:1003 — `bytes([raw[0] | 0x80, raw[1]])` sets the IFAC flag at bit 7 in Transport.transmit when ifac_identity is attached. The reporter on issue #4 was correct: bit 7 has always been the IFAC indicator. The 8c4d550 paragraph telling implementations "MUST NOT treat bit 7 as a separate flag" is removed and replaced with the correct layout, the upstream parse masks, and the IFAC sealing snippet showing where the bit gets set on the wire. A spec-correction callout in §2.1 documents the prior-version mistake so anyone who consumed the bad guidance can identify the breakage. verify_packet_header.py gains verify_ifac_bit_position() which locks in the bit-7-is-IFAC invariant against future regression: it asserts header_type's parse mask covers bit 6 only, never bit 7, and that the IFAC mask 0x80 is disjoint from the header_type mask. The existing flag-layout cases were always correct (header_type << 6 puts it at bit 6); only the docstring described the wrong layout. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 8c4d550 commit 0c2021e

2 files changed

Lines changed: 73 additions & 11 deletions

File tree

‎SPEC.md‎

Lines changed: 27 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -316,14 +316,36 @@ A clean-room client that targets LXMF interop only can ignore GROUP destinations
316316
Every Reticulum packet starts with a 1-byte flag field:
317317

318318
```
319-
bit 7-6 : header_type (0 = HEADER_1, 1 = HEADER_2)
319+
bit 7 : ifac_flag (0 = open / no IFAC, 1 = IFAC field present)
320+
bit 6 : header_type (0 = HEADER_1, 1 = HEADER_2)
320321
bit 5 : context_flag (1 = announce includes a ratchet pubkey)
321-
bit 4 : transport_type (0 = BROADCAST, 1 = TRANSPORT)
322-
bit 3-2 : destination_type (0=SINGLE, 1=GROUP, 2=PLAIN, 3=LINK)
323-
bit 1-0 : packet_type (0=DATA, 1=ANNOUNCE, 2=LINKREQUEST, 3=PROOF)
322+
bit 4 : transport_type (0 = BROADCAST, 1 = TRANSPORT) — the official manual calls this "propagation_type"
323+
bit 3-2 : destination_type (0 = SINGLE, 1 = GROUP, 2 = PLAIN, 3 = LINK)
324+
bit 1-0 : packet_type (0 = DATA, 1 = ANNOUNCE, 2 = LINKREQUEST, 3 = PROOF)
324325
```
325326

326-
`header_type` is a **2-bit field**. Only values `0` (HEADER_1) and `1` (HEADER_2) are defined; values `2` and `3` are RESERVED and never emitted on the wire by upstream. Bit 7 therefore reads `0` on every packet RNS 1.x produces. Implementations MUST NOT treat bit 7 as a separate flag (e.g. an IFAC indicator) — both bits are extracted as one field by upstream's parser (`(self.flags & 0b01000000) >> 6` at `RNS/Packet.py:246`), and a non-zero high bit will be interpreted as `header_type ∈ {2, 3}` and rejected. The IFAC (Interface Authentication Code) is a **separate trailing field** appended after the packet body, never sharing space with the flag byte (`IFAC_MIN_SIZE = 1` byte at `RNS/Reticulum.py:151-154`).
327+
Each subfield is **1 bit** (or 2 for `destination_type` / `packet_type`). Upstream's parser extracts them with these masks (`RNS/Packet.py:246-250` in RNS 1.2.0):
328+
329+
```python
330+
self.header_type = (self.flags & 0b01000000) >> 6 # bit 6 only
331+
self.context_flag = (self.flags & 0b00100000) >> 5
332+
self.transport_type = (self.flags & 0b00010000) >> 4
333+
self.destination_type = (self.flags & 0b00001100) >> 2
334+
self.packet_type = (self.flags & 0b00000011)
335+
```
336+
337+
Bit 7 (`ifac_flag`) is set by `Transport.transmit` immediately before transmission when the egress interface has an IFAC identity attached (`RNS/Transport.py:993-1024`). The setter is unambiguous:
338+
339+
```python
340+
# Set IFAC flag
341+
new_header = bytes([raw[0] | 0x80, raw[1]]) # 0x80 = bit 7
342+
# Assemble new payload with IFAC
343+
new_raw = new_header + ifac + raw[2:] # IFAC field is inserted between header and addresses
344+
```
345+
346+
When `ifac_flag = 1`, an `ifac_size`-byte IFAC field appears immediately after byte 2 of the header — i.e. between the `hops` byte and the start of `ADDRESSES`. `ifac_size` is interface-configured and ranges from `IFAC_MIN_SIZE = 1` byte (`RNS/Reticulum.py:151-154`) up to 64 bytes (full Ed25519 signature). The receiving side strips the IFAC after verification and rebuilds the un-IFACed packet for upstream processing (`RNS/Transport.py:1342-1369`).
347+
348+
> ⚠️ **Spec correction.** Earlier revisions of this section (through commit [`8c4d550`](https://github.com/thatSFguy/reticulum-specifications/commit/8c4d550)) treated `header_type` as a 2-bit field occupying bits 7-6, with bit 7 reserved. That was wrong: bit 7 has always been the IFAC flag (`Transport.transmit` line 1003), and `header_type` is 1 bit at position 6. The official manual §4.6.3 documents the correct layout. Implementations that followed the prior wording will mis-parse IFAC-protected packets as `header_type = 2 or 3` and reject them. Surfaced by the reporter on [issue #4](https://github.com/thatSFguy/reticulum-specifications/issues/4) item #1.
327349
328350
### 2.2 Two header forms
329351

‎tools/verify_packet_header.py‎

Lines changed: 46 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,12 @@
22
Verifier for SPEC.md §2.1, §2.2, §2.3.
33
44
Verifies:
5-
- §2.1: flag-byte layout (header_type, context_flag, transport_type,
6-
destination_type, packet_type) — by constructing packets with each
7-
combination and reading the resulting flag byte.
5+
- §2.1: flag-byte layout (ifac_flag at bit 7, header_type at bit 6,
6+
context_flag at bit 5, transport_type at bit 4, destination_type
7+
at bits 3-2, packet_type at bits 1-0) — by constructing packets
8+
with each combination and reading the resulting flag byte, and
9+
by asserting that upstream's parse mask `0b01000000 >> 6`
10+
treats bit 7 as separate from header_type.
811
- §2.2: HEADER_1 layout flags(1) hops(1) dest_hash(16) context(1) data
912
and HEADER_2 layout flags(1) hops(1) transport_id(16) dest_hash(16)
1013
context(1) data.
@@ -48,10 +51,11 @@ def init_minimal_rns():
4851

4952

5053
def verify_flag_byte_layout():
51-
# §2.1: bit 7-6 header_type, bit 5 context_flag, bit 4 transport_type,
52-
# bit 3-2 dest_type, bit 1-0 packet_type.
54+
# §2.1: bit 7 ifac_flag, bit 6 header_type, bit 5 context_flag,
55+
# bit 4 transport_type, bit 3-2 dest_type, bit 1-0 packet_type.
5356
# Build a packet by hand and check the flag byte by replicating
54-
# RNS.Packet.pack's header_type field semantics.
57+
# RNS.Packet.pack's header_type field semantics (header_type << 6,
58+
# i.e. 1-bit field at position 6 — NOT bits 7-6).
5559
cases = [
5660
# (header_type, context_flag, transport_type, dest_type, packet_type, expected_flag)
5761
(0, 0, 0, 0, 0, 0b00000000),
@@ -70,6 +74,41 @@ def verify_flag_byte_layout():
7074
print("PASS S2.1 flag-byte layout")
7175

7276

77+
def verify_ifac_bit_position():
78+
# §2.1: bit 7 (mask 0x80) is the IFAC flag, set by Transport.transmit
79+
# at line 1003: `new_header = bytes([raw[0] | 0x80, raw[1]])`. It is
80+
# NOT part of header_type.
81+
# Lock in two invariants:
82+
# 1. Setting bit 7 must NOT change the parsed header_type — upstream's
83+
# parser at RNS/Packet.py:246 isolates bit 6 only via mask 0b01000000.
84+
# 2. The constant 0x80 == bit 7, distinct from the header_type mask.
85+
parse_mask = 0b01000000
86+
if parse_mask != 1 << 6:
87+
fail(f"S2.1 parse_mask: header_type mask must be bit 6 (0x40), got 0x{parse_mask:02x}")
88+
if (parse_mask & 0x80) != 0:
89+
fail("S2.1 parse_mask: header_type mask must NOT cover bit 7")
90+
91+
for ifac_set in (0, 1):
92+
for ht_value in (0, 1):
93+
flag = (ifac_set << 7) | (ht_value << 6)
94+
parsed_ht = (flag & parse_mask) >> 6
95+
if parsed_ht != ht_value:
96+
fail(f"S2.1 ifac_bit: flag=0x{flag:02x} (ifac={ifac_set} ht={ht_value}) "
97+
f"parsed header_type={parsed_ht}, expected {ht_value} — "
98+
f"bit 7 leaking into header_type would make this fail")
99+
100+
# Also confirm the upstream IFAC setter constant matches our spec.
101+
# RNS/Transport.py:1003: `bytes([raw[0] | 0x80, raw[1]])` — we lock in
102+
# the value 0x80 (bit 7) as the IFAC flag mask.
103+
IFAC_FLAG_MASK = 0x80
104+
if IFAC_FLAG_MASK != 1 << 7:
105+
fail(f"S2.1 IFAC mask: expected 0x80 (bit 7), got 0x{IFAC_FLAG_MASK:02x}")
106+
if IFAC_FLAG_MASK & parse_mask:
107+
fail("S2.1 IFAC mask overlaps header_type parse mask — would re-introduce the prior-spec bug")
108+
109+
print("PASS S2.1 IFAC bit position (bit 7, distinct from header_type)")
110+
111+
73112
def verify_header_two_form():
74113
# §2.2: HEADER_2 wire form is flags(1) hops(1) transport_id(16) dest_hash(16) context(1) data.
75114
# The simplest verification is to round-trip via RNS.Packet's unpack: build
@@ -182,6 +221,7 @@ def main():
182221
rns_instance = init_minimal_rns()
183222
try:
184223
verify_flag_byte_layout()
224+
verify_ifac_bit_position()
185225
verify_header_two_form()
186226
verify_header_conversion(rns_instance)
187227
finally:

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /