HTML 5

Draft Recommendation — 7 July 2008

5.10 Structured client-side storage

5.10.1 Storing name/value pairs

5.10.1.1. Introduction

This section is non-normative.

This specification introduces two related mechanisms, similar to HTTP session cookies, for storing structured data on the client side. [RFC2109] [RFC2965]

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 DOM 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 he wants insurance:

<label>
 <input type="checkbox" onchange="sessionStorage.insurance = checked">
 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 may 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 DOM 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, 10) + 1;
  document.getElementById('count').textContent = localStorage.pageLoadCount;
</script>

Each site has its own separate storage area.

Storage areas (both session storage and local storage) store strings. To store structured data in a storage area, you must first convert it to a string.

5.10.1.2. The Storage interface
interface Storage {
  readonly attribute unsigned long length;
  [IndexGetter] DOMString key(in unsigned long index);
  [NameGetter] DOMString getItem(in DOMString key);
  [NameSetter] void setItem(in DOMString key, in DOMString data);
  [XXX] void removeItem(in DOMString key); 
  void clear();
};

Each Storage object provides access to a list of key/value pairs, which are sometimes called items. Keys and values are strings. Any string (including the empty string) is a valid key.

To store more structured data, authors may consider using the SQL interfaces instead.

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.

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 nth key in the list. The order of keys is user-agent defined, but must be consistent within an object between changes to the number of keys. (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 less than zero or greater than or equal to the number of key/value pairs in the object, then this method must raise an INDEX_SIZE_ERR exception.

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 value.

If the given key does exist in the list, then it must have its value updated to the value given in the value argument.

If it couldn't set the new value, the method must raise an INVALID_ACCESS_ERR exception. (Setting could fail if, e.g., the user has disabled storage for the domain, or if the quota has been exceeded.)

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. 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.

When the setItem(), removeItem(), and clear() methods are invoked, events are fired on other HTMLDocument objects that can access the newly stored or removed data, as defined in the sections on the sessionStorage and localStorage attributes.

5.10.1.3. The sessionStorage attribute

The sessionStorage attribute represents the set of storage areas specific to the current top-level browsing context.

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 may support resuming sessions after a restart.

When a new HTMLDocument is created, the user agent must check to see if the document's top-level browsing context has allocated a session storage area for that document's origin. If it has not, a new storage area for that document's origin must be created.

The Storage object for the document's associated Window object's sessionStorage attribute must then be associated with that origin's session storage area for that top-level browsing context.

When a new top-level browsing context is created by cloning an existing browsing context, the new browsing context must start with the same session storage areas as the original, but the two sets must from that point on be considered separate, not affecting each other in any way.

When a new top-level browsing context is created by a script in an existing browsing context, or by the user following a link in an existing browsing context, or in some other way related to a specific HTMLDocument, then the session storage area of the origin of that HTMLDocument must be copied into the new browsing context when it is created. From that point on, however, the two session storage areas must be considered separate, not affecting each other in any way.

When the setItem(), removeItem(), and clear() methods are called on a Storage object x that is associated with a session storage area, then in every HTMLDocument object whose Window object's sessionStorage attribute's Storage object is associated with the same storage area, other than x, a storage event must be fired, as described below.

5.10.1.4. The localStorage attribute

The localStorage object provides a Storage object for an origin.

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. Data stored in local storage areas should be considered potentially user-critical. It is expected that Web applications will use the local storage areas for storing user-written documents.

When the localStorage attribute is accessed, the user agent must check to see if it has allocated local storage area for the origin of the browsing context within which the script is running. If it has not, a new storage area for that origin must be created.

The user agent must then create a Storage object associated with that origin's local storage area, and return it.

When the setItem(), removeItem(), and clear() methods are called on a Storage object x that is associated with a local storage area, then in every HTMLDocument object whose Window object's localStorage attribute's Storage object is associated with the same storage area, other than x, a storage event must be fired, as described below.

5.10.1.5. The storage event

The storage event is fired in an HTMLDocument when a storage area changes, as described in the previous two sections (for session storage, for local storage).

When this happens, the user agent must dispatch an event with the name storage, with no namespace, which does not bubble but is cancelable, and which uses the StorageEvent, at the body element of each active HTMLDocument object affected.

If the event is being fired due to an invocation of the setItem() or removeItem() methods, the event must have its key attribute set to the name of the key in question, its oldValue attribute set to the old value of the key in question, or null if the key is newly added, and its newValue attribute set 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 set to null.

In addition, the event must have its url attribute set to the address of the page whose Storage object was affected, and its source attribute set to the Window object of the browsing context that that document is in, if the two documents are in the same unit of related browsing contexts, or null otherwise.

5.10.1.5.1. Event definition
interface StorageEvent : Event {
  readonly attribute DOMString key;
  readonly attribute DOMString oldValue;
  readonly attribute DOMString newValue;
  readonly attribute DOMString url;
  readonly attribute Window source;
  void initStorageEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString keyArg, in DOMString oldValueArg, in DOMString newValueArg, in DOMString urlArg, in Window sourceArg);
  void initStorageEventNS(in DOMString namespaceURI, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString keyArg, in DOMString oldValueArg, in DOMString newValueArg, in DOMString urlArg, in Window sourceArg);
};

The initStorageEvent() and initStorageEventNS() methods must initialise the event in a manner analogous to the similarly-named methods in the DOM3 Events interfaces. [DOM3EVENTS]

The key attribute represents the key being changed.

The oldValue attribute represents the old value of the key being changed.

The newValue attribute represents the new value of the key being changed.

The url attribute represents the address of the document that changed the key.

The source attribute represents the Window that changed the key.

5.10.1.6. Threads

Multiple browsing contexts must be able to access the local storage areas simultaneously in a predictable manner. Scripts must not be able to detect any concurrent script execution.

This is required to guarantee that the length attribute of a Storage object never changes while a script is executing, other than in a way that is predictable by the script itself.

There are various ways of implementing this requirement. One is that if a script running in one browsing context accesses a local storage area, the UA blocks scripts in other browsing contexts when they try to access the local storage area for the same origin until the first script has executed to completion. (Similarly, when a script in one browsing context accesses its session storage area, any scripts that have the same top level browsing context and the same origin would block when accessing their session storage area until the first script has executed to completion.) Another (potentially more efficient but probably more complex) implementation strategy is to use optimistic transactional script execution. This specification does not require any particular implementation strategy, so long as the requirement above is met.

5.10.2 Database storage

5.10.2.1. Introduction

This section is non-normative.

...

5.10.2.2. Databases

Each origin has an associated set of databases. Each database has a name and a current version. There is no way to enumerate or delete the databases available for a domain from this API.

Each database has one version at a time, a database can't exist in multiple versions at once. Versions are intended to allow authors to manage schema changes incrementally and non-destructively, and without running the risk of old code (e.g. in another browser window) trying to write to a database with incorrect assumptions.

The openDatabase() method returns a Database object. The method takes four arguments: a database name, a database version, a display name, and an estimated size, in bytes, of the data that will be stored in the database.

The openDatabase() method must use and create databases from the origin of the active document of the browsing context of the Window object on which the method was invoked.

If the database version provided is not the empty string, and the database already exists but has a different version, then the method must raise an INVALID_STATE_ERR exception.

The user agent may also raise a security exception in case the request violates a policy decision (e.g. if the user agent is configured to not allow the page to open databases).

Otherwise, if the database version provided is the empty string, or if the database doesn't yet exist, or if the database exists and the version provided to the openDatabase() method is the same as the current version associated with the database, then the method must return a Database object representing the database that has the name that was given. If no such database exists, it must be created first.

All strings including the empty string are valid database names. Database names are case-sensitive.

Implementations can support this even in environments that only support a subset of all strings as database names by mapping database names (e.g. using a hashing algorithm) to the supported set of names.

User agents are expected to use the display name and the estimated database size to optimize the user experience. For example, a user agent could use the estimated size to suggest an initial quota to the user. This allows a site that is aware that it will try to use hundreds of megabytes to declare this upfront, instead of the user agent prompting the user for permission to increase the quota every five megabytes.

interface Database {
  void transaction(in SQLTransactionCallback callback);
  void transaction(in SQLTransactionCallback callback, in SQLTransactionErrorCallback errorCallback);
  void transaction(in SQLTransactionCallback callback, in SQLTransactionErrorCallback errorCallback, in VoidCallback successCallback);

  readonly attribute DOMString version;
  void changeVersion(in DOMString oldVersion, in DOMString newVersion, in SQLTransactionCallback callback, in SQLTransactionErrorCallback errorCallback, in VoidCallback successCallback);
};

interface SQLTransactionCallback {
  void handleEvent(in SQLTransaction transaction);
};

interface SQLTransactionErrorCallback {
  void handleEvent(in SQLError error);
};

The transaction() method takes one or two arguments. When called, the method must immediately return and then asynchronously run the transaction steps with the transaction callback being the first argument, the error callback being the second argument, if any, the success callback being the third argument, if any, and with no preflight operation or postflight operation.

The version that the database was opened with is the expected version of this Database object. It can be the empty string, in which case there is no expected version — any version is fine.

On getting, the version attribute must return the current version of the database (as opposed to the expected version of the Database object).

The changeVersion() method allows scripts to atomically verify the version number and change it at the same time as doing a schema update. When the method is invoked, it must immediately return, and then asynchronously run the transaction steps with the transaction callback being the third argument, the error callback being the fourth argument, the success callback being the fifth argument, the preflight operation being the following:

  1. Check that the value of the first argument to the changeVersion() method exactly matches the database's actual version. If it does not, then the preflight operation fails.

...and the postflight operation being the following:

  1. Change the database's actual version to the value of the second argument to the changeVersion() method.
  2. Change the Database object's expected version to the value of the second argument to the changeVersion() method.
5.10.2.3. Executing SQL statements

The transaction() and changeVersion() methods invoke callbacks with SQLTransaction objects.

typedef sequence<Object> ObjectArray;

interface SQLTransaction {
  void executeSql(in DOMString sqlStatement);
  void executeSql(in DOMString sqlStatement, in ObjectArray arguments);
  void executeSql(in DOMString sqlStatement, in ObjectArray arguments, in SQLStatementCallback callback);
  void executeSql(in DOMString sqlStatement, in ObjectArray arguments, in SQLStatementCallback callback, in SQLStatementErrorCallback errorCallback);
};

interface SQLStatementCallback {
  void handleEvent(in SQLTransaction transaction, in SQLResultSet resultSet);
};

interface SQLStatementErrorCallback {
  boolean handleEvent(in SQLTransaction transaction, in SQLError error);Or should these arguments be the other way around? Either way we're inconsistent with _something_. What should we be consistent with?
};

When the executeSql(sqlStatement, arguments, callback, errorCallback) method is invoked, the user agent must run the following algorithm. (This algorithm is relatively simple and doesn't actually execute any SQL — the bulk of the work is actually done as part of the transaction steps.)

  1. If the method was not invoked during the execution of a SQLTransactionCallback, SQLStatementCallback, or SQLStatementErrorCallback then raise an INVALID_STATE_ERR exception. (Calls from inside a SQLTransactionErrorCallback thus raise an exception. The SQLTransactionErrorCallback handler is only called once a transaction has failed, and no SQL statements can be added to a failed transaction.)

  2. Parse the first argument to the method (sqlStatement) as an SQL statement, with the exception that ? characters can be used in place of literals in the statement. [SQL]

  3. Replace each ? placeholder with the value of the argument in the arguments array with the same position. (So the first ? placeholder gets replaced by the first value in the arguments array, and generally the nth ? placeholder gets replaced by the nth value in the arguments array.)

    If the second argument is omitted or null, then treat the arguments array as empty.

    The result is the statement.

    Implementation feedback is requested on what to do with arguments that are of types that are not supported by the underlying SQL backend. For example, SQLite doesn't support booleans, so what should the UA do if passed a boolean? The Gears team suggests failing, not silently converting types.

  4. If the syntax of sqlStatement is not valid (except for the use of ? characters in the place of literals), or the statement uses features that are not supported (e.g. due to security reasons), or the number of items in the arguments array is not equal to the number of ? placeholders in the statement, or the statement cannot be parsed for some other reason, then mark the statement as bogus.

  5. If the Database object that the SQLTransaction object was created from has an expected version that is neither the empty string nor the actual version of the database, then mark the statement as bogus. (Error code 2.)

  6. Queue up the statement in the transaction, along with the third argument (if any) as the statement's result set callback and the fourth argument (if any) as the error callback.

The user agent must act as if the database was hosted in an otherwise completely empty environment with no resources. For example, attempts to read from or write to the file system will fail.

SQL inherently supports multiple concurrent connections. Authors should make appropriate use of the transaction features to handle the case of multiple scripts interacting with the same database simultaneously (as could happen if the same page was opened in two different browsing contexts).

User agents must consider statements that use the BEGIN, COMMIT, and ROLLBACK SQL features as being unsupported (and thus will mark them as bogus), so as to not let these statements interfere with the explicit transactions managed by the database API itself.

A future version of this specification will probably define the exact SQL subset required in more detail.

5.10.2.4. Database query results

The executeSql() method invokes its callback with a SQLResultSet object as an argument.

interface SQLResultSet {
  readonly attribute int insertId;
  readonly attribute int rowsAffected;
  readonly attribute SQLResultSetRowList rows;
};

The insertId attribute must return the row ID of the row that the SQLResultSet object's SQL statement inserted into the database, if the statement inserted a row. If the statement inserted multiple rows, the ID of the last row must be the one returned. If the statement did not insert a row, then the attribute must instead raise an INVALID_ACCESS_ERR exception.

The rowsAffected attribute must return the number of rows that were affected by the SQL statement. If the statement did not affected any rows, then the attribute must return zero. For "SELECT" statements, this returns zero (querying the database doesn't affect any rows).

The rows attribute must return a SQLResultSetRowList representing the rows returned, in the order returned by the database. If no rows were returned, then the object will be empty (its length will be zero).

interface SQLResultSetRowList {
  readonly attribute unsigned long length;
  [IndexGetter] DOMObject item(in unsigned long index);
};

SQLResultSetRowList objects have a length attribute that must return the number of rows it represents (the number of rows returned by the database).

The item(index) attribute must return the row with the given index index. If there is no such row, then the method must raise an INDEX_SIZE_ERR exception.

Each row must be represented by a native ordered dictionary data type. In the ECMAScript binding, this must be Object. Each row object must have one property (or dictionary entry) per column, with those properties enumerating in the order that these columns were returned by the database. Each property must have the name of the column and the value of the cell, as they were returned by the database.

5.10.2.5. Errors

Errors in the database API are reported using callbacks that have a SQLError object as one of their arguments.

interface SQLError {
  readonly attribute unsigned int code;
  readonly attribute DOMString message;
};

The code DOM attribute must return the most appropriate code from the following table:

Code Situation
0 The transaction failed for reasons unrelated to the database itself and not covered by any other error code.
1 The statement failed for database reasons not covered by any other error code.
2 The statement failed because the expected version of the database didn't match the actual database version.
3 The statement failed because the data returned from the database was too large. The SQL "LIMIT" modifier might be useful to reduce the size of the result set.
4 The statement failed because there was not enough remaining storage space, or the storage quota was reached and the user declined to give more space to the database.
5 The statement failed because the transaction's first statement was a read-only statement, and a subsequent statement in the same transaction tried to modify the database, but the transaction failed to obtain a write lock before another transaction obtained a write lock and changed a part of the database that the former transaction was depending upon.
6 An INSERT, UPDATE, or REPLACE statement failed due to a constraint failure. For example, because a row was being inserted and the value given for the primary key column duplicated the value of an existing row.

We should define a more thorough list of codes. Implementation feedback is requested to determine what codes are needed.

The message DOM attribute must return an error message describing the error encountered. The message should be localized to the user's language.

5.10.2.6. Processing model

The transaction steps are as follows. These steps must be run asynchronously. These steps are invoked with a transaction callback, optionally an error callback, optionally a success callback, optionally a preflight operation, and optionally a postflight operation.

  1. Open a new SQL transaction to the database, and create a SQLTransaction object that represents that transaction.

  2. If an error occurred in the opening of the transaction, jump to the last step.

  3. If a preflight operation was defined for this instance of the transaction steps, run that. If it fails, then jump to the last step. (This is basically a hook for the changeVersion() method.)

  4. Invoke the transaction callback with the aforementioned SQLTransaction object as its only argument.

  5. If the callback couldn't be called (e.g. it was null), or if the callback was invoked and raised an exception, jump to the last step.

  6. While there are any statements queued up in the transaction, perform the following steps for each queued up statement in the transaction, oldest first. Each statement has a statement, optionally a result set callback, and optionally an error callback.

    1. If the statement is marked as bogus, jump to the "in case of error" steps below.

    2. Execute the statement in the context of the transaction. [SQL]

    3. If the statement failed, jump to the "in case of error" steps below.

    4. Create a SQLResultSet object that represents the result of the statement.

    5. If the statement has a result set callback, invoke it with the SQLTransaction object as its first argument and the new SQLResultSet object as its second argument.

    6. If the callback was invoked and raised an exception, jump to the last step in the overall steps.

    7. Move on to the next statement, if any, or onto the next overall step otherwise.

    In case of error (or more specifically, if the above substeps say to jump to the "in case of error" steps), run the following substeps:

    1. If the statement had an associated error callback, then invoke that error callback with the SQLTransaction object and a newly constructed SQLError object that represents the error that caused these substeps to be run as the two arguments, respectively.

    2. If the error callback returns false, then move on to the next statement, if any, or onto the next overall step otherwise.

    3. Otherwise, the error callback did not return false, or there was no error callback. Jump to the last step in the overall steps.

  7. If a postflight operation was defined for this instance of the transaction steps, run that. If it fails, then jump to the last step. (This is basically a hook for the changeVersion() method.)

  8. Commit the transaction.

  9. If an error occurred in the committing of the transaction, jump to the last step.

  10. Invoke the success callback.

  11. End these steps. The next step is only used when something goes wrong.

  12. Call the error callback with a newly constructed SQLError object that represents the last error to have occurred in this transaction. Rollback the transaction. Any still-pending statements in the transaction are discarded.

5.10.3 Disk space

User agents should limit the total amount of space allowed for storage areas and databases.

User agents should guard against sites storing data in the storage areas or databases of subdomains, 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 domain is recommended. Implementation feedback is welcome and will be used to update this suggestion in future.

5.10.4 Privacy

5.10.4.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 or in its client-side database 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:

While these suggestions prevent trivial use of these APIs 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 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.

If the user interface for persistent storage presents data in the persistent storage features separately from data in HTTP session cookies, then users are likely to delete data in one and not the other. This would allow sites to use the two features as redundant backup for each other, defeating a user's attempts to protect his privacy.

5.10.5 Security

5.10.5.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 SSL. Pages using SSL can be sure that only pages using SSL that have certificates identifying them as being from the same domain can access their local storage areas and databases.

5.10.5.2. Cross-directory attacks

Different authors sharing one host name, for example users hosting content on geocities.com, all share one persistent storage object and one set of databases. There is no feature to restrict the access by pathname. Authors on shared hosts are therefore recommended to avoid using the persistent storage features, as it would be trivial for other authors to read from and write to the same storage area or database.

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.

5.10.5.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 storage areas 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.

5.10.5.4. SQL and user agents

User agent implementors are strongly encouraged to audit all their supported SQL statements for security implications. For example, LOAD DATA INFILE is likely to pose security risks and there is little reason to support it.

In general, it is recommended that user agents not support features that control how databases are stored on disk. For example, there is little reason to allow Web authors to control the character encoding used in the disk representation of the data, as all data in ECMAScript is implicitly UTF-16.

5.10.5.5. SQL injection

Authors are strongly recommended to make use of the ? placeholder feature of the executeSql() method, and to never construct SQL statements on the fly.

The a, area, and link elements can, in certain situations described in the definitions of those elements, represent hyperlinks.

The href attribute on a hyperlink element must have a value that is a valid URL. This URL is the destination resource of the hyperlink.

The href attribute on a and area elements is not required; when those elements do not have href attributes they do not represent hyperlinks.

The href attribute on the link element is required, but whether a link element represents a hyperlink or not depends on the value of the rel attribute of that element.

The target attribute, if present, must be a valid browsing context name or keyword. User agents use this name when following hyperlinks.

The ping attribute, if present, gives the URLs of the resources that are interested in being notified if the user follows the hyperlink. The value must be a space separated list of one or more valid URLs. The value is used by the user agent when following hyperlinks.

For a and area elements that represent hyperlinks, the relationship between the document containing the hyperlink and the destination resource indicated by the hyperlink is given by the value of the element's rel attribute, which must be a set of space-separated tokens. The allowed values and their meanings are defined below. The rel attribute has no default value. If the attribute is omitted or if none of the values in the attribute are recognized by the UA, then the document has no particular relationship with the destination resource other than there being a hyperlink between the two.

The media attribute describes for which media the target document was designed. It is purely advisory. The value must be a valid media query. [MQ] The default, if the media attribute is omitted, is all.

The hreflang attribute on hyperlink elements, if present, gives the language of the linked resource. It is purely advisory. The value must be a valid RFC 3066 language code. [RFC3066] User agents must not consider this attribute authoritative — upon fetching the resource, user agents must use only language information associated with the resource to determine its language, not metadata included in the link to the resource.

The type attribute, if present, gives the MIME type of the linked resource. It is purely advisory. The value must be a valid MIME type, optionally with parameters. [RFC2046] User agents must not consider the type attribute authoritative — upon fetching the resource, user agents must not use metadata included in the link to the resource to determine its type.

5.11.2 Following hyperlinks

When a user follows a hyperlink, the user agent must navigate a browsing context to the URL given by the href attribute of that hyperlink. In the case of server-side image maps, the URL of the hyperlink must further have its hyperlink suffix appended to it.

If the user indicated a specific browsing context when following the hyperlink, or if the user agent is configured to follow hyperlinks by navigating a particular browsing context, then that must be the browsing context that is navigated.

Otherwise, if the hyperlink element is an a or area element that has a target attribute, then the browsing context that is navigated must be chosen by applying the rules for choosing a browsing context given a browsing context name, using the value of the target attribute as the browsing context name. If these rules result in the creation of a new browsing context, it must be navigated with replacement enabled.

Otherwise, if the hyperlink element is a sidebar hyperlink and the user agent implements a feature that can be considered a secondary browsing context, such a secondary browsing context may be selected as the browsing context to be navigated.

Otherwise, if the hyperlink element is an a or area element with no target attribute, but one of the child nodes of the head element is a base element with a target attribute, then the browsing context that is navigated must be chosen by applying the rules for choosing a browsing context given a browsing context name, using the value of the target attribute of the first such base element as the browsing context name. If these rules result in the creation of a new browsing context, it must be navigated with replacement enabled.

Otherwise, the browsing context that must be navigated is the same browsing context as the one which the hyperlink element itself is in.

The navigation must be done with the browsing context that contains the Document object with which the hyperlink's element in question is associated as the source browsing context.

5.11.2.1. Hyperlink auditing

If an a or area hyperlink element has a ping attribute and the user follows the hyperlink, the user agent must take the ping attribute's value, split that string on spaces, resolve each resulting token, and then should send a request (as described below) to each of the resulting absolute URLs. (Tokens that fail to resolve are ignored.) This may be done in parallel with the primary request, and is independent of the result of that request.

User agents should allow the user to adjust this behavior, for example in conjunction with a setting that disables the sending of HTTP Referer headers. Based on the user's preferences, UAs may either ignore the ping attribute altogether, or selectively ignore URLs in the list (e.g. ignoring any third-party URLs).

For URLs that are HTTP URLs, the requests must be performed using the POST method (with an empty entity body in the request). All relevant cookie and HTTP authentication headers must be included in the request. Which other headers are required depends on the URls involved.

If both the address of the Document object containing the hyperlink being audited and the ping URL have the same origin
The request must include a Ping-From HTTP header with, as its value, the address of the document containing the hyperlink, and a Ping-To HTTP header with, as its value, the address of the absolute URL of the target of the hyperlink. The request must not include a Referer HTTP header.
Otherwise, if the origins are different, but the document containing the hyperlink being audited was not retrieved over an encrypted connection
The request must include a Referer HTTP header [sic] with, as its value, the location of the document containing the hyperlink, a Ping-From HTTP header with the same value, and a Ping-To HTTP header with, as its value, the address of the target of the hyperlink.
Otherwise, the origins are different and the document containing the hyperlink being audited was retrieved over an encrypted connection
The request must include a Ping-To HTTP header with, as its value, the address of the target of the hyperlink. The request must neither include a Referer HTTP header nor include a Ping-From HTTP header.

To save bandwidth, implementors might also wish to consider omitting optional headers such as Accept from these requests.

User agents must ignore any entity bodies returned in the responses, but must, unless otherwise specified by the user, honor the HTTP headers (including, in particular, redirects and HTTP cookie headers). [RFC2109] [RFC2965]

When the ping attribute is present, user agents should clearly indicate to the user that following the hyperlink will also cause secondary requests to be sent in the background, possibly including listing the actual target URLs.

The ping attribute is redundant with pre-existing technologies like HTTP redirects and JavaScript in allowing Web pages to track which off-site links are most popular or allowing advertisers to track click-through rates.

However, the ping attribute provides these advantages to the user over those alternatives:

Thus, while it is possible to track users without this feature, authors are encouraged to use the ping attribute so that the user agent can improve the user experience.

5.11.3 Link types

The following table summarizes the link types that are defined by this specification. This table is non-normative; the actual definitions for the link types are given in the next few sections.

In this section, the term referenced document refers to the resource identified by the element representing the link, and the term current document refers to the resource within which the element representing the link finds itself.

To determine which link types apply to a link, a, or area element, the element's rel attribute must be split on spaces. The resulting tokens are the link types that apply to that element.

Unless otherwise specified, a keyword must not be specified more than once per rel attribute.

Link type Effect on... Brief description
link a and area
alternate Hyperlink Hyperlink Gives alternate representations of the current document.
archives Hyperlink Hyperlink Provides a link to a collection of records, documents, or other materials of historical interest.
author Hyperlink Hyperlink Gives a link to the current document's author.
bookmark not allowed Hyperlink Gives the permalink for the nearest ancestor section.
external not allowed Hyperlink Indicates that the referenced document is not part of the same site as the current document.
feed Hyperlink Hyperlink Gives the address of a syndication feed for the current document.
first Hyperlink Hyperlink Indicates that the current document is a part of a series, and that the first document in the series is the referenced document.
help Hyperlink Hyperlink Provides a link to context-sensitive help.
icon External Resource not allowed Imports an icon to represent the current document.
index Hyperlink Hyperlink Gives a link to the document that provides a table of contents or index listing the current document.
last Hyperlink Hyperlink Indicates that the current document is a part of a series, and that the last document in the series is the referenced document.
license Hyperlink Hyperlink Indicates that the current document is covered by the copyright license described by the referenced document.
next Hyperlink Hyperlink Indicates that the current document is a part of a series, and that the next document in the series is the referenced document.
nofollow not allowed Hyperlink Indicates that the current document's original author or publisher does not endorse the referenced document.
noreferrer not allowed Hyperlink Requires that the user agent not send an HTTP Referer header if the user follows the hyperlink.
pingback External Resource not allowed Gives the address of the pingback server that handles pingbacks to the current document.
prefetch External Resource not allowed Specifies that the target resource should be preemptively cached.
prev Hyperlink Hyperlink Indicates that the current document is a part of a series, and that the previous document in the series is the referenced document.
search Hyperlink Hyperlink Gives a link to a resource that can be used to search through the current document and its related pages.
stylesheet External Resource not allowed Imports a stylesheet.
sidebar Hyperlink Hyperlink Specifies that the referenced document, if retrieved, is intended to be shown in the browser's sidebar (if it has one).
tag Hyperlink Hyperlink Gives a tag (identified by the given address) that applies to the current document.
up Hyperlink Hyperlink Provides a link to a document giving the context for the current document.

Some of the types described below list synonyms for these values. These are to be handled as specified by user agents, but must not be used in documents.

The alternate keyword may be used with link, a, and area elements. For link elements, if the rel attribute does not also contain the keyword stylesheet, it creates a hyperlink; but if it does also contain the keyword stylesheet, the alternate keyword instead modifies the meaning of the stylesheet keyword in the way described for that keyword, and the rest of this subsection doesn't apply.

The alternate keyword indicates that the referenced document is an alternate representation of the current document.

The nature of the referenced document is given by the media, hreflang, and type attributes.

If the alternate keyword is used with the media attribute, it indicates that the referenced document is intended for use with the media specified.

If the alternate keyword is used with the hreflang attribute, and that attribute's value differs from the root element's language, it indicates that the referenced document is a translation.

If the alternate keyword is used with the type attribute, it indicates that the referenced document is a reformulation of the current document in the specified format.

The media, hreflang, and type attributes can be combined when specified with the alternate keyword.

For example, the following link is a French translation that uses the PDF format:

<link rel=alternate type=application/pdf hreflang=fr href=manual-fr>

If the alternate keyword is used with the type attribute set to the value application/rss+xml or the value application/atom+xml, then the user agent must treat the link as it would if it had the feed keyword specified as well.

The alternate link relationship is transitive — that is, if a document links to two other documents with the link type "alternate", then, in addition to implying that those documents are alternative representations of the first document, it is also implying that those two documents are alternative representations of each other.

The archives keyword may be used with link, a, and area elements. For link elements, it creates a hyperlink.

The archives keyword indicates that the referenced document describes a collection of records, documents, or other materials of historical interest.

A blog's index page could link to an index of the blog's past posts with rel="archives".

Synonyms: For historical reasons, user agents must also treat the keyword "archive" like the archives keyword.

The author keyword may be used with link, a, and area elements. For link elements, it creates a hyperlink.

For a and area elements, the author keyword indicates that the referenced document provides further information about the author of the section that the element defining the hyperlink applies to.

For link elements, the author keyword indicates that the referenced document provides further information about the author for the page as a whole.

The "referenced document" can be, and often is, a mailto: URL giving the e-mail address of the author. [MAILTO]

Synonyms: For historical reasons, user agents must also treat link, a, and area elements that have a rev attribute with the value "made" as having the author keyword specified as a link relationship.

The bookmark keyword may be used with a and area elements.

The bookmark keyword gives a permalink for the nearest ancestor article element of the linking element in question, or of the section the linking element is most closely associated with, if there are no ancestor article elements.

The following snippet has three permalinks. A user agent could determine which permalink applies to which part of the spec by looking at where the permalinks are given.

 ...
 <body>
  <h1>Example of permalinks</h1>
  <div id="a">
   <h2>First example</h2>
   <p><a href="a.html" rel="bookmark">This</a> permalink applies to
   only the content from the first H2 to the second H2. The DIV isn't
   exactly that section, but it roughly corresponds to it.</p>
  </div>
  <h2>Second example</h2>
  <article id="b">
   <p><a href="b.html" rel="bookmark">This</a> permalink applies to
   the outer ARTICLE element (which could be, e.g., a blog post).</p>
   <article id="c">
    <p><a href="c.html" rel="bookmark">This</a> permalink applies to
    the inner ARTICLE element (which could be, e.g., a blog comment).</p>
   </article>
  </article>
 </body>
 ...

The external keyword may be used with a and area elements.

The external keyword indicates that the link is leading to a document that is not part of the site that the current document forms a part of.

The feed keyword may be used with link, a, and area elements. For link elements, it creates a hyperlink.

The feed keyword indicates that the referenced document is a syndication feed. If the alternate link type is also specified, then the feed is specifically the feed for the current document; otherwise, the feed is just a syndication feed, not necessarily associated with a particular Web page.

The first link, a, or area element in the document (in tree order) that creates a hyperlink with the link type feed must be treated as the default syndication feed for the purposes of feed autodiscovery.

The feed keyword is implied by the alternate link type in certain cases (q.v.).

The following two link elements are equivalent: both give the syndication feed for the current page:

<link rel="alternate" type="application/atom+xml" href="data.xml">
<link rel="feed alternate" href="data.xml">

The following extract offers various different syndication feeds:

 <p>You can access the planets database using Atom feeds:</p>
 <ul>
  <li><a href="recently-visited-planets.xml" rel="feed">Recently Visited Planets</a></li>
  <li><a href="known-bad-planets.xml" rel="feed">Known Bad Planets</a></li>
  <li><a href="unexplored-planets.xml" rel="feed">Unexplored Planets</a></li>
 </ul>

The help keyword may be used with link, a, and area elements. For link elements, it creates a hyperlink.

For a and area elements, the help keyword indicates that the referenced document provides further help information for the parent of the element defining the hyperlink, and its children.

In the following example, the form control has associated context-sensitive help. The user agent could use this information, for example, displaying the referenced document if the user presses the "Help" or "F1" key.

 <p><label> Topic: <input name=topic> <a href="help/topic.html" rel="help">(Help)</a></label></p>

For link elements, the help keyword indicates that the referenced document provides help for the page as a whole.

5.11.3.8. Link type "icon"

The icon keyword may be used with link elements, for which it creates an external resource link.

The specified resource is an icon representing the page or site, and should be used by the user agent when representing the page in the user interface.

Icons could be auditory icons, visual icons, or other kinds of icons. If multiple icons are provided, the user agent must select the most appropriate icon according to the type, media, and sizes attributes. If there are multiple equally appropriate icons, user agents must use the last one declared in tree order. If the user agent tries to use an icon but that icon is determined, upon closer examination, to in fact be inappropriate (e.g. because it uses an unsupported format), then the user agent must try the next-most-appropriate icon as determined by the attributes.

There is no default type for resources given by the icon keyword. However, for the purposes of determining the type of the resource, user agents must expect the resource to be an image.

The sizes attribute gives the sizes of icons for visual media.

If specified, the attribute must have a value that is an unordered set of unique space-separated tokens. The values must all be either any or a value that consists of two valid non-negative integers that do not have a leading U+0030 DIGIT ZERO (0) character and that are separated by a single U+0078 LATIN SMALL LETTER X character.

The keywords represent icon sizes.

To parse and process the attribute's value, the user agent must first split the attribute's value on spaces, and must then parse each resulting keyword to determine what it represents.

The any keyword represents that the resource contains a scalable icon, e.g. as provided by an SVG image.

Other keywords must be further parsed as follows to determine what they represent:

The keywords specified on the sizes attribute must not represent icon sizes that are not actually available in the linked resource.

If the attribute is not specified, then the user agent must assume that the given icon is appropriate, but less appropriate than an icon of a known and appropriate size.

The following snippet shows the top part of an application with several icons.

<!DOCTYPE HTML>
<html>
 <head>
  <title>lsForums — Inbox</title>
  <link rel=icon href=favicon.png sizes="16x16">
  <link rel=icon href=windows.ico sizes="32x32 48x48">
  <link rel=icon href=mac.icns sizes="128x128 512x512 8192x8192 32768x32768">
  <link rel=icon href=iphone.png sizes="59x60">
  <link rel=icon href=gnome.svg sizes="any">
  <link rel=stylesheet href=lsforums.css>
  <script src=lsforums.js></script>
  <meta name=application-name content="lsForums">
 </head>
 <body>
  ...

The license keyword may be used with link, a, and area elements. For link elements, it creates a hyperlink.

The license keyword indicates that the referenced document provides the copyright license terms under which the current document is provided.

Synonyms: For historical reasons, user agents must also treat the keyword "copyright" like the license keyword.

The nofollow keyword may be used with a and area elements.

The nofollow keyword indicates that the link is not endorsed by the original author or publisher of the page, or that the link to the referenced document was included primarily because of a commercial relationship between people affiliated with the two pages.

The noreferrer keyword may be used with a and area elements.

If a user agent follows a link defined by an a or area element that has the noreferrer keyword, the user agent must not include a Referer HTTP header (or equivalent for other protocols) in the request.

The pingback keyword may be used with link elements, for which it creates an external resource link.

For the semantics of the pingback keyword, see the Pingback 1.0 specification. [PINGBACK]

The prefetch keyword may be used with link elements, for which it creates an external resource link.

The prefetch keyword indicates that preemptively fetching and caching the specified resource is likely to be beneficial, as it is highly likely that the user will require this resource.

There is no default type for resources given by the prefetch keyword.

The search keyword may be used with link, a, and area elements. For link elements, it creates a hyperlink.

The search keyword indicates that the referenced document provides an interface specifically for searching the document and its related resources.

OpenSearch description documents can be used with link elements and the search link type to enable user agents to autodiscover search interfaces. [OPENSEARCH]

The stylesheet keyword may be used with link elements, for which it creates an external resource link that contributes to the styling processing model.

The specified resource is a resource that describes how to present the document. Exactly how the resource is to be processed depends on the actual type of the resource.

If the alternate keyword is also specified on the link element, then the link is an alternative stylesheet.

The default type for resources given by the stylesheet keyword is text/css.

Quirk: If the document has been set to quirks mode and the Content-Type metadata of the external resource is not a supported style sheet type, the user agent must instead assume it to be text/css.

The sidebar keyword may be used with link, a, and area elements. For link elements, it creates a hyperlink.

The sidebar keyword indicates that the referenced document, if retrieved, is intended to be shown in a secondary browsing context (if possible), instead of in the current browsing context.

A hyperlink element with with the sidebar keyword specified is a sidebar hyperlink.

The tag keyword may be used with link, a, and area elements. For link elements, it creates a hyperlink.

The tag keyword indicates that the tag that the referenced document represents applies to the current document.

5.11.3.18. Hierarchical link types

Some documents form part of a hierarchical structure of documents.

A hierarchical structure of documents is one where each document can have various subdocuments. The document of which a document is a subdocument is said to be the document's parent. A document with no parent forms the top of the hierarchy.

A document may be part of multiple hierarchies.

The index keyword may be used with link, a, and area elements. For link elements, it creates a hyperlink.

The index keyword indicates that the document is part of a hierarchical structure, and that the link is leading to the document that is the top of the hierarchy. It conveys more information when used with the up keyword (q.v.).

Synonyms: For historical reasons, user agents must also treat the keywords "top", "contents", and "toc" like the index keyword.

The up keyword may be used with link, a, and area elements. For link elements, it creates a hyperlink.

The up keyword indicates that the document is part of a hierarchical structure, and that the link is leading to the document that is the parent of the current document.

The up keyword may be repeated within a rel attribute to indicate the hierarchical distance from the current document to the referenced document. Each occurrence of the keyword represents one further level. If the index keyword is also present, then the number of up keywords is the depth of the current page relative to the top of the hierarchy. Only one link is created for the set of one or more up keywords and, if present, the index keyword.

If the page is part of multiple hierarchies, then they should be described in different paragraphs. User agents must scope any interpretation of the up and index keywords together indicating the depth of the hierarchy to the paragraph in which the link finds itself, if any, or to the document otherwise.

When two links have both the up and index keywords specified together in the same scope and contradict each other by having a different number of up keywords, the link with the greater number of up keywords must be taken as giving the depth of the document.

This can be used to mark up a navigation style sometimes known as bread crumbs. In the following example, the current page can be reached via two paths.

<nav>
 <p>
  <a href="/" rel="index up up up">Main</a> >
  <a href="/products/" rel="up up">Products</a> >
  <a href="/products/dishwashers/" rel="up">Dishwashers</a> >
  <a>Second hand</a>
 </p>
 <p>
  <a href="/" rel="index up up">Main</a> >
  <a href="/second-hand/" rel="up">Second hand</a> >
  <a>Dishwashers</a>
 </p>
</nav>

The relList DOM attribute (e.g. on the a element) does not currently represent multiple up keywords (the interface hides duplicates).

5.11.3.19. Sequential link types

Some documents form part of a sequence of documents.

A sequence of documents is one where each document can have a previous sibling and a next sibling. A document with no previous sibling is the start of its sequence, a document with no next sibling is the end of its sequence.

A document may be part of multiple sequences.

The first keyword may be used with link, a, and area elements. For link elements, it creates a hyperlink.

The first keyword indicates that the document is part of a sequence, and that the link is leading to the document that is the first logical document in the sequence.

Synonyms: For historical reasons, user agents must also treat the keywords "begin" and "start" like the first keyword.

The last keyword may be used with link, a, and area elements. For link elements, it creates a hyperlink.

The last keyword indicates that the document is part of a sequence, and that the link is leading to the document that is the last logical document in the sequence.

Synonyms: For historical reasons, user agents must also treat the keyword "end" like the last keyword.

The next keyword may be used with link, a, and area elements. For link elements, it creates a hyperlink.

The next keyword indicates that the document is part of a sequence, and that the link is leading to the document that is the next logical document in the sequence.

The prev keyword may be used with link, a, and area elements. For link elements, it creates a hyperlink.

The prev keyword indicates that the document is part of a sequence, and that the link is leading to the document that is the previous logical document in the sequence.

Synonyms: For historical reasons, user agents must also treat the keyword "previous" like the prev keyword.

5.11.3.20. Other link types

Other than the types defined above, only types defined as extensions in the WHATTF Wiki RelExtensions page may be used with the rel attribute on link, a, and area elements. [WHATTFWIKI]

Anyone is free to edit the WHATTF Wiki RelExtensions page at any time to add a type. Extension types must be specified with the following information:

Keyword

The actual value being defined. The value should not be confusingly similar to any other defined value (e.g. differing only in case).

Effect on... link

One of the following:

not allowed
The keyword is not allowed to be specified on link elements.
Hyperlink
The keyword may be specified on a link element; it creates a hyperlink link.
External Resource
The keyword may be specified on a link element; it creates a external resource link.
Effect on... a and area

One of the following:

not allowed
The keyword is not allowed to be specified on a and area elements.
Hyperlink
The keyword may be specified on a and area elements.
Brief description

A short description of what the keyword's meaning is.

Link to more details

A link to a more detailed description of the keyword's semantics and requirements. It could be another page on the Wiki, or a link to an external page.

Synonyms

A list of other keyword values that have exactly the same processing requirements. Authors must not use the values defined to be synonyms, they are only intended to allow user agents to support legacy content.

Status

One of the following:

Proposal
The keyword has not received wide peer review and approval. It is included for completeness because pages use the keyword. Pages should not use the keyword.
Accepted
The keyword has received wide peer review and approval. It has a specification that unambiguously defines how to handle pages that use the keyword, including when they use them in incorrect ways. Pages may use the keyword.
Rejected
The keyword has received wide peer review and it has been found to have significant problems. Pages must not use the keyword. When a keyword has this status, the "Effect on... link" and "Effect on... a and area" information should be set to "not allowed".

If a keyword is added with the "proposal" status and found to be redundant with existing values, it should be removed and listed as a synonym for the existing value. If a keyword is added with the "proposal" status and found to be harmful, then it should be changed to "rejected" status, and its "Effect on..." information should be changed accordingly.

Conformance checkers must use the information given on the WHATTF Wiki RelExtensions page to establish if a value not explicitly defined in this specification is allowed or not. When an author uses a new type not defined by either this specification or the Wiki page, conformance checkers should offer to add the value to the Wiki, with the details described above, with the "proposal" status.

This specification does not define how new values will get approved. It is expected that the Wiki will have a community that addresses this.