Copyright © 2009 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/.
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.
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.
This specification is part of the Widgets Family of Specifications.
This document was published by the Web Applications WG as a Last Call Working Draft. 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). The Last Call period ends 13 January 2010. All feedback is welcome.
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.
This is a Last Call Working Draft and thus the Working Group has determined that this document has satisfied the relevant technical requirements and is sufficiently stable to advance through the Technical Recommendation process.
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. The
network resources and author requests to access are identified
using access
elements in the widget's configuration document.
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 that implement the interfaces that it contains.
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 may grant access to network resources listed in the access-request list; in this case the user agent must 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 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
*
) may be used. This special value provides a means for an
author to request from the user agent unrestricted access to
network resources. Only the scheme
and authority components can be present in the IRI that this
attribute contains ([URI], [RFC3987]).
subdomains
origin
attribute. The default value when this attribute is absent is
false
, meaning that access to subdomains is not requested.
This example contains multiple uses of the access
element (not contained in
the same configuration as the last one would make the others useless). They presume that
http://www.w3.org/ns/widgets
is the default namespace defined in their context:
<access origin="https://example.net"/> <access origin="http://example.org" subdomains="true"/> <access origin="http://dahut.example.com:4242"/> <access origin="*"/>
access
elements in the Configuration DocumentA user agent must add the following to the Table of Configuration Defaults [WIDGETS].
Variable | Type | Default Value | Overridden in | Description |
---|---|---|---|---|
access-request list | List | null |
Processing access elements in the Configuration Document |
The list of items extracted from access elements to which the user agent
will grant access.
|
This processing takes place as part of Step 7 - Process the Configuration Document in [WIDGETS].
Let access-request list be an empty list of objects that represent the author's access requests to network resources.
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.
For each access
element that is a direct child of the widget
element:
origin
attribute is absent, then this element is
in error and
the user agent must ignore it.
origin
attribute. If the result is a
single U+002A ASTERISK (*
) character, then prepend the U+002A ASTERISK to
the access-request list and skip all steps below.
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.
http
" or "https
", then the value of host
must be processed using the ToASCII algorithm as per
[RFC3490].
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
, 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; 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.
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, and Batman Càceres.