ACTION-434: Propose final disposition of Referencing syntax

This is proposed text for 2.0 covering the general Reference/Selection
syntax but without complete specifics on the XPath subset used to perform
the actual selection work, which is waiting on additional discussion.

My suggestion is to get this text (once agreed to) along with all the other
"legacy" material into the new 2.0 document so that we can see everything in
context, and identify the remaining legacy text that needs tweaking to fit
with the new material.

A summation before the normative text so people know what they're reading:

- The Reference element does not carry a URI or Type attribute.

- When the content of the Transforms element contains exactly one Transform
child matching the new 2.0 Transform Algorithm, it's a 2.0 signature.
Otherwise it's a 1.x signature and the missing URI indicates
application-specific semantics as in the original spec.

- The new Transform algorithm includes ds2:Selection and
CanonicalizationMethod elements representing the two phases. For XML
content, since c14n always runs, the result is an octet stream and is fed
directly to the digest as per the original spec behavior (i.e., c14n is
never "implied"). I altered Pratik's initial proposal by reusing the
existing CanonicalizationMethod element, and suggest we limit all discussion
of parameters and their XML syntax to the c14n document. This is consistent
with past examples such as the excl c14n InclusivePrefixes list.

- The Selection element carries a URI attribute with simplified behavior
derived from the original spec to identify the "data context" for selection.
It also carries a Type attribute to identify the data type of the reference
and the selection syntax permitted. Thus, new syntaxes for XML selection
will use a different Type attribute to communicate this.

Now, the suggested normative text. The section numbers correspond to the
current drafts and may need adjusting during the editorial merge. Much of
the compatibility text is just the original 1.x text, but I've reordered
some of it in certain cases.

=======================
4.4.3 Reference Element

Reference is an element that may occur one or more times. It specifies a
digest algorithm and digest value, and optionally an identifier of the
object being signed, the type of the object, and/or a list of transforms to
be applied prior to digesting. The identification (URI) and transforms
describe how the digested content (i.e., the input to the digest method) was
created. The Type attribute facilitates the processing of referenced data.
For example, while this specification makes no requirements over external
data, an application may wish to signal that the referent is a Manifest. An
optional ID attribute permits a Reference to be referenced from elsewhere.

	Schema Definiton:
	(as before)

4.4.3.1 Signature Modes

The XML Signature 2.0 Specification is designed to support a new, simplified
processing model while remaining backwardly compatible with the older 1.x
processing model. These are termed "2.0 Mode" and "Compatibility Mode"
respectively.

A generic signature processor can determine the mode of a signature by
examining the Reference element's attributes and the child element(s) of the
Transforms element. If the URI or Type attributes are present,
"Compatibility Mode" is used. If the URI and Type attributes are not
present, and the Transforms element contains exactly one Transform element
with an Algorithm of
"http://www.w3.org/2010/xmlsec/xmldsig2#newTransformModel", then "2.0 Mode"
is used. Otherwise, "Compatibility Mode" is used.

4.4.3.2 The URI Attribute

The URI attribute MUST be omitted for "2.0 Mode" signatures. If the
attribute is omitted for a "Compatibility Mode" signature, then 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.

At most one "Compatibility Mode" Reference element without a URI attribute
may be present in any particular SignedInfo, or Manifest. However, any
number of "2.0 Mode" Reference elements may be present.

The remainder of this section applies only to "Compatibility Mode".

<insert original section 4.4.3.1 here, minus the fifth paragraph>

4.4.3.3 The "Compatibility Mode" Reference Processing Model

<insert original section 4.4.3.2 here>

4.4.3.4 "Compatibility Mode" Same-Document URI-References

<insert original section 4.4.3.3 here>

4.4.3.5 The Transforms Element

The optional Transforms element contains an ordered list of Transform
elements; these describe how the signer obtained the data object that was
digested. Each Transform consists of an Algorithm attribute and content
parameters, if any, appropriate for the given algorithm. The Algorithm
attribute value specifies the name of the algorithm to be performed, and the
Transform content provides additional data to govern the algorithm's
processing of the transform input. (See Algorithm Identifiers and
Implementation Requirements (section 6).)

If the Transforms element is present and contains exactly one Transform
element with an Algorithm of
"http://www.w3.org/2010/xmlsec/xmldsig2#newTransformModel", then "2.0 Mode"
is used. Otherwise, "Compatibility Mode" is used. The following two sections
detail the use of this element in each case.

	Schema Definition:
	(as before)

4.4.3.6 The "2.0 Mode" Transforms Processing Model

In this mode, the Transforms element is required, and MUST contain exactly
one Transform element with an Algorithm of
"http://www.w3.org/2010/xmlsec/xmldsig2#newTransformModel". Legacy
implementations will react to this as an undefined Transform algorithm and
report failure in the fashion that is normal for them.

The semantics of the "2.0 Mode" Transform are such that its input is
determined solely from within the Transform itself rather than via the
surrounding Reference element. The output is guaranteed to be an octet
stream. All further processing is defined by the new transform algorithm
itself and is self-contained (see section 

4.4.3.7 The "Compatibility Mode" Transforms Processing Model

In this mode, the Transforms element is optional and its presence indicates
that the signer is not signing the native (original) document but the
resulting (transformed) document. (See Only What is Signed is Secure
(section 8.1).)

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.

As described in The "Compatibility Mode" Reference Processing Model (section
4.3.3.3), some transforms take an XPath node-set as input, while others
require an octet stream. If the actual input matches the input needs of the
transform, then the transform operates on the unaltered input. If the
transform input requirement differs from the format of the actual input,
then the input must be converted.

Some Transforms may require explicit MIME type, charset (IANA registered
"character set"), or other such information concerning the data they are
receiving from an earlier Transform or the source data, although no
Transform algorithm specified in this document needs such explicit
information. Such data characteristics are provided as parameters to the
Transform algorithm and should be described in the specification for the
algorithm.

Examples of transforms include but are not limited to base64 decoding
[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.
"Compatibility Mode" Transform Algorithms (section 6.2.11) defines the list
of standard transformations for "Compatibility Mode" signatures.

4.4.3.8 The DigestMethod Element

DigestMethod is a required element that identifies the digest algorithm to
be applied to the signed object. This element uses the general structure
here for algorithms specified in Algorithm Identifiers and Implementation
Requirements  (section 6.1).

For "2.0 Mode" signatures, the result of processing the Reference is an
octet stream, and the digest algorithm is applied to the resulting data
octets.

For "Compatibility Mode" signatures, if the result of the URI dereference
and application of Transforms is an XPath node-set (or sufficiently
functional replacement implemented by the application) then it must be
converted as described in the "Compatibility Mode" Reference Processing
Model (section  4.4.3.3). 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:
	(as before)

4.4.3.9 The DigestValue Element

<insert original section 4.4.3.6 here>

.....


6.2.7 "2.0 Mode" Transform and Canonicalization

In "2.0 Mode" signatures, the use of extensible Transform algorithms is
replaced with a construct that combines selection of the content to sign,
and canonicalization, into a single unit with an extensible syntax for
reference and selection processing.

The Transform element consists of a required ds2:Selection element followed
by an optional CanonicalizationMethod element.

The Algorithm attribute MUST be set to
"http://www.w3.org/2010/xmlsec/xmldsig2#newTransformModel".
 
6.2.7.1 The ds2:Selection Element

The ds2:Selection element describes the data being signed for a "2.0 Mode"
signature reference. The content and processing model for this element
depends on the value of the required Type attribute, which identifies the
selection algorithm in use. The values of the required URI and optional
Subtype attributes are used as input to this selection algorithm.

The result of processing the ds:Selection element MUST be one of the
following:

* a set of one or more element nodes (such that no element is a descendant
of any other), and a set of zero or more exclusions consisting of element
and/or attribite nodes

* an octet stream

In the former case, a canonicalization algorithm compatible with these
inputs MUST be applied to produce an octet stream for the digest algorithm.
The contents of the sibling CanonicalizationMethod element, if present, will
specify the algorithm to use, and supply any non-default parameters to that
algorithm. If no sibling CanonicalizationMethod element is present, then the
XML Canonicalization 2.0 Algorithm [ref] MUST be used with no non-default
parameters.

In the latter case, no further processing is applied to the resulting octet
stream, which will be supplied directly to the digest algorithm.

	Schema Definition:
	<xs:element name="Selection" type="ds2:SelectionType"/>
	<xs:complexType name="SelectionType">
	    <xs:sequence>
	        <xs:any namespace="##any" minOccurs="0"
maxOccurs="unbounded"/>
	    </xs:sequence>
	    <xs:attribute name="URI" type="xs:anyURI" use="required"/>
	    <xs:attribute name="Type" type="xs:anyURI" use="required"/>
	    <xs:attribute name="Subtype" type="xs:string" use="optional"/>
	</xs:complexType>

6.2.8 "2.0 Mode" Selection Algorithms

A ds2:Selection algorithm has two explicit input parameters, a required URI
and an optional Subtype. The output MUST consist of one of the options
described in section 6.2.7.1.

6.2.8.1 "XPath Subset"

Identifiers:
	"http://www.w3.org/2010/xmlsec/xmldsig2#xpath-subset"

<incorporate material from 2.0 draft, but I suggest a simplified set of
rules for the URI attribute, specifically that #xpointer is dumped, and the
rules for bare fragments be altered to get rid of the step that dumps
comment nodes>

6.2.8.2 "Binary"

Identifiers:
	"http://www.w3.org/2010/xmlsec/xmldsig2#binary"

<incorporate material from 2.0 draft, discussing use of Subtype for the two
approaches defined there, and referring back to section 6.2.8.1 for the
XPath syntax>

6.2.9 "2.0 Mode" Canonicalization Algorithms

The result of evaluating a ds2:Selection algorithm, when not an octet
stream, is not compatible with the input model of "Compatibility Mode"
Canonicalization Algorithms; instead, a "2.0 Mode" Canonicalization
algorithm MUST be used.

6.2.9.1 "Canonical XML 2.0"

Identifier: 
	TBD

The normative specification of Canonical XML 2.0 is [XML-C14N-20]. The
algorithm requires as input a set of one or more element nodes (such that no
element is a descendant of any other), and a set of zero or more exclusions
consisting of element and/or attribite nodes.

The algorithm produces an octet stream as output.

Canonical XML 2.0 takes a number of additional parameters to customize the
behavior of the algorithm. See [XML-C14N-20] for the description of these
parameters and the XML syntax for use with this specification.

6.2.10 "Compatibility Mode" Canonicalization Algorithms

<insert original section 6.2.7 here>, perhaps with altered intro text?

6.2.11 "Compatibility Mode" Transform Algorithms

<insert original section 6.2.8 here>, perhaps with altered intro text?

Received on Monday, 21 December 2009 00:31:26 UTC