Java Client SSL Setup and Related Errors

This article explains how to configure SSL for a Java client and how to troubleshoot some common errors that may occur during the process.

To troubleshoot the issue effectively, please do the following:

- Enable the JVM option -Djavax.net.debug=all

- Capture the network traffic dump for faster analysis.

Certificate Setup

Go to your console and access your <JAVA_HOME>/bin/keytool

NB: The default location for saving the generated files is the user home directory. You can change this by specifying a path.

STEP 1: Generate a new key (private key) for a Keystore. This either creates a file called <KEYSTORE_NAME>.keystore or update an existing file if it already exists.

The CSR which will be presented to a Certificate Authority (CA) will be generated with this key and alias.

<JAVA_HOME>/bin/keytool -genkey -alias <KEY_ALIAS> -keyalg RSA -key <KEYSTORE_NAME>.keystore -validity 3650 -keysize 2048

STEP 2: Generate a CSR file to be shared with the Certificate Authority (CA) for signing using the command below.

<JAVA_HOME>/bin/keytool -certreq -alias <KEY_ALIAS> -keyalg RSA -file <CSR_NAME>.csr -keystore <KEYSTORE_NAME>.keystore

STEP 3: Copy the CSR file from the user's home directory or specified location to the CA of your choice.

STEP 4: Copy the signed certificate file into a known directory and run the command below.

Import same into your <KEYSTORE_NAME>.keystore using the command below.

<JAVA_HOME>/bin/keytool -importcert -alias <KEY_ALIAS> -file <CERT_FILE>.cer -keystore <KEYSTORE_NAME>.keystore

Pay close attention to the <KEY_ALIAS>. This is the alias to the private key that was used to generate the CSR. This is very important to note.

STEP 5: You can view the details of the keystore with the command below.

<JAVA_HOME>/bin/keytool -list -v -keystore <KEYSTORE_NAME>.keystore

STEP 6: You can delete a certificate by using the alias

<JAVA_HOME>/bin/keytool -delete -alias <KEY_ALIAS> -keystore <KEYSTORE_NAME>.keystore

NB: If you delete the alias of a key, i.e. alias of the command below, you'd need to regenerate another key and use the newly generated key to generate another CSR and then get it signed.

<JAVA_HOME>/bin/keytool -genkey -alias <KEY_ALIAS> -keyalg RSA -key <KEYSTORE_NAME>.keystore -validity 3650 -keysize 2048

This feature allows you to create, sign and import unlimited keys. You can also specify the outbound certificate alias for HTTPS requests. This is useful when you need to use your server as a client and authenticate with another server using a client certificate. This way, you can switch between being a server and a client.

STEP 7: TTo import certificates that are not used as keys, such as a root for a trusted issuer, use the command below

<JAVA_HOME>/bin/keytool -importcert -alias <ALIAS> -file <CERT_FILE>.cer -keystore <KEYSTORE_NAME>.keystore

Errors Encountered Related to the Setup Above Setup

Error: java.lang.Exception: Failed to establish chain from reply

Attempted Fix: Install the root certificate file first into the Keystore as illustrated below.

<JAVA_HOME>/bin/keytool -importcert -alias <ROOR_ALIAS> -file <ROOT>.cer -keystore <KEYSTORE_NAME>.keystore

Keytool Error: java.io.IOException: Invalid keystore format

Fix: remove -storetype JCEKS from the importcert command

Keytool Error: java.lang.Exception: Public keys in reply and keystore don't match

Fix: The <KEY_ALIAS> used to generate the CSR for the certificate does not match the key in the <KEYSTORE_NAME>.keystore file.

Other Communication Errors Include.

RECV TLSv1.2 ALERT: fatal, handshake_failure

javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure

change cipher spec handshake failure

send tlsv1.2 alert: warning, description = close_notify

recv tlsv1 2 alert fatal unexpected_message

recv tlsv1 2 alert fatal close_notify

javax net ssl sslhandshakeexception received fatal alert handshake_failure

Attempted Fix:

Confirm that the certificate alias has a correct and corresponding private key as illustrated below.

Generating a key with an alias <KEY_ALIAS>

<JAVA_HOME>/bin/keytool -genkey -alias <KEY_ALIAS> -keyalg RSA -key <KEYSTORE_NAME>.keystore -validity 3650 -keysize 2048

Generating a CSR file for the CA with same <KEY_ALIAS>

<JAVA_HOME>/bin/keytool -certreq -alias <KEY_ALIAS> -keyalg RSA -file <CSR_NAME>.csr -keystore <KEYSTORE_NAME>.keystore

Importing a signed certificate with the same <KEY_ALIAS>

<JAVA_HOME>/bin/keytool -importcert -alias <KEY_ALIAS> -file <CERT_FILE>.cer -keystore <KEYSTORE_NAME>.keystore

Error: GET_SERVER_HELLO:sslv3 alert handshake failure

Attempted Fix: Confirm your signed certificate is client certificate and not server.

Error: SSL Exception sending alert: java.net.SocketException: Broken pipe

Attempted Fix: Confirm that there is a key in the keystore. In a case of multiple key, implement a custom key manager to pass a desired key.

Errors related to ignoring unsupported cipher suite:

Upgrade “JCE Unlimited Strength Jurisdiction Policy Files" in the <JAVA_HOME>/lib/security directory.

You can find files at:

http://www.oracle.com/technetwork/java/javase/downloads/index.html

Upgrade process at:

https://www.attachmate.com/documentation/rweb/rweb-installguide/data/b1gdutii.htm

Some References

http://www.madhur.co.in/blog/2016/10/30/debugging-ssl-issues-java.html

https://blogs.oracle.com/java-platform-group/jdk-8-will-use-tls-12-as-default

https://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html#SunJSSEProvider

https://stackoverflow.com/questions/44378970/jdk7-ssl-conenction-issue-ignoring-unsupported-cipher-suite-tls-ecdhe-rsa-with

https://blogs.msdn.microsoft.com/sudeepg/2009/02/16/debugging-ssl-handshake-failure-using-network-monitor-a-scenario/