KB – Cookie parsing according to RFC 6265

Affects component

  • Airlock Microgateway

Affects version(s)

  • all versions

Purpose of this article

Airlock Microgateway implements a cookie store. Cookies are not exposed to the client by default. This prevents various attacks on cookies and enables secure cookie exchange between back-ends. Airlock Microgateway further supports passing cookies directly to the client, either in cleartext or encrypted. These features require parsing all cookies in HTTP requests as well as in HTTP responses.

Cookie parsing is described in three different RFCs. The following table lists some statements from these RFCs:

RFC and year

What it states

RFC 2109 from 1997

Allows multiple cookies within the same Set-Cookie header. Servers should accept comma and semicolon-separated cookies.

RFC 2965 from 2000

Added a new definition of cookies (Set-Cookie2 header) that was later deprecated in RFC 6265.

RFC 6265 from 2011

Forbids multiple cookie values within the same Set-Cookie response header. Also forbids commas in cookie values. Further, forbids multiple Cookie headers in requests.

The current implementation of Airlock Microgateway follows the newest RFC 6265 which is also implemented by all modern browsers and most modern web application servers.

Causes or possible causes

The legacy parsing behavior splits cookies by comma and semicolon with unencoded commas and semicolons in their values.

For example Set-Cookie:
A=X,B=Y would have been split into 2 cookies, A=X and B=Y.

Unfortunately, this breaks applications sending commas in their cookie values, e.g. Set-Cookie:
Nonce=aaa,bbb.

Even when commas in cookie values are not allowed according to RFC 6265, such cookies are accepted by all modern browsers and set by certain applications. We have changed the default cookie parsing to be compatible with such applications. The current default parsing affects the request header Cookie as well as the response header Set-Cookie.

Known errors and solutions

Following the newest RFC 6265 can break other applications not following this RFC. At the moment of writing this article, we are only aware of certain client-side frameworks that are incompatible with the new behavior. Web browsers are not affected.

  • In the following cases an application will probably break:
  • If the client sends cookie values separated by commas.
  • If the client sends multiple Cookie headers in a request. Cookies must be sent in a single, semicolon-separated, Cookie header.
  • In the following cases the application may break:
  • If the server sends multiple cookies in the same Set-Cookie header

We are aware that the RESTful Web Service framework "Jersey" is affected by the first issue (bug report https://github.com/eclipse-ee4j/jersey/issues/2811). Note that such applications would also be incompatible with other reverse proxies or application servers following the new RFC, like newer Tomcat servers.

Configuration Settings

By default, the legacy parsing is disabled to be compatible with RFC 6265. The following two configuration settings are available in the corresponding Expert Settings sections:

Where to configure

Settings/values

Description

Apache Expert Setting, globally or on the virtual host

AirlockLegacyCookieParsing "TRUE" | "FALSE"

The Apache Expert Setting is used to configure the cookie parsing of the HTTP request (HTTP header name "Cookie").

SG Expert Setting, globally or on the virtual host

LegacyCookieParsing "TRUE" | "FALSE"

The SG Expert Setting is used to configure the cookie parsing of the HTTP response (HTTP header name "Set-Cookie").

The following table describes the recommended configuration depending on the application type:

Application type

Correct behavior of the application

Configuration recommendation

Common applications, fully compliant with RFC 6265.

–

Use default settings.

Applications sending commas in cookie values.

Commas in cookie values must be encoded according to RFC 6265 1.

Use default settings.

Clients sending multiple request cookie headers.

Cookies in HTTP requests must be sent in a single Cookie header1.

Enable legacy cookie parsing.

1

We recommend updating or fixing affected applications so that they are compatible with RFC 6265.

There may be other special client behaviors not mentioned in this table.

Please let us know if your application is not working with the new cookie parsing scheme and you are using a common and modern framework for cookie handling because we intend to deprecate the legacy parsing in the future.