idnits 2.17.1 draft-ietf-httpbis-rfc6265bis-10.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 : ---------------------------------------------------------------------------- No issues found here. 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 (24 April 2022) is 734 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' -- 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 2109 (Obsoleted by RFC 2965) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 10 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: 26 October 2022 M. West, Ed. 7 Google LLC 8 J. Wilander, Ed. 9 Apple, Inc 10 24 April 2022 12 Cookies: HTTP State Management Mechanism 13 draft-ietf-httpbis-rfc6265bis-10 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 About This Document 27 This note is to be removed before publishing as an RFC. 29 Status information for this document may be found at 30 https://datatracker.ietf.org/doc/draft-ietf-httpbis-rfc6265bis/. 32 Discussion of this document takes place on the HTTP Working Group 33 mailing list (mailto:ietf-http-wg@w3.org), which is archived at 34 https://lists.w3.org/Archives/Public/ietf-http-wg/. Working Group 35 information can be found at https://httpwg.org/. 37 Source for this draft and an issue tracker can be found at 38 https://github.com/httpwg/http-extensions/labels/6265bis. 40 Status of This Memo 42 This Internet-Draft is submitted in full conformance with the 43 provisions of BCP 78 and BCP 79. 45 Internet-Drafts are working documents of the Internet Engineering 46 Task Force (IETF). Note that other groups may also distribute 47 working documents as Internet-Drafts. The list of current Internet- 48 Drafts is at https://datatracker.ietf.org/drafts/current/. 50 Internet-Drafts are draft documents valid for a maximum of six months 51 and may be updated, replaced, or obsoleted by other documents at any 52 time. It is inappropriate to use Internet-Drafts as reference 53 material or to cite them other than as "work in progress." 55 This Internet-Draft will expire on 26 October 2022. 57 Copyright Notice 59 Copyright (c) 2022 IETF Trust and the persons identified as the 60 document authors. All rights reserved. 62 This document is subject to BCP 78 and the IETF Trust's Legal 63 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 64 license-info) in effect on the date of publication of this document. 65 Please review these documents carefully, as they describe your rights 66 and restrictions with respect to this document. Code Components 67 extracted from this document must include Revised BSD License text as 68 described in Section 4.e of the Trust Legal Provisions and are 69 provided without warranty as described in the Revised BSD License. 71 This document may contain material from IETF Documents or IETF 72 Contributions published or made publicly available before November 73 10, 2008. The person(s) controlling the copyright in some of this 74 material may not have granted the IETF Trust the right to allow 75 modifications of such material outside the IETF Standards Process. 76 Without obtaining an adequate license from the person(s) controlling 77 the copyright in such materials, this document may not be modified 78 outside the IETF Standards Process, and derivative works of it may 79 not be created outside the IETF Standards Process, except to format 80 it for publication as an RFC or to translate it into languages other 81 than English. 83 Table of Contents 85 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 86 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 5 87 2.1. Conformance Criteria . . . . . . . . . . . . . . . . . . 5 88 2.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 6 89 2.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 90 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 7 91 3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8 92 4. Server Requirements . . . . . . . . . . . . . . . . . . . . . 9 93 4.1. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . 9 94 4.1.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . 10 95 4.1.2. Semantics (Non-Normative) . . . . . . . . . . . . . . 11 96 4.1.3. Cookie Name Prefixes . . . . . . . . . . . . . . . . 15 97 4.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . 16 98 4.2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . 16 99 4.2.2. Semantics . . . . . . . . . . . . . . . . . . . . . . 16 100 5. User Agent Requirements . . . . . . . . . . . . . . . . . . . 17 101 5.1. Subcomponent Algorithms . . . . . . . . . . . . . . . . . 17 102 5.1.1. Dates . . . . . . . . . . . . . . . . . . . . . . . . 17 103 5.1.2. Canonicalized Host Names . . . . . . . . . . . . . . 19 104 5.1.3. Domain Matching . . . . . . . . . . . . . . . . . . . 20 105 5.1.4. Paths and Path-Match . . . . . . . . . . . . . . . . 20 106 5.2. "Same-site" and "cross-site" Requests . . . . . . . . . . 21 107 5.2.1. Document-based requests . . . . . . . . . . . . . . . 21 108 5.2.2. Worker-based requests . . . . . . . . . . . . . . . . 22 109 5.3. Ignoring Set-Cookie Header Fields . . . . . . . . . . . . 23 110 5.4. The Set-Cookie Header Field . . . . . . . . . . . . . . . 24 111 5.4.1. The Expires Attribute . . . . . . . . . . . . . . . . 26 112 5.4.2. The Max-Age Attribute . . . . . . . . . . . . . . . . 27 113 5.4.3. The Domain Attribute . . . . . . . . . . . . . . . . 27 114 5.4.4. The Path Attribute . . . . . . . . . . . . . . . . . 28 115 5.4.5. The Secure Attribute . . . . . . . . . . . . . . . . 28 116 5.4.6. The HttpOnly Attribute . . . . . . . . . . . . . . . 28 117 5.4.7. The SameSite Attribute . . . . . . . . . . . . . . . 28 118 5.5. Storage Model . . . . . . . . . . . . . . . . . . . . . . 30 119 5.6. Retrieval Model . . . . . . . . . . . . . . . . . . . . . 36 120 5.6.1. The Cookie Header Field . . . . . . . . . . . . . . . 36 121 5.6.2. Non-HTTP APIs . . . . . . . . . . . . . . . . . . . . 36 122 5.6.3. Retrieval Algorithm . . . . . . . . . . . . . . . . . 37 123 6. Implementation Considerations . . . . . . . . . . . . . . . . 39 124 6.1. Limits . . . . . . . . . . . . . . . . . . . . . . . . . 39 125 6.2. Application Programming Interfaces . . . . . . . . . . . 39 126 6.3. IDNA Dependency and Migration . . . . . . . . . . . . . . 40 127 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 40 128 7.1. Third-Party Cookies . . . . . . . . . . . . . . . . . . . 41 129 7.2. Cookie Policy . . . . . . . . . . . . . . . . . . . . . . 41 130 7.3. User Controls . . . . . . . . . . . . . . . . . . . . . . 42 131 7.4. Expiration Dates . . . . . . . . . . . . . . . . . . . . 42 132 8. Security Considerations . . . . . . . . . . . . . . . . . . . 43 133 8.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 43 134 8.2. Ambient Authority . . . . . . . . . . . . . . . . . . . . 43 135 8.3. Clear Text . . . . . . . . . . . . . . . . . . . . . . . 44 136 8.4. Session Identifiers . . . . . . . . . . . . . . . . . . . 44 137 8.5. Weak Confidentiality . . . . . . . . . . . . . . . . . . 45 138 8.6. Weak Integrity . . . . . . . . . . . . . . . . . . . . . 46 139 8.7. Reliance on DNS . . . . . . . . . . . . . . . . . . . . . 47 140 8.8. SameSite Cookies . . . . . . . . . . . . . . . . . . . . 47 141 8.8.1. Defense in depth . . . . . . . . . . . . . . . . . . 47 142 8.8.2. Top-level Navigations . . . . . . . . . . . . . . . . 47 143 8.8.3. Mashups and Widgets . . . . . . . . . . . . . . . . . 48 144 8.8.4. Server-controlled . . . . . . . . . . . . . . . . . . 48 145 8.8.5. Reload navigations . . . . . . . . . . . . . . . . . 48 146 8.8.6. Top-level requests with "unsafe" methods . . . . . . 49 147 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 50 148 9.1. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . 50 149 9.2. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . 50 150 9.3. Cookie Attribute Registry . . . . . . . . . . . . . . . . 50 151 9.3.1. Procedure . . . . . . . . . . . . . . . . . . . . . . 51 152 9.3.2. Registration . . . . . . . . . . . . . . . . . . . . 51 153 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 51 154 10.1. Normative References . . . . . . . . . . . . . . . . . . 51 155 10.2. Informative References . . . . . . . . . . . . . . . . . 53 156 Appendix A. Changes . . . . . . . . . . . . . . . . . . . . . . 55 157 A.1. draft-ietf-httpbis-rfc6265bis-00 . . . . . . . . . . . . 55 158 A.2. draft-ietf-httpbis-rfc6265bis-01 . . . . . . . . . . . . 55 159 A.3. draft-ietf-httpbis-rfc6265bis-02 . . . . . . . . . . . . 56 160 A.4. draft-ietf-httpbis-rfc6265bis-03 . . . . . . . . . . . . 56 161 A.5. draft-ietf-httpbis-rfc6265bis-04 . . . . . . . . . . . . 57 162 A.6. draft-ietf-httpbis-rfc6265bis-05 . . . . . . . . . . . . 57 163 A.7. draft-ietf-httpbis-rfc6265bis-06 . . . . . . . . . . . . 57 164 A.8. draft-ietf-httpbis-rfc6265bis-07 . . . . . . . . . . . . 58 165 A.9. draft-ietf-httpbis-rfc6265bis-08 . . . . . . . . . . . . 58 166 A.10. draft-ietf-httpbis-rfc6265bis-09 . . . . . . . . . . . . 59 167 A.11. draft-ietf-httpbis-rfc6265bis-10 . . . . . . . . . . . . 59 168 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 60 169 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 60 171 1. Introduction 173 This document defines the HTTP Cookie and Set-Cookie header fields. 174 Using the Set-Cookie header field, an HTTP server can pass name/value 175 pairs and associated metadata (called cookies) to a user agent. When 176 the user agent makes subsequent requests to the server, the user 177 agent uses the metadata and other information to determine whether to 178 return the name/value pairs in the Cookie header field. 180 Although simple on their surface, cookies have a number of 181 complexities. For example, the server indicates a scope for each 182 cookie when sending it to the user agent. The scope indicates the 183 maximum amount of time in which the user agent should return the 184 cookie, the servers to which the user agent should return the cookie, 185 and the URI schemes for which the cookie is applicable. 187 For historical reasons, cookies contain a number of security and 188 privacy infelicities. For example, a server can indicate that a 189 given cookie is intended for "secure" connections, but the Secure 190 attribute does not provide integrity in the presence of an active 191 network attacker. Similarly, cookies for a given host are shared 192 across all the ports on that host, even though the usual "same-origin 193 policy" used by web browsers isolates content retrieved via different 194 ports. 196 There are two audiences for this specification: developers of cookie- 197 generating servers and developers of cookie-consuming user agents. 199 To maximize interoperability with user agents, servers SHOULD limit 200 themselves to the well-behaved profile defined in Section 4 when 201 generating cookies. 203 User agents MUST implement the more liberal processing rules defined 204 in Section 5, in order to maximize interoperability with existing 205 servers that do not conform to the well-behaved profile defined in 206 Section 4. 208 This document specifies the syntax and semantics of these header 209 fields as they are actually used on the Internet. In particular, 210 this document does not create new syntax or semantics beyond those in 211 use today. The recommendations for cookie generation provided in 212 Section 4 represent a preferred subset of current server behavior, 213 and even the more liberal cookie processing algorithm provided in 214 Section 5 does not recommend all of the syntactic and semantic 215 variations in use today. Where some existing software differs from 216 the recommended protocol in significant ways, the document contains a 217 note explaining the difference. 219 This document obsoletes [RFC6265]. 221 2. Conventions 223 2.1. Conformance Criteria 225 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 226 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 227 document are to be interpreted as described in [RFC2119]. 229 Requirements phrased in the imperative as part of algorithms (such as 230 "strip any leading space characters" or "return false and abort these 231 steps") are to be interpreted with the meaning of the key word 232 ("MUST", "SHOULD", "MAY", etc.) used in introducing the algorithm. 234 Conformance requirements phrased as algorithms or specific steps can 235 be implemented in any manner, so long as the end result is 236 equivalent. In particular, the algorithms defined in this 237 specification are intended to be easy to understand and are not 238 intended to be performant. 240 2.2. Syntax Notation 242 This specification uses the Augmented Backus-Naur Form (ABNF) 243 notation of [RFC5234]. 245 The following core rules are included by reference, as defined in 246 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 247 (CR LF), CTLs (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 248 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), NUL (null octet), 249 OCTET (any 8-bit sequence of data except NUL), SP (space), HTAB 250 (horizontal tab), CHAR (any [USASCII] character), VCHAR (any visible 251 [USASCII] character), and WSP (whitespace). 253 The OWS (optional whitespace) and BWS (bad whitespace) rules are 254 defined in Section 5.6.3 of [HTTPSEM]. 256 2.3. Terminology 258 The terms "user agent", "client", "server", "proxy", and "origin 259 server" have the same meaning as in the HTTP/1.1 specification 260 ([HTTPSEM], Section 3). 262 The request-host is the name of the host, as known by the user agent, 263 to which the user agent is sending an HTTP request or from which it 264 is receiving an HTTP response (i.e., the name of the host to which it 265 sent the corresponding HTTP request). 267 The term request-uri refers to "target URI" as defined in Section 7.1 268 of [HTTPSEM]. 270 Two sequences of octets are said to case-insensitively match each 271 other if and only if they are equivalent under the i;ascii-casemap 272 collation defined in [RFC4790]. 274 The term string means a sequence of non-NUL octets. 276 The terms "active document", "ancestor browsing context", "browsing 277 context", "dedicated worker", "Document", "nested browsing context", 278 "opaque origin", "parent browsing context", "sandboxed origin 279 browsing context flag", "shared worker", "the worker's Documents", 280 "top-level browsing context", and "WorkerGlobalScope" are defined in 281 [HTML]. 283 "Service Workers" are defined in the Service Workers specification 284 [SERVICE-WORKERS]. 286 The term "origin", the mechanism of deriving an origin from a URI, 287 and the "the same" matching algorithm for origins are defined in 288 [RFC6454]. 290 "Safe" HTTP methods include GET, HEAD, OPTIONS, and TRACE, as defined 291 in Section 9.2.1 of [HTTPSEM]. 293 A domain's "public suffix" is the portion of a domain that is 294 controlled by a public registry, such as "com", "co.uk", and 295 "pvt.k12.wy.us". A domain's "registrable domain" is the domain's 296 public suffix plus the label to its left. That is, for 297 https://www.site.example, the public suffix is example, and the 298 registrable domain is site.example. Whenever possible, user agents 299 SHOULD use an up-to-date public suffix list, such as the one 300 maintained by the Mozilla project at [PSL]. 302 The term "request", as well as a request's "client", "current url", 303 "method", "target browsing context", and "url list", are defined in 304 [FETCH]. 306 The term "non-HTTP APIs" refers to non-HTTP mechanisms used to set 307 and retrieve cookies, such as a web browser API that exposes cookies 308 to scripts. 310 3. Overview 312 This section outlines a way for an origin server to send state 313 information to a user agent and for the user agent to return the 314 state information to the origin server. 316 To store state, the origin server includes a Set-Cookie header field 317 in an HTTP response. In subsequent requests, the user agent returns 318 a Cookie request header field to the origin server. The Cookie 319 header field contains cookies the user agent received in previous 320 Set-Cookie header fields. The origin server is free to ignore the 321 Cookie header field or use its contents for an application-defined 322 purpose. 324 Origin servers MAY send a Set-Cookie response header field with any 325 response. An origin server can include multiple Set-Cookie header 326 fields in a single response. The presence of a Cookie or a Set- 327 Cookie header field does not preclude HTTP caches from storing and 328 reusing a response. 330 Origin servers SHOULD NOT fold multiple Set-Cookie header fields into 331 a single header field. The usual mechanism for folding HTTP headers 332 fields (i.e., as defined in Section 5.3 of [HTTPSEM]) might change 333 the semantics of the Set-Cookie header field because the %x2C (",") 334 character is used by Set-Cookie in a way that conflicts with such 335 folding. 337 User agents MAY ignore Set-Cookie header fields based on response 338 status codes or the user agent's cookie policy (see Section 5.3). 340 3.1. Examples 342 Using the Set-Cookie header field, a server can send the user agent a 343 short string in an HTTP response that the user agent will return in 344 future HTTP requests that are within the scope of the cookie. For 345 example, the server can send the user agent a "session identifier" 346 named SID with the value 31d4d96e407aad42. The user agent then 347 returns the session identifier in subsequent requests. 349 == Server -> User Agent == 351 Set-Cookie: SID=31d4d96e407aad42 353 == User Agent -> Server == 355 Cookie: SID=31d4d96e407aad42 357 The server can alter the default scope of the cookie using the Path 358 and Domain attributes. For example, the server can instruct the user 359 agent to return the cookie to every path and every subdomain of 360 site.example. 362 == Server -> User Agent == 364 Set-Cookie: SID=31d4d96e407aad42; Path=/; Domain=site.example 366 == User Agent -> Server == 368 Cookie: SID=31d4d96e407aad42 370 As shown in the next example, the server can store multiple cookies 371 at the user agent. For example, the server can store a session 372 identifier as well as the user's preferred language by returning two 373 Set-Cookie header fields. Notice that the server uses the Secure and 374 HttpOnly attributes to provide additional security protections for 375 the more sensitive session identifier (see Section 4.1.2). 377 == Server -> User Agent == 379 Set-Cookie: SID=31d4d96e407aad42; Path=/; Secure; HttpOnly 380 Set-Cookie: lang=en-US; Path=/; Domain=site.example 382 == User Agent -> Server == 384 Cookie: SID=31d4d96e407aad42; lang=en-US 386 Notice that the Cookie header field above contains two cookies, one 387 named SID and one named lang. If the server wishes the user agent to 388 persist the cookie over multiple "sessions" (e.g., user agent 389 restarts), the server can specify an expiration date in the Expires 390 attribute. Note that the user agent might delete the cookie before 391 the expiration date if the user agent's cookie store exceeds its 392 quota or if the user manually deletes the server's cookie. 394 == Server -> User Agent == 396 Set-Cookie: lang=en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT 398 == User Agent -> Server == 400 Cookie: SID=31d4d96e407aad42; lang=en-US 402 Finally, to remove a cookie, the server returns a Set-Cookie header 403 field with an expiration date in the past. The server will be 404 successful in removing the cookie only if the Path and the Domain 405 attribute in the Set-Cookie header field match the values used when 406 the cookie was created. 408 == Server -> User Agent == 410 Set-Cookie: lang=; Expires=Sun, 06 Nov 1994 08:49:37 GMT 412 == User Agent -> Server == 414 Cookie: SID=31d4d96e407aad42 416 4. Server Requirements 418 This section describes the syntax and semantics of a well-behaved 419 profile of the Cookie and Set-Cookie header fields. 421 4.1. Set-Cookie 423 The Set-Cookie HTTP response header field is used to send cookies 424 from the server to the user agent. 426 4.1.1. Syntax 428 Informally, the Set-Cookie response header field contains a cookie, 429 which begins with a name-value-pair, followed by zero or more 430 attribute-value pairs. Servers SHOULD NOT send Set-Cookie header 431 fields that fail to conform to the following grammar: 433 set-cookie = set-cookie-string 434 set-cookie-string = BWS cookie-pair *( BWS ";" OWS cookie-av ) 435 cookie-pair = cookie-name BWS "=" BWS cookie-value 436 cookie-name = 1*cookie-octet 437 cookie-value = *cookie-octet / ( DQUOTE *cookie-octet DQUOTE ) 438 cookie-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E 439 / %x80-FF 440 ; octets excluding CTLs, 441 ; whitespace DQUOTE, comma, semicolon, 442 ; and backslash 444 cookie-av = expires-av / max-age-av / domain-av / 445 path-av / secure-av / httponly-av / 446 samesite-av / extension-av 447 expires-av = "Expires" BWS "=" BWS sane-cookie-date 448 sane-cookie-date = 449 450 max-age-av = "Max-Age" BWS "=" BWS non-zero-digit *DIGIT 451 non-zero-digit = %x31-39 452 ; digits 1 through 9 453 domain-av = "Domain" BWS "=" BWS domain-value 454 domain-value = 455 ; see details below 456 path-av = "Path" BWS "=" BWS path-value 457 path-value = *av-octet 458 secure-av = "Secure" 459 httponly-av = "HttpOnly" 460 samesite-av = "SameSite" BWS "=" BWS samesite-value 461 samesite-value = "Strict" / "Lax" / "None" 462 extension-av = *av-octet 463 av-octet = %x20-3A / %x3C-7E 464 ; any CHAR except CTLs or ";" 466 Note that some of the grammatical terms above reference documents 467 that use different grammatical notations than this document (which 468 uses ABNF from [RFC5234]). 470 The semantics of the cookie-value are not defined by this document. 472 To maximize compatibility with user agents, servers that wish to 473 store arbitrary data in a cookie-value SHOULD encode that data, for 474 example, using Base64 [RFC4648]. 476 The domain-value is a subdomain as defined by [RFC1034], Section 3.5, 477 and as enhanced by [RFC1123], Section 2.1. Thus, domain-value is a 478 string of [USASCII] characters, such as one obtained by applying the 479 "ToASCII" operation defined in Section 4 of [RFC3490]. 481 Per the grammar above, the cookie-value MAY be wrapped in DQUOTE 482 characters. Note that in this case, the initial and trailing DQUOTE 483 characters are not stripped. They are part of the cookie-value, and 484 will be included in Cookie header fields sent to the server. 486 The portions of the set-cookie-string produced by the cookie-av term 487 are known as attributes. To maximize compatibility with user agents, 488 servers SHOULD NOT produce two attributes with the same name in the 489 same set-cookie-string. (See Section 5.5 for how user agents handle 490 this case.) 492 Servers SHOULD NOT include more than one Set-Cookie header field in 493 the same response with the same cookie-name. (See Section 5.4 for 494 how user agents handle this case.) 496 If a server sends multiple responses containing Set-Cookie header 497 fields concurrently to the user agent (e.g., when communicating with 498 the user agent over multiple sockets), these responses create a "race 499 condition" that can lead to unpredictable behavior. 501 NOTE: Some existing user agents differ in their interpretation of 502 two-digit years. To avoid compatibility issues, servers SHOULD use 503 the rfc1123-date format, which requires a four-digit year. 505 NOTE: Some user agents store and process dates in cookies as 32-bit 506 UNIX time_t values. Implementation bugs in the libraries supporting 507 time_t processing on some systems might cause such user agents to 508 process dates after the year 2038 incorrectly. 510 4.1.2. Semantics (Non-Normative) 512 This section describes simplified semantics of the Set-Cookie header 513 field. These semantics are detailed enough to be useful for 514 understanding the most common uses of cookies by servers. The full 515 semantics are described in Section 5. 517 When the user agent receives a Set-Cookie header field, the user 518 agent stores the cookie together with its attributes. Subsequently, 519 when the user agent makes an HTTP request, the user agent includes 520 the applicable, non-expired cookies in the Cookie header field. 522 If the user agent receives a new cookie with the same cookie-name, 523 domain-value, and path-value as a cookie that it has already stored, 524 the existing cookie is evicted and replaced with the new cookie. 525 Notice that servers can delete cookies by sending the user agent a 526 new cookie with an Expires attribute with a value in the past. 528 Unless the cookie's attributes indicate otherwise, the cookie is 529 returned only to the origin server (and not, for example, to any 530 subdomains), and it expires at the end of the current session (as 531 defined by the user agent). User agents ignore unrecognized cookie 532 attributes (but not the entire cookie). 534 4.1.2.1. The Expires Attribute 536 The Expires attribute indicates the maximum lifetime of the cookie, 537 represented as the date and time at which the cookie expires. The 538 user agent is not required to retain the cookie until the specified 539 date has passed. In fact, user agents often evict cookies due to 540 memory pressure or privacy concerns. 542 The user agent MUST limit the maximum value of the Expires attribute. 543 The limit SHOULD NOT be greater than 400 days (34560000 seconds) in 544 the future. The RECOMMENDED limit is 400 days in the future, but the 545 user agent MAY adjust the limit (see Section 7.2). Expires 546 attributes that are greater than the limit MUST be reduced to the 547 limit. 549 4.1.2.2. The Max-Age Attribute 551 The Max-Age attribute indicates the maximum lifetime of the cookie, 552 represented as the number of seconds until the cookie expires. The 553 user agent is not required to retain the cookie for the specified 554 duration. In fact, user agents often evict cookies due to memory 555 pressure or privacy concerns. 557 The user agent MUST limit the maximum value of the Max-Age attribute. 558 The limit SHOULD NOT be greater than 400 days (34560000 seconds) in 559 duration. The RECOMMENDED limit is 400 days in duration, but the 560 user agent MAY adjust the limit (see Section 7.2). Max-Age 561 attributes that are greater than the limit MUST be reduced to the 562 limit. 564 NOTE: Some existing user agents do not support the Max-Age attribute. 565 User agents that do not support the Max-Age attribute ignore the 566 attribute. 568 If a cookie has both the Max-Age and the Expires attribute, the Max- 569 Age attribute has precedence and controls the expiration date of the 570 cookie. If a cookie has neither the Max-Age nor the Expires 571 attribute, the user agent will retain the cookie until "the current 572 session is over" (as defined by the user agent). 574 4.1.2.3. The Domain Attribute 576 The Domain attribute specifies those hosts to which the cookie will 577 be sent. For example, if the value of the Domain attribute is 578 "site.example", the user agent will include the cookie in the Cookie 579 header field when making HTTP requests to site.example, 580 www.site.example, and www.corp.site.example. (Note that a leading 581 %x2E ("."), if present, is ignored even though that character is not 582 permitted, but a trailing %x2E ("."), if present, will cause the user 583 agent to ignore the attribute.) If the server omits the Domain 584 attribute, the user agent will return the cookie only to the origin 585 server. 587 WARNING: Some existing user agents treat an absent Domain attribute 588 as if the Domain attribute were present and contained the current 589 host name. For example, if site.example returns a Set-Cookie header 590 field without a Domain attribute, these user agents will erroneously 591 send the cookie to www.site.example as well. 593 The user agent will reject cookies unless the Domain attribute 594 specifies a scope for the cookie that would include the origin 595 server. For example, the user agent will accept a cookie with a 596 Domain attribute of "site.example" or of "foo.site.example" from 597 foo.site.example, but the user agent will not accept a cookie with a 598 Domain attribute of "bar.site.example" or of "baz.foo.site.example". 600 NOTE: For security reasons, many user agents are configured to reject 601 Domain attributes that correspond to "public suffixes". For example, 602 some user agents will reject Domain attributes of "com" or "co.uk". 603 (See Section 5.5 for more information.) 605 4.1.2.4. The Path Attribute 607 The scope of each cookie is limited to a set of paths, controlled by 608 the Path attribute. If the server omits the Path attribute, the user 609 agent will use the "directory" of the request-uri's path component as 610 the default value. (See Section 5.1.4 for more details.) 611 The user agent will include the cookie in an HTTP request only if the 612 path portion of the request-uri matches (or is a subdirectory of) the 613 cookie's Path attribute, where the %x2F ("/") character is 614 interpreted as a directory separator. 616 Although seemingly useful for isolating cookies between different 617 paths within a given host, the Path attribute cannot be relied upon 618 for security (see Section 8). 620 4.1.2.5. The Secure Attribute 622 The Secure attribute limits the scope of the cookie to "secure" 623 channels (where "secure" is defined by the user agent). When a 624 cookie has the Secure attribute, the user agent will include the 625 cookie in an HTTP request only if the request is transmitted over a 626 secure channel (typically HTTP over Transport Layer Security (TLS) 627 [RFC2818]). 629 4.1.2.6. The HttpOnly Attribute 631 The HttpOnly attribute limits the scope of the cookie to HTTP 632 requests. In particular, the attribute instructs the user agent to 633 omit the cookie when providing access to cookies via non-HTTP APIs. 635 Note that the HttpOnly attribute is independent of the Secure 636 attribute: a cookie can have both the HttpOnly and the Secure 637 attribute. 639 4.1.2.7. The SameSite Attribute 641 The "SameSite" attribute limits the scope of the cookie such that it 642 will only be attached to requests if those requests are same-site, as 643 defined by the algorithm in Section 5.2. For example, requests for 644 https://site.example/sekrit-image will attach same-site cookies if 645 and only if initiated from a context whose "site for cookies" is an 646 origin with a scheme and registered domain of "https" and 647 "site.example" respectively. 649 If the "SameSite" attribute's value is "Strict", the cookie will only 650 be sent along with "same-site" requests. If the value is "Lax", the 651 cookie will be sent with same-site requests, and with "cross-site" 652 top-level navigations, as described in Section 5.4.7.1. If the value 653 is "None", the cookie will be sent with same-site and cross-site 654 requests. If the "SameSite" attribute's value is something other 655 than these three known keywords, the attribute's value will be 656 subject to a default enforcement mode that is equivalent to "Lax". 658 The "SameSite" attribute affects cookie creation as well as delivery. 659 Cookies which assert "SameSite=Lax" or "SameSite=Strict" cannot be 660 set in responses to cross-site subresource requests, or cross-site 661 nested navigations. They can be set along with any top-level 662 navigation, cross-site or otherwise. 664 4.1.3. Cookie Name Prefixes 666 Section 8.5 and Section 8.6 of this document spell out some of the 667 drawbacks of cookies' historical implementation. In particular, it 668 is impossible for a server to have confidence that a given cookie was 669 set with a particular set of attributes. In order to provide such 670 confidence in a backwards-compatible way, two common sets of 671 requirements can be inferred from the first few characters of the 672 cookie's name. 674 The normative requirements for the prefixes described below are 675 detailed in the storage model algorithm defined in Section 5.5. 677 4.1.3.1. The "__Secure-" Prefix 679 If a cookie's name begins with a case-sensitive match for the string 680 __Secure-, then the cookie will have been set with a Secure 681 attribute. 683 For example, the following Set-Cookie header field would be rejected 684 by a conformant user agent, as it does not have a Secure attribute. 686 Set-Cookie: __Secure-SID=12345; Domain=site.example 688 Whereas the following Set-Cookie header field would be accepted if 689 set from a secure origin (e.g. "https://site.example/"), and rejected 690 otherwise: 692 Set-Cookie: __Secure-SID=12345; Domain=site.example; Secure 694 4.1.3.2. The "__Host-" Prefix 696 If a cookie's name begins with a case-sensitive match for the string 697 __Host-, then the cookie will have been set with a Secure attribute, 698 a Path attribute with a value of /, and no Domain attribute. 700 This combination yields a cookie that hews as closely as a cookie can 701 to treating the origin as a security boundary. The lack of a Domain 702 attribute ensures that the cookie's host-only-flag is true, locking 703 the cookie to a particular host, rather than allowing it to span 704 subdomains. Setting the Path to / means that the cookie is effective 705 for the entire host, and won't be overridden for specific paths. The 706 Secure attribute ensures that the cookie is unaltered by non-secure 707 origins, and won't span protocols. 709 Ports are the only piece of the origin model that __Host- cookies 710 continue to ignore. 712 For example, the following cookies would always be rejected: 714 Set-Cookie: __Host-SID=12345 715 Set-Cookie: __Host-SID=12345; Secure 716 Set-Cookie: __Host-SID=12345; Domain=site.example 717 Set-Cookie: __Host-SID=12345; Domain=site.example; Path=/ 718 Set-Cookie: __Host-SID=12345; Secure; Domain=site.example; Path=/ 720 While the following would be accepted if set from a secure origin 721 (e.g. "https://site.example/"), and rejected otherwise: 723 Set-Cookie: __Host-SID=12345; Secure; Path=/ 725 4.2. Cookie 727 4.2.1. Syntax 729 The user agent sends stored cookies to the origin server in the 730 Cookie header field. If the server conforms to the requirements in 731 Section 4.1 (and the user agent conforms to the requirements in 732 Section 5), the user agent will send a Cookie header field that 733 conforms to the following grammar: 735 cookie = cookie-string 736 cookie-string = cookie-pair *( ";" SP cookie-pair ) 738 4.2.2. Semantics 740 Each cookie-pair represents a cookie stored by the user agent. The 741 cookie-pair contains the cookie-name and cookie-value the user agent 742 received in the Set-Cookie header field. 744 Notice that the cookie attributes are not returned. In particular, 745 the server cannot determine from the Cookie field alone when a cookie 746 will expire, for which hosts the cookie is valid, for which paths the 747 cookie is valid, or whether the cookie was set with the Secure or 748 HttpOnly attributes. 750 The semantics of individual cookies in the Cookie header field are 751 not defined by this document. Servers are expected to imbue these 752 cookies with application-specific semantics. 754 Although cookies are serialized linearly in the Cookie header field, 755 servers SHOULD NOT rely upon the serialization order. In particular, 756 if the Cookie header field contains two cookies with the same name 757 (e.g., that were set with different Path or Domain attributes), 758 servers SHOULD NOT rely upon the order in which these cookies appear 759 in the header field. 761 5. User Agent Requirements 763 This section specifies the Cookie and Set-Cookie header fields in 764 sufficient detail that a user agent implementing these requirements 765 precisely can interoperate with existing servers (even those that do 766 not conform to the well-behaved profile described in Section 4). 768 A user agent could enforce more restrictions than those specified 769 herein (e.g., restrictions specified by its cookie policy, described 770 in Section 7.2). However, such additional restrictions may reduce 771 the likelihood that a user agent will be able to interoperate with 772 existing servers. 774 5.1. Subcomponent Algorithms 776 This section defines some algorithms used by user agents to process 777 specific subcomponents of the Cookie and Set-Cookie header fields. 779 5.1.1. Dates 781 The user agent MUST use an algorithm equivalent to the following 782 algorithm to parse a cookie-date. Note that the various boolean 783 flags defined as a part of the algorithm (i.e., found-time, found- 784 day-of-month, found-month, found-year) are initially "not set". 786 1. Using the grammar below, divide the cookie-date into date-tokens. 788 cookie-date = *delimiter date-token-list *delimiter 789 date-token-list = date-token *( 1*delimiter date-token ) 790 date-token = 1*non-delimiter 792 delimiter = %x09 / %x20-2F / %x3B-40 / %x5B-60 / %x7B-7E 793 non-delimiter = %x00-08 / %x0A-1F / DIGIT / ":" / ALPHA 794 / %x7F-FF 795 non-digit = %x00-2F / %x3A-FF 797 day-of-month = 1*2DIGIT [ non-digit *OCTET ] 798 month = ( "jan" / "feb" / "mar" / "apr" / 799 "may" / "jun" / "jul" / "aug" / 800 "sep" / "oct" / "nov" / "dec" ) *OCTET 801 year = 2*4DIGIT [ non-digit *OCTET ] 802 time = hms-time [ non-digit *OCTET ] 803 hms-time = time-field ":" time-field ":" time-field 804 time-field = 1*2DIGIT 806 2. Process each date-token sequentially in the order the date-tokens 807 appear in the cookie-date: 809 1. If the found-time flag is not set and the token matches the 810 time production, set the found-time flag and set the hour- 811 value, minute-value, and second-value to the numbers denoted 812 by the digits in the date-token, respectively. Skip the 813 remaining sub-steps and continue to the next date-token. 815 2. If the found-day-of-month flag is not set and the date-token 816 matches the day-of-month production, set the found-day-of- 817 month flag and set the day-of-month-value to the number 818 denoted by the date-token. Skip the remaining sub-steps and 819 continue to the next date-token. 821 3. If the found-month flag is not set and the date-token matches 822 the month production, set the found-month flag and set the 823 month-value to the month denoted by the date-token. Skip the 824 remaining sub-steps and continue to the next date-token. 826 4. If the found-year flag is not set and the date-token matches 827 the year production, set the found-year flag and set the 828 year-value to the number denoted by the date-token. Skip the 829 remaining sub-steps and continue to the next date-token. 831 3. If the year-value is greater than or equal to 70 and less than or 832 equal to 99, increment the year-value by 1900. 834 4. If the year-value is greater than or equal to 0 and less than or 835 equal to 69, increment the year-value by 2000. 837 1. NOTE: Some existing user agents interpret two-digit years 838 differently. 840 5. Abort these steps and fail to parse the cookie-date if: 842 * at least one of the found-day-of-month, found-month, found- 843 year, or found-time flags is not set, 845 * the day-of-month-value is less than 1 or greater than 31, 847 * the year-value is less than 1601, 849 * the hour-value is greater than 23, 851 * the minute-value is greater than 59, or 853 * the second-value is greater than 59. 855 (Note that leap seconds cannot be represented in this syntax.) 857 6. Let the parsed-cookie-date be the date whose day-of-month, month, 858 year, hour, minute, and second (in UTC) are the day-of-month- 859 value, the month-value, the year-value, the hour-value, the 860 minute-value, and the second-value, respectively. If no such 861 date exists, abort these steps and fail to parse the cookie-date. 863 7. Return the parsed-cookie-date as the result of this algorithm. 865 5.1.2. Canonicalized Host Names 867 A canonicalized host name is the string generated by the following 868 algorithm: 870 1. Convert the host name to a sequence of individual domain name 871 labels. 873 2. Convert each label that is not a Non-Reserved LDH (NR-LDH) label, 874 to an A-label (see Section 2.3.2.1 of [RFC5890] for the former 875 and latter), or to a "punycode label" (a label resulting from the 876 "ToASCII" conversion in Section 4 of [RFC3490]), as appropriate 877 (see Section 6.3 of this specification). 879 3. Concatenate the resulting labels, separated by a %x2E (".") 880 character. 882 5.1.3. Domain Matching 884 A string domain-matches a given domain string if at least one of the 885 following conditions hold: 887 * The domain string and the string are identical. (Note that both 888 the domain string and the string will have been canonicalized to 889 lower case at this point.) 891 * All of the following conditions hold: 893 - The domain string is a suffix of the string. 895 - The last character of the string that is not included in the 896 domain string is a %x2E (".") character. 898 - The string is a host name (i.e., not an IP address). 900 5.1.4. Paths and Path-Match 902 The user agent MUST use an algorithm equivalent to the following 903 algorithm to compute the default-path of a cookie: 905 1. Let uri-path be the path portion of the request-uri if such a 906 portion exists (and empty otherwise). 908 2. If the uri-path is empty or if the first character of the uri- 909 path is not a %x2F ("/") character, output %x2F ("/") and skip 910 the remaining steps. 912 3. If the uri-path contains no more than one %x2F ("/") character, 913 output %x2F ("/") and skip the remaining step. 915 4. Output the characters of the uri-path from the first character up 916 to, but not including, the right-most %x2F ("/"). 918 A request-path path-matches a given cookie-path if at least one of 919 the following conditions holds: 921 * The cookie-path and the request-path are identical. 923 Note that this differs from the rules in [RFC3986] for equivalence 924 of the path component, and hence two equivalent paths can have 925 different cookies. 927 * The cookie-path is a prefix of the request-path, and the last 928 character of the cookie-path is %x2F ("/"). 930 * The cookie-path is a prefix of the request-path, and the first 931 character of the request-path that is not included in the cookie- 932 path is a %x2F ("/") character. 934 5.2. "Same-site" and "cross-site" Requests 936 Two origins are same-site if they satisfy the "same site" criteria 937 defined in [SAMESITE]. A request is "same-site" if the following 938 criteria are true: 940 1. The request is not the result of a cross-site redirect. That is, 941 the origin of every url in the request's url list is same-site 942 with the request's current url's origin. 944 2. The request is not the result of a reload navigation triggered 945 through a user interface element (as defined by the user agent; 946 e.g., a request triggered by the user clicking a refresh button 947 on a toolbar). 949 3. The request's current url's origin is same-site with the 950 request's client's "site for cookies" (which is an origin), or if 951 the request has no client or the request's client is null. 953 Requests which are the result of a reload navigation triggered 954 through a user interface element are same-site if the reloaded 955 document was originally navigated to via a same-site request. A 956 request that is not "same-site" is instead "cross-site". 958 The request's client's "site for cookies" is calculated depending 959 upon its client's type, as described in the following subsections: 961 5.2.1. Document-based requests 963 The URI displayed in a user agent's address bar is the only security 964 context directly exposed to users, and therefore the only signal 965 users can reasonably rely upon to determine whether or not they trust 966 a particular website. The origin of that URI represents the context 967 in which a user most likely believes themselves to be interacting. 968 We'll define this origin, the top-level browsing context's active 969 document's origin, as the "top-level origin". 971 For a document displayed in a top-level browsing context, we can stop 972 here: the document's "site for cookies" is the top-level origin. 974 For documents which are displayed in nested browsing contexts, we 975 need to audit the origins of each of a document's ancestor browsing 976 contexts' active documents in order to account for the "multiple- 977 nested scenarios" described in Section 4 of [RFC7034]. A document's 978 "site for cookies" is the top-level origin if and only if the top- 979 level origin is same-site with the document's origin, and with each 980 of the document's ancestor documents' origins. Otherwise its "site 981 for cookies" is an origin set to an opaque origin. 983 Given a Document (document), the following algorithm returns its 984 "site for cookies": 986 1. Let top-document be the active document in document's browsing 987 context's top-level browsing context. 989 2. Let top-origin be the origin of top-document's URI if top- 990 document's sandboxed origin browsing context flag is set, and 991 top-document's origin otherwise. 993 3. Let documents be a list containing document and each of 994 document's ancestor browsing contexts' active documents. 996 4. For each item in documents: 998 1. Let origin be the origin of item's URI if item's sandboxed 999 origin browsing context flag is set, and item's origin 1000 otherwise. 1002 2. If origin is not same-site with top-origin, return an origin 1003 set to an opaque origin. 1005 5. Return top-origin. 1007 5.2.2. Worker-based requests 1009 Worker-driven requests aren't as clear-cut as document-driven 1010 requests, as there isn't a clear link between a top-level browsing 1011 context and a worker. This is especially true for Service Workers 1012 [SERVICE-WORKERS], which may execute code in the background, without 1013 any document visible at all. 1015 Note: The descriptions below assume that workers must be same-origin 1016 with the documents that instantiate them. If this invariant changes, 1017 we'll need to take the worker's script's URI into account when 1018 determining their status. 1020 5.2.2.1. Dedicated and Shared Workers 1022 Dedicated workers are simple, as each dedicated worker is bound to 1023 one and only one document. Requests generated from a dedicated 1024 worker (via importScripts, XMLHttpRequest, fetch(), etc) define their 1025 "site for cookies" as that document's "site for cookies". 1027 Shared workers may be bound to multiple documents at once. As it is 1028 quite possible for those documents to have distinct "site for 1029 cookies" values, the worker's "site for cookies" will be an origin 1030 set to an opaque origin in cases where the values are not all same- 1031 site with the worker's origin, and the worker's origin in cases where 1032 the values agree. 1034 Given a WorkerGlobalScope (worker), the following algorithm returns 1035 its "site for cookies": 1037 1. Let site be worker's origin. 1039 2. For each document in worker's Documents: 1041 1. Let document-site be document's "site for cookies" (as 1042 defined in Section 5.2.1). 1044 2. If document-site is not same-site with site, return an origin 1045 set to an opaque origin. 1047 3. Return site. 1049 5.2.2.2. Service Workers 1051 Service Workers are more complicated, as they act as a completely 1052 separate execution context with only tangential relationship to the 1053 Document which registered them. 1055 Requests which simply pass through a Service Worker will be handled 1056 as described above: the request's client will be the Document or 1057 Worker which initiated the request, and its "site for cookies" will 1058 be those defined in Section 5.2.1 and Section 5.2.2.1 1060 Requests which are initiated by the Service Worker itself (via a 1061 direct call to fetch(), for instance), on the other hand, will have a 1062 client which is a ServiceWorkerGlobalScope. Its "site for cookies" 1063 will be the Service Worker's URI's origin. 1065 Given a ServiceWorkerGlobalScope (worker), the following algorithm 1066 returns its "site for cookies": 1068 1. Return worker's origin. 1070 5.3. Ignoring Set-Cookie Header Fields 1072 User agents MAY ignore Set-Cookie header fields contained in 1073 responses with 100-level status codes or based on its cookie policy 1074 (see Section 7.2). 1076 All other Set-Cookie header fields SHOULD be processed according to 1077 Section 5.4. That is, Set-Cookie header fields contained in 1078 responses with non-100-level status codes (including those in 1079 responses with 400- and 500-level status codes) SHOULD be processed 1080 unless ignored according to the user agent's cookie policy. 1082 5.4. The Set-Cookie Header Field 1084 When a user agent receives a Set-Cookie header field in an HTTP 1085 response, the user agent MAY ignore the Set-Cookie header field in 1086 its entirety (see Section 5.3). 1088 If the user agent does not ignore the Set-Cookie header field in its 1089 entirety, the user agent MUST parse the field-value of the Set-Cookie 1090 header field as a set-cookie-string (defined below). 1092 NOTE: The algorithm below is more permissive than the grammar in 1093 Section 4.1. For example, the algorithm strips leading and trailing 1094 whitespace from the cookie name and value (but maintains internal 1095 whitespace), whereas the grammar in Section 4.1 forbids whitespace in 1096 these positions. In addition, the algorithm below accommodates some 1097 characters that are not cookie-octets according to the grammar in 1098 Section 4.1. User agents use this algorithm so as to interoperate 1099 with servers that do not follow the recommendations in Section 4. 1101 NOTE: As set-cookie-string may originate from a non-HTTP API, it is 1102 not guaranteed to be free of CTL characters, so this algorithm 1103 handles them explicitly. Horizontal tab (%x09) is excluded from the 1104 CTL characters that lead to set-cookie-string rejection, as it is 1105 considered whitespace, which is handled separately. 1107 NOTE: The set-cookie-string may contain octet sequences that appear 1108 percent-encoded as per Section 2.1 of [RFC3986]. However, a user 1109 agent MUST NOT decode these sequences and instead parse the 1110 individual octets as specified in this algorithm. 1112 A user agent MUST use an algorithm equivalent to the following 1113 algorithm to parse a set-cookie-string: 1115 1. If the set-cookie-string contains a %x00-08 / %x0A-1F / %x7F 1116 character (CTL characters excluding HTAB): Abort these steps and 1117 ignore the set-cookie-string entirely. 1119 2. If the set-cookie-string contains a %x3B (";") character: 1121 1. The name-value-pair string consists of the characters up to, 1122 but not including, the first %x3B (";"), and the unparsed- 1123 attributes consist of the remainder of the set-cookie-string 1124 (including the %x3B (";") in question). 1126 Otherwise: 1128 1. The name-value-pair string consists of all the characters 1129 contained in the set-cookie-string, and the unparsed- 1130 attributes is the empty string. 1132 3. If the name-value-pair string lacks a %x3D ("=") character, then 1133 the name string is empty, and the value string is the value of 1134 name-value-pair. 1136 Otherwise, the name string consists of the characters up to, but 1137 not including, the first %x3D ("=") character, and the (possibly 1138 empty) value string consists of the characters after the first 1139 %x3D ("=") character. 1141 4. Remove any leading or trailing WSP characters from the name 1142 string and the value string. 1144 5. If the sum of the lengths of the name string and the value string 1145 is more than 4096 octets, abort these steps and ignore the set- 1146 cookie-string entirely. 1148 6. The cookie-name is the name string, and the cookie-value is the 1149 value string. 1151 The user agent MUST use an algorithm equivalent to the following 1152 algorithm to parse the unparsed-attributes: 1154 1. If the unparsed-attributes string is empty, skip the rest of 1155 these steps. 1157 2. Discard the first character of the unparsed-attributes (which 1158 will be a %x3B (";") character). 1160 3. If the remaining unparsed-attributes contains a %x3B (";") 1161 character: 1163 1. Consume the characters of the unparsed-attributes up to, but 1164 not including, the first %x3B (";") character. 1166 Otherwise: 1168 1. Consume the remainder of the unparsed-attributes. 1170 Let the cookie-av string be the characters consumed in this step. 1172 4. If the cookie-av string contains a %x3D ("=") character: 1174 1. The (possibly empty) attribute-name string consists of the 1175 characters up to, but not including, the first %x3D ("=") 1176 character, and the (possibly empty) attribute-value string 1177 consists of the characters after the first %x3D ("=") 1178 character. 1180 Otherwise: 1182 1. The attribute-name string consists of the entire cookie-av 1183 string, and the attribute-value string is empty. 1185 5. Remove any leading or trailing WSP characters from the attribute- 1186 name string and the attribute-value string. 1188 6. If the attribute-value is longer than 1024 octets, ignore the 1189 cookie-av string and return to Step 1 of this algorithm. 1191 7. Process the attribute-name and attribute-value according to the 1192 requirements in the following subsections. (Notice that 1193 attributes with unrecognized attribute-names are ignored.) 1195 8. Return to Step 1 of this algorithm. 1197 When the user agent finishes parsing the set-cookie-string, the user 1198 agent is said to "receive a cookie" from the request-uri with name 1199 cookie-name, value cookie-value, and attributes cookie-attribute- 1200 list. (See Section 5.5 for additional requirements triggered by 1201 receiving a cookie.) 1203 5.4.1. The Expires Attribute 1205 If the attribute-name case-insensitively matches the string 1206 "Expires", the user agent MUST process the cookie-av as follows. 1208 1. Let the expiry-time be the result of parsing the attribute-value 1209 as cookie-date (see Section 5.1.1). 1211 2. If the attribute-value failed to parse as a cookie date, ignore 1212 the cookie-av. 1214 3. Let cookie-age-limit be the maximum age of the cookie (which 1215 SHOULD be 400 days in the future or sooner, see Section 4.1.2.1). 1217 4. If the expiry-time is more than cookie-age-limit, the user agent 1218 MUST set the expiry time to cookie-age-limit in seconds. 1220 5. If the expiry-time is earlier than the earliest date the user 1221 agent can represent, the user agent MAY replace the expiry-time 1222 with the earliest representable date. 1224 6. Append an attribute to the cookie-attribute-list with an 1225 attribute-name of Expires and an attribute-value of expiry-time. 1227 5.4.2. The Max-Age Attribute 1229 If the attribute-name case-insensitively matches the string "Max- 1230 Age", the user agent MUST process the cookie-av as follows. 1232 1. If the first character of the attribute-value is not a DIGIT or a 1233 "-" character, ignore the cookie-av. 1235 2. If the remainder of attribute-value contains a non-DIGIT 1236 character, ignore the cookie-av. 1238 3. Let delta-seconds be the attribute-value converted to an integer. 1240 4. Let cookie-age-limit be the maximum age of the cookie (which 1241 SHOULD be 400 days or less, see Section 4.1.2.2). 1243 5. Set delta-seconds to the smaller of its present value and cookie- 1244 age-limit. 1246 6. If delta-seconds is less than or equal to zero (0), let expiry- 1247 time be the earliest representable date and time. Otherwise, let 1248 the expiry-time be the current date and time plus delta-seconds 1249 seconds. 1251 7. Append an attribute to the cookie-attribute-list with an 1252 attribute-name of Max-Age and an attribute-value of expiry-time. 1254 5.4.3. The Domain Attribute 1256 If the attribute-name case-insensitively matches the string "Domain", 1257 the user agent MUST process the cookie-av as follows. 1259 1. Let cookie-domain be the attribute-value. 1261 2. If cookie-domain starts with %x2E ("."), let cookie-domain be 1262 cookie-domain without its leading %x2E ("."). 1264 3. Convert the cookie-domain to lower case. 1266 4. Append an attribute to the cookie-attribute-list with an 1267 attribute-name of Domain and an attribute-value of cookie-domain. 1269 5.4.4. The Path Attribute 1271 If the attribute-name case-insensitively matches the string "Path", 1272 the user agent MUST process the cookie-av as follows. 1274 1. If the attribute-value is empty or if the first character of the 1275 attribute-value is not %x2F ("/"): 1277 1. Let cookie-path be the default-path. 1279 Otherwise: 1281 1. Let cookie-path be the attribute-value. 1283 2. Append an attribute to the cookie-attribute-list with an 1284 attribute-name of Path and an attribute-value of cookie-path. 1286 5.4.5. The Secure Attribute 1288 If the attribute-name case-insensitively matches the string "Secure", 1289 the user agent MUST append an attribute to the cookie-attribute-list 1290 with an attribute-name of Secure and an empty attribute-value. 1292 5.4.6. The HttpOnly Attribute 1294 If the attribute-name case-insensitively matches the string 1295 "HttpOnly", the user agent MUST append an attribute to the cookie- 1296 attribute-list with an attribute-name of HttpOnly and an empty 1297 attribute-value. 1299 5.4.7. The SameSite Attribute 1301 If the attribute-name case-insensitively matches the string 1302 "SameSite", the user agent MUST process the cookie-av as follows: 1304 1. Let enforcement be "Default". 1306 2. If cookie-av's attribute-value is a case-insensitive match for 1307 "None", set enforcement to "None". 1309 3. If cookie-av's attribute-value is a case-insensitive match for 1310 "Strict", set enforcement to "Strict". 1312 4. If cookie-av's attribute-value is a case-insensitive match for 1313 "Lax", set enforcement to "Lax". 1315 5. Append an attribute to the cookie-attribute-list with an 1316 attribute-name of "SameSite" and an attribute-value of 1317 enforcement. 1319 5.4.7.1. "Strict" and "Lax" enforcement 1321 Same-site cookies in "Strict" enforcement mode will not be sent along 1322 with top-level navigations which are triggered from a cross-site 1323 document context. As discussed in Section 8.8.2, this might or might 1324 not be compatible with existing session management systems. In the 1325 interests of providing a drop-in mechanism that mitigates the risk of 1326 CSRF attacks, developers may set the SameSite attribute in a "Lax" 1327 enforcement mode that carves out an exception which sends same-site 1328 cookies along with cross-site requests if and only if they are top- 1329 level navigations which use a "safe" (in the [HTTPSEM] sense) HTTP 1330 method. (Note that a request's method may be changed from POST to 1331 GET for some redirects (see Sections 15.4.2 and 15.4.3 of [HTTPSEM]); 1332 in these cases, a request's "safe"ness is determined based on the 1333 method of the current redirect hop.) 1335 Lax enforcement provides reasonable defense in depth against CSRF 1336 attacks that rely on unsafe HTTP methods (like POST), but does not 1337 offer a robust defense against CSRF as a general category of attack: 1339 1. Attackers can still pop up new windows or trigger top-level 1340 navigations in order to create a "same-site" request (as 1341 described in Section 5.2.1), which is only a speedbump along the 1342 road to exploitation. 1344 2. Features like [prerendering] can be 1345 exploited to create "same-site" requests without the risk of user 1346 detection. 1348 When possible, developers should use a session management mechanism 1349 such as that described in Section 8.8.2 to mitigate the risk of CSRF 1350 more completely. 1352 5.4.7.2. "Lax-Allowing-Unsafe" enforcement 1354 As discussed in Section 8.8.6, compatibility concerns may necessitate 1355 the use of a "Lax-allowing-unsafe" enforcement mode that allows 1356 cookies to be sent with a cross-site HTTP request if and only if it 1357 is a top-level request, regardless of request method. That is, the 1358 "Lax-allowing-unsafe" enforcement mode waives the requirement for the 1359 HTTP request's method to be "safe" in the SameSite enforcement step 1360 of the retrieval algorithm in Section 5.6.3. (All cookies, 1361 regardless of SameSite enforcement mode, may be set for top-level 1362 navigations, regardless of HTTP request method, as specified in 1363 Section 5.5.) 1365 "Lax-allowing-unsafe" is not a distinct value of the SameSite 1366 attribute. Rather, user agents MAY apply "Lax-allowing-unsafe" 1367 enforcement only to cookies that did not explicitly specify a 1368 SameSite attribute (i.e., those whose same-site-flag was set to 1369 "Default" by default). To limit the scope of this compatibility 1370 mode, user agents which apply "Lax-allowing-unsafe" enforcement 1371 SHOULD restrict the enforcement to cookies which were created 1372 recently. Deployment experience has shown a cookie age of 2 minutes 1373 or less to be a reasonable limit. 1375 If the user agent uses "Lax-allowing-unsafe" enforcement, it MUST 1376 apply the following modification to the retrieval algorithm defined 1377 in Section 5.6.3: 1379 Replace the condition in the penultimate bullet point of step 1 of 1380 the retrieval algorithm reading 1382 * The HTTP request associated with the retrieval uses a "safe" 1383 method. 1385 with 1387 * At least one of the following is true: 1389 1. The HTTP request associated with the retrieval uses a "safe" 1390 method. 1392 2. The cookie's same-site-flag is "Default" and the amount of 1393 time elapsed since the cookie's creation-time is at most a 1394 duration of the user agent's choosing. 1396 5.5. Storage Model 1398 The user agent stores the following fields about each cookie: name, 1399 value, expiry-time, domain, path, creation-time, last-access-time, 1400 persistent-flag, host-only-flag, secure-only-flag, http-only-flag, 1401 and same-site-flag. 1403 When the user agent "receives a cookie" from a request-uri with name 1404 cookie-name, value cookie-value, and attributes cookie-attribute- 1405 list, the user agent MUST process the cookie as follows: 1407 1. A user agent MAY ignore a received cookie in its entirety. See 1408 Section 5.3. 1410 2. If cookie-name is empty and cookie-value is empty, abort these 1411 steps and ignore the cookie entirely. 1413 3. If the cookie-name or the cookie-value contains a %x00-08 / 1414 %x0A-1F / %x7F character (CTL characters excluding HTAB), abort 1415 these steps and ignore the cookie entirely. 1417 4. If the sum of the lengths of cookie-name and cookie-value is 1418 more than 4096 octets, abort these steps and ignore the cookie 1419 entirely. 1421 5. Create a new cookie with name cookie-name, value cookie-value. 1422 Set the creation-time and the last-access-time to the current 1423 date and time. 1425 6. If the cookie-attribute-list contains an attribute with an 1426 attribute-name of "Max-Age": 1428 1. Set the cookie's persistent-flag to true. 1430 2. Set the cookie's expiry-time to attribute-value of the last 1431 attribute in the cookie-attribute-list with an attribute- 1432 name of "Max-Age". 1434 Otherwise, if the cookie-attribute-list contains an attribute 1435 with an attribute-name of "Expires" (and does not contain an 1436 attribute with an attribute-name of "Max-Age"): 1438 1. Set the cookie's persistent-flag to true. 1440 2. Set the cookie's expiry-time to attribute-value of the last 1441 attribute in the cookie-attribute-list with an attribute- 1442 name of "Expires". 1444 Otherwise: 1446 1. Set the cookie's persistent-flag to false. 1448 2. Set the cookie's expiry-time to the latest representable 1449 date. 1451 7. If the cookie-attribute-list contains an attribute with an 1452 attribute-name of "Domain": 1454 1. Let the domain-attribute be the attribute-value of the last 1455 attribute in the cookie-attribute-list with both an 1456 attribute-name of "Domain" and an attribute-value whose 1457 length is no more than 1024 octets. (Note that a leading 1458 %x2E ("."), if present, is ignored even though that 1459 character is not permitted, but a trailing %x2E ("."), if 1460 present, will cause the user agent to ignore the attribute.) 1462 Otherwise: 1464 1. Let the domain-attribute be the empty string. 1466 8. If the domain-attribute contains a character that is not in the 1467 range of [USASCII] characters, abort these steps and ignore the 1468 cookie entirely. 1470 9. If the user agent is configured to reject "public suffixes" and 1471 the domain-attribute is a public suffix: 1473 1. If the domain-attribute is identical to the canonicalized 1474 request-host: 1476 1. Let the domain-attribute be the empty string. 1478 Otherwise: 1480 1. Abort these steps and ignore the cookie entirely. 1482 NOTE: This step prevents attacker.example from disrupting the 1483 integrity of site.example by setting a cookie with a Domain 1484 attribute of "example". 1486 10. If the domain-attribute is non-empty: 1488 1. If the canonicalized request-host does not domain-match the 1489 domain-attribute: 1491 1. Abort these steps and ignore the cookie entirely. 1493 Otherwise: 1495 1. Set the cookie's host-only-flag to false. 1497 2. Set the cookie's domain to the domain-attribute. 1499 Otherwise: 1501 1. Set the cookie's host-only-flag to true. 1503 2. Set the cookie's domain to the canonicalized request-host. 1505 11. If the cookie-attribute-list contains an attribute with an 1506 attribute-name of "Path", set the cookie's path to attribute- 1507 value of the last attribute in the cookie-attribute-list with 1508 both an attribute-name of "Path" and an attribute-value whose 1509 length is no more than 1024 octets. Otherwise, set the cookie's 1510 path to the default-path of the request-uri. 1512 12. If the cookie-attribute-list contains an attribute with an 1513 attribute-name of "Secure", set the cookie's secure-only-flag to 1514 true. Otherwise, set the cookie's secure-only-flag to false. 1516 13. If the scheme component of the request-uri does not denote a 1517 "secure" protocol (as defined by the user agent), and the 1518 cookie's secure-only-flag is true, then abort these steps and 1519 ignore the cookie entirely. 1521 14. If the cookie-attribute-list contains an attribute with an 1522 attribute-name of "HttpOnly", set the cookie's http-only-flag to 1523 true. Otherwise, set the cookie's http-only-flag to false. 1525 15. If the cookie was received from a "non-HTTP" API and the 1526 cookie's http-only-flag is true, abort these steps and ignore 1527 the cookie entirely. 1529 16. If the cookie's secure-only-flag is false, and the scheme 1530 component of request-uri does not denote a "secure" protocol, 1531 then abort these steps and ignore the cookie entirely if the 1532 cookie store contains one or more cookies that meet all of the 1533 following criteria: 1535 1. Their name matches the name of the newly-created cookie. 1537 2. Their secure-only-flag is true. 1539 3. Their domain domain-matches the domain of the newly-created 1540 cookie, or vice-versa. 1542 4. The path of the newly-created cookie path-matches the path 1543 of the existing cookie. 1545 Note: The path comparison is not symmetric, ensuring only that a 1546 newly-created, non-secure cookie does not overlay an existing 1547 secure cookie, providing some mitigation against cookie-fixing 1548 attacks. That is, given an existing secure cookie named 'a' 1549 with a path of '/login', a non-secure cookie named 'a' could be 1550 set for a path of '/' or '/foo', but not for a path of '/login' 1551 or '/login/en'. 1553 17. If the cookie-attribute-list contains an attribute with an 1554 attribute-name of "SameSite", and an attribute-value of 1555 "Strict", "Lax", or "None", set the cookie's same-site-flag to 1556 the attribute-value of the last attribute in the cookie- 1557 attribute-list with an attribute-name of "SameSite". Otherwise, 1558 set the cookie's same-site-flag to "Default". 1560 18. If the cookie's same-site-flag is not "None": 1562 1. If the cookie was received from a "non-HTTP" API, and the 1563 API was called from a browsing context's active document 1564 whose "site for cookies" is not same-site with the top-level 1565 origin, then abort these steps and ignore the newly created 1566 cookie entirely. 1568 2. If the cookie was received from a "same-site" request (as 1569 defined in Section 5.2), skip the remaining substeps and 1570 continue processing the cookie. 1572 3. If the cookie was received from a request which is 1573 navigating a top-level browsing context [HTML] (e.g. if the 1574 request's "reserved client" is either null or an environment 1575 whose "target browsing context" is a top-level browing 1576 context), skip the remaining substeps and continue 1577 processing the cookie. 1579 Note: Top-level navigations can create a cookie with any 1580 SameSite value, even if the new cookie wouldn't have been 1581 sent along with the request had it already existed prior to 1582 the navigation. 1584 4. Abort these steps and ignore the newly created cookie 1585 entirely. 1587 19. If the cookie's "same-site-flag" is "None", abort these steps 1588 and ignore the cookie entirely unless the cookie's secure-only- 1589 flag is true. 1591 20. If the cookie-name begins with a case-sensitive match for the 1592 string "__Secure-", abort these steps and ignore the cookie 1593 entirely unless the cookie's secure-only-flag is true. 1595 21. If the cookie-name begins with a case-sensitive match for the 1596 string "__Host-", abort these steps and ignore the cookie 1597 entirely unless the cookie meets all the following criteria: 1599 1. The cookie's secure-only-flag is true. 1601 2. The cookie's host-only-flag is true. 1603 3. The cookie-attribute-list contains an attribute with an 1604 attribute-name of "Path", and the cookie's path is /. 1606 22. If the cookie store contains a cookie with the same name, 1607 domain, host-only-flag, and path as the newly-created cookie: 1609 1. Let old-cookie be the existing cookie with the same name, 1610 domain, host-only-flag, and path as the newly-created 1611 cookie. (Notice that this algorithm maintains the invariant 1612 that there is at most one such cookie.) 1614 2. If the newly-created cookie was received from a "non-HTTP" 1615 API and the old-cookie's http-only-flag is true, abort these 1616 steps and ignore the newly created cookie entirely. 1618 3. Update the creation-time of the newly-created cookie to 1619 match the creation-time of the old-cookie. 1621 4. Remove the old-cookie from the cookie store. 1623 23. Insert the newly-created cookie into the cookie store. 1625 A cookie is "expired" if the cookie has an expiry date in the past. 1627 The user agent MUST evict all expired cookies from the cookie store 1628 if, at any time, an expired cookie exists in the cookie store. 1630 At any time, the user agent MAY "remove excess cookies" from the 1631 cookie store if the number of cookies sharing a domain field exceeds 1632 some implementation-defined upper bound (such as 50 cookies). 1634 At any time, the user agent MAY "remove excess cookies" from the 1635 cookie store if the cookie store exceeds some predetermined upper 1636 bound (such as 3000 cookies). 1638 When the user agent removes excess cookies from the cookie store, the 1639 user agent MUST evict cookies in the following priority order: 1641 1. Expired cookies. 1643 2. Cookies whose secure-only-flag is false, and which share a domain 1644 field with more than a predetermined number of other cookies. 1646 3. Cookies that share a domain field with more than a predetermined 1647 number of other cookies. 1649 4. All cookies. 1651 If two cookies have the same removal priority, the user agent MUST 1652 evict the cookie with the earliest last-access-time first. 1654 When "the current session is over" (as defined by the user agent), 1655 the user agent MUST remove from the cookie store all cookies with the 1656 persistent-flag set to false. 1658 5.6. Retrieval Model 1660 This section defines how cookies are retrieved from a cookie store in 1661 the form of a cookie-string. A "retrieval" is any event which 1662 requires generating a cookie-string. For example, a retrieval may 1663 occur in order to build a Cookie header field for an HTTP request, or 1664 may be required in order to return a cookie-string from a call to a 1665 "non-HTTP" API that provides access to cookies. A retrieval has an 1666 associated URI, same-site status, and type, which are defined below 1667 depending on the type of retrieval. 1669 5.6.1. The Cookie Header Field 1671 The user agent includes stored cookies in the Cookie HTTP request 1672 header field. 1674 When the user agent generates an HTTP request, the user agent MUST 1675 NOT attach more than one Cookie header field. 1677 A user agent MAY omit the Cookie header field in its entirety. For 1678 example, the user agent might wish to block sending cookies during 1679 "third-party" requests from setting cookies (see Section 7.1). 1681 If the user agent does attach a Cookie header field to an HTTP 1682 request, the user agent MUST compute the cookie-string following the 1683 algorithm defined in Section 5.6.3, where the retrieval's URI is the 1684 request-uri, the retrieval's same-site status is computed for the 1685 HTTP request as defined in Section 5.2, and the retrieval's type is 1686 "HTTP". 1688 5.6.2. Non-HTTP APIs 1690 The user agent MAY implement "non-HTTP" APIs that can be used to 1691 access stored cookies. 1693 A user agent MAY return an empty cookie-string in certain contexts, 1694 such as when a retrieval occurs within a third-party context (see 1695 Section 7.1). 1697 If a user agent does return cookies for a given call to a "non-HTTP" 1698 API with an associated Document, then the user agent MUST compute the 1699 cookie-string following the algorithm defined in Section 5.6.3, where 1700 the retrieval's URI is defined by the caller (see 1701 [DOM-DOCUMENT-COOKIE]), the retrieval's same-site status is "same- 1702 site" if the Document's "site for cookies" is same-site with the top- 1703 level origin as defined in Section 5.2.1 (otherwise it is "cross- 1704 site"), and the retrieval's type is "non-HTTP". 1706 5.6.3. Retrieval Algorithm 1708 Given a cookie store and a retrieval, the following algorithm returns 1709 a cookie-string from a given cookie store. 1711 1. Let cookie-list be the set of cookies from the cookie store that 1712 meets all of the following requirements: 1714 * Either: 1716 - The cookie's host-only-flag is true and the canonicalized 1717 host of the retrieval's URI is identical to the cookie's 1718 domain. 1720 Or: 1722 - The cookie's host-only-flag is false and the canonicalized 1723 host of the retrieval's URI domain-matches the cookie's 1724 domain. 1726 * The retrieval's URI's path path-matches the cookie's path. 1728 * If the cookie's secure-only-flag is true, then the retrieval's 1729 URI's scheme must denote a "secure" protocol (as defined by 1730 the user agent). 1732 NOTE: The notion of a "secure" protocol is not defined by this 1733 document. Typically, user agents consider a protocol secure 1734 if the protocol makes use of transport-layer security, such as 1735 SSL or TLS. For example, most user agents consider "https" to 1736 be a scheme that denotes a secure protocol. 1738 * If the cookie's http-only-flag is true, then exclude the 1739 cookie if the retrieval's type is "non-HTTP". 1741 * If the cookie's same-site-flag is not "None" and the 1742 retrieval's same-site status is "cross-site", then exclude the 1743 cookie unless all of the following conditions are met: 1745 - The retrieval's type is "HTTP". 1747 - The same-site-flag is "Lax" or "Default". 1749 - The HTTP request associated with the retrieval uses a 1750 "safe" method. 1752 - The target browsing context of the HTTP request associated 1753 with the retrieval is a top-level browsing context. 1755 2. The user agent SHOULD sort the cookie-list in the following 1756 order: 1758 * Cookies with longer paths are listed before cookies with 1759 shorter paths. 1761 * Among cookies that have equal-length path fields, cookies with 1762 earlier creation-times are listed before cookies with later 1763 creation-times. 1765 NOTE: Not all user agents sort the cookie-list in this order, but 1766 this order reflects common practice when this document was 1767 written, and, historically, there have been servers that 1768 (erroneously) depended on this order. 1770 3. Update the last-access-time of each cookie in the cookie-list to 1771 the current date and time. 1773 4. Serialize the cookie-list into a cookie-string by processing each 1774 cookie in the cookie-list in order: 1776 1. If the cookies' name is not empty, output the cookie's name 1777 followed by the %x3D ("=") character. 1779 2. If the cookies' value is not empty, output the cookie's 1780 value. 1782 3. If there is an unprocessed cookie in the cookie-list, output 1783 the characters %x3B and %x20 ("; "). 1785 NOTE: Despite its name, the cookie-string is actually a sequence of 1786 octets, not a sequence of characters. To convert the cookie-string 1787 (or components thereof) into a sequence of characters (e.g., for 1788 presentation to the user), the user agent might wish to try using the 1789 UTF-8 character encoding [RFC3629] to decode the octet sequence. 1790 This decoding might fail, however, because not every sequence of 1791 octets is valid UTF-8. 1793 6. Implementation Considerations 1795 6.1. Limits 1797 Practical user agent implementations have limits on the number and 1798 size of cookies that they can store. General-use user agents SHOULD 1799 provide each of the following minimum capabilities: 1801 * At least 50 cookies per domain. 1803 * At least 3000 cookies total. 1805 User agents MAY limit the maximum number of cookies they store, and 1806 may evict any cookie at any time (whether at the request of the user 1807 or due to implementation limitations). 1809 Note that a limit on the maximum number of cookies also limits the 1810 total size of the stored cookies, due to the length limits which MUST 1811 be enforced in Section 5.4. 1813 Servers SHOULD use as few and as small cookies as possible to avoid 1814 reaching these implementation limits and to minimize network 1815 bandwidth due to the Cookie header field being included in every 1816 request. 1818 Servers SHOULD gracefully degrade if the user agent fails to return 1819 one or more cookies in the Cookie header field because the user agent 1820 might evict any cookie at any time. 1822 6.2. Application Programming Interfaces 1824 One reason the Cookie and Set-Cookie header fields use such esoteric 1825 syntax is that many platforms (both in servers and user agents) 1826 provide a string-based application programming interface (API) to 1827 cookies, requiring application-layer programmers to generate and 1828 parse the syntax used by the Cookie and Set-Cookie header fields, 1829 which many programmers have done incorrectly, resulting in 1830 interoperability problems. 1832 Instead of providing string-based APIs to cookies, platforms would be 1833 well-served by providing more semantic APIs. It is beyond the scope 1834 of this document to recommend specific API designs, but there are 1835 clear benefits to accepting an abstract "Date" object instead of a 1836 serialized date string. 1838 6.3. IDNA Dependency and Migration 1840 IDNA2008 [RFC5890] supersedes IDNA2003 [RFC3490]. However, there are 1841 differences between the two specifications, and thus there can be 1842 differences in processing (e.g., converting) domain name labels that 1843 have been registered under one from those registered under the other. 1844 There will be a transition period of some time during which 1845 IDNA2003-based domain name labels will exist in the wild. User 1846 agents SHOULD implement IDNA2008 [RFC5890] and MAY implement [UTS46] 1847 or [RFC5895] in order to facilitate their IDNA transition. If a user 1848 agent does not implement IDNA2008, the user agent MUST implement 1849 IDNA2003 [RFC3490]. 1851 7. Privacy Considerations 1853 Cookies' primary privacy risk is their ability to correlate user 1854 activity. This can happen on a single site, but is most problematic 1855 when activity is tracked across different, seemingly unconnected Web 1856 sites to build a user profile. 1858 Over time, this capability (warned against explicitly in [RFC2109] 1859 and all of its successors) has become widely used for varied reasons 1860 including: 1862 * authenticating users across sites, 1864 * assembling information on users, 1866 * protecting against fraud and other forms of undesirable traffic, 1868 * targeting advertisements at specific users or at users with 1869 specified attributes, 1871 * measuring how often ads are shown to users, and 1873 * recognizing when an ad resulted in a change in user behavior. 1875 While not every use of cookies is necessarily problematic for 1876 privacy, their potential for abuse has become a widespread concern in 1877 the Internet community and broader society. In response to these 1878 concerns, user agents have actively constrained cookie functionality 1879 in various ways (as allowed and encouraged by previous 1880 specifications), while avoiding disruption to features they judge 1881 desirable for the health of the Web. 1883 It is too early to declare consensus on which specific mechanism(s) 1884 should be used to mitigate cookies' privacy impact; user agents' 1885 ongoing changes to how they are handled are best characterised as 1886 experiments that can provide input into that eventual consensus. 1888 Instead, this document describes limited, general mitigations against 1889 the privacy risks associated with cookies that enjoy wide deployment 1890 at the time of writing. It is expected that implementations will 1891 continue to experiment and impose stricter, more well-defined 1892 limitations on cookies over time. Future versions of this document 1893 might codify those mechanisms based upon deployment experience. If 1894 functions that currently rely on cookies can be supported by 1895 separate, targeted mechanisms, they might be documented in separate 1896 specifications and stricter limitations on cookies might become 1897 feasible. 1899 Note that cookies are not the only mechanism that can be used to 1900 track users across sites, so while these mitigations are necessary to 1901 improve Web privacy, they are not sufficient on their own. 1903 7.1. Third-Party Cookies 1905 A "third-party" or cross-site cookie is one that is associated with 1906 embedded content (such as scripts, images, stylesheets, frames) that 1907 is obtained from a different server than the one that hosts the 1908 primary resource (usually, the Web page that the user is viewing). 1909 Third-party cookies are often used to correlate users' activity on 1910 different sites. 1912 Because of their inherent privacy issues, most user agents now limit 1913 third-party cookies in a variety of ways. Some completely block 1914 third-party cookies by refusing to process third-party Set-Cookie 1915 header fields and refusing to send third-party Cookie header fields. 1916 Some partition cookies based upon the first-party context, so that 1917 different cookies are sent depending on the site being browsed. Some 1918 block cookies based upon user agent cookie policy and/or user 1919 controls. 1921 While this document does not endorse or require a specific approach, 1922 it is RECOMMENDED that user agents adopt a policy for third-party 1923 cookies that is as restrictive as compatibility constraints permit. 1924 Consequently, resources cannot rely upon third-party cookies being 1925 treated consistently by user agents for the foreseeable future. 1927 7.2. Cookie Policy 1929 User agents MAY enforce a cookie policy consisting of restrictions on 1930 how cookies may be used or ignored (see Section 5.3). 1932 A cookie policy may govern which domains or parties, as in first and 1933 third parties (see Section 7.1), for which the user agent will allow 1934 cookie access. The policy can also define limits on cookie size, 1935 cookie expiry (see Section 4.1.2.1 and Section 4.1.2.2), and the 1936 number of cookies per domain or in total. 1938 The recomended cookie expiry upper limit is 400 days. User agents 1939 may set a lower limit to enforce shorter data retention timelines, or 1940 set the limit higher to support longer retention when appropriate 1941 (e.g., server-to-server communication over HTTPS). 1943 The goal of a restrictive cookie policy is often to improve security 1944 or privacy. User agents often allow users to change the cookie 1945 policy (see Section 7.3). 1947 7.3. User Controls 1949 User agents SHOULD provide users with a mechanism for managing the 1950 cookies stored in the cookie store. For example, a user agent might 1951 let users delete all cookies received during a specified time period 1952 or all the cookies related to a particular domain. In addition, many 1953 user agents include a user interface element that lets users examine 1954 the cookies stored in their cookie store. 1956 User agents SHOULD provide users with a mechanism for disabling 1957 cookies. When cookies are disabled, the user agent MUST NOT include 1958 a Cookie header field in outbound HTTP requests and the user agent 1959 MUST NOT process Set-Cookie header fields in inbound HTTP responses. 1961 User agents MAY offer a way to change the cookie policy (see 1962 Section 7.2). 1964 User agents MAY provide users the option of preventing persistent 1965 storage of cookies across sessions. When configured thusly, user 1966 agents MUST treat all received cookies as if the persistent-flag were 1967 set to false. Some popular user agents expose this functionality via 1968 "private browsing" mode [Aggarwal2010]. 1970 7.4. Expiration Dates 1972 Although servers can set the expiration date for cookies to the 1973 distant future, most user agents do not actually retain cookies for 1974 multiple decades. Rather than choosing gratuitously long expiration 1975 periods, servers SHOULD promote user privacy by selecting reasonable 1976 cookie expiration periods based on the purpose of the cookie. For 1977 example, a typical session identifier might reasonably be set to 1978 expire in two weeks. 1980 8. Security Considerations 1982 8.1. Overview 1984 Cookies have a number of security pitfalls. This section overviews a 1985 few of the more salient issues. 1987 In particular, cookies encourage developers to rely on ambient 1988 authority for authentication, often becoming vulnerable to attacks 1989 such as cross-site request forgery [CSRF]. Also, when storing 1990 session identifiers in cookies, developers often create session 1991 fixation vulnerabilities. 1993 Transport-layer encryption, such as that employed in HTTPS, is 1994 insufficient to prevent a network attacker from obtaining or altering 1995 a victim's cookies because the cookie protocol itself has various 1996 vulnerabilities (see "Weak Confidentiality" and "Weak Integrity", 1997 below). In addition, by default, cookies do not provide 1998 confidentiality or integrity from network attackers, even when used 1999 in conjunction with HTTPS. 2001 8.2. Ambient Authority 2003 A server that uses cookies to authenticate users can suffer security 2004 vulnerabilities because some user agents let remote parties issue 2005 HTTP requests from the user agent (e.g., via HTTP redirects or HTML 2006 forms). When issuing those requests, user agents attach cookies even 2007 if the remote party does not know the contents of the cookies, 2008 potentially letting the remote party exercise authority at an unwary 2009 server. 2011 Although this security concern goes by a number of names (e.g., 2012 cross-site request forgery, confused deputy), the issue stems from 2013 cookies being a form of ambient authority. Cookies encourage server 2014 operators to separate designation (in the form of URLs) from 2015 authorization (in the form of cookies). Consequently, the user agent 2016 might supply the authorization for a resource designated by the 2017 attacker, possibly causing the server or its clients to undertake 2018 actions designated by the attacker as though they were authorized by 2019 the user. 2021 Instead of using cookies for authorization, server operators might 2022 wish to consider entangling designation and authorization by treating 2023 URLs as capabilities. Instead of storing secrets in cookies, this 2024 approach stores secrets in URLs, requiring the remote entity to 2025 supply the secret itself. Although this approach is not a panacea, 2026 judicious application of these principles can lead to more robust 2027 security. 2029 8.3. Clear Text 2031 Unless sent over a secure channel (such as TLS), the information in 2032 the Cookie and Set-Cookie header fields is transmitted in the clear. 2034 1. All sensitive information conveyed in these header fields is 2035 exposed to an eavesdropper. 2037 2. A malicious intermediary could alter the header fields as they 2038 travel in either direction, with unpredictable results. 2040 3. A malicious client could alter the Cookie header fields before 2041 transmission, with unpredictable results. 2043 Servers SHOULD encrypt and sign the contents of cookies (using 2044 whatever format the server desires) when transmitting them to the 2045 user agent (even when sending the cookies over a secure channel). 2046 However, encrypting and signing cookie contents does not prevent an 2047 attacker from transplanting a cookie from one user agent to another 2048 or from replaying the cookie at a later time. 2050 In addition to encrypting and signing the contents of every cookie, 2051 servers that require a higher level of security SHOULD use the Cookie 2052 and Set-Cookie header fields only over a secure channel. When using 2053 cookies over a secure channel, servers SHOULD set the Secure 2054 attribute (see Section 4.1.2.5) for every cookie. If a server does 2055 not set the Secure attribute, the protection provided by the secure 2056 channel will be largely moot. 2058 For example, consider a webmail server that stores a session 2059 identifier in a cookie and is typically accessed over HTTPS. If the 2060 server does not set the Secure attribute on its cookies, an active 2061 network attacker can intercept any outbound HTTP request from the 2062 user agent and redirect that request to the webmail server over HTTP. 2063 Even if the webmail server is not listening for HTTP connections, the 2064 user agent will still include cookies in the request. The active 2065 network attacker can intercept these cookies, replay them against the 2066 server, and learn the contents of the user's email. If, instead, the 2067 server had set the Secure attribute on its cookies, the user agent 2068 would not have included the cookies in the clear-text request. 2070 8.4. Session Identifiers 2072 Instead of storing session information directly in a cookie (where it 2073 might be exposed to or replayed by an attacker), servers commonly 2074 store a nonce (or "session identifier") in a cookie. When the server 2075 receives an HTTP request with a nonce, the server can look up state 2076 information associated with the cookie using the nonce as a key. 2078 Using session identifier cookies limits the damage an attacker can 2079 cause if the attacker learns the contents of a cookie because the 2080 nonce is useful only for interacting with the server (unlike non- 2081 nonce cookie content, which might itself be sensitive). Furthermore, 2082 using a single nonce prevents an attacker from "splicing" together 2083 cookie content from two interactions with the server, which could 2084 cause the server to behave unexpectedly. 2086 Using session identifiers is not without risk. For example, the 2087 server SHOULD take care to avoid "session fixation" vulnerabilities. 2088 A session fixation attack proceeds in three steps. First, the 2089 attacker transplants a session identifier from his or her user agent 2090 to the victim's user agent. Second, the victim uses that session 2091 identifier to interact with the server, possibly imbuing the session 2092 identifier with the user's credentials or confidential information. 2093 Third, the attacker uses the session identifier to interact with 2094 server directly, possibly obtaining the user's authority or 2095 confidential information. 2097 8.5. Weak Confidentiality 2099 Cookies do not provide isolation by port. If a cookie is readable by 2100 a service running on one port, the cookie is also readable by a 2101 service running on another port of the same server. If a cookie is 2102 writable by a service on one port, the cookie is also writable by a 2103 service running on another port of the same server. For this reason, 2104 servers SHOULD NOT both run mutually distrusting services on 2105 different ports of the same host and use cookies to store security- 2106 sensitive information. 2108 Cookies do not provide isolation by scheme. Although most commonly 2109 used with the http and https schemes, the cookies for a given host 2110 might also be available to other schemes, such as ftp and gopher. 2111 Although this lack of isolation by scheme is most apparent in non- 2112 HTTP APIs that permit access to cookies (e.g., HTML's document.cookie 2113 API), the lack of isolation by scheme is actually present in 2114 requirements for processing cookies themselves (e.g., consider 2115 retrieving a URI with the gopher scheme via HTTP). 2117 Cookies do not always provide isolation by path. Although the 2118 network-level protocol does not send cookies stored for one path to 2119 another, some user agents expose cookies via non-HTTP APIs, such as 2120 HTML's document.cookie API. Because some of these user agents (e.g., 2121 web browsers) do not isolate resources received from different paths, 2122 a resource retrieved from one path might be able to access cookies 2123 stored for another path. 2125 8.6. Weak Integrity 2127 Cookies do not provide integrity guarantees for sibling domains (and 2128 their subdomains). For example, consider foo.site.example and 2129 bar.site.example. The foo.site.example server can set a cookie with 2130 a Domain attribute of "site.example" (possibly overwriting an 2131 existing "site.example" cookie set by bar.site.example), and the user 2132 agent will include that cookie in HTTP requests to bar.site.example. 2133 In the worst case, bar.site.example will be unable to distinguish 2134 this cookie from a cookie it set itself. The foo.site.example server 2135 might be able to leverage this ability to mount an attack against 2136 bar.site.example. 2138 Even though the Set-Cookie header field supports the Path attribute, 2139 the Path attribute does not provide any integrity protection because 2140 the user agent will accept an arbitrary Path attribute in a Set- 2141 Cookie header field. For example, an HTTP response to a request for 2142 http://site.example/foo/bar can set a cookie with a Path attribute of 2143 "/qux". Consequently, servers SHOULD NOT both run mutually 2144 distrusting services on different paths of the same host and use 2145 cookies to store security-sensitive information. 2147 An active network attacker can also inject cookies into the Cookie 2148 header field sent to https://site.example/ by impersonating a 2149 response from http://site.example/ and injecting a Set-Cookie header 2150 field. The HTTPS server at site.example will be unable to 2151 distinguish these cookies from cookies that it set itself in an HTTPS 2152 response. An active network attacker might be able to leverage this 2153 ability to mount an attack against site.example even if site.example 2154 uses HTTPS exclusively. 2156 Servers can partially mitigate these attacks by encrypting and 2157 signing the contents of their cookies, or by naming the cookie with 2158 the __Secure- prefix. However, using cryptography does not mitigate 2159 the issue completely because an attacker can replay a cookie he or 2160 she received from the authentic site.example server in the user's 2161 session, with unpredictable results. 2163 Finally, an attacker might be able to force the user agent to delete 2164 cookies by storing a large number of cookies. Once the user agent 2165 reaches its storage limit, the user agent will be forced to evict 2166 some cookies. Servers SHOULD NOT rely upon user agents retaining 2167 cookies. 2169 8.7. Reliance on DNS 2171 Cookies rely upon the Domain Name System (DNS) for security. If the 2172 DNS is partially or fully compromised, the cookie protocol might fail 2173 to provide the security properties required by applications. 2175 8.8. SameSite Cookies 2177 8.8.1. Defense in depth 2179 "SameSite" cookies offer a robust defense against CSRF attack when 2180 deployed in strict mode, and when supported by the client. It is, 2181 however, prudent to ensure that this designation is not the extent of 2182 a site's defense against CSRF, as same-site navigations and 2183 submissions can certainly be executed in conjunction with other 2184 attack vectors such as cross-site scripting. 2186 Developers are strongly encouraged to deploy the usual server-side 2187 defenses (CSRF tokens, ensuring that "safe" HTTP methods are 2188 idempotent, etc) to mitigate the risk more fully. 2190 Additionally, client-side techniques such as those described in 2191 [app-isolation] may also prove effective against CSRF, and are 2192 certainly worth exploring in combination with "SameSite" cookies. 2194 8.8.2. Top-level Navigations 2196 Setting the SameSite attribute in "strict" mode provides robust 2197 defense in depth against CSRF attacks, but has the potential to 2198 confuse users unless sites' developers carefully ensure that their 2199 cookie-based session management systems deal reasonably well with 2200 top-level navigations. 2202 Consider the scenario in which a user reads their email at MegaCorp 2203 Inc's webmail provider https://site.example/. They might expect that 2204 clicking on an emailed link to https://projects.example/secret/ 2205 project would show them the secret project that they're authorized to 2206 see, but if https://projects.example has marked their session cookies 2207 as SameSite=Strict, then this cross-site navigation won't send them 2208 along with the request. https://projects.example will render a 404 2209 error to avoid leaking secret information, and the user will be quite 2210 confused. 2212 Developers can avoid this confusion by adopting a session management 2213 system that relies on not one, but two cookies: one conceptually 2214 granting "read" access, another granting "write" access. The latter 2215 could be marked as SameSite=Strict, and its absence would prompt a 2216 reauthentication step before executing any non-idempotent action. 2218 The former could be marked as SameSite=Lax, in order to allow users 2219 access to data via top-level navigation, or SameSite=None, to permit 2220 access in all contexts (including cross-site embedded contexts). 2222 8.8.3. Mashups and Widgets 2224 The Lax and Strict values for the SameSite attribute are 2225 inappropriate for some important use-cases. In particular, note that 2226 content intended for embedding in cross-site contexts (social 2227 networking widgets or commenting services, for instance) will not 2228 have access to same-site cookies. Cookies which are required in 2229 these situations should be marked with SameSite=None to allow access 2230 in cross-site contexts. 2232 Likewise, some forms of Single-Sign-On might require cookie-based 2233 authentication in a cross-site context; these mechanisms will not 2234 function as intended with same-site cookies and will also require 2235 SameSite=None. 2237 8.8.4. Server-controlled 2239 SameSite cookies in and of themselves don't do anything to address 2240 the general privacy concerns outlined in Section 7.1 of [RFC6265]. 2241 The "SameSite" attribute is set by the server, and serves to mitigate 2242 the risk of certain kinds of attacks that the server is worried 2243 about. The user is not involved in this decision. Moreover, a 2244 number of side-channels exist which could allow a server to link 2245 distinct requests even in the absence of cookies (for example, 2246 connection and/or socket pooling between same-site and cross-site 2247 requests). 2249 8.8.5. Reload navigations 2251 Requests issued for reloads triggered through user interface elements 2252 (such as a refresh button on a toolbar) are same-site only if the 2253 reloaded document was originally navigated to via a same-site 2254 request. This differs from the handling of other reload navigations, 2255 which are always same-site if top-level, since the source browsing 2256 context's active document is precisely the document being reloaded. 2258 This special handling of reloads triggered through a user interface 2259 element avoids sending SameSite cookies on user-initiated reloads if 2260 they were withheld on the original navigation (i.e., if the initial 2261 navigation were cross-site). If the reload navigation were instead 2262 considered same-site, and sent all the initially withheld SameSite 2263 cookies, the security benefits of withholding the cookies in the 2264 first place would be nullified. This is especially important given 2265 that the absence of SameSite cookies withheld on a cross-site 2266 navigation request may lead to visible site breakage, prompting the 2267 user to trigger a reload. 2269 For example, suppose the user clicks on a link from 2270 https://attacker.example/ to https://victim.example/. This is a 2271 cross-site request, so SameSite=Strict cookies are withheld. Suppose 2272 this causes https://victim.example/ to appear broken, because the 2273 site only displays its sensitive content if a particular SameSite 2274 cookie is present in the request. The user, frustrated by the 2275 unexpectedly broken site, presses refresh on their browser's toolbar. 2276 To now consider the reload request same-site and send the initially 2277 withheld SameSite cookie would defeat the purpose of withholding it 2278 in the first place, as the reload navigation triggered through the 2279 user interface may replay the original (potentially malicious) 2280 request. Thus, the reload request should be considered cross-site, 2281 like the request that initially navigated to the page. 2283 8.8.6. Top-level requests with "unsafe" methods 2285 The "Lax" enforcement mode described in Section 5.4.7.1 allows a 2286 cookie to be sent with a cross-site HTTP request if and only if it is 2287 a top-level navigation with a "safe" HTTP method. Implementation 2288 experience shows that this is difficult to apply as the default 2289 behavior, as some sites may rely on cookies not explicitly specifying 2290 a SameSite attribute being included on top-level cross-site requests 2291 with "unsafe" HTTP methods (as was the case prior to the introduction 2292 of the SameSite attribute). 2294 For example, a login flow may involve a cross-site top-level POST 2295 request to an endpoint which expects a cookie with login information. 2296 For such a cookie, "Lax" enforcement is not appropriate, as it would 2297 cause the cookie to be excluded due to the unsafe HTTP request 2298 method. On the other hand, "None" enforcement would allow the cookie 2299 to be sent with all cross-site requests, which may not be desirable 2300 due to the cookie's sensitive contents. 2302 The "Lax-allowing-unsafe" enforcement mode described in 2303 Section 5.4.7.2 retains some of the protections of "Lax" enforcement 2304 (as compared to "None") while still allowing cookies to be sent 2305 cross-site with unsafe top-level requests. 2307 As a more permissive variant of "Lax" mode, "Lax-allowing-unsafe" 2308 mode necessarily provides fewer protections against CSRF. 2309 Ultimately, the provision of such an enforcement mode should be seen 2310 as a temporary, transitional measure to ease adoption of "Lax" 2311 enforcement by default. 2313 9. IANA Considerations 2315 9.1. Cookie 2317 The permanent message header field registry (see [RFC3864]) needs to 2318 be updated with the following registration: 2320 Header field name: Cookie 2322 Applicable protocol: http 2324 Status: standard 2326 Author/Change controller: IETF 2328 Specification document: this specification (Section 5.6.1) 2330 9.2. Set-Cookie 2332 The permanent message header field registry (see [RFC3864]) needs to 2333 be updated with the following registration: 2335 Header field name: Set-Cookie 2337 Applicable protocol: http 2339 Status: standard 2341 Author/Change controller: IETF 2343 Specification document: this specification (Section 5.4) 2345 9.3. Cookie Attribute Registry 2347 IANA is requested to create the "Cookie Attribute Registry", defining 2348 the name space of attribute used to control cookies' behavior. The 2349 registry should be maintained at https://www.iana.org/assignments/ 2350 cookie-attribute-names (https://www.iana.org/assignments/cookie- 2351 attribute-names). 2353 9.3.1. Procedure 2355 Each registered attribute name is associated with a description, and 2356 a reference detailing how the attribute is to be processed and 2357 stored. 2359 New registrations happen on a "RFC Required" basis (see Section 4.7 2360 of [RFC8126]). The attribute to be registered MUST match the 2361 extension-av syntax defined in Section 4.1.1. Note that attribute 2362 names are generally defined in CamelCase, but technically accepted 2363 case-insensitively. 2365 9.3.2. Registration 2367 The "Cookie Attribute Registry" should be created with the 2368 registrations below: 2370 +==========+==================================+ 2371 | Name | Reference | 2372 +==========+==================================+ 2373 | Domain | Section 4.1.2.3 of this document | 2374 +----------+----------------------------------+ 2375 | Expires | Section 4.1.2.1 of this document | 2376 +----------+----------------------------------+ 2377 | HttpOnly | Section 4.1.2.6 of this document | 2378 +----------+----------------------------------+ 2379 | Max-Age | Section 4.1.2.2 of this document | 2380 +----------+----------------------------------+ 2381 | Path | Section 4.1.2.4 of this document | 2382 +----------+----------------------------------+ 2383 | SameSite | Section 4.1.2.7 of this document | 2384 +----------+----------------------------------+ 2385 | Secure | Section 4.1.2.5 of this document | 2386 +----------+----------------------------------+ 2388 Table 1 2390 10. References 2392 10.1. Normative References 2394 [DOM-DOCUMENT-COOKIE] 2395 WHATWG, "HTML - Living Standard", 18 May 2021, 2396 . 2398 [FETCH] van Kesteren, A., "Fetch", n.d., 2399 . 2401 [HTML] Hickson, I., Pieters, S., van Kesteren, A., Jägenstedt, 2402 P., and D. Denicola, "HTML", n.d., 2403 . 2405 [HTTPSEM] Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 2406 Semantics", Work in Progress, Internet-Draft, draft-ietf- 2407 httpbis-semantics-19, 12 September 2021, 2408 . 2411 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 2412 STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987, 2413 . 2415 [RFC1123] Braden, R., Ed., "Requirements for Internet Hosts - 2416 Application and Support", STD 3, RFC 1123, 2417 DOI 10.17487/RFC1123, October 1989, 2418 . 2420 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2421 Requirement Levels", BCP 14, RFC 2119, 2422 DOI 10.17487/RFC2119, March 1997, 2423 . 2425 [RFC3490] Costello, A., "Internationalizing Domain Names in 2426 Applications (IDNA)", RFC 3490, March 2003, 2427 . See Section 6.3 2428 for an explanation why the normative reference to an 2429 obsoleted specification is needed. 2431 [RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet 2432 Application Protocol Collation Registry", RFC 4790, 2433 DOI 10.17487/RFC4790, March 2007, 2434 . 2436 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 2437 Specifications: ABNF", STD 68, RFC 5234, 2438 DOI 10.17487/RFC5234, January 2008, 2439 . 2441 [RFC5890] Klensin, J., "Internationalized Domain Names for 2442 Applications (IDNA): Definitions and Document Framework", 2443 RFC 5890, DOI 10.17487/RFC5890, August 2010, 2444 . 2446 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 2447 DOI 10.17487/RFC6454, December 2011, 2448 . 2450 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2451 Writing an IANA Considerations Section in RFCs", BCP 26, 2452 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2453 . 2455 [SAMESITE] WHATWG, "HTML - Living Standard", 26 January 2021, 2456 . 2458 [SERVICE-WORKERS] 2459 Russell, A., Song, J., and J. Archibald, "Service 2460 Workers", n.d., . 2462 [USASCII] American National Standards Institute, "Coded Character 2463 Set -- 7-bit American Standard Code for Information 2464 Interchange", ANSI X3.4, 1986. 2466 10.2. Informative References 2468 [Aggarwal2010] 2469 Aggarwal, G., Burzstein, E., Jackson, C., and D. Boneh, 2470 "An Analysis of Private Browsing Modes in Modern 2471 Browsers", 2010, 2472 . 2475 [app-isolation] 2476 Chen, E., Bau, J., Reis, C., Barth, A., and C. Jackson, 2477 "App Isolation - Get the Security of Multiple Browsers 2478 with Just One", 2011, 2479 . 2482 [CSRF] Barth, A., Jackson, C., and J. Mitchell, "Robust Defenses 2483 for Cross-Site Request Forgery", 2484 DOI 10.1145/1455770.1455782, ISBN 978-1-59593-810-7, 2485 ACM CCS '08: Proceedings of the 15th ACM conference on 2486 Computer and communications security (pages 75-88), 2487 October 2008, 2488 . 2490 [I-D.ietf-httpbis-cookie-alone] 2491 West, M., "Deprecate modification of 'secure' cookies from 2492 non-secure origins", Work in Progress, Internet-Draft, 2493 draft-ietf-httpbis-cookie-alone-01, 5 September 2016, 2494 . 2497 [I-D.ietf-httpbis-cookie-prefixes] 2498 West, M., "Cookie Prefixes", Work in Progress, Internet- 2499 Draft, draft-ietf-httpbis-cookie-prefixes-00, 23 February 2500 2016, . 2503 [I-D.ietf-httpbis-cookie-same-site] 2504 West, M. and M. Goodwin, "Same-Site Cookies", Work in 2505 Progress, Internet-Draft, draft-ietf-httpbis-cookie-same- 2506 site-00, 20 June 2016, 2507 . 2510 [prerendering] 2511 Bentzel, C., "Chrome Prerendering", n.d., 2512 . 2515 [PSL] "Public Suffix List", n.d., 2516 . 2518 [RFC2109] Kristol, D. and L. Montulli, "HTTP State Management 2519 Mechanism", RFC 2109, DOI 10.17487/RFC2109, February 1997, 2520 . 2522 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 2523 DOI 10.17487/RFC2818, May 2000, 2524 . 2526 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2527 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2528 2003, . 2530 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 2531 Procedures for Message Header Fields", BCP 90, RFC 3864, 2532 DOI 10.17487/RFC3864, September 2004, 2533 . 2535 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2536 Resource Identifier (URI): Generic Syntax", STD 66, 2537 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2538 . 2540 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2541 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 2542 . 2544 [RFC5895] Resnick, P. and P. Hoffman, "Mapping Characters for 2545 Internationalized Domain Names in Applications (IDNA) 2546 2008", RFC 5895, DOI 10.17487/RFC5895, September 2010, 2547 . 2549 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 2550 DOI 10.17487/RFC6265, April 2011, 2551 . 2553 [RFC7034] Ross, D. and T. Gondrom, "HTTP Header Field X-Frame- 2554 Options", RFC 7034, DOI 10.17487/RFC7034, October 2013, 2555 . 2557 [UTS46] Davis, M. and M. Suignard, "Unicode IDNA Compatibility 2558 Processing", UNICODE Unicode Technical Standards # 46, 2559 June 2016, . 2561 Appendix A. Changes 2563 A.1. draft-ietf-httpbis-rfc6265bis-00 2565 * Port [RFC6265] to Markdown. No (intentional) normative changes. 2567 A.2. draft-ietf-httpbis-rfc6265bis-01 2569 * Fixes to formatting caused by mistakes in the initial port to 2570 Markdown: 2572 - https://github.com/httpwg/http-extensions/issues/243 2573 (https://github.com/httpwg/http-extensions/issues/243) 2575 - https://github.com/httpwg/http-extensions/issues/246 2576 (https://github.com/httpwg/http-extensions/issues/246) 2578 * Addresses errata 3444 by updating the path-value and extension-av 2579 grammar, errata 4148 by updating the day-of-month, year, and time 2580 grammar, and errata 3663 by adding the requested note. 2581 https://www.rfc-editor.org/errata_search.php?rfc=6265 2582 (https://www.rfc-editor.org/errata_search.php?rfc=6265) 2584 * Dropped Cookie2 and Set-Cookie2 from the IANA Considerations 2585 section: https://github.com/httpwg/http-extensions/issues/247 2586 (https://github.com/httpwg/http-extensions/issues/247) 2588 * Merged the recommendations from [I-D.ietf-httpbis-cookie-alone], 2589 removing the ability for a non-secure origin to set cookies with a 2590 'secure' flag, and to overwrite cookies whose 'secure' flag is 2591 true. 2593 * Merged the recommendations from 2594 [I-D.ietf-httpbis-cookie-prefixes], adding __Secure- and __Host- 2595 cookie name prefix processing instructions. 2597 A.3. draft-ietf-httpbis-rfc6265bis-02 2599 * Merged the recommendations from 2600 [I-D.ietf-httpbis-cookie-same-site], adding support for the 2601 SameSite attribute. 2603 * Closed a number of editorial bugs: 2605 - Clarified address bar behavior for SameSite cookies: 2606 https://github.com/httpwg/http-extensions/issues/201 2607 (https://github.com/httpwg/http-extensions/issues/201) 2609 - Added the word "Cookies" to the document's name: 2610 https://github.com/httpwg/http-extensions/issues/204 2611 (https://github.com/httpwg/http-extensions/issues/204) 2613 - Clarified that the __Host- prefix requires an explicit Path 2614 attribute: https://github.com/httpwg/http-extensions/issues/222 2615 (https://github.com/httpwg/http-extensions/issues/222) 2617 - Expanded the options for dealing with third-party cookies to 2618 include a brief mention of partitioning based on first-party: 2619 https://github.com/httpwg/http-extensions/issues/248 2620 (https://github.com/httpwg/http-extensions/issues/248) 2622 - Noted that double-quotes in cookie values are part of the 2623 value, and are not stripped: https://github.com/httpwg/http- 2624 extensions/issues/295 (https://github.com/httpwg/http- 2625 extensions/issues/295) 2627 - Fixed the "site for cookies" algorithm to return something that 2628 makes sense: https://github.com/httpwg/http-extensions/ 2629 issues/302 (https://github.com/httpwg/http-extensions/ 2630 issues/302) 2632 A.4. draft-ietf-httpbis-rfc6265bis-03 2634 * Clarified handling of invalid SameSite values: 2635 https://github.com/httpwg/http-extensions/issues/389 2636 (https://github.com/httpwg/http-extensions/issues/389) 2638 * Reflect widespread implementation practice of including a cookie's 2639 host-only-flag when calculating its uniqueness: 2640 https://github.com/httpwg/http-extensions/issues/199 2641 (https://github.com/httpwg/http-extensions/issues/199) 2643 * Introduced an explicit "None" value for the SameSite attribute: 2644 https://github.com/httpwg/http-extensions/issues/788 2645 (https://github.com/httpwg/http-extensions/issues/788) 2647 A.5. draft-ietf-httpbis-rfc6265bis-04 2649 * Allow SameSite cookies to be set for all top-level navigations. 2650 https://github.com/httpwg/http-extensions/issues/594 2651 (https://github.com/httpwg/http-extensions/issues/594) 2653 * Treat Set-Cookie: token as creating the cookie ("", "token"): 2654 https://github.com/httpwg/http-extensions/issues/159 2655 (https://github.com/httpwg/http-extensions/issues/159) 2657 * Reject cookies with neither name nor value (e.g. Set-Cookie: = 2658 and Set-Cookie:: https://github.com/httpwg/http-extensions/ 2659 issues/159 (https://github.com/httpwg/http-extensions/issues/159) 2661 * Clarified behavior of multiple SameSite attributes in a cookie 2662 string: https://github.com/httpwg/http-extensions/issues/901 2663 (https://github.com/httpwg/http-extensions/issues/901) 2665 A.6. draft-ietf-httpbis-rfc6265bis-05 2667 * Typos and editorial fixes: https://github.com/httpwg/http- 2668 extensions/pull/1035 (https://github.com/httpwg/http-extensions/ 2669 pull/1035), https://github.com/httpwg/http-extensions/pull/1038 2670 (https://github.com/httpwg/http-extensions/pull/1038), 2671 https://github.com/httpwg/http-extensions/pull/1040 2672 (https://github.com/httpwg/http-extensions/pull/1040), 2673 https://github.com/httpwg/http-extensions/pull/1047 2674 (https://github.com/httpwg/http-extensions/pull/1047). 2676 A.7. draft-ietf-httpbis-rfc6265bis-06 2678 * Editorial fixes: https://github.com/httpwg/http-extensions/ 2679 issues/1059 (https://github.com/httpwg/http-extensions/ 2680 issues/1059), https://github.com/httpwg/http-extensions/ 2681 issues/1158 (https://github.com/httpwg/http-extensions/ 2682 issues/1158). 2684 * Created a registry for cookie attribute names: 2685 https://github.com/httpwg/http-extensions/pull/1060 2686 (https://github.com/httpwg/http-extensions/pull/1060). 2688 * Tweaks to ABNF for cookie-pair and the Cookie header production: 2689 https://github.com/httpwg/http-extensions/issues/1074 2690 (https://github.com/httpwg/http-extensions/issues/1074), 2691 https://github.com/httpwg/http-extensions/issues/1119 2692 (https://github.com/httpwg/http-extensions/issues/1119). 2694 * Fixed serialization for nameless/valueless cookies: 2695 https://github.com/httpwg/http-extensions/pull/1143 2696 (https://github.com/httpwg/http-extensions/pull/1143). 2698 * Converted a normative reference to Mozilla's Public Suffix List 2699 [PSL] into an informative reference: https://github.com/httpwg/ 2700 http-extensions/issues/1159 (https://github.com/httpwg/http- 2701 extensions/issues/1159). 2703 A.8. draft-ietf-httpbis-rfc6265bis-07 2705 * Moved instruction to ignore cookies with empty cookie-name and 2706 cookie-value from Section 5.4 to Section 5.5 to ensure that they 2707 apply to cookies created without parsing a cookie string: 2708 https://github.com/httpwg/http-extensions/issues/1234 2709 (https://github.com/httpwg/http-extensions/issues/1234). 2711 * Add a default enforcement value to the same-site-flag, equivalent 2712 to "SameSite=Lax": https://github.com/httpwg/http-extensions/ 2713 pull/1325 (https://github.com/httpwg/http-extensions/pull/1325). 2715 * Require a Secure attribute for "SameSite=None": 2716 https://github.com/httpwg/http-extensions/pull/1323 2717 (https://github.com/httpwg/http-extensions/pull/1323). 2719 * Consider scheme when running the same-site algorithm: 2720 https://github.com/httpwg/http-extensions/pull/1324 2721 (https://github.com/httpwg/http-extensions/pull/1324). 2723 A.9. draft-ietf-httpbis-rfc6265bis-08 2725 * Define "same-site" for reload navigation requests, e.g. those 2726 triggered via user interface elements: https://github.com/httpwg/ 2727 http-extensions/pull/1384 (https://github.com/httpwg/http- 2728 extensions/pull/1384) 2730 * Consider redirects when defining same-site: 2731 https://github.com/httpwg/http-extensions/pull/1348 2732 (https://github.com/httpwg/http-extensions/pull/1348) 2734 * Align on using HTML terminology for origins: 2735 https://github.com/httpwg/http-extensions/pull/1416 2736 (https://github.com/httpwg/http-extensions/pull/1416) 2738 * Modify cookie parsing and creation algorithms in Section 5.4 and 2739 Section 5.5 to explicitly handle control characters: 2740 https://github.com/httpwg/http-extensions/pull/1420 2741 (https://github.com/httpwg/http-extensions/pull/1420) 2743 * Refactor cookie retrieval algorithm to support non-HTTP APIs: 2744 https://github.com/httpwg/http-extensions/pull/1428 2745 (https://github.com/httpwg/http-extensions/pull/1428) 2747 * Define "Lax-allowing-unsafe" SameSite enforcement mode: 2748 https://github.com/httpwg/http-extensions/pull/1435 2749 (https://github.com/httpwg/http-extensions/pull/1435) 2751 * Consistently use "header field" (vs 'header"): 2752 https://github.com/httpwg/http-extensions/pull/1527 2753 (https://github.com/httpwg/http-extensions/pull/1527) 2755 A.10. draft-ietf-httpbis-rfc6265bis-09 2757 * Update cookie size requirements: https://github.com/httpwg/http- 2758 extensions/pull/1563 (https://github.com/httpwg/http-extensions/ 2759 pull/1563) 2761 * Reject cookies with control characters: https://github.com/httpwg/ 2762 http-extensions/pull/1576 (https://github.com/httpwg/http- 2763 extensions/pull/1576) 2765 * No longer treat horizontal tab as a control character: 2766 https://github.com/httpwg/http-extensions/pull/1589 2767 (https://github.com/httpwg/http-extensions/pull/1589) 2769 * Specify empty domain attribute handling: 2770 https://github.com/httpwg/http-extensions/pull/1709 2771 (https://github.com/httpwg/http-extensions/pull/1709) 2773 A.11. draft-ietf-httpbis-rfc6265bis-10 2775 * Standardize Max-Age/Expires upper bound: 2776 https://github.com/httpwg/http-extensions/pull/1732 2777 (https://github.com/httpwg/http-extensions/pull/1732) 2779 Acknowledgements 2781 RFC 6265 was written by Adam Barth. This document is an update of 2782 RFC 6265, adding features and aligning the specification with the 2783 reality of today's deployments. Here, we're standing upon the 2784 shoulders of a giant since the majority of the text is still Adam's. 2786 Authors' Addresses 2788 Lily Chen (editor) 2789 Google LLC 2790 Email: chlily@google.com 2792 Steven Englehardt (editor) 2793 Mozilla 2794 Email: senglehardt@mozilla.com 2796 Mike West (editor) 2797 Google LLC 2798 Email: mkwst@google.com 2799 URI: https://mikewest.org/ 2801 John Wilander (editor) 2802 Apple, Inc 2803 Email: wilander@apple.com