localStorage
object
provides
a
Storage
object
for
an
origin
.
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.
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
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.
Support: namevalue-storage Chrome for Android 69+ Chrome 4+ iOS Safari 3.2+ UC Browser for Android 11.8+ Firefox 3.5+ IE 8+ Opera Mini None Safari 4+ Edge 12+ Samsung Internet 4+ Opera 10.5+ Android Browser 2.1+
Source: caniuse.com
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.
length
Returns the number of key/value pairs currently present in the list associated with the object.
key
(
n
)
Returns the name of the n th key in the list, or null if n is greater than or equal to the number of key/value pairs in the object.
getItem
(
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.
setItem
(
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.)
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.
clear
()
Empties the list associated with the object of all key/value pairs, if there are any.
The
length
attribute
must
return
the
number
of
key/value
pairs
currently
present
in
the
list
associated
with
the
object.
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.)
If
n
is
greater
than
or
equal
to
the
number
of
key/value
pairs
in
the
object,
then
this
method
must
return
null.
The
supported
property
names
on
a
Storage
object
are
the
keys
of
each
key/value
pair
currently
present
in
the
list
associated
with
the
object,
in
the
order
that
the
keys
were
last
added
to
the
storage
area.
The
getItem(
key
)
method
must
return
the
current
value
associated
with
the
given
key
.
If
the
given
key
does
not
exist
in
the
list
associated
with
the
object
then
this
method
must
return
null.
The
setItem(
key
,
value
)
method
must
first
check
if
a
key/value
pair
with
the
given
key
already
exists
in
the
list
associated
with
the
object.
If it does not, then a new key/value pair must be added to the list, with the given key and with its value set to value .
If the given key does exist in the list, and its value is not equal to value , then it must have its value updated to value . If its previous value is equal to value , then the method must do nothing.
If
it
couldn't
set
the
new
value,
the
method
must
throw
a
"
QuotaExceededError
"
DOMException
exception.
The
removeItem(
key
)
method
must
cause
the
key/value
pair
with
the
given
key
to
be
removed
from
the
list
associated
with
the
object,
if
it
exists.
If
no
item
with
that
key
exists,
the
method
must
do
nothing.
The
setItem()
and
removeItem()
methods
must
be
atomic
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.
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.
When
the
setItem()
,
removeItem()
,
and
clear()
methods
are
invoked,
events
are
fired
on
the
Window
relevant
global
objects
of
other
Document
s
objects
that
can
access
the
newly
stored
or
removed
data,
as
defined
in
the
sections
on
the
sessionStorage
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.
sessionStorage
attribute
interface mixin WindowSessionStorage {
readonly attribute Storage sessionStorage;
};
Window
includes
WindowSessionStorage
;
The
sessionStorage
attribute
represents
the
set
of
storage
areas
specific
to
the
current
top-level
browsing
context
.
sessionStorage
Returns
the
Storage
object
associated
with
that
origin's
session
storage
area.
Each top-level browsing context has a unique set of session storage areas, one for each origin .
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 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 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 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
must
be
created,
and
then
that
is
the
Document
's
assigned
session
storage
area.
A
Document
's
assigned
storage
area
does
not
change
during
the
lifetime
of
a
Document
.
In
the
case
of
an
iframe
being
moved
to
another
Document
,
the
nested
browsing
context
is
destroyed
and
a
new
one
created.
The
sessionStorage
attribute
must
return
a
Storage
object
associated
with
the
Document
's
assigned
session
storage
area.
Each
Document
object
must
have
a
separate
object
for
its
Window
relevant
global
object
's
sessionStorage
attribute.
While creating a new browsing context , the session storage area is sometimes copied over.
When
the
setItem()
,
removeItem()
,
and
clear()
methods
are
called
on
a
Storage
object
x
that
is
associated
with
a
session
storage
area,
if
the
methods
did
not
throw
an
exception
or
"do
nothing"
as
defined
above,
then
for
every
Document
object
whose
Window
relevant
global
object
object's
's
sessionStorage
attribute's
Storage
object
is
associated
with
the
same
storage
area,
other
than
x
,
send
a
storage
notification
.
localStorage
attribute
interface mixin WindowLocalStorage {
readonly attribute Storage localStorage;
};
Window
includes
WindowLocalStorage
;
The
localStorage
object
provides
a
Storage
object
for
an
origin
.
localStorage
Returns
the
Storage
object
associated
with
that
origin's
local
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).
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
attribute
is
accessed,
the
user
agent
must
run
the
following
steps,
which
are
known
as
the
Storage
object
initialization
steps
:
If
the
request
violates
a
policy
decision
(e.g.
if
the
user
agent
is
configured
to
not
allow
the
page
to
persist
data),
the
user
agent
may
throw
a
"
SecurityError
"
DOMException
instead
of
returning
a
Storage
object
If
the
Document
's
origin
is
an
opaque
origin
,
then
throw
a
"
SecurityError
"
DOMException
.
Check
to
see
if
the
user
agent
has
allocated
a
local
storage
area
for
the
origin
of
the
associated
Document
of
the
Window
object
on
which
the
attribute
was
accessed.
If
it
has
not,
create
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
Window
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
Window
relevant
global
object
object's
's
localStorage
attribute's
Storage
object
is
associated
with
the
same
storage
area,
other
than
x
,
send
a
storage
notification
.
The
localStorage
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
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.
storage
event
The
storage
event
is
fired
on
a
Document
's
Window
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
storage
at
the
Document
object's
Window
object,
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
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
Window
relevant
global
object
of
the
target
Document
that
represents
the
same
kind
of
Storage
area
as
was
affected
(i.e.
session
or
local).
StorageEvent
interface
[Exposed=Window,
Constructor(DOMString type, optional StorageEventInit eventInitDict)]
interface StorageEvent : Event {
readonly attribute DOMString? key;
readonly attribute DOMString? oldValue;
readonly attribute DOMString? newValue;
readonly attribute USVString url;
readonly attribute Storage? storageArea;
};
dictionary StorageEventInit : EventInit {
DOMString? key = null;
DOMString? oldValue = null;
DOMString? newValue = null;
USVString url = "";
Storage? storageArea = null;
};
key
Returns the key of the storage item being changed.
oldValue
Returns the old value of the key of the storage item whose value is being changed.
newValue
Returns the new value of the key of the storage item whose value is being changed.
url
Returns the URL of the document whose storage item changed.
storageArea
Returns
the
Storage
object
that
was
affected.
The
key
,
oldValue
,
newValue
,
url
,
and
storageArea
attributes
must
return
the
values
they
were
initialized
to.
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.
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:
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.
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.
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]
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.
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.
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.
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.
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.
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.
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.