WireGuard QR-Code: aus einer .conf erzeugen (qrencode)

Affiliate-Hinweis: Dieser Beitrag enthält Affiliate-Links zu Contabo. Wenn Sie darüber einen VPS buchen, erhalten wir eine Provision, ohne dass Ihnen zusätzliche Kosten entstehen.

Einen base64-kodierten privaten Schlüssel über die Handytastatur einzutippen, ist so mühsam, dass viele Konfigurationen stattdessen über Chat-Apps verschicken, was noch schlechter ist. Der QR-Code existiert, um beides zu vermeiden.

Es ist ein einziger Befehl, und lesenswert ist vor allem, was nach dem Scannen passiert.

Noch keine Konfiguration oder gerade kein Terminal zur Hand? Unser WireGuard-Konfigurationsgenerator erstellt die Serverdatei und eine Client-Konfiguration pro Gerät, jeweils mit QR-Code, vollständig in Ihrem Browser: Die Schlüssel werden lokal mit Curve25519 erzeugt, und nichts wird an einen Server gesendet. Eine vorhandene .conf wandelt er nicht um; dafür ist qrencode (siehe unten) das richtige Werkzeug. Auch noch keinen Server? Die erzeugten Dateien laufen auf jedem VPS mit öffentlicher IPv4, etwa einem Contabo Cloud VPS 4 für 5,50 €/Monat (Affiliate-Link, 24 Monate Laufzeit, inkl. MwSt.).

QR-Code erzeugen

Installieren Sie den Encoder:

apt install qrencode      # Debian, Ubuntu
dnf install qrencode      # Fedora, RHEL

Dann, auf dem Rechner mit der Client-Konfiguration:

qrencode -t ansiutf8 < /etc/wireguard/client1.conf

Der Code erscheint im Terminal, gezeichnet aus Blockzeichen. Öffnen Sie WireGuard auf dem Telefon, fügen Sie einen Tunnel hinzu, wählen Sie das Scannen per QR-Code und richten Sie die Kamera auf den Bildschirm. Der Tunnel wird vollständig hinzugefügt, mit Name, Adressen, Schlüsseln und Peer.

Es gibt kein spezielles Format. Der QR-Code enthält die Konfigurationsdatei als Klartext. Alles, was einen QR-Code lesen kann, kann auch Ihre Konfiguration lesen.

Die Größe ist hier selten eine Einschränkung. Eine typische WireGuard-Client-Konfiguration umfasst einige hundert Bytes, und der QR-Standard reicht bis Version 40, einem Raster aus 177 × 177 Modulen, das bei der niedrigsten seiner vier Fehlerkorrekturstufen 2.953 Bytes aufnimmt. Eine Konfiguration passt bequem hinein, und genau deshalb reist das Ganze, privater Schlüssel inklusive, in einem einzigen Bild.

Für eine Datei statt einer Terminalzeichnung:

qrencode -o client1.png < /etc/wireguard/client1.conf

Lässt sich der Code nicht scannen, sind die üblichen Ursachen eine Terminalschrift, die die Blöcke verzerrt, oder eine sehr lange Konfiguration. -t utf8 statt ansiutf8 stellt den Code kleiner dar, und eine kleinere Schriftgröße im Terminal hilft mehr als alles andere.

Der entscheidende Punkt

Eine WireGuard-Client-Konfiguration enthält PrivateKey: einen 32-Byte-Schlüssel nach Curve25519, geschrieben als 44 base64-Zeichen in einer einzigen Zeile. Der QR-Code enthält die Konfiguration. Folglich ist der QR-Code der private Schlüssel, in einem Format, das dafür gemacht ist, von einer Kamera aus der Entfernung gelesen zu werden.

Das verändert, wie Sie damit umgehen sollten:

• Fotografieren Sie ihn nicht. Ein Foto landet in Ihrer Galerie und auf den meisten Telefonen direkt in einer Cloud-Sicherung.
• Verschicken Sie ihn nicht per Chat oder E-Mail. Beides sind gespeicherte Kopien, die Sie nicht kontrollieren.
• Leeren Sie das Terminal nach dem Scannen. clear allein leert den Scrollback nicht. Verwenden Sie reset oder schließen Sie das Terminalfenster ganz.
• Löschen Sie PNG-Dateien sofort. Eine client1.png in einem Home-Verzeichnis überdauert den Grund, aus dem sie erstellt wurde.
• Zeigen Sie ihn nicht dort an, wo eine Kamera ihn sehen kann, was in einem Gemeinschaftsbüro auch das Fenster hinter Ihnen einschließt.

Ein privater Schlüssel pro Client ist die Regel, die der QR-Code leicht brechen lässt. Wer eine Konfiguration erzeugt und sie auf drei Telefone scannt, gibt allen dreien dieselbe Identität. Der Server kann sie dann nicht unterscheiden, kann keines davon einzeln sperren und leitet Datenverkehr falsch, sobald zwei gleichzeitig verbunden sind. Wie Sie für jedes Gerät einen eigenen Peer anlegen, erklärt WireGuard-Peer hinzufügen.

Zuerst die Konfiguration erzeugen, falls Sie noch keine haben

Der QR-Code ist der letzte Schritt. Davor braucht der Client ein Schlüsselpaar und einen Peer-Eintrag auf dem Server:

wg genkey | tee client1.key | wg pubkey > client1.pub

Dann eine Konfiguration, die auf den öffentlichen Schlüssel des Servers, den Endpoint und AllowedIPs verweist, sowie einen passenden [Peer]-Block auf dem Server mit client1.pub. Wird die Serverseite übersprungen, ist das der häufigste Grund, warum ein gescannter Tunnel sich mit nichts verbindet: Das Telefon ist konfiguriert, aber der Server hat noch nie davon gehört.

Wenn Sie die Dateien lieber nicht von Hand erstellen, schreibt der Konfigurationsgenerator beide Seiten auf einmal (Server-[Interface] mit jedem [Peer]-Block, dazu pro Gerät eine Client-Datei und einen QR-Code), sodass das gescannte Telefon und der Server, mit dem es spricht, von Anfang an zusammenpassen.

Der Server braucht eine öffentliche IP-Adresse, die Ihr Telefon aus dem Mobilfunknetz erreichen kann. Ein Heimanschluss hinter CGNAT hat keine (prüfen Sie Ihren mit dem WireGuard-Port-Checker); ein kleiner VPS hat eine, für rund 5 € im Monat.

Vollständige Anleitungen inklusive Serverseite finden Sie unter PiVPN-WireGuard-Einrichtung für einen Raspberry Pi und Selbsthosting auf einem VPS für einen gemieteten Server. Beide erzeugen Client-Konfigurationen, die Sie direkt an qrencode weiterleiten können.

Wenn der Scan klappt, der Tunnel aber nicht

Der QR-Code hat seine Aufgabe erfüllt, sobald der Tunnel in der App erscheint. Alles danach ist gewöhnliches WireGuard.

Prüfen Sie, ob das Telefon einen aktuellen Handshake anzeigt. Ein gesunder Peer führt etwa alle 120 Sekunden einen neuen Handshake durch, ein Wert von mehr als rund zwei Minuten bei einem aktiven Tunnel ist also ein Symptom und keine Pause. Fehlt er, gehen Sie die Handshake-Fehlerbehebung durch: Endpoint-Adresse, von außen erreichbarer Port (standardmäßig 51820/UDP), Server-Firewall und Peer-Eintrag. Gelingt der Handshake, aber Seiten bleiben hängen, liegt es an der MTU, was besonders in Mobilfunknetzen häufig vorkommt.

Plattformspezifische Hinweise zur Einrichtung finden Sie unter WireGuard auf Android einrichten und WireGuard unter iOS einrichten.