idnits 2.17.1 draft-ietf-httpbis-rfc6265bis-05.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 (February 5, 2020) is 1542 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 2208 -- Looks like a reference, but probably isn't: '2' on line 2210 -- Looks like a reference, but probably isn't: '3' on line 2212 -- Looks like a reference, but probably isn't: '4' on line 2267 -- Looks like a reference, but probably isn't: '5' on line 2269 -- Looks like a reference, but probably isn't: '6' on line 2274 -- Looks like a reference, but probably isn't: '7' on line 2277 -- Looks like a reference, but probably isn't: '8' on line 2297 -- Looks like a reference, but probably isn't: '9' on line 2300 -- Looks like a reference, but probably isn't: '10' on line 2304 -- Looks like a reference, but probably isn't: '11' on line 2308 -- Looks like a reference, but probably isn't: '12' on line 2312 -- Looks like a reference, but probably isn't: '13' on line 2316 -- Looks like a reference, but probably isn't: '14' on line 2321 -- Looks like a reference, but probably isn't: '15' on line 2325 -- Looks like a reference, but probably isn't: '16' on line 2328 -- Looks like a reference, but probably isn't: '17' on line 2333 -- Looks like a reference, but probably isn't: '18' on line 2336 -- Looks like a reference, but probably isn't: '19' on line 2340 -- Looks like a reference, but probably isn't: '20' on line 2343 -- Looks like a reference, but probably isn't: '21' on line 2348 -- Looks like a reference, but probably isn't: '22' on line 2349 -- Looks like a reference, but probably isn't: '23' on line 2350 -- Looks like a reference, but probably isn't: '24' on line 2351 -- 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 (==), 31 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: August 8, 2020 February 5, 2020 8 Cookies: HTTP State Management Mechanism 9 draft-ietf-httpbis-rfc6265bis-05 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 August 8, 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 . . . . . . . . . . . . . . . . . . . . 33 111 6. Implementation Considerations . . . . . . . . . . . . . . . . 35 112 6.1. Limits . . . . . . . . . . . . . . . . . . . . . . . . . 35 113 6.2. Application Programming Interfaces . . . . . . . . . . . 36 114 6.3. IDNA Dependency and Migration . . . . . . . . . . . . . . 36 115 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 36 116 7.1. Third-Party Cookies . . . . . . . . . . . . . . . . . . . 37 117 7.2. User Controls . . . . . . . . . . . . . . . . . . . . . . 37 118 7.3. Expiration Dates . . . . . . . . . . . . . . . . . . . . 38 119 8. Security Considerations . . . . . . . . . . . . . . . . . . . 38 120 8.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 38 121 8.2. Ambient Authority . . . . . . . . . . . . . . . . . . . . 38 122 8.3. Clear Text . . . . . . . . . . . . . . . . . . . . . . . 39 123 8.4. Session Identifiers . . . . . . . . . . . . . . . . . . . 40 124 8.5. Weak Confidentiality . . . . . . . . . . . . . . . . . . 40 125 8.6. Weak Integrity . . . . . . . . . . . . . . . . . . . . . 41 126 8.7. Reliance on DNS . . . . . . . . . . . . . . . . . . . . . 42 127 8.8. SameSite Cookies . . . . . . . . . . . . . . . . . . . . 42 128 8.8.1. Defense in depth . . . . . . . . . . . . . . . . . . 42 129 8.8.2. Top-level Navigations . . . . . . . . . . . . . . . . 42 130 8.8.3. Mashups and Widgets . . . . . . . . . . . . . . . . . 43 131 8.8.4. Server-controlled . . . . . . . . . . . . . . . . . . 43 132 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44 133 9.1. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . 44 134 9.2. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . 44 135 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 44 136 10.1. Normative References . . . . . . . . . . . . . . . . . . 44 137 10.2. Informative References . . . . . . . . . . . . . . . . . 46 138 10.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 47 139 Appendix A. Changes . . . . . . . . . . . . . . . . . . . . . . 48 140 A.1. draft-ietf-httpbis-rfc6265bis-00 . . . . . . . . . . . . 48 141 A.2. draft-ietf-httpbis-rfc6265bis-01 . . . . . . . . . . . . 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 A.6. draft-ietf-httpbis-rfc6265bis-05 . . . . . . . . . . . . 50 146 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 50 147 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 51 149 1. Introduction 151 This document defines the HTTP Cookie and Set-Cookie header fields. 152 Using the Set-Cookie header field, an HTTP server can pass name/value 153 pairs and associated metadata (called cookies) to a user agent. When 154 the user agent makes subsequent requests to the server, the user 155 agent uses the metadata and other information to determine whether to 156 return the name/value pairs in the Cookie header. 158 Although simple on their surface, cookies have a number of 159 complexities. For example, the server indicates a scope for each 160 cookie when sending it to the user agent. The scope indicates the 161 maximum amount of time in which the user agent should return the 162 cookie, the servers to which the user agent should return the cookie, 163 and the URI schemes for which the cookie is applicable. 165 For historical reasons, cookies contain a number of security and 166 privacy infelicities. For example, a server can indicate that a 167 given cookie is intended for "secure" connections, but the Secure 168 attribute does not provide integrity in the presence of an active 169 network attacker. Similarly, cookies for a given host are shared 170 across all the ports on that host, even though the usual "same-origin 171 policy" used by web browsers isolates content retrieved via different 172 ports. 174 There are two audiences for this specification: developers of cookie- 175 generating servers and developers of cookie-consuming user agents. 177 To maximize interoperability with user agents, servers SHOULD limit 178 themselves to the well-behaved profile defined in Section 4 when 179 generating cookies. 181 User agents MUST implement the more liberal processing rules defined 182 in Section 5, in order to maximize interoperability with existing 183 servers that do not conform to the well-behaved profile defined in 184 Section 4. 186 This document specifies the syntax and semantics of these headers as 187 they are actually used on the Internet. In particular, this document 188 does not create new syntax or semantics beyond those in use today. 189 The recommendations for cookie generation provided in Section 4 190 represent a preferred subset of current server behavior, and even the 191 more liberal cookie processing algorithm provided in Section 5 does 192 not recommend all of the syntactic and semantic variations in use 193 today. Where some existing software differs from the recommended 194 protocol in significant ways, the document contains a note explaining 195 the difference. 197 This document obsoletes [RFC6265]. 199 2. Conventions 201 2.1. Conformance Criteria 203 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 204 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 205 document are to be interpreted as described in [RFC2119]. 207 Requirements phrased in the imperative as part of algorithms (such as 208 "strip any leading space characters" or "return false and abort these 209 steps") are to be interpreted with the meaning of the key word 210 ("MUST", "SHOULD", "MAY", etc.) used in introducing the algorithm. 212 Conformance requirements phrased as algorithms or specific steps can 213 be implemented in any manner, so long as the end result is 214 equivalent. In particular, the algorithms defined in this 215 specification are intended to be easy to understand and are not 216 intended to be performant. 218 2.2. Syntax Notation 220 This specification uses the Augmented Backus-Naur Form (ABNF) 221 notation of [RFC5234]. 223 The following core rules are included by reference, as defined in 224 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 225 (CR LF), CTLs (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 226 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), NUL (null octet), 227 OCTET (any 8-bit sequence of data except NUL), SP (space), HTAB 228 (horizontal tab), CHAR (any [USASCII] character), VCHAR (any visible 229 [USASCII] character), and WSP (whitespace). 231 The OWS (optional whitespace) rule is used where zero or more linear 232 whitespace characters MAY appear: 234 OWS = *( [ obs-fold ] WSP ) 235 ; "optional" whitespace 236 obs-fold = CRLF 238 OWS SHOULD either not be produced or be produced as a single SP 239 character. 241 2.3. Terminology 243 The terms "user agent", "client", "server", "proxy", and "origin 244 server" have the same meaning as in the HTTP/1.1 specification 245 ([RFC7230], Section 2). 247 The request-host is the name of the host, as known by the user agent, 248 to which the user agent is sending an HTTP request or from which it 249 is receiving an HTTP response (i.e., the name of the host to which it 250 sent the corresponding HTTP request). 252 The term request-uri refers to "request-target" as defined in 253 Section 5.3 of [RFC7230]. 255 Two sequences of octets are said to case-insensitively match each 256 other if and only if they are equivalent under the i;ascii-casemap 257 collation defined in [RFC4790]. 259 The term string means a sequence of non-NUL octets. 261 The terms "active document", "ancestor browsing context", "browsing 262 context", "dedicated worker", "Document", "WorkerGlobalScope", 263 "sandboxed origin browsing context flag", "parent browsing context", 264 "shared worker", "the worker's Documents", "nested browsing context", 265 and "top-level browsing context" are defined in [HTML]. 267 "Service Workers" are defined in the Service Workers specification 268 [SERVICE-WORKERS]. 270 The term "origin", the mechanism of deriving an origin from a URI, 271 and the "the same" matching algorithm for origins are defined in 272 [RFC6454]. 274 "Safe" HTTP methods include "GET", "HEAD", "OPTIONS", and "TRACE", as 275 defined in Section 4.2.1 of [RFC7231]. 277 A domain's "public suffix" is the portion of a domain that is 278 controlled by a public registry, such as "com", "co.uk", and 279 "pvt.k12.wy.us" [PSL]. A domain's "registrable domain" is the 280 domain's public suffix plus the label to its left. That is, for 281 "https://www.site.example", the public suffix is "example", and the 282 registrable domain is "site.example". This concept is defined more 283 rigorously in [PSL], which specifies a formal algorithm to obtain 284 both. 286 The term "request", as well as a request's "client", "current url", 287 "method", and "target browsing context", are defined in [FETCH]. 289 3. Overview 291 This section outlines a way for an origin server to send state 292 information to a user agent and for the user agent to return the 293 state information to the origin server. 295 To store state, the origin server includes a Set-Cookie header in an 296 HTTP response. In subsequent requests, the user agent returns a 297 Cookie request header to the origin server. The Cookie header 298 contains cookies the user agent received in previous Set-Cookie 299 headers. The origin server is free to ignore the Cookie header or 300 use its contents for an application-defined purpose. 302 Origin servers MAY send a Set-Cookie response header with any 303 response. User agents MAY ignore Set-Cookie headers contained in 304 responses with 100-level status codes but MUST process Set-Cookie 305 headers contained in other responses (including responses with 400- 306 and 500-level status codes). An origin server can include multiple 307 Set-Cookie header fields in a single response. The presence of a 308 Cookie or a Set-Cookie header field does not preclude HTTP caches 309 from storing and reusing a response. 311 Origin servers SHOULD NOT fold multiple Set-Cookie header fields into 312 a single header field. The usual mechanism for folding HTTP headers 313 fields (i.e., as defined in Section 3.2.2 of [RFC7230]) might change 314 the semantics of the Set-Cookie header field because the %x2C (",") 315 character is used by Set-Cookie in a way that conflicts with such 316 folding. 318 3.1. Examples 320 Using the Set-Cookie header, a server can send the user agent a short 321 string in an HTTP response that the user agent will return in future 322 HTTP requests that are within the scope of the cookie. For example, 323 the server can send the user agent a "session identifier" named SID 324 with the value 31d4d96e407aad42. The user agent then returns the 325 session identifier in subsequent requests. 327 == Server -> User Agent == 329 Set-Cookie: SID=31d4d96e407aad42 331 == User Agent -> Server == 333 Cookie: SID=31d4d96e407aad42 335 The server can alter the default scope of the cookie using the Path 336 and Domain attributes. For example, the server can instruct the user 337 agent to return the cookie to every path and every subdomain of 338 site.example. 340 == Server -> User Agent == 342 Set-Cookie: SID=31d4d96e407aad42; Path=/; Domain=site.example 344 == User Agent -> Server == 346 Cookie: SID=31d4d96e407aad42 348 As shown in the next example, the server can store multiple cookies 349 at the user agent. For example, the server can store a session 350 identifier as well as the user's preferred language by returning two 351 Set-Cookie header fields. Notice that the server uses the Secure and 352 HttpOnly attributes to provide additional security protections for 353 the more sensitive session identifier (see Section 4.1.2). 355 == Server -> User Agent == 357 Set-Cookie: SID=31d4d96e407aad42; Path=/; Secure; HttpOnly 358 Set-Cookie: lang=en-US; Path=/; Domain=site.example 360 == User Agent -> Server == 362 Cookie: SID=31d4d96e407aad42; lang=en-US 364 Notice that the Cookie header above contains two cookies, one named 365 SID and one named lang. If the server wishes the user agent to 366 persist the cookie over multiple "sessions" (e.g., user agent 367 restarts), the server can specify an expiration date in the Expires 368 attribute. Note that the user agent might delete the cookie before 369 the expiration date if the user agent's cookie store exceeds its 370 quota or if the user manually deletes the server's cookie. 372 == Server -> User Agent == 374 Set-Cookie: lang=en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT 376 == User Agent -> Server == 378 Cookie: SID=31d4d96e407aad42; lang=en-US 380 Finally, to remove a cookie, the server returns a Set-Cookie header 381 with an expiration date in the past. The server will be successful 382 in removing the cookie only if the Path and the Domain attribute in 383 the Set-Cookie header match the values used when the cookie was 384 created. 386 == Server -> User Agent == 388 Set-Cookie: lang=; Expires=Sun, 06 Nov 1994 08:49:37 GMT 390 == User Agent -> Server == 392 Cookie: SID=31d4d96e407aad42 394 4. Server Requirements 396 This section describes the syntax and semantics of a well-behaved 397 profile of the Cookie and Set-Cookie headers. 399 4.1. Set-Cookie 401 The Set-Cookie HTTP response header is used to send cookies from the 402 server to the user agent. 404 4.1.1. Syntax 406 Informally, the Set-Cookie response header contains the header name 407 "Set-Cookie" followed by a ":" and a cookie. Each cookie begins with 408 a name-value-pair, followed by zero or more attribute-value pairs. 409 Servers SHOULD NOT send Set-Cookie headers that fail to conform to 410 the following grammar: 412 set-cookie-header = "Set-Cookie:" SP set-cookie-string 413 set-cookie-string = cookie-pair *( ";" SP cookie-av ) 414 cookie-pair = cookie-name "=" cookie-value 415 cookie-name = token 416 cookie-value = *cookie-octet / ( DQUOTE *cookie-octet DQUOTE ) 417 cookie-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E 418 ; US-ASCII characters excluding CTLs, 419 ; whitespace DQUOTE, comma, semicolon, 420 ; and backslash 421 token = 423 cookie-av = expires-av / max-age-av / domain-av / 424 path-av / secure-av / httponly-av / 425 samesite-av / extension-av 426 expires-av = "Expires=" sane-cookie-date 427 sane-cookie-date = 428 429 max-age-av = "Max-Age=" non-zero-digit *DIGIT 430 ; In practice, both expires-av and max-age-av 431 ; are limited to dates representable by the 432 ; user agent. 433 non-zero-digit = %x31-39 434 ; digits 1 through 9 435 domain-av = "Domain=" domain-value 436 domain-value = 437 ; defined in [RFC1034], Section 3.5, as 438 ; enhanced by [RFC1123], Section 2.1 439 path-av = "Path=" path-value 440 path-value = *av-octet 441 secure-av = "Secure" 442 httponly-av = "HttpOnly" 443 samesite-av = "SameSite=" samesite-value 444 samesite-value = "Strict" / "Lax" / "None" 445 extension-av = *av-octet 446 av-octet = %x20-3A / %x3C-7E 447 ; any CHAR except CTLs or ";" 449 Note that some of the grammatical terms above reference documents 450 that use different grammatical notations than this document (which 451 uses ABNF from [RFC5234]). 453 The semantics of the cookie-value are not defined by this document. 455 To maximize compatibility with user agents, servers that wish to 456 store arbitrary data in a cookie-value SHOULD encode that data, for 457 example, using Base64 [RFC4648]. 459 Per the grammar above, the cookie-value MAY be wrapped in DQUOTE 460 characters. Note that in this case, the initial and trailing DQUOTE 461 characters are not stripped. They are part of the cookie-value, and 462 will be included in Cookie headers sent to the server. 464 The portions of the set-cookie-string produced by the cookie-av term 465 are known as attributes. To maximize compatibility with user agents, 466 servers SHOULD NOT produce two attributes with the same name in the 467 same set-cookie-string. (See Section 5.4 for how user agents handle 468 this case.) 470 Servers SHOULD NOT include more than one Set-Cookie header field in 471 the same response with the same cookie-name. (See Section 5.3 for 472 how user agents handle this case.) 474 If a server sends multiple responses containing Set-Cookie headers 475 concurrently to the user agent (e.g., when communicating with the 476 user agent over multiple sockets), these responses create a "race 477 condition" that can lead to unpredictable behavior. 479 NOTE: Some existing user agents differ in their interpretation of 480 two-digit years. To avoid compatibility issues, servers SHOULD use 481 the rfc1123-date format, which requires a four-digit year. 483 NOTE: Some user agents store and process dates in cookies as 32-bit 484 UNIX time_t values. Implementation bugs in the libraries supporting 485 time_t processing on some systems might cause such user agents to 486 process dates after the year 2038 incorrectly. 488 4.1.2. Semantics (Non-Normative) 490 This section describes simplified semantics of the Set-Cookie header. 491 These semantics are detailed enough to be useful for understanding 492 the most common uses of cookies by servers. The full semantics are 493 described in Section 5. 495 When the user agent receives a Set-Cookie header, the user agent 496 stores the cookie together with its attributes. Subsequently, when 497 the user agent makes an HTTP request, the user agent includes the 498 applicable, non-expired cookies in the Cookie header. 500 If the user agent receives a new cookie with the same cookie-name, 501 domain-value, and path-value as a cookie that it has already stored, 502 the existing cookie is evicted and replaced with the new cookie. 503 Notice that servers can delete cookies by sending the user agent a 504 new cookie with an Expires attribute with a value in the past. 506 Unless the cookie's attributes indicate otherwise, the cookie is 507 returned only to the origin server (and not, for example, to any 508 subdomains), and it expires at the end of the current session (as 509 defined by the user agent). User agents ignore unrecognized cookie 510 attributes (but not the entire cookie). 512 4.1.2.1. The Expires Attribute 514 The Expires attribute indicates the maximum lifetime of the cookie, 515 represented as the date and time at which the cookie expires. The 516 user agent is not required to retain the cookie until the specified 517 date has passed. In fact, user agents often evict cookies due to 518 memory pressure or privacy concerns. 520 4.1.2.2. The Max-Age Attribute 522 The Max-Age attribute indicates the maximum lifetime of the cookie, 523 represented as the number of seconds until the cookie expires. The 524 user agent is not required to retain the cookie for the specified 525 duration. In fact, user agents often evict cookies due to memory 526 pressure or privacy concerns. 528 NOTE: Some existing user agents do not support the Max-Age attribute. 529 User agents that do not support the Max-Age attribute ignore the 530 attribute. 532 If a cookie has both the Max-Age and the Expires attribute, the Max- 533 Age attribute has precedence and controls the expiration date of the 534 cookie. If a cookie has neither the Max-Age nor the Expires 535 attribute, the user agent will retain the cookie until "the current 536 session is over" (as defined by the user agent). 538 4.1.2.3. The Domain Attribute 540 The Domain attribute specifies those hosts to which the cookie will 541 be sent. For example, if the value of the Domain attribute is 542 "site.example", the user agent will include the cookie in the Cookie 543 header when making HTTP requests to site.example, www.site.example, 544 and www.corp.site.example. (Note that a leading %x2E ("."), if 545 present, is ignored even though that character is not permitted, but 546 a trailing %x2E ("."), if present, will cause the user agent to 547 ignore the attribute.) If the server omits the Domain attribute, the 548 user agent will return the cookie only to the origin server. 550 WARNING: Some existing user agents treat an absent Domain attribute 551 as if the Domain attribute were present and contained the current 552 host name. For example, if site.example returns a Set-Cookie header 553 without a Domain attribute, these user agents will erroneously send 554 the cookie to www.site.example as well. 556 The user agent will reject cookies unless the Domain attribute 557 specifies a scope for the cookie that would include the origin 558 server. For example, the user agent will accept a cookie with a 559 Domain attribute of "site.example" or of "foo.site.example" from 560 foo.site.example, but the user agent will not accept a cookie with a 561 Domain attribute of "bar.site.example" or of "baz.foo.site.example". 563 NOTE: For security reasons, many user agents are configured to reject 564 Domain attributes that correspond to "public suffixes". For example, 565 some user agents will reject Domain attributes of "com" or "co.uk". 566 (See Section 5.4 for more information.) 568 4.1.2.4. The Path Attribute 570 The scope of each cookie is limited to a set of paths, controlled by 571 the Path attribute. If the server omits the Path attribute, the user 572 agent will use the "directory" of the request-uri's path component as 573 the default value. (See Section 5.1.4 for more details.) 575 The user agent will include the cookie in an HTTP request only if the 576 path portion of the request-uri matches (or is a subdirectory of) the 577 cookie's Path attribute, where the %x2F ("/") character is 578 interpreted as a directory separator. 580 Although seemingly useful for isolating cookies between different 581 paths within a given host, the Path attribute cannot be relied upon 582 for security (see Section 8). 584 4.1.2.5. The Secure Attribute 586 The Secure attribute limits the scope of the cookie to "secure" 587 channels (where "secure" is defined by the user agent). When a 588 cookie has the Secure attribute, the user agent will include the 589 cookie in an HTTP request only if the request is transmitted over a 590 secure channel (typically HTTP over Transport Layer Security (TLS) 591 [RFC2818]). 593 Although seemingly useful for protecting cookies from active network 594 attackers, the Secure attribute protects only the cookie's 595 confidentiality. An active network attacker can overwrite Secure 596 cookies from an insecure channel, disrupting their integrity (see 597 Section 8.6 for more details). 599 4.1.2.6. The HttpOnly Attribute 601 The HttpOnly attribute limits the scope of the cookie to HTTP 602 requests. In particular, the attribute instructs the user agent to 603 omit the cookie when providing access to cookies via "non-HTTP" APIs 604 (such as a web browser API that exposes cookies to scripts). 606 Note that the HttpOnly attribute is independent of the Secure 607 attribute: a cookie can have both the HttpOnly and the Secure 608 attribute. 610 4.1.2.7. The SameSite Attribute 612 The "SameSite" attribute limits the scope of the cookie such that it 613 will only be attached to requests if those requests are same-site, as 614 defined by the algorithm in Section 5.2. For example, requests for 615 "https://site.example/sekrit-image" will attach same-site cookies if 616 and only if initiated from a context whose "site for cookies" is 617 "site.example". 619 If the "SameSite" attribute's value is "Strict", the cookie will only 620 be sent along with "same-site" requests. If the value is "Lax", the 621 cookie will be sent with same-site requests, and with "cross-site" 622 top-level navigations, as described in Section 5.3.7.1. If the value 623 is "None", the cookie will be sent with same-site and cross-site 624 requests. If the "SameSite" attribute's value is something other 625 than these three known keywords, the attribute's value will be 626 treated as "None". 628 The "SameSite" attribute affects cookie creation as well as delivery. 629 Cookies which assert "SameSite=Lax" or "SameSite=Strict" cannot be 630 set in responses to cross-site subresource requests, or cross-site 631 nested navigations. They can be set along with any top-level 632 navigation, cross-site or otherwise. 634 4.1.3. Cookie Name Prefixes 636 Section 8.5 and Section 8.6 of this document spell out some of the 637 drawbacks of cookies' historical implementation. In particular, it 638 is impossible for a server to have confidence that a given cookie was 639 set with a particular set of attributes. In order to provide such 640 confidence in a backwards-compatible way, two common sets of 641 requirements can be inferred from the first few characters of the 642 cookie's name. 644 The normative requirements for the prefixes described below are 645 detailed in the storage model algorithm defined in Section 5.4. 647 4.1.3.1. The "__Secure-" Prefix 649 If a cookie's name begins with a case-sensitive match for the string 650 "__Secure-", then the cookie will have been set with a "Secure" 651 attribute. 653 For example, the following "Set-Cookie" header would be rejected by a 654 conformant user agent, as it does not have a "Secure" attribute. 656 Set-Cookie: __Secure-SID=12345; Domain=site.example 658 Whereas the following "Set-Cookie" header would be accepted: 660 Set-Cookie: __Secure-SID=12345; Domain=site.example; Secure 662 4.1.3.2. The "__Host-" Prefix 664 If a cookie's name begins with a case-sensitive match for the string 665 "__Host-", then the cookie will have been set with a "Secure" 666 attribute, a "Path" attribute with a value of "/", and no "Domain" 667 attribute. 669 This combination yields a cookie that hews as closely as a cookie can 670 to treating the origin as a security boundary. The lack of a 671 "Domain" attribute ensures that the cookie's "host-only-flag" is 672 true, locking the cookie to a particular host, rather than allowing 673 it to span subdomains. Setting the "Path" to "/" means that the 674 cookie is effective for the entire host, and won't be overridden for 675 specific paths. The "Secure" attribute ensures that the cookie is 676 unaltered by non-secure origins, and won't span protocols. 678 Ports are the only piece of the origin model that "__Host-" cookies 679 continue to ignore. 681 For example, the following cookies would always be rejected: 683 Set-Cookie: __Host-SID=12345 684 Set-Cookie: __Host-SID=12345; Secure 685 Set-Cookie: __Host-SID=12345; Domain=site.example 686 Set-Cookie: __Host-SID=12345; Domain=site.example; Path=/ 687 Set-Cookie: __Host-SID=12345; Secure; Domain=site.example; Path=/ 689 While the would be accepted if set from a secure origin (e.g. 690 "https://site.example/"), and rejected otherwise: 692 Set-Cookie: __Host-SID=12345; Secure; Path=/ 694 4.2. Cookie 696 4.2.1. Syntax 698 The user agent sends stored cookies to the origin server in the 699 Cookie header. If the server conforms to the requirements in 700 Section 4.1 (and the user agent conforms to the requirements in 701 Section 5), the user agent will send a Cookie header that conforms to 702 the following grammar: 704 cookie-header = "Cookie:" OWS cookie-string OWS 705 cookie-string = cookie-pair *( ";" SP cookie-pair ) 707 4.2.2. Semantics 709 Each cookie-pair represents a cookie stored by the user agent. The 710 cookie-pair contains the cookie-name and cookie-value the user agent 711 received in the Set-Cookie header. 713 Notice that the cookie attributes are not returned. In particular, 714 the server cannot determine from the Cookie header alone when a 715 cookie will expire, for which hosts the cookie is valid, for which 716 paths the cookie is valid, or whether the cookie was set with the 717 Secure or HttpOnly attributes. 719 The semantics of individual cookies in the Cookie header are not 720 defined by this document. Servers are expected to imbue these 721 cookies with application-specific semantics. 723 Although cookies are serialized linearly in the Cookie header, 724 servers SHOULD NOT rely upon the serialization order. In particular, 725 if the Cookie header contains two cookies with the same name (e.g., 726 that were set with different Path or Domain attributes), servers 727 SHOULD NOT rely upon the order in which these cookies appear in the 728 header. 730 5. User Agent Requirements 732 This section specifies the Cookie and Set-Cookie headers in 733 sufficient detail that a user agent implementing these requirements 734 precisely can interoperate with existing servers (even those that do 735 not conform to the well-behaved profile described in Section 4). 737 A user agent could enforce more restrictions than those specified 738 herein (e.g., for the sake of improved security); however, 739 experiments have shown that such strictness reduces the likelihood 740 that a user agent will be able to interoperate with existing servers. 742 5.1. Subcomponent Algorithms 744 This section defines some algorithms used by user agents to process 745 specific subcomponents of the Cookie and Set-Cookie headers. 747 5.1.1. Dates 749 The user agent MUST use an algorithm equivalent to the following 750 algorithm to parse a cookie-date. Note that the various boolean 751 flags defined as a part of the algorithm (i.e., found-time, found- 752 day-of-month, found-month, found-year) are initially "not set". 754 1. Using the grammar below, divide the cookie-date into date-tokens. 756 cookie-date = *delimiter date-token-list *delimiter 757 date-token-list = date-token *( 1*delimiter date-token ) 758 date-token = 1*non-delimiter 760 delimiter = %x09 / %x20-2F / %x3B-40 / %x5B-60 / %x7B-7E 761 non-delimiter = %x00-08 / %x0A-1F / DIGIT / ":" / ALPHA / %x7F-FF 762 non-digit = %x00-2F / %x3A-FF 764 day-of-month = 1*2DIGIT [ non-digit *OCTET ] 765 month = ( "jan" / "feb" / "mar" / "apr" / 766 "may" / "jun" / "jul" / "aug" / 767 "sep" / "oct" / "nov" / "dec" ) *OCTET 768 year = 2*4DIGIT [ non-digit *OCTET ] 769 time = hms-time [ non-digit *OCTET ] 770 hms-time = time-field ":" time-field ":" time-field 771 time-field = 1*2DIGIT 773 2. Process each date-token sequentially in the order the date-tokens 774 appear in the cookie-date: 776 1. If the found-time flag is not set and the token matches the 777 time production, set the found-time flag and set the hour- 778 value, minute-value, and second-value to the numbers denoted 779 by the digits in the date-token, respectively. Skip the 780 remaining sub-steps and continue to the next date-token. 782 2. If the found-day-of-month flag is not set and the date-token 783 matches the day-of-month production, set the found-day-of- 784 month flag and set the day-of-month-value to the number 785 denoted by the date-token. Skip the remaining sub-steps and 786 continue to the next date-token. 788 3. If the found-month flag is not set and the date-token matches 789 the month production, set the found-month flag and set the 790 month-value to the month denoted by the date-token. Skip the 791 remaining sub-steps and continue to the next date-token. 793 4. If the found-year flag is not set and the date-token matches 794 the year production, set the found-year flag and set the 795 year-value to the number denoted by the date-token. Skip the 796 remaining sub-steps and continue to the next date-token. 798 3. If the year-value is greater than or equal to 70 and less than or 799 equal to 99, increment the year-value by 1900. 801 4. If the year-value is greater than or equal to 0 and less than or 802 equal to 69, increment the year-value by 2000. 804 1. NOTE: Some existing user agents interpret two-digit years 805 differently. 807 5. Abort these steps and fail to parse the cookie-date if: 809 * at least one of the found-day-of-month, found-month, found- 810 year, or found-time flags is not set, 812 * the day-of-month-value is less than 1 or greater than 31, 814 * the year-value is less than 1601, 816 * the hour-value is greater than 23, 818 * the minute-value is greater than 59, or 820 * the second-value is greater than 59. 822 (Note that leap seconds cannot be represented in this syntax.) 824 6. Let the parsed-cookie-date be the date whose day-of-month, month, 825 year, hour, minute, and second (in UTC) are the day-of-month- 826 value, the month-value, the year-value, the hour-value, the 827 minute-value, and the second-value, respectively. If no such 828 date exists, abort these steps and fail to parse the cookie-date. 830 7. Return the parsed-cookie-date as the result of this algorithm. 832 5.1.2. Canonicalized Host Names 834 A canonicalized host name is the string generated by the following 835 algorithm: 837 1. Convert the host name to a sequence of individual domain name 838 labels. 840 2. Convert each label that is not a Non-Reserved LDH (NR-LDH) label, 841 to an A-label (see Section 2.3.2.1 of [RFC5890] for the former 842 and latter), or to a "punycode label" (a label resulting from the 843 "ToASCII" conversion in Section 4 of [RFC3490]), as appropriate 844 (see Section 6.3 of this specification). 846 3. Concatenate the resulting labels, separated by a %x2E (".") 847 character. 849 5.1.3. Domain Matching 851 A string domain-matches a given domain string if at least one of the 852 following conditions hold: 854 o The domain string and the string are identical. (Note that both 855 the domain string and the string will have been canonicalized to 856 lower case at this point.) 858 o All of the following conditions hold: 860 * The domain string is a suffix of the string. 862 * The last character of the string that is not included in the 863 domain string is a %x2E (".") character. 865 * The string is a host name (i.e., not an IP address). 867 5.1.4. Paths and Path-Match 869 The user agent MUST use an algorithm equivalent to the following 870 algorithm to compute the default-path of a cookie: 872 1. Let uri-path be the path portion of the request-uri if such a 873 portion exists (and empty otherwise). For example, if the 874 request-uri contains just a path (and optional query string), 875 then the uri-path is that path (without the %x3F ("?") character 876 or query string), and if the request-uri contains a full 877 absoluteURI, the uri-path is the path component of that URI. 879 2. If the uri-path is empty or if the first character of the uri- 880 path is not a %x2F ("/") character, output %x2F ("/") and skip 881 the remaining steps. 883 3. If the uri-path contains no more than one %x2F ("/") character, 884 output %x2F ("/") and skip the remaining step. 886 4. Output the characters of the uri-path from the first character up 887 to, but not including, the right-most %x2F ("/"). 889 A request-path path-matches a given cookie-path if at least one of 890 the following conditions holds: 892 o The cookie-path and the request-path are identical. 894 Note that this differs from the rules in [RFC3986] for equivalence 895 of the path component, and hence two equivalent paths can have 896 different cookies. 898 o The cookie-path is a prefix of the request-path, and the last 899 character of the cookie-path is %x2F ("/"). 901 o The cookie-path is a prefix of the request-path, and the first 902 character of the request-path that is not included in the cookie- 903 path is a %x2F ("/") character. 905 5.2. "Same-site" and "cross-site" Requests 907 A request is "same-site" if its target's URI's origin's registrable 908 domain is an exact match for the request's client's "site for 909 cookies", or if the request has no client. The request is otherwise 910 "cross-site". 912 For a given request ("request"), the following algorithm returns 913 "same-site" or "cross-site": 915 1. If "request"'s client is "null", return "same-site". 917 Note that this is the case for navigation triggered by the user 918 directly (e.g. by typing directly into a user agent's address 919 bar). 921 2. Let "site" be "request"'s client's "site for cookies" (as defined 922 in the following sections). 924 3. Let "target" be the registrable domain of "request"'s current 925 url. 927 4. If "site" is an exact match for "target", return "same-site". 929 5. Return "cross-site". 931 The request's client's "site for cookies" is calculated depending 932 upon its client's type, as described in the following subsections: 934 5.2.1. Document-based requests 936 The URI displayed in a user agent's address bar is the only security 937 context directly exposed to users, and therefore the only signal 938 users can reasonably rely upon to determine whether or not they trust 939 a particular website. The registrable domain of that URI's origin 940 represents the context in which a user most likely believes 941 themselves to be interacting. We'll label this domain the "top-level 942 site". 944 For a document displayed in a top-level browsing context, we can stop 945 here: the document's "site for cookies" is the top-level site. 947 For documents which are displayed in nested browsing contexts, we 948 need to audit the origins of each of a document's ancestor browsing 949 contexts' active documents in order to account for the "multiple- 950 nested scenarios" described in Section 4 of [RFC7034]. A document's 951 "site for cookies" is the top-level site if and only if the document 952 and each of its ancestor documents' origins have the same registrable 953 domain as the top-level site. Otherwise its "site for cookies" is 954 the empty string. 956 Given a Document ("document"), the following algorithm returns its 957 "site for cookies" (either a registrable domain, or the empty 958 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 registrable domain is not an exact match 977 for "top-origin"'s host's registrable domain, return the 978 empty string. 980 5. Return "top-origin"'s host's registrable 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 registrable domain, or the empty 1010 string): 1012 1. Let "site" be "worker"'s origin's host's registrable 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 registrable domain of the Service Worker's URI. 1040 Given a ServiceWorkerGlobalScope ("worker"), the following algorithm 1041 returns its "site for cookies" (either a registrable domain, or the 1042 empty string): 1044 1. Return "worker"'s origin's host's registrable 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 5.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: This step prevents "attacker.example" from disrupting the 1366 integrity of "site.example" by setting a cookie with a Domain 1367 attribute of "example". 1369 6. If the domain-attribute is non-empty: 1371 1. If the canonicalized request-host does not domain-match the 1372 domain-attribute: 1374 1. Ignore the cookie entirely and abort these steps. 1376 Otherwise: 1378 1. Set the cookie's host-only-flag to false. 1380 2. Set the cookie's domain to the domain-attribute. 1382 Otherwise: 1384 1. Set the cookie's host-only-flag to true. 1386 2. Set the cookie's domain to the canonicalized request-host. 1388 7. If the cookie-attribute-list contains an attribute with an 1389 attribute-name of "Path", set the cookie's path to attribute- 1390 value of the last attribute in the cookie-attribute-list with an 1391 attribute-name of "Path". Otherwise, set the cookie's path to 1392 the default-path of the request-uri. 1394 8. If the cookie-attribute-list contains an attribute with an 1395 attribute-name of "Secure", set the cookie's secure-only-flag to 1396 true. Otherwise, set the cookie's secure-only-flag to false. 1398 9. If the scheme component of the request-uri does not denote a 1399 "secure" protocol (as defined by the user agent), and the 1400 cookie's secure-only-flag is true, then abort these steps and 1401 ignore the cookie entirely. 1403 10. If the cookie-attribute-list contains an attribute with an 1404 attribute-name of "HttpOnly", set the cookie's http-only-flag to 1405 true. Otherwise, set the cookie's http-only-flag to false. 1407 11. If the cookie was received from a "non-HTTP" API and the 1408 cookie's http-only-flag is true, abort these steps and ignore 1409 the cookie entirely. 1411 12. If the cookie's secure-only-flag is not set, and the scheme 1412 component of request-uri does not denote a "secure" protocol, 1413 then abort these steps and ignore the cookie entirely if the 1414 cookie store contains one or more cookies that meet all of the 1415 following criteria: 1417 1. Their name matches the name of the newly-created cookie. 1419 2. Their secure-only-flag is true. 1421 3. Their domain domain-matches the domain of the newly-created 1422 cookie, or vice-versa. 1424 4. The path of the newly-created cookie path-matches the path 1425 of the existing cookie. 1427 Note: The path comparison is not symmetric, ensuring only that a 1428 newly-created, non-secure cookie does not overlay an existing 1429 secure cookie, providing some mitigation against cookie-fixing 1430 attacks. That is, given an existing secure cookie named 'a' 1431 with a path of '/login', a non-secure cookie named 'a' could be 1432 set for a path of '/' or '/foo', but not for a path of '/login' 1433 or '/login/en'. 1435 13. If the cookie-attribute-list contains an attribute with an 1436 attribute-name of "SameSite", set the cookie's same-site-flag to 1437 the attribute-value of the last attribute in the cookie- 1438 attribute-list with an attribute-name of "SameSite" (i.e. either 1439 "Strict", "Lax", or "None"). Otherwise, set the cookie's same- 1440 site-flag to "None". 1442 14. If the cookie's "same-site-flag" is not "None": 1444 1. If the cookie was received from a "non-HTTP" API, and the 1445 API was called from a context whose "site for cookies" is 1446 not an exact match for request-uri's host's registrable 1447 domain, then abort these steps and ignore the newly created 1448 cookie entirely. 1450 2. If the cookie was received from a "same-site" request (as 1451 defined in Section 5.2), skip the remaining substeps and 1452 continue processing the cookie. 1454 3. If the cookie was received from a request which is 1455 navigating a top-level browsing context [HTML] (e.g. if the 1456 request's "reserved client" is either "null" or an 1457 environment whose "target browsing context" is a top-level 1458 browing context), skip the remaining substeps and continue 1459 processing the cookie. 1461 Note: Top-level navigations can create a cookie with any 1462 "SameSite" value, even if the new cookie wouldn't have been 1463 sent along with the request had it already existed prior to 1464 the navigation. 1466 4. Abort these steps and ignore the newly created cookie 1467 entirely. 1469 15. If the cookie-name begins with a case-sensitive match for the 1470 string "__Secure-", abort these steps and ignore the cookie 1471 entirely unless the cookie's secure-only-flag is true. 1473 16. If the cookie-name begins with a case-sensitive match for the 1474 string "__Host-", abort these steps and ignore the cookie 1475 entirely unless the cookie meets all the following criteria: 1477 1. The cookie's secure-only-flag is true. 1479 2. The cookie's host-only-flag is true. 1481 3. The cookie-attribute-list contains an attribute with an 1482 attribute-name of "Path", and the cookie's path is "/". 1484 17. If the cookie store contains a cookie with the same name, 1485 domain, host-only-flag, and path as the newly-created cookie: 1487 1. Let old-cookie be the existing cookie with the same name, 1488 domain, host-only-flag, and path as the newly-created 1489 cookie. (Notice that this algorithm maintains the invariant 1490 that there is at most one such cookie.) 1492 2. If the newly-created cookie was received from a "non-HTTP" 1493 API and the old-cookie's http-only-flag is true, abort these 1494 steps and ignore the newly created cookie entirely. 1496 3. Update the creation-time of the newly-created cookie to 1497 match the creation-time of the old-cookie. 1499 4. Remove the old-cookie from the cookie store. 1501 18. Insert the newly-created cookie into the cookie store. 1503 A cookie is "expired" if the cookie has an expiry date in the past. 1505 The user agent MUST evict all expired cookies from the cookie store 1506 if, at any time, an expired cookie exists in the cookie store. 1508 At any time, the user agent MAY "remove excess cookies" from the 1509 cookie store if the number of cookies sharing a domain field exceeds 1510 some implementation-defined upper bound (such as 50 cookies). 1512 At any time, the user agent MAY "remove excess cookies" from the 1513 cookie store if the cookie store exceeds some predetermined upper 1514 bound (such as 3000 cookies). 1516 When the user agent removes excess cookies from the cookie store, the 1517 user agent MUST evict cookies in the following priority order: 1519 1. Expired cookies. 1521 2. Cookies whose secure-only-flag is not set, and which share a 1522 domain field with more than a predetermined number of other 1523 cookies. 1525 3. Cookies that share a domain field with more than a predetermined 1526 number of other cookies. 1528 4. All cookies. 1530 If two cookies have the same removal priority, the user agent MUST 1531 evict the cookie with the earliest last-access-time first. 1533 When "the current session is over" (as defined by the user agent), 1534 the user agent MUST remove from the cookie store all cookies with the 1535 persistent-flag set to false. 1537 5.5. The Cookie Header 1539 The user agent includes stored cookies in the Cookie HTTP request 1540 header. 1542 When the user agent generates an HTTP request, the user agent MUST 1543 NOT attach more than one Cookie header field. 1545 A user agent MAY omit the Cookie header in its entirety. For 1546 example, the user agent might wish to block sending cookies during 1547 "third-party" requests from setting cookies (see Section 7.1). 1549 If the user agent does attach a Cookie header field to an HTTP 1550 request, the user agent MUST send the cookie-string (defined below) 1551 as the value of the header field. 1553 The user agent MUST use an algorithm equivalent to the following 1554 algorithm to compute the cookie-string from a cookie store and a 1555 request-uri: 1557 1. Let cookie-list be the set of cookies from the cookie store that 1558 meets all of the following requirements: 1560 * Either: 1562 + The cookie's host-only-flag is true and the canonicalized 1563 request-host is identical to the cookie's domain. 1565 Or: 1567 + The cookie's host-only-flag is false and the canonicalized 1568 request-host domain-matches the cookie's domain. 1570 * The request-uri's path path-matches the cookie's path. 1572 * If the cookie's secure-only-flag is true, then the request- 1573 uri's scheme must denote a "secure" protocol (as defined by 1574 the user agent). 1576 NOTE: The notion of a "secure" protocol is not defined by this 1577 document. Typically, user agents consider a protocol secure 1578 if the protocol makes use of transport-layer security, such as 1579 SSL or TLS. For example, most user agents consider "https" to 1580 be a scheme that denotes a secure protocol. 1582 * If the cookie's http-only-flag is true, then exclude the 1583 cookie if the cookie-string is being generated for a "non- 1584 HTTP" API (as defined by the user agent). 1586 * If the cookie's same-site-flag is not "None", and the HTTP 1587 request is cross-site (as defined in Section 5.2) then exclude 1588 the cookie unless all of the following statements hold: 1590 1. The same-site-flag is "Lax" 1592 2. The HTTP request's method is "safe". 1594 3. The HTTP request's target browsing context is a top-level 1595 browsing context. 1597 2. The user agent SHOULD sort the cookie-list in the following 1598 order: 1600 * Cookies with longer paths are listed before cookies with 1601 shorter paths. 1603 * Among cookies that have equal-length path fields, cookies with 1604 earlier creation-times are listed before cookies with later 1605 creation-times. 1607 NOTE: Not all user agents sort the cookie-list in this order, but 1608 this order reflects common practice when this document was 1609 written, and, historically, there have been servers that 1610 (erroneously) depended on this order. 1612 3. Update the last-access-time of each cookie in the cookie-list to 1613 the current date and time. 1615 4. Serialize the cookie-list into a cookie-string by processing each 1616 cookie in the cookie-list in order: 1618 1. Output the cookie's name, the %x3D ("=") character, and the 1619 cookie's value. 1621 2. If there is an unprocessed cookie in the cookie-list, output 1622 the characters %x3B and %x20 ("; "). 1624 NOTE: Despite its name, the cookie-string is actually a sequence of 1625 octets, not a sequence of characters. To convert the cookie-string 1626 (or components thereof) into a sequence of characters (e.g., for 1627 presentation to the user), the user agent might wish to try using the 1628 UTF-8 character encoding [RFC3629] to decode the octet sequence. 1629 This decoding might fail, however, because not every sequence of 1630 octets is valid UTF-8. 1632 6. Implementation Considerations 1634 6.1. Limits 1636 Practical user agent implementations have limits on the number and 1637 size of cookies that they can store. General-use user agents SHOULD 1638 provide each of the following minimum capabilities: 1640 o At least 4096 bytes per cookie (as measured by the sum of the 1641 length of the cookie's name, value, and attributes). 1643 o At least 50 cookies per domain. 1645 o At least 3000 cookies total. 1647 Servers SHOULD use as few and as small cookies as possible to avoid 1648 reaching these implementation limits and to minimize network 1649 bandwidth due to the Cookie header being included in every request. 1651 Servers SHOULD gracefully degrade if the user agent fails to return 1652 one or more cookies in the Cookie header because the user agent might 1653 evict any cookie at any time on orders from the user. 1655 6.2. Application Programming Interfaces 1657 One reason the Cookie and Set-Cookie headers use such esoteric syntax 1658 is that many platforms (both in servers and user agents) provide a 1659 string-based application programming interface (API) to cookies, 1660 requiring application-layer programmers to generate and parse the 1661 syntax used by the Cookie and Set-Cookie headers, which many 1662 programmers have done incorrectly, resulting in interoperability 1663 problems. 1665 Instead of providing string-based APIs to cookies, platforms would be 1666 well-served by providing more semantic APIs. It is beyond the scope 1667 of this document to recommend specific API designs, but there are 1668 clear benefits to accepting an abstract "Date" object instead of a 1669 serialized date string. 1671 6.3. IDNA Dependency and Migration 1673 IDNA2008 [RFC5890] supersedes IDNA2003 [RFC3490]. However, there are 1674 differences between the two specifications, and thus there can be 1675 differences in processing (e.g., converting) domain name labels that 1676 have been registered under one from those registered under the other. 1677 There will be a transition period of some time during which 1678 IDNA2003-based domain name labels will exist in the wild. User 1679 agents SHOULD implement IDNA2008 [RFC5890] and MAY implement [UTS46] 1680 or [RFC5895] in order to facilitate their IDNA transition. If a user 1681 agent does not implement IDNA2008, the user agent MUST implement 1682 IDNA2003 [RFC3490]. 1684 7. Privacy Considerations 1686 Cookies are often criticized for letting servers track users. For 1687 example, a number of "web analytics" companies use cookies to 1688 recognize when a user returns to a web site or visits another web 1689 site. Although cookies are not the only mechanism servers can use to 1690 track users across HTTP requests, cookies facilitate tracking because 1691 they are persistent across user agent sessions and can be shared 1692 between hosts. 1694 7.1. Third-Party Cookies 1696 Particularly worrisome are so-called "third-party" cookies. In 1697 rendering an HTML document, a user agent often requests resources 1698 from other servers (such as advertising networks). These third-party 1699 servers can use cookies to track the user even if the user never 1700 visits the server directly. For example, if a user visits a site 1701 that contains content from a third party and then later visits 1702 another site that contains content from the same third party, the 1703 third party can track the user between the two sites. 1705 Given this risk to user privacy, some user agents restrict how third- 1706 party cookies behave, and those restrictions vary widly. For 1707 instance, user agents might block third-party cookies entirely by 1708 refusing to send Cookie headers or process Set-Cookie headers during 1709 third-party requests. They might take a less draconian approach by 1710 partitioning cookies based on the first-party context, sending one 1711 set of cookies to a given third party in one first-party context, and 1712 another to the same third party in another. 1714 This document grants user agents wide latitude to experiment with 1715 third-party cookie policies that balance the privacy and 1716 compatibility needs of their users. However, this document does not 1717 endorse any particular third-party cookie policy. 1719 Third-party cookie blocking policies are often ineffective at 1720 achieving their privacy goals if servers attempt to work around their 1721 restrictions to track users. In particular, two collaborating 1722 servers can often track users without using cookies at all by 1723 injecting identifying information into dynamic URLs. 1725 7.2. User Controls 1727 User agents SHOULD provide users with a mechanism for managing the 1728 cookies stored in the cookie store. For example, a user agent might 1729 let users delete all cookies received during a specified time period 1730 or all the cookies related to a particular domain. In addition, many 1731 user agents include a user interface element that lets users examine 1732 the cookies stored in their cookie store. 1734 User agents SHOULD provide users with a mechanism for disabling 1735 cookies. When cookies are disabled, the user agent MUST NOT include 1736 a Cookie header in outbound HTTP requests and the user agent MUST NOT 1737 process Set-Cookie headers in inbound HTTP responses. 1739 Some user agents provide users the option of preventing persistent 1740 storage of cookies across sessions. When configured thusly, user 1741 agents MUST treat all received cookies as if the persistent-flag were 1742 set to false. Some popular user agents expose this functionality via 1743 "private browsing" mode [Aggarwal2010]. 1745 Some user agents provide users with the ability to approve individual 1746 writes to the cookie store. In many common usage scenarios, these 1747 controls generate a large number of prompts. However, some privacy- 1748 conscious users find these controls useful nonetheless. 1750 7.3. Expiration Dates 1752 Although servers can set the expiration date for cookies to the 1753 distant future, most user agents do not actually retain cookies for 1754 multiple decades. Rather than choosing gratuitously long expiration 1755 periods, servers SHOULD promote user privacy by selecting reasonable 1756 cookie expiration periods based on the purpose of the cookie. For 1757 example, a typical session identifier might reasonably be set to 1758 expire in two weeks. 1760 8. Security Considerations 1762 8.1. Overview 1764 Cookies have a number of security pitfalls. This section overviews a 1765 few of the more salient issues. 1767 In particular, cookies encourage developers to rely on ambient 1768 authority for authentication, often becoming vulnerable to attacks 1769 such as cross-site request forgery [CSRF]. Also, when storing 1770 session identifiers in cookies, developers often create session 1771 fixation vulnerabilities. 1773 Transport-layer encryption, such as that employed in HTTPS, is 1774 insufficient to prevent a network attacker from obtaining or altering 1775 a victim's cookies because the cookie protocol itself has various 1776 vulnerabilities (see "Weak Confidentiality" and "Weak Integrity", 1777 below). In addition, by default, cookies do not provide 1778 confidentiality or integrity from network attackers, even when used 1779 in conjunction with HTTPS. 1781 8.2. Ambient Authority 1783 A server that uses cookies to authenticate users can suffer security 1784 vulnerabilities because some user agents let remote parties issue 1785 HTTP requests from the user agent (e.g., via HTTP redirects or HTML 1786 forms). When issuing those requests, user agents attach cookies even 1787 if the remote party does not know the contents of the cookies, 1788 potentially letting the remote party exercise authority at an unwary 1789 server. 1791 Although this security concern goes by a number of names (e.g., 1792 cross-site request forgery, confused deputy), the issue stems from 1793 cookies being a form of ambient authority. Cookies encourage server 1794 operators to separate designation (in the form of URLs) from 1795 authorization (in the form of cookies). Consequently, the user agent 1796 might supply the authorization for a resource designated by the 1797 attacker, possibly causing the server or its clients to undertake 1798 actions designated by the attacker as though they were authorized by 1799 the user. 1801 Instead of using cookies for authorization, server operators might 1802 wish to consider entangling designation and authorization by treating 1803 URLs as capabilities. Instead of storing secrets in cookies, this 1804 approach stores secrets in URLs, requiring the remote entity to 1805 supply the secret itself. Although this approach is not a panacea, 1806 judicious application of these principles can lead to more robust 1807 security. 1809 8.3. Clear Text 1811 Unless sent over a secure channel (such as TLS), the information in 1812 the Cookie and Set-Cookie headers is transmitted in the clear. 1814 1. All sensitive information conveyed in these headers is exposed to 1815 an eavesdropper. 1817 2. A malicious intermediary could alter the headers as they travel 1818 in either direction, with unpredictable results. 1820 3. A malicious client could alter the Cookie header before 1821 transmission, with unpredictable results. 1823 Servers SHOULD encrypt and sign the contents of cookies (using 1824 whatever format the server desires) when transmitting them to the 1825 user agent (even when sending the cookies over a secure channel). 1826 However, encrypting and signing cookie contents does not prevent an 1827 attacker from transplanting a cookie from one user agent to another 1828 or from replaying the cookie at a later time. 1830 In addition to encrypting and signing the contents of every cookie, 1831 servers that require a higher level of security SHOULD use the Cookie 1832 and Set-Cookie headers only over a secure channel. When using 1833 cookies over a secure channel, servers SHOULD set the Secure 1834 attribute (see Section 4.1.2.5) for every cookie. If a server does 1835 not set the Secure attribute, the protection provided by the secure 1836 channel will be largely moot. 1838 For example, consider a webmail server that stores a session 1839 identifier in a cookie and is typically accessed over HTTPS. If the 1840 server does not set the Secure attribute on its cookies, an active 1841 network attacker can intercept any outbound HTTP request from the 1842 user agent and redirect that request to the webmail server over HTTP. 1843 Even if the webmail server is not listening for HTTP connections, the 1844 user agent will still include cookies in the request. The active 1845 network attacker can intercept these cookies, replay them against the 1846 server, and learn the contents of the user's email. If, instead, the 1847 server had set the Secure attribute on its cookies, the user agent 1848 would not have included the cookies in the clear-text request. 1850 8.4. Session Identifiers 1852 Instead of storing session information directly in a cookie (where it 1853 might be exposed to or replayed by an attacker), servers commonly 1854 store a nonce (or "session identifier") in a cookie. When the server 1855 receives an HTTP request with a nonce, the server can look up state 1856 information associated with the cookie using the nonce as a key. 1858 Using session identifier cookies limits the damage an attacker can 1859 cause if the attacker learns the contents of a cookie because the 1860 nonce is useful only for interacting with the server (unlike non- 1861 nonce cookie content, which might itself be sensitive). Furthermore, 1862 using a single nonce prevents an attacker from "splicing" together 1863 cookie content from two interactions with the server, which could 1864 cause the server to behave unexpectedly. 1866 Using session identifiers is not without risk. For example, the 1867 server SHOULD take care to avoid "session fixation" vulnerabilities. 1868 A session fixation attack proceeds in three steps. First, the 1869 attacker transplants a session identifier from his or her user agent 1870 to the victim's user agent. Second, the victim uses that session 1871 identifier to interact with the server, possibly imbuing the session 1872 identifier with the user's credentials or confidential information. 1873 Third, the attacker uses the session identifier to interact with 1874 server directly, possibly obtaining the user's authority or 1875 confidential information. 1877 8.5. Weak Confidentiality 1879 Cookies do not provide isolation by port. If a cookie is readable by 1880 a service running on one port, the cookie is also readable by a 1881 service running on another port of the same server. If a cookie is 1882 writable by a service on one port, the cookie is also writable by a 1883 service running on another port of the same server. For this reason, 1884 servers SHOULD NOT both run mutually distrusting services on 1885 different ports of the same host and use cookies to store security- 1886 sensitive information. 1888 Cookies do not provide isolation by scheme. Although most commonly 1889 used with the http and https schemes, the cookies for a given host 1890 might also be available to other schemes, such as ftp and gopher. 1891 Although this lack of isolation by scheme is most apparent in non- 1892 HTTP APIs that permit access to cookies (e.g., HTML's document.cookie 1893 API), the lack of isolation by scheme is actually present in 1894 requirements for processing cookies themselves (e.g., consider 1895 retrieving a URI with the gopher scheme via HTTP). 1897 Cookies do not always provide isolation by path. Although the 1898 network-level protocol does not send cookies stored for one path to 1899 another, some user agents expose cookies via non-HTTP APIs, such as 1900 HTML's document.cookie API. Because some of these user agents (e.g., 1901 web browsers) do not isolate resources received from different paths, 1902 a resource retrieved from one path might be able to access cookies 1903 stored for another path. 1905 8.6. Weak Integrity 1907 Cookies do not provide integrity guarantees for sibling domains (and 1908 their subdomains). For example, consider foo.site.example and 1909 bar.site.example. The foo.site.example server can set a cookie with 1910 a Domain attribute of "site.example" (possibly overwriting an 1911 existing "site.example" cookie set by bar.site.example), and the user 1912 agent will include that cookie in HTTP requests to bar.site.example. 1913 In the worst case, bar.site.example will be unable to distinguish 1914 this cookie from a cookie it set itself. The foo.site.example server 1915 might be able to leverage this ability to mount an attack against 1916 bar.site.example. 1918 Even though the Set-Cookie header supports the Path attribute, the 1919 Path attribute does not provide any integrity protection because the 1920 user agent will accept an arbitrary Path attribute in a Set-Cookie 1921 header. For example, an HTTP response to a request for 1922 http://site.example/foo/bar can set a cookie with a Path attribute of 1923 "/qux". Consequently, servers SHOULD NOT both run mutually 1924 distrusting services on different paths of the same host and use 1925 cookies to store security-sensitive information. 1927 An active network attacker can also inject cookies into the Cookie 1928 header sent to https://site.example/ by impersonating a response from 1929 http://site.example/ and injecting a Set-Cookie header. The HTTPS 1930 server at site.example will be unable to distinguish these cookies 1931 from cookies that it set itself in an HTTPS response. An active 1932 network attacker might be able to leverage this ability to mount an 1933 attack against site.example even if site.example uses HTTPS 1934 exclusively. 1936 Servers can partially mitigate these attacks by encrypting and 1937 signing the contents of their cookies. However, using cryptography 1938 does not mitigate the issue completely because an attacker can replay 1939 a cookie he or she received from the authentic site.example server in 1940 the user's session, with unpredictable results. 1942 Finally, an attacker might be able to force the user agent to delete 1943 cookies by storing a large number of cookies. Once the user agent 1944 reaches its storage limit, the user agent will be forced to evict 1945 some cookies. Servers SHOULD NOT rely upon user agents retaining 1946 cookies. 1948 8.7. Reliance on DNS 1950 Cookies rely upon the Domain Name System (DNS) for security. If the 1951 DNS is partially or fully compromised, the cookie protocol might fail 1952 to provide the security properties required by applications. 1954 8.8. SameSite Cookies 1956 8.8.1. Defense in depth 1958 "SameSite" cookies offer a robust defense against CSRF attack when 1959 deployed in strict mode, and when supported by the client. It is, 1960 however, prudent to ensure that this designation is not the extent of 1961 a site's defense against CSRF, as same-site navigations and 1962 submissions can certainly be executed in conjunction with other 1963 attack vectors such as cross-site scripting. 1965 Developers are strongly encouraged to deploy the usual server-side 1966 defenses (CSRF tokens, ensuring that "safe" HTTP methods are 1967 idempotent, etc) to mitigate the risk more fully. 1969 Additionally, client-side techniques such as those described in 1970 [app-isolation] may also prove effective against CSRF, and are 1971 certainly worth exploring in combination with "SameSite" cookies. 1973 8.8.2. Top-level Navigations 1975 Setting the "SameSite" attribute in "strict" mode provides robust 1976 defense in depth against CSRF attacks, but has the potential to 1977 confuse users unless sites' developers carefully ensure that their 1978 cookie-based session management systems deal reasonably well with 1979 top-level navigations. 1981 Consider the scenario in which a user reads their email at MegaCorp 1982 Inc's webmail provider "https://site.example/". They might expect 1983 that clicking on an emailed link to "https://projects.example/secret/ 1984 project" would show them the secret project that they're authorized 1985 to see, but if "projects.example" has marked their session cookies as 1986 "SameSite", then this cross-site navigation won't send them along 1987 with the request. "projects.example" will render a 404 error to avoid 1988 leaking secret information, and the user will be quite confused. 1990 Developers can avoid this confusion by adopting a session management 1991 system that relies on not one, but two cookies: one conceptually 1992 granting "read" access, another granting "write" access. The latter 1993 could be marked as "SameSite", and its absence would prompt a 1994 reauthentication step before executing any non-idempotent action. 1995 The former could drop the "SameSite" attribute entirely, or choose 1996 the "Lax" version of enforcement, in order to allow users access to 1997 data via top-level navigation. 1999 8.8.3. Mashups and Widgets 2001 The "SameSite" attribute is inappropriate for some important use- 2002 cases. In particular, note that content intended for embedding in a 2003 cross-site contexts (social networking widgets or commenting 2004 services, for instance) will not have access to same-site cookies. 2005 Cookies may be required for requests triggered in these cross-site 2006 contexts in order to provide seamless functionality that relies on a 2007 user's state. 2009 Likewise, some forms of Single-Sign-On might require cookie-based 2010 authentication in a cross-site context; these mechanisms will not 2011 function as intended with same-site cookies. 2013 8.8.4. Server-controlled 2015 SameSite cookies in and of themselves don't do anything to address 2016 the general privacy concerns outlined in Section 7.1 of [RFC6265]. 2017 The "SameSite" attribute is set by the server, and serves to mitigate 2018 the risk of certain kinds of attacks that the server is worried 2019 about. The user is not involved in this decision. Moreover, a 2020 number of side-channels exist which could allow a server to link 2021 distinct requests even in the absence of cookies. Connection and/or 2022 socket pooling, Token Binding, and Channel ID all offer explicit 2023 methods of identification that servers could take advantage of. 2025 9. IANA Considerations 2027 The permanent message header field registry (see [RFC3864]) needs to 2028 be updated with the following registrations. 2030 9.1. Cookie 2032 Header field name: Cookie 2034 Applicable protocol: http 2036 Status: standard 2038 Author/Change controller: IETF 2040 Specification document: this specification (Section 5.5) 2042 9.2. Set-Cookie 2044 Header field name: Set-Cookie 2046 Applicable protocol: http 2048 Status: standard 2050 Author/Change controller: IETF 2052 Specification document: this specification (Section 5.3) 2054 10. References 2056 10.1. Normative References 2058 [FETCH] van Kesteren, A., "Fetch", n.d., 2059 . 2061 [HTML] Hickson, I., Pieters, S., van Kesteren, A., Jaegenstedt, 2062 P., and D. Denicola, "HTML", n.d., 2063 . 2065 [PSL] "Public Suffix List", n.d., 2066 . 2068 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 2069 STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987, 2070 . 2072 [RFC1123] Braden, R., Ed., "Requirements for Internet Hosts - 2073 Application and Support", STD 3, RFC 1123, 2074 DOI 10.17487/RFC1123, October 1989, 2075 . 2077 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2078 Requirement Levels", BCP 14, RFC 2119, 2079 DOI 10.17487/RFC2119, March 1997, 2080 . 2082 [RFC3490] Costello, A., "Internationalizing Domain Names in 2083 Applications (IDNA)", RFC 3490, March 2003. 2085 See Section 6.3 for an explanation why the normative 2086 reference to an obsoleted specification is needed. 2088 [RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet 2089 Application Protocol Collation Registry", RFC 4790, 2090 DOI 10.17487/RFC4790, March 2007, 2091 . 2093 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 2094 Specifications: ABNF", STD 68, RFC 5234, 2095 DOI 10.17487/RFC5234, January 2008, 2096 . 2098 [RFC5890] Klensin, J., "Internationalized Domain Names for 2099 Applications (IDNA): Definitions and Document Framework", 2100 RFC 5890, DOI 10.17487/RFC5890, August 2010, 2101 . 2103 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 2104 DOI 10.17487/RFC6454, December 2011, 2105 . 2107 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2108 Protocol (HTTP/1.1): Message Syntax and Routing", 2109 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2110 . 2112 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2113 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 2114 DOI 10.17487/RFC7231, June 2014, 2115 . 2117 [SERVICE-WORKERS] 2118 Russell, A., Song, J., and J. Archibald, "Service 2119 Workers", n.d., . 2121 [USASCII] American National Standards Institute, "Coded Character 2122 Set -- 7-bit American Standard Code for Information 2123 Interchange", ANSI X3.4, 1986. 2125 10.2. Informative References 2127 [Aggarwal2010] 2128 Aggarwal, G., Burzstein, E., Jackson, C., and D. Boneh, 2129 "An Analysis of Private Browsing Modes in Modern 2130 Browsers", 2010, 2131 . 2134 [app-isolation] 2135 Chen, E., Bau, J., Reis, C., Barth, A., and C. Jackson, 2136 "App Isolation - Get the Security of Multiple Browsers 2137 with Just One", 2011, 2138 . 2141 [CSRF] Barth, A., Jackson, C., and J. Mitchell, "Robust Defenses 2142 for Cross-Site Request Forgery", 2143 DOI 10.1145/1455770.1455782, ISBN 978-1-59593-810-7, 2144 ACM CCS '08: Proceedings of the 15th ACM conference on 2145 Computer and communications security (pages 75-88), 2146 October 2008, 2147 . 2149 [I-D.ietf-httpbis-cookie-alone] 2150 West, M., "Deprecate modification of 'secure' cookies from 2151 non-secure origins", draft-ietf-httpbis-cookie-alone-01 2152 (work in progress), September 2016. 2154 [I-D.ietf-httpbis-cookie-prefixes] 2155 West, M., "Cookie Prefixes", draft-ietf-httpbis-cookie- 2156 prefixes-00 (work in progress), February 2016. 2158 [I-D.ietf-httpbis-cookie-same-site] 2159 West, M. and M. Goodwin, "Same-Site Cookies", draft-ietf- 2160 httpbis-cookie-same-site-00 (work in progress), June 2016. 2162 [prerendering] 2163 Bentzel, C., "Chrome Prerendering", n.d., 2164 . 2167 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 2168 DOI 10.17487/RFC2818, May 2000, 2169 . 2171 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2172 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2173 2003, . 2175 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 2176 Procedures for Message Header Fields", BCP 90, RFC 3864, 2177 DOI 10.17487/RFC3864, September 2004, 2178 . 2180 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2181 Resource Identifier (URI): Generic Syntax", STD 66, 2182 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2183 . 2185 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2186 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 2187 . 2189 [RFC5895] Resnick, P. and P. Hoffman, "Mapping Characters for 2190 Internationalized Domain Names in Applications (IDNA) 2191 2008", RFC 5895, DOI 10.17487/RFC5895, September 2010, 2192 . 2194 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 2195 DOI 10.17487/RFC6265, April 2011, 2196 . 2198 [RFC7034] Ross, D. and T. Gondrom, "HTTP Header Field X-Frame- 2199 Options", RFC 7034, DOI 10.17487/RFC7034, October 2013, 2200 . 2202 [UTS46] Davis, M. and M. Suignard, "Unicode IDNA Compatibility 2203 Processing", UNICODE Unicode Technical Standards # 46, 2204 June 2016, . 2206 10.3. URIs 2208 [1] https://lists.w3.org/Archives/Public/ietf-http-wg/ 2210 [2] http://httpwg.github.io/ 2212 [3] https://github.com/httpwg/http-extensions/labels/6265bis 2214 [4] https://github.com/httpwg/http-extensions/issues/243 2216 [5] https://github.com/httpwg/http-extensions/issues/246 2218 [6] https://www.rfc-editor.org/errata_search.php?rfc=6265 2220 [7] https://github.com/httpwg/http-extensions/issues/247 2222 [8] https://github.com/httpwg/http-extensions/issues/201 2224 [9] https://github.com/httpwg/http-extensions/issues/204 2226 [10] https://github.com/httpwg/http-extensions/issues/222 2228 [11] https://github.com/httpwg/http-extensions/issues/248 2230 [12] https://github.com/httpwg/http-extensions/issues/295 2232 [13] https://github.com/httpwg/http-extensions/issues/302 2234 [14] https://github.com/httpwg/http-extensions/issues/389 2236 [15] https://github.com/httpwg/http-extensions/issues/199 2238 [16] https://github.com/httpwg/http-extensions/issues/788 2240 [17] https://github.com/httpwg/http-extensions/issues/594 2242 [18] https://github.com/httpwg/http-extensions/issues/159 2244 [19] https://github.com/httpwg/http-extensions/issues/159 2246 [20] https://github.com/httpwg/http-extensions/issues/901 2248 [21] https://github.com/httpwg/http-extensions/pull/1035 2250 [22] https://github.com/httpwg/http-extensions/pull/1038 2252 [23] https://github.com/httpwg/http-extensions/pull/1040 2254 [24] https://github.com/httpwg/http-extensions/pull/1047 2256 Appendix A. Changes 2258 A.1. draft-ietf-httpbis-rfc6265bis-00 2260 o Port [RFC6265] to Markdown. No (intentional) normative changes. 2262 A.2. draft-ietf-httpbis-rfc6265bis-01 2264 o Fixes to formatting caused by mistakes in the initial port to 2265 Markdown: 2267 * https://github.com/httpwg/http-extensions/issues/243 [4] 2269 * https://github.com/httpwg/http-extensions/issues/246 [5] 2271 o Addresses errata 3444 by updating the "path-value" and "extension- 2272 av" grammar, errata 4148 by updating the "day-of-month", "year", 2273 and "time" grammar, and errata 3663 by adding the requested note. 2274 https://www.rfc-editor.org/errata_search.php?rfc=6265 [6] 2276 o Dropped "Cookie2" and "Set-Cookie2" from the IANA Considerations 2277 section: https://github.com/httpwg/http-extensions/issues/247 [7] 2279 o Merged the recommendations from [I-D.ietf-httpbis-cookie-alone], 2280 removing the ability for a non-secure origin to set cookies with a 2281 'secure' flag, and to overwrite cookies whose 'secure' flag is 2282 true. 2284 o Merged the recommendations from 2285 [I-D.ietf-httpbis-cookie-prefixes], adding "__Secure-" and 2286 "__Host-" cookie name prefix processing instructions. 2288 A.3. draft-ietf-httpbis-rfc6265bis-02 2290 o Merged the recommendations from 2291 [I-D.ietf-httpbis-cookie-same-site], adding support for the 2292 "SameSite" attribute. 2294 o Closed a number of editorial bugs: 2296 * Clarified address bar behavior for SameSite cookies: 2297 https://github.com/httpwg/http-extensions/issues/201 [8] 2299 * Added the word "Cookies" to the document's name: 2300 https://github.com/httpwg/http-extensions/issues/204 [9] 2302 * Clarified that the "__Host-" prefix requires an explicit "Path" 2303 attribute: https://github.com/httpwg/http-extensions/issues/222 2304 [10] 2306 * Expanded the options for dealing with third-party cookies to 2307 include a brief mention of partitioning based on first-party: 2308 https://github.com/httpwg/http-extensions/issues/248 [11] 2310 * Noted that double-quotes in cookie values are part of the 2311 value, and are not stripped: https://github.com/httpwg/http- 2312 extensions/issues/295 [12] 2314 * Fixed the "site for cookies" algorithm to return something that 2315 makes sense: https://github.com/httpwg/http-extensions/ 2316 issues/302 [13] 2318 A.4. draft-ietf-httpbis-rfc6265bis-03 2320 o Clarified handling of invalid SameSite values: 2321 https://github.com/httpwg/http-extensions/issues/389 [14] 2323 o Reflect widespread implementation practice of including a cookie's 2324 "host-only-flag" when calculating its uniqueness: 2325 https://github.com/httpwg/http-extensions/issues/199 [15] 2327 o Introduced an explicit "None" value for the SameSite attribute: 2328 https://github.com/httpwg/http-extensions/issues/788 [16] 2330 A.5. draft-ietf-httpbis-rfc6265bis-04 2332 o Allow "SameSite" cookies to be set for all top-level navigations. 2333 https://github.com/httpwg/http-extensions/issues/594 [17] 2335 o Treat "Set-Cookie: token" as creating the cookie "("", "token")": 2336 https://github.com/httpwg/http-extensions/issues/159 [18] 2338 o Reject cookies with neither name nor value (e.g. "Set-Cookie: =" 2339 and "Set-Cookie:": https://github.com/httpwg/http-extensions/ 2340 issues/159 [19] 2342 o Clarified behavior of multiple "SameSite" attributes in a cookie 2343 string: https://github.com/httpwg/http-extensions/issues/901 [20] 2345 A.6. draft-ietf-httpbis-rfc6265bis-05 2347 o Typos and editorial fixes: https://github.com/httpwg/http- 2348 extensions/pull/1035 [21], https://github.com/httpwg/http- 2349 extensions/pull/1038 [22], https://github.com/httpwg/http- 2350 extensions/pull/1040 [23], https://github.com/httpwg/http- 2351 extensions/pull/1047 [24]. 2353 Acknowledgements 2355 RFC 6265 was written by Adam Barth. This document is a minor update 2356 of RFC 6265, adding small features, and aligning the specification 2357 with the reality of today's deployments. Here, we're standing upon 2358 the shoulders of a giant since the majority of the text is still 2359 Adam's. 2361 Authors' Addresses 2363 Mike West (editor) 2364 Google, Inc 2366 Email: mkwst@google.com 2367 URI: https://mikewest.org/ 2369 John Wilander (editor) 2370 Apple, Inc 2372 Email: wilander@apple.com