idnits 2.17.1 draft-ietf-httpbis-rfc6265bis-08.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: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 3 instances of too long lines in the document, the longest one being 4 characters in excess of 72. 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 (2 June 2021) is 1051 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'DOM-DOCUMENT-COOKIE' -- Possible downref: Non-RFC (?) normative reference: ref. 'FETCH' -- Possible downref: Non-RFC (?) normative reference: ref. 'HTML' == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-16 -- Possible downref: Normative reference to a draft: ref. 'HTTPSEM' ** Obsolete normative reference: RFC 3490 (Obsoleted by RFC 5890, RFC 5891) -- Possible downref: Non-RFC (?) normative reference: ref. 'SAMESITE' -- 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: 2 errors (**), 0 flaws (~~), 4 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP L. Chen, Ed. 3 Internet-Draft Google LLC 4 Obsoletes: 6265 (if approved) S. Englehardt, Ed. 5 Intended status: Standards Track Mozilla 6 Expires: 4 December 2021 M. West, Ed. 7 Google LLC 8 J. Wilander, Ed. 9 Apple, Inc 10 2 June 2021 12 Cookies: HTTP State Management Mechanism 13 draft-ietf-httpbis-rfc6265bis-08 15 Abstract 17 This document defines the HTTP Cookie and Set-Cookie header fields. 18 These header fields can be used by HTTP servers to store state 19 (called cookies) at HTTP user agents, letting the servers maintain a 20 stateful session over the mostly stateless HTTP protocol. Although 21 cookies have many historical infelicities that degrade their security 22 and privacy, the Cookie and Set-Cookie header fields are widely used 23 on the Internet. This document obsoletes RFC 6265. 25 Note to Readers 27 Discussion of this draft takes place on the HTTP working group 28 mailing list (ietf-http-wg@w3.org), which is archived at 29 https://lists.w3.org/Archives/Public/ietf-http-wg/ 30 (https://lists.w3.org/Archives/Public/ietf-http-wg/). 32 Working Group information can be found at http://httpwg.github.io/ 33 (http://httpwg.github.io/); source code and issues list for this 34 draft can be found at https://github.com/httpwg/http-extensions/ 35 labels/6265bis (https://github.com/httpwg/http-extensions/ 36 labels/6265bis). 38 Status of This Memo 40 This Internet-Draft is submitted in full conformance with the 41 provisions of BCP 78 and BCP 79. 43 Internet-Drafts are working documents of the Internet Engineering 44 Task Force (IETF). Note that other groups may also distribute 45 working documents as Internet-Drafts. The list of current Internet- 46 Drafts is at https://datatracker.ietf.org/drafts/current/. 48 Internet-Drafts are draft documents valid for a maximum of six months 49 and may be updated, replaced, or obsoleted by other documents at any 50 time. It is inappropriate to use Internet-Drafts as reference 51 material or to cite them other than as "work in progress." 53 This Internet-Draft will expire on 4 December 2021. 55 Copyright Notice 57 Copyright (c) 2021 IETF Trust and the persons identified as the 58 document authors. All rights reserved. 60 This document is subject to BCP 78 and the IETF Trust's Legal 61 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 62 license-info) in effect on the date of publication of this document. 63 Please review these documents carefully, as they describe your rights 64 and restrictions with respect to this document. Code Components 65 extracted from this document must include Simplified BSD License text 66 as described in Section 4.e of the Trust Legal Provisions and are 67 provided without warranty as described in the Simplified BSD License. 69 This document may contain material from IETF Documents or IETF 70 Contributions published or made publicly available before November 71 10, 2008. The person(s) controlling the copyright in some of this 72 material may not have granted the IETF Trust the right to allow 73 modifications of such material outside the IETF Standards Process. 74 Without obtaining an adequate license from the person(s) controlling 75 the copyright in such materials, this document may not be modified 76 outside the IETF Standards Process, and derivative works of it may 77 not be created outside the IETF Standards Process, except to format 78 it for publication as an RFC or to translate it into languages other 79 than English. 81 Table of Contents 83 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 84 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 5 85 2.1. Conformance Criteria . . . . . . . . . . . . . . . . . . 5 86 2.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 5 87 2.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 88 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 7 89 3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8 90 4. Server Requirements . . . . . . . . . . . . . . . . . . . . . 9 91 4.1. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . 9 92 4.1.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . 9 93 4.1.2. Semantics (Non-Normative) . . . . . . . . . . . . . . 11 94 4.1.3. Cookie Name Prefixes . . . . . . . . . . . . . . . . 14 95 4.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . 16 96 4.2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . 16 97 4.2.2. Semantics . . . . . . . . . . . . . . . . . . . . . . 16 98 5. User Agent Requirements . . . . . . . . . . . . . . . . . . . 16 99 5.1. Subcomponent Algorithms . . . . . . . . . . . . . . . . . 17 100 5.1.1. Dates . . . . . . . . . . . . . . . . . . . . . . . . 17 101 5.1.2. Canonicalized Host Names . . . . . . . . . . . . . . 18 102 5.1.3. Domain Matching . . . . . . . . . . . . . . . . . . . 19 103 5.1.4. Paths and Path-Match . . . . . . . . . . . . . . . . 19 104 5.2. "Same-site" and "cross-site" Requests . . . . . . . . . . 20 105 5.2.1. Document-based requests . . . . . . . . . . . . . . . 21 106 5.2.2. Worker-based requests . . . . . . . . . . . . . . . . 22 107 5.3. Ignoring Set-Cookie Header Fields . . . . . . . . . . . . 23 108 5.4. The Set-Cookie Header Field . . . . . . . . . . . . . . . 23 109 5.4.1. The Expires Attribute . . . . . . . . . . . . . . . . 26 110 5.4.2. The Max-Age Attribute . . . . . . . . . . . . . . . . 26 111 5.4.3. The Domain Attribute . . . . . . . . . . . . . . . . 26 112 5.4.4. The Path Attribute . . . . . . . . . . . . . . . . . 27 113 5.4.5. The Secure Attribute . . . . . . . . . . . . . . . . 27 114 5.4.6. The HttpOnly Attribute . . . . . . . . . . . . . . . 27 115 5.4.7. The SameSite Attribute . . . . . . . . . . . . . . . 28 116 5.5. Storage Model . . . . . . . . . . . . . . . . . . . . . . 30 117 5.6. Retrieval Model . . . . . . . . . . . . . . . . . . . . . 35 118 5.6.1. The Cookie Header Field . . . . . . . . . . . . . . . 35 119 5.6.2. Non-HTTP APIs . . . . . . . . . . . . . . . . . . . . 35 120 5.6.3. Retrieval Algorithm . . . . . . . . . . . . . . . . . 36 121 6. Implementation Considerations . . . . . . . . . . . . . . . . 38 122 6.1. Limits . . . . . . . . . . . . . . . . . . . . . . . . . 38 123 6.2. Application Programming Interfaces . . . . . . . . . . . 38 124 6.3. IDNA Dependency and Migration . . . . . . . . . . . . . . 38 125 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 39 126 7.1. Third-Party Cookies . . . . . . . . . . . . . . . . . . . 39 127 7.2. Cookie policy . . . . . . . . . . . . . . . . . . . . . . 40 128 7.3. User Controls . . . . . . . . . . . . . . . . . . . . . . 40 129 7.4. Expiration Dates . . . . . . . . . . . . . . . . . . . . 40 130 8. Security Considerations . . . . . . . . . . . . . . . . . . . 41 131 8.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 41 132 8.2. Ambient Authority . . . . . . . . . . . . . . . . . . . . 41 133 8.3. Clear Text . . . . . . . . . . . . . . . . . . . . . . . 42 134 8.4. Session Identifiers . . . . . . . . . . . . . . . . . . . 42 135 8.5. Weak Confidentiality . . . . . . . . . . . . . . . . . . 43 136 8.6. Weak Integrity . . . . . . . . . . . . . . . . . . . . . 44 137 8.7. Reliance on DNS . . . . . . . . . . . . . . . . . . . . . 44 138 8.8. SameSite Cookies . . . . . . . . . . . . . . . . . . . . 45 139 8.8.1. Defense in depth . . . . . . . . . . . . . . . . . . 45 140 8.8.2. Top-level Navigations . . . . . . . . . . . . . . . . 45 141 8.8.3. Mashups and Widgets . . . . . . . . . . . . . . . . . 46 142 8.8.4. Server-controlled . . . . . . . . . . . . . . . . . . 46 143 8.8.5. Reload navigations . . . . . . . . . . . . . . . . . 46 144 8.8.6. Top-level requests with "unsafe" methods . . . . . . 47 145 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 146 9.1. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . 48 147 9.2. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . 48 148 9.3. Cookie Attribute Registry . . . . . . . . . . . . . . . . 48 149 9.3.1. Procedure . . . . . . . . . . . . . . . . . . . . . . 48 150 9.3.2. Registration . . . . . . . . . . . . . . . . . . . . 49 151 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 49 152 10.1. Normative References . . . . . . . . . . . . . . . . . . 49 153 10.2. Informative References . . . . . . . . . . . . . . . . . 51 154 Appendix A. Changes . . . . . . . . . . . . . . . . . . . . . . 53 155 A.1. draft-ietf-httpbis-rfc6265bis-00 . . . . . . . . . . . . 53 156 A.2. draft-ietf-httpbis-rfc6265bis-01 . . . . . . . . . . . . 53 157 A.3. draft-ietf-httpbis-rfc6265bis-02 . . . . . . . . . . . . 54 158 A.4. draft-ietf-httpbis-rfc6265bis-03 . . . . . . . . . . . . 54 159 A.5. draft-ietf-httpbis-rfc6265bis-04 . . . . . . . . . . . . 55 160 A.6. draft-ietf-httpbis-rfc6265bis-05 . . . . . . . . . . . . 55 161 A.7. draft-ietf-httpbis-rfc6265bis-06 . . . . . . . . . . . . 55 162 A.8. draft-ietf-httpbis-rfc6265bis-07 . . . . . . . . . . . . 56 163 A.9. draft-ietf-httpbis-rfc6265bis-08 . . . . . . . . . . . . 56 164 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 57 165 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 57 167 1. Introduction 169 This document defines the HTTP Cookie and Set-Cookie header fields. 170 Using the Set-Cookie header field, an HTTP server can pass name/value 171 pairs and associated metadata (called cookies) to a user agent. When 172 the user agent makes subsequent requests to the server, the user 173 agent uses the metadata and other information to determine whether to 174 return the name/value pairs in the Cookie header field. 176 Although simple on their surface, cookies have a number of 177 complexities. For example, the server indicates a scope for each 178 cookie when sending it to the user agent. The scope indicates the 179 maximum amount of time in which the user agent should return the 180 cookie, the servers to which the user agent should return the cookie, 181 and the URI schemes for which the cookie is applicable. 183 For historical reasons, cookies contain a number of security and 184 privacy infelicities. For example, a server can indicate that a 185 given cookie is intended for "secure" connections, but the Secure 186 attribute does not provide integrity in the presence of an active 187 network attacker. Similarly, cookies for a given host are shared 188 across all the ports on that host, even though the usual "same-origin 189 policy" used by web browsers isolates content retrieved via different 190 ports. 192 There are two audiences for this specification: developers of cookie- 193 generating servers and developers of cookie-consuming user agents. 195 To maximize interoperability with user agents, servers SHOULD limit 196 themselves to the well-behaved profile defined in Section 4 when 197 generating cookies. 199 User agents MUST implement the more liberal processing rules defined 200 in Section 5, in order to maximize interoperability with existing 201 servers that do not conform to the well-behaved profile defined in 202 Section 4. 204 This document specifies the syntax and semantics of these header 205 fields as they are actually used on the Internet. In particular, 206 this document does not create new syntax or semantics beyond those in 207 use today. The recommendations for cookie generation provided in 208 Section 4 represent a preferred subset of current server behavior, 209 and even the more liberal cookie processing algorithm provided in 210 Section 5 does not recommend all of the syntactic and semantic 211 variations in use today. Where some existing software differs from 212 the recommended protocol in significant ways, the document contains a 213 note explaining the difference. 215 This document obsoletes [RFC6265]. 217 2. Conventions 219 2.1. Conformance Criteria 221 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 222 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 223 document are to be interpreted as described in [RFC2119]. 225 Requirements phrased in the imperative as part of algorithms (such as 226 "strip any leading space characters" or "return false and abort these 227 steps") are to be interpreted with the meaning of the key word 228 ("MUST", "SHOULD", "MAY", etc.) used in introducing the algorithm. 230 Conformance requirements phrased as algorithms or specific steps can 231 be implemented in any manner, so long as the end result is 232 equivalent. In particular, the algorithms defined in this 233 specification are intended to be easy to understand and are not 234 intended to be performant. 236 2.2. Syntax Notation 238 This specification uses the Augmented Backus-Naur Form (ABNF) 239 notation of [RFC5234]. 241 The following core rules are included by reference, as defined in 242 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 243 (CR LF), CTLs (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 244 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), NUL (null octet), 245 OCTET (any 8-bit sequence of data except NUL), SP (space), HTAB 246 (horizontal tab), CHAR (any [USASCII] character), VCHAR (any visible 247 [USASCII] character), and WSP (whitespace). 249 The OWS (optional whitespace) and BWS (bad whitespace) rules are 250 defined in Section 5.6.3 of [HTTPSEM]. 252 2.3. Terminology 254 The terms "user agent", "client", "server", "proxy", and "origin 255 server" have the same meaning as in the HTTP/1.1 specification 256 ([HTTPSEM], Section 3). 258 The request-host is the name of the host, as known by the user agent, 259 to which the user agent is sending an HTTP request or from which it 260 is receiving an HTTP response (i.e., the name of the host to which it 261 sent the corresponding HTTP request). 263 The term request-uri refers to "target URI" as defined in Section 7.1 264 of [HTTPSEM]. 266 Two sequences of octets are said to case-insensitively match each 267 other if and only if they are equivalent under the i;ascii-casemap 268 collation defined in [RFC4790]. 270 The term string means a sequence of non-NUL octets. 272 The terms "active document", "ancestor browsing context", "browsing 273 context", "dedicated worker", "Document", "nested browsing context", 274 "opaque origin", "parent browsing context", "sandboxed origin 275 browsing context flag", "shared worker", "the worker's Documents", 276 "top-level browsing context", and "WorkerGlobalScope" are defined in 277 [HTML]. 279 "Service Workers" are defined in the Service Workers specification 280 [SERVICE-WORKERS]. 282 The term "origin", the mechanism of deriving an origin from a URI, 283 and the "the same" matching algorithm for origins are defined in 284 [RFC6454]. 286 "Safe" HTTP methods include "GET", "HEAD", "OPTIONS", and "TRACE", as 287 defined in Section 9.2.1 of [HTTPSEM]. 289 A domain's "public suffix" is the portion of a domain that is 290 controlled by a public registry, such as "com", "co.uk", and 291 "pvt.k12.wy.us". A domain's "registrable domain" is the domain's 292 public suffix plus the label to its left. That is, for 293 "https://www.site.example", the public suffix is "example", and the 294 registrable domain is "site.example". Whenever possible, user agents 295 SHOULD use an up-to-date public suffix list, such as the one 296 maintained by the Mozilla project at [PSL]. 298 The term "request", as well as a request's "client", "current url", 299 "method", "target browsing context", and "url list", are defined in 300 [FETCH]. 302 The term "non-HTTP APIs" refers to non-HTTP mechanisms used to set 303 and retrieve cookies, such as a web browser API that exposes cookies 304 to scripts. 306 3. Overview 308 This section outlines a way for an origin server to send state 309 information to a user agent and for the user agent to return the 310 state information to the origin server. 312 To store state, the origin server includes a Set-Cookie header field 313 in an HTTP response. In subsequent requests, the user agent returns 314 a Cookie request header field to the origin server. The Cookie 315 header field contains cookies the user agent received in previous 316 Set-Cookie header fields. The origin server is free to ignore the 317 Cookie header field or use its contents for an application-defined 318 purpose. 320 Origin servers MAY send a Set-Cookie response header field with any 321 response. An origin server can include multiple Set-Cookie header 322 fields in a single response. The presence of a Cookie or a Set- 323 Cookie header field does not preclude HTTP caches from storing and 324 reusing a response. 326 Origin servers SHOULD NOT fold multiple Set-Cookie header fields into 327 a single header field. The usual mechanism for folding HTTP headers 328 fields (i.e., as defined in Section 5.3 of [HTTPSEM]) might change 329 the semantics of the Set-Cookie header field because the %x2C (",") 330 character is used by Set-Cookie in a way that conflicts with such 331 folding. 333 User agents MAY ignore Set-Cookie header fieldss based on response 334 status codes or the user agent's cookie policy (see Section 5.3). 336 3.1. Examples 338 Using the Set-Cookie header field, a server can send the user agent a 339 short string in an HTTP response that the user agent will return in 340 future HTTP requests that are within the scope of the cookie. For 341 example, the server can send the user agent a "session identifier" 342 named SID with the value 31d4d96e407aad42. The user agent then 343 returns the session identifier in subsequent requests. 345 == Server -> User Agent == 347 Set-Cookie: SID=31d4d96e407aad42 349 == User Agent -> Server == 351 Cookie: SID=31d4d96e407aad42 353 The server can alter the default scope of the cookie using the Path 354 and Domain attributes. For example, the server can instruct the user 355 agent to return the cookie to every path and every subdomain of 356 site.example. 358 == Server -> User Agent == 360 Set-Cookie: SID=31d4d96e407aad42; Path=/; Domain=site.example 362 == User Agent -> Server == 364 Cookie: SID=31d4d96e407aad42 366 As shown in the next example, the server can store multiple cookies 367 at the user agent. For example, the server can store a session 368 identifier as well as the user's preferred language by returning two 369 Set-Cookie header fields. Notice that the server uses the Secure and 370 HttpOnly attributes to provide additional security protections for 371 the more sensitive session identifier (see Section 4.1.2). 373 == Server -> User Agent == 375 Set-Cookie: SID=31d4d96e407aad42; Path=/; Secure; HttpOnly 376 Set-Cookie: lang=en-US; Path=/; Domain=site.example 378 == User Agent -> Server == 380 Cookie: SID=31d4d96e407aad42; lang=en-US 381 Notice that the Cookie header field above contains two cookies, one 382 named SID and one named lang. If the server wishes the user agent to 383 persist the cookie over multiple "sessions" (e.g., user agent 384 restarts), the server can specify an expiration date in the Expires 385 attribute. Note that the user agent might delete the cookie before 386 the expiration date if the user agent's cookie store exceeds its 387 quota or if the user manually deletes the server's cookie. 389 == Server -> User Agent == 391 Set-Cookie: lang=en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT 393 == User Agent -> Server == 395 Cookie: SID=31d4d96e407aad42; lang=en-US 397 Finally, to remove a cookie, the server returns a Set-Cookie header 398 field with an expiration date in the past. The server will be 399 successful in removing the cookie only if the Path and the Domain 400 attribute in the Set-Cookie header field match the values used when 401 the cookie was created. 403 == Server -> User Agent == 405 Set-Cookie: lang=; Expires=Sun, 06 Nov 1994 08:49:37 GMT 407 == User Agent -> Server == 409 Cookie: SID=31d4d96e407aad42 411 4. Server Requirements 413 This section describes the syntax and semantics of a well-behaved 414 profile of the Cookie and Set-Cookie header fields. 416 4.1. Set-Cookie 418 The Set-Cookie HTTP response header field is used to send cookies 419 from the server to the user agent. 421 4.1.1. Syntax 423 Informally, the Set-Cookie response header field contains a cookie, 424 which begins with a name-value-pair, followed by zero or more 425 attribute-value pairs. Servers SHOULD NOT send Set-Cookie header 426 fields that fail to conform to the following grammar: 428 set-cookie = set-cookie-string 429 set-cookie-string = BWS cookie-pair *( BWS ";" OWS cookie-av ) 430 cookie-pair = cookie-name BWS "=" BWS cookie-value 431 cookie-name = 1*cookie-octet 432 cookie-value = *cookie-octet / ( DQUOTE *cookie-octet DQUOTE ) 433 cookie-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E 434 / %x80-FF 435 ; octets excluding CTLs, 436 ; whitespace DQUOTE, comma, semicolon, 437 ; and backslash 439 cookie-av = expires-av / max-age-av / domain-av / 440 path-av / secure-av / httponly-av / 441 samesite-av / extension-av 442 expires-av = "Expires" BWS "=" BWS sane-cookie-date 443 sane-cookie-date = 444 445 max-age-av = "Max-Age" BWS "=" BWS non-zero-digit *DIGIT 446 ; In practice, both expires-av and max-age-av 447 ; are limited to dates representable by the 448 ; user agent. 449 non-zero-digit = %x31-39 450 ; digits 1 through 9 451 domain-av = "Domain" BWS "=" BWS domain-value 452 domain-value = 453 ; defined in [RFC1034], Section 3.5, as 454 ; enhanced by [RFC1123], Section 2.1 455 path-av = "Path" BWS "=" BWS path-value 456 path-value = *av-octet 457 secure-av = "Secure" 458 httponly-av = "HttpOnly" 459 samesite-av = "SameSite" BWS "=" BWS samesite-value 460 samesite-value = "Strict" / "Lax" / "None" 461 extension-av = *av-octet 462 av-octet = %x20-3A / %x3C-7E 463 ; any CHAR except CTLs or ";" 465 Note that some of the grammatical terms above reference documents 466 that use different grammatical notations than this document (which 467 uses ABNF from [RFC5234]). 469 The semantics of the cookie-value are not defined by this document. 471 To maximize compatibility with user agents, servers that wish to 472 store arbitrary data in a cookie-value SHOULD encode that data, for 473 example, using Base64 [RFC4648]. 475 Per the grammar above, the cookie-value MAY be wrapped in DQUOTE 476 characters. Note that in this case, the initial and trailing DQUOTE 477 characters are not stripped. They are part of the cookie-value, and 478 will be included in Cookie header fields sent to the server. 480 The portions of the set-cookie-string produced by the cookie-av term 481 are known as attributes. To maximize compatibility with user agents, 482 servers SHOULD NOT produce two attributes with the same name in the 483 same set-cookie-string. (See Section 5.5 for how user agents handle 484 this case.) 486 Servers SHOULD NOT include more than one Set-Cookie header field in 487 the same response with the same cookie-name. (See Section 5.4 for 488 how user agents handle this case.) 490 If a server sends multiple responses containing Set-Cookie header 491 fields concurrently to the user agent (e.g., when communicating with 492 the user agent over multiple sockets), these responses create a "race 493 condition" that can lead to unpredictable behavior. 495 NOTE: Some existing user agents differ in their interpretation of 496 two-digit years. To avoid compatibility issues, servers SHOULD use 497 the rfc1123-date format, which requires a four-digit year. 499 NOTE: Some user agents store and process dates in cookies as 32-bit 500 UNIX time_t values. Implementation bugs in the libraries supporting 501 time_t processing on some systems might cause such user agents to 502 process dates after the year 2038 incorrectly. 504 4.1.2. Semantics (Non-Normative) 506 This section describes simplified semantics of the Set-Cookie header 507 field. These semantics are detailed enough to be useful for 508 understanding the most common uses of cookies by servers. The full 509 semantics are described in Section 5. 511 When the user agent receives a Set-Cookie header field, the user 512 agent stores the cookie together with its attributes. Subsequently, 513 when the user agent makes an HTTP request, the user agent includes 514 the applicable, non-expired cookies in the Cookie header field. 516 If the user agent receives a new cookie with the same cookie-name, 517 domain-value, and path-value as a cookie that it has already stored, 518 the existing cookie is evicted and replaced with the new cookie. 519 Notice that servers can delete cookies by sending the user agent a 520 new cookie with an Expires attribute with a value in the past. 522 Unless the cookie's attributes indicate otherwise, the cookie is 523 returned only to the origin server (and not, for example, to any 524 subdomains), and it expires at the end of the current session (as 525 defined by the user agent). User agents ignore unrecognized cookie 526 attributes (but not the entire cookie). 528 4.1.2.1. The Expires Attribute 530 The Expires attribute indicates the maximum lifetime of the cookie, 531 represented as the date and time at which the cookie expires. The 532 user agent is not required to retain the cookie until the specified 533 date has passed. In fact, user agents often evict cookies due to 534 memory pressure or privacy concerns. 536 4.1.2.2. The Max-Age Attribute 538 The Max-Age attribute indicates the maximum lifetime of the cookie, 539 represented as the number of seconds until the cookie expires. The 540 user agent is not required to retain the cookie for the specified 541 duration. In fact, user agents often evict cookies due to memory 542 pressure or privacy concerns. 544 NOTE: Some existing user agents do not support the Max-Age attribute. 545 User agents that do not support the Max-Age attribute ignore the 546 attribute. 548 If a cookie has both the Max-Age and the Expires attribute, the Max- 549 Age attribute has precedence and controls the expiration date of the 550 cookie. If a cookie has neither the Max-Age nor the Expires 551 attribute, the user agent will retain the cookie until "the current 552 session is over" (as defined by the user agent). 554 4.1.2.3. The Domain Attribute 556 The Domain attribute specifies those hosts to which the cookie will 557 be sent. For example, if the value of the Domain attribute is 558 "site.example", the user agent will include the cookie in the Cookie 559 header field when making HTTP requests to site.example, 560 www.site.example, and www.corp.site.example. (Note that a leading 561 %x2E ("."), if present, is ignored even though that character is not 562 permitted, but a trailing %x2E ("."), if present, will cause the user 563 agent to ignore the attribute.) If the server omits the Domain 564 attribute, the user agent will return the cookie only to the origin 565 server. 567 WARNING: Some existing user agents treat an absent Domain attribute 568 as if the Domain attribute were present and contained the current 569 host name. For example, if site.example returns a Set-Cookie header 570 field without a Domain attribute, these user agents will erroneously 571 send the cookie to www.site.example as well. 573 The user agent will reject cookies unless the Domain attribute 574 specifies a scope for the cookie that would include the origin 575 server. For example, the user agent will accept a cookie with a 576 Domain attribute of "site.example" or of "foo.site.example" from 577 foo.site.example, but the user agent will not accept a cookie with a 578 Domain attribute of "bar.site.example" or of "baz.foo.site.example". 580 NOTE: For security reasons, many user agents are configured to reject 581 Domain attributes that correspond to "public suffixes". For example, 582 some user agents will reject Domain attributes of "com" or "co.uk". 583 (See Section 5.5 for more information.) 585 4.1.2.4. The Path Attribute 587 The scope of each cookie is limited to a set of paths, controlled by 588 the Path attribute. If the server omits the Path attribute, the user 589 agent will use the "directory" of the request-uri's path component as 590 the default value. (See Section 5.1.4 for more details.) 592 The user agent will include the cookie in an HTTP request only if the 593 path portion of the request-uri matches (or is a subdirectory of) the 594 cookie's Path attribute, where the %x2F ("/") character is 595 interpreted as a directory separator. 597 Although seemingly useful for isolating cookies between different 598 paths within a given host, the Path attribute cannot be relied upon 599 for security (see Section 8). 601 4.1.2.5. The Secure Attribute 603 The Secure attribute limits the scope of the cookie to "secure" 604 channels (where "secure" is defined by the user agent). When a 605 cookie has the Secure attribute, the user agent will include the 606 cookie in an HTTP request only if the request is transmitted over a 607 secure channel (typically HTTP over Transport Layer Security (TLS) 608 [RFC2818]). 610 Although seemingly useful for protecting cookies from active network 611 attackers, the Secure attribute protects only the cookie's 612 confidentiality. An active network attacker can overwrite Secure 613 cookies from an insecure channel, disrupting their integrity (see 614 Section 8.6 for more details). 616 4.1.2.6. The HttpOnly Attribute 618 The HttpOnly attribute limits the scope of the cookie to HTTP 619 requests. In particular, the attribute instructs the user agent to 620 omit the cookie when providing access to cookies via non-HTTP APIs. 622 Note that the HttpOnly attribute is independent of the Secure 623 attribute: a cookie can have both the HttpOnly and the Secure 624 attribute. 626 4.1.2.7. The SameSite Attribute 628 The "SameSite" attribute limits the scope of the cookie such that it 629 will only be attached to requests if those requests are same-site, as 630 defined by the algorithm in Section 5.2. For example, requests for 631 "https://site.example/sekrit-image" will attach same-site cookies if 632 and only if initiated from a context whose "site for cookies" is an 633 origin with a scheme and registered domain of "https" and 634 "site.example" respectively. 636 If the "SameSite" attribute's value is "Strict", the cookie will only 637 be sent along with "same-site" requests. If the value is "Lax", the 638 cookie will be sent with same-site requests, and with "cross-site" 639 top-level navigations, as described in Section 5.4.7.1. If the value 640 is "None", the cookie will be sent with same-site and cross-site 641 requests. If the "SameSite" attribute's value is something other 642 than these three known keywords, the attribute's value will be 643 subject to a default enforcement mode that is equivalent to "Lax". 645 The "SameSite" attribute affects cookie creation as well as delivery. 646 Cookies which assert "SameSite=Lax" or "SameSite=Strict" cannot be 647 set in responses to cross-site subresource requests, or cross-site 648 nested navigations. They can be set along with any top-level 649 navigation, cross-site or otherwise. 651 4.1.3. Cookie Name Prefixes 653 Section 8.5 and Section 8.6 of this document spell out some of the 654 drawbacks of cookies' historical implementation. In particular, it 655 is impossible for a server to have confidence that a given cookie was 656 set with a particular set of attributes. In order to provide such 657 confidence in a backwards-compatible way, two common sets of 658 requirements can be inferred from the first few characters of the 659 cookie's name. 661 The normative requirements for the prefixes described below are 662 detailed in the storage model algorithm defined in Section 5.5. 664 4.1.3.1. The "__Secure-" Prefix 666 If a cookie's name begins with a case-sensitive match for the string 667 "__Secure-", then the cookie will have been set with a "Secure" 668 attribute. 670 For example, the following "Set-Cookie" header field would be 671 rejected by a conformant user agent, as it does not have a "Secure" 672 attribute. 674 Set-Cookie: __Secure-SID=12345; Domain=site.example 676 Whereas the following "Set-Cookie" header field would be accepted: 678 Set-Cookie: __Secure-SID=12345; Domain=site.example; Secure 680 4.1.3.2. The "__Host-" Prefix 682 If a cookie's name begins with a case-sensitive match for the string 683 "__Host-", then the cookie will have been set with a "Secure" 684 attribute, a "Path" attribute with a value of "/", and no "Domain" 685 attribute. 687 This combination yields a cookie that hews as closely as a cookie can 688 to treating the origin as a security boundary. The lack of a 689 "Domain" attribute ensures that the cookie's "host-only-flag" is 690 true, locking the cookie to a particular host, rather than allowing 691 it to span subdomains. Setting the "Path" to "/" means that the 692 cookie is effective for the entire host, and won't be overridden for 693 specific paths. The "Secure" attribute ensures that the cookie is 694 unaltered by non-secure origins, and won't span protocols. 696 Ports are the only piece of the origin model that "__Host-" cookies 697 continue to ignore. 699 For example, the following cookies would always be rejected: 701 Set-Cookie: __Host-SID=12345 702 Set-Cookie: __Host-SID=12345; Secure 703 Set-Cookie: __Host-SID=12345; Domain=site.example 704 Set-Cookie: __Host-SID=12345; Domain=site.example; Path=/ 705 Set-Cookie: __Host-SID=12345; Secure; Domain=site.example; Path=/ 707 While the following would be accepted if set from a secure origin 708 (e.g. "https://site.example/"), and rejected otherwise: 710 Set-Cookie: __Host-SID=12345; Secure; Path=/ 712 4.2. Cookie 714 4.2.1. Syntax 716 The user agent sends stored cookies to the origin server in the 717 Cookie header field. If the server conforms to the requirements in 718 Section 4.1 (and the user agent conforms to the requirements in 719 Section 5), the user agent will send a Cookie header field that 720 conforms to the following grammar: 722 cookie = cookie-string 723 cookie-string = cookie-pair *( ";" SP cookie-pair ) 725 4.2.2. Semantics 727 Each cookie-pair represents a cookie stored by the user agent. The 728 cookie-pair contains the cookie-name and cookie-value the user agent 729 received in the Set-Cookie header field. 731 Notice that the cookie attributes are not returned. In particular, 732 the server cannot determine from the Cookie field alone when a cookie 733 will expire, for which hosts the cookie is valid, for which paths the 734 cookie is valid, or whether the cookie was set with the Secure or 735 HttpOnly attributes. 737 The semantics of individual cookies in the Cookie header field are 738 not defined by this document. Servers are expected to imbue these 739 cookies with application-specific semantics. 741 Although cookies are serialized linearly in the Cookie header field, 742 servers SHOULD NOT rely upon the serialization order. In particular, 743 if the Cookie header field contains two cookies with the same name 744 (e.g., that were set with different Path or Domain attributes), 745 servers SHOULD NOT rely upon the order in which these cookies appear 746 in the header field. 748 5. User Agent Requirements 750 This section specifies the Cookie and Set-Cookie header fields in 751 sufficient detail that a user agent implementing these requirements 752 precisely can interoperate with existing servers (even those that do 753 not conform to the well-behaved profile described in Section 4). 755 A user agent could enforce more restrictions than those specified 756 herein (e.g., restrictions specified by its cookie policy, described 757 in Section 7.2). However, such additional restrictions may reduce 758 the likelihood that a user agent will be able to interoperate with 759 existing servers. 761 5.1. Subcomponent Algorithms 763 This section defines some algorithms used by user agents to process 764 specific subcomponents of the Cookie and Set-Cookie header fields. 766 5.1.1. Dates 768 The user agent MUST use an algorithm equivalent to the following 769 algorithm to parse a cookie-date. Note that the various boolean 770 flags defined as a part of the algorithm (i.e., found-time, found- 771 day-of-month, found-month, found-year) are initially "not set". 773 1. Using the grammar below, divide the cookie-date into date-tokens. 775 cookie-date = *delimiter date-token-list *delimiter 776 date-token-list = date-token *( 1*delimiter date-token ) 777 date-token = 1*non-delimiter 779 delimiter = %x09 / %x20-2F / %x3B-40 / %x5B-60 / %x7B-7E 780 non-delimiter = %x00-08 / %x0A-1F / DIGIT / ":" / ALPHA / %x7F-FF 781 non-digit = %x00-2F / %x3A-FF 783 day-of-month = 1*2DIGIT [ non-digit *OCTET ] 784 month = ( "jan" / "feb" / "mar" / "apr" / 785 "may" / "jun" / "jul" / "aug" / 786 "sep" / "oct" / "nov" / "dec" ) *OCTET 787 year = 2*4DIGIT [ non-digit *OCTET ] 788 time = hms-time [ non-digit *OCTET ] 789 hms-time = time-field ":" time-field ":" time-field 790 time-field = 1*2DIGIT 792 2. Process each date-token sequentially in the order the date-tokens 793 appear in the cookie-date: 795 1. If the found-time flag is not set and the token matches the 796 time production, set the found-time flag and set the hour- 797 value, minute-value, and second-value to the numbers denoted 798 by the digits in the date-token, respectively. Skip the 799 remaining sub-steps and continue to the next date-token. 801 2. If the found-day-of-month flag is not set and the date-token 802 matches the day-of-month production, set the found-day-of- 803 month flag and set the day-of-month-value to the number 804 denoted by the date-token. Skip the remaining sub-steps and 805 continue to the next date-token. 807 3. If the found-month flag is not set and the date-token matches 808 the month production, set the found-month flag and set the 809 month-value to the month denoted by the date-token. Skip the 810 remaining sub-steps and continue to the next date-token. 812 4. If the found-year flag is not set and the date-token matches 813 the year production, set the found-year flag and set the 814 year-value to the number denoted by the date-token. Skip the 815 remaining sub-steps and continue to the next date-token. 817 3. If the year-value is greater than or equal to 70 and less than or 818 equal to 99, increment the year-value by 1900. 820 4. If the year-value is greater than or equal to 0 and less than or 821 equal to 69, increment the year-value by 2000. 823 1. NOTE: Some existing user agents interpret two-digit years 824 differently. 826 5. Abort these steps and fail to parse the cookie-date if: 828 * at least one of the found-day-of-month, found-month, found- 829 year, or found-time flags is not set, 831 * the day-of-month-value is less than 1 or greater than 31, 833 * the year-value is less than 1601, 835 * the hour-value is greater than 23, 837 * the minute-value is greater than 59, or 839 * the second-value is greater than 59. 841 (Note that leap seconds cannot be represented in this syntax.) 843 6. Let the parsed-cookie-date be the date whose day-of-month, month, 844 year, hour, minute, and second (in UTC) are the day-of-month- 845 value, the month-value, the year-value, the hour-value, the 846 minute-value, and the second-value, respectively. If no such 847 date exists, abort these steps and fail to parse the cookie-date. 849 7. Return the parsed-cookie-date as the result of this algorithm. 851 5.1.2. Canonicalized Host Names 853 A canonicalized host name is the string generated by the following 854 algorithm: 856 1. Convert the host name to a sequence of individual domain name 857 labels. 859 2. Convert each label that is not a Non-Reserved LDH (NR-LDH) label, 860 to an A-label (see Section 2.3.2.1 of [RFC5890] for the former 861 and latter), or to a "punycode label" (a label resulting from the 862 "ToASCII" conversion in Section 4 of [RFC3490]), as appropriate 863 (see Section 6.3 of this specification). 865 3. Concatenate the resulting labels, separated by a %x2E (".") 866 character. 868 5.1.3. Domain Matching 870 A string domain-matches a given domain string if at least one of the 871 following conditions hold: 873 * The domain string and the string are identical. (Note that both 874 the domain string and the string will have been canonicalized to 875 lower case at this point.) 877 * All of the following conditions hold: 879 - The domain string is a suffix of the string. 881 - The last character of the string that is not included in the 882 domain string is a %x2E (".") character. 884 - The string is a host name (i.e., not an IP address). 886 5.1.4. Paths and Path-Match 888 The user agent MUST use an algorithm equivalent to the following 889 algorithm to compute the default-path of a cookie: 891 1. Let uri-path be the path portion of the request-uri if such a 892 portion exists (and empty otherwise). 894 2. If the uri-path is empty or if the first character of the uri- 895 path is not a %x2F ("/") character, output %x2F ("/") and skip 896 the remaining steps. 898 3. If the uri-path contains no more than one %x2F ("/") character, 899 output %x2F ("/") and skip the remaining step. 901 4. Output the characters of the uri-path from the first character up 902 to, but not including, the right-most %x2F ("/"). 904 A request-path path-matches a given cookie-path if at least one of 905 the following conditions holds: 907 * The cookie-path and the request-path are identical. 909 Note that this differs from the rules in [RFC3986] for equivalence 910 of the path component, and hence two equivalent paths can have 911 different cookies. 913 * The cookie-path is a prefix of the request-path, and the last 914 character of the cookie-path is %x2F ("/"). 916 * The cookie-path is a prefix of the request-path, and the first 917 character of the request-path that is not included in the cookie- 918 path is a %x2F ("/") character. 920 5.2. "Same-site" and "cross-site" Requests 922 Two origins are same-site if they satisfy the "same site" criteria 923 defined in [SAMESITE]. A request is "same-site" if the following 924 criteria are true: 926 1. The request is not the result of a cross-site redirect. That is, 927 the origin of every url in the request's url list is same-site 928 with the request's current url's origin. 930 2. The request is not the result of a reload navigation triggered 931 through a user interface element (as defined by the user agent; 932 e.g., a request triggered by the user clicking a refresh button 933 on a toolbar). 935 3. The request's current url's origin is same-site with the 936 request's client's "site for cookies" (which is an origin), or if 937 the request has no client or the request's client is null. 939 Requests which are the result of a reload navigation triggered 940 through a user interface element are same-site if the reloaded 941 document was originally navigated to via a same-site request. A 942 request that is not "same-site" is instead "cross-site". 944 The request's client's "site for cookies" is calculated depending 945 upon its client's type, as described in the following subsections: 947 5.2.1. Document-based requests 949 The URI displayed in a user agent's address bar is the only security 950 context directly exposed to users, and therefore the only signal 951 users can reasonably rely upon to determine whether or not they trust 952 a particular website. The origin of that URI represents the context 953 in which a user most likely believes themselves to be interacting. 954 We'll define this origin, the top-level browsing context's active 955 document's origin, as the "top-level origin". 957 For a document displayed in a top-level browsing context, we can stop 958 here: the document's "site for cookies" is the top-level origin. 960 For documents which are displayed in nested browsing contexts, we 961 need to audit the origins of each of a document's ancestor browsing 962 contexts' active documents in order to account for the "multiple- 963 nested scenarios" described in Section 4 of [RFC7034]. A document's 964 "site for cookies" is the top-level origin if and only if the top- 965 level origin is same-site with the document's origin, and with each 966 of the document's ancestor documents' origins. Otherwise its "site 967 for cookies" is an origin set to an opaque origin. 969 Given a Document ("document"), the following algorithm returns its 970 "site for cookies": 972 1. Let "top-document" be the active document in "document"'s 973 browsing context's top-level browsing context. 975 2. Let "top-origin" be the origin of "top-document"'s URI if "top- 976 document"'s sandboxed origin browsing context flag is set, and 977 "top-document"'s origin otherwise. 979 3. Let "documents" be a list containing "document" and each of 980 "document"'s ancestor browsing contexts' active documents. 982 4. For each "item" in "documents": 984 1. Let "origin" be the origin of "item"'s URI if "item"'s 985 sandboxed origin browsing context flag is set, and "item"'s 986 origin otherwise. 988 2. If "origin" is not same-site with "top-origin", return an 989 origin set to an opaque origin. 991 5. Return "top-origin". 993 5.2.2. Worker-based requests 995 Worker-driven requests aren't as clear-cut as document-driven 996 requests, as there isn't a clear link between a top-level browsing 997 context and a worker. This is especially true for Service Workers 998 [SERVICE-WORKERS], which may execute code in the background, without 999 any document visible at all. 1001 Note: The descriptions below assume that workers must be same-origin 1002 with the documents that instantiate them. If this invariant changes, 1003 we'll need to take the worker's script's URI into account when 1004 determining their status. 1006 5.2.2.1. Dedicated and Shared Workers 1008 Dedicated workers are simple, as each dedicated worker is bound to 1009 one and only one document. Requests generated from a dedicated 1010 worker (via "importScripts", "XMLHttpRequest", "fetch()", etc) define 1011 their "site for cookies" as that document's "site for cookies". 1013 Shared workers may be bound to multiple documents at once. As it is 1014 quite possible for those documents to have distinct "site for 1015 cookies" values, the worker's "site for cookies" will be an origin 1016 set to an opaque origin in cases where the values are not all same- 1017 site with the worker's origin, and the worker's origin in cases where 1018 the values agree. 1020 Given a WorkerGlobalScope ("worker"), the following algorithm returns 1021 its "site for cookies": 1023 1. Let "site" be "worker"'s origin. 1025 2. For each "document" in "worker"'s Documents: 1027 1. Let "document-site" be "document"'s "site for cookies" (as 1028 defined in Section 5.2.1). 1030 2. If "document-site" is not same-site with "site", return an 1031 origin set to an opaque origin. 1033 3. Return "site". 1035 5.2.2.2. Service Workers 1037 Service Workers are more complicated, as they act as a completely 1038 separate execution context with only tangential relationship to the 1039 Document which registered them. 1041 Requests which simply pass through a Service Worker will be handled 1042 as described above: the request's client will be the Document or 1043 Worker which initiated the request, and its "site for cookies" will 1044 be those defined in Section 5.2.1 and Section 5.2.2.1 1046 Requests which are initiated by the Service Worker itself (via a 1047 direct call to "fetch()", for instance), on the other hand, will have 1048 a client which is a ServiceWorkerGlobalScope. Its "site for cookies" 1049 will be the Service Worker's URI's origin. 1051 Given a ServiceWorkerGlobalScope ("worker"), the following algorithm 1052 returns its "site for cookies": 1054 1. Return "worker"'s origin. 1056 5.3. Ignoring Set-Cookie Header Fields 1058 User agents MAY ignore Set-Cookie header fields contained in 1059 responses with 100-level status codes or based on its cookie policy 1060 (see Section 7.2). 1062 All other Set-Cookie header fields SHOULD be processed according to 1063 Section 5.4. That is, Set-Cookie header fields contained in 1064 responses with non-100-level status codes (including those in 1065 responses with 400- and 500-level status codes) SHOULD be processed 1066 unless ignored according to the user agent's cookie policy. 1068 5.4. The Set-Cookie Header Field 1070 When a user agent receives a Set-Cookie header field in an HTTP 1071 response, the user agent MAY ignore the Set-Cookie header field in 1072 its entirety (see Section 5.3). 1074 If the user agent does not ignore the Set-Cookie header field in its 1075 entirety, the user agent MUST parse the field-value of the Set-Cookie 1076 header field as a set-cookie-string (defined below). 1078 NOTE: The algorithm below is more permissive than the grammar in 1079 Section 4.1. For example, the algorithm strips leading and trailing 1080 whitespace from the cookie name and value (but maintains internal 1081 whitespace), whereas the grammar in Section 4.1 forbids whitespace in 1082 these positions. In addition, the algorithm below accommodates some 1083 characters that are not cookie-octets according to the grammar in 1084 Section 4.1. User agents use this algorithm so as to interoperate 1085 with servers that do not follow the recommendations in Section 4. 1087 NOTE: As set-cookie-string may originate from a non-HTTP API, it is 1088 not guaranteed to be free of CTL characters, so this algorithm 1089 handles them explicitly. 1091 A user agent MUST use an algorithm equivalent to the following 1092 algorithm to parse a set-cookie-string: 1094 1. If the set-cookie-string contains a %x0D (CR), %x0A (LF), or %x00 1095 (NUL) octet, then set the set-cookie-string equal to all the 1096 characters of set-cookie-string up to, but not including, the 1097 first such octet. 1099 2. If the set-cookie-string contains a %x00-1F / %x7F (CTL) 1100 character: Abort these steps and ignore the set-cookie-string 1101 entirely. 1103 3. If the set-cookie-string contains a %x3B (";") character: 1105 1. The name-value-pair string consists of the characters up to, 1106 but not including, the first %x3B (";"), and the unparsed- 1107 attributes consist of the remainder of the set-cookie-string 1108 (including the %x3B (";") in question). 1110 Otherwise: 1112 1. The name-value-pair string consists of all the characters 1113 contained in the set-cookie-string, and the unparsed- 1114 attributes is the empty string. 1116 4. If the name-value-pair string lacks a %x3D ("=") character, then 1117 the name string is empty, and the value string is the value of 1118 name-value-pair. 1120 Otherwise, the name string consists of the characters up to, but 1121 not including, the first %x3D ("=") character, and the (possibly 1122 empty) value string consists of the characters after the first 1123 %x3D ("=") character. 1125 5. Remove any leading or trailing WSP characters from the name 1126 string and the value string. 1128 6. The cookie-name is the name string, and the cookie-value is the 1129 value string. 1131 The user agent MUST use an algorithm equivalent to the following 1132 algorithm to parse the unparsed-attributes: 1134 1. If the unparsed-attributes string is empty, skip the rest of 1135 these steps. 1137 2. Discard the first character of the unparsed-attributes (which 1138 will be a %x3B (";") character). 1140 3. If the remaining unparsed-attributes contains a %x3B (";") 1141 character: 1143 1. Consume the characters of the unparsed-attributes up to, but 1144 not including, the first %x3B (";") character. 1146 Otherwise: 1148 1. Consume the remainder of the unparsed-attributes. 1150 Let the cookie-av string be the characters consumed in this step. 1152 4. If the cookie-av string contains a %x3D ("=") character: 1154 1. The (possibly empty) attribute-name string consists of the 1155 characters up to, but not including, the first %x3D ("=") 1156 character, and the (possibly empty) attribute-value string 1157 consists of the characters after the first %x3D ("=") 1158 character. 1160 Otherwise: 1162 1. The attribute-name string consists of the entire cookie-av 1163 string, and the attribute-value string is empty. 1165 5. Remove any leading or trailing WSP characters from the attribute- 1166 name string and the attribute-value string. 1168 6. Process the attribute-name and attribute-value according to the 1169 requirements in the following subsections. (Notice that 1170 attributes with unrecognized attribute-names are ignored.) 1172 7. Return to Step 1 of this algorithm. 1174 When the user agent finishes parsing the set-cookie-string, the user 1175 agent is said to "receive a cookie" from the request-uri with name 1176 cookie-name, value cookie-value, and attributes cookie-attribute- 1177 list. (See Section 5.5 for additional requirements triggered by 1178 receiving a cookie.) 1180 5.4.1. The Expires Attribute 1182 If the attribute-name case-insensitively matches the string 1183 "Expires", the user agent MUST process the cookie-av as follows. 1185 1. Let the expiry-time be the result of parsing the attribute-value 1186 as cookie-date (see Section 5.1.1). 1188 2. If the attribute-value failed to parse as a cookie date, ignore 1189 the cookie-av. 1191 3. If the expiry-time is later than the last date the user agent can 1192 represent, the user agent MAY replace the expiry-time with the 1193 last representable date. 1195 4. If the expiry-time is earlier than the earliest date the user 1196 agent can represent, the user agent MAY replace the expiry-time 1197 with the earliest representable date. 1199 5. Append an attribute to the cookie-attribute-list with an 1200 attribute-name of Expires and an attribute-value of expiry-time. 1202 5.4.2. The Max-Age Attribute 1204 If the attribute-name case-insensitively matches the string "Max- 1205 Age", the user agent MUST process the cookie-av as follows. 1207 1. If the first character of the attribute-value is not a DIGIT or a 1208 "-" character, ignore the cookie-av. 1210 2. If the remainder of attribute-value contains a non-DIGIT 1211 character, ignore the cookie-av. 1213 3. Let delta-seconds be the attribute-value converted to an integer. 1215 4. If delta-seconds is less than or equal to zero (0), let expiry- 1216 time be the earliest representable date and time. Otherwise, let 1217 the expiry-time be the current date and time plus delta-seconds 1218 seconds. 1220 5. Append an attribute to the cookie-attribute-list with an 1221 attribute-name of Max-Age and an attribute-value of expiry-time. 1223 5.4.3. The Domain Attribute 1225 If the attribute-name case-insensitively matches the string "Domain", 1226 the user agent MUST process the cookie-av as follows. 1228 1. If the attribute-value is empty, the behavior is undefined. 1229 However, the user agent SHOULD ignore the cookie-av entirely. 1231 2. If the first character of the attribute-value string is %x2E 1232 ("."): 1234 1. Let cookie-domain be the attribute-value without the leading 1235 %x2E (".") character. 1237 Otherwise: 1239 1. Let cookie-domain be the entire attribute-value. 1241 3. Convert the cookie-domain to lower case. 1243 4. Append an attribute to the cookie-attribute-list with an 1244 attribute-name of Domain and an attribute-value of cookie-domain. 1246 5.4.4. The Path Attribute 1248 If the attribute-name case-insensitively matches the string "Path", 1249 the user agent MUST process the cookie-av as follows. 1251 1. If the attribute-value is empty or if the first character of the 1252 attribute-value is not %x2F ("/"): 1254 1. Let cookie-path be the default-path. 1256 Otherwise: 1258 1. Let cookie-path be the attribute-value. 1260 2. Append an attribute to the cookie-attribute-list with an 1261 attribute-name of Path and an attribute-value of cookie-path. 1263 5.4.5. The Secure Attribute 1265 If the attribute-name case-insensitively matches the string "Secure", 1266 the user agent MUST append an attribute to the cookie-attribute-list 1267 with an attribute-name of Secure and an empty attribute-value. 1269 5.4.6. The HttpOnly Attribute 1271 If the attribute-name case-insensitively matches the string 1272 "HttpOnly", the user agent MUST append an attribute to the cookie- 1273 attribute-list with an attribute-name of HttpOnly and an empty 1274 attribute-value. 1276 5.4.7. The SameSite Attribute 1278 If the attribute-name case-insensitively matches the string 1279 "SameSite", the user agent MUST process the cookie-av as follows: 1281 1. Let "enforcement" be "Default". 1283 2. If cookie-av's attribute-value is a case-insensitive match for 1284 "None", set "enforcement" to "None". 1286 3. If cookie-av's attribute-value is a case-insensitive match for 1287 "Strict", set "enforcement" to "Strict". 1289 4. If cookie-av's attribute-value is a case-insensitive match for 1290 "Lax", set "enforcement" to "Lax". 1292 5. Append an attribute to the cookie-attribute-list with an 1293 attribute-name of "SameSite" and an attribute-value of 1294 "enforcement". 1296 5.4.7.1. "Strict" and "Lax" enforcement 1298 Same-site cookies in "Strict" enforcement mode will not be sent along 1299 with top-level navigations which are triggered from a cross-site 1300 document context. As discussed in Section 8.8.2, this might or might 1301 not be compatible with existing session management systems. In the 1302 interests of providing a drop-in mechanism that mitigates the risk of 1303 CSRF attacks, developers may set the "SameSite" attribute in a "Lax" 1304 enforcement mode that carves out an exception which sends same-site 1305 cookies along with cross-site requests if and only if they are top- 1306 level navigations which use a "safe" (in the [HTTPSEM] sense) HTTP 1307 method. (Note that a request's method may be changed from POST to 1308 GET for some redirects (see Sections 15.4.2 and 15.4.3 of [HTTPSEM]); 1309 in these cases, a request's "safe"ness is determined based on the 1310 method of the current redirect hop.) 1312 Lax enforcement provides reasonable defense in depth against CSRF 1313 attacks that rely on unsafe HTTP methods (like "POST"), but does not 1314 offer a robust defense against CSRF as a general category of attack: 1316 1. Attackers can still pop up new windows or trigger top-level 1317 navigations in order to create a "same-site" request (as 1318 described in Section 5.2.1), which is only a speedbump along the 1319 road to exploitation. 1321 2. Features like "" [prerendering] can be 1322 exploited to create "same-site" requests without the risk of user 1323 detection. 1325 When possible, developers should use a session management mechanism 1326 such as that described in Section 8.8.2 to mitigate the risk of CSRF 1327 more completely. 1329 5.4.7.2. "Lax-Allowing-Unsafe" enforcement 1331 As discussed in Section 8.8.6, compatibility concerns may necessitate 1332 the use of a "Lax-allowing-unsafe" enforcement mode that allows 1333 cookies to be sent with a cross-site HTTP request if and only if it 1334 is a top-level request, regardless of request method. That is, the 1335 "Lax-allowing-unsafe" enforcement mode waives the requirement for the 1336 HTTP request's method to be "safe" in the "SameSite" enforcement step 1337 of the retrieval algorithm in Section 5.6.3. (All cookies, 1338 regardless of "SameSite" enforcement mode, may be set for top-level 1339 navigations, regardless of HTTP request method, as specified in 1340 Section 5.5.) 1342 "Lax-allowing-unsafe" is not a distinct value of the "SameSite" 1343 attribute. Rather, user agents MAY apply "Lax-allowing-unsafe" 1344 enforcement only to cookies that did not explicitly specify a 1345 "SameSite" attribute (i.e., those whose same-site-flag was set to 1346 "Default" by default). To limit the scope of this compatibility 1347 mode, user agents which apply "Lax-allowing-unsafe" enforcement 1348 SHOULD restrict the enforcement to cookies which were created 1349 recently. Deployment experience has shown a cookie age of 2 minutes 1350 or less to be a reasonable limit. 1352 If the user agent uses "Lax-allowing-unsafe" enforcement, it MUST 1353 apply the following modification to the retrieval algorithm defined 1354 in Section 5.6.3: 1356 Replace the condition in the penultimate bullet point of step 1 of 1357 the retrieval algorithm reading 1359 * The HTTP request associated with the retrieval uses a "safe" method. 1361 with 1363 * At least one of the following is true: 1365 1. The HTTP request associated with the retrieval uses a "safe" method. 1367 2. The cookie's same-site-flag is "Default" and the amount of time 1368 elapsed since the cookie's creation-time is at most a duration of the 1369 user agent's choosing. 1371 5.5. Storage Model 1373 The user agent stores the following fields about each cookie: name, 1374 value, expiry-time, domain, path, creation-time, last-access-time, 1375 persistent-flag, host-only-flag, secure-only-flag, http-only-flag, 1376 and same-site-flag. 1378 When the user agent "receives a cookie" from a request-uri with name 1379 cookie-name, value cookie-value, and attributes cookie-attribute- 1380 list, the user agent MUST process the cookie as follows: 1382 1. A user agent MAY ignore a received cookie in its entirety. See 1383 Section 5.3. 1385 2. If cookie-name is empty and cookie-value is empty, abort these 1386 steps and ignore the cookie entirely. 1388 3. If the cookie-name or the cookie-value contains a %x00-1F / %x7F 1389 (CTL) character, abort these steps and ignore the cookie 1390 entirely. 1392 4. Create a new cookie with name cookie-name, value cookie-value. 1393 Set the creation-time and the last-access-time to the current 1394 date and time. 1396 5. If the cookie-attribute-list contains an attribute with an 1397 attribute-name of "Max-Age": 1399 1. Set the cookie's persistent-flag to true. 1401 2. Set the cookie's expiry-time to attribute-value of the last 1402 attribute in the cookie-attribute-list with an attribute- 1403 name of "Max-Age". 1405 Otherwise, if the cookie-attribute-list contains an attribute 1406 with an attribute-name of "Expires" (and does not contain an 1407 attribute with an attribute-name of "Max-Age"): 1409 1. Set the cookie's persistent-flag to true. 1411 2. Set the cookie's expiry-time to attribute-value of the last 1412 attribute in the cookie-attribute-list with an attribute- 1413 name of "Expires". 1415 Otherwise: 1417 1. Set the cookie's persistent-flag to false. 1419 2. Set the cookie's expiry-time to the latest representable 1420 date. 1422 6. If the cookie-attribute-list contains an attribute with an 1423 attribute-name of "Domain": 1425 1. Let the domain-attribute be the attribute-value of the last 1426 attribute in the cookie-attribute-list with an attribute- 1427 name of "Domain". 1429 Otherwise: 1431 1. Let the domain-attribute be the empty string. 1433 7. If the user agent is configured to reject "public suffixes" and 1434 the domain-attribute is a public suffix: 1436 1. If the domain-attribute is identical to the canonicalized 1437 request-host: 1439 1. Let the domain-attribute be the empty string. 1441 Otherwise: 1443 1. Ignore the cookie entirely and abort these steps. 1445 NOTE: This step prevents "attacker.example" from disrupting the 1446 integrity of "site.example" by setting a cookie with a Domain 1447 attribute of "example". 1449 8. If the domain-attribute is non-empty: 1451 1. If the canonicalized request-host does not domain-match the 1452 domain-attribute: 1454 1. Ignore the cookie entirely and abort these steps. 1456 Otherwise: 1458 1. Set the cookie's host-only-flag to false. 1460 2. Set the cookie's domain to the domain-attribute. 1462 Otherwise: 1464 1. Set the cookie's host-only-flag to true. 1466 2. Set the cookie's domain to the canonicalized request-host. 1468 9. If the cookie-attribute-list contains an attribute with an 1469 attribute-name of "Path", set the cookie's path to attribute- 1470 value of the last attribute in the cookie-attribute-list with an 1471 attribute-name of "Path". Otherwise, set the cookie's path to 1472 the default-path of the request-uri. 1474 10. If the cookie-attribute-list contains an attribute with an 1475 attribute-name of "Secure", set the cookie's secure-only-flag to 1476 true. Otherwise, set the cookie's secure-only-flag to false. 1478 11. If the scheme component of the request-uri does not denote a 1479 "secure" protocol (as defined by the user agent), and the 1480 cookie's secure-only-flag is true, then abort these steps and 1481 ignore the cookie entirely. 1483 12. If the cookie-attribute-list contains an attribute with an 1484 attribute-name of "HttpOnly", set the cookie's http-only-flag to 1485 true. Otherwise, set the cookie's http-only-flag to false. 1487 13. If the cookie was received from a "non-HTTP" API and the 1488 cookie's http-only-flag is true, abort these steps and ignore 1489 the cookie entirely. 1491 14. If the cookie's secure-only-flag is false, and the scheme 1492 component of request-uri does not denote a "secure" protocol, 1493 then abort these steps and ignore the cookie entirely if the 1494 cookie store contains one or more cookies that meet all of the 1495 following criteria: 1497 1. Their name matches the name of the newly-created cookie. 1499 2. Their secure-only-flag is true. 1501 3. Their domain domain-matches the domain of the newly-created 1502 cookie, or vice-versa. 1504 4. The path of the newly-created cookie path-matches the path 1505 of the existing cookie. 1507 Note: The path comparison is not symmetric, ensuring only that a 1508 newly-created, non-secure cookie does not overlay an existing 1509 secure cookie, providing some mitigation against cookie-fixing 1510 attacks. That is, given an existing secure cookie named 'a' 1511 with a path of '/login', a non-secure cookie named 'a' could be 1512 set for a path of '/' or '/foo', but not for a path of '/login' 1513 or '/login/en'. 1515 15. If the cookie-attribute-list contains an attribute with an 1516 attribute-name of "SameSite", and an attribute-value of 1517 "Strict", "Lax", or "None", set the cookie's same-site-flag to 1518 the attribute-value of the last attribute in the cookie- 1519 attribute-list with an attribute-name of "SameSite". Otherwise, 1520 set the cookie's same-site-flag to "Default". 1522 16. If the cookie's "same-site-flag" is not "None": 1524 1. If the cookie was received from a "non-HTTP" API, and the 1525 API was called from a browsing context's active document 1526 whose "site for cookies" is not same-site with the top-level 1527 origin, then abort these steps and ignore the newly created 1528 cookie entirely. 1530 2. If the cookie was received from a "same-site" request (as 1531 defined in Section 5.2), skip the remaining substeps and 1532 continue processing the cookie. 1534 3. If the cookie was received from a request which is 1535 navigating a top-level browsing context [HTML] (e.g. if the 1536 request's "reserved client" is either "null" or an 1537 environment whose "target browsing context" is a top-level 1538 browing context), skip the remaining substeps and continue 1539 processing the cookie. 1541 Note: Top-level navigations can create a cookie with any 1542 "SameSite" value, even if the new cookie wouldn't have been 1543 sent along with the request had it already existed prior to 1544 the navigation. 1546 4. Abort these steps and ignore the newly created cookie 1547 entirely. 1549 17. If the cookie's "same-site-flag" is "None", abort these steps 1550 and ignore the cookie entirely unless the cookie's secure-only- 1551 flag is true. 1553 18. If the cookie-name begins with a case-sensitive match for the 1554 string "__Secure-", abort these steps and ignore the cookie 1555 entirely unless the cookie's secure-only-flag is true. 1557 19. If the cookie-name begins with a case-sensitive match for the 1558 string "__Host-", abort these steps and ignore the cookie 1559 entirely unless the cookie meets all the following criteria: 1561 1. The cookie's secure-only-flag is true. 1563 2. The cookie's host-only-flag is true. 1565 3. The cookie-attribute-list contains an attribute with an 1566 attribute-name of "Path", and the cookie's path is "/". 1568 20. If the cookie store contains a cookie with the same name, 1569 domain, host-only-flag, and path as the newly-created cookie: 1571 1. Let old-cookie be the existing cookie with the same name, 1572 domain, host-only-flag, and path as the newly-created 1573 cookie. (Notice that this algorithm maintains the invariant 1574 that there is at most one such cookie.) 1576 2. If the newly-created cookie was received from a "non-HTTP" 1577 API and the old-cookie's http-only-flag is true, abort these 1578 steps and ignore the newly created cookie entirely. 1580 3. Update the creation-time of the newly-created cookie to 1581 match the creation-time of the old-cookie. 1583 4. Remove the old-cookie from the cookie store. 1585 21. Insert the newly-created cookie into the cookie store. 1587 A cookie is "expired" if the cookie has an expiry date in the past. 1589 The user agent MUST evict all expired cookies from the cookie store 1590 if, at any time, an expired cookie exists in the cookie store. 1592 At any time, the user agent MAY "remove excess cookies" from the 1593 cookie store if the number of cookies sharing a domain field exceeds 1594 some implementation-defined upper bound (such as 50 cookies). 1596 At any time, the user agent MAY "remove excess cookies" from the 1597 cookie store if the cookie store exceeds some predetermined upper 1598 bound (such as 3000 cookies). 1600 When the user agent removes excess cookies from the cookie store, the 1601 user agent MUST evict cookies in the following priority order: 1603 1. Expired cookies. 1605 2. Cookies whose secure-only-flag is false, and which share a domain 1606 field with more than a predetermined number of other cookies. 1608 3. Cookies that share a domain field with more than a predetermined 1609 number of other cookies. 1611 4. All cookies. 1613 If two cookies have the same removal priority, the user agent MUST 1614 evict the cookie with the earliest last-access-time first. 1616 When "the current session is over" (as defined by the user agent), 1617 the user agent MUST remove from the cookie store all cookies with the 1618 persistent-flag set to false. 1620 5.6. Retrieval Model 1622 This section defines how cookies are retrieved from a cookie store in 1623 the form of a cookie-string. A "retrieval" is any event which 1624 requires generating a cookie-string. For example, a retrieval may 1625 occur in order to build a Cookie header field for an HTTP request, or 1626 may be required in order to return a cookie-string from a call to a 1627 "non-HTTP" API that provides access to cookies. A retrieval has an 1628 associated URI, same-site status, and type, which are defined below 1629 depending on the type of retrieval. 1631 5.6.1. The Cookie Header Field 1633 The user agent includes stored cookies in the Cookie HTTP request 1634 header field. 1636 When the user agent generates an HTTP request, the user agent MUST 1637 NOT attach more than one Cookie header field. 1639 A user agent MAY omit the Cookie header field in its entirety. For 1640 example, the user agent might wish to block sending cookies during 1641 "third-party" requests from setting cookies (see Section 7.1). 1643 If the user agent does attach a Cookie header field to an HTTP 1644 request, the user agent MUST compute the cookie-string following the 1645 algorithm defined in Section 5.6.3, where the retrieval's URI is the 1646 request-uri, the retrieval's same-site status is computed for the 1647 HTTP request as defined in Section 5.2, and the retrieval's type is 1648 "HTTP". 1650 5.6.2. Non-HTTP APIs 1652 The user agent MAY implement "non-HTTP" APIs that can be used to 1653 access stored cookies. 1655 A user agent MAY return an empty cookie-string in certain contexts, 1656 such as when a retrieval occurs within a third-party context (see 1657 Section 7.1). 1659 If a user agent does return cookies for a given call to a "non-HTTP" 1660 API with an associated Document, then the user agent MUST compute the 1661 cookie-string following the algorithm defined in Section 5.6.3, where 1662 the retrieval's URI is defined by the caller (see 1663 [DOM-DOCUMENT-COOKIE]), the retrieval's same-site status is "same- 1664 site" if the Document's "site for cookies" is same-site with the top- 1665 level origin as defined in Section 5.2.1 (otherwise it is "cross- 1666 site"), and the retrieval's type is "non-HTTP". 1668 5.6.3. Retrieval Algorithm 1670 Given a cookie store and a retrieval, the following algorithm returns 1671 a cookie-string from a given cookie store. 1673 1. Let cookie-list be the set of cookies from the cookie store that 1674 meets all of the following requirements: 1676 * Either: 1678 - The cookie's host-only-flag is true and the canonicalized 1679 host of the retrieval's URI is identical to the cookie's 1680 domain. 1682 Or: 1684 - The cookie's host-only-flag is false and the canonicalized 1685 host of the retrieval's URI domain-matches the cookie's 1686 domain. 1688 * The retrieval's URI's path path-matches the cookie's path. 1690 * If the cookie's secure-only-flag is true, then the retrieval's 1691 URI's scheme must denote a "secure" protocol (as defined by 1692 the user agent). 1694 NOTE: The notion of a "secure" protocol is not defined by this 1695 document. Typically, user agents consider a protocol secure 1696 if the protocol makes use of transport-layer security, such as 1697 SSL or TLS. For example, most user agents consider "https" to 1698 be a scheme that denotes a secure protocol. 1700 * If the cookie's http-only-flag is true, then exclude the 1701 cookie if the retrieval's type is "non-HTTP". 1703 * If the cookie's same-site-flag is not "None" and the 1704 retrieval's same-site status is "cross-site", then exclude the 1705 cookie unless all of the following conditions are met: 1707 - The retrieval's type is "HTTP". 1709 - The same-site-flag is "Lax" or "Default". 1711 - The HTTP request associated with the retrieval uses a 1712 "safe" method. 1714 - The target browsing context of the HTTP request associated 1715 with the retrieval is a top-level browsing context. 1717 2. The user agent SHOULD sort the cookie-list in the following 1718 order: 1720 * Cookies with longer paths are listed before cookies with 1721 shorter paths. 1723 * Among cookies that have equal-length path fields, cookies with 1724 earlier creation-times are listed before cookies with later 1725 creation-times. 1727 NOTE: Not all user agents sort the cookie-list in this order, but 1728 this order reflects common practice when this document was 1729 written, and, historically, there have been servers that 1730 (erroneously) depended on this order. 1732 3. Update the last-access-time of each cookie in the cookie-list to 1733 the current date and time. 1735 4. Serialize the cookie-list into a cookie-string by processing each 1736 cookie in the cookie-list in order: 1738 1. If the cookies' name is not empty, output the cookie's name 1739 followed by the %x3D ("=") character. 1741 2. If the cookies' value is not empty, output the cookie's 1742 value. 1744 3. If there is an unprocessed cookie in the cookie-list, output 1745 the characters %x3B and %x20 ("; "). 1747 NOTE: Despite its name, the cookie-string is actually a sequence of 1748 octets, not a sequence of characters. To convert the cookie-string 1749 (or components thereof) into a sequence of characters (e.g., for 1750 presentation to the user), the user agent might wish to try using the 1751 UTF-8 character encoding [RFC3629] to decode the octet sequence. 1752 This decoding might fail, however, because not every sequence of 1753 octets is valid UTF-8. 1755 6. Implementation Considerations 1757 6.1. Limits 1759 Practical user agent implementations have limits on the number and 1760 size of cookies that they can store. General-use user agents SHOULD 1761 provide each of the following minimum capabilities: 1763 * At least 4096 bytes per cookie (as measured by the sum of the 1764 length of the cookie's name, value, and attributes). 1766 * At least 50 cookies per domain. 1768 * At least 3000 cookies total. 1770 Servers SHOULD use as few and as small cookies as possible to avoid 1771 reaching these implementation limits and to minimize network 1772 bandwidth due to the Cookie header field being included in every 1773 request. 1775 Servers SHOULD gracefully degrade if the user agent fails to return 1776 one or more cookies in the Cookie header field because the user agent 1777 might evict any cookie at any time on orders from the user. 1779 6.2. Application Programming Interfaces 1781 One reason the Cookie and Set-Cookie header fields use such esoteric 1782 syntax is that many platforms (both in servers and user agents) 1783 provide a string-based application programming interface (API) to 1784 cookies, requiring application-layer programmers to generate and 1785 parse the syntax used by the Cookie and Set-Cookie header fields, 1786 which many programmers have done incorrectly, resulting in 1787 interoperability problems. 1789 Instead of providing string-based APIs to cookies, platforms would be 1790 well-served by providing more semantic APIs. It is beyond the scope 1791 of this document to recommend specific API designs, but there are 1792 clear benefits to accepting an abstract "Date" object instead of a 1793 serialized date string. 1795 6.3. IDNA Dependency and Migration 1797 IDNA2008 [RFC5890] supersedes IDNA2003 [RFC3490]. However, there are 1798 differences between the two specifications, and thus there can be 1799 differences in processing (e.g., converting) domain name labels that 1800 have been registered under one from those registered under the other. 1801 There will be a transition period of some time during which 1802 IDNA2003-based domain name labels will exist in the wild. User 1803 agents SHOULD implement IDNA2008 [RFC5890] and MAY implement [UTS46] 1804 or [RFC5895] in order to facilitate their IDNA transition. If a user 1805 agent does not implement IDNA2008, the user agent MUST implement 1806 IDNA2003 [RFC3490]. 1808 7. Privacy Considerations 1810 Cookies are often criticized for letting servers track users. For 1811 example, a number of "web analytics" companies use cookies to 1812 recognize when a user returns to a web site or visits another web 1813 site. Although cookies are not the only mechanism servers can use to 1814 track users across HTTP requests, cookies facilitate tracking because 1815 they are persistent across user agent sessions and can be shared 1816 between hosts. 1818 7.1. Third-Party Cookies 1820 Particularly worrisome are so-called "third-party" cookies. In 1821 rendering an HTML document, a user agent often requests resources 1822 from other servers (such as advertising networks). These third-party 1823 servers can use cookies to track the user even if the user never 1824 visits the server directly. For example, if a user visits a site 1825 that contains content from a third party and then later visits 1826 another site that contains content from the same third party, the 1827 third party can track the user between the two sites. 1829 Given this risk to user privacy, some user agents restrict how third- 1830 party cookies behave, and those restrictions vary widly. For 1831 instance, user agents might block third-party cookies entirely by 1832 refusing to send Cookie header fields or process Set-Cookie header 1833 fields during third-party requests. They might take a less draconian 1834 approach by partitioning cookies based on the first-party context, 1835 sending one set of cookies to a given third party in one first-party 1836 context, and another to the same third party in another. 1838 This document grants user agents wide latitude to experiment with 1839 third-party cookie policies that balance the privacy and 1840 compatibility needs of their users. However, this document does not 1841 endorse any particular third-party cookie policy. 1843 Third-party cookie blocking policies are often ineffective at 1844 achieving their privacy goals if servers attempt to work around their 1845 restrictions to track users. In particular, two collaborating 1846 servers can often track users without using cookies at all by 1847 injecting identifying information into dynamic URLs. 1849 7.2. Cookie policy 1851 User agents MAY enforce a cookie policy consisting of restrictions on 1852 how cookies may be used or ignored (see Section 5.3). 1854 A cookie policy may govern which domains or parties, as in first and 1855 third parties (see Section 7.1), for which the user agent will allow 1856 cookie access. The policy can also define limits on cookie size, 1857 cookie expiry, and the number of cookies per domain or in total. 1859 The goal of a restrictive cookie policy is often to improve security 1860 or privacy. User agents often allow users to change the cookie 1861 policy (see Section 7.3). 1863 7.3. User Controls 1865 User agents SHOULD provide users with a mechanism for managing the 1866 cookies stored in the cookie store. For example, a user agent might 1867 let users delete all cookies received during a specified time period 1868 or all the cookies related to a particular domain. In addition, many 1869 user agents include a user interface element that lets users examine 1870 the cookies stored in their cookie store. 1872 User agents SHOULD provide users with a mechanism for disabling 1873 cookies. When cookies are disabled, the user agent MUST NOT include 1874 a Cookie header field in outbound HTTP requests and the user agent 1875 MUST NOT process Set-Cookie header fields in inbound HTTP responses. 1877 User agents MAY offer a way to change the cookie policy (see 1878 Section 7.2). 1880 User agents MAY provide users the option of preventing persistent 1881 storage of cookies across sessions. When configured thusly, user 1882 agents MUST treat all received cookies as if the persistent-flag were 1883 set to false. Some popular user agents expose this functionality via 1884 "private browsing" mode [Aggarwal2010]. 1886 7.4. Expiration Dates 1888 Although servers can set the expiration date for cookies to the 1889 distant future, most user agents do not actually retain cookies for 1890 multiple decades. Rather than choosing gratuitously long expiration 1891 periods, servers SHOULD promote user privacy by selecting reasonable 1892 cookie expiration periods based on the purpose of the cookie. For 1893 example, a typical session identifier might reasonably be set to 1894 expire in two weeks. 1896 8. Security Considerations 1898 8.1. Overview 1900 Cookies have a number of security pitfalls. This section overviews a 1901 few of the more salient issues. 1903 In particular, cookies encourage developers to rely on ambient 1904 authority for authentication, often becoming vulnerable to attacks 1905 such as cross-site request forgery [CSRF]. Also, when storing 1906 session identifiers in cookies, developers often create session 1907 fixation vulnerabilities. 1909 Transport-layer encryption, such as that employed in HTTPS, is 1910 insufficient to prevent a network attacker from obtaining or altering 1911 a victim's cookies because the cookie protocol itself has various 1912 vulnerabilities (see "Weak Confidentiality" and "Weak Integrity", 1913 below). In addition, by default, cookies do not provide 1914 confidentiality or integrity from network attackers, even when used 1915 in conjunction with HTTPS. 1917 8.2. Ambient Authority 1919 A server that uses cookies to authenticate users can suffer security 1920 vulnerabilities because some user agents let remote parties issue 1921 HTTP requests from the user agent (e.g., via HTTP redirects or HTML 1922 forms). When issuing those requests, user agents attach cookies even 1923 if the remote party does not know the contents of the cookies, 1924 potentially letting the remote party exercise authority at an unwary 1925 server. 1927 Although this security concern goes by a number of names (e.g., 1928 cross-site request forgery, confused deputy), the issue stems from 1929 cookies being a form of ambient authority. Cookies encourage server 1930 operators to separate designation (in the form of URLs) from 1931 authorization (in the form of cookies). Consequently, the user agent 1932 might supply the authorization for a resource designated by the 1933 attacker, possibly causing the server or its clients to undertake 1934 actions designated by the attacker as though they were authorized by 1935 the user. 1937 Instead of using cookies for authorization, server operators might 1938 wish to consider entangling designation and authorization by treating 1939 URLs as capabilities. Instead of storing secrets in cookies, this 1940 approach stores secrets in URLs, requiring the remote entity to 1941 supply the secret itself. Although this approach is not a panacea, 1942 judicious application of these principles can lead to more robust 1943 security. 1945 8.3. Clear Text 1947 Unless sent over a secure channel (such as TLS), the information in 1948 the Cookie and Set-Cookie header fields is transmitted in the clear. 1950 1. All sensitive information conveyed in these header fields is 1951 exposed to an eavesdropper. 1953 2. A malicious intermediary could alter the header fields as they 1954 travel in either direction, with unpredictable results. 1956 3. A malicious client could alter the Cookie header fields before 1957 transmission, with unpredictable results. 1959 Servers SHOULD encrypt and sign the contents of cookies (using 1960 whatever format the server desires) when transmitting them to the 1961 user agent (even when sending the cookies over a secure channel). 1962 However, encrypting and signing cookie contents does not prevent an 1963 attacker from transplanting a cookie from one user agent to another 1964 or from replaying the cookie at a later time. 1966 In addition to encrypting and signing the contents of every cookie, 1967 servers that require a higher level of security SHOULD use the Cookie 1968 and Set-Cookie header fields only over a secure channel. When using 1969 cookies over a secure channel, servers SHOULD set the Secure 1970 attribute (see Section 4.1.2.5) for every cookie. If a server does 1971 not set the Secure attribute, the protection provided by the secure 1972 channel will be largely moot. 1974 For example, consider a webmail server that stores a session 1975 identifier in a cookie and is typically accessed over HTTPS. If the 1976 server does not set the Secure attribute on its cookies, an active 1977 network attacker can intercept any outbound HTTP request from the 1978 user agent and redirect that request to the webmail server over HTTP. 1979 Even if the webmail server is not listening for HTTP connections, the 1980 user agent will still include cookies in the request. The active 1981 network attacker can intercept these cookies, replay them against the 1982 server, and learn the contents of the user's email. If, instead, the 1983 server had set the Secure attribute on its cookies, the user agent 1984 would not have included the cookies in the clear-text request. 1986 8.4. Session Identifiers 1988 Instead of storing session information directly in a cookie (where it 1989 might be exposed to or replayed by an attacker), servers commonly 1990 store a nonce (or "session identifier") in a cookie. When the server 1991 receives an HTTP request with a nonce, the server can look up state 1992 information associated with the cookie using the nonce as a key. 1994 Using session identifier cookies limits the damage an attacker can 1995 cause if the attacker learns the contents of a cookie because the 1996 nonce is useful only for interacting with the server (unlike non- 1997 nonce cookie content, which might itself be sensitive). Furthermore, 1998 using a single nonce prevents an attacker from "splicing" together 1999 cookie content from two interactions with the server, which could 2000 cause the server to behave unexpectedly. 2002 Using session identifiers is not without risk. For example, the 2003 server SHOULD take care to avoid "session fixation" vulnerabilities. 2004 A session fixation attack proceeds in three steps. First, the 2005 attacker transplants a session identifier from his or her user agent 2006 to the victim's user agent. Second, the victim uses that session 2007 identifier to interact with the server, possibly imbuing the session 2008 identifier with the user's credentials or confidential information. 2009 Third, the attacker uses the session identifier to interact with 2010 server directly, possibly obtaining the user's authority or 2011 confidential information. 2013 8.5. Weak Confidentiality 2015 Cookies do not provide isolation by port. If a cookie is readable by 2016 a service running on one port, the cookie is also readable by a 2017 service running on another port of the same server. If a cookie is 2018 writable by a service on one port, the cookie is also writable by a 2019 service running on another port of the same server. For this reason, 2020 servers SHOULD NOT both run mutually distrusting services on 2021 different ports of the same host and use cookies to store security- 2022 sensitive information. 2024 Cookies do not provide isolation by scheme. Although most commonly 2025 used with the http and https schemes, the cookies for a given host 2026 might also be available to other schemes, such as ftp and gopher. 2027 Although this lack of isolation by scheme is most apparent in non- 2028 HTTP APIs that permit access to cookies (e.g., HTML's document.cookie 2029 API), the lack of isolation by scheme is actually present in 2030 requirements for processing cookies themselves (e.g., consider 2031 retrieving a URI with the gopher scheme via HTTP). 2033 Cookies do not always provide isolation by path. Although the 2034 network-level protocol does not send cookies stored for one path to 2035 another, some user agents expose cookies via non-HTTP APIs, such as 2036 HTML's document.cookie API. Because some of these user agents (e.g., 2037 web browsers) do not isolate resources received from different paths, 2038 a resource retrieved from one path might be able to access cookies 2039 stored for another path. 2041 8.6. Weak Integrity 2043 Cookies do not provide integrity guarantees for sibling domains (and 2044 their subdomains). For example, consider foo.site.example and 2045 bar.site.example. The foo.site.example server can set a cookie with 2046 a Domain attribute of "site.example" (possibly overwriting an 2047 existing "site.example" cookie set by bar.site.example), and the user 2048 agent will include that cookie in HTTP requests to bar.site.example. 2049 In the worst case, bar.site.example will be unable to distinguish 2050 this cookie from a cookie it set itself. The foo.site.example server 2051 might be able to leverage this ability to mount an attack against 2052 bar.site.example. 2054 Even though the Set-Cookie header field supports the Path attribute, 2055 the Path attribute does not provide any integrity protection because 2056 the user agent will accept an arbitrary Path attribute in a Set- 2057 Cookie header field. For example, an HTTP response to a request for 2058 http://site.example/foo/bar can set a cookie with a Path attribute of 2059 "/qux". Consequently, servers SHOULD NOT both run mutually 2060 distrusting services on different paths of the same host and use 2061 cookies to store security-sensitive information. 2063 An active network attacker can also inject cookies into the Cookie 2064 header field sent to https://site.example/ by impersonating a 2065 response from http://site.example/ and injecting a Set-Cookie header 2066 field. The HTTPS server at site.example will be unable to 2067 distinguish these cookies from cookies that it set itself in an HTTPS 2068 response. An active network attacker might be able to leverage this 2069 ability to mount an attack against site.example even if site.example 2070 uses HTTPS exclusively. 2072 Servers can partially mitigate these attacks by encrypting and 2073 signing the contents of their cookies. However, using cryptography 2074 does not mitigate the issue completely because an attacker can replay 2075 a cookie he or she received from the authentic site.example server in 2076 the user's session, with unpredictable results. 2078 Finally, an attacker might be able to force the user agent to delete 2079 cookies by storing a large number of cookies. Once the user agent 2080 reaches its storage limit, the user agent will be forced to evict 2081 some cookies. Servers SHOULD NOT rely upon user agents retaining 2082 cookies. 2084 8.7. Reliance on DNS 2086 Cookies rely upon the Domain Name System (DNS) for security. If the 2087 DNS is partially or fully compromised, the cookie protocol might fail 2088 to provide the security properties required by applications. 2090 8.8. SameSite Cookies 2092 8.8.1. Defense in depth 2094 "SameSite" cookies offer a robust defense against CSRF attack when 2095 deployed in strict mode, and when supported by the client. It is, 2096 however, prudent to ensure that this designation is not the extent of 2097 a site's defense against CSRF, as same-site navigations and 2098 submissions can certainly be executed in conjunction with other 2099 attack vectors such as cross-site scripting. 2101 Developers are strongly encouraged to deploy the usual server-side 2102 defenses (CSRF tokens, ensuring that "safe" HTTP methods are 2103 idempotent, etc) to mitigate the risk more fully. 2105 Additionally, client-side techniques such as those described in 2106 [app-isolation] may also prove effective against CSRF, and are 2107 certainly worth exploring in combination with "SameSite" cookies. 2109 8.8.2. Top-level Navigations 2111 Setting the "SameSite" attribute in "strict" mode provides robust 2112 defense in depth against CSRF attacks, but has the potential to 2113 confuse users unless sites' developers carefully ensure that their 2114 cookie-based session management systems deal reasonably well with 2115 top-level navigations. 2117 Consider the scenario in which a user reads their email at MegaCorp 2118 Inc's webmail provider "https://site.example/". They might expect 2119 that clicking on an emailed link to "https://projects.example/secret/ 2120 project" would show them the secret project that they're authorized 2121 to see, but if "https://projects.example" has marked their session 2122 cookies as "SameSite=Strict", then this cross-site navigation won't 2123 send them along with the request. "https://projects.example" will 2124 render a 404 error to avoid leaking secret information, and the user 2125 will be quite confused. 2127 Developers can avoid this confusion by adopting a session management 2128 system that relies on not one, but two cookies: one conceptually 2129 granting "read" access, another granting "write" access. The latter 2130 could be marked as "SameSite=Strict", and its absence would prompt a 2131 reauthentication step before executing any non-idempotent action. 2132 The former could be marked as "SameSite=Lax", in order to allow users 2133 access to data via top-level navigation, or "SameSite=None", to 2134 permit access in all contexts (including cross-site embedded 2135 contexts). 2137 8.8.3. Mashups and Widgets 2139 The "Lax" and "Strict" values for the "SameSite" attribute are 2140 inappropriate for some important use-cases. In particular, note that 2141 content intended for embedding in cross-site contexts (social 2142 networking widgets or commenting services, for instance) will not 2143 have access to same-site cookies. Cookies which are required in 2144 these situations should be marked with "SameSite=None" to allow 2145 access in cross-site contexts. 2147 Likewise, some forms of Single-Sign-On might require cookie-based 2148 authentication in a cross-site context; these mechanisms will not 2149 function as intended with same-site cookies and will also require 2150 "SameSite=None". 2152 8.8.4. Server-controlled 2154 SameSite cookies in and of themselves don't do anything to address 2155 the general privacy concerns outlined in Section 7.1 of [RFC6265]. 2156 The "SameSite" attribute is set by the server, and serves to mitigate 2157 the risk of certain kinds of attacks that the server is worried 2158 about. The user is not involved in this decision. Moreover, a 2159 number of side-channels exist which could allow a server to link 2160 distinct requests even in the absence of cookies (for example, 2161 connection and/or socket pooling between same-site and cross-site 2162 requests). 2164 8.8.5. Reload navigations 2166 Requests issued for reloads triggered through user interface elements 2167 (such as a refresh button on a toolbar) are same-site only if the 2168 reloaded document was originally navigated to via a same-site 2169 request. This differs from the handling of other reload navigations, 2170 which are always same-site if top-level, since the source browsing 2171 context's active document is precisely the document being reloaded. 2173 This special handling of reloads triggered through a user interface 2174 element avoids sending "SameSite" cookies on user-initiated reloads 2175 if they were withheld on the original navigation (i.e., if the 2176 initial navigation were cross-site). If the reload navigation were 2177 instead considered same-site, and sent all the initially withheld 2178 "SameSite" cookies, the security benefits of withholding the cookies 2179 in the first place would be nullified. This is especially important 2180 given that the absence of "SameSite" cookies withheld on a cross-site 2181 navigation request may lead to visible site breakage, prompting the 2182 user to trigger a reload. 2184 For example, suppose the user clicks on a link from 2185 "https://attacker.example/" to "https://victim.example/". This is a 2186 cross-site request, so "SameSite=Strict" cookies are withheld. 2187 Suppose this causes "https://victim.example/" to appear broken, 2188 because the site only displays its sensitive content if a particular 2189 "SameSite" cookie is present in the request. The user, frustrated by 2190 the unexpectedly broken site, presses refresh on their browser's 2191 toolbar. To now consider the reload request same-site and send the 2192 initially withheld "SameSite" cookie would defeat the purpose of 2193 withholding it in the first place, as the reload navigation triggered 2194 through the user interface may replay the original (potentially 2195 malicious) request. Thus, the reload request should be considered 2196 cross-site, like the request that initially navigated to the page. 2198 8.8.6. Top-level requests with "unsafe" methods 2200 The "Lax" enforcement mode described in Section 5.4.7.1 allows a 2201 cookie to be sent with a cross-site HTTP request if and only if it is 2202 a top-level navigation with a "safe" HTTP method. Implementation 2203 experience shows that this is difficult to apply as the default 2204 behavior, as some sites may rely on cookies not explicitly specifying 2205 a "SameSite" attribute being included on top-level cross-site 2206 requests with "unsafe" HTTP methods (as was the case prior to the 2207 introduction of the "SameSite" attribute). 2209 For example, a login flow may involve a cross-site top-level "POST" 2210 request to an endpoint which expects a cookie with login information. 2211 For such a cookie, "Lax" enforcement is not appropriate, as it would 2212 cause the cookie to be excluded due to the unsafe HTTP request 2213 method. On the other hand, "None" enforcement would allow the cookie 2214 to be sent with all cross-site requests, which may not be desirable 2215 due to the cookie's sensitive contents. 2217 The "Lax-allowing-unsafe" enforcement mode described in 2218 Section 5.4.7.2 retains some of the protections of "Lax" enforcement 2219 (as compared to "None") while still allowing cookies to be sent 2220 cross-site with unsafe top-level requests. 2222 As a more permissive variant of "Lax" mode, "Lax-allowing-unsafe" 2223 mode necessarily provides fewer protections against CSRF. 2224 Ultimately, the provision of such an enforcement mode should be seen 2225 as a temporary, transitional measure to ease adoption of "Lax" 2226 enforcement by default. 2228 9. IANA Considerations 2229 9.1. Cookie 2231 The permanent message header field registry (see [RFC3864]) needs to 2232 be updated with the following registration: 2234 Header field name: Cookie 2236 Applicable protocol: http 2238 Status: standard 2240 Author/Change controller: IETF 2242 Specification document: this specification (Section 5.6.1) 2244 9.2. Set-Cookie 2246 The permanent message header field registry (see [RFC3864]) needs to 2247 be updated with the following registration: 2249 Header field name: Set-Cookie 2251 Applicable protocol: http 2253 Status: standard 2255 Author/Change controller: IETF 2257 Specification document: this specification (Section 5.4) 2259 9.3. Cookie Attribute Registry 2261 IANA is requested to create the "Cookie Attribute Registry", defining 2262 the name space of attribute used to control cookies' behavior. The 2263 registry should be maintained at https://www.iana.org/assignments/ 2264 cookie-attribute-names (https://www.iana.org/assignments/cookie- 2265 attribute-names). 2267 9.3.1. Procedure 2269 Each registered attribute name is associated with a description, and 2270 a reference detailing how the attribute is to be processed and 2271 stored. 2273 New registrations happen on a "RFC Required" basis (see Section 4.7 2274 of [RFC8126]). The attribute to be registered MUST match the 2275 "extension-av" syntax defined in Section 4.1.1. Note that attribute 2276 names are generally defined in CamelCase, but technically accepted 2277 case-insensitively. 2279 9.3.2. Registration 2281 The "Cookie Attribute Registry" should be created with the 2282 registrations below: 2284 +==========+==================================+ 2285 | Name | Reference | 2286 +==========+==================================+ 2287 | Domain | Section 4.1.2.3 of this document | 2288 +----------+----------------------------------+ 2289 | Expires | Section 4.1.2.1 of this document | 2290 +----------+----------------------------------+ 2291 | HttpOnly | Section 4.1.2.6 of this document | 2292 +----------+----------------------------------+ 2293 | Max-Age | Section 4.1.2.2 of this document | 2294 +----------+----------------------------------+ 2295 | Path | Section 4.1.2.4 of this document | 2296 +----------+----------------------------------+ 2297 | SameSite | Section 4.1.2.7 of this document | 2298 +----------+----------------------------------+ 2299 | Secure | Section 4.1.2.5 of this document | 2300 +----------+----------------------------------+ 2302 Table 1 2304 10. References 2306 10.1. Normative References 2308 [DOM-DOCUMENT-COOKIE] 2309 WHATWG, "HTML - Living Standard", 18 May 2021, 2310 . 2312 [FETCH] van Kesteren, A., "Fetch", n.d., 2313 . 2315 [HTML] Hickson, I., Pieters, S., van Kesteren, A., Jägenstedt, 2316 P., and D. Denicola, "HTML", n.d., 2317 . 2319 [HTTPSEM] Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 2320 Semantics", Work in Progress, Internet-Draft, draft-ietf- 2321 httpbis-semantics-16, 27 May 2021, 2322 . 2325 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 2326 STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987, 2327 . 2329 [RFC1123] Braden, R., Ed., "Requirements for Internet Hosts - 2330 Application and Support", STD 3, RFC 1123, 2331 DOI 10.17487/RFC1123, October 1989, 2332 . 2334 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2335 Requirement Levels", BCP 14, RFC 2119, 2336 DOI 10.17487/RFC2119, March 1997, 2337 . 2339 [RFC3490] Costello, A., "Internationalizing Domain Names in 2340 Applications (IDNA)", RFC 3490, March 2003, 2341 . See Section 6.3 2342 for an explanation why the normative reference to an 2343 obsoleted specification is needed. 2345 [RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet 2346 Application Protocol Collation Registry", RFC 4790, 2347 DOI 10.17487/RFC4790, March 2007, 2348 . 2350 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 2351 Specifications: ABNF", STD 68, RFC 5234, 2352 DOI 10.17487/RFC5234, January 2008, 2353 . 2355 [RFC5890] Klensin, J., "Internationalized Domain Names for 2356 Applications (IDNA): Definitions and Document Framework", 2357 RFC 5890, DOI 10.17487/RFC5890, August 2010, 2358 . 2360 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 2361 DOI 10.17487/RFC6454, December 2011, 2362 . 2364 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2365 Writing an IANA Considerations Section in RFCs", BCP 26, 2366 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2367 . 2369 [SAMESITE] WHATWG, "HTML - Living Standard", 26 January 2021, 2370 . 2372 [SERVICE-WORKERS] 2373 Russell, A., Song, J., and J. Archibald, "Service 2374 Workers", n.d., . 2376 [USASCII] American National Standards Institute, "Coded Character 2377 Set -- 7-bit American Standard Code for Information 2378 Interchange", ANSI X3.4, 1986. 2380 10.2. Informative References 2382 [Aggarwal2010] 2383 Aggarwal, G., Burzstein, E., Jackson, C., and D. Boneh, 2384 "An Analysis of Private Browsing Modes in Modern 2385 Browsers", 2010, 2386 . 2389 [app-isolation] 2390 Chen, E., Bau, J., Reis, C., Barth, A., and C. Jackson, 2391 "App Isolation - Get the Security of Multiple Browsers 2392 with Just One", 2011, 2393 . 2396 [CSRF] Barth, A., Jackson, C., and J. Mitchell, "Robust Defenses 2397 for Cross-Site Request Forgery", 2398 DOI 10.1145/1455770.1455782, ISBN 978-1-59593-810-7, 2399 ACM CCS '08: Proceedings of the 15th ACM conference on 2400 Computer and communications security (pages 75-88), 2401 October 2008, 2402 . 2404 [I-D.ietf-httpbis-cookie-alone] 2405 West, M., "Deprecate modification of 'secure' cookies from 2406 non-secure origins", Work in Progress, Internet-Draft, 2407 draft-ietf-httpbis-cookie-alone-01, 5 September 2016, 2408 . 2411 [I-D.ietf-httpbis-cookie-prefixes] 2412 West, M., "Cookie Prefixes", Work in Progress, Internet- 2413 Draft, draft-ietf-httpbis-cookie-prefixes-00, 23 February 2414 2016, . 2417 [I-D.ietf-httpbis-cookie-same-site] 2418 West, M. and M. Goodwin, "Same-Site Cookies", Work in 2419 Progress, Internet-Draft, draft-ietf-httpbis-cookie-same- 2420 site-00, 20 June 2016, . 2423 [prerendering] 2424 Bentzel, C., "Chrome Prerendering", n.d., 2425 . 2428 [PSL] "Public Suffix List", n.d., 2429 . 2431 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 2432 DOI 10.17487/RFC2818, May 2000, 2433 . 2435 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2436 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2437 2003, . 2439 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 2440 Procedures for Message Header Fields", BCP 90, RFC 3864, 2441 DOI 10.17487/RFC3864, September 2004, 2442 . 2444 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2445 Resource Identifier (URI): Generic Syntax", STD 66, 2446 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2447 . 2449 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2450 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 2451 . 2453 [RFC5895] Resnick, P. and P. Hoffman, "Mapping Characters for 2454 Internationalized Domain Names in Applications (IDNA) 2455 2008", RFC 5895, DOI 10.17487/RFC5895, September 2010, 2456 . 2458 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 2459 DOI 10.17487/RFC6265, April 2011, 2460 . 2462 [RFC7034] Ross, D. and T. Gondrom, "HTTP Header Field X-Frame- 2463 Options", RFC 7034, DOI 10.17487/RFC7034, October 2013, 2464 . 2466 [UTS46] Davis, M. and M. Suignard, "Unicode IDNA Compatibility 2467 Processing", UNICODE Unicode Technical Standards # 46, 2468 June 2016, . 2470 Appendix A. Changes 2472 A.1. draft-ietf-httpbis-rfc6265bis-00 2474 * Port [RFC6265] to Markdown. No (intentional) normative changes. 2476 A.2. draft-ietf-httpbis-rfc6265bis-01 2478 * Fixes to formatting caused by mistakes in the initial port to 2479 Markdown: 2481 - https://github.com/httpwg/http-extensions/issues/243 2482 (https://github.com/httpwg/http-extensions/issues/243) 2484 - https://github.com/httpwg/http-extensions/issues/246 2485 (https://github.com/httpwg/http-extensions/issues/246) 2487 * Addresses errata 3444 by updating the "path-value" and "extension- 2488 av" grammar, errata 4148 by updating the "day-of-month", "year", 2489 and "time" grammar, and errata 3663 by adding the requested note. 2490 https://www.rfc-editor.org/errata_search.php?rfc=6265 2491 (https://www.rfc-editor.org/errata_search.php?rfc=6265) 2493 * Dropped "Cookie2" and "Set-Cookie2" from the IANA Considerations 2494 section: https://github.com/httpwg/http-extensions/issues/247 2495 (https://github.com/httpwg/http-extensions/issues/247) 2497 * Merged the recommendations from [I-D.ietf-httpbis-cookie-alone], 2498 removing the ability for a non-secure origin to set cookies with a 2499 'secure' flag, and to overwrite cookies whose 'secure' flag is 2500 true. 2502 * Merged the recommendations from 2503 [I-D.ietf-httpbis-cookie-prefixes], adding "__Secure-" and 2504 "__Host-" cookie name prefix processing instructions. 2506 A.3. draft-ietf-httpbis-rfc6265bis-02 2508 * Merged the recommendations from 2509 [I-D.ietf-httpbis-cookie-same-site], adding support for the 2510 "SameSite" attribute. 2512 * Closed a number of editorial bugs: 2514 - Clarified address bar behavior for SameSite cookies: 2515 https://github.com/httpwg/http-extensions/issues/201 2516 (https://github.com/httpwg/http-extensions/issues/201) 2518 - Added the word "Cookies" to the document's name: 2519 https://github.com/httpwg/http-extensions/issues/204 2520 (https://github.com/httpwg/http-extensions/issues/204) 2522 - Clarified that the "__Host-" prefix requires an explicit "Path" 2523 attribute: https://github.com/httpwg/http-extensions/issues/222 2524 (https://github.com/httpwg/http-extensions/issues/222) 2526 - Expanded the options for dealing with third-party cookies to 2527 include a brief mention of partitioning based on first-party: 2528 https://github.com/httpwg/http-extensions/issues/248 2529 (https://github.com/httpwg/http-extensions/issues/248) 2531 - Noted that double-quotes in cookie values are part of the 2532 value, and are not stripped: https://github.com/httpwg/http- 2533 extensions/issues/295 (https://github.com/httpwg/http- 2534 extensions/issues/295) 2536 - Fixed the "site for cookies" algorithm to return something that 2537 makes sense: https://github.com/httpwg/http-extensions/ 2538 issues/302 (https://github.com/httpwg/http-extensions/ 2539 issues/302) 2541 A.4. draft-ietf-httpbis-rfc6265bis-03 2543 * Clarified handling of invalid SameSite values: 2544 https://github.com/httpwg/http-extensions/issues/389 2545 (https://github.com/httpwg/http-extensions/issues/389) 2547 * Reflect widespread implementation practice of including a cookie's 2548 "host-only-flag" when calculating its uniqueness: 2549 https://github.com/httpwg/http-extensions/issues/199 2550 (https://github.com/httpwg/http-extensions/issues/199) 2552 * Introduced an explicit "None" value for the SameSite attribute: 2553 https://github.com/httpwg/http-extensions/issues/788 2554 (https://github.com/httpwg/http-extensions/issues/788) 2556 A.5. draft-ietf-httpbis-rfc6265bis-04 2558 * Allow "SameSite" cookies to be set for all top-level navigations. 2559 https://github.com/httpwg/http-extensions/issues/594 2560 (https://github.com/httpwg/http-extensions/issues/594) 2562 * Treat "Set-Cookie: token" as creating the cookie "("", "token")": 2563 https://github.com/httpwg/http-extensions/issues/159 2564 (https://github.com/httpwg/http-extensions/issues/159) 2566 * Reject cookies with neither name nor value (e.g. "Set-Cookie: =" 2567 and "Set-Cookie:": https://github.com/httpwg/http-extensions/ 2568 issues/159 (https://github.com/httpwg/http-extensions/issues/159) 2570 * Clarified behavior of multiple "SameSite" attributes in a cookie 2571 string: https://github.com/httpwg/http-extensions/issues/901 2572 (https://github.com/httpwg/http-extensions/issues/901) 2574 A.6. draft-ietf-httpbis-rfc6265bis-05 2576 * Typos and editorial fixes: https://github.com/httpwg/http- 2577 extensions/pull/1035 (https://github.com/httpwg/http-extensions/ 2578 pull/1035), https://github.com/httpwg/http-extensions/pull/1038 2579 (https://github.com/httpwg/http-extensions/pull/1038), 2580 https://github.com/httpwg/http-extensions/pull/1040 2581 (https://github.com/httpwg/http-extensions/pull/1040), 2582 https://github.com/httpwg/http-extensions/pull/1047 2583 (https://github.com/httpwg/http-extensions/pull/1047). 2585 A.7. draft-ietf-httpbis-rfc6265bis-06 2587 * Editorial fixes: https://github.com/httpwg/http-extensions/ 2588 issues/1059 (https://github.com/httpwg/http-extensions/ 2589 issues/1059), https://github.com/httpwg/http-extensions/ 2590 issues/1158 (https://github.com/httpwg/http-extensions/ 2591 issues/1158). 2593 * Created a registry for cookie attribute names: 2594 https://github.com/httpwg/http-extensions/pull/1060 2595 (https://github.com/httpwg/http-extensions/pull/1060). 2597 * Tweaks to ABNF for "cookie-pair" and the "Cookie" header 2598 production: https://github.com/httpwg/http-extensions/issues/1074 2599 (https://github.com/httpwg/http-extensions/issues/1074), 2600 https://github.com/httpwg/http-extensions/issues/1119 2601 (https://github.com/httpwg/http-extensions/issues/1119). 2603 * Fixed serialization for nameless/valueless cookies: 2604 https://github.com/httpwg/http-extensions/pull/1143 2605 (https://github.com/httpwg/http-extensions/pull/1143). 2607 * Converted a normative reference to Mozilla's Public Suffix List 2608 [PSL] into an informative reference: https://github.com/httpwg/ 2609 http-extensions/issues/1159 (https://github.com/httpwg/http- 2610 extensions/issues/1159). 2612 A.8. draft-ietf-httpbis-rfc6265bis-07 2614 * Moved instruction to ignore cookies with empty cookie-name and 2615 cookie-value from Section 5.4 to Section 5.5 to ensure that they 2616 apply to cookies created without parsing a cookie string: 2617 https://github.com/httpwg/http-extensions/issues/1234 2618 (https://github.com/httpwg/http-extensions/issues/1234). 2620 * Add a default enforcement value to the "same-site-flag", 2621 equivalent to "SameSite=Lax": https://github.com/httpwg/http- 2622 extensions/pull/1325 (https://github.com/httpwg/http-extensions/ 2623 pull/1325). 2625 * Require a Secure attribute for "SameSite=None": 2626 https://github.com/httpwg/http-extensions/pull/1323 2627 (https://github.com/httpwg/http-extensions/pull/1323). 2629 * Consider scheme when running the same-site algorithm: 2630 https://github.com/httpwg/http-extensions/pull/1324 2631 (https://github.com/httpwg/http-extensions/pull/1324). 2633 A.9. draft-ietf-httpbis-rfc6265bis-08 2635 * Define "same-site" for reload navigation requests, e.g. those 2636 triggered via user interface elements: https://github.com/httpwg/ 2637 http-extensions/pull/1384 (https://github.com/httpwg/http- 2638 extensions/pull/1384) 2640 * Consider redirects when defining same-site: 2641 https://github.com/httpwg/http-extensions/pull/1348 2642 (https://github.com/httpwg/http-extensions/pull/1348) 2644 * Align on using HTML terminology for origins: 2645 https://github.com/httpwg/http-extensions/pull/1416 2646 (https://github.com/httpwg/http-extensions/pull/1416) 2648 * Modify cookie parsing and creation algorithms in Section 5.4 and 2649 Section 5.5 to explicitly handle control characters: 2650 https://github.com/httpwg/http-extensions/pull/1420 2651 (https://github.com/httpwg/http-extensions/pull/1420) 2653 * Refactor cookie retrieval algorithm to support non-HTTP APIs: 2654 https://github.com/httpwg/http-extensions/pull/1428 2655 (https://github.com/httpwg/http-extensions/pull/1428) 2657 * Define "Lax-allowing-unsafe" SameSite enforcement mode: 2658 https://github.com/httpwg/http-extensions/pull/1435 2659 (https://github.com/httpwg/http-extensions/pull/1435) 2661 * Consistently use "header field" (vs 'header"): 2662 https://github.com/httpwg/http-extensions/pull/1527 2663 (https://github.com/httpwg/http-extensions/pull/1527) 2665 Acknowledgements 2667 RFC 6265 was written by Adam Barth. This document is an update of 2668 RFC 6265, adding features and aligning the specification with the 2669 reality of today's deployments. Here, we're standing upon the 2670 shoulders of a giant since the majority of the text is still Adam's. 2672 Authors' Addresses 2674 Lily Chen (editor) 2675 Google LLC 2677 Email: chlily@google.com 2679 Steven Englehardt (editor) 2680 Mozilla 2682 Email: senglehardt@mozilla.com 2684 Mike West (editor) 2685 Google LLC 2687 Email: mkwst@google.com 2688 URI: https://mikewest.org/ 2689 John Wilander (editor) 2690 Apple, Inc 2692 Email: wilander@apple.com