Commandline Java Truststore Cert Setup
Originally posted on the DevObsessed blog at https://www.devobsessed.com/post/commandline-java-truststore-cert-setup
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 google.com 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 ~/.certsthen
cd ~/.certs
Step 3 - Export the cert to a file using:
openssl s_client -servername google.com -connect google.com:443 /dev/null | openssl x509 -inform PEM -outform DER -out google.com.cer
Step 4 - Import the cert to the Java cacerts truststore:
“$JAVA_HOME”/bin/keytool -keystore “$JAVA_HOME”/lib/security/cacerts -importcert -alias google.com -file google.com.cer
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!