Copyright © 2013 The IETF Trust & W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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.
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/.
At the time of this publication, the most recent W3C Recommendation of XML Signature 1 is the 10 June 2008 XML Signature (Second Edition) Recommendation.
The most recent publication of this draft is the LC draft of 18 October 2012. Changes since that LC publication include the following:
Please review the differences between the previous Last Call Working Draft and this Proposed Recomendation , and the differences between the previous XML Signature Recommendation and this Proposed Recommendation; A detailed explanation of changes since the last Recommendation is also available [XMLDSIG-CORE1-CHGS].
The previous Last Call working draft followed Candidate Recommendation since a feature was removed due to lack of implementation, results of a PAG recommendation were included in the specification, additional algorithm identifiers were added based on review during implementation, and clarifications resulted from implementation experience. This Last Call resulted in an additional clarification, but with no objection to the changes resulting in Last Call.
Conformance-affecting changes 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.
This document was published by the XML Security Working Group as a Proposed Recommendation. This document is intended to become a W3C Recommendation. The W3C Membership and other interested parties are invited to review the document and send comments to public-xmlsec@w3.org (subscribe, archives) through 25 February 2013. Advisory Committee Representatives should consult their WBS questionnaires. Note that substantive technical comments were expected during the Last Call review period that ended 08 November 2012.
Please see the Working Group's implementation report.
Publication as a Proposed Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This 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.
ds:CryptoBinary
Simple TypeSignature
elementSignatureValue
ElementSignedInfo
ElementKeyInfo
ElementKeyName
ElementKeyValue
ElementRetrievalMethod
ElementX509Data
ElementPGPData
ElementSPKIData
ElementMgmtData
ElementEncryptedKey
and DerivedKey
ElementsDEREncodedKeyValue
ElementKeyInfoReference
ElementObject
Element
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.
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.
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].
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 |
---|---|---|
http://www.w3.org/2000/09/xmldsig# | default namespace,
ds: , dsig: | <!ENTITY dsig "http://www.w3.org/2000/09/xmldsig#"> |
http://www.w3.org/2009/xmldsig11# | dsig11: | <!ENTITY dsig11 "http://www.w3.org/2009/xmldsig11#"> |
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 http://www.w3.org/2000/09/xmldsig#
(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
http://www.w3.org/2009/xmldsig11#
(dsig11:
)
namespace
is used.
This specification uses algorithm identifiers in the namespace
http://www.w3.org/2001/04/xmldsig-more#
that were originally
coined in [RFC4051]. RFC 4051 associates these identifiers
with specific algorithms. Implementations of this specification
must be fully interoperable with the algorithms specified in
[RFC4051], 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:
namespacehttp://www.w3.org/2000/09/xmldsig#SignatureProperties
ECKeyValue
is identified and defined by the
dsig11:
namespacehttp://www.w3.org/2009/xmldsig11#ECKeyValue
http://www.w3.org/TR/1999/REC-xslt-19991116
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.
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:
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.
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):
<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 [XML10].
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/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] <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/> [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 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.
Reference
[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/2001/04/xmlenc#sha256"/> [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.
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]
.)
[ ] <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/2001/04/xmlenc#sha256"/> [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".)
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 Reference
s); 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/2001/04/xmlenc#sha256"/> [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:
Transforms
, as determined by the application, to
the data object.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
section 3.1.2 Signature Generation and
validated in
section 3.2.1 Reference Validation.)
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.
SignedInfo
element with
SignatureMethod
,
CanonicalizationMethod
and
Reference
(s).SignatureValue
over SignedInfo
based on algorithms
specified in SignedInfo
.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,
[XML10] or [XMLSCHEMA-1], [XMLSCHEMA-2]
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 each value in reference and signature validation is 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.
SignedInfo
element based on the
CanonicalizationMethod
in
SignedInfo
.Reference
in SignedInfo
:
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.)DigestMethod
specified in its
Reference
specification.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 effects,
such as rewriting URIs, (see
note on Canonicalization Method
) and that it
Sees What is Signed, which is the canonical form.
Note, After a Signature
element has been created in
Signature
Generation for a signature with a same document reference, an
implementation can serialize the XML content with variations in that
serialization. This means that Reference Validation needs to
canonicalize the XML document before digesting in step 1 to avoid
issues related to variations in serialization.
KeyInfo
or from an external source.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 section 2. Signature Overview and Examples. 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 an [XMLSCHEMA-1][XMLSCHEMA-2] 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" [ <!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">
Additional markup defined in version 1.1 of this
specification uses the dsig11:
namespace. The syntax is defined in an XML schema with the
following preamble:
Schema Definition:
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE schema PUBLIC "-//W3C//DTD XMLSchema 200102//EN" [ <!ENTITY dsig 'http://www.w3.org/2000/09/xmldsig#'> <!ENTITY dsig11 'http://www.w3.org/2009/xmldsig11#'> <!ENTITY % p ''> <!ENTITY % s ''> ]> <schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:dsig11="http://www.w3.org/2009/xmldsig11#" targetNamespace="http://www.w3.org/2009/xmldsig11#" version="0.1" elementFormDefault="qualified">
ds:CryptoBinary
Simple TypeThis 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 [RFC2045] encoded. (The
conversion from integer to octet string is equivalent to IEEE 1363's
I2OSP
[IEEE1363]
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" /> </simpleType>
Signature
elementThe Signature
element is the root element of an XML
Signature.
Implementation must generate
laxly
schema valid
[XMLSCHEMA-1][XMLSCHEMA-2]
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>
SignatureValue
ElementThe SignatureValue
element contains the
actual value of the
digital signature; it is always encoded using base64 [RFC2045].
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>
SignedInfo
ElementThe 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>
CanonicalizationMethod
ElementCanonicalizationMethod
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
section 6.1 Algorithm Identifiers and Implementation Requirements.
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.1.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:
SignedInfo
and currently indicating the
SignedInfo
, its descendants, and the attribute and namespace
nodes of SignedInfo
and its descendant elements.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 [XML10].
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 Reference
s 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>
SignatureMethod
ElementSignatureMethod
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>
The ds:HMACOutputLength
parameter is used for HMAC [HMAC] algorithms. The
parameter specifies a truncation length in bits. If this parameter is trusted without further
verification, then this can lead to a security bypass
[CVE-2009-0217].
Signatures must be deemed invalid if the truncation length is below
the larger of (a) half the underlying hash algorithm's output length,
and (b) 80 bits.
Note that some implementations are known to not
accept truncation lengths that are lower than the underlying hash algorithm's output length.
Reference
ElementReference
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>
URI
AttributeThe 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-2].
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 [HTTP11] (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 section 3.2 Core Validation for 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.
Note: XPath is recommended. Signature applications need not conform to [XPATH] specification in order to conform to this specification. However, the XPath data model, definitions (e.g., node-sets) and syntax is used within this document in order to describe functionality for those that want to process XML-as-XML (instead of octets) as part of signature generation. For those that want to use these features, a conformant [XPATH] implementation is one way to implement these features, but it is not required. Such applications could use a sufficiently functional replacement to a node-set and implement only those XPath expression behaviors required by this specification. However, for simplicity we generally will use XPath terminology without including this qualification on every point. Requirements over "XPath node-sets" can include a node-set functional equivalent. Requirements over XPath processing can include application behaviors that are equivalent to the corresponding XPath behavior.
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:
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 section 3.1.1 Reference Generation 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.4.3.4).)
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 [RFC2045]. 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
or XPath Filter 2 Transform [XMLDSIG-XPATH-FILTER2].
When a fragment is not preceded by a URI in the URI-Reference, XML
Signature applications must support the null URI and shortname XPointer [XPTR-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.4.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)
'
[XPTR-ELEMENT] when evaluated with
respect to the document that contains the
URI
attribute.
The original edition of this specification [XMLDSIG-CORE]
referenced the XPointer
Candidate Recommendation [XPTR-XPOINTER-CR2001]
and some implementations support it optionally.
That Candidate Recommendation has been superseded by the
[XPTR-FRAMEWORK], [XPTR-XMLNS] and [XPTR-ELEMENT] Recommendations,
and -- at the time of this edition -- the
[XPTR-XPOINTER]
Working Draft. Therefore, the use of
the
xpointer()
scheme [XPTR-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"
URI="http://example.com/bar.xml#chapter1"
URI=""
URI="#chapter1"
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 [XPTR-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 [XPTR-FRAMEWORK] were a node-set derived from the resultant
subresource as follows:
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.4.3.2).
Transforms
ElementThe 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.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 section 6.1 Algorithm Identifiers and Implementation Requirements)
As described in The Reference Processing Model (section 4.4.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 Transform
s 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 [RFC2045],
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>
DigestMethod
ElementDigestMethod
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 section 6.1 Algorithm Identifiers and Implementation Requirements.
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 section 4.4.3.2 The Reference Processing Model. 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>
DigestValue
ElementDigestValue is an element that contains the encoded value of the digest. The digest is always encoded using base64 [RFC2045].
Schema Definition:
<element name="DigestValue" type="ds:DigestValueType"/> <simpleType name="DigestValueType"> <restriction base="base64Binary"/> </simpleType>
KeyInfo
ElementKeyInfo
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-NAMES].
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.
Details of the structure and usage of element children
of KeyInfo
other than
simple types described in this specification are out of scope. For
example, the definition of PKI certificate contents, certificate ordering,
certificate revocation and CRL management are out of scope.
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.5.2 The KeyValue Element) and
should implement KeyInfoReference
(section 4.5.10 The KeyInfoReference Element).
KeyInfoReference
is preferred over use of
RetrievalMethod
as it avoids use of
Transform
child elements that
introduce security risk and implementation challenges. Support for
other children of KeyInfo
is optional.
The schema specification 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 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.
The following list summarizes the additional KeyInfo
types that are allocated an identifier in the dsig11:
namespace.
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"/> <!-- <element ref="dsig11:DEREncodedKeyValue"/> --> <!-- DEREncodedKeyValue (XMLDsig 1.1) will use the any element --> <!-- <element ref="dsig11:KeyInfoReference"/> --> <!-- KeyInfoReference (XMLDsig 1.1) will use the any element --> <!-- <element ref="xenc:EncryptedKey"/> --> <!-- EncryptedKey (XMLEnc) will use the any element --> <!-- <element ref="xenc:Agreement"/> --> <!-- Agreement (XMLEnc) will use the any element --> <any processContents="lax" namespace="##other"/> <!-- (1,1) elements from (0,unbounded) namespaces --> </choice> <attribute name="Id" type="ID" use="optional"/> </complexType>
KeyName
ElementThe 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" />
KeyValue
ElementThe KeyValue
element contains a single public key that may be
useful in validating the signature. Structured formats for defining DSA
(required), RSA (required) and ECDSA (required) public keys are
defined in
section 6.4 Signature Algorithms.
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"/> <!-- <element ref="dsig11:ECKeyValue"/> --> <!-- ECC keys (XMLDsig 1.1) will use the any element --> <any namespace="##other" processContents="lax"/> </choice> </complexType>
DSAKeyValue
ElementType="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 [FIPS-186-3]. DSA public key values can have the following fields:
P
Q
G
Y
J
seed
pgenCounter
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 [FIPS-186-3]. 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
[RFC2045]
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>
RSAKeyValue
ElementType="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>
ECKeyValue
ElementType="http://www.w3.org/2009/xmldsig11#ECKeyValue"
(this can be used within a RetrievalMethod
or Reference
element to identify the referent's type)The ECKeyValue
element is defined in the
http://www.w3.org/2009/xmldsig11# namespace.
EC public key values consists of two sub components: Domain parameters and
PublicKey
.
<ECKeyValue xmlns="http://www.w3.org/2009/xmldsig11#"> <NamedCurve URI="urn:oid:1.2.840.10045.3.1.7" /> <PublicKey> vWccUP6Jp3pcaMCGIcAh3YOev4gaa2ukOANC7Ufg Cf8KDO7AtTOsGJK7/TA8IC3vZoCy9I5oPjRhyTBulBnj7Y </PublicKey> </ECKeyValue>
Note - A line break has been added to the PublicKey
content to preserve printed page width.
Domain parameters can be encoded explicitly using
the dsig11:ECParameters
element
or by reference using the dsig11:NamedCurve
element. A named
curve is specified
through the URI
attribute. For named curves that are
identified by
OIDs, such as those defined in [RFC3279] and [RFC4055],
the OID should be encoded
according to [URN-OID]. Conformant
applications must support the dsig11:NamedCurve
element and
the 256-bit prime field
curve as identified by the OID 1.2.840.10045.3.1.7
.
The PublicKey
element contains a Base64 encoding of
a binary representation
of the x and y coordinates of the point. Its value is computed as
follows:
Schema Definition:
<!-- targetNamespace="http://www.w3.org/2009/xmldsig11#" --> <element name="ECKeyValue" type="dsig11:ECKeyValueType" /> <complexType name="ECKeyValueType"> <sequence> <choice> <element name="ECParameters" type="dsig11:ECParametersType" /> <element name="NamedCurve" type="dsig11:NamedCurveType" /> </choice> <element name="PublicKey" type="dsig11:ECPointType" /> </sequence> <attribute name="Id" type="ID" use="optional" /> </complexType> <complexType name="NamedCurveType"> <attribute name="URI" type="anyURI" use="required" /> </complexType> <simpleType name="ECPointType"> <restriction base="ds:CryptoBinary" /> </simpleType>
The ECParameters
element consists of the following
subelements. Note these
definitions are based on the those described in [RFC3279].
FieldID
element identifies the finite field
over which the elliptic
curve is defined. Additional details on the structures for
defining prime
and characteristic two fields is provided below.dsig11:Curve
element specifies the coefficients a
and b of the elliptic
curve E. Each coefficient is first converted from a field
element to an
octet string as specified in section 6.2 of [ECC-ALGS], then
the resultant octet string is encoded in
base64.Base
element specifies the base point P on
the elliptic curve. The
base point is represented as a value of type ECPointType
.Order
element specifies the order n of the base point and is encoded
as a positiveInteger.Cofactor
element is an optional element that
specifies the integer h
= #E(Fq)/n. The cofactor is not required to support ECDSA, except in
parameter validation. The cofactor may be included to support parameter
validation for ECDSA keys. Parameter validation is not required by this
specification. The cofactor is required in ECDH public key parameters.dsig11:ValidationData
element is an optional
element that
specifies the hash algorithm used to generate the elliptic curve E
and the base point G verifiably at random. It also specifies the
seed that was used to generate the curve and the base point.
Schema Definition:
<!-- targetNamespace="http://www.w3.org/2009/xmldsig11#" --> <complexType name="ECParametersType"> <sequence> <element name="FieldID" type="dsig11:FieldIDType" /> <element name="Curve" type="dsig11:CurveType" /> <element name="Base" type="dsig11:ECPointType" /> <element name="Order" type="ds:CryptoBinary" /> <element name="CoFactor" type="integer" minOccurs="0" /> <element name="ValidationData" type="dsig11:ECValidationDataType" minOccurs="0" /> </sequence> </complexType> <complexType name="FieldIDType"> <choice> <element ref="dsig11:Prime" /> <element ref="dsig11:TnB" /> <element ref="dsig11:PnB" /> <element ref="dsig11:GnB" /> <any namespace="##other" processContents="lax" /> </choice> </complexType> <complexType name="CurveType"> <sequence> <element name="A" type="ds:CryptoBinary" /> <element name="B" type="ds:CryptoBinary" /> </sequence> </complexType> <complexType name="ECValidationDataType"> <sequence> <element name="seed" type="ds:CryptoBinary" /> </sequence> <attribute name="hashAlgorithm" type="anyURI" use="required" /> </complexType>
Prime fields are described by a single subelement P
,
which represents the
field size in bits. It is encoded as a positiveInteger.
Schema Definition:
<!-- targetNamespace="http://www.w3.org/2009/xmldsig11#" --> <element name="Prime" type="dsig11:PrimeFieldParamsType" /> <complexType name="PrimeFieldParamsType"> <sequence> <element name="P" type="ds:CryptoBinary" /> </sequence> </complexType>
Structures are defined for three types of characteristic two fields: gaussian normal basis, pentanomial basis and trinomial basis.
Schema Definition:
<!-- targetNamespace="http://www.w3.org/2009/xmldsig11#" --> <element name="GnB" type="dsig11:CharTwoFieldParamsType" /> <complexType name="CharTwoFieldParamsType"> <sequence> <element name="M" type="positiveInteger" /> </sequence> </complexType> <element name="TnB" type="dsig11:TnBFieldParamsType" /> <complexType name="TnBFieldParamsType"> <complexContent> <extension base="dsig11:CharTwoFieldParamsType"> <sequence> <element name="K" type="positiveInteger" /> </sequence> </extension> </complexContent> </complexType> <element name="PnB" type="dsig11:PnBFieldParamsType" /> <complexType name="PnBFieldParamsType"> <complexContent> <extension base="dsig11:CharTwoFieldParamsType"> <sequence> <element name="K1" type="positiveInteger" /> <element name="K2" type="positiveInteger" /> <element name="K3" type="positiveInteger" /> </sequence> </extension> </complexContent> </complexType>
Implementations that need to support the [RFC4050] format for ECDSA keys can avoid known interoperability problems with that specification by adhering to the following profile:
ECDSAKeyValue
element against the [RFC4050]
schema. XML schema validators may not support integer types with decimal data
exceeding 18 decimal digits.
[XMLSCHEMA-1][XMLSCHEMA-2].NamedCurve
element.urn:oid:1.2.840.10045.3.1.7
.The following is an example of a ECDSAKeyValue
element that meets the
profile described in this section.
<ECDSAKeyValue xmlns="http://www.w3.org/2001/04/xmldsig-more#"> <DomainParameters> <NamedCurve URN="urn:oid:1.2.840.10045.3.1.7" /> </DomainParameters> <PublicKey> <X Value="5851106065380174439324917904648283332 0204931884267326155134056258624064349885" /> <Y Value="1024033521368277752409102672177795083 59028642524881540878079119895764161434936" /> </PublicKey> </ECDSAKeyValue>
Note - A line break has been added to the X
and Y
Value
attribute values to preserve
printed page width.
RetrievalMethod
ElementA 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 the Reference
URI attribute (section 4.4.3.1 The URI Attribute) and
the Reference Processing Model
except that there are
no DigestMethod
or DigestValue
child elements and presence of the URI
attribute 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.5 The KeyInfo Element)
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.
Note that when referencing one of the
defined KeyInfo
types within the same document, or some remote documents, at
least one Transform
is required to turn an ID-based
reference to a KeyInfo
element into a child element located inside it. This is due to the lack of
an XML ID attribute on the defined KeyInfo
types.
In such cases, use of KeyInfoReference
is
encouraged instead, see
section 4.5.10 The KeyInfoReference Element.
Note:
The KeyInfoReference
element is preferred over use of
RetrievalMethod
as it avoids use
of Transform
child elements that
introduce security risk and implementation challenges.
.footer {
position: fixed;
left: 0;
bottom: 0;
width: 100%;
background-color: white;
color: black;
text-align: center;
}