Please refer to the errata for this document, which may include some normative corrections.
See also translations .
Copyright
©
2013
2012
W3C
®
(
MIT
,
ERCIM
,
Keio
,
Beihang
),
All
Rights
Reserved.
W3C
liability
,
trademark
and
document
use
rules
apply.
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).
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
https://www.w3.org/TR/.
http://www.w3.org/TR/.
This
specification
is
obsolete
and
should
no
longer
be
used
as
a
basis
the
30
March
2012
W3C
Recommendation
of
the
XML
Digital
Signatures
for
implementation.
Widgets
specification.
The
Widget
specifications
became
This
document
has
been
reviewed
by
W3C
Recommendations
in
2012-2013.
They
were
designed
to
enable
interactive
single
purpose
application
for
displaying
and/or
updating
local
data
or
data
on
Members,
by
software
developers,
and
by
other
W3C
groups
and
interested
parties,
and
is
endorsed
by
the
Web,
packaged
in
Director
as
a
way
to
allow
W3C
Recommendation.
It
is
a
single
download
stable
document
and
installation
on
a
user's
machine
may
be
used
as
reference
material
or
mobile
device.
Since
2013,
Widgets
has
had
limited
deployment
cited
from
another
document.
W3C's
role
in
making
the
Recommendation
is
to
draw
attention
to
the
specification
and
to
promote
its
usage
has
been
reduced
since
then.
Service
Workers
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
App
Manifest
Applications
WG
,
part
of
the
Rich
Web
Client
Activity
are
considered
to
provide
better
solutions
nowadays.
in
the
W3C
Interaction
Domain
.
It
is
expected
that
this
document
will
progress
along
the
W3C's
Recommendation
track.
For
purposes
of
This
document
was
produced
by
a
group
operating
under
the
5
February
2004
W3C
Patent
Policy
this
Obsolete
Recommendation
.
W3C
maintains
a
public
list
of
any
patent
disclosures
has
made
in
connection
with
the
same
status
as
an
active
Recommendation;
it
retains
licensing
commitments
and
remains
available
as
a
reference
for
old
implementations
but
is
no
longer
recommended
deliverables
of
the
group;
that
page
also
includes
instructions
for
future
implementation.
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
.
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:
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:
The complete signing model is illustrated in Figure 1 .
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.
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.
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).
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]
.
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.
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] .
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.
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 .
http://www.w3.org/ns/widgets-digsig#role-author
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
".
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 .
http://www.w3.org/ns/widgets-digsig#role-distributor
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
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
.
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 :
Generate
a
role
property
in
the
manner
specified
in
[Signature
Properties]
and
let
its
URI
attribute
value
be
the
distributor
role
URI
.
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] (e.g., created , expires , replayProtect ) 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.
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#"
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#"
Id="DistributorSignature">
<SignedInfo>
<CanonicalizationMethod
<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
<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">
<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>
<SignatureProperty Id="role" Target="#DistributorSignature">
<dsp:Role
URI="http://www.w3.org/ns/widgets-digsig#role-distributor"/>
</SignatureProperty>
</SignatureProperty>
<SignatureProperty Id="identifier" Target="#DistributorSignature">
<dsp:Identifier>…</dsp:Identifier>
</SignatureProperty>
</SignatureProperties>
</Object>
</SignatureProperty>
</SignatureProperties>
</Object>
</Signature>
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 :
If signature is not a valid [XMLDSIG] document, then signature is in error .
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
.
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]
.
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 .
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 .
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 .
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 .
Otherwise, if signature 's file name matches the naming convention for a distributor signature :
Validate the role property against the distributor role URI . If the role property is missing or or invalid, then signature is in error .
If
an
author
signature
is
present
in
the
widget
package,
verify
that
signature
has
a
ds:Reference
for
the
author
signature
.
Optionally, validate any other [Signature Properties] supported by the user agent in the manner specified in [Signature Properties] .
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.
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.
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.