Enabling SSL on Apache Tomcat

Solution Verified - Updated

Environment

  • Red Hat Enterprise Linux (RHEL)
  • Red Hat JBoss Web Server (JWS)
  • Apache Tomcat

Issue

  • How do I setup SSL on Tomcat using a Certificate Authority such as Verisign or Thawte?
  • How to enable end-to-end SSL configuration on JBoss Web Server?
  • How to choose TLSv1.3 on Apache Tomcat?
  • How to set up the cipher list on Apache Tomcat?

Resolution

The container will attempt to auto-configure the connector's protocol based on loaded libraries (NOT recommended).

Set the protocol attribute of the Connector to avoid auto-configuration (recommended).

Tomcat provides three different implementations of SSL:

  • JSSE implementation provided as part of the Java runtime (default)
  • JSSE implementation that uses OpenSSL (PEM files)
  • APR implementation, which uses the OpenSSL (PEM files) engine by default

Note: The APR/Native HTTP Connector is deprecated and will be removed in Tomcat 10.1.x onwards.

To install and configure SSL/TLS support on Tomcat:

  1. Create a certificate by following the instructions in How to build Certificates for use with Java applications.
  2. Configure the Connector entry in $CATALINA_BASE/conf/server.xml using one of the implementations below.

Important Configuration Notes:

  • The protocols and ciphers values in the examples below are illustrative and must be replaced with values conforming to current security standards.
  • For JWS RPM installations, $CATALINA_HOME is /opt/rh/jws-<version>/root/usr/share.
  • For JWS ZIP installations, $CATALINA_HOME is the extraction directory (e.g., /opt/jws-<version>).
  • For RHEL's base Tomcat package, the server.xml file is located at /etc/tomcat/server.xml.

JSSE Implementation

<Connector port="8443" 
           protocol="org.apache.coyote.http11.Http11NioProtocol"
           sslImplementationName="org.apache.tomcat.util.net.jsse.JSSEImplementation"
           maxThreads="150" 
           SSLEnabled="true"
           maxParameterCount="1000"
           protocols="TLSv1.2,TLSv1.3"
           ciphers="ECDHE-ECDSA-AES128-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384"
           >
    <SSLHostConfig>
        <Certificate certificateKeystoreFile="/path/to/keystore.jks"
                     type="RSA" />
    </SSLHostConfig>
</Connector>

JSSE OpenSSL Implementation

<Connector port="8443" 
           protocol="org.apache.coyote.http11.Http11NioProtocol"
           sslImplementationName="org.apache.tomcat.util.net.openssl.OpenSSLImplementation"
           maxThreads="150" 
           SSLEnabled="true"
           maxParameterCount="1000"
           protocols="TLSv1.3"
           ciphers="ECDHE-ECDSA-AES128-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384"
           >
    <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" />
    <SSLHostConfig>
        <Certificate certificateKeyFile="/path/to/certificateKey.pem"
                     certificateFile="/path/to/certificate.pem"
                     certificateChainFile="/path/to/certificateChain.pem"
                     type="RSA" />
    </SSLHostConfig>
</Connector>

APR Implementation (Deprecated)

<Connector port="8443" protocol="org.apache.coyote.http11.Http11AprProtocol"
           maxThreads="150" SSLEnabled="true" >
    <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" />
    <SSLHostConfig>
        <Certificate certificateKeyFile="/path/to/certificateKey.pem"
                     certificateFile="/path/to/certificate.pem"
                     certificateChainFile="/path/to/certificateChain.pem"
                     type="RSA" />
    </SSLHostConfig>
</Connector>

Root Cause

The HTTPS connector is disabled by default. Only the HTTP (8080) connector is enabled upon initial installation.

Diagnostic Steps

To verify the configuration, deploy a test application or query the root context (if enabled). Replace <hostnameOrIp> and <app> with the appropriate environment values.

  • To test the root context:
curl -kv https://<hostnameOrIp>:8443/
  • To test a deployed application:
curl -kv https://<hostnameOrIp>:8443/<app>

A successful configuration will return an HTTP 200 (OK) response.

SBR
Product(s)
Components
Category
Tags

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.