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

[Stephen Farrell <[e-mail]>]

Hi Martin,

On 06/11/2012 12:04 PM, "Martin J. Dürst" wrote:
> 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.

No probs.

> 
> 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.
> <<<<

That looks good to me, ta. I've put it in.

>>> 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.

Ok, I've now done a version that tries to copy as much
as possible unmodified from 3986. Let me know if its
right this time:-)

> 
> 
>>> 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)

Now full stopped:-)

>>> (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.

Well, the suite IDs don't have to related to a truncated
hash, but can also be full length. Sticking with suite ID
for now.

>>> 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?

Tweaked. Though I still don't think its at all unclear.

> 
>>> 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
> :-).

Still disagree:-)

> 
> 
>>> 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.

Turns out I disagree.

> 
>>> 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.

Ok, I copied from the core link format.

>>> 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.

I've changed the SHOULD seek IETF review to a MUST. I guess that
makes sense.

> 
> 
>>> 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 :-).

Tweaked.

> 
> 
>>> 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)

Grand. I've updated the working copy at [1] with those changes.

Thanks,
S.

[1] http://down.dsg.cs.tcd.ie/misc/draft-farrell-decade-ni.txt

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