--- 1/draft-ietf-ldapbis-protocol-14.txt 2006-02-05 00:12:01.000000000 +0100 +++ 2/draft-ietf-ldapbis-protocol-15.txt 2006-02-05 00:12:01.000000000 +0100 @@ -1,14 +1,14 @@ Internet-Draft Editor: J. Sermersheim Intended Category: Standard Track Novell, Inc -Document: draft-ietf-ldapbis-protocol-14.txt Jun 2003 +Document: draft-ietf-ldapbis-protocol-15.txt Jun 2003 Obsoletes: RFC 2251 LDAP: The Protocol Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering @@ -34,83 +34,83 @@ This document describes the protocol elements, along with their semantics and encodings, for the Lightweight Directory Access Protocol (LDAP). LDAP provides access to distributed directory services that act in accordance with X.500 data and service models. These protocol elements are based on those described in the X.500 Directory Access Protocol (DAP). Table of Contents - 1. Introduction.....................................................2 - 2. Conventions......................................................3 - 3. Protocol Model...................................................3 - 4. Elements of Protocol.............................................4 - 4.1. Common Elements................................................4 - 4.1.1. Message Envelope.............................................4 - 4.1.2. String Types.................................................6 - 4.1.3. Distinguished Name and Relative Distinguished Name...........6 + 1. Introduction....................................................2 + 2. Conventions.....................................................3 + 3. Protocol Model..................................................3 + 4. Elements of Protocol............................................4 + 4.1. Common Elements...............................................4 + 4.1.1. Message Envelope............................................4 + 4.1.2. String Types................................................6 + 4.1.3. Distinguished Name and Relative Distinguished Name..........6 Sermersheim Internet-Draft - Expires Jan 2004 Page 1 Lightweight Directory Access Protocol Version 3 - 4.1.4. Attribute Descriptions.......................................6 - 4.1.5. Attribute Value..............................................7 - 4.1.6. Attribute Value Assertion....................................7 - 4.1.7. Attribute....................................................8 - 4.1.8. Matching Rule Identifier.....................................8 - 4.1.9. Result Message...............................................8 - 4.1.10. Referral...................................................10 - 4.1.11. Controls...................................................11 - 4.2. Bind Operation................................................12 - 4.3. Unbind Operation..............................................15 - 4.4. Unsolicited Notification......................................15 - 4.5. Search Operation..............................................16 - 4.6. Modify Operation..............................................23 - 4.7. Add Operation.................................................25 - 4.8. Delete Operation..............................................26 - 4.9. Modify DN Operation...........................................26 - 4.10. Compare Operation............................................27 - 4.11. Abandon Operation............................................28 - 4.12. Extended Operation...........................................29 - 4.13. Start TLS Operation..........................................29 - 5. Protocol Element Encodings and Transfer.........................31 - 5.1. Protocol Encoding.............................................31 - 5.2. Transfer Protocols............................................32 - 6. Implementation Guidelines.......................................32 - 6.1. Server Implementations........................................32 - 6.2. Client Implementations........................................32 - 7. Security Considerations.........................................33 - 8. Acknowledgements................................................33 - 9. Normative References............................................33 - 10. Editor's Address...............................................35 - Appendix A - LDAP Result Codes.....................................36 - A.1 Non-Error Result Codes.........................................36 - A.2 Error Result Codes.............................................36 - A.3 Classes and Precedence of Error Result Codes...................36 - Appendix C - Change History........................................47 - C.1 Changes made to RFC 2251:......................................47 - C.2 Changes made to draft-ietf-ldapbis-protocol-00.txt:............47 - C.3 Changes made to draft-ietf-ldapbis-protocol-01.txt:............48 - C.4 Changes made to draft-ietf-ldapbis-protocol-02.txt:............48 - C.5 Changes made to draft-ietf-ldapbis-protocol-03.txt:............50 - C.6 Changes made to draft-ietf-ldapbis-protocol-04.txt:............52 - C.7 Changes made to draft-ietf-ldapbis-protocol-05.txt:............52 - C.8 Changes made to draft-ietf-ldapbis-protocol-06.txt:............53 - C.9 Changes made to draft-ietf-ldapbis-protocol-07.txt:............56 - C.10 Changes made to draft-ietf-ldapbis-protocol-08.txt:...........56 - C.11 Changes made to draft-ietf-ldapbis-protocol-09.txt:...........56 - C.12 Changes made to draft-ietf-ldapbis-protocol-10.txt:...........56 - C.13 Changes made to draft-ietf-ldapbis-protocol-11.txt:...........57 - C.14 Changes made to draft-ietf-ldapbis-protocol-12.txt:...........57 - C.15 Changes made to draft-ietf-ldapbis-protocol-13.txt............57 - Appendix D - Outstanding Work Items................................58 + 4.1.4. Attribute Descriptions......................................6 + 4.1.5. Attribute Value.............................................7 + 4.1.6. Attribute Value Assertion...................................7 + 4.1.7. Attribute...................................................8 + 4.1.8. Matching Rule Identifier....................................8 + 4.1.9. Result Message..............................................8 + 4.1.10. Referral..................................................10 + 4.1.11. Controls..................................................11 + 4.2. Bind Operation...............................................12 + 4.3. Unbind Operation.............................................15 + 4.4. Unsolicited Notification.....................................15 + 4.5. Search Operation.............................................16 + 4.6. Modify Operation.............................................23 + 4.7. Add Operation................................................25 + 4.8. Delete Operation.............................................26 + 4.9. Modify DN Operation..........................................26 + 4.10. Compare Operation...........................................27 + 4.11. Abandon Operation...........................................28 + 4.12. Extended Operation..........................................29 + 4.13. Start TLS Operation.........................................30 + 5. Protocol Element Encodings and Transfer........................32 + 5.1. Protocol Encoding............................................32 + 5.2. Transfer Protocols...........................................32 + 6. Implementation Guidelines......................................33 + 6.1. Server Implementations.......................................33 + 6.2. Client Implementations.......................................33 + 7. Security Considerations........................................33 + 8. Acknowledgements...............................................34 + 9. Normative References...........................................34 + 10. Editor's Address..............................................35 + Appendix A - LDAP Result Codes....................................37 + A.1 Non-Error Result Codes........................................37 + A.2 Error Result Codes............................................37 + Appendix C - Change History.......................................48 + C.1 Changes made to RFC 2251:.....................................48 + C.2 Changes made to draft-ietf-ldapbis-protocol-00.txt:...........48 + C.3 Changes made to draft-ietf-ldapbis-protocol-01.txt:...........49 + C.4 Changes made to draft-ietf-ldapbis-protocol-02.txt:...........49 + C.5 Changes made to draft-ietf-ldapbis-protocol-03.txt:...........51 + C.6 Changes made to draft-ietf-ldapbis-protocol-04.txt:...........53 + C.7 Changes made to draft-ietf-ldapbis-protocol-05.txt:...........53 + C.8 Changes made to draft-ietf-ldapbis-protocol-06.txt:...........54 + C.9 Changes made to draft-ietf-ldapbis-protocol-07.txt:...........57 + C.10 Changes made to draft-ietf-ldapbis-protocol-08.txt:..........57 + C.11 Changes made to draft-ietf-ldapbis-protocol-09.txt:..........57 + C.12 Changes made to draft-ietf-ldapbis-protocol-10.txt:..........57 + C.13 Changes made to draft-ietf-ldapbis-protocol-11.txt:..........58 + C.14 Changes made to draft-ietf-ldapbis-protocol-12.txt:..........58 + C.15 Changes made to draft-ietf-ldapbis-protocol-13.txt...........58 + C.16 Changes made to draft-ietf-ldapbis-protocol-14.txt...........59 + Appendix D - Outstanding Work Items...............................61 1. Introduction Sermersheim Internet-Draft - Expires Jan 2004 Page 2 Lightweight Directory Access Protocol Version 3 The Directory is "a collection of open systems cooperating to provide directory services" [X.500]. A Directory user, which may be a human or other entity, accesses the Directory through a client (or Directory User Agent (DUA)). The client, on behalf of the directory @@ -132,21 +132,21 @@ 2. Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are to be interpreted as described in [RFC2119]. The terms "connection" and "LDAP connection" both refer to the underlying transport protocol connection between two protocol peers. The term "TLS connection" refers to a TLS-protected LDAP connection. The terms "association" and "LDAP association" both refer to the - association of the LDAP connection and the current authentication and + association of the LDAP connection and its current authentication and authorization state. 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 operation(s), the server returns a response containing any results or @@ -480,31 +480,32 @@ -- 70 reserved for CLDAP -- affectsMultipleDSAs (71), -- 72-79 unused -- other (80), ... }, -- 81-90 reserved for APIs -- matchedDN LDAPDN, diagnosticMessage LDAPString, referral [3] Referral OPTIONAL } - The result codes enumeration is extensible as defined in Section 3.5 - of [LDAPIANA]. The meanings of the result codes are given in Appendix - A. - - The diagnosticMessage field of this construct may, at the server's - option, be used to return a string containing a textual, human- - readable (terminal control and page formatting characters should be + The resultCode enumeration is extensible as defined in Section 3.5 of + [LDAPIANA]. The meanings of the result codes are given in Appendix A. + If a server detects multiple errors for an operation, only one + resultCode is returned. The server should return the resultCode that + best indicates the nature of the error encountered. Sermersheim Internet-Draft - Expires Jan 2004 Page 9 Lightweight Directory Access Protocol Version 3 + The diagnosticMessage field of this construct may, at the server's + option, be used to return a string containing a textual, human- + readable (terminal control and page formatting characters should be avoided) diagnostic message. As this diagnostic message is not standardized, implementations MUST NOT rely on the values returned. If the server chooses not to return a textual diagnostic, the diagnosticMessage field of the LDAPResult type MUST contain a zero length string. For certain result codes (typically, but not restricted to noSuchObject, aliasProblem, invalidDNSyntax and aliasDereferencingProblem), the matchedDN field is set to the name of the lowest entry (object or alias) in the directory that was matched. @@ -541,27 +542,27 @@ If the client wishes to progress the operation, it MUST follow the referral by contacting one of the servers. If multiple URLs are present, the client assumes that any URL may be used to progress the operation. URLs for servers implementing the LDAP protocol are written according to [LDAPURL]. If an alias was dereferenced, the part of the URL MUST be present, with the new target object name. If the 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. Some servers (e.g. - participating in distributed indexing) may provide a different filter - in a referral for a search operation. If the filter part of the URL Sermersheim Internet-Draft - Expires Jan 2004 Page 10 Lightweight Directory Access Protocol Version 3 + the same name as in the original request. Some servers (e.g. + participating in distributed indexing) may provide a different filter + in a referral for a search operation. If the filter part of the URL is present in an LDAPURL, the client MUST use this filter in its next request to progress this search, and if it is not present the client MUST use the same filter as it used for that search. Other aspects of the new request may be the same or different as the request which generated the referral. Note that UTF-8 characters appearing in a DN or search filter may not be legal for URLs (e.g. spaces) and MUST be escaped using the % method in [RFC2396]. @@ -596,28 +597,32 @@ If the server does not recognize the control type or it is not appropriate for the operation, and the criticality field is TRUE, the server MUST NOT perform the operation, and MUST instead return the resultCode unavailableCriticalExtension. If the control is unrecognized or inappropriate but the criticality field is FALSE, the server MUST ignore the control. The controlValue contains any information associated with the - control, and its format is defined for the control. Implementations - MUST be prepared to handle arbitrary contents of the controlValue - octet string, including zero bytes. It is absent only if there is no - value information which is associated with a control of its type. + control. Its format is defined by the specification of the control. + Implementations MUST be prepared to handle arbitrary contents of the Sermersheim Internet-Draft - Expires Jan 2004 Page 11 Lightweight Directory Access Protocol Version 3 + controlValue octet string, including zero bytes. It is absent only if + there is no value information which is associated with a control of + its type. controlValues 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 document does not specify any controls. Controls may be specified in other documents. The specification of a control consists of: - the OBJECT IDENTIFIER assigned to the control, - whether the control is always noncritical, always critical, or critical at the client's option, - the format of the controlValue contents of the control, @@ -651,38 +656,39 @@ BindRequest ::= [APPLICATION 0] SEQUENCE { version INTEGER (1 .. 127), name LDAPDN, authentication AuthenticationChoice } AuthenticationChoice ::= CHOICE { simple [0] OCTET STRING, -- 1 and 2 reserved sasl [3] SaslCredentials, + +Sermersheim Internet-Draft - Expires Jan 2004 Page 12 + Lightweight Directory Access Protocol Version 3 + ... } SaslCredentials ::= SEQUENCE { mechanism LDAPString, credentials OCTET STRING OPTIONAL } -Sermersheim Internet-Draft - Expires Jan 2004 Page 12 - Lightweight Directory Access Protocol Version 3 - Parameters of the Bind Request are: - version: A version number indicating the version of the protocol to be used in this protocol association. This document describes version 3 of the LDAP protocol. Note that there is no version negotiation, and the client just sets this parameter to the version it desires. If the server does not support the specified - version, it responds with protocolError in the resultCode field of - the BindResponse. + version, it MUST respond with protocolError in the resultCode + field of the BindResponse. - name: The name of the directory object that the client wishes to bind as. This field may take on a null value (a zero length string) for the purposes of anonymous binds ([AuthMeth] section 7) or when using SASL authentication ([AuthMeth] section 4.3). Server behavior is undefined when the name is a null value, simple authentication is used, and a password is specified. The server SHOULD NOT perform any alias dereferencing in determining the object to bind as. @@ -700,45 +706,42 @@ Authorization is the use of this authentication information when performing operations. Authorization MAY be affected by factors outside of the LDAP Bind Request, such as lower layer security services. 4.2.1. Processing of the Bind Request Upon receipt of a BindRequest, the server MUST ensure there are no outstanding operations in progress on the connection (this simplifies - server implementation). The server then proceeds to authenticate the - client in either a single-step, or multi-step bind process. Each step - requires the server to return a BindResponse to indicate the status - of authentication. + server implementation). To do this, the server may cause them to be + abandoned or allow them to finish. The server then proceeds to + authenticate the client in either a single-step, or multi-step bind + process. Each step requires the server to return a BindResponse to + indicate the status of authentication. + +Sermersheim Internet-Draft - Expires Jan 2004 Page 13 + Lightweight Directory Access Protocol Version 3 If the client did not bind before sending a request and receives an operationsError, it may then send a Bind Request. If this also fails or the client chooses not to bind on the existing connection, it may close the connection, reopen it and begin again by first sending a PDU with a Bind Request. This will aid in interoperating with servers implementing other versions of LDAP. -Sermersheim Internet-Draft - Expires Jan 2004 Page 13 - Lightweight Directory Access Protocol Version 3 - Clients MAY send multiple Bind Requests on a connection to change their credentials. Authentication from earlier binds is subsequently ignored. A failed or abandoned Bind Operation has the effect of leaving the LDAP association in an anonymous state. To arrive at a known authentication state after abandoning a bind operation, clients - may unbind, rebind, or make use of the BindResponse. If a SASL - transfer encryption or integrity mechanism has been negotiated, and - that mechanism does not support the changing of credentials from one - identity to another, then the client MUST instead establish a new - connection. + may unbind, rebind, or make use of the BindResponse. For some SASL authentication mechanisms, it may be necessary for the client to invoke the BindRequest multiple times. This is indicated by the server sending a BindResponse with the resultCode set to saslBindInProgress. This indicates that the server requires the client to send a new bind request, with the same sasl mechanism, to continue the authentication process. If at any stage the client wishes to abort the bind process it MAY unbind and then drop the underlying connection. Clients MUST NOT invoke operations between two Bind Requests made as part of a multi-stage bind. @@ -765,27 +768,28 @@ status of the client's request for authentication. A successful bind operation is indicated by a BindResponse with a resultCode set to success (0). Otherwise, an appropriate resultCode is set in the BindResponse. For bind, the protocolError (2) resultCode may be used to indicate that the version number supplied by the client is unsupported. If the client receives a BindResponse response where the resultCode was protocolError, it MUST close the connection as the server will be - unwilling to accept further operations. (This is for compatibility - with earlier versions of LDAP, in which the bind was always the first - operation, and there was no negotiation.) Sermersheim Internet-Draft - Expires Jan 2004 Page 14 Lightweight Directory Access Protocol Version 3 + unwilling to accept further operations. (This is for compatibility + with earlier versions of LDAP, in which the bind was always the first + operation, and there was no negotiation.) + 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 result. 4.3. Unbind Operation The function of the Unbind Operation is to terminate an LDAP @@ -819,42 +823,43 @@ One unsolicited notification (Notice of Disconnection) is defined in this document. 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. Note that this notification is NOT a response to an unbind requested by the client: the server MUST follow the procedures of section 4.3. This notification is intended to assist clients in - distinguishing between an error condition and a transient network - failure. As with a connection close due to network failure, the Sermersheim Internet-Draft - Expires Jan 2004 Page 15 Lightweight Directory Access Protocol Version 3 + distinguishing between an error condition and a transient network + failure. As with a connection close due to network failure, the client MUST NOT assume that any outstanding requests which modified the directory have succeeded or failed. The responseName is 1.3.6.1.4.1.1466.20036, the response field is absent, and the resultCode is used to indicate the reason for the disconnection. The following resultCode values have these meanings when used in this notification: - protocolError: The server has received data from the client in which the LDAPMessage structure could not be parsed. - - strongAuthRequired: The server has detected that an established - underlying security association protecting communication between - the client and server has unexpectedly failed or been compromised. + - strongAuthRequired: The server has detected that an establish + security association between the client and server has + unexpectedly failed or been compromised, or that the server now + requires the client to authenticate using a strong(er) mechanism. - unavailable: This server will stop accepting new connections and operations on all existing connections, and be unavailable for an extended period of time. The client may make use of an alternative server. After sending this notice, the server MUST close the connection. After receiving this notice, the client MUST NOT transmit any further on the connection, and may abruptly close the connection. @@ -874,27 +879,27 @@ scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefAliases (0), derefInSearching (1), derefFindingBaseObj (2), derefAlways (3) }, sizeLimit INTEGER (0 .. maxInt), - timeLimit INTEGER (0 .. maxInt), - typesOnly BOOLEAN, - filter Filter, Sermersheim Internet-Draft - Expires Jan 2004 Page 16 Lightweight Directory Access Protocol Version 3 + timeLimit INTEGER (0 .. maxInt), + typesOnly BOOLEAN, + filter Filter, attributes AttributeDescriptionList } Filter ::= CHOICE { and [0] SET SIZE (1..MAX) OF Filter, or [1] SET SIZE (1..MAX) OF Filter, not [2] Filter, equalityMatch [3] AttributeValueAssertion, substrings [4] SubstringFilter, greaterOrEqual [5] AttributeValueAssertion, lessOrEqual [6] AttributeValueAssertion, @@ -932,26 +937,27 @@ neverDerefAliases: Do not dereference aliases in searching or in locating the base object of the search. derefInSearching: While searching, dereference any alias object 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. Servers - SHOULD detect looping in this process to prevent denial of - service attacks and duplicate entries. Sermersheim Internet-Draft - Expires Jan 2004 Page 17 Lightweight Directory Access Protocol Version 3 + SHOULD detect looping in this process to prevent denial of + service attacks and duplicate entries. + derefFindingBaseObj: Dereference aliases in locating the base object of the search, but not when searching subordinates of the base object. derefAlways: Dereference aliases both in searching and in locating the base object of the search. - 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 @@ -990,26 +996,25 @@ to FALSE or Undefined, then the entry is ignored for the search. A filter of the "and" choice is TRUE if all the filters in the SET OF evaluate to TRUE, FALSE if at least one filter is FALSE, and otherwise Undefined. A filter of the "or" choice is FALSE if all of the filters in the SET OF evaluate to FALSE, TRUE if at least one filter is TRUE, and Undefined otherwise. A filter of the "not" choice is TRUE if the filter being negated is FALSE, FALSE if it is TRUE, and Undefined if it is Undefined. - The present match evaluates to TRUE where there is an attribute or - subtype of the specified attribute description present in an - Sermersheim Internet-Draft - Expires Jan 2004 Page 18 Lightweight Directory Access Protocol Version 3 + 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.) The matching rule for equalityMatch filter items is defined by the EQUALITY matching rule for the attribute type. The matching rule for AssertionValues in a substrings filter item is defined by the SUBSTR matching rule for the attribute type. The matching rule for greaterOrEqual and lessOrEqual filter items @@ -1048,26 +1053,25 @@ greaterOrEqual, lessOrEqual, approxMatch or extensibleMatch filter is not recognized by the server, a matching rule id in the extensibleMatch is not recognized by the server, the assertion value cannot be parsed, or the type of filtering requested is not implemented, then the filter is Undefined. Thus for example if a server did not recognize the attribute type shoeSize, a filter of (shoeSize=*) would evaluate to FALSE, and the filters (shoeSize=12), (shoeSize>=12) and (shoeSize<=12) would evaluate to Undefined. - Servers MUST NOT return errors if attribute descriptions or - matching rule ids are not recognized, or assertion values cannot - Sermersheim Internet-Draft - Expires Jan 2004 Page 19 Lightweight Directory Access Protocol Version 3 + Servers MUST NOT return errors if attribute descriptions or + matching rule ids are not recognized, or assertion values cannot be parsed. More details of filter processing are given in section 7.8 of [X.511]. - attributes: A list of the attributes to be returned from each entry which matches the search filter. There are two special values which may be used: an empty list with no attributes, and the attribute description string "*". Both of these signify that all user attributes are to be returned. (The "*" allows the client to request all user attributes in addition to any specified operational attributes). @@ -1104,53 +1108,51 @@ The results of the search attempted by the server upon receipt of a Search Request are returned in Search Responses, which are LDAP messages containing either SearchResultEntry, SearchResultReference, or SearchResultDone data types. SearchResultEntry ::= [APPLICATION 4] SEQUENCE { objectName LDAPDN, attributes PartialAttributeList } - PartialAttributeList ::= SEQUENCE OF SEQUENCE { - type AttributeDescription, - vals SET OF AttributeValue } - Sermersheim Internet-Draft - Expires Jan 2004 Page 20 Lightweight Directory Access Protocol Version 3 + PartialAttributeList ::= SEQUENCE OF SEQUENCE { + type AttributeDescription, + vals SET OF AttributeValue } -- implementors should note that the PartialAttributeList may -- have zero elements (if none of the attributes of that entry -- were requested, or could be returned), and that the vals set -- may also have zero elements (if types only was requested, or -- all values were excluded from the result.) SearchResultReference ::= [APPLICATION 19] SEQUENCE OF LDAPURL -- at least one LDAPURL element must be present SearchResultDone ::= [APPLICATION 5] LDAPResult Upon receipt of a Search Request, a server will perform the necessary search of the DIT. - If the LDAP association is operating over a connection-oriented - transport such as TCP, the server will return to the client a - sequence of responses in separate LDAP messages. There may be zero or - more responses containing SearchResultEntry, one for each entry found - during the search. There may also be zero or more responses - containing SearchResultReference, one for each area not explored by - this server during the search. The SearchResultEntry and - SearchResultReference PDUs may come in any order. Following all the - SearchResultReference responses and all SearchResultEntry responses - to be returned by the server, the server will return a response - containing the SearchResultDone, which contains an indication of - success, or detailing any errors that have occurred. + The server will return to the client a sequence of responses in + separate LDAP messages. There may be zero or more responses + containing SearchResultEntry, one for each entry found during the + search. There may also be zero or more responses containing + SearchResultReference, one for each area not explored by this server + during the search. The SearchResultEntry and SearchResultReference + PDUs may come in any order. Following all the SearchResultReference + responses and all SearchResultEntry responses to be returned by the + server, the server will return a response containing the + SearchResultDone, which contains an indication of success, or + detailing any errors that have occurred. 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. Some attributes may be constructed by the server and appear in a SearchResultEntry attribute list, although they are not stored attributes of an entry. Clients SHOULD NOT assume that all attributes can be modified, even if permitted by access control. @@ -1162,26 +1164,26 @@ 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. 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 - SearchResultReference entries, each containing a reference to another - set of servers for continuing the operation. A server MUST NOT return Sermersheim Internet-Draft - Expires Jan 2004 Page 21 Lightweight Directory Access Protocol Version 3 + SearchResultReference entries, each containing a reference to another + set of servers for continuing the operation. A server MUST NOT return any SearchResultReference if it has not located the baseObject and thus has not searched any entries; in this case it would return a SearchResultDone containing a referral resultCode. If a server holds a copy or partial copy of the subordinate naming context, it may use the search filter to determine whether or not to return a SearchResultReference response. Otherwise SearchResultReference responses are always returned when in scope. The SearchResultReference is of the same data type as the Referral. @@ -1219,26 +1221,26 @@ a shadow), and that LDAP-capable server (hostd) holds the subtree "OU=Roles,DC=Example,DC=NET". If a subtree search of "DC=Example,DC=NET" is requested to the contacted server, it may return the following: SearchResultEntry for DC=Example,DC=NET SearchResultEntry for CN=Manager,DC=Example,DC=NET SearchResultReference { ldap://hostb/OU=People,DC=Example,DC=NET ldap://hostc/OU=People,DC=Example,DC=NET - } - SearchResultReference { Sermersheim Internet-Draft - Expires Jan 2004 Page 22 Lightweight Directory Access Protocol Version 3 + } + SearchResultReference { ldap://hostd/OU=Roles,DC=Example,DC=NET } SearchResultDone (success) Client implementors should note that when following a SearchResultReference, additional SearchResultReference may be generated. Continuing the example, if the client contacted the server (hostb) and issued the search for the subtree "OU=People,DC=Example,DC=NET", the server might respond as follows: @@ -1276,26 +1278,27 @@ modification AttributeTypeAndValues } } AttributeTypeAndValues ::= SEQUENCE { type AttributeDescription, vals SET OF AttributeValue } 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 - perform any alias dereferencing in determining the object to be - modified. Sermersheim Internet-Draft - Expires Jan 2004 Page 23 Lightweight Directory Access Protocol Version 3 + perform any alias dereferencing in determining the object to be + modified. + - modification: A list of modifications to be performed on the entry. The entire list of entry modifications MUST be performed in the order they are listed, as a single atomic operation. While individual modifications may violate the directory schema, the resulting entry after the entire list of modifications is performed MUST conform to the requirements of the directory schema. The values that may be taken on by the 'operation' field in each modification construct have the following semantics respectively: @@ -1332,27 +1335,26 @@ performed if the Modify Response indicates successful completion of the Modify Operation. If the association changes or the connection fails, whether the modification occurred or not is indeterminate. The Modify Operation cannot be used to remove from an entry any of its distinguished values, those values which form the entry's relative distinguished name. An attempt to do so will result in the server returning the error notAllowedOnRDN. The Modify DN Operation described in section 4.9 is used to rename an entry. - Note that due to the simplifications made in LDAP, there is not a - direct mapping of the modifications in an LDAP ModifyRequest onto the - EntryModifications of a DAP ModifyEntry operation, and different - Sermersheim Internet-Draft - Expires Jan 2004 Page 24 Lightweight Directory Access Protocol Version 3 + Note that due to the simplifications made in LDAP, there is not a + direct mapping of the modifications in an LDAP ModifyRequest onto the + EntryModifications of a DAP ModifyEntry operation, and different implementations of LDAP-DAP gateways may use different means of representing the change. If successful, the final effect of the operations on the entry MUST be identical. 4.7. Add Operation The Add Operation allows a client to request the addition of an entry into the directory. The Add Request is defined as follows: AddRequest ::= [APPLICATION 8] SEQUENCE { @@ -1389,25 +1391,25 @@ 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 entries which can be added to the directory. Upon receipt of an Add Request, a server will attempt to add the requested entry. The result of the add attempt will be returned to the client in the Add Response, defined as follows: - AddResponse ::= [APPLICATION 9] LDAPResult - Sermersheim Internet-Draft - Expires Jan 2004 Page 25 Lightweight Directory Access Protocol Version 3 + AddResponse ::= [APPLICATION 9] LDAPResult + A response of success indicates that the new entry is present in the directory. 4.8. Delete Operation The Delete Operation allows a client to request the removal of an entry from the directory. The Delete Request is defined as follows: DelRequest ::= [APPLICATION 10] LDAPDN @@ -1443,27 +1445,27 @@ 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 be changed. - newrdn: the RDN that will form the leftmost component of the new name of the entry. +Sermersheim Internet-Draft - Expires Jan 2004 Page 26 + Lightweight Directory Access Protocol Version 3 + - deleteoldrdn: a boolean parameter that controls whether the old RDN attribute values are to be retained as attributes of the entry, or deleted from the entry. -Sermersheim Internet-Draft - Expires Jan 2004 Page 26 - Lightweight Directory Access Protocol Version 3 - - newSuperior: if present, this is the Distinguished Name of an existing object entry which becomes the immediate superior (parent)of the existing entry. 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 @@ -1499,27 +1501,28 @@ arbitrary movements of entries and subtrees between servers. 4.10. Compare Operation The Compare Operation allows a client to compare an assertion provided with an entry in the directory. The Compare Request is defined as follows: CompareRequest ::= [APPLICATION 14] SEQUENCE { entry LDAPDN, - ava AttributeValueAssertion } - - Parameters of the Compare Request are: Sermersheim Internet-Draft - Expires Jan 2004 Page 27 Lightweight Directory Access Protocol Version 3 + ava AttributeValueAssertion } + + Parameters of the Compare Request are: + - 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. - ava: the assertion with which an attribute in the entry is 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: @@ -1542,39 +1545,41 @@ that the server abandon an outstanding operation. The Abandon Request is defined as follows: AbandonRequest ::= [APPLICATION 16] MessageID The MessageID MUST be that of an operation which was requested earlier in this LDAP association. The abandon request itself has its own message id. This is distinct from the id of the earlier operation being abandoned. - There is no response defined in the Abandon Operation. Upon - transmission of an Abandon Operation, the server MAY abandon the - operation identified by the Message ID in the Abandon Request. - Operation responses are not sent for successfully abandoned - operations. Clients can determine that an operation has been - abandoned by performing a subsequent bind operation. + There is no response defined in the Abandon operation. Upon reciept + of an AbandonRequest, the server MAY abandon the operation identified + by the MessageID. Operation responses are not sent for successfully + abandoned operations, thus a client SHOULD NOT use the Abandon + operation when it needs an indication of whether the operation was + abandoned. For example, if a client performs an update operation + (Add, Modify, or ModifyDN), and it needs to know whether the + directory has changed due to the operation, it should not use the + Abandon operation to cancel the update operation. Abandon and Unbind operations cannot be abandoned. The ability to abandon other (particularly update) operations is at the discretion of the server. +Sermersheim Internet-Draft - Expires Jan 2004 Page 28 + Lightweight Directory Access Protocol Version 3 + In the event that a server receives an Abandon Request on a Search Operation in the midst of transmitting responses to the search, that server MUST cease transmitting entry responses to the abandoned request immediately, and MUST NOT send the SearchResponseDone. Of - -Sermersheim Internet-Draft - Expires Jan 2004 Page 28 - Lightweight Directory Access Protocol Version 3 - course, the server MUST ensure that only properly encoded LDAPMessage PDUs are transmitted. Clients MUST NOT send abandon requests for the same operation multiple times, and MUST also be prepared to receive results from operations it has abandoned (since these may have been in transit when the abandon was requested, or are not able to be abandoned). Servers MUST discard abandon requests for message IDs they do not recognize, for operations which cannot be abandoned, and for @@ -1600,57 +1605,87 @@ IDENTIFIER corresponding to the request. The requestValue is information in a form defined by that request, encapsulated inside an OCTET STRING. The server will respond to this with an LDAPMessage containing the ExtendedResponse. ExtendedResponse ::= [APPLICATION 24] SEQUENCE { COMPONENTS OF LDAPResult, responseName [10] LDAPOID OPTIONAL, - response [11] OCTET STRING OPTIONAL } + responseValue [11] OCTET STRING OPTIONAL } If the server does not recognize the request name, it MUST return only the response fields from LDAPResult, containing the protocolError result code. + The requestValue and responseValue fields contain any information + associated with the operation. The format of these fields is defined + by the specification of the extended operation. Implementations MUST + +Sermersheim Internet-Draft - Expires Jan 2004 Page 29 + Lightweight Directory Access Protocol Version 3 + + be prepared to handle arbitrary contents of these fields, including + zero bytes. Values that are defined in terms of ASN.1 and BER encoded + according to Section 5.1, also follow the extensibility rules in + Section 4. + + Extended operations may be specified in other documents. The + specification of an extended operation consists of: + + - the OBJECT IDENTIFIER assigned to the ExtendedRequest.requestName + (and possibly ExtendedResponse.responseName), + + - the format of the contents of the requestValue and responseValue + (if any), + + - the semantics of the operation, + + Servers list the requestName of all ExtendedRequests they recognize + in the supportedExtension attribute [Models] in the root DSE. + + 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. + 4.13. Start TLS Operation The Start Transport Layer Security (StartTLS) operation provides the ability to establish Transport Layer Security [RFC2246] on an LDAP connection. 4.13.1. Start TLS Request -Sermersheim Internet-Draft - Expires Jan 2004 Page 29 - Lightweight Directory Access Protocol Version 3 - A client requests TLS establishment by transmitting a Start TLS request PDU to the server. The Start TLS request is defined in terms of an ExtendedRequest. The requestName is "1.3.6.1.4.1.1466.20037", and the requestValue field is absent. The client MUST NOT send any PDUs on this connection following this request until it receives a Start TLS extended response. 4.13.2. Start TLS Response When a Start TLS request is made, servers supporting the operation MUST return a Start TLS response PDU to the requestor. The Start TLS response responseName is also "1.3.6.1.4.1.1466.20037", and the response field is absent. The server MUST set the resultCode field to either success or one of the other values outlined in section 4.13.2.2. 4.13.2.1. "Success" Response +Sermersheim Internet-Draft - Expires Jan 2004 Page 30 + Lightweight Directory Access Protocol Version 3 + If the Start TLS Response contains a resultCode of success, this indicates that the server is willing and able to negotiate TLS. Refer to section 5.3 of [AuthMeth] for details. 4.13.2.2. Response other than "success" If the ExtendedResponse contains a resultCode other than success, this indicates that the server is unwilling or unable to negotiate TLS. The following resultCodes have these meanings for this operation: @@ -1669,24 +1704,20 @@ If the server does not support TLS (whether by design or by current configuration), it MUST set the resultCode 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. 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 - -Sermersheim Internet-Draft - Expires Jan 2004 Page 30 - Lightweight Directory Access Protocol Version 3 - 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. 4.13.3. Closing a TLS Connection Two forms of TLS connection closure--graceful and abrupt--are supported. 4.13.3.1. Graceful Closure @@ -1694,27 +1725,34 @@ Either the client or server MAY terminate the TLS connection and leave the LDAP connection intact by sending a TLS closure alert. Before sending a TLS closure alert, the client MUST either wait for any outstanding LDAP operations to complete, or explicitly abandon them. After the initiator of a close has sent a TLS closure alert, it MUST discard any TLS messages until it has received a TLS closure alert from the other party. It will cease to send TLS Record Protocol + +Sermersheim Internet-Draft - Expires Jan 2004 Page 31 + Lightweight Directory Access Protocol Version 3 + PDUs, and following the receipt of the alert, MAY send and receive LDAP PDUs. The other party, if it receives a TLS closure alert, MUST immediately transmit a TLS closure alert. It will subsequently cease to send TLS Record Protocol PDUs, and MAY send and receive LDAP PDUs. + After the TLS connection has been closed, the server MUST NOT send + responses to any request message received before the TLS closure. + 4.13.3.2. Abrupt Closure Either the client or server MAY abruptly close the TLS connection by dropping the underlying transfer protocol connection. In this circumstance, a server MAY send the client a Notice of Disconnection before dropping the underlying LDAP connection. 5. Protocol Element Encodings and Transfer One underlying service is defined here. Clients and servers SHOULD @@ -1725,40 +1763,40 @@ The protocol elements of LDAP are encoded for exchange using the Basic Encoding Rules (BER) [X.690] of ASN.1 [X.680]. However, due to the high overhead involved in using certain elements of the BER, the following additional restrictions are placed on BER-encodings of LDAP protocol elements: (1) Only the definite form of length encoding will be used. (2) OCTET STRING values will be encoded in the primitive form only. -Sermersheim Internet-Draft - Expires Jan 2004 Page 31 - Lightweight Directory Access Protocol Version 3 - (3) If the value of a BOOLEAN type is true, the encoding MUST have its contents octets set to hex "FF". (4) If a value of a type is its default value, it MUST be absent. Only some BOOLEAN and INTEGER types have default values in this protocol definition. These restrictions do not apply to ASN.1 types encapsulated inside of OCTET STRING values, such as attribute values, unless otherwise noted. 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. +Sermersheim Internet-Draft - Expires Jan 2004 Page 32 + Lightweight Directory Access Protocol Version 3 + 5.2.1. Transmission Control Protocol (TCP) The encoded LDAPMessage PDUs are mapped directly onto the TCP bytestream using the BER-based encoding described in section 5.1. It is recommended that server implementations running over the TCP provide a protocol listener on the assigned port, 389. Servers may instead provide a listener on a different port number. Clients MUST support contacting servers on any valid TCP port. 6. Implementation Guidelines @@ -1769,48 +1807,47 @@ type names and implement the syntaxes specified in [Syntaxes]. Servers MAY also recognize additional attribute type names. 6.2. Client Implementations Clients that follow referrals or search continuation references MUST ensure that they do not loop between servers. They MUST NOT repeatedly contact the same server for the same request with the same target entry name, scope and filter. Some clients use a counter that is incremented each time referral handling occurs for an operation, - and these kinds of clients MUST be able to handle a DIT with at least - ten layers of naming contexts between the root and a leaf entry. + and these kinds of clients MUST be able to handle at least ten nested + referrals between the root and a leaf entry. In the absence of prior agreements with servers, clients SHOULD NOT assume that servers support any particular schemas beyond those referenced in section 6.1. Different schemas can have different attribute types with the same names. The client can retrieve the - -Sermersheim Internet-Draft - Expires Jan 2004 Page 32 - Lightweight Directory Access Protocol Version 3 - subschema entries referenced by the subschemaSubentry attribute in the entries held by the server. 7. Security Considerations - When used with a connection-oriented transport, this version of the - protocol provides facilities for simple authentication using a - cleartext password, as well as any SASL mechanism [RFC2222]. SASL - allows for integrity and privacy services to be negotiated. + This version of the protocol provides facilities for simple + authentication using a cleartext password, as well as any SASL + mechanism [RFC2222]. SASL allows for integrity and privacy services + to be negotiated. It is also permitted that the server can return its credentials to the client, if it chooses to do so. Use of cleartext password is strongly discouraged where the underlying transport service cannot guarantee confidentiality and may result in disclosure of the password to unauthorized parties. +Sermersheim Internet-Draft - Expires Jan 2004 Page 33 + Lightweight Directory Access Protocol Version 3 + When used with SASL, it should be noted that the name field of the BindRequest is not protected against modification. Thus if the distinguished name of the client (an LDAPDN) is agreed through the negotiation of the credentials, it takes precedence over any value in the unprotected name field. Implementations which cache attributes and entries obtained via LDAP MUST ensure that access controls are maintained if that information is to be provided to multiple clients, since servers may have access control policies which prevent the return of entries or attributes in @@ -1831,40 +1868,40 @@ This document is an update to RFC 2251, by Mark Wahl, Tim Howes, and Steve Kille. Their work along with the input of individuals of the IETF LDAPEXT, LDUP, LDAPBIS, and other Working Groups is gratefully acknowledged. 9. Normative References [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts, Models and Service", 1993. -Sermersheim Internet-Draft - Expires Jan 2004 Page 33 - Lightweight Directory Access Protocol Version 3 - [Roadmap] K. Zeilenga (editor), "LDAP: Technical Specification Road Map", draft-ietf-ldapbis-roadmap-xx.txt (a work in progress). [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March 1997. [X.680] ITU-T Recommendation X.680 (1997) | ISO/IEC 8824-1:1998 Information Technology - Abstract Syntax Notation One (ASN.1): Specification of basic notation [X.690] ITU-T Rec. X.690, "Specification of ASN.1 encoding rules: Basic, Canonical, and Distinguished Encoding Rules", 1994. [LDAPIANA] K. Zeilenga, "IANA Considerations for LDAP", draft-ietf- ldapbis-xx.txt (a work in progress). +Sermersheim Internet-Draft - Expires Jan 2004 Page 34 + Lightweight Directory Access Protocol Version 3 + [ISO10646] Universal Multiple-Octet Coded Character Set (UCS) - Architecture and Basic Multilingual Plane, ISO/IEC 10646-1 : 1993. [RFC2279] Yergeau, F., "UTF-8, a transformation format of Unicode and ISO 10646", RFC 2279, January 1998. [Models] K. Zeilenga, "LDAP: The Models", draft-ietf-ldapbis- models-xx.txt (a work in progress). @@ -1887,43 +1924,44 @@ [AuthMeth] R. Harrison (editor), "LDAP: Authentication Methods", draft-ietf-ldapbis-authmeth-xx.txt, (a work in progress). [RFC2222] Meyers, J., "Simple Authentication and Security Layer", RFC 2222, October 1997. [SASLPrep] Zeilenga, K., "Stringprep profile for user names and passwords", draft-ietf-sasl-saslprep-xx.txt, (a work in progress). -Sermersheim Internet-Draft - Expires Jan 2004 Page 34 - Lightweight Directory Access Protocol Version 3 - [Unicode] The Unicode Consortium, "The Unicode Standard, Version 3.2.0" is defined by "The Unicode Standard, Version 3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5), as amended by the "Unicode Standard Annex #27: Unicode 3.1" (http://www.unicode.org/reports/tr27/) and by the "Unicode Standard Annex #28: Unicode 3.2" (http://www.unicode.org/reports/tr28/). 10. Editor's Address Jim Sermersheim Novell, Inc. 1800 South Novell Place Provo, Utah 84606, USA jimse@novell.com - +1 801 861-3088 Sermersheim Internet-Draft - Expires Jan 2004 Page 35 Lightweight Directory Access Protocol Version 3 + +1 801 861-3088 + +Sermersheim Internet-Draft - Expires Jan 2004 Page 36 + Lightweight Directory Access Protocol Version 3 + Appendix A - LDAP Result Codes This normative appendix details additional considerations regarding LDAP result codes and provides a brief, general description of each LDAP result code enumerated in Section 4.1.10. Additional result codes MAY be defined for use with extensions. Client implementations SHALL treat any result code which they do not recognize as an unknown error condition. @@ -1937,68 +1975,45 @@ saslBindInProgress(14). The success(0), compareTrue(6), and compare(7) result codes indicate successful completion (and, hence, are called to as "successful" result codes). The referral(10) and saslBindInProgress(14) indicate the client is required to take additional action to complete the operation A.2 Error Result Codes - -A.3 Classes and Precedence of Error Result Codes - - Result codes that indicate error conditions (and, hence, are called - "error" result codes) fall into 6 classes. The following list - specifies the precedence of error classes to be used when more than - one error is detected [X511]: - 1) Name Errors (codes 32 - 34, 36) - - a problem related to a name (DN or RDN), - 2) Update Errors (codes 64 - 69, 71) - - a problem related to an update operation, - 3) Attribute Errors (codes 16 - 21) - - a problem related to a supplied attribute, - 4) Security Errors (codes 8, 13, 48 - 50) - - a security related problem, - 5) Service Problem (codes 3, 4, 7, 11, 12, 51 - 54, 80) - - a problem related to the provision of the service, and - 6) Protocol Problem (codes 1, 2) - - a problem related to protocol structure or semantics. - - If the server detects multiple errors simultaneously, the server - SHOULD report the error with the highest precedence. - Existing LDAP result codes are described as follows: success (0) -Sermersheim Internet-Draft - Expires Jan 2004 Page 36 - Lightweight Directory Access Protocol Version 3 - Indicates successful completion of an operation. This result code is normally not returned by the compare operation, see compareFalse (5) and compareTrue (6). It is possible that a future extension mechanism would allow this to be returned by a compare operation. operationsError (1) Indicates that the operation is not properly sequenced with relation to other operations (of same or different type). For example, this code is returned if the client attempts to Start TLS [RFC2246] while there are other operations outstanding or if TLS was already established. protocolError (2) +Sermersheim Internet-Draft - Expires Jan 2004 Page 37 + Lightweight Directory Access Protocol Version 3 + Indicates the server received data which has incorrect structure. For bind operation only, the code may be resulted to indicate the server does not support the requested protocol version. timeLimitExceeded (3) Indicates that the time limit specified by the client was exceeded before the operation could be completed. @@ -2014,42 +2029,42 @@ assertion has evaluated to FALSE. This result code is normally only returned by the compare operation. compareTrue (6) Indicates that the operation successfully completes and the assertion has evaluated to TRUE. -Sermersheim Internet-Draft - Expires Jan 2004 Page 37 - Lightweight Directory Access Protocol Version 3 - This result code is normally only returned by the compare operation. authMethodNotSupported (7) Indicates that the authentication method or mechanism is not supported. strongAuthRequired (8) Except when returned in a Notice of Disconnect (see section 4.4.1), this indicates that the server requires the client to authentication using a strong(er) mechanism. referral (10) Indicates that a referral needs to be chased to complete the operation (see section 4.1.11). +Sermersheim Internet-Draft - Expires Jan 2004 Page 38 + Lightweight Directory Access Protocol Version 3 + adminLimitExceeded (11) Indicates that an administrative limit has been exceeded. unavailableCriticalExtension (12) Indicates that server cannot perform a critical extension (see section 4.1.12). confidentialityRequired (13) @@ -2062,41 +2077,41 @@ request, with the same SASL mechanism, to continue the authentication process (see section 4.2). noSuchAttribute (16) Indicates that the named entry does not contain the specified attribute or attribute value. undefinedAttributeType (17) -Sermersheim Internet-Draft - Expires Jan 2004 Page 38 - Lightweight Directory Access Protocol Version 3 - Indicates that a request field contains an undefined attribute type. inappropriateMatching (18) Indicates that a request cannot be completed due to an inappropriate matching. constraintViolation (19) Indicates that the client supplied an attribute value which does not conform to constraints placed upon it by the data model. For example, this code is returned when the multiple values are supplied to an attribute which has a SINGLE-VALUE constraint. +Sermersheim Internet-Draft - Expires Jan 2004 Page 39 + Lightweight Directory Access Protocol Version 3 + attributeOrValueExists (20) Indicates that the client supplied an attribute or value to be added to an entry already exists. invalidAttributeSyntax (21) Indicates that a purported attribute value does not conform to the syntax of the attribute. @@ -2110,42 +2125,42 @@ alias has been dereferenced which names no object. invalidDNSyntax (34) Indicates that a LDAPDN or RelativeLDAPDN field (e.g. search base, target entry, ModifyDN newrdn, etc.) of a request does not conform to the required syntax or contains attribute values which do not conform to the syntax of the attribute's type. -Sermersheim Internet-Draft - Expires Jan 2004 Page 39 - Lightweight Directory Access Protocol Version 3 - aliasDereferencingProblem (36) Indicates that a problem occurred while dereferencing an alias. Typically an alias was encountered in a situation where it was not allowed or where access was denied. inappropriateAuthentication (48) Indicates the server requires the client which had attempted to bind anonymously or without supplying credentials to provide some form of credentials, invalidCredentials (49) Indicates the supplied password or SASL credentials are invalid. insufficientAccessRights (50) +Sermersheim Internet-Draft - Expires Jan 2004 Page 40 + Lightweight Directory Access Protocol Version 3 + Indicates that the client does not have sufficient access rights to perform the operation. busy (51) Indicates that the server is busy. unavailable (52) Indicates that the server is shutting down or a subsystem @@ -2159,59 +2174,59 @@ loopDetect (54) Indicates that the server has detected an internal loop. namingViolation (64) Indicates that the entry name violates naming restrictions. objectClassViolation (65) -Sermersheim Internet-Draft - Expires Jan 2004 Page 40 - Lightweight Directory Access Protocol Version 3 - Indicates that the entry violates object class restrictions. notAllowedOnNonLeaf (66) Indicates that operation is inappropriately acting upon a non-leaf entry. notAllowedOnRDN (67) Indicates that the operation is inappropriately attempting to remove a value which forms the entry's relative distinguished name. entryAlreadyExists (68) Indicates that the request cannot be added fulfilled as the entry already exists. +Sermersheim Internet-Draft - Expires Jan 2004 Page 41 + Lightweight Directory Access Protocol Version 3 + objectClassModsProhibited (69) Indicates that the attempt to modify the object class(es) of an entry objectClass attribute is prohibited. For example, this code is returned when a when a client attempts to modify the structural object class of an entry. affectsMultipleDSAs (71) Indicates that the operation cannot be completed as it affects multiple servers (DSAs). other (80) Indicates the server has encountered an internal error. -Sermersheim Internet-Draft - Expires Jan 2004 Page 41 +Sermersheim Internet-Draft - Expires Jan 2004 Page 42 Lightweight Directory Access Protocol Version 3 Appendix B - Complete ASN.1 Definition This appendix is normative. Lightweight-Directory-Access-Protocol-V3 DEFINITIONS IMPLICIT TAGS EXTENSIBILITY IMPLIED ::= @@ -2255,21 +2270,21 @@ LDAPDN ::= LDAPString RelativeLDAPDN ::= LDAPString AttributeDescription ::= LDAPString -- Constrained to attributedescription -- [Models] AttributeDescriptionList ::= SEQUENCE OF -Sermersheim Internet-Draft - Expires Jan 2004 Page 42 +Sermersheim Internet-Draft - Expires Jan 2004 Page 43 Lightweight Directory Access Protocol Version 3 AttributeDescription AttributeValue ::= OCTET STRING AttributeValueAssertion ::= SEQUENCE { attributeDesc AttributeDescription, assertionValue AssertionValue } @@ -2313,21 +2328,21 @@ -- 37-47 unused -- inappropriateAuthentication (48), invalidCredentials (49), insufficientAccessRights (50), busy (51), unavailable (52), unwillingToPerform (53), loopDetect (54), -- 55-63 unused -- -Sermersheim Internet-Draft - Expires Jan 2004 Page 43 +Sermersheim Internet-Draft - Expires Jan 2004 Page 44 Lightweight Directory Access Protocol Version 3 namingViolation (64), objectClassViolation (65), notAllowedOnNonLeaf (66), notAllowedOnRDN (67), entryAlreadyExists (68), objectClassModsProhibited (69), -- 70 reserved for CLDAP -- affectsMultipleDSAs (71), @@ -2371,21 +2386,21 @@ serverSaslCreds [7] OCTET STRING OPTIONAL } UnbindRequest ::= [APPLICATION 2] NULL SearchRequest ::= [APPLICATION 3] SEQUENCE { baseObject LDAPDN, scope ENUMERATED { baseObject (0), singleLevel (1), -Sermersheim Internet-Draft - Expires Jan 2004 Page 44 +Sermersheim Internet-Draft - Expires Jan 2004 Page 45 Lightweight Directory Access Protocol Version 3 wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefAliases (0), derefInSearching (1), derefFindingBaseObj (2), derefAlways (3) }, sizeLimit INTEGER (0 .. maxInt), timeLimit INTEGER (0 .. maxInt), @@ -2429,21 +2444,21 @@ vals SET OF AttributeValue } SearchResultReference ::= [APPLICATION 19] SEQUENCE OF LDAPURL SearchResultDone ::= [APPLICATION 5] LDAPResult ModifyRequest ::= [APPLICATION 6] SEQUENCE { object LDAPDN, modification SEQUENCE OF SEQUENCE { -Sermersheim Internet-Draft - Expires Jan 2004 Page 45 +Sermersheim Internet-Draft - Expires Jan 2004 Page 46 Lightweight Directory Access Protocol Version 3 operation ENUMERATED { add (0), delete (1), replace (2) }, modification AttributeTypeAndValues } } AttributeTypeAndValues ::= SEQUENCE { type AttributeDescription, @@ -2481,25 +2496,25 @@ AbandonRequest ::= [APPLICATION 16] MessageID ExtendedRequest ::= [APPLICATION 23] SEQUENCE { requestName [0] LDAPOID, requestValue [1] OCTET STRING OPTIONAL } ExtendedResponse ::= [APPLICATION 24] SEQUENCE { COMPONENTS OF LDAPResult, responseName [10] LDAPOID OPTIONAL, - response [11] OCTET STRING OPTIONAL } + responseValue [11] OCTET STRING OPTIONAL } END -Sermersheim Internet-Draft - Expires Jan 2004 Page 46 +Sermersheim Internet-Draft - Expires Jan 2004 Page 47 Lightweight Directory Access Protocol Version 3 Appendix C - Change History C.1 Changes made to RFC 2251: C.1.1 Editorial @@ -2542,21 +2557,21 @@ the transfer encoding is present in attributeDesc, the AssertionValue is encoded as specified by the option...". Previously, only the ;binary option was mentioned. C.2.3 Sections 4.2, 4.9, 4.10 - Added alias dereferencing specifications. In the case of modDN, followed precedent set on other update operations (... alias is not dereferenced...) In the case of bind and compare stated that -Sermersheim Internet-Draft - Expires Jan 2004 Page 47 +Sermersheim Internet-Draft - Expires Jan 2004 Page 48 Lightweight Directory Access Protocol Version 3 servers SHOULD NOT dereference aliases. Specifications were added because they were missing from the previous version and caused interoperability problems. Concessions were made for bind and compare (neither should have ever allowed alias dereferencing) by using SHOULD NOT language, due to the behavior of some existing implementations. C.2.4 Sections 4.5 and Appendix A @@ -2598,21 +2613,21 @@ by a lower layer" to "the underlying transport service cannot guarantee confidentiality" C.3.6 Section 4.5.2 - Removed all mention of ExtendedResponse due to lack of implementation. C.4 Changes made to draft-ietf-ldapbis-protocol-02.txt: -Sermersheim Internet-Draft - Expires Jan 2004 Page 48 +Sermersheim Internet-Draft - Expires Jan 2004 Page 49 Lightweight Directory Access Protocol Version 3 C.4.1 Section 4 - Removed "typically" from "and is typically transferred" in the first paragraph. We know of no (and can conceive of no) case where this isn't true. - Added "Section 5.1 specifies how the LDAP protocol is encoded." To the first paragraph. Added this cross reference for readability. - Changed "version 3 " to "version 3 or later" in the second @@ -2654,21 +2669,21 @@ controls). C.4.6 Section 4.4 - Changed "One unsolicited notification is defined" to "One unsolicited notification (Notice of Disconnection) is defined" in the third paragraph. For clarity and readability. C.4.7 Section 4.5.1 -Sermersheim Internet-Draft - Expires Jan 2004 Page 49 +Sermersheim Internet-Draft - Expires Jan 2004 Page 50 Lightweight Directory Access Protocol Version 3 - Changed "checking for the existence of the objectClass attribute" to "checking for the presence of the objectClass attribute" in the last paragraph. This was done as a measure of consistency (we use the terms present and presence rather than exists and existence in search filters). C.4.8 Section 4.5.3 @@ -2710,21 +2725,21 @@ whether there can be more than one value of an attribute of that type in an entry, the syntax to which the values must conform, the kinds of matching which can be performed on values of that attribute, and other functions." to " An attribute is a description (a type and zero or more options) with one or more associated values. The attribute type governs whether the attribute can have multiple values, the syntax and matching rules used to construct and compare values of that attribute, and other functions. Options indicate modes of transfer and other -Sermersheim Internet-Draft - Expires Jan 2004 Page 50 +Sermersheim Internet-Draft - Expires Jan 2004 Page 51 Lightweight Directory Access Protocol Version 3 functions.". This points out that an attribute consists of both the type and options. C.5.2 Section 4 - Changed "Section 5.1 specifies the encoding rules for the LDAP protocol" to "Section 5.1 specifies how the protocol is encoded and transferred." @@ -2767,21 +2782,21 @@ - Changed the wording regarding 'equally capable' referrals to "If multiple URLs are present, the client assumes that any URL may be used to progress the operation.". The previous language implied that the server MUST enforce rules that it was practically incapable of. The new language highlights the original intent-- that is, that any of the referrals may be used to progress the operation, there is no inherent 'weighting' mechanism. C.5.7 Section 4.5.1 and Appendix A -Sermersheim Internet-Draft - Expires Jan 2004 Page 51 +Sermersheim Internet-Draft - Expires Jan 2004 Page 52 Lightweight Directory Access Protocol Version 3 - Added the comment "-- initial and final can occur at most once", to clarify this restriction. C.5.8 Section 5.1 - Changed heading from "Mapping Onto BER-based Transport Services" to "Protocol Encoding". @@ -2823,21 +2838,21 @@ doc now specifies a difference between transfer and tagging options and describes the semantics of each, and how and when subtyping rules apply. Now allow options to be transmitted in any order but disallow any ordering semantics to be implied. These changes are the result of ongoing input from an engineering team designed to deal with ambiguity issues surrounding attribute options. C.7.3 Sections 4.1.5.1 and 4.1.6 -Sermersheim Internet-Draft - Expires Jan 2004 Page 52 +Sermersheim Internet-Draft - Expires Jan 2004 Page 53 Lightweight Directory Access Protocol Version 3 - Refer to non "binary" transfer encodings as "native encoding" rather than "string" encoding to clarify and avoid confusion. C.8 Changes made to draft-ietf-ldapbis-protocol-06.txt: C.8.1 Title - Changed to "LDAP: The Protocol" to be consisted with other working @@ -2879,21 +2894,21 @@ C.8.7 Relationship to X.500 - Removed section. It has been moved to [Roadmap] C.8.8 Server Specific Data Requirements - Removed section. It has been moved to [Models] C.8.9 Elements of Protocol -Sermersheim Internet-Draft - Expires Jan 2004 Page 53 +Sermersheim Internet-Draft - Expires Jan 2004 Page 54 Lightweight Directory Access Protocol Version 3 - Added "Section 5.1 specifies how the protocol is encoded and transferred." to the end of the first paragraph for reference. - Reworded notes about extensibility, and now talk about implied extensibility and the use of ellipses in the ASN.1 - Removed references to LDAPv2 in third and fourth paragraphs. @@ -2936,21 +2951,21 @@ - Clarified intent regarding exactly what is to be BER encoded. - Clarified that clients must not expect ;binary when not asking for it (;binary, as opposed to ber encoded data). C.8.17 Attribute - Use the term "attribute description" in lieu of "type" -Sermersheim Internet-Draft - Expires Jan 2004 Page 54 +Sermersheim Internet-Draft - Expires Jan 2004 Page 55 Lightweight Directory Access Protocol Version 3 - Clarified the fact that clients cannot rely on any apparent ordering of attribute values. C.8.18 LDAPResult - To resultCode, added ellipses "..." to the enumeration to indicate extensibility. and added a note, pointing to [LDAPIANA] @@ -2993,29 +3008,30 @@ - Added as normative appendix A C.8.25 ASN.1 - Added EXTENSIBILITY IMPLIED - Added a number of comments holding referenced to [Models] and [ISO10646]. -Sermersheim Internet-Draft - Expires Jan 2004 Page 55 +Sermersheim Internet-Draft - Expires Jan 2004 Page 56 Lightweight Directory Access Protocol Version 3 - Removed AttributeType. It is not used. C.9 Changes made to draft-ietf-ldapbis-protocol-07.txt: - Removed all mention of transfer encodings and the binary attribute - option + option. Please refer to draft-legg-ldap-binary-00.txt and draft- + legg-ldap-transfer-00.txt - Further alignment with [Models]. - Added extensibility ellipsis to protocol op choice - In 4.1.1, clarified when connections may be dropped due to malformed PDUs - Specified which matching rules and syntaxes are used for various filter items @@ -3046,21 +3062,21 @@ C.11 Changes made to draft-ietf-ldapbis-protocol-09.txt: - Fixed formatting C.12 Changes made to draft-ietf-ldapbis-protocol-10.txt: C.12.1 Section 4.1.4: - Removed second paragraph as this language exists in MODELS -Sermersheim Internet-Draft - Expires Jan 2004 Page 56 +Sermersheim Internet-Draft - Expires Jan 2004 Page 57 Lightweight Directory Access Protocol Version 3 C.12.2 Section 4.2.1: - Replaced fourth paragraph. It was accidentally removed in an earlier edit. C.12.2 Section 4.13: - Added section describing the StartTLS operation (moved from @@ -3101,25 +3117,24 @@ C.15 Changes made to draft-ietf-ldapbis-protocol-13.txt C.15.1 Section 2 & various - Added definitions for LDAP connection, TLS connection, and LDAP association, and updated appropriate fields to use proper terms. C.15.2 Section 4.2 - Added text to authentication, specifying the way in which textual strings used as passwords are to be prepared. -C.15.3 Section 4.5.1 - -Sermersheim Internet-Draft - Expires Jan 2004 Page 57 +Sermersheim Internet-Draft - Expires Jan 2004 Page 58 Lightweight Directory Access Protocol Version 3 +C.15.3 Section 4.5.1 - Clarified derefInSearching. Specifically how it works in terms of subtree and one level searches C.15.4 Section 4.5.2 - Changed MUST to SHOULD for returning textual attribute name, The MUST is unreasonable. There are likely cases (such as when the server knows multiple attributes in separate entries of a search result set share the same short name) where returning a numericoid is better than returning a short name. That is, the MUST may @@ -3128,20 +3143,111 @@ security consideration. C.15.4 Section 4.9 - Made modify consistent with add in regards to teh need of parent entries already existing. C.15.6 Section 4.13.2.2 - Removed wording indicating that referrals can be returned from StartTLS +C.16 Changes made to draft-ietf-ldapbis-protocol-14.txt + +C.16.1 Section 4.1.9 + + - Added: If a server detects multiple errors for an operation, only + one resultCode is returned. The server should return the + resultCode that best indicates the nature of the error + encountered. + +C.16.2 Section 4.1.11 + - Added: controlValues that are defined in terms of ASN.1 and BER + encoded according to Section 5.1, also follow the extensibility + rules in Section 4. + + - Removed: "If a SASL transfer encryption or integrity mechanism has + been negotiated, that mechanism does not support the changing of + credentials from one identity to another, then the client MUST + instead establish a new connection." + + Each SASL negotiation is, generally, independent of other SASL + negotiations. If there were dependencies between multiple + negotiations of a particular mechanism, the mechanism technical + specification should detail how applications are to deal with + them. LDAP should not require any special handling. And if an LDAP + client had used such a mechanism, it would have the option of + using another mechanism. + +C.16.3 Section 4.5.2 and Section 7 + - Removed: "If the LDAP association is operating over a connection- + oriented transport such as TCP" + +Sermersheim Internet-Draft - Expires Jan 2004 Page 59 + Lightweight Directory Access Protocol Version 3 + + This is always true. + +C.16.4 Section 4.11 + - Added: thus a client SHOULD NOT use the Abandon operation when it + needs an indication of whether the operation was abandoned. For + example, if a client performs an update operation (Add, Modify, or + ModifyDN), and it needs to know whether the directory has changed + due to the operation, it should not use the Abandon operation to + cancel the update operation. Clients can determine that an + operation has been abandoned by performing a subsequent bind + operation. + +C.16.5 Section 4.12 + + - Added: + "The requestValue and responseValue fields contain any information + associated with the operation. The format of these fields is + defined by the specification of the extended operation. + Implementations MUST be prepared to handle arbitrary contents of + these fields, including zero bytes. Values that are defined in + terms of ASN.1 and BER encoded according to Section 5.1, also + follow the extensibility rules in Section 4. + + Extended operations may be specified in other documents. The + specification of an extended operation consists of: + + - the OBJECT IDENTIFIER assigned to the + ExtendedRequest.requestName (and possibly + ExtendedResponse.responseName), + + - the format of the contents of the requestValue and responseValue + (if any), + + - the semantics of the operation, + + Servers list the requestName of all ExtendedRequests they + recognize in the supportedExtension attribute [Models] in the root + DSE. + + 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 was to align with controls and control values. + +C.16.6 Section 4.13.3.1 + + - Added: After the TLS connection has been closed, the server MUST + NOT send responses to any request message received before the TLS + closure. + +C.16.7 Section A2 + - Removed precedence rules + +Sermersheim Internet-Draft - Expires Jan 2004 Page 60 + Lightweight Directory Access Protocol Version 3 + Appendix D - Outstanding Work Items D.0 General - Integrate notational consistency agreements WG will discuss notation consistency. Once agreement happens, reconcile draft. - Reconcile problems with [Models]. Section 3.2 was wholly removed. There were some protocol semantics in that section that need to be brought back. Specifically, there was the notion of the server implicitly adding objectclass superclasses when a value is added. @@ -3151,111 +3257,72 @@ - While there is a result code appendix, ensure it speaks of result codes in a general sense, and only highlight specific result codes in the context of an operation when that operation ties more specific meanings to that result code. D.2 Verify references. - Many referenced documents have changed. Ensure references and section numbers are correct. -D.3 Usage of Naming Context - - - Make sure occurrences of "namingcontext" and "naming context" are - consistent with [Models]. Use in section 6.2 should be reworked. - It's layers of indirection that matter, not number of contexts. - (That is, referrals can be returned for a number of reasons (cross - reference, superior, subordinate, busy, not master, etc.) - -Sermersheim Internet-Draft - Expires Jan 2004 Page 58 - Lightweight Directory Access Protocol Version 3 - - Other uses are fine. - -D.4 Review 2119 usage - -D.5 Reconcile with I-D Nits - -D.23 Section 4.5.3 - - - A server MUST NOT return any SearchResultReference if it has not - located the baseObject and thus has not searched any entries; in - this case it would return a SearchResultDone containing a referral - resultCode. - - - Add "Similarly, a server MUST NOT return a SearchResultReference - when the scope of the search is baseObject. If a client receives - such a SearchResultReference it MUST interpret is as a protocol - error and MUST NOT follow it." to the first paragraph. - The technical specification doesn't have to describe how a - protocol peer should react when its partner violates an absolute. - - OR return noSuchObject. +D.3 Review 2119 usage - - Add "If the scope part of the LDAP URL is present, the client MUST - use the new scope in its next request to progress the search. If - the scope part is absent the client MUST use subtree scope to - complete subtree searches and base scope to complete one level - searches." to the third paragraph. +D.4 Reconcile with I-D Nits -D.25 Section 4.6 +D.5 Section 4.6 - Resolve the meaning of "and is ignored if the attribute does not exist". See "modify: "non-existent attribute"" on the list. Not sure if there's really an issue here. Will look at archive -D.27 Section 4.10 +D.6 Section 4.10 - Specify what happens when the attr is missing vs. attr isn't in schema. Also what happens if there's no equality matching rule. noSuchAttribute, undefinedAttributeType, inappropriateMatching -D.30 Section 5.1 - - - Add "control and extended operation values" to last paragraph. See - "LBER (BER Restrictions)" on list. - -D.32 Section 6.1 +D.7 Section 6.1 - Add "that are used by those attributes" to the first paragraph. - Add "Servers which support update operations MUST, and other servers SHOULD, support strong authentication mechanisms described in [RFC2829]." as a second paragraph. Likely should just say - -Sermersheim Internet-Draft - Expires Jan 2004 Page 59 - Lightweight Directory Access Protocol Version 3 - Requirements of authentication methods, SASL mechanisms, and TLS are described in [AUTHMETH]." (also apply to next two below) - Add "Servers which provide access to sensitive information MUST, and other servers SHOULD support privacy protections such as those described in [RFC2829] and [RFC2830]." as a third paragraph. -D.33 Section 7 +Sermersheim Internet-Draft - Expires Jan 2004 Page 61 + Lightweight Directory Access Protocol Version 3 + +D.8 Section 7 - Add "Servers which support update operations MUST, and other servers SHOULD, support strong authentication mechanisms described in [RFC2829]." as a fourth paragraph. - Add "In order to automatically follow referrals, clients may need to hold authentication secrets. This poses significant privacy and security concerns and SHOULD be avoided." as a sixth paragraph. There are concerns with "automatic" chasing regardless of which, if any, authentication method/mechanism is used. - Add notes regarding DoS attack found by CERT advisories. -D.34 Appendix C +D.9 Various issues on ldapbis mailing list (some may already be + resolved) - - C.9. Explain why we removed ;binary, and what clients can do to - get around potential problems (likely refer to an I-D) + - "Attribute Name Length Bounds" thread. -Sermersheim Internet-Draft - Expires Jan 2004 Page 60 + - "Extensibility of SearchRequest.attributes" thread + +Sermersheim Internet-Draft - Expires Jan 2004 Page 62 Lightweight Directory Access Protocol Version 3 Full Copyright Statement Copyright (C) The Internet Society (2002). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any @@ -3272,11 +3339,11 @@ The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -Sermersheim Internet-Draft - Expires Jan 2004 Page 61 +Sermersheim Internet-Draft - Expires Jan 2004 Page 63