So beheben Sie die javax.net.ssl.SSLHandshakeException: Der Remote-Host hat die Verbindung während des Handshakes geschlossen

javax.net.ssl.SSLHandshakeException: Remote host closed connection during handshake bedeutet, dass der SSL/TLS-Handshake von Java nicht abgeschlossen wurde, weil die Gegenstelle die Verbindung geschlossen hat. Die Meldung zeigt, an welcher Stelle der Fehler auftrat, nennt für sich genommen aber nicht dessen Ursache. Mögliche Ursachen sind inkompatible Protokolle oder Cipher, Zertifikats- oder Vertrauensprobleme, Client-Einstellungen, zwischengeschaltete Netzwerkgeräte und Serverrichtlinien.

Bedeutung der Ausnahme

Während eines SSL/TLS-Handshakes handeln Client und Server Protokoll- und Cipher-Auswahl aus und prüfen die Identität des Servers, bevor sie Anwendungsdaten austauschen. Schließt die Gegenstelle die Verbindung während dieser Aushandlung, meldet Java eine SSLHandshakeException. Die Gegenstelle kann der vorgesehene Server, ein Proxy, ein Load Balancer oder ein anderes Netzwerkgerät sein. Aus dem Meldungstext folgt daher nicht, dass der Anwendungsserver selbst die Verbindung geschlossen hat.

Betrachten Sie die Ausnahme als Hinweis auf einen fehlgeschlagenen Handshake, nicht als Beweis für ein abgelaufenes Zertifikat oder eine veraltete Java-Version. Ermitteln Sie zuerst den genauen Endpunkt, die tatsächlich verwendete Java-Laufzeitumgebung und die beteiligte Client-Bibliothek. Die Java-Version auf der Kommandozeile kann von der Laufzeitumgebung abweichen, die eine IDE, ein Anwendungsserver, ein Container oder ein Dienst verwendet.

Ermitteln, warum die Gegenstelle die Verbindung geschlossen hat

Gehen Sie von den Beobachtungen zu den möglichen Ursachen über:

1. Notieren Sie Hostname, Port, Zeitpunkt des Fehlers, die vom Prozess tatsächlich verwendete Java-Laufzeitumgebung sowie die HTTP- oder sonstige Client-Bibliothek. Prüfen Sie, ob Endpunkt und Port stimmen und der Dienst über denselben Netzwerkpfad wie die Anwendung erreichbar ist.
2. Vergleichen Sie die unterstützten TLS-Protokolle und Cipher auf Client- und Serverseite. Prüfen Sie die Konfiguration des Servers oder Load Balancers sowie die wirksamen Einstellungen der Client-Bibliothek. Eine Inkompatibilität ist nur dann plausibel, wenn beide Seiten keine gemeinsam nutzbare Option haben.
3. Untersuchen Sie das für diesen Hostnamen bereitgestellte Serverzertifikat. Prüfen Sie Gültigkeitszeitraum, Übereinstimmung mit dem Hostnamen und Zertifikatskette. Ermitteln Sie anschließend, ob der konfigurierte Truststore des Java-Prozesses der ausstellenden Zertifikatskette vertraut. Ein Zertifikat zu prüfen und einen Truststore zu ändern sind getrennte Schritte.
4. Prüfen Sie, ob ein Proxy, eine Firewall, ein TLS-Inspektionsgerät oder eine andere Netzwerkkontrolle die Verbindung beendet oder filtert. Vergleichen Sie Protokolle und Verhalten entlang des Client-Netzwerkpfads mit den zeitgleichen Serverprotokollen.

Die Java-TLS-Diagnoseprotokollierung kann Details zur Aushandlung offenlegen. Wie sie aktiviert wird und welche Ausgabe entsteht, hängt jedoch vom Java-Client und dessen Startart ab. Verwenden Sie die dokumentierte Diagnoseeinstellung des Clients oder der Laufzeitumgebung. Behandeln Sie die Protokolle vertraulich, da sie Verbindungsdetails enthalten können, und vergleichen Sie die aufgezeichnete Aushandlung mit der Serverkonfiguration. Leiten Sie die Ursache nicht allein aus dem Ausnahmetext ab.

Eine gezielte Lösung anwenden

Ändern Sie immer nur eine Einstellung und nur dann, wenn die Diagnose dafür spricht. Verwendet der Prozess eine Laufzeitumgebung mit einer bekannten Kompatibilitätslücke oder fehlenden Sicherheitsupdates, aktualisieren Sie sie über den unterstützten Bereitstellungsprozess der Anwendung und prüfen Sie, welche Laufzeitumgebung der Prozess lädt. Ein Java-Update ist keine allgemeine Lösung, wenn die Verbindung serverseitig geschlossen wird.

Ergibt die Diagnose ein Problem bei der Protokollaushandlung, konfigurieren Sie die Protokolle für den konkreten HTTP-Client, Socket oder das Framework der Anwendung. Die Systemeigenschaft https.protocols gilt nicht universell für alle Java-TLS-Clients. Dieses API-Beispiel erstellt ein SSLParameters-Objekt, legt TLSv1.2 als Protokollliste fest und liest den gespeicherten Wert anschließend aus. Es veranschaulicht nur den Aufruf der Java-API: Ein realer Client muss geeignete Parameter auf seine eigene Socket- oder Client-Konfiguration anwenden, und die Gegenstelle muss eine kompatible Option unterstützen. Führen Sie das Beispiel aus. Die unveränderte Beispielausgabe zeigt „Configured protocol: TLSv1.2“; diese Beschriftung bleibt Englisch.

import javax.net.ssl.SSLParameters;

public class TlsProtocolExample {
    public static void main(String[] args) {
        SSLParameters parameters = new SSLParameters();
        parameters.setProtocols(new String[] {"TLSv1.2"});
        System.out.println("Configured protocol: " + parameters.getProtocols()[0]);
    }
}

Zeigt die Prüfung des Zertifikats ein Problem mit dem Hostnamen, der Gültigkeit oder der Zertifikatskette, korrigieren Sie das vom Endpunkt bereitgestellte Zertifikat oder dessen Serverkonfiguration. Ist die Kette korrekt, dem Java-Prozess fehlt aber ein passender Vertrauensanker, prüfen Sie den für diesen Prozess ausgewählten Truststore und befolgen Sie das Verfahren Ihrer Organisation für die Verwaltung von Vertrauensstellungen. Importieren Sie nicht einfach ein Zertifikat, nur weil der Handshake fehlgeschlagen ist: Ein ungeprüftes Zertifikat kann die Identitätsprüfung schwächen. Mit keytool lassen sich Java-Keystores untersuchen oder ändern. Datei, Optionen und nötige Berechtigungen hängen jedoch von Laufzeitumgebung und Bereitstellung ab. Orientieren Sie sich an der Dokumentation für Ihre Umgebung, statt einen Befehl mit angenommenen Pfaden zu übernehmen.

Weisen die Befunde auf einen Proxy, eine Firewall oder eine Richtlinie der Gegenstelle hin, ändern Sie gemeinsam mit der zuständigen Stelle nur den betroffenen Netzwerkpfad oder die betreffende Konfiguration. Kann der Client nicht erkennen, warum die Gegenstelle die Verbindung geschlossen hat, bitten Sie die Serveradministration, die serverseitigen TLS-Protokolle, unterstützten Protokolle und Cipher, die Zertifikatskonfiguration sowie jüngste Änderungen zu vergleichen.

Die Lösung überprüfen und serverseitige Probleme eskalieren

Wiederholen Sie dieselbe Anfrage mit derselben Anwendungs-Laufzeitumgebung, demselben Endpunkt und demselben Netzwerkpfad. Ein erfolgreicher Handshake und die erwartete Antwort der Anwendung zeigen, dass die Verbindung nun zustande kommt; eine Einstellung lediglich zu ändern, reicht dafür nicht. Tritt die Ausnahme weiterhin auf, erfassen Sie Zeitpunkt, Endpunkt, Versionen von Laufzeitumgebung und Client, relevante Client-Diagnosedaten sowie die dazugehörigen Server- oder Proxy-Protokolle. Vergleichen Sie diese Angaben, um festzustellen, welche Seite die Verbindung schließt. Entfernen Sie Zugangsdaten und andere vertrauliche Werte, bevor Sie Protokolle weitergeben. Haben Sie keinen Zugriff auf serverseitige Befunde, geben Sie diese Informationen an die Server- oder Netzwerkadministration weiter, statt anzunehmen, dass eine weitere Änderung auf der Clientseite das Problem behebt.