fix

Bumps [github.com/gaissmai/bart](https://github.com/gaissmai/bart) from 0.26.0 to 0.26.1.
- [Release notes](https://github.com/gaissmai/bart/releases)
- [Commits](https://github.com/gaissmai/bart/compare/v0.26.0...v0.26.1)

---
updated-dependencies:
- dependency-name: github.com/gaissmai/bart
  dependency-version: 0.26.1
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.github/actions/code-sign/action.yml

@@ -0,0 +1,113 @@
+name: Code-sign Windows binaries
+description: >
+  Sign every .exe under a given path in place via the DefinedNet code-signer
+  Lambda. If `role` or `bucket` is empty, logs a notice and skips signing so
+  forks and dev branches without AWS access still produce usable builds.
+
+inputs:
+  path:
+    description: "Directory whose .exe files should be signed in place"
+    required: true
+  role:
+    description: "IAM role ARN to assume via OIDC; empty disables signing"
+    required: false
+    default: ""
+  bucket:
+    description: "S3 staging bucket the code-signer Lambda reads from; empty disables signing"
+    required: false
+    default: ""
+  region:
+    description: "AWS region for the role and Lambda"
+    required: false
+    default: "us-east-2"
+  function-name:
+    description: "Code-signer Lambda function name"
+    required: false
+    default: "code-signer"
+  key-prefix:
+    description: "S3 key prefix the caller is authorized to write under"
+    required: false
+    default: "code-signing/slackhq/nebula"
+
+runs:
+  using: composite
+  steps:
+    - name: Skip notice
+      if: inputs.role == '' || inputs.bucket == ''
+      shell: sh
+      run: echo "::notice::code-signer role or bucket not set; skipping code signing."
+
+    - name: Configure AWS credentials
+      if: inputs.role != '' && inputs.bucket != ''
+      uses: aws-actions/configure-aws-credentials@v6
+      with:
+        role-to-assume: ${{ inputs.role }}
+        aws-region: ${{ inputs.region }}
+        # Default is 12 retries to ride out IAM trust-policy propagation; once
+        # the role is stable we want a real misconfiguration to fail fast.
+        retry-max-attempts: 5
+
+    - name: Sign .exe files
+      if: inputs.role != '' && inputs.bucket != ''
+      shell: sh
+      env:
+        SIGN_PATH: ${{ inputs.path }}
+        BUCKET: ${{ inputs.bucket }}
+        FUNCTION_NAME: ${{ inputs.function-name }}
+        KEY_PREFIX: ${{ inputs.key-prefix }}
+      run: |
+        set -eu
+        RUN="${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+
+        find "$SIGN_PATH" -name '*.exe' -print | while read -r path
+        do
+            rel=${path#"$SIGN_PATH"/}
+            file=$(basename "$path")
+            name=${file%.exe}
+            prefix="${KEY_PREFIX}/${RUN}"
+            src="${prefix}/unsigned/${rel}"
+            dst="${prefix}/signed/${rel}"
+
+            echo "::group::Sign ${rel}"
+            echo "Uploading unsigned to s3://${BUCKET}/${src}"
+            aws s3 cp --no-progress "$path" "s3://${BUCKET}/${src}" >/dev/null
+
+            echo "Invoking ${FUNCTION_NAME} Lambda"
+            payload=$(jq -nc \
+                --arg s "$src" \
+                --arg d "$dst" \
+                --arg p "$name" \
+                '{source_key: $s, dest_key: $d, program_name: $p}')
+            meta=$(aws lambda invoke \
+                --function-name "$FUNCTION_NAME" \
+                --cli-binary-format raw-in-base64-out \
+                --payload "$payload" \
+                --output json \
+                /tmp/sign-resp.json)
+            if echo "$meta" | jq -e '.FunctionError != null' >/dev/null
+            then
+                echo "::endgroup::"
+                echo "::error::code-signer Lambda failed for ${rel}"
+                cat /tmp/sign-resp.json >&2
+                exit 1
+            fi
+
+            echo "Downloading signed back to ${path}"
+            aws s3 cp --no-progress "s3://${BUCKET}/${dst}" "$path" >/dev/null
+
+            aws s3 rm "s3://${BUCKET}/${src}" >/dev/null 2>&1 || true
+            aws s3 rm "s3://${BUCKET}/${dst}" >/dev/null 2>&1 || true
+
+            # Sanity-check the bytes we got back actually carry an Authenticode
+            # signature that this machine can validate end to end.
+            status=$(powershell -NoProfile -Command "(Get-AuthenticodeSignature -FilePath '$path').Status" | tr -d '\r')
+            if [ "$status" != "Valid" ]
+            then
+                echo "::endgroup::"
+                echo "::error::${rel} signature status: ${status} (expected Valid)"
+                exit 1
+            fi
+
+            echo "Signed ${rel} (sha256=$(jq -r '.sha256' /tmp/sign-resp.json), status=${status})"
+            echo "::endgroup::"
+        done

.github/workflows/release.yml

@@ -24,7 +24,7 @@ jobs:
           mv build/*.tar.gz release
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: linux-latest
           path: release
@@ -32,6 +32,9 @@ jobs:
   build-windows:
     name: Build Windows
     runs-on: windows-latest
+    permissions:
+      id-token: write
+      contents: read
     steps:
       - uses: actions/checkout@v6
 
@@ -54,8 +57,15 @@ jobs:
           mkdir build\dist\windows
           mv dist\windows\wintun build\dist\windows\
 
+      - name: Code-sign
+        uses: ./.github/actions/code-sign
+        with:
+          path: build
+          role: ${{ secrets.DEFINED_CODE_SIGNER_ROLE }}
+          bucket: ${{ secrets.DEFINED_CODE_SIGNER_BUCKET }}
+
       - name: Upload artifacts
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: windows-latest
           path: build
@@ -75,7 +85,7 @@ jobs:
 
       - name: Import certificates
         if: env.HAS_SIGNING_CREDS == 'true'
-        uses: Apple-Actions/import-codesign-certs@v6
+        uses: Apple-Actions/import-codesign-certs@v7
         with:
           p12-file-base64: ${{ secrets.APPLE_DEVELOPER_CERTIFICATE_P12_BASE64 }}
           p12-password: ${{ secrets.APPLE_DEVELOPER_CERTIFICATE_PASSWORD }}
@@ -104,7 +114,7 @@ jobs:
           fi
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: darwin-latest
           path: ./release/*
@@ -128,21 +138,21 @@ jobs:
 
       - name: Download artifacts
         if: ${{ env.HAS_DOCKER_CREDS == 'true' }}
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           name: linux-latest
           path: artifacts
 
       - name: Login to Docker Hub
         if: ${{ env.HAS_DOCKER_CREDS == 'true' }}
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           username: ${{ vars.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Set up Docker Buildx
         if: ${{ env.HAS_DOCKER_CREDS == 'true' }}
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
 
       - name: Build and push images
         if: ${{ env.HAS_DOCKER_CREDS == 'true' }}
@@ -163,7 +173,7 @@ jobs:
       - uses: actions/checkout@v6
 
       - name: Download artifacts
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           path: artifacts
 

.github/workflows/smoke-extra.yml

@@ -14,10 +14,18 @@ on:
       - 'go.sum'
 jobs:
 
-  smoke-extra:
+  smoke-extra-libvirt:
     if: github.ref == 'refs/heads/master' || contains(github.event.pull_request.labels.*.name, 'smoke-test-extra')
-    name: Run extra smoke tests
+    name: ${{ matrix.target }}
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        target:
+          - freebsd-amd64
+          - openbsd-amd64
+          - netbsd-amd64
+          - linux-amd64-ipv6disable
     env:
       VAGRANT_DEFAULT_PROVIDER: libvirt
     steps:
@@ -40,28 +48,85 @@ jobs:
         sudo chmod 666 /var/run/libvirt/libvirt-sock
         vagrant plugin install vagrant-libvirt
 
-    - name: freebsd-amd64
-      run: make smoke-vagrant/freebsd-amd64
+    - name: ${{ matrix.target }}
+      run: make smoke-vagrant/${{ matrix.target }}
 
-    - name: openbsd-amd64
-      run: make smoke-vagrant/openbsd-amd64
+    timeout-minutes: 30
 
-    - name: netbsd-amd64
-      run: make smoke-vagrant/netbsd-amd64
+  # linux-386 needs VirtualBox, which conflicts with KVM/libvirt -- isolated job.
+  smoke-extra-virtualbox:
+    if: github.ref == 'refs/heads/master' || contains(github.event.pull_request.labels.*.name, 'smoke-test-extra')
+    name: linux-386
+    runs-on: ubuntu-latest
+    env:
+      VAGRANT_DEFAULT_PROVIDER: virtualbox
+    steps:
 
-    - name: linux-amd64-ipv6disable
-      run: make smoke-vagrant/linux-amd64-ipv6disable
+    - uses: actions/checkout@v6
 
-    # linux-386 runs last because it requires disabling KVM to use VirtualBox,
-    # which prevents libvirt (used by the other tests) from working after this point.
-    - name: install virtualbox for i386 test
+    - uses: actions/setup-go@v6
+      with:
+        go-version: '1.25'
+        check-latest: true
+
+    - name: add hashicorp source
+      run: wget -O- https://apt.releases.hashicorp.com/gpg | gpg --dearmor | sudo tee /usr/share/keyrings/hashicorp-archive-keyring.gpg && echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
+
+    - name: install vagrant and virtualbox
       run: |
-        sudo apt-get install -y virtualbox
+        sudo apt-get update && sudo apt-get install -y vagrant virtualbox
         sudo rmmod kvm_amd kvm_intel kvm 2>/dev/null || true
 
     - name: linux-386
-      env:
-        VAGRANT_DEFAULT_PROVIDER: virtualbox
       run: make smoke-vagrant/linux-386
 
     timeout-minutes: 30
+
+  smoke-windows:
+    if: github.ref == 'refs/heads/master' || contains(github.event.pull_request.labels.*.name, 'smoke-test-extra')
+    name: Run windows smoke test
+    runs-on: windows-latest
+    steps:
+
+    - uses: actions/checkout@v6
+
+    - uses: actions/setup-go@v6
+      with:
+        go-version: '1.25'
+        check-latest: true
+
+    # WSL2 + Ubuntu so the smoke can run a real linux peer with its own
+    # netns. iputils-ping is needed for the in-WSL ping check. WSL1 has no
+    # real kernel and would lack /dev/net/tun, so we have to force WSL2.
+    - uses: Vampire/setup-wsl@v3
+      with:
+        distribution: Ubuntu-24.04
+        additional-packages: iputils-ping iproute2
+
+    # Vampire/setup-wsl provisions WSL1 even when the WSL2 platform is present.
+    # Convert the distro to WSL2 explicitly before we try to use /dev/net/tun.
+    - name: convert distro to WSL2
+      shell: pwsh
+      run: |
+        wsl --set-version Ubuntu-24.04 2
+        wsl --shutdown
+        wsl --list --verbose
+
+    - name: build windows nebula
+      run: make bin-windows
+
+    - name: build linux nebula for WSL
+      shell: bash
+      env:
+        GOOS: linux
+        GOARCH: amd64
+      run: |
+        mkdir -p build/linux-amd64
+        go build -o build/linux-amd64/nebula ./cmd/nebula
+
+    - name: run smoke-windows
+      shell: pwsh
+      working-directory: ./.github/workflows/smoke
+      run: ./smoke-windows.ps1
+
+    timeout-minutes: 15

.github/workflows/smoke/smoke-windows.ps1

@@ -0,0 +1,272 @@
+#!/usr/bin/env pwsh
+# Windows smoke test for the nebula tun + UDP + NLM code paths.
+#
+# Topology:
+#   - lighthouse runs natively on the Windows host (wintun + windows UDP)
+#   - peer runs inside WSL2 (Linux build of nebula, /dev/net/tun)
+#
+# WSL2 gives us a real netns boundary so the loopback fast-path on Windows
+# does not short-circuit the overlay -- when WSL pings the lighthouse VPN IP,
+# Linux has no idea that IP is local to the Windows host, so the packet is
+# forced through nebula. Same in reverse.
+
+$ErrorActionPreference = 'Stop'
+
+# wsl.exe emits UTF-16 LE by default which PowerShell reads as bytes, mangling
+# every captured string. WSL_UTF8 makes wsl.exe emit UTF-8 instead.
+$env:WSL_UTF8 = '1'
+
+$RepoRoot = Resolve-Path "$PSScriptRoot\..\..\.."
+$Nebula = Join-Path $RepoRoot 'nebula.exe'
+$NebulaCert = Join-Path $RepoRoot 'nebula-cert.exe'
+$NebulaLinux = Join-Path $RepoRoot 'build\linux-amd64\nebula'
+
+if (-not (Test-Path $Nebula)) { throw "missing $Nebula; run 'make bin-windows' first" }
+if (-not (Test-Path $NebulaCert)) { throw "missing $NebulaCert; run 'make bin-windows' first" }
+if (-not (Test-Path $NebulaLinux)) { throw "missing $NebulaLinux; build the linux nebula first" }
+
+# Matches the distro installed by Vampire/setup-wsl in smoke-extra.yml.
+$Distro = 'Ubuntu-24.04'
+$listed = (wsl --list --quiet 2>$null) -join "`n"
+if ($listed -notmatch [regex]::Escape($Distro)) {
+    throw "WSL distro $Distro not registered. Got: $listed"
+}
+Write-Host "Using WSL distro: $Distro"
+
+# Windows host as seen from inside WSL: WSL's default-route gateway. We extract
+# it with a regex rather than awk fields so PowerShell does not eat any '$N'
+# tokens, and tabs/double-spaces in `ip route` output do not confuse a cut.
+$ipCmd = 'ip route show default | grep -oE "([0-9]+\.){3}[0-9]+" | head -1'
+$WindowsIp = (wsl -d $Distro -- bash -c $ipCmd).Trim()
+if (-not $WindowsIp) { throw "could not determine Windows host IP from WSL" }
+Write-Host "Windows host IP from WSL: $WindowsIp"
+
+$WorkDir = Join-Path $env:TEMP 'nebula-smoke-windows'
+if (Test-Path $WorkDir) { Remove-Item -Recurse -Force $WorkDir }
+New-Item -ItemType Directory -Path $WorkDir | Out-Null
+
+$WslDir = '/tmp/nebula-smoke'
+wsl -d $Distro -- bash -c "rm -rf $WslDir && mkdir -p $WslDir" | Out-Null
+
+$DevName = 'nebula-smoke'
+$Ip1 = '192.168.241.1'
+$Ip2 = '192.168.241.2'
+$Port = 4242
+
+& $NebulaCert ca -name 'smoke-ca' -out-crt "$WorkDir\ca.crt" -out-key "$WorkDir\ca.key"
+if ($LASTEXITCODE -ne 0) { throw "nebula-cert ca failed (exit $LASTEXITCODE)" }
+
+& $NebulaCert sign -name 'lighthouse' -networks "$Ip1/24" -ca-crt "$WorkDir\ca.crt" -ca-key "$WorkDir\ca.key" -out-crt "$WorkDir\lighthouse.crt" -out-key "$WorkDir\lighthouse.key"
+if ($LASTEXITCODE -ne 0) { throw "nebula-cert sign lighthouse failed (exit $LASTEXITCODE)" }
+
+& $NebulaCert sign -name 'peer' -networks "$Ip2/24" -ca-crt "$WorkDir\ca.crt" -ca-key "$WorkDir\ca.key" -out-crt "$WorkDir\peer.crt" -out-key "$WorkDir\peer.key"
+if ($LASTEXITCODE -ne 0) { throw "nebula-cert sign peer failed (exit $LASTEXITCODE)" }
+
+# Windows lighthouse config.
+@"
+pki:
+  ca: $WorkDir\ca.crt
+  cert: $WorkDir\lighthouse.crt
+  key: $WorkDir\lighthouse.key
+static_host_map: {}
+lighthouse:
+  am_lighthouse: true
+  interval: 60
+  hosts: []
+listen:
+  host: 0.0.0.0
+  port: $Port
+tun:
+  disabled: false
+  dev: $DevName
+  drop_local_broadcast: false
+  drop_multicast: false
+  tx_queue: 500
+  mtu: 1300
+  network_category: private
+logging:
+  level: info
+  format: text
+firewall:
+  outbound_action: drop
+  inbound_action: drop
+  conntrack:
+    tcp_timeout: 12m
+    udp_timeout: 3m
+    default_timeout: 10m
+  outbound:
+    - port: any
+      proto: any
+      host: any
+  inbound:
+    - port: any
+      proto: any
+      host: any
+"@ | Out-File -FilePath "$WorkDir\lighthouse.yml" -Encoding utf8
+
+# WSL peer config (paths are POSIX, deliberately).
+@"
+pki:
+  ca: $WslDir/ca.crt
+  cert: $WslDir/peer.crt
+  key: $WslDir/peer.key
+static_host_map:
+  "${Ip1}": ["${WindowsIp}:$Port"]
+lighthouse:
+  am_lighthouse: false
+  interval: 60
+  hosts:
+    - "${Ip1}"
+listen:
+  host: 0.0.0.0
+  port: 0
+tun:
+  disabled: false
+  dev: nebula1
+  drop_local_broadcast: false
+  drop_multicast: false
+  tx_queue: 500
+  mtu: 1300
+logging:
+  level: info
+  format: text
+firewall:
+  outbound_action: drop
+  inbound_action: drop
+  conntrack:
+    tcp_timeout: 12m
+    udp_timeout: 3m
+    default_timeout: 10m
+  outbound:
+    - port: any
+      proto: any
+      host: any
+  inbound:
+    - port: any
+      proto: any
+      host: any
+"@ | Out-File -FilePath "$WorkDir\peer.yml" -Encoding utf8
+
+# Stage WSL artifacts. Convert Windows paths to WSL paths ourselves rather than
+# calling `wslpath`, because PowerShell's argument-passing to external EXEs
+# strips backslashes from path arguments in ways that are hard to escape around.
+function ConvertTo-WslPath {
+    param([string]$WindowsPath)
+    if ($WindowsPath -notmatch '^([A-Za-z]):\\(.*)$') {
+        throw "cannot convert path to WSL: $WindowsPath"
+    }
+    return "/mnt/$($matches[1].ToLower())/$($matches[2].Replace('\','/'))"
+}
+
+$WslWorkDir = ConvertTo-WslPath $WorkDir
+$WslNebulaPath = ConvertTo-WslPath $NebulaLinux
+wsl -d $Distro -- bash -c "cp '$WslWorkDir/ca.crt' '$WslWorkDir/peer.crt' '$WslWorkDir/peer.key' '$WslWorkDir/peer.yml' $WslDir/ && cp '$WslNebulaPath' $WslDir/nebula && chmod +x $WslDir/nebula"
+
+# Make sure WSL has tun support and /dev/net/tun is usable before starting
+# nebula. Diagnostics first so a fail here points at the real problem (e.g.
+# WSL1 distros do not have a real kernel and will not have tun).
+Write-Host '=== WSL diagnostic ==='
+wsl --version 2>&1 | Out-Host
+wsl --list --verbose 2>&1 | Out-Host
+wsl -d $Distro -u root -- uname -a | Out-Host
+wsl -d $Distro -u root -- bash -c "modprobe tun 2>&1 || true; mkdir -p /dev/net; [ -c /dev/net/tun ] || mknod /dev/net/tun c 10 200; chmod 600 /dev/net/tun; ls -l /dev/net/tun"
+if ($LASTEXITCODE -ne 0) { throw "failed to prepare /dev/net/tun in WSL (TUN support missing?)" }
+
+# Deliberately no New-NetFirewallRule calls here -- nebula's windows_bypass_wdf
+# feature is supposed to install WFP permit filters that let inbound traffic
+# through Windows Defender Firewall on its own. If this smoke regresses, that
+# feature regressed.
+
+$lhOut = Join-Path $WorkDir 'lighthouse.out.log'
+$lhErr = Join-Path $WorkDir 'lighthouse.err.log'
+$lhProc = Start-Process -FilePath $Nebula -ArgumentList @('-config', "$WorkDir\lighthouse.yml") `
+    -PassThru -NoNewWindow `
+    -RedirectStandardOutput $lhOut `
+    -RedirectStandardError $lhErr
+
+# Run nebula in WSL as root with no sudo + no shell wrapper. PowerShell's
+# Start-Process arg quoting mangles `bash -c "..."` strings that contain
+# spaces/redirections, so we skip bash entirely and let Start-Process do the
+# stdout/stderr capture itself.
+$peerOut = Join-Path $WorkDir 'peer.out.log'
+$peerErr = Join-Path $WorkDir 'peer.err.log'
+$peerProc = Start-Process -FilePath 'wsl' `
+    -ArgumentList @('-d', $Distro, '-u', 'root', '--', "$WslDir/nebula", '-config', "$WslDir/peer.yml") `
+    -PassThru -NoNewWindow `
+    -RedirectStandardOutput $peerOut `
+    -RedirectStandardError $peerErr
+
+function Wait-Until {
+    param([scriptblock]$Predicate, [int]$TimeoutSec, [string]$What)
+    $deadline = (Get-Date).AddSeconds($TimeoutSec)
+    while ((Get-Date) -lt $deadline) {
+        if (& $Predicate) { return }
+        Start-Sleep -Milliseconds 500
+    }
+    throw "timed out waiting for: $What"
+}
+
+try {
+    Wait-Until -TimeoutSec 30 -What "windows wintun adapter $DevName with NetworkCategory=Private" -Predicate {
+        if ($lhProc.HasExited) { throw "lighthouse exited (code $($lhProc.ExitCode)) before tun was ready" }
+        $p = Get-NetConnectionProfile -InterfaceAlias $DevName -ErrorAction SilentlyContinue
+        $p -and ("$($p.NetworkCategory)" -ieq 'Private')
+    }
+    Write-Host "OK: $DevName NetworkCategory=Private"
+
+    Wait-Until -TimeoutSec 30 -What "WSL nebula1 with $Ip2" -Predicate {
+        if ($peerProc.HasExited) { throw "peer exited (code $($peerProc.ExitCode)) before tun was ready" }
+        $r = wsl -d $Distro -u root -- bash -c "ip -o addr show nebula1 2>/dev/null | grep -q 'inet $Ip2' && echo yes"
+        ("$r").Trim() -eq 'yes'
+    }
+    Write-Host "OK: WSL nebula1 has $Ip2"
+
+    Wait-Until -TimeoutSec 30 -What "ping from WSL peer to windows lighthouse ($Ip1)" -Predicate {
+        if ($peerProc.HasExited) { throw "peer exited (code $($peerProc.ExitCode)) before ping succeeded" }
+        $r = wsl -d $Distro -u root -- bash -c "ping -c1 -W1 $Ip1 >/dev/null 2>&1 && echo OK"
+        ("$r").Trim() -eq 'OK'
+    }
+    Write-Host "OK: WSL peer -> windows lighthouse"
+
+    Wait-Until -TimeoutSec 30 -What "ping from windows lighthouse to WSL peer ($Ip2)" -Predicate {
+        $null = & ping.exe -n 1 -w 1000 $Ip2
+        $LASTEXITCODE -eq 0
+    }
+    Write-Host "OK: windows lighthouse -> WSL peer"
+
+    Write-Host ''
+    Write-Host 'All smoke checks passed.'
+}
+catch {
+    Write-Host ''
+    Write-Host '=== lighthouse stdout ==='
+    Get-Content $lhOut -ErrorAction SilentlyContinue | Out-Host
+    Write-Host '=== lighthouse stderr ==='
+    Get-Content $lhErr -ErrorAction SilentlyContinue | Out-Host
+    Write-Host '=== peer stdout ==='
+    Get-Content $peerOut -ErrorAction SilentlyContinue | Out-Host
+    Write-Host '=== peer stderr ==='
+    Get-Content $peerErr -ErrorAction SilentlyContinue | Out-Host
+    Write-Host '=== nebula WFP filters ==='
+    # Dump nebula-installed filters so we can verify they got registered with
+    # the conditions we expect.
+    $wfpDump = Join-Path $WorkDir 'wfp.xml'
+    netsh wfp show filters file=$wfpDump 2>&1 | Out-Null
+    if (Test-Path $wfpDump) {
+        Select-String -Path $wfpDump -Pattern 'Nebula' -Context 0,80 -ErrorAction SilentlyContinue | Out-Host
+    }
+    throw
+}
+finally {
+    if (-not $lhProc.HasExited) {
+        Stop-Process -Id $lhProc.Id -Force -ErrorAction SilentlyContinue
+        $lhProc.WaitForExit(5000) | Out-Null
+    }
+    wsl -d $Distro -u root -- bash -c "pkill -f $WslDir/nebula 2>/dev/null; true" | Out-Null
+    # pkill returns 1 when no match and wsl propagates that; the smoke is done
+    # so we don't want it to leak into the script's exit code.
+    $global:LASTEXITCODE = 0
+    if ($peerProc -and -not $peerProc.HasExited) {
+        Stop-Process -Id $peerProc.Id -Force -ErrorAction SilentlyContinue
+    }
+}

.github/workflows/smoke/vagrant-netbsd-amd64/Vagrantfile

@@ -1,7 +1,7 @@
 # -*- mode: ruby -*-
 # vi: set ft=ruby :
 Vagrant.configure("2") do |config|
-  config.vm.box = "generic/netbsd9"
+  config.vm.box = "DefinedNet/netbsd10"
 
   config.vm.synced_folder "../build", "/nebula", type: "rsync"
 end

.github/workflows/test.yml

@@ -45,7 +45,7 @@ jobs:
     - name: Build test mobile
       run: make build-test-mobile
 
-    - uses: actions/upload-artifact@v6
+    - uses: actions/upload-artifact@v7
       with:
         name: e2e packet flow linux-latest
         path: e2e/mermaid/linux-latest
@@ -125,7 +125,7 @@ jobs:
     - name: End 2 end
       run: make e2evv
 
-    - uses: actions/upload-artifact@v6
+    - uses: actions/upload-artifact@v7
       with:
         name: e2e packet flow ${{ matrix.os }}
         path: e2e/mermaid/${{ matrix.os }}

bits.go

@@ -2,24 +2,42 @@ package nebula
 
 import (
 	"context"
+	"fmt"
 	"log/slog"
+	"math"
+	mathbits "math/bits"
 
 	"github.com/rcrowley/go-metrics"
 )
 
+const bitsPerWord = 64
+
+// Bits is a sliding-window anti-replay tracker. The window is stored as a
+// circular bitmap packed into uint64 words (8x denser than a []bool), so a
+// length-N window costs N/8 bytes. length must be a power of two.
 type Bits struct {
 	length             uint64
+	lengthMask         uint64
 	current            uint64
-	bits               []bool
+	bits               []uint64
 	lostCounter        metrics.Counter
 	dupeCounter        metrics.Counter
 	outOfWindowCounter metrics.Counter
 }
 
-func NewBits(bits uint64) *Bits {
+func NewBits(length uint64) *Bits {
+	if length == 0 || length&(length-1) != 0 {
+		panic(fmt.Sprintf("Bits length must be a power of two, got %d", length))
+	}
+
+	nWords := length / bitsPerWord
+	if nWords == 0 {
+		nWords = 1
+	}
 	b := &Bits{
-		length:             bits,
-		bits:               make([]bool, bits, bits),
+		length:             length,
+		lengthMask:         length - 1,
+		bits:               make([]uint64, nWords),
 		current:            0,
 		lostCounter:        metrics.GetOrRegisterCounter("network.packets.lost", nil),
 		dupeCounter:        metrics.GetOrRegisterCounter("network.packets.duplicate", nil),
@@ -27,71 +45,194 @@ func NewBits(bits uint64) *Bits {
 	}
 
 	// There is no counter value 0, mark it to avoid counting a lost packet later.
-	b.bits[0] = true
-	b.current = 0
+	b.bits[0] = 1
 	return b
 }
 
+func (b *Bits) get(i uint64) bool {
+	pos := i & b.lengthMask
+	//bit-shifting by 6 because i is a bit index, not a u64 index, and we need to find the u64 without bit in it
+	return b.bits[pos>>6]&(uint64(1)<<(pos&63)) != 0
+}
+
+func (b *Bits) set(i uint64) {
+	pos := i & b.lengthMask
+	b.bits[pos>>6] |= uint64(1) << (pos & 63)
+}
+
+// clearRange clears `count` bits starting at circular position `startPos`
+// (already masked to [0, length)) and returns how many of them were set
+// before the clear. count must be in [1, length].
+func (b *Bits) clearRange(startPos, count uint64) uint64 {
+	wasSet := uint64(0)
+	if count >= b.length {
+		for _, w := range b.bits {
+			wasSet += uint64(mathbits.OnesCount64(w))
+		}
+		clear(b.bits)
+		return wasSet
+	}
+
+	pos := startPos
+	remaining := count
+
+	// handle the potential partial word before pos becomes u64 aligned
+	word := pos >> 6
+	bit := pos & 63
+	take := uint64(64) - bit
+	if take > remaining {
+		take = remaining
+	}
+	if take > b.length-pos {
+		take = b.length - pos
+	}
+	var mask uint64
+	if take == 64 {
+		mask = math.MaxUint64
+	} else {
+		mask = ((uint64(1) << take) - 1) << bit
+	}
+	wasSet += uint64(mathbits.OnesCount64(b.bits[word] & mask))
+	b.bits[word] &^= mask
+	remaining -= take
+	pos = (pos + take) & b.lengthMask
+
+	// Clear whole words, keeping track of the number of set bits
+	for remaining >= 64 {
+		word = pos >> 6
+		wasSet += uint64(mathbits.OnesCount64(b.bits[word]))
+		b.bits[word] = 0
+		remaining -= 64
+		pos = (pos + 64) & b.lengthMask
+	}
+
+	// Clear the remaining partial word
+	if remaining > 0 {
+		word = pos >> 6
+		mask = (uint64(1) << remaining) - 1
+		wasSet += uint64(mathbits.OnesCount64(b.bits[word] & mask))
+		b.bits[word] &^= mask
+	}
+
+	return wasSet
+}
+
+func (b *Bits) strictlyWithinWindow(i uint64) bool {
+	// Handle the case where the window hasn't slid yet. This avoids u64 underflow.
+	inWarmup := b.current < b.length
+	if i < b.length && inWarmup {
+		return true
+	}
+
+	// Next, if the packet is in-window, see if we've seen it before
+	if i > b.current-b.length {
+		return true
+	}
+	return false //not within window!
+}
+
+// Check returns true if i is within (or way out in front of) the window, and not a replay
 func (b *Bits) Check(l *slog.Logger, i uint64) bool {
 	// If i is the next number, return true.
 	if i > b.current {
 		return true
 	}
 
-	// If i is within the window, check if it's been set already.
-	if i > b.current-b.length || i < b.length && b.current < b.length {
-		return !b.bits[i%b.length]
+	if b.strictlyWithinWindow(i) {
+		return !b.get(i)
 	}
 
 	// Not within the window
 	if l.Enabled(context.Background(), slog.LevelDebug) {
-		l.Debug("rejected a packet (top)",
-			"current", b.current,
-			"incoming", i,
-		)
+		l.Debug("rejected a packet (top)", "current", b.current, "incoming", i)
 	}
 	return false
 }
 
+// Update has three branches:
+//   - i == b.current+1: fast path; advance the cursor by one and lose-count
+//     the slot we just stomped (only past warmup; see the i > b.length guard
+//     below).
+//   - i  >  b.current+1: jump path; clear all slots between current and i
+//     (or up to a full window's worth, whichever is smaller) via clearRange,
+//     then mark i. Two arms here: a warmup arm that handles the very first
+//     window before the cursor has slid, and a steady-state arm that treats
+//     every cleared empty slot as a lost packet.
+//   - i  <= b.current: in-window check for duplicates; out-of-window otherwise.
+//
+// NewBits seeds bits[0]=1 so counter 0 looks "received" — Update never
+// clears that marker during warmup (clearRange skips position 0 when
+// startPos=1), and once b.current >= b.length the marker is no longer
+// consulted. The marker prevents a fictitious "lost" hit on the first real
+// counter.
 func (b *Bits) Update(l *slog.Logger, i uint64) bool {
-	// If i is the next number, return true and update current.
+	// Fast path: i is the next expected counter. Split out so the function
+	// stays small and avoids paying for the slow paths' slog argument-build
+	// stack frame on every call. The bit read/test/write is inlined to
+	// touch the backing word once.
 	if i == b.current+1 {
-		// Check if the oldest bit was lost since we are shifting the window by 1 and occupying it with this counter
-		// The very first window can only be tracked as lost once we are on the 2nd window or greater
-		if b.bits[i%b.length] == false && i > b.length {
+		pos := i & b.lengthMask
+		word := pos >> 6
+		mask := uint64(1) << (pos & 63)
+		w := b.bits[word]
+		if i > b.length && w&mask == 0 {
 			b.lostCounter.Inc(1)
 		}
-		b.bits[i%b.length] = true
+		b.bits[word] = w | mask
 		b.current = i
 		return true
 	}
+	return b.updateSlow(l, i)
+}
 
+// updateSlow handles jumps, in-window backfill, dupes, and out-of-window.
+func (b *Bits) updateSlow(l *slog.Logger, i uint64) bool {
 	// If i is a jump, adjust the window, record lost, update current, and return true
 	if i > b.current {
-		lost := int64(0)
-		// Zero out the bits between the current and the new counter value, limited by the window size,
-		// since the window is shifting
-		for n := b.current + 1; n <= min(i, b.current+b.length); n++ {
-			if b.bits[n%b.length] == false && n > b.length {
-				lost++
+		end := i
+		if end > b.current+b.length {
+			end = b.current + b.length
+		}
+		count := end - b.current
+		startPos := (b.current + 1) & b.lengthMask
+
+		var lost int64
+		if b.current >= b.length {
+			// Steady state: every cleared slot is past warmup, so any unset
+			// bit we evict is a lost packet from the previous cycle.
+			wasSet := b.clearRange(startPos, count)
+			lost = int64(count) - int64(wasSet)
+		} else {
+			// Warmup (the very first window). Some cleared slots represent
+			// packets <= length where eviction is not "lost" in the usual
+			// sense. This branch is taken at most once per connection so we
+			// don't bother optimizing it.
+			for n := b.current + 1; n <= end; n++ {
+				if !b.get(n) && n > b.length {
+					lost++
+				}
 			}
-			b.bits[n%b.length] = false
+			b.clearRange(startPos, count)
 		}
 
-		// Only record any skipped packets as a result of the window moving further than the window length
-		// Any loss within the new window will be accounted for in future calls
-		lost += max(0, int64(i-b.current-b.length))
+		// Anything past the new window can never be backfilled, so it's lost.
+		if i > b.current+b.length {
+			lost += int64(i - b.current - b.length)
+		}
 		b.lostCounter.Inc(lost)
 
-		b.bits[i%b.length] = true
+		b.set(i)
 		b.current = i
 		return true
 	}
 
-	// If i is within the current window but below the current counter,
-	// Check to see if it's a duplicate
-	if i > b.current-b.length || i < b.length && b.current < b.length {
-		if b.current == i || b.bits[i%b.length] == true {
+	// If i is within the current window but below the current counter, check to see if it's a duplicate
+	if b.strictlyWithinWindow(i) {
+		pos := i & b.lengthMask
+		word := pos >> 6
+		mask := uint64(1) << (pos & 63)
+		w := b.bits[word]
+		if b.current == i || w&mask != 0 {
 			if l.Enabled(context.Background(), slog.LevelDebug) {
 				l.Debug("Receive window",
 					"accepted", false,
@@ -104,7 +245,7 @@ func (b *Bits) Update(l *slog.Logger, i uint64) bool {
 			return false
 		}
 
-		b.bits[i%b.length] = true
+		b.bits[word] = w | mask
 		return true
 	}
 

bits_test.go

@@ -7,61 +7,79 @@ import (
 	"github.com/stretchr/testify/assert"
 )
 
+// snapshot returns the bitmap as a []bool of length b.length, for readable
+// test assertions against the now-packed []uint64 storage.
+func (b *Bits) snapshot() []bool {
+	out := make([]bool, b.length)
+	for i := uint64(0); i < b.length; i++ {
+		out[i] = b.get(i)
+	}
+	return out
+}
+
+func TestBitsRequiresPowerOfTwo(t *testing.T) {
+	assert.Panics(t, func() { NewBits(10) })
+	assert.Panics(t, func() { NewBits(0) })
+	assert.NotPanics(t, func() { NewBits(1) })
+	assert.NotPanics(t, func() { NewBits(16) })
+	assert.NotPanics(t, func() { NewBits(1024) })
+	assert.NotPanics(t, func() { NewBits(16384) })
+}
+
 func TestBits(t *testing.T) {
 	l := test.NewLogger()
-	b := NewBits(10)
-
-	// make sure it is the right size
-	assert.Len(t, b.bits, 10)
+	b := NewBits(16)
+	assert.EqualValues(t, 16, b.length)
 
 	// This is initialized to zero - receive one. This should work.
 	assert.True(t, b.Check(l, 1))
 	assert.True(t, b.Update(l, 1))
 	assert.EqualValues(t, 1, b.current)
-	g := []bool{true, true, false, false, false, false, false, false, false, false}
-	assert.Equal(t, g, b.bits)
+	g := []bool{true, true, false, false, false, false, false, false, false, false, false, false, false, false, false, false}
+	assert.Equal(t, g, b.snapshot())
 
 	// Receive two
 	assert.True(t, b.Check(l, 2))
 	assert.True(t, b.Update(l, 2))
 	assert.EqualValues(t, 2, b.current)
-	g = []bool{true, true, true, false, false, false, false, false, false, false}
-	assert.Equal(t, g, b.bits)
+	g = []bool{true, true, true, false, false, false, false, false, false, false, false, false, false, false, false, false}
+	assert.Equal(t, g, b.snapshot())
 
 	// Receive two again - it will fail
 	assert.False(t, b.Check(l, 2))
 	assert.False(t, b.Update(l, 2))
 	assert.EqualValues(t, 2, b.current)
 
-	// Jump ahead to 15, which should clear everything and set the 6th element
-	assert.True(t, b.Check(l, 15))
-	assert.True(t, b.Update(l, 15))
-	assert.EqualValues(t, 15, b.current)
-	g = []bool{false, false, false, false, false, true, false, false, false, false}
-	assert.Equal(t, g, b.bits)
+	// Jump ahead to 25, which clears the window and sets slot 25%16 = 9.
+	assert.True(t, b.Check(l, 25))
+	assert.True(t, b.Update(l, 25))
+	assert.EqualValues(t, 25, b.current)
+	g = []bool{false, false, false, false, false, false, false, false, false, true, false, false, false, false, false, false}
+	assert.Equal(t, g, b.snapshot())
 
-	// Mark 14, which is allowed because it is in the window
-	assert.True(t, b.Check(l, 14))
-	assert.True(t, b.Update(l, 14))
-	assert.EqualValues(t, 15, b.current)
-	g = []bool{false, false, false, false, true, true, false, false, false, false}
-	assert.Equal(t, g, b.bits)
+	// Mark 24, which is in window (current 25, length 16, window covers [10,25]).
+	assert.True(t, b.Check(l, 24))
+	assert.True(t, b.Update(l, 24))
+	assert.EqualValues(t, 25, b.current)
+	g = []bool{false, false, false, false, false, false, false, false, true, true, false, false, false, false, false, false}
+	assert.Equal(t, g, b.snapshot())
 
-	// Mark 5, which is not allowed because it is not in the window
+	// Mark 5, not allowed because 5 <= current-length (25-16=9).
 	assert.False(t, b.Check(l, 5))
 	assert.False(t, b.Update(l, 5))
-	assert.EqualValues(t, 15, b.current)
-	g = []bool{false, false, false, false, true, true, false, false, false, false}
-	assert.Equal(t, g, b.bits)
+	assert.EqualValues(t, 25, b.current)
+	g = []bool{false, false, false, false, false, false, false, false, true, true, false, false, false, false, false, false}
+	assert.Equal(t, g, b.snapshot())
 
-	// make sure we handle wrapping around once to the current position
-	b = NewBits(10)
+	// Make sure we handle wrapping around once to the same slot. With
+	// length=16, packets 1 and 17 share slot 1.
+	b = NewBits(16)
 	assert.True(t, b.Update(l, 1))
-	assert.True(t, b.Update(l, 11))
-	assert.Equal(t, []bool{false, true, false, false, false, false, false, false, false, false}, b.bits)
+	assert.True(t, b.Update(l, 17))
+	assert.Equal(t, []bool{false, true, false, false, false, false, false, false, false, false, false, false, false, false, false, false}, b.snapshot())
 
 	// Walk through a few windows in order
-	b = NewBits(10)
+	b = NewBits(16)
 	for i := uint64(1); i <= 100; i++ {
 		assert.True(t, b.Check(l, i), "Error while checking %v", i)
 		assert.True(t, b.Update(l, i), "Error while updating %v", i)
@@ -72,24 +90,31 @@ func TestBits(t *testing.T) {
 
 func TestBitsLargeJumps(t *testing.T) {
 	l := test.NewLogger()
-	b := NewBits(10)
+
+	// length=16. Update(55) from current=0:
+	//   warmup, per-bit loop sees no n>16 with unset bits (slot 0 was set by
+	//   NewBits and gets re-evaluated when n=16; n=16 is not strictly > 16),
+	//   so the loop contributes 0. The jump exceeds the window so we record
+	//   55 - 0 - 16 = 39 packets fell out the back.
+	b := NewBits(16)
 	b.lostCounter.Clear()
+	assert.True(t, b.Update(l, 55))
+	assert.Equal(t, int64(39), b.lostCounter.Count())
 
-	b = NewBits(10)
-	b.lostCounter.Clear()
-	assert.True(t, b.Update(l, 55)) // We saw packet 55 and can still track 45,46,47,48,49,50,51,52,53,54
-	assert.Equal(t, int64(45), b.lostCounter.Count())
+	// Update(100): clears 16 slots starting at slot 56%16=8. Only slot 7 (for
+	// packet 55) was set, so 16 - 1 = 15 evicted slots had unset bits.
+	// Plus 100 - 55 - 16 = 29 packets fell past the window. Total 44.
+	assert.True(t, b.Update(l, 100))
+	assert.Equal(t, int64(39+44), b.lostCounter.Count())
 
-	assert.True(t, b.Update(l, 100)) // We saw packet 55 and 100 and can still track 90,91,92,93,94,95,96,97,98,99
-	assert.Equal(t, int64(89), b.lostCounter.Count())
-
-	assert.True(t, b.Update(l, 200)) // We saw packet 55, 100, and 200 and can still track 190,191,192,193,194,195,196,197,198,199
-	assert.Equal(t, int64(188), b.lostCounter.Count())
+	// Update(200): same shape: 16 - 1 = 15 evicted unset, plus 200 - 100 - 16 = 84 past window. Total 99.
+	assert.True(t, b.Update(l, 200))
+	assert.Equal(t, int64(39+44+99), b.lostCounter.Count())
 }
 
 func TestBitsDupeCounter(t *testing.T) {
 	l := test.NewLogger()
-	b := NewBits(10)
+	b := NewBits(16)
 	b.lostCounter.Clear()
 	b.dupeCounter.Clear()
 	b.outOfWindowCounter.Clear()
@@ -114,120 +139,117 @@ func TestBitsDupeCounter(t *testing.T) {
 
 func TestBitsOutOfWindowCounter(t *testing.T) {
 	l := test.NewLogger()
-	b := NewBits(10)
+	b := NewBits(16)
 	b.lostCounter.Clear()
 	b.dupeCounter.Clear()
 	b.outOfWindowCounter.Clear()
 
+	// Jump to 20 (warmup branch + 4 past-window packets).
 	assert.True(t, b.Update(l, 20))
 	assert.Equal(t, int64(0), b.outOfWindowCounter.Count())
 
-	assert.True(t, b.Update(l, 21))
-	assert.True(t, b.Update(l, 22))
-	assert.True(t, b.Update(l, 23))
-	assert.True(t, b.Update(l, 24))
-	assert.True(t, b.Update(l, 25))
-	assert.True(t, b.Update(l, 26))
-	assert.True(t, b.Update(l, 27))
-	assert.True(t, b.Update(l, 28))
-	assert.True(t, b.Update(l, 29))
+	// 9 single-step advances, each evicts a slot whose bit was cleared during
+	// the jump above and whose value was never seen, so each contributes 1
+	// to lostCounter.
+	for n := uint64(21); n <= 29; n++ {
+		assert.True(t, b.Update(l, n))
+	}
 	assert.Equal(t, int64(0), b.outOfWindowCounter.Count())
 
+	// 0 is below current-length (29-16=13) so it falls outside the window.
 	assert.False(t, b.Update(l, 0))
 	assert.Equal(t, int64(1), b.outOfWindowCounter.Count())
 
-	assert.Equal(t, int64(19), b.lostCounter.Count()) // packet 0 wasn't lost
+	// 4 from the Update(20) jump + 9 from 21..29.
+	assert.Equal(t, int64(13), b.lostCounter.Count())
 	assert.Equal(t, int64(0), b.dupeCounter.Count())
 	assert.Equal(t, int64(1), b.outOfWindowCounter.Count())
 }
 
 func TestBitsLostCounter(t *testing.T) {
 	l := test.NewLogger()
-	b := NewBits(10)
+	b := NewBits(16)
 	b.lostCounter.Clear()
 	b.dupeCounter.Clear()
 	b.outOfWindowCounter.Clear()
 
-	assert.True(t, b.Update(l, 20))
-	assert.True(t, b.Update(l, 21))
-	assert.True(t, b.Update(l, 22))
-	assert.True(t, b.Update(l, 23))
-	assert.True(t, b.Update(l, 24))
-	assert.True(t, b.Update(l, 25))
-	assert.True(t, b.Update(l, 26))
-	assert.True(t, b.Update(l, 27))
-	assert.True(t, b.Update(l, 28))
-	assert.True(t, b.Update(l, 29))
-	assert.Equal(t, int64(19), b.lostCounter.Count()) // packet 0 wasn't lost
+	// Walk 20..29 like the original, just with a bigger window. Same
+	// reasoning as TestBitsOutOfWindowCounter: 4 past-window from Update(20),
+	// then 9 more from the unit advances.
+	for n := uint64(20); n <= 29; n++ {
+		assert.True(t, b.Update(l, n))
+	}
+	assert.Equal(t, int64(13), b.lostCounter.Count())
 	assert.Equal(t, int64(0), b.dupeCounter.Count())
 	assert.Equal(t, int64(0), b.outOfWindowCounter.Count())
 
-	b = NewBits(10)
+	b = NewBits(16)
 	b.lostCounter.Clear()
 	b.dupeCounter.Clear()
 	b.outOfWindowCounter.Clear()
 
-	assert.True(t, b.Update(l, 9))
-	assert.Equal(t, int64(0), b.lostCounter.Count())
-	// 10 will set 0 index, 0 was already set, no lost packets
-	assert.True(t, b.Update(l, 10))
-	assert.Equal(t, int64(0), b.lostCounter.Count())
-	// 11 will set 1 index, 1 was missed, we should see 1 packet lost
-	assert.True(t, b.Update(l, 11))
-	assert.Equal(t, int64(1), b.lostCounter.Count())
-	// Now let's fill in the window, should end up with 8 lost packets
-	assert.True(t, b.Update(l, 12))
-	assert.True(t, b.Update(l, 13))
-	assert.True(t, b.Update(l, 14))
+	// Update(15) clears the warmup window (no lost), sets slot 15.
 	assert.True(t, b.Update(l, 15))
+	assert.Equal(t, int64(0), b.lostCounter.Count())
+
+	// Update(16): slot 0 was already set (NewBits seeded it), and 16 is not
+	// strictly > length, so nothing is recorded as lost.
 	assert.True(t, b.Update(l, 16))
+	assert.Equal(t, int64(0), b.lostCounter.Count())
+
+	// Update(17): we jumped straight from 0 to 15, so slot 1 was cleared
+	// (and never re-set). 17 > 16 is past warmup, so packet 1 is recorded lost.
 	assert.True(t, b.Update(l, 17))
-	assert.True(t, b.Update(l, 18))
-	assert.True(t, b.Update(l, 19))
-	assert.Equal(t, int64(8), b.lostCounter.Count())
+	assert.Equal(t, int64(1), b.lostCounter.Count())
 
-	// Jump ahead by a window size
-	assert.True(t, b.Update(l, 29))
-	assert.Equal(t, int64(8), b.lostCounter.Count())
-	// Now lets walk ahead normally through the window, the missed packets should fill in
-	assert.True(t, b.Update(l, 30))
-	assert.True(t, b.Update(l, 31))
-	assert.True(t, b.Update(l, 32))
-	assert.True(t, b.Update(l, 33))
-	assert.True(t, b.Update(l, 34))
-	assert.True(t, b.Update(l, 35))
-	assert.True(t, b.Update(l, 36))
-	assert.True(t, b.Update(l, 37))
-	assert.True(t, b.Update(l, 38))
-	// 39 packets tracked, 22 seen, 17 lost
-	assert.Equal(t, int64(17), b.lostCounter.Count())
+	// Fill in 18..30 in single steps. Each i evicts slot i%16. Slots 2..14
+	// were all cleared during Update(15), and we never re-set any of them,
+	// so each i in 18..30 is a fresh lost packet — 13 more.
+	for n := uint64(18); n <= 30; n++ {
+		assert.True(t, b.Update(l, n))
+	}
+	assert.Equal(t, int64(14), b.lostCounter.Count())
 
-	// Jump ahead by 2 windows, should have recording 1 full window missing
-	assert.True(t, b.Update(l, 58))
-	assert.Equal(t, int64(27), b.lostCounter.Count())
-	// Now lets walk ahead normally through the window, the missed packets should fill in from this window
-	assert.True(t, b.Update(l, 59))
-	assert.True(t, b.Update(l, 60))
-	assert.True(t, b.Update(l, 61))
-	assert.True(t, b.Update(l, 62))
-	assert.True(t, b.Update(l, 63))
-	assert.True(t, b.Update(l, 64))
-	assert.True(t, b.Update(l, 65))
-	assert.True(t, b.Update(l, 66))
-	assert.True(t, b.Update(l, 67))
-	// 68 packets tracked, 32 seen, 36 missed
-	assert.Equal(t, int64(36), b.lostCounter.Count())
+	// Jump ahead by exactly one window size.
+	assert.True(t, b.Update(l, 46))
+	// end = min(46, 30+16) = 46, count = 16, all slots cleared. Before the
+	// jump every slot 0..15 had been set (Update(15), (16), (17), 18..30),
+	// so wasSet=16 and 46 == current+length means no past-window slack:
+	// lost contribution = 0.
+	assert.Equal(t, int64(14), b.lostCounter.Count())
+
+	// Walk 47..55. The Update(46) jump cleared every slot, so only slot 14
+	// (for packet 46) is set when we start. Each subsequent unit step lands
+	// on a slot that was cleared and is past warmup, so it counts as lost.
+	// 9 more = 23.
+	for n := uint64(47); n <= 55; n++ {
+		assert.True(t, b.Update(l, n))
+	}
+	assert.Equal(t, int64(23), b.lostCounter.Count())
+
+	// Jump ahead by two windows: clears the window plus past-window loss.
+	assert.True(t, b.Update(l, 87))
+	// current=55, length=16. end = min(87, 71) = 71. count=16, all slots
+	// cleared. Slots set before the clear are slots 14,15,0..7 (10 total).
+	// Lost from clear = 16 - 10 = 6. Past window: 87 - 55 - 16 = 16. +22.
+	assert.Equal(t, int64(45), b.lostCounter.Count())
 	assert.Equal(t, int64(0), b.dupeCounter.Count())
 	assert.Equal(t, int64(0), b.outOfWindowCounter.Count())
 }
 
 func TestBitsLostCounterIssue1(t *testing.T) {
 	l := test.NewLogger()
-	b := NewBits(10)
+	b := NewBits(16)
 	b.lostCounter.Clear()
 	b.dupeCounter.Clear()
 	b.outOfWindowCounter.Clear()
 
+	// Receive 4, backfill 1, then 9, 2, 3, 5, 6, 7 (skip 8), 10, 11, 14.
+	// Then jump to 25 — slot 25%16=9 is being evicted, but it had been set
+	// (we received packet 9), so no spurious lost increment. The original
+	// regression was about double-counting a missing packet when its slot
+	// got cleared on a jump. With the jump path now using clearRange's
+	// word-level wasSet count, the same semantics hold.
 	assert.True(t, b.Update(l, 4))
 	assert.Equal(t, int64(0), b.lostCounter.Count())
 	assert.True(t, b.Update(l, 1))
@@ -244,7 +266,7 @@ func TestBitsLostCounterIssue1(t *testing.T) {
 	assert.Equal(t, int64(0), b.lostCounter.Count())
 	assert.True(t, b.Update(l, 7))
 	assert.Equal(t, int64(0), b.lostCounter.Count())
-	// assert.True(t, b.Update(l, 8))
+	// Skip packet 8.
 	assert.True(t, b.Update(l, 10))
 	assert.Equal(t, int64(0), b.lostCounter.Count())
 	assert.True(t, b.Update(l, 11))
@@ -252,9 +274,23 @@ func TestBitsLostCounterIssue1(t *testing.T) {
 
 	assert.True(t, b.Update(l, 14))
 	assert.Equal(t, int64(0), b.lostCounter.Count())
-	// Issue seems to be here, we reset missing packet 8 to false here and don't increment the lost counter
-	assert.True(t, b.Update(l, 19))
+
+	// Jump to 25. With length=16, slot 25%16=9 corresponds to packet 9
+	// (which we DID receive), so its bit is set and no lost++ from that
+	// eviction. The trace below shows the only loss is packet 8.
+	assert.True(t, b.Update(l, 25))
+	// current was 14, i=25. end=min(25,30)=25. count=11. startPos=15.
+	// steady? current=14<16, so warmup branch: per-bit n=15..25, count those
+	// with !get(n) AND n>16. n=17..25 are >16. Among slots 17%16=1..25%16=9
+	// did we set slots 1..9 (packets 1..9)? Yes for all but slot 8 (packet 8
+	// was skipped). n=24 maps to slot 8 which is FALSE → lost++. All other
+	// n in 17..25 map to slots that are set. n=16 is not strictly > 16. So
+	// lost = 1.
 	assert.Equal(t, int64(1), b.lostCounter.Count())
+
+	// Fill in 12, 13, 15, 16. Each is below current=25 (in-window). 16 must
+	// recheck slot 0 — it was set by NewBits and then cleared by the
+	// Update(25) jump, so 16 backfills cleanly.
 	assert.True(t, b.Update(l, 12))
 	assert.Equal(t, int64(1), b.lostCounter.Count())
 	assert.True(t, b.Update(l, 13))
@@ -263,29 +299,140 @@ func TestBitsLostCounterIssue1(t *testing.T) {
 	assert.Equal(t, int64(1), b.lostCounter.Count())
 	assert.True(t, b.Update(l, 16))
 	assert.Equal(t, int64(1), b.lostCounter.Count())
-	assert.True(t, b.Update(l, 17))
-	assert.Equal(t, int64(1), b.lostCounter.Count())
-	assert.True(t, b.Update(l, 18))
-	assert.Equal(t, int64(1), b.lostCounter.Count())
-	assert.True(t, b.Update(l, 20))
-	assert.Equal(t, int64(1), b.lostCounter.Count())
-	assert.True(t, b.Update(l, 21))
 
-	// We missed packet 8 above
+	// We missed packet 8 above and that loss is still recorded once, never
+	// double-counted, never zeroed.
 	assert.Equal(t, int64(1), b.lostCounter.Count())
 	assert.Equal(t, int64(0), b.dupeCounter.Count())
 	assert.Equal(t, int64(0), b.outOfWindowCounter.Count())
 }
 
-func BenchmarkBits(b *testing.B) {
-	z := NewBits(10)
-	for n := 0; n < b.N; n++ {
-		for i := range z.bits {
-			z.bits[i] = true
-		}
-		for i := range z.bits {
-			z.bits[i] = false
-		}
+// TestBitsWarmupOvershoot exercises the jump path's warmup arm with an
+// overshoot past one full window. NewBits leaves current=0 with only slot 0
+// "set" by the marker. Jumping straight to length+k must (a) clear every
+// slot the jump straddles, (b) count only past-window slack (not the
+// in-window slots, which never had a "lost" tenant during warmup), and
+// (c) leave the cursor at the new counter so subsequent unit advances
+// count from steady state. The marker bit at slot 0 is irrelevant once
+// current >= length.
+func TestBitsWarmupOvershoot(t *testing.T) {
+	l := test.NewLogger()
+	b := NewBits(16)
+	b.lostCounter.Clear()
 
+	// Jump from current=0 to i=20 (length=16, overshoot=4).
+	// Warmup arm: counts slots in [1..16] where bit unset and n>length.
+	// Only n=16 was unset and >length: but slot 16%16=0 is the marker,
+	// so b.get(16) reads bits[0]=1 and skips. Result: 0 lost from the loop.
+	// Past-window: i - current - length = 20 - 0 - 16 = 4 lost.
+	assert.True(t, b.Update(l, 20))
+	assert.Equal(t, int64(4), b.lostCounter.Count())
+	assert.Equal(t, uint64(20), b.current)
+
+	// Steady state now (current=20 >= length=16). Unit advance to 21
+	// stomps slot 21%16=5, which was cleared by the jump and not reset,
+	// so this is +1 lost.
+	assert.True(t, b.Update(l, 21))
+	assert.Equal(t, int64(5), b.lostCounter.Count())
+}
+
+// TestBitsCheckAcrossWarmupBoundary pins the underflow trick in Check's
+// in-window clause. While in warmup, b.current-b.length underflows uint64
+// to a huge value so the first OR-clause is always false; the second
+// clause (i < length && current < length) carries the in-window check.
+// Once current >= length the regimes flip cleanly.
+func TestBitsCheckAcrossWarmupBoundary(t *testing.T) {
+	l := test.NewLogger()
+	b := NewBits(16)
+
+	// Warmup: current=0. Check(0) must read the marker (set) and return false.
+	assert.False(t, b.Check(l, 0), "marker slot should look already-received")
+	// Warmup: any 0 < i < length is in-window and unset → accepted.
+	for i := uint64(1); i < 16; i++ {
+		assert.True(t, b.Check(l, i), "warmup in-window i=%d should be accepted", i)
+	}
+	// Warmup: i >= length but > current is "next number" so accepted.
+	assert.True(t, b.Check(l, 16))
+	assert.True(t, b.Check(l, 1_000_000))
+
+	// Cross into steady state.
+	assert.True(t, b.Update(l, 100))
+	// Now current=100, length=16. In-window range is [85..100].
+	// 84 is just outside: the underflow clause activates; 84 > 100-16=84 is false.
+	// And the warmup clause is false (current >= length). So out of window.
+	assert.False(t, b.Check(l, 84))
+	// 85 sits at the boundary. 85 > 84 is true → in window, unset → accept.
+	assert.True(t, b.Check(l, 85))
+	// 100 is current itself; not strictly greater, in-window, but already set.
+	assert.False(t, b.Check(l, 100))
+	// Way out: clearly out of window.
+	assert.False(t, b.Check(l, 50))
+}
+
+// TestBitsMarkerInvariant verifies the seeded bits[0]=1 marker behaves
+// correctly across warmup and beyond. Update should never clear the marker
+// during warmup (clearRange skips position 0 when startPos=1), and once
+// current >= length the marker is no longer consulted by Check/Update on
+// the live path — but it must still report counter 0 as a duplicate while
+// we are in warmup.
+func TestBitsMarkerInvariant(t *testing.T) {
+	l := test.NewLogger()
+	b := NewBits(8)
+
+	// Counter 0 is the seeded marker; Check sees it as already received.
+	assert.False(t, b.Check(l, 0))
+	// Update(0) at current=0 hits the duplicate branch.
+	b.dupeCounter.Clear()
+	assert.False(t, b.Update(l, 0))
+	assert.Equal(t, int64(1), b.dupeCounter.Count())
+
+	// Walk forward through warmup; the marker must remain set.
+	for n := uint64(1); n <= 7; n++ {
+		assert.True(t, b.Update(l, n))
+	}
+	// Position 0 (the marker) should still read as set because we never
+	// cleared it; Update(0) still looks like a duplicate.
+	assert.False(t, b.Check(l, 0))
+
+	// Cross into steady state with a unit advance to 8: pos=0, evicts the
+	// marker bit. The lost-counter guard (i > b.length) is false (8 == 8),
+	// so this advance does NOT charge a lost packet — exactly what the
+	// marker is there to prevent.
+	b.lostCounter.Clear()
+	assert.True(t, b.Update(l, 8))
+	assert.Equal(t, int64(0), b.lostCounter.Count())
+	// The slot at pos 0 is now occupied by counter 8.
+	assert.False(t, b.Check(l, 8))
+}
+
+// BenchmarkBitsUpdateInOrder is the steady-state hot path: each call is
+// i == current+1.
+func BenchmarkBitsUpdateInOrder(b *testing.B) {
+	l := test.NewLogger()
+	z := NewBits(16384)
+	for n := 0; n < b.N; n++ {
+		z.Update(l, uint64(n)+1)
+	}
+}
+
+// BenchmarkBitsUpdateReorder simulates light reorder within the window:
+// every other packet arrives one slot behind its predecessor (forces the
+// in-window backfill branch).
+func BenchmarkBitsUpdateReorder(b *testing.B) {
+	l := test.NewLogger()
+	z := NewBits(16384)
+	for n := 0; n < b.N; n++ {
+		base := uint64(n) * 2
+		z.Update(l, base+2)
+		z.Update(l, base+1)
+	}
+}
+
+// BenchmarkBitsUpdateLargeJumps stresses the clearRange word-level path.
+func BenchmarkBitsUpdateLargeJumps(b *testing.B) {
+	l := test.NewLogger()
+	z := NewBits(16384)
+	for n := 0; n < b.N; n++ {
+		z.Update(l, uint64(n+1)*1000)
 	}
 }

cert/ca_pool.go

@@ -217,6 +217,10 @@ func (ncp *CAPool) verify(c Certificate, now time.Time, certFp string, signerFp
 		return nil, err
 	}
 
+	if signer.Certificate.Curve() != c.Curve() {
+		return nil, ErrCurveMismatch
+	}
+
 	if signer.Certificate.Expired(now) {
 		return nil, ErrRootExpired
 	}

cert/ca_pool_test.go

@@ -654,3 +654,31 @@ func TestCertificateV2_Verify_Subnets(t *testing.T) {
 	_, err = caPool.VerifyCertificate(time.Now(), c)
 	require.NoError(t, err)
 }
+
+func TestCertificateV2_CurveMismatch(t *testing.T) {
+	caIp1 := mustParsePrefixUnmapped("10.0.0.0/16")
+	caIp2 := mustParsePrefixUnmapped("192.168.0.0/24")
+	ca, _, caKey, _ := NewTestCaCert(Version2, Curve_P256, time.Now(), time.Now().Add(10*time.Minute), []netip.Prefix{caIp1, caIp2}, nil, []string{"test"})
+
+	caPem, err := ca.MarshalPEM()
+	require.NoError(t, err)
+
+	caPool := NewCAPool()
+	b, err := caPool.AddCAFromPEM(caPem)
+	require.NoError(t, err)
+	assert.Empty(t, b)
+
+	// ip is outside the network
+	cIp1 := mustParsePrefixUnmapped("10.0.0.1/24")
+	c, _, _, _ := NewTestCert(Version2, Curve_P256, ca, caKey, "test", time.Now(), time.Now().Add(5*time.Minute), []netip.Prefix{cIp1}, nil, []string{"test"})
+
+	fp, _ := c.Fingerprint()
+	_, err = caPool.verify(c, time.Now(), fp, c.Issuer())
+	require.NoError(t, err)
+	//
+	c2 := c.(*certificateV2)
+	c2.curve = Curve_CURVE25519
+	fp, _ = c.Fingerprint()
+	_, err = caPool.verify(c, time.Now(), fp, c.Issuer())
+	require.Error(t, err)
+}

cert/cert_v1.go

@@ -112,6 +112,9 @@ func (c *certificateV1) CheckSignature(key []byte) bool {
 	}
 	switch c.details.curve {
 	case Curve_CURVE25519:
+		if len(key) != ed25519.PublicKeySize {
+			return false //avoids a panic internal to ed25519
+		}
 		return ed25519.Verify(key, b, c.signature)
 	case Curve_P256:
 		pubKey, err := ecdsa.ParseUncompressedPublicKey(elliptic.P256(), key)

cert/cert_v2.go

@@ -151,6 +151,9 @@ func (c *certificateV2) CheckSignature(key []byte) bool {
 
 	switch c.curve {
 	case Curve_CURVE25519:
+		if len(key) != ed25519.PublicKeySize {
+			return false //avoids a panic internal to ed25519
+		}
 		return ed25519.Verify(key, b, c.signature)
 	case Curve_P256:
 		pubKey, err := ecdsa.ParseUncompressedPublicKey(elliptic.P256(), key)

cert/errors.go

@@ -22,6 +22,7 @@ var (
 	ErrCaNotFound                 = errors.New("could not find ca for the certificate")
 	ErrUnknownVersion             = errors.New("certificate version unrecognized")
 	ErrCertPubkeyPresent          = errors.New("certificate has unexpected pubkey present")
+	ErrCurveMismatch              = errors.New("certificate curve does not match CA")
 
 	ErrInvalidPEMBlock                   = errors.New("input did not contain a valid PEM encoded block")
 	ErrInvalidPEMCertificateBanner       = errors.New("bytes did not contain a proper certificate banner")

cert_test/cert.go

@@ -163,3 +163,55 @@ func P256Keypair() ([]byte, []byte) {
 	pubkey := privkey.PublicKey()
 	return pubkey.Bytes(), privkey.Bytes()
 }
+
+// DummyCert is a minimal cert.Certificate implementation for testing error paths.
+type DummyCert struct {
+	Version_        cert.Version
+	Curve_          cert.Curve
+	Groups_         []string
+	IsCA_           bool
+	Issuer_         string
+	Name_           string
+	Networks_       []netip.Prefix
+	NotAfter_       time.Time
+	NotBefore_      time.Time
+	PublicKey_      []byte
+	Signature_      []byte
+	UnsafeNetworks_ []netip.Prefix
+}
+
+func (d *DummyCert) Version() cert.Version                         { return d.Version_ }
+func (d *DummyCert) Curve() cert.Curve                             { return d.Curve_ }
+func (d *DummyCert) Groups() []string                              { return d.Groups_ }
+func (d *DummyCert) IsCA() bool                                    { return d.IsCA_ }
+func (d *DummyCert) Issuer() string                                { return d.Issuer_ }
+func (d *DummyCert) Name() string                                  { return d.Name_ }
+func (d *DummyCert) Networks() []netip.Prefix                      { return d.Networks_ }
+func (d *DummyCert) NotAfter() time.Time                           { return d.NotAfter_ }
+func (d *DummyCert) NotBefore() time.Time                          { return d.NotBefore_ }
+func (d *DummyCert) PublicKey() []byte                             { return d.PublicKey_ }
+func (d *DummyCert) Signature() []byte                             { return d.Signature_ }
+func (d *DummyCert) UnsafeNetworks() []netip.Prefix                { return d.UnsafeNetworks_ }
+func (d *DummyCert) Fingerprint() (string, error)                  { return "", nil }
+func (d *DummyCert) CheckSignature(key []byte) bool                { return false }
+func (d *DummyCert) MarshalForHandshakes() ([]byte, error)         { return nil, nil }
+func (d *DummyCert) MarshalPEM() ([]byte, error)                   { return nil, nil }
+func (d *DummyCert) MarshalJSON() ([]byte, error)                  { return nil, nil }
+func (d *DummyCert) Marshal() ([]byte, error)                      { return nil, nil }
+func (d *DummyCert) String() string                                { return "dummy" }
+func (d *DummyCert) Copy() cert.Certificate                        { return d }
+func (d *DummyCert) VerifyPrivateKey(c cert.Curve, k []byte) error { return nil }
+func (d *DummyCert) Expired(time.Time) bool                        { return false }
+func (d *DummyCert) MarshalPublicKeyPEM() []byte                   { return nil }
+func (d *DummyCert) PublicKeyPEM() []byte                          { return nil }
+
+// NewTestCAPool creates a CAPool from the given CA certificates, panicking on error.
+func NewTestCAPool(cas ...cert.Certificate) *cert.CAPool {
+	pool := cert.NewCAPool()
+	for _, ca := range cas {
+		if err := pool.AddCA(ca); err != nil {
+			panic(err)
+		}
+	}
+	return pool
+}

connection_manager.go

@@ -11,7 +11,6 @@ import (
 	"sync/atomic"
 	"time"
 
-	"github.com/rcrowley/go-metrics"
 	"github.com/slackhq/nebula/cert"
 	"github.com/slackhq/nebula/config"
 	"github.com/slackhq/nebula/header"
@@ -45,19 +44,16 @@ type connectionManager struct {
 	inactivityTimeout       atomic.Int64
 	dropInactive            atomic.Bool
 
-	metricsTxPunchy metrics.Counter
-
 	l *slog.Logger
 }
 
 func newConnectionManagerFromConfig(l *slog.Logger, c *config.C, hm *HostMap, p *Punchy) *connectionManager {
 	cm := &connectionManager{
-		hostMap:         hm,
-		l:               l,
-		punchy:          p,
-		relayUsed:       make(map[uint32]struct{}),
-		relayUsedLock:   &sync.RWMutex{},
-		metricsTxPunchy: metrics.GetOrRegisterCounter("messages.tx.punchy", nil),
+		hostMap:       hm,
+		l:             l,
+		punchy:        p,
+		relayUsed:     make(map[uint32]struct{}),
+		relayUsedLock: &sync.RWMutex{},
 	}
 
 	cm.reload(c, true)
@@ -369,7 +365,7 @@ func (cm *connectionManager) makeTrafficDecision(localIndex uint32, now time.Tim
 
 		if !outTraffic {
 			// Send a punch packet to keep the NAT state alive
-			cm.sendPunch(hostinfo)
+			cm.punchy.SendPunch(hostinfo)
 		}
 
 		return decision, hostinfo, primary
@@ -400,17 +396,16 @@ func (cm *connectionManager) makeTrafficDecision(localIndex uint32, now time.Tim
 
 			// If we aren't sending or receiving traffic then its an unused tunnel and we don't to test the tunnel.
 			// Just maintain NAT state if configured to do so.
-			cm.sendPunch(hostinfo)
+			cm.punchy.SendPunch(hostinfo)
 			cm.trafficTimer.Add(hostinfo.localIndexId, cm.checkInterval)
 			return doNothing, nil, nil
 		}
 
-		if cm.punchy.GetTargetEverything() {
-			// This is similar to the old punchy behavior with a slight optimization.
-			// We aren't receiving traffic but we are sending it, punch on all known
-			// ips in case we need to re-prime NAT state
-			cm.sendPunch(hostinfo)
-		}
+		// We aren't receiving traffic but we are sending it. The outbound
+		// traffic itself refreshes the primary remote's NAT state; this
+		// fans out to non-primary remotes, but only if target_all_remotes
+		// is configured.
+		cm.punchy.SendPunchToAll(hostinfo)
 
 		if cm.l.Enabled(context.Background(), slog.LevelDebug) {
 			hostinfo.logger(cm.l).Debug("Tunnel status",
@@ -512,31 +507,6 @@ func (cm *connectionManager) isInvalidCertificate(now time.Time, hostinfo *HostI
 	}
 }
 
-func (cm *connectionManager) sendPunch(hostinfo *HostInfo) {
-	if !cm.punchy.GetPunch() {
-		// Punching is disabled
-		return
-	}
-
-	if cm.intf.lightHouse.IsAnyLighthouseAddr(hostinfo.vpnAddrs) {
-		// Do not punch to lighthouses, we assume our lighthouse update interval is good enough.
-		// In the event the update interval is not sufficient to maintain NAT state then a publicly available lighthouse
-		// would lose the ability to notify us and punchy.respond would become unreliable.
-		return
-	}
-
-	if cm.punchy.GetTargetEverything() {
-		hostinfo.remotes.ForEach(cm.hostMap.GetPreferredRanges(), func(addr netip.AddrPort, preferred bool) {
-			cm.metricsTxPunchy.Inc(1)
-			cm.intf.outside.WriteTo([]byte{1}, addr)
-		})
-
-	} else if hostinfo.remote.IsValid() {
-		cm.metricsTxPunchy.Inc(1)
-		cm.intf.outside.WriteTo([]byte{1}, hostinfo.remote)
-	}
-}
-
 func (cm *connectionManager) tryRehandshake(hostinfo *HostInfo) {
 	cs := cm.intf.pki.getCertState()
 	curCrt := hostinfo.ConnectionState.myCert

connection_manager_test.go

@@ -7,7 +7,6 @@ import (
 	"testing"
 	"time"
 
-	"github.com/flynn/noise"
 	"github.com/slackhq/nebula/cert"
 	"github.com/slackhq/nebula/config"
 	"github.com/slackhq/nebula/overlay/overlaytest"
@@ -47,7 +46,7 @@ func Test_NewConnectionManagerTest(t *testing.T) {
 		initiatingVersion: cert.Version1,
 		privateKey:        []byte{},
 		v1Cert:            &dummyCert{version: cert.Version1},
-		v1HandshakeBytes:  []byte{},
+		v1Credential:      nil,
 	}
 
 	lh := newTestLighthouse()
@@ -65,7 +64,7 @@ func Test_NewConnectionManagerTest(t *testing.T) {
 
 	// Create manager
 	conf := config.NewC(test.NewLogger())
-	punchy := NewPunchyFromConfig(test.NewLogger(), conf)
+	punchy := NewPunchyFromConfig(test.NewLogger(), conf, nil)
 	nc := newConnectionManagerFromConfig(test.NewLogger(), conf, hostMap, punchy)
 	nc.intf = ifce
 	p := []byte("")
@@ -80,7 +79,6 @@ func Test_NewConnectionManagerTest(t *testing.T) {
 	}
 	hostinfo.ConnectionState = &ConnectionState{
 		myCert: &dummyCert{version: cert.Version1},
-		H:      &noise.HandshakeState{},
 	}
 	nc.hostMap.unlockedAddHostInfo(hostinfo, ifce)
 
@@ -130,7 +128,7 @@ func Test_NewConnectionManagerTest2(t *testing.T) {
 		initiatingVersion: cert.Version1,
 		privateKey:        []byte{},
 		v1Cert:            &dummyCert{version: cert.Version1},
-		v1HandshakeBytes:  []byte{},
+		v1Credential:      nil,
 	}
 
 	lh := newTestLighthouse()
@@ -148,7 +146,7 @@ func Test_NewConnectionManagerTest2(t *testing.T) {
 
 	// Create manager
 	conf := config.NewC(test.NewLogger())
-	punchy := NewPunchyFromConfig(test.NewLogger(), conf)
+	punchy := NewPunchyFromConfig(test.NewLogger(), conf, nil)
 	nc := newConnectionManagerFromConfig(test.NewLogger(), conf, hostMap, punchy)
 	nc.intf = ifce
 	p := []byte("")
@@ -163,7 +161,6 @@ func Test_NewConnectionManagerTest2(t *testing.T) {
 	}
 	hostinfo.ConnectionState = &ConnectionState{
 		myCert: &dummyCert{version: cert.Version1},
-		H:      &noise.HandshakeState{},
 	}
 	nc.hostMap.unlockedAddHostInfo(hostinfo, ifce)
 
@@ -215,7 +212,7 @@ func Test_NewConnectionManager_DisconnectInactive(t *testing.T) {
 		initiatingVersion: cert.Version1,
 		privateKey:        []byte{},
 		v1Cert:            &dummyCert{version: cert.Version1},
-		v1HandshakeBytes:  []byte{},
+		v1Credential:      nil,
 	}
 
 	lh := newTestLighthouse()
@@ -236,7 +233,7 @@ func Test_NewConnectionManager_DisconnectInactive(t *testing.T) {
 	conf.Settings["tunnels"] = map[string]any{
 		"drop_inactive": true,
 	}
-	punchy := NewPunchyFromConfig(test.NewLogger(), conf)
+	punchy := NewPunchyFromConfig(test.NewLogger(), conf, nil)
 	nc := newConnectionManagerFromConfig(test.NewLogger(), conf, hostMap, punchy)
 	assert.True(t, nc.dropInactive.Load())
 	nc.intf = ifce
@@ -249,7 +246,6 @@ func Test_NewConnectionManager_DisconnectInactive(t *testing.T) {
 	}
 	hostinfo.ConnectionState = &ConnectionState{
 		myCert: &dummyCert{version: cert.Version1},
-		H:      &noise.HandshakeState{},
 	}
 	nc.hostMap.unlockedAddHostInfo(hostinfo, ifce)
 
@@ -340,9 +336,9 @@ func Test_NewConnectionManagerTest_DisconnectInvalid(t *testing.T) {
 	cachedPeerCert, err := ncp.VerifyCertificate(now.Add(time.Second), peerCert)
 
 	cs := &CertState{
-		privateKey:       []byte{},
-		v1Cert:           &dummyCert{},
-		v1HandshakeBytes: []byte{},
+		privateKey:   []byte{},
+		v1Cert:       &dummyCert{},
+		v1Credential: nil,
 	}
 
 	lh := newTestLighthouse()
@@ -362,7 +358,7 @@ func Test_NewConnectionManagerTest_DisconnectInvalid(t *testing.T) {
 
 	// Create manager
 	conf := config.NewC(test.NewLogger())
-	punchy := NewPunchyFromConfig(test.NewLogger(), conf)
+	punchy := NewPunchyFromConfig(test.NewLogger(), conf, nil)
 	nc := newConnectionManagerFromConfig(test.NewLogger(), conf, hostMap, punchy)
 	nc.intf = ifce
 	ifce.connectionManager = nc
@@ -372,7 +368,6 @@ func Test_NewConnectionManagerTest_DisconnectInvalid(t *testing.T) {
 		ConnectionState: &ConnectionState{
 			myCert:   &dummyCert{},
 			peerCert: cachedPeerCert,
-			H:        &noise.HandshakeState{},
 		},
 	}
 	nc.hostMap.unlockedAddHostInfo(hostinfo, ifce)

connection_state.go

@@ -1,23 +1,20 @@
 package nebula
 
 import (
-	"crypto/rand"
 	"encoding/json"
-	"fmt"
 	"sync"
 	"sync/atomic"
 
-	"github.com/flynn/noise"
 	"github.com/slackhq/nebula/cert"
+	"github.com/slackhq/nebula/handshake"
 	"github.com/slackhq/nebula/noiseutil"
 )
 
 const ReplayWindow = 1024
 
 type ConnectionState struct {
-	eKey           *NebulaCipherState
-	dKey           *NebulaCipherState
-	H              *noise.HandshakeState
+	eKey           noiseutil.CipherState
+	dKey           noiseutil.CipherState
 	myCert         cert.Certificate
 	peerCert       *cert.CachedCertificate
 	initiator      bool
@@ -26,55 +23,24 @@ type ConnectionState struct {
 	writeLock      sync.Mutex
 }
 
-func NewConnectionState(cs *CertState, crt cert.Certificate, initiator bool, pattern noise.HandshakePattern) (*ConnectionState, error) {
-	var dhFunc noise.DHFunc
-	switch crt.Curve() {
-	case cert.Curve_CURVE25519:
-		dhFunc = noise.DH25519
-	case cert.Curve_P256:
-		if cs.pkcs11Backed {
-			dhFunc = noiseutil.DHP256PKCS11
-		} else {
-			dhFunc = noiseutil.DHP256
-		}
-	default:
-		return nil, fmt.Errorf("invalid curve: %s", crt.Curve())
-	}
-
-	var ncs noise.CipherSuite
-	if cs.cipher == "chachapoly" {
-		ncs = noise.NewCipherSuite(dhFunc, noise.CipherChaChaPoly, noise.HashSHA256)
-	} else {
-		ncs = noise.NewCipherSuite(dhFunc, noiseutil.CipherAESGCM, noise.HashSHA256)
-	}
-
-	static := noise.DHKey{Private: cs.privateKey, Public: crt.PublicKey()}
-	hs, err := noise.NewHandshakeState(noise.Config{
-		CipherSuite:   ncs,
-		Random:        rand.Reader,
-		Pattern:       pattern,
-		Initiator:     initiator,
-		StaticKeypair: static,
-		//NOTE: These should come from CertState (pki.go) when we finally implement it
-		PresharedKey:          []byte{},
-		PresharedKeyPlacement: 0,
-	})
-	if err != nil {
-		return nil, fmt.Errorf("NewConnectionState: %s", err)
-	}
-
-	// The queue and ready params prevent a counter race that would happen when
-	// sending stored packets and simultaneously accepting new traffic.
+// newConnectionStateFromResult builds a fully-populated ConnectionState from a
+// completed handshake.Result. It seeds messageCounter and the replay window so
+// that the post-handshake message indices already used on the wire don't count
+// as missed traffic in the data plane.
+func newConnectionStateFromResult(r *handshake.Result) *ConnectionState {
 	ci := &ConnectionState{
-		H:         hs,
-		initiator: initiator,
+		myCert:    r.MyCert,
+		initiator: r.Initiator,
+		peerCert:  r.RemoteCert,
+		eKey:      noiseutil.NewCipherState(r.EKey, r.Cipher),
+		dKey:      noiseutil.NewCipherState(r.DKey, r.Cipher),
 		window:    NewBits(ReplayWindow),
-		myCert:    crt,
 	}
-	// always start the counter from 2, as packet 1 and packet 2 are handshake packets.
-	ci.messageCounter.Add(2)
-
-	return ci, nil
+	ci.messageCounter.Add(r.MessageIndex)
+	for i := uint64(1); i <= r.MessageIndex; i++ {
+		ci.window.Update(nil, i)
+	}
+	return ci
 }
 
 func (cs *ConnectionState) MarshalJSON() ([]byte, error) {

connection_state_test.go

@@ -0,0 +1,114 @@
+package nebula
+
+import (
+	"net/netip"
+	"testing"
+	"time"
+
+	"github.com/flynn/noise"
+	"github.com/slackhq/nebula/cert"
+	ct "github.com/slackhq/nebula/cert_test"
+	"github.com/slackhq/nebula/handshake"
+	"github.com/slackhq/nebula/header"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// runTestHandshake runs a complete IX handshake between two freshly-built
+// peers and returns the initiator and responder Results. Used to produce
+// real cipher states for tests that need to exercise post-handshake glue.
+func runTestHandshake(t *testing.T) (initR, respR *handshake.Result) {
+	t.Helper()
+
+	ca, _, caKey, _ := ct.NewTestCaCert(
+		cert.Version2, cert.Curve_CURVE25519, time.Time{}, time.Time{}, nil, nil, nil,
+	)
+	caPool := ct.NewTestCAPool(ca)
+
+	makeCreds := func(name string, networks []netip.Prefix) handshake.GetCredentialFunc {
+		c, _, rawKey, _ := ct.NewTestCert(
+			cert.Version2, cert.Curve_CURVE25519, ca, caKey,
+			name, ca.NotBefore(), ca.NotAfter(), networks, nil, nil,
+		)
+		priv, _, _, err := cert.UnmarshalPrivateKeyFromPEM(rawKey)
+		require.NoError(t, err)
+		hsBytes, err := c.MarshalForHandshakes()
+		require.NoError(t, err)
+		ncs := noise.NewCipherSuite(noise.DH25519, noise.CipherChaChaPoly, noise.HashSHA256)
+		cred := handshake.NewCredential(c, hsBytes, priv, ncs)
+		return func(v cert.Version) *handshake.Credential {
+			if v == cert.Version2 {
+				return cred
+			}
+			return nil
+		}
+	}
+
+	verifier := func(c cert.Certificate) (*cert.CachedCertificate, error) {
+		return caPool.VerifyCertificate(time.Now(), c)
+	}
+
+	initCreds := makeCreds("initiator", []netip.Prefix{netip.MustParsePrefix("10.0.0.1/24")})
+	respCreds := makeCreds("responder", []netip.Prefix{netip.MustParsePrefix("10.0.0.2/24")})
+
+	initM, err := handshake.NewMachine(
+		cert.Version2, initCreds, verifier,
+		func() (uint32, error) { return 1000, nil },
+		true, header.HandshakeIXPSK0,
+	)
+	require.NoError(t, err)
+
+	respM, err := handshake.NewMachine(
+		cert.Version2, respCreds, verifier,
+		func() (uint32, error) { return 2000, nil },
+		false, header.HandshakeIXPSK0,
+	)
+	require.NoError(t, err)
+
+	msg1, err := initM.Initiate(nil)
+	require.NoError(t, err)
+
+	resp, respR, err := respM.ProcessPacket(nil, msg1)
+	require.NoError(t, err)
+	require.NotNil(t, respR)
+
+	_, initR, err = initM.ProcessPacket(nil, resp)
+	require.NoError(t, err)
+	require.NotNil(t, initR)
+
+	return initR, respR
+}
+
+func TestNewConnectionStateFromResult(t *testing.T) {
+	initR, respR := runTestHandshake(t)
+
+	t.Run("initiator", func(t *testing.T) {
+		ci := newConnectionStateFromResult(initR)
+		assert.True(t, ci.initiator)
+		assert.Equal(t, initR.MyCert, ci.myCert)
+		assert.Equal(t, initR.RemoteCert, ci.peerCert)
+		assert.NotNil(t, ci.eKey)
+		assert.NotNil(t, ci.dKey)
+
+		// IX has 2 handshake messages; the next data-plane send is counter=3.
+		assert.Equal(t, uint64(2), ci.messageCounter.Load(),
+			"messageCounter must equal Result.MessageIndex so the next send is N+1")
+
+		// Both handshake counters must be marked seen so they don't appear lost.
+		// Check returns false if an index has already been recorded.
+		assert.False(t, ci.window.Check(nil, 1), "counter 1 must already be seen")
+		assert.False(t, ci.window.Check(nil, 2), "counter 2 must already be seen")
+		// Counter 3 is the next data-plane message and must NOT be pre-marked.
+		assert.True(t, ci.window.Check(nil, 3), "counter 3 must not be pre-seeded")
+	})
+
+	t.Run("responder", func(t *testing.T) {
+		ci := newConnectionStateFromResult(respR)
+		assert.False(t, ci.initiator)
+		assert.Equal(t, respR.MyCert, ci.myCert)
+		assert.Equal(t, respR.RemoteCert, ci.peerCert)
+		assert.NotNil(t, ci.eKey)
+		assert.NotNil(t, ci.dKey)
+		assert.Equal(t, uint64(2), ci.messageCounter.Load())
+	})
+}

control_tester.go

@@ -5,8 +5,6 @@ package nebula
 import (
 	"net/netip"
 
-	"github.com/google/gopacket"
-	"github.com/google/gopacket/layers"
 	"github.com/slackhq/nebula/header"
 	"github.com/slackhq/nebula/overlay"
 	"github.com/slackhq/nebula/udp"
@@ -22,7 +20,9 @@ func (c *Control) WaitForType(msgType header.MessageType, subType header.Message
 			panic(err)
 		}
 		pipeTo.InjectUDPPacket(p)
-		if h.Type == msgType && h.Subtype == subType {
+		match := h.Type == msgType && h.Subtype == subType
+		p.Release()
+		if match {
 			return
 		}
 	}
@@ -38,7 +38,9 @@ func (c *Control) WaitForTypeByIndex(toIndex uint32, msgType header.MessageType,
 			panic(err)
 		}
 		pipeTo.InjectUDPPacket(p)
-		if h.RemoteIndex == toIndex && h.Type == msgType && h.Subtype == subType {
+		match := h.RemoteIndex == toIndex && h.Type == msgType && h.Subtype == subType
+		p.Release()
+		if match {
 			return
 		}
 	}
@@ -90,65 +92,15 @@ func (c *Control) GetTunTxChan() <-chan []byte {
 	return c.f.inside.(*overlay.TestTun).TxPackets
 }
 
-// InjectUDPPacket will inject a packet into the udp side of nebula
+// InjectUDPPacket injects a packet into the udp side. We copy internally so the caller keeps ownership of p.
+// The copy comes from the freelist so steady-state alloc is zero.
 func (c *Control) InjectUDPPacket(p *udp.Packet) {
-	c.f.outside.(*udp.TesterConn).Send(p)
+	c.f.outside.(*udp.TesterConn).Send(p.Copy())
 }
 
-// InjectTunUDPPacket puts a udp packet on the tun interface. Using UDP here because it's a simpler protocol
-func (c *Control) InjectTunUDPPacket(toAddr netip.Addr, toPort uint16, fromAddr netip.Addr, fromPort uint16, data []byte) {
-	serialize := make([]gopacket.SerializableLayer, 0)
-	var netLayer gopacket.NetworkLayer
-	if toAddr.Is6() {
-		if !fromAddr.Is6() {
-			panic("Cant send ipv6 to ipv4")
-		}
-		ip := &layers.IPv6{
-			Version:    6,
-			NextHeader: layers.IPProtocolUDP,
-			SrcIP:      fromAddr.Unmap().AsSlice(),
-			DstIP:      toAddr.Unmap().AsSlice(),
-		}
-		serialize = append(serialize, ip)
-		netLayer = ip
-	} else {
-		if !fromAddr.Is4() {
-			panic("Cant send ipv4 to ipv6")
-		}
-
-		ip := &layers.IPv4{
-			Version:  4,
-			TTL:      64,
-			Protocol: layers.IPProtocolUDP,
-			SrcIP:    fromAddr.Unmap().AsSlice(),
-			DstIP:    toAddr.Unmap().AsSlice(),
-		}
-		serialize = append(serialize, ip)
-		netLayer = ip
-	}
-
-	udp := layers.UDP{
-		SrcPort: layers.UDPPort(fromPort),
-		DstPort: layers.UDPPort(toPort),
-	}
-	err := udp.SetNetworkLayerForChecksum(netLayer)
-	if err != nil {
-		panic(err)
-	}
-
-	buffer := gopacket.NewSerializeBuffer()
-	opt := gopacket.SerializeOptions{
-		ComputeChecksums: true,
-		FixLengths:       true,
-	}
-
-	serialize = append(serialize, &udp, gopacket.Payload(data))
-	err = gopacket.SerializeLayers(buffer, opt, serialize...)
-	if err != nil {
-		panic(err)
-	}
-
-	c.f.inside.(*overlay.TestTun).Send(buffer.Bytes())
+// InjectTunPacket pushes an IP packet onto the tun interface.
+func (c *Control) InjectTunPacket(packet []byte) {
+	c.f.inside.(*overlay.TestTun).Send(packet)
 }
 
 func (c *Control) GetVpnAddrs() []netip.Addr {

e2e/handshake_manager_test.go

@@ -28,6 +28,7 @@ func makeHandshakePacket(from, to netip.AddrPort, subtype header.MessageSubType,
 }
 
 func TestHandshakeRetransmitDuplicate(t *testing.T) {
+	t.Parallel()
 	// Verify the responder correctly handles receiving the same msg1 multiple times
 	// (retransmission). The duplicate goes through CheckAndComplete -> ErrAlreadySeen
 	// and the cached response is resent.
@@ -46,7 +47,7 @@ func TestHandshakeRetransmitDuplicate(t *testing.T) {
 	defer r.RenderFlow()
 
 	t.Log("Trigger handshake from me to them")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi")))
 
 	t.Log("Grab my msg1")
 	msg1 := myControl.GetFromUDP(true)
@@ -78,6 +79,7 @@ func TestHandshakeRetransmitDuplicate(t *testing.T) {
 }
 
 func TestHandshakeTruncatedPacketRecovery(t *testing.T) {
+	t.Parallel()
 	// Verify that a truncated handshake packet is ignored and the real
 	// packet can still complete the handshake.
 
@@ -95,7 +97,7 @@ func TestHandshakeTruncatedPacketRecovery(t *testing.T) {
 	defer r.RenderFlow()
 
 	t.Log("Trigger handshake")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi")))
 
 	t.Log("Get msg1 and deliver to responder")
 	msg1 := myControl.GetFromUDP(true)
@@ -126,6 +128,7 @@ func TestHandshakeTruncatedPacketRecovery(t *testing.T) {
 }
 
 func TestHandshakeOrphanedMsg2Dropped(t *testing.T) {
+	t.Parallel()
 	// A msg2 arriving with no matching pending index should be silently dropped
 	// with no response sent and no state changes.
 
@@ -143,7 +146,7 @@ func TestHandshakeOrphanedMsg2Dropped(t *testing.T) {
 	defer r.RenderFlow()
 
 	t.Log("Complete a normal handshake")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi")))
 	r.RouteForAllUntilTxTun(theirControl)
 	assertTunnel(t, myVpnIpNet[0].Addr(), theirVpnIpNet[0].Addr(), myControl, theirControl, r)
 
@@ -168,6 +171,7 @@ func TestHandshakeOrphanedMsg2Dropped(t *testing.T) {
 }
 
 func TestHandshakeUnknownMessageCounter(t *testing.T) {
+	t.Parallel()
 	// A handshake packet with an unexpected message counter should be silently
 	// dropped with no side effects and no UDP response.
 
@@ -199,6 +203,7 @@ func TestHandshakeUnknownMessageCounter(t *testing.T) {
 }
 
 func TestHandshakeUnknownSubtype(t *testing.T) {
+	t.Parallel()
 	// A handshake packet with an unknown subtype should be silently dropped.
 
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
@@ -224,6 +229,7 @@ func TestHandshakeUnknownSubtype(t *testing.T) {
 }
 
 func TestHandshakeLateResponse(t *testing.T) {
+	t.Parallel()
 	// After a handshake times out, a late response should be silently ignored
 	// with no new tunnels created.
 
@@ -242,7 +248,7 @@ func TestHandshakeLateResponse(t *testing.T) {
 	theirControl.Start()
 
 	t.Log("Trigger handshake from me")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi")))
 
 	t.Log("Grab msg1 but don't deliver")
 	msg1 := myControl.GetFromUDP(true)
@@ -273,6 +279,7 @@ func TestHandshakeLateResponse(t *testing.T) {
 }
 
 func TestHandshakeSelfConnectionRejected(t *testing.T) {
+	t.Parallel()
 	// Verify that a node rejects a handshake containing its own VPN IP in the
 	// peer cert. We do this by sending the initiator's own msg1 back to itself.
 
@@ -285,7 +292,7 @@ func TestHandshakeSelfConnectionRejected(t *testing.T) {
 	myControl.Start()
 
 	t.Log("Trigger handshake from me")
-	myControl.InjectTunUDPPacket(netip.MustParseAddr("10.128.0.2"), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(netip.MustParseAddr("10.128.0.2"), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi")))
 	msg1 := myControl.GetFromUDP(true)
 
 	t.Log("Drain any handshake retransmits before injecting")
@@ -321,6 +328,7 @@ func TestHandshakeSelfConnectionRejected(t *testing.T) {
 }
 
 func TestHandshakeMessageCounter0Dropped(t *testing.T) {
+	t.Parallel()
 	// MessageCounter=0 is not a valid handshake message and should be dropped.
 
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
@@ -341,6 +349,7 @@ func TestHandshakeMessageCounter0Dropped(t *testing.T) {
 }
 
 func TestHandshakeRemoteAllowList(t *testing.T) {
+	t.Parallel()
 	// Verify that a handshake from a blocked underlay IP is dropped with no
 	// response and no state changes. Then verify the same packet from an
 	// allowed IP succeeds.
@@ -366,7 +375,7 @@ func TestHandshakeRemoteAllowList(t *testing.T) {
 	defer r.RenderFlow()
 
 	t.Log("Trigger handshake from them")
-	theirControl.InjectTunUDPPacket(myVpnIpNet[0].Addr(), 80, theirVpnIpNet[0].Addr(), 80, []byte("Hi"))
+	theirControl.InjectTunPacket(BuildTunUDPPacket(myVpnIpNet[0].Addr(), 80, theirVpnIpNet[0].Addr(), 80, []byte("Hi")))
 	msg1 := theirControl.GetFromUDP(true)
 
 	t.Log("Rewrite the source to a blocked IP and inject")
@@ -399,6 +408,7 @@ func TestHandshakeRemoteAllowList(t *testing.T) {
 }
 
 func TestHandshakeAlreadySeenPreferredRemote(t *testing.T) {
+	t.Parallel()
 	// When a duplicate msg1 arrives via ErrAlreadySeen, verify the tunnel
 	// remains functional and hostmap index count is stable.
 
@@ -416,7 +426,7 @@ func TestHandshakeAlreadySeenPreferredRemote(t *testing.T) {
 	defer r.RenderFlow()
 
 	t.Log("Complete a normal handshake via the router")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi")))
 	r.RouteForAllUntilTxTun(theirControl)
 	assertTunnel(t, myVpnIpNet[0].Addr(), theirVpnIpNet[0].Addr(), myControl, theirControl, r)
 
@@ -427,7 +437,7 @@ func TestHandshakeAlreadySeenPreferredRemote(t *testing.T) {
 	originalRemote := hi.CurrentRemote
 
 	t.Log("Re-trigger traffic to cause a new handshake attempt (ErrAlreadySeen)")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("roam"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("roam")))
 	r.RouteForAllUntilTxTun(theirControl)
 
 	t.Log("Verify tunnel still works")
@@ -445,6 +455,7 @@ func TestHandshakeAlreadySeenPreferredRemote(t *testing.T) {
 }
 
 func TestHandshakeWrongResponderPacketStore(t *testing.T) {
+	t.Parallel()
 	// Verify that when the wrong host responds, the cached packets are
 	// transferred to the new handshake, the evil tunnel is closed, evil's
 	// address is blocked, and the correct tunnel is eventually established.
@@ -464,8 +475,8 @@ func TestHandshakeWrongResponderPacketStore(t *testing.T) {
 	evilControl.Start()
 
 	t.Log("Send multiple packets to them (cached during handshake)")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("packet1"))
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("packet2"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("packet1")))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("packet2")))
 
 	t.Log("Route until evil tunnel is closed")
 	h := &header.H{}
@@ -508,6 +519,7 @@ func TestHandshakeWrongResponderPacketStore(t *testing.T) {
 }
 
 func TestHandshakeRelayComplete(t *testing.T) {
+	t.Parallel()
 	// Verify that a relay handshake completes correctly and relay state is
 	// properly maintained on all three nodes.
 
@@ -528,7 +540,7 @@ func TestHandshakeRelayComplete(t *testing.T) {
 	theirControl.Start()
 
 	t.Log("Trigger handshake via relay")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi via relay"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi via relay")))
 
 	p := r.RouteForAllUntilTxTun(theirControl)
 	assertUdpPacket(t, []byte("Hi via relay"), p, myVpnIpNet[0].Addr(), theirVpnIpNet[0].Addr(), 80, 80)
@@ -556,7 +568,7 @@ func TestHandshakeRelayComplete(t *testing.T) {
 }
 
 // NOTE: Relay V1 cert + IPv6 rejection is not tested here because
-// InjectTunUDPPacket from a V4 node to a V6 address panics in the test
+// BuildTunUDPPacket from a V4 node to a V6 address panics in the test
 // framework. The check is in handshake_manager.go handleOutbound relay
 // logic (lines ~304-313): if the relay host has a V1 cert and either
 // address is IPv6, the relay is skipped.

e2e/handshakes_test.go

@@ -16,6 +16,7 @@ import (
 	"github.com/slackhq/nebula/cert_test"
 	"github.com/slackhq/nebula/e2e/router"
 	"github.com/slackhq/nebula/header"
+	"github.com/slackhq/nebula/overlay"
 	"github.com/slackhq/nebula/udp"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -39,11 +40,22 @@ func BenchmarkHotPath(b *testing.B) {
 	r.CancelFlowLogs()
 
 	assertTunnel(b, myVpnIpNet[0].Addr(), theirVpnIpNet[0].Addr(), myControl, theirControl, r)
+
+	// Pre-build the IP packet bytes once so the bench measures the data plane,
+	// not gopacket SerializeLayers overhead.
+	prebuilt := BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me"))
+
+	// EnableFanIn switches the router to a 0-alloc routing path. Required
+	// for hot-path benchmarks; would conflict with GetFromUDP-using tests.
+	r.EnableFanIn()
+
 	b.ResetTimer()
 
 	for n := 0; n < b.N; n++ {
-		myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me"))
-		_ = r.RouteForAllUntilTxTun(theirControl)
+		myControl.InjectTunPacket(prebuilt)
+		// Release the TUN-side bytes back to the harness freelist; the bench
+		// just confirms a packet arrived, the contents aren't inspected.
+		overlay.ReleaseTunBuf(r.RouteForAllUntilTxTun(theirControl))
 	}
 
 	myControl.Stop()
@@ -71,11 +83,15 @@ func BenchmarkHotPathRelay(b *testing.B) {
 	theirControl.Start()
 
 	assertTunnel(b, theirVpnIpNet[0].Addr(), myVpnIpNet[0].Addr(), theirControl, myControl, r)
+
+	prebuilt := BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me"))
+	r.EnableFanIn()
+
 	b.ResetTimer()
 
 	for n := 0; n < b.N; n++ {
-		myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me"))
-		_ = r.RouteForAllUntilTxTun(theirControl)
+		myControl.InjectTunPacket(prebuilt)
+		overlay.ReleaseTunBuf(r.RouteForAllUntilTxTun(theirControl))
 	}
 
 	myControl.Stop()
@@ -84,6 +100,7 @@ func BenchmarkHotPathRelay(b *testing.B) {
 }
 
 func TestGoodHandshake(t *testing.T) {
+	t.Parallel()
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
 	myControl, myVpnIpNet, myUdpAddr, _ := newSimpleServer(cert.Version1, ca, caKey, "me", "10.128.0.1/24", nil)
 	theirControl, theirVpnIpNet, theirUdpAddr, _ := newSimpleServer(cert.Version1, ca, caKey, "them", "10.128.0.2/24", nil)
@@ -96,7 +113,7 @@ func TestGoodHandshake(t *testing.T) {
 	theirControl.Start()
 
 	t.Log("Send a udp packet through to begin standing up the tunnel, this should come out the other side")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me")))
 
 	t.Log("Have them consume my stage 0 packet. They have a tunnel now")
 	theirControl.InjectUDPPacket(myControl.GetFromUDP(true))
@@ -134,6 +151,7 @@ func TestGoodHandshake(t *testing.T) {
 }
 
 func TestGoodHandshakeNoOverlap(t *testing.T) {
+	t.Parallel()
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version2, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
 	myControl, myVpnIpNet, myUdpAddr, _ := newSimpleServer(cert.Version2, ca, caKey, "me", "10.128.0.1/24", nil)
 	theirControl, theirVpnIpNet, theirUdpAddr, _ := newSimpleServer(cert.Version2, ca, caKey, "them", "2001::69/24", nil) //look ma, cross-stack!
@@ -169,6 +187,7 @@ func TestGoodHandshakeNoOverlap(t *testing.T) {
 }
 
 func TestWrongResponderHandshake(t *testing.T) {
+	t.Parallel()
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
 
 	myControl, myVpnIpNet, myUdpAddr, _ := newSimpleServer(cert.Version1, ca, caKey, "me", "10.128.0.100/24", nil)
@@ -188,7 +207,7 @@ func TestWrongResponderHandshake(t *testing.T) {
 	evilControl.Start()
 
 	t.Log("Start the handshake process, we will route until we see the evil tunnel closed")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me")))
 
 	h := &header.H{}
 	r.RouteForAllExitFunc(func(p *udp.Packet, c *nebula.Control) router.ExitType {
@@ -245,6 +264,7 @@ func TestWrongResponderHandshake(t *testing.T) {
 }
 
 func TestWrongResponderHandshakeStaticHostMap(t *testing.T) {
+	t.Parallel()
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
 
 	theirControl, theirVpnIpNet, theirUdpAddr, _ := newSimpleServer(cert.Version1, ca, caKey, "them", "10.128.0.99/24", nil)
@@ -269,7 +289,7 @@ func TestWrongResponderHandshakeStaticHostMap(t *testing.T) {
 	evilControl.Start()
 
 	t.Log("Start the handshake process, we will route until we see the evil tunnel closed")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me")))
 
 	h := &header.H{}
 	r.RouteForAllExitFunc(func(p *udp.Packet, c *nebula.Control) router.ExitType {
@@ -327,6 +347,7 @@ func TestWrongResponderHandshakeStaticHostMap(t *testing.T) {
 }
 
 func TestStage1Race(t *testing.T) {
+	t.Parallel()
 	// This tests ensures that two hosts handshaking with each other at the same time will allow traffic to flow
 	// But will eventually collapse down to a single tunnel
 
@@ -347,8 +368,8 @@ func TestStage1Race(t *testing.T) {
 	theirControl.Start()
 
 	t.Log("Trigger a handshake to start on both me and them")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me"))
-	theirControl.InjectTunUDPPacket(myVpnIpNet[0].Addr(), 80, theirVpnIpNet[0].Addr(), 80, []byte("Hi from them"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me")))
+	theirControl.InjectTunPacket(BuildTunUDPPacket(myVpnIpNet[0].Addr(), 80, theirVpnIpNet[0].Addr(), 80, []byte("Hi from them")))
 
 	t.Log("Get both stage 1 handshake packets")
 	myHsForThem := myControl.GetFromUDP(true)
@@ -407,6 +428,7 @@ func TestStage1Race(t *testing.T) {
 }
 
 func TestUncleanShutdownRaceLoser(t *testing.T) {
+	t.Parallel()
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
 	myControl, myVpnIpNet, myUdpAddr, _ := newSimpleServer(cert.Version1, ca, caKey, "me  ", "10.128.0.1/24", nil)
 	theirControl, theirVpnIpNet, theirUdpAddr, _ := newSimpleServer(cert.Version1, ca, caKey, "them", "10.128.0.2/24", nil)
@@ -424,7 +446,7 @@ func TestUncleanShutdownRaceLoser(t *testing.T) {
 	theirControl.Start()
 
 	r.Log("Trigger a handshake from me to them")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me")))
 
 	p := r.RouteForAllUntilTxTun(theirControl)
 	assertUdpPacket(t, []byte("Hi from me"), p, myVpnIpNet[0].Addr(), theirVpnIpNet[0].Addr(), 80, 80)
@@ -435,7 +457,7 @@ func TestUncleanShutdownRaceLoser(t *testing.T) {
 	myHostmap.Indexes = map[uint32]*nebula.HostInfo{}
 	myHostmap.RemoteIndexes = map[uint32]*nebula.HostInfo{}
 
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me again"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me again")))
 	p = r.RouteForAllUntilTxTun(theirControl)
 	assertUdpPacket(t, []byte("Hi from me again"), p, myVpnIpNet[0].Addr(), theirVpnIpNet[0].Addr(), 80, 80)
 
@@ -456,6 +478,7 @@ func TestUncleanShutdownRaceLoser(t *testing.T) {
 }
 
 func TestUncleanShutdownRaceWinner(t *testing.T) {
+	t.Parallel()
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
 	myControl, myVpnIpNet, myUdpAddr, _ := newSimpleServer(cert.Version1, ca, caKey, "me  ", "10.128.0.1/24", nil)
 	theirControl, theirVpnIpNet, theirUdpAddr, _ := newSimpleServer(cert.Version1, ca, caKey, "them", "10.128.0.2/24", nil)
@@ -473,7 +496,7 @@ func TestUncleanShutdownRaceWinner(t *testing.T) {
 	theirControl.Start()
 
 	r.Log("Trigger a handshake from me to them")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me")))
 
 	p := r.RouteForAllUntilTxTun(theirControl)
 	assertUdpPacket(t, []byte("Hi from me"), p, myVpnIpNet[0].Addr(), theirVpnIpNet[0].Addr(), 80, 80)
@@ -485,7 +508,7 @@ func TestUncleanShutdownRaceWinner(t *testing.T) {
 	theirHostmap.Indexes = map[uint32]*nebula.HostInfo{}
 	theirHostmap.RemoteIndexes = map[uint32]*nebula.HostInfo{}
 
-	theirControl.InjectTunUDPPacket(myVpnIpNet[0].Addr(), 80, theirVpnIpNet[0].Addr(), 80, []byte("Hi from them again"))
+	theirControl.InjectTunPacket(BuildTunUDPPacket(myVpnIpNet[0].Addr(), 80, theirVpnIpNet[0].Addr(), 80, []byte("Hi from them again")))
 	p = r.RouteForAllUntilTxTun(myControl)
 	assertUdpPacket(t, []byte("Hi from them again"), p, theirVpnIpNet[0].Addr(), myVpnIpNet[0].Addr(), 80, 80)
 	r.RenderHostmaps("Derp hostmaps", myControl, theirControl)
@@ -507,6 +530,7 @@ func TestUncleanShutdownRaceWinner(t *testing.T) {
 }
 
 func TestRelays(t *testing.T) {
+	t.Parallel()
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
 	myControl, myVpnIpNet, _, _ := newSimpleServer(cert.Version1, ca, caKey, "me     ", "10.128.0.1/24", m{"relay": m{"use_relays": true}})
 	relayControl, relayVpnIpNet, relayUdpAddr, _ := newSimpleServer(cert.Version1, ca, caKey, "relay  ", "10.128.0.128/24", m{"relay": m{"am_relay": true}})
@@ -527,7 +551,7 @@ func TestRelays(t *testing.T) {
 	theirControl.Start()
 
 	t.Log("Trigger a handshake from me to them via the relay")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me")))
 
 	p := r.RouteForAllUntilTxTun(theirControl)
 	r.Log("Assert the tunnel works")
@@ -536,6 +560,7 @@ func TestRelays(t *testing.T) {
 }
 
 func TestRelaysDontCareAboutIps(t *testing.T) {
+	t.Parallel()
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version2, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
 	myControl, myVpnIpNet, _, _ := newSimpleServer(cert.Version2, ca, caKey, "me     ", "10.128.0.1/24", m{"relay": m{"use_relays": true}})
 	relayControl, relayVpnIpNet, relayUdpAddr, _ := newSimpleServer(cert.Version2, ca, caKey, "relay  ", "2001::9999/24", m{"relay": m{"am_relay": true}})
@@ -556,7 +581,7 @@ func TestRelaysDontCareAboutIps(t *testing.T) {
 	theirControl.Start()
 
 	t.Log("Trigger a handshake from me to them via the relay")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me")))
 
 	p := r.RouteForAllUntilTxTun(theirControl)
 	r.Log("Assert the tunnel works")
@@ -565,6 +590,7 @@ func TestRelaysDontCareAboutIps(t *testing.T) {
 }
 
 func TestReestablishRelays(t *testing.T) {
+	t.Parallel()
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
 	myControl, myVpnIpNet, _, _ := newSimpleServer(cert.Version1, ca, caKey, "me     ", "10.128.0.1/24", m{"relay": m{"use_relays": true}})
 	relayControl, relayVpnIpNet, relayUdpAddr, _ := newSimpleServer(cert.Version1, ca, caKey, "relay  ", "10.128.0.128/24", m{"relay": m{"am_relay": true}})
@@ -585,14 +611,14 @@ func TestReestablishRelays(t *testing.T) {
 	theirControl.Start()
 
 	t.Log("Trigger a handshake from me to them via the relay")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me")))
 
 	p := r.RouteForAllUntilTxTun(theirControl)
 	r.Log("Assert the tunnel works")
 	assertUdpPacket(t, []byte("Hi from me"), p, myVpnIpNet[0].Addr(), theirVpnIpNet[0].Addr(), 80, 80)
 
 	t.Log("Ensure packet traversal from them to me via the relay")
-	theirControl.InjectTunUDPPacket(myVpnIpNet[0].Addr(), 80, theirVpnIpNet[0].Addr(), 80, []byte("Hi from them"))
+	theirControl.InjectTunPacket(BuildTunUDPPacket(myVpnIpNet[0].Addr(), 80, theirVpnIpNet[0].Addr(), 80, []byte("Hi from them")))
 
 	p = r.RouteForAllUntilTxTun(myControl)
 	r.Log("Assert the tunnel works")
@@ -607,7 +633,7 @@ func TestReestablishRelays(t *testing.T) {
 	for curIndexes >= start {
 		curIndexes = len(myControl.GetHostmap().Indexes)
 		r.Logf("Wait for the dead index to go away:start=%v indexes, current=%v indexes", start, curIndexes)
-		myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me should fail"))
+		myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me should fail")))
 
 		r.RouteForAllExitFunc(func(p *udp.Packet, c *nebula.Control) router.ExitType {
 			return router.RouteAndExit
@@ -624,7 +650,7 @@ func TestReestablishRelays(t *testing.T) {
 		myControl.InjectLightHouseAddr(relayVpnIpNet[0].Addr(), relayUdpAddr)
 		myControl.InjectRelays(theirVpnIpNet[0].Addr(), []netip.Addr{relayVpnIpNet[0].Addr()})
 		relayControl.InjectLightHouseAddr(theirVpnIpNet[0].Addr(), theirUdpAddr)
-		myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me"))
+		myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me")))
 
 		p = r.RouteForAllUntilTxTun(theirControl)
 		r.Log("Assert the tunnel works")
@@ -659,7 +685,7 @@ func TestReestablishRelays(t *testing.T) {
 	t.Log("Assert the tunnel works the other way, too")
 	for {
 		t.Log("RouteForAllUntilTxTun")
-		theirControl.InjectTunUDPPacket(myVpnIpNet[0].Addr(), 80, theirVpnIpNet[0].Addr(), 80, []byte("Hi from them"))
+		theirControl.InjectTunPacket(BuildTunUDPPacket(myVpnIpNet[0].Addr(), 80, theirVpnIpNet[0].Addr(), 80, []byte("Hi from them")))
 
 		p = r.RouteForAllUntilTxTun(myControl)
 		r.Log("Assert the tunnel works")
@@ -696,6 +722,7 @@ func TestReestablishRelays(t *testing.T) {
 }
 
 func TestStage1RaceRelays(t *testing.T) {
+	t.Parallel()
 	//NOTE: this is a race between me and relay resulting in a full tunnel from me to them via relay
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
 	myControl, myVpnIpNet, myUdpAddr, _ := newSimpleServer(cert.Version1, ca, caKey, "me     ", "10.128.0.1/24", m{"relay": m{"use_relays": true}})
@@ -728,8 +755,8 @@ func TestStage1RaceRelays(t *testing.T) {
 	assertTunnel(t, theirVpnIpNet[0].Addr(), relayVpnIpNet[0].Addr(), theirControl, relayControl, r)
 
 	r.Log("Trigger a handshake from both them and me via relay to them and me")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me"))
-	theirControl.InjectTunUDPPacket(myVpnIpNet[0].Addr(), 80, theirVpnIpNet[0].Addr(), 80, []byte("Hi from them"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me")))
+	theirControl.InjectTunPacket(BuildTunUDPPacket(myVpnIpNet[0].Addr(), 80, theirVpnIpNet[0].Addr(), 80, []byte("Hi from them")))
 
 	r.Log("Wait for a packet from them to me")
 	p := r.RouteForAllUntilTxTun(myControl)
@@ -743,6 +770,7 @@ func TestStage1RaceRelays(t *testing.T) {
 }
 
 func TestStage1RaceRelays2(t *testing.T) {
+	t.Parallel()
 	//NOTE: this is a race between me and relay resulting in a full tunnel from me to them via relay
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
 	myControl, myVpnIpNet, myUdpAddr, _ := newSimpleServer(cert.Version1, ca, caKey, "me     ", "10.128.0.1/24", m{"relay": m{"use_relays": true}})
@@ -775,8 +803,8 @@ func TestStage1RaceRelays2(t *testing.T) {
 	assertTunnel(t, theirVpnIpNet[0].Addr(), relayVpnIpNet[0].Addr(), theirControl, relayControl, r)
 
 	r.Log("Trigger a handshake from both them and me via relay to them and me")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me"))
-	theirControl.InjectTunUDPPacket(myVpnIpNet[0].Addr(), 80, theirVpnIpNet[0].Addr(), 80, []byte("Hi from them"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me")))
+	theirControl.InjectTunPacket(BuildTunUDPPacket(myVpnIpNet[0].Addr(), 80, theirVpnIpNet[0].Addr(), 80, []byte("Hi from them")))
 
 	//r.RouteUntilAfterMsgType(myControl, header.Control, header.MessageNone)
 	//r.RouteUntilAfterMsgType(theirControl, header.Control, header.MessageNone)
@@ -819,6 +847,7 @@ func TestStage1RaceRelays2(t *testing.T) {
 }
 
 func TestRehandshakingRelays(t *testing.T) {
+	t.Parallel()
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
 	myControl, myVpnIpNet, _, _ := newSimpleServer(cert.Version1, ca, caKey, "me     ", "10.128.0.1/24", m{"relay": m{"use_relays": true}})
 	relayControl, relayVpnIpNet, relayUdpAddr, relayConfig := newSimpleServer(cert.Version1, ca, caKey, "relay  ", "10.128.0.128/24", m{"relay": m{"am_relay": true}})
@@ -839,7 +868,7 @@ func TestRehandshakingRelays(t *testing.T) {
 	theirControl.Start()
 
 	t.Log("Trigger a handshake from me to them via the relay")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me")))
 
 	p := r.RouteForAllUntilTxTun(theirControl)
 	r.Log("Assert the tunnel works")
@@ -922,6 +951,7 @@ func TestRehandshakingRelays(t *testing.T) {
 }
 
 func TestRehandshakingRelaysPrimary(t *testing.T) {
+	t.Parallel()
 	// This test is the same as TestRehandshakingRelays but one of the terminal types is a primary swap winner
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
 	myControl, myVpnIpNet, _, _ := newSimpleServer(cert.Version1, ca, caKey, "me     ", "10.128.0.128/24", m{"relay": m{"use_relays": true}})
@@ -943,7 +973,7 @@ func TestRehandshakingRelaysPrimary(t *testing.T) {
 	theirControl.Start()
 
 	t.Log("Trigger a handshake from me to them via the relay")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me")))
 
 	p := r.RouteForAllUntilTxTun(theirControl)
 	r.Log("Assert the tunnel works")
@@ -1026,6 +1056,7 @@ func TestRehandshakingRelaysPrimary(t *testing.T) {
 }
 
 func TestRehandshaking(t *testing.T) {
+	t.Parallel()
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
 	myControl, myVpnIpNet, myUdpAddr, myConfig := newSimpleServer(cert.Version1, ca, caKey, "me  ", "10.128.0.2/24", nil)
 	theirControl, theirVpnIpNet, theirUdpAddr, theirConfig := newSimpleServer(cert.Version1, ca, caKey, "them", "10.128.0.1/24", nil)
@@ -1121,6 +1152,7 @@ func TestRehandshaking(t *testing.T) {
 }
 
 func TestRehandshakingLoser(t *testing.T) {
+	t.Parallel()
 	// The purpose of this test is that the race loser renews their certificate and rehandshakes. The final tunnel
 	// Should be the one with the new certificate
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
@@ -1219,6 +1251,7 @@ func TestRehandshakingLoser(t *testing.T) {
 }
 
 func TestRaceRegression(t *testing.T) {
+	t.Parallel()
 	// This test forces stage 1, stage 2, stage 1 to be received by me from them
 	// We had a bug where we were not finding the duplicate handshake and responding to the final stage 1 which
 	// caused a cross-linked hostinfo
@@ -1242,8 +1275,8 @@ func TestRaceRegression(t *testing.T) {
 	//them rx stage:2 initiatorIndex=120607833 responderIndex=4209862089
 
 	t.Log("Start both handshakes")
-	myControl.InjectTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me"))
-	theirControl.InjectTunUDPPacket(myVpnIpNet[0].Addr(), 80, theirVpnIpNet[0].Addr(), 80, []byte("Hi from them"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnIpNet[0].Addr(), 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me")))
+	theirControl.InjectTunPacket(BuildTunUDPPacket(myVpnIpNet[0].Addr(), 80, theirVpnIpNet[0].Addr(), 80, []byte("Hi from them")))
 
 	t.Log("Get both stage 1")
 	myStage1ForThem := myControl.GetFromUDP(true)
@@ -1279,6 +1312,7 @@ func TestRaceRegression(t *testing.T) {
 }
 
 func TestV2NonPrimaryWithLighthouse(t *testing.T) {
+	t.Parallel()
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version2, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
 	lhControl, lhVpnIpNet, lhUdpAddr, _ := newSimpleServer(cert.Version2, ca, caKey, "lh  ", "10.128.0.1/24, ff::1/64", m{"lighthouse": m{"am_lighthouse": true}})
 
@@ -1319,6 +1353,7 @@ func TestV2NonPrimaryWithLighthouse(t *testing.T) {
 }
 
 func TestV2NonPrimaryWithOffNetLighthouse(t *testing.T) {
+	t.Parallel()
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version2, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
 	lhControl, lhVpnIpNet, lhUdpAddr, _ := newSimpleServer(cert.Version2, ca, caKey, "lh  ", "2001::1/64", m{"lighthouse": m{"am_lighthouse": true}})
 
@@ -1359,6 +1394,7 @@ func TestV2NonPrimaryWithOffNetLighthouse(t *testing.T) {
 }
 
 func TestLighthouseUpdateOnReload(t *testing.T) {
+	t.Parallel()
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version2, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
 
 	// Create the lighthouse
@@ -1434,6 +1470,7 @@ func TestLighthouseUpdateOnReload(t *testing.T) {
 }
 
 func TestGoodHandshakeUnsafeDest(t *testing.T) {
+	t.Parallel()
 	unsafePrefix := "192.168.6.0/24"
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version2, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
 	theirControl, theirVpnIpNet, theirUdpAddr, _ := newSimpleServerWithUdpAndUnsafeNetworks(cert.Version2, ca, caKey, "spooky", "10.128.0.2/24", netip.MustParseAddrPort("10.64.0.2:4242"), unsafePrefix, nil)
@@ -1455,7 +1492,7 @@ func TestGoodHandshakeUnsafeDest(t *testing.T) {
 	theirControl.Start()
 
 	t.Log("Send a udp packet through to begin standing up the tunnel, this should come out the other side")
-	myControl.InjectTunUDPPacket(spookyDest, 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(spookyDest, 80, myVpnIpNet[0].Addr(), 80, []byte("Hi from me")))
 
 	t.Log("Have them consume my stage 0 packet. They have a tunnel now")
 	theirControl.InjectUDPPacket(myControl.GetFromUDP(true))
@@ -1483,7 +1520,7 @@ func TestGoodHandshakeUnsafeDest(t *testing.T) {
 	assertUdpPacket(t, []byte("Hi from me"), myCachedPacket, myVpnIpNet[0].Addr(), spookyDest, 80, 80)
 
 	//reply
-	theirControl.InjectTunUDPPacket(myVpnIpNet[0].Addr(), 80, spookyDest, 80, []byte("Hi from the spookyman"))
+	theirControl.InjectTunPacket(BuildTunUDPPacket(myVpnIpNet[0].Addr(), 80, spookyDest, 80, []byte("Hi from the spookyman")))
 	//wait for reply
 	theirControl.WaitForType(1, 0, myControl)
 	theirCachedPacket := myControl.GetFromTun(true)

e2e/helpers_test.go

@@ -4,15 +4,13 @@
 package e2e
 
 import (
-	"io"
+	"log/slog"
 	"net/netip"
 	"os"
 	"strings"
 	"testing"
 	"time"
 
-	"log/slog"
-
 	"dario.cat/mergo"
 	"github.com/google/gopacket"
 	"github.com/google/gopacket/layers"
@@ -294,12 +292,12 @@ func deadline(t *testing.T, seconds time.Duration) doneCb {
 
 func assertTunnel(t testing.TB, vpnIpA, vpnIpB netip.Addr, controlA, controlB *nebula.Control, r *router.R) {
 	// Send a packet from them to me
-	controlB.InjectTunUDPPacket(vpnIpA, 80, vpnIpB, 90, []byte("Hi from B"))
+	controlB.InjectTunPacket(BuildTunUDPPacket(vpnIpA, 80, vpnIpB, 90, []byte("Hi from B")))
 	bPacket := r.RouteForAllUntilTxTun(controlA)
 	assertUdpPacket(t, []byte("Hi from B"), bPacket, vpnIpB, vpnIpA, 90, 80)
 
 	// And once more from me to them
-	controlA.InjectTunUDPPacket(vpnIpB, 80, vpnIpA, 90, []byte("Hello from A"))
+	controlA.InjectTunPacket(BuildTunUDPPacket(vpnIpB, 80, vpnIpA, 90, []byte("Hello from A")))
 	aPacket := r.RouteForAllUntilTxTun(controlB)
 	assertUdpPacket(t, []byte("Hello from A"), aPacket, vpnIpA, vpnIpB, 90, 80)
 }
@@ -382,7 +380,7 @@ func getAddrs(ns []netip.Prefix) []netip.Addr {
 func NewTestLogger() *slog.Logger {
 	v := os.Getenv("TEST_LOGS")
 	if v == "" {
-		return slog.New(slog.NewTextHandler(io.Discard, nil))
+		return slog.New(slog.DiscardHandler)
 	}
 
 	level := slog.LevelInfo
@@ -408,3 +406,58 @@ func testLogLevelName() string {
 	}
 	return "info"
 }
+
+// BuildTunUDPPacket assembles an IP+UDP packet suitable for Control.InjectTunPacket.
+// Using UDP here because it's a simpler protocol.
+func BuildTunUDPPacket(toAddr netip.Addr, toPort uint16, fromAddr netip.Addr, fromPort uint16, data []byte) []byte {
+	serialize := make([]gopacket.SerializableLayer, 0)
+	var netLayer gopacket.NetworkLayer
+	if toAddr.Is6() {
+		if !fromAddr.Is6() {
+			panic("Cant send ipv6 to ipv4")
+		}
+		ip := &layers.IPv6{
+			Version:    6,
+			NextHeader: layers.IPProtocolUDP,
+			SrcIP:      fromAddr.Unmap().AsSlice(),
+			DstIP:      toAddr.Unmap().AsSlice(),
+		}
+		serialize = append(serialize, ip)
+		netLayer = ip
+	} else {
+		if !fromAddr.Is4() {
+			panic("Cant send ipv4 to ipv6")
+		}
+
+		ip := &layers.IPv4{
+			Version:  4,
+			TTL:      64,
+			Protocol: layers.IPProtocolUDP,
+			SrcIP:    fromAddr.Unmap().AsSlice(),
+			DstIP:    toAddr.Unmap().AsSlice(),
+		}
+		serialize = append(serialize, ip)
+		netLayer = ip
+	}
+
+	udp := layers.UDP{
+		SrcPort: layers.UDPPort(fromPort),
+		DstPort: layers.UDPPort(toPort),
+	}
+	if err := udp.SetNetworkLayerForChecksum(netLayer); err != nil {
+		panic(err)
+	}
+
+	buffer := gopacket.NewSerializeBuffer()
+	opt := gopacket.SerializeOptions{
+		ComputeChecksums: true,
+		FixLengths:       true,
+	}
+
+	serialize = append(serialize, &udp, gopacket.Payload(data))
+	if err := gopacket.SerializeLayers(buffer, opt, serialize...); err != nil {
+		panic(err)
+	}
+
+	return buffer.Bytes()
+}

e2e/leak_test.go

@@ -0,0 +1,47 @@
+//go:build e2e_testing
+// +build e2e_testing
+
+package e2e
+
+import (
+	"testing"
+	"time"
+
+	"github.com/slackhq/nebula/cert"
+	"github.com/slackhq/nebula/cert_test"
+	"github.com/slackhq/nebula/e2e/router"
+	"go.uber.org/goleak"
+)
+
+// TestNoGoroutineLeaks brings up two nebula instances, completes a tunnel,
+// stops both, and asserts no goroutines leak past the shutdown. goleak's
+// retry mechanism gives the wg.Wait()-driven goroutines a moment to drain
+// before failing the assertion.
+//
+// Intentionally NOT t.Parallel()'d: concurrent tests would have their own
+// goroutines running and trip the assertion.
+func TestNoGoroutineLeaks(t *testing.T) {
+	defer goleak.VerifyNone(t)
+
+	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
+	myControl, myVpnIpNet, myUdpAddr, _ := newSimpleServer(cert.Version1, ca, caKey, "me", "10.128.0.1/24", nil)
+	theirControl, theirVpnIpNet, theirUdpAddr, _ := newSimpleServer(cert.Version1, ca, caKey, "them", "10.128.0.2/24", nil)
+
+	myControl.InjectLightHouseAddr(theirVpnIpNet[0].Addr(), theirUdpAddr)
+	theirControl.InjectLightHouseAddr(myVpnIpNet[0].Addr(), myUdpAddr)
+
+	myControl.Start()
+	theirControl.Start()
+
+	r := router.NewR(t, myControl, theirControl)
+	assertTunnel(t, myVpnIpNet[0].Addr(), theirVpnIpNet[0].Addr(), myControl, theirControl, r)
+
+	myControl.Stop()
+	theirControl.Stop()
+	r.RenderFlow()
+
+	// Settle period: Stop() is non-blocking; the wg-driven goroutines need
+	// a moment to drain. goleak retries internally too, but a short explicit
+	// settle reduces flakes when the suite is busy.
+	time.Sleep(50 * time.Millisecond)
+}

e2e/router/router.go

@@ -13,6 +13,7 @@ import (
 	"regexp"
 	"sort"
 	"sync"
+	"sync/atomic"
 	"testing"
 	"time"
 
@@ -24,6 +25,19 @@ import (
 	"golang.org/x/exp/maps"
 )
 
+// outNatKey is the (from, to) pair used by outNat. Comparable struct, so it works as a map key without the
+// allocation cost of a string-concat key.
+type outNatKey struct {
+	from, to netip.AddrPort
+}
+
+// fannedPacket pairs a UDP TX packet with its source control so the router can route it after popping from
+// the fan-in channel.
+type fannedPacket struct {
+	from *nebula.Control
+	pkt  *udp.Packet
+}
+
 type R struct {
 	// Simple map of the ip:port registered on a control to the control
 	// Basically a router, right?
@@ -34,12 +48,28 @@ type R struct {
 
 	// A last used map, if an inbound packet hit the inNat map then
 	// all return packets should use the same last used inbound address for the outbound sender
-	// map[from address + ":" + to address] => ip:port to rewrite in the udp packet to receiver
-	outNat map[string]netip.AddrPort
+	outNat map[outNatKey]netip.AddrPort
 
 	// A map of vpn ip to the nebula control it belongs to
 	vpnControls map[netip.Addr]*nebula.Control
 
+	// Cached select infrastructure for RouteForAllUntilTxTun.
+	// The controls map is immutable after NewR so the cases are good for the test lifetime.
+	// We only rebuild if a different receiver is asked.
+	selRecvCtl *nebula.Control
+	selCases   []reflect.SelectCase
+	selCtls    []*nebula.Control
+
+	// Optional fan-in mode for hot-path benchmarks: one forwarder goroutine per control drains UDP TX into udpFanIn,
+	// so RouteForAllUntilTxTun can do a fixed 2-way native select instead of paying reflect.Select per call.
+	// Off by default (would otherwise interleave with tests that use GetFromUDP directly on the same control).
+	// Enabled by EnableFanIn.
+	udpFanIn  chan fannedPacket
+	stopFanIn chan struct{}
+	fanInWG   sync.WaitGroup
+	fanInMu   sync.Mutex
+	fanInOn   atomic.Bool
+
 	ignoreFlows []ignoreFlow
 	flow        []flowEntry
 
@@ -119,7 +149,7 @@ func NewR(t testing.TB, controls ...*nebula.Control) *R {
 		controls:     make(map[netip.AddrPort]*nebula.Control),
 		vpnControls:  make(map[netip.Addr]*nebula.Control),
 		inNat:        make(map[netip.AddrPort]*nebula.Control),
-		outNat:       make(map[string]netip.AddrPort),
+		outNat:       make(map[outNatKey]netip.AddrPort),
 		flow:         []flowEntry{},
 		ignoreFlows:  []ignoreFlow{},
 		fn:           filepath.Join("mermaid", fmt.Sprintf("%s.md", t.Name())),
@@ -153,8 +183,10 @@ func NewR(t testing.TB, controls ...*nebula.Control) *R {
 			case <-ctx.Done():
 				return
 			case <-clockSource.C:
+				r.Lock()
 				r.renderHostmaps("clock tick")
 				r.renderFlow()
+				r.Unlock()
 			}
 		}
 	}()
@@ -180,15 +212,21 @@ func (r *R) AddRoute(ip netip.Addr, port uint16, c *nebula.Control) {
 // RenderFlow renders the packet flow seen up until now and stops further automatic renders from happening.
 func (r *R) RenderFlow() {
 	r.cancelRender()
+	r.Lock()
+	defer r.Unlock()
 	r.renderFlow()
 }
 
 // CancelFlowLogs stops flow logs from being tracked and destroys any logs already collected
 func (r *R) CancelFlowLogs() {
 	r.cancelRender()
+	r.Lock()
 	r.flow = nil
+	r.Unlock()
 }
 
+// renderFlow writes the flow log to disk. Caller must hold r.Lock. renderFlow reads r.flow / r.additionalGraphs and
+// the *packet pointers stashed inside, all of which are mutated under the same lock by routing paths.
 func (r *R) renderFlow() {
 	if r.flow == nil {
 		return
@@ -434,68 +472,157 @@ func (r *R) RouteUntilTxTun(sender *nebula.Control, receiver *nebula.Control) []
 				panic("No control for udp tx " + a.String())
 			}
 			fp := r.unlockedInjectFlow(sender, c, p, false)
-			c.InjectUDPPacket(p)
+			c.InjectUDPPacket(p) // copies internally; original is ours to release
 			fp.WasReceived()
 			r.Unlock()
+			p.Release()
 		}
 	}
 }
 
-// RouteForAllUntilTxTun will route for everyone and return when a packet is seen on receivers tun
-// If the router doesn't have the nebula controller for that address, we panic
+// RouteForAllUntilTxTun will route for everyone and return when a packet is seen on the receiver's tun.
+// If a control's UDP TX address can't be matched to a registered control, we panic.
+//
+// For allocation-sensitive callers (hot-path benchmarks, in particular relay
+// benches with 3+ controls), call EnableFanIn() first.
 func (r *R) RouteForAllUntilTxTun(receiver *nebula.Control) []byte {
+	if r.fanInOn.Load() {
+		return r.routeFanIn(receiver)
+	}
+	return r.routeReflect(receiver)
+}
+
+// routeFanIn is the alloc-free path used when EnableFanIn is in effect.
+func (r *R) routeFanIn(receiver *nebula.Control) []byte {
+	tunTx := receiver.GetTunTxChan()
+	for {
+		select {
+		case p := <-tunTx:
+			r.Lock()
+			if r.flow != nil {
+				np := udp.Packet{Data: make([]byte, len(p))}
+				copy(np.Data, p)
+				r.unlockedInjectFlow(receiver, receiver, &np, true)
+			}
+			r.Unlock()
+			return p
+		case fp := <-r.udpFanIn:
+			r.routeUDP(fp.from, fp.pkt)
+		}
+	}
+}
+
+// routeReflect is the default reflect.Select-based path. Pays the boxing allocation per call but doesn't interfere
+// with tests that pull packets directly from controls' UDP TX channels via GetFromUDP.
+func (r *R) routeReflect(receiver *nebula.Control) []byte {
+	sc, cm := r.selectCasesFor(receiver)
+	for {
+		x, rx, _ := reflect.Select(sc)
+		if x == 0 {
+			p := rx.Interface().([]byte)
+			r.Lock()
+			if r.flow != nil {
+				np := udp.Packet{Data: make([]byte, len(p))}
+				copy(np.Data, p)
+				r.unlockedInjectFlow(cm[x], cm[x], &np, true)
+			}
+			r.Unlock()
+			return p
+		}
+		r.routeUDP(cm[x], rx.Interface().(*udp.Packet))
+	}
+}
+
+// EnableFanIn switches RouteForAllUntilTxTun to the alloc-free fan-in path.
+// One forwarder goroutine per registered control drains UDP TX into a shared channel that RouteForAllUntilTxTun selects
+// on alongside the receiver's TUN TX channel.
+func (r *R) EnableFanIn() {
+	r.fanInMu.Lock()
+	defer r.fanInMu.Unlock()
+	if r.fanInOn.Load() {
+		return
+	}
+	r.udpFanIn = make(chan fannedPacket, 32)
+	r.stopFanIn = make(chan struct{})
+	for _, c := range r.controls {
+		r.startFanInWorker(c)
+	}
+	r.fanInOn.Store(true)
+	r.t.Cleanup(r.stopFanInWorkers)
+}
+
+// startFanInWorker spawns a goroutine that drains c's UDP TX into r.udpFanIn.
+func (r *R) startFanInWorker(c *nebula.Control) {
+	r.fanInWG.Add(1)
+	udpTx := c.GetUDPTxChan()
+	go func() {
+		defer r.fanInWG.Done()
+		for {
+			select {
+			case <-r.stopFanIn:
+				return
+			case p := <-udpTx:
+				select {
+				case <-r.stopFanIn:
+					p.Release()
+					return
+				case r.udpFanIn <- fannedPacket{from: c, pkt: p}:
+				}
+			}
+		}
+	}()
+}
+
+// stopFanInWorkers signals the fan-in goroutines to exit and waits for them.
+func (r *R) stopFanInWorkers() {
+	r.fanInMu.Lock()
+	wasOn := r.fanInOn.Swap(false)
+	r.fanInMu.Unlock()
+	if !wasOn {
+		return
+	}
+	close(r.stopFanIn)
+	r.fanInWG.Wait()
+}
+
+// routeUDP forwards a UDP TX packet from the named source control to the destination control derived from p.To,
+// releasing the source packet after InjectUDPPacket has copied its bytes into a fresh pool slot.
+func (r *R) routeUDP(from *nebula.Control, p *udp.Packet) {
+	r.Lock()
+	defer r.Unlock()
+	a := from.GetUDPAddr()
+	c := r.getControl(a, p.To, p)
+	if c == nil {
+		panic(fmt.Sprintf("No control for udp tx %s", p.To))
+	}
+	fp := r.unlockedInjectFlow(from, c, p, false)
+	c.InjectUDPPacket(p) // copies internally; original is ours to release
+	fp.WasReceived()
+	p.Release()
+}
+
+// selectCasesFor returns the SelectCase array used by routeReflect: one slot for the receiver's TUN TX channel followed
+// by one per control's UDP TX channel. Cached for the test lifetime, only rebuilt if the receiver changes.
+func (r *R) selectCasesFor(receiver *nebula.Control) ([]reflect.SelectCase, []*nebula.Control) {
+	r.Lock()
+	defer r.Unlock()
+	if r.selRecvCtl == receiver && r.selCases != nil {
+		return r.selCases, r.selCtls
+	}
 	sc := make([]reflect.SelectCase, len(r.controls)+1)
 	cm := make([]*nebula.Control, len(r.controls)+1)
-
-	i := 0
-	sc[i] = reflect.SelectCase{
-		Dir:  reflect.SelectRecv,
-		Chan: reflect.ValueOf(receiver.GetTunTxChan()),
-		Send: reflect.Value{},
-	}
-	cm[i] = receiver
-
-	i++
+	sc[0] = reflect.SelectCase{Dir: reflect.SelectRecv, Chan: reflect.ValueOf(receiver.GetTunTxChan())}
+	cm[0] = receiver
+	i := 1
 	for _, c := range r.controls {
-		sc[i] = reflect.SelectCase{
-			Dir:  reflect.SelectRecv,
-			Chan: reflect.ValueOf(c.GetUDPTxChan()),
-			Send: reflect.Value{},
-		}
-
+		sc[i] = reflect.SelectCase{Dir: reflect.SelectRecv, Chan: reflect.ValueOf(c.GetUDPTxChan())}
 		cm[i] = c
 		i++
 	}
-
-	for {
-		x, rx, _ := reflect.Select(sc)
-		r.Lock()
-
-		if x == 0 {
-			// we are the tun tx, we can exit
-			p := rx.Interface().([]byte)
-			np := udp.Packet{Data: make([]byte, len(p))}
-			copy(np.Data, p)
-
-			r.unlockedInjectFlow(cm[x], cm[x], &np, true)
-			r.Unlock()
-			return p
-
-		} else {
-			// we are a udp tx, route and continue
-			p := rx.Interface().(*udp.Packet)
-			a := cm[x].GetUDPAddr()
-			c := r.getControl(a, p.To, p)
-			if c == nil {
-				r.Unlock()
-				panic(fmt.Sprintf("No control for udp tx %s", p.To))
-			}
-			fp := r.unlockedInjectFlow(cm[x], c, p, false)
-			c.InjectUDPPacket(p)
-			fp.WasReceived()
-		}
-		r.Unlock()
-	}
+	r.selRecvCtl = receiver
+	r.selCases = sc
+	r.selCtls = cm
+	return sc, cm
 }
 
 // RouteExitFunc will call the whatDo func with each udp packet from sender.
@@ -522,6 +649,7 @@ func (r *R) RouteExitFunc(sender *nebula.Control, whatDo ExitFunc) {
 		switch e {
 		case ExitNow:
 			r.Unlock()
+			p.Release()
 			return
 
 		case RouteAndExit:
@@ -529,6 +657,7 @@ func (r *R) RouteExitFunc(sender *nebula.Control, whatDo ExitFunc) {
 			receiver.InjectUDPPacket(p)
 			fp.WasReceived()
 			r.Unlock()
+			p.Release()
 			return
 
 		case KeepRouting:
@@ -541,6 +670,7 @@ func (r *R) RouteExitFunc(sender *nebula.Control, whatDo ExitFunc) {
 		}
 
 		r.Unlock()
+		p.Release()
 	}
 }
 
@@ -641,6 +771,7 @@ func (r *R) RouteForAllExitFunc(whatDo ExitFunc) {
 		switch e {
 		case ExitNow:
 			r.Unlock()
+			p.Release()
 			return
 
 		case RouteAndExit:
@@ -648,6 +779,7 @@ func (r *R) RouteForAllExitFunc(whatDo ExitFunc) {
 			receiver.InjectUDPPacket(p)
 			fp.WasReceived()
 			r.Unlock()
+			p.Release()
 			return
 
 		case KeepRouting:
@@ -659,6 +791,7 @@ func (r *R) RouteForAllExitFunc(whatDo ExitFunc) {
 			panic(fmt.Sprintf("Unknown exitFunc return: %v", e))
 		}
 		r.Unlock()
+		p.Release()
 	}
 }
 
@@ -702,19 +835,20 @@ func (r *R) FlushAll() {
 		}
 		receiver.InjectUDPPacket(p)
 		r.Unlock()
+		p.Release()
 	}
 }
 
 // getControl performs or seeds NAT translation and returns the control for toAddr, p from fields may change
 // This is an internal router function, the caller must hold the lock
 func (r *R) getControl(fromAddr, toAddr netip.AddrPort, p *udp.Packet) *nebula.Control {
-	if newAddr, ok := r.outNat[fromAddr.String()+":"+toAddr.String()]; ok {
+	if newAddr, ok := r.outNat[outNatKey{from: fromAddr, to: toAddr}]; ok {
 		p.From = newAddr
 	}
 
 	c, ok := r.inNat[toAddr]
 	if ok {
-		r.outNat[c.GetUDPAddr().String()+":"+fromAddr.String()] = toAddr
+		r.outNat[outNatKey{from: c.GetUDPAddr(), to: fromAddr}] = toAddr
 		return c
 	}
 

e2e/sshd_test.go

@@ -0,0 +1,125 @@
+//go:build e2e_testing
+// +build e2e_testing
+
+package e2e
+
+import (
+	"crypto/ed25519"
+	"crypto/rand"
+	"encoding/pem"
+	"net"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/slackhq/nebula/cert"
+	"github.com/slackhq/nebula/cert_test"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"golang.org/x/crypto/ssh"
+)
+
+func TestSSHDLifecycle(t *testing.T) {
+	// TestSSHDLifecycle exercises the in-process sshd through several config reloads and a Control.Stop.
+	ca, _, caKey, _ := cert_test.NewTestCaCert(
+		cert.Version1, cert.Curve_CURVE25519,
+		time.Now(), time.Now().Add(10*time.Minute),
+		nil, nil, []string{},
+	)
+
+	hostKeyPEM := generateSSHHostKey(t)
+	clientSigner, clientAuthKey := generateSSHClientKey(t)
+	sshdAddr := allocLoopbackPort(t)
+
+	overrides := m{
+		"sshd": m{
+			"enabled":  true,
+			"listen":   sshdAddr,
+			"host_key": hostKeyPEM,
+			"authorized_users": []m{{
+				"user": "tester",
+				"keys": []string{clientAuthKey},
+			}},
+		},
+	}
+	control, _, _, _ := newSimpleServer(cert.Version1, ca, caKey, "sshd-test", "10.222.0.1/24", overrides)
+	control.Start()
+	t.Cleanup(func() { control.Stop() })
+
+	// sshd binds in a goroutine after Start returns; wait for it.
+	require.Eventually(t, func() bool { return canDial(sshdAddr) }, 2*time.Second, 25*time.Millisecond,
+		"sshd never started listening")
+
+	for i := 1; i <= 3; i++ {
+		out := sshExecReload(t, sshdAddr, clientSigner)
+		assert.Contains(t, out, "Reloading config", "reload cycle %d", i)
+		require.Eventually(t, func() bool { return canDial(sshdAddr) }, 2*time.Second, 25*time.Millisecond,
+			"sshd not listening after reload cycle %d", i)
+	}
+
+	control.Stop()
+	require.Eventually(t, func() bool { return !canDial(sshdAddr) }, 2*time.Second, 25*time.Millisecond,
+		"sshd still listening after Control.Stop")
+}
+
+func canDial(addr string) bool {
+	c, err := net.DialTimeout("tcp", addr, 100*time.Millisecond)
+	if err != nil {
+		return false
+	}
+	_ = c.Close()
+	return true
+}
+
+// allocLoopbackPort grabs an unused TCP port on 127.0.0.1, closes it, and returns the address. There
+// is a small race between releasing the port and the sshd reclaiming it; in practice the OS keeps the
+// port available long enough for the test to bind it.
+func allocLoopbackPort(t *testing.T) string {
+	t.Helper()
+	l, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+	addr := l.Addr().String()
+	require.NoError(t, l.Close())
+	return addr
+}
+
+func generateSSHHostKey(t *testing.T) string {
+	t.Helper()
+	_, priv, err := ed25519.GenerateKey(rand.Reader)
+	require.NoError(t, err)
+	block, err := ssh.MarshalPrivateKey(priv, "nebula-e2e-host")
+	require.NoError(t, err)
+	return string(pem.EncodeToMemory(block))
+}
+
+func generateSSHClientKey(t *testing.T) (ssh.Signer, string) {
+	t.Helper()
+	_, priv, err := ed25519.GenerateKey(rand.Reader)
+	require.NoError(t, err)
+	signer, err := ssh.NewSignerFromKey(priv)
+	require.NoError(t, err)
+	auth := strings.TrimSpace(string(ssh.MarshalAuthorizedKey(signer.PublicKey())))
+	return signer, auth
+}
+
+func sshExecReload(t *testing.T, addr string, signer ssh.Signer) string {
+	t.Helper()
+	cfg := &ssh.ClientConfig{
+		User:            "tester",
+		Auth:            []ssh.AuthMethod{ssh.PublicKeys(signer)},
+		HostKeyCallback: ssh.InsecureIgnoreHostKey(),
+		Timeout:         2 * time.Second,
+	}
+	client, err := ssh.Dial("tcp", addr, cfg)
+	require.NoError(t, err)
+	defer client.Close()
+
+	sess, err := client.NewSession()
+	require.NoError(t, err)
+	defer sess.Close()
+
+	// reload tears the channel down before sending exit-status, so Output returns an error on the
+	// channel close. The output buffer still has whatever the reload callback wrote before that.
+	out, _ := sess.Output("reload")
+	return string(out)
+}

e2e/tunnels_test.go

@@ -19,6 +19,7 @@ import (
 )
 
 func TestDropInactiveTunnels(t *testing.T) {
+	t.Parallel()
 	// The goal of this test is to ensure the shortest inactivity timeout will close the tunnel on both sides
 	// under ideal conditions
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
@@ -63,6 +64,7 @@ func TestDropInactiveTunnels(t *testing.T) {
 }
 
 func TestCertUpgrade(t *testing.T) {
+	t.Parallel()
 	// The goal of this test is to ensure the shortest inactivity timeout will close the tunnel on both sides
 	// under ideal conditions
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
@@ -157,6 +159,7 @@ func TestCertUpgrade(t *testing.T) {
 }
 
 func TestCertDowngrade(t *testing.T) {
+	t.Parallel()
 	// The goal of this test is to ensure the shortest inactivity timeout will close the tunnel on both sides
 	// under ideal conditions
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
@@ -255,6 +258,7 @@ func TestCertDowngrade(t *testing.T) {
 }
 
 func TestCertMismatchCorrection(t *testing.T) {
+	t.Parallel()
 	// The goal of this test is to ensure the shortest inactivity timeout will close the tunnel on both sides
 	// under ideal conditions
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
@@ -322,6 +326,7 @@ func TestCertMismatchCorrection(t *testing.T) {
 }
 
 func TestCrossStackRelaysWork(t *testing.T) {
+	t.Parallel()
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version2, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
 	myControl, myVpnIpNet, _, _ := newSimpleServer(cert.Version2, ca, caKey, "me     ", "10.128.0.1/24,fc00::1/64", m{"relay": m{"use_relays": true}})
 	relayControl, relayVpnIpNet, relayUdpAddr, _ := newSimpleServer(cert.Version2, ca, caKey, "relay  ", "10.128.0.128/24,fc00::128/64", m{"relay": m{"am_relay": true}})
@@ -350,14 +355,14 @@ func TestCrossStackRelaysWork(t *testing.T) {
 	theirControl.Start()
 
 	t.Log("Trigger a handshake from me to them via the relay")
-	myControl.InjectTunUDPPacket(theirVpnV6.Addr(), 80, myVpnV6.Addr(), 80, []byte("Hi from me"))
+	myControl.InjectTunPacket(BuildTunUDPPacket(theirVpnV6.Addr(), 80, myVpnV6.Addr(), 80, []byte("Hi from me")))
 
 	p := r.RouteForAllUntilTxTun(theirControl)
 	r.Log("Assert the tunnel works")
 	assertUdpPacket(t, []byte("Hi from me"), p, myVpnV6.Addr(), theirVpnV6.Addr(), 80, 80)
 
 	t.Log("reply?")
-	theirControl.InjectTunUDPPacket(myVpnV6.Addr(), 80, theirVpnV6.Addr(), 80, []byte("Hi from them"))
+	theirControl.InjectTunPacket(BuildTunUDPPacket(myVpnV6.Addr(), 80, theirVpnV6.Addr(), 80, []byte("Hi from them")))
 	p = r.RouteForAllUntilTxTun(myControl)
 	assertUdpPacket(t, []byte("Hi from them"), p, theirVpnV6.Addr(), myVpnV6.Addr(), 80, 80)
 
@@ -369,6 +374,7 @@ func TestCrossStackRelaysWork(t *testing.T) {
 }
 
 func TestCloseTunnelAuthenticated(t *testing.T) {
+	t.Parallel()
 	ca, _, caKey, _ := cert_test.NewTestCaCert(cert.Version1, cert.Curve_CURVE25519, time.Now(), time.Now().Add(10*time.Minute), nil, nil, []string{})
 	myControl, myVpnIpNet, myUdpAddr, _ := newSimpleServer(cert.Version1, ca, caKey, "me", "10.128.0.1/24", m{"tunnels": m{"drop_inactive": true, "inactivity_timeout": "5s"}})
 	theirControl, theirVpnIpNet, theirUdpAddr, _ := newSimpleServer(cert.Version1, ca, caKey, "them", "10.128.0.2/24", m{"tunnels": m{"drop_inactive": true, "inactivity_timeout": "10m"}})

examples/config.yml

@@ -138,6 +138,14 @@ listen:
   # max, net.core.rmem_max and net.core.wmem_max
   #read_buffer: 10485760
   #write_buffer: 10485760
+
+  # On Windows only
+  # When true, Nebula installs a WFP (Windows Filtering Platform) PERMIT filter scoped to UDP at the listener port.
+  # WFP sits below Windows Defender Firewall, so this lets peer handshakes reach Nebula's outside socket regardless
+  # of WDF's inbound rules.
+  # Default true; set to false to leave WDF in charge of inbound decisions on the listener port. Not reloadable.
+  #windows_bypass_wdf: true
+
   # By default, Nebula replies to packets it has no tunnel for with a "recv_error" packet. This packet helps speed up reconnection
   # in the case that Nebula on either side did not shut down cleanly. This response can be abused as a way to discover if Nebula is running
   # on a host though. This option lets you configure if you want to send "recv_error" packets always, never, or only to private network remotes.
@@ -163,17 +171,21 @@ listen:
 
 punchy:
   # Continues to punch inbound/outbound at a regular interval to avoid expiration of firewall nat mappings
+  # This setting is reloadable.
   punch: true
 
   # respond means that a node you are trying to reach will connect back out to you if your hole punching fails
   # this is extremely useful if one node is behind a difficult nat, such as a symmetric NAT
   # Default is false
+  # This setting is reloadable.
   #respond: true
 
   # delays a punch response for misbehaving NATs, default is 1 second.
+  # This setting is reloadable.
   #delay: 1s
 
   # set the delay before attempting punchy.respond. Default is 5 seconds. respond must be true to take effect.
+  # This setting is reloadable.
   #respond_delay: 5s
 
 # Cipher allows you to choose between the available ciphers for your network. Options are chachapoly or aes
@@ -282,6 +294,24 @@ tun:
     #  metric: 100
     #  install: true
 
+  # On Windows only, sets the network category of the nebula interface. Without this, Windows often
+  # leaves the network as "Unidentified" and treats it as Public, which makes the host firewall more
+  # restrictive than you usually want for an overlay between trusted peers. Valid values:
+  #   private             - treat the nebula network as a private/trusted network (default)
+  #   public              - treat it as a public/untrusted network
+  #   domain              - treat it as a domain-authenticated network
+  #   unset               - leave whatever Windows decided alone
+  # Not reloadable.
+  #network_category: private
+
+  # On Windows only
+  # When true, Nebula installs a WFP (Windows Filtering Platform) PERMIT filter scoped to the nebula adapter LUID.
+  # WFP sits below Windows Defender Firewall, so this lets inbound traffic through regardless of WDF rules.
+  # Filters are auto-removed when the adapter goes away.
+  # See listen.windows_bypass_wdf for the matching control over inbound to nebula's outside UDP listener.
+  # Default true; set to false to leave WDF in charge of inbound decisions on the nebula interface. Not reloadable.
+  #windows_bypass_wdf: true
+
   # On linux only, set to true to manage unsafe routes directly on the system route table with gateway routes instead of
   # in nebula configuration files. Default false, not reloadable.
   #use_system_route_table: false

firewall_test.go

@@ -1033,7 +1033,7 @@ func TestNewFirewallFromConfig(t *testing.T) {
 	l := test.NewLogger()
 	// Test a bad rule definition
 	c := &dummyCert{}
-	cs, err := newCertState(cert.Version2, nil, c, false, cert.Curve_CURVE25519, nil)
+	cs, err := newCertState(cert.Version2, nil, c, false, cert.Curve_CURVE25519, nil, "aes")
 	require.NoError(t, err)
 
 	conf := config.NewC(test.NewLogger())

go.mod

@@ -9,7 +9,7 @@ require (
 	github.com/armon/go-radix v1.0.0
 	github.com/cyberdelia/go-metrics-graphite v0.0.0-20161219230853-39f87cc3b432
 	github.com/flynn/noise v1.1.0
-	github.com/gaissmai/bart v0.26.0
+	github.com/gaissmai/bart v0.26.1
 	github.com/gogo/protobuf v1.3.2
 	github.com/google/gopacket v1.1.19
 	github.com/kardianos/service v1.2.4
@@ -22,10 +22,11 @@ require (
 	github.com/stefanberger/go-pkcs11uri v0.0.0-20230803200340-78284954bff6
 	github.com/stretchr/testify v1.11.1
 	github.com/vishvananda/netlink v1.3.1
+	go.uber.org/goleak v1.3.0
 	go.yaml.in/yaml/v3 v3.0.4
 	golang.org/x/crypto v0.50.0
 	golang.org/x/exp v0.0.0-20230725093048-515e97ebf090
-	golang.org/x/net v0.52.0
+	golang.org/x/net v0.53.0
 	golang.org/x/sync v0.20.0
 	golang.org/x/sys v0.43.0
 	golang.org/x/term v0.42.0

go.sum

@@ -26,8 +26,8 @@ github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/flynn/noise v1.1.0 h1:KjPQoQCEFdZDiP03phOvGi11+SVVhBG2wOWAorLsstg=
 github.com/flynn/noise v1.1.0/go.mod h1:xbMo+0i6+IGbYdJhF31t2eR1BIU0CYc12+BNAKwUTag=
-github.com/gaissmai/bart v0.26.0 h1:xOZ57E9hJLBiQaSyeZa9wgWhGuzfGACgqp4BE77OkO0=
-github.com/gaissmai/bart v0.26.0/go.mod h1:GREWQfTLRWz/c5FTOsIw+KkscuFkIV5t8Rp7Nd1Td5c=
+github.com/gaissmai/bart v0.26.1 h1:+w4rnLGNlA2GDVn382Tfe3jOsK5vOr5n4KmigJ9lbTo=
+github.com/gaissmai/bart v0.26.1/go.mod h1:GREWQfTLRWz/c5FTOsIw+KkscuFkIV5t8Rp7Nd1Td5c=
 github.com/go-kit/kit v0.8.0/go.mod h1:xBxKIO96dXMWWy0MnWVtmwkA9/13aqxPnvrjFYMA2as=
 github.com/go-kit/kit v0.9.0/go.mod h1:xBxKIO96dXMWWy0MnWVtmwkA9/13aqxPnvrjFYMA2as=
 github.com/go-kit/log v0.1.0/go.mod h1:zbhenjAZHb184qTLMA9ZjW7ThYL0H2mk7Q6pNt4vbaY=
@@ -182,8 +182,8 @@ golang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLL
 golang.org/x/net v0.0.0-20200625001655-4c5254603344/go.mod h1:/O7V0waA8r7cgGh81Ro3o1hOxt32SMVPicZroKQ2sZA=
 golang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
-golang.org/x/net v0.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0=
-golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw=
+golang.org/x/net v0.53.0 h1:d+qAbo5L0orcWAr0a9JweQpjXF19LMXJE8Ey7hwOdUA=
+golang.org/x/net v0.53.0/go.mod h1:JvMuJH7rrdiCfbeHoo3fCQU24Lf5JJwT9W3sJFulfgs=
 golang.org/x/oauth2 v0.0.0-20190226205417-e64efc72b421/go.mod h1:gOpvHmFTYa4IltrdGE7lF6nIHvwfUNPOp7c8zoXwtLw=
 golang.org/x/sync v0.0.0-20181108010431-42b317875d0f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20181221193216-37e7f081c4d4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=

handshake/credential.go

@@ -0,0 +1,57 @@
+package handshake
+
+import (
+	"crypto/rand"
+
+	"github.com/flynn/noise"
+	"github.com/slackhq/nebula/cert"
+)
+
+// Credential holds everything needed to participate in a handshake
+// at a given cert version. Version and Curve are read from Cert; the public
+// half of the static keypair likewise comes from Cert.PublicKey().
+type Credential struct {
+	Cert        cert.Certificate  // the certificate
+	Bytes       []byte            // pre-marshaled certificate bytes
+	privateKey  []byte            // static private key (public half lives in Cert)
+	cipherSuite noise.CipherSuite // pre-built cipher suite (DH + cipher + hash)
+}
+
+// NewCredential creates a Credential with all material needed for handshake
+// participation. The cipherSuite should be pre-built by the caller with the
+// appropriate DH function, cipher, and hash.
+func NewCredential(
+	c cert.Certificate,
+	hsBytes []byte,
+	privateKey []byte,
+	cipherSuite noise.CipherSuite,
+) *Credential {
+	return &Credential{
+		Cert:        c,
+		Bytes:       hsBytes,
+		privateKey:  privateKey,
+		cipherSuite: cipherSuite,
+	}
+}
+
+// buildHandshakeState creates a noise.HandshakeState from this credential.
+func (hc *Credential) buildHandshakeState(initiator bool, pattern noise.HandshakePattern) (*noise.HandshakeState, error) {
+	return noise.NewHandshakeState(noise.Config{
+		CipherSuite:           hc.cipherSuite,
+		Random:                rand.Reader,
+		Pattern:               pattern,
+		Initiator:             initiator,
+		StaticKeypair:         noise.DHKey{Private: hc.privateKey, Public: hc.Cert.PublicKey()},
+		PresharedKey:          []byte{},
+		PresharedKeyPlacement: 0,
+	})
+}
+
+// GetCredentialFunc returns the handshake credential for the given version,
+// or nil if that version is not available.
+//
+// Implementations must return credentials drawn from a snapshot stable for
+// the lifetime of any single Machine. The Machine may call this multiple
+// times during a handshake (e.g. when negotiating to the peer's version)
+// and assumes the underlying static keypair is consistent across calls.
+type GetCredentialFunc func(v cert.Version) *Credential

handshake/errors.go

@@ -0,0 +1,21 @@
+package handshake
+
+import "errors"
+
+var (
+	ErrInitiateOnResponder     = errors.New("initiate called on responder")
+	ErrInitiateAlreadyCalled   = errors.New("initiate already called")
+	ErrInitiateNotCalled       = errors.New("initiate must be called before ProcessPacket for initiators")
+	ErrPacketTooShort          = errors.New("packet too short")
+	ErrPublicKeyMismatch       = errors.New("public key mismatch between certificate and handshake")
+	ErrIncompleteHandshake     = errors.New("handshake completed without receiving required content")
+	ErrMachineFailed           = errors.New("handshake machine has failed")
+	ErrUnknownSubtype          = errors.New("unknown handshake subtype")
+	ErrMissingContent          = errors.New("expected handshake content but message was empty")
+	ErrUnexpectedContent       = errors.New("received unexpected handshake content")
+	ErrIndexAllocation         = errors.New("failed to allocate local index")
+	ErrNoCredential            = errors.New("no handshake credential available for cert version")
+	ErrAsymmetricCipherKeys    = errors.New("noise produced only one cipher key")
+	ErrMultiMessageUnsupported = errors.New("multi-message handshake patterns are not yet supported by the manager")
+	ErrSubtypeMismatch         = errors.New("packet subtype does not match handshake machine subtype")
+)

handshake/handshake.proto

@@ -0,0 +1,29 @@
+// This file documents the wire format the nebula handshake speaks. It is
+// not run through protoc; the encoder/decoder in payload.go is hand-written
+// against this shape directly to keep the parser narrow and panic-free.
+//
+// Any change to the wire format must be reflected here, and adding a new
+// field requires updating MarshalPayload / unmarshalPayloadDetails together
+// with the field-uniqueness and wire-type checks in those functions.
+
+syntax = "proto3";
+package nebula.handshake;
+
+message NebulaHandshake {
+  NebulaHandshakeDetails Details = 1;
+  bytes Hmac = 2;
+}
+
+message NebulaHandshakeDetails {
+  bytes Cert = 1;
+  uint32 InitiatorIndex = 2;
+  uint32 ResponderIndex = 3;
+  // Cookie was reserved for an anti-DoS mechanism that was never
+  // implemented. No released version of nebula has ever populated it; the
+  // hand-written parser silently skips it on read.
+  uint64 Cookie = 4 [deprecated = true];
+  uint64 Time = 5;
+  uint32 CertVersion = 8;
+  // reserved for WIP multiport
+  reserved 6, 7;
+}

handshake/helpers_test.go

@@ -0,0 +1,116 @@
+package handshake
+
+import (
+	"net/netip"
+	"testing"
+	"time"
+
+	"github.com/flynn/noise"
+	"github.com/slackhq/nebula/cert"
+	ct "github.com/slackhq/nebula/cert_test"
+	"github.com/slackhq/nebula/header"
+	"github.com/stretchr/testify/require"
+)
+
+// testCertState holds cert material for a test peer.
+type testCertState struct {
+	version cert.Version
+	creds   map[cert.Version]*Credential
+}
+
+func (s *testCertState) getCredential(v cert.Version) *Credential {
+	return s.creds[v]
+}
+
+func newTestCertState(
+	t *testing.T, ca cert.Certificate, caKey []byte, name string, networks []netip.Prefix,
+) *testCertState {
+	return newTestCertStateWithCipher(t, ca, caKey, name, networks, noise.CipherChaChaPoly)
+}
+
+func newTestCertStateWithCipher(
+	t *testing.T, ca cert.Certificate, caKey []byte, name string, networks []netip.Prefix,
+	cipher noise.CipherFunc,
+) *testCertState {
+	t.Helper()
+	c, _, rawPrivKey, _ := ct.NewTestCert(
+		cert.Version2, cert.Curve_CURVE25519, ca, caKey,
+		name, ca.NotBefore(), ca.NotAfter(), networks, nil, nil,
+	)
+
+	priv, _, _, err := cert.UnmarshalPrivateKeyFromPEM(rawPrivKey)
+	require.NoError(t, err)
+
+	hsBytes, err := c.MarshalForHandshakes()
+	require.NoError(t, err)
+
+	ncs := noise.NewCipherSuite(noise.DH25519, cipher, noise.HashSHA256)
+	return &testCertState{
+		version: cert.Version2,
+		creds: map[cert.Version]*Credential{
+			cert.Version2: NewCredential(c, hsBytes, priv, ncs),
+		},
+	}
+}
+
+func testVerifier(pool *cert.CAPool) CertVerifier {
+	return func(c cert.Certificate) (*cert.CachedCertificate, error) {
+		return pool.VerifyCertificate(time.Now(), c)
+	}
+}
+
+func newTestMachine(
+	t *testing.T,
+	cs *testCertState,
+	verifier CertVerifier,
+	initiator bool,
+	localIndex uint32,
+) *Machine {
+	t.Helper()
+	m, err := NewMachine(
+		cs.version, cs.getCredential,
+		verifier, func() (uint32, error) { return localIndex, nil },
+		initiator, header.HandshakeIXPSK0,
+	)
+	require.NoError(t, err)
+	return m
+}
+
+func initiateHandshake(
+	t *testing.T,
+	initCS *testCertState, initVerifier CertVerifier,
+	respCS *testCertState, respVerifier CertVerifier,
+) (initM, respM *Machine, respResult *Result, resp []byte, err error) {
+	t.Helper()
+	initM = newTestMachine(t, initCS, initVerifier, true, 100)
+	msg1, merr := initM.Initiate(nil)
+	require.NoError(t, merr)
+
+	respM = newTestMachine(t, respCS, respVerifier, false, 200)
+	resp, respResult, err = respM.ProcessPacket(nil, msg1)
+	return
+}
+
+func doFullHandshake(
+	t *testing.T, initCS, respCS *testCertState, caPool *cert.CAPool,
+) (initResult, respResult *Result) {
+	t.Helper()
+	v := testVerifier(caPool)
+
+	initM := newTestMachine(t, initCS, v, true, 1000)
+	respM := newTestMachine(t, respCS, v, false, 2000)
+
+	msg1, err := initM.Initiate(nil)
+	require.NoError(t, err)
+
+	resp, respResult, err := respM.ProcessPacket(nil, msg1)
+	require.NoError(t, err)
+	require.NotNil(t, respResult)
+	require.NotEmpty(t, resp)
+
+	_, initResult, err = initM.ProcessPacket(nil, resp)
+	require.NoError(t, err)
+	require.NotNil(t, initResult)
+
+	return initResult, respResult
+}

handshake/machine.go

@@ -0,0 +1,446 @@
+package handshake
+
+import (
+	"bytes"
+	"fmt"
+	"slices"
+	"time"
+
+	"github.com/flynn/noise"
+	"github.com/slackhq/nebula/cert"
+	"github.com/slackhq/nebula/header"
+)
+
+// IndexAllocator is called by the Machine to allocate a local index for the
+// handshake. It is called at most once, when the first outgoing message that
+// carries a payload is built.
+//
+// Implementations MUST NOT return 0. Zero is reserved as a sentinel meaning
+// "no index assigned" on the wire and in the payload-presence checks. If an
+// allocator ever returned 0, a legitimate handshake's payload could be
+// indistinguishable from an empty one and would be rejected.
+type IndexAllocator func() (uint32, error)
+
+// CertVerifier is called by the Machine after reconstructing the peer's
+// certificate from the handshake. The verifier performs all validation
+// (CA trust, expiry, policy checks, allow lists).
+type CertVerifier func(cert.Certificate) (*cert.CachedCertificate, error)
+
+// Result contains the results of a successful handshake.
+// Returned by ProcessPacket when the handshake is complete.
+type Result struct {
+	EKey          *noise.CipherState
+	DKey          *noise.CipherState
+	Cipher        noise.CipherFunc // identifies which post-handshake CipherState the data plane should wrap EKey/DKey in
+	MyCert        cert.Certificate
+	RemoteCert    *cert.CachedCertificate
+	RemoteIndex   uint32
+	LocalIndex    uint32
+	HandshakeTime uint64
+	MessageIndex  uint64 // number of messages exchanged during the handshake
+	Initiator     bool
+}
+
+// Machine drives a Noise handshake through N messages. It handles Noise
+// protocol operations, certificate reconstruction, and payload encoding.
+// Certificate validation is delegated to the caller via CertVerifier.
+//
+// A Machine is not safe for concurrent use. The caller must ensure that
+// Initiate and ProcessPacket are not called concurrently.
+//
+// Error contract: when ProcessPacket or Initiate returns an error, callers
+// must check Failed() to decide what to do next. If Failed() is false the
+// underlying noise state was not advanced (the packet was rejected before
+// ReadMessage took effect, or the rejection is non-fatal like a stale
+// retransmit) and the Machine can accept another packet. If Failed() is
+// true the Machine is unrecoverable and the caller must abandon it.
+type Machine struct {
+	hs             *noise.HandshakeState
+	getCred        GetCredentialFunc
+	allocIndex     IndexAllocator
+	verifier       CertVerifier
+	result         *Result
+	msgs           []msgFlags
+	myVersion      cert.Version
+	subtype        header.MessageSubType
+	indexAllocated bool
+	remoteCertSet  bool
+	payloadSet     bool
+	failed         bool
+}
+
+// NewMachine creates a handshake state machine. The subtype determines both
+// the noise pattern and the per-message content layout. The credential for
+// `version` is fetched via getCred and used to seed the noise.HandshakeState.
+// IndexAllocator is called lazily when the first outgoing payload is built.
+func NewMachine(
+	version cert.Version,
+	getCred GetCredentialFunc,
+	verifier CertVerifier,
+	allocIndex IndexAllocator,
+	initiator bool,
+	subtype header.MessageSubType,
+) (*Machine, error) {
+	info, err := subtypeInfoFor(subtype)
+	if err != nil {
+		return nil, err
+	}
+
+	cred := getCred(version)
+	if cred == nil {
+		return nil, fmt.Errorf("%w: %v", ErrNoCredential, version)
+	}
+
+	hs, err := cred.buildHandshakeState(initiator, info.pattern)
+	if err != nil {
+		return nil, fmt.Errorf("build noise state: %w", err)
+	}
+
+	return &Machine{
+		hs:         hs,
+		subtype:    subtype,
+		msgs:       info.msgs,
+		getCred:    getCred,
+		allocIndex: allocIndex,
+		verifier:   verifier,
+		myVersion:  version,
+		result: &Result{
+			Initiator: initiator,
+			Cipher:    cred.cipherSuite,
+		},
+	}, nil
+}
+
+// Failed returns true if the Machine is in an unrecoverable state.
+func (m *Machine) Failed() bool {
+	return m.failed
+}
+
+// Subtype returns the handshake subtype this Machine was built for.
+func (m *Machine) Subtype() header.MessageSubType {
+	return m.subtype
+}
+
+// MessageIndex returns the noise handshake message index, which equals the
+// wire counter of the most recently sent or received message.
+func (m *Machine) MessageIndex() int {
+	return m.hs.MessageIndex()
+}
+
+// requireComplete checks that both a peer cert and payload have been received.
+// Marks the machine as failed if not.
+func (m *Machine) requireComplete() error {
+	if !m.payloadSet || !m.remoteCertSet {
+		m.failed = true
+		return ErrIncompleteHandshake
+	}
+	return nil
+}
+
+// myMsgFlags returns the flags for the current outgoing message.
+func (m *Machine) myMsgFlags() msgFlags {
+	idx := m.hs.MessageIndex()
+	if idx < len(m.msgs) {
+		return m.msgs[idx]
+	}
+	return msgFlags{}
+}
+
+// peerMsgFlags returns the flags for the message we just read.
+func (m *Machine) peerMsgFlags() msgFlags {
+	idx := m.hs.MessageIndex() - 1
+	if idx >= 0 && idx < len(m.msgs) {
+		return m.msgs[idx]
+	}
+	return msgFlags{}
+}
+
+// Initiate produces the first handshake message. Only valid for initiators,
+// and must be called exactly once before ProcessPacket.
+//
+// out is a destination buffer the message is appended to and returned. Pass
+// nil to allocate fresh, or pass a re-used buffer sliced to length 0 (e.g.
+// buf[:0]) with sufficient capacity to avoid allocation.
+//
+// An error return may not indicate a fatal condition, check Failed() to
+// determine if the Machine can still be used.
+func (m *Machine) Initiate(out []byte) ([]byte, error) {
+	if m.failed {
+		return nil, ErrMachineFailed
+	}
+	if !m.result.Initiator {
+		m.failed = true
+		return nil, ErrInitiateOnResponder
+	}
+	if m.hs.MessageIndex() != 0 {
+		m.failed = true
+		return nil, ErrInitiateAlreadyCalled
+	}
+
+	// At MessageIndex=0 with RemoteIndex still zero, buildResponse produces
+	// header counter 1 and remote index 0, which is what the initial message needs.
+	out, _, _, err := m.buildResponse(out)
+	if err != nil {
+		m.failed = true
+		return nil, err
+	}
+	return out, nil
+}
+
+// ProcessPacket handles an incoming handshake message. It advances the Noise
+// state, validates the peer certificate via the verifier, and optionally
+// produces a response.
+//
+// out is a destination buffer the response is appended to and returned. Pass
+// nil to allocate fresh, or pass a re-used buffer sliced to length 0 (e.g.
+// buf[:0]) with sufficient capacity to avoid allocation. The returned slice
+// is nil when no outgoing message is produced (handshake complete on this
+// side, or final message of a multi-message pattern).
+//
+// Returns a non-nil Result when the handshake is complete.
+// An error return may not indicate a fatal condition, check Failed() to
+// determine if the Machine can still be used.
+func (m *Machine) ProcessPacket(out, packet []byte) ([]byte, *Result, error) {
+	if m.failed {
+		return nil, nil, ErrMachineFailed
+	}
+	if len(packet) < header.Len {
+		return nil, nil, ErrPacketTooShort
+	}
+	// Reject packets whose subtype doesn't match the one this Machine was
+	// built for. A pending handshake that suddenly receives a different
+	// subtype on its index is either a stray packet that matched by chance
+	// or a peer protocol violation; drop it without failing the Machine so
+	// the legitimate retransmit can still complete.
+	if header.MessageSubType(packet[1]) != m.subtype {
+		return nil, nil, ErrSubtypeMismatch
+	}
+	if m.result.Initiator && m.hs.MessageIndex() == 0 {
+		m.failed = true
+		return nil, nil, ErrInitiateNotCalled
+	}
+
+	// The (eKey, dKey) ordering here is correct for IX, where the initiator
+	// completes the handshake by reading the responder's stage-2 message.
+	// noise returns (cs1, cs2) where cs1 is the initiator->responder cipher.
+	// For 3-message patterns where a responder finishes by reading the final
+	// message, this ordering would be wrong; revisit when XX/pqIX lands.
+	msg, eKey, dKey, err := m.hs.ReadMessage(nil, packet[header.Len:])
+	if err != nil {
+		// Noise ReadMessage failed. The noise library checkpoints and rolls back
+		// on failure, so the Machine is still alive. The caller can retry with
+		// a different packet.
+		return nil, nil, fmt.Errorf("noise ReadMessage: %w", err)
+	}
+
+	// From here on, noise state has advanced. Any error is fatal.
+	flags := m.peerMsgFlags()
+
+	if err := m.processPayload(msg, flags); err != nil {
+		return nil, nil, err
+	}
+
+	// If ReadMessage derived keys, the handshake is complete. Noise should
+	// always produce both keys together; asymmetry is a protocol invariant
+	// violation.
+	if eKey != nil || dKey != nil {
+		if eKey == nil || dKey == nil {
+			m.failed = true
+			return nil, nil, ErrAsymmetricCipherKeys
+		}
+		if err := m.requireComplete(); err != nil {
+			return nil, nil, err
+		}
+		return nil, m.completed(eKey, dKey), nil
+	}
+
+	// ReadMessage didn't complete, produce the next outgoing message
+	out, dk, ek, err := m.buildResponse(out)
+	if err != nil {
+		m.failed = true
+		return nil, nil, err
+	}
+
+	if ek != nil || dk != nil {
+		if ek == nil || dk == nil {
+			m.failed = true
+			return nil, nil, ErrAsymmetricCipherKeys
+		}
+		if err := m.requireComplete(); err != nil {
+			return nil, nil, err
+		}
+		return out, m.completed(ek, dk), nil
+	}
+
+	return out, nil, nil
+}
+
+func (m *Machine) completed(eKey, dKey *noise.CipherState) *Result {
+	m.result.EKey = eKey
+	m.result.DKey = dKey
+	m.result.MessageIndex = uint64(m.hs.MessageIndex())
+	return m.result
+}
+
+func (m *Machine) processPayload(msg []byte, flags msgFlags) error {
+	if len(msg) == 0 {
+		if flags.expectsPayload || flags.expectsCert {
+			m.failed = true
+			return ErrMissingContent
+		}
+		return nil
+	}
+
+	payload, err := UnmarshalPayload(msg)
+	if err != nil {
+		m.failed = true
+		return fmt.Errorf("unmarshal handshake: %w", err)
+	}
+
+	// Assert the payload contains exactly what we expect
+	hasPayloadData := payload.InitiatorIndex != 0 || payload.ResponderIndex != 0 || payload.Time != 0
+	if hasPayloadData != flags.expectsPayload {
+		m.failed = true
+		return ErrUnexpectedContent
+	}
+
+	hasCertData := len(payload.Cert) > 0
+	if hasCertData != flags.expectsCert {
+		m.failed = true
+		return ErrUnexpectedContent
+	}
+
+	// Process payload
+	if flags.expectsPayload {
+		if m.result.Initiator {
+			m.result.RemoteIndex = payload.ResponderIndex
+		} else {
+			m.result.RemoteIndex = payload.InitiatorIndex
+		}
+		m.result.HandshakeTime = payload.Time
+		m.payloadSet = true
+	}
+
+	// Process certificate
+	if flags.expectsCert {
+		if err := m.validateCert(payload); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func (m *Machine) validateCert(payload Payload) error {
+	cred := m.getCred(m.myVersion)
+	if cred == nil {
+		m.failed = true
+		return fmt.Errorf("%w: %v", ErrNoCredential, m.myVersion)
+	}
+	rc, err := cert.Recombine(
+		cert.Version(payload.CertVersion),
+		payload.Cert,
+		m.hs.PeerStatic(),
+		cred.Cert.Curve(),
+	)
+	if err != nil {
+		m.failed = true
+		return fmt.Errorf("recombine cert: %w", err)
+	}
+
+	if !bytes.Equal(rc.PublicKey(), m.hs.PeerStatic()) {
+		m.failed = true
+		return ErrPublicKeyMismatch
+	}
+
+	// Version negotiation, if the peer sent a different version and we have it, switch
+	if rc.Version() != m.myVersion {
+		if m.getCred(rc.Version()) != nil {
+			m.myVersion = rc.Version()
+		}
+	}
+
+	verified, err := m.verifier(rc)
+	if err != nil {
+		m.failed = true
+		return fmt.Errorf("verify cert: %w", err)
+	}
+
+	m.result.RemoteCert = verified
+	m.remoteCertSet = true
+	return nil
+}
+
+func (m *Machine) marshalOutgoing(flags msgFlags) ([]byte, error) {
+	if !flags.expectsPayload && !flags.expectsCert {
+		return nil, nil
+	}
+
+	var p Payload
+	if flags.expectsPayload {
+		if !m.indexAllocated {
+			index, err := m.allocIndex()
+			if err != nil {
+				return nil, fmt.Errorf("%w: %w", ErrIndexAllocation, err)
+			}
+			m.result.LocalIndex = index
+			m.indexAllocated = true
+		}
+
+		if m.result.Initiator {
+			p.InitiatorIndex = m.result.LocalIndex
+		} else {
+			p.ResponderIndex = m.result.LocalIndex
+			p.InitiatorIndex = m.result.RemoteIndex
+		}
+		p.Time = uint64(time.Now().UnixNano())
+	}
+	if flags.expectsCert {
+		cred := m.getCred(m.myVersion)
+		if cred == nil {
+			return nil, fmt.Errorf("%w: %v", ErrNoCredential, m.myVersion)
+		}
+		p.Cert = cred.Bytes
+		p.CertVersion = uint32(cred.Cert.Version())
+		m.result.MyCert = cred.Cert
+	}
+
+	return MarshalPayload(nil, p), nil
+}
+
+func (m *Machine) buildResponse(out []byte) ([]byte, *noise.CipherState, *noise.CipherState, error) {
+	flags := m.myMsgFlags()
+	hsBytes, err := m.marshalOutgoing(flags)
+	if err != nil {
+		return nil, nil, nil, err
+	}
+
+	// Extend out by header.Len to make room for the header. slices.Grow is a
+	// no-op when the cap is already sufficient (the zero-copy case where the
+	// caller passed a pre-sized buffer). header.Encode overwrites the new
+	// bytes, so they don't need to be zeroed.
+	start := len(out)
+	out = slices.Grow(out, header.Len)[:start+header.Len]
+	header.Encode(
+		out[start:],
+		header.Version, header.Handshake, m.subtype,
+		m.result.RemoteIndex,
+		uint64(m.hs.MessageIndex()+1),
+	)
+
+	// noise.WriteMessage appends the encrypted handshake message to out,
+	// reusing capacity when present.
+	//
+	// The (dKey, eKey) ordering here is correct for IX, where the responder
+	// completes the handshake by writing the stage-2 message. noise returns
+	// (cs1, cs2) where cs1 is the initiator->responder cipher (which is the
+	// responder's decrypt key). For 3-message patterns where an initiator
+	// finishes by writing the final message, this ordering would be wrong;
+	// revisit when XX/pqIX lands.
+	out, dKey, eKey, err := m.hs.WriteMessage(out, hsBytes)
+	if err != nil {
+		return nil, nil, nil, fmt.Errorf("noise WriteMessage: %w", err)
+	}
+
+	return out, dKey, eKey, nil
+}

handshake/machine_test.go

@@ -0,0 +1,662 @@
+package handshake
+
+import (
+	"net/netip"
+	"testing"
+	"time"
+
+	"github.com/flynn/noise"
+	"github.com/slackhq/nebula/cert"
+	ct "github.com/slackhq/nebula/cert_test"
+	"github.com/slackhq/nebula/header"
+	"github.com/slackhq/nebula/noiseutil"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestMachineIXHappyPath(t *testing.T) {
+	ca, _, caKey, _ := ct.NewTestCaCert(
+		cert.Version2, cert.Curve_CURVE25519, time.Time{}, time.Time{}, nil, nil, nil,
+	)
+	caPool := ct.NewTestCAPool(ca)
+
+	initCS := newTestCertState(t, ca, caKey, "initiator", []netip.Prefix{netip.MustParsePrefix("10.0.0.1/24")})
+	respCS := newTestCertState(t, ca, caKey, "responder", []netip.Prefix{netip.MustParsePrefix("10.0.0.2/24")})
+
+	initR, respR := doFullHandshake(t, initCS, respCS, caPool)
+
+	assert.Equal(t, "responder", initR.RemoteCert.Certificate.Name())
+	assert.Equal(t, "initiator", respR.RemoteCert.Certificate.Name())
+
+	assert.Equal(t, uint32(1000), initR.LocalIndex)
+	assert.Equal(t, uint32(2000), initR.RemoteIndex)
+	assert.Equal(t, uint32(2000), respR.LocalIndex)
+	assert.Equal(t, uint32(1000), respR.RemoteIndex)
+
+	assert.Equal(t, uint64(2), initR.MessageIndex, "IX has 2 messages")
+	assert.Equal(t, uint64(2), respR.MessageIndex, "IX has 2 messages")
+
+	ct1, err := initR.EKey.Encrypt(nil, nil, []byte("hello"))
+	require.NoError(t, err)
+	pt1, err := respR.DKey.Decrypt(nil, nil, ct1)
+	require.NoError(t, err)
+	assert.Equal(t, []byte("hello"), pt1)
+
+	ct2, err := respR.EKey.Encrypt(nil, nil, []byte("world"))
+	require.NoError(t, err)
+	pt2, err := initR.DKey.Decrypt(nil, nil, ct2)
+	require.NoError(t, err)
+	assert.Equal(t, []byte("world"), pt2)
+}
+
+func TestMachineInitiateErrors(t *testing.T) {
+	ca, _, caKey, _ := ct.NewTestCaCert(
+		cert.Version2, cert.Curve_CURVE25519, time.Time{}, time.Time{}, nil, nil, nil,
+	)
+	caPool := ct.NewTestCAPool(ca)
+	cs := newTestCertState(t, ca, caKey, "test", []netip.Prefix{netip.MustParsePrefix("10.0.0.1/24")})
+	v := testVerifier(caPool)
+
+	t.Run("initiate on responder", func(t *testing.T) {
+		m := newTestMachine(t, cs, v, false, 100)
+		_, err := m.Initiate(nil)
+		require.ErrorIs(t, err, ErrInitiateOnResponder)
+		assert.True(t, m.Failed())
+	})
+
+	t.Run("initiate called twice", func(t *testing.T) {
+		m := newTestMachine(t, cs, v, true, 100)
+		_, err := m.Initiate(nil)
+		require.NoError(t, err)
+		_, err = m.Initiate(nil)
+		require.ErrorIs(t, err, ErrInitiateAlreadyCalled)
+		assert.True(t, m.Failed())
+	})
+
+	t.Run("process packet before initiate on initiator", func(t *testing.T) {
+		m := newTestMachine(t, cs, v, true, 100)
+		_, _, err := m.ProcessPacket(nil, make([]byte, 100))
+		require.ErrorIs(t, err, ErrInitiateNotCalled)
+		assert.True(t, m.Failed())
+	})
+
+	t.Run("calling failed machine", func(t *testing.T) {
+		m := newTestMachine(t, cs, v, false, 100)
+		_, err := m.Initiate(nil) // fails: responder
+		require.Error(t, err)
+		_, err = m.Initiate(nil) // fails: already failed
+		require.ErrorIs(t, err, ErrMachineFailed)
+	})
+}
+
+func TestMachineProcessPacketErrors(t *testing.T) {
+	ca, _, caKey, _ := ct.NewTestCaCert(
+		cert.Version2, cert.Curve_CURVE25519, time.Time{}, time.Time{}, nil, nil, nil,
+	)
+	caPool := ct.NewTestCAPool(ca)
+	cs := newTestCertState(t, ca, caKey, "test", []netip.Prefix{netip.MustParsePrefix("10.0.0.1/24")})
+	v := testVerifier(caPool)
+
+	t.Run("packet too short", func(t *testing.T) {
+		m := newTestMachine(t, cs, v, false, 100)
+		_, _, err := m.ProcessPacket(nil, []byte{1, 2, 3})
+		require.ErrorIs(t, err, ErrPacketTooShort)
+		assert.False(t, m.Failed(), "short packet should not kill machine")
+	})
+
+	t.Run("noise decryption failure is recoverable", func(t *testing.T) {
+		initCS := newTestCertState(t, ca, caKey, "init", []netip.Prefix{netip.MustParsePrefix("10.0.0.1/24")})
+		initM := newTestMachine(t, initCS, v, true, 100)
+		msg1, err := initM.Initiate(nil)
+		require.NoError(t, err)
+
+		respM := newTestMachine(t, cs, v, false, 200)
+		resp, _, err := respM.ProcessPacket(nil, msg1)
+		require.NoError(t, err)
+
+		corrupted := make([]byte, len(resp))
+		copy(corrupted, resp)
+		for i := header.Len; i < len(corrupted); i++ {
+			corrupted[i] ^= 0xff
+		}
+		_, _, err = initM.ProcessPacket(nil, corrupted)
+		require.Error(t, err)
+		assert.False(t, initM.Failed(), "noise failure should be recoverable")
+
+		// And the machine should still complete a real handshake afterward.
+		_, result, err := initM.ProcessPacket(nil, resp)
+		require.NoError(t, err)
+		require.NotNil(t, result, "initiator should complete on the legitimate response")
+	})
+
+	t.Run("invalid cert is fatal", func(t *testing.T) {
+		otherCA, _, otherCAKey, _ := ct.NewTestCaCert(
+			cert.Version2, cert.Curve_CURVE25519, time.Time{}, time.Time{}, nil, nil, nil,
+		)
+		otherCS := newTestCertState(t, otherCA, otherCAKey, "other", []netip.Prefix{netip.MustParsePrefix("10.0.0.2/24")})
+
+		initM := newTestMachine(t, otherCS, testVerifier(ct.NewTestCAPool(otherCA)), true, 100)
+		msg1, err := initM.Initiate(nil)
+		require.NoError(t, err)
+
+		respM := newTestMachine(t, cs, v, false, 200)
+		_, _, err = respM.ProcessPacket(nil, msg1)
+		require.Error(t, err)
+		assert.True(t, respM.Failed(), "cert validation failure should kill machine")
+	})
+
+	t.Run("subtype mismatch is recoverable", func(t *testing.T) {
+		initCS := newTestCertState(t, ca, caKey, "init", []netip.Prefix{netip.MustParsePrefix("10.0.0.1/24")})
+		initM := newTestMachine(t, initCS, v, true, 100)
+		msg1, err := initM.Initiate(nil)
+		require.NoError(t, err)
+
+		// Mutate the subtype byte (offset 1 in the header) to a value the
+		// responder Machine wasn't built for.
+		bad := make([]byte, len(msg1))
+		copy(bad, msg1)
+		bad[1] = 0xff
+
+		respM := newTestMachine(t, cs, v, false, 200)
+		_, _, err = respM.ProcessPacket(nil, bad)
+		require.ErrorIs(t, err, ErrSubtypeMismatch)
+		assert.False(t, respM.Failed(), "subtype mismatch should not kill the machine")
+
+		// And the machine should still complete a real handshake afterward.
+		resp, result, err := respM.ProcessPacket(nil, msg1)
+		require.NoError(t, err)
+		require.NotNil(t, result, "responder should complete on the legitimate stage-1 packet")
+		assert.NotEmpty(t, resp, "responder should produce a stage-2 reply")
+	})
+}
+
+// TestMachineProcessPayload exercises processPayload's internal validation
+// directly. Most of these failure modes can't be reached black-box once the
+// subtype check at the top of ProcessPacket gates external callers, so we
+// drive them by hand here for coverage.
+func TestMachineProcessPayload(t *testing.T) {
+	ca, _, caKey, _ := ct.NewTestCaCert(
+		cert.Version2, cert.Curve_CURVE25519, time.Time{}, time.Time{}, nil, nil, nil,
+	)
+	caPool := ct.NewTestCAPool(ca)
+	cs := newTestCertState(t, ca, caKey, "test", []netip.Prefix{netip.MustParsePrefix("10.0.0.1/24")})
+	v := testVerifier(caPool)
+
+	t.Run("empty message with expects fails", func(t *testing.T) {
+		m := newTestMachine(t, cs, v, false, 100)
+		err := m.processPayload(nil, msgFlags{expectsPayload: true, expectsCert: true})
+		require.ErrorIs(t, err, ErrMissingContent)
+		assert.True(t, m.Failed())
+	})
+
+	t.Run("empty message with no expects passes", func(t *testing.T) {
+		m := newTestMachine(t, cs, v, false, 100)
+		err := m.processPayload(nil, msgFlags{})
+		require.NoError(t, err)
+		assert.False(t, m.Failed())
+	})
+
+	t.Run("malformed protobuf is fatal", func(t *testing.T) {
+		m := newTestMachine(t, cs, v, false, 100)
+		err := m.processPayload([]byte{0xff, 0xff, 0xff}, msgFlags{expectsPayload: true, expectsCert: true})
+		require.Error(t, err)
+		assert.True(t, m.Failed())
+	})
+
+	t.Run("unexpected payload data is fatal", func(t *testing.T) {
+		m := newTestMachine(t, cs, v, false, 100)
+		// A payload with index data when none was expected.
+		bytes := MarshalPayload(nil, Payload{InitiatorIndex: 42, Time: 1})
+		err := m.processPayload(bytes, msgFlags{expectsPayload: false, expectsCert: false})
+		require.ErrorIs(t, err, ErrUnexpectedContent)
+		assert.True(t, m.Failed())
+	})
+
+	t.Run("unexpected cert data is fatal", func(t *testing.T) {
+		m := newTestMachine(t, cs, v, false, 100)
+		// A payload with cert when none was expected.
+		bytes := MarshalPayload(nil, Payload{Cert: []byte{1, 2, 3}, CertVersion: 2})
+		err := m.processPayload(bytes, msgFlags{expectsPayload: false, expectsCert: false})
+		require.ErrorIs(t, err, ErrUnexpectedContent)
+		assert.True(t, m.Failed())
+	})
+
+	t.Run("missing payload data when expected is fatal", func(t *testing.T) {
+		m := newTestMachine(t, cs, v, false, 100)
+		// Cert present, but no index/time fields.
+		bytes := MarshalPayload(nil, Payload{Cert: []byte{1, 2, 3}, CertVersion: 2})
+		err := m.processPayload(bytes, msgFlags{expectsPayload: true, expectsCert: true})
+		require.ErrorIs(t, err, ErrUnexpectedContent)
+		assert.True(t, m.Failed())
+	})
+}
+
+// TestMachineRequireComplete checks the fail-on-incomplete-handshake path
+// directly. Like processPayload above this isn't reachable from a normal IX
+// flow, so we drive it by hand.
+func TestMachineRequireComplete(t *testing.T) {
+	ca, _, caKey, _ := ct.NewTestCaCert(
+		cert.Version2, cert.Curve_CURVE25519, time.Time{}, time.Time{}, nil, nil, nil,
+	)
+	caPool := ct.NewTestCAPool(ca)
+	cs := newTestCertState(t, ca, caKey, "test", []netip.Prefix{netip.MustParsePrefix("10.0.0.1/24")})
+	v := testVerifier(caPool)
+
+	t.Run("missing both fails", func(t *testing.T) {
+		m := newTestMachine(t, cs, v, false, 100)
+		err := m.requireComplete()
+		require.ErrorIs(t, err, ErrIncompleteHandshake)
+		assert.True(t, m.Failed())
+	})
+
+	t.Run("payload only fails", func(t *testing.T) {
+		m := newTestMachine(t, cs, v, false, 100)
+		m.payloadSet = true
+		err := m.requireComplete()
+		require.ErrorIs(t, err, ErrIncompleteHandshake)
+		assert.True(t, m.Failed())
+	})
+
+	t.Run("cert only fails", func(t *testing.T) {
+		m := newTestMachine(t, cs, v, false, 100)
+		m.remoteCertSet = true
+		err := m.requireComplete()
+		require.ErrorIs(t, err, ErrIncompleteHandshake)
+		assert.True(t, m.Failed())
+	})
+
+	t.Run("both set passes", func(t *testing.T) {
+		m := newTestMachine(t, cs, v, false, 100)
+		m.payloadSet = true
+		m.remoteCertSet = true
+		err := m.requireComplete()
+		require.NoError(t, err)
+		assert.False(t, m.Failed())
+	})
+}
+
+func TestMachineAESCipher(t *testing.T) {
+	ca, _, caKey, _ := ct.NewTestCaCert(
+		cert.Version2, cert.Curve_CURVE25519, time.Time{}, time.Time{}, nil, nil, nil,
+	)
+	caPool := ct.NewTestCAPool(ca)
+
+	initCS := newTestCertStateWithCipher(
+		t, ca, caKey, "init",
+		[]netip.Prefix{netip.MustParsePrefix("10.0.0.1/24")},
+		noiseutil.CipherAESGCM,
+	)
+	respCS := newTestCertStateWithCipher(
+		t, ca, caKey, "resp",
+		[]netip.Prefix{netip.MustParsePrefix("10.0.0.2/24")},
+		noiseutil.CipherAESGCM,
+	)
+
+	initR, respR := doFullHandshake(t, initCS, respCS, caPool)
+
+	ct1, err := initR.EKey.Encrypt(nil, nil, []byte("works"))
+	require.NoError(t, err)
+	pt1, err := respR.DKey.Decrypt(nil, nil, ct1)
+	require.NoError(t, err)
+	assert.Equal(t, []byte("works"), pt1)
+
+	ct2, err := respR.EKey.Encrypt(nil, nil, []byte("back"))
+	require.NoError(t, err)
+	pt2, err := initR.DKey.Decrypt(nil, nil, ct2)
+	require.NoError(t, err)
+	assert.Equal(t, []byte("back"), pt2)
+}
+
+func TestResultFields(t *testing.T) {
+	ca, _, caKey, _ := ct.NewTestCaCert(
+		cert.Version2, cert.Curve_CURVE25519, time.Time{}, time.Time{}, nil, nil, nil,
+	)
+	caPool := ct.NewTestCAPool(ca)
+	initCS := newTestCertState(t, ca, caKey, "init", []netip.Prefix{netip.MustParsePrefix("10.0.0.1/24")})
+	respCS := newTestCertState(t, ca, caKey, "resp", []netip.Prefix{netip.MustParsePrefix("10.0.0.2/24")})
+
+	initR, respR := doFullHandshake(t, initCS, respCS, caPool)
+
+	assert.True(t, initR.Initiator)
+	assert.False(t, respR.Initiator)
+	assert.NotZero(t, initR.HandshakeTime)
+	assert.NotZero(t, respR.HandshakeTime)
+	assert.NotNil(t, initR.RemoteCert)
+	assert.NotNil(t, respR.RemoteCert)
+}
+
+func TestMachineBufferReuse(t *testing.T) {
+	ca, _, caKey, _ := ct.NewTestCaCert(
+		cert.Version2, cert.Curve_CURVE25519, time.Time{}, time.Time{}, nil, nil, nil,
+	)
+	caPool := ct.NewTestCAPool(ca)
+	initCS := newTestCertState(t, ca, caKey, "init", []netip.Prefix{netip.MustParsePrefix("10.0.0.1/24")})
+	respCS := newTestCertState(t, ca, caKey, "resp", []netip.Prefix{netip.MustParsePrefix("10.0.0.2/24")})
+	v := testVerifier(caPool)
+
+	initM := newTestMachine(t, initCS, v, true, 1000)
+	respM := newTestMachine(t, respCS, v, false, 2000)
+
+	msg1, err := initM.Initiate(nil)
+	require.NoError(t, err)
+
+	t.Run("response writes into provided buffer", func(t *testing.T) {
+		buf := make([]byte, 0, 4096)
+		resp, result, err := respM.ProcessPacket(buf, msg1)
+		require.NoError(t, err)
+		require.NotNil(t, result)
+
+		assert.NotEmpty(t, resp, "response should have content")
+		assert.Equal(t, &buf[:1][0], &resp[:1][0],
+			"response should reuse the provided buffer's backing array")
+	})
+
+	t.Run("initiate writes into provided buffer", func(t *testing.T) {
+		initM2 := newTestMachine(t, initCS, v, true, 3000)
+		buf := make([]byte, 0, 4096)
+		msg, err := initM2.Initiate(buf)
+		require.NoError(t, err)
+
+		assert.NotEmpty(t, msg, "initiate should have content")
+		assert.Equal(t, &buf[:1][0], &msg[:1][0],
+			"initiate should reuse the provided buffer's backing array")
+	})
+
+	t.Run("nil out still works", func(t *testing.T) {
+		initM2 := newTestMachine(t, initCS, v, true, 4000)
+		respM2 := newTestMachine(t, respCS, v, false, 5000)
+
+		msg1, err := initM2.Initiate(nil)
+		require.NoError(t, err)
+
+		resp, _, err := respM2.ProcessPacket(nil, msg1)
+		require.NoError(t, err)
+
+		out, result, err := initM2.ProcessPacket(nil, resp)
+		require.NoError(t, err)
+		assert.NotNil(t, result)
+		assert.Nil(t, out, "initiator should have no response for IX msg2")
+	})
+}
+
+func TestMachineMsgIndexTracking(t *testing.T) {
+	ca, _, caKey, _ := ct.NewTestCaCert(
+		cert.Version2, cert.Curve_CURVE25519, time.Time{}, time.Time{}, nil, nil, nil,
+	)
+	caPool := ct.NewTestCAPool(ca)
+	initCS := newTestCertState(t, ca, caKey, "init", []netip.Prefix{netip.MustParsePrefix("10.0.0.1/24")})
+	respCS := newTestCertState(t, ca, caKey, "resp", []netip.Prefix{netip.MustParsePrefix("10.0.0.2/24")})
+	v := testVerifier(caPool)
+
+	initM := newTestMachine(t, initCS, v, true, 100)
+	respM := newTestMachine(t, respCS, v, false, 200)
+
+	msg1, err := initM.Initiate(nil)
+	require.NoError(t, err)
+
+	resp1, result1, err := respM.ProcessPacket(nil, msg1)
+	require.NoError(t, err)
+	assert.NotNil(t, result1)
+
+	_, result2, err := initM.ProcessPacket(nil, resp1)
+	require.NoError(t, err)
+	assert.NotNil(t, result2)
+}
+
+func TestMachineThreeMessagePattern(t *testing.T) {
+	registerTestXXInfo(t)
+
+	// Use HandshakeXX (3 messages) to verify the Machine handles multi-message
+	// patterns correctly. XX flow:
+	//   msg1 (I->R): [E]           - payload only, no cert
+	//   msg2 (R->I): [E, ee, S, es] - payload + cert
+	//   msg3 (I->R): [S, se]       - cert only (no payload, not first two)
+
+	ca, _, caKey, _ := ct.NewTestCaCert(
+		cert.Version2, cert.Curve_CURVE25519, time.Time{}, time.Time{}, nil, nil, nil,
+	)
+	caPool := ct.NewTestCAPool(ca)
+	v := testVerifier(caPool)
+
+	initCS := newTestCertState(t, ca, caKey, "init", []netip.Prefix{netip.MustParsePrefix("10.0.0.1/24")})
+	respCS := newTestCertState(t, ca, caKey, "resp", []netip.Prefix{netip.MustParsePrefix("10.0.0.2/24")})
+
+	initM, err := NewMachine(
+		cert.Version2,
+		initCS.getCredential, v,
+		func() (uint32, error) { return 1000, nil },
+		true, header.HandshakeXXPSK0,
+	)
+	require.NoError(t, err)
+
+	respM, err := NewMachine(
+		cert.Version2,
+		respCS.getCredential, v,
+		func() (uint32, error) { return 2000, nil },
+		false, header.HandshakeXXPSK0,
+	)
+	require.NoError(t, err)
+
+	// msg1: initiator -> responder (E only, no cert)
+	msg1, err := initM.Initiate(nil)
+	require.NoError(t, err)
+	assert.NotEmpty(t, msg1)
+
+	// Responder processes msg1, should not complete yet, should produce msg2
+	msg2, result, err := respM.ProcessPacket(nil, msg1)
+	require.NoError(t, err)
+	assert.Nil(t, result, "XX should not complete on msg1")
+	assert.NotEmpty(t, msg2, "responder should produce msg2")
+
+	// Initiator processes msg2: gets responder's cert, produces msg3, and
+	// completes (WriteMessage for msg3 derives keys)
+	msg3, initResult, err := initM.ProcessPacket(nil, msg2)
+	require.NoError(t, err)
+	require.NotNil(t, initResult, "XX initiator should complete after reading msg2 and writing msg3")
+	assert.NotEmpty(t, msg3, "initiator should produce msg3")
+	assert.Equal(t, "resp", initResult.RemoteCert.Certificate.Name())
+
+	// Responder processes msg3: gets initiator's cert and completes
+	_, respResult, err := respM.ProcessPacket(nil, msg3)
+	require.NoError(t, err)
+	require.NotNil(t, respResult, "XX responder should complete on msg3")
+	assert.Equal(t, "init", respResult.RemoteCert.Certificate.Name())
+
+	assert.Equal(t, uint64(3), initResult.MessageIndex, "XX has 3 messages")
+	assert.Equal(t, uint64(3), respResult.MessageIndex, "XX has 3 messages")
+
+	// Verify keys work
+	ct1, err := initResult.EKey.Encrypt(nil, nil, []byte("three messages"))
+	require.NoError(t, err)
+	pt1, err := respResult.DKey.Decrypt(nil, nil, ct1)
+	require.NoError(t, err)
+	assert.Equal(t, []byte("three messages"), pt1)
+}
+
+// NOTE: ErrIncompleteHandshake is tested implicitly. It can't be triggered with
+// IX since the cert is always in the payload. A 3-message pattern test (HybridIX)
+// should exercise the case where cert arrives in msg3 and verify that completing
+// without it fails.
+
+func TestMachineExpiredCert(t *testing.T) {
+	ca, _, caKey, _ := ct.NewTestCaCert(
+		cert.Version2, cert.Curve_CURVE25519,
+		time.Now().Add(-24*time.Hour), time.Now().Add(24*time.Hour),
+		nil, nil, nil,
+	)
+	caPool := ct.NewTestCAPool(ca)
+
+	expCert, _, expKeyPEM, _ := ct.NewTestCert(
+		cert.Version2, cert.Curve_CURVE25519, ca, caKey,
+		"expired", time.Now().Add(-2*time.Hour), time.Now().Add(-1*time.Hour),
+		[]netip.Prefix{netip.MustParsePrefix("10.0.0.1/24")}, nil, nil,
+	)
+	expKey, _, _, err := cert.UnmarshalPrivateKeyFromPEM(expKeyPEM)
+	require.NoError(t, err)
+	expHsBytes, err := expCert.MarshalForHandshakes()
+	require.NoError(t, err)
+	ncs := noise.NewCipherSuite(noise.DH25519, noise.CipherChaChaPoly, noise.HashSHA256)
+
+	expiredCS := &testCertState{
+		version: cert.Version2,
+		creds: map[cert.Version]*Credential{
+			cert.Version2: NewCredential(expCert, expHsBytes, expKey, ncs),
+		},
+	}
+
+	respCS := newTestCertState(
+		t, ca, caKey, "responder",
+		[]netip.Prefix{netip.MustParsePrefix("10.0.0.2/24")},
+	)
+
+	_, respM, _, _, err := initiateHandshake(
+		t, expiredCS, testVerifier(caPool),
+		respCS, testVerifier(caPool),
+	)
+	require.ErrorContains(t, err, "verify cert")
+	assert.True(t, respM.Failed())
+}
+
+func TestMachineNoCertNetworks(t *testing.T) {
+	ca, _, caKey, _ := ct.NewTestCaCert(
+		cert.Version2, cert.Curve_CURVE25519, time.Time{}, time.Time{}, nil, nil, nil,
+	)
+	caPool := ct.NewTestCAPool(ca)
+
+	caHsBytes, err := ca.MarshalForHandshakes()
+	require.NoError(t, err)
+	ncs := noise.NewCipherSuite(noise.DH25519, noise.CipherChaChaPoly, noise.HashSHA256)
+
+	noNetCS := &testCertState{
+		version: cert.Version2,
+		creds: map[cert.Version]*Credential{
+			cert.Version2: NewCredential(ca, caHsBytes, caKey, ncs),
+		},
+	}
+
+	respCS := newTestCertState(
+		t, ca, caKey, "responder",
+		[]netip.Prefix{netip.MustParsePrefix("10.0.0.2/24")},
+	)
+
+	_, respM, _, _, err := initiateHandshake(
+		t, noNetCS, testVerifier(caPool),
+		respCS, testVerifier(caPool),
+	)
+	require.Error(t, err)
+	assert.True(t, respM.Failed())
+}
+
+func TestMachineDifferentCAs(t *testing.T) {
+	ca1, _, caKey1, _ := ct.NewTestCaCert(
+		cert.Version2, cert.Curve_CURVE25519, time.Time{}, time.Time{}, nil, nil, nil,
+	)
+	ca2, _, caKey2, _ := ct.NewTestCaCert(
+		cert.Version2, cert.Curve_CURVE25519, time.Time{}, time.Time{}, nil, nil, nil,
+	)
+
+	initCS := newTestCertState(
+		t, ca1, caKey1, "init",
+		[]netip.Prefix{netip.MustParsePrefix("10.0.0.1/24")},
+	)
+	respCS := newTestCertState(
+		t, ca2, caKey2, "resp",
+		[]netip.Prefix{netip.MustParsePrefix("10.0.0.2/24")},
+	)
+
+	_, respM, _, _, err := initiateHandshake(
+		t, initCS, testVerifier(ct.NewTestCAPool(ca1)),
+		respCS, testVerifier(ct.NewTestCAPool(ca2)),
+	)
+	require.ErrorContains(t, err, "verify cert")
+	assert.True(t, respM.Failed())
+}
+
+func TestMachineVersionNegotiation(t *testing.T) {
+	ca1, _, caKey1, _ := ct.NewTestCaCert(
+		cert.Version1, cert.Curve_CURVE25519, time.Time{}, time.Time{}, nil, nil, nil,
+	)
+	ca2, _, caKey2, _ := ct.NewTestCaCert(
+		cert.Version2, cert.Curve_CURVE25519, time.Time{}, time.Time{}, nil, nil, nil,
+	)
+	caPool := ct.NewTestCAPool(ca1, ca2)
+
+	makeMultiVersionResp := func(t *testing.T) *testCertState {
+		t.Helper()
+		respCertV1, _, respKeyPEM, _ := ct.NewTestCert(
+			cert.Version1, cert.Curve_CURVE25519, ca1, caKey1, "resp",
+			ca1.NotBefore(), ca1.NotAfter(),
+			[]netip.Prefix{netip.MustParsePrefix("10.0.0.2/24")}, nil, nil,
+		)
+		respKey, _, _, _ := cert.UnmarshalPrivateKeyFromPEM(respKeyPEM)
+		respCertV2, _ := ct.NewTestCertDifferentVersion(respCertV1, cert.Version2, ca2, caKey2)
+		respHsV1, _ := respCertV1.MarshalForHandshakes()
+		respHsV2, _ := respCertV2.MarshalForHandshakes()
+		ncs := noise.NewCipherSuite(noise.DH25519, noise.CipherChaChaPoly, noise.HashSHA256)
+		return &testCertState{
+			version: cert.Version1,
+			creds: map[cert.Version]*Credential{
+				cert.Version1: NewCredential(respCertV1, respHsV1, respKey, ncs),
+				cert.Version2: NewCredential(respCertV2, respHsV2, respKey, ncs),
+			},
+		}
+	}
+
+	t.Run("responder matches initiator version", func(t *testing.T) {
+		initCS := newTestCertState(
+			t, ca2, caKey2, "init",
+			[]netip.Prefix{netip.MustParsePrefix("10.0.0.1/24")},
+		)
+		respCS := makeMultiVersionResp(t)
+		v := testVerifier(caPool)
+
+		initM, _, respResult, resp, err := initiateHandshake(
+			t, initCS, v,
+			respCS, v,
+		)
+		require.NoError(t, err)
+		require.NotNil(t, respResult)
+
+		assert.Equal(t, cert.Version2, respResult.MyCert.Version(),
+			"responder should negotiate to initiator's version")
+
+		_, initResult, err := initM.ProcessPacket(nil, resp)
+		require.NoError(t, err)
+		require.NotNil(t, initResult)
+		assert.Equal(t, cert.Version2, initResult.RemoteCert.Certificate.Version(),
+			"initiator should see V2 cert from responder")
+	})
+
+	t.Run("responder keeps version when no match available", func(t *testing.T) {
+		initCS := newTestCertState(
+			t, ca2, caKey2, "init",
+			[]netip.Prefix{netip.MustParsePrefix("10.0.0.1/24")},
+		)
+
+		respCert, _, respKeyPEM, _ := ct.NewTestCert(
+			cert.Version1, cert.Curve_CURVE25519, ca1, caKey1, "resp",
+			ca1.NotBefore(), ca1.NotAfter(),
+			[]netip.Prefix{netip.MustParsePrefix("10.0.0.2/24")}, nil, nil,
+		)
+		respKey, _, _, _ := cert.UnmarshalPrivateKeyFromPEM(respKeyPEM)
+		respHs, _ := respCert.MarshalForHandshakes()
+		ncs := noise.NewCipherSuite(noise.DH25519, noise.CipherChaChaPoly, noise.HashSHA256)
+		respCS := &testCertState{
+			version: cert.Version1,
+			creds: map[cert.Version]*Credential{
+				cert.Version1: NewCredential(respCert, respHs, respKey, ncs),
+			},
+		}
+
+		v := testVerifier(caPool)
+		_, _, respResult, _, err := initiateHandshake(
+			t, initCS, v,
+			respCS, v,
+		)
+		require.NoError(t, err)
+		require.NotNil(t, respResult)
+
+		assert.Equal(t, cert.Version1, respResult.MyCert.Version(),
+			"responder should keep V1 when V2 not available")
+	})
+}

handshake/patterns.go

@@ -0,0 +1,54 @@
+package handshake
+
+import (
+	"fmt"
+
+	"github.com/flynn/noise"
+	"github.com/slackhq/nebula/header"
+)
+
+// msgFlags tracks what application data a handshake message carries.
+type msgFlags struct {
+	expectsPayload bool // message carries indexes and time
+	expectsCert    bool // message carries the certificate
+}
+
+// subtypeInfo bundles the noise pattern with the per-message flags for a
+// given handshake subtype.
+type subtypeInfo struct {
+	pattern noise.HandshakePattern
+	msgs    []msgFlags
+}
+
+// subtypeInfos defines the noise pattern and message content layout for each
+// handshake subtype.
+var subtypeInfos = map[header.MessageSubType]subtypeInfo{
+	// IX: 2 messages, both carry payload and cert
+	header.HandshakeIXPSK0: {
+		pattern: noise.HandshakeIX,
+		msgs: []msgFlags{
+			{expectsPayload: true, expectsCert: true},
+			{expectsPayload: true, expectsCert: true},
+		},
+	},
+
+	// XX: 3 messages
+	//   msg1 (I->R): payload only
+	//   msg2 (R->I): payload + cert
+	//   msg3 (I->R): cert only
+	//header.HandshakeXXPSK0: {
+	//	pattern: noise.HandshakeXX,
+	//	msgs: []msgFlags{
+	//		{expectsPayload: true, expectsCert: false},
+	//		{expectsPayload: true, expectsCert: true},
+	//		{expectsPayload: false, expectsCert: true},
+	//	},
+	//},
+}
+
+func subtypeInfoFor(subtype header.MessageSubType) (subtypeInfo, error) {
+	if info, ok := subtypeInfos[subtype]; ok {
+		return info, nil
+	}
+	return subtypeInfo{}, fmt.Errorf("%w: %d", ErrUnknownSubtype, subtype)
+}

handshake/patterns_test.go

@@ -0,0 +1,63 @@
+package handshake
+
+import (
+	"testing"
+
+	"github.com/flynn/noise"
+	"github.com/slackhq/nebula/header"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestSubtypeInfo(t *testing.T) {
+	t.Run("IX", func(t *testing.T) {
+		info, err := subtypeInfoFor(header.HandshakeIXPSK0)
+		require.NoError(t, err)
+		assert.Equal(t, noise.HandshakeIX.Name, info.pattern.Name)
+		require.Len(t, info.msgs, 2)
+		// msg1: payload + cert
+		assert.True(t, info.msgs[0].expectsPayload)
+		assert.True(t, info.msgs[0].expectsCert)
+		// msg2: payload + cert
+		assert.True(t, info.msgs[1].expectsPayload)
+		assert.True(t, info.msgs[1].expectsCert)
+	})
+
+	t.Run("XX", func(t *testing.T) {
+		registerTestXXInfo(t)
+		info, err := subtypeInfoFor(header.HandshakeXXPSK0)
+		require.NoError(t, err)
+		assert.Equal(t, noise.HandshakeXX.Name, info.pattern.Name)
+		require.Len(t, info.msgs, 3)
+		// msg1: payload only
+		assert.True(t, info.msgs[0].expectsPayload)
+		assert.False(t, info.msgs[0].expectsCert)
+		// msg2: payload + cert
+		assert.True(t, info.msgs[1].expectsPayload)
+		assert.True(t, info.msgs[1].expectsCert)
+		// msg3: cert only
+		assert.False(t, info.msgs[2].expectsPayload)
+		assert.True(t, info.msgs[2].expectsCert)
+	})
+
+	t.Run("unknown subtype returns error", func(t *testing.T) {
+		_, err := subtypeInfoFor(99)
+		require.ErrorIs(t, err, ErrUnknownSubtype)
+	})
+}
+
+// registerTestXXInfo temporarily registers XX subtype info for testing.
+func registerTestXXInfo(t *testing.T) {
+	t.Helper()
+	subtypeInfos[header.HandshakeXXPSK0] = subtypeInfo{
+		pattern: noise.HandshakeXX,
+		msgs: []msgFlags{
+			{expectsPayload: true, expectsCert: false},
+			{expectsPayload: true, expectsCert: true},
+			{expectsPayload: false, expectsCert: true},
+		},
+	}
+	t.Cleanup(func() {
+		delete(subtypeInfos, header.HandshakeXXPSK0)
+	})
+}

handshake/payload.go

@@ -0,0 +1,173 @@
+package handshake
+
+import (
+	"errors"
+	"math"
+
+	"google.golang.org/protobuf/encoding/protowire"
+)
+
+var (
+	errInvalidHandshakeMessage = errors.New("invalid handshake message")
+	errInvalidHandshakeDetails = errors.New("invalid handshake details")
+)
+
+// Payload represents the decoded fields of a handshake message.
+// Wire format is protobuf-compatible with NebulaHandshake{Details: NebulaHandshakeDetails{...}}.
+type Payload struct {
+	Cert           []byte
+	InitiatorIndex uint32
+	ResponderIndex uint32
+	Time           uint64
+	CertVersion    uint32
+}
+
+// Proto field numbers for NebulaHandshakeDetails
+const (
+	fieldCert           = 1 // bytes
+	fieldInitiatorIndex = 2 // uint32
+	fieldResponderIndex = 3 // uint32
+	fieldTime           = 5 // uint64
+	fieldCertVersion    = 8 // uint32
+)
+
+// MarshalPayload encodes a handshake payload in protobuf wire format compatible
+// with NebulaHandshake{Details: NebulaHandshakeDetails{...}}.
+// Returns out (which may be nil), with the marshalled Payload appended to it.
+func MarshalPayload(out []byte, p Payload) []byte {
+	var details []byte
+
+	if len(p.Cert) > 0 {
+		details = protowire.AppendTag(details, fieldCert, protowire.BytesType)
+		details = protowire.AppendBytes(details, p.Cert)
+	}
+	if p.InitiatorIndex != 0 {
+		details = protowire.AppendTag(details, fieldInitiatorIndex, protowire.VarintType)
+		details = protowire.AppendVarint(details, uint64(p.InitiatorIndex))
+	}
+	if p.ResponderIndex != 0 {
+		details = protowire.AppendTag(details, fieldResponderIndex, protowire.VarintType)
+		details = protowire.AppendVarint(details, uint64(p.ResponderIndex))
+	}
+	if p.Time != 0 {
+		details = protowire.AppendTag(details, fieldTime, protowire.VarintType)
+		details = protowire.AppendVarint(details, p.Time)
+	}
+	if p.CertVersion != 0 {
+		details = protowire.AppendTag(details, fieldCertVersion, protowire.VarintType)
+		details = protowire.AppendVarint(details, uint64(p.CertVersion))
+	}
+
+	out = protowire.AppendTag(out, 1, protowire.BytesType)
+	out = protowire.AppendBytes(out, details)
+
+	return out
+}
+
+// UnmarshalPayload decodes a protobuf-encoded NebulaHandshake message.
+func UnmarshalPayload(b []byte) (Payload, error) {
+	var p Payload
+
+	for len(b) > 0 {
+		num, typ, n := protowire.ConsumeTag(b)
+		if n < 0 {
+			return p, errInvalidHandshakeMessage
+		}
+		b = b[n:]
+
+		switch {
+		case num == 1 && typ == protowire.BytesType:
+			details, n := protowire.ConsumeBytes(b)
+			if n < 0 {
+				return p, errInvalidHandshakeMessage
+			}
+			b = b[n:]
+			if err := unmarshalPayloadDetails(&p, details); err != nil {
+				return p, err
+			}
+		default:
+			n := protowire.ConsumeFieldValue(num, typ, b)
+			if n < 0 {
+				return p, errInvalidHandshakeMessage
+			}
+			b = b[n:]
+		}
+	}
+
+	return p, nil
+}
+
+func unmarshalPayloadDetails(p *Payload, b []byte) error {
+	for len(b) > 0 {
+		num, typ, n := protowire.ConsumeTag(b)
+		if n < 0 {
+			return errInvalidHandshakeDetails
+		}
+		b = b[n:]
+
+		// For known field numbers, reject any non-matching wire type as a
+		// hard error rather than silently skipping. The caller will catch
+		// missing-field cases downstream, but a wire-type mismatch on a tag
+		// we know is a peer protocol violation worth flagging here.
+		// Repeated occurrences of a singular field follow proto3 last-wins.
+		switch num {
+		case fieldCert:
+			if typ != protowire.BytesType {
+				return errInvalidHandshakeDetails
+			}
+			v, n := protowire.ConsumeBytes(b)
+			if n < 0 {
+				return errInvalidHandshakeDetails
+			}
+			p.Cert = append([]byte(nil), v...)
+			b = b[n:]
+		case fieldInitiatorIndex:
+			if typ != protowire.VarintType {
+				return errInvalidHandshakeDetails
+			}
+			v, n := protowire.ConsumeVarint(b)
+			if n < 0 || v > math.MaxUint32 {
+				return errInvalidHandshakeDetails
+			}
+			p.InitiatorIndex = uint32(v)
+			b = b[n:]
+		case fieldResponderIndex:
+			if typ != protowire.VarintType {
+				return errInvalidHandshakeDetails
+			}
+			v, n := protowire.ConsumeVarint(b)
+			if n < 0 || v > math.MaxUint32 {
+				return errInvalidHandshakeDetails
+			}
+			p.ResponderIndex = uint32(v)
+			b = b[n:]
+		case fieldTime:
+			if typ != protowire.VarintType {
+				return errInvalidHandshakeDetails
+			}
+			v, n := protowire.ConsumeVarint(b)
+			if n < 0 {
+				return errInvalidHandshakeDetails
+			}
+			p.Time = v
+			b = b[n:]
+		case fieldCertVersion:
+			if typ != protowire.VarintType {
+				return errInvalidHandshakeDetails
+			}
+			v, n := protowire.ConsumeVarint(b)
+			if n < 0 || v > math.MaxUint32 {
+				return errInvalidHandshakeDetails
+			}
+			p.CertVersion = uint32(v)
+			b = b[n:]
+		default:
+			n := protowire.ConsumeFieldValue(num, typ, b)
+			if n < 0 {
+				return errInvalidHandshakeDetails
+			}
+			b = b[n:]
+		}
+	}
+	return nil
+}

handshake/payload_test.go

@@ -0,0 +1,361 @@
+package handshake
+
+import (
+	"bytes"
+	"math"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"google.golang.org/protobuf/encoding/protowire"
+)
+
+func TestPayloadRoundTrip(t *testing.T) {
+	t.Run("all fields set", func(t *testing.T) {
+		data := MarshalPayload(nil, Payload{
+			Cert:           []byte("test-cert-bytes"),
+			CertVersion:    2,
+			InitiatorIndex: 12345,
+			ResponderIndex: 67890,
+			Time:           1234567890,
+		})
+
+		got, err := UnmarshalPayload(data)
+		require.NoError(t, err)
+
+		assert.Equal(t, []byte("test-cert-bytes"), got.Cert)
+		assert.Equal(t, uint32(12345), got.InitiatorIndex)
+		assert.Equal(t, uint32(67890), got.ResponderIndex)
+		assert.Equal(t, uint64(1234567890), got.Time)
+		assert.Equal(t, uint32(2), got.CertVersion)
+	})
+
+	t.Run("minimal fields", func(t *testing.T) {
+		data := MarshalPayload(nil, Payload{InitiatorIndex: 1})
+
+		got, err := UnmarshalPayload(data)
+		require.NoError(t, err)
+
+		assert.Equal(t, uint32(1), got.InitiatorIndex)
+		assert.Equal(t, uint32(0), got.ResponderIndex)
+		assert.Equal(t, uint64(0), got.Time)
+		assert.Nil(t, got.Cert)
+	})
+
+	t.Run("empty payload", func(t *testing.T) {
+		data := MarshalPayload(nil, Payload{})
+
+		got, err := UnmarshalPayload(data)
+		require.NoError(t, err)
+
+		assert.Equal(t, uint32(0), got.InitiatorIndex)
+	})
+
+	t.Run("large cert bytes", func(t *testing.T) {
+		bigCert := make([]byte, 4096)
+		for i := range bigCert {
+			bigCert[i] = byte(i % 256)
+		}
+
+		data := MarshalPayload(nil, Payload{
+			Cert:           bigCert,
+			CertVersion:    2,
+			InitiatorIndex: 999,
+		})
+
+		got, err := UnmarshalPayload(data)
+		require.NoError(t, err)
+
+		assert.Equal(t, bigCert, got.Cert)
+		assert.Equal(t, uint32(999), got.InitiatorIndex)
+	})
+
+	t.Run("append to existing buffer", func(t *testing.T) {
+		prefix := []byte("prefix")
+		data := MarshalPayload(prefix, Payload{InitiatorIndex: 42})
+
+		assert.Equal(t, []byte("prefix"), data[:6])
+
+		got, err := UnmarshalPayload(data[6:])
+		require.NoError(t, err)
+		assert.Equal(t, uint32(42), got.InitiatorIndex)
+	})
+}
+
+func TestPayloadUnknownFields(t *testing.T) {
+	t.Run("unknown field in outer message is skipped", func(t *testing.T) {
+		// Marshal a normal payload then append an unknown field (field 99, varint)
+		data := MarshalPayload(nil, Payload{InitiatorIndex: 42})
+		data = protowire.AppendTag(data, 99, protowire.VarintType)
+		data = protowire.AppendVarint(data, 12345)
+
+		got, err := UnmarshalPayload(data)
+		require.NoError(t, err)
+		assert.Equal(t, uint32(42), got.InitiatorIndex)
+	})
+
+	t.Run("unknown field in details is skipped", func(t *testing.T) {
+		// Build details with a known field + unknown field
+		var details []byte
+		details = protowire.AppendTag(details, fieldInitiatorIndex, protowire.VarintType)
+		details = protowire.AppendVarint(details, 77)
+		// Unknown field 50, varint
+		details = protowire.AppendTag(details, 50, protowire.VarintType)
+		details = protowire.AppendVarint(details, 9999)
+		// Another known field after the unknown one
+		details = protowire.AppendTag(details, fieldResponderIndex, protowire.VarintType)
+		details = protowire.AppendVarint(details, 88)
+
+		// Wrap in outer message
+		var data []byte
+		data = protowire.AppendTag(data, 1, protowire.BytesType)
+		data = protowire.AppendBytes(data, details)
+
+		got, err := UnmarshalPayload(data)
+		require.NoError(t, err)
+		assert.Equal(t, uint32(77), got.InitiatorIndex)
+		assert.Equal(t, uint32(88), got.ResponderIndex)
+	})
+
+	t.Run("reserved fields 6 and 7 are skipped", func(t *testing.T) {
+		// Fields 6 and 7 are reserved in the proto definition
+		var details []byte
+		details = protowire.AppendTag(details, fieldInitiatorIndex, protowire.VarintType)
+		details = protowire.AppendVarint(details, 100)
+		details = protowire.AppendTag(details, 6, protowire.VarintType)
+		details = protowire.AppendVarint(details, 1)
+		details = protowire.AppendTag(details, 7, protowire.VarintType)
+		details = protowire.AppendVarint(details, 2)
+
+		var data []byte
+		data = protowire.AppendTag(data, 1, protowire.BytesType)
+		data = protowire.AppendBytes(data, details)
+
+		got, err := UnmarshalPayload(data)
+		require.NoError(t, err)
+		assert.Equal(t, uint32(100), got.InitiatorIndex)
+	})
+}
+
+func TestPayloadBytesConsumed(t *testing.T) {
+	t.Run("all bytes consumed on valid input", func(t *testing.T) {
+		original := Payload{
+			Cert:           []byte("cert"),
+			CertVersion:    2,
+			InitiatorIndex: 100,
+			ResponderIndex: 200,
+			Time:           999,
+		}
+		data := MarshalPayload(nil, original)
+
+		got, err := UnmarshalPayload(data)
+		require.NoError(t, err)
+
+		// Re-marshal and compare — proves we consumed and reproduced all fields
+		remarshaled := MarshalPayload(nil, got)
+		assert.Equal(t, data, remarshaled)
+	})
+}
+
+// wrapDetails wraps raw detail bytes in the outer NebulaHandshake envelope
+// so UnmarshalPayload can reach unmarshalPayloadDetails.
+func wrapDetails(details []byte) []byte {
+	var out []byte
+	out = protowire.AppendTag(out, 1, protowire.BytesType)
+	out = protowire.AppendBytes(out, details)
+	return out
+}
+
+func TestPayloadUnmarshalErrors(t *testing.T) {
+	t.Run("nil input", func(t *testing.T) {
+		got, err := UnmarshalPayload(nil)
+		require.NoError(t, err)
+		assert.Equal(t, uint32(0), got.InitiatorIndex)
+	})
+
+	t.Run("truncated outer tag", func(t *testing.T) {
+		_, err := UnmarshalPayload([]byte{0x80})
+		assert.Error(t, err)
+	})
+
+	t.Run("truncated outer details field", func(t *testing.T) {
+		_, err := UnmarshalPayload([]byte{0x0a, 0x64, 0x01, 0x02, 0x03, 0x04, 0x05})
+		assert.Error(t, err)
+	})
+
+	t.Run("truncated outer unknown field", func(t *testing.T) {
+		// Valid tag for unknown field 99 varint, but no value follows
+		var data []byte
+		data = protowire.AppendTag(data, 99, protowire.VarintType)
+		_, err := UnmarshalPayload(data)
+		assert.Error(t, err)
+	})
+
+	t.Run("truncated details tag", func(t *testing.T) {
+		_, err := UnmarshalPayload(wrapDetails([]byte{0x80}))
+		assert.Error(t, err)
+	})
+
+	t.Run("truncated cert bytes", func(t *testing.T) {
+		// Field 1 (cert), bytes type, length 10 but only 2 bytes
+		var details []byte
+		details = protowire.AppendTag(details, fieldCert, protowire.BytesType)
+		details = append(details, 0x0a, 0x01, 0x02) // length 10, only 2 bytes
+		_, err := UnmarshalPayload(wrapDetails(details))
+		assert.Error(t, err)
+	})
+
+	t.Run("truncated initiator index varint", func(t *testing.T) {
+		var details []byte
+		details = protowire.AppendTag(details, fieldInitiatorIndex, protowire.VarintType)
+		details = append(details, 0x80) // incomplete varint
+		_, err := UnmarshalPayload(wrapDetails(details))
+		assert.Error(t, err)
+	})
+
+	t.Run("truncated responder index varint", func(t *testing.T) {
+		var details []byte
+		details = protowire.AppendTag(details, fieldResponderIndex, protowire.VarintType)
+		details = append(details, 0x80)
+		_, err := UnmarshalPayload(wrapDetails(details))
+		assert.Error(t, err)
+	})
+
+	t.Run("truncated time varint", func(t *testing.T) {
+		var details []byte
+		details = protowire.AppendTag(details, fieldTime, protowire.VarintType)
+		details = append(details, 0x80)
+		_, err := UnmarshalPayload(wrapDetails(details))
+		assert.Error(t, err)
+	})
+
+	t.Run("truncated cert version varint", func(t *testing.T) {
+		var details []byte
+		details = protowire.AppendTag(details, fieldCertVersion, protowire.VarintType)
+		details = append(details, 0x80)
+		_, err := UnmarshalPayload(wrapDetails(details))
+		assert.Error(t, err)
+	})
+
+	t.Run("truncated unknown field in details", func(t *testing.T) {
+		var details []byte
+		details = protowire.AppendTag(details, 50, protowire.VarintType)
+		details = append(details, 0x80) // incomplete varint
+		_, err := UnmarshalPayload(wrapDetails(details))
+		assert.Error(t, err)
+	})
+
+	t.Run("cert with wrong wire type rejected", func(t *testing.T) {
+		// fieldCert as Varint instead of Bytes.
+		var details []byte
+		details = protowire.AppendTag(details, fieldCert, protowire.VarintType)
+		details = protowire.AppendVarint(details, 42)
+		_, err := UnmarshalPayload(wrapDetails(details))
+		assert.Error(t, err)
+	})
+
+	t.Run("initiator index with wrong wire type rejected", func(t *testing.T) {
+		// fieldInitiatorIndex as Bytes instead of Varint.
+		var details []byte
+		details = protowire.AppendTag(details, fieldInitiatorIndex, protowire.BytesType)
+		details = protowire.AppendBytes(details, []byte{1, 2, 3})
+		_, err := UnmarshalPayload(wrapDetails(details))
+		assert.Error(t, err)
+	})
+
+	t.Run("time with wrong wire type rejected", func(t *testing.T) {
+		var details []byte
+		details = protowire.AppendTag(details, fieldTime, protowire.BytesType)
+		details = protowire.AppendBytes(details, []byte{1, 2, 3})
+		_, err := UnmarshalPayload(wrapDetails(details))
+		assert.Error(t, err)
+	})
+
+	t.Run("cert version with wrong wire type rejected", func(t *testing.T) {
+		var details []byte
+		details = protowire.AppendTag(details, fieldCertVersion, protowire.BytesType)
+		details = protowire.AppendBytes(details, []byte{1, 2, 3})
+		_, err := UnmarshalPayload(wrapDetails(details))
+		assert.Error(t, err)
+	})
+
+	t.Run("repeated singular field follows proto3 last-wins", func(t *testing.T) {
+		// Per proto3, multiple instances of a singular field are accepted and
+		// the last value wins. We keep this behavior so that peers using
+		// alternative encoders aren't rejected.
+		var details []byte
+		details = protowire.AppendTag(details, fieldInitiatorIndex, protowire.VarintType)
+		details = protowire.AppendVarint(details, 1)
+		details = protowire.AppendTag(details, fieldInitiatorIndex, protowire.VarintType)
+		details = protowire.AppendVarint(details, 42)
+		got, err := UnmarshalPayload(wrapDetails(details))
+		require.NoError(t, err)
+		assert.Equal(t, uint32(42), got.InitiatorIndex)
+	})
+
+	t.Run("initiator index varint overflow rejected", func(t *testing.T) {
+		var details []byte
+		details = protowire.AppendTag(details, fieldInitiatorIndex, protowire.VarintType)
+		details = protowire.AppendVarint(details, math.MaxUint32+1)
+		_, err := UnmarshalPayload(wrapDetails(details))
+		assert.Error(t, err)
+	})
+
+	t.Run("cert version varint overflow rejected", func(t *testing.T) {
+		var details []byte
+		details = protowire.AppendTag(details, fieldCertVersion, protowire.VarintType)
+		details = protowire.AppendVarint(details, math.MaxUint32+1)
+		_, err := UnmarshalPayload(wrapDetails(details))
+		assert.Error(t, err)
+	})
+
+}
+
+// FuzzPayload feeds arbitrary bytes through UnmarshalPayload to confirm it
+// never panics, and for any input that parses cleanly, that re-marshal +
+// re-parse is a fix-point. Inputs come from an authenticated peer (post-
+// noise-decrypt), so the threat model is "valid peer behaving arbitrarily,"
+// not "unauthenticated injection."
+func FuzzPayload(f *testing.F) {
+	// Seed corpus with a handful of known-good shapes.
+	f.Add(MarshalPayload(nil, Payload{}))
+	f.Add(MarshalPayload(nil, Payload{Cert: []byte{1, 2, 3}, CertVersion: 2}))
+	f.Add(MarshalPayload(nil, Payload{InitiatorIndex: 42, Time: 1}))
+	f.Add(MarshalPayload(nil, Payload{
+		Cert:           []byte("seed-cert"),
+		InitiatorIndex: 1,
+		ResponderIndex: 2,
+		Time:           3,
+		CertVersion:    2,
+	}))
+	f.Add([]byte{})
+	f.Add([]byte{0xff})
+
+	f.Fuzz(func(t *testing.T, data []byte) {
+		p1, err := UnmarshalPayload(data)
+		if err != nil {
+			return
+		}
+
+		// For any input that parses, re-marshaling and re-parsing must
+		// yield an equivalent Payload. This catches dispatch bugs (e.g.
+		// emitting a field on marshal that we don't accept on parse) and
+		// any non-idempotent parsing behavior.
+		b2 := MarshalPayload(nil, p1)
+		p2, err := UnmarshalPayload(b2)
+		if err != nil {
+			t.Fatalf("re-parse of self-marshaled payload failed: %v\nintermediate: %x\n", err, b2)
+		}
+		if !payloadsEqual(p1, p2) {
+			t.Fatalf("re-marshal not idempotent\nfirst:  %+v\nsecond: %+v", p1, p2)
+		}
+	})
+}
+
+func payloadsEqual(a, b Payload) bool {
+	return bytes.Equal(a.Cert, b.Cert) &&
+		a.InitiatorIndex == b.InitiatorIndex &&
+		a.ResponderIndex == b.ResponderIndex &&
+		a.Time == b.Time &&
+		a.CertVersion == b.CertVersion
+}

handshake_ix.go

@@ -1,813 +0,0 @@
-package nebula
-
-import (
-	"bytes"
-	"context"
-	"log/slog"
-	"net/netip"
-	"time"
-
-	"github.com/flynn/noise"
-	"github.com/slackhq/nebula/cert"
-	"github.com/slackhq/nebula/header"
-)
-
-// NOISE IX Handshakes
-
-// This function constructs a handshake packet, but does not actually send it
-// Sending is done by the handshake manager
-func ixHandshakeStage0(f *Interface, hh *HandshakeHostInfo) bool {
-	err := f.handshakeManager.allocateIndex(hh)
-	if err != nil {
-		f.l.Error("Failed to generate index",
-			"error", err,
-			"vpnAddrs", hh.hostinfo.vpnAddrs,
-			"handshake", m{"stage": 0, "style": "ix_psk0"},
-		)
-		return false
-	}
-
-	cs := f.pki.getCertState()
-	v := cs.initiatingVersion
-	if hh.initiatingVersionOverride != cert.VersionPre1 {
-		v = hh.initiatingVersionOverride
-	} else if v < cert.Version2 {
-		// If we're connecting to a v6 address we should encourage use of a V2 cert
-		for _, a := range hh.hostinfo.vpnAddrs {
-			if a.Is6() {
-				v = cert.Version2
-				break
-			}
-		}
-	}
-
-	crt := cs.getCertificate(v)
-	if crt == nil {
-		f.l.Error("Unable to handshake with host because no certificate is available",
-			"vpnAddrs", hh.hostinfo.vpnAddrs,
-			"handshake", m{"stage": 0, "style": "ix_psk0"},
-			"certVersion", v,
-		)
-		return false
-	}
-
-	crtHs := cs.getHandshakeBytes(v)
-	if crtHs == nil {
-		f.l.Error("Unable to handshake with host because no certificate handshake bytes is available",
-			"vpnAddrs", hh.hostinfo.vpnAddrs,
-			"handshake", m{"stage": 0, "style": "ix_psk0"},
-			"certVersion", v,
-		)
-		return false
-	}
-
-	ci, err := NewConnectionState(cs, crt, true, noise.HandshakeIX)
-	if err != nil {
-		f.l.Error("Failed to create connection state",
-			"error", err,
-			"vpnAddrs", hh.hostinfo.vpnAddrs,
-			"handshake", m{"stage": 0, "style": "ix_psk0"},
-			"certVersion", v,
-		)
-		return false
-	}
-	hh.hostinfo.ConnectionState = ci
-
-	hs := &NebulaHandshake{
-		Details: &NebulaHandshakeDetails{
-			InitiatorIndex: hh.hostinfo.localIndexId,
-			Time:           uint64(time.Now().UnixNano()),
-			Cert:           crtHs,
-			CertVersion:    uint32(v),
-		},
-	}
-
-	hsBytes, err := hs.Marshal()
-	if err != nil {
-		f.l.Error("Failed to marshal handshake message",
-			"error", err,
-			"vpnAddrs", hh.hostinfo.vpnAddrs,
-			"certVersion", v,
-			"handshake", m{"stage": 0, "style": "ix_psk0"},
-		)
-		return false
-	}
-
-	h := header.Encode(make([]byte, header.Len), header.Version, header.Handshake, header.HandshakeIXPSK0, 0, 1)
-
-	msg, _, _, err := ci.H.WriteMessage(h, hsBytes)
-	if err != nil {
-		f.l.Error("Failed to call noise.WriteMessage",
-			"error", err,
-			"vpnAddrs", hh.hostinfo.vpnAddrs,
-			"handshake", m{"stage": 0, "style": "ix_psk0"},
-		)
-		return false
-	}
-
-	// We are sending handshake packet 1, so we don't expect to receive
-	// handshake packet 1 from the responder
-	ci.window.Update(f.l, 1)
-
-	hh.hostinfo.HandshakePacket[0] = msg
-	hh.ready = true
-	return true
-}
-
-func ixHandshakeStage1(f *Interface, via ViaSender, packet []byte, h *header.H) {
-	cs := f.pki.getCertState()
-	crt := cs.GetDefaultCertificate()
-	if crt == nil {
-		f.l.Error("Unable to handshake with host because no certificate is available",
-			"from", via,
-			"handshake", m{"stage": 0, "style": "ix_psk0"},
-			"certVersion", cs.initiatingVersion,
-		)
-		return
-	}
-
-	ci, err := NewConnectionState(cs, crt, false, noise.HandshakeIX)
-	if err != nil {
-		f.l.Error("Failed to create connection state",
-			"error", err,
-			"from", via,
-			"handshake", m{"stage": 1, "style": "ix_psk0"},
-		)
-		return
-	}
-
-	// Mark packet 1 as seen so it doesn't show up as missed
-	ci.window.Update(f.l, 1)
-
-	msg, _, _, err := ci.H.ReadMessage(nil, packet[header.Len:])
-	if err != nil {
-		f.l.Error("Failed to call noise.ReadMessage",
-			"error", err,
-			"from", via,
-			"handshake", m{"stage": 1, "style": "ix_psk0"},
-		)
-		return
-	}
-
-	hs := &NebulaHandshake{}
-	err = hs.Unmarshal(msg)
-	if err != nil || hs.Details == nil {
-		f.l.Error("Failed unmarshal handshake message",
-			"error", err,
-			"from", via,
-			"handshake", m{"stage": 1, "style": "ix_psk0"},
-		)
-		return
-	}
-
-	rc, err := cert.Recombine(cert.Version(hs.Details.CertVersion), hs.Details.Cert, ci.H.PeerStatic(), ci.Curve())
-	if err != nil {
-		f.l.Info("Handshake did not contain a certificate",
-			"error", err,
-			"from", via,
-			"handshake", m{"stage": 1, "style": "ix_psk0"},
-		)
-		return
-	}
-
-	remoteCert, err := f.pki.GetCAPool().VerifyCertificate(time.Now(), rc)
-	if err != nil {
-		fp, fperr := rc.Fingerprint()
-		if fperr != nil {
-			fp = "<error generating certificate fingerprint>"
-		}
-
-		attrs := []slog.Attr{
-			slog.Any("error", err),
-			slog.Any("from", via),
-			slog.Any("handshake", m{"stage": 1, "style": "ix_psk0"}),
-			slog.Any("certVpnNetworks", rc.Networks()),
-			slog.String("certFingerprint", fp),
-		}
-		if f.l.Enabled(context.Background(), slog.LevelDebug) {
-			attrs = append(attrs, slog.Any("cert", rc))
-		}
-
-		// LogAttrs is intentional: attrs is a pre-built []slog.Attr slice that
-		// callers grow conditionally, which has no pair-form equivalent.
-		//nolint:sloglint
-		f.l.LogAttrs(context.Background(), slog.LevelInfo, "Invalid certificate from host", attrs...)
-		return
-	}
-
-	if !bytes.Equal(remoteCert.Certificate.PublicKey(), ci.H.PeerStatic()) {
-		f.l.Info("public key mismatch between certificate and handshake",
-			"from", via,
-			"handshake", m{"stage": 1, "style": "ix_psk0"},
-			"cert", remoteCert,
-		)
-		return
-	}
-
-	if remoteCert.Certificate.Version() != ci.myCert.Version() {
-		// We started off using the wrong certificate version, lets see if we can match the version that was sent to us
-		myCertOtherVersion := cs.getCertificate(remoteCert.Certificate.Version())
-		if myCertOtherVersion == nil {
-			if f.l.Enabled(context.Background(), slog.LevelDebug) {
-				f.l.Debug("Might be unable to handshake with host due to missing certificate version",
-					"error", err,
-					"from", via,
-					"handshake", m{"stage": 1, "style": "ix_psk0"},
-					"cert", remoteCert,
-				)
-			}
-		} else {
-			// Record the certificate we are actually using
-			ci.myCert = myCertOtherVersion
-		}
-	}
-
-	if len(remoteCert.Certificate.Networks()) == 0 {
-		f.l.Info("No networks in certificate",
-			"error", err,
-			"from", via,
-			"cert", remoteCert,
-			"handshake", m{"stage": 1, "style": "ix_psk0"},
-		)
-		return
-	}
-
-	certName := remoteCert.Certificate.Name()
-	certVersion := remoteCert.Certificate.Version()
-	fingerprint := remoteCert.Fingerprint
-	issuer := remoteCert.Certificate.Issuer()
-	vpnNetworks := remoteCert.Certificate.Networks()
-
-	anyVpnAddrsInCommon := false
-	vpnAddrs := make([]netip.Addr, len(vpnNetworks))
-	for i, network := range vpnNetworks {
-		if f.myVpnAddrsTable.Contains(network.Addr()) {
-			f.l.Error("Refusing to handshake with myself",
-				"vpnNetworks", vpnNetworks,
-				"from", via,
-				"certName", certName,
-				"certVersion", certVersion,
-				"fingerprint", fingerprint,
-				"issuer", issuer,
-				"handshake", m{"stage": 1, "style": "ix_psk0"},
-			)
-			return
-		}
-		vpnAddrs[i] = network.Addr()
-		if f.myVpnNetworksTable.Contains(network.Addr()) {
-			anyVpnAddrsInCommon = true
-		}
-	}
-
-	if !via.IsRelayed {
-		// We only want to apply the remote allow list for direct tunnels here
-		if !f.lightHouse.GetRemoteAllowList().AllowAll(vpnAddrs, via.UdpAddr.Addr()) {
-			if f.l.Enabled(context.Background(), slog.LevelDebug) {
-				f.l.Debug("lighthouse.remote_allow_list denied incoming handshake",
-					"vpnAddrs", vpnAddrs,
-					"from", via,
-				)
-			}
-			return
-		}
-	}
-
-	myIndex, err := generateIndex(f.l)
-	if err != nil {
-		f.l.Error("Failed to generate index",
-			"error", err,
-			"vpnAddrs", vpnAddrs,
-			"from", via,
-			"certName", certName,
-			"certVersion", certVersion,
-			"fingerprint", fingerprint,
-			"issuer", issuer,
-			"handshake", m{"stage": 1, "style": "ix_psk0"},
-		)
-		return
-	}
-
-	hostinfo := &HostInfo{
-		ConnectionState:   ci,
-		localIndexId:      myIndex,
-		remoteIndexId:     hs.Details.InitiatorIndex,
-		vpnAddrs:          vpnAddrs,
-		HandshakePacket:   make(map[uint8][]byte, 0),
-		lastHandshakeTime: hs.Details.Time,
-		relayState: RelayState{
-			relays:         nil,
-			relayForByAddr: map[netip.Addr]*Relay{},
-			relayForByIdx:  map[uint32]*Relay{},
-		},
-	}
-
-	msgRxL := f.l.With(
-		"vpnAddrs", vpnAddrs,
-		"from", via,
-		"certName", certName,
-		"certVersion", certVersion,
-		"fingerprint", fingerprint,
-		"issuer", issuer,
-		"initiatorIndex", hs.Details.InitiatorIndex,
-		"responderIndex", hs.Details.ResponderIndex,
-		"remoteIndex", h.RemoteIndex,
-		"handshake", m{"stage": 1, "style": "ix_psk0"},
-	)
-
-	if anyVpnAddrsInCommon {
-		msgRxL.Info("Handshake message received")
-	} else {
-		//todo warn if not lighthouse or relay?
-		msgRxL.Info("Handshake message received, but no vpnNetworks in common.")
-	}
-
-	hs.Details.ResponderIndex = myIndex
-	hs.Details.Cert = cs.getHandshakeBytes(ci.myCert.Version())
-	if hs.Details.Cert == nil {
-		msgRxL.Error("Unable to handshake with host because no certificate handshake bytes is available",
-			"myCertVersion", ci.myCert.Version(),
-		)
-		return
-	}
-
-	hs.Details.CertVersion = uint32(ci.myCert.Version())
-	// Update the time in case their clock is way off from ours
-	hs.Details.Time = uint64(time.Now().UnixNano())
-
-	hsBytes, err := hs.Marshal()
-	if err != nil {
-		f.l.Error("Failed to marshal handshake message",
-			"error", err,
-			"vpnAddrs", hostinfo.vpnAddrs,
-			"from", via,
-			"certName", certName,
-			"certVersion", certVersion,
-			"fingerprint", fingerprint,
-			"issuer", issuer,
-			"handshake", m{"stage": 1, "style": "ix_psk0"},
-		)
-		return
-	}
-
-	nh := header.Encode(make([]byte, header.Len), header.Version, header.Handshake, header.HandshakeIXPSK0, hs.Details.InitiatorIndex, 2)
-	msg, dKey, eKey, err := ci.H.WriteMessage(nh, hsBytes)
-	if err != nil {
-		f.l.Error("Failed to call noise.WriteMessage",
-			"error", err,
-			"vpnAddrs", hostinfo.vpnAddrs,
-			"from", via,
-			"certName", certName,
-			"certVersion", certVersion,
-			"fingerprint", fingerprint,
-			"issuer", issuer,
-			"handshake", m{"stage": 1, "style": "ix_psk0"},
-		)
-		return
-	} else if dKey == nil || eKey == nil {
-		f.l.Error("Noise did not arrive at a key",
-			"vpnAddrs", hostinfo.vpnAddrs,
-			"from", via,
-			"certName", certName,
-			"certVersion", certVersion,
-			"fingerprint", fingerprint,
-			"issuer", issuer,
-			"handshake", m{"stage": 1, "style": "ix_psk0"},
-		)
-		return
-	}
-
-	hostinfo.HandshakePacket[0] = make([]byte, len(packet[header.Len:]))
-	copy(hostinfo.HandshakePacket[0], packet[header.Len:])
-
-	// Regardless of whether you are the sender or receiver, you should arrive here
-	// and complete standing up the connection.
-	hostinfo.HandshakePacket[2] = make([]byte, len(msg))
-	copy(hostinfo.HandshakePacket[2], msg)
-
-	// We are sending handshake packet 2, so we don't expect to receive
-	// handshake packet 2 from the initiator.
-	ci.window.Update(f.l, 2)
-
-	ci.peerCert = remoteCert
-	ci.dKey = NewNebulaCipherState(dKey)
-	ci.eKey = NewNebulaCipherState(eKey)
-
-	hostinfo.remotes = f.lightHouse.QueryCache(vpnAddrs)
-	if !via.IsRelayed {
-		hostinfo.SetRemote(via.UdpAddr)
-	}
-	hostinfo.buildNetworks(f.myVpnNetworksTable, remoteCert.Certificate)
-
-	existing, err := f.handshakeManager.CheckAndComplete(hostinfo, 0, f)
-	if err != nil {
-		switch err {
-		case ErrAlreadySeen:
-			// Update remote if preferred
-			if existing.SetRemoteIfPreferred(f.hostMap, via) {
-				// Send a test packet to ensure the other side has also switched to
-				// the preferred remote
-				f.SendMessageToVpnAddr(header.Test, header.TestRequest, vpnAddrs[0], []byte(""), make([]byte, 12, 12), make([]byte, mtu))
-			}
-
-			msg = existing.HandshakePacket[2]
-			f.messageMetrics.Tx(header.Handshake, header.MessageSubType(msg[1]), 1)
-			if !via.IsRelayed {
-				err := f.outside.WriteTo(msg, via.UdpAddr)
-				if err != nil {
-					f.l.Error("Failed to send handshake message",
-						"vpnAddrs", existing.vpnAddrs,
-						"from", via,
-						"handshake", m{"stage": 2, "style": "ix_psk0"},
-						"cached", true,
-						"error", err,
-					)
-				} else {
-					f.l.Info("Handshake message sent",
-						"vpnAddrs", existing.vpnAddrs,
-						"from", via,
-						"handshake", m{"stage": 2, "style": "ix_psk0"},
-						"cached", true,
-					)
-				}
-				return
-			} else {
-				if via.relay == nil {
-					f.l.Error("Handshake send failed: both addr and via.relay are nil.")
-					return
-				}
-				hostinfo.relayState.InsertRelayTo(via.relayHI.vpnAddrs[0])
-				f.SendVia(via.relayHI, via.relay, msg, make([]byte, 12), make([]byte, mtu), false)
-				f.l.Info("Handshake message sent",
-					"vpnAddrs", existing.vpnAddrs,
-					"relay", via.relayHI.vpnAddrs[0],
-					"handshake", m{"stage": 2, "style": "ix_psk0"},
-					"cached", true,
-				)
-				return
-			}
-		case ErrExistingHostInfo:
-			// This means there was an existing tunnel and this handshake was older than the one we are currently based on
-			f.l.Info("Handshake too old",
-				"vpnAddrs", vpnAddrs,
-				"from", via,
-				"certName", certName,
-				"certVersion", certVersion,
-				"oldHandshakeTime", existing.lastHandshakeTime,
-				"newHandshakeTime", hostinfo.lastHandshakeTime,
-				"fingerprint", fingerprint,
-				"issuer", issuer,
-				"initiatorIndex", hs.Details.InitiatorIndex,
-				"responderIndex", hs.Details.ResponderIndex,
-				"remoteIndex", h.RemoteIndex,
-				"handshake", m{"stage": 1, "style": "ix_psk0"},
-			)
-
-			// Send a test packet to trigger an authenticated tunnel test, this should suss out any lingering tunnel issues
-			f.SendMessageToVpnAddr(header.Test, header.TestRequest, vpnAddrs[0], []byte(""), make([]byte, 12, 12), make([]byte, mtu))
-			return
-		case ErrLocalIndexCollision:
-			// This means we failed to insert because of collision on localIndexId. Just let the next handshake packet retry
-			f.l.Error("Failed to add HostInfo due to localIndex collision",
-				"vpnAddrs", vpnAddrs,
-				"from", via,
-				"certName", certName,
-				"certVersion", certVersion,
-				"fingerprint", fingerprint,
-				"issuer", issuer,
-				"initiatorIndex", hs.Details.InitiatorIndex,
-				"responderIndex", hs.Details.ResponderIndex,
-				"remoteIndex", h.RemoteIndex,
-				"handshake", m{"stage": 1, "style": "ix_psk0"},
-				"localIndex", hostinfo.localIndexId,
-				"collision", existing.vpnAddrs,
-			)
-			return
-		default:
-			// Shouldn't happen, but just in case someone adds a new error type to CheckAndComplete
-			// And we forget to update it here
-			f.l.Error("Failed to add HostInfo to HostMap",
-				"error", err,
-				"vpnAddrs", vpnAddrs,
-				"from", via,
-				"certName", certName,
-				"certVersion", certVersion,
-				"fingerprint", fingerprint,
-				"issuer", issuer,
-				"initiatorIndex", hs.Details.InitiatorIndex,
-				"responderIndex", hs.Details.ResponderIndex,
-				"remoteIndex", h.RemoteIndex,
-				"handshake", m{"stage": 1, "style": "ix_psk0"},
-			)
-			return
-		}
-	}
-
-	// Do the send
-	f.messageMetrics.Tx(header.Handshake, header.MessageSubType(msg[1]), 1)
-	if !via.IsRelayed {
-		err = f.outside.WriteTo(msg, via.UdpAddr)
-		log := f.l.With(
-			"vpnAddrs", vpnAddrs,
-			"from", via,
-			"certName", certName,
-			"certVersion", certVersion,
-			"fingerprint", fingerprint,
-			"issuer", issuer,
-			"initiatorIndex", hs.Details.InitiatorIndex,
-			"responderIndex", hs.Details.ResponderIndex,
-			"remoteIndex", h.RemoteIndex,
-			"handshake", m{"stage": 2, "style": "ix_psk0"},
-		)
-		if err != nil {
-			log.Error("Failed to send handshake", "error", err)
-		} else {
-			log.Info("Handshake message sent")
-		}
-	} else {
-		if via.relay == nil {
-			f.l.Error("Handshake send failed: both addr and via.relay are nil.")
-			return
-		}
-		hostinfo.relayState.InsertRelayTo(via.relayHI.vpnAddrs[0])
-		// I successfully received a handshake. Just in case I marked this tunnel as 'Disestablished', ensure
-		// it's correctly marked as working.
-		via.relayHI.relayState.UpdateRelayForByIdxState(via.remoteIdx, Established)
-		f.SendVia(via.relayHI, via.relay, msg, make([]byte, 12), make([]byte, mtu), false)
-		f.l.Info("Handshake message sent",
-			"vpnAddrs", vpnAddrs,
-			"relay", via.relayHI.vpnAddrs[0],
-			"certName", certName,
-			"certVersion", certVersion,
-			"fingerprint", fingerprint,
-			"issuer", issuer,
-			"initiatorIndex", hs.Details.InitiatorIndex,
-			"responderIndex", hs.Details.ResponderIndex,
-			"remoteIndex", h.RemoteIndex,
-			"handshake", m{"stage": 2, "style": "ix_psk0"},
-		)
-	}
-
-	f.connectionManager.AddTrafficWatch(hostinfo)
-
-	hostinfo.remotes.RefreshFromHandshake(vpnAddrs)
-
-	// Don't wait for UpdateWorker
-	if f.lightHouse.IsAnyLighthouseAddr(vpnAddrs) {
-		f.lightHouse.TriggerUpdate()
-	}
-
-	return
-}
-
-func ixHandshakeStage2(f *Interface, via ViaSender, hh *HandshakeHostInfo, packet []byte, h *header.H) bool {
-	if hh == nil {
-		// Nothing here to tear down, got a bogus stage 2 packet
-		return true
-	}
-
-	hh.Lock()
-	defer hh.Unlock()
-
-	hostinfo := hh.hostinfo
-	if !via.IsRelayed {
-		// The vpnAddr we know about is the one we tried to handshake with, use it to apply the remote allow list.
-		if !f.lightHouse.GetRemoteAllowList().AllowAll(hostinfo.vpnAddrs, via.UdpAddr.Addr()) {
-			if f.l.Enabled(context.Background(), slog.LevelDebug) {
-				f.l.Debug("lighthouse.remote_allow_list denied incoming handshake",
-					"vpnAddrs", hostinfo.vpnAddrs,
-					"from", via,
-				)
-			}
-			return false
-		}
-	}
-
-	ci := hostinfo.ConnectionState
-	msg, eKey, dKey, err := ci.H.ReadMessage(nil, packet[header.Len:])
-	if err != nil {
-		f.l.Error("Failed to call noise.ReadMessage",
-			"error", err,
-			"vpnAddrs", hostinfo.vpnAddrs,
-			"from", via,
-			"handshake", m{"stage": 2, "style": "ix_psk0"},
-			"header", h,
-		)
-
-		// We don't want to tear down the connection on a bad ReadMessage because it could be an attacker trying
-		// to DOS us. Every other error condition after should to allow a possible good handshake to complete in the
-		// near future
-		return false
-	} else if dKey == nil || eKey == nil {
-		f.l.Error("Noise did not arrive at a key",
-			"vpnAddrs", hostinfo.vpnAddrs,
-			"from", via,
-			"handshake", m{"stage": 2, "style": "ix_psk0"},
-		)
-
-		// This should be impossible in IX but just in case, if we get here then there is no chance to recover
-		// the handshake state machine. Tear it down
-		return true
-	}
-
-	hs := &NebulaHandshake{}
-	err = hs.Unmarshal(msg)
-	if err != nil || hs.Details == nil {
-		f.l.Error("Failed unmarshal handshake message",
-			"error", err,
-			"vpnAddrs", hostinfo.vpnAddrs,
-			"from", via,
-			"handshake", m{"stage": 2, "style": "ix_psk0"},
-		)
-
-		// The handshake state machine is complete, if things break now there is no chance to recover. Tear down and start again
-		return true
-	}
-
-	rc, err := cert.Recombine(cert.Version(hs.Details.CertVersion), hs.Details.Cert, ci.H.PeerStatic(), ci.Curve())
-	if err != nil {
-		f.l.Info("Handshake did not contain a certificate",
-			"error", err,
-			"from", via,
-			"vpnAddrs", hostinfo.vpnAddrs,
-			"handshake", m{"stage": 2, "style": "ix_psk0"},
-		)
-		return true
-	}
-
-	remoteCert, err := f.pki.GetCAPool().VerifyCertificate(time.Now(), rc)
-	if err != nil {
-		fp, err := rc.Fingerprint()
-		if err != nil {
-			fp = "<error generating certificate fingerprint>"
-		}
-
-		attrs := []slog.Attr{
-			slog.Any("error", err),
-			slog.Any("from", via),
-			slog.Any("vpnAddrs", hostinfo.vpnAddrs),
-			slog.Any("handshake", m{"stage": 2, "style": "ix_psk0"}),
-			slog.String("certFingerprint", fp),
-			slog.Any("certVpnNetworks", rc.Networks()),
-		}
-		if f.l.Enabled(context.Background(), slog.LevelDebug) {
-			attrs = append(attrs, slog.Any("cert", rc))
-		}
-
-		// LogAttrs is intentional: attrs is a pre-built []slog.Attr slice that
-		// callers grow conditionally, which has no pair-form equivalent.
-		//nolint:sloglint
-		f.l.LogAttrs(context.Background(), slog.LevelInfo, "Invalid certificate from host", attrs...)
-		return true
-	}
-	if !bytes.Equal(remoteCert.Certificate.PublicKey(), ci.H.PeerStatic()) {
-		f.l.Info("public key mismatch between certificate and handshake",
-			"from", via,
-			"handshake", m{"stage": 2, "style": "ix_psk0"},
-			"cert", remoteCert,
-		)
-		return true
-	}
-
-	if len(remoteCert.Certificate.Networks()) == 0 {
-		f.l.Info("No networks in certificate",
-			"error", err,
-			"from", via,
-			"vpnAddrs", hostinfo.vpnAddrs,
-			"cert", remoteCert,
-			"handshake", m{"stage": 2, "style": "ix_psk0"},
-		)
-		return true
-	}
-
-	vpnNetworks := remoteCert.Certificate.Networks()
-	certName := remoteCert.Certificate.Name()
-	certVersion := remoteCert.Certificate.Version()
-	fingerprint := remoteCert.Fingerprint
-	issuer := remoteCert.Certificate.Issuer()
-
-	hostinfo.remoteIndexId = hs.Details.ResponderIndex
-	hostinfo.lastHandshakeTime = hs.Details.Time
-
-	// Store their cert and our symmetric keys
-	ci.peerCert = remoteCert
-	ci.dKey = NewNebulaCipherState(dKey)
-	ci.eKey = NewNebulaCipherState(eKey)
-
-	// Make sure the current udpAddr being used is set for responding
-	if !via.IsRelayed {
-		hostinfo.SetRemote(via.UdpAddr)
-	} else {
-		hostinfo.relayState.InsertRelayTo(via.relayHI.vpnAddrs[0])
-	}
-
-	correctHostResponded := false
-	anyVpnAddrsInCommon := false
-	vpnAddrs := make([]netip.Addr, len(vpnNetworks))
-	for i, network := range vpnNetworks {
-		vpnAddrs[i] = network.Addr()
-		if f.myVpnNetworksTable.Contains(network.Addr()) {
-			anyVpnAddrsInCommon = true
-		}
-		if hostinfo.vpnAddrs[0] == network.Addr() {
-			// todo is it more correct to see if any of hostinfo.vpnAddrs are in the cert? it should have len==1, but one day it might not?
-			correctHostResponded = true
-		}
-	}
-
-	// Ensure the right host responded
-	if !correctHostResponded {
-		f.l.Info("Incorrect host responded to handshake",
-			"intendedVpnAddrs", hostinfo.vpnAddrs,
-			"haveVpnNetworks", vpnNetworks,
-			"from", via,
-			"certName", certName,
-			"certVersion", certVersion,
-			"handshake", m{"stage": 2, "style": "ix_psk0"},
-		)
-
-		// Release our old handshake from pending, it should not continue
-		f.handshakeManager.DeleteHostInfo(hostinfo)
-
-		// Create a new hostinfo/handshake for the intended vpn ip
-		//TODO is hostinfo.vpnAddrs[0] always the address to use?
-		f.handshakeManager.StartHandshake(hostinfo.vpnAddrs[0], func(newHH *HandshakeHostInfo) {
-			// Block the current used address
-			newHH.hostinfo.remotes = hostinfo.remotes
-			newHH.hostinfo.remotes.BlockRemote(via)
-
-			f.l.Info("Blocked addresses for handshakes",
-				"blockedUdpAddrs", newHH.hostinfo.remotes.CopyBlockedRemotes(),
-				"vpnNetworks", vpnNetworks,
-				"remotes", newHH.hostinfo.remotes.CopyAddrs(f.hostMap.GetPreferredRanges()),
-			)
-
-			// Swap the packet store to benefit the original intended recipient
-			newHH.packetStore = hh.packetStore
-			hh.packetStore = []*cachedPacket{}
-
-			// Finally, put the correct vpn addrs in the host info, tell them to close the tunnel, and return true to tear down
-			hostinfo.vpnAddrs = vpnAddrs
-			f.sendCloseTunnel(hostinfo)
-		})
-
-		return true
-	}
-
-	// Mark packet 2 as seen so it doesn't show up as missed
-	ci.window.Update(f.l, 2)
-
-	duration := time.Since(hh.startTime).Nanoseconds()
-	msgRxL := f.l.With(
-		"vpnAddrs", vpnAddrs,
-		"from", via,
-		"certName", certName,
-		"certVersion", certVersion,
-		"fingerprint", fingerprint,
-		"issuer", issuer,
-		"initiatorIndex", hs.Details.InitiatorIndex,
-		"responderIndex", hs.Details.ResponderIndex,
-		"remoteIndex", h.RemoteIndex,
-		"handshake", m{"stage": 2, "style": "ix_psk0"},
-		"durationNs", duration,
-		"sentCachedPackets", len(hh.packetStore),
-	)
-	if anyVpnAddrsInCommon {
-		msgRxL.Info("Handshake message received")
-	} else {
-		//todo warn if not lighthouse or relay?
-		msgRxL.Info("Handshake message received, but no vpnNetworks in common.")
-	}
-
-	// Build up the radix for the firewall if we have subnets in the cert
-	hostinfo.vpnAddrs = vpnAddrs
-	hostinfo.buildNetworks(f.myVpnNetworksTable, remoteCert.Certificate)
-
-	// Complete our handshake and update metrics, this will replace any existing tunnels for the vpnAddrs here
-	f.handshakeManager.Complete(hostinfo, f)
-	f.connectionManager.AddTrafficWatch(hostinfo)
-
-	if f.l.Enabled(context.Background(), slog.LevelDebug) {
-		hostinfo.logger(f.l).Debug("Sending stored packets",
-			"count", len(hh.packetStore),
-		)
-	}
-
-	if len(hh.packetStore) > 0 {
-		nb := make([]byte, 12, 12)
-		out := make([]byte, mtu)
-		for _, cp := range hh.packetStore {
-			cp.callback(cp.messageType, cp.messageSubType, hostinfo, cp.packet, nb, out)
-		}
-		f.cachedPacketMetrics.sent.Inc(int64(len(hh.packetStore)))
-	}
-
-	hostinfo.remotes.RefreshFromHandshake(vpnAddrs)
-	f.metricHandshakes.Update(duration)
-
-	// Don't wait for UpdateWorker
-	if f.lightHouse.IsAnyLighthouseAddr(vpnAddrs) {
-		f.lightHouse.TriggerUpdate()
-	}
-
-	return false
-}

handshake_manager.go

@@ -14,6 +14,7 @@ import (
 
 	"github.com/rcrowley/go-metrics"
 	"github.com/slackhq/nebula/cert"
+	"github.com/slackhq/nebula/handshake"
 	"github.com/slackhq/nebula/header"
 	"github.com/slackhq/nebula/udp"
 )
@@ -22,7 +23,18 @@ const (
 	DefaultHandshakeTryInterval   = time.Millisecond * 100
 	DefaultHandshakeRetries       = 10
 	DefaultHandshakeTriggerBuffer = 64
-	DefaultUseRelays              = true
+
+	// maxCachedPackets is how many unsent packets we'll buffer per pending
+	// handshake before dropping further ones.
+	maxCachedPackets = 100
+
+	// HandshakePacket map keys mirror the IX protocol stage convention:
+	//   stage 0 = the initiator's first message (and what the responder
+	//             receives, stripped of header)
+	//   stage 2 = the responder's reply
+	// Other handshake patterns will need new keys when added.
+	handshakePacketStage0 uint8 = 0
+	handshakePacketStage2 uint8 = 2
 )
 
 var (
@@ -30,7 +42,6 @@ var (
 		tryInterval:   DefaultHandshakeTryInterval,
 		retries:       DefaultHandshakeRetries,
 		triggerBuffer: DefaultHandshakeTriggerBuffer,
-		useRelays:     DefaultUseRelays,
 	}
 )
 
@@ -38,7 +49,6 @@ type HandshakeConfig struct {
 	tryInterval   time.Duration
 	retries       int64
 	triggerBuffer int
-	useRelays     bool
 
 	messageMetrics *MessageMetrics
 }
@@ -76,10 +86,11 @@ type HandshakeHostInfo struct {
 	packetStore               []*cachedPacket  // A set of packets to be transmitted once the handshake completes
 
 	hostinfo *HostInfo
+	machine  *handshake.Machine // The handshake state machine, set during stage 0 (initiator) or beginHandshake (responder multi-message)
 }
 
 func (hh *HandshakeHostInfo) cachePacket(l *slog.Logger, t header.MessageType, st header.MessageSubType, packet []byte, f packetCallback, m *cachedPacketMetrics) {
-	if len(hh.packetStore) < 100 {
+	if len(hh.packetStore) < maxCachedPackets {
 		tempPacket := make([]byte, len(packet))
 		copy(tempPacket, packet)
 
@@ -137,6 +148,18 @@ func (hm *HandshakeManager) Run(ctx context.Context) {
 }
 
 func (hm *HandshakeManager) HandleIncoming(via ViaSender, packet []byte, h *header.H) {
+	// Gate on known handshake subtypes. Unknown subtypes (or future ones we
+	// don't yet support) are dropped here rather than silently routed through
+	// the IX path. Add a case when introducing a new pattern.
+	switch h.Subtype {
+	case header.HandshakeIXPSK0:
+		// supported
+	default:
+		hm.l.Debug("dropping handshake with unsupported subtype",
+			"from", via, "subtype", h.Subtype)
+		return
+	}
+
 	// First remote allow list check before we know the vpnIp
 	if !via.IsRelayed {
 		if !hm.lightHouse.GetRemoteAllowList().AllowUnknownVpnAddr(via.UdpAddr.Addr()) {
@@ -145,19 +168,27 @@ func (hm *HandshakeManager) HandleIncoming(via ViaSender, packet []byte, h *head
 		}
 	}
 
-	switch h.Subtype {
-	case header.HandshakeIXPSK0:
-		switch h.MessageCounter {
-		case 1:
-			ixHandshakeStage1(hm.f, via, packet, h)
-
-		case 2:
-			newHostinfo := hm.queryIndex(h.RemoteIndex)
-			tearDown := ixHandshakeStage2(hm.f, via, newHostinfo, packet, h)
-			if tearDown && newHostinfo != nil {
-				hm.DeleteHostInfo(newHostinfo.hostinfo)
-			}
+	// First message of a new handshake. The wire format requires RemoteIndex
+	// to be zero here (the initiator has no responder index to fill in yet),
+	// and generateIndex never allocates 0, so any non-zero RemoteIndex on a
+	// stage-1 packet is malformed or someone probing for an index collision.
+	// Drop without paying the cost of running noise on a pending Machine.
+	if h.MessageCounter == 1 {
+		if h.RemoteIndex != 0 {
+			hm.l.Debug("dropping stage-1 handshake with non-zero RemoteIndex",
+				"from", via, "remoteIndex", h.RemoteIndex)
+			return
 		}
+		hm.beginHandshake(via, packet, h)
+		return
+	}
+
+	// Continuation message must match a pending handshake by index.
+	// Anything else is an orphaned packet (e.g., late retransmit after
+	// timeout) and is dropped.
+	if hh := hm.queryIndex(h.RemoteIndex); hh != nil {
+		hm.continueHandshake(via, hh, packet)
+		return
 	}
 }
 
@@ -183,13 +214,22 @@ func (hm *HandshakeManager) handleOutbound(vpnIp netip.Addr, lighthouseTriggered
 	hostinfo := hh.hostinfo
 	// If we are out of time, clean up
 	if hh.counter >= hm.config.retries {
-		hh.hostinfo.logger(hm.l).Info("Handshake timed out",
+		fields := []any{
 			"udpAddrs", hh.hostinfo.remotes.CopyAddrs(hm.mainHostMap.GetPreferredRanges()),
 			"initiatorIndex", hh.hostinfo.localIndexId,
 			"remoteIndex", hh.hostinfo.remoteIndexId,
-			"handshake", m{"stage": 1, "style": "ix_psk0"},
 			"durationNs", time.Since(hh.startTime).Nanoseconds(),
-		)
+		}
+		// hh.machine can be nil here if buildStage0Packet never succeeded
+		// (e.g., no certificate available). In that case there's no useful
+		// handshake metadata to log.
+		if hh.machine != nil {
+			fields = append(fields, "handshake", m{
+				"stage": uint64(hh.machine.MessageIndex()),
+				"style": header.SubTypeName(header.Handshake, hh.machine.Subtype()),
+			})
+		}
+		hh.hostinfo.logger(hm.l).Info("Handshake timed out", fields...)
 		hm.metricTimedOut.Inc(1)
 		hm.DeleteHostInfo(hostinfo)
 		return
@@ -200,12 +240,25 @@ func (hm *HandshakeManager) handleOutbound(vpnIp netip.Addr, lighthouseTriggered
 
 	// Check if we have a handshake packet to transmit yet
 	if !hh.ready {
-		if !ixHandshakeStage0(hm.f, hh) {
+		if !hm.buildStage0Packet(hh) {
 			hm.OutboundHandshakeTimer.Add(vpnIp, hm.config.tryInterval*time.Duration(hh.counter))
 			return
 		}
 	}
 
+	// TODO: this hardcodes "always retransmit stage 0", which is correct for
+	// IX (the initiator only ever sends one packet, msg1) but wrong the
+	// moment a 3+ message pattern lands. The retry loop should resend the
+	// most recent outgoing message, not always stage 0. That implies
+	// HandshakeHostInfo tracking a single "currentOutbound" packet (bytes +
+	// header metadata) that gets replaced as the handshake progresses,
+	// instead of indexing into HandshakePacket.
+	stage0 := hostinfo.HandshakePacket[handshakePacketStage0]
+	hsFields := m{
+		"stage": uint64(hh.machine.MessageIndex()),
+		"style": header.SubTypeName(header.Handshake, hh.machine.Subtype()),
+	}
+
 	// Get a remotes object if we don't already have one.
 	// This is mainly to protect us as this should never be the case
 	// NB ^ This comment doesn't jive. It's how the thing gets initialized.
@@ -239,13 +292,13 @@ func (hm *HandshakeManager) handleOutbound(vpnIp netip.Addr, lighthouseTriggered
 	// Send the handshake to all known ips, stage 2 takes care of assigning the hostinfo.remote based on the first to reply
 	var sentTo []netip.AddrPort
 	hostinfo.remotes.ForEach(hm.mainHostMap.GetPreferredRanges(), func(addr netip.AddrPort, _ bool) {
-		hm.messageMetrics.Tx(header.Handshake, header.MessageSubType(hostinfo.HandshakePacket[0][1]), 1)
-		err := hm.outside.WriteTo(hostinfo.HandshakePacket[0], addr)
+		hm.messageMetrics.Tx(header.Handshake, hh.machine.Subtype(), 1)
+		err := hm.outside.WriteTo(stage0, addr)
 		if err != nil {
 			hostinfo.logger(hm.l).Error("Failed to send handshake message",
 				"udpAddr", addr,
 				"initiatorIndex", hostinfo.localIndexId,
-				"handshake", m{"stage": 1, "style": "ix_psk0"},
+				"handshake", hsFields,
 				"error", err,
 			)
 
@@ -260,156 +313,17 @@ func (hm *HandshakeManager) handleOutbound(vpnIp netip.Addr, lighthouseTriggered
 		hostinfo.logger(hm.l).Info("Handshake message sent",
 			"udpAddrs", sentTo,
 			"initiatorIndex", hostinfo.localIndexId,
-			"handshake", m{"stage": 1, "style": "ix_psk0"},
+			"handshake", hsFields,
 		)
 	} else if hm.l.Enabled(context.Background(), slog.LevelDebug) {
 		hostinfo.logger(hm.l).Debug("Handshake message sent",
 			"udpAddrs", sentTo,
 			"initiatorIndex", hostinfo.localIndexId,
-			"handshake", m{"stage": 1, "style": "ix_psk0"},
+			"handshake", hsFields,
 		)
 	}
 
-	if hm.config.useRelays && len(hostinfo.remotes.relays) > 0 {
-		hostinfo.logger(hm.l).Info("Attempt to relay through hosts", "relays", hostinfo.remotes.relays)
-		// Send a RelayRequest to all known Relay IP's
-		for _, relay := range hostinfo.remotes.relays {
-			// Don't relay through the host I'm trying to connect to
-			if relay == vpnIp {
-				continue
-			}
-
-			// Don't relay to myself
-			if hm.f.myVpnAddrsTable.Contains(relay) {
-				continue
-			}
-
-			relayHostInfo := hm.mainHostMap.QueryVpnAddr(relay)
-			if relayHostInfo == nil || !relayHostInfo.remote.IsValid() {
-				hostinfo.logger(hm.l).Info("Establish tunnel to relay target", "relay", relay.String())
-				hm.f.Handshake(relay)
-				continue
-			}
-			// Check the relay HostInfo to see if we already established a relay through
-			existingRelay, ok := relayHostInfo.relayState.QueryRelayForByIp(vpnIp)
-			if !ok {
-				// No relays exist or requested yet.
-				if relayHostInfo.remote.IsValid() {
-					idx, err := AddRelay(hm.l, relayHostInfo, hm.mainHostMap, vpnIp, nil, TerminalType, Requested)
-					if err != nil {
-						hostinfo.logger(hm.l).Info("Failed to add relay to hostmap", "relay", relay.String(), "error", err)
-					}
-
-					m := NebulaControl{
-						Type:                NebulaControl_CreateRelayRequest,
-						InitiatorRelayIndex: idx,
-					}
-
-					switch relayHostInfo.GetCert().Certificate.Version() {
-					case cert.Version1:
-						if !hm.f.myVpnAddrs[0].Is4() {
-							hostinfo.logger(hm.l).Error("can not establish v1 relay with a v6 network because the relay is not running a current nebula version")
-							continue
-						}
-
-						if !vpnIp.Is4() {
-							hostinfo.logger(hm.l).Error("can not establish v1 relay with a v6 remote network because the relay is not running a current nebula version")
-							continue
-						}
-
-						b := hm.f.myVpnAddrs[0].As4()
-						m.OldRelayFromAddr = binary.BigEndian.Uint32(b[:])
-						b = vpnIp.As4()
-						m.OldRelayToAddr = binary.BigEndian.Uint32(b[:])
-					case cert.Version2:
-						m.RelayFromAddr = netAddrToProtoAddr(hm.f.myVpnAddrs[0])
-						m.RelayToAddr = netAddrToProtoAddr(vpnIp)
-					default:
-						hostinfo.logger(hm.l).Error("Unknown certificate version found while creating relay")
-						continue
-					}
-
-					msg, err := m.Marshal()
-					if err != nil {
-						hostinfo.logger(hm.l).Error("Failed to marshal Control message to create relay", "error", err)
-					} else {
-						hm.f.SendMessageToHostInfo(header.Control, 0, relayHostInfo, msg, make([]byte, 12), make([]byte, mtu))
-						hm.l.Info("send CreateRelayRequest",
-							"relayFrom", hm.f.myVpnAddrs[0],
-							"relayTo", vpnIp,
-							"initiatorRelayIndex", idx,
-							"relay", relay,
-						)
-					}
-				}
-				continue
-			}
-
-			switch existingRelay.State {
-			case Established:
-				hostinfo.logger(hm.l).Info("Send handshake via relay", "relay", relay.String())
-				hm.f.SendVia(relayHostInfo, existingRelay, hostinfo.HandshakePacket[0], make([]byte, 12), make([]byte, mtu), false)
-			case Disestablished:
-				// Mark this relay as 'requested'
-				relayHostInfo.relayState.UpdateRelayForByIpState(vpnIp, Requested)
-				fallthrough
-			case Requested:
-				hostinfo.logger(hm.l).Info("Re-send CreateRelay request", "relay", relay.String())
-				// Re-send the CreateRelay request, in case the previous one was lost.
-				m := NebulaControl{
-					Type:                NebulaControl_CreateRelayRequest,
-					InitiatorRelayIndex: existingRelay.LocalIndex,
-				}
-
-				switch relayHostInfo.GetCert().Certificate.Version() {
-				case cert.Version1:
-					if !hm.f.myVpnAddrs[0].Is4() {
-						hostinfo.logger(hm.l).Error("can not establish v1 relay with a v6 network because the relay is not running a current nebula version")
-						continue
-					}
-
-					if !vpnIp.Is4() {
-						hostinfo.logger(hm.l).Error("can not establish v1 relay with a v6 remote network because the relay is not running a current nebula version")
-						continue
-					}
-
-					b := hm.f.myVpnAddrs[0].As4()
-					m.OldRelayFromAddr = binary.BigEndian.Uint32(b[:])
-					b = vpnIp.As4()
-					m.OldRelayToAddr = binary.BigEndian.Uint32(b[:])
-				case cert.Version2:
-					m.RelayFromAddr = netAddrToProtoAddr(hm.f.myVpnAddrs[0])
-					m.RelayToAddr = netAddrToProtoAddr(vpnIp)
-				default:
-					hostinfo.logger(hm.l).Error("Unknown certificate version found while creating relay")
-					continue
-				}
-				msg, err := m.Marshal()
-				if err != nil {
-					hostinfo.logger(hm.l).Error("Failed to marshal Control message to create relay", "error", err)
-				} else {
-					// This must send over the hostinfo, not over hm.Hosts[ip]
-					hm.f.SendMessageToHostInfo(header.Control, 0, relayHostInfo, msg, make([]byte, 12), make([]byte, mtu))
-					hm.l.Info("send CreateRelayRequest",
-						"relayFrom", hm.f.myVpnAddrs[0],
-						"relayTo", vpnIp,
-						"initiatorRelayIndex", existingRelay.LocalIndex,
-						"relay", relay,
-					)
-				}
-			case PeerRequested:
-				// PeerRequested only occurs in Forwarding relays, not Terminal relays, and this is a Terminal relay case.
-				fallthrough
-			default:
-				hostinfo.logger(hm.l).Error("Relay unexpected state",
-					"vpnIp", vpnIp,
-					"state", existingRelay.State,
-					"relay", relay,
-				)
-
-			}
-		}
-	}
+	hm.f.relayManager.StartRelays(hm.f, vpnIp, hostinfo, stage0)
 
 	// If a lighthouse triggered this attempt then we are still in the timer wheel and do not need to re-add
 	if !lighthouseTriggered {
@@ -587,7 +501,7 @@ func (hm *HandshakeManager) Complete(hostinfo *HostInfo, f *Interface) {
 // allocateIndex generates a unique localIndexId for this HostInfo
 // and adds it to the pendingHostMap. Will error if we are unable to generate
 // a unique localIndexId
-func (hm *HandshakeManager) allocateIndex(hh *HandshakeHostInfo) error {
+func (hm *HandshakeManager) allocateIndex(hh *HandshakeHostInfo) (uint32, error) {
 	hm.mainHostMap.RLock()
 	defer hm.mainHostMap.RUnlock()
 	hm.Lock()
@@ -596,7 +510,7 @@ func (hm *HandshakeManager) allocateIndex(hh *HandshakeHostInfo) error {
 	for range 32 {
 		index, err := generateIndex(hm.l)
 		if err != nil {
-			return err
+			return 0, err
 		}
 
 		_, inPending := hm.indexes[index]
@@ -605,11 +519,11 @@ func (hm *HandshakeManager) allocateIndex(hh *HandshakeHostInfo) error {
 		if !inMain && !inPending {
 			hh.hostinfo.localIndexId = index
 			hm.indexes[index] = hh
-			return nil
+			return index, nil
 		}
 	}
 
-	return errors.New("failed to generate unique localIndexId")
+	return 0, errors.New("failed to generate unique localIndexId")
 }
 
 func (hm *HandshakeManager) DeleteHostInfo(hostinfo *HostInfo) {
@@ -728,3 +642,525 @@ func generateIndex(l *slog.Logger) (uint32, error) {
 func hsTimeout(tries int64, interval time.Duration) time.Duration {
 	return time.Duration(tries / 2 * ((2 * int64(interval)) + (tries-1)*int64(interval)))
 }
+
+// buildStage0Packet creates the initial handshake packet for the initiator.
+func (hm *HandshakeManager) buildStage0Packet(hh *HandshakeHostInfo) bool {
+	cs := hm.f.pki.getCertState()
+	v := cs.DefaultVersion()
+	if hh.initiatingVersionOverride != cert.VersionPre1 {
+		v = hh.initiatingVersionOverride
+	} else if v < cert.Version2 {
+		for _, a := range hh.hostinfo.vpnAddrs {
+			if a.Is6() {
+				v = cert.Version2
+				break
+			}
+		}
+	}
+
+	cred := cs.GetCredential(v)
+	if cred == nil {
+		hm.f.l.Error("Unable to handshake with host because no certificate is available",
+			"vpnAddrs", hh.hostinfo.vpnAddrs, "certVersion", v)
+		return false
+	}
+
+	machine, err := handshake.NewMachine(
+		v, cs.GetCredential,
+		hm.certVerifier(), func() (uint32, error) { return hm.allocateIndex(hh) },
+		true, header.HandshakeIXPSK0,
+	)
+	if err != nil {
+		hm.f.l.Error("Failed to create handshake machine",
+			"vpnAddrs", hh.hostinfo.vpnAddrs, "error", err)
+		return false
+	}
+
+	msg, err := machine.Initiate(nil)
+	if err != nil {
+		hm.f.l.Error("Failed to initiate handshake",
+			"vpnAddrs", hh.hostinfo.vpnAddrs, "error", err)
+		return false
+	}
+
+	// hostinfo.ConnectionState stays nil until the handshake completes in
+	// continueHandshake. Pre-completion control surfaces guard with nil
+	// checks; the data plane never observes a pending hostinfo.
+	hh.hostinfo.HandshakePacket[handshakePacketStage0] = msg
+	hh.machine = machine
+	hh.ready = true
+	return true
+}
+
+// beginHandshake handles an incoming handshake packet that doesn't match any
+// existing pending handshake. It creates a new responder Machine and processes
+// the first message.
+func (hm *HandshakeManager) beginHandshake(via ViaSender, packet []byte, h *header.H) {
+	f := hm.f
+	cs := f.pki.getCertState()
+
+	v := cs.DefaultVersion()
+	if cs.GetCredential(v) == nil {
+		f.l.Error("Unable to handshake with host because no certificate is available",
+			"from", via, "certVersion", v)
+		return
+	}
+
+	machine, err := handshake.NewMachine(
+		v, cs.GetCredential,
+		hm.certVerifier(), func() (uint32, error) { return generateIndex(f.l) },
+		false, header.HandshakeIXPSK0,
+	)
+	if err != nil {
+		f.l.Error("Failed to create handshake machine", "from", via, "error", err)
+		return
+	}
+
+	response, result, err := machine.ProcessPacket(nil, packet)
+	if err != nil {
+		f.l.Error("Failed to process handshake packet", "from", via, "error", err)
+		return
+	}
+
+	if result == nil {
+		// Multi-message pattern: the responder Machine would need to be
+		// registered in hm.indexes so a future inbound packet finds it via
+		// continueHandshake. The current manager doesn't do that yet, so
+		// fail loudly rather than silently dropping the in-flight handshake.
+		// TODO: support multi-message responder flows (XX, pqIX, etc.).
+		// See also the IX-shaped cipher key assignment in handshake.Machine.
+		f.l.Error("multi-message handshake responder is not supported",
+			"from", via, "error", handshake.ErrMultiMessageUnsupported)
+		return
+	}
+
+	remoteCert := result.RemoteCert
+	if remoteCert == nil {
+		f.l.Error("Handshake did not produce a peer certificate", "from", via)
+		return
+	}
+
+	// Validate peer identity
+	vpnAddrs, anyVpnAddrsInCommon, ok := hm.validatePeerCert(via, remoteCert)
+	if !ok {
+		return
+	}
+
+	hostinfo := &HostInfo{
+		ConnectionState:   newConnectionStateFromResult(result),
+		localIndexId:      result.LocalIndex,
+		remoteIndexId:     result.RemoteIndex,
+		vpnAddrs:          vpnAddrs,
+		HandshakePacket:   make(map[uint8][]byte, 0),
+		lastHandshakeTime: result.HandshakeTime,
+		relayState: RelayState{
+			relays:         nil,
+			relayForByAddr: map[netip.Addr]*Relay{},
+			relayForByIdx:  map[uint32]*Relay{},
+		},
+	}
+
+	msg := "Handshake message received"
+	if !anyVpnAddrsInCommon {
+		msg = "Handshake message received, but no vpnNetworks in common."
+	}
+	f.l.Info(msg,
+		"vpnAddrs", vpnAddrs,
+		"from", via,
+		"certName", remoteCert.Certificate.Name(),
+		"certVersion", remoteCert.Certificate.Version(),
+		"fingerprint", remoteCert.Fingerprint,
+		"issuer", remoteCert.Certificate.Issuer(),
+		"initiatorIndex", result.RemoteIndex,
+		"responderIndex", result.LocalIndex,
+		"handshake", m{"stage": uint64(machine.MessageIndex()), "style": header.SubTypeName(header.Handshake, machine.Subtype())},
+	)
+
+	// packet aliases the listener's incoming buffer, so this copy must stay.
+	hostinfo.HandshakePacket[handshakePacketStage0] = make([]byte, len(packet[header.Len:]))
+	copy(hostinfo.HandshakePacket[handshakePacketStage0], packet[header.Len:])
+
+	// response was freshly allocated by ProcessPacket; safe to retain directly.
+	if response != nil {
+		hostinfo.HandshakePacket[handshakePacketStage2] = response
+	}
+
+	hostinfo.remotes = f.lightHouse.QueryCache(vpnAddrs)
+	if !via.IsRelayed {
+		hostinfo.SetRemote(via.UdpAddr)
+	}
+	hostinfo.buildNetworks(f.myVpnNetworksTable, remoteCert.Certificate)
+
+	existing, err := hm.CheckAndComplete(hostinfo, handshakePacketStage0, f)
+	if err != nil {
+		hm.handleCheckAndCompleteError(err, existing, hostinfo, via)
+		return
+	}
+
+	hm.sendHandshakeResponse(via, response, hostinfo, false)
+	f.connectionManager.AddTrafficWatch(hostinfo)
+	hostinfo.remotes.RefreshFromHandshake(vpnAddrs)
+
+	// Don't wait for UpdateWorker
+	if f.lightHouse.IsAnyLighthouseAddr(vpnAddrs) {
+		f.lightHouse.TriggerUpdate()
+	}
+}
+
+// continueHandshake feeds an incoming packet to an existing pending handshake Machine.
+func (hm *HandshakeManager) continueHandshake(via ViaSender, hh *HandshakeHostInfo, packet []byte) {
+	f := hm.f
+
+	hh.Lock()
+	defer hh.Unlock()
+
+	// Re-verify hh is still tracked. Between queryIndex returning and us taking
+	// hh.Lock, handleOutbound may have timed out and deleted it. Once we hold
+	// hh.Lock no other deleter can race our index: handleOutbound also takes
+	// hh.Lock first, and handleRecvError targets a main-hostmap entry with a
+	// different localIndexId.
+	hm.RLock()
+	cur, ok := hm.indexes[hh.hostinfo.localIndexId]
+	hm.RUnlock()
+	if !ok || cur != hh {
+		return
+	}
+
+	hostinfo := hh.hostinfo
+	if !via.IsRelayed {
+		if !f.lightHouse.GetRemoteAllowList().AllowAll(hostinfo.vpnAddrs, via.UdpAddr.Addr()) {
+			f.l.Debug("lighthouse.remote_allow_list denied incoming handshake",
+				"vpnAddrs", hostinfo.vpnAddrs, "from", via)
+			return
+		}
+	}
+
+	machine := hh.machine
+	if machine == nil {
+		f.l.Error("No handshake machine available for continuation",
+			"vpnAddrs", hostinfo.vpnAddrs, "from", via)
+		hm.DeleteHostInfo(hostinfo)
+		return
+	}
+
+	response, result, err := machine.ProcessPacket(nil, packet)
+	if err != nil {
+		// Recoverable errors are routine noise, log at Debug. Fatal errors get a Warn.
+		if machine.Failed() {
+			f.l.Warn("Failed to process handshake packet, abandoning",
+				"vpnAddrs", hostinfo.vpnAddrs, "from", via, "error", err)
+			hm.DeleteHostInfo(hostinfo)
+		} else {
+			f.l.Debug("Failed to process handshake packet",
+				"vpnAddrs", hostinfo.vpnAddrs, "from", via, "error", err)
+		}
+		return
+	}
+
+	if response != nil {
+		hm.sendHandshakeResponse(via, response, hostinfo, false)
+	}
+
+	if result == nil {
+		return
+	}
+
+	// Handshake complete; build the ConnectionState now that we have keys and a verified peer cert.
+	hostinfo.ConnectionState = newConnectionStateFromResult(result)
+
+	remoteCert := result.RemoteCert
+	if remoteCert == nil {
+		f.l.Error("Handshake completed without peer certificate",
+			"vpnAddrs", hostinfo.vpnAddrs, "from", via)
+		hm.DeleteHostInfo(hostinfo)
+		return
+	}
+
+	vpnNetworks := remoteCert.Certificate.Networks()
+	hostinfo.remoteIndexId = result.RemoteIndex
+	hostinfo.lastHandshakeTime = result.HandshakeTime
+
+	if !via.IsRelayed {
+		hostinfo.SetRemote(via.UdpAddr)
+	} else {
+		hostinfo.relayState.InsertRelayTo(via.relayHI.vpnAddrs[0])
+	}
+
+	// Verify correct host responded (initiator check)
+	vpnAddrs := make([]netip.Addr, len(vpnNetworks))
+	correctHostResponded := false
+	anyVpnAddrsInCommon := false
+	for i, network := range vpnNetworks {
+		// inside.go drops self-routed packets at the firewall stage, but we'd
+		// rather not let a self-handshake complete in the first place: it
+		// wastes a hostmap slot, suppresses no log, and obscures routing
+		// misconfig. Explicit refusal here mirrors the responder-side check
+		// in validatePeerCert.
+		if f.myVpnAddrsTable.Contains(network.Addr()) {
+			f.l.Error("Refusing to handshake with myself",
+				"vpnNetworks", vpnNetworks,
+				"from", via,
+				"certName", remoteCert.Certificate.Name(),
+				"certVersion", remoteCert.Certificate.Version(),
+				"fingerprint", remoteCert.Fingerprint,
+				"issuer", remoteCert.Certificate.Issuer(),
+				"handshake", m{"stage": uint64(machine.MessageIndex()), "style": header.SubTypeName(header.Handshake, machine.Subtype())},
+			)
+			hm.DeleteHostInfo(hostinfo)
+			return
+		}
+		vpnAddrs[i] = network.Addr()
+		if hostinfo.vpnAddrs[0] == network.Addr() {
+			correctHostResponded = true
+		}
+		if f.myVpnNetworksTable.Contains(network.Addr()) {
+			anyVpnAddrsInCommon = true
+		}
+	}
+
+	if !correctHostResponded {
+		f.l.Info("Incorrect host responded to handshake",
+			"intendedVpnAddrs", hostinfo.vpnAddrs,
+			"haveVpnNetworks", vpnNetworks,
+			"from", via,
+			"certName", remoteCert.Certificate.Name(),
+			"certVersion", remoteCert.Certificate.Version(),
+			"fingerprint", remoteCert.Fingerprint,
+			"issuer", remoteCert.Certificate.Issuer(),
+			"handshake", m{"stage": uint64(machine.MessageIndex()), "style": header.SubTypeName(header.Handshake, machine.Subtype())},
+		)
+
+		hm.DeleteHostInfo(hostinfo)
+		hm.StartHandshake(hostinfo.vpnAddrs[0], func(newHH *HandshakeHostInfo) {
+			newHH.hostinfo.remotes = hostinfo.remotes
+			newHH.hostinfo.remotes.BlockRemote(via)
+			newHH.packetStore = hh.packetStore
+			hh.packetStore = []*cachedPacket{}
+			hostinfo.vpnAddrs = vpnAddrs
+			f.sendCloseTunnel(hostinfo)
+		})
+		return
+	}
+
+	duration := time.Since(hh.startTime).Nanoseconds()
+	msg := "Handshake message received"
+	if !anyVpnAddrsInCommon {
+		msg = "Handshake message received, but no vpnNetworks in common."
+	}
+	f.l.Info(msg,
+		"vpnAddrs", vpnAddrs,
+		"from", via,
+		"certName", remoteCert.Certificate.Name(),
+		"certVersion", remoteCert.Certificate.Version(),
+		"fingerprint", remoteCert.Fingerprint,
+		"issuer", remoteCert.Certificate.Issuer(),
+		"initiatorIndex", result.LocalIndex,
+		"responderIndex", result.RemoteIndex,
+		"handshake", m{"stage": uint64(machine.MessageIndex()), "style": header.SubTypeName(header.Handshake, machine.Subtype())},
+		"durationNs", duration,
+		"sentCachedPackets", len(hh.packetStore),
+	)
+
+	hostinfo.vpnAddrs = vpnAddrs
+	hostinfo.buildNetworks(f.myVpnNetworksTable, remoteCert.Certificate)
+
+	hm.Complete(hostinfo, f)
+	f.connectionManager.AddTrafficWatch(hostinfo)
+
+	if len(hh.packetStore) > 0 {
+		if f.l.Enabled(context.Background(), slog.LevelDebug) {
+			hostinfo.logger(f.l).Debug("Sending stored packets", "count", len(hh.packetStore))
+		}
+		nb := make([]byte, 12, 12)
+		out := make([]byte, mtu)
+		for _, cp := range hh.packetStore {
+			//todo use a sendbatcher
+			cp.callback(cp.messageType, cp.messageSubType, hostinfo, cp.packet, nb, out)
+		}
+		f.cachedPacketMetrics.sent.Inc(int64(len(hh.packetStore)))
+	}
+
+	hostinfo.remotes.RefreshFromHandshake(vpnAddrs)
+	f.metricHandshakes.Update(duration)
+
+	// Don't wait for UpdateWorker
+	if f.lightHouse.IsAnyLighthouseAddr(vpnAddrs) {
+		f.lightHouse.TriggerUpdate()
+	}
+}
+
+// validatePeerCert checks the peer certificate for self-connection and remote allow list.
+// Returns the VPN addrs, whether any of them fall within one of our own VPN
+// networks, and true if valid; false if rejected.
+func (hm *HandshakeManager) validatePeerCert(via ViaSender, remoteCert *cert.CachedCertificate) ([]netip.Addr, bool, bool) {
+	f := hm.f
+	vpnNetworks := remoteCert.Certificate.Networks()
+
+	// The cert package rejects host certs with no networks at parse time, so
+	// reaching this state would mean an invariant was bypassed elsewhere.
+	// Refuse explicitly so downstream code (which indexes vpnAddrs[0]) can't
+	// panic if that invariant ever changes.
+	if len(vpnNetworks) == 0 {
+		f.l.Info("No networks in certificate",
+			"from", via, "cert", remoteCert)
+		return nil, false, false
+	}
+
+	vpnAddrs := make([]netip.Addr, len(vpnNetworks))
+	anyVpnAddrsInCommon := false
+
+	for i, network := range vpnNetworks {
+		if f.myVpnAddrsTable.Contains(network.Addr()) {
+			f.l.Error("Refusing to handshake with myself",
+				"vpnNetworks", vpnNetworks,
+				"from", via,
+				"certName", remoteCert.Certificate.Name(),
+				"certVersion", remoteCert.Certificate.Version(),
+				"fingerprint", remoteCert.Fingerprint,
+				"issuer", remoteCert.Certificate.Issuer(),
+			)
+			return nil, false, false
+		}
+		vpnAddrs[i] = network.Addr()
+		if f.myVpnNetworksTable.Contains(network.Addr()) {
+			anyVpnAddrsInCommon = true
+		}
+	}
+
+	if !via.IsRelayed {
+		if !f.lightHouse.GetRemoteAllowList().AllowAll(vpnAddrs, via.UdpAddr.Addr()) {
+			f.l.Debug("lighthouse.remote_allow_list denied incoming handshake",
+				"vpnAddrs", vpnAddrs, "from", via)
+			return nil, false, false
+		}
+	}
+
+	return vpnAddrs, anyVpnAddrsInCommon, true
+}
+
+// sendHandshakeResponse sends a handshake response via the appropriate transport.
+// cached is true when msg is a stored response being retransmitted because
+// the peer's stage-1 retransmit landed (the ErrAlreadySeen path); false on a
+// fresh response.
+func (hm *HandshakeManager) sendHandshakeResponse(via ViaSender, msg []byte, hostinfo *HostInfo, cached bool) {
+	if msg == nil {
+		return
+	}
+
+	f := hm.f
+	f.messageMetrics.Tx(header.Handshake, header.MessageSubType(msg[1]), 1)
+
+	// Common log fields. peerCert may be nil during intermediate
+	// multi-message flows (handshake hasn't completed yet); skip the cert
+	// block if so.
+	logFields := []any{
+		"vpnAddrs", hostinfo.vpnAddrs,
+		"handshake", m{"stage": uint64(2), "style": header.SubTypeName(header.Handshake, header.HandshakeIXPSK0)},
+		"cached", cached,
+		"initiatorIndex", hostinfo.remoteIndexId,
+		"responderIndex", hostinfo.localIndexId,
+	}
+	if peerCert := hostinfo.ConnectionState.peerCert; peerCert != nil {
+		logFields = append(logFields,
+			"certName", peerCert.Certificate.Name(),
+			"certVersion", peerCert.Certificate.Version(),
+			"fingerprint", peerCert.Fingerprint,
+			"issuer", peerCert.Certificate.Issuer(),
+		)
+	}
+
+	if !via.IsRelayed {
+		fields := append(logFields, "from", via)
+		err := f.outside.WriteTo(msg, via.UdpAddr)
+		if err != nil {
+			f.l.Error("Failed to send handshake message", append(fields, "error", err)...)
+		} else {
+			f.l.Info("Handshake message sent", fields...)
+		}
+	} else {
+		if via.relay == nil {
+			f.l.Error("Handshake send failed: both addr and via.relay are nil.")
+			return
+		}
+		hostinfo.relayState.InsertRelayTo(via.relayHI.vpnAddrs[0])
+		// We received a valid handshake on this relay, so make sure the relay
+		// state reflects that, in case it had been marked Disestablished.
+		via.relayHI.relayState.UpdateRelayForByIdxState(via.remoteIdx, Established)
+		f.SendVia(via.relayHI, via.relay, msg, make([]byte, 12), make([]byte, mtu), false)
+		f.l.Info("Handshake message sent", append(logFields, "relay", via.relayHI.vpnAddrs[0])...)
+	}
+}
+
+// handleCheckAndCompleteError handles errors from CheckAndComplete.
+// This only fires from the responder-side beginHandshake path, after the
+// peer cert has been validated and ConnectionState populated, so peerCert
+// is always non-nil for the cases that log it.
+func (hm *HandshakeManager) handleCheckAndCompleteError(err error, existing, hostinfo *HostInfo, via ViaSender) {
+	f := hm.f
+	peerCert := hostinfo.ConnectionState.peerCert
+	hsFields := m{"stage": uint64(1), "style": header.SubTypeName(header.Handshake, header.HandshakeIXPSK0)}
+
+	switch err {
+	case ErrAlreadySeen:
+		if existing.SetRemoteIfPreferred(f.hostMap, via) {
+			f.SendMessageToVpnAddr(header.Test, header.TestRequest, hostinfo.vpnAddrs[0], []byte(""), make([]byte, 12, 12), make([]byte, mtu))
+		}
+		// Resend the original response. The peer is committed to that response's
+		// ephemeral keys; a freshly-built one would have different keys and break
+		// the tunnel even though both sides "completed" the handshake.
+		if msg := existing.HandshakePacket[handshakePacketStage2]; msg != nil {
+			hm.sendHandshakeResponse(via, msg, existing, true)
+		}
+
+	case ErrExistingHostInfo:
+		f.l.Info("Handshake too old",
+			"vpnAddrs", hostinfo.vpnAddrs,
+			"from", via,
+			"certName", peerCert.Certificate.Name(),
+			"certVersion", peerCert.Certificate.Version(),
+			"fingerprint", peerCert.Fingerprint,
+			"issuer", peerCert.Certificate.Issuer(),
+			"oldHandshakeTime", existing.lastHandshakeTime,
+			"newHandshakeTime", hostinfo.lastHandshakeTime,
+			"initiatorIndex", hostinfo.remoteIndexId,
+			"responderIndex", hostinfo.localIndexId,
+			"handshake", hsFields,
+		)
+		f.SendMessageToVpnAddr(header.Test, header.TestRequest, hostinfo.vpnAddrs[0], []byte(""), make([]byte, 12, 12), make([]byte, mtu))
+
+	case ErrLocalIndexCollision:
+		f.l.Error("Failed to add HostInfo due to localIndex collision",
+			"vpnAddrs", hostinfo.vpnAddrs,
+			"from", via,
+			"certName", peerCert.Certificate.Name(),
+			"certVersion", peerCert.Certificate.Version(),
+			"fingerprint", peerCert.Fingerprint,
+			"issuer", peerCert.Certificate.Issuer(),
+			"localIndex", hostinfo.localIndexId,
+			"initiatorIndex", hostinfo.remoteIndexId,
+			"responderIndex", hostinfo.localIndexId,
+			"handshake", hsFields,
+		)
+
+	default:
+		f.l.Error("Failed to add HostInfo to HostMap",
+			"vpnAddrs", hostinfo.vpnAddrs,
+			"from", via,
+			"error", err,
+			"certName", peerCert.Certificate.Name(),
+			"certVersion", peerCert.Certificate.Version(),
+			"fingerprint", peerCert.Fingerprint,
+			"issuer", peerCert.Certificate.Issuer(),
+			"initiatorIndex", hostinfo.remoteIndexId,
+			"responderIndex", hostinfo.localIndexId,
+			"handshake", hsFields,
+		)
+	}
+}
+
+// certVerifier returns a CertVerifier that validates certs against the current CA pool.
+func (hm *HandshakeManager) certVerifier() handshake.CertVerifier {
+	return func(c cert.Certificate) (*cert.CachedCertificate, error) {
+		return hm.f.pki.GetCAPool().VerifyCertificate(time.Now(), c)
+	}
+}

handshake_manager_test.go

@@ -5,6 +5,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/gaissmai/bart"
 	"github.com/slackhq/nebula/cert"
 	"github.com/slackhq/nebula/header"
 	"github.com/slackhq/nebula/test"
@@ -27,7 +28,7 @@ func Test_NewHandshakeManagerVpnIp(t *testing.T) {
 		initiatingVersion: cert.Version1,
 		privateKey:        []byte{},
 		v1Cert:            &dummyCert{version: cert.Version1},
-		v1HandshakeBytes:  []byte{},
+		v1Credential:      nil,
 	}
 
 	blah := NewHandshakeManager(l, mainHM, lh, &udp.NoopConn{}, defaultHandshakeConfig)
@@ -100,3 +101,137 @@ func (mw *mockEncWriter) GetHostInfo(_ netip.Addr) *HostInfo {
 func (mw *mockEncWriter) GetCertState() *CertState {
 	return &CertState{initiatingVersion: cert.Version2}
 }
+
+func TestValidatePeerCert(t *testing.T) {
+	l := test.NewLogger()
+
+	myNetwork := netip.MustParsePrefix("10.0.0.1/24")
+	myAddrTable := new(bart.Lite)
+	myAddrTable.Insert(netip.PrefixFrom(myNetwork.Addr(), myNetwork.Addr().BitLen()))
+	myNetTable := new(bart.Lite)
+	myNetTable.Insert(myNetwork.Masked())
+
+	newHM := func() *HandshakeManager {
+		hm := NewHandshakeManager(l, newHostMap(l), newTestLighthouse(), &udp.NoopConn{}, defaultHandshakeConfig)
+		hm.f = &Interface{
+			handshakeManager:   hm,
+			pki:                &PKI{},
+			l:                  l,
+			myVpnAddrsTable:    myAddrTable,
+			myVpnNetworksTable: myNetTable,
+			lightHouse:         hm.lightHouse,
+		}
+		return hm
+	}
+
+	cached := func(networks ...netip.Prefix) *cert.CachedCertificate {
+		return &cert.CachedCertificate{
+			Certificate: &dummyCert{name: "peer", networks: networks},
+		}
+	}
+
+	via := ViaSender{
+		UdpAddr:   netip.MustParseAddrPort("198.51.100.7:4242"),
+		IsRelayed: true, // skip the remote allow list (covered separately)
+	}
+
+	t.Run("addr inside our networks sets anyVpnAddrsInCommon", func(t *testing.T) {
+		hm := newHM()
+		// 10.0.0.2 falls inside our 10.0.0.0/24
+		addrs, common, ok := hm.validatePeerCert(via, cached(netip.MustParsePrefix("10.0.0.2/24")))
+		assert.True(t, ok)
+		assert.True(t, common)
+		assert.Equal(t, []netip.Addr{netip.MustParseAddr("10.0.0.2")}, addrs)
+	})
+
+	t.Run("addr outside our networks leaves anyVpnAddrsInCommon false", func(t *testing.T) {
+		hm := newHM()
+		addrs, common, ok := hm.validatePeerCert(via, cached(netip.MustParsePrefix("192.168.1.5/24")))
+		assert.True(t, ok)
+		assert.False(t, common)
+		assert.Equal(t, []netip.Addr{netip.MustParseAddr("192.168.1.5")}, addrs)
+	})
+
+	t.Run("any matching network is enough", func(t *testing.T) {
+		hm := newHM()
+		addrs, common, ok := hm.validatePeerCert(via, cached(
+			netip.MustParsePrefix("192.168.1.5/24"),
+			netip.MustParsePrefix("10.0.0.42/24"),
+		))
+		assert.True(t, ok)
+		assert.True(t, common)
+		assert.Len(t, addrs, 2)
+	})
+
+	t.Run("self-handshake is rejected", func(t *testing.T) {
+		hm := newHM()
+		// 10.0.0.1 is in myVpnAddrsTable
+		addrs, common, ok := hm.validatePeerCert(via, cached(netip.MustParsePrefix("10.0.0.1/24")))
+		assert.False(t, ok)
+		assert.False(t, common)
+		assert.Nil(t, addrs)
+	})
+
+	t.Run("cert with no networks is rejected", func(t *testing.T) {
+		hm := newHM()
+		addrs, common, ok := hm.validatePeerCert(via, cached())
+		assert.False(t, ok)
+		assert.False(t, common)
+		assert.Nil(t, addrs)
+	})
+}
+
+func TestHandleIncomingDispatch(t *testing.T) {
+	l := test.NewLogger()
+
+	newHM := func() *HandshakeManager {
+		hm := NewHandshakeManager(l, newHostMap(l), newTestLighthouse(), &udp.NoopConn{}, defaultHandshakeConfig)
+		hm.f = &Interface{
+			handshakeManager: hm,
+			pki:              &PKI{},
+			l:                l,
+		}
+		return hm
+	}
+
+	via := ViaSender{
+		UdpAddr:   netip.MustParseAddrPort("198.51.100.7:4242"),
+		IsRelayed: true, // bypass remote allow list
+	}
+
+	// A packet body of zero length is fine for these tests: dispatch is
+	// gated on header fields, and we assert that we never reach noise/cert
+	// processing for any of the malformed shapes here.
+	pkt := make([]byte, header.Len)
+
+	t.Run("unsupported subtype dropped", func(t *testing.T) {
+		hm := newHM()
+		h := &header.H{Type: header.Handshake, Subtype: header.MessageSubType(99), MessageCounter: 1}
+		hm.HandleIncoming(via, pkt, h)
+		assert.Empty(t, hm.indexes, "no pending handshake should be created")
+	})
+
+	t.Run("stage-1 with non-zero RemoteIndex dropped", func(t *testing.T) {
+		hm := newHM()
+		h := &header.H{
+			Type:           header.Handshake,
+			Subtype:        header.HandshakeIXPSK0,
+			RemoteIndex:    0xdeadbeef,
+			MessageCounter: 1,
+		}
+		hm.HandleIncoming(via, pkt, h)
+		assert.Empty(t, hm.indexes, "spoofed stage-1 must not create a pending machine")
+	})
+
+	t.Run("continuation with no matching pending index dropped", func(t *testing.T) {
+		hm := newHM()
+		h := &header.H{
+			Type:           header.Handshake,
+			Subtype:        header.HandshakeIXPSK0,
+			RemoteIndex:    0xcafef00d,
+			MessageCounter: 2,
+		}
+		hm.HandleIncoming(via, pkt, h)
+		assert.Empty(t, hm.indexes, "orphan stage-2 must not create state")
+	})
+}

header/header.go

@@ -174,6 +174,10 @@ func (h *H) SubTypeName() string {
 	return SubTypeName(h.Type, h.Subtype)
 }
 
+func (h *H) IsValidSubType() bool {
+	return IsValidSubType(h.Type, h.Subtype)
+}
+
 // SubTypeName will transform a nebula message sub type into a human string
 func SubTypeName(t MessageType, s MessageSubType) string {
 	if n, ok := subTypeMap[t]; ok {
@@ -185,6 +189,16 @@ func SubTypeName(t MessageType, s MessageSubType) string {
 	return "unknown"
 }
 
+func IsValidSubType(t MessageType, s MessageSubType) bool {
+	if n, ok := subTypeMap[t]; ok {
+		if _, ok := (*n)[s]; ok {
+			return true
+		}
+	}
+
+	return false
+}
+
 // NewHeader turns bytes into a header
 func NewHeader(b []byte) (*H, error) {
 	h := new(H)

inside.go

@@ -2,6 +2,7 @@ package nebula
 
 import (
 	"context"
+	"io"
 	"log/slog"
 	"net/netip"
 
@@ -9,10 +10,16 @@ import (
 	"github.com/slackhq/nebula/header"
 	"github.com/slackhq/nebula/iputil"
 	"github.com/slackhq/nebula/noiseutil"
+	"github.com/slackhq/nebula/overlay/batch"
 	"github.com/slackhq/nebula/routing"
+	"github.com/slackhq/nebula/wire"
 )
 
-func (f *Interface) consumeInsidePacket(packet []byte, fwPacket *firewall.Packet, nb, out []byte, q int, localCache firewall.ConntrackCache) {
+func (f *Interface) consumeInsidePacket(pkt wire.TunPacket, fwPacket *firewall.Packet, nb []byte, sendBatch *batch.SendBatch, rejectBuf []byte, q int, localCache firewall.ConntrackCache) {
+	// borrowed: pkt.Bytes is owned by the originating tio.Queue and is
+	// only valid until the next Read on that queue. If you must keep
+	// the packet, use pkt.Clone() to detach it
+	packet := pkt.Bytes
 	err := newPacket(packet, false, fwPacket)
 	if err != nil {
 		if f.l.Enabled(context.Background(), slog.LevelDebug) {
@@ -37,7 +44,10 @@ func (f *Interface) consumeInsidePacket(packet []byte, fwPacket *firewall.Packet
 		// routes packets from the Nebula addr to the Nebula addr through the Nebula
 		// TUN device.
 		if immediatelyForwardToSelf {
-			_, err := f.readers[q].Write(packet)
+			err := pkt.PerSegment(func(seg []byte) error {
+				_, werr := f.readers[q].Write(seg)
+				return werr
+			})
 			if err != nil {
 				f.l.Error("Failed to forward to tun", "error", err)
 			}
@@ -53,11 +63,23 @@ func (f *Interface) consumeInsidePacket(packet []byte, fwPacket *firewall.Packet
 	}
 
 	hostinfo, ready := f.getOrHandshakeConsiderRouting(fwPacket, func(hh *HandshakeHostInfo) {
-		hh.cachePacket(f.l, header.Message, 0, packet, f.sendMessageNow, f.cachedPacketMetrics)
+		// borrowed: SegmentSuperpacket builds each segment in the kernel-supplied pkt
+		// bytes underneath. cachePacket explicitly copies its argument (handshake_manager.go cachePacket),
+		// so retaining segments past the loop is safe.
+		err := pkt.PerSegment(func(seg []byte) error {
+			hh.cachePacket(f.l, header.Message, 0, seg, f.sendMessageNow, f.cachedPacketMetrics)
+			return nil
+		})
+		if err != nil && f.l.Enabled(context.Background(), slog.LevelDebug) {
+			f.l.Debug("Failed to segment superpacket for handshake cache",
+				"error", err,
+				"vpnAddr", fwPacket.RemoteAddr,
+			)
+		}
 	})
 
 	if hostinfo == nil {
-		f.rejectInside(packet, out, q)
+		f.rejectInside(packet, rejectBuf, q)
 		if f.l.Enabled(context.Background(), slog.LevelDebug) {
 			f.l.Debug("dropping outbound packet, vpnAddr not in our vpn networks or in unsafe networks",
 				"vpnAddr", fwPacket.RemoteAddr,
@@ -73,10 +95,9 @@ func (f *Interface) consumeInsidePacket(packet []byte, fwPacket *firewall.Packet
 
 	dropReason := f.firewall.Drop(*fwPacket, false, hostinfo, f.pki.GetCAPool(), localCache)
 	if dropReason == nil {
-		f.sendNoMetrics(header.Message, 0, hostinfo.ConnectionState, hostinfo, netip.AddrPort{}, packet, nb, out, q)
-
+		f.sendInsideMessage(hostinfo, pkt, nb, sendBatch)
 	} else {
-		f.rejectInside(packet, out, q)
+		f.rejectInside(packet, rejectBuf, q)
 		if f.l.Enabled(context.Background(), slog.LevelDebug) {
 			hostinfo.logger(f.l).Debug("dropping outbound packet",
 				"fwPacket", fwPacket,
@@ -86,6 +107,124 @@ func (f *Interface) consumeInsidePacket(packet []byte, fwPacket *firewall.Packet
 	}
 }
 
+func (f *Interface) sendInsideEncrypt(hostinfo *HostInfo, ci *ConnectionState, seg, scratch, nb []byte) []byte {
+	if noiseutil.EncryptLockNeeded {
+		ci.writeLock.Lock()
+	}
+	c := ci.messageCounter.Add(1)
+
+	out := header.Encode(scratch, header.Version, header.Message, 0, hostinfo.remoteIndexId, c)
+	f.connectionManager.Out(hostinfo)
+
+	out, encErr := ci.eKey.EncryptDanger(out, out, seg, c, nb)
+	if noiseutil.EncryptLockNeeded {
+		ci.writeLock.Unlock()
+	}
+	if encErr != nil {
+		hostinfo.logger(f.l).Error("Failed to encrypt outgoing packet",
+			"error", encErr,
+			"udpAddr", hostinfo.remote,
+			"counter", c,
+		)
+		// Skip this segment; the rest of the superpacket can still
+		// go out — TCP will retransmit anything we drop here.
+		return nil
+	}
+
+	return out
+}
+
+// sendInsideMessage encrypts a firewall-approved inside packet (or every
+// segment of a TSO/USO superpacket) into the caller's batch slot for
+// later sendmmsg flush. Segmentation is fused with encryption here so the
+// kernel-supplied superpacket bytes never get written into a separate
+// scratch arena: PerSegment builds each segment's plaintext in
+// segScratch[:segLen] in turn, and we encrypt directly into a fresh
+// SendBatch slot.
+func (f *Interface) sendInsideMessage(hostinfo *HostInfo, pkt wire.TunPacket, nb []byte, sendBatch *batch.SendBatch) {
+	ci := hostinfo.ConnectionState
+	if ci.eKey == nil {
+		return
+	}
+
+	if hostinfo.lastRebindCount != f.rebindCount {
+		//NOTE: there is an update hole if a tunnel isn't used and exactly 256 rebinds occur before the tunnel is
+		// finally used again. This tunnel would eventually be torn down and recreated if this action didn't help.
+		f.lightHouse.QueryServer(hostinfo.vpnAddrs[0])
+		hostinfo.lastRebindCount = f.rebindCount
+		if f.l.Enabled(context.Background(), slog.LevelDebug) {
+			hostinfo.logger(f.l).Debug("Lighthouse update triggered for punch due to rebind counter",
+				"vpnAddrs", hostinfo.vpnAddrs,
+			)
+		}
+	}
+
+	if !hostinfo.remote.IsValid() { //the relay path
+		//first, find our relay hostinfo:
+		var relayHostInfo *HostInfo
+		var relay *Relay
+		var err error
+		for _, relayIP := range hostinfo.relayState.CopyRelayIps() {
+			relayHostInfo, relay, err = f.hostMap.QueryVpnAddrsRelayFor(hostinfo.vpnAddrs, relayIP)
+			if err != nil {
+				hostinfo.relayState.DeleteRelay(relayIP)
+				hostinfo.logger(f.l).Info("sendNoMetrics failed to find HostInfo",
+					"relay", relayIP,
+					"error", err,
+				)
+				continue
+			}
+			break
+		}
+		if relayHostInfo == nil || relay == nil {
+			//failure already logged
+			return
+		}
+
+		err = pkt.PerSegment(func(seg []byte) error {
+			//relay header + header + plaintext + AEAD tag (16 bytes for both AES-GCM and ChaCha20-Poly1305) + relay tag
+			scratch := sendBatch.Reserve(header.Len + header.Len + len(seg) + 16 + 16)
+
+			innerPacket := f.sendInsideEncrypt(hostinfo, ci, seg, scratch[header.Len:], nb)
+			if innerPacket == nil {
+				return nil
+			}
+
+			//now we need to do a relay-encrypt:
+			toSend, err := f.prepareSendVia(relayHostInfo, relay, innerPacket, nb, scratch, true)
+			if err != nil {
+				//already logged
+				return nil
+			}
+
+			sendBatch.Commit(toSend, relayHostInfo.remote, 0)
+			return nil
+		})
+		if err != nil {
+			hostinfo.logger(f.l).Error("Failed to segment superpacket for relay send", "error", err)
+		}
+		return
+	}
+
+	err := pkt.PerSegment(func(seg []byte) error {
+		// header + plaintext + AEAD tag (16 bytes for both AES-GCM and ChaCha20-Poly1305)
+		scratch := sendBatch.Reserve(header.Len + len(seg) + 16)
+
+		out := f.sendInsideEncrypt(hostinfo, ci, seg, scratch, nb)
+		if out == nil {
+			return nil
+		}
+
+		sendBatch.Commit(out, hostinfo.remote, 0)
+		return nil
+	})
+	if err != nil {
+		hostinfo.logger(f.l).Error("Failed to segment superpacket for send",
+			"error", err,
+		)
+	}
+}
+
 func (f *Interface) rejectInside(packet []byte, out []byte, q int) {
 	if !f.firewall.InSendReject {
 		return
@@ -275,21 +414,13 @@ func (f *Interface) sendTo(t header.MessageType, st header.MessageSubType, ci *C
 	f.sendNoMetrics(t, st, ci, hostinfo, remote, p, nb, out, 0)
 }
 
-// SendVia sends a payload through a Relay tunnel. No authentication or encryption is done
-// to the payload for the ultimate target host, making this a useful method for sending
-// handshake messages to peers through relay tunnels.
-// via is the HostInfo through which the message is relayed.
-// ad is the plaintext data to authenticate, but not encrypt
-// nb is a buffer used to store the nonce value, re-used for performance reasons.
-// out is a buffer used to store the result of the Encrypt operation
-// q indicates which writer to use to send the packet.
-func (f *Interface) SendVia(via *HostInfo,
+func (f *Interface) prepareSendVia(via *HostInfo,
 	relay *Relay,
 	ad,
 	nb,
 	out []byte,
 	nocopy bool,
-) {
+) ([]byte, error) {
 	if noiseutil.EncryptLockNeeded {
 		// NOTE: for goboring AESGCMTLS we need to lock because of the nonce check
 		via.ConnectionState.writeLock.Lock()
@@ -311,7 +442,7 @@ func (f *Interface) SendVia(via *HostInfo,
 			"headerLen", len(out),
 			"cipherOverhead", via.ConnectionState.eKey.Overhead(),
 		)
-		return
+		return nil, io.ErrShortBuffer
 	}
 
 	// The header bytes are written to the 'out' slice; Grow the slice to hold the header and associated data payload.
@@ -331,13 +462,36 @@ func (f *Interface) SendVia(via *HostInfo,
 	}
 	if err != nil {
 		via.logger(f.l).Info("Failed to EncryptDanger in sendVia", "error", err)
+		return nil, err
+	}
+	f.connectionManager.RelayUsed(relay.LocalIndex)
+	return out, nil
+}
+
+// SendVia sends a payload through a Relay tunnel. No authentication or encryption is done
+// to the payload for the ultimate target host, making this a useful method for sending
+// handshake messages to peers through relay tunnels.
+// via is the HostInfo through which the message is relayed.
+// ad is the plaintext data to authenticate, but not encrypt
+// nb is a buffer used to store the nonce value, re-used for performance reasons.
+// out is a buffer used to store the result of the Encrypt operation
+// q indicates which writer to use to send the packet.
+func (f *Interface) SendVia(via *HostInfo,
+	relay *Relay,
+	ad,
+	nb,
+	out []byte,
+	nocopy bool,
+) {
+	toSend, err := f.prepareSendVia(via, relay, ad, nb, out, nocopy)
+	if err != nil {
+		via.logger(f.l).Info("Failed to prepareSendVia", "error", err)
 		return
 	}
-	err = f.writers[0].WriteTo(out, via.remote)
+	err = f.writers[0].WriteTo(toSend, via.remote)
 	if err != nil {
 		via.logger(f.l).Info("Failed to WriteTo in sendVia", "error", err)
 	}
-	f.connectionManager.RelayUsed(relay.LocalIndex)
 }
 
 func (f *Interface) sendNoMetrics(t header.MessageType, st header.MessageSubType, ci *ConnectionState, hostinfo *HostInfo, remote netip.AddrPort, p, nb, out []byte, q int) {

interface.go

@@ -4,7 +4,6 @@ import (
 	"context"
 	"errors"
 	"fmt"
-	"io"
 	"log/slog"
 	"net/netip"
 	"sync"
@@ -13,11 +12,15 @@ import (
 
 	"github.com/gaissmai/bart"
 	"github.com/rcrowley/go-metrics"
+	"github.com/slackhq/nebula/util"
+	"github.com/slackhq/nebula/wire"
 
 	"github.com/slackhq/nebula/config"
 	"github.com/slackhq/nebula/firewall"
 	"github.com/slackhq/nebula/header"
 	"github.com/slackhq/nebula/overlay"
+	"github.com/slackhq/nebula/overlay/batch"
+	"github.com/slackhq/nebula/overlay/tio"
 	"github.com/slackhq/nebula/udp"
 )
 
@@ -37,6 +40,7 @@ type InterfaceConfig struct {
 	DropLocalBroadcast bool
 	DropMulticast      bool
 	routines           int
+	batchSize          int
 	MessageMetrics     *MessageMetrics
 	version            string
 	relayManager       *relayManager
@@ -69,6 +73,7 @@ type Interface struct {
 	dropLocalBroadcast    bool
 	dropMulticast         bool
 	routines              int
+	batchSize             int
 	disconnectInvalid     atomic.Bool
 	closed                atomic.Bool
 	relayManager          *relayManager
@@ -88,8 +93,12 @@ type Interface struct {
 
 	ctx     context.Context
 	writers []udp.Conn
-	readers []io.ReadWriteCloser
-	wg      sync.WaitGroup
+	readers []tio.Queue
+	// batchers is one per tun queue, wrapping readers[i].
+	// decryptToTun sends plaintext into the batch.RxBatcher;
+	// listenOut calls its Flush at the end of each UDP recvmmsg batch.
+	batchers []batch.RxBatcher
+	wg       sync.WaitGroup
 
 	// fatalErr holds the first unexpected reader error that caused shutdown.
 	// nil means "no fatal error" (yet)
@@ -185,9 +194,11 @@ func NewInterface(ctx context.Context, c *InterfaceConfig) (*Interface, error) {
 		dropLocalBroadcast:    c.DropLocalBroadcast,
 		dropMulticast:         c.DropMulticast,
 		routines:              c.routines,
+		batchSize:             c.batchSize,
 		version:               c.version,
 		writers:               make([]udp.Conn, c.routines),
-		readers:               make([]io.ReadWriteCloser, c.routines),
+		readers:               make([]tio.Queue, c.routines),
+		batchers:              make([]batch.RxBatcher, c.routines),
 		myVpnNetworks:         cs.myVpnNetworks,
 		myVpnNetworksTable:    cs.myVpnNetworksTable,
 		myVpnAddrs:            cs.myVpnAddrs,
@@ -245,15 +256,17 @@ func (f *Interface) activate() error {
 	metrics.GetOrRegisterGauge("routines", nil).Update(int64(f.routines))
 
 	// Prepare n tun queues
-	var reader io.ReadWriteCloser = f.inside
 	for i := 0; i < f.routines; i++ {
 		if i > 0 {
-			reader, err = f.inside.NewMultiQueueReader()
-			if err != nil {
+			if err = f.inside.NewMultiQueueReader(); err != nil {
 				return err
 			}
 		}
-		f.readers[i] = reader
+	}
+	f.readers = f.inside.Readers()
+	for i := range f.readers {
+		arena := util.NewArena(max(f.batchSize, 1) * udp.MTU)
+		f.batchers[i] = batch.NewPassthrough(f.readers[i], f.batchSize, arena)
 	}
 
 	f.wg.Add(1) // for us to wait on Close() to return
@@ -311,14 +324,21 @@ func (f *Interface) listenOut(i int) {
 
 	ctCache := firewall.NewConntrackCacheTicker(f.ctx, f.l, f.conntrackCacheTimeout)
 	lhh := f.lightHouse.NewRequestHandler()
-	plaintext := make([]byte, udp.MTU)
 	h := &header.H{}
 	fwPacket := &firewall.Packet{}
 	nb := make([]byte, 12, 12)
 
-	err := li.ListenOut(func(fromUdpAddr netip.AddrPort, payload []byte) {
-		f.readOutsidePackets(ViaSender{UdpAddr: fromUdpAddr}, plaintext[:0], payload, h, fwPacket, lhh, nb, i, ctCache.Get())
-	})
+	listener := func(fromUdpAddr netip.AddrPort, payload []byte, meta udp.RxMeta) {
+		f.readOutsidePackets(ViaSender{UdpAddr: fromUdpAddr}, payload, h, fwPacket, lhh, nb, i, ctCache.Get())
+	}
+
+	flusher := func() {
+		if err := f.batchers[i].Flush(); err != nil {
+			f.l.Error("Failed to flush tun coalescer", "error", err)
+		}
+	}
+
+	err := li.ListenOut(listener, flusher)
 
 	if err != nil && !f.closed.Load() {
 		f.l.Error("Error while reading inbound packet, closing", "error", err)
@@ -328,28 +348,38 @@ func (f *Interface) listenOut(i int) {
 	f.l.Debug("underlay reader is done", "reader", i)
 }
 
-func (f *Interface) listenIn(reader io.ReadWriteCloser, i int) {
-	packet := make([]byte, mtu)
-	out := make([]byte, mtu)
+func (f *Interface) listenIn(reader tio.Queue, q int) {
+	packetMem := make([]byte, mtu+16) //MTU + some leading slack space for platforms that return "bonus info"
+	// TODO get the amount of bonus info from the reader
+	packets := make([]wire.TunPacket, 1)
+	rejectBuf := make([]byte, mtu)
+	arenaSize := batch.SendBatchCap * (udp.MTU + 32)
+	sb := batch.NewSendBatch(f.writers[q], batch.SendBatchCap, util.NewArena(arenaSize))
 	fwPacket := &firewall.Packet{}
 	nb := make([]byte, 12, 12)
 
 	conntrackCache := firewall.NewConntrackCacheTicker(f.ctx, f.l, f.conntrackCacheTimeout)
 
 	for {
-		n, err := reader.Read(packet)
+		n, err := reader.Read(packets, packetMem)
 		if err != nil {
 			if !f.closed.Load() {
-				f.l.Error("Error while reading outbound packet, closing", "error", err, "reader", i)
+				f.l.Error("Error while reading outbound packet, closing", "error", err, "reader", q)
 				f.onFatal(err)
 			}
 			break
 		}
 
-		f.consumeInsidePacket(packet[:n], fwPacket, nb, out, i, conntrackCache.Get())
+		ctCache := conntrackCache.Get()
+		for i := range n {
+			f.consumeInsidePacket(packets[i], fwPacket, nb, sb, rejectBuf, q, ctCache)
+		}
+		if err := sb.Flush(); err != nil {
+			f.l.Error("Failed to write outgoing batch", "error", err, "writer", q)
+		}
 	}
 
-	f.l.Debug("overlay reader is done", "reader", i)
+	f.l.Debug("overlay reader is done", "reader", q)
 }
 
 func (f *Interface) RegisterConfigChangeCallbacks(c *config.C) {

lighthouse.go

@@ -15,7 +15,6 @@ import (
 	"time"
 
 	"github.com/gaissmai/bart"
-	"github.com/rcrowley/go-metrics"
 	"github.com/slackhq/nebula/cert"
 	"github.com/slackhq/nebula/config"
 	"github.com/slackhq/nebula/header"
@@ -35,7 +34,6 @@ type LightHouse struct {
 
 	myVpnNetworks      []netip.Prefix
 	myVpnNetworksTable *bart.Lite
-	punchConn          udp.Conn
 	punchy             *Punchy
 
 	// Local cache of answers from light houses
@@ -75,9 +73,8 @@ type LightHouse struct {
 
 	calculatedRemotes atomic.Pointer[bart.Table[[]*calculatedRemote]] // Maps VpnAddr to []*calculatedRemote
 
-	metrics           *MessageMetrics
-	metricHolepunchTx metrics.Counter
-	l                 *slog.Logger
+	metrics *MessageMetrics
+	l       *slog.Logger
 }
 
 // NewLightHouseFromConfig will build a Lighthouse struct from the values provided in the config object
@@ -105,7 +102,6 @@ func NewLightHouseFromConfig(ctx context.Context, l *slog.Logger, c *config.C, c
 		myVpnNetworksTable: cs.myVpnNetworksTable,
 		addrMap:            make(map[netip.Addr]*RemoteList),
 		nebulaPort:         nebulaPort,
-		punchConn:          pc,
 		punchy:             p,
 		updateTrigger:      make(chan struct{}, 1),
 		queryChan:          make(chan netip.Addr, c.GetUint32("handshakes.query_buffer", 64)),
@@ -118,9 +114,6 @@ func NewLightHouseFromConfig(ctx context.Context, l *slog.Logger, c *config.C, c
 
 	if c.GetBool("stats.lighthouse_metrics", false) {
 		h.metrics = newLighthouseMetrics()
-		h.metricHolepunchTx = metrics.GetOrRegisterCounter("messages.tx.holepunch", nil)
-	} else {
-		h.metricHolepunchTx = metrics.NilCounter{}
 	}
 
 	err := h.reload(c, true)
@@ -1406,58 +1399,25 @@ func (lhh *LightHouseHandler) handleHostPunchNotification(n *NebulaMeta, fromVpn
 		return
 	}
 
-	empty := []byte{0}
-	punch := func(vpnPeer netip.AddrPort, logVpnAddr netip.Addr) {
-		if !vpnPeer.IsValid() {
-			return
-		}
-
-		go func() {
-			time.Sleep(lhh.lh.punchy.GetDelay())
-			lhh.lh.metricHolepunchTx.Inc(1)
-			lhh.lh.punchConn.WriteTo(empty, vpnPeer)
-		}()
-
-		if lhh.l.Enabled(context.Background(), slog.LevelDebug) {
-			lhh.l.Debug("Punching",
-				"vpnPeer", vpnPeer,
-				"logVpnAddr", logVpnAddr,
-			)
-		}
-	}
-
 	remoteAllowList := lhh.lh.GetRemoteAllowList()
 	for _, a := range n.Details.V4AddrPorts {
 		b := protoV4AddrPortToNetAddrPort(a)
 		if remoteAllowList.Allow(detailsVpnAddr, b.Addr()) {
-			punch(b, detailsVpnAddr)
+			lhh.lh.punchy.Schedule(b, detailsVpnAddr)
 		}
 	}
 
 	for _, a := range n.Details.V6AddrPorts {
 		b := protoV6AddrPortToNetAddrPort(a)
 		if remoteAllowList.Allow(detailsVpnAddr, b.Addr()) {
-			punch(b, detailsVpnAddr)
+			lhh.lh.punchy.Schedule(b, detailsVpnAddr)
 		}
 	}
 
 	// This sends a nebula test packet to the host trying to contact us. In the case
 	// of a double nat or other difficult scenario, this may help establish
-	// a tunnel.
-	if lhh.lh.punchy.GetRespond() {
-		go func() {
-			time.Sleep(lhh.lh.punchy.GetRespondDelay())
-			if lhh.l.Enabled(context.Background(), slog.LevelDebug) {
-				lhh.l.Debug("Sending a nebula test packet",
-					"vpnAddr", detailsVpnAddr,
-				)
-			}
-			//NOTE: we have to allocate a new output buffer here since we are spawning a new goroutine
-			// for each punchBack packet. We should move this into a timerwheel or a single goroutine
-			// managed by a channel.
-			w.SendMessageToVpnAddr(header.Test, header.TestRequest, detailsVpnAddr, []byte(""), make([]byte, 12, 12), make([]byte, mtu))
-		}()
-	}
+	// a tunnel. ScheduleRespond is a no-op when punchy.respond is disabled.
+	lhh.lh.punchy.ScheduleRespond(detailsVpnAddr)
 }
 
 func protoAddrToNetAddr(addr *Addr) netip.Addr {

main.go

@@ -55,7 +55,7 @@ func Main(c *config.C, configTest bool, buildVersion string, l *slog.Logger, dev
 	}
 	l.Info("Firewall started", "firewallHashes", fw.GetRuleHashes())
 
-	ssh, err := sshd.NewSSHServer(l.With("subsystem", "sshd"))
+	ssh, err := sshd.NewSSHServer(ctx, l.With("subsystem", "sshd"))
 	if err != nil {
 		return nil, util.ContextualizeIfNeeded("Error while creating SSH server", err)
 	}
@@ -170,7 +170,7 @@ func Main(c *config.C, configTest bool, buildVersion string, l *slog.Logger, dev
 	}
 
 	hostMap := NewHostMapFromConfig(l, c)
-	punchy := NewPunchyFromConfig(l, c)
+	punchy := NewPunchyFromConfig(l, c, udpConns[0])
 	connManager := newConnectionManagerFromConfig(l, c, hostMap, punchy)
 	lightHouse, err := NewLightHouseFromConfig(ctx, l, c, pki.getCertState(), udpConns[0], punchy)
 	if err != nil {
@@ -184,14 +184,10 @@ func Main(c *config.C, configTest bool, buildVersion string, l *slog.Logger, dev
 		messageMetrics = newMessageMetricsOnlyRecvError()
 	}
 
-	useRelays := c.GetBool("relay.use_relays", DefaultUseRelays) && !c.GetBool("relay.am_relay", false)
-
 	handshakeConfig := HandshakeConfig{
-		tryInterval:   c.GetDuration("handshakes.try_interval", DefaultHandshakeTryInterval),
-		retries:       int64(c.GetInt("handshakes.retries", DefaultHandshakeRetries)),
-		triggerBuffer: c.GetInt("handshakes.trigger_buffer", DefaultHandshakeTriggerBuffer),
-		useRelays:     useRelays,
-
+		tryInterval:    c.GetDuration("handshakes.try_interval", DefaultHandshakeTryInterval),
+		retries:        int64(c.GetInt("handshakes.retries", DefaultHandshakeRetries)),
+		triggerBuffer:  c.GetInt("handshakes.trigger_buffer", DefaultHandshakeTriggerBuffer),
 		messageMetrics: messageMetrics,
 	}
 
@@ -219,6 +215,7 @@ func Main(c *config.C, configTest bool, buildVersion string, l *slog.Logger, dev
 		DropLocalBroadcast:    c.GetBool("tun.drop_local_broadcast", false),
 		DropMulticast:         c.GetBool("tun.drop_multicast", false),
 		routines:              routines,
+		batchSize:             c.GetInt("listen.batch", 64),
 		MessageMetrics:        messageMetrics,
 		version:               buildVersion,
 		relayManager:          NewRelayManager(ctx, l, hostMap, c),
@@ -244,6 +241,8 @@ func Main(c *config.C, configTest bool, buildVersion string, l *slog.Logger, dev
 
 		handshakeManager.f = ifce
 		go handshakeManager.Run(ctx)
+
+		punchy.Start(ctx, ifce, hostMap, lightHouse)
 	}
 
 	stats, err := newStatsServerFromConfig(ctx, l, c, buildVersion, configTest)

message_metrics.go

@@ -13,6 +13,8 @@ type MessageMetrics struct {
 
 	rxUnknown metrics.Counter
 	txUnknown metrics.Counter
+
+	rxInvalid metrics.Counter
 }
 
 func (m *MessageMetrics) Rx(t header.MessageType, s header.MessageSubType, i int64) {
@@ -33,6 +35,11 @@ func (m *MessageMetrics) Tx(t header.MessageType, s header.MessageSubType, i int
 		}
 	}
 }
+func (m *MessageMetrics) RxInvalid(i int64) {
+	if m != nil && m.rxInvalid != nil {
+		m.rxInvalid.Inc(i)
+	}
+}
 
 func newMessageMetrics() *MessageMetrics {
 	gen := func(t string) [][]metrics.Counter {
@@ -56,6 +63,7 @@ func newMessageMetrics() *MessageMetrics {
 
 		rxUnknown: metrics.GetOrRegisterCounter("messages.rx.other", nil),
 		txUnknown: metrics.GetOrRegisterCounter("messages.tx.other", nil),
+		rxInvalid: metrics.GetOrRegisterCounter("messages.rx.invalid", nil),
 	}
 }
 

nebula.pb.go

@@ -124,7 +124,7 @@ func (x NebulaControl_MessageType) String() string {
 }
 
 func (NebulaControl_MessageType) EnumDescriptor() ([]byte, []int) {
-	return fileDescriptor_2d65afa7693df5ef, []int{8, 0}
+	return fileDescriptor_2d65afa7693df5ef, []int{6, 0}
 }
 
 type NebulaMeta struct {
@@ -489,142 +489,6 @@ func (m *NebulaPing) GetTime() uint64 {
 	return 0
 }
 
-type NebulaHandshake struct {
-	Details *NebulaHandshakeDetails `protobuf:"bytes,1,opt,name=Details,proto3" json:"Details,omitempty"`
-	Hmac    []byte                  `protobuf:"bytes,2,opt,name=Hmac,proto3" json:"Hmac,omitempty"`
-}
-
-func (m *NebulaHandshake) Reset()         { *m = NebulaHandshake{} }
-func (m *NebulaHandshake) String() string { return proto.CompactTextString(m) }
-func (*NebulaHandshake) ProtoMessage()    {}
-func (*NebulaHandshake) Descriptor() ([]byte, []int) {
-	return fileDescriptor_2d65afa7693df5ef, []int{6}
-}
-func (m *NebulaHandshake) XXX_Unmarshal(b []byte) error {
-	return m.Unmarshal(b)
-}
-func (m *NebulaHandshake) XXX_Marshal(b []byte, deterministic bool) ([]byte, error) {
-	if deterministic {
-		return xxx_messageInfo_NebulaHandshake.Marshal(b, m, deterministic)
-	} else {
-		b = b[:cap(b)]
-		n, err := m.MarshalToSizedBuffer(b)
-		if err != nil {
-			return nil, err
-		}
-		return b[:n], nil
-	}
-}
-func (m *NebulaHandshake) XXX_Merge(src proto.Message) {
-	xxx_messageInfo_NebulaHandshake.Merge(m, src)
-}
-func (m *NebulaHandshake) XXX_Size() int {
-	return m.Size()
-}
-func (m *NebulaHandshake) XXX_DiscardUnknown() {
-	xxx_messageInfo_NebulaHandshake.DiscardUnknown(m)
-}
-
-var xxx_messageInfo_NebulaHandshake proto.InternalMessageInfo
-
-func (m *NebulaHandshake) GetDetails() *NebulaHandshakeDetails {
-	if m != nil {
-		return m.Details
-	}
-	return nil
-}
-
-func (m *NebulaHandshake) GetHmac() []byte {
-	if m != nil {
-		return m.Hmac
-	}
-	return nil
-}
-
-type NebulaHandshakeDetails struct {
-	Cert           []byte `protobuf:"bytes,1,opt,name=Cert,proto3" json:"Cert,omitempty"`
-	InitiatorIndex uint32 `protobuf:"varint,2,opt,name=InitiatorIndex,proto3" json:"InitiatorIndex,omitempty"`
-	ResponderIndex uint32 `protobuf:"varint,3,opt,name=ResponderIndex,proto3" json:"ResponderIndex,omitempty"`
-	Cookie         uint64 `protobuf:"varint,4,opt,name=Cookie,proto3" json:"Cookie,omitempty"`
-	Time           uint64 `protobuf:"varint,5,opt,name=Time,proto3" json:"Time,omitempty"`
-	CertVersion    uint32 `protobuf:"varint,8,opt,name=CertVersion,proto3" json:"CertVersion,omitempty"`
-}
-
-func (m *NebulaHandshakeDetails) Reset()         { *m = NebulaHandshakeDetails{} }
-func (m *NebulaHandshakeDetails) String() string { return proto.CompactTextString(m) }
-func (*NebulaHandshakeDetails) ProtoMessage()    {}
-func (*NebulaHandshakeDetails) Descriptor() ([]byte, []int) {
-	return fileDescriptor_2d65afa7693df5ef, []int{7}
-}
-func (m *NebulaHandshakeDetails) XXX_Unmarshal(b []byte) error {
-	return m.Unmarshal(b)
-}
-func (m *NebulaHandshakeDetails) XXX_Marshal(b []byte, deterministic bool) ([]byte, error) {
-	if deterministic {
-		return xxx_messageInfo_NebulaHandshakeDetails.Marshal(b, m, deterministic)
-	} else {
-		b = b[:cap(b)]
-		n, err := m.MarshalToSizedBuffer(b)
-		if err != nil {
-			return nil, err
-		}
-		return b[:n], nil
-	}
-}
-func (m *NebulaHandshakeDetails) XXX_Merge(src proto.Message) {
-	xxx_messageInfo_NebulaHandshakeDetails.Merge(m, src)
-}
-func (m *NebulaHandshakeDetails) XXX_Size() int {
-	return m.Size()
-}
-func (m *NebulaHandshakeDetails) XXX_DiscardUnknown() {
-	xxx_messageInfo_NebulaHandshakeDetails.DiscardUnknown(m)
-}
-
-var xxx_messageInfo_NebulaHandshakeDetails proto.InternalMessageInfo
-
-func (m *NebulaHandshakeDetails) GetCert() []byte {
-	if m != nil {
-		return m.Cert
-	}
-	return nil
-}
-
-func (m *NebulaHandshakeDetails) GetInitiatorIndex() uint32 {
-	if m != nil {
-		return m.InitiatorIndex
-	}
-	return 0
-}
-
-func (m *NebulaHandshakeDetails) GetResponderIndex() uint32 {
-	if m != nil {
-		return m.ResponderIndex
-	}
-	return 0
-}
-
-func (m *NebulaHandshakeDetails) GetCookie() uint64 {
-	if m != nil {
-		return m.Cookie
-	}
-	return 0
-}
-
-func (m *NebulaHandshakeDetails) GetTime() uint64 {
-	if m != nil {
-		return m.Time
-	}
-	return 0
-}
-
-func (m *NebulaHandshakeDetails) GetCertVersion() uint32 {
-	if m != nil {
-		return m.CertVersion
-	}
-	return 0
-}
-
 type NebulaControl struct {
 	Type                NebulaControl_MessageType `protobuf:"varint,1,opt,name=Type,proto3,enum=nebula.NebulaControl_MessageType" json:"Type,omitempty"`
 	InitiatorRelayIndex uint32                    `protobuf:"varint,2,opt,name=InitiatorRelayIndex,proto3" json:"InitiatorRelayIndex,omitempty"`
@@ -639,7 +503,7 @@ func (m *NebulaControl) Reset()         { *m = NebulaControl{} }
 func (m *NebulaControl) String() string { return proto.CompactTextString(m) }
 func (*NebulaControl) ProtoMessage()    {}
 func (*NebulaControl) Descriptor() ([]byte, []int) {
-	return fileDescriptor_2d65afa7693df5ef, []int{8}
+	return fileDescriptor_2d65afa7693df5ef, []int{6}
 }
 func (m *NebulaControl) XXX_Unmarshal(b []byte) error {
 	return m.Unmarshal(b)
@@ -729,65 +593,55 @@ func init() {
 	proto.RegisterType((*V4AddrPort)(nil), "nebula.V4AddrPort")
 	proto.RegisterType((*V6AddrPort)(nil), "nebula.V6AddrPort")
 	proto.RegisterType((*NebulaPing)(nil), "nebula.NebulaPing")
-	proto.RegisterType((*NebulaHandshake)(nil), "nebula.NebulaHandshake")
-	proto.RegisterType((*NebulaHandshakeDetails)(nil), "nebula.NebulaHandshakeDetails")
 	proto.RegisterType((*NebulaControl)(nil), "nebula.NebulaControl")
 }
 
 func init() { proto.RegisterFile("nebula.proto", fileDescriptor_2d65afa7693df5ef) }
 
 var fileDescriptor_2d65afa7693df5ef = []byte{
-	// 785 bytes of a gzipped FileDescriptorProto
-	0x1f, 0x8b, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02, 0xff, 0x84, 0x55, 0xcd, 0x6e, 0xeb, 0x44,
-	0x14, 0x8e, 0x1d, 0x27, 0x4e, 0x4f, 0x7e, 0xae, 0x39, 0x15, 0xc1, 0x41, 0x22, 0x0a, 0x5e, 0x54,
-	0x57, 0x2c, 0x72, 0x51, 0x5a, 0xae, 0x58, 0x72, 0x1b, 0x84, 0xd2, 0xaa, 0x3f, 0x61, 0x54, 0x8a,
-	0xc4, 0x06, 0xb9, 0xf6, 0xd0, 0x58, 0x71, 0x3c, 0xa9, 0x3d, 0x41, 0xcd, 0x5b, 0xf0, 0x30, 0x3c,
-	0x04, 0xec, 0xba, 0x42, 0x2c, 0x51, 0xbb, 0x64, 0xc9, 0x0b, 0xa0, 0x19, 0xff, 0x27, 0x86, 0xbb,
-	0x9b, 0x73, 0xbe, 0xef, 0x3b, 0x73, 0xe6, 0xf3, 0x9c, 0x31, 0x74, 0x02, 0x7a, 0xb7, 0xf1, 0xed,
-	0xf1, 0x3a, 0x64, 0x9c, 0x61, 0x33, 0x8e, 0xac, 0xbf, 0x55, 0x80, 0x2b, 0xb9, 0xbc, 0xa4, 0xdc,
-	0xc6, 0x09, 0x68, 0x37, 0xdb, 0x35, 0x35, 0x95, 0x91, 0xf2, 0xba, 0x37, 0x19, 0x8e, 0x13, 0x4d,
-	0xce, 0x18, 0x5f, 0xd2, 0x28, 0xb2, 0xef, 0xa9, 0x60, 0x11, 0xc9, 0xc5, 0x63, 0xd0, 0xbf, 0xa6,
-	0xdc, 0xf6, 0xfc, 0xc8, 0x54, 0x47, 0xca, 0xeb, 0xf6, 0x64, 0xb0, 0x2f, 0x4b, 0x08, 0x24, 0x65,
-	0x5a, 0xff, 0x28, 0xd0, 0x2e, 0x94, 0xc2, 0x16, 0x68, 0x57, 0x2c, 0xa0, 0x46, 0x0d, 0xbb, 0x70,
-	0x30, 0x63, 0x11, 0xff, 0x76, 0x43, 0xc3, 0xad, 0xa1, 0x20, 0x42, 0x2f, 0x0b, 0x09, 0x5d, 0xfb,
-	0x5b, 0x43, 0xc5, 0x8f, 0xa1, 0x2f, 0x72, 0xdf, 0xad, 0x5d, 0x9b, 0xd3, 0x2b, 0xc6, 0xbd, 0x9f,
-	0x3c, 0xc7, 0xe6, 0x1e, 0x0b, 0x8c, 0x3a, 0x0e, 0xe0, 0x43, 0x81, 0x5d, 0xb2, 0x9f, 0xa9, 0x5b,
-	0x82, 0xb4, 0x14, 0x9a, 0x6f, 0x02, 0x67, 0x51, 0x82, 0x1a, 0xd8, 0x03, 0x10, 0xd0, 0xf7, 0x0b,
-	0x66, 0xaf, 0x3c, 0xa3, 0x89, 0x87, 0xf0, 0x2a, 0x8f, 0xe3, 0x6d, 0x75, 0xd1, 0xd9, 0xdc, 0xe6,
-	0x8b, 0xe9, 0x82, 0x3a, 0x4b, 0xa3, 0x25, 0x3a, 0xcb, 0xc2, 0x98, 0x72, 0x80, 0x9f, 0xc0, 0xa0,
-	0xba, 0xb3, 0x77, 0xce, 0xd2, 0x00, 0xeb, 0x77, 0x15, 0x3e, 0xd8, 0x33, 0x05, 0x2d, 0x80, 0x6b,
-	0xdf, 0xbd, 0x5d, 0x07, 0xef, 0x5c, 0x37, 0x94, 0xd6, 0x77, 0x4f, 0x55, 0x53, 0x21, 0x85, 0x2c,
-	0x1e, 0x81, 0x9e, 0x12, 0x9a, 0xd2, 0xe4, 0x4e, 0x6a, 0xb2, 0xc8, 0x91, 0x14, 0xc4, 0x31, 0x18,
-	0xd7, 0xbe, 0x4b, 0xa8, 0x6f, 0x6f, 0x93, 0x54, 0x64, 0x36, 0x46, 0xf5, 0xa4, 0xe2, 0x1e, 0x86,
-	0x13, 0xe8, 0x96, 0xc9, 0xfa, 0xa8, 0xbe, 0x57, 0xbd, 0x4c, 0xc1, 0x13, 0x68, 0xdf, 0x9e, 0x88,
-	0xe5, 0x9c, 0x85, 0x5c, 0x7c, 0x74, 0xa1, 0xc0, 0x54, 0x91, 0x43, 0xa4, 0x48, 0x93, 0xaa, 0xb7,
-	0xb9, 0x4a, 0xdb, 0x51, 0xbd, 0x2d, 0xa8, 0x72, 0x1a, 0x9a, 0xa0, 0x3b, 0x6c, 0x13, 0x70, 0x1a,
-	0x9a, 0x75, 0x61, 0x0c, 0x49, 0x43, 0xeb, 0x08, 0x34, 0x79, 0xe2, 0x1e, 0xa8, 0x33, 0x4f, 0xba,
-	0xa6, 0x11, 0x75, 0xe6, 0x89, 0xf8, 0x82, 0xc9, 0x9b, 0xa8, 0x11, 0xf5, 0x82, 0x59, 0x27, 0x00,
-	0x79, 0x1b, 0x88, 0xb1, 0x2a, 0x76, 0x99, 0xc4, 0x15, 0x10, 0x34, 0x81, 0x49, 0x4d, 0x97, 0xc8,
-	0xb5, 0xf5, 0x15, 0x40, 0xde, 0xc6, 0xfb, 0xf6, 0xc8, 0x2a, 0xd4, 0x0b, 0x15, 0x1e, 0xd3, 0xc1,
-	0x9a, 0x7b, 0xc1, 0xfd, 0xff, 0x0f, 0x96, 0x60, 0x54, 0x0c, 0x16, 0x82, 0x76, 0xe3, 0xad, 0x68,
-	0xb2, 0x8f, 0x5c, 0x5b, 0xd6, 0xde, 0xd8, 0x08, 0xb1, 0x51, 0xc3, 0x03, 0x68, 0xc4, 0x97, 0x50,
-	0xb1, 0x7e, 0x84, 0x57, 0x71, 0xdd, 0x99, 0x1d, 0xb8, 0xd1, 0xc2, 0x5e, 0x52, 0xfc, 0x32, 0x9f,
-	0x51, 0x45, 0x5e, 0x9f, 0x9d, 0x0e, 0x32, 0xe6, 0xee, 0xa0, 0x8a, 0x26, 0x66, 0x2b, 0xdb, 0x91,
-	0x4d, 0x74, 0x88, 0x5c, 0x5b, 0x7f, 0x28, 0xd0, 0xaf, 0xd6, 0x09, 0xfa, 0x94, 0x86, 0x5c, 0xee,
-	0xd2, 0x21, 0x72, 0x8d, 0x47, 0xd0, 0x3b, 0x0b, 0x3c, 0xee, 0xd9, 0x9c, 0x85, 0x67, 0x81, 0x4b,
-	0x1f, 0x13, 0xa7, 0x77, 0xb2, 0x82, 0x47, 0x68, 0xb4, 0x66, 0x81, 0x4b, 0x13, 0x5e, 0xec, 0xe7,
-	0x4e, 0x16, 0xfb, 0xd0, 0x9c, 0x32, 0xb6, 0xf4, 0xa8, 0xa9, 0x49, 0x67, 0x92, 0x28, 0xf3, 0xab,
-	0x91, 0xfb, 0x85, 0x23, 0x68, 0x8b, 0x1e, 0x6e, 0x69, 0x18, 0x79, 0x2c, 0x30, 0x5b, 0xb2, 0x60,
-	0x31, 0x75, 0xae, 0xb5, 0x9a, 0x86, 0x7e, 0xae, 0xb5, 0x74, 0xa3, 0x65, 0xfd, 0x5a, 0x87, 0x6e,
-	0x7c, 0xb0, 0x29, 0x0b, 0x78, 0xc8, 0x7c, 0xfc, 0xa2, 0xf4, 0xdd, 0x3e, 0x2d, 0xbb, 0x96, 0x90,
-	0x2a, 0x3e, 0xdd, 0xe7, 0x70, 0x98, 0x1d, 0x4e, 0x0e, 0x4f, 0xf1, 0xdc, 0x55, 0x90, 0x50, 0x64,
-	0xc7, 0x2c, 0x28, 0x62, 0x07, 0xaa, 0x20, 0xfc, 0x0c, 0x7a, 0xe9, 0x38, 0xdf, 0x30, 0x79, 0xa9,
-	0xb5, 0xec, 0xe9, 0xd8, 0x41, 0x8a, 0xcf, 0xc2, 0x37, 0x21, 0x5b, 0x49, 0x76, 0x23, 0x63, 0xef,
-	0x61, 0x38, 0x86, 0x76, 0xb1, 0x70, 0xd5, 0x93, 0x53, 0x24, 0x64, 0xcf, 0x48, 0x56, 0x5c, 0xaf,
-	0x50, 0x94, 0x29, 0xd6, 0xec, 0xbf, 0xfe, 0x00, 0x7d, 0xc0, 0x69, 0x48, 0x6d, 0x4e, 0x25, 0x9f,
-	0xd0, 0x87, 0x0d, 0x8d, 0xb8, 0xa1, 0xe0, 0x47, 0x70, 0x58, 0xca, 0x0b, 0x4b, 0x22, 0x6a, 0xa8,
-	0xa7, 0xc7, 0xbf, 0x3d, 0x0f, 0x95, 0xa7, 0xe7, 0xa1, 0xf2, 0xd7, 0xf3, 0x50, 0xf9, 0xe5, 0x65,
-	0x58, 0x7b, 0x7a, 0x19, 0xd6, 0xfe, 0x7c, 0x19, 0xd6, 0x7e, 0x18, 0xdc, 0x7b, 0x7c, 0xb1, 0xb9,
-	0x1b, 0x3b, 0x6c, 0xf5, 0x26, 0xf2, 0x6d, 0x67, 0xb9, 0x78, 0x78, 0x13, 0xb7, 0x74, 0xd7, 0x94,
-	0x3f, 0xc2, 0xe3, 0x7f, 0x03, 0x00, 0x00, 0xff, 0xff, 0xea, 0x6f, 0xbc, 0x50, 0x18, 0x07, 0x00,
-	0x00,
+	// 665 bytes of a gzipped FileDescriptorProto
+	0x1f, 0x8b, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02, 0xff, 0x84, 0x54, 0xcd, 0x6e, 0xd3, 0x5c,
+	0x10, 0x8d, 0x1d, 0x27, 0x69, 0x27, 0x4d, 0x3e, 0x7f, 0x53, 0x51, 0x12, 0x24, 0xac, 0xe0, 0x45,
+	0x55, 0xb1, 0x48, 0x51, 0x5a, 0xba, 0xa6, 0x2d, 0x42, 0xa9, 0xd4, 0x9f, 0x70, 0x55, 0x8a, 0xc4,
+	0xce, 0xb5, 0x2f, 0x8d, 0x55, 0xc7, 0x37, 0xb5, 0x6f, 0x50, 0xf3, 0x16, 0x3c, 0x0c, 0x0f, 0x01,
+	0xbb, 0x2e, 0x59, 0xa2, 0x66, 0xc9, 0x92, 0x17, 0x40, 0xf7, 0xfa, 0xbf, 0x31, 0xb0, 0xbb, 0x33,
+	0xe7, 0x9c, 0x99, 0xc9, 0xc9, 0x8c, 0x61, 0xcd, 0xa7, 0x97, 0x33, 0xcf, 0xea, 0x4f, 0x03, 0xc6,
+	0x19, 0xd6, 0xa3, 0xc8, 0xfc, 0xa9, 0x02, 0x9c, 0xca, 0xe7, 0x09, 0xe5, 0x16, 0x0e, 0x40, 0x3b,
+	0x9f, 0x4f, 0x69, 0x47, 0xe9, 0x29, 0x5b, 0xed, 0x81, 0xd1, 0x8f, 0x35, 0x19, 0xa3, 0x7f, 0x42,
+	0xc3, 0xd0, 0xba, 0xa2, 0x82, 0x45, 0x24, 0x17, 0x77, 0xa0, 0xf1, 0x9a, 0x72, 0xcb, 0xf5, 0xc2,
+	0x8e, 0xda, 0x53, 0xb6, 0x9a, 0x83, 0xee, 0xb2, 0x2c, 0x26, 0x90, 0x84, 0x69, 0xfe, 0x52, 0xa0,
+	0x99, 0x2b, 0x85, 0x2b, 0xa0, 0x9d, 0x32, 0x9f, 0xea, 0x15, 0x6c, 0xc1, 0xea, 0x90, 0x85, 0xfc,
+	0xed, 0x8c, 0x06, 0x73, 0x5d, 0x41, 0x84, 0x76, 0x1a, 0x12, 0x3a, 0xf5, 0xe6, 0xba, 0x8a, 0x4f,
+	0x60, 0x43, 0xe4, 0xde, 0x4d, 0x1d, 0x8b, 0xd3, 0x53, 0xc6, 0xdd, 0x8f, 0xae, 0x6d, 0x71, 0x97,
+	0xf9, 0x7a, 0x15, 0xbb, 0xf0, 0x48, 0x60, 0x27, 0xec, 0x13, 0x75, 0x0a, 0x90, 0x96, 0x40, 0xa3,
+	0x99, 0x6f, 0x8f, 0x0b, 0x50, 0x0d, 0xdb, 0x00, 0x02, 0x7a, 0x3f, 0x66, 0xd6, 0xc4, 0xd5, 0xeb,
+	0xb8, 0x0e, 0xff, 0x65, 0x71, 0xd4, 0xb6, 0x21, 0x26, 0x1b, 0x59, 0x7c, 0x7c, 0x38, 0xa6, 0xf6,
+	0xb5, 0xbe, 0x22, 0x26, 0x4b, 0xc3, 0x88, 0xb2, 0x8a, 0x4f, 0xa1, 0x5b, 0x3e, 0xd9, 0xbe, 0x7d,
+	0xad, 0x83, 0xf9, 0x4d, 0x85, 0xff, 0x97, 0x4c, 0x41, 0x13, 0xe0, 0xcc, 0x73, 0x2e, 0xa6, 0xfe,
+	0xbe, 0xe3, 0x04, 0xd2, 0xfa, 0xd6, 0x81, 0xda, 0x51, 0x48, 0x2e, 0x8b, 0x9b, 0xd0, 0x48, 0x08,
+	0x75, 0x69, 0xf2, 0x5a, 0x62, 0xb2, 0xc8, 0x91, 0x04, 0xc4, 0x3e, 0xe8, 0x67, 0x9e, 0x43, 0xa8,
+	0x67, 0xcd, 0xe3, 0x54, 0xd8, 0xa9, 0xf5, 0xaa, 0x71, 0xc5, 0x25, 0x0c, 0x07, 0xd0, 0x2a, 0x92,
+	0x1b, 0xbd, 0xea, 0x52, 0xf5, 0x22, 0x05, 0x77, 0xa1, 0x79, 0xb1, 0x2b, 0x9e, 0x23, 0x16, 0x70,
+	0xf1, 0xa7, 0x0b, 0x05, 0x26, 0x8a, 0x0c, 0x22, 0x79, 0x9a, 0x54, 0xed, 0x65, 0x2a, 0xed, 0x81,
+	0x6a, 0x2f, 0xa7, 0xca, 0x68, 0xd8, 0x81, 0x86, 0xcd, 0x66, 0x3e, 0xa7, 0x41, 0xa7, 0x2a, 0x8c,
+	0x21, 0x49, 0x68, 0x6e, 0x82, 0x26, 0x7f, 0x71, 0x1b, 0xd4, 0xa1, 0x2b, 0x5d, 0xd3, 0x88, 0x3a,
+	0x74, 0x45, 0x7c, 0xcc, 0xe4, 0x26, 0x6a, 0x44, 0x3d, 0x66, 0xe6, 0x2e, 0x40, 0x36, 0x06, 0x62,
+	0xa4, 0x8a, 0x5c, 0x26, 0x51, 0x05, 0x04, 0x4d, 0x60, 0x52, 0xd3, 0x22, 0xf2, 0x6d, 0xbe, 0x02,
+	0xc8, 0xc6, 0xf8, 0x57, 0x8f, 0xb4, 0x42, 0x35, 0x57, 0xe1, 0x36, 0x39, 0xac, 0x91, 0xeb, 0x5f,
+	0xfd, 0xfd, 0xb0, 0x04, 0xa3, 0xe4, 0xb0, 0x10, 0xb4, 0x73, 0x77, 0x42, 0xe3, 0x3e, 0xf2, 0x6d,
+	0x9a, 0x4b, 0x67, 0x23, 0xc4, 0x7a, 0x05, 0x57, 0xa1, 0x16, 0x2d, 0xa1, 0x62, 0x7e, 0xa9, 0x42,
+	0x2b, 0x2a, 0x7c, 0xc8, 0x7c, 0x1e, 0x30, 0x0f, 0x5f, 0x16, 0xba, 0x3f, 0x2b, 0x76, 0x8f, 0x49,
+	0x25, 0x03, 0xbc, 0x80, 0xf5, 0x23, 0xdf, 0xe5, 0xae, 0xc5, 0x59, 0x20, 0x57, 0xe0, 0xc8, 0x77,
+	0xe8, 0x6d, 0xec, 0x53, 0x19, 0x24, 0x14, 0x84, 0x86, 0x53, 0xe6, 0x3b, 0x34, 0xaf, 0x88, 0x7c,
+	0x29, 0x83, 0xf0, 0x39, 0xb4, 0x93, 0xa5, 0x3c, 0x67, 0xf2, 0xaf, 0xd1, 0xd2, 0x03, 0x78, 0x80,
+	0xe4, 0x97, 0xfb, 0x4d, 0xc0, 0x26, 0x92, 0x5d, 0x4b, 0xd9, 0x4b, 0x18, 0xf6, 0xa1, 0x99, 0x2f,
+	0x5c, 0x76, 0x38, 0x79, 0x42, 0x7a, 0x0c, 0x69, 0xf1, 0x46, 0x89, 0xa2, 0x48, 0x31, 0x87, 0x7f,
+	0xfa, 0x8e, 0x6d, 0x00, 0x1e, 0x06, 0xd4, 0xe2, 0x54, 0xf2, 0x09, 0xbd, 0x99, 0xd1, 0x90, 0xeb,
+	0x0a, 0x3e, 0x86, 0xf5, 0x42, 0x5e, 0x58, 0x12, 0x52, 0x5d, 0x3d, 0xd8, 0xf9, 0x7a, 0x6f, 0x28,
+	0x77, 0xf7, 0x86, 0xf2, 0xe3, 0xde, 0x50, 0x3e, 0x2f, 0x8c, 0xca, 0xdd, 0xc2, 0xa8, 0x7c, 0x5f,
+	0x18, 0x95, 0x0f, 0xdd, 0x2b, 0x97, 0x8f, 0x67, 0x97, 0x7d, 0x9b, 0x4d, 0xb6, 0x43, 0xcf, 0xb2,
+	0xaf, 0xc7, 0x37, 0xdb, 0xd1, 0x48, 0x97, 0x75, 0xf9, 0x39, 0xdf, 0xf9, 0x1d, 0x00, 0x00, 0xff,
+	0xff, 0x51, 0x0a, 0xe3, 0xd7, 0xde, 0x05, 0x00, 0x00,
 }
 
 func (m *NebulaMeta) Marshal() (dAtA []byte, err error) {
@@ -1072,103 +926,6 @@ func (m *NebulaPing) MarshalToSizedBuffer(dAtA []byte) (int, error) {
 	return len(dAtA) - i, nil
 }
 
-func (m *NebulaHandshake) Marshal() (dAtA []byte, err error) {
-	size := m.Size()
-	dAtA = make([]byte, size)
-	n, err := m.MarshalToSizedBuffer(dAtA[:size])
-	if err != nil {
-		return nil, err
-	}
-	return dAtA[:n], nil
-}
-
-func (m *NebulaHandshake) MarshalTo(dAtA []byte) (int, error) {
-	size := m.Size()
-	return m.MarshalToSizedBuffer(dAtA[:size])
-}
-
-func (m *NebulaHandshake) MarshalToSizedBuffer(dAtA []byte) (int, error) {
-	i := len(dAtA)
-	_ = i
-	var l int
-	_ = l
-	if len(m.Hmac) > 0 {
-		i -= len(m.Hmac)
-		copy(dAtA[i:], m.Hmac)
-		i = encodeVarintNebula(dAtA, i, uint64(len(m.Hmac)))
-		i--
-		dAtA[i] = 0x12
-	}
-	if m.Details != nil {
-		{
-			size, err := m.Details.MarshalToSizedBuffer(dAtA[:i])
-			if err != nil {
-				return 0, err
-			}
-			i -= size
-			i = encodeVarintNebula(dAtA, i, uint64(size))
-		}
-		i--
-		dAtA[i] = 0xa
-	}
-	return len(dAtA) - i, nil
-}
-
-func (m *NebulaHandshakeDetails) Marshal() (dAtA []byte, err error) {
-	size := m.Size()
-	dAtA = make([]byte, size)
-	n, err := m.MarshalToSizedBuffer(dAtA[:size])
-	if err != nil {
-		return nil, err
-	}
-	return dAtA[:n], nil
-}
-
-func (m *NebulaHandshakeDetails) MarshalTo(dAtA []byte) (int, error) {
-	size := m.Size()
-	return m.MarshalToSizedBuffer(dAtA[:size])
-}
-
-func (m *NebulaHandshakeDetails) MarshalToSizedBuffer(dAtA []byte) (int, error) {
-	i := len(dAtA)
-	_ = i
-	var l int
-	_ = l
-	if m.CertVersion != 0 {
-		i = encodeVarintNebula(dAtA, i, uint64(m.CertVersion))
-		i--
-		dAtA[i] = 0x40
-	}
-	if m.Time != 0 {
-		i = encodeVarintNebula(dAtA, i, uint64(m.Time))
-		i--
-		dAtA[i] = 0x28
-	}
-	if m.Cookie != 0 {
-		i = encodeVarintNebula(dAtA, i, uint64(m.Cookie))
-		i--
-		dAtA[i] = 0x20
-	}
-	if m.ResponderIndex != 0 {
-		i = encodeVarintNebula(dAtA, i, uint64(m.ResponderIndex))
-		i--
-		dAtA[i] = 0x18
-	}
-	if m.InitiatorIndex != 0 {
-		i = encodeVarintNebula(dAtA, i, uint64(m.InitiatorIndex))
-		i--
-		dAtA[i] = 0x10
-	}
-	if len(m.Cert) > 0 {
-		i -= len(m.Cert)
-		copy(dAtA[i:], m.Cert)
-		i = encodeVarintNebula(dAtA, i, uint64(len(m.Cert)))
-		i--
-		dAtA[i] = 0xa
-	}
-	return len(dAtA) - i, nil
-}
-
 func (m *NebulaControl) Marshal() (dAtA []byte, err error) {
 	size := m.Size()
 	dAtA = make([]byte, size)
@@ -1375,51 +1132,6 @@ func (m *NebulaPing) Size() (n int) {
 	return n
 }
 
-func (m *NebulaHandshake) Size() (n int) {
-	if m == nil {
-		return 0
-	}
-	var l int
-	_ = l
-	if m.Details != nil {
-		l = m.Details.Size()
-		n += 1 + l + sovNebula(uint64(l))
-	}
-	l = len(m.Hmac)
-	if l > 0 {
-		n += 1 + l + sovNebula(uint64(l))
-	}
-	return n
-}
-
-func (m *NebulaHandshakeDetails) Size() (n int) {
-	if m == nil {
-		return 0
-	}
-	var l int
-	_ = l
-	l = len(m.Cert)
-	if l > 0 {
-		n += 1 + l + sovNebula(uint64(l))
-	}
-	if m.InitiatorIndex != 0 {
-		n += 1 + sovNebula(uint64(m.InitiatorIndex))
-	}
-	if m.ResponderIndex != 0 {
-		n += 1 + sovNebula(uint64(m.ResponderIndex))
-	}
-	if m.Cookie != 0 {
-		n += 1 + sovNebula(uint64(m.Cookie))
-	}
-	if m.Time != 0 {
-		n += 1 + sovNebula(uint64(m.Time))
-	}
-	if m.CertVersion != 0 {
-		n += 1 + sovNebula(uint64(m.CertVersion))
-	}
-	return n
-}
-
 func (m *NebulaControl) Size() (n int) {
 	if m == nil {
 		return 0
@@ -2236,305 +1948,6 @@ func (m *NebulaPing) Unmarshal(dAtA []byte) error {
 	}
 	return nil
 }
-func (m *NebulaHandshake) Unmarshal(dAtA []byte) error {
-	l := len(dAtA)
-	iNdEx := 0
-	for iNdEx < l {
-		preIndex := iNdEx
-		var wire uint64
-		for shift := uint(0); ; shift += 7 {
-			if shift >= 64 {
-				return ErrIntOverflowNebula
-			}
-			if iNdEx >= l {
-				return io.ErrUnexpectedEOF
-			}
-			b := dAtA[iNdEx]
-			iNdEx++
-			wire |= uint64(b&0x7F) << shift
-			if b < 0x80 {
-				break
-			}
-		}
-		fieldNum := int32(wire >> 3)
-		wireType := int(wire & 0x7)
-		if wireType == 4 {
-			return fmt.Errorf("proto: NebulaHandshake: wiretype end group for non-group")
-		}
-		if fieldNum <= 0 {
-			return fmt.Errorf("proto: NebulaHandshake: illegal tag %d (wire type %d)", fieldNum, wire)
-		}
-		switch fieldNum {
-		case 1:
-			if wireType != 2 {
-				return fmt.Errorf("proto: wrong wireType = %d for field Details", wireType)
-			}
-			var msglen int
-			for shift := uint(0); ; shift += 7 {
-				if shift >= 64 {
-					return ErrIntOverflowNebula
-				}
-				if iNdEx >= l {
-					return io.ErrUnexpectedEOF
-				}
-				b := dAtA[iNdEx]
-				iNdEx++
-				msglen |= int(b&0x7F) << shift
-				if b < 0x80 {
-					break
-				}
-			}
-			if msglen < 0 {
-				return ErrInvalidLengthNebula
-			}
-			postIndex := iNdEx + msglen
-			if postIndex < 0 {
-				return ErrInvalidLengthNebula
-			}
-			if postIndex > l {
-				return io.ErrUnexpectedEOF
-			}
-			if m.Details == nil {
-				m.Details = &NebulaHandshakeDetails{}
-			}
-			if err := m.Details.Unmarshal(dAtA[iNdEx:postIndex]); err != nil {
-				return err
-			}
-			iNdEx = postIndex
-		case 2:
-			if wireType != 2 {
-				return fmt.Errorf("proto: wrong wireType = %d for field Hmac", wireType)
-			}
-			var byteLen int
-			for shift := uint(0); ; shift += 7 {
-				if shift >= 64 {
-					return ErrIntOverflowNebula
-				}
-				if iNdEx >= l {
-					return io.ErrUnexpectedEOF
-				}
-				b := dAtA[iNdEx]
-				iNdEx++
-				byteLen |= int(b&0x7F) << shift
-				if b < 0x80 {
-					break
-				}
-			}
-			if byteLen < 0 {
-				return ErrInvalidLengthNebula
-			}
-			postIndex := iNdEx + byteLen
-			if postIndex < 0 {
-				return ErrInvalidLengthNebula
-			}
-			if postIndex > l {
-				return io.ErrUnexpectedEOF
-			}
-			m.Hmac = append(m.Hmac[:0], dAtA[iNdEx:postIndex]...)
-			if m.Hmac == nil {
-				m.Hmac = []byte{}
-			}
-			iNdEx = postIndex
-		default:
-			iNdEx = preIndex
-			skippy, err := skipNebula(dAtA[iNdEx:])
-			if err != nil {
-				return err
-			}
-			if (skippy < 0) || (iNdEx+skippy) < 0 {
-				return ErrInvalidLengthNebula
-			}
-			if (iNdEx + skippy) > l {
-				return io.ErrUnexpectedEOF
-			}
-			iNdEx += skippy
-		}
-	}
-
-	if iNdEx > l {
-		return io.ErrUnexpectedEOF
-	}
-	return nil
-}
-func (m *NebulaHandshakeDetails) Unmarshal(dAtA []byte) error {
-	l := len(dAtA)
-	iNdEx := 0
-	for iNdEx < l {
-		preIndex := iNdEx
-		var wire uint64
-		for shift := uint(0); ; shift += 7 {
-			if shift >= 64 {
-				return ErrIntOverflowNebula
-			}
-			if iNdEx >= l {
-				return io.ErrUnexpectedEOF
-			}
-			b := dAtA[iNdEx]
-			iNdEx++
-			wire |= uint64(b&0x7F) << shift
-			if b < 0x80 {
-				break
-			}
-		}
-		fieldNum := int32(wire >> 3)
-		wireType := int(wire & 0x7)
-		if wireType == 4 {
-			return fmt.Errorf("proto: NebulaHandshakeDetails: wiretype end group for non-group")
-		}
-		if fieldNum <= 0 {
-			return fmt.Errorf("proto: NebulaHandshakeDetails: illegal tag %d (wire type %d)", fieldNum, wire)
-		}
-		switch fieldNum {
-		case 1:
-			if wireType != 2 {
-				return fmt.Errorf("proto: wrong wireType = %d for field Cert", wireType)
-			}
-			var byteLen int
-			for shift := uint(0); ; shift += 7 {
-				if shift >= 64 {
-					return ErrIntOverflowNebula
-				}
-				if iNdEx >= l {
-					return io.ErrUnexpectedEOF
-				}
-				b := dAtA[iNdEx]
-				iNdEx++
-				byteLen |= int(b&0x7F) << shift
-				if b < 0x80 {
-					break
-				}
-			}
-			if byteLen < 0 {
-				return ErrInvalidLengthNebula
-			}
-			postIndex := iNdEx + byteLen
-			if postIndex < 0 {
-				return ErrInvalidLengthNebula
-			}
-			if postIndex > l {
-				return io.ErrUnexpectedEOF
-			}
-			m.Cert = append(m.Cert[:0], dAtA[iNdEx:postIndex]...)
-			if m.Cert == nil {
-				m.Cert = []byte{}
-			}
-			iNdEx = postIndex
-		case 2:
-			if wireType != 0 {
-				return fmt.Errorf("proto: wrong wireType = %d for field InitiatorIndex", wireType)
-			}
-			m.InitiatorIndex = 0
-			for shift := uint(0); ; shift += 7 {
-				if shift >= 64 {
-					return ErrIntOverflowNebula
-				}
-				if iNdEx >= l {
-					return io.ErrUnexpectedEOF
-				}
-				b := dAtA[iNdEx]
-				iNdEx++
-				m.InitiatorIndex |= uint32(b&0x7F) << shift
-				if b < 0x80 {
-					break
-				}
-			}
-		case 3:
-			if wireType != 0 {
-				return fmt.Errorf("proto: wrong wireType = %d for field ResponderIndex", wireType)
-			}
-			m.ResponderIndex = 0
-			for shift := uint(0); ; shift += 7 {
-				if shift >= 64 {
-					return ErrIntOverflowNebula
-				}
-				if iNdEx >= l {
-					return io.ErrUnexpectedEOF
-				}
-				b := dAtA[iNdEx]
-				iNdEx++
-				m.ResponderIndex |= uint32(b&0x7F) << shift
-				if b < 0x80 {
-					break
-				}
-			}
-		case 4:
-			if wireType != 0 {
-				return fmt.Errorf("proto: wrong wireType = %d for field Cookie", wireType)
-			}
-			m.Cookie = 0
-			for shift := uint(0); ; shift += 7 {
-				if shift >= 64 {
-					return ErrIntOverflowNebula
-				}
-				if iNdEx >= l {
-					return io.ErrUnexpectedEOF
-				}
-				b := dAtA[iNdEx]
-				iNdEx++
-				m.Cookie |= uint64(b&0x7F) << shift
-				if b < 0x80 {
-					break
-				}
-			}
-		case 5:
-			if wireType != 0 {
-				return fmt.Errorf("proto: wrong wireType = %d for field Time", wireType)
-			}
-			m.Time = 0
-			for shift := uint(0); ; shift += 7 {
-				if shift >= 64 {
-					return ErrIntOverflowNebula
-				}
-				if iNdEx >= l {
-					return io.ErrUnexpectedEOF
-				}
-				b := dAtA[iNdEx]
-				iNdEx++
-				m.Time |= uint64(b&0x7F) << shift
-				if b < 0x80 {
-					break
-				}
-			}
-		case 8:
-			if wireType != 0 {
-				return fmt.Errorf("proto: wrong wireType = %d for field CertVersion", wireType)
-			}
-			m.CertVersion = 0
-			for shift := uint(0); ; shift += 7 {
-				if shift >= 64 {
-					return ErrIntOverflowNebula
-				}
-				if iNdEx >= l {
-					return io.ErrUnexpectedEOF
-				}
-				b := dAtA[iNdEx]
-				iNdEx++
-				m.CertVersion |= uint32(b&0x7F) << shift
-				if b < 0x80 {
-					break
-				}
-			}
-		default:
-			iNdEx = preIndex
-			skippy, err := skipNebula(dAtA[iNdEx:])
-			if err != nil {
-				return err
-			}
-			if (skippy < 0) || (iNdEx+skippy) < 0 {
-				return ErrInvalidLengthNebula
-			}
-			if (iNdEx + skippy) > l {
-				return io.ErrUnexpectedEOF
-			}
-			iNdEx += skippy
-		}
-	}
-
-	if iNdEx > l {
-		return io.ErrUnexpectedEOF
-	}
-	return nil
-}
 func (m *NebulaControl) Unmarshal(dAtA []byte) error {
 	l := len(dAtA)
 	iNdEx := 0

nebula.proto

@@ -60,21 +60,9 @@ message NebulaPing {
 	uint64 Time = 2;
 }
 
-message NebulaHandshake {
-  NebulaHandshakeDetails Details = 1;
-  bytes Hmac = 2;
-}
-
-message NebulaHandshakeDetails {
-  bytes Cert = 1;
-  uint32 InitiatorIndex = 2;
-  uint32 ResponderIndex = 3;
-  uint64 Cookie = 4;
-  uint64 Time = 5;
-  uint32 CertVersion = 8;
-  // reserved for WIP multiport
-  reserved 6, 7;
-}
+// NebulaHandshake / NebulaHandshakeDetails moved to
+// handshake/handshake.proto. The handshake package speaks that wire format
+// directly via a hand-written encoder/decoder.
 
 message NebulaControl {
   enum MessageType {

noise.go

@@ -1,73 +0,0 @@
-package nebula
-
-import (
-	"crypto/cipher"
-	"encoding/binary"
-	"errors"
-
-	"github.com/flynn/noise"
-)
-
-type endianness interface {
-	PutUint64(b []byte, v uint64)
-}
-
-var noiseEndianness endianness = binary.BigEndian
-
-type NebulaCipherState struct {
-	c cipher.AEAD
-}
-
-func NewNebulaCipherState(s *noise.CipherState) *NebulaCipherState {
-	x := s.Cipher()
-	return &NebulaCipherState{c: x.(cipher.AEAD)}
-}
-
-// EncryptDanger encrypts and authenticates a given payload.
-//
-// out is a destination slice to hold the output of the EncryptDanger operation.
-//   - ad is additional data, which will be authenticated and appended to out, but not encrypted.
-//   - plaintext is encrypted, authenticated and appended to out.
-//   - n is a nonce value which must never be re-used with this key.
-//   - nb is a buffer used for temporary storage in the implementation of this call, which should
-//     be re-used by callers to minimize garbage collection.
-func (s *NebulaCipherState) EncryptDanger(out, ad, plaintext []byte, n uint64, nb []byte) ([]byte, error) {
-	if s != nil {
-		// TODO: Is this okay now that we have made messageCounter atomic?
-		// Alternative may be to split the counter space into ranges
-		//if n <= s.n {
-		//	return nil, errors.New("CRITICAL: a duplicate counter value was used")
-		//}
-		//s.n = n
-		nb[0] = 0
-		nb[1] = 0
-		nb[2] = 0
-		nb[3] = 0
-		noiseEndianness.PutUint64(nb[4:], n)
-		out = s.c.Seal(out, nb, plaintext, ad)
-		//l.Debugf("Encryption: outlen: %d, nonce: %d, ad: %s, plainlen %d", len(out), n, ad, len(plaintext))
-		return out, nil
-	} else {
-		return nil, errors.New("no cipher state available to encrypt")
-	}
-}
-
-func (s *NebulaCipherState) DecryptDanger(out, ad, ciphertext []byte, n uint64, nb []byte) ([]byte, error) {
-	if s != nil {
-		nb[0] = 0
-		nb[1] = 0
-		nb[2] = 0
-		nb[3] = 0
-		noiseEndianness.PutUint64(nb[4:], n)
-		return s.c.Open(out, nb, ciphertext, ad)
-	} else {
-		return []byte{}, nil
-	}
-}
-
-func (s *NebulaCipherState) Overhead() int {
-	if s != nil {
-		return s.c.Overhead()
-	}
-	return 0
-}

noiseutil/aesgcm.go

@@ -0,0 +1,53 @@
+package noiseutil
+
+import (
+	"crypto/cipher"
+	"encoding/binary"
+	"errors"
+
+	"github.com/flynn/noise"
+)
+
+// CipherStateAESGCM is the data-plane wrapper for the AES-GCM AEAD cipher.
+// AES-GCM uses big-endian nonce encoding per the Noise spec.
+type CipherStateAESGCM struct {
+	c cipher.AEAD
+}
+
+// NewCipherStateAESGCM extracts the underlying AEAD from the post-handshake noise.CipherState.
+// The caller is responsible for ensuring the noise cipher is actually AES-GCM,
+// otherwise the type assertion still succeeds but the nonce endianness will be wrong on the wire.
+func NewCipherStateAESGCM(s *noise.CipherState) *CipherStateAESGCM {
+	return &CipherStateAESGCM{c: s.Cipher().(cipher.AEAD)}
+}
+
+func (s *CipherStateAESGCM) EncryptDanger(out, ad, plaintext []byte, n uint64, nb []byte) ([]byte, error) {
+	if s == nil {
+		return nil, errors.New("no cipher state available to encrypt")
+	}
+	nb[0] = 0
+	nb[1] = 0
+	nb[2] = 0
+	nb[3] = 0
+	binary.BigEndian.PutUint64(nb[4:], n)
+	return s.c.Seal(out, nb, plaintext, ad), nil
+}
+
+func (s *CipherStateAESGCM) DecryptDanger(out, ad, ciphertext []byte, n uint64, nb []byte) ([]byte, error) {
+	if s == nil {
+		return []byte{}, nil
+	}
+	nb[0] = 0
+	nb[1] = 0
+	nb[2] = 0
+	nb[3] = 0
+	binary.BigEndian.PutUint64(nb[4:], n)
+	return s.c.Open(out, nb, ciphertext, ad)
+}
+
+func (s *CipherStateAESGCM) Overhead() int {
+	if s == nil {
+		return 0
+	}
+	return s.c.Overhead()
+}

noiseutil/chachapoly.go

@@ -0,0 +1,52 @@
+package noiseutil
+
+import (
+	"crypto/cipher"
+	"encoding/binary"
+	"errors"
+
+	"github.com/flynn/noise"
+)
+
+// CipherStateChaChaPoly is the data-plane wrapper for the ChaCha20-Poly1305 AEAD cipher.
+// ChaCha20-Poly1305 uses little-endian nonce encoding per the Noise spec.
+type CipherStateChaChaPoly struct {
+	c cipher.AEAD
+}
+
+// NewCipherStateChaChaPoly extracts the underlying AEAD from the post-handshake noise.CipherState.
+// The caller is responsible for ensuring the noise cipher is actually ChaCha20-Poly1305.
+func NewCipherStateChaChaPoly(s *noise.CipherState) *CipherStateChaChaPoly {
+	return &CipherStateChaChaPoly{c: s.Cipher().(cipher.AEAD)}
+}
+
+func (s *CipherStateChaChaPoly) EncryptDanger(out, ad, plaintext []byte, n uint64, nb []byte) ([]byte, error) {
+	if s == nil {
+		return nil, errors.New("no cipher state available to encrypt")
+	}
+	nb[0] = 0
+	nb[1] = 0
+	nb[2] = 0
+	nb[3] = 0
+	binary.LittleEndian.PutUint64(nb[4:], n)
+	return s.c.Seal(out, nb, plaintext, ad), nil
+}
+
+func (s *CipherStateChaChaPoly) DecryptDanger(out, ad, ciphertext []byte, n uint64, nb []byte) ([]byte, error) {
+	if s == nil {
+		return []byte{}, nil
+	}
+	nb[0] = 0
+	nb[1] = 0
+	nb[2] = 0
+	nb[3] = 0
+	binary.LittleEndian.PutUint64(nb[4:], n)
+	return s.c.Open(out, nb, ciphertext, ad)
+}
+
+func (s *CipherStateChaChaPoly) Overhead() int {
+	if s == nil {
+		return 0
+	}
+	return s.c.Overhead()
+}

noiseutil/cipher_state.go

@@ -0,0 +1,40 @@
+package noiseutil
+
+import (
+	"fmt"
+
+	"github.com/flynn/noise"
+)
+
+// CipherState is the post-handshake AEAD cipher used for the data plane.
+// Each supported cipher has its own concrete implementation in this package with the nonce endianness hardcoded,
+// so the encrypt/decrypt fast path avoids interface dispatch on the byte order.
+type CipherState interface {
+	// EncryptDanger encrypts and authenticates a given payload.
+	//
+	// out is a destination slice to hold the output of the EncryptDanger operation.
+	//   - ad is additional data, which will be authenticated and appended to out, but not encrypted.
+	//   - plaintext is encrypted, authenticated and appended to out.
+	//   - n is a nonce value which must never be re-used with this key.
+	//   - nb is a scratch buffer used to assemble the nonce.
+	EncryptDanger(out, ad, plaintext []byte, n uint64, nb []byte) ([]byte, error)
+
+	// DecryptDanger authenticates and decrypts a given payload, with the same argument shape as EncryptDanger.
+	DecryptDanger(out, ad, ciphertext []byte, n uint64, nb []byte) ([]byte, error)
+
+	// Overhead returns the AEAD tag size, or 0 if the receiver is nil.
+	Overhead() int
+}
+
+// NewCipherState wraps the post-handshake noise.CipherState in the per-cipher type that matches cipherFunc.
+// cipherFunc must be the same cipher used to build the noise CipherSuite that produced s.
+func NewCipherState(s *noise.CipherState, cipherFunc noise.CipherFunc) CipherState {
+	switch cipherFunc.CipherName() {
+	case CipherAESGCM.CipherName():
+		return NewCipherStateAESGCM(s)
+	case noise.CipherChaChaPoly.CipherName():
+		return NewCipherStateChaChaPoly(s)
+	default:
+		panic(fmt.Sprintf("noiseutil: unsupported cipher %q", cipherFunc.CipherName()))
+	}
+}

noiseutil/cipher_state_test.go

@@ -0,0 +1,222 @@
+package noiseutil
+
+import (
+	"testing"
+
+	"github.com/flynn/noise"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCipherStateAESGCMRoundtrip(t *testing.T) {
+	enc, dec := buildCipherStates(t, CipherAESGCM)
+	roundtrip(t, NewCipherStateAESGCM(enc), NewCipherStateAESGCM(dec))
+}
+
+func TestCipherStateChaChaPolyRoundtrip(t *testing.T) {
+	enc, dec := buildCipherStates(t, noise.CipherChaChaPoly)
+	roundtrip(t, NewCipherStateChaChaPoly(enc), NewCipherStateChaChaPoly(dec))
+}
+
+func TestNewCipherStateDispatch(t *testing.T) {
+	encA, _ := buildCipherStates(t, CipherAESGCM)
+	encC, _ := buildCipherStates(t, noise.CipherChaChaPoly)
+
+	assert.IsType(t, &CipherStateAESGCM{}, NewCipherState(encA, CipherAESGCM))
+	assert.IsType(t, &CipherStateChaChaPoly{}, NewCipherState(encC, noise.CipherChaChaPoly))
+}
+
+func TestNewCipherStateUnsupportedPanics(t *testing.T) {
+	enc, _ := buildCipherStates(t, CipherAESGCM)
+	assert.Panics(t, func() {
+		NewCipherState(enc, fakeCipher{})
+	})
+}
+
+type fakeCipher struct{}
+
+func (fakeCipher) Cipher(k [32]byte) noise.Cipher { return nil }
+func (fakeCipher) CipherName() string             { return "Fake" }
+
+// buildCipherStates runs an in-memory NN handshake with the requested cipher
+// to produce a pair of post-handshake CipherStates that share keys.
+func buildCipherStates(t *testing.T, c noise.CipherFunc) (*noise.CipherState, *noise.CipherState) {
+	t.Helper()
+	suite := noise.NewCipherSuite(noise.DH25519, c, noise.HashSHA256)
+	cfg := noise.Config{CipherSuite: suite, Pattern: noise.HandshakeNN}
+	cfg.Initiator = true
+	hsI, err := noise.NewHandshakeState(cfg)
+	require.NoError(t, err)
+	cfg.Initiator = false
+	hsR, err := noise.NewHandshakeState(cfg)
+	require.NoError(t, err)
+
+	msg, _, _, err := hsI.WriteMessage(nil, nil)
+	require.NoError(t, err)
+	_, _, _, err = hsR.ReadMessage(nil, msg)
+	require.NoError(t, err)
+
+	msg, dR, _, err := hsR.WriteMessage(nil, nil)
+	require.NoError(t, err)
+	_, eI, _, err := hsI.ReadMessage(nil, msg)
+	require.NoError(t, err)
+	require.NotNil(t, eI)
+	require.NotNil(t, dR)
+
+	// noise returns (cs1, cs2) where cs1 is the initiator->responder cipher.
+	return eI, dR
+}
+
+func roundtrip(t *testing.T, enc, dec CipherState) {
+	t.Helper()
+	plaintext := []byte("nebula cipher state roundtrip")
+	ad := []byte("aad")
+	nb := make([]byte, 12)
+
+	ct, err := enc.EncryptDanger(nil, ad, plaintext, 1, nb)
+	require.NoError(t, err)
+	assert.NotEqual(t, plaintext, ct)
+
+	pt, err := dec.DecryptDanger(nil, ad, ct, 1, nb)
+	require.NoError(t, err)
+	assert.Equal(t, plaintext, pt)
+
+	// Wrong nonce must fail authentication.
+	_, err = dec.DecryptDanger(nil, ad, ct, 2, nb)
+	require.Error(t, err)
+
+	assert.Equal(t, enc.Overhead(), dec.Overhead())
+	assert.Equal(t, 16, enc.Overhead())
+}
+
+func BenchmarkCipherStateEncryptAESGCM(b *testing.B) {
+	enc, _ := buildCipherStatesB(b, CipherAESGCM)
+	benchEncryptCipherState(b, NewCipherState(enc, CipherAESGCM))
+}
+
+func BenchmarkCipherStateEncryptChaChaPoly(b *testing.B) {
+	enc, _ := buildCipherStatesB(b, noise.CipherChaChaPoly)
+	benchEncryptCipherState(b, NewCipherState(enc, noise.CipherChaChaPoly))
+}
+
+func benchEncryptCipherState(b *testing.B, cs CipherState) {
+	plaintext := make([]byte, 1280)
+	ad := make([]byte, 16)
+	nb := make([]byte, 12)
+	out := make([]byte, 0, len(plaintext)+cs.Overhead())
+	b.ResetTimer()
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		var err error
+		out, err = cs.EncryptDanger(out[:0], ad, plaintext, uint64(i+1), nb)
+		if err != nil {
+			b.Fatal(err)
+		}
+	}
+}
+
+func buildCipherStatesB(b *testing.B, c noise.CipherFunc) (*noise.CipherState, *noise.CipherState) {
+	b.Helper()
+	suite := noise.NewCipherSuite(noise.DH25519, c, noise.HashSHA256)
+	cfg := noise.Config{CipherSuite: suite, Pattern: noise.HandshakeNN}
+	cfg.Initiator = true
+	hsI, err := noise.NewHandshakeState(cfg)
+	if err != nil {
+		b.Fatal(err)
+	}
+	cfg.Initiator = false
+	hsR, err := noise.NewHandshakeState(cfg)
+	if err != nil {
+		b.Fatal(err)
+	}
+	msg, _, _, err := hsI.WriteMessage(nil, nil)
+	if err != nil {
+		b.Fatal(err)
+	}
+	if _, _, _, err := hsR.ReadMessage(nil, msg); err != nil {
+		b.Fatal(err)
+	}
+	msg, dR, _, err := hsR.WriteMessage(nil, nil)
+	if err != nil {
+		b.Fatal(err)
+	}
+	_, eI, _, err := hsI.ReadMessage(nil, msg)
+	if err != nil {
+		b.Fatal(err)
+	}
+	return eI, dR
+}
+
+// TestDecryptDangerRelayShapeNoAlloc covers the AD-only relay path used in
+// outside.go's handleOutsideRelayPacket: the body is AD, the trailing 16 bytes
+// are the AEAD tag, the plaintext is empty, and the caller passes nil as the
+// destination because it only needs the auth side-effect. The call must
+// succeed, return an empty plaintext, and not allocate on the hot path.
+func TestDecryptDangerRelayShapeNoAlloc(t *testing.T) {
+	cases := []struct {
+		name string
+		c    noise.CipherFunc
+		wrap func(*noise.CipherState) CipherState
+	}{
+		{"AESGCM", CipherAESGCM, func(cs *noise.CipherState) CipherState { return NewCipherStateAESGCM(cs) }},
+		{"ChaChaPoly", noise.CipherChaChaPoly, func(cs *noise.CipherState) CipherState { return NewCipherStateChaChaPoly(cs) }},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			encCS, decCS := buildCipherStates(t, tc.c)
+			enc, dec := tc.wrap(encCS), tc.wrap(decCS)
+
+			ad := make([]byte, 1200) // typical relay packet body size
+			for i := range ad {
+				ad[i] = byte(i)
+			}
+			nb := make([]byte, 12)
+
+			// Build the "signature value" the way handleOutsideRelayPacket sees it:
+			// empty plaintext encrypted with the body as AD yields just the 16-byte tag.
+			tag, err := enc.EncryptDanger(nil, ad, nil, 1, nb)
+			require.NoError(t, err)
+			require.Len(t, tag, dec.Overhead())
+
+			// Sanity: the relay-shaped call returns empty plaintext, no error.
+			out, err := dec.DecryptDanger(nil, ad, tag, 1, nb)
+			require.NoError(t, err)
+			assert.Empty(t, out)
+
+			// Tampering with the AD must fail authentication.
+			ad[0] ^= 0xff
+			_, err = dec.DecryptDanger(nil, ad, tag, 1, nb)
+			require.Error(t, err)
+			ad[0] ^= 0xff
+
+			// The hot path must not allocate. AllocsPerRun does a warm-up run, so any
+			// one-time setup is excluded. Counter has to advance so the AEAD nonce is
+			// unique per call, but we don't care whether the auth succeeds — we only
+			// care about whether the call path allocates.
+			var counter uint64 = 2
+			allocs := testing.AllocsPerRun(100, func() {
+				_, _ = dec.DecryptDanger(nil, ad, tag, counter, nb)
+				counter++
+			})
+			assert.Equal(t, 0.0, allocs, "DecryptDanger(nil, ...) must not allocate")
+		})
+	}
+}
+
+func TestCipherStateNilSafety(t *testing.T) {
+	var aes *CipherStateAESGCM
+	_, err := aes.EncryptDanger(nil, nil, nil, 0, make([]byte, 12))
+	require.Error(t, err)
+	out, err := aes.DecryptDanger(nil, nil, nil, 0, make([]byte, 12))
+	require.NoError(t, err)
+	assert.Empty(t, out)
+	assert.Equal(t, 0, aes.Overhead())
+
+	var cc *CipherStateChaChaPoly
+	_, err = cc.EncryptDanger(nil, nil, nil, 0, make([]byte, 12))
+	require.Error(t, err)
+	out, err = cc.DecryptDanger(nil, nil, nil, 0, make([]byte, 12))
+	require.NoError(t, err)
+	assert.Empty(t, out)
+	assert.Equal(t, 0, cc.Overhead())
+}

outside.go

@@ -20,23 +20,46 @@ const (
 	minFwPacketLen = 4
 )
 
-func (f *Interface) readOutsidePackets(via ViaSender, out []byte, packet []byte, h *header.H, fwPacket *firewall.Packet, lhf *LightHouseHandler, nb []byte, q int, localCache firewall.ConntrackCache) {
+var ErrOutOfWindow = errors.New("out of window packet")
+
+func (f *Interface) readOutsidePackets(via ViaSender, packet []byte, h *header.H, fwPacket *firewall.Packet, lhf *LightHouseHandler, nb []byte, q int, localCache firewall.ConntrackCache) {
 	err := h.Parse(packet)
 	if err != nil {
 		// Hole punch packets are 0 or 1 byte big, so lets ignore printing those errors
+		// TODO: record metrics for rx holepunch/punchy packets?
 		if len(packet) > 1 {
-			f.l.Info("Error while parsing inbound packet",
-				"from", via,
-				"error", err,
-				"packet", packet,
-			)
+			f.messageMetrics.RxInvalid(1)
+			if f.l.Enabled(context.Background(), slog.LevelDebug) {
+				f.l.Debug("Error while parsing inbound packet",
+					"from", via,
+					"error", err,
+					"packet", packet,
+				)
+			}
+		}
+		return
+	}
+
+	if h.Version != header.Version {
+		f.messageMetrics.RxInvalid(1)
+		if f.l.Enabled(context.Background(), slog.LevelDebug) {
+			f.l.Debug("Unexpected header version received", "from", via)
+		}
+		return
+	}
+
+	// Check before processing to see if this is a expected type/subtype
+	if !h.IsValidSubType() {
+		f.messageMetrics.RxInvalid(1)
+		if f.l.Enabled(context.Background(), slog.LevelDebug) {
+			f.l.Debug("Unexpected packet received", "from", via)
 		}
 		return
 	}
 
-	//l.Error("in packet ", header, packet[HeaderLen:])
 	if !via.IsRelayed {
 		if f.myVpnNetworksTable.Contains(via.UdpAddr.Addr()) {
+			f.messageMetrics.RxInvalid(1)
 			if f.l.Enabled(context.Background(), slog.LevelDebug) {
 				f.l.Debug("Refusing to process double encrypted packet", "from", via)
 			}
@@ -44,215 +67,194 @@ func (f *Interface) readOutsidePackets(via ViaSender, out []byte, packet []byte,
 		}
 	}
 
+	// don't keep Rx metrics for message type, since you can see those in the tun metrics
+	if h.Type != header.Message {
+		f.messageMetrics.Rx(h.Type, h.Subtype, 1)
+	}
+
+	// Unencrypted packets
+	switch h.Type {
+	case header.Handshake:
+		f.handshakeManager.HandleIncoming(via, packet, h)
+		return
+
+	case header.RecvError:
+		f.handleRecvError(via.UdpAddr, h)
+		return
+	}
+
+	// Relay packets are special
+	isMessageRelay := (h.Type == header.Message && h.Subtype == header.MessageRelay)
+
 	var hostinfo *HostInfo
-	// verify if we've seen this index before, otherwise respond to the handshake initiation
-	if h.Type == header.Message && h.Subtype == header.MessageRelay {
+	if isMessageRelay {
 		hostinfo = f.hostMap.QueryRelayIndex(h.RemoteIndex)
 	} else {
 		hostinfo = f.hostMap.QueryIndex(h.RemoteIndex)
 	}
 
-	var ci *ConnectionState
-	if hostinfo != nil {
-		ci = hostinfo.ConnectionState
+	// At this point we should have a valid existing tunnel, verify and send
+	// recvError if necessary
+	if hostinfo == nil || hostinfo.ConnectionState == nil {
+		if !via.IsRelayed {
+			f.maybeSendRecvError(via.UdpAddr, h.RemoteIndex)
+		}
+		return
 	}
 
+	// All remaining packets are encrypted
+	ci := hostinfo.ConnectionState
+	if !ci.window.Check(f.l, h.MessageCounter) {
+		return
+	}
+
+	// Relay packets are special
+	if isMessageRelay {
+		f.handleOutsideRelayPacket(hostinfo, via, packet, h, fwPacket, lhf, nb, q, localCache)
+		return
+	}
+
+	out := f.batchers[q].Reserve(len(packet))[:0]
+	out, err = f.decrypt(hostinfo, h.MessageCounter, out, packet, h, nb)
+	if err != nil {
+		if f.l.Enabled(context.Background(), slog.LevelDebug) {
+			hostinfo.logger(f.l).Debug("Failed to decrypt packet",
+				"error", err,
+				"from", via,
+				"header", h,
+			)
+		}
+		return
+	}
+
+	// Roam before we respond
+	f.handleHostRoaming(hostinfo, via)
+	f.connectionManager.In(hostinfo)
+
 	switch h.Type {
 	case header.Message:
-		if !f.handleEncrypted(ci, via, h) {
-			return
-		}
-
 		switch h.Subtype {
 		case header.MessageNone:
-			if !f.decryptToTun(hostinfo, h.MessageCounter, out, packet, fwPacket, nb, q, localCache) {
-				return
-			}
-		case header.MessageRelay:
-			// The entire body is sent as AD, not encrypted.
-			// The packet consists of a 16-byte parsed Nebula header, Associated Data-protected payload, and a trailing 16-byte AEAD signature value.
-			// The packet is guaranteed to be at least 16 bytes at this point, b/c it got past the h.Parse() call above. If it's
-			// otherwise malformed (meaning, there is no trailing 16 byte AEAD value), then this will result in at worst a 0-length slice
-			// which will gracefully fail in the DecryptDanger call.
-			signedPayload := packet[:len(packet)-hostinfo.ConnectionState.dKey.Overhead()]
-			signatureValue := packet[len(packet)-hostinfo.ConnectionState.dKey.Overhead():]
-			out, err = hostinfo.ConnectionState.dKey.DecryptDanger(out, signedPayload, signatureValue, h.MessageCounter, nb)
-			if err != nil {
-				return
-			}
-			// Successfully validated the thing. Get rid of the Relay header.
-			signedPayload = signedPayload[header.Len:]
-			// Pull the Roaming parts up here, and return in all call paths.
-			f.handleHostRoaming(hostinfo, via)
-			// Track usage of both the HostInfo and the Relay for the received & authenticated packet
-			f.connectionManager.In(hostinfo)
-			f.connectionManager.RelayUsed(h.RemoteIndex)
-
-			relay, ok := hostinfo.relayState.QueryRelayForByIdx(h.RemoteIndex)
-			if !ok {
-				// The only way this happens is if hostmap has an index to the correct HostInfo, but the HostInfo is missing
-				// its internal mapping. This should never happen.
-				hostinfo.logger(f.l).Error("HostInfo missing remote relay index",
-					"vpnAddrs", hostinfo.vpnAddrs,
-					"remoteIndex", h.RemoteIndex,
-				)
-				return
-			}
-
-			switch relay.Type {
-			case TerminalType:
-				// If I am the target of this relay, process the unwrapped packet
-				// From this recursive point, all these variables are 'burned'. We shouldn't rely on them again.
-				via = ViaSender{
-					UdpAddr:   via.UdpAddr,
-					relayHI:   hostinfo,
-					remoteIdx: relay.RemoteIndex,
-					relay:     relay,
-					IsRelayed: true,
-				}
-				f.readOutsidePackets(via, out[:0], signedPayload, h, fwPacket, lhf, nb, q, localCache)
-				return
-			case ForwardingType:
-				// Find the target HostInfo relay object
-				targetHI, targetRelay, err := f.hostMap.QueryVpnAddrsRelayFor(hostinfo.vpnAddrs, relay.PeerAddr)
-				if err != nil {
-					hostinfo.logger(f.l).Info("Failed to find target host info by ip",
-						"relayTo", relay.PeerAddr,
-						"error", err,
-						"hostinfo.vpnAddrs", hostinfo.vpnAddrs,
-					)
-					return
-				}
-
-				// If that relay is Established, forward the payload through it
-				if targetRelay.State == Established {
-					switch targetRelay.Type {
-					case ForwardingType:
-						// Forward this packet through the relay tunnel
-						// Find the target HostInfo
-						f.SendVia(targetHI, targetRelay, signedPayload, nb, out, false)
-						return
-					case TerminalType:
-						hostinfo.logger(f.l).Error("Unexpected Relay Type of Terminal")
-					}
-				} else {
-					hostinfo.logger(f.l).Info("Unexpected target relay state",
-						"relayTo", relay.PeerAddr,
-						"relayFrom", hostinfo.vpnAddrs[0],
-						"targetRelayState", targetRelay.State,
-					)
-					return
-				}
-			}
+			f.handleOutsideMessagePacket(hostinfo, out, packet, fwPacket, nb, q, localCache)
+		default:
+			hostinfo.logger(f.l).Error("IsValidSubType was true, but unexpected message subtype seen", "from", via, "header", h)
+			return
 		}
 
 	case header.LightHouse:
-		f.messageMetrics.Rx(h.Type, h.Subtype, 1)
-		if !f.handleEncrypted(ci, via, h) {
-			return
-		}
-
-		d, err := f.decrypt(hostinfo, h.MessageCounter, out, packet, h, nb)
-		if err != nil {
-			hostinfo.logger(f.l).Error("Failed to decrypt lighthouse packet",
-				"error", err,
-				"from", via,
-				"packet", packet,
-			)
-			return
-		}
-
 		//TODO: assert via is not relayed
-		lhf.HandleRequest(via.UdpAddr, hostinfo.vpnAddrs, d, f)
-
-		// Fallthrough to the bottom to record incoming traffic
+		lhf.HandleRequest(via.UdpAddr, hostinfo.vpnAddrs, out, f)
 
 	case header.Test:
-		f.messageMetrics.Rx(h.Type, h.Subtype, 1)
-		if !f.handleEncrypted(ci, via, h) {
+		switch h.Subtype {
+		case header.TestReply:
+			// No-op, useful for the Roaming and connectionManager side-effects above
+		case header.TestRequest:
+			f.send(header.Test, header.TestReply, ci, hostinfo, out, nb, out)
+		default:
+			hostinfo.logger(f.l).Error("IsValidSubType was true, but unexpected test subtype seen", "from", via, "header", h)
 			return
 		}
 
-		d, err := f.decrypt(hostinfo, h.MessageCounter, out, packet, h, nb)
-		if err != nil {
-			hostinfo.logger(f.l).Error("Failed to decrypt test packet",
-				"error", err,
-				"from", via,
-				"packet", packet,
-			)
-			return
-		}
-
-		if h.Subtype == header.TestRequest {
-			// This testRequest might be from TryPromoteBest, so we should roam
-			// to the new IP address before responding
-			f.handleHostRoaming(hostinfo, via)
-			f.send(header.Test, header.TestReply, ci, hostinfo, d, nb, out)
-		}
-
-		// Fallthrough to the bottom to record incoming traffic
-
-		// Non encrypted messages below here, they should not fall through to avoid tracking incoming traffic since they
-		// are unauthenticated
-
-	case header.Handshake:
-		f.messageMetrics.Rx(h.Type, h.Subtype, 1)
-		f.handshakeManager.HandleIncoming(via, packet, h)
-		return
-
-	case header.RecvError:
-		f.messageMetrics.Rx(h.Type, h.Subtype, 1)
-		f.handleRecvError(via.UdpAddr, h)
-		return
-
 	case header.CloseTunnel:
-		f.messageMetrics.Rx(h.Type, h.Subtype, 1)
-		if !f.handleEncrypted(ci, via, h) {
-			return
-		}
-		_, err = f.decrypt(hostinfo, h.MessageCounter, out, packet, h, nb)
-		if err != nil {
-			hostinfo.logger(f.l).Error("Failed to decrypt CloseTunnel packet",
-				"error", err,
-				"from", via,
-				"packet", packet,
-			)
-			return
-		}
-
 		hostinfo.logger(f.l).Info("Close tunnel received, tearing down.", "from", via)
-
 		f.closeTunnel(hostinfo)
-		return
 
 	case header.Control:
-		if !f.handleEncrypted(ci, via, h) {
-			return
-		}
-
-		d, err := f.decrypt(hostinfo, h.MessageCounter, out, packet, h, nb)
-		if err != nil {
-			hostinfo.logger(f.l).Error("Failed to decrypt Control packet",
-				"error", err,
-				"from", via,
-				"packet", packet,
-			)
-			return
-		}
-
-		f.relayManager.HandleControlMsg(hostinfo, d, f)
+		f.relayManager.HandleControlMsg(hostinfo, out, f)
 
 	default:
-		f.messageMetrics.Rx(h.Type, h.Subtype, 1)
-		if f.l.Enabled(context.Background(), slog.LevelDebug) {
-			hostinfo.logger(f.l).Debug("Unexpected packet received", "from", via)
-		}
+		hostinfo.logger(f.l).Error("IsValidSubType was true, but unexpected message type seen", "from", via, "header", h)
+	}
+}
+
+func (f *Interface) handleOutsideRelayPacket(hostinfo *HostInfo, via ViaSender, packet []byte, h *header.H, fwPacket *firewall.Packet, lhf *LightHouseHandler, nb []byte, q int, localCache firewall.ConntrackCache) {
+	// The entire body is sent as AD, not encrypted.
+	// The packet consists of a 16-byte parsed Nebula header, Associated Data-protected payload, and a trailing 16-byte AEAD signature value.
+	// The packet is guaranteed to be at least 16 bytes at this point, b/c it got past the h.Parse() call above. If it's
+	// otherwise malformed (meaning, there is no trailing 16 byte AEAD value), then this will result in at worst a 0-length slice
+	// which will gracefully fail in the DecryptDanger call.
+	signedPayload := packet[:len(packet)-hostinfo.ConnectionState.dKey.Overhead()]
+	signatureValue := packet[len(packet)-hostinfo.ConnectionState.dKey.Overhead():]
+	// The decrypted output is empty (relay packets carry their payload as AD) and unused.
+	// The recursive readOutsidePackets call below operates on signedPayload. Passing
+	// nil avoids reserving an arena slot.
+	if _, err := hostinfo.ConnectionState.dKey.DecryptDanger(nil, signedPayload, signatureValue, h.MessageCounter, nb); err != nil {
+		return
+	}
+	// Successfully validated the thing. Get rid of the Relay header.
+	signedPayload = signedPayload[header.Len:]
+	// Pull the Roaming parts up here, and return in all call paths.
+	f.handleHostRoaming(hostinfo, via)
+	// Track usage of both the HostInfo and the Relay for the received & authenticated packet
+	f.connectionManager.In(hostinfo)
+	f.connectionManager.RelayUsed(h.RemoteIndex)
+
+	relay, ok := hostinfo.relayState.QueryRelayForByIdx(h.RemoteIndex)
+	if !ok {
+		// The only way this happens is if hostmap has an index to the correct HostInfo, but the HostInfo is missing
+		// its internal mapping. This should never happen.
+		hostinfo.logger(f.l).Error("HostInfo missing remote relay index",
+			"vpnAddrs", hostinfo.vpnAddrs,
+			"remoteIndex", h.RemoteIndex,
+		)
 		return
 	}
 
-	f.handleHostRoaming(hostinfo, via)
+	switch relay.Type {
+	case TerminalType:
+		// If I am the target of this relay, process the unwrapped packet
+		// From this recursive point, all these variables are 'burned'. We shouldn't rely on them again.
+		via = ViaSender{
+			UdpAddr:   via.UdpAddr,
+			relayHI:   hostinfo,
+			remoteIdx: relay.RemoteIndex,
+			relay:     relay,
+			IsRelayed: true,
+		}
+		f.readOutsidePackets(via, signedPayload, h, fwPacket, lhf, nb, q, localCache)
+	case ForwardingType:
+		// Find the target HostInfo relay object
+		targetHI, targetRelay, err := f.hostMap.QueryVpnAddrsRelayFor(hostinfo.vpnAddrs, relay.PeerAddr)
+		if err != nil {
+			hostinfo.logger(f.l).Info("Failed to find target host info by ip",
+				"relayTo", relay.PeerAddr,
+				"error", err,
+				"hostinfo.vpnAddrs", hostinfo.vpnAddrs,
+			)
+			return
+		}
 
-	f.connectionManager.In(hostinfo)
+		// If that relay is Established, forward the payload through it
+		if targetRelay.State == Established {
+			switch targetRelay.Type {
+			case ForwardingType:
+				// Forward this packet through the relay tunnel
+				// Find the target HostInfo //todo it would potentially be nice to batch these
+				out := f.batchers[q].Reserve(len(packet) + header.Len + hostinfo.ConnectionState.dKey.Overhead())[:0]
+				f.SendVia(targetHI, targetRelay, signedPayload, nb, out, false)
+			case TerminalType:
+				hostinfo.logger(f.l).Error("Unexpected Relay Type of Terminal")
+				return
+			default:
+				if f.l.Enabled(context.Background(), slog.LevelDebug) {
+					hostinfo.logger(f.l).Debug("Unexpected targetRelay Type", "from", via, "relayType", targetRelay.Type)
+				}
+				return
+			}
+		} else {
+			hostinfo.logger(f.l).Info("Unexpected target relay state",
+				"relayTo", relay.PeerAddr,
+				"relayFrom", hostinfo.vpnAddrs[0],
+				"targetRelayState", targetRelay.State,
+			)
+			return
+		}
+	default:
+		if f.l.Enabled(context.Background(), slog.LevelDebug) {
+			hostinfo.logger(f.l).Debug("Unexpected relay type", "from", via, "relayType", relay.Type)
+		}
+	}
 }
 
 // closeTunnel closes a tunnel locally, it does not send a closeTunnel packet to the remote
@@ -300,23 +302,6 @@ func (f *Interface) handleHostRoaming(hostinfo *HostInfo, via ViaSender) {
 
 }
 
-// handleEncrypted returns true if a packet should be processed, false otherwise
-func (f *Interface) handleEncrypted(ci *ConnectionState, via ViaSender, h *header.H) bool {
-	// If connectionstate does not exist, send a recv error, if possible, to encourage a fast reconnect
-	if ci == nil {
-		if !via.IsRelayed {
-			f.maybeSendRecvError(via.UdpAddr, h.RemoteIndex)
-		}
-		return false
-	}
-	// If the window check fails, refuse to process the packet, but don't send a recv error
-	if !ci.window.Check(f.l, h.MessageCounter) {
-		return false
-	}
-
-	return true
-}
-
 var (
 	ErrPacketTooShort          = errors.New("packet is too short")
 	ErrUnknownIPVersion        = errors.New("packet is an unknown ip version")
@@ -523,38 +508,20 @@ func (f *Interface) decrypt(hostinfo *HostInfo, mc uint64, out []byte, packet []
 	}
 
 	if !hostinfo.ConnectionState.window.Update(f.l, mc) {
-		if f.l.Enabled(context.Background(), slog.LevelDebug) {
-			hostinfo.logger(f.l).Debug("dropping out of window packet", "header", h)
-		}
-		return nil, errors.New("out of window packet")
+		return nil, ErrOutOfWindow
 	}
 
 	return out, nil
 }
 
-func (f *Interface) decryptToTun(hostinfo *HostInfo, messageCounter uint64, out []byte, packet []byte, fwPacket *firewall.Packet, nb []byte, q int, localCache firewall.ConntrackCache) bool {
-	var err error
-
-	out, err = hostinfo.ConnectionState.dKey.DecryptDanger(out, packet[:header.Len], packet[header.Len:], messageCounter, nb)
-	if err != nil {
-		hostinfo.logger(f.l).Error("Failed to decrypt packet", "error", err)
-		return false
-	}
-
-	err = newPacket(out, true, fwPacket)
+func (f *Interface) handleOutsideMessagePacket(hostinfo *HostInfo, out []byte, packet []byte, fwPacket *firewall.Packet, nb []byte, q int, localCache firewall.ConntrackCache) {
+	err := newPacket(out, true, fwPacket)
 	if err != nil {
 		hostinfo.logger(f.l).Warn("Error while validating inbound packet",
 			"error", err,
 			"packet", out,
 		)
-		return false
-	}
-
-	if !hostinfo.ConnectionState.window.Update(f.l, messageCounter) {
-		if f.l.Enabled(context.Background(), slog.LevelDebug) {
-			hostinfo.logger(f.l).Debug("dropping out of window packet", "fwPacket", fwPacket)
-		}
-		return false
+		return
 	}
 
 	dropReason := f.firewall.Drop(*fwPacket, true, hostinfo, f.pki.GetCAPool(), localCache)
@@ -568,15 +535,13 @@ func (f *Interface) decryptToTun(hostinfo *HostInfo, messageCounter uint64, out
 				"reason", dropReason,
 			)
 		}
-		return false
+		return
 	}
 
-	f.connectionManager.In(hostinfo)
-	_, err = f.readers[q].Write(out)
+	err = f.batchers[q].Commit(out)
 	if err != nil {
 		f.l.Error("Failed to write to tun", "error", err)
 	}
-	return true
 }
 
 func (f *Interface) maybeSendRecvError(endpoint netip.AddrPort, index uint32) {

overlay/batch/coalesce_core.go

@@ -0,0 +1,42 @@
+package batch
+
+// Arena is an injectable byte-slab that hands out non-overlapping borrowed
+// slices via Reserve and releases them in bulk via Reset. Coalescers take
+// an *Arena at construction so the caller controls the slab lifetime and
+// can share one slab across multiple coalescers (MultiCoalescer hands the
+// same *Arena to every lane so the lanes don't carry their own backings).
+//
+// Reserve borrows; the slice is valid until the next Reset. The slab grows
+// (by allocating a fresh, larger backing array) if a Reserve doesn't fit;
+// pre-size the arena via NewArena to avoid that path on the hot path.
+type Arena struct {
+	buf []byte
+}
+
+// NewArena returns an Arena with a pre-allocated backing of the given
+// capacity. Pass 0 if you don't intend to call Reserve (e.g. a test that
+// only feeds the coalescer pre-made []byte packets via Commit).
+func NewArena(capacity int) *Arena {
+	return &Arena{buf: make([]byte, 0, capacity)}
+}
+
+// Reserve hands out a non-overlapping sz-byte slice from the arena. If the
+// request doesn't fit the current backing, a fresh, larger backing is
+// allocated; already-borrowed slices reference the old backing and remain
+// valid until Reset.
+func (a *Arena) Reserve(sz int) []byte {
+	if len(a.buf)+sz > cap(a.buf) {
+		newCap := max(cap(a.buf)*2, sz)
+		a.buf = make([]byte, 0, newCap)
+	}
+	start := len(a.buf)
+	a.buf = a.buf[:start+sz]
+	return a.buf[start : start+sz : start+sz]
+}
+
+// Reset releases every slice handed out since the last Reset. Callers must
+// not use any previously-borrowed slice after this returns. The underlying
+// backing array is retained so subsequent Reserves don't re-allocate.
+func (a *Arena) Reset() {
+	a.buf = a.buf[:0]
+}

overlay/batch/passthrough.go

@@ -0,0 +1,46 @@
+package batch
+
+import (
+	"io"
+
+	"github.com/slackhq/nebula/util"
+)
+
+// Passthrough is a RxBatcher that doesn't batch anything, it just accumulates and then sends packets.
+type Passthrough struct {
+	out    io.Writer
+	slots  [][]byte
+	arena  *util.Arena
+	cursor int
+}
+
+func NewPassthrough(w io.Writer, slots int, arena *util.Arena) *Passthrough {
+	return &Passthrough{
+		out:   w,
+		slots: make([][]byte, 0, slots),
+		arena: arena,
+	}
+}
+
+func (p *Passthrough) Reserve(sz int) []byte {
+	return p.arena.Reserve(sz)
+}
+
+func (p *Passthrough) Commit(pkt []byte) error {
+	p.slots = append(p.slots, pkt)
+	return nil
+}
+
+func (p *Passthrough) Flush() error {
+	var firstErr error
+	for _, s := range p.slots {
+		_, err := p.out.Write(s)
+		if err != nil && firstErr == nil {
+			firstErr = err
+		}
+	}
+	clear(p.slots)
+	p.slots = p.slots[:0]
+	p.arena.Reset()
+	return firstErr
+}

overlay/batch/rx_batch.go

@@ -0,0 +1,12 @@
+package batch
+
+type RxBatcher interface {
+	// Reserve creates a pkt to borrow
+	Reserve(sz int) []byte
+	// Commit borrows pkt. The caller must keep pkt valid until the next Flush
+	Commit(pkt []byte) error
+	// Flush emits every queued packet in arrival order. Returns the
+	// first error observed; keeps draining so one bad packet doesn't hold up
+	// the rest. After Flush returns, borrowed payload slices may be recycled.
+	Flush() error
+}

overlay/batch/tx_batch.go

@@ -0,0 +1,60 @@
+package batch
+
+import (
+	"net/netip"
+
+	"github.com/slackhq/nebula/util"
+)
+
+const SendBatchCap = 128
+
+// batchWriter is the minimal subset of udp.Conn needed by SendBatch to flush.
+type batchWriter interface {
+	WriteBatch(bufs [][]byte, addrs []netip.AddrPort, outerECNs []byte) error
+}
+
+// SendBatch accumulates encrypted UDP packets and flushes them via WriteBatch.
+// One SendBatch is owned by each listenIn goroutine; no locking is needed.
+// Slot bytes are borrowed from the injected Arena and remain valid until
+// Flush, which Resets the arena.
+type SendBatch struct {
+	out   batchWriter
+	bufs  [][]byte
+	dsts  []netip.AddrPort
+	ecns  []byte
+	arena *util.Arena
+}
+
+// NewSendBatch makes a SendBatch with batchCap slots backed by arena.
+func NewSendBatch(out batchWriter, batchCap int, arena *util.Arena) *SendBatch {
+	return &SendBatch{
+		out:   out,
+		bufs:  make([][]byte, 0, batchCap),
+		dsts:  make([]netip.AddrPort, 0, batchCap),
+		ecns:  make([]byte, 0, batchCap),
+		arena: arena,
+	}
+}
+
+func (b *SendBatch) Reserve(sz int) []byte {
+	return b.arena.Reserve(sz)
+}
+
+func (b *SendBatch) Commit(pkt []byte, dst netip.AddrPort, outerECN byte) {
+	b.bufs = append(b.bufs, pkt)
+	b.dsts = append(b.dsts, dst)
+	b.ecns = append(b.ecns, outerECN)
+}
+
+func (b *SendBatch) Flush() error {
+	var err error
+	if len(b.bufs) > 0 {
+		err = b.out.WriteBatch(b.bufs, b.dsts, b.ecns)
+	}
+	clear(b.bufs)
+	b.bufs = b.bufs[:0]
+	b.dsts = b.dsts[:0]
+	b.ecns = b.ecns[:0]
+	b.arena.Reset()
+	return err
+}

overlay/batch/tx_batch_test.go

@@ -0,0 +1,126 @@
+package batch
+
+import (
+	"net/netip"
+	"testing"
+
+	"github.com/slackhq/nebula/util"
+)
+
+type fakeBatchWriter struct {
+	bufs  [][]byte
+	addrs []netip.AddrPort
+	ecns  []byte
+}
+
+func (w *fakeBatchWriter) WriteBatch(bufs [][]byte, addrs []netip.AddrPort, ecns []byte) error {
+	// Snapshot — SendBatch.Flush nils its slot pointers right after WriteBatch
+	// returns, so tests must capture data before that happens.
+	w.bufs = make([][]byte, len(bufs))
+	for i, b := range bufs {
+		cp := make([]byte, len(b))
+		copy(cp, b)
+		w.bufs[i] = cp
+	}
+	w.addrs = append(w.addrs[:0], addrs...)
+	w.ecns = append(w.ecns[:0], ecns...)
+	return nil
+}
+
+func TestSendBatchReserveCommitFlush(t *testing.T) {
+	fw := &fakeBatchWriter{}
+	b := NewSendBatch(fw, 4, util.NewArena(32))
+
+	ap := netip.MustParseAddrPort("10.0.0.1:4242")
+	for i := 0; i < 4; i++ {
+		slot := b.Reserve(32)
+		if cap(slot) != 32 {
+			t.Fatalf("slot %d: cap=%d want 32", i, cap(slot))
+		}
+		pkt := append(slot[:0], byte(i), byte(i+1), byte(i+2))
+		b.Commit(pkt, ap, 0)
+	}
+	if err := b.Flush(); err != nil {
+		t.Fatalf("Flush: %v", err)
+	}
+	if len(fw.bufs) != 4 {
+		t.Fatalf("WriteBatch got %d bufs want 4", len(fw.bufs))
+	}
+	for i, buf := range fw.bufs {
+		if len(buf) != 3 || buf[0] != byte(i) {
+			t.Errorf("buf %d: %x", i, buf)
+		}
+		if fw.addrs[i] != ap {
+			t.Errorf("addr %d: got %v want %v", i, fw.addrs[i], ap)
+		}
+	}
+
+	// Flush again with nothing committed — should be a no-op.
+	fw.bufs = nil
+	if err := b.Flush(); err != nil {
+		t.Fatalf("empty Flush: %v", err)
+	}
+	if fw.bufs != nil {
+		t.Fatalf("empty Flush triggered WriteBatch")
+	}
+
+	// Reuse after Flush.
+	slot := b.Reserve(32)
+	if cap(slot) != 32 {
+		t.Fatalf("after Flush Reserve wrong cap: %d", cap(slot))
+	}
+}
+
+func TestSendBatchSlotsDoNotOverlap(t *testing.T) {
+	fw := &fakeBatchWriter{}
+	b := NewSendBatch(fw, 3, util.NewArena(8))
+	ap := netip.MustParseAddrPort("10.0.0.1:80")
+
+	for i := 0; i < 3; i++ {
+		s := b.Reserve(8)
+		pkt := append(s[:0], byte(0xA0+i), byte(0xB0+i))
+		b.Commit(pkt, ap, 0)
+	}
+	if err := b.Flush(); err != nil {
+		t.Fatalf("Flush: %v", err)
+	}
+
+	for i, buf := range fw.bufs {
+		if buf[0] != byte(0xA0+i) || buf[1] != byte(0xB0+i) {
+			t.Errorf("slot %d corrupted: %x", i, buf)
+		}
+	}
+}
+
+func TestSendBatchGrowPreservesCommitted(t *testing.T) {
+	fw := &fakeBatchWriter{}
+	// Tiny initial backing forces a grow on the second Reserve.
+	b := NewSendBatch(fw, 1, util.NewArena(4))
+	ap := netip.MustParseAddrPort("10.0.0.1:80")
+
+	s1 := b.Reserve(4)
+	pkt1 := append(s1[:0], 0x11, 0x22, 0x33, 0x44)
+	b.Commit(pkt1, ap, 0)
+
+	s2 := b.Reserve(8) // exceeds remaining cap, triggers grow
+	pkt2 := append(s2[:0], 0xA, 0xB, 0xC, 0xD, 0xE)
+	b.Commit(pkt2, ap, 0)
+
+	// pkt1 must still be intact even though backing reallocated.
+	if pkt1[0] != 0x11 || pkt1[3] != 0x44 {
+		t.Fatalf("first packet corrupted by grow: %x", pkt1)
+	}
+
+	if err := b.Flush(); err != nil {
+		t.Fatalf("Flush: %v", err)
+	}
+	if len(fw.bufs) != 2 {
+		t.Fatalf("got %d bufs want 2", len(fw.bufs))
+	}
+	if fw.bufs[0][0] != 0x11 || fw.bufs[0][3] != 0x44 {
+		t.Errorf("first packet on the wire: %x", fw.bufs[0])
+	}
+	if fw.bufs[1][0] != 0xA || fw.bufs[1][4] != 0xE {
+		t.Errorf("second packet on the wire: %x", fw.bufs[1])
+	}
+}

overlay/device.go

@@ -4,15 +4,21 @@ import (
 	"io"
 	"net/netip"
 
+	"github.com/slackhq/nebula/overlay/tio"
 	"github.com/slackhq/nebula/routing"
 )
 
+// defaultBatchBufSize is the per-Queue scratch size for Read on backends
+// that don't do TSO segmentation. 65535 covers any single IP packet.
+const defaultBatchBufSize = 65535
+
 type Device interface {
-	io.ReadWriteCloser
+	io.Closer
 	Activate() error
 	Networks() []netip.Prefix
 	Name() string
 	RoutesFor(netip.Addr) routing.Gateways
 	SupportsMultiqueue() bool
-	NewMultiQueueReader() (io.ReadWriteCloser, error)
+	NewMultiQueueReader() error
+	Readers() []tio.Queue
 }

overlay/network_category_windows.go

@@ -0,0 +1,358 @@
+//go:build !e2e_testing
+// +build !e2e_testing
+
+package overlay
+
+import (
+	"errors"
+	"fmt"
+	"log/slog"
+	"runtime"
+	"strings"
+	"syscall"
+	"time"
+	"unsafe"
+
+	"golang.org/x/sys/windows"
+)
+
+// networkCategory mirrors NLM_NETWORK_CATEGORY from netlistmgr.h.
+type networkCategory int32
+
+const (
+	networkCategoryPublic              networkCategory = 0
+	networkCategoryPrivate             networkCategory = 1
+	networkCategoryDomainAuthenticated networkCategory = 2
+)
+
+func (c networkCategory) String() string {
+	switch c {
+	case networkCategoryPublic:
+		return "public"
+	case networkCategoryPrivate:
+		return "private"
+	case networkCategoryDomainAuthenticated:
+		return "domain"
+	}
+	return fmt.Sprintf("unknown(%d)", c)
+}
+
+// parseNetworkCategory accepts the user-supplied tun.network_category. A
+// second return of false means "leave the category alone".
+func parseNetworkCategory(s string) (networkCategory, bool, error) {
+	switch strings.ToLower(strings.TrimSpace(s)) {
+	case "", "unset":
+		return 0, false, nil
+	case "public":
+		return networkCategoryPublic, true, nil
+	case "private":
+		return networkCategoryPrivate, true, nil
+	case "domain", "domainauthenticated":
+		return networkCategoryDomainAuthenticated, true, nil
+	}
+	return 0, false, fmt.Errorf("unknown tun.network_category %q (expected public, private, domain, or unset)", s)
+}
+
+// CLSID_NetworkListManager {DCB00C01-570F-4A9B-8D69-199FDBA5723B}
+var clsidNetworkListManager = windows.GUID{
+	Data1: 0xDCB00C01, Data2: 0x570F, Data3: 0x4A9B,
+	Data4: [8]byte{0x8D, 0x69, 0x19, 0x9F, 0xDB, 0xA5, 0x72, 0x3B},
+}
+
+// IID_INetworkListManager {DCB00000-570F-4A9B-8D69-199FDBA5723B}
+var iidINetworkListManager = windows.GUID{
+	Data1: 0xDCB00000, Data2: 0x570F, Data3: 0x4A9B,
+	Data4: [8]byte{0x8D, 0x69, 0x19, 0x9F, 0xDB, 0xA5, 0x72, 0x3B},
+}
+
+// x/sys/windows doesn't expose CoCreateInstance, so we bind it ourselves.
+var procCoCreateInstance = windows.NewLazySystemDLL("ole32.dll").NewProc("CoCreateInstance")
+
+const clsCtxAll = windows.CLSCTX_INPROC_SERVER | windows.CLSCTX_INPROC_HANDLER |
+	windows.CLSCTX_LOCAL_SERVER | windows.CLSCTX_REMOTE_SERVER
+
+const (
+	hrSFALSE          = 0x00000001
+	hrRPCEChangedMode = 0x80010106
+)
+
+type hresult uint32
+
+func (h hresult) failed() bool { return int32(h) < 0 }
+func (h hresult) String() string {
+	return fmt.Sprintf("HRESULT 0x%08x", uint32(h))
+}
+
+var errAdapterNotFound = errors.New("adapter not present in network connections enumeration")
+
+// Vtable layouts. Slot order must match the declaration order in netlistmgr.h.
+// All NLM interfaces here derive from IDispatch, which derives from IUnknown.
+
+type iUnknownVtbl struct {
+	QueryInterface uintptr
+	AddRef         uintptr
+	Release        uintptr
+}
+
+type iDispatchVtbl struct {
+	iUnknownVtbl
+	GetTypeInfoCount uintptr
+	GetTypeInfo      uintptr
+	GetIDsOfNames    uintptr
+	Invoke           uintptr
+}
+
+type iNetworkListManagerVtbl struct {
+	iDispatchVtbl
+	GetNetworks           uintptr
+	GetNetwork            uintptr
+	GetNetworkConnections uintptr
+	GetNetworkConnection  uintptr
+	IsConnectedToInternet uintptr
+	IsConnected           uintptr
+	GetConnectivity       uintptr
+}
+
+type iNetworkListManager struct{ Vtbl *iNetworkListManagerVtbl }
+
+func (n *iNetworkListManager) Release() {
+	syscall.SyscallN(n.Vtbl.Release, uintptr(unsafe.Pointer(n)))
+}
+
+func (n *iNetworkListManager) GetNetworkConnections() (*iEnumNetworkConnections, error) {
+	var enum *iEnumNetworkConnections
+	r1, _, _ := syscall.SyscallN(n.Vtbl.GetNetworkConnections,
+		uintptr(unsafe.Pointer(n)), uintptr(unsafe.Pointer(&enum)),
+	)
+	if hr := hresult(r1); hr.failed() {
+		return nil, fmt.Errorf("INetworkListManager.GetNetworkConnections: %s", hr)
+	}
+	return enum, nil
+}
+
+type iEnumNetworkConnectionsVtbl struct {
+	iDispatchVtbl
+	NewEnum uintptr
+	Next    uintptr
+	Skip    uintptr
+	Reset   uintptr
+	Clone   uintptr
+}
+
+type iEnumNetworkConnections struct{ Vtbl *iEnumNetworkConnectionsVtbl }
+
+func (e *iEnumNetworkConnections) Release() {
+	syscall.SyscallN(e.Vtbl.Release, uintptr(unsafe.Pointer(e)))
+}
+
+// Next returns the next connection, or (nil, nil) at the end of the enumeration.
+func (e *iEnumNetworkConnections) Next() (*iNetworkConnection, error) {
+	var conn *iNetworkConnection
+	var fetched uint32
+	r1, _, _ := syscall.SyscallN(e.Vtbl.Next,
+		uintptr(unsafe.Pointer(e)), 1,
+		uintptr(unsafe.Pointer(&conn)), uintptr(unsafe.Pointer(&fetched)),
+	)
+	if hr := hresult(r1); hr.failed() {
+		return nil, fmt.Errorf("IEnumNetworkConnections.Next: %s", hr)
+	}
+	if fetched == 0 {
+		return nil, nil
+	}
+	return conn, nil
+}
+
+type iNetworkConnectionVtbl struct {
+	iDispatchVtbl
+	GetNetwork            uintptr
+	IsConnectedToInternet uintptr
+	IsConnected           uintptr
+	GetConnectivity       uintptr
+	GetConnectionId       uintptr
+	GetAdapterId          uintptr
+	GetDomainType         uintptr
+}
+
+type iNetworkConnection struct{ Vtbl *iNetworkConnectionVtbl }
+
+func (c *iNetworkConnection) Release() {
+	syscall.SyscallN(c.Vtbl.Release, uintptr(unsafe.Pointer(c)))
+}
+
+func (c *iNetworkConnection) GetAdapterId() (windows.GUID, error) {
+	var g windows.GUID
+	r1, _, _ := syscall.SyscallN(c.Vtbl.GetAdapterId,
+		uintptr(unsafe.Pointer(c)), uintptr(unsafe.Pointer(&g)),
+	)
+	if hr := hresult(r1); hr.failed() {
+		return windows.GUID{}, fmt.Errorf("INetworkConnection.GetAdapterId: %s", hr)
+	}
+	return g, nil
+}
+
+func (c *iNetworkConnection) GetNetwork() (*iNetwork, error) {
+	var net *iNetwork
+	r1, _, _ := syscall.SyscallN(c.Vtbl.GetNetwork,
+		uintptr(unsafe.Pointer(c)), uintptr(unsafe.Pointer(&net)),
+	)
+	if hr := hresult(r1); hr.failed() {
+		return nil, fmt.Errorf("INetworkConnection.GetNetwork: %s", hr)
+	}
+	return net, nil
+}
+
+type iNetworkVtbl struct {
+	iDispatchVtbl
+	GetName                    uintptr
+	SetName                    uintptr
+	GetDescription             uintptr
+	SetDescription             uintptr
+	GetNetworkId               uintptr
+	GetDomainType              uintptr
+	GetNetworkConnections      uintptr
+	GetTimeCreatedAndConnected uintptr
+	IsConnectedToInternet      uintptr
+	IsConnected                uintptr
+	GetConnectivity            uintptr
+	GetCategory                uintptr
+	SetCategory                uintptr
+}
+
+type iNetwork struct{ Vtbl *iNetworkVtbl }
+
+func (n *iNetwork) Release() {
+	syscall.SyscallN(n.Vtbl.Release, uintptr(unsafe.Pointer(n)))
+}
+
+func (n *iNetwork) GetCategory() (networkCategory, error) {
+	var c networkCategory
+	r1, _, _ := syscall.SyscallN(n.Vtbl.GetCategory,
+		uintptr(unsafe.Pointer(n)), uintptr(unsafe.Pointer(&c)),
+	)
+	if hr := hresult(r1); hr.failed() {
+		return 0, fmt.Errorf("INetwork.GetCategory: %s", hr)
+	}
+	return c, nil
+}
+
+func (n *iNetwork) SetCategory(c networkCategory) error {
+	r1, _, _ := syscall.SyscallN(n.Vtbl.SetCategory,
+		uintptr(unsafe.Pointer(n)), uintptr(int32(c)),
+	)
+	if hr := hresult(r1); hr.failed() {
+		return fmt.Errorf("INetwork.SetCategory: %s", hr)
+	}
+	return nil
+}
+
+// coInit initializes COM for the current OS thread. The returned function must
+// be deferred to balance a successful init. RPC_E_CHANGED_MODE means COM is
+// already initialized in a different mode on this thread, which is still fine
+// for our calls but we must not Uninitialize in that case.
+func coInit() (func(), error) {
+	err := windows.CoInitializeEx(0, windows.COINIT_MULTITHREADED)
+	if err == nil {
+		return windows.CoUninitialize, nil
+	}
+	if e, ok := err.(syscall.Errno); ok {
+		switch uint32(e) {
+		case hrSFALSE:
+			return windows.CoUninitialize, nil
+		case hrRPCEChangedMode:
+			return func() {}, nil
+		}
+	}
+	return nil, fmt.Errorf("CoInitializeEx: %w", err)
+}
+
+func createNetworkListManager() (*iNetworkListManager, error) {
+	var nlm *iNetworkListManager
+	r1, _, _ := procCoCreateInstance.Call(
+		uintptr(unsafe.Pointer(&clsidNetworkListManager)),
+		0,
+		uintptr(clsCtxAll),
+		uintptr(unsafe.Pointer(&iidINetworkListManager)),
+		uintptr(unsafe.Pointer(&nlm)),
+	)
+	if hr := hresult(r1); hr.failed() {
+		return nil, fmt.Errorf("CoCreateInstance(NetworkListManager): %s", hr)
+	}
+	return nlm, nil
+}
+
+// setNetworkCategory locates the network connection bound to adapterGUID and
+// sets the category of its parent network. Returns errAdapterNotFound if the
+// adapter is not yet visible in the NLM enumeration.
+func setNetworkCategory(adapterGUID windows.GUID, cat networkCategory) error {
+	deinit, err := coInit()
+	if err != nil {
+		return err
+	}
+	defer deinit()
+
+	nlm, err := createNetworkListManager()
+	if err != nil {
+		return err
+	}
+	defer nlm.Release()
+
+	enum, err := nlm.GetNetworkConnections()
+	if err != nil {
+		return err
+	}
+	defer enum.Release()
+
+	for {
+		conn, err := enum.Next()
+		if err != nil {
+			return err
+		}
+		if conn == nil {
+			return errAdapterNotFound
+		}
+
+		guid, err := conn.GetAdapterId()
+		if err != nil || guid != adapterGUID {
+			conn.Release()
+			continue
+		}
+
+		net, err := conn.GetNetwork()
+		conn.Release()
+		if err != nil {
+			return err
+		}
+		err = net.SetCategory(cat)
+		net.Release()
+		return err
+	}
+}
+
+// applyNetworkCategory polls until the wintun adapter shows up in the NLM
+// enumeration, then sets the category. Intended to run in its own goroutine.
+func applyNetworkCategory(l *slog.Logger, adapterGUID windows.GUID, cat networkCategory) {
+	// COM Init/Uninit must be paired on the same OS thread.
+	runtime.LockOSThread()
+	defer runtime.UnlockOSThread()
+
+	const (
+		attempts = 30
+		interval = 500 * time.Millisecond
+	)
+	for i := 0; i < attempts; i++ {
+		err := setNetworkCategory(adapterGUID, cat)
+		if err == nil {
+			l.Info("Set Windows network category", "category", cat.String())
+			return
+		}
+		if !errors.Is(err, errAdapterNotFound) {
+			l.Warn("Failed to set Windows network category", "error", err, "category", cat.String())
+			return
+		}
+		time.Sleep(interval)
+	}
+	l.Warn("Gave up waiting for adapter to appear in NLM enumeration; network category not set",
+		"category", cat.String(),
+		"waited", time.Duration(attempts)*interval,
+	)
+}

overlay/network_category_windows_test.go

@@ -0,0 +1,109 @@
+//go:build !e2e_testing
+// +build !e2e_testing
+
+package overlay
+
+import (
+	"testing"
+)
+
+func Test_parseNetworkCategory(t *testing.T) {
+	cases := []struct {
+		in        string
+		wantCat   networkCategory
+		wantApply bool
+		wantErr   bool
+	}{
+		{"", 0, false, false},
+		{"unset", 0, false, false},
+		{"  UNSET  ", 0, false, false},
+		{"private", networkCategoryPrivate, true, false},
+		{"Private", networkCategoryPrivate, true, false},
+		{"  PRIVATE  ", networkCategoryPrivate, true, false},
+		{"public", networkCategoryPublic, true, false},
+		{"PUBLIC", networkCategoryPublic, true, false},
+		{"domain", networkCategoryDomainAuthenticated, true, false},
+		{"DomainAuthenticated", networkCategoryDomainAuthenticated, true, false},
+		{"garbage", 0, false, true},
+		{"privates", 0, false, true},
+	}
+	for _, tc := range cases {
+		cat, apply, err := parseNetworkCategory(tc.in)
+		if (err != nil) != tc.wantErr {
+			t.Errorf("parseNetworkCategory(%q) err=%v, wantErr=%v", tc.in, err, tc.wantErr)
+			continue
+		}
+		if cat != tc.wantCat || apply != tc.wantApply {
+			t.Errorf("parseNetworkCategory(%q) = (%v, %v), want (%v, %v)", tc.in, cat, apply, tc.wantCat, tc.wantApply)
+		}
+	}
+}
+
+// Test_NLM_round_trip exercises every COM call path used by setNetworkCategory
+// without mutating the host's network state. It validates the CLSID/IID
+// constants and every vtable index by enumerating connections, fetching the
+// adapter id and parent network, reading the current category, and writing it
+// back unchanged.
+//
+// Requires Windows but does not require admin or the wintun driver. Skips if
+// no network connections are available (unlikely outside of an isolated
+// container).
+func Test_NLM_round_trip(t *testing.T) {
+	deinit, err := coInit()
+	if err != nil {
+		t.Fatalf("coInit: %v", err)
+	}
+	defer deinit()
+
+	nlm, err := createNetworkListManager()
+	if err != nil {
+		t.Fatalf("createNetworkListManager: %v", err)
+	}
+	defer nlm.Release()
+
+	enum, err := nlm.GetNetworkConnections()
+	if err != nil {
+		t.Fatalf("GetNetworkConnections: %v", err)
+	}
+	defer enum.Release()
+
+	saw := 0
+	for {
+		conn, err := enum.Next()
+		if err != nil {
+			t.Fatalf("EnumNetworkConnections.Next: %v", err)
+		}
+		if conn == nil {
+			break
+		}
+		saw++
+
+		if _, err := conn.GetAdapterId(); err != nil {
+			conn.Release()
+			t.Fatalf("INetworkConnection.GetAdapterId: %v", err)
+		}
+
+		net, err := conn.GetNetwork()
+		conn.Release()
+		if err != nil {
+			t.Fatalf("INetworkConnection.GetNetwork: %v", err)
+		}
+
+		cat, err := net.GetCategory()
+		if err != nil {
+			net.Release()
+			t.Fatalf("INetwork.GetCategory: %v", err)
+		}
+		// Set to the current value so the host's NLM state is unchanged but
+		// SetCategory's vtable slot is still validated end-to-end.
+		if err := net.SetCategory(cat); err != nil {
+			net.Release()
+			t.Fatalf("INetwork.SetCategory(%v): %v", cat, err)
+		}
+		net.Release()
+	}
+
+	if saw == 0 {
+		t.Skip("no NLM network connections available; skipping round-trip")
+	}
+}

overlay/overlaytest/noop.go

@@ -4,10 +4,11 @@ package overlaytest
 
 import (
 	"errors"
-	"io"
 	"net/netip"
 
+	"github.com/slackhq/nebula/overlay/tio"
 	"github.com/slackhq/nebula/routing"
+	"github.com/slackhq/nebula/wire"
 )
 
 // NoopTun is an overlay.Device that silently discards every read and write.
@@ -15,6 +16,10 @@ import (
 // exercise the datapath.
 type NoopTun struct{}
 
+func (NoopTun) Capabilities() tio.Capabilities {
+	return tio.Capabilities{}
+}
+
 func (NoopTun) RoutesFor(addr netip.Addr) routing.Gateways {
 	return routing.Gateways{}
 }
@@ -31,7 +36,7 @@ func (NoopTun) Name() string {
 	return "noop"
 }
 
-func (NoopTun) Read([]byte) (int, error) {
+func (NoopTun) Read(p []wire.TunPacket, mem []byte) (int, error) {
 	return 0, nil
 }
 
@@ -43,8 +48,12 @@ func (NoopTun) SupportsMultiqueue() bool {
 	return false
 }
 
-func (NoopTun) NewMultiQueueReader() (io.ReadWriteCloser, error) {
-	return nil, errors.New("unsupported")
+func (NoopTun) NewMultiQueueReader() error {
+	return errors.New("unsupported")
+}
+
+func (NoopTun) Readers() []tio.Queue {
+	return []tio.Queue{NoopTun{}}
 }
 
 func (NoopTun) Close() error {

overlay/tio/queueset_poll_linux.go

@@ -0,0 +1,80 @@
+package tio
+
+import (
+	"encoding/binary"
+	"errors"
+	"fmt"
+
+	"golang.org/x/sys/unix"
+)
+
+type pollQueueSet struct {
+	pq []*Poll
+	// pqi is exactly the same as pq, but stored as the interface type
+	pqi        []Queue
+	shutdownFd int
+}
+
+func NewPollQueueSet() (QueueSet, error) {
+	shutdownFd, err := unix.Eventfd(0, unix.EFD_NONBLOCK|unix.EFD_CLOEXEC)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create eventfd: %w", err)
+	}
+
+	out := &pollQueueSet{
+		pq:         []*Poll{},
+		pqi:        []Queue{},
+		shutdownFd: shutdownFd,
+	}
+
+	return out, nil
+}
+
+func (c *pollQueueSet) Queues() []Queue {
+	return c.pqi
+}
+
+func (c *pollQueueSet) Add(fd int) error {
+	x, err := newPoll(fd, c.shutdownFd)
+	if err != nil {
+		return err
+	}
+	c.pq = append(c.pq, x)
+	c.pqi = append(c.pqi, x)
+
+	return nil
+}
+
+func (c *pollQueueSet) wakeForShutdown() error {
+	var buf [8]byte
+	binary.NativeEndian.PutUint64(buf[:], 1)
+	_, err := unix.Write(c.shutdownFd, buf[:])
+	return err
+}
+
+func (c *pollQueueSet) Close() error {
+	if c.shutdownFd < 0 {
+		return nil
+	}
+
+	errs := []error{}
+
+	if err := c.wakeForShutdown(); err != nil {
+		errs = append(errs, err)
+	}
+
+	for _, x := range c.pq {
+		if err := x.Close(); err != nil {
+			errs = append(errs, err)
+		}
+	}
+
+	// All Polls reference shutdownFd in their pollfd arrays, so close it
+	// only after every Poll.Close has returned.
+	if err := unix.Close(c.shutdownFd); err != nil {
+		errs = append(errs, err)
+	}
+	c.shutdownFd = -1
+
+	return errors.Join(errs...)
+}

overlay/tio/tio.go

@@ -0,0 +1,122 @@
+package tio
+
+import (
+	"io"
+
+	"github.com/slackhq/nebula/wire"
+)
+
+// QueueSet holds one or many Queue objects and helps close them in an orderly way.
+type QueueSet interface {
+	io.Closer
+	Queues() []Queue
+
+	// Add takes a tun fd, adds it to the set, and prepares it for use as a Queue.
+	Add(fd int) error
+}
+
+// Capabilities advertises which kernel offload features a Queue successfully negotiated.
+// Callers consult this to decide which coalescers to wire onto the write path.
+type Capabilities struct {
+	// TSO means the FD was opened with IFF_VNET_HDR and the kernel agreed
+	// to TUN_F_TSO4|TSO6 — i.e. WriteGSO with GSOProtoTCP is safe.
+	TSO bool
+	// USO means the kernel additionally agreed to TUN_F_USO4|USO6, so
+	// WriteGSO with GSOProtoUDP is safe. Linux ≥ 6.2.
+	USO bool
+}
+
+// Queue is a readable/writable Poll queue. One Queue is driven by a single
+// read goroutine plus a single writer (see Write below).
+type Queue interface {
+	io.Closer
+
+	// Read will read at least 1 packet from the tun (up to len(p)).
+	// mem will be used to provide the backing for each of p[n].Bytes.
+	// Callers should size mem and p to avoid exhausting mem before p.
+	// Returns the number of packets actually read, or error.
+	Read(p []wire.TunPacket, mem []byte) (int, error)
+
+	// Write emits a single packet on the plaintext (outside→inside)
+	// delivery path.
+	Write(p []byte) (int, error)
+
+	// Capabilities returns the Queue's negotiated offload capabilities,
+	// or the zero value when q does not advertise any.
+	Capabilities() Capabilities
+}
+
+// GSOInfo describes a kernel-supplied superpacket sitting in Packet.Bytes.
+// The zero value means "not a superpacket" — Bytes is one regular IP
+// datagram and no segmentation is required.
+type GSOInfo struct {
+	// Size is the GSO segment size: max payload bytes per segment
+	// (== TCP MSS for TSO, == UDP payload chunk for USO). Zero means
+	// not a superpacket.
+	Size uint16
+	// HdrLen is the total L3+L4 header length within Bytes (already
+	// corrected via correctHdrLen, so safe to slice on).
+	HdrLen uint16
+	// CsumStart is the L4 header offset inside Bytes (== L3 header
+	// length).
+	CsumStart uint16
+	// Proto picks the L4 protocol (TCP or UDP) so the segmenter knows
+	// which checksum/header layout to apply.
+	Proto GSOProto
+}
+
+// GSOProto selects the L4 protocol for a GSO superpacket. Determines which
+// VIRTIO_NET_HDR_GSO_* type the writer stamps and which checksum offset
+// inside the transport header virtio NEEDS_CSUM expects.
+type GSOProto uint8
+
+const (
+	GSOProtoNone GSOProto = iota
+	GSOProtoTCP
+	GSOProtoUDP
+)
+
+// GSOWriter is implemented by Queues that can emit a TCP or UDP superpacket
+// assembled from a header prefix plus one or more borrowed payload
+// fragments, in a single vectored write (writev with a leading
+// virtio_net_hdr). This lets the coalescer avoid copying payload bytes
+// between the caller's decrypt buffer and the TUN. Backends without GSO
+// support do not implement this interface and coalescing is skipped.
+//
+// hdr contains the IPv4/IPv6 header prefix (mutable - callers will have
+// filled in total length and IP csum). transportHdr is the TCP or UDP
+// header (mutable - the L4 checksum field must hold the pseudo-header
+// partial, single-fold not inverted, per virtio NEEDS_CSUM semantics).
+// pays are non-overlapping payload fragments whose concatenation is the
+// full superpacket payload; they are read-only from the writer's
+// perspective and must remain valid until the call returns. Every segment
+// in pays except possibly the last is exactly the same size. proto picks
+// the L4 protocol so the writer knows which GSOType / CsumOffset to set.
+//
+// Callers should also consult CapsProvider (via SupportsGSO or
+// QueueCapabilities) for the per-protocol negotiated capability; an
+// implementation of GSOWriter is necessary but not sufficient since USO
+// may not have been negotiated even when TSO was.
+type GSOWriter interface {
+	WriteGSO(hdr []byte, transportHdr []byte, pays [][]byte, proto GSOProto) error
+}
+
+// SupportsGSO reports whether w implements GSOWriter and the underlying
+// queue advertises the negotiated capability for `want`. A writer that
+// implements GSOWriter but not CapsProvider is treated as permissive
+// (used by tests and fakes that don't negotiate).
+func SupportsGSO(w Queue, want GSOProto) (GSOWriter, bool) {
+	gw, ok := w.(GSOWriter)
+	if !ok {
+		return nil, false
+	}
+	caps := w.Capabilities()
+	switch want {
+	case GSOProtoTCP:
+		return gw, caps.TSO
+	case GSOProtoUDP:
+		return gw, caps.USO
+	default:
+		return gw, false
+	}
+}

overlay/tio/tio_poll_linux.go

@@ -0,0 +1,168 @@
+package tio
+
+import (
+	"fmt"
+	"os"
+	"sync"
+	"sync/atomic"
+
+	"github.com/slackhq/nebula/wire"
+	"golang.org/x/sys/unix"
+)
+
+type Poll struct {
+	fd int
+
+	readPoll  [2]unix.PollFd
+	writePoll [2]unix.PollFd
+	writeLock sync.Mutex
+	closed    atomic.Bool
+}
+
+func newPoll(fd int, shutdownFd int) (*Poll, error) {
+	if err := unix.SetNonblock(fd, true); err != nil {
+		_ = unix.Close(fd)
+		return nil, fmt.Errorf("failed to set Poll device as nonblocking: %w", err)
+	}
+
+	out := &Poll{
+		fd: fd,
+		readPoll: [2]unix.PollFd{
+			{Fd: int32(fd), Events: unix.POLLIN},
+			{Fd: int32(shutdownFd), Events: unix.POLLIN},
+		},
+		writePoll: [2]unix.PollFd{
+			{Fd: int32(fd), Events: unix.POLLOUT},
+			{Fd: int32(shutdownFd), Events: unix.POLLIN},
+		},
+		writeLock: sync.Mutex{},
+	}
+	return out, nil
+}
+
+// blockOnRead waits until the Poll fd is readable or shutdown has been signaled.
+// Returns os.ErrClosed if Close was called.
+func (t *Poll) blockOnRead() error {
+	const problemFlags = unix.POLLHUP | unix.POLLNVAL | unix.POLLERR
+	var err error
+	for {
+		_, err = unix.Poll(t.readPoll[:], -1)
+		if err != unix.EINTR {
+			break
+		}
+	}
+	tunEvents := t.readPoll[0].Revents
+	shutdownEvents := t.readPoll[1].Revents
+	t.readPoll[0].Revents = 0
+	t.readPoll[1].Revents = 0
+	if err != nil {
+		return err
+	}
+	if shutdownEvents&(unix.POLLIN|problemFlags) != 0 {
+		return os.ErrClosed
+	}
+	if tunEvents&problemFlags != 0 {
+		return os.ErrClosed
+	}
+	return nil
+}
+
+func (t *Poll) blockOnWrite() error {
+	const problemFlags = unix.POLLHUP | unix.POLLNVAL | unix.POLLERR
+	var err error
+	for {
+		_, err = unix.Poll(t.writePoll[:], -1)
+		if err != unix.EINTR {
+			break
+		}
+	}
+	t.writeLock.Lock()
+	tunEvents := t.writePoll[0].Revents
+	shutdownEvents := t.writePoll[1].Revents
+	t.writePoll[0].Revents = 0
+	t.writePoll[1].Revents = 0
+	t.writeLock.Unlock()
+	if err != nil {
+		return err
+	}
+	if shutdownEvents&(unix.POLLIN|problemFlags) != 0 {
+		return os.ErrClosed
+	}
+	if tunEvents&problemFlags != 0 {
+		return os.ErrClosed
+	}
+	return nil
+}
+
+func (t *Poll) Read(p []wire.TunPacket, mem []byte) (int, error) {
+	if len(p) == 0 || len(mem) == 0 {
+		return 0, nil //todo should this be an err?
+	}
+	p[0].Meta = struct{}{}
+	n, err := t.readOne(mem)
+	if err != nil {
+		return 0, err
+	}
+	p[0].Bytes = mem[:n]
+	return 1, nil
+}
+
+func (t *Poll) readOne(to []byte) (int, error) {
+	for {
+		n, errno := unix.Read(t.fd, to)
+		if errno == nil {
+			return n, nil
+		}
+		switch errno {
+		case unix.EAGAIN:
+			if err := t.blockOnRead(); err != nil {
+				return 0, err
+			}
+		case unix.EINTR:
+			// retry
+		case unix.EBADF:
+			return 0, os.ErrClosed
+		default:
+			return 0, errno
+		}
+	}
+}
+
+func (t *Poll) Write(from []byte) (int, error) {
+	for {
+		n, errno := unix.Write(t.fd, from)
+		if errno == nil {
+			return n, nil
+		}
+		switch errno {
+		case unix.EAGAIN:
+			if err := t.blockOnWrite(); err != nil {
+				return 0, err
+			}
+		case unix.EINTR:
+			// retry
+		case unix.EBADF:
+			return 0, os.ErrClosed
+		default:
+			return 0, errno
+		}
+	}
+}
+
+func (t *Poll) Close() error {
+	if t.closed.Swap(true) {
+		return nil
+	}
+	//shutdownFd is owned by the container, so we should not close it
+	var err error
+	if t.fd >= 0 {
+		err = unix.Close(t.fd)
+		t.fd = -1
+	}
+
+	return err
+}
+
+func (t *Poll) Capabilities() Capabilities {
+	return Capabilities{}
+}

overlay/tio/tun_file_linux_test.go

@@ -0,0 +1,106 @@
+//go:build linux && !android && !e2e_testing
+// +build linux,!android,!e2e_testing
+
+package tio
+
+import (
+	"errors"
+	"os"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/slackhq/nebula/wire"
+	"github.com/stretchr/testify/require"
+	"golang.org/x/sys/unix"
+)
+
+// newReadPipe returns a read fd. The matching write fd is registered for cleanup.
+// The caller takes ownership of the read fd (pass it into a QueueSet).
+func newReadPipe(t *testing.T) int {
+	t.Helper()
+	var fds [2]int
+	if err := unix.Pipe2(fds[:], unix.O_CLOEXEC); err != nil {
+		t.Fatalf("pipe2: %v", err)
+	}
+	t.Cleanup(func() { _ = unix.Close(fds[1]) })
+	return fds[0]
+}
+
+func TestPoll_WakeForShutdown_WakesFriends(t *testing.T) {
+	parent, err := NewPollQueueSet()
+	require.NoError(t, err)
+	require.NoError(t, parent.Add(newReadPipe(t)))
+	require.NoError(t, parent.Add(newReadPipe(t)))
+	// QueueSet.Close owns the read fds we Added — don't register a separate
+	// Cleanup to close them or we'll double-close whatever fd the kernel
+	// has since reused.
+
+	readers := parent.Queues()
+	errs := make([]error, len(readers))
+	var wg sync.WaitGroup
+	for i, r := range readers {
+		wg.Add(1)
+		go func(i int, r Queue) {
+			defer wg.Done()
+			pkts := make([]wire.TunPacket, 1)
+			_, errs[i] = r.Read(pkts, make([]byte, 64))
+		}(i, r)
+	}
+
+	time.Sleep(50 * time.Millisecond)
+
+	if err := parent.Close(); err != nil {
+		t.Fatalf("Close: %v", err)
+	}
+
+	done := make(chan struct{})
+	go func() { wg.Wait(); close(done) }()
+	select {
+	case <-done:
+	case <-time.After(2 * time.Second):
+		t.Fatal("readers did not wake")
+	}
+
+	for i, err := range errs {
+		if !errors.Is(err, os.ErrClosed) {
+			t.Errorf("reader %d: expected os.ErrClosed, got %v", i, err)
+		}
+	}
+}
+
+func TestPoll_Close_Idempotent(t *testing.T) {
+	shutdownFd, err := unix.Eventfd(0, unix.EFD_NONBLOCK|unix.EFD_CLOEXEC)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = unix.Close(shutdownFd) })
+
+	tf, err := newPoll(newReadPipe(t), shutdownFd)
+	require.NoError(t, err)
+	if err := tf.Close(); err != nil {
+		t.Fatalf("first Close: %v", err)
+	}
+	if err := tf.Close(); err != nil {
+		t.Fatalf("second Close should be a no-op, got %v", err)
+	}
+}
+
+func TestPollQueueSet_Close_ClosesEventfd(t *testing.T) {
+	qs, err := NewPollQueueSet()
+	require.NoError(t, err)
+	require.NoError(t, qs.Add(newReadPipe(t)))
+
+	fd := qs.(*pollQueueSet).shutdownFd
+	require.NoError(t, qs.Close())
+
+	// Closing the eventfd again should fail with EBADF, proving Close
+	// actually released it.
+	if err := unix.Close(fd); err == nil {
+		t.Fatalf("eventfd %d still open after QueueSet.Close", fd)
+	}
+
+	// Second Close must be a no-op (and must not double-close the eventfd
+	// in case the kernel handed it out to another caller in the meantime).
+	if err := qs.Close(); err != nil {
+		t.Fatalf("second Close: %v", err)
+	}
+}

overlay/tun_android.go

@@ -13,12 +13,14 @@ import (
 
 	"github.com/gaissmai/bart"
 	"github.com/slackhq/nebula/config"
+	"github.com/slackhq/nebula/overlay/tio"
 	"github.com/slackhq/nebula/routing"
 	"github.com/slackhq/nebula/util"
+	"github.com/slackhq/nebula/wire"
 )
 
 type tun struct {
-	io.ReadWriteCloser
+	rwc         io.ReadWriteCloser
 	fd          int
 	vpnNetworks []netip.Prefix
 	Routes      atomic.Pointer[[]Route]
@@ -26,16 +28,37 @@ type tun struct {
 	l           *slog.Logger
 }
 
+func (t *tun) Read(p []wire.TunPacket, mem []byte) (int, error) {
+	if len(p) == 0 || len(mem) == 0 {
+		return 0, nil //todo should this be an err?
+	}
+	p[0].Meta = struct{}{}
+	n, err := t.rwc.Read(mem)
+	if err != nil {
+		return 0, err
+	}
+	p[0].Bytes = mem[:n]
+	return 1, nil
+}
+
+func (t *tun) Write(p []byte) (int, error) {
+	return t.rwc.Write(p)
+}
+
+func (t *tun) Close() error {
+	return t.rwc.Close()
+}
+
 func newTunFromFd(c *config.C, l *slog.Logger, deviceFd int, vpnNetworks []netip.Prefix) (*tun, error) {
 	// XXX Android returns an fd in non-blocking mode which is necessary for shutdown to work properly.
 	// Be sure not to call file.Fd() as it will set the fd to blocking mode.
 	file := os.NewFile(uintptr(deviceFd), "/dev/net/tun")
 
 	t := &tun{
-		ReadWriteCloser: file,
-		fd:              deviceFd,
-		vpnNetworks:     vpnNetworks,
-		l:               l,
+		rwc:         file,
+		fd:          deviceFd,
+		vpnNetworks: vpnNetworks,
+		l:           l,
 	}
 
 	err := t.reload(c, true)
@@ -62,7 +85,7 @@ func (t *tun) RoutesFor(ip netip.Addr) routing.Gateways {
 	return r
 }
 
-func (t tun) Activate() error {
+func (t *tun) Activate() error {
 	return nil
 }
 
@@ -99,6 +122,14 @@ func (t *tun) SupportsMultiqueue() bool {
 	return false
 }
 
-func (t *tun) NewMultiQueueReader() (io.ReadWriteCloser, error) {
-	return nil, fmt.Errorf("TODO: multiqueue not implemented for android")
+func (t *tun) NewMultiQueueReader() error {
+	return fmt.Errorf("TODO: multiqueue not implemented for android")
+}
+
+func (t *tun) Readers() []tio.Queue {
+	return []tio.Queue{t}
+}
+
+func (t *tun) Capabilities() tio.Capabilities {
+	return tio.Capabilities{}
 }

overlay/tun_bypass_windows.go

@@ -0,0 +1,23 @@
+//go:build (amd64 || arm64) && !e2e_testing
+// +build amd64 arm64
+// +build !e2e_testing
+
+package overlay
+
+import (
+	"log/slog"
+
+	"github.com/slackhq/nebula/wfp"
+)
+
+// installInterfaceBypass installs a WFP PERMIT filter scoped to the wintun interface LUID so inbound traffic on the
+// nebula adapter bypasses Windows Defender Firewall.
+func installInterfaceBypass(l *slog.Logger, luid uint64) closer {
+	s, err := wfp.PermitInterface(luid)
+	if err != nil {
+		l.Warn("Failed to install WFP bypass filters on nebula interface", "error", err)
+		return nil
+	}
+	l.Info("Installed WFP filters bypassing Windows Defender Firewall on nebula interface")
+	return s
+}

overlay/tun_bypass_windows_386.go

@@ -0,0 +1,11 @@
+//go:build !e2e_testing
+// +build !e2e_testing
+
+package overlay
+
+import "log/slog"
+
+// installInterfaceBypass is a no-op on windows-386 because we don't currently build for it.
+func installInterfaceBypass(_ *slog.Logger, _ uint64) closer {
+	return nil
+}

overlay/tun_darwin.go

@@ -16,14 +16,16 @@ import (
 
 	"github.com/gaissmai/bart"
 	"github.com/slackhq/nebula/config"
+	"github.com/slackhq/nebula/overlay/tio"
 	"github.com/slackhq/nebula/routing"
 	"github.com/slackhq/nebula/util"
+	"github.com/slackhq/nebula/wire"
 	netroute "golang.org/x/net/route"
 	"golang.org/x/sys/unix"
 )
 
 type tun struct {
-	io.ReadWriteCloser
+	rwc         io.ReadWriteCloser
 	Device      string
 	vpnNetworks []netip.Prefix
 	DefaultMTU  int
@@ -124,11 +126,11 @@ func newTun(c *config.C, l *slog.Logger, vpnNetworks []netip.Prefix, _ bool) (*t
 	}
 
 	t := &tun{
-		ReadWriteCloser: os.NewFile(uintptr(fd), ""),
-		Device:          name,
-		vpnNetworks:     vpnNetworks,
-		DefaultMTU:      c.GetInt("tun.mtu", DefaultMTU),
-		l:               l,
+		rwc:         os.NewFile(uintptr(fd), ""),
+		Device:      name,
+		vpnNetworks: vpnNetworks,
+		DefaultMTU:  c.GetInt("tun.mtu", DefaultMTU),
+		l:           l,
 	}
 
 	err = t.reload(c, true)
@@ -158,8 +160,8 @@ func newTunFromFd(_ *config.C, _ *slog.Logger, _ int, _ []netip.Prefix) (*tun, e
 }
 
 func (t *tun) Close() error {
-	if t.ReadWriteCloser != nil {
-		return t.ReadWriteCloser.Close()
+	if t.rwc != nil {
+		return t.rwc.Close()
 	}
 	return nil
 }
@@ -502,13 +504,17 @@ func delRoute(prefix netip.Prefix, gateway netroute.Addr) error {
 	return nil
 }
 
-func (t *tun) Read(to []byte) (int, error) {
-	buf := make([]byte, len(to)+4)
-
-	n, err := t.ReadWriteCloser.Read(buf)
-
-	copy(to, buf[4:])
-	return n - 4, err
+func (t *tun) Read(p []wire.TunPacket, mem []byte) (int, error) {
+	if len(p) == 0 || len(mem) <= 4 {
+		return 0, nil //todo should this be an err?
+	}
+	p[0].Meta = struct{}{}
+	n, err := t.rwc.Read(mem)
+	if err != nil {
+		return 0, err
+	}
+	p[0].Bytes = mem[4:n]
+	return 1, nil
 }
 
 // Write is only valid for single threaded use
@@ -536,7 +542,7 @@ func (t *tun) Write(from []byte) (int, error) {
 
 	copy(buf[4:], from)
 
-	n, err := t.ReadWriteCloser.Write(buf)
+	n, err := t.rwc.Write(buf)
 	return n - 4, err
 }
 
@@ -552,6 +558,14 @@ func (t *tun) SupportsMultiqueue() bool {
 	return false
 }
 
-func (t *tun) NewMultiQueueReader() (io.ReadWriteCloser, error) {
-	return nil, fmt.Errorf("TODO: multiqueue not implemented for darwin")
+func (t *tun) NewMultiQueueReader() error {
+	return fmt.Errorf("TODO: multiqueue not implemented for darwin")
+}
+
+func (t *tun) Readers() []tio.Queue {
+	return []tio.Queue{t}
+}
+
+func (t *tun) Capabilities() tio.Capabilities {
+	return tio.Capabilities{}
 }

overlay/tun_disabled.go

@@ -10,7 +10,9 @@ import (
 
 	"github.com/rcrowley/go-metrics"
 	"github.com/slackhq/nebula/iputil"
+	"github.com/slackhq/nebula/overlay/tio"
 	"github.com/slackhq/nebula/routing"
+	"github.com/slackhq/nebula/wire"
 )
 
 type disabledTun struct {
@@ -18,9 +20,10 @@ type disabledTun struct {
 	vpnNetworks []netip.Prefix
 
 	// Track these metrics since we don't have the tun device to do it for us
-	tx metrics.Counter
-	rx metrics.Counter
-	l  *slog.Logger
+	tx         metrics.Counter
+	rx         metrics.Counter
+	numReaders int
+	l          *slog.Logger
 }
 
 func newDisabledTun(vpnNetworks []netip.Prefix, queueLen int, metricsEnabled bool, l *slog.Logger) *disabledTun {
@@ -28,6 +31,7 @@ func newDisabledTun(vpnNetworks []netip.Prefix, queueLen int, metricsEnabled boo
 		vpnNetworks: vpnNetworks,
 		read:        make(chan []byte, queueLen),
 		l:           l,
+		numReaders:  1,
 	}
 
 	if metricsEnabled {
@@ -57,7 +61,7 @@ func (*disabledTun) Name() string {
 	return "disabled"
 }
 
-func (t *disabledTun) Read(b []byte) (int, error) {
+func (t *disabledTun) readOne(b []byte) (int, error) {
 	r, ok := <-t.read
 	if !ok {
 		return 0, io.EOF
@@ -75,6 +79,19 @@ func (t *disabledTun) Read(b []byte) (int, error) {
 	return copy(b, r), nil
 }
 
+func (t *disabledTun) Read(p []wire.TunPacket, mem []byte) (int, error) {
+	if len(p) == 0 || len(mem) == 0 {
+		return 0, nil //todo should this be an err?
+	}
+	p[0].Meta = struct{}{}
+	n, err := t.readOne(mem)
+	if err != nil {
+		return 0, err
+	}
+	p[0].Bytes = mem[:n]
+	return 1, nil
+}
+
 func (t *disabledTun) handleICMPEchoRequest(b []byte) bool {
 	out := make([]byte, len(b))
 	out = iputil.CreateICMPEchoResponse(b, out)
@@ -110,8 +127,21 @@ func (t *disabledTun) SupportsMultiqueue() bool {
 	return true
 }
 
-func (t *disabledTun) NewMultiQueueReader() (io.ReadWriteCloser, error) {
-	return t, nil
+func (t *disabledTun) NewMultiQueueReader() error {
+	t.numReaders++
+	return nil
+}
+
+func (t *disabledTun) Readers() []tio.Queue {
+	out := make([]tio.Queue, t.numReaders)
+	for i := range t.numReaders {
+		out[i] = t
+	}
+	return out
+}
+
+func (t *disabledTun) Capabilities() tio.Capabilities {
+	return tio.Capabilities{}
 }
 
 func (t *disabledTun) Close() error {

overlay/tun_file_linux_test.go

@@ -1,120 +0,0 @@
-//go:build linux && !android && !e2e_testing
-// +build linux,!android,!e2e_testing
-
-package overlay
-
-import (
-	"errors"
-	"os"
-	"sync"
-	"testing"
-	"time"
-
-	"golang.org/x/sys/unix"
-)
-
-// newReadPipe returns a read fd. The matching write fd is registered for cleanup.
-// The caller takes ownership of the read fd (pass it to newTunFd / newFriend).
-func newReadPipe(t *testing.T) int {
-	t.Helper()
-	var fds [2]int
-	if err := unix.Pipe2(fds[:], unix.O_CLOEXEC); err != nil {
-		t.Fatalf("pipe2: %v", err)
-	}
-	t.Cleanup(func() { _ = unix.Close(fds[1]) })
-	return fds[0]
-}
-
-func TestTunFile_WakeForShutdown_UnblocksRead(t *testing.T) {
-	tf, err := newTunFd(newReadPipe(t))
-	if err != nil {
-		t.Fatalf("newTunFd: %v", err)
-	}
-	t.Cleanup(func() { _ = tf.Close() })
-
-	done := make(chan error, 1)
-	go func() {
-		_, err := tf.Read(make([]byte, 64))
-		done <- err
-	}()
-
-	// Verify Read is actually blocked in poll.
-	select {
-	case err := <-done:
-		t.Fatalf("Read returned before shutdown signal: %v", err)
-	case <-time.After(50 * time.Millisecond):
-	}
-
-	if err := tf.wakeForShutdown(); err != nil {
-		t.Fatalf("wakeForShutdown: %v", err)
-	}
-
-	select {
-	case err := <-done:
-		if !errors.Is(err, os.ErrClosed) {
-			t.Fatalf("expected os.ErrClosed, got %v", err)
-		}
-	case <-time.After(2 * time.Second):
-		t.Fatal("Read did not wake on shutdown")
-	}
-}
-
-func TestTunFile_WakeForShutdown_WakesFriends(t *testing.T) {
-	parent, err := newTunFd(newReadPipe(t))
-	if err != nil {
-		t.Fatalf("newTunFd: %v", err)
-	}
-	friend, err := parent.newFriend(newReadPipe(t))
-	if err != nil {
-		_ = parent.Close()
-		t.Fatalf("newFriend: %v", err)
-	}
-	t.Cleanup(func() {
-		_ = friend.Close()
-		_ = parent.Close()
-	})
-
-	readers := []*tunFile{parent, friend}
-	errs := make([]error, len(readers))
-	var wg sync.WaitGroup
-	for i, r := range readers {
-		wg.Add(1)
-		go func(i int, r *tunFile) {
-			defer wg.Done()
-			_, errs[i] = r.Read(make([]byte, 64))
-		}(i, r)
-	}
-
-	time.Sleep(50 * time.Millisecond)
-
-	if err := parent.wakeForShutdown(); err != nil {
-		t.Fatalf("wakeForShutdown: %v", err)
-	}
-
-	done := make(chan struct{})
-	go func() { wg.Wait(); close(done) }()
-	select {
-	case <-done:
-	case <-time.After(2 * time.Second):
-		t.Fatal("readers did not wake")
-	}
-
-	for i, err := range errs {
-		if !errors.Is(err, os.ErrClosed) {
-			t.Errorf("reader %d: expected os.ErrClosed, got %v", i, err)
-		}
-	}
-}
-
-func TestTunFile_Close_Idempotent(t *testing.T) {
-	tf, err := newTunFd(newReadPipe(t))
-	if err != nil {
-		t.Fatalf("newTunFd: %v", err)
-	}
-	if err := tf.Close(); err != nil {
-		t.Fatalf("first Close: %v", err)
-	}
-	if err := tf.Close(); err != nil {
-		t.Fatalf("second Close should be a no-op, got %v", err)
-	}
-}

overlay/tun_freebsd.go

@@ -7,7 +7,6 @@ import (
 	"bytes"
 	"errors"
 	"fmt"
-	"io"
 	"io/fs"
 	"log/slog"
 	"net/netip"
@@ -18,9 +17,10 @@ import (
 	"unsafe"
 
 	"github.com/gaissmai/bart"
+	"github.com/slackhq/nebula/wire"
 
 	"github.com/slackhq/nebula/config"
-
+	"github.com/slackhq/nebula/overlay/tio"
 	"github.com/slackhq/nebula/routing"
 	"github.com/slackhq/nebula/util"
 	netroute "golang.org/x/net/route"
@@ -157,7 +157,20 @@ func (t *tun) blockOnWrite() error {
 	return nil
 }
 
-func (t *tun) Read(to []byte) (int, error) {
+func (t *tun) Read(p []wire.TunPacket, mem []byte) (int, error) {
+	if len(p) == 0 || len(mem) == 0 {
+		return 0, nil //todo should this be an err?
+	}
+	p[0].Meta = struct{}{}
+	n, err := t.readOne(mem)
+	if err != nil {
+		return 0, err
+	}
+	p[0].Bytes = mem[:n]
+	return 1, nil
+}
+
+func (t *tun) readOne(to []byte) (int, error) {
 	// first 4 bytes is protocol family, in network byte order
 	var head [4]byte
 	iovecs := [2]syscall.Iovec{
@@ -565,8 +578,8 @@ func (t *tun) SupportsMultiqueue() bool {
 	return false
 }
 
-func (t *tun) NewMultiQueueReader() (io.ReadWriteCloser, error) {
-	return nil, fmt.Errorf("TODO: multiqueue not implemented for freebsd")
+func (t *tun) NewMultiQueueReader() error {
+	return fmt.Errorf("TODO: multiqueue not implemented for freebsd")
 }
 
 func (t *tun) addRoutes(logErrors bool) error {
@@ -593,6 +606,14 @@ func (t *tun) addRoutes(logErrors bool) error {
 	return nil
 }
 
+func (t *tun) Readers() []tio.Queue {
+	return []tio.Queue{t}
+}
+
+func (t *tun) Capabilities() tio.Capabilities {
+	return tio.Capabilities{}
+}
+
 func (t *tun) removeRoutes(routes []Route) error {
 	for _, r := range routes {
 		if !r.Install {

overlay/tun_ios.go

@@ -16,18 +16,41 @@ import (
 
 	"github.com/gaissmai/bart"
 	"github.com/slackhq/nebula/config"
+	"github.com/slackhq/nebula/overlay/tio"
 	"github.com/slackhq/nebula/routing"
 	"github.com/slackhq/nebula/util"
+	"github.com/slackhq/nebula/wire"
 )
 
 type tun struct {
-	io.ReadWriteCloser
+	rwc         io.ReadWriteCloser
 	vpnNetworks []netip.Prefix
 	Routes      atomic.Pointer[[]Route]
 	routeTree   atomic.Pointer[bart.Table[routing.Gateways]]
 	l           *slog.Logger
 }
 
+func (t *tun) Read(p []wire.TunPacket, mem []byte) (int, error) {
+	if len(p) == 0 || len(mem) <= 4 {
+		return 0, nil //todo should this be an err?
+	}
+	p[0].Meta = struct{}{}
+	n, err := t.rwc.Read(mem)
+	if err != nil {
+		return 0, err
+	}
+	p[0].Bytes = mem[4:n]
+	return 1, nil
+}
+
+func (t *tun) Write(p []byte) (int, error) {
+	return t.rwc.Write(p)
+}
+
+func (t *tun) Close() error {
+	return t.rwc.Close()
+}
+
 func newTun(_ *config.C, _ *slog.Logger, _ []netip.Prefix, _ bool) (*tun, error) {
 	return nil, fmt.Errorf("newTun not supported in iOS")
 }
@@ -35,9 +58,9 @@ func newTun(_ *config.C, _ *slog.Logger, _ []netip.Prefix, _ bool) (*tun, error)
 func newTunFromFd(c *config.C, l *slog.Logger, deviceFd int, vpnNetworks []netip.Prefix) (*tun, error) {
 	file := os.NewFile(uintptr(deviceFd), "/dev/tun")
 	t := &tun{
-		vpnNetworks:     vpnNetworks,
-		ReadWriteCloser: &tunReadCloser{f: file},
-		l:               l,
+		vpnNetworks: vpnNetworks,
+		rwc:         &tunReadCloser{f: file},
+		l:           l,
 	}
 
 	err := t.reload(c, true)
@@ -96,18 +119,9 @@ type tunReadCloser struct {
 	wBuf []byte
 }
 
+// Read returns a packet with the BSD 4-byte header, watch out!
 func (tr *tunReadCloser) Read(to []byte) (int, error) {
-	tr.rMu.Lock()
-	defer tr.rMu.Unlock()
-
-	if cap(tr.rBuf) < len(to)+4 {
-		tr.rBuf = make([]byte, len(to)+4)
-	}
-	tr.rBuf = tr.rBuf[:len(to)+4]
-
-	n, err := tr.f.Read(tr.rBuf)
-	copy(to, tr.rBuf[4:])
-	return n - 4, err
+	return tr.f.Read(to)
 }
 
 func (tr *tunReadCloser) Write(from []byte) (int, error) {
@@ -155,6 +169,14 @@ func (t *tun) SupportsMultiqueue() bool {
 	return false
 }
 
-func (t *tun) NewMultiQueueReader() (io.ReadWriteCloser, error) {
-	return nil, fmt.Errorf("TODO: multiqueue not implemented for ios")
+func (t *tun) NewMultiQueueReader() error {
+	return fmt.Errorf("TODO: multiqueue not implemented for ios")
+}
+
+func (t *tun) Readers() []tio.Queue {
+	return []tio.Queue{t}
+}
+
+func (t *tun) Capabilities() tio.Capabilities {
+	return tio.Capabilities{}
 }

overlay/tun_linux.go

@@ -4,9 +4,7 @@
 package overlay
 
 import (
-	"encoding/binary"
 	"fmt"
-	"io"
 	"log/slog"
 	"net"
 	"net/netip"
@@ -19,180 +17,15 @@ import (
 
 	"github.com/gaissmai/bart"
 	"github.com/slackhq/nebula/config"
+	"github.com/slackhq/nebula/overlay/tio"
 	"github.com/slackhq/nebula/routing"
 	"github.com/slackhq/nebula/util"
 	"github.com/vishvananda/netlink"
 	"golang.org/x/sys/unix"
 )
 
-// tunFile wraps a TUN file descriptor with poll-based reads. The FD provided will be changed to non-blocking.
-// A shared eventfd allows Close to wake all readers blocked in poll.
-type tunFile struct {
-	fd         int
-	shutdownFd int
-	lastOne    bool
-	readPoll   [2]unix.PollFd
-	writePoll  [2]unix.PollFd
-	closed     bool
-}
-
-// newFriend makes a tunFile for a MultiQueueReader that copies the shutdown eventfd from the parent tun
-func (r *tunFile) newFriend(fd int) (*tunFile, error) {
-	if err := unix.SetNonblock(fd, true); err != nil {
-		return nil, fmt.Errorf("failed to set tun fd non-blocking: %w", err)
-	}
-	return &tunFile{
-		fd:         fd,
-		shutdownFd: r.shutdownFd,
-		readPoll: [2]unix.PollFd{
-			{Fd: int32(fd), Events: unix.POLLIN},
-			{Fd: int32(r.shutdownFd), Events: unix.POLLIN},
-		},
-		writePoll: [2]unix.PollFd{
-			{Fd: int32(fd), Events: unix.POLLOUT},
-			{Fd: int32(r.shutdownFd), Events: unix.POLLIN},
-		},
-	}, nil
-}
-
-func newTunFd(fd int) (*tunFile, error) {
-	if err := unix.SetNonblock(fd, true); err != nil {
-		return nil, fmt.Errorf("failed to set tun fd non-blocking: %w", err)
-	}
-
-	shutdownFd, err := unix.Eventfd(0, unix.EFD_NONBLOCK|unix.EFD_CLOEXEC)
-	if err != nil {
-		return nil, fmt.Errorf("failed to create eventfd: %w", err)
-	}
-
-	out := &tunFile{
-		fd:         fd,
-		shutdownFd: shutdownFd,
-		lastOne:    true,
-		readPoll: [2]unix.PollFd{
-			{Fd: int32(fd), Events: unix.POLLIN},
-			{Fd: int32(shutdownFd), Events: unix.POLLIN},
-		},
-		writePoll: [2]unix.PollFd{
-			{Fd: int32(fd), Events: unix.POLLOUT},
-			{Fd: int32(shutdownFd), Events: unix.POLLIN},
-		},
-	}
-
-	return out, nil
-}
-
-func (r *tunFile) blockOnRead() error {
-	const problemFlags = unix.POLLHUP | unix.POLLNVAL | unix.POLLERR
-	var err error
-	for {
-		_, err = unix.Poll(r.readPoll[:], -1)
-		if err != unix.EINTR {
-			break
-		}
-	}
-	//always reset these!
-	tunEvents := r.readPoll[0].Revents
-	shutdownEvents := r.readPoll[1].Revents
-	r.readPoll[0].Revents = 0
-	r.readPoll[1].Revents = 0
-	//do the err check before trusting the potentially bogus bits we just got
-	if err != nil {
-		return err
-	}
-	if shutdownEvents&(unix.POLLIN|problemFlags) != 0 {
-		return os.ErrClosed
-	} else if tunEvents&problemFlags != 0 {
-		return os.ErrClosed
-	}
-	return nil
-}
-
-func (r *tunFile) blockOnWrite() error {
-	const problemFlags = unix.POLLHUP | unix.POLLNVAL | unix.POLLERR
-	var err error
-	for {
-		_, err = unix.Poll(r.writePoll[:], -1)
-		if err != unix.EINTR {
-			break
-		}
-	}
-	//always reset these!
-	tunEvents := r.writePoll[0].Revents
-	shutdownEvents := r.writePoll[1].Revents
-	r.writePoll[0].Revents = 0
-	r.writePoll[1].Revents = 0
-	//do the err check before trusting the potentially bogus bits we just got
-	if err != nil {
-		return err
-	}
-	if shutdownEvents&(unix.POLLIN|problemFlags) != 0 {
-		return os.ErrClosed
-	} else if tunEvents&problemFlags != 0 {
-		return os.ErrClosed
-	}
-	return nil
-}
-
-func (r *tunFile) Read(buf []byte) (int, error) {
-	for {
-		if n, err := unix.Read(r.fd, buf); err == nil {
-			return n, nil
-		} else if err == unix.EAGAIN {
-			if err = r.blockOnRead(); err != nil {
-				return 0, err
-			}
-			continue
-		} else if err == unix.EINTR {
-			continue
-		} else if err == unix.EBADF {
-			return 0, os.ErrClosed
-		} else {
-			return 0, err
-		}
-	}
-}
-
-func (r *tunFile) Write(buf []byte) (int, error) {
-	for {
-		if n, err := unix.Write(r.fd, buf); err == nil {
-			return n, nil
-		} else if err == unix.EAGAIN {
-			if err = r.blockOnWrite(); err != nil {
-				return 0, err
-			}
-			continue
-		} else if err == unix.EINTR {
-			continue
-		} else if err == unix.EBADF {
-			return 0, os.ErrClosed
-		} else {
-			return 0, err
-		}
-	}
-}
-
-func (r *tunFile) wakeForShutdown() error {
-	var buf [8]byte
-	binary.NativeEndian.PutUint64(buf[:], 1)
-	_, err := unix.Write(int(r.readPoll[1].Fd), buf[:])
-	return err
-}
-
-func (r *tunFile) Close() error {
-	if r.closed { // avoid closing more than once. Technically a fd could get re-used, which would be a problem
-		return nil
-	}
-	r.closed = true
-	if r.lastOne {
-		_ = unix.Close(r.shutdownFd)
-	}
-	return unix.Close(r.fd)
-}
-
 type tun struct {
-	*tunFile
-	readers     []*tunFile
+	readers     tio.QueueSet
 	closeLock   sync.Mutex
 	Device      string
 	vpnNetworks []netip.Prefix
@@ -239,7 +72,9 @@ type ifreqQLEN struct {
 }
 
 func newTunFromFd(c *config.C, l *slog.Logger, deviceFd int, vpnNetworks []netip.Prefix) (*tun, error) {
-	t, err := newTunGeneric(c, l, deviceFd, vpnNetworks)
+	// We don't know what flags the caller opened this fd with and can't turn
+	// on IFF_VNET_HDR after TUNSETIFF, so skip offload on inherited fds.
+	t, err := newTunGeneric(c, l, deviceFd, false, false, vpnNetworks)
 	if err != nil {
 		return nil, err
 	}
@@ -249,46 +84,60 @@ func newTunFromFd(c *config.C, l *slog.Logger, deviceFd int, vpnNetworks []netip
 	return t, nil
 }
 
-func newTun(c *config.C, l *slog.Logger, vpnNetworks []netip.Prefix, multiqueue bool) (*tun, error) {
+// openTunDev opens /dev/net/tun, creating the device node first if it's
+// missing (docker containers occasionally omit it).
+func openTunDev() (int, error) {
 	fd, err := unix.Open("/dev/net/tun", os.O_RDWR, 0)
-	if err != nil {
-		// If /dev/net/tun doesn't exist, try to create it (will happen in docker)
-		if os.IsNotExist(err) {
-			err = os.MkdirAll("/dev/net", 0755)
-			if err != nil {
-				return nil, fmt.Errorf("/dev/net/tun doesn't exist, failed to mkdir -p /dev/net: %w", err)
-			}
-			err = unix.Mknod("/dev/net/tun", unix.S_IFCHR|0600, int(unix.Mkdev(10, 200)))
-			if err != nil {
-				return nil, fmt.Errorf("failed to create /dev/net/tun: %w", err)
-			}
-
-			fd, err = unix.Open("/dev/net/tun", os.O_RDWR, 0)
-			if err != nil {
-				return nil, fmt.Errorf("created /dev/net/tun, but still failed: %w", err)
-			}
-		} else {
-			return nil, err
-		}
+	if err == nil {
+		return fd, nil
 	}
+	if !os.IsNotExist(err) {
+		return -1, err
+	}
+	if err = os.MkdirAll("/dev/net", 0755); err != nil {
+		return -1, fmt.Errorf("/dev/net/tun doesn't exist, failed to mkdir -p /dev/net: %w", err)
+	}
+	if err = unix.Mknod("/dev/net/tun", unix.S_IFCHR|0600, int(unix.Mkdev(10, 200))); err != nil {
+		return -1, fmt.Errorf("failed to create /dev/net/tun: %w", err)
+	}
+	fd, err = unix.Open("/dev/net/tun", os.O_RDWR, 0)
+	if err != nil {
+		return -1, fmt.Errorf("created /dev/net/tun, but still failed: %w", err)
+	}
+	return fd, nil
+}
 
+// tunSetIff runs TUNSETIFF with the given flags and returns the kernel-chosen
+// device name on success.
+func tunSetIff(fd int, name string, flags uint16) (string, error) {
 	var req ifReq
-	req.Flags = uint16(unix.IFF_TUN | unix.IFF_NO_PI)
+	req.Flags = flags
+	copy(req.Name[:], name)
+	if err := ioctl(uintptr(fd), uintptr(unix.TUNSETIFF), uintptr(unsafe.Pointer(&req))); err != nil {
+		return "", err
+	}
+	return strings.Trim(string(req.Name[:]), "\x00"), nil
+}
+
+func newTun(c *config.C, l *slog.Logger, vpnNetworks []netip.Prefix, multiqueue bool) (*tun, error) {
+	baseFlags := uint16(unix.IFF_TUN | unix.IFF_NO_PI)
 	if multiqueue {
-		req.Flags |= unix.IFF_MULTI_QUEUE
+		baseFlags |= unix.IFF_MULTI_QUEUE
 	}
 	nameStr := c.GetString("tun.dev", "")
-	copy(req.Name[:], nameStr)
-	if err = ioctl(uintptr(fd), uintptr(unix.TUNSETIFF), uintptr(unsafe.Pointer(&req))); err != nil {
-		_ = unix.Close(fd)
-		return nil, &NameError{
-			Name:       nameStr,
-			Underlying: err,
-		}
-	}
-	name := strings.Trim(string(req.Name[:]), "\x00")
 
-	t, err := newTunGeneric(c, l, fd, vpnNetworks)
+	fd, err := openTunDev()
+	if err != nil {
+		return nil, err
+	}
+
+	name, err := tunSetIff(fd, nameStr, baseFlags)
+	if err != nil {
+		_ = unix.Close(fd)
+		return nil, &NameError{Name: nameStr, Underlying: err}
+	}
+
+	t, err := newTunGeneric(c, l, fd, false, false, vpnNetworks)
 	if err != nil {
 		return nil, err
 	}
@@ -299,15 +148,21 @@ func newTun(c *config.C, l *slog.Logger, vpnNetworks []netip.Prefix, multiqueue
 }
 
 // newTunGeneric does all the stuff common to different tun initialization paths. It will close your files on error.
-func newTunGeneric(c *config.C, l *slog.Logger, fd int, vpnNetworks []netip.Prefix) (*tun, error) {
-	tfd, err := newTunFd(fd)
+func newTunGeneric(c *config.C, l *slog.Logger, fd int, vnetHdr, usoEnabled bool, vpnNetworks []netip.Prefix) (*tun, error) {
+	qs, err := tio.NewPollQueueSet()
+
 	if err != nil {
 		_ = unix.Close(fd)
 		return nil, err
 	}
+	err = qs.Add(fd)
+	if err != nil {
+		_ = unix.Close(fd)
+		return nil, err
+	}
+
 	t := &tun{
-		tunFile:                   tfd,
-		readers:                   []*tunFile{tfd},
+		readers:                   qs,
 		closeLock:                 sync.Mutex{},
 		vpnNetworks:               vpnNetworks,
 		TXQueueLen:                c.GetInt("tun.tx_queue", 500),
@@ -410,32 +265,29 @@ func (t *tun) SupportsMultiqueue() bool {
 	return true
 }
 
-func (t *tun) NewMultiQueueReader() (io.ReadWriteCloser, error) {
+func (t *tun) NewMultiQueueReader() error {
 	t.closeLock.Lock()
 	defer t.closeLock.Unlock()
 
 	fd, err := unix.Open("/dev/net/tun", os.O_RDWR, 0)
 	if err != nil {
-		return nil, err
+		return err
 	}
 
-	var req ifReq
-	req.Flags = uint16(unix.IFF_TUN | unix.IFF_NO_PI | unix.IFF_MULTI_QUEUE)
-	copy(req.Name[:], t.Device)
-	if err = ioctl(uintptr(fd), uintptr(unix.TUNSETIFF), uintptr(unsafe.Pointer(&req))); err != nil {
+	flags := uint16(unix.IFF_TUN | unix.IFF_NO_PI | unix.IFF_MULTI_QUEUE)
+
+	if _, err = tunSetIff(fd, t.Device, flags); err != nil {
 		_ = unix.Close(fd)
-		return nil, err
+		return err
 	}
 
-	out, err := t.tunFile.newFriend(fd)
+	err = t.readers.Add(fd)
 	if err != nil {
 		_ = unix.Close(fd)
-		return nil, err
+		return err
 	}
 
-	t.readers = append(t.readers, out)
-
-	return out, nil
+	return nil
 }
 
 func (t *tun) RoutesFor(ip netip.Addr) routing.Gateways {
@@ -603,6 +455,15 @@ func (t *tun) setDefaultRoute(cidr netip.Prefix) error {
 		Table:     unix.RT_TABLE_MAIN,
 		Type:      unix.RTN_UNICAST,
 	}
+	// Match the metric the kernel uses for its auto-installed connected
+	// route, so RouteReplace overwrites it in place instead of adding a
+	// second route at a worse metric. IPv6 connected routes are installed
+	// at metric 256 (IP6_RT_PRIO_KERN); IPv4 uses 0. Without this, the
+	// kernel route wins lookups and our MTU / AdvMSS / Features never
+	// apply on v6.
+	if cidr.Addr().Is6() {
+		nr.Priority = 256
+	}
 	err := netlink.RouteReplace(&nr)
 	if err != nil {
 		t.l.Warn("Failed to set default route MTU, retrying", "error", err, "cidr", cidr)
@@ -869,6 +730,10 @@ func (t *tun) updateRoutes(r netlink.RouteUpdate) {
 	t.routeTree.Store(newTree)
 }
 
+func (t *tun) Readers() []tio.Queue {
+	return t.readers.Queues()
+}
+
 func (t *tun) Close() error {
 	t.closeLock.Lock()
 	defer t.closeLock.Unlock()
@@ -878,32 +743,10 @@ func (t *tun) Close() error {
 		t.routeChan = nil
 	}
 
-	// Signal all readers blocked in poll to wake up and exit
-	_ = t.tunFile.wakeForShutdown()
-
 	if t.ioctlFd > 0 {
 		_ = unix.Close(int(t.ioctlFd))
 		t.ioctlFd = 0
 	}
 
-	for i := range t.readers {
-		if i == 0 {
-			continue //we want to close the zeroth reader last
-		}
-		err := t.readers[i].Close()
-		if err != nil {
-			t.l.Error("error closing tun reader", "reader", i, "error", err)
-		} else {
-			t.l.Info("closed tun reader", "reader", i)
-		}
-	}
-
-	//this is t.readers[0] too
-	err := t.tunFile.Close()
-	if err != nil {
-		t.l.Error("error closing tun reader", "reader", 0, "error", err)
-	} else {
-		t.l.Info("closed tun reader", "reader", 0)
-	}
-	return err
+	return t.readers.Close()
 }

overlay/tun_linux_test.go

@@ -3,7 +3,9 @@
 
 package overlay
 
-import "testing"
+import (
+	"testing"
+)
 
 var runAdvMSSTests = []struct {
 	name     string

overlay/tun_netbsd.go

@@ -6,7 +6,6 @@ package overlay
 import (
 	"errors"
 	"fmt"
-	"io"
 	"log/slog"
 	"net/netip"
 	"os"
@@ -17,8 +16,10 @@ import (
 
 	"github.com/gaissmai/bart"
 	"github.com/slackhq/nebula/config"
+	"github.com/slackhq/nebula/overlay/tio"
 	"github.com/slackhq/nebula/routing"
 	"github.com/slackhq/nebula/util"
+	"github.com/slackhq/nebula/wire"
 	netroute "golang.org/x/net/route"
 	"golang.org/x/sys/unix"
 )
@@ -68,6 +69,27 @@ type tun struct {
 	fd          int
 }
 
+func (t *tun) Read(p []wire.TunPacket, mem []byte) (int, error) {
+	if len(p) == 0 || len(mem) == 0 {
+		return 0, nil //todo should this be an err?
+	}
+	p[0].Meta = struct{}{}
+	n, err := t.readOne(mem)
+	if err != nil {
+		return 0, err
+	}
+	p[0].Bytes = mem[:n]
+	return 1, nil
+}
+
+func (t *tun) Readers() []tio.Queue {
+	return []tio.Queue{t}
+}
+
+func (t *tun) Capabilities() tio.Capabilities {
+	return tio.Capabilities{}
+}
+
 var deviceNameRE = regexp.MustCompile(`^tun[0-9]+$`)
 
 func newTunFromFd(_ *config.C, _ *slog.Logger, _ int, _ []netip.Prefix) (*tun, error) {
@@ -141,7 +163,7 @@ func (t *tun) Close() error {
 	return nil
 }
 
-func (t *tun) Read(to []byte) (int, error) {
+func (t *tun) readOne(to []byte) (int, error) {
 	rc, err := t.f.SyscallConn()
 	if err != nil {
 		return 0, fmt.Errorf("failed to get syscall conn for tun: %w", err)
@@ -394,8 +416,8 @@ func (t *tun) SupportsMultiqueue() bool {
 	return false
 }
 
-func (t *tun) NewMultiQueueReader() (io.ReadWriteCloser, error) {
-	return nil, fmt.Errorf("TODO: multiqueue not implemented for netbsd")
+func (t *tun) NewMultiQueueReader() error {
+	return fmt.Errorf("TODO: multiqueue not implemented for netbsd")
 }
 
 func (t *tun) addRoutes(logErrors bool) error {

overlay/tun_openbsd.go

@@ -6,7 +6,6 @@ package overlay
 import (
 	"errors"
 	"fmt"
-	"io"
 	"log/slog"
 	"net/netip"
 	"os"
@@ -17,8 +16,10 @@ import (
 
 	"github.com/gaissmai/bart"
 	"github.com/slackhq/nebula/config"
+	"github.com/slackhq/nebula/overlay/tio"
 	"github.com/slackhq/nebula/routing"
 	"github.com/slackhq/nebula/util"
+	"github.com/slackhq/nebula/wire"
 	netroute "golang.org/x/net/route"
 	"golang.org/x/sys/unix"
 )
@@ -61,6 +62,19 @@ type tun struct {
 	out []byte
 }
 
+func (t *tun) Read(p []wire.TunPacket, mem []byte) (int, error) {
+	if len(p) == 0 || len(mem) <= 4 {
+		return 0, nil //todo should this be an err?
+	}
+	p[0].Meta = struct{}{}
+	n, err := t.f.Read(mem)
+	if err != nil {
+		return 0, err
+	}
+	p[0].Bytes = mem[4:n]
+	return 1, nil
+}
+
 var deviceNameRE = regexp.MustCompile(`^tun[0-9]+$`)
 
 func newTunFromFd(_ *config.C, _ *slog.Logger, _ int, _ []netip.Prefix) (*tun, error) {
@@ -124,15 +138,6 @@ func (t *tun) Close() error {
 	return nil
 }
 
-func (t *tun) Read(to []byte) (int, error) {
-	buf := make([]byte, len(to)+4)
-
-	n, err := t.f.Read(buf)
-
-	copy(to, buf[4:])
-	return n - 4, err
-}
-
 // Write is only valid for single threaded use
 func (t *tun) Write(from []byte) (int, error) {
 	buf := t.out
@@ -314,8 +319,8 @@ func (t *tun) SupportsMultiqueue() bool {
 	return false
 }
 
-func (t *tun) NewMultiQueueReader() (io.ReadWriteCloser, error) {
-	return nil, fmt.Errorf("TODO: multiqueue not implemented for openbsd")
+func (t *tun) NewMultiQueueReader() error {
+	return fmt.Errorf("TODO: multiqueue not implemented for openbsd")
 }
 
 func (t *tun) addRoutes(logErrors bool) error {
@@ -366,6 +371,14 @@ func (t *tun) deviceBytes() (o [16]byte) {
 	return
 }
 
+func (t *tun) Readers() []tio.Queue {
+	return []tio.Queue{t}
+}
+
+func (t *tun) Capabilities() tio.Capabilities {
+	return tio.Capabilities{}
+}
+
 func addRoute(prefix netip.Prefix, gateways []netip.Prefix) error {
 	sock, err := unix.Socket(unix.AF_ROUTE, unix.SOCK_RAW, unix.AF_UNSPEC)
 	if err != nil {

overlay/tun_tester.go

@@ -14,7 +14,10 @@ import (
 
 	"github.com/gaissmai/bart"
 	"github.com/slackhq/nebula/config"
+	"github.com/slackhq/nebula/overlay/tio"
 	"github.com/slackhq/nebula/routing"
+	"github.com/slackhq/nebula/udp"
+	"github.com/slackhq/nebula/wire"
 )
 
 type TestTun struct {
@@ -54,9 +57,12 @@ func newTunFromFd(_ *config.C, _ *slog.Logger, _ int, _ []netip.Prefix) (*TestTu
 	return nil, fmt.Errorf("newTunFromFd not supported")
 }
 
-// Send will place a byte array onto the receive queue for nebula to consume
+// Send will place a byte array onto the receive queue for nebula to consume.
 // These are unencrypted ip layer frames destined for another nebula node.
-// packets should exit the udp side, capture them with udpConn.Get
+// packets should exit the udp side, capture them with udpConn.Get.
+//
+// Send copies the input via the freelist, so the caller is free to mutate
+// or reuse it after the call returns.
 func (t *TestTun) Send(packet []byte) {
 	if t.closed.Load() {
 		return
@@ -65,7 +71,9 @@ func (t *TestTun) Send(packet []byte) {
 	if t.l.Enabled(context.Background(), slog.LevelDebug) {
 		t.l.Debug("Tun receiving injected packet", "dataLen", len(packet))
 	}
-	t.rxPackets <- packet
+	buf := acquireTunBuf(len(packet))
+	copy(buf, packet)
+	t.rxPackets <- buf
 }
 
 // Get will pull an unencrypted ip layer frame from the transmit queue
@@ -110,12 +118,44 @@ func (t *TestTun) Write(b []byte) (n int, err error) {
 		return 0, io.ErrClosedPipe
 	}
 
-	packet := make([]byte, len(b), len(b))
+	packet := acquireTunBuf(len(b))
 	copy(packet, b)
 	t.TxPackets <- packet
 	return len(b), nil
 }
 
+// ReleaseTunBuf returns a slice from TxPackets to the harness freelist, don't use the bytes after the call.
+// Channel-backed instead of sync.Pool because putting a []byte in a sync.Pool escapes the slice header to heap.
+func ReleaseTunBuf(b []byte) {
+	if b == nil {
+		return
+	}
+	select {
+	case tunBufFreelist <- b:
+	default:
+		// Freelist full; drop the buffer for the GC.
+	}
+}
+
+// tunBufFreelist retains the backing arrays for TestTun.Write so steady-state allocation drops to zero once the
+// freelist has saturated for the current MTU.
+var tunBufFreelist = make(chan []byte, 64)
+
+func acquireTunBuf(n int) []byte {
+	var b []byte
+	select {
+	case b = <-tunBufFreelist:
+	default:
+		b = make([]byte, 0, udp.MTU)
+	}
+	if cap(b) < n {
+		b = make([]byte, n)
+	} else {
+		b = b[:n]
+	}
+	return b
+}
+
 func (t *TestTun) Close() error {
 	if t.closed.CompareAndSwap(false, true) {
 		close(t.rxPackets)
@@ -124,19 +164,46 @@ func (t *TestTun) Close() error {
 	return nil
 }
 
-func (t *TestTun) Read(b []byte) (int, error) {
+func (t *TestTun) Read(p []wire.TunPacket, mem []byte) (int, error) {
+	if len(p) == 0 || len(mem) == 0 {
+		return 0, nil //todo should this be an err?
+	}
+	p[0].Meta = struct{}{}
+	n, err := t.read(mem)
+	if err != nil {
+		return 0, err
+	}
+	p[0].Bytes = mem[:n]
+	return 1, nil
+}
+
+func (t *TestTun) read(b []byte) (int, error) {
 	p, ok := <-t.rxPackets
 	if !ok {
 		return 0, os.ErrClosed
 	}
+	n := len(p)
 	copy(b, p)
-	return len(p), nil
+	// Send always pushes a freelist-acquired slice, return it once we've copied the bytes into the caller's buffer.
+	select {
+	case tunBufFreelist <- p:
+	default:
+	}
+	return n, nil
+}
+
+func (t *TestTun) Readers() []tio.Queue {
+	return []tio.Queue{t}
+}
+
+func (t *TestTun) Capabilities() tio.Capabilities {
+	return tio.Capabilities{}
 }
 
 func (t *TestTun) SupportsMultiqueue() bool {
 	return false
 }
 
-func (t *TestTun) NewMultiQueueReader() (io.ReadWriteCloser, error) {
-	return nil, fmt.Errorf("TODO: multiqueue not implemented")
+func (t *TestTun) NewMultiQueueReader() error {
+	return fmt.Errorf("TODO: multiqueue not implemented")
 }

overlay/tun_windows.go

@@ -6,7 +6,6 @@ package overlay
 import (
 	"crypto"
 	"fmt"
-	"io"
 	"log/slog"
 	"net/netip"
 	"os"
@@ -18,26 +17,50 @@ import (
 
 	"github.com/gaissmai/bart"
 	"github.com/slackhq/nebula/config"
+	"github.com/slackhq/nebula/overlay/tio"
 	"github.com/slackhq/nebula/routing"
 	"github.com/slackhq/nebula/util"
 	"github.com/slackhq/nebula/wintun"
+	"github.com/slackhq/nebula/wire"
 	"golang.org/x/sys/windows"
 	"golang.zx2c4.com/wireguard/windows/tunnel/winipcfg"
 )
 
+type closer interface {
+	Close()
+}
+
 const tunGUIDLabel = "Fixed Nebula Windows GUID v1"
 
 type winTun struct {
-	Device      string
-	vpnNetworks []netip.Prefix
-	MTU         int
-	Routes      atomic.Pointer[[]Route]
-	routeTree   atomic.Pointer[bart.Table[routing.Gateways]]
-	l           *slog.Logger
+	Device          string
+	vpnNetworks     []netip.Prefix
+	MTU             int
+	Routes          atomic.Pointer[[]Route]
+	routeTree       atomic.Pointer[bart.Table[routing.Gateways]]
+	guid            windows.GUID
+	networkCategory networkCategory
+	setCategory     bool
+	bypassWDF       bool
+	wdfBypass       closer
+	l               *slog.Logger
 
 	tun *wintun.NativeTun
 }
 
+func (t *winTun) Read(p []wire.TunPacket, mem []byte) (int, error) {
+	if len(p) == 0 || len(mem) == 0 {
+		return 0, nil //todo should this be an err?
+	}
+	p[0].Meta = struct{}{}
+	n, err := t.tun.Read(mem, 0)
+	if err != nil {
+		return 0, err
+	}
+	p[0].Bytes = mem[:n]
+	return 1, nil
+}
+
 func newTunFromFd(_ *config.C, _ *slog.Logger, _ int, _ []netip.Prefix) (Device, error) {
 	return nil, fmt.Errorf("newTunFromFd not supported in Windows")
 }
@@ -54,11 +77,20 @@ func newTun(c *config.C, l *slog.Logger, vpnNetworks []netip.Prefix, _ bool) (*w
 		return nil, fmt.Errorf("generate GUID failed: %w", err)
 	}
 
+	cat, setCat, err := parseNetworkCategory(c.GetString("tun.network_category", "private"))
+	if err != nil {
+		return nil, err
+	}
+
 	t := &winTun{
-		Device:      deviceName,
-		vpnNetworks: vpnNetworks,
-		MTU:         c.GetInt("tun.mtu", DefaultMTU),
-		l:           l,
+		Device:          deviceName,
+		vpnNetworks:     vpnNetworks,
+		MTU:             c.GetInt("tun.mtu", DefaultMTU),
+		guid:            *guid,
+		networkCategory: cat,
+		setCategory:     setCat,
+		bypassWDF:       c.GetBool("tun.windows_bypass_wdf", true),
+		l:               l,
 	}
 
 	err = t.reload(c, true)
@@ -142,6 +174,17 @@ func (t *winTun) Activate() error {
 		return err
 	}
 
+	if t.setCategory {
+		// The wintun adapter takes a moment to register with the Network List
+		// Manager, so we apply the category in the background and retry until
+		// it shows up.
+		go applyNetworkCategory(t.l, t.guid, t.networkCategory)
+	}
+
+	if t.bypassWDF {
+		t.wdfBypass = installInterfaceBypass(t.l, uint64(t.tun.LUID()))
+	}
+
 	return nil
 }
 
@@ -156,11 +199,8 @@ func (t *winTun) addRoutes(logErrors bool) error {
 			continue
 		}
 
-		// Add our unsafe route
-		// Windows does not support multipath routes natively, so we install only a single route.
-		// This is not a problem as traffic will always be sent to Nebula which handles the multipath routing internally.
-		// In effect this provides multipath routing support to windows supporting loadbalancing and redundancy.
-		err := luid.AddRoute(r.Cidr, r.Via[0].Addr(), uint32(r.Metric))
+		// Add our unsafe route as an on-link route to the nebula tun device.
+		err := luid.AddRoute(r.Cidr, unspecifiedNextHop(r.Cidr), uint32(r.Metric))
 		if err != nil {
 			retErr := util.NewContextualError("Failed to add route", map[string]any{"route": r}, err)
 			if logErrors {
@@ -206,7 +246,7 @@ func (t *winTun) removeRoutes(routes []Route) error {
 		}
 
 		// See comment on luid.AddRoute
-		err := luid.DeleteRoute(r.Cidr, r.Via[0].Addr())
+		err := luid.DeleteRoute(r.Cidr, unspecifiedNextHop(r.Cidr))
 		if err != nil {
 			t.l.Error("Failed to remove route", "error", err, "route", r)
 		} else {
@@ -229,10 +269,6 @@ func (t *winTun) Name() string {
 	return t.Device
 }
 
-func (t *winTun) Read(b []byte) (int, error) {
-	return t.tun.Read(b, 0)
-}
-
 func (t *winTun) Write(b []byte) (int, error) {
 	return t.tun.Write(b, 0)
 }
@@ -241,8 +277,16 @@ func (t *winTun) SupportsMultiqueue() bool {
 	return false
 }
 
-func (t *winTun) NewMultiQueueReader() (io.ReadWriteCloser, error) {
-	return nil, fmt.Errorf("TODO: multiqueue not implemented for windows")
+func (t *winTun) NewMultiQueueReader() error {
+	return fmt.Errorf("TODO: multiqueue not implemented for windows")
+}
+
+func (t *winTun) Readers() []tio.Queue {
+	return []tio.Queue{t}
+}
+
+func (t *winTun) Capabilities() tio.Capabilities {
+	return tio.Capabilities{}
 }
 
 func (t *winTun) Close() error {
@@ -258,9 +302,21 @@ func (t *winTun) Close() error {
 	_ = luid.FlushDNS(windows.AF_INET)
 	_ = luid.FlushDNS(windows.AF_INET6)
 
+	if t.wdfBypass != nil {
+		t.wdfBypass.Close()
+		t.wdfBypass = nil
+	}
+
 	return t.tun.Close()
 }
 
+func unspecifiedNextHop(p netip.Prefix) netip.Addr {
+	if p.Addr().Is4() {
+		return netip.IPv4Unspecified()
+	}
+	return netip.IPv6Unspecified()
+}
+
 func generateGUIDByDeviceName(name string) (*windows.GUID, error) {
 	// GUID is 128 bit
 	hash := crypto.MD5.New()

overlay/user.go

@@ -6,7 +6,9 @@ import (
 	"net/netip"
 
 	"github.com/slackhq/nebula/config"
+	"github.com/slackhq/nebula/overlay/tio"
 	"github.com/slackhq/nebula/routing"
+	"github.com/slackhq/nebula/wire"
 )
 
 func NewUserDeviceFromConfig(c *config.C, l *slog.Logger, vpnNetworks []netip.Prefix, routines int) (Device, error) {
@@ -23,11 +25,13 @@ func NewUserDevice(vpnNetworks []netip.Prefix) (Device, error) {
 		outboundWriter: ow,
 		inboundReader:  ir,
 		inboundWriter:  iw,
+		numReaders:     1,
 	}, nil
 }
 
 type UserDevice struct {
 	vpnNetworks []netip.Prefix
+	numReaders  int
 
 	outboundReader *io.PipeReader
 	outboundWriter *io.PipeWriter
@@ -36,6 +40,23 @@ type UserDevice struct {
 	inboundWriter *io.PipeWriter
 }
 
+func (d *UserDevice) Capabilities() tio.Capabilities {
+	return tio.Capabilities{}
+}
+
+func (d *UserDevice) Read(p []wire.TunPacket, mem []byte) (int, error) {
+	if len(p) == 0 || len(mem) == 0 {
+		return 0, nil //todo should this be an err?
+	}
+	p[0].Meta = struct{}{}
+	n, err := d.outboundReader.Read(mem)
+	if err != nil {
+		return 0, err
+	}
+	p[0].Bytes = mem[:n]
+	return 1, nil
+}
+
 func (d *UserDevice) Activate() error {
 	return nil
 }
@@ -50,20 +71,27 @@ func (d *UserDevice) SupportsMultiqueue() bool {
 	return true
 }
 
-func (d *UserDevice) NewMultiQueueReader() (io.ReadWriteCloser, error) {
-	return d, nil
+func (d *UserDevice) NewMultiQueueReader() error {
+	d.numReaders++
+	return nil
+}
+
+func (d *UserDevice) Readers() []tio.Queue {
+	out := make([]tio.Queue, d.numReaders)
+	for i := range d.numReaders {
+		out[i] = d
+	}
+	return out
 }
 
 func (d *UserDevice) Pipe() (*io.PipeReader, *io.PipeWriter) {
 	return d.inboundReader, d.outboundWriter
 }
 
-func (d *UserDevice) Read(p []byte) (n int, err error) {
-	return d.outboundReader.Read(p)
-}
 func (d *UserDevice) Write(p []byte) (n int, err error) {
 	return d.inboundWriter.Write(p)
 }
+
 func (d *UserDevice) Close() error {
 	d.inboundWriter.Close()
 	d.outboundWriter.Close()

pki.go

@@ -15,9 +15,12 @@ import (
 	"sync/atomic"
 	"time"
 
+	"github.com/flynn/noise"
 	"github.com/gaissmai/bart"
 	"github.com/slackhq/nebula/cert"
 	"github.com/slackhq/nebula/config"
+	"github.com/slackhq/nebula/handshake"
+	"github.com/slackhq/nebula/noiseutil"
 	"github.com/slackhq/nebula/util"
 )
 
@@ -28,11 +31,11 @@ type PKI struct {
 }
 
 type CertState struct {
-	v1Cert           cert.Certificate
-	v1HandshakeBytes []byte
+	v1Cert       cert.Certificate
+	v1Credential *handshake.Credential
 
-	v2Cert           cert.Certificate
-	v2HandshakeBytes []byte
+	v2Cert       cert.Certificate
+	v2Credential *handshake.Credential
 
 	initiatingVersion cert.Version
 	privateKey        []byte
@@ -92,13 +95,33 @@ func (p *PKI) reload(c *config.C, initial bool) error {
 }
 
 func (p *PKI) reloadCerts(c *config.C, initial bool) *util.ContextualError {
-	newState, err := newCertStateFromConfig(c)
+	var cipher string
+	var currentState *CertState
+	if initial {
+		cipher = c.GetString("cipher", "aes")
+		switch cipher {
+		case "aes", "chachapoly":
+			// Each post-handshake CipherState in noiseutil hardcodes its own
+			// nonce endianness now, so there's nothing to set up here.
+		default:
+			return util.NewContextualError(
+				"unknown cipher",
+				m{"cipher": cipher},
+				nil,
+			)
+		}
+	} else {
+		// Cipher cant be hot swapped so just leave it at what it was before
+		currentState = p.cs.Load()
+		cipher = currentState.cipher
+	}
+
+	newState, err := newCertStateFromConfig(c, cipher)
 	if err != nil {
 		return util.NewContextualError("Could not load client cert", nil, err)
 	}
 
-	if !initial {
-		currentState := p.cs.Load()
+	if currentState != nil {
 		if newState.v1Cert != nil {
 			if currentState.v1Cert == nil {
 				//adding certs is fine, actually. Networks-in-common confirmed in newCertState().
@@ -158,25 +181,6 @@ func (p *PKI) reloadCerts(c *config.C, initial bool) *util.ContextualError {
 				)
 			}
 		}
-
-		// Cipher cant be hot swapped so just leave it at what it was before
-		newState.cipher = currentState.cipher
-
-	} else {
-		newState.cipher = c.GetString("cipher", "aes")
-		//TODO: this sucks and we should make it not a global
-		switch newState.cipher {
-		case "aes":
-			noiseEndianness = binary.BigEndian
-		case "chachapoly":
-			noiseEndianness = binary.LittleEndian
-		default:
-			return util.NewContextualError(
-				"unknown cipher",
-				m{"cipher": newState.cipher},
-				nil,
-			)
-		}
 	}
 
 	p.cs.Store(newState)
@@ -208,6 +212,20 @@ func (cs *CertState) GetDefaultCertificate() cert.Certificate {
 	return c
 }
 
+// DefaultVersion returns the preferred cert version for initiating handshakes.
+func (cs *CertState) DefaultVersion() cert.Version { return cs.initiatingVersion }
+
+// GetCredential returns the pre-computed handshake credential for the given version, or nil.
+func (cs *CertState) GetCredential(v cert.Version) *handshake.Credential {
+	switch v {
+	case cert.Version1:
+		return cs.v1Credential
+	case cert.Version2:
+		return cs.v2Credential
+	}
+	return nil
+}
+
 func (cs *CertState) getCertificate(v cert.Version) cert.Certificate {
 	switch v {
 	case cert.Version1:
@@ -219,17 +237,25 @@ func (cs *CertState) getCertificate(v cert.Version) cert.Certificate {
 	return nil
 }
 
-// getHandshakeBytes returns the cached bytes to be used in a handshake message for the requested version.
-// Callers must check if the return []byte is nil.
-func (cs *CertState) getHandshakeBytes(v cert.Version) []byte {
-	switch v {
-	case cert.Version1:
-		return cs.v1HandshakeBytes
-	case cert.Version2:
-		return cs.v2HandshakeBytes
+func newCipherSuite(curve cert.Curve, pkcs11backed bool, cipher string) (noise.CipherSuite, error) {
+	var dhFunc noise.DHFunc
+	switch curve {
+	case cert.Curve_CURVE25519:
+		dhFunc = noise.DH25519
+	case cert.Curve_P256:
+		if pkcs11backed {
+			dhFunc = noiseutil.DHP256PKCS11
+		} else {
+			dhFunc = noiseutil.DHP256
+		}
 	default:
-		return nil
+		return nil, fmt.Errorf("unsupported curve: %s", curve)
 	}
+
+	if cipher == "chachapoly" {
+		return noise.NewCipherSuite(dhFunc, noise.CipherChaChaPoly, noise.HashSHA256), nil
+	}
+	return noise.NewCipherSuite(dhFunc, noiseutil.CipherAESGCM, noise.HashSHA256), nil
 }
 
 func (cs *CertState) String() string {
@@ -261,7 +287,7 @@ func (cs *CertState) MarshalJSON() ([]byte, error) {
 	return json.Marshal(msg)
 }
 
-func newCertStateFromConfig(c *config.C) (*CertState, error) {
+func newCertStateFromConfig(c *config.C, cipher string) (*CertState, error) {
 	var err error
 
 	privPathOrPEM := c.GetString("pki.key", "")
@@ -345,13 +371,14 @@ func newCertStateFromConfig(c *config.C) (*CertState, error) {
 		return nil, fmt.Errorf("unknown pki.initiating_version: %v", rawInitiatingVersion)
 	}
 
-	return newCertState(initiatingVersion, v1, v2, isPkcs11, curve, rawKey)
+	return newCertState(initiatingVersion, v1, v2, isPkcs11, curve, rawKey, cipher)
 }
 
-func newCertState(dv cert.Version, v1, v2 cert.Certificate, pkcs11backed bool, privateKeyCurve cert.Curve, privateKey []byte) (*CertState, error) {
+func newCertState(dv cert.Version, v1, v2 cert.Certificate, pkcs11backed bool, privateKeyCurve cert.Curve, privateKey []byte, cipher string) (*CertState, error) {
 	cs := CertState{
 		privateKey:               privateKey,
 		pkcs11Backed:             pkcs11backed,
+		cipher:                   cipher,
 		myVpnNetworksTable:       new(bart.Lite),
 		myVpnAddrsTable:          new(bart.Lite),
 		myVpnBroadcastAddrsTable: new(bart.Lite),
@@ -384,10 +411,14 @@ func newCertState(dv cert.Version, v1, v2 cert.Certificate, pkcs11backed bool, p
 
 		v1hs, err := v1.MarshalForHandshakes()
 		if err != nil {
-			return nil, fmt.Errorf("error marshalling certificate for handshake: %w", err)
+			return nil, fmt.Errorf("error marshalling v1 certificate for handshake: %w", err)
+		}
+		ncs, err := newCipherSuite(v1.Curve(), pkcs11backed, cipher)
+		if err != nil {
+			return nil, err
 		}
 		cs.v1Cert = v1
-		cs.v1HandshakeBytes = v1hs
+		cs.v1Credential = handshake.NewCredential(v1, v1hs, privateKey, ncs)
 
 		if cs.initiatingVersion == 0 {
 			cs.initiatingVersion = cert.Version1
@@ -405,10 +436,14 @@ func newCertState(dv cert.Version, v1, v2 cert.Certificate, pkcs11backed bool, p
 
 		v2hs, err := v2.MarshalForHandshakes()
 		if err != nil {
-			return nil, fmt.Errorf("error marshalling certificate for handshake: %w", err)
+			return nil, fmt.Errorf("error marshalling v2 certificate for handshake: %w", err)
+		}
+		ncs, err := newCipherSuite(v2.Curve(), pkcs11backed, cipher)
+		if err != nil {
+			return nil, err
 		}
 		cs.v2Cert = v2
-		cs.v2HandshakeBytes = v2hs
+		cs.v2Credential = handshake.NewCredential(v2, v2hs, privateKey, ncs)
 
 		if cs.initiatingVersion == 0 {
 			cs.initiatingVersion = cert.Version2

punchy.go

@@ -1,24 +1,70 @@
 package nebula
 
 import (
+	"context"
 	"log/slog"
+	"net/netip"
 	"sync/atomic"
 	"time"
 
+	"github.com/rcrowley/go-metrics"
 	"github.com/slackhq/nebula/config"
+	"github.com/slackhq/nebula/header"
+	"github.com/slackhq/nebula/udp"
 )
 
+// holepunchQueueSize buffers the channel that pending holepunchJobs land on after their delay timer fires.
+const holepunchQueueSize = 64
+
+// holepunchJob is one scheduled item delivered to the worker goroutine.
+//   - target valid -> send a UDP punch to target. vpnAddr, if set, is the peer's vpn addr carried for log context.
+//   - target invalid, vpnAddr valid -> send an encrypted test packet to vpnAddr (a "punchback").
+type holepunchJob struct {
+	target  netip.AddrPort
+	vpnAddr netip.Addr
+}
+
+// lighthouseChecker is the slice of LightHouse that Punchy actually needs.
+// Defined here so Punchy doesn't take a *LightHouse dependency (LightHouse
+// already holds a *Punchy, and the bidirectional pointer reference is awkward
+// even within the same package). Tests can also substitute a fake.
+type lighthouseChecker interface {
+	IsAnyLighthouseAddr(vpnAddrs []netip.Addr) bool
+}
+
 type Punchy struct {
 	punch           atomic.Bool
 	respond         atomic.Bool
 	delay           atomic.Int64
 	respondDelay    atomic.Int64
 	punchEverything atomic.Bool
-	l               *slog.Logger
+
+	sched             *Scheduler[holepunchJob]
+	punchConn         udp.Conn
+	metricHolepunchTx metrics.Counter
+	metricPunchyTx    metrics.Counter
+
+	ctx  context.Context
+	ifce EncWriter
+	hm   *HostMap
+	lh   lighthouseChecker
+
+	l *slog.Logger
 }
 
-func NewPunchyFromConfig(l *slog.Logger, c *config.C) *Punchy {
-	p := &Punchy{l: l}
+func NewPunchyFromConfig(l *slog.Logger, c *config.C, punchConn udp.Conn) *Punchy {
+	p := &Punchy{
+		l:              l,
+		punchConn:      punchConn,
+		sched:          NewScheduler[holepunchJob](holepunchQueueSize),
+		metricPunchyTx: metrics.GetOrRegisterCounter("messages.tx.punchy", nil),
+	}
+
+	if c.GetBool("stats.lighthouse_metrics", false) {
+		p.metricHolepunchTx = metrics.GetOrRegisterCounter("messages.tx.holepunch", nil)
+	} else {
+		p.metricHolepunchTx = metrics.NilCounter{}
+	}
 
 	p.reload(c, true)
 	c.RegisterReloadCallback(func(c *config.C) {
@@ -29,7 +75,7 @@ func NewPunchyFromConfig(l *slog.Logger, c *config.C) *Punchy {
 }
 
 func (p *Punchy) reload(c *config.C, initial bool) {
-	if initial {
+	if initial || c.HasChanged("punchy.punch") || c.HasChanged("punchy") {
 		var yes bool
 		if c.IsSet("punchy.punch") {
 			yes = c.GetBool("punchy.punch", false)
@@ -38,16 +84,15 @@ func (p *Punchy) reload(c *config.C, initial bool) {
 			yes = c.GetBool("punchy", false)
 		}
 
-		p.punch.Store(yes)
-		if yes {
+		old := p.punch.Swap(yes)
+		switch {
+		case initial && yes:
 			p.l.Info("punchy enabled")
-		} else {
+		case initial:
 			p.l.Info("punchy disabled")
+		case old != yes:
+			p.l.Info("punchy.punch changed", "punch", yes)
 		}
-
-	} else if c.HasChanged("punchy.punch") || c.HasChanged("punchy") {
-		//TODO: it should be relatively easy to support this, just need to be able to cancel the goroutine and boot it up from here
-		p.l.Warn("Changing punchy.punch with reload is not supported, ignoring.")
 	}
 
 	if initial || c.HasChanged("punchy.respond") || c.HasChanged("punch_back") {
@@ -59,52 +104,132 @@ func (p *Punchy) reload(c *config.C, initial bool) {
 			yes = c.GetBool("punch_back", false)
 		}
 
-		p.respond.Store(yes)
-
-		if !initial {
-			p.l.Info("punchy.respond changed", "respond", p.GetRespond())
+		old := p.respond.Swap(yes)
+		if !initial && old != yes {
+			p.l.Info("punchy.respond changed", "respond", yes)
 		}
 	}
 
 	//NOTE: this will not apply to any in progress operations, only the next one
 	if initial || c.HasChanged("punchy.delay") {
-		p.delay.Store((int64)(c.GetDuration("punchy.delay", time.Second)))
-		if !initial {
-			p.l.Info("punchy.delay changed", "delay", p.GetDelay())
+		newDelay := int64(c.GetDuration("punchy.delay", time.Second))
+		old := p.delay.Swap(newDelay)
+		if !initial && old != newDelay {
+			p.l.Info("punchy.delay changed", "delay", time.Duration(newDelay))
 		}
 	}
 
 	if initial || c.HasChanged("punchy.target_all_remotes") {
-		p.punchEverything.Store(c.GetBool("punchy.target_all_remotes", false))
-		if !initial {
-			p.l.Info("punchy.target_all_remotes changed", "target_all_remotes", p.GetTargetEverything())
+		yes := c.GetBool("punchy.target_all_remotes", false)
+		old := p.punchEverything.Swap(yes)
+		if !initial && old != yes {
+			p.l.Info("punchy.target_all_remotes changed", "target_all_remotes", yes)
 		}
 	}
 
 	if initial || c.HasChanged("punchy.respond_delay") {
-		p.respondDelay.Store((int64)(c.GetDuration("punchy.respond_delay", 5*time.Second)))
-		if !initial {
-			p.l.Info("punchy.respond_delay changed", "respond_delay", p.GetRespondDelay())
+		newDelay := int64(c.GetDuration("punchy.respond_delay", 5*time.Second))
+		old := p.respondDelay.Swap(newDelay)
+		if !initial && old != newDelay {
+			p.l.Info("punchy.respond_delay changed", "respond_delay", time.Duration(newDelay))
 		}
 	}
 }
 
-func (p *Punchy) GetPunch() bool {
-	return p.punch.Load()
+// Schedule queues a punch packet to target, to be sent after the configured delay.
+// vpnAddr is the peer's vpn addr, used for log context when the packet actually fires.
+// No-op if target is not a valid AddrPort or if Start has not yet been called. Safe to call from any goroutine.
+func (p *Punchy) Schedule(target netip.AddrPort, vpnAddr netip.Addr) {
+	if !target.IsValid() || p.ctx == nil {
+		return
+	}
+	p.scheduleJob(holepunchJob{target: target, vpnAddr: vpnAddr}, time.Duration(p.delay.Load()))
 }
 
-func (p *Punchy) GetRespond() bool {
-	return p.respond.Load()
+// ScheduleRespond queues a punchback test packet to vpnAddr after the configured respond delay,
+// gated on punchy.respond. No-op when respond is disabled or before Start has been called.
+func (p *Punchy) ScheduleRespond(vpnAddr netip.Addr) {
+	if !p.respond.Load() || p.ctx == nil {
+		return
+	}
+	p.scheduleJob(holepunchJob{vpnAddr: vpnAddr}, time.Duration(p.respondDelay.Load()))
 }
 
-func (p *Punchy) GetDelay() time.Duration {
-	return (time.Duration)(p.delay.Load())
+// scheduleJob delegates to the pooled Scheduler.
+// The callback observes p.ctx so a job that becomes due after Stop is dropped instead of queued.
+func (p *Punchy) scheduleJob(job holepunchJob, delay time.Duration) {
+	p.sched.Schedule(p.ctx, job, delay)
 }
 
-func (p *Punchy) GetRespondDelay() time.Duration {
-	return (time.Duration)(p.respondDelay.Load())
+// SendPunch sends an immediate keepalive punch for an idle hostinfo.
+// The configured punchy.target_all_remotes mode picks the targets. Gated on punchy.punch and the lighthouse-skip rule
+// (lighthouses don't get keepalive punches because the regular update interval keeps their NAT state warm).
+func (p *Punchy) SendPunch(hostinfo *HostInfo) {
+	if !p.punch.Load() {
+		return
+	}
+	if p.lh.IsAnyLighthouseAddr(hostinfo.vpnAddrs) {
+		return
+	}
+
+	if p.punchEverything.Load() {
+		p.sendPunchToAllRemotes(hostinfo)
+	} else if hostinfo.remote.IsValid() {
+		p.metricPunchyTx.Inc(1)
+		p.punchConn.WriteTo([]byte{1}, hostinfo.remote)
+	}
 }
 
-func (p *Punchy) GetTargetEverything() bool {
-	return p.punchEverything.Load()
+// SendPunchToAll punches every known remote for hostinfo, but only when punchy.target_all_remotes is enabled.
+// The connection manager calls this during outbound-only traffic: the outbound traffic itself keeps the primary's
+// NAT state warm, but non-primary remotes need separate refresh, so we fan out to all of them (the redundant
+// primary punch is harmless). Gated on punchy.punch and the lighthouse-skip rule.
+func (p *Punchy) SendPunchToAll(hostinfo *HostInfo) {
+	if !p.punchEverything.Load() {
+		return
+	}
+	if !p.punch.Load() {
+		return
+	}
+	if p.lh.IsAnyLighthouseAddr(hostinfo.vpnAddrs) {
+		return
+	}
+	p.sendPunchToAllRemotes(hostinfo)
+}
+
+func (p *Punchy) sendPunchToAllRemotes(hostinfo *HostInfo) {
+	hostinfo.remotes.ForEach(p.hm.GetPreferredRanges(), func(addr netip.AddrPort, preferred bool) {
+		p.metricPunchyTx.Inc(1)
+		p.punchConn.WriteTo([]byte{1}, addr)
+	})
+}
+
+// Start wires the runtime dependencies and spawns the scheduler worker.
+func (p *Punchy) Start(ctx context.Context, ifce EncWriter, hm *HostMap, lh lighthouseChecker) {
+	p.ctx = ctx
+	p.ifce = ifce
+	p.hm = hm
+	p.lh = lh
+
+	nb := make([]byte, 12, 12)
+	out := make([]byte, mtu)
+	empty := []byte{0}
+
+	go p.sched.Run(ctx, func(job holepunchJob) {
+		switch {
+		case job.target.IsValid():
+			if p.l.Enabled(context.Background(), slog.LevelDebug) {
+				p.l.Debug("Punching", "target", job.target, "vpnAddr", job.vpnAddr)
+			}
+			p.metricHolepunchTx.Inc(1)
+			p.punchConn.WriteTo(empty, job.target)
+		case job.vpnAddr.IsValid():
+			// A nebula test packet to the host trying to contact us.
+			// In the case of a double nat or other difficult scenario, this may help establish a tunnel.
+			if p.l.Enabled(context.Background(), slog.LevelDebug) {
+				p.l.Debug("Sending a nebula test packet", "vpnAddr", job.vpnAddr)
+			}
+			p.ifce.SendMessageToVpnAddr(header.Test, header.TestRequest, job.vpnAddr, []byte(""), nb, out)
+		}
+	})
 }

punchy_test.go

@@ -17,42 +17,42 @@ func TestNewPunchyFromConfig(t *testing.T) {
 	c := config.NewC(l)
 
 	// Test defaults
-	p := NewPunchyFromConfig(test.NewLogger(), c)
-	assert.False(t, p.GetPunch())
-	assert.False(t, p.GetRespond())
-	assert.Equal(t, time.Second, p.GetDelay())
-	assert.Equal(t, 5*time.Second, p.GetRespondDelay())
+	p := NewPunchyFromConfig(test.NewLogger(), c, nil)
+	assert.False(t, p.punch.Load())
+	assert.False(t, p.respond.Load())
+	assert.Equal(t, time.Second, time.Duration(p.delay.Load()))
+	assert.Equal(t, 5*time.Second, time.Duration(p.respondDelay.Load()))
 
 	// punchy deprecation
 	c.Settings["punchy"] = true
-	p = NewPunchyFromConfig(test.NewLogger(), c)
-	assert.True(t, p.GetPunch())
+	p = NewPunchyFromConfig(test.NewLogger(), c, nil)
+	assert.True(t, p.punch.Load())
 
 	// punchy.punch
 	c.Settings["punchy"] = map[string]any{"punch": true}
-	p = NewPunchyFromConfig(test.NewLogger(), c)
-	assert.True(t, p.GetPunch())
+	p = NewPunchyFromConfig(test.NewLogger(), c, nil)
+	assert.True(t, p.punch.Load())
 
 	// punch_back deprecation
 	c.Settings["punch_back"] = true
-	p = NewPunchyFromConfig(test.NewLogger(), c)
-	assert.True(t, p.GetRespond())
+	p = NewPunchyFromConfig(test.NewLogger(), c, nil)
+	assert.True(t, p.respond.Load())
 
 	// punchy.respond
 	c.Settings["punchy"] = map[string]any{"respond": true}
 	c.Settings["punch_back"] = false
-	p = NewPunchyFromConfig(test.NewLogger(), c)
-	assert.True(t, p.GetRespond())
+	p = NewPunchyFromConfig(test.NewLogger(), c, nil)
+	assert.True(t, p.respond.Load())
 
 	// punchy.delay
 	c.Settings["punchy"] = map[string]any{"delay": "1m"}
-	p = NewPunchyFromConfig(test.NewLogger(), c)
-	assert.Equal(t, time.Minute, p.GetDelay())
+	p = NewPunchyFromConfig(test.NewLogger(), c, nil)
+	assert.Equal(t, time.Minute, time.Duration(p.delay.Load()))
 
 	// punchy.respond_delay
 	c.Settings["punchy"] = map[string]any{"respond_delay": "1m"}
-	p = NewPunchyFromConfig(test.NewLogger(), c)
-	assert.Equal(t, time.Minute, p.GetRespondDelay())
+	p = NewPunchyFromConfig(test.NewLogger(), c, nil)
+	assert.Equal(t, time.Minute, time.Duration(p.respondDelay.Load()))
 }
 
 func TestPunchy_reload(t *testing.T) {
@@ -61,35 +61,34 @@ func TestPunchy_reload(t *testing.T) {
 	delay, _ := time.ParseDuration("1m")
 	require.NoError(t, c.LoadString(`
 punchy:
+  punch: false
   delay: 1m
   respond: false
 `))
-	p := NewPunchyFromConfig(test.NewLogger(), c)
-	assert.Equal(t, delay, p.GetDelay())
-	assert.False(t, p.GetRespond())
+	p := NewPunchyFromConfig(test.NewLogger(), c, nil)
+	assert.False(t, p.punch.Load())
+	assert.Equal(t, delay, time.Duration(p.delay.Load()))
+	assert.False(t, p.respond.Load())
 
 	newDelay, _ := time.ParseDuration("10m")
 	require.NoError(t, c.ReloadConfigString(`
 punchy:
+  punch: true
   delay: 10m
   respond: true
 `))
 	p.reload(c, false)
-	assert.Equal(t, newDelay, p.GetDelay())
-	assert.True(t, p.GetRespond())
+	assert.True(t, p.punch.Load())
+	assert.Equal(t, newDelay, time.Duration(p.delay.Load()))
+	assert.True(t, p.respond.Load())
 }
 
 // The tests below pin the shape of each log line Punchy produces so changes
 // cannot silently break whatever operators are grepping for. The assertions
 // are on the structured message + attrs (e.g. "punchy.respond changed" with
-// a respond=true field) rather than a formatted string.
-//
-// Punchy.reload also emits a spurious "Changing punchy.punch with reload is
-// not supported" warning whenever any key under punchy changes, because of
-// the c.HasChanged("punchy") fallback kept for the deprecated top-level
-// punchy form. The tests filter by message rather than asserting total
-// entry counts so that warning is tolerated without being locked into
-// the format.
+// a respond=true field) rather than a formatted string. Tests filter by
+// message rather than asserting total entry counts so unrelated info lines
+// are tolerated without being locked into the format.
 
 type capturedEntry struct {
 	Level slog.Level
@@ -145,7 +144,7 @@ func TestPunchy_LogFormat_InitialEnabled(t *testing.T) {
 	c := config.NewC(test.NewLogger())
 	require.NoError(t, c.LoadString(`punchy: {punch: true}`))
 
-	NewPunchyFromConfig(l, c)
+	NewPunchyFromConfig(l, c, nil)
 
 	entry := findEntry(t, hook.entries, "punchy enabled")
 	assert.Equal(t, slog.LevelInfo, entry.Level)
@@ -157,32 +156,32 @@ func TestPunchy_LogFormat_InitialDisabled(t *testing.T) {
 	c := config.NewC(test.NewLogger())
 	require.NoError(t, c.LoadString(`punchy: {punch: false}`))
 
-	NewPunchyFromConfig(l, c)
+	NewPunchyFromConfig(l, c, nil)
 
 	entry := findEntry(t, hook.entries, "punchy disabled")
 	assert.Equal(t, slog.LevelInfo, entry.Level)
 	assert.Empty(t, entry.Attrs)
 }
 
-func TestPunchy_LogFormat_ReloadPunchUnsupported(t *testing.T) {
+func TestPunchy_LogFormat_ReloadPunch(t *testing.T) {
 	l, hook := newCapturingPunchyLogger(t)
 	c := config.NewC(test.NewLogger())
 	require.NoError(t, c.LoadString(`punchy: {punch: false}`))
-	NewPunchyFromConfig(l, c)
+	NewPunchyFromConfig(l, c, nil)
 	hook.entries = nil
 
 	require.NoError(t, c.ReloadConfigString(`punchy: {punch: true}`))
 
-	entry := findEntry(t, hook.entries, "Changing punchy.punch with reload is not supported, ignoring.")
-	assert.Equal(t, slog.LevelWarn, entry.Level)
-	assert.Empty(t, entry.Attrs)
+	entry := findEntry(t, hook.entries, "punchy.punch changed")
+	assert.Equal(t, slog.LevelInfo, entry.Level)
+	assert.Equal(t, map[string]any{"punch": true}, entry.Attrs)
 }
 
 func TestPunchy_LogFormat_ReloadRespond(t *testing.T) {
 	l, hook := newCapturingPunchyLogger(t)
 	c := config.NewC(test.NewLogger())
 	require.NoError(t, c.LoadString(`punchy: {respond: false}`))
-	NewPunchyFromConfig(l, c)
+	NewPunchyFromConfig(l, c, nil)
 	hook.entries = nil
 
 	require.NoError(t, c.ReloadConfigString(`punchy: {respond: true}`))
@@ -196,7 +195,7 @@ func TestPunchy_LogFormat_ReloadDelay(t *testing.T) {
 	l, hook := newCapturingPunchyLogger(t)
 	c := config.NewC(test.NewLogger())
 	require.NoError(t, c.LoadString(`punchy: {delay: 1s}`))
-	NewPunchyFromConfig(l, c)
+	NewPunchyFromConfig(l, c, nil)
 	hook.entries = nil
 
 	require.NoError(t, c.ReloadConfigString(`punchy: {delay: 10s}`))
@@ -210,7 +209,7 @@ func TestPunchy_LogFormat_ReloadTargetAllRemotes(t *testing.T) {
 	l, hook := newCapturingPunchyLogger(t)
 	c := config.NewC(test.NewLogger())
 	require.NoError(t, c.LoadString(`punchy: {target_all_remotes: false}`))
-	NewPunchyFromConfig(l, c)
+	NewPunchyFromConfig(l, c, nil)
 	hook.entries = nil
 
 	require.NoError(t, c.ReloadConfigString(`punchy: {target_all_remotes: true}`))
@@ -224,7 +223,7 @@ func TestPunchy_LogFormat_ReloadRespondDelay(t *testing.T) {
 	l, hook := newCapturingPunchyLogger(t)
 	c := config.NewC(test.NewLogger())
 	require.NoError(t, c.LoadString(`punchy: {respond_delay: 5s}`))
-	NewPunchyFromConfig(l, c)
+	NewPunchyFromConfig(l, c, nil)
 	hook.entries = nil
 
 	require.NoError(t, c.ReloadConfigString(`punchy: {respond_delay: 15s}`))

relay_manager.go

@@ -15,9 +15,10 @@ import (
 )
 
 type relayManager struct {
-	l       *slog.Logger
-	hostmap *HostMap
-	amRelay atomic.Bool
+	l         *slog.Logger
+	hostmap   *HostMap
+	amRelay   atomic.Bool
+	useRelays atomic.Bool
 }
 
 func NewRelayManager(ctx context.Context, l *slog.Logger, hostmap *HostMap, c *config.C) *relayManager {
@@ -36,8 +37,10 @@ func NewRelayManager(ctx context.Context, l *slog.Logger, hostmap *HostMap, c *c
 }
 
 func (rm *relayManager) reload(c *config.C, initial bool) error {
-	if initial || c.HasChanged("relay.am_relay") {
-		rm.setAmRelay(c.GetBool("relay.am_relay", false))
+	if initial || c.HasChanged("relay.am_relay") || c.HasChanged("relay.use_relays") {
+		amRelay := c.GetBool("relay.am_relay", false)
+		rm.amRelay.Store(amRelay)
+		rm.useRelays.Store(c.GetBool("relay.use_relays", true) && !amRelay)
 	}
 	return nil
 }
@@ -46,8 +49,157 @@ func (rm *relayManager) GetAmRelay() bool {
 	return rm.amRelay.Load()
 }
 
-func (rm *relayManager) setAmRelay(v bool) {
-	rm.amRelay.Store(v)
+func (rm *relayManager) GetUseRelays() bool {
+	return rm.useRelays.Load()
+}
+
+// StartRelays drives the relay-establishment side of an outbound handshake attempt.
+// For each candidate relay it either kicks off a handshake to the relay, sends a CreateRelayRequest, retransmits
+// one that may have been lost, or, once the relay is Established, forwards the in-progress
+// stage 0 handshake packet for vpnIp through it.
+func (rm *relayManager) StartRelays(f *Interface, vpnIp netip.Addr, hostinfo *HostInfo, stage0 []byte) {
+	if !rm.GetUseRelays() || len(hostinfo.remotes.relays) == 0 {
+		return
+	}
+
+	hostinfo.logger(rm.l).Info("Attempt to relay through hosts", "relays", hostinfo.remotes.relays)
+	// Send a RelayRequest to all known Relay IP's
+	for _, relay := range hostinfo.remotes.relays {
+		// Don't relay through the host I'm trying to connect to
+		if relay == vpnIp {
+			continue
+		}
+
+		// Don't relay to myself
+		if f.myVpnAddrsTable.Contains(relay) {
+			continue
+		}
+
+		relayHostInfo := rm.hostmap.QueryVpnAddr(relay)
+		if relayHostInfo == nil || !relayHostInfo.remote.IsValid() {
+			hostinfo.logger(rm.l).Info("Establish tunnel to relay target", "relay", relay.String())
+			f.Handshake(relay)
+			continue
+		}
+		// Check the relay HostInfo to see if we already established a relay through
+		existingRelay, ok := relayHostInfo.relayState.QueryRelayForByIp(vpnIp)
+		if !ok {
+			// No relays exist or requested yet.
+			if relayHostInfo.remote.IsValid() {
+				idx, err := AddRelay(rm.l, relayHostInfo, rm.hostmap, vpnIp, nil, TerminalType, Requested)
+				if err != nil {
+					hostinfo.logger(rm.l).Info("Failed to add relay to hostmap", "relay", relay.String(), "error", err)
+				}
+
+				m := NebulaControl{
+					Type:                NebulaControl_CreateRelayRequest,
+					InitiatorRelayIndex: idx,
+				}
+
+				switch relayHostInfo.GetCert().Certificate.Version() {
+				case cert.Version1:
+					if !f.myVpnAddrs[0].Is4() {
+						hostinfo.logger(rm.l).Error("can not establish v1 relay with a v6 network because the relay is not running a current nebula version")
+						continue
+					}
+
+					if !vpnIp.Is4() {
+						hostinfo.logger(rm.l).Error("can not establish v1 relay with a v6 remote network because the relay is not running a current nebula version")
+						continue
+					}
+
+					b := f.myVpnAddrs[0].As4()
+					m.OldRelayFromAddr = binary.BigEndian.Uint32(b[:])
+					b = vpnIp.As4()
+					m.OldRelayToAddr = binary.BigEndian.Uint32(b[:])
+				case cert.Version2:
+					m.RelayFromAddr = netAddrToProtoAddr(f.myVpnAddrs[0])
+					m.RelayToAddr = netAddrToProtoAddr(vpnIp)
+				default:
+					hostinfo.logger(rm.l).Error("Unknown certificate version found while creating relay")
+					continue
+				}
+
+				msg, err := m.Marshal()
+				if err != nil {
+					hostinfo.logger(rm.l).Error("Failed to marshal Control message to create relay", "error", err)
+				} else {
+					f.SendMessageToHostInfo(header.Control, 0, relayHostInfo, msg, make([]byte, 12), make([]byte, mtu))
+					rm.l.Info("send CreateRelayRequest",
+						"relayFrom", f.myVpnAddrs[0],
+						"relayTo", vpnIp,
+						"initiatorRelayIndex", idx,
+						"relay", relay,
+					)
+				}
+			}
+			continue
+		}
+
+		switch existingRelay.State {
+		case Established:
+			hostinfo.logger(rm.l).Info("Send handshake via relay", "relay", relay.String())
+			f.SendVia(relayHostInfo, existingRelay, stage0, make([]byte, 12), make([]byte, mtu), false)
+		case Disestablished:
+			// Mark this relay as 'requested'
+			relayHostInfo.relayState.UpdateRelayForByIpState(vpnIp, Requested)
+			fallthrough
+		case Requested:
+			hostinfo.logger(rm.l).Info("Re-send CreateRelay request", "relay", relay.String())
+			// Re-send the CreateRelay request, in case the previous one was lost.
+			m := NebulaControl{
+				Type:                NebulaControl_CreateRelayRequest,
+				InitiatorRelayIndex: existingRelay.LocalIndex,
+			}
+
+			switch relayHostInfo.GetCert().Certificate.Version() {
+			case cert.Version1:
+				if !f.myVpnAddrs[0].Is4() {
+					hostinfo.logger(rm.l).Error("can not establish v1 relay with a v6 network because the relay is not running a current nebula version")
+					continue
+				}
+
+				if !vpnIp.Is4() {
+					hostinfo.logger(rm.l).Error("can not establish v1 relay with a v6 remote network because the relay is not running a current nebula version")
+					continue
+				}
+
+				b := f.myVpnAddrs[0].As4()
+				m.OldRelayFromAddr = binary.BigEndian.Uint32(b[:])
+				b = vpnIp.As4()
+				m.OldRelayToAddr = binary.BigEndian.Uint32(b[:])
+			case cert.Version2:
+				m.RelayFromAddr = netAddrToProtoAddr(f.myVpnAddrs[0])
+				m.RelayToAddr = netAddrToProtoAddr(vpnIp)
+			default:
+				hostinfo.logger(rm.l).Error("Unknown certificate version found while creating relay")
+				continue
+			}
+			msg, err := m.Marshal()
+			if err != nil {
+				hostinfo.logger(rm.l).Error("Failed to marshal Control message to create relay", "error", err)
+			} else {
+				// This must send over the hostinfo, not over hm.Hosts[ip]
+				f.SendMessageToHostInfo(header.Control, 0, relayHostInfo, msg, make([]byte, 12), make([]byte, mtu))
+				rm.l.Info("send CreateRelayRequest",
+					"relayFrom", f.myVpnAddrs[0],
+					"relayTo", vpnIp,
+					"initiatorRelayIndex", existingRelay.LocalIndex,
+					"relay", relay,
+				)
+			}
+		case PeerRequested:
+			// PeerRequested only occurs in Forwarding relays, not Terminal relays, and this is a Terminal relay case.
+			fallthrough
+		default:
+			hostinfo.logger(rm.l).Error("Relay unexpected state",
+				"vpnIp", vpnIp,
+				"state", existingRelay.State,
+				"relay", relay,
+			)
+
+		}
+	}
 }
 
 // AddRelay finds an available relay index on the hostmap, and associates the relay info with it.

scheduler.go

@@ -0,0 +1,84 @@
+package nebula
+
+import (
+	"context"
+	"sync"
+	"time"
+)
+
+// Scheduler is an allocation-conscious dispatch primitive for delayed work.
+// Pending items are handed to time.AfterFunc, and ready items land on a worker
+// channel for centralized dispatch in fire-time order.
+//
+// Pick a Scheduler when fire timing matters (exact deadlines, no bucketing) or when the scheduling
+// rate is uneven enough that idle CPU matters. Each fire is a runtime-spawned goroutine running the callback before
+// delivering to the worker, which is fine at sparse rates but adds up at line rate.
+//
+// Pick a TimerWheel when scheduling is high-rate and uniform: its O(1) insert, internal item cache,
+// and bucket-batched dispatch are cheaper at scale.
+// The caller drives the tick loop (Advance/Purge) and pays for fires at bucket boundaries rather than exact deadlines.
+type Scheduler[T any] struct {
+	queue chan T
+	pool  sync.Pool
+}
+
+type schedItem[T any] struct {
+	val   T
+	ctx   context.Context
+	s     *Scheduler[T]
+	timer *time.Timer
+	fire  func()
+}
+
+// NewScheduler builds a Scheduler whose worker channel is sized to queueSize.
+// The buffer absorbs bursts of timers firing close together without
+// blocking the runtime's callback goroutines on the worker.
+func NewScheduler[T any](queueSize int) *Scheduler[T] {
+	s := &Scheduler[T]{
+		queue: make(chan T, queueSize),
+	}
+	s.pool.New = func() any {
+		si := &schedItem[T]{s: s}
+		// fire is allocated exactly once per pool-resident item.
+		// The closure captures only `si`, which stays stable for the item's lifetime.
+		si.fire = func() {
+			select {
+			case si.s.queue <- si.val:
+			case <-si.ctx.Done():
+			}
+			var zero T
+			si.val = zero
+			si.ctx = nil
+			si.s.pool.Put(si)
+		}
+		return si
+	}
+	return s
+}
+
+// Schedule arranges item to be delivered to the worker after delay.
+// The runtime's timer heap handles the wait, so the scheduler itself burns no CPU while idle.
+// The callback observes ctx: if ctx is cancelled before the timer fires, the item is dropped instead of queued.
+func (s *Scheduler[T]) Schedule(ctx context.Context, item T, delay time.Duration) {
+	si := s.pool.Get().(*schedItem[T])
+	si.val = item
+	si.ctx = ctx
+	if si.timer == nil {
+		si.timer = time.AfterFunc(delay, si.fire)
+	} else {
+		si.timer.Reset(delay)
+	}
+}
+
+// Run drains the worker queue, calling fn for each item. Returns when ctx is cancelled.
+// Tests that want deterministic timing should drive the queue directly rather than going through Schedule + Run.
+func (s *Scheduler[T]) Run(ctx context.Context, fn func(T)) {
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case item := <-s.queue:
+			fn(item)
+		}
+	}
+}

scheduler_test.go

@@ -0,0 +1,79 @@
+package nebula
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func TestScheduler_PooledReuse(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	s := NewScheduler[int](16)
+	delivered := make(chan int, 256)
+	go s.Run(ctx, func(item int) { delivered <- item })
+
+	const N = 100
+	for i := 0; i < N; i++ {
+		s.Schedule(ctx, i, time.Millisecond)
+	}
+
+	deadline := time.After(2 * time.Second)
+	got := 0
+	for got < N {
+		select {
+		case <-delivered:
+			got++
+		case <-deadline:
+			t.Fatalf("only %d/%d items delivered", got, N)
+		}
+	}
+}
+
+// BenchmarkScheduler_Schedule reports allocations per Schedule call.
+// In steady state the Scheduler's sync.Pool means we should see zero allocs per op once the pool warms up.
+func BenchmarkScheduler_Schedule(b *testing.B) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	s := NewScheduler[int](b.N)
+	go s.Run(ctx, func(int) {})
+
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		s.Schedule(ctx, i, time.Microsecond)
+	}
+}
+
+// BenchmarkBareAfterFunc is the comparison baseline.
+// What we'd pay per Schedule if Punchy called time.AfterFunc directly without the pooled Scheduler.
+// Allocates a *time.Timer plus a closure each call.
+func BenchmarkBareAfterFunc(b *testing.B) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	queue := make(chan int, b.N)
+	go func() {
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-queue:
+			}
+		}
+	}()
+
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		i := i
+		time.AfterFunc(time.Microsecond, func() {
+			select {
+			case queue <- i:
+			case <-ctx.Done():
+			}
+		})
+	}
+}

sshd/server.go

@@ -27,21 +27,20 @@ type SSHServer struct {
 	commands    *radix.Tree
 	listener    net.Listener
 
-	// Call the cancel() function to stop all active sessions
-	ctx    context.Context
-	cancel func()
+	// ctx parents per-Run contexts. Cancelling it (e.g. via Control.Stop) tears the server down even
+	// across reloads, since each Run derives a fresh child rather than reusing this one directly.
+	ctx context.Context
 }
 
-// NewSSHServer creates a new ssh server rigged with default commands and prepares to listen
-func NewSSHServer(l *slog.Logger) (*SSHServer, error) {
-
-	ctx, cancel := context.WithCancel(context.Background())
+// NewSSHServer creates a new ssh server rigged with default commands and prepares to listen.
+// The ssh server's context is parented off the supplied ctx so cancelling it
+// (e.g. on Control.Stop) tears down active sessions and closes the listener.
+func NewSSHServer(ctx context.Context, l *slog.Logger) (*SSHServer, error) {
 	s := &SSHServer{
 		trustedKeys: make(map[string]map[string]bool),
 		l:           l,
 		commands:    radix.New(),
 		ctx:         ctx,
-		cancel:      cancel,
 	}
 
 	cc := ssh.CertChecker{
@@ -151,28 +150,51 @@ func (s *SSHServer) RegisterCommand(c *Command) {
 	s.commands.Insert(c.Name, c)
 }
 
-// Run begins listening and accepting connections
+// Run begins listening and accepting connections. Each invocation derives a fresh per-Run context
+// from the constructor-supplied ctx so a Stop+Run sequence (used by config reload) starts clean
+// rather than carrying a permanently-cancelled context across runs.
 func (s *SSHServer) Run(addr string) error {
-	var err error
-	s.listener, err = net.Listen("tcp", addr)
+	if s.ctx.Err() != nil {
+		return s.ctx.Err()
+	}
+
+	listener, err := net.Listen("tcp", addr)
 	if err != nil {
 		return err
 	}
+	// s.listener is the public handle Stop uses to interrupt the active run; listener (the local) is what
+	// this run owns. They start equal but a fast reload may overwrite s.listener with the next run's
+	// listener before this run's watcher fires, so each run must close its own listener via the local
+	// reference.
+	s.listener = listener
+
+	runCtx, cancel := context.WithCancel(s.ctx)
+	defer cancel()
+
+	// Close the listener when this run's context is cancelled. That can come from the parent
+	// (Control.Stop), from Run returning normally (defer cancel above), or transitively when a sibling
+	// run cancels through Stop closing the listener. net.Listener.Close is idempotent so a duplicate
+	// close from Stop is benign.
+	go func() {
+		<-runCtx.Done()
+		if err := listener.Close(); err != nil && !errors.Is(err, net.ErrClosed) {
+			s.l.Warn("Failed to close the sshd listener", "error", err)
+		}
+	}()
 
 	s.l.Info("SSH server is listening", "sshListener", addr)
 
 	// Run loops until there is an error
-	s.run()
-	s.closeSessions()
+	s.run(runCtx, listener)
 
 	s.l.Info("SSH server stopped listening")
 	// We don't return an error because run logs for us
 	return nil
 }
 
-func (s *SSHServer) run() {
+func (s *SSHServer) run(ctx context.Context, listener net.Listener) {
 	for {
-		c, err := s.listener.Accept()
+		c, err := listener.Accept()
 		if err != nil {
 			if !errors.Is(err, net.ErrClosed) {
 				s.l.Warn("Error in listener, shutting down", "error", err)
@@ -184,7 +206,7 @@ func (s *SSHServer) run() {
 			// Ensure that a bad client doesn't hurt us by checking for the parent context
 			// cancellation before calling NewServerConn, and forcing the socket to close when
 			// the context is cancelled.
-			sessionContext, sessionCancel := context.WithCancel(s.ctx)
+			sessionContext, sessionCancel := context.WithCancel(ctx)
 			go func() {
 				<-sessionContext.Done()
 				c.Close()
@@ -227,14 +249,9 @@ func (s *SSHServer) run() {
 }
 
 func (s *SSHServer) Stop() {
-	// Close the listener, this will cause all session to terminate as well, see SSHServer.Run
 	if s.listener != nil {
 		if err := s.listener.Close(); err != nil {
 			s.l.Warn("Failed to close the sshd listener", "error", err)
 		}
 	}
 }
-
-func (s *SSHServer) closeSessions() {
-	s.cancel()
-}

timeout.go

@@ -8,6 +8,23 @@ import (
 // How many timer objects should be cached
 const timerCacheMax = 50000
 
+// TimerWheel is a hashed timing wheel: a fixed slot array indexed by (now + delay) % wheelLen,
+// with each slot a singly linked list of items due in that bucket.
+// Adds are O(1), Purges return items in arrival-within-slot order, and an internal cache of TimeoutItems
+// keeps steady-state inserts allocation-free.
+//
+// The TimerWheel does not handle concurrency or lifecycle on its own.
+// Callers drive Advance/Purge from their own ticker loop, take their own locks (or use LockingTimerWheel),
+// and decide whether to keep ticking when the wheel is empty.
+//
+// Pick a TimerWheel when scheduling is high-rate and uniform: line-rate conntrack inserts,
+// per-tunnel traffic checks at fixed intervals. O(1) insert plus the item cache means the hot path doesn't allocate.
+// Items added in the same tick are dispatched together when that slot rotates current,
+// which amortizes the cost of waking the worker.
+//
+// Pick a Scheduler when delay precision matters or scheduling is sparse or uneven.
+// The wheel rounds requested timeouts up to its tick resolution and clamps anything beyond its wheel duration;
+// both are silent in this implementation.
 type TimerWheel[T any] struct {
 	// Current tick
 	current int

udp/conn.go

@@ -8,16 +8,49 @@ import (
 
 const MTU = 9001
 
+// MaxWriteBatch is the largest batch any Conn.WriteBatch implementation is
+// required to accept. Callers SHOULD NOT pass more than this per call; Linux
+// backends preallocate sendmmsg scratch sized to this value, so exceeding it
+// only costs additional sendmmsg chunks within a single WriteBatch call.
+const MaxWriteBatch = 128
+
+// RxMeta carries per-packet metadata extracted from the RX path (ancillary
+// data, kernel offload state, etc.) and passed to EncReader callbacks.
+// Backends that do not produce a particular signal leave its zero value.
+//
+// OuterECN is the 2-bit IP-level ECN codepoint stamped on the carrier
+// datagram (extracted from IP_TOS / IPV6_TCLASS cmsg on Linux). Zero
+// means Not-ECT, which is also the value backends without ECN RX support
+// supply on every packet.
+type RxMeta struct {
+	OuterECN byte
+}
+
 type EncReader func(
 	addr netip.AddrPort,
 	payload []byte,
+	meta RxMeta,
 )
 
 type Conn interface {
 	Rebind() error
 	LocalAddr() (netip.AddrPort, error)
-	ListenOut(r EncReader) error
+	// ListenOut invokes r for each received packet. On batch-capable
+	// backends (recvmmsg), flush is called after each batch is fully
+	// delivered — callers use it to flush per-batch accumulators such as
+	// TUN write coalescers. Single-packet backends call flush after each
+	// packet. flush must not be nil.
+	ListenOut(r EncReader, flush func()) error
 	WriteTo(b []byte, addr netip.AddrPort) error
+	// WriteBatch sends a contiguous batch of packets, each with its own
+	// destination. bufs and addrs must have the same length. outerECNs may
+	// be nil (treated as all-zero / Not-ECT); when non-nil it must have the
+	// same length as bufs, and outerECNs[i] is the 2-bit IP-level ECN
+	// codepoint to set on packet i's outer header. Linux uses sendmmsg(2)
+	// for a single syscall and attaches the value as IP_TOS / IPV6_TCLASS
+	// cmsg; other backends ignore it. Returns on the first error; callers
+	// may observe a partial send if some packets went out before the error.
+	WriteBatch(bufs [][]byte, addrs []netip.AddrPort, outerECNs []byte) error
 	ReloadConfig(c *config.C)
 	SupportsMultipleReaders() bool
 	Close() error
@@ -31,7 +64,7 @@ func (NoopConn) Rebind() error {
 func (NoopConn) LocalAddr() (netip.AddrPort, error) {
 	return netip.AddrPort{}, nil
 }
-func (NoopConn) ListenOut(_ EncReader) error {
+func (NoopConn) ListenOut(_ EncReader, _ func()) error {
 	return nil
 }
 func (NoopConn) SupportsMultipleReaders() bool {
@@ -40,6 +73,9 @@ func (NoopConn) SupportsMultipleReaders() bool {
 func (NoopConn) WriteTo(_ []byte, _ netip.AddrPort) error {
 	return nil
 }
+func (NoopConn) WriteBatch(_ [][]byte, _ []netip.AddrPort, _ []byte) error {
+	return nil
+}
 func (NoopConn) ReloadConfig(_ *config.C) {
 	return
 }

udp/udp_android.go

@@ -5,12 +5,11 @@ package udp
 
 import (
 	"fmt"
+	"log/slog"
 	"net"
 	"net/netip"
 	"syscall"
 
-	"log/slog"
-
 	"golang.org/x/sys/unix"
 )
 

udp/udp_bsd.go

@@ -8,12 +8,11 @@ package udp
 
 import (
 	"fmt"
+	"log/slog"
 	"net"
 	"net/netip"
 	"syscall"
 
-	"log/slog"
-
 	"golang.org/x/sys/unix"
 )
 

udp/udp_bypass_windows.go

@@ -0,0 +1,57 @@
+//go:build (amd64 || arm64) && !e2e_testing
+// +build amd64 arm64
+// +build !e2e_testing
+
+package udp
+
+import (
+	"log/slog"
+	"sync"
+
+	"github.com/slackhq/nebula/config"
+	"github.com/slackhq/nebula/wfp"
+)
+
+// wrapWithWDFBypass wraps a Conn so that the first ReloadConfig consults listen.windows_bypass_wdf
+// and installs a WFP PERMIT filter for the listener's bound UDP port. The session is released when Close runs.
+func wrapWithWDFBypass(l *slog.Logger, conn Conn) Conn {
+	return &bypassConn{Conn: conn, l: l}
+}
+
+type bypassConn struct {
+	Conn
+
+	l           *slog.Logger
+	installOnce sync.Once
+	session     *wfp.Session
+}
+
+func (b *bypassConn) ReloadConfig(c *config.C) {
+	b.installOnce.Do(func() {
+		if !c.GetBool("listen.windows_bypass_wdf", true) {
+			return
+		}
+		addr, err := b.Conn.LocalAddr()
+		if err != nil {
+			b.l.Warn("Failed to query listener port for WFP bypass", "error", err)
+			return
+		}
+		s, err := wfp.PermitUDPPort(addr.Port())
+		if err != nil {
+			b.l.Warn("Failed to install WFP bypass filters for listener", "error", err)
+			return
+		}
+		b.l.Info("Installed WFP filters bypassing Windows Defender Firewall on UDP listener port",
+			"port", addr.Port())
+		b.session = s
+	})
+	b.Conn.ReloadConfig(c)
+}
+
+func (b *bypassConn) Close() error {
+	if b.session != nil {
+		b.session.Close()
+		b.session = nil
+	}
+	return b.Conn.Close()
+}

udp/udp_bypass_windows_386.go

@@ -0,0 +1,11 @@
+//go:build !e2e_testing
+// +build !e2e_testing
+
+package udp
+
+import "log/slog"
+
+// wrapWithWDFBypass is a no-op on windows-386 since we don't currently build for it.
+func wrapWithWDFBypass(_ *slog.Logger, conn Conn) Conn {
+	return conn
+}

udp/udp_darwin.go

@@ -140,6 +140,15 @@ func (u *StdConn) WriteTo(b []byte, ap netip.AddrPort) error {
 	}
 }
 
+func (u *StdConn) WriteBatch(bufs [][]byte, addrs []netip.AddrPort, _ []byte) error {
+	for i, b := range bufs {
+		if err := u.WriteTo(b, addrs[i]); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
 func (u *StdConn) LocalAddr() (netip.AddrPort, error) {
 	a := u.UDPConn.LocalAddr()
 
@@ -165,7 +174,7 @@ func NewUDPStatsEmitter(udpConns []Conn) func() {
 	return func() {}
 }
 
-func (u *StdConn) ListenOut(r EncReader) error {
+func (u *StdConn) ListenOut(r EncReader, flush func()) error {
 	buffer := make([]byte, MTU)
 
 	for {
@@ -179,7 +188,8 @@ func (u *StdConn) ListenOut(r EncReader) error {
 			u.l.Error("unexpected udp socket receive error", "error", err)
 		}
 
-		r(netip.AddrPortFrom(rua.Addr().Unmap(), rua.Port()), buffer[:n])
+		r(netip.AddrPortFrom(rua.Addr().Unmap(), rua.Port()), buffer[:n], RxMeta{})
+		flush()
 	}
 }
 

udp/udp_generic.go

@@ -44,6 +44,15 @@ func (u *GenericConn) WriteTo(b []byte, addr netip.AddrPort) error {
 	return err
 }
 
+func (u *GenericConn) WriteBatch(bufs [][]byte, addrs []netip.AddrPort, _ []byte) error {
+	for i, b := range bufs {
+		if _, err := u.UDPConn.WriteToUDPAddrPort(b, addrs[i]); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
 func (u *GenericConn) LocalAddr() (netip.AddrPort, error) {
 	a := u.UDPConn.LocalAddr()
 
@@ -73,7 +82,7 @@ type rawMessage struct {
 	Len uint32
 }
 
-func (u *GenericConn) ListenOut(r EncReader) error {
+func (u *GenericConn) ListenOut(r EncReader, flush func()) error {
 	buffer := make([]byte, MTU)
 
 	var lastRecvErr time.Time
@@ -93,7 +102,8 @@ func (u *GenericConn) ListenOut(r EncReader) error {
 			continue
 		}
 
-		r(netip.AddrPortFrom(rua.Addr().Unmap(), rua.Port()), buffer[:n])
+		r(netip.AddrPortFrom(rua.Addr().Unmap(), rua.Port()), buffer[:n], RxMeta{})
+		flush()
 	}
 }