Verbindungs-Handshake mit optionaler gegenseitiger PSK-Authentifizierung #21

Merged
jochen merged 2 commits from feat/psk-handshake into master 2026-11-10 20:16:25 +00:00
Collaborator

Refs #15 (PSK als leichtgewichtige Alternative zu mTLS/PKI) · Teil 1 der Portierung aus Branch auth / ZIP-Version

Wire-Protokoll-Änderung: alle Standorte brauchen diese Version (bewusst ohne Rückwärtskompatibilität, Code läuft nur im Test).

Handshake v1

Jede Peer-Verbindung beginnt mit einem HELLO von beiden Seiten:
"MDNSBRG" | Protokollversion | Flags (PSK an/aus) | 16-Byte-Nonce (25 Bytes).

Fehlkonfigurationen fallen sofort mit klarer Meldung auf statt per Timeout:

  • Gegenseite ist kein mdns-bridged bzw. eine alte Version ohne Handshake
  • unterschiedliche Protokollversion
  • auth_psk is set here but not set on the peer - configure the same PSK on both sides, or on neither

PSK (optional)

Gegenseitige Authentifizierung: HMAC-SHA256 über Rollenlabel + beide HELLOs, Server antwortet 0x00 (abgelehnt) oder 0x01 | MAC_s.

  • kein Replay (frische Nonces), keine Reflection (Rollenlabels), kein Downgrade der Flags (MAC deckt beide HELLOs ab)
  • konstantzeitiger Vergleich (verify_slice), Timeout 5 s, Handshake im Task je Verbindung (blockiert accept nicht)
  • Gegenüber der ZIP-Version (auth.rs): beidseitig statt einseitig, versioniert, getrandom statt rand

Konfiguration: auth_psk (inline) oder auth_psk_file (erste Zeile). Fehler bei beiden gesetzt / leerem Key; Warnung bei < 16 Zeichen und bei für alle lesbarem Key (inline in world-readable Config oder world-readable Key-Datei). Debug des Keys ist geschwärzt.

Status: neue Zähler auth_failed (falscher Key) und handshake_failed (alles andere). Startlog zeigt authentication=psk|none protocol=1.

Doku: README-Abschnitt Authentication, Hinweise in Beispielen, FreeBSD-Sample (inkl. openssl rand/chown root:mdnsbridge/chmod 0640), systemd LoadCredential.

Neue Abhängigkeiten: hmac 0.13, sha2 0.11, getrandom 0.4 (RustCrypto).

Getestet

  • fmt, clippy -D warnings, 29 Tests (9 neu im Handshake, 2 in config), 5× stabil; cargo audit grün; FreeBSD cargo check
  • E2E mit zwei Daemons: gleicher PSK (inline vs. Datei) → authenticated=true, Weiterleitung ok; falscher PSK → beidseitig auth_failed + „peer rejected our PSK…“; PSK nur einseitig → handshake_failed mit obiger Meldung; ohne PSK unverändert; leerer PSK fatal; Warnungen für kurzen/world-readable Key erscheinen
  • Offen: Test auf OPNsense mit dem Paket aus diesem PR-Lauf (beide Knoten brauchen diese Version)

Nächste Schritte

PR 2: Adress-Records immer mitsenden (auch ingress, SRV-Targets), Replay bei (Re-)Connect mit TTL-Ablauf/Goodbye, TCP-Keepalive, Warnung bei unbekannten Config-Keys. Danach Plugin.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Vh6img4RYU1F52VUwGJcrp

Refs #15 (PSK als leichtgewichtige Alternative zu mTLS/PKI) · Teil 1 der Portierung aus Branch `auth` / ZIP-Version **Wire-Protokoll-Änderung:** alle Standorte brauchen diese Version (bewusst ohne Rückwärtskompatibilität, Code läuft nur im Test). ## Handshake v1 Jede Peer-Verbindung beginnt mit einem HELLO von beiden Seiten: `"MDNSBRG" | Protokollversion | Flags (PSK an/aus) | 16-Byte-Nonce` (25 Bytes). Fehlkonfigurationen fallen **sofort mit klarer Meldung** auf statt per Timeout: - Gegenseite ist kein mdns-bridged bzw. eine alte Version ohne Handshake - unterschiedliche Protokollversion - `auth_psk is set here but not set on the peer - configure the same PSK on both sides, or on neither` ## PSK (optional) Gegenseitige Authentifizierung: HMAC-SHA256 über Rollenlabel + beide HELLOs, Server antwortet `0x00` (abgelehnt) oder `0x01 | MAC_s`. - kein Replay (frische Nonces), keine Reflection (Rollenlabels), kein Downgrade der Flags (MAC deckt beide HELLOs ab) - konstantzeitiger Vergleich (`verify_slice`), Timeout 5 s, Handshake im Task je Verbindung (blockiert `accept` nicht) - Gegenüber der ZIP-Version (`auth.rs`): beidseitig statt einseitig, versioniert, `getrandom` statt `rand` Konfiguration: `auth_psk` (inline) **oder** `auth_psk_file` (erste Zeile). Fehler bei beiden gesetzt / leerem Key; Warnung bei < 16 Zeichen und bei für alle lesbarem Key (inline in world-readable Config oder world-readable Key-Datei). `Debug` des Keys ist geschwärzt. Status: neue Zähler `auth_failed` (falscher Key) und `handshake_failed` (alles andere). Startlog zeigt `authentication=psk|none protocol=1`. Doku: README-Abschnitt *Authentication*, Hinweise in Beispielen, FreeBSD-Sample (inkl. `openssl rand`/`chown root:mdnsbridge`/`chmod 0640`), systemd `LoadCredential`. Neue Abhängigkeiten: `hmac 0.13`, `sha2 0.11`, `getrandom 0.4` (RustCrypto). ## Getestet - fmt, clippy `-D warnings`, 29 Tests (9 neu im Handshake, 2 in config), 5× stabil; `cargo audit` grün; FreeBSD `cargo check` - E2E mit zwei Daemons: gleicher PSK (inline vs. Datei) → `authenticated=true`, Weiterleitung ok; falscher PSK → beidseitig `auth_failed` + „peer rejected our PSK…“; PSK nur einseitig → `handshake_failed` mit obiger Meldung; ohne PSK unverändert; leerer PSK fatal; Warnungen für kurzen/world-readable Key erscheinen - **Offen:** Test auf OPNsense mit dem Paket aus diesem PR-Lauf (beide Knoten brauchen diese Version) ## Nächste Schritte PR 2: Adress-Records immer mitsenden (auch ingress, SRV-Targets), Replay bei (Re-)Connect mit TTL-Ablauf/Goodbye, TCP-Keepalive, Warnung bei unbekannten Config-Keys. Danach Plugin. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01Vh6img4RYU1F52VUwGJcrp
Versioned connection handshake with optional mutual PSK authentication
Some checks failed
ci / rust (push) Failing after 27s
733a69786b
Every peer connection now starts with a HELLO from both sides:
"MDNSBRG" | protocol version | flags (PSK on/off) | 16-byte nonce.
Mismatches are reported immediately instead of hanging until a
timeout: peer is not mdns-bridge / pre-handshake version, protocol
version differs, auth_psk set on only one side.

With a PSK both sides authenticate each other (HMAC-SHA256 over a role
label and both HELLOs): no replay (fresh nonces), no reflection (role
labels), no downgrade of the flags (MAC covers both HELLOs). Based on
the PSK handshake from the earlier ZIP version (auth.rs), made mutual
and versioned; uses hmac's constant-time verify_slice and getrandom
instead of rand.

- config: auth_psk (inline) or auth_psk_file (first line); both set or
  empty key is an error; warnings for keys shorter than 16 chars and
  for keys readable by everyone (inline in a world-readable config or
  world-readable key file); Psk Debug output is redacted
- handshake runs in the per-connection task (listener) after the
  address allowlist, and after connect (forward) with the normal
  reconnect backoff
- status: new counters auth_failed (wrong key) and handshake_failed
  (everything else)
- deps: hmac 0.13, sha2 0.11, getrandom 0.4; tokio test-util for tests

Wire protocol change: all sites need this version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh6img4RYU1F52VUwGJcrp
PSK: Cargo.lock, README section, config hints
All checks were successful
ci / rust (push) Successful in 2m51s
build-freebsd / freebsd (pull_request) Successful in 2m49s
build-freebsd / release (pull_request) Has been skipped
ci / rust (pull_request) Successful in 2m47s
0db99360f9
- Cargo.lock for hmac/sha2/getrandom
- README: "Authentication (optional PSK)", handshake in the Accept
  step, new status counters, #15 note
- examples, FreeBSD sample config: commented auth_psk_file with
  key-generation commands
- systemd unit: commented LoadCredential for the PSK

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh6img4RYU1F52VUwGJcrp
jochen approved these changes 2026-11-10 20:16:18 +00:00
jochen merged commit 5d0fa15611 into master 2026-11-10 20:16:25 +00:00
jochen deleted branch feat/psk-handshake 2026-11-10 20:16:25 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
jochen/mdns-bridge!21
No description provided.