Easy Way to Replace or Install Apache Tomcat SSL Certificate

0

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.

Beginng-the-Keystore-Explorer-installation Easy Way to Replace or Install Apache Tomcat SSL Certificate

Beginning the Keystore Explorer installation

Associate-common-Java-and-keystore-file-types-with-Keystore-Explorer Easy Way to Replace or Install Apache Tomcat SSL Certificate

Associate common Java and keystore file types with Keystore Explorer

Select-a-destination-directory Easy Way to Replace or Install Apache Tomcat SSL Certificate

Select a destination directory

Choosing-shortcut-creation-options Easy Way to Replace or Install Apache Tomcat SSL Certificate

Choosing shortcut creation options

Keystore-Explorer-installation-finishes Easy Way to Replace or Install Apache Tomcat SSL Certificate

Keystore Explorer installation finishes

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.

Opening-a-keystore-file-in-Keystore-Explorer Easy Way to Replace or Install Apache Tomcat SSL Certificate

Opening a keystore file in Keystore Explorer

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.

Checking-the-keystore-along-with-expiry-status-of-the-SSL-certificate Easy Way to Replace or Install Apache Tomcat SSL Certificate

Checking the keystore along with expiry status of the SSL certificate

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

Keystore-Explorer-SSL-certificate-options Easy Way to Replace or Install Apache Tomcat SSL Certificate

Keystore Explorer SSL certificate options

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

Download-the-OpenSSL-Windows-installer Easy Way to Replace or Install Apache Tomcat SSL Certificate

Download the OpenSSL Windows installer

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.

Certficate-files-and-private-key-before-combining Easy Way to Replace or Install Apache Tomcat SSL Certificate

Certficate files and private key before combining


Running-OpenSSL-to-combine-the-files-needed-to-import-into-the-keystore Easy Way to Replace or Install Apache Tomcat SSL Certificate

Running OpenSSL to combine the files needed to import into the keystore

The utility will ask to create an export password.

Enter-an-export-password Easy Way to Replace or Install Apache Tomcat SSL Certificate

Enter an export password

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

Importing-the-keypair-using-Keystore-Explorer Easy Way to Replace or Install Apache Tomcat SSL Certificate

Importing the key pair using Keystore Explorer

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.

Choose-the-keypair-type Easy Way to Replace or Install Apache Tomcat SSL Certificate

Choose the key pair type

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

Choose-the-key-pair-alias Easy Way to Replace or Install Apache Tomcat SSL Certificate

Choose the key pair alias

Select Yes to overwrite.

Overwrite-the-existing-key-pair Easy Way to Replace or Install Apache Tomcat SSL Certificate

Overwrite the existing key pair

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

Create-a-new-key-pair-password Easy Way to Replace or Install Apache Tomcat SSL Certificate

Create a new key pair password

The import should be successful.

Import-of-the-new-key-pair-is-successful-in-the-keystore Easy Way to Replace or Install Apache Tomcat SSL Certificate

Import of the new key pair is successful in the keystore

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

The-status-of-the-SSL-certificate-in-the-keystore-is-now-showing-as-current Easy Way to Replace or Install Apache Tomcat SSL Certificate

The status of the SSL certificate in the keystore is now showing as 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.