idnits 2.17.1 draft-ietf-httpstate-cookie-23.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. 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 abstract seems to contain references ([RFC2965]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. 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 (March 1, 2011) is 4803 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) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 3490 (Obsoleted by RFC 5890, RFC 5891) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' -- Obsolete informational reference (is this intentional?): RFC 2109 (Obsoleted by RFC 2965) -- Obsolete informational reference (is this intentional?): RFC 2965 (Obsoleted by RFC 6265) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 5 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: 2965 (if approved) March 1, 2011 5 Intended status: Standards Track 6 Expires: September 2, 2011 8 HTTP State Management Mechanism 9 draft-ietf-httpstate-cookie-23 11 Abstract 13 This document defines the HTTP Cookie and Set-Cookie header fields. 14 These header fields can be used by HTTP servers to store state 15 (called cookies) at HTTP user agents, letting the servers maintain a 16 stateful session over the mostly stateless HTTP protocol. Although 17 cookies have many historical infelicities that degrade their security 18 and privacy, the Cookie and Set-Cookie header fields are widely used 19 on the Internet. This document obsoletes [RFC2965]. 21 Editorial Note (To be removed by RFC Editor) 23 If you have suggestions for improving this document, please send 24 email to . Suggestions with test cases 25 are especially appreciated. Further Working Group information is 26 available from . 28 Status of this Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on September 2, 2011. 45 Copyright Notice 47 Copyright (c) 2011 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 This document may contain material from IETF Documents or IETF 61 Contributions published or made publicly available before November 62 10, 2008. The person(s) controlling the copyright in some of this 63 material may not have granted the IETF Trust the right to allow 64 modifications of such material outside the IETF Standards Process. 65 Without obtaining an adequate license from the person(s) controlling 66 the copyright in such materials, this document may not be modified 67 outside the IETF Standards Process, and derivative works of it may 68 not be created outside the IETF Standards Process, except to format 69 it for publication as an RFC or to translate it into languages other 70 than English. 72 Table of Contents 74 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 75 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 7 76 2.1. Conformance Criteria . . . . . . . . . . . . . . . . . . . 7 77 2.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 7 78 2.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 79 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 80 3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 9 81 4. Server Requirements . . . . . . . . . . . . . . . . . . . . . 12 82 4.1. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . . 12 83 4.1.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . 12 84 4.1.2. Semantics (Non-Normative) . . . . . . . . . . . . . . 13 85 4.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . . 16 86 4.2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . 16 87 4.2.2. Semantics . . . . . . . . . . . . . . . . . . . . . . 16 88 5. User Agent Requirements . . . . . . . . . . . . . . . . . . . 18 89 5.1. Subcomponent Algorithms . . . . . . . . . . . . . . . . . 18 90 5.1.1. Dates . . . . . . . . . . . . . . . . . . . . . . . . 18 91 5.1.2. Canonicalized host names . . . . . . . . . . . . . . . 20 92 5.1.3. Domain matching . . . . . . . . . . . . . . . . . . . 20 93 5.1.4. Paths and path-match . . . . . . . . . . . . . . . . . 20 94 5.2. The Set-Cookie Header . . . . . . . . . . . . . . . . . . 21 95 5.2.1. The Expires Attribute . . . . . . . . . . . . . . . . 23 96 5.2.2. The Max-Age Attribute . . . . . . . . . . . . . . . . 24 97 5.2.3. The Domain Attribute . . . . . . . . . . . . . . . . . 24 98 5.2.4. The Path Attribute . . . . . . . . . . . . . . . . . . 25 99 5.2.5. The Secure Attribute . . . . . . . . . . . . . . . . . 25 100 5.2.6. The HttpOnly Attribute . . . . . . . . . . . . . . . . 25 101 5.3. Storage Model . . . . . . . . . . . . . . . . . . . . . . 25 102 5.4. The Cookie Header . . . . . . . . . . . . . . . . . . . . 29 103 6. Implementation Considerations . . . . . . . . . . . . . . . . 31 104 6.1. Limits . . . . . . . . . . . . . . . . . . . . . . . . . . 31 105 6.2. Application Programming Interfaces . . . . . . . . . . . . 31 106 6.3. IDNA dependency and migration . . . . . . . . . . . . . . 31 107 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 33 108 7.1. Third-Party Cookies . . . . . . . . . . . . . . . . . . . 33 109 7.2. User Controls . . . . . . . . . . . . . . . . . . . . . . 33 110 7.3. Expiration Dates . . . . . . . . . . . . . . . . . . . . . 34 111 8. Security Considerations . . . . . . . . . . . . . . . . . . . 35 112 8.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 35 113 8.2. Ambient Authority . . . . . . . . . . . . . . . . . . . . 35 114 8.3. Clear Text . . . . . . . . . . . . . . . . . . . . . . . . 36 115 8.4. Session Identifiers . . . . . . . . . . . . . . . . . . . 36 116 8.5. Weak Confidentiality . . . . . . . . . . . . . . . . . . . 37 117 8.6. Weak Integrity . . . . . . . . . . . . . . . . . . . . . . 38 118 8.7. Reliance on DNS . . . . . . . . . . . . . . . . . . . . . 38 119 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 120 9.1. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . . 39 121 9.2. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . . 39 122 9.3. Cookie2 . . . . . . . . . . . . . . . . . . . . . . . . . 39 123 9.4. Set-Cookie2 . . . . . . . . . . . . . . . . . . . . . . . 39 124 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 41 125 10.1. Normative References . . . . . . . . . . . . . . . . . . . 41 126 10.2. Informative References . . . . . . . . . . . . . . . . . . 41 127 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 43 128 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 44 130 1. Introduction 132 This document defines the HTTP Cookie and Set-Cookie header fields. 133 Using the Set-Cookie header field, an HTTP server can pass name/value 134 pairs and associated metadata (called cookies) to a user agent. When 135 the user agent makes subsequent requests to the server, the user 136 agent uses the metadata and other information to determine whether to 137 return the name/value pairs in the Cookie header. 139 Although simple on their surface, cookies have a number of 140 complexities. For example, the server indicates a scope for each 141 cookie when sending it to the user agent. The scope indicates the 142 maximum amount of time the user agent should return the cookie, the 143 servers to which the user agent should return the cookie, and the URI 144 schemes for which the cookie is applicable. 146 For historical reasons, cookies contain a number of security and 147 privacy infelicities. For example, a server can indicate that a 148 given cookie is intended for "secure" connections, but the Secure 149 attribute does not provide integrity in the presence of an active 150 network attacker. Similarly, cookies for a given host are shared 151 across all the ports on that host, even though the usual "same-origin 152 policy" used by web browsers isolates content retrieved via different 153 ports. 155 There are two audiences for this specifications: developers of 156 cookie-generating servers and developers of cookie-consuming user 157 agents. 159 To maximize interoperability with user agents, servers SHOULD limit 160 themselves to the well-behaved profile defined in Section 4 when 161 generating cookies. 163 User agents MUST implement the more liberal processing rules defined 164 in Section 5, in order to maximize interoperability with existing 165 servers that do not conform to the well-behaved profile defined in 166 Section 4. 168 This document specifies the syntax and semantics of these headers as 169 they are actually used on the Internet. In particular, this document 170 does not create new syntax or semantics beyond those in use today. 171 The recommendations for cookie generation provided in Section 4 172 represent a preferred subset of current server behavior, and even the 173 more liberal cookie processing algorithm provided in Section 5 does 174 not recommend all of the syntactic and semantic variations in use 175 today. Where some existing software differs from the recommended 176 protocol in significant ways, the document contains a note explaining 177 the difference. 179 Prior to this document, there were at least three descriptions of 180 cookies: the so-called "Netscape cookie specification" [Netscape], 181 RFC 2109 [RFC2109], and RFC 2965 [RFC2965]. However, none of these 182 documents describe how the Cookie and Set-Cookie headers are actually 183 used on the Internet (see [Kri2001] for historical context). In 184 relation to previous IETF specifications of HTTP state management 185 mechanisms, this document requests the following actions: 187 1. Change the status of [RFC2109] to Historic (it has already been 188 obsoleted by [RFC2965]). 190 2. Change the status of [RFC2965] to Historic. 192 3. Indicate that [RFC2965] is obsoleted by this document. 194 In particular, in moving RFC 2965 to Historic and obsoleting it, this 195 document deprecates the use of the Cookie2 and Set-Cookie2 header 196 fields. 198 2. Conventions 200 2.1. Conformance Criteria 202 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 203 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 204 document are to be interpreted as described in [RFC2119]. 206 Requirements phrased in the imperative as part of algorithms (such as 207 "strip any leading space characters" or "return false and abort these 208 steps") are to be interpreted with the meaning of the key word 209 ("MUST", "SHOULD", "MAY", etc) used in introducing the algorithm. 211 Conformance requirements phrased as algorithms or specific steps can 212 be implemented in any manner, so long as the end result is 213 equivalent. In particular, the algorithms defined in this 214 specification are intended to be easy to understand and are not 215 intended to be performant. 217 2.2. Syntax Notation 219 This specification uses the Augmented Backus-Naur Form (ABNF) 220 notation of [RFC5234]. 222 The following core rules are included by reference, as defined in 223 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 224 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 225 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), NUL (null octet), 226 OCTET (any 8-bit sequence of data except NUL), SP (space), HTAB 227 (horizontal tab), CHAR (any [USASCII] character), VCHAR (any visible 228 [USASCII] character), and WSP (whitespace). 230 The OWS (optional whitespace) rule is used where zero or more linear 231 whitespace characters MAY appear: 233 OWS = *( [ obs-fold ] WSP ) 234 ; "optional" whitespace 235 obs-fold = CRLF 237 OWS SHOULD either not be produced or be produced as a single SP 238 character. 240 2.3. Terminology 242 The terms user agent, client, server, proxy, and origin server have 243 the same meaning as in the HTTP/1.1 specification ([RFC2616], Section 244 1.3). 246 The request-host is the name of the host, as known by the user agent, 247 to which the user agent is sending an HTTP request or is receiving an 248 HTTP response from (i.e., the name of the host to which it sent the 249 corresponding HTTP request). 251 The term request-uri is defined in Section 5.1.2 of [RFC2616]. 253 Two sequences of octets are said to case-insensitively match each 254 other if and only if they are equivalent under the i;ascii-casemap 255 collation defined in [RFC4790]. 257 The term string means a sequence of non-NUL octets. 259 3. Overview 261 This section outlines a way for an origin server to send state 262 information to a user agent and for the user agent to return the 263 state information to the origin server. 265 To store state, the origin server includes a Set-Cookie header in an 266 HTTP response. In subsequent requests, the user agent returns a 267 Cookie request header to the origin server. The Cookie header 268 contains cookies the user agent received in previous Set-Cookie 269 headers. The origin server is free to ignore the Cookie header or 270 use its contents for an application-defined purpose. 272 Origin servers MAY send a Set-Cookie response header with any 273 response. User agents MAY ignore Set-Cookie headers contained in 274 responses with 100-level status codes but MUST process Set-Cookie 275 headers contained in other responses (including responses with 400- 276 and 500-level status codes). An origin server can include multiple 277 Set-Cookie header fields in a single response. The presence of a 278 Cookie or a Set-Cookie header field does not preclude HTTP caches 279 from storing and reusing a response. 281 Origin servers SHOULD NOT fold multiple Set-Cookie header fields into 282 a single header field. The usual mechanism for folding HTTP headers 283 fields (i.e., as defined in [RFC2616]) might change the semantics of 284 the Set-Cookie header field because the %x2C (",") character is used 285 by Set-Cookie in a way that conflicts with such folding. 287 3.1. Examples 289 Using the Set-Cookie header, a server can send the user agent a short 290 string in an HTTP response that the user agent will return in future 291 HTTP requests that are within the scope of the cookie. For example, 292 the server can send the user agent a "session identifier" named SID 293 with the value 31d4d96e407aad42. The user agent then returns the 294 session identifier in subsequent requests. 296 == Server -> User Agent == 298 Set-Cookie: SID=31d4d96e407aad42 300 == User Agent -> Server == 302 Cookie: SID=31d4d96e407aad42 304 The server can alter the default scope of the cookie using the Path 305 and Domain attributes. For example, the server can instruct the user 306 agent to return the cookie to every path and every subdomain of 307 example.com. 309 == Server -> User Agent == 311 Set-Cookie: SID=31d4d96e407aad42; Path=/; Domain=example.com 313 == User Agent -> Server == 315 Cookie: SID=31d4d96e407aad42 317 As shown in the next example, the server can store multiple cookies 318 at the user agent. For example, the server can store a session 319 identifier as well as the user's preferred language by returning two 320 Set-Cookie header fields. Notice that the server uses the Secure and 321 HttpOnly attributes to provide additional security protections for 322 the more-sensitive session identifier (see Section 4.1.2.) 324 == Server -> User Agent == 326 Set-Cookie: SID=31d4d96e407aad42; Path=/; Secure; HttpOnly 327 Set-Cookie: lang=en-US; Path=/; Domain=example.com 329 == User Agent -> Server == 331 Cookie: SID=31d4d96e407aad42; lang=en-US 333 Notice that the Cookie header above contains two cookies, one named 334 SID and one named lang. If the server wishes the user agent to 335 persist the cookie over multiple "sessions" (e.g., user agent 336 restarts), the server can specify an expiration date in the Expires 337 attribute. Note that the user agent might delete the cookie before 338 the expiration date if the user agent's cookie store exceeds its 339 quota or if the user manually deletes the server's cookie. 341 == Server -> User Agent == 343 Set-Cookie: lang=en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT 345 == User Agent -> Server == 347 Cookie: SID=31d4d96e407aad42; lang=en-US 349 Finally, to remove a cookie, the server returns a Set-Cookie header 350 with an expiration date in the past. The server will be successful 351 in removing the cookie only if the Path and the Domain attribute in 352 the Set-Cookie header match the values used when the cookie was 353 created. 355 == Server -> User Agent == 357 Set-Cookie: lang=; Expires=Sun, 06 Nov 1994 08:49:37 GMT 359 == User Agent -> Server == 361 Cookie: SID=31d4d96e407aad42 363 4. Server Requirements 365 This section describes the syntax and semantics of a well-behaved 366 profile of the Cookie and Set-Cookie headers. 368 4.1. Set-Cookie 370 The Set-Cookie HTTP response header is used to send cookies from the 371 server to the user agent. 373 4.1.1. Syntax 375 Informally, the Set-Cookie response header contains the header name 376 "Set-Cookie" followed by a ":" and a cookie. Each cookie begins with 377 a name-value pair, followed by zero or more attribute-value pairs. 378 Servers SHOULD NOT send Set-Cookie headers that fail to conform to 379 the following grammar: 381 set-cookie-header = "Set-Cookie:" SP set-cookie-string 382 set-cookie-string = cookie-pair *( ";" SP cookie-av ) 383 cookie-pair = cookie-name "=" cookie-value 384 cookie-name = token 385 cookie-value = *cookie-octet / ( DQUOTE *cookie-octet DQUOTE ) 386 cookie-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E 387 ; US-ASCII characters excluding CTLs, 388 ; whitespace DQUOTE, comma, semicolon, 389 ; and backslash 390 token = 392 cookie-av = expires-av / max-age-av / domain-av / 393 path-av / secure-av / httponly-av / 394 extension-av 395 expires-av = "Expires=" sane-cookie-date 396 sane-cookie-date = 397 max-age-av = "Max-Age=" non-zero-digit *DIGIT 398 ; In practice, both expires-av and max-age-av 399 ; are limited to dates representable by the 400 ; user agent. 401 non-zero-digit = %x31-39 402 ; digits 1 through 9 403 domain-av = "Domain=" domain-value 404 domain-value = 405 ; defined in [RFC1034], Section 3.5, as 406 ; enhanced by [RFC1123], Section 2.1 407 path-av = "Path=" path-value 408 path-value = 409 secure-av = "Secure" 410 httponly-av = "HttpOnly" 411 extension-av = 413 Note that some of the grammatical terms above reference documents 414 that use different grammatical notations than this document (which 415 uses ABNF from [RFC5234]). 417 The semantics of the cookie-value are not defined by this document. 419 To maximize compatibility with user agents, servers that wish to 420 store arbitrary data in a cookie-value SHOULD encode that data, for 421 example, using Base64 [RFC4648]. 423 The portions of the set-cookie-string produced by the cookie-av term 424 are known as attributes. To maximize compatibility with user agents, 425 servers SHOULD NOT produce two attributes with the same name in the 426 same set-cookie-string. (See Section 5.3 for how user agents handle 427 this case.) 429 Servers SHOULD NOT include more than one Set-Cookie header field in 430 the same response with the same cookie-name. (See Section 5.2 for 431 how user agents handle this case.) 433 If a server sends multiple responses containing Set-Cookie headers 434 concurrently to the user agent (e.g., when communicating with the 435 user agent over multiple sockets), these responses create a "race 436 condition" that can lead to unpredictable behavior. 438 NOTE: Some existing user agents differ on their interpretation of 439 two-digit years. To avoid compatibility issues, servers SHOULD use 440 the rfc1123-date format, which requires a four-digit year. 442 NOTE: Some user agents store and process dates in cookies as 32-bit 443 UNIX time_t values. Implementation bugs in the libraries supporting 444 time_t processing on some systems might cause such user agents to 445 process dates after the year 2038 incorrectly. 447 4.1.2. Semantics (Non-Normative) 449 This section describes a simplified semantics of the Set-Cookie 450 header. These semantics are detailed enough to be useful for 451 understanding the most common uses of cookies by servers. The full 452 semantics are described in Section 5. 454 When the user agent receives a Set-Cookie header, the user agent 455 stores the cookie together with its attributes. Subsequently, when 456 the user agent makes an HTTP request, the user agent includes the 457 applicable, non-expired cookies in the Cookie header. 459 If the user agent receives a new cookie with the same cookie-name, 460 domain-value, and path-value as a cookie that it has already stored, 461 the existing cookie is evicted and replaced with the new cookie. 462 Notice that servers can delete cookies by sending the user agent a 463 new cookie with an Expires attribute with a value in the past. 465 Unless the cookie's attributes indicate otherwise, the cookie is 466 returned only to the origin server (and not, e.g., to any 467 subdomains), and it expires at the end of the current session (as 468 defined by the user agent). User agents ignore unrecognized cookie 469 attributes (but not the entire cookie). 471 4.1.2.1. The Expires Attribute 473 The Expires attribute indicates the maximum lifetime of the cookie, 474 represented as the date and time at which the cookie expires. The 475 user agent is not required to retain the cookie until the specified 476 date has passed. In fact, user agents often evict cookies due to 477 memory pressure or privacy concerns. 479 4.1.2.2. The Max-Age Attribute 481 The Max-Age attribute indicates the maximum lifetime of the cookie, 482 represented as the number of seconds until the cookie expires. The 483 user agent is not required to retain the cookie for the specified 484 duration. In fact, user agents often evict cookies from due to 485 memory pressure or privacy concerns. 487 NOTE: Some existing user agents do not support the Max-Age 488 attribute. User agents that do not support the Max-Age attribute 489 ignore the attribute. 491 If a cookie has both the Max-Age and the Expires attribute, the Max- 492 Age attribute has precedence and controls the expiration date of the 493 cookie. If a cookie has neither the Max-Age nor the Expires 494 attribute, the user agent will retain the cookie until "the current 495 session is over" (as defined by the user agent). 497 4.1.2.3. The Domain Attribute 499 The Domain attribute specifies those hosts to which the cookie will 500 be sent. For example, if the value of the Domain attribute is 501 "example.com", the user agent will include the cookie in the Cookie 502 header when making HTTP requests to example.com, www.example.com, and 503 www.corp.example.com. (Note that a leading %x2E ("."), if present, 504 is ignored even though that character is not permitted, but a 505 trailing %x2E ("."), if present, will cause the user agent to ignore 506 the attribute.) If the server omits the Domain attribute, the user 507 agent will return the cookie only to the origin server. 509 WARNING: Some existing user agents treat an absent Domain 510 attribute as if the Domain attribute were present and contained 511 the current host name. For example, if example.com returns a Set- 512 Cookie header without a Domain attribute, these user agents will 513 erroneously send the cookie to www.example.com as well. 515 The user agent will reject cookies unless the Domain attribute 516 specifies a scope for the cookie that would include the origin 517 server. For example, the user agent will accept a cookie with a 518 Domain attribute of "example.com" or of "foo.example.com" from 519 foo.example.com, but the user agent will not accept a cookie with a 520 Domain attribute of "bar.example.com" or of "baz.foo.example.com". 522 NOTE: For security reasons, many user agents are configured to reject 523 Domain attributes that correspond to "public suffixes". For example, 524 some user agents will reject Domain attributes of "com" or "co.uk". 525 (See Section 5.3 for more information.) 527 4.1.2.4. The Path Attribute 529 The scope of each cookie is limited to a set of paths, controlled by 530 the Path attribute. If the server omits the Path attribute, the user 531 agent will use the "directory" of the request-uri's path component as 532 the default value. (See Section 5.1.4 for more details.) 534 The user agent will include the cookie in an HTTP request only if the 535 path portion of the request-uri matches (or is a subdirectory of) the 536 cookie's Path attribute, where the %x2F ("/") character is 537 interpreted as a directory separator. 539 Although seemingly useful for isolating cookies between different 540 paths within a given host, the Path attribute cannot be relied upon 541 for security (see Section 8). 543 4.1.2.5. The Secure Attribute 545 The Secure attribute limits the scope of the cookie to "secure" 546 channels (where "secure" is defined by the user agent). When a 547 cookie has the Secure attribute, the user agent will include the 548 cookie in an HTTP request only if the request is transmitted over a 549 secure channel (typically HTTP over Transport Layer Security (TLS) 550 [RFC2818]). 552 Although seemingly useful for protecting cookies from active network 553 attackers, the Secure attribute protects only the cookie's 554 confidentiality. An active network attacker can overwrite Secure 555 cookies from an insecure channel, disrupting their integrity (see 556 Section 8.6 for more details). 558 4.1.2.6. The HttpOnly Attribute 560 The HttpOnly attribute limits the scope of the cookie to HTTP 561 requests. In particular, the attribute instructs the user agent to 562 omit the cookie when providing access to cookies via "non-HTTP" APIs 563 (such as a web browser API that exposes cookies to scripts). 565 Note that the HttpOnly attribute is independent of the Secure 566 attribute: a cookie can have both the HttpOnly and the Secure 567 attribute. 569 4.2. Cookie 571 4.2.1. Syntax 573 The user agent sends stored cookies to the origin server in the 574 Cookie header. If the server conforms to the requirements in 575 Section 4.1 (and the user agent conforms to the requirements in 576 Section 5), the user agent will send a Cookie header that conforms to 577 the following grammar: 579 cookie-header = "Cookie:" OWS cookie-string OWS 580 cookie-string = cookie-pair *( ";" SP cookie-pair ) 582 4.2.2. Semantics 584 Each cookie-pair represents a cookie stored by the user agent. The 585 cookie-pair contains the cookie-name and cookie-value the user agent 586 received in the Set-Cookie header. 588 Notice that the cookie attributes are not returned. In particular, 589 the server cannot determine from the Cookie header alone when a 590 cookie will expire, for which hosts the cookie is valid, for which 591 paths the cookie is valid, or whether the cookie was set with the 592 Secure or HttpOnly attributes. 594 The semantics of individual cookies in the Cookie header are not 595 defined by this document. Servers are expected to imbue these 596 cookies with application-specific semantics. 598 Although cookies are serialized linearly in the Cookie header, 599 servers SHOULD NOT rely upon the serialization order. In particular, 600 if the Cookie header contains two cookies with the same name (e.g., 601 that were set with different Path or Domain attributes), servers 602 SHOULD NOT rely upon the order in which these cookies appear in the 603 header. 605 5. User Agent Requirements 607 This section specifies the Cookie and Set-Cookie headers in 608 sufficient detail that a user agent implementing these requirements 609 precisely can interoperate with existing servers (even those that do 610 not conform to the well-behaved profile described in Section 4). 612 A user agent could enforce more restrictions than those specified 613 herein (e.g., for the sake of improved security); however, 614 experiments have shown that such strictness reduces the likelihood 615 that a user agent will be able to interoperate with existing servers. 617 5.1. Subcomponent Algorithms 619 This section defines some algorithms used by user agents to process 620 specific subcomponents of the Cookie and Set-Cookie headers. 622 5.1.1. Dates 624 The user agent MUST use an algorithm equivalent to the following 625 algorithm to parse a cookie-date. Note that the various boolean 626 flags defined as a part of the algorithm (i.e., found-time, found- 627 day-of-month, found-month, found-year) are initially "not set". 629 1. Using the grammar below, divide the cookie-date into date-tokens. 631 cookie-date = *delimiter date-token-list *delimiter 632 date-token-list = date-token *( 1*delimiter date-token ) 633 date-token = 1*non-delimiter 635 delimiter = %x09 / %x20-2F / %x3B-40 / %x5B-60 / %x7B-7E 636 non-delimiter = %x00-08 / %x0A-1F / DIGIT / ":" / ALPHA / %x7F-FF 637 non-digit = %x00-2F / %x3A-FF 639 day-of-month = 1*2DIGIT ( non-digit *OCTET ) 640 month = ( "jan" / "feb" / "mar" / "apr" / 641 "may" / "jun" / "jul" / "aug" / 642 "sep" / "oct" / "nov" / "dec" ) *OCTET 643 year = 2*4DIGIT ( non-digit *OCTET ) 644 time = hms-time ( non-digit *OCTET ) 645 hms-time = time-field ":" time-field ":" time-field 646 time-field = 1*2DIGIT 648 2. Process each date-token sequentially in the order the date-tokens 649 appear in the cookie-date: 651 1. If the found-time flag is not set and the token matches the 652 time production, set the found-time flag and set the hour- 653 value, minute-value, and second-value to the numbers denoted 654 by the digits in the date-token, respectively. Skip the 655 remaining sub-steps and continue to the next date-token. 657 2. If the found-day-of-month flag is not set and the date-token 658 matches the day-of-month production, set the found-day-of- 659 month flag and set the day-of-month-value to the number 660 denoted by the date-token. Skip the remaining sub-steps and 661 continue to the next date-token. 663 3. If the found-month flag is not set and the date-token matches 664 the month production, set the found-month flag and set the 665 month-value to the month denoted by the date-token. Skip the 666 remaining sub-steps and continue to the next date-token. 668 4. If the found-year flag is not set and the date-token matches 669 the year production, set the found-year flag and set the 670 year-value to the number denoted by the date-token. Skip the 671 remaining sub-steps and continue to the next date-token. 673 3. If the year-value is greater than or equal to 70 and less than or 674 equal to 99, increment the year-value by 1900. 676 4. If the year-value is greater than or equal to 0 and less than or 677 equal to 69, increment the year-value by 2000. 679 1. NOTE: Some existing user agents interpret two-digit years 680 differently. 682 5. Abort these steps and fail to parse the cookie-date if 684 * at least one of the found-day-of-month, found-month, found- 685 year, or found-time flags is not set, 687 * the day-of-month-value is less than 1 or greater than 31, 689 * the year-value is less than 1601, 691 * the hour-value is greater than 23, 693 * the minute-value is greater than 59, or 695 * the second-value is greater than 59. 697 (Note that leap seconds cannot be represented in this syntax.) 699 6. Let the parsed-cookie-date be the date whose day-of-month, month, 700 year, hour, minute, and second (in UTC) are the day-of-month- 701 value, the month-value, the year-value, the hour-value, the 702 minute-value, and the second-value, respectively. If no such 703 date exists, abort these steps and fail to parse the cookie-date. 705 7. Return the parsed-cookie-date as the result of this algorithm. 707 5.1.2. Canonicalized host names 709 A canonicalized host name is the string generated by the following 710 algorithm: 712 1. Convert the host name to a sequence of individual domain name 713 labels. 715 2. Convert each label that is not a NR-LDH label, to a A-label (see 716 Section 2.3.2.1 of [RFC5890] for the fomer and latter), or to a 717 "punycode label" (a label resulting from the "ToASCII" conversion 718 in Section 4 of [RFC3490]), as appropriate (see Section 6.3 of 719 this specification). 721 3. Concatentate the resulting labels, separated by a %x2E (".") 722 character. 724 5.1.3. Domain matching 726 A string domain-matches a given domain string if at least one of the 727 following conditions hold: 729 o The domain string and the string are identical. (Note that both 730 the domain string and the string will have been canonicalized to 731 lower case at this point.) 733 o All of the following conditions hold: 735 * The domain string is a suffix of the string. 737 * The last character of the string that is not included in the 738 domain string is a %x2E (".") character. 740 * The string is a host name (i.e., not an IP address). 742 5.1.4. Paths and path-match 744 The user agent MUST use an algorithm equivalent to the following 745 algorithm to compute the default-path of a cookie: 747 1. Let uri-path be the path portion of the request-uri if such a 748 portion exists (and empty otherwise). For example, if the 749 request-uri contains just a path (and optional query string), 750 then the uri-path is that path (without the %x3F ("?") character 751 or query string), and if the request-uri contains a full 752 absoluteURI, the uri-path is the path component of that URI. 754 2. If the uri-path is empty or if the first character of the uri- 755 path is not a %x2F ("/") character, output %x2F ("/") and skip 756 the remaining steps. 758 3. If the uri-path contains only a single %x2F ("/") character, 759 output %x2F ("/") and skip the remaining steps. 761 4. Output the characters of the uri-path from the first character up 762 to, but not including, the right-most %x2F ("/"). 764 A request-path path-matches a given cookie-path if at least one of 765 the following conditions hold: 767 o The cookie-path and the request-path are identical. 769 o The cookie-path is a prefix of the request-path and the last 770 character of the cookie-path is %x2F ("/"). 772 o The cookie-path is a prefix of the request-path and the first 773 character of the request-path that is not included in the cookie- 774 path is a %x2F ("/") character. 776 5.2. The Set-Cookie Header 778 When a user agent receives a Set-Cookie header field in an HTTP 779 response, the user agent MAY ignore the Set-Cookie header field in 780 its entirety. For example, the user agent might wish to block 781 responses to "third-party" requests from setting cookies (See 782 Section 7.1). 784 If the user agent does not ignore the Set-Cookie header field in its 785 entirety, the user agent MUST parse the field-value of the Set-Cookie 786 header field as a set-cookie-string (defined below). 788 NOTE: The algorithm below is more permissive than the grammar in 789 Section 4.1. For example, the algorithm strips leading and trailing 790 whitespace from the cookie name and value (but maintains internal 791 whitespace), whereas the grammar in Section 4.1 forbids whitespace in 792 these positions. User agents use this algorithm so as to 793 interoperate with servers that do not follow the recommendations in 794 Section 4. 796 A user agent MUST use an algorithm equivalent to the following 797 algorithm to parse a "set-cookie-string": 799 1. If the set-cookie-string contains a %x3B (";") character: 801 The name-value-pair string consists of the characters up to, 802 but not including, the first %x3B (";"), and the unparsed- 803 attributes consist of the remainder of the set-cookie-string 804 (including the %x3B (";") in question). 806 Otherwise: 808 The name-value-pair string consists of all the characters 809 contained in the set-cookie-string, and the unparsed- 810 attributes is the empty string. 812 2. If the name-value-pair string lacks a %x3D ("=") character, 813 ignore the set-cookie-string entirely. 815 3. The (possibly empty) name string consists of the characters up 816 to, but not including, the first %x3D ("=") character, and the 817 (possibly empty) value string consists of the characters after 818 the first %x3D ("=") character. 820 4. Remove any leading or trailing WSP characters from the name 821 string and the value string. 823 5. If the name string is empty, ignore the set-cookie-string 824 entirely. 826 6. The cookie-name is the name string, and the cookie-value is the 827 value string. 829 The user agent MUST use an algorithm equivalent to the following 830 algorithm to parse the unparsed-attributes: 832 1. If the unparsed-attributes string is empty, skip the rest of 833 these steps. 835 2. Discard the first character of the unparsed-attributes (which 836 will be a %x3B (";") character). 838 3. If the remaining unparsed-attributes contains a %x3B (";") 839 character: 841 Consume the characters of the unparsed-attributes up to, but 842 not including, the first %x3B (";") character. 844 Otherwise: 846 Consume the remainder of the unparsed-attributes. 848 Let the cookie-av string be the characters consumed in this step. 850 4. If the cookie-av string contains a %x3D ("=") character: 852 The (possibly empty) attribute-name string consists of the 853 characters up to, but not including, the first %x3D ("=") 854 character, and the (possibly empty) attribute-value string 855 consists of the characters after the first %x3D ("=") 856 character. 858 Otherwise: 860 The attribute-name string consists of the entire cookie-av 861 string, and the attribute-value string is empty. 863 5. Remove any leading or trailing WSP characters from the attribute- 864 name string and the attribute-value string. 866 6. Process the attribute-name and attribute-value according to the 867 requirements in the following subsections. (Notice that 868 attributes with unrecognized attribute-names are ignored.) 870 7. Return to Step 1 of this algorithm. 872 When the user agent finishes parsing the set-cookie-string, the user 873 agent is said to "receive a cookie" from the request-uri with name 874 cookie-name, value cookie-value, and attributes cookie-attribute- 875 list. (See Section 5.3 for additional requirements triggered by 876 receiving a cookie.) 878 5.2.1. The Expires Attribute 880 If the attribute-name case-insensitively matches the string 881 "Expires", the user agent MUST process the cookie-av as follows. 883 Let the expiry-time be the result of parsing the attribute-value as 884 cookie-date (see Section 5.1.1). 886 If the attribute-value failed to parse as a cookie date, ignore the 887 cookie-av. 889 If the expiry-time is later than the last date the user agent can 890 represent, the user agent MAY replace the expiry-time with the last 891 representable date. 893 If the expiry-time is earlier than the earliest date the user agent 894 can represent, the user agent MAY replace the expiry-time with the 895 earliest representable date. 897 Append an attribute to the cookie-attribute-list with an attribute- 898 name of Expires and an attribute-value of expiry-time. 900 5.2.2. The Max-Age Attribute 902 If the attribute-name case-insensitively matches the string "Max- 903 Age", the user agent MUST process the cookie-av as follows. 905 If the first character of the attribute-value is not a DIGIT or a "-" 906 character, ignore the cookie-av. 908 If the remainder of attribute-value contains a non-DIGIT character, 909 ignore the cookie-av. 911 Let delta-seconds be the attribute-value converted to an integer. 913 If delta-seconds is less than or equal to zero (0), let expiry-time 914 be the earliest representable date and time. Otherwise, let the 915 expiry-time be the current date and time plus delta-seconds seconds. 917 Append an attribute to the cookie-attribute-list with an attribute- 918 name of Max-Age and an attribute-value of expiry-time. 920 5.2.3. The Domain Attribute 922 If the attribute-name case-insensitively matches the string "Domain", 923 the user agent MUST process the cookie-av as follows. 925 If the attribute-value is empty, the behavior is undefined. However, 926 user agent SHOULD ignore the cookie-av entirely. 928 If the first character of the attribute-value string is %x2E ("."): 930 Let cookie-domain be the attribute-value without the leading %x2E 931 (".") character. 933 Otherwise: 935 Let cookie-domain be the entire attribute-value. 937 Convert the cookie-domain to lower case. 939 Append an attribute to the cookie-attribute-list with an attribute- 940 name of Domain and an attribute-value of cookie-domain. 942 5.2.4. The Path Attribute 944 If the attribute-name case-insensitively matches the string "Path", 945 the user agent MUST process the cookie-av as follows. 947 If the attribute-value is empty or if the first character of the 948 attribute-value is not %x2F ("/"): 950 Let cookie-path be the default-path. 952 Otherwise: 954 Let cookie-path be the attribute-value. 956 Append an attribute to the cookie-attribute-list with an attribute- 957 name of Path and an attribute-value of cookie-path. 959 5.2.5. The Secure Attribute 961 If the attribute-name case-insensitively matches the string "Secure", 962 the user agent MUST append an attribute to the cookie-attribute-list 963 with an attribute-name of Secure and an empty attribute-value. 965 5.2.6. The HttpOnly Attribute 967 If the attribute-name case-insensitively matches the string 968 "HttpOnly", the user agent MUST append an attribute to the cookie- 969 attribute-list with an attribute-name of HttpOnly and an empty 970 attribute-value. 972 5.3. Storage Model 974 The user agent stores the following fields about each cookie: name, 975 value, expiry-time, domain, path, creation-time, last-access-time, 976 persistent-flag, host-only-flag, secure-only-flag, and http-only- 977 flag. 979 When the user agent "receives a cookie" from a request-uri with name 980 cookie-name, value cookie-value, and attributes cookie-attribute- 981 list, the user agent MUST process the cookie as follows: 983 1. A user agent MAY ignore a received cookie in its entirety. For 984 example, the user agent might wish to block receiving cookies 985 from "third-party" responses or the user agent might not wish to 986 store cookies that exceed some size. 988 2. Create a new cookie with name cookie-name, value cookie-value. 989 Set the creation-time and the last-access-time to the current 990 date and time. 992 3. If the cookie-attribute-list contains an attribute with an 993 attribute-name of "Max-Age": 995 Set the cookie's persistent-flag to true. 997 Set the cookie's expiry-time to attribute-value of the last 998 attribute in the cookie-attribute-list with an attribute-name 999 of "Max-Age". 1001 Otherwise, if the cookie-attribute-list contains an attribute 1002 with an attribute-name of "Expires" (and does not contain an 1003 attribute with an attribute-name of "Max-Age"): 1005 Set the cookie's persistent-flag to true. 1007 Set the cookie's expiry-time to attribute-value of the last 1008 attribute in the cookie-attribute-list with an attribute-name 1009 of "Expires". 1011 Otherwise: 1013 Set the cookie's persistent-flag to false. 1015 Set the cookie's expiry-time to the latest representable 1016 date. 1018 4. If the cookie-attribute-list contains an attribute with an 1019 attribute-name of "Domain": 1021 Let the domain-attribute be the attribute-value of the last 1022 attribute in the cookie-attribute-list with an attribute-name 1023 of "Domain". 1025 Otherwise: 1027 Let the domain-attribute be the empty string. 1029 5. If the user agent is configured to reject "public suffixes" and 1030 the domain-attribute is a public suffix: 1032 If the domain-attribute is identical to the canonicalized 1033 request-host: 1035 Let the domain-attribute be the empty string. 1037 Otherwise: 1039 Ignore the cookie entirely and abort these steps. 1041 NOTE: A "public suffix" is a domain that is controlled by a 1042 public registry, such as "com", "co.uk", and "pvt.k12.wy.us". 1043 This step is essential for preventing attacker.com from 1044 disrupting the integrity of example.com by setting a cookie 1045 with a Domain attribute of "com". Unfortunately, the set of 1046 public suffixes (also known as "registry controlled domains") 1047 changes over time. If feasible, user agents SHOULD use an 1048 up-to-date public suffix list, such as the one maintained by 1049 the Mozilla project at . 1051 6. If the domain-attribute is non-empty: 1053 If the canonicalized request-host does not domain-match the 1054 domain-attribute: 1056 Ignore the cookie entirely and abort these steps. 1058 Otherwise: 1060 Set the cookie's host-only-flag to false. 1062 Set the cookie's domain to the domain-attribute. 1064 Otherwise: 1066 Set the cookie's host-only-flag to true. 1068 Set the cookie's domain to the canonicalized request-host. 1070 7. If the cookie-attribute-list contains an attribute with an 1071 attribute-name of "Path", set the cookie's path to attribute- 1072 value of the last attribute in the cookie-attribute-list with an 1073 attribute-name of "Path". Otherwise, set cookie's path to the 1074 default-path of the request-uri. 1076 8. If the cookie-attribute-list contains an attribute with an 1077 attribute-name of "Secure", set the cookie's secure-only-flag to 1078 true. Otherwise, set cookie's secure-only-flag to false. 1080 9. If the cookie-attribute-list contains an attribute with an 1081 attribute-name of "HttpOnly", set the cookie's http-only-flag to 1082 true. Otherwise, set cookie's http-only-flag to false. 1084 10. If the cookie was received from a "non-HTTP" API and the 1085 cookie's http-only-flag is set, abort these steps and ignore the 1086 cookie entirely. 1088 11. If the cookie store contains a cookie with the same name, 1089 domain, and path as the newly created cookie: 1091 1. Let old-cookie be the existing cookie with the same name, 1092 domain, and path as the newly created cookie. (Notice that 1093 this algorithm maintains the invariant that there is at most 1094 one such cookie.) 1096 2. If the newly created cookie was received from a "non-HTTP" 1097 API and the old-cookie's http-only-flag is set, abort these 1098 steps and ignore the newly created cookie entirely. 1100 3. Update the creation-time of the newly created cookie to 1101 match the creation-time of the old-cookie. 1103 4. Remove the old-cookie from the cookie store. 1105 12. Insert the newly created cookie into the cookie store. 1107 A cookie is "expired" if the cookie has an expiry date in the past. 1109 The user agent MUST evict all expired cookies from the cookie store 1110 if, at any time, an expired cookie exists in the cookie store. 1112 At any time, the user agent MAY "remove excess cookies" from the 1113 cookie store if the number of cookies sharing a domain field exceeds 1114 some implementation defined upper bound (such as 50 cookies). 1116 At any time, the user agent MAY "remove excess cookies" from the 1117 cookie store if the cookie store exceeds some predetermined upper 1118 bound (such as 3000 cookies). 1120 When the user agent removes excess cookies from the cookie store, the 1121 user agent MUST evict cookies in the following priority order: 1123 1. Expired cookies. 1125 2. Cookies that share a domain field with more than a predetermined 1126 number of other cookies. 1128 3. All cookies. 1130 If two cookies have the same removal priority, the user agent MUST 1131 evict the cookie with the earliest last-access date first. 1133 When "the current session is over" (as defined by the user agent), 1134 the user agent MUST remove from the cookie store all cookies with the 1135 persistent-flag set to false. 1137 5.4. The Cookie Header 1139 The user agent includes stored cookies in the Cookie HTTP request 1140 header. 1142 When the user agent generates an HTTP request, the user agent MUST 1143 NOT attach more than one Cookie header field. 1145 A user agent MAY omit the Cookie header in its entirety. For 1146 example, the user agent might wish to block sending cookies during 1147 "third-party" requests from setting cookies (See Section 7.1). 1149 If the user agent does attach a Cookie header field to an HTTP 1150 request, the user agent MUST send the cookie-string (defined below) 1151 as the value of the header field. 1153 The user agent MUST use an algorithm equivalent to the following 1154 algorithm to compute the "cookie-string" from a cookie store and a 1155 request-uri: 1157 1. Let cookie-list be the set of cookies from the cookie store that 1158 meet all of the following requirements: 1160 * Either: 1162 The cookie's host-only-flag is true and the canonicalized 1163 request-host is identical to the cookie's domain. 1165 Or: 1167 The cookie's host-only-flag is false and the canonicalized 1168 request-host domain-matches cookie's domain. 1170 * The request-uri's path path-matches cookie's path. 1172 * If the cookie's secure-only-flag is true, then the request- 1173 uri's scheme must denote a "secure" protocol (as defined by 1174 the user agent). 1176 NOTE: The notion of a "secure" protocol is not defined by 1177 this document. Typically, user agents consider a protocol 1178 secure if the protocol makes use of transport-layer 1179 security, such as SSL or TLS. For example, most user 1180 agents consider "https" to be a scheme that denotes a 1181 secure protocol. 1183 * If the cookie's http-only-flag is true, then exclude the 1184 cookie if the cookie-string is being generated for a "non- 1185 HTTP" API (as defined by the user agent). 1187 2. The user agent SHOULD sort the cookie-list in the following 1188 order: 1190 * Cookies with longer paths are listed before cookies with 1191 shorter paths. 1193 * Among cookies that have equal length path fields, cookies with 1194 earlier creation-times are listed before cookies with later 1195 creation-times. 1197 NOTE: Not all user agents sort the cookie-list in this order, but 1198 this order reflects common practice when this document was 1199 written, and, historically, there have been servers that 1200 (erroneously) depended on this order. 1202 3. Update the last-access-time of each cookie in the cookie-list to 1203 the current date and time. 1205 4. Serialize the cookie-list into a cookie-string by processing each 1206 cookie in the cookie-list in order: 1208 1. Output the cookie's name, the %x3D ("=") character, and the 1209 cookie's value. 1211 2. If there is an unprocessed cookie in the cookie-list, output 1212 the characters %x3B and %x20 ("; "). 1214 NOTE: Despite its name, the cookie-string is actually a sequence of 1215 octets, not a sequence of characters. To convert the cookie-string 1216 (or components thereof) into a sequence of characters (e.g., for 1217 presentation to the user), the user agent might wish to try using the 1218 UTF-8 character encoding [RFC3629] to decode the octet sequence. 1219 This decoding might fail, however, because not every sequence of 1220 octets is valid UTF-8. 1222 6. Implementation Considerations 1224 6.1. Limits 1226 Practical user agent implementations have limits on the number and 1227 size of cookies that they can store. General-use user agents SHOULD 1228 provide each of the following minimum capabilities: 1230 o At least 4096 bytes per cookie (as measured by the sum of the 1231 length of the cookie's name, value, and attributes). 1233 o At least 50 cookies per domain. 1235 o At least 3000 cookies total. 1237 Servers SHOULD use as few and as small cookies as possible to avoid 1238 reaching these implementation limits and to minimize network 1239 bandwidth due to the Cookie header being included in every request. 1241 Servers SHOULD gracefully degrade if the user agent fails to return 1242 one or more cookies in the Cookie header because the user agent might 1243 evict any cookie at any time on orders from the user. 1245 6.2. Application Programming Interfaces 1247 One reason the Cookie and Set-Cookie headers uses such esoteric 1248 syntax is because many platforms (both in servers and user agents) 1249 provide a string-based application programing interface (API) to 1250 cookies, requiring application-layer programmers to generate and 1251 parse the syntax used by the Cookie and Set-Cookie headers, which 1252 many programmers have done incorrectly, resulting in interoperability 1253 problems. 1255 Instead of providing string-based APIs to cookies, platforms would be 1256 well-served by providing more semantic APIs. It is beyond the scope 1257 of this document to recommend specific API designs, but there are 1258 clear benefits to accepting an abstract "Date" object instead of a 1259 serialized date string. 1261 6.3. IDNA dependency and migration 1263 IDNA2008 [RFC5890] supersedes IDNA2003 [RFC3490]. However, there are 1264 differences between the two specifications, and thus there can be 1265 differences in processing (e.g. converting) domain name labels that 1266 have been registered under one from those registered under the other. 1267 There will be a transition period of some time during which IDNA2003- 1268 based domain name labels will exist in the wild. User agents SHOULD 1269 implement IDNA2008 [RFC5890] and MAY implement [UTS46] or [RFC5895] 1270 in order to facilitate their IDNA transition. If a user agent does 1271 not implement IDNA2008, the user agent MUST implement IDNA2003 1272 [RFC3490]. 1274 7. Privacy Considerations 1276 Cookies are often criticized for letting servers track users. For 1277 example, a number of "web analytics" companies use cookies to 1278 recognize when a user returns to a web site or visits another web 1279 site. Although cookies are not the only mechanism servers can use to 1280 track users across HTTP requests, cookies facilitate tracking because 1281 they are persistent across user agent sessions and can be shared 1282 between hosts. 1284 7.1. Third-Party Cookies 1286 Particularly worrisome are so-called "third-party" cookies. In 1287 rendering an HTML document, a user agent often requests resources 1288 from other servers (such as advertising networks). These third-party 1289 servers can use cookies to track the user even if the user never 1290 visits the server directly. For example, if a user visits a site 1291 that contains content from a third party and then later visits 1292 another site that contains content from the same third party, the 1293 third party can track the user between the two sites. 1295 Some user agents restrict how third-party cookies behave. For 1296 example, some of these user agents refuse to send the Cookie header 1297 in third-party requests. Others refuse to process the Set-Cookie 1298 header in responses to third-party requests. User agents vary widely 1299 in their third-party cookie policies. This document grants user 1300 agents wide latitude to experiment with third-party cookie policies 1301 that balance the privacy and compatibility needs of their users. 1302 However, this document does not endorse any particular third-party 1303 cookie policy. 1305 Third-party cookie blocking policies are often ineffective at 1306 achieving their privacy goals if servers attempt to work around their 1307 restrictions to track users. In particular, two collaborating 1308 servers can often track users without using cookies at all by 1309 injecting identifying information into dynamic URLs. 1311 7.2. User Controls 1313 User agents SHOULD provide users with a mechanism for managing the 1314 cookies stored in the cookie store. For example, a user agent might 1315 let users delete all cookies received during a specified time period 1316 or all the cookies related to a particular domain. In addition, many 1317 user agents include a user interface element that lets users examine 1318 the cookies stored in their cookie store. 1320 User agents SHOULD provide users with a mechanism for disabling 1321 cookies. When cookies are disabled, the user agent MUST NOT include 1322 a Cookie header in outbound HTTP requests and the user agent MUST NOT 1323 process Set-Cookie headers in inbound HTTP responses. 1325 Some user agents provide users the option of preventing persistent 1326 storage of cookies across sessions. When configured thusly, user 1327 agents MUST treat all received cookies as if the persistent-flag were 1328 set to false. Some popular user agents expose this functionality via 1329 "private browsing" mode [Aggarwal2010] 1331 Some user agents provide users with the ability to approve individual 1332 writes to the cookie store. In many common usage scenarios, these 1333 controls generate a large number of prompts. However, some privacy- 1334 conscious users find these controls useful nonetheless. 1336 7.3. Expiration Dates 1338 Although servers can set the expiration date for cookies to the 1339 distant future, most user agents do not actually retain cookies for 1340 multiple decades. Rather than chosing gratuitously long expiration 1341 periods, servers SHOULD promote user privacy by selecting reasonable 1342 cookie expiration periods based on the purpose of the cookie. For 1343 example, a typical session identifier might reasonably be set to 1344 expire in two weeks. 1346 8. Security Considerations 1348 8.1. Overview 1350 Cookies have a number of security pitfalls. This section overviews a 1351 few of the more salient issues. 1353 In particular, cookies encourage developers to rely on ambient 1354 authority for authentication, often becoming vulnerable to attacks 1355 such as cross-site request forgery [CSRF]. Also, when storing 1356 session identifiers in cookies, developers often create session 1357 fixation vulnerabilities. 1359 Transport-layer encryption, such as that employed in HTTPS, is 1360 insufficient to prevent a network attacker from obtaining or altering 1361 a victim's cookies because the cookie protocol itself has various 1362 vulnerabilities (see "Weak Confidentiality" and "Weak Integrity", 1363 below). In addition, by default, cookies do not provide 1364 confidentiality or integrity from network attackers, even when used 1365 in conjunction with HTTPS. 1367 8.2. Ambient Authority 1369 A server that uses cookies to authenticate users can suffer security 1370 vulnerabilities because some user agents let remote parties issue 1371 HTTP requests from the user agent (e.g., via HTTP redirects or HTML 1372 forms). When issuing those requests, user agents attach cookies even 1373 if the remote party does not know the contents of the cookies, 1374 potentially letting the remote party exercise authority at an unwary 1375 server. 1377 Although this security concern goes by a number of names (e.g., 1378 cross-site request forgery, confused deputy), the issue stems from 1379 cookies being a form of ambient authority. Cookies encourage server 1380 operators to separate designation (in the form of URLs) from 1381 authorization (in the form of cookies). Consequently, the user agent 1382 might supply the authorization for a resource designated by the 1383 attacker, possibly causing the server or its clients to undertake 1384 actions designated by the attacker as though they were authorized by 1385 the user. 1387 Instead of using cookies for authorization, server operators might 1388 wish to consider entangling designation and authorization by treating 1389 URLs as capabilities. Instead of storing secrets in cookies, this 1390 approach stores secrets in URLs, requiring the remote entity to 1391 supply the secret itself. Although this approach is not a panacea, 1392 judicious application of these principles can lead to more robust 1393 security. 1395 8.3. Clear Text 1397 Unless sent over a secure channel (such as TLS), the information in 1398 the Cookie and Set-Cookie headers is transmitted in the clear. 1400 1. All sensitive information conveyed in these headers is exposed to 1401 an eavesdropper. 1403 2. A malicious intermediary could alter the headers as they travel 1404 in either direction, with unpredictable results. 1406 3. A malicious client could alter the Cookie header before 1407 transmission, with unpredictable results. 1409 Servers SHOULD encrypt and sign the contents of cookies (using 1410 whatever format the server desires) when transmitting them to the 1411 user agent (even when sending the cookies over a secure channel). 1412 However, encrypting and signing cookie contents does not prevent an 1413 attacker from transplanting a cookie from one user agent to another 1414 or from replaying the cookie at a later time. 1416 In addition to encrypting and signing the contents of every cookie, 1417 servers that require a higher level of security SHOULD use the Cookie 1418 and Set-Cookie headers only over a secure channel. When using 1419 cookies over a secure channel, servers SHOULD set the Secure 1420 attribute (see Section 4.1.2.5) for every cookie. If a server does 1421 not set the Secure attribute, the protection provided by the secure 1422 channel will be largely moot. 1424 For example, consider a webmail server that stores a session 1425 identifier in a cookie and is typically accessed over HTTPS. If the 1426 server does not set the Secure attribute on its cookies, an active 1427 network attacker can intercept any outbound HTTP request from the 1428 user agent and redirect that request to the webmail server over HTTP. 1429 Even if the webmail server is not listening for HTTP connections, the 1430 user agent will still include cookies in the request. The active 1431 network attacker can intercept these cookies, replay them against the 1432 server, and learn the contents of the user's email. If, instead, the 1433 server had set the Secure attribute on its cookies, the user agent 1434 would not have included the cookies in the clear-text request. 1436 8.4. Session Identifiers 1438 Instead of storing session information directly in a cookie (where it 1439 might be exposed to or replayed by an attacker), servers commonly 1440 store a nonce (or "session identifier") in a cookie. When the server 1441 receives an HTTP request with a nonce, the server can look up state 1442 information associated with the cookie using the nonce as a key. 1444 Using session identifier cookies limits the damage an attacker can 1445 cause if the attacker learns the contents of a cookie because the 1446 nonce is useful only for interacting with the server (unlike non- 1447 nonce cookie content, which might itself be sensitive). Furthermore, 1448 using a single nonce prevents an attacker from "splicing" together 1449 cookie content from two interactions with the server, which could 1450 cause the server to behave unexpectedly. 1452 Using session identifiers is not without risk. For example, the 1453 server SHOULD take care to avoid "session fixation" vulnerabilities. 1454 A session fixation attack proceeds in three steps. First, the 1455 attacker transplants a session identifier from his or her user agent 1456 to the victim's user agent. Second, the victim uses that session 1457 identifier to interact with the server, possibly imbuing the session 1458 identifier with the user's credentials or confidential information. 1459 Third, the attacker uses the session identifier to interact with 1460 server directly, possibly obtaining the user's authority or 1461 confidential information. 1463 8.5. Weak Confidentiality 1465 Cookies do not provide isolation by port. If a cookie is readable by 1466 a service running on one port, the cookie is also readable by a 1467 service running on another port of the same server. If a cookie is 1468 writable by a service on one port, the cookie is also writable by a 1469 service running on another port of the same server. For this reason, 1470 servers SHOULD NOT both run mutually distrusting services on 1471 different ports of the same host and use cookies to store security- 1472 sensitive information. 1474 Cookies do not provide isolation by scheme. Although most commonly 1475 used with the http and https schemes, the cookies for a given host 1476 might also be available to other schemes, such as ftp and gopher. 1477 Although this lack of isolation by scheme is most apparent in non- 1478 HTTP APIs that permit access to cookies (e.g., HTML's document.cookie 1479 API), the lack of isolation by scheme is actually present in 1480 requirements for processing cookies themselves (e.g., consider 1481 retrieving a URI with the gopher scheme via HTTP). 1483 Cookies do not always provide isolation by path. Although the 1484 network-level protocol does not send cookies stored for one path to 1485 another, some user agents expose cookies via non-HTTP APIs, such as 1486 HTML's document.cookie API. Because some of these user agents (e.g., 1487 web browsers) do not isolate resources received from different paths, 1488 a resource retrieved from one path might be able to access cookies 1489 stored for another path. 1491 8.6. Weak Integrity 1493 Cookies do not provide integrity guarantees for sibling domains (and 1494 their subdomains). For example, consider foo.example.com and 1495 bar.example.com. The foo.example.com server can set a cookie with a 1496 Domain attribute of "example.com" (possibly overwriting an existing 1497 "example.com" cookie set by bar.example.com), and the user agent will 1498 include that cookie in HTTP requests to bar.example.com. In the 1499 worst case, bar.example.com will be unable to distinguish this cookie 1500 from a cookie it set itself. The foo.example.com server might be 1501 able to leverage this ability to mount an attack against 1502 bar.example.com. 1504 Even though the Set-Cookie header supports the Path attribute, the 1505 Path attribute does not provide any integrity protection because the 1506 user agent will accept an arbitrary Path attribute in a Set-Cookie 1507 header. For example, an HTTP response to a request for 1508 http://example.com/foo/bar can set a cookie with a Path attribute of 1509 "/qux". Consequently, servers SHOULD NOT both run mutually 1510 distrusting services on different paths of the same host and use 1511 cookies to store security-sensitive information. 1513 An active network attacker can also inject cookies into the Cookie 1514 header sent to https://example.com/ by impersonating a response from 1515 http://example.com/ and injecting a Set-Cookie header. The HTTPS 1516 server at example.com will be unable to distinguish these cookies 1517 from cookies that it set itself in an HTTPS response. An active 1518 network attacker might be able to leverage this ability to mount an 1519 attack against example.com even if example.com uses HTTPS 1520 exclusively. 1522 Servers can partially mitigate these attacks by encrypting and 1523 signing the contents of their cookies. However, using cryptography 1524 does not mitigate the issue completely because an attacker can replay 1525 a cookie he or she received from the authentic example.com server in 1526 the user's session, with unpredictable results. 1528 Finally, an attacker might be able to force the user agent to delete 1529 cookies by storing a large number of cookies. Once the user agent 1530 reaches its storage limit, the user agent will be forced to evict 1531 some cookies. Servers SHOULD NOT rely upon user agents retaining 1532 cookies. 1534 8.7. Reliance on DNS 1536 Cookies rely upon the Domain Name System (DNS) for security. If the 1537 DNS is partially or fully compromised, the cookie protocol might fail 1538 to provide the security properties required by applications. 1540 9. IANA Considerations 1542 The permanent message header field registry (see [RFC3864]) should be 1543 updated with the following registrations: 1545 9.1. Cookie 1547 Header field name: Cookie 1549 Applicable protocol: http 1551 Status: standard 1553 Author/Change controller: IETF 1555 Specification document: this specification (Section 5.4) 1557 9.2. Set-Cookie 1559 Header field name: Set-Cookie 1561 Applicable protocol: http 1563 Status: standard 1565 Author/Change controller: IETF 1567 Specification document: this specification (Section 5.2) 1569 9.3. Cookie2 1571 Header field name: Cookie2 1573 Applicable protocol: http 1575 Status: obsoleted 1577 Author/Change controller: IETF 1579 Specification document: [RFC2965] 1581 9.4. Set-Cookie2 1583 Header field name: Set-Cookie2 1585 Applicable protocol: http 1587 Status: obsoleted 1588 Author/Change controller: IETF 1590 Specification document: [RFC2965] 1592 10. References 1594 10.1. Normative References 1596 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 1597 STD 13, RFC 1034, November 1987. 1599 [RFC1123] Braden, R., "Requirements for Internet Hosts - Application 1600 and Support", STD 3, RFC 1123, October 1989. 1602 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1603 Requirement Levels", BCP 14, RFC 2119, March 1997. 1605 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1606 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1607 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1609 [RFC3490] Faltstrom, P., Hoffman, P., and A. Costello, 1610 "Internationalizing Domain Names in Applications (IDNA)", 1611 RFC 3490, March 2003. 1613 See Section 6.3 for an explanation why the normative 1614 reference to an obsoleted specification is needed. 1616 [RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet 1617 Application Protocol Collation Registry", RFC 4790, 1618 March 2007. 1620 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1621 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1623 [RFC5890] Klensin, J., "Internationalized Domain Names for 1624 Applications (IDNA): Definitions and Document Framework", 1625 RFC 5890, August 2010. 1627 [USASCII] American National Standards Institute, "Coded Character 1628 Set -- 7-bit American Standard Code for Information 1629 Interchange", ANSI X3.4, 1986. 1631 10.2. Informative References 1633 [RFC2109] Kristol, D. and L. Montulli, "HTTP State Management 1634 Mechanism", RFC 2109, February 1997. 1636 [RFC2965] Kristol, D. and L. Montulli, "HTTP State Management 1637 Mechanism", RFC 2965, October 2000. 1639 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1641 [Netscape] 1642 Netscape Communications Corp., "Persistent Client State -- 1643 HTTP Cookies", 1999, . 1647 [Kri2001] Kristol, D., "HTTP Cookies: Standards, Privacy, and 1648 Politics", ACM Transactions on Internet Technology Vol. 1, 1649 #2, November 2001, . 1651 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1652 10646", STD 63, RFC 3629, November 2003. 1654 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1655 Encodings", RFC 4648, October 2006. 1657 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1658 Procedures for Message Header Fields", BCP 90, RFC 3864, 1659 September 2004. 1661 [RFC5895] Resnick, P. and P. Hoffman, "Mapping Characters for 1662 Internationalized Domain Names in Applications (IDNA) 1663 2008", RFC 5895, September 2010. 1665 [UTS46] Davis, M. and M. Suignard, "Unicode IDNA Compatibility 1666 Processing", Unicode Technical Standards # 46, 2010, 1667 . 1669 [CSRF] Barth, A., Jackson, C., and J. Mitchell, "Robust Defenses 1670 for Cross-Site Request Forgery", 2008, . 1674 [Aggarwal2010] 1675 Aggarwal, G., Burzstein, E., Jackson, C., and D. Boneh, 1676 "An Analysis of Private Browsing Modes in Modern 1677 Browsers", 2010, . 1680 Appendix A. Acknowledgements 1682 This document borrows heavily from RFC 2109 [RFC2109]. We are 1683 indebted to David M. Kristol and Lou Montulli for their efforts to 1684 specify cookies. David M. Kristol, in particular, provided 1685 invaluable advice on navigating the IETF process. We would also like 1686 to thank Thomas Broyer, Tyler Close, Alissa Cooper, Bil Corry, 1687 corvid, Lisa Dusseault, Roy T. Fielding, Blake Frantz, Anne van 1688 Kesteren, Eran Hammer-Lahav, Jeff Hodges, Bjoern Hoehrmann, Achim 1689 Hoffmann, Georg Koppen, Dean McNamee, Alexey Melnikov, Mark Miller, 1690 Mark Pauley, Yngve N. Pettersen, Julian Reschke, Peter Saint-Andre, 1691 Mark Seaborn, Maciej Stachowiak, Daniel Stenberg, Tatsuhiro 1692 Tsujikawa, David Wagner, Dan Winship, and Dan Witte for their 1693 valuable feedback on this document. 1695 Author's Address 1697 Adam Barth 1698 University of California, Berkeley 1700 Email: abarth@eecs.berkeley.edu 1701 URI: http://www.adambarth.com/