draft-ietf-httpbis-rfc6265bis-03.txt   draft-ietf-httpbis-rfc6265bis-04.txt 
HTTP Working Group A. Barth HTTP M. West, Ed.
Internet-Draft M. West Internet-Draft Google, Inc
Obsoletes: 6265 (if approved) Google, Inc Obsoletes: 6265 (if approved) J. Wilander, Ed.
Intended status: Standards Track April 27, 2019 Intended status: Standards Track Apple, Inc
Expires: October 29, 2019 Expires: July 23, 2020 January 20, 2020
Cookies: HTTP State Management Mechanism Cookies: HTTP State Management Mechanism
draft-ietf-httpbis-rfc6265bis-03 draft-ietf-httpbis-rfc6265bis-04
Abstract Abstract
This document defines the HTTP Cookie and Set-Cookie header fields. This document defines the HTTP Cookie and Set-Cookie header fields.
These header fields can be used by HTTP servers to store state These header fields can be used by HTTP servers to store state
(called cookies) at HTTP user agents, letting the servers maintain a (called cookies) at HTTP user agents, letting the servers maintain a
stateful session over the mostly stateless HTTP protocol. Although stateful session over the mostly stateless HTTP protocol. Although
cookies have many historical infelicities that degrade their security cookies have many historical infelicities that degrade their security
and privacy, the Cookie and Set-Cookie header fields are widely used and privacy, the Cookie and Set-Cookie header fields are widely used
on the Internet. This document obsoletes RFC 6265. on the Internet. This document obsoletes RFC 6265.
skipping to change at page 1, line 47 skipping to change at page 1, line 47
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on October 29, 2019. This Internet-Draft will expire on July 23, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2020 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
skipping to change at page 2, line 46 skipping to change at page 2, line 46
2.1. Conformance Criteria . . . . . . . . . . . . . . . . . . 5 2.1. Conformance Criteria . . . . . . . . . . . . . . . . . . 5
2.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 5 2.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 5
2.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 2.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6
3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 7 3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 7
4. Server Requirements . . . . . . . . . . . . . . . . . . . . . 9 4. Server Requirements . . . . . . . . . . . . . . . . . . . . . 9
4.1. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . 9 4.1. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . 9
4.1.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . 9 4.1.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . 9
4.1.2. Semantics (Non-Normative) . . . . . . . . . . . . . . 11 4.1.2. Semantics (Non-Normative) . . . . . . . . . . . . . . 11
4.1.3. Cookie Name Prefixes . . . . . . . . . . . . . . . . 14 4.1.3. Cookie Name Prefixes . . . . . . . . . . . . . . . . 14
4.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . 15 4.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . 15 4.2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . 16
4.2.2. Semantics . . . . . . . . . . . . . . . . . . . . . . 16 4.2.2. Semantics . . . . . . . . . . . . . . . . . . . . . . 16
5. User Agent Requirements . . . . . . . . . . . . . . . . . . . 16 5. User Agent Requirements . . . . . . . . . . . . . . . . . . . 16
5.1. Subcomponent Algorithms . . . . . . . . . . . . . . . . . 16 5.1. Subcomponent Algorithms . . . . . . . . . . . . . . . . . 17
5.1.1. Dates . . . . . . . . . . . . . . . . . . . . . . . . 17 5.1.1. Dates . . . . . . . . . . . . . . . . . . . . . . . . 17
5.1.2. Canonicalized Host Names . . . . . . . . . . . . . . 18 5.1.2. Canonicalized Host Names . . . . . . . . . . . . . . 19
5.1.3. Domain Matching . . . . . . . . . . . . . . . . . . . 19 5.1.3. Domain Matching . . . . . . . . . . . . . . . . . . . 19
5.1.4. Paths and Path-Match . . . . . . . . . . . . . . . . 19 5.1.4. Paths and Path-Match . . . . . . . . . . . . . . . . 19
5.2. "Same-site" and "cross-site" Requests . . . . . . . . . . 20 5.2. "Same-site" and "cross-site" Requests . . . . . . . . . . 20
5.2.1. Document-based requests . . . . . . . . . . . . . . . 21 5.2.1. Document-based requests . . . . . . . . . . . . . . . 21
5.2.2. Worker-based requests . . . . . . . . . . . . . . . . 22 5.2.2. Worker-based requests . . . . . . . . . . . . . . . . 22
5.3. The Set-Cookie Header . . . . . . . . . . . . . . . . . . 23 5.3. The Set-Cookie Header . . . . . . . . . . . . . . . . . . 23
5.3.1. The Expires Attribute . . . . . . . . . . . . . . . . 25 5.3.1. The Expires Attribute . . . . . . . . . . . . . . . . 25
5.3.2. The Max-Age Attribute . . . . . . . . . . . . . . . . 26 5.3.2. The Max-Age Attribute . . . . . . . . . . . . . . . . 26
5.3.3. The Domain Attribute . . . . . . . . . . . . . . . . 26 5.3.3. The Domain Attribute . . . . . . . . . . . . . . . . 26
5.3.4. The Path Attribute . . . . . . . . . . . . . . . . . 27 5.3.4. The Path Attribute . . . . . . . . . . . . . . . . . 27
5.3.5. The Secure Attribute . . . . . . . . . . . . . . . . 27 5.3.5. The Secure Attribute . . . . . . . . . . . . . . . . 27
5.3.6. The HttpOnly Attribute . . . . . . . . . . . . . . . 27 5.3.6. The HttpOnly Attribute . . . . . . . . . . . . . . . 27
5.3.7. The SameSite Attribute . . . . . . . . . . . . . . . 27 5.3.7. The SameSite Attribute . . . . . . . . . . . . . . . 27
5.4. Storage Model . . . . . . . . . . . . . . . . . . . . . . 28 5.4. Storage Model . . . . . . . . . . . . . . . . . . . . . . 28
5.5. The Cookie Header . . . . . . . . . . . . . . . . . . . . 33 5.5. The Cookie Header . . . . . . . . . . . . . . . . . . . . 34
6. Implementation Considerations . . . . . . . . . . . . . . . . 35 6. Implementation Considerations . . . . . . . . . . . . . . . . 36
6.1. Limits . . . . . . . . . . . . . . . . . . . . . . . . . 35 6.1. Limits . . . . . . . . . . . . . . . . . . . . . . . . . 36
6.2. Application Programming Interfaces . . . . . . . . . . . 35 6.2. Application Programming Interfaces . . . . . . . . . . . 36
6.3. IDNA Dependency and Migration . . . . . . . . . . . . . . 36 6.3. IDNA Dependency and Migration . . . . . . . . . . . . . . 36
7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 36 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 37
7.1. Third-Party Cookies . . . . . . . . . . . . . . . . . . . 36 7.1. Third-Party Cookies . . . . . . . . . . . . . . . . . . . 37
7.2. User Controls . . . . . . . . . . . . . . . . . . . . . . 37 7.2. User Controls . . . . . . . . . . . . . . . . . . . . . . 38
7.3. Expiration Dates . . . . . . . . . . . . . . . . . . . . 37 7.3. Expiration Dates . . . . . . . . . . . . . . . . . . . . 38
8. Security Considerations . . . . . . . . . . . . . . . . . . . 38 8. Security Considerations . . . . . . . . . . . . . . . . . . . 38
8.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 38 8.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 38
8.2. Ambient Authority . . . . . . . . . . . . . . . . . . . . 38 8.2. Ambient Authority . . . . . . . . . . . . . . . . . . . . 39
8.3. Clear Text . . . . . . . . . . . . . . . . . . . . . . . 39 8.3. Clear Text . . . . . . . . . . . . . . . . . . . . . . . 39
8.4. Session Identifiers . . . . . . . . . . . . . . . . . . . 40 8.4. Session Identifiers . . . . . . . . . . . . . . . . . . . 40
8.5. Weak Confidentiality . . . . . . . . . . . . . . . . . . 40 8.5. Weak Confidentiality . . . . . . . . . . . . . . . . . . 41
8.6. Weak Integrity . . . . . . . . . . . . . . . . . . . . . 41 8.6. Weak Integrity . . . . . . . . . . . . . . . . . . . . . 41
8.7. Reliance on DNS . . . . . . . . . . . . . . . . . . . . . 42 8.7. Reliance on DNS . . . . . . . . . . . . . . . . . . . . . 42
8.8. SameSite Cookies . . . . . . . . . . . . . . . . . . . . 42 8.8. SameSite Cookies . . . . . . . . . . . . . . . . . . . . 42
8.8.1. Defense in depth . . . . . . . . . . . . . . . . . . 42 8.8.1. Defense in depth . . . . . . . . . . . . . . . . . . 42
8.8.2. Top-level Navigations . . . . . . . . . . . . . . . . 42 8.8.2. Top-level Navigations . . . . . . . . . . . . . . . . 43
8.8.3. Mashups and Widgets . . . . . . . . . . . . . . . . . 43 8.8.3. Mashups and Widgets . . . . . . . . . . . . . . . . . 43
8.8.4. Server-controlled . . . . . . . . . . . . . . . . . . 43 8.8.4. Server-controlled . . . . . . . . . . . . . . . . . . 44
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44
9.1. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . 43 9.1. Cookie . . . . . . . . . . . . . . . . . . . . . . . . . 44
9.2. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . 44 9.2. Set-Cookie . . . . . . . . . . . . . . . . . . . . . . . 44
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 44 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 45
10.1. Normative References . . . . . . . . . . . . . . . . . . 44 10.1. Normative References . . . . . . . . . . . . . . . . . . 45
10.2. Informative References . . . . . . . . . . . . . . . . . 45 10.2. Informative References . . . . . . . . . . . . . . . . . 46
10.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 47 10.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Appendix A. Changes . . . . . . . . . . . . . . . . . . . . . . 48 Appendix A. Changes . . . . . . . . . . . . . . . . . . . . . . 49
A.1. draft-ietf-httpbis-rfc6265bis-00 . . . . . . . . . . . . 48 A.1. draft-ietf-httpbis-rfc6265bis-00 . . . . . . . . . . . . 49
A.2. draft-ietf-httpbis-rfc6265bis-01 . . . . . . . . . . . . 48 A.2. draft-ietf-httpbis-rfc6265bis-01 . . . . . . . . . . . . 49
A.3. draft-ietf-httpbis-rfc6265bis-02 . . . . . . . . . . . . 49 A.3. draft-ietf-httpbis-rfc6265bis-02 . . . . . . . . . . . . 49
A.4. draft-ietf-httpbis-rfc6265bis-03 . . . . . . . . . . . . 49 A.4. draft-ietf-httpbis-rfc6265bis-03 . . . . . . . . . . . . 50
A.5. draft-ietf-httpbis-rfc6265bis-04 . . . . . . . . . . . . 50
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 49 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 51
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 50 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 51
1. Introduction 1. Introduction
This document defines the HTTP Cookie and Set-Cookie header fields. This document defines the HTTP Cookie and Set-Cookie header fields.
Using the Set-Cookie header field, an HTTP server can pass name/value Using the Set-Cookie header field, an HTTP server can pass name/value
pairs and associated metadata (called cookies) to a user agent. When pairs and associated metadata (called cookies) to a user agent. When
the user agent makes subsequent requests to the server, the user the user agent makes subsequent requests to the server, the user
agent uses the metadata and other information to determine whether to agent uses the metadata and other information to determine whether to
return the name/value pairs in the Cookie header. return the name/value pairs in the Cookie header.
skipping to change at page 6, line 44 skipping to change at page 6, line 44
The term "origin", the mechanism of deriving an origin from a URI, The term "origin", the mechanism of deriving an origin from a URI,
and the "the same" matching algorithm for origins are defined in and the "the same" matching algorithm for origins are defined in
[RFC6454]. [RFC6454].
"Safe" HTTP methods include "GET", "HEAD", "OPTIONS", and "TRACE", as "Safe" HTTP methods include "GET", "HEAD", "OPTIONS", and "TRACE", as
defined in Section 4.2.1 of [RFC7231]. defined in Section 4.2.1 of [RFC7231].
The term "public suffix" is defined in a note in Section 5.3 of The term "public suffix" is defined in a note in Section 5.3 of
[RFC6265] as "a domain that is controlled by a public registry", and [RFC6265] as "a domain that is controlled by a public registry", and
are also known as "effective top-level domains" (eTLDs). For are also known as "effective top-level domains" (eTLDs). For
example, "example.com"'s public suffix is "com". User agents SHOULD example, "site.example"'s public suffix is "com". User agents SHOULD
use an up-to-date public suffix list, such as the one maintained by use an up-to-date public suffix list, such as the one maintained by
Mozilla at [PSL]. Mozilla at [PSL].
An origin's "registered domain" is the origin's host's public suffix An origin's "registered domain" is the origin's host's public suffix
plus the label to its left. That is, for "https://www.example.com", plus the label to its left. That is, for "https://www.site.example",
the public suffix is "com", and the registered domain is the public suffix is "example", and the registered domain is
"example.com". This concept is defined more rigorously in [PSL], and "site.example". This concept is defined more rigorously in [PSL],
is also known as "effective top-level domain plus one" (eTLD+1). and is also known as "effective top-level domain plus one" (eTLD+1).
The term "request", as well as a request's "client", "current url", The term "request", as well as a request's "client", "current url",
"method", and "target browsing context", are defined in [FETCH]. "method", and "target browsing context", are defined in [FETCH].
3. Overview 3. Overview
This section outlines a way for an origin server to send state This section outlines a way for an origin server to send state
information to a user agent and for the user agent to return the information to a user agent and for the user agent to return the
state information to the origin server. state information to the origin server.
skipping to change at page 8, line 7 skipping to change at page 8, line 7
== Server -> User Agent == == Server -> User Agent ==
Set-Cookie: SID=31d4d96e407aad42 Set-Cookie: SID=31d4d96e407aad42
== User Agent -> Server == == User Agent -> Server ==
Cookie: SID=31d4d96e407aad42 Cookie: SID=31d4d96e407aad42
The server can alter the default scope of the cookie using the Path The server can alter the default scope of the cookie using the Path
and Domain attributes. For example, the server can instruct the user and Domain attributes. For example, the server can instruct the user
agent to return the cookie to every path and every subdomain of agent to return the cookie to every path and every subdomain of
example.com. site.example.
== Server -> User Agent == == Server -> User Agent ==
Set-Cookie: SID=31d4d96e407aad42; Path=/; Domain=example.com Set-Cookie: SID=31d4d96e407aad42; Path=/; Domain=site.example
== User Agent -> Server == == User Agent -> Server ==
Cookie: SID=31d4d96e407aad42 Cookie: SID=31d4d96e407aad42
As shown in the next example, the server can store multiple cookies As shown in the next example, the server can store multiple cookies
at the user agent. For example, the server can store a session at the user agent. For example, the server can store a session
identifier as well as the user's preferred language by returning two identifier as well as the user's preferred language by returning two
Set-Cookie header fields. Notice that the server uses the Secure and Set-Cookie header fields. Notice that the server uses the Secure and
HttpOnly attributes to provide additional security protections for HttpOnly attributes to provide additional security protections for
the more sensitive session identifier (see Section 4.1.2). the more sensitive session identifier (see Section 4.1.2).
== Server -> User Agent == == Server -> User Agent ==
Set-Cookie: SID=31d4d96e407aad42; Path=/; Secure; HttpOnly Set-Cookie: SID=31d4d96e407aad42; Path=/; Secure; HttpOnly
Set-Cookie: lang=en-US; Path=/; Domain=example.com Set-Cookie: lang=en-US; Path=/; Domain=site.example
== User Agent -> Server == == User Agent -> Server ==
Cookie: SID=31d4d96e407aad42; lang=en-US Cookie: SID=31d4d96e407aad42; lang=en-US
Notice that the Cookie header above contains two cookies, one named Notice that the Cookie header above contains two cookies, one named
SID and one named lang. If the server wishes the user agent to SID and one named lang. If the server wishes the user agent to
persist the cookie over multiple "sessions" (e.g., user agent persist the cookie over multiple "sessions" (e.g., user agent
restarts), the server can specify an expiration date in the Expires restarts), the server can specify an expiration date in the Expires
attribute. Note that the user agent might delete the cookie before attribute. Note that the user agent might delete the cookie before
skipping to change at page 12, line 41 skipping to change at page 12, line 41
If a cookie has both the Max-Age and the Expires attribute, the Max- If a cookie has both the Max-Age and the Expires attribute, the Max-
Age attribute has precedence and controls the expiration date of the Age attribute has precedence and controls the expiration date of the
cookie. If a cookie has neither the Max-Age nor the Expires cookie. If a cookie has neither the Max-Age nor the Expires
attribute, the user agent will retain the cookie until "the current attribute, the user agent will retain the cookie until "the current
session is over" (as defined by the user agent). session is over" (as defined by the user agent).
4.1.2.3. The Domain Attribute 4.1.2.3. The Domain Attribute
The Domain attribute specifies those hosts to which the cookie will The Domain attribute specifies those hosts to which the cookie will
be sent. For example, if the value of the Domain attribute is be sent. For example, if the value of the Domain attribute is
"example.com", the user agent will include the cookie in the Cookie "site.example", the user agent will include the cookie in the Cookie
header when making HTTP requests to example.com, www.example.com, and header when making HTTP requests to site.example, www.site.example,
www.corp.example.com. (Note that a leading %x2E ("."), if present, and www.corp.site.example. (Note that a leading %x2E ("."), if
is ignored even though that character is not permitted, but a present, is ignored even though that character is not permitted, but
trailing %x2E ("."), if present, will cause the user agent to ignore a trailing %x2E ("."), if present, will cause the user agent to
the attribute.) If the server omits the Domain attribute, the user ignore the attribute.) If the server omits the Domain attribute, the
agent will return the cookie only to the origin server. user agent will return the cookie only to the origin server.
WARNING: Some existing user agents treat an absent Domain attribute WARNING: Some existing user agents treat an absent Domain attribute
as if the Domain attribute were present and contained the current as if the Domain attribute were present and contained the current
host name. For example, if example.com returns a Set-Cookie header host name. For example, if site.example returns a Set-Cookie header
without a Domain attribute, these user agents will erroneously send without a Domain attribute, these user agents will erroneously send
the cookie to www.example.com as well. the cookie to www.site.example as well.
The user agent will reject cookies unless the Domain attribute The user agent will reject cookies unless the Domain attribute
specifies a scope for the cookie that would include the origin specifies a scope for the cookie that would include the origin
server. For example, the user agent will accept a cookie with a server. For example, the user agent will accept a cookie with a
Domain attribute of "example.com" or of "foo.example.com" from Domain attribute of "site.example" or of "foo.site.example" from
foo.example.com, but the user agent will not accept a cookie with a foo.site.example, but the user agent will not accept a cookie with a
Domain attribute of "bar.example.com" or of "baz.foo.example.com". Domain attribute of "bar.site.example" or of "baz.foo.site.example".
NOTE: For security reasons, many user agents are configured to reject NOTE: For security reasons, many user agents are configured to reject
Domain attributes that correspond to "public suffixes". For example, Domain attributes that correspond to "public suffixes". For example,
some user agents will reject Domain attributes of "com" or "co.uk". some user agents will reject Domain attributes of "com" or "co.uk".
(See Section 5.4 for more information.) (See Section 5.4 for more information.)
4.1.2.4. The Path Attribute 4.1.2.4. The Path Attribute
The scope of each cookie is limited to a set of paths, controlled by The scope of each cookie is limited to a set of paths, controlled by
the Path attribute. If the server omits the Path attribute, the user the Path attribute. If the server omits the Path attribute, the user
skipping to change at page 14, line 21 skipping to change at page 14, line 21
Note that the HttpOnly attribute is independent of the Secure Note that the HttpOnly attribute is independent of the Secure
attribute: a cookie can have both the HttpOnly and the Secure attribute: a cookie can have both the HttpOnly and the Secure
attribute. attribute.
4.1.2.7. The SameSite Attribute 4.1.2.7. The SameSite Attribute
The "SameSite" attribute limits the scope of the cookie such that it The "SameSite" attribute limits the scope of the cookie such that it
will only be attached to requests if those requests are same-site, as will only be attached to requests if those requests are same-site, as
defined by the algorithm in Section 5.2. For example, requests for defined by the algorithm in Section 5.2. For example, requests for
"https://example.com/sekrit-image" will attach same-site cookies if "https://site.example/sekrit-image" will attach same-site cookies if
and only if initiated from a context whose "site for cookies" is and only if initiated from a context whose "site for cookies" is
"example.com". "site.example".
If the "SameSite" attribute's value is "Strict", the cookie will only If the "SameSite" attribute's value is "Strict", the cookie will only
be sent along with "same-site" requests. If the value is "Lax", the be sent along with "same-site" requests. If the value is "Lax", the
cookie will be sent with same-site requests, and with "cross-site" cookie will be sent with same-site requests, and with "cross-site"
top-level navigations, as described in Section 5.3.7.1. If the value top-level navigations, as described in Section 5.3.7.1. If the value
is "None", the cookie will be sent with same-site and cross-site is "None", the cookie will be sent with same-site and cross-site
requests. If the "SameSite" attribute's value is something other requests. If the "SameSite" attribute's value is something other
than these three known keywords, the attribute's value will be than these three known keywords, the attribute's value will be
treated as "None". treated as "None".
The "SameSite" attribute affects cookie creation as well as delivery.
Cookies which assert "SameSite=Lax" or "SameSite=Strict" cannot be
set in responses to cross-site subresource requests, or cross-site
nested navigations. They can be set along with any top-level
navigation, cross-site or otherwise.
4.1.3. Cookie Name Prefixes 4.1.3. Cookie Name Prefixes
Section 8.5 and Section 8.6 of this document spell out some of the Section 8.5 and Section 8.6 of this document spell out some of the
drawbacks of cookies' historical implementation. In particular, it drawbacks of cookies' historical implementation. In particular, it
is impossible for a server to have confidence that a given cookie was is impossible for a server to have confidence that a given cookie was
set with a particular set of attributes. In order to provide such set with a particular set of attributes. In order to provide such
confidence in a backwards-compatible way, two common sets of confidence in a backwards-compatible way, two common sets of
requirements can be inferred from the first few characters of the requirements can be inferred from the first few characters of the
cookie's name. cookie's name.
skipping to change at page 15, line 8 skipping to change at page 15, line 14
4.1.3.1. The "__Secure-" Prefix 4.1.3.1. The "__Secure-" Prefix
If a cookie's name begins with a case-sensitive match for the string If a cookie's name begins with a case-sensitive match for the string
"__Secure-", then the cookie will have been set with a "Secure" "__Secure-", then the cookie will have been set with a "Secure"
attribute. attribute.
For example, the following "Set-Cookie" header would be rejected by a For example, the following "Set-Cookie" header would be rejected by a
conformant user agent, as it does not have a "Secure" attribute. conformant user agent, as it does not have a "Secure" attribute.
Set-Cookie: __Secure-SID=12345; Domain=example.com Set-Cookie: __Secure-SID=12345; Domain=site.example
Whereas the following "Set-Cookie" header would be accepted: Whereas the following "Set-Cookie" header would be accepted:
Set-Cookie: __Secure-SID=12345; Domain=example.com; Secure Set-Cookie: __Secure-SID=12345; Domain=site.example; Secure
4.1.3.2. The "__Host-" Prefix 4.1.3.2. The "__Host-" Prefix
If a cookie's name begins with a case-sensitive match for the string If a cookie's name begins with a case-sensitive match for the string
"__Host-", then the cookie will have been set with a "Secure" "__Host-", then the cookie will have been set with a "Secure"
attribute, a "Path" attribute with a value of "/", and no "Domain" attribute, a "Path" attribute with a value of "/", and no "Domain"
attribute. attribute.
This combination yields a cookie that hews as closely as a cookie can This combination yields a cookie that hews as closely as a cookie can
to treating the origin as a security boundary. The lack of a to treating the origin as a security boundary. The lack of a
skipping to change at page 15, line 37 skipping to change at page 15, line 43
specific paths. The "Secure" attribute ensures that the cookie is specific paths. The "Secure" attribute ensures that the cookie is
unaltered by non-secure origins, and won't span protocols. unaltered by non-secure origins, and won't span protocols.
Ports are the only piece of the origin model that "__Host-" cookies Ports are the only piece of the origin model that "__Host-" cookies
continue to ignore. continue to ignore.
For example, the following cookies would always be rejected: For example, the following cookies would always be rejected:
Set-Cookie: __Host-SID=12345 Set-Cookie: __Host-SID=12345
Set-Cookie: __Host-SID=12345; Secure Set-Cookie: __Host-SID=12345; Secure
Set-Cookie: __Host-SID=12345; Domain=example.com Set-Cookie: __Host-SID=12345; Domain=site.example
Set-Cookie: __Host-SID=12345; Domain=example.com; Path=/ Set-Cookie: __Host-SID=12345; Domain=site.example; Path=/
Set-Cookie: __Host-SID=12345; Secure; Domain=example.com; Path=/ Set-Cookie: __Host-SID=12345; Secure; Domain=site.example; Path=/
While the would be accepted if set from a secure origin (e.g. While the would be accepted if set from a secure origin (e.g.
"https://example.com/"), and rejected otherwise: "https://site.example/"), and rejected otherwise:
Set-Cookie: __Host-SID=12345; Secure; Path=/ Set-Cookie: __Host-SID=12345; Secure; Path=/
4.2. Cookie 4.2. Cookie
4.2.1. Syntax 4.2.1. Syntax
The user agent sends stored cookies to the origin server in the The user agent sends stored cookies to the origin server in the
Cookie header. If the server conforms to the requirements in Cookie header. If the server conforms to the requirements in
Section 4.1 (and the user agent conforms to the requirements in Section 4.1 (and the user agent conforms to the requirements in
skipping to change at page 24, line 9 skipping to change at page 24, line 16
but not including, the first %x3B (";"), and the unparsed- but not including, the first %x3B (";"), and the unparsed-
attributes consist of the remainder of the set-cookie-string attributes consist of the remainder of the set-cookie-string
(including the %x3B (";") in question). (including the %x3B (";") in question).
Otherwise: Otherwise:
1. The name-value-pair string consists of all the characters 1. The name-value-pair string consists of all the characters
contained in the set-cookie-string, and the unparsed- contained in the set-cookie-string, and the unparsed-
attributes is the empty string. attributes is the empty string.
2. If the name-value-pair string lacks a %x3D ("=") character, 2. If the name-value-pair string lacks a %x3D ("=") character, then
ignore the set-cookie-string entirely. the name string is empty, and the value string is the value of
name-value-pair.
3. The (possibly empty) name string consists of the characters up Otherwise, the name string consists of the characters up to, but
to, but not including, the first %x3D ("=") character, and the not including, the first %x3D ("=") character, and the (possibly
(possibly empty) value string consists of the characters after empty) value string consists of the characters after the first
the first %x3D ("=") character. %x3D ("=") character.
4. Remove any leading or trailing WSP characters from the name 3. Remove any leading or trailing WSP characters from the name
string and the value string. string and the value string.
5. If the name string is empty, ignore the set-cookie-string 4. If both the name string and the value string are empty, ignore
entirely. the set-cookie-string entirely.
6. The cookie-name is the name string, and the cookie-value is the 5. The cookie-name is the name string, and the cookie-value is the
value string. value string.
The user agent MUST use an algorithm equivalent to the following The user agent MUST use an algorithm equivalent to the following
algorithm to parse the unparsed-attributes: algorithm to parse the unparsed-attributes:
1. If the unparsed-attributes string is empty, skip the rest of 1. If the unparsed-attributes string is empty, skip the rest of
these steps. these steps.
2. Discard the first character of the unparsed-attributes (which 2. Discard the first character of the unparsed-attributes (which
will be a %x3B (";") character). will be a %x3B (";") character).
skipping to change at page 30, line 17 skipping to change at page 30, line 17
1. Let the domain-attribute be the empty string. 1. Let the domain-attribute be the empty string.
Otherwise: Otherwise:
1. Ignore the cookie entirely and abort these steps. 1. Ignore the cookie entirely and abort these steps.
NOTE: A "public suffix" is a domain that is controlled by a NOTE: A "public suffix" is a domain that is controlled by a
public registry, such as "com", "co.uk", and "pvt.k12.wy.us". public registry, such as "com", "co.uk", and "pvt.k12.wy.us".
This step is essential for preventing attacker.com from This step is essential for preventing attacker.com from
disrupting the integrity of example.com by setting a cookie with disrupting the integrity of site.example by setting a cookie
a Domain attribute of "com". Unfortunately, the set of public with a Domain attribute of "com". Unfortunately, the set of
suffixes (also known as "registry controlled domains") changes public suffixes (also known as "registry controlled domains")
over time. If feasible, user agents SHOULD use an up-to-date changes over time. If feasible, user agents SHOULD use an up-
public suffix list, such as the one maintained by the Mozilla to-date public suffix list, such as the one maintained by the
project at http://publicsuffix.org/ [4]. Mozilla project at http://publicsuffix.org/ [4].
6. If the domain-attribute is non-empty: 6. If the domain-attribute is non-empty:
1. If the canonicalized request-host does not domain-match the 1. If the canonicalized request-host does not domain-match the
domain-attribute: domain-attribute:
1. Ignore the cookie entirely and abort these steps. 1. Ignore the cookie entirely and abort these steps.
Otherwise: Otherwise:
skipping to change at page 31, line 44 skipping to change at page 31, line 44
Note: The path comparison is not symmetric, ensuring only that a Note: The path comparison is not symmetric, ensuring only that a
newly-created, non-secure cookie does not overlay an existing newly-created, non-secure cookie does not overlay an existing
secure cookie, providing some mitigation against cookie-fixing secure cookie, providing some mitigation against cookie-fixing
attacks. That is, given an existing secure cookie named 'a' attacks. That is, given an existing secure cookie named 'a'
with a path of '/login', a non-secure cookie named 'a' could be with a path of '/login', a non-secure cookie named 'a' could be
set for a path of '/' or '/foo', but not for a path of '/login' set for a path of '/' or '/foo', but not for a path of '/login'
or '/login/en'. or '/login/en'.
13. If the cookie-attribute-list contains an attribute with an 13. If the cookie-attribute-list contains an attribute with an
attribute-name of "SameSite", set the cookie's same-site-flag to attribute-name of "SameSite", set the cookie's same-site-flag to
attribute-value (i.e. either "Strict", "Lax", or "None"). the attribute-value of the last attribute in the cookie-
Otherwise, set the cookie's same-site-flag to "None". attribute-list with an attribute-name of "SameSite" (i.e. either
"Strict", "Lax", or "None"). Otherwise, set the cookie's same-
site-flag to "None".
14. If the cookie's "same-site-flag" is not "None", and the cookie 14. If the cookie's "same-site-flag" is not "None":
is being set from a context whose "site for cookies" is not an
exact match for request-uri's host's registered domain, then 1. If the cookie was received from a "non-HTTP" API, and the
abort these steps and ignore the newly created cookie entirely. API was called from a context whose "site for cookies" is
not an exact match for request-uri's host's registered
domain, then abort these steps and ignore the newly created
cookie entirely.
2. If the cookie was received from a "same-site" request (as
defined in Section 5.2), skip the remaining substeps and
continue processing the cookie.
3. If the cookie was received from a request which is
navigating a top-level browsing context [HTML] (e.g. if the
request's "reserved client" is either "null" or an
environment whose "target browsing context" is a top-level
browing context), skip the remaining substeps and continue
processing the cookie.
Note: Top-level navigations can create a cookie with any
"SameSite" value, even if the new cookie wouldn't have been
sent along with the request had it already existed prior to
the navigation.
4. Abort these steps and ignore the newly created cookie
entirely.
15. If the cookie-name begins with a case-sensitive match for the 15. If the cookie-name begins with a case-sensitive match for the
string "__Secure-", abort these steps and ignore the cookie string "__Secure-", abort these steps and ignore the cookie
entirely unless the cookie's secure-only-flag is true. entirely unless the cookie's secure-only-flag is true.
16. If the cookie-name begins with a case-sensitive match for the 16. If the cookie-name begins with a case-sensitive match for the
string "__Host-", abort these steps and ignore the cookie string "__Host-", abort these steps and ignore the cookie
entirely unless the cookie meets all the following criteria: entirely unless the cookie meets all the following criteria:
1. The cookie's secure-only-flag is true. 1. The cookie's secure-only-flag is true.
skipping to change at page 41, line 16 skipping to change at page 41, line 45
network-level protocol does not send cookies stored for one path to network-level protocol does not send cookies stored for one path to
another, some user agents expose cookies via non-HTTP APIs, such as another, some user agents expose cookies via non-HTTP APIs, such as
HTML's document.cookie API. Because some of these user agents (e.g., HTML's document.cookie API. Because some of these user agents (e.g.,
web browsers) do not isolate resources received from different paths, web browsers) do not isolate resources received from different paths,
a resource retrieved from one path might be able to access cookies a resource retrieved from one path might be able to access cookies
stored for another path. stored for another path.
8.6. Weak Integrity 8.6. Weak Integrity
Cookies do not provide integrity guarantees for sibling domains (and Cookies do not provide integrity guarantees for sibling domains (and
their subdomains). For example, consider foo.example.com and their subdomains). For example, consider foo.site.example and
bar.example.com. The foo.example.com server can set a cookie with a bar.site.example. The foo.site.example server can set a cookie with
Domain attribute of "example.com" (possibly overwriting an existing a Domain attribute of "site.example" (possibly overwriting an
"example.com" cookie set by bar.example.com), and the user agent will existing "site.example" cookie set by bar.site.example), and the user
include that cookie in HTTP requests to bar.example.com. In the agent will include that cookie in HTTP requests to bar.site.example.
worst case, bar.example.com will be unable to distinguish this cookie In the worst case, bar.site.example will be unable to distinguish
from a cookie it set itself. The foo.example.com server might be this cookie from a cookie it set itself. The foo.site.example server
able to leverage this ability to mount an attack against might be able to leverage this ability to mount an attack against
bar.example.com. bar.site.example.
Even though the Set-Cookie header supports the Path attribute, the Even though the Set-Cookie header supports the Path attribute, the
Path attribute does not provide any integrity protection because the Path attribute does not provide any integrity protection because the
user agent will accept an arbitrary Path attribute in a Set-Cookie user agent will accept an arbitrary Path attribute in a Set-Cookie
header. For example, an HTTP response to a request for header. For example, an HTTP response to a request for
http://example.com/foo/bar can set a cookie with a Path attribute of http://site.example/foo/bar can set a cookie with a Path attribute of
"/qux". Consequently, servers SHOULD NOT both run mutually "/qux". Consequently, servers SHOULD NOT both run mutually
distrusting services on different paths of the same host and use distrusting services on different paths of the same host and use
cookies to store security-sensitive information. cookies to store security-sensitive information.
An active network attacker can also inject cookies into the Cookie An active network attacker can also inject cookies into the Cookie
header sent to https://example.com/ by impersonating a response from header sent to https://site.example/ by impersonating a response from
http://example.com/ and injecting a Set-Cookie header. The HTTPS http://site.example/ and injecting a Set-Cookie header. The HTTPS
server at example.com will be unable to distinguish these cookies server at site.example will be unable to distinguish these cookies
from cookies that it set itself in an HTTPS response. An active from cookies that it set itself in an HTTPS response. An active
network attacker might be able to leverage this ability to mount an network attacker might be able to leverage this ability to mount an
attack against example.com even if example.com uses HTTPS attack against site.example even if site.example uses HTTPS
exclusively. exclusively.
Servers can partially mitigate these attacks by encrypting and Servers can partially mitigate these attacks by encrypting and
signing the contents of their cookies. However, using cryptography signing the contents of their cookies. However, using cryptography
does not mitigate the issue completely because an attacker can replay does not mitigate the issue completely because an attacker can replay
a cookie he or she received from the authentic example.com server in a cookie he or she received from the authentic site.example server in
the user's session, with unpredictable results. the user's session, with unpredictable results.
Finally, an attacker might be able to force the user agent to delete Finally, an attacker might be able to force the user agent to delete
cookies by storing a large number of cookies. Once the user agent cookies by storing a large number of cookies. Once the user agent
reaches its storage limit, the user agent will be forced to evict reaches its storage limit, the user agent will be forced to evict
some cookies. Servers SHOULD NOT rely upon user agents retaining some cookies. Servers SHOULD NOT rely upon user agents retaining
cookies. cookies.
8.7. Reliance on DNS 8.7. Reliance on DNS
skipping to change at page 42, line 41 skipping to change at page 43, line 24
8.8.2. Top-level Navigations 8.8.2. Top-level Navigations
Setting the "SameSite" attribute in "strict" mode provides robust Setting the "SameSite" attribute in "strict" mode provides robust
defense in depth against CSRF attacks, but has the potential to defense in depth against CSRF attacks, but has the potential to
confuse users unless sites' developers carefully ensure that their confuse users unless sites' developers carefully ensure that their
cookie-based session management systems deal reasonably well with cookie-based session management systems deal reasonably well with
top-level navigations. top-level navigations.
Consider the scenario in which a user reads their email at MegaCorp Consider the scenario in which a user reads their email at MegaCorp
Inc's webmail provider "https://example.com/". They might expect Inc's webmail provider "https://site.example/". They might expect
that clicking on an emailed link to "https://projects.com/secret/ that clicking on an emailed link to "https://projects.example/secret/
project" would show them the secret project that they're authorized project" would show them the secret project that they're authorized
to see, but if "projects.com" has marked their session cookies as to see, but if "projects.example" has marked their session cookies as
"SameSite", then this cross-site navigation won't send them along "SameSite", then this cross-site navigation won't send them along
with the request. "projects.com" will render a 404 error to avoid with the request. "projects.com" will render a 404 error to avoid
leaking secret information, and the user will be quite confused. leaking secret information, and the user will be quite confused.
Developers can avoid this confusion by adopting a session management Developers can avoid this confusion by adopting a session management
system that relies on not one, but two cookies: one conceptually system that relies on not one, but two cookies: one conceptually
granting "read" access, another granting "write" access. The latter granting "read" access, another granting "write" access. The latter
could be marked as "SameSite", and its absence would prompt a could be marked as "SameSite", and its absence would prompt a
reauthentication step before executing any non-idempotent action. reauthentication step before executing any non-idempotent action.
The former could drop the "SameSite" attribute entirely, or choose The former could drop the "SameSite" attribute entirely, or choose
skipping to change at page 44, line 46 skipping to change at page 45, line 34
Application and Support", STD 3, RFC 1123, Application and Support", STD 3, RFC 1123,
DOI 10.17487/RFC1123, October 1989, DOI 10.17487/RFC1123, October 1989,
<https://www.rfc-editor.org/info/rfc1123>. <https://www.rfc-editor.org/info/rfc1123>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC3490] Costello, A., "Internationalizing Domain Names in [RFC3490] Costello, A., "Internationalizing Domain Names in
Applications (IDNA)", RFC 3490, DOI 10.17487/RFC3490, Applications (IDNA)", RFC 3490, March 2003.
March 2003, <https://www.rfc-editor.org/info/rfc3490>.
See Section 6.3 for an explanation why the normative See Section 6.3 for an explanation why the normative
reference to an obsoleted specification is needed. reference to an obsoleted specification is needed.
[RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet [RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet
Application Protocol Collation Registry", RFC 4790, Application Protocol Collation Registry", RFC 4790,
DOI 10.17487/RFC4790, March 2007, DOI 10.17487/RFC4790, March 2007,
<https://www.rfc-editor.org/info/rfc4790>. <https://www.rfc-editor.org/info/rfc4790>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
skipping to change at page 48, line 19 skipping to change at page 48, line 49
[13] https://github.com/httpwg/http-extensions/issues/295 [13] https://github.com/httpwg/http-extensions/issues/295
[14] https://github.com/httpwg/http-extensions/issues/302 [14] https://github.com/httpwg/http-extensions/issues/302
[15] https://github.com/httpwg/http-extensions/issues/389 [15] https://github.com/httpwg/http-extensions/issues/389
[16] https://github.com/httpwg/http-extensions/issues/199 [16] https://github.com/httpwg/http-extensions/issues/199
[17] https://github.com/httpwg/http-extensions/issues/788 [17] https://github.com/httpwg/http-extensions/issues/788
[18] https://github.com/httpwg/http-extensions/issues/594
[19] https://github.com/httpwg/http-extensions/issues/159
[20] https://github.com/httpwg/http-extensions/issues/159
[21] https://github.com/httpwg/http-extensions/issues/901
Appendix A. Changes Appendix A. Changes
A.1. draft-ietf-httpbis-rfc6265bis-00 A.1. draft-ietf-httpbis-rfc6265bis-00
o Port [RFC6265] to Markdown. No (intentional) normative changes. o Port [RFC6265] to Markdown. No (intentional) normative changes.
A.2. draft-ietf-httpbis-rfc6265bis-01 A.2. draft-ietf-httpbis-rfc6265bis-01
o Fixes to formatting caused by mistakes in the initial port to o Fixes to formatting caused by mistakes in the initial port to
Markdown: Markdown:
skipping to change at page 49, line 47 skipping to change at page 50, line 36
o Clarified handling of invalid SameSite values: o Clarified handling of invalid SameSite values:
https://github.com/httpwg/http-extensions/issues/389 [15] https://github.com/httpwg/http-extensions/issues/389 [15]
o Reflect widespread implementation practice of including a cookie's o Reflect widespread implementation practice of including a cookie's
"host-only-flag" when calculating its uniqueness: "host-only-flag" when calculating its uniqueness:
https://github.com/httpwg/http-extensions/issues/199 [16] https://github.com/httpwg/http-extensions/issues/199 [16]
o Introduced an explicit "None" value for the SameSite attribute: o Introduced an explicit "None" value for the SameSite attribute:
https://github.com/httpwg/http-extensions/issues/788 [17] https://github.com/httpwg/http-extensions/issues/788 [17]
Acknowledgements A.5. draft-ietf-httpbis-rfc6265bis-04
This document is a minor update of RFC 6265, adding small features, o Allow "SameSite" cookies to be set for all top-level navigations.
and aligning the specification with the reality of today's https://github.com/httpwg/http-extensions/issues/594 [18]
deployments. Here, we're standing upon the shoulders of giants.
Authors' Addresses o Treat "Set-Cookie: token" as creating the cookie "("", "token")":
https://github.com/httpwg/http-extensions/issues/159 [19]
Adam Barth o Reject cookies with neither name nor value (e.g. "Set-Cookie: ="
Google, Inc and "Set-Cookie:": https://github.com/httpwg/http-extensions/
issues/159 [20]
URI: https://www.adambarth.com/ o Clarified behavior of multiple "SameSite" attributes in a cookie
string: https://github.com/httpwg/http-extensions/issues/901 [21]
Mike West Acknowledgements
RFC 6265 was written by Adam Barth. This document is a minor update
of RFC 6265, adding small features, and aligning the specification
with the reality of today's deployments. Here, we're standing upon
the shoulders of a giant since the majority of the text is still
Adam's.
Authors' Addresses
Mike West (editor)
Google, Inc Google, Inc
Email: mkwst@google.com Email: mkwst@google.com
URI: https://mikewest.org/ URI: https://mikewest.org/
John Wilander (editor)
Apple, Inc
Email: wilander@apple.com
 End of changes. 55 change blocks. 
116 lines changed or deleted 166 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/