ElixirForge/firmware
1
0
Fork 0
mirror of https://github.com/alexhopeoconnor/firmware.git synced 2026-10-18 01:11:42 +10:00
Code Releases Activity

TMM & Warmstore key source naming (#11119)

Browse Source 
* one becomes two

* warmstore clarify

* Address PR review: key-provenance terminology consistency

- Log line now says "not key-proven" (gate is XEdDSA OR manual, not just signer)
- Rename markKeySignerProvenForTest -> markKeyXeddsaSignedForTest (sets only the XEdDSA bit)
- Docs + test comments: "signer bit" -> "XEdDSA-signed bit"

clod helped too

* Rename signer-proven -> key-proven for broadened provenance predicate

Address PR #11119 review: the copyPublicKey()/copyUser() out-parameter and
the cache-path replay gate now report entry->keyProven() (XEdDSA-signed OR
manually verified), so the "signerProven" name and "signer-proven" comments
were misleading. Rename the public out-param to keyProven, the local
cachedKeySignerProven to cachedKeyProven, and update coupled callers, log
strings, docs headings, and comments to say "key-proven".

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* nitpicks

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom
2026-07-31 10:39:39 +00:00
committed by GitHub
co-authored by Claude Opus 4.8
parent 6367132919
commit e26b6bfc5a
11 changed files with 314 additions and 189 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/mesh/NodeDB.cpp
+9 -9
View File
@@ -3974,7 +3974,7 @@ bool NodeDB::copyPublicKey(NodeNum n, meshtastic_NodeInfoLite_public_key_t &out)
#if HAS_TRAFFIC_MANAGEMENT
// Last resort: a key the TrafficManagement NodeInfo cache learned from an observed frame
// for a node no longer in either NodeDB tier. This extends the pool of peers we can
// encrypt to. Keys here may be trust-on-first-use (see copyPublicKey's signerProven), the
// encrypt to. Keys here may be trust-on-first-use (see copyPublicKey's keyProven), the
// same first-contact trust NodeDB itself applies via updateUser().
if (trafficManagementModule && trafficManagementModule->copyPublicKey(n, out.bytes)) {
out.size = 32;
@@ -3989,10 +3989,10 @@ bool NodeDB::copyPublicKeyForDecrypt(NodeNum n, meshtastic_NodeInfoLite_public_k
if (copyPublicKeyAuthoritative(n, out))
return true;
#if HAS_TRAFFIC_MANAGEMENT
// A cold-tier cache key backs an authenticated decrypt only when signer-proven; unverified TOFU
// A cold-tier cache key backs an authenticated decrypt only when key-proven; unverified TOFU
// cache keys must not. Outbound encryption still uses the opportunistic copyPublicKey().
bool signerProven = false;
if (trafficManagementModule && trafficManagementModule->copyPublicKey(n, out.bytes, &signerProven) && signerProven) {
bool keyProven = false;
if (trafficManagementModule && trafficManagementModule->copyPublicKey(n, out.bytes, &keyProven) && keyProven) {
out.size = 32;
return true;
}
@@ -4012,7 +4012,7 @@ bool NodeDB::isVerifiedSignerForKey(NodeNum n, const uint8_t *key32)
#if WARM_NODE_COUNT > 0
uint8_t warmKey[32];
if (warmStore.copyKey(n, warmKey) && memcmp(warmKey, key32, 32) == 0)
return warmStore.isVerifiedSigner(n);
return warmStore.hasXeddsaSigned(n);
#endif
return false;
}
@@ -4024,7 +4024,7 @@ bool NodeDB::isKnownXeddsaSigner(NodeNum n)
if (info)
return nodeInfoLiteHasXeddsaSigned(info);
#if WARM_NODE_COUNT > 0
return warmStore.isVerifiedSigner(n);
return warmStore.hasXeddsaSigned(n);
#else
return false;
#endif
@@ -4146,9 +4146,9 @@ meshtastic_NodeInfoLite *NodeDB::getOrCreateMeshNode(NodeNum n)
// Restore the role the warm tier cached, so re-admission isn't stuck at CLIENT
// until the next NodeInfo arrives.
lite->role = static_cast<meshtastic_Config_DeviceConfig_Role>(warmRoleOf(warm));
// Restore the signer bit too: it is learned from verified traffic, not from
// Restore the XEdDSA-signed bit too: it is learned from verified traffic, not from
// NodeInfo, so a round trip through the warm tier must not relearn it from zero.
nodeInfoLiteSetBit(lite, NODEINFO_BITFIELD_HAS_XEDDSA_SIGNED_MASK, warmSignerOf(warm));
nodeInfoLiteSetBit(lite, NODEINFO_BITFIELD_HAS_XEDDSA_SIGNED_MASK, warmXeddsaSignedOf(warm));
if (!memfll(warm.public_key, 0, sizeof(warm.public_key))) {
lite->public_key.size = 32;
memcpy(lite->public_key.bytes, warm.public_key, 32);
@@ -4165,7 +4165,7 @@ meshtastic_NodeInfoLite *NodeDB::getOrCreateMeshNode(NodeNum n)
// its cached key matches the key we just restored from warm, so a name never attaches to
// a different identity than the one we encrypt to. No-op without the TMM NodeInfo cache
// or when no key is present (key-matched by design). CopyUserToNodeInfoLite sets only the
// user-related bits, so the warm-restored signer bit survives.
// user-related bits, so the warm-restored XEdDSA-signed bit survives.
if (lite->public_key.size == 32 && !nodeInfoLiteHasUser(lite) && trafficManagementModule) {
meshtastic_User tmmUser = meshtastic_User_init_zero;
if (trafficManagementModule->copyUser(n, tmmUser) && tmmUser.public_key.size == 32 &&
src/mesh/NodeDB.h
+4 -4
View File
@@ -419,15 +419,15 @@ class NodeDB
bool copyPublicKeyAuthoritative(NodeNum n, meshtastic_NodeInfoLite_public_key_t &out);
/// Key for the inbound-decrypt path: authoritative (hot/warm), or a cold-tier cache key only when
/// it is signer-proven. Keeps unverified TOFU cache keys from backing pki_encrypted attribution.
/// it is key-proven. Keeps unverified TOFU cache keys from backing pki_encrypted attribution.
bool copyPublicKeyForDecrypt(NodeNum n, meshtastic_NodeInfoLite_public_key_t &out);
/// True if n is a known XEdDSA signer for exactly `key32` (hot signed bitfield or warm
/// signer bit); the key match stops a rotated key inheriting a stale signer verdict.
/// xeddsa-signed bit); the key match stops a rotated key inheriting a stale signer verdict.
bool isVerifiedSignerForKey(NodeNum n, const uint8_t *key32);
/// Key-agnostic "should n's signable traffic arrive signed", per hot bitfield or warm signer
/// bit - hot-only gates would let a warm-evicted signer be impersonated with unsigned frames.
/// Key-agnostic "should n's signable traffic arrive signed", per hot bitfield or warm
/// xeddsa-signed bit - hot-only gates would let a warm-evicted signer be impersonated with unsigned frames.
bool isKnownXeddsaSigner(NodeNum n);
/// Provenance of a bare-key commit that deliberately bypasses updateUser()'s
src/mesh/Router.cpp
+1 -1
View File
@@ -838,7 +838,7 @@ DecodeState perhapsDecode(meshtastic_MeshPacket *p)
// Resolve the sender's key only for actual PKI-decrypt candidates, not every encrypted channel
// packet: copyPublicKeyForDecrypt() can fall through to a linear scan of TrafficManagement's large
// NodeInfo cache. It returns authoritative keys (hot/warm), or a cold-tier cache key only when it is
// signer-proven - an unverified TOFU cache key must not back authenticated (pki_encrypted, p->from)
// key-proven - an unverified TOFU cache key must not back authenticated (pki_encrypted, p->from)
// DM attribution.
meshtastic_NodeInfoLite_public_key_t remotePublic = {0, {0}};
bool haveRemoteKey = nodeDB->copyPublicKeyForDecrypt(p->from, remotePublic);
src/mesh/WarmNodeStore.cpp
+13 -12
View File
@@ -13,7 +13,7 @@
#if defined(NRF52840_XXAA)
#include "flash/flash_nrf5x.h"
#define WARM_RING_MAGIC 0x334E5257u // "WRN3" - v3: last_heard low bits carry role + protected + signer
#define WARM_RING_MAGIC 0x334E5257u // "WRN3" - v3: last_heard low bits carry role + protected + xeddsa-signed
#define WARM_RING_MAGIC_V2 0x324E5257u // "WRN2" - v2: role + protected only; bit 6 was still timestamp.
#define WARM_RING_MAGIC_V1 0x474E5257u // "WRNG" - v1: last_heard was a plain timestamp.
// Older pages are still read on upgrade: v1 keeps identity + key but discards last_heard,
@@ -33,10 +33,10 @@ struct WarmStoreHeader {
};
static_assert(sizeof(WarmStoreHeader) == 16, "header layout is part of the persistence format");
#define WARM_STORE_MAGIC 0x334D5257u // "WRM3" - v3: last_heard low bits carry role + protected + signer
#define WARM_STORE_MAGIC 0x334D5257u // "WRM3" - v3: last_heard low bits carry role + protected + xeddsa-signed
#define WARM_STORE_MAGIC_V2 \
0x324D5257u // "WRM2" - v2: role + protected only; bit 6 was still timestamp. On upgrade
// we clear the signer bit, then rewrite as v3.
// we clear the xeddsa-signed bit, then rewrite as v3.
#define WARM_STORE_MAGIC_V1 \
0x314D5257u // "WRM1" - v1: last_heard was a plain timestamp. On upgrade we keep
// identity + key but discard last_heard, then rewrite as v3.
@@ -136,18 +136,19 @@ WarmNodeEntry *WarmNodeStore::place(NodeNum num, uint32_t lastHeard, const uint8
return slot;
}
bool WarmNodeStore::absorb(NodeNum num, uint32_t lastHeard, const uint8_t *key32, uint8_t role, uint8_t protectedCat, bool signer)
bool WarmNodeStore::absorb(NodeNum num, uint32_t lastHeard, const uint8_t *key32, uint8_t role, uint8_t protectedCat,
bool xeddsaSigned)
{
// Pack role + protected category + signer into the low bits of last_heard. place() and
// Pack role + protected category + xeddsa-signed into the low bits of last_heard. place() and
// ring replay store the raw word verbatim, so the metadata round-trips through flash.
const uint32_t packed = warmPackLastHeard(lastHeard, role, protectedCat, signer);
const uint32_t packed = warmPackLastHeard(lastHeard, role, protectedCat, xeddsaSigned);
const WarmNodeEntry *slot = place(num, packed, key32);
if (!slot)
return false;
persistEntry(*slot);
LOG_MIGRATION("WarmStore absorb 0x%08x key=%d last_heard=%u role=%u prot=%u signer=%u (now %u/%u)", (unsigned)num,
LOG_MIGRATION("WarmStore absorb 0x%08x key=%d last_heard=%u role=%u prot=%u xeddsa=%u (now %u/%u)", (unsigned)num,
keyIsSet(slot->public_key) ? 1 : 0, (unsigned)warmTimeOf(*slot), (unsigned)role, (unsigned)protectedCat,
signer ? 1u : 0u, (unsigned)count(), (unsigned)capacity());
xeddsaSigned ? 1u : 0u, (unsigned)count(), (unsigned)capacity());
return true;
}
@@ -161,10 +162,10 @@ bool WarmNodeStore::lookupMeta(NodeNum num, uint8_t &role, uint8_t &protectedCat
return true;
}
bool WarmNodeStore::isVerifiedSigner(NodeNum num) const
bool WarmNodeStore::hasXeddsaSigned(NodeNum num) const
{
const WarmNodeEntry *e = find(num);
return e && warmSignerOf(*e);
return e && warmXeddsaSignedOf(*e);
}
bool WarmNodeStore::take(NodeNum num, WarmNodeEntry &out)
@@ -464,7 +465,7 @@ void WarmNodeStore::load()
lh = 0;
migrated++;
} else if (fmt == WarmFormat::V2) {
lh &= ~(WARM_SIGNER_MASK << WARM_SIGNER_SHIFT);
lh &= ~(WARM_XEDDSA_SIGNED_MASK << WARM_XEDDSA_SIGNED_SHIFT);
migrated++;
}
const WarmNodeEntry *e = place(rec.num, lh, rec.public_key);
@@ -589,7 +590,7 @@ void WarmNodeStore::load()
} else if (fmt == WarmFormat::V2) {
for (size_t i = 0; i < WARM_NODE_COUNT; i++)
if (entries[i].num)
entries[i].last_heard &= ~(WARM_SIGNER_MASK << WARM_SIGNER_SHIFT);
entries[i].last_heard &= ~(WARM_XEDDSA_SIGNED_MASK << WARM_XEDDSA_SIGNED_SHIFT);
dirty = true;
}
} else {
src/mesh/WarmNodeStore.h
+12 -12
View File
@@ -43,21 +43,21 @@ static_assert(sizeof(WarmNodeEntry) == 40, "WarmNodeEntry must stay 40 B - persi
//
// The warm tier only uses last_heard to LRU-rank evicted (long-tail) nodes, so ~minute
// recency resolution is plenty. We reclaim the low WARM_META_BITS of that field to carry
// the evicted node's device role, a protected category + a signer flag, at zero cost to
// the evicted node's device role, a protected category + an XEdDSA-signed flag, at zero cost to
// record size (entry stays 40 B; no RAM/flash growth). The high bits remain a real
// unix-seconds timestamp quantised to (1 << WARM_META_BITS) seconds.
//
// Safe because: a real timestamp can never be all-ones (the tombstone sentinel) before
// 2106, and tombstones/erased flash are detected via num before last_heard is read. Only
// the LOW bits are stolen - the high (era) bits are untouched, so the time range is intact.
static constexpr uint32_t WARM_META_BITS = 7; // role(4) + protected(2) + signer(1)
static constexpr uint32_t WARM_META_BITS = 7; // role(4) + protected(2) + xeddsa-signed(1)
static constexpr uint32_t WARM_META_MASK = (1u << WARM_META_BITS) - 1; // 0x7F → 128 s quantum
static constexpr uint32_t WARM_TIME_MASK = ~WARM_META_MASK; // 0xFFFFFF80
static constexpr uint32_t WARM_ROLE_MASK = 0x0Fu; // bits [3:0] device role (0..12)
static constexpr uint32_t WARM_PROT_SHIFT = 4; // bits [5:4] protected category
static constexpr uint32_t WARM_PROT_MASK = 0x03u;
static constexpr uint32_t WARM_SIGNER_SHIFT = 6; // bit [6] we verified an XEdDSA signature from this node
static constexpr uint32_t WARM_SIGNER_MASK = 0x01u;
static constexpr uint32_t WARM_XEDDSA_SIGNED_SHIFT = 6; // bit [6] we verified an XEdDSA signature from this node
static constexpr uint32_t WARM_XEDDSA_SIGNED_MASK = 0x01u;
// On-disk record format, from the page/file magic; older ones are normalised by load().
enum class WarmFormat : uint8_t { Current, V2, V1 };
@@ -65,11 +65,11 @@ enum class WarmFormat : uint8_t { Current, V2, V1 };
// Protected category cached alongside role so consumers needn't re-derive the mapping.
enum class WarmProtected : uint8_t { None = 0, Role = 1, Flag = 2, XeddsaSigner = 3 };
inline uint32_t warmPackLastHeard(uint32_t lastHeard, uint8_t role, uint8_t prot, bool signer)
inline uint32_t warmPackLastHeard(uint32_t lastHeard, uint8_t role, uint8_t prot, bool xeddsaSigned)
{
return (lastHeard & WARM_TIME_MASK) | (static_cast<uint32_t>(role) & WARM_ROLE_MASK) |
((static_cast<uint32_t>(prot) & WARM_PROT_MASK) << WARM_PROT_SHIFT) |
((signer ? WARM_SIGNER_MASK : 0u) << WARM_SIGNER_SHIFT);
((xeddsaSigned ? WARM_XEDDSA_SIGNED_MASK : 0u) << WARM_XEDDSA_SIGNED_SHIFT);
}
inline uint32_t warmTimeOf(const WarmNodeEntry &e)
{
@@ -83,9 +83,9 @@ inline uint8_t warmProtOf(const WarmNodeEntry &e)
{
return static_cast<uint8_t>((e.last_heard >> WARM_PROT_SHIFT) & WARM_PROT_MASK);
}
inline bool warmSignerOf(const WarmNodeEntry &e)
inline bool warmXeddsaSignedOf(const WarmNodeEntry &e)
{
return ((e.last_heard >> WARM_SIGNER_SHIFT) & WARM_SIGNER_MASK) != 0;
return ((e.last_heard >> WARM_XEDDSA_SIGNED_SHIFT) & WARM_XEDDSA_SIGNED_MASK) != 0;
}
// Gated on NRF52840_XXAA: the ring sits at 0xEA000
@@ -109,19 +109,19 @@ class WarmNodeStore
/// entries; otherwise the oldest (keyless-first) entry is replaced.
/// @param role the node's device role (meshtastic_Config_DeviceConfig_Role, 0..12)
/// @param protectedCat WarmProtected category cached for the hop-trim path
/// @param signer true if we ever verified an XEdDSA signature from this node, so
/// @param xeddsaSigned true if we ever verified an XEdDSA signature from this node, so
/// re-admission restores the bit rather than relearning it
/// @return true if the node was stored or updated
bool absorb(NodeNum num, uint32_t lastHeard, const uint8_t *key32 /* may be NULL */, uint8_t role = 0,
uint8_t protectedCat = 0, bool signer = false);
uint8_t protectedCat = 0, bool xeddsaSigned = false);
/// Look up the cached device role + protected category for a warm node.
/// @return false if the node is not in the warm tier.
bool lookupMeta(NodeNum num, uint8_t &role, uint8_t &protectedCat) const;
/// True if the warm tier holds this node with its signer bit set (an XEdDSA signature
/// True if the warm tier holds this node with its XEdDSA-signed bit set (an XEdDSA signature
/// was verified from it before eviction).
bool isVerifiedSigner(NodeNum num) const;
bool hasXeddsaSigned(NodeNum num) const;
/// Find and remove an entry (used when the node is re-admitted to the hot store).
bool take(NodeNum num, WarmNodeEntry &out);
src/modules/TrafficManagementModule.cpp
+58 -41
View File
@@ -439,7 +439,7 @@ const TrafficManagementModule::NodeInfoPayloadEntry *TrafficManagementModule::fi
/// Find or create a NodeInfo payload entry. Victim selection is trust-tiered so the cache
/// doubles as a pubkey pool: NodeDB membership outranks key trust, then keyless < TOFU key <
/// signer-proven key; within a tier the oldest observation loses (never-observed = oldest).
/// key-proven key; within a tier the oldest observation loses (never-observed = oldest).
TrafficManagementModule::NodeInfoPayloadEntry *
TrafficManagementModule::findOrCreateNodeInfoEntry(NodeNum node, bool *usedEmptySlot, bool spareMembers)
{
@@ -466,9 +466,9 @@ TrafficManagementModule::findOrCreateNodeInfoEntry(NodeNum node, bool *usedEmpty
}
if (empty)
continue; // an empty slot beats any victim; stop scoring
// Eviction tier (lower loses first): 0 keyless, 1 TOFU key, 2 signer-proven key;
// Eviction tier (lower loses first): 0 keyless, 1 TOFU key, 2 key-proven key;
// +3 for NodeDB members - never shed a NodeDB-tier identity over a stranger.
const uint8_t tier = static_cast<uint8_t>(((entry.user.public_key.size != 32) ? 0 : (entry.keySignerProven ? 2 : 1)) +
const uint8_t tier = static_cast<uint8_t>(((entry.user.public_key.size != 32) ? 0 : (entry.keyProven() ? 2 : 1)) +
(entry.isMember ? 3 : 0));
// Modular observation age; saturation keeps real ages far below the 0xFF a
// never-observed entry scores, so that entry is always the oldest in its tier.
@@ -549,10 +549,18 @@ void TrafficManagementModule::reconcileNodeInfoFromNodeDBLocked()
memcpy(entry->user.public_key.bytes, key32, 32);
entry->user.public_key.size = 32;
}
if (keyChanged)
entry->keySignerProven = false;
if (signerKnown && key32 && entry->user.public_key.size == 32 && memcmp(entry->user.public_key.bytes, key32, 32) == 0)
entry->keySignerProven = true;
if (keyChanged) {
entry->keyXeddsaSigned = false;
entry->keyManuallyVerified = false;
}
const bool keyMatch = key32 && entry->user.public_key.size == 32 && memcmp(entry->user.public_key.bytes, key32, 32) == 0;
if (signerKnown && keyMatch)
entry->keyXeddsaSigned = true;
// Manual verification is a hot-store fact (is_key_manually_verified); re-seed it here so a
// reconciled/re-created slot doesn't silently drop it. Warm-only records (hot == nullptr)
// don't carry the flag, so this only fires on the hot-tier pass.
if (hot && keyMatch && nodeInfoLiteIsKeyManuallyVerified(hot))
entry->keyManuallyVerified = true;
entry->isMember = true;
};
@@ -571,7 +579,7 @@ void TrafficManagementModule::reconcileNodeInfoFromNodeDBLocked()
if (!warm)
continue;
const bool hasKey = !memfll(warm->public_key, 0, sizeof(warm->public_key));
reconcileOne(warm->num, hasKey ? warm->public_key : nullptr, warmSignerOf(*warm), nullptr);
reconcileOne(warm->num, hasKey ? warm->public_key : nullptr, warmXeddsaSignedOf(*warm), nullptr);
}
#endif
@@ -670,12 +678,17 @@ void TrafficManagementModule::onNodeIdentityCommitted(NodeNum node, const meshta
// and may be re-proven by signerKnown below - which vouches for the COMMITTED key only.
const bool sameKey = !usedEmptySlot && entry->user.public_key.size == 32 && merged.public_key.size == 32 &&
memcmp(entry->user.public_key.bytes, merged.public_key.bytes, 32) == 0;
const bool provenBefore = !usedEmptySlot && entry->keySignerProven && sameKey;
// Each provenance channel survives independently alongside an unchanged key. signerKnown
// (from updateUser's isVerifiedSignerForKey) is the XEdDSA verdict for the COMMITTED key;
// the manual bit isn't carried on this path, so it's only preserved, never freshly set here.
const bool xeddsaBefore = !usedEmptySlot && entry->keyXeddsaSigned && sameKey;
const bool manualBefore = !usedEmptySlot && entry->keyManuallyVerified && sameKey;
entry->user = merged;
snprintf(entry->user.id, sizeof(entry->user.id), "!%08x", node);
entry->hasFullUser = true;
entry->keySignerProven = provenBefore || (signerKnown && user.public_key.size == 32);
entry->keyXeddsaSigned = xeddsaBefore || (signerKnown && user.public_key.size == 32);
entry->keyManuallyVerified = manualBefore;
entry->isMember = true; // committed via updateUser => it sits in the hot store right now
// obsTick/hasObserved deliberately untouched: only a heard frame makes a node servable.
}
@@ -699,16 +712,19 @@ void TrafficManagementModule::onNodeKeyCommitted(NodeNum node, const uint8_t key
memcpy(entry->user.public_key.bytes, key32, 32);
entry->user.public_key.size = 32;
entry->isMember = true; // the caller just committed it to the hot store
// A rotated key never inherits the old key's verdict; `proven` (manual verification of
// exactly this key) is the strongest provenance this cache can carry.
if (keyChanged)
entry->keySignerProven = false;
// A rotated key never inherits the old key's verdict; `proven` here means the user manually
// verified possession of exactly this key (KeyCommitTrust::ManuallyVerified) - it routes to
// the manual bit, not the XEdDSA one.
if (keyChanged) {
entry->keyXeddsaSigned = false;
entry->keyManuallyVerified = false;
}
if (proven)
entry->keySignerProven = true;
entry->keyManuallyVerified = true;
// hasObserved/obsTick untouched: a key commit is knowledge, not an observation.
}
bool TrafficManagementModule::copyPublicKey(NodeNum node, uint8_t out[32], bool *signerProven) const
bool TrafficManagementModule::copyPublicKey(NodeNum node, uint8_t out[32], bool *keyProven) const
{
// Same enable gate as the write-through hooks and maintenance: a disabled module stops
// updating and sweeping the cache, so its frozen contents must not keep feeding PKI key
@@ -724,12 +740,12 @@ bool TrafficManagementModule::copyPublicKey(NodeNum node, uint8_t out[32], bool
return false;
memcpy(out, entry->user.public_key.bytes, 32);
if (signerProven)
*signerProven = entry->keySignerProven;
if (keyProven)
*keyProven = entry->keyProven();
return true;
}
bool TrafficManagementModule::copyUser(NodeNum node, meshtastic_User &out, bool *signerProven) const
bool TrafficManagementModule::copyUser(NodeNum node, meshtastic_User &out, bool *keyProven) const
{
// Enable gate, as in copyPublicKey(): a disabled module must not feed name rehydration
// from frozen cache contents once its maintenance/write-through have stopped.
@@ -746,8 +762,8 @@ bool TrafficManagementModule::copyUser(NodeNum node, meshtastic_User &out, bool
return false;
out = entry->user;
if (signerProven)
*signerProven = entry->keySignerProven;
if (keyProven)
*keyProven = entry->keyProven();
return true;
}
@@ -830,11 +846,12 @@ void TrafficManagementModule::cacheNodeInfoPacket(const meshtastic_MeshPacket &m
entry->hasDecodedBitfield = mp.decoded.has_bitfield;
entry->decodedBitfield = mp.decoded.bitfield;
// Upgrade to signer-proven on a Router-verified signature or a NodeDB signer verdict
// for this same key. Never downgrade (a later unsigned frame leaves the flag set),
// and the key itself cannot change here - the pin checks above already rejected that.
// Upgrade the XEdDSA-signed bit on a Router-verified signature or a NodeDB signer verdict
// for this same key (both are XEdDSA provenance). Never downgrade (a later unsigned frame
// leaves it set), and the key cannot change here - the pin checks above already rejected
// that. The manual-verification bit is orthogonal and untouched on this observation path.
if ((mp.xeddsa_signed || dbSaysSigner) && user.public_key.size == 32)
entry->keySignerProven = true;
entry->keyXeddsaSigned = true;
if (usedEmptySlot)
cachedCount = countNodeInfoEntriesLocked();
@@ -866,18 +883,17 @@ int TrafficManagementModule::peekNodeInfoFlagsForTest(NodeNum node)
const NodeInfoPayloadEntry *entry = findNodeInfoEntry(node);
if (!entry)
return -1;
return (entry->hasObserved ? 1 : 0) | (entry->isMember ? 2 : 0) | (entry->hasFullUser ? 4 : 0) |
(entry->keySignerProven ? 8 : 0);
return (entry->hasObserved ? 1 : 0) | (entry->isMember ? 2 : 0) | (entry->hasFullUser ? 4 : 0) | (entry->keyProven() ? 8 : 0);
}
void TrafficManagementModule::markKeySignerProvenForTest(NodeNum node)
void TrafficManagementModule::markKeyXeddsaSignedForTest(NodeNum node)
{
concurrency::LockGuard guard(&cacheLock);
if (!nodeInfoPayload)
return;
for (uint16_t i = 0; i < nodeInfoTargetEntries(); i++) {
if (nodeInfoPayload[i].node == node) {
nodeInfoPayload[i].keySignerProven = true;
nodeInfoPayload[i].keyXeddsaSigned = true;
return;
}
}
@@ -918,7 +934,7 @@ int TrafficManagementModule::peekNodeInfoFlagsForTest(NodeNum)
{
return -1;
}
void TrafficManagementModule::markKeySignerProvenForTest(NodeNum) {}
void TrafficManagementModule::markKeyXeddsaSignedForTest(NodeNum) {}
#endif // TMM_HAS_NODEINFO_CACHE
@@ -1414,9 +1430,9 @@ bool TrafficManagementModule::shouldRespondToNodeInfo(const meshtastic_MeshPacke
uint8_t cachedSourceChannel = 0;
bool cachedHasObserved = false;
uint8_t cachedObsTick = 0;
// Signer-proven provenance of the cached key, consumed by the replay gate below
// Key-proven provenance (XEdDSA-signed | manually verified) of the cached key, consumed by the replay gate below
// (maybe_unused: read only when TMM_NODEINFO_REPLAY_SIGNED_GATE is compiled in).
[[maybe_unused]] bool cachedKeySignerProven = false;
[[maybe_unused]] bool cachedKeyProven = false;
// True once we commit to answering from the NodeDB fallback (no NodeInfo cache) path. The
// response throttle no longer distinguishes the paths - the per-requester/per-target RAM
// tables cover both - but the replay gate below still keys off it.
@@ -1433,7 +1449,7 @@ bool TrafficManagementModule::shouldRespondToNodeInfo(const meshtastic_MeshPacke
cachedSourceChannel = entry->sourceChannel;
cachedHasObserved = entry->hasObserved;
cachedObsTick = entry->obsTick;
cachedKeySignerProven = entry->keySignerProven;
cachedKeyProven = entry->keyProven();
}
}
@@ -1461,11 +1477,12 @@ bool TrafficManagementModule::shouldRespondToNodeInfo(const meshtastic_MeshPacke
return false;
}
#if TMM_NODEINFO_REPLAY_SIGNED_GATE
// Replay provenance gate (fallback path): only vouch for a node NodeDB knows as a
// verified signer. An unproven (trust-on-first-use) identity is left for the genuine
// node or another cache-holder to answer.
if (!nodeInfoLiteHasXeddsaSigned(node)) {
TM_LOG_DEBUG("NodeInfo NodeDB entry for 0x%08x not signer-proven, not responding", p->to);
// Replay provenance gate (fallback path): only vouch for a node whose key NodeDB has
// proven - an XEdDSA-verified signer or a manually-verified key. This mirrors the cache
// path's keyProven() (XEdDSA | manual). An unproven (trust-on-first-use) identity is left
// for the genuine node or another cache-holder to answer.
if (!nodeInfoLiteHasXeddsaSigned(node) && !nodeInfoLiteIsKeyManuallyVerified(node)) {
TM_LOG_DEBUG("NodeInfo NodeDB entry for 0x%08x not key-proven, not responding", p->to);
return false;
}
#endif
@@ -1483,10 +1500,10 @@ bool TrafficManagementModule::shouldRespondToNodeInfo(const meshtastic_MeshPacke
}
#if TMM_NODEINFO_REPLAY_SIGNED_GATE
// Replay provenance gate (cache path): only spoof a reply for a signer-proven cached key.
// Replay provenance gate (cache path): only spoof a reply for a key-proven cached key.
// usedFallback entries were already gated above. See TMM_NODEINFO_REPLAY_REQUIRE_SIGNED.
if (!usedFallback && !cachedKeySignerProven) {
TM_LOG_DEBUG("NodeInfo cache entry for 0x%08x not signer-proven, not responding", p->to);
if (!usedFallback && !cachedKeyProven) {
TM_LOG_DEBUG("NodeInfo cache entry for 0x%08x not key-proven, not responding", p->to);
return false;
}
#endif
src/modules/TrafficManagementModule.h
+25 -14
View File
@@ -9,7 +9,7 @@
#if HAS_TRAFFIC_MANAGEMENT
// Replay provenance gate: when 1 (default), direct responses are spoofed only for nodes whose
// cached key is signer-proven (XEdDSA-verified), not for trust-on-first-use identities.
// cached key is key-proven (XEdDSA-signed or manually verified), not for trust-on-first-use identities.
// Define as 0 to also serve fresh TOFU-only nodes; bypassed entirely when PKI is excluded.
#ifndef TMM_NODEINFO_REPLAY_REQUIRE_SIGNED
#define TMM_NODEINFO_REPLAY_REQUIRE_SIGNED 1
@@ -65,14 +65,14 @@ class TrafficManagementModule : public MeshModule, private concurrency::OSThread
bool preloadNextHopsFromNodeDB();
/// Last-resort key source for NodeDB::copyPublicKey() after the hot and warm tiers miss.
/// Copies the 32-byte key for `node` into out[32]; `signerProven` (optional) reports whether
/// the key was XEdDSA-verified vs trust-on-first-use. Thread-safe.
bool copyPublicKey(NodeNum node, uint8_t out[32], bool *signerProven = nullptr) const;
/// Copies the 32-byte key for `node` into out[32]; `keyProven` (optional) reports whether
/// the key is proven (XEdDSA-signed or manually verified) vs trust-on-first-use. Thread-safe.
bool copyPublicKey(NodeNum node, uint8_t out[32], bool *keyProven = nullptr) const;
/// Copy the full cached User for `node` (used by NodeDB to rehydrate a re-admitted node's
/// name - the warm tier keeps keys but not names). False on miss or key-only records.
/// `signerProven` (optional) reports the cached key's provenance. Thread-safe.
bool copyUser(NodeNum node, meshtastic_User &out, bool *signerProven = nullptr) const;
/// `keyProven` (optional) reports the cached key's provenance. Thread-safe.
bool copyUser(NodeNum node, meshtastic_User &out, bool *keyProven = nullptr) const;
/// Write-through hook from NodeDB::updateUser(): upsert the committed identity immediately
/// (the reconcile sweep remains the backstop). NodeDB's key is authoritative, but a keyless
@@ -125,16 +125,16 @@ class TrafficManagementModule : public MeshModule, private concurrency::OSThread
/// (distinguishes "not tracked" from CLIENT == 0).
int peekCachedRole(NodeNum node);
/// Test hook: force a cached NodeInfo entry's key to signer-proven so replay-gate tests
/// Test hook: force a cached NodeInfo entry's key to XEdDSA-signed so replay-gate tests
/// can skip a full XEdDSA verification. No-op if absent.
void markKeySignerProvenForTest(NodeNum node);
void markKeyXeddsaSignedForTest(NodeNum node);
/// Test hook: free the NodeInfo cache so the NodeDB fallback path can be exercised in
/// builds where the cache is compiled in. No-op when already absent.
void dropNodeInfoCacheForTest();
/// Test introspection: NodeInfo flag bits for `node` (-1 if absent): bit0 hasObserved,
/// bit1 isMember, bit2 hasFullUser, bit3 keySignerProven.
/// bit1 isMember, bit2 hasFullUser, bit3 keyProven (keyXeddsaSigned | keyManuallyVerified).
int peekNodeInfoFlagsForTest(NodeNum node);
/// Test introspection: NodeInfo cache capacity (kNodeInfoCacheEntries), so tests can
@@ -253,16 +253,23 @@ class TrafficManagementModule : public MeshModule, private concurrency::OSThread
// in direct replies). Validity: hasDecodedBitfield.
uint8_t decodedBitfield;
// 1-bit flags, packed into one byte (6 spare bits; add future booleans here rather
// 1-bit flags, packed into one byte (2 spare bits; add future booleans here rather
// than new bytes - the array is 2000 entries).
// The source packet carried a decoded bitfield (so decodedBitfield is meaningful).
uint8_t hasDecodedBitfield : 1;
// Key provenance: set once an XEdDSA signature was verified for user.public_key
// (directly, or inherited from NodeDB via isVerifiedSignerForKey). Monotonic per slot;
// the key-pin checks forbid the key changing underneath it. TOFU keys start at 0.
uint8_t keySignerProven : 1;
// Key provenance, split by how possession was established (either one implies "proven" -
// read the pair via keyProven()). Both are monotonic per slot until the key rotates (the
// key-pin checks forbid the key changing underneath them), and TOFU keys start at 0.
//
// keyXeddsaSigned: an XEdDSA signature was verified for user.public_key - a heard signed
// frame, or inherited from NodeDB via isVerifiedSignerForKey.
uint8_t keyXeddsaSigned : 1;
// keyManuallyVerified: the user confirmed possession of exactly this key out-of-band
// (QR / fingerprint). Routed here via onNodeKeyCommitted(proven) and re-seeded from the
// hot-store is_key_manually_verified bit at reconcile (warm records don't carry it).
uint8_t keyManuallyVerified : 1;
// obsTick is valid: a NODEINFO frame was actually heard within the observation clock's
// horizon. Cleared by the sweep once the serve window passes (saturation).
@@ -277,6 +284,10 @@ class TrafficManagementModule : public MeshModule, private concurrency::OSThread
// removal; a passive NodeDB eviction may lag up to an hour). Member entries are
// stickiest under LRU; the bit is the keep-alive (no TTL).
uint8_t isMember : 1;
// Possession proven by either channel - the "key-proven" predicate the replay gate,
// eviction tiering, and NodeDB pubkey-pool callers consume.
bool keyProven() const { return keyXeddsaSigned || keyManuallyVerified; }
};
// No exact-size static_assert: sizeof(meshtastic_User) and its padding vary by platform, so
// any fixed byte count would fail the build on some boards.