Add ChaChaPoly AEAD-4 encryption with nonce persistence

[weebl2000]

Build firmware: Build from this branch

Testing

• Current testling on Heltec v4 companion and Heltec v4 repeater. It's working so far. Would be great if others can try with different devices, especially more constrained devices with less ram/flash storage.

Summary

Adds ChaCha20-Poly1305 (AEAD-4) encryption alongside the existing AES-128-ECB + HMAC-2 scheme, plus session key negotiation for Perfect Forward Secrecy. Updated nodes send AEAD-4 to peers that advertise support and fall back to ECB for legacy peers. All nodes can decode both formats. Old nodes continue to work unchanged.

Nonces are persisted to flash so they survive reboots without risk of reuse. Session keys are negotiated via ephemeral X25519 Diffie-Hellman and persisted immediately on establishment.

Relates to meshcore-dev#259.

What This Means in Practical Terms

The current encryption has a few weaknesses that this PR addresses:

• Message tampering is too easy to attempt. The existing 2-byte authentication code means an attacker only needs about 65,000 guesses to forge a valid-looking message. At LoRa speeds that's roughly 9 hours of continuous attempts. The new 4-byte tag raises this to over 4 billion guesses — at LoRa rates, that would take over a century.

• Identical messages look identical on the air. The current block cipher (ECB mode) produces the same ciphertext for the same plaintext, which can reveal patterns — for example, you could tell when someone sends the same message twice. The new scheme produces completely different ciphertext every time, even for identical messages.

• Addressing fields are now protected. Currently, only the message body is authenticated. With AEAD, the payload type and addressing hashes (which identify sender and recipient) are included in the authentication check, so an attacker cannot swap or modify them without detection. Outer routing fields like TTL and hop path are intentionally left unauthenticated so repeaters can still forward packets through the mesh.

• Messages get slightly smaller. ECB pads every message up to a 16-byte boundary, wasting airtime. The new scheme has no padding, so most messages shrink by a few bytes on the wire.

• Compromise of a node doesn't reveal past messages. Session key negotiation establishes fresh shared secrets via ephemeral key exchange. Even if a node's long-term private key is later compromised, previously recorded traffic cannot be decrypted (Perfect Forward Secrecy).

• Nothing breaks. Updated nodes send AEAD-4 to peers that advertise support, and fall back to ECB for legacy peers. Old nodes are completely unaffected — they never receive AEAD-4 messages because the sender checks their capability first.

• Nodes advertise their capabilities. Updated nodes include a flag in their advertisements saying "I understand the new encryption." When two updated nodes discover each other, they automatically start using AEAD-4 for their communication.

• Nonces survive reboots. Per-peer nonce counters are saved to flash periodically and before clean reboots. After a dirty reset (power loss, watchdog, brownout), nonces are bumped forward by a safety margin to guarantee no reuse.

Wire Format

Current ECB:

[HMAC:2] [ECB_ciphertext:N×16]     (padded to block boundary)

New AEAD-4 (same position in payload):

[nonce:2] [ciphertext:M] [tag:4]    (exact plaintext length, no padding)

Average overhead: ~6 bytes (AEAD) vs ~9.5 bytes (ECB). Most messages get smaller.

Cryptographic Design

Per-message key derivation (eliminates nonce-reuse catastrophe):

msg_key[32] = HMAC-SHA256(shared_secret, nonce || dest_hash || src_hash)

The shared_secret is either the static ECDH secret or a session key (see Session Key Negotiation below).

Including dest_hash || src_hash makes keys direction-dependent — Alice→Bob and Bob→Alice derive different keys even with the same nonce value (for 255/256 peer pairs; the 1/256 where dest_hash == src_hash is a residual limitation of 1-byte hashes).

IV construction (12 bytes, from on-wire fields):

iv[12] = { nonce_hi, nonce_lo, dest_hash, src_hash, 0, 0, 0, 0, 0, 0, 0, 0 }

Associated data (authenticated but not encrypted):

• Peer messages: header || dest_hash || src_hash
• Anonymous requests: header || dest_hash
• Group messages: header || channel_hash

Route type bits are masked out of the header in associated data (header & ~PH_ROUTE_MASK), since routing mode changes per hop as repeaters forward packets.

Nonce management: 16-bit counter per peer, persisted to flash. See "Nonce Persistence" section below.

Session Key Negotiation (Perfect Forward Secrecy)

Session keys provide Perfect Forward Secrecy by establishing fresh shared secrets via ephemeral X25519 Diffie-Hellman. Compromise of either node's long-term private key cannot recover traffic encrypted with a session key.

Protocol (2 messages + implicit confirmation)

Initiator                                   Responder
    |  1. REQ [REQ_TYPE_SESSION_KEY_INIT]        |
    |     [ephemeral_pub_A:32] (AEAD-4)          |
    | -----------------------------------------> |  derive session_key, persist, dual-decode
    |  2. RESPONSE [RESP_TYPE_SESSION_KEY_ACCEPT] |
    |     [ephemeral_pub_B:32] (static ECDH)     |
    | <----------------------------------------- |
    |  derive session_key, persist, nonce=1       |
    |  3. Any normal message (session key)       |
    | -----------------------------------------> |  confirm: drop old key

The INIT is encrypted with AEAD-4 (static ECDH or existing session key). The ACCEPT is always encrypted with the static ECDH secret, because the initiator hasn't derived the session key yet.

Key Derivation

ephemeral_secret = X25519(their_ephemeral_pub, my_ephemeral_prv)
session_key[32]  = HMAC-SHA256(static_shared_secret, ephemeral_secret)

Uses existing ed25519_key_exchange() (X25519 Montgomery ladder) from lib/ed25519. No new dependencies.

Who Initiates

• Companion ↔ Repeater/Room/Sensor: Companion initiates, server responds
• Companion ↔ Companion: Either side can initiate, both can respond

Repeaters, room servers, and sensors only implement the responder role — they never initiate session key negotiation.

Automatic Triggers

Session key negotiation is triggered automatically based on message count. The trigger check runs inside getEncryptionNonceFor() — the single funnel all encrypted sends pass through — so no send path can silently skip it. Negotiation is deferred to the next loop() tick to avoid re-entrancy.

Hop count	Current key	Trigger	Retry after failure
0 (direct)	Static ECDH	Every 100 msgs	100 msgs
0 (direct)	Session key	nonce > 60000, then every 100 msgs	100 msgs
1–9	Static ECDH	Every 500 msgs	500 msgs
1–9	Session key	nonce > 60000, then every 300 msgs	300 msgs
10+	Static ECDH	Every 1000 msgs	1000 msgs
10+	Session key	nonce > 60000, then every 300 msgs	300 msgs

3 INIT attempts per negotiation (3-minute timeout each).

Nonce Lifecycle

• New contacts: Static ECDH nonce seeded from RNG in range 1000–50000
• Session key nonce: Starts at 1 on establishment, full 65535 budget per session
• Nonce exhaustion: Fall back to static ECDH, keep retrying negotiation at tier intervals

Encryption Key Selection

All node types use paired getEncryptionKey() / getEncryptionNonce() functions that return the correct key and nonce based on current session state:

has_session_key && sends_since_last_recv < 50  → AEAD with session key
has_session_key && sends_since_last_recv >= 50 → AEAD with static ECDH (stale probe)
CONTACT_FLAG_AEAD && nonce OK                  → AEAD with static ECDH
CONTACT_FLAG_AEAD && nonce exhausted           → ECB (pending renegotiation)
else                                           → ECB (legacy peer)

Decode Order

has_session_key: session_key → prev_session_key (dual-decode) → static ECDH → ECB
CONTACT_FLAG_AEAD: static ECDH → ECB
else: ECB → static ECDH

Dual-Decode Window

When the responder accepts a session key INIT, it enters DUAL_DECODE state: the new session key is active for sending, but both old and new keys are accepted for decoding. Once the initiator sends a message encrypted with the new session key (message 3), the responder confirms the transition and drops the old key.

This makes ACCEPT packet loss safe — the responder stays in dual-decode, the initiator times out and retries, and no messages are lost.

Stale Session Detection

If a node sends 50 consecutive messages without receiving any session-key-encrypted reply, it falls back to static ECDH for sending (the peer may have lost the session key). At 100 unanswered sends, falls back to ECB. At 255, clears the AEAD capability flag and removes the session key entirely. The counter resets to 0 on any successful session-key-encrypted message from the peer.

Session Key Persistence

Session keys use a two-tier storage model: a small RAM pool for active sessions and a larger flash-backed store for less recently used entries.

RAM pool: 8 slots (MAX_SESSION_KEYS_RAM), managed as an LRU cache. Each access touches a counter so the least-recently-used entry can be evicted when the pool is full. Entries in INIT_SENT state (ephemeral keys only) are never evicted — they must complete or time out.

Flash store: Up to 48 entries (MAX_SESSION_KEYS_FLASH), persisted to /sess_keys (companion) or /s_sess_keys (server firmware).

Variable-length records: Entries without a previous session key (no dual-decode) use 39 bytes (SESSION_KEY_RECORD_MIN_SIZE); entries with a previous key use 71 bytes (SESSION_KEY_RECORD_SIZE). The SESSION_FLAG_PREV_VALID flag bit distinguishes the two.

Without prev_key: [pub_key_prefix:4] [flags:1] [nonce:2] [session_key:32]         = 39 bytes
With prev_key:    [pub_key_prefix:4] [flags:1] [nonce:2] [session_key:32] [prev_session_key:32] = 71 bytes

On-demand flash lookup: When findSessionKey() misses the RAM pool, it reads the flash file to look for a matching entry. If found, the entry is loaded into RAM (evicting LRU if needed) and returned.

Merge-save strategy: When persisting, the code reads existing flash entries, filters out any that are already in the RAM pool or have been explicitly removed, then writes the merged result (RAM entries + surviving flash-only entries). This prevents flash from resurrecting deleted entries while preserving entries that were evicted from RAM.

Removed-entry tracking: When a session key is explicitly removed (e.g., invalidation after static ECDH fallback), its prefix is recorded in a small tracking array. The merge-save step skips these prefixes so the deleted entry doesn't reappear from stale flash data. The tracking array is cleared after each successful save.

Nonce Persistence

Nonces are persisted to a dedicated file on flash (/nonces for companion radios, /s_nonces for server firmware).

Periodic saves: After every NONCE_PERSIST_INTERVAL (50) messages to a given peer, the nonce file is written. A dirty flag tracks whether any nonce has advanced since the last save.

Clean reboot: Software restarts and deep sleep wakes load the persisted nonces as-is. A onBeforeReboot() callback in CommonCLI flushes any dirty nonces before the restart.

Dirty reboot: Power-on, watchdog, and brownout resets are detected via wasDirtyReset() (platform-specific: esp_reset_reason() on ESP32, RESETREAS register on NRF52). After a dirty reset, all loaded nonces are bumped forward by NONCE_BOOT_BUMP (100), which is at least 2× the persist interval, guaranteeing that even the worst-case unpersisted nonce is safely skipped. Session key nonces also receive the boot bump; if the bump causes a wrap, the nonce is forced to 65535 to trigger renegotiation.

Format: Simple array of {pub_key_prefix[6], nonce[2]} entries, matched to in-memory contacts/clients on load.

Security Comparison

Property	ECB + HMAC-2 (current)	AEAD-4 (new)	AEAD-4 + Session Key
Confidentiality	Identical blocks → identical ciphertext	Unique keystream per message	Same
Forgery resistance	1/65K (~9 hours at LoRa rates)	1/4.3B (~136 years)	Same
Key usage	16 of 32 bytes (AES-128)	Full 32 bytes (ChaCha20-256)	Same
Addressing authentication	None	Payload type & address hashes via AAD	Same
MAC timing	memcmp (timing side-channel)	secure_compare (constant-time)	Same
Padding waste	0-15 bytes per message	None	None
Perfect Forward Secrecy	No	No	Yes
Nonce reuse on reboot	N/A (no nonces)	Mitigated by persistence + boot bump	Same

Scope

Payload type	AEAD-4 decode	AEAD-4 send	Session keys	Notes
TXT_MSG, REQ, RESPONSE, PATH	Yes	Yes (if peer advertises AEAD)	Yes	Per-peer secret, no collision risk
ANON_REQ	Yes	No (no prior capability exchange)	No	Ephemeral ECDH secret
GRP_TXT, GRP_DATA	Yes	No (see group considerations)	No	Shared channel key

All node types (companion radio, repeater, room server, sensor) support AEAD-4 decode, AEAD-4 send, and session key negotiation (companion initiates or responds; server firmware responds only).

Group Message Considerations

Group channels share a single key among all members. With a 2-byte nonce and multiple senders, cross-sender nonce collisions follow the birthday bound (~300 messages for 50% probability on an active channel). A collision leaks P1 ⊕ P2 for that specific message pair via crib-dragging, but:

• No key recovery — per-message key derivation via HMAC-SHA256 is one-way
• No cascade — each collision is isolated, doesn't affect other messages
• Bounded threat model — the attacker must not have the channel PSK (if they do, they can already read everything)

This is mainly beneficial for public/hashtag channels where the PSK is already widely known and the ECB pattern leakage and weak MAC are a greater concern than the bounded nonce collision risk.

Potential future mitigations explored and deferred:

• Per-sender derived keys (HMAC(channel_secret, sender_pub_key)) — eliminates cross-sender collisions but requires receivers to know all senders' public keys, changing the group security model from "know the PSK = full access" to "know the PSK + sender discovery = access." Ruled out as a usability regression.
• Expanded nonce (4 bytes instead of 2) — pushes birthday bound to ~65,000 messages (~2 years at 100 msgs/day). Costs 2 extra bytes of airtime and creates a different wire format for groups vs peers.
• Sender hash byte on wire — differentiates senders for key derivation at 1 byte cost, but leaks sender identity metadata (traffic correlation, identification via adverts) that is currently hidden inside the encrypted payload.

Decode Order

Adaptive per-peer: for peers with CONTACT_FLAG_AEAD set, try AEAD-4 first then ECB fallback. For unknown/legacy peers, try ECB first then AEAD-4 fallback. When a session key exists, decode order is: session key → prev session key (dual-decode window) → static ECDH → ECB. This avoids the 1/65536 ECB false-positive rate on AEAD packets (nonce bytes matching truncated HMAC) for known AEAD peers, while minimizing wasted CPU for legacy peers.

Capability Advertisement

• feat1 bit 0 (FEAT1_AEAD_SUPPORT) is set in adverts for all node types (chat, repeater, room, sensor)
• Receivers record peer capability in ContactInfo.flags bit 1 (CONTACT_FLAG_AEAD)
• Old nodes parse feat1 but ignore the value (forward-compatible via existing AdvertDataParser)

Files Changed

Core Library

• src/MeshCore.h — AEAD constants, session key constants (SESSION_KEY_SIZE, REQ_TYPE_SESSION_KEY_INIT, RESP_TYPE_SESSION_KEY_ACCEPT, NONCE_REKEY_THRESHOLD, SESSION_KEY_* thresholds and limits), two-tier pool sizing (MAX_SESSION_KEYS_RAM=8, MAX_SESSION_KEYS_FLASH=48), variable-length record sizes (SESSION_KEY_RECORD_SIZE, SESSION_KEY_RECORD_MIN_SIZE), SESSION_FLAG_PREV_VALID
• src/Utils.h / src/Utils.cpp — aeadEncrypt() and aeadDecrypt() using ChaChaPoly
• src/Mesh.h — getPeerFlags(), getPeerNextAeadNonce(), getPeerSessionKey(), getPeerPrevSessionKey(), onSessionKeyDecryptSuccess(), getPeerEncryptionKey(), getPeerEncryptionNonce() virtuals; aead_nonce param on createDatagram/createPathReturn
• src/Mesh.cpp — AEAD send path in createDatagram/createPathReturn; session key → prev session key → static ECDH → ECB adaptive decode order
• src/helpers/ContactInfo.h — uint16_t aead_nonce field, nextAeadNonce() helper
• src/helpers/SessionKeyPool.h — SessionKeyEntry struct and SessionKeyPool class (LRU-managed RAM pool with last_used tracking, eviction that skips INIT_SENT entries, removed-entry tracking for merge-save safety)

Companion Radio (BaseChatMesh)

• src/helpers/BaseChatMesh.h / BaseChatMesh.cpp — Advertise AEAD, track peer capability, AEAD send for all peer message types, nonce persistence, session key negotiation (both initiator and responder roles), encryption key/nonce funnel (getEncryptionKeyFor/getEncryptionNonceFor), deferred rekey trigger via _pending_rekey_idx

Server-Side (ClientACL + examples)

• src/helpers/ClientACL.h / ClientACL.cpp — Server-side AEAD nonce tracking and persistence, session key responder (handleSessionKeyInit), paired encryption key/nonce selection (getEncryptionKey/getEncryptionNonce), flash-backed session key wrappers with merge-save, peer-index forwarding helpers
• src/helpers/CommonCLI.h / CommonCLI.cpp — Advertise AEAD for repeaters/rooms/sensors; onBeforeReboot() callback for nonce/session key flush
• examples/simple_repeater/MyMesh.h / MyMesh.cpp — AEAD + session key support, nonce persistence, session key INIT handling in onPeerDataRecv
• examples/simple_room_server/MyMesh.h / MyMesh.cpp — Same
• examples/simple_sensor/SensorMesh.h / SensorMesh.cpp — Same

Platform Support

• src/helpers/ArduinoHelpers.h — wasDirtyReset() helper (ESP32/NRF52 reset reason detection)
• examples/companion_radio/DataStore.h / DataStore.cpp — Nonce and session key file I/O, variable-length session key records, merge-save with flash-backed lookup (loadSessionKeyByPrefix)
• examples/companion_radio/MyMesh.h / MyMesh.cpp — Wire up nonce/session key persistence and reboot callback, flash-backed session key overrides (loadSessionKeyRecordFromFlash, mergeAndSaveSessionKeys)

Build Verification

• ESP32 (Heltec_v3_companion_radio_ble): builds successfully
• ESP32 (Heltec_v3_repeater): builds successfully
• ESP32 (Heltec_v3_room_server): builds successfully
• NRF52 (Xiao_nrf52_companion_radio_ble): builds successfully

Future Work

• Group messages: send AEAD-4 (all updated nodes can already decode it)
• ANON_REQ: remain ECB (no prior capability exchange possible)
• rekey <peer> CLI command for manual session key renegotiation

---

Build firmware: Build from this branch

---

Mirror of meshcore-dev#1677