Installing an SSL Certificate on Apache Tomcat

Installing an SSL Certificate on Apache Tomcat

Jessica Moore

Apache Tomcat handles SSL Certificates differently from every other server in this series, because Java applications traditionally expect SSL Certificate material packaged inside a keystore rather than as loose files.

The good news is that modern Tomcat releases accept the widely used PKCS12 format directly and can even read plain SSL Certificate files, so the old Java specific hurdles have largely disappeared. This guide covers Tomcat 9, 10, and 11 using the current SSLHostConfig configuration style.

Understanding Keystore Formats

Tomcat accepts two keystore types. PKCS12 is the industry standard container format, identical to the Personal Information Exchange (PFX) files used on Windows, and it is the recommended choice for new configurations. The older Java KeyStore (JKS) format still works but offers no advantage, and the Java platform itself has treated PKCS12 as the default for years.

If your SSL Certificate came from a Windows server as a PFX file, Tomcat can use it directly with no conversion, since PFX and PKCS12 are the same format under different names. Learn About PFX Files 🔗

Prerequisites and Required Files

You need administrative access to the Tomcat server with permission to edit the server.xml configuration file and restart the service. You also need your issued SSL Certificate file and the ca-bundle containing the Intermediate Certificates, both available in the tracking system. View Our Tracking & SSL Management 🔗

The Private Key completes the set. It was created alongside your Certificate Signing Request (CSR) and exists only where it was generated, since Trustico® does not retain Private Keys after issuance. Learn About Generating a CSR 🔗

Converting Separate Files into a PKCS12 Keystore

When your material exists as separate files, a single OpenSSL command packages the SSL Certificate, the Private Key, and the chain into one keystore. Run it in the directory containing all three files.

openssl pkcs12 -export -inkey yourdomain.key -in yourdomain.crt -certfile yourdomain.ca-bundle -out yourdomain.p12

OpenSSL prompts for an export password, which protects the new keystore and will be referenced in the Tomcat configuration. Including the ca-bundle through the certfile option matters, because a keystore built without the Intermediate Certificates produces a server that passes desktop browser checks while failing on mobile devices. Learn About Intermediate Certificates 🔗

Configuring the HTTPS Connector in server.xml

Tomcat configures HTTPS through a Connector element in the conf/server.xml file. Older guides place the keystore details directly on the Connector as keystoreFile and keystorePass attributes, but Tomcat 9 and later prefer the SSLHostConfig structure, which supports Server Name Indication (SNI) and multiple SSL Certificates cleanly.

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true" maxThreads="150">
    <SSLHostConfig protocols="TLSv1.2,TLSv1.3">
        <Certificate certificateKeystoreFile="conf/yourdomain.p12"
                     certificateKeystoreType="PKCS12"
                     certificateKeystorePassword="YourKeystorePassword" />
    </SSLHostConfig>
</Connector>

Tomcat can alternatively reference the loose files directly, skipping keystore creation entirely. This style suits administrators coming from an Apache HTTP Server background.

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true" maxThreads="150">
    <SSLHostConfig protocols="TLSv1.2,TLSv1.3">
        <Certificate certificateFile="conf/yourdomain.crt"
                     certificateKeyFile="conf/yourdomain.key"
                     certificateChainFile="conf/yourdomain.ca-bundle" />
    </SSLHostConfig>
</Connector>

Tip : Tomcat listens on port 8443 by default, while browsers expect HTTPS on port 443. Production deployments commonly either change the Connector port to 443, place a reverse proxy such as NGINX in front of Tomcat, or redirect the port at the firewall. Running Tomcat itself on port 443 on Linux requires either root privileges or a capability grant to bind the privileged port.

Once the Connector is in place and the port question is settled, the configuration is ready to load.

Restarting Tomcat and Verifying the Installation

Restart the service so the new Connector configuration loads. On most Linux installations the command is sudo systemctl restart tomcat, with the exact service name depending on how Tomcat was installed.

Watch the catalina.out log during startup, because Tomcat reports keystore problems there immediately. A clean start followed by a successful HTTPS connection in a browser confirms the basics, and an external scan confirms the full chain reaches fresh clients correctly. Trustico® provides free checking tools for this purpose. Explore Our Trustico® SSL Tools 🔗

Troubleshooting Common Installation Problems

A keystore was tampered with or password was incorrect message in the log means the certificateKeystorePassword value in server.xml does not match the export password set when the keystore was created. Correct the password in the configuration, or rebuild the keystore if the password has been lost, since keystore passwords cannot be recovered.

Chain warnings on mobile devices while desktop browsers stay quiet mean the keystore was built without the ca-bundle. Rebuild it with the certfile option included and restart Tomcat.

An alias or key mismatch during keystore creation means the Private Key does not pair with the SSL Certificate, usually because the CSR was regenerated after submission. A reissue against the current CSR resolves the mismatch cleanly. Learn About Reissuing Your SSL Certificate 🔗

Professional Installation Assistance

Tomcat deployments range from single application servers to clustered environments behind load balancers, and the keystore layer adds a step that other platforms do not have.

Trustico® offers a Premium Installation service where our technicians complete the installation on your behalf. Discover Our Premium Installation Service 🔗

Back to Blog

Most Popular Questions

Frequently asked questions covering SSL Certificate installation on Apache Tomcat, including PKCS12 keystore creation, the SSLHostConfig configuration style, direct file references, port 8443 versus port 443 decisions, keystore password limits, and the Trustico® Premium Installation service.

Choosing Between PKCS12 and Java KeyStore (JKS) Formats

PKCS12 is the industry standard container format, identical to the Personal Information Exchange (PFX) files used on Windows, and it is the recommended choice for new configurations. The older Java KeyStore (JKS) format still works but offers no advantage, and the Java platform itself has treated PKCS12 as the default for years.

Building a PKCS12 Keystore from Separate Files

A single OpenSSL command packages the SSL Certificate, the Private Key, and the chain into one keystore, protected by an export password that the Tomcat configuration references. Including the ca-bundle through the certfile option matters, because a keystore built without the Intermediate Certificates passes desktop browser checks while failing on mobile devices.

Configuring the HTTPS Connector with SSLHostConfig

Tomcat 9 and later prefer the SSLHostConfig structure inside conf/server.xml over the older keystoreFile attributes, because it supports Server Name Indication (SNI) and multiple SSL Certificates cleanly. Tomcat can alternatively reference the loose SSL Certificate, Private Key, and chain files directly, skipping keystore creation entirely.

Serving HTTPS on Port 443 Instead of Port 8443

Tomcat listens on port 8443 by default, while browsers expect HTTPS on port 443. Production deployments commonly change the Connector port to 443, place a reverse proxy such as NGINX in front of Tomcat, or redirect the port at the firewall, noting that binding the privileged port on Linux requires root privileges or a capability grant.

Keystore Password Errors During Startup

A keystore was tampered with or password was incorrect message in catalina.out means the certificateKeystorePassword value in server.xml does not match the export password set when the keystore was created. Correct the password in the configuration, or rebuild the keystore if the password has been lost, since keystore passwords cannot be recovered.

Chain and Key Mismatch Problems in Tomcat

Chain warnings on mobile devices while desktop browsers stay quiet mean the keystore was built without the ca-bundle, so rebuild it with the certfile option included and restart Tomcat. A key mismatch during keystore creation usually means the Certificate Signing Request (CSR) was regenerated after submission, which a reissue against the current Certificate Signing Request (CSR) resolves cleanly.

Premium Installation Assistance for Tomcat Environments

Tomcat deployments range from single application servers to clustered environments behind load balancers, and the keystore layer adds a step that other platforms do not have. Trustico® offers a Premium Installation service where our technicians complete the installation on your behalf.

Stay Updated - Our RSS Feed

There's never a reason to miss a post! Subscribe to our Atom/RSS feed and get instant notifications when we publish new articles about SSL Certificates, security updates, and news. Use your favorite RSS reader or news aggregator.

Subscribe via RSS/Atom