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.