Copyright © 2009 W3C ® ( MIT , ERCIM , Keio ), All Rights Reserved. W3C liability , trademark and document use rules apply.
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 is the 12 June 2009 Candidate Recommendation of the Widgets 1.0: Digital Signature specification. W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. The Web Applications (WebApps) Working Group expects to request that the Director advance this document to Proposed Recommendation once the Working Group has developed a comprehensive Widgets 1.0: Digital Signature test suite, and demonstrated at least two interoperable implementations for each test. The WebApps Working Group expects to show these implementations by September 2009. The Working Group does not plan to request to advance to Proposed Recommendation prior to 01 September 2009.
Publication as a Working Draft
Candidate Recommendation 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 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 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 public-webapps@w3.org ( 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.
This is the 30 April 2009 Last Call
Working Draft version of the "Widgets 1.0 Digital Signature
Specification". The Last Call period ends on 1 June 2009.
This document is produced by the Web Applications WG , part of
the Rich Web Clients
Activity in the W3C Interaction Domain .
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.
A widget package can be signed by
the author of the widget producing an [XMLDSIG11] signature that cryptographically
includes all of the file entries other than signature file s. 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 specification makes use of [XML-Namespaces] , and uses Uniform Resource Identifiers [URI] to identify resources, algorithms, and semantics.
Implementations of this specification MUST use the following URI as the XML namespace for [XML] elements used by this specification:
http://www.w3.org/ns/widgets-digsig
Implementations MUST support the [XML] specification and the [XML-Namespaces] specification.
While use of the above namespace URI is REQUIRED 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">
wsig:
For resources not under the control of this specification, we use the designated Uniform Resource Identifiers [URI] defined by the relevant specifications. For example:
ds:
namespacehttp://www.w3.org/2000/09/xmldsig
ds11:
namespacehttp://www.w3.org/2009/xmldsig11
Role
are defined in the dsp:
namespacehttp://www.w3.org/2009/xmldsig-properties
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.
A widget package is a [Zip] archive that conforms to the [Widgets Packaging] specification.
A file entry is the compressed (or Stored [ZIP] ) representation of a physical file or folder contained within a widget package , as defined in the [Widgets Packaging] specification.
The root of the widget package is the top-most path level of the widget package that can logically contain one or more file entries, as defined in the [Widgets Packaging] specification.
A file name is the name of a file contained in a widget package (derived from the file name field of a local file header of a file entry ), as defined in the [Widgets Packaging] specification. All file names MUST be treated as case-sensitive. In other words, case matters in file name comparisons.
A digitally signed
widget package is a widget
package that contains one or more signature file
s. files .
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 (as profiled in this specification) whose file name follows the naming conventions of a signature file name .
A signature file name is a
file name for a file
entry that represents a signature
file . This specification defines the naming conventions for
both author
signature signatures s and
distributor signature
s. signatures .
A widget signature is an [XMLDSIG11] signature, as contained in a signature file .
An author signature is a
widget signature with a widget signature
file name that adheres to the naming convention for
an author signature and has an [XMLDSIG-Properties] Role
element whose URI
attribute is
equivalent to the author role attribute value . An
author signature is intended to be generated by the author of a
widget (i.e., the person who authored the widget).
A distributor signature is
a widget signature with a signature file name that adheres to the
naming
convention for a distributor signature and has an [XMLDSIG-Properties] Role
element whose URI
is equivalent to
the distributor role attribute
value . A distributor signature is intended to be generated by
the distributor of a widget (i.e., a third party that is
distributing the widget on behalf of the author).
A wall clock timestamp is defined in the [XMLDSIG-Properties] specification.
A zip relative path MUST conform to the [ABNF] for
zip-rel-path
as specified in [Widgets Packaging] .
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 code
.
Examples are highlighted to indicate the whole:
if (a <> 1234122){ //...do something }
Notes are highlighted specially and are used to note editorial issues, or items to be aware of.
This specification uses [ABNF] syntax to
define file names. Rules are concatenated by being written next to
each other. A rule prefixed by *
means zero or more.
See [ABNF] for details on this syntax.
This section is non-normative.
Example of a distributor
signature document, named signature1.xml
:
<?xml version="1.0" encoding="UTF-8"?>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#"
Id="DistributorASignature">
<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">
<DigestMethod
Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
<DigestValue>...</DigestValue>
</Reference>
</SignedInfo>
<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>
<SignatureValue>...</SignatureValue>
<KeyInfo>
<X509Data>
<X509Certificate>...</X509Certificate>
</X509Data>
</KeyInfo>
</Signature>
The design goals and requirements for this specification are addressed in the Widgets 1.0 Requirements document [Widgets Requirements] . This document addresses the following requirements:
reference
element,
and ds:SignedInfo
element.In particular, this specification explicitly supports both
author
signature signatures s and
distributor signature
s. signatures .
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:
Products that generate a widget signature MUST generate [XML] documents that conform to [XMLDSIG11] and conform to this specification.
A user agent is an implementation that attempts to support this specification. A user agent MUST behave as described by this specification in order to claim conformance.
Implementers 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 how to locate signature files in a widget package for processing. An implementation MUST achieve the same result as the following algorithm used to locate signature files in a widget package :
Let signatures
be an empty list.
For each file entry in the root of the widget package , if
the file name matches the naming convention for
a distributor signature then append this file entry to the signatures
list.
An Implementation MUST perform a case-sensitive
comparison.
If the signatures
list is not empty, sort the list
of signatures
by the file name field in ascending
numerical order (e.g. signature1.xml
followed by
signature2.xml
followed by signature3.xml
etc).
Search the root of the
widget package for any file name that
matches the naming convention for
an author signature and then append this file entry to the signatures
list.
An Implementation MUST perform a case-sensitive
comparison.
If the signatures
list is empty (meaning no
signature
file files s were
found), terminate this algorithm and treat this widget package as
an unsigned widget package
.
Validate the signature files in the signature list in numerical
descending order, with distributor signature signatures s first
(if any).
The decision of which (if any) distributor signature signatures s 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 user agent.
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.
Ordering of widget signature file
files s
by the numeric portion of the file name
can be used to allow consistent processing and possible
optimization.
Every signature that is verified MUST be verified according to Signature Verification defined in this specification.
A widget package MAY be digitally signed using the profile of [XMLDSIG11] defined by this specification.
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 processing.
When a widget package is signed according to this specification, the following requirements on a widget signature apply to any widget signature included in widget package :
Each signature file MUST appear at the root of the widget package .
Each widget signature MUST be a detached XML Signature that complies with XML Signature 1.1 syntax [XMLDSIG11] .
Each widget signature MUST be generated and validated in a manner compliant with XML Signature 1.1 processing rules [XMLDSIG11] .
Each widget signature MUST contain a dsp:Profile
signature
properties element compliant with the [XMLDSIG-Properties] and this
specification. This dsp:Profile
property MUST have the URI
attribute value of
http://www.w3.org/ns/widgets-digsig#profile
.
Each widget signature MUST contain a dsp:Role
signature properties
element compliant with the [XMLDSIG-Properties] and this
specification.
Each widget signature MUST contain a dsp:Identifier
signature
properties element compliant with XML Signature Properties [XMLDSIG-Properties] and this
specification.
Every ds:Reference
used within a widget signature MUST
have a URI
attribute.
Every ds:Reference
used within a widget signature MUST
be one of the following two kinds of reference:
ds:Signature
elementEvery ds:Reference
to an item within the widget signature MUST
use an IDREF
value for the ds:Reference
URI
attribute, referring to a
unique ID (as defined in [XML-Schema-Datatypes] ) within the
widget signature .
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.
The author signature can be used to determine:
A widget package MAY contain zero or one author signature
s. signatures .
In addition to the requirements on a widget
signature , the following MUST be true of
an author signature ‘ s 's [XMLDSIG-Properties] Role
element ’s element's URI
attribute value:
Role
Attribute value ( URI
):http://www.w3.org/ns/widgets-digsig#role-author
In addition, the ds:Signature
MUST have ds:Reference
s for every file entry of the widget package other than any widget signature .
The author-sig-filename
[ABNF] rule defines the naming convention for
an author signature , as it applies to the signature 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
".
A file matching the author-sig-filename
[ABNF] rule MUST contain a
dsp:Role
signature property having the URI for an
Author role as defined in this specification or the signature
MUST be flagged as being in error.
The distributor signature can be used to determine:
A widget package MAY contain zero, one, or more distributor
signature s. signatures .
In addition to the requirements on a widget
signature , the following MUST be true of
an distributor signature
‘ s 's
[XMLDSIG-Properties]
Role
element ’s
element's URI
attribute value:
Role
Attribute value ( URI
):http://www.w3.org/ns/widgets-digsig#role-distributor
In addition, the ds:Signature
MUST include ds:Reference
s for every
file entry of the widget package , including any author signature , but excluding any
distributor signature
s. signatures . In other
words, distributor
signature s MUST countersign author signature s, signatures , but MUST NOT
countersign other distributor signature
s. signatures .
Each distributor signature
MUST have 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
string " .xml
".
The dist-sig-filename
[ABNF] rule formally defines the naming convention for a
distributor signature , as it applies to the signature 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
(case-sensitive) string " signature
".
The non-zero-digit
rule defines a digit in the
range 1-9
.
DIGIT
is defined in [ABNF] 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".
Leading zeros are disallowed in the numbers.
A file entry whose file name does not match the above ABNF MUST be ignored, meaning that an implementation MUST NOT treat the file entry as a signature file .
For example, a file with the file name " signature01.xml
" will be
ignored.
It is OPTIONAL that the signature file name s of distributor
signature signatures s form
a contiguous set of numeric values.
Within a widget package these signature files MUST be ordered based on the numeric portion of the signature file name.
Thus, for example, signature2.xml
precedes signature11.xml
.
A file matching the dist-sig-filename
[ABNF] rule MUST contain a
dsp:Role
signature property having the URI for a
Distributor role as defined in this specification or the signature
MUST be flagged as being in error.
Every widget signature MAY have additional
information contained in the signature ds:X509Data
element as specified by the [XMLDSIG11]
specification. This MAY include X.509
certificates, and/or CRL and/or OCSP response information that, if
included, MUST be conveyed according to the
[XMLDSIG11] specification.
The X.509 certificate format MUST be
supported when certificates are used in the
ds:X509Data
. This is the mandatory certificate format .
The RECOMMENDED version of the certificate
format is X.509 version 3 as specified in [RFC5280] . Implementations MUST
be prepared to accept X.509 v3 certificates [RFC5280] .
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.
Identifier
Signature PropertyThe signer uses the dsp:Identifier
signature
property to uniquely identify the signature to enable signature
management. It MUST be unique for a given
signer. Signing parties are expected to ensure that the
dsp:Identifier
signature property value is unique for
the widget packages that they sign.
Definitions of the algorithm URI identifiers specified in [XMLDSIG11] take precedence if there is any difference in this document. Rules specified in [XMLDSIG11] regarding use of these algorithms MUST be followed. Note that use of optional algorithms may result in signatures that are not interoperable with implementations that do not support these algorithms. Authors are cautioned to take this into consideration.
The following signature algorithms MUST be supported:
http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
http://www.w3.org/2000/09/xmldsig#dsa-sha1
The following signature algorithms SHOULD be supported:
http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256
Note: Although all implementations may not 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.
A user agent MAY support additional signature algorithms.
The RECOMMENDED key length ( recommended key length ) of the key used to generate the signature is 2048 bits. The key length of the key used to generate the signature MUST NOT be less than 1024 bits. The signer MUST NOT generate signatures using key lengths of less than 2048 bits unless the life time of the signature is less than one year.
The following digest algorithms MUST be supported:
REQUIRED : SHA-256
http://www.w3.org/2001/04/xmlenc#sha256
A user agent MAY support additional digest methods.
The following canonicalization algorithms MUST be supported:
REQUIRED : Canonical Exclusive
XML 1.1 Canonicalization 1.0 (omits comments) [XML-exc-C14N]
http://www.w3.org/2006/12/xml-c14n11 http://www.w3.org/2001/10/xml-exc-c14n#
A user agent MAY support additional XML canonicalization methods.
The following constraints apply to both Signature Generation and Signature Verification . These constraints MUST be observed when generating a widget signature and MUST be verified as met when validating a widget signature .
A widget signature MUST have a ds:Reference
for every file entry that is not a widget signature .
A distributor signature
MUST have a ds:Reference
for any
author signature , if one is
present within the widget package
.
For each ds:Reference
element:
The URI
attribute MUST be a zip relative
path from the root of the
widget package to the file entry
being referenced.
The Algorithm
attribute of the
ds:digestMethod
MUST be one of the
digest algorithms .
The ds:Reference
MUST NOT have
any ds:Transform
elements.
Every Signature Property required by this specification MUST be incorporated into the signature as follows:
A widget signature MUST include a ds:Object
element within the
ds:Signature
element. This ds:Object
element MUST have an Id
attribute
that is referenced by a ds:Reference
element within
the signature ds:SignedInfo
element.
This 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.
Each ds:Signature
property required by this
specification MUST meet the syntax requirements
of [XMLDSIG-Properties] .
The ds:Signature
MUST meet the
following requirements:
The Algorithm
attribute of the
ds:CanonicalizationMethod
element MUST be one of the canonicalization algorithms
.
The ds:SignatureMethod
algorithm used in the
ds:SignatureValue
element MUST be
one of the signature
algorithms . The ds:Signature
MUST be produced using a key of the recommended key length or stronger
(meaning larger than 2048 bits).
The ds:KeyInfo
element MAY be
included and MAY include certificate, CRL
and/or OCSP information. If so, it MUST be
compliant with the [XMLDSIG11]
specification. If certificates are used, they MUST conform to the mandatory certificate format
.
The 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 .
A widget signature MUST be generated according to the Core Generation rules specified in [XMLDSIG11] , including rules on Reference Generation and Signature Generation.
The Common Constraints for Signature Generation and Validation MUST be met on signature generation.
A unique identifier string for the signature MUST be placed in the dsp:Identifier
signature property by the signer. This MUST be
a unique signing string for all widget signature
signatures s created by the signer. Signing parties are
expected to ensure that the dsp:Identifier
signature
property value is unique for the widgets that they sign.
A widget signature MUST be validated according to Core Validation, as defined in XML Signature [XMLDSIG11] , including Reference Validation and Signature Validation.
The Common Constraints for Signature Generation and Validation MUST be met on signature validation.
If a ds:KeyInfo
element is present, then it
MUST conform to the [XMLDSIG11] specification. If present, the user
agent MUST perform Basic Path Validation
[RFC5280] on the signing key and SHOULD perform revocation checking as appropriate.
If widget signature validation is successful any external entities (e.g., a user agent that implements [Widgets Packaging] relying on the validation of the widget signature MUST be notified of the success.
If widget signature validation fails for any reason, any external entities (e.g., a user agent that implements [Widgets Packaging] ) relying on the validation of the widget signature MUST be notified of the failure. This specification does not define the means or format of a failure notification, which is left up to implementers. The reason for validation failure MAY 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.
This section is non-normative.
The signature scheme described in this document deals with the content present inside a 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 should be taken to avoid resource exhaustion attacks through maliciously crafted widget packages during signature verification.
Implementations should 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
signature signatures s can
be removed or added. An author
signature could also be attacked by removing it and any
distributor signature signatures s if
they are present. A signature file may also be renamed, which can
affect the order in which distributor signatures are processed.
Mechanisms to install new root certificates in a user agent should 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 earlier drafts of this document.