XML-Signature Core Syntax

W3C Status of this Document

This is the candidate first WG's Working Draft. The attached update to the syntax draft represents the consensus reached at the FTF on 30/31 Aug. Tentative decisions (pending further review here) reflected in the attached include:

• changing the name of signedobject data to signedobject reference
• promoting objecttype within signedobject reference
• allowing multiple instances of signedobject reference and signedobject within signature - eliminating signatureattributes (signedattributes) as an explicit item. It is now expected to be handled as an instance of signedobject
• defining other useful types (signatureattributes, manifest) - filling in a few more blanks
• decision to maintain the grouping around keyinfodata and attributedata (i.e. not promoting those types)
• confirming decision to go with the signedobject reference model with mandatory validation of the digest over signedobject at the top level
• confirming decision to keep keyinfo out of the signedinfo element (but note it can be bound using a signedobject reference if an application desires)

Abstract

This document lists the core signature syntax. 

Table of Contents

...

1.0 Introduction

This document describes the proposed syntax and processing rules for the XML Digital Signature Standard. This standard provides a mechanism for applying digital signatures to XML documents and other internet resources.

The structure allows for both embedded and detached signatures. An embedded signature may either include the signature within the signed object or embed the signed object within the signature. A detached signature allows the signature to be independent of the object. The processing structure allows for switching between embedded and detached signatures without invalidating the signature.

In addition to the basic signature document type, this document also defines other useful types including a manifest for referencing multiple resources and key management and algorithm definitions.

2.0 Signature Structre

The general structure of an XML signature document is:

<signature>
  <signedinfo/>
  <signedobject />
  <keyinfo/>
  <signaturevalue/>
</signature>

2.1 signedinfo

signedinfo is the actual data over which the signature is calculated. It contains control information (algorithm identifiers, pre-processing transformations) and digest(s) over the object(s) being signed.

2.2 signedobject

signedobject is an optional element which may occur one or more times and which is used to include the object(s) being signed within the signature document. When present this element may contain any item and specifies the encoding.

2.3 keyinfo

keyinfo is an optional element which enables the recipient(s) to obtain the key(s) needed to validate the signature. keyinfo may contain the key, may name the key, may include certificates and other public key management information, may include inband key distribution or agreement data, or use any other method.

2.4 signaturevalue

signaturevalue is an empty element that contains the actual value of the digital signature. The ability to define a signaturealg and signaturevalue pair which includes multiple distinct signatures is explicitly permitted (e.g. "rsawithsha-1 and ecdsawithsha-1").

3.0 signedinfo

The structure of signedinfo is:

<signedinfo>
  <c14nalg/>
  <signaturealg/>
  <signedobject reference/>
</signedinfo>

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 an explicit signatureattributes element. If an application needs to associate attributes (such as signing time, signing device, etc.) with the signature, it may add an additional signedobject reference and signedobject to the signature (see useful types).

3.1 c14nalg

c14nalg is an optional element which specifies the c14n algorithm applied to the signedinfoelement prior to performing signature calculations. If the default c14n algorithm for signedinfois used, this element may be omitted. This element uses the general structure here for algorithms in which a uri is included as an attribute naming the algorithm and optional contents of the element contain any parameter, value, or other information defined by the algorithm name. Possible options may include a null algorithm (no changes), a simple identity algorithm (CRLF and charset normalization), and more extensive transformations such as the W3C c14n proposal.

3.2 signaturealg

signaturealg is a required element which specifies the algorithm used for signature generation and validation. This algorithm ID identifies all cryptographic functions involved in the signature operation (e.g. hashing, public key algorithms, MACs, etc.). This element uses the general structure here for algorithms in which a uri is included as an attribute naming the algorithm and optional contents of the element contain any parameter, value, or other information defined by the algorithm name. While there is a single identifier, that identifier may specify a format containing multiple distinct signature values.

3.3 signedobject reference

signedobject reference  is an element that may occur one or more times. The structure of signedobject reference is:

<signedobject reference>
  <objectlocation/>
  <objecttype/>
  <transformations/>
  <digestalg/>
  <digestvalue/>
</signedobject reference>

3.3.1 objectlocation

objectlocation identifies where to find the signedobject . This element may be omitted if the location is implicit in the application.

3.3.2 objecttype

objecttype is an optional element which contains information about the type of object being signed (e.g. manifest, package, document, signedinfo, PDF file). This may be represented as a name (e.g. MIME type), namespace qualified element name, or uri.

3.3.3 transformations

transformations is an optional element that contains one or more operations to be performed on the signedobject prior to signature calculation. Examples of transformations include c14n, exclusion (omitting certain portions of the object from the signature), encoding, etc. Each element within transformations uses the general structure here for algorithms in which a uri is included as an attribute naming the algorithm and optional contents of the element contain any parameter, value, or other information defined by the algorithm name. If the transformations element is omitted, the only operation performed is the default object c14n algorithm (null or identity).

3.3.4 digestalg

digestalg is a required element which identifies the digest algorithm to be applied to the signed object. This element uses the general structure here for algorithms in which a uri is included as an attribute naming the algorithm and optional contents of the element contain any parameter, value, or other information defined by the algorithm name.

3.3.5 digestvalue

digestvalue is a required empty element which contains the base64 encoded value of the digest.

4.0 signedobject

signedobject is an optional element which may occur one or more times and which contains a signed object identified in a signedobject reference in signedinfo. This element is used for embedded signatures where the object being signed is to be included in the signature document. The signedobject element may include optional type, ID, and encoding attributes and may contain any data.

5.0 keyinfo

keyinfo is an optional element which enables the recipient(s) to obtain the key(s) needed to validate the signature. If omitted, the recipient is expected to be able to identify the key based on application context information. This element contains one or more keyinfo data elements providing information for the recipient(s). Some types are defined here, although applications may define any mechanism they choose.

5.1 keyname

keyname contains an identifier for the key which may be useful to the recipient. This may be a name, index, etc.

5.2 keyvalue

keyvalue contains the actual key(s) used to validate the signature. If the key is sent in protected form, the keymgmtdata element should be used. Specific types must be defined for each algorithm type (see algorithms).

5.3 subjectname

subjectname contains one or more names for the sender. Forms to be supported include a simple name string, encoded DN, email address, etc.

5.4 keyretrievalmethod

keyretrievalmethod is a uri which may be used to obtain key and/or certificate information. The uri should contain the complete string for retrieving the key needed for this message (rather than a generic uri).

5.5 x509data

x509data contains an identifier of the key/cert used for validation (either an issuerserial value, a subject name, or a subjectkeyID) and an optional collection of certificates and revocation/status information which may be used by the recipient. issuerserial contains the encoded issuer name (RFCxxxx) along with the serial number.

5.6 pgpdata

5.7 keymgmtdata

keymgmtdata contains in-band key distribution or agreement data. Examples may include DH key exchange, RSA key encryption etc.

6.0 signaturevalue

signaturevalue is a required empty element which contains the base64 encoded value of the signature as defined by the signaturealg value in signedinfo.

7.0 Algorithms

This sections identifies algorithms used with the XML digital signature standard. Entries contain the identifier to be used in signature documents, a reference to the formal specification, and definitions, where applicable, for the representation of keys and the results of cryptographic operations.

7.1 Digest algorithms

SHA-1, MD5, (AESH)

7.2 Signature algorithms

HMAC, DSAwithSHA1, RSAwithSHA1, RSAwithMD5

7.3 c14n algorithms

Null, Minimal, DOM-CANON, W3C-SWG

7.4 exclusion

Xpointer, ??

8.0 Processing rules

These sections describe the operations to be performed as part of signature generation and validation. The description is of a logical behavior and does not specify an order of execution, nor specify discrete steps.

8.1 Generation

1. apply transformations determined by application to object to be signed.
2. calculate digest over object
3. create signedobject reference element(s) including location of object, digest, and transformation and digest algorithm elements, if required.
4. create signedinfoelement with signaturealg, c14nalg (for signedinfo), and signedobject reference(s).
5. canonicalize and calculate signature over signedinfobased on algorithms in step d. f) construct signature document with signedinfo, signedobject (s) (if desired, encoding may be different than that used for signing), keyinfo (if required), and signaturevalue.

8.2 Validation

1. locate and apply transformations (e.g. c14n) to the signed object(s) based on all signedobject reference(s) in the signedinfoelement.
2. calculate digest over all transformed signed object(s) based on the algorithm in signedobject reference(s). If the object is contained within the signedobject element, only the object itself is hashed (i.e. the <signedobject > and </signedobject > tags are excluded).
3. compare value against digest value in signedinfo(if mismatch, validation fails).
4. canonicalize the signedinfoelement based on the c14n algorithm ID in signedinfo(or based on the default if absent).
5. obtain the validation keying info from keyinfo or externally.
6. alidate the signaturevalue based on the signaturealg in the signedinfoelement, the key obtained in step c, and the results of step d. - Digest calculation is performed over the signedinfoelement including start and end tags.

9 DTD

<?xml version="1.0"?>

 <!ELEMENT dsig:signature 
   (dsig:signedinfo, dsig:signedobject*, dsig:keyinfo?, 
dsig:signaturevalue)>
 <!ATTLIST dsig:signature
         id     ID      #IMPLIED>

 <!ELEMENT dsig:signedinfo 
     (dsig:c14nalg?, dsig:signaturealg, dsig:signedobjectreference+ )>    
 <!ATTLIST dsig:signedinfo
         id     ID      #IMPLIED>

 <!ELEMENT dsig:signedobject ANY>
 <!ATTLIST dsig:signedobject
          id    CDATA   #IMPLIED
          type  CDATA   #IMPLIED
          encoding      CDATA   #IMPLIED >

 <!ELEMENT dsig:keyinfo  (dsig:keyinfodata)+>
 <!-- must be at least one keyinfodata or omit the element-->  

 <!ELEMENT dsig:keyinfodata ANY>
 <!ATTLIST dsig:keyinfodata
        type    CDATA   #REQUIRED >

 <!ELEMENT dsig:signaturevalue EMPTY)>
 <!ATTLIST dsig:signaturevalue
          value         CDATA   #REQUIRED >
 <!-- base64 encoded signature value -->

 <!ELEMENT dsig:c14nalg ANY>
 <!ATTLIST dsig:c14nalg
        type    CDATA   #REQUIRED >

 <!ELEMENT dsig:signaturealg ANY>
 <!ATTLIST dsig:signaturealg
        type    CDATA   #REQUIRED >

 <!ELEMENT dsig:digestalg ANY>
 <!ATTLIST dsig:digestalg
        type    CDATA   #REQUIRED >

 <!ELEMENT dsig:encoding ANY>
 <!ATTLIST dsig:encoding
        type    CDATA   #REQUIRED >

 <!ELEMENT dsig:exclusion ANY>
 <!ATTLIST dsig:exclusion
        type    CDATA   #REQUIRED >

 <!ELEMENT dsig:signedobjectreference 
    (dsig:objectlocation?, dsig:objecttype?, dsig:transformations?,
dsig:digestalg, dsig:digestvalue) >

 <!ELEMENT dsig:objectlocation EMPTY >
 <!ATTLIST dsig:objectlocation
          href          CDATA   #REQUIRED >

 <!ELEMENT dsig:objecttype EMPTY >
 <!ATTLIST dsig:objecttype
          type          CDATA   #REQUIRED >

 <!ELEMENT dsig:transformations
  (dsig:c14nalg?, dsig:encoding?, dsig:exclusion?) >

 <!ELEMENT dsig:digestvalue EMPTY>
 <!-- base64 encoded digest value -->
 <!ATTLIST dsig:digestvalue
          value         CDATA   #REQUIRED >

----

 <!ELEMENT dsig:signatureattributes 
    (dsig:attributedata+, objectlocation?>

 <!ELEMENT dsig:attributedata ANY>
 <!ATTLIST dsig:attributedata
        type    CDATA   #REQUIRED >

 <!ELEMENT dsig:manifest
    (dsig:signedobjectreference+, signedobject*)
 <!ATTLIST dsig:manifest
        id      ID      #IMPLIED >

10.0 Example syntax

<dsig:signature>
  <dsig:signedinfo id="...">
    <dsig:c14nalg type="null"/>
    <dsig:signaturealg type="rsaWithSHA-1"/>
    <dsig:signedobjectreference>
      <dsig:objectlocation href="..."/> 
        <!-- pointer to external signedobject  -->
      <dsig:objecttype type="http://..." />
      <dsig:transformations>
         <dsig:c14nalg type="http://..."/>
         <dsig:encoding type="http://..."/>
      </dsig:transformations>
      <dsig:digestalg type="sha-1"/>
      <dsig:digestvalue value="a23bcd43" />
    </dsig:signedobjectreference>
    <dsig:signedobjectreference>
      <dsig:objectlocation href="..."/> 
        <!-- pointer to signedobject below -->
      <dsig:objecttype type="dsig:signatureattributes" />
      <dsig:transformations>
         <dsig:c14nalg type="http://..."/>
      </dsig:transformations>
      <dsig:digestalg type="sha-1"/>
      <dsig:digestvalue value="a53uud43" />
    </dsig:signedobjectreference>
  </dsig:signedinfo>
  <dsig:signedobject id="..." type="dsig:signatureattributes" >
    <dsig:signatureattributes>
      <dsig:attributedata type="http://...">   19990824132700Z  
      </dsig:attributedata>
      <objectlocation href="...">
        <!-- pointer to signedinfo above -->
    </dsig:signatureattributes>
  </dsig:signedobject>
  <dsig:keyinfo>
     <dsig:keyinfodata type="keyname"> 3 </dsig:keyinfodata>
  </dsig:keyinfo>
  <dsig:signaturevalue value="dd2323dd"/>
</dsig:signature>

11.0 Open Issues

1. Default c14n algorithms for signedinfoand for objects. Other defaults. Mandatory to implement cryptographic algorithms and keyinfo types.
2. Identifying signed object. How do we handle the pointer from signedinfoto the signed object, and what rules need to be defined for the ID attributes in signedinfoand signedobject ?

12.0 Security Considerations

...