curl SNI verstehen - Fehler bei TLS-Zertifikaten lösen

Bei TLS-Verbindungen entscheidet der Hostname nicht nur darüber, wohin curl spricht, sondern auch darüber, welches Zertifikat der Server im Handshake präsentiert. Genau deshalb ist curl sni in der Praxis kein Randthema, sondern eine saubere Testfrage für Staging, Reverse Proxies und interne Zertifikate. Ich zeige dir, wie curl den Namen für SNI auswählt, welche Optionen nur die Ziel-IP ändern und wo Zertifikatsfehler in Wirklichkeit herkommen.

Was SNI bei curl technisch auslöst

Ich trenne das Thema gern in eine klare Kette: Hostname in der URL, TCP-Verbindung zur Zieladresse, TLS-Handshake mit SNI. SNI bedeutet Server Name Indication, also die Weitergabe des gewünschten Namens schon im TLS-Start, damit ein Server mit mehreren virtuellen Hosts das richtige Zertifikat und den richtigen Zielkontext liefert. Streng genommen reden wir heute fast immer über TLS, auch wenn im Alltag noch oft von SSL die Rede ist.

curl nimmt den Namen aus der URL und verwendet ihn für die TLS-Identität, solange wirklich ein Hostname vorhanden ist. Wenn du dagegen direkt eine IP ansprichst, fehlt dieser Name als Grundlage für SNI, und genau dann kippen viele Setups in Zertifikatsfehler oder liefern das falsche Default-Zertifikat zurück. Der erste praktische Schluss daraus ist simpel: Hostname behalten, wenn du Zertifikate sauber testen willst.

Genau deshalb lohnt sich im nächsten Schritt die saubere Trennung von URL-Hostname, HTTP-Header und Ziel-IP.

Hostname, IP und Host-Header nicht verwechseln

In der Praxis entstehen die meisten Missverständnisse nicht durch curl selbst, sondern durch die Vermischung von drei Ebenen. Ich schaue bei jedem Testfall zuerst auf diese Aufteilung:

• URL-Hostname steuert SNI und die Zertifikatsprüfung.
• Ziel-IP bestimmt, wohin die Verbindung technisch aufgebaut wird.
• Host-Header gehört zur HTTP-Schicht und beeinflusst nicht automatisch TLS.

Ein Beispiel zeigt den Unterschied sehr deutlich: Wenn du mit -H "Host: app.example.de" auf eine IP gehst, kann das zwar für das HTTP-Routing reichen, aber das Zertifikat ist damit noch lange nicht passend. curl prüft weiterhin gegen den Namen, den die TLS-Schicht sieht, und der kommt nicht aus dem HTTP-Header. Ich setze den Host-Header nur dann separat, wenn die Anwendungsebene ihn wirklich braucht, nicht als Ersatz für SNI.

Wenn diese Ebenen getrennt sind, lässt sich viel leichter entscheiden, welche curl-Option das Problem wirklich löst.

Welche curl-Optionen die Verbindung wirklich beeinflussen

Hier wird es praktisch, denn nicht jede Umleitung ist gleich. Manche Optionen ändern nur den Netzwerkpfad, andere behalten den Hostnamen bewusst bei, und wieder andere schalten die Prüfung komplett ab. Ich nutze sie deshalb sehr bewusst und nicht als Sammelbecken für „irgendwie soll es erstmal laufen“.

Ein Detail, das oft übersehen wird: Bei --connect-to muss der Hostname exakt zum Namen in der URL passen, also wirklich als String übereinstimmen. Außerdem brauchst du für unterschiedliche Ports eigene Einträge, also zum Beispiel getrennt für :443 und :8443. Bei IPv6 gehören die Adressen in eckige Klammern. Wenn du nur die Zieladresse für einen Hostname austauschen willst, ist --resolve deshalb meist die sauberere Lösung.

Mit diesen Werkzeugen lassen sich die meisten Testfälle schon abbilden; im Alltag zeigt sich dann, welche Muster wirklich stabil sind.

Praxisbeispiele für Staging, Reverse Proxies und lokale Tests

Wenn ich eine produktive Domain gegen einen lokalen Dienst testen will, lasse ich den Hostnamen stehen und biege nur die Zieladresse um. So bleibt SNI korrekt, und das Zertifikat wird gegen denselben Namen geprüft, den die echte Umgebung später auch sieht.

curl -v --resolve shop.example.de:443:127.0.0.1 https://shop.example.de/

Dieses Muster ist für Staging fast immer meine erste Wahl. Der Dienst auf 127.0.0.1 kann dabei mit einem Zertifikat für shop.example.de laufen, und genau so sieht curl die Verbindung auch. Das ist präziser als ein direkter IP-Aufruf, weil du nicht versehentlich an der TLS-Identität vorbeitest.

Wenn ich dagegen nur den Verbindungsweg auf einen anderen Backend-Port legen will, aber den TLS-Namen unverändert lassen muss, greife ich zu --connect-to.

curl -v --connect-to api.example.de:443:127.0.0.1:8443 https://api.example.de/

Das ist nützlich, wenn ein Reverse Proxy, ein lokaler Tunnel oder ein Test-Backend auf einem anderen Port sitzt. Der entscheidende Punkt ist hier: Der Zertifikatsname bleibt api.example.de, nur der TCP-Weg führt an einen anderen Ort. Genau deshalb ist diese Option keine SNI-Abkürzung, sondern ein Routing-Werkzeug.

Wenn das Zertifikat selbst vertrauenswürdig sein soll, aber die eigene PKI noch nicht im System vertraut ist, arbeite ich lieber mit einer passenden CA-Datei statt mit einem pauschalen -k.

curl --cacert /pfad/zur/internal-ca.pem https://api.intern.example/

Das ist in Unternehmensumgebungen meist die richtige Haltung: Vertrauen sauber konfigurieren, nicht abschalten. Trotzdem entstehen die meisten Fehlermeldungen nicht hier, sondern an ein paar sehr typischen Stellen.

Typische Fehlerbilder bei Zertifikaten und Weiterleitungen

Der häufigste Fehler ist fast banal: Die URL zeigt auf eine IP, aber das Zertifikat ist nur für den Namen ausgestellt. Dann fehlt SNI als sauberer Namensanker, und die Prüfung schlägt fehl oder landet beim falschen Zertifikat. Wer hier nur mit -k reagiert, kaschiert das Problem eher, als es zu lösen.

• Direkte IP statt Hostname führt oft zu fehlendem SNI und Zertifikatsmismatch.
• Nur den Host-Header ändern hilft auf HTTP-Ebene, aber nicht bei TLS.
• Weiterleitungen auf eine IP sind heikel, weil der zweite Aufruf dann wieder ohne passenden Namen dasteht.
• Ein einzelner --resolve-Eintrag für mehrere Ports reicht nicht, weil Host und Port zusammengehören.
• Zu früh zu -k greifen macht Tests scheinbar erfolgreich, obwohl die Zertifikatskette weiter falsch ist.

Wenn ein Redirect ins Spiel kommt, prüfe ich immer das Location-Ziel. Führt es auf eine IP oder auf einen anderen Hostnamen, kann der zweite TLS-Handshake plötzlich ganz anders aussehen als der erste. Das ist besonders tückisch bei -L, weil curl die Weiterleitung automatisch folgt und der eigentliche Fehler erst später sichtbar wird.

Auf Windows und Linux lohnt sich zusätzlich ein Blick auf curl -V, weil das verwendete TLS-Backend und der Trust Store das Fehlverhalten sichtbar beeinflussen können. Wenn du diese Muster erkennst, sparst du dir viel Zeit im Debugging.

So debugge ich SNI-Probleme sauber und ohne Rätselraten

Mein Debugging läuft fast immer in derselben Reihenfolge. Erst der einfache Blick mit -v, dann bei Bedarf ein kompletteres Trace, und erst danach die Frage, ob das Zertifikat selbst oder nur die Zielauflösung falsch ist.

1. Verbose starten: Mit curl -v https://example.de/ sehe ich schnell, wohin die Verbindung geht und welches Zertifikat präsentiert wird.
2. Trace einschalten: Mit --trace-ascii debug.txt --trace-time bekomme ich die Details, wenn -v nicht mehr reicht.
3. Hostname und Zieladresse gegeneinander testen: Erst der normale Aufruf, dann derselbe Host mit --resolve.
4. Zertifikatsprüfung maschinenlesbar machen: curl -s -o /dev/null -w '%{ssl_verify_result}\n' https://api.example.de/ liefert 0, wenn die Prüfung erfolgreich war.
5. CA statt Ausnahmen prüfen: Wenn nur der Trust fehlt, ist --cacert die richtige Diagnose, nicht -k.

Ich schaue dabei immer auf drei Fragen: Welcher Name steht in der URL, wohin geht die TCP-Verbindung und welches Zertifikat wird tatsächlich geliefert? Genau diese drei Punkte erklären in der Regel fast jeden SNI-Fehler. Wenn der Trace sauber ist, sieht man außerdem schneller, ob ein Proxy, ein Redirect oder ein falscher Backend-Pfad dazwischenfunkt.

Am Ende ist die zuverlässigste Methode meist die unspektakulärste.

Welche Arbeitsweise bei curl und Zertifikaten am zuverlässigsten bleibt

Wenn ich einen Test wirklich belastbar machen will, halte ich den Hostnamen in der URL fest und ändere nur dann die Zieladresse, wenn es einen klaren Grund gibt. Für die Namensauflösung nehme ich --resolve oder notfalls /etc/hosts, für reine Verbindungsumleitungen --connect-to, und für Vertrauensprobleme eine passende CA statt einer pauschalen Abschaltung der Prüfung.

Das ist die Variante, die im Alltag am wenigsten Überraschungen erzeugt. Sie bleibt nah an der echten Produktion, zeigt Fehlkonfigurationen früh und verhindert, dass ein scheinbar funktionierender Test später im Betrieb wieder auseinanderfällt. Wenn du zwischen Routing und TLS-Identität sauber trennst, bleibt curl ein präzises Werkzeug und kein Zufallsgenerator.