Widget Updates

Table of Contents

• 1. Introduction
• 2. Conformance
• 3. Definitions
  • 3.1 Value types
• 4. Extensions to Configuration Document
  • 4.1 The update-description Element
    • 4.1.1 Attributes
    • 4.1.2 Usage example
  • 4.2 Processing update-description elements in the Configuration Document
• 5. Update Description Document
  • 5.1 Example Update Description Document
  • 5.2 Namespace
  • 5.3 The update-info Element
    • 5.3.1 Attributes
    • 5.3.2 Usage example
  • 5.4 The details Element
    • 5.4.1 Usage example
• 6. Acquiring an Update Description Document
• 7. Processing an Update Description Document
• 8. Verifying and Installing an Update
• 9. Security Considerations
• A. Design Goals and Requirements
• B. Acknowledgements
• C. References
  • C.1 Normative references
  • C.2 Informative references

2. 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 requirements for a single class of product: user agents.

3. Definitions

The concepts of a widget package and a configuration document are defined in the [WIDGETS] specification.

A user agent is an implementation of this specification that also implements the [WIDGETS] specification and its dependencies.

An installed widget is a widget package that has been correctly installed on a user agent.

An update description source is the URI referenced by the href attribute of an update-description element of an installed widget's configuration document.

An update description document is an [XML10] document that has a update-info element at its root.

An update source is the URI referenced by the src attribute of an update-info element of an update description document.

A potential update is a resource acquired via HTTP from an update source or from local media.

The widget update process is a multi-step process whereby a user agent acquires a potential update, performs the rule for verifying a widget update, and then proceeds to install the widget package.

The identity of a widget package is determined by the id attribute of the widget element declared by an author in the configuration document of a widget package.

The version of a widget package is determined by the version attribute of the widget element declared by an author in the configuration document of a widget package.

An incumbent widget is an installed widget that is determined to have the same identity as the potential update.

An installed widget is said to be up-to-date if a user agent determins that an incumbent widget does not need updating.

A failure notification is an optional message emitted by the user agent to indicate to the user that a widget update has failed.

Note: This specification does not define the means or format of a failure notification, which is left up to implementers.

4. Extensions to Configuration Document

<widget xmlns  ="http://www.w3.org/ns/widgets" 
        id     ="http://example.com/my-widget" 
        version="1.0">

<update-description 
   href="http//example.com/update?widget=my-widget&amp;version=1.0"/>

</widget>

5. Update Description Document

Within an update description document an author declares, amongst other things, what's new or different in the potential update, the version that the widget will be updated to, and the URI from where the user agent can retrieve the potential update (the update source).

The purpose of the update description document is to provide the details about a potential update, including a pointer to a HTTP resource that will act as the potential update.

In order for a user agent to retrieve and process an update description document, an author must initially declare a valid URI for the update-description element in the installed configuration document (e.g. <update-description href="https://example.com/myWidget/updates"/>).

<update-info xmlns   = "http://www.w3.org/ns/widgets"
             src     = "https://w.example.com/2.1/RC/app.wgt"
             version = "RC2.1">

  <details>
    Now supporting X, Y and Z features!
  </details>
</update-info>

<update-info xmlns="http://www.w3.org/ns/widgets"
             src="http://sometld/somewidget_0_3_BETA.wgt"
             version="BETA 0.3">
           
</update-info>

<update-info xmlns="http://www.w3.org/ns/widgets"
             src="http://foo.com/widget.wgt"
             version="1.3.1">
  <details>
    This update tries to make 2010 a little bit less like "1984".
  </details>
</update-info>

6. Acquiring an Update Description Document

The authoritative update URI is the update source of an installed widget's configuration document.

A user agent must support the capability to acquire an update description document over HTTP protocols. For non-HTTP protocols, UAs should act in equivalent ways.

It is expected that user agents will perform a widget update process asynchronously and periodically check for any available updates. The timing of any widget update process is an implementation detail left to the discretion of the implementer (e.g. once a day or once a week).

To check for updates to a widget, the user agent issues a HTTP request towards the authoritative update URI.

The user agent should send the last known ETag response value, if available, in an If-None-Match header.

The user agent should send an If-Modified-Since header indicating the time of the last check for an update from the user agent.

If the widget is displaying localized content, the user agent should send an Accept-Encoding header representing the widget's locale.

As data is received, the user agent will then act as follows.

The user agent should ignore any Cache-Control or Pragma header with a value of no-cache.

The user agent should honor the value of any Expires header when scheduling the next widget update process for the current installed widget.

HTTP 200 OK responses with a Content-Type header specifying the type application/xml must be processed according to the rules defined in Processing an Update Description Document.

HTTP 200 OK responses that have a Content-Type other than application/xml must cause the user agent to terminate the widget update.

HTTP 204 No Content, 205 Reset Content, and 304 Not Modified responses are equivalent to 200 OK responses with a Content-Type other than application/xml.

Other HTTP response codes in the 2xx range must terminate the widget update. They are, however, likely to indicate an error has occurred somewhere and may cause the user agent to emit a warning.

HTTP 301 Moved Permanently, 302 Found, 303 See Other, and 307 Temporary Redirect responses must cause the user agent to reconnect using the new server specified URL instead of the previously specified URL.

HTTP 305 Use Proxy, 401 Unauthorized, and 407 Proxy Authentication Required should be treated transparently as for any other subresource.

Any other HTTP response code not listed here, and any network error that prevents the HTTP connection from being established in the first place (e.g. DNS errors), must cause the user agent to terminate the widget update.

7. Processing an Update Description Document

A user agent must assume the following defaults prior to processing an update description document:

A user agent must process an update description document according to the rule for processing an update description document.

The following processing model is written with more concern for clarity over efficiency. As such, a user agent can optimize the processing model so long as the end result is indistinguishable from the result that would be obtained by the following the specification.

The term in error, typically used on an element or attribute, means that the element, attribute, or other construct does not conform to the rules of this specification. Rules for exactly how a user agent needs to treat the erroneous construct are always given when the term is used.

When an invalid update description document is determined, the user agent must terminate the current widget update process.

The rule for processing an update description document is defined as follows:

1. Let doc be the result of parsing the acquired update description document as a [DOM-LEVEL-3-CORE] Document using a [XML-NAMES]-aware parser. If the document is not well-formed [XML10], then treat this as an invalid update description document.
2. Let root element be the documentElement of doc.
3. If the root element is not a update-info element in the widget namespace, then treat this update description document as an invalid update description document.
4. If the root element is a update-info element:
   1. If the version attribute was used, and it is a valid version-tag, then let version-tag be the value of version.
   2. If no version attribute was used, or the value was in error, treat this as an invalid update description document.
   3. If the src attribute was used, and it is a valid URI, then let update-source be the value of src.
   4. If no src attribute was used, or the value was in error, treat this as an invalid update description document.
5. For any child element of the root element:
6. 1. If the child element is a details element:
      1. If this is not the first details element, then the element is in error and must be ignored.
      2. Let details be the result of applying the rule for getting text content [WIDGETS] to this element.
   2. Otherwise it must be ignored.

8. Verifying and Installing an Update

When a user agent is to install the widget package it must remove any incumbent widget and add the potential update as an installed widget.

When a user agent is to terminate the widget update the user agent must terminate the current widget update process. The user agent may emit a failure notification warning that the widget update has been terminated.

To verify and install a potential update the user agent must apply the rule for verifying a widget update.

The rule for verifying a widget update enables a user agent to match and verify a potential update - acquired via HTTP or from local media - with an installed widget package and is defined as follows:

1. Apply the steps for processing a widget package [WIDGETS] to the obtained potential update.
   • If an invalid widget package [WIDGETS] is detected, the user agent must terminate the widget update.
2. If an incumbent widget could not be found then skip the rest of this rule and install the widget package.
3. If the incumbent widget has the same version as the potential update then the installed widget is up-to-date and the user agent must terminate the widget update.
4. If the potential update is determined to be a digitally-signed widget package when applying the rules for signature validation [WIDGETS-DIGSIG] then the user agent will act as follows:
   • If the incumbent widget is also determined to be a digitally-signed widget package when applying the rules for signature validation [WIDGETS-DIGSIG] then the user agent will act as follows:
     1. Let update_digsigs be an enumerated list of all the digital signatures contained within the potential update obtained according to the rule to locate signature files in a widget package [WIDGETS-DIGSIG].
     2. If any of the elements within update_digsigs were determined to be in error then terminate the widget update.
     3. Let incumbent_digsigs be an enumerated list of all the digital signatures contained within the incumbent widget obtained according to the rule to locate signature files in a widget package [WIDGETS-DIGSIG].
     4. If any of the elements within incumbent_digsigs were determined to be in error then terminate the widget update. This is, however, likely to indicate an error has occurred somewhere in the installed widget package processing and may cause the user agent to emit a warning.

     Note: The decision of which (if any) distributor signatures are to be validated and whether the author signature is to be validated is out of scope [WIDGETS-DIGSIG].

     5. For each update_signature to be validated in update_digsigs:
        1. Let digSigsMatch be the result of comparing the dsp:Identifier value [WIDGETS-DIGSIG] from update_signature with the same value obtained from the associated incumbent_signature within incumbent_digsigs.
        2. If digSigsMatch is false then terminate the widget update.
5. The user agent must install the widget package.

9. Security Considerations

Because an update description document is not self-contained, it is conceivable that the update model could be subject to a man-in-the-middle attack, as with any unencrypted requests performed over [HTTP11]. For this reason, it is recommended that, for widgets that have not been digitally signed, updates are always performed over [HTTP-TLS].

Another means of protection is for authors to always digitally sign their widget resources. During an update, the user agent will then validate the signature before installation, ensuring that a widget resource's identity and integrity was maintained over the network.

Without the availability of a digitally signed installed widget, it is extremely easy to overwrite a widget resource with another (potentially malicious) widget resource. Therefore it is recommended that a user agent only allow updates to a signed installed widget or to a non-signed installed widget only from a potential update obtained via its authoritative update URI.