Commandline Java Truststore Cert Setup

Java Security
Originally posted on the DevObsessed blog at

A quick lesson learned in consulting is that most every software organization has custom tailored setups in a variety of ways. As consultants on our first days at a new client we'll begin gathering environmental information in all forms. We'll see a variety of programming languages, API gateways, infrastructure as code utilities, databases, and more. In our quest to quickly build confidence and cohesion between ourselves and our new partner team, we'll inevitably dive into project onboarding & setup instructions. Our goals are to get up and running efficiently while updating the steps involved along the way.

Oftentimes setting up trust for enterprise self-signed certs is one of the initial setup steps to connect to APIs, npm/artifactory repositories, and git repos. For JVM based systems (which could be using Java, Kotlin, Groovy, or other JVM langs), this requires configuring the local Java Truststore. You'll know that this setup is needed if hitting system URLs gives a dreaded Java SSLHandshakeException. The error message received will list a domain URL that is not trusted at some point in the cert handshake chain.

The Bad

How many setup instructions go something like this:

1. Hit some site in a browser
2. Click on some browser icon to open some cert menu, and click to export the cert to somewhere on the file system

Possibly from a Word doc with pictures. Or a wiki page with vague missing pieces. And it is almost always hard to follow and brittle.

Then the next step is to import this and other certs into the java cacerts file.

Or maybe one lead developer will get everything setup, and copy/email/share the cacerts file around the team. With the added confusion that nobody will now know how to add new certs in the future.

At DevObsessed, we’re obsessed with simplifying onboarding steps. We want to avoid documents of pictures and instructions to follow, and especially avoid setting things up without instructions on how to modify and maintain it in the future. ‍

The Good

Exporting and Importing certs can be done via the command-line. For some reason this is often difficult to find and piece together online, so here’s the info all in one place to help your team improve your onboarding instructions. These steps have been fine-tuned over the past 4-5 years of use, and are especially helpful on client locked-down Windows laptops.

Step 1 - Identify the server/URL for the cert. Often the first site to use is the internal NPM/Artifactory repo. For our example we’ll use but replace this with your own servername to load your own certs.

Step 2 - Create a folder locally to hold these certs, even if temporarily. For example:

mkdir ~/.certs
cd ~/.certs

Step 3 - Export the cert to a file using:

openssl s_client
-servername -connect /dev/null | openssl x509 -inform PEM -outform
DER -out

Step 4 - Import the cert to the Java cacerts truststore:

“$JAVA_HOME”/bin/keytool -keystore “$JAVA_HOME”/lib/security/cacerts -importcert
-alias -file

A couple of notes about this step:
  • the default java cacerts password is changeit
  • if you get an update denied message, and on Windows, then try running in a Git Bash prompt As Administrator
  • or in Windows File Explorer set security on cacerts file to MODIFY for all Users
  • or on Mac/Linux use chmod
  • if keytool is not found, define a JAVA_HOME environment variable (or replace $JAVA_HOME with the full path needed)

Step 5 - Restart your IntelliJ/Eclipe/VSCode IDE, and any network tabs, to ensure you use the updated cacerts file

The Best

That’s it! And now to leave things in a better spot than when you started:

Step 6 - Update your complicated onboarding instructions to these main steps 3 & 4 for each unique self-cert / domain in your environment!