Copyright © 2007 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
Widgets are a class of client-side web application for displaying and/or updating local or remote data, packaged in a way to allow a single download and installation on a client machine or device. Examples include clocks, stock tickers, news casters, games and weather forecasters. This specification, when combined with other dependent specifications, defines a software solution for Widgets, including:
An internationalization model for widgets is not currently defined by this working draft. It may be defined future revisions of this specification, but only if we receive use cases from interested parties. If you want to see automated internationalization and localization support for widgets, then please let us know (public-appformats@w3.org).
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 15 October 2007 Second Public Working Draft of the Widgets 1.0 specification. This document is produced by the Web Application Formats WG, part of the Rich Web Clients Activity in the W3C Interaction Domain. It is expected that this document will progress along the W3C's Recommendation track. 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.
You can find the latest Editor's Draft of this document in the W3C's CVS repository, which is updated on a very regular basis. Please send comments to public-appformats@w3.org, the W3C's public email list for issues related to Web Application Formats. Archives of the list are available. A detailed list of changes from the previous version is also available from the W3C's CVS server.
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-appformats so their extensions can be considered for standardization.
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.
In this specification, a widget is understood to be an
interactive single purpose application for displaying and/or updating local data
or data on the Web, packaged in a way to allow a single download and installation on
a user's machine or mobile device
as defined in the Widgets 1.0
Requirements document [WIDGET-REQ]. For widgets,
this specification defines:
This specification attempts to conform to the requirements enumerated in the Widgets 1.0 Requirements [WIDGET-REQ] document.
Where a requirement is addressed, the specification should list the appropriate number. This will be done once the specification becomes a bit more mature.
As well as sections marked as non-normative, all 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 describes the conformance criteria for user agents (relevant to implementers) and documents (relevant to authors and authoring tool implementers).
There are three classes of products that can claim conformance to this specification:
Products that generate widget resources and/or allow authoring of configuration documents must not claim conformance to this specification, though they can claim to produce widget resources or configuration documents that themselves are conformant to this specification. Authoring tools and markup generators must generate conforming configuration documents and/or widget resources.
Products that check the conformance of widget resources or configuration documents must not claim conformance to this specification, though they can claim to verify that a widget resource or a configuration document is conformant to the relevant section(s) of this specification.
Products that generate digital signature must generate XML documents that conform to the XML-Signature Syntax and Processing Specification [XMLDsig] in compliance with the procedure for signing a widget resource.
A widget user agent is an implementation that attempts to support this specification.
In addition to supporting this specification, a widget user agent must support the following specifications:
A Widget user agent must behave as described by this specification in order to be considered conformant, even when faced with a non-conformant widget resource or a non-conformant configuration document.
This section describes the logical container for widgets.
A widget resource is a Zip archive that contains at least one start file. A widget resource may contain a configuration document as well as additional resources located either at the root of the archive or in sub-directories. In addition, a widget resource may also be digitally signed.
...how parts should be names and stored within an archive.
To be written...
This section describes the physical container format for widgets.
For the purposes of this specification, a Zip archive is a byte stream or file that conforms to the production of a .Zip file as defined by the the Zip File Format Specification [ZIP], with the exclusion or support for the following features and conditions. A Zip archive that is either corrupt (meaning that a CRC for the archive, or for a file within the archive, has failed) or non-conforming with any of the conditions listed below is referred to as an invalid Zip archive. In the event that a widget user agent encounters an invalid Zip archive during the procedures for processing a widget resource, the widget user agent must abort any processing and should inform the end-user with an appropriate localized error dialog. The wording of appropriate localized error dialogs are left to the discretion of implementers. A widget user agent must enforce the following conditions to claim conformance to this specification:
4.5. If a widget user agent encounters a
local file header with a version needed to extract value
higher than 4.5, the Zip archive must be treated as an invalid Zip
archive.Deflatecompression method or
stored(no compression), as defined in [ZIP]. A widget user agent must support the Deflate decompression method defined in [ZIP] to claim conformance to this specification. For each file in the Zip archive, the
compression methodfield of the
local file headermust indicate the compression method appropriately:
compression methodof a
local file headermust be
0. If a file is compressed with Deflate, then the compression methodof a
local file headermust be
8.
If the compression methodof a
local file headeris any value other than
0 or 8, then
the Zip archive is non-conforming and a widget user agent must treat it as an
invalid Zip archive.A widget resource can be created using proprietary extensions to the [ZIP] specification so long as the resulting widget resource can be processed in a interoperable manner across widget user agents. A Zip archive that cannot be processes by another widget user agent is non-conforming.
To be written...
To be written...
The extension .wgt is recommended for a widget resource on systems where it is customarily for file names
to include an extension that symbolizes the file type. The .wgt file
extension is case insensitive, although the lower case form is recommended. On systems where file names are case sensitive, the
lower case .wgt is preferred. Over the wire (eg. over HTTP), a widget
resource must be labeled with an application/widget
Media Type.
application/widget
Media Type and .wgt file extension over HTTPIt is recommended that a widget
resource served over HTTP are always be served with the .wgt file
extension in lower case.
If a widget user agent encounters a resource with an
invalid Media Type, but with a .wgt files extension, the resource is in error and the widget user agent should not attempt to process the resource.
Widget engines are allowed to support other legacy/proprietary widget resource types, but they must remain conformant to this specification when dealing with a widget resource.
If a widget user agent encounters a resource over HTTP
labeled with the application/widget Media Type and any file extension,
including no file extension, the widget user agent MUST attempt to process the resource in accordance to the procedures for processing a widget resource.
In this example, the Media Type is invalid so the widget engine should not attempt to process the following widget:
GET /foo.wgt HTTP/1.1
Host: www.example.com
Accept: application/widget,*/*
HTTP/1.1 200 OK
Date: Tue, 04 Sep 2007 00:00:38 GMT
Last-Modified: Mon, 03 Sep 2007 06:47:19 GMT
ETag: "8b5c14b4-7f-8b3e2bc0"
Accept-Ranges: bytes
Content-Length: 127323
Content-Type: application/x-gadget
A configuration document is an [XML] document that has the widget element at its root. The namespace of XML elements
in the configuration document must be
http://www.w3.org/ns/widgets.
Within the widget resource, the file name of a configuration document must be
config.xml. The file name is case insensitive,
although the lower case form is preferred. On systems where file names are case
sensitive the lower case config.xml is
preferred.
In this section, the term in error, typically used to means that an element or attribute in a configuration document is not conformant according to the rules of this specification. Rules for exactly how the an element or attribute must be treated when it is in error is always given when the term is used. Typically this will involve ignoring the erroneous DOM nodes, meaning the widget user agent must act as if erroneous nodes were absent.
Some necessary information to run a widget is stored in a file named
config.xml. This file contains information
about the widget's dimensions which is necessary to establish the initial view for
the widget file.
The following is an example of a config.xml document:
<widget id="http://www.example.org/widget" version="1" height="200" width="200">
<title>Hello World!</title>
<description>
A sample widget to demonstrate some of the possibilities.
</description>
</widget>
This section defines the various XML attributes types that a widget user agent may encounter during the processing of a Configuration Document.
A string is a valid non-negative float if it consists of one or more characters in the range U+0030 (0) to U+0039 (9) followed by a single U+002E FULL STOP (".") character and one or more characters in the range U+0030 (0) to U+0039 (9). (eg. 1.0, 243.23, 23.006).
A string is a valid non-negative integer if it consists of one of more characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). (eg. 2, 323, 23214).
The space characters, for the purposes of this specification, are U+0020 SPACE, U+0009 CHARACTER TABULATION (tab), U+000A LINE FEED (LF), U+000B LINE TABULATION, U+000C FORM FEED (FF), and U+000D CARRIAGE RETURN (CR).
A string is a valid version-tag is one that matches the
production for valid-version-tag in the
following ABNF [RFC4234]:
valid-version-tag := version-identifier*('.'version-identifier)version-identifier := string
Version 1.0 Beta, 1.0 RC1,
1.0-Build1580, Happydog 5.1.2600A valid e-mail address is one that follows the addr-spec token defined in [RFC2822] section 3.4.1, but excluding the CFWS subtoken everywhere, and excluding the FWS subtoken everywhere except in the quoted-string subtoken.
black or
white, are referred to as keyword attribute. For such
attributes, the values must be specified exactly, in the case
given in this specification, and with no leading or trailing whitespace. Unless
otherwise stated, implementations must only perform literal
comparisons, and must not use case-insensitive comparisons nor
trim attribute values before comparison.true or false. The default behavior, which is used when
the attribute is omitted or has a value other than the two allowed values, is
false. Rules for exactly how a boolean attribute must be
treated is given when the term is used.For the purpose of this specification, version tags have no significant semantics; they are just treated as arbitrary strings (eg. '1.0' is not greater than '2.0', but is simply different). This may change in future versions of this specification.
widget Elementtitle, description, icon
and access elements and zero or more author, and license
elements.idversionheightwidthstartchromeThe widget element is the root element of the
configuration document and serves as a container for
the other elements. As such, it must be present. It also
allows authors to version their widget as well as setting the initial height and
width.
User agents must only process the widget element when it is the root element. Other elements
named widget must not be
processed.
The id and version
attributes allow authors to version their widget. The id attribute
specifies a globally unique identifier specific to the widget and the
version attribute specifies the version associated with that
identifier.
The id attribute value must be a valid
identifier and the version attribute value must be a valid version list.
The width
and height
attributes control the initial dimensions of the widget. These attributes, when
specified, must have values that are valid non-negative integers. The rules
for parsing non-negative integers must be used to obtain
their numeric values. If an attribute is missing, or if parsing its value returns an
error, then the default value must be used instead. The
width attribute defaults to the screen width as amount of CSS pixels
[CSS], and the height attribute defaults to the screen height as amount
of CSS pixels.
The width and height attributes are only relevant to
widgets with a visual output.
The rendering section defines how the obtained values are to be used.
The start
attribute is used to identify the resource which can represent the widget. The
start attribute allows another file name than the default file name for
such a resource to be chosen.
Each start attribute has an associated resource identified by its
attribute value. The value of the start attribute must be a valid file in the package.
title Elementwidget element.The title element may be
present in config.xml as a child of the
widget element. It should
contain a human-readable title for the widget that can be used for example in
application menus and similar contexts.
User agents must use the first title element that is child of the widget root element as the element that provides a title
for the widget.
See next issue. eg: <title>My <blink>awesome</blink> widget</title>. Need the processing model for text nodes (based on HTML-5 or 4.10... extracting text from a text node....same for description).
description Elementwidget element.The description element may be present as a child of the widget element. If present, this element should contain a human-readable description of the widget.
User agents must use the first description element that is child of the widget root element as the element that provides a
description for the widget.
Define "description for the widget" using the definition of textContent. That definition should be used inline as it doesn't make much sense to reference the DOM specification just for that.
author Elementwidget element.urlemailAn author element denotes a person or an
organization involved in the creation of the widget. The
contents of the author element is the
human-readable name of the author. The url and email attributes are optional.
<author url="http://foo-bar.example.org/"
email="foo-bar@example.org">Foo Bar Corporation</author>
The url and
email
attributes provide further information about the author. Both attributes are
optional. The url attribute, when present, must have
a valid external link as value, (eg. the homepage of the author).
Likewise, the email attribute, when present, must
have a valid e-mail address as value (eg. the author's
email).
User agents are encouraged (though this is not required) to expose the information
provided by the author element(s) to the user.
license Elementwidget element.href...what happens if the href points to nothing or to an empty document? What if the attribute is not specified?
The href
attribute can be used to point to an external license. The href
attribute, when present, must have a valid external
link as value which should point to a document that
provides the copyright license terms under which the widget is provided.
icon Elementwidget element.src
(required)Currently there is only one permitted. Need to allow for more icons and maybe what role they play and something related to rendering dimensions/size.
The icon elements represents an application icon
for the widget. When used, the src attribute must be
present.
The src attribute
allows authors to point to an icon inside the package. When present, its value must be a valid package link.
A widget user agent must use the first
icon element that is a child of the widget root element as the icon for the application. User
agents should expose this icon in some way that it is visible to
the end user.
A widget user agent must support PNG, GIF87 and GIF89 as icon formats. A widget user agent may support other formats.
access Elementwidget element.networkplugins"Network" and network access needs to be defined as networked resource on the web or by any other TCP/IP interfaces implemented by the user agent. Implication of x-domain requests need to addressed (access control spec?). How do you establish the origin of the widget? Should the widget engine record the domain (url) of origin of a widget and record it securely somehow.
The access element indicates what kind of
permissions the widget has. When present, at least one element-specific attribute must be specified by the author.
The network and plugins
attributes are boolean attributes that
indicate what kind of rights the widget needs.
When the network attribute is present it indicates that
the widget might need network access to function. Similarly, when the plugins
attribute is present it indicates that the widget might need plugins to function.
User agents must only consider the first access element that is a child of the widget root element. User agents must
not examine any other access elements.
User agents should grant network access to the widget when the
network
attribute is specified and should allow the widget to use plugins
when the plugins attribute is specified.
When the access element is absent or the network
attribute is not present user agents must deny network access to
the widget. Similarly, when the access element is
absent or the plugins attribute is not present user agents
must not allow the instantiation of plugins.
User agents may optimize any of the parsing rules in this specification, so long as the end result is indistinguishable from the result that would be obtained by the specification's algorithms. (The algorithms in this specification are generally written with more concern for clarity than over efficiency.)
The rules for parsing a non-negative integer are as given in the following algorithm. When invoked, the steps must be followed in the order given, aborting at the first step that returns a value. This algorithm will either return zero, a positive integer, or an error. Leading spaces are ignored. Trailing spaces and indeed any trailing garbage characters are ignored.
0) .. U+0039
(9), then return an error.0) .. U+0039
(9):
0..9) to
value.See also the example Implementation of Rules for Parsing a Non-negative Integers in ECMAScript.
The Rules for Removing Whitespace are as given in the following algorithm. As with the previous algorithms, when this one is invoked, the steps must be followed in the order given, aborting at the first step that returns a value. This algorithm returns a string with all space characters removed.
See also the example Implementation of Rules for Removing Whitespace in ECMAScript.
The procedures for processing a widget resource involve eight steps that a widget user agent must follow in order, aborting if any of the steps result in an error. The procedures of how to abort when an error is encountered are described as part of each step. The steps listed as follows and are specified in detail in the following sub-sections:
A Widget user agent must treat file and directory names within a widget resource as case sensitive.
Once the widget resource is retrieved the user agent must use the unzipped representation for determining where files are located within the widget.
To be written.
To be written..
If the widget user agent was successful in locating signature files, then the widget user agent must follow the verification procedure for digital signatures defined in the Digital Signatures section of this specification.
The config.xml file must be processed as described in this section.
widget
element terminate this algorithm.widget
element:
title elementIf this is the first title element
encountered the concatenation of its Text and
CDATASection child nodes (ignoring any other nodes) are the widget title.
If this is not the first title element
this is an error. Ignore the node.
description element...
If this is not the first description element this is an error. Ignore
the node.
author element...
If this is not the first author element
this is an error. Ignore the node.
license element...
If this is not the first license
element this is an error. Ignore the node.
icon elementIf this is the first icon element and it
has a src attribute specified that points to a correct resource
use that resource as the widget icon.
Otherwise this is an error. Ignore the node.
start elementIf this is the first start element and it has a
src attribute specified that points to a correct resource use
that resource as the start file.
Otherwise this is an error. Ignore the node.
access elementIf this is the first access element use
the attributes specified on it to determine what rights the widgets has.
If this is not the first access element
this is an error. Ignore the node.
Comment nodeProcessingInstruction nodeText node that only contains space
charactersCDATASection node that only contains space charactersIgnore the node.
This is an error. Ignore the node.
The root folder of the widget is determined by the following algorithm:
If the start folder algorithm applied to the top-most folder returns "true" let the top-most directory be the root folder and terminate this algorithm.
Let the result of the find an alternative root folder algorithm be folder.
If folder is "false" terminate this algorithm. There is no root folder.
Apply the start folder algorithm to folder. If it returns "true" let folder be the root folder. Otherwise, there is no root folder.
A user agent should not install a widget without a root folder.
The start folder algorithm applied to folder returns either "true" or "false". The user agent must run the following steps in order to determine the return value:
If a file named config.xml exists in
folder return "true" and terminate this algorithm.
If the find a fallback start file algorithm does not return "false" return "true" and terminate this algorithm.
Return "false".
The find an alternative root folder algorithm either returns a folder or "false" if no folder was found. The user agent must run the following steps for this algorithm:
If the top-most folder contains a single folder return that folder and terminate this algorithm.
Return "false".
Need to define "start file", "potential start files", "updating", "installing" and various other user agent processing models.
A widget must have a start file in order to function. Without a start file there's basically no widget. If a user agent is unable to obtain a reference to a start file it should not install the widget as it can not be used. The start file contains the logic for the widget, such as some HTML and ECMAScript. It is found by running the following algorithm:
If the root folder contains a file named config.xml parse it and obtain a start file.
If that algorithm does not return "false" terminate this
algorithm.
Apply the find a fallback start file algorithm on the root folder. If a file is returned terminate this algorithm.
There is no start file.
A user agent should not install a widget without a start file.
To find a fallback start file the user agent must go search for the following file names within the widget in the folder given and abort whenever a file with such a file name is found. If no such file is found return "false".
index.htmlindex.htmindex.xhtmlindex.xhtindex.xmlindex.svgIf a user agent does not support the MIME type to which these file extensions map it may skip that file name.
This section should cover what file extensions inside a widget mean, authoring requirements on files. Maybe some terminology on how to handle the ZIP format if that's not sufficiently clear.
To be written..
... states, state change events. Platform specific states?
WindowWidget InterfaceWe need to say somehow that this interface is only to be exposed when the file is run in widget context. Probably by defining widget context.
The WindowWidget interface provides a pointer to the Widget object.
Objects implementing the Window interface must also implement the WindowWidget interface.
interface WindowWidget {
readonly attribute Widget widget;
}
The widget
attribute, on getting, must return a Widget object.
Widget
ObjectThe Widget object
exposes widget-specific functionality to scripts.
interface Widget {
void openURL(DOMString url);
DOMString preferenceForKey(DOMString key);
void setPreferenceForKey(DOMString value, DOMString key);
}
The openURL(url) method takes a
valid URL as argument. When invoked, the URL should
be opened in the default browser of the operating system on which the widget runs. If there is no such browser or the URL is not a
valid URL the user agent must act as if the method
was not invoked.
The getPreferenceForKey(key), when
invoked, must return the string that is stored for
key. If no such string has been stored the method must
return undefined.
The setPreferenceForKey(value,key)
method, when invoked, must return undefined.
If key is null, undefined or an empty
string return false terminate this algorithm.
If value is null or undefined and a
key matches a value stored for key remove that
value, return true and terminate this algorithm. If
key does not have a value stored return false and
terminate this algorithm.
If there is enough free space store value preference under
key, return true and terminate this algorithm. If there
is not enough space do not store the value, return false and
terminate this algorithm.
WindowThis should probably be defined in The Window Object specification, HTML5 or the CSSOM. Whichever ends up defining it.
A widget's initial dimensions are controlled by the width and
height elements in the config.xml
file. In addition to this, a widget can be resized or moved by scripting. If you
change these settings for a widget, the settings are volatile. User agents may ignore changes when closing and reopening widgets. To make the
widget a different size from the install-time default, store the widget size using
setPreference() and resize it on opening.
interface Window {
void resizeTo( in int w, in int h );
void resizeBy( in int delta_w, in int delta_h );
void moveTo( in int x, in int y );
void moveBy( in int delta_x , in int delta_y );
};
resizeTo(w,
h), methodThis method takes two positive integers as arguments: a width w and
height h. These sizes are the desired dimensions of the widgets in
pixels, and correspond to the width height elements in
a widget's configuration file. The method sets the window.outerWidth
and window.outerHeight properties. Example:
// Resize the widget to 400x300 px
window.resizeTo( 400, 300 );
Need to define error handling and outerWidth and
outerHeight properly. Well again, The Window Object specification
should...
resizeBy(), methodThis method takes two integers as arguments: A delta_w that is the desired change in width, measured in pixels, and a delta_h that is the desired change in height, again measured in pixels. The width and height of the widget is then recalculated to be equivalent to the following pseudo-code:
window.resizeTo( window.outerWidth + delta_x, window.outerHeight + delta_y );
In all cases of window resizing, the resizing happens from the lower-right corner of the widget window, while the upper-left corner remains static.
// Grow the widget by 100px horizontally
window.resizeBy( 100, 0 );
moveTo(), methodThe moveTo method takes two integers as
arguments: An x that is the desired x coordinate for the upper-left
corner of the widget, and an y that is the desired y coordinate for
the upper-left corner of the widget, with both values mentioned in pixels.
// Move the widget to the upper-left corner of the screen window.moveTo( 0, 0 )
moveBy(), methodThe resizeBy method takes two integers as
arguments: A delta_x that is the desired change in x position,
measured in pixels, and a delta_y that is the desired change in y
position, again measured in pixels. Both values can be negative. Example:
// Move the 50px left and 50px down window.moveBy( -50, 50 )
This section will define how widgets will be able to communicate with each other by sending messages via javascript. We are going to base this model on the Cross-document messaging model found in HTML 5.
This section will define hit-testing, that the background color of the "start file" canvas is transparent (does not default to some color), how the height and width attributes affect rendering. It should take into account platform limitations, etc.
Curved widgets and how they behave when clicked in a transparent area, etc.
...TBW...
A widget resource may be digitally signed. A widget resource must
be treated as digitally signed if it contains a digital signature: an XML document that conforms to structure and
semantics specified in the XML-Signature Syntax and Processing Specification [XMLDsig], which must be stored at the root of a widget resource under the file name signature.xml.
For a widget resource to be considered digitally signed, the signature.xml must include a <Digest> element for each file in
the widget resource. To verify that a widget resource has been correctly digitally
signed, the widget user agent must
follow the verification procedure for digital
signatures. If the digital signature has not been
digitally signed correctly, then the widget resource is in error and a widget user agent must
abort processing the widget resource.
Example (signature.xml):
<?xml version="1.0" encoding="UTF-8"?>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
<SignedInfo>
<CanonicalizationMethod
Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
<SignatureMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
<Reference URI="#References"
Type="http://www.w3.org/2000/09/xmldsig#Manifest">
<DigestMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<DigestValue>725x3fVasdfvBGFGjhjyDSFvUk=</DigestValue>
</Reference>
</SignedInfo>
<SignatureValue>MC0E~LE=</SignatureValue>
<KeyInfo>
<X509Data>
<X509Certificate>MI...lVN</X509Certificate>
</X509Data>
</KeyInfo>
<Manifest Id="References">
<Reference URI="config.xml">
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
<DigestValue>j6...8nk=</DigestValue>
</Reference>
<Reference URI="index.html">
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<DigestValue>lm...34=</DigestValue>
</Reference>
<Reference URI="pictures/picture1.gif">
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<DigestValue>pq...56=</DigestValue>
</Reference>
</Manifest>
</Signature>
The verification procedure for digital signatures is as follows:
signature.xml using a valid XML Parser. If
the document is not well-formed, then the widget resource is in error and the widget user agent must abort any further processing of the widget
resource and inform the end-user with an appropriate error dialog.<KeyInfo> element (details
on how to do this are out of scope of this specification). If the widget user agent is not able to do this, proceed to the next
signature.<SignedInfo> element.<Manifest> element and check
that it is the same as the corresponding <DigestValue> in
<SignedInfo>.<Manifest> element and compare them to the digest values
expressed in each <Reference> element's corresponding
<DigestValue> element. Check that all files in the widget resource are listed in
<Manifest>.The procedure for signing a widget resource to produce a digital signature are as follows:
<Reference> element and place the digest in
<DigestValue> child element as described in in [XMLDsig].<Reference> elements within a
<Manifest> element. Calculate the digest of
<Manifest>.<SignedInfo> element with a reference to the
<Manifest> element, including its digest.<SignedInfo> element, sign it
and place the signature in the <SignatureValue> element.<KeyInfo> element.<SignedInfo>, <SignatureValue>,
and <KeyInfo> elements into a <Signature>
element.<Signature> element in the root directory of the
widget resource as signature.xml.In order to support additional signatures (by the same signer or other signers) in
an efficient and flexible way, the <Manifest> element is used to
list the references. Additional signatures are placed in resource
signature1.xml, signature2.xml and so on. It is recommended that these be the first files in the widget resource. The <Manifest> element is
only in signature.xml. Additional signature[x].xml
resources refer to the Manifest in signature.xml.
Example (signature1.xml)
<?xml version="1.0" encoding="UTF-8"?>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
<SignedInfo>
<CanonicalizationMethod
Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
<SignatureMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
<Reference URI="signature.xml#References"
Type="http://www.w3.org/2000/09/xmldsig#Manifest">
<DigestMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<DigestValue>725x3fVasdfvBGFGjhjyDSFvUk=</DigestValue>
</Reference>
</SignedInfo>
<SignatureValue>MC0E~LE=</SignatureValue>
<KeyInfo>
<X509Data>
<X509Certificate>MI...lVN</X509Certificate>
</X509Data>
</KeyInfo>
</Signature>
The following is the rule for signing an existing signature ("signature[x].xml") inside a widget resource:
<SignedInfo> element with a reference to the
<Manifest> element (in �signature[x].xml�).<SignedInfo> element, sign it
and place the signature in the <SignatureValue> element.<KeyInfo> element.
<SignedInfo>, <SignatureValue>,
and <KeyInfo> elements into a <Signature>
element.<Signature> element in the root directory of the
widget resource as �signature1.xml� (�signature2.xml�
etc.)To be written.
To be written.
This section only applies to HTML user agents [HTML4] [XHTML].
This section only applies to HTML user agents [HTML4] [XHTML].
Auto-discovery enables a user agent to identify and install a widget resource that is associated with an HTML page. When a page points to a widget resource, user agents should expose the presence of the widget resource to the end-user and allow the end-user to install the widget.
The link type "widget" indicates that a link of this type
references a document that is a widget resource. In HTML, it
may be specified for the a, area and link elements to create a
hyperlink.
For example:
<a rel="widget" href="http://widgets.example.org/SimAquarium">The SimAquarium Widget</a>
This section contains reference implementations of each of the the Parsing Rules discussed in this specification. The following algorithms have been written to demonstrate or otherwise explain various aspects of in this specification; written with more concern for clarity than efficiency.
This section is informative.
The following is an example implementation of the Rules for Removing Whitespace written in ECMAScript.
function removeWhitespace(input){
var result = "";
for(position in input){
var character = input[position];
if(character!= "\u0020" &&
character != "\u0009" &&
character != "\u000A" &&
character != "\u000B" &&
character != "\u000C" &&
character != "\u000D"){
result += character;
}
}
return result;
}
This section is informative.
/***************************************************************************************************************************************************
Demo application for generating widget signatures.
Olli Immonen, Nokia, 18.5.2007
Based largely on
http://java.sun.com/developer/technicalArticles/xml/dig_signature_api/
Note:
The following command needs to be run to create the Java Keystore, private key and a (self-signed) certificate:
keytool -genkey -keyalg rsa -dname "cn=Widget testing, o=Testing, c=FI" -alias Testkey -keypass abc123 -keystore testkeystore.jks -storepass abc123
- create the files that the demo assumes: config.xml, index.htm and pictures/picture1.gif
***************************************************************************************************************************************************/
import java.io.*;
import java.util.*;
import java.security.*;
import javax.xml.crypto.*;
import javax.xml.crypto.dsig.*;
import javax.xml.crypto.dsig.keyinfo.*;
import javax.xml.crypto.dsig.spec.*;
import javax.xml.crypto.dsig.dom.*;
import javax.xml.crypto.dsig.dom.DOMSignContext;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.transform.*;
import javax.xml.transform.dom.DOMSource;
import javax.xml.transform.stream.StreamResult;
import java.security.cert.*;
import org.w3c.dom.*;
class SignWidget {
public static void main(String[] args) {
String[] files = {"config.xml", "index.html", "pictures/picture1.gif", ""};
String sigfilename = "signature.xml";
// Strings for using the Java KeyStore
String keystorename = "testkeystore.jks";
String keystorepw = "abc123";
String keyname = "Testkey";
String keypw = "abc123";
try {
// Create a DOM XMLSignatureFactory that will be used to
// generate the signature.
System.out.println("Create a DOM XMLSignatureFactory");
XMLSignatureFactory fac = XMLSignatureFactory.getInstance("DOM");
// Create the a list of references to the files.
List manrefs = new ArrayList();
for (int i = 0; (files[i] != "") ; i++)
{
System.out.println("Add reference: " + files[i]);
Boolean b = manrefs.add(fac.newReference(files[i],
fac.newDigestMethod(DigestMethod.SHA1, null), null, null, null, digestFile(files[i])));
}
System.out.println("Create Manifest");
Manifest manifest = fac.newManifest(manrefs, "references");
Reference ref = fac.newReference("#references", fac.newDigestMethod(DigestMethod.SHA1, null));
List content = Collections.singletonList(manifest);
XMLObject object = fac.newXMLObject(content, null, null, null);
// Create the SignedInfo.
System.out.println("Create the SignedInfo");
SignedInfo si = fac.newSignedInfo
(fac.newCanonicalizationMethod
(CanonicalizationMethod.INCLUSIVE,
(C14NMethodParameterSpec) null),
fac.newSignatureMethod(SignatureMethod.RSA_SHA1, null),
Collections.singletonList(ref));
// Load the KeyStore and get the signing key and certificate.
System.out.println("Load the KeyStore and get the signing key and certificate");
KeyStore ks = KeyStore.getInstance("JKS");
ks.load(new FileInputStream(keystorename), keystorepw.toCharArray());
KeyStore.PrivateKeyEntry keyEntry =
(KeyStore.PrivateKeyEntry) ks.getEntry
(keyname, new KeyStore.PasswordProtection(keypw.toCharArray()));
X509Certificate cert = (X509Certificate) keyEntry.getCertificate();
// Create the KeyInfo containing the X509Data.
System.out.println("Create the KeyInfo containing the X509Data");
KeyInfoFactory kif = fac.getKeyInfoFactory();
List x509Content = new ArrayList();
x509Content.add(cert.getSubjectX500Principal().getName());
x509Content.add(cert);
X509Data xd = kif.newX509Data(x509Content);
KeyInfo ki = kif.newKeyInfo(Collections.singletonList(xd));
// Instantiate the document to be signed.
System.out.println("Instantiate the document to be signed");
DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);
Document doc = dbf.newDocumentBuilder().newDocument();
// Create a DOMSignContext and specify the RSA PrivateKey and
// location of the resulting XMLSignature's parent element.
System.out.println("Create a DOMSignContext");
DOMSignContext dsc = new DOMSignContext
(keyEntry.getPrivateKey(), doc);
// Create the XMLSignature, but don't sign it yet.
System.out.println("Create the XMLSignature");
XMLSignature signature = fac.newXMLSignature(si, ki, Collections.singletonList(object), null, null);
// Marshal, generate, and sign the enveloped signature.
System.out.println("Marshal, generate, and sign");
signature.sign(dsc);
// Output the resulting document.
OutputStream os = new FileOutputStream(sigfilename);
TransformerFactory tf = TransformerFactory.newInstance();
Transformer trans = tf.newTransformer();
trans.transform(new DOMSource(doc), new StreamResult(os));
} catch (Exception e) {
e.printStackTrace();
}
}
static byte[] digestFile(String fname){
byte[] mdbytes = null;
try{
MessageDigest md = MessageDigest.getInstance("SHA1");
FileInputStream fis = new FileInputStream(fname);
byte[] dataBytes = new byte[1024];
int nread = fis.read(dataBytes);
while (nread > 0) {
md.update(dataBytes, 0, nread);
nread = fis.read(dataBytes);
}
mdbytes = md.digest();
}
catch (Exception e) {
e.printStackTrace();
}
return mdbytes;
}
}
This section is informative.
The following RelaxNG schema is a representation of the elements and attributes Configuration Document as described in this specification.
# Widgets 1.0 (Working Draft) RELAX NG schema
default namespace = "http://www.w3.org/ns/widgets"
namespace xsd = "http://www.w3.org/2001/XMLSchema-datatypes"
start = widget
widget = element widget {
attribute id { text }?,
attribute version { text }?,
attribute height { xsd:nonNegativeInteger }?,
attribute width { xsd:nonNegativeInteger }?,
attribute start { xsd:string { pattern="index\.(html|htm|xhtml|xht|xml|svg)" } }?,
attribute chrome { text }?,
( title? &
description? &
icon? &
access? &
author* &
license* )
}
title = element title { text }
description = element description { text }
icon = element icon {
attribute src { xsd:anyURI },
empty
}
access = element access {
attribute network { "true" | "false" }?,
attribute plugins { "true" | "false" }?,
text
}
author = element author {
attribute url { xsd:anyURI }?,
attribute email { xsd:string { pattern=".*@.*" } }?,
text
}
license = element license {
attribute href { xsd:anyURI }?,
text
}
Special thanks go to Arve Bersvendsen and Charles McCathieNevile who wrote the initial version of this specification, "Opera Widgets 1.0." Thanks also to David Håsäther for providing the RelaxNG Schema for the configuration document. The editors would also like to thank the following people for their contributions to this specification:
The Widget object is
based on Apple's Dashboard.
This section will be completed as the document matures.