Cookie parsing settings
Cookie parsing according to RFC 6265

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

Currently, the parser behavior can be configured as legacy parsing TRUE or FALSE. The legacy, as well as the new parsing (that follows RFC 6265), can break certain applications which do not respect the newest RFCs. This article provides technical information about the changes in parsing.

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.
This is the Airlock Gateway default behavior before version 7.4.
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 new implementation of Airlock Gateway 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.

If you are migrating a non-web browser client (e.g. a Java client application) from Airlock Gateway before version 7.4 to a newer Airlock Gateway release version, you should carefully test the application.

  • 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 header. 1
Enable legacy cookie parsing for Apache and SG Expert Settings.
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.

Further information and links