idnits 2.17.1 draft-ietf-httpbis-rfc6265bis-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The abstract seems to indicate that this document obsoletes RFC2965, but the header doesn't have an 'Obsoletes:' line to match this. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 10, 2016) is 2748 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 3490 (Obsoleted by RFC 5890, RFC 5891) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' -- Obsolete informational reference (is this intentional?): RFC 2109 (Obsoleted by RFC 2965) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 2965 (Obsoleted by RFC 6265) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP Working Group A. Barth 3 Internet-Draft M. West 4 Intended status: Standards Track Google, Inc 5 Expires: April 13, 2017 October 10, 2016 7 HTTP State Management Mechanism 8 draft-ietf-httpbis-rfc6265bis-00 10 Abstract 12 This document defines the HTTP Cookie and Set-Cookie header fields. 13 These header fields can be used by HTTP servers to store state 14 (called cookies) at HTTP user agents, letting the servers maintain a 15 stateful session over the mostly stateless HTTP protocol. Although 16 cookies have many historical infelicities that degrade their security 17 and privacy, the Cookie and Set-Cookie header fields are widely used 18 on the Internet. This document obsoletes RFC 2965. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on April 13, 2017. 37 Copyright Notice 39 Copyright (c) 2016 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 2.1. Conformance Criteria . . . . . . . . . . . . . . . . . . 4 57 2.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 5 58 2.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 59 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 6 61 4. Server Requirements . . . . . . . . . . . . . . . . . . . . . 8 62 4.1. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . 8 63 4.1.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . 8 64 4.1.2. Semantics (Non-Normative) . . . . . . . . . . . . . . 10 65 4.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . 13 66 4.2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . 13 67 4.2.2. Semantics . . . . . . . . . . . . . . . . . . . . . . 13 68 5. User Agent Requirements . . . . . . . . . . . . . . . . . . . 13 69 5.1. Subcomponent Algorithms . . . . . . . . . . . . . . . . . 14 70 5.1.1. Dates . . . . . . . . . . . . . . . . . . . . . . . . 14 71 5.1.2. Canonicalized Host Names . . . . . . . . . . . . . . 15 72 5.1.3. Domain Matching . . . . . . . . . . . . . . . . . . . 16 73 5.1.4. Paths and Path-Match . . . . . . . . . . . . . . . . 16 74 5.2. The Set-Cookie Header . . . . . . . . . . . . . . . . . . 17 75 5.2.1. The Expires Attribute . . . . . . . . . . . . . . . . 18 76 5.2.2. The Max-Age Attribute . . . . . . . . . . . . . . . . 19 77 5.2.3. The Domain Attribute . . . . . . . . . . . . . . . . 19 78 5.2.4. The Path Attribute . . . . . . . . . . . . . . . . . 20 79 5.2.5. The Secure Attribute . . . . . . . . . . . . . . . . 20 80 5.2.6. The HttpOnly Attribute . . . . . . . . . . . . . . . 20 81 5.3. Storage Model . . . . . . . . . . . . . . . . . . . . . . 20 82 5.4. The Cookie Header . . . . . . . . . . . . . . . . . . . . 23 83 6. Implementation Considerations . . . . . . . . . . . . . . . . 25 84 6.1. Limits . . . . . . . . . . . . . . . . . . . . . . . . . 25 85 6.2. Application Programming Interfaces . . . . . . . . . . . 25 86 6.3. IDNA Dependency and Migration . . . . . . . . . . . . . . 26 87 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 26 88 7.1. Third-Party Cookies . . . . . . . . . . . . . . . . . . . 26 89 7.2. User Controls . . . . . . . . . . . . . . . . . . . . . . 27 90 7.3. Expiration Dates . . . . . . . . . . . . . . . . . . . . 27 91 8. Security Considerations . . . . . . . . . . . . . . . . . . . 28 92 8.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 28 93 8.2. Ambient Authority . . . . . . . . . . . . . . . . . . . . 28 94 8.3. Clear Text . . . . . . . . . . . . . . . . . . . . . . . 29 95 8.4. Session Identifiers . . . . . . . . . . . . . . . . . . . 29 96 8.5. Weak Confidentiality . . . . . . . . . . . . . . . . . . 30 97 8.6. Weak Integrity . . . . . . . . . . . . . . . . . . . . . 31 98 8.7. Reliance on DNS . . . . . . . . . . . . . . . . . . . . . 31 99 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 100 9.1. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . 32 101 9.2. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . 32 102 9.3. Cookie2 . . . . . . . . . . . . . . . . . . . . . . . . . 32 103 9.4. Set-Cookie2 . . . . . . . . . . . . . . . . . . . . . . . 32 104 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 32 105 10.1. Normative References . . . . . . . . . . . . . . . . . . 32 106 10.2. Informative References . . . . . . . . . . . . . . . . . 33 107 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 35 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35 110 1. Introduction 112 This document defines the HTTP Cookie and Set-Cookie header fields. 113 Using the Set-Cookie header field, an HTTP server can pass name/value 114 pairs and associated metadata (called cookies) to a user agent. When 115 the user agent makes subsequent requests to the server, the user 116 agent uses the metadata and other information to determine whether to 117 return the name/value pairs in the Cookie header. 119 Although simple on their surface, cookies have a number of 120 complexities. For example, the server indicates a scope for each 121 cookie when sending it to the user agent. The scope indicates the 122 maximum amount of time in which the user agent should return the 123 cookie, the servers to which the user agent should return the cookie, 124 and the URI schemes for which the cookie is applicable. 126 For historical reasons, cookies contain a number of security and 127 privacy infelicities. For example, a server can indicate that a 128 given cookie is intended for "secure" connections, but the Secure 129 attribute does not provide integrity in the presence of an active 130 network attacker. Similarly, cookies for a given host are shared 131 across all the ports on that host, even though the usual "same-origin 132 policy" used by web browsers isolates content retrieved via different 133 ports. 135 There are two audiences for this specification: developers of cookie- 136 generating servers and developers of cookie-consuming user agents. 138 To maximize interoperability with user agents, servers SHOULD limit 139 themselves to the well-behaved profile defined in Section 4 when 140 generating cookies. 142 User agents MUST implement the more liberal processing rules defined 143 in Section 5, in order to maximize interoperability with existing 144 servers that do not conform to the well-behaved profile defined in 145 Section 4. 147 This document specifies the syntax and semantics of these headers as 148 they are actually used on the Internet. In particular, this document 149 does not create new syntax or semantics beyond those in use today. 150 The recommendations for cookie generation provided in Section 4 151 represent a preferred subset of current server behavior, and even the 152 more liberal cookie processing algorithm provided in Section 5 does 153 not recommend all of the syntactic and semantic variations in use 154 today. Where some existing software differs from the recommended 155 protocol in significant ways, the document contains a note explaining 156 the difference. 158 Prior to this document, there were at least three descriptions of 159 cookies: the so-called "Netscape cookie specification" [Netscape], 160 RFC 2109 [RFC2109], and RFC 2965 [RFC2965]. However, none of these 161 documents describe how the Cookie and Set-Cookie headers are actually 162 used on the Internet (see [Kri2001] for historical context). In 163 relation to previous IETF specifications of HTTP state management 164 mechanisms, this document requests the following actions: 166 1. Change the status of [RFC2109] to Historic (it has already been 167 obsoleted by [RFC2965]). 168 2. Change the status of [RFC2965] to Historic. 169 3. Indicate that [RFC2965] has been obsoleted by this document. 171 In particular, in moving RFC 2965 to Historic and obsoleting it, this 172 document deprecates the use of the Cookie2 and Set-Cookie2 header 173 fields. 175 2. Conventions 177 2.1. Conformance Criteria 179 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 180 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 181 document are to be interpreted as described in [RFC2119]. 183 Requirements phrased in the imperative as part of algorithms (such as 184 "strip any leading space characters" or "return false and abort these 185 steps") are to be interpreted with the meaning of the key word 186 ("MUST", "SHOULD", "MAY", etc.) used in introducing the algorithm. 188 Conformance requirements phrased as algorithms or specific steps can 189 be implemented in any manner, so long as the end result is 190 equivalent. In particular, the algorithms defined in this 191 specification are intended to be easy to understand and are not 192 intended to be performant. 194 2.2. Syntax Notation 196 This specification uses the Augmented Backus-Naur Form (ABNF) 197 notation of [RFC5234]. 199 The following core rules are included by reference, as defined in 200 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 201 (CR LF), CTLs (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 202 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), NUL (null octet), 203 OCTET (any 8-bit sequence of data except NUL), SP (space), HTAB 204 (horizontal tab), CHAR (any [USASCII] character), VCHAR (any visible 205 [USASCII] character), and WSP (whitespace). 207 The OWS (optional whitespace) rule is used where zero or more linear 208 whitespace characters MAY appear: 210 OWS = *( [ obs-fold ] WSP ) 211 ; "optional" whitespace 212 obs-fold = CRLF 214 OWS SHOULD either not be produced or be produced as a single SP 215 character. 217 2.3. Terminology 219 The terms "user agent", "client", "server", "proxy", and "origin 220 server" have the same meaning as in the HTTP/1.1 specification 221 ([RFC2616], Section 1.3). 223 The request-host is the name of the host, as known by the user agent, 224 to which the user agent is sending an HTTP request or from which it 225 is receiving an HTTP response (i.e., the name of the host to which it 226 sent the corresponding HTTP request). 228 The term request-uri is defined in Section 5.1.2 of [RFC2616]. 230 Two sequences of octets are said to case-insensitively match each 231 other if and only if they are equivalent under the i;ascii-casemap 232 collation defined in [RFC4790]. 234 The term string means a sequence of non-NUL octets. 236 3. Overview 238 This section outlines a way for an origin server to send state 239 information to a user agent and for the user agent to return the 240 state information to the origin server. 242 To store state, the origin server includes a Set-Cookie header in an 243 HTTP response. In subsequent requests, the user agent returns a 244 Cookie request header to the origin server. The Cookie header 245 contains cookies the user agent received in previous Set-Cookie 246 headers. The origin server is free to ignore the Cookie header or 247 use its contents for an application-defined purpose. 249 Origin servers MAY send a Set-Cookie response header with any 250 response. User agents MAY ignore Set-Cookie headers contained in 251 responses with 100-level status codes but MUST process Set-Cookie 252 headers contained in other responses (including responses with 400- 253 and 500-level status codes). An origin server can include multiple 254 Set-Cookie header fields in a single response. The presence of a 255 Cookie or a Set-Cookie header field does not preclude HTTP caches 256 from storing and reusing a response. 258 Origin servers SHOULD NOT fold multiple Set-Cookie header fields into 259 a single header field. The usual mechanism for folding HTTP headers 260 fields (i.e., as defined in [RFC2616]) might change the semantics of 261 the Set-Cookie header field because the %x2C (",") character is used 262 by Set-Cookie in a way that conflicts with such folding. 264 3.1. Examples 266 Using the Set-Cookie header, a server can send the user agent a short 267 string in an HTTP response that the user agent will return in future 268 HTTP requests that are within the scope of the cookie. For example, 269 the server can send the user agent a "session identifier" named SID 270 with the value 31d4d96e407aad42. The user agent then returns the 271 session identifier in subsequent requests. 273 == Server -> User Agent == 275 Set-Cookie: SID=31d4d96e407aad42 277 == User Agent -> Server == 279 Cookie: SID=31d4d96e407aad42 281 The server can alter the default scope of the cookie using the Path 282 and Domain attributes. For example, the server can instruct the user 283 agent to return the cookie to every path and every subdomain of 284 example.com. 286 == Server -> User Agent == 288 Set-Cookie: SID=31d4d96e407aad42; Path=/; Domain=example.com 290 == User Agent -> Server == 292 Cookie: SID=31d4d96e407aad42 294 As shown in the next example, the server can store multiple cookies 295 at the user agent. For example, the server can store a session 296 identifier as well as the user's preferred language by returning two 297 Set-Cookie header fields. Notice that the server uses the Secure and 298 HttpOnly attributes to provide additional security protections for 299 the more sensitive session identifier (see Section 4.1.2). 301 == Server -> User Agent == 303 Set-Cookie: SID=31d4d96e407aad42; Path=/; Secure; HttpOnly 304 Set-Cookie: lang=en-US; Path=/; Domain=example.com 306 == User Agent -> Server == 308 Cookie: SID=31d4d96e407aad42; lang=en-US 310 Notice that the Cookie header above contains two cookies, one named 311 SID and one named lang. If the server wishes the user agent to 312 persist the cookie over multiple "sessions" (e.g., user agent 313 restarts), the server can specify an expiration date in the Expires 314 attribute. Note that the user agent might delete the cookie before 315 the expiration date if the user agent's cookie store exceeds its 316 quota or if the user manually deletes the server's cookie. 318 == Server -> User Agent == 320 Set-Cookie: lang=en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT 322 == User Agent -> Server == 324 Cookie: SID=31d4d96e407aad42; lang=en-US 326 Finally, to remove a cookie, the server returns a Set-Cookie header 327 with an expiration date in the past. The server will be successful 328 in removing the cookie only if the Path and the Domain attribute in 329 the Set-Cookie header match the values used when the cookie was 330 created. 332 == Server -> User Agent == 334 Set-Cookie: lang=; Expires=Sun, 06 Nov 1994 08:49:37 GMT 336 == User Agent -> Server == 338 Cookie: SID=31d4d96e407aad42 340 4. Server Requirements 342 This section describes the syntax and semantics of a well-behaved 343 profile of the Cookie and Set-Cookie headers. 345 4.1. Set-Cookie 347 The Set-Cookie HTTP response header is used to send cookies from the 348 server to the user agent. 350 4.1.1. Syntax 352 Informally, the Set-Cookie response header contains the header name 353 "Set-Cookie" followed by a ":" and a cookie. Each cookie begins with 354 a name-value-pair, followed by zero or more attribute-value pairs. 355 Servers SHOULD NOT send Set-Cookie headers that fail to conform to 356 the following grammar: 358 set-cookie-header = "Set-Cookie:" SP set-cookie-string 359 set-cookie-string = cookie-pair *( ";" SP cookie-av ) 360 cookie-pair = cookie-name "=" cookie-value 361 cookie-name = token 362 cookie-value = *cookie-octet / ( DQUOTE *cookie-octet DQUOTE ) 363 cookie-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E 364 ; US-ASCII characters excluding CTLs, 365 ; whitespace DQUOTE, comma, semicolon, 366 ; and backslash 367 token = token 368 ; defined in [RFC2616], Section 2.2 370 cookie-av = expires-av / max-age-av / domain-av / 371 path-av / secure-av / httponly-av / 372 extension-av 373 expires-av = "Expires=" sane-cookie-date 374 sane-cookie-date = rfc1123-date 375 ; defined in [RFC2616], Section 3.3.1 376 max-age-av = "Max-Age=" non-zero-digit *DIGIT 377 ; In practice, both expires-av and max-age-av 378 ; are limited to dates representable by the 379 ; user agent. 380 non-zero-digit = %x31-39 381 ; digits 1 through 9 382 domain-av = "Domain=" domain-value 383 domain-value = 384 ; defined in [RFC1034], Section 3.5, as 385 ; enhanced by [RFC1123], Section 2.1 386 path-av = "Path=" path-value 387 path-value = 388 secure-av = "Secure" 389 httponly-av = "HttpOnly" 390 extension-av = 392 Note that some of the grammatical terms above reference documents 393 that use different grammatical notations than this document (which 394 uses ABNF from [RFC5234]). 396 The semantics of the cookie-value are not defined by this document. 398 To maximize compatibility with user agents, servers that wish to 399 store arbitrary data in a cookie-value SHOULD encode that data, for 400 example, using Base64 [RFC4648]. 402 The portions of the set-cookie-string produced by the cookie-av term 403 are known as attributes. To maximize compatibility with user agents, 404 servers SHOULD NOT produce two attributes with the same name in the 405 same set-cookie-string. (See Section 5.3 for how user agents handle 406 this case.) 408 Servers SHOULD NOT include more than one Set-Cookie header field in 409 the same response with the same cookie-name. (See Section 5.2 for 410 how user agents handle this case.) 412 If a server sends multiple responses containing Set-Cookie headers 413 concurrently to the user agent (e.g., when communicating with the 414 user agent over multiple sockets), these responses create a "race 415 condition" that can lead to unpredictable behavior. 417 NOTE: Some existing user agents differ in their interpretation of 418 two-digit years. To avoid compatibility issues, servers SHOULD use 419 the rfc1123-date format, which requires a four-digit year. 421 NOTE: Some user agents store and process dates in cookies as 32-bit 422 UNIX time_t values. Implementation bugs in the libraries supporting 423 time_t processing on some systems might cause such user agents to 424 process dates after the year 2038 incorrectly. 426 4.1.2. Semantics (Non-Normative) 428 This section describes simplified semantics of the Set-Cookie header. 429 These semantics are detailed enough to be useful for understanding 430 the most common uses of cookies by servers. The full semantics are 431 described in Section 5. 433 When the user agent receives a Set-Cookie header, the user agent 434 stores the cookie together with its attributes. Subsequently, when 435 the user agent makes an HTTP request, the user agent includes the 436 applicable, non-expired cookies in the Cookie header. 438 If the user agent receives a new cookie with the same cookie-name, 439 domain-value, and path-value as a cookie that it has already stored, 440 the existing cookie is evicted and replaced with the new cookie. 441 Notice that servers can delete cookies by sending the user agent a 442 new cookie with an Expires attribute with a value in the past. 444 Unless the cookie's attributes indicate otherwise, the cookie is 445 returned only to the origin server (and not, for example, to any 446 subdomains), and it expires at the end of the current session (as 447 defined by the user agent). User agents ignore unrecognized cookie 448 attributes (but not the entire cookie). 450 4.1.2.1. The Expires Attribute 452 The Expires attribute indicates the maximum lifetime of the cookie, 453 represented as the date and time at which the cookie expires. The 454 user agent is not required to retain the cookie until the specified 455 date has passed. In fact, user agents often evict cookies due to 456 memory pressure or privacy concerns. 458 4.1.2.2. The Max-Age Attribute 460 The Max-Age attribute indicates the maximum lifetime of the cookie, 461 represented as the number of seconds until the cookie expires. The 462 user agent is not required to retain the cookie for the specified 463 duration. In fact, user agents often evict cookies due to memory 464 pressure or privacy concerns. 466 NOTE: Some existing user agents do not support the Max-Age attribute. 467 User agents that do not support the Max-Age attribute ignore the 468 attribute. 470 If a cookie has both the Max-Age and the Expires attribute, the Max- 471 Age attribute has precedence and controls the expiration date of the 472 cookie. If a cookie has neither the Max-Age nor the Expires 473 attribute, the user agent will retain the cookie until "the current 474 session is over" (as defined by the user agent). 476 4.1.2.3. The Domain Attribute 478 The Domain attribute specifies those hosts to which the cookie will 479 be sent. For example, if the value of the Domain attribute is 480 "example.com", the user agent will include the cookie in the Cookie 481 header when making HTTP requests to example.com, www.example.com, and 482 www.corp.example.com. (Note that a leading %x2E ("."), if present, 483 is ignored even though that character is not permitted, but a 484 trailing %x2E ("."), if present, will cause the user agent to ignore 485 the attribute.) If the server omits the Domain attribute, the user 486 agent will return the cookie only to the origin server. 488 WARNING: Some existing user agents treat an absent Domain attribute 489 as if the Domain attribute were present and contained the current 490 host name. For example, if example.com returns a Set-Cookie header 491 without a Domain attribute, these user agents will erroneously send 492 the cookie to www.example.com as well. 494 The user agent will reject cookies unless the Domain attribute 495 specifies a scope for the cookie that would include the origin 496 server. For example, the user agent will accept a cookie with a 497 Domain attribute of "example.com" or of "foo.example.com" from 498 foo.example.com, but the user agent will not accept a cookie with a 499 Domain attribute of "bar.example.com" or of "baz.foo.example.com". 501 NOTE: For security reasons, many user agents are configured to reject 502 Domain attributes that correspond to "public suffixes". For example, 503 some user agents will reject Domain attributes of "com" or "co.uk". 504 (See Section 5.3 for more information.) 506 4.1.2.4. The Path Attribute 508 The scope of each cookie is limited to a set of paths, controlled by 509 the Path attribute. If the server omits the Path attribute, the user 510 agent will use the "directory" of the request-uri's path component as 511 the default value. (See Section 5.1.4 for more details.) 513 The user agent will include the cookie in an HTTP request only if the 514 path portion of the request-uri matches (or is a subdirectory of) the 515 cookie's Path attribute, where the %x2F ("/") character is 516 interpreted as a directory separator. 518 Although seemingly useful for isolating cookies between different 519 paths within a given host, the Path attribute cannot be relied upon 520 for security (see Section 8). 522 4.1.2.5. The Secure Attribute 524 The Secure attribute limits the scope of the cookie to "secure" 525 channels (where "secure" is defined by the user agent). When a 526 cookie has the Secure attribute, the user agent will include the 527 cookie in an HTTP request only if the request is transmitted over a 528 secure channel (typically HTTP over Transport Layer Security (TLS) 529 [RFC2818]). 531 Although seemingly useful for protecting cookies from active network 532 attackers, the Secure attribute protects only the cookie's 533 confidentiality. An active network attacker can overwrite Secure 534 cookies from an insecure channel, disrupting their integrity (see 535 Section 8.6 for more details). 537 4.1.2.6. The HttpOnly Attribute 539 The HttpOnly attribute limits the scope of the cookie to HTTP 540 requests. In particular, the attribute instructs the user agent to 541 omit the cookie when providing access to cookies via "non-HTTP" APIs 542 (such as a web browser API that exposes cookies to scripts). 544 Note that the HttpOnly attribute is independent of the Secure 545 attribute: a cookie can have both the HttpOnly and the Secure 546 attribute. 548 4.2. Cookie 550 4.2.1. Syntax 552 The user agent sends stored cookies to the origin server in the 553 Cookie header. If the server conforms to the requirements in 554 Section 4.1 (and the user agent conforms to the requirements in 555 Section 5), the user agent will send a Cookie header that conforms to 556 the following grammar: 558 cookie-header = "Cookie:" OWS cookie-string OWS 559 cookie-string = cookie-pair *( ";" SP cookie-pair ) 561 4.2.2. Semantics 563 Each cookie-pair represents a cookie stored by the user agent. The 564 cookie-pair contains the cookie-name and cookie-value the user agent 565 received in the Set-Cookie header. 567 Notice that the cookie attributes are not returned. In particular, 568 the server cannot determine from the Cookie header alone when a 569 cookie will expire, for which hosts the cookie is valid, for which 570 paths the cookie is valid, or whether the cookie was set with the 571 Secure or HttpOnly attributes. 573 The semantics of individual cookies in the Cookie header are not 574 defined by this document. Servers are expected to imbue these 575 cookies with application-specific semantics. 577 Although cookies are serialized linearly in the Cookie header, 578 servers SHOULD NOT rely upon the serialization order. In particular, 579 if the Cookie header contains two cookies with the same name (e.g., 580 that were set with different Path or Domain attributes), servers 581 SHOULD NOT rely upon the order in which these cookies appear in the 582 header. 584 5. User Agent Requirements 586 This section specifies the Cookie and Set-Cookie headers in 587 sufficient detail that a user agent implementing these requirements 588 precisely can interoperate with existing servers (even those that do 589 not conform to the well-behaved profile described in Section 4). 591 A user agent could enforce more restrictions than those specified 592 herein (e.g., for the sake of improved security); however, 593 experiments have shown that such strictness reduces the likelihood 594 that a user agent will be able to interoperate with existing servers. 596 5.1. Subcomponent Algorithms 598 This section defines some algorithms used by user agents to process 599 specific subcomponents of the Cookie and Set-Cookie headers. 601 5.1.1. Dates 603 The user agent MUST use an algorithm equivalent to the following 604 algorithm to parse a cookie-date. Note that the various boolean 605 flags defined as a part of the algorithm (i.e., found-time, found- 606 day-of-month, found-month, found-year) are initially "not set". 608 1. Using the grammar below, divide the cookie-date into date-tokens. 610 cookie-date = *delimiter date-token-list *delimiter 611 date-token-list = date-token *( 1*delimiter date-token ) 612 date-token = 1*non-delimiter 614 delimiter = %x09 / %x20-2F / %x3B-40 / %x5B-60 / %x7B-7E 615 non-delimiter = %x00-08 / %x0A-1F / DIGIT / ":" / ALPHA / %x7F-FF 616 non-digit = %x00-2F / %x3A-FF 618 day-of-month = 1*2DIGIT ( non-digit *OCTET ) 619 month = ( "jan" / "feb" / "mar" / "apr" / 620 "may" / "jun" / "jul" / "aug" / 621 "sep" / "oct" / "nov" / "dec" ) *OCTET 622 year = 2*4DIGIT ( non-digit *OCTET ) 623 time = hms-time ( non-digit *OCTET ) 624 hms-time = time-field ":" time-field ":" time-field 625 time-field = 1*2DIGIT 626 2. Process each date-token sequentially in the order the date-tokens 627 appear in the cookie-date: 629 1. If the found-time flag is not set and the token matches the 630 time production, set the found-time flag and set the hour- 631 value, minute-value, and second-value to the numbers denoted 632 by the digits in the date-token, respectively. Skip the 633 remaining sub-steps and continue to the next date-token. 634 2. If the found-day-of-month flag is not set and the date-token 635 matches the day-of-month production, set the found-day-of- 636 month flag and set the day-of-month-value to the number 637 denoted by the date-token. Skip the remaining sub-steps and 638 continue to the next date-token. 639 3. If the found-month flag is not set and the date-token matches 640 the month production, set the found-month flag and set the 641 month-value to the month denoted by the date-token. Skip the 642 remaining sub-steps and continue to the next date-token. 643 4. If the found-year flag is not set and the date-token matches 644 the year production, set the found-year flag and set the 645 year-value to the number denoted by the date-token. Skip the 646 remaining sub-steps and continue to the next date-token. 647 3. If the year-value is greater than or equal to 70 and less than or 648 equal to 99, increment the year-value by 1900. 649 4. If the year-value is greater than or equal to 0 and less than or 650 equal to 69, increment the year-value by 2000. 652 1. NOTE: Some existing user agents interpret two-digit years 653 differently. 654 5. Abort these steps and fail to parse the cookie-date if: 656 * at least one of the found-day-of-month, found-month, found- 657 year, or found-time flags is not set, 658 * the day-of-month-value is less than 1 or greater than 31, 659 * the year-value is less than 1601, 660 * the hour-value is greater than 23, 661 * the minute-value is greater than 59, or 662 * the second-value is greater than 59. 664 (Note that leap seconds cannot be represented in this syntax.) 665 6. Let the parsed-cookie-date be the date whose day-of-month, month, 666 year, hour, minute, and second (in UTC) are the day-of-month- 667 value, the month-value, the year-value, the hour-value, the 668 minute-value, and the second-value, respectively. If no such 669 date exists, abort these steps and fail to parse the cookie-date. 670 7. Return the parsed-cookie-date as the result of this algorithm. 672 5.1.2. Canonicalized Host Names 674 A canonicalized host name is the string generated by the following 675 algorithm: 677 1. Convert the host name to a sequence of individual domain name 678 labels. 679 2. Convert each label that is not a Non-Reserved LDH (NR-LDH) label, 680 to an A-label (see Section 2.3.2.1 of [RFC5890] for the former 681 and latter), or to a "punycode label" (a label resulting from the 682 "ToASCII" conversion in Section 4 of [RFC3490]), as appropriate 683 (see Section 6.3 of this specification). 685 3. Concatenate the resulting labels, separated by a %x2E (".") 686 character. 688 5.1.3. Domain Matching 690 A string domain-matches a given domain string if at least one of the 691 following conditions hold: 693 o The domain string and the string are identical. (Note that both 694 the domain string and the string will have been canonicalized to 695 lower case at this point.) 696 o All of the following conditions hold: 697 o The domain string is a suffix of the string. 698 o The last character of the string that is not included in the 699 domain string is a %x2E (".") character. 700 o The string is a host name (i.e., not an IP address). 702 5.1.4. Paths and Path-Match 704 The user agent MUST use an algorithm equivalent to the following 705 algorithm to compute the default-path of a cookie: 707 1. Let uri-path be the path portion of the request-uri if such a 708 portion exists (and empty otherwise). For example, if the 709 request-uri contains just a path (and optional query string), 710 then the uri-path is that path (without the %x3F ("?") character 711 or query string), and if the request-uri contains a full 712 absoluteURI, the uri-path is the path component of that URI. 713 2. If the uri-path is empty or if the first character of the uri- 714 path is not a %x2F ("/") character, output %x2F ("/") and skip 715 the remaining steps. 716 3. If the uri-path contains no more than one %x2F ("/") character, 717 output %x2F ("/") and skip the remaining step. 718 4. Output the characters of the uri-path from the first character up 719 to, but not including, the right-most %x2F ("/"). 721 A request-path path-matches a given cookie-path if at least one of 722 the following conditions holds: 724 o The cookie-path and the request-path are identical. 725 o The cookie-path is a prefix of the request-path, and the last 726 character of the cookie-path is %x2F ("/"). 727 o The cookie-path is a prefix of the request-path, and the first 728 character of the request-path that is not included in the cookie- 729 path is a %x2F ("/") character. 731 5.2. The Set-Cookie Header 733 When a user agent receives a Set-Cookie header field in an HTTP 734 response, the user agent MAY ignore the Set-Cookie header field in 735 its entirety. For example, the user agent might wish to block 736 responses to "third-party" requests from setting cookies (see 737 Section 7.1). 739 If the user agent does not ignore the Set-Cookie header field in its 740 entirety, the user agent MUST parse the field-value of the Set-Cookie 741 header field as a set-cookie-string (defined below). 743 NOTE: The algorithm below is more permissive than the grammar in 744 Section 4.1. For example, the algorithm strips leading and trailing 745 whitespace from the cookie name and value (but maintains internal 746 whitespace), whereas the grammar in Section 4.1 forbids whitespace in 747 these positions. User agents use this algorithm so as to 748 interoperate with servers that do not follow the recommendations in 749 Section 4. 751 A user agent MUST use an algorithm equivalent to the following 752 algorithm to parse a set-cookie-string: 754 1. If the set-cookie-string contains a %x3B (";") character: 756 1. The name-value-pair string consists of the characters up to, 757 but not including, the first %x3B (";"), and the unparsed- 758 attributes consist of the remainder of the set-cookie-string 759 (including the %x3B (";") in question). 761 Otherwise: 763 1. The name-value-pair string consists of all the characters 764 contained in the set-cookie-string, and the unparsed- 765 attributes is the empty string. 766 2. If the name-value-pair string lacks a %x3D ("=") character, 767 ignore the set-cookie-string entirely. 768 3. The (possibly empty) name string consists of the characters up 769 to, but not including, the first %x3D ("=") character, and the 770 (possibly empty) value string consists of the characters after 771 the first %x3D ("=") character. 772 4. Remove any leading or trailing WSP characters from the name 773 string and the value string. 774 5. If the name string is empty, ignore the set-cookie-string 775 entirely. 776 6. The cookie-name is the name string, and the cookie-value is the 777 value string. 779 The user agent MUST use an algorithm equivalent to the following 780 algorithm to parse the unparsed-attributes: 782 1. If the unparsed-attributes string is empty, skip the rest of 783 these steps. 784 2. Discard the first character of the unparsed-attributes (which 785 will be a %x3B (";") character). 786 3. If the remaining unparsed-attributes contains a %x3B (";") 787 character: 789 1. Consume the characters of the unparsed-attributes up to, but 790 not including, the first %x3B (";") character. 792 Otherwise: 794 1. Consume the remainder of the unparsed-attributes. 796 Let the cookie-av string be the characters consumed in this step. 797 4. If the cookie-av string contains a %x3D ("=") character: 799 1. The (possibly empty) attribute-name string consists of the 800 characters up to, but not including, the first %x3D ("=") 801 character, and the (possibly empty) attribute-value string 802 consists of the characters after the first %x3D ("=") 803 character. 805 Otherwise: 807 1. The attribute-name string consists of the entire cookie-av 808 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. 811 6. Process the attribute-name and attribute-value according to the 812 requirements in the following subsections. (Notice that 813 attributes with unrecognized attribute-names are ignored.) 814 7. Return to Step 1 of this algorithm. 816 When the user agent finishes parsing the set-cookie-string, the user 817 agent is said to "receive a cookie" from the request-uri with name 818 cookie-name, value cookie-value, and attributes cookie-attribute- 819 list. (See Section 5.3 for additional requirements triggered by 820 receiving a cookie.) 822 5.2.1. The Expires Attribute 824 If the attribute-name case-insensitively matches the string 825 "Expires", the user agent MUST process the cookie-av as follows. 827 1. Let the expiry-time be the result of parsing the attribute-value 828 as cookie-date (see Section 5.1.1). 829 2. If the attribute-value failed to parse as a cookie date, ignore 830 the cookie-av. 831 3. If the expiry-time is later than the last date the user agent can 832 represent, the user agent MAY replace the expiry-time with the 833 last representable date. 834 4. If the expiry-time is earlier than the earliest date the user 835 agent can represent, the user agent MAY replace the expiry-time 836 with the earliest representable date. 837 5. Append an attribute to the cookie-attribute-list with an 838 attribute-name of Expires and an attribute-value of expiry-time. 840 5.2.2. The Max-Age Attribute 842 If the attribute-name case-insensitively matches the string "Max- 843 Age", the user agent MUST process the cookie-av as follows. 845 1. If the first character of the attribute-value is not a DIGIT or a 846 "-" character, ignore the cookie-av. 847 2. If the remainder of attribute-value contains a non-DIGIT 848 character, ignore the cookie-av. 849 3. Let delta-seconds be the attribute-value converted to an integer. 850 4. If delta-seconds is less than or equal to zero (0), let expiry- 851 time be the earliest representable date and time. Otherwise, let 852 the expiry-time be the current date and time plus delta-seconds 853 seconds. 854 5. Append an attribute to the cookie-attribute-list with an 855 attribute-name of Max-Age and an attribute-value of expiry-time. 857 5.2.3. The Domain Attribute 859 If the attribute-name case-insensitively matches the string "Domain", 860 the user agent MUST process the cookie-av as follows. 862 1. If the attribute-value is empty, the behavior is undefined. 863 However, the user agent SHOULD ignore the cookie-av entirely. 864 2. If the first character of the attribute-value string is %x2E 865 ("."): 867 1. Let cookie-domain be the attribute-value without the leading 868 %x2E (".") character. 870 Otherwise: 872 1. Let cookie-domain be the entire attribute-value. 873 3. Convert the cookie-domain to lower case. 875 4. Append an attribute to the cookie-attribute-list with an 876 attribute-name of Domain and an attribute-value of cookie-domain. 878 5.2.4. The Path Attribute 880 If the attribute-name case-insensitively matches the string "Path", 881 the user agent MUST process the cookie-av as follows. 883 1. If the attribute-value is empty or if the first character of the 884 attribute-value is not %x2F ("/"): 886 1. Let cookie-path be the default-path. 888 Otherwise: 890 1. Let cookie-path be the attribute-value. 891 2. Append an attribute to the cookie-attribute-list with an 892 attribute-name of Path and an attribute-value of cookie-path. 894 5.2.5. The Secure Attribute 896 If the attribute-name case-insensitively matches the string "Secure", 897 the user agent MUST append an attribute to the cookie-attribute-list 898 with an attribute-name of Secure and an empty attribute-value. 900 5.2.6. The HttpOnly Attribute 902 If the attribute-name case-insensitively matches the string 903 "HttpOnly", the user agent MUST append an attribute to the cookie- 904 attribute-list with an attribute-name of HttpOnly and an empty 905 attribute-value. 907 5.3. Storage Model 909 The user agent stores the following fields about each cookie: name, 910 value, expiry-time, domain, path, creation-time, last-access-time, 911 persistent-flag, host-only-flag, secure-only-flag, and http-only- 912 flag. 914 When the user agent "receives a cookie" from a request-uri with name 915 cookie-name, value cookie-value, and attributes cookie-attribute- 916 list, the user agent MUST process the cookie as follows: 918 1. A user agent MAY ignore a received cookie in its entirety. For 919 example, the user agent might wish to block receiving cookies 920 from "third-party" responses or the user agent might not wish to 921 store cookies that exceed some size. 923 2. Create a new cookie with name cookie-name, value cookie-value. 924 Set the creation-time and the last-access-time to the current 925 date and time. 926 3. If the cookie-attribute-list contains an attribute with an 927 attribute-name of "Max-Age": 929 1. Set the cookie's persistent-flag to true. 930 2. Set the cookie's expiry-time to attribute-value of the last 931 attribute in the cookie-attribute-list with an attribute- 932 name of "Max-Age". 934 Otherwise, if the cookie-attribute-list contains an attribute 935 with an attribute-name of "Expires" (and does not contain an 936 attribute with an attribute-name of "Max-Age"): 938 1. Set the cookie's persistent-flag to true. 939 2. Set the cookie's expiry-time to attribute-value of the last 940 attribute in the cookie-attribute-list with an attribute- 941 name of "Expires". 943 Otherwise: 945 1. Set the cookie's persistent-flag to false. 946 2. Set the cookie's expiry-time to the latest representable 947 date. 948 4. If the cookie-attribute-list contains an attribute with an 949 attribute-name iof "Domain": 951 1. Let the domain-attribute be the attribute-value of the last 952 attribute in the cookie-attribute-list with an attribute- 953 name of "Domain". 955 Otherwise: 957 1. Let the domain-attribute be the empty string. 958 5. If the user agent is configured to reject "public suffixes" and 959 the domain-attribute is a public suffix: 961 1. If the domain-attribute is identical to the canonicalized 962 request-host: 964 1. Let the domain-attribute be the empty string. 966 Otherwise: 968 1. Ignore the cookie entirely and abort these steps. 970 NOTE: A "public suffix" is a domain that is controlled by a 971 public registry, such as "com", "co.uk", and "pvt.k12.wy.us". 972 This step is essential for preventing attacker.com from 973 disrupting the integrity of example.com by setting a cookie with 974 a Domain attribute of "com". Unfortunately, the set of public 975 suffixes (also known as "registry controlled domains") changes 976 over time. If feasible, user agents SHOULD use an up-to-date 977 public suffix list, such as the one maintained by the Mozilla 978 project at http://publicsuffix.org/ . 979 6. If the domain-attribute is non-empty: 981 1. If the canonicalized request-host does not domain-match the 982 domain-attribute: 984 1. Ignore the cookie entirely and abort these steps. 986 Otherwise: 988 1. Set the cookie's host-only-flag to false. 989 2. Set the cookie's domain to the domain-attribute. 991 Otherwise: 993 1. Set the cookie's host-only-flag to true. 994 2. Set the cookie's domain to the canonicalized request-host. 995 7. If the cookie-attribute-list contains an attribute with an 996 attribute-name of "Path", set the cookie's path to attribute- 997 value of the last attribute in the cookie-attribute-list with an 998 attribute-name of "Path". Otherwise, set the cookie's path to 999 the default-path of the request-uri. 1000 8. If the cookie-attribute-list contains an attribute with an 1001 attribute-name of "Secure", set the cookie's secure-only-flag to 1002 true. Otherwise, set the cookie's secure-only-flag to false. 1003 9. If the cookie-attribute-list contains an attribute with an 1004 attribute-name of "HttpOnly", set the cookie's http-only-flag to 1005 true. Otherwise, set the cookie's http-only-flag to false. 1006 10. If the cookie was received from a "non-HTTP" API and the 1007 cookie's http-only-flag is set, abort these steps and ignore the 1008 cookie entirely. 1009 11. If the cookie store contains a cookie with the same name, 1010 domain, and path as the newly created cookie: 1012 1. Let old-cookie be the existing cookie with the same name, 1013 domain, and path as the newly created cookie. (Notice that 1014 this algorithm maintains the invariant that there is at most 1015 one such cookie.) 1017 2. If the newly created cookie was received from a "non-HTTP" 1018 API and the old-cookie's http-only-flag is set, abort these 1019 steps and ignore the newly created cookie entirely. 1020 3. Update the creation-time of the newly created cookie to 1021 match the creation-time of the old-cookie. 1022 4. Remove the old-cookie from the cookie store. 1023 12. Insert the newly created cookie into the cookie store. 1025 A cookie is "expired" if the cookie has an expiry date in the past. 1027 The user agent MUST evict all expired cookies from the cookie store 1028 if, at any time, an expired cookie exists in the cookie store. 1030 At any time, the user agent MAY "remove excess cookies" from the 1031 cookie store if the number of cookies sharing a domain field exceeds 1032 some implementation-defined upper bound (such as 50 cookies). 1034 At any time, the user agent MAY "remove excess cookies" from the 1035 cookie store if the cookie store exceeds some predetermined upper 1036 bound (such as 3000 cookies). 1038 When the user agent removes excess cookies from the cookie store, the 1039 user agent MUST evict cookies in the following priority order: 1041 1. Expired cookies. 1042 2. Cookies that share a domain field with more than a predetermined 1043 number of other cookies. 1044 3. All cookies. 1046 If two cookies have the same removal priority, the user agent MUST 1047 evict the cookie with the earliest last-access date first. 1049 When "the current session is over" (as defined by the user agent), 1050 the user agent MUST remove from the cookie store all cookies with the 1051 persistent-flag set to false. 1053 5.4. The Cookie Header 1055 The user agent includes stored cookies in the Cookie HTTP request 1056 header. 1058 When the user agent generates an HTTP request, the user agent MUST 1059 NOT attach more than one Cookie header field. 1061 A user agent MAY omit the Cookie header in its entirety. For 1062 example, the user agent might wish to block sending cookies during 1063 "third-party" requests from setting cookies (see Section 7.1). 1065 If the user agent does attach a Cookie header field to an HTTP 1066 request, the user agent MUST send the cookie-string (defined below) 1067 as the value of the header field. 1069 The user agent MUST use an algorithm equivalent to the following 1070 algorithm to compute the cookie-string from a cookie store and a 1071 request-uri: 1073 1. Let cookie-list be the set of cookies from the cookie store that 1074 meets all of the following requirements: 1076 * Either: 1078 + The cookie's host-only-flag is true and the canonicalized 1079 request-host is identical to the cookie's domain. 1081 Or: 1083 + The cookie's host-only-flag is false and the canonicalized 1084 request-host domain-matches the cookie's domain. 1085 * The request-uri's path path-matches the cookie's path. 1086 * If the cookie's secure-only-flag is true, then the request- 1087 uri's scheme must denote a "secure" protocol (as defined by 1088 the user agent). 1090 NOTE: The notion of a "secure" protocol is not defined by this 1091 document. Typically, user agents consider a protocol secure 1092 if the protocol makes use of transport-layer security, such as 1093 SSL or TLS. For example, most user agents consider "https" to 1094 be a scheme that denotes a secure protocol. 1095 * If the cookie's http-only-flag is true, then exclude the 1096 cookie if the cookie-string is being generated for a "non- 1097 HTTP" API (as defined by the user agent). 1098 2. The user agent SHOULD sort the cookie-list in the following 1099 order: 1101 * Cookies with longer paths are listed before cookies with 1102 shorter paths. 1103 * Among cookies that have equal-length path fields, cookies with 1104 earlier creation-times are listed before cookies with later 1105 creation-times. 1107 NOTE: Not all user agents sort the cookie-list in this order, but 1108 this order reflects common practice when this document was 1109 written, and, historically, there have been servers that 1110 (erroneously) depended on this order. 1111 3. Update the last-access-time of each cookie in the cookie-list to 1112 the current date and time. 1114 4. Serialize the cookie-list into a cookie-string by processing each 1115 cookie in the cookie-list in order: 1117 1. Output the cookie's name, the %x3D ("=") character, and the 1118 cookie's value. 1119 2. If there is an unprocessed cookie in the cookie-list, output 1120 the characters %x3B and %x20 ("; "). 1122 NOTE: Despite its name, the cookie-string is actually a sequence of 1123 octets, not a sequence of characters. To convert the cookie-string 1124 (or components thereof) into a sequence of characters (e.g., for 1125 presentation to the user), the user agent might wish to try using the 1126 UTF-8 character encoding [RFC3629] to decode the octet sequence. 1127 This decoding might fail, however, because not every sequence of 1128 octets is valid UTF-8. 1130 6. Implementation Considerations 1132 6.1. Limits 1134 Practical user agent implementations have limits on the number and 1135 size of cookies that they can store. General-use user agents SHOULD 1136 provide each of the following minimum capabilities: 1138 o At least 4096 bytes per cookie (as measured by the sum of the 1139 length of the cookie's name, value, and attributes). 1140 o At least 50 cookies per domain. 1141 o At least 3000 cookies total. 1143 Servers SHOULD use as few and as small cookies as possible to avoid 1144 reaching these implementation limits and to minimize network 1145 bandwidth due to the Cookie header being included in every request. 1147 Servers SHOULD gracefully degrade if the user agent fails to return 1148 one or more cookies in the Cookie header because the user agent might 1149 evict any cookie at any time on orders from the user. 1151 6.2. Application Programming Interfaces 1153 One reason the Cookie and Set-Cookie headers use such esoteric syntax 1154 is that many platforms (both in servers and user agents) provide a 1155 string-based application programming interface (API) to cookies, 1156 requiring application-layer programmers to generate and parse the 1157 syntax used by the Cookie and Set-Cookie headers, which many 1158 programmers have done incorrectly, resulting in interoperability 1159 problems. 1161 Instead of providing string-based APIs to cookies, platforms would be 1162 well-served by providing more semantic APIs. It is beyond the scope 1163 of this document to recommend specific API designs, but there are 1164 clear benefits to accepting an abstract "Date" object instead of a 1165 serialized date string. 1167 6.3. IDNA Dependency and Migration 1169 IDNA2008 [RFC5890] supersedes IDNA2003 [RFC3490]. However, there are 1170 differences between the two specifications, and thus there can be 1171 differences in processing (e.g., converting) domain name labels that 1172 have been registered under one from those registered under the other. 1173 There will be a transition period of some time during which 1174 IDNA2003-based domain name labels will exist in the wild. User 1175 agents SHOULD implement IDNA2008 [RFC5890] and MAY implement [UTS46] 1176 or [RFC5895] in order to facilitate their IDNA transition. If a user 1177 agent does not implement IDNA2008, the user agent MUST implement 1178 IDNA2003 [RFC3490]. 1180 7. Privacy Considerations 1182 Cookies are often criticized for letting servers track users. For 1183 example, a number of "web analytics" companies use cookies to 1184 recognize when a user returns to a web site or visits another web 1185 site. Although cookies are not the only mechanism servers can use to 1186 track users across HTTP requests, cookies facilitate tracking because 1187 they are persistent across user agent sessions and can be shared 1188 between hosts. 1190 7.1. Third-Party Cookies 1192 Particularly worrisome are so-called "third-party" cookies. In 1193 rendering an HTML document, a user agent often requests resources 1194 from other servers (such as advertising networks). These third-party 1195 servers can use cookies to track the user even if the user never 1196 visits the server directly. For example, if a user visits a site 1197 that contains content from a third party and then later visits 1198 another site that contains content from the same third party, the 1199 third party can track the user between the two sites. 1201 Some user agents restrict how third-party cookies behave. For 1202 example, some of these user agents refuse to send the Cookie header 1203 in third-party requests. Others refuse to process the Set-Cookie 1204 header in responses to third-party requests. User agents vary widely 1205 in their third-party cookie policies. This document grants user 1206 agents wide latitude to experiment with third-party cookie policies 1207 that balance the privacy and compatibility needs of their users. 1209 However, this document does not endorse any particular third-party 1210 cookie policy. 1212 Third-party cookie blocking policies are often ineffective at 1213 achieving their privacy goals if servers attempt to work around their 1214 restrictions to track users. In particular, two collaborating 1215 servers can often track users without using cookies at all by 1216 injecting identifying information into dynamic URLs. 1218 7.2. User Controls 1220 User agents SHOULD provide users with a mechanism for managing the 1221 cookies stored in the cookie store. For example, a user agent might 1222 let users delete all cookies received during a specified time period 1223 or all the cookies related to a particular domain. In addition, many 1224 user agents include a user interface element that lets users examine 1225 the cookies stored in their cookie store. 1227 User agents SHOULD provide users with a mechanism for disabling 1228 cookies. When cookies are disabled, the user agent MUST NOT include 1229 a Cookie header in outbound HTTP requests and the user agent MUST NOT 1230 process Set-Cookie headers in inbound HTTP responses. 1232 Some user agents provide users the option of preventing persistent 1233 storage of cookies across sessions. When configured thusly, user 1234 agents MUST treat all received cookies as if the persistent-flag were 1235 set to false. Some popular user agents expose this functionality via 1236 "private browsing" mode [Aggarwal2010]. 1238 Some user agents provide users with the ability to approve individual 1239 writes to the cookie store. In many common usage scenarios, these 1240 controls generate a large number of prompts. However, some privacy- 1241 conscious users find these controls useful nonetheless. 1243 7.3. Expiration Dates 1245 Although servers can set the expiration date for cookies to the 1246 distant future, most user agents do not actually retain cookies for 1247 multiple decades. Rather than choosing gratuitously long expiration 1248 periods, servers SHOULD promote user privacy by selecting reasonable 1249 cookie expiration periods based on the purpose of the cookie. For 1250 example, a typical session identifier might reasonably be set to 1251 expire in two weeks. 1253 8. Security Considerations 1255 8.1. Overview 1257 Cookies have a number of security pitfalls. This section overviews a 1258 few of the more salient issues. 1260 In particular, cookies encourage developers to rely on ambient 1261 authority for authentication, often becoming vulnerable to attacks 1262 such as cross-site request forgery [CSRF]. Also, when storing 1263 session identifiers in cookies, developers often create session 1264 fixation vulnerabilities. 1266 Transport-layer encryption, such as that employed in HTTPS, is 1267 insufficient to prevent a network attacker from obtaining or altering 1268 a victim's cookies because the cookie protocol itself has various 1269 vulnerabilities (see "Weak Confidentiality" and "Weak Integrity", 1270 below). In addition, by default, cookies do not provide 1271 confidentiality or integrity from network attackers, even when used 1272 in conjunction with HTTPS. 1274 8.2. Ambient Authority 1276 A server that uses cookies to authenticate users can suffer security 1277 vulnerabilities because some user agents let remote parties issue 1278 HTTP requests from the user agent (e.g., via HTTP redirects or HTML 1279 forms). When issuing those requests, user agents attach cookies even 1280 if the remote party does not know the contents of the cookies, 1281 potentially letting the remote party exercise authority at an unwary 1282 server. 1284 Although this security concern goes by a number of names (e.g., 1285 cross-site request forgery, confused deputy), the issue stems from 1286 cookies being a form of ambient authority. Cookies encourage server 1287 operators to separate designation (in the form of URLs) from 1288 authorization (in the form of cookies). Consequently, the user agent 1289 might supply the authorization for a resource designated by the 1290 attacker, possibly causing the server or its clients to undertake 1291 actions designated by the attacker as though they were authorized by 1292 the user. 1294 Instead of using cookies for authorization, server operators might 1295 wish to consider entangling designation and authorization by treating 1296 URLs as capabilities. Instead of storing secrets in cookies, this 1297 approach stores secrets in URLs, requiring the remote entity to 1298 supply the secret itself. Although this approach is not a panacea, 1299 judicious application of these principles can lead to more robust 1300 security. 1302 8.3. Clear Text 1304 Unless sent over a secure channel (such as TLS), the information in 1305 the Cookie and Set-Cookie headers is transmitted in the clear. 1307 1. All sensitive information conveyed in these headers is exposed to 1308 an eavesdropper. 1309 2. A malicious intermediary could alter the headers as they travel 1310 in either direction, with unpredictable results. 1311 3. A malicious client could alter the Cookie header before 1312 transmission, with unpredictable results. 1314 Servers SHOULD encrypt and sign the contents of cookies (using 1315 whatever format the server desires) when transmitting them to the 1316 user agent (even when sending the cookies over a secure channel). 1317 However, encrypting and signing cookie contents does not prevent an 1318 attacker from transplanting a cookie from one user agent to another 1319 or from replaying the cookie at a later time. 1321 In addition to encrypting and signing the contents of every cookie, 1322 servers that require a higher level of security SHOULD use the Cookie 1323 and Set-Cookie headers only over a secure channel. When using 1324 cookies over a secure channel, servers SHOULD set the Secure 1325 attribute (see Section 4.1.2.5) for every cookie. If a server does 1326 not set the Secure attribute, the protection provided by the secure 1327 channel will be largely moot. 1329 For example, consider a webmail server that stores a session 1330 identifier in a cookie and is typically accessed over HTTPS. If the 1331 server does not set the Secure attribute on its cookies, an active 1332 network attacker can intercept any outbound HTTP request from the 1333 user agent and redirect that request to the webmail server over HTTP. 1334 Even if the webmail server is not listening for HTTP connections, the 1335 user agent will still include cookies in the request. The active 1336 network attacker can intercept these cookies, replay them against the 1337 server, and learn the contents of the user's email. If, instead, the 1338 server had set the Secure attribute on its cookies, the user agent 1339 would not have included the cookies in the clear-text request. 1341 8.4. Session Identifiers 1343 Instead of storing session information directly in a cookie (where it 1344 might be exposed to or replayed by an attacker), servers commonly 1345 store a nonce (or "session identifier") in a cookie. When the server 1346 receives an HTTP request with a nonce, the server can look up state 1347 information associated with the cookie using the nonce as a key. 1349 Using session identifier cookies limits the damage an attacker can 1350 cause if the attacker learns the contents of a cookie because the 1351 nonce is useful only for interacting with the server (unlike non- 1352 nonce cookie content, which might itself be sensitive). Furthermore, 1353 using a single nonce prevents an attacker from "splicing" together 1354 cookie content from two interactions with the server, which could 1355 cause the server to behave unexpectedly. 1357 Using session identifiers is not without risk. For example, the 1358 server SHOULD take care to avoid "session fixation" vulnerabilities. 1359 A session fixation attack proceeds in three steps. First, the 1360 attacker transplants a session identifier from his or her user agent 1361 to the victim's user agent. Second, the victim uses that session 1362 identifier to interact with the server, possibly imbuing the session 1363 identifier with the user's credentials or confidential information. 1364 Third, the attacker uses the session identifier to interact with 1365 server directly, possibly obtaining the user's authority or 1366 confidential information. 1368 8.5. Weak Confidentiality 1370 Cookies do not provide isolation by port. If a cookie is readable by 1371 a service running on one port, the cookie is also readable by a 1372 service running on another port of the same server. If a cookie is 1373 writable by a service on one port, the cookie is also writable by a 1374 service running on another port of the same server. For this reason, 1375 servers SHOULD NOT both run mutually distrusting services on 1376 different ports of the same host and use cookies to store security- 1377 sensitive information. 1379 Cookies do not provide isolation by scheme. Although most commonly 1380 used with the http and https schemes, the cookies for a given host 1381 might also be available to other schemes, such as ftp and gopher. 1382 Although this lack of isolation by scheme is most apparent in non- 1383 HTTP APIs that permit access to cookies (e.g., HTML's document.cookie 1384 API), the lack of isolation by scheme is actually present in 1385 requirements for processing cookies themselves (e.g., consider 1386 retrieving a URI with the gopher scheme via HTTP). 1388 Cookies do not always provide isolation by path. Although the 1389 network-level protocol does not send cookies stored for one path to 1390 another, some user agents expose cookies via non-HTTP APIs, such as 1391 HTML's document.cookie API. Because some of these user agents (e.g., 1392 web browsers) do not isolate resources received from different paths, 1393 a resource retrieved from one path might be able to access cookies 1394 stored for another path. 1396 8.6. Weak Integrity 1398 Cookies do not provide integrity guarantees for sibling domains (and 1399 their subdomains). For example, consider foo.example.com and 1400 bar.example.com. The foo.example.com server can set a cookie with a 1401 Domain attribute of "example.com" (possibly overwriting an existing 1402 "example.com" cookie set by bar.example.com), and the user agent will 1403 include that cookie in HTTP requests to bar.example.com. In the 1404 worst case, bar.example.com will be unable to distinguish this cookie 1405 from a cookie it set itself. The foo.example.com server might be 1406 able to leverage this ability to mount an attack against 1407 bar.example.com. 1409 Even though the Set-Cookie header supports the Path attribute, the 1410 Path attribute does not provide any integrity protection because the 1411 user agent will accept an arbitrary Path attribute in a Set-Cookie 1412 header. For example, an HTTP response to a request for 1413 http://example.com/foo/bar can set a cookie with a Path attribute of 1414 "/qux". Consequently, servers SHOULD NOT both run mutually 1415 distrusting services on different paths of the same host and use 1416 cookies to store security-sensitive information. 1418 An active network attacker can also inject cookies into the Cookie 1419 header sent to https://example.com/ by impersonating a response from 1420 http://example.com/ and injecting a Set-Cookie header. The HTTPS 1421 server at example.com will be unable to distinguish these cookies 1422 from cookies that it set itself in an HTTPS response. An active 1423 network attacker might be able to leverage this ability to mount an 1424 attack against example.com even if example.com uses HTTPS 1425 exclusively. 1427 Servers can partially mitigate these attacks by encrypting and 1428 signing the contents of their cookies. However, using cryptography 1429 does not mitigate the issue completely because an attacker can replay 1430 a cookie he or she received from the authentic example.com server in 1431 the user's session, with unpredictable results. 1433 Finally, an attacker might be able to force the user agent to delete 1434 cookies by storing a large number of cookies. Once the user agent 1435 reaches its storage limit, the user agent will be forced to evict 1436 some cookies. Servers SHOULD NOT rely upon user agents retaining 1437 cookies. 1439 8.7. Reliance on DNS 1441 Cookies rely upon the Domain Name System (DNS) for security. If the 1442 DNS is partially or fully compromised, the cookie protocol might fail 1443 to provide the security properties required by applications. 1445 9. IANA Considerations 1447 The permanent message header field registry (see [RFC3864]) has been 1448 updated with the following registrations. 1450 9.1. Cookie 1452 Header field name: Cookie 1453 Applicable protocol: http 1454 Status: standard 1455 Author/Change controller: IETF 1456 Specification document: this specification (Section 5.4) 1458 9.2. Set-Cookie 1460 Header field name: Set-Cookie 1461 Applicable protocol: http 1462 Status: standard 1463 Author/Change controller: IETF 1464 Specification document: this specification (Section 5.2) 1466 9.3. Cookie2 1468 Header field name: Cookie2 1469 Applicable protocol: http 1470 Status: obsoleted 1471 Author/Change controller: IETF 1472 Specification document: [RFC2965] 1474 9.4. Set-Cookie2 1476 Header field name: Set-Cookie2 1477 Applicable protocol: http 1478 Status: obsoleted 1479 Author/Change controller: IETF 1480 Specification document: [RFC2965] 1482 10. References 1484 10.1. Normative References 1486 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 1487 STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987, 1488 . 1490 [RFC1123] Braden, R., Ed., "Requirements for Internet Hosts - 1491 Application and Support", STD 3, RFC 1123, 1492 DOI 10.17487/RFC1123, October 1989, 1493 . 1495 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1496 Requirement Levels", BCP 14, RFC 2119, 1497 DOI 10.17487/RFC2119, March 1997, 1498 . 1500 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1501 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1502 Transfer Protocol -- HTTP/1.1", RFC 2616, 1503 DOI 10.17487/RFC2616, June 1999, 1504 . 1506 [RFC3490] Faltstrom, P., Hoffman, P., and A. Costello, 1507 "Internationalizing Domain Names in Applications (IDNA)", 1508 RFC 3490, DOI 10.17487/RFC3490, March 2003, 1509 . 1511 [RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet 1512 Application Protocol Collation Registry", RFC 4790, 1513 DOI 10.17487/RFC4790, March 2007, 1514 . 1516 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1517 Specifications: ABNF", STD 68, RFC 5234, 1518 DOI 10.17487/RFC5234, January 2008, 1519 . 1521 [RFC5890] Klensin, J., "Internationalized Domain Names for 1522 Applications (IDNA): Definitions and Document Framework", 1523 RFC 5890, DOI 10.17487/RFC5890, August 2010, 1524 . 1526 [USASCII] "Coded Character Set -- 7-bit American Standard Code for 1527 Information Interchange", 1986, . 1529 10.2. Informative References 1531 [Aggarwal2010] 1532 Aggarwal, G., Burzstein, E., Jackson, C., and D. Boneh, 1533 "An Analysis of Private Browsing Modes in Modern 1534 Browsers", 2010, 1535 . 1538 [CSRF] Barth, A., Jackson, C., and J. Mitchell, "Robust Defenses 1539 for Cross-Site Request Forgery", 2008, 1540 . 1542 [Kri2001] Kristol, D., "HTTP Cookies: Standards, Privacy, and 1543 Politics", ACM ACM Transactions on Internet Technology 1544 Vol. 1, #2, November 2001, 1545 . 1547 [Netscape] 1548 "Persistent Client State -- HTTP Cookies", 1999, . 1552 [RFC2109] Kristol, D. and L. Montulli, "HTTP State Management 1553 Mechanism", RFC 2109, DOI 10.17487/RFC2109, February 1997, 1554 . 1556 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 1557 DOI 10.17487/RFC2818, May 2000, 1558 . 1560 [RFC2965] Kristol, D. and L. Montulli, "HTTP State Management 1561 Mechanism", RFC 2965, DOI 10.17487/RFC2965, October 2000, 1562 . 1564 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1565 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 1566 2003, . 1568 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1569 Procedures for Message Header Fields", BCP 90, RFC 3864, 1570 DOI 10.17487/RFC3864, September 2004, 1571 . 1573 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1574 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1575 . 1577 [RFC5895] Resnick, P. and P. Hoffman, "Mapping Characters for 1578 Internationalized Domain Names in Applications (IDNA) 1579 2008", RFC 5895, DOI 10.17487/RFC5895, September 2010, 1580 . 1582 [UTS46] Davis, M. and M. Suignard, "Unicode IDNA Compatibility 1583 Processing", UNICODE Unicode Technical Standards # 46, 1584 2010, . 1586 Appendix A. Acknowledgements 1588 This document is a minor update of RFC 6265, adding small features, 1589 and aligning the specification with the reality of today's 1590 deployments. Here, we're standing upon the shoulders of giants. 1592 Authors' Addresses 1594 Adam Barth 1595 Google, Inc 1597 URI: https://www.adambarth.com/ 1599 Mike West 1600 Google, Inc 1602 Email: mkwst@google.com 1603 URI: https://mikewest.org/