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 18 June 2009 First Public Working Draft version of the "Widgets 1.0: Access Requests" specification. This version was forked out of "Widgets 1.0: Packaging and Configuration" in order to allow the group to focus on this specific issue without delaying further work on the rest of the widget stack. The purpose of this draft is to give external interested parties an opportunity to publicly comment on how access requests should work within widgets before the Working Group moves this specification to Last Call. 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
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 schemes
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 addressed 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 (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
access element (e.g. based on a
security policy, user prompting, etc.).
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
*) 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 "
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 access to.
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 "
host comparisons must be performed in a
As a special case, the
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.