protocol-27 comments #3

[Hallvard B Furuseth <h.b.furuseth@usit.uio.no>]

Final (hopefully:-) bunch of protocol comments:

> 4.1.10. Referral

>    If the client wishes to progress the operation, it MUST follow the
>    referral by contacting one of the supported services.

"if the client wishes, then it MUST" sounds strange to me.
I would s/MUST/can/.

>    Protocol peers (...) MUST NOT repeatedly contact the same
>    server for the same request with the same target entry name, scope
>    and filter.

How about different controls (maybe due to LDAPURL extensions) and other
extensions?  (Same question to continuation references in section 4.5.3.)

How about non-search operations?  Maybe this text should just be

     MUST NOT contact the same server for the same request with the
     same parameters.

>    - If an alias was dereferenced, the <dn> part of the URL MUST be
>      present, with the new target object name.

I would prepend "Note that" to the following, and move it below the list
of instructions:

>      UTF-8 encoded characters
>      appearing in the string representation of a DN or search filter
>      may not be legal for URLs (e.g. spaces) and MUST be escaped using
>      the % method in [URI].

>    - If the <dn> part is present, the client MUST use this name in its
>      next request to progress the operation, and if it is not present
>      the client will use the same name as in the original request.

s/will/MUST/ for consistency.

>    - If the <scope> part is missing, the scope of the original search
>      is used by the client to progress the operation.

s/is/MUST be/.  (Or go the other way, and remove MUSTs in this list.)

> 4.1.11. Controls

>    For controls attached to
>    response messages and the unbindRequest, the criticality field SHOULD
>    be FALSE,

Well, the protocol _field_ should not be FALSE but absent (since default
values MUST be absent, by Section 5.2).  The abstract _value_ sent by
the client should be FALSE.  The same applies to the rest of the text.

>    A value
>    of TRUE indicates that it is unacceptable to perform the operation
>    without applying the semantics of the control and FALSE otherwise.

"and FALSE otherwise" looks strange in this sentence - is it left over
from a different wording?

>    - whether information is to be present in the controlValue field,
>      and if so, the format of the controlValue contents,

I think that should be

       whether the controlValue field is to be present, and if so, ...

since if it is present, it does contain information.

> 4.2. Bind Operation

>    Authorization is the decision of which access an operation has to the
>    directory. Among other things, the process of authorization takes as
>    input authentication information obtained during the bind operation
>    and/or other acts of authentication (such as lower layer security
>    services).

Authorization can also - or instead - take as input information which is
not normally considered acts of authentication, such as the IP number of
time of day.

> 4.4. Unsolicited Notification

>    The unsolicited notification is structured as an LDAPMessage in which
>    the messageID is zero and protocolOp is of the extendedResp form (See
>    Section 4.12).

Actually, 4.12 defines ExtendedResponse.  extendedResp is defined in
4.1.1.

>    - the format of the contents (if any) of the responseValue,

move "(if any)" to the end of the sentence (to address an absent value,
not a present but empty value).

>    - the circumstances which will cause the notification to be
>      returned, and
>
>    - the semantics of the operation.

s/returned/sent/.  I think 'returned' means it is some request's return
value.  "operation" seems strange for the same reason.  "message",
maybe?

> 4.4.1. Notice of Disconnection

>    This notification may be used by the server to advise the client that
>    the server is about to close the connection due to an error
>    condition.

s/error condition/exceptional condition/ or something?  I wouldn't call
controlled shutdown of the server or idletimeout of the connection an
error.  Or maybe the question should be avoided:

     ... server is about to close the connection on its own initiative.

> 4.5.1. Search Request

>         SubstringFilter ::= SEQUENCE {
>              type           AttributeDescription,
>              -- initial and final can occur at most once
                                
s/once/once each/?  (I.e. twice:-)

>    - scope: Specifies the scope of the search to be performed. The
>      semantics (as described in [X.511]) of the possible values of this
>      field are:
>    - derefAliases: An indicator as to how alias entries (as defined in
>      [Models]) are to be handled in searching. The semantics of the
>      possible values of this field are:

s/possible/defined/ in these two, since other values can be defined
later.

>         derefInSearching: While searching, dereference any alias entry
>         subordinate to the base object which is also in the search
>         scope. The filter is applied to the dereferenced object(s). If
>         the search scope is wholeSubtree, the search continues in the
>         subtree of any dereferenced object. Aliases in that subtree are
>         also dereferenced.

This seems to say that recursive dereferencing stops at alias entries
that are not subordinate to the base object, and that onelevel searches
do not recursively dereference aliases.

>         derefAlways: Dereference aliases both in searching and in
>         locating the base object of the search.

Add a blank line.

>      The present match evaluates to TRUE where there is an attribute or
>      subtype of the specified attribute description present in an
>      entry, and FALSE otherwise (including a presence test with an
>      unrecognized attribute description.)

s/.)/)./ ?  Not sure how () and punctuation interact in English.

>      Note that the AssertionValue in a substrings filter item conforms

s/AssertionValue/AssertionValues/.

>         If the matchingRule field is absent, the type field MUST be
>         present, and an equality match is performed for that type.

Which means just (:dn:=foo) is not allowed.  Maybe the draft should
suggest that one can use (1.1:dn:=foo).

Also, is it an error to violate this "MUST"?  Most other invalid filters
just return Undefined.

>         If the type field is present and the matchingRule is present,
>         the matchValue is compared against entry attributes of the
>         specified type. In this case, the matchingRule MUST be one
>         suitable for use with the specified type (see [Syntaxes]),
>         otherwise the filter item is Undefined.

This "MUST" looks a bit strange, since it's well-defined what the filter
returns.  There might be a good reason to use a matching rule which one
doesn't know is suitable for use with the type.

> 4.5.2. Search Result

>    The results of the search operation are returned as zero or more
>    searchResultEntry messages, zero or more SearchResultReference
>    messages, followed by a single searchResultDone message.

replace "messages, zero or more" with "and/or" to clarify that the
entries need not precede the references.

>    Each entry returned in a SearchResultEntry will contain all
>    appropriate attributes as specified in the attributes field of the
>    Search Request. Return of attributes is subject to access control and
>    other administrative policy.

I would s/. Return of attributes is/,/

> 4.5.3. Continuation References in the Search Result

>    If the server was able to locate the entry referred to by the
>    baseObject but was unable to search one or more non-local entries,
>    the server may return one or more SearchResultReference entries, each
>    containing a reference to another set of servers for continuing the
>    operation.

It's not clear to me if "SearchResultReference entries" - which is wrong
since they are protocol elements, not entries - means to imply that each
SearchResultReference represents one entry.  Can NSSRs or something like
them be returned?  (Would that be if one has an entry - maybe a shadow
copy - but does not search (or return) any of its children?)

>    - If the originating search scope was singleLevel, the <scope> part
>      of the URL will be "base".
>
>    - It is RECOMMENDED that the <scope> part be present to avoid
>      ambiguity.

The text doesn't seem to say that the scope defaults to the original
value.  (Nor other aspects below, but I guess that would depend on these
aspects' definitions.)

>    - Other aspects of the new search request may be the same as or
>      different from the search request which generated the
>      SearchResultReference.

> 4.5.3.1. Examples

>    It
>    knows that either LDAP-capable servers (hostb) or (hostc) hold
>    <OU=People,DC=Example,DC=NET>

s/either...or/both...and/, I think.

>      SearchResultReference {
>        ldap://hostb/OU=People,DC=Example,DC=NET??sub
>        ldap://hostc/OU=People,DC=Example,DC=NET??sub }
>      SearchResultReference {
>        ldap://hostd/OU=Roles,DC=Example,DC=NET??sub }
>      SearchResultDone (success)

I suggest you change an example (and the matching text) so a DN on one
host is different from the original DN.

> 4.6. Modify Operation

>    - object: The name of the object to be modified. The value of this
>      field contains the DN of the entry to be modified.

Doesn't this say the same thing twice?  Mimicing the wording from add &
co, it should be

     - object: The name of the entry [not object] to be modified.

If you wish to imply that the name is a DN, I suggest 'The name (DN)
of...' both here and elsewhere.

>            delete: delete values listed from the modification attribute,
>            removing the entire attribute if no values are listed, or if
>            all current values of the attribute are listed for deletion;

Suggest /if no values are listed, or if/if either values are listed or/.

> 4.7. Add Operation

>    - attributes: (...)

>      Clients MUST
>      include the 'objectClass' attribute, and values of any mandatory
>      attributes of the listed object classes. Clients MUST NOT supply
>      NO-USER-MODIFICATION attributes such as the createTimestamp or
>      creatorsName attributes, since the server maintains these
>      automatically.

The same applies to Modify Operation.  Maybe factor that out and replace
with a reference to [Models], similar to what has been done with some
Modify Operation text?

> 4.9. Modify DN Operation

>    - newrdn: (...) If the operation moves the entry
>      to a new superior without changing its RDN, the value of the old
>      RDN is supplied for this parameter.

This sort of implies that Something (the server?) modifies this
parameter if one does that operation, instead of the other way around.
Maybe:

       To move the entry to a new superior without changing its RDN, the
       client can supply the value of the old RDN for this parameter.

> 4.13. IntermediateResponse Message

>    - the format of the contents of the responseValue, and

s/responseValue/responseValue (if any)/.

> 6. Security Considerations

>    This version of the protocol provides facilities for simple
>    authentication using a cleartext password, as well as any [SASL]
>    mechanism. Installing SASL

and TLS  [or did I say that before?]

>    layers can provide integrity and other
>    data security services.

> A.1 Non-Error Result Codes

>    The referral and saslBindInProgress result codes indicate the client
>    is required to take additional action to complete the operation.

s/is required/needs/, since the client is free to not follow referrals.

-- 
Hallvard