1. Introduction
Interesting web applications generally end up with a large number of web-exposed endpoints that might reveal sensitive data about a user, or take action on a user’s behalf. Since users' browsers can be easily convinced to make requests to those endpoints, and to include the users' ambient credentials (cookies, privileged position on an intranet, etc), applications need to be very careful about the way those endpoints work in order to avoid abuse.
Being careful turns out to be hard in some cases ("simple" CSRF), and practically impossible in others (cross-site search, timing attacks, etc). The latter category includes timing attacks based on the server-side processing necessary to generate certain responses, and length measurements (both via web-facing timing attacks and passive network attackers).
It would be helpful if servers could make more intelligent decisions about whether or not to respond
to a given request based on the way that it’s made in order to mitigate the latter category. For
example, it seems pretty unlikely that a "Transfer all my money" endpoint on a bank’s server would
expect to be referenced from an img
tag, and likewise unlikely that evil.com
is going to be
making any legitimate requests whatsoever. Ideally, the server could reject these requests a priori rather than delivering them to the application backend.
Here, we describe a mechanims by which user agents can enable this kind of decision-making by adding additional context to outgoing requests. By delivering metadata to a server in a set of fetch metadata headers, we enable applications to quickly reject requests based on testing a set of preconditions. That work can even be lifted up above the application layer (to reverse proxies, CDNs, etc) if desired.
1.1. Examples
A request generated by a picture
element would result in a request containing the following
HTTP request headers:
Sec-Fetch-Dest: image Sec-Fetch-Mode: no-cors Sec-Fetch-Site: cross-site
A top-level navigation from https://example.com
to https://example.com/
caused by a user’s click
on an in-page link would result in a request containing the following HTTP request header:
Sec-Fetch-Dest: document Sec-Fetch-Mode: navigate Sec-Fetch-Site: same-origin Sec-Fetch-User: ?1
2. Fetch Metadata Headers
The following sections define several fetch metadata headers, each of which exposes an interesting request attribute to a server.
2.1. The Sec-Fetch-Dest
HTTP Request Header
In only one current engine.
Opera67+Edge80+
Edge (Legacy)NoneIENone
Firefox for AndroidNoneiOS SafariNoneChrome for Android80+Android WebView80+Samsung InternetNoneOpera MobileNone
The Sec-Fetch-Dest
HTTP request header exposes a request's destination to a server. It is a Structured Header whose value MUST be a token. [I-D.ietf-httpbis-header-structure] Its ABNF is:
Sec-Fetch-Dest = sh-token
Valid Sec-Fetch-Dest
values include "audio
", "audioworklet
", "document
", "embed
",
"empty
", "font
", "frame
", "iframe
", "image
", "manifest
", "object
", "paintworklet
",
"report
", "script
", "serviceworker
", "sharedworker
", "style
", "track
", "video
",
"worker
", "xslt
".
frame
and iframe
haven’t landed in Fetch yet. <https://github.com/whatwg/fetch/issues/948>
In order to support forward-compatibility with as-yet-unknown request types, servers SHOULD ignore this header if it contains an invalid value.
//fetch()
's destination is the empty string: Sec-Fetch-Dest: empty //<img>
's destination is "image" Sec-Fetch-Dest: image //new Worker()
's destination is "worker" Sec-Fetch-Dest: worker // Top-level navigations' destinations are "document" Sec-Fetch-Dest: document //<iframe>
navigations' destinations are "iframe" Sec-Fetch-Dest: iframe
Sec-Fetch-Dest
header for a request r:
-
Assert: r’s url is a potentially trustworthy URL.
-
Let header be a Structured Header whose value is a token.
-
If r’s destination is the empty string, set header’s value to the string "
empty
". Otherwise, set header’s value to r’s destination.Note: We map Fetch’s empty string destination onto an explicit "
empty
" token in order to simplify processing. -
Set a structured field value `
Sec-Fetch-Dest
`/header in r’s header list.
2.2. The Sec-Fetch-Mode
HTTP Request Header
In only one current engine.
Opera63+Edge79+
Edge (Legacy)NoneIENone
Firefox for AndroidNoneiOS SafariNoneChrome for Android76+Android WebView76+Samsung InternetNoneOpera Mobile54+
The Sec-Fetch-Mode
HTTP request header exposes a request's mode to a server. It is a Structured Header whose value is a token. [I-D.ietf-httpbis-header-structure] Its ABNF is:
Sec-Fetch-Mode = sh-token
Valid Sec-Fetch-Mode
values include "cors
", "navigate
", "no-cors
", "same-origin
",
and "websocket
". In order to support forward-compatibility with as-yet-unknown request types,
servers SHOULD ignore this header if it contains an invalid value.
Sec-Fetch-Mode
header for a request r:
-
Assert: r’s url is a potentially trustworthy URL.
-
Let header be a Structured Header whose value is a token.
-
Set header’s value to r’s mode.
-
Set a structured field value `
Sec-Fetch-Mode
`/header in r’s header list.
2.3. The Sec-Fetch-Site
HTTP Request Header
In only one current engine.
Opera63+Edge79+
Edge (Legacy)NoneIENone
Firefox for AndroidNoneiOS SafariNoneChrome for Android76+Android WebView76+Samsung InternetNoneOpera Mobile54+
The Sec-Fetch-Site
HTTP request header exposes the relationship
between a request initiator’s origin and its target’s origin. It is a Structured Header whose value is a token. [I-D.ietf-httpbis-header-structure] Its ABNF is:
Sec-Fetch-Site = sh-token
Valid Sec-Fetch-Site
values include "cross-site
", "same-origin
", "same-site
", and "none
".
In order to support forward-compatibility with as-yet-unknown request types, servers SHOULD ignore
this header if it contains an invalid value.
Sec-Fetch-Site
header for a request r:
-
Assert: r’s url is a potentially trustworthy URL.
-
Let header be a Structured Header whose value is a token.
-
Set header’s value to
same-origin
. -
If r is a navigation request that was explicitly caused by a user’s interaction with the user agent (by typing an address into the user agent directly, for example, or by clicking a bookmark, etc.), then set header’s value to
none
.Note: See § 4.3 Directly User-Initiated Requests for more detail on this somewhat poorly-defined step.
-
If header’s value is not
none
, then for each url in r’s url list: -
Set a structured field value `
Sec-Fetch-Site
`/header in r’s header list.
2.4. The Sec-Fetch-User
HTTP Request Header
In only one current engine.
Opera63+Edge79+
Edge (Legacy)NoneIENone
Firefox for AndroidNoneiOS SafariNoneChrome for Android76+Android WebView76+Samsung InternetNoneOpera Mobile54+
The Sec-Fetch-User
HTTP request header exposes whether or not a navigation request was triggered by user activation. It is a Structured Header whose
value is a boolean. [I-D.ietf-httpbis-header-structure] Its ABNF is:
Sec-Fetch-User = sh-boolean
Note: The header is delivered only for navigation requests, and only when its value is true
.
It might be reasonable to expand the headers' scope in the future to include subresource requests
generally if we can spell out some use cases that would be improved by exposing that information
(and if we can agree on ways to define that status for all the subresource request types we’d be
interested in), but for the moment, navigation requests have clear use cases, and seem
straightforward to define interoperably.
Sec-Fetch-User
header for a request r:
-
Assert: r’s url is a potentially trustworthy URL.
-
If r is not a navigation request, or if r’s user activation is
false
, return. -
Let header be a Structured Header whose value is a token.
-
Set header’s value to
true
. -
Set a structured field value `
Sec-Fetch-User
`/header in r’s header list.
3. Integration with Fetch and HTML
To support Sec-Fetch-User
, request needs to be taught about requests which were
triggered by user activation:
Monkeypatching [FETCH]:
A request has a boolean user activation. Unless stated otherwise, it is
false
.Note: This is only used for navigation requests.
This should be defined in Fetch. <https://github.com/whatwg/fetch/issues/993>
This flag could be populated from HTML’s process a navigate fetch algorithm, perhaps by inserting the following step after the current algorithm’s step 2:
Monkeypatching [HTML]:
If sourceBrowsingContext’s
WindowProxy
's[[Window]]
value has transient activation, then set request’s user activation to true.
This should be defined in HTML. <https://github.com/whatwg/html/issues/5203>
-
If r’s url is not an potentially trustworthy URL, return.
Fetch will call into the algorithm above from within its "HTTP-network-or-cache fetch" algorithm. Please consult that specification for integration details [FETCH].
This should be called from in Fetch. <https://github.com/whatwg/fetch/issues/993>
4. Security and Privacy Considerations
4.1. Redirects
The user agent will send a Sec-Fetch-Site
header along with each request in a
redirect chain. The header’s value will shift in the presence of cross-origin or cross-site
redirection in order to mitigate confusion.
The algorithm to set the Sec-Fetch-Site
header walks the request's entire url list, and will send cross-site
if any URL in the list is cross-site to the
request’s current url, same-site
only if all URLs in the list are same-site with the
request’s current url, and same-origin
only if all URLs in the list are same-origin
with the request’s current url.
For example, if https://example.com/
requests https://example.com/redirect
, the initial
request’s Sec-Fetch-Site
value would be same-origin
. If that response redirected to https://subdomain.example.com/redirect
, that request’s Sec-Fetch-Site
value would be same-site
(as https://subdomain.example.com/
and https://example.com/
have the same
registrable domain). If that response redirected to https://example.net/redirect
, that
request’s Sec-Fetch-Site
value would be cross-site
(as https://example.net/
is not
same-site with https://example.com/
and https://subdomain.example.com/
). If that response
redirects all the way back to https://example.com/
, the final request’s Sec-Fetch-Site
value would still be cross-site
(as the redirect chain includes https://example.net/
, which is
still not same-site with the other URLs.
4.2. The Sec-
Prefix
Each of the headers defined in this document is prefixed with Sec-
, which makes them all forbidden header names, and therefore unmodifiable from JavaScript. This will prevent
malicious websites from convincing user agents to send forged metadata along with requests,
which should give sites a bit more confidence in their ability to respond reasonably to
the advertised information.
4.3. Directly User-Initiated Requests
When setting the Sec-Fetch-Site
header, user agents are asked to
distinguish between navigation requests that are "explicitly caused by a user’s interaction". This
somewhat poorly defined phrase is pulled from HTML, which suggests that "A user agent may provide various ways for the user to explicitly cause a browsing context to
navigate, in addition to those defined in this specification."
The goal is to distinguish between "webby" navigations that are controlled by a given (potentially
malicious!) website (e.g. links, the window.location
setter, form submissions, etc.), and those
that are not (e.g. user interaction with a user agent’s address bar, bookmarks, etc). The former
will be delivered with a Sec-Fetch-Site
header whose value is same-origin
, same-site
, or cross-site
, as appropriate. The latter will be distinguished with a value of none
, as no
specific site is actually responsible for the request, and it makes sense to allow servers to treat
them as trusted, as they somehow represent a user’s direct intent.
Each user agent is likely to have a distinct set of interactions which might fall into one or the other category, and it will be hard to share an automated test suite for these cases. Still, it would be ideal to align on behavior for those which are likely to be common. Sme examples follow:
-
Navigation from the address bar: In the general case, this kind of navigation should be treated as directly user-initiated, and include
Sec-Fetch-Site: none
. It may be reasonable for user agents to include heuristics around pasting values into the address bar (especially if the "copy" action can be traced to a specific origin), and to treat such navigations distinctly from those which the user types themselves. -
Navigation from user agent UI (bookmarks, new tab page, etc): A user’s interaction with links in user agent UI should be treated similarly to their input in the user agent’s address bar, including
Sec-Fetch-Site: none
to demarcate the navigation as user-initiated. -
Navigation from a link’s context menu (e.g. "Open in new window"): as the link’s target is controlled by the page on which the link is present, user agents should treat the navigation as site-controlled, and set the
Sec-Fetch-Site
header appropriately for the relationship between the site which controls the link and the site which is being opened. -
Ctrl-click on a link: the same arguments and conclusions apply here as apply to a link’s context menu, discussed directly above.
-
Navigation through history (e.g. a user agent’s "back" button):
-
Drag-and-drop: It seems reasonable to distinguish behavior here based upon the source of the dragged content. If content is dragged from a tab, the user agent should be able to ascertain its origin, and set
Sec-Fetch-Site
accordingly. If content is dragged from elsewhere (the user agent’s bookmark bar, another app entirely, etc), thenSec-Fetch-Site: none
may be appropriate.
5. Deployment Considerations
5.1. Vary
If a given endpoint’s response depends upon the values the client delivers in a Fetch metadata header, developers should be careful to include an appropriate Vary
header [RFC7231], in order to ensure that caches handle the response appropriately. For example, Vary: Accept-Encoding, Sec-Fetch-Site
.
5.2. Header Bloat
An earlier version of this document defined a single Sec-Metadata
header, whose contents were
a dictionary. Subsequent discussion (as well as Mark Nottingham’s excellent [mnot-designing-headers]) shifted the design away from a single dictionary to a series of simple
headers, each of which contains only a single token. This design should perform significantly better
under HTTP’s current HPACK compression algorithms.
Further discussion on the topic can be found on the review thread in w3ctag/design-reviews#280.
6. IANA Considerations
The permanent message header field registry should be updated with the following registrations for Fetch metadata headers: [RFC3864]
6.1. Sec-Fetch-Dest
Registration
- Header field name
-
Sec-Fetch-Dest
- Applicable protocol
-
http
- Status
-
standard
- Author/Change controller
-
Me
- Specification document
-
This specification (See § 2.1 The Sec-Fetch-Dest HTTP Request Header)
6.2. Sec-Fetch-Mode
Registration
- Header field name
-
Sec-Fetch-Mode
- Applicable protocol
-
http
- Status
-
standard
- Author/Change controller
-
Me
- Specification document
-
This specification (See § 2.2 The Sec-Fetch-Mode HTTP Request Header)
6.3. Sec-Fetch-Site
Registration
- Header field name
-
Sec-Fetch-Site
- Applicable protocol
-
http
- Status
-
standard
- Author/Change controller
-
Me
- Specification document
-
This specification (See § 2.3 The Sec-Fetch-Site HTTP Request Header)
6.4. Sec-Fetch-User
Registration
- Header field name
-
Sec-Fetch-User
- Applicable protocol
-
http
- Status
-
standard
- Author/Change controller
-
Me
- Specification document
-
This specification (See § 2.4 The Sec-Fetch-User HTTP Request Header)
7. Acknowledgements
Thanks to Anne van Kesteren, Artur Janc, Dan Veditz, Łukasz Anforowicz, Mark Nottingham, and Roberto Clapis, who all provided substantial support in the design of this mechanism.