[client] Post Quantum ML-KEM rosenpass alternative

RI
2h ago
+5525-165

Describe your changes

Adds an optional post-quantum key exchange that derives the WireGuard preshared key from
an X25519MLKEM768 hybrid KEM, as an alternative to Rosenpass. It gives the tunnel key
post-quantum confidentiality (harvest-now-decrypt-later protection) while riding the
existing, already-authenticated Signal offer/answer channel, with a much smaller on-wire
footprint than Rosenpass (~2.3 KB per exchange). Off by default; opt in with
NB_ENABLE_PQ_MLKEM=true.

The KEM logic is a self-contained, consumer-agnostic library (client/internal/pqkem,
no WireGuard/NetBird types); the engine wires it to signalling and the WG interface via
an adapter. Pieces:

  1. KEM (pqkem/kem.go): X25519MLKEM768 per draft-ietf-tls-ecdhe-mlkem; PSK =
    HKDF-SHA256 over ML-KEM_ss ‖ X25519_ss, bound to the transcript and the
    canonicalised peer identities so it can't be transplanted to another pair/exchange.
  2. Manager (pqkem/manager.go, convergence.go): stateful orchestrator. The
    initiator is deterministic (higher WireGuard pubkey = the ICE controller), so a single
    unidirectional exchange yields one shared PSK — no glare / split-brain.
  3. Signalling (peer/handshaker.go, signaler.go, shared/signal/proto): the KEM
    offer/answer piggyback the existing Signal offer/answer. The controller replies to a
    responder's (KEM-less) offer with its own KEM offer instead of answering, so the single
    KEM-carrying transaction is the one that establishes the tunnel and the derived PSK is
    in hand before the first WireGuard handshake.
  4. Data-path transport (pqkem_transport.go): a dedicated UDP socket on the WG
    overlay IP (default port 51833, announced over Signal only when non-default) used for
    PSK rotation.
  5. PSK application (peer/conn.go, pqkem_adapter.go): the bootstrap PSK is pulled
    at WG peer-config time; steady-state rotations are pushed via SetPresharedKey.
  6. Rotation: clocked by WireGuard rekeys and gated on recent real-data activity, so
    idle tunnels stop rotating (keeps lazy connections able to return to idle).
  7. Strict mode (NB_PQ_MLKEM_STRICT): fail-closed — a per-conn random sentinel PSK
    blocks peer traffic until the real PSK is derived. Off = permissive (tunnel forms
    classically and upgrades to PQ when ready).
  8. Coexistence: mutually exclusive with Rosenpass (ML-KEM takes precedence); a peer
    that never presents KEM material is detected as non-PQ (no offer churn); a persistent
    rekey failure re-bootstraps over Signal.

Env vars: NB_ENABLE_PQ_MLKEM (default off), NB_PQ_MLKEM_STRICT, NB_PQ_MLKEM_LOG_LEVEL.

Issue ticket number and link

No public ticket — internal post-quantum project. New self-contained library under
client/internal/pqkem plus engine/signalling wiring; opt-in and off by default.

Stack

Checklist

  • Is it a bug fix
  • Is a typo/documentation fix
  • Is a feature enhancement
  • It is a refactor
  • Created tests that fail without the change (if possible)

By submitting this pull request, you confirm that you have read and agree to the terms of the Contributor License Agreement.

Documentation

Select exactly one:

  • I added/updated documentation for this change
  • Documentation is not needed for this change (explain why)

Experimental, off by default and gated behind NB_ENABLE_PQ_MLKEM; the env vars are not
yet a stable, documented public configuration surface. Public docs will follow once the
feature graduates from opt-in.

Docs PR URL (required if "docs added" is checked)

Paste the PR link from https://github.com/netbirdio/docs here:

N/A

Summary by CodeRabbit

  • New Features
    • Added optional post-quantum protection using ML-KEM alongside existing key exchange.
    • Added configurable enabled and strict modes through environment settings.
    • Added secure peer handshaking, key rotation, recovery, and protection status reporting.
    • Added signaling and data-path support for post-quantum handshake messages.
  • Bug Fixes
    • Improved recovery from failed handshakes and rekey attempts while preserving established connections.
    • Preserved newer security keys during endpoint updates.
  • Reliability
    • Added validation for malformed or tampered exchange messages.