Abstract
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 Introduction
- 1.1 Definitions
- 1.2 The Widget Family of Specifications
- 1.3 Design Goals and Requirements
- 2 Policy
- 3 The
access Element
- 4 Processing model
- Acknowledgements
- Normative References
- 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.
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
- Motivation:
-
Security, Current development practice or industry best-
practice, Interoperability.
- Rationale:
-
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:
-
enable access to the service (for example, adding the service to a
proxy server or firewall white list),
- cancel installing the Widget, or
-
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:
- Empty.
- Occurrences:
- Zero or more.
- Expected children:
- none.
- Localizable via
xml:lang:
- No.
Attributes
-
uri
-
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.
-
subdomains
-
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.
<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>
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.
-
The request for access made by the
access element is for network
resources that have:
- a scheme equal to scheme; and
-
if subdomains is
false, a host exactly equal to host;
and
-
if subdomains is
true, a host either exactly equal to
host, or that is a subdomain of host; and
- a port equal to port; and
- a path and query concatenation that is equal to path or begins with it.
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.
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, and Batman Caceres.
Normative References
- [RFC3987]
-
Internationalized Resource Identifiers (IRIs).
RFC3987, M. Duerst, M. Suignard. January 2005.
- [URI]
-
Uniform Resource Identifier (URI): Generic Syntax.
RFC 3986, T. Berners-Lee, R. Fielding and L. Masinter. January 2005.
- [RFC3490]
-
Internationalizing Domain Names in Applications (IDNA).
RFC 3490, P. Faltstrom, et al. March 2003.
- [Widgets-PC]
-
Widgets 1.0: Packaging and Configuration,
M. Caceres. W3C, December 2008.
- [Widgets-Reqs]
-
Widgets 1.0 Requirements, M. Caceres. W3C, April 2009.
- [Widgets-DigSig]
-
Widgets 1.0: Digital Signature. M. Caceres, . W3C, W3C Working Draft
April 2009.
- [Widgets-Updates]
-
Widgets 1.0: Updates. M. Caceres. W3C Working Draft October 2008.
- [Widgets-APIs]
-
Widgets 1.0: APIs and Events. Arve Bersvendsen et al.
W3C Working Draft 23 April 2009.
- [HTML5]
-
HTML 5. Ian Hickson et al.
W3C Working Draft 23 April 2009.
- [HTTP]
-
Hypertext Transfer Protocol -- HTTP/1.1.
RFC 2616, R. Fielding, et al. June 1999.
- [HTTPS]
-
HTTP Over TLS.
RFC 2818, E. Rescorla. May 2000.