Easy Way to Replace or Install Apache Tomcat SSL Certificate

In working with a client recently, I was tasked with replacing an SSL certificate in Apache Tomcat, specifically for a JIRA install. If you have ever done this before, you know that it can be a royal PITA as there are specific commands and specific certificate types that you have to have in order to make sure the command line options do not bomb out on you when you are updating the certificate. I want to show you an easy way to replace or install apache tomcat SSL certificate for Jira or any other Apache Tomcat based application.

Easy Way to Replace or Install Apache Tomcat SSL Certificate

Instead of painstakingly maneuvering around the myriad of commands to get a new SSL certificate in place, there is an easy way to do this with a handy GUI utility. If you aren’t familiar, most if not all Apache Tomcat applications make use of a “keystore” file that houses the private key and certificate chain that is read when the Apache Tomcat Java applet starts.  This file is usually found in the “Home” directory of the user that is running the Tomcat application.

Official documentation with many applications such as Atlassian Jira, have you use a combination of openssl commands and the keytool command.  The keytool command is the command line way to interact with the keystore file.  However, the keytool command can be difficult to decipher correct syntax, and I have found many discrepancies between documentation, depending on the source of the documentation as to the correct syntax of keytool.  Is there an easy way, or a better way?

Let me introduce you to a GUI tool that makes interacting with the keystore file MUCH easier!  It is called Keystore Explorer.  It is self described this way:

KeyStore Explorer is an open source GUI replacement for the Java command-line utilities keytool and jarsigner. KeyStore Explorer presents their functionality, and more, via an intuitive graphical user interface.

I found the above statement to be extremely accurate.  Let’s look at installing this little gem and using it for replacing an SSL certificate in the keystore for use with Apache Tomcat.  Download the utility here: http://keystore-explorer.org/downloads.html

After downloading (a small .exe file), the installer is a basic “next, next, finish” operation.  Below is a quick run through.

Download the Keystore File and Open with Keystore Explorer

Even if we are using a Linux platform as the Apache Tomcat server, we can still make use of the Windows based Keystore Explorer.  Simply download the “keystore” file (generally named just that and may be hidden in the user’s home directory).  I connected to my server via WinSCP and downloaded it to a temporary working directory on my Windows workstation.  Then using Keystore Explorer, you can open this keystore file to view/edit, etc.  Again, the keystore file contains the SSL certificate that needs replacing if expired/expiring.

Notice, the tomcatapp alias is showing a “red dot”.  This is under the expiry status column.  This is a visual way to see the SSL certificate is indeed expired.

As you can see below, there are a wealth of options that are found inside the utility including Certificate Chain Details, Private Key Details, etc.

Use OpenSSL to Combine Certificates and Private Key

Before using Keystore Explorer, we need to do a bit of work on the certificate bundle received from the CA.  With Jira and other Tomcat applications that read the keystore, we need to present the server certificate, CA certificate, and private key combined in the keystore.  To do that, we can use the OpenSSL command line utility to easily combine the files.  This is a command line operation, however, it is the only command line tinkering that we need to do.  The command to do what we need is very simple as well.  First, you can download the OpenSSL Windows installation here:  http://gnuwin32.sourceforge.net/packages/openssl.htm

After installation, use OpenSSL to combine the server certificate, CA certificate, and private key into a single file.  We can do that with a simple one liner.

openssl pkcs12 -export -out <combined cert name> -inkey <private key file> -in <server certificate> -certfile <CA certificate>

The utility will ask to create an export password.

Click the little set of keys to the right in the tools menu.  This is the Import Key Pair option.

Choose the type of Key Pair Type.  We choose the PKCS #12 as the type since this is the type of file we created wit the OpenSSL command line utility.

Enter an alias for the key pair.  If you choose the same alias name as the expired entry, it will overwrite it for you.

Select Yes to overwrite.

You will be prompted to enter a New Key Pair Entry Password.

The import should be successful.

You now see in the Expiry Status column, we have a “green dot” which means the SSL certificate is current.

Now, all we have left to do is save the keystore file.  Then upload the keystore back to the Linux server hosting Apache Tomcat.

Important Rename the current keystore file to have a backup to go back to in case you need to revert the changes or something was not correct in the certificate configuration.

One final step is to restart your Apache Tomcat service on the server so it will pick up the new certificate.  The keystore is read at startup so this needs to be refreshed by cycling services.

Thoughts

Replacing SSL certificates in Apache Tomcat can be challenging.  However, by using the great GUI utility – Keystore Explorer, this process is much easier than hassling with command line options and parameters.  It also alleviates a lot of room for error.  This provides an Easy Way to Replace or Install Apache Tomcat SSL Certificate.  The next time you have an SSL certificate expiring on your Apache Tomcat server application, be sure and check out the Keystore Explorer utility.