diff --git a/updates/Overview.html b/updates/Overview.html index f90c44c..d963336 100644 --- a/updates/Overview.html +++ b/updates/Overview.html @@ -7,13 +7,6 @@ - +

- W3C + W3C

Widget Updates

@@ -204,7 +197,7 @@

W3C Copyright © - 2013 + 2013 W3C® (MIT, @@ -218,9 +211,9 @@

W3C

-

Abstract

+

Abstract

- This specification defines a process and a document format to allow a user agent to update an installed widget package with + This specification defines a process and a document format to allow a user agent to update an installed widget package with a different version of a widget package. A widget cannot automatically update itself; instead, a widget relies on the user agent to manage the update process.

Status of This Document

@@ -300,51 +293,51 @@

W3C

Table of Contents

Table of Contents

+
  • C. References

    • -
    +

    1. Introduction

    This section is non-normative.

    @@ -360,12 +353,12 @@

    W3CSometimes an author may even want to revert back to a previous version of an application, if it is found that a newly deployed version of a application contains issues or vulnerabilities.

    To facilitate the process of updating widgets, this specification introduces an XML element, called - an update description source, that is included as an Extension to the Configuration Document - of a widget package. This specification also introduces a new XML vocabulary, called an update description document. The update description source - provides an author with a means to point to an update description document. + an update description source, that is included as an Extension to the Configuration Document + of a widget package. This specification also introduces a new XML vocabulary, called an update description document. The update description source + provides an author with a means to point to an update description document.

    - An update description document is metadata about a widget update including: + An update description document is metadata about a widget update including:

    - If a user agent determines, after Acquiring an Update Description Document and + If a user agent determines, after Acquiring an Update Description Document and during Processing an Update Description Document, that two widget packages are not the - same version, and if the user consents, the user agent will attempt to replace the currently installed widget with the - potential update. Updates are designed to retain any locally stored data, so to protect end-users from losing data that a + same version, and if the user consents, the user agent will attempt to replace the currently installed widget with the + potential update. Updates are designed to retain any locally stored data, so to protect end-users from losing data that a widget may have stored at runtime.

    - A user agent must support the capability to acquire an update description document over HTTP protocols. For non-HTTP + 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.

    @@ -407,12 +400,12 @@

    W3C

    - 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]. + 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. + This specification defines conformance requirements for a single class of product: user agents.

    @@ -420,79 +413,79 @@

    W3C

    - The concepts of a widget package, a configuration document, a valid IRI, a version attribute, user agent locales, global attributes and the definition that one element is allowed per language are defined in the [WIDGETS] specification. + The concepts of a widget package, a configuration document, a valid IRI, a version attribute, user agent locales, global attributes and the definition that one element is allowed per language are defined in the [WIDGETS] specification.

    - A user agent is an implementation of this specification that also implements the [WIDGETS] specification and its + 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 [WIDGETS] that has been correctly installed and currently resides on or within a user agent. + An installed widget is a widget package [WIDGETS] that has been correctly installed and currently resides on or within a user agent.

    An update description source is the URI pointing to the location of an update description document.

    - An update description document is an [XML10] document that has a update-info element at its root. + 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 within an - update description document. + update description document.

    - A potential update is a resource acquired via HTTP (from an update source) or from local media. + 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 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 [WIDGETS] is determined by the id attribute of the widget - element declared by an author in the configuration document [WIDGETS] of a widget package [WIDGETS]. + The identity of a widget package [WIDGETS] is determined by the id attribute of the widget + element declared by an author in the configuration document [WIDGETS] of a widget package [WIDGETS].

    - The version of a widget package [WIDGETS] is determined by the version attribute of the widget - element declared by an author in the configuration document [WIDGETS] of a widget package [WIDGETS]. + The version of a widget package [WIDGETS] is determined by the version attribute of the widget + element declared by an author in the configuration document [WIDGETS] of a widget package [WIDGETS].

    - An incumbent widget is an installed widget that is determined to have the same identity as the - potential update. + 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 determines that an incumbent widget does not need + An installed widget is said to be up-to-date if a user agent determines 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 + 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. + Note: This specification does not define the means or format of a failure notification, which is left up to implementers.

    4. Update Extensions to Widget Configuration Documents

    - This specification introduces a new element, called the update-description element, for inclusion in a widget's configuration document [WIDGETS]. + This specification introduces a new element, called the update-description element, for inclusion in a widget's configuration document [WIDGETS].

    4.1 The update-description Element

    - The update-description element points, via the href attribute, to an update description + The update-description element points, via the href attribute, to an update description document.

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

    Context in which this element is used:
    - As a child of the widget element defined in the [WIDGETS] specification. + As a child of the widget element defined in the [WIDGETS] specification.
    Content model: @@ -528,7 +521,7 @@

    4.1.1 href

    - A valid IRI [WIDGETS] that points to the location of an update description document. + A valid IRI [WIDGETS] that points to the location of an update description document.
    @@ -554,14 +547,14 @@

    4.2 Processing update-description elements in the Configuration Document

    - The user agent MUST process a configuration document [WIDGETS] containing an update-description element according - to the rule for processing the update-description element. + The user agent MUST process a configuration document [WIDGETS] containing an update-description element according + to the rule for processing the update-description element.

    The rule for processing the update-description element is defined as follows.

      -
    1. A user agent MUST add the following to the Table of Configuration Defaults [WIDGETS] during Step 3 - Set the Configuration defaults.
      2. +
    2. A user agent MUST add the following to the Table of Configuration Defaults [WIDGETS] during Step 3 - Set the Configuration defaults.
    - +
    @@ -598,18 +591,18 @@

    4.2 Processing update-description elements in the Configuration Document

    Table of Configuration Defaults (addendum)
    - The URI for where the widget's update description document can be downloaded, corresponding to the update-description element's + The URI for where the widget's update description document can be downloaded, corresponding to the update-description element's href attribute.

     

      -
    1. During Step 7 - Process the Configuration Document, if this is not the first update-description element, then the user agent MUST ignore this +
    2. During Step 7 - Process the Configuration Document, if this is not the first update-description element, then the user agent MUST ignore this element and its descendants.
    3. If this is the first update-description element and the href attribute is used, and it is a - valid IRI [WIDGETS], then let update href be the value of the href attribute. - Otherwise, this element is in error and the user agent MUST ignore this element.
      4. + valid IRI [WIDGETS], then let update href be the value of the href attribute. + Otherwise, this element is in error and the user agent MUST ignore this element.
    @@ -618,17 +611,17 @@

    4.2 The 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 update source from where the user agent can retrieve - the potential update. + 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 update source from where the user agent can retrieve + the potential update.

    - 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. + 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 will initially declare a - valid IRI [WIDGETS] for the update-description element in the installed configuration document (e.g. + In order for a user agent to retrieve and process an update description document, an author will initially declare a + valid IRI [WIDGETS] for the update-description element in the installed configuration document (e.g. <update-description href="https://example.com/myWidget/updates"/>), as defined in the Update Extensions to Widget Configuration Documents section.

    @@ -636,7 +629,7 @@

    5.1 Example Update Description Document

    - Below is an example of a typical update description document. + Below is an example of a typical update description document.

    Example 2
    <update-info xmlns   = "http://www.w3.org/ns/widgets"
              src     = "https://w.example.com/2.1/RC/app.wgt"
@@ -657,8 +650,8 @@ 
    5.2 
           Namespace
         
    
         
    
-          All elements defined to be used in an update description document are in the http://www.w3.org/ns/widgets
-          namespace as defined in [WIDGETS].
+          All elements defined to be used in an update description document are in the http://www.w3.org/ns/widgets
+          namespace as defined in [WIDGETS].
    @@ -666,7 +659,7 @@

    5.3 The update-info Element

    - The update-info element is intended to provide metadata about the potential update. In addition, it serves as + The update-info element is intended to provide metadata about the potential update. In addition, it serves as a container for the other elements.

    @@ -674,7 +667,7 @@

    5.3 Context in which this element is to be used:
    - The root element of an update description document. + The root element of an update description document.
    Content model: @@ -692,7 +685,7 @@

    5.3 Expected children:

    - details. + details.
    Localizable via xml:lang: @@ -710,13 +703,13 @@

    5.3.1 version

    - A valid version tag that denotes the version number of the potential update. + A valid version tag that denotes the version number of the potential update.
    src
    - A valid IRI [WIDGETS] that references a potential update. Over the wire, the potential update MUST be labeled with + A valid IRI [WIDGETS] that references a potential update. Over the wire, the potential update MUST be labeled with a correct widget media type (i.e. application/widget).

    @@ -740,7 +733,7 @@

    5.4 The details Element

    - The details element represents a human-readable description of what differentiates this potential update from + The details element represents a human-readable description of what differentiates this potential update from other versions.

    @@ -772,11 +765,11 @@

    5.4 Localizable via xml:lang:
    - Yes (one element is allowed per language). + Yes (one element is allowed per language).

    - All global attributes [WIDGETS], in particular xml:lang and dir attributes, can be applied to this element. + All global attributes [WIDGETS], in particular xml:lang and dir attributes, can be applied to this element.

    5.4.1 @@ -806,62 +799,62 @@

    5.4.1 Acquiring an Update Description Document

    - 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. + 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 update description source. + To check for updates to a widget, the user agent issues a HTTP request towards the update description source.

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

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

    - The user agent MUST send an Accept-Language header representing the widget's locale. + The user agent MUST send an Accept-Language header representing the widget's locale.

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

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

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

    - The user agent MUST process HTTP 200 OK responses, with a Content-Type header specifying the type application/xml, + The user agent MUST process HTTP 200 OK responses, with a Content-Type header specifying the type application/xml, according to the rules defined in Processing an Update Description Document.

    - The user agent MUST terminate the widget update on HTTP 200 OK responses that have a Content-Type other than application/xml. + The user agent MUST terminate the widget update on HTTP 200 OK responses that have a Content-Type other than application/xml.

    - On receiving HTTP 204 No Content, 205 Reset Content, and 304 Not Modified responses, the user agent MUST terminate the widget update. + On receiving HTTP 204 No Content, 205 Reset Content, and 304 Not Modified responses, the user agent MUST terminate the widget update.

    - On receiving HTTP response codes in the 2xx range, other than HTTP 200 OK, the user agent 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. + On receiving HTTP response codes in the 2xx range, other than HTTP 200 OK, the user agent 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.

    - On receiving HTTP 301 Moved Permanently, 302 Found, 303 See Other, and 307 Temporary Redirect responses, the user agent MUST reconnect using the new server + On receiving HTTP 301 Moved Permanently, 302 Found, 303 See Other, and 307 Temporary Redirect responses, the user agent MUST reconnect using the new server specified URL instead of the previously specified URL.

    - The user agent SHOULD treated HTTP 305 Use Proxy, 401 Unauthorized, and 407 Proxy Authentication Required responses transparently as for any other + The user agent SHOULD treated HTTP 305 Use Proxy, 401 Unauthorized, and 407 Proxy Authentication Required responses transparently as for any other subresource.

    - On receiving an HTTP 410 Gone response, the user agent must terminate the widget update and remove the installed widget. + On receiving an HTTP 410 Gone response, the user agent must terminate the widget update and remove the installed widget.

    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. + first place (e.g. DNS errors), must cause the user agent to terminate the widget update.

      @@ -872,9 +865,9 @@

    5.4.1 Processing an Update Description Document

    - A user agent MUST assume the following defaults prior to processing an update description document: + A user agent MUST assume the following defaults prior to processing an update description document:

    - +
    @@ -938,11 +931,11 @@

    5.4.1

    Update Defaults

    - A user agent MUST process an update description document according to the rule for processing an update + 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 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 following the specification.

    @@ -952,46 +945,46 @@

    5.4.1 always given when the term is used.

    - When an invalid update description document is determined then the user agent MUST terminate the widget update. + When an invalid update description document is determined then the user agent MUST terminate the widget update.

    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. + 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. + 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 attribute [WIDGETS], then let version-tag + If the version attribute was used, and it is a valid version attribute [WIDGETS], 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 + 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 relative URL, then let - update-source be the absolute valid IRI [WIDGETS] value of src relative to the current - update description document's IRI. + update-source be the absolute valid IRI [WIDGETS] value of src relative to the current + update description document's IRI.
      4. - If the src attribute was used, and it is an absolute valid IRI [WIDGETS], then let + If the src attribute was used, and it is an absolute valid IRI [WIDGETS], then let update-source be the value of src.
      5. - If no src attribute was used, or the value was in error, treat this as an invalid update description + If no src attribute was used, or the value was in error, treat this as an invalid update description document.
      @@ -1006,16 +999,16 @@

      5.4.1
      1. If this is not the first details element, in document order, that - matches a language range in the user agent locales; or, if no details element in the document matches the user agent locales and this is not the first element; then the element is in error and MUST be + matches a language range in the user agent locales; or, if no details element in the document matches the user agent locales and this is not the first 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. + Let details be the result of applying the rule for getting text content [WIDGETS] to this element.

    5. - Otherwise it MUST be ignored. + Otherwise it MUST be ignored.
    @@ -1028,81 +1021,81 @@

    5.4.1

    8. Verifying and Installing an Update

    -

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

    +

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

    - When a user agent is to remove the installed widget it is to disable the current incumbent widget, if it exists. The user agent may also physically remove the incumbent widget from the device. - The user agent may emit a notification warning that the incumbent widget is being removed. + When a user agent is to remove the installed widget it is to disable the current incumbent widget, if it exists. The user agent may also physically remove the incumbent widget from the device. + The user agent may emit a notification warning that the incumbent widget is being removed.

    -

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

    When a user agent is to terminate the widget update it is to 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. + 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 [WIDGETS] and is defined as follows: + 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 [WIDGETS] and is defined as follows:

    1. - Apply the steps for processing a widget package [WIDGETS] to the obtained - potential update. + Apply the steps for processing a widget package [WIDGETS] to the obtained + potential update.
    2. - If an incumbent widget could not be found then skip the rest of this rule and install the widget package. + 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. + 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 + 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:
    5. - If the potential update is determined not to be a digitally-signed widget package when applying the rules for signature validation [WIDGETS-DIGSIG] then the user agent will act as + If the potential update is determined not to be a digitally-signed widget package when applying the rules for signature validation [WIDGETS-DIGSIG] then the user agent will act as follows:
    6. - The user agent MUST install the widget package. + The user agent MUST install the widget package.
    @@ -1129,36 +1122,36 @@

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

    - An authoritative update URI is an update description source referenced in the href attribute of an - update-description element within an installed widget's configuration document [WIDGETS]. + An authoritative update URI is an update description source referenced in the href attribute of an + update-description element within an installed widget's configuration document [WIDGETS].

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

    -
    +

    A. Design Goals and Requirements

    This section is non-normative.

    This document addresses the Remote and Local Updates the requirement of the 30 April - 2009 Working Draft of the Widgets 1.0: Requirements Document (see [WIDGETS-REQS]). + 2009 Working Draft of the Widgets 1.0: Requirements Document (see [WIDGETS-REQS]).

    -
    +

    B. Acknowledgements

    @@ -1175,7 +1168,7 @@

    5.4.1 -

    C. References

    C.1 Normative references

    [DOM-LEVEL-3-CORE]
    Gavin Nicol et al. Document Object Model (DOM) Level 3 Core Specification. 7 April 2004. W3C Recommendation. URL: http://www.w3.org/TR/DOM-Level-3-Core/ +

    C. References

    C.1 Normative references

    [DOM-LEVEL-3-CORE]
    Gavin Nicol et al. Document Object Model (DOM) Level 3 Core Specification. 7 April 2004. W3C Recommendation. URL: http://www.w3.org/TR/DOM-Level-3-Core/
    [RFC2119]
    S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
    [WIDGETS]
    Marcos Cáceres. Widget Packaging and XML Configuration. 27 November 2012. W3C Recommendation. URL: http://www.w3.org/TR/widgets/
    [WIDGETS-DIGSIG]
    M. Cáceres; P. Bayers; Stuart Knightley; F. Hirsch; M Priestley. Digital Signatures for Widgets. (Work in progress. ). URL: http://www.w3.org/TR/widgets-digsig diff --git a/updates/Overview.src.html b/updates/Overview.src.html index a2de4b9..64a8bf9 100644 --- a/updates/Overview.src.html +++ b/updates/Overview.src.html @@ -43,14 +43,6 @@ wgPatentURI: "http://www.w3.org/2004/01/pp-impl/42538/status", }; -
    href='http://www.w3.org/TR/widgets/#table-of-configuration-defaults'>Table of Configuration Defaults [[!WIDGETS]] during Step 3 - Set the Configuration defaults.
    Table of Configuration Defaults (addendum) @@ -654,7 +646,6 @@

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

    Update Defaults