• Prerequisites
• Java keystores
  • PKCS7
  • PEM
  • PKCS12
• APR-based installation
• Apply the changes
• Troubleshooting
  • View keystore content
  • Extract Private key from keystore
  • Proprietary keystore format warning

Prerequisites

Java keystores

PKCS#7

Step 1: Upload SSL files

Upload the PKCS#7 certificate file on the server. Then, import it using the following command:

keytool -import -trustcacerts -alias tomcat -file certificate.p7b -keystore yourkeystore.jks

Where:

• tomcat is the actual alias of your keystore
• certificate.p7b is the actual name/path to your certificate file
• yourkeystore.jks is the actual name/path to the keystore file

Make sure the certificate file has the same alias used for creating the keystore. Otherwise, the “Input not an X.509 certificate” error may take place.

After you have imported successfully, you should receive the following output:

Certificate reply was installed in keystore

Step 2: Edit SSL Configuration

In the next step, you will need to modify the connector for the default port 8443 or 443.

The modification should be done in the ‘Tomcat installation directory’/conf/server.xml file. You can find the location of the directory containing the server.xml configuration file by issuing this command:

sudo find / -ipath '*tomcat*server.xml'

It will most likely be in /opt/tomcat/conf/server.xml or /etc/tomcat/server.xml

Here is an example of a JSSE connector for port 443 using the HTTP/1.1 protocol with TLS up to 1.3 enabled:

Where:

• /opt/tomcat/ssl/yourkeystore.jks is the absolute path and actual name of the keystore file
• keystore_password is the actual password for your keystore

Step 3: Apply changes

Once done, please restart Tomcat in order to apply the changes. If you are not quite sure about the steps to reproduce, feel free to jump to this section to apply the changes and verify SSL installation.

PEM

The most challenging, yet still common, way of installing an SSL certificate on Tomcat is by using separate PEM-formatted SSL certificates.

Step 1: Prepare the files

This method requires you to have each of the certificates saved in separate files:

1. CA root certificate.
2. CA second intermediate certificate (optional and can be omitted if your CA bundle contains only 1 intermediate certificate).
3. CA intermediate certificate.
4. End-entity certificate for your domain.

The order of the certificate will be as follows for the most frequently used PositiveSSL certificate:

Note: You can find more CA Bundles here.

Note: The “AAA Certificate Services” is only installed if you chose the CA Bundle containing the cross-signed certificate.

The above list is composed in reverse order on purpose as this is the exact order in which the certificates should be imported to the keystore. You can download the certificate files from your Namecheap account along with the CA bundle. Here is the dedicated page with download links if you only need the CA bundle. It may come in handy if you encounter the “keytool error: java.langException: Failed to establish chain from reply” error.

Step 2: Import the files

Follow the below steps in the given order to import the files properly.

Import the root certificate by running:

keytool -import -trustcacerts -alias root -file root.crt -keystore yourkeystore.jks

Where:

• root is the alias of the imported CA root certificate
• root.crt is the actual name/path of your CA root certificate
• yourkeystore.jks is the actual name/path of the keystore file

Note: During import of the CA root certificate, you may be prompted with the following message.

Certificate already exists in system-wide CA keystore under alias <aliasname>
Do you still want to add it to your own keystore? [no]:

Disregard the warning and confirm certificate import with submitting y.

Import the second intermediate certificate:

keytool -import -trustcacerts -alias intermediate2 -file intermediate_2.crt -keystore yourkeystore.jks

Where:

• intermediate2 is the alias of the imported second intermediate CA certificate
• intermediate_2.crt is the actual name/path of your second intermediate CA certificate

Import the first intermediate certificate:

keytool -import -trustcacerts -alias intermediate1 -file intermediate_1.crt -keystore yourkeystore.jks

Where:

• intermediate1 is the alias of the imported first intermediate CA certificate
• intermediate_1.crt is the actual actual name/path of your first intermediate CA certificate

After the successful import of each of the above certificates, you should receive the following output:

Certificate was added to keystore

Import the end-entity certificate for your domain:

keytool -import -trustcacerts -alias tomcat -file certificate.crt -keystore yourkeystore.jks

Where:

• tomcat is the actual alias of your keystore. The alias for your end-entity certificate should be the same as the one you used when creating the keystore with the Private key. If you did not specify the alias during the keystore creation, the default value will be mykey.
• certificate.crt is the actual actual name/path of your end-entity certificate file.

After import of the end-entity certificate, the below message will be prompted:

Certificate reply was installed in keystore

Step 3: Edit the connector

In the next step, you will need to modify the connector for the default port 8443 or 443.

The modification should be done in the ‘Tomcat installation directory’/conf/server.xml file. You can find the location of the directory containing the server.xml configuration file by issuing the below command:

sudo find / -ipath '*tomcat*server.xml'

Most likely, it will be in /opt/tomcat/conf/server.xml or /etc/tomcat/server.xml

Here is an example of the JSSE connector for port 443 using HTTP/1.1 protocol along with TLS up to 1.3 protocol versions:

Where:

• /opt/tomcat/ssl/yourkeystore.jks is the absolute path and actual name of the keystore file
• keystore_password is the actual password for your keystore

Step 4: Enforce the changes

Once done, please restart Tomcat in order to apply changes.If you are not quite sure about the steps to reproduce, you can go to this section to apply the changes and verify SSL installation.

PKCS#12

If you have no APR enabled on Apache Tomcat, this method of SSL installation is the optimal balance between the PKCS#7 and PEM import methods. PKCS#12 is a certificate standard when all the required parts (end-entity certificate for the hostname, CA bundle, and the Private key) are stored in the same file.

Step 1: Prepare the SSL files

Feel free to jump right to the next part if you already have a PKCS#12 (.pfx/.p12) certificate. If you do not have one, convert the corresponding files first.

Step 2: Modify the keystore

PKCS#12 file is considered as a keystore in itself. Thus, you will just need to specify the path to the PKCS#12 file in the keystoreFile directive. The process is pretty much the same as for the PKCS7 and PEM standards.

The modification should be done in the ‘Tomcat installation directory’/conf/server.xml file. You can find the location of the directory containing the server.xml configuration file by issuing the below command:

sudo find / -ipath '*tomcat*server.xml'

It will most likely be in /opt/tomcat/conf/server.xml or /etc/tomcat/server.xml.

Here is an example of PKCS#12 JSSE connector for port 443 using HTTP/1.1 protocol along with TLS up to 1.3 protocol versions:

Where:

• /opt/tomcat/ssl/somefile.pfx is the absolute path and actual name for the PKCS#12 certificate
• password_from_your_pfx is the actual password for the PKCS#12 file

Step 3: Complete the SSL installation

Once done, please restart Tomcat in order to apply changes. If you are not quite sure about the steps to reproduce, skip to this section to apply the changes and verify SSL installation.

APR-based installation

Most Linux distributions ship packages for APR out-of-the-box. Still, additional libtcnative, libapr1-dev and libssl-dev packages are required for APR to function properly with Tomcat (if you do not have installed them yet). Tomcat Native libraries also need to be compiled. We do not address this topic in this guide; it’s assumed you already have APR set up with Tomcat. If no APR is set up on your Apache Tomcat, check out this installation method.

Step 1: Upload files

First, upload the certificate, the Private key, and the CA bundle (if the Certificate Signing Request was generated elsewhere) to the server.

Step 2: Configure the connector

Next, modify the existing connector for the default port 8443 or 443. The modification should be done in the ‘Tomcat installation directory’/conf/server.xml file.

You can find the location of the directory containing the server.xml configuration file by issuing below command:

sudo find / -ipath '*tomcat*server.xml'

It will most likely be in /opt/tomcat/conf/server.xml or /etc/tomcat/server.xml

Here is an example of the APR connector for the port 443 using HTTP/1.1 protocol along with TLS1.1 & TLS1.2 enabled:

Where:

• /opt/tomcat/ssl/cert.crt is the absolute path and actual name of the PEM-formatted certificate
• /opt/tomcat/ssl/bundle.ca-bundle is the absolute path and actual name of the CA bundle file
• /opt/tomcat/ssl/private.key is the absolute path and actual name of the Private key file

Important Note: The APR connector requires you to set the SSLCertificateChainFile directive explicitly. It isn’t possible to install the certificate properly with a single file containing both the end-entity certificate and CA bundle chain, like it is usually done on Apache 2.4.8 and above. If only the SSLCertificateFile is set in the connector, the first certificate from the file will be retrieved during handshake, which could possibly trigger the ERR_CERT_AUTHORITY_INVALID error.

Step 3: Apply the changes

Once done, please restart Tomcat in order to apply changes. If you are not quite sure about the steps to reproduce, feel free to jump to this section to apply the changes and verify SSL installation.

Apply the changes

Save the changes and restart Tomcat either via the systemd service if there is any available, like so:

sudo systemctl restart tomcat

Or by using binaries. These will most likely be found in the following location:

However, the location of Tomcat binaries may vary between installations. You can find the location of both the startup and shutdown binary files by executing the below command:

sudo find / -ipath '*tomcat*\/s[h t]*.sh'

You will have 2 files in the output. They should be used for restarting Tomcat. Run the below commands in the following order to restart the server:

Where:

• /opt/tomcat/bin/shutdown.sh is the absolute path to the shutdown.sh file from the previous output
• /opt/tomcat/bin/startup.sh is the absolute path to the startup.sh file from the previous output

Once restarted, feel free to check the SSL installation using this online tool.

Troubleshooting

View keystore content

Use this command to check the imported decoded certificates in the keystore. For each correctly-imported certificate, you will see its details in a keystore entry. The Private key entry is displayed in the list as well:

keytool -list -keystore yourkeystore.jks -v

The output should be similar to the below listing:

To view the keystore content with respective encoded certificates in plain text (RFC-style), use the below command:

keytool -list -rfc -keystore yourkeystore.jks

The output should be similar to the below listing:

Extract Private key from keystore

It is not possible to extract the Private key from a keystore directly, but there is a workaround with OpenSSL. You will need to:

1. Convert the Java keystore file into the PKCS#12 standard file;
2. Get the PKCS#12 file converted into a separate PEM encoded Private key file, i.e. export the Private key;
3. View the content of the newly created Private key file.

Follow the below commands to start the process:

1. keytool -importkeystore -srckeystore yourkeystore.jks -destkeystore somefile.pfx -srcstoretype JKS -deststoretype PKCS12 -deststorepass password_from_your_pfx


Note: Some Java versions running Tomcat (or another servlet container using keytool as a Private/Public keys management shell) have different prefered file extensions for PKCS#12 (e.g. older versions like JDK 1.6 and earlier can generate .p12 files). The current stable versions usually generate .pfx files. The file content of .p12 and .pfx files are essentially the same.

2. openssl pkcs12 -in somefile.pfx -out private.key -nocerts -nodes
3. cat private.key

Be aware that the exported Private key may contain additional attributes (such as Bag Attributes or Key Attributes) along with the key code itself. In the output file, feel free to remove the first ~4 lines standing before the -----BEGIN PRIVATE KEY----- tag.

Proprietary keystore format warning

If you have a JDK version older than version 9 installed, the keystore will be generated in the JKS format (which should not be confused with the .jks file extension). The current up-to-date openjdk environment will give the following warning for such a keystore:

The JKS keystore uses a proprietary format. It is recommended to migrate to PKCS12 which is an industry standard format ..."

You can probably disregard the warning and install the certificate as usual. Still, to stay on the safe side, you should probably convert the JKS keystore into the PKCS#12 format for the sake of compatibility. You can use the below command to convert this keystore type:

keytool -importkeystore -srckeystore yourkeystore.jks -destkeystore yourkeystore.jks -deststoretype pkcs12

Where yourkeystore.jks is the actual name/path to your keystore file.

Once done, you can check the keystore type by listing the keystore contents.

The successful output will give a warning stating that the previous keystore in the JKS format was backed up in a separate file:

Migrated "yourkeystore.jks" to PKCS12. The JKS keystore is backed up as "yourkeystore.jks.old".