draft-ietf-httpstate-cookie-06.txt   draft-ietf-httpstate-cookie-07.txt 
httpstate A. Barth httpstate A. Barth
Internet-Draft U.C. Berkeley Internet-Draft U.C. Berkeley
Obsoletes: 2109 (if approved) April 16, 2010 Obsoletes: 2109 (if approved) April 18, 2010
Intended status: Standards Track Intended status: Standards Track
Expires: October 18, 2010 Expires: October 20, 2010
HTTP State Management Mechanism HTTP State Management Mechanism
draft-ietf-httpstate-cookie-06 draft-ietf-httpstate-cookie-07
Abstract Abstract
This document defines the HTTP Cookie and Set-Cookie headers. These This document defines the HTTP Cookie and Set-Cookie headers. These
headers can be used by HTTP servers to store state on HTTP user headers can be used by HTTP servers to store state (called cookies)
agents, letting the servers maintain a stateful session over the at HTTP user agents, letting the servers maintain a stateful session
mostly stateless HTTP protocol. The cookie protocol has many over the mostly stateless HTTP protocol. Although cookies have many
historical infelicities that degrade its security and privacy. historical infelicities that degrade their security and privacy, the
Cookie and Set-Cookie headers are widely used on the Internet.
NOTE: If you have suggestions for improving the draft, please send Editorial Note (To be removed by RFC Editor)
email to http-state@ietf.org. Suggestions with test cases are
especially appreciated. If you have suggestions for improving this document, please send
email to http-state@ietf.org. Suggestions with test cases are
especially appreciated. https://tools.ietf.org/wg/httpstate/
Status of this Memo Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet- other groups may also distribute working documents as Internet-
Drafts. Drafts.
skipping to change at page 1, line 45 skipping to change at page 2, line 32
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on October 18, 2010. This Internet-Draft will expire on October 20, 2010.
Copyright Notice Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the Copyright (c) 2010 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
skipping to change at page 3, line 14 skipping to change at page 3, line 21
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
2. General Nonsense . . . . . . . . . . . . . . . . . . . . . . . 6 2. General Nonsense . . . . . . . . . . . . . . . . . . . . . . . 6
2.1. Conformance Criteria . . . . . . . . . . . . . . . . . . . 6 2.1. Conformance Criteria . . . . . . . . . . . . . . . . . . . 6
2.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 6 2.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 6
2.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 2.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6
3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 7
4. A Well-Behaved Profile . . . . . . . . . . . . . . . . . . . . 10 4. Server Requirements . . . . . . . . . . . . . . . . . . . . . 10
4.1. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . . 10 4.1. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . . 10
4.1.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . 10 4.1.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . 10
4.1.2. Semantics (Non-Normative) . . . . . . . . . . . . . . 11 4.1.2. Semantics (Non-Normative) . . . . . . . . . . . . . . 11
4.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . 13 4.2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2.2. Semantics . . . . . . . . . . . . . . . . . . . . . . 14 4.2.2. Semantics . . . . . . . . . . . . . . . . . . . . . . 14
5. The Cookie Protocol . . . . . . . . . . . . . . . . . . . . . 15 5. User Agent Requirements . . . . . . . . . . . . . . . . . . . 15
5.1. Algorithms . . . . . . . . . . . . . . . . . . . . . . . . 15 5.1. Algorithms . . . . . . . . . . . . . . . . . . . . . . . . 15
5.1.1. Dates . . . . . . . . . . . . . . . . . . . . . . . . 15 5.1.1. Dates . . . . . . . . . . . . . . . . . . . . . . . . 15
5.1.2. Domains . . . . . . . . . . . . . . . . . . . . . . . 17 5.1.2. Domains . . . . . . . . . . . . . . . . . . . . . . . 17
5.1.3. Paths . . . . . . . . . . . . . . . . . . . . . . . . 17 5.1.3. Paths . . . . . . . . . . . . . . . . . . . . . . . . 17
5.2. The Set-Cookie Header . . . . . . . . . . . . . . . . . . 18 5.2. The Set-Cookie Header . . . . . . . . . . . . . . . . . . 18
5.2.1. The Max-Age Attribute . . . . . . . . . . . . . . . . 20 5.2.1. The Expires Attribute . . . . . . . . . . . . . . . . 20
5.2.2. The Expires Attribute . . . . . . . . . . . . . . . . 20 5.2.2. The Max-Age Attribute . . . . . . . . . . . . . . . . 20
5.2.3. The Domain Attribute . . . . . . . . . . . . . . . . . 21 5.2.3. The Domain Attribute . . . . . . . . . . . . . . . . . 21
5.2.4. The Path Attribute . . . . . . . . . . . . . . . . . . 21 5.2.4. The Path Attribute . . . . . . . . . . . . . . . . . . 21
5.2.5. The Secure Attribute . . . . . . . . . . . . . . . . . 22 5.2.5. The Secure Attribute . . . . . . . . . . . . . . . . . 22
5.2.6. The HttpOnly Attribute . . . . . . . . . . . . . . . . 22 5.2.6. The HttpOnly Attribute . . . . . . . . . . . . . . . . 22
5.3. Storage Model . . . . . . . . . . . . . . . . . . . . . . 22 5.3. Storage Model . . . . . . . . . . . . . . . . . . . . . . 22
5.4. The Cookie Header . . . . . . . . . . . . . . . . . . . . 25 5.4. The Cookie Header . . . . . . . . . . . . . . . . . . . . 25
6. Implementation Considerations . . . . . . . . . . . . . . . . 28 6. Implementation Considerations . . . . . . . . . . . . . . . . 28
6.1. Limits . . . . . . . . . . . . . . . . . . . . . . . . . . 28 6.1. Limits . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.2. Application Programmer Interfaces . . . . . . . . . . . . 28 6.2. Application Programmer Interfaces . . . . . . . . . . . . 28
7. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 29 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 29
skipping to change at page 5, line 7 skipping to change at page 5, line 7
8.6. Weak Integrity . . . . . . . . . . . . . . . . . . . . . . 33 8.6. Weak Integrity . . . . . . . . . . . . . . . . . . . . . . 33
8.7. Reliance on DNS . . . . . . . . . . . . . . . . . . . . . 34 8.7. Reliance on DNS . . . . . . . . . . . . . . . . . . . . . 34
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 35 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 35
9.1. Normative References . . . . . . . . . . . . . . . . . . . 35 9.1. Normative References . . . . . . . . . . . . . . . . . . . 35
9.2. Informative References . . . . . . . . . . . . . . . . . . 35 9.2. Informative References . . . . . . . . . . . . . . . . . . 35
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 36 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 36
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 37 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 37
1. Introduction 1. Introduction
This document defines the HTTP Cookie and Set-Cookie header. Using This document defines the HTTP Cookie and Set-Cookie headers. Using
the Set-Cookie header, an HTTP server can store name/value pairs and the Set-Cookie header, an HTTP server can store name/value pairs and
associated metadata (called cookies) at the user agent. When the associated metadata (called cookies) at the user agent. When the
user agent makes subsequent requests to the server, the user agent user agent makes subsequent requests to the server, the user agent
uses the metadata to determine whether to return the name/value pairs uses the metadata to determine whether to return the name/value pairs
in the Cookie header. in the Cookie header.
Although simple on its surface, the cookie protocol has a number of Although simple on its surface, cookies have a number of
complexities. For example, the server indicates a scope for each complexities. For example, the server indicates a scope for each
cookie when sending them to the user agent. The scope indicates the cookie when sending them to the user agent. The scope indicates the
maximum amount of time the user agent should retain the cookie, to maximum amount of time the user agent should retain the cookie, to
which servers the user agent should return the cookie, and for which which servers the user agent should return the cookie, and for which
protocols the cookie is applicable. protocols the cookie is applicable.
For historical reasons, the cookie protocol contains a number of For historical reasons, cookies contain a number of security and
security and privacy infelicities. For example, a server can privacy infelicities. For example, a server can indicate that a
indicate that a given cookie is intended for "secure" connections, given cookie is intended for "secure" connections, but the Secure
but the Secure attribute provides only confidentiality (not attribute provides only confidentiality (not integrity) from active
integrity) from active network attackers. Similarly, cookies for a network attackers. Similarly, cookies for a given host are shared
given host are shared across all the ports on that host, even though across all the ports on that host, even though the usual "same-origin
the usual "same-origin policy" used by web browsers isolates content policy" used by web browsers isolates content retrieved from
retrieved from different ports. different ports.
2. General Nonsense 2. General Nonsense
2.1. Conformance Criteria 2.1. Conformance Criteria
The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT",
"RECOMMENDED", "MAY", and "OPTIONAL" in document are to be "RECOMMENDED", "MAY", and "OPTIONAL" in document are to be
interpreted as described in [RFC2119]. interpreted as described in [RFC2119].
Requirements phrased in the imperative as part of algorithms (such as Requirements phrased in the imperative as part of algorithms (such as
skipping to change at page 7, line 8 skipping to change at page 7, line 8
the same meaning as in the HTTP/1.1 specification ([RFC2616]). the same meaning as in the HTTP/1.1 specification ([RFC2616]).
The terms request-host and request-URI refer to the values the user The terms request-host and request-URI refer to the values the user
agent would send to the server as, respectively, the host (but not agent would send to the server as, respectively, the host (but not
port) and abs_path portions of the absoluteURI (http_URL) of the HTTP port) and abs_path portions of the absoluteURI (http_URL) of the HTTP
Request-Line. Request-Line.
3. Overview 3. Overview
We outline here a way for an origin server to send state information We outline here a way for an origin server to send state information
to a user agent, and for the user agent to return the state to a user agent and for the user agent to return the state
information to the origin server. information to the origin server.
To initiate a session, the origin server includes a Set-Cookie header To store state, the origin server includes a Set-Cookie header in an
in an HTTP response. (Note that "session" here does not refer to a HTTP response. In subsequent requests, the user agent returns a
persistent network connection but to a logical session created from Cookie request header to the origin server. The Cookie header
HTTP requests and responses. The presence or absence of a persistent contains a number of cookies the user agent received in previous Set-
connection should have no effect on the use of cookie-derived Cookie headers. The origin server is free to ignore the Cookie
sessions). header or use its contents for an application-defined purpose. The
origin server MAY send the user agent a Set-Cookie response header
The user agent returns a Cookie request header to the origin server with the same or different information, or it MAY send no Set-Cookie
if it chooses to continue a session. The Cookie header contains a header at all.
number of cookies the user agent received in previous Set-Cookie
headers. The origin server MAY ignore the Cookie header or use the
header to determine the current state of the session. The origin
server MAY send the user agent a Set-Cookie response header with the
same or different information, or it MAY send no Set-Cookie header at
all.
Servers MAY return a Set-Cookie response header with any response. Servers MAY return a Set-Cookie response header with any response.
User agents SHOULD send a Cookie request header, subject to other User agents SHOULD send a Cookie request header, subject to other
rules detailed below, with every request. rules detailed below, with every request.
An origin server MAY include multiple Set-Cookie header fields in a An origin server MAY include multiple Set-Cookie header fields in a
single response. Note that an intervening gateway MUST NOT fold single response. Note that an intervening gateway MUST NOT fold
multiple Set-Cookie header fields into a single header field. multiple Set-Cookie header fields into a single header field.
If a server sends multiple responses containing Set-Cookie headers If a server sends multiple responses containing Set-Cookie headers
concurrently to the user agent (e.g., when communicating with the concurrently to the user agent (e.g., when communicating with the
user agent over multiple sockets), these responses create a "race user agent over multiple sockets), these responses create a "race
condition" that can lead to unpredictable behavior. condition" that can lead to unpredictable behavior.
3.1. Examples 3.1. Examples
Using the cookie protocol, a server can send the user agent a short Using the Set-Cookie header, a server can send the user agent a short
string in an HTTP response that the user agent will return in future string in an HTTP response that the user agent will return in future
HTTP requests. For example, the server can send the user agent a HTTP requests. For example, the server can send the user agent a
"session identifier" named SID with the value 31d4d96e407aad42. The "session identifier" named SID with the value 31d4d96e407aad42. The
user agent then returns the session identifier in subsequent user agent then returns the session identifier in subsequent
requests. requests.
== Server -> User Agent == == Server -> User Agent ==
Set-Cookie: SID=31d4d96e407aad42 Set-Cookie: SID=31d4d96e407aad42
== User Agent -> Server == == User Agent -> Server ==
Cookie: SID=31d4d96e407aad42 Cookie: SID=31d4d96e407aad42
The server can alter the default scope of the cookie using the Path The server can alter the default scope of the cookie using the Path
and Domain attributes. For example, the server can instruct the user and Domain attributes. For example, the server can instruct the user
agent to return the cookie to every path and every subdomain of agent to return the cookie to every path and every subdomain of
example.com. example.com.
== Server -> User Agent == == Server -> User Agent ==
Set-Cookie: SID=31d4d96e407aad42; Path=/; Domain=.example.com Set-Cookie: SID=31d4d96e407aad42; Path=/; Domain=.example.com
skipping to change at page 8, line 18 skipping to change at page 8, line 13
and Domain attributes. For example, the server can instruct the user and Domain attributes. For example, the server can instruct the user
agent to return the cookie to every path and every subdomain of agent to return the cookie to every path and every subdomain of
example.com. example.com.
== Server -> User Agent == == Server -> User Agent ==
Set-Cookie: SID=31d4d96e407aad42; Path=/; Domain=.example.com Set-Cookie: SID=31d4d96e407aad42; Path=/; Domain=.example.com
== User Agent -> Server == == User Agent -> Server ==
Cookie: SID=31d4d96e407aad42 Cookie: SID=31d4d96e407aad42
The server can store multiple cookies in the user agent. For The server can store multiple cookies at the user agent. For
example, the server can store a session identifier as well as the example, the server can store a session identifier as well as the
user's preferred language by returning two Set-Cookie response user's preferred language by returning two Set-Cookie header fields.
headers. Notice that the server uses the Secure and HttpOnly Notice that the server uses the Secure and HttpOnly attributes to
attributes to provide additional security protections for the more- provide additional security protections for the more-sensitive
sensitive session identifier. session identifier.
== Server -> User Agent == == Server -> User Agent ==
Set-Cookie: SID=31d4d96e407aad42; Path=/; Secure; HttpOnly Set-Cookie: SID=31d4d96e407aad42; Path=/; Secure; HttpOnly
Set-Cookie: lang=en-US; Path=/; Domain=.example.com Set-Cookie: lang=en-US; Path=/; Domain=.example.com
== User Agent -> Server == == User Agent -> Server ==
Cookie: SID=31d4d96e407aad42; lang=en-US Cookie: SID=31d4d96e407aad42; lang=en-US
If the server wishes the user agent to persist the cookie over If the server wishes the user agent to persist the cookie over
multiple sessions, the server can specify a expiration date in the multiple sessions, the server can specify a expiration date in the
Expires attribute. Note that the user agent might might delete the Expires attribute. Note that the user agent might delete the cookie
cookie before the expiration date if the user agent's cookie store before the expiration date if the user agent's cookie store exceeds
exceeds its quota or if the user manually deletes the server's its quota or if the user manually deletes the server's cookie.
cookie.
== Server -> User Agent == == Server -> User Agent ==
Set-Cookie: lang=en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT Set-Cookie: lang=en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT
== User Agent -> Server == == User Agent -> Server ==
Cookie: lang=en-US Cookie: lang=en-US
Finally, to remove a cookie, the server returns a Set-Cookie header Finally, to remove a cookie, the server returns a Set-Cookie header
with an expiration date in the past. The server will be successful with an expiration date in the past. The server will be successful
in removing the cookie only if the Path and the Domain attribute in in removing the cookie only if the Path and the Domain attribute in
the Set-Cookie header match the values used when the cookie was the Set-Cookie header match the values used when the cookie was
created. created.
== Server -> User Agent == == Server -> User Agent ==
Set-Cookie: lang=; Expires=Sun, 06 Nov 1994 08:49:37 GMT Set-Cookie: lang=; Expires=Sun, 06 Nov 1994 08:49:37 GMT
== User Agent -> Server == == User Agent -> Server ==
skipping to change at page 10, line 5 skipping to change at page 10, line 5
in removing the cookie only if the Path and the Domain attribute in in removing the cookie only if the Path and the Domain attribute in
the Set-Cookie header match the values used when the cookie was the Set-Cookie header match the values used when the cookie was
created. created.
== Server -> User Agent == == Server -> User Agent ==
Set-Cookie: lang=; Expires=Sun, 06 Nov 1994 08:49:37 GMT Set-Cookie: lang=; Expires=Sun, 06 Nov 1994 08:49:37 GMT
== User Agent -> Server == == User Agent -> Server ==
(No Cookie header) (No Cookie header)
4. A Well-Behaved Profile 4. Server Requirements
This section describes the syntax and semantics of a well-behaved This section describes the syntax and semantics of a well-behaved
profile of the protocol. Servers SHOULD use the profile described in profile of the Cookie and Set-Cookie headers. Servers SHOULD use the
this section, both to maximize interoperability with existing user profile described in this section, both to maximize interoperability
agents and because a future version of the cookie protocol could with existing user agents and because a future version of the Cookie
remove support for some of the most esoteric aspects of the protocol. or Set-Cookie headers could remove support for some of the most
User agents, however, MUST implement the full protocol to ensure esoteric semantics. User agents, however, MUST implement the full
interoperability with servers making use of the full protocol. semantics to ensure interoperability with servers making use of the
full semantics.
4.1. Set-Cookie 4.1. Set-Cookie
The Set-Cookie header is used to send cookies from the server to the The Set-Cookie header is used to send cookies from the server to the
user agent. user agent.
4.1.1. Syntax 4.1.1. Syntax
Informally, the Set-Cookie response header comprises the token Set- Informally, the Set-Cookie response header comprises the token Set-
Cookie:, followed by a cookie. Each cookie begins with a name-value- Cookie:, followed by a cookie. Each cookie begins with a name-value-
skipping to change at page 11, line 19 skipping to change at page 11, line 20
To maximize compatibility with user agents, servers that wish to To maximize compatibility with user agents, servers that wish to
store non-ASCII data in a cookie-value SHOULD encode that data using store non-ASCII data in a cookie-value SHOULD encode that data using
a printable ASCII encoding, such as base64. a printable ASCII encoding, such as base64.
NOTE: Some user agents represent dates using 32-bit integers. Some NOTE: Some user agents represent dates using 32-bit integers. Some
of these user agents might contain bugs that cause them process dates of these user agents might contain bugs that cause them process dates
after the year 2038 incorrectly. Servers wishing to interoperate after the year 2038 incorrectly. Servers wishing to interoperate
with these user agents might wish to use dates before 2038. with these user agents might wish to use dates before 2038.
NOTE: The syntax above allows whitespace between the attribute and NOTE: The syntax above allows whitespace around the U+003D ("=")
the U+003D ("=") character. Servers wishing to interoperate with characters. Servers wishing to interoperate with some legacy user
some legacy user agents might wish to omit this whitespace. agents might wish to omit this whitespace.
4.1.2. Semantics (Non-Normative) 4.1.2. Semantics (Non-Normative)
This section describes a simplified semantics of the Set-Cookie This section describes a simplified semantics of the Set-Cookie
header. These semantics are detailed enough to be useful for header. These semantics are detailed enough to be useful for
understanding the most common uses of the cookie protocol. The full understanding the most common uses of cookies. The full semantics
semantics are described in Section 5. are described in Section 5.
When the user agent receives a Set-Cookie header, the user agent When the user agent receives a Set-Cookie header, the user agent
stores the cookie in its cookie store. When the user agent stores the cookie in its cookie store. Subsequently, when the user
subsequently makes an HTTP request, the user agent consults its agent makes an HTTP request, the user agent consults its cookie store
cookie store and includes the applicable, non-expired cookies in the and includes the applicable, non-expired cookies in the Cookie
Cookie header. header.
If the cookie store already contains a cookie with the same cookie- If the user agent receives a new cookie with the same cookie-name,
name, domain-value, and path-value, the existing cookie is evicted domain-value, and path-value as a cookie that already exists in its
from the cookie store and replaced with the new value. Notice that cookie store, the existing cookie is evicted from the cookie store
servers can delete cookies by including an Expires attribute with a and replaced with the new cookie. Notice that servers can delete
value in the past. cookies by sending the user agent a new cookie with an Expires
attribute with a value in the past.
Unless the cookie's attributes indicate otherwise, the cookie is Unless the cookie's attributes indicate otherwise, the cookie is
returned only to the origin server, and it expires at the end of the returned only to the origin server, and it expires at the end of the
current session (as defined by the user agent). User agents ignore current session (as defined by the user agent). User agents ignore
unrecognized cookie attributes. unrecognized cookie attributes.
4.1.2.1. Expires 4.1.2.1. The Expires Attribute
The Expires attribute indicates the maximum lifetime of the cookie, The Expires attribute indicates the maximum lifetime of the cookie,
represented as the date and time at which the cookie expires. The represented as the date and time at which the cookie expires. The
user agent is not required to retain the cookie until the specified user agent is not required to retain the cookie until the specified
date has passed. In fact, user agents often evict cookies from the date has passed. In fact, user agents often evict cookies from the
cookie store due to memory pressure or privacy concerns. cookie store due to memory pressure or privacy concerns.
4.1.2.2. Max-Age 4.1.2.2. The Max-Age Attribute
The Max-Age attribute indicates the maximum lifetime of the cookie, The Max-Age attribute indicates the maximum lifetime of the cookie,
represented as the number of seconds until the cookie expires. The represented as the number of seconds until the cookie expires. The
user agent is not required to retain the cookie until the specified user agent is not required to retain the cookie until the specified
date has passed. In fact, user agents often evict cookies from the date has passed. In fact, user agents often evict cookies from the
cookie store due to memory pressure or privacy concerns. cookie store due to memory pressure or privacy concerns.
WARNING: Not all user agents support the Max-Age attribute. User WARNING: Not all user agents support the Max-Age attribute. User
agents that do not support the Max-Age attribute will retain the agents that do not support the Max-Age attribute will retain the
cookie for the current session only. cookie for the current session only.
If a cookie has both the Max-Age and the Expires attribute, the Max- If a cookie has both the Max-Age and the Expires attribute, the Max-
Age attribute has precedence and controls the expiration date of the Age attribute has precedence and controls the expiration date of the
cookie. cookie.
4.1.2.3. Domain 4.1.2.3. The Domain Attribute
The Domain attribute specifies those hosts for which the cookie will The Domain attribute specifies those hosts to which the cookie will
be sent. For example, if the Domain attribute contains the value be sent. For example, if the Domain attribute contains the value
".example.com", the user agent will include the cookie in the Cookie "example.com", the user agent will include the cookie in the Cookie
header when making HTTP requests to example.com, www.example.com, and header when making HTTP requests to example.com, www.example.com, and
www.corp.example.com. (Note that a leading U+002E ("."), if present, www.corp.example.com. (Note that a leading U+002E ("."), if present,
is ignored.) If the server omits the Domain attribute, the user is ignored.) If the server omits the Domain attribute, the user
agent will return the cookie only to the origin server. agent will return the cookie only to the origin server.
WARNING: Some legacy user agents treat an absent Domain attribute WARNING: Some legacy user agents treat an absent Domain attribute
as if the Domain attribute were present and contained the current as if the Domain attribute were present and contained the current
host name. For example, if example.com returns a Set-Cookie host name. For example, if example.com returns a Set-Cookie
header without a Domain attribute, these user agents will send the header without a Domain attribute, these user agents will
cookie to www.example.com. erroneously send the cookie to www.example.com.
The user agent will reject cookies (refuse to store them in the The user agent will reject cookies (refuse to store them in the
cookie store) unless the Domain attribute specifies a scope for the cookie store) unless the Domain attribute specifies a scope for the
cookie that would include the origin server. For example, the user cookie that would include the origin server. For example, the user
agent will accept a Domain attribute of ".example.com" or of agent will accept a Domain attribute of "example.com" or of
".foo.example.com" from foo.example.com, but the user agent will not "foo.example.com" from foo.example.com, but the user agent will not
accept a Domain attribute of ".bar.example.com" or of accept a Domain attribute of "bar.example.com" or of
".baz.foo.example.com". "baz.foo.example.com".
NOTE: For security reasons, some user agents are configured to reject NOTE: For security reasons, some user agents are configured to reject
Domain attributes that do not correspond to a "registry controlled" Domain attributes that correspond to "public suffixes." For example,
domain (or a subdomain of a registry controlled domain). For some user agents will reject Domain attributes of "com" or "co.uk".
example, some user agents will reject Domain attributes of ".com" or
".co.uk".
4.1.2.4. Path 4.1.2.4. The Path Attribute
The Path attribute limits the scope of the cookie to a set of paths. The Path attribute limits the scope of the cookie to a set of paths.
When a cookie has a Path attribute, the user agent will include the When a cookie has a Path attribute, the user agent will include the
cookie in an HTTP request only if the path portion of the Request-URI cookie in an HTTP request only if the path portion of the Request-URI
matches (or is a subdirectory of) the cookie's Path attribute, where matches (or is a subdirectory of) the cookie's Path attribute, where
the U+002F ("/") character is interpreted as a directory separator. the U+002F ("/") character is interpreted as a directory separator.
If the server omits the Path attribute, the user agent will use the If the server omits the Path attribute, the user agent will use the
directory of the Request-URI's path component as the default value. directory of the Request-URI's path component as the default value.
Although seemingly useful for isolating cookies between different Although seemingly useful for isolating cookies between different
paths within a given domain, the Path attribute cannot be relied upon paths within a given domain, the Path attribute cannot be relied upon
for security for two reasons: First, user agents do not prevent one for security for two reasons:
path from overwriting the cookies for another path. For example, if
a response to a request for /foo/bar.html attempts to set a cookie
with a Path attribute of "/baz" the user agent will store that cookie
in the cookie store. Second, the "same-origin" policy implemented by
many user agents does not isolate different paths within an origin.
For example, /foo/bar.html can read cookies with a Path attribute of
"/baz" because they are within the "same origin".
4.1.2.5. Secure 1. User agents do not prevent one path from overwriting the cookies
for another path. For example, if a response to a request for
/foo/bar.html attempts to set a cookie with a Path attribute of
"/baz" the user agent will store that cookie in the cookie store.
2. The "same-origin" policy implemented by many user agents does not
isolate different paths within an origin. For example, /foo/
bar.html can read cookies with a Path attribute of "/baz" because
they are within the "same origin".
4.1.2.5. The Secure Attribute
The Secure attribute limits the scope of the cookie to "secure" The Secure attribute limits the scope of the cookie to "secure"
channels (where "secure" is defined by the user agent). When a channels (where "secure" is defined by the user agent). When a
cookie has the Secure attribute, the user agent will include the cookie has the Secure attribute, the user agent will include the
cookie in an HTTP request only if the request is transmitted over a cookie in an HTTP request only if the request is transmitted over a
secure channel (typically TLS [RFC5246]). secure channel (typically TLS [RFC5246]).
Although seemingly useful for protecting cookies from active network Although seemingly useful for protecting cookies from active network
attackers, the Secure attribute protects only the cookie's attackers, the Secure attribute protects only the cookie's
confidentiality. An active network attacker can overwrite Secure confidentiality. An active network attacker can overwrite Secure
cookies from an insecure channel, disrupting the integrity of the cookies from an insecure channel, disrupting its integrity.
cookies.
4.1.2.6. HttpOnly 4.1.2.6. The HttpOnly Attribute
The HttpOnly attribute limits the scope of the cookie to HTTP The HttpOnly attribute limits the scope of the cookie to HTTP
requests. In particular, the attribute instructs the user agent to requests. In particular, the attribute instructs the user agent to
omit the cookie when providing access to its cookie store via "non- omit the cookie when providing access to its cookie store via "non-
HTTP" APIs (as defined by the user agent). HTTP" APIs (as defined by the user agent).
4.2. Cookie 4.2. Cookie
4.2.1. Syntax 4.2.1. Syntax
skipping to change at page 14, line 14 skipping to change at page 14, line 21
section, the requirements in the next section will cause the user section, the requirements in the next section will cause the user
agent to return a Cookie header that conforms to the following agent to return a Cookie header that conforms to the following
grammar: grammar:
cookie-header = "Cookie:" OWS cookie-string OWS cookie-header = "Cookie:" OWS cookie-string OWS
cookie-string = cookie-pair *( ";" cookie-pair ) cookie-string = cookie-pair *( ";" cookie-pair )
4.2.2. Semantics 4.2.2. Semantics
Each cookie-pair represents a cookie stored by the user agent. The Each cookie-pair represents a cookie stored by the user agent. The
cookie-name and the cookie-value are returned verbatim from the cookie-name and the cookie-value are returned from the corresponding
corresponding parts of the Set-Cookie header. parts of the Set-Cookie header.
Notice that the cookie attributes are not returned. In particular, Notice that the cookie attributes are not returned. In particular,
the server cannot determine from the Cookie header alone when a the server cannot determine from the Cookie header alone when a
cookie will expire, for which domains the cookie is valid, for which cookie will expire, for which domains the cookie is valid, for which
paths the cookie is valid, or whether the cookie was set with the paths the cookie is valid, or whether the cookie was set with the
Secure or HttpOnly attributes. Secure or HttpOnly attributes.
The semantics of individual cookies in the Cookie header is not The semantics of individual cookies in the Cookie header is not
defined by this document. Servers are expected to imbue these defined by this document. Servers are expected to imbue these
cookies with server-specific semantics. cookies with application-specific semantics.
Although cookies are serialized linearly in the Cookie header, Although cookies are serialized linearly in the Cookie header,
servers SHOULD NOT rely upon the serialization order. In particular, servers SHOULD NOT rely upon the serialization order. In particular,
if the Cookie header contains two cookies with the same name, servers if the Cookie header contains two cookies with the same name, servers
SHOULD NOT rely upon the order in which these cookies appear in the SHOULD NOT rely upon the order in which these cookies appear in the
header. header.
5. The Cookie Protocol 5. User Agent Requirements
For historical reasons, the full cookie protocol contains a number of For historical reasons, the full semantics of cookies contains a
exotic quirks. This section is intended to specify the cookie number of exotic quirks. This section is intended to specify the
protocol in enough detail to enable a user agent that implements the Cookie and Set-Cookie headers in sufficient detail to allow a user
protocol precisely as specified to interoperate with existing agent implementing these requirements precisely to interoperate with
servers. existing servers.
Conformance requirements phrased as algorithms or specific steps may Conformance requirements phrased as algorithms or specific steps MAY
be implemented in any manner, so long as the end result is be implemented in any manner, so long as the end result is
equivalent. (In particular, the algorithms defined in this equivalent. In particular, the algorithms defined in this
specification are intended to be easy to follow, and not intended to specification are intended to be easy to understand and are not
be performant.) intended to be performant.
5.1. Algorithms 5.1. Algorithms
This section defines a number of algorithms used by the cookie This section defines a number of algorithms used by user agents to
protocol. process the Cookie and Set-Cookie headers.
5.1.1. Dates 5.1.1. Dates
The user agent MUST use the following algorithm to *parse a cookie- The user agent MUST use the following algorithm to *parse a cookie-
date*: date*:
1. Using the grammar below, divide the cookie-date into date-tokens. 1. Using the grammar below, divide the cookie-date into date-tokens.
cookie-date = *delimiter date-token-list *delimiter cookie-date = *delimiter date-token-list *delimiter
date-token-list = date-token *( 1*delimiter date-token ) date-token-list = date-token *( 1*delimiter date-token )
skipping to change at page 18, line 22 skipping to change at page 18, line 22
5.2. The Set-Cookie Header 5.2. The Set-Cookie Header
When a user agent receives a Set-Cookie header in an HTTP response, When a user agent receives a Set-Cookie header in an HTTP response,
the user agent *receives a set-cookie-string* consisting of the value the user agent *receives a set-cookie-string* consisting of the value
of the header. of the header.
A user agent MUST use the following algorithm to parse set-cookie- A user agent MUST use the following algorithm to parse set-cookie-
strings: strings:
1. If the set-cookie-string is empty or consists entirely of WSP 1. If the set-cookie-string is empty or consists entirely of WSP
characters, the user agent MAY ignore the set-cookie-string characters, ignore the set-cookie-string entirely.
entirely.
2. If the set-cookie-string contains a U+003B (";") character: 2. If the set-cookie-string contains a U+003B (";") character:
The name-value-pair string consists of the characters up to, The name-value-pair string consists of the characters up to,
but not including, the first U+003B (";"), and the unparsed- but not including, the first U+003B (";"), and the unparsed-
attributes consist of the remainder of the set-cookie-string attributes consist of the remainder of the set-cookie-string
(including the U+003B (";") in question). (including the U+003B (";") in question).
Otherwise: Otherwise:
skipping to change at page 19, line 40 skipping to change at page 19, line 37
The (possibly empty) attribute-name string consists of the The (possibly empty) attribute-name string consists of the
characters up to, but not including, the first U+003D ("=") characters up to, but not including, the first U+003D ("=")
character, and the (possibly empty) attribute-value string character, and the (possibly empty) attribute-value string
consists of the characters after the first U+003D ("=") consists of the characters after the first U+003D ("=")
character. character.
Otherwise: Otherwise:
The attribute-name string consists of the entire cookie-av The attribute-name string consists of the entire cookie-av
string, and the attribute-value string is empty. (Note that string, and the attribute-value string is empty.
this step differs from the analogous step when parsing the
name-value-pair string.)
5. Remove any leading or trailing WSP characters from the attribute- 5. Remove any leading or trailing WSP characters from the attribute-
name string and the attribute-value string. name string and the attribute-value string.
6. Process the attribute-name and attribute-value according to the 6. Process the attribute-name and attribute-value according to the
requirements in the following subsections. requirements in the following subsections.
7. Return to Step 1. 7. Return to Step 1.
When the user agent finishes parsing the set-cookie-string, the user When the user agent finishes parsing the set-cookie-string, the user
agent *receives a cookie* from the Request-URI with name cookie-name, agent *receives a cookie* from the Request-URI with name cookie-name,
value cookie-value, and attributes cookie-attribute-list. value cookie-value, and attributes cookie-attribute-list.
5.2.1. The Max-Age Attribute 5.2.1. The Expires Attribute
If the attribute-name case-insensitively matches the string "Max-
Age", the user agent MUST process the cookie-av as follows.
If the first character of the attribute-value is not a DIGIT or a "-"
character, ignore the cookie-av.
If the remainder of attribute-value contains a non-DIGIT character,
ignore the cookie-av.
Let delta-seconds be the attribute-value converted to an integer.
If delta-seconds is less than or equal to zero (0), let expiry-time
be the current date and time. Otherwise, let the expiry-time be the
current date and time plus delta-seconds seconds.
Append an attribute to the cookie-attribute-list with an attribute-
name of Max-Age and an attribute-value of expiry-time.
5.2.2. The Expires Attribute
If the attribute-name case-insensitively matches the string If the attribute-name case-insensitively matches the string
"Expires", the user agent MUST process the cookie-av as follows. "Expires", the user agent MUST process the cookie-av as follows.
Let the parsed-cookie-date be the result of parsing the attribute- Let the parsed-cookie-date be the result of parsing the attribute-
value as cookie-date. value as cookie-date.
If the attribute-value failed to parse as a cookie date, ignore the If the attribute-value failed to parse as a cookie date, ignore the
cookie-av. cookie-av.
skipping to change at page 21, line 20 skipping to change at page 20, line 45
represent, the user agent MAY replace the expiry-time with the last represent, the user agent MAY replace the expiry-time with the last
representable date. representable date.
If the expiry-time is earlier than the first date the user agent can If the expiry-time is earlier than the first date the user agent can
represent, the user agent MAY replace the expiry-time with the first represent, the user agent MAY replace the expiry-time with the first
representable date. representable date.
Append an attribute to the cookie-attribute-list with an attribute- Append an attribute to the cookie-attribute-list with an attribute-
name of Expires and an attribute-value of expiry-time. name of Expires and an attribute-value of expiry-time.
5.2.2. The Max-Age Attribute
If the attribute-name case-insensitively matches the string "Max-
Age", the user agent MUST process the cookie-av as follows.
If the first character of the attribute-value is not a DIGIT or a "-"
character, ignore the cookie-av.
If the remainder of attribute-value contains a non-DIGIT character,
ignore the cookie-av.
Let delta-seconds be the attribute-value converted to an integer.
If delta-seconds is less than or equal to zero (0), let expiry-time
be the earliest representable date and time. Otherwise, let the
expiry-time be the current date and time plus delta-seconds seconds.
Append an attribute to the cookie-attribute-list with an attribute-
name of Max-Age and an attribute-value of expiry-time.
5.2.3. The Domain Attribute 5.2.3. The Domain Attribute
If the attribute-name case-insensitively matches the string "Domain", If the attribute-name case-insensitively matches the string "Domain",
the user agent MUST process the cookie-av as follows. the user agent MUST process the cookie-av as follows.
If the attribute-value is empty, the behavior is undefined. However, If the attribute-value is empty, the behavior is undefined. However,
user agent SHOULD ignore the cookie-av entirely. user agent SHOULD ignore the cookie-av entirely.
If the first character of the attribute-value string is U+002E ("."): If the first character of the attribute-value string is U+002E ("."):
skipping to change at page 22, line 25 skipping to change at page 22, line 23
5.2.6. The HttpOnly Attribute 5.2.6. The HttpOnly Attribute
If the attribute-name case-insensitively matches the string If the attribute-name case-insensitively matches the string
"HttpOnly", the user agent MUST append an attribute to the cookie- "HttpOnly", the user agent MUST append an attribute to the cookie-
attribute-list with an attribute-name of HttpOnly and an empty attribute-list with an attribute-name of HttpOnly and an empty
attribute-value. attribute-value.
5.3. Storage Model 5.3. Storage Model
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 a received cookie in its entirety if the user
agent is configured to block receiving cookies. 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, The user agent stores the following fields about each cookie: name,
value, expiry-time, domain, path, creation-time, last-access-time, value, expiry-time, domain, path, creation-time, last-access-time,
persistent-flag, host-only-flag, secure-only-flag, and http-only- persistent-flag, host-only-flag, secure-only-flag, and http-only-
flag. flag.
When the user agent receives a cookie from a Request-URI with name When the user agent *receives a cookie* from a Request-URI with name
cookie-name, value cookie-value, and attributes cookie-attribute- cookie-name, value cookie-value, and attributes cookie-attribute-
list, the user agent MUST process the cookie as follows: list, the user agent MUST process the cookie as follows:
1. Create a new cookie with name cookie-name, value cookie-value. 1. A user agent MAY ignore a received cookie in its entirety. For
example, the user agent might wish to block receiving cookies
from "third-party" responses.
2. Create a new cookie with name cookie-name, value cookie-value.
Set the creation-time and the last-access-time to the current Set the creation-time and the last-access-time to the current
date and time. date and time.
2. If the cookie-attribute-list contains an attribute with an 3. If the cookie-attribute-list contains an attribute with an
attribute-name of "Max-Age": attribute-name of "Max-Age":
Set the cookie's persistent-flag to true. Set the cookie's persistent-flag to true.
Set the cookie's expiry-time to attribute-value of the last Set the cookie's expiry-time to attribute-value of the last
attribute in the cookie-attribute-list with an attribute-name attribute in the cookie-attribute-list with an attribute-name
of "Max-Age". of "Max-Age".
Otherwise, if the cookie-attribute-list contains an attribute Otherwise, if the cookie-attribute-list contains an attribute
with an attribute-name of "Expires" (and does not contain an with an attribute-name of "Expires" (and does not contain an
skipping to change at page 23, line 23 skipping to change at page 23, line 18
attribute in the cookie-attribute-list with an attribute-name attribute in the cookie-attribute-list with an attribute-name
of "Expires". of "Expires".
Otherwise: Otherwise:
Set the cookie's persistent-flag to false. Set the cookie's persistent-flag to false.
Set the cookie's expiry-time to the latest representable Set the cookie's expiry-time to the latest representable
date. date.
3. If the cookie-attribute-list contains an attribute with an 4. If the cookie-attribute-list contains an attribute with an
attribute-name of "Domain": attribute-name of "Domain":
Let the domain-attribute be the attribute-value of the last Let the domain-attribute be the attribute-value of the last
attribute in the cookie-attribute-list with an attribute-name attribute in the cookie-attribute-list with an attribute-name
of "Domain". of "Domain".
Otherwise: Otherwise:
Let the domain-attribute be the empty string. Let the domain-attribute be the empty string.
4. If the user agent is configured to use a "public suffix" list 5. If the user agent is configured to use a "public suffix" list
and the domain-attribute is a public suffix: and the domain-attribute is a public suffix:
If the domain-attribute is identical to the canonicalized If the domain-attribute is identical to the canonicalized
Request-URI's host: Request-URI's host:
Let the domain-attribute be the empty string. Let the domain-attribute be the empty string.
Otherwise: Otherwise:
Ignore the cookie entirely and abort these steps Ignore the cookie entirely and abort these steps
skipping to change at page 24, line 8 skipping to change at page 24, line 5
NOTE: A "public suffix" is a domain that is controlled by a NOTE: A "public suffix" is a domain that is controlled by a
public registry, such as "com", "co.uk", and "pvt.k12.wy.us". public registry, such as "com", "co.uk", and "pvt.k12.wy.us".
This step is essential for preventing attacker.com from This step is essential for preventing attacker.com from
disrupting the integrity of example.com by setting a cookie disrupting the integrity of example.com by setting a cookie
with a Domain attribute of "com". Unfortunately, the set of with a Domain attribute of "com". Unfortunately, the set of
public suffixes (also known as "registry controlled domains") public suffixes (also known as "registry controlled domains")
changes over time. If feasible, user agents SHOULD use an changes over time. If feasible, user agents SHOULD use an
up-to-date public suffix list, such as the one maintained by up-to-date public suffix list, such as the one maintained by
the Mozilla project at http://publicsuffix.org/. the Mozilla project at http://publicsuffix.org/.
5. If the domain-attribute is non-empty: 6. If the domain-attribute is non-empty:
If the Request-URI's host does not domain-match the domain- If the Request-URI's host does not domain-match the domain-
attribute, ignore the cookie entirely and abort these steps. attribute, ignore the cookie entirely and abort these steps.
Set the cookie's host-only-flag to false. Set the cookie's host-only-flag to false.
Set the cookie's domain to the domain-attribute. Set the cookie's domain to the domain-attribute.
Otherwise: Otherwise:
Set the cookie's host-only-flag to true. Set the cookie's host-only-flag to true.
Set the cookie's domain to the host of the Request-URI. Set the cookie's domain to the canonicalized host of the
Request-URI.
6. If the cookie-attribute-list contains an attribute with an 7. If the cookie-attribute-list contains an attribute with an
attribute-name of "Path", set the cookie's path to attribute- attribute-name of "Path", set the cookie's path to attribute-
value of the last attribute in the cookie-attribute-list with an value of the last attribute in the cookie-attribute-list with an
attribute-name of "Path". Otherwise, set cookie's path to the attribute-name of "Path". Otherwise, set cookie's path to the
default-path of the Request-URI. default-path of the Request-URI.
7. If the cookie-attribute-list contains an attribute with an 8. If the cookie-attribute-list contains an attribute with an
attribute-name of "Secure", set the cookie's secure-only-flag to attribute-name of "Secure", set the cookie's secure-only-flag to
true. Otherwise, set cookie's secure-only-flag to false. true. Otherwise, set cookie's secure-only-flag to false.
8. If the cookie-attribute-list contains an attribute with an 9. If the cookie-attribute-list contains an attribute with an
attribute-name of "HttpOnly", set the cookie's http-only-flag to attribute-name of "HttpOnly", set the cookie's http-only-flag to
true. Otherwise, set cookie's http-only-flag to false. true. Otherwise, set cookie's http-only-flag to false.
9. If the cookie's name and value are both empty, abort these steps 10. If the cookie's name and value are both empty, abort these steps
and ignore the cookie entirely. and ignore the cookie entirely.
10. If the cookie's expiry-time is not in the future, abort these 11. If the cookie was received from a non-HTTP API and the cookie's
steps and ignore the cookie entirely. http-only-flag is set, abort these steps and ignore the cookie
entirely.
11. If the cookie was received from a non-HTTP context and the
cookie's http-only-flag is set, abort these steps and ignore the
cookie entirely.
12. If the cookie store contains a cookie with the same name, 12. If the cookie store contains a cookie with the same name,
domain, and path as the newly created cookie: domain, and path as the newly created cookie:
1. Let old-cookie be the existing cookie with the same name, 1. Let old-cookie be the existing cookie with the same name,
domain, and path as the newly created cookie. (Notice that domain, and path as the newly created cookie. (Notice that
this algorithm maintains the invariant that there is at most this algorithm maintains the invariant that there is at most
one such cookie.) one such cookie.)
2. If the newly created cookie was received from an non-HTTP 2. If the newly created cookie was received from an non-HTTP
context and the old-cookie's host-only-flag is set, abort API and the old-cookie's host-only-flag is set, abort these
these steps and ignore the newly created cookie entirely. steps and ignore the newly created cookie entirely.
3. Update the creation-time of the newly created cookie to 3. Update the creation-time of the newly created cookie to
match the creation-time of the old-cookie. match the creation-time of the old-cookie.
4. Remove the old-cookie from the cookie store. 4. Remove the old-cookie from the cookie store.
13. Insert the newly created cookie into the cookie store. 13. Insert the newly created cookie into the cookie store.
The user agent MUST evict a cookie from the cookie store if, at any The user agent MUST evict a cookie from the cookie store if, at any
time, a cookie exists in the cookie store with an expiry date in the time, a cookie exists in the cookie store with an expiry date in the
skipping to change at page 26, line 5 skipping to change at page 25, line 46
When "the current session is over" (as defined by the user agent), When "the current session is over" (as defined by the user agent),
the user agent MUST remove from the cookie store all cookies with the the user agent MUST remove from the cookie store all cookies with the
persistent-flag set to false. persistent-flag set to false.
5.4. The Cookie Header 5.4. The Cookie Header
When the user agent generates an HTTP request, the user agent SHOULD When the user agent generates an HTTP request, the user agent SHOULD
attach exactly one HTTP header named Cookie if the cookie-string attach exactly one HTTP header named Cookie if the cookie-string
(defined below) for the Request-URI is non-empty. (defined below) for the Request-URI is non-empty.
A user agent MAY omit the Cookie header in its entirety if the user A user agent MAY omit the Cookie header in its entirety. For
agent is configured to block sending cookies. For example, the user example, the user agent might wish to block sending cookies during
agent might wish to block sending cookies during "third-party" "third-party" requests.
requests.
The user agent MUST use the following algorithm to compute the The user agent MUST use the following algorithm to compute the
cookie-string from a cookie store and a Request-URI: cookie-string from a cookie store and a Request-URI:
1. Let cookie-list be the set of cookies from the cookie store that 1. Let cookie-list be the set of cookies from the cookie store that
meet all of the following requirements: meet all of the following requirements:
* Let request-host be the Request-URI's host. Either: * Let request-host be the Request-URI's host. Either:
The cookie's host-only-flag is true and the canonicalized The cookie's host-only-flag is true and the canonicalized
skipping to change at page 27, line 5 skipping to change at page 26, line 45
2. The user agent SHOULD sort the cookie-list in the following 2. The user agent SHOULD sort the cookie-list in the following
order: order:
* Cookies with longer paths are listed before cookies with * Cookies with longer paths are listed before cookies with
shorter paths. shorter paths.
* Among cookies that have equal length path fields, cookies with * Among cookies that have equal length path fields, cookies with
earlier creation-times are listed before cookies with later earlier creation-times are listed before cookies with later
creation-times. creation-times.
NOTE: Not all user agents sort the cookie-list in this order, NOTE: Not all user agents sort the cookie-list in this order, but
but this order reflects common practice when this document was this order reflects common practice when this document was
written. The specific ordering might not be optimal in every written. The specific ordering might not be optimal in every
metric, but using the consensus ordering is a relatively low metric, but using the consensus ordering is a relatively low cost
cost way to improve interoperability between user agents. way to improve interoperability between user agents.
3. Update the last-access-time of each cookie in the cookie-list to 3. Update the last-access-time of each cookie in the cookie-list to
the current date and time. the current date and time.
4. Serialize the cookie-list into a cookie-string by processing each 4. Serialize the cookie-list into a cookie-string by processing each
cookie in the cookie-list in order: cookie in the cookie-list in order:
1. Output the cookie's name, the U+003D ("=") character, and the 1. Output the cookie's name, the U+003D ("=") character, and the
cookie's value. cookie's value.
2. If there is an unprocessed cookie in the cookie-list, output 2. If there is an unprocessed cookie in the cookie-list, output
the characters U+003B and U+0020 ("; "). the characters U+003B and U+0020 ("; ").
Note: Despite its name, the cookie-string is actually a sequence of NOTE: Despite its name, the cookie-string is actually a sequence of
octets, not a sequence of characters. To convert the cookie-string octets, not a sequence of characters. To convert the cookie-string
into a sequence of characters (e.g., for presentation to the user), into a sequence of characters (e.g., for presentation to the user),
the user agent SHOULD use the UTF-8 character encoding [RFC3629]. the user agent SHOULD use the UTF-8 character encoding [RFC3629].
6. Implementation Considerations 6. Implementation Considerations
6.1. Limits 6.1. Limits
Practical user agent implementations have limits on the number and Practical user agent implementations have limits on the number and
size of cookies that they can store. General-use user agents SHOULD size of cookies that they can store. General-use user agents SHOULD
skipping to change at page 28, line 30 skipping to change at page 28, line 30
Servers SHOULD use as few and as small cookies as possible to avoid Servers SHOULD use as few and as small cookies as possible to avoid
reaching these implementation limits and to avoid network latency due reaching these implementation limits and to avoid network latency due
to the Cookie header being included in every request. to the Cookie header being included in every request.
Servers should gracefully degrade if the user agent fails to return Servers should gracefully degrade if the user agent fails to return
one or more cookies in the Cookie header because the user agent might one or more cookies in the Cookie header because the user agent might
evict any cookie at any time on orders from the user. evict any cookie at any time on orders from the user.
6.2. Application Programmer Interfaces 6.2. Application Programmer Interfaces
One reason the cookie protocol uses such an esoteric syntax is One reason the Cookie and Set-Cookie headers uses such esoteric
because many platforms (both in servers and user agents) provide syntax is because many platforms (both in servers and user agents)
string-based application programmer interfaces (APIs), requiring provide a string-based application programmer interface (API) to
application-layer programmers to generate and parse the syntax used cookies, requiring application-layer programmers to generate and
by the cookie protocol. parse the syntax used by the Cookie and Set-Cookie headers.
Instead of providing string-based APIs to the cookie protocols, Instead of providing string-based APIs to cookies, platforms would be
implementations would be well-served by providing more semantic APIs. well-served by providing more semantic APIs. It is beyond the scope
It is beyond the scope of this document to recommend specific API of this document to recommend specific API designs, but there are
designs, but there are clear benefits to accepting a abstract "Date" clear benefits to accepting a abstract "Date" object instead of a
object instead of a serialized date string. serialized date string.
7. Privacy Considerations 7. Privacy Considerations
The cookie protocol is often criticized for letting servers track Cookies are often criticized for letting servers track users. For
users. For example, a number of "web analytics" companies use example, a number of "web analytics" companies use cookies to
cookies to recognize when a user returns to a web site or visits recognize when a user returns to a web site or visits another web
another web site. Although cookies are not the only mechanism site. Although cookies are not the only mechanism servers can use to
servers can use to track users across HTTP requests, cookies track users across HTTP requests, cookies facilitate tracking because
facilitate tracking because they are persistent across user agent they are persistent across user agent sessions and can be shared
sessions and can be shared between host names. between domains.
7.1. Third-Party Cookies 7.1. Third-Party Cookies
Particularly worrisome are so-called "third-party" cookies. In Particularly worrisome are so-called "third-party" cookies. In
rendering an HTML document, a user agent often requests resources rendering an HTML document, a user agent often requests resources
from other servers (such as advertising networks). These third-party from other servers (such as advertising networks). These third-party
servers can use the cookie protocol to track the user even if the servers can use cookies to track the user even if the user never
user never visits the server directly. visits the server directly.
Some user agents restrict how third-party cookies behave. For Some user agents restrict how third-party cookies behave. For
example, some user agents refuse to send the Cookie header in third- example, some user agents refuse to send the Cookie header in third-
party requests. Other user agents refuse to process the Set-Cookie party requests. Other user agents refuse to process the Set-Cookie
header in responses to third-party requests. Among user agents, header in responses to third-party requests. User agents vary widely
there is a wide variety of third-party cookie policies. This in their third-party cookie policies. This document grants user
document grants user agents wide latitude to experiment with third- agents wide latitude to experiment with third-party cookie policies
party cookie policies that balance the privacy and compatibility that balance the privacy and compatibility needs of their users.
needs of their users. However, this document does not endorse any However, this document does not endorse any particular third-party
particular third-party cookie policy. cookie policy.
Third-party cookie blocking policies are often ineffective at Third-party cookie blocking policies are often ineffective at
achieving their privacy goals if servers attempt to work around their achieving their privacy goals if servers attempt to work around their
restrictions to track users. In particular, two collaborating restrictions to track users. In particular, two collaborating
servers can often track users without using cookies at all. servers can often track users without using cookies at all.
7.2. User Controls 7.2. User Controls
User agents SHOULD provide users with a mechanism for managing the User agents SHOULD provide users with a mechanism for managing the
cookies stored in the cookie store. For example, a user agent might cookies stored in the cookie store. For example, a user agent might
let users delete all cookies received during a specified time period let users delete all cookies received during a specified time period
or all the cookies related to a particular domain. In addition, many or all the cookies related to a particular domain. In addition, many
user agent include a user interface element that lets users examine user agent include a user interface element that lets users examine
the cookies stored in the cookie store. the cookies stored in their cookie store.
User agents SHOULD provide users with a mechanism for disabling User agents SHOULD provide users with a mechanism for disabling
cookies. When cookies are disabled, the user agent MUST NOT include cookies. When cookies are disabled, the user agent MUST NOT include
a Cookie header in outbound HTTP requests and the user agent MUST NOT a Cookie header in outbound HTTP requests and the user agent MUST NOT
process Set-Cookie headers in inbound HTTP responses. process Set-Cookie headers in inbound HTTP responses.
Some user agents provide users the option of preventing persistent Some user agents provide users the option of preventing persistent
storage of cookies across sessions. When configured thusly, user storage of cookies across sessions. When configured thusly, user
agents MUST treat all received cookies as if the persistent-flag were agents MUST treat all received cookies as if the persistent-flag were
set to false. set to false.
Some user agents provide users with the ability to approve individual Some user agents provide users with the ability to approve individual
writes to the cookie store. In many common usage scenarios, these writes to the cookie store. In many common usage scenarios, these
controls generate a large number of prompts. However, some privacy- controls generate a large number of prompts. However, some privacy-
conscious users find these controls useful nonetheless. conscious users find these controls useful nonetheless.
8. Security Considerations 8. Security Considerations
8.1. Overview 8.1. Overview
The cookie protocol has a number of security and privacy pitfalls. Cookies have a number of security and privacy pitfalls.
In particular, cookies encourage developers to rely on ambient In particular, cookies encourage developers to rely on ambient
authority for authentication, often creating vulnerabilities such as authority for authentication, often becoming vulnerable to attacks
cross-site request forgery. When storing session identifiers in such as cross-site request forgery. Also, when storing session
cookies, developers often create session fixation vulnerabilities. identifiers in cookies, developers often create session fixation
vulnerabilities.
Transport-layer encryption, such as that employed in HTTPS, is Transport-layer encryption, such as that employed in HTTPS, is
insufficient to prevent a network attacker from obtaining or altering insufficient to prevent a network attacker from obtaining or altering
a victim's cookies because the cookie protocol itself has various a victim's cookies because the cookie protocol itself has various
vulnerabilities (see "Weak Confidentiality" and "Weak Integrity", vulnerabilities (see "Weak Confidentiality" and "Weak Integrity",
below). In addition, by default, the cookie protocol does not below). In addition, by default, cookies do not provide
provide confidentiality or integrity from network attackers, even confidentiality or integrity from network attackers, even when used
when used in conjunction with HTTPS. in conjunction with HTTPS.
8.2. Ambient Authority 8.2. Ambient Authority
A server that uses cookies to authenticate users can suffer security A server that uses cookies to authenticate users can suffer security
vulnerabilities because some user agents let remote parties issue vulnerabilities because some user agents let remote parties issue
HTTP requests from the user agent (e.g., via HTTP redirects and HTML HTTP requests from the user agent (e.g., via HTTP redirects or HTML
forms). When issuing those requests, user agent attaches cookies forms). When issuing those requests, user agents attach cookies even
even if the entity does not know the contents of the cookies, if the remote party does not know the contents of the cookies,
possibly letting the remote entity exercise authority at an unwary potentially letting the remote party exercise authority at an unwary
server. server.
Although this security concern goes by a number of names (e.g., Although this security concern goes by a number of names (e.g.,
cross-site request forgery, confused deputy), the issue stems from cross-site request forgery, confused deputy), the issue stems from
cookies being a form of ambient authority. Cookies encourage server cookies being a form of ambient authority. Cookies encourage server
operators to separate designation (in the form of URLs) from operators to separate designation (in the form of URLs) from
authorization (in the form of cookies). Consequently, the user agent authorization (in the form of cookies). Consequently, the user agent
might supply the authorization for a resource designated by the might supply the authorization for a resource designated by the
attacker, possibly causing the server or its clients to undertake attacker, possibly causing the server or its clients to undertake
actions designated by the attacker as though they were authorized by actions designated by the attacker as though they were authorized by
skipping to change at page 32, line 8 skipping to change at page 32, line 8
Instead of using cookies for authorization, server operators might Instead of using cookies for authorization, server operators might
wish to consider entangling designation and authorization by treating wish to consider entangling designation and authorization by treating
URLs as capabilities. Instead of storing secrets in cookies, this URLs as capabilities. Instead of storing secrets in cookies, this
approach stores secrets in URLs, requiring the remote entity to approach stores secrets in URLs, requiring the remote entity to
supply the secret itself. Although this approach is not a panacea, supply the secret itself. Although this approach is not a panacea,
judicious use of these principles can lead to more robust security. judicious use of these principles can lead to more robust security.
8.3. Clear Text 8.3. Clear Text
Unless sent over a secure channel (such as TLS), the information in Unless sent over a secure channel (such as TLS), the information in
the Set-Cookie and Cookie headers is transmitted in the clear. the Cookie and Set-Cookie headers is transmitted in the clear.
1. All sensitive information conveyed in these headers is exposed to 1. All sensitive information conveyed in these headers is exposed to
an eavesdropper. an eavesdropper.
2. A malicious intermediary could alter the headers as they travel 2. A malicious intermediary could alter the headers as they travel
in either direction, with unpredictable results. in either direction, with unpredictable results.
3. A malicious client could alter the Cookie header before 3. A malicious client could alter the Cookie header before
transmission, with unpredictable results. transmission, with unpredictable results.
Servers SHOULD encrypt and sign the contents of cookies when Servers SHOULD encrypt and sign the contents of cookies when
transmitting them to the user agent (even when sending the cookies transmitting them to the user agent (even when sending the cookies
over a secure channel). However, encrypting and signing cookie over a secure channel). However, encrypting and signing cookie
contents does not prevent an attacker from transplanting a cookie contents does not prevent an attacker from transplanting a cookie
from one user agent to another or from replaying the cookie at a from one user agent to another or from replaying the cookie at a
later time. later time.
In addition to encrypting and signing the contents of every cookie, In addition to encrypting and signing the contents of every cookie,
servers that require a higher level of security SHOULD use the cookie servers that require a higher level of security SHOULD use the Cookie
protocol only over a secure channel. When using the cookie protocol and Set-Cookie headers only over a secure channel. When using
over a secure channel, servers SHOULD set the Secure attribute in cookies over a secure channel, servers SHOULD set the Secure
every cookie. If a server does not set the Secure attribute, the attribute for every cookie. If a server does not set the Secure
protection provided by the secure channel will be largely moot. attribute, the protection provided by the secure channel will be
largely moot.
8.4. Session Identifiers 8.4. Session Identifiers
Instead of storing session information directly in a cookie (where it Instead of storing session information directly in a cookie (where it
might be exposed to or replayed by an attacker), servers commonly might be exposed to or replayed by an attacker), servers commonly
store a nonce (or "session identifier") in a cookie. When the server store a nonce (or "session identifier") in a cookie. When the server
receives an HTTP request with a nonce, the server can look up state receives an HTTP request with a nonce, the server can look up state
information associated with the cookie using the nonce as a key. information associated with the cookie using the nonce as a key.
Using session identifier cookies limits the damage an attacker can Using session identifier cookies limits the damage an attacker can
skipping to change at page 33, line 24 skipping to change at page 33, line 25
a service running on one port, the cookie is also readable by a a service running on one port, the cookie is also readable by a
service running on another port of the same server. If a cookie is service running on another port of the same server. If a cookie is
writable by a service on one port, the cookie is also writable by a writable by a service on one port, the cookie is also writable by a
service running on another port of the same server. For this reason, service running on another port of the same server. For this reason,
servers SHOULD NOT both run mutually distrusting services on servers SHOULD NOT both run mutually distrusting services on
different ports of the same host and use cookies to store security- different ports of the same host and use cookies to store security-
sensitive information. sensitive information.
Cookies do not provide isolation by scheme. Although most commonly Cookies do not provide isolation by scheme. Although most commonly
used with the http and https schemes, the cookies for a given host used with the http and https schemes, the cookies for a given host
might also available to other schemes, such as ftp and gopher. might also be available to other schemes, such as ftp and gopher.
Although this lack of isolation by scheme is most apparent in via Although this lack of isolation by scheme is most apparent in via
non-HTTP APIs that permit access to cookies (e.g., HTML's non-HTTP APIs that permit access to cookies (e.g., HTML's
document.cookie API), the lack of isolation by scheme is actually document.cookie API), the lack of isolation by scheme is actually
present in the cookie protocol itself (e.g., consider retrieving a present in requirements for processing cookies themselves (e.g.,
URI with the gopher scheme via HTTP). consider retrieving a URI with the gopher scheme via HTTP).
Cookies do not always provide isolation by path. Although the Cookies do not always provide isolation by path. Although the
network-level protocol does not send cookie stored for one path to network-level protocol does not send cookie stored for one path to
another, some user agents expose cookies via non-HTTP APIs, such as another, some user agents expose cookies via non-HTTP APIs, such as
HTML's document.cookie API. Because some of these user agents (e.g., HTML's document.cookie API. Because some of these user agents (e.g.,
web browsers) do not isolate resources received from different paths, web browsers) do not isolate resources received from different paths,
a resource retrieved from one path might be able to access cookies a resource retrieved from one path might be able to access cookies
stored for another path. stored for another path.
8.6. Weak Integrity 8.6. Weak Integrity
Cookies do not provide integrity guarantees for sibling domains (and Cookies do not provide integrity guarantees for sibling domains (and
their subdomains). For example, consider foo.example.com and their subdomains). For example, consider foo.example.com and
bar.example.com. The foo.example.com server can set a cookie with a bar.example.com. The foo.example.com server can set a cookie with a
Domain attribute of ".example.com" (possibly overwriting an existing Domain attribute of "example.com" (possibly overwriting an existing
".example.com" cookie set by bar.example.com), and the user agent "example.com" cookie set by bar.example.com), and the user agent will
will include that cookie in HTTP requests to bar.example.com. In the include that cookie in HTTP requests to bar.example.com. In the
worst case, bar.example.com will be unable to distinguish this cookie worst case, bar.example.com will be unable to distinguish this cookie
from a cookie it set itself. The foo.example.com server might be from a cookie it set itself. The foo.example.com server might be
able to leverage this ability to mount an attack against able to leverage this ability to mount an attack against
bar.example.com. bar.example.com.
Even though the cookie protocol supports the Path attribute, the Path Even though the Set-Cookie header supports the Path attribute, the
attribute does not provide any integrity protection because the user Path attribute does not provide any integrity protection because the
agent will accept an arbitrary Path attribute in a Set-Cookie header. user agent will accept an arbitrary Path attribute in a Set-Cookie
For example, an HTTP response to a request for header. For example, an HTTP response to a request for
http://example.com/foo/bar can set a cookie with a Path attribute of http://example.com/foo/bar can set a cookie with a Path attribute of
"/qux". Consequently, servers SHOULD NOT both run mutually "/qux". Consequently, servers SHOULD NOT both run mutually
distrusting services on different paths of the same host and use distrusting services on different paths of the same host and use
cookies store security sensitive information. cookies store security-sensitive information.
An active network attacker can also inject cookies into the Cookie An active network attacker can also inject cookies into the Cookie
header sent to https://example.com/ by impersonating a response from header sent to https://example.com/ by impersonating a response from
http://example.com/ and injecting a Set-Cookie header. The HTTPS http://example.com/ and injecting a Set-Cookie header. The HTTPS
server at example.com will be unable to distinguish these cookies server at example.com will be unable to distinguish these cookies
from cookies that it set itself in an HTTPS response. An active from cookies that it set itself in an HTTPS response. An active
network attacker might be able to leverage this ability to mount an network attacker might be able to leverage this ability to mount an
attack against example.com even if example.com uses HTTPS attack against example.com even if example.com uses HTTPS
exclusively. exclusively.
skipping to change at page 34, line 37 skipping to change at page 34, line 37
the user's session, with unpredictable results. the user's session, with unpredictable results.
Finally, an attacker might be able to force the user agent to delete Finally, an attacker might be able to force the user agent to delete
cookies by storing large number of cookies. Once the user agent cookies by storing large number of cookies. Once the user agent
reaches its storage limit, the user agent will be forced to evict reaches its storage limit, the user agent will be forced to evict
some cookies. Servers SHOULD NOT rely upon user agents retaining some cookies. Servers SHOULD NOT rely upon user agents retaining
cookies. cookies.
8.7. Reliance on DNS 8.7. Reliance on DNS
The cookie protocol relies upon the Domain Name System (DNS) for Cookies rely upon the Domain Name System (DNS) for security. If the
security. If the DNS is partially or fully compromised, the cookie DNS is partially or fully compromised, the cookie protocol might fail
protocol might fail to provide the security properties required by to provide the security properties required by applications.
applications.
9. References 9. References
9.1. Normative References 9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
skipping to change at page 36, line 11 skipping to change at page 36, line 11
[RFC2109] Kristol, D. and L. Montulli, "HTTP State Management [RFC2109] Kristol, D. and L. Montulli, "HTTP State Management
Mechanism", RFC 2109, February 1997. Mechanism", RFC 2109, February 1997.
Appendix A. Acknowledgements Appendix A. Acknowledgements
This document borrows heavily from RFC 2109 [RFC2109]. We are This document borrows heavily from RFC 2109 [RFC2109]. We are
indebted to David M. Kristol and Lou Montulli for their efforts to indebted to David M. Kristol and Lou Montulli for their efforts to
specify the cookie protocol. David M. Kristol, in particular, specify the cookie protocol. David M. Kristol, in particular,
provided invaluable advice on navigating the IETF process. We would provided invaluable advice on navigating the IETF process. We would
also like to thank Thomas Broyer, Tyler Close, Bil Corry, corvid, Roy also like to thank Thomas Broyer, Tyler Close, Bil Corry, corvid,
T. Fielding, Blake Frantz, Eran Hammer-Lahav, Jeff Hodges, Achim Lisa Dusseault, Roy T. Fielding, Blake Frantz, Eran Hammer-Lahav,
Hoffmann, Georg Koppen, Dean McNamee, Mark Miller, Yngve N. Jeff Hodges, Achim Hoffmann, Georg Koppen, Dean McNamee, Mark Miller,
Pettersen, Julian Reschke, Mark Seaborn, Maciej Stachowiak, Daniel Mark Pauley, Yngve N. Pettersen, Julian Reschke, Mark Seaborn, Maciej
Stenberg, David Wagner, Dan Winship, and Dan Witte for their valuable Stachowiak, Daniel Stenberg, David Wagner, Dan Winship, and Dan Witte
feedback on this document. for their valuable feedback on this document.
Author's Address Author's Address
Adam Barth Adam Barth
University of California, Berkeley University of California, Berkeley
Email: abarth@eecs.berkeley.edu Email: abarth@eecs.berkeley.edu
URI: http://www.adambarth.com/ URI: http://www.adambarth.com/
 End of changes. 88 change blocks. 
244 lines changed or deleted 236 lines changed or added

This html diff was produced by rfcdiff 1.38. The latest version is available from http://tools.ietf.org/tools/rfcdiff/