jlpoole/reticiulum-specification
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
reticiulum-specification/test-vectors/README.md
Rob cfd0d8249b Re-anchor against RNS 1.2.4 / LXMF 0.9.7 + track upstream distribution shift 
Upstream RNS 1.2.4 (2026-05-07) announces it is "probably the last
release that is also published to GitHub" — pip continues until rnpkg
is complete and RNS is self-hosting. All 13 verifiers pass against
1.2.4 / 0.9.7; no wire-format, signing, or protocol behavior changed
between 1.2.0 and 1.2.4, so the changes here are purely currency:

- Pin tools/requirements.txt to rns==1.2.4 / lxmf==0.9.7 so the
  verifier stays reproducible if upstream stops mirroring to PyPI
  before the migration is ready.
- Add an "Upstream distribution shift" watch-list to todo.md (local
  Reticulum node, repo destination hash, rnpkg install/upgrade
  commands, rsg signature verification, mirroring source citations).
- Bump SPEC.md frontmatter and re-anchor ~50 line citations across
  Identity.py, Transport.py, Resource.py, Link.py, Reticulum.py,
  Packet.py, and LXMF/* (Identity.py drift was the heaviest at +13
  to +31 lines; Transport.py was variable). Fix one numeric
  (MAX_RANDOM_BLOBS = 32 → 64) and one semantic (§6.6.3 LRPROOF MTU
  clamp citation pointed at the wrong location — corrected to point
  at the transit-relay clamp at Transport.py:1539-1556).
- Update §10.4 decompression-bomb hazard to note upstream's 1.1.9 cap
  adoption, with citations to Resource.py:686-691 and Buffer.py:95-97
  plus a "do not use one-shot bz2.decompress()" warning.
- Re-anchor 11 flows/ files (version pins + ~30 line citations).
- Bump version labels in tools/README.md, test-vectors/README.md, and
  4 verifier docstrings + 2 hardcoded print strings.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-08 07:42:25 -04:00

3.3 KiB
Raw Blame History

Test vectors

Known-good byte sequences that any Reticulum-compatible implementation should be able to round-trip in both directions.

Status

Populated against RNS 1.2.4 / LXMF 0.9.7:

  • ✅ identities.json — Alice + Bob identity vectors (regenerator: ../tools/regen_identities.py, verifier: ../tools/verify_destination_hash.py).
  • ✅ announces.json — two announce vectors (no-ratchet + with-ratchet) signed by Alice (regenerator: ../tools/regen_announces.py, verifier: ../tools/verify_announce_roundtrip.py).
  • ✅ lxmf.json — two opportunistic-LXMF vectors Alice → Bob (regenerator: ../tools/regen_lxmf.py, verifier: ../tools/verify_lxmf_opportunistic.py).
  • ✅ links.json — full Link handshake vector (LINKREQUEST + LRPROOF + derived session key) Alice → Bob (regenerator: ../tools/regen_links.py, verifier: ../tools/verify_link_handshake.py).

All four files are byte-deterministic across runs: regenerators pin every random source (ephemeral keys, IVs, random_hash prefix + timestamp, LXMF timestamp) so the output is reproducible against a fixed upstream RNS / LXMF version.

See ../agent.md §5 and ../todo.md for the remaining bootstrap task list.

Format (proposed)

Each vector lives in a per-domain JSON file, e.g.:

  • identities.json — Alice + Bob with encPriv, sigPriv, ratchetPriv (hex), plus the derived publicKey, identityHash, destinationHash for lxmf.delivery
  • announces.json — full hex of a signed announce packet, plus the inputs that produced it (display_name, ratchetPub, etc.)
  • lxmf.json — sender + recipient identity, plaintext, expected ciphertext bytes
  • links.json — LINKREQUEST + LRPROOF + derived session keys

Each entry should include:

{
  "description": "Alice's lxmf.delivery announce with ratchet, display_name='AliceTest'",
  "inputs": { ... },
  "expected_bytes_hex": "...",
  "rns_version_at_generation": "1.2.0",
  "generator_script": "tools/regen_announces.py"
}

The generator_script is the file in ../tools/ that, when run against upstream RNS, regenerates expected_bytes_hex. Keeping the generator alongside the vector lets a future contributor verify the vector still matches a newer upstream RNS.

What needs to round-trip

For the spec to claim "an implementation that passes all test vectors interoperates with upstream", the vectors must cover:

  1. Identity construction — given the same private-key inputs, derive the same public key, identity hash, destination hash.
  2. Announce build + parse — build a signed announce; verify the same bytes come back through upstream's parser; verify upstream-built announces parse correctly.
  3. Token encrypt + decrypt — bidirectional, with both ratchet and long-term keys.
  4. Opportunistic LXMF — full plaintext → ciphertext → plaintext round-trip, signature valid both ways.
  5. Link handshake — LINKREQUEST built by client A, LRPROOF computed by upstream as B, both arrive at the same link_id and session keys.
  6. Link-delivered LXMF — body packed by client, decrypted + parsed by upstream.

A separate vector set for FAILURE cases is also useful: malformed announces, expired ratchets, mismatched signatures. An implementation should reject those as a regression-prevention measure.