Subject: [Gen-art] Gen-ART review of draft-daboo-srv-caldav-08.txt

From: "Miguel A. Garcia" <[email-masked]>
Date: Wed, 08 Sep 2010 15:25:49 +0200

I have been selected as the General Area Review Team (Gen-ART)
reviewer for this draft. For background on Gen-ART, please see the FAQ at 
http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq

Please resolve these comments along with any other comments you may receive.

Document:  draft-daboo-srv-caldav-08.txt
Reviewer: Miguel Garcia <[email-masked]>
Review Date: 08-Sept-2010
IETF LC End Date: 09-Sept-2010
IESG Telechat date: (if known)

Summary: The document is almost ready for publication as a standards 
track RFC. The reviewer has some minor/editorial comments and questions 
that should be addressed.

I reviewed version 05 of this document, and the concerned I had at that 
time has been properly addressed.

Major issues:

Minor issues:

- Section 4, second paragraph. The text reads:

    A site MAY provide TXT records in addition to SRV records for each
    service.

   I think that the "MAY" word does not make sense written in capital 
letters, because in this case you are giving an operational advice of the 
protocol. This is not the intention of a capitalized "MAY", which is 
supposed to indicate an optional requirement for conformance of the 
protocol. I suggest to replace "MAY" with "may".

- A question on Section 4, 2nd paragraph. The text says how to _use_ the 
existing "context path" with the received "path" in the TXT record. 
First, I am not sure that the word "use" is good enough here. Do you mean 
"replace"? Second, I don't know what is a "context path" and where it is 
defined, so, can you add a reference to a document that defines context 
path? Third, it is not clear to me that even with the two above 
clarifications, there is a unique way to build a new URI with the 
information received in the TXT record. Can you demonstrate that there is 
only one way of creating this URI with the received "path", so that all 
the implementations will obtain the same result?

- Section 6. The title of the section contains the word "Guidelines". To 
me, the word Guideline indicates a suggestion, or pure informative text. 
So, I am surprise to see quite a lot of normative text (see bullet points 
2, 4, etc.). This makes me think that the title is not accurate, and 
perhaps you should talk about "Procedures" rather than "Guidelines".

- Section 6, first paragraph, the text reads:

    This section describes a procedure that CalDAV or CardDAV clients MAY
    use to do their initial configuration based on minimal user input.

This is a relative clause. I don't like to have normative statements 
("MAY") in relative clauses, because normative part of it becomes 
diluted. If you still want to have normative MAY, split the sentence into 
two. My recommendation, you don't need normative, and the "MAY" should be 
written in lower case.

- In Section 6, bullet point 3, the text describes a client making an SRV 
request and receiving SRV and TXT records in a response. So, the client 
receives TXT even when it didn't ask for it. In principle, 
draft-cheshire-dnsext-dns-sd does not recommend the inclusion of TXT 
records when SRV is requested. So, I wonder if there is a real use case 
for this paragraph.

- Section 6, bullet point 5, first paragraph. The text reads:

           Certificate verification MUST
           use the procedure outlined in Section 4 of
           [I-D.saintandre-tls-server-id-check] in regard to verification
           with an SRV RR as the starting point.

I would like to see an explicit active sentence, with a proper subject. 
So, who must do the verification, the client? Then write:

     "The client MUST do a certificate verification by using the 
procedure... "

Nits/editorial comments:

- Abstract. I am missing an explicit mention to "DNS", for example:

    "This specification describes how DNS SRV records, DNS TXT records
    and well-known URIs can be used together or separately to locate..."

- The short title of the I-D, which is visible in the header of every 
page, misses "CardDAV, because it merely reads "SRV for CalDAV".

- Introduction, first paragraph: s/port/port number

- Introduction, third paragraph: s/addition al/additional

- Section 4, 2nd paragraph. Write ".well-known" within quotes to 
facilitate the reading of the text.

- Section 5 talks about the prohibition to servers to locate the actual 
service in the well-known URI. I would suggest to add a bit of 
motivation. Perhaps it is already covered in another document, but still 
it would be good to find out the reason.

/Miguel
-- 
Miguel A. Garcia
+34-91-339-3608
Ericsson Spain

---

From: Cyrus Daboo <[email-masked]>
Date: Wed, 08 Sep 2010 10:38:39 -0400

Hi Miguel,
Thank you for your detailed review.

> protocol. I suggest to replace "MAY" with "may".

In my working copy I have changed "MAY" to "might".

> "replace"?

I think "use" is correct here, as at that point there is no "context path" 
already defined that could be replaced.

> Second, I don't know what is a "context path" and where it is
> path?

Paragraph 5 of the Introduction introduces the term "context path". I am 
not aware of any formal definition of that. Perhaps "service path" would be 
a better term.

> Third, it is not clear to me that even with the two above

There is only one path value specified in the TXT record so there is only 
one way to build the HTTP request-URI (using the SRV host/port and the TXT 
path= values). I don't see where there are "multiple" ways to do that.

> perhaps you should talk about "Procedures" rather than "Guidelines".

I don't want to "insist" that all clients or servers do things exactly in 
the way proscribed. There could be reasons for following slightly different 
approaches (e.g. when out-of-band forms of authentication are used). That 
said changing "Guidelines" to "Procedures" is fine given that the first 
paragraph makes it clear that this procedure is optional.

> two. My recommendation, you don't need normative, and the "MAY" should be

As mentioned in the answer to the previous issue, I want to make it clear 
that the procedure being described is not required. So how about:

   This section describes a procedure that CalDAV or CardDAV clients can
   use to do their initial configuration based on minimal user input. This
   procedure is OPTIONAL, clients can use alternative methods to accomplish
   the appropriate configuration steps.

> records when SRV is requested. So, I wonder if there is a real use case

Actually my intent was that the client needs to do another query for the 
TXT record. So how about changing the text to:

   When an SRV lookup is done and a valid SRV record returned,
   the client MUST also make a query for a corresponding
   TXT record and check for a "path" key in its value.

>      "The client MUST do a certificate verification by using the

Fixed in my working copy.

>     and well-known URIs can be used together or separately to locate..."

Fixed in my working copy.

> page, misses "CardDAV, because it merely reads "SRV for CalDAV".

Fixed in my working copy.

> - Introduction, first paragraph: s/port/port number

I made that change in my working copy for all appropriate instances of 
"port" throughout the document.

> - Introduction, third paragraph: s/addition al/additional

Fixed in my working copy.

> facilitate the reading of the text.

Fixed there and other places for consistency.

> it would be good to find out the reason.

I added a reference to "Section 1.1 of [RFC5785]" to cover that. This 
requirement was imposed by the .well-known registry expert review - prior 
to that it was not explicitly stated.

-- 
Cyrus Daboo

---

From: "Miguel A. Garcia" <[email-masked]>
Date: Thu, 09 Sep 2010 10:46:54 +0200

Hi Cyrus.

See more comments inline. I have delete those comments that do not 
require further discussion.

> already defined that could be replaced.

I not comfortable yet. Look at the text:

    When present, clients MUST use the "path" value as the
    "context path" for the service.

My question is related to the ambiguity of "use". I don't know what "use" 
really means. "Use" could refer to dispose, delete, replace. You have a 
normative strength "MUST" with an ambiguous verb. I can assure you that 
different implementations will "use" in a different way.

I am trying to suggest you something, please verify if this is your 
intention. Do you want to say that:

     When the "path" value is present, clients building a URI MUST use 
the value of the "path" as a "context path" for the service.

> not aware of any formal definition of that. Perhaps "service path" would be

I thought the term could have been defined in some RFC. But since this is 
not the case, the text in Paragraph 5 does not define "context path". So, 
you need to find a formal definition of it, otherwise I don't know how to 
use the "path" as "context path", if I don't know what a "context path" 
is. In principle, I would suggest to inspire in the generic URI syntax 
(RFC 3986?), which describes a "scheme" and a "path". Perhaps you can 
define "context path" as a subset of "path" that has some properties 
(which you would need to enumerate, I don't know which ones they are, 
here is my problem).

> path= values). I don't see where there are "multiple" ways to do that.

This comment is a consequence of the previous ones. If you assume that a 
context path is a subset of the path, do we know which subset of the path 
is the context path all about? If we clarify the definition of context 
path, I think we can clear this comment as well.

> paragraph makes it clear that this procedure is optional.

I understand your comment, I can accept it.

>     the appropriate configuration steps.

Your proposal looks very good.

>     TXT record and check for a "path" key in its value.

Very good proposal. Go ahead with it. Just replace the last sentence:

       "... TXT record and check for the presence of a "path" key in the 
response".

Question, do you need to explicitly say what to do with the "path" key at 
this point in time, or is it obvious? My point is that the word "check" 
is ambiguous and does not indicate what to do with the "path" key value.

/Miguel
-- 
Miguel A. Garcia
+34-91-339-3608
Ericsson Spain

---

From: Cyrus Daboo <[email-masked]>
Date: Thu, 09 Sep 2010 09:53:49 -0400

Hi Miguel,

--On September 9, 2010 10:46:54 AM +0200 "Miguel A. Garcia" 
<[email-masked]> wrote:

>>> First, I am not sure that the word "use" is good enough here. Do you
>>> mean "replace"?
>>
>> I think "use" is correct here, as at that point there is no "context
>> path" already defined that could be replaced.
>

I have changed this text to:

    When present, clients MUST use the "path" value as the "context path"
    for the service in HTTP requests.

In addition, I have added the following as the second sentence in paragraph 
4 of section 1 to define "context path":

    Thus a client needs to be able to determine the complete path
    component of the Request-URI to use in HTTP requests: the "context
    path".

I think the combination of the definition and the additional text to the 
"use" sentence clarify the intent.

>> not aware of any formal definition of that. Perhaps "service path" would
>> be a better term.
>

See above for addition to section 1 to define "context path".

>>> information received in the TXT record. Can you demonstrate that there
>>> is only one way of creating this URI with the received "path", so that
>>> all the implementations will obtain the same result?
>>
>> one way to build the HTTP request-URI (using the SRV host/port and the
>> TXT path= values). I don't see where there are "multiple" ways to do
>> that.
>

There is no "subset" of the path - the "context path" IS the full path. I 
think use of the term "complete path" in the new definition of "context 
path" clarifies that.

>>> - In Section 6, bullet point 3, the text describes a client making an
>>> SRV request and receiving SRV and TXT records in a response. So, the
>>> client receives TXT even when it didn't ask for it. In principle,

OK, text changed as per suggestion.

> is ambiguous and does not indicate what to do with the "path" key value.

Well the next sentence after the text tweaked above is:

    If present, the value of the "path" key is used for the initial 
"context path".

I think that covers it.

FYI Attached is a diff of my current working copy with the last published 
-08 version showing the current proposed changes (this includes one or two 
items from IESG review too).

-- 
Cyrus Daboo

---

From: "Miguel A. Garcia" <[email-masked]>
Date: Fri, 10 Sep 2010 11:53:24 +0200

Hi Cyrus,

I took a look at the diff version, and I think all my comments have been 
properly addressed.

/Miguel

-- 
Miguel A. Garcia
+34-91-339-3608
Ericsson Spain

---

From: Alexey Melnikov <[email-masked]>
Date: Thu, 16 Sep 2010 09:15:07 +0100

> Hi Cyrus.

Hi Miguel,
I was discussing with Cyrus one of the changes that you and him agreed 

>> <[email-masked]>  wrote:
 [...]

>>> perhaps you should talk about "Procedures" rather than "Guidelines".
I think the Section title was changed to Procedures.

> I understand your comment, I can accept it.

I actually think that making this optional is too weak. Implementations 
don't need to claim conformance to this document, so it is already 
optional to implement. But I think that *if* they claim conformance, 
they should implement autoconfiguration as described. In particular they 
need to retrieve SRV/TXT records and use .well-known if TXT record is 
not available.
IMHO, doing anything less would affect interoperability and might defeat 
the purpose of this document.

> Your proposal looks very good.

See my comments above. Personally I would prefer to go the other way and 
change the original MAY to SHOULD.

Any objections?

---

From: "Miguel A. Garcia" <[email-masked]>
Date: Thu, 16 Sep 2010 14:40:54 +0200

Hi Alexey:

My point wasn't about whether the procedure should be optional or 
mandatory. My comment was related to the difficulties to understand 
whether it was a procedure that implementations should provide compliance 
or not, due to the mixture of normative statements with the word 
"Guidelines".

So, if there is a strong recommendation to implement the procedure, then 
I have no problem to change the OPTIONAL to RECOMMENDED, if that is the 
spirit of the specification.

/Miguel

-- 
Miguel A. Garcia
+34-91-339-3608
Ericsson Spain