idnits 2.17.1 draft-ietf-http-state-man-mec-12.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 23 longer pages, the longest (page 2) being 66 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 23 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 2 instances of too long lines in the document, the longest one being 5 characters in excess of 72. ** The abstract seems to contain references ([Netscape], [RFC2109]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == The 'Obsoletes: ' line in the draft header should list only the _numbers_ of the RFCs which will be obsoleted by this document (if approved); it should not include the word 'RFC' in the list. -- The draft header indicates that this document obsoletes RFC2109, but the abstract doesn't seem to directly say this. It does mention RFC2109 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Proxies MUST not introduce Set-Cookie2 (Cookie) headers of their own in proxy responses (requests). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 27, 2000) is 8825 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'DMK95' is mentioned on line 1010, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'Netscape' ** Obsolete normative reference: RFC 2109 (Obsoleted by RFC 2965) ** Obsolete normative reference: RFC 2279 (Obsoleted by RFC 3629) ** Obsolete normative reference: RFC 2396 (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 13 errors (**), 0 flaws (~~), 7 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 HTTP Working Group David M. Kristol 2 INTERNET DRAFT Bell Laboratories, Lucent Technologies 3 Obsoletes: RFC 2109 Lou Montulli 4 Epinions.com, Inc. 5 6 August 27, 1999 Expires February 27, 2000 8 HTTP State Management Mechanism 10 Status of this Memo 12 This document is an Internet-Draft and is in full conformance 13 with all provisions of Section 10 of RFC2026. 15 This document is an Internet-Draft. Internet-Drafts are 16 working documents of the Internet Engineering Task Force 17 (IETF), its areas, and its working groups. Note that other 18 groups may also distribute working documents as Internet- 19 Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six 22 months and may be updated, replaced, or obsoleted by other 23 documents at any time. It is inappropriate to use Internet- 24 Drafts as reference material or to cite them other than as 25 ``work in progress.'' 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed 31 at http://www.ietf.org/shadow.html. 33 This is authors' draft 3.11. 35 1. ABSTRACT 37 This document specifies a way to create a stateful session with HTTP 38 requests and responses. It describes two new headers, Cookie and Set- 39 Cookie2, which carry state information between participating origin 40 servers and user agents. The method described here differs from 41 Netscape's Cookie proposal [Netscape], but it can interoperate with 42 HTTP/1.0 user agents that use Netscape's method. (See the HISTORICAL 43 section.) 45 This document reflects implementation experience with RFC 2109 [RFC2109] 46 and obsoletes it. 48 2. TERMINOLOGY 50 The terms user agent, client, server, proxy, origin server, and http_URL 51 have the same meaning as in the HTTP/1.1 specification [RFC2616]. The 52 terms abs_path and absoluteURI have the same meaning as in the URI 53 Syntax specification [RFC2396]. 55 Host name (HN) means either the host domain name (HDN) or the numeric 56 Internet Protocol (IP) address of a host. The fully qualified domain 57 name is preferred; use of numeric IP addresses is strongly discouraged. 59 The terms request-host and request-URI refer to the values the client 60 would send to the server as, respectively, the host (but not port) and 61 abs_path portions of the absoluteURI (http_URL) of the HTTP request 62 line. Note that request-host is a HN. 64 The term effective host name is related to host name. If a host name 65 contains no dots, the effective host name is that name with the string 66 .local appended to it. Otherwise the effective host name is the same as 67 the host name. Note that all effective host names contain at least one 68 dot. 70 The term request-port refers to the port portion of the absoluteURI 71 (http_URL) of the HTTP request line. If the absoluteURI has no explicit 72 port, the request-port is the HTTP default, 80. The request-port of a 73 cookie is the request-port of the request in which a Set-Cookie2 74 response header was returned to the user agent. 76 Host names can be specified either as an IP address or a HDN string. 77 Sometimes we compare one host name with another. (Such comparisons 78 SHALL be case-insensitive.) Host A's name domain-matches host B's if 80 * their host name strings string-compare equal; or 82 * A is a HDN string and has the form NB, where N is a non-empty name 83 string, B has the form .B', and B' is a HDN string. (So, x.y.com 84 domain-matches .Y.com but not Y.com.) 86 Note that domain-match is not a commutative operation: a.b.c.com 87 domain-matches .c.com, but not the reverse. 89 The reach R of a host name H is defined as follows: 91 * If 93 - H is the host domain name of a host; and, 95 - H has the form A.B; and 97 - A has no embedded (that is, interior) dots; and 98 - B has at least one embedded dot, or B is the string ``local''. 99 then the reach of H is .B. 101 * Otherwise, the reach of H is H. 103 For two strings that represent paths, P1 and P2, P1 path-matches P2 if 104 P2 is a prefix of P1 (including the case where P1 and P2 string-compare 105 equal). Thus, the string /tec/waldo path-matches /tec. 107 Because it was used in Netscape's original implementation of state 108 management, we will use the term cookie to refer to the state 109 information that passes between an origin server and user agent, and 110 that gets stored by the user agent. 112 2.1 Requirements 114 The key words ``MAY'', ``MUST'', ``MUST NOT'', ``OPTIONAL'', 115 ``RECOMMENDED'', ``REQUIRED'', ``SHALL'', ``SHALL NOT'', ``SHOULD'', 116 ``SHOULD NOT'' in this document are to be interpreted as described in 117 RFC 2119 [RFC2119]. 119 3. STATE AND SESSIONS 121 This document describes a way to create stateful sessions with HTTP 122 requests and responses. Currently, HTTP servers respond to each client 123 request without relating that request to previous or subsequent 124 requests; the state management mechanism allows clients and servers that 125 wish to exchange state information to place HTTP requests and responses 126 within a larger context, which we term a ``session.'' This context 127 might be used to create, for example, a ``shopping cart,'' in which user 128 selections can be aggregated before purchase, or a magazine browsing 129 system, in which a user's previous reading affects which offerings are 130 presented. 132 Neither clients nor servers are required to support cookies. A server 133 MAY refuse to provide content to a client that does not return the 134 cookies it sends. 136 4. DESCRIPTION 138 We describe here a way for an origin server to send state information to 139 the user agent, and for the user agent to return the state information 140 to the origin server. The goal is to have a minimal impact on HTTP and 141 user agents. 143 4.1 Syntax: General 145 The two state management headers, Set-Cookie2 and Cookie, have common 146 syntactic properties involving attribute-value pairs. The following 147 grammar uses the notation, and tokens DIGIT (decimal digits), token 148 (informally, a sequence of non-special, non-white space characters), and 149 http_URL from the HTTP/1.1 specification [RFC2616] to describe their 150 syntax. 152 av-pairs = av-pair *(";" av-pair) 153 av-pair = attr ["=" value] ; optional value 154 attr = token 155 value = token | quoted-string 157 Attributes (names) (attr) are case-insensitive. White space is 158 permitted between tokens. Note that while the above syntax description 159 shows value as optional, most attrs require them. 161 NOTE: The syntax above allows whitespace between the attribute and the = 162 sign. 164 4.2 Origin Server Role 166 4.2.1 General The origin server initiates a session, if it so desires. 167 To do so, it returns an extra response header to the client, Set- 168 Cookie2. (The details follow later.) 170 A user agent returns a Cookie request header (see below) to the origin 171 server if it chooses to continue a session. The origin server MAY 172 ignore it or use it to determine the current state of the session. It 173 MAY send back to the client a Set-Cookie2 response header with the same 174 or different information, or it MAY send no Set-Cookie2 header at all. 175 The origin server effectively ends a session by sending the client a 176 Set-Cookie2 header with Max-Age=0. 178 Servers MAY return Set-Cookie2 response headers with any response. User 179 agents SHOULD send Cookie request headers, subject to other rules 180 detailed below, with every request. 182 An origin server MAY include multiple Set-Cookie2 headers in a response. 183 Note that an intervening gateway could fold multiple such headers into a 184 single header. 186 4.2.2 Set-Cookie2 Syntax The syntax for the Set-Cookie2 response 187 header is 188 set-cookie = "Set-Cookie2:" cookies 189 cookies = 1#cookie 190 cookie = NAME "=" VALUE *(";" set-cookie-av) 191 NAME = attr 192 VALUE = value 193 set-cookie-av = "Comment" "=" value 194 | "CommentURL" "=" <"> http_URL <"> 195 | "Discard" 196 | "Domain" "=" value 197 | "Max-Age" "=" value 198 | "Path" "=" value 199 | "Port" [ "=" <"> portlist <"> ] 200 | "Secure" 201 | "Version" "=" 1*DIGIT 202 portlist = 1#portnum 203 portnum = 1*DIGIT 205 Informally, the Set-Cookie2 response header comprises the token Set- 206 Cookie2:, followed by a comma-separated list of one or more cookies. 207 Each cookie begins with a NAME=VALUE pair, followed by zero or more 208 semi-colon-separated attribute-value pairs. The syntax for attribute- 209 value pairs was shown earlier. The specific attributes and the 210 semantics of their values follows. The NAME=VALUE attribute-value pair 211 MUST come first in each cookie. The others, if present, can occur in 212 any order. If an attribute appears more than once in a cookie, the 213 client SHALL use only the value associated with the first appearance of 214 the attribute; a client MUST ignore values after the first. 216 The NAME of a cookie MAY be the same as one of the attributes in this 217 specification. However, because the cookie's NAME must come first in a 218 Set-Cookie2 response header, the NAME and its VALUE cannot be confused 219 with an attribute-value pair. 221 NAME=VALUE 222 REQUIRED. The name of the state information (``cookie'') is NAME, 223 and its value is VALUE. NAMEs that begin with $ are reserved and 224 MUST NOT be used by applications. 226 The VALUE is opaque to the user agent and may be anything the 227 origin server chooses to send, possibly in a server-selected 228 printable ASCII encoding. ``Opaque'' implies that the content is 229 of interest and relevance only to the origin server. The content 230 may, in fact, be readable by anyone that examines the Set-Cookie2 231 header. 233 Comment=value 234 OPTIONAL. Because cookies can be used to derive or store private 235 information about a user, the value of the Comment attribute allows 236 an origin server to document how it intends to use the cookie. The 237 user can inspect the information to decide whether to initiate or 238 continue a session with this cookie. Characters in value MUST be 239 in UTF-8 encoding. [RFC2279] 241 CommentURL="http_URL" 242 OPTIONAL. Because cookies can be used to derive or store private 243 information about a user, the CommentURL attribute allows an origin 244 server to document how it intends to use the cookie. The user can 245 inspect the information identified by the URL to decide whether to 246 initiate or continue a session with this cookie. 248 Discard 249 OPTIONAL. The Discard attribute instructs the user agent to 250 discard the cookie unconditionally when the user agent terminates. 252 Domain=value 253 OPTIONAL. The value of the Domain attribute specifies the domain 254 for which the cookie is valid. If an explicitly specified value 255 does not start with a dot, the user agent supplies a leading dot. 257 Max-Age=value 258 OPTIONAL. The value of the Max-Age attribute is delta-seconds, the 259 lifetime of the cookie in seconds, a decimal non-negative integer. 260 To handle cached cookies correctly, a client SHOULD calculate the 261 age of the cookie according to the age calculation rules in the 262 HTTP/1.1 specification [RFC2616]. When the age is greater than 263 delta-seconds seconds, the client SHOULD discard the cookie. A 264 value of zero means the cookie SHOULD be discarded immediately. 266 Path=value 267 OPTIONAL. The value of the Path attribute specifies the subset of 268 URLs on the origin server to which this cookie applies. 270 Port[="portlist"] 271 OPTIONAL. The Port attribute restricts the port to which a cookie 272 may be returned in a Cookie request header. Note that the syntax 273 REQUIREs quotes around the OPTIONAL portlist even if there is only 274 one portnum in portlist. 276 Secure 277 OPTIONAL. The Secure attribute (with no value) directs the user 278 agent to use only (unspecified) secure means to contact the origin 279 server whenever it sends back this cookie, to protect the 280 confidentially and authenticity of the information in the cookie. 282 The user agent (possibly with user interaction) MAY determine what 283 level of security it considers appropriate for ``secure'' cookies. 284 The Secure attribute should be considered security advice from the 285 server to the user agent, indicating that it is in the session's 286 interest to protect the cookie contents. When it sends a 287 ``secure'' cookie back to a server, the user agent SHOULD use no 288 less than the same level of security as was used when it received 289 the cookie from the server. 291 Version=value 292 REQUIRED. The value of the Version attribute, a decimal integer, 293 identifies the version of the state management specification to 294 which the cookie conforms. For this specification, Version=1 295 applies. 297 4.2.3 Controlling Caching An origin server must be cognizant of the 298 effect of possible caching of both the returned resource and the Set- 299 Cookie2 header. Caching ``public'' documents is desirable. For 300 example, if the origin server wants to use a public document such as a 301 ``front door'' page as a sentinel to indicate the beginning of a session 302 for which a Set-Cookie2 response header must be generated, the page 303 SHOULD be stored in caches ``pre-expired'' so that the origin server 304 will see further requests. ``Private documents,'' for example those 305 that contain information strictly private to a session, SHOULD NOT be 306 cached in shared caches. 308 If the cookie is intended for use by a single user, the Set-Cookie2 309 header SHOULD NOT be cached. A Set-Cookie2 header that is intended to 310 be shared by multiple users MAY be cached. 312 The origin server SHOULD send the following additional HTTP/1.1 response 313 headers, depending on circumstances: 315 * To suppress caching of the Set-Cookie2 header: 317 Cache-control: no-cache="set-cookie2" 319 and one of the following: 321 * To suppress caching of a private document in shared caches: 323 Cache-control: private 325 * To allow caching of a document and require that it be validated 326 before returning it to the client: 328 Cache-Control: must-revalidate, max-age=0 330 * To allow caching of a document, but to require that proxy caches 331 (not user agent caches) validate it before returning it to the 332 client: 334 Cache-Control: proxy-revalidate, max-age=0 336 * To allow caching of a document and request that it be validated 337 before returning it to the client (by ``pre-expiring'' it): 339 Cache-control: max-age=0 341 Not all caches will revalidate the document in every case. 343 HTTP/1.1 servers MUST send Expires: old-date (where old-date is a date 344 long in the past) on responses containing Set-Cookie2 response headers 345 unless they know for certain (by out of band means) that there are no 346 HTTP/1.0 proxies in the response chain. HTTP/1.1 servers MAY send other 347 Cache-Control directives that permit caching by HTTP/1.1 proxies in 348 addition to the Expires: old-date directive; the Cache-Control directive 349 will override the Expires: old-date for HTTP/1.1 proxies. 351 4.3 User Agent Role 353 4.3.1 Interpreting Set-Cookie2 The user agent keeps separate track of 354 state information that arrives via Set-Cookie2 response headers from 355 each origin server (as distinguished by name or IP address and port). 356 The user agent MUST ignore attribute-value pairs whose attribute it does 357 not recognize. The user agent applies these defaults for optional 358 attributes that are missing: 360 Discard The default behavior is dictated by the presence or absence of a 361 Max-Age attribute. 363 Domain Defaults to the effective request-host. (Note that because 364 there is no dot at the beginning of effective request-host, the 365 default Domain can only domain-match itself.) 367 Max-Age The default behavior is to discard the cookie when the user 368 agent exits. 370 Path Defaults to the path of the request URL that generated the Set- 371 Cookie2 response, up to and including the right-most /. 373 Port The default behavior is that a cookie MAY be returned to any 374 request-port. 376 Secure If absent, the user agent MAY send the cookie over an insecure 377 channel. 379 4.3.2 Rejecting Cookies To prevent possible security or privacy 380 violations, a user agent rejects a cookie according to rules below. The 381 goal of the rules is to try to limit the set of servers for which a 382 cookie is valid, based on the values of the Path, Domain, and Port 383 attributes and the request-URI, request-host and request-port. 385 A user agent rejects (SHALL NOT store its information) if the Version 386 attribute is missing. Moreover, a user agent rejects (SHALL NOT store 387 its information) if any of the following is true of the attributes 388 explicitly present in the Set-Cookie2 response header: 390 * The value for the Path attribute is not a prefix of the request- 391 URI. 393 * The value for the Domain attribute contains no embedded dots, and 394 the value is not .local. 396 * The effective host name that derives from the request-host does not 397 domain-match the Domain attribute. 399 * The request-host is a HDN (not IP address) and has the form HD, 400 where D is the value of the Domain attribute, and H is a string 401 that contains one or more dots. 403 * The Port attribute has a "port-list", and the request-port was not 404 in the list. 406 Examples: 408 * A Set-Cookie2 from request-host y.x.foo.com for Domain=.foo.com 409 would be rejected, because H is y.x and contains a dot. 411 * A Set-Cookie2 from request-host x.foo.com for Domain=.foo.com would 412 be accepted. 414 * A Set-Cookie2 with Domain=.com or Domain=.com., will always be 415 rejected, because there is no embedded dot. 417 * A Set-Cookie2 with Domain=ajax.com will be accepted, and the value 418 for Domain will be taken to be .ajax.com, because a dot gets 419 prepended to the value. 421 * A Set-Cookie2 with Port="80,8000" will be accepted if the request 422 was made to port 80 or 8000 and will be rejected otherwise. 424 * A Set-Cookie2 from request-host example for Domain=.local will be 425 accepted, because the effective host name for the request-host is 426 example.local, and example.local domain-matches .local. 428 4.3.3 Cookie Management If a user agent receives a Set-Cookie2 429 response header whose NAME is the same as that of a cookie it has 430 previously stored, the new cookie supersedes the old when: the old and 431 new Domain attribute values compare equal, using a case-insensitive 432 string-compare; and, the old and new Path attribute values string- 433 compare equal (case-sensitive). However, if the Set-Cookie2 has a value 434 for Max-Age of zero, the (old and new) cookie is discarded. Otherwise a 435 cookie persists (resources permitting) until whichever happens first, 436 then gets discarded: its Max-Age lifetime is exceeded; or, if the 437 Discard attribute is set, the user agent terminates the session. 439 Because user agents have finite space in which to store cookies, they 440 MAY also discard older cookies to make space for newer ones, using, for 441 example, a least-recently-used algorithm, along with constraints on the 442 maximum number of cookies that each origin server may set. 444 If a Set-Cookie2 response header includes a Comment attribute, the user 445 agent SHOULD store that information in a human-readable form with the 446 cookie and SHOULD display the comment text as part of a cookie 447 inspection user interface. 449 If a Set-Cookie2 response header includes a CommentURL attribute, the 450 user agent SHOULD store that information in a human-readable form with 451 the cookie, or, preferably, SHOULD allow the user to follow the http_URL 452 link as part of a cookie inspection user interface. 454 The cookie inspection user interface may include a facility whereby a 455 user can decide, at the time the user agent receives the Set-Cookie2 456 response header, whether or not to accept the cookie. A potentially 457 confusing situation could arise if the following sequence occurs: 459 * the user agent receives a cookie that contains a CommentURL 460 attribute; 462 * the user agent's cookie inspection interface is configured so that 463 it presents a dialog to the user before the user agent accepts the 464 cookie; 466 * the dialog allows the user to follow the CommentURL link when the 467 user agent receives the cookie; and, 469 * when the user follows the CommentURL link, the origin server (or 470 another server, via other links in the returned content) returns 471 another cookie. 473 The user agent SHOULD NOT send any cookies in this context. The user 474 agent MAY discard any cookie it receives in this context that the user 475 has not, through some user agent mechanism, deemed acceptable. 477 User agents SHOULD allow the user to control cookie destruction, but 478 they MUST NOT extend the cookie's lifetime beyond that controlled by the 479 Discard and Max-Age attributes. An infrequently-used cookie may 480 function as a ``preferences file'' for network applications, and a user 481 may wish to keep it even if it is the least-recently-used cookie. One 482 possible implementation would be an interface that allows the permanent 483 storage of a cookie through a checkbox (or, conversely, its immediate 484 destruction). 486 Privacy considerations dictate that the user have considerable control 487 over cookie management. The PRIVACY section contains more information. 489 4.3.4 Sending Cookies to the Origin Server When it sends a request to 490 an origin server, the user agent includes a Cookie request header if it 491 has stored cookies that are applicable to the request, based on 493 * the request-host and request-port; 494 * the request-URI; 496 * the cookie's age. 498 The syntax for the header is: 500 cookie = "Cookie:" cookie-version 1*((";" | ",") cookie-value) 501 cookie-value = NAME "=" VALUE [";" path] [";" domain] [";" port] 502 cookie-version = "$Version" "=" value 503 NAME = attr 504 VALUE = value 505 path = "$Path" "=" value 506 domain = "$Domain" "=" value 507 port = "$Port" [ "=" <"> value <"> ] 509 The value of the cookie-version attribute MUST be the value from the 510 Version attribute of the corresponding Set-Cookie2 response header. 511 Otherwise the value for cookie-version is 0. The value for the path 512 attribute MUST be the value from the Path attribute, if one was present, 513 of the corresponding Set-Cookie2 response header. Otherwise the 514 attribute SHOULD be omitted from the Cookie request header. The value 515 for the domain attribute MUST be the value from the Domain attribute, if 516 one was present, of the corresponding Set-Cookie2 response header. 517 Otherwise the attribute SHOULD be omitted from the Cookie request 518 header. 520 The port attribute of the Cookie request header MUST mirror the Port 521 attribute, if one was present, in the corresponding Set-Cookie2 response 522 header. That is, the port attribute MUST be present if the Port 523 attribute was present in the Set-Cookie2 header, and it MUST have the 524 same value, if any. Otherwise, if the Port attribute was absent from 525 the Set-Cookie2 header, the attribute likewise MUST be omitted from the 526 Cookie request header. 528 Note that there is neither a Comment nor a CommentURL attribute in the 529 Cookie request header corresponding to the ones in the Set-Cookie2 530 response header. The user agent does not return the comment information 531 to the origin server. 533 The user agent applies the following rules to choose applicable cookie- 534 values to send in Cookie request headers from among all the cookies it 535 has received. 537 Domain Selection 538 The origin server's effective host name MUST domain-match the 539 Domain attribute of the cookie. 541 Port Selection 542 There are three possible behaviors, depending on the Port attribute 543 in the Set-Cookie2 response header: 545 1. By default (no Port attribute), the cookie MAY be sent to any 546 port. 548 2. If the attribute is present but has no value (e.g., Port), 549 the cookie MUST only be sent to the request-port it was 550 received from. 552 3. If the attribute has a port-list, the cookie MUST only be 553 returned if the new request-port is one of those listed in 554 port-list. 556 Path Selection 557 The request-URI MUST path-match the Path attribute of the cookie. 559 Max-Age Selection 560 Cookies that have expired should have been discarded and thus are 561 not forwarded to an origin server. 563 If multiple cookies satisfy the criteria above, they are ordered in the 564 Cookie header such that those with more specific Path attributes precede 565 those with less specific. Ordering with respect to other attributes 566 (e.g., Domain) is unspecified. 568 Note: For backward compatibility, the separator in the Cookie header is 569 semi-colon (;) everywhere. A server SHOULD also accept comma (,) as the 570 separator between cookie-values for future compatibility. 572 4.3.5 Identifying What Version is Understood: Cookie2 The Cookie2 573 request header facilitates interoperation between clients and servers 574 that understand different versions of the cookie specification. When 575 the client sends one or more cookies to an origin server, if at least 576 one of those cookies contains a $Version attribute whose value is 577 different from the version that the client understands, then the client 578 MUST also send a Cookie2 request header, the syntax for which is 580 cookie2 = "Cookie2:" cookie-version 582 Here the value for cookie-version is the highest version of cookie 583 specification (currently 1) that the client understands. The client 584 needs to send at most one such request header per request. 586 4.3.6 Sending Cookies in Unverifiable Transactions Users MUST have 587 control over sessions in order to ensure privacy. (See PRIVACY section 588 below.) To simplify implementation and to prevent an additional layer 589 of complexity where adequate safeguards exist, however, this document 590 distinguishes between transactions that are verifiable and those that 591 are unverifiable. A transaction is verifiable if the user, or a user- 592 designated agent, has the option to review the request-URI prior to its 593 use in the transaction. A transaction is unverifiable if the user does 594 not have that option. Unverifiable transactions typically arise when a 595 user agent automatically requests inlined or embedded entities or when 596 it resolves redirection (3xx) responses from an origin server. 597 Typically the origin transaction, the transaction that the user 598 initiates, is verifiable, and that transaction may directly or 599 indirectly induce the user agent to make unverifiable transactions. 601 An unverifiable transaction is to a third-party host if its request-host 602 U does not domain-match the reach R of the request-host O in the origin 603 transaction. 605 When it makes an unverifiable transaction, a user agent MUST disable all 606 cookie processing (i.e., MUST NOT send cookies, and MUST NOT accept any 607 received cookies) if the transaction is to a third-party host. 609 This restriction prevents a malicious service author from using 610 unverifiable transactions to induce a user agent to start or continue a 611 session with a server in a different domain. The starting or 612 continuation of such sessions could be contrary to the privacy 613 expectations of the user, and could also be a security problem. 615 User agents MAY offer configurable options that allow the user agent, or 616 any autonomous programs that the user agent executes, to ignore the 617 above rule, so long as these override options default to ``off.'' 619 (N.B. Mechanisms may be proposed that will automate overriding the 620 third-party restrictions under controlled conditions.) 622 Many current user agents already provide a review option that would 623 render many links verifiable. For instance, some user agents display 624 the URL that would be referenced for a particular link when the mouse 625 pointer is placed over that link. The user can therefore determine 626 whether to visit that site before causing the browser to do so. (Though 627 not implemented on current user agents, a similar technique could be 628 used for a button used to submit a form -- the user agent could display 629 the action to be taken if the user were to select that button.) 630 However, even this would not make all links verifiable; for example, 631 links to automatically loaded images would not normally be subject to 632 ``mouse pointer'' verification. 634 Many user agents also provide the option for a user to view the HTML 635 source of a document, or to save the source to an external file where it 636 can be viewed by another application. While such an option does provide 637 a crude review mechanism, some users might not consider it acceptable 638 for this purpose. 640 4.4 How an Origin Server Interprets the Cookie Header 642 A user agent returns much of the information in the Set-Cookie2 header 643 to the origin server when the request-URI path-matches the Path 644 attribute of the cookie. When it receives a Cookie header, the origin 645 server SHOULD treat cookies with NAMEs whose prefix is $ specially, as 646 an attribute for the cookie. 648 4.5 Caching Proxy Role 650 One reason for separating state information from both a URL and document 651 content is to facilitate the scaling that caching permits. To support 652 cookies, a caching proxy MUST obey these rules already in the HTTP 653 specification: 655 * Honor requests from the cache, if possible, based on cache validity 656 rules. 658 * Pass along a Cookie request header in any request that the proxy 659 must make of another server. 661 * Return the response to the client. Include any Set-Cookie2 662 response header. 664 * Cache the received response subject to the control of the usual 665 headers, such as Expires, 667 Cache-control: no-cache 669 and 671 Cache-control: private 673 * Cache the Set-Cookie2 subject to the control of the usual header, 675 Cache-control: no-cache="set-cookie2" 677 (The Set-Cookie2 header should usually not be cached.) 679 Proxies MUST not introduce Set-Cookie2 (Cookie) headers of their own in 680 proxy responses (requests). 682 5. EXAMPLES 684 5.1 Example 1 686 Most detail of request and response headers has been omitted. Assume 687 the user agent has no stored cookies. 689 1. User Agent -> Server 691 POST /acme/login HTTP/1.1 692 [form data] 694 User identifies self via a form. 696 2. Server -> User Agent 697 HTTP/1.1 200 OK 698 Set-Cookie2: Customer="WILE_E_COYOTE"; Version="1"; Path="/acme" 700 Cookie reflects user's identity. 702 3. User Agent -> Server 704 POST /acme/pickitem HTTP/1.1 705 Cookie: $Version="1"; Customer="WILE_E_COYOTE"; $Path="/acme" 706 [form data] 708 User selects an item for ``shopping basket.'' 710 4. Server -> User Agent 712 HTTP/1.1 200 OK 713 Set-Cookie2: Part_Number="Rocket_Launcher_0001"; Version="1"; 714 Path="/acme" 716 Shopping basket contains an item. 718 5. User Agent -> Server 720 POST /acme/shipping HTTP/1.1 721 Cookie: $Version="1"; 722 Customer="WILE_E_COYOTE"; $Path="/acme"; 723 Part_Number="Rocket_Launcher_0001"; $Path="/acme" 724 [form data] 726 User selects shipping method from form. 728 6. Server -> User Agent 730 HTTP/1.1 200 OK 731 Set-Cookie2: Shipping="FedEx"; Version="1"; Path="/acme" 733 New cookie reflects shipping method. 735 7. User Agent -> Server 737 POST /acme/process HTTP/1.1 738 Cookie: $Version="1"; 739 Customer="WILE_E_COYOTE"; $Path="/acme"; 740 Part_Number="Rocket_Launcher_0001"; $Path="/acme"; 741 Shipping="FedEx"; $Path="/acme" 742 [form data] 744 User chooses to process order. 746 8. Server -> User Agent 747 HTTP/1.1 200 OK 749 Transaction is complete. 751 The user agent makes a series of requests on the origin server, after 752 each of which it receives a new cookie. All the cookies have the same 753 Path attribute and (default) domain. Because the request-URIs all 754 path-match /acme, the Path attribute of each cookie, each request 755 contains all the cookies received so far. 757 5.2 Example 2 759 This example illustrates the effect of the Path attribute. All detail 760 of request and response headers has been omitted. Assume the user agent 761 has no stored cookies. 763 Imagine the user agent has received, in response to earlier requests, 764 the response headers 766 Set-Cookie2: Part_Number="Rocket_Launcher_0001"; Version="1"; 767 Path="/acme" 769 and 771 Set-Cookie2: Part_Number="Riding_Rocket_0023"; Version="1"; 772 Path="/acme/ammo" 774 A subsequent request by the user agent to the (same) server for URLs of 775 the form /acme/ammo/... would include the following request header: 777 Cookie: $Version="1"; 778 Part_Number="Riding_Rocket_0023"; $Path="/acme/ammo"; 779 Part_Number="Rocket_Launcher_0001"; $Path="/acme" 781 Note that the NAME=VALUE pair for the cookie with the more specific Path 782 attribute, /acme/ammo, comes before the one with the less specific Path 783 attribute, /acme. Further note that the same cookie name appears more 784 than once. 786 A subsequent request by the user agent to the (same) server for a URL of 787 the form /acme/parts/ would include the following request header: 789 Cookie: $Version="1"; Part_Number="Rocket_Launcher_0001"; $Path="/acme" 791 Here, the second cookie's Path attribute /acme/ammo is not a prefix of 792 the request URL, /acme/parts/, so the cookie does not get forwarded to 793 the server. 795 6. IMPLEMENTATION CONSIDERATIONS 797 Here we provide guidance on likely or desirable details for an origin 798 server that implements state management. 800 6.1 Set-Cookie2 Content 802 An origin server's content should probably be divided into disjoint 803 application areas, some of which require the use of state information. 804 The application areas can be distinguished by their request URLs. The 805 Set-Cookie2 header can incorporate information about the application 806 areas by setting the Path attribute for each one. 808 The session information can obviously be clear or encoded text that 809 describes state. However, if it grows too large, it can become 810 unwieldy. Therefore, an implementor might choose for the session 811 information to be a key to a server-side resource. Of course, using a 812 database creates some problems that this state management specification 813 was meant to avoid, namely: 815 1. keeping real state on the server side; 817 2. how and when to garbage-collect the database entry, in case the 818 user agent terminates the session by, for example, exiting. 820 6.2 Stateless Pages 822 Caching benefits the scalability of WWW. Therefore it is important to 823 reduce the number of documents that have state embedded in them 824 inherently. For example, if a shopping-basket-style application always 825 displays a user's current basket contents on each page, those pages 826 cannot be cached, because each user's basket's contents would be 827 different. On the other hand, if each page contains just a link that 828 allows the user to ``Look at My Shopping Basket,'' the page can be 829 cached. 831 6.3 Implementation Limits 833 Practical user agent implementations have limits on the number and size 834 of cookies that they can store. In general, user agents' cookie support 835 should have no fixed limits. They should strive to store as many 836 frequently-used cookies as possible. Furthermore, general-use user 837 agents SHOULD provide each of the following minimum capabilities 838 individually, although not necessarily simultaneously: 840 * at least 300 cookies 842 * at least 4096 bytes per cookie (as measured by the characters that 843 comprise the cookie non-terminal in the syntax description of the 844 Set-Cookie2 header, and as received in the Set-Cookie2 header) 846 * at least 20 cookies per unique host or domain name 848 User agents created for specific purposes or for limited-capacity 849 devices SHOULD provide at least 20 cookies of 4096 bytes, to ensure that 850 the user can interact with a session-based origin server. 852 The information in a Set-Cookie2 response header MUST be retained in its 853 entirety. If for some reason there is inadequate space to store the 854 cookie, it MUST be discarded, not truncated. 856 Applications should use as few and as small cookies as possible, and 857 they should cope gracefully with the loss of a cookie. 859 6.3.1 Denial of Service Attacks User agents MAY choose to set an upper 860 bound on the number of cookies to be stored from a given host or domain 861 name or on the size of the cookie information. Otherwise a malicious 862 server could attempt to flood a user agent with many cookies, or large 863 cookies, on successive responses, which would force out cookies the user 864 agent had received from other servers. However, the minima specified 865 above SHOULD still be supported. 867 7. PRIVACY 869 Informed consent should guide the design of systems that use cookies. A 870 user should be able to find out how a web site plans to use information 871 in a cookie and should be able to choose whether or not those policies 872 are acceptable. Both the user agent and the origin server must assist 873 informed consent. 875 7.1 User Agent Control 877 An origin server could create a Set-Cookie2 header to track the path of 878 a user through the server. Users may object to this behavior as an 879 intrusive accumulation of information, even if their identity is not 880 evident. (Identity might become evident, for example, if a user 881 subsequently fills out a form that contains identifying information.) 882 This state management specification therefore requires that a user agent 883 give the user control over such a possible intrusion, although the 884 interface through which the user is given this control is left 885 unspecified. However, the control mechanisms provided SHALL at least 886 allow the user 888 * to completely disable the sending and saving of cookies. 890 * to determine whether a stateful session is in progress. 892 * to control the saving of a cookie on the basis of the cookie's 893 Domain attribute. 895 Such control could be provided, for example, by mechanisms 897 * to notify the user when the user agent is about to send a cookie to 898 the origin server, to offer the option not to begin a session. 900 * to display a visual indication that a stateful session is in 901 progress. 903 * to let the user decide which cookies, if any, should be saved when 904 the user concludes a window or user agent session. 906 * to let the user examine and delete the contents of a cookie at any 907 time. 909 A user agent usually begins execution with no remembered state 910 information. It SHOULD be possible to configure a user agent never to 911 send Cookie headers, in which case it can never sustain state with an 912 origin server. (The user agent would then behave like one that is 913 unaware of how to handle Set-Cookie2 response headers.) 915 When the user agent terminates execution, it SHOULD let the user discard 916 all state information. Alternatively, the user agent MAY ask the user 917 whether state information should be retained; the default should be 918 ``no.'' If the user chooses to retain state information, it would be 919 restored the next time the user agent runs. 921 NOTE: User agents should probably be cautious about using files to store 922 cookies long-term. If a user runs more than one instance of the user 923 agent, the cookies could be commingled or otherwise corrupted. 925 7.2 Origin Server Role 927 A origin server SHOULD promote informed consent by adding CommentURL or 928 Comment information to the cookies it sends. CommentURL is preferred 929 because of the opportunity to provide richer information in a 930 multiplicity of languages. 932 7.3 Clear Text 934 The information in the Set-Cookie2 and Cookie headers is unprotected. 935 As a consequence: 937 1. Any sensitive information that is conveyed in them is exposed to 938 intruders. 940 2. A malicious intermediary could alter the headers as they travel in 941 either direction, with unpredictable results. 943 These facts imply that information of a personal and/or financial nature 944 should only be sent over a secure channel. For less sensitive 945 information, or when the content of the header is a database key, an 946 origin server should be vigilant to prevent a bad Cookie value from 947 causing failures. 949 A user agent in a shared user environment poses a further risk. Using a 950 cookie inspection interface, User B could examine the contents of 951 cookies that were saved when User A used the machine. 953 8. SECURITY CONSIDERATIONS 955 8.1 Protocol Design 957 The restrictions on the value of the Domain attribute, and the rules 958 concerning unverifiable transactions, are meant to reduce the ways that 959 cookies can ``leak'' to the ``wrong'' site. The intent is to restrict 960 cookies to one host, or a closely related set of hosts. Therefore a 961 request-host is limited as to what values it can set for Domain. We 962 consider it acceptable for hosts host1.foo.com and host2.foo.com to 963 share cookies, but not a.com and b.com. 965 Similarly, a server can set a Path only for cookies that are related to 966 the request-URI. 968 8.2 Cookie Spoofing 970 Proper application design can avoid spoofing attacks from related 971 domains. Consider: 973 1. User agent makes request to victim.cracker.edu, gets back cookie 974 session_id="1234" and sets the default domain victim.cracker.edu. 976 2. User agent makes request to spoof.cracker.edu, gets back cookie 977 session-id="1111", with Domain=".cracker.edu". 979 3. User agent makes request to victim.cracker.edu again, and passes 981 Cookie: $Version="1"; session_id="1234", 982 $Version="1"; session_id="1111"; $Domain=".cracker.edu" 984 The server at victim.cracker.edu should detect that the second 985 cookie was not one it originated by noticing that the Domain 986 attribute is not for itself and ignore it. 988 8.3 Unexpected Cookie Sharing 990 A user agent SHOULD make every attempt to prevent the sharing of session 991 information between hosts that are in different domains. Embedded or 992 inlined objects may cause particularly severe privacy problems if they 993 can be used to share cookies between disparate hosts. For example, a 994 malicious server could embed cookie information for host a.com in a URI 995 for a CGI on host b.com. User agent implementors are strongly 996 encouraged to prevent this sort of exchange whenever possible. 998 8.4 Cookies For Account Information 1000 While it is common practice to use them this way, cookies are not 1001 designed or intended to be used to hold authentication information, such 1002 as account names and passwords. Unless such cookies are exchanged over 1003 an encrypted path, the account information they contain is highly 1004 vulnerable to perusal and theft. 1006 9. OTHER, SIMILAR, PROPOSALS 1008 Apart from RFC 2109, three other proposals have been made to accomplish 1009 similar goals. This specification began as an amalgam of Kristol's 1010 State-Info proposal [DMK95] and Netscape's Cookie proposal [Netscape]. 1012 Brian Behlendorf proposed a Session-ID header that would be user-agent- 1013 initiated and could be used by an origin server to track 1014 ``clicktrails.'' It would not carry any origin-server-defined state, 1015 however. Phillip Hallam-Baker has proposed another client-defined 1016 session ID mechanism for similar purposes. 1018 While both session IDs and cookies can provide a way to sustain stateful 1019 sessions, their intended purpose is different, and, consequently, the 1020 privacy requirements for them are different. A user initiates session 1021 IDs to allow servers to track progress through them, or to distinguish 1022 multiple users on a shared machine. Cookies are server-initiated, so 1023 the cookie mechanism described here gives users control over something 1024 that would otherwise take place without the users' awareness. 1025 Furthermore, cookies convey rich, server-selected information, whereas 1026 session IDs comprise user-selected, simple information. 1028 10. HISTORICAL 1030 10.1 Compatibility with Existing Implementations 1032 Existing cookie implementations, based on the Netscape specification, 1033 use the Set-Cookie (not Set-Cookie2) header. User agents that receive 1034 in the same response both a Set-Cookie and Set-Cookie2 response header 1035 for the same cookie MUST discard the Set-Cookie information and use only 1036 the Set-Cookie2 information. Furthermore, a user agent MUST assume, if 1037 it received a Set-Cookie2 response header, that the sending server 1038 complies with this document and will understand Cookie request headers 1039 that also follow this specification. 1041 New cookies MUST replace both equivalent old- and new-style cookies. 1042 That is, if a user agent that follows both this specification and 1043 Netscape's original specification receives a Set-Cookie2 response 1044 header, and the NAME and the Domain and Path attributes match (per the 1045 Cookie Management section) a Netscape-style cookie, the Netscape-style 1046 cookie MUST be discarded, and the user agent MUST retain only the cookie 1047 adhering to this specification. 1049 Older user agents that do not understand this specification, but that do 1050 understand Netscape's original specification, will not recognize the 1051 Set-Cookie2 response header and will receive and send cookies according 1052 to the older specification. 1054 A user agent that supports both this specification and Netscape-style 1055 cookies SHOULD send a Cookie request header that follows the older 1056 Netscape specification if it received the cookie in a Set-Cookie 1057 response header and not in a Set-Cookie2 response header. However, it 1058 SHOULD send the following request header as well: 1060 Cookie2: $Version="1" 1062 The Cookie2 header advises the server that the user agent understands 1063 new-style cookies. If the server understands new-style cookies, as 1064 well, it SHOULD continue the stateful session by sending a Set-Cookie2 1065 response header, rather than Set-Cookie. A server that does not 1066 understand new-style cookies will simply ignore the Cookie2 request 1067 header. 1069 10.2 Caching and HTTP/1.0 1071 Some caches, such as those conforming to HTTP/1.0, will inevitably cache 1072 the Set-Cookie2 and Set-Cookie headers, because there was no mechanism 1073 to suppress caching of headers prior to HTTP/1.1. This caching can lead 1074 to security problems. Documents transmitted by an origin server along 1075 with Set-Cookie2 and Set-Cookie headers usually either will be 1076 uncachable, or will be ``pre-expired.'' As long as caches obey 1077 instructions not to cache documents (following Expires: or Pragma: no-cache (HTTP/1.0), or Cache-control: no-cache 1079 (HTTP/1.1)) uncachable documents present no problem. However, pre- 1080 expired documents may be stored in caches. They require validation (a 1081 conditional GET) on each new request, but some cache operators loosen 1082 the rules for their caches, and sometimes serve expired documents 1083 without first validating them. This combination of factors can lead to 1084 cookies meant for one user later being sent to another user. The Set- 1085 Cookie2 and Set-Cookie headers are stored in the cache, and, although 1086 the document is stale (expired), the cache returns the document in 1087 response to later requests, including cached headers. 1089 11. ACKNOWLEDGEMENTS 1091 This document really represents the collective efforts of the HTTP 1092 Working Group of the IETF and, particularly, the following people, in 1093 addition to the authors: Roy Fielding, Yaron Goland, Marc Hedlund, Ted 1094 Hardie, Koen Holtman, Shel Kaphan, Rohit Khare, Foteos Macrides, David 1095 W. Morris. 1097 12. AUTHORS' ADDRESSES 1099 David M. Kristol 1100 Bell Laboratories, Lucent Technologies 1101 600 Mountain Ave. Room 2A-333 1102 Murray Hill, NJ 07974 1104 Phone: (908) 582-2250 1105 FAX: (908) 582-1239 1106 Email: dmk@bell-labs.com 1108 Lou Montulli 1109 Epinions.com, Inc. 1110 2037 Landings Dr. 1111 Mountain View, CA 94301 1112 Email: lou@montulli.org 1114 13. REFERENCES 1116 [DMK95]Kristol, D.M., ``Proposed HTTP State-Info Mechanism'', available 1117 at , 1118 September, 1995. 1120 [Netscape] ``Persistent Client State -- HTTP Cookies'', available at 1121 , undated. 1123 [RFC2109] Kristol, D.M., Montulli, L., ``HTTP State Management 1124 Mechanism'', RFC 2109, February, 1997. 1126 [RFC2119] Bradner, S., ``Key words for use in RFCs to Indicate 1127 Requirement Levels'', RFC 2119, March 1997. 1129 [RFC2279] Yergeau, F., ``UTF-8, a transformation format of Unicode and 1130 ISO-10646'', RFC 2279, January 1998. 1132 [RFC2396] Berners-Lee, T., Fielding, R., Masinter, L., ``Uniform 1133 Resource Identifiers (URI): Generic Syntax'', RFC 2396, August, 1134 1998. 1136 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Berners-Lee, 1137 T., ``Hypertext Transfer Protocol -- HTTP/1.1'', RFC 2616, June, 1138 1999. 1140 Expires February 27, 2000