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
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/.
Table of Contents
-
Introduction
- Editorial
Conventions
- Design
Philosophy
- Versions,
Namespaces and Identifiers
- Acknowledgements
-
Signature Overview and
Examples
-
Simple Example
(
Signature, SignedInfo,
Methods, and References)
- More on
Reference
- Extended Example (
Object and
SignatureProperty)
- Extended Example
(
Object and Manifest)
-
Processing Rules
- Signature
Generation
- Signature
Validation
-
Core Signature
Syntax
- The
Signature element
- The
SignatureValue Element
-
The
SignedInfo Element
- The
CanonicalizationMethod
Element
- The
SignatureMethod Element
-
The
Reference Element
- The
URI Attribute
- The Reference Processing Model
- Same-Document URI-References
- The
Transforms Element
- The
DigestMethod Element
- The
DigestValue Element
-
The
KeyInfo Element
- The
KeyName Element
-
The
KeyValue Element
- The
DSAKeyValue Element
- The
RSAKeyValue Element
- The
RetrievalMethod Element
-
The
X509Data Element
- Distinguished Name Encoding Rules
- The
PGPData Element
- The
SPKIData Element
- The
MgmtData Element
- The
Object Element
-
Additional
Signature Syntax
- The
Manifest Element
- The
SignatureProperties Element
- Processing
Instructions
- Comments in dsig
Elements
-
Algorithms
- Algorithm Identifiers
and Implementation Requirements
- Message
Digests
- Message Authentication
Codes
- Signature
Algorithms
-
Canonicalization
Algorithms
- Canonical XML
1.0
- Canonical
XML 1.1
-
Transform
Algorithms
- Canonicalization
- Base64
- XPath
Filtering
- Enveloped Signature Transform
- XSLT
Transform
-
XML
Canonicalization and Syntax Constraint Considerations
- XML 1.0, Syntax
Constraints, and Canonicalization
- DOM/SAX Processing
and Canonicalization
- Namespace
Context and Portable Signatures
-
Security
Considerations
-
Transforms
- Only What is
Signed is Secure
- Only What is
"Seen" Should be Signed
- "See" What is
Signed
- Check the Security
Model
- Algorithms, Key
Lengths, Etc.
- Schema, DTD, Data Model,
and Valid Examples
- Definitions
- References
- Authors'
Address
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 Security Considerations (section
8).
1.1 Editorial and Conformance Conventions
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 Check the Security Model, section 8.3.)
This specification provides an XML Schema [XML-schema] and DTD [XML]. The schema definition is
normative.
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 [KEYWORDS]:
"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-ns] is described as "REQUIRED."
1.2 Design Philosophy
The design philosophy and requirements of this specification
are addressed in the XML-Signature Requirements document
[XML-Signature-RD].
1.3 Versions, Namespaces and Identifiers
No provision is made for an explicit version number in this
syntax. If a future version is needed, it will use a different
namespace. The XML namespace [XML-ns] URI that MUST be used by implementations of
this (dated) specification is:
xmlns="http://www.w3.org/2000/09/xmldsig#"
This namespace is also used as the prefix for algorithm
identifiers used by this specification. While applications MUST
support XML and XML namespaces, the use of internal entities [XML] or our "dsig" XML namespace prefix and defaulting/scoping
conventions are OPTIONAL; we use these facilities to provide
compact and readable examples.
This specification uses Uniform Resource Identifiers
[URI] to identify resources,
algorithms, and semantics. The URI in the namespace declaration
above is also used as a prefix for URIs under the control of this
specification. For resources not under the control of this
specification, we use the designated Uniform Resource Names
[URN] or Uniform Resource
Locators [URL] defined by its
normative external specification. If an external specification
has not allocated itself a Uniform Resource Identifier we
allocate an identifier under our own namespace. For instance:
SignatureProperties is identified and defined
by this specification's namespace- http://www.w3.org/2000/09/xmldsig#SignatureProperties
- XSLT is identified and
defined by an external URI
- http://www.w3.org/TR/1999/REC-xslt-19991116
- SHA1 is identified via this specification's namespace and
defined via a normative reference
- http://www.w3.org/2000/09/xmldsig#sha1
- FIPS PUB 180-2. Secure Hash Standard. U.S.
Department of Commerce/National Institute of Standards and
Technology.
Finally, in order to provide for terse namespace declarations
we sometimes use XML
internal entities [XML]
within URIs. For instance:
<?xml version='1.0'?>
<!DOCTYPE Signature SYSTEM
"xmldsig-core-schema.dtd" [ <!ENTITY dsig
"http://www.w3.org/2000/09/xmldsig#"> ]>
<Signature xmlns="&dsig;" Id="MyFirstSignature">
<SignedInfo>
...
The contributions of the following Working Group members to
this 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 Last Call comments from the following:
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, A-SIT
- 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
This section provides an overview and examples of XML digital
signature syntax. The specific processing is given in Processing Rules (section 3). The formal syntax
is found in Core Signature
Syntax (section 4) and Additional Signature Syntax (section 5).
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):
<Signature ID?>
<SignedInfo>
<CanonicalizationMethod/>
<SignatureMethod/>
(<Reference URI? >
(<Transforms>)?
<DigestMethod>
<DigestValue>
</Reference>)+
</SignedInfo>
<SignatureValue>
(<KeyInfo>)?
(<Object ID?>)*
</Signature>
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 [XML].
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.
[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/2000/09/xmldsig#dsa-sha1"/>
[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] <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
[s10] <DigestValue>dGhpcyBpcyBub3QgYSBzaWduYXR1cmUK.../DigestValue>
[s11] </Reference>
[s12] </SignedInfo>
[s13] <SignatureValue>...</SignatureValue>
[s14] <KeyInfo>
[s15a] <KeyValue>
[s15b] <DSAKeyValue>
[s15c] <P>...</P><Q>...</Q><G>...</G><Y>...</Y>
[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, and all examples
in this specification, are not 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.
[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] <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
[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 a resources content to the
signer's key.
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 [XML, RDF]. 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].)
[ ] <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] <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
[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] <date>19990914</date>
[p18] <time>14:34:34:34</time>
[p19] </timestamp>
[p20] </SignatureProperty>
[p21] </SignatureProperties>
[p22] </Object>
[p23]</Signature>
[p04] The optional Type attribute of
Reference provides information about the resource
identified by the URI. In particular, it can
indicate that it is an Object,
SignatureProperty, or Manifest element.
This can be used by applications to initiate special processing
of some Reference elements. References to an XML
data element within an Object element SHOULD
identify the actual element pointed to. Where the element content
is not XML (perhaps it is binary or encoded data) the reference
should identify the Object and the
Reference Type, if given, SHOULD
indicate Object. Note that Type is
advisory and no action based on it or checking of its correctness
is required by core behavior.
[p13] Object is an optional element
for including data objects within the signature element or
elsewhere. The Object can be optionally typed and/or
encoded.
[p14-21] Signature properties, such as time of
signing, can be optionally signed by identifying them from within
a Reference. (These properties are traditionally
called signature "attributes" although that term has no
relationship to the XML term "attribute".)
2.3 Extended Example (Object and Manifest)
The Manifest element is provided to meet
additional requirements not directly addressed by the mandatory
parts of this specification. Two requirements and the way the
Manifest satisfies them follow.
First, applications frequently need to efficiently sign
multiple data objects even where the signature operation itself
is an expensive public key signature. This requirement can be met
by including multiple Reference elements within
SignedInfo since the inclusion of each digest
secures the data digested. However, some applications may not
want the core validation behavior associated with this approach
because it requires every Reference within
SignedInfo to undergo reference validation -- the DigestValue
elements are checked. These applications may wish to reserve
reference validation decision logic to themselves. For example,
an application might receive a signature valid
SignedInfo element that includes three
Reference elements. If a single
Reference fails (the identified data object when
digested does not yield the specified DigestValue)
the signature would fail core validation. However, the
application may wish to treat the signature over the two valid
Reference elements as valid or take different
actions depending on which fails. To accomplish this,
SignedInfo would reference a Manifest
element that contains one or more Reference elements
(with the same structure as those in SignedInfo).
Then, reference validation of the Manifest is under
application control.
Second, consider an application where many signatures (using
different keys) are applied to a large number of documents. An
inefficient solution is to have a separate signature (per key)
repeatedly applied to a large SignedInfo element
(with many References); this is wasteful and
redundant. A more efficient solution is to include many
references in a single Manifest that is then
referenced from multiple Signature elements.
The example below includes a Reference that signs
a Manifest found within the Object
element.
[ ] ...
[m01] <Reference URI="#MyFirstManifest"
[m02] Type="http://www.w3.org/2000/09/xmldsig#Manifest">
[m03] <Transforms>
[m04] <Transform Algorithm="http://www.w3.org/2006/12/xml-c14n11"/>
[m05] </Transforms>
[m06] <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
[m07] <DigestValue>dGhpcyBpcyBub3QgYSBzaWduYXR1cmUK...=</DigestValue>
[m08] </Reference>
[ ] ...
[m09] <Object>
[m10] <Manifest Id="MyFirstManifest">
[m11] <Reference>
[m12] ...
[m13] </Reference>
[m14] <Reference>
[m15] ...
[m16] </Reference>
[m17] </Manifest>
[m18] </Object>
The sections below describe the operations to be performed as
part of signature generation and validation.
The REQUIRED steps include the generation of
Reference elements and the
SignatureValue over SignedInfo.
For each data object being signed:
- Apply the
Transforms, as determined by the
application, to the data object.
- Calculate the digest value over the resulting data
object.
- Create a
Reference element, including the
(optional) identification of the data object, any (optional)
transform elements, the digest algorithm and the
DigestValue. (Note, it is the canonical form of
these references that are signed in 3.1.2 and validated in
3.2.1 .)
The Reference Processing Model (section 4.3.3.2) requires
use of Canonical XML 1.0 [XML-C14N] as default processing behavior when a
transformation is expecting an octet-stream, but the data object
resulting from URI dereferencing or from the previous
transformation in the list of Transform elements is
a node-set. We RECOMMEND that, when generating signatures,
signature applications do not rely on this default behavior, but
explicitly identify the transformation that is applied to perform
this mapping. In cases in which inclusive canonicalization is
desired, we RECOMMEND that Canonical XML 1.1 [XML-C14N11] be used.
- Create
SignedInfo element with
SignatureMethod,
CanonicalizationMethod and
Reference(s).
- Canonicalize and then calculate the
SignatureValue over SignedInfo based
on algorithms specified in SignedInfo.
- Construct the
Signature element that includes
SignedInfo, Object(s) (if desired,
encoding may be different than that used for signing),
KeyInfo (if required), and
SignatureValue.
Note, if the Signature includes same-document
references, [XML] or
[XML-schema]
validation of the document might introduce changes that break
the signature. Consequently, applications should be careful
to consistently process the document or refrain from using
external contributions (e.g., defaults and entities).
The REQUIRED steps of core validation include (1) reference validation, the verification of the digest
contained in each Reference in
SignedInfo, and (2) the cryptographic signature validation of the signature calculated over
SignedInfo.
Note, there may be valid signatures that some signature
applications are unable to validate. Reasons for this include
failure to implement optional parts of this specification,
inability or unwillingness to execute specified algorithms, or
inability or unwillingness to dereference specified URIs (some
URI schemes may cause undesirable side effects), etc.
Comparison of values in reference and signature validation are
over the numeric (e.g., integer) or decoded octet sequence of the
value. Different implementations may produce different encoded
digest and signature values when processing the same resources
because of variances in their encoding, such as accidental white
space. But if one uses numeric or octet comparison (choose one)
on both the stated and computed values these problems are
eliminated.
- Canonicalize the
SignedInfo element based on
the CanonicalizationMethod in
SignedInfo.
- For each
Reference in SignedInfo:
- Obtain the data object to be digested. (For example,
the signature application may dereference the
URI and execute Transforms
provided by the signer in the Reference
element, or it may obtain the content through other means
such as a local cache.)
- Digest the resulting data object using the
DigestMethod specified in its
Reference specification.
- Compare the generated digest value against
DigestValue in the SignedInfo
Reference; if there is any mismatch,
validation fails.
Note, SignedInfo is canonicalized in step 1. The
application must ensure that the CanonicalizationMethod has no
dangerous side affects, such as rewriting URIs, (see
CanonicalizationMethod (section 4.3)) and that
it Sees What is Signed, which
is the canonical form.
- Obtain the keying information from
KeyInfo or from an
external source.
- Obtain the canonical form of the
SignatureMethod using the
CanonicalizationMethod and use the result
(and previously obtained KeyInfo) to confirm the
SignatureValue over the SignedInfo
element.
Note, KeyInfo (or some transformed version thereof)
may be signed via a Reference element.
Transformation and validation of this reference (3.2.1) is
orthogonal to Signature Validation which uses the
KeyInfo as parsed.
Additionally, the SignatureMethod URI may have
been altered by the canonicalization of SignedInfo
(e.g., absolutization of relative URIs) and it is the canonical
form that MUST be used. However, the required canonicalization
[XML-C14N] of this
specification does not change URIs.
The general structure of an XML signature is described in
Signature Overview
(section 2). This section provides detailed syntax of the core
signature features. Features described in this section are
mandatory to implement unless otherwise indicated. The syntax is
defined via DTDs and [XML-Schema] with the following XML preamble,
declaration, and internal entity.
Schema Definition:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE schema
PUBLIC "-//W3C//DTD XMLSchema 200102//EN" "http://www.w3.org/2001/XMLSchema.dtd"
[
<!ATTLIST schema
xmlns:ds CDATA #FIXED "http://www.w3.org/2000/09/xmldsig#">
<!ENTITY dsig 'http://www.w3.org/2000/09/xmldsig#'>
<!ENTITY % p ''>
<!ENTITY % s ''>
]>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
targetNamespace="http://www.w3.org/2000/09/xmldsig#"
version="0.1" elementFormDefault="qualified">
DTD:
<!--
The following entity declarations enable external/flexible content in
the Signature content model.
#PCDATA emulates schema:string; when combined with element types it
emulates schema mixed="true".
%foo.ANY permits the user to include their own element types from
other namespaces, for example:
<!ENTITY % KeyValue.ANY '| ecds:ECDSAKeyValue'>
...
<!ELEMENT ecds:ECDSAKeyValue (#PCDATA) >
-->
<!ENTITY % Object.ANY ''>
<!ENTITY % Method.ANY ''>
<!ENTITY % Transform.ANY ''>
<!ENTITY % SignatureProperty.ANY ''>
<!ENTITY % KeyInfo.ANY ''>
<!ENTITY % KeyValue.ANY ''>
<!ENTITY % PGPData.ANY ''>
<!ENTITY % X509Data.ANY ''>
<!ENTITY % SPKIData.ANY ''>
4.0.1 The ds:CryptoBinary Simple Type
This specification defines the ds:CryptoBinary
simple type for representing arbitrary-length integers (e.g.
"bignums") in XML as octet strings. The integer value is first
converted to a "big endian" bitstring. The bitstring is then
padded with leading zero bits so that the total number of bits ==
0 mod 8 (so that there are an integral number of octets). If the
bitstring contains entire leading octets that are zero, these are
removed (so the high-order octet is always non-zero). This octet
string is then base64 [MIME]
encoded. (The conversion from integer to octet string is
equivalent to IEEE 1363's I2OSP [1363] with minimal length).
This type is used by "bignum" values such as
RSAKeyValue and DSAKeyValue. If a value
can be of type base64Binary or
ds:CryptoBinary they are defined as base64Binary. For example, if the
signature algorithm is RSA or DSA then
SignatureValue represents a bignum and could be
ds:CryptoBinary. However, if HMAC-SHA1 is the
signature algorithm then SignatureValue could have
leading zero octets that must be preserved. Thus
SignatureValue is generically defined as of type
base64Binary.
Schema Definition:
<simpleType name="CryptoBinary">
<restriction base="base64Binary">
</restriction>
</simpleType>
The Signature element is the root element of an
XML Signature. Implementation MUST generate laxly schema valid [XML-schema] Signature elements as
specified by the following schema:
Schema Definition:
<element name="Signature" type="ds:SignatureType"/>
<complexType name="SignatureType">
<sequence>
<element ref="ds:SignedInfo"/>
<element ref="ds:SignatureValue"/>
<element ref="ds:KeyInfo" minOccurs="0"/>
<element ref="ds:Object" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
<attribute name="Id" type="ID" use="optional"/>
</complexType>
DTD:
<!ELEMENT Signature (SignedInfo, SignatureValue, KeyInfo?, Object*) >
<!ATTLIST Signature
xmlns CDATA #FIXED 'http://www.w3.org/2000/09/xmldsig#'
Id ID #IMPLIED >
The SignatureValue element contains the actual
value of the digital signature; it is always encoded using base64
[MIME]. While we identify
two SignatureMethod algorithms, one mandatory and
one optional to implement, user specified algorithms may be used
as well.
Schema Definition:
<element name="SignatureValue" type="ds:SignatureValueType"/>
<complexType name="SignatureValueType">
<simpleContent>
<extension base="base64Binary">
<attribute name="Id" type="ID" use="optional"/>
</extension>
</simpleContent>
</complexType>
DTD:
<!ELEMENT SignatureValue (#PCDATA) >
<!ATTLIST SignatureValue
Id ID #IMPLIED>
The structure of SignedInfo includes the
canonicalization algorithm, a signature algorithm, and one or
more references. The SignedInfo element may contain
an optional ID attribute that will allow it to be referenced by
other signatures and objects.
SignedInfo does not include explicit signature or
digest properties (such as calculation time, cryptographic device
serial number, etc.). If an application needs to associate
properties with the signature or digest, it may include such
information in a SignatureProperties element within
an Object element.
Schema Definition:
<element name="SignedInfo" type="ds:SignedInfoType"/>
<complexType name="SignedInfoType">
<sequence>
<element ref="ds:CanonicalizationMethod"/>
<element ref="ds:SignatureMethod"/>
<element ref="ds:Reference" maxOccurs="unbounded"/>
</sequence>
<attribute name="Id" type="ID" use="optional"/>
</complexType>
DTD:
<!ELEMENT SignedInfo (CanonicalizationMethod,
SignatureMethod, Reference+) >
<!ATTLIST SignedInfo
Id ID #IMPLIED
CanonicalizationMethod is a required element that
specifies the canonicalization algorithm applied to the
SignedInfo element prior to performing signature
calculations. This element uses the general structure for
algorithms described in Algorithm Identifiers and Implementation Requirements
(section 6.1). Implementations MUST support the REQUIRED canonicalization algorithms.
Alternatives to the REQUIRED canonicalization algorithms (section 6.5), such as
Canonical XML with
Comments (section 6.5.1) or a minimal canonicalization (such
as CRLF and charset normalization), may be explicitly specified
but are NOT REQUIRED. Consequently, their use may not
interoperate with other applications that do not support the
specified algorithm (see XML Canonicalization and Syntax Constraint
Considerations, section 7). Security issues may also arise in
the treatment of entity processing and comments if non-XML aware
canonicalization algorithms are not properly constrained (see
section 8.2: Only What is "Seen"
Should be Signed).
The way in which the SignedInfo element is
presented to the canonicalization method is dependent on that
method. The following applies to algorithms which process XML as
nodes or characters:
- XML based canonicalization implementations MUST be provided
with a [XPath] node-set
originally formed from the document containing the
SignedInfo and currently indicating the
SignedInfo, its descendants, and the attribute and
namespace nodes of SignedInfo and its descendant
elements.
- Text based canonicalization algorithms (such as CRLF and
charset normalization) should be provided with the UTF-8 octets
that represent the well-formed SignedInfo element, from the
first character to the last character of the XML
representation, inclusive. This includes the entire text of the
start and end tags of the SignedInfo element as well as all
descendant markup and character data (i.e., the text) between those tags. Use of text based
canonicalization of SignedInfo is NOT RECOMMENDED.
We recommend applications that implement a text-based instead
of XML-based canonicalization -- such as resource constrained
apps -- generate canonicalized XML as their output serialization
so as to mitigate interoperability and security concerns. For
instance, such an implementation SHOULD (at least) generate
standalone XML instances [XML].
NOTE: The
signature application must exercise great care in accepting and
executing an arbitrary CanonicalizationMethod. For
example, the canonicalization method could rewrite the URIs of
the References being validated. Or, the method could
massively transform SignedInfo so that validation
would always succeed (i.e., converting it to a trivial signature
with a known key over trivial data). Since
CanonicalizationMethod is inside
SignedInfo, in the resulting canonical form it could
erase itself from SignedInfo or modify the
SignedInfo element so that it appears that a
different canonicalization function was used! Thus a
Signature which appears to authenticate the desired
data with the desired key, DigestMethod, and
SignatureMethod, can be meaningless if a capricious
CanonicalizationMethod is used.
Schema Definition:
<element name="CanonicalizationMethod" type="ds:CanonicalizationMethodType"/>
<complexType name="CanonicalizationMethodType" mixed="true">
<sequence>
<any namespace="##any" minOccurs="0" maxOccurs="unbounded"/>
<!-- (0,unbounded) elements from (1,1) namespace -->
</sequence>
<attribute name="Algorithm" type="anyURI" use="required"/>
</complexType>
DTD:
<!ELEMENT CanonicalizationMethod (#PCDATA %Method.ANY;)* >
<!ATTLIST CanonicalizationMethod
Algorithm CDATA #REQUIRED >
SignatureMethod is a required element that
specifies the algorithm used for signature generation and
validation. This algorithm identifies all cryptographic functions
involved in the signature operation (e.g. hashing, public key
algorithms, MACs, padding, etc.). This element uses the general
structure here for algorithms described in section 6.1: Algorithm Identifiers and
Implementation Requirements. While there is a single
identifier, that identifier may specify a format containing
multiple distinct signature values.
Schema Definition:
<element name="SignatureMethod" type="ds:SignatureMethodType"/>
<complexType name="SignatureMethodType" mixed="true">
<sequence>
<element name="HMACOutputLength" minOccurs="0" type="ds:HMACOutputLengthType"/>
<any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
<!-- (0,unbounded) elements from (1,1) external namespace -->
</sequence>
<attribute name="Algorithm" type="anyURI" use="required"/>
</complexType>
DTD:
<!ELEMENT SignatureMethod (#PCDATA|HMACOutputLength %Method.ANY;)* >
<!ATTLIST SignatureMethod
Algorithm CDATA #REQUIRED >
Reference is an element that may occur one or
more times. It specifies a digest algorithm and digest value, and
optionally an identifier of the object being signed, the type of
the object, and/or a list of transforms to be applied prior to
digesting. The identification (URI) and transforms describe how
the digested content (i.e., the input to the digest method) was
created. The Type attribute facilitates the
processing of referenced data. For example, while this
specification makes no requirements over external data, an
application may wish to signal that the referent is a
Manifest. An optional ID attribute permits a
Reference to be referenced from elsewhere.
Schema Definition:
<element name="Reference" type="ds:ReferenceType"/>
<complexType name="ReferenceType">
<sequence>
<element ref="ds:Transforms" minOccurs="0"/>
<element ref="ds:DigestMethod"/>
<element ref="ds:DigestValue"/>
</sequence>
<attribute name="Id" type="ID" use="optional"/>
<attribute name="URI" type="anyURI" use="optional"/>
<attribute name="Type" type="anyURI" use="optional"/>
</complexType>
DTD:
<!ELEMENT Reference (Transforms?, DigestMethod, DigestValue) >
<!ATTLIST Reference
Id ID #IMPLIED
URI CDATA #IMPLIED
Type CDATA #IMPLIED>
4.3.3.1 The URI Attribute
The URI attribute identifies a data object using
a URI-Reference [URI].
The mapping from this attribute's value to a URI reference
MUST be performed as specified in section 3.2.17 of [XMLSCHEMA Datatypes, 2nd
Edition]. Additionally: Some existing implementations are
known to verify the value of the URI attribute against the
grammar in [URI]. It is
therefore safest to perform any necessary escaping while
generating the URI attribute.
We RECOMMEND XML signature applications be able to dereference
URIs in the HTTP scheme. Dereferencing a URI in the HTTP scheme
MUST comply with the Status Code Definitions of [HTTP] (e.g., 302, 305 and 307 redirects are
followed to obtain the entity-body of a 200 status code
response). Applications should also be cognizant of the fact that
protocol parameter and state information, (such as HTTP cookies,
HTML device profiles or content negotiation), may affect the
content yielded by dereferencing a URI.
If a resource is identified by more than one URI, the most
specific should be used (e.g.
http://www.w3.org/2000/06/interop-pressrelease.html.en instead of
http://www.w3.org/2000/06/interop-pressrelease). (See the
Reference
Validation (section 3.2.1) for a further information on
reference processing.)
If the URI attribute is omitted altogether, the
receiving application is expected to know the identity of the
object. For example, a lightweight data protocol might omit this
attribute given the identity of the object is part of the
application context. This attribute may be omitted from at most
one Reference in any particular
SignedInfo, or Manifest.
The optional Type attribute contains information about the
type of object being signed after all ds:Reference
transforms have been applied. This is represented as a URI. For
example:
Type="http://www.w3.org/2000/09/xmldsig#Object"
Type="http://www.w3.org/2000/09/xmldsig#Manifest"
The Type attribute applies to the item being pointed at, not
its contents. For example, a reference that results in the
digesting of an Object element containing a
SignatureProperties element is still of type
#Object. The type attribute is advisory. No
validation of the type information is required by this
specification.
The data-type of the result of URI dereferencing or subsequent
Transforms is either an octet stream or an XPath node-set.
The Transforms specified in this document are
defined with respect to the input they require. The following is
the default signature application behavior:
- If the data object is an octet stream and the next
transform requires a node-set, the signature application MUST
attempt to parse the octets yielding the required node-set via
[XML] well-formed
processing.
- If the data object is a node-set and the next transform
requires octets, the signature application MUST attempt to
convert the node-set to an octet stream using Canonical XML
[XML-C14N].
Users may specify alternative transforms that override these
defaults in transitions between transforms that expect different
inputs. The final octet stream contains the data octets being
secured. The digest algorithm specified by
DigestMethod is then applied to these data octets,
resulting in the DigestValue.
Note: The Reference Generation Model (section 3.1.1)
includes further restrictions on the reliance upon defined
default transformations when applications generate
signatures.
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 [URI].
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. (See Transforms (section 4.3.3.1).)
When a fragment is preceded by an absolute or relative URI in
the URI-Reference, the meaning of the fragment is defined by the
resource's MIME type. Even for XML documents, URI dereferencing
(including the fragment processing) might be done for the
signature application by a proxy. Therefore, reference validation
might fail if fragment processing is not performed in a standard
way (as defined in the following section for same-document
references). Consequently, we RECOMMEND in this case that the
URI attribute not include fragment identifiers
and that such processing be specified as an additional XPath Transform.
When a fragment is not preceded by a URI in the URI-Reference,
XML Signature applications MUST support the null URI and
shortname XPointer [XPointer-Framework]. We RECOMMEND support for the
same-document XPointers '#xpointer(/)' and
'#xpointer(id('ID'))' if the application also
intends to support any canonicalization that preserves comments. (Otherwise
URI="#foo" will automatically remove comments before
the canonicalization can even be invoked due to the processing
defined in Same-Document URI-References (section 4.3.3.3).) All
other support for XPointers is OPTIONAL, especially all support
for shortname and other XPointers in external resources since the
application may not have control over how the fragment is
generated (leading to interoperability problems and validation
failures).
'#xpointer(/)' MUST be interpreted to identify
the root node [XPath] of
the document that contains the URI attribute.
'#xpointer(id('ID'))' MUST be
interpreted to identify the element node identified by
'#element(ID)' [XPointer-Element] when
evaluated with respect to the document that contains the
URI attribute.
The original edition of this specification [XMLDSIG-2002] referenced the
XPointer Candidate Recommendation [XPTR-2001] and some implementations support it
optionally. That Candidate Recommendation has been superseded by
the [XPointer-Framework], [XPointer-xmlns] and [XPointer-Element]
Recommendations, and -- at the time of this edition -- the
[XPointer-xpointer] Working Draft. Therefore, the use
of the xpointer() scheme [XPointer-xpointer]
beyond the usage discussed in this section is discouraged.
The following examples demonstrate what the URI attribute
identifies and how it is dereferenced:
URI="http://example.com/bar.xml"- Identifies the octets that represent the external resource
'http://example.com/bar.xml', that is probably an XML document
given its file extension.
URI="http://example.com/bar.xml#chapter1"- Identifies the element with ID attribute value 'chapter1'
of the external XML resource 'http://example.com/bar.xml',
provided as an octet stream. Again, for the sake of
interoperability, the element identified as 'chapter1' should
be obtained using an XPath transform rather than a URI fragment
(shortname XPointer resolution in external resources is not
REQUIRED in this specification).
URI=""- Identifies the node-set (minus any comment nodes) of the
XML resource containing the signature
URI="#chapter1"- Identifies a node-set containing the element with ID
attribute value 'chapter1' of the XML resource containing the
signature. XML Signature (and its applications) modify this
node-set to include the element plus all descendants including
namespaces and attributes -- but not comments.
Dereferencing a same-document reference MUST result in an
XPath node-set suitable for use by Canonical XML [XML-C14N]. Specifically,
dereferencing a null URI (URI="") MUST result in an
XPath node-set that includes every non-comment node of the XML
document containing the URI attribute. In a fragment
URI, the characters after the number sign ('#') character conform
to the XPointer syntax [XPointer-Framework]. When processing an XPointer, the
application MUST behave as if the XPointer was evaluated with
respect to the XML document containing the URI
attribute . The application MUST behave as if the result of
XPointer processing [XPointer-Framework] were a node-set derived from the
resultant subresource as follows:
- include XPath nodes having full or partial content within
the subresource
- replace the root node with its children (if it is in the
node-set)
- replace any element node E with
E plus all descendants of E
(text, comment, PI, element) and all namespace and attribute
nodes of E and its descendant elements.
- if the URI has no fragment identifier or the fragment
identifier is a shortname XPointer, then delete all comment
nodes
The second to last replacement is necessary because XPointer
typically indicates a subtree of an XML document's parse tree
using just the element node at the root of the subtree, whereas
Canonical XML treats a node-set as a set of nodes in which
absence of descendant nodes results in absence of their
representative text from the canonical form.
The last step is performed for null URIs and shortname
XPointers . It is necessary because when [XML-C14N] or [XML-C14N11] is passed a node-set, it processes the
node-set as is: with or without comments. Only when it is called
with an octet stream does it invoke its own XPath expressions
(default or without comments). Therefore to retain the default
behavior of stripping comments when passed a node-set, they are
removed in the last step if the URI is not a scheme-based
XPointer. To retain comments while selecting an element by an
identifier ID, use the following scheme-based XPointer:
URI='#xpointer(id('ID'))'. To retain
comments while selecting the entire document, use the following
scheme-based XPointer: URI='#xpointer(/)'.
The interpretation of these XPointers is defined in The Reference
Processing Model (section 4.3.3.2).
The optional Transforms element contains an
ordered list of Transform elements; these describe
how the signer obtained the data object that was digested. The
output of each Transform serves as input to the next
Transform. The input to the first
Transform is the result of dereferencing the
URI attribute of the Reference element.
The output from the last Transform is the input for
the DigestMethod algorithm. When transforms are
applied the signer is not signing the native (original) document
but the resulting (transformed) document. (See Only What is Signed is Secure
(section 8.1).)
Each Transform consists of an
Algorithm attribute and content parameters, if any,
appropriate for the given algorithm. The Algorithm
attribute value specifies the name of the algorithm to be
performed, and the Transform content provides
additional data to govern the algorithm's processing of the
transform input. (See Algorithm
Identifiers and Implementation Requirements (section 6).)
As described in The Reference Processing Model (section
4.3.3.2), some transforms take an XPath node-set as input, while
others require an octet stream. If the actual input matches the
input needs of the transform, then the transform operates on the
unaltered input. If the transform input requirement differs from
the format of the actual input, then the input must be
converted.
Some Transforms may require explicit MIME type,
charset (IANA registered "character set"), or other such
information concerning the data they are receiving from an
earlier Transform or the source data, although no
Transform algorithm specified in this document needs
such explicit information. Such data characteristics are provided
as parameters to the Transform algorithm and should
be described in the specification for the algorithm.
Examples of transforms include but are not limited to base64
decoding [MIME],
canonicalization [XML-C14N], XPath filtering [XPath], and XSLT [XSLT]. The generic definition of the
Transform element also allows application-specific
transform algorithms. For example, the transform could be a
decompression routine given by a Java class appearing as a base64
encoded parameter to a Java Transform algorithm.
However, applications should refrain from using
application-specific transforms if they wish their signatures to
be verifiable outside of their application domain. Transform Algorithms
(section 6.6) defines the list of standard transformations.
Schema Definition:
<element name="Transforms" type="ds:TransformsType"/>
<complexType name="TransformsType">
<sequence>
<element ref="ds:Transform" maxOccurs="unbounded"/>
</sequence>
</complexType>
<element name="Transform" type="ds:TransformType"/>
<complexType name="TransformType" mixed="true">
<choice minOccurs="0" maxOccurs="unbounded">
<any namespace="##other" processContents="lax"/>
<!-- (1,1) elements from (0,unbounded) namespaces -->
<element name="XPath" type="string"/>
</choice>
<attribute name="Algorithm" type="anyURI" use="required"/>
</complexType>
DTD:
<!ELEMENT Transforms (Transform+)>
<!ELEMENT Transform (#PCDATA|XPath %Transform.ANY;)* >
<!ATTLIST Transform
Algorithm CDATA #REQUIRED >
<!ELEMENT XPath (#PCDATA) >
DigestMethod is a required element that
identifies the digest algorithm to be applied to the signed
object. This element uses the general structure here for
algorithms specified in Algorithm Identifiers and Implementation Requirements
(section 6.1).
If the result of the URI dereference and application of
Transforms is an XPath node-set (or sufficiently functional
replacement implemented by the application) then it must be
converted as described in the Reference Processing Model (section
4.3.3.2). If the result of URI dereference and application of
transforms is an octet stream, then no conversion occurs
(comments might be present if the Canonical XML with Comments was
specified in the Transforms). The digest algorithm is applied to
the data octets of the resulting octet stream.
Schema Definition:
<element name="DigestMethod" type="ds:DigestMethodType"/>
<complexType name="DigestMethodType" mixed="true">
<sequence>
<any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
<attribute name="Algorithm" type="anyURI" use="required"/>
</complexType>
DTD:
<!ELEMENT DigestMethod (#PCDATA %Method.ANY;)* >
<!ATTLIST DigestMethod
Algorithm CDATA #REQUIRED >
DigestValue is an element that contains the encoded value of
the digest. The digest is always encoded using base64 [MIME].
Schema Definition:
<element name="DigestValue" type="ds:DigestValueType"/>
<simpleType name="DigestValueType">
<restriction base="base64Binary"/>
</simpleType>
DTD:
<!ELEMENT DigestValue (#PCDATA) >
<!-- base64 encoded digest value -->
4.4 The KeyInfo Element
KeyInfo is an optional element that enables the
recipient(s) to obtain the key needed to validate the
signature. KeyInfo may contain keys, names,
certificates and other public key management information, such as
in-band key distribution or key agreement data. This
specification defines a few simple types but applications may
extend those types or all together replace them with their own
key identification and exchange semantics using the XML namespace
facility. [XML-ns]
However, questions of trust of such key information (e.g., its
authenticity or strength) are out of scope of this
specification and left to the application.
If KeyInfo is omitted, the recipient is expected
to be able to identify the key based on application context.
Multiple declarations within KeyInfo refer to the
same key. While applications may define and use any mechanism
they choose through inclusion of elements from a different
namespace, compliant versions MUST implement KeyValue (section
4.4.2) and SHOULD implement RetrievalMethod (section 4.4.3).
The schema/DTD specifications of many of
KeyInfo's children (e.g., PGPData,
SPKIData, X509Data) permit their
content to be extended/complemented with elements from another
namespace. This may be done only if it is safe to ignore these
extension elements while claiming support for the types defined
in this specification. Otherwise, external elements, including
alternative structures to those defined by this
specification, MUST be a child of KeyInfo. For
example, should a complete XML-PGP standard be defined, its root
element MUST be a child of KeyInfo. (Of course, new
structures from external namespaces can incorporate elements from
the &dsig; namespace via features of the type
definition language. For instance, they can create a DTD that
mixes their own and dsig qualified elements, or a schema that
permits, includes, imports, or derives new types based on
&dsig; elements.)
The following list summarizes the KeyInfo types
that are allocated an identifier in the &dsig;
namespace; these can be used within the
RetrievalMethod Type attribute to
describe a remote KeyInfo structure.
In addition to the types above for which we define an XML
structure, we specify one additional type to indicate a binary
(ASN.1 DER) X.509 Certificate.
Schema Definition:
<element name="KeyInfo" type="ds:KeyInfoType"/>
<complexType name="KeyInfoType" mixed="true">
<choice maxOccurs="unbounded">
<element ref="ds:KeyName"/>
<element ref="ds:KeyValue"/>
<element ref="ds:RetrievalMethod"/>
<element ref="ds:X509Data"/>
<element ref="ds:PGPData"/>
<element ref="ds:SPKIData"/>
<element ref="ds:MgmtData"/>
<any processContents="lax" namespace="##other"/>
<!-- (1,1) elements from (0,unbounded) namespaces -->
</choice>
<attribute name="Id" type="ID" use="optional"/>
</complexType>
DTD:
<!ELEMENT KeyInfo (#PCDATA|KeyName|KeyValue|RetrievalMethod|
X509Data|PGPData|SPKIData|MgmtData %KeyInfo.ANY;)* >
<!ATTLIST KeyInfo
Id ID #IMPLIED >
4.4.1 The KeyName Element
The KeyName element contains a string value (in
which white space is significant) which may be used by the signer
to communicate a key identifier to the recipient. Typically,
KeyName contains an identifier related to the key
pair used to sign the message, but it may contain other
protocol-related information that indirectly identifies a key
pair. (Common uses of KeyName include simple string
names for keys, a key index, a distinguished name (DN), an email
address, etc.)
Schema Definition:
<element name="KeyName" type="string"/>
DTD:
<!ELEMENT KeyName (#PCDATA) >
4.4.2 The KeyValue Element
The KeyValue element contains a single public key
that may be useful in validating the signature. Structured
formats for defining DSA (REQUIRED) and RSA (RECOMMENDED) public
keys are defined in Signature Algorithms (section 6.4). The
KeyValue element may include externally defined
public keys values represented as PCDATA or element types from an
external namespace.
Schema Definition:
<element name="KeyValue" type="ds:KeyValueType"/>
<complexType name="KeyValueType" mixed="true">
<choice>
<element ref="ds:DSAKeyValue"/>
<element ref="ds:RSAKeyValue"/>
<any namespace="##other" processContents="lax"/>
</choice>
</complexType>
DTD:
<!ELEMENT KeyValue (#PCDATA|DSAKeyValue|RSAKeyValue %KeyValue.ANY;)* >
- Identifier
Type="http://www.w3.org/2000/09/xmldsig#DSAKeyValue"
(this can be used within a RetrievalMethod
or Reference element to identify the referent's
type)
DSA keys and the DSA signature algorithm are specified in
[DSS]. DSA public key values can have the following fields:
P- a prime modulus meeting the [DSS] requirements
Q- an integer in the range 2**159 < Q < 2**160 which is
a prime divisor of P-1
G- an integer with certain properties with respect to P and
Q
Y- G**X mod P (where X is part of the private key and not made
public)
J- (P - 1) / Q
seed- a DSA prime generation seed
pgenCounter- a DSA prime generation counter
Parameter J is available for inclusion solely for efficiency
as it is calculatable from P and Q. Parameters seed and
pgenCounter are used in the DSA prime number generation algorithm
specified in [DSS]. As such, they are optional but must either
both be present or both be absent. This prime generation
algorithm is designed to provide assurance that a weak prime is
not being used and it yields a P and Q value. Parameters P, Q,
and G can be public and common to a group of users. They might be
known from application context. As such, they are optional but P
and Q must either both appear or both be absent. If all of
P, Q, seed, and
pgenCounter are present, implementations are not
required to check if they are consistent and are free to use
either P and Q or seed and
pgenCounter. All parameters are encoded as base64
[MIME] values.
Arbitrary-length integers (e.g. "bignums" such as RSA moduli)
are represented in XML as octet strings as defined by the
ds:CryptoBinary type.
Schema Definition:
<element name="DSAKeyValue" type="ds:DSAKeyValueType"/>
<complexType name="DSAKeyValueType">
<sequence>
<sequence minOccurs="0">
<element name="P" type="ds:CryptoBinary"/>
<element name="Q" type="ds:CryptoBinary"/>
</sequence>
<element name="G" type="ds:CryptoBinary" minOccurs="0"/>
<element name="Y" type="ds:CryptoBinary"/>
<element name="J" type="ds:CryptoBinary" minOccurs="0"/>
<sequence minOccurs="0">
<element name="Seed" type="ds:CryptoBinary"/>
<element name="PgenCounter" type="ds:CryptoBinary"/>
</sequence>
</sequence>
</complexType>
DTD Definition:
<!ELEMENT DSAKeyValue ((P, Q)?, G?, Y, J?, (Seed, PgenCounter)?) >
<!ELEMENT P (#PCDATA) >
<!ELEMENT Q (#PCDATA) >
<!ELEMENT G (#PCDATA) >
<!ELEMENT Y (#PCDATA) >
<!ELEMENT J (#PCDATA) >
<!ELEMENT Seed (#PCDATA) >
<!ELEMENT PgenCounter (#PCDATA) >
- Identifier
Type="http://www.w3.org/2000/09/xmldsig#RSAKeyValue"
(this can be used within a RetrievalMethod
or Reference element to identify the referent's
type)
RSA key values have two fields: Modulus and Exponent.
<RSAKeyValue>
<Modulus>xA7SEU+e0yQH5rm9kbCDN9o3aPIo7HbP7tX6WOocLZAtNfyxSZDU16ksL6W
jubafOqNEpcwR3RdFsT7bCqnXPBe5ELh5u4VEy19MzxkXRgrMvavzyBpVRgBUwUlV
5foK5hhmbktQhyNdy/6LpQRhDUDsTvK+g9Ucj47es9AQJ3U=
</Modulus>
<Exponent>AQAB</Exponent>
</RSAKeyValue>
Arbitrary-length integers (e.g. "bignums" such as RSA moduli)
are represented in XML as octet strings as defined by the
ds:CryptoBinary type.
Schema Definition:
<element name="RSAKeyValue" type="ds:RSAKeyValueType"/>
<complexType name="RSAKeyValueType">
<sequence>
<element name="Modulus" type="ds:CryptoBinary"/>
<element name="Exponent" type="ds:CryptoBinary"/>
</sequence>
</complexType>
DTD Definition:
<!ELEMENT RSAKeyValue (Modulus, Exponent) >
<!ELEMENT Modulus (#PCDATA) >
<!ELEMENT Exponent (#PCDATA) >
A RetrievalMethod element within
KeyInfo is used to convey a reference to
KeyInfo information that is stored at another
location. For example, several signatures in a document might use
a key verified by an X.509v3 certificate chain appearing once in
the document or remotely outside the document; each signature's
KeyInfo can reference this chain using a single
RetrievalMethod element instead of including the
entire chain with a sequence of X509Certificate
elements.
RetrievalMethod uses the same syntax and
dereferencing behavior as Reference's URI (section 4.3.3.1) and
The
Reference Processing Model (section 4.3.3.2) except that
there is no DigestMethod or DigestValue
child elements and presence of the URI is mandatory.
Type is an optional identifier for the type of
data retrieved after all transforms have been applied. The result
of dereferencing a RetrievalMethod Reference for all KeyInfo types defined by
this specification (section 4.4) with a corresponding XML
structure is an XML element or document with that element as the
root. The rawX509Certificate KeyInfo
(for which there is no XML structure) returns a binary X509
certificate.
Schema Definition
<element name="RetrievalMethod" type="ds:RetrievalMethodType"/>
<complexType name="RetrievalMethodType">
<sequence>
<element ref="ds:Transforms" minOccurs="0"/>
</sequence>
<attribute name="URI" type="anyURI"/>
<attribute name="Type" type="anyURI" use="optional"/>
</complexType>
DTD
<!ELEMENT RetrievalMethod (Transforms?) >
<!ATTLIST RetrievalMethod
URI CDATA #REQUIRED
Type CDATA #IMPLIED >
Note: The schema for the URI
attribute of RetrievalMethod erroneously omitted the attribute:
use="required"
The DTD is correct. However, this error only results in a more
lax schema which permits all valid RetrievalMethod elements.
Because the existing schema is embedded in many applications,
which may include the schema in their signatures, the schema has
not been corrected to be more restrictive.
4.4.4 The X509Data Element
- Identifier
Type="http://www.w3.org/2000/09/xmldsig#X509Data
"
(this can be used within a RetrievalMethod or
Reference element to identify the referent's
type)
An X509Data element within KeyInfo
contains one or more identifiers of keys or X509 certificates (or
certificates' identifiers or a revocation list). The content of
X509Data is:
- At least one element, from the following set of element
types; any of these may appear together or more than once iff
(if and only if) each instance describes or is related to the
same certificate:
-
- The
X509IssuerSerial element, which
contains an X.509 issuer distinguished name/serial number
pair. The distinguished name SHOULD be represented as a
string that complies with section 3 of RFC4514 [LDAP-DN], to be generated
according to the Distinguished Name Encoding Rules section
below,
- The
X509SubjectName element, which
contains an X.509 subject distinguished name that SHOULD be
represented as a string that complies with section 3 of
RFC4514 [LDAP-DN],
to be generated according to the Distinguished Name Encoding Rules section
below,
- The
X509SKI element, which contains the
base64 encoded plain (i.e. non-DER-encoded) value of a X509
V.3 SubjectKeyIdentifier extension.
- The
X509Certificate element, which
contains a base64-encoded [X509v3] certificate, and
- Elements from an external namespace which
accompanies/complements any of the elements above.
- The
X509CRL element, which contains a
base64-encoded certificate revocation list (CRL) [X509v3].
Any X509IssuerSerial, X509SKI, and
X509SubjectName elements that appear MUST refer to
the certificate or certificates containing the validation key.
All such elements that refer to a particular individual
certificate MUST be grouped inside a single X509Data
element and if the certificate to which they refer appears, it
MUST also be in that X509Data element.
Any X509IssuerSerial, X509SKI, and
X509SubjectName elements that relate to the same key
but different certificates MUST be grouped within a single
KeyInfo but MAY occur in multiple
X509Data elements.
All certificates appearing in an X509Data element
MUST relate to the validation key by either containing it or
being part of a certification chain that terminates in a
certificate containing the validation key.
No ordering is implied by the above constraints. The comments
in the following instance demonstrate these constraints:
<KeyInfo>
<X509Data> <!-- two pointers to certificate-A -->
<X509IssuerSerial>
<X509IssuerName>CN=TAMURA Kent, OU=TRL, O=IBM,
L=Yamato-shi, ST=Kanagawa, C=JP</X509IssuerName>
<X509SerialNumber>12345678</X509SerialNumber>
</X509IssuerSerial>
<X509SKI>31d97bd7</X509SKI>
</X509Data>
<X509Data><!-- single pointer to certificate-B -->
<X509SubjectName>Subject of Certificate B</X509SubjectName>
</X509Data>
<X509Data> <!-- certificate chain -->
<!--Signer cert, issuer CN=arbolCA,OU=FVT,O=IBM,C=US, serial 4-->
<X509Certificate>MIICXTCCA..</X509Certificate>
<!-- Intermediate cert subject CN=arbolCA,OU=FVT,O=IBM,C=US
issuer CN=tootiseCA,OU=FVT,O=Bridgepoint,C=US -->
<X509Certificate>MIICPzCCA...</X509Certificate>
<!-- Root cert subject CN=tootiseCA,OU=FVT,O=Bridgepoint,C=US -->
<X509Certificate>MIICSTCCA...</X509Certificate>
</X509Data>
</KeyInfo>
Note, there is no direct provision for a PKCS#7 encoded "bag"
of certificates or CRLs. However, a set of certificates and CRLs
can occur within an X509Data element and multiple
X509Data elements can occur in a
KeyInfo. Whenever multiple certificates occur in an
X509Data element, at least one such certificate must
contain the public key which verifies the signature.
To encode a distinguished name
(X509IssuerSerial,X509SubjectName, and
KeyName if appropriate), the encoding rules in
section 2 of RFC 4514 [LDAP-DN] SHOULD be applied, except that the character
escaping rules in section 2.4 of RFC 4514 [LDAP-DN] MAY be augmented as follows:
- Escape all occurrences of ASCII control characters (Unicode
range \x00 - \x1f) by replacing them with "\" followed by a two
digit hex number showing its Unicode number.
- Escape any trailing space characters (Unicode \x20) by
replacing them with "\20", instead of using the escape sequence
"\ ".
Since a XML document logically consists of characters, not
octets, the resulting Unicode string is finally encoded according
to the character encoding used for producing the physical
representation of the XML document.
Schema Definition
<element name="X509Data" type="ds:X509DataType"/>
<complexType name="X509DataType">
<sequence maxOccurs="unbounded">
<choice>
<element name="X509IssuerSerial" type="ds:X509IssuerSerialType"/>
<element name="X509SKI" type="base64Binary"/>
<element name="X509SubjectName" type="string"/>
<element name="X509Certificate" type="base64Binary"/>
<element name="X509CRL" type="base64Binary"/>
<any namespace="##other" processContents="lax"/>
</choice>
</sequence>
</complexType>
<complexType name="X509IssuerSerialType">
<sequence>
<element name="X509IssuerName" type="string"/>
<element name="X509SerialNumber" type="integer"/>
</sequence>
</complexType>
DTD
<!ELEMENT X509Data ((X509IssuerSerial | X509SKI | X509SubjectName |
X509Certificate | X509CRL)+ %X509.ANY;)>
<!ELEMENT X509IssuerSerial (X509IssuerName, X509SerialNumber) >
<!ELEMENT X509IssuerName (#PCDATA) >
<!ELEMENT X509SubjectName (#PCDATA) >
<!ELEMENT X509SerialNumber (#PCDATA) >
<!ELEMENT X509SKI (#PCDATA) >
<!ELEMENT X509Certificate (#PCDATA) >
<!ELEMENT X509CRL (#PCDATA) >
<!-- Note, this DTD and schema permit X509Data to be empty; this is
precluded by the text in KeyInfo Element (section 4.4) which states
that at least one element from the dsig namespace should be present
in the PGP, SPKI, and X509 structures. This is easily expressed for
the other key types, but not for X509Data because of its rich
structure. -->
4.4.5 The PGPData Element
- Identifier
Type="http://www.w3.org/2000/09/xmldsig#PGPData
"
(this can be used within a RetrievalMethod or
Reference element to identify the referent's
type)
The PGPData element within KeyInfo
is used to convey information related to PGP public key pairs and
signatures on such keys. The PGPKeyID's value is a
base64Binary sequence containing a standard PGP public key
identifier as defined in [PGP, section 11.2]. The PGPKeyPacket
contains a base64-encoded Key Material Packet as defined in
[PGP, section 5.5]. These
children element types can be complemented/extended by siblings
from an external namespace within PGPData, or
PGPData can be replaced all together with an
alternative PGP XML structure as a child of KeyInfo.
PGPData must contain one PGPKeyID
and/or one PGPKeyPacket and 0 or more elements from
an external namespace.
Schema Definition:
<element name="PGPData" type="ds:PGPDataType"/>
<complexType name="PGPDataType">
<choice>
<sequence>
<element name="PGPKeyID" type="base64Binary"/>
<element name="PGPKeyPacket" type="base64Binary" minOccurs="0"/>
<any namespace="##other" processContents="lax" minOccurs="0"
maxOccurs="unbounded"/>
</sequence>
<sequence>
<element name="PGPKeyPacket" type="base64Binary"/>
<any namespace="##other" processContents="lax" minOccurs="0"
maxOccurs="unbounded"/>
</sequence>
</choice>
</complexType>
DTD:
<!ELEMENT PGPData ((PGPKeyID, PGPKeyPacket?) | (PGPKeyPacket) %PGPData.ANY;) >
<!ELEMENT PGPKeyPacket (#PCDATA) >
<!ELEMENT PGPKeyID (#PCDATA) >
4.4.6 The SPKIData Element
- Identifier
Type="http://www.w3.org/2000/09/xmldsig#SPKIData
"
(this can be used within a RetrievalMethod or
Reference element to identify the referent's
type)
The SPKIData element within KeyInfo
is used to convey information related to SPKI public key pairs,
certificates and other SPKI data. SPKISexp is the
base64 encoding of a SPKI canonical S-expression.
SPKIData must have at least one
SPKISexp; SPKISexp can be
complemented/extended by siblings from an external namespace
within SPKIData, or SPKIData can be
entirely replaced with an alternative SPKI XML structure as a
child of KeyInfo.
Schema Definition:
<element name="SPKIData" type="ds:SPKIDataType"/>
<complexType name="SPKIDataType">
<sequence maxOccurs="unbounded">
<element name="SPKISexp" type="base64Binary"/>
<any namespace="##other" processContents="lax" minOccurs="0"/>
</sequence>
</complexType>
DTD:
<!ELEMENT SPKIData (SPKISexp %SPKIData.ANY;) >
<!ELEMENT SPKISexp (#PCDATA) >
4.4.7 The MgmtData Element
- Identifier
Type="http://www.w3.org/2000/09/xmldsig#MgmtData
"
(this can be used within a RetrievalMethod or
Reference element to identify the referent's
type)
The MgmtData element within KeyInfo
is a string value used to convey in-band key distribution or
agreement data. For example, DH key exchange, RSA key encryption,
etc. Use of this element is NOT RECOMMENDED. It provides a
syntactic hook where in-band key distribution or agreement data
can be placed. However, superior interoperable child elements of
KeyInfo for the transmission of encrypted keys and
for key agreement are being specified by the W3C XML Encryption
Working Group and they should be used instead of
MgmtData.
Schema Definition:
<element name="MgmtData" type="string"/>
DTD:
<!ELEMENT MgmtData (#PCDATA)>
4.5 The Object Element
- Identifier
Type="http://www.w3.org/2000/09/xmldsig#Object"
(this can be used within a
Reference element to identify the referent's
type)
Object is an optional element that may occur one
or more times. When present, this element may contain any data.
The Object element may include optional MIME type,
ID, and encoding attributes.
The Object's Encoding attributed may
be used to provide a URI that identifies the method by which the
object is encoded (e.g., a binary file).
The MimeType attribute is an optional attribute
which describes the data within the Object
(independent of its encoding). This is a string with values
defined by [MIME]. For
example, if the Object contains base64 encoded
PNG,
the Encoding may be specified as
'http://www.w3.org/2000/09/xmldsig#base64' and the
MimeType as 'image/png'. This attribute is purely
advisory; no validation of the MimeType information
is required by this specification. Applications which require
normative type and encoding information for signature validation
should specify Transforms with well defined resulting types
and/or encodings.
The Object's Id is commonly
referenced from a Reference in
SignedInfo, or Manifest. This element
is typically used for enveloping signatures where the
object being signed is to be included in the signature element.
The digest is calculated over the entire Object
element including start and end tags.
Note, if the application wishes to exclude the
<Object> tags from the digest calculation the
Reference must identify the actual data object (easy
for XML documents) or a transform must be used to remove the
Object tags (likely where the data object is
non-XML). Exclusion of the object tags may be desired for cases
where one wants the signature to remain valid if the data object
is moved from inside a signature to outside the signature (or
vice versa), or where the content of the Object is
an encoding of an original binary document and it is desired to
extract and decode so as to sign the original bitwise
representation.
Schema Definition:
<element name="Object" type="ds:ObjectType"/>
<complexType name="ObjectType" mixed="true">
<sequence minOccurs="0" maxOccurs="unbounded">
<any namespace="##any" processContents="lax"/>
</sequence>
<attribute name="Id" type="ID" use="optional"/>
<attribute name="MimeType" type="string" use="optional"/>
<attribute name="Encoding" type="anyURI" use="optional"/>
</complexType>
DTD:
<!ELEMENT Object (#PCDATA|Signature|SignatureProperties|Manifest %Object.ANY;)* >
<!ATTLIST Object
Id ID #IMPLIED
MimeType CDATA #IMPLIED
Encoding CDATA #IMPLIED >
This section describes the optional to implement
Manifest and SignatureProperties
elements and describes the handling of XML processing
instructions and comments. With respect to the elements
Manifest and SignatureProperties this
section specifies syntax and little behavior -- it is left to the
application. These elements can appear anywhere the parent's
content model permits; the Signature content model
only permits them within Object.
- Identifier
Type="http://www.w3.org/2000/09/xmldsig#Manifest"
(this can be used within a Reference
element to identify the referent's type)
The Manifest element provides a list of
References. The difference from the list in
SignedInfo is that it is application defined which,
if any, of the digests are actually checked against the objects
referenced and what to do if the object is inaccessible or the
digest compare fails. If a Manifest is pointed to
from SignedInfo, the digest over the
Manifest itself will be checked by the core
signature validation behavior. The digests within such a
Manifest are checked at the application's
discretion. If a Manifest is referenced from another
Manifest, even the overall digest of this two level
deep Manifest might not be checked.
Schema Definition:
<element name="Manifest" type="ds:ManifestType"/>
<complexType name="ManifestType">
<sequence>
<element ref="ds:Reference" maxOccurs="unbounded"/>
</sequence>
<attribute name="Id" type="ID" use="optional"/>
</complexType>
DTD:
<!ELEMENT Manifest (Reference+) >
<!ATTLIST Manifest
Id ID #IMPLIED >
-
- Identifier
Type="http://www.w3.org/2000/09/xmldsig#SignatureProperties"
(this can be used within a Reference
element to identify the referent's type)
Additional information items concerning the generation of the
signature(s) can be placed in a SignatureProperty
element (i.e., date/time stamp or the serial number of
cryptographic hardware used in signature generation).
Schema Definition:
<element name="SignatureProperties" type="ds:SignaturePropertiesType"/>
<complexType name="SignaturePropertiesType">
<sequence>
<element ref="ds:SignatureProperty" maxOcc