Draft:  draft-zeilenga-ldap-ext-09.txt
Reviewer: Elwyn Davies [elwynd@dial.pipex.com]
Review Date: Wednesday 1/4/2006 7:14 AM CST
LC Date: 4 january 2006

Summary: Assuming that numbers of extensions to LDAP are expected, this seems a 
useful piece of work.  I am not an LDAP expert so it is difficult for me 
to judge the correctness or degree of completeness of the work but it 
'feels' like it covers the field.

In general, the document appears ready to go to the IESG, but I think it 
would be worth reviewing the prescriptive items, which fall into three 
separate categories - see the full review, and using different language 
for each category.  Amongst these prescriptions, there are a few 
constraints that really belong in the protocol specification in my opinion.

Review:

[This next long winded bit is basically a way of saying that (mainly) 
SHALL and SHALL NOT are overloaded to mean subtly different things and 
it might be better if they were differentiated.]

In my view the guidelines could be classified into
1. Motherhood and apple pie both for general protocol design and IETF 
specifications,
2. Advice on preferred routes where there might be multiple choices,
3. Attempts to forbid specific really stupid ideas,
4. Requirements on designers to document reasoning (e.g., para 2 in each 
of s3.1.1, s3.1.2), and
5. Outright constraints.

The desirability of using RFC2119 requirements language capitalization 
for describing advice in a meta-specification is arguable.  However, 
types 3, 4 and 5 all use the prescriptive SHALL/SHALL NOT and MUST/MUST 
NOT language which is a little confusing as they are requiring 
qualitatively different things.

In general terms I have no problem with types 1, 2 and 3. 

Regarding the type 5, these items are so prescriptive of extension 
specification or behaviour that I think they belong in the main protocol 
definition rather than in this document (although reference could 
obviously be made here).  As is said in s1, LDAP is intended to be 
extensible, and if there are things that extensions MUST or SHALL do 
then the definitive statement does't belong in the BCP, which is about 
choices.  For example, s3.3:

  Extensions SHALL use IntermediateResponse messages instead of
  ExtendedResponse messages to return intermediate results.

Similarly para 2 of s4.1, first half of last para of s4.3 and s6.2.


Type 4 occurs, for example, in para 2 of s3.1.1 and s3.1.2:

  Specifications detailing controls extending the Bind operation SHALL
  detail that the Bind negotiated security layers do not protect the
  information contained in these controls and SHALL detail why this
  protection is not needed.

This is about documenting design decisions (a meta-meta-specification 
maybe?). I think using 'needs to explain' rather than 'SHALL detail' is 
more helpful.

The remaining Type 3 (don't do this because it is really stupid) items 
might just be better said as 'Do not do X' rather than using 'SHALL 
NOT'.  Ultimately you can't prevent it if stupid designers and dumb 
reviewers conspire to allow it. A few words of justification might help 
in a couple of cases.


Couple of other minor points:

s2.2, para 1: 'Designers SHOULD consider...'.  I would have said if 
there was ever a case for MUST it is here!

s4.4
  Designers SHOULD avoid introducing extensions which rely on
  unsuspecting implementations to ignore trailing components of SEQUENCE
  whose tags they do not recognize.
I don't understand what this is trying to forbid.


Editorial:

s1: Expand acronyms URL, ASN (yawn).

s1.1, para 2: s/client/a client/, s/server generated/a server generated/

s2.3, para 1: s/discover/discovery/
s2.3, para 2: s/this discover/this discovery/

s2.4: s/repitor/repertory/

[Aside: s2.4, para 2: Does the update of RFC3066  have any implications 
for RFC3866?]

s2.5: s/is described/are described/
s2.5: s/specific contains/specific contents/

s2.7: Expand acronym DN.

s2.8: s/SHALL extended/SHALL extend/

s3, para 1: I think the last piece 'extended operation instead' is 
confusing.  I suggest s/existing operations/existing operations wherever 
it is appropriate/, s/extended operation/extra, new operation using the 
extended operations mechanism/

s3.1, para 1: s/Controls... is/Controls... are/
s3.1, para 2: s/unless unless/unless/

s3.1.1, last para: s/controls semantics/controls' semantics/

s3.1.3, last para: s/apply in./apply./, s/finding phasing/finding phase/

s3.1.4, para 1: s/concistency/consistency/
s3.1.4, para after bullets: s/wether/whether/, s/or separate/or a separate/

s4, para 1: s/to made/to be made/

s4.1, last para:s/server/the server/

s4.2: s/protocolOp/protocol/

s5.2, last para: s/In additional/In addition/

s6.1: s/hyphen/hyphens/