[Date Prev][Date Next]
[Chronological]
[Thread]
[Top]
RE: WG Last Call: draft-ietf-ldapbis-protocol-17.txt [corrected]
- To: <ietf-ldapbis@OpenLDAP.org>
- Subject: RE: WG Last Call: draft-ietf-ldapbis-protocol-17.txt [corrected]
- From: "Steven Legg" <steven.legg@adacel.com.au>
- Date: Mon, 6 Oct 2003 16:50:20 +1100
- Importance: Normal
- In-reply-to: <5.2.0.9.0.20030919105440.03bcf5d8@127.0.0.1>
Here are some comments on draft-ietf-ldapbis-protocol-17.txt .
They are mostly of an editorial nature.
---------------------------------------
> 1. Introduction
> This document details the protocol elements of Lightweight Directory
^ the ?
> Access Protocol, along with their semantics. Following the
> description of protocol elements, it describes the way in which the
> protocol is encoded and transferred.
^^ messages are
Or substitute "operations" for "messages".
It doesn't make sense to me to be encoding and transferring a protocol.
It does make sense to me to be encoding and transferring a protocol
message/operation.
> Prior to Working Group Last Call, this appendix
> will be distilled to a summary of changes to RFC 2251.
doh! :-)
> 3. Protocol Model
>
> The general model adopted by this protocol is one of clients
> performing protocol operations against servers. In this model, a
> client transmits a protocol request describing the operation to be
> performed to a server. The server is then responsible for performing
> the necessary operation(s) in the directory. Upon completion of the
^
The introduction starts off capitalizing the `d' in directory.
Consistency in the capitalization is desirable, though I don't have a
preference between "Directory" and "directory".
> The core protocol operations defined in this document can be mapped
> to a subset of the X.500 (1997) directory abstract service. However
> there is not a one-to-one mapping between LDAP protocol operations
> and DAP operations. Server implementations acting as a gateway to
> X.500 directories may need to make multiple DAP requests.
^ per LDAP request
> 4. Elements of Protocol
>
> The LDAP protocol is described using Abstract Syntax Notation 1
^ One
> (ASN.1) [X.680], and is transferred using a subset of ASN.1 Basic
> Encoding Rules [X.690]. Section 5.1 specifies how the protocol is
^^
Suggest: "messages are" or "operations are".
> In order to support future Standards Track extensions to this
> protocol, extensibility is implied where it is allowed (per ASN.1).
> In addition, ellipses (...) have been supplied in ASN.1 types that
> are explicitly extensible as discussed in [LDAPIANA]. Because of the
> implied extensibility, clients and servers MUST (unless otherwise
> specified) ignore trailing SEQUENCE elements whose tags they do not
^^^^^^^^
Suggest: "components".
> 4.1.3. Distinguished Name and Relative Distinguished Name
>
> An LDAPDN and a RelativeLDAPDN are respectively defined to be the
> representation of a distinguished-name and a relative-distinguished-
^ ^ ^
Remove the hyphens, the terms are not hyphenated elsewhere in the document.
> 4.1.5. Attribute Value
>
> A field of type AttributeValue is an OCTET STRING containing an
> encoded attribute value data type. The value is encoded according to
^^^^^^^^^^
I would remove the "data type". The data type isn't what is being encoded,
though it controls how the value is encoded.
> its LDAP-specific encoding definition. The LDAP-specific encoding
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Suggest: "the LDAP-specific encoding definition of the corresponding
attribute syntax".
> 4.1.7. Attribute
> Each attribute value is distinct in the set (no duplicates). The set
> of attribute values is unordered. Implementations MUST NOT reply upon
^^^^^ rely
> 4.1.10. Referral
> Referral ::= SEQUENCE OF URL -- one or more
The "one or more" constraint can be represented
explicitly as "SEQUENCE SIZE (1..MAX) OF URL".
> If the client wishes to progress the operation, it MUST follow the
> referral by contacting one of the servers.
"If" and "MUST" make this an effective "MAY", e.g.
"The Client MAY progress the operation by following the referral and
contacting one of the servers."
> - Other aspects of the new request may be the same or different as
^^^^^^^^^^^^^^^^^^^^
Suggest: "same as, or different from,"
> 4.2. Bind Operation
> - authentication: information used to authenticate the name, if any,
> provided in the Bind Request. This type is extensible as defined
> in Section 3.6 of [LDAPIANA]. Servers that do not support a choice
> supplied by a client will return authMethodNotSupported in the
> resultCode field of the BindResponse. The simple form of an
> AuthenticationChoice specifies a simple password to be used for
> authentication. To improve matching, applications SHOULD prepare
> textual strings used as passwords. Applications which prepare
> textural strings used as password are REQUIRED to prepare them by
^^^^^^^^ textual ^s
> 4.2.2. Bind Response
> The serverSaslCreds are used as part of a SASL-defined bind mechanism
> to allow the client to authenticate the server to which it is
> communicating, or to perform "challenge-response" authentication. If
> the client bound with the simple choice, or the SASL mechanism does
> not require the server to return information to the client, then this
> field is not to be included in the BindResponse.
^^^^^^^^^ SHALL NOT ?
> 4.5. Search Operation
>
> The Search Operation allows a client to request that a search be
> performed on its behalf by a server. This can be used to read
> attributes from a single entry, from entries immediately below a
^^^^^
Suggest: "subordinate to"
> 4.5.1. Search Request
> SubstringFilter ::= SEQUENCE {
> type AttributeDescription,
> -- at least one must be present,
> -- initial and final can occur at most once
> substrings SEQUENCE OF CHOICE {
The "at least one must be present" constraint can be represented
explicitly as "SEQUENCE SIZE (1..MAX) OF CHOICE".
> - sizeLimit: A size limit that restricts the maximum number of
> entries to be returned as a result of the search. A value of 0 in
> this field indicates that no client-requested size limit
> restrictions are in effect for the search. Servers may enforce a
> maximum number of entries to return.
>
> - timeLimit: A time limit that restricts the maximum time (in
> seconds) allowed for a search. A value of 0 in this field
> indicates that no client-requested time limit restrictions are in
> effect for the search.
Servers may limit the number of entries returned. Should they not also
be allowed to limit the amount of time spent ?
> The extensibleMatch is new in this version of LDAP. If the
> matchingRule field is absent, the type field MUST be present, and
> the equality match is performed for that type. If the type field
> is absent and matchingRule is present, the matchValue is compared
> against all attributes in an entry which support that
> matchingRule, and the matchingRule determines the syntax for the
> assertion value (the filter item evaluates to TRUE if it matches
> with at least one attribute in the entry, FALSE if it does not
> match any attribute in the entry, and Undefined if the
> matchingRule is not recognized or the assertionValue cannot be
> parsed.) If the type field is present and matchingRule is present,
> the matchingRule MUST be one permitted for use with that type,
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Suggest: "suitable for use with that type (see [Syntaxes])".
> - attributes: A list of the attributes to be returned from each
> entry which matches the search filter. LDAPString values of this
> field are constrained to the following ABNF:
>
> attributeSelection = noattrs /
> *( attributedescription / specialattr )
>
> noattrs = %x31 %x2E %x31 ; "1.1"
>
> attributedescription = ; attributedescription from 2.5 of [Models]
I would leave out the above line and instead add (after the ABNF) the comment:
"The <attributedescription> rule is defined in Section 2.5 of [Models]."
> Attributes MUST be named at most once in the list, and are
^^^^^^^^^^^^^^^^^^^^^^^^^^
Suggest: "MUST NOT be named more than once".
> Client implementors should note that even if all user attributes
> are requested, some attributes of the entry may not be included in
> search results due to access controls or other restrictions.
> Furthermore, servers will not return operational attributes, such
> as objectClasses or attributeTypes, unless they are listed by
> name, since there may be extremely large number of values for
> certain operational attributes. (A list of operational attributes
> for use in LDAP is given in [Syntaxes].)
^^^^^^^^^^
The operational attributes are now listed in other documents.
> 4.5.2. Search Result
> PartialAttributeList ::= SEQUENCE OF SEQUENCE {
> type AttributeDescription,
> vals SET OF AttributeValue }
I thought there was an agreement to consolidate all the SEQUENCEs
of type and vals into one Attribute ASN.1 type, and for there to be only
one "SEQUENCE OF Attribute" ASN.1 type. What happened to that ?
> SearchResultReference ::= [APPLICATION 19] SEQUENCE OF URL
> -- at least one URL element must be present
The "at least one URL element must be present" constraint can be represented
explicitly as "SEQUENCE SIZE (1..MAX) OF URL".
> If the server's schema defines a textual name for an attribute type,
> it SHOULD use a textual name for attributes of that attribute type by
> specifying one of the textual names as the value of the attribute
> type. Otherwise, the server uses the object identifier for the
> attribute type by specifying the object identifier, in ldapOID form,
> as the value of attribute type. If the server determines that
> returning a textual name will cause interoperability problems, it
> SHOULD return the ldapOID form of the attribute type.
This paragraph is a bit shaky. Consider this instead:
"If the server's schema defines short names [Models] for an attribute type
then the server SHOULD use one of those names in attribute descriptions
for that attribute type (in preference to using the dotted decimal format
of the attribute type's object identifier). The server should not use the
short name if that name is known by the server to be ambiguous, or
otherwise likely to cause interoperability problems."
> 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 all the entries in the scope at
> and under the baseObject, the server may return one or more
^^^^^
Suggest: "subordinate to".
> - Other aspects of the new search request may be the same or
^^^^^^^
> different as the search request which generated the
^^^^^^^^^^^^
Suggest: "same as, or different from,"
> 4.6. Modify Operation
> Parameters of the Modify Request are:
>
> - object: The object to be modified. The value of this field
> contains the DN of the entry to be modified. The server will not
^^^^^^^^
SHALL NOT ?
> The result of the modification attempted by the server upon receipt
> of a Modify Request is returned in a Modify Response, defined as
> follows:
>
> ModifyResponse ::= [APPLICATION 7] LDAPResult
>
> Upon receipt of a Modify Request, a server will perform the necessary
> modifications to the DIT.
I would swap around the two sentences above.
> The Modify Operation cannot be used to remove from an entry any of
> its distinguished values, those values which form the entry's
^ i.e.
> 4.7. Add Operation
> Parameters of the Add Request are:
>
> - entry: the Distinguished Name of the entry to be added. Note that
^^^^^^^^^
> the server will not dereference any aliases in locating the entry
^^^^^^^^^^^^^^^^^^^
Suggest: "The server SHALL NOT".
> The entry named in the entry field of the AddRequest MUST NOT exist
> for the AddRequest to succeed. The immediate superior (parent) of the
^^^
> object and alias entries to be added MUST exist. For example, if the
^^^^^^^^^^^^^^^^^^^^^^^^
Suggest: "an object or alias entry".
> Server implementations SHOULD NOT restrict where entries can be
> located in the directory unless DIT structure rules are in place.
> Some servers MAY allow the administrator to restrict the classes of
^^^^
The "Some" is redundant.
> 4.8. Delete Operation
> The Delete Request consists of the Distinguished Name of the entry to
> be deleted. Note that the server will not dereference aliases while
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Suggest: "The server SHALL NOT".
> resolving the name of the target entry to be removed, and that only
^^^^^^^^^^
And start a new sentence here, "Note that only" etc.
> The result of the delete attempted by the server upon receipt of a
> Delete Request is returned in the Delete Response, defined as
> follows:
>
> DelResponse ::= [APPLICATION 11] LDAPResult
>
> Upon receipt of a Delete Request, a server will attempt to perform
> the entry removal requested. The result of the delete attempt will be
> returned to the client in the Delete Response.
There is some redundancy here. Try this instead:
Upon receipt of a Delete Request, a server will attempt to perform
the entry removal requested. The result of the delete attempt will be
returned to the client in the Delete Response, defined as follows:
DelResponse ::= [APPLICATION 11] LDAPResult
> 4.9. Modify DN Operation
>
> The Modify DN Operation allows a client to change the leftmost (least
^^^^^^^^^^^^^^^
> significant) component of the name of an entry in the directory,
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
I think it would be better to say the "relative distinguished name".
> Parameters of the Modify DN Request are:
>
> - entry: the Distinguished Name of the entry to be changed. This
> entry may or may not have subordinate entries. Note that the
^^^^^^^^^^^^^
> server will not dereference any aliases in locating the entry to
^^^^^^^^^^^^^^^
Suggest: "The server SHALL NOT".
> - newrdn: the RDN that will form the leftmost component of the new
> name of the entry.
I think it would be better to say "the new relative distinguished name
of the entry".
> - newSuperior: if present, this is the Distinguished Name of an
> existing object entry which becomes the immediate superior
> (parent)of the existing entry.
^
Missing space.
> The result of the name change attempted by the server upon receipt of
> a Modify DN Request is returned in the Modify DN Response, defined as
> follows:
>
> ModifyDNResponse ::= [APPLICATION 13] LDAPResult
>
> Upon receipt of a ModifyDNRequest, a server will attempt to perform
> the name change. The result of the name change attempt will be
> returned to the client in the Modify DN Response.
See the simplification of the similar text for the Delete Response.
> If the deleteoldrdn parameter is TRUE, the values forming the old RDN
> are deleted from the entry. If the deleteoldrdn parameter is FALSE,
> the values forming the old RDN will be retained as non-distinguished
> attribute values of the entry. The server may not perform the
^^^^^^^^^^^^^^^
Suggest: "MUST fail".
> operation and return an error in the result code if the setting of
> the deleteoldrdn parameter would cause a schema inconsistency in the
> entry.
> 4.10. Compare Operation
> - entry: the name of the entry to be compared with. Note that the
> server SHOULD NOT dereference any aliases in locating the entry to
> be compared with.
Suggest: "the name of the entry to be compared. The server SHOULD NOT
dereference any aliases in locating the entry to be compared."
> The result of the compare attempted by the server upon receipt of a
> Compare Request is returned in the Compare Response, defined as
> follows:
>
> CompareResponse ::= [APPLICATION 15] LDAPResult
>
> Upon receipt of a Compare Request, a server will attempt to perform
> the requested comparison using the EQUALITY matching rule for the
> attribute type. The result of the comparison will be returned to the
> client in the Compare Response.
Redundancy here too.
> 4.12. Extended Operation
> Servers list the requestName of all ExtendedRequests they recognize
^ SHALL ?
> requestValues and responseValues that are defined in terms of ASN.1
> and BER encoded according to Section 5.1, also follow the
> extensibility rules in Section 4.
This paragraph restates a condition in a previous paragraph in this section.
> 4.13.2.2. Response other than "success"
> If the server does not support TLS (whether by design or by current
> configuration), it MUST set the resultCode field to protocolError.
> The client's current association is unaffected if the server does not
> support TLS. The client MAY proceed with any LDAP operation, or it
^^^ ^^
> MAY close the connection.
^^^
"MAY" and "or" both suggest optionality. I am left wondering what a client
is supposed to do if it elects to do neither of the MAY actions.
Perhaps the "MAY"s should be downcased.
> The server MUST return unavailable if it supports TLS but cannot
> establish a TLS connection for some reason, e.g. the certificate
> server not responding, it cannot contact its TLS implementation, or
> if the server is in process of shutting down. The client MAY retry
^^^
> the StartTLS operation, or it MAY proceed with any other LDAP
^^^^^^^^^
> operation, or it MAY close the LDAP connection.
^^^^^^^^^
Same again.
> 4.13.3. Closing a TLS Connection
>
> Two forms of TLS connection closure--graceful and abrupt--are
^^ ^^
Extra spaces needed around the hyphens.
> 4.13.3.1. Graceful Closure
> The other party, if it receives a TLS closure alert, MUST immediately
> transmit a TLS closure alert. It will subsequently cease to send TLS
^^^^ MUST ?
> 7. Security Considerations
> Server implementors should plan for the possibility of an identity or
^^
The "or" appears to be spurious.
> associated with an LDAP connection being deleted, renamed, or
> modified, and take appropriate actions to prevent insecure side
> effects. The way in which this is dealt with is implementation
> specific. Likewise, server implementors should plan for the
> possibility of an associated identities credentials becoming invalid.
^^^^^^^^^^ identity's ?
> Protocol servers may return referrals which redirect protocol clients
> to peer servers. It is possible for a rogue application to inject
> such referrals into the data stream in an attempt to redirect a
> client to a rogue server. Protocol clients are advised to be aware of
> this, and possibly reject referrals when confidentiality measures are
Is there a "not" missing after the "are" ?
> in place. Protocol clients are advised to ignore referrals from the
> Start TLS operation.
> 9. Normative References
> [LDAPIANA] K. Zeilenga, "IANA Considerations for LDAP", draft-ietf-
> ldapbis-xx.txt (a work in progress).
Should be draft-ietf-ldapbis-bcp64-00.txt .
> [Syntaxes] K. Dally (editor), "LDAP: Syntaxes", draft-ietf-ldapbis-
> syntaxes-xx.txt, (a work in progress).
Officially, I'm the editor now, but in any case I thought the normal
practice was to list all the authors.
> 11. IANA Considerations
> It is requested that the Internet Assigned Numbers Authority (IANA)
> update the occurrence of "RFC XXXX" Appendix B with this RFC number
^ in
> Appendix A - LDAP Result Codes
> Additional result codes MAY be defined for use with extensions.
I suggest adding a reference to [LDAPIANA].
> A.1 Non-Error Result Codes
> The success, compareTrue, and compare result codes indicate
> successful completion (and, hence, are called to as "successful"
^^^^^^ referred ?
> A.2 Result Codes
> protocolError (2)
> For bind operation only, the code may be resulted to indicate
^^^^^^^^ returned ?
> inappropriateMatching (18)
>
> Indicates that a request cannot be completed due to an
> inappropriate matching.
This doesn't tell me much. The X.511 description is "An attempt was made,
e.g. in a filter, to use a matching rule not defined for the attribute
type concerned".
> attributeOrValueExists (20)
>
> Indicates that the client supplied an attribute or value to
> be added to an entry already exists.
^ that
> inappropriateAuthentication (48)
>
> Indicates the server requires the client which had attempted
> to bind anonymously or without supplying credentials to
> provide some form of credentials,
Sentence is truncated.
> objectClassModsProhibited (69)
> For example, this code is returned when a when a client
^^^^^^^^^^^^^
Regards,
Steven