--- 1/draft-ietf-ldapbis-protocol-26.txt 2006-02-05 00:12:29.000000000 +0100 +++ 2/draft-ietf-ldapbis-protocol-27.txt 2006-02-05 00:12:29.000000000 +0100 @@ -1,51 +1,51 @@ - Internet-Draft Editor: J. Sermersheim Intended Category: Standard Track Novell, Inc -Document: draft-ietf-ldapbis-protocol-26.txt Aug 2004 +Document: draft-ietf-ldapbis-protocol-27.txt Oct 2004 Obsoletes: RFCs 2251, 2830, 3771 LDAP: The Protocol Status of this Memo This document is an Internet-Draft and is subject to all provisions of section 3 of RFC 3667. By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she become aware will be disclosed, in accordance with RFC 3668. Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF), its areas, and its working groups. Note that - other groups may also distribute working documents as Internet- - Drafts. + Task Force (IETF), its areas, and its working groups. Note that other + groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as "work in progress." + material or to cite them other than as "work in progress". The list of current Internet-Drafts can be accessed at - http://www.ietf.org/ietf/1id-abstracts.txt. + . The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html. + . + + This Internet-Draft will expire in February 2005. Technical discussion of this document will take place on the IETF LDAP Revision Working Group (LDAPbis) mailing list . Please send editorial comments directly to the editor . Copyright Notice - Copyright (C) The Internet Society 2004. + Copyright (C) The Internet Society 2004. All Rights Reserved. Abstract This document describes the protocol elements, along with their semantics and encodings, of 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). @@ -76,40 +76,41 @@ 4.4. Unsolicited Notification.....................................17 4.5. Search Operation.............................................18 4.6. Modify Operation.............................................27 4.7. Add Operation................................................28 4.8. Delete Operation.............................................29 4.9. Modify DN Operation..........................................30 4.10. Compare Operation...........................................31 4.11. Abandon Operation...........................................32 4.12. Extended Operation..........................................32 4.13. IntermediateResponse Message................................34 - 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse......35 + 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse......34 4.13.2. Usage with LDAP Request Controls..........................35 4.14. StartTLS Operation..........................................35 5. Protocol Encoding, Connection, and Transfer....................37 - 5.2. Protocol Encoding............................................38 + 5.2. Protocol Encoding............................................37 5.3. Transmission Control Protocol (TCP)..........................38 - 6. Security Considerations........................................39 - 7. Acknowledgements...............................................40 + 6. Security Considerations........................................38 + 7. Acknowledgements...............................................39 8. Normative References...........................................40 - 9. Informative References.........................................42 + 9. Informative References.........................................41 10. IANA Considerations...........................................42 - 11. Editor's Address..............................................43 - Appendix A - LDAP Result Codes....................................44 - A.1 Non-Error Result Codes........................................44 - A.2 Result Codes..................................................44 - Appendix B - Complete ASN.1 Definition............................49 - Appendix C - Changes..............................................55 - C.1 Changes made to RFC 2251:.....................................55 - C.2 Changes made to RFC 2830:.....................................60 - C.3 Changes made to RFC 3771:.....................................61 + 11. Editor's Address..............................................42 + Appendix A - LDAP Result Codes....................................43 + A.1 Non-Error Result Codes........................................43 + A.2 Result Codes..................................................43 + Appendix B - Complete ASN.1 Definition............................48 + Appendix C - Changes..............................................54 + C.1 Changes made to RFC 2251:.....................................54 + C.2 Changes made to RFC 2830:.....................................59 + C.3 Changes made to RFC 3771:.....................................59 + Lightweight Directory Access Protocol Version 3 1. Introduction 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 user, interacts with one or more servers (or Directory System Agents (DSA)). Clients interact with servers using a directory access @@ -141,52 +142,46 @@ summarizes substantive changes to the remaining sections. This document also obsoletes RFC 3771 in entirety. 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 [Keyword]. + Character names in this document use the notation for code points and + names from the Unicode Standard [Unicode]. For example, the letter + "a" may be represented as either or . + + Note: a glossary of terms used in Unicode can be found in [Glossary]. + Information on the Unicode character encoding model can be found in + [CharModel]. + + Lightweight Directory Access Protocol Version 3 + The term "connection" refers to the underlying transport service used to carry the protocol exchange. - The term "LDAP exchange" refers to application layer where LDAP PDUs - are exchanged between protocol peers. + The term "LDAP exchange" refers to the layer where LDAP PDUs are + exchanged between protocol peers. The term "TLS layer" refers to a layer inserted between the connection and the LDAP exchange that utilizes Transport Layer Security ([TLS]) to protect the exchange of LDAP PDUs. - Lightweight Directory Access Protocol Version 3 - The term "SASL layer" refers to a layer inserted between the connection and the LDAP exchange that utilizes Simple Authentication and Security Layer ([SASL]) to protect the exchange of LDAP PDUs. See the table in Section 5 for an illustration of these four terms. - The term "TLS-protected LDAP exchange" refers to an LDAP exchange - protected by a TLS-layer. - - The term "association" refers to the association of the LDAP exchange - and its current authentication and authorization state. - - Character names in this document use the notation for code points and - names from the Unicode Standard [Unicode]. For example, the letter - "a" may be represented as either or . - - Note: a glossary of terms used in Unicode can be found in [Glossary]. - Information on the Unicode character encoding model can be found in - [CharModel]. - 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 an operation, the server typically returns a response containing appropriate data to the requesting client. @@ -202,29 +197,30 @@ synchronous behavior may be controlled by client applications. The core protocol operations defined in this document can be mapped to a subset of the X.500 (1993) Directory Abstract Service [X.511]. However there is not a one-to-one mapping between LDAP operations and X.500 Directory Access Protocol (DAP) operations. Server implementations acting as a gateway to X.500 directories may need to make multiple DAP requests to service a single LDAP request. 3.1 Operation and LDAP Exchange Relationship - Lightweight Directory Access Protocol Version 3 Protocol operations are tied to an LDAP exchange. When the connection is closed, any uncompleted operations tied to the LDAP exchange are, when possible, abandoned, and when not possible, completed without transmission of the response. Also, when the connection is closed, the client MUST NOT assume that any uncompleted update operations tied to the LDAP exchange have succeeded or failed. + Lightweight Directory Access Protocol Version 3 + 4. Elements of Protocol The protocol is described using Abstract Syntax Notation One ([ASN.1]), and is transferred using a subset of ASN.1 Basic Encoding Rules ([BER]). Section 5 specifies how the protocol elements are encoded and transferred. In order to support future extensions to this protocol, extensibility is implied where it is allowed per ASN.1 (i.e. sequence, set, choice, and enumerated types are extensible). In addition, ellipses (...) @@ -255,28 +251,29 @@ encapsulated in a common envelope, the LDAPMessage, which is defined as follows: LDAPMessage ::= SEQUENCE { messageID MessageID, protocolOp CHOICE { bindRequest BindRequest, bindResponse BindResponse, unbindRequest UnbindRequest, searchRequest SearchRequest, - Lightweight Directory Access Protocol Version 3 - searchResEntry SearchResultEntry, searchResDone SearchResultDone, searchResRef SearchResultReference, modifyRequest ModifyRequest, modifyResponse ModifyResponse, addRequest AddRequest, + + Lightweight Directory Access Protocol Version 3 + addResponse AddResponse, delRequest DelRequest, delResponse DelResponse, modDNRequest ModifyDNRequest, modDNResponse ModifyDNResponse, compareRequest CompareRequest, compareResponse CompareResponse, abandonRequest AbandonRequest, extendedReq ExtendedRequest, extendedResp ExtendedResponse, @@ -307,32 +304,33 @@ (including providing notice) would be pernicious. Otherwise, server implementations MUST return an appropriate response to the request, with the resultCode set to protocolError. 4.1.1.1. Message ID All LDAPMessage envelopes encapsulating responses contain the messageID value of the corresponding request LDAPMessage. The message ID of a request MUST have a non-zero value different from - the values of any other uncompleted requests in the LDAP association - of which this message is a part. The zero value is reserved for the - unsolicited notification message. - - Lightweight Directory Access Protocol Version 3 + the the messageID of any other uncompleted requests in the LDAP + exchange. The zero value is reserved for the unsolicited notification + message. Typical clients increment a counter for each request. A client MUST NOT send a request with the same message ID as an - earlier request on the same LDAP association unless it can be - determined that the server is no longer servicing the earlier request - (e.g. after the final response is received, or a subsequent bind + earlier request in the same LDAP exchange unless it can be determined + that the server is no longer servicing the earlier request (e.g. + + Lightweight Directory Access Protocol Version 3 + + after the final response is received, or a subsequent bind completes). Otherwise the behavior is undefined. For this purpose, note that abandon and abandoned operations do not send responses. 4.1.2. String Types The LDAPString is a notational convenience to indicate that, although strings of LDAPString type encode as ASN.1 OCTET STRING types, the [ISO10646] character set (a superset of [Unicode]) is used, encoded following the [UTF-8] algorithm. Note that Unicode characters U+0000 through U+007F are the same as ASCII 0 through 127, respectively, and @@ -363,27 +361,29 @@ -- Constrained to [LDAPDN] A RelativeLDAPDN is defined to be the representation of a Relative Distinguished Name (RDN) after encoding according to the specification in [LDAPDN]. RelativeLDAPDN ::= LDAPString -- Constrained to [LDAPDN] 4.1.4. Attribute Descriptions - Lightweight Directory Access Protocol Version 3 The definition and encoding rules for attribute descriptions are defined in Section 2.5 of [Models]. Briefly, an attribute description is an attribute type and zero or more options. AttributeDescription ::= LDAPString + + Lightweight Directory Access Protocol Version 3 + -- Constrained to -- [Models] 4.1.5. Attribute Value A field of type AttributeValue is an OCTET STRING containing an encoded attribute value. The attribute value is encoded according to the LDAP-specific encoding definition of its corresponding syntax. The LDAP-specific encoding definitions for different syntaxes and attribute types may be found in other documents and in particular @@ -416,27 +416,27 @@ AttributeValueAssertion ::= SEQUENCE { attributeDesc AttributeDescription, assertionValue AssertionValue } AssertionValue ::= OCTET STRING The syntax of the AssertionValue depends on the context of the LDAP operation being performed. For example, the syntax of the EQUALITY matching rule for an attribute is used when performing a Compare - Lightweight Directory Access Protocol Version 3 - operation. Often this is the same syntax used for values of the attribute type, but in some cases the assertion syntax differs from the value syntax. See objectIdentiferFirstComponentMatch in [Syntaxes] for an example. + Lightweight Directory Access Protocol Version 3 + 4.1.7. Attribute and PartialAttribute Attributes and partial attributes consist of an attribute description and attribute values. A PartialAttribute allows zero values, while Attribute requires at least one value. PartialAttribute ::= SEQUENCE { type AttributeDescription, vals SET OF value AttributeValue } @@ -469,28 +469,29 @@ resultCode ENUMERATED { success (0), operationsError (1), protocolError (2), timeLimitExceeded (3), sizeLimitExceeded (4), compareFalse (5), compareTrue (6), authMethodNotSupported (7), strongAuthRequired (8), - Lightweight Directory Access Protocol Version 3 - -- 9 reserved -- referral (10), adminLimitExceeded (11), unavailableCriticalExtension (12), confidentialityRequired (13), saslBindInProgress (14), + + Lightweight Directory Access Protocol Version 3 + noSuchAttribute (16), undefinedAttributeType (17), inappropriateMatching (18), constraintViolation (19), attributeOrValueExists (20), invalidAttributeSyntax (21), -- 22-31 unused -- noSuchObject (32), aliasProblem (33), invalidDNSyntax (34), @@ -524,34 +525,35 @@ [LDAPIANA]. The meanings of the listed result codes are given in Appendix A. If a server detects multiple errors for an operation, only one result code is returned. The server should return the result code that best indicates the nature of the error encountered. 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. - - Lightweight Directory Access Protocol Version 3 - If the server chooses not to return a textual diagnostic, the diagnosticMessage field MUST be empty. 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. - If no aliases were dereferenced while attempting to locate the entry, - this will be a truncated form of the name provided, or if aliases - were dereferenced, of the resulting name, as defined in Section 12.5 - of [X.511]. Otherwise the matchedDN field is empty. + aliasDereferencingProblem), the matchedDN field is set (subject to + access controls) to the name of the last entry (object or alias) used + + Lightweight Directory Access Protocol Version 3 + + in finding the target (or base) object. If no aliases were + dereferenced while attempting to locate the entry, this will be a + truncated form of the name provided or if aliases were dereferenced, + of the resulting name, as defined in Section 12.5 of [X.511]. + Otherwise the matchedDN field is empty. 4.1.10. Referral The referral result code indicates that the contacted server cannot or will not perform the operation and that one or more other servers may be able to. Reasons for this include: - The target entry of the request is not held locally, but the server has knowledge of its possible existence elsewhere. @@ -580,28 +582,28 @@ If the client wishes to progress the operation, it MUST follow the referral by contacting one of the supported services. If multiple URIs are present, the client assumes that any supported URI may be used to progress the operation. Protocol peers that follow referrals 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 implementations use a counter that is incremented each time referral handling occurs for an operation, and these kinds - Lightweight Directory Access Protocol Version 3 - of implementations MUST be able to handle at least ten nested referrals between the root and a leaf entry. A URI for a server implementing LDAP and accessible via [TCP]/[IP] (v4 or v6) is written as an LDAP URL according to [LDAPURL]. + Lightweight Directory Access Protocol Version 3 + When an LDAP URL is used, the following instructions are followed: - If an alias was dereferenced, the part of the URL MUST be present, with the new target object name. UTF-8 encoded characters appearing in the string representation of a DN or search filter may not be legal for URLs (e.g. spaces) and MUST be escaped using the % method in [URI]. - It is RECOMMENDED that the part be present to avoid ambiguity. @@ -635,29 +637,29 @@ 4.1.11. Controls Controls provide a mechanism whereby the semantics and arguments of existing LDAP operations may be extended. One or more controls may be attached to a single LDAP message. A control only affects the semantics of the message it is attached to. Controls sent by clients are termed 'request controls' and those sent by servers are termed 'response controls'. - Lightweight Directory Access Protocol Version 3 - Controls ::= SEQUENCE OF control Control Control ::= SEQUENCE { controlType LDAPOID, criticality BOOLEAN DEFAULT FALSE, controlValue OCTET STRING OPTIONAL } + Lightweight Directory Access Protocol Version 3 + The controlType field is the dotted-decimal representation of an OBJECT IDENTIFIER which uniquely identifies the control. This provides unambiguous naming of controls. Often, response control(s) solicited by a request control share controlType values with the request control. The criticality field only has meaning in controls attached to request messages (except unbindRequest). For controls attached to response messages and the unbindRequest, the criticality field SHOULD be FALSE, and MUST be ignored by the receiving protocol peer. A value @@ -691,27 +693,28 @@ Servers list the controlType of request controls they recognize in the 'supportedControl' attribute in the root DSE (Section 5.1 of [Models]). Controls SHOULD NOT be combined unless the semantics of the combination has been specified. The semantics of control combinations, if specified, are generally found in the control specification most recently published. When a combination of controls is encountered whose semantics are invalid, not specified (or not - Lightweight Directory Access Protocol Version 3 - known), the message is considered to be not well-formed, thus the operation fails with protocolError. Additionally, unless order- dependent semantics are given in a specification, the order of a combination of controls in the SEQUENCE is ignored. Where the order is to be ignored but cannot be ignored by the server, the message is + + Lightweight Directory Access Protocol Version 3 + considered not well-formed and the operation fails with protocolError. This document does not specify any controls. Controls may be specified in other documents. Documents detailing control extensions are to provide for each control: - the OBJECT IDENTIFIER assigned to the control, - direction as to what value the sender should provide for the @@ -747,36 +750,37 @@ -- 1 and 2 reserved sasl [3] SaslCredentials, ... } SaslCredentials ::= SEQUENCE { mechanism LDAPString, credentials OCTET STRING OPTIONAL } Fields of the Bind Request are: + - version: A version number indicating the version of the protocol + to be used for the LDAP exchange. This document describes version + 3 of the protocol. There is no version negotiation. The client + sets this field to the version it desires. If the server does not + Lightweight Directory Access Protocol Version 3 - - version: A version number indicating the version of the protocol - to be used in this LDAP association. This document describes - version 3 of the protocol. There is no version negotiation. The - client sets this field to the version it desires. If the server - does not support the specified version, it MUST respond with - protocolError in the resultCode field of the BindResponse. + support the specified 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 - 5.1) or when using Simple Authentication and Security Layer [SASL] - authentication ([AuthMeth] Section 3.3.2). Where the server - attempts to locate the named object, it SHALL NOT perform alias - dereferencing. + - name: If not empty, 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 5.1) or when using Simple Authentication and + Security Layer [SASL] authentication ([AuthMeth] Section 3.3.2). + Where the server attempts to locate the named object, it SHALL NOT + perform alias dereferencing. - authentication: information used in authentication. This type is extensible as defined in Section 3.7 of [LDAPIANA]. Servers that do not support a choice supplied by a client return authMethodNotSupported in the resultCode field of the BindResponse. Textual passwords (consisting of a character sequence with a known character set and encoding) transferred to the server using the simple AuthenticationChoice SHALL be transferred as [UTF-8] @@ -801,27 +805,27 @@ multi-step bind process. Each step requires the server to return a BindResponse to indicate the status of authentication. After sending a BindRequest, clients MUST NOT send further LDAP PDUs until receiving the BindResponse. Similarly, servers SHOULD NOT process or respond to requests received while processing a BindRequest. If the client did not bind before sending a request and receives an operationsError to that request, it may then send a Bind Request. If - Lightweight Directory Access Protocol Version 3 - this also fails or the client chooses not to bind on the existing LDAP exchange, 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. + Lightweight Directory Access Protocol Version 3 + Clients may send multiple Bind Requests on an LDAP exchange to change the authentication and/or security associations or to complete a multi-stage bind process. Authentication from earlier binds is subsequently ignored. For some SASL authentication mechanisms, it may be necessary for the client to invoke the BindRequest multiple times ([AuthMeth] Section 8.2). Clients MUST NOT invoke operations between two Bind Requests made as part of a multi-stage bind. @@ -856,43 +860,42 @@ protocolError, it is to assume that the server does not support this version of LDAP. While the client may be able proceed with another version of this protocol (this may or may not require closing and re- establishing the connection), how to proceed with another version of this protocol is beyond the scope of this document. Clients which are unable or unwilling to proceed SHOULD close the connection. The serverSaslCreds field is 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. - - Lightweight Directory Access Protocol Version 3 - 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 SHALL NOT be included in the BindResponse. + Lightweight Directory Access Protocol Version 3 + 4.3. Unbind Operation - The function of the Unbind Operation is to terminate an LDAP - association and close the connection. The Unbind operation is not the - antithesis of the Bind operation as the name implies. The naming of - these operations is historical. The Unbind operation should be - thought of as the "quit" operation. + The function of the Unbind Operation is to terminate an LDAP exchange + and close the connection. The Unbind operation is not the antithesis + of the Bind operation as the name implies. The naming of these + operations is historical. The Unbind operation should be thought of + as the "quit" operation. The Unbind Operation is defined as follows: UnbindRequest ::= [APPLICATION 2] NULL The Unbind Operation has no response defined. Upon transmission of the UnbindRequest, each protocol peer is to consider the LDAP - association terminated, MUST cease transmission of messages to the - other peer, and MUST close the connection. Uncompleted operations are + exchange terminated, MUST cease transmission of messages to the other + peer, and MUST close the connection. Uncompleted operations are handled as specified in Section 5.1. 4.4. Unsolicited Notification An unsolicited notification is an LDAPMessage sent from the server to the client which is not in response to any LDAPMessage received by the server. It is used to signal an extraordinary condition in the server or in the LDAP exchange or connection between the client and the server. The notification is of an advisory nature, and the server will not expect any response to be returned from the client. @@ -910,52 +913,38 @@ specified in the responseName, - the format of the contents (if any) of the responseValue, - the circumstances which will cause the notification to be returned, and - the semantics of the operation. 4.4.1. Notice of Disconnection - Lightweight Directory Access Protocol Version 3 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. This notification is intended to assist clients in distinguishing between an error condition and a transient network + + Lightweight Directory Access Protocol Version 3 + failure. Note that this notification is not a response to an unbind requested by the client. Uncompleted operations are handled as specified in Section 5.1. The responseName is 1.3.6.1.4.1.1466.20036, the responseValue field is absent, and the resultCode is used to indicate the reason for the disconnection. - The following result codes 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 - 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 LDAP exchanges, and be unavailable for - an extended period of time. The client may make use of an - alternative server. - Upon transmission of the Notice of Disconnection, the server is to - consider the LDAP association terminated, MUST cease transmission of + consider the LDAP exchange terminated, MUST cease transmission of messages to the client, and MUST close the connection. 4.5. Search Operation The Search Operation is used to request a server to return, subject to access controls and other restrictions, a set of entries matching a complex search criterion. This can be used to read attributes from a single entry, from entries immediately subordinate to a particular entry, or a whole subtree of entries. @@ -963,43 +952,44 @@ The Search Request is defined as follows: SearchRequest ::= [APPLICATION 3] SEQUENCE { baseObject LDAPDN, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { - Lightweight Directory Access Protocol Version 3 - neverDerefAliases (0), derefInSearching (1), derefFindingBaseObj (2), derefAlways (3) }, sizeLimit INTEGER (0 .. maxInt), timeLimit INTEGER (0 .. maxInt), typesOnly BOOLEAN, filter Filter, attributes AttributeSelection } AttributeSelection ::= SEQUENCE OF selector LDAPString -- The LDAPString is constrained to -- below Filter ::= CHOICE { - and [0] SET SIZE (1..MAX) OF filter Filter, - or [1] SET SIZE (1..MAX) OF filter Filter, + and [0] SET OF filter Filter, + or [1] SET OF filter Filter, not [2] Filter, equalityMatch [3] AttributeValueAssertion, substrings [4] SubstringFilter, greaterOrEqual [5] AttributeValueAssertion, + + Lightweight Directory Access Protocol Version 3 + lessOrEqual [6] AttributeValueAssertion, present [7] AttributeDescription, approxMatch [8] AttributeValueAssertion, extensibleMatch [9] MatchingRuleAssertion } SubstringFilter ::= SEQUENCE { type AttributeDescription, -- initial and final can occur at most once substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE { initial [0] AssertionValue, @@ -1020,40 +1010,40 @@ - scope: Specifies the scope of the search to be performed. The semantics (as described in [X.511]) of the possible values of this field are: baseObject: The scope is constrained to the entry named by baseObject. singleLevel: The scope is constrained to the immediate subordinates of the entry named by baseObject. - Lightweight Directory Access Protocol Version 3 - wholeSubtree: the scope is constrained to the entry named by the baseObject, and all its subordinates. - derefAliases: An indicator as to how alias entries (as defined in [Models]) are to be handled in searching. The semantics of the possible values of this field are: neverDerefAliases: Do not dereference aliases in searching or in locating the base object of the search. derefInSearching: While searching, dereference any alias entry subordinate to the base object which is also in the search scope. The filter is applied to the dereferenced object(s). If the search scope is wholeSubtree, the search continues in the subtree of any dereferenced object. Aliases in that subtree are also dereferenced. Servers SHOULD eliminate duplicate entries that arise due to alias dereferencing while searching. + Lightweight Directory Access Protocol Version 3 + 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. Servers MUST detect looping while dereferencing aliases in order to prevent denial of service attacks of this nature. - sizeLimit: A size limit that restricts the maximum number of @@ -1074,22 +1064,20 @@ descriptions (no values) to be returned. Setting this field to FALSE causes both attribute descriptions and values to be returned. - filter: A filter that defines the conditions that must be fulfilled in order for the search to match a given entry. The 'and', 'or' and 'not' choices can be used to form combinations of filters. At least one filter element MUST be present in an 'and' or 'or' choice. The others match against individual - Lightweight Directory Access Protocol Version 3 - attribute values of entries in the scope of the search. (Implementor's note: the 'not' filter is an example of a tagged choice in an implicitly-tagged module. In BER this is treated as if the tag was explicit.) A server MUST evaluate filters according to the three-valued logic of X.511 (1993) Section 7.8.1. In summary, a filter is evaluated to either "TRUE", "FALSE" or "Undefined". If the filter evaluates to TRUE for a particular entry, then the attributes of that entry are returned as part of the search result (subject to any @@ -1097,20 +1085,22 @@ 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. + 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. There SHALL be at most one 'initial', and at most one 'final' in the 'substrings' of a SubstringFilter. If 'initial' is present, it @@ -1130,86 +1120,97 @@ The matching rule for the lessOrEqual filter item is defined by the ORDERING matching rule for the attribute type. An approxMatch filter item evaluates to TRUE when there is a value of the attribute or subtype for which some locally-defined approximate matching algorithm (e.g. spelling variations, phonetic match, etc.) returns TRUE. If an item matches for equality, it also satisfies an approximate match. If approximate matching is not supported for the attribute, this filter item should be - Lightweight Directory Access Protocol Version 3 - treated as an equalityMatch. An extensibleMatch filter item is evaluated as follows: If the matchingRule field is absent, the type field MUST be present, and an equality match is performed for that type. If the type field is absent and the matchingRule is present, the matchValue is compared against all attributes in an entry which support that matchingRule. 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 is invalid. If the type field is present and the matchingRule is present, the matchValue is compared against entry attributes of the specified type. In this case, the matchingRule MUST be one + + Lightweight Directory Access Protocol Version 3 + suitable for use with the specified type (see [Syntaxes]), otherwise the filter item is Undefined. If the dnAttributes field is set to TRUE, the match is additionally applied against all the AttributeValueAssertions in an entry's distinguished name, and evaluates to TRUE if there is at least one attribute in the distinguished name for which the filter item evaluates to TRUE. The dnAttributes field is present to alleviate the need for multiple versions of generic matching rules (such as word matching), where one applies to entries and another applies to entries and dn attributes as well. A filter item evaluates to Undefined when the server would not be - able to determine whether the assertion value matches an entry. If - an attribute description in an equalityMatch, substrings, - greaterOrEqual, lessOrEqual, approxMatch or extensibleMatch filter - is not recognized by the server, a MatchingRuleId in the - extensibleMatch is not recognized by the server, the assertion - value is invalid, 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. + able to determine whether the assertion value matches an entry. + Examples include: + + - An attribute description in an equalityMatch, substrings, + greaterOrEqual, lessOrEqual, approxMatch or extensibleMatch + filter is not recognized by the server. + + - The attribute type does not define the appropriate matching + rule. + + - A MatchingRuleId in the extensibleMatch is not recognized by + the server or is not valid for the attribute type. + + - The type of filtering requested is not implemented. + + - The assertion value is invalid. + + 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 + each evaluate to Undefined. Servers MUST NOT return errors if attribute descriptions or matching rule ids are not recognized, assertion values are invalid, or the assertion syntax is not supported. More details of filter processing are given in Section 7.8 of [X.511]. - attributes: A selection 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 Augmented Backus-Naur Form ([ABNF]): - Lightweight Directory Access Protocol Version 3 - attributeSelector = attributedescription / selectorpecial selectorspecial = noattrs / alluserattrs noattrs = %x31.2E.31 ; "1.1" alluserattrs = %x2A ; asterisk ("*") + Lightweight Directory Access Protocol Version 3 + The production is defined in Section 2.5 of [Models]. There are three special cases which may appear in the attributes selection list: - an empty list with no attributes, - a list containing "*" (with zero or more attribute descriptions), and @@ -1242,29 +1243,30 @@ Note that an X.500 "list"-like operation can be emulated by the client requesting a one-level LDAP search operation with a filter checking for the presence of the 'objectClass' attribute, and that an X.500 "read"-like operation can be emulated by a base object LDAP search operation with the same filter. A server which provides a gateway to X.500 is not required to use the Read or List operations, although it may choose to do so, and if it does, it must provide the same semantics as the X.500 search operation. - Lightweight Directory Access Protocol Version 3 - 4.5.2. Search Result The results of the search operation are returned as zero or more searchResultEntry messages, zero or more SearchResultReference messages, followed by a single searchResultDone message. SearchResultEntry ::= [APPLICATION 4] SEQUENCE { + + Lightweight Directory Access Protocol Version 3 + objectName LDAPDN, attributes PartialAttributeList } PartialAttributeList ::= SEQUENCE OF partialAttribute PartialAttribute -- Note that the PartialAttributeList may hold zero elements. -- This may happen when none of the attributes of an entry -- were requested, or could be returned. -- Note also that the partialAttribute vals set may hold zero -- elements. This may happen when typesOnly is requested, access @@ -1295,47 +1297,49 @@ 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 [Models] 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 - Lightweight Directory Access Protocol Version 3 If the server was able to locate the entry referred to by the baseObject but was unable to search one or more non-local entries, the server may return one or more SearchResultReference entries, each containing a reference to another set of servers for continuing the operation. 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 either a + + Lightweight Directory Access Protocol Version 3 + referral or noSuchObject result code (depending on the server's knowledge of the entry named in the baseObject). If a server holds a copy or partial copy of the subordinate naming context [Section 5 of Models], 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. A URI for a server implementing LDAP and accessible via [TCP]/[IP] (v4 or v6) is written as an LDAP URL according to [LDAPURL]. In order to complete the search, the client issues a new search operation for each SearchResultReference that is returned. Note that the abandon operation described in Section 4.11 applies only to a - particular operation sent on an association between a client and + particular operation sent on the LDAP exchange between a client and server. The client must abandon subsequent search operations it wishes to individually. Clients that follow 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 search result reference handling occurs for an operation, and these kinds of clients MUST be able to handle at least ten nested search result references between the root and a leaf entry. @@ -1352,29 +1356,29 @@ provide a different filter in a URL of a SearchResultReference. - If the part of the URL is present, 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. - If the originating search scope was singleLevel, the part of the URL will be "base". - Lightweight Directory Access Protocol Version 3 - - - it is RECOMMENDED that the part be present to avoid + - It is RECOMMENDED that the part be present to avoid ambiguity. - Other aspects of the new search request may be the same as or different from the search request which generated the SearchResultReference. + Lightweight Directory Access Protocol Version 3 + - The name of an unexplored subtree in a SearchResultReference need not be subordinate to the base object. Other kinds of URIs may be returned. The syntax and semantics of such URIs is left to future specifications. Clients may ignore URIs that they do not support. 4.5.3.1. Examples For example, suppose the contacted server (hosta) holds the entry @@ -1406,28 +1410,28 @@ ldap://hoste/OU=Managers,OU=People,DC=Example,DC=NET??sub } SearchResultReference { ldap://hostf/OU=Consultants,OU=People,DC=Example,DC=NET??sub } SearchResultDone (success) Similarly, if a singleLevel search of is requested to the contacted server, it may return the following: SearchResultEntry for CN=Manager,DC=Example,DC=NET SearchResultReference { - Lightweight Directory Access Protocol Version 3 - ldap://hostb/OU=People,DC=Example,DC=NET??base ldap://hostc/OU=People,DC=Example,DC=NET??base } SearchResultReference { ldap://hostd/OU=Roles,DC=Example,DC=NET??base } SearchResultDone (success) + Lightweight Directory Access Protocol Version 3 + If the contacted server does not hold the base object for the search, but has knowledge of its possible location, then it may return a referral to the client. In this case, if the client requests a subtree search of to hosta, the server returns a SearchResultDone containing a referral. SearchResultDone (referral) { ldap://hostg/DC=Example,DC=ORG??sub } 4.6. Modify Operation @@ -1461,26 +1465,27 @@ performed MUST conform to the requirements of the directory model and controlling schema [Models]. - operation: Used to specify the type of modification being performed. Each operation type acts on the following modification. The values of this field have the following semantics respectively: add: add values listed to the modification attribute, creating the attribute if necessary; - Lightweight Directory Access Protocol Version 3 delete: delete values listed from the modification attribute, removing the entire attribute if no values are listed, or if all current values of the attribute are listed for deletion; + Lightweight Directory Access Protocol Version 3 + replace: replace all existing values of the modification attribute with the new values listed, creating the attribute if it did not already exist. A replace with no value will delete the entire attribute if it exists, and is ignored if the attribute does not exist. - modification: A PartialAttribute (which may have an empty SET of vals) used to hold the attribute type or attribute type and values being modified. @@ -1491,22 +1496,23 @@ ModifyResponse ::= [APPLICATION 7] LDAPResult The server will return to the client a single Modify Response indicating either the successful completion of the DIT modification, or the reason that the modification failed. Due to the requirement for atomicity in applying the list of modifications in the Modify Request, the client may expect that no modifications of the DIT have been performed if the Modify Response received indicates any sort of error, and that all requested modifications have been 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. + Operation. The result of the modification is indeterminate if the + Modify Response is not received (e.g. the LDA exchange is terminated + or the Modify Operation is abandoned). The Modify Operation cannot be used to remove from an entry any of its distinguished values, i.e. those values which form the entry's relative distinguished name. An attempt to do so will result in the server returning the notAllowedOnRDN result code. 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 changes in an LDAP ModifyRequest onto the changes of a DAP ModifyEntry operation, and different implementations @@ -1515,26 +1521,27 @@ 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 { entry LDAPDN, attributes AttributeList } - Lightweight Directory Access Protocol Version 3 AttributeList ::= SEQUENCE OF attribute Attribute Fields of the Add Request are: + Lightweight Directory Access Protocol Version 3 + - entry: the name of the entry to be added. The server SHALL NOT dereference any aliases in locating the entry to be added. - attributes: the list of attributes that, along with those from the RDN, make up the content of the entry being added. Clients MAY or MAY NOT include the RDN attribute in this list. Clients MUST include the 'objectClass' attribute, and values of any mandatory attributes of the listed object classes. Clients MUST NOT supply NO-USER-MODIFICATION attributes such as the createTimestamp or creatorsName attributes, since the server maintains these @@ -1569,26 +1576,26 @@ DelRequest ::= [APPLICATION 10] LDAPDN The Delete Request consists of the name of the entry to be deleted. The server SHALL NOT dereference aliases while resolving the name of the target entry to be removed. Only leaf entries (those with no subordinate entries) can be deleted with this operation. - Lightweight Directory Access Protocol Version 3 - Upon receipt of a Delete Request, a server will attempt to perform the entry removal requested and return the result in the Delete Response defined as follows: + Lightweight Directory Access Protocol Version 3 + DelResponse ::= [APPLICATION 11] LDAPResult 4.9. Modify DN Operation The Modify DN Operation allows a client to change the Relative Distinguished Name (RDN) of an entry in the Directory, and/or to move a subtree of entries to a new location in the Directory. The Modify DN Request is defined as follows: ModifyDNRequest ::= [APPLICATION 12] SEQUENCE { @@ -1623,27 +1630,28 @@ Upon receipt of a ModifyDNRequest, a server will attempt to perform the name change and return the result in the Modify DN Response, defined as follows: ModifyDNResponse ::= [APPLICATION 13] LDAPResult For example, if the entry named in the entry field was , the newrdn field was , and the newSuperior field was absent, then this operation would attempt to rename the entry to be . If there was - Lightweight Directory Access Protocol Version 3 - already an entry with that name, the operation would fail with the entryAlreadyExists result code. The object named in newSuperior MUST exist. For example, if the client attempted to add , the + + Lightweight Directory Access Protocol Version 3 + entry did not exist, and the entry did exist, then the server would return the noSuchObject result code with the matchedDN field containing . If the deleteoldrdn field is TRUE, the attribute values forming the old RDN but not the new RDN are deleted from the entry. If the deleteoldrdn field is FALSE, the attribute values forming the old RDN will be retained as non-distinguished attribute values of the entry. The server MUST fail the operation and return an error in the result code if the setting of the deleteoldrdn field would cause a schema @@ -1678,42 +1686,42 @@ the requested comparison and return the result in the Compare Response, defined as follows: CompareResponse ::= [APPLICATION 15] LDAPResult The resultCode field is set to compareTrue, compareFalse, or an appropriate error. compareTrue indicates that the assertion value in the ava field matches a value of the attribute or subtype according to the attribute's EQUALITY matching rule. compareFalse indicates that the assertion value in the ava field and the values of the - Lightweight Directory Access Protocol Version 3 - attribute or subtype did not match. Other result codes indicate either that the result of the comparison was Undefined (Section 4.5.1), or that some error occurred. + Lightweight Directory Access Protocol Version 3 + Note that some directory systems may establish access controls which permit the values of certain attributes (such as userPassword) to be compared but not interrogated by other means. 4.11. Abandon Operation The function of the Abandon Operation is to allow a client to request that the server abandon an uncompleted operation. The Abandon Request is defined as follows: AbandonRequest ::= [APPLICATION 16] MessageID The MessageID is that of an operation which was requested earlier in - this LDAP association. The abandon request itself has its own - MessageID. This is distinct from the MessageID of the earlier - operation being abandoned. + this LDAP exchange. The abandon request itself has its own MessageID. + This is distinct from the MessageID of the earlier operation being + abandoned. There is no response defined in the Abandon operation. Upon receipt of an AbandonRequest, the server MAY abandon the operation identified by the MessageID. Since the client cannot tell the difference between a successfully abandoned operation and an uncompleted operation, the application of the Abandon operation is limited to uses where the client does not require an indication of its outcome. Abandon, Bind, Unbind, and StartTLS operations cannot be abandoned. @@ -1730,26 +1738,27 @@ Clients should 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 operations which have already been abandoned. 4.12. Extended Operation - Lightweight Directory Access Protocol Version 3 The extended operation allows additional operations to be defined for services not already available in the protocol. For example, to add operations to install transport layer security (see Section 4.14). + Lightweight Directory Access Protocol Version 3 + The extended operation allows clients to make requests and receive responses with predefined syntaxes and semantics. These may be defined in RFCs or be private to particular implementations. Each extended operation consists of an extended request and an extended response. ExtendedRequest ::= [APPLICATION 23] SEQUENCE { requestName [0] LDAPOID, requestValue [1] OCTET STRING OPTIONAL } @@ -1785,26 +1794,27 @@ Section 4. Servers list the requestName of Extended Requests they recognize in the ' supportedExtension ' attribute in the root DSE (Section 5.1 of [Models]). Extended operations may be specified in other documents. The specification of an extended operation consists of: - the OBJECT IDENTIFIER assigned to the requestName, - Lightweight Directory Access Protocol Version 3 - the OBJECT IDENTIFIER (if any) assigned to the responseName (note that the same OBJECT IDENTIFIER my be used for both the requestName and responseName), + Lightweight Directory Access Protocol Version 3 + - the format of the contents of the requestValue and responseValue (if any), and - the semantics of the operation. 4.13. IntermediateResponse Message While the Search operation provides a mechanism to return multiple response messages for a single search request, other operations, by nature, do not provide for multiple response messages. @@ -1838,28 +1848,28 @@ - the OBJECT IDENTIFIER (if any) assigned to the responseName, - the format of the contents of the responseValue, and - the semantics associated with the IntermediateResponse message. Extensions that allow the return of multiple types of IntermediateResponse messages SHALL identify those types using unique responseName values (note that one of these may specify no value). - Lightweight Directory Access Protocol Version 3 - Sections 4.13.1 and 4.13.2 describe additional requirements on the inclusion of responseName and responseValue in IntermediateResponse messages. 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse + Lightweight Directory Access Protocol Version 3 + A single-request/multiple-response operation may be defined using a single ExtendedRequest message to solicit zero or more IntermediateResponse messages of one or more kinds followed by an ExtendedResponse message. 4.13.2. Usage with LDAP Request Controls A control's semantics may include the return of zero or more IntermediateResponse messages prior to returning the final result code for the operation. One or more kinds of IntermediateResponse @@ -1872,87 +1882,63 @@ - two or more controls using IntermediateResponse messages are included in a request for any LDAP operation or - one or more controls using IntermediateResponse messages are included in a request with an LDAP extended operation that uses IntermediateResponse messages. 4.14. StartTLS Operation - The Start Transport Layer Security (StartTLS) operation provides the - ability to establish a TLS-protected LDAP exchange. The StartTLS - operation is defined using the extended operation mechanism described - in Section 4.12. + The Start Transport Layer Security (StartTLS) operationĘs purpose is + to initiate installation of a TLS layer. The StartTLS operation is + defined using the extended operation mechanism described in Section + 4.12. 4.14.1. StartTLS Request A client requests TLS establishment by transmitting a StartTLS request PDU to the server. The StartTLS request is defined in terms of an ExtendedRequest. The requestName is "1.3.6.1.4.1.1466.20037", and the requestValue field is always absent. The client MUST NOT send any PDUs on this LDAP exchange following this request until it receives a StartTLS extended response and, in the case of a successful response, completes TLS negotiations. + Sequencing problems (particularly those detailed in Section 3.1.1 of + [AuthMeth] result in an operationsError being returned in the + resultCode. + + If the server does not support TLS (whether by design or by current + configuration), it returns the protocolError resultCode as described + in Section 4.12. + Lightweight Directory Access Protocol Version 3 4.14.2. StartTLS Response When a StartTLS request is made, servers supporting the operation MUST return a StartTLS response PDU to the requestor. The responseName, if present, is also "1.3.6.1.4.1.1466.20037". The responseValue is absent. - The server provides a resultCode field to either success or one of - the other values outlined in Section 4.14.2.2. - -4.14.2.1. "Success" Response - - If the StartTLS Response contains a resultCode of success, this - indicates that the server is willing and able to negotiate TLS. Refer - to Section 4 of [AuthMeth] for details. - -4.14.2.2. Response other than "success" - - If the ExtendedResponse contains a result code other than success, - this indicates that the server is unwilling or unable to negotiate - TLS. The following result codes have these meanings for this - operation: - - - operationsError: operations sequencing incorrect; e.g. TLS is - already established. - - - protocolError: TLS is not supported or incorrect PDU structure. - - - unavailable: Some major problem with TLS, or the server is - shutting down. - - The server MUST return operationsError if the client violates any of - the StartTLS extended operation sequencing requirements described in - Section 4 of [AuthMeth]. - - If the server does not support TLS (whether by design or by current - configuration), it MUST return the protocolError resultCode. In this - event, the client may proceed with any LDAP operation, or it may - close the connection. + If the server is willing and able to negotiate TLS, it returns a + success resultCode. Refer to Section 4 of [AuthMeth] for details. - The server MUST return unavailable if it supports TLS but cannot - install the TLS layer 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 connection. + If the server is otherwise unwilling or unable to perform this + operation, the server is to return an appropriate result code + indicating the nature of the problem. For example, if the TLS + subsystem is not presently available, the server may return indicate + so by returning the unavailable resultCode. 4.14.3. Removal of the TLS Layer - Lightweight Directory Access Protocol Version 3 Two forms of TLS layer removal -- graceful and abrupt -- are provided. These do not involve LDAP PDUs, but are preformed at the underlying layers. If the connection is closed, uncompleted operations are handled as specified in Section 5.1. 4.14.3.1. Graceful Removal @@ -1970,43 +1956,43 @@ When a protocol peer receives the initial TLS closure alert, it may choose to allow the LDAP exchange to remain intact. In this case, it MUST immediately transmit a TLS closure alert. Following this, it MAY send and receive LDAP PDUs. Protocol peers MAY close the connection after sending or receiving a TLS closure alert. After the TLS layer has been removed, the server MUST NOT send responses to any request message received before the TLS closure + + Lightweight Directory Access Protocol Version 3 + alert. Thus, clients wishing to receive responses to messages sent while the TLS layer is intact MUST wait for those message responses before sending the TLS closure alert. 4.14.3.2. Abrupt Removal Either the client or server MAY abruptly remove the TLS layer by closing the connection. In this circumstance, a server MAY send the client a Notice of Disconnection before closing the connection. 5. Protocol Encoding, Connection, and Transfer This protocol is designed to run over connection-oriented, reliable transports, where the data stream is divided into octets (8-bit units), with each octet and each bit being significant. One underlying service, LDAP over TCP, is defined in Section 5.3. This service is generally applicable to applications providing or consuming X.500-based directory services on the Internet. This specification was generally written with the TCP mapping in mind. - - Lightweight Directory Access Protocol Version 3 - Specifications detailing other mappings may encounter various obstacles. Implementations of LDAP over TCP MUST implement the mapping as described in Section 5.3. This table illustrates the relationship between the different layers involved in an exchange between two protocol peers: +---------------+ @@ -2023,20 +2009,22 @@ +---------------+ 5.2. Protocol Encoding The protocol elements of LDAP SHALL be encoded for exchange using the Basic Encoding Rules [BER] of [ASN.1] with the following restrictions: - Only the definite form of length encoding is used. + Lightweight Directory Access Protocol Version 3 + - OCTET STRING values are encoded in the primitive form only. - If the value of a BOOLEAN type is true, the encoding of the value octet is set to hex "FF". - If a value of a type is its default value, it is absent. Only some BOOLEAN and INTEGER types have default values in this protocol definition. These restrictions are meant to ease the overhead of encoding and @@ -2046,22 +2034,20 @@ OCTET STRING values, such as attribute values, unless otherwise stated. 5.3. Transmission Control Protocol (TCP) The encoded LDAPMessage PDUs are mapped directly onto the [TCP] bytestream using the BER-based encoding described in Section 5.2. It is recommended that server implementations running over the TCP provide a protocol listener on the Internet Assigned Numbers Authority (IANA)-assigned LDAP port, 389 [PortReg]. Servers may - Lightweight Directory Access Protocol Version 3 - instead provide a listener on a different port number. Clients MUST support contacting servers on any valid TCP port. 6. Security Considerations This version of the protocol provides facilities for simple authentication using a cleartext password, as well as any [SASL] mechanism. Installing SASL layers can provide integrity and other data security services. @@ -2077,46 +2063,47 @@ Security considerations for authentication methods, SASL mechanisms, and TLS are described in [AuthMeth]. It should be noted that SASL authentication exchanges do not provide data confidentiality nor integrity protection for the version or name fields of the bind request nor the resultCode, diagnosticMessage, or referral fields of the bind response nor of any information contained in controls attached to bind request or responses. Thus information contained in these fields SHOULD NOT be relied on unless otherwise + + Lightweight Directory Access Protocol Version 3 + protected (such as by establishing protections at the transport layer). - Server implementors should plan for the possibility of an identity in - and association being deleted, renamed, or modified, and take - appropriate actions to prevent insecure side effects. Likewise, - server implementors should plan for the possibility of an associated - identity's credentials becoming invalid, or an identity's privileges - being changed. The ways in which these issues are addressed are - application and/or implementation specific. + Server implementors should plan for the possibility of (protocol or + external) events which alter the information used to establish + security factors (e.g., credentials, authorization identities, access + controls) during the course of the LDAP exchange, and even during the + performance of a particular operation, and should take steps to avoid + insecure side effects of these changes. The ways in which these + issues are addressed are application and/or implementation specific. 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 search results except to particular authenticated clients. For example, caches could serve result information only to the client whose request caused it to be in the cache. Servers may return referrals or search result references which redirect 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. Clients are advised to be aware of this, and possibly reject referrals when - Lightweight Directory Access Protocol Version 3 - confidentiality measures are not in place. Clients are advised to reject referrals from the StartTLS operation. The matchedDN and diagnosticMessage fields, as well as some resultCode values (e.g., attributeOrValueExists and entryAlreadyExists), could disclose the presence the specific data in the directory which is subject to access and other administrative controls. Server implementations should restrict access to protected information equally under both normal and error conditions. @@ -2132,31 +2119,31 @@ This document is based on RFC 2251 by Mark Wahl, Tim Howes, and Steve Kille. RFC 2251 was a product of the IETF ASID Working Group. It is also based on RFC 2830 by Jeff Hodges, RL "Bob" Morgan, and Mark Wahl. RFC 2830 was a product of the IETF LDAPEXT Working Group. It is also based on RFC 3771 by Roger Harrison, and Kurt Zeilenga. RFC 3771 was an individual submission to the IETF. - This document is a product of the LDAPBIS Working Group. Significant - contributors of technical review and content include Kurt Zeilenga, - Steven Legg, and Hallvard Furuseth. + Lightweight Directory Access Protocol Version 3 + + This document is a product of the IETF LDAPBIS Working Group. + Significant contributors of technical review and content include Kurt + Zeilenga, Steven Legg, and Hallvard Furuseth. 8. Normative References [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997. - Lightweight Directory Access Protocol Version 3 - [ASN.1] ITU-T Recommendation X.680 (07/2002) | ISO/IEC 8824-1:2002 "Information Technology - Abstract Syntax Notation One (ASN.1): Specification of basic notation" [AuthMeth] Harrison, R., "LDAP: Authentication Methods and Connection Level Security Mechanisms", draft-ietf-ldapbis-authmeth- xx.txt, (a work in progress). [BER] ITU-T Rec. X.690 (07/2002) | ISO/IEC 8825-1:2002, "Information technology - ASN.1 encoding rules: @@ -2186,30 +2173,30 @@ [Models] Zeilenga, K., "LDAP: Directory Information Models", draft- ietf-ldapbis-models-xx.txt (a work in progress). [Roadmap] Zeilenga, K., "LDAP: Technical Specification Road Map", draft-ietf-ldapbis-roadmap-xx.txt (a work in progress). [SASL] Melnikov, A., "Simple Authentication and Security Layer", draft-ietf-sasl-rfc2222bis-xx.txt (a work in progress). + Lightweight Directory Access Protocol Version 3 + [SASLPrep] Zeilenga, K., "Stringprep profile for user names and passwords", draft-ietf-sasl-saslprep-xx.txt, (a work in progress). [StringPrep] Hoffman P. and M. Blanchet, "Preparation of Internationalized Strings ('stringprep')", draft-hoffman- rfc3454bis-xx.txt, a work in progress. - Lightweight Directory Access Protocol Version 3 - [Syntaxes] Legg, S., and K. Dally, "LDAP: Syntaxes and Matching Rules", draft-ietf-ldapbis-syntaxes-xx.txt, (a work in progress). [TCP] Postel, J., "Transmission Control Protocol", STD7 and RFC 793, September 1981 [TLS] Dierks, T. and C. Allen. "The TLS Protocol Version 1.1", draft-ietf-tls-rfc2246-bis-xx.txt, a work in progress. @@ -2239,29 +2226,30 @@ 9. Informative References [Glossary] The Unicode Consortium, "Unicode Glossary", . [CharModel] Whistler, K. and M. Davis, "Unicode Technical Report #17, Character Encoding Model", UTR17, , August 2000. + Lightweight Directory Access Protocol Version 3 + [PROTOS-LDAP] University of Oulu, "PROTOS Test-Suite: c06-ldapv3" [PortReg] IANA, "Port Numbers", http://www.iana.org/assignments/port-numbers 10. IANA Considerations - Lightweight Directory Access Protocol Version 3 It is requested that the Internet Assigned Numbers Authority (IANA) update the LDAP result code registry to indicate that this document provides the definitive technical specification for result codes 0- 36, 48-54, 64-70, 80-90. It is requested that the IANA update the LDAP Protocol Mechanism registry to indicate that this document and [AuthMeth] provides the definitive technical specification for the StartTLS (1.3.6.1.4.1.1466.20037) extended operation. @@ -2692,22 +2685,22 @@ timeLimit INTEGER (0 .. maxInt), typesOnly BOOLEAN, filter Filter, attributes AttributeSelection } AttributeSelection ::= SEQUENCE OF selector LDAPString -- The LDAPString is constrained to -- in Section 4.5.1 Filter ::= CHOICE { - and [0] SET SIZE (1..MAX) OF filter Filter, - or [1] SET SIZE (1..MAX) OF filter Filter, + and [0] SET OF filter Filter, + or [1] SET OF filter Filter, not [2] Filter, equalityMatch [3] AttributeValueAssertion, substrings [4] SubstringFilter, greaterOrEqual [5] AttributeValueAssertion, lessOrEqual [6] AttributeValueAssertion, present [7] AttributeDescription, approxMatch [8] AttributeValueAssertion, extensibleMatch [9] MatchingRuleAssertion } SubstringFilter ::= SEQUENCE { @@ -2845,310 +2841,305 @@ Lightweight Directory Access Protocol Version 3 - Clarified when it is and isn't appropriate to return an already used message id. RFC 2251 accidentally imposed synchronous server behavior in its wording of this. C.1.6 Section 4.1.2 - Stated that LDAPOID is constrained to from [Models]. -C.1.7 Section 4.1.5.1 +C.1.7 Section 4.1.5.1 and others - Removed the Binary Option from the specification. There are numerous interoperability problems associated with this method of alternate attribute type encoding. Work to specify a suitable replacement is ongoing. -C.1.8 Section 4.1.6 - - - Removed references to the "binary" encoding as it has been removed - from the specification. - -C.1.9 Section 4.1.7 - - - Removed references to the "binary" encoding as it has been removed - from the specification. - -C.1.10 Section 4.1.8 +C.1.8 Section 4.1.8 - Combined the definitions of PartialAttribute and Attribute here, and defined Attribute in terms of PartialAttribute. -C.1.11 Section 4.1.10 +C.1.9 Section 4.1.10 - Renamed "errorMessage" to "diagnosticMessage" as it is allowed to be sent for non-error results. - Moved some language into Appendix A, and refer the reader there. - Allowed matchedDN to be present for other result codes than those listed in RFC 2251. -C.1.12 Section 4.1.11 +C.1.10 Section 4.1.11 - Defined referrals in terms of URIs rather than URLs. - Removed the requirement that all referral URIs MUST be equally capable of progressing the operation. The statement was ambiguous and provided no instructions on how to carry it out. - Added the requirement that clients MUST NOT loop between servers. - Clarified the instructions for using LDAPURLs in referrals, and in doing so added a recommendation that the scope part be present. - Lightweight Directory Access Protocol Version 3 - -C.1.13 Section 4.1.12 +C.1.11 Section 4.1.12 - Specified how control values defined in terms of ASN.1 are to be encoded. - Noted that the criticality field is only applied to request messages (except unbindRequest), and must be ignored when present on response messages and unbindRequest. - Added language regarding combinations of controls and the ordering of controls on a message. + + Lightweight Directory Access Protocol Version 3 + - Specified that when the semantics of the combination of controls is undefined or unknown, it results in a protocolError. - Changed "The server MUST be prepared" to "Implementations MUST be prepared" in the eighth paragraph to reflect that both client and server implementations must be able to handle this (as both parse controls). -C.1.14 Section 4.2 +C.1.12 Section 4.2 - Mandated that servers return protocolError when the version is not supported. - Clarified behavior when the simple authentication is used, the name is empty and the password is non-empty. - Required servers to not dereference aliases for bind. This was added for consistency with other operations and to help ensure data consistency. - Required that textual passwords be transferred as UTF-8 encoded Unicode, and added recommendations on string preparation. This was to help ensure interoperability of passwords being sent from different clients. -C.1.15 Section 4.2.1 +C.1.13 Section 4.2.1 - This section was largely reorganized for readability and language was added to clarify the authentication state of failed and abandoned bind operations. - 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. - Dropped MUST imperative in paragraph 3 to align with [Keywords]. - Mandated that clients not send non-bind operations while a bind is in progress, and suggested that servers not process them if they - Lightweight Directory Access Protocol Version 3 - are received. This is needed to ensure proper sequencing of the bind in relationship to other operations. -C.1.16 Section 4.2.3 +C.1.14 Section 4.2.3 - Moved most error-related text to Appendix A, and added text regarding certain errors used in conjunction with the bind operation. - Prohibited the server from specifying serverSaslCreds when not appropriate. -C.1.17 Section 4.3 + Lightweight Directory Access Protocol Version 3 + +C.1.15 Section 4.3 - Required both peers to cease transmission and close the LDAP exchange for the unbind operation. -C.1.18 Section 4.4 +C.1.16 Section 4.4 - Added instructions for future specifications of Unsolicited Notifications. -C.1.19 Section 4.5.1 +C.1.17 Section 4.5.1 - SearchRequest attributes is now defined as an AttributeSelection type rather than AttributeDescriptionList, and an ABNF is provided. - SearchRequest attributes may contain duplicate attribute descriptions. This was previously prohibited. Now servers are instructed to ignore subsequent names when they are duplicated. This was relaxed in order to allow different short names and also OIDs to be requested for an attribute. - - The Filter choices 'and' and 'or', and the SubstringFilter - substrings types are now defined with a lower bound of 1. + - The Filter choice SubstringFilter substrings type is now defined + with a lower bound of 1. - The SubstringFilter substrings 'initial, 'any', and 'final' types are now AssertionValue rather than LDAPString. Also, added imperatives stating that 'initial' (if present) must be listed first, and 'final' (if present) must be listed last. - Clarified the semantics of the derefAliases choices. - Added instructions for equalityMatch, substrings, greaterOrEqual, lessOrEqual, and approxMatch. -C.1.20 Section 4.5.2 +C.1.18 Section 4.5.2 - Recommended that servers not use attribute short names when it knows they are ambiguous or may cause interoperability problems. - Removed all mention of ExtendedResponse due to lack of implementation. - Lightweight Directory Access Protocol Version 3 - -C.1.21 Section 4.5.3 +C.1.19 Section 4.5.3 - Made changes similar to those made to Section 4.1.11. -C.1.22 Section 4.5.3.1 +C.1.20 Section 4.5.3.1 - Fixed examples to adhere to changes made to Section 4.5.3. -C.1.23 Section 4.6 +C.1.21 Section 4.6 + + Lightweight Directory Access Protocol Version 3 - Removed restriction that required an EQUALITY matching rule in order to perform value delete modifications. It is sufficiently documented that in absence of an equality matching rule, octet equality is used. - Replaced AttributeTypeAndValues with Attribute as they are equivalent. - Clarified what type of modification changes might temporarily violate schema. -C.1.24 Section 4.7 +C.1.22 Section 4.7 - Aligned Add operation with X.511 in that the attributes of the RDN are used in conjunction with the listed attributes to create the entry. Previously, Add required that the distinguished values be present in the listed attributes. -C.1.25 Section 4.9 +C.1.23 Section 4.9 - Required servers to not dereference aliases for modify DN. This was added for consistency with other operations and to help ensure data consistency. - Allow modify DN to fail when moving between naming contexts. - Specified what happens when the attributes of the newrdn are no present on the entry. -C.1.26 Section 4.10 +C.1.24 Section 4.10 - Clarified that compareFalse means that the compare took place and the result is false. There was confusion which lead people to believe that an Undefined match resulted in compareFalse. - Required servers to not dereference aliases for compare. This was added for consistency with other operations and to help ensure data consistency. -C.1.27 Section 4.11 +C.1.25 Section 4.11 - Explained that since abandon returns no response, clients should not use it if they need to know the outcome. - - Lightweight Directory Access Protocol Version 3 - - Specified that Abandon and Unbind cannot be abandoned. -C.1.28 Section 4.12 +C.1.26 Section 4.12 - Specified how values of extended operations defined in terms of ASN.1 are to be encoded. - Added instructions on what extended operation specifications consist of. - Added a recommendation that servers advertise supported extended operations. -C.1.29 Section 5.2 + Lightweight Directory Access Protocol Version 3 + +C.1.27 Section 5.2 - Moved referral-specific instructions into referral-related sections. -C.1.30 Section 7 +C.1.28 Section 7 - Reworded notes regarding SASL not protecting certain aspects of the LDAP bind PDU. - Noted that Servers are encouraged to prevent directory modifications by clients that have authenticated anonymously [AuthMeth]. - Added a note regarding the scenario where an identity is changed (deleted, privileges or credentials modified, etc.). - Warned against following referrals that may have been injected in the data stream. - Noted that servers should protect information equally, whether in an error condition or not, and mentioned specifically; matchedDN, diagnosticMessage, and resultCodes. - Added a note regarding malformed and long encodings. -C.1.31 Appendix A +C.1.29 Appendix A - - Added "EXTESIBILITY IMPLIED" to ASN.1 definition. + - Added "EXTENSIBILITY IMPLIED" to ASN.1 definition. - Removed AttributeType. It is not used. C.2 Changes made to RFC 2830: This section summarizes the substantive changes made to Sections of RFC 2830. Readers should consult [AuthMeth] for summaries of changes to other sections. C.2.1 Section 2.3 - Removed wording indicating that referrals can be returned from StartTLS - Lightweight Directory Access Protocol Version 3 - - Removed requirement that only a narrow set of result codes can be returned. Some result codes are required in certain scenarios, but any other may be returned if appropriate. C.2.1 Section 4.13.3.1 - Reworded most of this section and added the requirement that after the TLS connection has been closed, the server MUST NOT send responses to any request message received before the TLS closure. C.3 Changes made to RFC 3771: + Lightweight Directory Access Protocol Version 3 + - In general, all technical language was transferred in whole. Supporting and background language seen as redundant due to its presence in this document was omitted. Lightweight Directory Access Protocol Version 3 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information - on the IETF's procedures with respect to rights in IETF Documents can - be found in BCP 78 and BCP 79. + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. + . The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf- - ipr@ietf.org." - -Copyright Statement - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - retain all their rights. + ipr@ietf.org. Disclaimer of Validity This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM 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. + +Copyright Statement + + Copyright (C) The Internet Society (2004). This document is subject + to the rights, licenses and restrictions contained in BCP 78, and + except as set forth therein, the authors retain all their rights. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society.