idnits 2.17.1 draft-ietf-httpbis-rfc6265bis-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([2], [3], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (April 27, 2019) is 1824 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) -- Looks like a reference, but probably isn't: '1' on line 2184 -- Looks like a reference, but probably isn't: '2' on line 2186 -- Looks like a reference, but probably isn't: '3' on line 2188 -- Looks like a reference, but probably isn't: '4' on line 2190 -- Looks like a reference, but probably isn't: '5' on line 2229 -- Looks like a reference, but probably isn't: '6' on line 2231 -- Looks like a reference, but probably isn't: '7' on line 2236 -- Looks like a reference, but probably isn't: '8' on line 2239 -- Looks like a reference, but probably isn't: '9' on line 2259 -- Looks like a reference, but probably isn't: '10' on line 2262 -- Looks like a reference, but probably isn't: '11' on line 2266 -- Looks like a reference, but probably isn't: '12' on line 2270 -- Looks like a reference, but probably isn't: '13' on line 2274 -- Looks like a reference, but probably isn't: '14' on line 2278 -- Looks like a reference, but probably isn't: '15' on line 2283 -- Looks like a reference, but probably isn't: '16' on line 2287 -- Looks like a reference, but probably isn't: '17' on line 2290 -- Possible downref: Non-RFC (?) normative reference: ref. 'FETCH' -- Possible downref: Non-RFC (?) normative reference: ref. 'HTML' -- Possible downref: Non-RFC (?) normative reference: ref. 'PSL' ** Obsolete normative reference: RFC 3490 (Obsoleted by RFC 5890, RFC 5891) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) -- Possible downref: Non-RFC (?) normative reference: ref. 'SERVICE-WORKERS' -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 24 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 Obsoletes: 6265 (if approved) Google, Inc 5 Intended status: Standards Track April 27, 2019 6 Expires: October 29, 2019 8 Cookies: HTTP State Management Mechanism 9 draft-ietf-httpbis-rfc6265bis-03 11 Abstract 13 This document defines the HTTP Cookie and Set-Cookie header fields. 14 These header fields can be used by HTTP servers to store state 15 (called cookies) at HTTP user agents, letting the servers maintain a 16 stateful session over the mostly stateless HTTP protocol. Although 17 cookies have many historical infelicities that degrade their security 18 and privacy, the Cookie and Set-Cookie header fields are widely used 19 on the Internet. This document obsoletes RFC 6265. 21 Note to Readers 23 Discussion of this draft takes place on the HTTP working group 24 mailing list (ietf-http-wg@w3.org), which is archived at 25 https://lists.w3.org/Archives/Public/ietf-http-wg/ [1]. 27 Working Group information can be found at http://httpwg.github.io/ 28 [2]; source code and issues list for this draft can be found at 29 https://github.com/httpwg/http-extensions/labels/6265bis [3]. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at https://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on October 29, 2019. 48 Copyright Notice 50 Copyright (c) 2019 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (https://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 This document may contain material from IETF Documents or IETF 64 Contributions published or made publicly available before November 65 10, 2008. The person(s) controlling the copyright in some of this 66 material may not have granted the IETF Trust the right to allow 67 modifications of such material outside the IETF Standards Process. 68 Without obtaining an adequate license from the person(s) controlling 69 the copyright in such materials, this document may not be modified 70 outside the IETF Standards Process, and derivative works of it may 71 not be created outside the IETF Standards Process, except to format 72 it for publication as an RFC or to translate it into languages other 73 than English. 75 Table of Contents 77 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 78 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 5 79 2.1. Conformance Criteria . . . . . . . . . . . . . . . . . . 5 80 2.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 5 81 2.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 82 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 7 83 3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 7 84 4. Server Requirements . . . . . . . . . . . . . . . . . . . . . 9 85 4.1. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . 9 86 4.1.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . 9 87 4.1.2. Semantics (Non-Normative) . . . . . . . . . . . . . . 11 88 4.1.3. Cookie Name Prefixes . . . . . . . . . . . . . . . . 14 89 4.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . 15 90 4.2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . 15 91 4.2.2. Semantics . . . . . . . . . . . . . . . . . . . . . . 16 92 5. User Agent Requirements . . . . . . . . . . . . . . . . . . . 16 93 5.1. Subcomponent Algorithms . . . . . . . . . . . . . . . . . 16 94 5.1.1. Dates . . . . . . . . . . . . . . . . . . . . . . . . 17 95 5.1.2. Canonicalized Host Names . . . . . . . . . . . . . . 18 96 5.1.3. Domain Matching . . . . . . . . . . . . . . . . . . . 19 97 5.1.4. Paths and Path-Match . . . . . . . . . . . . . . . . 19 98 5.2. "Same-site" and "cross-site" Requests . . . . . . . . . . 20 99 5.2.1. Document-based requests . . . . . . . . . . . . . . . 21 100 5.2.2. Worker-based requests . . . . . . . . . . . . . . . . 22 101 5.3. The Set-Cookie Header . . . . . . . . . . . . . . . . . . 23 102 5.3.1. The Expires Attribute . . . . . . . . . . . . . . . . 25 103 5.3.2. The Max-Age Attribute . . . . . . . . . . . . . . . . 26 104 5.3.3. The Domain Attribute . . . . . . . . . . . . . . . . 26 105 5.3.4. The Path Attribute . . . . . . . . . . . . . . . . . 27 106 5.3.5. The Secure Attribute . . . . . . . . . . . . . . . . 27 107 5.3.6. The HttpOnly Attribute . . . . . . . . . . . . . . . 27 108 5.3.7. The SameSite Attribute . . . . . . . . . . . . . . . 27 109 5.4. Storage Model . . . . . . . . . . . . . . . . . . . . . . 28 110 5.5. The Cookie Header . . . . . . . . . . . . . . . . . . . . 33 111 6. Implementation Considerations . . . . . . . . . . . . . . . . 35 112 6.1. Limits . . . . . . . . . . . . . . . . . . . . . . . . . 35 113 6.2. Application Programming Interfaces . . . . . . . . . . . 35 114 6.3. IDNA Dependency and Migration . . . . . . . . . . . . . . 36 115 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 36 116 7.1. Third-Party Cookies . . . . . . . . . . . . . . . . . . . 36 117 7.2. User Controls . . . . . . . . . . . . . . . . . . . . . . 37 118 7.3. Expiration Dates . . . . . . . . . . . . . . . . . . . . 37 119 8. Security Considerations . . . . . . . . . . . . . . . . . . . 38 120 8.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 38 121 8.2. Ambient Authority . . . . . . . . . . . . . . . . . . . . 38 122 8.3. Clear Text . . . . . . . . . . . . . . . . . . . . . . . 39 123 8.4. Session Identifiers . . . . . . . . . . . . . . . . . . . 40 124 8.5. Weak Confidentiality . . . . . . . . . . . . . . . . . . 40 125 8.6. Weak Integrity . . . . . . . . . . . . . . . . . . . . . 41 126 8.7. Reliance on DNS . . . . . . . . . . . . . . . . . . . . . 42 127 8.8. SameSite Cookies . . . . . . . . . . . . . . . . . . . . 42 128 8.8.1. Defense in depth . . . . . . . . . . . . . . . . . . 42 129 8.8.2. Top-level Navigations . . . . . . . . . . . . . . . . 42 130 8.8.3. Mashups and Widgets . . . . . . . . . . . . . . . . . 43 131 8.8.4. Server-controlled . . . . . . . . . . . . . . . . . . 43 132 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43 133 9.1. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . 43 134 9.2. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . 44 135 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 44 136 10.1. Normative References . . . . . . . . . . . . . . . . . . 44 137 10.2. Informative References . . . . . . . . . . . . . . . . . 45 138 10.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 47 139 Appendix A. Changes . . . . . . . . . . . . . . . . . . . . . . 48 140 A.1. draft-ietf-httpbis-rfc6265bis-00 . . . . . . . . . . . . 48 141 A.2. draft-ietf-httpbis-rfc6265bis-01 . . . . . . . . . . . . 48 142 A.3. draft-ietf-httpbis-rfc6265bis-02 . . . . . . . . . . . . 49 143 A.4. draft-ietf-httpbis-rfc6265bis-03 . . . . . . . . . . . . 49 145 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 49 146 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 50 148 1. Introduction 150 This document defines the HTTP Cookie and Set-Cookie header fields. 151 Using the Set-Cookie header field, an HTTP server can pass name/value 152 pairs and associated metadata (called cookies) to a user agent. When 153 the user agent makes subsequent requests to the server, the user 154 agent uses the metadata and other information to determine whether to 155 return the name/value pairs in the Cookie header. 157 Although simple on their surface, cookies have a number of 158 complexities. For example, the server indicates a scope for each 159 cookie when sending it to the user agent. The scope indicates the 160 maximum amount of time in which the user agent should return the 161 cookie, the servers to which the user agent should return the cookie, 162 and the URI schemes for which the cookie is applicable. 164 For historical reasons, cookies contain a number of security and 165 privacy infelicities. For example, a server can indicate that a 166 given cookie is intended for "secure" connections, but the Secure 167 attribute does not provide integrity in the presence of an active 168 network attacker. Similarly, cookies for a given host are shared 169 across all the ports on that host, even though the usual "same-origin 170 policy" used by web browsers isolates content retrieved via different 171 ports. 173 There are two audiences for this specification: developers of cookie- 174 generating servers and developers of cookie-consuming user agents. 176 To maximize interoperability with user agents, servers SHOULD limit 177 themselves to the well-behaved profile defined in Section 4 when 178 generating cookies. 180 User agents MUST implement the more liberal processing rules defined 181 in Section 5, in order to maximize interoperability with existing 182 servers that do not conform to the well-behaved profile defined in 183 Section 4. 185 This document specifies the syntax and semantics of these headers as 186 they are actually used on the Internet. In particular, this document 187 does not create new syntax or semantics beyond those in use today. 188 The recommendations for cookie generation provided in Section 4 189 represent a preferred subset of current server behavior, and even the 190 more liberal cookie processing algorithm provided in Section 5 does 191 not recommend all of the syntactic and semantic variations in use 192 today. Where some existing software differs from the recommended 193 protocol in significant ways, the document contains a note explaining 194 the difference. 196 This document obsoletes [RFC6265]. 198 2. Conventions 200 2.1. Conformance Criteria 202 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 203 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 204 document are to be interpreted as described in [RFC2119]. 206 Requirements phrased in the imperative as part of algorithms (such as 207 "strip any leading space characters" or "return false and abort these 208 steps") are to be interpreted with the meaning of the key word 209 ("MUST", "SHOULD", "MAY", etc.) used in introducing the algorithm. 211 Conformance requirements phrased as algorithms or specific steps can 212 be implemented in any manner, so long as the end result is 213 equivalent. In particular, the algorithms defined in this 214 specification are intended to be easy to understand and are not 215 intended to be performant. 217 2.2. Syntax Notation 219 This specification uses the Augmented Backus-Naur Form (ABNF) 220 notation of [RFC5234]. 222 The following core rules are included by reference, as defined in 223 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 224 (CR LF), CTLs (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 225 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), NUL (null octet), 226 OCTET (any 8-bit sequence of data except NUL), SP (space), HTAB 227 (horizontal tab), CHAR (any [USASCII] character), VCHAR (any visible 228 [USASCII] character), and WSP (whitespace). 230 The OWS (optional whitespace) rule is used where zero or more linear 231 whitespace characters MAY appear: 233 OWS = *( [ obs-fold ] WSP ) 234 ; "optional" whitespace 235 obs-fold = CRLF 237 OWS SHOULD either not be produced or be produced as a single SP 238 character. 240 2.3. Terminology 242 The terms "user agent", "client", "server", "proxy", and "origin 243 server" have the same meaning as in the HTTP/1.1 specification 244 ([RFC7230], Section 2). 246 The request-host is the name of the host, as known by the user agent, 247 to which the user agent is sending an HTTP request or from which it 248 is receiving an HTTP response (i.e., the name of the host to which it 249 sent the corresponding HTTP request). 251 The term request-uri refers to "request-target" as defined in 252 Section 5.3 of [RFC7230]. 254 Two sequences of octets are said to case-insensitively match each 255 other if and only if they are equivalent under the i;ascii-casemap 256 collation defined in [RFC4790]. 258 The term string means a sequence of non-NUL octets. 260 The terms "active document", "ancestor browsing context", "browsing 261 context", "dedicated worker", "Document", "WorkerGlobalScope", 262 "sandboxed origin browsing context flag", "parent browsing context", 263 "shared worker", "the worker's Documents", "nested browsing context", 264 and "top-level browsing context" are defined in [HTML]. 266 "Service Workers" are defined in the Service Workers specification 267 [SERVICE-WORKERS]. 269 The term "origin", the mechanism of deriving an origin from a URI, 270 and the "the same" matching algorithm for origins are defined in 271 [RFC6454]. 273 "Safe" HTTP methods include "GET", "HEAD", "OPTIONS", and "TRACE", as 274 defined in Section 4.2.1 of [RFC7231]. 276 The term "public suffix" is defined in a note in Section 5.3 of 277 [RFC6265] as "a domain that is controlled by a public registry", and 278 are also known as "effective top-level domains" (eTLDs). For 279 example, "example.com"'s public suffix is "com". User agents SHOULD 280 use an up-to-date public suffix list, such as the one maintained by 281 Mozilla at [PSL]. 283 An origin's "registered domain" is the origin's host's public suffix 284 plus the label to its left. That is, for "https://www.example.com", 285 the public suffix is "com", and the registered domain is 286 "example.com". This concept is defined more rigorously in [PSL], and 287 is also known as "effective top-level domain plus one" (eTLD+1). 289 The term "request", as well as a request's "client", "current url", 290 "method", and "target browsing context", are defined in [FETCH]. 292 3. Overview 294 This section outlines a way for an origin server to send state 295 information to a user agent and for the user agent to return the 296 state information to the origin server. 298 To store state, the origin server includes a Set-Cookie header in an 299 HTTP response. In subsequent requests, the user agent returns a 300 Cookie request header to the origin server. The Cookie header 301 contains cookies the user agent received in previous Set-Cookie 302 headers. The origin server is free to ignore the Cookie header or 303 use its contents for an application-defined purpose. 305 Origin servers MAY send a Set-Cookie response header with any 306 response. User agents MAY ignore Set-Cookie headers contained in 307 responses with 100-level status codes but MUST process Set-Cookie 308 headers contained in other responses (including responses with 400- 309 and 500-level status codes). An origin server can include multiple 310 Set-Cookie header fields in a single response. The presence of a 311 Cookie or a Set-Cookie header field does not preclude HTTP caches 312 from storing and reusing a response. 314 Origin servers SHOULD NOT fold multiple Set-Cookie header fields into 315 a single header field. The usual mechanism for folding HTTP headers 316 fields (i.e., as defined in Section 3.2.2 of [RFC7230]) might change 317 the semantics of the Set-Cookie header field because the %x2C (",") 318 character is used by Set-Cookie in a way that conflicts with such 319 folding. 321 3.1. Examples 323 Using the Set-Cookie header, a server can send the user agent a short 324 string in an HTTP response that the user agent will return in future 325 HTTP requests that are within the scope of the cookie. For example, 326 the server can send the user agent a "session identifier" named SID 327 with the value 31d4d96e407aad42. The user agent then returns the 328 session identifier in subsequent requests. 330 == Server -> User Agent == 332 Set-Cookie: SID=31d4d96e407aad42 334 == User Agent -> Server == 336 Cookie: SID=31d4d96e407aad42 337 The server can alter the default scope of the cookie using the Path 338 and Domain attributes. For example, the server can instruct the user 339 agent to return the cookie to every path and every subdomain of 340 example.com. 342 == Server -> User Agent == 344 Set-Cookie: SID=31d4d96e407aad42; Path=/; Domain=example.com 346 == User Agent -> Server == 348 Cookie: SID=31d4d96e407aad42 350 As shown in the next example, the server can store multiple cookies 351 at the user agent. For example, the server can store a session 352 identifier as well as the user's preferred language by returning two 353 Set-Cookie header fields. Notice that the server uses the Secure and 354 HttpOnly attributes to provide additional security protections for 355 the more sensitive session identifier (see Section 4.1.2). 357 == Server -> User Agent == 359 Set-Cookie: SID=31d4d96e407aad42; Path=/; Secure; HttpOnly 360 Set-Cookie: lang=en-US; Path=/; Domain=example.com 362 == User Agent -> Server == 364 Cookie: SID=31d4d96e407aad42; lang=en-US 366 Notice that the Cookie header above contains two cookies, one named 367 SID and one named lang. If the server wishes the user agent to 368 persist the cookie over multiple "sessions" (e.g., user agent 369 restarts), the server can specify an expiration date in the Expires 370 attribute. Note that the user agent might delete the cookie before 371 the expiration date if the user agent's cookie store exceeds its 372 quota or if the user manually deletes the server's cookie. 374 == Server -> User Agent == 376 Set-Cookie: lang=en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT 378 == User Agent -> Server == 380 Cookie: SID=31d4d96e407aad42; lang=en-US 382 Finally, to remove a cookie, the server returns a Set-Cookie header 383 with an expiration date in the past. The server will be successful 384 in removing the cookie only if the Path and the Domain attribute in 385 the Set-Cookie header match the values used when the cookie was 386 created. 388 == Server -> User Agent == 390 Set-Cookie: lang=; Expires=Sun, 06 Nov 1994 08:49:37 GMT 392 == User Agent -> Server == 394 Cookie: SID=31d4d96e407aad42 396 4. Server Requirements 398 This section describes the syntax and semantics of a well-behaved 399 profile of the Cookie and Set-Cookie headers. 401 4.1. Set-Cookie 403 The Set-Cookie HTTP response header is used to send cookies from the 404 server to the user agent. 406 4.1.1. Syntax 408 Informally, the Set-Cookie response header contains the header name 409 "Set-Cookie" followed by a ":" and a cookie. Each cookie begins with 410 a name-value-pair, followed by zero or more attribute-value pairs. 411 Servers SHOULD NOT send Set-Cookie headers that fail to conform to 412 the following grammar: 414 set-cookie-header = "Set-Cookie:" SP set-cookie-string 415 set-cookie-string = cookie-pair *( ";" SP cookie-av ) 416 cookie-pair = cookie-name "=" cookie-value 417 cookie-name = token 418 cookie-value = *cookie-octet / ( DQUOTE *cookie-octet DQUOTE ) 419 cookie-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E 420 ; US-ASCII characters excluding CTLs, 421 ; whitespace DQUOTE, comma, semicolon, 422 ; and backslash 423 token = 425 cookie-av = expires-av / max-age-av / domain-av / 426 path-av / secure-av / httponly-av / 427 samesite-av / extension-av 428 expires-av = "Expires=" sane-cookie-date 429 sane-cookie-date = 430 431 max-age-av = "Max-Age=" non-zero-digit *DIGIT 432 ; In practice, both expires-av and max-age-av 433 ; are limited to dates representable by the 434 ; user agent. 435 non-zero-digit = %x31-39 436 ; digits 1 through 9 437 domain-av = "Domain=" domain-value 438 domain-value = 439 ; defined in [RFC1034], Section 3.5, as 440 ; enhanced by [RFC1123], Section 2.1 441 path-av = "Path=" path-value 442 path-value = *av-octet 443 secure-av = "Secure" 444 httponly-av = "HttpOnly" 445 samesite-av = "SameSite=" samesite-value 446 samesite-value = "Strict" / "Lax" / "None" 447 extension-av = *av-octet 448 av-octet = %x20-3A / %x3C-7E 449 ; any CHAR except CTLs or ";" 451 Note that some of the grammatical terms above reference documents 452 that use different grammatical notations than this document (which 453 uses ABNF from [RFC5234]). 455 The semantics of the cookie-value are not defined by this document. 457 To maximize compatibility with user agents, servers that wish to 458 store arbitrary data in a cookie-value SHOULD encode that data, for 459 example, using Base64 [RFC4648]. 461 Per the grammar above, the cookie-value MAY be wrapped in DQUOTE 462 characters. Note that in this case, the initial and trailing DQUOTE 463 characters are not stripped. They are part of the cookie-value, and 464 will be included in Cookie headers sent to the server. 466 The portions of the set-cookie-string produced by the cookie-av term 467 are known as attributes. To maximize compatibility with user agents, 468 servers SHOULD NOT produce two attributes with the same name in the 469 same set-cookie-string. (See Section 5.4 for how user agents handle 470 this case.) 472 Servers SHOULD NOT include more than one Set-Cookie header field in 473 the same response with the same cookie-name. (See Section 5.3 for 474 how user agents handle this case.) 476 If a server sends multiple responses containing Set-Cookie headers 477 concurrently to the user agent (e.g., when communicating with the 478 user agent over multiple sockets), these responses create a "race 479 condition" that can lead to unpredictable behavior. 481 NOTE: Some existing user agents differ in their interpretation of 482 two-digit years. To avoid compatibility issues, servers SHOULD use 483 the rfc1123-date format, which requires a four-digit year. 485 NOTE: Some user agents store and process dates in cookies as 32-bit 486 UNIX time_t values. Implementation bugs in the libraries supporting 487 time_t processing on some systems might cause such user agents to 488 process dates after the year 2038 incorrectly. 490 4.1.2. Semantics (Non-Normative) 492 This section describes simplified semantics of the Set-Cookie header. 493 These semantics are detailed enough to be useful for understanding 494 the most common uses of cookies by servers. The full semantics are 495 described in Section 5. 497 When the user agent receives a Set-Cookie header, the user agent 498 stores the cookie together with its attributes. Subsequently, when 499 the user agent makes an HTTP request, the user agent includes the 500 applicable, non-expired cookies in the Cookie header. 502 If the user agent receives a new cookie with the same cookie-name, 503 domain-value, and path-value as a cookie that it has already stored, 504 the existing cookie is evicted and replaced with the new cookie. 505 Notice that servers can delete cookies by sending the user agent a 506 new cookie with an Expires attribute with a value in the past. 508 Unless the cookie's attributes indicate otherwise, the cookie is 509 returned only to the origin server (and not, for example, to any 510 subdomains), and it expires at the end of the current session (as 511 defined by the user agent). User agents ignore unrecognized cookie 512 attributes (but not the entire cookie). 514 4.1.2.1. The Expires Attribute 516 The Expires attribute indicates the maximum lifetime of the cookie, 517 represented as the date and time at which the cookie expires. The 518 user agent is not required to retain the cookie until the specified 519 date has passed. In fact, user agents often evict cookies due to 520 memory pressure or privacy concerns. 522 4.1.2.2. The Max-Age Attribute 524 The Max-Age attribute indicates the maximum lifetime of the cookie, 525 represented as the number of seconds until the cookie expires. The 526 user agent is not required to retain the cookie for the specified 527 duration. In fact, user agents often evict cookies due to memory 528 pressure or privacy concerns. 530 NOTE: Some existing user agents do not support the Max-Age attribute. 531 User agents that do not support the Max-Age attribute ignore the 532 attribute. 534 If a cookie has both the Max-Age and the Expires attribute, the Max- 535 Age attribute has precedence and controls the expiration date of the 536 cookie. If a cookie has neither the Max-Age nor the Expires 537 attribute, the user agent will retain the cookie until "the current 538 session is over" (as defined by the user agent). 540 4.1.2.3. The Domain Attribute 542 The Domain attribute specifies those hosts to which the cookie will 543 be sent. For example, if the value of the Domain attribute is 544 "example.com", the user agent will include the cookie in the Cookie 545 header when making HTTP requests to example.com, www.example.com, and 546 www.corp.example.com. (Note that a leading %x2E ("."), if present, 547 is ignored even though that character is not permitted, but a 548 trailing %x2E ("."), if present, will cause the user agent to ignore 549 the attribute.) If the server omits the Domain attribute, the user 550 agent will return the cookie only to the origin server. 552 WARNING: Some existing user agents treat an absent Domain attribute 553 as if the Domain attribute were present and contained the current 554 host name. For example, if example.com returns a Set-Cookie header 555 without a Domain attribute, these user agents will erroneously send 556 the cookie to www.example.com as well. 558 The user agent will reject cookies unless the Domain attribute 559 specifies a scope for the cookie that would include the origin 560 server. For example, the user agent will accept a cookie with a 561 Domain attribute of "example.com" or of "foo.example.com" from 562 foo.example.com, but the user agent will not accept a cookie with a 563 Domain attribute of "bar.example.com" or of "baz.foo.example.com". 565 NOTE: For security reasons, many user agents are configured to reject 566 Domain attributes that correspond to "public suffixes". For example, 567 some user agents will reject Domain attributes of "com" or "co.uk". 568 (See Section 5.4 for more information.) 570 4.1.2.4. The Path Attribute 572 The scope of each cookie is limited to a set of paths, controlled by 573 the Path attribute. If the server omits the Path attribute, the user 574 agent will use the "directory" of the request-uri's path component as 575 the default value. (See Section 5.1.4 for more details.) 577 The user agent will include the cookie in an HTTP request only if the 578 path portion of the request-uri matches (or is a subdirectory of) the 579 cookie's Path attribute, where the %x2F ("/") character is 580 interpreted as a directory separator. 582 Although seemingly useful for isolating cookies between different 583 paths within a given host, the Path attribute cannot be relied upon 584 for security (see Section 8). 586 4.1.2.5. The Secure Attribute 588 The Secure attribute limits the scope of the cookie to "secure" 589 channels (where "secure" is defined by the user agent). When a 590 cookie has the Secure attribute, the user agent will include the 591 cookie in an HTTP request only if the request is transmitted over a 592 secure channel (typically HTTP over Transport Layer Security (TLS) 593 [RFC2818]). 595 Although seemingly useful for protecting cookies from active network 596 attackers, the Secure attribute protects only the cookie's 597 confidentiality. An active network attacker can overwrite Secure 598 cookies from an insecure channel, disrupting their integrity (see 599 Section 8.6 for more details). 601 4.1.2.6. The HttpOnly Attribute 603 The HttpOnly attribute limits the scope of the cookie to HTTP 604 requests. In particular, the attribute instructs the user agent to 605 omit the cookie when providing access to cookies via "non-HTTP" APIs 606 (such as a web browser API that exposes cookies to scripts). 608 Note that the HttpOnly attribute is independent of the Secure 609 attribute: a cookie can have both the HttpOnly and the Secure 610 attribute. 612 4.1.2.7. The SameSite Attribute 614 The "SameSite" attribute limits the scope of the cookie such that it 615 will only be attached to requests if those requests are same-site, as 616 defined by the algorithm in Section 5.2. For example, requests for 617 "https://example.com/sekrit-image" will attach same-site cookies if 618 and only if initiated from a context whose "site for cookies" is 619 "example.com". 621 If the "SameSite" attribute's value is "Strict", the cookie will only 622 be sent along with "same-site" requests. If the value is "Lax", the 623 cookie will be sent with same-site requests, and with "cross-site" 624 top-level navigations, as described in Section 5.3.7.1. If the value 625 is "None", the cookie will be sent with same-site and cross-site 626 requests. If the "SameSite" attribute's value is something other 627 than these three known keywords, the attribute's value will be 628 treated as "None". 630 4.1.3. Cookie Name Prefixes 632 Section 8.5 and Section 8.6 of this document spell out some of the 633 drawbacks of cookies' historical implementation. In particular, it 634 is impossible for a server to have confidence that a given cookie was 635 set with a particular set of attributes. In order to provide such 636 confidence in a backwards-compatible way, two common sets of 637 requirements can be inferred from the first few characters of the 638 cookie's name. 640 The normative requirements for the prefixes described below are 641 detailed in the storage model algorithm defined in Section 5.4. 643 4.1.3.1. The "__Secure-" Prefix 645 If a cookie's name begins with a case-sensitive match for the string 646 "__Secure-", then the cookie will have been set with a "Secure" 647 attribute. 649 For example, the following "Set-Cookie" header would be rejected by a 650 conformant user agent, as it does not have a "Secure" attribute. 652 Set-Cookie: __Secure-SID=12345; Domain=example.com 654 Whereas the following "Set-Cookie" header would be accepted: 656 Set-Cookie: __Secure-SID=12345; Domain=example.com; Secure 658 4.1.3.2. The "__Host-" Prefix 660 If a cookie's name begins with a case-sensitive match for the string 661 "__Host-", then the cookie will have been set with a "Secure" 662 attribute, a "Path" attribute with a value of "/", and no "Domain" 663 attribute. 665 This combination yields a cookie that hews as closely as a cookie can 666 to treating the origin as a security boundary. The lack of a 667 "Domain" attribute ensures that the cookie's "host-only-flag" is 668 true, locking the cookie to a particular host, rather than allowing 669 it to span subdomains. Setting the "Path" to "/" means that the 670 cookie is effective for the entire host, and won't be overridden for 671 specific paths. The "Secure" attribute ensures that the cookie is 672 unaltered by non-secure origins, and won't span protocols. 674 Ports are the only piece of the origin model that "__Host-" cookies 675 continue to ignore. 677 For example, the following cookies would always be rejected: 679 Set-Cookie: __Host-SID=12345 680 Set-Cookie: __Host-SID=12345; Secure 681 Set-Cookie: __Host-SID=12345; Domain=example.com 682 Set-Cookie: __Host-SID=12345; Domain=example.com; Path=/ 683 Set-Cookie: __Host-SID=12345; Secure; Domain=example.com; Path=/ 685 While the would be accepted if set from a secure origin (e.g. 686 "https://example.com/"), and rejected otherwise: 688 Set-Cookie: __Host-SID=12345; Secure; Path=/ 690 4.2. Cookie 692 4.2.1. Syntax 694 The user agent sends stored cookies to the origin server in the 695 Cookie header. If the server conforms to the requirements in 696 Section 4.1 (and the user agent conforms to the requirements in 697 Section 5), the user agent will send a Cookie header that conforms to 698 the following grammar: 700 cookie-header = "Cookie:" OWS cookie-string OWS 701 cookie-string = cookie-pair *( ";" SP cookie-pair ) 703 4.2.2. Semantics 705 Each cookie-pair represents a cookie stored by the user agent. The 706 cookie-pair contains the cookie-name and cookie-value the user agent 707 received in the Set-Cookie header. 709 Notice that the cookie attributes are not returned. In particular, 710 the server cannot determine from the Cookie header alone when a 711 cookie will expire, for which hosts the cookie is valid, for which 712 paths the cookie is valid, or whether the cookie was set with the 713 Secure or HttpOnly attributes. 715 The semantics of individual cookies in the Cookie header are not 716 defined by this document. Servers are expected to imbue these 717 cookies with application-specific semantics. 719 Although cookies are serialized linearly in the Cookie header, 720 servers SHOULD NOT rely upon the serialization order. In particular, 721 if the Cookie header contains two cookies with the same name (e.g., 722 that were set with different Path or Domain attributes), servers 723 SHOULD NOT rely upon the order in which these cookies appear in the 724 header. 726 5. User Agent Requirements 728 This section specifies the Cookie and Set-Cookie headers in 729 sufficient detail that a user agent implementing these requirements 730 precisely can interoperate with existing servers (even those that do 731 not conform to the well-behaved profile described in Section 4). 733 A user agent could enforce more restrictions than those specified 734 herein (e.g., for the sake of improved security); however, 735 experiments have shown that such strictness reduces the likelihood 736 that a user agent will be able to interoperate with existing servers. 738 5.1. Subcomponent Algorithms 740 This section defines some algorithms used by user agents to process 741 specific subcomponents of the Cookie and Set-Cookie headers. 743 5.1.1. Dates 745 The user agent MUST use an algorithm equivalent to the following 746 algorithm to parse a cookie-date. Note that the various boolean 747 flags defined as a part of the algorithm (i.e., found-time, found- 748 day-of-month, found-month, found-year) are initially "not set". 750 1. Using the grammar below, divide the cookie-date into date-tokens. 752 cookie-date = *delimiter date-token-list *delimiter 753 date-token-list = date-token *( 1*delimiter date-token ) 754 date-token = 1*non-delimiter 756 delimiter = %x09 / %x20-2F / %x3B-40 / %x5B-60 / %x7B-7E 757 non-delimiter = %x00-08 / %x0A-1F / DIGIT / ":" / ALPHA / %x7F-FF 758 non-digit = %x00-2F / %x3A-FF 760 day-of-month = 1*2DIGIT [ non-digit *OCTET ] 761 month = ( "jan" / "feb" / "mar" / "apr" / 762 "may" / "jun" / "jul" / "aug" / 763 "sep" / "oct" / "nov" / "dec" ) *OCTET 764 year = 2*4DIGIT [ non-digit *OCTET ] 765 time = hms-time [ non-digit *OCTET ] 766 hms-time = time-field ":" time-field ":" time-field 767 time-field = 1*2DIGIT 769 2. Process each date-token sequentially in the order the date-tokens 770 appear in the cookie-date: 772 1. If the found-time flag is not set and the token matches the 773 time production, set the found-time flag and set the hour- 774 value, minute-value, and second-value to the numbers denoted 775 by the digits in the date-token, respectively. Skip the 776 remaining sub-steps and continue to the next date-token. 778 2. If the found-day-of-month flag is not set and the date-token 779 matches the day-of-month production, set the found-day-of- 780 month flag and set the day-of-month-value to the number 781 denoted by the date-token. Skip the remaining sub-steps and 782 continue to the next date-token. 784 3. If the found-month flag is not set and the date-token matches 785 the month production, set the found-month flag and set the 786 month-value to the month denoted by the date-token. Skip the 787 remaining sub-steps and continue to the next date-token. 789 4. If the found-year flag is not set and the date-token matches 790 the year production, set the found-year flag and set the 791 year-value to the number denoted by the date-token. Skip the 792 remaining sub-steps and continue to the next date-token. 794 3. If the year-value is greater than or equal to 70 and less than or 795 equal to 99, increment the year-value by 1900. 797 4. If the year-value is greater than or equal to 0 and less than or 798 equal to 69, increment the year-value by 2000. 800 1. NOTE: Some existing user agents interpret two-digit years 801 differently. 803 5. Abort these steps and fail to parse the cookie-date if: 805 * at least one of the found-day-of-month, found-month, found- 806 year, or found-time flags is not set, 808 * the day-of-month-value is less than 1 or greater than 31, 810 * the year-value is less than 1601, 812 * the hour-value is greater than 23, 814 * the minute-value is greater than 59, or 816 * the second-value is greater than 59. 818 (Note that leap seconds cannot be represented in this syntax.) 820 6. Let the parsed-cookie-date be the date whose day-of-month, month, 821 year, hour, minute, and second (in UTC) are the day-of-month- 822 value, the month-value, the year-value, the hour-value, the 823 minute-value, and the second-value, respectively. If no such 824 date exists, abort these steps and fail to parse the cookie-date. 826 7. Return the parsed-cookie-date as the result of this algorithm. 828 5.1.2. Canonicalized Host Names 830 A canonicalized host name is the string generated by the following 831 algorithm: 833 1. Convert the host name to a sequence of individual domain name 834 labels. 836 2. Convert each label that is not a Non-Reserved LDH (NR-LDH) label, 837 to an A-label (see Section 2.3.2.1 of [RFC5890] for the former 838 and latter), or to a "punycode label" (a label resulting from the 839 "ToASCII" conversion in Section 4 of [RFC3490]), as appropriate 840 (see Section 6.3 of this specification). 842 3. Concatenate the resulting labels, separated by a %x2E (".") 843 character. 845 5.1.3. Domain Matching 847 A string domain-matches a given domain string if at least one of the 848 following conditions hold: 850 o The domain string and the string are identical. (Note that both 851 the domain string and the string will have been canonicalized to 852 lower case at this point.) 854 o All of the following conditions hold: 856 * The domain string is a suffix of the string. 858 * The last character of the string that is not included in the 859 domain string is a %x2E (".") character. 861 * The string is a host name (i.e., not an IP address). 863 5.1.4. Paths and Path-Match 865 The user agent MUST use an algorithm equivalent to the following 866 algorithm to compute the default-path of a cookie: 868 1. Let uri-path be the path portion of the request-uri if such a 869 portion exists (and empty otherwise). For example, if the 870 request-uri contains just a path (and optional query string), 871 then the uri-path is that path (without the %x3F ("?") character 872 or query string), and if the request-uri contains a full 873 absoluteURI, the uri-path is the path component of that URI. 875 2. If the uri-path is empty or if the first character of the uri- 876 path is not a %x2F ("/") character, output %x2F ("/") and skip 877 the remaining steps. 879 3. If the uri-path contains no more than one %x2F ("/") character, 880 output %x2F ("/") and skip the remaining step. 882 4. Output the characters of the uri-path from the first character up 883 to, but not including, the right-most %x2F ("/"). 885 A request-path path-matches a given cookie-path if at least one of 886 the following conditions holds: 888 o The cookie-path and the request-path are identical. 890 Note that this differs from the rules in [RFC3986] for equivalence 891 of the path component, and hence two equivalent paths can have 892 different cookies. 894 o The cookie-path is a prefix of the request-path, and the last 895 character of the cookie-path is %x2F ("/"). 897 o The cookie-path is a prefix of the request-path, and the first 898 character of the request-path that is not included in the cookie- 899 path is a %x2F ("/") character. 901 5.2. "Same-site" and "cross-site" Requests 903 A request is "same-site" if its target's URI's origin's registered 904 domain is an exact match for the request's client's "site for 905 cookies", or if the request has no client. The request is otherwise 906 "cross-site". 908 For a given request ("request"), the following algorithm returns 909 "same-site" or "cross-site": 911 1. If "request"'s client is "null", return "same-site". 913 Note that this is the case for navigation triggered by the user 914 directly (e.g. by typing directly into a user agent's address 915 bar). 917 2. Let "site" be "request"'s client's "site for cookies" (as defined 918 in the following sections). 920 3. Let "target" be the registered domain of "request"'s current url. 922 4. If "site" is an exact match for "target", return "same-site". 924 5. Return "cross-site". 926 The request's client's "site for cookies" is calculated depending 927 upon its client's type, as described in the following subsections: 929 5.2.1. Document-based requests 931 The URI displayed in a user agent's address bar is the only security 932 context directly exposed to users, and therefore the only signal 933 users can reasonably rely upon to determine whether or not they trust 934 a particular website. The registered domain of that URI's origin 935 represents the context in which a user most likely believes 936 themselves to be interacting. We'll label this domain the "top-level 937 site". 939 For a document displayed in a top-level browsing context, we can stop 940 here: the document's "site for cookies" is the top-level site. 942 For documents which are displayed in nested browsing contexts, we 943 need to audit the origins of each of a document's ancestor browsing 944 contexts' active documents in order to account for the "multiple- 945 nested scenarios" described in Section 4 of [RFC7034]. A document's 946 "site for cookies" is the top-level site if and only if the document 947 and each of its ancestor documents' origins have the same registered 948 domain as the top-level site. Otherwise its "site for cookies" is 949 the empty string. 951 Given a Document ("document"), the following algorithm returns its 952 "site for cookies" (either a registered domain, or the empty string): 954 1. Let "top-document" be the active document in "document"'s 955 browsing context's top-level browsing context. 957 2. Let "top-origin" be the origin of "top-document"'s URI if "top- 958 document"'s sandboxed origin browsing context flag is set, and 959 "top-document"'s origin otherwise. 961 3. Let "documents" be a list containing "document" and each of 962 "document"'s ancestor browsing contexts' active documents. 964 4. For each "item" in "documents": 966 1. Let "origin" be the origin of "item"'s URI if "item"'s 967 sandboxed origin browsing context flag is set, and "item"'s 968 origin otherwise. 970 2. If "origin"'s host's registered domain is not an exact match 971 for "top-origin"'s host's registered domain, return the empty 972 string. 974 5. Return "top-origin"'s host's registered domain. 976 5.2.2. Worker-based requests 978 Worker-driven requests aren't as clear-cut as document-driven 979 requests, as there isn't a clear link between a top-level browsing 980 context and a worker. This is especially true for Service Workers 981 [SERVICE-WORKERS], which may execute code in the background, without 982 any document visible at all. 984 Note: The descriptions below assume that workers must be same-origin 985 with the documents that instantiate them. If this invariant changes, 986 we'll need to take the worker's script's URI into account when 987 determining their status. 989 5.2.2.1. Dedicated and Shared Workers 991 Dedicated workers are simple, as each dedicated worker is bound to 992 one and only one document. Requests generated from a dedicated 993 worker (via "importScripts", "XMLHttpRequest", "fetch()", etc) define 994 their "site for cookies" as that document's "site for cookies". 996 Shared workers may be bound to multiple documents at once. As it is 997 quite possible for those documents to have distinct "site for cookie" 998 values, the worker's "site for cookies" will be the empty string in 999 cases where the values diverge, and the shared value in cases where 1000 the values agree. 1002 Given a WorkerGlobalScope ("worker"), the following algorithm returns 1003 its "site for cookies" (either a registered domain, or the empty 1004 string): 1006 1. Let "site" be "worker"'s origin's host's registered domain. 1008 2. For each "document" in "worker"'s Documents: 1010 1. Let "document-site" be "document"'s "site for cookies" (as 1011 defined in Section 5.2.1). 1013 2. If "document-site" is not an exact match for "site", return 1014 the empty string. 1016 3. Return "site". 1018 5.2.2.2. Service Workers 1020 Service Workers are more complicated, as they act as a completely 1021 separate execution context with only tangential relationship to the 1022 Document which registered them. 1024 Requests which simply pass through a Service Worker will be handled 1025 as described above: the request's client will be the Document or 1026 Worker which initiated the request, and its "site for cookies" will 1027 be those defined in Section 5.2.1 and Section 5.2.2.1 1029 Requests which are initiated by the Service Worker itself (via a 1030 direct call to "fetch()", for instance), on the other hand, will have 1031 a client which is a ServiceWorkerGlobalScope. Its "site for cookies" 1032 will be the registered domain of the Service Worker's URI. 1034 Given a ServiceWorkerGlobalScope ("worker"), the following algorithm 1035 returns its "site for cookies" (either a registered domain, or the 1036 empty string): 1038 1. Return "worker"'s origin's host's registered domain. 1040 5.3. The Set-Cookie Header 1042 When a user agent receives a Set-Cookie header field in an HTTP 1043 response, the user agent MAY ignore the Set-Cookie header field in 1044 its entirety. For example, the user agent might wish to block 1045 responses to "third-party" requests from setting cookies (see 1046 Section 7.1). 1048 If the user agent does not ignore the Set-Cookie header field in its 1049 entirety, the user agent MUST parse the field-value of the Set-Cookie 1050 header field as a set-cookie-string (defined below). 1052 NOTE: The algorithm below is more permissive than the grammar in 1053 Section 4.1. For example, the algorithm strips leading and trailing 1054 whitespace from the cookie name and value (but maintains internal 1055 whitespace), whereas the grammar in Section 4.1 forbids whitespace in 1056 these positions. User agents use this algorithm so as to 1057 interoperate with servers that do not follow the recommendations in 1058 Section 4. 1060 A user agent MUST use an algorithm equivalent to the following 1061 algorithm to parse a set-cookie-string: 1063 1. If the set-cookie-string contains a %x3B (";") character: 1065 1. The name-value-pair string consists of the characters up to, 1066 but not including, the first %x3B (";"), and the unparsed- 1067 attributes consist of the remainder of the set-cookie-string 1068 (including the %x3B (";") in question). 1070 Otherwise: 1072 1. The name-value-pair string consists of all the characters 1073 contained in the set-cookie-string, and the unparsed- 1074 attributes is the empty string. 1076 2. If the name-value-pair string lacks a %x3D ("=") character, 1077 ignore the set-cookie-string entirely. 1079 3. The (possibly empty) name string consists of the characters up 1080 to, but not including, the first %x3D ("=") character, and the 1081 (possibly empty) value string consists of the characters after 1082 the first %x3D ("=") character. 1084 4. Remove any leading or trailing WSP characters from the name 1085 string and the value string. 1087 5. If the name string is empty, ignore the set-cookie-string 1088 entirely. 1090 6. The cookie-name is the name string, and the cookie-value is the 1091 value string. 1093 The user agent MUST use an algorithm equivalent to the following 1094 algorithm to parse the unparsed-attributes: 1096 1. If the unparsed-attributes string is empty, skip the rest of 1097 these steps. 1099 2. Discard the first character of the unparsed-attributes (which 1100 will be a %x3B (";") character). 1102 3. If the remaining unparsed-attributes contains a %x3B (";") 1103 character: 1105 1. Consume the characters of the unparsed-attributes up to, but 1106 not including, the first %x3B (";") character. 1108 Otherwise: 1110 1. Consume the remainder of the unparsed-attributes. 1112 Let the cookie-av string be the characters consumed in this step. 1114 4. If the cookie-av string contains a %x3D ("=") character: 1116 1. The (possibly empty) attribute-name string consists of the 1117 characters up to, but not including, the first %x3D ("=") 1118 character, and the (possibly empty) attribute-value string 1119 consists of the characters after the first %x3D ("=") 1120 character. 1122 Otherwise: 1124 1. The attribute-name string consists of the entire cookie-av 1125 string, and the attribute-value string is empty. 1127 5. Remove any leading or trailing WSP characters from the attribute- 1128 name string and the attribute-value string. 1130 6. Process the attribute-name and attribute-value according to the 1131 requirements in the following subsections. (Notice that 1132 attributes with unrecognized attribute-names are ignored.) 1134 7. Return to Step 1 of this algorithm. 1136 When the user agent finishes parsing the set-cookie-string, the user 1137 agent is said to "receive a cookie" from the request-uri with name 1138 cookie-name, value cookie-value, and attributes cookie-attribute- 1139 list. (See Section 5.4 for additional requirements triggered by 1140 receiving a cookie.) 1142 5.3.1. The Expires Attribute 1144 If the attribute-name case-insensitively matches the string 1145 "Expires", the user agent MUST process the cookie-av as follows. 1147 1. Let the expiry-time be the result of parsing the attribute-value 1148 as cookie-date (see Section 5.1.1). 1150 2. If the attribute-value failed to parse as a cookie date, ignore 1151 the cookie-av. 1153 3. If the expiry-time is later than the last date the user agent can 1154 represent, the user agent MAY replace the expiry-time with the 1155 last representable date. 1157 4. If the expiry-time is earlier than the earliest date the user 1158 agent can represent, the user agent MAY replace the expiry-time 1159 with the earliest representable date. 1161 5. Append an attribute to the cookie-attribute-list with an 1162 attribute-name of Expires and an attribute-value of expiry-time. 1164 5.3.2. The Max-Age Attribute 1166 If the attribute-name case-insensitively matches the string "Max- 1167 Age", the user agent MUST process the cookie-av as follows. 1169 1. If the first character of the attribute-value is not a DIGIT or a 1170 "-" character, ignore the cookie-av. 1172 2. If the remainder of attribute-value contains a non-DIGIT 1173 character, ignore the cookie-av. 1175 3. Let delta-seconds be the attribute-value converted to an integer. 1177 4. If delta-seconds is less than or equal to zero (0), let expiry- 1178 time be the earliest representable date and time. Otherwise, let 1179 the expiry-time be the current date and time plus delta-seconds 1180 seconds. 1182 5. Append an attribute to the cookie-attribute-list with an 1183 attribute-name of Max-Age and an attribute-value of expiry-time. 1185 5.3.3. The Domain Attribute 1187 If the attribute-name case-insensitively matches the string "Domain", 1188 the user agent MUST process the cookie-av as follows. 1190 1. If the attribute-value is empty, the behavior is undefined. 1191 However, the user agent SHOULD ignore the cookie-av entirely. 1193 2. If the first character of the attribute-value string is %x2E 1194 ("."): 1196 1. Let cookie-domain be the attribute-value without the leading 1197 %x2E (".") character. 1199 Otherwise: 1201 1. Let cookie-domain be the entire attribute-value. 1203 3. Convert the cookie-domain to lower case. 1205 4. Append an attribute to the cookie-attribute-list with an 1206 attribute-name of Domain and an attribute-value of cookie-domain. 1208 5.3.4. The Path Attribute 1210 If the attribute-name case-insensitively matches the string "Path", 1211 the user agent MUST process the cookie-av as follows. 1213 1. If the attribute-value is empty or if the first character of the 1214 attribute-value is not %x2F ("/"): 1216 1. Let cookie-path be the default-path. 1218 Otherwise: 1220 1. Let cookie-path be the attribute-value. 1222 2. Append an attribute to the cookie-attribute-list with an 1223 attribute-name of Path and an attribute-value of cookie-path. 1225 5.3.5. The Secure Attribute 1227 If the attribute-name case-insensitively matches the string "Secure", 1228 the user agent MUST append an attribute to the cookie-attribute-list 1229 with an attribute-name of Secure and an empty attribute-value. 1231 5.3.6. The HttpOnly Attribute 1233 If the attribute-name case-insensitively matches the string 1234 "HttpOnly", the user agent MUST append an attribute to the cookie- 1235 attribute-list with an attribute-name of HttpOnly and an empty 1236 attribute-value. 1238 5.3.7. The SameSite Attribute 1240 If the attribute-name case-insensitively matches the string 1241 "SameSite", the user agent MUST process the cookie-av as follows: 1243 1. Let "enforcement" be "None". 1245 2. If cookie-av's attribute-value is a case-insensitive match for 1246 "Strict", set "enforcement" to "Strict". 1248 3. If cookie-av's attribute-value is a case-insensitive match for 1249 "Lax", set "enforcement" to "Lax". 1251 4. Append an attribute to the cookie-attribute-list with an 1252 attribute-name of "SameSite" and an attribute-value of 1253 "enforcement". 1255 Note: This algorithm maps the "None" value, as well as any unknown 1256 value, to the "None" behavior, which is helpful for backwards 1257 compatibility when introducing new variants. 1259 5.3.7.1. "Strict" and "Lax" enforcement 1261 Same-site cookies in "Strict" enforcement mode will not be sent along 1262 with top-level navigations which are triggered from a cross-site 1263 document context. As discussed in Section 8.8.2, this might or might 1264 not be compatible with existing session management systems. In the 1265 interests of providing a drop-in mechanism that mitigates the risk of 1266 CSRF attacks, developers may set the "SameSite" attribute in a "Lax" 1267 enforcement mode that carves out an exception which sends same-site 1268 cookies along with cross-site requests if and only if they are top- 1269 level navigations which use a "safe" (in the [RFC7231] sense) HTTP 1270 method. 1272 Lax enforcement provides reasonable defense in depth against CSRF 1273 attacks that rely on unsafe HTTP methods (like "POST"), but does not 1274 offer a robust defense against CSRF as a general category of attack: 1276 1. Attackers can still pop up new windows or trigger top-level 1277 navigations in order to create a "same-site" request (as 1278 described in section 2.1), which is only a speedbump along the 1279 road to exploitation. 1281 2. Features like "" [prerendering] can be 1282 exploited to create "same-site" requests without the risk of user 1283 detection. 1285 When possible, developers should use a session management mechanism 1286 such as that described in Section 8.8.2 to mitigate the risk of CSRF 1287 more completely. 1289 5.4. Storage Model 1291 The user agent stores the following fields about each cookie: name, 1292 value, expiry-time, domain, path, creation-time, last-access-time, 1293 persistent-flag, host-only-flag, secure-only-flag, http-only-flag, 1294 and same-site-flag. 1296 When the user agent "receives a cookie" from a request-uri with name 1297 cookie-name, value cookie-value, and attributes cookie-attribute- 1298 list, the user agent MUST process the cookie as follows: 1300 1. A user agent MAY ignore a received cookie in its entirety. For 1301 example, the user agent might wish to block receiving cookies 1302 from "third-party" responses or the user agent might not wish to 1303 store cookies that exceed some size. 1305 2. Create a new cookie with name cookie-name, value cookie-value. 1306 Set the creation-time and the last-access-time to the current 1307 date and time. 1309 3. If the cookie-attribute-list contains an attribute with an 1310 attribute-name of "Max-Age": 1312 1. Set the cookie's persistent-flag to true. 1314 2. Set the cookie's expiry-time to attribute-value of the last 1315 attribute in the cookie-attribute-list with an attribute- 1316 name of "Max-Age". 1318 Otherwise, if the cookie-attribute-list contains an attribute 1319 with an attribute-name of "Expires" (and does not contain an 1320 attribute with an attribute-name of "Max-Age"): 1322 1. Set the cookie's persistent-flag to true. 1324 2. Set the cookie's expiry-time to attribute-value of the last 1325 attribute in the cookie-attribute-list with an attribute- 1326 name of "Expires". 1328 Otherwise: 1330 1. Set the cookie's persistent-flag to false. 1332 2. Set the cookie's expiry-time to the latest representable 1333 date. 1335 4. If the cookie-attribute-list contains an attribute with an 1336 attribute-name of "Domain": 1338 1. Let the domain-attribute be the attribute-value of the last 1339 attribute in the cookie-attribute-list with an attribute- 1340 name of "Domain". 1342 Otherwise: 1344 1. Let the domain-attribute be the empty string. 1346 5. If the user agent is configured to reject "public suffixes" and 1347 the domain-attribute is a public suffix: 1349 1. If the domain-attribute is identical to the canonicalized 1350 request-host: 1352 1. Let the domain-attribute be the empty string. 1354 Otherwise: 1356 1. Ignore the cookie entirely and abort these steps. 1358 NOTE: A "public suffix" is a domain that is controlled by a 1359 public registry, such as "com", "co.uk", and "pvt.k12.wy.us". 1360 This step is essential for preventing attacker.com from 1361 disrupting the integrity of example.com by setting a cookie with 1362 a Domain attribute of "com". Unfortunately, the set of public 1363 suffixes (also known as "registry controlled domains") changes 1364 over time. If feasible, user agents SHOULD use an up-to-date 1365 public suffix list, such as the one maintained by the Mozilla 1366 project at http://publicsuffix.org/ [4]. 1368 6. If the domain-attribute is non-empty: 1370 1. If the canonicalized request-host does not domain-match the 1371 domain-attribute: 1373 1. Ignore the cookie entirely and abort these steps. 1375 Otherwise: 1377 1. Set the cookie's host-only-flag to false. 1379 2. Set the cookie's domain to the domain-attribute. 1381 Otherwise: 1383 1. Set the cookie's host-only-flag to true. 1385 2. Set the cookie's domain to the canonicalized request-host. 1387 7. If the cookie-attribute-list contains an attribute with an 1388 attribute-name of "Path", set the cookie's path to attribute- 1389 value of the last attribute in the cookie-attribute-list with an 1390 attribute-name of "Path". Otherwise, set the cookie's path to 1391 the default-path of the request-uri. 1393 8. If the cookie-attribute-list contains an attribute with an 1394 attribute-name of "Secure", set the cookie's secure-only-flag to 1395 true. Otherwise, set the cookie's secure-only-flag to false. 1397 9. If the scheme component of the request-uri does not denote a 1398 "secure" protocol (as defined by the user agent), and the 1399 cookie's secure-only-flag is true, then abort these steps and 1400 ignore the cookie entirely. 1402 10. If the cookie-attribute-list contains an attribute with an 1403 attribute-name of "HttpOnly", set the cookie's http-only-flag to 1404 true. Otherwise, set the cookie's http-only-flag to false. 1406 11. If the cookie was received from a "non-HTTP" API and the 1407 cookie's http-only-flag is true, abort these steps and ignore 1408 the cookie entirely. 1410 12. If the cookie's secure-only-flag is not set, and the scheme 1411 component of request-uri does not denote a "secure" protocol, 1412 then abort these steps and ignore the cookie entirely if the 1413 cookie store contains one or more cookies that meet all of the 1414 following criteria: 1416 1. Their name matches the name of the newly-created cookie. 1418 2. Their secure-only-flag is true. 1420 3. Their domain domain-matches the domain of the newly-created 1421 cookie, or vice-versa. 1423 4. The path of the newly-created cookie path-matches the path 1424 of the existing cookie. 1426 Note: The path comparison is not symmetric, ensuring only that a 1427 newly-created, non-secure cookie does not overlay an existing 1428 secure cookie, providing some mitigation against cookie-fixing 1429 attacks. That is, given an existing secure cookie named 'a' 1430 with a path of '/login', a non-secure cookie named 'a' could be 1431 set for a path of '/' or '/foo', but not for a path of '/login' 1432 or '/login/en'. 1434 13. If the cookie-attribute-list contains an attribute with an 1435 attribute-name of "SameSite", set the cookie's same-site-flag to 1436 attribute-value (i.e. either "Strict", "Lax", or "None"). 1437 Otherwise, set the cookie's same-site-flag to "None". 1439 14. If the cookie's "same-site-flag" is not "None", and the cookie 1440 is being set from a context whose "site for cookies" is not an 1441 exact match for request-uri's host's registered domain, then 1442 abort these steps and ignore the newly created cookie entirely. 1444 15. If the cookie-name begins with a case-sensitive match for the 1445 string "__Secure-", abort these steps and ignore the cookie 1446 entirely unless the cookie's secure-only-flag is true. 1448 16. If the cookie-name begins with a case-sensitive match for the 1449 string "__Host-", abort these steps and ignore the cookie 1450 entirely unless the cookie meets all the following criteria: 1452 1. The cookie's secure-only-flag is true. 1454 2. The cookie's host-only-flag is true. 1456 3. The cookie-attribute-list contains an attribute with an 1457 attribute-name of "Path", and the cookie's path is "/". 1459 17. If the cookie store contains a cookie with the same name, 1460 domain, host-only-flag, and path as the newly-created cookie: 1462 1. Let old-cookie be the existing cookie with the same name, 1463 domain, host-only-flag, and path as the newly-created 1464 cookie. (Notice that this algorithm maintains the invariant 1465 that there is at most one such cookie.) 1467 2. If the newly-created cookie was received from a "non-HTTP" 1468 API and the old-cookie's http-only-flag is true, abort these 1469 steps and ignore the newly created cookie entirely. 1471 3. Update the creation-time of the newly-created cookie to 1472 match the creation-time of the old-cookie. 1474 4. Remove the old-cookie from the cookie store. 1476 18. Insert the newly-created cookie into the cookie store. 1478 A cookie is "expired" if the cookie has an expiry date in the past. 1480 The user agent MUST evict all expired cookies from the cookie store 1481 if, at any time, an expired cookie exists in the cookie store. 1483 At any time, the user agent MAY "remove excess cookies" from the 1484 cookie store if the number of cookies sharing a domain field exceeds 1485 some implementation-defined upper bound (such as 50 cookies). 1487 At any time, the user agent MAY "remove excess cookies" from the 1488 cookie store if the cookie store exceeds some predetermined upper 1489 bound (such as 3000 cookies). 1491 When the user agent removes excess cookies from the cookie store, the 1492 user agent MUST evict cookies in the following priority order: 1494 1. Expired cookies. 1496 2. Cookies whose secure-only-flag is not set, and which share a 1497 domain field with more than a predetermined number of other 1498 cookies. 1500 3. Cookies that share a domain field with more than a predetermined 1501 number of other cookies. 1503 4. All cookies. 1505 If two cookies have the same removal priority, the user agent MUST 1506 evict the cookie with the earliest last-access date first. 1508 When "the current session is over" (as defined by the user agent), 1509 the user agent MUST remove from the cookie store all cookies with the 1510 persistent-flag set to false. 1512 5.5. The Cookie Header 1514 The user agent includes stored cookies in the Cookie HTTP request 1515 header. 1517 When the user agent generates an HTTP request, the user agent MUST 1518 NOT attach more than one Cookie header field. 1520 A user agent MAY omit the Cookie header in its entirety. For 1521 example, the user agent might wish to block sending cookies during 1522 "third-party" requests from setting cookies (see Section 7.1). 1524 If the user agent does attach a Cookie header field to an HTTP 1525 request, the user agent MUST send the cookie-string (defined below) 1526 as the value of the header field. 1528 The user agent MUST use an algorithm equivalent to the following 1529 algorithm to compute the cookie-string from a cookie store and a 1530 request-uri: 1532 1. Let cookie-list be the set of cookies from the cookie store that 1533 meets all of the following requirements: 1535 * Either: 1537 + The cookie's host-only-flag is true and the canonicalized 1538 request-host is identical to the cookie's domain. 1540 Or: 1542 + The cookie's host-only-flag is false and the canonicalized 1543 request-host domain-matches the cookie's domain. 1545 * The request-uri's path path-matches the cookie's path. 1547 * If the cookie's secure-only-flag is true, then the request- 1548 uri's scheme must denote a "secure" protocol (as defined by 1549 the user agent). 1551 NOTE: The notion of a "secure" protocol is not defined by this 1552 document. Typically, user agents consider a protocol secure 1553 if the protocol makes use of transport-layer security, such as 1554 SSL or TLS. For example, most user agents consider "https" to 1555 be a scheme that denotes a secure protocol. 1557 * If the cookie's http-only-flag is true, then exclude the 1558 cookie if the cookie-string is being generated for a "non- 1559 HTTP" API (as defined by the user agent). 1561 * If the cookie's same-site-flag is not "None", and the HTTP 1562 request is cross-site (as defined in Section 5.2) then exclude 1563 the cookie unless all of the following statements hold: 1565 1. The same-site-flag is "Lax" 1567 2. The HTTP request's method is "safe". 1569 3. The HTTP request's target browsing context is a top-level 1570 browsing context. 1572 2. The user agent SHOULD sort the cookie-list in the following 1573 order: 1575 * Cookies with longer paths are listed before cookies with 1576 shorter paths. 1578 * Among cookies that have equal-length path fields, cookies with 1579 earlier creation-times are listed before cookies with later 1580 creation-times. 1582 NOTE: Not all user agents sort the cookie-list in this order, but 1583 this order reflects common practice when this document was 1584 written, and, historically, there have been servers that 1585 (erroneously) depended on this order. 1587 3. Update the last-access-time of each cookie in the cookie-list to 1588 the current date and time. 1590 4. Serialize the cookie-list into a cookie-string by processing each 1591 cookie in the cookie-list in order: 1593 1. Output the cookie's name, the %x3D ("=") character, and the 1594 cookie's value. 1596 2. If there is an unprocessed cookie in the cookie-list, output 1597 the characters %x3B and %x20 ("; "). 1599 NOTE: Despite its name, the cookie-string is actually a sequence of 1600 octets, not a sequence of characters. To convert the cookie-string 1601 (or components thereof) into a sequence of characters (e.g., for 1602 presentation to the user), the user agent might wish to try using the 1603 UTF-8 character encoding [RFC3629] to decode the octet sequence. 1604 This decoding might fail, however, because not every sequence of 1605 octets is valid UTF-8. 1607 6. Implementation Considerations 1609 6.1. Limits 1611 Practical user agent implementations have limits on the number and 1612 size of cookies that they can store. General-use user agents SHOULD 1613 provide each of the following minimum capabilities: 1615 o At least 4096 bytes per cookie (as measured by the sum of the 1616 length of the cookie's name, value, and attributes). 1618 o At least 50 cookies per domain. 1620 o At least 3000 cookies total. 1622 Servers SHOULD use as few and as small cookies as possible to avoid 1623 reaching these implementation limits and to minimize network 1624 bandwidth due to the Cookie header being included in every request. 1626 Servers SHOULD gracefully degrade if the user agent fails to return 1627 one or more cookies in the Cookie header because the user agent might 1628 evict any cookie at any time on orders from the user. 1630 6.2. Application Programming Interfaces 1632 One reason the Cookie and Set-Cookie headers use such esoteric syntax 1633 is that many platforms (both in servers and user agents) provide a 1634 string-based application programming interface (API) to cookies, 1635 requiring application-layer programmers to generate and parse the 1636 syntax used by the Cookie and Set-Cookie headers, which many 1637 programmers have done incorrectly, resulting in interoperability 1638 problems. 1640 Instead of providing string-based APIs to cookies, platforms would be 1641 well-served by providing more semantic APIs. It is beyond the scope 1642 of this document to recommend specific API designs, but there are 1643 clear benefits to accepting an abstract "Date" object instead of a 1644 serialized date string. 1646 6.3. IDNA Dependency and Migration 1648 IDNA2008 [RFC5890] supersedes IDNA2003 [RFC3490]. However, there are 1649 differences between the two specifications, and thus there can be 1650 differences in processing (e.g., converting) domain name labels that 1651 have been registered under one from those registered under the other. 1652 There will be a transition period of some time during which 1653 IDNA2003-based domain name labels will exist in the wild. User 1654 agents SHOULD implement IDNA2008 [RFC5890] and MAY implement [UTS46] 1655 or [RFC5895] in order to facilitate their IDNA transition. If a user 1656 agent does not implement IDNA2008, the user agent MUST implement 1657 IDNA2003 [RFC3490]. 1659 7. Privacy Considerations 1661 Cookies are often criticized for letting servers track users. For 1662 example, a number of "web analytics" companies use cookies to 1663 recognize when a user returns to a web site or visits another web 1664 site. Although cookies are not the only mechanism servers can use to 1665 track users across HTTP requests, cookies facilitate tracking because 1666 they are persistent across user agent sessions and can be shared 1667 between hosts. 1669 7.1. Third-Party Cookies 1671 Particularly worrisome are so-called "third-party" cookies. In 1672 rendering an HTML document, a user agent often requests resources 1673 from other servers (such as advertising networks). These third-party 1674 servers can use cookies to track the user even if the user never 1675 visits the server directly. For example, if a user visits a site 1676 that contains content from a third party and then later visits 1677 another site that contains content from the same third party, the 1678 third party can track the user between the two sites. 1680 Given this risk to user privacy, some user agents restrict how third- 1681 party cookies behave, and those restrictions vary widly. For 1682 instance, user agents might block third-party cookies entirely by 1683 refusing to send Cookie headers or process Set-Cookie headers during 1684 third-party requests. They might take a less draconian approach by 1685 partitioning cookies based on the first-party context, sending one 1686 set of cookies to a given third party in one first-party context, and 1687 another to the same third party in another. 1689 This document grants user agents wide latitude to experiment with 1690 third-party cookie policies that balance the privacy and 1691 compatibility needs of their users. However, this document does not 1692 endorse any particular third-party cookie policy. 1694 Third-party cookie blocking policies are often ineffective at 1695 achieving their privacy goals if servers attempt to work around their 1696 restrictions to track users. In particular, two collaborating 1697 servers can often track users without using cookies at all by 1698 injecting identifying information into dynamic URLs. 1700 7.2. User Controls 1702 User agents SHOULD provide users with a mechanism for managing the 1703 cookies stored in the cookie store. For example, a user agent might 1704 let users delete all cookies received during a specified time period 1705 or all the cookies related to a particular domain. In addition, many 1706 user agents include a user interface element that lets users examine 1707 the cookies stored in their cookie store. 1709 User agents SHOULD provide users with a mechanism for disabling 1710 cookies. When cookies are disabled, the user agent MUST NOT include 1711 a Cookie header in outbound HTTP requests and the user agent MUST NOT 1712 process Set-Cookie headers in inbound HTTP responses. 1714 Some user agents provide users the option of preventing persistent 1715 storage of cookies across sessions. When configured thusly, user 1716 agents MUST treat all received cookies as if the persistent-flag were 1717 set to false. Some popular user agents expose this functionality via 1718 "private browsing" mode [Aggarwal2010]. 1720 Some user agents provide users with the ability to approve individual 1721 writes to the cookie store. In many common usage scenarios, these 1722 controls generate a large number of prompts. However, some privacy- 1723 conscious users find these controls useful nonetheless. 1725 7.3. Expiration Dates 1727 Although servers can set the expiration date for cookies to the 1728 distant future, most user agents do not actually retain cookies for 1729 multiple decades. Rather than choosing gratuitously long expiration 1730 periods, servers SHOULD promote user privacy by selecting reasonable 1731 cookie expiration periods based on the purpose of the cookie. For 1732 example, a typical session identifier might reasonably be set to 1733 expire in two weeks. 1735 8. Security Considerations 1737 8.1. Overview 1739 Cookies have a number of security pitfalls. This section overviews a 1740 few of the more salient issues. 1742 In particular, cookies encourage developers to rely on ambient 1743 authority for authentication, often becoming vulnerable to attacks 1744 such as cross-site request forgery [CSRF]. Also, when storing 1745 session identifiers in cookies, developers often create session 1746 fixation vulnerabilities. 1748 Transport-layer encryption, such as that employed in HTTPS, is 1749 insufficient to prevent a network attacker from obtaining or altering 1750 a victim's cookies because the cookie protocol itself has various 1751 vulnerabilities (see "Weak Confidentiality" and "Weak Integrity", 1752 below). In addition, by default, cookies do not provide 1753 confidentiality or integrity from network attackers, even when used 1754 in conjunction with HTTPS. 1756 8.2. Ambient Authority 1758 A server that uses cookies to authenticate users can suffer security 1759 vulnerabilities because some user agents let remote parties issue 1760 HTTP requests from the user agent (e.g., via HTTP redirects or HTML 1761 forms). When issuing those requests, user agents attach cookies even 1762 if the remote party does not know the contents of the cookies, 1763 potentially letting the remote party exercise authority at an unwary 1764 server. 1766 Although this security concern goes by a number of names (e.g., 1767 cross-site request forgery, confused deputy), the issue stems from 1768 cookies being a form of ambient authority. Cookies encourage server 1769 operators to separate designation (in the form of URLs) from 1770 authorization (in the form of cookies). Consequently, the user agent 1771 might supply the authorization for a resource designated by the 1772 attacker, possibly causing the server or its clients to undertake 1773 actions designated by the attacker as though they were authorized by 1774 the user. 1776 Instead of using cookies for authorization, server operators might 1777 wish to consider entangling designation and authorization by treating 1778 URLs as capabilities. Instead of storing secrets in cookies, this 1779 approach stores secrets in URLs, requiring the remote entity to 1780 supply the secret itself. Although this approach is not a panacea, 1781 judicious application of these principles can lead to more robust 1782 security. 1784 8.3. Clear Text 1786 Unless sent over a secure channel (such as TLS), the information in 1787 the Cookie and Set-Cookie headers is transmitted in the clear. 1789 1. All sensitive information conveyed in these headers is exposed to 1790 an eavesdropper. 1792 2. A malicious intermediary could alter the headers as they travel 1793 in either direction, with unpredictable results. 1795 3. A malicious client could alter the Cookie header before 1796 transmission, with unpredictable results. 1798 Servers SHOULD encrypt and sign the contents of cookies (using 1799 whatever format the server desires) when transmitting them to the 1800 user agent (even when sending the cookies over a secure channel). 1801 However, encrypting and signing cookie contents does not prevent an 1802 attacker from transplanting a cookie from one user agent to another 1803 or from replaying the cookie at a later time. 1805 In addition to encrypting and signing the contents of every cookie, 1806 servers that require a higher level of security SHOULD use the Cookie 1807 and Set-Cookie headers only over a secure channel. When using 1808 cookies over a secure channel, servers SHOULD set the Secure 1809 attribute (see Section 4.1.2.5) for every cookie. If a server does 1810 not set the Secure attribute, the protection provided by the secure 1811 channel will be largely moot. 1813 For example, consider a webmail server that stores a session 1814 identifier in a cookie and is typically accessed over HTTPS. If the 1815 server does not set the Secure attribute on its cookies, an active 1816 network attacker can intercept any outbound HTTP request from the 1817 user agent and redirect that request to the webmail server over HTTP. 1818 Even if the webmail server is not listening for HTTP connections, the 1819 user agent will still include cookies in the request. The active 1820 network attacker can intercept these cookies, replay them against the 1821 server, and learn the contents of the user's email. If, instead, the 1822 server had set the Secure attribute on its cookies, the user agent 1823 would not have included the cookies in the clear-text request. 1825 8.4. Session Identifiers 1827 Instead of storing session information directly in a cookie (where it 1828 might be exposed to or replayed by an attacker), servers commonly 1829 store a nonce (or "session identifier") in a cookie. When the server 1830 receives an HTTP request with a nonce, the server can look up state 1831 information associated with the cookie using the nonce as a key. 1833 Using session identifier cookies limits the damage an attacker can 1834 cause if the attacker learns the contents of a cookie because the 1835 nonce is useful only for interacting with the server (unlike non- 1836 nonce cookie content, which might itself be sensitive). Furthermore, 1837 using a single nonce prevents an attacker from "splicing" together 1838 cookie content from two interactions with the server, which could 1839 cause the server to behave unexpectedly. 1841 Using session identifiers is not without risk. For example, the 1842 server SHOULD take care to avoid "session fixation" vulnerabilities. 1843 A session fixation attack proceeds in three steps. First, the 1844 attacker transplants a session identifier from his or her user agent 1845 to the victim's user agent. Second, the victim uses that session 1846 identifier to interact with the server, possibly imbuing the session 1847 identifier with the user's credentials or confidential information. 1848 Third, the attacker uses the session identifier to interact with 1849 server directly, possibly obtaining the user's authority or 1850 confidential information. 1852 8.5. Weak Confidentiality 1854 Cookies do not provide isolation by port. If a cookie is readable by 1855 a service running on one port, the cookie is also readable by a 1856 service running on another port of the same server. If a cookie is 1857 writable by a service on one port, the cookie is also writable by a 1858 service running on another port of the same server. For this reason, 1859 servers SHOULD NOT both run mutually distrusting services on 1860 different ports of the same host and use cookies to store security- 1861 sensitive information. 1863 Cookies do not provide isolation by scheme. Although most commonly 1864 used with the http and https schemes, the cookies for a given host 1865 might also be available to other schemes, such as ftp and gopher. 1866 Although this lack of isolation by scheme is most apparent in non- 1867 HTTP APIs that permit access to cookies (e.g., HTML's document.cookie 1868 API), the lack of isolation by scheme is actually present in 1869 requirements for processing cookies themselves (e.g., consider 1870 retrieving a URI with the gopher scheme via HTTP). 1872 Cookies do not always provide isolation by path. Although the 1873 network-level protocol does not send cookies stored for one path to 1874 another, some user agents expose cookies via non-HTTP APIs, such as 1875 HTML's document.cookie API. Because some of these user agents (e.g., 1876 web browsers) do not isolate resources received from different paths, 1877 a resource retrieved from one path might be able to access cookies 1878 stored for another path. 1880 8.6. Weak Integrity 1882 Cookies do not provide integrity guarantees for sibling domains (and 1883 their subdomains). For example, consider foo.example.com and 1884 bar.example.com. The foo.example.com server can set a cookie with a 1885 Domain attribute of "example.com" (possibly overwriting an existing 1886 "example.com" cookie set by bar.example.com), and the user agent will 1887 include that cookie in HTTP requests to bar.example.com. In the 1888 worst case, bar.example.com will be unable to distinguish this cookie 1889 from a cookie it set itself. The foo.example.com server might be 1890 able to leverage this ability to mount an attack against 1891 bar.example.com. 1893 Even though the Set-Cookie header supports the Path attribute, the 1894 Path attribute does not provide any integrity protection because the 1895 user agent will accept an arbitrary Path attribute in a Set-Cookie 1896 header. For example, an HTTP response to a request for 1897 http://example.com/foo/bar can set a cookie with a Path attribute of 1898 "/qux". Consequently, servers SHOULD NOT both run mutually 1899 distrusting services on different paths of the same host and use 1900 cookies to store security-sensitive information. 1902 An active network attacker can also inject cookies into the Cookie 1903 header sent to https://example.com/ by impersonating a response from 1904 http://example.com/ and injecting a Set-Cookie header. The HTTPS 1905 server at example.com will be unable to distinguish these cookies 1906 from cookies that it set itself in an HTTPS response. An active 1907 network attacker might be able to leverage this ability to mount an 1908 attack against example.com even if example.com uses HTTPS 1909 exclusively. 1911 Servers can partially mitigate these attacks by encrypting and 1912 signing the contents of their cookies. However, using cryptography 1913 does not mitigate the issue completely because an attacker can replay 1914 a cookie he or she received from the authentic example.com server in 1915 the user's session, with unpredictable results. 1917 Finally, an attacker might be able to force the user agent to delete 1918 cookies by storing a large number of cookies. Once the user agent 1919 reaches its storage limit, the user agent will be forced to evict 1920 some cookies. Servers SHOULD NOT rely upon user agents retaining 1921 cookies. 1923 8.7. Reliance on DNS 1925 Cookies rely upon the Domain Name System (DNS) for security. If the 1926 DNS is partially or fully compromised, the cookie protocol might fail 1927 to provide the security properties required by applications. 1929 8.8. SameSite Cookies 1931 8.8.1. Defense in depth 1933 "SameSite" cookies offer a robust defense against CSRF attack when 1934 deployed in strict mode, and when supported by the client. It is, 1935 however, prudent to ensure that this designation is not the extent of 1936 a site's defense against CSRF, as same-site navigations and 1937 submissions can certainly be executed in conjunction with other 1938 attack vectors such as cross-site scripting. 1940 Developers are strongly encouraged to deploy the usual server-side 1941 defenses (CSRF tokens, ensuring that "safe" HTTP methods are 1942 idempotent, etc) to mitigate the risk more fully. 1944 Additionally, client-side techniques such as those described in 1945 [app-isolation] may also prove effective against CSRF, and are 1946 certainly worth exploring in combination with "SameSite" cookies. 1948 8.8.2. Top-level Navigations 1950 Setting the "SameSite" attribute in "strict" mode provides robust 1951 defense in depth against CSRF attacks, but has the potential to 1952 confuse users unless sites' developers carefully ensure that their 1953 cookie-based session management systems deal reasonably well with 1954 top-level navigations. 1956 Consider the scenario in which a user reads their email at MegaCorp 1957 Inc's webmail provider "https://example.com/". They might expect 1958 that clicking on an emailed link to "https://projects.com/secret/ 1959 project" would show them the secret project that they're authorized 1960 to see, but if "projects.com" has marked their session cookies as 1961 "SameSite", then this cross-site navigation won't send them along 1962 with the request. "projects.com" will render a 404 error to avoid 1963 leaking secret information, and the user will be quite confused. 1965 Developers can avoid this confusion by adopting a session management 1966 system that relies on not one, but two cookies: one conceptually 1967 granting "read" access, another granting "write" access. The latter 1968 could be marked as "SameSite", and its absence would prompt a 1969 reauthentication step before executing any non-idempotent action. 1970 The former could drop the "SameSite" attribute entirely, or choose 1971 the "Lax" version of enforcement, in order to allow users access to 1972 data via top-level navigation. 1974 8.8.3. Mashups and Widgets 1976 The "SameSite" attribute is inappropriate for some important use- 1977 cases. In particular, note that content intended for embedding in a 1978 cross-site contexts (social networking widgets or commenting 1979 services, for instance) will not have access to same-site cookies. 1980 Cookies may be required for requests triggered in these cross-site 1981 contexts in order to provide seamless functionality that relies on a 1982 user's state. 1984 Likewise, some forms of Single-Sign-On might require cookie-based 1985 authentication in a cross-site context; these mechanisms will not 1986 function as intended with same-site cookies. 1988 8.8.4. Server-controlled 1990 SameSite cookies in and of themselves don't do anything to address 1991 the general privacy concerns outlined in Section 7.1 of [RFC6265]. 1992 The "SameSite" attribute is set by the server, and serves to mitigate 1993 the risk of certain kinds of attacks that the server is worried 1994 about. The user is not involved in this decision. Moreover, a 1995 number of side-channels exist which could allow a server to link 1996 distinct requests even in the absence of cookies. Connection and/or 1997 socket pooling, Token Binding, and Channel ID all offer explicit 1998 methods of identification that servers could take advantage of. 2000 9. IANA Considerations 2002 The permanent message header field registry (see [RFC3864]) needs to 2003 be updated with the following registrations. 2005 9.1. Cookie 2007 Header field name: Cookie 2009 Applicable protocol: http 2011 Status: standard 2013 Author/Change controller: IETF 2015 Specification document: this specification (Section 5.5) 2017 9.2. Set-Cookie 2019 Header field name: Set-Cookie 2021 Applicable protocol: http 2023 Status: standard 2025 Author/Change controller: IETF 2027 Specification document: this specification (Section 5.3) 2029 10. References 2031 10.1. Normative References 2033 [FETCH] van Kesteren, A., "Fetch", n.d., 2034 . 2036 [HTML] Hickson, I., Pieters, S., van Kesteren, A., Jaegenstedt, 2037 P., and D. Denicola, "HTML", n.d., 2038 . 2040 [PSL] "Public Suffix List", n.d., 2041 . 2043 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 2044 STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987, 2045 . 2047 [RFC1123] Braden, R., Ed., "Requirements for Internet Hosts - 2048 Application and Support", STD 3, RFC 1123, 2049 DOI 10.17487/RFC1123, October 1989, 2050 . 2052 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2053 Requirement Levels", BCP 14, RFC 2119, 2054 DOI 10.17487/RFC2119, March 1997, 2055 . 2057 [RFC3490] Costello, A., "Internationalizing Domain Names in 2058 Applications (IDNA)", RFC 3490, DOI 10.17487/RFC3490, 2059 March 2003, . 2061 See Section 6.3 for an explanation why the normative 2062 reference to an obsoleted specification is needed. 2064 [RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet 2065 Application Protocol Collation Registry", RFC 4790, 2066 DOI 10.17487/RFC4790, March 2007, 2067 . 2069 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 2070 Specifications: ABNF", STD 68, RFC 5234, 2071 DOI 10.17487/RFC5234, January 2008, 2072 . 2074 [RFC5890] Klensin, J., "Internationalized Domain Names for 2075 Applications (IDNA): Definitions and Document Framework", 2076 RFC 5890, DOI 10.17487/RFC5890, August 2010, 2077 . 2079 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 2080 DOI 10.17487/RFC6454, December 2011, 2081 . 2083 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2084 Protocol (HTTP/1.1): Message Syntax and Routing", 2085 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2086 . 2088 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2089 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 2090 DOI 10.17487/RFC7231, June 2014, 2091 . 2093 [SERVICE-WORKERS] 2094 Russell, A., Song, J., and J. Archibald, "Service 2095 Workers", n.d., . 2097 [USASCII] American National Standards Institute, "Coded Character 2098 Set -- 7-bit American Standard Code for Information 2099 Interchange", ANSI X3.4, 1986. 2101 10.2. Informative References 2103 [Aggarwal2010] 2104 Aggarwal, G., Burzstein, E., Jackson, C., and D. Boneh, 2105 "An Analysis of Private Browsing Modes in Modern 2106 Browsers", 2010, 2107 . 2110 [app-isolation] 2111 Chen, E., Bau, J., Reis, C., Barth, A., and C. Jackson, 2112 "App Isolation - Get the Security of Multiple Browsers 2113 with Just One", 2011, 2114 . 2117 [CSRF] Barth, A., Jackson, C., and J. Mitchell, "Robust Defenses 2118 for Cross-Site Request Forgery", 2119 DOI 10.1145/1455770.1455782, ISBN 978-1-59593-810-7, 2120 ACM CCS '08: Proceedings of the 15th ACM conference on 2121 Computer and communications security (pages 75-88), 2122 October 2008, 2123 . 2125 [I-D.ietf-httpbis-cookie-alone] 2126 West, M., "Deprecate modification of 'secure' cookies from 2127 non-secure origins", draft-ietf-httpbis-cookie-alone-01 2128 (work in progress), September 2016. 2130 [I-D.ietf-httpbis-cookie-prefixes] 2131 West, M., "Cookie Prefixes", draft-ietf-httpbis-cookie- 2132 prefixes-00 (work in progress), February 2016. 2134 [I-D.ietf-httpbis-cookie-same-site] 2135 West, M. and M. Goodwin, "Same-Site Cookies", draft-ietf- 2136 httpbis-cookie-same-site-00 (work in progress), June 2016. 2138 [prerendering] 2139 Bentzel, C., "Chrome Prerendering", n.d., 2140 . 2143 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 2144 DOI 10.17487/RFC2818, May 2000, 2145 . 2147 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2148 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2149 2003, . 2151 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 2152 Procedures for Message Header Fields", BCP 90, RFC 3864, 2153 DOI 10.17487/RFC3864, September 2004, 2154 . 2156 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2157 Resource Identifier (URI): Generic Syntax", STD 66, 2158 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2159 . 2161 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2162 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 2163 . 2165 [RFC5895] Resnick, P. and P. Hoffman, "Mapping Characters for 2166 Internationalized Domain Names in Applications (IDNA) 2167 2008", RFC 5895, DOI 10.17487/RFC5895, September 2010, 2168 . 2170 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 2171 DOI 10.17487/RFC6265, April 2011, 2172 . 2174 [RFC7034] Ross, D. and T. Gondrom, "HTTP Header Field X-Frame- 2175 Options", RFC 7034, DOI 10.17487/RFC7034, October 2013, 2176 . 2178 [UTS46] Davis, M. and M. Suignard, "Unicode IDNA Compatibility 2179 Processing", UNICODE Unicode Technical Standards # 46, 2180 June 2016, . 2182 10.3. URIs 2184 [1] https://lists.w3.org/Archives/Public/ietf-http-wg/ 2186 [2] http://httpwg.github.io/ 2188 [3] https://github.com/httpwg/http-extensions/labels/6265bis 2190 [4] http://publicsuffix.org/ 2192 [5] https://github.com/httpwg/http-extensions/issues/243 2194 [6] https://github.com/httpwg/http-extensions/issues/246 2196 [7] https://www.rfc-editor.org/errata_search.php?rfc=6265 2198 [8] https://github.com/httpwg/http-extensions/issues/247 2200 [9] https://github.com/httpwg/http-extensions/issues/201 2202 [10] https://github.com/httpwg/http-extensions/issues/204 2204 [11] https://github.com/httpwg/http-extensions/issues/222 2206 [12] https://github.com/httpwg/http-extensions/issues/248 2208 [13] https://github.com/httpwg/http-extensions/issues/295 2210 [14] https://github.com/httpwg/http-extensions/issues/302 2212 [15] https://github.com/httpwg/http-extensions/issues/389 2214 [16] https://github.com/httpwg/http-extensions/issues/199 2216 [17] https://github.com/httpwg/http-extensions/issues/788 2218 Appendix A. Changes 2220 A.1. draft-ietf-httpbis-rfc6265bis-00 2222 o Port [RFC6265] to Markdown. No (intentional) normative changes. 2224 A.2. draft-ietf-httpbis-rfc6265bis-01 2226 o Fixes to formatting caused by mistakes in the initial port to 2227 Markdown: 2229 * https://github.com/httpwg/http-extensions/issues/243 [5] 2231 * https://github.com/httpwg/http-extensions/issues/246 [6] 2233 o Addresses errata 3444 by updating the "path-value" and "extension- 2234 av" grammar, errata 4148 by updating the "day-of-month", "year", 2235 and "time" grammar, and errata 3663 by adding the requested note. 2236 https://www.rfc-editor.org/errata_search.php?rfc=6265 [7] 2238 o Dropped "Cookie2" and "Set-Cookie2" from the IANA Considerations 2239 section: https://github.com/httpwg/http-extensions/issues/247 [8] 2241 o Merged the recommendations from [I-D.ietf-httpbis-cookie-alone], 2242 removing the ability for a non-secure origin to set cookies with a 2243 'secure' flag, and to overwrite cookies whose 'secure' flag is 2244 true. 2246 o Merged the recommendations from 2247 [I-D.ietf-httpbis-cookie-prefixes], adding "__Secure-" and 2248 "__Host-" cookie name prefix processing instructions. 2250 A.3. draft-ietf-httpbis-rfc6265bis-02 2252 o Merged the recommendations from 2253 [I-D.ietf-httpbis-cookie-same-site], adding support for the 2254 "SameSite" attribute. 2256 o Closed a number of editorial bugs: 2258 * Clarified address bar behavior for SameSite cookies: 2259 https://github.com/httpwg/http-extensions/issues/201 [9] 2261 * Added the word "Cookies" to the document's name: 2262 https://github.com/httpwg/http-extensions/issues/204 [10] 2264 * Clarified that the "__Host-" prefix requires an explicit "Path" 2265 attribute: https://github.com/httpwg/http-extensions/issues/222 2266 [11] 2268 * Expanded the options for dealing with third-party cookies to 2269 include a brief mention of partitioning based on first-party: 2270 https://github.com/httpwg/http-extensions/issues/248 [12] 2272 * Noted that double-quotes in cookie values are part of the 2273 value, and are not stripped: https://github.com/httpwg/http- 2274 extensions/issues/295 [13] 2276 * Fixed the "site for cookies" algorithm to return something that 2277 makes sense: https://github.com/httpwg/http-extensions/ 2278 issues/302 [14] 2280 A.4. draft-ietf-httpbis-rfc6265bis-03 2282 o Clarified handling of invalid SameSite values: 2283 https://github.com/httpwg/http-extensions/issues/389 [15] 2285 o Reflect widespread implementation practice of including a cookie's 2286 "host-only-flag" when calculating its uniqueness: 2287 https://github.com/httpwg/http-extensions/issues/199 [16] 2289 o Introduced an explicit "None" value for the SameSite attribute: 2290 https://github.com/httpwg/http-extensions/issues/788 [17] 2292 Acknowledgements 2294 This document is a minor update of RFC 6265, adding small features, 2295 and aligning the specification with the reality of today's 2296 deployments. Here, we're standing upon the shoulders of giants. 2298 Authors' Addresses 2300 Adam Barth 2301 Google, Inc 2303 URI: https://www.adambarth.com/ 2305 Mike West 2306 Google, Inc 2308 Email: mkwst@google.com 2309 URI: https://mikewest.org/