BackOne/SPEC.md

SPEC — BackOne

§G (goal)

Make BackOne quantum ready: phases 1-6 of backone-quantum-fork-research.md — liboqs + hybrid X25519+ML-KEM-768 / Ed25519+ML-DSA-65 handshake, identity/COM v2 double-sign, capability-bit negotiation. Phase 7 (AES-256-GCM) OUT.

§C (constraints)

• C++17. GNU make = real build. Top CMakeLists.txt = stub, never product build.
• Deps vendored in ext/. No new dep for few-liners.
• Tabs always, .clang-format LLVM/Stroustrup, indent 4. No reformat of untouched lines.
• New .cpp/.hpp/.h gets 11-line BSL header verbatim (node/Mutex.hpp:1-12).
• node/ stays OS-independent. Sockets/files → osdep/. Orchestration → service/. Persistence → controller/.
• No exceptions across C API. Fatal ZT_ResultCode = 100–999.
• One reactor thread (Phy::poll). Cross-thread wake only Phy::whack().
• New compiled file → register in objects.mk or no link.
• Platforms: Linux (primary), macOS, BSD/NetBSD, Windows (msbuild).
• Header edits: no -MMD dep tracking → make clean after touching .h.
• PQC lock: liboqs static vendored ext/; hybrid key = KDF(classical ‖ pq); presets hybrid (ML-KEM-768/ML-DSA-65) + pqconly (intended ML-KEM-1024/ML-DSA-87 — not yet distinct, see T25)
• wire/identity/COM use versioned v2 + capability-bit fallback to classic
• include/ZeroTierOne.h changes additive-only (Java/libzt ripple)
• OUT: AES-256-GCM swap, trusted-path skipCrypto, forward secrecy, protocol standardization, crypto audit, production release/signing
• ? address v2 derivation keeping 40-bit + PoW
• ? VL1 fragmentation capacity for +4KB identity (check node/Packet.*)
• ? liboqs version/tag + build flags for ext/
• ? measured ML-KEM/ML-DSA latency (doc estimates unverified)
• ? capability-bit placement in existing handshake

§I (public surfaces)

id	surface	detail
I.capi	C API	include/ZeroTierOne.h, ZT_Node_* (lines 1796-2258), ZT_SDK_API. Ripples to Java/libzt/SDK
I.api	HTTP JSON API	127.0.0.1:9993, /status /peer /network /member /controller /metrics /info, auth X-ZT1-Auth header or ?auth= from authtoken.secret
I.cli	CLI	backone-cli info|listpeers|listnetworks|join|leave (-j -p -D), backone-idtool generate|validate|getpublic|sign|verify|mkcom — symlink dispatch on argv[0]
I.cfg	config	home /var/lib/backone (macOS /Library/Application Support/BackOne), local.conf, identity.secret, networks.d/, controller.db, backone.port, backone.pid
I.build	build	make, make one, make selftest, make core, make debug, make install, make debian/redhat, make central-controller; env ZT_* knobs
I.ffi	Rust FFI	rustybits/zeroidc (zeroidc_new…), smeeclient — C header zeroidc.h, link on ZT_SSO_SUPPORTED=1/ZT_CONTROLLER=1
I.jni	Java SDK	java/jni/…Node.cpp, ant targets build_java/build_android/build_jar
I.pqc.cfg	config	local.conf settings.pqcMode (off/hybrid/pqconly); absent = off/classic (opt-in), unknown value = warn + classic. Per-algorithm kem/sig selection is not wired (research doc only, see T25)
I.pqc.wire	wire	static-static hybrid, no ephemeral exchange: identity v2 (type byte 1) carries ML-KEM-768 pub + ML-DSA-65 pub; agree = KDF(X25519-identity-agree ‖ ML-KEM-encaps(peer static pub)) (node/Identity.hpp:364-379 encaps / :392+ decaps, driven from node/Peer.cpp ensurePendingHybridCt/setHybridSessionKey); capability via HELLO protocol-version bytes (node/Packet.hpp:329-333); identity.secret/identity.public v2 on disk
I.pqc.com	credentials	COM double-sign/verify — controller + node/CertificateOfMembership.*
I.rules	rules compiler	node rule-compiler/cli.js <rules> → rules/tags JSON

§V (invariants)

Derived from selftest.cpp + CI gates. ? = code-derived, no test yet.

id	invariant	evidence
V1	Crypto KATs pass: Salsa20 vectors, C25519 agreement, Ed25519 sign/verify, SHA512, Poly1305	selftest.cpp:137 testCrypto
V2	Identity known-good accepted, known-bad rejected	selftest.cpp:475 testIdentity
V3	CertificateOfMembership signs and agreesWith roundtrip	selftest.cpp:577 testCertificate
V4	Packet encode/decode roundtrip exact	selftest.cpp:641 testPacket
V5	Phy UDP+TCP loopback on 127.0.0.1 works, no root	selftest.cpp:1002 testPhy
V6	Zero definite leaks under valgrind; test exit code 0	.github/workflows/validate-report.sh
V7	? No exception crosses C API; ZT_ResultCode_isFatal only 100–999	include/ZeroTierOne.h:426
V8	? node/ contains no OS calls (sockets/files/interfaces)	node/README.md rule
V9	hybrid↔vanilla negotiates classic, link stays up	interop matrix
V10	identity v2 survives 1280B MTU tunnel intact; v2 = type byte 1 (wire Identity.hpp:219, string slot Identity.cpp:173); address derivation hashes X25519 material only → v1/v2 addresses bit-identical; v1 parser rejects type ≠ 0 cleanly	interop matrix
V11	ML-KEM/ML-DSA KATs + hybrid KDF vector + identity v2 roundtrip + COM double-sign verify pass	extended selftest.cpp
V12	pqcMode negotiation honors local.conf (off -> no v2 fields)	live daemon: bogus settings.pqcMode -> WARNING (service/OneService.cpp:1478), hybrid -> clean (2026-10-03); selftest has no pqcMode coverage
V13	hybrid agree = KDF(X25519-identity-agree ‖ ML-KEM static-static), no ephemeral exchange; hybrid↔hybrid agree + hybrid↔vanilla classic fallback pass	node/Peer.cpp:105-117 (encaps) node/IncomingPacket.cpp:534-542,697-703 (decaps)
V14	COM double-sign = type byte 1→2 appends ML-DSA sig alongside Ed25519; v1 verify path unchanged; v1 rejects type 2 cleanly	node/CertificateOfMembership.hpp:222-296, node/CertificateOfMembership.cpp:97-162, selftest.cpp:717
V15	handshake vs fragment loss measured: PQC identity in clear HELLO = 3273B → 3 frags (classic 137B → 1 frag, max 7 Packet.hpp:235); Monte Carlo 20k trials obs≈analytic at p∈{.01,.05,.10,.30}; fragment loss delays HELLO (retransmit), does not break handshake	selftest.cpp:1713 benchmark
V16	hybrid handshake puts a 1088 B ML-KEM-768 ct on the wire and both sides derive the same hybrid _key; classic/off peers carry none and fall back	write node/Peer.cpp:493-502, parse node/IncomingPacket.cpp:534-542, OK echo node/IncomingPacket.cpp:608-619,697-703; E2E lab M1-M5 all pass tools/pqc-lab.sh (2026-10-02; M3 68 / M4 90 large PQ datagrams on wire)

§T (tasks)

id	status	task	cites
T1	x	Fix CI build smoke: build.yml runs ./zerotier-selftest, build emits backone-selftest (also tar zerotier-one → backone)	I.build,V6
T2	x	Fix validate-linux.sh binary names: invokes ./zerotier-one, ./zerotier-cli (lines 41-43,105,111,451), builds backone*	I.cli,V6
T3	x	Wire ZT_COVERAGE into makefiles — consumed by none, gcovr likely reports zeros ?	I.build
T4	x	make install manpage rule: expects doc/backone.8, doc/backone-cli.1, doc/backone-idtool.1; doc/ only has zerotier-*, no rename rule	I.build
T5	x	make redhat: backone.spec %install copies missing debian/backone.service + ext/installfiles/linux/backone.init.rhel6 (actual files zerotier-*)	I.build
T6	x	Rebrand make-bsd.mk/make-netbsd.mk: still emit/install zerotier-one, /var/db/zerotier-one vs code writing backone.pid	I.build
T7	x	Dockerfile.ci: copies zerotier-one from build → fails; binary is backone	I.build
T8	.	pkg/snap/snapcraft.yaml: builds upstream github.com/zerotier/zerotierone.git, expects usr/sbin/zerotier-one	I.build
T9	.	Wire orphaned java/test/StringUtilsTest.java (JUnit4) into java/build.xml target or delete	I.jni
T10	.	Replace rule-compiler/package.json npm test failing placeholder with real test of rule-compiler.js	I.rules
T11	.	? Add #[test] coverage for rustybits/zeroidc FFI parse/exchange paths	I.ffi,V7
T12	x	Implement Redis config TODO (service/OneService.cpp:1467 // TODO: Redis config)	I.cfg
T13	.	Implement LFDB::eraseNetwork/eraseMember TODOs (controller/LFDB.cpp:383,388)	I.cfg
T14	.	Lint gate done: make lint (tools/lint.sh, changed-lines clang-format) + .github/workflows/lint.yml	I.build
T15	.	Fix -Wsign-compare suppression FIXME (node/Bond.cpp:23, node/Node.cpp:40)	I.build
T16	x	Federation identity-collision payload FIXME (node/IncomingPacket.cpp:211) ? scope	I.capi,V7
T17	x	Phase 1: vendor liboqs static into ext/, wire make-linux.mk + objects.mk, pin version/tag + flags	I.build
T18	x	Phase 2: node/PQHybrid.* hybrid agree = KDF(X25519-identity-agree ‖ ML-KEM-768 encaps over peer static pub); phase-2 ephemeral-field mockup dropped	I.pqc.wire,V13
T19	x	Phase 3: identity v2 type byte 1, append ML-KEM+ML-DSA pubs, address hash X25519-only, v1 clean reject type ≠ 0	I.pqc.wire,V10
T20	x	Phase 4: COM type byte 2 double-sign (Ed25519+ML-DSA-65), v1 rejects cleanly	I.pqc.com,V14
T21	.	Phase 5: local.conf settings.pqcMode parse (off/hybrid/pqconly) + capability negotiation via HELLO protocol-version bytes, fallback classic. Mode now selects whether PQ material is used; which preset is still hardcoded (T24)	I.pqc.cfg,V12,V9
T22	x	Phase 6: selftest extension — ML-KEM/ML-DSA KATs, hybrid KDF vector, identity v2 roundtrip + address stability, COM double-sign, interop hybrid↔vanilla matrix	I.build,V11,V10,V14
T23	x	Phase 6: handshake-vs-fragment-loss benchmark for PQC HELLO; cap/segment if loss breaks handshake	V15
T24	x	Plumb settings.pqcMode through the identity path: Node(…,int pqcMode) stores _pqcMode; Identity::generate(bool pq,int pqcMode) derives pq from the daemon mode; OneService reads local.conf before new Node — a fresh hybrid/pqconly node writes a type-1 identity, a classic one type-0. Fixes the G1 defect.	I.pqc.cfg,V12
T25	.	Distinct PQ parameter sets: node/PQHybrid.* hardcodes ML-KEM-768/ML-DSA-65 (PQHybrid.cpp static_asserts OQS_KEM_ml_kem_768/OQS_SIG_ml_dsa_65), so hybrid and pqconly currently select identical material, while SPEC §C claims ML-KEM-1024/ML-DSA-87 for pqconly. Parameterize the preset (key sizes, ct len, _pendingHybridCt buffer, HELLO guard) or drop the pqconly claim. Note a pqconly HELLO with a PQ identity is 3273B → 3 frags, well under the 10024B cap, so no clean-fail path is reachable today	I.pqc.wire,I.pqc.cfg,V15

T1/T2 = prerequisites — CI must invoke backone-selftest before PQC gates mean anything. T1–T16 backlog (rebrand/CI/lint leftovers); T17–T25 = PQC phases 1–6 + the pqconly preset gap.

Not tracked (low value ?): one.cpp:256 port/token cleanup, MacKextEthernetTap.cpp:480 iface status, VLAN TODOs in NetBSDEthernetTap.cpp:468/MacKextEthernetTap.cpp:685, Phy.hpp:325 unix sock type comment.

§B (bug log)

id	date	cause	fix
B1	2026-10-02	Phase 5 (T21) advertised PQC capability in HELLO but never consumed it: Peer::_key was derived classically in the constructor and the hybrid ciphertext had no place in the HELLO/OK(HELLO) layout, so hybridEligible() was dead.	Wire hybrid static-static KEM ct into HELLO (lowest-address side writes [moon count][moons][flag(1B)][ct 1088B], crypted with the classical key) and echo it in OK(HELLO); parser order matches Peer::sendHELLO/_doHELLO; Peer::ensurePendingHybridCt() lazily encapsulates on first capability sighting so the handshake completes in one round trip; direction guard sender == lowest address on both parses. Refuse to start when the on-disk identity cannot satisfy settings.pqcMode (classic↔PQ migration changes the address).
B2	2026-10-02	settings.pqcMode absent (or unrecognized) resolved to HYBRID, and Node's pqcMode default was HYBRID with no way to tell "unconfigured" from "configured hybrid". Every existing type-0 install would hit the B1 refusal guard at startup; the C API ZT_Node_new path would silently generate type-1 identities.	Absent/unknown settings.pqcMode now resolves to ZT_PQC_MODE_CLASSIC (PQC is opt-in, matching the research doc); Node(…,int pqcMode = ZT_PQC_MODE_CLASSIC). Verified: classic identity + no config boots on 2.0.0 and stays 141 B; fresh node w/o config makes type-0; fresh node with "hybrid" makes type-1 (6415 B); classic + explicit "off" boots; classic + explicit "hybrid" still refuses; unknown value warns and runs classic.