XML Digital Signatures for Widgets

Living Document - Last updated 28 March 2013

Latest version:: http://www.w3.org/TR/widgets-digsig/

Test Suite:: http://dev.w3.org/2006/waf/widgets-digsig/test-suite/
Implementation Report:: http://dev.w3.org/2006/waf/widgets-digsig/imp-report/
Editors:: Marcos Cáceres, W3C Invited Expert; Paddy Byers, Aplix Corporation; Stuart Knightley, Opera Software ASA; Frederick Hirsch, Nokia; Mark Priestley, Vodafone

Please refer to the errata for this document, which may include some normative corrections.

Abstract

This document defines a profile of the XML Signature Syntax and Processing specification to allow a widget package to be digitally signed. Authors and distributors can digitally sign a widget as a mechanism to ensure continuity of authorship and distributorship. A user agent, or other validation system, can use a digital signature to verify the data integrity of the files within a widget package and to confirm the signing key(s).

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 30 March 2012 W3C Recommendation of the XML Digital Signatures for Widgets specification.

This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.

The public is encouraged to send comments to the WebApps Working Group's public mailing list public-webapps@w3.org (archive). See W3C mailing list and archive usage guidelines.

This document is produced by the Web Applications WG, part of the Rich Web Client Activity in the W3C Interaction Domain. It is expected that this document will progress along the W3C's Recommendation track.

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.

1 Introduction
1. 1.1 Design goals and requirements
2 Conformance
3 Definitions
4 Versions, namespaces, and identifiers
5 Algorithms, key lengths, and certificate formats
1. 5.1 Note about X.509 data
6 Author signature
1. 6.1 Naming convention
7 Distributor signatures
1. 7.1 Naming convention
8 Generating a digital signature
1. 8.1 Example of a generated distributor signature
9 Validating digital signatures
10 Locating signature files in a widget package
11 Security Considerations
Acknowledgements
Normative References
Informative References

1 Introduction

A widget package can be digitally signed by an author to produce a signature file that cryptographically covers all of the files of a widget package that are not signature files (e.g., HTML files, CSS files, and JavaScript files). In this specification, this kind of signature is referred to as an author signature.

A user agent or other entity can use an author signature to determine:

which entity alleges to have authored the widget,
that the integrity of the widget is as the author intended,
and whether a set of widgets came from the same author.

A widget package can also be signed by one or more distributors to produce a signature file that cryptographically includes all non-signature files as well as any author signature (if one was included). In this specification, this kind of signature is referred to as a distributor signature. To be clear,distributor signatures countersign author signatures, but do not countersign other distributor signatures. Because of this, an author signature needs to be included in a widget package before a distributor signature or the validation process defined in this specification will fail.

A user agent or other entity can use a distributor signature to determine:

that a particular distributor has distributed a widget package,
that the integrity of the widget package is as the distributor intended,
and whether a set of widgets came from the same distributor.

The complete signing model is illustrated in Figure 1.

This figure shows which files are signed by each kind of signature, indicated by the dashed lines and arrows. Author signatures sign all the non-signature files of the widget package (e.g., images, sounds, HTML files, and CSS files). The distributor signatures sign the author signature and all other non-signature files in the package (but not other distributor signatures). The model allows distributor signatures to be removed without affecting the integrity of the widget package as the author intended it. This also facilitates redistribution of widget packages by either complete removal of all signature files or substitutions of signatures.

1.1 Design goals and requirements

This document addresses the following requirements from the [Widgets Requirements] document:

Digital Signatures: this specification relies on [XMLDSIG] and [RFC5280] to address this requirement.
Multiple Signatures and Certificate Chains: this specification relies on [XMLDSIG] and [RFC5280] to address this requirement.
Signature Document Format: see signature file.
Support for Multiple Message Digest Algorithms: this specification supports SHA-256, the reference element, and ds:SignedInfo element.
Support for Multiple Signature Algorithms: this specification relies on the signature algorithms defined in [XMLDSIG].
Key Lengths: see the recommended key length.
Key Usage Extension: part of X.509v3.
Inclusion of Revocation Information: this specification relies on [XMLDSIG] and [RFC5280] to address this requirement.

2 Conformance

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

As well as sections marked as non-normative, the examples and notes, and security considerations in this specification are non-normative. Everything else in this specification is normative.

There are two classes of product that can claim conformance to this specification, a signer and a validator:

A signer is a user agent that implements [XMLDSIG] and digitally signs a widget package in a manner that conforms to the requirements of this specification and in a manner that conforms to the applicable generation requirements of [Signature Properties].
A validator is a user agent that implements [XMLDSIG] and validates the signature files of a widget package in a manner that conforms to the requirements of this specification and in a manner that conforms to the applicable validation requirements of [Signature Properties].

Note: User agents that implement this specification are encouraged to allow end-users to install digital certificates. This allows the verification of digital signatures within the widget package for when custom root certificates are not shipped with a runtime (e.g., for beta testing purposes).

3 Definitions

As the following terms are used throughout this specification, they are gathered here for the reader's convenience. The following list of terms is not exhaustive; other terms are defined throughout this specification.

A file is the uncompressed representation of a physical file contained in a widget package (e.g., config.xml).

A file name is the name of a file contained in a widget package (excluding path information).

The root of the widget package is the top-most file-path level of the widget package, as defined in the [Widgets Packaging] specification.

A signature file is a detached [XMLDSIG] document, likely encoded in [UTF-8].

A widget package is a [ZIP] archive that conforms to the [Widgets Packaging] specification.

A zip relative path is a string that conforms to the [ABNF] for zip-rel-path as specified in [Widgets Packaging].

4 Versions, namespaces, and identifiers

This specification makes use of [XML-Namespaces], and uses [URI]s to identify resources, algorithms, and semantics.

The XML namespace for [XML] elements used by this specification is http://www.w3.org/ns/widgets-digsig

The profile URI for this specification is http://www.w3.org/ns/widgets-digsig#profile

No provision is made for an explicit version number in this specification. If a future version of this specification requires explicit versioning of the document format, a different namespace will be used.

5 Algorithms, key lengths, and certificate formats

This specification relies on a user agent's conformance to [XMLDSIG] for support of signature algorithms, certificate formats, canonicalization algorithms, and digest methods. As this specification is a profile of [XMLDSIG], it makes a number of recommendations as to what signature algorithms should be used when signing a widget package to achieve optimum interoperability. See Signature Algorithms of [XMLDSIG] for the list of required algorithms.

The recommended signature algorithm is RSA using the RSAwithSHA256 signature identifier: http://www.w3.org/2001/04/xmldsig-more#rsa-sha256.

The recommended key length for RSA is 4096 bits.

The recommended digest method is SHA-256.

The recommended canonicalization algorithm is Canonical XML Version 1.1 (omits comments) as defined in [C14N11]. The identifier for the algorithm is http://www.w3.org/2006/12/xml-c14n11.

The recommended certificate format is X.509 version 3 as specified in [RFC5280].

5.1 Note about X.509 data

This section is informative.

A signature file can have information contained in a ds:X509Data element, as specified by the [XMLDSIG] specification. This can include X.509 certificates, and/or CRL and/or OCSP response information that, if included, are conveyed according to the [XMLDSIG] specification. X.509 v3 certificates provide means to express the basic constraints on a certificate. This allows CA certificates to be distinguished from end entity certificates, enabling more robust trust verification. See also [RFC5280] for more information.

6 Author signature

An author signature is a signature file whose file name adheres to the naming convention for an author signature and whose [Signature Properties] Role element's URI attribute value is equal to the author role URI. An author signature is intended to be generated by the author of the widget, which is the entity or entities whom claim authorship over the content of the widget package.

A widget package can contain zero or one author signature.

Author role URI:: http://www.w3.org/ns/widgets-digsig#role-author

6.1 Naming convention

The author-sig-filename [ABNF] rule defines the naming convention for an author signature, as it applies to the file name of the author signature:

 author-sig-filename = %x61.75.74.68.6f.72.2d.73.69.67.6e.61.74.75.72.65.2e.78.6d.6c

The author-sig-filename rule defines the lower-case (case-sensitive) string "author-signature.xml".

7 Distributor signatures

A distributor signature is a signature file whose file name adheres to the naming convention for a distributor signature and whose [Signature Properties] Role element's URI attribute value is equal to the distributor role URI. A distributor signature is intended to be generated by a distributor, which is a third party that is distributing the widget on behalf of the author.

A widget package can contain zero, one, or more distributor signatures.

Distributor role URI:: http://www.w3.org/ns/widgets-digsig#role-distributor

7.1 Naming convention

Each distributor signature has a file name consisting of the lower-case string "signature" followed by a digit in the range 1-9 inclusive, followed by an optional zero or more digits in the range 0-9 inclusive and then the lower-case ".xml".

The dist-sig-filename rule formally defines the naming convention for a distributor signature, as it applies to the file name of a distributor signature:

dist-sig-filename = signature-string non-zero-digit 
                    *DIGIT  xml-suffix-string
signature-string  = %x73.69.67.6e.61.74.75.72.65
non-zero-digit    = %x31-39                       
xml-suffix-string = %x2e.78.6d.6c

The signature-string rule defines the lower-case string "signature".
The non-zero-digit rule defines a digit in the range 1-9, thus leading zeros are disallowed by this rule.
DIGIT is defined as a digit in the range 0-9.
The xml-suffix-string rule defines the lower-case (case-sensitive) string ".xml".

An example is signature20.xml.

8 Generating a digital signature

To digitally sign the contents of a widget package with an author signature or with a distributor signature, a signer MUST run the algorithm to generate a digital signature.

The algorithm below relies on the signature generation rules of [XMLDSIG] (Section 3.1) and the various generation rules defined in [Signature Properties] (links to the appropriate sections of those specifications are provided where needed for generation). When performing the algorithm below, it is RECOMMENDED that a signer use the recommended canonicalization algorithm, the recommended signature algorithm, the recommended key length for the appropriate algorithm, and the recommended certificate format.

The algorithm to generate a digital signature is as follows:

Using the Processing Rules of [XMLDSIG], perform reference generation for each file of the widget package that is not a signature file. Set the a URI attribute of each ds:Reference to be the zip relative path that identifies the file inside the widget package.
Optionally, include a ds:KeyInfo element in the manner described in [XMLDSIG] (see The KeyInfo Element for how to do this). The element can include CRL and/or OCSP information [RFC5280] (see note about X.509 data in this specification).
Generate the container elements for [Signature Properties] in accordance with the Signature Properties Placement section of [Signature Properties].
If generating an author signature, generate a role property and let its URI attribute value be the author role URI.
Otherwise, if generating a distributor signature:
1. Generate a role property in the manner specified in [Signature Properties] and let its URI attribute value be the distributor role URI.
2. If the widget package contains an author signature, perform reference generation on the author signature and set the resulting ds:Reference element's URI attribute to be author-signature.xml.
Generate an identifier property in the manner specified in [Signature Properties].
Generate a profile property in the manner specified in [Signature Properties] whose URI attribute is the profile URI.
Optionally, include any additional [Signature Properties] by following the appropriate generation rules specified in [Signature Properties].
Generate a reference to the ds:Object that contains the signature properties created in the steps above.
Perform signature generation as defined in [XMLDSIG].
Serialize the signature as a [UTF-8] encoded [XML] document using the appropriate naming convention depending on its role: using either the naming convention for a distributor signature or the naming convention for an author signature.

Note: It is not a requirement that the file names of distributor signatures are serially numbered signatures1.xml, signature2.xml, signature3.xml, and so on. A signer can to use whatever pattern they want, so long as the file name conforms to the naming convention for a distributor signature. The numeric part of the file name affects the order in which signature files are processed by a validator (see the algorithm to locate signature files in a widget package). So, to ensure that a distributor signature is processed before any other distributor signatures, assign a number greater than that of all the other distributor signatures for the numeric part of the distributor signature's file name.
Place the generated signature file at the root of the widget package.

8.1 Example of a generated distributor signature

This section is non-normative.

The following is an example of a distributor signature document, named signature1.xml. For legibility, the example omits the content of the various cryptographic digests and instead uses "…":

<?xml version="1.0" encoding="UTF-8"?>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#" 
  Id="DistributorSignature">
 <SignedInfo>
  <CanonicalizationMethod 
   Algorithm="http://www.w3.org/2006/12/xml-c14n11"/>
  <SignatureMethod
   Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
  <Reference URI="config.xml">
   <DigestMethod
    Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
   <DigestValue>…</DigestValue>
  </Reference>
  <Reference URI="index.html">
    <DigestMethod
     Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
     <DigestValue>…</DigestValue>
  </Reference>
  <Reference URI="#prop">
   <Transforms>
    <Transform Algorithm="http://www.w3.org/2006/12/xml-c14n11"/>
   </Transforms>
   <DigestMethod 
    Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
   <DigestValue>…</DigestValue>
  </Reference>
 </SignedInfo>
 <SignatureValue>…</SignatureValue>
 <KeyInfo>
  <X509Data>
   <X509Certificate>…</X509Certificate>
  </X509Data>
 </KeyInfo>
 <Object Id="prop"> 
  <SignatureProperties
   xmlns:dsp="http://www.w3.org/2009/xmldsig-properties">
   <SignatureProperty Id="profile" Target="#DistributorSignature">
    <dsp:Profile URI="http://www.w3.org/ns/widgets-digsig#profile"/>
   </SignatureProperty> 
   <SignatureProperty Id="role" Target="#DistributorSignature">
    <dsp:Role
      URI="http://www.w3.org/ns/widgets-digsig#role-distributor"/>
   </SignatureProperty> 
   <SignatureProperty Id="identifier" Target="#DistributorSignature">
    <dsp:Identifier>…</dsp:Identifier>
   </SignatureProperty> 
  </SignatureProperties> 
 </Object>  
</Signature>

9 Validating digital signatures

To validate the signature files of a widget package, a validator MUST run the algorithm to validate digital signatures.

The algorithm below relies on the Core Validation of [XMLDSIG] and the various validation rules defined in [Signature Properties] (links to the appropriate sections of those specifications are provided where needed for validation). This specification does not define the means or format of a failure notification: handling of signatures that are in error is left up to the implementation. The reason for validation failure can be returned by the implementation to an external entity, including reasons related to Reference validation, Signature validation, Signature Property validation and/or certificate and CRL/OCSP verification. The decision of which (if any) distributor signatures are to be validated and whether the author signature is validated is out of scope of this specification. This MAY be determined by the security policy used by the validator.

During validation, a user agent MAY treat a widget package as being in error if it deems that the key length for a signature algorithm to is not large enough to be secure (e.g., under 2048 bits for RSA and DSA).

The algorithm to validate digital signatures is as follows:

Let signatures list be the result of applying the algorithm to locate signature files in a widget package.
If the signatures list is empty (meaning no signature files were found in the widget package), terminate this algorithm and treat the widget package as an unsigned widget package: It is left up to the user agent to decide how to treat unsigned widget packages.
For each signature in signatures list:
1. If signature is not a valid [XMLDSIG] document, then signature is in error.
2. Check that signature has a ds:Reference for every file that is not a signature file. If any non-signature file is not listed, then signature is in error.
3. Check that signature has a single same-document ds:Reference to a ds:Object container for [Signature Properties] in accordance with the Signature Properties Placement section of [Signature Properties].
4. Optionally, if the ds:Signature's key length for a given signature algorithm (e.g., RSA) is less than a user agent predefined minimum key length, then signature is in error.
5. Validate the profile property against the profile URI in the manner specified in [Signature Properties]. If the profile property is missing or invalid, then signature is in error.
6. Validate the identifier property in the manner specified in [Signature Properties]. If the identifier property is missing or or invalid, then signature is in error.
7. If signature's file name matches the naming convention for an author signature, validate the role property against the author role URI. If the role property is missing or or invalid, then signature is in error.
8. Otherwise, if signature's file name matches the naming convention for a distributor signature:
  1. Validate the role property against the distributor role URI. If the role property is missing or or invalid, then signature is in error.
  2. If an author signature is present in the widget package, verify that signature has a ds:Reference for the author signature.
9. Optionally, validate any other [Signature Properties] supported by the user agent in the manner specified in [Signature Properties].
10. Perform reference validation and signature validation on signature. If validation fails, then signature is in error.
If all signatures validate successfully, treat this as a signed widget package. It is left up to the user agent to decide how to treat singed widget packages.

The algorithm to locate signature files in a widget package is as follows. This algorithm makes use of the concept of numerical order, which is the order based on the numeric portion of a distributor signature's file name. Thus in the case more than one distributor signature is to be processed, the highest numbered distributor signature is ordered first.

Let signatures be an empty list.
For each file at the root of the widget package, if the file name case-sensitively matches the naming convention for a distributor signature then append this file to the signatures list.
If the signatures list is not empty, sort the list of signatures by the file name in ascending numerical order.

For example, signature1.xml followed by signature2.xml followed by signature3.xml and so on. As another example, signature9.xml followed by signature44.xml followed by signature122134.xml and so on.
Search the root of the widget package for any file name that case-sensitively matches the naming convention for an author signature and then append this file to the signatures list.
Return signatures.

11 Security Considerations

This section is non-normative.

In addition to the security considerations described in this section, the Security Considerations of [XMLDSIG] apply to this specification. In addition, the security considerations of [Widget Packaging] also apply to this specification.

The signature scheme described in this document deals with the content present inside a potentially compressed widget package. This implies that, in order to verify a signature file, a user agent needs to decompress a data stream that can come from an arbitrary source.

Care needs to be taken to avoid resource exhaustion attacks through maliciously crafted widget packages during signature validation.

Because there is no single signature file that includes all files of a widget package, including all of the signature files, this leaves a widget package subject to an attack where distributor signatures can be removed or added. An author signature could also be attacked by removing the signature and any distributor signatures, if they are present. A signature file can also be renamed, which can affect the order in which distributor signatures are processed.

If the user agent supports installing a new root certificate, an end-user should be made aware of what they are doing, and why.

A user agent's security policy can affect how signature validation impacts operation, and can have additional constraints on establishing trust, including additional requirements on certificate chain validation and certificate revocation processing using CRLs [RFC5280] or OCSP [RFC2560]. Security policy can also require additional information to be conveyed in ds:KeyInfo. Security policy is out of scope of this specification but has important implications for signature file processing.

Acknowledgements

The Web Applications working group would like to thank members of the W3C XML Security Working Group for their comments and suggestions, as well as all reviewers of drafts of this document.

Normative References

[ABNF]: RFC 5234. Augmented BNF for Syntax Specifications: ABNF, IETF.
[C14N11]: Canonical XML Version 1.1, W3C.
[RFC2119]: Key words for use in RFCs to Indicate Requirement Levels, IETF.
[RFC5280]: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile, IETF.
[UTF-8]: UTF-8, a transformation format of ISO 10646, IETF.
[URI]: Uniform Resource Identifiers (URI): Generic Syntax, IETF.
[Widgets Packaging]: Widget Packaging and Configuration, W3C.
[XML]: Extensible Markup Language, W3C.
[XML-Namespaces]: Namespaces in XML, W3C.
[XMLDSIG]: XML Signature Syntax and Processing, W3C.
[Signature Properties]: XML Signature Properties, W3C.
[ZIP]: .ZIP File Format Specification, PKWare Inc.

Informative References

[RFC2560]: X.509 Public Key Infrastructure Online Certificate Status Protocol - OCSP, IETF.
[Widgets Requirements]: Widgets Requirements, W3C.