Widgets 1.0: Digital Signature

W3C Working Draft 14 April 2008

This Version:: http://www.w3.org/TR/2008/WD-widgets-digsig-20080414/
Latest Version:: http://www.w3.org/TR/widgets-digsig/
Previous Version:: None.
Latest Editor's Draft:: http://dev.w3.org/2006/waf/widgets-digsig/
Version history:: Twitter messages (non-editorial changes only): http://twitter.com/widgetspecs (RSS)
Editor:: Marcos Caceres, Invited Expert

Abstract

This document defines a profile of the XML-Signature Syntax and Processing specification to allow a widget resource to be digitally signed. Vendors and authors can digitally sign widgets as a trust and quality assurance mechanism. Prior to instantiation, a widget user agent can use the digital signature to verify the authenticity and data integrity of the files in a widget resource. In the rare case where a widget damages the end-user's device, the digital signature may provide a user with legal recourse to prove that a widget resource was signed by a particular author or publisher.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is the W3C First Public Working Draft of the Widgets 1.0: Digital Signature. This document is produced the Web Application Formats (WAF) Working Group (WG). This WG is part of the Rich Web Clients Activity and this activity is within the W3C's Interaction Domain.

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.

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.

1. Introduction
- 1.1 Signature Profile
2. Conformance
3. Definitions
4. Procedure for Signing a Widget Resource
5. Procedure for Verifying a Digital Signature
Acknowledgements
References

1. Introduction

Digitally signing a widget resource involves signing all of its file entries using a unique private key that is known only to the signer. The resulting signature, along with the signer's digital certificate, is structured into an XML document, and included at the root of a widget resource under the name signature.xml.

Example of a signature.xml document:

<?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="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="icon.png">

			<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
			<DigestValue>pq...56=</DigestValue>
		</Reference>
	</SignedInfo>
	<SignatureValue>MC0E~LE=</SignatureValue>

	<KeyInfo>
		<X509Data>
			<X509Certificate>MI...lVN</X509Certificate>
		</X509Data>
	</KeyInfo>

</Signature>

1.1 Signature Profile

The signature scheme defined in this specification imposes a number of restrictions on the XML-Signature Syntax and Processing Specification [XMLDsig]:

Every file entry in a widget resource must be signed. The resulting digital signature must be serialized into an UTF-8 encoded XML document and placed at the root of the widget archive under the name signature.xml.
Reference elements must use the SHA1 as the digest method.
The signature method to produce the SignatureValue must be RSA-SHA1.
A KeyInfo element must be present and the digital certificate format must conform to the [X509v3] specification. Implementations must be prepared to accept all X.509 certificates versions identified in [X509v3] via the version field. To be clear, the value of the version field identifies the version of an X.509 certificate in the following way:
- 0 is X.509 version 1,
- 1 is X.509 version 2,
- 2 is X.509 version 3,
- if the version field is omitted, then the X.509 version is 1
SignatureProperties elements are ignored by this specification, but they may be present in a signature document.

(For SignatureProperties, we are considering defining one element: WidgetSigningProfile, with a version parameter. All of which would be signed.)

Note: The intention of these restrictions is to define a light-weight profile of [XMLDsig] that does not require widget user agents to implement [XPath].

2. Conformance

As well as sections marked as non-normative, 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].

There are two classes of product that can claim conformance to this specification:

A digital signature document.
A widget user agent

Products that generate a digital signature document must generate XML documents that conform to [XMLDsig] and adhere to the restrictions imposed by this specification.

Products that check the conformance of a digital signature document must not claim conformance to this specification, though they can claim to verify that a digital signature document conforms to this specification.

A widget user agent must behave as described by this specification in order to claim conformance, specially when faced with an invalid widget resource or a non-conforming digital signature document.

3. Definitions

A widget resource is a byte-stream or file that conforms to section 4.0 and section 5.0 of the [Widgets Packaging] specification.

A file entry is the amalgamation of data held by a local file header, file data, and (optional) data descriptor [ZIP] for each physical file stored in a zip archive.

A digital signature document is a well-formed XML document named signature.xml generated by applying the procedure for signing a widget resource described in this document. The document will conform to [XMLDsig].

An invalid zip archive in this specification is one where the digital signature document is either in error, or there is a mismatch between the data in the digital signature document and/or the data in a file entry (meaning that the authenticity or data integrity of the zip archive could not be verified). For rules on dealing with invalid zip archives, please see the "Dealing with Invalid Zip Archives" section in the [Widgets Packaging] specification.

A digitally signed widget resource is one that contains a file entry with a file name field that matches 'signature.xml' in a any case form, though the lower case form is recommended. The signature.xml document must contain a Reference element for every file entry in the widget resource. In addition, the file data of the file entry must conform to [XMLDsig], but in accordance to the procedure for signing a widget resource.

A decompressed representation of a file entry is the data extracted from the data field of a local file header (and decompressed using [Deflate] when the compression method field is 8).

4. Procedure for Signing a Widget Resource

The procedure for signing a widget resource to produce a conforming digital signature document is as follows:

If the widget resource contains zero file entries, treat this zip archive as an invalid zip archive.
Let doc be a new XML [DOM3CORE] document encoded in UTF-8 [XML].
Create a SignedInfo element.
For each file entry in the widget resource, if the file name field of the local file header of the file entry does not case insensitively match signature.xml:
1. Let path be the value of the file name field of the local file header.
2. If general purpose bit 11 of the local file header is 0, then convert the character encoding of path from [CP437] to [UTF-8].
3. Verify that path is a valid zip-relative-path, as defined in [Widgets Packaging].
4. Create a Reference element.
5. Create a URI attribute in the Reference element and assign it the value of path.
6. Let hash-value be the digests of applying the SHA-1 algorithm to the file entry's decompressed representation (see [XMLDsig] for how to do this).
7. Create a DigestValue element and append the hash-value as a Text node.
8. Create a DigestMethod element with an Algorithm attribute, and give that attribute the value http://www.w3.org/2000/09/xmldsig#sha1.
9. Append this Reference element to the SignedInfo element.
Create a CanonicalizationMethod element and set the value of its Algorithm attribute to http://www.w3.org/TR/2001/REC-xml-c14n-20010315.
Create a SignatureMethod element and set the value of its Algorithm attribute to http://www.w3.org/2000/09/xmldsig#rsa-sha1.
Calculate the digest of the SignedInfo element using RSA-SHA1, sign it and place the signature in the <SignatureValue> element.
Place the signer's certificate in the KeyInfo element.
Create a Signature element in the http://www.w3.org/2000/09/xmldsig# namespace.
Place the SignedInfo, SignatureValue, and KeyInfo elements into the Signature element.
Open the zip archive so that a file entry can be written (eg. as a buffered output stream).
Serialize the Signature element and all its children into a UTF-8 encoded XML file in canonical form and save it in the root of the widget resource as signature.xml overriding the contents of any existing signature.xml file entry.

5. Procedure for Verifying a Digital Signature

The procedure for verifying a digital signature is as follows. The algorithm first checks the validity of the digital signature and then verifies that all resources in a widget resource.

If a steps results in a false condition or is otherwise in error, then a widget user agent must treat the widget resource as an invalid zip archive and all processing of the widget resource must stop.

Find the the file entry whose file name field case insensitively matches signature.xml.
Parse the decompressed representation of signature.xml into a DOM tree using a valid XML Parser to check that the document is well-formed [XML].
Check that a Signature element exists and it contains a SignedInfo element.
Check that every file entry in the zip archive has a corresponding Reference element in the SingedInfo element:
1. Let path be the value of the file name field of the local file header of the file entry.
2. If general purpose bit 11 of the local file header of the file entry is 0, then convert the character encoding of path from [CP437] to [UTF-8].
3. Check that path is a valid zip-relative-path (absolute URI references are considered in error)
Apply the Signature Validation algorithm as defined in [XMLDsig]:
1. If the widget user agent cannot verify the certificate from its list of explicitly trusted root certificates, then the certificate must be treated as invalid.
Extract the decompressed representation of each file entry in the widget archive, making sure to retain the directory structure of each file entry.
1. NEED SECURITY CONSIDERATIONS HERE.
Apply the Reference Validation algorithm as defined in [XMLDsig],
1. THIS SECTION IS STILL UNDER DEVELOPMENT.
2. Let base URI be the absolute path to where the widget archive was extracted (eg. file:///temp/widget/)
3. Validate against the matched file entry's decompressed representation. The relative URI references are evaluated with respect to a base URI that points at where the widget resource was demcompressed.

Acknowledgements

This section will be completed as the document matures.

References