Turn on SSL/TLS Support on Tomcat

Linux Apps Tutorials - Herong's Tutorial Examples

∟Turn on SSL/TLS Support on Tomcat

This section provides a tutorial example on how to configure Tomcat to support SSL/TLS for the HTTPS service.

By default, support for SSL/TLS is turned off in the configuration file:

herong$ more $TOMCAT_HOME/conf/server.xml

...
<!--
<Connector port="8443" 
           protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="150" SSLEnabled="true"
           maxParameterCount="1000">
  <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol"/>
  <SSLHostConfig>
    <Certificate certificateKeystoreFile="conf/localhost-rsa.jks"
                 type="RSA" />
  </SSLHostConfig>
</Connector>
-->

To turn on the HTTPS service, you need to prepare your server certificate and update the configuration file as shown below.

1. Decide which certificate file format to use. Tomcat 9 or newer release supports 3 file formats: PEM, JKS and PKCS12. PEM is easiest to manage.

2. Prepare your server certificate, related private key and signing CA certificate chain in 3 PEM files.

herong$ $TOMCAT_HOME/conf/*.pem 

...
-r--r--r--. 1  4350 Mar 30 03:13 ca-chain.cert.pem
-r--r--r--. 1  2175 Mar 30 03:13 server.cert.pem
-r--r--r--. 1  1704 Mar 29 10:55 server.key.pem

Note that signing CA certificate chain file, ca-chain.cert.pem, is not needed, if the certificate is self-signed. Otherwise, the chain file must contain all certificates in the signing chain and in the reverse order of the signing process.

3. Update the configuration file to turn on the HTTPS service, by opening the port="8443" connector and specifying certificate related PEM files. Don't forget to provide the certificateKeyPassword setting.

herong$ sudo vi $TOMCAT_HOME/conf/server.xml

...
<Connector port="8443" 
           protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="150" SSLEnabled="true"
           maxParameterCount="1000">
  <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol"/>
  <SSLHostConfig>
      <Certificate 
        certificateFile="conf/server.cert.pem"
        certificateKeyFile="conf/server.key.pem"
        certificateKeyPassword="TopSecret"
        certificateChainFile="conf/ca-chain.cert.pem"
      />
  </SSLHostConfig>
</Connector>

4. Restart Tomcat and check the log file. You should see the [https-jsse-nio-8443] connector started with no errors:

herong$ $TOMCAT_HOME/logs/shutdown.sh

herong$ $TOMCAT_HOME/logs/startup.sh

herong$ tail -100 $TOMCAT_HOME/logs/catalina.out
...
INFO [main] org.apache.coyote.AbstractProtocol.init 
  Initializing ProtocolHandler ["https-jsse-nio-8443"]
INFO [main] org.apache.tomcat.util.net.AbstractEndpoint.logCertificate 
  Connector [https-jsse-nio-8443], TLS virtual host [_default_], 
  certificate type [UNDEFINED] configured from 
  key [conf/server.key.pem], 
  certificate [conf/server.cert.pem] and 
  certificate chain [conf/ca-chain.cert.pem] 
  with trust store [null]

5. Open firewall for port 8443:

herong$ sudo firewall-cmd --zone=public --add-port=8443/tcp
herong$ sudo firewall-cmd --runtime-to-permanent

6. Try to open Tomcat home page with the HTTPS protocol in a Web browser: https://localhost:8443. You should see the home page displayed, if the certificate is valid.

7. Resolve certificate exception issues, if the certificate is self-signed, the Root CA certificate is not trusted, the certificate is expired, etc..

If certificate settings are not specified correctly, you may see errors in the log file. For example:

1. If the "SSLHostConfig" section is missing or specified incorrectly, you may see the following error:

Caused by: java.lang.IllegalArgumentException: 
  no element SSLHostConfig found with hostName [default] 
  corresponding to defaultSSLHostConfigName 
  for the connector [https-jsse-nio-8443

1. If the "SSLHostConfig" section is missing or specified incorrectly, you may see the following error:

Caused by: java.lang.IllegalArgumentException: 
  no element SSLHostConfig found with hostName [default] 
  corresponding to defaultSSLHostConfigName 
  for the connector [https-jsse-nio-8443

2. If you are using a JKS or PKCS12 file to store certificates/private keys, and you specify the wrong password to open the file, you may see the following error:

Caused by: java.io.IOException: keystore password was incorrect

3. If you have a RSA-based private key and certificate, and you specify the wrong certificate type like "PKCS12", you may see the following error:

Caused by: java.lang.IllegalArgumentException: 
  No enum constant org.apache.tomcat.util.net.SSLHostConfigCertificate.Type.PKCS12

Note that the "Type" settings in the "Certificate" section specifies the cryptography algorithm type like RSA, DSA or EC, not the certificate file format type of PEM, JKS, or PKCS12.

4. If you specify keystoreFile and keystoreType settings as attributes of the "Connector" element, like you did in Tomcat 8 or older releases, you may see the following error:

Caused by: java.lang.IllegalArgumentException: 
  no element SSLHostConfig found with hostName [default] corresponding 
  to defaultSSLHostConfigName for the connector [https-jsse-nio-8443

Tomcat 9 or newer release requires certificate related settings being specified in the "SSLHostConfig" sub-element.

For more information on HTTPS service, also referred as SSL support, see "SSL/TLS Configuration How-To" at tomcat.apache.org/tomcat-10.1-doc/ssl-howto.html.