The Cookie Processor Component

Table of Contents

Introduction

The CookieProcessor element represents the component that parses received cookie headers into javax.servlet.http.Cookie objects accessible through HttpServletRequest.getCookies() and converts javax.servlet.http.Cookie objects added to the response through HttpServletResponse.addCookie() to the HTTP headers returned to the client.

A CookieProcessor element MAY be nested inside a Context component. If it is not included, a default implementation will be created automatically.

Note: CookieProcessor is a new configuration element, introduced in Tomcat 8.0.15. This is work in progress. The goal is to review the current implementation of HTTP Cookie headers processing in Tomcat to provide better compliance with RFC6265 specification. The ideas are summarized on a Wiki page and discussed on mailing lists. Notable points:

  • CookieProcessor element allows to configure cookie parsing separately in each web application, or globally in the default conf/context.xml file. The legacy cookie parsing algorithm supported only limited global configuration via several system properties. Those system properties are still supported, but are going to be deprecated in favor of this new configuration element.
  • The new RFC6265-compliant (work in progress) implementation is a stand-in replacement for the original legacy one. Until the new code is stabilized, the legacy implementation remains the default one. You can select the implementation by setting className attribute on CookieProcessor element.
  • This is work in progress. Configuration attributes may change in a future release.

Attributes

Common Attributes

All implementations of CookieProcessor support the following attributes:

Attribute Description
className

Java class name of the implementation to use. This class must implement the org.apache.tomcat.util.http.CookieProcessor interface. If not specified, the standard value (defined below) will be used.

Standard Implementation

The standard implementation of CookieProcessor is org.apache.tomcat.util.http.LegacyCookieProcessor. Note that it is anticipated that this will change to org.apache.tomcat.util.http.Rfc6265CookieProcessor in a future Tomcat 8 release.

This is the legacy cookie parser based on RFC6265, RFC2109 and RFC2616. It implements a strict interpretation of the cookie specifications. Due to various interoperability issues with browsers not all strict behaviours are enabled by default and additional options are available to further relax the behaviour of this cookie processor if required.

Attribute Description
allowEqualsInValue

If this is true Tomcat will allow '=' characters when parsing unquoted cookie values. If false, cookie values containing '=' will be terminated when the '=' is encountered and the remainder of the cookie value will be dropped.

If not set the specification compliant default value of false will be used. This default may be changed by setting the org.apache.tomcat.util.http.ServerCookie.ALLOW_EQUALS_IN_VALUE system property.

allowHttpSepsInV0

If this is true Tomcat will allow HTTP separators in cookie names and values.

If not specified, the default specification compliant value of false will be used. This default may be changed by setting the org.apache.tomcat.util.http.ServerCookie.ALLOW_HTTP_SEPARATORS_IN_V0 system property.

allowNameOnly

If this is true Tomcat will allow name only cookies (with or without trailing '=') when parsing cookie headers. If false, name only cookies will be dropped.

If not set the specification compliant default value of false will be used. This default may be changed by setting the org.apache.tomcat.util.http.ServerCookie.ALLOW_NAME_ONLY system property.

forwardSlashIsSeparator

If this is true Tomcat will treat the forward slash character ('/') as an HTTP separator when processing cookie headers. If org.apache.catalina.STRICT_SERVLET_COMPLIANCE is set to true, the default of this setting will be true, else the default value will be false. This default may be overridden by setting the org.apache.tomcat.util.http.ServerCookie.FWD_SLASH_IS_SEPARATOR system property.

preserveCookieHeader

If this is true Tomcat will ensure that cookie processing does not modify cookie header returned by HttpServletRequest.getHeader(). If org.apache.catalina.STRICT_SERVLET_COMPLIANCE is set to true, the default of this setting will be true, else the default value will be false. This default may be overridden by setting the org.apache.tomcat.util.http.ServerCookie.PRESERVE_COOKIE_HEADER system property.

RFC 6265 Cookie Processor - org.apache.tomcat.util.http.Rfc6265CookieProcessor

This cookie processor is based on RFC6265 with the following changes to support better interoperability:

  • Values 0x80 to 0xFF are permitted in cookie-octet to support the use of UTF-8 in cookie values as used by HTML 5.
  • For cookies without a value, the '=' is not required after the name as some browsers do not sent it.

The RFC 6265 cookie processor is generally more lenient than the legacy cookie parser. In particular:

  • The '=' and '/' characters are always permitted in a cookie value.
  • Name only cookies are always permitted.
  • The cookie header is always preserved.

No additional attributes are supported by the RFC 6265 Cookie Processor.

Nested Components

No element may be nested inside a CookieProcessor.

Special Features

No special features are associated with a CookieProcessor element.

Comments

Notice: This comments section collects your suggestions on improving documentation for Apache Tomcat.

If you have trouble and need help, read Find Help page and ask your question on the tomcat-users mailing list. Do not ask such questions here. This is not a Q&A section.

The Apache Comments System is explained here. Comments may be removed by our moderators if they are either implemented or considered invalid/off-topic.