NPAPI:ClearSiteData

Status

Under consideration.

Contributors

• Last modified: December 7, 2010
• Authors: Julian Reschke (greenbytes), Dan Witte (Mozilla), Bernhard Bauer (Chromium), Rajesh Gwalani (Adobe), Josh Aas (Mozilla)

Overview

Allows browsers to request that plugins clear locally stored private data.

Specification

The following method will allow browsers to request that plugins clear data. Note that plugins (but no instances) must be initialized and function tables retrieved in order to call this method.

NPError NPP_ClearSiteData(
   PRUint64 flags,         // what type of data to clear
   const char* site,       // site for which to clear data
   PRUInt64 maxAge         // max. age of information in seconds
);

• The flags argument is a bit mask representing the type(s) of data to clear.

#define NP_CLEAR_ALL                 0            /* Clear All data */
#define NP_CLEAR_COOKIES             1 << 0       /* Clear cookies */
#define NP_CLEAR_SITE_PREFS          1 << 1       /* Clear site preferences */
#define NP_CLEAR_BROWSING_HISTORY    1 << 2       /* Clear browsing history */
#define NP_CLEAR_DOWNLOAD_HISTORY    1 << 3       /* Clear download history */
#define NP_CLEAR_FORM_HISTORY        1 << 4       /* Clear form and search history */
#define NP_CLEAR_CACHE               1 << 5       /* Clear cache */
#define NP_CLEAR_PASSWORDS           1 << 6       /* Clear saved passwords */
#define NP_CLEAR_LOGINS              1 << 7       /* Clear active logins */
#define NP_CLEAR_PLUGIN_STORAGE      1 << 8       /* Clear plugin local storage */

• The site argument is interpreted as follows:
  • The preferred form for this argument is an origin: scheme + "://" + domain + optional port preceded by ":" (e.g. "http://mozilla.org:80").
  • If a hostname of the form "foo.com", data in the "foo.com" domain and all subdomains should be cleared. In this form domains must be in lowercase normalized ACE-encoded form, they must not contain a trailing dot, must not contain a scheme, port, or other such fields, and must contain at least one embedded dot.
  • If an IP address (either IPv4 or IPv6), data for that IP should be cleared.
  • If NULL, all site-specific data and more generic data on browsing history (for instance, number of sites visited) should be cleared.
• The maxAge argument is the maximum age in seconds of data to clear, inclusive. If maxAge is 0, no data is cleared. If maxAge is the maximum unsigned 64-bit integer, all data is cleared.

The following new NPError values will be available for return from NPP_ClearSiteData.

// can't clear by time range
#define NPERR_TIMERANGE_NOT_SUPPORTED (NPERR_BASE + 14)
// can't clear by origin
#define NPERR_LIMITBYORIGIN_NOT_SUPPORTED (NPERR_BASE + 15)
// malformed 'origin' string
#define NPERR_MALFORMED_ORIGIN (NPERR_BASE + 16)

If site data is in use by an instance of the plugin when NPP_ClearSiteData is called then it is up to the plugin to do the right thing.

Open Issues

• Do we need a method for discovering what site data the plugin has? Mozilla and Apple have expressed a strong desire for this.
• What is the syntax for an IPv6 address in site? As per RFC 3986 "IP-literal" ([1])?
• What should be returned if a plugin does not support a requested type of data. What if it does not exist? What if clearing that data is not possible or simply not supported for any reason (data remains)?
• Make sure the requirements for parsing the origin argument are not too much of a burden for plugin developers.
• Suggested that we document what happens when a particular plug-in is keyed by domain, not origin. This way for simplicity purposes the API can handle both models, regardless of how it's keyed. The specific suggestion is that for a plug-in that stores domain-keyed info, that plug-in will just strip the protocol and (optional) port.

Notes

Overview of current UIs

Type	Firefox	IE	Opera	Safari	Chrome
Browsing History	yes	yes	yes	yes	yes
Download History	yes	yes	yes	yes	yes
Form History	yes	yes	?	yes	yes
Search History	yes	?	?	?	?
Cookies	yes	yes	temporary/all	yes	yes
Cache	yes	yes	yes	yes	yes
Active Logins	yes	yes	"password manager"	yes	yes
Site Preferences	yes	?	?	?	?

In addition, IE has "InPrivate Filtering Data" (what is this?)

In addition, Opera has "delete password protected pages and data" and "bookmark visited times".

In addition, Safari has "webpage preview images", "website icons" and "top sites"

Parameters	Firefox	IE	Opera	Safari	Chrome
Time Range	yes	no	no	no	yes
By Site	yes (context menu in history)	??	??	??	??

Type of Data

• things the user enters, except for credentials (form data)
• credentials
• things cached by the UA (pages, preview images, icons)
• local data stored by the server / web application (cookies, HTML5 local storage, Flash/Silverlight local storage)
• history information (bookmarks, visited URIs)
• settings specific to a site (for instance, preferences with respect to privacy, script disabling...)

Time range

Several UAs offer to restrict the clear operation to a time range such as "today" or "last week".

Site/URI

Firefox supports "forget about this site". Other UAs do not appear to support this.

Existing Discussion and Documentation

Mail thread on plugin-futures: https://mail.mozilla.org/private/plugin-futures/2010-January/001150.html

In particular, Lloyd Hilaiel proposed an alternate approach where plugins would store everything in a standard filesystem based layout, so the UA itself can do the clearing. See https://mail.mozilla.org/private/plugin-futures/2010-January/001156.html

Flash Local Storage: http://www.macromedia.com/support/documentation/en/flashplayer/help/help02.html

Firefox issue - clearing local storage with time range: https://bugzilla.mozilla.org/show_bug.cgi?id=527667