idnits 2.17.1 draft-abarth-cookie-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.ii or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** 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 a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 167: '...he origin server MAY ignore the Cookie...' RFC 2119 keyword, line 169: '... server MAY send the user agent a Se...' RFC 2119 keyword, line 170: '...formation, or it MAY send no Set-Cooki...' RFC 2119 keyword, line 173: '... Servers MAY return a Set-Cookie res...' RFC 2119 keyword, line 177: '...An origin server MAY include multiple ...' (37 more instances...) -- The draft header indicates that this document obsoletes RFC2109, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (December 30, 2009) is 5224 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: 'USASCII' is mentioned on line 139, but not defined == Unused Reference: 'RFC2616' is defined on line 979, but no explicit reference was found in the text == Unused Reference: 'RFC5246' is defined on line 986, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) Summary: 5 errors (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 httpstate A. Barth 3 Internet-Draft U.C. Berkeley 4 Obsoletes: 2109 (if approved) December 30, 2009 5 Intended status: Standards Track 6 Expires: July 3, 2010 8 HTTP State Management Mechanism 9 draft-abarth-cookie-07 11 Status of this Memo 13 This Internet-Draft is submitted to IETF in full conformance with the 14 provisions of BCP 78 and BCP 79. This document may contain material 15 from IETF Documents or IETF Contributions published or made publicly 16 available before November 10, 2008. The person(s) controlling the 17 copyright in some of this material may not have granted the IETF 18 Trust the right to allow modifications of such material outside the 19 IETF Standards Process. Without obtaining an adequate license from 20 the person(s) controlling the copyright in such materials, this 21 document may not be modified outside the IETF Standards Process, and 22 derivative works of it may not be created outside the IETF Standards 23 Process, except to format it for publication as an RFC or to 24 translate it into languages other than English. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF), its areas, and its working groups. Note that 28 other groups may also distribute working documents as Internet- 29 Drafts. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 The list of current Internet-Drafts can be accessed at 37 http://www.ietf.org/ietf/1id-abstracts.txt. 39 The list of Internet-Draft Shadow Directories can be accessed at 40 http://www.ietf.org/shadow.html. 42 This Internet-Draft will expire on July 3, 2010. 44 Copyright Notice 46 Copyright (c) 2009 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents in effect on the date of 51 publication of this document (http://trustee.ietf.org/license-info). 52 Please review these documents carefully, as they describe your rights 53 and restrictions with respect to this document. 55 Abstract 57 This document defines the HTTP Cookie and Set-Cookie headers. These 58 headers can be used by HTTP servers to store state on HTTP user 59 agents, letting the servers maintain a stateful session over the 60 mostly stateless HTTP protocol. The cookie protocol has many 61 historical infelicities and should be avoided for new applications of 62 HTTP. 64 NOTE: If you have suggestions for improving the draft, please send 65 email to http-state@ietf.org. Suggestions with test cases are 66 especially appreciated. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 71 1.1. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 5 72 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 73 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 74 3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 7 75 4. A Well-Behaved Profile . . . . . . . . . . . . . . . . . . . . 8 76 4.1. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . . 8 77 4.1.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . 8 78 4.1.2. Semantics (Non-Normative) . . . . . . . . . . . . . . 9 79 4.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . . 11 80 4.2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . 11 81 4.2.2. Semantics . . . . . . . . . . . . . . . . . . . . . . 11 82 5. The Cookie Protocol . . . . . . . . . . . . . . . . . . . . . 12 83 5.1. Algorithms . . . . . . . . . . . . . . . . . . . . . . . . 12 84 5.1.1. Dates . . . . . . . . . . . . . . . . . . . . . . . . 12 85 5.1.2. Domains . . . . . . . . . . . . . . . . . . . . . . . 14 86 5.1.3. Paths . . . . . . . . . . . . . . . . . . . . . . . . 14 87 5.2. The Set-Cookie Header . . . . . . . . . . . . . . . . . . 15 88 5.2.1. The Max-Age Attribute . . . . . . . . . . . . . . . . 16 89 5.2.2. The Expires Attribute . . . . . . . . . . . . . . . . 17 90 5.2.3. The Domain Attribute . . . . . . . . . . . . . . . . . 18 91 5.2.4. The Path Attribute . . . . . . . . . . . . . . . . . . 18 92 5.2.5. The Secure Attribute . . . . . . . . . . . . . . . . . 19 93 5.2.6. The HttpOnly Attribute . . . . . . . . . . . . . . . . 19 94 5.3. Storage Model . . . . . . . . . . . . . . . . . . . . . . 19 95 5.4. The Cookie Header . . . . . . . . . . . . . . . . . . . . 21 96 6. Implementation Limits . . . . . . . . . . . . . . . . . . . . 23 97 7. Security Considerations . . . . . . . . . . . . . . . . . . . 24 98 7.1. Clear Text . . . . . . . . . . . . . . . . . . . . . . . . 24 99 7.2. Weak Confidentiality . . . . . . . . . . . . . . . . . . . 24 100 7.3. Weak Integrity . . . . . . . . . . . . . . . . . . . . . . 24 101 8. Normative References . . . . . . . . . . . . . . . . . . . . . 26 102 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 27 103 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 28 105 1. Introduction 107 This document defines the HTTP Cookie and Set-Cookie header. Using 108 the Set-Cookie header, an HTTP server can store name/value pairs 109 (called cookies) at the user agent. When the user agent makes 110 subsequent requests to the server, the user agent will return the 111 name/value pairs in the Cookie header. 113 Although simple on its surface, the cookie protocol has a number of 114 complexities. For example, the server indicates a scope for each 115 cookie when sending them to the user agent. The scope indicates the 116 maximum amount of time the user agent should persist the cookie, to 117 which servers the user agent should return the cookie, and for which 118 protocols the cookie is applicable. 120 For historical reasons, the cookie protocol contains a number of 121 security and privacy infelicities. For example, a server can 122 indicate that a given cookie is intended for "secure" connections, 123 but the Secure attribute provides only confidentiality (not 124 integrity) from active network attackers. Similarly, cookies for a 125 given host are shared across all the ports on that host, even though 126 the usual "same-origin policy" used by web browsers isolates content 127 retrieved from different ports. 129 1.1. Syntax Notation 131 This specification uses the Augmented Backus-Naur Form (ABNF) 132 notation of [RFC5234]. 134 The following core rules are included by reference, as defined in 135 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 136 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 137 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 138 sequence of data), SP (space), HTAB (horizontal tab), VCHAR (any 139 visible [USASCII] character), and WSP (whitespace). 141 2. Terminology 143 The terms user agent, client, server, proxy, and origin server have 144 the same meaning as in the HTTP/1.0 specification. 146 The terms request-host and request-URI refer to the values the user 147 agent would send to the server as, respectively, the host (but not 148 port) and abs_path portions of the absoluteURI (http_URL) of the HTTP 149 request line. 151 3. Overview 153 We outline here a way for an origin server to send state information 154 to the user agent, and for the user agent to return the state 155 information to the origin server. 157 The origin server initiates a session, if it so desires, by including 158 a Set-Cookie header in an HTTP response. (Note that "session" here 159 does not refer to a persistent network connection but to a logical 160 session created from HTTP requests and responses. The presence or 161 absence of a persistent connection should have no effect on the use 162 of cookie-derived sessions). 164 The user agent returns a Cookie request header to the origin server 165 if it chooses to continue a session. The Cookie header contains a 166 number of cookies the user agent received in previous Set-Cookie 167 headers. The origin server MAY ignore the Cookie header or use the 168 header to determine the current state of the session. The origin 169 server MAY send the user agent a Set-Cookie response header with the 170 same or different information, or it MAY send no Set-Cookie header at 171 all. 173 Servers MAY return a Set-Cookie response headers with any response. 174 User agents should send Cookie request headers, subject to other 175 rules detailed below, with every request. 177 An origin server MAY include multiple Set-Cookie header fields in a 178 single response. Note that an intervening gateway MUST NOT fold 179 multiple Set-Cookie header fields into a single header field. 181 3.1. Examples 183 [TODO: Put some examples here. 185 4. A Well-Behaved Profile 187 This section describes the syntax and semantics of a well-behaved 188 profile of the protocol. Servers SHOULD use the profile described in 189 this section, both to maximize interoperability with existing user 190 agents and because a future version of the cookie protocol could 191 remove support for some of the most esoteric aspects of the protocol. 192 User agents, however, MUST implement the full protocol to ensure 193 interoperability with servers making use of the full protocol. 195 4.1. Set-Cookie 197 The Set-Cookie header is used to send cookies from the server to the 198 user agent. 200 4.1.1. Syntax 202 Informally, the Set-Cookie response header comprises the token Set- 203 Cookie:, followed by a cookie. Each cookie begins with a name-value- 204 pair, followed by zero or more semi-colon-separated attribute-value 205 pairs. Servers SHOULD NOT send Set-Cookie headers that fail to 206 conform to the following grammar: 208 set-cookie-header = "Set-Cookie:" OWS a-cookie OWS 209 a-cookie = cookie-pair *( ";" cookie-av) 210 cookie-pair = cookie-name "=" cookie-value 211 cookie-name = token 212 cookie-value = token 213 token = 215 cookie-av = expires-av / domain-av / path-av / 216 secure-av / httponly-av 217 expires-av = "Expires" "=" cookie-date 218 cookie-date = 219 domain-av = "Domain" "=" domain-value 220 domain-value = token 221 path-av = "Path" "=" path-value 222 path-value = 223 secure-av = "Secure" 224 httponly-av = "HttpOnly" 226 Servers SHOULD NOT include two attributes with the same name. 228 The cookie-value is opaque to the user agent and MAY be anything the 229 origin server chooses to send, possibly in a server-selected 230 printable ASCII encoding. "Opaque" implies that the content is of 231 interest and relevance only to the origin server. The content is, in 232 fact, be readable by anyone who examines the Set-Cookie header. 234 NOTE: The syntax above allows whitespace between the attribute and 235 the U+3D ("=") character. Servers wishing to interoperate with some 236 legacy user agents might wish to elide this whitespace. 238 4.1.2. Semantics (Non-Normative) 240 This section describes a simplified semantics of the Set-Cookie 241 header. These semantics are detailed enough to be useful for 242 understanding the most common uses of the cookie protocol. The full 243 semantics are described in Section 5. 245 When the user agent receives a Set-Cookie header, the user agent 246 stores the cookie in its cookie store.When the user agent 247 subsequently makes an HTTP request, the user agent consults its 248 cookie store and includes the applicable, non-expired cookies in the 249 Cookie header. 251 If the cookie store already contains a cookie with the same cookie- 252 name, domain-value, and path-value, the existing cookie is evicted 253 from the cookie store and replaced with the new value. Notice that 254 servers can delete cookies by setting their values to the empty 255 string or by including an Expires attribute with a value in the past. 257 By default, cookies are returned only to the origin server and expire 258 at a the end of the current session (as defined by the user agent). 259 The server can override the default handling of cookies by specifying 260 various cookie attributes. User agents ignore unrecognized cookie 261 attributes. 263 4.1.2.1. Expires 265 The Expires attribute represent the maximum lifetime of the cookie, 266 represented as the date and time at which the cookie expires. The 267 user agent is not required to persist the cookie until the specified 268 date has passed. In fact, user agents often evict cookies from the 269 cookie store due to memory pressure or privacy concerns. 271 4.1.2.2. Domain 273 The Domain attribute specifies the hosts for which the cookie is 274 applicable. For example, if the domain attribute contains the value 275 ".example.com", the use agent will include the cookie in the Cookie 276 header when making HTTPS requests to example.com, www.example.com, 277 and www.corp.example.com. (Note that the leading U+2E (".") is 278 meaningless and not required.) If the server omits the Domain 279 attribute, the user agent will return the cookie only to the origin 280 server 282 The user agent will reject cookies less the Domain attribute 283 specifies a scope for the cookie that would include the origin 284 server. For example, the user agent will accept a Domain attribute 285 of ".example.com" or of ".foo.example.com" from a response from 286 foo.example.com, but the user agent will not accept a Domain 287 attribute of ".bar.example.com" or ".baz.foo.example.com". 289 NOTE: For security reasons, some user agents are configured to reject 290 Domain attributes that do not correspond to a "registry controlled" 291 domain (or a subdomain of a registry controlled domain). For 292 example, some user agents will reject Domain attributes of ".com". 294 4.1.2.3. Path 296 The Path attribute limits the scope of the cookie to a set of paths. 297 When a cookie has a Path attribute, the user agent will include the 298 cookie in an HTTP request only if the path portion of the Request-URI 299 matches (or is a subdirectory of) the cookie's Path attribute, where 300 the U+2F ("/") character is interpreted as a directory separator. If 301 the server omits the Path attribute, the user agent will use the 302 directory of the Request-URI's path component as the default value. 304 Although seemingly useful for isolating cookies between different 305 paths within a given domain, the Path attribute cannot be relied upon 306 for security for two reasons: First, user agents do not prevent one 307 path from overwriting the cookies for another path. For example, a 308 response to a request for /foo/bar.html can include a Set-Cookie 309 header with a Path attribute of "/baz". Second, the "same-origin" 310 policy implemented by many user agents does not isolate different 311 paths within an origin. For example, /foo/bar.html can read cookies 312 with a Path attribute of "/baz" because they are within the "same 313 origin". 315 4.1.2.4. Secure 317 The Secure attribute limits the scope of the cookie to "secure" 318 channels (where "secure" is defined by the user agent). When a 319 cookie has the Secure attribute, the user agent will include the 320 cookie in an HTTP request only if the request is transmitted over a 321 secure channel (typically TLS [RFC5234]). 323 Although seemingly useful for protecting cookies from active network 324 attackers, the Secure attribute protects only the cookie's 325 confidentiality. An active network attacker can overwrite Secure 326 cookies from an insecure channel, disrupting the integrity of the 327 cookies. 329 4.1.2.5. HttpOnly 331 The HttpOnly attribute limits the scope of the cookie to HTTP 332 requests. In particular, the attribute instructs the user agent to 333 elide the cookie when providing access to its cookie store via "non- 334 HTTP" APIs (as defined by the user agent). 336 4.2. Cookie 338 4.2.1. Syntax 340 The user agent returns stored cookies to the origin server in the 341 Cookie header. If the server conforms to the requirements in this 342 section, the requirements in the next section will cause the user 343 agent to return a Cookie header that conforms to the following 344 grammar. 346 cookie-header = "Set-Cookie:" OWS cookie-pair *( ";" cookie-pair) OWS 347 cookie-pair = cookie-name "=" cookie-value 348 cookie-name = token 349 cookie-value = token 350 token = 352 4.2.2. Semantics 354 Each cookie-pair represents a cookie stored by the user agent. The 355 cookie-name and the cookie-value are returned verbatim from the 356 corresponding parts of the Set-Cookie header. 358 Notice that the cookie attributes are not returned. In particular, 359 the server cannot determine from the Cookie header alone when a 360 cookie will expire, for which domains the cookie is valid, for which 361 paths the cookie is valid, or whether the cookie is marked Secure or 362 HttpOnly. 364 The semantics of individual cookies in the Cookie header is not 365 defined by this document. Servers are expected to imbue these 366 cookies with server-specific semantics. 368 5. The Cookie Protocol 370 For historical reasons, the full cookie protocol contains a number of 371 exotic quirks. This section is intended to specify the cookie 372 protocol in enough precision to enable a user agent that implement 373 the protocol precisely as specified to interoperate with existing 374 servers. 376 Although some parts of the cookie protocol is specified 377 algorithmically, user agents are free to implement the cookie 378 protocol in any manner as long as their resultant behavior is "black- 379 box" indistinguishable from a user agent that implements the protocol 380 as described. 382 5.1. Algorithms 384 The cookie protocol uses a number of self-contained algorithms, which 385 are described in this section. 387 5.1.1. Dates 389 The user agent MUST use the following algorithm to *parse a cookie- 390 date*: 392 1. Using the grammar below, divide the cookie-date into date-tokens. 394 cookie-date = date-token *( 1*delimiter date-token ) 395 delimiter = %x09 / %x20 / %x21 / %x22 / %x23 / %x24 / 396 %x25 / %x26 / %x27 / %x28 / %x29 / %x2A / 397 %x2B / %x2C / %x2D / %x2E / %x2F / %x3B / 398 %x3C / %x3D / %x3E / %x3F / %x40 / %x5B / 399 %x5C / %x5D / %x5E / %x5F / %x60 / %x7B / 400 %x7C / %x7D / %x7E 401 date-token = day-of-month / month / year / time / mystery 402 day-of-month = 2DIGIT / DIGIT 403 month = "jan" [ mystery ] / "feb" [ mystery ] / 404 "mar" [ mystery ] / "apr" [ mystery ] / 405 "may" [ mystery ] / "jun" [ mystery ] / 406 "jul" [ mystery ] / "aug" [ mystery ] / 407 "sep" [ mystery ] / "oct" [ mystery ] / 408 "nov" [ mystery ] / "dec" [ mystery ] 409 year = 5DIGIT / 4DIGIT / 3DIGIT / 2DIGIT / DIGIT 410 time = 2DIGIT ":" 2DIGIT ":" 2DIGIT 411 mystery = 412 2. Process each date-token sequentially in the order the date-tokens 413 appear in the cookie-date: 415 1. If the found-day-of-month flag is not set and the date-token 416 matches the day-of-month production, set the found-day-of- 417 month flag and set the day-of-month-value to the number 418 denoted by the date-token. Skip the remaining sub-steps and 419 continue to the next date-token. 421 2. If the found-month flag is not set and the date-token matches 422 the month production, set the found-month flag and set the 423 month-value to the month denoted by the date-token. Skip the 424 remaining sub-steps and continue to the next date-token. 426 3. If the found-year flag is not set and the date-token matches 427 the year production, set the found-year flag and set the 428 year-value to the number denoted by the date-token. Skip the 429 remaining sub-steps and continue to the next date-token. 431 4. If the found-time flag is not set and the token matches the 432 time production, set the found-time flag and set the hour- 433 value, minute-value, and second-value to the numbers denoted 434 by the digits in the date-token, respectively. Skip the 435 remaining sub-steps and continue to the next date-token. 437 3. Abort these steps and *fail to parse* if 439 * at least one of the found-day-of-month, found-month, found- 440 year, or found-time flags is not set, 442 * the day-of-month-value is less than 1 or greater than 31, 444 * the year-value is less than 1601 or greater than 30827, 446 * the hour-value is greater than 23, 448 * the minute-value is greater than 59, or 450 * the second-value is greater than 59. 452 4. If the year-value is greater than 68 and less than 100, increment 453 the year-value by 1900. 455 5. If the year-value is greater than or equal to 0 and less than 69, 456 increment the year-value by 2000. 458 6. Let the parsed-cookie-date be the date whose day-of-month, month, 459 year, hour, minute, and second (in GMT) are the day-of-month- 460 value, the month-value, the year-value, the hour-value, the 461 minute-value, and the second-value, respectively. 463 7. Return the parsed-cookie-date as the result of this algorithm. 465 5.1.2. Domains 467 A *canonicalized* host-name is the host-name converted to lower case. 469 A request-host *domain-matches* a cookie-domain if the cookie-domain 470 is a suffix of the canonicalized request-host and at least one of the 471 following conditions hold: 473 o The cookie-domain and the canonicalized request-host are 474 identical. 476 o The last character of the canonicalized request-host that is not 477 included in the cookie-domain is a U+2E (".") character and 478 request-host is a host name (i.e., not an IP address). [TODO: Is 479 this the right way to spec this???] 481 5.1.3. Paths 483 The user agent MUST use the following algorithm to compute the 484 *default-path* of a cookie: 486 1. Let uri-path be the path portion of the Request-URI. 488 2. If the first character of the uri-path is not a U+2F ("/") 489 character, output U+2F ("/") and skip the remaining steps. 491 3. If the uri-path contains only a single U+2F ("/") character, 492 output U+2F ("/") and skip the remaining steps. 494 4. Output the characters of the uri-path from the first character up 495 to, and but not including, the right-most U+2F ("/"). 497 A request-path *path-matches* a cookie-path if the cookie-path is a 498 prefix of the request-path and at least one of the following 499 conditions hold: [TODO: This isn't exactly what IE does.] 501 o The cookie-path and the request-path are identical. 503 o The last character of the cookie-path is U+2F ("/"). 505 o The first character of the request-path that is not included in 506 the cookie-path is a U+2F ("/") character. 508 5.2. The Set-Cookie Header 510 When a user agent receives an Set-Cookie header in an HTTP response, 511 the user agent *receives a set-cookie-string* consisting of the value 512 of the header. 514 A user agent MUST use the following algorithm to parse set-cookie- 515 strings: 517 1. If the set-cookie-string is empty or consists entirely of WSP 518 characters, the user agent MAY ignore the entirely. 520 2. If the header contains a U+3B (";") character: 522 The name-value-pair string is characters up to, but not 523 including, the first U+3B (";"), and the unparsed-attributes 524 are the remainder of the header (including the U+3B (";") in 525 question). 527 Otherwise: 529 The name-value-pair string is all the character contained in 530 the header, and the unparsed-attributes is the empty string. 532 3. If the name-value-pair string contains a U+3D ("=") character: 534 The (possibly empty) name string is the characters up to, but 535 not including, the first U+3D ("=") character, and the 536 (possibly empty) value string is the characters after the 537 first U+3D ("=") character. 539 Otherwise: 541 The name string is empty, and the value string is the entire 542 name-value-pair string. 544 4. Remove any leading or trailing WSP characters from the name 545 string and the value string. 547 5. The cookie-name is the name string, and the cookie-value is the 548 value string. 550 The user agent MUST use the following algorithm to parse the 551 unparsed-attributes: 553 1. If the unparsed-attributes string is empty, skip the rest of 554 these steps. 556 2. Consume the first character of the unparsed-attributes (which 557 will be a U+3B (";") character). 559 3. If the remaining unparsed-attributes contains a U+3B (";") 560 character: 562 Consume the characters of the unparsed-attributes up to, but 563 not including, the first U+3B (";") character. 565 Otherwise: 567 Consume the remainder of the unparsed-attributes. 569 Let the cookie-av string be the characters consumed in this step. 571 4. If the cookie-av string contains a U+3D ("=") character: 573 The (possibly empty) attribute-name string is the characters 574 up to, but not including, the first U+3D ("=") character, and 575 the (possibly empty) attribute-value string is the characters 576 after the first U+3D ("=") character. 578 Otherwise: 580 The attribute-name string is the entire cookie-av string, and 581 the attribute-value string is empty. (Note that this step 582 differs from the analogous step when parsing the name-value- 583 pair string.) 585 5. Remove any leading or trailing WSP characters from the attribute- 586 name string and the attribute-value string. 588 6. Process the attribute-name and attribute-value according to the 589 requirements in the following subsections. 591 7. Return to Step 1. 593 When the user agent finishes parsing the set-cookie-string header, 594 the user agent *receives a cookie* from the Request-URI with name 595 cookie-name, value cookie-value, and attributes cookie-attribute- 596 list. 598 5.2.1. The Max-Age Attribute 600 If the attribute-name case-insensitively matches the string "Max- 601 Age", the user agent MUST process the cookie-av as follows. 603 If the first character of the attribute-value is not a DIGIT or a "-" 604 character, ignore the cookie-av. 606 If the remainder of attribute-value contains a non-DIGIT character, 607 ignore the cookie-av. 609 Let delta-seconds be the attribute-value converted to an integer. 611 If delta-seconds is less than or equal to zero (0), let expiry-time 612 be the current date and time. Otherwise, let the expiry-time be the 613 current date and time plus delta-seconds seconds. 615 Append an attribute to the cookie-attribute-list with an attribute- 616 name of Expires (note the name conversion) and an attribute-value of 617 expiry-time. 619 5.2.2. The Expires Attribute 621 If the attribute-name case-insensitively matches the string 622 "Expires", the user agent MUST process the cookie-av as follows. 624 Let the parsed-cookie-date be the result of parsing the attribute- 625 value as cookie-date. 627 If the attribute-value failed to parse as a cookie date, ignore the 628 cookie-av. 630 If the user agent received the set-cookie-string from an HTTP 631 response that contains a Date header field and the contents of the 632 last Date header field successfully parse as a cookie-date: 634 Let server-date be the date obtained by parsing the contents of 635 the last Date header field as a cookie-date. 637 Let time-delta be the number of seconds between the server-date 638 and the parsed-cookie-date. 640 Let the expiry-time be the current date and time plus delta- 641 seconds seconds. 643 Otherwise: 645 Let the expiry-time be the parsed-cookie-date. 647 If the expiry-time is later than the last date the user agent can 648 represent, the user agent MAY replace the expiry-time with the last 649 representable date. 651 If the expiry-time is earlier than the first date the user agent can 652 represent, the user agent MAY replace the expiry-time with the first 653 representable date. 655 Append an attribute to the cookie-attribute-list with an attribute- 656 name of Expires and an attribute-value of expiry-time. 658 5.2.3. The Domain Attribute 660 If the attribute-name case-insensitively matches the string "Domain", 661 the user agent MUST process the cookie-av as follows. 663 If the attribute-value is empty, the behavior is undefined. However, 664 user agent SHOULD ignore the cookie-av entirely. 666 If the first character of the attribute-value string is U+2E ("."): 668 Let cookie-domain be the attribute-value with the leading U+2E 669 (".") character. 671 Otherwise: 673 Let cookie-domain be the entire attribute-value. 675 [TODO: Test ".127.0.0.1" and "127.0.0.1"] 677 Append an attribute to the cookie-attribute-list with an attribute- 678 name of Domain and an attribute-value of canonicalized cookie-domain. 680 5.2.4. The Path Attribute 682 If the attribute-name case-insensitively matches the string "Path", 683 the user agent MUST process the cookie-av as follows. 685 If the attribute-value is empty or if the first character of the 686 attribute-value is not U+2F ("/"): 688 Let cookie-path be the default-path. [TODO: We need more tests 689 for this, including with " characters and with multiple Path 690 attributes.] 692 Otherwise: 694 Let cookie-path be the attribute-value. 696 Append an attribute to the cookie-attribute-list with an attribute- 697 name of Path and an attribute-value of cookie-path. 699 5.2.5. The Secure Attribute 701 If the attribute-name case-insensitively matches the string "Secure", 702 the user agent MUST append an attribute to the cookie-attribute-list 703 with an attribute-name of Secure and an empty attribute-value. 705 5.2.6. The HttpOnly Attribute 707 If the attribute-name case-insensitively matches the string 708 "HttpOnly", the user agent MUST append an attribute to the cookie- 709 attribute-list with an attribute-name of Secure and an empty 710 attribute-value. 712 5.3. Storage Model 714 When the user agent receives a cookie, the user agent SHOULD record 715 the cookie in its cookie store as follows. 717 A user agent MAY ignore a received cookie in its entirety if the user 718 agent is configured to block receiving cookies. For example, the 719 user agent might wish to block receiving cookies from "third-party" 720 responses. 722 The user agent stores the following fields about each cookie: name, 723 value, expiry-time, domain, path, creation-time, last-access-time, 724 persistent-flag, host-only-flag, secure-only-flag, and http-only- 725 flag. 727 When the user agent receives a cookie from a Request-URI with name 728 cookie-name, value cookie-value, and attributes cookie-attribute- 729 list, the user agent MUST process the cookie as follows: 731 1. Create a new cookie with name cookie-name, value cookie-value. 732 Set the creation-time and the last-access-time to the current 733 date and time. 735 2. If the cookie-attribute-list contains an attribute with an 736 attribute-name of "Expires": 738 Set the cookie's persistent-flag to true. 740 Set the cookie's expiry-time to attribute-value of the last 741 attribute in the cookie-attribute-list with an attribute-name 742 of "Expires". [TODO: Test that this really works when mixing 743 Max-Age and Expires.] 745 Otherwise: 747 Set the cookie's persistent-flag to false. 749 Set the cookie's expiry-time to the latest representable date. 751 3. If the cookie-attribute-list contains an attribute with an 752 attribute-name of "Domain": 754 Let the domain-attribute be the attribute-value of the last 755 attribute in the cookie-attribute-list with an attribute-name 756 of "Domain". 758 If the Request-URI's host does not domain-match the domain- 759 attribute, ignore the cookie entirely and abort these steps. 761 Set the cookie's host-only-flag to false. 763 Set the cookie's domain to the domain-attribute. 765 Otherwise: 767 Set the cookie's host-only-flag to true. 769 Set the cookie's domain to the host of the Request-URI. 771 4. If the cookie-attribute-list contains an attribute with an 772 attribute-name of "Path", set the cookie's path to attribute- 773 value of the last attribute in the cookie-attribute-list with an 774 attribute-name of "Path". Otherwise, set cookie's path to the 775 default-path of the Request-URI. 777 5. If the cookie-attribute-list contains an attribute with an 778 attribute-name of "Secure", set the cookie's secure-only-flag to 779 true. Otherwise, set cookie's secure-only-flag to false. 781 6. If the cookie-attribute-list contains an attribute with an 782 attribute-name of "HttpOnly", set the cookie's http-only-flag to 783 true. Otherwise, set cookie's http-only-flag to false. 785 7. Remove from the cookie store all cookies that have the share the 786 same name, domain, path, and host-only-flag as the newly created 787 cookie. [TODO: Validate this list!] [TODO: There's some funny 788 business around http-only here.] 790 8. Insert the newly created cookie into the cookie store unless the 791 cookie's name and value are both empty. 793 The user agent MUST evict a cookie from the cookie store if a cookie 794 exists in the cookie store with an expiry date in the past. 796 The user agent MAY evict a cookie from the cookie store if the number 797 of cookies sharing a domain field exceeds some predetermined upper 798 bound (such as 50 cookies). 800 The user agent MAY evict a cookie from the cookie store if the cookie 801 store exceeds some predetermined upper bound (such as 3000 cookies). 803 When the user agent evicts a cookie from the cookie store, the user 804 agent MUST evict cookies in the following priority order: 806 1. Cookies with an expiry date in the past. 808 2. Cookies that share a domain field more than a predetermined 809 number of other cookies. 811 3. All other cookies. 813 If two cookies have the same removal priority, the user agent MUST 814 evict the cookie with the least recent last-access date first. 816 When "the current session is over" (as defined by the user agent), 817 the user agent MUST remove from the cookie store all cookies with the 818 persistent-flag set to false. 820 5.4. The Cookie Header 822 When the user agent generates an HTTP request, the user agent SHOULD 823 attach exactly one HTTP header named Cookie if the cookie-string 824 (defined below) for the Request-URI is non-empty. 826 A user agent MAY elide the Cookie header in its entirety if the user 827 agent is configured to block sending cookies. For example, the user 828 agent might wish to block sending cookies during "third-party" 829 requests. 831 The user agent MUST use the following algorithm to compute the 832 cookie-string from a cookie store and a Request-URI: 834 1. Let cookie-list be the set of cookies from the cookie store that 835 meet the following requirements: 837 * Let request-host be the Request-URI's host. Either: 839 The cookie's host-only-flag is true and the canonicalized 840 request-host is identical to the cookie's domain. 842 Or: 844 The cookie's host-only-flag is false and the request-host 845 domain-matches cookie's domain. 847 * The Request-URI's path patch-matches cookie's path. 849 * If the cookie's secure-only field is true, then the Request- 850 URI's scheme must denote a "secure" protocol (as defined by 851 the user agent). 853 NOTE: The notion of an "secure" protocol is not defined by 854 this document. Typically, user agents consider a protocol 855 secure if the protocol makes use of transport-layer 856 security, such as TLS. For example, most user agents 857 consider "https" to be a scheme that denotes a secure 858 protocol. 860 * If the cookie's http-only field is true, then include the 861 cookie unless the cookie-string is begin generated for a "non- 862 HTTP" API (as defined by the user agent). 864 2. Sort the cookie-list in the following order: 866 * Cookies with longer paths are listed before cookies with 867 shorter paths. 869 * Among cookies that have equal length path fields, cookies with 870 earlier creation-times are listed before cookies with later 871 creation-times. 873 3. Update the last-access-time of each cookie in the cookie-list to 874 the current date and time. 876 4. Serialize the cookie-list into a cookie-string by processing each 877 cookie in the cookie-list in order: 879 1. If the cookie's name is non-empty, output the cookie's name 880 followed by the U+3D ("=") character. 882 2. Output the cookie's value. 884 3. If there is an unprocessed cookie in the cookie-list, output 885 the characters U+3B and U+20 ("; "). 887 6. Implementation Limits 889 Practical user agent implementations have limits on the number and 890 size of cookies that they can store. General-use user agents SHOULD 891 provide each of the following minimum capabilities: 893 o At least 4096 bytes per cookie (as measured by the sum of the 894 length of the cookie's name, value, and attributes). 896 o At least 50 cookies per domain. 898 o At least 3000 cookies total. 900 Servers SHOULD use as few and as small cookies as possible to avoid 901 reaching these implementation limits and to avoid network latency due 902 to the Cookie header being included in every request. 904 Servers should gracefully degrade if the user agent fails to return 905 one or more cookies in the Cookie header because the user agent might 906 evict any cookie at any time on orders from the user. 908 7. Security Considerations 910 7.1. Clear Text 912 The information in the Set-Cookie and Cookie headers is transmitted 913 in the clear. 915 1. All sensitive information conveyed in these headers is exposed to 916 an eavesdropper. 918 2. A malicious intermediary could alter the headers as they travel 919 in either direction, with unpredictable results. 921 3. A malicious client could alter the Cookie header before 922 transmission, with unpredictable results. 924 Servers SHOULD encrypt and sign their cookies. However, encrypting 925 and signing cookies does not prevent an attacker from transplanting a 926 cookie from one user agent to another. 928 In addition to encrypting and signing the the contents of every 929 cookie, servers that require a higher level of security SHOULD use 930 the cookie protocol only over a secure channel. 932 7.2. Weak Confidentiality 934 Cookies do provide isolation by port. If a cookie is readable by a 935 service running on one port, the cookie is also readable by a service 936 running on another port of the same server. If a cookie is writable 937 by a service on one port, the cookie is also writable by a service 938 running on another port of the same server. For this reason, servers 939 SHOULD NOT both run mutually distrusting services on different ports 940 of the same machine and use cookies to store security-sensitive 941 information. 943 Cookies do not provide isolation by scheme. Although most commonly 944 used with the http and https schemes, the cookies for a given host 945 are also available to other schemes, such as ftp and gopher. This 946 lack of isolation is most easily seen when a user agent retrieves a 947 URI with a gopher scheme via HTTP, but the lack of isolation by 948 scheme is also apparent via non-HTTP APIs that permit access to 949 cookies, such as HTML's document.cookie API. 951 7.3. Weak Integrity 953 Cookies do not integrity guarantees for sibling domains (and their 954 subdomains). For example, consider foo.example.com and 955 bar.example.com. The foo.example.com server can set a cookie with a 956 Domain attribute of ".example.com", and the user agent will include 957 that cookie in HTTP requests to bar.example.com. In the worst case, 958 bar.example.com will be unable to distinguish this cookie from a 959 cookie it set itself. The foo.example.com server might be able to 960 leverage this ability to mount an attack against bar.example.com. 962 Similarly, an active network attacker can inject cookies into the 963 Cookie header sent to https://example.com/ by impersonating a 964 response from http://example.com/ and injecting a Set-Cookie header. 965 The HTTPS server at example.com will be unable to distinguish these 966 cookies from cookies that it set itself in an HTTPS response. An 967 active network attacker might be able to leverage this ability to 968 mount an attack against example.com even if example.com uses HTTPS 969 exclusively. 971 Servers can partially mitigate these attacks by encrypting and 972 signing their cookies. However, using cryptography does not fully 973 ameliorate the issue because an attacker can replay a cookie he or 974 she received from the authentic example.com server in the user's 975 session, with unpredictable results. 977 8. Normative References 979 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 980 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 981 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 983 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 984 Specifications: ABNF", STD 68, RFC 5234, January 2008. 986 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 987 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 989 Appendix A. Acknowledgements 991 This document borrows heavily from RFC 2109. [TODO: Figure out the 992 proper way to credit the authors of RFC 2109.] 994 Author's Address 996 Adam Barth 997 University of California, Berkeley 999 Email: abarth@eecs.berkeley.edu 1000 URI: http://www.adambarth.com/