Copyright © 2009-2010 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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.
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.
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.
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.
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.
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].
widget element [WIDGETS].xml:lang:origin
subdomains
origin attribute. The default value when this
attribute is absent is false, meaning that access to subdomains is not requested.
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="*"/>
access elements in the Configuration DocumentFirstly, 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.
| 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].
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.
Let element be the access element to be processed.
If the origin attribute is absent, then this element is
in error and
the user agent must ignore this element.
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.
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.
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.
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.
If scheme is unsupported by the user agent, then this element is in error and the user agent must ignore this element.
If scheme is "http" or "https", then the user agent must process the value of host
using the ToASCII algorithm as per
[RFC3490].
The user agent must append an item inside the access-request list that is the tuple: scheme, host, port, sub domains.
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:
false or if the URI's host component is not a domain
name (as defined in [RFC1034]), the URI's host component is
the same as host; or
true, the URI's host component is
either the same as host, or is a subdomain of host (as defined in [RFC1034]); and
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.
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.
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.