## The Cookie Processor Component

### Table of Contents

- Introduction
- Attributes
  1. Common Attributes
  2. Standard Implementation
  3. RFC 6265 Cookie Processor - org.apache.tomcat.util.http.Rfc6265CookieProcessor
- Nested Components
- Special Features

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