This document defines a security model for widgets, specifying which resources the widget is allowed and denied access to, and how the widget can signal which resources it intends to access.
It is assumed that widgets are not web pages and that in order to be useful they need a security model that is different from that of web pages.
Conceptually speaking a widget is "loaded" onto a computer before it is "run", and so its home domain is the computer on which it is running. In addition, many useful widgets accomplish their task by synthesizing information from various sources on the web. Thus the widget needs greater rights than normal web pages in order to access network resources. Yet the security concerns of unrestricted access cannot be ignored: The main concern is that a widget that accesses pages on an intranet can steal information, but there is also a general concern about leaking information about the widget user from one web site to another.
This document specifies what widgets are normally allowed to do, how they can be granted greater privileges, and how their privileges can be curtailed. Actions are controlled by reasonable defaults, with overrides from the user or system administrator, and checked against the behavior the widget declares itself to have.
A widget's config.xml file may contain a "security specification": a declaration of the protocols, hosts, ports, and pages that the widget will normally attempt to access. It may also contain declarations of other things that the widget will do.
The security specification is represented as the "security" element in the config.xml file. Additional local settings for widgets are specific to the system.
This specification does not concern itself directly with signing, but an implementation of signatures may use different policy documents based on the identity provided by a signature, thus granting different privileges based on said signature.
Latent widgets are identified by URLs that reference zip files on hosts on the Internet. (They can also be identified by a path in the file system to a config.xml file.) A widget is loaded into the user agent by loading the URL of the zip or config.xml file.
Once the zip file is loaded, a running widget instance will normally be created in a vendor-specific manner.
The widget runner may be suspended, and running widget instances are suspended with it. Only when the user explicitly kills the instance are it's data deleted.
The widget instance is unique in the universe. There is no notion at all of two widget instances being "the same". No information in the config.xml file or in the URL from which the zip file is loaded has any bearing on widget identity.
Note that while upgrades is not directly covered in this specification, any future upgrade mechanism should display a warning/confirmation prior to upgrading. If the security settings of the widget will change during such an upgrade process, and in such a way that the network privileges change, or the widget asks for additional APIs to be enabled, such a warning should be displayed, with an option to inspect the new security settings.
Separate widget instances share no information at all. Specifically:
The access rights model determines whether a widget should be allowed to access any particular URL, where "access" means the following:
The rules for accessing the network are determined based on the following components:
This specification describes two classes of networks, a default "private" network, and a public network.
A private network, or local network is by default defined as the user's local machine, including any IP address that resolves to the local machine. Further, the IP ranges as defined by [RFC 1918], are considered to be private. These addresses are primarily being used in systems set up behind a NAT translation device, and provides machines with unique addresses where there is only one public IP address for several machines. These addresses are:
10.0.0.0 - 10.255.255.255 (10/8 prefix)
172.16.0.0 - 172.31.255.255 (172.16/12 prefix)
192.168.0.0 - 192.168.255.255 (192.168/16 prefix)
In addition, when a user is within an ad-hoc network, networking equipment (including software components in operating systems), typically use the IPv4 Link-Local addresses as defined by [RFC 3927], which is also considered to be part of the local network.
169.254.0.0 - 169.254.255.255 (169.254/16 prefix)
A widget runner should provide a default configuration wherein the four network ranges described above are defined to fall within the private IP range. As stated above, this policy may be editable, may be possible to add or remove items to the list of private networks and hosts.
When a widget wants to request access to resources, it does so by adding a security fragment to the config.xml element, as specified below:
element security optional
element access multiple
element "protocol" multiple
cdata
element "host" multiple
cdata
element "port" multiple
cdata
element "path" multiple
cdata
element "content"
attribute "plugin" value = "yes|no"
The access element is used to specify the access permissions of the widget. The element. If the contents of the access element is empty, then a widget would not be granted access. With the exception of the 'protocol' element, the absence of an element means the same as "match all", granting access to all resources not limiting access.
The host element is a syntactical construct used to determine which hosts a widget can contact. The element is defined as such
element host
attribute type optional value="localhost|string|range"
cdata
The type attribute determines which kind of matching is done for the host element:
If the 'type' attribute is omitted from any declaration, it is assumed to be present, with the value 'string'
The protocol element is used to determine which protocols a widget should have access to. When missing from config.xml, the element is assumed to be present three times, with the values 'widget', 'http' and 'https'. When missing from any other context, the element gets no value, and for instance if missing from 'access', a widget would not be allowed to get network access.
The port element is used to define which port numbers a widget should have access to when initiating network traffic. The port element accepts as its value a single port number, port numbers separated by a comma, or a range of ports separated using '-'.
When missing from an 'access' element, the port element is assumed to be present, matching all ports, and when a widget requests access to a resource using http, it can do so on every port. It should however be noted that there are certain port numbers for which the User Agent may have disabled access for security reasons, and a configuration override cannot change these.
When a different port number is specified for a protocol in an access element, the port numbers specified are the only by which a widget can communicate.
The path element is used to restrict widget access to particular paths within the rule sets. When missing from anywhere within widget configuration, or policy file, the element is assumed to be present, allowing access to any path, thus implicitly bearing the value "/".
The path is treated as a wildcard path, allowing access to any matching subpath of the element. In the following access fragment, placed within config.xml, access to any resource contained within the "/cats" subpath is allowed:
<path>/cats</path>
thus, the widget can access all of
/cats/siamese.html
/cats/
/catsoup
In the case that the author of the config.xml fragment meant to limit access to '/cats/', the specification of the path would have to include the forward slash:
<path>/cats/</path>
A widget must declare its intention with regard to API and network access through the config.xml file, using the syntax described in the below config.xml fragment:
element widget
attribute "network" optional value = "public|&private"
To acquire access to the network, the widget must thus declare this by adding the network attribute to the widget element in the widget's config.xml file. The value accepted for this attribute is a list of DOMStrings that can specify which network class it intends to access. The values are case sensitive. Valid values are:
It is assumed that a security mechanism exists in the widget user agent to enforce a policy where a separation between the two network classes exist, and optionally lock access to either of the resources after first access has taken place, so that a widget that has for instance accessed the public network can no longer access the private network.
When a widget starts, The user agent reads this configuration, and compares it to the User Agent's internal configuration.
The term 'URL access' specifies any access to a networked resource a widget may attempt. This includes:
If a widget, by configuration, excplicitly requires access to a resource forbidden by other configuration, installation of the widget should fail.
If a widget attempts to contact a resource that is in conflict with the widget's own stated security policy, or the widget attempts to contact a resource which it has been restricted from accessing (such as accessing a private network resource when it has only requested access to public network resources), it should fail in one of two ways:
The algorithm for allowing access to the private network is as such:
The same algorithm is also applied separately to the public network.
When the widget requests access to both types of network, apply the following algorithm
In the case that any step in the above processes has resulted in "Deny access", deny access. Otherwise allow access.
When a widget attempts to contact a resource, and this resource has been allowed by the network class above, the URL that is attempted accessed is compared to a whitelist and/or a blacklist on the system, that contains a componentized list of URLs.:
A leap of faith is required to understand how this works, but the general idea is that domains have to match, while separate subdomains want. Assume that the black/whitelists support wildcards. Assume that the same lists supports both IP ranges and port ranges.