1. Introduction
This section is not normative.
Web applications store data locally on a user’s computer in order to provide functionality while the user is offline, and to increase performance when the user is online. These local caches have significant advantages for both users and developers, but present risks as well.
A user’s data is both sensitive and valuable; web developers ought to take reasonable steps to protect it. One such step would be to encrypt data before storing it. Another would be to remove data from the user’s machine when it is no longer necessary (for example, when the user signs out of the application, or deletes their account).
Site authors can remove data from a number of storage mechanisms via
JavaScript, but others are difficult to deal with reliably. Consider cookies,
for instance, which can be partially cleared via JavaScript access to
document.cookie
. HttpOnly
cookies, however, can only
be removed via a number of Set-Cookie
headers in an HTTP
response. This, of course, requires exhaustive knowledge of all the cookies
set for a host, which can be complicated to ascertain. Cache is still harder;
no imperative interface to a browser’s network cache exists, period.
This document defines a new mechanism to deal with removing data from these and other types of local storage, giving web developers the ability to clear out a user’s local cache of data via the Clear-Site-Data HTTP response header.
1.1. Examples
1.1.1. Signing Out
https://supersecretsocialnetwork.example.com/logout
, and the
site author wishes to ensure that locally stored data is removed as a
result.
They can do so by sending the following HTTP header in the response:
Clear-Site-Data: *
1.1.2. Targeted Clearing
https://megacorp.example.com/logout
. Megacorp has a large
number of services available as subdomains, so many that it’s not entirely
clear which of them would be safe to clear as a response to a logout action.
One option would be to simply clear everything, and deal with the fallout.
Megacorp’s CEO, however, once lost hours and hours of progress in "Irate
Ibexes" due to inadvertent site-data clearing, and so refuses to allow such
a sweeping impact to the site’s users.
The developers know, however, that the "Minus" application is certainly safe to clear out. They can target this specific subdomain by including a request to that subdomain as part of the logout landing page (ideally as a CORS-enabled, CSRF-protected POST):
fetch("https://minus.megacorp.example.com/clear-site-data", { method: "POST", mode: "cors", headers: new Headers({ "CSRF": "[insert sekrit token here]" }) });
That endpoint would return proper CORS headers in response to that request’s preflight, and would return the following header for the actual request:
Clear-Site-Data: *; includeSubdomains
1.1.3. Keep Critical Cookies
https://ads-are-awesome.example.com/optout
. The site author
wishes to remove DOM-accessible data which might contain tracking
information, but needs to ensure that the opt-out cookie which the user has
just received isn’t wiped along with it.
They can do so by sending the following HTTP header in the response, which includes all the types except for "cookies":
Clear-Site-Data: storage; executionContexts; cache; includeSubdomains
1.1.4. Kill Switch
They can reduce the risk of a persistent client-side XSS by sending the following HTTP header in a response to wipe out local sources of data:
Clear-Site-Data: *; includeSubdomains
Note: Installing a Service Worker guarantees that a request will go out to a server every ~24 hours. That update ping would be a wonderful time to send a header like this one in case of catastrophe. [SERVICE-WORKERS]
1.2. Goals
Generally, the goal is to allow web developers more control over the data stored locally by a user agent for their origins. In particular, developers should be able to reliably ensure the following:
-
Data stored in an origin’s client-side storage mechanisms like [INDEXEDDB], WebSQL, Filesystem,
localStorage
, andsessionStorage
is cleared. -
Cookies for an origin’s host are removed [RFC6265].
-
Web Workers (dedicated and shared) running for an origin are terminated.
-
Service Workers registered for an origin are terminated and deregistered.
-
Resources from an origin are removed from the user agent’s local cache.
-
All of the above can be propagated to an origin’s host’s subdomains.
-
All of the above can be propagated to the HTTP version of an HTTPS origin.
-
None of the above can be bypassed by a maliciously active document that retains interesting data in memory, and rewrites it if it’s cleared.
2. Clearing Site Data
Developers may instruct a user agent to clear various types of relevant data in two ways: an HTTP response header, and a JavaScript API:
2.1.
The Clear-Site-Data
HTTP Response Header Field
The Clear-Site-Data
HTTP response header field
sends a signal to the user agent that it ought to remove all data
of a certain set of types. The header is represented by the following ABNF
[RFC5234]:
Clear-Site-Data = 1#option option = parameter *( OWS ";" [ OWS parameter ] ) parameter = key [ BWS "=" value ] key = token value = token / quoted-string
Note: The BWS, OWS, token, and quoted-string rules as well as the #rule list extension are defined in [RFC7230].
The Clear-Site-Data header’s value is essentially a semicolon-delimited
list of "[key]=[value]
" pairs which define the kinds of data to
be cleared for a given response.
The following subsections define an initial set of known parameter components; future versions of this document may define additional parameter components: the ABNF above is intentionally generic and extensible to make room for these future values, and user agents MUST ignore unknown parameter components when parsing the header’s value.
2.1.1.
The cache
parameter
The cache
parameter indicates that the server wishes
to remove locally cached data associated with the origin of a
particular response’s url
. This includes the network
cache, of course, but will also remove data from various other caches
which a user agent implements (prerendered pages, script caches, shader
caches, etc.).
The value component of this parameter is currently ignored, if present.
Implementation details are in §3.4.3 Clear cache for origin with subdomain state, as part of the larger §3.2 Clear data for response and §3.3 Clear data for storageRequestOptions algorithms.
https://example.com/clear
,
the following header will cause caches associated with the origin
https://example.com
to be cleared:
Clear-Site-Data: cache
2.1.2.
The cookies
parameter
The cookies
parameter indicates that the server wishes
to remove cookies associated with the origin of a particular
response’s url
. This includes the network cache, of
course, but will also remove data from various other caches which a user agent
implements (prerendered pages, script caches, shader caches, etc.).
The value component of this parameter is currently ignored, if present.
Implementation details are in §3.4.3 Clear cache for origin with subdomain state, as part of the larger §3.2 Clear data for response and §3.3 Clear data for storageRequestOptions algorithms.
https://example.com/clear
,
the following header will cause cookies associated with the origin
https://example.com
to be cleared:
Clear-Site-Data: cookies
2.1.3.
The storage
parameter
The storage
parameter indicates that the server
wishes to remove locally stored data associated with the origin of a
particular response’s url
. This includes storage
mechansims such as (localStorage
, sessionStorage
, [INDEXEDDB],
[WEBDATABASE], etc), as well as tangentially related mechainsm such as
service worker registrations.
The value component of this parameter is currently ignored, if present.
Implementation details are in §3.4.5 Clear DOM-accessible storage for origin with subdomain state, as part of the larger §3.2 Clear data for response and §3.3 Clear data for storageRequestOptions algorithms.
https://example.com/clear
,
the following header will cause DOM-accessible storage for the origin
https://example.com
to be cleared:
Clear-Site-Data: storage
2.1.4.
The executionContexts
parameter
The executionContexts
parameter indicates that the
server wishes to neuter and reload execution contexts currently rendering the
origin of a particular response’s url
.
The value component of this parameter is currently ignored, if present.
Implementation details are in §3.4.1 Neuter browsing contexts matching origin with subdomain state, as part of the larger §3.2 Clear data for response and §3.3 Clear data for storageRequestOptions algorithms.
https://example.com/clear
,
the following header will cause execution contexts displaying the origin
https://example.com
to be neutered and reloaded:
Clear-Site-Data: executionContexts
2.1.5.
The includeSubdomains
parameter
The includeSubdomains
parameter expands the scope of
the storage type parameters to include any origin whose host
is a
subdomain of the response’s url
's host
.
Implementation details are included as part of the larger §3.2 Clear data for response and §3.3 Clear data for storageRequestOptions algorithms.
https://example.com/clear
,
the following header will cause caches associated with the origins
https://example.com
and
https://anythingelse.example.com
to be cleared:
Clear-Site-Data: cache; includeSubdomains
2.1.6.
The *
parameter
The *
parameter is syntactic sugar which includes all
storage type parameters. That is:
Clear-Site-Data: *
has the same meaning as:
Clear-Site-Data: cache; cookies; storage; executionContexts
2.2. JavaScript API
This might live more cleanly in [STORAGE].
navigator.storage.clear();
If they only wished to clear the otherwise inaccessible cache for the current origin and all subdomains:
navigator.storage.clear({ types: [ "cache" ], includeSubdomains: true });
enum StorageClearType { "cache", "cookies", "storage", "executionContexts" }; dictionary StorageClearOptions { sequence<StorageClearType> types; boolean includeSubdomains = false; }; partial interface StorageManager { Promise<void> clear(StorageClearOptions options); };
- clear(options)
-
Clears data based on the values in the options argument.
Returns a Promise that resolves when clearing is complete. If no
types
are specified, all data types will be cleared.Parameter Type Nullable Optional Description options StorageClearOptions ✘ ✘ The data to clear. Arguments for the StorageManager.clear(options) method.
2.3. Fetch Integration
Monkey patching! Talk with Anne.
If the Clear-Site-Data
header is present in an HTTP
response, then data MUST be cleared before rendering the response to
the user. That is, before step #9 in the current main fetch algorithm,
execute the following step:
-
If response’s header list contains a header named
Clear-Site-Data
, then execute §3.2 Clear data for response on response.
Note: This happens after Set-Cookie
headers are
processed. If we clear cookies, we clear all of them. This is intentional, as
removing only certain cookies might leave an application in an indeterminate
and vulnerable state. Removing specific cookies is best done via expiration
using the Set-Cookie
header.
3. Algorithms
3.1. Parsing
3.1.1. Which data types ought to be removed for response?
-
If response does not contain a
Clear-Site-Data
header, return an empty list. -
Let parameters be the list of parameter components in the value of response’s
Clear-Site-Data
header. -
If parameters contains a parameter whose key is
*
:-
Append
cache
,cookies
,storage
, andexecutionContexts
to remove. -
Return remove.
-
-
Otherwise, let remove be an empty list.
-
For each parameter in parameters:
-
Return remove.
3.1.2. Should subdomains' data be cleared for response
-
If response does not contain a
Clear-Site-Data
header, returnExclude Subdomains
. -
Let parameters be the list of parameter components in the value of response’s
Clear-Site-Data
header. -
If parameters contains a parameter whose key is
includeSubdomains
, returnInclude Subdomains
. -
Otherwise, return
Exclude Subdomains
.
3.1.3. Does origin match origin to clear and subdomain state
Given an origin, the origin to clear, and the "include subdomains"
flag, return Matches
or Does Not
Match
.
-
If either origin or origin to clear are globally unique identifiers, return
Does Not Match
. -
If origin is the same as origin to clear, return
Matches
. -
If subdomain state is
Exclude Subdomains
, returnDoes Not Match
. -
Let labels to clear be the
host
component of origin to clear split into labels, and labels be thehost
component of origin, split into labels. -
If labels does not have more entries than labels to clear, return
Does Not Match
. -
While labels to clear is not empty:
-
If the final entry of labels to clear does not exactly match the final entry of labels, return
Does Not Match
. -
Remove the final entry of labels to clear, and of labels.
-
-
Return
Matches
.
3.2. Clear data for response
Given a response (response), this algorithm parses the
Clear-Site-Data
header to determine what needs to be
cleared, which origins are affected, and then executes those requests.
-
If response’s
URL
is a priori insecure, skip the remaining steps of this algorithm.Some have suggested that this might not be a restriction we want (see Martin Thomson’s public-webappsec post on the topic, for example).
-
Let types be the result of §3.1.1 Which data types ought to be removed for response? executed on response.
-
Let subdomain state be the result of §3.1.2 Should subdomains' data be cleared for response executed on response.
-
Execute §3.4 Clear types for origin with subdomain state on types, response’s
url
's origin, and subdomain state.
Note: Especially given the cross-context implications, user agents are are encouraged to give web developers some mechanism by which the clearing operation can be debugged. This might take the form of a console message or timeline entry indicating success.
3.3. Clear data for storageRequestOptions
Given a StorageClearOptions
(options), this algorithm
determines what needs to be cleared, returns a Promise, and executes the
request asynchronously.
-
If the incumbent settings object is not a secure context, return a
Promise
rejected withNotSupportedError
. -
Let promise be a newly created
Promise
object. -
Return promise, and execute the remaining steps asynchronously.
-
Let subdomain state be
Include Subdomains
if options'includeSubdomains
property istrue
, andExclude Subdomains
otherwise. -
Let types be an empty list.
-
If options'
types
is an empty sequence:-
Append
cache
,cookies
,storage
, andexecutionContexts
to types.
-
-
Otherwise, for each
StorageClearType
type in options'types
property:-
Append type to types.
-
-
Execute §3.4 Clear types for origin with subdomain state on types, the incumbent settings object’s origin, and subdomain state.
-
Resolve promise with
undefined
.
3.4. Clear types for origin with subdomain state
-
If types contains "
executionContexts
", execute §3.4.1 Neuter browsing contexts matching origin with subdomain state on origin, with subdomain state. -
If types contains "
cookies
", execute §3.4.4 Clear cookies for origin with subdomain state on origin, with subdomain state. -
If types contains "
storage
", execute §3.4.5 Clear DOM-accessible storage for origin with subdomain state on origin, with subdomain state. -
If types contains "
cache
", execute §3.4.3 Clear cache for origin with subdomain state on origin, with subdomain state. -
If types contains "
executionContexts
", execute §3.4.2 Reload browsing contexts matching origin with subdomain state on origin, with subdomain state.
3.4.1. Neuter browsing contexts matching origin with subdomain state
Given an origin (origin) and a subdomain state
of either Include Subdomains
or Exclude
Subdomains
, this algorithm walks through the set of browsing
contexts which the user agent knows about, and sandboxes each in order
to prevent them from recreating cleared data (from in-memory JavaScript
variables, for instance). Once data is cleared, the affected browsing
contexts will be hard-reloaded, as defined in §3.4.2 Reload browsing contexts matching origin with
subdomain state:
-
For each context in the user agent’s set of browsing contexts:
-
Let document be context’s active document.
-
While document is an
iframe srcdoc
document, let document be the active document of document’s browsing context container. -
If §3.1.3 Does origin match origin to clear and subdomain state returns
Matches
when executed on context’s origin, origin, andsubdomain state
:-
Parse a sandboxing directive using the empty string as the input, and document’s active sandboxing flag set as the output.
-
-
3.4.2. Reload browsing contexts matching origin with subdomain state
Given an origin (origin) and a subdomain state
of either Include Subdomains
or Exclude
Subdomains
, this algorithm walks through the set of browsing
contexts which the user agent knows about and reloads each of them:
-
For each context in the user agent’s set of browsing contexts:
-
Let document be context’s active document.
-
While document is an
iframe srcdoc
document, let document be the active document of document’s browsing context container. -
If §3.1.3 Does origin match origin to clear and subdomain state returns
Matches
when executed on context’s origin, origin, andsubdomain state
:-
Navigate context to document’s
URL
with replacement enabled and exceptions enabled. The source browsing context is context. This is a reload-triggered navigation.
-
-
3.4.3. Clear cache for origin with subdomain state
Given an origin (origin) and a subdomain state
of either Include Subdomains
or Exclude
Subdomains
, this algorithm removes data from the user agent’s
local caches that matches the origin and subdomain state.
-
Let host be origin’s
host
, canonicalized as per Section 5.1.2 of [RFC6265]. -
If subdomain state is
Include Subdomains
, then let cache list be the set of entries from the network cache whosetarget URI
’shost
domain-matches host when canonicalized as per Section 5.1.2 of [RFC6265] -
Otherwise, subdomain state is
Exclude Subdomains
, so let cache list be the set of entries from the network cache whosetarget URI
host
is identical to host when canonicalized as per Section 5.1.2 or [RFC6265]. -
Remove each entry in cache list from the network cache.
-
If a user agent implements caches beyond a pure network cache, it MUST remove all entries from those caches which match origin and subdomain state.
We’re dealing with the network cache here, as defined in [RFC7234], but that’s not nearly everything a user agent caches. How hand-wavey with the vendor-specific section can we be? For instance, Chrome clears out prerendered pages, script caches, WebGL shader caches, WebRTC bits and pieces, address bar suggestion caches, various networking bits that aren’t representations (HSTS/HPKP, SCDH, etc.). Perhaps [STORAGE] will make this clearer?
3.4.4. Clear cookies for origin with subdomain state
Given an origin (origin) and a subdomain state
of either Include Subdomains
or Exclude
Subdomains
, this algorithm removes cookies from the user agent’s
cookie store whose domain
attribute matches the origin
and subdomain state.
Note: This algorithm assumes that the user agent has implemented a cookie store (as discussed in Section 5.3 of [RFC6265]), which offers the ability to retrieve a list of cookies by host, and to remove individual cookies.
-
Let host be origin’s
host
, canonicalized as per Section 5.1.2 of [RFC6265]. -
If subdomain state is
Include Subdomains
, then let cookie list be the set of cookies from the cookie store whosedomain
attribute is domain-matched by host.Note: The direction of the matching is important. If
subdomain.example.com
delivers theClear-Site-Data
header and includes subdomains, then cookies for.another.subdomain.example.com
will be cleared, but cookies for.example.com
will not. -
Otherwise, subdomain state is
Exclude Subdomains
, so let cookie list be the set of cookies from the cookie store whosedomain
attribute is identical to host. -
Remove each cookie in cookie list from the cookie store.
3.4.5. Clear DOM-accessible storage for origin with subdomain state
-
For each area in the user agent’s set of local storage areas [HTML]:
-
If §3.1.3 Does origin match origin to clear and subdomain state returns
Matches
when executed on area’s origin, origin, andsubdomain state
:
-
-
For each area in the user agent’s set of session storage areas [HTML]:
-
If §3.1.3 Does origin match origin to clear and subdomain state returns
Matches
when executed on area’s origin, origin, andsubdomain state
:
-
-
For each database in the user agent’s set of Indexed Databases [INDEXEDDB]:
-
If §3.1.3 Does origin match origin to clear and subdomain state returns
Matches
when executed on database’s origin, origin, andsubdomain state
:-
Set database’s delete pending flag to
true
. -
For each connection in the set of all
IDBDatabase
objects connected to database:-
Execute the database closing steps on connection.
-
-
Execute the database deletion steps on database, passing in database’s origin and name.
-
-
-
For each database in the user agent’s set of WebSQL databases [WEBDATABASE]:
-
If §3.1.3 Does origin match origin to clear and subdomain state returns
Matches
when executed on database’s origin, origin, andsubdomain state
:-
Delete database.
The [WEBDATABASE] spec is fairly unhelpful here with regard to deletion details.
-
-
-
For each registration in the user agent’s set of registered service worker registrations:
-
If §3.1.3 Does origin match origin to clear and subdomain state returns
Matches
when executed on registration’s scope URL’s origin, origin, andsubdomain state
:-
Execute
unregister()
on registration.
-
-
We still need to spell out Filesystems, Dedicated Workers, Shared Workers, etc. (This isn’t an exhaustive list. We should fix that too.)
How do we say something about plugins here? Point out to NPP_ClearSiteData?
4. Privacy Considerations
4.1. Web developers control the timing.
If triggered at appropriate times, Clear-Site-Data
can
increase a user’s privacy and security by clearing sensitive data from their
user agent. However, note that the web developer (and not the user)
is in control of when the clearing event is triggered. Even assuming a
non-malicious site author, users can’t rely on data being cleared at any
particular point, nor are users in control of what data types are cleared.
If a user wishes to ensure that site data is indeed cleared at some specific point, they ought to rely on the data-clearing functionality offered by their user agent.
At a bare minimum, user agents OUGHT TO (in the [RFC6919] sense of the words) offer the same functionality to users that they offer to web developers. Ideally, they will offer significantly more than we can offer at a platform level (clearing browsing history, for example).
4.2. Remnants of data on disk.
While Clear-Site-Data
triggers a clearing event in a
user’s agent, it is difficult to make promises about the state of a user’s
disk after a clearing event takes place. In particular, note that it is up
to the user agent to ensure that all traces of a site’s date is actually
removed from disk, which can be a herculean task (consider virtual memory,
as a good example of a larger issue).
In short, most user agents implement data clearing as "best effort", but can’t promise an exhaustive wipe.
If a user wishes to ensure that site data does not remain on disk, the best way to do so is to use a browsing mode that promises not to intentionally write data to disk (Chrome’s "Incognito", Internet Explorer’s "InPrivate", etc). These modes will do a better job of keeping data off disk, but are still subject to a number of limitations at the edges.
5. IANA Considerations
The permanent message header field registry should be updated with the following registration: [RFC3864]
5.1. Clear-Site-Data
- Header field name
- Clear-Site-Data
- Applicable protocol
- http
- Status
- standard
- Author/Change controller
- W3C
- Specification document
- This specification (See §2.1 The Clear-Site-Data HTTP Response Header Field)
6. Acknowledgements
Michal Zalewski proposed a variant of this concept, and Mark Knichel helped refine the details.