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).
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 email@example.com (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.
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.
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
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
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.
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].
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:
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:
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.
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
XMLHttpRequest) or through inlined content (e.g.
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.
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
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
access element is in the
*) 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.
uriattribute. The default value when this attribute is absent is
false, meaning that access to subdomains is not requested.
This example shows the expected usage of the
<widget xmlns ="http://www.w3.org/ns/widgets" width ="400" height="500"> <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="*"/> </widget>
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.
access element that is a direct child of 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.
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
accesselement 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
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.