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.

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.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.

The RFC 6265 Cookie Processor supports the following additional attributes.

Attribute Description
cookiesWithoutEquals

Determines how a cookie received from a user agent should be interpreted when the name value pair does not contain an equals sign. The default value is name which means that the cookie will be treated as a cookie with a name but no value. The other option is ignore which means the cookie will be ignored. From Tomcat 12 onwards the default will be ignore.

partitioned

Should the Partitioned flag be set on cookies? Defaults to false.

Note: The name of the attribute used to indicate a partitioned cookie as part of CHIPS is not defined by an RFC and may change in a non-backwards compatible way once equivalent functionality is included in an RFC.

sameSiteCookies

Enables setting same-site cookie attribute.

If value is unset then the same-site cookie attribute won't be set. This is the default value.

If value is none then the same-site cookie attribute will be set and the cookie will always be sent in cross-site requests.

If value is lax then the browser only sends the cookie in same-site requests and cross-site top level GET requests.

If value is strict then the browser prevents sending the cookie in any cross-site request.

Legacy Cookie Processor - org.apache.tomcat.util.http.LegacyCookieProcessor

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.

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.

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.

alwaysAddExpires

If this is true Tomcat will always add an expires parameter to a SetCookie header even for cookies with version greater than zero. This is to work around a known IE6 and IE7 bug that causes I to ignore the Max-Age parameter in a SetCookie header.

If org.apache.catalina.STRICT_SERVLET_COMPLIANCE is set to true, the default of this setting will be false, else the default value will be true.

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.

sameSiteCookies

Enables setting same-site cookie attribute.

If value is unset then the same-site cookie attribute won't be set. This is the default value.

If value is none then the same-site cookie attribute will be set and the cookie will always be sent in cross-site requests.

If value is lax then the browser only sends the cookie in same-site requests and cross-site top level GET requests.

If value is strict then the browser prevents sending the cookie in any cross-site request.

Nested Components

No element may be nested inside a CookieProcessor.

Special Features

No special features are associated with a CookieProcessor element.