XML Signature Syntax and Processing Version 1.1
XML Signature Syntax and Processing Version 1.1
W3C
Recommendation 11 April 2013
This version:
Latest published version:
Latest editor's draft:
Previous version:
Editors:
Donald Eastlake
d3e3e3@gmail.com
Joseph Reagle
reagle@mit.edu
David Solo
dsolo@alum.mit.edu
Frederick Hirsch
frederick.hirsch@nokia.com
(2nd edition, 1.1)
Magnus Nyström
mnystrom@microsoft.com
(1.1)
Thomas Roessler
tlr@w3.org
(2nd edition, 1.1)
Kelvin Yiu
kelviny@microsoft.com
(1.1)
Authors:
Mark Bartel
mbartel@adobe.com
John Boyer
boyerj@ca.ibm.com
Barb Fox
bfox@Exchange.Microsoft.com
Brian LaMacchia
bal@microsoft.com
Ed Simon
edsimon@xmlsec.com
Please refer to the
errata
for this document, which may include some normative corrections.
The English version of this specification is the only normative version. Non-normative
translations
may also be available.
2013
The IETF Trust
W3C
MIT
ERCIM
Keio
Beihang
), All Rights Reserved.
W3C
liability
trademark
and
document use
rules apply.
Abstract
This document specifies XML digital signature processing rules
and syntax. XML Signatures provide
integrity
message authentication
, and/or
signer
authentication
services for data of any type, whether located within the
XML that includes the signature or elsewhere.
Status of This Document
Note
: On 23 April 2013, the reference to the "Additional XML Security URIs" RFC was updated. The Director previously authorized the publication knowing that the reference would be updated in a near future.
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 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
original version
of
this specification was produced by the IETF/
W3C
XML Signature Working Group
; the
Interoperability
Report
shows at least 10 implementations with at least two
interoperable implementations over every feature.
The
Second
Edition
was produced by the
W3C
XML Security Specifications
Maintenance Working Group
, adding Canonical XML 1.1 as a
required canonicalization algorithm and incorporating known
errata. A
detailed
list of Second Edition changes
is available as is a
Second
Edition implementation report
demonstrating four or more
implementations of all new features.
Conformance-affecting changes of XML Signature 1.1 against this previous
recommendation mainly affect the set of
mandatory to implement cryptographic algorithms, including Elliptic
Curve DSA (and mark-up for
corresponding key material), and additional hash
algorithms.
detailed explanation of changes since
the last Recommendation are
available [
XMLDSIG-CORE1-CHGS
].
Changes are also described in a
diff document showing changes since
the Second Edition
, as well as a
diff document showing changes
since the previous PR draft
Please refer to
the
implementation
report for version 1.1 of this specification
for
additional details about the implementation status of
features added in this revision.
This document was published by the
XML Security Working Group
as a Recommendation.

If you wish to make comments regarding this document, please send them to
public-xmlsec@w3.org
archives
).

All comments are welcome.
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
Additional information related to the IPR status of XML Signature 1.1
is available.
Table of Contents
1.
Introduction
1.1
Conformance
1.2
Design Philosophy
1.3
Versions, Namespaces and Identifiers
1.4
Acknowledgements
2.
Signature Overview and Examples
2.1
Simple Example (
Signature
SignedInfo
Methods
, and
Reference
s)
2.1.1
More on
Reference
2.2
Extended Example (
Object
and
SignatureProperty
2.3
Extended Example (
Object
and
Manifest
3.
Processing Rules
3.1
Signature Generation
3.1.1
Reference Generation
3.1.2
Signature Generation
3.2
Core Validation
3.2.1
Reference Validation
3.2.2
Signature Validation
4.
Core Signature Syntax
4.1
The
ds:CryptoBinary
Simple Type
4.2
The
Signature
element
4.3
The
SignatureValue
Element
4.4
The
SignedInfo
Element
4.4.1
The
CanonicalizationMethod
Element
4.4.2
The
SignatureMethod
Element
4.4.3
The
Reference
Element
4.4.3.1
The
URI
Attribute
4.4.3.2
The Reference Processing Model
4.4.3.3
Same-Document URI-References
4.4.3.4
The
Transforms
Element
4.4.3.5
The
DigestMethod
Element
4.4.3.6
The
DigestValue
Element
4.5
The
KeyInfo
Element
4.5.1
The
KeyName
Element
4.5.2
The
KeyValue
Element
4.5.2.1
The
DSAKeyValue
Element
4.5.2.2
The
RSAKeyValue
Element
4.5.2.3
The
ECKeyValue
Element
4.5.2.3.1
Explicit Curve Parameters
4.5.2.3.2
Compatibility with RFC 4050
4.5.3
The
RetrievalMethod
Element
4.5.4
The
X509Data
Element
4.5.4.1
Distinguished Name Encoding Rules
4.5.5
The
PGPData
Element
4.5.6
The
SPKIData
Element
4.5.7
The
MgmtData
Element
4.5.8
XML Encryption
EncryptedKey
and
DerivedKey
Elements
4.5.9
The
DEREncodedKeyValue
Element
4.5.10
The
KeyInfoReference
Element
4.6
The
Object
Element
5.
Additional Signature Syntax
5.1
The
Manifest
Element
5.2
The
SignatureProperties
Element
5.3
Processing Instructions in Signature Elements
5.4
Comments in Signature Elements
6.
Algorithms
6.1
Algorithm Identifiers and Implementation Requirements
6.2
Message Digests
6.2.1
SHA-1
6.2.2
SHA-224
6.2.3
SHA-256
6.2.4
SHA-384
6.2.5
SHA-512
6.3
Message Authentication
Codes
6.3.1
HMAC
6.4
Signature Algorithms
6.4.1
DSA
6.4.2
RSA (PKCS#1 v1.5)
6.4.3
ECDSA
6.5
Canonicalization Algorithms
6.5.1
Canonical XML 1.0
6.5.2
Canonical XML 1.1
6.5.3
Exclusive XML Canonicalization 1.0
6.6
Transform
Algorithms
6.6.1
Canonicalization
6.6.2
Base64
6.6.3
XPath Filtering
6.6.4
Enveloped Signature Transform
6.6.5
XSLT Transform
7.
XML Canonicalization and Syntax Constraint Considerations
7.1
XML 1.0 Syntax Constraints, and Canonicalization
7.2
DOM/SAX Processing and Canonicalization
7.3
Namespace Context and Portable Signatures
8.
Security Considerations
8.1
Transforms
8.1.1
Only What is Signed is Secure
8.1.2
Only What is "Seen" Should be Signed
8.1.3
"See" What is Signed
8.2
Check the Security Model
8.3
Algorithms, Key Lengths, Certificates, Etc.
8.4
Error Messages
9.
Schema
9.1
XSD Schema
9.2
RNG Schema
10.
Definitions
A.
References
A.1
Normative references
A.2
Informative references
1.
Introduction
This document specifies XML syntax and processing rules for creating and
representing digital signatures. XML Signatures can be applied to any
digital content (data object)
, including XML. An XML
Signature may be applied to the content of one or more resources.
Enveloped
or
enveloping
signatures are over data within
the same XML document as the signature;
detached
signatures are over data external to the signature
element. More specifically, this specification defines an XML signature
element type and an
XML signature
application
; conformance requirements for each are specified by way of
schema definitions and prose respectively. This specification also includes
other useful types that identify methods for referencing collections of
resources, algorithms, and keying and management information.
The XML Signature is a method of associating a key with referenced data
(octets); it does not normatively specify how keys are associated with persons
or institutions, nor the meaning of the data being referenced and signed.
Consequently, while this specification is an important component of secure XML
applications, it itself is not sufficient to address all application
security/trust concerns, particularly with respect to using signed XML (or
other data formats) as a basis of human-to-human communication and agreement.
Such an application must specify additional key, algorithm, processing and
rendering requirements. For further information, please see
see
section 8. Security Considerations
The Working Group encourages implementers and developers to read
XML Signature Best Practices
XMLDSIG-BESTPRACTICES
]. It
contains a number of best practices related to the use of XML
Signature, including implementation considerations and practical ways
of improving security.
1.1
Conformance
For readability, brevity, and historic reasons this document uses the term
"signature" to generally refer to digital authentication values of all types.
Obviously, the term is also strictly used to refer to authentication values
that are based on public keys and that provide signer authentication. When
specifically discussing authentication values based on symmetric secret key
codes we use the terms authenticators or authentication
codes. (See
section 8.2 Check the Security Model
.)
This specification provides a normative XML Schema
XMLSCHEMA-1
], [
XMLSCHEMA-2
]. The full normative grammar is
defined by the XSD schema and the normative text in this
specification. The standalone XSD schema file is authoritative in
case there is any disagreement between it and the XSD schema
portions in this specification.
The key words "
MUST
", "
MUST NOT
", "
REQUIRED
", "
SHALL
", "
SHALL NOT
",
SHOULD
", "
SHOULD NOT
", "
RECOMMENDED
", "
MAY
", and "
OPTIONAL
" in this
specification are to be interpreted as described in [
RFC2119
].
"They
MUST
only be used where it is actually required for interoperation
or to limit behavior which has potential for causing harm (e.g., limiting
retransmissions)"
Consequently, we use these capitalized key words to unambiguously specify
requirements over protocol and application features and behavior that affect
the interoperability and security of implementations. These key words are not
used (capitalized) to describe XML grammar; schema definitions unambiguously
describe such requirements and we wish to reserve the prominence of these
terms for the natural language descriptions of protocols and features. For
instance, an XML attribute might be described as being "optional." Compliance
with the Namespaces in XML specification [
XML-NAMES
] is described
as "
REQUIRED
."
This document specifies optional and mandatory to support
algorithms, providing references for these algorithms. This means
that a conformant implementation should for given inputs be able
to produce outputs for those algorithms that interoperate as
specified in the referenced specification. A conformant
implementation may use any technique to achieve the results as-if
it were implemented according to the referenced specification, but
is not required to follow detailed implementation techniques of
that specification.
1.2
Design Philosophy
The design philosophy and requirements of this specification are addressed
in the original XML-Signature Requirements document
XMLDSIG-REQUIREMENTS
] and the XML Security 1.1 Requirements
document [
XMLSEC11-REQS
].
1.3
Versions, Namespaces and Identifiers
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 XML
namespace URIs:
URI
namespace prefix
XML internal entity
default namespace
ds:
dsig:

dsig11:

While implementations
MUST
support XML and XML namespaces, and while use of the above namespace
URIs is
REQUIRED
, the namespace prefixes and entity declarations
given are merely editorial
conventions used in this document. Their use by implementations is
OPTIONAL
These namespace URIs are also used as the prefix for algorithm identifiers that are under
control of this specification. For resources not under the control of this specification, we use
the designated Uniform Resource Names [
URN
], [
RFC3406
or Uniform
Resource Identifiers [
URI
] defined by the relevant normative
external specification.
The
dsig:
) namespace was
introduced in the first edition of this specification. This version does not coin any new
elements or algorithm identifiers in that namespace; instead, the
dsig11:
namespace
is used.
This specification uses algorithm identifiers in the namespace
that were originally
coined in [
RFC6931
]. RFC 6931 associates these identifiers
with specific algorithms. Implementations of this specification
MUST
be fully interoperable with the algorithms specified in
RFC6931
], but
MAY
compute the requisite values through any
technique that leads to the same output.
Examples of items in various namespaces include:
SignatureProperties
is identified and defined by the
disg:
namespace
ECKeyValue
is identified and defined by the
dsig11:
namespace
XSLT is identified and defined by an external URI
SHA1 is identified via this
specification's namespace and defined via a normative reference [
FIPS-180-3
FIPS PUB 180-3.
Secure Hash Standard.
U.S. Department of
Commerce/National Institute of Standards and Technology.
No provision is made for an explicit version number in this syntax. If a future version of
this specification requires explicit versioning of the document format, a different namespace will
be used.
1.4
Acknowledgements
The contributions of the members of the XML Signature Working
Group to the first edition specification are
gratefully acknowledged: Mark Bartel, Adobe, was Accelio (Author); John Boyer, IBM (Author);
Mariano P. Consens, University of Waterloo; John Cowan, Reuters Health; Donald Eastlake 3rd,
Motorola  (Chair, Author/Editor); Barb Fox, Microsoft (Author); Christian Geuer-Pollmann,
University Siegen; Tom Gindin, IBM; Phillip Hallam-Baker, VeriSign Inc; Richard Himes, US Courts;
Merlin Hughes, Baltimore; Gregor Karlinger, IAIK TU Graz; Brian LaMacchia, Microsoft (Author);
Peter Lipp, IAIK TU Graz; Joseph Reagle, NYU, was
W3C
(Chair, Author/Editor); Ed Simon, XMLsec
(Author); David Solo, Citigroup (Author/Editor); Petteri Stenius, Capslock; Raghavan Srinivas,
Sun; Kent Tamura, IBM; Winchel Todd Vincent III, GSU; Carl Wallace, Corsec Security, Inc.; Greg
Whitehead, Signio Inc.
As are the first edition Last Call comments from the following:
Dan Connolly,
W3C
Paul Biron, Kaiser Permanente, on behalf of the
XML Schema WG
Martin J. Duerst,
W3C
; and Masahiro Sekiguchi, Fujitsu; on behalf of the
Internationalization WG/IG
Jonathan Marsh, Microsoft, on behalf of the
Extensible Stylesheet Language
WG
The following members of the XML Security Specification Maintenance Working Group contributed
to the second edition: Juan Carlos Cruellas, Universitat Politècnica de Catalunya; Pratik
Datta, Oracle Corporation; Phillip Hallam-Baker, VeriSign, Inc.; Frederick Hirsch, Nokia, (Chair,
Editor); Konrad Lanz, Applied Information processing and Kommunications (IAIK); Hal Lockhart, BEA
Systems, Inc.; Robert Miller, MITRE Corporation; Sean Mullan, Sun Microsystems, Inc.; Bruce Rich,
IBM Corporation; Thomas Roessler,
W3C
ERCIM
, (Staff contact, Editor); Ed Simon,
W3C
Invited
Expert; Greg Whitehead, HP.
Contributions for version 1.1 were received from the members of the XML Security Working Group:
Scott Cantor, Juan Carlos Cruellas, Pratik Datta, Gerald Edgar, Ken Graf, Phillip Hallam-Baker,
Brad Hill, Frederick Hirsch (Chair,
Editor), Brian LaMacchia, Konrad Lanz, Hal Lockhart, Cynthia Martin, Rob
Miller, Sean Mullan, Shivaram Mysore, Magnus Nyström, Bruce Rich, Thomas Roessler (Staff contact, Editor), Ed Simon, Chris
Solc, John Wray, Kelvin Yiu (Editor).
The Working Group thanks Makoto Murata for assistance with the
RELAX NG schemas.
2.
Signature Overview and Examples
This section provides an overview and examples of XML digital signature
syntax. The specific processing is given in
section 3. Processing Rules
The formal
syntax is found in
section 4. Core Signature Syntax
and
section 5. Additional Signature Syntax
In this section, an informal representation and examples are used to
describe the structure of the XML signature syntax. This representation and
examples may omit attributes, details and potential features that are fully
explained later.
XML Signatures are applied to arbitrary
digital content (data objects)
via an indirection. Data objects are digested, the resulting value is placed
in an element (with other information) and that element is then digested and
cryptographically signed. XML digital signatures are represented by the
Signature
element which has the following structure (where "?" denotes
zero or one occurrence; "+" denotes one or more occurrences; and "*" denotes
zero or more occurrences):
Example 1
ID

/>
/>
URI

)?



)+



)?
ID
)*

Signatures are related to
data objects
via URIs [
URI
]. Within an XML document, signatures are
related to local data objects via fragment identifiers. Such local data can be
included within an
enveloping
signature or can enclose an
enveloped
signature.
Detached signatures
are over external
network resources or local data objects that reside within the same XML
document as sibling elements; in this case, the signature is neither
enveloping (signature is parent) nor enveloped (signature is child). Since a
Signature
element (and its
Id
attribute value/name) may co-exist or be
combined with other elements (and their IDs) within a single XML document,
care should be taken in choosing names such that there are no subsequent
collisions that violate the
ID uniqueness validity constraint
XML10
].
2.1
Simple Example (
Signature
SignedInfo
Methods
, and
Reference
s)
The following example is a detached signature of the content of the HTML4
in XML specification.
Example 2
s01
Signature
Id
"MyFirstSignature"
xmlns
"http://www.w3.org/2000/09/xmldsig#"
s02
SignedInfo
s03
CanonicalizationMethod
Algorithm
"http://www.w3.org/2006/12/xml-c14n11"
/>
s04
SignatureMethod
Algorithm
"http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
/>
s05
Reference
URI
"http://www.w3.org/TR/2000/REC-xhtml1-20000126/"
s06
Transforms
s07
Transform
Algorithm
"http://www.w3.org/2006/12/xml-c14n11"
/>
s08
/Transforms>
[s09]
s10
DigestValue
dGhpcyBpcyBub3QgYSBzaWduYXR1cmUK
...DigestValue
s11
/Reference>
[s12] SignedInfo
s13
SignatureValue
>...SignatureValue
s14
KeyInfo
s15a
KeyValue
s15b
DSAKeyValue
s15c
>...><
>...><
>...><
>...s15d
/DSAKeyValue>
[s15e] KeyValue
s16
/KeyInfo>
[s17] Signature
[s02-12]
The required
SignedInfo
element is the information that is actually signed.
Core validation
of
SignedInfo
consists of two mandatory processes:
validation of the signature
over
SignedInfo
and
validation of each
Reference
digest within
SignedInfo
. Note that
the algorithms used in calculating the
SignatureValue
are also included in the signed information while
the
SignatureValue
element is outside
SignedInfo
[s03]
The
CanonicalizationMethod
is the algorithm
that is used to canonicalize the
SignedInfo
element before it is digested as part of the signature
operation.
Note that this example is not in canonical form. (None of the examples in this
specification are in canonical form.)
[s04]
The
SignatureMethod
is the algorithm that
is used to convert the canonicalized
SignedInfo
into the
SignatureValue
. It is a
combination of a digest algorithm and a key dependent algorithm and possibly
other algorithms such as padding, for example RSA-SHA1. The algorithm names
are signed to resist attacks based on substituting a weaker algorithm. To
promote application interoperability we specify a set of signature algorithms
that
MUST
be implemented, though their use is at the discretion of the
signature creator. We specify additional algorithms as
RECOMMENDED
or
OPTIONAL
for implementation; the design also permits arbitrary user specified
algorithms.
[s05-11]
Each
Reference
element includes the
digest method and resulting digest value calculated over the identified data
object. It also may include transformations that produced the input to the
digest operation. A data object is signed by computing its digest value and a
signature over that value. The signature is later checked via
reference
and
signature validation
[s14-16]
KeyInfo
indicates the key to be used to
validate the signature. Possible forms for identification include
certificates, key names, and key agreement algorithms and information -- we
define only a few.
KeyInfo
is optional for two reasons. First, the signer may not
wish to reveal key information to all document processing parties. Second, the
information may be known within the application's context and need not be
represented explicitly. Since
KeyInfo
is outside of
SignedInfo
, if the signer wishes to bind the keying information to the
signature, a
Reference
can easily identify and include the
KeyInfo
as part of the signature.
Use of
KeyInfo
is optional, however note that senders and receivers
must agree on how it will be used through a mechanism out of scope for
this specification.
2.1.1
More on
Reference
Example 3
s05
Reference
URI
"http://www.w3.org/TR/2000/REC-xhtml1-20000126/"
s06
Transforms
s07
Transform
Algorithm
"http://www.w3.org/2006/12/xml-c14n11"
/>
s08
/Transforms>
[s09]
s10
DigestValue
dGhpcyBpcyBub3QgYSBzaWduYXR1cmUK
...DigestValue
s11
Reference
[s05]
The optional
URI
attribute of
Reference
identifies the data object to be signed. This attribute
may be omitted on at most one
Reference
in a
Signature
. (This limitation is
imposed in order to ensure that references and objects may be matched
unambiguously.)
[s05-08]
This identification, along with the transforms, is a
description provided by the signer on how they obtained the signed data object
in the form it was digested (i.e. the digested content). The verifier may
obtain the digested content in another method so long as the digest verifies.
In particular, the verifier may obtain the content from a different location
such as a local store than that specified in the
URI
[s06-08] Transforms
is an optional ordered list of processing
steps that were applied to the resource's content before it was digested.
Transforms can include operations such as canonicalization, encoding/decoding
(including compression/inflation), XSLT, XPath, XML schema validation, or
XInclude. XPath transforms permit the signer to derive an XML document that
omits portions of the source document. Consequently those excluded portions
can change without affecting signature validity. For example, if the resource
being signed encloses the signature itself, such a transform must be used to
exclude the signature value from its own computation. If no
Transforms
element is present, the resource's content is digested
directly. While the Working Group has specified mandatory (and optional)
canonicalization and decoding algorithms, user specified transforms are
permitted.
[s09-10] DigestMethod
is the algorithm applied to the data
after
Transforms
is applied (if specified) to yield the
DigestValue
. The signing of the
DigestValue
is what binds the content of a resource to
the signer's
key.
2.2
Extended Example (
Object
and
SignatureProperty
This specification does not address mechanisms for making statements or
assertions. Instead, this document defines what it means for something to be
signed by an XML Signature (
integrity
message authentication
, and/or
signer
authentication
). Applications that wish to represent other semantics must
rely upon other technologies, such as [
XML10
], [
RDF-PRIMER
]. For
instance, an application might use a
foo:assuredby
attribute within its own markup to reference a
Signature
element. Consequently, it's the application that must
understand and know how to make trust decisions given the validity of the
signature and the meaning of
assuredby
syntax. We also define a
SignatureProperties
element type for the inclusion of assertions
about the signature itself (e.g., signature semantics, the time of signing or
the serial number of hardware used in cryptographic processes). Such
assertions may be signed by including a
Reference
for the
SignatureProperties
in
SignedInfo
. While the signing
application should be very careful about what it signs (it should understand
what is in the
SignatureProperty
) a receiving application has no obligation to
understand that semantic (though its parent trust engine may wish to). Any
content about the signature generation may be located within the
SignatureProperty
element. The mandatory
Target
attribute
references the
Signature
element to which the property applies.
Consider the preceding example with an additional reference to a local
Object
that includes a
SignatureProperty
element. (Such a signature would not only be
detached
[p02]
but
enveloping
[p03]
.)
Example 4
Signature
Id
"MySecondSignature"
...>
p01
SignedInfo
...
p02
Reference
URI
"http://www.w3.org/TR/xml-stylesheet/"
...
p03
Reference
URI
"#AMadeUpTimeStamp"
p04
Type
"http://www.w3.org/2000/09/xmldsig#SignatureProperties"
p05
Transforms
p06
Transform
Algorithm
"http://www.w3.org/2006/12/xml-c14n11"
/>
p07
/Transforms>
[p08]
p09
DigestValue
dGhpcyBpcyBub3QgYSBzaWduYXR1cmUK
...DigestValue
p10
/Reference>
[p11] SignedInfo
p12
...
p13
Object
p14
SignatureProperties
p15
SignatureProperty
Id
"AMadeUpTimeStamp"
Target
"#MySecondSignature"
p16
timestamp xmlns
"http://www.ietf.org/rfcXXXX.txt"
p17

19990914
/date>
[p18]