This document defines a profile of the XML Signature Syntax and Processing 1.1 specification to allow a widget package to be digitally signed. Widget authors and distributors can digitally sign widgets as a mechanism to ensure continuity of authorship and distributorship. Prior to instantiation, a user agent can use the digital signature to verify the integrity of the widget package and to confirm the signing key(s). This document specifies conformance requirements on both widget packages and user agents.
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/.
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.
This is the 11 May 2010 Last Call Working Draft of "Digital Signatures for Widgets". The Last Call period ends on 1 June 2010.
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.
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. The public is encouraged to send comments to the WebApps Working Group's public mailing list email@example.com (archive). See W3C mailing list and archive usage guidelines. A detailed list of changes from the previous version is also available from the W3C's CVS server.
Since the last publication, the Working Group made further changes to the specification. The Working Group believes that these changes should have limited impact on existing implementation and the changes were mostly to clarify certain ambiguous aspects detailed below. Regardless, if you have implemented a previous draft, then you should read this section carefully as it could potentially affect your implementation.
The following normative statements were removed from the specification:
1.The URI attribute of every ds:Reference to a file entry must be a URL-encoded [URI] zip relative path that identifies a file inside the widget package.
2.Within a widget package these signature files must be ordered based on the numeric portion of the signature file name.
For 1., Zip-relative paths are URI safe so URL Encoding is not necessary. Also, the algorithm for looking up files would fail because the algorithm did not instruct user agents to decode encoded URIs. In this new version of the spec, a signer is no longer required to encode Zip-relative paths.
For 2., It is the WG's position that this assertion was putting an unnecessary optimization on the signer (and might be beyond the control of the signer, as might be the case when the author manually has to create the zip file). It was evident that 2. was simply an optimization because the validator uses the "Locating and Processing Digital Signatures for the Widget". Using that rule assumes that the signatures will be in a random order within the zip archive. Removing 2. from the specification should have no impact on current implementations.
Lastly, members of the Mobile Web Test Suites Working Group pointed out that, aside from a number of editorial issues, the conformance model of the previous draft was ambiguous: it mixed conformance criteria for too many products. Because of the ambiguous conformance model, it became clear that it would not be possible to create a suitable test suite. To overcome this limitation in the specification, the Working Group applied the Method for Writing Testable Conformance Requirements defined in [Test-Methodology]. The result is a restructured specification whose conformance model now only applies to two classes of products: signers and validators. The Working Group believes that the specification is testable, and a test suite harness has been created that will allow testing those two products independently.
A widget package can be signed by the author producing an [XMLDSIG11] signature that cryptographically includes all of the file entries other than signature files. A widget package can also be signed by one or more distributors of the widget, producing [XMLDSIG11] signatures that each cryptographically includes all of the non-signature file entries as well as any author signature.
This section is non-normative.
Defined terms appear as this sample defined term. Such terms are referenced as sample defined term, providing a link back to where the term is defined.
Words that denote a conformance clause or testable assertion use keywords from [RFC2119]: MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY and OPTIONAL.
Variables are formatted specially, e.g. variable. Code is
also specially formatted, such as
Examples are highlighted to indicate the whole:
This is an example containing some code:
<?xml version="1.0" encoding="UTF-8"?>
Notes are highlighted specially and are used to note editorial issues, or items to be aware of.
The following terms are used throughout this specification so they are gathered here for the readers convenience. The following list of terms is not exhaustive; other terms are defined throughout this specification.
A file entry is the data held by a local file header, file data, and (optional) data descriptor, as defined in the [ZIP] specification, for each physical file contained in a Zip archive.
An unsigned widget package is a widget package that does not contain any signature files.
A signature file is a file entry containing a detached [XMLDSIG11] signature that adheres to the common constraints for signature generation and validation whose file name conforms to the naming conventions of a signature file name. Signature files are located at the root of the widget package.
The following URI is the XML namespace for [XML] elements used by this specification:
Note: While use of the above namespace URI is mandatory for XML elements used by this specification, the namespace prefix and entity declaration given below are merely editorial conventions used in this document. Their use by authors of digital signature documents is optional.
<!ENTITY wsig "http://www.w3.org/ns/widgets-digsig">
For resources not under the control of this specification, we use the Uniform Resource Identifiers [URI] defined by the relevant specifications. For example:
Roleare defined in the
See the XML Security Algorithm Cross-Reference for details [XMLSecAlgs].
Note: 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.
This section is non-normative.
Example of a distributor
signature document, named
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="icon.png"> <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="#DistributorASignature"> <dsp:Profile URI="http://www.w3.org/ns/widgets-digsig#profile"/> </SignatureProperty> <SignatureProperty Id="role" Target="#DistributorASignature"> <dsp:Role URI="http://www.w3.org/ns/widgets-digsig#role-distributor"/> </SignatureProperty> <SignatureProperty Id="identifier" Target="#DistributorASignature"> <dsp:Identifier>07425f59c544b9cebff04ab367e8854a</dsp:Identifier> </SignatureProperty> </SignatureProperties> </Object> </Signature>
The design goals and requirements for this specification are addressed in the [Widgets Requirements] document. This document addresses the following requirements:
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]. When intended as conformance requirements, the words appear capitalized.
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 validator is an implementation of this specification that follow the rules for signature validation to validate the digital signatures within a widget package.
Note: User agents that implement this specification are encouraged to provide mechanisms to enable end-users to install certificates for enabling verification of digital signatures within the widget package.
This section defines the conformance requirements for signature generation as they apply to a signer.
A signer MUST apply the Common Constraints for Signature Generation and Validation upon signature generation.
The signer MUST NOT generate widget signatures using key lengths of less than the recommended key length unless the life time of the signature is less than one year. Regardless, the key length of the key used by a signer to generate the signature MUST NOT be less than 1024 bits.
It is OPTIONAL for a signer
to make the signature file names of distributor signatures form a
contiguous set of numeric values (i.e., it is not required that signature
files names of distributor signatures follow the pattern
signature3.xml, and so on. Signers are free to use whatever pattern they want, so
long as the file name conforms to the naming convention for a
A signer MUST
ensure that every
ds:Reference to same-document XML content
has exactly one
ds:Transform element to specify the
Note: This means that a
ds:Reference to the
ds:Object element will require a
element to specify canonicalization method. A reference to
config.xml will not, however, since it is not a
Note: Signing parties are expected to ensure that the
dsp:Identifier signature property value is unique for the
widgets that they sign.
This section defines the conformance requirements for signature validation as they apply to a validator.
If widget signature validation is successful or fails, the validator MUST notify any external entities relying on the validation of the widget signature. An example of an external entity is, for example, a user agent that implements [Widgets Packaging].
Note: This specification does not define the means or format of a failure notification, which is left up to implementers. 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.
A validator MUST verify the Common Constraints for Signature Generation and Validation upon signature validation.
If a validator finds that a file entry matching the naming convention for a
distributor signature that does not contain a
signature property having the URI for a distributor role, then the validator MUST treat the
signature as being in error.
If a validator finds that a file
entry matching the naming convention for
an author signature that does not contain a
signature property having the URI for a author role, then the validator MUST treat the signature as being in error.
ds:KeyInfo element is present, then a validator MUST check that the
ds:KeyInfo conforms to the [XMLDSIG11] specification by performing Basic Path
Validation [RFC5280] on the signing key. A validator SHOULD perform
revocation checking as appropriate.
A validator SHOULD be able to process a
same- document XML content when that
ds:Reference does not
ds:Transform, for backward compatibility.
Note: A user agent's security policy can affect how signature validation impacts operation, and may 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 may 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
When a signer digitally signs a widget package, or a validator validates a widget package, it MUST make sure that the following requirements on a widget signature apply to all widget signatures included in widget package:
Each widget signature
dsp:Profile signature properties element
compliant with the [XMLDSIG-Properties] and this
dsp:Profile property has the
URI attribute value of
ds:Reference used within a widget signature is one of the following
two kinds of reference:
ds:Reference to an item within the widget signature uses an
IDREF value for the
URI attribute, referring to a unique ID
(as defined in [XML-Schema-Datatypes]) within the
An author signature is a widget signature with a signature file name that adheres to the
for an author signature and has an [XMLDSIG-Properties]
URI attribute is equivalent
to the author role
attribute value. An author signature is intended to be generated by
the author of the widget. The author
signature can be used to determine:
RoleAttribute value (
author-sig-filename = %x126.96.36.199.6f.72.2d.188.8.131.52e.184.108.40.206.65.2e.78.6d.6c
rule defines the lower-case (case-sensitive) string
A distributor signature is a widget signature with a signature file name that adheres to the
for a distributor signature and has an [XMLDSIG-Properties]
URI is equivalent to the distributor role attribute
value. A distributor signature is intended to be generated by a third
party (a distributor) that is distributing
the widget on behalf of the author. The distributor signature can be used to
RoleAttribute value (
In addition, the
ds:References for every file entry
of the widget package, including any author signature, but excluding any distributor
signatures. In other words, distributor signatures countersign author signatures,
but will not countersign other distributor signatures.
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 zero or more digits in the range 0-9 inclusive and
then the lower-case "
dist-sig-filename = signature-string non-zero-digit *DIGIT xml-suffix-string signature-string = %x220.127.116.11e.18.104.22.168.65 non-zero-digit = %x31-39 xml-suffix-string = %x2e.78.6d.6c
signature-string rule defines the lower-case string
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
xml-suffix-string rule defines the lower-case
(case-sensitive) string "
An example is
Every widget signature can have additional information contained in the
ds:X509Data element, as specified by the [XMLDSIG11] specification. This can include X.509
certificates, and/or CRL and/or OCSP response information that, if
included, are conveyed according to the [XMLDSIG11] specification.
A validator MUST support processing X.509 v3 certificates for when
certificates are used in the
ds:X509Data of a digital
Note: v3 certificates are necessary to use the v3 extension to express the basic constraints on a certificate. This allows CA certificates to be distinguished from end entity certificates, enabling more robust trust verification.
A signer uses the
signature property to uniquely identify the signature (for example, to
enable signature management).
Note: Signing parties are expected to ensure that the
dsp:Identifier signature property value is unique for the
widget packages that they sign.
Note: Signing a widget with an optional algorithm can result in signatures that are not interoperable with implementations that do not support these algorithms. Authors are cautioned to take this into consideration when signing widget packages.
This section defines the signature algorithms that this specification relies upon. The recommended key length of the key used to generate a signature is 2048 bits.
The following signature algorithms MUST be supported by a validator:
The following signature algorithms MUST be supported by a signer:
It is OPTIONAL for a signer to support the following signature algorithm:
Note: Although not all validators may support this optional algorithm, implementation is encouraged since it may become mandatory in a subsequent release of this specification. This may also be necessary if any security issues are discovered with the currently required algorithm.
It is OPTIONAL for an implementation to support additional signature algorithms.
The following digest algorithms MUST be supported by an implementation:
It is OPTIONAL for an implementation to support additional digest algorithms.
The following canonicalization algorithms MUST be supported by an implementation:
It is OPTIONAL for an implementation to support additional canonicalization algorithms.
This section defines for how to locate signature files in a widget package for the purpose of signature validation.
An implementation MUST perform a case-sensitive comparisons on file names.
signatures be an empty list.
signature1.xml followed by
signature2.xml followed by
As another example,
signature44.xml followed by
signature122134.xml and so on.
For example, validate
As another example, validate
signature9.xml, and lastly
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.
Numerical order is the order based on the numeric portion of the signature file name. Thus in the case more than one distributor signature is to be processed, the highest numbered distributor signature is processed first.
This section defines a set of common constraints for signature generation and validation.
The set of constraints are as follows:
Algorithm attribute of the
ds:digestMethod MUST be one of the
ds:Reference to same-document XML
content MUST have a
element child that specifies the canonicalization method. Canonical
XML 1.1 MUST be specified as the Canonicalization
Algorithm for this transform. A
ds:Reference that is not
to same-document XML content MUST NOT have any
An implementation SHOULD be able to
ds:Reference to same-document XML content when
ds:Reference does not have a
ds:Transform child element, for backward compatibility.
In this case the default canonicalization algorithm Canonical XML 1.0
will be used, as specified in XML Signature 1.1.
Note: The relevant section in XML Signature 1.1 is
section 22.214.171.124, "The Reference Processing Model". This section
states "Unless the URI- Reference is such a ‘
same-document’ reference , the result
of dereferencing the URI-Reference MUST be an octet stream. In
particular, an XML document identified by URI is not parsed by the
signature application unless the URI is a same-document reference or
unless a transform that requires XML parsing is applied." In the same
section the specification notes, "In this specification, a
same- document’ reference is
defined as a URI-Reference that consists of a hash sign (‘
#’) followed by a fragment or alternatively
consists of an empty URI…" [XMLDSIG11].
Every Signature Property required by this specification is to be incorporated into the signature as follows:
A widget signature MUST include a
ds:Object element within
ds:Signature element. This
element MUST have an
that is referenced by a
ds:Reference element within the
ds:Object element MUST contain a single
ds:SignatureProperties element that MUST contain a different
ds:SignatureProperty element for each property required
by this specification.
ds:Signature property required by this
specification MUST meet the syntax requirements
ds:Signature needs to meet the following
Algorithm attribute of the
ds:CanonicalizationMethod element MUST be one of the canonicalization algorithms.
ds:SignatureMethod algorithm used in
ds:SignatureValue element MUST
be one of the signature
ds:Signature MUST be produced using a key of the recommended key length or stronger
(meaning larger than 2048 bits).
ds:KeyInfo element MAY be
included, which MAY include CRL and/or OCSP
information in a manner compliant with the [XMLDSIG11] specification.
If one or more certificates are in the
ds:KeyInfo element, they MUST be of
the mandatory certificate
ds:SignedInfo element MUST
include all the
ds:Reference elements listed in items 1,
2 and 4 of this section.
The widget signature MUST be serialized as a [UTF-8] encoded [XML] document and be named using the appropriate naming convention: either the naming convention for a distributor signature or the naming convention for an author signature.
This section is non-normative.
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 widget signature, implementations need to decompress a data stream that can come from an arbitrary source. A signature according to this specification does not limit the attack surface of decompression and unpacking code used during signature extraction and verification.
Care needs to be taken to avoid resource exhaustion attacks through maliciously crafted widget packages during signature validation.
Implementations need to be careful about trusting path components found in the widget package. Such path components might be interpreted by operating systems as pointing at security critical files outside the widget environment proper, and naive unpacking of widget packages into the file system might lead to undesirable and security relevant effects, such as overwriting of startup or system files.
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.
Mechanisms to install new root certificates in a user agent need to be subject to security critical mechanisms. End-users should be made aware of what they are doing and why when installing a new root certificate.
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.