Tomcat - Install SSL Certificate

Dec 17, 2024

Tomcat - Install SSL Certificate

Introduction

This article will go over how to install and configure your SSL certificate in Tomcat. You will need either a Personal Information Exchange (.pfx) or a Java Keystore (.jks) file to configure your server. To get a .pfx file, order an SSL certificate. To get a .jks file, follow our Java Keytool - Create Keystore instructions and provide your own CSR during the ordering process.

Install & Configure a Java Keystore (.jks)

You can watch the video below for a tutorial.

Or, you can check the step by step guidelines below. 
 

1. Open the Tomcat server.xml file in a text editor (this is usually located in the conf folder of Tomcat's home directory).
   
   Find the connector that will be secured with the new keystore and uncomment it if necessary (it is usually a connector with port 443 or 8443 like the example below).
   
   Specify the correct keystore filename and password in your connector configuration. When you are done your connector should look something like this:
   
   <Connector port="443" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="100" scheme="https" secure="true" SSLEnabled="true" clientAuth="false" sslProtocol="TLS"keyAlias="server" keystoreFile="/home/user_name/your_site_name.jks" keystorePass="your_keystore_password" /> 
2. Save your changes to the server.xml file.
    
3. Restart Tomcat.
   
   Note: By default Tomcat will look for your Keystore with the file name .keystore in the home directory with the default password changeit. The home directory is generally /home/user_name/ on Unix and Linux systems, and C:\Documents and Settings\user_name\ on Microsoft Windows systems.

Install & Configure a Personal Information Exchange (.pfx)

1. Retrieve the .pfx file to be installed on your server.
    
2. Save the .pfx file in your Tomcat server location.
    
3. Update the SSL section of the server.xml configuration file with the following information:
   
   <Connector port="443" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="100" scheme="https" secure="true" SSLEnabled="true" clientAuth="false" sslProtocol="TLS" keystoreFile="conf/mydomain.pfx" keystorePass="your_keystore_password" keystoreType="PKCS12"/> 
4. Restart Tomcat for your new certificate to take effect.
    

Tomcat Errors

1. java.io.IoException: keystore was tampered with, or password was incorrect
   
   Incorrect Password
   This error may occur during installation. You may receive this error message if the password is entered into the Connector className instead of the factory className. Enter the password into the correct field to resolve the error.
   
   If you cannot remember your password then your certificate must be reissued.
   
   Keystore Tampered With
   If the password is entered properly the issue may be with the keystore. Check if the correct keystore alias was used and if the keystore exists. If the key store is corrupted then a new keystore needs to be created, a new private key generated, and the certificate reissued.
2. java.security.UnrecoverableKeyException: Cannot recover key
   
   This error occurs when the keystore and keyEntry passwords are different. To resolve this issue, you must remove all traces of the past certificate and request the file.
   
   You must generate a new keystore, keyEntry and CSR. You must also specify the same password for the keystore and the keyEntry.
3. java.security.cert.CertificateParsingException: signed overrun, bytes = 84
   
   This error may occur when the -alias parameter is omitted from the import command. Ensure you import the certificate into the keystore using the command:
   
   keytool -import -alias [keyentry_friendly_name] -trustcacerts -file mycert.crt -keystore [keystore_name]
   Be sure to specify the correct keystore name and keyEntry alias (friendly name).