idnits 2.17.1 draft-ietf-httpstate-cookie-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (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 173: '...he origin server MAY ignore the Cookie...' RFC 2119 keyword, line 175: '... server MAY send the user agent a Se...' RFC 2119 keyword, line 176: '...formation, or it MAY send no Set-Cooki...' RFC 2119 keyword, line 179: '... Servers MAY return a Set-Cookie res...' RFC 2119 keyword, line 180: '... User agents SHOULD send a Cookie re...' (39 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 (January 21, 2010) is 5181 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 145, but not defined == Unused Reference: 'RFC2616' is defined on line 1015, but no explicit reference was found in the text == Unused Reference: 'RFC5246' is defined on line 1022, 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) January 21, 2010 5 Intended status: Standards Track 6 Expires: July 25, 2010 8 HTTP State Management Mechanism 9 draft-ietf-httpstate-cookie-02 11 Abstract 13 This document defines the HTTP Cookie and Set-Cookie headers. These 14 headers can be used by HTTP servers to store state on HTTP user 15 agents, letting the servers maintain a stateful session over the 16 mostly stateless HTTP protocol. The cookie protocol has many 17 historical infelicities and should be avoided for new applications of 18 HTTP. 20 NOTE: If you have suggestions for improving the draft, please send 21 email to http-state@ietf.org. Suggestions with test cases are 22 especially appreciated. 24 Status of this Memo 26 This Internet-Draft is submitted to IETF in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF), its areas, and its working groups. Note that 31 other groups may also distribute working documents as Internet- 32 Drafts. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 The list of current Internet-Drafts can be accessed at 40 http://www.ietf.org/ietf/1id-abstracts.txt. 42 The list of Internet-Draft Shadow Directories can be accessed at 43 http://www.ietf.org/shadow.html. 45 This Internet-Draft will expire on July 25, 2010. 47 Copyright Notice 48 Copyright (c) 2010 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the BSD License. 61 This document may contain material from IETF Documents or IETF 62 Contributions published or made publicly available before November 63 10, 2008. The person(s) controlling the copyright in some of this 64 material may not have granted the IETF Trust the right to allow 65 modifications of such material outside the IETF Standards Process. 66 Without obtaining an adequate license from the person(s) controlling 67 the copyright in such materials, this document may not be modified 68 outside the IETF Standards Process, and derivative works of it may 69 not be created outside the IETF Standards Process, except to format 70 it for publication as an RFC or to translate it into languages other 71 than English. 73 Table of Contents 75 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 76 1.1. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 4 77 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 78 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 79 3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 6 80 4. A Well-Behaved Profile . . . . . . . . . . . . . . . . . . . . 7 81 4.1. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . . 7 82 4.1.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . 7 83 4.1.2. Semantics (Non-Normative) . . . . . . . . . . . . . . 8 84 4.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . . 10 85 4.2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . 10 86 4.2.2. Semantics . . . . . . . . . . . . . . . . . . . . . . 10 87 5. The Cookie Protocol . . . . . . . . . . . . . . . . . . . . . 11 88 5.1. Algorithms . . . . . . . . . . . . . . . . . . . . . . . . 11 89 5.1.1. Dates . . . . . . . . . . . . . . . . . . . . . . . . 11 90 5.1.2. Domains . . . . . . . . . . . . . . . . . . . . . . . 13 91 5.1.3. Paths . . . . . . . . . . . . . . . . . . . . . . . . 13 92 5.2. The Set-Cookie Header . . . . . . . . . . . . . . . . . . 14 93 5.2.1. The Max-Age Attribute . . . . . . . . . . . . . . . . 16 94 5.2.2. The Expires Attribute . . . . . . . . . . . . . . . . 16 95 5.2.3. The Domain Attribute . . . . . . . . . . . . . . . . . 17 96 5.2.4. The Path Attribute . . . . . . . . . . . . . . . . . . 17 97 5.2.5. The Secure Attribute . . . . . . . . . . . . . . . . . 18 98 5.2.6. The HttpOnly Attribute . . . . . . . . . . . . . . . . 18 99 5.3. Storage Model . . . . . . . . . . . . . . . . . . . . . . 18 100 5.4. The Cookie Header . . . . . . . . . . . . . . . . . . . . 21 101 6. Implementation Limits . . . . . . . . . . . . . . . . . . . . 23 102 7. Security Considerations . . . . . . . . . . . . . . . . . . . 24 103 7.1. Clear Text . . . . . . . . . . . . . . . . . . . . . . . . 24 104 7.2. Weak Confidentiality . . . . . . . . . . . . . . . . . . . 24 105 7.3. Weak Integrity . . . . . . . . . . . . . . . . . . . . . . 24 106 8. Normative References . . . . . . . . . . . . . . . . . . . . . 26 107 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 27 108 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 28 110 1. Introduction 112 This document defines the HTTP Cookie and Set-Cookie header. Using 113 the Set-Cookie header, an HTTP server can store name/value pairs and 114 associated metadata (called cookies) at the user agent. When the 115 user agent makes subsequent requests to the server, the user agent 116 uses the metadata to determine whether to return the name/value pairs 117 in the Cookie header. 119 Although simple on its surface, the cookie protocol has a number of 120 complexities. For example, the server indicates a scope for each 121 cookie when sending them to the user agent. The scope indicates the 122 maximum amount of time the user agent should retain the cookie, to 123 which servers the user agent should return the cookie, and for which 124 protocols the cookie is applicable. 126 For historical reasons, the cookie protocol contains a number of 127 security and privacy infelicities. For example, a server can 128 indicate that a given cookie is intended for "secure" connections, 129 but the Secure attribute provides only confidentiality (not 130 integrity) from active network attackers. Similarly, cookies for a 131 given host are shared across all the ports on that host, even though 132 the usual "same-origin policy" used by web browsers isolates content 133 retrieved from different ports. 135 1.1. Syntax Notation 137 This specification uses the Augmented Backus-Naur Form (ABNF) 138 notation of [RFC5234]. 140 The following core rules are included by reference, as defined in 141 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 142 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 143 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 144 sequence of data), SP (space), HTAB (horizontal tab), VCHAR (any 145 visible [USASCII] character), and WSP (whitespace). 147 2. Terminology 149 The terms user agent, client, server, proxy, and origin server have 150 the same meaning as in the HTTP/1.1 specification. 152 The terms request-host and request-URI refer to the values the user 153 agent would send to the server as, respectively, the host (but not 154 port) and abs_path portions of the absoluteURI (http_URL) of the HTTP 155 Request-Line. 157 3. Overview 159 We outline here a way for an origin server to send state information 160 to a user agent, and for the user agent to return the state 161 information to the origin server. 163 To initiate a session, the origin server includes a Set-Cookie header 164 in an HTTP response. (Note that "session" here does not refer to a 165 persistent network connection but to a logical session created from 166 HTTP requests and responses. The presence or absence of a persistent 167 connection should have no effect on the use of cookie-derived 168 sessions). 170 The user agent returns a Cookie request header to the origin server 171 if it chooses to continue a session. The Cookie header contains a 172 number of cookies the user agent received in previous Set-Cookie 173 headers. The origin server MAY ignore the Cookie header or use the 174 header to determine the current state of the session. The origin 175 server MAY send the user agent a Set-Cookie response header with the 176 same or different information, or it MAY send no Set-Cookie header at 177 all. 179 Servers MAY return a Set-Cookie response header with any response. 180 User agents SHOULD send a Cookie request header, subject to other 181 rules detailed below, with every request. 183 An origin server MAY include multiple Set-Cookie header fields in a 184 single response. Note that an intervening gateway MUST NOT fold 185 multiple Set-Cookie header fields into a single header field. 187 3.1. Examples 189 [TODO: Put some examples here. 191 4. A Well-Behaved Profile 193 This section describes the syntax and semantics of a well-behaved 194 profile of the protocol. Servers SHOULD use the profile described in 195 this section, both to maximize interoperability with existing user 196 agents and because a future version of the cookie protocol could 197 remove support for some of the most esoteric aspects of the protocol. 198 User agents, however, MUST implement the full protocol to ensure 199 interoperability with servers making use of the full protocol. 201 4.1. Set-Cookie 203 The Set-Cookie header is used to send cookies from the server to the 204 user agent. 206 4.1.1. Syntax 208 Informally, the Set-Cookie response header comprises the token Set- 209 Cookie:, followed by a cookie. Each cookie begins with a name-value- 210 pair, followed by zero or more attribute-value pairs. Servers SHOULD 211 NOT send Set-Cookie headers that fail to conform to the following 212 grammar: 214 set-cookie-header = "Set-Cookie:" OWS set-cookie-string OWS 215 set-cookie-string = cookie-pair *( ";" cookie-av ) 216 cookie-pair = cookie-name "=" cookie-value 217 cookie-name = token 218 cookie-value = token 219 token = 221 cookie-av = expires-av / domain-av / path-av / 222 secure-av / httponly-av 223 expires-av = "Expires" "=" cookie-date 224 cookie-date = 225 domain-av = "Domain" "=" domain-value 226 domain-value = token 227 path-av = "Path" "=" path-value 228 path-value = 229 secure-av = "Secure" 230 httponly-av = "HttpOnly" 232 Servers SHOULD NOT include two attributes with the same name. 234 The cookie-value is opaque to the user agent and MAY be anything the 235 origin server chooses to send, possibly in a server-selected 236 printable ASCII encoding. "Opaque" implies that the content is of 237 interest and relevance only to the origin server. The content is, in 238 fact, readable by anyone who examines the Set-Cookie header. 240 NOTE: The syntax above allows whitespace between the attribute and 241 the U+003D ("=") character. Servers wishing to interoperate with 242 some legacy user agents might wish to elide this whitespace. 244 4.1.2. Semantics (Non-Normative) 246 This section describes a simplified semantics of the Set-Cookie 247 header. These semantics are detailed enough to be useful for 248 understanding the most common uses of the cookie protocol. The full 249 semantics are described in Section 5. 251 When the user agent receives a Set-Cookie header, the user agent 252 stores the cookie in its cookie store. When the user agent 253 subsequently makes an HTTP request, the user agent consults its 254 cookie store and includes the applicable, non-expired cookies in the 255 Cookie header. 257 If the cookie store already contains a cookie with the same cookie- 258 name, domain-value, and path-value, the existing cookie is evicted 259 from the cookie store and replaced with the new value. Notice that 260 servers can delete cookies by including an Expires attribute with a 261 value in the past. 263 Unless the cookie's attributes indicate otherwise, the cookie is 264 returned only to the origin server, and it expires at the end of the 265 current session (as defined by the user agent). User agents ignore 266 unrecognized cookie attributes. 268 4.1.2.1. Expires 270 The Expires attribute indicates the maximum lifetime of the cookie, 271 represented as the date and time at which the cookie expires. The 272 user agent is not required to retain the cookie until the specified 273 date has passed. In fact, user agents often evict cookies from the 274 cookie store due to memory pressure or privacy concerns. 276 4.1.2.2. Domain 278 The Domain attribute specifies those hosts for which the cookie will 279 be sent. For example, if the Domain attribute contains the value 280 ".example.com", the user agent will include the cookie in the Cookie 281 header when making HTTP requests to example.com, www.example.com, and 282 www.corp.example.com. (Note that a leading U+002E ("."), if present, 283 is ignored.) If the server omits the Domain attribute, the user 284 agent will return the cookie only to the origin server. 286 The user agent will reject cookies (refuse to store them in the 287 cookie store) unless the Domain attribute specifies a scope for the 288 cookie that would include the origin server. For example, the user 289 agent will accept a Domain attribute of ".example.com" or of 290 ".foo.example.com" from foo.example.com, but the user agent will not 291 accept a Domain attribute of ".bar.example.com" or of 292 ".baz.foo.example.com". 294 NOTE: For security reasons, some user agents are configured to reject 295 Domain attributes that do not correspond to a "registry controlled" 296 domain (or a subdomain of a registry controlled domain). For 297 example, some user agents will reject Domain attributes of ".com". 299 4.1.2.3. Path 301 The Path attribute limits the scope of the cookie to a set of paths. 302 When a cookie has a Path attribute, the user agent will include the 303 cookie in an HTTP request only if the path portion of the Request-URI 304 matches (or is a subdirectory of) the cookie's Path attribute, where 305 the U+002F ("/") character is interpreted as a directory separator. 306 If the server omits the Path attribute, the user agent will use the 307 directory of the Request-URI's path component as the default value. 309 Although seemingly useful for isolating cookies between different 310 paths within a given domain, the Path attribute cannot be relied upon 311 for security for two reasons: First, user agents do not prevent one 312 path from overwriting the cookies for another path. For example, if 313 a response to a request for /foo/bar.html attempts to set a cookie 314 with a Path attribute of "/baz" the user agent will store that cookie 315 in the cookie store. Second, the "same-origin" policy implemented by 316 many user agents does not isolate different paths within an origin. 317 For example, /foo/bar.html can read cookies with a Path attribute of 318 "/baz" because they are within the "same origin". 320 4.1.2.4. Secure 322 The Secure attribute limits the scope of the cookie to "secure" 323 channels (where "secure" is defined by the user agent). When a 324 cookie has the Secure attribute, the user agent will include the 325 cookie in an HTTP request only if the request is transmitted over a 326 secure channel (typically TLS [RFC5234]). 328 Although seemingly useful for protecting cookies from active network 329 attackers, the Secure attribute protects only the cookie's 330 confidentiality. An active network attacker can overwrite Secure 331 cookies from an insecure channel, disrupting the integrity of the 332 cookies. 334 4.1.2.5. HttpOnly 336 The HttpOnly attribute limits the scope of the cookie to HTTP 337 requests. In particular, the attribute instructs the user agent to 338 elide the cookie when providing access to its cookie store via "non- 339 HTTP" APIs (as defined by the user agent). 341 4.2. Cookie 343 4.2.1. Syntax 345 The user agent returns stored cookies to the origin server in the 346 Cookie header. If the server conforms to the requirements in this 347 section, the requirements in the next section will cause the user 348 agent to return a Cookie header that conforms to the following 349 grammar: 351 cookie-header = "Cookie:" OWS cookie-string OWS 352 cookie-string = cookie-pair *( ";" cookie-pair ) 353 cookie-pair = cookie-name "=" cookie-value 354 cookie-name = token 355 cookie-value = token 356 token = 358 4.2.2. Semantics 360 Each cookie-pair represents a cookie stored by the user agent. The 361 cookie-name and the cookie-value are returned verbatim from the 362 corresponding parts of the Set-Cookie header. 364 Notice that the cookie attributes are not returned. In particular, 365 the server cannot determine from the Cookie header alone when a 366 cookie will expire, for which domains the cookie is valid, for which 367 paths the cookie is valid, or whether the cookie was set with the 368 Secure or HttpOnly attributes. 370 The semantics of individual cookies in the Cookie header is not 371 defined by this document. Servers are expected to imbue these 372 cookies with server-specific semantics. 374 5. The Cookie Protocol 376 For historical reasons, the full cookie protocol contains a number of 377 exotic quirks. This section is intended to specify the cookie 378 protocol in enough detail to enable a user agent that implements the 379 protocol precisely as specified to interoperate with existing 380 servers. 382 Conformance requirements phrased as algorithms or specific steps may 383 be implemented in any manner, so long as the end result is 384 equivalent. (In particular, the algorithms defined in this 385 specification are intended to be easy to follow, and not intended to 386 be performant.) 388 5.1. Algorithms 390 This section defines a number of algorithms used by the cookie 391 protocol. 393 5.1.1. Dates 395 The user agent MUST use the following algorithm to *parse a cookie- 396 date*: 398 1. Using the grammar below, divide the cookie-date into date-tokens. 400 cookie-date = *delimiter date-token-list *delimiter 401 date-token-list = date-token *( 1*delimiter date-token ) 402 delimiter = %x09 / %x20 / %x21 / %x22 / %x23 / %x24 / 403 %x25 / %x26 / %x27 / %x28 / %x29 / %x2A / 404 %x2B / %x2C / %x2D / %x2E / %x2F / %x3B / 405 %x3C / %x3D / %x3E / %x3F / %x40 / %x5B / 406 %x5C / %x5D / %x5E / %x5F / %x60 / %x7B / 407 %x7C / %x7D / %x7E 408 date-token = day-of-month / month / year / time / mystery 409 day-of-month = 2DIGIT / DIGIT 410 month = "jan" [ mystery ] / "feb" [ mystery ] / 411 "mar" [ mystery ] / "apr" [ mystery ] / 412 "may" [ mystery ] / "jun" [ mystery ] / 413 "jul" [ mystery ] / "aug" [ mystery ] / 414 "sep" [ mystery ] / "oct" [ mystery ] / 415 "nov" [ mystery ] / "dec" [ mystery ] 416 year = 5DIGIT / 4DIGIT / 3DIGIT / 2DIGIT / DIGIT 417 time = 2DIGIT ":" 2DIGIT ":" 2DIGIT 418 mystery = 419 2. Process each date-token sequentially in the order the date-tokens 420 appear in the cookie-date: 422 1. If the found-day-of-month flag is not set and the date-token 423 matches the day-of-month production, set the found-day-of- 424 month flag and set the day-of-month-value to the number 425 denoted by the date-token. Skip the remaining sub-steps and 426 continue to the next date-token. 428 2. If the found-month flag is not set and the date-token matches 429 the month production, set the found-month flag and set the 430 month-value to the month denoted by the date-token. Skip the 431 remaining sub-steps and continue to the next date-token. 433 3. If the found-year flag is not set and the date-token matches 434 the year production, set the found-year flag and set the 435 year-value to the number denoted by the date-token. Skip the 436 remaining sub-steps and continue to the next date-token. 438 4. If the found-time flag is not set and the token matches the 439 time production, set the found-time flag and set the hour- 440 value, minute-value, and second-value to the numbers denoted 441 by the digits in the date-token, respectively. Skip the 442 remaining sub-steps and continue to the next date-token. 444 3. Abort these steps and *fail to parse* if 446 * at least one of the found-day-of-month, found-month, found- 447 year, or found-time flags is not set, 449 * the day-of-month-value is less than 1 or greater than 31, 451 * the year-value is less than 1601 or greater than 30827, 453 * the hour-value is greater than 23, 455 * the minute-value is greater than 59, or 457 * the second-value is greater than 59. 459 4. If the year-value is greater than 68 and less than 100, increment 460 the year-value by 1900. 462 5. If the year-value is greater than or equal to 0 and less than 69, 463 increment the year-value by 2000. 465 6. Let the parsed-cookie-date be the date whose day-of-month, month, 466 year, hour, minute, and second (in GMT) are the day-of-month- 467 value, the month-value, the year-value, the hour-value, the 468 minute-value, and the second-value, respectively. 470 7. Return the parsed-cookie-date as the result of this algorithm. 472 5.1.2. Domains 474 A *canonicalized* host-name is the host-name converted to lower case. 476 A request-host *domain-matches* a cookie-domain if at least one of 477 the following conditions hold: 479 o The cookie-domain and the canonicalized request-host are 480 identical. 482 o The cookie-domain is a suffix of the canonicalized request-host, 483 the last character of the canonicalized request-host that is not 484 included in the cookie-domain is a U+002E (".") character, and 485 request-host is a host name (i.e., not an IP address). [TODO: Is 486 this the right way to spec this???] 488 5.1.3. Paths 490 The user agent MUST use the following algorithm to compute the 491 *default-path* of a cookie: 493 1. Let uri-path be the path portion of the Request-URI. 495 2. If the first character of the uri-path is not a U+002F ("/") 496 character, output U+002F ("/") and skip the remaining steps. 498 3. If the uri-path contains only a single U+002F ("/") character, 499 output U+002F ("/") and skip the remaining steps. 501 4. Output the characters of the uri-path from the first character up 502 to, but not including, the right-most U+002F ("/"). 504 A request-path *path-matches* a cookie-path if at least one of the 505 following conditions hold: [TODO: This isn't exactly what IE or 506 Firefox does.] 508 o The cookie-path and the request-path are identical. 510 o The cookie-path is a prefix of the request-path and the last 511 character of the cookie-path is U+002F ("/"). 513 o The cookie-path is a prefix of the request-path and the first 514 character of the request-path that is not included in the cookie- 515 path is a U+002F ("/") character. 517 5.2. The Set-Cookie Header 519 When a user agent receives a Set-Cookie header in an HTTP response, 520 the user agent *receives a set-cookie-string* consisting of the value 521 of the header. 523 A user agent MUST use the following algorithm to parse set-cookie- 524 strings: 526 1. If the set-cookie-string is empty or consists entirely of WSP 527 characters, the user agent MAY ignore the set-cookie-string 528 entirely. 530 2. If the set-cookie-string contains a U+003B (";") character: 532 The name-value-pair string consists of the characters up to, 533 but not including, the first U+003B (";"), and the unparsed- 534 attributes consist of the remainder of the set-cookie-string 535 (including the U+003B (";") in question). 537 Otherwise: 539 The name-value-pair string consists of all the characters 540 contained in the set-cookie-string, and the unparsed- 541 attributes is the empty string. 543 3. If the name-value-pair string contains a U+003D ("=") character: 545 The (possibly empty) name string consists of the characters up 546 to, but not including, the first U+003D ("=") character, and 547 the (possibly empty) value string consists of the characters 548 after the first U+003D ("=") character. 550 Otherwise: 552 The name string is empty, and the value string consists of the 553 entire name-value-pair string. 555 4. Remove any leading or trailing WSP characters from the name 556 string and the value string. 558 5. The cookie-name is the name string, and the cookie-value is the 559 value string. 561 The user agent MUST use the following algorithm to parse the 562 unparsed-attributes: 564 1. If the unparsed-attributes string is empty, skip the rest of 565 these steps. 567 2. Consume the first character of the unparsed-attributes (which 568 will be a U+003B (";") character). 570 3. If the remaining unparsed-attributes contains a U+003B (";") 571 character: 573 Consume the characters of the unparsed-attributes up to, but 574 not including, the first U+003B (";") character. 576 Otherwise: 578 Consume the remainder of the unparsed-attributes. 580 Let the cookie-av string be the characters consumed in this step. 582 4. If the cookie-av string contains a U+003D ("=") character: 584 The (possibly empty) attribute-name string consists of the 585 characters up to, but not including, the first U+003D ("=") 586 character, and the (possibly empty) attribute-value string 587 consists of the characters after the first U+003D ("=") 588 character. 590 Otherwise: 592 The attribute-name string consists of the entire cookie-av 593 string, and the attribute-value string is empty. (Note that 594 this step differs from the analogous step when parsing the 595 name-value-pair string.) 597 5. Remove any leading or trailing WSP characters from the attribute- 598 name string and the attribute-value string. 600 6. Process the attribute-name and attribute-value according to the 601 requirements in the following subsections. 603 7. Return to Step 1. 605 When the user agent finishes parsing the set-cookie-string, the user 606 agent *receives a cookie* from the Request-URI with name cookie-name, 607 value cookie-value, and attributes cookie-attribute-list. 609 5.2.1. The Max-Age Attribute 611 If the attribute-name case-insensitively matches the string "Max- 612 Age", the user agent MUST process the cookie-av as follows. 614 If the first character of the attribute-value is not a DIGIT or a "-" 615 character, ignore the cookie-av. 617 If the remainder of attribute-value contains a non-DIGIT character, 618 ignore the cookie-av. 620 Let delta-seconds be the attribute-value converted to an integer. 622 If delta-seconds is less than or equal to zero (0), let expiry-time 623 be the current date and time. Otherwise, let the expiry-time be the 624 current date and time plus delta-seconds seconds. 626 Append an attribute to the cookie-attribute-list with an attribute- 627 name of Expires (note the name conversion) and an attribute-value of 628 expiry-time. 630 5.2.2. The Expires Attribute 632 If the attribute-name case-insensitively matches the string 633 "Expires", the user agent MUST process the cookie-av as follows. 635 Let the parsed-cookie-date be the result of parsing the attribute- 636 value as cookie-date. 638 If the attribute-value failed to parse as a cookie date, ignore the 639 cookie-av. 641 If the user agent received the set-cookie-string from an HTTP 642 response that contains a Date header field and the contents of the 643 last Date header field successfully parse as a cookie-date: 645 Let server-date be the date obtained by parsing the contents of 646 the last Date header field as a cookie-date. 648 Let delta-seconds be the number of seconds between the server-date 649 and the parsed-cookie-date (i.e., parsed-cookie-date - server- 650 date). 652 Let the expiry-time be the current date and time plus delta- 653 seconds seconds. 655 Otherwise: 657 Let the expiry-time be the parsed-cookie-date. 659 If the expiry-time is later than the last date the user agent can 660 represent, the user agent MAY replace the expiry-time with the last 661 representable date. 663 If the expiry-time is earlier than the first date the user agent can 664 represent, the user agent MAY replace the expiry-time with the first 665 representable date. 667 Append an attribute to the cookie-attribute-list with an attribute- 668 name of Expires and an attribute-value of expiry-time. 670 5.2.3. The Domain Attribute 672 If the attribute-name case-insensitively matches the string "Domain", 673 the user agent MUST process the cookie-av as follows. 675 If the attribute-value is empty, the behavior is undefined. However, 676 user agent SHOULD ignore the cookie-av entirely. 678 If the first character of the attribute-value string is U+002E ("."): 680 Let cookie-domain be the attribute-value without the leading 681 U+002E (".") character. 683 Otherwise: 685 Let cookie-domain be the entire attribute-value. 687 Convert the cookie-domain to lower case. 689 [TODO: Test ".127.0.0.1" and "127.0.0.1"] 691 Append an attribute to the cookie-attribute-list with an attribute- 692 name of Domain and an attribute-value of cookie-domain. 694 5.2.4. The Path Attribute 696 If the attribute-name case-insensitively matches the string "Path", 697 the user agent MUST process the cookie-av as follows. 699 If the attribute-value is empty or if the first character of the 700 attribute-value is not U+002F ("/"): 702 Let cookie-path be the default-path. [TODO: We need more tests 703 for this, including with " characters and with multiple Path 704 attributes.] 706 Otherwise: 708 Let cookie-path be the attribute-value. 710 Append an attribute to the cookie-attribute-list with an attribute- 711 name of Path and an attribute-value of cookie-path. 713 5.2.5. The Secure Attribute 715 If the attribute-name case-insensitively matches the string "Secure", 716 the user agent MUST append an attribute to the cookie-attribute-list 717 with an attribute-name of Secure and an empty attribute-value. 719 5.2.6. The HttpOnly Attribute 721 If the attribute-name case-insensitively matches the string 722 "HttpOnly", the user agent MUST append an attribute to the cookie- 723 attribute-list with an attribute-name of Secure and an empty 724 attribute-value. 726 5.3. Storage Model 728 When the user agent receives a cookie, the user agent SHOULD record 729 the cookie in its cookie store as follows. 731 A user agent MAY ignore a received cookie in its entirety if the user 732 agent is configured to block receiving cookies. For example, the 733 user agent might wish to block receiving cookies from "third-party" 734 responses. 736 The user agent stores the following fields about each cookie: name, 737 value, expiry-time, domain, path, creation-time, last-access-time, 738 persistent-flag, host-only-flag, secure-only-flag, and http-only- 739 flag. 741 When the user agent receives a cookie from a Request-URI with name 742 cookie-name, value cookie-value, and attributes cookie-attribute- 743 list, the user agent MUST process the cookie as follows: 745 1. Create a new cookie with name cookie-name, value cookie-value. 746 Set the creation-time and the last-access-time to the current 747 date and time. 749 2. If the cookie-attribute-list contains an attribute with an 750 attribute-name of "Expires": 752 Set the cookie's persistent-flag to true. 754 Set the cookie's expiry-time to attribute-value of the last 755 attribute in the cookie-attribute-list with an attribute-name 756 of "Expires". [TODO: Test that this really works when mixing 757 Max-Age and Expires.] 759 Otherwise: 761 Set the cookie's persistent-flag to false. 763 Set the cookie's expiry-time to the latest representable 764 date. 766 3. If the cookie-attribute-list contains an attribute with an 767 attribute-name of "Domain": 769 Let the domain-attribute be the attribute-value of the last 770 attribute in the cookie-attribute-list with an attribute-name 771 of "Domain". 773 If the Request-URI's host does not domain-match the domain- 774 attribute, ignore the cookie entirely and abort these steps. 776 If the user agent is configured to use a "public suffix" list 777 and the domain-attribute is a public suffix, ignore the 778 cookie entirely and abort these steps. 780 NOTE: A "public suffix" is a domain that is controlled by 781 a public registry, such as "com", "co.uk", and 782 "pvt.k12.wy.us". This step is essential for preventing 783 attacker.com from disrupting the integrity of example.com 784 by setting a cookie with a Domain attribute of "com". 785 Unfortunately, the set of public suffixes (also known as 786 "registry controlled domains") changes over time. If 787 feasible, user agents SHOULD use an up-to-date public 788 suffix list, such as the one maintained by the Mozilla 789 project at http://publicsuffix.org/. 791 Set the cookie's host-only-flag to false. 793 Set the cookie's domain to the domain-attribute. 795 Otherwise: 797 Set the cookie's host-only-flag to true. 799 Set the cookie's domain to the host of the Request-URI. 801 4. If the cookie-attribute-list contains an attribute with an 802 attribute-name of "Path", set the cookie's path to attribute- 803 value of the last attribute in the cookie-attribute-list with an 804 attribute-name of "Path". Otherwise, set cookie's path to the 805 default-path of the Request-URI. 807 5. If the cookie-attribute-list contains an attribute with an 808 attribute-name of "Secure", set the cookie's secure-only-flag to 809 true. Otherwise, set cookie's secure-only-flag to false. 811 6. If the cookie-attribute-list contains an attribute with an 812 attribute-name of "HttpOnly", set the cookie's http-only-flag to 813 true. Otherwise, set cookie's http-only-flag to false. 815 7. Remove from the cookie store all cookies that share the same 816 name, domain, path, and host-only-flag as the newly created 817 cookie. [TODO: Validate this list!] [TODO: There's some funny 818 business around http-only here.] 820 8. If the cookie's name and value are both empty, abort these 821 steps. 823 9. If the cookie's expiry-time is not in the future, abort these 824 steps. 826 10. Insert the newly created cookie into the cookie store. 828 The user agent MUST evict a cookie from the cookie store if, at any 829 time, a cookie exists in the cookie store with an expiry date in the 830 past. 832 The user agent MAY evict a cookie from the cookie store if the number 833 of cookies sharing a domain field exceeds some predetermined upper 834 bound (such as 50 cookies). 836 The user agent MAY evict a cookie from the cookie store if the cookie 837 store exceeds some predetermined upper bound (such as 3000 cookies). 839 When the user agent evicts a cookie from the cookie store, the user 840 agent MUST evict cookies in the following priority order: 842 1. Cookies with an expiry date in the past. 844 2. Cookies that share a domain field with more than a predetermined 845 number of other cookies. 847 3. All cookies. 849 If two cookies have the same removal priority, the user agent MUST 850 evict the cookie with the least recent last-access date first. 852 When "the current session is over" (as defined by the user agent), 853 the user agent MUST remove from the cookie store all cookies with the 854 persistent-flag set to false. 856 5.4. The Cookie Header 858 When the user agent generates an HTTP request, the user agent SHOULD 859 attach exactly one HTTP header named Cookie if the cookie-string 860 (defined below) for the Request-URI is non-empty. 862 A user agent MAY elide the Cookie header in its entirety if the user 863 agent is configured to block sending cookies. For example, the user 864 agent might wish to block sending cookies during "third-party" 865 requests. 867 The user agent MUST use the following algorithm to compute the 868 cookie-string from a cookie store and a Request-URI: 870 1. Let cookie-list be the set of cookies from the cookie store that 871 meet all of the following requirements: 873 * Let request-host be the Request-URI's host. Either: 875 The cookie's host-only-flag is true and the canonicalized 876 request-host is identical to the cookie's domain. 878 Or: 880 The cookie's host-only-flag is false and the request-host 881 domain-matches cookie's domain. 883 * The Request-URI's path patch-matches cookie's path. 885 * If the cookie's secure-only field is true, then the Request- 886 URI's scheme must denote a "secure" protocol (as defined by 887 the user agent). 889 NOTE: The notion of a "secure" protocol is not defined by 890 this document. Typically, user agents consider a protocol 891 secure if the protocol makes use of transport-layer 892 security, such as TLS. For example, most user agents 893 consider "https" to be a scheme that denotes a secure 894 protocol. 896 * If the cookie's http-only field is true, then exclude the 897 cookie unless the cookie-string is being generated for an 898 "HTTP" API (as defined by the user agent). 900 2. Sort the cookie-list in the following order: 902 * Cookies with longer paths are listed before cookies with 903 shorter paths. 905 * Among cookies that have equal length path fields, cookies with 906 earlier creation-times are listed before cookies with later 907 creation-times. 909 3. Update the last-access-time of each cookie in the cookie-list to 910 the current date and time. 912 4. Serialize the cookie-list into a cookie-string by processing each 913 cookie in the cookie-list in order: 915 1. If the cookie's name is non-empty, output the cookie's name 916 followed by the U+003D ("=") character. 918 2. Output the cookie's value. 920 3. If there is an unprocessed cookie in the cookie-list, output 921 the characters U+003B and U+0020 ("; "). 923 6. Implementation Limits 925 Practical user agent implementations have limits on the number and 926 size of cookies that they can store. General-use user agents SHOULD 927 provide each of the following minimum capabilities: 929 o At least 4096 bytes per cookie (as measured by the sum of the 930 length of the cookie's name, value, and attributes). 932 o At least 50 cookies per domain. 934 o At least 3000 cookies total. 936 Servers SHOULD use as few and as small cookies as possible to avoid 937 reaching these implementation limits and to avoid network latency due 938 to the Cookie header being included in every request. 940 Servers should gracefully degrade if the user agent fails to return 941 one or more cookies in the Cookie header because the user agent might 942 evict any cookie at any time on orders from the user. 944 7. Security Considerations 946 7.1. Clear Text 948 The information in the Set-Cookie and Cookie headers is transmitted 949 in the clear. 951 1. All sensitive information conveyed in these headers is exposed to 952 an eavesdropper. 954 2. A malicious intermediary could alter the headers as they travel 955 in either direction, with unpredictable results. 957 3. A malicious client could alter the Cookie header before 958 transmission, with unpredictable results. 960 Servers SHOULD encrypt and sign their cookies. However, encrypting 961 and signing cookies does not prevent an attacker from transplanting a 962 cookie from one user agent to another. 964 In addition to encrypting and signing the contents of every cookie, 965 servers that require a higher level of security SHOULD use the cookie 966 protocol only over a secure channel. 968 7.2. Weak Confidentiality 970 Cookies do not provide isolation by port. If a cookie is readable by 971 a service running on one port, the cookie is also readable by a 972 service running on another port of the same server. If a cookie is 973 writable by a service on one port, the cookie is also writable by a 974 service running on another port of the same server. For this reason, 975 servers SHOULD NOT both run mutually distrusting services on 976 different ports of the same machine and use cookies to store 977 security-sensitive information. 979 Cookies do not provide isolation by scheme. Although most commonly 980 used with the http and https schemes, the cookies for a given host 981 are also available to other schemes, such as ftp and gopher. This 982 lack of isolation is most easily seen when a user agent retrieves a 983 URI with a gopher scheme via HTTP, but the lack of isolation by 984 scheme is also apparent via non-HTTP APIs that permit access to 985 cookies, such as HTML's document.cookie API. 987 7.3. Weak Integrity 989 Cookies do not provide integrity guarantees for sibling domains (and 990 their subdomains). For example, consider foo.example.com and 991 bar.example.com. The foo.example.com server can set a cookie with a 992 Domain attribute of ".example.com", and the user agent will include 993 that cookie in HTTP requests to bar.example.com. In the worst case, 994 bar.example.com will be unable to distinguish this cookie from a 995 cookie it set itself. The foo.example.com server might be able to 996 leverage this ability to mount an attack against bar.example.com. 998 Similarly, an active network attacker can inject cookies into the 999 Cookie header sent to https://example.com/ by impersonating a 1000 response from http://example.com/ and injecting a Set-Cookie header. 1001 The HTTPS server at example.com will be unable to distinguish these 1002 cookies from cookies that it set itself in an HTTPS response. An 1003 active network attacker might be able to leverage this ability to 1004 mount an attack against example.com even if example.com uses HTTPS 1005 exclusively. 1007 Servers can partially mitigate these attacks by encrypting and 1008 signing their cookies. However, using cryptography does not mitigate 1009 the issue completely because an attacker can replay a cookie he or 1010 she received from the authentic example.com server in the user's 1011 session, with unpredictable results. 1013 8. Normative References 1015 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1016 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1017 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1019 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1020 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1022 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1023 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1025 Appendix A. Acknowledgements 1027 This document borrows heavily from RFC 2109. [TODO: Figure out the 1028 proper way to credit the authors of RFC 2109.] 1030 Author's Address 1032 Adam Barth 1033 University of California, Berkeley 1035 Email: abarth@eecs.berkeley.edu 1036 URI: http://www.adambarth.com/