idnits 2.17.1 draft-ietf-http-state-man-mec-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-24) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** 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 seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** 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 535 instances of lines with control characters in the document. ** 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.) -- Couldn't find a document date in the document -- date freshness check skipped. 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 991, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'Netscape' ** Obsolete normative reference: RFC 2068 (Obsoleted by RFC 2616) ** Obsolete normative reference: RFC 2109 (Obsoleted by RFC 2965) Summary: 14 errors (**), 0 flaws (~~), 7 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 TTP Working Group David M. Kristol 3 INTERNET DRAFT Bell Laboratories, Lucent Technologies 4 Obsoletes: RFC 2109 Lou Montulli 5 Netscape Communications 6 7 July 24, 1998 Expires January 24, 1999 9 HTTP State Management Mechanism 11 Status of this Memo 13 This document is an Internet-Draft. Internet-Drafts are 14 working documents of the Internet Engineering Task Force 15 (IETF), its areas, and its working groups. Note that other 16 groups may also distribute working documents as Internet- 17 Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six 20 months and may be updated, replaced, or obsoleted by other 21 documents at any time. It is inappropriate to use Internet- 22 Drafts as reference material or to cite them other than as 23 ``work in progress.'' 25 To learn the current status of any Internet-Draft, please 26 check the ``1id-abstracts.txt'' listing contained in the 27 Internet- Drafts Shadow Directories on ftp.is.co.za (Africa), 28 nic.nordu.net (Europe), munnari.oz.au (Pacific Rim), 29 ftp.ietf.org (US East Coast), or ftp.isi.edu (US West 30 Coast). 32 This is authors' draft %I%. 34 1. ABSTRACT 36 This document specifies a way to create a stateful session with HTTP 37 requests and responses. It describes two new headers, Cookie and Set- 38 Cookie2, which carry state information between participating origin 39 servers and user agents. The method described here differs from 40 Netscape's Cookie proposal [Netscape], but it can interoperate with 41 TTP/1.0 user agents that use Netscape's method. (See the HISTORICAL 42 section.) 44 This document reflects implementation experience with RFC 2109 [RFC2109] 45 and obsoletes it. 47 2. TERMINOLOGY 49 The terms user agent, client, server, proxy, and origin server have the 50 same meaning as in the HTTP/1.1 specification [RFC2068]. 52 Host name (HN) means either the host domain name (HDN) or the numeric 53 Internet Protocol (IP) address of a host. The fully qualified domain 54 name is preferred; use of numeric IP addresses is strongly discouraged. 56 The terms request-host and request-URI refer to the values the client 57 would send to the server as, respectively, the host (but not port) and 58 abs_path portions of the absoluteURI (http_URL) of the HTTP request 59 line. Note that request-host is a HN. 61 The term effective host name is related to host name. If a host name 62 contains no dots, the effective host name is that name with the string 63 .local appended to it. Otherwise the effective host name is the same as 64 the host name. Note that all effective host names contain at least one 65 dot. 67 The term request-port refers to the port portion of the absoluteURI 68 (http_URL) of the HTTP request line. If the absoluteURI has no explicit 69 port, the request-port is the HTTP default, 80. The request-port of a 70 cookie is the request-port of the request in which a Set-Cookie2 71 response header was returned to the user agent. 73 ost names can be specified either as an IP address or a HDN string. 74 Sometimes we compare one host name with another. Host A's name domain- 75 matches host B's if 77 o their host name strings match exactly; or 79 o A is a HDN string and has the form NB, where N is a non-empty name 80 string, B has the form .B', and B' is a HDN string. (So, x.y.com 81 domain-matches .y.com but not y.com.) 83 Note that domain-match is not a commutative operation: a.b.c.com 84 domain-matches .c.com, but not the reverse. 86 The reach R of a host name H is defined as follows: 88 o If 90 - H is the host domain name of a host; and, 92 - H has the form A.B; and 94 - A has no embedded (that is, interior) dots; and 96 - B has at least one embedded dot, or B is the string ``local''. 97 then the reach of H is .B. 99 o Otherwise, the reach of H is H. 101 Because it was used in Netscape's original implementation of state 102 management, we will use the term cookie to refer to the state 103 information that passes between an origin server and user agent, and 104 that gets stored by the user agent. 106 2.1 Requirements 108 The key words ``MAY'', ``MUST'', ``MUST NOT'', ``OPTIONAL'', 109 ``RECOMMENDED'', ``REQUIRED'', ``SHALL'', ``SHALL NOT'', ``SHOULD'', 110 ``SHOULD NOT'' in this document are to be interpreted as described in 111 RFC 2119 [RFC2119]. 113 3. STATE AND SESSIONS 115 This document describes a way to create stateful sessions with HTTP 116 requests and responses. Currently, HTTP servers respond to each client 117 request without relating that request to previous or subsequent 118 requests; the state management mechanism allows clients and servers that 119 wish to exchange state information to place HTTP requests and responses 120 within a larger context, which we term a ``session.'' This context 121 might be used to create, for example, a ``shopping cart,'' in which user 122 selections can be aggregated before purchase, or a magazine browsing 123 system, in which a user's previous reading affects which offerings are 124 presented. 126 Neither clients nor servers are required to support cookies. A server 127 MAY refuse to provide content to a client that does not return the 128 cookies it sends. 130 4. DESCRIPTION 132 We describe here a way for an origin server to send state information to 133 the user agent, and for the user agent to return the state information 134 to the origin server. The goal is to have a minimal impact on HTTP and 135 user agents. 137 4.1 Syntax: General 139 The two state management headers, Set-Cookie2 and Cookie, have common 140 syntactic properties involving attribute-value pairs. The following 141 grammar uses the notation, and tokens DIGIT (decimal digits), token 142 (informally, a sequence of non-special, non-white space characters), and 143 http_URL from the HTTP/1.1 specification [RFC2068] to describe their 144 syntax. 146 av-pairs = av-pair *(";" av-pair) 147 av-pair = attr ["=" value] ; optional value 148 attr = token 149 value = token | quoted-string 150 Attributes (names) (attr) are case-insensitive. White space is 151 permitted between tokens. Note that while the above syntax description 152 shows value as optional, most attrs require them. 154 NOTE: The syntax above allows whitespace between the attribute and the = 155 sign. 157 4.2 Origin Server Role 159 4.2.1 General The origin server initiates a session, if it so desires. 160 To do so, it returns an extra response header to the client, Set- 161 Cookie2. (The details follow later.) 163 A user agent returns a Cookie request header (see below) to the origin 164 server if it chooses to continue a session. The origin server MAY 165 ignore it or use it to determine the current state of the session. It 166 MAY send back to the client a Set-Cookie2 response header with the same 167 or different information, or it MAY send no Set-Cookie2 header at all. 168 The origin server effectively ends a session by sending the client a 169 Set-Cookie2 header with Max-Age=0. 171 Servers MAY return Set-Cookie2 response headers with any response. User 172 agents SHOULD send Cookie request headers, subject to other rules 173 detailed below, with every request. 175 An origin server MAY include multiple Set-Cookie2 headers in a response. 176 Note that an intervening gateway could fold multiple such headers into a 177 single header. 179 4.2.2 Set-Cookie2 Syntax The syntax for the Set-Cookie2 response 180 header is 182 set-cookie = "Set-Cookie2:" cookies 183 cookies = 1#cookie 184 cookie = NAME "=" VALUE *(";" set-cookie-av) 185 NAME = attr 186 VALUE = value 187 set-cookie-av = "Comment" "=" value 188 | "CommentURL" "=" <"> http_URL <"> 189 | "Discard" 190 | "Domain" "=" value 191 | "Max-Age" "=" value 192 | "Path" "=" value 193 | "Port" [ "=" <"> portlist <"> ] 194 | "Secure" 195 | "Version" "=" 1*DIGIT 196 portlist = 1#portnum 197 portnum = 1*DIGIT 199 Informally, the Set-Cookie2 response header comprises the token Set- 200 Cookie2:, followed by a comma-separated list of one or more cookies. 202 Each cookie begins with a NAME=VALUE pair, followed by zero or more 203 semi-colon-separated attribute-value pairs. The syntax for attribute- 204 value pairs was shown earlier. The specific attributes and the 205 semantics of their values follows. The NAME=VALUE attribute-value pair 206 MUST come first in each cookie. The others, if present, can occur in 207 any order. If an attribute appears more than once in a cookie, only the 208 value associated with the first appearance of the attribute SHALL be 209 used; subsequent values after the first MUST be ignored. 211 The NAME of a cookie MAY be the same as one of the attributes in this 212 specification. However, because the cookie's NAME must come first in a 213 Set-Cookie2 response header, the NAME and its VALUE cannot be confused 214 with an attribute-value pair. 216 NAME=VALUE 217 REQUIRED. The name of the state information (``cookie'') is NAME, 218 and its value is VALUE. NAMEs that begin with $ are reserved and 219 MUST NOT be used by applications. 221 The VALUE is opaque to the user agent and may be anything the 222 origin server chooses to send, possibly in a server-selected 223 printable ASCII encoding. ``Opaque'' implies that the content is 224 of interest and relevance only to the origin server. The content 225 may, in fact, be readable by anyone that examines the Set-Cookie2 226 header. 228 Comment=value 229 OPTIONAL. Because cookies can be used to derive or store private 230 information about a user, the value of the Comment attribute allows 231 an origin server to document how it intends to use the cookie. The 232 user can inspect the information to decide whether to initiate or 233 continue a session with this cookie. 235 CommentURL="http_URL" 236 OPTIONAL. Because cookies can be used to derive or store private 237 information about a user, the CommentURL attribute allows an origin 238 server to document how it intends to use the cookie. The user can 239 inspect the information identified by the URL to decide whether to 240 initiate or continue a session with this cookie. 242 Discard 243 OPTIONAL. The Discard attribute instructs the user agent to 244 discard the cookie unconditionally when the user agent terminates. 246 Domain=value 247 OPTIONAL. The value of the Domain attribute specifies the domain 248 for which the cookie is valid. If an explicitly specified value 249 does not start with a dot, the user agent supplies a leading dot. 251 Max-Age=value 252 OPTIONAL. The value of the Max-Age attribute is delta-seconds, the 253 lifetime of the cookie in seconds, a decimal non-negative integer. 254 To handle cached cookies correctly, a client SHOULD calculate the 255 age of the cookie according to the age calculation rules in the 256 HTTP/1.1 specification [RFC2068]. When the age is greater than 257 delta-seconds seconds, the client SHOULD discard the cookie. A 258 value of zero means the cookie SHOULD be discarded immediately. 260 Path=value 261 OPTIONAL. The value of the Path attribute specifies the subset of 262 URLs on the origin server to which this cookie applies. 264 Port[="portlist"] 265 OPTIONAL. The Port attribute restricts the port to which a cookie 266 may be returned in a Cookie request header. Note that the syntax 267 REQUIREs quotes around the OPTIONAL portlist even if there is only 268 one portnum in portlist. 270 Secure 271 OPTIONAL. The Secure attribute (with no value) directs the user 272 agent to use only (unspecified) secure means to contact the origin 273 server whenever it sends back this cookie, to protect the 274 confidentially and authenticity of the information in the cookie. 276 The user agent (possibly with user interaction) MAY determine what 277 level of security it considers appropriate for ``secure'' cookies. 278 The Secure attribute should be considered security advice from the 279 server to the user agent, indicating that it is in the session's 280 interest to protect the cookie contents. When it sends a 281 ``secure'' cookie back to a server, the user agent SHOULD use no 282 less than the same level of security as was used when it received 283 the cookie from the server. 285 Version=value 286 REQUIRED. The value of the Version attribute, a decimal integer, 287 identifies the version of the state management specification to 288 which the cookie conforms. For this specification, Version=1 289 applies. 291 4.2.3 Controlling Caching An origin server must be cognizant of the 292 effect of possible caching of both the returned resource and the Set- 293 Cookie2 header. Caching ``public'' documents is desirable. For 294 example, if the origin server wants to use a public document such as a 295 ``front door'' page as a sentinel to indicate the beginning of a session 296 for which a Set-Cookie2 response header must be generated, the page 297 SHOULD be stored in caches ``pre-expired'' so that the origin server 298 will see further requests. ``Private documents,'' for example those 299 that contain information strictly private to a session, SHOULD NOT be 300 cached in shared caches. 302 If the cookie is intended for use by a single user, the Set-Cookie2 303 header SHOULD NOT be cached. A Set-Cookie2 header that is intended to 304 be shared by multiple users MAY be cached. 306 The origin server SHOULD send the following additional HTTP/1.1 response 307 headers, depending on circumstances: 309 o To suppress caching of the Set-Cookie2 header: 311 Cache-control: no-cache="set-cookie2" 313 and one of the following: 315 o To suppress caching of a private document in shared caches: 317 Cache-control: private 319 o To allow caching of a document and require that it be validated 320 before returning it to the client: 322 Cache-Control: must-revalidate, max-age=0 324 o To allow caching of a document, but to require that proxy caches 325 (not user agent caches) validate it before returning it to the 326 client: 328 Cache-Control: proxy-revalidate, max-age=0 330 o To allow caching of a document and request that it be validated 331 before returning it to the client (by ``pre-expiring'' it): 333 Cache-control: max-age=0 335 Not all caches will revalidate the document in every case. 337 TTP/1.1 servers MUST send Expires: old-date (where old-date is a date 338 long in the past) on responses containing Set-Cookie2 response headers 339 unless they know for certain (by out of band means) that there are no 340 TTP/1.0 proxies in the response chain. HTTP/1.1 servers MAY send other 341 Cache-Control directives that permit caching by HTTP/1.1 proxies in 342 addition to the Expires: old-date directive; the Cache-Control directive 343 will override the Expires: old-date for HTTP/1.1 proxies. 345 4.3 User Agent Role 347 4.3.1 Interpreting Set-Cookie2 The user agent keeps separate track of 348 state information that arrives via Set-Cookie2 response headers from 349 each origin server (as distinguished by name or IP address and port). 350 The user agent MUST ignore attribute-value pairs whose attribute it does 351 not recognize. The user agent applies these defaults for optional 352 attributes that are missing: 354 Discard The default behavior is dictated by the presence or absence of a 355 Max-Age attribute. 357 Domain Defaults to the effective request-host. (Note that because 358 there is no dot at the beginning of effective request-host, the 359 default Domain can only domain-match itself.) 361 Max-Age The default behavior is to discard the cookie when the user 362 agent exits. 364 Path Defaults to the path of the request URL that generated the Set- 365 Cookie2 response, up to and including the right-most /. 367 Port The default behavior is that a cookie MAY be returned to any 368 request-port. 370 Secure If absent, the user agent MAY send the cookie over an insecure 371 channel. 373 4.3.2 Rejecting Cookies To prevent possible security or privacy 374 violations, a user agent rejects a cookie according to rules below. The 375 goal of the rules is to try to limit the set of servers for which a 376 cookie is valid, based on the values of the Path, Domain, and Port 377 attributes and the request-URI, request-host and request-port. 379 A user agent rejects (SHALL NOT store its information) if any of the 380 following is true of the attributes explicitly present in the Set- 381 Cookie2 response header: 383 o The value for the Path attribute is not a prefix of the request- 384 URI. 386 o The value for the Domain attribute contains no embedded dots, and 387 the value is not .local. 389 o The effective host name that derives from the request-host does not 390 domain-match the Domain attribute. 392 o The request-host is a HDN (not IP address) and has the form HD, 393 where D is the value of the Domain attribute, and H is a string 394 that contains one or more dots. 396 o The Port attribute has a "port-list", and the request-port was not 397 in the list. 399 Examples: 401 o A Set-Cookie2 from request-host y.x.foo.com for Domain=.foo.com 402 would be rejected, because H is y.x and contains a dot. 404 o A Set-Cookie2 from request-host x.foo.com for Domain=.foo.com would 405 be accepted. 407 o A Set-Cookie2 with Domain=.com or Domain=.com., will always be 408 rejected, because there is no embedded dot. 410 o A Set-Cookie2 with Domain=ajax.com will be accepted, and the value 411 for Domain will be taken to be .ajax.com, because a dot gets 412 prepended to the value. 414 o A Set-Cookie2 with Port="80,8000" will be accepted if the request 415 was made to port 80 or 8000 and will be rejected otherwise. 417 o A Set-Cookie2 from request-host example for Domain=.local will be 418 accepted, because the effective host name for the request-host is 419 example.local, and example.local domain-matches .local. 421 4.3.3 Cookie Management If a user agent receives a Set-Cookie2 422 response header whose NAME is the same as a pre-existing cookie, and 423 whose Domain and Path attribute values exactly (string) match those of a 424 pre-existing cookie, the new cookie supersedes the old. However, if the 425 Set-Cookie2 has a value for Max-Age of zero, the (old and new) cookie is 426 discarded. Otherwise a cookie persists (resources permitting) until 427 whichever happens first, then gets discarded: its Max-Age lifetime is 428 exceeded; or, if the Discard attribute is set, the user agent terminates 429 the session. 431 Because user agents have finite space in which to store cookies, they 432 MAY also discard older cookies to make space for newer ones, using, for 433 example, a least-recently-used algorithm, along with constraints on the 434 maximum number of cookies that each origin server may set. 436 If a Set-Cookie2 response header includes a Comment attribute, the user 437 agent SHOULD store that information in a human-readable form with the 438 cookie and SHOULD display the comment text as part of a cookie 439 inspection user interface. 441 If a Set-Cookie2 response header includes a CommentURL attribute, the 442 user agent SHOULD store that information in a human-readable form with 443 the cookie, or, preferably, SHOULD allow the user to follow the http_URL 444 link as part of a cookie inspection user interface. 446 The cookie inspection user interface MAY include a facility whereby a 447 user can decide, at the time the user agent receives the Set-Cookie2 448 response header, whether or not to accept the cookie. A potentially 449 confusing situation could arise if the following sequence occurs: 451 o the user agent receives a cookie that contains a CommentURL 452 attribute; 454 o the user agent's cookie inspection interface is configured so that 455 it presents a dialog to the user before the user agent accepts the 456 cookie; 458 o the dialog allows the user to follow the CommentURL link when the 459 user agent receives the cookie; and, 461 o when the user follows the CommentURL link, the origin server (or 462 another server, via other links in the returned content) returns 463 another cookie. 465 The user agent SHOULD NOT send any cookies in this context. The user 466 agent MAY discard any cookie it receives in this context that the user 467 has not, through some user agent mechanism, deemed acceptable. 469 User agents SHOULD allow the user to control cookie destruction, but 470 they MUST NOT extend the cookie's lifetime beyond that controlled by the 471 Discard and Max-Age attributes. An infrequently-used cookie may 472 function as a ``preferences file'' for network applications, and a user 473 may wish to keep it even if it is the least-recently-used cookie. One 474 possible implementation would be an interface that allows the permanent 475 storage of a cookie through a checkbox (or, conversely, its immediate 476 destruction). 478 Privacy considerations dictate that the user have considerable control 479 over cookie management. The PRIVACY section contains more information. 481 4.3.4 Sending Cookies to the Origin Server When it sends a request to 482 an origin server, the user agent sends a Cookie request header to the 483 origin server if it has cookies that are applicable to the request, 484 based on 486 o the request-host and request-port; 488 o the request-URI; 490 o the cookie's age. 492 The syntax for the header is: 494 cookie = "Cookie:" cookie-version 1*((";" | ",") cookie-value) 495 cookie-value = NAME "=" VALUE [";" path] [";" domain] [";" port] 496 cookie-version = "$Version" "=" value 497 NAME = attr 498 VALUE = value 499 path = "$Path" "=" value 500 domain = "$Domain" "=" value 501 port = "$Port" [ "=" <"> value <"> ] 503 The value of the cookie-version attribute MUST be the value from the 504 Version attribute of the corresponding Set-Cookie2 response header. 506 Otherwise the value for cookie-version is 0. The value for the path 507 attribute MUST be the value from the Path attribute, if one was present, 508 of the corresponding Set-Cookie2 response header. Otherwise the 509 attribute SHOULD be omitted from the Cookie request header. The value 510 for the domain attribute MUST be the value from the Domain attribute, if 511 one was present, of the corresponding Set-Cookie2 response header. 512 Otherwise the attribute SHOULD be omitted from the Cookie request 513 header. 515 The port attribute of the Cookie request header MUST mirror the Port 516 attribute, if one was present, in the corresponding Set-Cookie2 response 517 header. That is, the port attribute MUST be present if the Port 518 attribute was present in the Set-Cookie2 header, and it MUST have the 519 same value, if any. Otherwise, if the Port attribute was absent from 520 the Set-Cookie2 header, the attribute likewise MUST be omitted from the 521 Cookie request header. 523 Note that there is neither a Comment nor a CommentURL attribute in the 524 Cookie request header corresponding to the ones in the Set-Cookie2 525 response header. The user agent does not return the comment information 526 to the origin server. 528 The user agent applies the following rules to choose applicable cookie- 529 values to send in Cookie request headers from among all the cookies it 530 has received. 532 Domain Selection 533 The origin server's effective host name MUST domain-match the 534 Domain attribute of the cookie. 536 Port Selection 537 There are three possible behaviors, depending on the Port attribute 538 in the Set-Cookie2 response header: 540 1. By default (no Port attribute), the cookie MAY be sent to any 541 port. 543 2. If the attribute is present but has no value (e.g., Port), 544 the cookie MUST only be sent to the request-port it was 545 received from. 547 3. If the attribute has a port-list, the cookie MUST only be 548 returned if the new request-port is one of those listed in 549 port-list. 551 Path Selection 552 The Path attribute of the cookie MUST match a prefix of the 553 request-URI. 555 Max-Age Selection 556 Cookies that have expired should have been discarded and thus are 557 not forwarded to an origin server. 559 If multiple cookies satisfy the criteria above, they are ordered in the 560 Cookie header such that those with more specific Path attributes precede 561 those with less specific. Ordering with respect to other attributes 562 (e.g., Domain) is unspecified. 564 Note: For backward compatibility, the separator in the Cookie header is 565 semi-colon (;) everywhere. A server SHOULD also accept comma (,) as the 566 separator between cookie-values for future compatibility. 568 4.3.5 Sending Cookies in Unverifiable Transactions Users MUST have 569 control over sessions in order to ensure privacy. (See PRIVACY section 570 below.) To simplify implementation and to prevent an additional layer 571 of complexity where adequate safeguards exist, however, this document 572 distinguishes between transactions that are verifiable and those that 573 are unverifiable. A transaction is verifiable if the user, or a user- 574 designated agent, has the option to review the request-URI prior to its 575 use in the transaction. A transaction is unverifiable if the user does 576 not have that option. Unverifiable transactions typically arise when a 577 user agent automatically requests inlined or embedded entities or when 578 it resolves redirection (3xx) responses from an origin server. 579 Typically the origin transaction, the transaction that the user 580 initiates, is verifiable, and that transaction may directly or 581 indirectly induce the user agent to make unverifiable transactions. 583 An unverifiable transaction is to a third-party host if its request-host 584 U does not domain-match the reach R of the request-host O in the origin 585 transaction. 587 When it makes an unverifiable transaction, a user agent MUST disable all 588 cookie processing (i.e., MUST NOT send cookies, and MUST NOT accept any 589 received cookies) if the transaction is to a third-party host. 591 This restriction prevents a malicious service author from using 592 unverifiable transactions to induce a user agent to start or continue a 593 session with a server in a different domain. The starting or 594 continuation of such sessions could be contrary to the privacy 595 expectations of the user, and could also be a security problem. 597 User agents MAY offer configurable options that allow the user agent, or 598 any autonomous programs that the user agent executes, to ignore the 599 above rule, so long as these override options default to ``off.'' 601 (N.B. Mechanisms may be proposed that will automate overriding the 602 third-party restrictions under controlled conditions.) 604 Many current user agents already provide a review option that would 605 render many links verifiable. For instance, some user agents display 606 the URL that would be referenced for a particular link when the mouse 607 pointer is placed over that link. The user can therefore determine 608 whether to visit that site before causing the browser to do so. (Though 609 not implemented on current user agents, a similar technique could be 610 used for a button used to submit a form -- the user agent could display 611 the action to be taken if the user were to select that button.) 612 owever, even this would not make all links verifiable; for example, 613 links to automatically loaded images would not normally be subject to 614 ``mouse pointer'' verification. 616 Many user agents also provide the option for a user to view the HTML 617 source of a document, or to save the source to an external file where it 618 can be viewed by another application. While such an option does provide 619 a crude review mechanism, some users might not consider it acceptable 620 for this purpose. 622 4.4 How an Origin Server Interprets the Cookie Header 624 A user agent returns much of the information in the Set-Cookie2 header 625 to the origin server when the Path attribute matches that of a new 626 request. When it receives a Cookie header, the origin server SHOULD 627 treat cookies with NAMEs whose prefix is $ specially, as an attribute 628 for the cookie. 630 4.5 Caching Proxy Role 632 One reason for separating state information from both a URL and document 633 content is to facilitate the scaling that caching permits. To support 634 cookies, a caching proxy MUST obey these rules already in the HTTP 635 specification: 637 o Honor requests from the cache, if possible, based on cache validity 638 rules. 640 o Pass along a Cookie request header in any request that the proxy 641 must make of another server. 643 o Return the response to the client. Include any Set-Cookie2 644 response header. 646 o Cache the received response subject to the control of the usual 647 headers, such as Expires, 649 Cache-control: no-cache 651 and 653 Cache-control: private 655 o Cache the Set-Cookie2 subject to the control of the usual header, 657 Cache-control: no-cache="set-cookie2" 658 (The Set-Cookie2 header should usually not be cached.) 660 Proxies MUST not introduce Set-Cookie2 (Cookie) headers of their own in 661 proxy responses (requests). 663 5. EXAMPLES 665 5.1 Example 1 667 Most detail of request and response headers has been omitted. Assume 668 the user agent has no stored cookies. 670 1. User Agent -> Server 672 POST /acme/login HTTP/1.1 673 [form data] 675 User identifies self via a form. 677 2. Server -> User Agent 679 HTTP/1.1 200 OK 680 Set-Cookie2: Customer="WILE_E_COYOTE"; Version="1"; Path="/acme" 682 Cookie reflects user's identity. 684 3. User Agent -> Server 686 POST /acme/pickitem HTTP/1.1 687 Cookie: $Version="1"; Customer="WILE_E_COYOTE"; $Path="/acme" 688 [form data] 690 User selects an item for ``shopping basket.'' 692 4. Server -> User Agent 694 HTTP/1.1 200 OK 695 Set-Cookie2: Part_Number="Rocket_Launcher_0001"; Version="1"; 696 Path="/acme" 698 Shopping basket contains an item. 700 5. User Agent -> Server 702 POST /acme/shipping HTTP/1.1 703 Cookie: $Version="1"; 704 Customer="WILE_E_COYOTE"; $Path="/acme"; 705 Part_Number="Rocket_Launcher_0001"; $Path="/acme" 706 [form data] 707 User selects shipping method from form. 709 6. Server -> User Agent 711 HTTP/1.1 200 OK 712 Set-Cookie2: Shipping="FedEx"; Version="1"; Path="/acme" 714 New cookie reflects shipping method. 716 7. User Agent -> Server 718 POST /acme/process HTTP/1.1 719 Cookie: $Version="1"; 720 Customer="WILE_E_COYOTE"; $Path="/acme"; 721 Part_Number="Rocket_Launcher_0001"; $Path="/acme"; 722 Shipping="FedEx"; $Path="/acme" 723 [form data] 725 User chooses to process order. 727 8. Server -> User Agent 729 HTTP/1.1 200 OK 731 Transaction is complete. 733 The user agent makes a series of requests on the origin server, after 734 each of which it receives a new cookie. All the cookies have the same 735 Path attribute and (default) domain. Because the request URLs all have 736 /acme as a prefix, and that matches the Path attribute, each request 737 contains all the cookies received so far. 739 5.2 Example 2 741 This example illustrates the effect of the Path attribute. All detail 742 of request and response headers has been omitted. Assume the user agent 743 has no stored cookies. 745 Imagine the user agent has received, in response to earlier requests, 746 the response headers 748 Set-Cookie2: Part_Number="Rocket_Launcher_0001"; Version="1"; 749 Path="/acme" 751 and 753 Set-Cookie2: Part_Number="Riding_Rocket_0023"; Version="1"; 754 Path="/acme/ammo" 756 A subsequent request by the user agent to the (same) server for URLs of 757 the form /acme/ammo/... would include the following request header: 759 Cookie: $Version="1"; 760 Part_Number="Riding_Rocket_0023"; $Path="/acme/ammo"; 761 Part_Number="Rocket_Launcher_0001"; $Path="/acme" 763 Note that the NAME=VALUE pair for the cookie with the more specific Path 764 attribute, /acme/ammo, comes before the one with the less specific Path 765 attribute, /acme. Further note that the same cookie name appears more 766 than once. 768 A subsequent request by the user agent to the (same) server for a URL of 769 the form /acme/parts/ would include the following request header: 771 Cookie: $Version="1"; Part_Number="Rocket_Launcher_0001"; $Path="/acme" 773 ere, the second cookie's Path attribute /acme/ammo is not a prefix of 774 the request URL, /acme/parts/, so the cookie does not get forwarded to 775 the server. 777 6. IMPLEMENTATION CONSIDERATIONS 779 ere we speculate on likely or desirable details for an origin server 780 that implements state management. 782 6.1 Set-Cookie2 Content 784 An origin server's content should probably be divided into disjoint 785 application areas, some of which require the use of state information. 786 The application areas can be distinguished by their request URLs. The 787 Set-Cookie2 header can incorporate information about the application 788 areas by setting the Path attribute for each one. 790 The session information can obviously be clear or encoded text that 791 describes state. However, if it grows too large, it can become 792 unwieldy. Therefore, an implementor might choose for the session 793 information to be a key to a server-side resource. Of course, using a 794 database creates some problems that this state management specification 795 was meant to avoid, namely: 797 1. keeping real state on the server side; 799 2. how and when to garbage-collect the database entry, in case the 800 user agent terminates the session by, for example, exiting. 802 6.2 Stateless Pages 804 Caching benefits the scalability of WWW. Therefore it is important to 805 reduce the number of documents that have state embedded in them 806 inherently. For example, if a shopping-basket-style application always 807 displays a user's current basket contents on each page, those pages 808 cannot be cached, because each user's basket's contents would be 809 different. On the other hand, if each page contains just a link that 810 allows the user to ``Look at My Shopping Basket,'' the page can be 811 cached. 813 6.3 Implementation Limits 815 Practical user agent implementations have limits on the number and size 816 of cookies that they can store. In general, user agents' cookie support 817 should have no fixed limits. They should strive to store as many 818 frequently-used cookies as possible. Furthermore, general-use user 819 agents SHOULD provide each of the following minimum capabilities 820 individually, although not necessarily simultaneously: 822 o at least 300 cookies 824 o at least 4096 bytes per cookie (as measured by the characters that 825 comprise the cookie non-terminal in the syntax description of the 826 Set-Cookie2 header, and as received in the Set-Cookie2 header) 828 o at least 20 cookies per unique host or domain name 830 User agents created for specific purposes or for limited-capacity 831 devices SHOULD provide at least 20 cookies of 4096 bytes, to ensure that 832 the user can interact with a session-based origin server. 834 The information in a Set-Cookie2 response header MUST be retained in its 835 entirety. If for some reason there is inadequate space to store the 836 cookie, it MUST be discarded, not truncated. 838 Applications should use as few and as small cookies as possible, and 839 they should cope gracefully with the loss of a cookie. 841 6.3.1 Denial of Service Attacks User agents MAY choose to set an upper 842 bound on the number of cookies to be stored from a given host or domain 843 name or on the size of the cookie information. Otherwise a malicious 844 server could attempt to flood a user agent with many cookies, or large 845 cookies, on successive responses, which would force out cookies the user 846 agent had received from other servers. However, the minima specified 847 above SHOULD still be supported. 849 7. PRIVACY 851 Informed consent should guide the design of systems that use cookies. A 852 user should be able to find out how a web site plans to use information 853 in a cookie and should be able to choose whether or not those policies 854 are acceptable. Both the user agent and the origin server must assist 855 informed consent. 857 7.1 User Agent Control 859 An origin server could create a Set-Cookie2 header to track the path of 860 a user through the server. Users may object to this behavior as an 861 intrusive accumulation of information, even if their identity is not 862 evident. (Identity might become evident, for example, if a user 863 subsequently fills out a form that contains identifying information.) 864 This state management specification therefore requires that a user agent 865 give the user control over such a possible intrusion, although the 866 interface through which the user is given this control is left 867 unspecified. However, the control mechanisms provided SHALL at least 868 allow the user 870 o to completely disable the sending and saving of cookies. 872 o to determine whether a stateful session is in progress. 874 o to control the saving of a cookie on the basis of the cookie's 875 Domain attribute. 877 Such control could be provided, for example, by mechanisms 879 o to notify the user when the user agent is about to send a cookie to 880 the origin server, to offer the option not to begin a session. 882 o to display a visual indication that a stateful session is in 883 progress. 885 o to let the user decide which cookies, if any, should be saved when 886 the user concludes a window or user agent session. 888 o to let the user examine the contents of a cookie at any time. 890 A user agent usually begins execution with no remembered state 891 information. It SHOULD be possible to configure a user agent never to 892 send Cookie headers, in which case it can never sustain state with an 893 origin server. (The user agent would then behave like one that is 894 unaware of how to handle Set-Cookie2 response headers.) 896 When the user agent terminates execution, it SHOULD let the user discard 897 all state information. Alternatively, the user agent MAY ask the user 898 whether state information should be retained; the default should be 899 ``no.'' If the user chooses to retain state information, it would be 900 restored the next time the user agent runs. 902 NOTE: User agents should probably be cautious about using files to store 903 cookies long-term. If a user runs more than one instance of the user 904 agent, the cookies could be commingled or otherwise corrupted. 906 7.2 Origin Server Role 908 A origin server SHOULD promote informed consent by adding CommentURL or 909 Comment information to the cookies it sends. CommentURL is preferred 910 because of the opportunity to provide richer information in a 911 multiplicity of languages. 913 7.3 Clear Text 915 The information in the Set-Cookie2 and Cookie headers is unprotected. 916 As a consequence: 918 1. Any sensitive information that is conveyed in them is exposed to 919 intruders. 921 2. A malicious intermediary could alter the headers as they travel in 922 either direction, with unpredictable results. 924 These facts imply that information of a personal and/or financial nature 925 should only be sent over a secure channel. For less sensitive 926 information, or when the content of the header is a database key, an 927 origin server should be vigilant to prevent a bad Cookie value from 928 causing failures. 930 A user agent in a shared user environment poses a further risk. Using a 931 cookie inspection interface, User B could examine the contents of 932 cookies that were saved when User A used the machine. 934 8. SECURITY CONSIDERATIONS 936 8.1 Protocol Design 938 The restrictions on the value of the Domain attribute, and the rules 939 concerning unverifiable transactions, are meant to reduce the ways that 940 cookies can ``leak'' to the ``wrong'' site. The intent is to restrict 941 cookies to one host, or a closely related set of hosts. Therefore a 942 request-host is limited as to what values it can set for Domain. We 943 consider it acceptable for hosts host1.foo.com and host2.foo.com to 944 share cookies, but not a.com and b.com. 946 Similarly, a server can set a Path only for cookies that are related to 947 the request-URI. 949 8.2 Cookie Spoofing 951 Proper application design can avoid spoofing attacks from related 952 domains. Consider: 954 1. User agent makes request to victim.cracker.edu, gets back cookie 955 session_id="1234" and sets the default domain victim.cracker.edu. 957 2. User agent makes request to spoof.cracker.edu, gets back cookie 958 session-id="1111", with Domain=".cracker.edu". 960 3. User agent makes request to victim.cracker.edu again, and passes 962 Cookie: $Version="1"; session_id="1234", 963 $Version="1"; session_id="1111"; $Domain=".cracker.edu" 965 The server at victim.cracker.edu should detect that the second 966 cookie was not one it originated by noticing that the Domain 967 attribute is not for itself and ignore it. 969 8.3 Unexpected Cookie Sharing 971 A user agent SHOULD make every attempt to prevent the sharing of session 972 information between hosts that are in different domains. Embedded or 973 inlined objects may cause particularly severe privacy problems if they 974 can be used to share cookies between disparate hosts. For example, a 975 malicious server could embed cookie information for host a.com in a URI 976 for a CGI on host b.com. User agent implementors are strongly 977 encouraged to prevent this sort of exchange whenever possible. 979 8.4 Cookies For Account Information 981 While it is common practice to use them this way, cookies are not 982 designed or intended to be used to hold authentication information, such 983 as account names and passwords. Unless such cookies are exchanged over 984 an encrypted path, the account information they contain is highly 985 vulnerable to perusal and theft. 987 9. OTHER, SIMILAR, PROPOSALS 989 Apart from RFC 2109, three other proposals have been made to accomplish 990 similar goals. This specification began as an amalgam of Kristol's 991 State-Info proposal [DMK95] and Netscape's Cookie proposal [Netscape]. 993 Brian Behlendorf proposed a Session-ID header that would be user-agent- 994 initiated and could be used by an origin server to track 995 ``clicktrails.'' It would not carry any origin-server-defined state, 996 however. Phillip Hallam-Baker has proposed another client-defined 997 session ID mechanism for similar purposes. 999 While both session IDs and cookies can provide a way to sustain stateful 1000 sessions, their intended purpose is different, and, consequently, the 1001 privacy requirements for them are different. A user initiates session 1002 IDs to allow servers to track progress through them, or to distinguish 1003 multiple users on a shared machine. Cookies are server-initiated, so 1004 the cookie mechanism described here gives users control over something 1005 that would otherwise take place without the users' awareness. 1006 Furthermore, cookies convey rich, server-selected information, whereas 1007 session IDs comprise user-selected, simple information. 1009 10. HISTORICAL 1011 10.1 Compatibility with Existing Implementations 1013 Existing cookie implementations, based on the Netscape specification, 1014 use the Set-Cookie (not Set-Cookie2) header. User agents that receive 1015 in the same response both a Set-Cookie and Set-Cookie2 response header 1016 for the same cookie MUST discard the Set-Cookie information and use only 1017 the Set-Cookie2 information. Furthermore, a user agent MUST assume, if 1018 it received a Set-Cookie2 response header, that the sending server 1019 complies with this document and will understand Cookie request headers 1020 that also follow this specification. 1022 New cookies MUST replace both equivalent old- and new-style cookies. 1023 That is, if a user agent that follows both this specification and 1024 Netscape's original specification receives a Set-Cookie2 response 1025 header, and the NAME and the Domain and Path attributes match (per the 1026 Cookie Management section) a Netscape-style cookie, the Netscape-style 1027 cookie MUST be discarded, and the user agent MUST retain only the cookie 1028 adhering to this specification. 1030 Older user agents that do not understand this specification, but that do 1031 understand Netscape's original specification, will not recognize the 1032 Set-Cookie2 response header and will receive and send cookies according 1033 to the older specification. 1035 A user agent that supports both this specification and Netscape-style 1036 cookies SHOULD send a Cookie request header that follows the older 1037 Netscape specification if it received the cookie in a Set-Cookie 1038 response header and not in a Set-Cookie2 response header. However, it 1039 SHOULD send the following request header as well: 1041 Cookie2: $Version="1" 1043 The Cookie2 header advises the server that the user agent understands 1044 new-style cookies. If the server understands new-style cookies, as 1045 well, it SHOULD continue the stateful session by sending a Set-Cookie2 1046 response header, rather than Set-Cookie. A server that does not 1047 understand new-style cookies will simply ignore the Cookie2 request 1048 header. 1050 10.2 Caching and HTTP/1.0 1052 Some caches, such as those conforming to HTTP/1.0, will inevitably cache 1053 the Set-Cookie2 and Set-Cookie headers, because there was no mechanism 1054 to suppress caching of headers prior to HTTP/1.1. This caching can lead 1055 to security problems. Documents transmitted by an origin server along 1056 with Set-Cookie2 and Set-Cookie headers usually either will be 1057 uncachable, or will be ``pre-expired.'' As long as caches obey 1058 instructions not to cache documents (following Expires: or Pragma: no-cache (HTTP/1.0), or Cache-control: no-cache 1060 (HTTP/1.1)) uncachable documents present no problem. However, pre- 1061 expired documents may be stored in caches. They require validation (a 1062 conditional GET) on each new request, but some cache operators loosen 1063 the rules for their caches, and sometimes serve expired documents 1064 without first validating them. This combination of factors can lead to 1065 cookies meant for one user later being sent to another user. The Set- 1066 Cookie2 and Set-Cookie headers are stored in the cache, and, although 1067 the document is stale (expired), the cache returns the document in 1068 response to later requests, including cached headers. 1070 11. ACKNOWLEDGEMENTS 1072 This document really represents the collective efforts of the HTTP 1073 Working Group of the IETF and, particularly, the following people, in 1074 addition to the authors: Roy Fielding, Yaron Goland, Marc Hedlund, Ted 1075 ardie, Koen Holtman, Shel Kaphan, Rohit Khare, Foteos Macrides, David 1076 W. Morris. 1078 12. AUTHORS' ADDRESSES 1080 David M. Kristol 1081 Bell Laboratories, Lucent Technologies 1082 600 Mountain Ave. Room 2A-333 1083 Murray Hill, NJ 07974 1085 Phone: (908) 582-2250 1086 FAX: (908) 582-1239 1087 Email: dmk@bell-labs.com 1089 Lou Montulli 1090 Netscape Communications Corp. 1091 501 E. Middlefield Rd. 1092 Mountain View, CA 94043 1094 Phone: (415) 528-2600 1095 Email: montulli@netscape.com 1097 13. REFERENCES 1099 [DMK95]Kristol, D.M., ``Proposed HTTP State-Info Mechanism'', available 1100 at , 1101 September, 1995. 1103 [Netscape] ``Persistent Client State -- HTTP Cookies'', available at 1104 , undated. 1106 [RFC2068] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Berners-Lee, 1107 T., ``Hypertext Transfer Protocol -- HTTP/1.1'', RFC 2068, 1108 January, 1997 1110 [RFC2109] Kristol, D.M., Montulli, L., ``HTTP State Management 1111 Mechanism'', RFC 2109, February, 1997. 1113 [RFC2119] Bradner, S., ``Key words for use in RFCs to Indicate 1114 Requirement Levels'', RFC 2119, March 1997. 1116 Expires January 24, 1999