Abstract

This specification defines the security model controlling network access from within a widget, as well as a method for 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 is the 07 February 2012 Recommendation of the Widget Access Request Policy specification. This document is produced by the Web Applications WG, part of the Rich Web Client Activity in the W3C Interaction Domain.

This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.

The public is encouraged to send comments to the WebApps Working Group's public mailing list public-webapps@w3.org (archive).

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.

Table of Contents

• 1. Introduction
  • 1.1 Design Goals and Requirements
• 2. Definitions
• 3. Conformance
• 4. User Agent
• 5. Policy
• 6. The access Element
  • 6.1 Attributes
  • 6.2 Usage example
• 7. Processing access elements in the Configuration Document
• 8. Rules for Granting Access to a Network Resource
• Changes since last publication
• Normative references
• Informative references

1. Introduction

This section is non-normative.

The purpose of this specification is to define a security model for widgets allowing them to access content on one or more domains. To achieve this purpose, the specification defines a default security policy, which blocks all network access, and a declarative means for an author to request access to specific resources across one or more network domains. By requesting access to specific domains, the author is able to change the default security policy to make it less restrictive.

1.1 Design Goals and Requirements

The design goals and requirements for this specification are addressed in the Requirement For Standardizing Widgets [WIDGETS-REQS] document. This document addresses the following requirements:

• Default Security Policy
• Security Declarations
• Restrict access to external resources (to be published)

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. Definitions

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 authorizes 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.

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.

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.

3. Conformance

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: a user agent.

4. User Agent

A user agent a software application that implements this specification and the [WIDGETS] specification and its dependencies.

At runtime, when a request is made to access a network resource from within the widget execution scope, the user agent must compare the request against the Rules for Granting Access to a Network Resources.

If scheme is "http" or "https", the user agent must compare hosts in a case-insensitive manner.

5. Policy

A user agent enforces an access request policy. However, how a user agent enforces a policy is beyond the scope of this specification: this specification does not define any data indicative of a security event, which is left up to other specifications (e.g., [XMLHTTPRequest] defines its own security errors which is indicative of a security event).

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 user agent may apply a different default policy if the widget is being used in a context that defines its own policy, such as for instance a widget served over HTTP.

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] 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.

6. The 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. When multiple access elements are used by an author, the set of network connections that are allowed is the union of all the access requests that were granted by the user agent.

The access element is in the http://www.w3.org/ns/widgets namespace as defined in [WIDGETS].

Context in which this element is used:

As a child of the widget element [WIDGETS].

Content model:

Empty.

Occurrences:

Zero or more.

Expected children:

none.

Localizable via xml:lang:

No.

6.1 Attributes

origin

An IRI attribute that defines the specifics of the access request that is made. Only the scheme and authority components can be present in the IRI that this attribute contains ([URI], [RFC3987]). Additionally, an author can use the special value of U+002A ASTERISK (*). This special value provides a means for an author to request from the user agent unrestricted access to network resources.

subdomains

A boolean attribute that indicates whether or not the host component part of the access request applies to subdomains (as defined in [RFC1034]) of domain in the origin attribute. The default value when this attribute is absent is false, meaning that access to subdomains is not requested.

6.2 Usage example

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://foo.example.com using the http protocol (port 4242):

<access origin="http://dahut.example.com:4242"/>

Access request to all network resources:

<access origin="*"/>

7. Processing access elements in the Configuration Document

When processing access elements in the configuration document, a user agent behaves as if the following had been defined in the Table of Configuration Defaults in Step 3 of the [WIDGETS] specification.

Table of Configuration Defaults (addendum)

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].

Rule for processing an 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.

1. Let element be the access element to be processed.

2. If the origin attribute is absent, then this element is in error and the user agent must ignore this element.

3. 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.

4. 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.

5. If the subdomains attribute is absent, then let sub domains be the value false. Otherwise, or 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 let sub domains be the value false.

6. Let scheme be the scheme component of origin. Let host be the host component of origin. Let port be the port component of origin. If there is no port component, the user agent must use the default value for the protocol that corresponds to scheme.

7. If scheme is unsupported by the user agent, then this element is in error and the user agent must ignore this element.

8. If scheme is "http" or "https", then the user agent must process the value of host using the ToASCII algorithm as per [RFC3490].

9. The user agent must append an item inside the access-request list that is the tuple: scheme, host, port, sub domains.

8. Rules for Granting Access to a Network Resource

The following rules for granting access to a network resource is applied to determine what each access element is requesting access to:

1. If the access-request list contains an item that is just the U+002A ASTERISK (*) character, then all access requests are granted.

2. An access request is granted for a given URI if there exists an item inside the access-request list such that:

   • The URI's scheme component is the same as scheme; and

   • if subdomains is 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

   • if subdomains is true, the URI's host component is either the same as host, or is a subdomain of host (as defined in [RFC1034]); and

   • the URI's port component is the same as port.

Normative references

[RFC1034]

Domain Names - Concepts and Facilities. IETF.

[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels. IETF.

[RFC3490]

Internationalizing Domain Names in Applications (IDNA). IETF.

[RFC3987]

Internationalized Resource Identifiers (IRIs). IETF.

[URI]

Uniform Resource Identifiers (URI): generic syntax. IETF.

[WIDGETS]

Widget Packaging and XML Configuration. W3C.

Informative references

[HTML]

HTML5 (Work in progress). W3C.

[WIDGETS-REQS]

Requirements For Standardizing Widgets. W3C.

[XHR]

XMLHttpRequest (Work in progress). W3C.