DocumentID: ECMA-376/Part2/12.2.4
Title: ECMA-376, Part2: 12.2.4 Digital Signature Markup
Extracted-From: ECMA-376 Office Open XML File Formats, 1st Edition / December 2006
Warning: Coverted to HTML format by a script known to have bugs

• Next: 12.3 Digital Signature Example
• Up: 12.2 Digital Signature Parts
• Table of contents: Table of contents
• Previous: 12.2.3 Digital Signature Certificate Part

12.2.4 Digital Signature Markup

The markup described here includes a subset of elements and attributes from the XML Digital Signature specification and some package-specific markup. For a complete example of a digital signature, see §12.3.

12.2.4.1 Modifications to the XML Digital Signature Specification

The package modifications to the XML Digital Signature specification are summarized as follows:

1. The producer shall create Reference elements within a SignedInfo element that reference elements within the same Signature element. The consumer shall consider Reference elements within a SignedInfo element that reference any resources outside the same Signature element to be in error. [M6.5] The producer should only create Reference elements within a SignedInfo element that reference an Object element. [S6.5] The producer shall not create a reference to a package-specific Object element that contains a transform other than a canonicalization transform. The consumer shall consider a reference to a package-specific Object element that contains a transform other than a canonical transform to be an error. [M6.6]
2. The producer shall create one and only one package-specific Object element in the Signature element. The consumer shall consider zero or more than one package-specific Object element in the Signature element to be an error. [M6.7]

The producer shall create package-specific Object elements that contain exactly one Manifest element and exactly one SignatureProperties element. [Note: This SignatureProperties element can contain multiple SignatureProperty elements. end note] The consumer shall consider package-specific Object elements that contain other types of elements to be an error. [M6.8] [Note: A signature may contain other Object elements that are not package-specific. end note]

[Note: All modifications to XML Digital Signature markup occur in locations where the XML Signature schema allows any namespace. Therefore, package digital signature XML is valid against the XML Signature schema. end note]

12.2.4.2 Signature Element

The structure of a Signature element is shown in the following diagram:

diagram
namespace	http://www.w3.org/2000/09/xmldsig#
attributes	Name Type Use Default Fixed Annotation Id xs:ID optional A unique identifier of the signature xml document.
annotation	The root element of the signature xml document stored in a signature part. The producer shall create a Signature element that contains exactly one local-data, package-specific Object element and zero or more application-specific Object elements. If a Signature element violates this constraint, a consumer shall consider this to be an error. [M6.15]

12.2.4.3 SignedInfo Element

The structure of a SignedInfo element is shown in the following diagram:

diagram
namespace	http://www.w3.org/2000/09/xmldsig#
annotation	Specifies the data in the package that is signed. Holds one or more references to Object elements within the same Digital Signature XML Signature part. The producer shall create a SignedInfo element that contains exactly one reference to the package-specific Object element. The consumer shall consider it an error if a SignedInfo element does not contain a reference to the package-specific Object element. [M6.16]

12.2.4.4 CanonicalizationMethod Element

The structure of a CanonicalizationMethod element is shown in the following diagram:

diagram
namespace	http://www.w3.org/2000/09/xmldsig#
attributes	Name Type Use Default Fixed Annotation Algorithm xs:anyURI required Contains a URI that identifies the particular canonicalization algorithm.
annotation	Specifies the canonicalization algorithm applied to the SignedInfo element prior to performing signature calculations.

Since XML allows equivalent content to be represented differently, a producer should apply a canonicalization transform to the SignedInfo element when it generates it, and a consumer should apply the canonicalization transform to the SignedInfo element when validating it. [S6.3]

[Note: Performing a canonicalization transform ensures that SignedInfo content can be validated even if the content has been regenerated using, for example, different entity structures, attribute ordering, or character encoding.

Producers and consumers should also use canonicalization transforms for references to parts that hold XML documents. These transforms are defined using the Transformelement. end note]

The following canonicalization methods shall be supported by producers and consumers of packages with digital signatures:

• XML Canonicalization (c14n)
• XML Canonicalization with Comments (c14n with comments)

Consumers validating signed packages shall fail the validation if other canonicalization methods are encountered. [M6.34]

12.2.4.5 SignatureMethod Element

The structure of a SignatureMethod element is shown in the following diagram:

diagram
namespace	http://www.w3.org/2000/09/xmldsig#
attributes	Name Type Use Default Fixed Annotation Algorithm xs:anyURI required Contains a URI that identifies the particular algorithm for the signature method.
annotation	Defines the algorithm that is used to convert the SignedInfo element into a hashed value contained in the SignatureValueelement. Producers shall support DSA and RSA algorithms to produce signatures. Consumers shall support DSA and RSA algorithms to validate signatures. [M6.17]

12.2.4.6 Reference Element

The structure of a Reference element is shown in the following diagram:

diagram
namespace	http://www.w3.org/2000/09/xmldsig#
attributes	Name Type Use Default Fixed Annotation URI xs:anyURI required Within a <SignedInfo> element, this attribute contains a URI that identifies an element within the signature xml document. Within a <Manifest> element, this attribute contains a relative reference composed of a reference to a part that conforms to the part name grammar and a query component that identifies the content type of that part.
annotation	Specifies the object being signed, a digest algorithm, a digest value, and a list of transforms to be applied prior to digesting.

12.2.4.6.1 Usage of <Reference> Element as <Manifest> Child Element

The producer shall create a Reference element within a Manifest element with a URI attribute and that attribute shall contain a part name, without a fragment identifier. The consumer shall consider a Reference element with a URI attribute that does not contain a part name to be an error. [M6.18]

References to package parts include the part content type as a query component. The syntax of the relative reference is as follows:

/page1.xml?ContentType="value"

where value is the content type of the targeted part.

[Note: See §12.2.4.1 for additional requirements on Reference elements. end note]

[Example:

Example 12--2. Part reference with query component

In the following example, the content type is "application/vnd.ms-package.relationships+xml".

URI="/_rels/document.xml.rels?ContentType=application/vnd.ms-package.relationships+xml"

end example]

12.2.4.7 Transforms Element

The structure of a Transforms element is shown in the following diagram:

diagram
namespace	http://www.w3.org/2000/09/xmldsig#
annotation	Contains an ordered list of Transform elements that describe how the producer digested the Object data before signing it.

The following transforms shall be supported by producers and consumers of packages with digital signatures:

• XML Canonicalization (c14n)
• XML Canonicalization with Comments (c14n with comments)
• Relationships transform (package-specific)

Consumers validating signed packages shall fail the validation if other transforms are encountered. Relationships transforms shall only be supported by producers and consumers when the Transform element is a descendant element of a Manifest element [M6.19]

12.2.4.8 Transform Element

The structure of a Transform element is shown in the following diagram:

diagram
namespace	http://www.w3.org/2000/09/xmldsig#
attributes	Name Type Use Default Fixed Annotation Algorithm xs:anyURI required Contains a URI that identifies the particular transformation algorithm.
annotation	Describes how the signer obtained the Object data that was digested.

12.2.4.9 DigestMethod Element

The structure of a DigestMethod element is shown in the following diagram:

diagram
namespace	http://www.w3.org/2000/09/xmldsig#
attributes	Name Type Use Default Fixed Annotation Algorithm xs:anyURI required Contains a URI that identifies the particular digest method.
annotation	Defines the algorithm that yields the DigestValue from the object data after transforms are applied. Package producers and consumers shall support RSA-SHA1 algorithms to produce or validate signatures. [M6.17]

12.2.4.10 DigestValue Element

The structure of a DigestValue element is shown in the following diagram:

diagram
namespace	http://www.w3.org/2000/09/xmldsig#
annotation	Contains the encoded value of the digest in base64.

12.2.4.11 SignatureValue Element

The structure of a SignatureValue element is shown in the following diagram:

diagram
namespace	http://www.w3.org/2000/09/xmldsig#
attributes	Name Type Use Default Fixed Annotation Id xs:ID optional Contains a URI that identifies the SignatureValueelement within the signature xml document.
annotation	Contains the actual value of the digital signature in base64.

12.2.4.12 Object Element

The Object element can be either package-specific or application-specific.

12.2.4.13 Package-Specific Object Element

The structure of a Object element is shown in the following diagram:

diagram
namespace	http://www.w3.org/2000/09/xmldsig#
attributes	Name Type Use Default Fixed Annotation Id xs:ID Shall have value of "idPackageObject".
annotation	Holds the Manifest and SignatureProperties elements that are package-specific.

[Note: Although the diagram above shows use of the Id attribute as optional, as does the XML Digital Signature schema, for package-specific Object elements, the Id attribute shall be specified and have the value of "idPackageObject". This is a package-specific restriction over and above the XML Digital Signature schema. end note]

The producer shall create each Signature element with exactly one package-specific Object. For a signed package, consumers shall treat the absence of a package-specific Object, or the presence of multiple package-specific Object elements, as an invalid signature. [M6.15]

12.2.4.14 Application-Specific Object Element

The application-specific Object element specifies application-specific information. The format designer might permit one or more application-specific Object elements. If allowed by the format designer, format producers can create one or more application-specific Object elements. [O6.8] Producers shall create application-specific Object elements that contain XML-compliant data; consumers shall treat data that is not XML-compliant as an error. [M6.20] Format designers and producers might not apply package-specific restrictions regarding URIs and Transform elements to application-specific Object element. [O6.9]

12.2.4.15 KeyInfo Element

The structure of a KeyInfo element is shown in the following diagram:

diagram
namespace	http://www.w3.org/2000/09/xmldsig#
annotation	Enables recipients to obtain the key needed to validate the signature. Can contain keys, names, certificates, and other public key management information. Producers and consumers shall use the certificate embedded in the Digital Signature XML Signature part when it is specified. [M6.21]

12.2.4.16 X509Data Element

The structure of an X509Data element is shown in the following diagram:

diagram
namespace	http://www.w3.org/2000/09/xmldsig#
annotation	Contains one or more identifiers of X509 certificates.

12.2.4.17 X509Certificate Element

The structure of an X509Certificate element is shown in the following diagram:

diagram
namespace	http://www.w3.org/2000/09/xmldsig#
annotation	Contains a base64-encoded X509 certificate.

12.2.4.18 Manifest Element

The structure of a Manifest element is shown in the following diagram:

diagram
namespace	http://www.w3.org/2000/09/xmldsig#
annotation	Contains references to the signed parts of the package. The producer shall not create a Manifest element that references any data outside of the package. The consumer shall consider a Manifest element that references data outside of the package to be in error. [M6.22]

12.2.4.19 SignatureProperties Element

The structure of a SignaturePropertieselement is shown in the following diagram:

diagram
namespace	http://www.w3.org/2000/09/xmldsig#
Annotation	Contains additional information items concerning the generation of signatures placed in SignatureProperty elements.

12.2.4.20 SignatureProperty Element

The structure of a SignatureProperty element is shown in the following diagram:

diagram
namespace	http://www.w3.org/2000/09/xmldsig#
attributes	Name Type Use Default Fixed Annotation Target xs:anyURI required Contains a unique identifier of the Signature element. Id xs:ID optional Contains signature property's unique identifier.
annotation	Contains additional information concerning the generation of signatures.

12.2.4.21 SignatureTime Element

The structure of a SignatureTime element is shown in the following diagram:

diagram
namespace	http://schemas.openxmlformats.org/package/2006/digital-signature
annotation	Holds the date/time stamp for the signature.

12.2.4.22 Format Element

The structure of a Format element is shown in the following diagram:

diagram
namespace	http://schemas.openxmlformats.org/package/2006/digital-signature
annotation	Specifies the format of the date/time stamp. The producer shall create a data/time format that conforms to the syntax described in the W3C Note "Date and Time Formats". The consumer shall consider a format that does not conform to the syntax described in that WC3 note to be in error. [M6.23]

The date and time format definition conforms to the syntax described in the W3C Note "Date and Time Formats."

12.2.4.23 Value Element

The structure of a Value element is shown in the following diagram:

diagram
namespace	http://schemas.openxmlformats.org/package/2006/digital-signature
annotation	Holds the value of the date/time stamp. The producer shall create a value that conforms to the format specified in the Format element. The consumer shall consider a value that does not conform to that format to be in error. [M6.24]

12.2.4.24 RelationshipReference Element

The structure of a RelationshipReference element is shown in the following diagram:

diagram
namespace	http://schemas.openxmlformats.org/package/2006/digital-signature
attributes	Name Type Use Default Fixed Annotation SourceId xsd:string required Specifies the value of the Id attribute of the Relationship element.
annotation	Specifies the Relationship element to be signed.

12.2.4.25 RelationshipsGroupReference Element

The structure of a RelationshipsGroupReference element is shown in the following diagram:

diagram
namespace	http://schemas.openxmlformats.org/package/2006/digital-signature
attributes	Name Type Use Default Fixed Annotation SourceType xsd:anyURI required Specifies the value of the Type attribute of Relationship elements.
annotation	Specifies that the group of Relationship elements with the specified Type value is to be signed.

Format designers might permit producers to sign individual relationships in a package or the Relationships part as a whole. [O6.10] To sign a subset of relationships, the producer shall use the package-specific relationships transform. The consumer shall use the package-specific relationships transform to validate the signature when a subset of relationships are signed. [M6.25] The transform filters the contents of the Relationships part to include only relationships that have Id values matching the specified SourceId values or Type values matching the specified SourceType values. A producer shall not specify more than one relationship transform for a particular relationships part. A consumer shall treat the presence of more than one relationship transform for a particular relationships part as an error. [M6.35]

Producers shall specify a canonicalization transform immediately following a relationships transform and consumers that encounter a relationships transform that is not immediately followed by a canonicalization transform shall generate an error. [M6.26]

12.2.4.26 Relationships Transform Algorithm

The relationships transform takes the XML document from the Relationships part and converts it to another XML document.

The package implementer might create relationships XML that contains content from several namespaces, along with versioning instructions as defined in Part 5: "Markup Compatibility and Extensibility". [O6.11]

The relationships transform algorithm is as follows:

Step 1: Process versioning instructions

1. The package implementer shall process the versioning instructions, considering that the only known namespace is the Relationships namespace.
2. The package implementer shall remove all ignorable content, ignoring preservation attributes.
3. The package implementer shall remove all versioning instructions.

Step 2: Sort and filter relationships

1. The package implementer shall remove all namespace declarations except the Relationships namespace declaration.
2. The package implementer shall remove the Relationships namespace prefix, if it is present.
3. The package implementer shall sort relationship elements by Id value in lexicographical order, considering Id values as case-sensitive Unicode strings.
4. The package implementer shall remove all Relationship elements that do not have eitheran Id value that matches any SourceId valueor a Type value that matches any SourceType value, among the SourceId and SourceType values specified in the transform definition. Producers and consumers shall compare values as case-sensitive Unicode strings. [M6.27] The resulting XML document holds all Relationship elements that either have an Id value that matches a SourceId value or a Type value that matches a SourceType value specified in the transform definition.

Step 3: Prepare for canonicalization

1. The package implementer shall remove all characters between the Relationships start tag and the first Relationship start tag.
2. The package implementer shall remove any contents of the Relationship element.
3. The package implementer shall remove all characters between the last Relationship end tag and the Relationships end tag.
4. If there are no Relationship elements, the package implementer shall remove all characters between the Relationships start tag and the Relationships end tag.