idnits 2.17.1 draft-ietf-ldapbis-protocol-29.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 3193. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 3170. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 3183. ** Found boilerplate matching RFC 3978, Section 5.4, paragraph 1 (on line 3199), which is fine, but *also* found old RFC 2026, Section 10.4C, paragraph 1 text on line 41. ** 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. 2 IPR Disclosure Acknowledgement -- 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 document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories -- however, there's a paragraph with a matching beginning. Boilerplate error? 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(s) in this list. 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 (Feb 2005) is 7009 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 2833 -- Looks like a reference, but probably isn't: '3' on line 2765 == Missing Reference: 'APPLICATION 0' is mentioned on line 2697, but not defined == Missing Reference: 'SASLprep' is mentioned on line 788, but not defined == Missing Reference: 'Stringprep' is mentioned on line 788, but not defined == Missing Reference: 'APPLICATION 1' is mentioned on line 2712, but not defined -- Looks like a reference, but probably isn't: '7' on line 2749 == Missing Reference: 'APPLICATION 2' is mentioned on line 2717, but not defined == Missing Reference: 'APPLICATION 3' is mentioned on line 2719, but not defined -- Looks like a reference, but probably isn't: '1' on line 2834 -- Looks like a reference, but probably isn't: '2' on line 2764 -- Looks like a reference, but probably isn't: '4' on line 2766 -- Looks like a reference, but probably isn't: '5' on line 2747 -- Looks like a reference, but probably isn't: '6' on line 2748 -- Looks like a reference, but probably isn't: '8' on line 2750 -- Looks like a reference, but probably isn't: '9' on line 2751 == Missing Reference: 'APPLICATION 4' is mentioned on line 2768, but not defined == Missing Reference: 'APPLICATION 19' is mentioned on line 2776, but not defined == Missing Reference: 'APPLICATION 5' is mentioned on line 2779, but not defined == Missing Reference: 'APPLICATION 6' is mentioned on line 2781, but not defined == Missing Reference: 'APPLICATION 7' is mentioned on line 2791, but not defined == Missing Reference: 'APPLICATION 8' is mentioned on line 2793, but not defined == Missing Reference: 'APPLICATION 9' is mentioned on line 2799, but not defined == Missing Reference: 'APPLICATION 10' is mentioned on line 2801, but not defined == Missing Reference: 'APPLICATION 11' is mentioned on line 2803, but not defined == Missing Reference: 'APPLICATION 12' is mentioned on line 2805, but not defined == Missing Reference: 'APPLICATION 13' is mentioned on line 2811, but not defined == Missing Reference: 'APPLICATION 14' is mentioned on line 2813, but not defined == Missing Reference: 'APPLICATION 15' is mentioned on line 2817, but not defined == Missing Reference: 'APPLICATION 16' is mentioned on line 2819, but not defined == Missing Reference: 'APPLICATION 23' is mentioned on line 2821, but not defined == Missing Reference: 'APPLICATION 24' is mentioned on line 2825, but not defined -- Looks like a reference, but probably isn't: '10' on line 2829 -- Looks like a reference, but probably isn't: '11' on line 2830 == Missing Reference: 'APPLICATION 25' is mentioned on line 2832, but not defined == Missing Reference: 'Keywords' is mentioned on line 2980, but not defined == Unused Reference: 'IP' is defined on line 2196, but no explicit reference was found in the text == Unused Reference: 'SASLPrep' is defined on line 2226, but no explicit reference was found in the text == Unused Reference: 'StringPrep' is defined on line 2230, 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: 12 errors (**), 0 flaws (~~), 33 warnings (==), 46 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-29.txt Feb 2005 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 other 19 groups may also distribute working documents as Internet-Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress". 26 The list of current Internet-Drafts can be accessed at 27 . 29 The list of Internet-Draft Shadow Directories can be accessed at 30 . 32 This Internet-Draft will expire in February 2005. 34 Technical discussion of this document will take place on the IETF 35 LDAP Revision Working Group (LDAPbis) mailing list . Please send editorial comments directly to the 37 editor . 39 Copyright Notice 41 Copyright (C) The Internet Society 2004. All Rights Reserved. 43 Abstract 45 This document describes the protocol elements, along with their 46 semantics and encodings, of the Lightweight Directory Access Protocol 47 (LDAP). LDAP provides access to distributed directory services that 48 act in accordance with X.500 data and service models. These protocol 49 elements are based on those described in the X.500 Directory Access 50 Protocol (DAP). 52 Lightweight Directory Access Protocol Version 3 54 Table of Contents 56 1. Introduction....................................................3 57 1.1. Relationship to Other LDAP Specifications.....................3 58 2. Conventions.....................................................3 59 3. Protocol Model..................................................4 60 3.1 Operation and LDAP Message Layer Relationship..................4 61 4. Elements of Protocol............................................5 62 4.1. Common Elements...............................................5 63 4.1.1. Message Envelope............................................5 64 4.1.2. String Types................................................7 65 4.1.3. Distinguished Name and Relative Distinguished Name..........7 66 4.1.4. Attribute Descriptions......................................8 67 4.1.5. Attribute Value.............................................8 68 4.1.6. Attribute Value Assertion...................................8 69 4.1.7. Attribute and PartialAttribute..............................9 70 4.1.8. Matching Rule Identifier....................................9 71 4.1.9. Result Message..............................................9 72 4.1.10. Referral..................................................11 73 4.1.11. Controls..................................................12 74 4.2. Bind Operation...............................................14 75 4.3. Unbind Operation.............................................17 76 4.4. Unsolicited Notification.....................................17 77 4.6. Modify Operation.............................................28 78 4.7. Add Operation................................................29 79 4.8. Delete Operation.............................................30 80 4.9. Modify DN Operation..........................................31 81 4.10. Compare Operation...........................................32 82 4.11. Abandon Operation...........................................33 83 4.12. Extended Operation..........................................34 84 4.13. IntermediateResponse Message................................35 85 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse......36 86 4.13.2. Usage with LDAP Request Controls..........................36 87 4.14. StartTLS Operation..........................................36 88 5. Protocol Encoding, Connection, and Transfer....................38 89 5.1. Protocol Encoding............................................38 90 5.2. Transmission Control Protocol (TCP)..........................39 91 5.3. Termination of the LDAP session..............................39 92 6. Security Considerations........................................39 93 7. Acknowledgements...............................................41 94 8. Normative References...........................................41 95 9. Informative References.........................................43 96 10. IANA Considerations...........................................43 97 11. Editor's Address..............................................43 98 Appendix A - LDAP Result Codes....................................45 99 A.1 Non-Error Result Codes........................................45 100 A.2 Result Codes..................................................45 101 Appendix B - Complete ASN.1 Definition............................50 102 Appendix C - Changes..............................................56 103 C.1 Changes made to RFC 2251:.....................................56 104 C.2 Changes made to RFC 2830:.....................................61 105 C.3 Changes made to RFC 3771:.....................................62 106 Lightweight Directory Access Protocol Version 3 108 1. Introduction 110 The Directory is "a collection of open systems cooperating to provide 111 directory services" [X.500]. A directory user, which may be a human 112 or other entity, accesses the Directory through a client (or 113 Directory User Agent (DUA)). The client, on behalf of the directory 114 user, interacts with one or more servers (or Directory System Agents 115 (DSA)). Clients interact with servers using a directory access 116 protocol. 118 This document details the protocol elements of the Lightweight 119 Directory Access Protocol (LDAP), along with their semantics. 120 Following the description of protocol elements, it describes the way 121 in which the protocol elements are encoded and transferred. 123 1.1. Relationship to Other LDAP Specifications 125 This document is an integral part of the LDAP Technical Specification 126 [Roadmap] which obsoletes the previously defined LDAP technical 127 specification, RFC 3377, in its entirety. 129 This document obsoletes all of RFC 2251 except the following: 130 Sections 3.2, 3.4, 4.1.3 (last paragraph), 4.1.4, 4.1.5, 4.1.5.1, 131 4.1.9 (last paragraph), 5.1, 6.1, and 6.2 (last paragraph) are 132 obsoleted by [Models]. 133 Section 3.3 is obsoleted by [Roadmap]. 134 Sections 4.2.1 (portions), and 4.2.2 are obsoleted by [AuthMeth]. 136 Appendix C.1 summarizes substantive changes to the remaining 137 sections. 139 This document obsoletes RFC 2830, Sections 2 and 4 in entirety. The 140 remainder of RFC 2830 is obsoleted by [AuthMeth]. Appendix C.2 141 summarizes substantive changes to the remaining sections. 143 This document also obsoletes RFC 3771 in entirety. 145 2. Conventions 147 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 148 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are 149 to be interpreted as described in [Keyword]. 151 Character names in this document use the notation for code points and 152 names from the Unicode Standard [Unicode]. For example, the letter 153 "a" may be represented as either or . 155 Note: a glossary of terms used in Unicode can be found in [Glossary]. 156 Information on the Unicode character encoding model can be found in 157 [CharModel]. 159 Lightweight Directory Access Protocol Version 3 161 The term "transport connection" refers to the underlying transport 162 services used to carry the protocol exchange, as well as associations 163 established by these services. 165 The term "TLS layer" refers to TLS services used in providing 166 security services, as well as associations established by these 167 services. 169 The term "SASL layer" refers to SASL services used in providing 170 security services, as well as associations established by these 171 services. 173 The term "LDAP message layer" refers to the LDAP Message (PDU) 174 services used in providing directory services, as well as 175 associations established by these services. 177 The term "LDAP session" refers to combined services (transport 178 connection, TLS layer, SASL layer, LDAP message layer) and their 179 associations. 181 See the table in Section 5 for an illustration of these four terms. 183 3. Protocol Model 185 The general model adopted by this protocol is one of clients 186 performing protocol operations against servers. In this model, a 187 client transmits a protocol request describing the operation to be 188 performed to a server. The server is then responsible for performing 189 the necessary operation(s) in the Directory. Upon completion of an 190 operation, the server typically returns a response containing 191 appropriate data to the requesting client. 193 Protocol operations are generally independent of one another. Each 194 operation is processed as an atomic action, leaving the directory in 195 a consistent state. 197 Although servers are required to return responses whenever such 198 responses are defined in the protocol, there is no requirement for 199 synchronous behavior on the part of either clients or servers. 200 Requests and responses for multiple operations generally may be 201 exchanged between a client and server in any order. If required, 202 synchronous behavior may be controlled by client applications. 204 The core protocol operations defined in this document can be mapped 205 to a subset of the X.500 (1993) Directory Abstract Service [X.511]. 206 However there is not a one-to-one mapping between LDAP operations and 207 X.500 Directory Access Protocol (DAP) operations. Server 208 implementations acting as a gateway to X.500 directories may need to 209 make multiple DAP requests to service a single LDAP request. 211 3.1 Operation and LDAP Message Layer Relationship 212 Lightweight Directory Access Protocol Version 3 214 Protocol operations are exchanged at the LDAP message layer. When the 215 transport connection is closed, any uncompleted operations at the 216 LDAP message layer, when possible, are abandoned, and when not 217 possible, are completed without transmission of the response. Also, 218 when the transport connection is closed, the client MUST NOT assume 219 that any uncompleted update operations have succeeded or failed. 221 4. Elements of Protocol 223 The protocol is described using Abstract Syntax Notation One 224 ([ASN.1]), and is transferred using a subset of ASN.1 Basic Encoding 225 Rules ([BER]). Section 5 specifies how the protocol elements are 226 encoded and transferred. 228 In order to support future extensions to this protocol, extensibility 229 is implied where it is allowed per ASN.1 (i.e. sequence, set, choice, 230 and enumerated types are extensible). In addition, ellipses (...) 231 have been supplied in ASN.1 types that are explicitly extensible as 232 discussed in [LDAPIANA]. Because of the implied extensibility, 233 clients and servers MUST (unless otherwise specified) ignore trailing 234 SEQUENCE components whose tags they do not recognize. 236 Changes to the protocol other than through the extension mechanisms 237 described here require a different version number. A client indicates 238 the version it is using as part of the BindRequest, described in 239 Section 4.2. If a client has not sent a Bind, the server MUST assume 240 the client is using version 3 or later. 242 Clients may attempt to determine the protocol versions a server 243 supports by reading the 'supportedLDAPVersion' attribute from the 244 root DSE (DSA-Specific Entry) [Models]. 246 4.1. Common Elements 248 This section describes the LDAPMessage envelope Protocol Data Unit 249 (PDU) format, as well as data type definitions, which are used in the 250 protocol operations. 252 4.1.1. Message Envelope 254 For the purposes of protocol exchanges, all protocol operations are 255 encapsulated in a common envelope, the LDAPMessage, which is defined 256 as follows: 258 LDAPMessage ::= SEQUENCE { 259 messageID MessageID, 260 protocolOp CHOICE { 261 bindRequest BindRequest, 262 bindResponse BindResponse, 263 unbindRequest UnbindRequest, 264 searchRequest SearchRequest, 266 Lightweight Directory Access Protocol Version 3 268 searchResEntry SearchResultEntry, 269 searchResDone SearchResultDone, 270 searchResRef SearchResultReference, 271 modifyRequest ModifyRequest, 272 modifyResponse ModifyResponse, 273 addRequest AddRequest, 274 addResponse AddResponse, 275 delRequest DelRequest, 276 delResponse DelResponse, 277 modDNRequest ModifyDNRequest, 278 modDNResponse ModifyDNResponse, 279 compareRequest CompareRequest, 280 compareResponse CompareResponse, 281 abandonRequest AbandonRequest, 282 extendedReq ExtendedRequest, 283 extendedResp ExtendedResponse, 284 ..., 285 intermediateResponse IntermediateResponse }, 286 controls [0] Controls OPTIONAL } 288 MessageID ::= INTEGER (0 .. maxInt) 290 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) -- 292 The ASN.1 type Controls is defined in Section 4.1.11. 294 The function of the LDAPMessage is to provide an envelope containing 295 common fields required in all protocol exchanges. At this time the 296 only common fields are the messageID and the controls. 298 If the server receives a PDU from the client in which the LDAPMessage 299 SEQUENCE tag cannot be recognized, the messageID cannot be parsed, 300 the tag of the protocolOp is not recognized as a request, or the 301 encoding structures or lengths of data fields are found to be 302 incorrect, then the server SHOULD return the Notice of Disconnection 303 described in Section 4.4.1, with the resultCode set to protocolError, 304 and MUST immediately terminate the LDAP session as described in 305 Section 5.3. 307 In other cases where the client or server cannot parse a PDU, it 308 SHOULD abruptly terminate the LDAP session (Section 5.3) where 309 further communication (including providing notice) would be 310 pernicious. Otherwise, server implementations MUST return an 311 appropriate response to the request, with the resultCode set to 312 protocolError. 314 4.1.1.1. Message ID 316 All LDAPMessage envelopes encapsulating responses contain the 317 messageID value of the corresponding request LDAPMessage. 319 The message ID of a request MUST have a non-zero value different from 320 the messageID of any other request in progress in the same LDAP 321 Lightweight Directory Access Protocol Version 3 323 session. The zero value is reserved for the unsolicited notification 324 message. 326 Typical clients increment a counter for each request. 328 A client MUST NOT send a request with the same message ID as an 329 earlier request in the same LDAP session unless it can be determined 330 that the server is no longer servicing the earlier request (e.g. 331 after the final response is received, or a subsequent Bind 332 completes). Otherwise the behavior is undefined. For this purpose, 333 note that Abandon and successfully abandoned operations do not send 334 responses. 336 4.1.2. String Types 338 The LDAPString is a notational convenience to indicate that, although 339 strings of LDAPString type encode as ASN.1 OCTET STRING types, the 340 [ISO10646] character set (a superset of [Unicode]) is used, encoded 341 following the [UTF-8] algorithm. Note that Unicode characters U+0000 342 through U+007F are the same as ASCII 0 through 127, respectively, and 343 have the same single octet UTF-8 encoding. Other Unicode characters 344 have a multiple octet UTF-8 encoding. 346 LDAPString ::= OCTET STRING -- UTF-8 encoded, 347 -- [ISO10646] characters 349 The LDAPOID is a notational convenience to indicate that the 350 permitted value of this string is a (UTF-8 encoded) dotted-decimal 351 representation of an OBJECT IDENTIFIER. Although an LDAPOID is 352 encoded as an OCTET STRING, values are limited to the definition of 353 given in Section 1.4 of [Models]. 355 LDAPOID ::= OCTET STRING -- Constrained to [Models] 357 For example, 359 1.3.6.1.4.1.1466.1.2.3 361 4.1.3. Distinguished Name and Relative Distinguished Name 363 An LDAPDN is defined to be the representation of a Distinguished Name 364 (DN) after encoding according to the specification in [LDAPDN]. 366 LDAPDN ::= LDAPString 367 -- Constrained to [LDAPDN] 369 A RelativeLDAPDN is defined to be the representation of a Relative 370 Distinguished Name (RDN) after encoding according to the 371 specification in [LDAPDN]. 373 RelativeLDAPDN ::= LDAPString 374 -- Constrained to [LDAPDN] 376 Lightweight Directory Access Protocol Version 3 378 4.1.4. Attribute Descriptions 380 The definition and encoding rules for attribute descriptions are 381 defined in Section 2.5 of [Models]. Briefly, an attribute description 382 is an attribute type and zero or more options. 384 AttributeDescription ::= LDAPString 385 -- Constrained to 386 -- [Models] 388 4.1.5. Attribute Value 390 A field of type AttributeValue is an OCTET STRING containing an 391 encoded attribute value. The attribute value is encoded according to 392 the LDAP-specific encoding definition of its corresponding syntax. 393 The LDAP-specific encoding definitions for different syntaxes and 394 attribute types may be found in other documents and in particular 395 [Syntaxes]. 397 AttributeValue ::= OCTET STRING 399 Note that there is no defined limit on the size of this encoding; 400 thus protocol values may include multi-megabyte attribute values 401 (e.g. photographs). 403 Attribute values may be defined which have arbitrary and non- 404 printable syntax. Implementations MUST NOT display nor attempt to 405 decode an attribute value if its syntax is not known. The 406 implementation may attempt to discover the subschema of the source 407 entry, and retrieve the descriptions of 'attributeTypes' from it 408 [Models]. 410 Clients MUST only send attribute values in a request that are valid 411 according to the syntax defined for the attributes. 413 4.1.6. Attribute Value Assertion 415 The AttributeValueAssertion (AVA) type definition is similar to the 416 one in the X.500 Directory standards. It contains an attribute 417 description and a matching rule ([Models] Section 4.1.3) assertion 418 value suitable for that type. Elements of this type are typically 419 used to assert that the value in assertionValue matches a value of an 420 attribute. 422 AttributeValueAssertion ::= SEQUENCE { 423 attributeDesc AttributeDescription, 424 assertionValue AssertionValue } 426 AssertionValue ::= OCTET STRING 427 Lightweight Directory Access Protocol Version 3 429 The syntax of the AssertionValue depends on the context of the LDAP 430 operation being performed. For example, the syntax of the EQUALITY 431 matching rule for an attribute is used when performing a Compare 432 operation. Often this is the same syntax used for values of the 433 attribute type, but in some cases the assertion syntax differs from 434 the value syntax. See objectIdentiferFirstComponentMatch in 435 [Syntaxes] for an example. 437 4.1.7. Attribute and PartialAttribute 439 Attributes and partial attributes consist of an attribute description 440 and attribute values. A PartialAttribute allows zero values, while 441 Attribute requires at least one value. 443 PartialAttribute ::= SEQUENCE { 444 type AttributeDescription, 445 vals SET OF value AttributeValue } 447 Attribute ::= PartialAttribute(WITH COMPONENTS { 448 ..., 449 vals (SIZE(1..MAX))}) 451 No two of the attribute values may be equivalent as described by 452 Section 2.3 of [Models]. The set of attribute values is unordered. 453 Implementations MUST NOT rely upon the ordering being repeatable. 455 4.1.8. Matching Rule Identifier 457 Matching rules are defined in Section 4.1.3 of [Models]. A matching 458 rule is identified in the protocol by the printable representation of 459 either its , or one of its short name descriptors 460 [Models], e.g. 'caseIgnoreMatch' or '2.5.13.2'. 462 MatchingRuleId ::= LDAPString 464 4.1.9. Result Message 466 The LDAPResult is the construct used in this protocol to return 467 success or failure indications from servers to clients. To various 468 requests, servers will return responses containing the elements found 469 in LDAPResult to indicate the final status of the protocol operation 470 request. 472 LDAPResult ::= SEQUENCE { 473 resultCode ENUMERATED { 474 success (0), 475 operationsError (1), 476 protocolError (2), 477 timeLimitExceeded (3), 478 sizeLimitExceeded (4), 479 compareFalse (5), 481 Lightweight Directory Access Protocol Version 3 483 compareTrue (6), 484 authMethodNotSupported (7), 485 strongerAuthRequired (8), 486 -- 9 reserved -- 487 referral (10), 488 adminLimitExceeded (11), 489 unavailableCriticalExtension (12), 490 confidentialityRequired (13), 491 saslBindInProgress (14), 492 noSuchAttribute (16), 493 undefinedAttributeType (17), 494 inappropriateMatching (18), 495 constraintViolation (19), 496 attributeOrValueExists (20), 497 invalidAttributeSyntax (21), 498 -- 22-31 unused -- 499 noSuchObject (32), 500 aliasProblem (33), 501 invalidDNSyntax (34), 502 -- 35 reserved for undefined isLeaf -- 503 aliasDereferencingProblem (36), 504 -- 37-47 unused -- 505 inappropriateAuthentication (48), 506 invalidCredentials (49), 507 insufficientAccessRights (50), 508 busy (51), 509 unavailable (52), 510 unwillingToPerform (53), 511 loopDetect (54), 512 -- 55-63 unused -- 513 namingViolation (64), 514 objectClassViolation (65), 515 notAllowedOnNonLeaf (66), 516 notAllowedOnRDN (67), 517 entryAlreadyExists (68), 518 objectClassModsProhibited (69), 519 -- 70 reserved for CLDAP -- 520 affectsMultipleDSAs (71), 521 -- 72-79 unused -- 522 other (80), 523 ... }, 524 matchedDN LDAPDN, 525 diagnosticMessage LDAPString, 526 referral [3] Referral OPTIONAL } 528 The resultCode enumeration is extensible as defined in Section 3.6 of 529 [LDAPIANA]. The meanings of the listed result codes are given in 530 Appendix A. If a server detects multiple errors for an operation, 531 only one result code is returned. The server should return the result 532 code that best indicates the nature of the error encountered. 534 The diagnosticMessage field of this construct may, at the server's 535 option, be used to return a string containing a textual, human- 536 readable (terminal control and page formatting characters should be 537 Lightweight Directory Access Protocol Version 3 539 avoided) diagnostic message. As this diagnostic message is not 540 standardized, implementations MUST NOT rely on the values returned. 541 Diagnostic messages typically supplement the resultCode with 542 additional information. If the server chooses not to return a textual 543 diagnostic, the diagnosticMessage field MUST be empty. 545 For certain result codes (typically, but not restricted to 546 noSuchObject, aliasProblem, invalidDNSyntax and 547 aliasDereferencingProblem), the matchedDN field is set (subject to 548 access controls) to the name of the last entry (object or alias) used 549 in finding the target (or base) object. This will be a truncated form 550 of the provided name or, if an alias was dereferenced while 551 attempting to locate the entry, of the resulting name. Otherwise the 552 matchedDN field is empty. 554 4.1.10. Referral 556 The referral result code indicates that the contacted server cannot 557 or will not perform the operation and that one or more other servers 558 may be able to. Reasons for this include: 560 - The target entry of the request is not held locally, but the 561 server has knowledge of its possible existence elsewhere. 563 - The operation is restricted on this server -- perhaps due to a 564 read-only copy of an entry to be modified. 566 The referral field is present in an LDAPResult if the resultCode is 567 set to referral, and absent with all other result codes. It contains 568 one or more references to one or more servers or services that may be 569 accessed via LDAP or other protocols. Referrals can be returned in 570 response to any operation request (except Unbind and Abandon which do 571 not have responses). At least one URI MUST be present in the 572 Referral. 574 During a Search operation, after the baseObject is located, and 575 entries are being evaluated, the referral is not returned. Instead, 576 continuation references, described in Section 4.5.3, are returned 577 when other servers would need to be contacted to complete the 578 operation. 580 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI 582 URI ::= LDAPString -- limited to characters permitted in 583 -- URIs 585 If the client wishes to progress the operation, it contacts one of 586 the supported services found in the referral. If multiple URIs are 587 present, the client assumes that any supported URI may be used to 588 progress the operation. 590 Clients that follow referrals MUST ensure that they do not loop 591 between servers. They MUST NOT repeatedly contact the same server for 592 Lightweight Directory Access Protocol Version 3 594 the same request with the same parameters. Some clients use a counter 595 that is incremented each time referral handling occurs for an 596 operation, and these kinds of clients MUST be able to handle at least 597 ten nested referrals while progressing the operation. 599 A URI for a server implementing LDAP and accessible via [TCP]/[IP] 600 (v4 or v6) is written as an LDAP URL according to [LDAPURL]. 602 Referral values which are LDAP URLs follow these rules: 604 - If an alias was dereferenced, the part of the LDAP URL MUST 605 be present, with the new target object name. 607 - It is RECOMMENDED that the part be present to avoid 608 ambiguity. 610 - If the part is present, the client uses this name in its next 611 request to progress the operation, and if it is not present the 612 client uses 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 uses 619 this filter in its next request to progress this Search, and if it 620 is not present the client uses the same filter as it used for that 621 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 UTF-8 encoded characters appearing in the string representation of a 637 DN, search filter, or other fields of the referral value may not be 638 legal for URIs (e.g. spaces) and MUST be escaped using the % method 639 in [URI]. 641 4.1.11. Controls 643 Controls provide a mechanism whereby the semantics and arguments of 644 existing LDAP operations may be extended. One or more controls may be 645 attached to a single LDAP message. A control only affects the 646 semantics of the message it is attached to. 648 Lightweight Directory Access Protocol Version 3 650 Controls sent by clients are termed 'request controls' and those sent 651 by servers are termed 'response controls'. 653 Controls ::= SEQUENCE OF control Control 655 Control ::= SEQUENCE { 656 controlType LDAPOID, 657 criticality BOOLEAN DEFAULT FALSE, 658 controlValue OCTET STRING OPTIONAL } 660 The controlType field is the dotted-decimal representation of an 661 OBJECT IDENTIFIER which uniquely identifies the control. This 662 provides unambiguous naming of controls. Often, response control(s) 663 solicited by a request control share controlType values with the 664 request control. 666 The criticality field only has meaning in controls attached to 667 request messages (except UnbindRequest). For controls attached to 668 response messages and the UnbindRequest, the criticality field SHOULD 669 be FALSE, and MUST be ignored by the receiving protocol peer. A value 670 of TRUE indicates that it is unacceptable to perform the operation 671 without applying the semantics of the control. Specifically, the 672 criticality field is applied as follows: 674 - Regardless of the value of the criticality field, if the server 675 recognizes the control type and it is appropriate for the 676 operation, the server is to make use of the control when 677 performing the operation. 679 - If the server does not recognize the control type or it is not 680 appropriate for the operation, and the criticality field is TRUE, 681 the server MUST NOT perform the operation, and for operations that 682 have a response message, MUST return with the resultCode set to 683 unavailableCriticalExtension. 685 - If the server does not recognize the control type or it is not 686 appropriate for the operation, and the criticality field is FALSE, 687 the server MUST ignore the control. 689 The controlValue may contain information associated with the 690 controlType. Its format is defined by the specification of the 691 control. Implementations MUST be prepared to handle arbitrary 692 contents of the controlValue octet string, including zero bytes. It 693 is absent only if there is no value information which is associated 694 with a control of its type. When a controlValue is defined in terms 695 of ASN.1, and BER encoded according to Section 5.1, it also follows 696 the extensibility rules in Section 4. 698 Servers list the controlType of request controls they recognize in 699 the 'supportedControl' attribute in the root DSE (Section 5.1 of 700 [Models]). 702 Lightweight Directory Access Protocol Version 3 704 Controls SHOULD NOT be combined unless the semantics of the 705 combination has been specified. The semantics of control 706 combinations, if specified, are generally found in the control 707 specification most recently published. When a combination of controls 708 is encountered whose semantics are invalid, not specified (or not 709 known), the message is considered to be not well-formed, thus the 710 operation fails with protocolError. Additionally, unless order- 711 dependent semantics are given in a specification, the order of a 712 combination of controls in the SEQUENCE is ignored. Where the order 713 is to be ignored but cannot be ignored by the server, the message is 714 considered not well-formed and the operation fails with 715 protocolError. 717 This document does not specify any controls. Controls may be 718 specified in other documents. Documents detailing control extensions 719 are to provide for each control: 721 - the OBJECT IDENTIFIER assigned to the control, 723 - direction as to what value the sender should provide for the 724 criticality field (note: the semantics of the criticality field 725 are defined above should not be altered by the control's 726 specification), 728 - whether the controlValue field is present, and if so, the format 729 of its contents, 731 - the semantics of the control, and 733 - optionally, semantics regarding the combination of the control 734 with other controls. 736 4.2. Bind Operation 738 The function of the Bind operation is to allow authentication 739 information to be exchanged between the client and server. The Bind 740 operation should be thought of as the "authenticate" operation. 741 Operational, authentication, and security-related semantics of this 742 operation are given in [AuthMeth]. 744 The Bind request is defined as follows: 746 BindRequest ::= [APPLICATION 0] SEQUENCE { 747 version INTEGER (1 .. 127), 748 name LDAPDN, 749 authentication AuthenticationChoice } 751 AuthenticationChoice ::= CHOICE { 752 simple [0] OCTET STRING, 753 -- 1 and 2 reserved 754 sasl [3] SaslCredentials, 755 ... } 756 Lightweight Directory Access Protocol Version 3 758 SaslCredentials ::= SEQUENCE { 759 mechanism LDAPString, 760 credentials OCTET STRING OPTIONAL } 762 Fields of the BindRequest are: 764 - version: A version number indicating the version of the protocol 765 to be used at the LDAP message layer. This document describes 766 version 3 of the protocol. There is no version negotiation. The 767 client sets this field to the version it desires. If the server 768 does not support the specified version, it MUST respond with a 769 BindResponse where the resultCode is set to protocolError. 771 - name: If not empty, the name of the Directory object that the 772 client wishes to bind as. This field may take on a null value (a 773 zero length string) for the purposes of anonymous binds 774 ([AuthMeth] Section 5.1) or when using Simple Authentication and 775 Security Layer [SASL] authentication ([AuthMeth] Section 3.3.2). 776 Where the server attempts to locate the named object, it SHALL NOT 777 perform alias dereferencing. 779 - authentication: information used in authentication. This type is 780 extensible as defined in Section 3.7 of [LDAPIANA]. Servers that 781 do not support a choice supplied by a client return a BindResponse 782 with the resultCode set to authMethodNotSupported. 784 Textual passwords (consisting of a character sequence with a known 785 character set and encoding) transferred to the server using the 786 simple AuthenticationChoice SHALL be transferred as [UTF-8] 787 encoded [Unicode]. Prior to transfer, clients SHOULD prepare text 788 passwords by applying the [SASLprep] profile of the [Stringprep] 789 algorithm. Passwords consisting of other data (such as random 790 octets) MUST NOT be altered. The determination of whether a 791 password is textual is a local client matter. 793 4.2.1. Processing of the Bind Request 795 Before processing a BindRequest, all uncompleted operations MUST 796 either complete or be abandoned. The server may either wait for the 797 uncompleted operations to complete, or abandon them. The server then 798 proceeds to authenticate the client in either a single-step, or 799 multi-step Bind process. Each step requires the server to return a 800 BindResponse to indicate the status of authentication. 802 After sending a BindRequest, clients MUST NOT send further LDAP PDUs 803 until receiving the BindResponse. Similarly, servers SHOULD NOT 804 process or respond to requests received while processing a 805 BindRequest. 807 If the client did not bind before sending a request and receives an 808 operationsError to that request, it may then send a BindRequest. If 809 this also fails or the client chooses not to bind on the existing 810 LDAP session, it may terminate the LDAP session, re-establish it and 811 Lightweight Directory Access Protocol Version 3 813 begin again by first sending a PDU with a BindRequest. This will aid 814 in interoperating with servers implementing other versions of LDAP. 816 Clients may send multiple Bind requests to change the authentication 817 and/or security associations or to complete a multi-stage Bind 818 process. Authentication from earlier binds is subsequently ignored. 820 For some SASL authentication mechanisms, it may be necessary for the 821 client to invoke the BindRequest multiple times ([AuthMeth] Section 822 8.2). Clients MUST NOT invoke operations between two Bind requests 823 made as part of a multi-stage Bind. 825 A client may abort a SASL bind negotiation by sending a BindRequest 826 with a different value in the mechanism field of SaslCredentials, or 827 an AuthenticationChoice other than sasl. 829 If the client sends a BindRequest with the sasl mechanism field as an 830 empty string, the server MUST return a BindResponse with the 831 resultCode set to authMethodNotSupported. This will allow clients to 832 abort a negotiation if it wishes to try again with the same SASL 833 mechanism. 835 4.2.2. Bind Response 837 The Bind response is defined as follows. 839 BindResponse ::= [APPLICATION 1] SEQUENCE { 840 COMPONENTS OF LDAPResult, 841 serverSaslCreds [7] OCTET STRING OPTIONAL } 843 BindResponse consists simply of an indication from the server of the 844 status of the client's request for authentication. 846 A successful Bind operation is indicated by a BindResponse with a 847 resultCode set to success. Otherwise, an appropriate result code is 848 set in the BindResponse. For BindResponse, the protocolError result 849 code may be used to indicate that the version number supplied by the 850 client is unsupported. 852 If the client receives a BindResponse where the resultCode is set to 853 protocolError, it is to assume that the server does not support this 854 version of LDAP. While the client may be able proceed with another 855 version of this protocol (this may or may not require closing and re- 856 establishing the transport connection), how to proceed with another 857 version of this protocol is beyond the scope of this document. 858 Clients which are unable or unwilling to proceed SHOULD terminate the 859 LDAP session. 861 The serverSaslCreds field is used as part of a SASL-defined bind 862 mechanism to allow the client to authenticate the server to which it 863 is communicating, or to perform "challenge-response" authentication. 864 If the client bound with the simple choice, or the SASL mechanism 865 Lightweight Directory Access Protocol Version 3 867 does not require the server to return information to the client, then 868 this field SHALL NOT be included in the BindResponse. 870 4.3. Unbind Operation 872 The function of the Unbind operation is to terminate an LDAP session. 873 The Unbind operation is not the antithesis of the Bind operation as 874 the name implies. The naming of these operations are historical. The 875 Unbind operation should be thought of as the "quit" operation. 877 The Unbind operation is defined as follows: 879 UnbindRequest ::= [APPLICATION 2] NULL 881 The client, upon transmission of the UnbindRequest, and the server, 882 upon receipt of the UnbindRequest are to gracefully terminate the 883 LDAP session as described in Section 5.3. 885 Uncompleted operations are handled as specified in Section 3.1. 887 4.4. Unsolicited Notification 889 An unsolicited notification is an LDAPMessage sent from the server to 890 the client which is not in response to any LDAPMessage received by 891 the server. It is used to signal an extraordinary condition in the 892 server or in the LDAP session between the client and the server. The 893 notification is of an advisory nature, and the server will not expect 894 any response to be returned from the client. 896 The unsolicited notification is structured as an LDAPMessage in which 897 the messageID is zero and protocolOp is set to the extendedResp 898 choice using the ExtendedResponse type (See Section 4.12). The 899 responseName field of the ExtendedResponse always contains an LDAPOID 900 which is unique for this notification. 902 One unsolicited notification (Notice of Disconnection) is defined in 903 this document. The specification of an unsolicited notification 904 consists of: 906 - the OBJECT IDENTIFIER assigned to the notification (to be 907 specified in the responseName, 909 - the format of the contents of the responseValue (if any), 911 - the circumstances which will cause the notification to be sent, 912 and 914 - the semantics of the message. 916 4.4.1. Notice of Disconnection 917 Lightweight Directory Access Protocol Version 3 919 This notification may be used by the server to advise the client that 920 the server is about to terminate the LDAP session on its own 921 initiative. This notification is intended to assist clients in 922 distinguishing between an exceptional server condition and a 923 transient network failure. Note that this notification is not a 924 response to an Unbind requested by the client. Uncompleted operations 925 are handled as specified in Section 3.1. 927 The responseName is 1.3.6.1.4.1.1466.20036, the responseValue field 928 is absent, and the resultCode is used to indicate the reason for the 929 disconnection. When the strongerAuthRequired resultCode is returned 930 with this message, it indicates that the server has detected that an 931 established security association between the client and server has 932 unexpectedly failed or been compromised. 934 Upon transmission of the Notice of Disconnection, the server 935 gracefully terminates the LDAP session as described in Section 5.3. 937 4.5. Search Operation 939 The Search operation is used to request a server to return, subject 940 to access controls and other restrictions, a set of entries matching 941 a complex search criterion. This can be used to read attributes from 942 a single entry, from entries immediately subordinate to a particular 943 entry, or a whole subtree of entries. 945 4.5.1. Search Request 947 The Search request is defined as follows: 949 SearchRequest ::= [APPLICATION 3] SEQUENCE { 950 baseObject LDAPDN, 951 scope ENUMERATED { 952 baseObject (0), 953 singleLevel (1), 954 wholeSubtree (2), 955 ... }, 956 derefAliases ENUMERATED { 957 neverDerefAliases (0), 958 derefInSearching (1), 959 derefFindingBaseObj (2), 960 derefAlways (3) }, 961 sizeLimit INTEGER (0 .. maxInt), 962 timeLimit INTEGER (0 .. maxInt), 963 typesOnly BOOLEAN, 964 filter Filter, 965 attributes AttributeSelection } 967 AttributeSelection ::= SEQUENCE OF selector LDAPString 968 -- The LDAPString is constrained to 969 -- in Section 4.5.1.7 971 Lightweight Directory Access Protocol Version 3 973 Filter ::= CHOICE { 974 and [0] SET SIZE (1..MAX) OF filter Filter, 975 or [1] SET SIZE (1..MAX) OF filter Filter, 976 not [2] Filter, 977 equalityMatch [3] AttributeValueAssertion, 978 substrings [4] SubstringFilter, 979 greaterOrEqual [5] AttributeValueAssertion, 980 lessOrEqual [6] AttributeValueAssertion, 981 present [7] AttributeDescription, 982 approxMatch [8] AttributeValueAssertion, 983 extensibleMatch [9] MatchingRuleAssertion, 984 ... } 986 SubstringFilter ::= SEQUENCE { 987 type AttributeDescription, 988 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE { 989 initial [0] AssertionValue, -- can occur at most once 990 any [1] AssertionValue, 991 final [2] AssertionValue } -- can occur at most once 992 } 994 MatchingRuleAssertion ::= SEQUENCE { 995 matchingRule [1] MatchingRuleId OPTIONAL, 996 type [2] AttributeDescription OPTIONAL, 997 matchValue [3] AssertionValue, 998 dnAttributes [4] BOOLEAN DEFAULT FALSE } 1000 Note that an X.500 "list"-like operation can be emulated by the 1001 client requesting a singleLevel Search operation with a filter 1002 checking for the presence of the 'objectClass' attribute, and that an 1003 X.500 "read"-like operation can be emulated by a baseObject Search 1004 operation with the same filter. A server which provides a gateway to 1005 X.500 is not required to use the Read or List operations, although it 1006 may choose to do so, and if it does, it must provide the same 1007 semantics as the X.500 Search operation. 1009 4.5.1.1 SearchRequest.baseObject 1011 The name of the base object entry (or possibly the root) relative to 1012 which the Search is to be performed. 1014 4.5.1.2 SearchRequest.scope 1016 Specifies the scope of the Search to be performed. The semantics (as 1017 described in [X.511]) of the defined values of this field are: 1019 baseObject: The scope is constrained to the entry named by 1020 baseObject. 1022 singleLevel: The scope is constrained to the immediate 1023 subordinates of the entry named by baseObject. 1025 Lightweight Directory Access Protocol Version 3 1027 wholeSubtree: the scope is constrained to the entry named by the 1028 baseObject, and all its subordinates. 1030 4.5.1.3 SearchRequest.derefAliases 1032 An indicator as to whether or not alias entries (as defined in 1033 [Models]) are to be dereferenced during stages of the Search 1034 operation. 1036 The act of dereferencing an alias includes recursively dereferencing 1037 aliases which refer to aliases. 1039 Servers MUST detect looping while dereferencing aliases in order to 1040 prevent denial of service attacks of this nature. 1042 The semantics of the defined values of this field are: 1044 neverDerefAliases: Do not dereference aliases in searching or in 1045 locating the base object of the Search. 1047 derefInSearching: While searching subordinates of the base object, 1048 dereference any alias within the search scope. Dereferenced 1049 objects become the vertices of further search scopes where the 1050 Search operation is also applied. If the search scope is 1051 wholeSubtree, the Search continues in the subtree(s) of any 1052 dereferenced object. If the search scope is singleLevel, the 1053 search is applied to any dereferenced objects, and is not applied 1054 to their subordinates. Servers SHOULD eliminate duplicate entries 1055 that arise due to alias dereferencing while searching. 1057 derefFindingBaseObj: Dereference aliases in locating the base 1058 object of the Search, but not when searching subordinates of the 1059 base object. 1061 derefAlways: Dereference aliases both in searching and in locating 1062 the base object of the Search. 1064 4.5.1.4 SearchRequest.sizeLimit 1066 A size limit that restricts the maximum number of entries to be 1067 returned as a result of the Search. A value of zero in this field 1068 indicates that no client-requested size limit restrictions are in 1069 effect for the Search. Servers may also enforce a maximum number of 1070 entries to return. 1072 4.5.1.5 SearchRequest.timeLimit 1074 A time limit that restricts the maximum time (in seconds) allowed for 1075 a Search. A value of zero in this field indicates that no client- 1076 requested time limit restrictions are in effect for the Search. 1077 Servers may also enforce a maximum time limit for the Search. 1079 Lightweight Directory Access Protocol Version 3 1081 4.5.1.6 SearchRequest.typesOnly 1083 An indicator as to whether Search results are to contain both 1084 attribute descriptions and values, or just attribute descriptions. 1085 Setting this field to TRUE causes only attribute descriptions (no 1086 values) to be returned. Setting this field to FALSE causes both 1087 attribute descriptions and values to be returned. 1089 4.5.1.7 SearchRequest.filter 1091 A filter that defines the conditions that must be fulfilled in order 1092 for the Search to match a given entry. 1094 The 'and', 'or' and 'not' choices can be used to form combinations of 1095 filters. At least one filter element MUST be present in an 'and' or 1096 'or' choice. The others match against individual attribute values of 1097 entries in the scope of the Search. (Implementor's note: the 'not' 1098 filter is an example of a tagged choice in an implicitly-tagged 1099 module. In BER this is treated as if the tag was explicit.) 1101 A server MUST evaluate filters according to the three-valued logic of 1102 [X.511] (1993) Clause 7.8.1. In summary, a filter is evaluated to 1103 either "TRUE", "FALSE" or "Undefined". If the filter evaluates to 1104 TRUE for a particular entry, then the attributes of that entry are 1105 returned as part of the Search result (subject to any applicable 1106 access control restrictions). If the filter evaluates to FALSE or 1107 Undefined, then the entry is ignored for the Search. 1109 A filter of the "and" choice is TRUE if all the filters in the SET OF 1110 evaluate to TRUE, FALSE if at least one filter is FALSE, and 1111 otherwise Undefined. A filter of the "or" choice is FALSE if all of 1112 the filters in the SET OF evaluate to FALSE, TRUE if at least one 1113 filter is TRUE, and Undefined otherwise. A filter of the 'not' choice 1114 is TRUE if the filter being negated is FALSE, FALSE if it is TRUE, 1115 and Undefined if it is Undefined. 1117 A filter item evaluates to Undefined when the server would not be 1118 able to determine whether the assertion value matches an entry. 1119 Examples include: 1121 - An attribute description in an equalityMatch, substrings, 1122 greaterOrEqual, lessOrEqual, approxMatch or extensibleMatch 1123 filter is not recognized by the server. 1125 - The attribute type does not define the appropriate matching 1126 rule. 1128 - A MatchingRuleId in the extensibleMatch is not recognized by 1129 the server or is not valid for the attribute type. 1131 - The type of filtering requested is not implemented. 1133 Lightweight Directory Access Protocol Version 3 1135 - The assertion value is invalid. 1137 For example, if a server did not recognize the attribute type 1138 shoeSize, a filter of (shoeSize=*) would evaluate to FALSE, and the 1139 filters (shoeSize=12), (shoeSize>=12) and (shoeSize<=12) would each 1140 evaluate to Undefined. 1142 Servers MUST NOT return errors if attribute descriptions or matching 1143 rule ids are not recognized, assertion values are invalid, or the 1144 assertion syntax is not supported. More details of filter processing 1145 are given in Clause 7.8 of [X.511]. 1147 4.5.1.7.1 SearchRequest.filter.equalityMatch 1149 The matching rule for equalityMatch filter items is defined by the 1150 EQUALITY matching rule for the attribute type. 1152 4.5.1.7.2 SearchRequest.filter.substrings 1154 There SHALL be at most one 'initial', and at most one 'final' in the 1155 'substrings' of a SubstringFilter. If 'initial' is present, it SHALL 1156 be the first element of 'substrings'. If 'final' is present, it SHALL 1157 be the last element of 'substrings'. 1159 The matching rule for an AssertionValue in a substrings filter item 1160 is defined by the SUBSTR matching rule for the attribute type. Note 1161 that the AssertionValue in a substrings filter item conforms to the 1162 assertion syntax of the EQUALITY matching rule for the attribute type 1163 rather than the assertion syntax of the SUBSTR matching rule for the 1164 attribute type. Conceptually, the entire SubstringFilter is converted 1165 into an assertion value of the substrings matching rule prior to 1166 applying the rule. 1168 4.5.1.7.3 SearchRequest.filter.greaterOrEqual 1170 The matching rule for the greaterOrEqual filter item is defined by 1171 the ORDERING and EQUALITY matching rules for the attribute type. 1173 4.5.1.7.4 SearchRequest.filter.lessOrEqual 1175 The matching rule for the lessOrEqual filter item is defined by the 1176 ORDERING matching rule for the attribute type. 1178 4.5.1.7.5 SearchRequest.filter.present 1180 The present match evaluates to TRUE where there is an attribute or 1181 subtype of the specified attribute description present in an entry, 1182 Lightweight Directory Access Protocol Version 3 1184 and FALSE otherwise (including a presence test with an unrecognized 1185 attribute description). 1187 4.5.1.7.6 SearchRequest.filter.approxMatch 1189 An approxMatch filter item evaluates to TRUE when there is a value of 1190 the attribute or subtype for which some locally-defined approximate 1191 matching algorithm (e.g. spelling variations, phonetic match, etc.) 1192 returns TRUE. If an item matches for equality, it also satisfies an 1193 approximate match. If approximate matching is not supported for the 1194 attribute, this filter item should be treated as an equalityMatch. 1196 4.5.1.7.7 SearchRequest.filter.extensibleMatch 1198 The fields of the extensibleMatch filter item are evaluated as 1199 follows: 1201 - If the matchingRule field is absent, the type field MUST be 1202 present, and an equality match is performed for that type. 1204 - If the type field is absent and the matchingRule is present, the 1205 matchValue is compared against all attributes in an entry which 1206 support that matchingRule. 1208 - If the type field is present and the matchingRule is present, the 1209 matchValue is compared against entry attributes of the specified 1210 type. 1212 - If the dnAttributes field is set to TRUE, the match is 1213 additionally applied against all the AttributeValueAssertions in 1214 an entry's distinguished name, and evaluates to TRUE if there is 1215 at least one attribute in the distinguished name for which the 1216 filter item evaluates to TRUE. The dnAttributes field is present 1217 to alleviate the need for multiple versions of generic matching 1218 rules (such as word matching), where one applies to entries and 1219 another applies to entries and DN attributes as well. 1221 The matchingRule used for evaluation determines the syntax for the 1222 assertion value. Once the matchingRule and attribute(s) have been 1223 determined, the filter item evaluates to TRUE if it matches with at 1224 least one attribute in the entry, FALSE if it does not match any 1225 attribute in the entry, and Undefined if the matchingRule is not 1226 recognized, the matchingRule is unsuitable for use with the specified 1227 type, or the assertionValue is invalid. 1229 4.5.1.7 SearchRequest.attributes 1231 A selection list of the attributes to be returned from each entry 1232 which matches the search filter. LDAPString values of this field are 1233 constrained to the following Augmented Backus-Naur Form ([ABNF]): 1235 Lightweight Directory Access Protocol Version 3 1237 attributeSelector = attributedescription / selectorspecial 1239 selectorspecial = noattrs / alluserattrs 1241 noattrs = %x31.2E.31 ; "1.1" 1243 alluserattrs = %x2A ; asterisk ("*") 1245 The production is defined in Section 2.5 of 1246 [Models]. 1248 There are three special cases which may appear in the attributes 1249 selection list: 1251 - an empty list with no attributes, 1253 - a list containing "*" (with zero or more attribute 1254 descriptions), and 1256 - a list containing only "1.1". 1258 An empty list requests the return of all user attributes. 1260 A list containing "*" requests the return of all user attributes 1261 in addition to other listed (operational) attributes. 1263 A list containing only the OID "1.1" indicates that no attributes 1264 are to be returned. If "1.1" is provided with other 1265 attributeSelector values, the "1.1" attributeSelector is ignored. 1266 This OID was chosen because it does not (and can not) correspond 1267 to any attribute in use. 1269 Client implementors should note that even if all user attributes are 1270 requested, some attributes and/or attribute values of the entry may 1271 not be included in Search results due to access controls or other 1272 restrictions. Furthermore, servers will not return operational 1273 attributes, such as objectClasses or attributeTypes, unless they are 1274 listed by name. Operational attributes are described in [Models]. 1276 Attributes are returned at most once in an entry. If an attribute 1277 description is named more than once in the list, the subsequent names 1278 are ignored. If an attribute description in the list is not 1279 recognized, it is ignored by the server. 1281 4.5.2. Search Result 1283 The results of the Search operation are returned as zero or more 1284 SearchResultEntry and/or SearchResultReference messages, followed by 1285 a single SearchResultDone message. 1287 SearchResultEntry ::= [APPLICATION 4] SEQUENCE { 1288 objectName LDAPDN, 1289 attributes PartialAttributeList } 1290 Lightweight Directory Access Protocol Version 3 1292 PartialAttributeList ::= SEQUENCE OF 1293 partialAttribute PartialAttribute 1295 SearchResultReference ::= [APPLICATION 19] SEQUENCE 1296 SIZE (1..MAX) OF uri URI 1298 SearchResultDone ::= [APPLICATION 5] LDAPResult 1300 Each SearchResultEntry represents an entry found during the Search. 1301 Each SearchResultReference represents an area not yet explored during 1302 the Search. The SearchResultEntry and SearchResultReference PDUs may 1303 come in any order. Following all the SearchResultReference and 1304 SearchResultEntry responses, the server returns a SearchResultDone 1305 response, which contains an indication of success, or detailing any 1306 errors that have occurred. 1308 Each entry returned in a SearchResultEntry will contain all 1309 appropriate attributes as specified in the attributes field of the 1310 Search Request, subject to access control and other administrative 1311 policy. Note that the PartialAttributeList may hold zero elements. 1312 This may happen when none of the attributes of an entry were 1313 requested, or could be returned. Note also that the partialAttribute 1314 vals set may hold zero elements. This may happen when typesOnly is 1315 requested, access controls prevent the return of values, or other 1316 reasons. 1318 Some attributes may be constructed by the server and appear in a 1319 SearchResultEntry attribute list, although they are not stored 1320 attributes of an entry. Clients SHOULD NOT assume that all attributes 1321 can be modified, even if permitted by access control. 1323 If the server's schema defines short names [Models] for an attribute 1324 type then the server SHOULD use one of those names in attribute 1325 descriptions for that attribute type (in preference to using the 1326 [Models] format of the attribute type's object 1327 identifier). The server SHOULD NOT use the short name if that name is 1328 known by the server to be ambiguous, or otherwise likely to cause 1329 interoperability problems. 1331 4.5.3. Continuation References in the Search Result 1333 If the server was able to locate the entry referred to by the 1334 baseObject but was unable or unwilling to search one or more non- 1335 local entries, the server may return one or more 1336 SearchResultReference messages, each containing a reference to 1337 another set of servers for continuing the operation. A server MUST 1338 NOT return any SearchResultReference messages if it has not located 1339 the baseObject and thus has not searched any entries; in this case it 1340 would return a SearchResultDone containing either a referral or 1341 noSuchObject result code (depending on the server's knowledge of the 1342 entry named in the baseObject). 1344 Lightweight Directory Access Protocol Version 3 1346 If a server holds a copy or partial copy of the subordinate naming 1347 context (Section 5 of [Models]), it may use the search filter to 1348 determine whether or not to return a SearchResultReference response. 1349 Otherwise SearchResultReference responses are always returned when in 1350 scope. 1352 The SearchResultReference is of the same data type as the Referral. 1354 If the client wishes to progress the Search, it issues a new Search 1355 operation for each SearchResultReference that is returned. If 1356 multiple URIs are present, the client assumes that any supported URI 1357 may be used to progress the operation. 1359 Clients that follow search continuation references MUST ensure that 1360 they do not loop between servers. They MUST NOT repeatedly contact 1361 the same server for the same request with the same parameters. Some 1362 clients use a counter that is incremented each time search result 1363 reference handling occurs for an operation, and these kinds of 1364 clients MUST be able to handle at least ten nested referrals while 1365 progressing the operation. 1367 Note that the Abandon operation described in Section 4.11 applies 1368 only to a particular operation sent at the LDAP message layer between 1369 a client and server. The client must abandon subsequent Search 1370 operations it wishes to individually. 1372 A URI for a server implementing LDAP and accessible via [TCP]/[IP] 1373 (v4 or v6) is written as an LDAP URL according to [LDAPURL]. 1375 SearchResultReference values which are LDAP URLs follow these rules: 1377 - The part of the LDAP URL MUST be present, with the new target 1378 object name. The client uses this name when following the 1379 reference. 1381 - Some servers (e.g. participating in distributed indexing) may 1382 provide a different filter in the LDAP URL. 1384 - If the part of the LDAP URL is present, the client uses 1385 this filter in its next request to progress this Search, and if it 1386 is not present the client uses the same filter as it used for that 1387 Search. 1389 - If the originating search scope was singleLevel, the part 1390 of the LDAP URL will be "base". 1392 - It is RECOMMENDED that the part be present to avoid 1393 ambiguity. In the absence of a part, the scope of the 1394 original Search request is assumed. 1396 - Other aspects of the new Search request may be the same as or 1397 different from the Search request which generated the 1398 SearchResultReference. 1400 Lightweight Directory Access Protocol Version 3 1402 - The name of an unexplored subtree in a SearchResultReference need 1403 not be subordinate to the base object. 1405 Other kinds of URIs may be returned. The syntax and semantics of such 1406 URIs is left to future specifications. Clients may ignore URIs that 1407 they do not support. 1409 UTF-8 encoded characters appearing in the string representation of a 1410 DN, search filter, or other fields of the referral value may not be 1411 legal for URIs (e.g. spaces) and MUST be escaped using the % method 1412 in [URI]. 1414 4.5.3.1. Examples 1416 For example, suppose the contacted server (hosta) holds the entry 1417 and the entry . It 1418 knows that both LDAP servers (hostb) and (hostc) hold 1419 (one is the master and the other server 1420 a shadow), and that LDAP-capable server (hostd) holds the subtree 1421 . If a wholeSubtree Search of 1422 is requested to the contacted server, it may 1423 return the following: 1425 SearchResultEntry for DC=Example,DC=NET 1426 SearchResultEntry for CN=Manager,DC=Example,DC=NET 1427 SearchResultReference { 1428 ldap://hostb/OU=People,DC=Example,DC=NET??sub 1429 ldap://hostc/OU=People,DC=Example,DC=NET??sub } 1430 SearchResultReference { 1431 ldap://hostd/OU=Roles,DC=Example,DC=NET??sub } 1432 SearchResultDone (success) 1434 Client implementors should note that when following a 1435 SearchResultReference, additional SearchResultReference may be 1436 generated. Continuing the example, if the client contacted the server 1437 (hostb) and issued the Search request for the subtree 1438 , the server might respond as follows: 1440 SearchResultEntry for OU=People,DC=Example,DC=NET 1441 SearchResultReference { 1442 ldap://hoste/OU=Managers,OU=People,DC=Example,DC=NET??sub } 1443 SearchResultReference { 1444 ldap://hostf/OU=Consultants,OU=People,DC=Example,DC=NET??sub } 1445 SearchResultDone (success) 1447 Similarly, if a singleLevel Search of is 1448 requested to the contacted server, it may return the following: 1450 SearchResultEntry for CN=Manager,DC=Example,DC=NET 1451 SearchResultReference { 1452 ldap://hostb/OU=People,DC=Example,DC=NET??base 1453 ldap://hostc/OU=People,DC=Example,DC=NET??base } 1454 Lightweight Directory Access Protocol Version 3 1456 SearchResultReference { 1457 ldap://hostd/OU=Roles,DC=Example,DC=NET??base } 1458 SearchResultDone (success) 1460 If the contacted server does not hold the base object for the Search, 1461 but has knowledge of its possible location, then it may return a 1462 referral to the client. In this case, if the client requests a 1463 subtree Search of to hosta, the server returns a 1464 SearchResultDone containing a referral. 1466 SearchResultDone (referral) { 1467 ldap://hostg/DC=Example,DC=ORG??sub } 1469 4.6. Modify Operation 1471 The Modify operation allows a client to request that a modification 1472 of an entry be performed on its behalf by a server. The Modify 1473 Request is defined as follows: 1475 ModifyRequest ::= [APPLICATION 6] SEQUENCE { 1476 object LDAPDN, 1477 changes SEQUENCE OF change SEQUENCE { 1478 operation ENUMERATED { 1479 add (0), 1480 delete (1), 1481 replace (2), 1482 ... }, 1483 modification PartialAttribute } } 1485 Fields of the Modify Request are: 1487 - object: The value of this field contains the name of the entry to 1488 be modified. The server SHALL NOT perform any alias dereferencing 1489 in determining the object to be modified. 1491 - changes: A list of modifications to be performed on the entry. The 1492 entire list of modifications MUST be performed in the order they 1493 are listed as a single atomic operation. While individual 1494 modifications may violate certain aspects of the directory schema 1495 (such as the object class definition and DIT content rule), the 1496 resulting entry after the entire list of modifications is 1497 performed MUST conform to the requirements of the directory model 1498 and controlling schema [Models]. 1500 - operation: Used to specify the type of modification being 1501 performed. Each operation type acts on the following 1502 modification. The values of this field have the following 1503 semantics respectively: 1505 add: add values listed to the modification attribute, 1506 creating the attribute if necessary; 1507 Lightweight Directory Access Protocol Version 3 1509 delete: delete values listed from the modification attribute. 1510 If no values are listed, or if all current values of the 1511 attribute are listed, the entire attribute is removed; 1513 replace: replace all existing values of the modification 1514 attribute with the new values listed, creating the attribute 1515 if it did not already exist. A replace with no value will 1516 delete the entire attribute if it exists, and is ignored if 1517 the attribute does not exist. 1519 - modification: A PartialAttribute (which may have an empty SET 1520 of vals) used to hold the attribute type or attribute type and 1521 values being modified. 1523 Upon receipt of a Modify Request, the server attempts to perform the 1524 necessary modifications to the DIT and returns the result in a Modify 1525 Response, defined as follows: 1527 ModifyResponse ::= [APPLICATION 7] LDAPResult 1529 The server will return to the client a single Modify Response 1530 indicating either the successful completion of the DIT modification, 1531 or the reason that the modification failed. Due to the requirement 1532 for atomicity in applying the list of modifications in the Modify 1533 Request, the client may expect that no modifications of the DIT have 1534 been performed if the Modify Response received indicates any sort of 1535 error, and that all requested modifications have been performed if 1536 the Modify Response indicates successful completion of the Modify 1537 operation. Whether the modification was applied or not cannot be 1538 determined by the client if the Modify Response was not received 1539 (e.g. the LDAP session was terminated or the Modify operation was 1540 abandoned). 1542 Servers MUST ensure that entries conform to user and system schema 1543 rules or other data model constraints. The Modify operation cannot be 1544 used to remove from an entry any of its distinguished values, i.e. 1545 those values which form the entry's relative distinguished name. An 1546 attempt to do so will result in the server returning the 1547 notAllowedOnRDN result code. The Modify DN operation described in 1548 Section 4.9 is used to rename an entry. 1550 For attribute types which specify no equality matching, the rules in 1551 Section 2.5.1 of [Models] are followed. 1553 Note that due to the simplifications made in LDAP, there is not a 1554 direct mapping of the changes in an LDAP ModifyRequest onto the 1555 changes of a DAP ModifyEntry operation, and different implementations 1556 of LDAP-DAP gateways may use different means of representing the 1557 change. If successful, the final effect of the operations on the 1558 entry MUST be identical. 1560 4.7. Add Operation 1561 Lightweight Directory Access Protocol Version 3 1563 The Add operation allows a client to request the addition of an entry 1564 into the Directory. The Add Request is defined as follows: 1566 AddRequest ::= [APPLICATION 8] SEQUENCE { 1567 entry LDAPDN, 1568 attributes AttributeList } 1570 AttributeList ::= SEQUENCE OF attribute Attribute 1572 Fields of the Add Request are: 1574 - entry: the name of the entry to be added. The server SHALL NOT 1575 dereference any aliases in locating the entry to be added. 1577 - attributes: the list of attributes that, along with those from the 1578 RDN, make up the content of the entry being added. Clients MAY or 1579 MAY NOT include the RDN attribute(s) in this list. Clients MUST 1580 NOT supply NO-USER-MODIFICATION attributes such as the 1581 createTimestamp or creatorsName attributes, since the server 1582 maintains these automatically. 1584 Servers MUST ensure that entries conform to user and system schema 1585 rules or other data model constraints. For attribute types which 1586 specify no equality matching, the rules in Section 2.5.1 of [Models] 1587 are followed (this applies to the naming attribute in addition to any 1588 multi-valued attributes being added). 1590 The entry named in the entry field of the AddRequest MUST NOT exist 1591 for the AddRequest to succeed. The immediate superior (parent) of an 1592 object or alias entry to be added MUST exist. For example, if the 1593 client attempted to add , the 1594 entry did not exist, and the entry did 1595 exist, then the server would return the noSuchObject result code with 1596 the matchedDN field containing . 1598 Upon receipt of an Add Request, a server will attempt to add the 1599 requested entry. The result of the Add attempt will be returned to 1600 the client in the Add Response, defined as follows: 1602 AddResponse ::= [APPLICATION 9] LDAPResult 1604 A response of success indicates that the new entry has been added to 1605 the Directory. 1607 4.8. Delete Operation 1609 The Delete operation allows a client to request the removal of an 1610 entry from the Directory. The Delete Request is defined as follows: 1612 DelRequest ::= [APPLICATION 10] LDAPDN 1613 Lightweight Directory Access Protocol Version 3 1615 The Delete Request consists of the name of the entry to be deleted. 1616 The server SHALL NOT dereference aliases while resolving the name of 1617 the target entry to be removed. 1619 Only leaf entries (those with no subordinate entries) can be deleted 1620 with this operation. 1622 Upon receipt of a Delete Request, a server will attempt to perform 1623 the entry removal requested and return the result in the Delete 1624 Response defined as follows: 1626 DelResponse ::= [APPLICATION 11] LDAPResult 1628 4.9. Modify DN Operation 1630 The Modify DN operation allows a client to change the Relative 1631 Distinguished Name (RDN) of an entry in the Directory, and/or to move 1632 a subtree of entries to a new location in the Directory. The Modify 1633 DN Request is defined as follows: 1635 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE { 1636 entry LDAPDN, 1637 newrdn RelativeLDAPDN, 1638 deleteoldrdn BOOLEAN, 1639 newSuperior [0] LDAPDN OPTIONAL } 1641 Fields of the Modify DN Request are: 1643 - entry: the name of the entry to be changed. This entry may or may 1644 not have subordinate entries. 1646 - newrdn: the new RDN of the entry. The value of the old RDN is 1647 supplied when moving the entry to a new superior without changing 1648 its RDN. Attribute values of the new RDN not matching any 1649 attribute value of the entry are added to the entry and an 1650 appropriate error is returned if this fails. 1652 - deleteoldrdn: a boolean field that controls whether the old RDN 1653 attribute values are to be retained as attributes of the entry, or 1654 deleted from the entry. 1656 - newSuperior: if present, this is the name of an existing object 1657 entry which becomes the immediate superior (parent) of the 1658 existing entry. 1660 The server SHALL NOT dereference any aliases in locating the objects 1661 named in entry or newSuperior. 1663 Upon receipt of a ModifyDNRequest, a server will attempt to perform 1664 the name change and return the result in the Modify DN Response, 1665 defined as follows: 1667 ModifyDNResponse ::= [APPLICATION 13] LDAPResult 1668 Lightweight Directory Access Protocol Version 3 1670 For example, if the entry named in the entry field was , the newrdn field was , and the 1672 newSuperior field was absent, then this operation would attempt to 1673 rename the entry to be . If there was 1674 already an entry with that name, the operation would fail with the 1675 entryAlreadyExists result code. 1677 Servers MUST ensure that entries conform to user and system schema 1678 rules or other data model constraints. For attribute types which 1679 specify no equality matching, the rules in Section 2.5.1 of [Models] 1680 are followed (this pertains to newrdn and deleteoldrdn). 1682 The object named in newSuperior MUST exist. For example, if the 1683 client attempted to add , the 1684 entry did not exist, and the entry did 1685 exist, then the server would return the noSuchObject result code with 1686 the matchedDN field containing . 1688 If the deleteoldrdn field is TRUE, the attribute values forming the 1689 old RDN but not the new RDN are deleted from the entry. If the 1690 deleteoldrdn field is FALSE, the attribute values forming the old RDN 1691 will be retained as non-distinguished attribute values of the entry. 1693 Note that X.500 restricts the ModifyDN operation to only affect 1694 entries that are contained within a single server. If the LDAP server 1695 is mapped onto DAP, then this restriction will apply, and the 1696 affectsMultipleDSAs result code will be returned if this error 1697 occurred. In general, clients MUST NOT expect to be able to perform 1698 arbitrary movements of entries and subtrees between servers or 1699 between naming contexts. 1701 4.10. Compare Operation 1703 The Compare operation allows a client to compare an assertion value 1704 with the values of a particular attribute in a particular entry in 1705 the Directory. The Compare Request is defined as follows: 1707 CompareRequest ::= [APPLICATION 14] SEQUENCE { 1708 entry LDAPDN, 1709 ava AttributeValueAssertion } 1711 Fields of the Compare Request are: 1713 - entry: the name of the entry to be compared. The server SHALL NOT 1714 dereference any aliases in locating the entry to be compared. 1716 - ava: holds the attribute value assertion to be compared. 1718 Upon receipt of a Compare Request, a server will attempt to perform 1719 the requested comparison and return the result in the Compare 1720 Response, defined as follows: 1722 Lightweight Directory Access Protocol Version 3 1724 CompareResponse ::= [APPLICATION 15] LDAPResult 1726 The resultCode is set to compareTrue, compareFalse, or an appropriate 1727 error. compareTrue indicates that the assertion value in the ava 1728 field matches a value of the attribute or subtype according to the 1729 attribute's EQUALITY matching rule. compareFalse indicates that the 1730 assertion value in the ava field and the values of the attribute or 1731 subtype did not match. Other result codes indicate either that the 1732 result of the comparison was Undefined (Section 4.5.1), or that some 1733 error occurred. 1735 Note that some directory systems may establish access controls which 1736 permit the values of certain attributes (such as userPassword) to be 1737 compared but not interrogated by other means. 1739 4.11. Abandon Operation 1741 The function of the Abandon operation is to allow a client to request 1742 that the server abandon an uncompleted operation. The Abandon Request 1743 is defined as follows: 1745 AbandonRequest ::= [APPLICATION 16] MessageID 1747 The MessageID is that of an operation which was requested earlier at 1748 this LDAP message layer. The Abandon request itself has its own 1749 MessageID. This is distinct from the MessageID of the earlier 1750 operation being abandoned. 1752 There is no response defined in the Abandon operation. Upon receipt 1753 of an AbandonRequest, the server MAY abandon the operation identified 1754 by the MessageID. Since the client cannot tell the difference between 1755 a successfully abandoned operation and an uncompleted operation, the 1756 application of the Abandon operation is limited to uses where the 1757 client does not require an indication of its outcome. 1759 Abandon, Bind, Unbind, and StartTLS operations cannot be abandoned. 1761 In the event that a server receives an Abandon Request on a Search 1762 operation in the midst of transmitting responses to the Search, that 1763 server MUST cease transmitting entry responses to the abandoned 1764 request immediately, and MUST NOT send the SearchResultDone. Of 1765 course, the server MUST ensure that only properly encoded LDAPMessage 1766 PDUs are transmitted. 1768 The ability to abandon other (particularly update) operations is at 1769 the discretion of the server. 1771 Clients should not send Abandon requests for the same operation 1772 multiple times, and MUST also be prepared to receive results from 1773 operations it has abandoned (since these may have been in transit 1774 when the Abandon was requested, or are not able to be abandoned). 1776 Lightweight Directory Access Protocol Version 3 1778 Servers MUST discard Abandon requests for message IDs they do not 1779 recognize, for operations which cannot be abandoned, and for 1780 operations which have already been abandoned. 1782 4.12. Extended Operation 1784 The Extended operation allows additional operations to be defined for 1785 services not already available in the protocol. For example, to Add 1786 operations to install transport layer security (see Section 4.14). 1788 The Extended operation allows clients to make requests and receive 1789 responses with predefined syntaxes and semantics. These may be 1790 defined in RFCs or be private to particular implementations. 1792 Each Extended operation consists of an Extended request and an 1793 Extended response. 1795 ExtendedRequest ::= [APPLICATION 23] SEQUENCE { 1796 requestName [0] LDAPOID, 1797 requestValue [1] OCTET STRING OPTIONAL } 1799 The requestName is a dotted-decimal representation of the unique 1800 OBJECT IDENTIFIER corresponding to the request. The requestValue is 1801 information in a form defined by that request, encapsulated inside an 1802 OCTET STRING. 1804 The server will respond to this with an LDAPMessage containing an 1805 ExtendedResponse. 1807 ExtendedResponse ::= [APPLICATION 24] SEQUENCE { 1808 COMPONENTS OF LDAPResult, 1809 responseName [10] LDAPOID OPTIONAL, 1810 responseValue [11] OCTET STRING OPTIONAL } 1812 The responseName is typically not required to be present as the 1813 syntax and semantics of the response (including the format of the 1814 responseValue) is implicitly known and associated with the request by 1815 the messageID. 1817 If the Extended operation associated with the requestName is not 1818 supported by the server, the server MUST NOT provide a responseName 1819 nor a responseValue and MUST return with resultCode set to 1820 protocolError. 1822 The requestValue and responseValue fields contain any information 1823 associated with the operation. The format of these fields is defined 1824 by the specification of the Extended operation. Implementations MUST 1825 be prepared to handle arbitrary contents of these fields, including 1826 zero bytes. Values that are defined in terms of ASN.1 and BER encoded 1827 according to Section 5.1, also follow the extensibility rules in 1828 Section 4. 1830 Lightweight Directory Access Protocol Version 3 1832 Servers list the requestName of Extended Requests they recognize in 1833 the 'supportedExtension' attribute in the root DSE (Section 5.1 of 1834 [Models]). 1836 Extended operations may be specified in other documents. The 1837 specification of an Extended operation consists of: 1839 - the OBJECT IDENTIFIER assigned to the requestName, 1841 - the OBJECT IDENTIFIER (if any) assigned to the responseName (note 1842 that the same OBJECT IDENTIFIER my be used for both the 1843 requestName and responseName), 1845 - the format of the contents of the requestValue and responseValue 1846 (if any), and 1848 - the semantics of the operation. 1850 4.13. IntermediateResponse Message 1852 While the Search operation provides a mechanism to return multiple 1853 response messages for a single Search request, other operations, by 1854 nature, do not provide for multiple response messages. 1856 The IntermediateResponse message provides a general mechanism for 1857 defining single-request/multiple-response operations in LDAP. This 1858 message is intended to be used in conjunction with the Extended 1859 operation to define new single-request/multiple-response operations 1860 or in conjunction with a control when extending existing LDAP 1861 operations in a way that requires them to return Intermediate 1862 response information. 1864 It is intended that the definitions and descriptions of Extended 1865 operations and controls that make use of the IntermediateResponse 1866 message will define the circumstances when an IntermediateResponse 1867 message can be sent by a server and the associated meaning of an 1868 IntermediateResponse message sent in a particular circumstance. 1870 IntermediateResponse ::= [APPLICATION 25] SEQUENCE { 1871 responseName [0] LDAPOID OPTIONAL, 1872 responseValue [1] OCTET STRING OPTIONAL } 1874 IntermediateResponse messages SHALL NOT be returned to the client 1875 unless the client issues a request that specifically solicits their 1876 return. This document defines two forms of solicitation: Extended 1877 operation and request control. IntermediateResponse messages are 1878 specified in documents describing the manner in which they are 1879 solicited (i.e. in the Extended operation or request control 1880 specification that uses them). These specifications include: 1882 - the OBJECT IDENTIFIER (if any) assigned to the responseName, 1884 - the format of the contents of the responseValue (if any), and 1885 Lightweight Directory Access Protocol Version 3 1887 - the semantics associated with the IntermediateResponse message. 1889 Extensions that allow the return of multiple types of 1890 IntermediateResponse messages SHALL identify those types using unique 1891 responseName values (note that one of these may specify no value). 1893 Sections 4.13.1 and 4.13.2 describe additional requirements on the 1894 inclusion of responseName and responseValue in IntermediateResponse 1895 messages. 1897 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse 1899 A single-request/multiple-response operation may be defined using a 1900 single ExtendedRequest message to solicit zero or more 1901 IntermediateResponse messages of one or more kinds followed by an 1902 ExtendedResponse message. 1904 4.13.2. Usage with LDAP Request Controls 1906 A control's semantics may include the return of zero or more 1907 IntermediateResponse messages prior to returning the final result 1908 code for the operation. One or more kinds of IntermediateResponse 1909 messages may be sent in response to a request control. 1911 All IntermediateResponse messages associated with request controls 1912 SHALL include a responseName. This requirement ensures that the 1913 client can correctly identify the source of IntermediateResponse 1914 messages when: 1916 - two or more controls using IntermediateResponse messages are 1917 included in a request for any LDAP operation or 1919 - one or more controls using IntermediateResponse messages are 1920 included in a request with an LDAP Extended operation that uses 1921 IntermediateResponse messages. 1923 4.14. StartTLS Operation 1925 The Start Transport Layer Security (StartTLS) operation's purpose is 1926 to initiate installation of a TLS layer. The StartTLS operation is 1927 defined using the Extended operation mechanism described in Section 1928 4.12. 1930 4.14.1. StartTLS Request 1932 A client requests TLS establishment by transmitting a StartTLS 1933 request PDU to the server. The StartTLS request is defined in terms 1934 Lightweight Directory Access Protocol Version 3 1936 of an ExtendedRequest. The requestName is "1.3.6.1.4.1.1466.20037", 1937 and the requestValue field is always absent. 1939 The client MUST NOT send any PDUs at this LDAP message layer 1940 following this request until it receives a StartTLS Extended response 1941 and, in the case of a successful response, completes TLS 1942 negotiations. 1944 Detected sequencing problems (particularly those detailed in Section 1945 3.1.1 of [AuthMeth]) result in the resultCode being set to 1946 operationsError. 1948 If the server does not support TLS (whether by design or by current 1949 configuration), it returns with the resultCode set to protocolError 1950 as described in Section 4.12. 1952 4.14.2. StartTLS Response 1954 When a StartTLS request is made, servers supporting the operation 1955 MUST return a StartTLS response PDU to the requestor. The 1956 responseName, if present, is also "1.3.6.1.4.1.1466.20037". The 1957 responseValue is absent. 1959 If the server is willing and able to negotiate TLS, it returns with 1960 the resultCode set to success. Refer to Section 4 of [AuthMeth] for 1961 details. 1963 If the server is otherwise unwilling or unable to perform this 1964 operation, the server is to return an appropriate result code 1965 indicating the nature of the problem. For example, if the TLS 1966 subsystem is not presently available, the server may indicate so by 1967 returning with the resultCode set to unavailable. 1969 4.14.3. Removal of the TLS Layer 1971 Either the client or server MAY remove the TLS layer and leave the 1972 LDAP message layer intact by sending and receiving a TLS closure 1973 alert. 1975 The initiating protocol peer sends the TLS closure alert. If it 1976 wishes to leave the LDAP message layer intact, it then MUST cease to 1977 send further PDUs and MUST ignore any received LDAP PDUs until it 1978 receives a TLS closure alert from the other peer. 1980 Once the initiating protocol peer receives a TLS closure alert from 1981 the other peer it MAY send and receive LDAP PDUs. 1983 When a protocol peer receives the initial TLS closure alert, it may 1984 choose to allow the LDAP message layer to remain intact. In this 1985 Lightweight Directory Access Protocol Version 3 1987 case, it MUST immediately transmit a TLS closure alert. Following 1988 this, it MAY send and receive LDAP PDUs. 1990 Protocol peers MAY terminate the LDAP session after sending or 1991 receiving a TLS closure alert. 1993 After the TLS layer has been removed, the server MUST NOT send 1994 responses to any request message received before the TLS closure 1995 alert. Thus, clients wishing to receive responses to messages sent 1996 while the TLS layer is intact MUST wait for those message responses 1997 before sending the TLS closure alert. 1999 5. Protocol Encoding, Connection, and Transfer 2001 This protocol is designed to run over connection-oriented, reliable 2002 transports, where the data stream is divided into octets (8-bit 2003 units), with each octet and each bit being significant. 2005 One underlying service, LDAP over TCP, is defined in Section 2006 5.2. This service is generally applicable to applications providing 2007 or consuming X.500-based directory services on the Internet. This 2008 specification was generally written with the TCP mapping in mind. 2009 Specifications detailing other mappings may encounter various 2010 obstacles. 2012 Implementations of LDAP over TCP MUST implement the mapping as 2013 described in Section 5.2. 2015 This table illustrates the relationship between the different layers 2016 involved in an exchange between two protocol peers: 2018 +----------------------+ 2019 | LDAP message layer | 2020 +----------------------+ > LDAP PDUs 2021 +----------------------+ < data 2022 | SASL layer | 2023 +----------------------+ > SASL-protected data 2024 +----------------------+ < data 2025 | TLS layer | 2026 Application +----------------------+ > TLS-protected data 2027 ------------+----------------------+ < data 2028 Transport | transport connection | 2029 +----------------------+ 2031 5.1. Protocol Encoding 2033 The protocol elements of LDAP SHALL be encoded for exchange using the 2034 Basic Encoding Rules [BER] of [ASN.1] with the following 2035 restrictions: 2037 - Only the definite form of length encoding is used. 2039 Lightweight Directory Access Protocol Version 3 2041 - OCTET STRING values are encoded in the primitive form only. 2043 - If the value of a BOOLEAN type is true, the encoding of the value 2044 octet is set to hex "FF". 2046 - If a value of a type is its default value, it is absent. Only some 2047 BOOLEAN and INTEGER types have default values in this protocol 2048 definition. 2050 These restrictions are meant to ease the overhead of encoding and 2051 decoding certain elements in BER. 2053 These restrictions do not apply to ASN.1 types encapsulated inside of 2054 OCTET STRING values, such as attribute values, unless otherwise 2055 stated. 2057 5.2. Transmission Control Protocol (TCP) 2059 The encoded LDAPMessage PDUs are mapped directly onto the [TCP] 2060 bytestream using the BER-based encoding described in Section 5.1. It 2061 is recommended that server implementations running over the TCP 2062 provide a protocol listener on the Internet Assigned Numbers 2063 Authority (IANA)-assigned LDAP port, 389 [PortReg]. Servers may 2064 instead provide a listener on a different port number. Clients MUST 2065 support contacting servers on any valid TCP port. 2067 5.3. Termination of the LDAP session 2069 Termination of the LDAP session is typically initiated by the client 2070 sending an UnbindRequst (Section 4.3), or by the server sending a 2071 Notice of Disconnection (Section 4.4.1). In these cases each protocol 2072 peer gracefully terminates the LDAP session by ceasing exchanges at 2073 the LDAP message layer, tearing down any SASL layer, tearing down any 2074 TLS layer, and closing the transport connection. 2076 A protocol peer may determine that the continuation of any 2077 communication would be pernicious, and in this case may abruptly 2078 terminate the session by ceasing communication and closing the 2079 transport connection. 2081 In either case, when the LDAP session is terminated, uncompleted 2082 operations are handled as specified in Section 3.1. 2084 6. Security Considerations 2086 This version of the protocol provides facilities for simple 2087 authentication using a cleartext password, as well as any [SASL] 2088 mechanism. Installing SASL and/or TLS layers can provide integrity 2089 and other data security services. 2091 Lightweight Directory Access Protocol Version 3 2093 It is also permitted that the server can return its credentials to 2094 the client, if it chooses to do so. 2096 Use of cleartext password is strongly discouraged where the 2097 underlying transport service cannot guarantee confidentiality and may 2098 result in disclosure of the password to unauthorized parties. 2100 Servers are encouraged to prevent directory modifications by clients 2101 that have authenticated anonymously [AuthMeth]. 2103 Security considerations for authentication methods, SASL mechanisms, 2104 and TLS are described in [AuthMeth]. 2106 It should be noted that SASL authentication exchanges do not provide 2107 data confidentiality nor integrity protection for the version or name 2108 fields of the BindRequest nor the resultCode, diagnosticMessage, or 2109 referral fields of the BindResponse nor of any information contained 2110 in controls attached to Bind requests or responses. Thus information 2111 contained in these fields SHOULD NOT be relied on unless otherwise 2112 protected (such as by establishing protections at the transport 2113 layer). 2115 Server implementors should plan for the possibility of (protocol or 2116 external) events which alter the information used to establish 2117 security factors (e.g., credentials, authorization identities, access 2118 controls) during the course of the LDAP session, and even during the 2119 performance of a particular operation, and should take steps to avoid 2120 insecure side effects of these changes. The ways in which these 2121 issues are addressed are application and/or implementation specific. 2123 Implementations which cache attributes and entries obtained via LDAP 2124 MUST ensure that access controls are maintained if that information 2125 is to be provided to multiple clients, since servers may have access 2126 control policies which prevent the return of entries or attributes in 2127 Search results except to particular authenticated clients. For 2128 example, caches could serve result information only to the client 2129 whose request caused it to be in the cache. 2131 Servers may return referrals or Search result references which 2132 redirect clients to peer servers. It is possible for a rogue 2133 application to inject such referrals into the data stream in an 2134 attempt to redirect a client to a rogue server. Clients are advised 2135 to be aware of this, and possibly reject referrals when 2136 confidentiality measures are not in place. Clients are advised to 2137 reject referrals from the StartTLS operation. 2139 The matchedDN and diagnosticMessage fields, as well as some 2140 resultCode values (e.g., attributeOrValueExists and 2141 entryAlreadyExists), could disclose the presence or absence of 2142 specific data in the directory which is subject to access and other 2143 administrative controls. Server implementations should restrict 2144 access to protected information equally under both normal and error 2145 conditions. 2147 Lightweight Directory Access Protocol Version 3 2149 Protocol peers MUST be prepared to handle invalid and arbitrary 2150 length protocol encodings. Invalid protocol encodings include: BER 2151 encoding exceptions, format string and UTF-8 encoding exceptions, 2152 overflow exceptions, integer value exceptions, and binary mode on/off 2153 flag exceptions. The LDAPv3 PROTOS [PROTOS-LDAP] test suite provides 2154 excellent examples of these exceptions and test cases used to 2155 discover flaws. 2157 In the event that a protocol peer senses an attack which in its 2158 nature could cause damage due to further communication at any layer 2159 in the LDAP session, the protocol peer should abruptly terminate the 2160 LDAP session as described in Section 5.3. 2162 7. Acknowledgements 2164 This document is based on RFC 2251 by Mark Wahl, Tim Howes, and Steve 2165 Kille. RFC 2251 was a product of the IETF ASID Working Group. 2167 It is also based on RFC 2830 by Jeff Hodges, RL "Bob" Morgan, and 2168 Mark Wahl. RFC 2830 was a product of the IETF LDAPEXT Working Group. 2170 It is also based on RFC 3771 by Roger Harrison, and Kurt Zeilenga. 2171 RFC 3771 was an individual submission to the IETF. 2173 This document is a product of the IETF LDAPBIS Working Group. 2174 Significant contributors of technical review and content include Kurt 2175 Zeilenga, Steven Legg, and Hallvard Furuseth. 2177 8. Normative References 2179 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2180 Specifications: ABNF", RFC 2234, November 1997. 2182 [ASN.1] ITU-T Recommendation X.680 (07/2002) | ISO/IEC 8824-1:2002 2183 "Information Technology - Abstract Syntax Notation One 2184 (ASN.1): Specification of basic notation" 2186 [AuthMeth] Harrison, R., "LDAP: Authentication Methods and Connection 2187 Level Security Mechanisms", draft-ietf-ldapbis-authmeth- 2188 xx.txt, (a work in progress). 2190 [BER] ITU-T Rec. X.690 (07/2002) | ISO/IEC 8825-1:2002, 2191 "Information technology - ASN.1 encoding rules: 2192 Specification of Basic Encoding Rules (BER), Canonical 2193 Encoding Rules (CER) and Distinguished Encoding Rules 2194 (DER)", 2002. 2196 [IP] Postel, J., "Internet Protocol", STD5 and RFC 791, 2197 September 1981 2198 Lightweight Directory Access Protocol Version 3 2200 [ISO10646] Universal Multiple-Octet Coded Character Set (UCS) - 2201 Architecture and Basic Multilingual Plane, ISO/IEC 10646-1 2202 : 1993. 2204 [Keyword] Bradner, S., "Key words for use in RFCs to Indicate 2205 Requirement Levels", RFC 2119, March 1997. 2207 [LDAPDN] Zeilenga, K., "LDAP: String Representation of 2208 Distinguished Names", draft-ietf-ldapbis-dn-xx.txt, (a 2209 work in progress). 2211 [LDAPIANA] Zeilenga, K., "IANA Considerations for LDAP", draft-ietf- 2212 ldapbis-bcp64-xx.txt, (a work in progress). 2214 [LDAPURL] Smith, M., "LDAP: Uniform Resource Locator", draft-ietf- 2215 ldapbis-url-xx.txt, (a work in progress). 2217 [Models] Zeilenga, K., "LDAP: Directory Information Models", draft- 2218 ietf-ldapbis-models-xx.txt (a work in progress). 2220 [Roadmap] Zeilenga, K., "LDAP: Technical Specification Road Map", 2221 draft-ietf-ldapbis-roadmap-xx.txt (a work in progress). 2223 [SASL] Melnikov, A., "Simple Authentication and Security Layer", 2224 draft-ietf-sasl-rfc2222bis-xx.txt (a work in progress). 2226 [SASLPrep] Zeilenga, K., "Stringprep profile for user names and 2227 passwords", draft-ietf-sasl-saslprep-xx.txt, (a work in 2228 progress). 2230 [StringPrep] Hoffman P. and M. Blanchet, "Preparation of 2231 Internationalized Strings ('stringprep')", draft-hoffman- 2232 rfc3454bis-xx.txt, a work in progress. 2234 [Syntaxes] Legg, S., and K. Dally, "LDAP: Syntaxes and Matching 2235 Rules", draft-ietf-ldapbis-syntaxes-xx.txt, (a work in 2236 progress). 2238 [TCP] Postel, J., "Transmission Control Protocol", STD7 and RFC 2239 793, September 1981 2241 [TLS] Dierks, T. and C. Allen. "The TLS Protocol Version 1.1", 2242 draft-ietf-tls-rfc2246-bis-xx.txt, a work in progress. 2244 [Unicode] The Unicode Consortium, "The Unicode Standard, Version 2245 3.2.0" is defined by "The Unicode Standard, Version 3.0" 2246 (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5), 2247 as amended by the "Unicode Standard Annex #27: Unicode 2248 3.1" (http://www.unicode.org/reports/tr27/) and by the 2249 "Unicode Standard Annex #28: Unicode 3.2" 2250 (http://www.unicode.org/reports/tr28/). 2252 Lightweight Directory Access Protocol Version 3 2254 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2255 Resource Identifiers (URI): Generic Syntax", RFC 2396, 2256 August 1998. 2258 [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO 2259 10646", STD63 and RFC3629, November 2003. 2261 [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts, 2262 Models and Service", 1993. 2264 [X.501] ITU-T Rec. X.501, "The Directory: Models", 1993. 2266 [X.511] ITU-T Rec. X.511, "The Directory: Abstract Service 2267 Definition", 1993. 2269 9. Informative References 2271 [Glossary] The Unicode Consortium, "Unicode Glossary", 2272 . 2274 [CharModel] Whistler, K. and M. Davis, "Unicode Technical Report 2275 #17, Character Encoding Model", UTR17, 2276 , August 2277 2000. 2279 [PROTOS-LDAP] University of Oulu, "PROTOS Test-Suite: c06-ldapv3" 2280 2283 [PortReg] IANA, "Port Numbers", 2284 http://www.iana.org/assignments/port-numbers 2286 10. IANA Considerations 2288 It is requested that the Internet Assigned Numbers Authority (IANA) 2289 update the LDAP result code registry to indicate that this document 2290 provides the definitive technical specification for result codes 0- 2291 36, 48-54, 64-70, 80-90. 2293 It is requested that the IANA update the LDAP Protocol Mechanism 2294 registry to indicate that this document and [AuthMeth] provides the 2295 definitive technical specification for the StartTLS 2296 (1.3.6.1.4.1.1466.20037) Extended operation. 2298 It is requested that the IANA update the occurrence of "RFC XXXX" in 2299 Appendix B with this RFC number at publication. 2301 11. Editor's Address 2303 Jim Sermersheim 2304 Novell, Inc. 2306 Lightweight Directory Access Protocol Version 3 2308 1800 South Novell Place 2309 Provo, Utah 84606, USA 2310 jimse@novell.com 2311 +1 801 861-3088 2312 Lightweight Directory Access Protocol Version 3 2314 Appendix A - LDAP Result Codes 2316 This normative appendix details additional considerations regarding 2317 LDAP result codes and provides a brief, general description of each 2318 LDAP result code enumerated in Section 4.1.9. 2320 Additional result codes MAY be defined for use with extensions 2321 [LDAPIANA]. Client implementations SHALL treat any result code which 2322 they do not recognize as an unknown error condition. 2324 Servers may substitute some result codes due to access controls which 2325 prevent their disclosure. 2327 A.1 Non-Error Result Codes 2329 These result codes (called "non-error" result codes) do not indicate 2330 an error condition: 2331 success (0), 2332 compareFalse (5), 2333 compareTrue (6), 2334 referral (10), and 2335 saslBindInProgress (14). 2337 The success, compareTrue, and compareFalse result codes indicate 2338 successful completion (and, hence, are referred to as "successful" 2339 result codes). 2341 The referral and saslBindInProgress result codes indicate the client 2342 needs to take additional action to complete the operation. 2344 A.2 Result Codes 2346 Existing LDAP result codes are described as follows: 2348 success (0) 2349 Indicates the successful completion of an operation. Note: 2350 this code is not used with the Compare operation. See 2351 compareFalse (5) and compareTrue (6). 2353 operationsError (1) 2354 Indicates that the operation is not properly sequenced with 2355 relation to other operations (of same or different type). 2357 For example, this code is returned if the client attempts to 2358 StartTLS [TLS] while there are other uncompleted operations 2359 or if a TLS layer was already installed. 2361 protocolError (2) 2362 Indicates the server received data which is not well-formed. 2364 Lightweight Directory Access Protocol Version 3 2366 For Bind operation only, this code is also used to indicate 2367 that the server does not support the requested protocol 2368 version. 2370 For Extended operations only, this code is also used to 2371 indicate that the server does not support (by design or 2372 configuration) the Extended operation associated with the 2373 requestName. 2375 For request operations specifying multiple controls, this may 2376 be used to indicate that the server cannot ignore the order 2377 of the controls as specified, or that the combination of the 2378 specified controls is invalid or unspecified. 2380 timeLimitExceeded (3) 2381 Indicates that the time limit specified by the client was 2382 exceeded before the operation could be completed. 2384 sizeLimitExceeded (4) 2385 Indicates that the size limit specified by the client was 2386 exceeded before the operation could be completed. 2388 compareFalse (5) 2389 Indicates that the Compare operation has successfully 2390 completed and the assertion has evaluated to FALSE or 2391 Undefined. 2393 compareTrue (6) 2394 Indicates that the Compare operation has successfully 2395 completed and the assertion has evaluated to TRUE. 2397 authMethodNotSupported (7) 2398 Indicates that the authentication method or mechanism is not 2399 supported. 2401 strongerAuthRequired (8) 2402 Indicates the server requires strong(er) authentication in 2403 order to complete the operation. 2405 When used with the Notice of Disconnection operation, this 2406 code indicates that the server has detected that an 2407 established security association between the client and 2408 server has unexpectedly failed or been compromised. 2410 referral (10) 2411 Indicates that a referral needs to be chased to complete the 2412 operation (see Section 4.1.10). 2414 adminLimitExceeded (11) 2415 Indicates that an administrative limit has been exceeded. 2417 unavailableCriticalExtension (12) 2418 Indicates a critical control is unrecognized (see Section 2419 4.1.11). 2421 Lightweight Directory Access Protocol Version 3 2423 confidentialityRequired (13) 2424 Indicates that data confidentiality protections are required. 2426 saslBindInProgress (14) 2427 Indicates the server requires the client to send a new bind 2428 request, with the same SASL mechanism, to continue the 2429 authentication process (see Section 4.2). 2431 noSuchAttribute (16) 2432 Indicates that the named entry does not contain the specified 2433 attribute or attribute value. 2435 undefinedAttributeType (17) 2436 Indicates that a request field contains an unrecognized 2437 attribute description. 2439 inappropriateMatching (18) 2440 Indicates that an attempt was made (e.g. in an assertion) to 2441 use a matching rule not defined for the attribute type 2442 concerned. 2444 constraintViolation (19) 2445 Indicates that the client supplied an attribute value which 2446 does not conform to the constraints placed upon it by the 2447 data model. 2449 For example, this code is returned when multiple values are 2450 supplied to an attribute which has a SINGLE-VALUE constraint. 2452 attributeOrValueExists (20) 2453 Indicates that the client supplied an attribute or value to 2454 be added to an entry, but the attribute or value already 2455 exists. 2457 invalidAttributeSyntax (21) 2458 Indicates that a purported attribute value does not conform 2459 to the syntax of the attribute. 2461 noSuchObject (32) 2462 Indicates that the object does not exist in the DIT. 2464 aliasProblem (33) 2465 Indicates that an alias problem has occurred. For example, 2466 the code may used to indicate an alias has been dereferenced 2467 which names no object. 2469 invalidDNSyntax (34) 2470 Indicates that an LDAPDN or RelativeLDAPDN field (e.g. search 2471 base, target entry, ModifyDN newrdn, etc.) of a request does 2472 not conform to the required syntax or contains attribute 2473 values which do not conform to the syntax of the attribute's 2474 type. 2476 Lightweight Directory Access Protocol Version 3 2478 aliasDereferencingProblem (36) 2479 Indicates that a problem occurred while dereferencing an 2480 alias. Typically an alias was encountered in a situation 2481 where it was not allowed or where access was denied. 2483 inappropriateAuthentication (48) 2484 Indicates the server requires the client which had attempted 2485 to bind anonymously or without supplying credentials to 2486 provide some form of credentials. 2488 invalidCredentials (49) 2489 Indicates that the provided credentials (e.g. the user's name 2490 and password) are invalid. 2492 insufficientAccessRights (50) 2493 Indicates that the client does not have sufficient access 2494 rights to perform the operation. 2496 busy (51) 2497 Indicates that the server is too busy to service the 2498 operation. 2500 unavailable (52) 2501 Indicates that the server is shutting down or a subsystem 2502 necessary to complete the operation is offline. 2504 unwillingToPerform (53) 2505 Indicates that the server is unwilling to perform the 2506 operation. 2508 loopDetect (54) 2509 Indicates that the server has detected an internal loop (e.g. 2510 while dereferencing aliases or chaining an operation). 2512 namingViolation (64) 2513 Indicates that the entry's name violates naming restrictions. 2515 objectClassViolation (65) 2516 Indicates that the entry violates object class restrictions. 2518 notAllowedOnNonLeaf (66) 2519 Indicates that the operation is inappropriately acting upon a 2520 non-leaf entry. 2522 notAllowedOnRDN (67) 2523 Indicates that the operation is inappropriately attempting to 2524 remove a value which forms the entry's relative distinguished 2525 name. 2527 entryAlreadyExists (68) 2528 Indicates that the request cannot be fulfilled (added, moved, 2529 or renamed) as the target entry already exists. 2531 objectClassModsProhibited (69) 2532 Lightweight Directory Access Protocol Version 3 2534 Indicates that an attempt to modify the object class(es) of 2535 an entry's 'objectClass' attribute is prohibited. 2537 For example, this code is returned when a client attempts to 2538 modify the structural object class of an entry. 2540 affectsMultipleDSAs (71) 2541 Indicates that the operation cannot be performed as it would 2542 affect multiple servers (DSAs). 2544 other (80) 2545 Indicates the server has encountered an internal error. 2547 Lightweight Directory Access Protocol Version 3 2549 Appendix B - Complete ASN.1 Definition 2551 This appendix is normative. 2553 Lightweight-Directory-Access-Protocol-V3 2554 -- Copyright (C) The Internet Society (2004). This version of 2555 -- this ASN.1 module is part of RFC XXXX; see the RFC itself 2556 -- for full legal notices. 2557 DEFINITIONS 2558 IMPLICIT TAGS 2559 EXTENSIBILITY IMPLIED ::= 2561 BEGIN 2563 LDAPMessage ::= SEQUENCE { 2564 messageID MessageID, 2565 protocolOp CHOICE { 2566 bindRequest BindRequest, 2567 bindResponse BindResponse, 2568 unbindRequest UnbindRequest, 2569 searchRequest SearchRequest, 2570 searchResEntry SearchResultEntry, 2571 searchResDone SearchResultDone, 2572 searchResRef SearchResultReference, 2573 modifyRequest ModifyRequest, 2574 modifyResponse ModifyResponse, 2575 addRequest AddRequest, 2576 addResponse AddResponse, 2577 delRequest DelRequest, 2578 delResponse DelResponse, 2579 modDNRequest ModifyDNRequest, 2580 modDNResponse ModifyDNResponse, 2581 compareRequest CompareRequest, 2582 compareResponse CompareResponse, 2583 abandonRequest AbandonRequest, 2584 extendedReq ExtendedRequest, 2585 extendedResp ExtendedResponse, 2586 ..., 2587 intermediateResponse IntermediateResponse }, 2588 controls [0] Controls OPTIONAL } 2590 MessageID ::= INTEGER (0 .. maxInt) 2592 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) -- 2594 LDAPString ::= OCTET STRING -- UTF-8 encoded, 2595 -- [ISO10646] characters 2597 LDAPOID ::= OCTET STRING -- Constrained to [Models] 2599 LDAPDN ::= LDAPString -- Constrained to 2600 -- [LDAPDN] 2602 RelativeLDAPDN ::= LDAPString -- Constrained to 2603 Lightweight Directory Access Protocol Version 3 2605 -- [LDAPDN] 2607 AttributeDescription ::= LDAPString 2608 -- Constrained to 2609 -- [Models] 2611 AttributeValue ::= OCTET STRING 2613 AttributeValueAssertion ::= SEQUENCE { 2614 attributeDesc AttributeDescription, 2615 assertionValue AssertionValue } 2617 AssertionValue ::= OCTET STRING 2619 PartialAttribute ::= SEQUENCE { 2620 type AttributeDescription, 2621 vals SET OF value AttributeValue } 2623 Attribute ::= PartialAttribute(WITH COMPONENTS { 2624 ..., 2625 vals (SIZE(1..MAX))}) 2627 MatchingRuleId ::= LDAPString 2629 LDAPResult ::= SEQUENCE { 2630 resultCode ENUMERATED { 2631 success (0), 2632 operationsError (1), 2633 protocolError (2), 2634 timeLimitExceeded (3), 2635 sizeLimitExceeded (4), 2636 compareFalse (5), 2637 compareTrue (6), 2638 authMethodNotSupported (7), 2639 strongerAuthRequired (8), 2640 -- 9 reserved -- 2641 referral (10), 2642 adminLimitExceeded (11), 2643 unavailableCriticalExtension (12), 2644 confidentialityRequired (13), 2645 saslBindInProgress (14), 2646 noSuchAttribute (16), 2647 undefinedAttributeType (17), 2648 inappropriateMatching (18), 2649 constraintViolation (19), 2650 attributeOrValueExists (20), 2651 invalidAttributeSyntax (21), 2652 -- 22-31 unused -- 2653 noSuchObject (32), 2654 aliasProblem (33), 2655 invalidDNSyntax (34), 2656 -- 35 reserved for undefined isLeaf -- 2657 aliasDereferencingProblem (36), 2658 -- 37-47 unused -- 2660 Lightweight Directory Access Protocol Version 3 2662 inappropriateAuthentication (48), 2663 invalidCredentials (49), 2664 insufficientAccessRights (50), 2665 busy (51), 2666 unavailable (52), 2667 unwillingToPerform (53), 2668 loopDetect (54), 2669 -- 55-63 unused -- 2670 namingViolation (64), 2671 objectClassViolation (65), 2672 notAllowedOnNonLeaf (66), 2673 notAllowedOnRDN (67), 2674 entryAlreadyExists (68), 2675 objectClassModsProhibited (69), 2676 -- 70 reserved for CLDAP -- 2677 affectsMultipleDSAs (71), 2678 -- 72-79 unused -- 2679 other (80), 2680 ... }, 2681 matchedDN LDAPDN, 2682 diagnosticMessage LDAPString, 2683 referral [3] Referral OPTIONAL } 2685 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI 2687 URI ::= LDAPString -- limited to characters permitted in 2688 -- URIs 2690 Controls ::= SEQUENCE OF control Control 2692 Control ::= SEQUENCE { 2693 controlType LDAPOID, 2694 criticality BOOLEAN DEFAULT FALSE, 2695 controlValue OCTET STRING OPTIONAL } 2697 BindRequest ::= [APPLICATION 0] SEQUENCE { 2698 version INTEGER (1 .. 127), 2699 name LDAPDN, 2700 authentication AuthenticationChoice } 2702 AuthenticationChoice ::= CHOICE { 2703 simple [0] OCTET STRING, 2704 -- 1 and 2 reserved 2705 sasl [3] SaslCredentials, 2706 ... } 2708 SaslCredentials ::= SEQUENCE { 2709 mechanism LDAPString, 2710 credentials OCTET STRING OPTIONAL } 2712 BindResponse ::= [APPLICATION 1] SEQUENCE { 2713 COMPONENTS OF LDAPResult, 2714 serverSaslCreds [7] OCTET STRING OPTIONAL } 2715 Lightweight Directory Access Protocol Version 3 2717 UnbindRequest ::= [APPLICATION 2] NULL 2719 SearchRequest ::= [APPLICATION 3] SEQUENCE { 2720 baseObject LDAPDN, 2721 scope ENUMERATED { 2722 baseObject (0), 2723 singleLevel (1), 2724 wholeSubtree (2), 2725 ... }, 2726 derefAliases ENUMERATED { 2727 neverDerefAliases (0), 2728 derefInSearching (1), 2729 derefFindingBaseObj (2), 2730 derefAlways (3) }, 2731 sizeLimit INTEGER (0 .. maxInt), 2732 timeLimit INTEGER (0 .. maxInt), 2733 typesOnly BOOLEAN, 2734 filter Filter, 2735 attributes AttributeSelection } 2737 AttributeSelection ::= SEQUENCE OF selector LDAPString 2738 -- The LDAPString is constrained to 2739 -- in Section 4.5.1.7 2741 Filter ::= CHOICE { 2742 and [0] SET SIZE (1..MAX) OF filter Filter, 2743 or [1] SET SIZE (1..MAX) OF filter Filter, 2744 not [2] Filter, 2745 equalityMatch [3] AttributeValueAssertion, 2746 substrings [4] SubstringFilter, 2747 greaterOrEqual [5] AttributeValueAssertion, 2748 lessOrEqual [6] AttributeValueAssertion, 2749 present [7] AttributeDescription, 2750 approxMatch [8] AttributeValueAssertion, 2751 extensibleMatch [9] MatchingRuleAssertion, 2752 ... } 2754 SubstringFilter ::= SEQUENCE { 2755 type AttributeDescription, 2756 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE { 2757 initial [0] AssertionValue, -- can occur at most once 2758 any [1] AssertionValue, 2759 final [2] AssertionValue } -- can occur at most once 2760 } 2762 MatchingRuleAssertion ::= SEQUENCE { 2763 matchingRule [1] MatchingRuleId OPTIONAL, 2764 type [2] AttributeDescription OPTIONAL, 2765 matchValue [3] AssertionValue, 2766 dnAttributes [4] BOOLEAN DEFAULT FALSE } 2768 SearchResultEntry ::= [APPLICATION 4] SEQUENCE { 2769 objectName LDAPDN, 2770 attributes PartialAttributeList } 2771 Lightweight Directory Access Protocol Version 3 2773 PartialAttributeList ::= SEQUENCE OF 2774 partialAttribute PartialAttribute 2776 SearchResultReference ::= [APPLICATION 19] SEQUENCE 2777 SIZE (1..MAX) OF uri URI 2779 SearchResultDone ::= [APPLICATION 5] LDAPResult 2781 ModifyRequest ::= [APPLICATION 6] SEQUENCE { 2782 object LDAPDN, 2783 changes SEQUENCE OF change SEQUENCE { 2784 operation ENUMERATED { 2785 add (0), 2786 delete (1), 2787 replace (2), 2788 ... }, 2789 modification PartialAttribute } } 2791 ModifyResponse ::= [APPLICATION 7] LDAPResult 2793 AddRequest ::= [APPLICATION 8] SEQUENCE { 2794 entry LDAPDN, 2795 attributes AttributeList } 2797 AttributeList ::= SEQUENCE OF attribute Attribute 2799 AddResponse ::= [APPLICATION 9] LDAPResult 2801 DelRequest ::= [APPLICATION 10] LDAPDN 2803 DelResponse ::= [APPLICATION 11] LDAPResult 2805 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE { 2806 entry LDAPDN, 2807 newrdn RelativeLDAPDN, 2808 deleteoldrdn BOOLEAN, 2809 newSuperior [0] LDAPDN OPTIONAL } 2811 ModifyDNResponse ::= [APPLICATION 13] LDAPResult 2813 CompareRequest ::= [APPLICATION 14] SEQUENCE { 2814 entry LDAPDN, 2815 ava AttributeValueAssertion } 2817 CompareResponse ::= [APPLICATION 15] LDAPResult 2819 AbandonRequest ::= [APPLICATION 16] MessageID 2821 ExtendedRequest ::= [APPLICATION 23] SEQUENCE { 2822 requestName [0] LDAPOID, 2823 requestValue [1] OCTET STRING OPTIONAL } 2825 ExtendedResponse ::= [APPLICATION 24] SEQUENCE { 2826 Lightweight Directory Access Protocol Version 3 2828 COMPONENTS OF LDAPResult, 2829 responseName [10] LDAPOID OPTIONAL, 2830 responseValue [11] OCTET STRING OPTIONAL } 2832 IntermediateResponse ::= [APPLICATION 25] SEQUENCE { 2833 responseName [0] LDAPOID OPTIONAL, 2834 responseValue [1] OCTET STRING OPTIONAL } 2836 END 2837 Lightweight Directory Access Protocol Version 3 2839 Appendix C - Changes 2841 This appendix is non-normative. 2843 This appendix summarizes substantive changes made to RFC 2251, RFC 2844 2830, and RFC 3771. 2846 C.1 Changes made to RFC 2251: 2848 This section summarizes the substantive changes made to Sections 1, 2849 2, 3.1, and 4 through the remainder of RFC 2251. Readers should 2850 consult [Models] and [AuthMeth] for summaries of changes to other 2851 sections. 2853 C.1.1 Section 1 (Status of this Memo) 2855 - Removed IESG note. Post publication of RFC 2251, mandatory LDAP 2856 authentication mechanisms have been standardized which are 2857 sufficient to remove this note. See [AuthMeth] for authentication 2858 mechanisms. 2860 C.1.2 Section 3.1 (Protocol Model) and others 2862 - Removed notes giving history between LDAP v1, v2 and v3. Instead, 2863 added sufficient language so that this document can stand on its 2864 own. 2866 C.1.3 Section 4 (Elements of Protocol) 2868 - Clarified where the extensibility features of ASN.1 apply to the 2869 protocol. This change affected various ASN.1 types by the 2870 inclusion of ellipses (...) to certain elements. 2871 - Removed the requirement that servers which implement version 3 or 2872 later MUST provide the 'supportedLDAPVersion' attribute. This 2873 statement provided no interoperability advantages. 2875 C.1.4 Section 4.1.1 (Message Envelope) 2877 - There was a mandatory requirement for the server to return a 2878 Notice of Disconnection and drop the transport connection when a 2879 PDU is malformed in a certain way. This has been updated such that 2880 the server SHOULD return the Notice of Disconnection, and MUST 2881 terminate the LDAP Session. 2883 C.1.5 Section 4.1.1.1 (Message ID) 2885 - Required that the messageID of requests MUST be non-zero as the 2886 zero is reserved for Notice of Disconnection. 2888 Lightweight Directory Access Protocol Version 3 2890 - Specified when it is and isn't appropriate to return an already 2891 used message id. RFC 2251 accidentally imposed synchronous server 2892 behavior in its wording of this. 2894 C.1.6 Section 4.1.2 (String Types) 2896 - Stated that LDAPOID is constrained to from [Models]. 2898 C.1.7 Section 4.1.5.1 (Binary Option) and others 2900 - Removed the Binary Option from the specification. There are 2901 numerous interoperability problems associated with this method of 2902 alternate attribute type encoding. Work to specify a suitable 2903 replacement is ongoing. 2905 C.1.8 Section 4.1.8 (Attribute) 2907 - Combined the definitions of PartialAttribute and Attribute here, 2908 and defined Attribute in terms of PartialAttribute. 2910 C.1.9 Section 4.1.10 (Result Message) 2912 - Renamed "errorMessage" to "diagnosticMessage" as it is allowed to 2913 be sent for non-error results. 2914 - Moved some language into Appendix A, and refer the reader there. 2915 - Allowed matchedDN to be present for other result codes than those 2916 listed in RFC 2251. 2917 - renamed the code "strongAuthRequired" to "strongerAuthRequired" to 2918 clarify that this code may often be returned to indicate that a 2919 stronger authentication is needed to perform a given operation. 2921 C.1.10 Section 4.1.11 (Referral) 2923 - Defined referrals in terms of URIs rather than URLs. 2924 - Removed the requirement that all referral URIs MUST be equally 2925 capable of progressing the operation. The statement was ambiguous 2926 and provided no instructions on how to carry it out. 2927 - Added the requirement that clients MUST NOT loop between servers. 2928 - Clarified the instructions for using LDAPURLs in referrals, and in 2929 doing so added a recommendation that the scope part be present. 2930 - Removed imperatives which required clients to use URLs in specific 2931 ways to progress an operation. These did nothing for 2932 interoperability. 2934 C.1.11 Section 4.1.12 (Controls) 2936 - Specified how control values defined in terms of ASN.1 are to be 2937 encoded. 2939 Lightweight Directory Access Protocol Version 3 2941 - Noted that the criticality field is only applied to request 2942 messages (except UnbindRequest), and must be ignored when present 2943 on response messages and UnbindRequest. 2944 - Added language regarding combinations of controls and the ordering 2945 of controls on a message. 2946 - Specified that when the semantics of the combination of controls 2947 is undefined or unknown, it results in a protocolError. 2948 - Changed "The server MUST be prepared" to "Implementations MUST be 2949 prepared" in the eighth paragraph to reflect that both client and 2950 server implementations must be able to handle this (as both parse 2951 controls). 2953 C.1.12 Section 4.2 (Bind Operation) 2955 - Mandated that servers return protocolError when the version is not 2956 supported. 2957 - Disambiguated behavior when the simple authentication is used, the 2958 name is empty and the password is non-empty. 2959 - Required servers to not dereference aliases for Bind. This was 2960 added for consistency with other operations and to help ensure 2961 data consistency. 2962 - Required that textual passwords be transferred as UTF-8 encoded 2963 Unicode, and added recommendations on string preparation. This was 2964 to help ensure interoperability of passwords being sent from 2965 different clients. 2967 C.1.13 Section 4.2.1 (Sequencing of the Bind Request) 2969 - This section was largely reorganized for readability and language 2970 was added to clarify the authentication state of failed and 2971 abandoned Bind operations. 2972 - Removed: "If a SASL transfer encryption or integrity mechanism has 2973 been negotiated, that mechanism does not support the changing of 2974 credentials from one identity to another, then the client MUST 2975 instead establish a new connection." 2976 If there are dependencies between multiple negotiations of a 2977 particular SASL mechanism, the technical specification for that 2978 SASL mechanism details how applications are to deal with them. 2979 LDAP should not require any special handling. 2980 - Dropped MUST imperative in paragraph 3 to align with [Keywords]. 2981 - Mandated that clients not send non-Bind operations while a Bind is 2982 in progress, and suggested that servers not process them if they 2983 are received. This is needed to ensure proper sequencing of the 2984 Bind in relationship to other operations. 2986 C.1.14 Section 4.2.3 (Bind Response) 2988 - Moved most error-related text to Appendix A, and added text 2989 regarding certain errors used in conjunction with the Bind 2990 operation. 2992 Lightweight Directory Access Protocol Version 3 2994 - Prohibited the server from specifying serverSaslCreds when not 2995 appropriate. 2997 C.1.15 Section 4.3 (Unbind Operation) 2999 - Specified that both peers are to cease transmission and terminate 3000 the LDAP session for the Unbind operation. 3002 C.1.16 Section 4.4 (Unsolicited Notification) 3004 - Added instructions for future specifications of Unsolicited 3005 Notifications. 3007 C.1.17 Section 4.5.1 (Search Request) 3009 - SearchRequest attributes is now defined as an AttributeSelection 3010 type rather than AttributeDescriptionList, and an ABNF is 3011 provided. 3012 - SearchRequest attributes may contain duplicate attribute 3013 descriptions. This was previously prohibited. Now servers are 3014 instructed to ignore subsequent names when they are duplicated. 3015 This was relaxed in order to allow different short names and also 3016 OIDs to be requested for an attribute. 3017 - The Filter choice SubstringFilter substrings type is now defined 3018 with a lower bound of 1. 3019 - The SubstringFilter substrings 'initial, 'any', and 'final' types 3020 are now AssertionValue rather than LDAPString. Also, added 3021 imperatives stating that 'initial' (if present) must be listed 3022 first, and 'final' (if present) must be listed last. 3023 - Disambiguated the semantics of the derefAliases choices. There was 3024 question as to whether derefInSearching applied to the base object 3025 in a wholeSubtree Search. 3026 - Added instructions for equalityMatch, substrings, greaterOrEqual, 3027 lessOrEqual, and approxMatch. 3029 C.1.18 Section 4.5.2 (Search Result) 3031 - Recommended that servers not use attribute short names when it 3032 knows they are ambiguous or may cause interoperability problems. 3033 - Removed all mention of ExtendedResponse due to lack of 3034 implementation. 3036 C.1.19 Section 4.5.3 (Continuation References in the Search Result) 3038 - Made changes similar to those made to Section 4.1.11. 3040 C.1.20 Section 4.5.3.1 (Example) 3041 Lightweight Directory Access Protocol Version 3 3043 - Fixed examples to adhere to changes made to Section 4.5.3. 3045 C.1.21 Section 4.6 (Modify Operation) 3047 - Replaced AttributeTypeAndValues with Attribute as they are 3048 equivalent. 3049 - Specified the types of modification changes which might 3050 temporarily violate schema. Some readers were under the impression 3051 that any temporary schema violation was allowed. 3053 C.1.22 Section 4.7 (Add Operation) 3055 - Aligned Add operation with X.511 in that the attributes of the RDN 3056 are used in conjunction with the listed attributes to create the 3057 entry. Previously, Add required that the distinguished values be 3058 present in the listed attributes. 3059 - Removed requirement that the objectClass attribute MUST be 3060 specified as some DSE types do not require this attribute. 3061 Instead, generic wording was added, requiring the added entry to 3062 adhere to the data model. 3063 - Removed recommendation regarding placement of objects. This is 3064 covered in the data model document. 3066 C.1.23 Section 4.9 (Modify DN Operation) 3068 - Required servers to not dereference aliases for Modify DN. This 3069 was added for consistency with other operations and to help ensure 3070 data consistency. 3071 - Allow Modify DN to fail when moving between naming contexts. 3072 - Specified what happens when the attributes of the newrdn are not 3073 present on the entry. 3075 C.1.24 Section 4.10 (Compare Operation) 3077 - Specified that compareFalse means that the Compare took place and 3078 the result is false. There was confusion which lead people to 3079 believe that an Undefined match resulted in compareFalse. 3080 - Required servers to not dereference aliases for Compare. This was 3081 added for consistency with other operations and to help ensure 3082 data consistency. 3084 C.1.25 Section 4.11 (Abandon Operation) 3086 - Explained that since Abandon returns no response, clients should 3087 not use it if they need to know the outcome. 3088 - Specified that Abandon and Unbind cannot be abandoned. 3090 C.1.26 Section 4.12 (Extended Operation) 3091 Lightweight Directory Access Protocol Version 3 3093 - Specified how values of Extended operations defined in terms of 3094 ASN.1 are to be encoded. 3095 - Added instructions on what Extended operation specifications 3096 consist of. 3097 - Added a recommendation that servers advertise supported Extended 3098 operations. 3100 C.1.27 Section 5.2 (Transfer Protocols) 3102 - Moved referral-specific instructions into referral-related 3103 sections. 3105 C.1.28 Section 7 (Security Considerations) 3107 - Reworded notes regarding SASL not protecting certain aspects of 3108 the LDAP Bind PDUs. 3109 - Noted that Servers are encouraged to prevent directory 3110 modifications by clients that have authenticated anonymously 3111 [AuthMeth]. 3112 - Added a note regarding the scenario where an identity is changed 3113 (deleted, privileges or credentials modified, etc.). 3114 - Warned against following referrals that may have been injected in 3115 the data stream. 3116 - Noted that servers should protect information equally, whether in 3117 an error condition or not, and mentioned specifically; matchedDN, 3118 diagnosticMessage, and resultCodes. 3119 - Added a note regarding malformed and long encodings. 3121 C.1.29 Appendix A (Complete ASN.1 Definition) 3123 - Added "EXTENSIBILITY IMPLIED" to ASN.1 definition. 3124 - Removed AttributeType. It is not used. 3126 C.2 Changes made to RFC 2830: 3128 This section summarizes the substantive changes made to Sections of 3129 RFC 2830. Readers should consult [AuthMeth] for summaries of changes 3130 to other sections. 3132 C.2.1 Section 2.3 (Response other than "success") 3134 - Removed wording indicating that referrals can be returned from 3135 StartTLS. 3136 - Removed requirement that only a narrow set of result codes can be 3137 returned. Some result codes are required in certain scenarios, but 3138 any other may be returned if appropriate. 3140 Lightweight Directory Access Protocol Version 3 3142 C.2.1 Section 4 (Closing a TLS Connection) 3144 - Reworded most of this section and added the requirement that after 3145 the TLS connection has been closed, the server MUST NOT send 3146 responses to any request message received before the TLS closure. 3147 - Removed instructions on abrupt closure as this is covered in other 3148 areas of the document (specifically, Section 5.3) 3150 C.3 Changes made to RFC 3771: 3152 - Rewrote to fit into this document. In general, semantics were 3153 preserved. Supporting and background language seen as redundant 3154 due to its presence in this document was omitted. 3155 - Specified that Intermediate responses to a request may be of 3156 different types, and one of the response types may be specified to 3157 have no response value. 3159 Lightweight Directory Access Protocol Version 3 3161 Intellectual Property Statement 3163 The IETF takes no position regarding the validity or scope of any 3164 Intellectual Property Rights or other rights that might be claimed to 3165 pertain to the implementation or use of the technology described in 3166 this document or the extent to which any license under such rights 3167 might or might not be available; nor does it represent that it has 3168 made any independent effort to identify any such rights. Information 3169 on the procedures with respect to rights in RFC documents can be 3170 found in BCP 78 and BCP 79. 3172 Copies of IPR disclosures made to the IETF Secretariat and any 3173 assurances of licenses to be made available, or the result of an 3174 attempt made to obtain a general license or permission for the use of 3175 such proprietary rights by implementers or users of this 3176 specification can be obtained from the IETF on-line IPR repository at 3177 . 3179 The IETF invites any interested party to bring to its attention any 3180 copyrights, patents or patent applications, or other proprietary 3181 rights that may cover technology that may be required to implement 3182 this standard. Please address the information to the IETF at ietf- 3183 ipr@ietf.org. 3185 Disclaimer of Validity 3187 This document and the information contained herein are provided on an 3188 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 3189 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 3190 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 3191 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 3192 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 3193 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3195 Copyright Statement 3197 Copyright (C) The Internet Society (2004). This document is subject 3198 to the rights, licenses and restrictions contained in BCP 78, and 3199 except as set forth therein, the authors retain all their rights. 3201 Acknowledgement 3203 Funding for the RFC Editor function is currently provided by the 3204 Internet Society.