W3C home > Mailing lists > Public > w3c-ietf-xmldsig@w3.org > July to September 1999

importing terminology in "XML-Signature Requirements"

From: by way of <connolly@w3.org>
Date: Fri, 16 Jul 1999 14:23:34 -0400
Message-Id: <3.0.5.32.19990716142334.00952280@localhost>
To: "IETF/W3C XML-DSig WG" <w3c-ietf-xmldsig@w3.org>
Some review comments on
	XML-Signature Requirements 
	W3C Working Draft 1999-June-23 
	http://www.w3.org/TR/1999/xmldsig-requirements-990623.html

It seems to use/import terminology liberally from other documents,
but not altogether consistently.

In section 1. "Introduction" the phrase "XML compliant syntax"
seems to borrow from the XML spec, but the XML spec
defines no such term. The two related terms that the XML 1.0
spec does define are

	XML document
http://www.w3.org/TR/1998/REC-xml-19980210#dt-xml-doc
	aka well-formed XML document
	aka conforming XML document

	XML processor
http://www.w3.org/TR/1998/REC-xml-19980210#dt-xml-proc
	aka conforming XML processor
	aka non-validating XML processor

I suggest "XML based" in place of "XML compliant" since
"compliant" suggests an imported definition, but that's not
what's going on.

The terminology for the thing that gets signed is odd too:
	"signatures on Web resources and portions of protocol
	messages (anything that can be referenced by a URI)"

The terms "Web resource" and "URI" seem to be imported from
somewhere, but it's not clear where.

The term "Web resource" is used fairly consistently with
the usage in the URI syntax Draft Standard:

	"A resource can be anything that has identity."
	-- http://www.ics.uci.edu/pub/ietf/uri/rfc2396.txt

but I don't think that identity is an essential property
of a thing that you want to sign. The essential property
of a thing that you want to digitally sign is that it's
(expressible as) a sequence of bytes.

So I'd suggest replacing that "signatures on Web resources"
with "signatures on digital content." So:

	... signatures on digital content: content of Web resources,
	portions of protocol messages, etc.

(editorial: period missing at end of that para)

This impacts section 2. "Design Principles and Scope" too:

	The XML-Signature specification will describe how to
	/-a-/ digitally sign /+the content of+/ a Web resource ...

Hm... "the content of a Web resource" is more exlusive
than "digital content"; it doesn't seem to include
"portions of protocol messages." So more wordsmithing may be
necessary.

You might consider citing the Web Characterization termonology
spec for the term "Web resource"
http://www.w3.org/1999/05/WCA-terms/
Hmm... never mind: it imports the term from rfc2396.

More impact:
	associates the cryptographic signature value with
	/+the content of+/ Web resources using XML markup.

(editorial: "signature value"? why not just "signature"?)


This terminology I find just baffling:

	"More than one signature may exist over any resource."

Given some content, a key, and a signature algorithm, surely
that determines exactly one signature. That's the whole point, no?
So I'm puzzled as to what "exist" really means. It could
mean any of these:
	(a) more than one party may sign a piece of content
	(b) more than one signature algorithm may be used
		for any XML-signature
	(c) since the content of a resource may change over time
	(or due to language preference, etc.)
	different signatures can be associated with different
	contents of a resource
Please be more clear which, if any, of these is meant.


Another misleading reference:
	In conjunction with XML facilities (including packaging)
That seems to imply that packaging facilities are part
of the XML 1.0 spec that was cited above. Not so. If you mean
to refer to xml packaging facilities-to-be, please be more clear,
as that represents a dependency, which is very important to
call out in a requirements document. The requirement
	5.XML-Signatures must be able to apply to the original
	version of an included/encoded resource.
implies that you _do_ depend on an XML packaging mechanism
(or at least an XML datatyping mechanism for labelling
base64-encoded stuff as such).

More in the scope list...
	prior to handing data to a XML-Signature application.
the term "XML-Signature application" sprung out of nowhere.
I suggest you define it before the list. The definition
seems to be "an implementation of the XML-Signature specification."


Talking about a piece of code in any way other than behaviour
that's observable from the outside is counterproductive in
specs. In stead of:
	An XML-Signature application must be able to use and understand
I suggest you just write:
	The XML-Signature specification may depend on:

I don't understand what
	Applications may optionally choose C14N
        algorithms which do or do not process namespaces within
	XML content. 
means. I suggest you expand with an example after the list or
something.

"signature manifest" is another term that springs up unexpectedly:

	Applications will use XLink locators within the
               signature manifest to reference signed resources.

(I have a substantive objection to using XLink locators,
but I'll write about that separately.)

Under 3. "Requirements"

There's only one RDF data model, so

	The XML-Signature data structures will be predicated
	on /-an-//+the+/ RDF data model [RDF]

Hmm... "predicated on" seems wordy, but I don't have a more
plain-english suggestion.

Here again the bit about what you're signing:

	2. XML-Signatures can be applied to any Web resource

I'm having trouble coming up with a suggested replacement.
I suggest you try to just draft that requirement again.
It introduces terms unexpectedly; e.g. "the manifest".

There's a distinction lost here:
	3.XML-Signatures are first class objects themselves and
           consequently can be referenced and signed.

XML-signatures can be signed iff they're digital content;
and they are, so they can be. I think this requirement
talks about being referenceable, but I'm not sure I understand it.


Under Format:
	1.An XML-Signature is XML. [Charter] 
huh? That sort of looks like you're saying
	An XML-Signature is an XML document
but I doubt you mean that. I think you mean:
	An XML-Signature is an XML element
but I'm not sure.

This seems to import a notion of XML document type
that's not in the XML 1.0 specification:
	An XML document of a certain type must still be
	recognizable as its original type when signed.
I think you mean that if a document bears a certain
<!DOCTYPE ...> you must be able to sign it without changing
the <!DOCTYPE ...>. I think that's an impossible requirement
in the general case. Could you explain more clearly what
you mean here?




Editorial: please don't use URLs as user interface.
Use titles as link anchors. i.e. in stead of

	<cite>_title_</cite>
	<a href="_address_">_address_</a>

write:
	<cite><a href="_address_">_title_</a></cite>
or, if the cited document bears an institutionalized address,
include that ala:

	<cite><a href="_address_">_title_</a></cite>
	<tt>_address_</tt>

and I think that you mean to cite the particular dated
specs, not any future revisions of them.

e.g. change
	http://www.w3.org/TR/REC-xml-names
to
	http://www.w3.org/TR/1999/REC-xml-names-19990114

-- 
Dan Connolly, W3C
http://www.w3.org/People/Connolly/
tel:+1-512-310-2971 (office, mobile)
mailto:connolly.pager@w3.org (put your tel# in the Subject:)
Received on Friday, 16 July 1999 14:46:09 GMT

This archive was generated by hypermail 2.2.0 + w3c-0.29 : Thursday, 13 January 2005 12:10:06 GMT