Widget Access Request Policy

W3C Working Draft 08 December 2009

This Version:
Latest Published Version:
Latest Editor's Draft:
Previous version:
Robin Berjon, Vodafone


This specification defines the security model controlling network access from within a widget, as well as a method for widget authors to request that the user agent grant access to certain network resources or sets thereof.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

Implementers should be aware that this document is not stable. Implementers who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this document before it eventually reaches the Candidate Recommendation stage should join the aforementioned mailing lists and take part in the discussions.

User agents that wish to extend this specification in any way are encouraged to discuss their extensions on a public forum, such as public-webapps so their extensions can be considered for standardisation.

This specification is part of the Widgets Family of Specifications.

This document was published by the Web Applications WG as a Last Call Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-webapps@w3.org (subscribe, archives). The Last Call period ends 13 January 2010. All feedback is welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This is a Last Call Working Draft and thus the Working Group has determined that this document has satisfied the relevant technical requirements and is sufficiently stable to advance through the Technical Recommendation process.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Introduction

This section is non-normative.

User agents running widgets are expected to provide access to potentially sensitive APIs (phone book, calendar, file system, etc.) that expose data which should not be exposed without the user's consent.

The purpose of this specification is to define the security model for network interactions from within a widget that has access to sensitive information. It provides means for a widget to declare its intent to access specific network resources so that a policy may control it.

2. Definitions

An access request is a request made by an author to the user agent for the ability to retrieve one or more network resources. The network resources and author requests to access are identified using access elements in the widget's configuration document.

To grant access means that the user agent authorises widget execution scopes to retrieve one or more network resources via the user agent.

Some schemes (e.g. mailto:) may be handled by third-party applications and are therefore not controlled by the access mechanism defined in this specification. Similarly, policies defined using this specification do not apply to opening content in external applications (e.g. through the openURL() method [WIDGETS-APIS]).

To deny access means that the user agent rejects an author's request to grant access.

An access request policy, or policy for short, is a set of rules that details whether given some conditions the user agent will grant or deny access to a given network resource.

A network resource is a retrievable resource of any media type that is identified by a URI that has a DNS or IP as its authority component [URI].

This deliberately excludes some schemes (e.g. sms:, tel:) from being controlled by the means provided by this specification.

A feature-enabled API is an API that for one reason or another is considered to be sensitive (typically because it has access to the user's private data). Such an API may for instance have been activated through use of the <feature> element [WIDGETS].

The widget execution scope is the scope (or set of scopes, seen as a single one for simplicity's sake) being the execution context for code running from documents that are part of the widget package.

The external execution scope is the scope (or set thereof) being the execution context for code running from documents that originate outside the widget package.

3. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

This specification defines conformance criteria that apply to a single product: user agents that implement the interfaces that it contains.

4. Policy

A user agent enforces an access request policy. In the default policy, a user agent must deny access to network resources external to the widget by default, whether this access is requested through APIs (e.g. XMLHttpRequest) or through markup (e.g. iframe, script, img).

A more lenient policy can be defined with the access-request list as defined in the processing section. A user agent may grant access to network resources listed in the access-request list; in this case the user agent must grant access based on the Rules for Granting Access to a Network Resources.

Furthermore, a user agent may grant access to certain URI schemes (e.g., mailto:) without the need of an access request if its security policy considers those schemes benign. A user agent may deny access requests made via the access element (e.g. based on a security policy, user prompting, etc.).

When a user agent grants access to a given set of network resources, it must do so equally for APIs and markup.

The exact rules defining which execution scope applies to network resources loaded into a document running in the widget execution scope depend on the language that is being used inside the the widget.

For instance, in HTML 5 [HTML5] a script loaded off the network into a document running in the widget execution scope is itself in the same scope, whereas a document loaded off the network in an iframe will be in the external execution scope.

5. The access Element

The access element allows authors to request permission from the user agent to retrieve a set of network resources. Zero or more access elements can be placed in the configuration document.

The access element is in the http://www.w3.org/ns/widgets namespace as defined in [WIDGETS].

Context in which this element may be used:
As a child of the widget element [WIDGETS].
Content model:
Zero or more.
Expected children:
Localizable via xml:lang:

5.1 Attributes

An IRI attribute that defines the specifics of the access request that is requested. Additionally, the special value of U+002A ASTERISK (*) may be used. This special value provides a means for an author to request from the user agent unrestricted access to network resources. Only the scheme and authority components can be present in the IRI that this attribute contains ([URI], [RFC3987]).
A boolean attribute that indicates whether or not the host component part of the access request applies to subdomains of domain in the origin attribute. The default value when this attribute is absent is false, meaning that access to subdomains is not requested.

5.2 Usage example

This example contains multiple uses of the access element (not contained in the same configuration as the last one would make the others useless). They presume that http://www.w3.org/ns/widgets is the default namespace defined in their context:

<access origin="https://example.net"/>
<access origin="http://example.org" subdomains="true"/>
<access origin="http://dahut.example.com:4242"/>
<access origin="*"/>

6. Processing access elements in the Configuration Document

A user agent must add the following to the Table of Configuration Defaults [WIDGETS].

Table of Configuration Defaults (addendum)
Variable Type Default Value Overridden in Description
access-request list List null Processing access elements in the Configuration Document The list of items extracted from access elements to which the user agent will grant access.

This processing takes place as part of Step 7 - Process the Configuration Document in [WIDGETS].

Let access-request list be an empty list of objects that represent the author's access requests to network resources.

The following sequence of steps relies on terminology that is defined in RFC 3987 [RFC3987] and in the URI [URI] specification. The particular the terms derived from the URI and IRI specifications include: host, port, scheme, ifragment, and iuser info.

For each access element that is a direct child of the widget element:

  1. If the origin attribute is absent, then this element is in error and the user agent must ignore it.
  2. Let origin be result of applying the rule for getting a single attribute value to the value of the origin attribute. If the result is a single U+002A ASTERISK (*) character, then prepend the U+002A ASTERISK to the access-request list and skip all steps below.
  3. If origin is not a valid IRI, if it has components other than scheme and iauthority, if it has no host component, or if it has a iuser info component, then this element is in error and the user agent must ignore it.
  4. Let sub domains be the result of applying the rule for getting a single attribute value to the value of the subdomains attribute. If the value of sub domains is not a valid boolean value, then this element is in error and the user agent must ignore it.
  5. Let scheme be the scheme component of origin. Let host be the host component of origin. Let port be the port component of origin or if there is no port component the default value for the protocol that corresponds to scheme.
  6. If scheme is unsupported by the user agent, then this element is in error and the user agent must ignore it.
  7. If scheme is "http" or "https", then the value of host must be processed using the ToASCII algorithm as per [RFC3490].
  8. Append an item inside the access-request list that is the tuple: scheme, host, port, sub domains.

7. Rules for Granting Access to a Network Resources

When multiple access elements are used, the set of network connections that are allowed is the union of all the access requests that were granted by the user agent. The following rule is applied to determine what each access element is requesting access to.

If the access-request list contains an item that is just the U+002A ASTERISK (*) character, then all access requests are granted.

An access request is granted for a given URI if there exists an item inside the access-request list such that:

At runtime, when a network request is made from within the widget execution scope, the user agent matches it against the rules defined above, accepting it if it matches and blocking it if it doesn't. If scheme is "http" or "https", the user agent must compare hosts in a case-insensitive manner.

A. Design Goals and Requirements

The design goals and requirements for this specification are addressed in the 30 April 2009 Working Draft of the Widgets 1.0 Requirements [WIDGETS-REQS] document. This document addresses the following requirements:

Additional considerations guiding this specification are maximal compatibility with existing web technology (including not breaking linking to JS libraries, embedded media, ads, etc.); and not restricting the platform in such a way that would make it less powerful than the web platform.

B. Acknowledgements

The editor would like to thank (in no particular order): the OMTP BONDI effort, Jere Kapyaho, Thomas Roessler, Art Barstow, Mohamed Zergaoui, Arve Bersvendsen, Stephen Jolly, Marcin Hanclik, Josh Soref, and Batman Càceres.

C. References

C.1 Normative references

S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
P. Faltstrom; P. Hoffman; A. Costello. Internationalizing Domain Names in Applications (IDNA). March 2003. Internet RFC 3490. URL: http://www.rfc-editor.org/rfc/rfc3490.txt
M. Dürst; M. Suignard. Internationalized Resource Identifiers (IRIs). January 2005. Internet RFC 3987. URL: http://www.ietf.org/rfc/rfc3987.txt
T. Berners-Lee; R. Fielding; L. Masinter. Uniform Resource Identifiers (URI): generic syntax. January 2005. Internet RFC 3986. URL: http://www.ietf.org/rfc/rfc3986.txt
Marcos Caceres. Widget Packaging and Configuration. 01 December 2009. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2009/CR-widgets-20091201/

C.2 Informative references

Ian Hickson; David Hyatt. HTML 5. 25 August 2009. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2009/WD-html5-20090825/
Marcos Caceres; Robin Berjon; Arve Bersvendsen. Widgets 1.0: The widget Interface. 17 November 2009. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2009/WD-widgets-apis-20091117/
Marcos Caceres. Widgets 1.0: Requirements. 30 April 2009. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2009/WD-widgets-reqs-20090430