Subject: Re: protocol-27 comments #3

From: "Jim Sermersheim" <[email-masked]>
Date: Mon, 08 Nov 2004 13:40:46 -0700

Halvard, I'm replying to this with responses I see not needing
discussion. I've replies in other threads for issues which may require
more discussion.
 
>>> Hallvard B Furuseth <[email-masked]> 11/8/04 5:59:28 AM
>>>
>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/.
 
new text proposal:
If the client wishes to progress the operation, it contacts one of the
supported services found in the referral
 
>> 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.
 
That's much better.
 
>> - 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:
 
right
 
<snip>
 
>> 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?
 
I agree, I'm removing that.
 
>> - 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.
 
yes
 
<snip>
 
>> 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.
 
I left the reference, but changed the text to:
 
...and protocolOp is set to the extendedResp choice using the
ExtendedResponse type (See Section 4.12)
 
>> - 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).
 
right
 
>> - 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?
 
yes on both.
 
>> 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.
 
yes, also s/error/exceptional server condidtion in the next sentence.
 
>> 4.5.1. Search Request
>
>> SubstringFilter ::= SEQUENCE {
>> type AttributeDescription,
>> -- initial and final can occur at most once
>
>s/once/once each/? (I.e. twice:-)
 
I removed this and added "-- can occur at most once to the right of
initial and final"
 
>> - 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.
 
yes
 
<snip>
 
>> derefAlways: Dereference aliases both in searching and in
>> locating the base object of the search.
>
>Add a blank line.
 
yes
 
>> 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.
 
you're right.
 
>> Note that the AssertionValue in a substrings filter item conforms
>
>s/AssertionValue/AssertionValues/.
 
I think you mean to s/AssertionValues/an AssertionValue/ in the
previous sentence.
 
<snip>
 
>> 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.
 
yes
 
>> 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/,/
 
ok
 
<snip>
 
>> - 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.)
 
will add: "In the absence of a <scope> part, the scope of the original
Search request is assumed."
 
>> 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.
 
right
 
<snip>
 
>> 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.
 
I think just "name" works.
 
>> 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/.
 
how about:
 
delete: delete values listed from the modification attribute. If no
values are listed, or if all current values of the attribute are listed,
the entire attribute is removed;
 
>> 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?
 
Already factored out as part of earlier edit
 
>> 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.
 
changed to:
The value of the old RDN is supplied when moving the entry to a new
superior without changing its RDN.
 
>> 4.13. IntermediateResponse Message
>
>> - the format of the contents of the responseValue, and
>
>s/responseValue/responseValue (if any)/.
 
right
 
>> 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.
 
got it
 
>> 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.
 
 yes
 
>-- 
>Hallvard
 
Thanks again,
 
Jim

---

From: Hallvard B Furuseth <[email-masked]>
Date: Tue, 9 Nov 2004 11:26:43 +0100

> I think you mean to s/AssertionValues/an AssertionValue/ in the

Better.

> the entire attribute is removed;

Better.

-- 
Hallvard