The Apache Tomcat Servlet/JSP Container

Apache Tomcat 7

Version 7.0.67, Dec 7 2015
Apache Logo

Links

Top Level Elements

Executors

Connectors

Containers

Nested Components

Cluster Elements

web.xml

Other

Container Provided Filters

Table of Contents
Introduction

Tomcat provides a number of Filters which may be configured for use with all web applications using $CATALINA_BASE/conf/web.xml or may be configured for individual web applications by configuring them in the application's WEB-INF/web.xml. Each filter is described below.

This description uses the variable name $CATALINA_BASE to refer the base directory against which most relative paths are resolved. If you have not configured Tomcat for multiple instances by setting a CATALINA_BASE directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, the directory into which you have installed Tomcat.

Add Default Character Set Filter
Introduction

The HTTP specification is clear that if no character set is specified for media sub-types of the "text" media type, the ISO-8859-1 character set must be used. However, browsers may attempt to auto-detect the character set. This may be exploited by an attacker to perform an XSS attack. Internet Explorer has this behaviour by default. Other browsers have an option to enable it.

This filter prevents the attack by explicitly setting a character set. Unless the provided character set is explicitly overridden by the user the browser will adhere to the explicitly set character set, thus preventing the XSS attack.

Filter Class Name

The filter class name for the Add Default Character Set Filter is org.apache.catalina.filters.AddDefaultCharsetFilter .

Initialisation parameters

The Add Default Character Set Filter supports the following initialization parameters:

AttributeDescription
encoding

Name of the character set which should be set, if no other character set was set explicitly by a Servlet. This parameter has two special values default and system. A value of system uses the JVM wide default character set, which is usually set by locale. A value of default will use ISO-8859-1.

CORS Filter
Introduction

This filter is an implementation of W3C's CORS (Cross-Origin Resource Sharing) specification, which is a mechanism that enables cross-origin requests.

The filter works by adding required Access-Control-* headers to HttpServletResponse object. The filter also protects against HTTP response splitting. If request is invalid, or is not permitted, then request is rejected with HTTP status code 403 (Forbidden). A flowchart that demonstrates request processing by this filter is available.

The minimal configuration required to use this filter is:

<filter>
  <filter-name>CorsFilter</filter-name>
  <filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
</filter>
<filter-mapping>
  <filter-name>CorsFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>
Filter Class Name

The filter class name for the CORS Filter is org.apache.catalina.filters.CorsFilter.

Initialisation parameters

The CORS Filter supports following initialisation parameters:

AttributeDescription
cors.allowed.origins

A list of origins that are allowed to access the resource. A * can be specified to enable access to resource from any origin. Otherwise, a whitelist of comma separated origins can be provided. Eg: http://www.w3.org, https://www.apache.org. Defaults: * (Any origin is allowed to access the resource).

cors.allowed.methods

A comma separated list of HTTP methods that can be used to access the resource, using cross-origin requests. These are the methods which will also be included as part of Access-Control-Allow-Methods header in pre-flight response. Eg: GET, POST. Defaults: GET, POST, HEAD, OPTIONS

cors.allowed.headers

A comma separated list of request headers that can be used when making an actual request. These headers will also be returned as part of Access-Control-Allow-Headers header in a pre-flight response. Eg: Origin,Accept. Defaults: Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers

cors.exposed.headers

A comma separated list of headers other than simple response headers that browsers are allowed to access. These are the headers which will also be included as part of Access-Control-Expose-Headers header in the pre-flight response. Eg: X-CUSTOM-HEADER-PING,X-CUSTOM-HEADER-PONG. Default: None. Non-simple headers are not exposed by default.

cors.preflight.maxage

The amount of seconds, browser is allowed to cache the result of the pre-flight request. This will be included as part of Access-Control-Max-Age header in the pre-flight response. A negative value will prevent CORS Filter from adding this response header to pre-flight response. Defaults: 1800

cors.support.credentials

A flag that indicates whether the resource supports user credentials. This flag is exposed as part of Access-Control-Allow-Credentials header in a pre-flight response. It helps browser determine whether or not an actual request can be made using credentials. Defaults: true

cors.request.decorate

A flag to control if CORS specific attributes should be added to HttpServletRequest object or not. Defaults: true

Here's an example of a more advanced configuration, that overrides defaults:

<filter>
  <filter-name>CorsFilter</filter-name>
  <filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
  <init-param>
    <param-name>cors.allowed.origins</param-name>
    <param-value>*</param-value>
  </init-param>
  <init-param>
    <param-name>cors.allowed.methods</param-name>
    <param-value>GET,POST,HEAD,OPTIONS,PUT</param-value>
  </init-param>
  <init-param>
    <param-name>cors.allowed.headers</param-name>
    <param-value>Content-Type,X-Requested-With,accept,Origin,Access-Control-Request-Method,Access-Control-Request-Headers</param-value>
  </init-param>
  <init-param>
    <param-name>cors.exposed.headers</param-name>
    <param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials</param-value>
  </init-param>
  <init-param>
    <param-name>cors.support.credentials</param-name>
    <param-value>true</param-value>
  </init-param>
  <init-param>
    <param-name>cors.preflight.maxage</param-name>
    <param-value>10</param-value>
  </init-param>
</filter>
<filter-mapping>
  <filter-name>CorsFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>
CORS Filter and HttpServletRequest attributes

CORS Filter adds information about the request, in HttpServletRequest object, for consumption downstream. Following attributes are set, if cors.request.decorate initialisation parameter is true:

  • cors.isCorsRequest: Flag to determine if request is a CORS request.
  • cors.request.origin: The Origin URL, i.e. the URL of the page from where the request originated.
  • cors.request.type: Type of CORS request. Possible values:
    • SIMPLE: A request which is not preceded by a pre-flight request.
    • ACTUAL: A request which is preceded by a pre-flight request.
    • PRE_FLIGHT: A pre-flight request.
    • NOT_CORS: A normal same-origin request.
    • INVALID_CORS: A cross-origin request, which is invalid.
  • cors.request.headers: Request headers sent as Access-Control-Request-Headers header, for a pre-flight request.
CSRF Prevention Filter
Introduction

This filter provides basic CSRF protection for a web application. The filter assumes that it is mapped to /* and that all URLs returned to the client are encoded via a call to HttpServletResponse#encodeRedirectURL(String) or HttpServletResponse#encodeURL(String).

This filter prevents CSRF by generating a nonce and storing it in the session. URLs are also encoded with the same nonce. When the next request is received the nonce in the request is compared to the nonce in the session and only if they are the same is the request allowed to continue.

Filter Class Name

The filter class name for the CSRF Prevention Filter is org.apache.catalina.filters.CsrfPreventionFilter .

Initialisation parameters

The CSRF Prevention Filter supports the following initialisation parameters:

AttributeDescription
denyStatus

HTTP response status code that is used when rejecting denied request. The default value is 403.

entryPoints

A comma separated list of URLs that will not be tested for the presence of a valid nonce. They are used to provide a way to navigate back to a protected application after having navigated away from it. Entry points will be limited to HTTP GET requests and should not trigger any security sensitive actions.

nonceCacheSize

The number of previously issued nonces that will be cached on a LRU basis to support parallel requests, limited use of the refresh and back in the browser and similar behaviors that may result in the submission of a previous nonce rather than the current one. If not set, the default value of 5 will be used.

randomClass

The name of the class to use to generate nonces. The class must be an instance of java.util.Random. If not set, the default value of java.security.SecureRandom will be used.

CSRF Prevention Filter for REST APIs
Introduction

This filter provides basic CSRF protection for REST APIs. The CSRF protection is applied only for modifying HTTP requests (different from GET, HEAD, OPTIONS) to protected resources. It is based on a custom header X-CSRF-Token that provides a valid nonce.

CSRF protection mechanism for REST APIs consists of the following steps:

  • Client asks for a valid nonce. This is performed with a non-modifying "Fetch" request to protected resource.
  • Server responds with a valid nonce mapped to the current user session.
  • Client provides this nonce in the subsequent modifying requests in the frame of the same user session.
  • Server rejects all modifying requests to protected resources that do not contain a valid nonce.

Basic configuration sample

On the server side

  • All CSRF protected REST APIs should be protected with an authentication mechanism.
  • Protect modifying REST APIs with this filter.
  • Provide at least one non-modifying operation.
<filter>
  <filter-name>RestCSRF</filter-name>
  <filter-class>org.apache.catalina.filters.RestCsrfPreventionFilter</filter-class>
</filter>
<filter-mapping>
  <filter-name>RestCSRF</filter-name>
  <!-- Modifying operations -->
  <url-pattern>/resources/removeResource</url-pattern>
  <url-pattern>/resources/addResource</url-pattern>
  <!-- Non-modifying operations -->
  <url-pattern>/resources/listResources</url-pattern>
</filter-mapping>

On the client side

  • Make a non-modifying "Fetch" request in order to obtain a valid nonce. This can be done with sending additional header X-CSRF-Token: Fetch
  • Cache the returned session id and nonce in order to provide them in the subsequent modifying requests to protected resources.
  • Modifying requests can be denied and header X-CSRF-Token: Required will be returned in case of invalid or missing nonce, expired session or in case the session id is changed by the server.
Client Request:
GET /rest/resources/listResources HTTP/1.1
X-CSRF-Token: Fetch
Authorization: Basic ...
Host: localhost:8080
...

Server Response:
HTTP/1.1 200 OK
Set-Cookie: JSESSIONID=...; Path=/rest; HttpOnly
X-CSRF-Token: ...
...

Client Request:
POST /rest/resources/addResource HTTP/1.1
Cookie: JSESSIONID=...
X-CSRF-Token: ...
Authorization: Basic ...
Host: localhost:8080
...

Server Response:
HTTP/1.1 200 OK
...
RestCsrfPreventionFilter and HttpServletRequest parameters

When the client is not able to insert custom headers in its calls to REST APIs there is additional capability to configure URLs for which a valid nonce will be accepted as a request parameter.

Note: If there is a X-CSRF-Token header, it will be taken with preference over any parameter with the same name in the request. Request parameters cannot be used to fetch new nonce, only header can be used to request a new nonce.

<filter>
  <filter-name>RestCSRF</filter-name>
  <filter-class>org.apache.catalina.filters.RestCsrfPreventionFilter</filter-class>
  <init-param>
    <param-name>pathsAcceptingParams</param-name>
    <param-value>/resources/removeResource,/resources/addResource</param-value>
  </init-param>
</filter>
<filter-mapping>
  <filter-name>RestCSRF</filter-name>
  <url-pattern>/resources/*</url-pattern>
</filter-mapping>
Filter Class Name

The filter class name for the CSRF Prevention Filter for REST APIs is org.apache.catalina.filters.RestCsrfPreventionFilter .

Initialisation parameters

The CSRF Prevention Filter for REST APIs supports the following initialisation parameters:

AttributeDescription
denyStatus

HTTP response status code that is used when rejecting denied request. The default value is 403.

pathsAcceptingParams

A comma separated list of URLs that can accept nonces via request parameter X-CSRF-Token. For use cases when a nonce information cannot be provided via header, one can provide it via request parameters. If there is a X-CSRF-Token header, it will be taken with preference over any parameter with the same name in the request. Request parameters cannot be used to fetch new nonce, only header can be used to request a new nonce.

randomClass

The name of the class to use to generate nonces. The class must be an instance of java.util.Random. If not set, the default value of java.security.SecureRandom will be used.

Expires Filter
Introduction

ExpiresFilter is a Java Servlet API port of Apache mod_expires. This filter controls the setting of the Expires HTTP header and the max-age directive of the Cache-Control HTTP header in server responses. The expiration date can set to be relative to either the time the source file was last modified, or to the time of the client access.

These HTTP headers are an instruction to the client about the document's validity and persistence. If cached, the document may be fetched from the cache rather than from the source until this time has passed. After that, the cache copy is considered "expired" and invalid, and a new copy must be obtained from the source.

To modify Cache-Control directives other than max-age (see RFC 2616 section 14.9), you can use other servlet filters or Apache Httpd mod_headers module.

Basic configuration sample

Basic configuration to add 'Expires' and 'Cache-Control: max-age=' headers to images, css and javascript.

<filter>
 <filter-name>ExpiresFilter</filter-name>
 <filter-class>org.apache.catalina.filters.ExpiresFilter</filter-class>
 <init-param>
    <param-name>ExpiresByType image</param-name>
    <param-value>access plus 10 minutes</param-value>
 </init-param>
 <init-param>
    <param-name>ExpiresByType text/css</param-name>
    <param-value>access plus 10 minutes</param-value>
 </init-param>
 <init-param>
    <param-name>ExpiresByType application/javascript</param-name>
    <param-value>access plus 10 minutes</param-value>
 </init-param>
</filter>
...
<filter-mapping>
 <filter-name>ExpiresFilter</filter-name>
 <url-pattern>/*</url-pattern>
 <dispatcher>REQUEST</dispatcher>
</filter-mapping>
Alternate Syntax

The ExpiresDefault and ExpiresByType directives can also be defined in a more readable syntax of the form:

<init-param>
 <param-name>ExpiresDefault</param-name>
 <param-value><base> [plus] {<num> <type>}*</param-value>
</init-param>

<init-param>
 <param-name>ExpiresByType type</param-name>
 <param-value><base> [plus] {<num> <type>}*</param-value>
</init-param>

<init-param>
 <param-name>ExpiresByType type;encoding</param-name>
 <param-value><base> [plus] {<num> <type>}*</param-value>
</init-param>

where <base> is one of:

  • access
  • now (equivalent to 'access')
  • modification

The plus keyword is optional. <num> should be an integer value (acceptable to Integer.parseInt()), and <type> is one of:

  • year, years
  • month, months
  • week, weeks
  • day, days
  • hour, hours
  • minute, minutes
  • second, seconds

For example, any of the following directives can be used to make documents expire 1 month after being accessed, by default:

<init-param>
 <param-name>ExpiresDefault</param-name>
 <param-value>access plus 1 month</param-value>
</init-param>

<init-param>
 <param-name>ExpiresDefault</param-name>
 <param-value>access plus 4 weeks</param-value>
</init-param>

<init-param>
 <param-name>ExpiresDefault</param-name>
 <param-value>access plus 30 days</param-value>
</init-param>

The expiry time can be fine-tuned by adding several '<num> <type>' clauses:

<init-param>
 <param-name>ExpiresByType text/html</param-name>
 <param-value>access plus 1 month 15 days 2 hours</param-value>
</init-param>

<init-param>
 <param-name>ExpiresByType image/gif</param-name>
 <param-value>modification plus 5 hours 3 minutes</param-value>
</init-param>

Note that if you use a modification date based setting, the Expires header will not be added to content that does not come from a file on disk. This is due to the fact that there is no modification time for such content.

Expiration headers generation eligibility

A response is eligible to be enriched by ExpiresFilter if :

  1. no expiration header is defined (Expires header or the max-age directive of the Cache-Control header),
  2. the response status code is not excluded by the directive ExpiresExcludedResponseStatusCodes,
  3. the Content-Type of the response matches one of the types defined the in ExpiresByType directives or the ExpiresDefault directive is defined.

Note : If Cache-Control header contains other directives than max-age, they are concatenated with the max-age directive that is added by the ExpiresFilter.

Expiration configuration selection

The expiration configuration if elected according to the following algorithm:

  1. ExpiresByType matching the exact content-type returned by HttpServletResponse.getContentType() possibly including the charset (e.g. 'text/xml;charset=UTF-8'),
  2. ExpiresByType matching the content-type without the charset if HttpServletResponse.getContentType() contains a charset (e.g. 'text/xml;charset=UTF-8' -> 'text/xml'),
  3. ExpiresByType matching the major type (e.g. substring before '/') of HttpServletResponse.getContentType() (e.g. 'text/xml;charset=UTF-8' -> 'text'),
  4. ExpiresDefault
Filter Class Name

The filter class name for the Expires Filter is org.apache.catalina.filters.ExpiresFilter .

Initialisation parameters

The Expires Filter supports the following initialisation parameters:

AttributeDescription
ExpiresExcludedResponseStatusCodes

This directive defines the http response status codes for which the ExpiresFilter will not generate expiration headers. By default, the 304 status code ("Not modified") is skipped. The value is a comma separated list of http status codes.

This directive is useful to ease usage of ExpiresDefault directive. Indeed, the behavior of 304 Not modified (which does specify a Content-Type header) combined with Expires and Cache-Control:max-age= headers can be unnecessarily tricky to understand.

See sample below the table

ExpiresByType <content-type>

This directive defines the value of the Expires header and the max-age directive of the Cache-Control header generated for documents of the specified type (e.g., text/html). The second argument sets the number of seconds that will be added to a base time to construct the expiration date. The Cache-Control: max-age is calculated by subtracting the request time from the expiration date and expressing the result in seconds.

The base time is either the last modification time of the file, or the time of the client's access to the document. Which should be used is specified by the <code> field; M means that the file's last modification time should be used as the base time, and A means the client's access time should be used. The duration is expressed in seconds. A2592000 stands for access plus 30 days in alternate syntax.

The difference in effect is subtle. If M (modification in alternate syntax) is used, all current copies of the document in all caches will expire at the same time, which can be good for something like a weekly notice that's always found at the same URL. If A ( access or now in alternate syntax) is used, the date of expiration is different for each client; this can be good for image files that don't change very often, particularly for a set of related documents that all refer to the same images (i.e., the images will be accessed repeatedly within a relatively short timespan).

Note: When the content type includes a charset (e.g. 'ExpiresByType text/xml;charset=utf-8'), Tomcat removes blank chars between the ';' and the 'charset' keyword. Due to this, configuration of an expiration with a charset must not include such a space character.

See sample below the table

It overrides, for the specified MIME type only, any expiration date set by the ExpiresDefault directive.

You can also specify the expiration time calculation using an alternate syntax, described earlier in this document.

ExpiresDefault

This directive sets the default algorithm for calculating the expiration time for all documents in the affected realm. It can be overridden on a type-by-type basis by the ExpiresByType directive. See the description of that directive for details about the syntax of the argument, and the "alternate syntax" description as well.

Sample: exclude response status codes 302, 500 and 503

<init-param>
 <param-name>ExpiresExcludedResponseStatusCodes</param-name>
 <param-value>302, 500, 503</param-value>
</init-param>

Sample for ExpiresByType initialization parameter

<init-param>
   <param-name>ExpiresByType text/html</param-name>
   <param-value>access plus 1 month 15   days 2 hours</param-value>
</init-param>

<init-param>
   <!-- 2592000 seconds = 30 days -->
   <param-name>ExpiresByType image/gif</param-name>
   <param-value>A2592000