dev@cloudburo

Install Letsencrypt Certificate in the Java JDK Keystore on OSX

Posted on 03.Jun 2018 | Tags quicktips javatutorial

The following article gives a short introduction, how to import a root certificate into the Java JDK keystore on a Mac OSX. The example is based on the import of the ISRG Root X1 certificate, which is a very new certificate and not broadly trusted yet. Actually they do a cross signing of their intermediate certificate with IdenTrust (which is already widely trusted) in order to relief this short-coming.

Anyway the import sequence may help you in case you want to install another certificate in a same way.

Assumption is that we have SSLHandshake Exception due to the missing ISRG certificate. In my example a gradle build was failing due to missing certificate. 


  Could not resolve all dependencies for configuration ':compileClasspath'. 
  > Could not resolve com.aspose:aspose-cells:17.9. 
    Required by: 
        project : > com.edorasware.one:edoras-one-starter:2.0.4 ... 
     > Could not resolve com.aspose:aspose-cells:17.9. 
        > Could not get resource ' https://artifact.aspose.com/repo/com/aspose/aspose-cells/17.9/aspose-cells-17.9.pom'. 
           ... 
              > sun.security.validator.ValidatorException: PKIX path building failed:  


  sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

The certificate of the https://aspose.com repository is a Let’s Encrypt Authority X3, which is based on DST Root CA X3. You get the below window when you check the certificate of the site in the browser (Chrome screenshot)



So we have to load the Let’s Encrypt certificates into the Java keystore
cacerts on our machine, to make the certificate path accessible.

The whole signing setup is described here: https://letsencrypt.org/certificates/




Step 1: Set-up JAVA_HOME and install wget

First of all it’s advisable to set up the JAVA_HOME correctly on your Mac OSX machine, by using the java_home executable ( Stackoverflow). Add the following to the .bash_profile 


  export JAVA_HOME=$(/usr/libexec/java_home)

For running the import script we require wget. Assuming you install OSX tools via brew - the so-called missing package manager for the Mac - run the following command 


  brew install wget

Step 2: Do some keystore checks

First of check if the ISRG certificate is already installed in your keystore. The java JDK keystore can be found under the JAVA_HOME directory in the following folder jre/lib/security/cacerts 


  ~ felix> keytool -v -list -keystore $JAVA_HOME/jre/lib/security/cacerts | grep ISRG 
  Enter keystore password:  changeit

changeit is the default password of the Java JDK installation. Nothing will be given back. As for example looking for existing certificate (i.e. the in this example the cross signing certificate of Digital Signature Trust Co.), will be shown. By storing the full output in a file, provides you with an overview of all installed certificates in your Java JDK keystore. 


  ~ felix> keytool -v -list -keystore $JAVA_HOME/jre/lib/security/cacerts | grep DST 
  Enter keystore password:  changeit 
  Issuer: CN=DST Root CA X3, O=Digital Signature Trust Co. 
       [URIName: http://crl.identrust.com/DSTROOTCAX3CRL.crl] 
  Issuer: CN=DST Root CA X3, O=Digital Signature Trust Co. 
       [URIName: http://crl.identrust.com/DSTROOTCAX3CRL.crl] 
  Issuer: CN=DST Root CA X3, O=Digital Signature Trust Co. 
       [URIName: http://crl.identrust.com/DSTROOTCAX3CRL.crl] 
  Issuer: CN=DST Root CA X3, O=Digital Signature Trust Co. 
       [URIName: http://crl.identrust.com/DSTROOTCAX3CRL.crl]

As we have seen, the certificate is missing, so let’s run the following script

Step 3: Run the import script

The script will fetch from the letsencrypt.org web site the certificate information via wget and adds it to the cacerts keystore via the keytool.




Run the script, which get all the necessary certificate artefacts from the letsencrypt server and installs in your keystore. So script is based on the following implementation and described by letsencrypt here.


Step 4: Check the successful Import

Run the list command once again, you will now get back result output 


  ~ felix> keytool -v -list -keystore $JAVA_HOME/jre/lib/security/cacerts | grep ISRG 
  Enter keystore password:  changeit 
  Issuer: CN=ISRG Root X1, O=Internet Security Research Group, C=US 
  Issuer: CN=ISRG Root X1, O=Internet Security Research Group, C=US 
  Issuer: CN=ISRG Root X1, O=Internet Security Research Group, C=US


Retry you java application or build, which should now be executed.


This blog entry was fully produced within Evernote and published using the Cloudburo Publishing Bot .

comments powered by Disqus