punchline

Ende-zu-Ende-verschlüsselter Peer-to-Peer-Chat über UDP. Keine Konten, kein zentraler Server, der Nachrichten weiterleitet/speichert, kein Mittelsmann. Nur zwei Peers, eine direkte Verbindung und Noise-Protokoll-Verschlüsselung.

https://github.com/user-attachments/assets/939e96d3-45e3-4484-9a27-28c3a0457b05

Inhaltsverzeichnis

• Was es tut
• Schnellstart
• Wie es funktioniert
• CLI-Referenz
• Verwendung
  • Konfiguration
  • Peers verwalten
  • Statusprüfung
  • Server-Optionen
  • Theming
  • Shell-Vervollständigung
• Kryptographie
  • IK-Handshake
  • Initiatorbestimmung
  • Schlüsselspeicherung
• Drahtprotokoll
  • Hole-Punch-Protokoll
  • Transportprotokoll
  • Signalprotokoll
  • STUN-Protokoll
• Projektstruktur
• Installation
  • Von crates.io
  • Aus dem Quellcode erstellen
• Tests ausführen
• Technologie-Stack
• Lizenz

Was es tut

Zwei Personen führen punchline connect <peer> auf ihren Maschinen aus. Punchline durchbricht ihre NATs, führt einen verschlüsselten Handshake durch und bringt sie in einen privaten Chat – alles in wenigen Millisekunden. Die enthaltenen STUN- und Signal-Server übernehmen die Erkennung und verschwinden dann.

Schnellstart

cargo build --release

Starte die Server (auf einer Maschine, die beide Peers erreichen können), oder verwende meine öffentlichen unter 64.225.107.28 (STUN: Port 3478, Signal: Port 8743):

punchline-stund                  # STUN server - tells peers their public IP
punchline-signald                # Signal server - matches peers who want to talk

Auf jedem Peer-Computer:

# Generate your identity (X25519 keypair)
punchline keygen

# Share your public key with your peer
punchline pubkey

# Save their key
punchline peers add alice a1b2c3d4...64_hex_chars

# Connect (both peers run this, targeting each other)
punchline connect alice --stun <server>:3478 --signal <server>:8743

Die TUI startet mit einer Live-Ansicht des Verbindungsfortschritts:

1. STUN-Erkennung – Ermittlung deiner externen Adresse über punchline-stund

2. Signal-Server – Verbindung zu punchline-signald

3. Warten auf Peer – Der Signal-Server bringt beide Peers zusammen

4. Hole Punch – Herstellung des direkten UDP-Pfads

5. Noise-Handshake – Verschlüsselter Schlüsselaustausch

   

Sobald abgeschlossen, bist du im Chat. Tippe und drücke Enter. Drücke Esc, um zu beenden.

Wie es funktioniert

Das gesamte System besteht aus drei Binärdateien, die alle in diesem Repository enthalten sind:

Nach der anfänglichen Einrichtung werden die STUN- und Signal-Server nicht mehr kontaktiert. Der gesamte Datenverkehr erfolgt direkt Peer-to-Peer.

CLI-Referenz

punchline

Globale Flags:

punchline-stund

punchline-signald

Verwendung

Konfiguration

Anstatt jedes Mal --stun und --signal zu übergeben, erstelle ~/.config/punchline/config.toml:

stun_server = "203.0.113.10:3478"
signal_server = "203.0.113.10:8743"

Peers verwalten

punchline peers                              # list all
punchline peers add alice a1b2c3d4...        # add
punchline peers remove alice                 # remove

Die Aliase werden in ~/.punchline/known_peers.toml gespeichert. Du kannst auch direkt mit einem rohen 64-stelligen Hex-Schlüssel verbinden.

Statusprüfung

punchline status

Zeigt deine Identität, Konfiguration, Servererreichbarkeit (sendet eine echte STUN-Abfrage und TCP-Verbindung) und die Anzahl der Peers.

Server-Optionen

Beide Server unterstützen -v (Debug), -vv (Trace), -q (Lautlos), --address und --port:

punchline-stund -v --port 3478
punchline-signald -v --port 8743

Theming

Passe die TUI über ~/.config/punchline/style.toml an. Im Video verwendete Stile:

[colors]
my_text = "#ebdbb2"
peer_text = "#bdae93"
input_text = "#ebdbb2"
border = "#ebdbb2"
sidebar_key = "#ebdbb2"
sidebar_value = "#bdae93"

[padding]
chat_horizontal = 2
chat_vertical = 1

Alle Farben sind hex RGB. Wenn die Datei fehlt, werden die Standardfarben des Terminals verwendet.

Shell-Vervollständigung

punchline completions bash > ~/.local/share/bash-completion/completions/punchline
punchline completions zsh > ~/.zfunc/_punchline
punchline completions fish > ~/.config/fish/completions/punchline.fish

Kryptographie

Vollständiger Protokollname: Noise_IK_25519_ChaChaPoly_SHA256

IK-Handshake

Das IK-Muster bedeutet, dass der Initiator den statischen öffentlichen Schlüssel des Responders kennt, bevor der Handshake beginnt. Beide Peers haben bereits die Schlüssel des jeweils anderen (out-of-band oder über die Peer-Registry ausgetauscht), sodass kein Trust-on-First-Use erforderlich ist.

1. Initiator -> Responder: Sendet eine verschlüsselte Nachricht mit seinem statischen öffentlichen Schlüssel, verschlüsselt mit dem bekannten Schlüssel des Responders. Bietet Identitätsschutz gegen passive Beobachter.
2. Responder -> Initiator: Entschlüsselt, verifiziert und antwortet. Beide Seiten wechseln in den Transportmodus mit gemeinsam genutzten Sitzungsschlüsseln.

Initiatorbestimmung

Punchline wählt den Initiator deterministisch aus, indem die ersten 8 Bytes des öffentlichen Schlüssels jedes Peers als Big-Endian-u64 verglichen werden. Der Peer mit dem kleineren Wert wird zum Initiator. Beide Seiten berechnen dies unabhängig.

Schlüsselspeicherung

Die Identität ist ein 32-Byte-X25519-Geheimschlüssel unter ~/.punchline/id_x25519 mit Unix-Berechtigungen 0600. Der öffentliche Schlüssel wird beim Laden abgeleitet. Die Schlüsselerzeugung verwendet x25519-dalek mit OsRng.

Drahtprotokoll

Das erste Byte jedes UDP-Pakets identifiziert seinen Typ:

Hole-Punch-Protokoll

Beide Peers führen gleichzeitig denselben Algorithmus aus:

1. Sende alle 200 ms PROBE (0x00) an die externe Adresse des Peers.
2. Beim Empfang eines PROBE wechsle zum Senden von ACK (0x01).
3. Beim Empfang eines ACK sende ein letztes ACK und erkläre den Erfolg.
4. Sicherheits-Timeout: 2 Sekunden Senden von ACKs ohne Antwort gehen davon aus, dass der Peer fertig ist.

Transportprotokoll

Nachrichten (0x02) enthalten Noise-verschlüsselte UTF-8-Nutzlasten. Keepalives (0x03) sind verschlüsselte leere Nutzlasten, die alle 10 Sekunden gesendet werden, um die Nonce-Synchronisation der Chiffre aufrechtzuerhalten. 30 Sekunden ohne ein Paket führen zur Trennung.

Signalprotokoll

JSON über WebSocket:

// PairRequest (client -> server)
{ "external_addr": "203.0.113.5:48291", "public_key": "a1b2...", "target_public_key": "d4e5..." }

// PairResponse (server -> client)
{ "target_external_addr": "198.51.100.7:51003", "target_public_key": "d4e5..." }

STUN-Protokoll

Folgt RFC 5389 (vereinfacht): Binding-Request/Response mit XOR-MAPPED-ADDRESS. Nur IPv4.

Projektstruktur

Cargo-Workspace mit vier Crates:

crates/
├── proto/      # Gemeinsame Bibliothek: Krypto, STUN, Signal-Typen, Transport-Trait
├── client/     # P2P-Client: CLI, TUI, Verbindungslogik, Peer-Verwaltung
├── signald/    # Signal-Server: WebSocket-Peer-Zuordnung
└── stund/      # STUN-Server: Erkennung externer Adressen

Installation

Von crates.io

cargo install punchline           # TUI client
cargo install punchline-signald   # Signal server
cargo install punchline-stund     # STUN server

Aus dem Quellcode erstellen

Voraussetzungen: Rust 2024 Edition (rustc 1.85+)

git clone https://github.com/michal-pielka/punchline.git
cd punchline
cargo build --release

Binärdateien befinden sich in target/release/:

• punchline
• punchline-signald
• punchline-stund

Tests ausführen

cargo test

Tests decken kryptografische Operationen, STUN-Codierung/-Decodierung, Signalprotokoll-Serialisierung, Konfigurationsparsing, Peer-Verwaltung, Style-Theming und den Noise-IK-Handshake ab.

Technologie-Stack

Lizenz

MIT – siehe LICENSE.