idnits 2.17.1 draft-ietf-ldapbis-protocol-26.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1.a on line 15. -- Found old boilerplate from RFC 3978, Section 5.5 on line 3156. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 3134. ** The document seems to lack an RFC 3978 Section 5.1 IPR Disclosure Acknowledgement. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. ** The document seems to lack an RFC 3979 Section 5, para. 1 IPR Disclosure Acknowledgement -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack an RFC 3979 Section 5, para. 3 IPR Disclosure Invitation -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document uses RFC 3667 boilerplate or RFC 3978-like boilerplate instead of verbatim RFC 3978 boilerplate. After 6 May 2005, submission of drafts without verbatim RFC 3978 boilerplate is not accepted. The following non-3978 patterns matched text found in the document. That text should be removed or replaced: 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 becomes aware will be disclosed, in accordance with Section 6 of BCP 79. == In addition to a regular copyright notice, the document also has a copyright notice embedded in the text. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 38) being 59 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. == The 'Obsoletes: ' line in the draft header should list only the _numbers_ of the RFCs which will be obsoleted by this document (if approved); it should not include the word 'RFC' in the list. -- The draft header indicates that this document obsoletes RFC2251, but the abstract doesn't seem to mention this, which it should. -- The draft header indicates that this document obsoletes RFC2830, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The exact meaning of the all-uppercase expression 'MAY NOT' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: - 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 automatically. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (Aug 2004) is 7166 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 2794 -- Looks like a reference, but probably isn't: '3' on line 2727 == Missing Reference: 'APPLICATION 0' is mentioned on line 2660, but not defined == Missing Reference: 'SASLprep' is mentioned on line 785, but not defined == Missing Reference: 'Stringprep' is mentioned on line 785, but not defined == Missing Reference: 'APPLICATION 1' is mentioned on line 2675, but not defined -- Looks like a reference, but probably isn't: '7' on line 2711 == Missing Reference: 'APPLICATION 2' is mentioned on line 2680, but not defined == Missing Reference: 'APPLICATION 3' is mentioned on line 2682, but not defined -- Looks like a reference, but probably isn't: '1' on line 2795 -- Looks like a reference, but probably isn't: '2' on line 2726 -- Looks like a reference, but probably isn't: '4' on line 2728 -- Looks like a reference, but probably isn't: '5' on line 2709 -- Looks like a reference, but probably isn't: '6' on line 2710 -- Looks like a reference, but probably isn't: '8' on line 2712 -- Looks like a reference, but probably isn't: '9' on line 2713 == Missing Reference: 'APPLICATION 4' is mentioned on line 2730, but not defined == Missing Reference: 'APPLICATION 19' is mentioned on line 2738, but not defined == Missing Reference: 'APPLICATION 5' is mentioned on line 2741, but not defined == Missing Reference: 'APPLICATION 6' is mentioned on line 2743, but not defined == Missing Reference: 'APPLICATION 7' is mentioned on line 2752, but not defined == Missing Reference: 'APPLICATION 8' is mentioned on line 2754, but not defined == Missing Reference: 'APPLICATION 9' is mentioned on line 2760, but not defined == Missing Reference: 'APPLICATION 10' is mentioned on line 2762, but not defined == Missing Reference: 'APPLICATION 11' is mentioned on line 2764, but not defined == Missing Reference: 'APPLICATION 12' is mentioned on line 2766, but not defined == Missing Reference: 'APPLICATION 13' is mentioned on line 2772, but not defined == Missing Reference: 'APPLICATION 14' is mentioned on line 2774, but not defined == Missing Reference: 'APPLICATION 15' is mentioned on line 2778, but not defined == Missing Reference: 'APPLICATION 16' is mentioned on line 2780, but not defined == Missing Reference: 'APPLICATION 23' is mentioned on line 2782, but not defined == Missing Reference: 'APPLICATION 24' is mentioned on line 2786, but not defined -- Looks like a reference, but probably isn't: '10' on line 2788 -- Looks like a reference, but probably isn't: '11' on line 2791 == Missing Reference: 'APPLICATION 25' is mentioned on line 2793, but not defined == Missing Reference: 'Keywords' is mentioned on line 2945, but not defined == Unused Reference: 'IP' is defined on line 2168, but no explicit reference was found in the text == Unused Reference: 'SASLPrep' is defined on line 2197, but no explicit reference was found in the text == Unused Reference: 'StringPrep' is defined on line 2201, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2234 (ref. 'ABNF') (Obsoleted by RFC 4234) -- No information found for draft-ietf-ldapbis-authmeth-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'AuthMeth' -- Possible downref: Non-RFC (?) normative reference: ref. 'BER' -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO10646' -- No information found for draft-ietf-ldapbis-dn-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'LDAPDN' -- No information found for draft-ietf-ldapbis-bcp64-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'LDAPIANA' -- No information found for draft-ietf-ldapbis-url-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'LDAPURL' -- No information found for draft-ietf-ldapbis-models-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'Models' -- No information found for draft-ietf-ldapbis-roadmap-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'Roadmap' -- No information found for draft-ietf-sasl-rfc2222bis-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'SASL' -- No information found for draft-ietf-sasl-saslprep-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'SASLPrep' -- No information found for draft-hoffman-rfc3454bis-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'StringPrep' -- No information found for draft-ietf-ldapbis-syntaxes-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'Syntaxes' ** Obsolete normative reference: RFC 793 (ref. 'TCP') (Obsoleted by RFC 9293) -- No information found for draft-ietf-tls-rfc2246-bis-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'TLS' -- Possible downref: Non-RFC (?) normative reference: ref. 'Unicode' ** Obsolete normative reference: RFC 2396 (ref. 'URI') (Obsoleted by RFC 3986) Summary: 10 errors (**), 0 flaws (~~), 34 warnings (==), 45 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet-Draft Editor: J. Sermersheim 2 Intended Category: Standard Track Novell, Inc 3 Document: draft-ietf-ldapbis-protocol-26.txt Aug 2004 4 Obsoletes: RFCs 2251, 2830, 3771 6 LDAP: The Protocol 8 Status of this Memo 10 This document is an Internet-Draft and is subject to all provisions 11 of section 3 of RFC 3667. By submitting this Internet-Draft, each 12 author represents that any applicable patent or other IPR claims of 13 which he or she is aware have been or will be disclosed, and any of 14 which he or she become aware will be disclosed, in accordance with 15 RFC 3668. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 Technical discussion of this document will take place on the IETF 34 LDAP Revision Working Group (LDAPbis) mailing list . Please send editorial comments directly to the 36 editor . 38 Copyright Notice 40 Copyright (C) The Internet Society 2004. 42 Abstract 44 This document describes the protocol elements, along with their 45 semantics and encodings, of the Lightweight Directory Access Protocol 46 (LDAP). LDAP provides access to distributed directory services that 47 act in accordance with X.500 data and service models. These protocol 48 elements are based on those described in the X.500 Directory Access 49 Protocol (DAP). 51 Lightweight Directory Access Protocol Version 3 53 Table of Contents 55 1. Introduction....................................................3 56 1.1. Relationship to Obsolete Specifications.......................3 57 2. Conventions.....................................................3 58 3. Protocol Model..................................................4 59 3.1 Operation and LDAP Exchange Relationship.......................4 60 4. Elements of Protocol............................................5 61 4.1. Common Elements...............................................5 62 4.1.1. Message Envelope............................................5 63 4.1.2. String Types................................................7 64 4.1.3. Distinguished Name and Relative Distinguished Name..........7 65 4.1.4. Attribute Descriptions......................................7 66 4.1.5. Attribute Value.............................................8 67 4.1.6. Attribute Value Assertion...................................8 68 4.1.7. Attribute and PartialAttribute..............................9 69 4.1.8. Matching Rule Identifier....................................9 70 4.1.9. Result Message..............................................9 71 4.1.10. Referral..................................................11 72 4.1.11. Controls..................................................12 73 4.2. Bind Operation...............................................14 74 4.3. Unbind Operation.............................................17 75 4.4. Unsolicited Notification.....................................17 76 4.5. Search Operation.............................................18 77 4.6. Modify Operation.............................................27 78 4.7. Add Operation................................................28 79 4.8. Delete Operation.............................................29 80 4.9. Modify DN Operation..........................................30 81 4.10. Compare Operation...........................................31 82 4.11. Abandon Operation...........................................32 83 4.12. Extended Operation..........................................32 84 4.13. IntermediateResponse Message................................34 85 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse......35 86 4.13.2. Usage with LDAP Request Controls..........................35 87 4.14. StartTLS Operation..........................................35 88 5. Protocol Encoding, Connection, and Transfer....................37 89 5.2. Protocol Encoding............................................38 90 5.3. Transmission Control Protocol (TCP)..........................38 91 6. Security Considerations........................................39 92 7. Acknowledgements...............................................40 93 8. Normative References...........................................40 94 9. Informative References.........................................42 95 10. IANA Considerations...........................................42 96 11. Editor's Address..............................................43 97 Appendix A - LDAP Result Codes....................................44 98 A.1 Non-Error Result Codes........................................44 99 A.2 Result Codes..................................................44 100 Appendix B - Complete ASN.1 Definition............................49 101 Appendix C - Changes..............................................55 102 C.1 Changes made to RFC 2251:.....................................55 103 C.2 Changes made to RFC 2830:.....................................60 104 C.3 Changes made to RFC 3771:.....................................61 105 Lightweight Directory Access Protocol Version 3 107 1. Introduction 109 The Directory is "a collection of open systems cooperating to provide 110 directory services" [X.500]. A directory user, which may be a human 111 or other entity, accesses the Directory through a client (or 112 Directory User Agent (DUA)). The client, on behalf of the directory 113 user, interacts with one or more servers (or Directory System Agents 114 (DSA)). Clients interact with servers using a directory access 115 protocol. 117 This document details the protocol elements of the Lightweight 118 Directory Access Protocol (LDAP), along with their semantics. 119 Following the description of protocol elements, it describes the way 120 in which the protocol elements are encoded and transferred. 122 1.1. Relationship to Obsolete Specifications 124 This document is an integral part of the LDAP Technical Specification 125 [Roadmap] which obsoletes the previously defined LDAP technical 126 specification, RFC 3377, in its entirety. 128 This document obsoletes all of RFC 2251 except the following: 129 Sections 3.2, 3.4, 4.1.3 (last paragraph), 4.1.4, 4.1.5, 4.1.5.1, 130 4.1.9 (last paragraph), 5.1, 6.1, and 6.2 (last paragraph) are 131 obsoleted by [Models]. 132 Section 3.3 is obsoleted by [Roadmap]. 133 Sections 4.2.1 (portions), and 4.2.2 are obsoleted by [AuthMeth]. 135 Appendix C.1 summarizes substantive changes to the remaining 136 sections. 138 This document obsoletes RFC 2830, Sections 2 and 4 in entirety. The 139 remainder of RFC 2830 is obsoleted by [AuthMeth]. Appendix C.2 140 summarizes substantive changes to the remaining sections. 142 This document also obsoletes RFC 3771 in entirety. 144 2. Conventions 146 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 147 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are 148 to be interpreted as described in [Keyword]. 150 The term "connection" refers to the underlying transport service used 151 to carry the protocol exchange. 153 The term "LDAP exchange" refers to application layer where LDAP PDUs 154 are exchanged between protocol peers. 156 The term "TLS layer" refers to a layer inserted between the 157 connection and the LDAP exchange that utilizes Transport Layer 158 Security ([TLS]) to protect the exchange of LDAP PDUs. 160 Lightweight Directory Access Protocol Version 3 162 The term "SASL layer" refers to a layer inserted between the 163 connection and the LDAP exchange that utilizes Simple Authentication 164 and Security Layer ([SASL]) to protect the exchange of LDAP PDUs. 166 See the table in Section 5 for an illustration of these four terms. 168 The term "TLS-protected LDAP exchange" refers to an LDAP exchange 169 protected by a TLS-layer. 171 The term "association" refers to the association of the LDAP exchange 172 and its current authentication and authorization state. 174 Character names in this document use the notation for code points and 175 names from the Unicode Standard [Unicode]. For example, the letter 176 "a" may be represented as either or . 178 Note: a glossary of terms used in Unicode can be found in [Glossary]. 179 Information on the Unicode character encoding model can be found in 180 [CharModel]. 182 3. Protocol Model 184 The general model adopted by this protocol is one of clients 185 performing protocol operations against servers. In this model, a 186 client transmits a protocol request describing the operation to be 187 performed to a server. The server is then responsible for performing 188 the necessary operation(s) in the Directory. Upon completion of an 189 operation, the server typically returns a response containing 190 appropriate data to the requesting client. 192 Protocol operations are generally independent of one another. Each 193 operation is processed as an atomic action, leaving the directory in 194 a consistent state. 196 Although servers are required to return responses whenever such 197 responses are defined in the protocol, there is no requirement for 198 synchronous behavior on the part of either clients or servers. 199 Requests and responses for multiple operations generally may be 200 exchanged between a client and server in any order. If required, 201 synchronous behavior may be controlled by client applications. 203 The core protocol operations defined in this document can be mapped 204 to a subset of the X.500 (1993) Directory Abstract Service [X.511]. 205 However there is not a one-to-one mapping between LDAP operations and 206 X.500 Directory Access Protocol (DAP) operations. Server 207 implementations acting as a gateway to X.500 directories may need to 208 make multiple DAP requests to service a single LDAP request. 210 3.1 Operation and LDAP Exchange Relationship 211 Lightweight Directory Access Protocol Version 3 213 Protocol operations are tied to an LDAP exchange. When the connection 214 is closed, any uncompleted operations tied to the LDAP exchange are, 215 when possible, abandoned, and when not possible, completed without 216 transmission of the response. Also, when the connection is closed, 217 the client MUST NOT assume that any uncompleted update operations 218 tied to the LDAP exchange have succeeded or failed. 220 4. Elements of Protocol 222 The protocol is described using Abstract Syntax Notation One 223 ([ASN.1]), and is transferred using a subset of ASN.1 Basic Encoding 224 Rules ([BER]). Section 5 specifies how the protocol elements are 225 encoded and transferred. 227 In order to support future extensions to this protocol, extensibility 228 is implied where it is allowed per ASN.1 (i.e. sequence, set, choice, 229 and enumerated types are extensible). In addition, ellipses (...) 230 have been supplied in ASN.1 types that are explicitly extensible as 231 discussed in [LDAPIANA]. Because of the implied extensibility, 232 clients and servers MUST (unless otherwise specified) ignore trailing 233 SEQUENCE components whose tags they do not recognize. 235 Changes to the protocol other than through the extension mechanisms 236 described here require a different version number. A client indicates 237 the version it is using as part of the bind request, described in 238 Section 4.2. If a client has not sent a bind, the server MUST assume 239 the client is using version 3 or later. 241 Clients may determine the protocol versions a server supports by 242 reading the 'supportedLDAPVersion' attribute from the root DSE (DSA- 243 Specific Entry) [Models]. 245 4.1. Common Elements 247 This section describes the LDAPMessage envelope Protocol Data Unit 248 (PDU) format, as well as data type definitions, which are used in the 249 protocol operations. 251 4.1.1. Message Envelope 253 For the purposes of protocol exchanges, all protocol operations are 254 encapsulated in a common envelope, the LDAPMessage, which is defined 255 as follows: 257 LDAPMessage ::= SEQUENCE { 258 messageID MessageID, 259 protocolOp CHOICE { 260 bindRequest BindRequest, 261 bindResponse BindResponse, 262 unbindRequest UnbindRequest, 263 searchRequest SearchRequest, 265 Lightweight Directory Access Protocol Version 3 267 searchResEntry SearchResultEntry, 268 searchResDone SearchResultDone, 269 searchResRef SearchResultReference, 270 modifyRequest ModifyRequest, 271 modifyResponse ModifyResponse, 272 addRequest AddRequest, 273 addResponse AddResponse, 274 delRequest DelRequest, 275 delResponse DelResponse, 276 modDNRequest ModifyDNRequest, 277 modDNResponse ModifyDNResponse, 278 compareRequest CompareRequest, 279 compareResponse CompareResponse, 280 abandonRequest AbandonRequest, 281 extendedReq ExtendedRequest, 282 extendedResp ExtendedResponse, 283 ..., 284 intermediateResponse IntermediateResponse }, 285 controls [0] Controls OPTIONAL } 287 MessageID ::= INTEGER (0 .. maxInt) 289 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) -- 291 The ASN.1 type Controls is defined in Section 4.1.11. 293 The function of the LDAPMessage is to provide an envelope containing 294 common fields required in all protocol exchanges. At this time the 295 only common fields are the messageID and the controls. 297 If the server receives a PDU from the client in which the LDAPMessage 298 SEQUENCE tag cannot be recognized, the messageID cannot be parsed, 299 the tag of the protocolOp is not recognized as a request, or the 300 encoding structures or lengths of data fields are found to be 301 incorrect, then the server SHOULD return the Notice of Disconnection 302 described in Section 4.4.1, with the resultCode set to protocolError, 303 and MUST immediately close the connection. 305 In other cases where the client or server cannot parse a PDU, it 306 SHOULD abruptly close the connection where further communication 307 (including providing notice) would be pernicious. Otherwise, server 308 implementations MUST return an appropriate response to the request, 309 with the resultCode set to protocolError. 311 4.1.1.1. Message ID 313 All LDAPMessage envelopes encapsulating responses contain the 314 messageID value of the corresponding request LDAPMessage. 316 The message ID of a request MUST have a non-zero value different from 317 the values of any other uncompleted requests in the LDAP association 318 of which this message is a part. The zero value is reserved for the 319 unsolicited notification message. 321 Lightweight Directory Access Protocol Version 3 323 Typical clients increment a counter for each request. 325 A client MUST NOT send a request with the same message ID as an 326 earlier request on the same LDAP association unless it can be 327 determined that the server is no longer servicing the earlier request 328 (e.g. after the final response is received, or a subsequent bind 329 completes). Otherwise the behavior is undefined. For this purpose, 330 note that abandon and abandoned operations do not send responses. 332 4.1.2. String Types 334 The LDAPString is a notational convenience to indicate that, although 335 strings of LDAPString type encode as ASN.1 OCTET STRING types, the 336 [ISO10646] character set (a superset of [Unicode]) is used, encoded 337 following the [UTF-8] algorithm. Note that Unicode characters U+0000 338 through U+007F are the same as ASCII 0 through 127, respectively, and 339 have the same single octet UTF-8 encoding. Other Unicode characters 340 have a multiple octet UTF-8 encoding. 342 LDAPString ::= OCTET STRING -- UTF-8 encoded, 343 -- [ISO10646] characters 345 The LDAPOID is a notational convenience to indicate that the 346 permitted value of this string is a (UTF-8 encoded) dotted-decimal 347 representation of an OBJECT IDENTIFIER. Although an LDAPOID is 348 encoded as an OCTET STRING, values are limited to the definition of 349 given in Section 1.4 of [Models]. 351 LDAPOID ::= OCTET STRING -- Constrained to [Models] 353 For example, 355 1.3.6.1.4.1.1466.1.2.3 357 4.1.3. Distinguished Name and Relative Distinguished Name 359 An LDAPDN is defined to be the representation of a Distinguished Name 360 (DN) after encoding according to the specification in [LDAPDN]. 362 LDAPDN ::= LDAPString 363 -- Constrained to [LDAPDN] 365 A RelativeLDAPDN is defined to be the representation of a Relative 366 Distinguished Name (RDN) after encoding according to the 367 specification in [LDAPDN]. 369 RelativeLDAPDN ::= LDAPString 370 -- Constrained to [LDAPDN] 372 4.1.4. Attribute Descriptions 373 Lightweight Directory Access Protocol Version 3 375 The definition and encoding rules for attribute descriptions are 376 defined in Section 2.5 of [Models]. Briefly, an attribute description 377 is an attribute type and zero or more options. 379 AttributeDescription ::= LDAPString 380 -- Constrained to 381 -- [Models] 383 4.1.5. Attribute Value 385 A field of type AttributeValue is an OCTET STRING containing an 386 encoded attribute value. The attribute value is encoded according to 387 the LDAP-specific encoding definition of its corresponding syntax. 388 The LDAP-specific encoding definitions for different syntaxes and 389 attribute types may be found in other documents and in particular 390 [Syntaxes]. 392 AttributeValue ::= OCTET STRING 394 Note that there is no defined limit on the size of this encoding; 395 thus protocol values may include multi-megabyte attribute values 396 (e.g. photographs). 398 Attribute values may be defined which have arbitrary and non- 399 printable syntax. Implementations MUST NOT display nor attempt to 400 decode an attribute value if its syntax is not known. The 401 implementation may attempt to discover the subschema of the source 402 entry, and retrieve the descriptions of 'attributeTypes' from it 403 [Models]. 405 Clients MUST only send attribute values in a request that are valid 406 according to the syntax defined for the attributes. 408 4.1.6. Attribute Value Assertion 410 The AttributeValueAssertion (AVA) type definition is similar to the 411 one in the X.500 Directory standards. It contains an attribute 412 description and a matching rule ([Models Section 4.1.3) assertion 413 value suitable for that type. Elements of this type are typically 414 used to assert that the value in assertionValue matches a value of an 415 attribute. 417 AttributeValueAssertion ::= SEQUENCE { 418 attributeDesc AttributeDescription, 419 assertionValue AssertionValue } 421 AssertionValue ::= OCTET STRING 423 The syntax of the AssertionValue depends on the context of the LDAP 424 operation being performed. For example, the syntax of the EQUALITY 425 matching rule for an attribute is used when performing a Compare 426 Lightweight Directory Access Protocol Version 3 428 operation. Often this is the same syntax used for values of the 429 attribute type, but in some cases the assertion syntax differs from 430 the value syntax. See objectIdentiferFirstComponentMatch in 431 [Syntaxes] for an example. 433 4.1.7. Attribute and PartialAttribute 435 Attributes and partial attributes consist of an attribute description 436 and attribute values. A PartialAttribute allows zero values, while 437 Attribute requires at least one value. 439 PartialAttribute ::= SEQUENCE { 440 type AttributeDescription, 441 vals SET OF value AttributeValue } 443 Attribute ::= PartialAttribute(WITH COMPONENTS { 444 ..., 445 vals (SIZE(1..MAX))}) 447 No two attribute values may be equivalent as described by Section 2.3 448 of [Models]. The set of attribute values is unordered. 449 Implementations MUST NOT rely upon the ordering being repeatable. 451 4.1.8. Matching Rule Identifier 453 Matching rules are defined in Section 4.1.3 of [Models]. A matching 454 rule is identified in the protocol by the printable representation of 455 either its , or one of its short name descriptors 456 [Models], e.g. 'caseIgnoreMatch' or '2.5.13.2'. 458 MatchingRuleId ::= LDAPString 460 4.1.9. Result Message 462 The LDAPResult is the construct used in this protocol to return 463 success or failure indications from servers to clients. To various 464 requests, servers will return responses of LDAPResult or responses 465 containing the components of LDAPResult to indicate the final status 466 of a protocol operation request. 468 LDAPResult ::= SEQUENCE { 469 resultCode ENUMERATED { 470 success (0), 471 operationsError (1), 472 protocolError (2), 473 timeLimitExceeded (3), 474 sizeLimitExceeded (4), 475 compareFalse (5), 476 compareTrue (6), 477 authMethodNotSupported (7), 478 strongAuthRequired (8), 480 Lightweight Directory Access Protocol Version 3 482 -- 9 reserved -- 483 referral (10), 484 adminLimitExceeded (11), 485 unavailableCriticalExtension (12), 486 confidentialityRequired (13), 487 saslBindInProgress (14), 488 noSuchAttribute (16), 489 undefinedAttributeType (17), 490 inappropriateMatching (18), 491 constraintViolation (19), 492 attributeOrValueExists (20), 493 invalidAttributeSyntax (21), 494 -- 22-31 unused -- 495 noSuchObject (32), 496 aliasProblem (33), 497 invalidDNSyntax (34), 498 -- 35 reserved for undefined isLeaf -- 499 aliasDereferencingProblem (36), 500 -- 37-47 unused -- 501 inappropriateAuthentication (48), 502 invalidCredentials (49), 503 insufficientAccessRights (50), 504 busy (51), 505 unavailable (52), 506 unwillingToPerform (53), 507 loopDetect (54), 508 -- 55-63 unused -- 509 namingViolation (64), 510 objectClassViolation (65), 511 notAllowedOnNonLeaf (66), 512 notAllowedOnRDN (67), 513 entryAlreadyExists (68), 514 objectClassModsProhibited (69), 515 -- 70 reserved for CLDAP -- 516 affectsMultipleDSAs (71), 517 -- 72-79 unused -- 518 other (80), 519 ... }, 520 matchedDN LDAPDN, 521 diagnosticMessage LDAPString, 522 referral [3] Referral OPTIONAL } 524 The resultCode enumeration is extensible as defined in Section 3.6 of 525 [LDAPIANA]. The meanings of the listed result codes are given in 526 Appendix A. If a server detects multiple errors for an operation, 527 only one result code is returned. The server should return the result 528 code that best indicates the nature of the error encountered. 530 The diagnosticMessage field of this construct may, at the server's 531 option, be used to return a string containing a textual, human- 532 readable (terminal control and page formatting characters should be 533 avoided) diagnostic message. As this diagnostic message is not 534 standardized, implementations MUST NOT rely on the values returned. 536 Lightweight Directory Access Protocol Version 3 538 If the server chooses not to return a textual diagnostic, the 539 diagnosticMessage field MUST be empty. 541 For certain result codes (typically, but not restricted to 542 noSuchObject, aliasProblem, invalidDNSyntax and 543 aliasDereferencingProblem), the matchedDN field is set to the name of 544 the lowest entry (object or alias) in the Directory that was matched. 545 If no aliases were dereferenced while attempting to locate the entry, 546 this will be a truncated form of the name provided, or if aliases 547 were dereferenced, of the resulting name, as defined in Section 12.5 548 of [X.511]. Otherwise the matchedDN field is empty. 550 4.1.10. Referral 552 The referral result code indicates that the contacted server cannot 553 or will not perform the operation and that one or more other servers 554 may be able to. Reasons for this include: 556 - The target entry of the request is not held locally, but the 557 server has knowledge of its possible existence elsewhere. 559 - The operation is restricted on this server -- perhaps due to a 560 read-only copy of an entry to be modified. 562 The referral field is present in an LDAPResult if the resultCode 563 field value is referral, and absent with all other result codes. It 564 contains one or more references to one or more servers or services 565 that may be accessed via LDAP or other protocols. Referrals can be 566 returned in response to any operation request (except unbind and 567 abandon which do not have responses). At least one URI MUST be 568 present in the Referral. 570 During a search operation, after the baseObject is located, and 571 entries are being evaluated, the referral is not returned. Instead, 572 continuation references, described in Section 4.5.3, are returned 573 when other servers would need to be contacted to complete the 574 operation. 576 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI 578 URI ::= LDAPString -- limited to characters permitted in 579 -- URIs 581 If the client wishes to progress the operation, it MUST follow the 582 referral by contacting one of the supported services. If multiple 583 URIs are present, the client assumes that any supported URI may be 584 used to progress the operation. 586 Protocol peers that follow referrals MUST ensure that they do not 587 loop between servers. They MUST NOT repeatedly contact the same 588 server for the same request with the same target entry name, scope 589 and filter. Some implementations use a counter that is incremented 590 each time referral handling occurs for an operation, and these kinds 591 Lightweight Directory Access Protocol Version 3 593 of implementations MUST be able to handle at least ten nested 594 referrals between the root and a leaf entry. 596 A URI for a server implementing LDAP and accessible via [TCP]/[IP] 597 (v4 or v6) is written as an LDAP URL according to [LDAPURL]. 599 When an LDAP URL is used, the following instructions are followed: 601 - If an alias was dereferenced, the part of the URL MUST be 602 present, with the new target object name. UTF-8 encoded characters 603 appearing in the string representation of a DN or search filter 604 may not be legal for URLs (e.g. spaces) and MUST be escaped using 605 the % method in [URI]. 607 - It is RECOMMENDED that the part be present to avoid 608 ambiguity. 610 - If the part is present, the client MUST use this name in its 611 next request to progress the operation, and if it is not present 612 the client will use the same name as in the original request. 614 - Some servers (e.g. participating in distributed indexing) may 615 provide a different filter in a URL of a referral for a search 616 operation. 618 - If the part of the LDAP URL is present, the client MUST 619 use this filter in its next request to progress this search, and 620 if it is not present the client MUST use the same filter as it 621 used for that search. 623 - For search, it is RECOMMENDED that the part be present to 624 avoid ambiguity. 626 - If the part is missing, the scope of the original search 627 is used by the client to progress the operation. 629 - Other aspects of the new request may be the same as or different 630 from the request which generated the referral. 632 Other kinds of URIs may be returned. The syntax and semantics of such 633 URIs is left to future specifications. Clients may ignore URIs that 634 they do not support. 636 4.1.11. Controls 638 Controls provide a mechanism whereby the semantics and arguments of 639 existing LDAP operations may be extended. One or more controls may be 640 attached to a single LDAP message. A control only affects the 641 semantics of the message it is attached to. 643 Controls sent by clients are termed 'request controls' and those sent 644 by servers are termed 'response controls'. 646 Lightweight Directory Access Protocol Version 3 648 Controls ::= SEQUENCE OF control Control 650 Control ::= SEQUENCE { 651 controlType LDAPOID, 652 criticality BOOLEAN DEFAULT FALSE, 653 controlValue OCTET STRING OPTIONAL } 655 The controlType field is the dotted-decimal representation of an 656 OBJECT IDENTIFIER which uniquely identifies the control. This 657 provides unambiguous naming of controls. Often, response control(s) 658 solicited by a request control share controlType values with the 659 request control. 661 The criticality field only has meaning in controls attached to 662 request messages (except unbindRequest). For controls attached to 663 response messages and the unbindRequest, the criticality field SHOULD 664 be FALSE, and MUST be ignored by the receiving protocol peer. A value 665 of TRUE indicates that it is unacceptable to perform the operation 666 without applying the semantics of the control and FALSE otherwise. 667 Specifically, the criticality field is applied as follows: 669 - Regardless of the value of the criticality field, if the server 670 recognizes the control type and it is appropriate for the 671 operation, the server is to make use of the control when 672 performing the operation. 674 - If the server does not recognize the control type or it is not 675 appropriate for the operation, and the criticality field is TRUE, 676 the server MUST NOT perform the operation, and for operations that 677 have a response message, MUST return unavailableCriticalExtension 678 in the resultCode. 680 - If the server does not recognize the control type or it is not 681 appropriate for the operation, and the criticality field is FALSE, 682 the server MUST ignore the control. 684 The controlValue may contain information associated with the 685 controlType. Its format is defined by the specification of the 686 control. Implementations MUST be prepared to handle arbitrary 687 contents of the controlValue octet string, including zero bytes. It 688 is absent only if there is no value information which is associated 689 with a control of its type. When a controlValue is defined in terms 690 of ASN.1, and BER encoded according to Section 5.2, it also follows 691 the extensibility rules in Section 4. 693 Servers list the controlType of request controls they recognize in 694 the 'supportedControl' attribute in the root DSE (Section 5.1 of 695 [Models]). 697 Controls SHOULD NOT be combined unless the semantics of the 698 combination has been specified. The semantics of control 699 combinations, if specified, are generally found in the control 700 specification most recently published. When a combination of controls 701 is encountered whose semantics are invalid, not specified (or not 702 Lightweight Directory Access Protocol Version 3 704 known), the message is considered to be not well-formed, thus the 705 operation fails with protocolError. Additionally, unless order- 706 dependent semantics are given in a specification, the order of a 707 combination of controls in the SEQUENCE is ignored. Where the order 708 is to be ignored but cannot be ignored by the server, the message is 709 considered not well-formed and the operation fails with 710 protocolError. 712 This document does not specify any controls. Controls may be 713 specified in other documents. Documents detailing control extensions 714 are to provide for each control: 716 - the OBJECT IDENTIFIER assigned to the control, 718 - direction as to what value the sender should provide for the 719 criticality field (note: the semantics of the criticality field 720 are defined above should not be altered by the control's 721 specification), 723 - whether information is to be present in the controlValue field, 724 and if so, the format of the controlValue contents, 726 - the semantics of the control, and 728 - optionally, semantics regarding the combination of the control 729 with other controls. 731 4.2. Bind Operation 733 The function of the Bind Operation is to allow authentication 734 information to be exchanged between the client and server. The Bind 735 operation should be thought of as the "authenticate" operation. 736 Operational, authentication, and security-related semantics of this 737 operation are given in [AuthMeth]. 739 The Bind Request is defined as follows: 741 BindRequest ::= [APPLICATION 0] SEQUENCE { 742 version INTEGER (1 .. 127), 743 name LDAPDN, 744 authentication AuthenticationChoice } 746 AuthenticationChoice ::= CHOICE { 747 simple [0] OCTET STRING, 748 -- 1 and 2 reserved 749 sasl [3] SaslCredentials, 750 ... } 752 SaslCredentials ::= SEQUENCE { 753 mechanism LDAPString, 754 credentials OCTET STRING OPTIONAL } 756 Fields of the Bind Request are: 758 Lightweight Directory Access Protocol Version 3 760 - version: A version number indicating the version of the protocol 761 to be used in this LDAP association. This document describes 762 version 3 of the protocol. There is no version negotiation. The 763 client sets this field to the version it desires. If the server 764 does not support the specified version, it MUST respond with 765 protocolError in the resultCode field of the BindResponse. 767 - name: The name of the Directory object that the client wishes to 768 bind as. This field may take on a null value (a zero length 769 string) for the purposes of anonymous binds ([AuthMeth] Section 770 5.1) or when using Simple Authentication and Security Layer [SASL] 771 authentication ([AuthMeth] Section 3.3.2). Where the server 772 attempts to locate the named object, it SHALL NOT perform alias 773 dereferencing. 775 - authentication: information used in authentication. This type is 776 extensible as defined in Section 3.7 of [LDAPIANA]. Servers that 777 do not support a choice supplied by a client return 778 authMethodNotSupported in the resultCode field of the 779 BindResponse. 781 Textual passwords (consisting of a character sequence with a known 782 character set and encoding) transferred to the server using the 783 simple AuthenticationChoice SHALL be transferred as [UTF-8] 784 encoded [Unicode]. Prior to transfer, clients SHOULD prepare text 785 passwords by applying the [SASLprep] profile of the [Stringprep] 786 algorithm. Passwords consisting of other data (such as random 787 octets) MUST NOT be altered. The determination of whether a 788 password is textual is a local client matter. 790 Authorization is the decision of which access an operation has to the 791 directory. Among other things, the process of authorization takes as 792 input authentication information obtained during the bind operation 793 and/or other acts of authentication (such as lower layer security 794 services). 796 4.2.1. Processing of the Bind Request 798 Before processing a BindRequest, all uncompleted operations MUST 799 either complete or be abandoned. The server may either wait for the 800 uncompleted operations to complete, or abandon them. The server then 801 proceeds to authenticate the client in either a single-step, or 802 multi-step bind process. Each step requires the server to return a 803 BindResponse to indicate the status of authentication. 805 After sending a BindRequest, clients MUST NOT send further LDAP PDUs 806 until receiving the BindResponse. Similarly, servers SHOULD NOT 807 process or respond to requests received while processing a 808 BindRequest. 810 If the client did not bind before sending a request and receives an 811 operationsError to that request, it may then send a Bind Request. If 812 Lightweight Directory Access Protocol Version 3 814 this also fails or the client chooses not to bind on the existing 815 LDAP exchange, it may close the connection, reopen it and begin again 816 by first sending a PDU with a Bind Request. This will aid in 817 interoperating with servers implementing other versions of LDAP. 819 Clients may send multiple Bind Requests on an LDAP exchange to change 820 the authentication and/or security associations or to complete a 821 multi-stage bind process. Authentication from earlier binds is 822 subsequently ignored. 824 For some SASL authentication mechanisms, it may be necessary for the 825 client to invoke the BindRequest multiple times ([AuthMeth] Section 826 8.2). Clients MUST NOT invoke operations between two Bind Requests 827 made as part of a multi-stage bind. 829 A client may abort a SASL bind negotiation by sending a BindRequest 830 with a different value in the mechanism field of SaslCredentials, or 831 an AuthenticationChoice other than sasl. 833 If the client sends a BindRequest with the sasl mechanism field as an 834 empty string, the server MUST return a BindResponse with 835 authMethodNotSupported as the resultCode. This will allow clients to 836 abort a negotiation if it wishes to try again with the same SASL 837 mechanism. 839 4.2.2. Bind Response 841 The Bind Response is defined as follows. 843 BindResponse ::= [APPLICATION 1] SEQUENCE { 844 COMPONENTS OF LDAPResult, 845 serverSaslCreds [7] OCTET STRING OPTIONAL } 847 BindResponse consists simply of an indication from the server of the 848 status of the client's request for authentication. 850 A successful bind operation is indicated by a BindResponse with a 851 resultCode set to success. Otherwise, an appropriate result code is 852 set in the BindResponse. For bind, the protocolError result code may 853 be used to indicate that the version number supplied by the client is 854 unsupported. 856 If the client receives a BindResponse where the resultCode field is 857 protocolError, it is to assume that the server does not support this 858 version of LDAP. While the client may be able proceed with another 859 version of this protocol (this may or may not require closing and re- 860 establishing the connection), how to proceed with another version of 861 this protocol is beyond the scope of this document. Clients which are 862 unable or unwilling to proceed SHOULD close the connection. 864 The serverSaslCreds field is used as part of a SASL-defined bind 865 mechanism to allow the client to authenticate the server to which it 866 is communicating, or to perform "challenge-response" authentication. 868 Lightweight Directory Access Protocol Version 3 870 If the client bound with the simple choice, or the SASL mechanism 871 does not require the server to return information to the client, then 872 this field SHALL NOT be included in the BindResponse. 874 4.3. Unbind Operation 876 The function of the Unbind Operation is to terminate an LDAP 877 association and close the connection. The Unbind operation is not the 878 antithesis of the Bind operation as the name implies. The naming of 879 these operations is historical. The Unbind operation should be 880 thought of as the "quit" operation. 882 The Unbind Operation is defined as follows: 884 UnbindRequest ::= [APPLICATION 2] NULL 886 The Unbind Operation has no response defined. Upon transmission of 887 the UnbindRequest, each protocol peer is to consider the LDAP 888 association terminated, MUST cease transmission of messages to the 889 other peer, and MUST close the connection. Uncompleted operations are 890 handled as specified in Section 5.1. 892 4.4. Unsolicited Notification 894 An unsolicited notification is an LDAPMessage sent from the server to 895 the client which is not in response to any LDAPMessage received by 896 the server. It is used to signal an extraordinary condition in the 897 server or in the LDAP exchange or connection between the client and 898 the server. The notification is of an advisory nature, and the server 899 will not expect any response to be returned from the client. 901 The unsolicited notification is structured as an LDAPMessage in which 902 the messageID is zero and protocolOp is of the extendedResp form (See 903 Section 4.12). The responseName field of the ExtendedResponse always 904 contains an LDAPOID which is unique for this notification. 906 One unsolicited notification (Notice of Disconnection) is defined in 907 this document. The specification of an unsolicited notification 908 consists of: 910 - the OBJECT IDENTIFIER assigned to the notification (to be 911 specified in the responseName, 913 - the format of the contents (if any) of the responseValue, 915 - the circumstances which will cause the notification to be 916 returned, and 918 - the semantics of the operation. 920 4.4.1. Notice of Disconnection 921 Lightweight Directory Access Protocol Version 3 923 This notification may be used by the server to advise the client that 924 the server is about to close the connection due to an error 925 condition. This notification is intended to assist clients in 926 distinguishing between an error condition and a transient network 927 failure. Note that this notification is not a response to an unbind 928 requested by the client. Uncompleted operations are handled as 929 specified in Section 5.1. 931 The responseName is 1.3.6.1.4.1.1466.20036, the responseValue field 932 is absent, and the resultCode is used to indicate the reason for the 933 disconnection. 935 The following result codes have these meanings when used in this 936 notification: 938 - protocolError: The server has received data from the client in 939 which the LDAPMessage structure could not be parsed. 941 - strongAuthRequired: The server has detected that an established 942 security association between the client and server has 943 unexpectedly failed or been compromised, or that the server now 944 requires the client to authenticate using a strong(er) mechanism. 946 - unavailable: This server will stop accepting new connections and 947 operations on all existing LDAP exchanges, and be unavailable for 948 an extended period of time. The client may make use of an 949 alternative server. 951 Upon transmission of the Notice of Disconnection, the server is to 952 consider the LDAP association terminated, MUST cease transmission of 953 messages to the client, and MUST close the connection. 955 4.5. Search Operation 957 The Search Operation is used to request a server to return, subject 958 to access controls and other restrictions, a set of entries matching 959 a complex search criterion. This can be used to read attributes from 960 a single entry, from entries immediately subordinate to a particular 961 entry, or a whole subtree of entries. 963 4.5.1. Search Request 965 The Search Request is defined as follows: 967 SearchRequest ::= [APPLICATION 3] SEQUENCE { 968 baseObject LDAPDN, 969 scope ENUMERATED { 970 baseObject (0), 971 singleLevel (1), 972 wholeSubtree (2) }, 973 derefAliases ENUMERATED { 974 Lightweight Directory Access Protocol Version 3 976 neverDerefAliases (0), 977 derefInSearching (1), 978 derefFindingBaseObj (2), 979 derefAlways (3) }, 980 sizeLimit INTEGER (0 .. maxInt), 981 timeLimit INTEGER (0 .. maxInt), 982 typesOnly BOOLEAN, 983 filter Filter, 984 attributes AttributeSelection } 986 AttributeSelection ::= SEQUENCE OF selector LDAPString 987 -- The LDAPString is constrained to 988 -- below 990 Filter ::= CHOICE { 991 and [0] SET SIZE (1..MAX) OF filter Filter, 992 or [1] SET SIZE (1..MAX) OF filter Filter, 993 not [2] Filter, 994 equalityMatch [3] AttributeValueAssertion, 995 substrings [4] SubstringFilter, 996 greaterOrEqual [5] AttributeValueAssertion, 997 lessOrEqual [6] AttributeValueAssertion, 998 present [7] AttributeDescription, 999 approxMatch [8] AttributeValueAssertion, 1000 extensibleMatch [9] MatchingRuleAssertion } 1002 SubstringFilter ::= SEQUENCE { 1003 type AttributeDescription, 1004 -- initial and final can occur at most once 1005 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE { 1006 initial [0] AssertionValue, 1007 any [1] AssertionValue, 1008 final [2] AssertionValue } } 1010 MatchingRuleAssertion ::= SEQUENCE { 1011 matchingRule [1] MatchingRuleId OPTIONAL, 1012 type [2] AttributeDescription OPTIONAL, 1013 matchValue [3] AssertionValue, 1014 dnAttributes [4] BOOLEAN DEFAULT FALSE } 1016 Fields of the Search Request are: 1018 - baseObject: The name of the base object entry relative to which 1019 the search is to be performed. 1021 - scope: Specifies the scope of the search to be performed. The 1022 semantics (as described in [X.511]) of the possible values of this 1023 field are: 1025 baseObject: The scope is constrained to the entry named by 1026 baseObject. 1028 singleLevel: The scope is constrained to the immediate 1029 subordinates of the entry named by baseObject. 1031 Lightweight Directory Access Protocol Version 3 1033 wholeSubtree: the scope is constrained to the entry named by 1034 the baseObject, and all its subordinates. 1036 - derefAliases: An indicator as to how alias entries (as defined in 1037 [Models]) are to be handled in searching. The semantics of the 1038 possible values of this field are: 1040 neverDerefAliases: Do not dereference aliases in searching or 1041 in locating the base object of the search. 1043 derefInSearching: While searching, dereference any alias entry 1044 subordinate to the base object which is also in the search 1045 scope. The filter is applied to the dereferenced object(s). If 1046 the search scope is wholeSubtree, the search continues in the 1047 subtree of any dereferenced object. Aliases in that subtree are 1048 also dereferenced. Servers SHOULD eliminate duplicate entries 1049 that arise due to alias dereferencing while searching. 1051 derefFindingBaseObj: Dereference aliases in locating the base 1052 object of the search, but not when searching subordinates of 1053 the base object. 1055 derefAlways: Dereference aliases both in searching and in 1056 locating the base object of the search. 1057 Servers MUST detect looping while dereferencing aliases in order 1058 to prevent denial of service attacks of this nature. 1060 - sizeLimit: A size limit that restricts the maximum number of 1061 entries to be returned as a result of the search. A value of zero 1062 in this field indicates that no client-requested size limit 1063 restrictions are in effect for the search. Servers may also 1064 enforce a maximum number of entries to return. 1066 - timeLimit: A time limit that restricts the maximum time (in 1067 seconds) allowed for a search. A value of zero in this field 1068 indicates that no client-requested time limit restrictions are in 1069 effect for the search. Servers may also enforce a maximum time 1070 limit for the search. 1072 - typesOnly: An indicator as to whether search results are to 1073 contain both attribute descriptions and values, or just attribute 1074 descriptions. Setting this field to TRUE causes only attribute 1075 descriptions (no values) to be returned. Setting this field to 1076 FALSE causes both attribute descriptions and values to be 1077 returned. 1079 - filter: A filter that defines the conditions that must be 1080 fulfilled in order for the search to match a given entry. 1082 The 'and', 'or' and 'not' choices can be used to form combinations 1083 of filters. At least one filter element MUST be present in an 1084 'and' or 'or' choice. The others match against individual 1085 Lightweight Directory Access Protocol Version 3 1087 attribute values of entries in the scope of the search. 1088 (Implementor's note: the 'not' filter is an example of a tagged 1089 choice in an implicitly-tagged module. In BER this is treated as 1090 if the tag was explicit.) 1092 A server MUST evaluate filters according to the three-valued logic 1093 of X.511 (1993) Section 7.8.1. In summary, a filter is evaluated 1094 to either "TRUE", "FALSE" or "Undefined". If the filter evaluates 1095 to TRUE for a particular entry, then the attributes of that entry 1096 are returned as part of the search result (subject to any 1097 applicable access control restrictions). If the filter evaluates 1098 to FALSE or Undefined, then the entry is ignored for the search. 1100 A filter of the "and" choice is TRUE if all the filters in the SET 1101 OF evaluate to TRUE, FALSE if at least one filter is FALSE, and 1102 otherwise Undefined. A filter of the "or" choice is FALSE if all 1103 of the filters in the SET OF evaluate to FALSE, TRUE if at least 1104 one filter is TRUE, and Undefined otherwise. A filter of the 'not' 1105 choice is TRUE if the filter being negated is FALSE, FALSE if it 1106 is TRUE, and Undefined if it is Undefined. 1108 The present match evaluates to TRUE where there is an attribute or 1109 subtype of the specified attribute description present in an 1110 entry, and FALSE otherwise (including a presence test with an 1111 unrecognized attribute description.) 1113 The matching rule for equalityMatch filter items is defined by the 1114 EQUALITY matching rule for the attribute type. 1116 There SHALL be at most one 'initial', and at most one 'final' in 1117 the 'substrings' of a SubstringFilter. If 'initial' is present, it 1118 SHALL be the first element of 'substrings'. If 'final' is present, 1119 it SHALL be the last element of 'substrings'. 1120 The matching rule for AssertionValues in a substrings filter item 1121 is defined by the SUBSTR matching rule for the attribute type. 1122 Note that the AssertionValue in a substrings filter item conforms 1123 to the assertion syntax of the EQUALITY matching rule for the 1124 attribute type rather than the assertion syntax of the SUBSTR 1125 matching rule for the attribute type. Conceptually, the entire 1126 SubstringFilter is converted into an assertion value of the 1127 substrings matching rule prior to applying the rule. 1129 The matching rule for the greaterOrEqual filter item is defined by 1130 the ORDERING and EQUALITY matching rules for the attribute type. 1132 The matching rule for the lessOrEqual filter item is defined by 1133 the ORDERING matching rule for the attribute type. 1135 An approxMatch filter item evaluates to TRUE when there is a value 1136 of the attribute or subtype for which some locally-defined 1137 approximate matching algorithm (e.g. spelling variations, phonetic 1138 match, etc.) returns TRUE. If an item matches for equality, it 1139 also satisfies an approximate match. If approximate matching is 1140 not supported for the attribute, this filter item should be 1141 Lightweight Directory Access Protocol Version 3 1143 treated as an equalityMatch. 1145 An extensibleMatch filter item is evaluated as follows: 1147 If the matchingRule field is absent, the type field MUST be 1148 present, and an equality match is performed for that type. 1150 If the type field is absent and the matchingRule is present, the 1151 matchValue is compared against all attributes in an entry which 1152 support that matchingRule. The matchingRule determines the 1153 syntax for the assertion value. The filter item evaluates to 1154 TRUE if it matches with at least one attribute in the entry, 1155 FALSE if it does not match any attribute in the entry, and 1156 Undefined if the matchingRule is not recognized or the 1157 assertionValue is invalid. 1159 If the type field is present and the matchingRule is present, 1160 the matchValue is compared against entry attributes of the 1161 specified type. In this case, the matchingRule MUST be one 1162 suitable for use with the specified type (see [Syntaxes]), 1163 otherwise the filter item is Undefined. 1165 If the dnAttributes field is set to TRUE, the match is 1166 additionally applied against all the AttributeValueAssertions in 1167 an entry's distinguished name, and evaluates to TRUE if there is 1168 at least one attribute in the distinguished name for which the 1169 filter item evaluates to TRUE. The dnAttributes field is present 1170 to alleviate the need for multiple versions of generic matching 1171 rules (such as word matching), where one applies to entries and 1172 another applies to entries and dn attributes as well. 1174 A filter item evaluates to Undefined when the server would not be 1175 able to determine whether the assertion value matches an entry. If 1176 an attribute description in an equalityMatch, substrings, 1177 greaterOrEqual, lessOrEqual, approxMatch or extensibleMatch filter 1178 is not recognized by the server, a MatchingRuleId in the 1179 extensibleMatch is not recognized by the server, the assertion 1180 value is invalid, or the type of filtering requested is not 1181 implemented, then the filter is Undefined. Thus for example if a 1182 server did not recognize the attribute type shoeSize, a filter of 1183 (shoeSize=*) would evaluate to FALSE, and the filters 1184 (shoeSize=12), (shoeSize>=12) and (shoeSize<=12) would evaluate to 1185 Undefined. 1187 Servers MUST NOT return errors if attribute descriptions or 1188 matching rule ids are not recognized, assertion values are 1189 invalid, or the assertion syntax is not supported. More details of 1190 filter processing are given in Section 7.8 of [X.511]. 1192 - attributes: A selection list of the attributes to be returned from 1193 each entry which matches the search filter. LDAPString values of 1194 this field are constrained to the following Augmented Backus-Naur 1195 Form ([ABNF]): 1197 Lightweight Directory Access Protocol Version 3 1199 attributeSelector = attributedescription / selectorpecial 1201 selectorspecial = noattrs / alluserattrs 1203 noattrs = %x31.2E.31 ; "1.1" 1205 alluserattrs = %x2A ; asterisk ("*") 1207 The production is defined in Section 2.5 of 1208 [Models]. 1210 There are three special cases which may appear in the attributes 1211 selection list: 1213 - an empty list with no attributes, 1215 - a list containing "*" (with zero or more attribute 1216 descriptions), and 1218 - a list containing only "1.1". 1220 An empty list requests the return of all user attributes. 1222 A list containing "*" requests the return of all user attributes 1223 in addition to other listed (operational) attributes. 1225 A list containing only the OID "1.1" indicates that no attributes 1226 are to be returned. If "1.1" is provided with other 1227 attributeSelector values, the "1.1" attributeSelector is ignored. 1228 This OID was chosen because it does not (and can not) correspond 1229 to any attribute in use. 1231 Client implementors should note that even if all user attributes 1232 are requested, some attributes and/or attribute values of the 1233 entry may not be included in search results due to access controls 1234 or other restrictions. Furthermore, servers will not return 1235 operational attributes, such as objectClasses or attributeTypes, 1236 unless they are listed by name. Operational attributes are 1237 described in [Models]. 1239 Attributes are returned at most once in an entry. If an attribute 1240 description is named more than once in the list, the subsequent 1241 names are ignored. If an attribute description in the list is not 1242 recognized, it is ignored by the server. 1244 Note that an X.500 "list"-like operation can be emulated by the 1245 client requesting a one-level LDAP search operation with a filter 1246 checking for the presence of the 'objectClass' attribute, and that an 1247 X.500 "read"-like operation can be emulated by a base object LDAP 1248 search operation with the same filter. A server which provides a 1249 gateway to X.500 is not required to use the Read or List operations, 1250 although it may choose to do so, and if it does, it must provide the 1251 same semantics as the X.500 search operation. 1253 Lightweight Directory Access Protocol Version 3 1255 4.5.2. Search Result 1257 The results of the search operation are returned as zero or more 1258 searchResultEntry messages, zero or more SearchResultReference 1259 messages, followed by a single searchResultDone message. 1261 SearchResultEntry ::= [APPLICATION 4] SEQUENCE { 1262 objectName LDAPDN, 1263 attributes PartialAttributeList } 1265 PartialAttributeList ::= SEQUENCE OF 1266 partialAttribute PartialAttribute 1267 -- Note that the PartialAttributeList may hold zero elements. 1268 -- This may happen when none of the attributes of an entry 1269 -- were requested, or could be returned. 1270 -- Note also that the partialAttribute vals set may hold zero 1271 -- elements. This may happen when typesOnly is requested, access 1272 -- controls prevent the return of values, or other reasons. 1274 SearchResultReference ::= [APPLICATION 19] SEQUENCE 1275 SIZE (1..MAX) OF uri URI 1277 SearchResultDone ::= [APPLICATION 5] LDAPResult 1279 Each SearchResultEntry represents an entry found during the search. 1280 Each SearchResultReference represents an area not yet explored during 1281 the search. The SearchResultEntry and SearchResultReference PDUs may 1282 come in any order. Following all the SearchResultReference and 1283 SearchResultEntry responses, the server returns a SearchResultDone 1284 response, which contains an indication of success, or detailing any 1285 errors that have occurred. 1287 Each entry returned in a SearchResultEntry will contain all 1288 appropriate attributes as specified in the attributes field of the 1289 Search Request. Return of attributes is subject to access control and 1290 other administrative policy. 1292 Some attributes may be constructed by the server and appear in a 1293 SearchResultEntry attribute list, although they are not stored 1294 attributes of an entry. Clients SHOULD NOT assume that all attributes 1295 can be modified, even if permitted by access control. 1297 If the server's schema defines short names [Models] for an attribute 1298 type then the server SHOULD use one of those names in attribute 1299 descriptions for that attribute type (in preference to using the 1300 [Models] format of the attribute type's object 1301 identifier). The server SHOULD NOT use the short name if that name is 1302 known by the server to be ambiguous, or otherwise likely to cause 1303 interoperability problems. 1305 4.5.3. Continuation References in the Search Result 1306 Lightweight Directory Access Protocol Version 3 1308 If the server was able to locate the entry referred to by the 1309 baseObject but was unable to search one or more non-local entries, 1310 the server may return one or more SearchResultReference entries, each 1311 containing a reference to another set of servers for continuing the 1312 operation. A server MUST NOT return any SearchResultReference if it 1313 has not located the baseObject and thus has not searched any entries; 1314 in this case it would return a SearchResultDone containing either a 1315 referral or noSuchObject result code (depending on the server's 1316 knowledge of the entry named in the baseObject). 1318 If a server holds a copy or partial copy of the subordinate naming 1319 context [Section 5 of Models], it may use the search filter to 1320 determine whether or not to return a SearchResultReference response. 1321 Otherwise SearchResultReference responses are always returned when in 1322 scope. 1324 The SearchResultReference is of the same data type as the Referral. 1326 A URI for a server implementing LDAP and accessible via [TCP]/[IP] 1327 (v4 or v6) is written as an LDAP URL according to [LDAPURL]. 1329 In order to complete the search, the client issues a new search 1330 operation for each SearchResultReference that is returned. Note that 1331 the abandon operation described in Section 4.11 applies only to a 1332 particular operation sent on an association between a client and 1333 server. The client must abandon subsequent search operations it 1334 wishes to individually. 1336 Clients that follow search continuation references MUST ensure that 1337 they do not loop between servers. They MUST NOT repeatedly contact 1338 the same server for the same request with the same target entry name, 1339 scope and filter. Some clients use a counter that is incremented each 1340 time search result reference handling occurs for an operation, and 1341 these kinds of clients MUST be able to handle at least ten nested 1342 search result references between the root and a leaf entry. 1344 When an LDAP URL is used, the following instructions are followed: 1346 - The part of the URL MUST be present, with the new target 1347 object name. The client MUST use this name when following the 1348 reference. UTF-8 encoded characters appearing in the string 1349 representation of a DN or search filter may not be legal for URLs 1350 (e.g. spaces) and MUST be escaped using the % method in [URI]. 1352 - Some servers (e.g. participating in distributed indexing) may 1353 provide a different filter in a URL of a SearchResultReference. 1355 - If the part of the URL is present, the client MUST use 1356 this filter in its next request to progress this search, and if it 1357 is not present the client MUST use the same filter as it used for 1358 that search. 1360 - If the originating search scope was singleLevel, the part 1361 of the URL will be "base". 1363 Lightweight Directory Access Protocol Version 3 1365 - it is RECOMMENDED that the part be present to avoid 1366 ambiguity. 1368 - Other aspects of the new search request may be the same as or 1369 different from the search request which generated the 1370 SearchResultReference. 1372 - The name of an unexplored subtree in a SearchResultReference need 1373 not be subordinate to the base object. 1375 Other kinds of URIs may be returned. The syntax and semantics of such 1376 URIs is left to future specifications. Clients may ignore URIs that 1377 they do not support. 1379 4.5.3.1. Examples 1381 For example, suppose the contacted server (hosta) holds the entry 1382 and the entry . It 1383 knows that either LDAP-capable servers (hostb) or (hostc) hold 1384 (one is the master and the other server 1385 a shadow), and that LDAP-capable server (hostd) holds the subtree 1386 . If a wholeSubtree search of 1387 is requested to the contacted server, it may 1388 return the following: 1390 SearchResultEntry for DC=Example,DC=NET 1391 SearchResultEntry for CN=Manager,DC=Example,DC=NET 1392 SearchResultReference { 1393 ldap://hostb/OU=People,DC=Example,DC=NET??sub 1394 ldap://hostc/OU=People,DC=Example,DC=NET??sub } 1395 SearchResultReference { 1396 ldap://hostd/OU=Roles,DC=Example,DC=NET??sub } 1397 SearchResultDone (success) 1399 Client implementors should note that when following a 1400 SearchResultReference, additional SearchResultReference may be 1401 generated. Continuing the example, if the client contacted the server 1402 (hostb) and issued the search for the subtree 1403 , the server might respond as follows: 1405 SearchResultEntry for OU=People,DC=Example,DC=NET 1406 SearchResultReference { 1407 ldap://hoste/OU=Managers,OU=People,DC=Example,DC=NET??sub } 1408 SearchResultReference { 1409 ldap://hostf/OU=Consultants,OU=People,DC=Example,DC=NET??sub } 1410 SearchResultDone (success) 1412 Similarly, if a singleLevel search of is 1413 requested to the contacted server, it may return the following: 1415 SearchResultEntry for CN=Manager,DC=Example,DC=NET 1416 SearchResultReference { 1417 Lightweight Directory Access Protocol Version 3 1419 ldap://hostb/OU=People,DC=Example,DC=NET??base 1420 ldap://hostc/OU=People,DC=Example,DC=NET??base } 1421 SearchResultReference { 1422 ldap://hostd/OU=Roles,DC=Example,DC=NET??base } 1423 SearchResultDone (success) 1425 If the contacted server does not hold the base object for the search, 1426 but has knowledge of its possible location, then it may return a 1427 referral to the client. In this case, if the client requests a 1428 subtree search of to hosta, the server returns a 1429 SearchResultDone containing a referral. 1431 SearchResultDone (referral) { 1432 ldap://hostg/DC=Example,DC=ORG??sub } 1434 4.6. Modify Operation 1436 The Modify Operation allows a client to request that a modification 1437 of an entry be performed on its behalf by a server. The Modify 1438 Request is defined as follows: 1440 ModifyRequest ::= [APPLICATION 6] SEQUENCE { 1441 object LDAPDN, 1442 changes SEQUENCE OF change SEQUENCE { 1443 operation ENUMERATED { 1444 add (0), 1445 delete (1), 1446 replace (2) }, 1447 modification PartialAttribute } } 1449 Fields of the Modify Request are: 1451 - object: The name of the object to be modified. The value of this 1452 field contains the DN of the entry to be modified. The server 1453 SHALL NOT perform any alias dereferencing in determining the 1454 object to be modified. 1456 - changes: A list of modifications to be performed on the entry. The 1457 entire list of modifications MUST be performed in the order they 1458 are listed as a single atomic operation. While individual 1459 modifications may violate certain aspects of the directory schema 1460 (such as the object class definition and DIT content rule), the 1461 resulting entry after the entire list of modifications is 1462 performed MUST conform to the requirements of the directory model 1463 and controlling schema [Models]. 1465 - operation: Used to specify the type of modification being 1466 performed. Each operation type acts on the following 1467 modification. The values of this field have the following 1468 semantics respectively: 1470 add: add values listed to the modification attribute, 1471 creating the attribute if necessary; 1472 Lightweight Directory Access Protocol Version 3 1474 delete: delete values listed from the modification attribute, 1475 removing the entire attribute if no values are listed, or if 1476 all current values of the attribute are listed for deletion; 1478 replace: replace all existing values of the modification 1479 attribute with the new values listed, creating the attribute 1480 if it did not already exist. A replace with no value will 1481 delete the entire attribute if it exists, and is ignored if 1482 the attribute does not exist. 1484 - modification: A PartialAttribute (which may have an empty SET 1485 of vals) used to hold the attribute type or attribute type and 1486 values being modified. 1488 Upon receipt of a Modify Request, the server attempts to perform the 1489 necessary modifications to the DIT and returns the result in a Modify 1490 Response, defined as follows: 1492 ModifyResponse ::= [APPLICATION 7] LDAPResult 1494 The server will return to the client a single Modify Response 1495 indicating either the successful completion of the DIT modification, 1496 or the reason that the modification failed. Due to the requirement 1497 for atomicity in applying the list of modifications in the Modify 1498 Request, the client may expect that no modifications of the DIT have 1499 been performed if the Modify Response received indicates any sort of 1500 error, and that all requested modifications have been performed if 1501 the Modify Response indicates successful completion of the Modify 1502 Operation. If the association changes or the connection fails, 1503 whether the modification occurred or not is indeterminate. 1505 The Modify Operation cannot be used to remove from an entry any of 1506 its distinguished values, i.e. those values which form the entry's 1507 relative distinguished name. An attempt to do so will result in the 1508 server returning the notAllowedOnRDN result code. The Modify DN 1509 Operation described in Section 4.9 is used to rename an entry. 1511 Note that due to the simplifications made in LDAP, there is not a 1512 direct mapping of the changes in an LDAP ModifyRequest onto the 1513 changes of a DAP ModifyEntry operation, and different implementations 1514 of LDAP-DAP gateways may use different means of representing the 1515 change. If successful, the final effect of the operations on the 1516 entry MUST be identical. 1518 4.7. Add Operation 1520 The Add Operation allows a client to request the addition of an entry 1521 into the Directory. The Add Request is defined as follows: 1523 AddRequest ::= [APPLICATION 8] SEQUENCE { 1524 entry LDAPDN, 1525 attributes AttributeList } 1526 Lightweight Directory Access Protocol Version 3 1528 AttributeList ::= SEQUENCE OF attribute Attribute 1530 Fields of the Add Request are: 1532 - entry: the name of the entry to be added. The server SHALL NOT 1533 dereference any aliases in locating the entry to be added. 1535 - attributes: the list of attributes that, along with those from the 1536 RDN, make up the content of the entry being added. Clients MAY or 1537 MAY NOT include the RDN attribute in this list. Clients MUST 1538 include the 'objectClass' attribute, and values of any mandatory 1539 attributes of the listed object classes. Clients MUST NOT supply 1540 NO-USER-MODIFICATION attributes such as the createTimestamp or 1541 creatorsName attributes, since the server maintains these 1542 automatically. 1544 The entry named in the entry field of the AddRequest MUST NOT exist 1545 for the AddRequest to succeed. The immediate superior (parent) of an 1546 object or alias entry to be added MUST exist. For example, if the 1547 client attempted to add , the 1548 entry did not exist, and the entry did 1549 exist, then the server would return the noSuchObject result code with 1550 the matchedDN field containing . 1552 Server implementations SHOULD NOT restrict where entries can be 1553 located in the Directory unless DIT structure rules are in place. 1554 Some servers allow the administrator to restrict the classes of 1555 entries which can be added to the Directory. 1557 Upon receipt of an Add Request, a server will attempt to add the 1558 requested entry. The result of the add attempt will be returned to 1559 the client in the Add Response, defined as follows: 1561 AddResponse ::= [APPLICATION 9] LDAPResult 1563 A response of success indicates that the new entry has been added to 1564 the Directory. 1566 4.8. Delete Operation 1568 The Delete Operation allows a client to request the removal of an 1569 entry from the Directory. The Delete Request is defined as follows: 1571 DelRequest ::= [APPLICATION 10] LDAPDN 1573 The Delete Request consists of the name of the entry to be deleted. 1574 The server SHALL NOT dereference aliases while resolving the name of 1575 the target entry to be removed. 1577 Only leaf entries (those with no subordinate entries) can be deleted 1578 with this operation. 1580 Lightweight Directory Access Protocol Version 3 1582 Upon receipt of a Delete Request, a server will attempt to perform 1583 the entry removal requested and return the result in the Delete 1584 Response defined as follows: 1586 DelResponse ::= [APPLICATION 11] LDAPResult 1588 4.9. Modify DN Operation 1590 The Modify DN Operation allows a client to change the Relative 1591 Distinguished Name (RDN) of an entry in the Directory, and/or to move 1592 a subtree of entries to a new location in the Directory. The Modify 1593 DN Request is defined as follows: 1595 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE { 1596 entry LDAPDN, 1597 newrdn RelativeLDAPDN, 1598 deleteoldrdn BOOLEAN, 1599 newSuperior [0] LDAPDN OPTIONAL } 1601 Fields of the Modify DN Request are: 1603 - entry: the name of the entry to be changed. This entry may or may 1604 not have subordinate entries. 1606 - newrdn: the new RDN of the entry. If the operation moves the entry 1607 to a new superior without changing its RDN, the value of the old 1608 RDN is supplied for this parameter. 1609 Attribute values of the new RDN not matching any attribute value 1610 of the entry are added to the entry and an appropriate error is 1611 returned if this fails. 1613 - deleteoldrdn: a boolean field that controls whether the old RDN 1614 attribute values are to be retained as attributes of the entry, or 1615 deleted from the entry. 1617 - newSuperior: if present, this is the name of an existing object 1618 entry which becomes the immediate superior (parent) of the 1619 existing entry. 1621 The server SHALL NOT dereference any aliases in locating the objects 1622 named in entry or newSuperior. 1624 Upon receipt of a ModifyDNRequest, a server will attempt to perform 1625 the name change and return the result in the Modify DN Response, 1626 defined as follows: 1628 ModifyDNResponse ::= [APPLICATION 13] LDAPResult 1630 For example, if the entry named in the entry field was , the newrdn field was , and the 1632 newSuperior field was absent, then this operation would attempt to 1633 rename the entry to be . If there was 1634 Lightweight Directory Access Protocol Version 3 1636 already an entry with that name, the operation would fail with the 1637 entryAlreadyExists result code. 1639 The object named in newSuperior MUST exist. For example, if the 1640 client attempted to add , the 1641 entry did not exist, and the entry did 1642 exist, then the server would return the noSuchObject result code with 1643 the matchedDN field containing . 1645 If the deleteoldrdn field is TRUE, the attribute values forming the 1646 old RDN but not the new RDN are deleted from the entry. If the 1647 deleteoldrdn field is FALSE, the attribute values forming the old RDN 1648 will be retained as non-distinguished attribute values of the entry. 1649 The server MUST fail the operation and return an error in the result 1650 code if the setting of the deleteoldrdn field would cause a schema 1651 inconsistency in the entry. 1653 Note that X.500 restricts the ModifyDN operation to only affect 1654 entries that are contained within a single server. If the LDAP server 1655 is mapped onto DAP, then this restriction will apply, and the 1656 affectsMultipleDSAs result code will be returned if this error 1657 occurred. In general, clients MUST NOT expect to be able to perform 1658 arbitrary movements of entries and subtrees between servers or 1659 between naming contexts. 1661 4.10. Compare Operation 1663 The Compare Operation allows a client to compare an assertion value 1664 with the values of a particular attribute in a particular entry in 1665 the Directory. The Compare Request is defined as follows: 1667 CompareRequest ::= [APPLICATION 14] SEQUENCE { 1668 entry LDAPDN, 1669 ava AttributeValueAssertion } 1671 Fields of the Compare Request are: 1673 - entry: the name of the entry to be compared. The server SHALL NOT 1674 dereference any aliases in locating the entry to be compared. 1676 - ava: holds the attribute value assertion to be compared. 1678 Upon receipt of a Compare Request, a server will attempt to perform 1679 the requested comparison and return the result in the Compare 1680 Response, defined as follows: 1682 CompareResponse ::= [APPLICATION 15] LDAPResult 1684 The resultCode field is set to compareTrue, compareFalse, or an 1685 appropriate error. compareTrue indicates that the assertion value in 1686 the ava field matches a value of the attribute or subtype according 1687 to the attribute's EQUALITY matching rule. compareFalse indicates 1688 that the assertion value in the ava field and the values of the 1689 Lightweight Directory Access Protocol Version 3 1691 attribute or subtype did not match. Other result codes indicate 1692 either that the result of the comparison was Undefined (Section 1693 4.5.1), or that some error occurred. 1695 Note that some directory systems may establish access controls which 1696 permit the values of certain attributes (such as userPassword) to be 1697 compared but not interrogated by other means. 1699 4.11. Abandon Operation 1701 The function of the Abandon Operation is to allow a client to request 1702 that the server abandon an uncompleted operation. The Abandon Request 1703 is defined as follows: 1705 AbandonRequest ::= [APPLICATION 16] MessageID 1707 The MessageID is that of an operation which was requested earlier in 1708 this LDAP association. The abandon request itself has its own 1709 MessageID. This is distinct from the MessageID of the earlier 1710 operation being abandoned. 1712 There is no response defined in the Abandon operation. Upon receipt 1713 of an AbandonRequest, the server MAY abandon the operation identified 1714 by the MessageID. Since the client cannot tell the difference between 1715 a successfully abandoned operation and an uncompleted operation, the 1716 application of the Abandon operation is limited to uses where the 1717 client does not require an indication of its outcome. 1719 Abandon, Bind, Unbind, and StartTLS operations cannot be abandoned. 1721 In the event that a server receives an Abandon Request on a Search 1722 Operation in the midst of transmitting responses to the search, that 1723 server MUST cease transmitting entry responses to the abandoned 1724 request immediately, and MUST NOT send the SearchResponseDone. Of 1725 course, the server MUST ensure that only properly encoded LDAPMessage 1726 PDUs are transmitted. 1728 The ability to abandon other (particularly update) operations is at 1729 the discretion of the server. 1731 Clients should not send abandon requests for the same operation 1732 multiple times, and MUST also be prepared to receive results from 1733 operations it has abandoned (since these may have been in transit 1734 when the abandon was requested, or are not able to be abandoned). 1736 Servers MUST discard abandon requests for message IDs they do not 1737 recognize, for operations which cannot be abandoned, and for 1738 operations which have already been abandoned. 1740 4.12. Extended Operation 1741 Lightweight Directory Access Protocol Version 3 1743 The extended operation allows additional operations to be defined for 1744 services not already available in the protocol. For example, to add 1745 operations to install transport layer security (see Section 4.14). 1747 The extended operation allows clients to make requests and receive 1748 responses with predefined syntaxes and semantics. These may be 1749 defined in RFCs or be private to particular implementations. 1751 Each extended operation consists of an extended request and an 1752 extended response. 1754 ExtendedRequest ::= [APPLICATION 23] SEQUENCE { 1755 requestName [0] LDAPOID, 1756 requestValue [1] OCTET STRING OPTIONAL } 1758 The requestName is a dotted-decimal representation of the unique 1759 OBJECT IDENTIFIER corresponding to the request. The requestValue is 1760 information in a form defined by that request, encapsulated inside an 1761 OCTET STRING. 1763 The server will respond to this with an LDAPMessage containing an 1764 ExtendedResponse. 1766 ExtendedResponse ::= [APPLICATION 24] SEQUENCE { 1767 COMPONENTS OF LDAPResult, 1768 responseName [10] LDAPOID OPTIONAL, 1769 responseValue [11] OCTET STRING OPTIONAL } 1771 The responseName is typically not required to be present as the 1772 syntax and semantics of the response (including the format of the 1773 responseValue) is implicitly known and associated with the request by 1774 the messageID. 1776 If the extended operation associated with the requestName is not 1777 supported by the server, the server MUST NOT provide a responseName 1778 nor a responseValue and MUST return a resultCode of protocolError. 1780 The requestValue and responseValue fields contain any information 1781 associated with the operation. The format of these fields is defined 1782 by the specification of the extended operation. Implementations MUST 1783 be prepared to handle arbitrary contents of these fields, including 1784 zero bytes. Values that are defined in terms of ASN.1 and BER encoded 1785 according to Section 5.2, also follow the extensibility rules in 1786 Section 4. 1788 Servers list the requestName of Extended Requests they recognize in 1789 the ' supportedExtension ' attribute in the root DSE (Section 5.1 of 1790 [Models]). 1792 Extended operations may be specified in other documents. The 1793 specification of an extended operation consists of: 1795 - the OBJECT IDENTIFIER assigned to the requestName, 1796 Lightweight Directory Access Protocol Version 3 1798 - the OBJECT IDENTIFIER (if any) assigned to the responseName (note 1799 that the same OBJECT IDENTIFIER my be used for both the 1800 requestName and responseName), 1802 - the format of the contents of the requestValue and responseValue 1803 (if any), and 1805 - the semantics of the operation. 1807 4.13. IntermediateResponse Message 1809 While the Search operation provides a mechanism to return multiple 1810 response messages for a single search request, other operations, by 1811 nature, do not provide for multiple response messages. 1813 The IntermediateResponse message provides a general mechanism for 1814 defining single-request/multiple-response operations in LDAP. This 1815 message is intended to be used in conjunction with the extended 1816 operation to define new single-request/multiple-response operations 1817 or in conjunction with a control when extending existing LDAP 1818 operations in a way that requires them to return intermediate 1819 response information. 1821 It is intended that the definitions and descriptions of extended 1822 operations and controls that make use of the IntermediateResponse 1823 message will define the circumstances when an IntermediateResponse 1824 message can be sent by a server and the associated meaning of an 1825 IntermediateResponse message sent in a particular circumstance. 1827 IntermediateResponse ::= [APPLICATION 25] SEQUENCE { 1828 responseName [0] LDAPOID OPTIONAL, 1829 responseValue [1] OCTET STRING OPTIONAL } 1831 IntermediateResponse messages SHALL NOT be returned to the client 1832 unless the client issues a request that specifically solicits their 1833 return. This document defines two forms of solicitation: extended 1834 operation and request control. IntermediateResponse messages are 1835 specified in documents describing the manner in which they are 1836 solicited (i.e. in the extended operation or request control 1837 specification that uses them). These specifications include: 1839 - the OBJECT IDENTIFIER (if any) assigned to the responseName, 1841 - the format of the contents of the responseValue, and 1843 - the semantics associated with the IntermediateResponse message. 1845 Extensions that allow the return of multiple types of 1846 IntermediateResponse messages SHALL identify those types using unique 1847 responseName values (note that one of these may specify no value). 1849 Lightweight Directory Access Protocol Version 3 1851 Sections 4.13.1 and 4.13.2 describe additional requirements on the 1852 inclusion of responseName and responseValue in IntermediateResponse 1853 messages. 1855 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse 1857 A single-request/multiple-response operation may be defined using a 1858 single ExtendedRequest message to solicit zero or more 1859 IntermediateResponse messages of one or more kinds followed by an 1860 ExtendedResponse message. 1862 4.13.2. Usage with LDAP Request Controls 1864 A control's semantics may include the return of zero or more 1865 IntermediateResponse messages prior to returning the final result 1866 code for the operation. One or more kinds of IntermediateResponse 1867 messages may be sent in response to a request control. 1869 All IntermediateResponse messages associated with request controls 1870 SHALL include a responseName. This requirement ensures that the 1871 client can correctly identify the source of IntermediateResponse 1872 messages when: 1874 - two or more controls using IntermediateResponse messages are 1875 included in a request for any LDAP operation or 1877 - one or more controls using IntermediateResponse messages are 1878 included in a request with an LDAP extended operation that uses 1879 IntermediateResponse messages. 1881 4.14. StartTLS Operation 1883 The Start Transport Layer Security (StartTLS) operation provides the 1884 ability to establish a TLS-protected LDAP exchange. The StartTLS 1885 operation is defined using the extended operation mechanism described 1886 in Section 4.12. 1888 4.14.1. StartTLS Request 1890 A client requests TLS establishment by transmitting a StartTLS 1891 request PDU to the server. The StartTLS request is defined in terms 1892 of an ExtendedRequest. The requestName is "1.3.6.1.4.1.1466.20037", 1893 and the requestValue field is always absent. 1895 The client MUST NOT send any PDUs on this LDAP exchange following 1896 this request until it receives a StartTLS extended response and, in 1897 the case of a successful response, completes TLS negotiations. 1899 Lightweight Directory Access Protocol Version 3 1901 4.14.2. StartTLS Response 1903 When a StartTLS request is made, servers supporting the operation 1904 MUST return a StartTLS response PDU to the requestor. The 1905 responseName, if present, is also "1.3.6.1.4.1.1466.20037". The 1906 responseValue is absent. 1908 The server provides a resultCode field to either success or one of 1909 the other values outlined in Section 4.14.2.2. 1911 4.14.2.1. "Success" Response 1913 If the StartTLS Response contains a resultCode of success, this 1914 indicates that the server is willing and able to negotiate TLS. Refer 1915 to Section 4 of [AuthMeth] for details. 1917 4.14.2.2. Response other than "success" 1919 If the ExtendedResponse contains a result code other than success, 1920 this indicates that the server is unwilling or unable to negotiate 1921 TLS. The following result codes have these meanings for this 1922 operation: 1924 - operationsError: operations sequencing incorrect; e.g. TLS is 1925 already established. 1927 - protocolError: TLS is not supported or incorrect PDU structure. 1929 - unavailable: Some major problem with TLS, or the server is 1930 shutting down. 1932 The server MUST return operationsError if the client violates any of 1933 the StartTLS extended operation sequencing requirements described in 1934 Section 4 of [AuthMeth]. 1936 If the server does not support TLS (whether by design or by current 1937 configuration), it MUST return the protocolError resultCode. In this 1938 event, the client may proceed with any LDAP operation, or it may 1939 close the connection. 1941 The server MUST return unavailable if it supports TLS but cannot 1942 install the TLS layer for some reason, e.g. the certificate server 1943 not responding, it cannot contact its TLS implementation, or if the 1944 server is in process of shutting down. The client may retry the 1945 StartTLS operation, or it may proceed with any other LDAP operation, 1946 or it may close the connection. 1948 4.14.3. Removal of the TLS Layer 1949 Lightweight Directory Access Protocol Version 3 1951 Two forms of TLS layer removal -- graceful and abrupt -- are 1952 provided. These do not involve LDAP PDUs, but are preformed at the 1953 underlying layers. 1955 If the connection is closed, uncompleted operations are handled as 1956 specified in Section 5.1. 1958 4.14.3.1. Graceful Removal 1960 Either the client or server MAY remove the TLS layer and leave the 1961 LDAP exchange intact by sending and receiving a TLS closure alert. 1963 The initiating protocol peer sends the TLS closure alert. If it 1964 wishes to leave the LDAP exchange intact, it then MUST cease to send 1965 further PDUs and MUST ignore any received LDAP PDUs until it receives 1966 a TLS closure alert from the other peer. 1968 Once the initiating protocol peer receives a TLS closure alert from 1969 the other peer it MAY send and receive LDAP PDUs. 1971 When a protocol peer receives the initial TLS closure alert, it may 1972 choose to allow the LDAP exchange to remain intact. In this case, it 1973 MUST immediately transmit a TLS closure alert. Following this, it MAY 1974 send and receive LDAP PDUs. 1976 Protocol peers MAY close the connection after sending or receiving a 1977 TLS closure alert. 1979 After the TLS layer has been removed, the server MUST NOT send 1980 responses to any request message received before the TLS closure 1981 alert. Thus, clients wishing to receive responses to messages sent 1982 while the TLS layer is intact MUST wait for those message responses 1983 before sending the TLS closure alert. 1985 4.14.3.2. Abrupt Removal 1987 Either the client or server MAY abruptly remove the TLS layer by 1988 closing the connection. In this circumstance, a server MAY send the 1989 client a Notice of Disconnection before closing the connection. 1991 5. Protocol Encoding, Connection, and Transfer 1993 This protocol is designed to run over connection-oriented, reliable 1994 transports, where the data stream is divided into octets (8-bit 1995 units), with each octet and each bit being significant. 1997 One underlying service, LDAP over TCP, is defined in Section 1998 5.3. This service is generally applicable to applications providing 1999 or consuming X.500-based directory services on the Internet. This 2000 specification was generally written with the TCP mapping in mind. 2002 Lightweight Directory Access Protocol Version 3 2004 Specifications detailing other mappings may encounter various 2005 obstacles. 2007 Implementations of LDAP over TCP MUST implement the mapping as 2008 described in Section 5.3. 2010 This table illustrates the relationship between the different layers 2011 involved in an exchange between two protocol peers: 2013 +---------------+ 2014 | LDAP exchange | 2015 +---------------+ > LDAP PDUs 2016 +---------------+ < data 2017 | SASL layer | 2018 +---------------+ > SASL-protected data 2019 +---------------+ < data 2020 | TLS layer | 2021 Application +---------------+ > TLS-protected data 2022 ------------+---------------+ < data 2023 Transport | connection | 2024 +---------------+ 2026 5.2. Protocol Encoding 2028 The protocol elements of LDAP SHALL be encoded for exchange using the 2029 Basic Encoding Rules [BER] of [ASN.1] with the following 2030 restrictions: 2032 - Only the definite form of length encoding is used. 2034 - OCTET STRING values are encoded in the primitive form only. 2036 - If the value of a BOOLEAN type is true, the encoding of the value 2037 octet is set to hex "FF". 2039 - If a value of a type is its default value, it is absent. Only some 2040 BOOLEAN and INTEGER types have default values in this protocol 2041 definition. 2043 These restrictions are meant to ease the overhead of encoding and 2044 decoding certain elements in BER. 2046 These restrictions do not apply to ASN.1 types encapsulated inside of 2047 OCTET STRING values, such as attribute values, unless otherwise 2048 stated. 2050 5.3. Transmission Control Protocol (TCP) 2052 The encoded LDAPMessage PDUs are mapped directly onto the [TCP] 2053 bytestream using the BER-based encoding described in Section 5.2. It 2054 is recommended that server implementations running over the TCP 2055 provide a protocol listener on the Internet Assigned Numbers 2056 Authority (IANA)-assigned LDAP port, 389 [PortReg]. Servers may 2057 Lightweight Directory Access Protocol Version 3 2059 instead provide a listener on a different port number. Clients MUST 2060 support contacting servers on any valid TCP port. 2062 6. Security Considerations 2064 This version of the protocol provides facilities for simple 2065 authentication using a cleartext password, as well as any [SASL] 2066 mechanism. Installing SASL layers can provide integrity and other 2067 data security services. 2069 It is also permitted that the server can return its credentials to 2070 the client, if it chooses to do so. 2072 Use of cleartext password is strongly discouraged where the 2073 underlying transport service cannot guarantee confidentiality and may 2074 result in disclosure of the password to unauthorized parties. 2076 Servers are encouraged to prevent directory modifications by clients 2077 that have authenticated anonymously [AuthMeth]. 2079 Security considerations for authentication methods, SASL mechanisms, 2080 and TLS are described in [AuthMeth]. 2082 It should be noted that SASL authentication exchanges do not provide 2083 data confidentiality nor integrity protection for the version or name 2084 fields of the bind request nor the resultCode, diagnosticMessage, or 2085 referral fields of the bind response nor of any information contained 2086 in controls attached to bind request or responses. Thus information 2087 contained in these fields SHOULD NOT be relied on unless otherwise 2088 protected (such as by establishing protections at the transport 2089 layer). 2091 Server implementors should plan for the possibility of an identity in 2092 and association being deleted, renamed, or modified, and take 2093 appropriate actions to prevent insecure side effects. Likewise, 2094 server implementors should plan for the possibility of an associated 2095 identity's credentials becoming invalid, or an identity's privileges 2096 being changed. The ways in which these issues are addressed are 2097 application and/or implementation specific. 2099 Implementations which cache attributes and entries obtained via LDAP 2100 MUST ensure that access controls are maintained if that information 2101 is to be provided to multiple clients, since servers may have access 2102 control policies which prevent the return of entries or attributes in 2103 search results except to particular authenticated clients. For 2104 example, caches could serve result information only to the client 2105 whose request caused it to be in the cache. 2107 Servers may return referrals or search result references which 2108 redirect clients to peer servers. It is possible for a rogue 2109 application to inject such referrals into the data stream in an 2110 attempt to redirect a client to a rogue server. Clients are advised 2111 to be aware of this, and possibly reject referrals when 2112 Lightweight Directory Access Protocol Version 3 2114 confidentiality measures are not in place. Clients are advised to 2115 reject referrals from the StartTLS operation. 2117 The matchedDN and diagnosticMessage fields, as well as some 2118 resultCode values (e.g., attributeOrValueExists and 2119 entryAlreadyExists), could disclose the presence the specific data in 2120 the directory which is subject to access and other administrative 2121 controls. Server implementations should restrict access to protected 2122 information equally under both normal and error conditions. 2124 Protocol peers MUST be prepared to handle invalid and arbitrary 2125 length protocol encodings. Invalid protocol encodings include: BER 2126 encoding exceptions, format string and UTF-8 encoding exceptions, 2127 overflow exceptions, integer value exceptions, and binary mode on/off 2128 flag exceptions. The LDAPv3 PROTOS [PROTOS-LDAP] test suite provides 2129 excellent examples of these exceptions and test cases used to 2130 discover flaws. 2132 7. Acknowledgements 2134 This document is based on RFC 2251 by Mark Wahl, Tim Howes, and Steve 2135 Kille. RFC 2251 was a product of the IETF ASID Working Group. 2137 It is also based on RFC 2830 by Jeff Hodges, RL "Bob" Morgan, and 2138 Mark Wahl. RFC 2830 was a product of the IETF LDAPEXT Working Group. 2140 It is also based on RFC 3771 by Roger Harrison, and Kurt Zeilenga. 2141 RFC 3771 was an individual submission to the IETF. 2143 This document is a product of the LDAPBIS Working Group. Significant 2144 contributors of technical review and content include Kurt Zeilenga, 2145 Steven Legg, and Hallvard Furuseth. 2147 8. Normative References 2149 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2150 Specifications: ABNF", RFC 2234, November 1997. 2152 Lightweight Directory Access Protocol Version 3 2154 [ASN.1] ITU-T Recommendation X.680 (07/2002) | ISO/IEC 8824-1:2002 2155 "Information Technology - Abstract Syntax Notation One 2156 (ASN.1): Specification of basic notation" 2158 [AuthMeth] Harrison, R., "LDAP: Authentication Methods and Connection 2159 Level Security Mechanisms", draft-ietf-ldapbis-authmeth- 2160 xx.txt, (a work in progress). 2162 [BER] ITU-T Rec. X.690 (07/2002) | ISO/IEC 8825-1:2002, 2163 "Information technology - ASN.1 encoding rules: 2164 Specification of Basic Encoding Rules (BER), Canonical 2165 Encoding Rules (CER) and Distinguished Encoding Rules 2166 (DER)", 2002. 2168 [IP] Postel, J., "Internet Protocol", STD5 and RFC 791, 2169 September 1981 2171 [ISO10646] Universal Multiple-Octet Coded Character Set (UCS) - 2172 Architecture and Basic Multilingual Plane, ISO/IEC 10646-1 2173 : 1993. 2175 [Keyword] Bradner, S., "Key words for use in RFCs to Indicate 2176 Requirement Levels", RFC 2119, March 1997. 2178 [LDAPDN] Zeilenga, K., "LDAP: String Representation of 2179 Distinguished Names", draft-ietf-ldapbis-dn-xx.txt, (a 2180 work in progress). 2182 [LDAPIANA] Zeilenga, K., "IANA Considerations for LDAP", draft-ietf- 2183 ldapbis-bcp64-xx.txt, (a work in progress). 2185 [LDAPURL] Smith, M., "LDAP: Uniform Resource Locator", draft-ietf- 2186 ldapbis-url-xx.txt, (a work in progress). 2188 [Models] Zeilenga, K., "LDAP: Directory Information Models", draft- 2189 ietf-ldapbis-models-xx.txt (a work in progress). 2191 [Roadmap] Zeilenga, K., "LDAP: Technical Specification Road Map", 2192 draft-ietf-ldapbis-roadmap-xx.txt (a work in progress). 2194 [SASL] Melnikov, A., "Simple Authentication and Security Layer", 2195 draft-ietf-sasl-rfc2222bis-xx.txt (a work in progress). 2197 [SASLPrep] Zeilenga, K., "Stringprep profile for user names and 2198 passwords", draft-ietf-sasl-saslprep-xx.txt, (a work in 2199 progress). 2201 [StringPrep] Hoffman P. and M. Blanchet, "Preparation of 2202 Internationalized Strings ('stringprep')", draft-hoffman- 2203 rfc3454bis-xx.txt, a work in progress. 2205 Lightweight Directory Access Protocol Version 3 2207 [Syntaxes] Legg, S., and K. Dally, "LDAP: Syntaxes and Matching 2208 Rules", draft-ietf-ldapbis-syntaxes-xx.txt, (a work in 2209 progress). 2211 [TCP] Postel, J., "Transmission Control Protocol", STD7 and RFC 2212 793, September 1981 2214 [TLS] Dierks, T. and C. Allen. "The TLS Protocol Version 1.1", 2215 draft-ietf-tls-rfc2246-bis-xx.txt, a work in progress. 2217 [Unicode] The Unicode Consortium, "The Unicode Standard, Version 2218 3.2.0" is defined by "The Unicode Standard, Version 3.0" 2219 (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5), 2220 as amended by the "Unicode Standard Annex #27: Unicode 2221 3.1" (http://www.unicode.org/reports/tr27/) and by the 2222 "Unicode Standard Annex #28: Unicode 3.2" 2223 (http://www.unicode.org/reports/tr28/). 2225 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2226 Resource Identifiers (URI): Generic Syntax", RFC 2396, 2227 August 1998. 2229 [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO 2230 10646", STD63 and RFC3629, November 2003. 2232 [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts, 2233 Models and Service", 1993. 2235 [X.501] ITU-T Rec. X.501, "The Directory: Models", 1993. 2237 [X.511] ITU-T Rec. X.511, "The Directory: Abstract Service 2238 Definition", 1993. 2240 9. Informative References 2242 [Glossary] The Unicode Consortium, "Unicode Glossary", 2243 . 2245 [CharModel] Whistler, K. and M. Davis, "Unicode Technical Report 2246 #17, Character Encoding Model", UTR17, 2247 , August 2248 2000. 2250 [PROTOS-LDAP] University of Oulu, "PROTOS Test-Suite: c06-ldapv3" 2251 2254 [PortReg] IANA, "Port Numbers", 2255 http://www.iana.org/assignments/port-numbers 2257 10. IANA Considerations 2258 Lightweight Directory Access Protocol Version 3 2260 It is requested that the Internet Assigned Numbers Authority (IANA) 2261 update the LDAP result code registry to indicate that this document 2262 provides the definitive technical specification for result codes 0- 2263 36, 48-54, 64-70, 80-90. 2265 It is requested that the IANA update the LDAP Protocol Mechanism 2266 registry to indicate that this document and [AuthMeth] provides the 2267 definitive technical specification for the StartTLS 2268 (1.3.6.1.4.1.1466.20037) extended operation. 2270 It is requested that the IANA update the occurrence of "RFC XXXX" in 2271 Appendix B with this RFC number at publication. 2273 11. Editor's Address 2275 Jim Sermersheim 2276 Novell, Inc. 2277 1800 South Novell Place 2278 Provo, Utah 84606, USA 2279 jimse@novell.com 2280 +1 801 861-3088 2281 Lightweight Directory Access Protocol Version 3 2283 Appendix A - LDAP Result Codes 2285 This normative appendix details additional considerations regarding 2286 LDAP result codes and provides a brief, general description of each 2287 LDAP result code enumerated in Section 4.1.9. 2289 Additional result codes MAY be defined for use with extensions 2290 [LDAPIANA]. Client implementations SHALL treat any result code which 2291 they do not recognize as an unknown error condition. 2293 A.1 Non-Error Result Codes 2295 These result codes (called "non-error" result codes) do not indicate 2296 an error condition: 2297 success (0), 2298 compareFalse (5), 2299 compareTrue (6), 2300 referral (10), and 2301 saslBindInProgress (14). 2303 The success, compareTrue, and compareFalse result codes indicate 2304 successful completion (and, hence, are referred to as "successful" 2305 result codes). 2307 The referral and saslBindInProgress result codes indicate the client 2308 is required to take additional action to complete the operation. 2310 A.2 Result Codes 2312 Existing LDAP result codes are described as follows: 2314 success (0) 2315 Indicates the successful completion of an operation. Note: 2316 this code is not used with the compare operation. See 2317 compareFalse (5) and compareTrue (6). 2319 operationsError (1) 2320 Indicates that the operation is not properly sequenced with 2321 relation to other operations (of same or different type). 2323 For example, this code is returned if the client attempts to 2324 StartTLS [TLS] while there are other uncompleted operations 2325 or if a TLS layer was already installed. 2327 protocolError (2) 2328 Indicates the server received data which is not well-formed. 2330 For bind operation only, this code is also used to indicate 2331 that the server does not support the requested protocol 2332 version. 2334 Lightweight Directory Access Protocol Version 3 2336 For extended operations only, this code indicates that the 2337 server does not support (by design or configuration) the 2338 extended operation associated with the requestName. 2340 For request operations specifying multiple controls, this may 2341 be used to indicate that the server cannot ignore the order 2342 of the controls as specified, or that the combination of the 2343 specified controls is invalid or unspecified. 2345 timeLimitExceeded (3) 2346 Indicates that the time limit specified by the client was 2347 exceeded before the operation could be completed. 2349 sizeLimitExceeded (4) 2350 Indicates that the size limit specified by the client was 2351 exceeded before the operation could be completed. 2353 compareFalse (5) 2354 Indicates that the compare operation has successfully 2355 completed and the assertion has evaluated to FALSE or 2356 Undefined. 2358 compareTrue (6) 2359 Indicates that the compare operation has successfully 2360 completed and the assertion has evaluated to TRUE. 2362 authMethodNotSupported (7) 2363 Indicates that the authentication method or mechanism is not 2364 supported. 2366 strongAuthRequired (8) 2367 Indicates that the server has detected that an established 2368 security association between the client and server has 2369 unexpectedly failed or been compromised, or that the server 2370 now requires the client to authenticate using a strong(er) 2371 mechanism. 2373 referral (10) 2374 Indicates that a referral needs to be chased to complete the 2375 operation (see Section 4.1.10). 2377 adminLimitExceeded (11) 2378 Indicates that an administrative limit has been exceeded. 2380 unavailableCriticalExtension (12) 2381 Indicates a critical control is unrecognized (see Section 2382 4.1.11). 2384 confidentialityRequired (13) 2385 Indicates that data confidentiality protections are required. 2387 saslBindInProgress (14) 2388 Lightweight Directory Access Protocol Version 3 2390 Indicates the server requires the client to send a new bind 2391 request, with the same SASL mechanism, to continue the 2392 authentication process (see Section 4.2). 2394 noSuchAttribute (16) 2395 Indicates that the named entry does not contain the specified 2396 attribute or attribute value. 2398 undefinedAttributeType (17) 2399 Indicates that a request field contains an unrecognized 2400 attribute description. 2402 inappropriateMatching (18) 2403 Indicates that an attempt was made (e.g. in an assertion) to 2404 use a matching rule not defined for the attribute type 2405 concerned. 2407 constraintViolation (19) 2408 Indicates that the client supplied an attribute value which 2409 does not conform to the constraints placed upon it by the 2410 data model. 2412 For example, this code is returned when multiple values are 2413 supplied to an attribute which has a SINGLE-VALUE constraint. 2415 attributeOrValueExists (20) 2416 Indicates that the client supplied an attribute or value to 2417 be added to an entry, but the attribute or value already 2418 exists. 2420 invalidAttributeSyntax (21) 2421 Indicates that a purported attribute value does not conform 2422 to the syntax of the attribute. 2424 noSuchObject (32) 2425 Indicates that the object does not exist in the DIT. 2427 aliasProblem (33) 2428 Indicates that an alias problem has occurred. For example, 2429 the code may used to indicate an alias has been dereferenced 2430 which names no object. 2432 invalidDNSyntax (34) 2433 Indicates that an LDAPDN or RelativeLDAPDN field (e.g. search 2434 base, target entry, ModifyDN newrdn, etc.) of a request does 2435 not conform to the required syntax or contains attribute 2436 values which do not conform to the syntax of the attribute's 2437 type. 2439 aliasDereferencingProblem (36) 2440 Indicates that a problem occurred while dereferencing an 2441 alias. Typically an alias was encountered in a situation 2442 where it was not allowed or where access was denied. 2444 Lightweight Directory Access Protocol Version 3 2446 inappropriateAuthentication (48) 2447 Indicates the server requires the client which had attempted 2448 to bind anonymously or without supplying credentials to 2449 provide some form of credentials. 2451 invalidCredentials (49) 2452 Indicates that the provided credentials (e.g. the user's name 2453 and password) are invalid. 2455 insufficientAccessRights (50) 2456 Indicates that the client does not have sufficient access 2457 rights to perform the operation. 2459 busy (51) 2460 Indicates that the server is too busy to service the 2461 operation. 2463 unavailable (52) 2464 Indicates that the server is shutting down or a subsystem 2465 necessary to complete the operation is offline. 2467 unwillingToPerform (53) 2468 Indicates that the server is unwilling to perform the 2469 operation. 2471 loopDetect (54) 2472 Indicates that the server has detected an internal loop (e.g. 2473 while dereferencing aliases or chaining an operation). 2475 namingViolation (64) 2476 Indicates that the entry's name violates naming restrictions. 2478 objectClassViolation (65) 2479 Indicates that the entry violates object class restrictions. 2481 notAllowedOnNonLeaf (66) 2482 Indicates that the operation is inappropriately acting upon a 2483 non-leaf entry. 2485 notAllowedOnRDN (67) 2486 Indicates that the operation is inappropriately attempting to 2487 remove a value which forms the entry's relative distinguished 2488 name. 2490 entryAlreadyExists (68) 2491 Indicates that the request cannot be fulfilled (added, moved, 2492 or renamed) as the target entry already exists. 2494 objectClassModsProhibited (69) 2495 Indicates that an attempt to modify the object class(es) of 2496 an entry's 'objectClass' attribute is prohibited. 2498 For example, this code is returned when a client attempts to 2499 modify the structural object class of an entry. 2501 Lightweight Directory Access Protocol Version 3 2503 affectsMultipleDSAs (71) 2504 Indicates that the operation cannot be performed as it would 2505 affect multiple servers (DSAs). 2507 other (80) 2508 Indicates the server has encountered an internal error. 2510 Lightweight Directory Access Protocol Version 3 2512 Appendix B - Complete ASN.1 Definition 2514 This appendix is normative. 2516 Lightweight-Directory-Access-Protocol-V3 2517 -- Copyright (C) The Internet Society (2004). This version of 2518 -- this ASN.1 module is part of RFC XXXX; see the RFC itself 2519 -- for full legal notices. 2520 DEFINITIONS 2521 IMPLICIT TAGS 2522 EXTENSIBILITY IMPLIED ::= 2524 BEGIN 2526 LDAPMessage ::= SEQUENCE { 2527 messageID MessageID, 2528 protocolOp CHOICE { 2529 bindRequest BindRequest, 2530 bindResponse BindResponse, 2531 unbindRequest UnbindRequest, 2532 searchRequest SearchRequest, 2533 searchResEntry SearchResultEntry, 2534 searchResDone SearchResultDone, 2535 searchResRef SearchResultReference, 2536 modifyRequest ModifyRequest, 2537 modifyResponse ModifyResponse, 2538 addRequest AddRequest, 2539 addResponse AddResponse, 2540 delRequest DelRequest, 2541 delResponse DelResponse, 2542 modDNRequest ModifyDNRequest, 2543 modDNResponse ModifyDNResponse, 2544 compareRequest CompareRequest, 2545 compareResponse CompareResponse, 2546 abandonRequest AbandonRequest, 2547 extendedReq ExtendedRequest, 2548 extendedResp ExtendedResponse, 2549 ..., 2550 intermediateResponse IntermediateResponse }, 2551 controls [0] Controls OPTIONAL } 2553 MessageID ::= INTEGER (0 .. maxInt) 2555 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) -- 2557 LDAPString ::= OCTET STRING -- UTF-8 encoded, 2558 -- [ISO10646] characters 2560 LDAPOID ::= OCTET STRING -- Constrained to [Models] 2562 LDAPDN ::= LDAPString -- Constrained to 2563 -- [LDAPDN] 2565 RelativeLDAPDN ::= LDAPString -- Constrained to 2566 Lightweight Directory Access Protocol Version 3 2568 -- [LDAPDN] 2570 AttributeDescription ::= LDAPString 2571 -- Constrained to 2572 -- [Models] 2574 AttributeValue ::= OCTET STRING 2576 AttributeValueAssertion ::= SEQUENCE { 2577 attributeDesc AttributeDescription, 2578 assertionValue AssertionValue } 2580 AssertionValue ::= OCTET STRING 2582 PartialAttribute ::= SEQUENCE { 2583 type AttributeDescription, 2584 vals SET OF value AttributeValue } 2586 Attribute ::= PartialAttribute(WITH COMPONENTS { 2587 ..., 2588 vals (SIZE(1..MAX))}) 2590 MatchingRuleId ::= LDAPString 2592 LDAPResult ::= SEQUENCE { 2593 resultCode ENUMERATED { 2594 success (0), 2595 operationsError (1), 2596 protocolError (2), 2597 timeLimitExceeded (3), 2598 sizeLimitExceeded (4), 2599 compareFalse (5), 2600 compareTrue (6), 2601 authMethodNotSupported (7), 2602 strongAuthRequired (8), 2603 -- 9 reserved -- 2604 referral (10), 2605 adminLimitExceeded (11), 2606 unavailableCriticalExtension (12), 2607 confidentialityRequired (13), 2608 saslBindInProgress (14), 2609 noSuchAttribute (16), 2610 undefinedAttributeType (17), 2611 inappropriateMatching (18), 2612 constraintViolation (19), 2613 attributeOrValueExists (20), 2614 invalidAttributeSyntax (21), 2615 -- 22-31 unused -- 2616 noSuchObject (32), 2617 aliasProblem (33), 2618 invalidDNSyntax (34), 2619 -- 35 reserved for undefined isLeaf -- 2620 aliasDereferencingProblem (36), 2621 -- 37-47 unused -- 2623 Lightweight Directory Access Protocol Version 3 2625 inappropriateAuthentication (48), 2626 invalidCredentials (49), 2627 insufficientAccessRights (50), 2628 busy (51), 2629 unavailable (52), 2630 unwillingToPerform (53), 2631 loopDetect (54), 2632 -- 55-63 unused -- 2633 namingViolation (64), 2634 objectClassViolation (65), 2635 notAllowedOnNonLeaf (66), 2636 notAllowedOnRDN (67), 2637 entryAlreadyExists (68), 2638 objectClassModsProhibited (69), 2639 -- 70 reserved for CLDAP -- 2640 affectsMultipleDSAs (71), 2641 -- 72-79 unused -- 2642 other (80), 2643 ... }, 2644 matchedDN LDAPDN, 2645 diagnosticMessage LDAPString, 2646 referral [3] Referral OPTIONAL } 2648 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI 2650 URI ::= LDAPString -- limited to characters permitted in 2651 -- URIs 2653 Controls ::= SEQUENCE OF control Control 2655 Control ::= SEQUENCE { 2656 controlType LDAPOID, 2657 criticality BOOLEAN DEFAULT FALSE, 2658 controlValue OCTET STRING OPTIONAL } 2660 BindRequest ::= [APPLICATION 0] SEQUENCE { 2661 version INTEGER (1 .. 127), 2662 name LDAPDN, 2663 authentication AuthenticationChoice } 2665 AuthenticationChoice ::= CHOICE { 2666 simple [0] OCTET STRING, 2667 -- 1 and 2 reserved 2668 sasl [3] SaslCredentials, 2669 ... } 2671 SaslCredentials ::= SEQUENCE { 2672 mechanism LDAPString, 2673 credentials OCTET STRING OPTIONAL } 2675 BindResponse ::= [APPLICATION 1] SEQUENCE { 2676 COMPONENTS OF LDAPResult, 2677 serverSaslCreds [7] OCTET STRING OPTIONAL } 2678 Lightweight Directory Access Protocol Version 3 2680 UnbindRequest ::= [APPLICATION 2] NULL 2682 SearchRequest ::= [APPLICATION 3] SEQUENCE { 2683 baseObject LDAPDN, 2684 scope ENUMERATED { 2685 baseObject (0), 2686 singleLevel (1), 2687 wholeSubtree (2) }, 2688 derefAliases ENUMERATED { 2689 neverDerefAliases (0), 2690 derefInSearching (1), 2691 derefFindingBaseObj (2), 2692 derefAlways (3) }, 2693 sizeLimit INTEGER (0 .. maxInt), 2694 timeLimit INTEGER (0 .. maxInt), 2695 typesOnly BOOLEAN, 2696 filter Filter, 2697 attributes AttributeSelection } 2699 AttributeSelection ::= SEQUENCE OF selector LDAPString 2700 -- The LDAPString is constrained to 2701 -- in Section 4.5.1 2703 Filter ::= CHOICE { 2704 and [0] SET SIZE (1..MAX) OF filter Filter, 2705 or [1] SET SIZE (1..MAX) OF filter Filter, 2706 not [2] Filter, 2707 equalityMatch [3] AttributeValueAssertion, 2708 substrings [4] SubstringFilter, 2709 greaterOrEqual [5] AttributeValueAssertion, 2710 lessOrEqual [6] AttributeValueAssertion, 2711 present [7] AttributeDescription, 2712 approxMatch [8] AttributeValueAssertion, 2713 extensibleMatch [9] MatchingRuleAssertion } 2715 SubstringFilter ::= SEQUENCE { 2716 type AttributeDescription, 2717 -- at least one must be present, 2718 -- initial and final can occur at most once 2719 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE { 2720 initial [0] AssertionValue, 2721 any [1] AssertionValue, 2722 final [2] AssertionValue } } 2724 MatchingRuleAssertion ::= SEQUENCE { 2725 matchingRule [1] MatchingRuleId OPTIONAL, 2726 type [2] AttributeDescription OPTIONAL, 2727 matchValue [3] AssertionValue, 2728 dnAttributes [4] BOOLEAN DEFAULT FALSE } 2730 SearchResultEntry ::= [APPLICATION 4] SEQUENCE { 2731 objectName LDAPDN, 2732 attributes PartialAttributeList } 2733 Lightweight Directory Access Protocol Version 3 2735 PartialAttributeList ::= SEQUENCE OF 2736 partialAttribute PartialAttribute 2738 SearchResultReference ::= [APPLICATION 19] SEQUENCE 2739 SIZE (1..MAX) OF uri URI 2741 SearchResultDone ::= [APPLICATION 5] LDAPResult 2743 ModifyRequest ::= [APPLICATION 6] SEQUENCE { 2744 object LDAPDN, 2745 changes SEQUENCE OF change SEQUENCE { 2746 operation ENUMERATED { 2747 add (0), 2748 delete (1), 2749 replace (2) }, 2750 modification PartialAttribute } } 2752 ModifyResponse ::= [APPLICATION 7] LDAPResult 2754 AddRequest ::= [APPLICATION 8] SEQUENCE { 2755 entry LDAPDN, 2756 attributes AttributeList } 2758 AttributeList ::= SEQUENCE OF attribute Attribute 2760 AddResponse ::= [APPLICATION 9] LDAPResult 2762 DelRequest ::= [APPLICATION 10] LDAPDN 2764 DelResponse ::= [APPLICATION 11] LDAPResult 2766 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE { 2767 entry LDAPDN, 2768 newrdn RelativeLDAPDN, 2769 deleteoldrdn BOOLEAN, 2770 newSuperior [0] LDAPDN OPTIONAL } 2772 ModifyDNResponse ::= [APPLICATION 13] LDAPResult 2774 CompareRequest ::= [APPLICATION 14] SEQUENCE { 2775 entry LDAPDN, 2776 ava AttributeValueAssertion } 2778 CompareResponse ::= [APPLICATION 15] LDAPResult 2780 AbandonRequest ::= [APPLICATION 16] MessageID 2782 ExtendedRequest ::= [APPLICATION 23] SEQUENCE { 2783 requestName [0] LDAPOID, 2784 requestValue [1] OCTET STRING OPTIONAL } 2786 ExtendedResponse ::= [APPLICATION 24] SEQUENCE { 2787 COMPONENTS OF LDAPResult, 2788 responseName [10] LDAPOID OPTIONAL, 2789 Lightweight Directory Access Protocol Version 3 2791 responseValue [11] OCTET STRING OPTIONAL } 2793 IntermediateResponse ::= [APPLICATION 25] SEQUENCE { 2794 responseName [0] LDAPOID OPTIONAL, 2795 responseValue [1] OCTET STRING OPTIONAL } 2797 END 2798 Lightweight Directory Access Protocol Version 3 2800 Appendix C - Changes 2802 This appendix is non-normative. 2804 This appendix summarizes substantive changes made to RFC 2251 and RFC 2805 2830. 2807 C.1 Changes made to RFC 2251: 2809 This section summarizes the substantive changes made to Sections 1, 2810 2, 3.1, and 4 through the remainder of RFC 2251. Readers should 2811 consult [Models] and [AuthMeth] for summaries of changes to other 2812 sections. 2814 C.1.1 Section 1 2816 - Removed IESG note. Post publication of RFC 2251, mandatory LDAP 2817 authentication mechanisms have been standardized which are 2818 sufficient to remove this note. See [AuthMeth] for authentication 2819 mechanisms. 2821 C.1.2 Section 3.1 and others 2823 - Removed notes giving history between LDAP v1, v2 and v3. Instead, 2824 added sufficient language so that this document can stand on its 2825 own. 2827 C.1.3 Section 4 2829 - Clarified where the extensibility features of ASN.1 apply to the 2830 protocol. This change also affected various ASN.1 types. 2831 - Removed the requirement that servers which implement version 3 or 2832 later MUST provide the 'supportedLDAPVersion' attribute. This 2833 statement provided no interoperability advantages. 2835 C.1.4 Section 4.1.1 2837 - There was a mandatory requirement for the server to return a 2838 Notice of Disconnection and drop the connection when a PDU is 2839 malformed in a certain way. This has been clarified such that the 2840 server SHOULD return the Notice of Disconnection, and MUST drop 2841 the connection. 2843 C.1.5 Section 4.1.1.1 2845 - Clarified that the messageID of requests MUST be non-zero. 2847 Lightweight Directory Access Protocol Version 3 2849 - Clarified when it is and isn't appropriate to return an already 2850 used message id. RFC 2251 accidentally imposed synchronous server 2851 behavior in its wording of this. 2853 C.1.6 Section 4.1.2 2855 - Stated that LDAPOID is constrained to from [Models]. 2857 C.1.7 Section 4.1.5.1 2859 - Removed the Binary Option from the specification. There are 2860 numerous interoperability problems associated with this method of 2861 alternate attribute type encoding. Work to specify a suitable 2862 replacement is ongoing. 2864 C.1.8 Section 4.1.6 2866 - Removed references to the "binary" encoding as it has been removed 2867 from the specification. 2869 C.1.9 Section 4.1.7 2871 - Removed references to the "binary" encoding as it has been removed 2872 from the specification. 2874 C.1.10 Section 4.1.8 2876 - Combined the definitions of PartialAttribute and Attribute here, 2877 and defined Attribute in terms of PartialAttribute. 2879 C.1.11 Section 4.1.10 2881 - Renamed "errorMessage" to "diagnosticMessage" as it is allowed to 2882 be sent for non-error results. 2883 - Moved some language into Appendix A, and refer the reader there. 2884 - Allowed matchedDN to be present for other result codes than those 2885 listed in RFC 2251. 2887 C.1.12 Section 4.1.11 2889 - Defined referrals in terms of URIs rather than URLs. 2890 - Removed the requirement that all referral URIs MUST be equally 2891 capable of progressing the operation. The statement was ambiguous 2892 and provided no instructions on how to carry it out. 2893 - Added the requirement that clients MUST NOT loop between servers. 2894 - Clarified the instructions for using LDAPURLs in referrals, and in 2895 doing so added a recommendation that the scope part be present. 2897 Lightweight Directory Access Protocol Version 3 2899 C.1.13 Section 4.1.12 2901 - Specified how control values defined in terms of ASN.1 are to be 2902 encoded. 2903 - Noted that the criticality field is only applied to request 2904 messages (except unbindRequest), and must be ignored when present 2905 on response messages and unbindRequest. 2906 - Added language regarding combinations of controls and the ordering 2907 of controls on a message. 2908 - Specified that when the semantics of the combination of controls 2909 is undefined or unknown, it results in a protocolError. 2910 - Changed "The server MUST be prepared" to "Implementations MUST be 2911 prepared" in the eighth paragraph to reflect that both client and 2912 server implementations must be able to handle this (as both parse 2913 controls). 2915 C.1.14 Section 4.2 2917 - Mandated that servers return protocolError when the version is not 2918 supported. 2919 - Clarified behavior when the simple authentication is used, the 2920 name is empty and the password is non-empty. 2921 - Required servers to not dereference aliases for bind. This was 2922 added for consistency with other operations and to help ensure 2923 data consistency. 2924 - Required that textual passwords be transferred as UTF-8 encoded 2925 Unicode, and added recommendations on string preparation. This was 2926 to help ensure interoperability of passwords being sent from 2927 different clients. 2929 C.1.15 Section 4.2.1 2931 - This section was largely reorganized for readability and language 2932 was added to clarify the authentication state of failed and 2933 abandoned bind operations. 2934 - Removed: "If a SASL transfer encryption or integrity mechanism has 2935 been negotiated, that mechanism does not support the changing of 2936 credentials from one identity to another, then the client MUST 2937 instead establish a new connection." 2938 Each SASL negotiation is, generally, independent of other SASL 2939 negotiations. If there were dependencies between multiple 2940 negotiations of a particular mechanism, the mechanism technical 2941 specification should detail how applications are to deal with 2942 them. LDAP should not require any special handling. And if an LDAP 2943 client had used such a mechanism, it would have the option of 2944 using another mechanism. 2945 - Dropped MUST imperative in paragraph 3 to align with [Keywords]. 2946 - Mandated that clients not send non-bind operations while a bind is 2947 in progress, and suggested that servers not process them if they 2948 Lightweight Directory Access Protocol Version 3 2950 are received. This is needed to ensure proper sequencing of the 2951 bind in relationship to other operations. 2953 C.1.16 Section 4.2.3 2955 - Moved most error-related text to Appendix A, and added text 2956 regarding certain errors used in conjunction with the bind 2957 operation. 2958 - Prohibited the server from specifying serverSaslCreds when not 2959 appropriate. 2961 C.1.17 Section 4.3 2963 - Required both peers to cease transmission and close the LDAP 2964 exchange for the unbind operation. 2966 C.1.18 Section 4.4 2968 - Added instructions for future specifications of Unsolicited 2969 Notifications. 2971 C.1.19 Section 4.5.1 2973 - SearchRequest attributes is now defined as an AttributeSelection 2974 type rather than AttributeDescriptionList, and an ABNF is 2975 provided. 2976 - SearchRequest attributes may contain duplicate attribute 2977 descriptions. This was previously prohibited. Now servers are 2978 instructed to ignore subsequent names when they are duplicated. 2979 This was relaxed in order to allow different short names and also 2980 OIDs to be requested for an attribute. 2981 - The Filter choices 'and' and 'or', and the SubstringFilter 2982 substrings types are now defined with a lower bound of 1. 2983 - The SubstringFilter substrings 'initial, 'any', and 'final' types 2984 are now AssertionValue rather than LDAPString. Also, added 2985 imperatives stating that 'initial' (if present) must be listed 2986 first, and 'final' (if present) must be listed last. 2987 - Clarified the semantics of the derefAliases choices. 2988 - Added instructions for equalityMatch, substrings, greaterOrEqual, 2989 lessOrEqual, and approxMatch. 2991 C.1.20 Section 4.5.2 2993 - Recommended that servers not use attribute short names when it 2994 knows they are ambiguous or may cause interoperability problems. 2995 - Removed all mention of ExtendedResponse due to lack of 2996 implementation. 2998 Lightweight Directory Access Protocol Version 3 3000 C.1.21 Section 4.5.3 3002 - Made changes similar to those made to Section 4.1.11. 3004 C.1.22 Section 4.5.3.1 3006 - Fixed examples to adhere to changes made to Section 4.5.3. 3008 C.1.23 Section 4.6 3010 - Removed restriction that required an EQUALITY matching rule in 3011 order to perform value delete modifications. It is sufficiently 3012 documented that in absence of an equality matching rule, octet 3013 equality is used. 3014 - Replaced AttributeTypeAndValues with Attribute as they are 3015 equivalent. 3016 - Clarified what type of modification changes might temporarily 3017 violate schema. 3019 C.1.24 Section 4.7 3021 - Aligned Add operation with X.511 in that the attributes of the RDN 3022 are used in conjunction with the listed attributes to create the 3023 entry. Previously, Add required that the distinguished values be 3024 present in the listed attributes. 3026 C.1.25 Section 4.9 3028 - Required servers to not dereference aliases for modify DN. This 3029 was added for consistency with other operations and to help ensure 3030 data consistency. 3031 - Allow modify DN to fail when moving between naming contexts. 3032 - Specified what happens when the attributes of the newrdn are no 3033 present on the entry. 3035 C.1.26 Section 4.10 3037 - Clarified that compareFalse means that the compare took place and 3038 the result is false. There was confusion which lead people to 3039 believe that an Undefined match resulted in compareFalse. 3040 - Required servers to not dereference aliases for compare. This was 3041 added for consistency with other operations and to help ensure 3042 data consistency. 3044 C.1.27 Section 4.11 3046 - Explained that since abandon returns no response, clients should 3047 not use it if they need to know the outcome. 3049 Lightweight Directory Access Protocol Version 3 3051 - Specified that Abandon and Unbind cannot be abandoned. 3053 C.1.28 Section 4.12 3055 - Specified how values of extended operations defined in terms of 3056 ASN.1 are to be encoded. 3057 - Added instructions on what extended operation specifications 3058 consist of. 3059 - Added a recommendation that servers advertise supported extended 3060 operations. 3062 C.1.29 Section 5.2 3064 - Moved referral-specific instructions into referral-related 3065 sections. 3067 C.1.30 Section 7 3069 - Reworded notes regarding SASL not protecting certain aspects of 3070 the LDAP bind PDU. 3071 - Noted that Servers are encouraged to prevent directory 3072 modifications by clients that have authenticated anonymously 3073 [AuthMeth]. 3074 - Added a note regarding the scenario where an identity is changed 3075 (deleted, privileges or credentials modified, etc.). 3076 - Warned against following referrals that may have been injected in 3077 the data stream. 3078 - Noted that servers should protect information equally, whether in 3079 an error condition or not, and mentioned specifically; matchedDN, 3080 diagnosticMessage, and resultCodes. 3081 - Added a note regarding malformed and long encodings. 3083 C.1.31 Appendix A 3085 - Added "EXTESIBILITY IMPLIED" to ASN.1 definition. 3086 - Removed AttributeType. It is not used. 3088 C.2 Changes made to RFC 2830: 3090 This section summarizes the substantive changes made to Sections of 3091 RFC 2830. Readers should consult [AuthMeth] for summaries of changes 3092 to other sections. 3094 C.2.1 Section 2.3 3096 - Removed wording indicating that referrals can be returned from 3097 StartTLS 3098 Lightweight Directory Access Protocol Version 3 3100 - Removed requirement that only a narrow set of result codes can be 3101 returned. Some result codes are required in certain scenarios, but 3102 any other may be returned if appropriate. 3104 C.2.1 Section 4.13.3.1 3106 - Reworded most of this section and added the requirement that after 3107 the TLS connection has been closed, the server MUST NOT send 3108 responses to any request message received before the TLS closure. 3110 C.3 Changes made to RFC 3771: 3112 - In general, all technical language was transferred in whole. 3113 Supporting and background language seen as redundant due to its 3114 presence in this document was omitted. 3116 Lightweight Directory Access Protocol Version 3 3118 Intellectual Property Statement 3120 The IETF takes no position regarding the validity or scope of any 3121 Intellectual Property Rights or other rights that might be claimed to 3122 pertain to the implementation or use of the technology described in 3123 this document or the extent to which any license under such rights 3124 might or might not be available; nor does it represent that it has 3125 made any independent effort to identify any such rights. Information 3126 on the IETF's procedures with respect to rights in IETF Documents can 3127 be found in BCP 78 and BCP 79. 3129 Copies of IPR disclosures made to the IETF Secretariat and any 3130 assurances of licenses to be made available, or the result of an 3131 attempt made to obtain a general license or permission for the use of 3132 such proprietary rights by implementers or users of this 3133 specification can be obtained from the IETF on-line IPR repository at 3134 http://www.ietf.org/ipr. 3136 The IETF invites any interested party to bring to its attention any 3137 copyrights, patents or patent applications, or other proprietary 3138 rights that may cover technology that may be required to implement 3139 this standard. Please address the information to the IETF at ietf- 3140 ipr@ietf.org." 3142 Copyright Statement 3144 This document is subject to the rights, licenses and restrictions 3145 contained in BCP 78, and except as set forth therein, the authors 3146 retain all their rights. 3148 Disclaimer of Validity 3150 This document and the information contained herein are provided on an 3151 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 3152 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 3153 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 3154 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 3155 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 3156 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.