How to import a CA root certificate into the JVM trust store

Web browsers and application runtimes, such as Java, have a special local database of recognised Certificate Authorities (CA). Each time an SSL/TLS connection is made, that database is queried in order to validate a server’s claimed identity (typically represented by its domain name).

If you try to make a secure connection (e.g. HTTPS or LDAPS) and the server doesn’t respond with a certificate issued by a recognised authority, the connection will fail with the following exception:

CertPathBuilderException: unable to find valid certification path to requested target

If your company has its own CA, or, if you want to make SSL/TLS connections to a server in possession of a certificate issued by a CA which you recognise and trust, but is not listed in the default Java trust store, you will need to import the CA’s root certificate.

We recently encountered such a case when a user of the online OpenID Connect client was not able to connect to a web server which has a certificate issued by the StartCom CA. The root certificate of StartCom is recognised by browsers, but for some reason has not been included in the default JVM trust store.

Instructions for importing a CA root certificate into the JVM trust store

Step 1. Obtain the root certificate

For StartCom the root certificate was made available at http://www.startssl.com/certs/ca.pem, in PEM format. Certificates contain public information and CAs always make them available for download.

Step 2. Convert the root certificate to DER format

This can be done with help of the openssl toolkit, where ca.pem is the original certificate filename in PEM format, and ca.der the filename to output, in DER format (which the Java keytool utility can understand). If you were able to obtain the root certificate in DER format, skip this step.

openssl x509 -in ca.pem -inform pem -out ca.der -outform der

Step 3. Validate the root certificate content

Ensure that the Java keytool can parse the certificate and display its content:

keytool -v -printcert -file ca.der

Step 4. Import the root certificate into the JVM trust store

Enter the following command where $JAVA_HOME is a shell environment variable that points to your Java installation, e.g. to /usr/lib/jvm/java-7-oracle; for -alias pick some unique name for the certificate in the store:

keytool -importcert -alias startssl -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit -file ca.der

(the default password for the CA store is changeit)

The keytool will prompt you for confirmation, enter yes to complete the operation.

Step 5. Verify that the root certificate has been imported

To do that list the trust store content and filter for the certificate alias (name) with grep:

keytool -keystore "$JAVA_HOME/jre/lib/security/cacerts" -storepass changeit -list | grep startssl

You will now be able to make secure SSL/TLS connections to servers which have a certificate signed by the CA which we just imported.