Subject: protocol-22 comments

From: Hallvard B Furuseth <[email-masked]>
Date: Tue, 9 Mar 2004 15:20:19 +0100

Various comments to protocol-22 follow.

> 4.1.11. Controls

>    When an extension calls for a particular response control to be sent
>    in response to a request control, the response and request controls
>    are termed to be "paired".
>    (...)
>    The controlType field is the dotted-decimal representation of an
>    OBJECT IDENTIFIER which uniquely identifies the control, or the
>    request control and its paired response control.

These paragraphs seem to imply that a request control may only solicit a
response control with the same OID as the request control, and it cannot
solicit two response controls (with different OIDs).  I think that's
wrong.

>    Additionally, unless order-dependent semantics are given in a
>    specification, the order of a combination of controls in the SEQUENCE
>    is ignored.

This implies that controls (A, B) MUST behave identically with controls
(B, A).  I think it should be, "the effect of the ordering of a
combination of controls in the SEQUENCE is unspecified"?

> 4.7. Add Operation

>    If the entry to be added would not fall within a naming context
>    [Section 5 of Models] held by the server, and the server has
>    knowledge of where that entry is to be located, a referral to the
>    server(s) holding the parent entry should be returned.

Unless the server chains the operation to another server (i.e. it sends
the request to the server which masters that naming context, and returns
the response from that server to the client).

> 4.12. Extended Operation

>    Extended operations may be specified in other documents. The
>    specification of an extended operation consists of:
>
>    - the OBJECT IDENTIFIER assigned to the requestName (and possibly
>      responseName),

Does this mean responseName must be empty or equal to requestName?
This should be clarified in the paragraph about responseName.

> 4.13. IntermediateResponse Message

>    Although the responseName and responseValue are optional in some
>    circumstances, generally speaking IntermediateResponse messages have
>    a predefined responseName and a responseValue.

I do not understand.  Are they any more predefined than other
LDAPMessages?

> A.1 Non-Error Result Codes

>         compareTrue (6),
>         compareFalse (7),

Should be 5 and 6.

> A.2 Result Codes

>         protocolError (2)
>            Indicates the server received data which has incorrect
>            structure.
>
>            For bind operation only, this code is also used to indicate
>            that the server does not support the requested protocol
>            version.

For Start TLS, it is also used to indicate that TLS is currently
unsupported.

>         compareFalse (5)
>            Indicates that the compare operation has successfully
>            completed and the assertion has evaluated to FALSE.

... or Undefined.

>         affectsMultipleDSAs (71)
>            Indicates that the operation cannot be completed as it
>            affects multiple servers (DSAs).

s/completed/performed/, s/affects/would affect/.

(The code doesn't mean that the operation may have been partially
performed but could not be completed.)

------------------------------------------------------------------------

Editorial comments:

> 4.2. Bind Operation

>    Authorization is the use of this authentication information when
>    performing operations.

No, authorization need not make use of the authentication information.
One could e.g. base it on IP addresses only (but only for read
operations, I would hope:-)

Nitpick:  The word "use" is wrong.  Putting the currently active
authentication identity in LDAPResult.diagnosticMessage is "use" of auth
info, but not authorization.  Not sure if this is worth bothering with,
though.

>    Authorization MAY be affected by factors
>    outside of the LDAP Bind Request, such as those provided by lower
>    layer security services.

Here is a suggestion, though it's a bit long.  Maybe the last sentence
should be dropped.

     Authorization is the decision of which access an operation has to
     the directory.  It may be affected by many factors, often including
     the association's authorization identity, which again was derived
     from or authorized via the authentication information.
     Authorization may be affected by factors outside of the LDAP Bind
     Request, such as those provided by lower layer security services.

> 4.2.1. Processing of the Bind Request

>    Before processing a BindRequest, all outstanding operations MUST
>    either complete or be abandoned.

This could be read as a suggestion for the client to abandon the
operations.  I suggest:

     The server MUST NOT process a BindRequest until no earlier
     operations are outstanding.

I added "earlier" because it shouldn't complete or abandon operations
submitted _after_ the Bind.

>    The server may either wait for the 
>    outstanding operations to complete, or abandon them.

> 4.5.3. Continuation References in the Search Result
> 4.5.3.1. Examples

>    If the contacted server does not hold the base object for the search,
>    then it will return a referral to the client.

s/will/may/.

> 4.10. Compare Operation

>    The resultCode field is set to compareTrue, compareFalse, or an
>    appropriate error. compareTrue indicates that the assertion value in
>    the ava field is equivalent to a value of the attribute or subtype
>    (according to the attribute's EQUALITY matching rule).

Maybe remove the "()"'s?

>    compareFalse
>    indicates that the comparison of the assertion value in the ava field
>    and the values of the attribute or subtype resulted in an Undefined
                                                            ^^
>    (Section 4.5.1) or non-equivalent match.
                     ^^                ^^^^^
s/an/only/, s/or/and/, s/match/matches/.

> 4.11. Abandon Operation

>    Operation responses are not sent for successfully
>    abandoned operations,

This can be read as 'the server performs abandoned operations but does
not send their responses':-)

>    thus the application of the Abandon operation
>    is limited to uses where the client does not require an indication of
>    its outcome.

You could say "Since operation responses are not ..." and strike "thus".
However, the reasoning is a bit unclear in any case.  I suggest:

     Since the client cannot tell the difference between a successfully
     abandoned operation and an outstanding operation yet to be
     performed, the application of (...)

>    Abandon, Bind, Unbind, and StartTLS operations cannot be abandoned.
>    The ability to abandon other (particularly update) operations is at
>    the discretion of the server.

The last sentence is contradicted by the next paragraph.  You can move
the sentence below the offending paragraph, or swap the two paragraphs.

>    In the event that a server receives an Abandon Request on a Search
>    Operation in the midst of transmitting responses (...)

> 4.13. IntermediateResponse Message

>    Similarly, it is intended that clients will explicitly solicit
>    IntermediateResponse messages by issuing operations that specifically
>    call for their return.

Delete this, it's repeated in stronger language in the next paragraph.

>         IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
>                 responseName     [0] LDAPOID OPTIONAL,
>                 responseValue    [1] OCTET STRING OPTIONAL }

This is missing from Appendix B (Complete ASN.1 Definition).

>    The value of the
>    responseName (if present), the syntax of the responseValue (if
>    present) and the semantics associated with a particular
>    IntermediateResponse message MUST be specified in documents
>    describing the extended operation or request control that uses them.
>    Sections 4.13.1 and 4.13.2 describe additional requirements on the
>    inclusion of responseName and responseValue in IntermediateResponse
>    messages.

I suggest you reformat this to a list of things the spec consists of,
similar to "The specification of an extended operation consists of:..."
in section 4.12.
    
> 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse

>    An extended operation that defines the return of multiple kinds of
>    IntermediateResponse messages MUST provide and document a mechanism
>    for the client to distinguish the kind of IntermediateResponse
>    message being sent.  This SHALL be accomplished by using different
>    responseName values for each type of IntermediateResponse message
>    associated with the extended operation or by including identifying
>    information in the responseValue of each type of IntermediateResponse
>    message associated with the extended operation.

s/type/kind/ or s/kind(s)/type(s)/.

I think this can be shortened a lot:

     An extended operation that defines the return of multiple kinds of
     IntermediateResponse messages SHALL identify those different kinds
     either by giving them different responseName values or by including
     identifying information in their responseValues.

However, this - and the original - does not allow one ExtendedRequest to
solicit some IntermediateResponse types identified by responseName and
some types identified by the contents of responseValue.  This does:

     (...) SHALL identify those different kinds by giving them different
     responseName values and/or including identifying information in
     their responseValues.

Finally, I suggest to factor this and the equivalent statement for
request controls, out to section 4.13: Just move the statement and do
s/extended operation/extended operation or request control/.

> 4.14.1. StartTLS Request

>    The client MUST NOT send any PDUs on this connection following this
>    request until it receives a StartTLS extended response and

, in case of a success response,

>    completes
>    TLS negotiations.

> 4.14.2.2. Response other than "success"

>    If the ExtendedResponse contains a result code other than success,
>    (...)

>    The
>    client's current association is unaffected if the server does not
>    support TLS.

It is also unaffected if StartTLS returns non-success for some other
reason.  Also, move it to the first paragraph.  Or maybe delete the
sentence, since [Authmeth] covers it.

> 4.14.3.2. Abrupt Closure
>
>    Either the client or server MAY abruptly close the TLS connection by
>    dropping the underlying transfer protocol connection. In this

s/transfer protocol connection/LDAP connection/; that's the phrase
which is used elsewhere (e.g. in 4.14.3.1).

>    Outstanding
>    operations are handled as specified in Section 5.2.

The same applies to graceful closure.  Delete this sentence, instead put
in 4.14.3 (Closing a TLS Connection):

     If the underlying LDAP connection is dropped, outstanding
     operations are handled as specified in Section 5.2.

> 5.2. Transfer Protocols
>
>    This protocol is designed to run over connection-oriented, reliable
>    transports, with all 8 bits in an octet being significant in the data
>    stream.

The ", with..." part is strange.  How about LDAP over transports that
are not naturally divided into octets, but e.g. 36-bit units?  I suggest
to replace it with:

     , where the data stream is divided into octets (8-bit units).

That all bits in an octet are significant need not be stated; that's
what anyone would assume unless the opposite was specified.

I suggest at least a paragraph break here.  In fact, I think the rest of
the paragraph belongs in a separate section '5.2.2 Connection Closure
Effects'.

>    Protocol operations are tied to a connection, thus if the
>    connection is closed or dropped, the operation is aborted. When this
>    happens, any outstanding operations on the server are, when possible,
>    abandoned, and when not possible, completed without transmission of
>    the response.

s/on the server/on the connection/.  Dropping one connection doesn't
affect operations on another connection to the same server.

The "thus..." is wrong: _aborting_ an operation might leave an update
operation halfway done.  The next sentence corrects it, but I suggest to
just drop the offending sentence:

     Protocol operations are tied to a connection.  If the connection is
     closed or dropped, any outstanding operations on the connection
     are, (...)
     
>    Also, if the connection is closed or dropped, the
>    client MUST NOT assume that any outstanding requests which modified
>    the Directory have succeeded or failed.

Suggest /which modified/to modify/.

> 6. Security Considerations

>    Requirements of authentication methods, SASL mechanisms, and TLS are
>    described in [AuthMeth].

s/Requirements of/Security considerations for/?

> C.1 Changes made to made to RFC 2251:
> C.2 Changes made to made to RFC 2830:
> C.3 Changes made to made to [LIMR]:

s/made to made to/made to/.

-- 
Hallvard