1. Overview
In this tutorial, we’ll take a look at common issues we might encounter when issuing SSL requests.
2. Certificate Store Error
Whenever a Java application opens an SSL connection with a remote party, it needs to check whether the server is trustworthy or not by validating its certificates. If the root certificate is not contained in the certificate store file, then there will be a security exception:
Untrusted: Exception in thread "main" javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
We need to remember that the default location of this file is $JAVA_HOME/lib/security/cacerts.
3. Self-Signed Certificates
In non-production environments, it is common to find certificates signed by non-trusted issuers, which are known as self-signed certificates.
We can find some examples of untrusted certificates under https://wrong.host.badssl.com/ or https://self-signed.badssl.com/. Opening both URLs in any browser will result in a security exception. We can check them out and see the differences in the certificates.
After opening https://self-signed.badssl.com/, we can see the browser returns a “Cert Authority Invalid” error, as the certificate has been issued by an authority that is unknown to the browser:
On the other hand, opening https://wrong.host.badssl.com/ results in a “Cert Common Name Invalid” error, another kind of error that indicates the certificate has been issued for a different hostname than the provided one:
The same will occur for an application running inside the JDK/JRE. These security exceptions will prevent us from opening an SSL connection to those untrusted parties.
4. Managing the Certificate Store to Trust Our Certificates
Lucky us, the JDK/JRE provides a tool to interact with the certificate store to administer its content. This tool is the Keytool and can be found in $JAVA_HOME/bin/keytool.
Important Note: keytool requires a password to interact with it. The default password is “changeit”.
4.1. List Certificates
To get a list of all the certificates registered in the JVM’s certificate store, we need to issue the following command:
keytool -list -keystore $JAVA_HOME/lib/security/cacerts
This will return a list with all the entries, like:
Your keystore contains 227 entries
Alias name: accvraiz1
Creation date: Apr 14, 2021
Entry type: trustedCertEntry
Owner: C=ES, O=ACCV, OU=PKIACCV, CN=ACCVRAIZ1
Issuer: C=ES, O=ACCV, OU=PKIACCV, CN=ACCVRAIZ1
....
4.2. Add Certificates
To manually add a certificate into that list, so it gets validated whenever we issue an SSL request, we need to execute the following command:
keytool -import -trustcacerts -file [certificate-file] -alias [alias] -keystore $JAVA_HOME/lib/security/cacerts
For instance:
keytool -import -alias ss-badssl.com -keystore $JAVA_HOME/lib/security/cacerts -file ss-badssl.pem
4.3. Custom Certificate Store Path
If nothing of the above works, it might be the case our Java application is using a different certificate store. To make sure of it, we can specify the certificate store to use whenever we run your Java application:
java -Djavax.net.ssl.trustStore=CustomTrustStorePath ...
That way, we make sure it’s using the certificate store we previously edited. If that doesn’t help, we can also debug SSL connections by applying the VM option:
-Djavax.net.debug=all
5. Automation Script
Wrapping up, we can create a simple but handy script to automate the whole process:
#!/bin/sh
# cacerts.sh
/usr/bin/openssl s_client -showcerts -connect $1:443 </dev/null 2>/dev/null | /usr/bin/openssl x509 -outform PEM > /tmp/$1.pem
$JAVA_HOME/bin/keytool -import -trustcacerts -file /tmp/$1.pem -alias $1 -keystore $JAVA_HOME/lib/security/cacerts
rm /tmp/$1.pem
In the script, we can see the first part opens an SSL connection to the DNS passed as the first argument and requests it to show the certificates. After that, the certificate information is piped through openssl to digest it and store it as a PEM file.
Finally, this PEM file is the one we’ll use by instructing the keytool to import the certificate into the cacerts file with the DNS as the alias.
For instance, we can try adding the certificate for https://self-signed.badssl.com:
cacerts.sh self-signed.badssl.com
And after running it, we can check our cacerts file now contains the certificate:
keytool -list -keystore $JAVA_HOME/lib/security/cacerts
Finally, we’ll see the new certificate is there:
#5: ObjectId: 2.5.29.32 Criticality=false
CertificatePolicies [
[CertificatePolicyId: [2.5.29.32.0]
Alias name: self-signed.badssl.com
Creation date: Oct 22, 2021
Entry type: trustedCertEntry
Owner: CN=*.badssl.com, O=BadSSL, L=San Francisco, ST=California, C=US
Issuer: CN=*.badssl.com, O=BadSSL, L=San Francisco, ST=California, C=US
Serial number: c9c0f0107cc53eb0
Valid from: Mon Oct 11 22:03:54 CEST 2021 until: Wed Oct 11 22:03:54 CEST 2023
Certificate fingerprints:
....
6. Manually Adding a Certificate
We can also use our browser to extract the certificate and add it through keytool if, for any reason, we don’t want to use openssl.
In Chromium-based browsers, we open the website like https://self-signed.badssl.com/ and open the developer tools (F12 for Windows and Linux). Let’s then click on the Security tab and finally on “View Certificate”. The certificate information will show up:
Let’s go to the “Details” tab, click on the “Export” button and save it. That’s our PEM file:
Finally, we import it using keytool:
$JAVA_HOME/bin/keytool -import -trustcacerts -file CERTIFICATEFILE -alias ALIAS -keystore $JAVA_HOME/lib/security/cacerts
7. Conclusion
In this article, we’ve seen how to add a self-signed certificate to our JDK/JRE certificate store. Now, our Java applications can trust the server-side whenever they open an SSL connection to sites containing these certificates.
