Network Working Group D. Kristol
Request for Comments: 2965 Bell Laboratories, Lucent Technologies
Obsoletes: 2109 L. Montulli
Category: Standards Track Epinions.com, Inc.
October 2000
HTTP State Management Mechanism
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2000). All Rights Reserved.
IESG Note
The IESG notes that this mechanism makes use of the .local top-level
domain (TLD) internally when handling host names that don't contain
any dots, and that this mechanism might not work in the expected way
should an actual .local TLD ever be registered.
Abstract
This document specifies a way to create a stateful session with
Hypertext Transfer Protocol (HTTP) requests and responses. It
describes three new headers, Cookie, Cookie2, and Set-Cookie2, which
carry state information between participating origin servers and user
agents. The method described here differs from Netscape's Cookie
proposal [Netscape], but it can interoperate with HTTP/1.0 user
agents that use Netscape's method. (See the HISTORICAL section.)
This document reflects implementation experience with RFC 2109 and
obsoletes it.
1. TERMINOLOGY
The terms user agent, client, server, proxy, origin server, and
http_URL have the same meaning as in the HTTP/1.1 specification
[RFC2616]. The terms abs_path and absoluteURI have the same meaning
as in the URI Syntax specification [RFC2396].
Kristol & Montulli Standards Track [Page 1]
RFC 2965 HTTP State Management Mechanism October 2000
Host name (HN) means either the host domain name (HDN) or the numeric
Internet Protocol (IP) address of a host. The fully qualified domain
name is preferred; use of numeric IP addresses is strongly
discouraged.
The terms request-host and request-URI refer to the values the client
would send to the server as, respectively, the host (but not port)
and abs_path portions of the absoluteURI (http_URL) of the HTTP
request line. Note that request-host is a HN.
The term effective host name is related to host name. If a host name
contains no dots, the effective host name is that name with the
string .local appended to it. Otherwise the effective host name is
the same as the host name. Note that all effective host names
contain at least one dot.
The term request-port refers to the port portion of the absoluteURI
(http_URL) of the HTTP request line. If the absoluteURI has no
explicit port, the request-port is the HTTP default, 80. The
request-port of a cookie is the request-port of the request in which
a Set-Cookie2 response header was returned to the user agent.
Host names can be specified either as an IP address or a HDN string.
Sometimes we compare one host name with another. (Such comparisons
SHALL be case-insensitive.) Host A's name domain-matches host B's if
name string, B has the form .B', and B' is a HDN string. (So,
x.y.com domain-matches .Y.com but not Y.com.)
Note that domain-match is not a commutative operation: a.b.c.com
domain-matches .c.com, but not the reverse.
The reach R of a host name H is defined as follows:
H is the host domain name of a host; and,
H has the form A.B; and
A has no embedded (that is, interior) dots; and
B has at least one embedded dot, or B is the string "local".
then the reach of H is .B.
Kristol & Montulli Standards Track [Page 2]
RFC 2965 HTTP State Management Mechanism October 2000
For two strings that represent paths, P1 and P2, P1 path-matches P2
if P2 is a prefix of P1 (including the case where P1 and P2 string-
compare equal). Thus, the string /tec/waldo path-matches /tec.
Because it was used in Netscape's original implementation of state
management, we will use the term cookie to refer to the state
information that passes between an origin server and user agent, and
that gets stored by the user agent.
1.1 Requirements
The key words "MAY", "MUST", "MUST NOT", "OPTIONAL", "RECOMMENDED",
"REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT" in this
document are to be interpreted as described in RFC 2119 [RFC2119].
2. STATE AND SESSIONS
This document describes a way to create stateful sessions with HTTP
requests and responses. Currently, HTTP servers respond to each
client request without relating that request to previous or
subsequent requests; the state management mechanism allows clients
and servers that wish to exchange state information to place HTTP
requests and responses within a larger context, which we term a
"session". This context might be used to create, for example, a
"shopping cart", in which user selections can be aggregated before
purchase, or a magazine browsing system, in which a user's previous
reading affects which offerings are presented.
Neither clients nor servers are required to support cookies. A
server MAY refuse to provide content to a client that does not return
the cookies it sends.
3. DESCRIPTION
We describe here a way for an origin server to send state information
to the user agent, and for the user agent to return the state
information to the origin server. The goal is to have a minimal
impact on HTTP and user agents.
3.1 Syntax: General
The two state management headers, Set-Cookie2 and Cookie, have common
syntactic properties involving attribute-value pairs. The following
grammar uses the notation, and tokens DIGIT (decimal digits), token
Kristol & Montulli Standards Track [Page 3]
RFC 2965 HTTP State Management Mechanism October 2000
(informally, a sequence of non-special, non-white space characters),
and http_URL from the HTTP/1.1 specification [RFC2616] to describe
their syntax.
av-pairs = av-pair *(";" av-pair)
av-pair = attr ["=" value] ; optional value
attr = token
value = token | quoted-string
Attributes (names) (attr) are case-insensitive. White space is
permitted between tokens. Note that while the above syntax
description shows value as optional, most attrs require them.
NOTE: The syntax above allows whitespace between the attribute and
the = sign.
3.2 Origin Server Role
3.2.1 General The origin server initiates a session, if it so
desires. To do so, it returns an extra response header to the
client, Set-Cookie2. (The details follow later.)
A user agent returns a Cookie request header (see below) to the
origin server if it chooses to continue a session. The origin server
MAY ignore it or use it to determine the current state of the
session. It MAY send back to the client a Set-Cookie2 response
header with the same or different information, or it MAY send no
Set-Cookie2 header at all. The origin server effectively ends a
session by sending the client a Set-Cookie2 header with Max-Age=0.
Servers MAY return Set-Cookie2 response headers with any response.
User agents SHOULD send Cookie request headers, subject to other
rules detailed below, with every request.
An origin server MAY include multiple Set-Cookie2 headers in a
response. Note that an intervening gateway could fold multiple such
headers into a single header.
Kristol & Montulli Standards Track [Page 4]
RFC 2965 HTTP State Management Mechanism October 2000
3.2.2 Set-Cookie2 Syntax The syntax for the Set-Cookie2 response
header is
set-cookie = "Set-Cookie2:" cookies
cookies = 1#cookie
cookie = NAME "=" VALUE *(";" set-cookie-av)
NAME = attr
VALUE = value
set-cookie-av = "Comment" "=" value
| "CommentURL" "=" <"> http_URL <">
| "Discard"
| "Domain" "=" value
| "Max-Age" "=" value
| "Path" "=" value
| "Port" [ "=" <"> portlist <"> ]
| "Secure"
| "Version" "=" 1*DIGIT
portlist = 1#portnum
portnum = 1*DIGIT
Informally, the Set-Cookie2 response header comprises the token Set-
Cookie2:, followed by a comma-separated list of one or more cookies.
Each cookie begins with a NAME=VALUE pair, followed by zero or more
semi-colon-separated attribute-value pairs. The syntax for
attribute-value pairs was shown earlier. The specific attributes and
the semantics of their values follows. The NAME=VALUE attribute-
value pair MUST come first in each cookie. The others, if present,
can occur in any order. If an attribute appears more than once in a
cookie, the client SHALL use only the value associated with the first
appearance of the attribute; a client MUST ignore values after the
first.
The NAME of a cookie MAY be the same as one of the attributes in this
specification. However, because the cookie's NAME must come first in
a Set-Cookie2 response header, the NAME and its VALUE cannot be
confused with an attribute-value pair.
NAME=VALUE
REQUIRED. The name of the state information ("cookie") is NAME,
and its value is VALUE. NAMEs that begin with $ are reserved and
MUST NOT be used by applications.
The VALUE is opaque to the user agent and may be anything the
origin server chooses to send, possibly in a server-selected
printable ASCII encoding. "Opaque" implies that the content is of
interest and relevance only to the origin server. The content
may, in fact, be readable by anyone that examines the Set-Cookie2
header.
Kristol & Montulli Standards Track [Page 5]
RFC 2965 HTTP State Management Mechanism October 2000
Comment=value
OPTIONAL. Because cookies can be used to derive or store private
information about a user, the value of the Comment attribute
allows an origin server to document how it intends to use the
cookie. The user can inspect the information to decide whether to
initiate or continue a session with this cookie. Characters in
value MUST be in UTF-8 encoding. [RFC2279]
CommentURL="http_URL"
OPTIONAL. Because cookies can be used to derive or store private
information about a user, the CommentURL attribute allows an
origin server to document how it intends to use the cookie. The
user can inspect the information identified by the URL to decide
whether to initiate or continue a session with this cookie.
Discard
OPTIONAL. The Discard attribute instructs the user agent to
discard the cookie unconditionally when the user agent terminates.
Domain=value
OPTIONAL. The value of the Domain attribute specifies the domain
for which the cookie is valid. If an explicitly specified value
does not start with a dot, the user agent supplies a leading dot.
Max-Age=value
OPTIONAL. The value of the Max-Age attribute is delta-seconds,
the lifetime of the cookie in seconds, a decimal non-negative
integer. To handle cached cookies correctly, a client SHOULD
calculate the age of the cookie according to the age calculation
rules in the HTTP/1.1 specification [RFC2616]. When the age is
greater than delta-seconds seconds, the client SHOULD discard the
cookie. A value of zero means the cookie SHOULD be discarded
immediately.
Path=value
OPTIONAL. The value of the Path attribute specifies the subset of
URLs on the origin server to which this cookie applies.
Port[="portlist"]
OPTIONAL. The Port attribute restricts the port to which a cookie
may be returned in a Cookie request header. Note that the syntax
REQUIREs quotes around the OPTIONAL portlist even if there is only
one portnum in portlist.
Kristol & Montulli Standards Track [Page 6]
RFC 2965 HTTP State Management Mechanism October 2000
Secure
OPTIONAL. The Secure attribute (with no value) directs the user
agent to use only (unspecified) secure means to contact the origin
server whenever it sends back this cookie, to protect the
confidentially and authenticity of the information in the cookie.
The user agent (possibly with user interaction) MAY determine what
level of security it considers appropriate for "secure" cookies.
The Secure attribute should be considered security advice from the
server to the user agent, indicating that it is in the session's
interest to protect the cookie contents. When it sends a "secure"
cookie back to a server, the user agent SHOULD use no less than
the same level of security as was used when it received the cookie
from the server.
Version=value
REQUIRED. The value of the Version attribute, a decimal integer,
identifies the version of the state management specification to
which the cookie conforms. For this specification, Version=1
applies.
3.2.3 Controlling Caching An origin server must be cognizant of the
effect of possible caching of both the returned resource and the
Set-Cookie2 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-Cookie2 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-Cookie2
header SHOULD NOT be cached. A Set-Cookie2 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:
Cache-control: no-cache="set-cookie2"
and one of the following:
Cache-control: private
Kristol & Montulli Standards Track [Page 7]
RFC 2965 HTTP State Management Mechanism October 2000
before returning it to the client:
Cache-Control: must-revalidate, max-age=0
caches (not user agent caches) validate it before returning it
to the client:
Cache-Control: proxy-revalidate, max-age=0
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-Cookie2 response
headers unless they know for certain (by out of band means) that
there are no HTTP/1.0 proxies in the response chain. 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.
3.3 User Agent Role
3.3.1 Interpreting Set-Cookie2 The user agent keeps separate track
of state information that arrives via Set-Cookie2 response headers
from each origin server (as distinguished by name or IP address and
port). The user agent MUST ignore attribute-value pairs whose
attribute it does not recognize. The user agent applies these
defaults for optional attributes that are missing:
Discard The default behavior is dictated by the presence or absence
of a Max-Age attribute.
Domain Defaults to the effective request-host. (Note that because
there is no dot at the beginning of effective request-host,
the default Domain can only domain-match itself.)
Max-Age The default behavior is to discard the cookie when the user
agent exits.
Path Defaults to the path of the request URL that generated the
Set-Cookie2 response, up to and including the right-most /.
Kristol & Montulli Standards Track [Page 8]
RFC 2965 HTTP State Management Mechanism October 2000
Port The default behavior is that a cookie MAY be returned to any
request-port.
Secure If absent, the user agent MAY send the cookie over an
insecure channel.
3.3.2 Rejecting Cookies To prevent possible security or privacy
violations, a user agent rejects a cookie according to rules below.
The goal of the rules is to try to limit the set of servers for which
a cookie is valid, based on the values of the Path, Domain, and Port
attributes and the request-URI, request-host and request-port.
A user agent rejects (SHALL NOT store its information) if the Version
attribute is missing. Moreover, a user agent rejects (SHALL NOT
store its information) if any of the following is true of the
attributes explicitly present in the Set-Cookie2 response header:
request-URI.
and the value is not .local.
not domain-match the Domain attribute.
where D is the value of the Domain attribute, and H is a string
that contains one or more dots.
not in the list.
Examples:
would be rejected, because H is y.x and contains a dot.
would be accepted.
rejected, because there is no embedded dot.
value for Domain will be taken to be .ajax.com, because a dot
gets prepended to the value.
Kristol & Montulli Standards Track [Page 9]
RFC 2965 HTTP State Management Mechanism October 2000
request was made to port 80 or 8000 and will be rejected
otherwise.
be accepted, because the effective host name for the request-
host is example.local, and example.local domain-matches .local.
3.3.3 Cookie Management If a user agent receives a Set-Cookie2
response header whose NAME is the same as that of a cookie it has
previously stored, the new cookie supersedes the old when: the old
and new Domain attribute values compare equal, using a case-
insensitive string-compare; and, the old and new Path attribute
values string-compare equal (case-sensitive). However, if the Set-
Cookie2 has a value for Max-Age of zero, the (old and new) cookie is
discarded. Otherwise a cookie persists (resources permitting) until
whichever happens first, then gets discarded: its Max-Age lifetime is
exceeded; or, if the Discard attribute is set, the user agent
terminates the session.
Because user agents have finite space in which to store cookies, they
MAY also discard older cookies to make space for newer ones, using,
for example, a least-recently-used algorithm, along with constraints
on the maximum number of cookies that each origin server may set.
If a Set-Cookie2 response header includes a Comment attribute, the
user agent SHOULD store that information in a human-readable form
with the cookie and SHOULD display the comment text as part of a
cookie inspection user interface.
If a Set-Cookie2 response header includes a CommentURL attribute, the
user agent SHOULD store that information in a human-readable form
with the cookie, or, preferably, SHOULD allow the user to follow the
http_URL link as part of a cookie inspection user interface.
The cookie inspection user interface may include a facility whereby a
user can decide, at the time the user agent receives the Set-Cookie2
response header, whether or not to accept the cookie. A potentially
confusing situation could arise if the following sequence occurs:
attribute;
that it presents a dialog to the user before the user agent
accepts the cookie;
Kristol & Montulli Standards Track [Page 10]
RFC 2965 HTTP State Management Mechanism October 2000
the user agent receives the cookie; and,
(or another server, via other links in the returned content)
returns another cookie.
The user agent SHOULD NOT send any cookies in this context. The user
agent MAY discard any cookie it receives in this context that the
user has not, through some user agent mechanism, deemed acceptable.
User agents SHOULD allow the user to control cookie destruction, but
they MUST NOT extend the cookie's lifetime beyond that controlled by
the Discard and Max-Age attributes. An infrequently-used cookie may
function as a "preferences file" for network applications, and a user
may wish to keep it even if it is the least-recently-used cookie. One
possible implementation would be an interface that allows the
permanent storage of a cookie through a checkbox (or, conversely, its
immediate destruction).
Privacy considerations dictate that the user have considerable
control over cookie management. The PRIVACY section contains more
information.
3.3.4 Sending Cookies to the Origin Server When it sends a request
to an origin server, the user agent includes a Cookie request header
if it has stored cookies that are applicable to the request, based on
The syntax for the header is:
cookie = "Cookie:" cookie-version 1*1)