## The Cookie Processor Component

### Table of Contents

- Introduction
- Attributes
  1. Common Attributes
  2. Standard Implementation
  3. Legacy Cookie Processor - org.apache.tomcat.util.http.LegacyCookieProcessor
- 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.

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