idnits 2.17.1 draft-ietf-httpstate-cookie-18.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 draft header indicates that this document obsoletes RFC2965, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 9, 2010) is 4910 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) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- 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) November 9, 2010 5 Intended status: Standards Track 6 Expires: May 13, 2011 8 HTTP State Management Mechanism 9 draft-ietf-httpstate-cookie-18 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. 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 May 13, 2011. 45 Copyright Notice 47 Copyright (c) 2010 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 . . . . . . . . . . . . . . . . . . . . . . . . . 6 76 2.1. Conformance Criteria . . . . . . . . . . . . . . . . . . . 6 77 2.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 6 78 2.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 79 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 80 3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 8 81 4. Server Requirements . . . . . . . . . . . . . . . . . . . . . 11 82 4.1. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . . 11 83 4.1.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . 11 84 4.1.2. Semantics (Non-Normative) . . . . . . . . . . . . . . 12 85 4.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . . 15 86 4.2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . 15 87 4.2.2. Semantics . . . . . . . . . . . . . . . . . . . . . . 15 88 5. User Agent Requirements . . . . . . . . . . . . . . . . . . . 16 89 5.1. Subcomponent Algorithms . . . . . . . . . . . . . . . . . 16 90 5.1.1. Dates . . . . . . . . . . . . . . . . . . . . . . . . 16 91 5.1.2. Canonicalized host names . . . . . . . . . . . . . . . 18 92 5.1.3. Domain matching . . . . . . . . . . . . . . . . . . . 18 93 5.1.4. Paths and path-match . . . . . . . . . . . . . . . . . 18 94 5.2. The Set-Cookie Header . . . . . . . . . . . . . . . . . . 19 95 5.2.1. The Expires Attribute . . . . . . . . . . . . . . . . 21 96 5.2.2. The Max-Age Attribute . . . . . . . . . . . . . . . . 21 97 5.2.3. The Domain Attribute . . . . . . . . . . . . . . . . . 22 98 5.2.4. The Path Attribute . . . . . . . . . . . . . . . . . . 22 99 5.2.5. The Secure Attribute . . . . . . . . . . . . . . . . . 23 100 5.2.6. The HttpOnly Attribute . . . . . . . . . . . . . . . . 23 101 5.3. Storage Model . . . . . . . . . . . . . . . . . . . . . . 23 102 5.4. The Cookie Header . . . . . . . . . . . . . . . . . . . . 26 103 6. Implementation Considerations . . . . . . . . . . . . . . . . 29 104 6.1. Limits . . . . . . . . . . . . . . . . . . . . . . . . . . 29 105 6.2. Application Programming Interfaces . . . . . . . . . . . . 29 106 6.3. IDNA dependency and migration . . . . . . . . . . . . . . 29 107 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 31 108 7.1. Third-Party Cookies . . . . . . . . . . . . . . . . . . . 31 109 7.2. User Controls . . . . . . . . . . . . . . . . . . . . . . 31 110 8. Security Considerations . . . . . . . . . . . . . . . . . . . 33 111 8.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 33 112 8.2. Ambient Authority . . . . . . . . . . . . . . . . . . . . 33 113 8.3. Clear Text . . . . . . . . . . . . . . . . . . . . . . . . 34 114 8.4. Session Identifiers . . . . . . . . . . . . . . . . . . . 34 115 8.5. Weak Confidentiality . . . . . . . . . . . . . . . . . . . 35 116 8.6. Weak Integrity . . . . . . . . . . . . . . . . . . . . . . 35 117 8.7. Reliance on DNS . . . . . . . . . . . . . . . . . . . . . 36 118 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 119 9.1. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . . 37 120 9.2. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . . 37 121 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 38 122 10.1. Normative References . . . . . . . . . . . . . . . . . . . 38 123 10.2. Informative References . . . . . . . . . . . . . . . . . . 38 124 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 40 125 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 41 127 1. Introduction 129 This document defines the HTTP Cookie and Set-Cookie header fields. 130 Using the Set-Cookie header field, an HTTP server can pass name/value 131 pairs and associated metadata (called cookies) to a user agent. When 132 the user agent makes subsequent requests to the server, the user 133 agent uses the metadata and other information to determine whether to 134 return the name/value pairs in the Cookie header. 136 Although simple on their surface, cookies have a number of 137 complexities. For example, the server indicates a scope for each 138 cookie when sending it to the user agent. The scope indicates the 139 maximum amount of time the user agent should return the cookie, the 140 servers to which the user agent should return the cookie, and the URI 141 schemes for which the cookie is applicable. 143 For historical reasons, cookies contain a number of security and 144 privacy infelicities. For example, a server can indicate that a 145 given cookie is intended for "secure" connections, but the Secure 146 attribute does not provide integrity in the presence of an active 147 network attacker. Similarly, cookies for a given host are shared 148 across all the ports on that host, even though the usual "same-origin 149 policy" used by web browsers isolates content retrieved via different 150 ports. 152 Prior to this document, there were at least three descriptions of 153 cookies: the so-called "Netscape cookie specification" [Netscape], 154 RFC 2109 [RFC2109], and RFC 2965 [RFC2965]. However, none of these 155 documents describe how the Cookie and Set-Cookie headers are actually 156 used on the Internet (see [Kri2001] for historical context). This 157 document attempts to specify the syntax and semantics of these 158 headers as they are actually used on the Internet. 160 Therefore, in relation to previous IETF specifications of HTTP state 161 management mechanisms, this document requests the following actions: 163 1. Change the status of [RFC2109] to Historic (it has already been 164 obsoleted by [RFC2965]). 166 2. Change the status of [RFC2965] to Historic. 168 3. Indicate that [RFC2965] is obsoleted by this document. 170 2. Conventions 172 2.1. Conformance Criteria 174 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 175 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 176 document are to be interpreted as described in [RFC2119]. 178 Requirements phrased in the imperative as part of algorithms (such as 179 "strip any leading space characters" or "return false and abort these 180 steps") are to be interpreted with the meaning of the key word 181 ("MUST", "SHOULD", "MAY", etc) used in introducing the algorithm. 183 Conformance requirements phrased as algorithms or specific steps can 184 be implemented in any manner, so long as the end result is 185 equivalent. In particular, the algorithms defined in this 186 specification are intended to be easy to understand and are not 187 intended to be performant. 189 2.2. Syntax Notation 191 This specification uses the Augmented Backus-Naur Form (ABNF) 192 notation of [RFC5234]. 194 The following core rules are included by reference, as defined in 195 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 196 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 197 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 198 sequence of data), SP (space), HTAB (horizontal tab), CHAR (any US- 199 ASCII character), VCHAR (any visible US-ASCII character), and WSP 200 (whitespace). 202 The OWS (optional whitespace) rule is used where zero or more linear 203 whitespace characters MAY appear: 205 OWS = *( [ obs-fold ] WSP ) 206 ; "optional" whitespace 207 obs-fold = CRLF 209 OWS SHOULD either not be produced or be produced as a single SP 210 character. 212 2.3. Terminology 214 The terms user agent, client, server, proxy, and origin server have 215 the same meaning as in the HTTP/1.1 specification ([RFC2616], Section 216 1.3). 218 The request-host is the name of the host, as known by the user agent, 219 to which the user agent is sending an HTTP request or is receiving an 220 HTTP response from (i.e., the name of the host to which it sent the 221 corresponding HTTP request). 223 The term request-uri is defined in Section 5.1.2 of [RFC2616]. 225 Two sequences of octets are said to case-insensitively match each 226 other if and only if they are equivalent under the i;ascii-casemap 227 collation defined in [RFC4790]. 229 The term string means a sequence of octets. 231 3. Overview 233 This section outlines a way for an origin server to send state 234 information to a user agent and for the user agent to return the 235 state information to the origin server. 237 To store state, the origin server includes a Set-Cookie header in an 238 HTTP response. In subsequent requests, the user agent returns a 239 Cookie request header to the origin server. The Cookie header 240 contains cookies the user agent received in previous Set-Cookie 241 headers. The origin server is free to ignore the Cookie header or 242 use its contents for an application-defined purpose. 244 Origin servers can send a Set-Cookie response header with any 245 response. An origin server can include multiple Set-Cookie header 246 fields in a single response. 248 Note that folding multiple Set-Cookie header fields into a single 249 header field might change the semantics of the header because the 250 %x2C (",") character is used by the Set-Cookie header in a way that 251 conflicts with such folding. This historical infelicity is 252 incompatible with the usual mechanism for folding HTTP headers as 253 defined in [RFC2616]. 255 3.1. Examples 257 Using the Set-Cookie header, a server can send the user agent a short 258 string in an HTTP response that the user agent will return in future 259 HTTP requests. For example, the server can send the user agent a 260 "session identifier" named SID with the value 31d4d96e407aad42. The 261 user agent then returns the session identifier in subsequent 262 requests. 264 == Server -> User Agent == 266 Set-Cookie: SID=31d4d96e407aad42 268 == User Agent -> Server == 270 Cookie: SID=31d4d96e407aad42 272 The server can alter the default scope of the cookie using the Path 273 and Domain attributes. For example, the server can instruct the user 274 agent to return the cookie to every path and every subdomain of 275 example.com. 277 == Server -> User Agent == 279 Set-Cookie: SID=31d4d96e407aad42; Path=/; Domain=example.com 281 == User Agent -> Server == 283 Cookie: SID=31d4d96e407aad42 285 As shown in the next example, the server can store multiple cookies 286 at the user agent. For example, the server can store a session 287 identifier as well as the user's preferred language by returning two 288 Set-Cookie header fields. Notice that the server uses the Secure and 289 HttpOnly attributes to provide additional security protections for 290 the more-sensitive session identifier (see Section 4.1.2.) 292 == Server -> User Agent == 294 Set-Cookie: SID=31d4d96e407aad42; Path=/; Secure; HttpOnly 295 Set-Cookie: lang=en-US; Path=/; Domain=example.com 297 == User Agent -> Server == 299 Cookie: SID=31d4d96e407aad42; lang=en-US 301 Notice that the Cookie header above contains two cookies, one named 302 SID and one named lang. If the server wishes the user agent to 303 persist the cookie over multiple "sessions" (e.g., user agent 304 restarts), the server can specify an expiration date in the Expires 305 attribute. Note that the user agent might delete the cookie before 306 the expiration date if the user agent's cookie store exceeds its 307 quota or if the user manually deletes the server's cookie. 309 == Server -> User Agent == 311 Set-Cookie: lang=en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT 313 == User Agent -> Server == 315 Cookie: SID=31d4d96e407aad42; lang=en-US 317 Finally, to remove a cookie, the server returns a Set-Cookie header 318 with an expiration date in the past. The server will be successful 319 in removing the cookie only if the Path and the Domain attribute in 320 the Set-Cookie header match the values used when the cookie was 321 created. 323 == Server -> User Agent == 325 Set-Cookie: lang=; Expires=Sun, 06 Nov 1994 08:49:37 GMT 327 == User Agent -> Server == 329 Cookie: SID=31d4d96e407aad42 331 4. Server Requirements 333 This section describes the syntax and semantics of a well-behaved 334 profile of the Cookie and Set-Cookie headers. Servers SHOULD limit 335 themselves to the profile described in this section, both to maximize 336 interoperability with existing user agents and because a future 337 version of the Cookie or Set-Cookie headers could remove support for 338 some of the esoteric semantics described in Section 5. User agents, 339 however, MUST implement the requirements in Section 5 to ensure 340 interoperability with servers making use of the full semantics. 342 4.1. Set-Cookie 344 The Set-Cookie HTTP response header is used to send cookies from the 345 server to the user agent. 347 4.1.1. Syntax 349 Informally, the Set-Cookie response header contains the header name 350 "Set-Cookie" followed by a ":" and a cookie. Each cookie begins with 351 a name-value pair, followed by zero or more attribute-value pairs. 352 Servers SHOULD NOT send Set-Cookie headers that fail to conform to 353 the following grammar: 355 set-cookie-header = "Set-Cookie:" SP set-cookie-string 356 set-cookie-string = cookie-pair *( ";" SP cookie-av ) 357 cookie-pair = cookie-name "=" cookie-value 358 cookie-name = token 359 cookie-value = token 360 token = 362 cookie-av = expires-av / max-age-av / domain-av / 363 path-av / secure-av / httponly-av / 364 extension-av 365 expires-av = "Expires=" sane-cookie-date 366 sane-cookie-date = 367 max-age-av = "Max-Age=" 1*DIGIT 368 domain-av = "Domain=" domain-value 369 domain-value = 370 ; defined in [RFC1034], Section 3.5, as 371 ; enhanced by [RFC1123], Section 2.1 372 path-av = "Path=" path-value 373 path-value = 374 secure-av = "Secure" 375 httponly-av = "HttpOnly" 376 extension-av = 377 Note that some of the grammatical terms above reference documents 378 that use different grammatical notations than this document (which 379 uses ABNF from [RFC5234]). 381 The semantics of the cookie-value are not defined by this document. 383 To maximize compatibility with user agents, servers that wish to 384 store arbitrary data in a cookie-value SHOULD encode that data, for 385 example, using Base 16 [RFC4648]. 387 The portions of the set-cookie-string produced by the cookie-av term 388 are known as attributes. To maximize compatibility with user agents, 389 servers SHOULD NOT produce two attributes with the same name in the 390 same set-cookie-string. 392 Servers SHOULD NOT include more than one Set-Cookie header field in 393 the same response with the same cookie-name. 395 If a server sends multiple responses containing Set-Cookie headers 396 concurrently to the user agent (e.g., when communicating with the 397 user agent over multiple sockets), these responses create a "race 398 condition" that can lead to unpredictable behavior. 400 NOTE: Some existing user agents differ on their interpretation of 401 two-digit years. To avoid compatibility issues, servers SHOULD use 402 the rfc1123-date format, which requires a four-digit year. 404 NOTE: Some user agents represent dates using 32-bit UNIX time_t 405 values. Some of these user agents might contain bugs that cause them 406 to process dates after the year 2038 incorrectly. 408 4.1.2. Semantics (Non-Normative) 410 This section describes a simplified semantics of the Set-Cookie 411 header. These semantics are detailed enough to be useful for 412 understanding the most common uses of cookies by servers. The full 413 semantics are described in Section 5. 415 When the user agent receives a Set-Cookie header, the user agent 416 stores the cookie together with its attributes. Subsequently, when 417 the user agent makes an HTTP request, the user agent includes the 418 applicable, non-expired cookies in the Cookie header. 420 If the user agent receives a new cookie with the same cookie-name, 421 domain-value, and path-value as a cookie that it has already stored, 422 the existing cookie is evicted and replaced with the new cookie. 423 Notice that servers can delete cookies by sending the user agent a 424 new cookie with an Expires attribute with a value in the past. 426 Unless the cookie's attributes indicate otherwise, the cookie is 427 returned only to the origin server, and it expires at the end of the 428 current session (as defined by the user agent). User agents ignore 429 unrecognized cookie attributes (but not the entire cookie). 431 4.1.2.1. The Expires Attribute 433 The Expires attribute indicates the maximum lifetime of the cookie, 434 represented as the date and time at which the cookie expires. The 435 user agent is not required to retain the cookie until the specified 436 date has passed. In fact, user agents often evict cookies due to 437 memory pressure or privacy concerns. 439 4.1.2.2. The Max-Age Attribute 441 The Max-Age attribute indicates the maximum lifetime of the cookie, 442 represented as the number of seconds until the cookie expires. The 443 user agent is not required to retain the cookie for the specified 444 duration. In fact, user agents often evict cookies from due to 445 memory pressure or privacy concerns. 447 NOTE: Some existing user agents do not support the Max-Age 448 attribute. User agents that do not support the Max-Age attribute 449 ignore the attribute. 451 If a cookie has both the Max-Age and the Expires attribute, the Max- 452 Age attribute has precedence and controls the expiration date of the 453 cookie. If a cookie has neither the Max-Age nor the Expires 454 attribute, the user agent will retain the cookie until "the current 455 session is over" (as defined by the user agent). 457 4.1.2.3. The Domain Attribute 459 The Domain attribute specifies those hosts to which the cookie will 460 be sent. For example, if the value of the Domain attribute is 461 "example.com", the user agent will include the cookie in the Cookie 462 header when making HTTP requests to example.com, www.example.com, and 463 www.corp.example.com. (Note that a leading %x2E ("."), if present, 464 is ignored even though that character is not permitted.) If the 465 server omits the Domain attribute, the user agent will return the 466 cookie only to the origin server. 468 WARNING: Some existing user agents treat an absent Domain 469 attribute as if the Domain attribute were present and contained 470 the current host name. For example, if example.com returns a Set- 471 Cookie header without a Domain attribute, these user agents will 472 erroneously send the cookie to www.example.com as well. 474 The user agent will reject cookies unless the Domain attribute 475 specifies a scope for the cookie that would include the origin 476 server. For example, the user agent will accept a cookie with a 477 Domain attribute of "example.com" or of "foo.example.com" from 478 foo.example.com, but the user agent will not accept a cookie with a 479 Domain attribute of "bar.example.com" or of "baz.foo.example.com". 481 NOTE: For security reasons, many user agents are configured to reject 482 Domain attributes that correspond to "public suffixes". For example, 483 some user agents will reject Domain attributes of "com" or "co.uk". 484 (See Section 5.3 for more information.) 486 4.1.2.4. The Path Attribute 488 The scope of each cookie is limited to a set of paths, controlled by 489 the Path attribute. If the server omits the Path attribute, the user 490 agent will use the "directory" of the request-uri's path component as 491 the default value. (See Section 5.1.4 for more details.) 493 The user agent will include the cookie in an HTTP request only if the 494 path portion of the request-uri matches (or is a subdirectory of) the 495 cookie's Path attribute, where the %x2F ("/") character is 496 interpreted as a directory separator. 498 Although seemingly useful for isolating cookies between different 499 paths within a given host, the Path attribute cannot be relied upon 500 for security (see Section 8). 502 4.1.2.5. The Secure Attribute 504 The Secure attribute limits the scope of the cookie to "secure" 505 channels (where "secure" is defined by the user agent). When a 506 cookie has the Secure attribute, the user agent will include the 507 cookie in an HTTP request only if the request is transmitted over a 508 secure channel (typically HTTP over Secure Sockets Layer (SSL), HTTP 509 over Transport Layer Security (TLS) [RFC2818], and TLS [RFC5246] 510 itself). 512 Although seemingly useful for protecting cookies from active network 513 attackers, the Secure attribute protects only the cookie's 514 confidentiality. An active network attacker can overwrite Secure 515 cookies from an insecure channel, disrupting their integrity (see 516 Section 8.6 for more details). 518 4.1.2.6. The HttpOnly Attribute 520 The HttpOnly attribute limits the scope of the cookie to HTTP 521 requests. In particular, the attribute instructs the user agent to 522 omit the cookie when providing access to cookies via "non-HTTP" APIs 523 (such as a web browser API that exposes cookies to scripts). 525 4.2. Cookie 527 4.2.1. Syntax 529 The user agent sends stored cookies to the origin server in the 530 Cookie header. If the server conforms to the requirements in 531 Section 4.1 (and the user agent conforms to the requirements in 532 Section 5), the user agent will send a Cookie header that conforms to 533 the following grammar: 535 cookie-header = "Cookie:" OWS cookie-string OWS 536 cookie-string = cookie-pair *( ";" SP cookie-pair ) 538 4.2.2. Semantics 540 Each cookie-pair represents a cookie stored by the user agent. The 541 cookie-pair contains the cookie-name and cookie-value the user agent 542 received in the Set-Cookie header. 544 Notice that the cookie attributes are not returned. In particular, 545 the server cannot determine from the Cookie header alone when a 546 cookie will expire, for which hosts the cookie is valid, for which 547 paths the cookie is valid, or whether the cookie was set with the 548 Secure or HttpOnly attributes. 550 The semantics of individual cookies in the Cookie header are not 551 defined by this document. Servers are expected to imbue these 552 cookies with application-specific semantics. 554 Although cookies are serialized linearly in the Cookie header, 555 servers SHOULD NOT rely upon the serialization order. In particular, 556 if the Cookie header contains two cookies with the same name (e.g., 557 that were set with different Path or Domain attributes), servers 558 SHOULD NOT rely upon the order in which these cookies appear in the 559 header. 561 5. User Agent Requirements 563 For historical reasons, the full semantics of cookies (as presently 564 deployed on the Internet) contain a number of exotic quirks. This 565 section is intended to specify the Cookie and Set-Cookie headers in 566 sufficient detail to allow a user agent implementing these 567 requirements precisely to interoperate with existing servers. 569 5.1. Subcomponent Algorithms 571 This section defines some algorithms used by user agents to process 572 specific subcomponents of the Cookie and Set-Cookie headers. 574 5.1.1. Dates 576 The user agent MUST use an algorithm equivalent to the following 577 algorithm to parse a cookie-date. Note that the various boolean 578 flags defined as a part of the algorithm are initially "not set". 580 1. Using the grammar below, divide the cookie-date into date-tokens. 582 cookie-date = *delimiter date-token-list *delimiter 583 date-token-list = date-token *( 1*delimiter date-token ) 584 date-token = 1*non-delimiter 586 delimiter = %x09 / %x20-2F / %x3B-40 / %x5B-60 / %x7B-7E 587 non-delimiter = %x00-08 / %x0A-1F / DIGIT / ":" / ALPHA / %x7F-FF 588 non-digit = %x00-2F / %x3A-FF 590 day-of-month = 1*2DIGIT ( non-digit *OCTET ) 591 month = ( "jan" / "feb" / "mar" / "apr" / 592 "may" / "jun" / "jul" / "aug" / 593 "sep" / "oct" / "nov" / "dec" ) *OCTET 594 year = 1*4DIGIT ( non-digit *OCTET ) 595 time = hms-time ( non-digit *OCTET ) 596 hms-time = time-field ":" time-field ":" time-field 597 time-field = 1*2DIGIT 599 2. Process each date-token sequentially in the order the date-tokens 600 appear in the cookie-date: 602 1. If the found-time flag is not set and the token matches the 603 time production, set the found-time flag and set the hour- 604 value, minute-value, and second-value to the numbers denoted 605 by the digits in the date-token, respectively. Skip the 606 remaining sub-steps and continue to the next date-token. 608 2. If the found-day-of-month flag is not set and the date-token 609 matches the day-of-month production, set the found-day-of- 610 month flag and set the day-of-month-value to the number 611 denoted by the date-token. Skip the remaining sub-steps and 612 continue to the next date-token. 614 3. If the found-month flag is not set and the date-token matches 615 the month production, set the found-month flag and set the 616 month-value to the month denoted by the date-token. Skip the 617 remaining sub-steps and continue to the next date-token. 619 4. If the found-year flag is not set and the date-token matches 620 the year production, set the found-year flag and set the 621 year-value to the number denoted by the date-token. Skip the 622 remaining sub-steps and continue to the next date-token. 624 3. If the year-value is greater than or equal to 70 and less than or 625 equal to 99, increment the year-value by 1900. 627 4. If the year-value is greater than or equal to 0 and less than or 628 equal to 69, increment the year-value by 2000. 630 1. NOTE: Some existing user agents interpret two-digit years 631 differently. 633 5. Abort these steps and fail to parse the cookie-date if 635 * at least one of the found-day-of-month, found-month, found- 636 year, or found-time flags is not set, 638 * the day-of-month-value is less than 1 or greater than 31, 640 * the year-value is less than 1601, 642 * the hour-value is greater than 23, 644 * the minute-value is greater than 59, or 646 * the second-value is greater than 59. 648 6. Let the parsed-cookie-date be the date whose day-of-month, month, 649 year, hour, minute, and second (in UTC) are the day-of-month- 650 value, the month-value, the year-value, the hour-value, the 651 minute-value, and the second-value, respectively. If no such 652 date exists, abort these steps and fail to parse the cookie-date. 654 7. Return the parsed-cookie-date as the result of this algorithm. 656 5.1.2. Canonicalized host names 658 A canonicalized host name is the string generated by the following 659 algorithm: 661 1. Convert the host name to a sequence of individual domain name 662 labels. 664 2. Convert each label that is not a NR-LDH label, to a A-label (see 665 Section 2.3.2.1 of [RFC5890] for the fomer and latter), or to a 666 "punycode label" (a label resulting from the "ToASCII" conversion 667 in Section 4 of [RFC3490]), as appropriate (see Section 6.3 of 668 this specification). 670 3. Concatentate the resulting labels, separated by a %x2E (".") 671 character. 673 5.1.3. Domain matching 675 A string domain-matches a given domain string if at least one of the 676 following conditions hold: 678 o The domain string and the string are identical. 680 o All of the following conditions hold: 682 * The domain string is a suffix of the string. 684 * The last character of the string that is not included in the 685 domain string is a %x2E (".") character. 687 * The string is a host name (i.e., not an IP address). 689 5.1.4. Paths and path-match 691 The user agent MUST use an algorithm equivalent to the following 692 algorithm to compute the default-path of a cookie: 694 1. Let uri-path be the path portion of the request-uri if such a 695 portion exists (and empty otherwise). For example, if the 696 request-uri contains just a path (and optional query string), 697 then the uri-path is that path (without the %x3F ("?") character 698 or query string), and if the request-uri contains a full 699 absoluteURI, the uri-path is the path component of that URI. 701 2. If the uri-path is empty or if the first character of the uri- 702 path is not a %x2F ("/") character, output %x2F ("/") and skip 703 the remaining steps. 705 3. If the uri-path contains only a single %x2F ("/") character, 706 output %x2F ("/") and skip the remaining steps. 708 4. Output the characters of the uri-path from the first character up 709 to, but not including, the right-most %x2F ("/"). 711 A request-path path-matches a given cookie-path if at least one of 712 the following conditions hold: 714 o The cookie-path and the request-path are identical. 716 o The cookie-path is a prefix of the request-path and the last 717 character of the cookie-path is %x2F ("/"). 719 o The cookie-path is a prefix of the request-path and the first 720 character of the request-path that is not included in the cookie- 721 path is a %x2F ("/") character. 723 5.2. The Set-Cookie Header 725 When a user agent receives a Set-Cookie header field in an HTTP 726 response, the user agent MAY ignore the Set-Cookie header field in 727 its entirety. For example, the user agent might wish to block 728 responses to "third-party" requests from setting cookies. 730 If the user agent does not ignore the Set-Cookie header field in its 731 entirety, the user agent MUST parse the field-value of the Set-Cookie 732 header field as a set-cookie-string (defined below). 734 NOTE: The algorithm below is more permissive than the grammar in 735 Section 4.1. For example, the algorithm strips leading and trailing 736 whitespace from the cookie name and value (but maintains internal 737 whitespace), whereas the grammar in Section 4.1 forbids whitespace in 738 these positions. User agents use this algorithm so as to 739 interoperate with servers that do not follow the recommendations in 740 Section 4. 742 A user agent MUST use an algorithm equivalent to the following 743 algorithm to parse a "set-cookie-string": 745 1. If the set-cookie-string contains a %x3B (";") character: 747 The name-value-pair string consists of the characters up to, 748 but not including, the first %x3B (";"), and the unparsed- 749 attributes consist of the remainder of the set-cookie-string 750 (including the %x3B (";") in question). 752 Otherwise: 754 The name-value-pair string consists of all the characters 755 contained in the set-cookie-string, and the unparsed- 756 attributes is the empty string. 758 2. If the name-value-pair string lacks a %x3D ("=") character, 759 ignore the set-cookie-string entirely. 761 3. The (possibly empty) name string consists of the characters up 762 to, but not including, the first %x3D ("=") character, and the 763 (possibly empty) value string consists of the characters after 764 the first %x3D ("=") character. 766 4. Remove any leading or trailing WSP characters from the name 767 string and the value string. 769 5. If the name string is empty, ignore the set-cookie-string 770 entirely. 772 6. The cookie-name is the name string, and the cookie-value is the 773 value string. 775 The user agent MUST use an algorithm equivalent to the following 776 algorithm to parse the unparsed-attributes: 778 1. If the unparsed-attributes string is empty, skip the rest of 779 these steps. 781 2. Discard the first character of the unparsed-attributes (which 782 will be a %x3B (";") character). 784 3. If the remaining unparsed-attributes contains a %x3B (";") 785 character: 787 Consume the characters of the unparsed-attributes up to, but 788 not including, the first %x3B (";") character. 790 Otherwise: 792 Consume the remainder of the unparsed-attributes. 794 Let the cookie-av string be the characters consumed in this step. 796 4. If the cookie-av string contains a %x3D ("=") character: 798 The (possibly empty) attribute-name string consists of the 799 characters up to, but not including, the first %x3D ("=") 800 character, and the (possibly empty) attribute-value string 801 consists of the characters after the first %x3D ("=") 802 character. 804 Otherwise: 806 The attribute-name string consists of the entire cookie-av 807 string, and the attribute-value string is empty. 809 5. Remove any leading or trailing WSP characters from the attribute- 810 name string and the attribute-value string. 812 6. Process the attribute-name and attribute-value according to the 813 requirements in the following subsections. (Notice that 814 attributes with unrecognized attribute-names are ignored.) 816 7. Return to Step 1 of this algorithm. 818 When the user agent finishes parsing the set-cookie-string, the user 819 agent is said to "receive a cookie" from the request-uri with name 820 cookie-name, value cookie-value, and attributes cookie-attribute- 821 list. (See Section 5.3 for additional requirements triggered by 822 receiving a cookie.) 824 5.2.1. The Expires Attribute 826 If the attribute-name case-insensitively matches the string 827 "Expires", the user agent MUST process the cookie-av as follows. 829 Let the expiry-time be the result of parsing the attribute-value as 830 cookie-date (see Section 5.1.1). 832 If the attribute-value failed to parse as a cookie date, ignore the 833 cookie-av. 835 If the expiry-time is later than the last date the user agent can 836 represent, the user agent MAY replace the expiry-time with the last 837 representable date. 839 If the expiry-time is earlier than the earliest date the user agent 840 can represent, the user agent MAY replace the expiry-time with the 841 earliest representable date. 843 Append an attribute to the cookie-attribute-list with an attribute- 844 name of Expires and an attribute-value of expiry-time. 846 5.2.2. The Max-Age Attribute 848 If the attribute-name case-insensitively matches the string "Max- 849 Age", the user agent MUST process the cookie-av as follows. 851 If the first character of the attribute-value is not a DIGIT or a "-" 852 character, ignore the cookie-av. 854 If the remainder of attribute-value contains a non-DIGIT character, 855 ignore the cookie-av. 857 Let delta-seconds be the attribute-value converted to an integer. 859 If delta-seconds is less than or equal to zero (0), let expiry-time 860 be the earliest representable date and time. Otherwise, let the 861 expiry-time be the current date and time plus delta-seconds seconds. 863 Append an attribute to the cookie-attribute-list with an attribute- 864 name of Max-Age and an attribute-value of expiry-time. 866 5.2.3. The Domain Attribute 868 If the attribute-name case-insensitively matches the string "Domain", 869 the user agent MUST process the cookie-av as follows. 871 If the attribute-value is empty, the behavior is undefined. However, 872 user agent SHOULD ignore the cookie-av entirely. 874 If the first character of the attribute-value string is %x2E ("."): 876 Let cookie-domain be the attribute-value without the leading %x2E 877 (".") character. 879 Otherwise: 881 Let cookie-domain be the entire attribute-value. 883 Convert the cookie-domain to lower case. 885 Append an attribute to the cookie-attribute-list with an attribute- 886 name of Domain and an attribute-value of cookie-domain. 888 5.2.4. The Path Attribute 890 If the attribute-name case-insensitively matches the string "Path", 891 the user agent MUST process the cookie-av as follows. 893 If the attribute-value is empty or if the first character of the 894 attribute-value is not %x2F ("/"): 896 Let cookie-path be the default-path. 898 Otherwise: 900 Let cookie-path be the attribute-value. 902 Append an attribute to the cookie-attribute-list with an attribute- 903 name of Path and an attribute-value of cookie-path. 905 5.2.5. The Secure Attribute 907 If the attribute-name case-insensitively matches the string "Secure", 908 the user agent MUST append an attribute to the cookie-attribute-list 909 with an attribute-name of Secure and an empty attribute-value. 911 5.2.6. The HttpOnly Attribute 913 If the attribute-name case-insensitively matches the string 914 "HttpOnly", the user agent MUST append an attribute to the cookie- 915 attribute-list with an attribute-name of HttpOnly and an empty 916 attribute-value. 918 5.3. Storage Model 920 The user agent stores the following fields about each cookie: name, 921 value, expiry-time, domain, path, creation-time, last-access-time, 922 persistent-flag, host-only-flag, secure-only-flag, and http-only- 923 flag. 925 When the user agent "receives a cookie" from a request-uri with name 926 cookie-name, value cookie-value, and attributes cookie-attribute- 927 list, the user agent MUST process the cookie as follows: 929 1. A user agent MAY ignore a received cookie in its entirety. For 930 example, the user agent might wish to block receiving cookies 931 from "third-party" responses or the user agent might not wish to 932 store cookies that exceed some size. 934 2. Create a new cookie with name cookie-name, value cookie-value. 935 Set the creation-time and the last-access-time to the current 936 date and time. 938 3. If the cookie-attribute-list contains an attribute with an 939 attribute-name of "Max-Age": 941 Set the cookie's persistent-flag to true. 943 Set the cookie's expiry-time to attribute-value of the last 944 attribute in the cookie-attribute-list with an attribute-name 945 of "Max-Age". 947 Otherwise, if the cookie-attribute-list contains an attribute 948 with an attribute-name of "Expires" (and does not contain an 949 attribute with an attribute-name of "Max-Age"): 951 Set the cookie's persistent-flag to true. 953 Set the cookie's expiry-time to attribute-value of the last 954 attribute in the cookie-attribute-list with an attribute-name 955 of "Expires". 957 Otherwise: 959 Set the cookie's persistent-flag to false. 961 Set the cookie's expiry-time to the latest representable 962 date. 964 4. If the cookie-attribute-list contains an attribute with an 965 attribute-name of "Domain": 967 Let the domain-attribute be the attribute-value of the last 968 attribute in the cookie-attribute-list with an attribute-name 969 of "Domain". 971 Otherwise: 973 Let the domain-attribute be the empty string. 975 5. If the user agent is configured to reject "public suffixes" and 976 the domain-attribute is a public suffix: 978 If the domain-attribute is identical to the canonicalized 979 request-host: 981 Let the domain-attribute be the empty string. 983 Otherwise: 985 Ignore the cookie entirely and abort these steps. 987 NOTE: A "public suffix" is a domain that is controlled by a 988 public registry, such as "com", "co.uk", and "pvt.k12.wy.us". 989 This step is essential for preventing attacker.com from 990 disrupting the integrity of example.com by setting a cookie 991 with a Domain attribute of "com". Unfortunately, the set of 992 public suffixes (also known as "registry controlled domains") 993 changes over time. If feasible, user agents SHOULD use an 994 up-to-date public suffix list, such as the one maintained by 995 the Mozilla project at . 997 6. If the domain-attribute is non-empty: 999 If the canonicalized request-host does not domain-match the 1000 domain-attribute: 1002 Ignore the cookie entirely and abort these steps. 1004 Otherwise: 1006 Set the cookie's host-only-flag to false. 1008 Set the cookie's domain to the domain-attribute. 1010 Otherwise: 1012 Set the cookie's host-only-flag to true. 1014 Set the cookie's domain to the canonicalized request-host. 1016 7. If the cookie-attribute-list contains an attribute with an 1017 attribute-name of "Path", set the cookie's path to attribute- 1018 value of the last attribute in the cookie-attribute-list with an 1019 attribute-name of "Path". Otherwise, set cookie's path to the 1020 default-path of the request-uri. 1022 8. If the cookie-attribute-list contains an attribute with an 1023 attribute-name of "Secure", set the cookie's secure-only-flag to 1024 true. Otherwise, set cookie's secure-only-flag to false. 1026 9. If the cookie-attribute-list contains an attribute with an 1027 attribute-name of "HttpOnly", set the cookie's http-only-flag to 1028 true. Otherwise, set cookie's http-only-flag to false. 1030 10. If the cookie was received from a "non-HTTP" API and the 1031 cookie's http-only-flag is set, abort these steps and ignore the 1032 cookie entirely. 1034 11. If the cookie store contains a cookie with the same name, 1035 domain, and path as the newly created cookie: 1037 1. Let old-cookie be the existing cookie with the same name, 1038 domain, and path as the newly created cookie. (Notice that 1039 this algorithm maintains the invariant that there is at most 1040 one such cookie.) 1042 2. If the newly created cookie was received from a "non-HTTP" 1043 API and the old-cookie's http-only-flag is set, abort these 1044 steps and ignore the newly created cookie entirely. 1046 3. Update the creation-time of the newly created cookie to 1047 match the creation-time of the old-cookie. 1049 4. Remove the old-cookie from the cookie store. 1051 12. Insert the newly created cookie into the cookie store. 1053 A cookie is "expired" if the cookie has an expiry date in the past. 1055 The user agent MUST evict all expired cookies from the cookie store 1056 if, at any time, an expired cookie exists in the cookie store. 1058 At any time, the user agent MAY "remove excess cookies" from the 1059 cookie store if the number of cookies sharing a domain field exceeds 1060 some implementation defined upper bound (such as 50 cookies). 1062 At any time, the user agent MAY "remove excess cookies" from the 1063 cookie store if the cookie store exceeds some predetermined upper 1064 bound (such as 3000 cookies). 1066 When the user agent removes excess cookies from the cookie store, the 1067 user agent MUST evict cookies in the following priority order: 1069 1. Expired cookies. 1071 2. Cookies that share a domain field with more than a predetermined 1072 number of other cookies. 1074 3. All cookies. 1076 If two cookies have the same removal priority, the user agent MUST 1077 evict the cookie with the earliest last-access date first. 1079 When "the current session is over" (as defined by the user agent), 1080 the user agent MUST remove from the cookie store all cookies with the 1081 persistent-flag set to false. 1083 5.4. The Cookie Header 1085 The user agent includes stored cookies in the Cookie HTTP request 1086 header. 1088 When the user agent generates an HTTP request, the user agent MUST 1089 NOT attach more than one Cookie header field. 1091 A user agent MAY omit the Cookie header in its entirety. For 1092 example, the user agent might wish to block sending cookies during 1093 "third-party" requests. 1095 If the user agent does attach a Cookie header field to an HTTP 1096 request, the user agent MUST send the cookie-string (defined below) 1097 as the value of the header field. 1099 The user agent MUST use an algorithm equivalent to the following 1100 algorithm to compute the "cookie-string" from a cookie store and a 1101 request-uri: 1103 1. Let cookie-list be the set of cookies from the cookie store that 1104 meet all of the following requirements: 1106 * Either: 1108 The cookie's host-only-flag is true and the canonicalized 1109 request-host is identical to the cookie's domain. 1111 Or: 1113 The cookie's host-only-flag is false and the canonicalized 1114 request-host domain-matches cookie's domain. 1116 * The request-uri's path path-matches cookie's path. 1118 * If the cookie's secure-only-flag is true, then the request- 1119 uri's scheme must denote a "secure" protocol (as defined by 1120 the user agent). 1122 NOTE: The notion of a "secure" protocol is not defined by 1123 this document. Typically, user agents consider a protocol 1124 secure if the protocol makes use of transport-layer 1125 security, such as SSL or TLS. For example, most user 1126 agents consider "https" to be a scheme that denotes a 1127 secure protocol. 1129 * If the cookie's http-only-flag is true, then exclude the 1130 cookie if the cookie-string is being generated for a "non- 1131 HTTP" API (as defined by the user agent). 1133 2. The user agent SHOULD sort the cookie-list in the following 1134 order: 1136 * Cookies with longer paths are listed before cookies with 1137 shorter paths. 1139 * Among cookies that have equal length path fields, cookies with 1140 earlier creation-times are listed before cookies with later 1141 creation-times. 1143 NOTE: Not all user agents sort the cookie-list in this order, but 1144 this order reflects common practice when this document was 1145 written, and, historically, there have been servers that 1146 (erroneously) depended on this order. 1148 3. Update the last-access-time of each cookie in the cookie-list to 1149 the current date and time. 1151 4. Serialize the cookie-list into a cookie-string by processing each 1152 cookie in the cookie-list in order: 1154 1. Output the cookie's name, the %x3D ("=") character, and the 1155 cookie's value. 1157 2. If there is an unprocessed cookie in the cookie-list, output 1158 the characters %x3B and %x20 ("; "). 1160 NOTE: Despite its name, the cookie-string is actually a sequence of 1161 octets, not a sequence of characters. To convert the cookie-string 1162 (or components thereof) into a sequence of characters (e.g., for 1163 presentation to the user), the user agent might wish use the UTF-8 1164 character encoding [RFC3629] to decode the octet sequence. 1166 6. Implementation Considerations 1168 6.1. Limits 1170 Practical user agent implementations have limits on the number and 1171 size of cookies that they can store. General-use user agents SHOULD 1172 provide each of the following minimum capabilities: 1174 o At least 4096 bytes per cookie (as measured by the sum of the 1175 length of the cookie's name, value, and attributes). 1177 o At least 50 cookies per domain. 1179 o At least 3000 cookies total. 1181 Servers SHOULD use as few and as small cookies as possible to avoid 1182 reaching these implementation limits and to minimize network 1183 bandwidth due to the Cookie header being included in every request. 1185 Servers SHOULD gracefully degrade if the user agent fails to return 1186 one or more cookies in the Cookie header because the user agent might 1187 evict any cookie at any time on orders from the user. 1189 6.2. Application Programming Interfaces 1191 One reason the Cookie and Set-Cookie headers uses such esoteric 1192 syntax is because many platforms (both in servers and user agents) 1193 provide a string-based application programing interface (API) to 1194 cookies, requiring application-layer programmers to generate and 1195 parse the syntax used by the Cookie and Set-Cookie headers, which 1196 many programmers have done incorrectly, resulting in interoperability 1197 problems. 1199 Instead of providing string-based APIs to cookies, platforms would be 1200 well-served by providing more semantic APIs. It is beyond the scope 1201 of this document to recommend specific API designs, but there are 1202 clear benefits to accepting an abstract "Date" object instead of a 1203 serialized date string. 1205 6.3. IDNA dependency and migration 1207 IDNA2008 [RFC5890] supersedes IDNA2003 [RFC3490]. However, there are 1208 differences between the two specifications, and thus there can be 1209 differences in processing (e.g. converting) domain name labels that 1210 have been registered under one from those registered under the other. 1211 There will be a transition period of some time during which IDNA2003- 1212 based domain name labels will exist in the wild. User agents SHOULD 1213 implement IDNA2008 [RFC5890] and MAY implement [UTS46] or [RFC5895] 1214 in order to facilitate their IDNA transition. If a user agent does 1215 not implement IDNA2008, the user agent MUST implement IDNA2003 1216 [RFC3490]. 1218 7. Privacy Considerations 1220 Cookies are often criticized for letting servers track users. For 1221 example, a number of "web analytics" companies use cookies to 1222 recognize when a user returns to a web site or visits another web 1223 site. Although cookies are not the only mechanism servers can use to 1224 track users across HTTP requests, cookies facilitate tracking because 1225 they are persistent across user agent sessions and can be shared 1226 between hosts. 1228 7.1. Third-Party Cookies 1230 Particularly worrisome are so-called "third-party" cookies. In 1231 rendering an HTML document, a user agent often requests resources 1232 from other servers (such as advertising networks). These third-party 1233 servers can use cookies to track the user even if the user never 1234 visits the server directly. 1236 Some user agents restrict how third-party cookies behave. For 1237 example, some of these user agents refuse to send the Cookie header 1238 in third-party requests. Others refuse to process the Set-Cookie 1239 header in responses to third-party requests. User agents vary widely 1240 in their third-party cookie policies. This document grants user 1241 agents wide latitude to experiment with third-party cookie policies 1242 that balance the privacy and compatibility needs of their users. 1243 However, this document does not endorse any particular third-party 1244 cookie policy. 1246 Third-party cookie blocking policies are often ineffective at 1247 achieving their privacy goals if servers attempt to work around their 1248 restrictions to track users. In particular, two collaborating 1249 servers can often track users without using cookies at all. 1251 7.2. User Controls 1253 User agents should provide users with a mechanism for managing the 1254 cookies stored in the cookie store. For example, a user agent might 1255 let users delete all cookies received during a specified time period 1256 or all the cookies related to a particular domain. In addition, many 1257 user agents include a user interface element that lets users examine 1258 the cookies stored in their cookie store. 1260 User agents should provide users with a mechanism for disabling 1261 cookies. When cookies are disabled, the user agent MUST NOT include 1262 a Cookie header in outbound HTTP requests and the user agent MUST NOT 1263 process Set-Cookie headers in inbound HTTP responses. 1265 Some user agents provide users the option of preventing persistent 1266 storage of cookies across sessions. When configured thusly, user 1267 agents MUST treat all received cookies as if the persistent-flag were 1268 set to false. 1270 Some user agents provide users with the ability to approve individual 1271 writes to the cookie store. In many common usage scenarios, these 1272 controls generate a large number of prompts. However, some privacy- 1273 conscious users find these controls useful nonetheless. 1275 8. Security Considerations 1277 8.1. Overview 1279 Cookies have a number of security pitfalls. This section overviews a 1280 few of the more salient issues. 1282 In particular, cookies encourage developers to rely on ambient 1283 authority for authentication, often becoming vulnerable to attacks 1284 such as cross-site request forgery. Also, when storing session 1285 identifiers in cookies, developers often create session fixation 1286 vulnerabilities. 1288 Transport-layer encryption, such as that employed in HTTPS, is 1289 insufficient to prevent a network attacker from obtaining or altering 1290 a victim's cookies because the cookie protocol itself has various 1291 vulnerabilities (see "Weak Confidentiality" and "Weak Integrity", 1292 below). In addition, by default, cookies do not provide 1293 confidentiality or integrity from network attackers, even when used 1294 in conjunction with HTTPS. 1296 8.2. Ambient Authority 1298 A server that uses cookies to authenticate users can suffer security 1299 vulnerabilities because some user agents let remote parties issue 1300 HTTP requests from the user agent (e.g., via HTTP redirects or HTML 1301 forms). When issuing those requests, user agents attach cookies even 1302 if the remote party does not know the contents of the cookies, 1303 potentially letting the remote party exercise authority at an unwary 1304 server. 1306 Although this security concern goes by a number of names (e.g., 1307 cross-site request forgery, confused deputy), the issue stems from 1308 cookies being a form of ambient authority. Cookies encourage server 1309 operators to separate designation (in the form of URLs) from 1310 authorization (in the form of cookies). Consequently, the user agent 1311 might supply the authorization for a resource designated by the 1312 attacker, possibly causing the server or its clients to undertake 1313 actions designated by the attacker as though they were authorized by 1314 the user. 1316 Instead of using cookies for authorization, server operators might 1317 wish to consider entangling designation and authorization by treating 1318 URLs as capabilities. Instead of storing secrets in cookies, this 1319 approach stores secrets in URLs, requiring the remote entity to 1320 supply the secret itself. Although this approach is not a panacea, 1321 judicious application of these principles can lead to more robust 1322 security. 1324 8.3. Clear Text 1326 Unless sent over a secure channel (such as TLS), the information in 1327 the Cookie and Set-Cookie headers is transmitted in the clear. 1329 1. All sensitive information conveyed in these headers is exposed to 1330 an eavesdropper. 1332 2. A malicious intermediary could alter the headers as they travel 1333 in either direction, with unpredictable results. 1335 3. A malicious client could alter the Cookie header before 1336 transmission, with unpredictable results. 1338 Servers SHOULD encrypt and sign the contents of cookies when 1339 transmitting them to the user agent (even when sending the cookies 1340 over a secure channel). However, encrypting and signing cookie 1341 contents does not prevent an attacker from transplanting a cookie 1342 from one user agent to another or from replaying the cookie at a 1343 later time. 1345 In addition to encrypting and signing the contents of every cookie, 1346 servers that require a higher level of security SHOULD use the Cookie 1347 and Set-Cookie headers only over a secure channel. When using 1348 cookies over a secure channel, servers SHOULD set the Secure 1349 attribute (see Section 4.1.2.5) for every cookie. If a server does 1350 not set the Secure attribute, the protection provided by the secure 1351 channel will be largely moot. 1353 8.4. Session Identifiers 1355 Instead of storing session information directly in a cookie (where it 1356 might be exposed to or replayed by an attacker), servers commonly 1357 store a nonce (or "session identifier") in a cookie. When the server 1358 receives an HTTP request with a nonce, the server can look up state 1359 information associated with the cookie using the nonce as a key. 1361 Using session identifier cookies limits the damage an attacker can 1362 cause if the attacker learns the contents of a cookie because the 1363 nonce is useful only for interacting with the server (unlike non- 1364 nonce cookie content, which might itself be sensitive). Furthermore, 1365 using a single nonce prevents an attacker from "splicing" together 1366 cookie content from two interactions with the server, which could 1367 cause the server to behave unexpectedly. 1369 Using session identifiers is not without risk. For example, the 1370 server SHOULD take care to avoid "session fixation" vulnerabilities. 1371 A session fixation attack proceeds in three steps. First, the 1372 attacker transplants a session identifier from his or her user agent 1373 to the victim's user agent. Second, the victim uses that session 1374 identifier to interact with the server, possibly imbuing the session 1375 identifier with the user's credentials or confidential information. 1376 Third, the attacker uses the session identifier to interact with 1377 server directly, possibly obtaining the user's authority or 1378 confidential information. 1380 8.5. Weak Confidentiality 1382 Cookies do not provide isolation by port. If a cookie is readable by 1383 a service running on one port, the cookie is also readable by a 1384 service running on another port of the same server. If a cookie is 1385 writable by a service on one port, the cookie is also writable by a 1386 service running on another port of the same server. For this reason, 1387 servers SHOULD NOT both run mutually distrusting services on 1388 different ports of the same host and use cookies to store security- 1389 sensitive information. 1391 Cookies do not provide isolation by scheme. Although most commonly 1392 used with the http and https schemes, the cookies for a given host 1393 might also be available to other schemes, such as ftp and gopher. 1394 Although this lack of isolation by scheme is most apparent in non- 1395 HTTP APIs that permit access to cookies (e.g., HTML's document.cookie 1396 API), the lack of isolation by scheme is actually present in 1397 requirements for processing cookies themselves (e.g., consider 1398 retrieving a URI with the gopher scheme via HTTP). 1400 Cookies do not always provide isolation by path. Although the 1401 network-level protocol does not send cookies stored for one path to 1402 another, some user agents expose cookies via non-HTTP APIs, such as 1403 HTML's document.cookie API. Because some of these user agents (e.g., 1404 web browsers) do not isolate resources received from different paths, 1405 a resource retrieved from one path might be able to access cookies 1406 stored for another path. 1408 8.6. Weak Integrity 1410 Cookies do not provide integrity guarantees for sibling domains (and 1411 their subdomains). For example, consider foo.example.com and 1412 bar.example.com. The foo.example.com server can set a cookie with a 1413 Domain attribute of "example.com" (possibly overwriting an existing 1414 "example.com" cookie set by bar.example.com), and the user agent will 1415 include that cookie in HTTP requests to bar.example.com. In the 1416 worst case, bar.example.com will be unable to distinguish this cookie 1417 from a cookie it set itself. The foo.example.com server might be 1418 able to leverage this ability to mount an attack against 1419 bar.example.com. 1421 Even though the Set-Cookie header supports the Path attribute, the 1422 Path attribute does not provide any integrity protection because the 1423 user agent will accept an arbitrary Path attribute in a Set-Cookie 1424 header. For example, an HTTP response to a request for 1425 http://example.com/foo/bar can set a cookie with a Path attribute of 1426 "/qux". Consequently, servers SHOULD NOT both run mutually 1427 distrusting services on different paths of the same host and use 1428 cookies to store security-sensitive information. 1430 An active network attacker can also inject cookies into the Cookie 1431 header sent to https://example.com/ by impersonating a response from 1432 http://example.com/ and injecting a Set-Cookie header. The HTTPS 1433 server at example.com will be unable to distinguish these cookies 1434 from cookies that it set itself in an HTTPS response. An active 1435 network attacker might be able to leverage this ability to mount an 1436 attack against example.com even if example.com uses HTTPS 1437 exclusively. 1439 Servers can partially mitigate these attacks by encrypting and 1440 signing the contents of their cookies. However, using cryptography 1441 does not mitigate the issue completely because an attacker can replay 1442 a cookie he or she received from the authentic example.com server in 1443 the user's session, with unpredictable results. 1445 Finally, an attacker might be able to force the user agent to delete 1446 cookies by storing a large number of cookies. Once the user agent 1447 reaches its storage limit, the user agent will be forced to evict 1448 some cookies. Servers SHOULD NOT rely upon user agents retaining 1449 cookies. 1451 8.7. Reliance on DNS 1453 Cookies rely upon the Domain Name System (DNS) for security. If the 1454 DNS is partially or fully compromised, the cookie protocol might fail 1455 to provide the security properties required by applications. 1457 9. IANA Considerations 1459 The permanent message header field registry (see [RFC3864]) should be 1460 updated with the following registrations: 1462 9.1. Cookie 1464 Header field name: Cookie 1466 Applicable protocol: http 1468 Status: standard 1470 Author/Change controller: IETF 1472 Specification document: this specification (Section 5.4) 1474 9.2. Set-Cookie 1476 Header field name: Set-Cookie 1478 Applicable protocol: http 1480 Status: standard 1482 Author/Change controller: IETF 1484 Specification document: this specification (Section 5.2) 1486 10. References 1488 10.1. Normative References 1490 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 1491 STD 13, RFC 1034, November 1987. 1493 [RFC1123] Braden, R., "Requirements for Internet Hosts - Application 1494 and Support", STD 3, RFC 1123, October 1989. 1496 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1497 Requirement Levels", BCP 14, RFC 2119, March 1997. 1499 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1500 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1501 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1503 [RFC3490] Faltstrom, P., Hoffman, P., and A. Costello, 1504 "Internationalizing Domain Names in Applications (IDNA)", 1505 RFC 3490, March 2003. 1507 See Section 6.3 for an explanation why the normative 1508 reference to an obsoleted specification is needed. 1510 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1511 10646", STD 63, RFC 3629, November 2003. 1513 [RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet 1514 Application Protocol Collation Registry", RFC 4790, 1515 March 2007. 1517 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1518 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1520 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1521 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1523 [RFC5890] Klensin, J., "Internationalized Domain Names for 1524 Applications (IDNA): Definitions and Document Framework", 1525 RFC 5890, August 2010. 1527 10.2. Informative References 1529 [RFC2109] Kristol, D. and L. Montulli, "HTTP State Management 1530 Mechanism", RFC 2109, February 1997. 1532 [RFC2965] Kristol, D. and L. Montulli, "HTTP State Management 1533 Mechanism", RFC 2965, October 2000. 1535 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1537 [Netscape] 1538 Netscape Communications Corp., "Persistent Client State -- 1539 HTTP Cookies", 1999, . 1543 [Kri2001] Kristol, D., "HTTP Cookies: Standards, Privacy, and 1544 Politics", ACM Transactions on Internet Technology Vol. 1, 1545 #2, November 2001, . 1547 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1548 Encodings", RFC 4648, October 2006. 1550 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1551 Procedures for Message Header Fields", BCP 90, RFC 3864, 1552 September 2004. 1554 [RFC5895] Resnick, P. and P. Hoffman, "Mapping Characters for 1555 Internationalized Domain Names in Applications (IDNA) 1556 2008", RFC 5895, September 2010. 1558 [UTS46] Davis, M. and M. Suignard, "Unicode IDNA Compatibility 1559 Processing", Unicode Technical Standards # 46, 2010, 1560 . 1562 Appendix A. Acknowledgements 1564 This document borrows heavily from RFC 2109 [RFC2109]. We are 1565 indebted to David M. Kristol and Lou Montulli for their efforts to 1566 specify cookies. David M. Kristol, in particular, provided 1567 invaluable advice on navigating the IETF process. We would also like 1568 to thank Thomas Broyer, Tyler Close, Bil Corry, corvid, Lisa 1569 Dusseault, Roy T. Fielding, Blake Frantz, Anne van Kesteren, Eran 1570 Hammer-Lahav, Jeff Hodges, Bjoern Hoehrmann, Achim Hoffmann, Georg 1571 Koppen, Dean McNamee, Mark Miller, Mark Pauley, Yngve N. Pettersen, 1572 Julian Reschke, Peter Saint-Andre, Mark Seaborn, Maciej Stachowiak, 1573 Daniel Stenberg, Tatsuhiro Tsujikawa, David Wagner, Dan Winship, and 1574 Dan Witte for their valuable feedback on this document. 1576 Author's Address 1578 Adam Barth 1579 University of California, Berkeley 1581 Email: abarth@eecs.berkeley.edu 1582 URI: http://www.adambarth.com/