XML-Signature Editorial Conventions

WG Proposal

This version:: /Drafts/xmldsig-ed-conventions-19991019.html
Authors: Donald Eastlake <dee3@torque.pothole.com>; Joseph Reagle <reagle@w3.org>

This document describes possible editorial conventions used throughout the core specification. Letters are used to designate steps or categories, numbers are used to designate options the WG should choose.

Simple Questions

Elements

Do people prefer Element Names as:

<DigestAlgorithm>...</DigestAlgorithm>
<DigestValue>...</DigestValue>
<Digest>
<Algorithm>
<Value>
</Digest>

If people prefer #2, we can change SignatureValue to SignatureResult since it is a special case.

Defaults

There are three ways to express semantics, via explicit representation in the XML syntax, a default declaration in the DTD, or via the natural language in the specification. Do people prefer:

Semantics should be communicated via explicit syntax whenever possible possible.
Syntax should be as brief as possible.

Properties:

Do we call things algorithm, name, or type?

Reagle's Second Proposal

If you use the term "Value" or "Algorithm" in the element name, then the content of that element must be a literal value or algorithm designation.
(Consequently) If you need to nest other content in an element, it must not contain the term Value or Algorithm in its name.
Otherwise, all URIs should be listed as an attribute value.

<Signature xmlns="http://www.w3.org/1999/10/signature-core">
<SignedInfo>
    <CanonicalizationAlgorithm>null</CanonicalizationAlgorithm>
    <SignatureAlgorithm>urn:ietf:dsaWithSHA-1</SignatureAlgorithm>
    <ObjectReference HREF="http://www.iet.org"/>
      <Type>text/html; charset="us-ascii"</Type>
      <DigestValue Algorithm="urn:ietf:sha-1"
         Encoding="urn:ietf:base64">ab3234c34</DigestValue>
    </ObjectReference>
</SignedInfo>
<SignatureValue Encoding="urn:ietf:base64">ab3234c34</SignatureValue>
<KeyInfo>
    <keyname>Solo</keyname>
</keyinfo>
</Signature>

Algorithm Specification: Parameters/Value

The following letters designated classes of syntax structures for which we want conventions. The numbers represent potential options the WG should select.

Algorithm Specification
1. As attribute <Canonicalization Algorithm="urn:...">...</Canonicalization>
2. As element <Canonicalization><Algorithm>urn:...</Algorithm>...</Canonicalization>
3. As element name <CanonicalizationAlgorithm>...</CanonicalizationAlgorithm>
Algorithm Parameters (for Transforms & possibly others)
1. Just use element content <Foo>1</Foo>
2. Use typed elements <Foo><Integer>1</Integer></Foo>
3. Use Parameter element with URI type attribute
  <Foo><Parameter type="urn:...">1</Parameter></Foo>
4. Use Parameter element with Type & Value elements
  <Foo><Parameter>
  <Type>urn:...</Type>
  <Value>1</Value>
  </Parameter></Foo>
Algorithm Parameter Encodings
1. Use a fixed encoding without choice (such as base64), works for any B
2. Use an attribute, works for any B option, example
  <Foo><Parameter type="urn:..." encoding="urn:...">93kv0w=</Parameter></Foo>
3. Use an element, works only for B.4
  <Foo><Parameter><Type>urn:...</Type>
  <Encoding>urn:...</Encoding><Value>93kv0w=</Value>
  </Parameter></Foo>
Algorithm Output Value (for Digest & Signature)
1. Just use element content <SignatureValue>ab2234c</SignatureValue>
2. Use Value element <Signature><Value>ab2234c</Value></Signature>
Algorithm Output Encodings
1. Use a fixed encoding, works for any D option
2. Use an attribute, works for any D option, for example
  <Signature><Value encoding="urn:...">...</Value></Signature>
3. Use an element, works only for D.2
  <Signature><Encoding>urn:...</Encoding><Value>...</Value></Signature>
Parameters and Value
If there are cases where an algorithm has both parameters and a value, which I think is reasonable, this argues against B.1 and D.1.
Algorithm Granularity
1. Suites as one algorithm (i.e., compound Algorithm names, like RSA-SHA1, can occur)
2. Orthogonal specification (i.e., simple Algorithm names but Algorithms occur as Parameters to other Algorithms)

Eastlake comments:

A simple decision that URI's appear at attributes would tend to select A.1 and B.3 and eliminate C.3 and E.2. Similarly a decision that URI's appear as element content would tend to select A.2 and B.4 and eliminate C.2 and E.2.
As long as we permit user defined algorithms, there is no way to stop someone from using G.1 and as long as we allow parameters, there is not way to stop someone from using G.2 although you can make G.2 a bit less convenient, depending on your parameter syntax. So the question is really just for the algorithms we specify in the WG documents. (Eastlake: There are arguments on both sides. This is a religious issue. I have my own opinions but we will go with the WG consensus.)

Reagle's 3 Simple Rules

1. Reserve use of quoted-attributes for HREFs, identifiers, namespaces, and xlinks.

2. Simple name/value pairs that describe something then use an element with content

3. If a name/value pair needs to be further qualified, or you want its content model to be open, then do not use its content for a value.

The resulting syntax under these productions is (notice the ObjectReference HREF):

<Signature xmlns="http://www.w3.org/1999/10/signature-core">
<SignedInfo>
    <CanonicalizationAlgorithm>null</CanonicalizationAlgorithm>
    <SignatureAlgorithm>urn:ietf:dsaWithSHA-1</SignatureAlgorithm>
      <ObjectReference HREF="http://www.iet.org"/>
        <Type>text/html; charset="us-ascii"</Type>
        <Digest>
          <Algorithm>urn:ietf:sha-1</Algorithm>
          <Encoding>urn:ietf:base64</Endoding>
          <Value>ab3234c34</Value>
    </Digest>
    </ObjectReference>
</SignedInfo>
<SignatureValue>
    <Encoding>urn:ietf:base64</Endoding>
    <Value>ab3234c34</Value>
</SignatureValue>
<KeyInfo>
    <keyname>Solo</keyname>
</keyinfo>
</Signature>

It results in slightly more verbose syntax, that might be alleviated by an exception to rule 1: "However, if you only have one value/name pair that you wish to associate with an element, you may place it as a quoted-attribute&value" but I was trying to be very clean above.

Anything that is likely to be defaulted, should be an attributed.

If the only value was going to be a single literal, it should be an attribute.

If the value of something needs to be further expanded, it should be represnted

Eastlake's Defaults

Attributes

Eastlake's Proposal:
Generally, an implied default of the most common value in the immediate future should be provided to shorten signatures. Note that providing such a default does not lengthen any case where the value is explicitly provided.
1. If a default value exists for an attribute when it is missing it will be specified in the DTD.
2. If there is no default value and the attribute is not mandatory, a brief comment should be included in the DTD as to the effect if and/or conditions under which it is omitted.
3. If an attribute is given a null value, it should have the natural meaning of a null value for that attribute or, if there is no such meaning, be treated as an error.
4. The textural description of the attribute should reflect the information in the DTD and expand as appropriate.

Elements

Eastlake's Proposal:
1. If an element is not required to be present, a brief comment should be included in the DTD as to the effect if and/or conditions under which it is omitted.
2. Similarly, if an element is not specified as EMPTY but may have no content, a brief comment should be included in the DTD as to what that means.
3. The textural description of the element should reflect the information in the DTD and expand as appropriate
4. The textural description of the attribute should reflect the information in the DTD and expand as appropriate.
5. Generally, the absence of an element which would cause an action implies that no action is taken and the absence of an element that provides or overrides information implies that the information is null or not overridden, respectively.
6. No content for an element has the natural meaning for what the content means is defined to have such a meaning when null. If this is the case, that meaning should be pointed out. If no content is not a meaningful value for the content of an element, it may be specified to mean the value most likely to be desired for the content of that element in the immediately foreseeable future, if any. Otherwise no content for the element should be an error.