idnits 2.17.1 draft-ietf-httpstate-cookie-03.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 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 lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == 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 (February 12, 2010) is 5186 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 165, but not defined == Unused Reference: 'RFC2616' is defined on line 1119, but no explicit reference was found in the text == Unused Reference: 'RFC5246' is defined on line 1126, 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: 4 errors (**), 0 flaws (~~), 6 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) February 12, 2010 5 Intended status: Standards Track 6 Expires: August 16, 2010 8 HTTP State Management Mechanism 9 draft-ietf-httpstate-cookie-03 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 August 16, 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 2. General Nonsense . . . . . . . . . . . . . . . . . . . . . . . 5 77 2.1. Conformance Criteria . . . . . . . . . . . . . . . . . . . 5 78 2.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 5 79 2.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 80 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 81 3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 6 82 4. A Well-Behaved Profile . . . . . . . . . . . . . . . . . . . . 7 83 4.1. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . . 7 84 4.1.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . 7 85 4.1.2. Semantics (Non-Normative) . . . . . . . . . . . . . . 8 86 4.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . . 10 87 4.2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . 10 88 4.2.2. Semantics . . . . . . . . . . . . . . . . . . . . . . 10 89 5. The Cookie Protocol . . . . . . . . . . . . . . . . . . . . . 11 90 5.1. Algorithms . . . . . . . . . . . . . . . . . . . . . . . . 11 91 5.1.1. Dates . . . . . . . . . . . . . . . . . . . . . . . . 11 92 5.1.2. Domains . . . . . . . . . . . . . . . . . . . . . . . 13 93 5.1.3. Paths . . . . . . . . . . . . . . . . . . . . . . . . 13 94 5.2. The Set-Cookie Header . . . . . . . . . . . . . . . . . . 14 95 5.2.1. The Max-Age Attribute . . . . . . . . . . . . . . . . 16 96 5.2.2. The Expires Attribute . . . . . . . . . . . . . . . . 16 97 5.2.3. The Domain Attribute . . . . . . . . . . . . . . . . . 17 98 5.2.4. The Path Attribute . . . . . . . . . . . . . . . . . . 17 99 5.2.5. The Secure Attribute . . . . . . . . . . . . . . . . . 18 100 5.2.6. The HttpOnly Attribute . . . . . . . . . . . . . . . . 18 101 5.3. Storage Model . . . . . . . . . . . . . . . . . . . . . . 18 102 5.4. The Cookie Header . . . . . . . . . . . . . . . . . . . . 21 103 6. Implementation Considerations . . . . . . . . . . . . . . . . 23 104 6.1. Limits . . . . . . . . . . . . . . . . . . . . . . . . . . 23 105 6.2. Application Programmer Interfaces . . . . . . . . . . . . 23 106 7. Security Considerations . . . . . . . . . . . . . . . . . . . 24 107 7.1. General Recommendations . . . . . . . . . . . . . . . . . 24 108 7.2. Ambient Authority . . . . . . . . . . . . . . . . . . . . 24 109 7.3. Clear Text . . . . . . . . . . . . . . . . . . . . . . . . 24 110 7.4. Weak Confidentiality . . . . . . . . . . . . . . . . . . . 25 111 7.5. Weak Integrity . . . . . . . . . . . . . . . . . . . . . . 25 112 7.6. Reliance on DNS . . . . . . . . . . . . . . . . . . . . . 26 113 8. Normative References . . . . . . . . . . . . . . . . . . . . . 27 114 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 28 115 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 29 117 1. Introduction 119 This document defines the HTTP Cookie and Set-Cookie header. Using 120 the Set-Cookie header, an HTTP server can store name/value pairs and 121 associated metadata (called cookies) at the user agent. When the 122 user agent makes subsequent requests to the server, the user agent 123 uses the metadata to determine whether to return the name/value pairs 124 in the Cookie header. 126 Although simple on its surface, the cookie protocol has a number of 127 complexities. For example, the server indicates a scope for each 128 cookie when sending them to the user agent. The scope indicates the 129 maximum amount of time the user agent should retain the cookie, to 130 which servers the user agent should return the cookie, and for which 131 protocols the cookie is applicable. 133 For historical reasons, the cookie protocol contains a number of 134 security and privacy infelicities. For example, a server can 135 indicate that a given cookie is intended for "secure" connections, 136 but the Secure attribute provides only confidentiality (not 137 integrity) from active network attackers. Similarly, cookies for a 138 given host are shared across all the ports on that host, even though 139 the usual "same-origin policy" used by web browsers isolates content 140 retrieved from different ports. 142 2. General Nonsense 144 2.1. Conformance Criteria 146 The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", 147 "RECOMMENDED", "MAY", and "OPTIONAL" in document are to be 148 interpreted as described in [RFC2119]. 150 Requirements phrased in the imperative as part of algorithms (such as 151 "strip any leading space characters" or "return false and abort these 152 steps") are to be interpreted with the meaning of the key word 153 ("MUST", "SHOULD", "MAY", etc) used in introducing the algorithm. 155 2.2. Syntax Notation 157 This specification uses the Augmented Backus-Naur Form (ABNF) 158 notation of [RFC5234]. 160 The following core rules are included by reference, as defined in 161 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 162 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 163 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 164 sequence of data), SP (space), HTAB (horizontal tab), VCHAR (any 165 visible [USASCII] character), and WSP (whitespace). 167 2.3. Terminology 169 The terms user agent, client, server, proxy, and origin server have 170 the same meaning as in the HTTP/1.1 specification. 172 The terms request-host and request-URI refer to the values the user 173 agent would send to the server as, respectively, the host (but not 174 port) and abs_path portions of the absoluteURI (http_URL) of the HTTP 175 Request-Line. 177 3. Overview 179 We outline here a way for an origin server to send state information 180 to a user agent, and for the user agent to return the state 181 information to the origin server. 183 To initiate a session, the origin server includes a Set-Cookie header 184 in an HTTP response. (Note that "session" here does not refer to a 185 persistent network connection but to a logical session created from 186 HTTP requests and responses. The presence or absence of a persistent 187 connection should have no effect on the use of cookie-derived 188 sessions). 190 The user agent returns a Cookie request header to the origin server 191 if it chooses to continue a session. The Cookie header contains a 192 number of cookies the user agent received in previous Set-Cookie 193 headers. The origin server MAY ignore the Cookie header or use the 194 header to determine the current state of the session. The origin 195 server MAY send the user agent a Set-Cookie response header with the 196 same or different information, or it MAY send no Set-Cookie header at 197 all. 199 Servers MAY return a Set-Cookie response header with any response. 200 User agents SHOULD send a Cookie request header, subject to other 201 rules detailed below, with every request. 203 An origin server MAY include multiple Set-Cookie header fields in a 204 single response. Note that an intervening gateway MUST NOT fold 205 multiple Set-Cookie header fields into a single header field. 207 3.1. Examples 209 [TODO: Put some examples here. 211 4. A Well-Behaved Profile 213 This section describes the syntax and semantics of a well-behaved 214 profile of the protocol. Servers SHOULD use the profile described in 215 this section, both to maximize interoperability with existing user 216 agents and because a future version of the cookie protocol could 217 remove support for some of the most esoteric aspects of the protocol. 218 User agents, however, MUST implement the full protocol to ensure 219 interoperability with servers making use of the full protocol. 221 4.1. Set-Cookie 223 The Set-Cookie header is used to send cookies from the server to the 224 user agent. 226 4.1.1. Syntax 228 Informally, the Set-Cookie response header comprises the token Set- 229 Cookie:, followed by a cookie. Each cookie begins with a name-value- 230 pair, followed by zero or more attribute-value pairs. Servers SHOULD 231 NOT send Set-Cookie headers that fail to conform to the following 232 grammar: 234 set-cookie-header = "Set-Cookie:" OWS set-cookie-string OWS 235 set-cookie-string = cookie-pair *( ";" cookie-av ) 236 cookie-pair = cookie-name "=" cookie-value 237 cookie-name = token 238 cookie-value = token 239 token = 241 cookie-av = expires-av / domain-av / path-av / 242 secure-av / httponly-av 243 expires-av = "Expires" "=" sane-cookie-date 244 sane-cookie-date = 245 domain-av = "Domain" "=" domain-value 246 domain-value = token 247 path-av = "Path" "=" path-value 248 path-value = 249 secure-av = "Secure" 250 httponly-av = "HttpOnly" 252 Servers SHOULD NOT include two attributes with the same name. 254 The cookie-value is opaque to the user agent and MAY be anything the 255 origin server chooses to send. "Opaque" implies that the content is 256 of interest and relevance only to the origin server. The content is, 257 in fact, readable by anyone who examines the Set-Cookie header. 259 To maximize compatibility with user agents, servers that wish to 260 store non-ASCII data in a cookie-value SHOULD encode that data using 261 a printable ASCII encoding, such as base64. 263 NOTE: The syntax above allows whitespace between the attribute and 264 the U+003D ("=") character. Servers wishing to interoperate with 265 some legacy user agents might wish to elide this whitespace. 267 4.1.2. Semantics (Non-Normative) 269 This section describes a simplified semantics of the Set-Cookie 270 header. These semantics are detailed enough to be useful for 271 understanding the most common uses of the cookie protocol. The full 272 semantics are described in Section 5. 274 When the user agent receives a Set-Cookie header, the user agent 275 stores the cookie in its cookie store. When the user agent 276 subsequently makes an HTTP request, the user agent consults its 277 cookie store and includes the applicable, non-expired cookies in the 278 Cookie header. 280 If the cookie store already contains a cookie with the same cookie- 281 name, domain-value, and path-value, the existing cookie is evicted 282 from the cookie store and replaced with the new value. Notice that 283 servers can delete cookies by including an Expires attribute with a 284 value in the past. 286 Unless the cookie's attributes indicate otherwise, the cookie is 287 returned only to the origin server, and it expires at the end of the 288 current session (as defined by the user agent). User agents ignore 289 unrecognized cookie attributes. 291 4.1.2.1. Expires 293 The Expires attribute indicates the maximum lifetime of the cookie, 294 represented as the date and time at which the cookie expires. The 295 user agent is not required to retain the cookie until the specified 296 date has passed. In fact, user agents often evict cookies from the 297 cookie store due to memory pressure or privacy concerns. 299 4.1.2.2. Domain 301 The Domain attribute specifies those hosts for which the cookie will 302 be sent. For example, if the Domain attribute contains the value 303 ".example.com", the user agent will include the cookie in the Cookie 304 header when making HTTP requests to example.com, www.example.com, and 305 www.corp.example.com. (Note that a leading U+002E ("."), if present, 306 is ignored.) If the server omits the Domain attribute, the user 307 agent will return the cookie only to the origin server. 309 WARNING: Some legacy user agents treat an absent Domain attribute 310 as if the Domain attribute were present and contained the current 311 host name. For example, if example.com returns a Set-Cookie 312 header without a Domain attribute, these user agents will send the 313 cookie to www.example.com. 315 The user agent will reject cookies (refuse to store them in the 316 cookie store) unless the Domain attribute specifies a scope for the 317 cookie that would include the origin server. For example, the user 318 agent will accept a Domain attribute of ".example.com" or of 319 ".foo.example.com" from foo.example.com, but the user agent will not 320 accept a Domain attribute of ".bar.example.com" or of 321 ".baz.foo.example.com". 323 NOTE: For security reasons, some user agents are configured to reject 324 Domain attributes that do not correspond to a "registry controlled" 325 domain (or a subdomain of a registry controlled domain). For 326 example, some user agents will reject Domain attributes of ".com". 328 4.1.2.3. Path 330 The Path attribute limits the scope of the cookie to a set of paths. 331 When a cookie has a Path attribute, the user agent will include the 332 cookie in an HTTP request only if the path portion of the Request-URI 333 matches (or is a subdirectory of) the cookie's Path attribute, where 334 the U+002F ("/") character is interpreted as a directory separator. 335 If the server omits the Path attribute, the user agent will use the 336 directory of the Request-URI's path component as the default value. 338 Although seemingly useful for isolating cookies between different 339 paths within a given domain, the Path attribute cannot be relied upon 340 for security for two reasons: First, user agents do not prevent one 341 path from overwriting the cookies for another path. For example, if 342 a response to a request for /foo/bar.html attempts to set a cookie 343 with a Path attribute of "/baz" the user agent will store that cookie 344 in the cookie store. Second, the "same-origin" policy implemented by 345 many user agents does not isolate different paths within an origin. 346 For example, /foo/bar.html can read cookies with a Path attribute of 347 "/baz" because they are within the "same origin". 349 4.1.2.4. Secure 351 The Secure attribute limits the scope of the cookie to "secure" 352 channels (where "secure" is defined by the user agent). When a 353 cookie has the Secure attribute, the user agent will include the 354 cookie in an HTTP request only if the request is transmitted over a 355 secure channel (typically TLS [RFC5234]). 357 Although seemingly useful for protecting cookies from active network 358 attackers, the Secure attribute protects only the cookie's 359 confidentiality. An active network attacker can overwrite Secure 360 cookies from an insecure channel, disrupting the integrity of the 361 cookies. 363 4.1.2.5. HttpOnly 365 The HttpOnly attribute limits the scope of the cookie to HTTP 366 requests. In particular, the attribute instructs the user agent to 367 elide the cookie when providing access to its cookie store via "non- 368 HTTP" APIs (as defined by the user agent). 370 4.2. Cookie 372 4.2.1. Syntax 374 The user agent returns stored cookies to the origin server in the 375 Cookie header. If the server conforms to the requirements in this 376 section, the requirements in the next section will cause the user 377 agent to return a Cookie header that conforms to the following 378 grammar: 380 cookie-header = "Cookie:" OWS cookie-string OWS 381 cookie-string = cookie-pair *( ";" cookie-pair ) 383 4.2.2. Semantics 385 Each cookie-pair represents a cookie stored by the user agent. The 386 cookie-name and the cookie-value are returned verbatim from the 387 corresponding parts of the Set-Cookie header. 389 Notice that the cookie attributes are not returned. In particular, 390 the server cannot determine from the Cookie header alone when a 391 cookie will expire, for which domains the cookie is valid, for which 392 paths the cookie is valid, or whether the cookie was set with the 393 Secure or HttpOnly attributes. 395 The semantics of individual cookies in the Cookie header is not 396 defined by this document. Servers are expected to imbue these 397 cookies with server-specific semantics. 399 5. The Cookie Protocol 401 For historical reasons, the full cookie protocol contains a number of 402 exotic quirks. This section is intended to specify the cookie 403 protocol in enough detail to enable a user agent that implements the 404 protocol precisely as specified to interoperate with existing 405 servers. 407 Conformance requirements phrased as algorithms or specific steps may 408 be implemented in any manner, so long as the end result is 409 equivalent. (In particular, the algorithms defined in this 410 specification are intended to be easy to follow, and not intended to 411 be performant.) 413 5.1. Algorithms 415 This section defines a number of algorithms used by the cookie 416 protocol. 418 5.1.1. Dates 420 The user agent MUST use the following algorithm to *parse a cookie- 421 date*: 423 1. Using the grammar below, divide the cookie-date into date-tokens. 425 cookie-date = *delimiter date-token-list *delimiter 426 date-token-list = date-token *( 1*delimiter date-token ) 427 delimiter = %x09 / %x20 / %x21 / %x22 / %x23 / %x24 / 428 %x25 / %x26 / %x27 / %x28 / %x29 / %x2A / 429 %x2B / %x2C / %x2D / %x2E / %x2F / %x3B / 430 %x3C / %x3D / %x3E / %x3F / %x40 / %x5B / 431 %x5C / %x5D / %x5E / %x5F / %x60 / %x7B / 432 %x7C / %x7D / %x7E 433 date-token = day-of-month / month / year / time / mystery 434 day-of-month = 2DIGIT / DIGIT 435 month = "jan" [ mystery ] / "feb" [ mystery ] / 436 "mar" [ mystery ] / "apr" [ mystery ] / 437 "may" [ mystery ] / "jun" [ mystery ] / 438 "jul" [ mystery ] / "aug" [ mystery ] / 439 "sep" [ mystery ] / "oct" [ mystery ] / 440 "nov" [ mystery ] / "dec" [ mystery ] 441 year = 5DIGIT / 4DIGIT / 3DIGIT / 2DIGIT / DIGIT 442 time = 2DIGIT ":" 2DIGIT ":" 2DIGIT 443 mystery = 444 2. Process each date-token sequentially in the order the date-tokens 445 appear in the cookie-date: 447 1. If the found-day-of-month flag is not set and the date-token 448 matches the day-of-month production, set the found-day-of- 449 month flag and set the day-of-month-value to the number 450 denoted by the date-token. Skip the remaining sub-steps and 451 continue to the next date-token. 453 2. If the found-month flag is not set and the date-token matches 454 the month production, set the found-month flag and set the 455 month-value to the month denoted by the date-token. Skip the 456 remaining sub-steps and continue to the next date-token. 458 3. If the found-year flag is not set and the date-token matches 459 the year production, set the found-year flag and set the 460 year-value to the number denoted by the date-token. Skip the 461 remaining sub-steps and continue to the next date-token. 463 4. If the found-time flag is not set and the token matches the 464 time production, set the found-time flag and set the hour- 465 value, minute-value, and second-value to the numbers denoted 466 by the digits in the date-token, respectively. Skip the 467 remaining sub-steps and continue to the next date-token. 469 3. Abort these steps and *fail to parse* if 471 * at least one of the found-day-of-month, found-month, found- 472 year, or found-time flags is not set, 474 * the day-of-month-value is less than 1 or greater than 31, 476 * the year-value is less than 1601 or greater than 30827, 478 * the hour-value is greater than 23, 480 * the minute-value is greater than 59, or 482 * the second-value is greater than 59. 484 4. If the year-value is greater than 68 and less than 100, increment 485 the year-value by 1900. 487 5. If the year-value is greater than or equal to 0 and less than 69, 488 increment the year-value by 2000. 490 6. Let the parsed-cookie-date be the date whose day-of-month, month, 491 year, hour, minute, and second (in GMT) are the day-of-month- 492 value, the month-value, the year-value, the hour-value, the 493 minute-value, and the second-value, respectively. 495 7. Return the parsed-cookie-date as the result of this algorithm. 497 5.1.2. Domains 499 A *canonicalized* host-name is the host-name converted to lower case. 501 A request-host *domain-matches* a cookie-domain if at least one of 502 the following conditions hold: 504 o The cookie-domain and the canonicalized request-host are 505 identical. 507 o The cookie-domain is a suffix of the canonicalized request-host, 508 the last character of the canonicalized request-host that is not 509 included in the cookie-domain is a U+002E (".") character, and 510 request-host is a host name (i.e., not an IP address). [TODO: Is 511 this the right way to spec this???] 513 5.1.3. Paths 515 The user agent MUST use the following algorithm to compute the 516 *default-path* of a cookie: 518 1. Let uri-path be the path portion of the Request-URI. 520 2. If the first character of the uri-path is not a U+002F ("/") 521 character, output U+002F ("/") and skip the remaining steps. 523 3. If the uri-path contains only a single U+002F ("/") character, 524 output U+002F ("/") and skip the remaining steps. 526 4. Output the characters of the uri-path from the first character up 527 to, but not including, the right-most U+002F ("/"). 529 A request-path *path-matches* a cookie-path if at least one of the 530 following conditions hold: [TODO: This isn't exactly what IE or 531 Firefox does.] 533 o The cookie-path and the request-path are identical. 535 o The cookie-path is a prefix of the request-path and the last 536 character of the cookie-path is U+002F ("/"). 538 o The cookie-path is a prefix of the request-path and the first 539 character of the request-path that is not included in the cookie- 540 path is a U+002F ("/") character. 542 5.2. The Set-Cookie Header 544 When a user agent receives a Set-Cookie header in an HTTP response, 545 the user agent *receives a set-cookie-string* consisting of the value 546 of the header. 548 A user agent MUST use the following algorithm to parse set-cookie- 549 strings: 551 1. If the set-cookie-string is empty or consists entirely of WSP 552 characters, the user agent MAY ignore the set-cookie-string 553 entirely. 555 2. If the set-cookie-string contains a U+003B (";") character: 557 The name-value-pair string consists of the characters up to, 558 but not including, the first U+003B (";"), and the unparsed- 559 attributes consist of the remainder of the set-cookie-string 560 (including the U+003B (";") in question). 562 Otherwise: 564 The name-value-pair string consists of all the characters 565 contained in the set-cookie-string, and the unparsed- 566 attributes is the empty string. 568 3. If the name-value-pair string contains a U+003D ("=") character: 570 The (possibly empty) name string consists of the characters up 571 to, but not including, the first U+003D ("=") character, and 572 the (possibly empty) value string consists of the characters 573 after the first U+003D ("=") character. 575 Otherwise: 577 The name string is empty, and the value string consists of the 578 entire name-value-pair string. 580 4. Remove any leading or trailing WSP characters from the name 581 string and the value string. 583 5. The cookie-name is the name string, and the cookie-value is the 584 value string. 586 The user agent MUST use the following algorithm to parse the 587 unparsed-attributes: 589 1. If the unparsed-attributes string is empty, skip the rest of 590 these steps. 592 2. Consume the first character of the unparsed-attributes (which 593 will be a U+003B (";") character). 595 3. If the remaining unparsed-attributes contains a U+003B (";") 596 character: 598 Consume the characters of the unparsed-attributes up to, but 599 not including, the first U+003B (";") character. 601 Otherwise: 603 Consume the remainder of the unparsed-attributes. 605 Let the cookie-av string be the characters consumed in this step. 607 4. If the cookie-av string contains a U+003D ("=") character: 609 The (possibly empty) attribute-name string consists of the 610 characters up to, but not including, the first U+003D ("=") 611 character, and the (possibly empty) attribute-value string 612 consists of the characters after the first U+003D ("=") 613 character. 615 Otherwise: 617 The attribute-name string consists of the entire cookie-av 618 string, and the attribute-value string is empty. (Note that 619 this step differs from the analogous step when parsing the 620 name-value-pair string.) 622 5. Remove any leading or trailing WSP characters from the attribute- 623 name string and the attribute-value string. 625 6. Process the attribute-name and attribute-value according to the 626 requirements in the following subsections. 628 7. Return to Step 1. 630 When the user agent finishes parsing the set-cookie-string, the user 631 agent *receives a cookie* from the Request-URI with name cookie-name, 632 value cookie-value, and attributes cookie-attribute-list. 634 5.2.1. The Max-Age Attribute 636 If the attribute-name case-insensitively matches the string "Max- 637 Age", the user agent MUST process the cookie-av as follows. 639 If the first character of the attribute-value is not a DIGIT or a "-" 640 character, ignore the cookie-av. 642 If the remainder of attribute-value contains a non-DIGIT character, 643 ignore the cookie-av. 645 Let delta-seconds be the attribute-value converted to an integer. 647 If delta-seconds is less than or equal to zero (0), let expiry-time 648 be the current date and time. Otherwise, let the expiry-time be the 649 current date and time plus delta-seconds seconds. 651 Append an attribute to the cookie-attribute-list with an attribute- 652 name of Expires (note the name conversion) and an attribute-value of 653 expiry-time. 655 5.2.2. The Expires Attribute 657 If the attribute-name case-insensitively matches the string 658 "Expires", the user agent MUST process the cookie-av as follows. 660 Let the parsed-cookie-date be the result of parsing the attribute- 661 value as cookie-date. 663 If the attribute-value failed to parse as a cookie date, ignore the 664 cookie-av. 666 If the user agent received the set-cookie-string from an HTTP 667 response that contains a Date header field and the contents of the 668 last Date header field successfully parse as a cookie-date: 670 Let server-date be the date obtained by parsing the contents of 671 the last Date header field as a cookie-date. 673 Let delta-seconds be the number of seconds between the server-date 674 and the parsed-cookie-date (i.e., parsed-cookie-date - server- 675 date). 677 Let the expiry-time be the current date and time plus delta- 678 seconds seconds. 680 Otherwise: 682 Let the expiry-time be the parsed-cookie-date. 684 If the expiry-time is later than the last date the user agent can 685 represent, the user agent MAY replace the expiry-time with the last 686 representable date. 688 If the expiry-time is earlier than the first date the user agent can 689 represent, the user agent MAY replace the expiry-time with the first 690 representable date. 692 Append an attribute to the cookie-attribute-list with an attribute- 693 name of Expires and an attribute-value of expiry-time. 695 5.2.3. The Domain Attribute 697 If the attribute-name case-insensitively matches the string "Domain", 698 the user agent MUST process the cookie-av as follows. 700 If the attribute-value is empty, the behavior is undefined. However, 701 user agent SHOULD ignore the cookie-av entirely. 703 If the first character of the attribute-value string is U+002E ("."): 705 Let cookie-domain be the attribute-value without the leading 706 U+002E (".") character. 708 Otherwise: 710 Let cookie-domain be the entire attribute-value. 712 Convert the cookie-domain to lower case. 714 [TODO: Test ".127.0.0.1" and "127.0.0.1"] 716 Append an attribute to the cookie-attribute-list with an attribute- 717 name of Domain and an attribute-value of cookie-domain. 719 5.2.4. The Path Attribute 721 If the attribute-name case-insensitively matches the string "Path", 722 the user agent MUST process the cookie-av as follows. 724 If the attribute-value is empty or if the first character of the 725 attribute-value is not U+002F ("/"): 727 Let cookie-path be the default-path. [TODO: We need more tests 728 for this, including with " characters and with multiple Path 729 attributes.] 731 Otherwise: 733 Let cookie-path be the attribute-value. 735 Append an attribute to the cookie-attribute-list with an attribute- 736 name of Path and an attribute-value of cookie-path. 738 5.2.5. The Secure Attribute 740 If the attribute-name case-insensitively matches the string "Secure", 741 the user agent MUST append an attribute to the cookie-attribute-list 742 with an attribute-name of Secure and an empty attribute-value. 744 5.2.6. The HttpOnly Attribute 746 If the attribute-name case-insensitively matches the string 747 "HttpOnly", the user agent MUST append an attribute to the cookie- 748 attribute-list with an attribute-name of Secure and an empty 749 attribute-value. 751 5.3. Storage Model 753 When the user agent receives a cookie, the user agent SHOULD record 754 the cookie in its cookie store as follows. 756 A user agent MAY ignore a received cookie in its entirety if the user 757 agent is configured to block receiving cookies. For example, the 758 user agent might wish to block receiving cookies from "third-party" 759 responses. 761 The user agent stores the following fields about each cookie: name, 762 value, expiry-time, domain, path, creation-time, last-access-time, 763 persistent-flag, host-only-flag, secure-only-flag, and http-only- 764 flag. 766 When the user agent receives a cookie from a Request-URI with name 767 cookie-name, value cookie-value, and attributes cookie-attribute- 768 list, the user agent MUST process the cookie as follows: 770 1. Create a new cookie with name cookie-name, value cookie-value. 771 Set the creation-time and the last-access-time to the current 772 date and time. 774 2. If the cookie-attribute-list contains an attribute with an 775 attribute-name of "Expires": 777 Set the cookie's persistent-flag to true. 779 Set the cookie's expiry-time to attribute-value of the last 780 attribute in the cookie-attribute-list with an attribute-name 781 of "Expires". [TODO: Test that this really works when mixing 782 Max-Age and Expires.] 784 Otherwise: 786 Set the cookie's persistent-flag to false. 788 Set the cookie's expiry-time to the latest representable 789 date. 791 3. If the cookie-attribute-list contains an attribute with an 792 attribute-name of "Domain": 794 Let the domain-attribute be the attribute-value of the last 795 attribute in the cookie-attribute-list with an attribute-name 796 of "Domain". 798 Otherwise: 800 Let the domain-attribute be the empty string. 802 4. If the user agent is configured to use a "public suffix" list 803 and the domain-attribute is a public suffix: 805 If the domain-attribute is identical to the canonicalized 806 Request-URI's host: 808 Let the domain-attribute be the empty string. 810 Otherwise: 812 Ignore the cookie entirely and abort these steps 814 NOTE: A "public suffix" is a domain that is controlled by a 815 public registry, such as "com", "co.uk", and "pvt.k12.wy.us". 816 This step is essential for preventing attacker.com from 817 disrupting the integrity of example.com by setting a cookie 818 with a Domain attribute of "com". Unfortunately, the set of 819 public suffixes (also known as "registry controlled domains") 820 changes over time. If feasible, user agents SHOULD use an 821 up-to-date public suffix list, such as the one maintained by 822 the Mozilla project at http://publicsuffix.org/. 824 5. If the domain-attribute is non-empty: 826 If the Request-URI's host does not domain-match the domain- 827 attribute, ignore the cookie entirely and abort these steps. 829 Set the cookie's host-only-flag to false. 831 Set the cookie's domain to the domain-attribute. 833 Otherwise: 835 Set the cookie's host-only-flag to true. 837 Set the cookie's domain to the host of the Request-URI. 839 6. If the cookie-attribute-list contains an attribute with an 840 attribute-name of "Path", set the cookie's path to attribute- 841 value of the last attribute in the cookie-attribute-list with an 842 attribute-name of "Path". Otherwise, set cookie's path to the 843 default-path of the Request-URI. 845 7. If the cookie-attribute-list contains an attribute with an 846 attribute-name of "Secure", set the cookie's secure-only-flag to 847 true. Otherwise, set cookie's secure-only-flag to false. 849 8. If the cookie-attribute-list contains an attribute with an 850 attribute-name of "HttpOnly", set the cookie's http-only-flag to 851 true. Otherwise, set cookie's http-only-flag to false. 853 9. Remove from the cookie store all cookies that share the same 854 name, domain, path, and host-only-flag as the newly created 855 cookie. [TODO: Validate this list!] [TODO: There's some funny 856 business around http-only here.] 858 10. If the cookie's name and value are both empty, abort these 859 steps. 861 11. If the cookie's expiry-time is not in the future, abort these 862 steps. 864 12. Insert the newly created cookie into the cookie store. 866 The user agent MUST evict a cookie from the cookie store if, at any 867 time, a cookie exists in the cookie store with an expiry date in the 868 past. 870 The user agent MAY evict a cookie from the cookie store if the number 871 of cookies sharing a domain field exceeds some predetermined upper 872 bound (such as 50 cookies). 874 The user agent MAY evict a cookie from the cookie store if the cookie 875 store exceeds some predetermined upper bound (such as 3000 cookies). 877 When the user agent evicts a cookie from the cookie store, the user 878 agent MUST evict cookies in the following priority order: 880 1. Cookies with an expiry date in the past. 882 2. Cookies that share a domain field with more than a predetermined 883 number of other cookies. 885 3. All cookies. 887 If two cookies have the same removal priority, the user agent MUST 888 evict the cookie with the least recent last-access date first. 890 When "the current session is over" (as defined by the user agent), 891 the user agent MUST remove from the cookie store all cookies with the 892 persistent-flag set to false. 894 5.4. The Cookie Header 896 When the user agent generates an HTTP request, the user agent SHOULD 897 attach exactly one HTTP header named Cookie if the cookie-string 898 (defined below) for the Request-URI is non-empty. 900 A user agent MAY elide the Cookie header in its entirety if the user 901 agent is configured to block sending cookies. For example, the user 902 agent might wish to block sending cookies during "third-party" 903 requests. 905 The user agent MUST use the following algorithm to compute the 906 cookie-string from a cookie store and a Request-URI: 908 1. Let cookie-list be the set of cookies from the cookie store that 909 meet all of the following requirements: 911 * Let request-host be the Request-URI's host. Either: 913 The cookie's host-only-flag is true and the canonicalized 914 request-host is identical to the cookie's domain. 916 Or: 918 The cookie's host-only-flag is false and the request-host 919 domain-matches cookie's domain. 921 * The Request-URI's path patch-matches cookie's path. 923 * If the cookie's secure-only field is true, then the Request- 924 URI's scheme must denote a "secure" protocol (as defined by 925 the user agent). 927 NOTE: The notion of a "secure" protocol is not defined by 928 this document. Typically, user agents consider a protocol 929 secure if the protocol makes use of transport-layer 930 security, such as TLS. For example, most user agents 931 consider "https" to be a scheme that denotes a secure 932 protocol. 934 * If the cookie's http-only field is true, then exclude the 935 cookie unless the cookie-string is being generated for an 936 "HTTP" API (as defined by the user agent). 938 2. Sort the cookie-list in the following order: 940 * Cookies with longer paths are listed before cookies with 941 shorter paths. 943 * Among cookies that have equal length path fields, cookies with 944 earlier creation-times are listed before cookies with later 945 creation-times. 947 3. Update the last-access-time of each cookie in the cookie-list to 948 the current date and time. 950 4. Serialize the cookie-list into a cookie-string by processing each 951 cookie in the cookie-list in order: 953 1. If the cookie's name is non-empty, output the cookie's name 954 followed by the U+003D ("=") character. 956 2. Output the cookie's value. 958 3. If there is an unprocessed cookie in the cookie-list, output 959 the characters U+003B and U+0020 ("; "). 961 6. Implementation Considerations 963 6.1. Limits 965 Practical user agent implementations have limits on the number and 966 size of cookies that they can store. General-use user agents SHOULD 967 provide each of the following minimum capabilities: 969 o At least 4096 bytes per cookie (as measured by the sum of the 970 length of the cookie's name, value, and attributes). 972 o At least 50 cookies per domain. 974 o At least 3000 cookies total. 976 Servers SHOULD use as few and as small cookies as possible to avoid 977 reaching these implementation limits and to avoid network latency due 978 to the Cookie header being included in every request. 980 Servers should gracefully degrade if the user agent fails to return 981 one or more cookies in the Cookie header because the user agent might 982 evict any cookie at any time on orders from the user. 984 6.2. Application Programmer Interfaces 986 One reason the cookie protocol uses such an esoteric syntax is 987 because many platforms (both in servers and user agents) provide 988 string-based application programmer interfaces (APIs), requiring 989 application-layer programmers to generate and parse the syntax used 990 by the cookie protocol. 992 Instead of providing string-based APIs to the cookie protocols, 993 implementations would be well-served by providing more semantic APIs. 994 It is beyond the scope of this document to recommend specific API 995 designs, but there are clear benefits to accepting a abstract "Date" 996 object instead of a serialized date string. 998 7. Security Considerations 1000 7.1. General Recommendations 1002 The cookie protocol is NOT RECOMMENDED for new applications. 1004 For applications that do use the cookie protocol, servers SHOULD NOT 1005 rely upon cookies for security. 1007 For servers that do use cookies for security, servers SHOULD use a 1008 redundant form of authentication, such as HTTP authentication or TLS 1009 client certificates. 1011 7.2. Ambient Authority 1013 A server that uses cookies to authenticate users can suffer security 1014 vulnerabilities because some user agents let remote parties issue 1015 HTTP requests from the user agent (e.g., via HTTP redirects and HTML 1016 forms). When issuing those requests, user agent attaches cookies 1017 even if the entity does not know the contents of the cookies, 1018 possibly letting the remote entity exercise authority at an unwary 1019 server. User agents can mitigate this issue to some degree by 1020 providing APIs for suppressing the Cookie header on outgoing 1021 requests. 1023 Although this security concern goes by a number of names (e.g., 1024 cross-site scripting and cross-site request forgery), the issue stems 1025 from cookies being a form of ambient authority. Cookies encourage 1026 server operators to separate designation (in the form of URLs) from 1027 authorization (in the form of cookies). Disentangling designation 1028 and authorization can cause the server and its clients to become 1029 confused deputies and undertake undesirable actions. 1031 Instead of using cookies for authorization, server operators might 1032 wish to consider entangling designation and authorization by treating 1033 URLs as object-capabilities. Instead of storing secrets in cookies, 1034 this approach stores secrets in URLs, requiring the remote entity to 1035 supply the secret itself. ALthough this approach is not a panacea, 1036 judicious use of these principles can lead to more robust security. 1038 7.3. Clear Text 1040 Unless sent over a secure channel (such as TLS), the information in 1041 the Set-Cookie and Cookie headers is transmitted in the clear. 1043 1. All sensitive information conveyed in these headers is exposed to 1044 an eavesdropper. 1046 2. A malicious intermediary could alter the headers as they travel 1047 in either direction, with unpredictable results. 1049 3. A malicious client could alter the Cookie header before 1050 transmission, with unpredictable results. 1052 Servers SHOULD encrypt and sign their cookies when transmitting them 1053 to the user agent (even when sending the cookies over a secure 1054 channel). However, encrypting and signing cookies does not prevent 1055 an attacker from transplanting a cookie from one user agent to 1056 another. 1058 In addition to encrypting and signing the contents of every cookie, 1059 servers that require a higher level of security SHOULD use the cookie 1060 protocol only over a secure channel. 1062 7.4. Weak Confidentiality 1064 Cookies do not provide isolation by port. If a cookie is readable by 1065 a service running on one port, the cookie is also readable by a 1066 service running on another port of the same server. If a cookie is 1067 writable by a service on one port, the cookie is also writable by a 1068 service running on another port of the same server. For this reason, 1069 servers SHOULD NOT both run mutually distrusting services on 1070 different ports of the same host and use cookies to store security- 1071 sensitive information. 1073 Cookies do not provide isolation by scheme. Although most commonly 1074 used with the http and https schemes, the cookies for a given host 1075 are also available to other schemes, such as ftp and gopher. This 1076 lack of isolation is most easily seen when a user agent retrieves a 1077 URI with a gopher scheme via HTTP, but the lack of isolation by 1078 scheme is also apparent via non-HTTP APIs that permit access to 1079 cookies, such as HTML's document.cookie API. 1081 7.5. Weak Integrity 1083 Cookies do not provide integrity guarantees for sibling domains (and 1084 their subdomains). For example, consider foo.example.com and 1085 bar.example.com. The foo.example.com server can set a cookie with a 1086 Domain attribute of ".example.com", and the user agent will include 1087 that cookie in HTTP requests to bar.example.com. In the worst case, 1088 bar.example.com will be unable to distinguish this cookie from a 1089 cookie it set itself. The foo.example.com server might be able to 1090 leverage this ability to mount an attack against bar.example.com. 1092 Similarly, an active network attacker can inject cookies into the 1093 Cookie header sent to https://example.com/ by impersonating a 1094 response from http://example.com/ and injecting a Set-Cookie header. 1095 The HTTPS server at example.com will be unable to distinguish these 1096 cookies from cookies that it set itself in an HTTPS response. An 1097 active network attacker might be able to leverage this ability to 1098 mount an attack against example.com even if example.com uses HTTPS 1099 exclusively. 1101 Servers can partially mitigate these attacks by encrypting and 1102 signing their cookies. However, using cryptography does not mitigate 1103 the issue completely because an attacker can replay a cookie he or 1104 she received from the authentic example.com server in the user's 1105 session, with unpredictable results. 1107 7.6. Reliance on DNS 1109 The cookie protocol relies upon the Domain Name System (DNS) for 1110 security. If the DNS is partially or fully compromised, the cookie 1111 protocol might fail to provide the security properties required by 1112 applications. 1114 8. Normative References 1116 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1117 Requirement Levels", BCP 14, RFC 2119, March 1997. 1119 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1120 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1121 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1123 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1124 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1126 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1127 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1129 Appendix A. Acknowledgements 1131 This document borrows heavily from RFC 2109. [TODO: Figure out the 1132 proper way to credit the authors of RFC 2109.] 1134 Author's Address 1136 Adam Barth 1137 University of California, Berkeley 1139 Email: abarth@eecs.berkeley.edu 1140 URI: http://www.adambarth.com/