HTTP State Management Mechanism

This specification uses the Augmented Backus-Naur Form (ABNF) notation of [RFC5234].¶

The following core rules are included by reference, as defined in [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit sequence of data), SP (space), VCHAR (any visible [USASCII] character), and WSP (whitespace).¶

[TODO: Put some examples here.¶

[TODO: Should we go into this much detail here? This seems redundant with the HTTP specs.]¶

An origin server must be cognizant of the effect of possible caching of both the returned resource and the Set-Cookie header. Caching "public" documents is desirable. For example, if the origin server wants to use a public document such as a "front door" page as a sentinel to indicate the beginning of a session for which a Set-Cookie response header must be generated, the page should be stored in caches "pre-expired" so that the origin server will see further requests. "Private documents", for example those that contain information strictly private to a session, should not be cached in shared caches.¶

If the cookie is intended for use by a single user, the Set-Cookie header should not be cached. A Set-Cookie header that is intended to be shared by multiple users may be cached.¶

The origin server should send the following additional HTTP/1.1 response headers, depending on circumstances: [TODO: Is this good advice?] ¶

• To suppress caching of the Set-Cookie header: Cache-control: no- cache="set-cookie".

and one of the following: ¶

• To suppress caching of a private document in shared caches: Cache-Control: private.
• To allow caching of a document and require that it be validated before returning it to the client: Cache-Control: must-revalidate.
• To allow caching of a document, but to require that proxy caches (not user agent caches) validate it before returning it to the client: Cache-Control: proxy-revalidate.
• To allow caching of a document and request that it be validated before returning it to the client (by "pre-expiring" it): Cache-Control: max-age=0. Not all caches will revalidate the document in every case.

HTTP/1.1 servers must send Expires: old-date (where old-date is a date long in the past) on responses containing Set-Cookie response headers unless they know for certain (by out of band means) that there are no downstream HTTP/1.0 proxies. HTTP/1.1 servers may send other Cache-Control directives that permit caching by HTTP/1.1 proxies in addition to the Expires: old-date directive; the Cache-Control directive will override the Expires: old-date for HTTP/1.1 proxies.¶

Let an LWS character be either a U+20 (SPACE) or a U+09 (TAB) character.¶

When a user agent receives an Set-Cookie header in an HTTP response, the user agent *receives a set-cookie-string* consisting of the value of the header.¶

A user agent MUST use the following algorithm to parse set-cookie-strings: ¶

1. [TODO: Deal with "," characters. My current thinking is that we don't actually have to do anything special for them.]
2. If the header contains a U+3B (";") character:
   • the name-value-pair string is characters up to, but not including, the first U+3B (";"), and the unparsed-cookie-attributes are the remainder of the header (including the U+3B (";") in question).
   Otherwise:
   • the name-value-pair string is all the character contained in the header, and the unparsed-cookie-attributes is the empty string.
3. If the name-value-pair string contains a U+3D ("=") character:
   • the (possibly empty) name string is the characters up to, but not including, the first U+3D ("=") character, and the (possibly empty) value string is the characters after the first U+3D ("=") character.
   Otherwise:
   • the name string is empty, and the value string is the entire name-value-pair string.
4. Remove any leading or trailing space from the name string and the value string.
5. The cookie-name is the name string, and the cookie-value is the value string.

The user agent MUST use the following algorithm to parse the unparsed-attributes: ¶

1. If the unparsed-attributes string is empty, skip the rest of these steps.
2. Consume the first character of the unparsed-attributes (which will be a U+3B (";") character).
3. If the remaining unparsed-attributes contains a U+3B (";") character:
   • Consume the characters of the unparsed-attributes up to, but not including, the first U+3B (";") character.
   Otherwise:
   • Consume the remainder of the unparsed-attributes.
   The characters consumed in this step comprise the attribute-value-pair string.
4. If the attribute-value-pair string contains a U+3D ("=") character:
   • the (possibly empty) name string is the characters up to, but not including, the first U+3D ("=") character, and the (possibly empty) value string is the characters after the first U+3D ("=") character .
   Otherwise:
   • the name string is the entire attribute-value-pair string, and the value string is empty. (Note that this step differs from the analogous step when parsing the name-value-pair string.)
5. Remove any leading or trailing space from the name string and the value string.
6. If the name is a ASCII case-insensitive match for an entry in the following table, process the value string as instructed.

                 
          Attribute  |  Instruction
         ------------+---------------------
          Max-Age    |  See Section [TODO]
          Expires    |  See Section [TODO] 
          Domain     |  See Section [TODO]
          Path       |  See Section [TODO]
          Secure     |  See Section [TODO]
          HttpOnly   |  See Section [TODO]
                 
               

7. Return to Step 1.

[TODO: Can parsing a cookie ever fail? Doesn't look like it! Well, unless you count "Set-Cookie: " as a fail...]¶

When the user agent finishes parsing the set-cookie-string header, the user agent *receives a cookie* from the origin server with name cookie-name, value cookie-value, and attributes cookie-attribute-list.¶

When the user agent receives a cookie, the user agent SHOULD record the cookie in its cookie store as follows.¶

A user agent MAY ignore received cookies in their entirety if the user agent is configured to block receiving cookie for a particular response. For example, the user agent might wish to block receiving cookies from "third-party" responses.¶

The user agent stores the following fields about each cookie: ¶

• name (a sequence of bytes)
• value (a sequence of bytes)
• expiry (a date)
• domain (a cookie-domain)
• path (a sequence of bytes)
• creation (a date)
• last-access (a date)
• persistent (a Boolean)
• host-only (a Boolean)
• secure-only (a Boolean)
• http-only (a Boolean)

When the user agent receives a cookie, the user agent MUST follow the following algorithm: ¶

1. Create a new cookie based on the parsed Set-Cookie header:
   1. Create a new cookie with the following default field values:
      • name = the cookie-name
      • value = the cookie-value
      • expiry = the latest representable date
      • domain = the request-host
      • path = the cookie's default-path
      • last-access = the date and time the cookie was received
      • persistent = false
      • host-only = true
      • secure-only = false
      • http-only = false
   2. Update the default field values according to the cookie-attributes:

      expiry

      If the cookie-attributes contains at least one valid Expires attribute, store the expiry-value of the last such attribute in the expiry field. Store the value true in the persistent field. [TODO: Test that this really works when mixing Max-Age and Expires.]

      domain

      If the cookie-attributes contains at least one Domain attribute, store the value of the last such attribute in the domain field. Store the value false in the host-only field. [TODO: Reject cookies for unrelated domains.] [TODO: If the URL's host is an IP address, let Domain to be an IP address if it matches the URL's host exactly, but set the host-only flag. ]

      path

      If the cookie-attributes contains at least one Path attribute, store the value of the last such attribute in the path field.

      secure-only

      If the cookie-attributes contains at least one Secure attribute, store the value true in the secure-only field.

      http-only

      If the cookie-attributes contains at least one HttpOnly attribute, store the value true in the http-only field.

2. Remove from the cookie store all cookies that have the share the same name, domain, path, and host-only fields as the newly created cookie. [TODO: Validate this list!] [TODO: There's some funny business around http-only here.]
3. Insert the newly created cookie into the cookie store.

The user agent MUST evict a cookie from the cookie store if A cookie exists in the cookie store with an expiry date in the past.¶

The user agent MAY evict a cookie from the cookie store if the number of cookies sharing a domain field exceeds some predetermined upper bound (such as 50 cookies). [TODO: Explain where 50 comes from.]¶

The user agent MAY evict cookies from the cookie store if the cookie store exceeds some maximum storage bound (such as 3000 cookies). [TODO: Explain where 3000 comes from.]¶

When the user agent evicts cookies from the cookie store, the user agent MUST evict cookies in the following priority order: ¶

1. Cookies with an expiry date in the past.
2. Cookies that share a domain field more than a predetermined number of other cookies.
3. All other cookies.

If two cookies have the same removal priority, the user agent MUST evict the cookie with the least recent last-access date first.¶

When "the current session is over", the user agent MUST remove from the cookie store all cookies with the persistent field set to false. ¶

• NOTE: This document does not define when "the current session is over." Many user agents remove non-persistent cookies when they exit. However, other user agent expire non-persistent cookies using other heuristics.

When the user agent generates an HTTP request for a particular URI, the user agent SHOULD attach exactly one HTTP header named Cookie if the cookie-string (defined below) for that URI is non-empty.¶

A user agent MAY elide the Cookie header in its entirety if the user agent is configured to block sending cookie for a particular request. For example, the user agent might wish to block sending cookies during "third-party" requests.¶

The user agent MUST use the following algorithm to compute the cookie-string from a cookie store and a URI: ¶

1. Let cookie-list be the set of cookies from the cookie store that meet the following requirements:
   • The cookie's domain field must domain-match the URI's host. [TODO: Spec me]
   • The cookie's path field must path-match the URI's path.
   • If the cookie's host-only flag is set, the cookie's domain field must denote exactly the same FQDN as the URI's host. [TODO: Internet Explorer does not implement this requirement but most other major implementations do.]
   • If the cookie's secure-only field is true, then the URI's scheme must denote a "secure" protocol.
     • NOTE: The notion of an "secure" protocol is not defined by this document. Typically, user agents consider a protocol secure if the protocol makes use of transport-layer security, such as TLS. For example, most user agents consider "https" to be a scheme that denotes a secure protocol.
   • If the cookie's http-only field is true, then include the cookie unless the cookie-string is begin generated for a "non-HTTP" API. (Note that this document does not define which APIs are "non-HTTP".)
   NOTE: The Cookie header will not contain any expired cookies because cookies past their expiry date are removed from the cookie store immediately.
2. Sort the cookie-list in the following order:
   • Cookies with longer path fields are listed before cookies with shorter path field.
   • Among cookies that have equal length path fields, cookies with earlier creation dates are listed before cookies with later creation dates.
3. Update the last-access field of each cookie in the cookie-list to the current date.
4. Serialize the cookie-list into a cookie-string by processing each cookie in the cookie-list in order:
   1. If the cookie's name and value fields are both empty, skip the remaining steps for this cookie and continue to the next cookie, if any.
   2. If the cookie's name field is non-empty, output the cookie's name field followed by the character U+3D ("=").
   3. Output the cookie's value field.
   4. If there is an unprocessed cookie in the cookie-list, output the characters U+3B and U+20 ("; ")

An origin server's content should probably be divided into disjoint application areas, some of which require the use of state information. The application areas can be distinguished by their request URLs. The Set-Cookie header can incorporate information about the application areas by setting the Path attribute for each one.¶

The session information can obviously be clear or encoded text that describes state. However, if it grows too large, it can become unwieldy. Therefore, an implementor might choose for the session information to be a key to a server-side resource. [TODO: Describe briefly how to generate a decent session key.]¶

[TODO: We could recommend that servers encrypt and mac their cookie data.]¶

[TODO: Mention issues that arise from having multiple concurrent sessions.]¶

Practical user agent implementations have limits on the number and size of cookies that they can store. General-use user agents SHOULD provide each of the following minimum capabilities: ¶

• At least 4096 bytes per cookie (as measured by the size of the characters that comprise the cookie non-terminal in the syntax description of the Set-Cookie header). [TODO: Validate]
• At least 50 cookies per domain. [TODO: History lesson]
• At least 3000 cookies total.

The information in a Set-Cookie response header must be retained in its entirety. If for some reason there is inadequate space to store the cookie, the cookie must be discarded, not truncated.¶

Applications should use as few and as small cookies as possible, and they should cope gracefully with the loss of a cookie. [TODO: Could mention latency issues that arise from having tons of cookies.]¶

The information in the Set-Cookie and Cookie headers is transmitted in the clear. Three consequences are: ¶

1. Any sensitive information that is conveyed in in the headers is exposed to an eavesdropper.
2. A malicious intermediary could alter the headers as they travel in either direction, with unpredictable results.
3. A malicious client could alter the Cookie header before transmission, with unpredictable results.

These facts imply that information of a personal and/or financial nature should be sent over a secure channel. For less sensitive information, or when the content of the header is a database key, an origin server should be vigilant to prevent a bad Cookie value from causing failures.¶

[TODO: Weak isolation by port.]¶

[TODO: Weak isolation by scheme (e.g., ftp, gopher, etc).]¶

[TODO: Mention integrity issue where a sibling domain can inject cookies.]¶

[TODO: Mention integrity issue where a HTTP can inject cookies into HTTPS.]¶