Widget Access Request Policy

W3C Candidate Recommendation 20 April 2010

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

Implementation feedback based on any aspect of this specification is welcome and encouraged.

The Last Call review period for this specification ended on 13 January 2010, for which a disposition of comments is available. The Web Applications Working Group hopes to request that the Director advance this document to Proposed Recommendation once the Working Group has demonstrated at least two interoperable implementations (interoperable meaning at least two implementations that pass each mandatory test in the test suite) as documented in an Implementation Report.

This document was published by the Web Applications WG as a Candidate Recommendation. 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). W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected to advance to Proposed Recommendation on 11 May 2010. All feedback is welcome.

Publication as a Candidate Recommendation 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 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. Access elements in the widget's configuration document express the author's requests to access network resources.

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.

A user agent a software application that implements this specification and the [WIDGETS] specification and its dependencies.

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 should grant access to network resources listed in the access-request list; in this case the user agent would 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 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 is 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 made. Only the scheme and authority components can be present in the IRI that this attribute contains ([URI], [RFC3987]). Additionally, an author can use the special value of U+002A ASTERISK (*). This special value provides a means for an author to request from the user agent unrestricted access to network resources.
A boolean attribute that indicates whether or not the host component part of the access request applies to subdomains (as defined in [RFC1034]) 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

All the examples below presume that http://www.w3.org/ns/widgets is the default namespace defined in their context and that there is a surrounding widget element:

Access request for https://example.net using the https protocol (port 443):

<access origin="https://example.net"/>

Access request for http://example.org and all its [RFC1034] subdomains using the http protocol (port 443):

<access origin="http://example.org" subdomains="true"/>

Access request for http://dahut.example.com using the http protocol (port 4242):

<access origin="http://dahut.example.com:4242"/>

Access request to all network resources:

<access origin="*"/>

6. Processing access elements in the Configuration Document

Firstly, a user agent must behave as if the following had been defined in the Table of Configuration Defaults in Step 3 of the [WIDGETS] specification.

Table of Configuration Defaults (addendum)
Variable Type Default Value Overridden in Description
access-request list List null Step 7 An empty list that represent the author's access requests to network resources.

Secondly, a user agent must apply the rule for processing an access element at the appropriate point in the algorithm to process a configuration document: the appropriate point is where the algorithm allows for processing 'any other type of element' [WIDGETS].

Rule for processing an access element

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.

The rule for processing an access element is given in the following algorithm. The algorithm does not return a value.

  1. Let element be the access element to be processed.

  2. If the origin attribute is absent, then this element is in error and the user agent must ignore this element.

  3. Let origin be the 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 the user agent must prepend the U+002A ASTERISK to the access-request list and skip all steps below.

  4. 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 this element.

  5. 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 this element.

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

  7. If scheme is unsupported by the user agent, then this element is in error and the user agent must ignore this element.

  8. If scheme is "http" or "https", then the user agent must process the value of host using the ToASCII algorithm as per [RFC3490].

  9. The user agent must 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 Resource

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

This section is non-normative.

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, Dominique Hazaël-Massieux, and Batman Cáceres.

C. References

C.1 Normative references

P. Mockapetris. DOMAIN NAMES - CONCEPTS AND FACILITIES. November 1987. Internet RFC 1034. URL: http://www.ietf.org/rfc/rfc1034.txt
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. 4 March 2010. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2010/WD-html5-20100304/
Marcos Caceres; Robin Berjon; Arve Bersvendsen. The Widget Interface. 22 December 2009. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2009/CR-widgets-apis-20091222/
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