Tomcat SSL configuration for HTTPS

Configure Application and Tomcat for an HTTPS connection

Table of Contents

• Basic Tomcat configuration
  • Non-TLS port
  • TLS port
• Advanced configuration with UI operating on https
  • Tomcat config/server.xml
  • Toolkit web.xml additions
  • Toolkit Properties Update

These instructions have been updated to align with the configuration used on our public server ihexds.nist.gov which runs Java 8 and Tomcat 8.

The keystore in the External Cache is used to establish outgoing TLS connections and the one referenced in the Tomcat Connector governs incoming connections.

You use the same cert for simulators (incoming connections) as for client (outgoing connections) so the certificate referenced here is the one in the External Cache in the default environment.

The examples below are taken from our public server.

These configuration elements come from Tomcat config/server.xml except as noted.

Basic Tomcat configuration

This covers the necessary Connectors to define TLS and non-TLS ports.

Non-TLS port

This is defined in toolkit.properties as Toolkit_Port

 <Connector
    port="12093"
    protocol="HTTP/1.1"
    connectionTimeout="20000"
    redirectPort="12094" />

TLS port

This port is defined in toolkit.properties as Toolkit_TLS_Port

    <Connector
           port="12091"
	   protocol="org.apache.coyote.http11.Http11NioProtocol"
	   SSLEnabled="true"
           maxHttpHeaderSize="8192"
	   maxThreads="150"
	   enableLookups="true"
	   disableUploadTimeout="true"
	   acceptCount="100"
	   scheme="https"
	   secure="true"
           ciphers="TLS_RSA_WITH_AES_128_CBC_SHA,SSL_RSA_WITH_3DES_EDE_CBC_SHA"
	   clientAuth="true"   <!-- 1 ->
           keystoreFile="/home/bmpaws/ec/environment/default/keystore/keystore"  <!-- 2 ->
           keystorePass="changeit"
           truststoreFile="/home/bmpaws/ec/environment/default/keystore/keystore"
           truststorePass="changeit"
    />

1. Mutual TLS

2. The External Cache is at /home/bmpaws/ec

Advanced configuration with UI operating on https

For most local installations (your development laptop) running the UI on https is not useful. But if you are installing Toolkit on a server and want the added protection here are the configuration additions we use on our server.

Tomcat config/server.xml

To operate the UI on https the follow element must be added to config/server.xml

    <Connector
           port="12094"
           protocol="HTTP/1.1"
           SSLEnabled="true"
           maxHttpHeaderSize="8192"
	   maxThreads="150"
	   enableLookups="true"
	   disableUploadTimeout="true"
	   acceptCount="100"
	   scheme="https"
	   secure="true"
	   clientAuth="false"  <!-- 1 ->
           SSLProtocol="TLSv1+TLSv1.1+TLSv1.2"
           sslEnabledProtocols="TLSv1.2"
           SSLCipherSuite="HIGH:!ADH"
           SSLCertificateFile="/sites/www/certs/hit-dev.crt"   <!-- 2 -->
           SSLCertificateKeyFile="/sites/www/certs/hit-dev.key"
           SSLCertificateChainFile="/sites/www/certs/chain.crt"
       />

1. Browser does not do mutual TLS

2. This should be a cert from a well known CA that your browser recognizes or you will have to install the Root CA cert in your browser.

Toolkit web.xml additions

The toolkit web.xml located in WEB-INF must have this element added to direct the content to the correct connectors.

    <security-constraint>
        <web-resource-collection>
            <web-resource-name>HTTPSOnly</web-resource-name>
            <url-pattern>/xdstools2/toolkit</url-pattern>   <!-- The GWT RPC backend -->
            <url-pattern>/Xdstools2.html</url-pattern>      <!-- The single-page application -->
            <url-pattern>/Xdstools2.html/*</url-pattern>    <!-- The single-page application wildcard -->
            <url-pattern>/#</url-pattern>                   <!-- Default page -->
            <url-pattern>/#*</url-pattern>                  <!-- Tool URL, for example /#ConfActor -->
            <url-pattern>/Xdstools2.html#*</url-pattern>    <!-- Tool URL wildcard -->
        </web-resource-collection>
        <user-data-constraint>
            <transport-guarantee>CONFIDENTIAL</transport-guarantee>
        </user-data-constraint>
    </security-constraint>

Toolkit Properties Update

These toolkit.properties are required when https GUI is used. Update these toolkit.properties:

Using_SSL=true
SSL_Port=12094

These properties are used when navigating to Simulators, Logs, or the using the Copy log link URL feature.

SSL_Port is used to build a link like this: SimResource Link: https://cat-nist-tools.ihe-europe.net.example.com:12094/xdstools/Xdstools2.html#SimMsgViewer:default__test1/reg/rb/2020_11_01_15_59_12_836

Port connector 12094 uses a different cert only for the web browser https UI. This is not to be confused with the certificate configured with Tomcat TLS connector Port (example 12091) that uses a Gazelle-issued cert for XDS Toolkit TLS testing purpose.