Knowledge Base

Overview

By the end of this article your existing certificate will be in a keystore Tomcat can read, and Tomcat will accept HTTPS connections on your chosen port. It covers the supported Apache Tomcat versions; the certificate material you need in Personal Information Exchange (PFX) or Privacy Enhanced Mail (PEM) form; converting that material to Public Key Cryptography Standards #12 (PKCS12) with OpenSSL; configuring the connector in conf/server.xml using SSLHostConfig, including Server Name Indication (SNI) for multiple certificates; verifying the result; and, optionally, using a Java KeyStore (JKS) instead of PKCS12.

What is SSLHostConfig?

SSLHostConfig is the Tomcat configuration element that holds the TLS settings and certificate for a host inside a connector. From Tomcat 9.0 onward it is the recommended way to configure HTTPS, replacing the legacy style of putting keystore attributes directly on the connector. Each connector can hold several SSLHostConfig elements, which is what allows one port to serve several certificates through Server Name Indication (SNI).

Applies to

Prerequisites

Have the following in place before you begin:

• Administrative access to the Tomcat server, so you can edit conf/server.xml and restart Tomcat.
• Certificate material in one of these forms: Personal Information Exchange (PFX) or .p12, which are both Public Key Cryptography Standards #12 (PKCS12) files, or a separate certificate and private key in Privacy Enhanced Mail (PEM) form (.crt and .key).
• OpenSSL installed, if you need to convert PEM files to PKCS12.
• A secure method for storing and handling the certificate passwords.

Tomcat reads PKCS12 (.p12 or .pfx) and Java KeyStore (JKS) keystores. Internet Information Services (IIS) exports PFX, which is already PKCS12; Apache HTTP Server keeps separate .crt and .key files, which need conversion first.

Step 1 — Convert the certificate to PKCS12

Perform this step only if your certificate and private key are separate Privacy Enhanced Mail (PEM) files (.crt and .key). Combine them into a single Public Key Cryptography Standards #12 (PKCS12) file with OpenSSL:

openssl pkcs12 -inkey private.key -in SectigoSSLserver.crt -export -out pkcs12keypair.p12

Replace the file names and paths to match your environment. You are prompted for the PEM pass phrase if the private key is encrypted, then for an export password for the new PKCS12 file. Keep that export password — you enter it in conf/server.xml in Step 2.

If your certificate came from Internet Information Services (IIS) as a Personal Information Exchange (PFX) file, it is already PKCS12. Go to Step 2.

Step 2 — Configure the HTTPS connector in server.xml

Copy the Public Key Cryptography Standards #12 (PKCS12) file, for example pkcs12keypair.p12, to the Tomcat server, then open conf/server.xml and define the HTTPS connector using SSLHostConfig with a Certificate element. Use one configuration style per connector — do not mix legacy attributes such as keystoreFile and keystorePass with SSLHostConfig.

Example 1 — PKCS12 keystore (.p12 or .pfx)

<Connector port="8443"
           protocol="org.apache.coyote.http11.Http11NioProtocol"
           SSLEnabled="true">
  <SSLHostConfig>
    <Certificate certificateKeystoreFile="C:/keystore/newstore.p12"
                 certificateKeystoreType="PKCS12"
                 certificateKeystorePassword="changeit" />
  </SSLHostConfig>
</Connector>

Example 2 — PEM files (certificate, key, and chain)

<Connector port="8443"
           protocol="org.apache.coyote.http11.Http11NioProtocol"
           SSLEnabled="true">
  <SSLHostConfig protocols="TLSv1.2,TLSv1.3">
    <Certificate certificateFile="conf/server.crt"
                 certificateKeyFile="conf/private.key"
                 certificateChainFile="conf/chain.crt" />
  </SSLHostConfig>
</Connector>

Example 3 — Multiple certificates with SNI

Server Name Indication (SNI) lets one connector present a different certificate for each hostname. Give the connector a defaultSSLHostConfigName and add one SSLHostConfig per hostname.

<Connector port="8443"
           protocol="org.apache.coyote.http11.Http11NioProtocol"
           SSLEnabled="true"
           defaultSSLHostConfigName="example.com">

  <SSLHostConfig hostName="example.com">
    <Certificate certificateKeystoreFile="C:/keystore/example.p12"
                 certificateKeystoreType="PKCS12"
                 certificateKeystorePassword="changeit" />
  </SSLHostConfig>

  <SSLHostConfig hostName="api.example.com">
    <Certificate certificateKeystoreFile="C:/keystore/api.p12"
                 certificateKeystoreType="PKCS12"
                 certificateKeystorePassword="changeit" />
  </SSLHostConfig>

</Connector>

Save conf/server.xml when the connector is complete.

How to verify the configuration

Confirm the HTTPS connector is working after restarting Tomcat:

• Restart Tomcat and confirm the HTTPS connector starts with no errors in the logs.
• Browse to https://<hostname>:8443/, or your configured HTTPS port, and confirm the certificate presented is the one you installed.
• If you configured Server Name Indication (SNI), test each hostname separately, for example https://example.com:8443/ and https://api.example.com:8443/, and confirm the correct certificate is returned for each name.

Troubleshooting

Optional — use a JKS keystore instead of PKCS12

If your environment requires a Java KeyStore (JKS) rather than a Public Key Cryptography Standards #12 (PKCS12) file, create a JKS keystore and import the PKCS12 keypair with the keytool command. Then reference it in conf/server.xml through SSLHostConfig: set certificateKeystoreFile to your .jks file and certificateKeystoreType to JKS.

Frequently asked questions