ietf
[Top] [All Lists]

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

2012-06-11 06:05:07
Hello Stephen,

As Barry has suggested, I'm removing apps-discuss(_at_)ietf(_dot_)org 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.