Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 37 ยท Security and TLS

TLS and HTTPS in Tomcat

Configure HTTPS in Tomcat 11: keystores, the SSLHostConfig and Certificate elements, protocols, ciphers, HTTP/2, redirects and certificate renewal.

HTTPS wraps every request and response in TLS, so nobody on the network can read or change them. Browsers now mark plain HTTP as not secure, search engines prefer HTTPS, and features like HTTP/2 only work over TLS. In a typical production setup a reverse proxy or load balancer ends TLS in front of Tomcat. Even so, you should know how Tomcat does it itself: for internal traffic, for a proxy that re-encrypts, and for the day the proxy is not there.

This lesson covers the keystore, the connector configuration, protocol and cipher choices, and renewal. The configuration is read-only here because Tomcat cannot run on this site; the Java examples are stand-ins that use the JDK's TLS classes Tomcat is built on.

How a TLS connector is built

Tomcat 9 and later describe TLS with a three-level structure inside a <Connector>:

  • <SSLHostConfig> holds protocols, ciphers and client-certificate settings for one host name.
  • <Certificate> points to a keystore or to PEM files (one per key type, e.g. RSA and ECDSA).
  • The connector itself sets the port and the protocol implementation.
XML
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="200" SSLEnabled="true" scheme="https" secure="true">
  <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol"/>
  <SSLHostConfig protocols="TLSv1.3,TLSv1.2" honorCipherOrder="true">
    <Certificate certificateKeystoreFile="conf/keystore.p12"
                 certificateKeystorePassword="changeit"
                 certificateKeystoreType="PKCS12"
                 type="RSA"/>
  </SSLHostConfig>
</Connector>

SSLEnabled="true" turns TLS on for the port; scheme and secure make request.isSecure() and getScheme() truthful. The nested UpgradeProtocol enables HTTP/2 through ALPN, with no further settings on modern JDKs.

If you prefer files from Let's Encrypt or another CA, use PEM paths directly and skip the keystore:

XML
<Certificate certificateFile="conf/ssl/fullchain.pem"
             certificateKeyFile="conf/ssl/privkey.pem"
             certificateChainFile="conf/ssl/chain.pem"
             type="RSA"/>

Creating a keystore for testing

For a development certificate, the JDK's keytool generates a key pair and a self-signed certificate in a PKCS12 keystore:

Terminal
keytool -genkeypair -alias tomcat -keyalg RSA -keysize 3072 \
  -validity 365 -storetype PKCS12 -keystore conf/keystore.p12 \
  -dname "CN=localhost" -ext "SAN=dns:localhost,ip:127.0.0.1"

Browsers will warn about a self-signed certificate; that is expected. For production, create a certificate signing request (keytool -certreq), send it to a CA, then import the signed chain with keytool -importcert. Always include the subject alternative name (SAN): modern clients ignore the common name.

Protocols and ciphers

Set protocols="TLSv1.3,TLSv1.2" and nothing older. SSLv3, TLS 1.0 and 1.1 are broken or deprecated. With TLS 1.3 you rarely tune ciphers, since all its suites are strong. For TLS 1.2, restrict suites to forward-secret AEAD ones if your clients allow it:

XML
<SSLHostConfig protocols="TLSv1.3,TLSv1.2"
  ciphers="TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384:TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
  honorCipherOrder="true">

Test the result with an external scanner or openssl s_client -connect host:8443 -tls1_2. Remember that the JDK itself disables weak algorithms through java.security, so a cipher you list may still be unavailable.

HTTP to HTTPS redirect

Keep a plain HTTP connector whose redirectPort="8443" points at the secure one. Together with a CONFIDENTIAL transport guarantee in web.xml (see realms and authentication) it redirects insecure requests. To redirect the whole site, add a constraint covering /* with no auth constraint. Add an HSTS header with the HttpHeaderSecurityFilter so browsers refuse HTTP in future.

What Java gives you

Tomcat uses the JDK's JSSE (or OpenSSL through the Tomcat Native/Panama bindings, for speed). You can inspect what a JVM supports with plain Java. This stand-in lists enabled protocols and some cipher suites on the machine running it; your Tomcat host may differ.

Java Stand-in: what does this JVM offer for TLS?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The output shows TLS 1.3 and 1.2 at the top of the defaults, matching what you would put in protocols.

Inspecting a certificate chain

Certificates in a keystore carry names, validity dates and a signer. Operators check these dates because an expired certificate takes the site down. This stand-in builds a small "expiry report" from dates, the way a monitoring script would after reading X509Certificate.getNotAfter():

Java Stand-in: certificate expiry report

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Renewing without downtime

A certificate change normally needs a restart, which drops connections. Tomcat can reload instead: the Manager's /text/sslReload command (or the JMX operation reloadSslHostConfigs on the connector) re-reads keystore files without stopping the connector. Automating renewal looks like this: renew with certbot or your CA's client, run a deploy hook that copies the new PEM files, then call the reload URL. Alert on certificates with fewer than 14 days left.

Common mistakes

  • Putting a keystore password in server.xml readable by everyone; restrict file permissions or use an externalized property.
  • A chain that lacks the intermediate certificate: desktop browsers may cope, mobile clients and curl fail.
  • Forgetting scheme="https" behind a proxy, so redirects send users to HTTP (use RemoteIpValve for proxied traffic).
  • Enabling TLS 1.0 for "old clients" and failing a compliance scan.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which element holds the keystore location inside a Tomcat TLS connector?

    SSLHostConfig groups TLS settings and its nested Certificate element points at the keystore or PEM files.
  2. 2. Which protocols setting is the sensible modern choice?

    TLS 1.3 and 1.2 are the supported, secure versions. Older ones are deprecated and fail scans.
  3. 3. Why include a subject alternative name in a new certificate?

    Browsers and HTTP libraries validate the host name against SAN entries.
  4. 4. How can a new certificate be loaded without restarting Tomcat?

    Tomcat can re-read SSLHostConfig files on demand, so renewal does not need to drop connections.

Summary

  • A TLS connector is Connector + SSLHostConfig + Certificate.
  • Use TLS 1.3 and 1.2 only, a full certificate chain and a SAN.
  • Add an HTTP connector with redirectPort, a CONFIDENTIAL constraint and HSTS.
  • Reload certificates on the fly and monitor expiry dates.

Next: Hardening Tomcat