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