idnits 2.17.1 draft-ietf-httpstate-cookie-14.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (See https://trustee.ietf.org/license-info/) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. -- The draft header indicates that this document obsoletes RFC2109, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (September 30, 2010) is 4956 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: 4 errors (**), 0 flaws (~~), 4 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: 2109 (if approved) September 30, 2010 5 Intended status: Standards Track 6 Expires: April 3, 2011 8 HTTP State Management Mechanism 9 draft-ietf-httpstate-cookie-14 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 to IETF 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), its areas, and its working groups. Note that 35 other groups may also distribute working documents as Internet- 36 Drafts. 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 The list of current Internet-Drafts can be accessed at 44 http://www.ietf.org/ietf/1id-abstracts.txt. 46 The list of Internet-Draft Shadow Directories can be accessed at 47 http://www.ietf.org/shadow.html. 49 This Internet-Draft will expire on April 3, 2011. 51 Copyright Notice 53 Copyright (c) 2010 IETF Trust and the persons identified as the 54 document authors. All rights reserved. 56 This document is subject to BCP 78 and the IETF Trust's Legal 57 Provisions Relating to IETF Documents 58 (http://trustee.ietf.org/license-info) in effect on the date of 59 publication of this document. Please review these documents 60 carefully, as they describe your rights and restrictions with respect 61 to this document. Code Components extracted from this document must 62 include Simplified BSD License text as described in Section 4.e of 63 the Trust Legal Provisions and are provided without warranty as 64 described in the BSD License. 66 This document may contain material from IETF Documents or IETF 67 Contributions published or made publicly available before November 68 10, 2008. The person(s) controlling the copyright in some of this 69 material may not have granted the IETF Trust the right to allow 70 modifications of such material outside the IETF Standards Process. 71 Without obtaining an adequate license from the person(s) controlling 72 the copyright in such materials, this document may not be modified 73 outside the IETF Standards Process, and derivative works of it may 74 not be created outside the IETF Standards Process, except to format 75 it for publication as an RFC or to translate it into languages other 76 than English. 78 Table of Contents 80 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 81 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 6 82 2.1. Conformance Criteria . . . . . . . . . . . . . . . . . . . 6 83 2.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 6 84 2.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 85 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 86 3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 8 87 4. Server Requirements . . . . . . . . . . . . . . . . . . . . . 11 88 4.1. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . . 11 89 4.1.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . 11 90 4.1.2. Semantics (Non-Normative) . . . . . . . . . . . . . . 12 91 4.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . . 15 92 4.2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . 15 93 4.2.2. Semantics . . . . . . . . . . . . . . . . . . . . . . 15 94 5. User Agent Requirements . . . . . . . . . . . . . . . . . . . 16 95 5.1. Subcomponent Algorithms . . . . . . . . . . . . . . . . . 16 96 5.1.1. Dates . . . . . . . . . . . . . . . . . . . . . . . . 16 97 5.1.2. Canonicalized host names . . . . . . . . . . . . . . . 18 98 5.1.3. Domain matching . . . . . . . . . . . . . . . . . . . 18 99 5.1.4. Paths and path-match . . . . . . . . . . . . . . . . . 18 100 5.2. The Set-Cookie Header . . . . . . . . . . . . . . . . . . 19 101 5.2.1. The Expires Attribute . . . . . . . . . . . . . . . . 21 102 5.2.2. The Max-Age Attribute . . . . . . . . . . . . . . . . 21 103 5.2.3. The Domain Attribute . . . . . . . . . . . . . . . . . 22 104 5.2.4. The Path Attribute . . . . . . . . . . . . . . . . . . 22 105 5.2.5. The Secure Attribute . . . . . . . . . . . . . . . . . 23 106 5.2.6. The HttpOnly Attribute . . . . . . . . . . . . . . . . 23 107 5.3. Storage Model . . . . . . . . . . . . . . . . . . . . . . 23 108 5.4. The Cookie Header . . . . . . . . . . . . . . . . . . . . 26 109 6. Implementation Considerations . . . . . . . . . . . . . . . . 29 110 6.1. Limits . . . . . . . . . . . . . . . . . . . . . . . . . . 29 111 6.2. Application Programming Interfaces . . . . . . . . . . . . 29 112 6.3. IDNA dependency and migration . . . . . . . . . . . . . . 29 113 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 30 114 7.1. Third-Party Cookies . . . . . . . . . . . . . . . . . . . 30 115 7.2. User Controls . . . . . . . . . . . . . . . . . . . . . . 30 117 8. Security Considerations . . . . . . . . . . . . . . . . . . . 32 118 8.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 32 119 8.2. Ambient Authority . . . . . . . . . . . . . . . . . . . . 32 120 8.3. Clear Text . . . . . . . . . . . . . . . . . . . . . . . . 33 121 8.4. Session Identifiers . . . . . . . . . . . . . . . . . . . 33 122 8.5. Weak Confidentiality . . . . . . . . . . . . . . . . . . . 34 123 8.6. Weak Integrity . . . . . . . . . . . . . . . . . . . . . . 34 124 8.7. Reliance on DNS . . . . . . . . . . . . . . . . . . . . . 35 125 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 126 9.1. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . . 36 127 9.2. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . . 36 128 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 37 129 10.1. Normative References . . . . . . . . . . . . . . . . . . . 37 130 10.2. Informative References . . . . . . . . . . . . . . . . . . 37 131 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 39 132 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 40 134 1. Introduction 136 This document defines the HTTP Cookie and Set-Cookie header fields. 137 Using the Set-Cookie header field, an HTTP server can pass name/value 138 pairs and associated metadata (called cookies) to a user agent. When 139 the user agent makes subsequent requests to the server, the user 140 agent uses the metadata and other information to determine whether to 141 return the name/value pairs in the Cookie header. 143 Although simple on its surface, cookies have a number of 144 complexities. For example, the server indicates a scope for each 145 cookie when sending them to the user agent. The scope indicates the 146 maximum amount of time the user agent should return the cookie, the 147 servers to which the user agent should return the cookie, and the URI 148 schemes for which the cookie is applicable. 150 For historical reasons, cookies contain a number of security and 151 privacy infelicities. For example, a server can indicate that a 152 given cookie is intended for "secure" connections, but the Secure 153 attribute does not provide integrity in the presence of an active 154 network attackers. Similarly, cookies for a given host are shared 155 across all the ports on that host, even though the usual "same-origin 156 policy" used by web browsers isolates content retrieved via different 157 ports. 159 Prior to this document, there were at least three descriptions of 160 cookies: the so-called "Netscape cookie specification" [Netscape], 161 RFC 2109 [RFC2109], and RFC 2965 [RFC2965]. However, none of these 162 documents describe how the Cookie and Set-Cookie headers are actually 163 used on the Internet (see [Kri2001] for historical context). This 164 document attempts to specify the syntax and semantics of these 165 headers as they are actually used on the Internet. 167 2. Conventions 169 2.1. Conformance Criteria 171 The keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", 172 "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 173 interpreted as described in [RFC2119]. 175 Requirements phrased in the imperative as part of algorithms (such as 176 "strip any leading space characters" or "return false and abort these 177 steps") are to be interpreted with the meaning of the key word 178 ("MUST", "SHOULD", "MAY", etc) used in introducing the algorithm. 180 Conformance requirements phrased as algorithms or specific steps can 181 be implemented in any manner, so long as the end result is 182 equivalent. In particular, the algorithms defined in this 183 specification are intended to be easy to understand and are not 184 intended to be performant. 186 2.2. Syntax Notation 188 This specification uses the Augmented Backus-Naur Form (ABNF) 189 notation of [RFC5234]. 191 The following core rules are included by reference, as defined in 192 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 193 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 194 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 195 sequence of data), SP (space), HTAB (horizontal tab), CHAR (any US- 196 ASCII character), VCHAR (any visible US-ASCII character), and WSP 197 (whitespace). 199 The OWS (optional whitespace) rule is used where zero or more linear 200 whitespace characters MAY appear: 202 OWS = *( [ obs-fold ] WSP ) 203 ; "optional" whitespace 204 obs-fold = CRLF 206 OWS SHOULD either not be produced or be produced as a single SP 207 character. 209 2.3. Terminology 211 The terms user agent, client, server, proxy, and origin server have 212 the same meaning as in the HTTP/1.1 specification ([RFC2616], Section 213 1.3). 215 The request-host is the name of the host, as known by the user agent, 216 to which the user agent is sending an HTTP request or is receiving an 217 HTTP response from (i.e., the name of the host to which it sent the 218 corresponding HTTP request). 220 The term request-uri is defined in Section 5.1.2 of [RFC2616]. 222 Two sequences of octets are said to case-insensitively match each 223 other if and only if they are equivalent under the i;ascii-casemap 224 collation defined in [RFC4790]. 226 The term string means a sequence of octets. 228 3. Overview 230 This section outlines a way for an origin server to send state 231 information to a user agent and for the user agent to return the 232 state information to the origin server. 234 To store state, the origin server includes a Set-Cookie header in an 235 HTTP response. In subsequent requests, the user agent returns a 236 Cookie request header to the origin server. The Cookie header 237 contains cookies the user agent received in previous Set-Cookie 238 headers. The origin server is free to ignore the Cookie header or 239 use its contents for an application-defined purpose. 241 Origin servers can send a Set-Cookie response header with any 242 response. An origin server can include multiple Set-Cookie header 243 fields in a single response. 245 Note that folding multiple Set-Cookie header fields into a single 246 header field might change the semantics of the header because the 247 %x2C (",") character is used by the Set-Cookie header in a way that 248 conflicts with such folding. This historical infelicity is 249 incompatible with the usual mechanism for folding HTTP headers as 250 defined in [RFC2616]. 252 3.1. Examples 254 Using the Set-Cookie header, a server can send the user agent a short 255 string in an HTTP response that the user agent will return in future 256 HTTP requests. For example, the server can send the user agent a 257 "session identifier" named SID with the value 31d4d96e407aad42. The 258 user agent then returns the session identifier in subsequent 259 requests. 261 == Server -> User Agent == 263 Set-Cookie: SID=31d4d96e407aad42 265 == User Agent -> Server == 267 Cookie: SID=31d4d96e407aad42 269 The server can alter the default scope of the cookie using the Path 270 and Domain attributes. For example, the server can instruct the user 271 agent to return the cookie to every path and every subdomain of 272 example.com. 274 == Server -> User Agent == 276 Set-Cookie: SID=31d4d96e407aad42; Path=/; Domain=example.com 278 == User Agent -> Server == 280 Cookie: SID=31d4d96e407aad42 282 As shown in the next example, the server can store multiple cookies 283 at the user agent. For example, the server can store a session 284 identifier as well as the user's preferred language by returning two 285 Set-Cookie header fields. Notice that the server uses the Secure and 286 HttpOnly attributes to provide additional security protections for 287 the more-sensitive session identifier (see Section 4.1.2.) 289 == Server -> User Agent == 291 Set-Cookie: SID=31d4d96e407aad42; Path=/; Secure; HttpOnly 292 Set-Cookie: lang=en-US; Path=/; Domain=example.com 294 == User Agent -> Server == 296 Cookie: SID=31d4d96e407aad42; lang=en-US 298 Notice that the Cookie header above contains two cookies, one named 299 SID and one named lang. If the server wishes the user agent to 300 persist the cookie over multiple "sessions" (e.g., user agent 301 restarts), the server can specify an expiration date in the Expires 302 attribute. Note that the user agent might delete the cookie before 303 the expiration date if the user agent's cookie store exceeds its 304 quota or if the user manually deletes the server's cookie. 306 == Server -> User Agent == 308 Set-Cookie: lang=en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT 310 == User Agent -> Server == 312 Cookie: SID=31d4d96e407aad42; lang=en-US 314 Finally, to remove a cookie, the server returns a Set-Cookie header 315 with an expiration date in the past. The server will be successful 316 in removing the cookie only if the Path and the Domain attribute in 317 the Set-Cookie header match the values used when the cookie was 318 created. 320 == Server -> User Agent == 322 Set-Cookie: lang=; Expires=Sun, 06 Nov 1994 08:49:37 GMT 324 == User Agent -> Server == 326 Cookie: SID=31d4d96e407aad42 328 4. Server Requirements 330 This section describes the syntax and semantics of a well-behaved 331 profile of the Cookie and Set-Cookie headers. Servers SHOULD limit 332 themselves to the profile described in this section, both to maximize 333 interoperability with existing user agents and because a future 334 version of the Cookie or Set-Cookie headers could remove support for 335 some of the esoteric semantics described in Section 5. User agents, 336 however, MUST implement the requirements in Section 5 to ensure 337 interoperability with servers making use of the full semantics. 339 4.1. Set-Cookie 341 The Set-Cookie HTTP response header is used to send cookies from the 342 server to the user agent. 344 4.1.1. Syntax 346 Informally, the Set-Cookie response header contains the header name 347 "Set-Cookie" followed by a ":" and a cookie. Each cookie begins with 348 a name-value pair, followed by zero or more attribute-value pairs. 349 Servers SHOULD NOT send Set-Cookie headers that fail to conform to 350 the following grammar: 352 set-cookie-header = "Set-Cookie:" SP set-cookie-string 353 set-cookie-string = cookie-pair *( ";" SP cookie-av ) 354 cookie-pair = cookie-name "=" cookie-value 355 cookie-name = token 356 cookie-value = token 357 token = 359 cookie-av = expires-av / max-age-av / domain-av / 360 path-av / secure-av / httponly-av / 361 extension-av 362 expires-av = "Expires=" sane-cookie-date 363 sane-cookie-date = 364 max-age-av = "Max-Age=" 1*DIGIT 365 domain-av = "Domain=" domain-value 366 domain-value = 367 ; defined in [RFC1034], Section 3.5, as 368 ; enhanced by [RFC1123], Section 2.1 369 path-av = "Path=" path-value 370 path-value = 371 secure-av = "Secure" 372 httponly-av = "HttpOnly" 373 extension-av = 374 Note that some of the grammatical terms above reference documents 375 that use different grammatical notations than this document (which 376 uses ABNF from [RFC5234]). 378 The semantics of the cookie-value are not defined by this document. 380 To maximize compatibility with user agents, servers that wish to 381 store non-ASCII data in a cookie-value SHOULD encode that data using 382 a printable ASCII encoding. 384 The portions of the set-cookie-string produced by the cookie-av term 385 are known as attributes. To maximize compatibility with user agents, 386 servers SHOULD NOT produce two attributes with the same name in the 387 same set-cookie-string. 389 Servers SHOULD NOT include more than one Set-Cookie header field in 390 the same response with the same cookie-name. 392 If a server sends multiple responses containing Set-Cookie headers 393 concurrently to the user agent (e.g., when communicating with the 394 user agent over multiple sockets), these responses create a "race 395 condition" that can lead to unpredictable behavior. 397 NOTE: Some legacy user agents differ on their interpretation of two- 398 digit years. To avoid compatibility issues, servers SHOULD use the 399 rfc1123-date format, which requires a four-digit year. 401 NOTE: Some user agents represent dates using 32-bit UNIX time_t 402 values. Some of these user agents might contain bugs that cause them 403 to process dates after the year 2038 incorrectly. 405 4.1.2. Semantics (Non-Normative) 407 This section describes a simplified semantics of the Set-Cookie 408 header. These semantics are detailed enough to be useful for 409 understanding the most common uses of cookies by servers. The full 410 semantics are described in Section 5. 412 When the user agent receives a Set-Cookie header, the user agent 413 stores the cookie together with its attributes. Subsequently, when 414 the user agent makes an HTTP request, the user agent includes the 415 applicable, non-expired cookies in the Cookie header. 417 If the user agent receives a new cookie with the same cookie-name, 418 domain-value, and path-value as a cookie that it has already stored, 419 the existing cookie is evicted and replaced with the new cookie. 420 Notice that servers can delete cookies by sending the user agent a 421 new cookie with an Expires attribute with a value in the past. 423 Unless the cookie's attributes indicate otherwise, the cookie is 424 returned only to the origin server, and it expires at the end of the 425 current session (as defined by the user agent). User agents ignore 426 unrecognized cookie attributes. 428 4.1.2.1. The Expires Attribute 430 The Expires attribute indicates the maximum lifetime of the cookie, 431 represented as the date and time at which the cookie expires. The 432 user agent is not required to retain the cookie until the specified 433 date has passed. In fact, user agents often evict cookies due to 434 memory pressure or privacy concerns. 436 4.1.2.2. The Max-Age Attribute 438 The Max-Age attribute indicates the maximum lifetime of the cookie, 439 represented as the number of seconds until the cookie expires. The 440 user agent is not required to retain the cookie for the specified 441 duration. In fact, user agents often evict cookies from due to 442 memory pressure or privacy concerns. 444 NOTE: Some legacy user agents do not support the Max-Age 445 attribute. User agents that do not support the Max-Age attribute 446 ignore the attribute. 448 If a cookie has both the Max-Age and the Expires attribute, the Max- 449 Age attribute has precedence and controls the expiration date of the 450 cookie. If a cookie has neither the Max-Age nor the Expires 451 attribute, the user agent will retain the cookie until "the current 452 session is over" (as defined by the user agent). 454 4.1.2.3. The Domain Attribute 456 The Domain attribute specifies those hosts to which the cookie will 457 be sent. For example, if the value of the Domain attribute is 458 "example.com", the user agent will include the cookie in the Cookie 459 header when making HTTP requests to example.com, www.example.com, and 460 www.corp.example.com. (Note that a leading %x2E ("."), if present, 461 is ignored even though that character is not permitted.) If the 462 server omits the Domain attribute, the user agent will return the 463 cookie only to the origin server. 465 WARNING: Some legacy user agents treat an absent Domain attribute 466 as if the Domain attribute were present and contained the current 467 host name. For example, if example.com returns a Set-Cookie 468 header without a Domain attribute, these user agents will 469 erroneously send the cookie to www.example.com as well. 471 The user agent will reject cookies unless the Domain attribute 472 specifies a scope for the cookie that would include the origin 473 server. For example, the user agent will accept a cookie with a 474 Domain attribute of "example.com" or of "foo.example.com" from 475 foo.example.com, but the user agent will not accept a cookie with a 476 Domain attribute of "bar.example.com" or of "baz.foo.example.com". 478 NOTE: For security reasons, many user agents are configured to reject 479 Domain attributes that correspond to "public suffixes." For example, 480 some user agents will reject Domain attributes of "com" or "co.uk". 482 4.1.2.4. The Path Attribute 484 The scope of each cookie is limited to a set of paths, controlled by 485 the Path attribute. If the server omits the Path attribute, the user 486 agent will use the "directory" of the request-uri's path component as 487 the default value. (See Section 5.1.4 for more details.) 489 The user agent will include the cookie in an HTTP request only if the 490 path portion of the request-uri matches (or is a subdirectory of) the 491 cookie's Path attribute, where the %x2F ("/") character is 492 interpreted as a directory separator. 494 Although seemingly useful for isolating cookies between different 495 paths within a given host, the Path attribute cannot be relied upon 496 for security (see Section 8). 498 4.1.2.5. The Secure Attribute 500 The Secure attribute limits the scope of the cookie to "secure" 501 channels (where "secure" is defined by the user agent). When a 502 cookie has the Secure attribute, the user agent will include the 503 cookie in an HTTP request only if the request is transmitted over a 504 secure channel (typically HTTP over SSL, HTTP over TLS [RFC2818], and 505 TLS [RFC5246] itself). 507 Although seemingly useful for protecting cookies from active network 508 attackers, the Secure attribute protects only the cookie's 509 confidentiality. An active network attacker can overwrite Secure 510 cookies from an insecure channel, disrupting their integrity (see 511 Section 8.6 for more details). 513 4.1.2.6. The HttpOnly Attribute 515 The HttpOnly attribute limits the scope of the cookie to HTTP 516 requests. In particular, the attribute instructs the user agent to 517 omit the cookie when providing access to cookies via "non-HTTP" APIs 518 (such as a web browser API that exposes cookies to scripts). 520 4.2. Cookie 522 4.2.1. Syntax 524 The user agent sends stored cookies to the origin server in the 525 Cookie header. If the server conforms to the requirements in 526 Section 4.1 (and the user agent conforms to the requirements in the 527 Section 5), the user agent will send a Cookie header that conforms to 528 the following grammar: 530 cookie-header = "Cookie:" OWS cookie-string OWS 531 cookie-string = cookie-pair *( ";" SP cookie-pair ) 533 4.2.2. Semantics 535 Each cookie-pair represents a cookie stored by the user agent. The 536 cookie-pair contains the cookie-name and cookie-value the user agent 537 received in the Set-Cookie header. 539 Notice that the cookie attributes are not returned. In particular, 540 the server cannot determine from the Cookie header alone when a 541 cookie will expire, for which hosts the cookie is valid, for which 542 paths the cookie is valid, or whether the cookie was set with the 543 Secure or HttpOnly attributes. 545 The semantics of individual cookies in the Cookie header are not 546 defined by this document. Servers are expected to imbue these 547 cookies with application-specific semantics. 549 Although cookies are serialized linearly in the Cookie header, 550 servers SHOULD NOT rely upon the serialization order. In particular, 551 if the Cookie header contains two cookies with the same name (e.g., 552 that were set with different Path or Domain attributes), servers 553 SHOULD NOT rely upon the order in which these cookies appear in the 554 header. 556 5. User Agent Requirements 558 For historical reasons, the full semantics of cookies (as presently 559 deployed on the Internet) contain a number of exotic quirks. This 560 section is intended to specify the Cookie and Set-Cookie headers in 561 sufficient detail to allow a user agent implementing these 562 requirements precisely to interoperate with existing servers. 564 5.1. Subcomponent Algorithms 566 This section defines some algorithms used by user agents to process 567 specific subcomponents of the Cookie and Set-Cookie headers. 569 5.1.1. Dates 571 The user agent MUST use an algorithm equivalent to the following 572 algorithm to parse a cookie-date. Note that the various boolean 573 flags defined as a part of the algorithm are initially "not set". 575 1. Using the grammar below, divide the cookie-date into date-tokens. 577 cookie-date = *delimiter date-token-list *delimiter 578 date-token-list = date-token *( 1*delimiter date-token ) 579 date-token = 1*non-delimiter 581 delimiter = %x09 / %x20-2F / %x3B-40 / %x5B-60 / %x7B-7E 582 non-delimiter = %x00-08 / %x0A-1F / DIGIT / ":" / ALPHA / %x7F-FF 583 non-digit = %x00-2F / %x3A-FF 585 day-of-month = 1*2DIGIT ( non-digit *OCTET ) 586 month = ( "jan" / "feb" / "mar" / "apr" / 587 "may" / "jun" / "jul" / "aug" / 588 "sep" / "oct" / "nov" / "dec" ) *OCTET 589 year = 1*4DIGIT ( non-digit *OCTET ) 590 time = hms-time ( non-digit *OCTET ) 591 hms-time = time-field ":" time-field ":" time-field 592 time-field = 1*2DIGIT 594 2. Process each date-token sequentially in the order the date-tokens 595 appear in the cookie-date: 597 1. If the found-day-of-month flag is not set and the date-token 598 matches the day-of-month production, set the found-day-of- 599 month flag and set the day-of-month-value to the number 600 denoted by the date-token. Skip the remaining sub-steps and 601 continue to the next date-token. 603 2. If the found-month flag is not set and the date-token matches 604 the month production, set the found-month flag and set the 605 month-value to the month denoted by the date-token. Skip the 606 remaining sub-steps and continue to the next date-token. 608 3. If the found-year flag is not set and the date-token matches 609 the year production, set the found-year flag and set the 610 year-value to the number denoted by the date-token. Skip the 611 remaining sub-steps and continue to the next date-token. 613 4. If the found-time flag is not set and the token matches the 614 time production, set the found-time flag and set the hour- 615 value, minute-value, and second-value to the numbers denoted 616 by the digits in the date-token, respectively. Skip the 617 remaining sub-steps and continue to the next date-token. 619 3. If the year-value is greater than or equal to 70 and less than or 620 equal to 99, increment the year-value by 1900. 622 4. If the year-value is greater than or equal to 0 and less than or 623 equal to 69, increment the year-value by 2000. 625 1. NOTE: Some legacy user agents interpret two-digit years 626 differently. 628 5. Abort these steps and fail to parse the cookie-date if 630 * at least one of the found-day-of-month, found-month, found- 631 year, or found-time flags is not set, 633 * the day-of-month-value is less than 1 or greater than 31, 635 * the year-value is less than 1601, 637 * the hour-value is greater than 23, 639 * the minute-value is greater than 59, or 641 * the second-value is greater than 59. 643 6. Let the parsed-cookie-date be the date whose day-of-month, month, 644 year, hour, minute, and second (in GMT) are the day-of-month- 645 value, the month-value, the year-value, the hour-value, the 646 minute-value, and the second-value, respectively. If no such 647 date exists, abort these steps and fail to parse the cookie-date. 649 7. Return the parsed-cookie-date as the result of this algorithm. 651 5.1.2. Canonicalized host names 653 A canonicalized host name is the string generated by the following 654 algorithm: 656 1. Convert the host name to a sequence of NR-LDH labels (see Section 657 2.3.2.2 of [RFC5890]) and/or A-labels according to the 658 appropriate IDNA specification [RFC5891] or [RFC3490] (see 659 Section 6.3 of this specification) 661 2. Convert the labels to lower case. 663 3. Concatenate the labels, separating each label from the next with 664 a %x2E (".") character. 666 5.1.3. Domain matching 668 A string domain-matches a given domain string if at least one of the 669 following conditions hold: 671 o The domain string and the string are identical. 673 o All of the following conditions hold: 675 * The domain string is a suffix of the string. 677 * The last character of the string that is not included in the 678 domain string is a %x2E (".") character. 680 * The string is a host name (i.e., not an IP address). 682 5.1.4. Paths and path-match 684 The user agent MUST use an algorithm equivalent to the following 685 algorithm to compute the default-path of a cookie: 687 1. Let uri-path be the path portion of the request-uri if such a 688 portion exists (and empty otherwise). For example, if the 689 request-uri contains just a path (and optional query string), 690 then the uri-path is that path (without the %x3F ("?") character 691 or query string), and if the request-uri contains a full 692 absoluteURI, the uri-path is the path component of that URI. 694 2. If the uri-path is empty or if first character of the uri-path is 695 not a %x2F ("/") character, output %x2F ("/") and skip the 696 remaining steps. 698 3. If the uri-path contains only a single %x2F ("/") character, 699 output %x2F ("/") and skip the remaining steps. 701 4. Output the characters of the uri-path from the first character up 702 to, but not including, the right-most %x2F ("/"). 704 A request-path path-matches a given cookie-path if at least one of 705 the following conditions hold: 707 o The cookie-path and the request-path are identical. 709 o The cookie-path is a prefix of the request-path and the last 710 character of the cookie-path is %x2F ("/"). 712 o The cookie-path is a prefix of the request-path and the first 713 character of the request-path that is not included in the cookie- 714 path is a %x2F ("/") character. 716 5.2. The Set-Cookie Header 718 When a user agent receives a Set-Cookie header field in an HTTP 719 response, the user agent MUST parse the field-value of the Set-Cookie 720 header field as a set-cookie-string (defined below). 722 NOTE: The algorithm below is more permissive than the grammar in 723 Section 4.1. For example, the algorithm strips leading and trailing 724 whitespace from the cookie name and value (but maintains internal 725 whitespace), whereas the grammar in Section 4.1 forbids whitespace in 726 these positions. User agents use this algorithm so as to 727 interoperate with servers that do not follow the recommendations in 728 Section 4. 730 A user agent MUST use an algorithm equivalent to the following 731 algorithm to parse a "set-cookie-string": 733 1. If the set-cookie-string contains a %x3B (";") character: 735 The name-value-pair string consists of the characters up to, 736 but not including, the first %x3B (";"), and the unparsed- 737 attributes consist of the remainder of the set-cookie-string 738 (including the %x3B (";") in question). 740 Otherwise: 742 The name-value-pair string consists of all the characters 743 contained in the set-cookie-string, and the unparsed- 744 attributes is the empty string. 746 2. If the name-value-pair string lacks a %x3D ("=") character, 747 ignore the set-cookie-string entirely. 749 3. The (possibly empty) name string consists of the characters up 750 to, but not including, the first %x3D ("=") character, and the 751 (possibly empty) value string consists of the characters after 752 the first %x3D ("=") character. 754 4. Remove any leading or trailing WSP characters from the name 755 string and the value string. 757 5. If the name string is empty, ignore the set-cookie-string 758 entirely. 760 6. The cookie-name is the name string, and the cookie-value is the 761 value string. 763 The user agent MUST use an algorithm equivalent to the following 764 algorithm to parse the unparsed-attributes: 766 1. If the unparsed-attributes string is empty, skip the rest of 767 these steps. 769 2. Discard the first character of the unparsed-attributes (which 770 will be a %x3B (";") character). 772 3. If the remaining unparsed-attributes contains a %x3B (";") 773 character: 775 Consume the characters of the unparsed-attributes up to, but 776 not including, the first %x3B (";") character. 778 Otherwise: 780 Consume the remainder of the unparsed-attributes. 782 Let the cookie-av string be the characters consumed in this step. 784 4. If the cookie-av string contains a %x3D ("=") character: 786 The (possibly empty) attribute-name string consists of the 787 characters up to, but not including, the first %x3D ("=") 788 character, and the (possibly empty) attribute-value string 789 consists of the characters after the first %x3D ("=") 790 character. 792 Otherwise: 794 The attribute-name string consists of the entire cookie-av 795 string, and the attribute-value string is empty. 797 5. Remove any leading or trailing WSP characters from the attribute- 798 name string and the attribute-value string. 800 6. Process the attribute-name and attribute-value according to the 801 requirements in the following subsections. (Notice that 802 attributes with unrecognized attribute-names are ignored.) 804 7. Return to Step 1 of this algorithm. 806 When the user agent finishes parsing the set-cookie-string, the user 807 agent is said to "receive a cookie" from the request-uri with name 808 cookie-name, value cookie-value, and attributes cookie-attribute- 809 list. (See Section 5.3 for additional requirements triggered by 810 receiving a cookie.) 812 5.2.1. The Expires Attribute 814 If the attribute-name case-insensitively matches the string 815 "Expires", the user agent MUST process the cookie-av as follows. 817 Let the expiry-time be the result of parsing the attribute-value as 818 cookie-date (see Section 5.1.1). 820 If the attribute-value failed to parse as a cookie date, ignore the 821 cookie-av. 823 If the expiry-time is later than the last date the user agent can 824 represent, the user agent MAY replace the expiry-time with the last 825 representable date. 827 If the expiry-time is earlier than the earliest date the user agent 828 can represent, the user agent MAY replace the expiry-time with the 829 earliest representable date. 831 Append an attribute to the cookie-attribute-list with an attribute- 832 name of Expires and an attribute-value of expiry-time. 834 5.2.2. The Max-Age Attribute 836 If the attribute-name case-insensitively matches the string "Max- 837 Age", the user agent MUST process the cookie-av as follows. 839 If the first character of the attribute-value is not a DIGIT or a "-" 840 character, ignore the cookie-av. 842 If the remainder of attribute-value contains a non-DIGIT character, 843 ignore the cookie-av. 845 Let delta-seconds be the attribute-value converted to an integer. 847 If delta-seconds is less than or equal to zero (0), let expiry-time 848 be the earliest representable date and time. Otherwise, let the 849 expiry-time be the current date and time plus delta-seconds seconds. 851 Append an attribute to the cookie-attribute-list with an attribute- 852 name of Max-Age and an attribute-value of expiry-time. 854 5.2.3. The Domain Attribute 856 If the attribute-name case-insensitively matches the string "Domain", 857 the user agent MUST process the cookie-av as follows. 859 If the attribute-value is empty, the behavior is undefined. However, 860 user agent SHOULD ignore the cookie-av entirely. 862 If the first character of the attribute-value string is %x2E ("."): 864 Let cookie-domain be the attribute-value without the leading %x2E 865 (".") character. 867 Otherwise: 869 Let cookie-domain be the entire attribute-value. 871 Convert the cookie-domain to lower case. 873 Append an attribute to the cookie-attribute-list with an attribute- 874 name of Domain and an attribute-value of cookie-domain. 876 5.2.4. The Path Attribute 878 If the attribute-name case-insensitively matches the string "Path", 879 the user agent MUST process the cookie-av as follows. 881 If the attribute-value is empty or if the first character of the 882 attribute-value is not %x2F ("/"): 884 Let cookie-path be the default-path. 886 Otherwise: 888 Let cookie-path be the attribute-value. 890 Append an attribute to the cookie-attribute-list with an attribute- 891 name of Path and an attribute-value of cookie-path. 893 5.2.5. The Secure Attribute 895 If the attribute-name case-insensitively matches the string "Secure", 896 the user agent MUST append an attribute to the cookie-attribute-list 897 with an attribute-name of Secure and an empty attribute-value. 899 5.2.6. The HttpOnly Attribute 901 If the attribute-name case-insensitively matches the string 902 "HttpOnly", the user agent MUST append an attribute to the cookie- 903 attribute-list with an attribute-name of HttpOnly and an empty 904 attribute-value. 906 5.3. Storage Model 908 The user agent stores the following fields about each cookie: name, 909 value, expiry-time, domain, path, creation-time, last-access-time, 910 persistent-flag, host-only-flag, secure-only-flag, and http-only- 911 flag. 913 When the user agent "receives a cookie" from a request-uri with name 914 cookie-name, value cookie-value, and attributes cookie-attribute- 915 list, the user agent MUST process the cookie as follows: 917 1. A user agent MAY ignore a received cookie in its entirety. For 918 example, the user agent might wish to block receiving cookies 919 from "third-party" responses or the user agent might not wish to 920 store cookies that exceed some size. 922 2. Create a new cookie with name cookie-name, value cookie-value. 923 Set the creation-time and the last-access-time to the current 924 date and time. 926 3. If the cookie-attribute-list contains an attribute with an 927 attribute-name of "Max-Age": 929 Set the cookie's persistent-flag to true. 931 Set the cookie's expiry-time to attribute-value of the last 932 attribute in the cookie-attribute-list with an attribute-name 933 of "Max-Age". 935 Otherwise, if the cookie-attribute-list contains an attribute 936 with an attribute-name of "Expires" (and does not contain an 937 attribute with an attribute-name of "Max-Age"): 939 Set the cookie's persistent-flag to true. 941 Set the cookie's expiry-time to attribute-value of the last 942 attribute in the cookie-attribute-list with an attribute-name 943 of "Expires". 945 Otherwise: 947 Set the cookie's persistent-flag to false. 949 Set the cookie's expiry-time to the latest representable 950 date. 952 4. If the cookie-attribute-list contains an attribute with an 953 attribute-name of "Domain": 955 Let the domain-attribute be the attribute-value of the last 956 attribute in the cookie-attribute-list with an attribute-name 957 of "Domain". 959 Otherwise: 961 Let the domain-attribute be the empty string. 963 5. If the user agent is configured to reject "public suffixes" and 964 the domain-attribute is a public suffix: 966 If the domain-attribute is identical to the canonicalized 967 request-host: 969 Let the domain-attribute be the empty string. 971 Otherwise: 973 Ignore the cookie entirely and abort these steps 975 NOTE: A "public suffix" is a domain that is controlled by a 976 public registry, such as "com", "co.uk", and "pvt.k12.wy.us". 977 This step is essential for preventing attacker.com from 978 disrupting the integrity of example.com by setting a cookie 979 with a Domain attribute of "com". Unfortunately, the set of 980 public suffixes (also known as "registry controlled domains") 981 changes over time. If feasible, user agents SHOULD use an 982 up-to-date public suffix list, such as the one maintained by 983 the Mozilla project at . 985 6. If the domain-attribute is non-empty: 987 If the canonicalized request-host does not domain-match the 988 domain-attribute, ignore the cookie entirely and abort these 989 steps. 991 Set the cookie's host-only-flag to false. 993 Set the cookie's domain to the domain-attribute. 995 Otherwise: 997 Set the cookie's host-only-flag to true. 999 Set the cookie's domain to the canonicalized request-host. 1001 7. If the cookie-attribute-list contains an attribute with an 1002 attribute-name of "Path", set the cookie's path to attribute- 1003 value of the last attribute in the cookie-attribute-list with an 1004 attribute-name of "Path". Otherwise, set cookie's path to the 1005 default-path of the request-uri. 1007 8. If the cookie-attribute-list contains an attribute with an 1008 attribute-name of "Secure", set the cookie's secure-only-flag to 1009 true. Otherwise, set cookie's secure-only-flag to false. 1011 9. If the cookie-attribute-list contains an attribute with an 1012 attribute-name of "HttpOnly", set the cookie's http-only-flag to 1013 true. Otherwise, set cookie's http-only-flag to false. 1015 10. If the cookie was received from a "non-HTTP" API and the 1016 cookie's http-only-flag is set, abort these steps and ignore the 1017 cookie entirely. 1019 11. If the cookie store contains a cookie with the same name, 1020 domain, and path as the newly created cookie: 1022 1. Let old-cookie be the existing cookie with the same name, 1023 domain, and path as the newly created cookie. (Notice that 1024 this algorithm maintains the invariant that there is at most 1025 one such cookie.) 1027 2. If the newly created cookie was received from an "non-HTTP" 1028 API and the old-cookie's http-only-flag is set, abort these 1029 steps and ignore the newly created cookie entirely. 1031 3. Update the creation-time of the newly created cookie to 1032 match the creation-time of the old-cookie. 1034 4. Remove the old-cookie from the cookie store. 1036 12. Insert the newly created cookie into the cookie store. 1038 A cookie is "expired" if the cookie has an expiry date in the past. 1040 The user agent MUST evict all expired cookies from the cookie store 1041 if, at any time, an expired cookie exists in the cookie store. 1043 At any time, the user agent MAY "remove excess cookies" from the 1044 cookie store if the number of cookies sharing a domain field exceeds 1045 some implementaiton defined upper bound (such as 50 cookies). 1047 At any time, the user agent MAY "remove excess cookies" from the 1048 cookie store if the cookie store exceeds some predetermined upper 1049 bound (such as 3000 cookies). 1051 When the user agent removes excess cookies from the cookie store, the 1052 user agent MUST evict cookies in the following priority order: 1054 1. Expired cookies. 1056 2. Cookies that share a domain field with more than a predetermined 1057 number of other cookies. 1059 3. All cookies. 1061 If two cookies have the same removal priority, the user agent MUST 1062 evict the cookie with the earliest last-access date first. 1064 When "the current session is over" (as defined by the user agent), 1065 the user agent MUST remove from the cookie store all cookies with the 1066 persistent-flag set to false. 1068 5.4. The Cookie Header 1070 The user agent includes stored cookies in the Cookie HTTP request 1071 header. 1073 When the user agent generates an HTTP request, the user agent MUST 1074 NOT attach more than one Cookie header field. 1076 A user agent MAY omit the Cookie header in its entirety. For 1077 example, the user agent might wish to block sending cookies during 1078 "third-party" requests. 1080 If the user agent does attach a Cookie header field to an HTTP 1081 request, the user agent MUST send the cookie-string (defined below) 1082 as the value of the header field. 1084 The user agent MUST use an algorithm equivalent to the following 1085 algorithm to compute the "cookie-string" from a cookie store and a 1086 request-uri: 1088 1. Let cookie-list be the set of cookies from the cookie store that 1089 meet all of the following requirements: 1091 * Either: 1093 The cookie's host-only-flag is true and the canonicalized 1094 request-host is identical to the cookie's domain. 1096 Or: 1098 The cookie's host-only-flag is false and the canonicalized 1099 request-host domain-matches cookie's domain. 1101 * The request-uri's path path-matches cookie's path. 1103 * If the cookie's secure-only-flag is true, then the request- 1104 uri's scheme must denote a "secure" protocol (as defined by 1105 the user agent). 1107 NOTE: The notion of a "secure" protocol is not defined by 1108 this document. Typically, user agents consider a protocol 1109 secure if the protocol makes use of transport-layer 1110 security, such as SSL or TLS. For example, most user 1111 agents consider "https" to be a scheme that denotes a 1112 secure protocol. 1114 * If the cookie's http-only-flag is true, then exclude the 1115 cookie if the cookie-string is being generated for a "non- 1116 HTTP" API (as defined by the user agent). 1118 2. The user agent SHOULD sort the cookie-list in the following 1119 order: 1121 * Cookies with longer paths are listed before cookies with 1122 shorter paths. 1124 * Among cookies that have equal length path fields, cookies with 1125 earlier creation-times are listed before cookies with later 1126 creation-times. 1128 NOTE: Not all user agents sort the cookie-list in this order, but 1129 this order reflects common practice when this document was 1130 written, and, historically, there have been servers that 1131 (erroneously) depended on this order. 1133 3. Update the last-access-time of each cookie in the cookie-list to 1134 the current date and time. 1136 4. Serialize the cookie-list into a cookie-string by processing each 1137 cookie in the cookie-list in order: 1139 1. Output the cookie's name, the %x3D ("=") character, and the 1140 cookie's value. 1142 2. If there is an unprocessed cookie in the cookie-list, output 1143 the characters %x3B and %x20 ("; "). 1145 NOTE: Despite its name, the cookie-string is actually a sequence of 1146 octets, not a sequence of characters. To convert the cookie-string 1147 (or components thereof) into a sequence of characters (e.g., for 1148 presentation to the user), the user agent might wish use the UTF-8 1149 character encoding [RFC3629] to decode the octet sequence. 1151 6. Implementation Considerations 1153 6.1. Limits 1155 Practical user agent implementations have limits on the number and 1156 size of cookies that they can store. General-use user agents SHOULD 1157 provide each of the following minimum capabilities: 1159 o At least 4096 bytes per cookie (as measured by the sum of the 1160 length of the cookie's name, value, and attributes). 1162 o At least 50 cookies per domain. 1164 o At least 3000 cookies total. 1166 Servers SHOULD use as few and as small cookies as possible to avoid 1167 reaching these implementation limits and to minimize network 1168 bandwidth due to the Cookie header being included in every request. 1170 Servers SHOULD gracefully degrade if the user agent fails to return 1171 one or more cookies in the Cookie header because the user agent might 1172 evict any cookie at any time on orders from the user. 1174 6.2. Application Programming Interfaces 1176 One reason the Cookie and Set-Cookie headers uses such esoteric 1177 syntax is because many platforms (both in servers and user agents) 1178 provide a string-based application programing interface (API) to 1179 cookies, requiring application-layer programmers to generate and 1180 parse the syntax used by the Cookie and Set-Cookie headers, which 1181 many programmers have done incorrectly, resulting in interoperability 1182 problems. 1184 Instead of providing string-based APIs to cookies, platforms would be 1185 well-served by providing more semantic APIs. It is beyond the scope 1186 of this document to recommend specific API designs, but there are 1187 clear benefits to accepting an abstract "Date" object instead of a 1188 serialized date string. 1190 6.3. IDNA dependency and migration 1192 IDNA2008 [RFC5890] supersedes IDNA2003 [RFC3490] but is not 1193 backwards-compatible. For this reason, there will be a transition 1194 period (possibly of a number of years). User agents SHOULD implement 1195 IDNA2008 [RFC5890] and MAY implement [Unicode Technical Standard #46 1196 ] in order to facilitate a smoother 1197 IDNA transition. If a user agent does not implement IDNA2008, the 1198 user agent MUST implement IDNA2003 [RFC3490]. 1200 7. Privacy Considerations 1202 Cookies are often criticized for letting servers track users. For 1203 example, a number of "web analytics" companies use cookies to 1204 recognize when a user returns to a web site or visits another web 1205 site. Although cookies are not the only mechanism servers can use to 1206 track users across HTTP requests, cookies facilitate tracking because 1207 they are persistent across user agent sessions and can be shared 1208 between hosts. 1210 7.1. Third-Party Cookies 1212 Particularly worrisome are so-called "third-party" cookies. In 1213 rendering an HTML document, a user agent often requests resources 1214 from other servers (such as advertising networks). These third-party 1215 servers can use cookies to track the user even if the user never 1216 visits the server directly. 1218 Some user agents restrict how third-party cookies behave. For 1219 example, some of these user agents refuse to send the Cookie header 1220 in third-party requests. Others refuse to process the Set-Cookie 1221 header in responses to third-party requests. User agents vary widely 1222 in their third-party cookie policies. This document grants user 1223 agents wide latitude to experiment with third-party cookie policies 1224 that balance the privacy and compatibility needs of their users. 1225 However, this document does not endorse any particular third-party 1226 cookie policy. 1228 Third-party cookie blocking policies are often ineffective at 1229 achieving their privacy goals if servers attempt to work around their 1230 restrictions to track users. In particular, two collaborating 1231 servers can often track users without using cookies at all. 1233 7.2. User Controls 1235 User agents should provide users with a mechanism for managing the 1236 cookies stored in the cookie store. For example, a user agent might 1237 let users delete all cookies received during a specified time period 1238 or all the cookies related to a particular domain. In addition, many 1239 user agent include a user interface element that lets users examine 1240 the cookies stored in their cookie store. 1242 User agents should provide users with a mechanism for disabling 1243 cookies. When cookies are disabled, the user agent MUST NOT include 1244 a Cookie header in outbound HTTP requests and the user agent MUST NOT 1245 process Set-Cookie headers in inbound HTTP responses. 1247 Some user agents provide users the option of preventing persistent 1248 storage of cookies across sessions. When configured thusly, user 1249 agents MUST treat all received cookies as if the persistent-flag were 1250 set to false. 1252 Some user agents provide users with the ability to approve individual 1253 writes to the cookie store. In many common usage scenarios, these 1254 controls generate a large number of prompts. However, some privacy- 1255 conscious users find these controls useful nonetheless. 1257 8. Security Considerations 1259 8.1. Overview 1261 Cookies have a number of security pitfalls. This section overviews a 1262 few of the more salient issues. 1264 In particular, cookies encourage developers to rely on ambient 1265 authority for authentication, often becoming vulnerable to attacks 1266 such as cross-site request forgery. Also, when storing session 1267 identifiers in cookies, developers often create session fixation 1268 vulnerabilities. 1270 Transport-layer encryption, such as that employed in HTTPS, is 1271 insufficient to prevent a network attacker from obtaining or altering 1272 a victim's cookies because the cookie protocol itself has various 1273 vulnerabilities (see "Weak Confidentiality" and "Weak Integrity", 1274 below). In addition, by default, cookies do not provide 1275 confidentiality or integrity from network attackers, even when used 1276 in conjunction with HTTPS. 1278 8.2. Ambient Authority 1280 A server that uses cookies to authenticate users can suffer security 1281 vulnerabilities because some user agents let remote parties issue 1282 HTTP requests from the user agent (e.g., via HTTP redirects or HTML 1283 forms). When issuing those requests, user agents attach cookies even 1284 if the remote party does not know the contents of the cookies, 1285 potentially letting the remote party exercise authority at an unwary 1286 server. 1288 Although this security concern goes by a number of names (e.g., 1289 cross-site request forgery, confused deputy), the issue stems from 1290 cookies being a form of ambient authority. Cookies encourage server 1291 operators to separate designation (in the form of URLs) from 1292 authorization (in the form of cookies). Consequently, the user agent 1293 might supply the authorization for a resource designated by the 1294 attacker, possibly causing the server or its clients to undertake 1295 actions designated by the attacker as though they were authorized by 1296 the user. 1298 Instead of using cookies for authorization, server operators might 1299 wish to consider entangling designation and authorization by treating 1300 URLs as capabilities. Instead of storing secrets in cookies, this 1301 approach stores secrets in URLs, requiring the remote entity to 1302 supply the secret itself. Although this approach is not a panacea, 1303 judicious application of these principles can lead to more robust 1304 security. 1306 8.3. Clear Text 1308 Unless sent over a secure channel (such as TLS), the information in 1309 the Cookie and Set-Cookie headers is transmitted in the clear. 1311 1. All sensitive information conveyed in these headers is exposed to 1312 an eavesdropper. 1314 2. A malicious intermediary could alter the headers as they travel 1315 in either direction, with unpredictable results. 1317 3. A malicious client could alter the Cookie header before 1318 transmission, with unpredictable results. 1320 Servers SHOULD encrypt and sign the contents of cookies when 1321 transmitting them to the user agent (even when sending the cookies 1322 over a secure channel). However, encrypting and signing cookie 1323 contents does not prevent an attacker from transplanting a cookie 1324 from one user agent to another or from replaying the cookie at a 1325 later time. 1327 In addition to encrypting and signing the contents of every cookie, 1328 servers that require a higher level of security SHOULD use the Cookie 1329 and Set-Cookie headers only over a secure channel. When using 1330 cookies over a secure channel, servers SHOULD set the Secure 1331 attribute (see Section 4.1.2.5) for every cookie. If a server does 1332 not set the Secure attribute, the protection provided by the secure 1333 channel will be largely moot. 1335 8.4. Session Identifiers 1337 Instead of storing session information directly in a cookie (where it 1338 might be exposed to or replayed by an attacker), servers commonly 1339 store a nonce (or "session identifier") in a cookie. When the server 1340 receives an HTTP request with a nonce, the server can look up state 1341 information associated with the cookie using the nonce as a key. 1343 Using session identifier cookies limits the damage an attacker can 1344 cause if the attacker learns the contents of a cookie because the 1345 nonce is useful only for interacting with the server (unlike non- 1346 nonce cookie content, which might itself be sensitive). Furthermore, 1347 using a single nonce prevents an attacker from "splicing" together 1348 cookie content from two interactions with the server, which could 1349 cause the server to behave unexpectedly. 1351 Using session identifiers is not without risk. For example, the 1352 server SHOULD take care to avoid "session fixation" vulnerabilities. 1353 A session fixation attack proceeds in three steps. First, the 1354 attacker transplants a session identifier from his or her user agent 1355 to the victim's user agent. Second, the victim uses that session 1356 identifier to interact with the server, possibly imbuing the session 1357 identifier with the user's credentials or confidential information. 1358 Third, the attacker uses the session identifier to interact with 1359 server directly, possibly obtaining the user's authority or 1360 confidential information. 1362 8.5. Weak Confidentiality 1364 Cookies do not provide isolation by port. If a cookie is readable by 1365 a service running on one port, the cookie is also readable by a 1366 service running on another port of the same server. If a cookie is 1367 writable by a service on one port, the cookie is also writable by a 1368 service running on another port of the same server. For this reason, 1369 servers SHOULD NOT both run mutually distrusting services on 1370 different ports of the same host and use cookies to store security- 1371 sensitive information. 1373 Cookies do not provide isolation by scheme. Although most commonly 1374 used with the http and https schemes, the cookies for a given host 1375 might also be available to other schemes, such as ftp and gopher. 1376 Although this lack of isolation by scheme is most apparent in non- 1377 HTTP APIs that permit access to cookies (e.g., HTML's document.cookie 1378 API), the lack of isolation by scheme is actually present in 1379 requirements for processing cookies themselves (e.g., consider 1380 retrieving a URI with the gopher scheme via HTTP). 1382 Cookies do not always provide isolation by path. Although the 1383 network-level protocol does not send cookies stored for one path to 1384 another, some user agents expose cookies via non-HTTP APIs, such as 1385 HTML's document.cookie API. Because some of these user agents (e.g., 1386 web browsers) do not isolate resources received from different paths, 1387 a resource retrieved from one path might be able to access cookies 1388 stored for another path. 1390 8.6. Weak Integrity 1392 Cookies do not provide integrity guarantees for sibling domains (and 1393 their subdomains). For example, consider foo.example.com and 1394 bar.example.com. The foo.example.com server can set a cookie with a 1395 Domain attribute of "example.com" (possibly overwriting an existing 1396 "example.com" cookie set by bar.example.com), and the user agent will 1397 include that cookie in HTTP requests to bar.example.com. In the 1398 worst case, bar.example.com will be unable to distinguish this cookie 1399 from a cookie it set itself. The foo.example.com server might be 1400 able to leverage this ability to mount an attack against 1401 bar.example.com. 1403 Even though the Set-Cookie header supports the Path attribute, the 1404 Path attribute does not provide any integrity protection because the 1405 user agent will accept an arbitrary Path attribute in a Set-Cookie 1406 header. For example, an HTTP response to a request for 1407 http://example.com/foo/bar can set a cookie with a Path attribute of 1408 "/qux". Consequently, servers SHOULD NOT both run mutually 1409 distrusting services on different paths of the same host and use 1410 cookies to store security-sensitive information. 1412 An active network attacker can also inject cookies into the Cookie 1413 header sent to https://example.com/ by impersonating a response from 1414 http://example.com/ and injecting a Set-Cookie header. The HTTPS 1415 server at example.com will be unable to distinguish these cookies 1416 from cookies that it set itself in an HTTPS response. An active 1417 network attacker might be able to leverage this ability to mount an 1418 attack against example.com even if example.com uses HTTPS 1419 exclusively. 1421 Servers can partially mitigate these attacks by encrypting and 1422 signing the contents of their cookies. However, using cryptography 1423 does not mitigate the issue completely because an attacker can replay 1424 a cookie he or she received from the authentic example.com server in 1425 the user's session, with unpredictable results. 1427 Finally, an attacker might be able to force the user agent to delete 1428 cookies by storing a large number of cookies. Once the user agent 1429 reaches its storage limit, the user agent will be forced to evict 1430 some cookies. Servers SHOULD NOT rely upon user agents retaining 1431 cookies. 1433 8.7. Reliance on DNS 1435 Cookies rely upon the Domain Name System (DNS) for security. If the 1436 DNS is partially or fully compromised, the cookie protocol might fail 1437 to provide the security properties required by applications. 1439 9. IANA Considerations 1441 The permanent message header registry (see [RFC3864]) should be 1442 updated with the following registrations: 1444 9.1. Cookie 1446 Header field name: Cookie 1448 Applicable protocol: http 1450 Status: standard 1452 Author/Change controller: IETF 1454 Specification document: this specification (Section 5.4) 1456 9.2. Set-Cookie 1458 Header field name: Set-Cookie 1460 Applicable protocol: http 1462 Status: standard 1464 Author/Change controller: IETF 1466 Specification document: this specification (Section 5.2) 1468 10. References 1470 10.1. Normative References 1472 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 1473 STD 13, RFC 1034, November 1987. 1475 [RFC1123] Braden, R., "Requirements for Internet Hosts - Application 1476 and Support", STD 3, RFC 1123, October 1989. 1478 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1479 Requirement Levels", BCP 14, RFC 2119, March 1997. 1481 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1482 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1483 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1485 [RFC3490] Faltstrom, P., Hoffman, P., and A. Costello, 1486 "Internationalizing Domain Names in Applications (IDNA)", 1487 RFC 3490, March 2003. 1489 See Section 6.3 for an explanation why the normative 1490 reference to an obsoleted specification is needed. 1492 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1493 10646", STD 63, RFC 3629, November 2003. 1495 [RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet 1496 Application Protocol Collation Registry", RFC 4790, 1497 March 2007. 1499 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1500 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1502 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1503 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1505 [RFC5890] Klensin, J., "Internationalized Domain Names for 1506 Applications (IDNA): Definitions and Document Framework", 1507 RFC 5890, August 2010. 1509 [RFC5891] Klensin, J., "Internationalized Domain Names in 1510 Applications (IDNA): Protocol", RFC 5891, August 2010. 1512 10.2. Informative References 1514 [RFC2109] Kristol, D. and L. Montulli, "HTTP State Management 1515 Mechanism", RFC 2109, February 1997. 1517 [RFC2965] Kristol, D. and L. Montulli, "HTTP State Management 1518 Mechanism", RFC 2965, October 2000. 1520 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1522 [Netscape] 1523 Netscape Communications Corp., "Persistent Client State -- 1524 HTTP Cookies", 1999, . 1528 [Kri2001] Kristol, D., "HTTP Cookies: Standards, Privacy, and 1529 Politics", ACM Transactions on Internet Technology Vol. 1, 1530 #2, November 2001, . 1532 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1533 Procedures for Message Header Fields", BCP 90, RFC 3864, 1534 September 2004. 1536 Appendix A. Acknowledgements 1538 This document borrows heavily from RFC 2109 [RFC2109]. We are 1539 indebted to David M. Kristol and Lou Montulli for their efforts to 1540 specify cookies. David M. Kristol, in particular, provided 1541 invaluable advice on navigating the IETF process. We would also like 1542 to thank Thomas Broyer, Tyler Close, Bil Corry, corvid, Lisa 1543 Dusseault, Roy T. Fielding, Blake Frantz, Anne van Kesteren, Eran 1544 Hammer-Lahav, Jeff Hodges, Bjoern Hoehrmann, Achim Hoffmann, Georg 1545 Koppen, Dean McNamee, Mark Miller, Mark Pauley, Yngve N. Pettersen, 1546 Julian Reschke, Peter Saint-Andre, Mark Seaborn, Maciej Stachowiak, 1547 Daniel Stenberg, David Wagner, Dan Winship, and Dan Witte for their 1548 valuable feedback on this document. 1550 Author's Address 1552 Adam Barth 1553 University of California, Berkeley 1555 Email: abarth@eecs.berkeley.edu 1556 URI: http://www.adambarth.com/