Enabling HSTS in Apache Tomcat
To enable HTTP Strict-Transport-Security (HSTS) in Apache Tomcat, PTC recommends using the information provided below.
Introduction
The HTTP HSTS is a mechanism that allows websites to declare that they can be only accessed via secure connection (HTTPS). The mechanism is specified by the
RFC6797, and it uses the response header Strict-Transport-Security to inform user agents (UAs) about the secure policy required by the website.
HSTS addresses the following threats:
• User bookmarks or manually types http://myDomain.com and is subject to a man-in-the-middle attacker.
◦ HSTS automatically redirects HTTP requests to HTTPS for the target domain.
• Web application that is intended to be purely HTTPS inadvertently contains HTTP links or serves content over HTTP.
◦ HSTS automatically redirects HTTP requests to HTTPS for the target domain.
• A man-in-the-middle attacker attempts to intercept traffic from a victim user using an invalid certificate, and hopes the user will accept the bad certificate.
◦ HSTS does not allow a user to override the invalid certificate message.
HSTS also eliminates the HTTP → HTTPS redirects, lowering access latencies.
The Strict-Transport-Security header:
• Is only recognized when sent over an HTTPS connection. Websites can still allow users to interact with the website using HTTP to provide compatibility with non-HTTPS user agents.
• Must contain a max-age directive. The value specifies the number of seconds the UA treats the host as a known HSTS host (a value of 0 means to cease the treatment).
• It can contain an includeSubdomain directive which, if present, signals the UA that the HSTS policy applies to the HSTS Host as well as to any subdomains of the host's domain name.
• The preload flag that indicates the site owner's consent to have their domain preloaded. With the domain preloaded, the browser is already aware that the host requires the use of SSL/TLS, therefore removing the small window where attacks can still happen: the initial HTTP → HTTPS redirect. The site owner must submit the domain to the list (
here).
HSTS in Tomcat
Apache Tomcat v8.0.23 provides the new
HttpHeaderSecurityFilter that adds the
Strict-Transport-Security,
X-Frame-Options, and
X-Content-Type-Options HTTP headers to the response. The filter can be added and configured like any other filter via the
web.xml file. The description of the filter can be found
here and the Tomcat installation that comes with an example in the
conf/web.xml. The example below is a snippet of the
web.xml file that allows you to enable HSTS in Tomcat:
<!-- ================== Built In Filter Definitions ===================== -->
<!-- A filter that sets various security related HTTP Response headers. -->
<!-- This filter supports the following initialization parameters -->
<!-- (default values are in square brackets): -->
<!-- -->
<!-- hstsEnabled Should the HTTP Strict Transport Security -->
<!-- (HSTS) header be added to the response? See -->
<!-- RFC 6797 for more information on HSTS. [true] -->
<!-- -->
<!-- hstsMaxAgeSeconds The max age value that should be used in the -->
<!-- HSTS header. Negative values will be treated -->
<!-- as zero. [0] -->
<!-- -->
<!-- hstsIncludeSubDomains -->
<!-- Should the includeSubDomains parameter be -->
<!-- included in the HSTS header. -->
<!-- -->
<!-- antiClickJackingEnabled -->
<!-- Should the anti click-jacking header -->
<!-- X-Frame-Options be added to every response? -->
<!-- [true] -->
<!-- -->
<!-- antiClickJackingOption -->
<!-- What value should be used for the header. Must -->
<!-- be one of DENY, SAMEORIGIN, ALLOW-FROM -->
<!-- (case-insensitive). [DENY] -->
<!-- -->
<!-- antiClickJackingUri IF ALLOW-FROM is used, what URI should be -->
<!-- allowed? [] -->
<!-- -->
<!-- blockContentTypeSniffingEnabled -->
<!-- Should the header that blocks content type -->
<!-- sniffing be added to every response? [true] -->
<filter>
<filter-name>httpHeaderSecurity</filter-name>
<filter-class>org.apache.catalina.filters.HttpHeaderSecurityFilter</filter-class>
<async-supported>true</async-supported>
<init-param>
<param-name>hstsEnabled</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>hstsMaxAgeSeconds</param-name>
<param-value>31536000</param-value>
</init-param>
<init-param>
<param-name>hstsIncludeSubDomains</param-name>
<param-value>true</param-value>
</init-param>
</filter>
<!-- The mapping for the HTTP header security Filter -->
<filter-mapping>
<filter-name>httpHeaderSecurity</filter-name>
<url-pattern>/*</url-pattern>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
The Strict-Transport-Security header is returned only if the UA accesses the website via HTTPs, therefore, Tomcat must be configured with SSL/TLS (see
here for the secure Tomcat set-up). Since the Strict-Transport-Security is only returned when the connection is secure, the owner of the website must decide the following:
• If they also serve the website via insecure connections for backwards compatibility.
• If they redirect insecure connections to secure connections (desired).
In the second case, it is possible to set up the redirect in Tomcat by adding a security constraint in the web.xml and adding the redirect in the server.xml. For example:
<security-constraint>
<web-resource-collection>
<web-resource-name>twx-portal</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
<Connector executor="tomcatThreadPool"
port="8080" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443" />
Set up HTTP to HTTPS Redirect (optional)
To force HTTP traffic to get redirected to the secure connection, make sure the HTTP connector defined in the server.xml has the redirectPort attribute set to point to the correct port. If the connector is not defined, add it. Tt should look similar to the following:
<Connector port="8080" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443" />
In the WEB-INF/web.xml, add the security constraint:
<security-constraint>
<web-resource-collection>
<web-resource-name>twx-portal</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>