Widgets 1.0: Access Requests Policy

W3C Working Draft 4 August 2009

This version:
Latest version:
Previous versions:
Latest Editor's draft:
Version history:
Twitter messages (non-editorial changes only): http://twitter.com/widgetspecs (RSS)
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/.

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.

This is the 4 August 2009 Last Call Working Draft version of the "Widgets 1.0: Access Requests" specification. The Last Call period ends on 20 September 2009. The requirements were specified and addressed via consultation with W3C members and the public through the Working Group's mailing lists (WAF archive, WebApps archive). The purpose of this Last Call is to give external interested parties a final opportunity to publicly comment on how access requests should work within widgets before the Working Group issues a call for implementations. The Working Group's goal is to make sure that vendor's requirements for access requests have been effectively addressed and clearly specified.

This document is produced by the Web Applications WG, part of the Rich Web Clients Activity in the W3C Interaction Domain. It is expected that this document will progress along the W3C's Recommendation track. 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.

You can find the latest Editor's Draft of this document in the W3C's CVS repository, which is updated on a very regular basis. The public is encouraged to send comments to the Web Apps Working Group's public mailing list public-webapps@w3.org (archive). See W3C mailing list and archive usage guidelines. A detailed list of changes from the previous version is also available from the W3C's CVS server.

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.

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

Table of Contents

  1. 1 Introduction
    1. 1.1 Definitions
    2. 1.2 The Widget Family of Specifications
    3. 1.3 Design Goals and Requirements
  2. 2 Policy
  3. 3 The access Element
  4. 4 Processing model
  5. Acknowledgements
  6. Normative References
  7. Informative References

1 Introduction

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 leaked to arbitrary network locations without the user's consent.

The purpose of this specification is precisely to define the security model for network interactions from within a widget that has access to sensitive information, and to provide means for a widget to declare the need to access specific network resources so that a policy may control it.

1.1 Definitions

An access request is a request made by an author in the configuration file for the ability to retrieve one or more network resources identified via the access element's uri and subdomains attributes.

To grant access means that the user agent authorises widget execution scopes to retrieve one or more network resources via the user agent. Note that 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.

To deny access is to refuse to grant access.

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

A feature-enabled API is an API that is for one reason or another considered to be sensitive (typically because it has access to the user's private data). It may be that this API can also be activated in a broader web context (e.g. through user interaction, prompting, etc.); but here we are considering the case where it was activated based on processing the <feature> element in the widget's configuration file as per the Widgets 1.0: Packaging and Configuration specification [Widgets-PC]

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 web execution scope is the scope (or set thereof) being the execution context for code running from documents that have been loaded off the web.

1.2 The Widget Family of Specifications

This section is non-normative.

This specification is part of the Widgets 1.0 family of specifications, which together standardise widgets as a whole. The Widgets 1.0: APIs and Events [Widgets-APIs] specification defines APIs to store preferences and capture events. The Widgets 1.0: Digital Signature [Widgets-DigSig] specification defines a means for widgets to be digitally signed using a custom profile of the XML-Signature Syntax and Processing Specification. The Widgets: 1.0: Automatic Updates [Widgets-Updates] specification defines a version control model that allows widgets to be kept up-to-date over [HTTP].

1.3 Design Goals and Requirements

This section is non-normative.

The design goals and requirements for this specification are captured in the Widgets 1.0 Requirements [Widgets-Reqs] document. This document addresses the following requirements:

Additionally, the following requirements are taken into account:

Restricted access to remote web resources

Security, Current development practice or industry best- practice, Interoperability.

A Widget may need to make use of external web services in order to function, for example using AJAX to obtain information.

A User Agent may wish to restrict access to external web services from Widgets based on white lists or black lists, for example using a proxy server or firewall.

This raises the possibility for users installing Widgets that are unable to function due to access restrictions on remote web services.

By providing a mechanism for declaring a Widget's access requirements, the usability and interoperability of Widgets can be improved.

For example, when a user attempts to install a Widget in a User Agent, and the Widget Configuration Document declares that it requires access to currently blocked services in order to function, the User Agent may prompt the user to choose to:

  1. enable access to the service (for example, adding the service to a proxy server or firewall white list),
  2. cancel installing the Widget, or
  3. proceed with installation, with the user now aware that there may be problems with the Widget due to restricted access to services.

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.

2 Policy

A widget runs in its own widget execution scope. Communication between that execution scope and the network is prohibited by default, but may be turned on selectively using the access element. This prohibition must apply equally to access through APIs (e.g. XMLHttpRequest) or through inlined content (e.g. iframe, script, img).

Scripts executing in that widget execution scope have access to feature-enabled APIs. Note that other mechanisms may provide access to the same APIs in other contexts, but that that is outside the scope of this specification.

When permission is selectively turned on to access a given set of network resources, it must be granted equally to APIs and inlined content.

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 web execution scope.

3 The access Element

The access element allows authors to request permission from the user agent to retrieve a set of network resources.

A user agent must prevent the widget execution scope from retrieving network resources, using any method (API, linking, etc.) and for any operation, unless the user agent has granted access to an explicitly declared access request.

However, 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.).

The access element is in the http://www.w3.org/ns/widgets namespace.

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


Required. A URI 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 resources through any and all schemes and protocols supported by the user agent.
Optional. A boolean attribute that indicates whether or not the host component part of the access request applies to subdomains of domain in the uri attribute. The default value when this attribute is absent is false, meaning that access to subdomains is not requested.

Usage example

This example shows the expected usage of the access element.

 xmlns ="http://www.w3.org/ns/widgets"
 width ="400"
 <name>Flight Tracker</name>
 <access uri="http://example.com/api/"/>
 <access uri="https://example.net"/>
 <access uri="http://example.org" subdomains="true"/>
 <access uri="http://example.com/dahut?bar"/>
 <access uri="*"/>

4 Processing model

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

Note: 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 IRIs specification include: ifragment , ipath, iuser info, and iquery.

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

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

Let uri be result of applying the rule for getting a single attribute value to the value of the uri attribute. If the result is a single U+002A ASTERISK (*) character, then prepend the a U+002A ASTERISK to the access-request list and skip all steps below.

If uri is not a valid URI, 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.

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.

If uri has an ifragment component, remove it from uri. Let scheme be the scheme component of uri. Let host be the host component of uri. Let port be the port component of uri or if there is no port component the default value for the protocol that corresponds to scheme. Let path be the ipath component of uri concatenated to the iquery component of uri.

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

If scheme is "http" or "https", then the value of host must be processed using the ToASCII algorithm as per [RFC3490], then decode, as per [URI], all percent-encoded parts of path that are unreserved characters.

Rule for Granting Access to a URI identifiable 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 rules are applied to determine what each access element is requesting access to.

  1. The request for access made by the access element is for network resources that have:

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. Note that if scheme is "http" or "https", host comparisons must be performed in a case-insensitive manner.

As a special case, the uri attribute may hold the value *. In that case, the access element is considered to request access to all network resources without limitation (e.g. retrieve RSS feeds from anywhere). If access is granted to such a request, then all other network access requests must be granted.


The editor would like to thank (in no particular order): the OMTP BONDI effort, Jere Kapyaho, Thomas Roessler, Art Barstow, Mohamed Zergaoui, Arve Bersvendsen, and Batman Caceres.

Normative References

Internationalized Resource Identifiers (IRIs). RFC3987, M. Duerst, M. Suignard. January 2005.
Uniform Resource Identifier (URI): Generic Syntax. RFC 3986, T. Berners-Lee, R. Fielding and L. Masinter. January 2005.
Internationalizing Domain Names in Applications (IDNA). RFC 3490, P. Faltstrom, et al. March 2003.
Widgets 1.0: Packaging and Configuration, M. Caceres. W3C, December 2008.

Informative References

Widgets 1.0 Requirements, M. Caceres. W3C, April 2009.
Widgets 1.0: Digital Signature. M. Caceres, . W3C, W3C Working Draft April 2009.
Widgets 1.0: Updates. M. Caceres. W3C Working Draft October 2008.
Widgets 1.0: APIs and Events. Arve Bersvendsen et al. W3C Working Draft 23 April 2009.
HTML 5. Ian Hickson et al. W3C Working Draft 23 April 2009.
Hypertext Transfer Protocol -- HTTP/1.1. RFC 2616, R. Fielding, et al. June 1999.
HTTP Over TLS. RFC 2818, E. Rescorla. May 2000.