diff --git a/client/internal/conn_mgr.go b/client/internal/conn_mgr.go index f0cc2610216..932cefe95ef 100644 --- a/client/internal/conn_mgr.go +++ b/client/internal/conn_mgr.go @@ -163,13 +163,7 @@ func (e *ConnMgr) SetExcludeList(ctx context.Context, peerIDs map[string]bool) { continue } - lazyPeerCfg := lazyconn.PeerConfig{ - PublicKey: peerID, - AllowedIPs: peerConn.WgConfig().AllowedIps, - PeerConnID: peerConn.ConnID(), - Log: peerConn.Log, - } - excludedPeers = append(excludedPeers, lazyPeerCfg) + excludedPeers = append(excludedPeers, newLazyPeerConfig(peerID, peerConn)) } added := e.lazyConnMgr.ExcludePeer(excludedPeers) @@ -188,6 +182,17 @@ func (e *ConnMgr) SetExcludeList(ctx context.Context, peerIDs map[string]bool) { } } +// newLazyPeerConfig describes a peer connection to the lazy connection manager. +func newLazyPeerConfig(peerKey string, conn *peer.Conn) lazyconn.PeerConfig { + return lazyconn.PeerConfig{ + PublicKey: peerKey, + AllowedIPs: conn.WgConfig().AllowedIps, + PeerConnID: conn.ConnID(), + Log: conn.Log, + PresharedKey: conn.IdlePresharedKey, + } +} + // AddPeerConn registers a peer connection. permanent requests an always-active connection // (the peer belongs to the exclude set: a forwarder, or a peer that is not lazy by policy). // Non-permanent peers are handed to the lazy manager. The subsequent SetExcludeList call @@ -212,13 +217,7 @@ func (e *ConnMgr) AddPeerConn(ctx context.Context, peerKey string, conn *peer.Co return } - lazyPeerCfg := lazyconn.PeerConfig{ - PublicKey: peerKey, - AllowedIPs: conn.WgConfig().AllowedIps, - PeerConnID: conn.ConnID(), - Log: conn.Log, - } - excluded, err := e.lazyConnMgr.AddPeer(lazyPeerCfg) + excluded, err := e.lazyConnMgr.AddPeer(newLazyPeerConfig(peerKey, conn)) if err != nil { conn.Log.Errorf("failed to add peer to lazyconn manager: %v", err) if err := conn.Open(ctx); err != nil { diff --git a/client/internal/debug/debug.go b/client/internal/debug/debug.go index 64d1443cd5c..c3b32e05d0d 100644 --- a/client/internal/debug/debug.go +++ b/client/internal/debug/debug.go @@ -27,6 +27,7 @@ import ( "github.com/netbirdio/netbird/client/anonymize" "github.com/netbirdio/netbird/client/configs" "github.com/netbirdio/netbird/client/internal/peer" + "github.com/netbirdio/netbird/client/internal/pqkem" "github.com/netbirdio/netbird/client/internal/profilemanager" "github.com/netbirdio/netbird/client/internal/updater/installer" nbstatus "github.com/netbirdio/netbird/client/status" @@ -961,6 +962,9 @@ func (g *BundleGenerator) addCommonConfigFields(configContent *strings.Builder) configContent.WriteString(fmt.Sprintf("DisableIPv6Discovery: %v\n", g.internalConfig.DisableIPv6Discovery)) configContent.WriteString(fmt.Sprintf("RosenpassEnabled: %v\n", g.internalConfig.RosenpassEnabled)) configContent.WriteString(fmt.Sprintf("RosenpassPermissive: %v\n", g.internalConfig.RosenpassPermissive)) + // ML-KEM (Rosenpass alternative) is env-driven, not part of the config, so read it here. + configContent.WriteString(fmt.Sprintf("MLKEMEnabled: %v\n", pqkem.Enabled())) + configContent.WriteString(fmt.Sprintf("MLKEMStrict: %v\n", pqkem.Strict())) if g.internalConfig.ServerSSHAllowed != nil { configContent.WriteString(fmt.Sprintf("ServerSSHAllowed: %v\n", *g.internalConfig.ServerSSHAllowed)) } diff --git a/client/internal/engine.go b/client/internal/engine.go index 4de0209b0c0..b53b7e9c29c 100644 --- a/client/internal/engine.go +++ b/client/internal/engine.go @@ -4,6 +4,7 @@ import ( "context" "errors" "fmt" + "math" "math/rand" "net" "net/netip" @@ -52,6 +53,7 @@ import ( icemaker "github.com/netbirdio/netbird/client/internal/peer/ice" "github.com/netbirdio/netbird/client/internal/peerstore" "github.com/netbirdio/netbird/client/internal/portforward" + "github.com/netbirdio/netbird/client/internal/pqkem" "github.com/netbirdio/netbird/client/internal/profilemanager" "github.com/netbirdio/netbird/client/internal/relay" "github.com/netbirdio/netbird/client/internal/rosenpass" @@ -214,6 +216,13 @@ type Engine struct { // rpManager is a Rosenpass manager rpManager *rosenpass.Manager + // pqkemManager runs the ML-KEM post-quantum PSK exchange (gated by NB_ENABLE_PQ_MLKEM). + // It owns the data-path transport and peer endpoint routing. + pqkemManager *pqkem.Manager + // pqPSKReapplier restores the latest PQ PSK after a conn configures WireGuard with a + // stale one. Set together with pqkemManager. + pqPSKReapplier *pqPSKReapplier + // syncMsgMux is used to guarantee sequential Management Service message processing syncMsgMux *sync.Mutex @@ -555,6 +564,83 @@ func waitWithContext(ctx context.Context, wg *sync.WaitGroup) error { } } +// startRosenpassManager brings up Rosenpass when it is enabled and ML-KEM (which takes +// precedence) is not, since the two post-quantum mechanisms are mutually exclusive. +func (e *Engine) startRosenpassManager(publicKey wgtypes.Key) error { + if e.config.RosenpassEnabled && pqkem.Enabled() { + log.Warnf("rosenpass and ML-KEM post-quantum are mutually exclusive; ML-KEM is enabled, so rosenpass is disabled") + } + if !e.config.RosenpassEnabled || pqkem.Enabled() { + return nil + } + + log.Infof("rosenpass is enabled") + if e.config.RosenpassPermissive { + log.Infof("running rosenpass in permissive mode") + } else { + log.Infof("running rosenpass in strict mode") + } + + var err error + e.rpManager, err = rosenpass.NewManager(e.config.PreSharedKey, e.config.WgIfaceName, publicKey) + if err != nil { + return fmt.Errorf("create rosenpass manager: %w", err) + } + if err := e.rpManager.Run(); err != nil { + return fmt.Errorf("run rosenpass manager: %w", err) + } + return nil +} + +// startPQKEMManager brings up the ML-KEM post-quantum PSK exchange when NB_ENABLE_PQ_MLKEM +// is set. It binds the dedicated UDP transport on the WG overlay IP, so the interface must +// already be up. In strict mode a bind failure is fatal (fail closed); in opportunistic +// mode it is logged and the exchange stays disabled. +func (e *Engine) startPQKEMManager(publicKey wgtypes.Key) error { + if !pqkem.Enabled() { + return nil + } + tr, err := newPQTransport(e.config.WgAddr.IP, e.wgInterface.GetNet()) + if err != nil { + if pqkem.Strict() { + return fmt.Errorf("pqkem: strict mode enabled but transport bind failed: %w", err) + } + log.Errorf("pqkem: transport bind failed, exchange disabled: %v", err) + return nil + } + applied := newAppliedGenerations() + cbHandler := pqCallbackHandler{ + wg: e.wgInterface, + status: e.statusRecorder, + applied: applied, + // On a persistent rekey failure, re-bootstrap the KEM over Signal: a fresh + // signalling offer starts a new exchange that overwrites the stalled PSK on both + // sides, recovering from a data-path desync. + recoverPQKeyOverSignal: func(remoteKey string) { + if conn, ok := e.peerStore.PeerConn(remoteKey); ok { + conn.RecoverPQKeyOverSignal() + } + }, + } + var opts []pqkem.Option + if e.config.PreSharedKey != nil { + // The configured key promises that only peers holding it can communicate. The PQ + // PSK replaces it in WireGuard, so it has to carry that guarantee itself. + opts = append(opts, pqkem.WithPresharedSecret(e.config.PreSharedKey[:])) + } + e.pqkemManager = pqkem.NewManager(pqkem.LocalID(publicKey.String()), cbHandler, pqkem.NewLogger(), opts...) + // Shares the apply lock with the rotation push, so a reapply and a push are ordered. + e.pqPSKReapplier = &pqPSKReapplier{psks: e.pqkemManager, wg: e.wgInterface, applied: applied} + e.pqkemManager.Start(tr) + // Here rather than in initFirewall: the firewall comes up before the interface, and the + // transport can only bind once the interface is up. + if e.firewall != nil { + e.allowOverlayUDPPort("ML-KEM", uint16(e.pqkemManager.LocalPort())) + } + log.Infof("pqkem: enabled (udp port %d on overlay %s)", e.pqkemManager.LocalPort(), e.config.WgAddr.IP) + return nil +} + // Start creates a new WireGuard tunnel interface and listens to events from Signal and Management services // Connections to remote peers are not established here. // However, they will be established once an event with a list of peers to connect to will be received from Management Service @@ -604,20 +690,8 @@ func (e *Engine) Start(netbirdConfig *mgmProto.NetbirdConfig, mgmtURL *url.URL) publicKey := e.config.WgPrivateKey.PublicKey() e.flowManager = netflow.NewManager(e.wgInterface, publicKey[:], e.statusRecorder) - if e.config.RosenpassEnabled { - log.Infof("rosenpass is enabled") - if e.config.RosenpassPermissive { - log.Infof("running rosenpass in permissive mode") - } else { - log.Infof("running rosenpass in strict mode") - } - e.rpManager, err = rosenpass.NewManager(e.config.PreSharedKey, e.config.WgIfaceName, publicKey) - if err != nil { - return fmt.Errorf("create rosenpass manager: %w", err) - } - if err := e.rpManager.Run(); err != nil { - return fmt.Errorf("run rosenpass manager: %w", err) - } + if err := e.startRosenpassManager(publicKey); err != nil { + return err } e.stateManager.Start() @@ -696,6 +770,10 @@ func (e *Engine) Start(netbirdConfig *mgmProto.NetbirdConfig, mgmtURL *url.URL) e.rpManager.SetInterface(e.wgInterface) } + if err := e.startPQKEMManager(publicKey); err != nil { + return err + } + // if inbound conns are blocked there is no need to create the ACL manager if e.firewall != nil && !e.config.BlockInbound { e.acl = acl.NewDefaultManager(e.firewall) @@ -795,14 +873,19 @@ func (e *Engine) initFirewall() error { e.blockLanAccess() } - if e.rpManager == nil || !e.config.RosenpassEnabled { - return nil + if e.rpManager != nil && e.config.RosenpassEnabled { + e.allowOverlayUDPPort("rosenpass", uint16(e.rpManager.GetAddress().Port)) } - rosenpassPort := e.rpManager.GetAddress().Port - port := firewallManager.Port{Values: []uint16{uint16(rosenpassPort)}} + return nil +} + +// allowOverlayUDPPort accepts inbound UDP from any overlay peer on a port a local +// service listens on, so the peer ACLs do not drop it. Failure is logged, not fatal. +func (e *Engine) allowOverlayUDPPort(service string, portValue uint16) { + port := firewallManager.Port{Values: []uint16{portValue}} - // IPv4-only: rosenpass peers connect via AllowedIps[0] which is always v4. + // IPv4-only: the peers reach the service via AllowedIps[0], which is always v4. if _, err := e.firewall.AddFilterRule( nil, []netip.Prefix{netip.PrefixFrom(netip.IPv4Unspecified(), 0)}, @@ -812,13 +895,11 @@ func (e *Engine) initFirewall() error { &port, firewallManager.ActionAccept, ); err != nil { - log.Errorf("failed to allow rosenpass interface traffic: %v", err) - return nil + log.Errorf("failed to allow %s interface traffic: %v", service, err) + return } - log.Infof("rosenpass interface traffic allowed on port %d", rosenpassPort) - - return nil + log.Infof("%s interface traffic allowed on port %d", service, portValue) } func (e *Engine) blockLanAccess() { @@ -946,6 +1027,10 @@ func (e *Engine) removePeer(peerKey string) error { e.connMgr.RemovePeerConn(peerKey) + if e.pqkemManager != nil { + e.pqkemManager.RemovePeer(pqkem.RemoteID(peerKey)) + } + err := e.statusRecorder.RemovePeer(peerKey) if err != nil { log.Warnf("received error when removing peer %s from status recorder: %v", peerKey, err) @@ -2022,6 +2107,10 @@ func (e *Engine) createPeerConn(pubKey string, allowedIPs []netip.Prefix, agentV ICEConfig: e.createICEConfig(), NetMgr: e.netMgr, } + if e.pqkemManager != nil { + config.PQ = pqHandshaker{mgr: e.pqkemManager, reapplier: e.pqPSKReapplier, status: e.statusRecorder} + config.PQStrict = pqkem.Strict() + } serviceDependencies := peer.ServiceDependencies{ StatusRecorder: e.statusRecorder, @@ -2209,6 +2298,10 @@ func (e *Engine) close() { _ = e.rpManager.Close() } + if e.pqkemManager != nil { + e.pqkemManager.Stop() + } + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() if err := e.portForwardManager.GracefullyStop(ctx); err != nil { @@ -2956,6 +3049,13 @@ func convertToOfferAnswer(msg *sProto.Message) (*peer.OfferAnswer, error) { relayIP := decodeRelayIP(msg.GetBody().GetRelayServerIP()) + // Ports are uint16 internally; the proto widens them to uint32, so validate the + // range before narrowing (a value that does not fit is a malformed message). + mlkemPort := msg.GetBody().GetMlkemPort() + if mlkemPort > math.MaxUint16 { + return nil, fmt.Errorf("invalid ML-KEM port %d in signalling message", mlkemPort) + } + offerAnswer := peer.OfferAnswer{ IceCredentials: peer.IceCredentials{ UFrag: remoteCred.UFrag, @@ -2965,6 +3065,8 @@ func convertToOfferAnswer(msg *sProto.Message) (*peer.OfferAnswer, error) { Version: msg.GetBody().GetNetBirdVersion(), RosenpassPubKey: rosenpassPubKey, RosenpassAddr: rosenpassAddr, + MlkemPayload: msg.GetBody().GetMlkemPayload(), + MlkemPort: uint16(mlkemPort), RelaySrvAddress: msg.GetBody().GetRelayServerAddress(), RelaySrvIP: relayIP, SessionID: sessionID, diff --git a/client/internal/engine_pqkem_firewall_test.go b/client/internal/engine_pqkem_firewall_test.go new file mode 100644 index 00000000000..03b20793bf6 --- /dev/null +++ b/client/internal/engine_pqkem_firewall_test.go @@ -0,0 +1,93 @@ +package internal + +import ( + "net" + "net/netip" + "testing" + + "github.com/google/gopacket" + "github.com/google/gopacket/layers" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "golang.zx2c4.com/wireguard/wgctrl/wgtypes" + + firewallManager "github.com/netbirdio/netbird/client/firewall/manager" + "github.com/netbirdio/netbird/client/firewall/uspfilter" + "github.com/netbirdio/netbird/client/iface" + "github.com/netbirdio/netbird/client/iface/device" + "github.com/netbirdio/netbird/client/iface/wgaddr" + "github.com/netbirdio/netbird/client/iface/wgbackend" + "github.com/netbirdio/netbird/client/internal/netflow" + "github.com/netbirdio/netbird/client/internal/pqkem" + "github.com/netbirdio/netbird/client/internal/routemanager" +) + +// pqFirewallIface is the minimal overlay interface the userspace firewall attaches to. +type pqFirewallIface struct{ addr wgaddr.Address } + +func (i pqFirewallIface) Name() string { return "wt-pq-test" } +func (i pqFirewallIface) Address() wgaddr.Address { return i.addr } +func (i pqFirewallIface) SetFilter(device.PacketFilter) error { return nil } +func (i pqFirewallIface) GetWGDevice() *wgbackend.Device { return nil } + +// firewallOnlyRouteManager accepts the firewall initFirewall hands to the route manager. +type firewallOnlyRouteManager struct{ *routemanager.MockManager } + +func (firewallOnlyRouteManager) SetFirewall(firewallManager.Manager) error { return nil } + +// pqInboundUDP builds an overlay UDP packet from a peer to the local PQ data-path port. +func pqInboundUDP(t *testing.T, src, dst netip.Addr, port uint16) []byte { + t.Helper() + ip := &layers.IPv4{Version: 4, TTL: 64, Protocol: layers.IPProtocolUDP, SrcIP: net.IP(src.AsSlice()), DstIP: net.IP(dst.AsSlice())} + udp := &layers.UDP{SrcPort: layers.UDPPort(port), DstPort: layers.UDPPort(port)} + require.NoError(t, udp.SetNetworkLayerForChecksum(ip)) + buf := gopacket.NewSerializeBuffer() + opts := gopacket.SerializeOptions{FixLengths: true, ComputeChecksums: true} + require.NoError(t, gopacket.SerializeLayers(buf, opts, ip, udp, gopacket.Payload("pq-offer"))) + return buf.Bytes() +} + +// pqFirewallWGIface is an overlay interface without netstack, so the PQ transport binds a +// plain OS socket. startPQKEMManager calls nothing else on it. +type pqFirewallWGIface struct{ WGIface } + +func (pqFirewallWGIface) GetNet() *wgbackend.NetstackNet { return nil } + +// TestEngine_PQKEMStartAllowsItsPort: the PQ transport listens on the overlay, so with peer +// ACLs that do not open its port a rotation offer from a peer is dropped and rotation times +// out. The engine sets the firewall up first and starts the transport later, once the +// interface is up; the port must still end up accepted. +func TestEngine_PQKEMStartAllowsItsPort(t *testing.T) { + t.Setenv(pqkem.EnvEnabled, "true") + local := netip.MustParseAddr("100.64.0.1") + remote := netip.MustParseAddr("100.64.0.2") + fw, err := uspfilter.Create(uspfilter.Config{ + IFace: pqFirewallIface{addr: wgaddr.Address{IP: local, Network: netip.MustParsePrefix("100.64.0.0/10")}}, + FlowLogger: netflow.NewManager(nil, []byte{}, nil).GetLogger(), + MTU: iface.DefaultMTU, + }) + require.NoError(t, err) + t.Cleanup(func() { require.NoError(t, fw.Close(nil)) }) + require.NoError(t, fw.UpdateLocalIPs()) + + e := &Engine{ + // The transport binds on loopback: the filter only looks at the packet's port. + config: &EngineConfig{WgAddr: wgaddr.Address{IP: netip.MustParseAddr("127.0.0.1")}}, + firewall: fw, + routeManager: firewallOnlyRouteManager{&routemanager.MockManager{}}, + wgInterface: pqFirewallWGIface{}, + } + // Engine.Start order: firewall first, PQ transport after the interface is up. + require.NoError(t, e.initFirewall()) + key, err := wgtypes.GeneratePrivateKey() + require.NoError(t, err) + require.NoError(t, e.startPQKEMManager(key.PublicKey())) + require.NotNil(t, e.pqkemManager, "precondition: the PQ manager started") + t.Cleanup(e.pqkemManager.Stop) + + packet := pqInboundUDP(t, remote, local, uint16(e.pqkemManager.LocalPort())) + assert.False(t, fw.FilterInbound(packet, len(packet)), "a peer's PQ data-path message must pass the firewall") + + other := pqInboundUDP(t, remote, local, uint16(e.pqkemManager.LocalPort())+1) + assert.True(t, fw.FilterInbound(other, len(other)), "only the PQ port may be opened") +} diff --git a/client/internal/lazyconn/activity/listener_bind.go b/client/internal/lazyconn/activity/listener_bind.go index 72a0cfc7675..82ff16190d6 100644 --- a/client/internal/lazyconn/activity/listener_bind.go +++ b/client/internal/lazyconn/activity/listener_bind.go @@ -106,7 +106,7 @@ func (d *BindListener) setupLazyConn() error { IP: d.fakeIP.AsSlice(), Port: lazyBindPort, } - return d.wgIface.UpdatePeer(d.peerCfg.PublicKey, d.peerCfg.AllowedIPs, 0, endpoint, nil) + return d.wgIface.UpdatePeer(d.peerCfg.PublicKey, d.peerCfg.AllowedIPs, 0, endpoint, d.peerCfg.IdlePresharedKey()) } // ReadPackets blocks until activity is detected on the LazyConn or the listener is closed. diff --git a/client/internal/lazyconn/activity/listener_psk_test.go b/client/internal/lazyconn/activity/listener_psk_test.go new file mode 100644 index 00000000000..1cf3643cb33 --- /dev/null +++ b/client/internal/lazyconn/activity/listener_psk_test.go @@ -0,0 +1,106 @@ +package activity + +import ( + "net" + "net/netip" + "sync" + "testing" + "time" + + log "github.com/sirupsen/logrus" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "golang.zx2c4.com/wireguard/wgctrl/wgtypes" + + "github.com/netbirdio/netbird/client/internal/lazyconn" +) + +// pskRecordingIface records the preshared key each idle peer is installed with. +type pskRecordingIface struct { + MocWGIface + mu sync.Mutex + psks []*wgtypes.Key +} + +func (r *pskRecordingIface) UpdatePeer(_ string, _ []netip.Prefix, _ time.Duration, _ *net.UDPAddr, psk *wgtypes.Key) error { + r.mu.Lock() + defer r.mu.Unlock() + r.psks = append(r.psks, psk) + return nil +} + +func (r *pskRecordingIface) installed() []*wgtypes.Key { + r.mu.Lock() + defer r.mu.Unlock() + return append([]*wgtypes.Key(nil), r.psks...) +} + +type idleListener interface { + ReadPackets() + Close() +} + +func closeListener(t *testing.T, l idleListener) { + t.Helper() + done := make(chan struct{}) + go func() { + l.ReadPackets() + close(done) + }() + l.Close() + select { + case <-done: + case <-time.After(2 * time.Second): + t.Fatal("timeout waiting for ReadPackets to exit after Close") + } +} + +// TestListeners_InstallIdlePeerWithItsPresharedKey covers ML-KEM strict mode with lazy +// connections. An idle peer is installed in WireGuard so a handshake the remote initiates +// directly is accepted; installed without a key, a fresh peer accepted a classical session +// before any post-quantum exchange, breaking strict mode's promise. Both listeners must +// install the key the peer config provides, and leave it unchanged when there is none. +func TestListeners_InstallIdlePeerWithItsPresharedKey(t *testing.T) { + sentinel := wgtypes.Key{1, 2, 3} + newCfg := func(psk func() *wgtypes.Key) lazyconn.PeerConfig { + peer := &MocPeer{PeerID: "testPeer1"} + return lazyconn.PeerConfig{ + PublicKey: peer.PeerID, + PeerConnID: peer.ConnID(), + AllowedIPs: []netip.Prefix{netip.MustParsePrefix("100.64.0.2/32")}, + Log: log.WithField("peer", "testPeer1"), + PresharedKey: psk, + } + } + listeners := map[string]func(WgInterface, lazyconn.PeerConfig) (idleListener, error){ + "udp": func(iface WgInterface, cfg lazyconn.PeerConfig) (idleListener, error) { + return NewUDPListener(iface, cfg) + }, + "bind": func(iface WgInterface, cfg lazyconn.PeerConfig) (idleListener, error) { + return NewBindListener(iface, newMockEndpointManager(), cfg) + }, + } + for name, newListener := range listeners { + t.Run(name+"/with key", func(t *testing.T) { + iface := &pskRecordingIface{} + l, err := newListener(iface, newCfg(func() *wgtypes.Key { return &sentinel })) + require.NoError(t, err) + closeListener(t, l) + + installed := iface.installed() + require.Len(t, installed, 1, "the idle peer must be installed once") + require.NotNil(t, installed[0], "the idle peer must be installed with the provided key") + assert.Equal(t, sentinel, *installed[0], "the idle peer must carry the provided key") + }) + t.Run(name+"/without key", func(t *testing.T) { + iface := &pskRecordingIface{} + l, err := newListener(iface, newCfg(nil)) + require.NoError(t, err) + closeListener(t, l) + + installed := iface.installed() + require.Len(t, installed, 1, "the idle peer must be installed once") + assert.Nil(t, installed[0], "without a key the idle peer's key must be left unchanged") + }) + } +} diff --git a/client/internal/lazyconn/activity/listener_udp.go b/client/internal/lazyconn/activity/listener_udp.go index 4b7e0ddf76b..ba7e154075a 100644 --- a/client/internal/lazyconn/activity/listener_udp.go +++ b/client/internal/lazyconn/activity/listener_udp.go @@ -101,7 +101,7 @@ func (d *UDPListener) Close() { func (d *UDPListener) createEndpoint() error { d.peerCfg.Log.Debugf("creating lazy endpoint: %s", d.endpoint.String()) - return d.wgIface.UpdatePeer(d.peerCfg.PublicKey, d.peerCfg.AllowedIPs, 0, d.endpoint, nil) + return d.wgIface.UpdatePeer(d.peerCfg.PublicKey, d.peerCfg.AllowedIPs, 0, d.endpoint, d.peerCfg.IdlePresharedKey()) } func (d *UDPListener) newConn() (*net.UDPConn, error) { diff --git a/client/internal/lazyconn/peercfg.go b/client/internal/lazyconn/peercfg.go index 987d06a3e1a..7847b19e0d3 100644 --- a/client/internal/lazyconn/peercfg.go +++ b/client/internal/lazyconn/peercfg.go @@ -4,6 +4,7 @@ import ( "net/netip" log "github.com/sirupsen/logrus" + "golang.zx2c4.com/wireguard/wgctrl/wgtypes" "github.com/netbirdio/netbird/client/internal/peer/id" ) @@ -13,4 +14,17 @@ type PeerConfig struct { AllowedIPs []netip.Prefix PeerConnID id.ConnID Log *log.Entry + // PresharedKey returns the key to install with the idle WireGuard peer, or nil to + // leave the peer's key as it is. It is read when the peer is installed, not when the + // config is built, so it reflects keys derived after the peer joined. A nil func + // leaves the key unchanged too. + PresharedKey func() *wgtypes.Key +} + +// IdlePresharedKey is the key to install with the idle WireGuard peer (nil: unchanged). +func (c PeerConfig) IdlePresharedKey() *wgtypes.Key { + if c.PresharedKey == nil { + return nil + } + return c.PresharedKey() } diff --git a/client/internal/peer/conn.go b/client/internal/peer/conn.go index b3d3a95ae93..665e6736186 100644 --- a/client/internal/peer/conn.go +++ b/client/internal/peer/conn.go @@ -3,6 +3,7 @@ package peer import ( "context" "fmt" + "math" "net" "net/netip" "runtime" @@ -27,6 +28,7 @@ import ( "github.com/netbirdio/netbird/client/internal/rosenpass" "github.com/netbirdio/netbird/client/internal/stdnet" "github.com/netbirdio/netbird/client/netevents" + "github.com/netbirdio/netbird/monotime" "github.com/netbirdio/netbird/route" relayClient "github.com/netbirdio/netbird/shared/relay/client" ) @@ -75,6 +77,46 @@ type RosenpassConfig struct { PermissiveMode bool } +// PQHandshaker attaches post-quantum ML-KEM material to signalling offers/answers and +// feeds received material back. It is implemented by the engine over the pqkem +// manager and is nil when the PQ exchange is disabled. remoteKey is the peer's +// WireGuard public key. +type PQHandshaker interface { + // OfferPayload returns the KEM offer to embed in an outgoing offer (nil if this + // peer is not the KEM initiator) and the local PQ data-path port to announce. + OfferPayload(remoteKey string) (payload []byte, port uint16) + // ShouldSendBootstrapOffer reports whether, as the controller, we should reply to a + // received responder offer with our own KEM offer (true unless an exchange of ours is + // already in flight, so we kick the KEM once and ignore further offers meanwhile). + ShouldSendBootstrapOffer(remoteKey string) bool + // SignalOfferInFlight reports whether, as the controller, our KEM offer over + // signalling is still waiting for its answer, so a crossing responder offer is a glare. + SignalOfferInFlight(remoteKey string) bool + // AnswerPayload processes a received KEM offer (nil if absent) and returns the KEM + // answer to embed in the outgoing answer (nil if none) and the local PQ port. + AnswerPayload(remoteKey string, recvOffer []byte) (payload []byte, port uint16) + // OnAnswer feeds a received KEM answer (nil if absent). + OnAnswer(remoteKey string, recvAnswer []byte) + // PSK returns the peer's latest derived post-quantum PSK to program at WG + // peer-config time (the pull path). ok is false until one has been derived. + PSK(remoteKey string) (wgtypes.Key, bool) + // ReapplyPSK runs after the conn configured WireGuard with programmed, a PSK it read + // beforehand. A rotation committed in between was overwritten by that stale value, so + // the latest PSK is programmed again when it differs. + ReapplyPSK(remoteKey string, programmed *wgtypes.Key) + // SetRemoteAddr registers the peer's data-path endpoint learned from signalling: + // its WG overlay IP with the announced pq UDP port (port 0 means the peer omitted + // it and is on the default port). + SetRemoteAddr(remoteKey string, addr netip.AddrPort) + // OnDataPathRekeyed signals a fresh WireGuard handshake for the peer; it clocks the + // next chained PSK rotation pushed over the data path. sinceActivity is how long + // ago the peer last exchanged real user data, so the rotation can be skipped for + // idle tunnels. + OnDataPathRekeyed(remoteKey string, sinceActivity time.Duration) + // OnDataPathDown signals the peer's tunnel went down. + OnDataPathDown(remoteKey string) +} + // ConnConfig is a peer Connection configuration type ConnConfig struct { // Key is a public key of a remote peer @@ -92,6 +134,12 @@ type ConnConfig struct { RosenpassConfig RosenpassConfig + // PQ carries post-quantum ML-KEM material on offers/answers; nil when disabled. + PQ PQHandshaker + // PQStrict fails closed: block peer traffic until the ML-KEM PSK is established, + // instead of letting the tunnel come up classically and upgrading to PQ later. + PQStrict bool + // ICEConfig ICE protocol configuration ICEConfig icemaker.Config @@ -155,6 +203,11 @@ type Conn struct { // pendingFirstPacket is the lazyconn-captured handshake init, replayed once the real // transport is up. pendingFirstPacket []byte + + // pqStrictSentinelKey is a per-conn random sentinel PSK used in PQ strict mode to + // fail closed: it is programmed until the real ML-KEM PSK is derived, so no session + // can form on a non-PQ key. Per-conn random so two strict peers never match by chance. + pqStrictSentinelKey *wgtypes.Key } // injectPendingFirstPacket replays the captured handshake through the proxy if present, else @@ -212,6 +265,16 @@ func NewConn(config ConnConfig, services ServiceDependencies) (*Conn, error) { metricsRecorder: services.MetricsRecorder, } + if config.PQ != nil && config.PQStrict { + // The sentinel is what makes strict mode fail closed; if we cannot generate it we + // must not fall back to a usable key, so fail creating the conn instead. + k, err := wgtypes.GenerateKey() + if err != nil { + return nil, fmt.Errorf("generate pqkem strict-mode sentinel key: %w", err) + } + conn.pqStrictSentinelKey = &k + } + return conn, nil } @@ -413,6 +476,9 @@ func (conn *Conn) ConnID() id.ConnID { // configureConnection starts proxying traffic from/to local Wireguard and sets connection status to StatusConnected func (conn *Conn) onICEConnectionIsReady(priority conntype.ConnPriority, iceConnInfo ICEConnInfo) { + // Read the PQ PSK before conn.mu to keep the lock order conn.mu -> manager. + pqPSK, pqOK := conn.pqPSK() + conn.mu.Lock() defer conn.mu.Unlock() @@ -430,7 +496,7 @@ func (conn *Conn) onICEConnectionIsReady(priority conntype.ConnPriority, iceConn if conn.currentConnPriority > priority { conn.Log.Infof("current connection priority (%s) is higher than the new one (%s), do not upgrade connection", conn.currentConnPriority, priority) conn.statusICE.SetConnected() - conn.updateIceState(iceConnInfo, time.Now()) + conn.updateIceState(iceConnInfo, pqOK, time.Now()) return } @@ -473,12 +539,13 @@ func (conn *Conn) onICEConnectionIsReady(priority conntype.ConnPriority, iceConn updateTime := time.Now() conn.enableWgWatcherIfNeeded(updateTime) - presharedKey := conn.presharedKey(iceConnInfo.RosenpassPubKey) + presharedKey := conn.presharedKey(iceConnInfo.RosenpassPubKey, pqPSK) if err = conn.endpointUpdater.ConfigureWGEndpoint(ep, presharedKey); err != nil { conn.handleConfigurationFailure(err, wgProxy) return } wgConfigWorkaround() + conn.reapplyPQPSK(presharedKey) if conn.wgProxyRelay != nil { conn.Log.Debugf("redirect packets from relayed conn to WireGuard") @@ -489,11 +556,14 @@ func (conn *Conn) onICEConnectionIsReady(priority conntype.ConnPriority, iceConn conn.currentConnPriority = priority conn.statusICE.SetConnected() - conn.updateIceState(iceConnInfo, updateTime) + conn.updateIceState(iceConnInfo, pqOK, updateTime) conn.doOnConnected(iceConnInfo.RosenpassPubKey, iceConnInfo.RosenpassAddr, updateTime) } func (conn *Conn) onICEStateDisconnected(sessionChanged bool) { + // Read the PQ PSK before conn.mu to keep the lock order conn.mu -> manager. + pqPSK, _ := conn.pqPSK() + conn.mu.Lock() defer conn.mu.Unlock() @@ -520,9 +590,11 @@ func (conn *Conn) onICEStateDisconnected(sessionChanged bool) { // todo consider to move after the ConfigureWGEndpoint conn.wgProxyRelay.Work() - presharedKey := conn.presharedKey(conn.rosenpassRemoteKey) + presharedKey := conn.presharedKey(conn.rosenpassRemoteKey, pqPSK) if err := conn.endpointUpdater.SwitchWGEndpoint(conn.wgProxyRelay.EndpointAddr(), presharedKey); err != nil { conn.Log.Errorf("failed to switch to relay conn: %v", err) + } else { + conn.reapplyPQPSK(presharedKey) } conn.currentConnPriority = conntype.Relay @@ -558,6 +630,9 @@ func (conn *Conn) onICEStateDisconnected(sessionChanged bool) { } func (conn *Conn) onRelayConnectionIsReady(rci RelayConnInfo) { + // Read the PQ PSK before conn.mu to keep the lock order conn.mu -> manager. + pqPSK, pqOK := conn.pqPSK() + conn.mu.Lock() defer conn.mu.Unlock() @@ -588,7 +663,7 @@ func (conn *Conn) onRelayConnectionIsReady(rci RelayConnInfo) { conn.Log.Debugf("do not switch to relay because current priority is: %s", conn.currentConnPriority.String()) conn.setRelayedProxy(wgProxy, rci.relayedConn) conn.statusRelay.SetConnected() - conn.updateRelayStatus(rci.relayedConn.RemoteAddr().String(), rci.rosenpassPubKey, time.Now()) + conn.updateRelayStatus(rci.relayedConn.RemoteAddr().String(), rci.rosenpassPubKey, pqOK, time.Now()) return } @@ -599,7 +674,8 @@ func (conn *Conn) onRelayConnectionIsReady(rci RelayConnInfo) { } updateTime := time.Now() conn.enableWgWatcherIfNeeded(updateTime) - if err := conn.endpointUpdater.ConfigureWGEndpoint(wgProxy.EndpointAddr(), conn.presharedKey(rci.rosenpassPubKey)); err != nil { + presharedKey := conn.presharedKey(rci.rosenpassPubKey, pqPSK) + if err := conn.endpointUpdater.ConfigureWGEndpoint(wgProxy.EndpointAddr(), presharedKey); err != nil { if err := wgProxy.CloseConn(); err != nil { conn.Log.Warnf("Failed to close relay connection: %v", err) } @@ -611,6 +687,7 @@ func (conn *Conn) onRelayConnectionIsReady(rci RelayConnInfo) { } wgConfigWorkaround() + conn.reapplyPQPSK(presharedKey) conn.injectPendingFirstPacket(wgProxy, nil) @@ -618,7 +695,7 @@ func (conn *Conn) onRelayConnectionIsReady(rci RelayConnInfo) { conn.currentConnPriority = conntype.Relay conn.statusRelay.SetConnected() conn.setRelayedProxy(wgProxy, rci.relayedConn) - conn.updateRelayStatus(rci.relayedConn.RemoteAddr().String(), rci.rosenpassPubKey, updateTime) + conn.updateRelayStatus(rci.relayedConn.RemoteAddr().String(), rci.rosenpassPubKey, pqOK, updateTime) conn.Log.Infof("start to communicate with peer via relay") conn.doOnConnected(rci.rosenpassPubKey, rci.rosenpassAddr, updateTime) } @@ -692,12 +769,36 @@ func (conn *Conn) onGuardEvent() { } } +// RecoverPQKeyOverSignal re-runs the post-quantum bootstrap over Signal after the ML-KEM +// exchange failed (the initial exchange, or repeated rotation failures): a fresh +// signalling offer starts a new exchange that overwrites the stalled PSK on both sides. +// It is not part of normal key rotation, which runs over the data path. No-op if the +// connection is not open yet, or if the peer is not connected: then the reconnect guard +// already retries it with backoff, and each of its offers starts a fresh exchange. +func (conn *Conn) RecoverPQKeyOverSignal() { + conn.mu.Lock() + h := conn.handshaker + connected := conn.evalStatus() == StatusConnected + conn.mu.Unlock() + if h == nil { + return + } + if !connected { + conn.Log.Debugf("pqkem: peer not connected, leaving the KEM re-bootstrap to the reconnect guard") + return + } + conn.Log.Warnf("pqkem: post-quantum key exchange failed with a connected peer, re-bootstrapping over signal") + if err := h.SendOffer(); err != nil { + conn.Log.Debugf("pqkem: PQ key recovery over signal failed: %v", err) + } +} + func (conn *Conn) onWGDisconnected(watcherCtx context.Context) { conn.mu.Lock() - defer conn.mu.Unlock() // watcherCtx guards against a stale watcher tearing down a connection that already superseded it. if conn.ctx.Err() != nil || watcherCtx.Err() != nil { + conn.mu.Unlock() return } @@ -715,6 +816,15 @@ func (conn *Conn) onWGDisconnected(watcherCtx context.Context) { } conn.escalateWGTimeoutLocked() + pq := conn.config.PQ + key := conn.config.Key + conn.mu.Unlock() + + // Signal the PQ manager outside conn.mu: it may re-enter Conn (PQ key recovery) under + // conn.mu, so calling it while holding the lock would invert the lock order. + if pq != nil { + pq.OnDataPathDown(key) + } } // escalateWGTimeoutLocked resets the peer's rosenpass state after repeated @@ -738,14 +848,14 @@ func (conn *Conn) escalateWGTimeoutLocked() { conn.onDisconnected(conn.config.WgConfig.RemoteKey) } -func (conn *Conn) updateRelayStatus(relayServerAddr string, rosenpassPubKey []byte, updateTime time.Time) { +func (conn *Conn) updateRelayStatus(relayServerAddr string, rosenpassPubKey []byte, pqEstablished bool, updateTime time.Time) { peerState := State{ PubKey: conn.config.Key, ConnStatusUpdate: updateTime, ConnStatus: conn.evalStatus(), Relayed: conn.isRelayed(), RelayServerAddress: relayServerAddr, - RosenpassEnabled: isRosenpassEnabled(rosenpassPubKey), + RosenpassEnabled: conn.quantumResistant(rosenpassPubKey, pqEstablished), } err := conn.statusRecorder.UpdatePeerRelayedState(peerState) @@ -754,7 +864,7 @@ func (conn *Conn) updateRelayStatus(relayServerAddr string, rosenpassPubKey []by } } -func (conn *Conn) updateIceState(iceConnInfo ICEConnInfo, updateTime time.Time) { +func (conn *Conn) updateIceState(iceConnInfo ICEConnInfo, pqEstablished bool, updateTime time.Time) { peerState := State{ PubKey: conn.config.Key, ConnStatusUpdate: updateTime, @@ -764,7 +874,7 @@ func (conn *Conn) updateIceState(iceConnInfo ICEConnInfo, updateTime time.Time) RemoteIceCandidateType: iceConnInfo.RemoteIceCandidateType, LocalIceCandidateEndpoint: iceConnInfo.LocalIceCandidateEndpoint, RemoteIceCandidateEndpoint: iceConnInfo.RemoteIceCandidateEndpoint, - RosenpassEnabled: isRosenpassEnabled(iceConnInfo.RosenpassPubKey), + RosenpassEnabled: conn.quantumResistant(iceConnInfo.RosenpassPubKey, pqEstablished), } err := conn.statusRecorder.UpdatePeerICEState(peerState) @@ -970,6 +1080,35 @@ func (conn *Conn) onWGCheckSuccess() { conn.mu.Lock() conn.wgTimeouts = 0 conn.mu.Unlock() + + // A fresh WireGuard handshake clocks the post-quantum PSK rotation. Pass how long + // ago the peer last exchanged real user data (keepalives excluded) so the pqkem + // manager can skip rotation on idle tunnels — rotating then would push data-path + // traffic that keeps the lazy connection artificially active. + if conn.config.PQ != nil { + conn.config.PQ.OnDataPathRekeyed(conn.config.Key, conn.dataActivityAge()) + } +} + +// dataActivityAge returns how long ago the peer last exchanged real user data +// (WireGuard keepalives excluded), per the same LastActivities signal the +// lazy-connection inactivity monitor uses. It reports a very large duration when no +// activity has ever been recorded, so the peer is treated as idle. +// +// In kernel mode there is no per-peer data-activity signal (LastActivities is +// userspace-only), so we cannot tell active from idle. We report zero — always +// "active" — so PSK rotation is not disabled in kernel mode. Lazy back-to-idle is +// already limited there; the eBPF WG-activity detection (future) will supply a real +// signal that excludes handshake/pqkem traffic. +func (conn *Conn) dataActivityAge() time.Duration { + if !conn.config.WgConfig.WgInterface.IsUserspaceBind() { + return 0 + } + last, ok := conn.config.WgConfig.WgInterface.LastActivities()[conn.config.WgConfig.RemoteKey] + if !ok { + return time.Duration(math.MaxInt64) + } + return monotime.Since(last) } // recordConnectionMetrics records connection stage timestamps as metrics @@ -1007,7 +1146,73 @@ func (conn *Conn) AgentVersionString() string { return conn.config.AgentVersion } -func (conn *Conn) presharedKey(remoteRosenpassKey []byte) *wgtypes.Key { +// pqPSK returns the post-quantum PSK derived for this peer, if the ML-KEM exchange has +// produced one. It reads the manager WITHOUT conn.mu, so callers fetch it before taking +// conn.mu: the lock order is always conn.mu -> manager, never the reverse (the manager's +// PQ key recovery callback re-enters Conn under conn.mu). +func (conn *Conn) pqPSK() (*wgtypes.Key, bool) { + if conn.config.PQ == nil { + return nil, false + } + psk, ok := conn.config.PQ.PSK(conn.config.Key) + if !ok { + return nil, false + } + return &psk, true +} + +// reapplyPQPSK restores the latest PQ PSK after a WireGuard configure that used +// programmed. It runs under conn.mu; the lock order conn.mu -> PSK apply -> manager holds, +// since neither of the other two calls back into Conn while locked. +func (conn *Conn) reapplyPQPSK(programmed *wgtypes.Key) { + if conn.config.PQ == nil { + return + } + conn.config.PQ.ReapplyPSK(conn.config.Key, programmed) +} + +// IdlePresharedKey is the preshared key an idle (lazy) WireGuard peer is installed with. +// An idle peer accepts a handshake the remote initiates directly, so in ML-KEM strict +// mode it must already carry the PQ PSK, or the strict sentinel until one exists; +// installed without a key, a fresh peer would accept a classical session before any +// exchange. Outside strict mode it returns nil and leaves the idle peer's key unchanged. +func (conn *Conn) IdlePresharedKey() *wgtypes.Key { + if conn.config.PQ == nil || !conn.config.PQStrict { + return nil + } + if psk, ok := conn.pqPSK(); ok { + return psk + } + return conn.pqStrictSentinelKey +} + +// presharedKey resolves the WireGuard preshared key for the peer. pqPSK is the +// post-quantum PSK looked up out of band via pqPSK (nil when none is derived yet), passed +// in so the manager lock is never taken under conn.mu. +func (conn *Conn) presharedKey(remoteRosenpassKey []byte, pqPSK *wgtypes.Key) *wgtypes.Key { + // Post-quantum: once the ML-KEM exchange has derived a PSK for this peer, program + // it here so the peer's next WireGuard handshake adopts it. Applied at peer-config + // time (bootstrap / reconnect); steady-state rotation is pushed separately. + if conn.config.PQ != nil { + if pqPSK != nil { + return pqPSK + } + if conn.config.PQStrict && conn.pqStrictSentinelKey != nil { + // Fail closed: program a non-matching sentinel so no session forms on a + // non-PQ key until the ML-KEM exchange derives the real PSK (pushed via + // SetPresharedKey once it converges). "pending" — turns into a "stuck" + // warning from the manager if the exchange keeps failing (see raiseFailure). + conn.Log.Debugf("pqkem: strict mode — no PQ PSK yet, blocking peer traffic until the ML-KEM exchange converges") + return conn.pqStrictSentinelKey + } + // A nil key keeps the one WireGuard has, which after a downgrade is the dropped PQ + // PSK. Program the classical key explicitly; zero is WireGuard's "no PSK". + if conn.config.WgConfig.PreSharedKey != nil { + return conn.config.WgConfig.PreSharedKey + } + return &wgtypes.Key{} + } + if conn.config.RosenpassConfig.PubKey == nil { return conn.config.WgConfig.PreSharedKey } @@ -1047,6 +1252,19 @@ func isRosenpassEnabled(remoteRosenpassPubKey []byte) bool { return remoteRosenpassPubKey != nil } +// quantumResistant reports whether the peer's tunnel is post-quantum protected, for +// the status "Quantum resistance" field: either Rosenpass (the remote advertised a +// Rosenpass key) or the ML-KEM exchange (a PQ PSK has been derived for this peer). +func (conn *Conn) quantumResistant(remoteRosenpassPubKey []byte, pqEstablished bool) bool { + // Rosenpass protects the tunnel only when both sides run it: the local peer has a + // Rosenpass key AND the remote advertised one. Checking only the remote key would + // report a plain (or blocked) tunnel as quantum-resistant when the local side does + // not run Rosenpass — e.g. against a peer that merely advertises it in a mixed + // deployment. A homogeneous Rosenpass deployment (both sides on) is unaffected. + rosenpassActive := conn.config.RosenpassConfig.PubKey != nil && isRosenpassEnabled(remoteRosenpassPubKey) + return rosenpassActive || pqEstablished +} + func evalConnStatus(in connStatusInputs) guard.ConnStatus { // "Relay up and needed" — the peer uses relay and the transport is connected. relayUsedAndUp := in.peerUsesRelay && in.relayConnected diff --git a/client/internal/peer/conn_pq_test.go b/client/internal/peer/conn_pq_test.go new file mode 100644 index 00000000000..2bf9ea5a0a8 --- /dev/null +++ b/client/internal/peer/conn_pq_test.go @@ -0,0 +1,224 @@ +package peer + +import ( + "net/netip" + "strings" + "testing" + "time" + + log "github.com/sirupsen/logrus" + logtest "github.com/sirupsen/logrus/hooks/test" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "golang.zx2c4.com/wireguard/wgctrl/wgtypes" + + "github.com/netbirdio/netbird/client/internal/peer/worker" + signal "github.com/netbirdio/netbird/shared/signal/client" +) + +// fakePQ is a minimal PQHandshaker: only PSK is exercised by presharedKey, the rest +// are no-op stubs to satisfy the interface. +type fakePQ struct { + psk wgtypes.Key + ok bool +} + +func (f fakePQ) OfferPayload(string) ([]byte, uint16) { return nil, 0 } +func (f fakePQ) ShouldSendBootstrapOffer(string) bool { return false } +func (f fakePQ) SignalOfferInFlight(string) bool { return false } +func (f fakePQ) AnswerPayload(string, []byte) ([]byte, uint16) { return nil, 0 } +func (f fakePQ) OnAnswer(string, []byte) {} +func (f fakePQ) PSK(string) (wgtypes.Key, bool) { return f.psk, f.ok } +func (f fakePQ) ReapplyPSK(string, *wgtypes.Key) {} +func (f fakePQ) SetRemoteAddr(string, netip.AddrPort) {} +func (f fakePQ) OnDataPathRekeyed(string, time.Duration) {} +func (f fakePQ) OnDataPathDown(string) {} + +// TestConn_presharedKey_PQ covers the post-quantum branch of presharedKey across the +// three states that matter: a derived PSK is programmed, and — before one exists — +// strict mode blocks with a sentinel while non-strict falls open to the ordinary key. +func TestConn_presharedKey_PQ(t *testing.T) { + derivedPSK, err := wgtypes.GenerateKey() + require.NoError(t, err) + nbPSK, err := wgtypes.GenerateKey() + require.NoError(t, err) + + newConn := func() *Conn { + return &Conn{ + Log: log.WithField("peer", "pq-test"), + config: ConnConfig{ + Key: "LLHf3Ma6z6mdLbriAJbqhX7+nM/B71lgw2+91q3LfhU=", + LocalKey: "RRHf3Ma6z6mdLbriAJbqhX7+nM/B71lgw2+91q3LfhU=", + WgConfig: WgConfig{PreSharedKey: &nbPSK}, + RosenpassConfig: RosenpassConfig{}, + }, + } + } + + t.Run("derived PSK is programmed", func(t *testing.T) { + for _, strict := range []bool{false, true} { + c := newConn() + c.config.PQ = fakePQ{psk: derivedPSK, ok: true} + c.config.PQStrict = strict + if strict { + sentinel, err := wgtypes.GenerateKey() + require.NoError(t, err) + c.pqStrictSentinelKey = &sentinel + } + pqPSK, _ := c.pqPSK() + got := c.presharedKey(nil, pqPSK) + require.NotNil(t, got) + require.Equal(t, derivedPSK, *got, "the derived PQ PSK must win (strict=%v)", strict) + } + }) + + t.Run("non-strict falls open to the ordinary key before a PSK exists", func(t *testing.T) { + c := newConn() + c.config.PQ = fakePQ{ok: false} + c.config.PQStrict = false + pqPSK, _ := c.pqPSK() + got := c.presharedKey(nil, pqPSK) + require.NotNil(t, got, "non-strict must not block") + require.Equal(t, nbPSK, *got, "non-strict falls through to the NetBird PSK, not a sentinel") + }) + + t.Run("non-strict with no NetBird PSK programs the zero key", func(t *testing.T) { + // A nil key leaves WireGuard's current one in place, so after a downgrade the stale + // PQ PSK would stay programmed and the classical handshake would never complete. + c := newConn() + c.config.WgConfig.PreSharedKey = nil + c.config.PQ = fakePQ{ok: false} + pqPSK, _ := c.pqPSK() + got := c.presharedKey(nil, pqPSK) + require.NotNil(t, got, "a nil key would keep a dropped PQ PSK programmed") + assert.Equal(t, wgtypes.Key{}, *got, "non-strict without a NetBird PSK must program the zero key") + }) + + t.Run("strict blocks with the per-conn sentinel before a PSK exists", func(t *testing.T) { + sentinel, err := wgtypes.GenerateKey() + require.NoError(t, err) + c := newConn() + c.config.PQ = fakePQ{ok: false} + c.config.PQStrict = true + c.pqStrictSentinelKey = &sentinel + pqPSK, _ := c.pqPSK() + got := c.presharedKey(nil, pqPSK) + require.NotNil(t, got) + require.Equal(t, sentinel, *got, "strict must return the blocking sentinel") + require.NotEqual(t, nbPSK, *got, "the sentinel must not be the ordinary key") + }) +} + +// TestConn_IdlePresharedKey covers the key an idle (lazy) peer is installed with. Strict +// mode must never leave an idle peer without a key, since the remote can complete a +// classical handshake with it directly; everything else leaves the idle key unchanged. +func TestConn_IdlePresharedKey(t *testing.T) { + derivedPSK, err := wgtypes.GenerateKey() + require.NoError(t, err) + sentinel, err := wgtypes.GenerateKey() + require.NoError(t, err) + + newConn := func(pq PQHandshaker, strict bool) *Conn { + c := &Conn{Log: log.WithField("peer", "pq-idle-test")} + c.config.PQ = pq + c.config.PQStrict = strict + if strict { + c.pqStrictSentinelKey = &sentinel + } + return c + } + + got := newConn(fakePQ{ok: false}, true).IdlePresharedKey() + require.NotNil(t, got, "strict mode must install a key on an idle peer") + assert.Equal(t, sentinel, *got, "before a PQ PSK exists strict mode installs the sentinel") + + got = newConn(fakePQ{psk: derivedPSK, ok: true}, true).IdlePresharedKey() + require.NotNil(t, got, "strict mode must install a key on an idle peer") + assert.Equal(t, derivedPSK, *got, "once derived, strict mode installs the PQ PSK") + + assert.Nil(t, newConn(fakePQ{ok: false}, false).IdlePresharedKey(), "non-strict mode leaves the idle key unchanged") + assert.Nil(t, newConn(nil, false).IdlePresharedKey(), "without ML-KEM the idle key is left unchanged") +} + +// TestConn_RecoverPQKeyOverSignalOnlyWhenConnected covers the PQ recovery path. A failed KEM +// exchange makes the manager ask for a fresh signalling offer. For a peer with no +// transport (offline) that offer cannot be answered: with lazy connections off it was +// repeated at every exchange timeout, a fixed-rate stream on top of the reconnect guard's +// own backed-off offers. The recovery offer must only be sent while the peer is connected. +func TestConn_RecoverPQKeyOverSignalOnlyWhenConnected(t *testing.T) { + newConn := func() (*Conn, *logtest.Hook) { + logger, hook := logtest.NewNullLogger() + logger.SetLevel(log.DebugLevel) + entry := logger.WithField("peer", "pq-recovery-test") + // The signal client is never ready, so an attempted offer fails fast and is logged. + signaler := NewSignaler(&signal.MockClient{}, wgtypes.Key{}) + c := &Conn{ + Log: entry, + statusRelay: worker.NewAtomicStatus(), + statusICE: worker.NewAtomicStatus(), + } + c.handshaker = NewHandshaker(entry, ConnConfig{}, signaler, nil, nil, nil) + return c, hook + } + offerAttempted := func(hook *logtest.Hook) bool { + for _, e := range hook.AllEntries() { + if strings.Contains(e.Message, "PQ key recovery over signal failed") { + return true + } + } + return false + } + + warned := func(hook *logtest.Hook) bool { + for _, e := range hook.AllEntries() { + if e.Level <= log.WarnLevel { + return true + } + } + return false + } + + // An offline peer's bootstrap can only time out; with lazy connections off that + // happens at every reconnect offer, so it must stay out of the warnings. + c, hook := newConn() + c.RecoverPQKeyOverSignal() + assert.False(t, offerAttempted(hook), "a disconnected peer must be left to the reconnect guard") + assert.False(t, warned(hook), "a disconnected peer's failed exchange must not be warned about") + + c, hook = newConn() + c.statusRelay.SetConnected() + c.RecoverPQKeyOverSignal() + assert.True(t, offerAttempted(hook), "a connected peer must get a recovery offer") + assert.True(t, warned(hook), "a failed exchange with a connected peer must be warned about") +} + +// TestConn_QuantumResistant covers the status flag: Rosenpass counts only when both sides +// run it, and an established ML-KEM PSK counts on its own. +func TestConn_QuantumResistant(t *testing.T) { + localRP := []byte("local-rosenpass-key") + remoteRP := []byte("remote-rosenpass-key") + + cases := []struct { + name string + localRP []byte + remoteRP []byte + pqEstablished bool + want bool + }{ + {"nothing", nil, nil, false, false}, + {"rosenpass on both sides", localRP, remoteRP, false, true}, + {"rosenpass only locally", localRP, nil, false, false}, + {"rosenpass only remotely", nil, remoteRP, false, false}, + {"ml-kem established", nil, nil, true, true}, + {"ml-kem established, rosenpass only remotely", nil, remoteRP, true, true}, + {"ml-kem established, rosenpass on both sides", localRP, remoteRP, true, true}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + conn := &Conn{config: ConnConfig{RosenpassConfig: RosenpassConfig{PubKey: c.localRP}}} + assert.Equal(t, c.want, conn.quantumResistant(c.remoteRP, c.pqEstablished), + "local rosenpass %t, remote rosenpass %t, ml-kem %t", + c.localRP != nil, c.remoteRP != nil, c.pqEstablished) + }) + } +} diff --git a/client/internal/peer/conn_test.go b/client/internal/peer/conn_test.go index b481c95edd5..e83d703b95e 100644 --- a/client/internal/peer/conn_test.go +++ b/client/internal/peer/conn_test.go @@ -24,6 +24,7 @@ import ( "github.com/netbirdio/netbird/client/internal/peer/ice" "github.com/netbirdio/netbird/client/internal/peer/worker" "github.com/netbirdio/netbird/client/internal/stdnet" + "github.com/netbirdio/netbird/monotime" "github.com/netbirdio/netbird/util" ) @@ -264,8 +265,8 @@ func TestConn_presharedKey(t *testing.T) { } conn2.config.RosenpassConfig.PermissiveMode = test.conn2Permissive - conn1PresharedKey := conn1.presharedKey(conn2.config.RosenpassConfig.PubKey) - conn2PresharedKey := conn2.presharedKey(conn1.config.RosenpassConfig.PubKey) + conn1PresharedKey := conn1.presharedKey(conn2.config.RosenpassConfig.PubKey, nil) + conn2PresharedKey := conn2.presharedKey(conn1.config.RosenpassConfig.PubKey, nil) if test.conn1ExpectedInitialKey { if conn1PresharedKey == nil { @@ -303,16 +304,12 @@ func TestConn_presharedKey_RosenpassManaged(t *testing.T) { // When Rosenpass has already initialized the PSK for this peer, // presharedKey must return nil to avoid UpdatePeer overwriting it. conn.rosenpassInitializedPresharedKeyValidator = func(peerKey string) bool { return true } - if k := conn.presharedKey([]byte("remote")); k != nil { - t.Fatalf("expected nil presharedKey when Rosenpass manages PSK, got %v", k) - } + assert.Nil(t, conn.presharedKey([]byte("remote"), nil), "expected nil presharedKey when Rosenpass manages PSK") // When Rosenpass hasn't taken over yet, presharedKey should provide // a non-nil initial key (deterministic or from NetBird PSK). conn.rosenpassInitializedPresharedKeyValidator = func(peerKey string) bool { return false } - if k := conn.presharedKey([]byte("remote")); k == nil { - t.Fatalf("expected non-nil presharedKey before Rosenpass manages PSK") - } + assert.NotNil(t, conn.presharedKey([]byte("remote"), nil), "expected non-nil presharedKey before Rosenpass manages PSK") } func newWGTimeoutTestConn(rosenpassEnabled bool, disconnected *[]string) *Conn { @@ -438,6 +435,10 @@ func (s *stubWGIface) GetStats() (map[string]configurer.WGStats, error) { func (s *stubWGIface) GetProxy() wgproxy.Proxy { return nil } func (s *stubWGIface) Address() wgaddr.Address { return wgaddr.Address{} } func (s *stubWGIface) RemoveEndpointAddress(key string) error { return nil } +func (s *stubWGIface) IsUserspaceBind() bool { return false } +func (s *stubWGIface) LastActivities() map[string]monotime.Time { + return map[string]monotime.Time{} +} func TestConn_Close_CallsOnDisconnected(t *testing.T) { var disconnected []string diff --git a/client/internal/peer/endpoint.go b/client/internal/peer/endpoint.go index 9ba1efb6eb3..c17e59ff04e 100644 --- a/client/internal/peer/endpoint.go +++ b/client/internal/peer/endpoint.go @@ -88,7 +88,7 @@ func (e *EndpointUpdater) configureAsResponder(addr *net.UDPAddr, presharedKey * var ctx context.Context ctx, e.cancelFunc = context.WithCancel(context.Background()) e.updateWg.Add(1) - go e.scheduleDelayedUpdate(ctx, addr, presharedKey) + go e.scheduleDelayedUpdate(ctx, addr) if err := e.updateWireGuardPeer(nil, presharedKey); err != nil { e.waitForCloseTheDelayedUpdate() @@ -107,8 +107,14 @@ func (e *EndpointUpdater) waitForCloseTheDelayedUpdate() { e.updateWg.Wait() } -// scheduleDelayedUpdate waits for the fallback period before updating the endpoint -func (e *EndpointUpdater) scheduleDelayedUpdate(ctx context.Context, addr *net.UDPAddr, presharedKey *wgtypes.Key) { +// scheduleDelayedUpdate waits for the fallback period, then sets the responder's real +// endpoint. It deliberately passes a nil preshared key so it only updates the endpoint +// and leaves the current PSK untouched: the PSK captured when this was scheduled may be +// stale by now (e.g. the post-quantum bootstrap derived a fresher PSK within the +// fallback window, applied via SetPresharedKey), and re-applying the captured one would +// revert WireGuard to a key the remote peer no longer uses — a mismatch that stalls the +// handshake until the next retry. +func (e *EndpointUpdater) scheduleDelayedUpdate(ctx context.Context, addr *net.UDPAddr) { defer e.updateWg.Done() t := time.NewTimer(fallbackDelay) defer t.Stop() @@ -117,7 +123,7 @@ func (e *EndpointUpdater) scheduleDelayedUpdate(ctx context.Context, addr *net.U case <-ctx.Done(): return case <-t.C: - if err := e.updateWireGuardPeer(addr, presharedKey); err != nil { + if err := e.updateWireGuardPeer(addr, nil); err != nil { e.log.Errorf("failed to update WireGuard peer, address: %s, error: %v", addr, err) } } diff --git a/client/internal/peer/handshaker.go b/client/internal/peer/handshaker.go index 654e32158a2..7842efa6aec 100644 --- a/client/internal/peer/handshaker.go +++ b/client/internal/peer/handshaker.go @@ -39,6 +39,18 @@ type OfferAnswer struct { // This value is the local Rosenpass server address when sending the message RosenpassAddr string + // MlkemPayload carries the post-quantum X25519MLKEM768 handshake message + // (pqkem-framed offer on an OFFER, answer on an ANSWER) that seeds the + // WireGuard PSK. Opaque here — the pqkem library frames and parses it. Nil + // when the peer does not run the ML-KEM PQ exchange. + MlkemPayload []byte + + // MlkemPort is the peer's ML-KEM PQ service UDP port (bound on its WG overlay IP) + // where data-path rekey messages are sent. Zero means "not explicitly advertised, + // assume DefaultPort" — it does NOT indicate whether the peer runs the exchange; + // that is told by the presence of MlkemPayload / the manager's capability state. + MlkemPort uint16 + // relay server address RelaySrvAddress string // RelaySrvIP is the IP the remote peer is connected to on its @@ -116,49 +128,144 @@ func (h *Handshaker) Listen(ctx context.Context) { for { select { case remoteOfferAnswer := <-h.remoteOffersCh: - h.log.Infof("received offer, running version %s, remote WireGuard listen port %d, session id: %s, remote ICE supported: %t, relay server: %s, relay IP: %s", remoteOfferAnswer.Version, remoteOfferAnswer.WgListenPort, remoteOfferAnswer.SessionIDString(), remoteOfferAnswer.hasICECredentials(), remoteOfferAnswer.RelaySrvAddress, remoteOfferAnswer.RelaySrvIP) - - // Record signaling received for reconnection attempts - if h.metricsStages != nil { - h.metricsStages.RecordSignalingReceived() - } + h.handleRemoteOffer(remoteOfferAnswer) + case remoteOfferAnswer := <-h.remoteAnswerCh: + h.handleRemoteAnswer(remoteOfferAnswer) + case <-ctx.Done(): + h.log.Infof("stop listening for remote offers and answers") + return + } + } +} - h.updateRemoteICEState(&remoteOfferAnswer) +// onSignalReceived runs the common preamble for a received offer/answer: record the +// signalling metric, refresh the remote ICE state, and register the peer's post-quantum +// data-path endpoint learned from the message. +func (h *Handshaker) onSignalReceived(remoteOfferAnswer *OfferAnswer) { + if h.metricsStages != nil { + h.metricsStages.RecordSignalingReceived() + } + h.updateRemoteICEState(remoteOfferAnswer) + h.pqRegisterEndpoint(remoteOfferAnswer.MlkemPort) +} - if h.relayListener != nil { - h.relayListener.Notify(&remoteOfferAnswer) - } +// notifyListeners hands the offer/answer to the relay and ICE workers so they bring the +// connection up. +func (h *Handshaker) notifyListeners(remoteOfferAnswer *OfferAnswer) { + if h.relayListener != nil { + h.relayListener.Notify(remoteOfferAnswer) + } + if h.iceListener != nil && h.RemoteICESupported() { + h.iceListener(remoteOfferAnswer) + } +} - if h.iceListener != nil && h.RemoteICESupported() { - h.iceListener(&remoteOfferAnswer) - } +func (h *Handshaker) handleRemoteOffer(remoteOfferAnswer OfferAnswer) { + h.log.Infof("received offer, running version %s, remote WireGuard listen port %d, session id: %s, remote ICE supported: %t, relay server: %s, relay IP: %s", remoteOfferAnswer.Version, remoteOfferAnswer.WgListenPort, remoteOfferAnswer.SessionIDString(), remoteOfferAnswer.hasICECredentials(), remoteOfferAnswer.RelaySrvAddress, remoteOfferAnswer.RelaySrvIP) + h.onSignalReceived(&remoteOfferAnswer) - if err := h.sendAnswer(); err != nil { - h.log.Errorf("failed to send remote offer confirmation: %s", err) - continue - } - case remoteOfferAnswer := <-h.remoteAnswerCh: - h.log.Infof("received answer, running version %s, remote WireGuard listen port %d, session id: %s, remote ICE supported: %t, relay server: %s, relay IP: %s", remoteOfferAnswer.Version, remoteOfferAnswer.WgListenPort, remoteOfferAnswer.SessionIDString(), remoteOfferAnswer.hasICECredentials(), remoteOfferAnswer.RelaySrvAddress, remoteOfferAnswer.RelaySrvIP) + // If we are the controller running the KEM, a responder's offer is handled by + // replying with our own KEM offer, not by answering it (see pqControllerReoffer). + if h.pqControllerReoffer() { + return + } - // Record signaling received for reconnection attempts - if h.metricsStages != nil { - h.metricsStages.RecordSignalingReceived() - } + // Derive+store the KEM PSK (inside sendAnswer's AnswerPayload) BEFORE bringing up the + // connection: the relay/ICE workers configure the WG endpoint, which pulls the PSK + // for the first handshake. Notifying them first would race the KEM exchange and hand + // the first handshake a not-yet-derived key. A failure to signal the answer is + // transient (the peer retries), so still bring the local transport up over relay/ICE + // instead of aborting the whole setup. + if err := h.sendAnswer(&remoteOfferAnswer); err != nil { + h.log.Errorf("failed to send remote offer confirmation: %s", err) + } + h.notifyListeners(&remoteOfferAnswer) +} - h.updateRemoteICEState(&remoteOfferAnswer) +func (h *Handshaker) handleRemoteAnswer(remoteOfferAnswer OfferAnswer) { + h.log.Infof("received answer, running version %s, remote WireGuard listen port %d, session id: %s, remote ICE supported: %t, relay server: %s, relay IP: %s", remoteOfferAnswer.Version, remoteOfferAnswer.WgListenPort, remoteOfferAnswer.SessionIDString(), remoteOfferAnswer.hasICECredentials(), remoteOfferAnswer.RelaySrvAddress, remoteOfferAnswer.RelaySrvIP) + h.onSignalReceived(&remoteOfferAnswer) - if h.relayListener != nil { - h.relayListener.Notify(&remoteOfferAnswer) - } + // Feed the KEM answer (derive+store PSK) BEFORE bringing up the connection so the WG + // endpoint config pulls the real PSK for the first handshake instead of racing ahead + // of the KEM exchange. + if h.config.PQ != nil { + h.config.PQ.OnAnswer(h.config.Key, remoteOfferAnswer.MlkemPayload) + } + h.notifyListeners(&remoteOfferAnswer) +} - if h.iceListener != nil && h.RemoteICESupported() { - h.iceListener(&remoteOfferAnswer) - } - case <-ctx.Done(): - h.log.Infof("stop listening for remote offers and answers") - return +// pqControllerReoffer handles a responder's offer when we are the controller running the +// KEM. The KEM material rides only the controller's offer, so the two peers derive a +// single shared PSK (a bidirectional KEM would yield two different PSKs and WireGuard +// would pick misaligned ones). Rather than answer the responder's (KEM-less) offer — +// which would bring WireGuard up on a pre-PQ key before the KEM completes — we reply with +// our own KEM offer, so the only transaction that establishes the tunnel is the one that +// also derives the PSK. It also guarantees a responder-initiated wake still triggers a +// KEM offer (no stuck responder). Sent exactly once per exchange; further offers while +// one is in flight are ignored (re-sending on every responder offer would be a runaway). +// The re-offer reuses our stable ICE session id, so the peer dedups repeats. +// +// Returns true when the caller must not answer the peer's offer: either a re-offer went +// out, or our own KEM offer is already in flight (an offer glare). In the glare we send +// that same offer again instead of answering: a KEM-less answer could let the peer bring +// WireGuard up before it reads our offer, on no PSK at all. Resending covers an earlier +// send that failed after the exchange was installed, and the peer answers a duplicate +// from its cache. Otherwise, as for a non-capable peer, it returns false and the caller +// answers normally: the peer's offer is then the only copy of its ICE and relay details. +func (h *Handshaker) pqControllerReoffer() bool { + if h.config.PQ == nil || !isController(h.config) { + return false + } + if h.config.PQ.SignalOfferInFlight(h.config.Key) { + h.log.Debugf("pqkem: controller received a responder offer while its own KEM offer is in flight, resending that offer instead of answering") + if err := h.sendOffer(); err != nil { + h.log.Errorf("failed to resend KEM offer during an offer glare: %s", err) } + return true + } + if !h.config.PQ.ShouldSendBootstrapOffer(h.config.Key) { + h.log.Debugf("pqkem: controller received a responder offer with no fresh KEM offer to send, handling it normally") + return false } + h.log.Debugf("pqkem: controller received a responder offer, replying with our KEM offer instead of an answer") + if err := h.sendOffer(); err != nil { + // The re-offer did not go out; fall through to normal handling rather than + // silently dropping the peer's offer. + h.log.Errorf("failed to send KEM offer in response to peer offer, handling it normally: %s", err) + return false + } + return true +} + +// pqRegisterEndpoint feeds the post-quantum handshaker the peer's data-path endpoint +// (its WG overlay IP plus the advertised pq UDP port) learned from a remote offer/answer. +func (h *Handshaker) pqRegisterEndpoint(remotePort uint16) { + if h.config.PQ == nil { + return + } + overlay, ok := h.pqPeerOverlayAddr() + if !ok { + return + } + // remotePort may be 0 (the peer omitted it, meaning the default port); the adapter + // resolves 0 to DefaultPort. + h.config.PQ.SetRemoteAddr(h.config.Key, netip.AddrPortFrom(overlay, remotePort)) +} + +// pqPeerOverlayAddr returns the peer's IPv4 overlay address for the pq data path. A +// RemotePeerConfig carries only the peer overlay (v4 /32, optionally v6 /128) — served +// routes are programmed on WireGuard separately and never land in WgConfig.AllowedIps — +// so AllowedIps[0] is the v4 overlay, matching conn.AllowedIP(). The transport is v4 +// (the overlay always has v4; v6 is additive). Returns false when no v4 overlay exists. +func (h *Handshaker) pqPeerOverlayAddr() (netip.Addr, bool) { + if len(h.config.WgConfig.AllowedIps) == 0 { + return netip.Addr{}, false + } + if a := h.config.WgConfig.AllowedIps[0].Addr().Unmap(); a.Is4() { + return a, true + } + return netip.Addr{}, false } func (h *Handshaker) SendOffer() error { @@ -209,13 +316,23 @@ func (h *Handshaker) sendOffer() error { } offer := h.buildOfferAnswer() + if h.config.PQ != nil { + offer.MlkemPayload, offer.MlkemPort = h.config.PQ.OfferPayload(h.config.Key) + } h.log.Debugf("sending offer with serial: %s, relay server: %s, relay IP: %s", offer.SessionIDString(), offer.RelaySrvAddress, offer.RelaySrvIP) return h.signaler.SignalOffer(offer, h.config.Key) } -func (h *Handshaker) sendAnswer() error { +func (h *Handshaker) sendAnswer(remoteOffer *OfferAnswer) error { answer := h.buildOfferAnswer() + if h.config.PQ != nil { + var recvOffer []byte + if remoteOffer != nil { + recvOffer = remoteOffer.MlkemPayload + } + answer.MlkemPayload, answer.MlkemPort = h.config.PQ.AnswerPayload(h.config.Key, recvOffer) + } h.log.Debugf("sending answer with serial: %s, relay server: %s, relay IP: %s", answer.SessionIDString(), answer.RelaySrvAddress, answer.RelaySrvIP) return h.signaler.SignalAnswer(answer, h.config.Key) diff --git a/client/internal/peer/handshaker_pq_test.go b/client/internal/peer/handshaker_pq_test.go new file mode 100644 index 00000000000..0ee1e6fc6e1 --- /dev/null +++ b/client/internal/peer/handshaker_pq_test.go @@ -0,0 +1,106 @@ +package peer + +import ( + "sync" + "testing" + + log "github.com/sirupsen/logrus" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "golang.zx2c4.com/wireguard/wgctrl/wgtypes" + + relayClient "github.com/netbirdio/netbird/shared/relay/client" + signal "github.com/netbirdio/netbird/shared/signal/client" + sProto "github.com/netbirdio/netbird/shared/signal/proto" +) + +// bootstrapPQ is a fakePQ whose controller decisions are set by the test. +type bootstrapPQ struct { + fakePQ + bootstrap bool + inFlight bool + offer []byte +} + +func (b bootstrapPQ) OfferPayload(string) ([]byte, uint16) { return b.offer, 0 } + +func (b bootstrapPQ) ShouldSendBootstrapOffer(string) bool { return b.bootstrap } +func (b bootstrapPQ) SignalOfferInFlight(string) bool { return b.inFlight } + +// newControllerHandshaker builds a handshaker for the controller side of a peer pair and +// records the body of every signalling message it sends. +func newControllerHandshaker(t *testing.T, pq PQHandshaker) (*Handshaker, func() []*sProto.Body) { + t.Helper() + var mu sync.Mutex + var sent []*sProto.Body + client := &signal.MockClient{ + ReadyFunc: func() bool { return true }, + SendFunc: func(msg *sProto.Message) error { + mu.Lock() + defer mu.Unlock() + sent = append(sent, msg.GetBody()) + return nil + }, + } + key, err := wgtypes.GeneratePrivateKey() + require.NoError(t, err) + config := ConnConfig{Key: "aaaa", LocalKey: "bbbb", PQ: pq} // LocalKey > Key: controller + relay := &WorkerRelay{relayManager: &relayClient.Manager{}} + h := NewHandshaker(log.WithField("test", t.Name()), config, NewSignaler(client, key), nil, relay, nil) + return h, func() []*sProto.Body { + mu.Lock() + defer mu.Unlock() + return append([]*sProto.Body(nil), sent...) + } +} + +func bodyTypes(bodies []*sProto.Body) []sProto.Body_Type { + types := make([]sProto.Body_Type, 0, len(bodies)) + for _, b := range bodies { + types = append(types, b.GetType()) + } + return types +} + +// TestHandshaker_ControllerReoffersOnResponderOffer drives the responder-originated +// reconnect through the handshaker: when the KEM manager asks for a fresh bootstrap, the +// controller replies to the responder's KEM-less offer with its own offer and sends no +// answer, so the reconnect re-derives one PSK on both sides. +func TestHandshaker_ControllerReoffersOnResponderOffer(t *testing.T) { + h, sent := newControllerHandshaker(t, bootstrapPQ{bootstrap: true}) + + h.handleRemoteOffer(OfferAnswer{}) + + assert.Equal(t, []sProto.Body_Type{sProto.Body_OFFER}, bodyTypes(sent()), + "the controller must reply with its own offer, not an answer") +} + +// TestHandshaker_ControllerResendsOfferInGlare covers an offer glare: the controller's KEM +// offer and the responder's KEM-less offer cross. The controller must not answer: a +// KEM-less answer could reach the responder before the KEM offer and let it bring WireGuard +// up with no PSK. It sends its in-flight offer again instead, in case the first send failed. +func TestHandshaker_ControllerResendsOfferInGlare(t *testing.T) { + inFlightOffer := []byte("in-flight KEM offer") + h, sent := newControllerHandshaker(t, bootstrapPQ{inFlight: true, offer: inFlightOffer}) + notified := false + h.AddICEListener(func(*OfferAnswer) { notified = true }) // called synchronously + + h.handleRemoteOffer(OfferAnswer{IceCredentials: IceCredentials{UFrag: "ufrag", Pwd: "pwd"}}) + + bodies := sent() + require.Len(t, bodies, 1, "in a glare the controller must send exactly one message") + assert.Equal(t, sProto.Body_OFFER, bodies[0].GetType(), "in a glare the controller must resend its offer, not answer") + assert.Equal(t, inFlightOffer, bodies[0].GetMlkemPayload(), "the resend must carry the in-flight KEM offer") + assert.False(t, notified, "in a glare the controller must not bring the connection up from the responder's offer") +} + +// TestHandshaker_ControllerAnswersNonCapablePeer keeps the normal answer when there is no +// KEM to run with the peer: its offer is then the only copy of its connection details. +func TestHandshaker_ControllerAnswersNonCapablePeer(t *testing.T) { + h, sent := newControllerHandshaker(t, bootstrapPQ{}) + + h.handleRemoteOffer(OfferAnswer{}) + + assert.Equal(t, []sProto.Body_Type{sProto.Body_ANSWER}, bodyTypes(sent()), + "without a KEM to run the controller must answer normally") +} diff --git a/client/internal/peer/iface.go b/client/internal/peer/iface.go index 678396e612e..a12a0e181ca 100644 --- a/client/internal/peer/iface.go +++ b/client/internal/peer/iface.go @@ -10,6 +10,7 @@ import ( "github.com/netbirdio/netbird/client/iface/configurer" "github.com/netbirdio/netbird/client/iface/wgaddr" "github.com/netbirdio/netbird/client/iface/wgproxy" + "github.com/netbirdio/netbird/monotime" ) type WGIface interface { @@ -19,4 +20,11 @@ type WGIface interface { GetProxy() wgproxy.Proxy Address() wgaddr.Address RemoveEndpointAddress(key string) error + // LastActivities returns the last real-data activity time per peer (WireGuard + // keepalives excluded), used to gate post-quantum PSK rotation on active tunnels. + LastActivities() map[string]monotime.Time + // IsUserspaceBind reports whether WireGuard runs in userspace. Only there does + // LastActivities track per-peer data activity; in kernel mode it is unavailable, + // so PSK rotation cannot be gated on activity. + IsUserspaceBind() bool } diff --git a/client/internal/peer/signaler.go b/client/internal/peer/signaler.go index 590bf3fed83..9207c86d505 100644 --- a/client/internal/peer/signaler.go +++ b/client/internal/peer/signaler.go @@ -63,6 +63,8 @@ func (s *Signaler) signalOfferAnswer(offerAnswer OfferAnswer, remoteKey string, }, RosenpassPubKey: offerAnswer.RosenpassPubKey, RosenpassAddr: offerAnswer.RosenpassAddr, + MlkemPayload: offerAnswer.MlkemPayload, + MlkemPort: int(offerAnswer.MlkemPort), RelaySrvAddress: offerAnswer.RelaySrvAddress, RelaySrvIP: offerAnswer.RelaySrvIP, SessionID: sessionIDBytes, diff --git a/client/internal/peer/status.go b/client/internal/peer/status.go index b695e3b22f6..13cde71887e 100644 --- a/client/internal/peer/status.go +++ b/client/internal/peer/status.go @@ -164,6 +164,14 @@ type RosenpassState struct { Permissive bool } +// MLKEMState contains the latest state of the ML-KEM post-quantum exchange, the +// Rosenpass alternative. Strict is the ML-KEM counterpart of Rosenpass non-permissive: +// it fails closed until the KEM PSK is established. +type MLKEMState struct { + Enabled bool + Strict bool +} + // NSGroupState represents the status of a DNS server group, including associated domains, // whether it's enabled, and the last error message encountered during probing. type NSGroupState struct { @@ -181,6 +189,7 @@ type FullStatus struct { SignalState SignalState LocalPeerState LocalPeerState RosenpassState RosenpassState + MLKEMState MLKEMState Relays []relay.ProbeResult NSGroupStates []NSGroupState LazyConnectionEnabled bool @@ -262,9 +271,12 @@ func (s *StatusChangeSubscription) deliver(snapshot *routerSnapshot, block bool) // every private-service request) don't contend against each other. // Pure read methods take RLock; anything that mutates state takes Lock. type Status struct { - mux sync.RWMutex - muxRelays sync.RWMutex - peers map[string]State + mux sync.RWMutex + muxRelays sync.RWMutex + peers map[string]State + // pqMarked holds the peers with a programmed post-quantum PSK. It survives connection + // updates (see quantumResistantLocked) and is dropped with the peer. + pqMarked map[string]struct{} ipToKey map[string]string activeRoutePeers map[route.HAUniqueID]string changeNotify map[string]map[string]*StatusChangeSubscription // map[peerID]map[subscriptionID]*StatusChangeSubscription @@ -282,6 +294,8 @@ type Status struct { notifier *notifier rosenpassEnabled bool rosenpassPermissive bool + mlkemEnabled bool + mlkemStrict bool // sessionExpiresAt is the absolute UTC instant at which the peer's SSO // session expires. Zero when the peer is not SSO-tracked or login // expiration is disabled. Populated from management LoginResponse / @@ -327,6 +341,7 @@ type Status struct { func NewRecorder(mgmAddress string) *Status { return &Status{ peers: make(map[string]State), + pqMarked: make(map[string]struct{}), ipToKey: make(map[string]string), activeRoutePeers: make(map[route.HAUniqueID]string), changeNotify: make(map[string]map[string]*StatusChangeSubscription), @@ -429,6 +444,7 @@ func (d *Status) RemovePeer(peerPubKey string) error { } delete(d.peers, peerPubKey) + delete(d.pqMarked, peerPubKey) if mappedKey, exists := d.ipToKey[p.IP]; exists && mappedKey == peerPubKey { delete(d.ipToKey, p.IP) } @@ -460,7 +476,7 @@ func (d *Status) UpdatePeerState(receivedState State) error { peerState.LocalIceCandidateEndpoint = receivedState.LocalIceCandidateEndpoint peerState.RemoteIceCandidateEndpoint = receivedState.RemoteIceCandidateEndpoint peerState.RelayServerAddress = receivedState.RelayServerAddress - peerState.RosenpassEnabled = receivedState.RosenpassEnabled + peerState.RosenpassEnabled = d.quantumResistantLocked(receivedState.PubKey, receivedState.RosenpassEnabled) peerState.clearLatency() } @@ -583,7 +599,7 @@ func (d *Status) UpdatePeerICEState(receivedState State) error { peerState.RemoteIceCandidateType = receivedState.RemoteIceCandidateType peerState.LocalIceCandidateEndpoint = receivedState.LocalIceCandidateEndpoint peerState.RemoteIceCandidateEndpoint = receivedState.RemoteIceCandidateEndpoint - peerState.RosenpassEnabled = receivedState.RosenpassEnabled + peerState.RosenpassEnabled = d.quantumResistantLocked(receivedState.PubKey, receivedState.RosenpassEnabled) d.peers[receivedState.PubKey] = peerState @@ -620,7 +636,7 @@ func (d *Status) UpdatePeerRelayedState(receivedState State) error { peerState.ConnStatusUpdate = receivedState.ConnStatusUpdate peerState.Relayed = receivedState.Relayed peerState.RelayServerAddress = receivedState.RelayServerAddress - peerState.RosenpassEnabled = receivedState.RosenpassEnabled + peerState.RosenpassEnabled = d.quantumResistantLocked(receivedState.PubKey, receivedState.RosenpassEnabled) d.peers[receivedState.PubKey] = peerState @@ -760,6 +776,54 @@ func (d *Status) UpdatePeerFQDN(peerPubKey, fqdn string) error { return nil } +// MarkPeerQuantumResistant flags the peer's tunnel as post-quantum protected. The flag is +// otherwise computed only when the connection comes up, so a PSK that lands after that +// (e.g. the KEM answer arriving after the WireGuard endpoint was configured) needs this +// to show up in the status. The mark persists until the peer is removed. +func (d *Status) MarkPeerQuantumResistant(peerPubKey string) error { + d.mux.Lock() + peerState, ok := d.peers[peerPubKey] + if !ok { + d.mux.Unlock() + return errors.New("peer doesn't exist") + } + + d.pqMarked[peerPubKey] = struct{}{} + peerState.RosenpassEnabled = true + d.peers[peerPubKey] = peerState + d.mux.Unlock() + + d.notifyStateChange() + return nil +} + +// UnmarkPeerQuantumResistant clears the post-quantum flag of a peer that stopped running +// the KEM, so the status stops claiming a protection its tunnel no longer has. +func (d *Status) UnmarkPeerQuantumResistant(peerPubKey string) error { + d.mux.Lock() + peerState, ok := d.peers[peerPubKey] + if !ok { + d.mux.Unlock() + return errors.New("peer doesn't exist") + } + + delete(d.pqMarked, peerPubKey) + peerState.RosenpassEnabled = false + d.peers[peerPubKey] = peerState + d.mux.Unlock() + + d.notifyStateChange() + return nil +} + +// quantumResistantLocked merges a connection update's verdict with the PQ mark. The +// connection path computes its verdict before configuring WireGuard, so it can write it +// after the PSK was programmed; the mark keeps that stale false from clearing it. +func (d *Status) quantumResistantLocked(peerPubKey string, fromConn bool) bool { + _, marked := d.pqMarked[peerPubKey] + return fromConn || marked +} + // UpdatePeerSSHHostKey updates peer's SSH host key func (d *Status) UpdatePeerSSHHostKey(peerPubKey string, sshHostKey []byte) error { d.mux.Lock() @@ -1026,6 +1090,14 @@ func (d *Status) UpdateRosenpass(rosenpassEnabled, rosenpassPermissive bool) { d.rosenpassEnabled = rosenpassEnabled } +// UpdateMLKEM updates the ML-KEM post-quantum exchange configuration. +func (d *Status) UpdateMLKEM(mlkemEnabled, mlkemStrict bool) { + d.mux.Lock() + defer d.mux.Unlock() + d.mlkemEnabled = mlkemEnabled + d.mlkemStrict = mlkemStrict +} + func (d *Status) UpdateLazyConnection(enabled bool) { d.mux.Lock() defer d.mux.Unlock() @@ -1118,6 +1190,15 @@ func (d *Status) GetRosenpassState() RosenpassState { } } +func (d *Status) GetMLKEMState() MLKEMState { + d.mux.RLock() + defer d.mux.RUnlock() + return MLKEMState{ + d.mlkemEnabled, + d.mlkemStrict, + } +} + func (d *Status) GetLazyConnection() bool { d.mux.RLock() defer d.mux.RUnlock() @@ -1270,6 +1351,7 @@ func (d *Status) GetFullStatus() FullStatus { SignalState: d.GetSignalState(), Relays: d.GetRelayStates(), RosenpassState: d.GetRosenpassState(), + MLKEMState: d.GetMLKEMState(), NSGroupStates: d.GetDNSStates(), LazyConnectionEnabled: d.GetLazyConnection(), } @@ -1646,6 +1728,8 @@ func (fs FullStatus) ToProto() *proto.FullStatus { pbFullStatus.LocalPeerState.WgPort = int32(fs.LocalPeerState.WgPort) pbFullStatus.LocalPeerState.RosenpassPermissive = fs.RosenpassState.Permissive pbFullStatus.LocalPeerState.RosenpassEnabled = fs.RosenpassState.Enabled + pbFullStatus.LocalPeerState.MlkemEnabled = fs.MLKEMState.Enabled + pbFullStatus.LocalPeerState.MlkemStrict = fs.MLKEMState.Strict pbFullStatus.LazyConnectionEnabled = fs.LazyConnectionEnabled pbFullStatus.LocalPeerState.Networks = maps.Keys(fs.LocalPeerState.Routes) diff --git a/client/internal/peer/status_test.go b/client/internal/peer/status_test.go index 2d910ccf52c..a7458f12cbc 100644 --- a/client/internal/peer/status_test.go +++ b/client/internal/peer/status_test.go @@ -573,3 +573,65 @@ func TestActiveRoutePeers(t *testing.T) { assert.False(t, ok) assert.Equal(t, "peerB", active[netB]) } + +// TestStatus_PQMarkSurvivesStaleConnectionUpdate reproduces a lab race: the relay/ICE +// path builds its status update from a PQ state read before the KEM answer landed, and +// writes it after the PSK was programmed and the peer marked quantum resistant. That +// stale "false" must not clear the mark, since the PQ PSK lives until the peer is removed. +func TestStatus_PQMarkSurvivesStaleConnectionUpdate(t *testing.T) { + const key = "eDQmZp9jhQGX7XdYpHGaFSpAouldr3Sbf7MZRcGTGGQ=" + updates := map[string]func(*Status, State) error{ + "relayed": (*Status).UpdatePeerRelayedState, + "ice": (*Status).UpdatePeerICEState, + "state": (*Status).UpdatePeerState, + } + for name, update := range updates { + t.Run(name, func(t *testing.T) { + status := NewRecorder("https://mgm") + require.NoError(t, status.AddPeer(key, "peer.netbird.cloud", "100.64.0.2", "")) + require.NoError(t, status.MarkPeerQuantumResistant(key)) + + require.NoError(t, update(status, State{PubKey: key, ConnStatus: StatusConnected, RosenpassEnabled: false})) + + st, err := status.GetPeer(key) + require.NoError(t, err) + assert.True(t, st.RosenpassEnabled, "a stale connection update must not clear the PQ mark") + }) + } +} + +// TestStatus_PQMarkClearedOnRemove verifies the mark does not outlive the peer: once the +// peer is removed and re-added, a connection update without PQ reports it as such. +func TestStatus_PQMarkClearedOnRemove(t *testing.T) { + const key = "eDQmZp9jhQGX7XdYpHGaFSpAouldr3Sbf7MZRcGTGGQ=" + status := NewRecorder("https://mgm") + require.NoError(t, status.AddPeer(key, "peer.netbird.cloud", "100.64.0.2", "")) + require.NoError(t, status.MarkPeerQuantumResistant(key)) + require.NoError(t, status.RemovePeer(key)) + require.NoError(t, status.AddPeer(key, "peer.netbird.cloud", "100.64.0.2", "")) + + require.NoError(t, status.UpdatePeerRelayedState(State{PubKey: key, ConnStatus: StatusConnected, RosenpassEnabled: false})) + + st, err := status.GetPeer(key) + require.NoError(t, err) + assert.False(t, st.RosenpassEnabled, "a re-added peer must not inherit the removed peer's PQ mark") +} + +// TestStatus_PQMarkWakesSubscribers checks that a PSK landing after the connection came up +// reaches status subscribers, which otherwise keep showing the peer as not protected. +func TestStatus_PQMarkWakesSubscribers(t *testing.T) { + const key = "eDQmZp9jhQGX7XdYpHGaFSpAouldr3Sbf7MZRcGTGGQ=" + status := NewRecorder("https://mgm") + require.NoError(t, status.AddPeer(key, "peer.netbird.cloud", "100.64.0.2", "")) + + id, changes := status.SubscribeToStateChanges() + defer status.UnsubscribeFromStateChanges(id) + + require.NoError(t, status.MarkPeerQuantumResistant(key)) + + select { + case <-changes: + default: + assert.Fail(t, "marking a peer quantum resistant must notify status subscribers") + } +} diff --git a/client/internal/pqkem/bench_test.go b/client/internal/pqkem/bench_test.go new file mode 100644 index 00000000000..7e500de77c7 --- /dev/null +++ b/client/internal/pqkem/bench_test.go @@ -0,0 +1,71 @@ +package pqkem + +import ( + "crypto/ecdh" + "crypto/mlkem" + "crypto/rand" + "testing" +) + +func BenchmarkX25519Keygen(b *testing.B) { + c := ecdh.X25519() + b.ResetTimer() + for i := 0; i < b.N; i++ { + if _, err := c.GenerateKey(rand.Reader); err != nil { + b.Fatal(err) + } + } +} + +func BenchmarkX25519ECDH(b *testing.B) { + c := ecdh.X25519() + a, err := c.GenerateKey(rand.Reader) + if err != nil { + b.Fatal(err) + } + p, err := c.GenerateKey(rand.Reader) + if err != nil { + b.Fatal(err) + } + pub := p.PublicKey() + b.ResetTimer() + for i := 0; i < b.N; i++ { + if _, err := a.ECDH(pub); err != nil { + b.Fatal(err) + } + } +} + +func BenchmarkMLKEMKeygen(b *testing.B) { + for i := 0; i < b.N; i++ { + if _, err := mlkem.GenerateKey768(); err != nil { + b.Fatal(err) + } + } +} + +func BenchmarkMLKEMEncaps(b *testing.B) { + dk, err := mlkem.GenerateKey768() + if err != nil { + b.Fatal(err) + } + ek := dk.EncapsulationKey() + b.ResetTimer() + for i := 0; i < b.N; i++ { + _, _ = ek.Encapsulate() + } +} + +func BenchmarkMLKEMDecaps(b *testing.B) { + dk, err := mlkem.GenerateKey768() + if err != nil { + b.Fatal(err) + } + _, ct := dk.EncapsulationKey().Encapsulate() + b.ResetTimer() + for i := 0; i < b.N; i++ { + if _, err := dk.Decapsulate(ct); err != nil { + b.Fatal(err) + } + } +} diff --git a/client/internal/pqkem/callbacks.go b/client/internal/pqkem/callbacks.go new file mode 100644 index 00000000000..f1b681648c6 --- /dev/null +++ b/client/internal/pqkem/callbacks.go @@ -0,0 +1,27 @@ +package pqkem + +// CallbackHandler is implemented by the host and invoked by the library. The +// library only reports events; the host owns the reaction. Keeping this an +// interface — rather than touching the transport or keying directly — is what lets +// the KEM code be extracted as a standalone library. +type CallbackHandler interface { + // OnNewPSKReady fires when a fresh post-quantum PSK has been derived for a peer + // and must be programmed into the consumer's secure channel. The protocol has no + // explicit confirm: the initiator fires it on receiving the answer, the responder + // fires it right after deriving the PSK from the offer and before sending that + // answer. A fired callback therefore means the key is derived locally, not that the + // peer has confirmed it — the next offer is the later acknowledgement. + // + // gen is a per-peer monotonic generation: a later exchange always carries a higher + // gen. Callbacks can be applied out of order (two exchanges deriving concurrently), + // so the host must ignore a call whose gen is not newer than the one it last applied + // for that peer, or it may restore an older PSK over a newer one and split the tunnel. + OnNewPSKReady(remoteID RemoteID, gen uint64, psk PSK) error + + // OnRekeyFailed fires when an exchange fails to converge within the allotted time. + // Recovery is host-defined: the library reports the event and does not dictate the + // reaction. The shipped NetBird host, for instance, re-bootstraps the KEM over + // signalling and keeps the tunnel on its previous PSK rather than tearing the + // connection down. + OnRekeyFailed(remoteID RemoteID) error +} diff --git a/client/internal/pqkem/capability_test.go b/client/internal/pqkem/capability_test.go new file mode 100644 index 00000000000..84d81196830 --- /dev/null +++ b/client/internal/pqkem/capability_test.go @@ -0,0 +1,267 @@ +package pqkem + +import ( + "context" + "log/slog" + "sync" + "sync/atomic" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// TestManager_NonCapablePeerNotOffered: a peer known not to run the KEM (it answered our +// offer with an empty KEM payload over signalling) is never offered an exchange, and no +// failure is raised — this is what stops the recovery storm against non-PQ peers (e.g. +// Rosenpass peers). +func TestManager_NonCapablePeerNotOffered(t *testing.T) { + wg := newFakeWG() + d := NewManager("bbbb", wg, nil) // initiator vs "aaaa" + d.Start(&loopback{ep: epB, sw: newSwitch()}) + defer d.Stop() + + d.MarkNonCapable("aaaa") + + offer, err := d.SignalOffer("aaaa") + require.NoError(t, err) + assert.Nil(t, offer, "a non-capable peer must not be offered a KEM exchange") + assert.Empty(t, wg.failed, "a non-capable peer must not raise a rekey failure") +} + +// TestManager_MarkNonCapableCancelsInFlight: if we start an exchange with a peer whose +// capability is not yet known and then learn it does not run the KEM, the in-flight +// exchange is cancelled and no further offer is produced (no timeout -> no failure). +func TestManager_MarkNonCapableCancelsInFlight(t *testing.T) { + wg := newFakeWG() + d := NewManager("bbbb", wg, nil) + d.Start(&loopback{ep: epB, sw: newSwitch()}) + defer d.Stop() + + // Capability unknown -> the bootstrap offer goes out optimistically. + offer, err := d.SignalOffer("aaaa") + require.NoError(t, err) + require.NotNil(t, offer) + + // Record the cancellation of the in-flight exchange's loop. Without it the loop would + // time out and raise OnRekeyFailed, the re-bootstrap storm MarkNonCapable prevents. + var cancelled atomic.Bool + d.mu.Lock() + ex := d.exchanges["aaaa"] + if ex != nil { + loopCancel := ex.cancel + ex.cancel = func() { + cancelled.Store(true) + loopCancel() + } + } + d.mu.Unlock() + // Asserted after unlocking: a failing require stops the test, and the deferred Stop + // would then block on the lock. + require.NotNil(t, ex, "precondition: the bootstrap exchange is in flight") + + // Now we learn the peer is non-PQ: the exchange must be dropped. + d.MarkNonCapable("aaaa") + + assert.True(t, cancelled.Load(), "the in-flight exchange's loop must be cancelled") + d.mu.Lock() + _, stillTracked := d.exchanges["aaaa"] + d.mu.Unlock() + assert.False(t, stillTracked, "the in-flight exchange must be dropped") + + next, err := d.SignalOffer("aaaa") + require.NoError(t, err) + assert.Nil(t, next, "after learning non-capability the peer is no longer offered") + assert.Empty(t, wg.failed, "cancelling an in-flight exchange must not raise a failure") +} + +// TestManager_EstablishedPeerDowngraded: every failure sends an error marker, so a missing +// KEM from an established peer means it restarted without the KEM. Keeping the PSK would +// program a key the peer no longer has and the tunnel would never come up, so it is dropped +// and the peer is no longer offered. +func TestManager_EstablishedPeerDowngraded(t *testing.T) { + dA, dB, _, wgB, _ := pair(t) + defer dA.Stop() + defer dB.Stop() + + bootstrap(t, dA, dB) + require.NotEqual(t, PSK{}, wgB.psk("aaaa"), "established a PSK") + + assert.True(t, dB.MarkNonCapable("aaaa"), "dropping an established PSK must be reported") + + _, ok := dB.PSK("aaaa") + assert.False(t, ok, "a downgraded peer must not keep its PSK") + offer, err := dB.SignalOffer("aaaa") + require.NoError(t, err) + assert.Nil(t, offer, "a downgraded peer must not be offered") + assert.False(t, dB.MarkNonCapable("aaaa"), "a peer already downgraded has no PSK left to drop") +} + +// TestManager_ClearNonCapableReoffers: a peer found non-capable is offered again once the +// host learns it runs the KEM, and the exchange converges. +func TestManager_ClearNonCapableReoffers(t *testing.T) { + dA, dB, wgA, wgB, _ := pair(t) + defer dA.Stop() + defer dB.Stop() + + assert.False(t, dB.MarkNonCapable("aaaa"), "a peer never established is not a downgrade") + require.False(t, dB.ShouldSendBootstrapOffer("aaaa"), "precondition: not offered") + + dB.ClearNonCapable("aaaa") + + assert.True(t, dB.ShouldSendBootstrapOffer("aaaa"), "a cleared peer must be offered again") + bootstrap(t, dA, dB) + assert.Equal(t, wgB.psk("aaaa"), wgA.psk("bbbb"), "the renewed exchange must converge") +} + +// TestManager_ErrorMarkerIsBenign verifies finding F's wire half: a responder failure is +// signalled with an error marker (not an empty answer), so the initiator does not read it +// as "peer has no KEM". The marker must be benign — it must not disturb the in-flight +// exchange, which still converges when the real answer arrives. +func TestManager_ErrorMarkerIsBenign(t *testing.T) { + dA, dB, wgA, wgB, _ := pair(t) // dB ("bbbb") initiator, dA ("aaaa") responder + defer dA.Stop() + defer dB.Stop() + + offer, err := dB.SignalOffer("aaaa") + require.NoError(t, err) + require.NotNil(t, offer) + + _, decoded, err := Decode(offer) + require.NoError(t, err) + offerID := decoded.(*OfferMsg).ExchangeID + + // An error marker for the in-flight offer must be accepted without error and must not + // tear the exchange down (unlike an empty answer, which signals non-capability). + marker := (&ErrorMsg{ExchangeID: offerID}).Encode() + require.NoError(t, dB.SignalOnAnswer("aaaa", marker)) + + // The real answer still converges both sides on the same PSK. + answer, err := dA.SignalOnOffer("bbbb", offer) + require.NoError(t, err) + require.NotNil(t, answer) + require.NoError(t, dB.SignalOnAnswer("aaaa", answer)) + + assert.Equal(t, wgB.psk("aaaa"), wgA.psk("bbbb"), "the exchange must still converge after a benign error marker") + assert.NotEqual(t, PSK{}, wgB.psk("aaaa")) +} + +// TestManager_OfferErrorMarkerAnsweredWithMarker covers the other direction: the initiator +// failed to build its offer and sent a marker. The responder must answer with a marker of +// its own, never an empty answer, which the initiator would read as "peer has no KEM". +func TestManager_OfferErrorMarkerAnsweredWithMarker(t *testing.T) { + dA, dB, _, _, _ := pair(t) + defer dA.Stop() + defer dB.Stop() + + reply, err := dA.SignalOnOffer("bbbb", (&ErrorMsg{}).Encode()) + require.NoError(t, err) + require.NotEmpty(t, reply, "an empty reply would mark the responder non-capable") + + typ, _, err := Decode(reply) + require.NoError(t, err) + assert.Equal(t, MsgError, typ, "the reply to an offer marker must be a marker") + + _, established := dA.PSK("bbbb") + assert.False(t, established, "a marker must not derive a PSK") +} + +// TestManager_UnreadableOfferAnsweredWithMarker: an offer the responder cannot process, such +// as one from a newer protocol version, must get an error marker. An empty answer would make +// the initiator mark the responder non-capable for good and stay classical with it. +func TestManager_UnreadableOfferAnsweredWithMarker(t *testing.T) { + dA, dB, _, _, _ := pair(t) + defer dB.Stop() + + offer, err := dB.SignalOffer("aaaa") + require.NoError(t, err) + require.NotNil(t, offer) + + newerVersion := append([]byte(nil), offer...) + newerVersion[1] = ProtocolVersion + 1 + answerType := (&ErrorMsg{}).Encode() + answerType[0] = byte(MsgAnswer) + + cases := map[string][]byte{ + "garbage": {1, 2, 3}, + "newer version": newerVersion, + "not an offer": answerType, + "truncated body": offer[:len(offer)-1], + } + for name, in := range cases { + t.Run(name, func(t *testing.T) { + reply, err := dA.SignalOnOffer("bbbb", in) + assert.Error(t, err) + assertErrorMarker(t, reply) + }) + } + + t.Run("manager stopping", func(t *testing.T) { + dA.Stop() + reply, err := dA.SignalOnOffer("bbbb", offer) + assert.Error(t, err) + assertErrorMarker(t, reply) + }) +} + +func assertErrorMarker(t *testing.T, reply []byte) { + t.Helper() + require.NotEmpty(t, reply, "an empty reply would mark the responder non-capable") + typ, _, err := Decode(reply) + require.NoError(t, err) + assert.Equal(t, MsgError, typ, "the reply must be an error marker") +} + +// levelRecorder keeps the warning-or-above records a manager logs. +type levelRecorder struct { + mu sync.Mutex + warns []slog.Record +} + +func (r *levelRecorder) Enabled(context.Context, slog.Level) bool { return true } +func (r *levelRecorder) Handle(_ context.Context, rec slog.Record) error { + r.mu.Lock() + defer r.mu.Unlock() + if rec.Level >= slog.LevelWarn { + r.warns = append(r.warns, rec) + } + return nil +} +func (r *levelRecorder) WithAttrs([]slog.Attr) slog.Handler { return r } +func (r *levelRecorder) WithGroup(string) slog.Handler { return r } + +func (r *levelRecorder) warnings() []string { + r.mu.Lock() + defer r.mu.Unlock() + var msgs []string + for _, rec := range r.warns { + msgs = append(msgs, rec.Message) + } + return msgs +} + +// TestManager_InitialTimeoutNotWarned: with lazy connections off, every reconnect offer to +// an offline peer starts a bootstrap that can only time out. The manager cannot tell that +// from a real failure, so it must report it without a warning and leave the severity to +// the host, which knows whether the peer is connected. +func TestManager_InitialTimeoutNotWarned(t *testing.T) { + wg := newFakeWG() + rec := &levelRecorder{} + d := NewManager("bbbb", wg, slog.New(rec)) // initiator vs "aaaa" + d.retryInterval = 5 * time.Millisecond + d.maxRetries = 1 + d.Start(&loopback{ep: epB, sw: newSwitch()}) + defer d.Stop() + + offer, err := d.SignalOffer("aaaa") + require.NoError(t, err) + require.NotNil(t, offer, "precondition: the bootstrap offer goes out") + + require.Eventually(t, func() bool { + wg.mu.Lock() + defer wg.mu.Unlock() + return len(wg.failed) == 1 + }, 2*time.Second, 5*time.Millisecond, "the unanswered bootstrap must still be reported to the host") + assert.Empty(t, rec.warnings(), "an unanswered bootstrap must not be logged as a warning") +} diff --git a/client/internal/pqkem/concurrency_test.go b/client/internal/pqkem/concurrency_test.go new file mode 100644 index 00000000000..e81265ee2e4 --- /dev/null +++ b/client/internal/pqkem/concurrency_test.go @@ -0,0 +1,90 @@ +package pqkem + +import ( + "sync" + "testing" + "time" + + "github.com/stretchr/testify/require" +) + +// TestConcurrency_RecoversViaResignalAfterDataPathBreak exercises the A-light recovery: +// a data-path rotation can no longer converge (OnRekeyFailed), and re-bootstrapping over +// signalling resyncs both peers on a fresh PSK — even while the data path stays broken, +// since the signal channel is independent of it. +func TestConcurrency_RecoversViaResignalAfterDataPathBreak(t *testing.T) { + dA, dB, wgA, wgB, lbB := pair(t) + defer dA.Stop() + defer dB.Stop() + + // A fast retransmit tick, set before any exchange loop spawns because the loop reads it + // unguarded at start. The retry budget stays generous for the two bootstraps, which + // must succeed: with a tight budget the loop could time an exchange out while the test + // goroutine is descheduled between the offer and the answer. + dB.retryInterval = 5 * time.Millisecond + setRetryBudget(dB, 1000, 1) + + bootstrap(t, dA, dB) + dA.OnDataPathRekeyed("bbbb", 0) + dB.OnDataPathRekeyed("aaaa", 0) + psk1 := wgB.psk("aaaa") + require.NotEqual(t, PSK{}, psk1) + require.Equal(t, psk1, wgA.psk("bbbb"), "converged on the same PSK after bootstrap+rotation") + + // Data path breaks: the rotation can no longer converge, and with a budget of two + // retransmits a single miss raises OnRekeyFailed. + setRetryBudget(dB, 2, 1) + lbB.drop.Store(true) + _, err := dB.startExchangeTest("aaaa", false, ExchangeID{}) + require.NoError(t, err) + require.Eventually(t, func() bool { return failedCount(wgB) >= 1 }, time.Second, 5*time.Millisecond) + + // Recovery: re-bootstrap over signalling with the data path STILL broken. It must + // still converge (signal is independent of the data path) on a fresh PSK. + setRetryBudget(dB, 1000, 1) + bootstrap(t, dA, dB) + psk2 := wgB.psk("aaaa") + require.NotEqual(t, psk1, psk2, "recovery derived a fresh PSK") + require.Equal(t, psk2, wgA.psk("bbbb"), "both sides resync after recovery") +} + +// setRetryBudget changes the retry and failure budgets of a running manager. The exchange +// loops read both under the manager lock, so they can change between phases of a test. +func setRetryBudget(m *Manager, maxRetries, maxRekeyFailures int) { + m.mu.Lock() + defer m.mu.Unlock() + m.maxRetries = maxRetries + m.maxRekeyFailures = maxRekeyFailures +} + +// TestConcurrency_ConcurrentRekeysNoRace hammers both managers with concurrent rotation +// clocks from many goroutines. Its primary job (with -race) is to prove the single-lock +// state machine has no data races or deadlocks under contention; a final deterministic +// bootstrap then asserts there is no split-brain (both sides on the same PSK). +func TestConcurrency_ConcurrentRekeysNoRace(t *testing.T) { + dA, dB, wgA, wgB, _ := pair(t) + defer dA.Stop() + defer dB.Stop() + + bootstrap(t, dA, dB) + + var wg sync.WaitGroup + for g := 0; g < 8; g++ { + wg.Add(1) + go func() { + defer wg.Done() + for i := 0; i < 50; i++ { + dB.OnDataPathRekeyed("aaaa", 0) // initiator chains a rotation + dA.OnDataPathRekeyed("bbbb", 0) // responder side is a no-op, still stresses the lock + } + }() + } + wg.Wait() + + // The storm may leave an exchange mid-flight (concurrent cancellation). Force a + // clean convergence over signalling, then assert no split-brain. + bootstrap(t, dA, dB) + a, b := wgA.psk("bbbb"), wgB.psk("aaaa") + require.NotEqual(t, PSK{}, b) + require.Equal(t, a, b, "both sides converge on the same PSK, no split-brain") +} diff --git a/client/internal/pqkem/convergence.go b/client/internal/pqkem/convergence.go new file mode 100644 index 00000000000..ca90889337a --- /dev/null +++ b/client/internal/pqkem/convergence.go @@ -0,0 +1,396 @@ +package pqkem + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "fmt" + "time" +) + +// idHex renders an exchange ID for logs. +func idHex(id ExchangeID) string { return hex.EncodeToString(id[:]) } + +// exchangeKind labels an exchange for logs by whether it acknowledges a prior one: a +// zero AckID is a bootstrap (a new connection's first exchange, or a re-bootstrap after +// a reconnect), a non-zero AckID is a rotation (a rekey chained off the previous PSK). +func exchangeKind(ackID ExchangeID) string { + if ackID == (ExchangeID{}) { + return "bootstrap" + } + return "rotation" +} + +// viaSignal maps the transport a message arrived on / goes out on to a log label. +const ( + viaSignalLabel = "signal" + viaDataPathLabel = "data-path" +) + +// pskFingerprint is a short, non-secret digest of a derived PSK: identical on both +// peers iff they derived the same key. Logged instead of the raw PSK so debug logs +// never carry the actual WireGuard preshared key. +func pskFingerprint(psk PSK) string { + sum := sha256.Sum256(psk[:]) + return hex.EncodeToString(sum[:8]) +} + +// startExchange creates a fresh initiator exchange (acknowledging ackID, zero for a +// bootstrap) and returns the framed offer for the caller to send — pushed over the +// data path for a chained rekey, or handed to the host for signalling when viaSignal +// is set. Any previous in-flight exchange for the peer is cancelled. +// startExchangeLocked must be called with m.mu held: the caller's idempotency check and +// the exchange install stay under one lock acquisition so two concurrent starts for the +// same peer cannot both create an exchange. It also refuses to start (and to Add to the +// wait group) once the manager is stopping, so it never races Manager.Stop's Wait. +func (m *Manager) startExchangeLocked(remoteID RemoteID, viaSignal bool, ackID ExchangeID) ([]byte, error) { + if m.rootCtx.Err() != nil { + return nil, fmt.Errorf("manager stopping") + } + init, err := NewInitiator() + if err != nil { + return nil, err + } + id, err := newExchangeID() + if err != nil { + return nil, err + } + raw, err := (&OfferMsg{ExchangeID: id, AckID: ackID, KEMOffer: init.Offer()}).Encode() + if err != nil { + return nil, err + } + + ctx, cancel := context.WithCancel(m.rootCtx) + if old := m.exchanges[remoteID]; old != nil && old.cancel != nil { + old.cancel() + } + m.exchanges[remoteID] = &exchangeCtl{ + id: id, + state: stateAwaitingAnswer, + gen: m.nextGenLocked(remoteID), + cancel: cancel, + lastSent: raw, + initiator: init, + viaSignal: viaSignal, + acks: ackID, + } + + m.wait.Add(1) + go m.initiatorLoop(ctx, remoteID, id) + + via := viaDataPathLabel + if viaSignal { + via = viaSignalLabel + } + m.debug("pqkem: sending offer", "peer", remoteID, "exchange", idHex(id), "role", "initiator", "via", via, "kind", exchangeKind(ackID), "acks", idHex(ackID)) + return raw, nil +} + +// processOffer (responder) first acknowledges the previous exchange the offer names +// (that offer riding the data path under the freshly adopted key proves it worked), +// then derives the PSK for the new offer, commits it optimistically, and returns the +// framed answer. A duplicate offer returns the cached answer without re-deriving. +func (m *Manager) processOffer(remoteID RemoteID, o *OfferMsg, via string) ([]byte, error) { + kind := exchangeKind(o.AckID) + m.debug("pqkem: offer received", "peer", remoteID, "exchange", idHex(o.ExchangeID), "role", "responder", "via", via, "kind", kind, "acks", idHex(o.AckID)) + + // Role guard: only the responder processes offers. The KEM is unidirectional — the + // initiator sends offers, the responder answers — so an offer reaching the initiator + // is anomalous (desync, duplicate, or an injected/spoofed packet). Processing it would + // derive and commit a fresh PSK, overwriting a live one and silently discarding any + // in-flight exchange (whose retry loop then exits without recovery). Drop it. + if m.IsInitiator(remoteID) { + m.debug("pqkem: dropping offer, we are the initiator for this peer (role violation)", "peer", remoteID, "exchange", idHex(o.ExchangeID), "via", via, "kind", kind) + return nil, nil + } + + if o.AckID != (ExchangeID{}) { + m.ackConverged(remoteID, o.AckID) + } + + m.mu.Lock() + ex := m.exchanges[remoteID] + if ex != nil && ex.id == o.ExchangeID { + state, last := ex.state, ex.lastSent + m.mu.Unlock() + if state == stateReserved { + return nil, nil + } + m.trace("pqkem: duplicate offer, resending cached answer", "peer", remoteID, "exchange", idHex(o.ExchangeID)) + return last, nil + } + // A data-path chain offer acknowledges the exchange we are awaiting-ack on, and + // ackConverged above deletes that exchange when the ack matches. So if a chain offer + // (non-zero AckID) did NOT match — our current exchange is still here and is a + // different one — it is a rotation a newer signal re-bootstrap has already superseded. + // Drop it, so a late stale offer can't revert us off the new round. A bootstrap + // (zero AckID) is an authoritative fresh start and always proceeds. + if o.AckID != (ExchangeID{}) && ex != nil { + m.mu.Unlock() + m.trace("pqkem: stale chain offer superseded by a newer round, dropping", "peer", remoteID, "exchange", idHex(o.ExchangeID), "acks", idHex(o.AckID)) + return nil, nil + } + // Reserve the slot so a concurrent duplicate offer bails. + m.exchanges[remoteID] = &exchangeCtl{id: o.ExchangeID, state: stateReserved, gen: m.nextGenLocked(remoteID)} + m.mu.Unlock() + + answerBytes, psk, err := Respond(o.KEMOffer, m.binding(remoteID)) + if err != nil { + // Respond failed before the PSK was committed: clear the reservation so a + // retransmission of this offer (a transient or malformed first packet) can retry + // instead of hitting the stuck reserved slot forever. + m.mu.Lock() + if cur := m.exchanges[remoteID]; cur != nil && cur.id == o.ExchangeID && cur.state == stateReserved { + delete(m.exchanges, remoteID) + } + m.mu.Unlock() + return nil, err + } + raw, err := (&AnswerMsg{ExchangeID: o.ExchangeID, KEMAnswer: answerBytes}).Encode() + if err != nil { + return nil, err + } + + m.mu.Lock() + ex = m.exchanges[remoteID] + if ex == nil || ex.id != o.ExchangeID { + m.mu.Unlock() + m.trace("pqkem: exchange superseded during respond, dropping answer", "peer", remoteID, "exchange", idHex(o.ExchangeID)) + return nil, nil + } + ex.state = stateAwaitingAck + ex.lastSent = raw + gen := ex.gen + m.commitPSKLocked(remoteID, psk) + m.capable[remoteID] = true // a real KEM offer proves the peer runs the exchange + m.mu.Unlock() + + m.debug("pqkem: PSK derived", "peer", remoteID, "exchange", idHex(o.ExchangeID), "role", "responder", "via", via, "kind", kind, "psk_fp", pskFingerprint(psk)) + + // Commit optimistically so our data path can rekey to the new PSK. Applying the PSK is + // part of the commit: if the host can't program it, drop the exchange and do NOT send + // the answer, so the initiator times out and re-bootstraps instead of converging on a + // key we could not apply. Route it through the failure path. + if err := m.cbHandler.OnNewPSKReady(remoteID, gen, psk); err != nil { + m.mu.Lock() + if c := m.exchanges[remoteID]; c != nil && c.id == o.ExchangeID { + delete(m.exchanges, remoteID) + } + initial := !m.established[remoteID] + fail := m.registerFailureLocked(remoteID) + m.mu.Unlock() + m.raiseFailure(remoteID, fail, initial) + return nil, err + } + m.trace("pqkem: answer sent", "peer", remoteID, "exchange", idHex(o.ExchangeID)) + return raw, nil +} + +// processAnswer (initiator) derives and commits the PSK and parks in +// stateAwaitingRekey; the next offer (chained from OnDataPathRekeyed) will acknowledge +// this exchange. Only valid in stateAwaitingAnswer; advancing the state under the +// lock makes a concurrent/duplicate answer bail. +func (m *Manager) processAnswer(remoteID RemoteID, a *AnswerMsg, via string) error { + // Role guard: only the initiator processes answers. An answer reaching the responder + // is anomalous (the responder sends answers, it never receives them) — drop it rather + // than let a stray/injected answer disturb the responder's state. + if !m.IsInitiator(remoteID) { + m.debug("pqkem: dropping answer, we are the responder for this peer (role violation)", "peer", remoteID, "answer_for", idHex(a.ExchangeID), "via", via) + return nil + } + + m.mu.Lock() + ex := m.exchanges[remoteID] + if ex == nil || ex.id != a.ExchangeID || ex.state != stateAwaitingAnswer { + haveID := "none" + if ex != nil { + haveID = idHex(ex.id) + } + m.mu.Unlock() + m.trace("pqkem: unexpected answer dropped (inconsistency)", "peer", remoteID, "answer_for", idHex(a.ExchangeID), "have_exchange", haveID, "via", via) + return nil + } + // The initiator's exchange kind: a signalling exchange is a bootstrap/re-bootstrap, a + // data-path one is a rotation chained off the previous PSK. + kind := "rotation" + if ex.viaSignal { + kind = "bootstrap" + } + // Move to an intermediate state while the PSK is being derived: the exchange is not + // committed yet, so OnDataPathRekeyed must not chain the next rotation off it. If we + // advanced straight to stateAwaitingRekey, a rekey firing before Finish returns would + // let the responder commit PSK N+1 before this side commits PSK N. + ex.state = stateFinishing + init := ex.initiator + ex.initiator = nil + m.mu.Unlock() + + m.trace("pqkem: answer received", "peer", remoteID, "exchange", idHex(a.ExchangeID), "via", via, "kind", kind) + + psk, err := init.Finish(a.KEMAnswer, m.binding(remoteID)) + if err != nil { + // Finish failed: drop the exchange and raise the failure so recovery re-bootstraps + // (the responder already committed its PSK in processOffer, so the peers are split). + m.mu.Lock() + if cur := m.exchanges[remoteID]; cur != nil && cur.id == a.ExchangeID { + delete(m.exchanges, remoteID) + } + initial := !m.established[remoteID] + fail := m.registerFailureLocked(remoteID) + m.mu.Unlock() + m.raiseFailure(remoteID, fail, initial) + return err + } + + // Commit only if the exchange we were finishing is still current: a supersede (a signal + // re-bootstrap) could have replaced it while Finish ran, in which case this PSK is stale. + m.mu.Lock() + cur := m.exchanges[remoteID] + if cur == nil || cur.id != a.ExchangeID || cur.state != stateFinishing { + m.mu.Unlock() + m.trace("pqkem: exchange superseded during finish, dropping PSK", "peer", remoteID, "exchange", idHex(a.ExchangeID)) + return nil + } + wasEstablished := m.established[remoteID] + gen := cur.gen + cur.state = stateAwaitingRekey + m.established[remoteID] = true + m.failures[remoteID] = 0 + m.commitPSKLocked(remoteID, psk) + m.capable[remoteID] = true // a real KEM answer proves the peer runs the exchange + m.mu.Unlock() + + m.debug("pqkem: PSK derived", "peer", remoteID, "exchange", idHex(a.ExchangeID), "role", "initiator", "via", via, "kind", kind, "psk_fp", pskFingerprint(psk)) + + if err := m.cbHandler.OnNewPSKReady(remoteID, gen, psk); err != nil { + // Applying the PSK is part of the commit: if the host fails to program it, the + // exchange is not really converged. Drop it and route the failure through recovery + // so a re-bootstrap re-derives and re-applies, instead of leaving the peer parked + // in awaitingRekey on a key the data path never adopted. + m.mu.Lock() + if c := m.exchanges[remoteID]; c != nil && c.id == a.ExchangeID { + delete(m.exchanges, remoteID) + } + fail := m.registerFailureLocked(remoteID) + m.mu.Unlock() + m.raiseFailure(remoteID, fail, !wasEstablished) + return err + } + return nil +} + +// ackConverged (responder) records convergence of the exchange named by ackID: a +// later offer acknowledging it proves both sides operate on that exchange's key. Only +// acts on a matching stateAwaitingAck exchange; anything else is ignored. +func (m *Manager) ackConverged(remoteID RemoteID, ackID ExchangeID) { + m.mu.Lock() + ex := m.exchanges[remoteID] + if ex == nil || ex.id != ackID || ex.state != stateAwaitingAck { + m.mu.Unlock() + m.trace("pqkem: ack for unknown/mismatched exchange, ignored (inconsistency)", "peer", remoteID, "acks", idHex(ackID)) + return + } + delete(m.exchanges, remoteID) + m.established[remoteID] = true + m.failures[remoteID] = 0 + m.mu.Unlock() + + m.trace("pqkem: previous exchange confirmed by ack", "peer", remoteID, "exchange", idHex(ackID)) +} + +// initiatorLoop enforces the offer->answer convergence deadline and retransmits the +// initiator's outstanding data-path offer while awaiting the answer (a +// signalling-bootstrapped offer is retransmitted by the host, so it is not resent +// here). Exhausting the deadline before the answer arrives is a failure. Once the +// answer is in (state past awaitingAnswer) the loop exits: the next rotation is driven +// by OnDataPathRekeyed, and the idle wait for it has no deadline. +func (m *Manager) initiatorLoop(ctx context.Context, remoteID RemoteID, id ExchangeID) { + defer m.wait.Done() + t := time.NewTicker(m.retryInterval) + defer t.Stop() + + attempts := 0 + for { + select { + case <-ctx.Done(): + return + case <-t.C: + m.mu.Lock() + ex := m.exchanges[remoteID] + if ex == nil || ex.id != id { + m.mu.Unlock() + return + } + + switch ex.state { + case stateAwaitingAnswer: + if attempts >= m.maxRetries { + delete(m.exchanges, remoteID) + // A timed-out rotation hands the chain back to the exchange it + // acknowledged, so the next data-path rekey starts a new rotation. + // Without it rotation stops until the next Signal re-bootstrap. + if ex.acks != (ExchangeID{}) { + m.exchanges[remoteID] = &exchangeCtl{id: ex.acks, state: stateAwaitingRekey} + } + initial := !m.established[remoteID] + fail := m.registerFailureLocked(remoteID) + m.mu.Unlock() + m.raiseFailure(remoteID, fail, initial) + return + } + viaSignal := ex.viaSignal + msg := ex.lastSent + attempts++ + m.mu.Unlock() + if !viaSignal { + if err := m.pushDataPath(remoteID, msg); err != nil { + m.logger.Warn("pqkem: offer retransmit failed", "peer", remoteID, "err", err) + } + } + + default: + // Past awaiting the answer (converged) or superseded: the loop's job + // is done. The next rotation is driven externally by OnDataPathRekeyed, + // so there is no deadline while idle-waiting for it (that wait can be + // as long as the transport's natural rekey interval). + m.mu.Unlock() + return + } + } + } +} + +// registerFailureLocked applies policy B and reports whether OnRekeyFailed is due: +// an initial exchange (peer never established) fails immediately; a rekey tolerates +// up to maxRekeyFailures consecutive misses (we stay on the still-valid previous +// PSK) before failing. Assumes m.mu is held. +func (m *Manager) registerFailureLocked(remoteID RemoteID) bool { + if !m.established[remoteID] { + return true + } + m.failures[remoteID]++ + if m.failures[remoteID] >= m.maxRekeyFailures { + m.failures[remoteID] = 0 + return true + } + return false +} + +// raiseFailure reports a convergence failure. initial distinguishes a never-established +// peer (bootstrap failed → no PQ PSK at all; in strict mode the peer stays blocked = +// "stuck") from a rekey failure (a previous PSK is still in force and traffic continues). +func (m *Manager) raiseFailure(remoteID RemoteID, fail, initial bool) { + if !fail { + m.logger.Warn("pqkem: rekey attempt timed out, will retry next cycle", "peer", remoteID) + return + } + if initial { + // Debug: an offline peer's bootstrap ends here too. The host knows if it was reachable. + m.debug("pqkem: initial exchange failed, no PQ PSK established for peer", "peer", remoteID) + } else { + m.logger.Warn("pqkem: rekey failed after retries — staying on the previous PSK", "peer", remoteID) + } + if err := m.cbHandler.OnRekeyFailed(remoteID); err != nil { + m.logger.Error("pqkem: OnRekeyFailed handler error", "peer", remoteID, "err", err) + } +} diff --git a/client/internal/pqkem/convergence_test.go b/client/internal/pqkem/convergence_test.go new file mode 100644 index 00000000000..14c4d2532e8 --- /dev/null +++ b/client/internal/pqkem/convergence_test.go @@ -0,0 +1,100 @@ +package pqkem + +import ( + "net/netip" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// dropTransport is a pqkem.Transport that silently discards everything. +type dropTransport struct{} + +func (dropTransport) Send(netip.AddrPort, []byte) error { return nil } +func (dropTransport) LocalPort() int { return 0 } +func (dropTransport) Run(func(netip.AddrPort, []byte)) {} +func (dropTransport) Close() error { return nil } + +func failedCount(f *fakeWG) int { + f.mu.Lock() + defer f.mu.Unlock() + return len(f.failed) +} + +func TestManager_InitialTimeoutFailsImmediately(t *testing.T) { + wg := newFakeWG() + d := NewManager("bbbb", wg, nil) // bbbb > aaaa -> initiator + d.Start(dropTransport{}) + d.retryInterval = 5 * time.Millisecond + d.maxRetries = 3 + defer d.Stop() + + // Bootstrap offer is produced for signalling; no answer ever comes back -> the + // initial exchange fails fast. + offer, err := d.SignalOffer("aaaa") + require.NoError(t, err) + require.NotNil(t, offer) + + assert.Eventually(t, func() bool { return failedCount(wg) == 1 }, time.Second, 5*time.Millisecond) +} + +func TestManager_RekeyToleratesKFailures(t *testing.T) { + dA, dB, _, wgB, lbB := pair(t) + defer dA.Stop() + defer dB.Stop() + + // Tighten B's timings before any exchange loop spawns (the loop reads these + // fields, so writing them after a loop is running would race). + dB.retryInterval = 5 * time.Millisecond + dB.maxRetries = 2 + + // Establish: bootstrap + data-path-rekeyed so B becomes established and its data + // path is usable. + bootstrap(t, dA, dB) + dA.OnDataPathRekeyed("bbbb", 0) + dB.OnDataPathRekeyed("aaaa", 0) + require.NotEqual(t, PSK{}, wgB.psk("aaaa")) + + // Drop B's outbound so rekeys can no longer converge. + lbB.drop.Store(true) + + // K-1 data-path rekeys must NOT raise OnRekeyFailed. + for i := 0; i < DefaultMaxRekeyFailures-1; i++ { + _, err := dB.startExchangeTest("aaaa", false, ExchangeID{}) + require.NoError(t, err) + time.Sleep(50 * time.Millisecond) + } + assert.Equal(t, 0, failedCount(wgB), "no failure before K attempts") + + // The K-th failure raises it once. + _, err := dB.startExchangeTest("aaaa", false, ExchangeID{}) + require.NoError(t, err) + assert.Eventually(t, func() bool { return failedCount(wgB) == 1 }, time.Second, 5*time.Millisecond) +} + +// TestManager_InitiatorRejectsOfferFromResponderRole verifies the role guard: an offer +// reaching the peer that is the initiator (here dB) must be dropped, not adopted — else a +// stray/injected offer would overwrite the live PSK and silently drop any in-flight +// exchange. dA (the role-responder) crafts an offer and injects it into dB (the initiator). +func TestManager_InitiatorRejectsOfferFromResponderRole(t *testing.T) { + dA, dB, _, wgB, _ := pair(t) // dB ("bbbb") is the initiator, dA ("aaaa") the responder + defer dA.Stop() + defer dB.Stop() + + bootstrap(t, dA, dB) + psk1 := wgB.psk("aaaa") + require.NotEqual(t, PSK{}, psk1, "bootstrap established a PSK") + + // Authenticated (sealed under the shared PSK) and shaped as a rotation, so only the + // role guard can stop it. + ack, err := newExchangeID() + require.NoError(t, err) + rogue, err := dA.startExchangeTest("bbbb", false, ack) + require.NoError(t, err) + require.NoError(t, dB.OnDataPathMessage("aaaa", sealForPeer(t, dA, "bbbb", rogue))) + + assert.Equal(t, psk1, wgB.psk("aaaa"), + "the initiator must not adopt a PSK from an offer sent by the role-responder") +} diff --git a/client/internal/pqkem/datapath_auth.go b/client/internal/pqkem/datapath_auth.go new file mode 100644 index 00000000000..fdd0fad8e2f --- /dev/null +++ b/client/internal/pqkem/datapath_auth.go @@ -0,0 +1,48 @@ +package pqkem + +import ( + "crypto/hkdf" + "crypto/hmac" + "crypto/sha256" + "fmt" +) + +// dataPathMACLabel separates the data-path MAC key from the PSK the consumer programs +// into its channel, so the same secret never serves two purposes directly. +const dataPathMACLabel = "netbird-pq-datapath-mac-v1" + +// dataPathTagSize is the length of the HMAC-SHA256 tag appended to every data-path frame. +const dataPathTagSize = sha256.Size + +// dataPathMACKey derives the key that authenticates data-path messages from a PSK both +// peers hold. +func dataPathMACKey(psk PSK) ([]byte, error) { + key, err := hkdf.Key(sha256.New, psk[:], nil, dataPathMACLabel, sha256.Size) + if err != nil { + return nil, fmt.Errorf("derive data-path mac key: %w", err) + } + return key, nil +} + +// sealDataPath appends the frame's HMAC-SHA256 tag under key. +func sealDataPath(key, frame []byte) []byte { + mac := hmac.New(sha256.New, key) + mac.Write(frame) + sealed := make([]byte, 0, len(frame)+dataPathTagSize) + sealed = append(sealed, frame...) + return mac.Sum(sealed) +} + +// openDataPath verifies a sealed frame under key and returns the frame without its tag. +func openDataPath(key, sealed []byte) ([]byte, bool) { + if len(sealed) < dataPathTagSize { + return nil, false + } + frame, tag := sealed[:len(sealed)-dataPathTagSize], sealed[len(sealed)-dataPathTagSize:] + mac := hmac.New(sha256.New, key) + mac.Write(frame) + if !hmac.Equal(tag, mac.Sum(nil)) { + return nil, false + } + return frame, true +} diff --git a/client/internal/pqkem/datapath_auth_test.go b/client/internal/pqkem/datapath_auth_test.go new file mode 100644 index 00000000000..b1cf42aa9ea --- /dev/null +++ b/client/internal/pqkem/datapath_auth_test.go @@ -0,0 +1,137 @@ +package pqkem + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// sealForPeer seals a data-path frame under the PSK m currently shares with remoteID, as +// a genuine sender would. +func sealForPeer(t *testing.T, m *Manager, remoteID RemoteID, frame []byte) []byte { + t.Helper() + psk, ok := m.PSK(remoteID) + require.True(t, ok, "sealing needs an established PSK") + key, err := dataPathMACKey(psk) + require.NoError(t, err) + return sealDataPath(key, frame) +} + +func TestDataPathSealOpen(t *testing.T) { + key, err := dataPathMACKey(PSK{1}) + require.NoError(t, err) + otherKey, err := dataPathMACKey(PSK{2}) + require.NoError(t, err) + frame := []byte("kem frame") + + sealed := sealDataPath(key, frame) + got, ok := openDataPath(key, sealed) + require.True(t, ok, "a frame sealed under the key must open") + assert.Equal(t, frame, got, "opening must return the original frame") + + _, ok = openDataPath(otherKey, sealed) + assert.False(t, ok, "a different key must not open the frame") + + tampered := append([]byte(nil), sealed...) + tampered[0] ^= 0x01 + _, ok = openDataPath(key, tampered) + assert.False(t, ok, "a modified frame must not open") + + _, ok = openDataPath(key, sealed[:dataPathTagSize-1]) + assert.False(t, ok, "a datagram shorter than a tag must not open") +} + +// TestManager_DataPathRejectsAuthenticatedBootstrap verifies a bootstrap is never taken +// from the data path, even with a valid MAC: the data path only carries rotations of an +// exchange that signalling already established. +func TestManager_DataPathRejectsAuthenticatedBootstrap(t *testing.T) { + dA, dB, wgA, _, _ := pair(t) + defer dA.Stop() + defer dB.Stop() + + bootstrap(t, dA, dB) + psk := wgA.psk("bbbb") + + require.NoError(t, dA.OnDataPathMessage("bbbb", sealForPeer(t, dA, "bbbb", forgedOffer(t, ExchangeID{})))) + + assert.Equal(t, psk, wgA.psk("bbbb"), "a bootstrap offer over the data path must be dropped") +} + +// TestManager_DataPathRetransmitAfterCommitIsAnswered covers a lost answer. The responder +// commits the rotated PSK when it answers, so the initiator's retransmission, still sealed +// under the previous PSK, must be accepted under that key and answered, or the two peers +// never converge. +func TestManager_DataPathRetransmitAfterCommitIsAnswered(t *testing.T) { + sw := newSwitch() + wgA, wgB := newFakeWG(), newFakeWG() + dA := NewManager("aaaa", wgA, nil) // responder + dB := NewManager("bbbb", wgB, nil) // initiator + dB.retryInterval = 20 * time.Millisecond + lbA := &loopback{ep: epA, sw: sw} + dA.Start(lbA) + dB.Start(&loopback{ep: epB, sw: sw}) + dA.AddPeer("bbbb", epB) + dB.AddPeer("aaaa", epA) + defer dA.Stop() + defer dB.Stop() + + bootstrap(t, dA, dB) + boot := wgB.psk("aaaa") + + lbA.drop.Store(true) // lose the responder's answers + dB.OnDataPathRekeyed("aaaa", 0) + require.Eventually(t, func() bool { return wgA.psk("bbbb") != boot }, time.Second, 5*time.Millisecond, + "the responder must commit the rotated PSK") + lbA.drop.Store(false) + + require.Eventually(t, func() bool { return wgB.psk("aaaa") == wgA.psk("bbbb") }, 2*time.Second, 5*time.Millisecond, + "the retransmitted offer must be answered so both peers converge") +} + +// forgedOffer builds a well-formed KEM offer that no peer authenticated: fresh KEM +// material, the given AckID, and no data-path MAC. +func forgedOffer(t *testing.T, ack ExchangeID) []byte { + t.Helper() + ini, err := NewInitiator() + require.NoError(t, err) + id, err := newExchangeID() + require.NoError(t, err) + raw, err := (&OfferMsg{ExchangeID: id, AckID: ack, KEMOffer: ini.Offer()}).Encode() + require.NoError(t, err) + return raw +} + +// TestManager_DataPathRejectsForgedOffer covers spoofed data-path datagrams. The data-path +// socket only knows the sender by source IP:port, and on a host-bound socket a datagram +// with a spoofed source can arrive from a physical interface rather than the tunnel. An +// unauthenticated offer must not re-key the responder: a forged bootstrap (zero AckID) +// used to be adopted, desynchronising the peers' PSKs. A guessed AckID is covered too. +func TestManager_DataPathRejectsForgedOffer(t *testing.T) { + guessed, err := newExchangeID() + require.NoError(t, err) + cases := map[string]ExchangeID{ + "forged bootstrap (zero AckID)": {}, + "forged rotation (guessed AckID)": guessed, + } + for name, ack := range cases { + t.Run(name, func(t *testing.T) { + dA, dB, wgA, _, _ := pair(t) // dB ("bbbb") initiator, dA ("aaaa") responder + defer dA.Stop() + defer dB.Stop() + + bootstrap(t, dA, dB) + psk := wgA.psk("bbbb") + require.NotEqual(t, PSK{}, psk, "bootstrap must establish a PSK") + + // Spoofed: it arrives from the initiator's registered data-path endpoint. + dA.onDataPathInbound(epB, forgedOffer(t, ack)) + + assert.Equal(t, psk, wgA.psk("bbbb"), "a forged data-path offer must not re-key the responder") + current, ok := dA.PSK("bbbb") + require.True(t, ok) + assert.Equal(t, psk, current, "the responder's stored PSK must be unchanged") + }) + } +} diff --git a/client/internal/pqkem/env.go b/client/internal/pqkem/env.go new file mode 100644 index 00000000000..ea6f4aed8c1 --- /dev/null +++ b/client/internal/pqkem/env.go @@ -0,0 +1,147 @@ +package pqkem + +import ( + "context" + "log/slog" + "os" + "strconv" + "strings" + + log "github.com/sirupsen/logrus" +) + +// EnvEnabled is the environment variable that turns the ML-KEM post-quantum +// exchange on for this client. Accepts on/off aliases plus anything +// strconv.ParseBool understands (true/false/1/0). +const EnvEnabled = "NB_ENABLE_PQ_MLKEM" + +// Enabled reports whether the ML-KEM PQ exchange is enabled via the environment. +// An empty or unrecognized value is treated as disabled. +func Enabled() bool { + raw := strings.ToLower(strings.TrimSpace(os.Getenv(EnvEnabled))) + switch raw { + case "": + return false + case "on": + return true + case "off": + return false + } + enabled, err := strconv.ParseBool(raw) + if err != nil { + log.Warnf("failed to parse %s value %q: %v", EnvEnabled, raw, err) + return false + } + return enabled +} + +// EnvStrict enables strict (fail-closed) mode: block peer traffic until the ML-KEM +// PSK has been established, instead of the default opportunistic behaviour that lets +// the tunnel come up classically and upgrades to PQ once the exchange converges. +const EnvStrict = "NB_PQ_MLKEM_STRICT" + +// Strict reports whether strict (fail-closed) mode is enabled via the environment. +// An empty or unrecognized value is treated as disabled (opportunistic). +func Strict() bool { + raw := strings.ToLower(strings.TrimSpace(os.Getenv(EnvStrict))) + switch raw { + case "on": + return true + case "", "off": + return false + } + enabled, err := strconv.ParseBool(raw) + if err != nil { + log.Warnf("failed to parse %s value %q: %v", EnvStrict, raw, err) + return false + } + return enabled +} + +// EnvLogLevel overrides the ML-KEM manager's slog level (trace/debug/info/warn/error). +// Defaults to info. The verbose per-exchange lifecycle logs are emitted at trace. +const EnvLogLevel = "NB_PQ_MLKEM_LOG_LEVEL" + +// LevelTrace is a custom slog level below Debug for the verbose per-exchange lifecycle +// logs, so they stay off unless NB_PQ_MLKEM_LOG_LEVEL=trace (and the daemon log level +// is trace, since the records are forwarded to logrus). +const LevelTrace = slog.LevelDebug - 4 + +// NewLogger builds the slog logger for the ML-KEM manager. It forwards records to +// logrus so PQ logs land in the same sink as the rest of the daemon (console + +// client.log) rather than stdout. Verbosity is gated by EnvLogLevel. +func NewLogger() *slog.Logger { + return slog.New(slogToLogrus{}) +} + +func logLevel() slog.Level { + switch strings.ToLower(strings.TrimSpace(os.Getenv(EnvLogLevel))) { + case "trace": + return LevelTrace + case "debug": + return slog.LevelDebug + case "warn": + return slog.LevelWarn + case "error": + return slog.LevelError + default: + return slog.LevelInfo + } +} + +// slogToLogrus is a slog.Handler that forwards records to logrus, so the ML-KEM +// manager's logs go wherever the daemon's logrus is configured (console + client.log) +// instead of stdout. Verbosity is gated by EnvLogLevel via logLevel(). +type slogToLogrus struct { + fields log.Fields + prefix string // open-group path (e.g. "a.b."), prepended to attribute keys +} + +func (h slogToLogrus) Enabled(_ context.Context, level slog.Level) bool { + return level >= logLevel() +} + +func (h slogToLogrus) Handle(_ context.Context, r slog.Record) error { + fields := make(log.Fields, len(h.fields)+r.NumAttrs()) + for k, v := range h.fields { + fields[k] = v + } + r.Attrs(func(a slog.Attr) bool { + fields[h.prefix+a.Key] = a.Value.Any() + return true + }) + entry := log.WithFields(fields) + switch { + case r.Level >= slog.LevelError: + entry.Error(r.Message) + case r.Level >= slog.LevelWarn: + entry.Warn(r.Message) + case r.Level >= slog.LevelInfo: + entry.Info(r.Message) + case r.Level >= slog.LevelDebug: + entry.Debug(r.Message) + default: + entry.Trace(r.Message) + } + return nil +} + +func (h slogToLogrus) WithAttrs(attrs []slog.Attr) slog.Handler { + fields := make(log.Fields, len(h.fields)+len(attrs)) + for k, v := range h.fields { + fields[k] = v + } + for _, a := range attrs { + fields[h.prefix+a.Key] = a.Value.Any() + } + return slogToLogrus{fields: fields, prefix: h.prefix} +} + +// WithGroup opens a nested namespace: subsequent attributes are keyed under the group +// path (joined with "."). An empty name is a no-op, per the slog contract. +func (h slogToLogrus) WithGroup(name string) slog.Handler { + if name == "" { + return h + } + return slogToLogrus{fields: h.fields, prefix: h.prefix + name + "."} +} diff --git a/client/internal/pqkem/env_test.go b/client/internal/pqkem/env_test.go new file mode 100644 index 00000000000..6af943eb8e8 --- /dev/null +++ b/client/internal/pqkem/env_test.go @@ -0,0 +1,58 @@ +package pqkem + +import ( + "os" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestEnvFlags(t *testing.T) { + cases := []struct { + value string + want bool + }{ + {"", false}, + {"on", true}, + {"ON", true}, + {" on ", true}, + {"off", false}, + {"Off", false}, + {"true", true}, + {"TRUE", true}, + {"1", true}, + {"t", true}, + {"false", false}, + {"0", false}, + {" 1 ", true}, + {"yes", false}, + {"garbage", false}, + } + + flags := []struct { + env string + get func() bool + }{ + {EnvEnabled, Enabled}, + {EnvStrict, Strict}, + } + + for _, f := range flags { + for _, c := range cases { + t.Run(f.env+"="+c.value, func(t *testing.T) { + t.Setenv(f.env, c.value) + assert.Equal(t, c.want, f.get(), "%s=%q", f.env, c.value) + }) + } + } +} + +func TestEnvFlagsUnset(t *testing.T) { + for _, env := range []string{EnvEnabled, EnvStrict} { + t.Setenv(env, "") + require.NoError(t, os.Unsetenv(env)) + } + assert.False(t, Enabled(), "an unset %s must leave ML-KEM disabled", EnvEnabled) + assert.False(t, Strict(), "an unset %s must leave strict mode off", EnvStrict) +} diff --git a/client/internal/pqkem/kem.go b/client/internal/pqkem/kem.go new file mode 100644 index 00000000000..54de4dda393 --- /dev/null +++ b/client/internal/pqkem/kem.go @@ -0,0 +1,191 @@ +// Package pqkem is a spike (NET-1406) for a post-quantum pre-shared-key exchange +// that could replace Rosenpass. It performs an X25519MLKEM768 hybrid key +// encapsulation and derives a 32-byte pre-shared key (PSK). +// +// The exchange is a single round trip designed to ride the (already +// authenticated) Signal offer/answer channel: +// +// initiator --Offer(1216B)--> responder +// initiator <--Answer(1120B)-- responder +// +// Both sides then hold the same PSK, which is bound to the two peers' identities +// (their peer identity keys) so the derived key cannot be transplanted +// to a different peer pair even if the transport authentication were bypassed. +// +// Combiner note: this follows draft-ietf-tls-ecdhe-mlkem for X25519MLKEM768 — on +// the wire ML-KEM ‖ X25519 (the draft deliberately reversed the share order for +// this group), and ML-KEM_ss ‖ X25519_ss as the KDF input. The PSK is derived with +// HKDF-SHA256 over that hybrid secret (plus an optional pre-shared secret both peers +// hold), salted with a domain-separation label and bound (via the HKDF info) to the +// full transcript and the canonicalised peer identities. +package pqkem + +import ( + "crypto/ecdh" + "crypto/hkdf" + "crypto/mlkem" + "crypto/rand" + "crypto/sha256" + "fmt" +) + +const ( + // OfferSize is the initiator message: ML-KEM-768 encapsulation key ‖ X25519 public key + // (share order per draft-ietf-tls-ecdhe-mlkem for X25519MLKEM768). + OfferSize = mlkem.EncapsulationKeySize768 + 32 // 1216 + // AnswerSize is the responder message: ML-KEM-768 ciphertext ‖ X25519 public key. + AnswerSize = mlkem.CiphertextSize768 + 32 // 1120 + + pskLabel = "netbird-pq-psk-v1" +) + +// PSK is the 32-byte derived pre-shared key handed to the consumer to key its channel. +type PSK [32]byte + +// Binding identifies the peer pair the PSK is derived for. Callers set both +// peer identity keys; the order does not matter (it is canonicalised). +type Binding struct { + LocalID []byte + RemoteID []byte + // Secret is an optional pre-shared secret both peers must hold. It is mixed into the + // derivation, so peers holding different secrets (or only one holding one) derive + // different PSKs and the consumer's channel fails closed. + Secret []byte +} + +// Initiator holds the ephemeral secrets between Offer and Finish. +type Initiator struct { + x25519 *ecdh.PrivateKey + mlkemDK *mlkem.DecapsulationKey768 + offer []byte +} + +// NewInitiator generates the ephemeral X25519 + ML-KEM-768 keypairs. +func NewInitiator() (*Initiator, error) { + x, err := ecdh.X25519().GenerateKey(rand.Reader) + if err != nil { + return nil, fmt.Errorf("x25519 keygen: %w", err) + } + dk, err := mlkem.GenerateKey768() + if err != nil { + return nil, fmt.Errorf("ml-kem keygen: %w", err) + } + + offer := make([]byte, 0, OfferSize) + offer = append(offer, dk.EncapsulationKey().Bytes()...) + offer = append(offer, x.PublicKey().Bytes()...) + + return &Initiator{x25519: x, mlkemDK: dk, offer: offer}, nil +} + +// Offer returns the initiator message to send over Signal. +func (i *Initiator) Offer() []byte { + return i.offer +} + +// Finish consumes the responder's answer and derives the PSK. +func (i *Initiator) Finish(answer []byte, b Binding) (PSK, error) { + if len(answer) != AnswerSize { + return PSK{}, fmt.Errorf("answer: got %d bytes, want %d", len(answer), AnswerSize) + } + ct := answer[:mlkem.CiphertextSize768] + peerX := answer[mlkem.CiphertextSize768:] + + ssMLKEM, err := i.mlkemDK.Decapsulate(ct) + if err != nil { + return PSK{}, fmt.Errorf("ml-kem decapsulate: %w", err) + } + pub, err := ecdh.X25519().NewPublicKey(peerX) + if err != nil { + return PSK{}, fmt.Errorf("parse peer x25519: %w", err) + } + ssX, err := i.x25519.ECDH(pub) + if err != nil { + return PSK{}, fmt.Errorf("x25519 ecdh: %w", err) + } + + return derivePSK(ssMLKEM, ssX, i.offer, answer, b) +} + +// Respond consumes an initiator offer, produces the answer, and derives the PSK. +func Respond(offer []byte, b Binding) (answer []byte, psk PSK, err error) { + if len(offer) != OfferSize { + return nil, PSK{}, fmt.Errorf("offer: got %d bytes, want %d", len(offer), OfferSize) + } + peerEK := offer[:mlkem.EncapsulationKeySize768] + peerX := offer[mlkem.EncapsulationKeySize768:] + + ek, err := mlkem.NewEncapsulationKey768(peerEK) + if err != nil { + return nil, PSK{}, fmt.Errorf("parse peer ml-kem key: %w", err) + } + ssMLKEM, ct := ek.Encapsulate() + + x, err := ecdh.X25519().GenerateKey(rand.Reader) + if err != nil { + return nil, PSK{}, fmt.Errorf("x25519 keygen: %w", err) + } + pub, err := ecdh.X25519().NewPublicKey(peerX) + if err != nil { + return nil, PSK{}, fmt.Errorf("parse peer x25519: %w", err) + } + ssX, err := x.ECDH(pub) + if err != nil { + return nil, PSK{}, fmt.Errorf("x25519 ecdh: %w", err) + } + + answer = make([]byte, 0, AnswerSize) + answer = append(answer, ct...) + answer = append(answer, x.PublicKey().Bytes()...) + + // derivePSK uses the same argument order on both sides; the responder's local + // binding is the mirror of the initiator's, canonicalised inside derivePSK. + psk, err = derivePSK(ssMLKEM, ssX, offer, answer, b) + if err != nil { + return nil, PSK{}, err + } + return answer, psk, nil +} + +// derivePSK runs HKDF-SHA256 over the hybrid shared secret (ML-KEM_ss ‖ X25519_ss, +// per draft-ietf-tls-ecdhe-mlkem) plus the binding's optional pre-shared secret, salted +// with the domain-separation label, and binds the result — via the HKDF info — to the +// full transcript (offer ‖ answer) and the canonicalised peer identities, so the PSK +// cannot be transplanted to another peer pair or a different exchange. +func derivePSK(ssMLKEM, ssX, offer, answer []byte, b Binding) (PSK, error) { + // A PSK not bound to both peer identities could be transplanted to a different peer + // pair, so refuse to derive one from an empty binding. + if len(b.LocalID) == 0 || len(b.RemoteID) == 0 { + return PSK{}, fmt.Errorf("empty peer identity binding") + } + lo, hi := canonicalPair(b.LocalID, b.RemoteID) + + // The shared secrets have fixed lengths, so appending the optional pre-shared secret + // after them keeps the input unambiguous. It sits in the keying material rather than + // the info, so a peer without it cannot derive the PSK at all. + ikm := make([]byte, 0, len(ssMLKEM)+len(ssX)+len(b.Secret)) + ikm = append(ikm, ssMLKEM...) + ikm = append(ikm, ssX...) + ikm = append(ikm, b.Secret...) + + info := make([]byte, 0, len(offer)+len(answer)+len(lo)+len(hi)) + info = append(info, offer...) + info = append(info, answer...) + info = append(info, lo...) + info = append(info, hi...) + + var psk PSK + key, err := hkdf.Key(sha256.New, ikm, []byte(pskLabel), string(info), len(psk)) + if err != nil { + return PSK{}, fmt.Errorf("hkdf derive psk: %w", err) + } + copy(psk[:], key) + return psk, nil +} + +func canonicalPair(a, b []byte) (lo, hi []byte) { + if string(a) <= string(b) { + return a, b + } + return b, a +} diff --git a/client/internal/pqkem/kem_framing_test.go b/client/internal/pqkem/kem_framing_test.go new file mode 100644 index 00000000000..771df0ca959 --- /dev/null +++ b/client/internal/pqkem/kem_framing_test.go @@ -0,0 +1,105 @@ +package pqkem + +import ( + "crypto/mlkem" + "testing" + + "github.com/stretchr/testify/require" +) + +// TestExchange_TamperedCiphertextFailsClosed verifies the core fail-closed +// property: mutating the ML-KEM ciphertext in the answer does not error (ML-KEM +// uses implicit rejection — Decapsulate always returns a value) but yields a +// different shared secret, so the initiator derives a PSK that does NOT match the +// responder's. A mismatched PSK means WireGuard passes no bytes: tamper => no data. +func TestExchange_TamperedCiphertextFailsClosed(t *testing.T) { + init, err := NewInitiator() + require.NoError(t, err) + + answer, pskB, err := Respond(init.Offer(), Binding{LocalID: wgB, RemoteID: wgA}) + require.NoError(t, err) + + tampered := append([]byte(nil), answer...) + tampered[0] ^= 0xff // flip a bit in the ML-KEM ciphertext + + pskA, err := init.Finish(tampered, Binding{LocalID: wgA, RemoteID: wgB}) + require.NoError(t, err, "implicit rejection: decapsulate still succeeds") + require.NotEqual(t, pskB, pskA, "tampered ciphertext must not yield the responder's PSK") +} + +// TestExchange_TamperedX25519ShareDiverges flips a byte in the answer's X25519 +// share: the classical half of the hybrid secret changes, so the derived PSK +// diverges from the responder's (fail-closed on the ECDH half too). +func TestExchange_TamperedX25519ShareDiverges(t *testing.T) { + init, err := NewInitiator() + require.NoError(t, err) + + answer, pskB, err := Respond(init.Offer(), Binding{LocalID: wgB, RemoteID: wgA}) + require.NoError(t, err) + + tampered := append([]byte(nil), answer...) + tampered[mlkem.CiphertextSize768] ^= 0x01 // first byte of the X25519 public key + + pskA, err := init.Finish(tampered, Binding{LocalID: wgA, RemoteID: wgB}) + // Either the point is rejected (error) or the ECDH differs (different PSK); + // in both cases the honest PSK is never reproduced. + if err == nil { + require.NotEqual(t, pskB, pskA, "tampered X25519 share must not yield the responder's PSK") + } +} + +// TestExchange_AllZeroX25519Rejected feeds an all-zero X25519 share (a low-order +// point) in the answer. The stdlib ECDH must reject it, so Finish errors rather +// than deriving a PSK from a degenerate secret. +func TestExchange_AllZeroX25519Rejected(t *testing.T) { + init, err := NewInitiator() + require.NoError(t, err) + + answer, _, err := Respond(init.Offer(), Binding{LocalID: wgB, RemoteID: wgA}) + require.NoError(t, err) + + bad := append([]byte(nil), answer...) + for i := mlkem.CiphertextSize768; i < len(bad); i++ { + bad[i] = 0 + } + + _, err = init.Finish(bad, Binding{LocalID: wgA, RemoteID: wgB}) + require.Error(t, err, "all-zero X25519 share (low-order point) must be rejected") +} + +// TestExchange_SizeBoundaries locks the exact-length framing checks: one byte +// short or long on either message is rejected, not silently truncated/padded. +func TestExchange_SizeBoundaries(t *testing.T) { + init, err := NewInitiator() + require.NoError(t, err) + offer := init.Offer() + + _, _, err = Respond(offer[:OfferSize-1], Binding{}) + require.Error(t, err, "offer one byte short") + _, _, err = Respond(append(append([]byte(nil), offer...), 0), Binding{}) + require.Error(t, err, "offer one byte long") + + answer, _, err := Respond(offer, Binding{LocalID: wgB, RemoteID: wgA}) + require.NoError(t, err) + + _, err = init.Finish(answer[:AnswerSize-1], Binding{LocalID: wgA, RemoteID: wgB}) + require.Error(t, err, "answer one byte short") + _, err = init.Finish(append(append([]byte(nil), answer...), 0), Binding{LocalID: wgA, RemoteID: wgB}) + require.Error(t, err, "answer one byte long") +} + +// TestExchange_BindingIsSymmetric confirms the canonicalisation: the two peers +// pass their identities in opposite (Local, Remote) order yet derive the same PSK, +// so identity binding does not depend on who is initiator vs responder. +func TestExchange_BindingIsSymmetric(t *testing.T) { + init, err := NewInitiator() + require.NoError(t, err) + + answer, pskB, err := Respond(init.Offer(), Binding{LocalID: wgB, RemoteID: wgA}) + require.NoError(t, err) + + pskA, err := init.Finish(answer, Binding{LocalID: wgA, RemoteID: wgB}) + require.NoError(t, err) + + require.Equal(t, pskB, pskA, "swapped Local/Remote order must canonicalise to the same PSK") +} diff --git a/client/internal/pqkem/kem_test.go b/client/internal/pqkem/kem_test.go new file mode 100644 index 00000000000..da5e98c1ed2 --- /dev/null +++ b/client/internal/pqkem/kem_test.go @@ -0,0 +1,89 @@ +package pqkem + +import ( + "testing" + + "github.com/stretchr/testify/require" +) + +var ( + wgA = []byte("peer-A-wireguard-pubkey-32bytes!") + wgB = []byte("peer-B-wireguard-pubkey-32bytes!") +) + +func TestExchange_DerivesMatchingPSK(t *testing.T) { + init, err := NewInitiator() + require.NoError(t, err) + + require.Len(t, init.Offer(), OfferSize) + + answer, pskB, err := Respond(init.Offer(), Binding{LocalID: wgB, RemoteID: wgA}) + require.NoError(t, err) + require.Len(t, answer, AnswerSize) + + pskA, err := init.Finish(answer, Binding{LocalID: wgA, RemoteID: wgB}) + require.NoError(t, err) + + require.Equal(t, pskB, pskA, "both sides must derive the same PSK") + require.NotEqual(t, PSK{}, pskA, "PSK must not be zero") +} + +func TestExchange_PSKBoundToPeerIdentities(t *testing.T) { + init, err := NewInitiator() + require.NoError(t, err) + + answer, _, err := Respond(init.Offer(), Binding{LocalID: wgB, RemoteID: wgA}) + require.NoError(t, err) + + // Finish twice over the SAME KEM material (same offer/answer/secrets), changing only + // the peer identity binding: the differing PSK is attributable to the binding alone. + pskHonest, err := init.Finish(answer, Binding{LocalID: wgA, RemoteID: wgB}) + require.NoError(t, err) + + wgC := []byte("peer-C-wireguard-pubkey-32bytes!") + pskWrong, err := init.Finish(answer, Binding{LocalID: wgA, RemoteID: wgC}) + require.NoError(t, err) + + require.NotEqual(t, pskHonest, pskWrong, "PSK must be bound to the peer pair") +} + +func TestExchange_RejectsEmptyBinding(t *testing.T) { + init, err := NewInitiator() + require.NoError(t, err) + answer, _, err := Respond(init.Offer(), Binding{LocalID: wgB, RemoteID: wgA}) + require.NoError(t, err) + + // A PSK not bound to both identities could be transplanted to another peer pair. + _, err = init.Finish(answer, Binding{}) + require.Error(t, err, "empty binding must be rejected") + _, err = init.Finish(answer, Binding{LocalID: wgA}) + require.Error(t, err, "missing RemoteID must be rejected") + _, _, err = Respond(init.Offer(), Binding{RemoteID: wgA}) + require.Error(t, err, "missing LocalID must be rejected") +} + +func TestExchange_RejectsMalformedMessages(t *testing.T) { + init, err := NewInitiator() + require.NoError(t, err) + + _, _, err = Respond(init.Offer()[:10], Binding{}) + require.Error(t, err) + + _, err = init.Finish([]byte("too short"), Binding{}) + require.Error(t, err) +} + +// BenchmarkExchange measures a full hybrid exchange (keygen, encapsulation, decapsulation) +// and reports its on-wire size. +// Run with: go test -run '^$' -bench BenchmarkExchange ./client/internal/pqkem/ +func BenchmarkExchange(b *testing.B) { + for i := 0; i < b.N; i++ { + init, err := NewInitiator() + require.NoError(b, err) + answer, _, err := Respond(init.Offer(), Binding{LocalID: wgB, RemoteID: wgA}) + require.NoError(b, err) + _, err = init.Finish(answer, Binding{LocalID: wgA, RemoteID: wgB}) + require.NoError(b, err) + } + b.ReportMetric(float64(OfferSize+AnswerSize), "wire-B/exchange") +} diff --git a/client/internal/pqkem/manager.go b/client/internal/pqkem/manager.go new file mode 100644 index 00000000000..5b9e242af88 --- /dev/null +++ b/client/internal/pqkem/manager.go @@ -0,0 +1,707 @@ +package pqkem + +import ( + "context" + "crypto/rand" + "fmt" + "log/slog" + "net/netip" + "sync" + "time" +) + +const ( + // DefaultRetryInterval is how often the initiator retransmits its outstanding + // data-path offer while awaiting the answer. + DefaultRetryInterval = 2 * time.Second + // DefaultMaxRetries is how many times the initiator retransmits its outstanding + // offer while awaiting the answer. Failure is declared on the tick after the last + // retransmit, so the convergence deadline is (MaxRetries+1) * RetryInterval. + DefaultMaxRetries = 10 + // DefaultMaxRekeyFailures is how many consecutive rekey (non-initial) failures + // are tolerated before OnRekeyFailed. The initial exchange fails immediately. + DefaultMaxRekeyFailures = 3 + + // rotationActivityWindow gates rotation on recent real-data activity: a rekey + // clocks a rotation only if the peer exchanged user data within this window. It + // must stay shorter than the data path's rekey interval (WireGuard + // REKEY_AFTER_TIME ~120s) so the rotation's own traffic — which itself renews the + // activity signal — ages out before the next rekey, letting an idle tunnel stop + // rotating instead of self-sustaining. + // + // INVARIANT: rotationActivityWindow < the gap between OnDataPathRekeyed calls. That + // gap converges to the WireGuard rehandshake interval (REKEY_AFTER_TIME 120s). Setting + // rotationActivityWindow to a value higher than 120s will make the rotation + // self-sustain (preventing going back to idle). Margin here is ~30s. + rotationActivityWindow = 90 * time.Second +) + +// LocalID and RemoteID are peer identity keys (e.g. WireGuard public keys). They are +// distinct types so the local and a remote identity cannot be mixed up. +type ( + LocalID string + RemoteID string +) + +// Transport is the data-path socket the Manager drives (the analogue of +// go-rosenpass's Conn). It is a dumb mover of bytes to/from endpoints: the Manager +// owns the remoteID<->endpoint routing and hands the transport a resolved endpoint +// to Send, and reverse-resolves the source of each inbound datagram. Its lifecycle +// belongs to the Manager (Run at Start, Close at Stop). +type Transport interface { + // Send delivers msg to the given data-path endpoint. + Send(endpoint netip.AddrPort, msg []byte) error + // LocalPort is the bound local UDP port, announced to peers so they know where + // to send data-path messages. + LocalPort() int + // Run starts delivering inbound datagrams as (source endpoint, msg) to onInbound + // and returns immediately; it runs until Close. + Run(onInbound func(src netip.AddrPort, msg []byte)) + // Close stops delivery, drains any in-flight onInbound callback, and releases the + // socket, so no callback is still running when Close returns. + Close() error +} + +// exchangeState is the single source of truth for an exchange's role and phase. +type exchangeState uint8 + +const ( + stateReserved exchangeState = iota // responder: deriving the answer + stateAwaitingAnswer // initiator: offer sent, awaiting the answer + stateFinishing // initiator: answer in, deriving the PSK (not yet committed) + stateAwaitingRekey // initiator: PSK derived+set, awaiting OnDataPathRekeyed to chain the next offer + stateAwaitingAck // responder: answer sent, awaiting the next offer that acks this exchange +) + +// exchangeCtl holds all state for one in-flight exchange with a peer, under the +// Manager's single lock. state drives every decision. lastSent is the current +// data-path retransmit payload (the offer, for the initiator). initiator is the +// ephemeral handle used at Finish. viaSignal records that the offer went to the host +// for the signalling channel, so the loop does not retransmit it on the data path. +// Only the initiator runs a retransmit loop, so only it sets cancel. +type exchangeCtl struct { + id ExchangeID + state exchangeState + gen uint64 // local, per-peer monotonic generation; lets the host reject a stale PSK apply + cancel context.CancelFunc + lastSent []byte + initiator *Initiator + viaSignal bool + acks ExchangeID // exchange this one acknowledges; zero for a bootstrap +} + +// Manager is the stateful orchestrator — the analogue of go-rosenpass's Server. It +// drives the X25519MLKEM768 exchange, owns the peer endpoint routing and the data-path +// transport, and surfaces the derived PSK and convergence to the host via +// CallbackHandler. It is event-driven: the bootstrap is triggered by the host +// (SignalOffer) and each rotation is clocked by OnDataPathRekeyed. The cryptography is +// the pure kem.go primitives; all state lives here under one lock. +type Manager struct { + localID LocalID + cbHandler CallbackHandler + logger *slog.Logger + secret []byte // optional pre-shared secret bound into every derivation; immutable + + retryInterval time.Duration + maxRetries int + maxRekeyFailures int + + rootCtx context.Context + rootCancel context.CancelFunc + + mu sync.Mutex + transport Transport + exchanges map[RemoteID]*exchangeCtl // in-flight exchange per peer + established map[RemoteID]bool // peer has completed at least one exchange + failures map[RemoteID]int // consecutive rekey failures per peer + psks map[RemoteID]PSK // latest derived PSK per peer (pulled at WG peer-config time) + prevPSKs map[RemoteID]PSK // PSK before the latest commit; still authenticates data-path messages sealed under it + capable map[RemoteID]bool // peer runs the KEM (advertised a PQ port); false = known non-capable + peerAddrs map[RemoteID]netip.AddrPort // remoteID -> data-path endpoint (send routing) + peersByAddr map[netip.AddrPort]RemoteID // reverse: source endpoint -> remoteID (inbound) + genCounter map[RemoteID]uint64 // per-peer monotonic exchange generation + wait sync.WaitGroup +} + +// nextGenLocked returns the next monotonic generation for a peer's exchange. Assumes +// m.mu is held. Because exchanges for a given peer are created under the lock in order, +// a later exchange always carries a higher generation, so the host can drop a PSK apply +// that arrives out of order (generation <= the one it already applied). +func (m *Manager) nextGenLocked(remoteID RemoteID) uint64 { + m.genCounter[remoteID]++ + return m.genCounter[remoteID] +} + +// Option configures a Manager at construction. +type Option func(*Manager) + +// WithPresharedSecret binds every derived PSK, bootstrap and rotation alike, to a secret +// both peers must already share. A peer with a different secret, or none, derives a +// different PSK, so the consumer's channel fails closed instead of bypassing the secret. +// An empty secret is the same as no option. +func WithPresharedSecret(secret []byte) Option { + return func(m *Manager) { + m.secret = append([]byte(nil), secret...) + } +} + +// NewManager builds a manager for the local peer identified by its peer identity key +// (used for the deterministic initiator role and the identity binding). A nil logger +// falls back to slog.Default(). Install the data-path transport with Start. +func NewManager(localID LocalID, h CallbackHandler, logger *slog.Logger, opts ...Option) *Manager { + if logger == nil { + logger = slog.Default() + } + ctx, cancel := context.WithCancel(context.Background()) + m := &Manager{ + localID: localID, + cbHandler: h, + logger: logger, + retryInterval: DefaultRetryInterval, + maxRetries: DefaultMaxRetries, + maxRekeyFailures: DefaultMaxRekeyFailures, + rootCtx: ctx, + rootCancel: cancel, + exchanges: make(map[RemoteID]*exchangeCtl), + established: make(map[RemoteID]bool), + failures: make(map[RemoteID]int), + psks: make(map[RemoteID]PSK), + prevPSKs: make(map[RemoteID]PSK), + capable: make(map[RemoteID]bool), + peerAddrs: make(map[RemoteID]netip.AddrPort), + peersByAddr: make(map[netip.AddrPort]RemoteID), + genCounter: make(map[RemoteID]uint64), + } + for _, opt := range opts { + opt(m) + } + return m +} + +// Start installs the data-path transport and begins its inbound delivery. The Manager +// owns it from here; Stop closes it. +func (m *Manager) Start(t Transport) { + m.mu.Lock() + m.transport = t + m.mu.Unlock() + if t != nil { + t.Run(m.onDataPathInbound) + } +} + +// LocalPort is the data-path transport's bound UDP port (0 if no transport), to be +// announced to peers. +func (m *Manager) LocalPort() int { + m.mu.Lock() + t := m.transport + m.mu.Unlock() + if t == nil { + return 0 + } + return t.LocalPort() +} + +// IsInitiator reports whether the local peer drives the exchange for this remote +// peer. Roles are deterministic (lexicographic identity-key compare) so exactly one +// side initiates, mirroring how Rosenpass picks its handshake initiator. +func (m *Manager) IsInitiator(remoteID RemoteID) bool { + return string(m.localID) > string(remoteID) +} + +// PSK returns the latest PSK derived for the peer, for the host to program at WG +// peer-config time (the pull path). ok is false until an exchange has derived one. +func (m *Manager) PSK(remoteID RemoteID) (PSK, bool) { + m.mu.Lock() + defer m.mu.Unlock() + psk, ok := m.psks[remoteID] + return psk, ok +} + +// beginCall registers an in-flight host-driven signalling call in the wait group so Stop +// drains it before clearing state, and refuses once the manager is stopping. It mirrors +// startExchangeLocked's guard: rootCancel runs under m.mu before Stop's Wait, and this +// Adds under the same lock after checking rootCtx, so no Add can race the Wait. The caller +// must defer m.wait.Done() when this returns true. +func (m *Manager) beginCall() bool { + m.mu.Lock() + defer m.mu.Unlock() + if m.rootCtx.Err() != nil { + return false + } + m.wait.Add(1) + return true +} + +// trace logs at LevelTrace, the verbose per-exchange lifecycle level gated by +// NB_PQ_MLKEM_LOG_LEVEL=trace. +func (m *Manager) trace(msg string, args ...any) { + m.logger.Log(context.Background(), LevelTrace, msg, args...) +} + +// debug logs at LevelDebug — visible at the default field log level. Reserved for the +// pivotal exchange events (an offer going out, a PSK converging) tagged with the four +// dimensions that tell them apart: msg (offer/answer), role (initiator/responder), via +// (signal/data-path), and kind (bootstrap for a new connection vs rotation for a rekey). +func (m *Manager) debug(msg string, args ...any) { + m.logger.Log(context.Background(), slog.LevelDebug, msg, args...) +} + +// AddPeer registers where a peer's data-path messages are sent and received: its +// overlay endpoint (IP:port). This is pure routing and says nothing about capability — +// PQ capability is decided solely from the peer's KEM payload (see processOffer / +// processAnswer / MarkNonCapable), never from an endpoint or port. +func (m *Manager) AddPeer(remoteID RemoteID, endpoint netip.AddrPort) { + if !endpoint.IsValid() { + return + } + m.mu.Lock() + if old, ok := m.peerAddrs[remoteID]; ok { + delete(m.peersByAddr, old) + } + m.peerAddrs[remoteID] = endpoint + m.peersByAddr[endpoint] = remoteID + m.mu.Unlock() +} + +// MarkNonCapable records that a peer does not run the KEM: its signalling message +// carried no KEM where one was due. Any in-flight exchange is cancelled and further +// offers are suppressed (see SignalOffer), so a non-PQ peer never drives the +// rekey-recovery storm. Every failure path sends an error marker instead of an empty +// payload, so for a peer we hold a PSK with this is a downgrade: it restarted without the +// KEM and lost the PSK. Ours is dropped too, and downgraded reports it, so the host stops +// programming a key the peer no longer has. +func (m *Manager) MarkNonCapable(remoteID RemoteID) (downgraded bool) { + m.mu.Lock() + defer m.mu.Unlock() + _, downgraded = m.psks[remoteID] + if prev, ok := m.capable[remoteID]; ok && !prev && !downgraded { + return false // already known non-capable, nothing to do + } + m.resetPeerLocked(remoteID) + m.capable[remoteID] = false + if downgraded { + m.debug("pqkem: peer stopped running the KEM, dropping its PSK", "peer", remoteID) + return true + } + m.trace("pqkem: peer advertises no PQ service — treating as non-capable, no KEM attempted", "peer", remoteID) + return false +} + +// ClearNonCapable forgets that a peer was found non-capable, so the next signalling round +// offers it the KEM again. The host calls it when the peer announces a PQ port: the peer +// runs the KEM now, though only its next payload proves it. +func (m *Manager) ClearNonCapable(remoteID RemoteID) { + m.mu.Lock() + defer m.mu.Unlock() + if capable, ok := m.capable[remoteID]; ok && !capable { + delete(m.capable, remoteID) + } +} + +// RemovePeer stops any in-flight exchange for a peer and drops its state and routing. +func (m *Manager) RemovePeer(remoteID RemoteID) { + m.mu.Lock() + m.resetPeerLocked(remoteID) + if ep, ok := m.peerAddrs[remoteID]; ok { + delete(m.peersByAddr, ep) + delete(m.peerAddrs, remoteID) + } + m.mu.Unlock() +} + +// resetPeerLocked cancels the peer's in-flight exchange and drops its keys and +// capability, leaving its routing in place. Generations keep counting, so the host never +// takes a later key for a stale one. Assumes m.mu is held. +func (m *Manager) resetPeerLocked(remoteID RemoteID) { + if ex, ok := m.exchanges[remoteID]; ok { + if ex.cancel != nil { + ex.cancel() + } + delete(m.exchanges, remoteID) + } + delete(m.established, remoteID) + delete(m.failures, remoteID) + delete(m.psks, remoteID) + delete(m.prevPSKs, remoteID) + delete(m.capable, remoteID) +} + +// Stop cancels all in-flight exchanges, closes the transport, and waits for the +// exchange goroutines to exit. +func (m *Manager) Stop() { + // Cancel the root context under the lock, before Wait: startExchangeLocked checks + // rootCtx.Err() under the same lock before it Adds to the wait group, so once Stop + // has cancelled here no new Add can race Wait. + m.mu.Lock() + m.rootCancel() + t := m.transport + m.transport = nil + m.mu.Unlock() + + // Close and drain the data-path receive loop BEFORE clearing peer state: Close waits + // for any in-flight onInbound to return, so no inbound message can derive a PSK into a + // cleared map, and the engine only tears the WireGuard interface down after this Stop + // returns, so no late SetPresharedKey hits a torn-down device. + if t != nil { + if err := t.Close(); err != nil { + m.logger.Warn("pqkem: closing data-path transport", "err", err) + } + } + m.wait.Wait() + + m.mu.Lock() + m.exchanges = make(map[RemoteID]*exchangeCtl) + m.psks = make(map[RemoteID]PSK) + m.prevPSKs = make(map[RemoteID]PSK) + m.mu.Unlock() +} + +// ---- Signalling channel (host-driven; rides the host's negotiation) ---- + +// SignalOffer returns the KEM offer for the host to embed in its outgoing offer to +// remoteID (bootstrap). It returns (nil, nil) when the local peer is not the +// initiator. It is idempotent for an in-flight bootstrap: a repeat call returns the +// same offer rather than starting a new exchange. +// +// On a build failure it returns a non-nil error AND a non-empty error-marker payload: +// the host must still send that payload, because an empty MlkemPayload is the "peer does +// not run the KEM" capability signal, which would wrongly mark this peer non-capable. +// +// A signal re-negotiation always re-bootstraps (fresh exchange): the remote may have +// restarted and lost its PSK, so reusing a locally frozen one would desync. The derived +// PSK still survives idle in the manager (dropped only on account-level peer removal), +// so a pure lazy wake with no re-negotiation reuses it via the conn's WG-config pull. +func (m *Manager) SignalOffer(remoteID RemoteID) ([]byte, error) { + if !m.IsInitiator(remoteID) { + return nil, nil + } + if !m.beginCall() { + // A marker, not nil: an empty offer would read as a downgrade on the responder. + return (&ErrorMsg{}).Encode(), fmt.Errorf("manager stopping") + } + defer m.wait.Done() + m.mu.Lock() + if capable, ok := m.capable[remoteID]; ok && !capable { + m.mu.Unlock() + return nil, nil // peer does not run the KEM; do not offer (avoids a failure/recovery loop) + } + // Idempotent ONLY while a signalling bootstrap is still in flight (awaitingAnswer): + // a repeat call returns the SAME offer instead of starting a duplicate exchange. Once + // the PSK is derived (awaitingRekey) a fresh signal offer must NOT reuse the frozen + // exchange: a signal re-negotiation means the remote may have restarted and lost its + // state, so it would Respond with fresh material and derive a different PSK, which our + // still-awaitingRekey side would reject — a permanent desync. Starting a fresh exchange + // re-bootstraps and both sides converge (the responder always adopts the latest). The + // controller-double-offer case the idempotency once guarded is already covered by + // ShouldSendBootstrapOffer (false while an exchange is in flight). + if ex := m.exchanges[remoteID]; ex != nil && ex.viaSignal && ex.state == stateAwaitingAnswer { + last := ex.lastSent + m.mu.Unlock() + return last, nil + } + // Hold the lock across the check above and the install so a concurrent SignalOffer + // for the same peer can't also start an exchange. bootstrap offer acks nothing. + raw, err := m.startExchangeLocked(remoteID, true, ExchangeID{}) + m.mu.Unlock() + if err != nil { + // Return an error marker, not an empty offer: an empty MlkemPayload is the "peer + // does not run the KEM" capability signal, so the responder would wrongly mark us + // non-capable (and answer empty, making us mark it non-capable in turn). The marker + // is benign on the far side; the host retries the offer. + return (&ErrorMsg{}).Encode(), err + } + return raw, nil +} + +// ShouldSendBootstrapOffer reports whether we should emit a fresh KEM offer to kick a +// bootstrap for this peer. True if we are the initiator, the peer is not known +// non-capable, and no exchange of ours is in flight. The host uses this when it (as the +// controller) receives the responder's offer, which never carries KEM material: it replies +// with a KEM offer, and ignores further responder offers while that one is in flight, +// avoiding an offer-per-offer runaway. A converged exchange does not count as in flight: a +// responder offer then means the responder is renegotiating (a reconnect or a wake), and +// our current PSK may be the reason, e.g. split by a rotation whose answers were lost. A +// fresh bootstrap re-aligns both sides, so that reconnect cannot come back on a stale key. +func (m *Manager) ShouldSendBootstrapOffer(remoteID RemoteID) bool { + if !m.IsInitiator(remoteID) { + return false + } + m.mu.Lock() + defer m.mu.Unlock() + if capable, ok := m.capable[remoteID]; ok && !capable { + return false + } + ex := m.exchanges[remoteID] + return ex == nil || ex.state == stateAwaitingRekey +} + +// SignalOfferInFlight reports whether we are the initiator and our bootstrap offer over +// signalling still awaits its answer. A data-path rotation in flight does not count: no +// offer of ours is crossing the peer's on the signalling channel then. +func (m *Manager) SignalOfferInFlight(remoteID RemoteID) bool { + if !m.IsInitiator(remoteID) { + return false + } + m.mu.Lock() + defer m.mu.Unlock() + ex := m.exchanges[remoteID] + return ex != nil && ex.viaSignal && ex.state == stateAwaitingAnswer +} + +// SignalOnOffer processes a KEM offer the host extracted from an incoming offer and +// returns the KEM answer for the host to embed in its outgoing answer. Every failure +// still returns an error marker: an empty answer means "this peer does not run the KEM" +// and would stop the initiator from ever offering again. +func (m *Manager) SignalOnOffer(remoteID RemoteID, offer []byte) ([]byte, error) { + if !m.beginCall() { + return (&ErrorMsg{}).Encode(), fmt.Errorf("manager stopping") + } + defer m.wait.Done() + typ, msg, err := Decode(offer) + if err != nil { + // Also covers an offer from a newer protocol version this peer cannot read. + return (&ErrorMsg{}).Encode(), fmt.Errorf("decode signal offer from %s: %w", remoteID, err) + } + if typ == MsgError { + // The initiator failed to build its offer and sent a marker. Answer with our own + // marker, not an empty answer, so it is not read as "peer does not run the KEM". + m.trace("pqkem: peer reported an error building its offer", "peer", remoteID) + return (&ErrorMsg{}).Encode(), nil + } + if typ != MsgOffer { + return (&ErrorMsg{}).Encode(), fmt.Errorf("expected offer from %s, got type %d", remoteID, typ) + } + o := msg.(*OfferMsg) + answer, err := m.processOffer(remoteID, o, viaSignalLabel) + if err != nil { + // Reply with an error marker rather than an empty answer: the initiator must not + // read our transient failure as "peer does not run the KEM" and mark us + // non-capable. The exchange times out on the initiator and re-bootstraps. + return (&ErrorMsg{ExchangeID: o.ExchangeID}).Encode(), err + } + return answer, nil +} + +// SignalOnAnswer processes a KEM answer the host extracted from an incoming answer. +// There is no reply: the next offer (over the data path) acknowledges this exchange. +func (m *Manager) SignalOnAnswer(remoteID RemoteID, answer []byte) error { + if !m.beginCall() { + return fmt.Errorf("manager stopping") + } + defer m.wait.Done() + typ, msg, err := Decode(answer) + if err != nil { + return fmt.Errorf("decode signal answer from %s: %w", remoteID, err) + } + if typ == MsgError { + // The responder runs the KEM but failed to answer this offer. It is capable, so + // leave the exchange to time out and re-bootstrap; do not mark it non-capable. + m.trace("pqkem: peer reported an error answering our offer", "peer", remoteID) + return nil + } + if typ != MsgAnswer { + return fmt.Errorf("expected answer from %s, got type %d", remoteID, typ) + } + return m.processAnswer(remoteID, msg.(*AnswerMsg), viaSignalLabel) +} + +// ---- Data path ---- + +// onDataPathInbound is the transport's inbound handler: it reverse-resolves the +// source endpoint to a peer and dispatches. Unknown sources are dropped. +func (m *Manager) onDataPathInbound(src netip.AddrPort, msg []byte) { + m.mu.Lock() + remoteID, ok := m.peersByAddr[src] + m.mu.Unlock() + if !ok { + return + } + if err := m.OnDataPathMessage(remoteID, msg); err != nil { + m.trace("pqkem: inbound", "peer", remoteID, "err", err) + } +} + +// OnDataPathMessage handles a KEM message received over the data path from remoteID +// and pushes any reply back over the data path. The sender is only known by its source +// address, which can be spoofed, so a message that does not carry a valid MAC under a PSK +// shared with remoteID is rejected. +func (m *Manager) OnDataPathMessage(remoteID RemoteID, raw []byte) error { + frame, key, err := m.openDataPathFrom(remoteID, raw) + if err != nil { + return err + } + typ, msg, err := Decode(frame) + if err != nil { + return fmt.Errorf("decode data-path msg from %s: %w", remoteID, err) + } + switch typ { + case MsgOffer: + o := msg.(*OfferMsg) + // The data path only carries rotations of an established exchange. A bootstrap + // starts from scratch, so it must come over the authenticated signalling channel. + if o.AckID == (ExchangeID{}) { + m.debug("pqkem: dropping a bootstrap offer received over the data path", "peer", remoteID, "exchange", idHex(o.ExchangeID)) + return nil + } + answer, err := m.processOffer(remoteID, o, viaDataPathLabel) + if err != nil { + return err + } + if answer == nil { + return nil + } + // Seal the reply under the key that verified the offer. processOffer has just + // committed the new PSK, which the initiator only derives once it reads this answer. + return m.sendDataPath(remoteID, sealDataPath(key, answer)) + case MsgAnswer: + return m.processAnswer(remoteID, msg.(*AnswerMsg), viaDataPathLabel) + case MsgError: + m.trace("pqkem: peer reported an error over the data path", "peer", remoteID) + return nil + default: + return fmt.Errorf("unhandled data-path message type %d from %s", typ, remoteID) + } +} + +// OnDataPathRekeyed clocks the next chained PSK rotation on a fresh data-path rekey +// (fired on first establishment AND every rekey). If we are the initiator that just +// derived a PSK, it chains the next exchange: a fresh offer over the data path that +// acknowledges the just-completed one (its arrival under the new key proves to the +// responder the key works). sinceActivity is how long ago the peer last exchanged real +// user data; past rotationActivityWindow the tunnel is treated as idle and rotation is +// skipped — an idle tunnel has nothing to protect, and rotating would emit data-path +// traffic that keeps the peer artificially active (see conn.onWGCheckSuccess). +func (m *Manager) OnDataPathRekeyed(remoteID RemoteID, sinceActivity time.Duration) { + if sinceActivity >= rotationActivityWindow { + m.trace("pqkem: peer idle, skipping data-path rotation", "peer", remoteID, "since_activity", sinceActivity) + return + } + + m.mu.Lock() + ex := m.exchanges[remoteID] + chain := ex != nil && ex.state == stateAwaitingRekey + if !chain { + m.mu.Unlock() + m.trace("pqkem: data-path rekey signal", "peer", remoteID, "chaining", false) + return + } + // Hold the lock across the awaitingRekey check and the install so two rekey clocks + // can't each start a chained exchange for the same peer. + offer, err := m.startExchangeLocked(remoteID, false, ex.id) + var chainID ExchangeID + if nc := m.exchanges[remoteID]; nc != nil { + chainID = nc.id + } + m.mu.Unlock() + + m.trace("pqkem: data-path rekey signal", "peer", remoteID, "chaining", true) + if err != nil { + m.logger.Error("pqkem: chain offer failed to start", "peer", remoteID, "err", err) + return + } + // A signal re-bootstrap can supersede this chain exchange in the gap between building + // the offer and sending it. Don't put the stale offer on the wire: the responder would + // otherwise reserve and commit an abandoned exchange, splitting the keys. A newer + // signal round always wins. (A supersede landing after this check still leaks one + // harmless offer; the responder's answer for it is rejected as superseded.) + m.mu.Lock() + stillCurrent := m.exchanges[remoteID] != nil && m.exchanges[remoteID].id == chainID + m.mu.Unlock() + if !stillCurrent { + m.trace("pqkem: chain offer superseded before send, dropping", "peer", remoteID, "exchange", idHex(chainID)) + return + } + if err := m.pushDataPath(remoteID, offer); err != nil { + m.logger.Warn("pqkem: send chain offer failed", "peer", remoteID, "err", err) + return + } + m.trace("pqkem: chain offer sent over data path", "peer", remoteID) +} + +// OnDataPathDown notifies that the peer's data path went down. Rotations resume once +// the host re-bootstraps over signalling on reconnect; in-flight data-path sends will +// simply fail until then. Reserved as an explicit hook. +func (m *Manager) OnDataPathDown(remoteID RemoteID) {} + +// ---- internals ---- + +// commitPSKLocked records a freshly derived PSK as the peer's current one, keeping the one +// it replaces: messages sealed under it may still be in flight (see openDataPathFrom). +// Assumes m.mu is held. +func (m *Manager) commitPSKLocked(remoteID RemoteID, psk PSK) { + if old, ok := m.psks[remoteID]; ok { + m.prevPSKs[remoteID] = old + } + m.psks[remoteID] = psk +} + +// pushDataPath sends a message to the peer over the data-path transport, sealed under +// the PSK the two peers currently share. +func (m *Manager) pushDataPath(remoteID RemoteID, msg []byte) error { + m.mu.Lock() + psk, ok := m.psks[remoteID] + m.mu.Unlock() + if !ok { + return fmt.Errorf("no PSK to authenticate a data-path message to %s", remoteID) + } + key, err := dataPathMACKey(psk) + if err != nil { + return err + } + return m.sendDataPath(remoteID, sealDataPath(key, msg)) +} + +// openDataPathFrom authenticates a data-path message from a peer under its current PSK, +// or failing that the previous one: an offer retransmitted after this side committed the +// PSK it derived was still sealed under the old key. It returns the frame and the key +// that verified it. +func (m *Manager) openDataPathFrom(remoteID RemoteID, raw []byte) ([]byte, []byte, error) { + m.mu.Lock() + candidates := make([]PSK, 0, 2) + if psk, ok := m.psks[remoteID]; ok { + candidates = append(candidates, psk) + } + if psk, ok := m.prevPSKs[remoteID]; ok { + candidates = append(candidates, psk) + } + m.mu.Unlock() + + for _, psk := range candidates { + key, err := dataPathMACKey(psk) + if err != nil { + return nil, nil, err + } + if frame, ok := openDataPath(key, raw); ok { + return frame, key, nil + } + } + return nil, nil, fmt.Errorf("unauthenticated data-path message from %s", remoteID) +} + +// sendDataPath resolves the peer's endpoint and sends over the data-path transport, +// erroring if the peer is unknown or no transport is set. +func (m *Manager) sendDataPath(remoteID RemoteID, msg []byte) error { + m.mu.Lock() + ep, ok := m.peerAddrs[remoteID] + t := m.transport + m.mu.Unlock() + if !ok { + return fmt.Errorf("no data-path endpoint for peer %s", remoteID) + } + if t == nil { + return fmt.Errorf("no data-path transport") + } + return t.Send(ep, msg) +} + +func (m *Manager) binding(remoteID RemoteID) Binding { + return Binding{LocalID: []byte(m.localID), RemoteID: []byte(remoteID), Secret: m.secret} +} + +func newExchangeID() (ExchangeID, error) { + var id ExchangeID + if _, err := rand.Read(id[:]); err != nil { + return ExchangeID{}, fmt.Errorf("generate exchange id: %w", err) + } + return id, nil +} diff --git a/client/internal/pqkem/manager_test.go b/client/internal/pqkem/manager_test.go new file mode 100644 index 00000000000..239037f03c2 --- /dev/null +++ b/client/internal/pqkem/manager_test.go @@ -0,0 +1,240 @@ +package pqkem + +import ( + "fmt" + "net/netip" + "sync" + "sync/atomic" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// netSwitch is an in-memory UDP fabric: transports register their endpoint and get +// datagrams delivered to their inbound handler. +type netSwitch struct { + mu sync.Mutex + h map[netip.AddrPort]func(netip.AddrPort, []byte) +} + +func newSwitch() *netSwitch { + return &netSwitch{h: map[netip.AddrPort]func(netip.AddrPort, []byte){}} +} + +func (s *netSwitch) register(ep netip.AddrPort, fn func(netip.AddrPort, []byte)) { + s.mu.Lock() + s.h[ep] = fn + s.mu.Unlock() +} + +func (s *netSwitch) deliver(dst, src netip.AddrPort, msg []byte) error { + s.mu.Lock() + fn := s.h[dst] + s.mu.Unlock() + if fn == nil { + return fmt.Errorf("no route to %s", dst) + } + fn(src, msg) + return nil +} + +// loopback is an endpoint-based pqkem.Transport over a netSwitch, with a switchable +// drop flag. +type loopback struct { + ep netip.AddrPort + sw *netSwitch + drop atomic.Bool +} + +func (l *loopback) Send(dst netip.AddrPort, msg []byte) error { + if l.drop.Load() { + return nil + } + return l.sw.deliver(dst, l.ep, append([]byte(nil), msg...)) +} + +func (l *loopback) LocalPort() int { return int(l.ep.Port()) } +func (l *loopback) Run(onInbound func(netip.AddrPort, []byte)) { l.sw.register(l.ep, onInbound) } +func (l *loopback) Close() error { return nil } + +type fakeWG struct { + mu sync.Mutex + psks map[RemoteID]PSK + failed []RemoteID +} + +func newFakeWG() *fakeWG { return &fakeWG{psks: map[RemoteID]PSK{}} } + +// startExchangeTest drives startExchangeLocked with the lock held, for tests that kick an +// exchange directly (production callers hold m.mu across their idempotency check). +func (m *Manager) startExchangeTest(remoteID RemoteID, viaSignal bool, ackID ExchangeID) ([]byte, error) { + m.mu.Lock() + defer m.mu.Unlock() + return m.startExchangeLocked(remoteID, viaSignal, ackID) +} + +func (f *fakeWG) OnNewPSKReady(remoteID RemoteID, _ uint64, psk PSK) error { + f.mu.Lock() + defer f.mu.Unlock() + f.psks[remoteID] = psk + return nil +} + +func (f *fakeWG) OnRekeyFailed(remoteID RemoteID) error { + f.mu.Lock() + defer f.mu.Unlock() + f.failed = append(f.failed, remoteID) + return nil +} + +func (f *fakeWG) psk(peer RemoteID) PSK { + f.mu.Lock() + defer f.mu.Unlock() + return f.psks[peer] +} + +var ( + epA = netip.MustParseAddrPort("100.64.0.1:51833") + epB = netip.MustParseAddrPort("100.64.0.2:51833") +) + +// pair builds two wired managers (B is the initiator, "bbbb" > "aaaa") sharing a +// netSwitch, with each peer's data-path endpoint registered. lbB is B's loopback +// (for toggling drop). +func pair(t *testing.T) (dA, dB *Manager, wgA, wgB *fakeWG, lbB *loopback) { + t.Helper() + sw := newSwitch() + wgA = newFakeWG() + wgB = newFakeWG() + dA = NewManager("aaaa", wgA, nil) + dB = NewManager("bbbb", wgB, nil) + dA.Start(&loopback{ep: epA, sw: sw}) + lbB = &loopback{ep: epB, sw: sw} + dB.Start(lbB) + dA.AddPeer("bbbb", epB) + dB.AddPeer("aaaa", epA) + return dA, dB, wgA, wgB, lbB +} + +// bootstrap runs the signalling offer/answer (the test plays the host carrying bytes). +func bootstrap(t *testing.T, dA, dB *Manager) { + t.Helper() + offer, err := dB.SignalOffer("aaaa") + require.NoError(t, err) + require.NotNil(t, offer) + answer, err := dA.SignalOnOffer("bbbb", offer) + require.NoError(t, err) + require.NotNil(t, answer) + require.NoError(t, dB.SignalOnAnswer("aaaa", answer)) +} + +func TestManager_BootstrapDerivesSamePSK(t *testing.T) { + dA, dB, wgA, wgB, _ := pair(t) + defer dA.Stop() + defer dB.Stop() + + bootstrap(t, dA, dB) + + pskA := wgA.psk("bbbb") + pskB := wgB.psk("aaaa") + require.NotEqual(t, PSK{}, pskA) + require.Equal(t, pskB, pskA, "both sides derive the same PSK from the bootstrap exchange") +} + +func TestManager_ChainRotatesAndAcks(t *testing.T) { + dA, dB, wgA, wgB, _ := pair(t) + defer dA.Stop() + defer dB.Stop() + + bootstrap(t, dA, dB) + psk1 := wgB.psk("aaaa") + + // Data path up: B (initiator) chains the next offer over the data path, which + // rotates both to a fresh PSK and acknowledges A. + dA.OnDataPathRekeyed("bbbb", 0) + dB.OnDataPathRekeyed("aaaa", 0) + + psk2A := wgA.psk("bbbb") + psk2B := wgB.psk("aaaa") + require.Equal(t, psk2B, psk2A, "both sides converge on the rotated PSK") + require.NotEqual(t, psk1, psk2B, "the chain rotated to a new PSK") +} + +func TestManager_RotationSkippedWhenIdle(t *testing.T) { + dA, dB, wgA, wgB, _ := pair(t) + defer dA.Stop() + defer dB.Stop() + + bootstrap(t, dA, dB) + psk1 := wgB.psk("aaaa") + require.NotEqual(t, PSK{}, psk1) + + // Idle: the peer's last real-data activity is older than the window, so a rekey + // must NOT clock a rotation. + dA.OnDataPathRekeyed("bbbb", rotationActivityWindow) + dB.OnDataPathRekeyed("aaaa", rotationActivityWindow) + require.Equal(t, psk1, wgB.psk("aaaa"), "idle peer must not rotate the PSK") + require.Equal(t, psk1, wgA.psk("bbbb"), "idle peer must not rotate the PSK") + + // Active: activity within the window clocks the rotation as usual. + dA.OnDataPathRekeyed("bbbb", rotationActivityWindow-1) + dB.OnDataPathRekeyed("aaaa", rotationActivityWindow-1) + psk2 := wgB.psk("aaaa") + require.NotEqual(t, psk1, psk2, "recent activity must clock a rotation") + require.Equal(t, psk2, wgA.psk("bbbb"), "both sides converge on the rotated PSK") +} + +func TestManager_NonInitiatorReturnsNoOffer(t *testing.T) { + dA := NewManager("aaaa", newFakeWG(), nil) + defer dA.Stop() + + offer, err := dA.SignalOffer("bbbb") // not the initiator vs "bbbb" + require.NoError(t, err) + require.Nil(t, offer) +} + +func TestManager_StopIsIdempotent(t *testing.T) { + dA := NewManager("aaaa", newFakeWG(), nil) + dA.Start(&loopback{ep: epA, sw: newSwitch()}) + dA.Stop() + dA.Stop() // must not panic or hang +} + +// TestManager_SignalOfferRebootstrapsAfterResponderRestart verifies finding A: once a PSK +// is derived (initiator in awaitingRekey), a fresh signalling offer must start a NEW +// exchange, not replay the frozen one. Otherwise, if the responder restarted and lost its +// state, it would derive a different PSK the initiator then rejects — a permanent desync. +func TestManager_SignalOfferRebootstrapsAfterResponderRestart(t *testing.T) { + sw := newSwitch() + wgA, wgB := newFakeWG(), newFakeWG() + dA := NewManager("aaaa", wgA, nil) + dB := NewManager("bbbb", wgB, nil) + dA.Start(&loopback{ep: epA, sw: sw}) + dB.Start(&loopback{ep: epB, sw: sw}) + dA.AddPeer("bbbb", epB) + dB.AddPeer("aaaa", epA) + defer dB.Stop() + + bootstrap(t, dA, dB) + require.Equal(t, wgB.psk("aaaa"), wgA.psk("bbbb"), "bootstrap converged") + + // Responder ("aaaa") restarts: fresh manager, no state. + dA.Stop() + wgA2 := newFakeWG() + dA2 := NewManager("aaaa", wgA2, nil) + dA2.Start(&loopback{ep: epA, sw: sw}) + dA2.AddPeer("bbbb", epB) + defer dA2.Stop() + + offer, err := dB.SignalOffer("aaaa") + require.NoError(t, err) + require.NotNil(t, offer) + answer, err := dA2.SignalOnOffer("bbbb", offer) + require.NoError(t, err) + require.NotNil(t, answer) + require.NoError(t, dB.SignalOnAnswer("aaaa", answer)) + + assert.Equal(t, wgB.psk("aaaa"), wgA2.psk("bbbb"), + "after a responder restart both sides must converge on the same PSK") +} diff --git a/client/internal/pqkem/message.go b/client/internal/pqkem/message.go new file mode 100644 index 00000000000..a28720b993d --- /dev/null +++ b/client/internal/pqkem/message.go @@ -0,0 +1,142 @@ +package pqkem + +import ( + "crypto/mlkem" + "fmt" +) + +// Wire framing for the PQ-KEM exchange. Messages are self-contained, versioned, +// transport-agnostic byte blobs: the same bytes ride the signalling channel +// (initial bootstrap) or a data-tunnel packet (rekey). The library only ever sees +// opaque []byte at the transport seam. +// +// Layout (all messages): [type:1][version:1][exchangeID:16][payload...] +// +// There is no confirm message: an exchange is acknowledged by the NEXT offer, which +// carries the acked exchange's id (see OfferMsg.AckID) and — riding the data path +// under the freshly adopted key — proves that key works. + +const ( + // ProtocolVersion is bumped on any wire-incompatible change; a peer rejects + // messages it does not understand rather than misparsing them. + ProtocolVersion uint8 = 1 + + // ExchangeIDSize identifies one exchange so answers/acks correlate and stale + // messages are dropped. + ExchangeIDSize = 16 + + headerSize = 1 + 1 + ExchangeIDSize +) + +// MsgType tags the message kinds of the exchange. +type MsgType uint8 + +const ( + MsgOffer MsgType = iota + 1 + MsgAnswer + // MsgError is a responder's "I run the KEM but could not answer this offer" reply. + // It is a non-empty, payload-less marker so the initiator does not mistake a + // transient failure for an empty "peer does not run the KEM" answer and mark the + // peer non-capable. The exchange still times out and re-bootstraps. + MsgError +) + +// ExchangeID is the per-exchange correlator. The zero value means "none" (an offer +// that acknowledges nothing, i.e. the first exchange of a connection). +type ExchangeID [ExchangeIDSize]byte + +// OfferMsg carries the initiator's public material (ML-KEM encap key ‖ X25519 pub) +// and AckID, the id of the previous exchange this offer acknowledges (zero if none). +type OfferMsg struct { + ExchangeID ExchangeID + AckID ExchangeID + // KEMOffer is the raw Initiator.Offer() blob (OfferSize bytes). + KEMOffer []byte +} + +// AnswerMsg carries the responder's reply (ML-KEM ciphertext ‖ X25519 pub) for the +// round identified by ExchangeID. +type AnswerMsg struct { + ExchangeID ExchangeID + // KEMAnswer is the raw Respond() answer blob (AnswerSize bytes). + KEMAnswer []byte +} + +// Encode serialises the offer with its framed header (payload = AckID ‖ KEMOffer). +func (m *OfferMsg) Encode() ([]byte, error) { + if len(m.KEMOffer) != OfferSize { + return nil, fmt.Errorf("offer payload: got %d, want %d", len(m.KEMOffer), OfferSize) + } + payload := make([]byte, 0, ExchangeIDSize+OfferSize) + payload = append(payload, m.AckID[:]...) + payload = append(payload, m.KEMOffer...) + return frame(MsgOffer, m.ExchangeID, payload), nil +} + +// Encode serialises the answer with its framed header. +func (m *AnswerMsg) Encode() ([]byte, error) { + if len(m.KEMAnswer) != AnswerSize { + return nil, fmt.Errorf("answer payload: got %d, want %d", len(m.KEMAnswer), AnswerSize) + } + return frame(MsgAnswer, m.ExchangeID, m.KEMAnswer), nil +} + +// ErrorMsg is the payload-less marker a responder returns when it runs the KEM but +// could not answer a given offer, naming the offer's exchange. +type ErrorMsg struct { + ExchangeID ExchangeID +} + +// Encode serialises the error marker (header only, no payload). +func (m *ErrorMsg) Encode() []byte { + return frame(MsgError, m.ExchangeID, nil) +} + +// Decode parses a framed message into one of *OfferMsg / *AnswerMsg / *ErrorMsg. +func Decode(buf []byte) (MsgType, any, error) { + if len(buf) < headerSize { + return 0, nil, fmt.Errorf("message too short: %d bytes", len(buf)) + } + typ := MsgType(buf[0]) + if ver := buf[1]; ver != ProtocolVersion { + return typ, nil, fmt.Errorf("unsupported protocol version %d (want %d)", ver, ProtocolVersion) + } + + var id ExchangeID + copy(id[:], buf[2:headerSize]) + payload := buf[headerSize:] + + switch typ { + case MsgOffer: + if len(payload) != ExchangeIDSize+OfferSize { + return typ, nil, fmt.Errorf("offer payload: got %d, want %d", len(payload), ExchangeIDSize+OfferSize) + } + var ack ExchangeID + copy(ack[:], payload[:ExchangeIDSize]) + return typ, &OfferMsg{ExchangeID: id, AckID: ack, KEMOffer: payload[ExchangeIDSize:]}, nil + case MsgAnswer: + if len(payload) != AnswerSize { + return typ, nil, fmt.Errorf("answer payload: got %d, want %d", len(payload), AnswerSize) + } + return typ, &AnswerMsg{ExchangeID: id, KEMAnswer: payload}, nil + case MsgError: + if len(payload) != 0 { + return typ, nil, fmt.Errorf("error marker payload: got %d, want 0", len(payload)) + } + return typ, &ErrorMsg{ExchangeID: id}, nil + default: + return typ, nil, fmt.Errorf("unknown message type %d", typ) + } +} + +func frame(typ MsgType, id ExchangeID, payload []byte) []byte { + buf := make([]byte, headerSize+len(payload)) + buf[0] = byte(typ) + buf[1] = ProtocolVersion + copy(buf[2:], id[:]) + copy(buf[headerSize:], payload) + return buf +} + +// compile-time assurance the KEM blob sizes referenced here stay in sync with kem.go. +var _ = [1]struct{}{}[OfferSize-(32+mlkem.EncapsulationKeySize768)] diff --git a/client/internal/pqkem/message_test.go b/client/internal/pqkem/message_test.go new file mode 100644 index 00000000000..d061b9528d9 --- /dev/null +++ b/client/internal/pqkem/message_test.go @@ -0,0 +1,86 @@ +package pqkem + +import ( + "testing" + + "github.com/stretchr/testify/require" +) + +func TestMessageRoundTrip(t *testing.T) { + init, err := NewInitiator() + require.NoError(t, err) + answer, _, err := Respond(init.Offer(), Binding{LocalID: wgB, RemoteID: wgA}) + require.NoError(t, err) + + id := ExchangeID{1, 2, 3, 4} + ack := ExchangeID{9, 9, 9} + + offBytes, err := (&OfferMsg{ExchangeID: id, AckID: ack, KEMOffer: init.Offer()}).Encode() + require.NoError(t, err) + typ, decoded, err := Decode(offBytes) + require.NoError(t, err) + require.Equal(t, MsgOffer, typ) + require.Equal(t, id, decoded.(*OfferMsg).ExchangeID) + require.Equal(t, ack, decoded.(*OfferMsg).AckID) + require.Equal(t, init.Offer(), decoded.(*OfferMsg).KEMOffer) + + ansBytes, err := (&AnswerMsg{ExchangeID: id, KEMAnswer: answer}).Encode() + require.NoError(t, err) + typ, decoded, err = Decode(ansBytes) + require.NoError(t, err) + require.Equal(t, MsgAnswer, typ) + require.Equal(t, answer, decoded.(*AnswerMsg).KEMAnswer) + + // The error marker is a non-empty, payload-less message carrying the exchange id, so + // the initiator can tell a responder failure from an empty "no KEM" answer. + errBytes := (&ErrorMsg{ExchangeID: id}).Encode() + require.NotEmpty(t, errBytes) + typ, decoded, err = Decode(errBytes) + require.NoError(t, err) + require.Equal(t, MsgError, typ) + require.Equal(t, id, decoded.(*ErrorMsg).ExchangeID) +} + +func TestDecodeRejects(t *testing.T) { + // too short + _, _, err := Decode([]byte{1, 1}) + require.Error(t, err) + + // wrong version + bad := make([]byte, headerSize+ExchangeIDSize+OfferSize) + bad[0] = byte(MsgOffer) + bad[1] = ProtocolVersion + 1 + _, _, err = Decode(bad) + require.Error(t, err) + + // unknown type + bad2 := make([]byte, headerSize) + bad2[0] = 99 + bad2[1] = ProtocolVersion + _, _, err = Decode(bad2) + require.Error(t, err) + + // the encoder refuses an offer with the wrong payload size + _, err = (&OfferMsg{KEMOffer: []byte{1, 2, 3}}).Encode() + require.Error(t, err) + + // the decoder refuses a framed offer, answer or error marker whose payload has the + // wrong size + short := make([]byte, headerSize+ExchangeIDSize+OfferSize-1) + short[0] = byte(MsgOffer) + short[1] = ProtocolVersion + _, _, err = Decode(short) + require.Error(t, err, "a truncated offer must be rejected") + + long := make([]byte, headerSize+AnswerSize+1) + long[0] = byte(MsgAnswer) + long[1] = ProtocolVersion + _, _, err = Decode(long) + require.Error(t, err, "an oversized answer must be rejected") + + marker := make([]byte, headerSize+1) + marker[0] = byte(MsgError) + marker[1] = ProtocolVersion + _, _, err = Decode(marker) + require.Error(t, err, "an error marker with a payload must be rejected") +} diff --git a/client/internal/pqkem/rotation_test.go b/client/internal/pqkem/rotation_test.go new file mode 100644 index 00000000000..70fb90601a2 --- /dev/null +++ b/client/internal/pqkem/rotation_test.go @@ -0,0 +1,69 @@ +package pqkem + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// TestManager_RotationResumesAfterTimeout covers a rotation whose offers are all lost. +// The timeout must leave the rotation chain usable: the next data-path rekey has to start +// a new rotation. Deleting the exchange on timeout stopped rotation for good, since a +// rekey only chains from an exchange awaiting it, and the failure count never reached the +// threshold that triggers a Signal re-bootstrap, despite the log promising a retry. +func TestManager_RotationResumesAfterTimeout(t *testing.T) { + dA, dB, wgA, wgB, lbB := pair(t) // dB ("bbbb") initiator + defer dA.Stop() + defer dB.Stop() + dB.retryInterval = 10 * time.Millisecond + dB.maxRetries = 2 + + bootstrap(t, dA, dB) + boot := wgB.psk("aaaa") + + // Lose every rotation offer until the exchange times out. + lbB.drop.Store(true) + dB.OnDataPathRekeyed("aaaa", 0) + require.Eventually(t, func() bool { + dB.mu.Lock() + defer dB.mu.Unlock() + ex := dB.exchanges["aaaa"] + return ex == nil || ex.state != stateAwaitingAnswer + }, time.Second, 5*time.Millisecond, "the lost rotation must time out") + lbB.drop.Store(false) + + dB.OnDataPathRekeyed("aaaa", 0) + require.Eventually(t, func() bool { + return wgB.psk("aaaa") != boot && wgA.psk("bbbb") == wgB.psk("aaaa") + }, time.Second, 5*time.Millisecond, "the next rekey must start a rotation that converges") + assert.Empty(t, wgB.failed, "a single lost rotation must not escalate to a re-bootstrap") +} + +// TestManager_RepeatedRotationTimeoutsEscalate verifies the failure policy can complete: +// consecutive lost rotations must reach the rekey-failure threshold and hand recovery to +// the host. With rotation stopping after the first timeout the threshold was unreachable. +func TestManager_RepeatedRotationTimeoutsEscalate(t *testing.T) { + dA, dB, _, wgB, lbB := pair(t) // dB ("bbbb") initiator + defer dA.Stop() + defer dB.Stop() + dB.retryInterval = 10 * time.Millisecond + dB.maxRetries = 2 + + bootstrap(t, dA, dB) + lbB.drop.Store(true) + + for i := 0; i < dB.maxRekeyFailures; i++ { + dB.OnDataPathRekeyed("aaaa", 0) + require.Eventually(t, func() bool { + dB.mu.Lock() + defer dB.mu.Unlock() + ex := dB.exchanges["aaaa"] + return ex == nil || ex.state != stateAwaitingAnswer + }, time.Second, 5*time.Millisecond, "rotation %d must time out", i+1) + } + + assert.Eventually(t, func() bool { return failedCount(wgB) == 1 }, time.Second, 5*time.Millisecond, + "consecutive lost rotations must escalate to a rekey failure") +} diff --git a/client/internal/pqkem/secret_test.go b/client/internal/pqkem/secret_test.go new file mode 100644 index 00000000000..610ff07ff16 --- /dev/null +++ b/client/internal/pqkem/secret_test.go @@ -0,0 +1,73 @@ +package pqkem + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// pairWithSecrets builds a wired initiator ("bbbb") / responder ("aaaa") pair whose +// managers hold the given pre-shared secrets (nil = no secret). +func pairWithSecrets(t *testing.T, secretA, secretB []byte) (dA, dB *Manager, wgA, wgB *fakeWG) { + t.Helper() + sw := newSwitch() + wgA, wgB = newFakeWG(), newFakeWG() + dA = NewManager("aaaa", wgA, nil, WithPresharedSecret(secretA)) + dB = NewManager("bbbb", wgB, nil, WithPresharedSecret(secretB)) + dA.Start(&loopback{ep: epA, sw: sw}) + dB.Start(&loopback{ep: epB, sw: sw}) + dA.AddPeer("bbbb", epB) + dB.AddPeer("aaaa", epA) + t.Cleanup(func() { + dA.Stop() + dB.Stop() + }) + return dA, dB, wgA, wgB +} + +// TestManager_PresharedSecretBindsPSK covers the configured-secret contract (a host +// option like WireGuard's --pre-shared-key: only peers holding the same secret may +// communicate). Without binding the secret into the derivation, two peers with +// different secrets derived the same PSK and the secret was silently bypassed. The PSK +// must match only when the secrets match, for the bootstrap and for a rotation alike. +func TestManager_PresharedSecretBindsPSK(t *testing.T) { + secret1 := []byte("configured-secret-one-0123456789") + secret2 := []byte("configured-secret-two-0123456789") + cases := map[string]struct { + a, b []byte + match bool + }{ + "same secret": {a: secret1, b: secret1, match: true}, + "different secrets": {a: secret1, b: secret2, match: false}, + "only the responder has one": {a: secret1, b: nil, match: false}, + "only the initiator has one": {a: nil, b: secret1, match: false}, + "no secret": {a: nil, b: nil, match: true}, + } + for name, tc := range cases { + t.Run(name, func(t *testing.T) { + dA, dB, wgA, wgB := pairWithSecrets(t, tc.a, tc.b) + + bootstrap(t, dA, dB) + bootA, bootB := wgA.psk("bbbb"), wgB.psk("aaaa") + require.NotEqual(t, PSK{}, bootA, "responder must derive a bootstrap PSK") + require.NotEqual(t, PSK{}, bootB, "initiator must derive a bootstrap PSK") + assert.Equal(t, tc.match, bootA == bootB, "bootstrap PSKs must match only when the secrets match") + + dB.OnDataPathRekeyed("aaaa", 0) + if !tc.match { + // The peers share no PSK, so the responder cannot authenticate the data-path + // rotation offer and keeps its key: a rotation cannot bridge the secret either. + assert.Never(t, func() bool { return wgA.psk("bbbb") != bootA }, 200*time.Millisecond, 10*time.Millisecond, + "a rotation between peers with different secrets must not re-key the responder") + return + } + // Rotation over the data path re-derives the PSK; it must honour the secret too. + require.Eventually(t, func() bool { + return wgA.psk("bbbb") != bootA && wgB.psk("aaaa") != bootB + }, time.Second, 5*time.Millisecond, "the rotation must re-key both peers") + assert.Equal(t, wgA.psk("bbbb"), wgB.psk("aaaa"), "rotated PSKs must match when the secrets match") + }) + } +} diff --git a/client/internal/pqkem/split_test.go b/client/internal/pqkem/split_test.go new file mode 100644 index 00000000000..412953266da --- /dev/null +++ b/client/internal/pqkem/split_test.go @@ -0,0 +1,122 @@ +package pqkem + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// TestManager_ResponderOfferRebootstrapsSplitKeys reproduces a split PSK and checks that a +// reconnect started by the responder heals it. When every answer of a rotation is lost, +// the responder has committed the new PSK and the initiator has not, so WireGuard can no +// longer handshake. The connection layer then reconnects, and the reconnect offer may come +// from the responder, carrying no KEM. The controller used to answer it normally whenever +// it held a converged exchange, keeping its stale key, so the tunnel stayed down. A +// responder offer must instead be answered with a fresh KEM bootstrap. +func TestManager_ResponderOfferRebootstrapsSplitKeys(t *testing.T) { + sw := newSwitch() + wgA, wgB := newFakeWG(), newFakeWG() + dA := NewManager("aaaa", wgA, nil) // responder + dB := NewManager("bbbb", wgB, nil) // initiator (controller) + dB.retryInterval = 10 * time.Millisecond + dB.maxRetries = 2 + lbA := &loopback{ep: epA, sw: sw} + dA.Start(lbA) + dB.Start(&loopback{ep: epB, sw: sw}) + dA.AddPeer("bbbb", epB) + dB.AddPeer("aaaa", epA) + defer dA.Stop() + defer dB.Stop() + + bootstrap(t, dA, dB) + + // Lose every answer of a rotation: the responder commits, the initiator times out. + lbA.drop.Store(true) + dB.OnDataPathRekeyed("aaaa", 0) + require.Eventually(t, func() bool { + dB.mu.Lock() + defer dB.mu.Unlock() + ex := dB.exchanges["aaaa"] + return ex == nil || ex.state != stateAwaitingAnswer + }, time.Second, 5*time.Millisecond, "the rotation must time out on the initiator") + lbA.drop.Store(false) + require.NotEqual(t, wgA.psk("bbbb"), wgB.psk("aaaa"), "precondition: the two PSKs are split") + + // The responder's reconnect offer carries no KEM: the controller must answer it with + // a fresh bootstrap, which brings both peers back to one PSK. + require.True(t, dB.ShouldSendBootstrapOffer("aaaa"), + "a controller holding a converged exchange must still re-bootstrap on a responder offer") + bootstrap(t, dA, dB) + assert.Equal(t, wgA.psk("bbbb"), wgB.psk("aaaa"), "the re-bootstrap must heal the split PSKs") +} + +// TestManager_NoRebootstrapWhileExchangeInFlight keeps the glare protection: while the +// controller's own exchange is waiting for its answer, a crossing responder offer must not +// start a second exchange, which would supersede the first and churn the keys. +func TestManager_NoRebootstrapWhileExchangeInFlight(t *testing.T) { + dA, dB, _, _, _ := pair(t) + defer dA.Stop() + defer dB.Stop() + + offer, err := dB.SignalOffer("aaaa") + require.NoError(t, err) + require.NotNil(t, offer, "the controller's bootstrap must be in flight") + + assert.False(t, dB.ShouldSendBootstrapOffer("aaaa"), + "no second exchange while the controller's own offer awaits its answer") +} + +// TestManager_SignalOfferInFlight: only our own bootstrap offer over signalling, still +// awaiting its answer, makes a crossing responder offer a glare. A converged exchange, a +// data-path rotation, or the responder role must not. +func TestManager_SignalOfferInFlight(t *testing.T) { + dA, dB, _, _, _ := pair(t) // dB ("bbbb") initiator + defer dA.Stop() + defer dB.Stop() + + assert.False(t, dB.SignalOfferInFlight("aaaa"), "no exchange yet: nothing in flight") + + offer, err := dB.SignalOffer("aaaa") + require.NoError(t, err) + require.NotNil(t, offer) + assert.True(t, dB.SignalOfferInFlight("aaaa"), "our bootstrap offer awaits its answer") + assert.False(t, dA.SignalOfferInFlight("bbbb"), "the responder never has a signalling offer in flight") + + answer, err := dA.SignalOnOffer("bbbb", offer) + require.NoError(t, err) + require.NoError(t, dB.SignalOnAnswer("aaaa", answer)) + assert.False(t, dB.SignalOfferInFlight("aaaa"), "a converged exchange is not in flight") + + _, err = dB.startExchangeTest("aaaa", false, ExchangeID{}) + require.NoError(t, err) + assert.False(t, dB.SignalOfferInFlight("aaaa"), "a data-path rotation is not a signalling offer") +} + +// TestManager_ResentSignalOfferIsTheSameExchange backs the glare resend: while our +// bootstrap offer awaits its answer, building the offer again must return the same bytes, +// not start a second exchange, and the responder must answer the duplicate from its cache +// so both sides still derive one PSK. +func TestManager_ResentSignalOfferIsTheSameExchange(t *testing.T) { + dA, dB, wgA, wgB, _ := pair(t) // dB ("bbbb") initiator + defer dA.Stop() + defer dB.Stop() + + first, err := dB.SignalOffer("aaaa") + require.NoError(t, err) + resent, err := dB.SignalOffer("aaaa") + require.NoError(t, err) + assert.Equal(t, first, resent, "a resend while in flight must carry the same offer") + + answer, err := dA.SignalOnOffer("bbbb", first) + require.NoError(t, err) + duplicateAnswer, err := dA.SignalOnOffer("bbbb", resent) + require.NoError(t, err) + assert.Equal(t, answer, duplicateAnswer, "the responder must answer a duplicate offer from its cache") + + require.NoError(t, dB.SignalOnAnswer("aaaa", answer)) + require.NoError(t, dB.SignalOnAnswer("aaaa", duplicateAnswer)) + assert.NotEqual(t, PSK{}, wgB.psk("aaaa")) + assert.Equal(t, wgB.psk("aaaa"), wgA.psk("bbbb"), "a resent offer must still converge on one PSK") +} diff --git a/client/internal/pqkem_adapter.go b/client/internal/pqkem_adapter.go new file mode 100644 index 00000000000..3079fcbd178 --- /dev/null +++ b/client/internal/pqkem_adapter.go @@ -0,0 +1,294 @@ +package internal + +import ( + "net/netip" + "sync" + "time" + + log "github.com/sirupsen/logrus" + "golang.zx2c4.com/wireguard/wgctrl/wgtypes" + + "github.com/netbirdio/netbird/client/internal/pqkem" +) + +// appliedGenerations records the newest PSK generation applied per peer, so an +// out-of-order OnNewPSKReady (two exchanges deriving concurrently) can't restore an +// older PSK over a newer one. +type appliedGenerations struct { + mu sync.Mutex + last map[string]uint64 +} + +func newAppliedGenerations() *appliedGenerations { + return &appliedGenerations{last: make(map[string]uint64)} +} + +// apply runs set when gen is newer than the last generation applied for the peer, and +// reports whether it ran. The check and set run under one lock: with only the check +// atomic, an older apply already inside set could finish after a newer one and restore +// its stale key. The generation is recorded before set runs, so a failed newer apply +// still keeps an older one from landing afterwards. The lock is shared by all peers, +// which is cheap because set is a quick local interface call. +func (a *appliedGenerations) apply(peer string, gen uint64, set func() error) (bool, error) { + a.mu.Lock() + defer a.mu.Unlock() + if gen <= a.last[peer] { + return false, nil + } + a.last[peer] = gen + return true, set() +} + +// locked runs fn under the apply lock, so it is ordered with every PSK push. +func (a *appliedGenerations) locked(fn func()) { + a.mu.Lock() + defer a.mu.Unlock() + fn() +} + +// pqPSKSource is the subset of the ML-KEM manager the reapply needs. *pqkem.Manager +// satisfies it. +type pqPSKSource interface { + PSK(remoteID pqkem.RemoteID) (pqkem.PSK, bool) +} + +// pqPSKReapplier programs the latest PQ PSK again after a WireGuard configure that may +// have used a stale one. The conn reads the PSK before configuring, and a rotation that +// commits in between pushes its key first, which the configure then overwrites. +type pqPSKReapplier struct { + psks pqPSKSource + wg pqPresharedKeySetter + applied *appliedGenerations +} + +// reapply reads the latest PSK under the apply lock: a push already done is visible in +// it, and a later push of a newer key runs after this one and wins. +func (r *pqPSKReapplier) reapply(peer string, programmed *wgtypes.Key) { + r.applied.locked(func() { + psk, ok := r.psks.PSK(pqkem.RemoteID(peer)) + if !ok || (programmed != nil && wgtypes.Key(psk) == *programmed) { + return + } + log.Debugf("pqkem: reprogramming the latest PSK for peer %s after a stale configure", peer) + if err := r.wg.SetPresharedKey(peer, wgtypes.Key(psk), true); err != nil { + log.Warnf("pqkem: reprogram PSK for peer %s: %v", peer, err) + } + }) +} + +// pqPresharedKeySetter is the subset of the WireGuard interface the ML-KEM callback +// needs: programming a peer's preshared key. *iface.WGIface satisfies it. +type pqPresharedKeySetter interface { + SetPresharedKey(peerKey string, psk wgtypes.Key, updateOnly bool) error +} + +// pqStatusMarker is the subset of the status recorder ML-KEM needs: flagging a peer as +// post-quantum protected once its PSK is programmed, and clearing the flag when the peer +// downgrades. *peer.Status satisfies it. +type pqStatusMarker interface { + MarkPeerQuantumResistant(peerPubKey string) error + UnmarkPeerQuantumResistant(peerPubKey string) error +} + +// pqCallbackHandler programs the derived PQ PSK onto the WireGuard peer. It is the +// engine-side implementation of pqkem.CallbackHandler. +type pqCallbackHandler struct { + wg pqPresharedKeySetter + // status reflects a newly programmed PSK in the peer's "Quantum resistance" flag. + // Nil disables it. + status pqStatusMarker + // applied drops an out-of-order PSK apply so a stale callback can't overwrite a newer + // key. Nil disables the guard. + applied *appliedGenerations + // recoverPQKeyOverSignal re-bootstraps the KEM over Signal for a peer (a fresh + // signalling offer) after its exchange failed. Nil disables recovery. + recoverPQKeyOverSignal func(remoteKey string) +} + +// OnNewPSKReady programs the freshly derived PSK for the peer (updateOnly: a no-op +// if the peer is not present, mirroring Rosenpass). A callback whose generation is not +// newer than the last applied for the peer is dropped, so a reordered apply can't +// restore an older PSK over a newer one. +func (h pqCallbackHandler) OnNewPSKReady(remoteID pqkem.RemoteID, gen uint64, psk pqkem.PSK) error { + // updateOnly: applies to an already-configured peer (rotation). At bootstrap the + // peer is not configured yet, so this is a no-op there and the PSK is instead + // pulled at peer-config time (pqHandshaker.PSK / conn.presharedKey). + set := func() error { + log.Tracef("pqkem: programming PSK for peer %s (gen %d)", remoteID, gen) + return h.wg.SetPresharedKey(string(remoteID), wgtypes.Key(psk), true) + } + if h.applied == nil { + if err := set(); err != nil { + return err + } + } else { + applied, err := h.applied.apply(string(remoteID), gen, set) + if err != nil { + return err + } + if !applied { + log.Tracef("pqkem: dropping stale PSK apply for peer %s (gen %d)", remoteID, gen) + return nil + } + } + // The status flag is computed when the connection comes up; a PSK landing afterwards + // would otherwise leave the peer reported as not quantum resistant. + if h.status != nil { + if err := h.status.MarkPeerQuantumResistant(string(remoteID)); err != nil { + log.Debugf("pqkem: mark peer %s quantum resistant in status: %v", remoteID, err) + } + } + return nil +} + +// OnRekeyFailed reports a failed PQ (re)key convergence and re-bootstraps the KEM over +// Signal to recover: a fresh signalling offer starts a new exchange that overwrites the +// stalled PSK on both sides, resyncing after a persistent data-path desync. The tunnel +// stays up on the previous PSK meanwhile (the Signal channel is independent of the +// broken data path). +func (h pqCallbackHandler) OnRekeyFailed(remoteID pqkem.RemoteID) error { + log.Debugf("pqkem: post-quantum key exchange failed for peer %s", remoteID) + if h.recoverPQKeyOverSignal != nil { + h.recoverPQKeyOverSignal(string(remoteID)) + } + return nil +} + +// pqHandshaker adapts the pqkem manager to peer.PQHandshaker (string peer keys), +// wiring the host's signalling offers/answers to the KEM exchange. +type pqHandshaker struct { + mgr *pqkem.Manager + // reapplier restores the latest PSK after a stale WireGuard configure. Nil disables it. + reapplier *pqPSKReapplier + // status clears the peer's "Quantum resistance" flag when it downgrades. Nil disables it. + status pqStatusMarker +} + +// announcedPort is the PQ data-path port to advertise to peers. It is sent even on +// DefaultPort: a non-zero port is how a peer that runs the KEM announces it, and a +// responder's offer carries nothing else that could (see SetRemoteAddr). +func (p pqHandshaker) announcedPort() uint16 { + return uint16(p.mgr.LocalPort()) +} + +// markNonCapable records that the peer sent no KEM where one was due, and clears its +// status flag when that drops the PSK we held with it. +func (p pqHandshaker) markNonCapable(remoteKey string) { + if !p.mgr.MarkNonCapable(pqkem.RemoteID(remoteKey)) || p.status == nil { + return + } + if err := p.status.UnmarkPeerQuantumResistant(remoteKey); err != nil { + log.Debugf("pqkem: unmark peer %s quantum resistant in status: %v", remoteKey, err) + } +} + +// OfferPayload builds the KEM offer to attach to an outgoing signalling offer for the +// peer, plus the data-path port to announce (0 when on DefaultPort). Payload is nil when +// this side has no offer to send. +func (p pqHandshaker) OfferPayload(remoteKey string) ([]byte, uint16) { + payload, err := p.mgr.SignalOffer(pqkem.RemoteID(remoteKey)) + if err != nil { + log.Warnf("pqkem: build offer for %s: %v", remoteKey, err) + } + return payload, p.announcedPort() +} + +// ShouldSendBootstrapOffer reports whether the controller should reply to the peer's +// KEM-less offer with its own bootstrap offer instead of an answer. +func (p pqHandshaker) ShouldSendBootstrapOffer(remoteKey string) bool { + return p.mgr.ShouldSendBootstrapOffer(pqkem.RemoteID(remoteKey)) +} + +// SignalOfferInFlight reports whether our KEM offer over signalling to the peer still +// awaits its answer. +func (p pqHandshaker) SignalOfferInFlight(remoteKey string) bool { + return p.mgr.SignalOfferInFlight(pqkem.RemoteID(remoteKey)) +} + +// AnswerPayload processes a received KEM offer (nil when absent) and returns the KEM +// answer to attach to the outgoing signalling answer, plus the data-path port to announce +// (0 when on DefaultPort). An empty offer is treated as a capability signal. +func (p pqHandshaker) AnswerPayload(remoteKey string, recvOffer []byte) ([]byte, uint16) { + if len(recvOffer) == 0 { + // Capability signal (responder side): the KEM offer flows initiator->responder, + // so if we are the responder for this peer (it is the KEM initiator by role) an + // empty offer means it does not run the KEM. If we are the initiator, an empty + // offer is normal — the peer is the responder and puts its material in the + // answer — so we must not flag it. + if !p.mgr.IsInitiator(pqkem.RemoteID(remoteKey)) { + p.markNonCapable(remoteKey) + } + return nil, p.announcedPort() + } + payload, err := p.mgr.SignalOnOffer(pqkem.RemoteID(remoteKey), recvOffer) + if err != nil { + log.Warnf("pqkem: build answer for %s: %v", remoteKey, err) + } + return payload, p.announcedPort() +} + +// OnAnswer feeds a received KEM answer (nil when absent) into the exchange. An empty +// answer to our offer is treated as a capability signal on the initiator side. +func (p pqHandshaker) OnAnswer(remoteKey string, recvAnswer []byte) { + if len(recvAnswer) == 0 { + // Capability signal (initiator side): an empty answer to our KEM offer means the + // peer does not run the KEM, so mark it non-capable to stop offering (no + // failure/recovery storm). Answering an offer that carried no KEM, an empty answer + // says nothing, from either role. + if p.mgr.SignalOfferInFlight(pqkem.RemoteID(remoteKey)) { + p.markNonCapable(remoteKey) + } + return + } + if err := p.mgr.SignalOnAnswer(pqkem.RemoteID(remoteKey), recvAnswer); err != nil { + log.Warnf("pqkem: process answer from %s: %v", remoteKey, err) + } +} + +// PSK exposes the peer's derived PSK for the conn to program at WG peer-config time. +func (p pqHandshaker) PSK(remoteKey string) (wgtypes.Key, bool) { + psk, ok := p.mgr.PSK(pqkem.RemoteID(remoteKey)) + if !ok { + return wgtypes.Key{}, false + } + return wgtypes.Key(psk), true +} + +// ReapplyPSK programs the peer's latest PSK again when the conn configured WireGuard with +// a different one. +func (p pqHandshaker) ReapplyPSK(remoteKey string, programmed *wgtypes.Key) { + if p.reapplier != nil { + p.reapplier.reapply(remoteKey, programmed) + } +} + +// SetRemoteAddr registers the peer's data-path endpoint learned from signalling. Sends +// only ever fire once the tunnel is up (clocked by OnDataPathRekeyed), so registering here +// is safe even before connection-up. A non-zero port means the peer runs the KEM, so one +// found non-capable earlier is offered it again; this is how a peer that enabled ML-KEM +// after we met it gets upgraded. A zero port comes from a peer that does not run the KEM +// and is resolved to DefaultPort, harmlessly, since nothing is sent to such a peer. +func (p pqHandshaker) SetRemoteAddr(remoteKey string, addr netip.AddrPort) { + if !addr.Addr().IsValid() { + return + } + port := addr.Port() + if port == 0 { + port = DefaultPort + } else { + p.mgr.ClearNonCapable(pqkem.RemoteID(remoteKey)) + } + p.mgr.AddPeer(pqkem.RemoteID(remoteKey), netip.AddrPortFrom(addr.Addr(), port)) +} + +// OnDataPathRekeyed clocks the next chained PSK rotation on a fresh WG handshake. +// sinceActivity is how long ago the peer last exchanged real user data; the manager +// skips rotation for idle tunnels. +func (p pqHandshaker) OnDataPathRekeyed(remoteKey string, sinceActivity time.Duration) { + p.mgr.OnDataPathRekeyed(pqkem.RemoteID(remoteKey), sinceActivity) +} + +// OnDataPathDown signals the peer's tunnel went down. +func (p pqHandshaker) OnDataPathDown(remoteKey string) { + p.mgr.OnDataPathDown(pqkem.RemoteID(remoteKey)) +} diff --git a/client/internal/pqkem_adapter_test.go b/client/internal/pqkem_adapter_test.go new file mode 100644 index 00000000000..a75aa9b9980 --- /dev/null +++ b/client/internal/pqkem_adapter_test.go @@ -0,0 +1,389 @@ +package internal + +import ( + "errors" + "net/netip" + "sync" + "testing" + "time" + + log "github.com/sirupsen/logrus" + logtest "github.com/sirupsen/logrus/hooks/test" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "golang.zx2c4.com/wireguard/wgctrl/wgtypes" + + "github.com/netbirdio/netbird/client/internal/peer" + "github.com/netbirdio/netbird/client/internal/pqkem" +) + +// fakePSKSetter records PSK programming and can be made to fail. +type fakePSKSetter struct { + err error + calls int +} + +func (f *fakePSKSetter) SetPresharedKey(string, wgtypes.Key, bool) error { + f.calls++ + return f.err +} + +const pqTestPeerKey = "eDQmZp9jhQGX7XdYpHGaFSpAouldr3Sbf7MZRcGTGGQ=" + +func newPQTestStatus(t *testing.T) *peer.Status { + t.Helper() + status := peer.NewRecorder("https://mgm") + require.NoError(t, status.AddPeer(pqTestPeerKey, "peer.netbird.cloud", "100.64.0.2", "")) + return status +} + +// TestPQCallbackHandler_MarksPeerQuantumResistant reproduces the stale status flag: when +// the KEM answer lands after the connection was set up, the per-peer "Quantum resistance" +// flag was computed without a PSK and never refreshed. Programming the PSK must flag it. +func TestPQCallbackHandler_MarksPeerQuantumResistant(t *testing.T) { + status := newPQTestStatus(t) + setter := &fakePSKSetter{} + h := pqCallbackHandler{wg: setter, applied: newAppliedGenerations(), status: status} + + require.NoError(t, h.OnNewPSKReady(pqkem.RemoteID(pqTestPeerKey), 1, pqkem.PSK{1})) + + st, err := status.GetPeer(pqTestPeerKey) + require.NoError(t, err) + assert.Equal(t, 1, setter.calls, "the PSK must be programmed once") + assert.True(t, st.RosenpassEnabled, "a programmed PQ PSK must mark the peer quantum resistant") +} + +// TestPQCallbackHandler_FailedApplyKeepsFlag verifies the flag only follows a PSK that was +// actually programmed: a failed SetPresharedKey must leave the peer unflagged. +func TestPQCallbackHandler_FailedApplyKeepsFlag(t *testing.T) { + status := newPQTestStatus(t) + h := pqCallbackHandler{wg: &fakePSKSetter{err: errors.New("boom")}, applied: newAppliedGenerations(), status: status} + + require.Error(t, h.OnNewPSKReady(pqkem.RemoteID(pqTestPeerKey), 1, pqkem.PSK{1})) + + st, err := status.GetPeer(pqTestPeerKey) + require.NoError(t, err) + assert.False(t, st.RosenpassEnabled, "a PSK that failed to program must not mark the peer quantum resistant") +} + +// TestPQCallbackHandler_UnknownStatusPeerDoesNotFailApply verifies the status update is +// best-effort: a peer missing from the status recorder must not fail the PSK apply. +func TestPQCallbackHandler_UnknownStatusPeerDoesNotFailApply(t *testing.T) { + setter := &fakePSKSetter{} + h := pqCallbackHandler{wg: setter, applied: newAppliedGenerations(), status: peer.NewRecorder("https://mgm")} + + assert.NoError(t, h.OnNewPSKReady(pqkem.RemoteID(pqTestPeerKey), 1, pqkem.PSK{1})) + assert.Equal(t, 1, setter.calls, "the PSK must still be programmed") +} + +// TestAppliedGenerations_DropsStale verifies the out-of-order guard: a generation is +// accepted only when it is strictly newer than the last one applied for that peer, so a +// reordered PSK callback cannot restore an older key over a newer one. +func TestAppliedGenerations_DropsStale(t *testing.T) { + a := newAppliedGenerations() + accept := func(peer string, gen uint64) bool { + ran, err := a.apply(peer, gen, func() error { return nil }) + require.NoError(t, err) + return ran + } + + if !accept("peerA", 1) { + t.Fatal("first generation must be accepted") + } + if !accept("peerA", 2) { + t.Fatal("a newer generation must be accepted") + } + if accept("peerA", 2) { + t.Fatal("re-applying the same generation must be dropped") + } + if accept("peerA", 1) { + t.Fatal("an older generation arriving late must be dropped") + } + if !accept("peerA", 3) { + t.Fatal("a newer generation after a dropped stale one must still be accepted") + } + + // Generations are tracked independently per peer. + if !accept("peerB", 1) { + t.Fatal("a different peer's first generation must be accepted") + } +} + +// blockingPSKSetter holds the first SetPresharedKey call until released, recording the +// key WireGuard ends up with. +type blockingPSKSetter struct { + mu sync.Mutex + calls int + last wgtypes.Key + entered chan struct{} + release chan struct{} +} + +func (s *blockingPSKSetter) SetPresharedKey(_ string, psk wgtypes.Key, _ bool) error { + s.mu.Lock() + s.calls++ + first := s.calls == 1 + s.mu.Unlock() + if first { + close(s.entered) + <-s.release + } + s.mu.Lock() + s.last = psk + s.mu.Unlock() + return nil +} + +// TestPQCallbackHandler_AppliesGenerationsInOrder covers two PSK callbacks for one peer +// overlapping. The newer generation must be the one WireGuard keeps: with the generation +// checked under a lock but the key set outside it, an older apply that was already +// writing could finish last and restore its stale key. +func TestPQCallbackHandler_AppliesGenerationsInOrder(t *testing.T) { + setter := &blockingPSKSetter{entered: make(chan struct{}), release: make(chan struct{})} + h := pqCallbackHandler{wg: setter, applied: newAppliedGenerations()} + older, newer := pqkem.PSK{3}, pqkem.PSK{4} + + var wg sync.WaitGroup + wg.Add(2) + go func() { + defer wg.Done() + assert.NoError(t, h.OnNewPSKReady(pqkem.RemoteID(pqTestPeerKey), 3, older)) + }() + <-setter.entered // the older apply is now inside SetPresharedKey + + go func() { + defer wg.Done() + assert.NoError(t, h.OnNewPSKReady(pqkem.RemoteID(pqTestPeerKey), 4, newer)) + }() + // Give the newer apply the chance to overtake the blocked older one. + time.Sleep(50 * time.Millisecond) + close(setter.release) + wg.Wait() + + setter.mu.Lock() + defer setter.mu.Unlock() + assert.Equal(t, wgtypes.Key(newer), setter.last, "WireGuard must keep the newest generation's PSK") +} + +// fakePSKSource returns a fixed PSK for every peer. +type fakePSKSource struct { + psk pqkem.PSK + ok bool +} + +func (f fakePSKSource) PSK(pqkem.RemoteID) (pqkem.PSK, bool) { return f.psk, f.ok } + +// recordingPSKSetter records the last key programmed. +type recordingPSKSetter struct { + calls int + last wgtypes.Key +} + +func (r *recordingPSKSetter) SetPresharedKey(_ string, psk wgtypes.Key, _ bool) error { + r.calls++ + r.last = psk + return nil +} + +// TestPQPSKReapplier_RestoresRotatedKey reproduces a configure that read the PSK before a +// rotation committed: WireGuard was configured with the old key while the manager already +// holds the new one, and the push of the new key was overwritten. The reapply must +// program the new key again. +func TestPQPSKReapplier_RestoresRotatedKey(t *testing.T) { + stale, latest := wgtypes.Key{1}, pqkem.PSK{2} + setter := &recordingPSKSetter{} + r := &pqPSKReapplier{psks: fakePSKSource{psk: latest, ok: true}, wg: setter, applied: newAppliedGenerations()} + + r.reapply(pqTestPeerKey, &stale) + + assert.Equal(t, 1, setter.calls, "a stale configure must be followed by one reprogram") + assert.Equal(t, wgtypes.Key(latest), setter.last, "WireGuard must end on the latest PSK") +} + +// TestPQPSKReapplier_StrictSentinelReplaced covers strict mode: the configure programmed +// the sentinel because no PSK existed yet, and the first PSK landed right after. +func TestPQPSKReapplier_StrictSentinelReplaced(t *testing.T) { + sentinel, first := wgtypes.Key{9}, pqkem.PSK{3} + setter := &recordingPSKSetter{} + r := &pqPSKReapplier{psks: fakePSKSource{psk: first, ok: true}, wg: setter, applied: newAppliedGenerations()} + + r.reapply(pqTestPeerKey, &sentinel) + + assert.Equal(t, wgtypes.Key(first), setter.last, "the sentinel must be replaced by the first PQ PSK") +} + +// TestPQPSKReapplier_NoWriteWhenCurrent: the common case, where the configure already used +// the latest PSK or none exists yet, must not touch WireGuard. +func TestPQPSKReapplier_NoWriteWhenCurrent(t *testing.T) { + current := pqkem.PSK{4} + programmed := wgtypes.Key(current) + + setter := &recordingPSKSetter{} + r := &pqPSKReapplier{psks: fakePSKSource{psk: current, ok: true}, wg: setter, applied: newAppliedGenerations()} + r.reapply(pqTestPeerKey, &programmed) + assert.Zero(t, setter.calls, "a configure with the latest PSK needs no reprogram") + + r = &pqPSKReapplier{psks: fakePSKSource{}, wg: setter, applied: newAppliedGenerations()} + r.reapply(pqTestPeerKey, nil) + assert.Zero(t, setter.calls, "with no PSK derived yet there is nothing to reprogram") +} + +// lockCheckingSource records whether the apply lock was held when the PSK was read. +type lockCheckingSource struct { + applied *appliedGenerations + lockedRead bool +} + +func (l *lockCheckingSource) PSK(pqkem.RemoteID) (pqkem.PSK, bool) { + if l.applied.mu.TryLock() { + l.applied.mu.Unlock() + } else { + l.lockedRead = true + } + return pqkem.PSK{5}, true +} + +// TestPQPSKReapplier_ReadsUnderApplyLock checks the reapply reads the PSK while holding the +// lock the rotation push takes. Reading it outside would let a push land between the read +// and the write, and the reapply would restore the key it was meant to replace. +func TestPQPSKReapplier_ReadsUnderApplyLock(t *testing.T) { + applied := newAppliedGenerations() + src := &lockCheckingSource{applied: applied} + r := &pqPSKReapplier{psks: src, wg: &recordingPSKSetter{}, applied: applied} + + r.reapply(pqTestPeerKey, &wgtypes.Key{1}) + + assert.True(t, src.lockedRead, "the PSK must be read under the apply lock") +} + +// pqInitiatorKey sorts above pqTestPeerKey, so its manager is the KEM initiator. +const pqInitiatorKey = "kXQmZp9jhQGX7XdYpHGaFSpAouldr3Sbf7MZRcGTGGQ=" + +var pqTestOverlay = netip.MustParseAddr("100.64.0.9") + +// pqStubTransport is a bound PQ data path that never delivers anything; signalling is all +// these tests exercise. +type pqStubTransport struct{} + +func (pqStubTransport) Send(netip.AddrPort, []byte) error { return nil } +func (pqStubTransport) LocalPort() int { return DefaultPort } +func (pqStubTransport) Run(func(netip.AddrPort, []byte)) {} +func (pqStubTransport) Close() error { return nil } + +// newPQHandshakerPair builds the initiator and responder handshakers over real managers. +// The tests play the host, carrying payloads between them as signalling would. +func newPQHandshakerPair(t *testing.T) (initiator, responder pqHandshaker) { + t.Helper() + mI := pqkem.NewManager(pqkem.LocalID(pqInitiatorKey), pqCallbackHandler{wg: &fakePSKSetter{}}, nil) + mR := pqkem.NewManager(pqkem.LocalID(pqTestPeerKey), pqCallbackHandler{wg: &fakePSKSetter{}}, nil) + mI.Start(pqStubTransport{}) + mR.Start(pqStubTransport{}) + t.Cleanup(mI.Stop) + t.Cleanup(mR.Stop) + require.True(t, mI.IsInitiator(pqkem.RemoteID(pqTestPeerKey)), "precondition: roles") + return pqHandshaker{mgr: mI}, pqHandshaker{mgr: mR} +} + +// pqSignalBootstrap runs one signalling offer/answer round that carries the KEM. +func pqSignalBootstrap(t *testing.T, hI, hR pqHandshaker) { + t.Helper() + offer, _ := hI.OfferPayload(pqTestPeerKey) + require.NotEmpty(t, offer, "the initiator must offer the KEM") + answer, _ := hR.AnswerPayload(pqInitiatorKey, offer) + require.NotEmpty(t, answer, "the responder must answer the KEM") + hI.OnAnswer(pqTestPeerKey, answer) + _, okI := hI.PSK(pqTestPeerKey) + _, okR := hR.PSK(pqInitiatorKey) + require.True(t, okI && okR, "precondition: both sides hold a PQ PSK") +} + +// TestPQHandshaker_InitiatorDowngrade: the initiator restarts without ML-KEM, so its next +// offer carries no KEM. The responder must drop its PSK, or it keeps programming a key the +// peer no longer has and the WireGuard handshake never completes. +func TestPQHandshaker_InitiatorDowngrade(t *testing.T) { + hI, hR := newPQHandshakerPair(t) + pqSignalBootstrap(t, hI, hR) + status := peer.NewRecorder("https://mgm") + require.NoError(t, status.AddPeer(pqInitiatorKey, "initiator.netbird.cloud", "100.64.0.3", "")) + require.NoError(t, status.MarkPeerQuantumResistant(pqInitiatorKey)) + hR.status = status + + hR.AnswerPayload(pqInitiatorKey, nil) + + _, ok := hR.PSK(pqInitiatorKey) + assert.False(t, ok, "a KEM-less offer from an established initiator must drop the PQ PSK") + st, err := status.GetPeer(pqInitiatorKey) + require.NoError(t, err) + assert.False(t, st.RosenpassEnabled, "a downgraded peer must not be reported quantum resistant") +} + +// TestPQHandshaker_ResponderDowngrade: the responder restarts without ML-KEM and answers +// our KEM offer with nothing. The initiator must drop its PSK. +func TestPQHandshaker_ResponderDowngrade(t *testing.T) { + hI, hR := newPQHandshakerPair(t) + pqSignalBootstrap(t, hI, hR) + status := newPQTestStatus(t) + require.NoError(t, status.MarkPeerQuantumResistant(pqTestPeerKey)) + hI.status = status + + offer, _ := hI.OfferPayload(pqTestPeerKey) + require.NotEmpty(t, offer, "an established initiator still offers on a new signalling round") + hI.OnAnswer(pqTestPeerKey, nil) + + _, ok := hI.PSK(pqTestPeerKey) + assert.False(t, ok, "a KEM-less answer to our KEM offer must drop the PQ PSK") + st, err := status.GetPeer(pqTestPeerKey) + require.NoError(t, err) + assert.False(t, st.RosenpassEnabled, "a downgraded peer must not be reported quantum resistant") +} + +// TestPQHandshaker_NonCapablePeerUpgrades: the responder ran without ML-KEM, so the +// initiator marked it non-capable. Once it restarts with ML-KEM it announces its PQ port, +// and the initiator must offer the KEM again instead of staying classical until restart. +func TestPQHandshaker_NonCapablePeerUpgrades(t *testing.T) { + hI, hR := newPQHandshakerPair(t) + + offer, _ := hI.OfferPayload(pqTestPeerKey) + require.NotEmpty(t, offer) + hI.OnAnswer(pqTestPeerKey, nil) + require.False(t, hI.ShouldSendBootstrapOffer(pqTestPeerKey), "precondition: marked non-capable") + + _, port := hR.AnswerPayload(pqInitiatorKey, nil) + require.NotZero(t, port, "a peer running ML-KEM must announce its PQ port") + hI.SetRemoteAddr(pqTestPeerKey, netip.AddrPortFrom(pqTestOverlay, port)) + + assert.True(t, hI.ShouldSendBootstrapOffer(pqTestPeerKey), "an announced PQ port must make the peer worth a KEM offer again") + pqSignalBootstrap(t, hI, hR) +} + +// TestPQHandshaker_EmptyAnswerWithoutOfferKeepsHint: an empty answer is only a capability +// signal when it answers our KEM offer. Answering an offer that carried no KEM, it says +// nothing, and must not undo the PQ port the same answer announced. +func TestPQHandshaker_EmptyAnswerWithoutOfferKeepsHint(t *testing.T) { + hI, _ := newPQHandshakerPair(t) + + offer, _ := hI.OfferPayload(pqTestPeerKey) + require.NotEmpty(t, offer) + hI.OnAnswer(pqTestPeerKey, nil) + + hI.SetRemoteAddr(pqTestPeerKey, netip.AddrPortFrom(pqTestOverlay, 1)) + hI.OnAnswer(pqTestPeerKey, nil) + + assert.True(t, hI.ShouldSendBootstrapOffer(pqTestPeerKey), "an empty answer with no KEM offer in flight must not mark the peer non-capable") +} + +// TestPQCallbackHandler_RekeyFailedLeavesSeverityToConn: the handler cannot tell an +// offline peer from a real failure, so it must not warn; the connection decides. +func TestPQCallbackHandler_RekeyFailedLeavesSeverityToConn(t *testing.T) { + hook := logtest.NewGlobal() + defer hook.Reset() + + var recovered []string + h := pqCallbackHandler{recoverPQKeyOverSignal: func(k string) { recovered = append(recovered, k) }} + require.NoError(t, h.OnRekeyFailed(pqkem.RemoteID(pqTestPeerKey))) + + assert.Equal(t, []string{pqTestPeerKey}, recovered, "the failure must still be handed to the connection") + for _, e := range hook.AllEntries() { + assert.Greater(t, e.Level, log.WarnLevel, "unexpected %s: %s", e.Level, e.Message) + } +} diff --git a/client/internal/pqkem_signal_test.go b/client/internal/pqkem_signal_test.go new file mode 100644 index 00000000000..9118802e943 --- /dev/null +++ b/client/internal/pqkem_signal_test.go @@ -0,0 +1,35 @@ +package internal + +import ( + "math" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + sProto "github.com/netbirdio/netbird/shared/signal/proto" +) + +func signalOfferWithMlkemPort(port uint32) *sProto.Message { + return &sProto.Message{Body: &sProto.Body{ + Type: sProto.Body_OFFER, + Payload: "ufrag:pwd", + MlkemPort: &port, + }} +} + +// TestConvertToOfferAnswer_MlkemPort checks that the proto's 32-bit ML-KEM port is narrowed +// to uint16 only when it fits: a larger value is a malformed message, not a port to +// truncate. +func TestConvertToOfferAnswer_MlkemPort(t *testing.T) { + for _, port := range []uint32{0, 51833, math.MaxUint16} { + oa, err := convertToOfferAnswer(signalOfferWithMlkemPort(port)) + require.NoError(t, err, "port %d", port) + assert.Equal(t, uint16(port), oa.MlkemPort, "port %d must survive the conversion", port) + } + + for _, port := range []uint32{math.MaxUint16 + 1, math.MaxUint32} { + _, err := convertToOfferAnswer(signalOfferWithMlkemPort(port)) + assert.Error(t, err, "port %d does not fit in uint16 and must be rejected", port) + } +} diff --git a/client/internal/pqkem_transport.go b/client/internal/pqkem_transport.go new file mode 100644 index 00000000000..825aeb09634 --- /dev/null +++ b/client/internal/pqkem_transport.go @@ -0,0 +1,115 @@ +package internal + +import ( + "fmt" + "net" + "net/netip" + "sync" + + log "github.com/sirupsen/logrus" + + "github.com/netbirdio/netbird/client/iface/wgbackend" +) + +// DefaultPort is the preferred UDP port for the ML-KEM data-path service, bound on +// the WG overlay IP. Since each client owns a distinct overlay IP, this port is +// almost always free, so it need not be announced (peers assume it). A peer only +// announces Body.mlkemPort when a collision forced it onto a different port. +const DefaultPort = 51833 + +// pqTransport is the ML-KEM data-path transport: a dumb UDP socket bound on the WG +// overlay IP. It implements pqkem.Transport — the manager owns the remoteID<->endpoint +// routing and drives this socket's lifecycle (Run / Close). +type pqTransport struct { + conn net.PacketConn + port int + wg sync.WaitGroup +} + +// newPQTransport binds a UDP socket on the WG overlay IP, preferring DefaultPort and +// falling back to an ephemeral port if it is in use. Call it after the WG interface is +// up so the overlay IP is assigned; when the bound port is not DefaultPort it must be +// announced to peers via Body.mlkemPort. +// +// ns is the interface's netstack when it runs in netstack mode (js/wasm, embedded +// clients): the overlay IP then exists only inside that userspace stack, so the socket +// is opened there and its datagrams ride the tunnel like any other overlay traffic. A +// nil ns binds on the host. +func newPQTransport(overlayIP netip.Addr, ns *wgbackend.NetstackNet) (*pqTransport, error) { + if !overlayIP.IsValid() { + return nil, fmt.Errorf("invalid overlay IP for pqkem transport") + } + // The WG overlay always carries an IPv4 address (v6 is additive, never standalone), + // so the transport binds over IPv4. Unmap first so AsSlice() yields 4 bytes for an + // IPv4-mapped IPv6 address (a hardcoded "udp4" would otherwise fail on its 16 bytes). + overlayIP = overlayIP.Unmap() + listen := func(port uint16) (net.PacketConn, error) { + if ns != nil { + conn, err := ns.ListenUDPAddrPort(netip.AddrPortFrom(overlayIP, port)) + if err != nil { + return nil, err + } + return conn, nil + } + conn, err := net.ListenUDP("udp4", &net.UDPAddr{IP: net.IP(overlayIP.AsSlice()), Port: int(port)}) + if err != nil { + return nil, err + } + return conn, nil + } + conn, err := listen(DefaultPort) + if err != nil { + log.Debugf("pqkem: default port %d unavailable on %s (%v), using an ephemeral port", DefaultPort, overlayIP, err) + conn, err = listen(0) + if err != nil { + return nil, fmt.Errorf("bind pqkem udp on overlay %s: %w", overlayIP, err) + } + } + local, ok := conn.LocalAddr().(*net.UDPAddr) + if !ok { + _ = conn.Close() + return nil, fmt.Errorf("pqkem transport bound to a non-UDP address %s", conn.LocalAddr()) + } + return &pqTransport{conn: conn, port: local.Port}, nil +} + +// Send implements pqkem.Transport. +func (t *pqTransport) Send(endpoint netip.AddrPort, msg []byte) error { + _, err := t.conn.WriteTo(msg, net.UDPAddrFromAddrPort(endpoint)) + return err +} + +// LocalPort implements pqkem.Transport. +func (t *pqTransport) LocalPort() int { return t.port } + +// Run implements pqkem.Transport: the receive loop, delivering each datagram as +// (source endpoint, msg). Exits when the socket is closed. +func (t *pqTransport) Run(onInbound func(src netip.AddrPort, msg []byte)) { + t.wg.Add(1) + go func() { + defer t.wg.Done() + buf := make([]byte, 2048) + for { + n, addr, err := t.conn.ReadFrom(buf) + if err != nil { + return + } + src, ok := addr.(*net.UDPAddr) + if !ok { + continue + } + ap := src.AddrPort() + msg := make([]byte, n) + copy(msg, buf[:n]) + onInbound(netip.AddrPortFrom(ap.Addr().Unmap(), ap.Port()), msg) + } + }() +} + +// Close implements pqkem.Transport. It closes the socket (unblocking the read) and drains +// the receive loop, so no onInbound callback is still running when Close returns. +func (t *pqTransport) Close() error { + err := t.conn.Close() + t.wg.Wait() + return err +} diff --git a/client/internal/pqkem_transport_test.go b/client/internal/pqkem_transport_test.go new file mode 100644 index 00000000000..0a963f6d649 --- /dev/null +++ b/client/internal/pqkem_transport_test.go @@ -0,0 +1,93 @@ +package internal + +import ( + "net/netip" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/netbirdio/netbird/client/iface/wgbackend" +) + +type pqInbound struct { + src netip.AddrPort + msg []byte +} + +func runPQTransport(t *testing.T, tr *pqTransport) <-chan pqInbound { + t.Helper() + got := make(chan pqInbound, 1) + tr.Run(func(src netip.AddrPort, msg []byte) { + select { + case got <- pqInbound{src: src, msg: msg}: + default: + } + }) + t.Cleanup(func() { _ = tr.Close() }) + return got +} + +func receivePQ(t *testing.T, got <-chan pqInbound) pqInbound { + t.Helper() + select { + case in := <-got: + return in + case <-time.After(5 * time.Second): + t.Fatal("no datagram received") + return pqInbound{} + } +} + +// TestPQTransport_HostRoundTrip sends a datagram between two host-bound transports. The +// second bind collides with the first on DefaultPort, so it also covers the fallback to +// an ephemeral port. The source must come back as a plain (unmapped) IPv4 endpoint, +// since the manager matches it against registered peer endpoints. +func TestPQTransport_HostRoundTrip(t *testing.T) { + loopback := netip.MustParseAddr("127.0.0.1") + + a, err := newPQTransport(loopback, nil) + require.NoError(t, err) + b, err := newPQTransport(loopback, nil) + require.NoError(t, err) + require.NotEqual(t, a.LocalPort(), b.LocalPort(), "two transports on one IP must get distinct ports") + + runPQTransport(t, a) + gotB := runPQTransport(t, b) + + require.NoError(t, a.Send(netip.AddrPortFrom(loopback, uint16(b.LocalPort())), []byte("offer"))) + + in := receivePQ(t, gotB) + assert.Equal(t, []byte("offer"), in.msg, "payload must arrive intact") + assert.Equal(t, netip.AddrPortFrom(loopback, uint16(a.LocalPort())), in.src, "source must be the sender's unmapped IPv4 endpoint") +} + +// TestPQTransport_NetstackRoundTrip covers netstack mode (js/wasm and embedded clients), +// where the overlay IP exists only inside the userspace stack. Binding it on the host +// fails, which disabled the exchange (or, in strict mode, stopped the engine from +// starting); the transport must open its socket on the netstack instead. +func TestPQTransport_NetstackRoundTrip(t *testing.T) { + overlay := netip.MustParseAddr("192.0.2.1") + dev, ns, err := wgbackend.CreateNetTUN([]netip.Addr{overlay}, nil, 1280) + require.NoError(t, err) + t.Cleanup(func() { _ = dev.Close() }) + + _, err = newPQTransport(overlay, nil) + require.Error(t, err, "the netstack-only overlay IP must not be bindable on the host") + + a, err := newPQTransport(overlay, ns) + require.NoError(t, err) + assert.Equal(t, DefaultPort, a.LocalPort(), "the default port must be free on a fresh netstack") + b, err := newPQTransport(overlay, ns) + require.NoError(t, err) + + runPQTransport(t, a) + gotB := runPQTransport(t, b) + + require.NoError(t, a.Send(netip.AddrPortFrom(overlay, uint16(b.LocalPort())), []byte("offer"))) + + in := receivePQ(t, gotB) + assert.Equal(t, []byte("offer"), in.msg, "payload must arrive intact") + assert.Equal(t, netip.AddrPortFrom(overlay, uint16(a.LocalPort())), in.src, "source must be the sender's overlay endpoint") +} diff --git a/client/proto/daemon.pb.go b/client/proto/daemon.pb.go index ee82cd8eae7..aac016ae011 100644 --- a/client/proto/daemon.pb.go +++ b/client/proto/daemon.pb.go @@ -1686,6 +1686,8 @@ type LocalPeerState struct { Networks []string `protobuf:"bytes,7,rep,name=networks,proto3" json:"networks,omitempty"` Ipv6 string `protobuf:"bytes,8,opt,name=ipv6,proto3" json:"ipv6,omitempty"` WgPort int32 `protobuf:"varint,9,opt,name=wgPort,proto3" json:"wgPort,omitempty"` + MlkemEnabled bool `protobuf:"varint,10,opt,name=mlkemEnabled,proto3" json:"mlkemEnabled,omitempty"` + MlkemStrict bool `protobuf:"varint,11,opt,name=mlkemStrict,proto3" json:"mlkemStrict,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache } @@ -1783,6 +1785,20 @@ func (x *LocalPeerState) GetWgPort() int32 { return 0 } +func (x *LocalPeerState) GetMlkemEnabled() bool { + if x != nil { + return x.MlkemEnabled + } + return false +} + +func (x *LocalPeerState) GetMlkemStrict() bool { + if x != nil { + return x.MlkemStrict + } + return false +} + // SignalState contains the latest state of a signal connection type SignalState struct { state protoimpl.MessageState `protogen:"open.v1"` @@ -7391,7 +7407,7 @@ const file_daemon_proto_rawDesc = "" + "\n" + "sshHostKey\x18\x13 \x01(\fR\n" + "sshHostKey\x12\x12\n" + - "\x04ipv6\x18\x14 \x01(\tR\x04ipv6\"\x9c\x02\n" + + "\x04ipv6\x18\x14 \x01(\tR\x04ipv6\"\xe2\x02\n" + "\x0eLocalPeerState\x12\x0e\n" + "\x02IP\x18\x01 \x01(\tR\x02IP\x12\x16\n" + "\x06pubKey\x18\x02 \x01(\tR\x06pubKey\x12(\n" + @@ -7401,7 +7417,10 @@ const file_daemon_proto_rawDesc = "" + "\x13rosenpassPermissive\x18\x06 \x01(\bR\x13rosenpassPermissive\x12\x1a\n" + "\bnetworks\x18\a \x03(\tR\bnetworks\x12\x12\n" + "\x04ipv6\x18\b \x01(\tR\x04ipv6\x12\x16\n" + - "\x06wgPort\x18\t \x01(\x05R\x06wgPort\"S\n" + + "\x06wgPort\x18\t \x01(\x05R\x06wgPort\x12\"\n" + + "\fmlkemEnabled\x18\n" + + " \x01(\bR\fmlkemEnabled\x12 \n" + + "\vmlkemStrict\x18\v \x01(\bR\vmlkemStrict\"S\n" + "\vSignalState\x12\x10\n" + "\x03URL\x18\x01 \x01(\tR\x03URL\x12\x1c\n" + "\tconnected\x18\x02 \x01(\bR\tconnected\x12\x14\n" + diff --git a/client/proto/daemon.proto b/client/proto/daemon.proto index 9f4dde33b41..9bbc0da05b4 100644 --- a/client/proto/daemon.proto +++ b/client/proto/daemon.proto @@ -417,6 +417,8 @@ message LocalPeerState { repeated string networks = 7; string ipv6 = 8; int32 wgPort = 9; + bool mlkemEnabled = 10; + bool mlkemStrict = 11; } // SignalState contains the latest state of a signal connection diff --git a/client/server/mdm.go b/client/server/mdm.go index b22c3b0a3ff..c68882593ca 100644 --- a/client/server/mdm.go +++ b/client/server/mdm.go @@ -9,6 +9,7 @@ import ( "google.golang.org/grpc/codes" gstatus "google.golang.org/grpc/status" + "github.com/netbirdio/netbird/client/internal/pqkem" "github.com/netbirdio/netbird/client/mdm" "github.com/netbirdio/netbird/client/proto" ) @@ -133,6 +134,9 @@ func (s *Server) restartEngineForMDMLocked() error { s.config = config s.statusRecorder.UpdateManagementAddress(config.ManagementURL.String()) s.statusRecorder.UpdateRosenpass(config.RosenpassEnabled, config.RosenpassPermissive) + // ML-KEM is env-driven today; mirror the Rosenpass update so the status stays in + // sync after an MDM config apply and the wiring is ready if it becomes a config field. + s.statusRecorder.UpdateMLKEM(pqkem.Enabled(), pqkem.Strict()) ctx, cancel := context.WithCancel(s.rootCtx) s.actCancel = cancel diff --git a/client/server/server.go b/client/server/server.go index c16c5f42fa3..8789a768d31 100644 --- a/client/server/server.go +++ b/client/server/server.go @@ -37,6 +37,7 @@ import ( "github.com/netbirdio/netbird/client/internal" "github.com/netbirdio/netbird/client/internal/peer" + "github.com/netbirdio/netbird/client/internal/pqkem" "github.com/netbirdio/netbird/client/internal/statemanager" "github.com/netbirdio/netbird/client/internal/updater" "github.com/netbirdio/netbird/client/proto" @@ -344,6 +345,7 @@ func (s *Server) Start() error { s.statusRecorder.UpdateManagementAddress(config.ManagementURL.String()) s.statusRecorder.UpdateRosenpass(config.RosenpassEnabled, config.RosenpassPermissive) + s.statusRecorder.UpdateMLKEM(pqkem.Enabled(), pqkem.Strict()) s.localMetrics.Reconcile(config.LocalMetricsEnabled, config.LocalMetricsAddress) if s.sessionWatcher == nil { @@ -1244,6 +1246,7 @@ func (s *Server) Up(callerCtx context.Context, msg *proto.UpRequest) (*proto.UpR s.statusRecorder.UpdateManagementAddress(s.config.ManagementURL.String()) s.statusRecorder.UpdateRosenpass(s.config.RosenpassEnabled, s.config.RosenpassPermissive) + s.statusRecorder.UpdateMLKEM(pqkem.Enabled(), pqkem.Strict()) s.localMetrics.Reconcile(s.config.LocalMetricsEnabled, s.config.LocalMetricsAddress) s.clientRunning = true @@ -1930,6 +1933,7 @@ func (s *Server) buildStatusResponse(ctx context.Context, msg *proto.StatusReque s.statusRecorder.UpdateManagementAddress(s.config.ManagementURL.String()) s.statusRecorder.UpdateRosenpass(s.config.RosenpassEnabled, s.config.RosenpassPermissive) + s.statusRecorder.UpdateMLKEM(pqkem.Enabled(), pqkem.Strict()) if msg.GetFullPeerStatus { s.runProbes(ctx, msg.ShouldRunProbes) diff --git a/client/status/status.go b/client/status/status.go index e0585b8f0c0..ff48d97fe34 100644 --- a/client/status/status.go +++ b/client/status/status.go @@ -155,6 +155,8 @@ type OutputOverview struct { FQDN string `json:"fqdn" yaml:"fqdn"` RosenpassEnabled bool `json:"quantumResistance" yaml:"quantumResistance"` RosenpassPermissive bool `json:"quantumResistancePermissive" yaml:"quantumResistancePermissive"` + MLKEMEnabled bool `json:"mlkemEnabled" yaml:"mlkemEnabled"` + MLKEMStrict bool `json:"mlkemStrict" yaml:"mlkemStrict"` Networks []string `json:"networks" yaml:"networks"` NSServerGroups []NsServerGroupStateOutput `json:"dnsServers" yaml:"dnsServers"` Events []SystemEventOutput `json:"events" yaml:"events"` @@ -204,6 +206,8 @@ func ConvertToStatusOutputOverview(pbFullStatus *proto.FullStatus, opts ConvertO FQDN: pbFullStatus.GetLocalPeerState().GetFqdn(), RosenpassEnabled: pbFullStatus.GetLocalPeerState().GetRosenpassEnabled(), RosenpassPermissive: pbFullStatus.GetLocalPeerState().GetRosenpassPermissive(), + MLKEMEnabled: pbFullStatus.GetLocalPeerState().GetMlkemEnabled(), + MLKEMStrict: pbFullStatus.GetLocalPeerState().GetMlkemStrict(), Networks: pbFullStatus.GetLocalPeerState().GetNetworks(), NSServerGroups: mapNSGroups(pbFullStatus.GetDnsServers()), Events: mapEvents(pbFullStatus.GetEvents()), @@ -509,12 +513,14 @@ func (o *OutputOverview) GeneralSummary(showURL bool, showRelays bool, showNameS dnsServersString = fmt.Sprintf("%d/%d Available", countEnabled(o.NSServerGroups), len(o.NSServerGroups)) } - rosenpassEnabledStatus := "false" - if o.RosenpassEnabled { - rosenpassEnabledStatus = "true" - if o.RosenpassPermissive { - rosenpassEnabledStatus = "true (permissive)" //nolint:gosec - } + // Quantum resistance is the outcome (post-quantum protected or not); the mechanism + // that provides it — ML-KEM or Rosenpass, strict or permissive — is a separate detail. + mechanism := quantumResistanceMechanism(o.RosenpassEnabled, o.RosenpassPermissive, o.MLKEMEnabled, o.MLKEMStrict) + quantumResistanceStatus := "false" + mechanismLine := "" + if mechanism != "none" { + quantumResistanceStatus = "true" + mechanismLine = fmt.Sprintf("Quantum resistance mechanism: %s\n", mechanism) } lazyConnectionEnabledStatus := "false" @@ -608,6 +614,7 @@ func (o *OutputOverview) GeneralSummary(showURL bool, showRelays bool, showNameS "Interface type: %s\n"+ "Wireguard port: %s\n"+ "Quantum resistance: %s\n"+ + "%s"+ "Lazy connection: %s\n"+ "SSH Server: %s\n"+ "Networks: %s\n"+ @@ -626,7 +633,8 @@ func (o *OutputOverview) GeneralSummary(showURL bool, showRelays bool, showNameS ipv6Line, interfaceTypeString, wgPortString, - rosenpassEnabledStatus, + quantumResistanceStatus, + mechanismLine, lazyConnectionEnabledStatus, sshServerStatus, networks, @@ -638,7 +646,7 @@ func (o *OutputOverview) GeneralSummary(showURL bool, showRelays bool, showNameS // FullDetailSummary returns a full detailed summary with peer details and events. func (o *OutputOverview) FullDetailSummary() string { - parsedPeersString := parsePeers(o.Peers, o.RosenpassEnabled, o.RosenpassPermissive) + parsedPeersString := parsePeers(o.Peers, o.RosenpassEnabled, o.RosenpassPermissive, o.MLKEMEnabled, o.MLKEMStrict) parsedEventsString := parseEvents(o.Events) summary := o.GeneralSummary(true, true, true, true) @@ -681,6 +689,8 @@ func ToProtoFullStatus(fullStatus peer.FullStatus) *proto.FullStatus { pbFullStatus.LocalPeerState.Fqdn = fullStatus.LocalPeerState.FQDN pbFullStatus.LocalPeerState.RosenpassPermissive = fullStatus.RosenpassState.Permissive pbFullStatus.LocalPeerState.RosenpassEnabled = fullStatus.RosenpassState.Enabled + pbFullStatus.LocalPeerState.MlkemEnabled = fullStatus.MLKEMState.Enabled + pbFullStatus.LocalPeerState.MlkemStrict = fullStatus.MLKEMState.Strict pbFullStatus.LocalPeerState.Networks = maps.Keys(fullStatus.LocalPeerState.Routes) pbFullStatus.LazyConnectionEnabled = fullStatus.LazyConnectionEnabled @@ -745,7 +755,47 @@ func ToProtoFullStatus(fullStatus peer.FullStatus) *proto.FullStatus { return &pbFullStatus } -func parsePeers(peers PeersStateOutput, rosenpassEnabled, rosenpassPermissive bool) string { +// quantumResistanceMechanism reports which post-quantum mechanism the local client runs, +// as an enum: "none", "ML-KEM strict", "ML-KEM permissive", "Rosenpass strict", "Rosenpass permissive". +// ML-KEM and Rosenpass are mutually exclusive, so at most one is active; ML-KEM takes +// precedence if somehow both are set. Strict/permissive is the fail-closed vs fail-open mode. +func quantumResistanceMechanism(rosenpassEnabled, rosenpassPermissive, mlkemEnabled, mlkemStrict bool) string { + switch { + case mlkemEnabled && mlkemStrict: + return "ML-KEM strict" + case mlkemEnabled: + return "ML-KEM permissive" + case rosenpassEnabled && !rosenpassPermissive: + return "Rosenpass strict" + case rosenpassEnabled: + return "Rosenpass permissive" + default: + return "none" + } +} + +// peerQuantumResistanceStatus renders the per-peer "Quantum resistance" field. established +// reports whether this peer's tunnel is post-quantum protected (Rosenpass or ML-KEM). When +// it is not, the reason is phrased for whichever mechanism is active locally. +func peerQuantumResistanceStatus(established, rosenpassEnabled, rosenpassPermissive, mlkemEnabled, mlkemStrict bool) string { + if established { + return "true" + } + switch { + case mlkemEnabled && mlkemStrict: + return "false (ML-KEM strict: no post-quantum PSK established for this peer yet)" + case mlkemEnabled: + return "false (ML-KEM: not converged yet, or peer does not run the exchange)" + case rosenpassEnabled && rosenpassPermissive: + return "false (remote didn't enable quantum resistance)" + case rosenpassEnabled: + return "false (connection won't work without a permissive mode)" + default: + return "false" + } +} + +func parsePeers(peers PeersStateOutput, rosenpassEnabled, rosenpassPermissive, mlkemEnabled, mlkemStrict bool) string { var ( peersString = "" ) @@ -772,22 +822,7 @@ func parsePeers(peers PeersStateOutput, rosenpassEnabled, rosenpassPermissive bo remoteICEEndpoint = peerState.IceCandidateEndpoint.Remote } - rosenpassEnabledStatus := "false" - if rosenpassEnabled { - if peerState.RosenpassEnabled { - rosenpassEnabledStatus = "true" - } else { - if rosenpassPermissive { - rosenpassEnabledStatus = "false (remote didn't enable quantum resistance)" - } else { - rosenpassEnabledStatus = "false (connection won't work without a permissive mode)" - } - } - } else { - if peerState.RosenpassEnabled { - rosenpassEnabledStatus = "false (connection might not work without a remote permissive mode)" - } - } + rosenpassEnabledStatus := peerQuantumResistanceStatus(peerState.RosenpassEnabled, rosenpassEnabled, rosenpassPermissive, mlkemEnabled, mlkemStrict) networks := "-" if len(peerState.Networks) > 0 { diff --git a/client/status/status_test.go b/client/status/status_test.go index 1580aca6d96..c451470d388 100644 --- a/client/status/status_test.go +++ b/client/status/status_test.go @@ -375,6 +375,8 @@ func TestParsingToJSON(t *testing.T) { "fqdn": "some-localhost.awesome-domain.com", "quantumResistance": false, "quantumResistancePermissive": false, + "mlkemEnabled": false, + "mlkemStrict": false, "networks": [ "10.10.0.0/24" ], @@ -493,6 +495,8 @@ wireguardPort: 51820 fqdn: some-localhost.awesome-domain.com quantumResistance: false quantumResistancePermissive: false +mlkemEnabled: false +mlkemStrict: false networks: - 10.10.0.0/24 dnsServers: diff --git a/shared/signal/client/client.go b/shared/signal/client/client.go index fb77cb90f73..51499bb3351 100644 --- a/shared/signal/client/client.go +++ b/shared/signal/client/client.go @@ -52,6 +52,11 @@ type CredentialPayload struct { Credential *Credential RosenpassPubKey []byte RosenpassAddr string + // MlkemPayload is the opaque post-quantum KEM handshake message riding this + // OFFER/ANSWER (see Body.mlkemPayload). Nil when not running the PQ exchange. + MlkemPayload []byte + // MlkemPort is the sender's ML-KEM PQ service UDP port (0 when not running). + MlkemPort int RelaySrvAddress string RelaySrvIP netip.Addr SessionID []byte @@ -89,6 +94,13 @@ func MarshalCredential(myKey wgtypes.Key, remoteKey string, p CredentialPayload) if p.RelaySrvIP.IsValid() { body.RelayServerIP = p.RelaySrvIP.Unmap().AsSlice() } + if len(p.MlkemPayload) > 0 { + body.MlkemPayload = p.MlkemPayload + } + if p.MlkemPort > 0 { + port := uint32(p.MlkemPort) + body.MlkemPort = &port + } return &proto.Message{ Key: myKey.PublicKey().String(), RemoteKey: remoteKey, diff --git a/shared/signal/proto/signalexchange.pb.go b/shared/signal/proto/signalexchange.pb.go index 8e07977f07f..812e3c9c008 100644 --- a/shared/signal/proto/signalexchange.pb.go +++ b/shared/signal/proto/signalexchange.pb.go @@ -239,6 +239,16 @@ type Body struct { // fallback dial target when DNS resolution of relayServerAddress fails. // SNI/TLS verification still uses relayServerAddress. RelayServerIP []byte `protobuf:"bytes,11,opt,name=relayServerIP,proto3,oneof" json:"relayServerIP,omitempty"` + // mlkemPayload carries a post-quantum X25519MLKEM768 handshake message that + // seeds the WireGuard PSK, riding this Body's OFFER/ANSWER: on an OFFER it is + // the KEM offer, on an ANSWER the KEM answer. It is opaque to signal — the + // pqkem library frames and parses it. Absent when the sender does not run the + // ML-KEM PQ exchange; unknown to older clients, which ignore it. + MlkemPayload []byte `protobuf:"bytes,12,opt,name=mlkemPayload,proto3,oneof" json:"mlkemPayload,omitempty"` + // mlkemPort is the UDP port of the sender's ML-KEM PQ service, bound on its + // WireGuard overlay IP. Peers send subsequent rekey messages there over the + // data path. Zero/absent when the ML-KEM PQ exchange is not running. + MlkemPort *uint32 `protobuf:"varint,13,opt,name=mlkemPort,proto3,oneof" json:"mlkemPort,omitempty"` } func (x *Body) Reset() { @@ -343,6 +353,20 @@ func (x *Body) GetRelayServerIP() []byte { return nil } +func (x *Body) GetMlkemPayload() []byte { + if x != nil { + return x.MlkemPayload + } + return nil +} + +func (x *Body) GetMlkemPort() uint32 { + if x != nil && x.MlkemPort != nil { + return *x.MlkemPort + } + return 0 +} + // Mode indicates a connection mode type Mode struct { state protoimpl.MessageState @@ -466,7 +490,7 @@ var file_signalexchange_proto_rawDesc = []byte{ 0x52, 0x09, 0x72, 0x65, 0x6d, 0x6f, 0x74, 0x65, 0x4b, 0x65, 0x79, 0x12, 0x28, 0x0a, 0x04, 0x62, 0x6f, 0x64, 0x79, 0x18, 0x04, 0x20, 0x01, 0x28, 0x0b, 0x32, 0x14, 0x2e, 0x73, 0x69, 0x67, 0x6e, 0x61, 0x6c, 0x65, 0x78, 0x63, 0x68, 0x61, 0x6e, 0x67, 0x65, 0x2e, 0x42, 0x6f, 0x64, 0x79, 0x52, - 0x04, 0x62, 0x6f, 0x64, 0x79, 0x22, 0xd2, 0x04, 0x0a, 0x04, 0x42, 0x6f, 0x64, 0x79, 0x12, 0x2d, + 0x04, 0x62, 0x6f, 0x64, 0x79, 0x22, 0xbd, 0x05, 0x0a, 0x04, 0x42, 0x6f, 0x64, 0x79, 0x12, 0x2d, 0x0a, 0x04, 0x74, 0x79, 0x70, 0x65, 0x18, 0x01, 0x20, 0x01, 0x28, 0x0e, 0x32, 0x19, 0x2e, 0x73, 0x69, 0x67, 0x6e, 0x61, 0x6c, 0x65, 0x78, 0x63, 0x68, 0x61, 0x6e, 0x67, 0x65, 0x2e, 0x42, 0x6f, 0x64, 0x79, 0x2e, 0x54, 0x79, 0x70, 0x65, 0x52, 0x04, 0x74, 0x79, 0x70, 0x65, 0x12, 0x18, 0x0a, @@ -494,39 +518,46 @@ var file_signalexchange_proto_rawDesc = []byte{ 0x52, 0x09, 0x73, 0x65, 0x73, 0x73, 0x69, 0x6f, 0x6e, 0x49, 0x64, 0x88, 0x01, 0x01, 0x12, 0x29, 0x0a, 0x0d, 0x72, 0x65, 0x6c, 0x61, 0x79, 0x53, 0x65, 0x72, 0x76, 0x65, 0x72, 0x49, 0x50, 0x18, 0x0b, 0x20, 0x01, 0x28, 0x0c, 0x48, 0x02, 0x52, 0x0d, 0x72, 0x65, 0x6c, 0x61, 0x79, 0x53, 0x65, - 0x72, 0x76, 0x65, 0x72, 0x49, 0x50, 0x88, 0x01, 0x01, 0x22, 0x52, 0x0a, 0x04, 0x54, 0x79, 0x70, - 0x65, 0x12, 0x09, 0x0a, 0x05, 0x4f, 0x46, 0x46, 0x45, 0x52, 0x10, 0x00, 0x12, 0x0a, 0x0a, 0x06, - 0x41, 0x4e, 0x53, 0x57, 0x45, 0x52, 0x10, 0x01, 0x12, 0x0d, 0x0a, 0x09, 0x43, 0x41, 0x4e, 0x44, - 0x49, 0x44, 0x41, 0x54, 0x45, 0x10, 0x02, 0x12, 0x08, 0x0a, 0x04, 0x4d, 0x4f, 0x44, 0x45, 0x10, - 0x04, 0x12, 0x0b, 0x0a, 0x07, 0x47, 0x4f, 0x5f, 0x49, 0x44, 0x4c, 0x45, 0x10, 0x05, 0x12, 0x0d, - 0x0a, 0x09, 0x48, 0x45, 0x41, 0x52, 0x54, 0x42, 0x45, 0x41, 0x54, 0x10, 0x06, 0x42, 0x15, 0x0a, - 0x13, 0x5f, 0x72, 0x65, 0x6c, 0x61, 0x79, 0x53, 0x65, 0x72, 0x76, 0x65, 0x72, 0x41, 0x64, 0x64, - 0x72, 0x65, 0x73, 0x73, 0x42, 0x0c, 0x0a, 0x0a, 0x5f, 0x73, 0x65, 0x73, 0x73, 0x69, 0x6f, 0x6e, - 0x49, 0x64, 0x42, 0x10, 0x0a, 0x0e, 0x5f, 0x72, 0x65, 0x6c, 0x61, 0x79, 0x53, 0x65, 0x72, 0x76, - 0x65, 0x72, 0x49, 0x50, 0x4a, 0x04, 0x08, 0x09, 0x10, 0x0a, 0x22, 0x2e, 0x0a, 0x04, 0x4d, 0x6f, - 0x64, 0x65, 0x12, 0x1b, 0x0a, 0x06, 0x64, 0x69, 0x72, 0x65, 0x63, 0x74, 0x18, 0x01, 0x20, 0x01, - 0x28, 0x08, 0x48, 0x00, 0x52, 0x06, 0x64, 0x69, 0x72, 0x65, 0x63, 0x74, 0x88, 0x01, 0x01, 0x42, - 0x09, 0x0a, 0x07, 0x5f, 0x64, 0x69, 0x72, 0x65, 0x63, 0x74, 0x22, 0x6d, 0x0a, 0x0f, 0x52, 0x6f, - 0x73, 0x65, 0x6e, 0x70, 0x61, 0x73, 0x73, 0x43, 0x6f, 0x6e, 0x66, 0x69, 0x67, 0x12, 0x28, 0x0a, - 0x0f, 0x72, 0x6f, 0x73, 0x65, 0x6e, 0x70, 0x61, 0x73, 0x73, 0x50, 0x75, 0x62, 0x4b, 0x65, 0x79, - 0x18, 0x01, 0x20, 0x01, 0x28, 0x0c, 0x52, 0x0f, 0x72, 0x6f, 0x73, 0x65, 0x6e, 0x70, 0x61, 0x73, - 0x73, 0x50, 0x75, 0x62, 0x4b, 0x65, 0x79, 0x12, 0x30, 0x0a, 0x13, 0x72, 0x6f, 0x73, 0x65, 0x6e, - 0x70, 0x61, 0x73, 0x73, 0x53, 0x65, 0x72, 0x76, 0x65, 0x72, 0x41, 0x64, 0x64, 0x72, 0x18, 0x02, - 0x20, 0x01, 0x28, 0x09, 0x52, 0x13, 0x72, 0x6f, 0x73, 0x65, 0x6e, 0x70, 0x61, 0x73, 0x73, 0x53, - 0x65, 0x72, 0x76, 0x65, 0x72, 0x41, 0x64, 0x64, 0x72, 0x32, 0xb9, 0x01, 0x0a, 0x0e, 0x53, 0x69, - 0x67, 0x6e, 0x61, 0x6c, 0x45, 0x78, 0x63, 0x68, 0x61, 0x6e, 0x67, 0x65, 0x12, 0x4c, 0x0a, 0x04, - 0x53, 0x65, 0x6e, 0x64, 0x12, 0x20, 0x2e, 0x73, 0x69, 0x67, 0x6e, 0x61, 0x6c, 0x65, 0x78, 0x63, - 0x68, 0x61, 0x6e, 0x67, 0x65, 0x2e, 0x45, 0x6e, 0x63, 0x72, 0x79, 0x70, 0x74, 0x65, 0x64, 0x4d, - 0x65, 0x73, 0x73, 0x61, 0x67, 0x65, 0x1a, 0x20, 0x2e, 0x73, 0x69, 0x67, 0x6e, 0x61, 0x6c, 0x65, + 0x72, 0x76, 0x65, 0x72, 0x49, 0x50, 0x88, 0x01, 0x01, 0x12, 0x27, 0x0a, 0x0c, 0x6d, 0x6c, 0x6b, + 0x65, 0x6d, 0x50, 0x61, 0x79, 0x6c, 0x6f, 0x61, 0x64, 0x18, 0x0c, 0x20, 0x01, 0x28, 0x0c, 0x48, + 0x03, 0x52, 0x0c, 0x6d, 0x6c, 0x6b, 0x65, 0x6d, 0x50, 0x61, 0x79, 0x6c, 0x6f, 0x61, 0x64, 0x88, + 0x01, 0x01, 0x12, 0x21, 0x0a, 0x09, 0x6d, 0x6c, 0x6b, 0x65, 0x6d, 0x50, 0x6f, 0x72, 0x74, 0x18, + 0x0d, 0x20, 0x01, 0x28, 0x0d, 0x48, 0x04, 0x52, 0x09, 0x6d, 0x6c, 0x6b, 0x65, 0x6d, 0x50, 0x6f, + 0x72, 0x74, 0x88, 0x01, 0x01, 0x22, 0x52, 0x0a, 0x04, 0x54, 0x79, 0x70, 0x65, 0x12, 0x09, 0x0a, + 0x05, 0x4f, 0x46, 0x46, 0x45, 0x52, 0x10, 0x00, 0x12, 0x0a, 0x0a, 0x06, 0x41, 0x4e, 0x53, 0x57, + 0x45, 0x52, 0x10, 0x01, 0x12, 0x0d, 0x0a, 0x09, 0x43, 0x41, 0x4e, 0x44, 0x49, 0x44, 0x41, 0x54, + 0x45, 0x10, 0x02, 0x12, 0x08, 0x0a, 0x04, 0x4d, 0x4f, 0x44, 0x45, 0x10, 0x04, 0x12, 0x0b, 0x0a, + 0x07, 0x47, 0x4f, 0x5f, 0x49, 0x44, 0x4c, 0x45, 0x10, 0x05, 0x12, 0x0d, 0x0a, 0x09, 0x48, 0x45, + 0x41, 0x52, 0x54, 0x42, 0x45, 0x41, 0x54, 0x10, 0x06, 0x42, 0x15, 0x0a, 0x13, 0x5f, 0x72, 0x65, + 0x6c, 0x61, 0x79, 0x53, 0x65, 0x72, 0x76, 0x65, 0x72, 0x41, 0x64, 0x64, 0x72, 0x65, 0x73, 0x73, + 0x42, 0x0c, 0x0a, 0x0a, 0x5f, 0x73, 0x65, 0x73, 0x73, 0x69, 0x6f, 0x6e, 0x49, 0x64, 0x42, 0x10, + 0x0a, 0x0e, 0x5f, 0x72, 0x65, 0x6c, 0x61, 0x79, 0x53, 0x65, 0x72, 0x76, 0x65, 0x72, 0x49, 0x50, + 0x42, 0x0f, 0x0a, 0x0d, 0x5f, 0x6d, 0x6c, 0x6b, 0x65, 0x6d, 0x50, 0x61, 0x79, 0x6c, 0x6f, 0x61, + 0x64, 0x42, 0x0c, 0x0a, 0x0a, 0x5f, 0x6d, 0x6c, 0x6b, 0x65, 0x6d, 0x50, 0x6f, 0x72, 0x74, 0x4a, + 0x04, 0x08, 0x09, 0x10, 0x0a, 0x22, 0x2e, 0x0a, 0x04, 0x4d, 0x6f, 0x64, 0x65, 0x12, 0x1b, 0x0a, + 0x06, 0x64, 0x69, 0x72, 0x65, 0x63, 0x74, 0x18, 0x01, 0x20, 0x01, 0x28, 0x08, 0x48, 0x00, 0x52, + 0x06, 0x64, 0x69, 0x72, 0x65, 0x63, 0x74, 0x88, 0x01, 0x01, 0x42, 0x09, 0x0a, 0x07, 0x5f, 0x64, + 0x69, 0x72, 0x65, 0x63, 0x74, 0x22, 0x6d, 0x0a, 0x0f, 0x52, 0x6f, 0x73, 0x65, 0x6e, 0x70, 0x61, + 0x73, 0x73, 0x43, 0x6f, 0x6e, 0x66, 0x69, 0x67, 0x12, 0x28, 0x0a, 0x0f, 0x72, 0x6f, 0x73, 0x65, + 0x6e, 0x70, 0x61, 0x73, 0x73, 0x50, 0x75, 0x62, 0x4b, 0x65, 0x79, 0x18, 0x01, 0x20, 0x01, 0x28, + 0x0c, 0x52, 0x0f, 0x72, 0x6f, 0x73, 0x65, 0x6e, 0x70, 0x61, 0x73, 0x73, 0x50, 0x75, 0x62, 0x4b, + 0x65, 0x79, 0x12, 0x30, 0x0a, 0x13, 0x72, 0x6f, 0x73, 0x65, 0x6e, 0x70, 0x61, 0x73, 0x73, 0x53, + 0x65, 0x72, 0x76, 0x65, 0x72, 0x41, 0x64, 0x64, 0x72, 0x18, 0x02, 0x20, 0x01, 0x28, 0x09, 0x52, + 0x13, 0x72, 0x6f, 0x73, 0x65, 0x6e, 0x70, 0x61, 0x73, 0x73, 0x53, 0x65, 0x72, 0x76, 0x65, 0x72, + 0x41, 0x64, 0x64, 0x72, 0x32, 0xb9, 0x01, 0x0a, 0x0e, 0x53, 0x69, 0x67, 0x6e, 0x61, 0x6c, 0x45, + 0x78, 0x63, 0x68, 0x61, 0x6e, 0x67, 0x65, 0x12, 0x4c, 0x0a, 0x04, 0x53, 0x65, 0x6e, 0x64, 0x12, + 0x20, 0x2e, 0x73, 0x69, 0x67, 0x6e, 0x61, 0x6c, 0x65, 0x78, 0x63, 0x68, 0x61, 0x6e, 0x67, 0x65, + 0x2e, 0x45, 0x6e, 0x63, 0x72, 0x79, 0x70, 0x74, 0x65, 0x64, 0x4d, 0x65, 0x73, 0x73, 0x61, 0x67, + 0x65, 0x1a, 0x20, 0x2e, 0x73, 0x69, 0x67, 0x6e, 0x61, 0x6c, 0x65, 0x78, 0x63, 0x68, 0x61, 0x6e, + 0x67, 0x65, 0x2e, 0x45, 0x6e, 0x63, 0x72, 0x79, 0x70, 0x74, 0x65, 0x64, 0x4d, 0x65, 0x73, 0x73, + 0x61, 0x67, 0x65, 0x22, 0x00, 0x12, 0x59, 0x0a, 0x0d, 0x43, 0x6f, 0x6e, 0x6e, 0x65, 0x63, 0x74, + 0x53, 0x74, 0x72, 0x65, 0x61, 0x6d, 0x12, 0x20, 0x2e, 0x73, 0x69, 0x67, 0x6e, 0x61, 0x6c, 0x65, 0x78, 0x63, 0x68, 0x61, 0x6e, 0x67, 0x65, 0x2e, 0x45, 0x6e, 0x63, 0x72, 0x79, 0x70, 0x74, 0x65, - 0x64, 0x4d, 0x65, 0x73, 0x73, 0x61, 0x67, 0x65, 0x22, 0x00, 0x12, 0x59, 0x0a, 0x0d, 0x43, 0x6f, - 0x6e, 0x6e, 0x65, 0x63, 0x74, 0x53, 0x74, 0x72, 0x65, 0x61, 0x6d, 0x12, 0x20, 0x2e, 0x73, 0x69, - 0x67, 0x6e, 0x61, 0x6c, 0x65, 0x78, 0x63, 0x68, 0x61, 0x6e, 0x67, 0x65, 0x2e, 0x45, 0x6e, 0x63, - 0x72, 0x79, 0x70, 0x74, 0x65, 0x64, 0x4d, 0x65, 0x73, 0x73, 0x61, 0x67, 0x65, 0x1a, 0x20, 0x2e, - 0x73, 0x69, 0x67, 0x6e, 0x61, 0x6c, 0x65, 0x78, 0x63, 0x68, 0x61, 0x6e, 0x67, 0x65, 0x2e, 0x45, - 0x6e, 0x63, 0x72, 0x79, 0x70, 0x74, 0x65, 0x64, 0x4d, 0x65, 0x73, 0x73, 0x61, 0x67, 0x65, 0x22, - 0x00, 0x28, 0x01, 0x30, 0x01, 0x42, 0x08, 0x5a, 0x06, 0x2f, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x62, - 0x06, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x33, + 0x64, 0x4d, 0x65, 0x73, 0x73, 0x61, 0x67, 0x65, 0x1a, 0x20, 0x2e, 0x73, 0x69, 0x67, 0x6e, 0x61, + 0x6c, 0x65, 0x78, 0x63, 0x68, 0x61, 0x6e, 0x67, 0x65, 0x2e, 0x45, 0x6e, 0x63, 0x72, 0x79, 0x70, + 0x74, 0x65, 0x64, 0x4d, 0x65, 0x73, 0x73, 0x61, 0x67, 0x65, 0x22, 0x00, 0x28, 0x01, 0x30, 0x01, + 0x42, 0x08, 0x5a, 0x06, 0x2f, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x62, 0x06, 0x70, 0x72, 0x6f, 0x74, + 0x6f, 0x33, } var ( diff --git a/shared/signal/proto/signalexchange.proto b/shared/signal/proto/signalexchange.proto index 8c304e37c23..c6b2a639bba 100644 --- a/shared/signal/proto/signalexchange.proto +++ b/shared/signal/proto/signalexchange.proto @@ -75,6 +75,18 @@ message Body { // fallback dial target when DNS resolution of relayServerAddress fails. // SNI/TLS verification still uses relayServerAddress. optional bytes relayServerIP = 11; + + // mlkemPayload carries a post-quantum X25519MLKEM768 handshake message that + // seeds the WireGuard PSK, riding this Body's OFFER/ANSWER: on an OFFER it is + // the KEM offer, on an ANSWER the KEM answer. It is opaque to signal — the + // pqkem library frames and parses it. Absent when the sender does not run the + // ML-KEM PQ exchange; unknown to older clients, which ignore it. + optional bytes mlkemPayload = 12; + + // mlkemPort is the UDP port of the sender's ML-KEM PQ service, bound on its + // WireGuard overlay IP. Peers send subsequent rekey messages there over the + // data path. Zero/absent when the ML-KEM PQ exchange is not running. + optional uint32 mlkemPort = 13; } // Mode indicates a connection mode