Re: APPSDIR review of draft-farrell-decade-ni-07 (minor editorial)

["Martin J. Dürst" <[e-mail]>]

Hello Stephen,

As Barry has suggested, I'm removing [e-mail] to reduced 
cross-posting. I'm going to split my response into several installments, 
hopefully separating the less contentious issues from the more 
contentious ones, and starting with the former ones.

Also, I want to apologize for the delays here, related to "day job" duties.

On 2012/06/05 20:11, Stephen Farrell wrote:
>
> Hi Martin,
>
> First, thanks for the speedy and thorough review. Some
> good points made, some with which I strongly disagree,
> but thrashing stuff like that out is part of the point
> of the reviews.
>
> On 06/05/2012 10:42 AM, "Martin J. Dürst" wrote:

>> Minor editorial issues:
>>
>> Introduction: It would be good to have a general reference to hashing
>> (for security purposes) for people not utterly familiar with the subject.
>
> Disagree. If I added that I could reasonably be asked to introduce
> URIs for the security folks. Serious and pointless ratholes would ensue.

Okay.

>> Intro: After reading the whole document, the structure of the Intro
>> seems to make some sense, but it didn't on first reading (where it's
>> actually more important). The main problem I was able to identify was
>> that after a general outlook in paragraph 1, the Intro drops into a list
>> of examples without saying what they are good for. I suggest to, after
>> the sentence "This document specifies standard ways to do that to aid
>> interoperability.", add a sentence along the lines: "The next few
>> paragraphs give usage examples for the various ways to include a hash in
>> a name or identifier as they are defined later in this document.". It
>> may also make sense to further streamline the following paragraphs, so
>> that it is clearer which pieces of text refer each to one of the
>> "standard ways".
>>
>> There are two instances of the term "binary presentation". Looking
>> around, it seems that they are supposed to mean the same as "binary
>> format". Please replace all instances of "binary presentation" with
>> "binary format" to avoid misunderstandings and useless seach time.
>>
>> Section 3: "A Named Information (ni) URI consists of the following
>> components:": It would be good to know exactly where the list ended. One
>> way to do this would be to say "consists of the following nine components".
>
> Those look reasonable. Will see if the changes work out.

The change that I have seen in your pre-draft for the above three items 
look good.


>> Section 3: "Note that while the ni names with and without an authority
>> differ syntactically, both names refer to the same object if the digest
>> algorithm and value are the same.": What about cases with different
>> authority? The text seems to apply by transitivity, but this may be easy
>> to miss for an implementer. I suggest changing to: "Note that while ni
>> names with and without an authority, and ni names with different
>> authorities, differ syntactically, they all refer to the same object if
>> the digest algorithm and value are the same.".
>
> Sure.

Okay.

>> Section 3: "Consequently no special escaping mechanism is required for
>> the query parameter portion of ni URIs.": Does this mean "no escaping
>> mechanism at all"? Or "nothing besides %-encoding"? Or something else?
>> Please clarify.
>
> I wish I knew:-) What do you think is right here? (Honestly,
> input on this would be appreciated.)

(In your internal draft, you removed the paragraph just before this one, 
and now the "Consequently" doesn't make any sense anymore.)

One possibility here is to remove anything about encoding, and have 
people check in RFC 3986, but I guess you wanted to help the reader 
here, so I'd propose something along the following lines (replacing the 
"Consequently" paragraph, and also in some sense the paragraph before 
that you already removed):

<<<<
Escaping of characters follows the rules in RFC 3986. This means that 
%-encoding is used to distinguish between reserved and unreserved 
functions of the same character in the same URI component. As an 
example, an ampersand ('&') is used in the query part to separate 
attribute-value pairs; an ampersand in a value therefore has to be 
escaped as '%26'. Note that the set of reserved characters differs for 
each component, as an example, a slash ('/') does not have any reserved 
function in a query part and therefore does not have to be escaped. 
However, it can still appear escaped as '%2f' or '%2F', and 
implementations have to be able to understand such escaped forms.
Also note that any characters outside those allowed in the respective 
URI component have to be escaped.
<<<<



>> Figure 3: the "=" characters of the various rules should be aligned as
>> much as possible to make it easier to scan the productions (see
>> http://tools.ietf.org/html/rfc3986#appendix-A for an example).
>
> Ack.

Great.

>> Section 3:
>>              unreserved  = ALPHA / DIGIT / "-" / "." / "_" / "~"
>>                  ;  directly from RFC 3986, section 2.3
>>                  ; "authority" and "pct-encoded" are also from RFC 3986
>> Please don't copy productions. Please don't copy half (or one-third,
>> actually) of the productions you use, and reference the rest. Please
>> don't say what productions you copy from where in a comment, and even
>> less in a comment for an unrelated production. Please before the ABNF,
>> say which productions are used from another spec.
>
> We got contrary advice from elsewhere (can't recall where right now;-).
> I'll let Barry (as sponsoring AD) just tell us his preference and go
> with that if that's ok.

If you want to do it in a different way, you should at least be 
consistent. That would mean to also copy "authority" and "pct-encoded". 
The later is easy, but the former would really be too much. That's why 
I'd kick out "unreserved", too.


>> Section 4:
>>     The HTTP(S) mapping MAY be used in any context where clients without
>>     support for ni URIs are needed without loss of interoperability or
>>     functionality.
>> This is difficult to understand. If some new functionality is proposed,
>> it's usually a client *with* the new functionality that's needed, not
>> one without. Also, the "without loss of interoperability or
>> functionality" is unclear: Sure if ni isn't supported, there's a loss in
>> interoperability. So I suggest to rewrite this as:
>>     The HTTP(S) mapping MAY be used in any context where clients with
>>     support for ni URIs are not available.
>
> Sure.

Great. But in your internal draft, the period at the end of the sentence 
is now missing. (unless there's a bug in the diff)


>> (but see also the comment in minor technical issues)
>>
>> Section 6: "binary format name": Why 'name'? Why not just "binary
>> format"? The later is completely clear in the context of the document or
>> together with an indication of the document; for something that can be
>> used independently, even "binary format name" isn't enough.
>
> I don't get the problem with that.

You had "binary presentation", and changed that to "binary format" as 
per my suggestion. This is a very similar suggestion to align 
terminology. In the later half of the above comment, I was just trying 
to speculate about reasons for the difference, an the only reason I came 
up with was that it would be good to have a longer term that could be 
used independently outside the document.


>> Section 6: "suite ID": The word "suite" seems out of place here. In the
>> general use of the term, it refers to "a group of things forming a unit
>> or constituting a collection" (see
>> http://www.merriam-webster.com/dictionary/suite). A good definition that
>> works for the uses I'm familiar with in digital security would be "An
>> algorithm suite is a coherent collection of cryptographic algorithms for
>> performing operations such as signing, encryption, generating message
>> digests, and so on."
>> (http://fusesource.com/docs/framework/2.4/security/MsgProtect-SOAP-SpecifyAlgorithmSuite.html;
>> disclaimer: I'm in no way a SOAP fan). The use here is not for a
>> collection, but for a single truncated-length variant of a single hash
>> algorithm. I seriously hope you can find a better name.
>
> That's a don't-care for me. I think suite is fine, but could
> take other terms (so long as its not "algorithm"). Suite could
> be justified since we have alg+truncation here, but like I
> said I'd be fine to change, if a good suggestion is made.

What about "Truncated Hash ID" or "Hash Truncation ID" or some such? I'm 
open to other ideas, too.


>> Section 6: "Note that a hash value that is truncated to 120 bits will
>> result in the overall name being a 128-bit value which may be useful
>> with certain use-cases.": This left me really wondering: Is there
>> something magic to 128 bits in computer/internet security? What are the
>> "certain use cases"? Or is this just an example to make sure the reader
>> got the relationships, and it could have been as well "Note that a hash
>> value that is truncated to 64 bits will result in the overall name being
>> a 72-bit value which may be useful with certain use-cases." (or whatever
>> other value that's registered in section 9)?
>
> Bit of both. I believe the core WG are keen to end up with a 128 bit
> binary value as their preferred option.

Is there a way to word this that doesn't leave the reader wondering how 
she is supposed to understand this?

>> Section 7: Just for the highly unfortunate case that this doesn't
>> disappear, it would be very helpful if the presentation of this section
>> paralleled section 3.
>
> Disagree. Different requirements, different URIs, different
> presentation. I don't think there's a real problem here.

I'll address the "Different requirement" in a separate thread. In 
general, I'd expect that if a draft defines 2 of the same thing (e.g. 
two mime types,...), that it streamlines the presentation as far as 
possible. That this hadn't been done was part of the reason for my 
impression that this draft got patched together. But I think we should 
put of streamlining, because I hope that section 7 will disappear anyway 
:-).


>> Section 7: "contain the ID value as a UTF-8 encoded decimal number": I'm
>> an internationalization expert with a strong affection for UTF-8, but
>> even for me, this should be "contain the ID value as an ASCII encoded
>> decimal number".
>
> Fine.
>
>>
>> Section 9: The registration templates refer to sections. This is fine
>> for readers of the draft, but not if the template is standalone. I
>> suggest using a format such as that at
>> http://tools.ietf.org/html/rfc6068#section-8.1, which in draft stage may
>> look e.g. like
>> http://tools.ietf.org/html/draft-duerst-eai-mailto-03#section-8.1.
>
> Will take a peek. Not sure I agree. (Nor disagree:-)

Okay, let me know when you have made up your mind.

>> Section 9.3: "Assignment of Well Known URI prefix ni" and later (and
>> elsewhere in the draft) "URI suffix": Are we dealing with a prefix or a
>> suffix here?
>
> Will take a peek.

For your information, the registry is just named "Well-Known URIs" 
(http://www.iana.org/assignments/well-known-uris/well-known-uris.xml). 
Other drafts 
(http://tools.ietf.org/html/draft-daboo-srv-caldav-10#section-9.1, 
http://tools.ietf.org/html/draft-daboo-srv-caldav-10#section-9.2, 
http://tools.ietf.org/html/draft-ietf-core-link-format-14#section-7.1, 
http://tools.ietf.org/html/rfc6415#section-6.1, 
http://tools.ietf.org/html/rfc6415#section-6.2) have neither "prefix" 
nor "suffix" in the section title. I suggest to follow these, it will be 
less confusing.


>> Section 9.4: "This registry has five fields, the binary suite ID,...":
>> Better to remove the word "binary", because the actual number is decimal.
>
> Ack.
>
>>
>> Section 9.4: "The expert SHOULD seek IETF review before approving a
>> request to mark an entry as "deprecated."  Such requests may simply take
>> the form of a mail to the designated expert (an RFC is not required).
>> IETF review can be achieved if the designated expert sends a mail to the
>> IETF discussion list.  At least two weeks for comments MUST be allowed
>> thereafter before the request is approved and actioned.": I'm at a loss
>> to see why asking the IETF at large is a SHOULD, but if it's done, then
>> the two weeks period is a MUST.
>
> I don't get your comment. The two weeks is a MUST already.

This combination of SHOULD and MUST just doesn't feel right to me. Let 
me try with a different subject area which may make it easier to get my 
point.

What would you think if a document said something: "The expert SHOULD 
donate money to the IETF. If the expert donates money, s/he MUST donate 
at least $200."

As this example hopefully shows, MUSTs conditioned by SHOULDs don't 
really make sense. Or is this really just me ?-)

And let me give another try. Let's assume the expert wants to make a 
decision after one week, but still inform the IETF discussion list. She 
can just send a mail to that list saying "This is not a formal review 
according to Section 9.4 of RFC YYYY, but I'm planning to deprecate this 
entry in a week unless I hear good reasons to do otherwise." Logically 
speaking, that would be following the RFC, and shows that the MUST 
doesn't make sense, because it can't force anything.


>> Section 9.4: The registry initialization in Fig. 8 refers to RFC4055
>> many times. But RFC 4055 does in no way define SHA-256. It looks like
>> the actual spec is http://tools.ietf.org/html/rfc4055#ref-SHA2 (National
>> Institute of Standards and Technology (NIST), FIPS 180-2: Secure Hash
>> Standard, 1 August 2002.) I think this should be cited, in particular
>> because there is a "Specification Required" requirement, and this sure
>> should mean that there is a Specification for the actual algorithm, and
>> not just a specification that mentions some labels. So using RFC4055 as
>> a reference could be taken as creating bad precedent.
>
> I guess so. Good catch.

Great.

>> Section 9.4: "The designated expert is responsible for ensuring that the
>> document referenced for the hash algorithm is such that it would be
>> acceptable were the "specification required" rule applied.": Why all
>> this circumscription? Why not just say something like: "The designated
>> expert is responsible for ensuring that the document referenced for the
>> hash algorithm meets the "specification required" rule."
>
> Honestly? I can't recall:-) Will change unless I do remember.

Okay.

>> Nits:
>>
>> Author's list: Last time I heard about this, there was a general limit
>> of 5 authors per RFC. I'm not sure whether this still exists, and what'd
>> be needed to get around it, but I just wanted to point out that this may
>> be a potential problem or additional work (hoops to get through).
>>
>> Intro: "Since, there is no standard" ->  "Since there is no standard"
>>
>> Intro: "for these various purposes" ->  "for these purposes" or "for
>> various purposes" (the indefinite 'various' is incompatible with the
>> definite 'these').
>>
>> "2.  Hashes are what Count" ->  "2.  Hashes are what Counts" (the former
>> may look logically correct, but 'what' requires a singular verb form.
>>
>> Section 2: "the left-most or most significant in network byte order N
>> bits from the binary representation of the hash value" ->  "the left-most
>> (or most significant in network byte order) N bits from the binary
>> representation of the hash value" or "the left-most N bits, or the N
>> most significant bits in network byte order, from the binary
>> representation of the hash value" (the current text is virtually
>> unparsable).

You seem to disagree with this, but every time I try to read the above 
sentence, I have to take two or three attempts. And given my long-time 
training in German and Japanese, I have to admit that I'm quite used to 
long and convoluted sentences :-).


>> Figure 1: The 0x notation is never explained. A short clause or pharse
>> is all that would be needed, but it would be better if this were spelled
>> out.
>>
>> Section 3, Query Parameter separator: "The query parameter separator
>> acts a separator between" ->  "The query parameter separator acts *as* a
>> separator between".
>>
>> Section 3, Query Parameters: "A tag=value list of optional query
>> parameters as are used with HTTP URLs" ->   "A tag=value list of optional
>> query parameters as used with HTTP URLs" (or "A tag=value list of
>> optional query parameters as they are used with HTTP URLs").
>>
>> Section 4: "the object named by the ni URI will be available at the
>> corresponding HTTP(S) URL" ->  "the object named by the ni URI will be
>> available via the corresponding HTTP(S) URL" (via stresses the point
>> that this should be done via (sic) redirection)
>>
>> Section 4: "so there may still be reasons to use" ->  "so there can still
>> be reasons to use" (better to use can because non-normative; the
>> document otherwise does a good job on this)
>>
>> Section 10: "Note that fact that" ->  "Note the fact that", or much
>> better: "Note that".
>
> Those look ok or are nits in any case.

Other than indicated above, I'm fine with the changes for these 
issues/nits that you have made (or not made) in your internal copy.


Regards,    Martin.

(more replies tomorrow)

> Thanks again for the thorough review even though we disagree as
> to the main point.
>
> Cheers,
> Stephen.
>
>
>>
>>
>> Regards,     Martin.
>>
>>
>>
>