Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

A Java client fails the TLS handshake with SSLHandshakeException

Errorjavax.net.ssl.SSLHandshakeException

Short answer

SSLHandshakeException means the TLS handshake stopped before any data moved. In a Java client the usual reasons are that the server certificate is unknown to the truststore the JVM loaded, the JVM loaded a different or empty truststore than you think, the system clock is wrong, or client and server could not agree on a TLS protocol version. Turn on handshake debugging first: it names which one.

  • Applies to Java 21, JSSE (SunJSSE provider), keytool from the JDK
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the failing program once with JSSE handshake tracing. The output shows each certificate the server sent and which truststore file was loaded, which separates the causes below.

    java -Djavax.net.debug=ssl:handshake -jar app.jar
  2. 2Match what you see, then jump to its fix

    1. 1The trace shows a certificate arriving from the server and the exception is a CertificateException while handshaking.The server certificate is unknown to the truststoreFix
    2. 2You imported the certificate, but the error stays, or it only fails in one environment (an app server, a container, a service).The JVM loads a different truststore than you expectFix
    3. 3The certificate chain is one you trust, but the handshake still fails with a CertificateException, mostly on a fresh VM, container or device.The system clock is wrongFix
    4. 4The connection is closed right after the client sends its ClientHello.Client and server do not share a TLS protocol versionFix

What does the error look like?

  • javax.net.ssl.SSLHandshakeException
  • Socket Disconnected After Sending ClientHello Message

Cause 1 of 4

The server certificate is unknown to the truststore

1Check

This is the usual cause when the server uses a private CA or a self-signed certificate. The received certificate is unknown to the trust mechanism, so Java refuses it. Compare the issuer in the trace with the CAs in the default truststore.

keytool -list -cacerts -storepass changeit | head

2Fix

Import the CA certificate (not the leaf, when you have the CA) into the truststore the app uses. The -cacerts option points keytool at the JDK default truststore; the cacerts password is documented as changeit unless an administrator changed it. For one application it is cleaner to build a separate truststore with -keystore and point the app at it (see the next cause).

keytool -importcert -alias my-private-ca -file ca.pem -cacerts

3Verify

Run the same program again; the handshake trace ends without an exception.

java -Djavax.net.debug=ssl:handshake -jar app.jar

Confirmed by docs.oracle.com

Did this fix it?

Cause 2 of 4

The JVM loads a different truststore than you expect

1Check

If javax.net.ssl.trustStore is set, only that file is used. If it is set to a path that does not exist, JSSE ends up with no trusted CAs at all. If the property is not set, Java uses jssecacerts when it exists, otherwise cacerts under the JDK. So a stray property, or a jssecacerts file, can hide the cacerts you edited.

ps -o args= -p <pid-of-java> | tr ' ' '\n' | grep -i truststore
ls "$JAVA_HOME/lib/security/"

2Fix

Point the property at the file that really holds your CA, with its password, or remove the stray property so the default is used. Make sure the JDK that runs the app is the JDK you edited.

java -Djavax.net.ssl.trustStore=/etc/app/truststore.p12 \
     -Djavax.net.ssl.trustStorePassword=changeme \
     -jar app.jar

3Verify

Restart the app with handshake tracing and check that the trace reads the truststore file you named.

java -Djavax.net.debug=ssl:handshake -Djavax.net.ssl.trustStore=/etc/app/truststore.p12 -Djavax.net.ssl.trustStorePassword=changeme -jar app.jar

Confirmed by docs.oracle.com

Did this fix it?

Cause 3 of 4

The system clock is wrong

1Check

The JSSE guide lists a wrong system clock as a second cause of a CertificateException during the handshake: a certificate is outside its validity dates when the clock is far off.

date -u
timedatectl status

2Fix

Correct the clock and keep it synchronised with NTP.

sudo timedatectl set-ntp true

3Verify

Run the client again after the clock is right.

date -u

Confirmed by docs.oracle.com

Did this fix it?

Cause 4 of 4

Client and server do not share a TLS protocol version

1Check

Some servers drop a connection when the ClientHello carries a protocol version they do not support. List the protocols your code or JVM settings allow.

grep -rn "jdk.tls.client.protocols\|https.protocols\|setEnabledProtocols\|SSLContext.getInstance" src/

2Fix

Adjust the enabled protocols on the client. The JSSE guide names these places: the https.protocols system property for HttpsURLConnection, the jdk.tls.client.protocols system property, SSLContext.getInstance and SSLEngine.setEnabledProtocols. Restrict to the versions the server really supports instead of switching security off.

java -Djdk.tls.client.protocols="TLSv1.2,TLSv1.3" -jar app.jar

3Verify

Run again with handshake tracing; the connection is no longer closed after the ClientHello.

java -Djavax.net.debug=ssl:handshake -Djdk.tls.client.protocols="TLSv1.2,TLSv1.3" -jar app.jar

Confirmed by docs.oracle.com

Did this fix it?

How do I stop it coming back?

  • Keep private CA certificates in a truststore file that ships with the app, and name it with javax.net.ssl.trustStore, instead of editing the JDK's cacerts by hand.
  • Log the JVM arguments at start-up so a stray trustStore property is easy to see.
  • Run NTP on every server and container host.
  • Never disable certificate or hostname checks to make an error go away; fix the trust.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Back end

Gradle runs no Cucumber scenarios from my feature files

Feature files exist under src/test but nothing runs

Cucumber runs on the JUnit Platform, so Gradle must call useJUnitPlatform() and have the cucumber-junit-platform-engine on the test classpath.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.