1. 11 Web storage
    1. 11.1 Introduction
    2. 11.2 The API
      1. 11.2.1 The Storage interface
      2. 11.2.2 The sessionStorage attribute getter
      3. 11.2.3 The localStorage attribute 11.2.4 The storage event getter
      4. 11.2.4.1 11.2.4 The StorageEvent interface
      11.3 Disk space
    3. 11.4 11.3 Privacy
      1. 11.4.1 11.3.1 User tracking
      2. 11.4.2 11.3.2 Sensitivity of data
    4. 11.5 11.4 Security
      1. 11.5.1 11.4.1 DNS spoofing attacks
      2. 11.5.2 11.4.2 Cross-directory attacks
      3. 11.5.3 11.4.3 Implementation risks

11 Web storage

11.1 Introduction

This section is non-normative.

This specification introduces two related mechanisms, similar to HTTP session cookies, for storing name-value pairs on the client side. [COOKIES]

The first is designed for scenarios where the user is carrying out a single transaction, but could be carrying out multiple transactions in different windows at the same time.

Cookies don't really handle this case well. For example, a user could be buying plane tickets in two different windows, using the same site. If the site used cookies to keep track of which ticket the user was buying, then as the user clicked from page to page in both windows, the ticket currently being purchased would "leak" from one window to the other, potentially causing the user to buy two tickets for the same flight without really noticing.

To address this, this specification introduces the sessionStorage IDL attribute. getter. Sites can add data to the session storage, and it will be accessible to any page from the same site opened in that window.

For example, a page could have a checkbox that the user ticks to indicate that they want insurance: 

<label>
 <input type="checkbox" onchange="sessionStorage.insurance = checked ? 'true' : ''">
  I want insurance on this trip.
</label>

A later page could then check, from script, whether the user had checked the checkbox or not: 


if
(sessionStorage.insurance)
{
...
}

If the user had multiple windows opened on the site, each one would have its own individual copy of the session storage object.

The second storage mechanism is designed for storage that spans multiple windows, and lasts beyond the current session. In particular, Web applications might wish to store megabytes of user data, such as entire user-authored documents or a user's mailbox, on the client side for performance reasons.

Again, cookies do not handle this case well, because they are transmitted with every request.

The localStorage IDL attribute getter is used to access a page's local storage area.

The site at example.com can display a count of how many times the user has loaded its page by putting the following at the bottom of its page: 

<p>
  You have viewed this page
  <span id="count">an untold number of</span>
  time(s).
</p>
<script>
  if (!localStorage.pageLoadCount)
    localStorage.pageLoadCount = 0;
  localStorage.pageLoadCount = parseInt(localStorage.pageLoadCount) + 1;
  document.getElementById('count').textContent = localStorage.pageLoadCount;
</script>

Each site has its own separate storage area.

The localStorage getter provides access to shared state. This specification does not define the interaction with other browsing contexts in a multiprocess user agent, and authors are encouraged to assume that there is no locking mechanism. A site could, for instance, try to read the value of a key, increment its value, then write it back out, using the new value as a unique identifier for the session; if the site does this twice in two different browser windows at the same time, it might end up using the same "unique" identifier for both sessions, with potentially disastrous effects.

11.2 The API

11.2.1 The Storage interface 

[Exposed=Window]
interface Storage {
  readonly attribute unsigned long length;
  DOMString? key(unsigned long index);
  getter DOMString? getItem(DOMString key);
  setter void setItem(DOMString key, DOMString value);
  deleter void removeItem(DOMString key);
  void clear();
};
Each Storage object provides access to a list of key/value pairs, which are sometimes called items. Keys are strings. Any string (including the empty string) is a valid key. Values are similarly strings. Each Storage object is associated with a list of key/value pairs when it is created, as defined in the sections on the sessionStorage and localStorage attributes. Multiple separate objects implementing the Storage interface can all be associated with the same list of key/value pairs simultaneously.
storage . length

Returns the number of key/value pairs currently present in the list associated with the object. pairs.

storage . key ( n )

Returns the name of the n th key in the list, key, or null if n is greater than or equal to the number of key/value pairs in the object. pairs.

value = storage . getItem ( key )
value = storage [ key ]

Returns the current value associated with the given key , or null if the given key does not exist in the list associated with the object. exist.

storage . setItem ( key , value )
storage [ key ] = value

Sets the value of the pair identified by key to value , creating a new key/value pair if none existed for key previously.

Throws a " QuotaExceededError " DOMException exception if the new value couldn't be set. (Setting could fail if, e.g., the user has disabled storage for the site, or if the quota has been exceeded.)

Dispatches a storage event on Window objects holding an equivalent Storage object.

storage . removeItem ( key )
delete storage [ key ]

Removes the key/value pair with the given key from the list associated with the object, , if a key/value pair with the given key exists.

Dispatches a storage event on Window objects holding an equivalent Storage object.

storage . clear ()

Empties the list associated with the object of Removes all key/value pairs, if there are any.

Dispatches a storage event on Window objects holding an equivalent Storage object.

A Storage object has an associated:

map
A storage proxy map .
type
" local " or " session ".

To reorder a Storage object storage , reorder storage 's map 's entries in an implementation-defined manner.

Unfortunate as it is, iteration order is not defined and can change upon most mutations.

To broadcast a Storage object storage , given a key , oldValue , and newValue , run these steps:

  1. Let url be storage 's relevant global object 's associated Document 's URL .

  2. Let remoteStorages be all Storage objects excluding storage whose:

    and, if type is " session ", whose relevant settings object 's browsing session is storage 's relevant settings object 's browsing session .

  3. For each remoteStorage of remoteStorages : queue a global task on the DOM manipulation task source given remoteStorage 's relevant global object to fire an event named storage at remoteStorage 's relevant global object , using StorageEvent , with key initialized to key , oldValue initialized to oldValue , newValue initialized to newValue , url initialized to url , and storageArea initialized to remoteStorage .

    The Document object associated with the resulting task is not necessarily fully active , but events fired on such objects are ignored by the event loop until the Document becomes fully active again.

The length attribute must getter steps are to return the number of key/value pairs currently present in the list associated with the object. this 's map 's size .

The key( n ) method must return the name of the n th key in the list. The order of keys is user-agent defined, but must be consistent within an object so long as the number of keys doesn't change. (Thus, adding or removing a key may change the order of the keys, but merely changing the value of an existing key must not.) steps are:

  1. If n is greater greather than or equal to this 's map 's size , then return null.

  2. Let keys be the number result of key/value pairs in running get the object, then keys on this method must return null. 's map .

  3. Return keys [ n ].

The supported property names on a Storage object storage are the keys result of each key/value pair currently present in the list associated with the object, in the order that running get the keys were last added to the on storage area. 's map .

The getItem( key ) method must return the current value associated with the given key . steps are:

  1. If the given this 's map [ key ] does not exist in the list associated with the object , then this method must return null.

  2. Return this 's map [ key ].

The setItem( key , value ) method must first check if a key/value pair with the given are:

  1. Let oldValue be null.

  2. Let reorder be true.

  3. If this 's map [ key already ] exists in the list associated with the object. :

    1. If it does not, then a new key/value pair must be added to the list, with the given Set key oldValue and with its value set to this 's map [ value . key ].

    2. If the given key oldValue does exist in the list, and its value is not equal to value , then it must have its value updated to return.

    3. Set value . If its previous value is equal reorder to false.

  4. If value , cannot be stored, then the method must do nothing. If it couldn't set the new value, the method must throw a " QuotaExceededError " DOMException exception.

  5. Set this 's map [ key ] to value .

  6. If reorder is true, then reorder this .

  7. Broadcast this with key , oldValue , and value .

The removeItem( key ) method must cause the key/value pair with the given steps are:

  1. If this 's map [ key ] does not exist , then return null.

  2. Set oldValue to be removed from the list associated with the object, if it exists. If no item with that this 's map [ key exists, the method must do nothing. ].

  3. The setItem() Remove this 's map [ key ].

  4. and

    removeItem() Reorder this .

  5. methods must be atomic

    Broadcast this with respect to failure. In the case of failure, the method does nothing. That is, changes to the data storage area must either be successful, or the data storage area must not be changed at all. key , oldValue , and null.

The clear() method must atomically cause the list associated with the object to be emptied of all key/value pairs, if there are any. If there are none, then the method must do nothing. steps are:

When the
    setItem()
  1. ,

    removeItem() Clear , and clear() this 's map .

  2. methods are invoked, events are fired on the relevant global objects of other

    Document Broadcast objects that can access the newly stored or removed data, as defined in the sections on the sessionStorage this with null, null, and localStorage attributes. This specification does not require that the above methods wait until the data has been physically written to disk. Only consistency in what different scripts accessing the same underlying list of key/value pairs see is required. null.

11.2.2 The sessionStorage attribute getter 

interface mixin WindowSessionStorage {
  readonly attribute Storage sessionStorage;
};

Window

includes

WindowSessionStorage

;
window . sessionStorage

Returns the Storage object associated with that window 's origin's session storage area.

Throws a " SecurityError " DOMException if the Document 's origin is an opaque origin or if the request violates a policy decision (e.g., if the user agent is configured to not allow the page to persist data).

A Document object has an associated session storage holder , which is null or a Storage object. It is initially null.

(This is a tracking vector.) The sessionStorage attribute represents the set of storage areas specific to the current top-level browsing context . getter steps are:

    window .
  1. sessionStorage

    If this 's associated Document Returns the Storage object associated with that origin's 's session storage area. Each top-level browsing context holder has a unique set of is non-null, then return this 's associated Document 's session storage areas, one for each origin holder .

  2. User agents should not expire data from a browsing context's session storage areas, but may do so when the user requests that such data Let map be deleted, or when the UA detects that it has limited storage space, or for security reasons. User agents should always avoid deleting data while a script that could access that data is running. When result of running obtain a top-level browsing context is destroyed (and therefore permanently inaccessible to the user) the data stored in its session storage areas can be discarded bottle map with it, as the API described in this specification provides no way for that data to ever be subsequently retrieved. The lifetime of a browsing context can be unrelated to the lifetime of the actual user agent process itself, as the user agent can support resuming sessions after a restart. When a new Document is created in a browsing context which has a top-level browsing context , the user agent must check to see if that top-level browsing context has a session storage area for that document's origin . If it does, then that is the Document 's assigned session storage area. If it does not, a new storage area for that document's origin relevant settings object must be created, and then that is the Document " sessionStorage 's assigned session storage area. A Document ".

  3. 's assigned storage area does not change during the lifetime of

    If map is failure, then throw a Document " SecurityError " . In the case of an iframe DOMException being moved to another Document .

  4. , its nested browsing context is destroyed and a new one created.

    The sessionStorage attribute must return Let storage be a new Storage object associated with the Document whose map is map .

  5. Set this 's assigned session storage area. Each associated Document object must have a separate object for its relevant global object 's sessionStorage session storage holder to storage .

  6. attribute.

    Return storage .

While creating a new auxiliary browsing context , the session storage area is copied over.

When the

setItem() 11.2.3 The localStorage , getter removeItem() , and 

interface mixin WindowLocalStorage {
  readonly attribute Storage localStorage;
};

Window

includes

WindowLocalStorage

;

clear()
window . localStorage methods are called on a

Returns the Storage object x that is associated with a session window 's origin's local storage area, if the methods did not throw an exception or "do nothing" as defined above, then for every Document area.

Throws a " SecurityError object whose relevant global object " 's sessionStorage DOMException attribute's if the Storage Document object 's origin is associated with an opaque origin or if the same storage area, other than x , send request violates a storage notification . policy decision (e.g., if the user agent is configured to not allow the page to persist data).

11.2.3 The

A localStorage Document attribute object has an associated local storage holder , which is null or a Storage { readonly attribute ; }; Window includes WindowLocalStorage ; object. It is initially null.

(This is a tracking vector.) The localStorage object provides a Storage object for an origin . getter steps are:

window . localStorage

  1. Returns the Storage If this object 's associated with that origin's local storage area. Throws a " SecurityError " DOMException Document if the Document 's origin is an opaque origin or if the request violates a policy decision (e.g. if the user agent is configured to not allow the page to persist data). User agents must have a set of local storage areas, one for each origin . User agents should expire data from the local storage areas only for security reasons or when requested to do so by the user. User agents should always avoid deleting data while a script that could access that data is running. When the localStorage holder attribute is accessed, the user agent must run the following steps, which are known as the non-null, then return this 's associated Storage Document object initialization steps : 's local storage holder .

  2. If the request violates a policy decision (e.g. if the user agent is configured to not allow the page to persist data), Let map be the user agent may throw result of running obtain a " SecurityError " local storage bottle map DOMException with this instead of returning a Storage 's relevant settings object and " localStorage object ".

  3. If the Document 's origin map is an opaque origin , failure, then throw a " SecurityError " DOMException .

  4. Check to see if the user agent has allocated a local Let storage area for the origin of the associated Document of the Window object on which the attribute was accessed. If it has not, create be a new storage area for that origin . Return the Storage object associated with that origin's local storage area. Each Document object must have a separate object for its relevant global object 's localStorage attribute. When the setItem() , removeItem() , and clear() methods are called on a Storage object x that is associated with a local storage area, if the methods did not throw an exception or "do nothing" as defined above, then for every Document object whose relevant global object 's localStorage attribute's Storage map object is associated with the same storage area, other than x , send a storage notification . The localStorage map .

  5. attribute provides access to shared state. This specification does not define the interaction with other browsing contexts in a multiprocess user agent, and authors are encouraged to assume that there is no locking mechanism. A site could, for instance, try to read the value of a key, increment its value, then write it back out, using the new value as a unique identifier for the session; if the site does

    Set this twice in two different browser windows at the same time, it might end up using the same "unique" identifier for both sessions, with potentially disastrous effects. 11.2.4 The storage event The storage event is fired on a 's associated Document object's relevant global object when a storage area changes , as described in the previous two sections ( for session storage , for local storage ). When a user agent is to send a storage notification for a Document , the user agent must queue a task to fire an event named 's local storage holder at the Document object's relevant global object , using StorageEvent . Such a Document object is not necessarily fully active , but events fired on such objects are ignored by the event loop until the Document becomes fully active again. The task source for these tasks is the DOM manipulation task source . If the event is being fired due to an invocation of the setItem() or removeItem() methods, the event must have its key attribute initialized to the name of the key in question, its oldValue attribute initialized to the old value of the key in question, or null if the key is newly added, and its newValue attribute initialized to the new value of the key in question, or null if the key was removed. Otherwise, if the event is being fired due to an invocation of the clear() method, the event must have its key , oldValue , and newValue storage .

  6. attributes initialized to null.

    In addition, the event must have its url attribute initialized to the URL of the document whose Storage object was affected; and its storageArea attribute initialized to the Storage object from the relevant global object of the target Document that represents the same kind of Storage area as was affected (i.e. session or local). Return storage .

11.2.4.1 11.2.4 The StorageEvent interface 

[Exposed=Window]
interface StorageEvent : Event {
  constructor(DOMString type, optional StorageEventInit eventInitDict = {});
  readonly attribute DOMString? key;
  readonly attribute DOMString? oldValue;
  readonly attribute DOMString? newValue;
  readonly attribute USVString url;
  readonly attribute Storage? storageArea;
  void initStorageEvent(DOMString type, optional boolean bubbles = false, optional boolean cancelable = false, optional DOMString? key = null, optional DOMString? oldValue = null, optional DOMString? newValue = null, optional USVString url = "", optional Storage? storageArea = null);
};
dictionary StorageEventInit : EventInit {
  DOMString? key = null;
  DOMString? oldValue = null;
  DOMString? newValue = null;
  USVString url = "";
  Storage? storageArea = null;
};
event . key

Returns the key of the storage item being changed.

event . oldValue

Returns the old value of the key of the storage item whose value is being changed.

event . newValue

Returns the new value of the key of the storage item whose value is being changed.

event . url

Returns the URL of the document whose storage item changed.

event . storageArea

Returns the Storage object that was affected.

The key , oldValue , newValue , url , and storageArea attributes must return the values they were initialized to.

The initStorageEvent() method must initialize the event in a manner analogous to the similarly-named initEvent() method. [DOM]

11.3 Disk space User agents should limit the total amount of space allowed for storage areas, because hostile authors could otherwise use this feature to exhaust the user's available disk space. User agents should guard against sites storing data under their origin's other affiliated sites, e.g. storing up to the limit in a1.example.com, a2.example.com, a3.example.com, etc, circumventing the main example.com storage limit. User agents may prompt the user when quotas are reached, allowing the user to grant a site more space. This enables sites to store many user-created documents on the user's computer, for instance. User agents should allow users to see how much space each domain is using. A mostly arbitrary limit of five megabytes per origin is suggested. Implementation feedback is welcome and will be used to update this suggestion in the future. For predictability, quotas should be based on the uncompressed size of data stored.

11.4 11.3 Privacy

11.4.1 11.3.1 User tracking

A third-party advertiser (or any entity capable of getting content distributed to multiple sites) could use a unique identifier stored in its local storage area to track a user across multiple sessions, building a profile of the user's interests to allow for highly targeted advertising. In conjunction with a site that is aware of the user's real identity (for example an e-commerce site that requires authenticated credentials), this could allow oppressive groups to target individuals with greater accuracy than in a world with purely anonymous Web usage.

There are a number of techniques that can be used to mitigate the risk of user tracking:

Blocking third-party storage

User agents may restrict access to the localStorage objects to scripts originating at the domain of the active document of the top-level browsing context , for instance denying access to the API for pages from other domains running in iframe s.

Expiring stored data

User agents may, possibly in a manner configured by the user, automatically delete stored data after a period of time.

For example, a user agent could be configured to treat third-party local storage areas as session-only storage, deleting the data once the user had closed all the browsing contexts that could access it.

This can restrict the ability of a site to track a user, as the site would then only be able to track the user across multiple sessions when they authenticate with the site itself (e.g. by making a purchase or logging in to a service).

However, this also reduces the usefulness of the API as a long-term storage mechanism. It can also put the user's data at risk, if the user does not fully understand the implications of data expiration.

Treating persistent storage as cookies

If users attempt to protect their privacy by clearing cookies without also clearing data stored in the local storage area, sites can defeat those attempts by using the two features as redundant backup for each other. User agents should present the interfaces for clearing these in a way that helps users to understand this possibility and enables them to delete data in all persistent storage features simultaneously. [COOKIES]

Site-specific safelisting of access to local storage areas

User agents may allow sites to access session storage areas in an unrestricted manner, but require the user to authorize access to local storage areas.

Origin-tracking of stored data

User agents may record the origins of sites that contained content from third-party origins that caused data to be stored.

If this information is then used to present the view of data currently in persistent storage, it would allow the user to make informed decisions about which parts of the persistent storage to prune. Combined with a blocklist ("delete this data and prevent this domain from ever storing data again"), the user can restrict the use of persistent storage to sites that they trust.

Shared blocklists

User agents may allow users to share their persistent storage domain blocklists.

This would allow communities to act together to protect their privacy.

While these suggestions prevent trivial use of this API for user tracking, they do not block it altogether. Within a single domain, a site can continue to track the user during a session, and can then pass all this information to the third party along with any identifying information (names, credit card numbers, addresses) obtained by the site. If a third party cooperates with multiple sites to obtain such information, a profile can still be created.

However, user tracking is to some extent possible even with no cooperation from the user agent whatsoever, for instance by using session identifiers in URLs, a technique already commonly used for innocuous purposes but easily repurposed for user tracking (even retroactively). This information can then be shared with other sites, using visitors' IP addresses and other user-specific data (e.g. user-agent headers and configuration settings) to combine separate sessions into coherent user profiles.

11.4.2 11.3.2 Sensitivity of data

User agents should treat persistently stored data as potentially sensitive; it's quite possible for e-mails, calendar appointments, health records, or other confidential documents to be stored in this mechanism.

To this end, user agents should ensure that when deleting data, it is promptly deleted from the underlying storage.

11.5 11.4 Security

11.5.1 11.4.1 DNS spoofing attacks

Because of the potential for DNS spoofing attacks, one cannot guarantee that a host claiming to be in a certain domain really is from that domain. To mitigate this, pages can use TLS. Pages using TLS can be sure that only the user, software working on behalf of the user, and other pages using TLS that have certificates identifying them as being from the same domain, can access their storage areas.

11.5.2 11.4.2 Cross-directory attacks

Different authors sharing one host name, for example users hosting content on the now defunct geocities.com , all share one local storage object. There is no feature to restrict the access by pathname. Authors on shared hosts are therefore urged to avoid using these features, as it would be trivial for other authors to read the data and overwrite it.

Even if a path-restriction feature was made available, the usual DOM scripting security model would make it trivial to bypass this protection and access the data from any path.

11.5.3 11.4.3 Implementation risks

The two primary risks when implementing these persistent storage features are letting hostile sites read information from other domains, and letting hostile sites write information that is then read from other domains.

Letting third-party sites read data that is not supposed to be read from their domain causes information leakage , For example, a user's shopping wishlist on one domain could be used by another domain for targeted advertising; or a user's work-in-progress confidential documents stored by a word-processing site could be examined by the site of a competing company.

Letting third-party sites write data to the persistent storage of other domains can result in information spoofing , which is equally dangerous. For example, a hostile site could add items to a user's wishlist; or a hostile site could set a user's session identifier to a known ID that the hostile site can then use to track the user's actions on the victim site.

Thus, strictly following the origin model described in this specification is important for user security.