idnits 2.17.1 draft-ietf-ldapbis-protocol-28.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 3207. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 3184. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 3197. ** Found boilerplate matching RFC 3978, Section 5.4, paragraph 1 (on line 3213), 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? == The page length should not exceed 58 lines per page, but there was 58 longer pages, the longest (page 2) being 59 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 62 pages 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 (Nov 2004) is 7101 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 2849 -- Looks like a reference, but probably isn't: '3' on line 2779 == Missing Reference: 'APPLICATION 0' is mentioned on line 2710, but not defined == Missing Reference: 'SASLprep' is mentioned on line 794, but not defined == Missing Reference: 'Stringprep' is mentioned on line 794, but not defined == Missing Reference: 'APPLICATION 1' is mentioned on line 2725, but not defined -- Looks like a reference, but probably isn't: '7' on line 2763 == Missing Reference: 'APPLICATION 2' is mentioned on line 2731, but not defined == Missing Reference: 'APPLICATION 3' is mentioned on line 2733, but not defined -- Looks like a reference, but probably isn't: '1' on line 2850 -- Looks like a reference, but probably isn't: '2' on line 2778 -- Looks like a reference, but probably isn't: '4' on line 2780 -- Looks like a reference, but probably isn't: '5' on line 2761 -- Looks like a reference, but probably isn't: '6' on line 2762 -- Looks like a reference, but probably isn't: '8' on line 2764 -- Looks like a reference, but probably isn't: '9' on line 2765 == Missing Reference: 'APPLICATION 4' is mentioned on line 2782, but not defined == Missing Reference: 'APPLICATION 19' is mentioned on line 2791, but not defined == Missing Reference: 'APPLICATION 5' is mentioned on line 2794, but not defined == Missing Reference: 'APPLICATION 6' is mentioned on line 2796, but not defined == Missing Reference: 'APPLICATION 7' is mentioned on line 2806, but not defined == Missing Reference: 'APPLICATION 8' is mentioned on line 2808, but not defined == Missing Reference: 'APPLICATION 9' is mentioned on line 2814, but not defined == Missing Reference: 'APPLICATION 10' is mentioned on line 2816, but not defined == Missing Reference: 'APPLICATION 11' is mentioned on line 2818, but not defined == Missing Reference: 'APPLICATION 12' is mentioned on line 2820, but not defined == Missing Reference: 'APPLICATION 13' is mentioned on line 2826, but not defined == Missing Reference: 'APPLICATION 14' is mentioned on line 2828, but not defined == Missing Reference: 'APPLICATION 15' is mentioned on line 2832, but not defined == Missing Reference: 'APPLICATION 16' is mentioned on line 2834, but not defined == Missing Reference: 'APPLICATION 23' is mentioned on line 2836, but not defined == Missing Reference: 'APPLICATION 24' is mentioned on line 2840, but not defined -- Looks like a reference, but probably isn't: '10' on line 2845 -- Looks like a reference, but probably isn't: '11' on line 2846 == Missing Reference: 'APPLICATION 25' is mentioned on line 2848, but not defined == Missing Reference: 'Keywords' is mentioned on line 2994, but not defined == Unused Reference: 'IP' is defined on line 2208, but no explicit reference was found in the text == Unused Reference: 'SASLPrep' is defined on line 2239, but no explicit reference was found in the text == Unused Reference: 'StringPrep' is defined on line 2243, 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 (~~), 35 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-28.txt Nov 2004 4 Obsoletes: RFCs 2251, 2830, 3771 6 LDAP: The Protocol 8 Status of this Memo 10 This document is an Internet-Draft and is subject to all provisions 11 of section 3 of RFC 3667. By submitting this Internet-Draft, each 12 author represents that any applicable patent or other IPR claims of 13 which he or she is aware have been or will be disclosed, and any of 14 which he or she become aware will be disclosed, in accordance with 15 RFC 3668. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 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 Obsolete Specifications.......................3 58 2. Conventions.....................................................3 59 3. Protocol Model..................................................4 60 3.1 Operation and LDAP Exchange 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.5. Search Operation.............................................18 78 4.6. Modify Operation.............................................28 79 4.7. Add Operation................................................29 80 4.8. Delete Operation.............................................30 81 4.9. Modify DN Operation..........................................31 82 4.10. Compare Operation...........................................32 83 4.11. Abandon Operation...........................................33 84 4.12. Extended Operation..........................................34 85 4.13. IntermediateResponse Message................................35 86 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse......36 87 4.13.2. Usage with LDAP Request Controls..........................36 88 4.14. StartTLS Operation..........................................36 89 5. Protocol Encoding, Connection, and Transfer....................38 90 5.2. Protocol Encoding............................................39 91 5.3. Transmission Control Protocol (TCP)..........................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....................................44 99 A.1 Non-Error Result Codes........................................44 100 A.2 Result Codes..................................................44 101 Appendix B - Complete ASN.1 Definition............................49 102 Appendix C - Changes..............................................55 103 C.1 Changes made to RFC 2251:.....................................55 104 C.2 Changes made to RFC 2830:.....................................60 105 C.3 Changes made to RFC 3771:.....................................61 107 Lightweight Directory Access Protocol Version 3 109 1. Introduction 111 The Directory is "a collection of open systems cooperating to provide 112 directory services" [X.500]. A directory user, which may be a human 113 or other entity, accesses the Directory through a client (or 114 Directory User Agent (DUA)). The client, on behalf of the directory 115 user, interacts with one or more servers (or Directory System Agents 116 (DSA)). Clients interact with servers using a directory access 117 protocol. 119 This document details the protocol elements of the Lightweight 120 Directory Access Protocol (LDAP), along with their semantics. 121 Following the description of protocol elements, it describes the way 122 in which the protocol elements are encoded and transferred. 124 1.1. Relationship to Other LDAP Specifications 126 This document is an integral part of the LDAP Technical Specification 127 [Roadmap] which obsoletes the previously defined LDAP technical 128 specification, RFC 3377, in its entirety. 130 This document obsoletes all of RFC 2251 except the following: 131 Sections 3.2, 3.4, 4.1.3 (last paragraph), 4.1.4, 4.1.5, 4.1.5.1, 132 4.1.9 (last paragraph), 5.1, 6.1, and 6.2 (last paragraph) are 133 obsoleted by [Models]. 134 Section 3.3 is obsoleted by [Roadmap]. 135 Sections 4.2.1 (portions), and 4.2.2 are obsoleted by [AuthMeth]. 137 Appendix C.1 summarizes substantive changes to the remaining 138 sections. 140 This document obsoletes RFC 2830, Sections 2 and 4 in entirety. The 141 remainder of RFC 2830 is obsoleted by [AuthMeth]. Appendix C.2 142 summarizes substantive changes to the remaining sections. 144 This document also obsoletes RFC 3771 in entirety. 146 2. Conventions 148 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 149 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are 150 to be interpreted as described in [Keyword]. 152 Character names in this document use the notation for code points and 153 names from the Unicode Standard [Unicode]. For example, the letter 154 "a" may be represented as either or . 156 Note: a glossary of terms used in Unicode can be found in [Glossary]. 157 Information on the Unicode character encoding model can be found in 158 [CharModel]. 160 Lightweight Directory Access Protocol Version 3 162 The term "transport connection" refers to the underlying transport 163 services used to carry the protocol exchange, as well as associations 164 established by these services. 166 The term "TLS layer" refers to TLS services used in providing 167 security services, as well as associations established by these 168 services. 170 The term "SASL layer" refers to SASL services used in providing 171 security services, as well as associations established by these 172 services. 174 The term "LDAP message layer" refers to the LDAP Message (PDU) 175 services used in providing directory services, as well as 176 associations established by these services. 178 The term "LDAP session" refers to combined services (transport 179 connection, TLS layer, SASL layer, LDAP message layer) and their 180 associations. 182 See the table in Section 5 for an illustration of these four terms. 184 3. Protocol Model 186 The general model adopted by this protocol is one of clients 187 performing protocol operations against servers. In this model, a 188 client transmits a protocol request describing the operation to be 189 performed to a server. The server is then responsible for performing 190 the necessary operation(s) in the Directory. Upon completion of an 191 operation, the server typically returns a response containing 192 appropriate data to the requesting client. 194 Protocol operations are generally independent of one another. Each 195 operation is processed as an atomic action, leaving the directory in 196 a consistent state. 198 Although servers are required to return responses whenever such 199 responses are defined in the protocol, there is no requirement for 200 synchronous behavior on the part of either clients or servers. 201 Requests and responses for multiple operations generally may be 202 exchanged between a client and server in any order. If required, 203 synchronous behavior may be controlled by client applications. 205 The core protocol operations defined in this document can be mapped 206 to a subset of the X.500 (1993) Directory Abstract Service [X.511]. 207 However there is not a one-to-one mapping between LDAP operations and 208 X.500 Directory Access Protocol (DAP) operations. Server 209 implementations acting as a gateway to X.500 directories may need to 210 make multiple DAP requests to service a single LDAP request. 212 3.1 Operation and LDAP Message Layer Relationship 214 Lightweight Directory Access Protocol Version 3 216 Protocol operations are exchanged at the LDAP message layer. When the 217 transport connection is closed, any uncompleted operations at the 218 LDAP message layer, when possible, are abandoned, and when not 219 possible, are completed without transmission of the response. Also, 220 when the transport connection is closed, the client MUST NOT assume 221 that any uncompleted update operations have succeeded or failed. 223 4. Elements of Protocol 225 The protocol is described using Abstract Syntax Notation One 226 ([ASN.1]), and is transferred using a subset of ASN.1 Basic Encoding 227 Rules ([BER]). Section 5 specifies how the protocol elements are 228 encoded and transferred. 230 In order to support future extensions to this protocol, extensibility 231 is implied where it is allowed per ASN.1 (i.e. sequence, set, choice, 232 and enumerated types are extensible). In addition, ellipses (...) 233 have been supplied in ASN.1 types that are explicitly extensible as 234 discussed in [LDAPIANA]. Because of the implied extensibility, 235 clients and servers MUST (unless otherwise specified) ignore trailing 236 SEQUENCE components whose tags they do not recognize. 238 Changes to the protocol other than through the extension mechanisms 239 described here require a different version number. A client indicates 240 the version it is using as part of the BindRequest, described in 241 Section 4.2. If a client has not sent a Bind, the server MUST assume 242 the client is using version 3 or later. 244 Clients may attempt to determine the protocol versions a server 245 supports by reading the 'supportedLDAPVersion' attribute from the 246 root DSE (DSA-Specific Entry) [Models]. 248 4.1. Common Elements 250 This section describes the LDAPMessage envelope Protocol Data Unit 251 (PDU) format, as well as data type definitions, which are used in the 252 protocol operations. 254 4.1.1. Message Envelope 256 For the purposes of protocol exchanges, all protocol operations are 257 encapsulated in a common envelope, the LDAPMessage, which is defined 258 as follows: 260 LDAPMessage ::= SEQUENCE { 261 messageID MessageID, 262 protocolOp CHOICE { 263 bindRequest BindRequest, 264 bindResponse BindResponse, 265 unbindRequest UnbindRequest, 266 searchRequest SearchRequest, 268 Lightweight Directory Access Protocol Version 3 270 searchResEntry SearchResultEntry, 271 searchResDone SearchResultDone, 272 searchResRef SearchResultReference, 273 modifyRequest ModifyRequest, 274 modifyResponse ModifyResponse, 275 addRequest AddRequest, 276 addResponse AddResponse, 277 delRequest DelRequest, 278 delResponse DelResponse, 279 modDNRequest ModifyDNRequest, 280 modDNResponse ModifyDNResponse, 281 compareRequest CompareRequest, 282 compareResponse CompareResponse, 283 abandonRequest AbandonRequest, 284 extendedReq ExtendedRequest, 285 extendedResp ExtendedResponse, 286 ..., 287 intermediateResponse IntermediateResponse }, 288 controls [0] Controls OPTIONAL } 290 MessageID ::= INTEGER (0 .. maxInt) 292 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) -- 294 The ASN.1 type Controls is defined in Section 4.1.11. 296 The function of the LDAPMessage is to provide an envelope containing 297 common fields required in all protocol exchanges. At this time the 298 only common fields are the messageID and the controls. 300 If the server receives a PDU from the client in which the LDAPMessage 301 SEQUENCE tag cannot be recognized, the messageID cannot be parsed, 302 the tag of the protocolOp is not recognized as a request, or the 303 encoding structures or lengths of data fields are found to be 304 incorrect, then the server SHOULD return the Notice of Disconnection 305 described in Section 4.4.1, with the resultCode set to protocolError, 306 and MUST immediately close the transport connection. 308 In other cases where the client or server cannot parse a PDU, it 309 SHOULD abruptly close the transport connection where further 310 communication (including providing notice) would be 311 pernicious. Otherwise, server implementations MUST return an 312 appropriate response to the request, with the resultCode set to 313 protocolError. 315 4.1.1.1. Message ID 317 All LDAPMessage envelopes encapsulating responses contain the 318 messageID value of the corresponding request LDAPMessage. 320 The message ID of a request MUST have a non-zero value different from 321 the messageID of any other request in progress in the same LDAP 323 Lightweight Directory Access Protocol Version 3 325 session. The zero value is reserved for the unsolicited notification 326 message. 328 Typical clients increment a counter for each request. 330 A client MUST NOT send a request with the same message ID as an 331 earlier request in the same LDAP session unless it can be determined 332 that the server is no longer servicing the earlier request (e.g. 333 after the final response is received, or a subsequent Bind 334 completes). Otherwise the behavior is undefined. For this purpose, 335 note that Abandon and successfully abandoned operations do not send 336 responses. 338 4.1.2. String Types 340 The LDAPString is a notational convenience to indicate that, although 341 strings of LDAPString type encode as ASN.1 OCTET STRING types, the 342 [ISO10646] character set (a superset of [Unicode]) is used, encoded 343 following the [UTF-8] algorithm. Note that Unicode characters U+0000 344 through U+007F are the same as ASCII 0 through 127, respectively, and 345 have the same single octet UTF-8 encoding. Other Unicode characters 346 have a multiple octet UTF-8 encoding. 348 LDAPString ::= OCTET STRING -- UTF-8 encoded, 349 -- [ISO10646] characters 351 The LDAPOID is a notational convenience to indicate that the 352 permitted value of this string is a (UTF-8 encoded) dotted-decimal 353 representation of an OBJECT IDENTIFIER. Although an LDAPOID is 354 encoded as an OCTET STRING, values are limited to the definition of 355 given in Section 1.4 of [Models]. 357 LDAPOID ::= OCTET STRING -- Constrained to [Models] 359 For example, 361 1.3.6.1.4.1.1466.1.2.3 363 4.1.3. Distinguished Name and Relative Distinguished Name 365 An LDAPDN is defined to be the representation of a Distinguished Name 366 (DN) after encoding according to the specification in [LDAPDN]. 368 LDAPDN ::= LDAPString 369 -- Constrained to [LDAPDN] 371 A RelativeLDAPDN is defined to be the representation of a Relative 372 Distinguished Name (RDN) after encoding according to the 373 specification in [LDAPDN]. 375 RelativeLDAPDN ::= LDAPString 376 -- Constrained to [LDAPDN] 378 Lightweight Directory Access Protocol Version 3 380 4.1.4. Attribute Descriptions 382 The definition and encoding rules for attribute descriptions are 383 defined in Section 2.5 of [Models]. Briefly, an attribute description 384 is an attribute type and zero or more options. 386 AttributeDescription ::= LDAPString 387 -- Constrained to 388 -- [Models] 390 4.1.5. Attribute Value 392 A field of type AttributeValue is an OCTET STRING containing an 393 encoded attribute value. The attribute value is encoded according to 394 the LDAP-specific encoding definition of its corresponding syntax. 395 The LDAP-specific encoding definitions for different syntaxes and 396 attribute types may be found in other documents and in particular 397 [Syntaxes]. 399 AttributeValue ::= OCTET STRING 401 Note that there is no defined limit on the size of this encoding; 402 thus protocol values may include multi-megabyte attribute values 403 (e.g. photographs). 405 Attribute values may be defined which have arbitrary and non- 406 printable syntax. Implementations MUST NOT display nor attempt to 407 decode an attribute value if its syntax is not known. The 408 implementation may attempt to discover the subschema of the source 409 entry, and retrieve the descriptions of 'attributeTypes' from it 410 [Models]. 412 Clients MUST only send attribute values in a request that are valid 413 according to the syntax defined for the attributes. 415 4.1.6. Attribute Value Assertion 417 The AttributeValueAssertion (AVA) type definition is similar to the 418 one in the X.500 Directory standards. It contains an attribute 419 description and a matching rule ([Models] Section 4.1.3) assertion 420 value suitable for that type. Elements of this type are typically 421 used to assert that the value in assertionValue matches a value of an 422 attribute. 424 AttributeValueAssertion ::= SEQUENCE { 425 attributeDesc AttributeDescription, 426 assertionValue AssertionValue } 428 AssertionValue ::= OCTET STRING 430 Lightweight Directory Access Protocol Version 3 432 The syntax of the AssertionValue depends on the context of the LDAP 433 operation being performed. For example, the syntax of the EQUALITY 434 matching rule for an attribute is used when performing a Compare 435 operation. Often this is the same syntax used for values of the 436 attribute type, but in some cases the assertion syntax differs from 437 the value syntax. See objectIdentiferFirstComponentMatch in 438 [Syntaxes] for an example. 440 4.1.7. Attribute and PartialAttribute 442 Attributes and partial attributes consist of an attribute description 443 and attribute values. A PartialAttribute allows zero values, while 444 Attribute requires at least one value. 446 PartialAttribute ::= SEQUENCE { 447 type AttributeDescription, 448 vals SET OF value AttributeValue } 450 Attribute ::= PartialAttribute(WITH COMPONENTS { 451 ..., 452 vals (SIZE(1..MAX))}) 454 No two of the attribute values may be equivalent as described by 455 Section 2.3 of [Models]. The set of attribute values is unordered. 456 Implementations MUST NOT rely upon the ordering being repeatable. 458 4.1.8. Matching Rule Identifier 460 Matching rules are defined in Section 4.1.3 of [Models]. A matching 461 rule is identified in the protocol by the printable representation of 462 either its , or one of its short name descriptors 463 [Models], e.g. 'caseIgnoreMatch' or '2.5.13.2'. 465 MatchingRuleId ::= LDAPString 467 4.1.9. Result Message 469 The LDAPResult is the construct used in this protocol to return 470 success or failure indications from servers to clients. To various 471 requests, servers will return responses containing the elements found 472 in LDAPResult to indicate the final status of the protocol operation 473 request. 475 LDAPResult ::= SEQUENCE { 476 resultCode ENUMERATED { 477 success (0), 478 operationsError (1), 479 protocolError (2), 480 timeLimitExceeded (3), 481 sizeLimitExceeded (4), 482 compareFalse (5), 484 Lightweight Directory Access Protocol Version 3 486 compareTrue (6), 487 authMethodNotSupported (7), 488 strongAuthRequired (8), 489 -- 9 reserved -- 490 referral (10), 491 adminLimitExceeded (11), 492 unavailableCriticalExtension (12), 493 confidentialityRequired (13), 494 saslBindInProgress (14), 495 noSuchAttribute (16), 496 undefinedAttributeType (17), 497 inappropriateMatching (18), 498 constraintViolation (19), 499 attributeOrValueExists (20), 500 invalidAttributeSyntax (21), 501 -- 22-31 unused -- 502 noSuchObject (32), 503 aliasProblem (33), 504 invalidDNSyntax (34), 505 -- 35 reserved for undefined isLeaf -- 506 aliasDereferencingProblem (36), 507 -- 37-47 unused -- 508 inappropriateAuthentication (48), 509 invalidCredentials (49), 510 insufficientAccessRights (50), 511 busy (51), 512 unavailable (52), 513 unwillingToPerform (53), 514 loopDetect (54), 515 -- 55-63 unused -- 516 namingViolation (64), 517 objectClassViolation (65), 518 notAllowedOnNonLeaf (66), 519 notAllowedOnRDN (67), 520 entryAlreadyExists (68), 521 objectClassModsProhibited (69), 522 -- 70 reserved for CLDAP -- 523 affectsMultipleDSAs (71), 524 -- 72-79 unused -- 525 other (80), 526 ... }, 527 matchedDN LDAPDN, 528 diagnosticMessage LDAPString, 529 referral [3] Referral OPTIONAL } 531 The resultCode enumeration is extensible as defined in Section 3.6 of 532 [LDAPIANA]. The meanings of the listed result codes are given in 533 Appendix A. If a server detects multiple errors for an operation, 534 only one result code is returned. The server should return the result 535 code that best indicates the nature of the error encountered. 537 The diagnosticMessage field of this construct may, at the server's 538 option, be used to return a string containing a textual, human- 539 readable (terminal control and page formatting characters should be 541 Lightweight Directory Access Protocol Version 3 543 avoided) diagnostic message. As this diagnostic message is not 544 standardized, implementations MUST NOT rely on the values returned. 545 Diagnostic messages typically supplement the resultCode with 546 additional information. If the server chooses not to return a textual 547 diagnostic, the diagnosticMessage field MUST be empty. 549 For certain result codes (typically, but not restricted to 550 noSuchObject, aliasProblem, invalidDNSyntax and 551 aliasDereferencingProblem), the matchedDN field is set (subject to 552 access controls) to the name of the last entry (object or alias) used 553 in finding the target (or base) object. This will be a truncated form 554 of the provided name or, if an alias was dereferenced while 555 attempting to locate the entry, of the resulting name. Otherwise the 556 matchedDN field is empty. 558 4.1.10. Referral 560 The referral result code indicates that the contacted server cannot 561 or will not perform the operation and that one or more other servers 562 may be able to. Reasons for this include: 564 - The target entry of the request is not held locally, but the 565 server has knowledge of its possible existence elsewhere. 567 - The operation is restricted on this server -- perhaps due to a 568 read-only copy of an entry to be modified. 570 The referral field is present in an LDAPResult if the resultCode is 571 set to referral, and absent with all other result codes. It contains 572 one or more references to one or more servers or services that may be 573 accessed via LDAP or other protocols. Referrals can be returned in 574 response to any operation request (except Unbind and Abandon which do 575 not have responses). At least one URI MUST be present in the 576 Referral. 578 During a Search operation, after the baseObject is located, and 579 entries are being evaluated, the referral is not returned. Instead, 580 continuation references, described in Section 4.5.3, are returned 581 when other servers would need to be contacted to complete the 582 operation. 584 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI 586 URI ::= LDAPString -- limited to characters permitted in 587 -- URIs 589 If the client wishes to progress the operation, it contacts one of 590 the supported services found in the referral. If multiple URIs are 591 present, the client assumes that any supported URI may be used to 592 progress the operation. 594 Protocol peers that follow referrals MUST ensure that they do not 595 loop between servers. They MUST NOT repeatedly contact the same 597 Lightweight Directory Access Protocol Version 3 599 server for the same request with the same parameters. Some 600 implementations use a counter that is incremented each time referral 601 handling occurs for an operation, and these kinds of implementations 602 MUST be able to handle at least ten nested referrals between the root 603 and a leaf entry. 605 A URI for a server implementing LDAP and accessible via [TCP]/[IP] 606 (v4 or v6) is written as an LDAP URL according to [LDAPURL]. 608 Referral values which are LDAP URLs follow these rules: 610 - If an alias was dereferenced, the part of the URL MUST be 611 present, with the new target object name. 613 - It is RECOMMENDED that the part be present to avoid 614 ambiguity. 616 - If the part is present, the client uses this name in its next 617 request to progress the operation, and if it is not present the 618 client uses the same name as in the original request. 620 - Some servers (e.g. participating in distributed indexing) may 621 provide a different filter in a URL of a referral for a Search 622 operation. 624 - If the part of the LDAP URL is present, the client uses 625 this filter in its next request to progress this Search, and if it 626 is not present the client uses the same filter as it used for that 627 Search. 629 - For Search, it is RECOMMENDED that the part be present to 630 avoid ambiguity. 632 - If the part is missing, the scope of the original Search 633 is used by the client to progress the operation. 635 - Other aspects of the new request may be the same as or different 636 from the request which generated the referral. 638 Other kinds of URIs may be returned. The syntax and semantics of such 639 URIs is left to future specifications. Clients may ignore URIs that 640 they do not support. 642 UTF-8 encoded characters appearing in the string representation of a 643 DN, search filter, or other fields may not be legal for URLs (e.g. 644 spaces) and MUST be escaped using the % method in [URI]. 646 4.1.11. Controls 648 Controls provide a mechanism whereby the semantics and arguments of 649 existing LDAP operations may be extended. One or more controls may be 650 attached to a single LDAP message. A control only affects the 651 semantics of the message it is attached to. 653 Lightweight Directory Access Protocol Version 3 655 Controls sent by clients are termed 'request controls' and those sent 656 by servers are termed 'response controls'. 658 Controls ::= SEQUENCE OF control Control 660 Control ::= SEQUENCE { 661 controlType LDAPOID, 662 criticality BOOLEAN DEFAULT FALSE, 663 controlValue OCTET STRING OPTIONAL } 665 The controlType field is the dotted-decimal representation of an 666 OBJECT IDENTIFIER which uniquely identifies the control. This 667 provides unambiguous naming of controls. Often, response control(s) 668 solicited by a request control share controlType values with the 669 request control. 671 The criticality field only has meaning in controls attached to 672 request messages (except UnbindRequest). For controls attached to 673 response messages and the UnbindRequest, the criticality field SHOULD 674 be FALSE, and MUST be ignored by the receiving protocol peer. A value 675 of TRUE indicates that it is unacceptable to perform the operation 676 without applying the semantics of the control. Specifically, the 677 criticality field is applied as follows: 679 - Regardless of the value of the criticality field, if the server 680 recognizes the control type and it is appropriate for the 681 operation, the server is to make use of the control when 682 performing the operation. 684 - If the server does not recognize the control type or it is not 685 appropriate for the operation, and the criticality field is TRUE, 686 the server MUST NOT perform the operation, and for operations that 687 have a response message, MUST return with the resultCode set to 688 unavailableCriticalExtension. 690 - If the server does not recognize the control type or it is not 691 appropriate for the operation, and the criticality field is FALSE, 692 the server MUST ignore the control. 694 The controlValue may contain information associated with the 695 controlType. Its format is defined by the specification of the 696 control. Implementations MUST be prepared to handle arbitrary 697 contents of the controlValue octet string, including zero bytes. It 698 is absent only if there is no value information which is associated 699 with a control of its type. When a controlValue is defined in terms 700 of ASN.1, and BER encoded according to Section 5.1, it also follows 701 the extensibility rules in Section 4. 703 Servers list the controlType of request controls they recognize in 704 the 'supportedControl' attribute in the root DSE (Section 5.1 of 705 [Models]). 707 Lightweight Directory Access Protocol Version 3 709 Controls SHOULD NOT be combined unless the semantics of the 710 combination has been specified. The semantics of control 711 combinations, if specified, are generally found in the control 712 specification most recently published. When a combination of controls 713 is encountered whose semantics are invalid, not specified (or not 714 known), the message is considered to be not well-formed, thus the 715 operation fails with protocolError. Additionally, unless order- 716 dependent semantics are given in a specification, the order of a 717 combination of controls in the SEQUENCE is ignored. Where the order 718 is to be ignored but cannot be ignored by the server, the message is 719 considered not well-formed and the operation fails with 720 protocolError. 722 This document does not specify any controls. Controls may be 723 specified in other documents. Documents detailing control extensions 724 are to provide for each control: 726 - the OBJECT IDENTIFIER assigned to the control, 728 - direction as to what value the sender should provide for the 729 criticality field (note: the semantics of the criticality field 730 are defined above should not be altered by the control's 731 specification), 733 - whether the controlValue field is present, and if so, the format 734 of its contents, 736 - the semantics of the control, and 738 - optionally, semantics regarding the combination of the control 739 with other controls. 741 4.2. Bind Operation 743 The function of the Bind operation is to allow authentication 744 information to be exchanged between the client and server. The Bind 745 operation should be thought of as the "authenticate" operation. 746 Operational, authentication, and security-related semantics of this 747 operation are given in [AuthMeth]. 749 The Bind request is defined as follows: 751 BindRequest ::= [APPLICATION 0] SEQUENCE { 752 version INTEGER (1 .. 127), 753 name LDAPDN, 754 authentication AuthenticationChoice } 756 AuthenticationChoice ::= CHOICE { 757 simple [0] OCTET STRING, 758 -- 1 and 2 reserved 759 sasl [3] SaslCredentials, 760 ... } 762 Lightweight Directory Access Protocol Version 3 764 SaslCredentials ::= SEQUENCE { 765 mechanism LDAPString, 766 credentials OCTET STRING OPTIONAL } 768 Fields of the BindRequest are: 770 - version: A version number indicating the version of the protocol 771 to be used at the LDAP message layer. This document describes 772 version 3 of the protocol. There is no version negotiation. The 773 client sets this field to the version it desires. If the server 774 does not support the specified version, it MUST respond with a 775 BindResponse where the resultCode is set to protocolError. 777 - name: If not empty, the name of the Directory object that the 778 client wishes to bind as. This field may take on a null value (a 779 zero length string) for the purposes of anonymous binds 780 ([AuthMeth] Section 5.1) or when using Simple Authentication and 781 Security Layer [SASL] authentication ([AuthMeth] Section 3.3.2). 782 Where the server attempts to locate the named object, it SHALL NOT 783 perform alias dereferencing. 785 - authentication: information used in authentication. This type is 786 extensible as defined in Section 3.7 of [LDAPIANA]. Servers that 787 do not support a choice supplied by a client return a BindResponse 788 with the resultCode set to authMethodNotSupported. 790 Textual passwords (consisting of a character sequence with a known 791 character set and encoding) transferred to the server using the 792 simple AuthenticationChoice SHALL be transferred as [UTF-8] 793 encoded [Unicode]. Prior to transfer, clients SHOULD prepare text 794 passwords by applying the [SASLprep] profile of the [Stringprep] 795 algorithm. Passwords consisting of other data (such as random 796 octets) MUST NOT be altered. The determination of whether a 797 password is textual is a local client matter. 799 4.2.1. Processing of the Bind Request 801 Before processing a BindRequest, all uncompleted operations MUST 802 either complete or be abandoned. The server may either wait for the 803 uncompleted operations to complete, or abandon them. The server then 804 proceeds to authenticate the client in either a single-step, or 805 multi-step Bind process. Each step requires the server to return a 806 BindResponse to indicate the status of authentication. 808 After sending a BindRequest, clients MUST NOT send further LDAP PDUs 809 until receiving the BindResponse. Similarly, servers SHOULD NOT 810 process or respond to requests received while processing a 811 BindRequest. 813 If the client did not bind before sending a request and receives an 814 operationsError to that request, it may then send a BindRequest. If 815 this also fails or the client chooses not to bind on the existing 816 LDAP session, it may close the transport connection, reopen it and 818 Lightweight Directory Access Protocol Version 3 820 begin again by first sending a PDU with a BindRequest. This will aid 821 in interoperating with servers implementing other versions of LDAP. 823 Clients may send multiple Bind requests to change the authentication 824 and/or security associations or to complete a multi-stage Bind 825 process. Authentication from earlier binds is subsequently ignored. 827 For some SASL authentication mechanisms, it may be necessary for the 828 client to invoke the BindRequest multiple times ([AuthMeth] Section 829 8.2). Clients MUST NOT invoke operations between two Bind requests 830 made as part of a multi-stage Bind. 832 A client may abort a SASL bind negotiation by sending a BindRequest 833 with a different value in the mechanism field of SaslCredentials, or 834 an AuthenticationChoice other than sasl. 836 If the client sends a BindRequest with the sasl mechanism field as an 837 empty string, the server MUST return a BindResponse with the 838 resultCode set to authMethodNotSupported. This will allow clients to 839 abort a negotiation if it wishes to try again with the same SASL 840 mechanism. 842 4.2.2. Bind Response 844 The Bind response is defined as follows. 846 BindResponse ::= [APPLICATION 1] SEQUENCE { 847 COMPONENTS OF LDAPResult, 848 serverSaslCreds [7] OCTET STRING OPTIONAL } 850 BindResponse consists simply of an indication from the server of the 851 status of the client's request for authentication. 853 A successful Bind operation is indicated by a BindResponse with a 854 resultCode set to success. Otherwise, an appropriate result code is 855 set in the BindResponse. For BindResponse, the protocolError result 856 code may be used to indicate that the version number supplied by the 857 client is unsupported. 859 If the client receives a BindResponse where the resultCode is set to 860 protocolError, it is to assume that the server does not support this 861 version of LDAP. While the client may be able proceed with another 862 version of this protocol (this may or may not require closing and re- 863 establishing the transport connection), how to proceed with another 864 version of this protocol is beyond the scope of this document. 865 Clients which are unable or unwilling to proceed SHOULD close the 866 transport connection. 868 The serverSaslCreds field is used as part of a SASL-defined bind 869 mechanism to allow the client to authenticate the server to which it 870 is communicating, or to perform "challenge-response" authentication. 871 If the client bound with the simple choice, or the SASL mechanism 873 Lightweight Directory Access Protocol Version 3 875 does not require the server to return information to the client, then 876 this field SHALL NOT be included in the BindResponse. 878 4.3. Unbind Operation 880 The function of the Unbind operation is to terminate an LDAP session. 881 The Unbind operation is not the antithesis of the Bind operation as 882 the name implies. The naming of these operations are historical. The 883 Unbind operation should be thought of as the "quit" operation. 885 The Unbind operation is defined as follows: 887 UnbindRequest ::= [APPLICATION 2] NULL 889 The client, upon transmission of the UnbindRequest, and the server, 890 upon receipt of the UnbindRequest are to close the LDAP session as 891 follows: 893 - cease exchanges at the LDAP message layer, 894 - close the SASL layer (if installed), 895 - close the TLS layer (if installed), and 896 - close the transport connection. 898 Uncompleted operations are handled as specified in Section 5.1. 900 4.4. Unsolicited Notification 902 An unsolicited notification is an LDAPMessage sent from the server to 903 the client which is not in response to any LDAPMessage received by 904 the server. It is used to signal an extraordinary condition in the 905 server or in the LDAP session between the client and the server. The 906 notification is of an advisory nature, and the server will not expect 907 any response to be returned from the client. 909 The unsolicited notification is structured as an LDAPMessage in which 910 the messageID is zero and protocolOp is set to the extendedResp 911 choice using the ExtendedResponse type (See Section 4.12). The 912 responseName field of the ExtendedResponse always contains an LDAPOID 913 which is unique for this notification. 915 One unsolicited notification (Notice of Disconnection) is defined in 916 this document. The specification of an unsolicited notification 917 consists of: 919 - the OBJECT IDENTIFIER assigned to the notification (to be 920 specified in the responseName, 922 - the format of the contents of the responseValue (if any), 924 - the circumstances which will cause the notification to be sent, 925 and 927 Lightweight Directory Access Protocol Version 3 929 - the semantics of the message. 931 4.4.1. Notice of Disconnection 933 This notification may be used by the server to advise the client that 934 the server is about to close the transport connection on its own 935 initiative. This notification is intended to assist clients in 936 distinguishing between an exceptional server condition and a 937 transient network failure. Note that this notification is not a 938 response to an Unbind requested by the client. Uncompleted operations 939 are handled as specified in Section 5.1. 941 The responseName is 1.3.6.1.4.1.1466.20036, the responseValue field 942 is absent, and the resultCode is used to indicate the reason for the 943 disconnection. When the strongAuthRequired resultCode is returned 944 with this message, it indicates that the server has detected that an 945 established security association between the client and server has 946 unexpectedly failed or been compromised. 948 Upon transmission of the Notice of Disconnection, the server MUST 949 cease transmission of messages to the client, and MUST close the 950 transport connection. 952 4.5. Search Operation 954 The Search operation is used to request a server to return, subject 955 to access controls and other restrictions, a set of entries matching 956 a complex search criterion. This can be used to read attributes from 957 a single entry, from entries immediately subordinate to a particular 958 entry, or a whole subtree of entries. 960 4.5.1. Search Request 962 The Search request is defined as follows: 964 SearchRequest ::= [APPLICATION 3] SEQUENCE { 965 baseObject LDAPDN, 966 scope ENUMERATED { 967 baseObject (0), 968 singleLevel (1), 969 wholeSubtree (2), 970 ... }, 971 derefAliases ENUMERATED { 972 neverDerefAliases (0), 973 derefInSearching (1), 974 derefFindingBaseObj (2), 975 derefAlways (3) }, 976 sizeLimit INTEGER (0 .. maxInt), 977 timeLimit INTEGER (0 .. maxInt), 978 typesOnly BOOLEAN, 979 filter Filter, 981 Lightweight Directory Access Protocol Version 3 983 attributes AttributeSelection } 985 AttributeSelection ::= SEQUENCE OF selector LDAPString 986 -- The LDAPString is constrained to 987 -- below 989 Filter ::= CHOICE { 990 and [0] SET SIZE (1..MAX) OF filter Filter, 991 or [1] SET SIZE (1..MAX) OF filter Filter, 992 not [2] Filter, 993 equalityMatch [3] AttributeValueAssertion, 994 substrings [4] SubstringFilter, 995 greaterOrEqual [5] AttributeValueAssertion, 996 lessOrEqual [6] AttributeValueAssertion, 997 present [7] AttributeDescription, 998 approxMatch [8] AttributeValueAssertion, 999 extensibleMatch [9] MatchingRuleAssertion, 1000 ... } 1002 SubstringFilter ::= SEQUENCE { 1003 type AttributeDescription, 1004 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE { 1005 initial [0] AssertionValue, -- can occur at most once 1006 any [1] AssertionValue, 1007 final [2] AssertionValue } -- can occur at most once 1008 } 1010 MatchingRuleAssertion ::= SEQUENCE { 1011 matchingRule [1] MatchingRuleId OPTIONAL, 1012 type [2] AttributeDescription OPTIONAL, 1013 matchValue [3] AssertionValue, 1014 dnAttributes [4] BOOLEAN DEFAULT FALSE } 1016 Note that an X.500 "list"-like operation can be emulated by the 1017 client requesting a singleLevel Search operation with a filter 1018 checking for the presence of the 'objectClass' attribute, and that an 1019 X.500 "read"-like operation can be emulated by a baseObject Search 1020 operation with the same filter. A server which provides a gateway to 1021 X.500 is not required to use the Read or List operations, although it 1022 may choose to do so, and if it does, it must provide the same 1023 semantics as the X.500 Search operation. 1025 4.5.1.1 SearchRequest.baseObject 1027 The name of the base object entry (or possibly the root) relative to 1028 which the Search is to be performed. 1030 4.5.1.2 SearchRequest.scope 1032 Specifies the scope of the Search to be performed. The semantics (as 1033 described in [X.511]) of the possible values of this field are: 1035 Lightweight Directory Access Protocol Version 3 1037 baseObject: The scope is constrained to the entry named by 1038 baseObject. 1040 singleLevel: The scope is constrained to the immediate 1041 subordinates of the entry named by baseObject. 1043 wholeSubtree: the scope is constrained to the entry named by the 1044 baseObject, and all its subordinates. 1046 4.5.1.3 SearchRequest.derefAliases 1048 An indicator as to how alias entries (as defined in [Models]) are to 1049 be handled in searching. The semantics of the defined values of this 1050 field are: 1052 neverDerefAliases: Do not dereference aliases in searching or in 1053 locating the base object of the Search. 1055 derefInSearching: While searching subordinates of the base object, 1056 dereference any alias within the search scope (the act of 1057 dereferencing an alias includes recursively dereferencing aliases 1058 which refer to aliases). Dereferenced objects become the vertices 1059 of further search scopes where the Search operation continues. If 1060 the search scope is wholeSubtree, the Search continues in the 1061 subtree(s) of any dereferenced object. If the search scope is 1062 singleLevel, the search is applied to any dereferenced objects, 1063 and is not applied to their subordinates. Servers SHOULD eliminate 1064 duplicate entries that arise due to alias dereferencing while 1065 searching. 1067 derefFindingBaseObj: Dereference aliases in locating the base 1068 object of the Search, but not when searching subordinates of the 1069 base object. 1071 derefAlways: Dereference aliases both in searching and in locating 1072 the base object of the Search. 1074 Servers MUST detect looping while dereferencing aliases in order to 1075 prevent denial of service attacks of this nature. 1077 4.5.1.4 SearchRequest.sizeLimit 1079 A size limit that restricts the maximum number of entries to be 1080 returned as a result of the Search. A value of zero in this field 1081 indicates that no client-requested size limit restrictions are in 1082 effect for the Search. Servers may also enforce a maximum number of 1083 entries to return. 1085 4.5.1.5 SearchRequest.timeLimit 1087 Lightweight Directory Access Protocol Version 3 1089 A time limit that restricts the maximum time (in seconds) allowed for 1090 a Search. A value of zero in this field indicates that no client- 1091 requested time limit restrictions are in effect for the Search. 1092 Servers may also enforce a maximum time limit for the Search. 1094 4.5.1.6 SearchRequest.typesOnly 1096 An indicator as to whether Search results are to contain both 1097 attribute descriptions and values, or just attribute descriptions. 1098 Setting this field to TRUE causes only attribute descriptions (no 1099 values) to be returned. Setting this field to FALSE causes both 1100 attribute descriptions and values to be returned. 1102 4.5.1.7 SearchRequest.filter 1104 A filter that defines the conditions that must be fulfilled in order 1105 for the Search to match a given entry. 1107 The 'and', 'or' and 'not' choices can be used to form combinations of 1108 filters. At least one filter element MUST be present in an 'and' or 1109 'or' choice. The others match against individual attribute values of 1110 entries in the scope of the Search. (Implementor's note: the 'not' 1111 filter is an example of a tagged choice in an implicitly-tagged 1112 module. In BER this is treated as if the tag was explicit.) 1114 A server MUST evaluate filters according to the three-valued logic of 1115 [X.511] (1993) Clause 7.8.1. In summary, a filter is evaluated to 1116 either "TRUE", "FALSE" or "Undefined". If the filter evaluates to 1117 TRUE for a particular entry, then the attributes of that entry are 1118 returned as part of the Search result (subject to any applicable 1119 access control restrictions). If the filter evaluates to FALSE or 1120 Undefined, then the entry is ignored for the Search. 1122 A filter of the "and" choice is TRUE if all the filters in the SET OF 1123 evaluate to TRUE, FALSE if at least one filter is FALSE, and 1124 otherwise Undefined. A filter of the "or" choice is FALSE if all of 1125 the filters in the SET OF evaluate to FALSE, TRUE if at least one 1126 filter is TRUE, and Undefined otherwise. A filter of the 'not' choice 1127 is TRUE if the filter being negated is FALSE, FALSE if it is TRUE, 1128 and Undefined if it is Undefined. 1130 A filter item evaluates to Undefined when the server would not be 1131 able to determine whether the assertion value matches an entry. 1132 Examples include: 1134 - An attribute description in an equalityMatch, substrings, 1135 greaterOrEqual, lessOrEqual, approxMatch or extensibleMatch 1136 filter is not recognized by the server. 1138 - The attribute type does not define the appropriate matching 1139 rule. 1141 Lightweight Directory Access Protocol Version 3 1143 - A MatchingRuleId in the extensibleMatch is not recognized by 1144 the server or is not valid for the attribute type. 1146 - The type of filtering requested is not implemented. 1148 - The assertion value is invalid. 1150 For example, if a server did not recognize the attribute type 1151 shoeSize, a filter of (shoeSize=*) would evaluate to FALSE, and the 1152 filters (shoeSize=12), (shoeSize>=12) and (shoeSize<=12) would each 1153 evaluate to Undefined. 1155 Servers MUST NOT return errors if attribute descriptions or matching 1156 rule ids are not recognized, assertion values are invalid, or the 1157 assertion syntax is not supported. More details of filter processing 1158 are given in Clause 7.8 of [X.511]. 1160 4.5.1.7.1 SearchRequest.filter.equalityMatch 1162 The matching rule for equalityMatch filter items is defined by the 1163 EQUALITY matching rule for the attribute type. 1165 4.5.1.7.2 SearchRequest.filter.substrings 1167 There SHALL be at most one 'initial', and at most one 'final' in the 1168 'substrings' of a SubstringFilter. If 'initial' is present, it SHALL 1169 be the first element of 'substrings'. If 'final' is present, it SHALL 1170 be the last element of 'substrings'. 1172 The matching rule for an AssertionValue in a substrings filter item 1173 is defined by the SUBSTR matching rule for the attribute type. Note 1174 that the AssertionValue in a substrings filter item conforms to the 1175 assertion syntax of the EQUALITY matching rule for the attribute type 1176 rather than the assertion syntax of the SUBSTR matching rule for the 1177 attribute type. Conceptually, the entire SubstringFilter is converted 1178 into an assertion value of the substrings matching rule prior to 1179 applying the rule. 1181 4.5.1.7.3 SearchRequest.filter.greaterOrEqual 1183 The matching rule for the greaterOrEqual filter item is defined by 1184 the ORDERING and EQUALITY matching rules for the attribute type. 1186 4.5.1.7.4 SearchRequest.filter.lessOrEqual 1188 The matching rule for the lessOrEqual filter item is defined by the 1189 ORDERING matching rule for the attribute type. 1191 4.5.1.7.5 SearchRequest.filter.present 1193 Lightweight Directory Access Protocol Version 3 1195 The present match evaluates to TRUE where there is an attribute or 1196 subtype of the specified attribute description present in an entry, 1197 and FALSE otherwise (including a presence test with an unrecognized 1198 attribute description). 1200 4.5.1.7.6 SearchRequest.filter.approxMatch 1202 An approxMatch filter item evaluates to TRUE when there is a value of 1203 the attribute or subtype for which some locally-defined approximate 1204 matching algorithm (e.g. spelling variations, phonetic match, etc.) 1205 returns TRUE. If an item matches for equality, it also satisfies an 1206 approximate match. If approximate matching is not supported for the 1207 attribute, this filter item should be treated as an equalityMatch. 1209 4.5.1.7.7 SearchRequest.filter.extensibleMatch 1211 The fields of the extensibleMatch filter item are evaluated as 1212 follows: 1214 - If the matchingRule field is absent, the type field MUST be 1215 present, and an equality match is performed for that type. 1217 - If the type field is absent and the matchingRule is present, the 1218 matchValue is compared against all attributes in an entry which 1219 support that matchingRule. 1221 - If the type field is present and the matchingRule is present, the 1222 matchValue is compared against entry attributes of the specified 1223 type. 1225 - If the dnAttributes field is set to TRUE, the match is 1226 additionally applied against all the AttributeValueAssertions in 1227 an entry's distinguished name, and evaluates to TRUE if there is 1228 at least one attribute in the distinguished name for which the 1229 filter item evaluates to TRUE. The dnAttributes field is present 1230 to alleviate the need for multiple versions of generic matching 1231 rules (such as word matching), where one applies to entries and 1232 another applies to entries and DN attributes as well. 1234 The matchingRule used for evaluation determines the syntax for the 1235 assertion value. Once the matchingRule and attribute(s) have been 1236 determined, the filter item evaluates to TRUE if it matches with at 1237 least one attribute in the entry, FALSE if it does not match any 1238 attribute in the entry, and Undefined if the matchingRule is not 1239 recognized, the matchingRule is unsuitable for use with the specified 1240 type, or the assertionValue is invalid. 1242 4.5.1.7 SearchRequest.attributes 1244 Lightweight Directory Access Protocol Version 3 1246 A selection list of the attributes to be returned from each entry 1247 which matches the search filter. LDAPString values of this field are 1248 constrained to the following Augmented Backus-Naur Form ([ABNF]): 1250 attributeSelector = attributedescription / selectorpecial 1252 selectorspecial = noattrs / alluserattrs 1254 noattrs = %x31.2E.31 ; "1.1" 1256 alluserattrs = %x2A ; asterisk ("*") 1258 The production is defined in Section 2.5 of 1259 [Models]. 1261 There are three special cases which may appear in the attributes 1262 selection list: 1264 - an empty list with no attributes, 1266 - a list containing "*" (with zero or more attribute 1267 descriptions), and 1269 - a list containing only "1.1". 1271 An empty list requests the return of all user attributes. 1273 A list containing "*" requests the return of all user attributes 1274 in addition to other listed (operational) attributes. 1276 A list containing only the OID "1.1" indicates that no attributes 1277 are to be returned. If "1.1" is provided with other 1278 attributeSelector values, the "1.1" attributeSelector is ignored. 1279 This OID was chosen because it does not (and can not) correspond 1280 to any attribute in use. 1282 Client implementors should note that even if all user attributes are 1283 requested, some attributes and/or attribute values of the entry may 1284 not be included in Search results due to access controls or other 1285 restrictions. Furthermore, servers will not return operational 1286 attributes, such as objectClasses or attributeTypes, unless they are 1287 listed by name. Operational attributes are described in [Models]. 1289 Attributes are returned at most once in an entry. If an attribute 1290 description is named more than once in the list, the subsequent names 1291 are ignored. If an attribute description in the list is not 1292 recognized, it is ignored by the server. 1294 4.5.2. Search Result 1296 The results of the Search operation are returned as zero or more 1297 SearchResultEntry and/or zero or more SearchResultReference messages, 1298 followed by a single SearchResultDone message. 1300 Lightweight Directory Access Protocol Version 3 1302 SearchResultEntry ::= [APPLICATION 4] SEQUENCE { 1303 objectName LDAPDN, 1304 attributes PartialAttributeList } 1306 PartialAttributeList ::= SEQUENCE OF 1307 partialAttribute PartialAttribute 1308 -- Note that the PartialAttributeList may hold zero elements. 1309 -- This may happen when none of the attributes of an entry 1310 -- were requested, or could be returned. 1311 -- Note also that the partialAttribute vals set may hold zero 1312 -- elements. This may happen when typesOnly is requested, access 1313 -- controls prevent the return of values, or other reasons. 1315 SearchResultReference ::= [APPLICATION 19] SEQUENCE 1316 SIZE (1..MAX) OF uri URI 1318 SearchResultDone ::= [APPLICATION 5] LDAPResult 1320 Each SearchResultEntry represents an entry found during the Search. 1321 Each SearchResultReference represents an area not yet explored during 1322 the Search. The SearchResultEntry and SearchResultReference PDUs may 1323 come in any order. Following all the SearchResultReference and 1324 SearchResultEntry responses, the server returns a SearchResultDone 1325 response, which contains an indication of success, or detailing any 1326 errors that have occurred. 1328 Each entry returned in a SearchResultEntry will contain all 1329 appropriate attributes as specified in the attributes field of the 1330 Search Request, subject to access control and other administrative 1331 policy. 1333 Some attributes may be constructed by the server and appear in a 1334 SearchResultEntry attribute list, although they are not stored 1335 attributes of an entry. Clients SHOULD NOT assume that all attributes 1336 can be modified, even if permitted by access control. 1338 If the server's schema defines short names [Models] for an attribute 1339 type then the server SHOULD use one of those names in attribute 1340 descriptions for that attribute type (in preference to using the 1341 [Models] format of the attribute type's object 1342 identifier). The server SHOULD NOT use the short name if that name is 1343 known by the server to be ambiguous, or otherwise likely to cause 1344 interoperability problems. 1346 4.5.3. Continuation References in the Search Result 1348 If the server was able to locate the entry referred to by the 1349 baseObject but was unable to search one or more non-local entries, 1350 the server may return one or more SearchResultReference messages, 1351 each containing a reference to another set of servers for continuing 1352 the operation. A server MUST NOT return any SearchResultReference 1353 messages if it has not located the baseObject and thus has not 1355 Lightweight Directory Access Protocol Version 3 1357 searched any entries; in this case it would return a SearchResultDone 1358 containing either a referral or noSuchObject result code (depending 1359 on the server's knowledge of the entry named in the baseObject). 1361 If a server holds a copy or partial copy of the subordinate naming 1362 context (Section 5 of [Models]), it may use the search filter to 1363 determine whether or not to return a SearchResultReference response. 1364 Otherwise SearchResultReference responses are always returned when in 1365 scope. 1367 The SearchResultReference is of the same data type as the Referral. 1369 A URI for a server implementing LDAP and accessible via [TCP]/[IP] 1370 (v4 or v6) is written as an LDAP URL according to [LDAPURL]. 1372 In order to complete the Search, the client issues a new Search 1373 operation for each SearchResultReference that is returned. Note that 1374 the Abandon operation described in Section 4.11 applies only to a 1375 particular operation sent at the LDAP message layer between a client 1376 and server. The client must abandon subsequent Search operations it 1377 wishes to individually. 1379 Clients that follow search continuation references MUST ensure that 1380 they do not loop between servers. They MUST NOT repeatedly contact 1381 the same server for the same request with the same target entry name, 1382 scope and filter. Some clients use a counter that is incremented each 1383 time search result reference handling occurs for an operation, and 1384 these kinds of clients MUST be able to handle at least ten nested 1385 search result references between the root and a leaf entry. 1387 SearchResultReference values which are LDAP URLs follow these rules: 1389 - The part of the URL MUST be present, with the new target 1390 object name. The client MUST use this name when following the 1391 reference. UTF-8 encoded characters appearing in the string 1392 representation of a DN or search filter may not be legal for URLs 1393 (e.g. spaces) and MUST be escaped using the % method in [URI]. 1395 - Some servers (e.g. participating in distributed indexing) may 1396 provide a different filter in a URL of a SearchResultReference. 1398 - If the part of the URL is present, the client MUST use 1399 this filter in its next request to progress this Search, and if it 1400 is not present the client MUST use the same filter as it used for 1401 that Search. 1403 - If the originating search scope was singleLevel, the part 1404 of the URL will be "base". 1406 - It is RECOMMENDED that the part be present to avoid 1407 ambiguity. In the absence of a part, the scope of the 1408 original Search request is assumed. 1410 Lightweight Directory Access Protocol Version 3 1412 - Other aspects of the new Search request may be the same as or 1413 different from the Search request which generated the 1414 SearchResultReference. 1416 - The name of an unexplored subtree in a SearchResultReference need 1417 not be subordinate to the base object. 1419 Other kinds of URIs may be returned. The syntax and semantics of such 1420 URIs is left to future specifications. Clients may ignore URIs that 1421 they do not support. 1423 4.5.3.1. Examples 1425 For example, suppose the contacted server (hosta) holds the entry 1426 and the entry . It 1427 knows that both LDAP servers (hostb) and (hostc) hold 1428 (one is the master and the other server 1429 a shadow), and that LDAP-capable server (hostd) holds the subtree 1430 . If a wholeSubtree Search of 1431 is requested to the contacted server, it may 1432 return the following: 1434 SearchResultEntry for DC=Example,DC=NET 1435 SearchResultEntry for CN=Manager,DC=Example,DC=NET 1436 SearchResultReference { 1437 ldap://hostb/OU=People,DC=Example,DC=NET??sub 1438 ldap://hostc/OU=People,DC=Example,DC=NET??sub } 1439 SearchResultReference { 1440 ldap://hostd/OU=Roles,DC=Example,DC=NET??sub } 1441 SearchResultDone (success) 1443 Client implementors should note that when following a 1444 SearchResultReference, additional SearchResultReference may be 1445 generated. Continuing the example, if the client contacted the server 1446 (hostb) and issued the Search request for the subtree 1447 , the server might respond as follows: 1449 SearchResultEntry for OU=People,DC=Example,DC=NET 1450 SearchResultReference { 1451 ldap://hoste/OU=Managers,OU=People,DC=Example,DC=NET??sub } 1452 SearchResultReference { 1453 ldap://hostf/OU=Consultants,OU=People,DC=Example,DC=NET??sub } 1454 SearchResultDone (success) 1456 Similarly, if a singleLevel Search of is 1457 requested to the contacted server, it may return the following: 1459 SearchResultEntry for CN=Manager,DC=Example,DC=NET 1460 SearchResultReference { 1461 ldap://hostb/OU=People,DC=Example,DC=NET??base 1462 ldap://hostc/OU=People,DC=Example,DC=NET??base } 1463 SearchResultReference { 1464 ldap://hostd/OU=Roles,DC=Example,DC=NET??base } 1466 Lightweight Directory Access Protocol Version 3 1468 SearchResultDone (success) 1470 If the contacted server does not hold the base object for the Search, 1471 but has knowledge of its possible location, then it may return a 1472 referral to the client. In this case, if the client requests a 1473 subtree Search of to hosta, the server returns a 1474 SearchResultDone containing a referral. 1476 SearchResultDone (referral) { 1477 ldap://hostg/DC=Example,DC=ORG??sub } 1479 4.6. Modify Operation 1481 The Modify operation allows a client to request that a modification 1482 of an entry be performed on its behalf by a server. The Modify 1483 Request is defined as follows: 1485 ModifyRequest ::= [APPLICATION 6] SEQUENCE { 1486 object LDAPDN, 1487 changes SEQUENCE OF change SEQUENCE { 1488 operation ENUMERATED { 1489 add (0), 1490 delete (1), 1491 replace (2), 1492 ... }, 1493 modification PartialAttribute } } 1495 Fields of the Modify Request are: 1497 - object: The value of this field contains the name of the entry to 1498 be modified. The server SHALL NOT perform any alias dereferencing 1499 in determining the object to be modified. 1501 - changes: A list of modifications to be performed on the entry. The 1502 entire list of modifications MUST be performed in the order they 1503 are listed as a single atomic operation. While individual 1504 modifications may violate certain aspects of the directory schema 1505 (such as the object class definition and DIT content rule), the 1506 resulting entry after the entire list of modifications is 1507 performed MUST conform to the requirements of the directory model 1508 and controlling schema [Models]. 1510 - operation: Used to specify the type of modification being 1511 performed. Each operation type acts on the following 1512 modification. The values of this field have the following 1513 semantics respectively: 1515 add: add values listed to the modification attribute, 1516 creating the attribute if necessary; 1518 delete: delete values listed from the modification attribute. 1519 If no values are listed, or if all current values of the 1520 attribute are listed, the entire attribute is removed; 1522 Lightweight Directory Access Protocol Version 3 1524 replace: replace all existing values of the modification 1525 attribute with the new values listed, creating the attribute 1526 if it did not already exist. A replace with no value will 1527 delete the entire attribute if it exists, and is ignored if 1528 the attribute does not exist. 1530 - modification: A PartialAttribute (which may have an empty SET 1531 of vals) used to hold the attribute type or attribute type and 1532 values being modified. 1534 Upon receipt of a Modify Request, the server attempts to perform the 1535 necessary modifications to the DIT and returns the result in a Modify 1536 Response, defined as follows: 1538 ModifyResponse ::= [APPLICATION 7] LDAPResult 1540 The server will return to the client a single Modify Response 1541 indicating either the successful completion of the DIT modification, 1542 or the reason that the modification failed. Due to the requirement 1543 for atomicity in applying the list of modifications in the Modify 1544 Request, the client may expect that no modifications of the DIT have 1545 been performed if the Modify Response received indicates any sort of 1546 error, and that all requested modifications have been performed if 1547 the Modify Response indicates successful completion of the Modify 1548 operation. Whether the modification was applied or not cannot be 1549 determined by the client if the Modify Response was not received 1550 (e.g. the LDAP session was terminated or the Modify operation was 1551 abandoned). 1553 Servers MUST ensure that entries conform to user and system schema 1554 rules or other data model constraints. The Modify operation cannot be 1555 used to remove from an entry any of its distinguished values, i.e. 1556 those values which form the entry's relative distinguished name. An 1557 attempt to do so will result in the server returning the 1558 notAllowedOnRDN result code. The Modify DN operation described in 1559 Section 4.9 is used to rename an entry. 1561 For attribute types which specify no equality matching, the rules in 1562 Section 2.5.1 of [Models] are followed. 1564 Note that due to the simplifications made in LDAP, there is not a 1565 direct mapping of the changes in an LDAP ModifyRequest onto the 1566 changes of a DAP ModifyEntry operation, and different implementations 1567 of LDAP-DAP gateways may use different means of representing the 1568 change. If successful, the final effect of the operations on the 1569 entry MUST be identical. 1571 4.7. Add Operation 1573 The Add operation allows a client to request the addition of an entry 1574 into the Directory. The Add Request is defined as follows: 1576 Lightweight Directory Access Protocol Version 3 1578 AddRequest ::= [APPLICATION 8] SEQUENCE { 1579 entry LDAPDN, 1580 attributes AttributeList } 1582 AttributeList ::= SEQUENCE OF attribute Attribute 1584 Fields of the Add Request are: 1586 - entry: the name of the entry to be added. The server SHALL NOT 1587 dereference any aliases in locating the entry to be added. 1589 - attributes: the list of attributes that, along with those from the 1590 RDN, make up the content of the entry being added. Clients MAY or 1591 MAY NOT include the RDN attribute(s) in this list. Clients MUST 1592 NOT supply NO-USER-MODIFICATION attributes such as the 1593 createTimestamp or creatorsName attributes, since the server 1594 maintains these automatically. 1596 Servers MUST ensure that entries conform to user and system schema 1597 rules or other data model constraints. For attribute types which 1598 specify no equality matching, the rules in Section 2.5.1 of [Models] 1599 are followed (this applies to the naming attribute in addition to any 1600 multi-valued attributes being added). 1602 The entry named in the entry field of the AddRequest MUST NOT exist 1603 for the AddRequest to succeed. The immediate superior (parent) of an 1604 object or alias entry to be added MUST exist. For example, if the 1605 client attempted to add , the 1606 entry did not exist, and the entry did 1607 exist, then the server would return the noSuchObject result code with 1608 the matchedDN field containing . 1610 Upon receipt of an Add Request, a server will attempt to add the 1611 requested entry. The result of the Add attempt will be returned to 1612 the client in the Add Response, defined as follows: 1614 AddResponse ::= [APPLICATION 9] LDAPResult 1616 A response of success indicates that the new entry has been added to 1617 the Directory. 1619 4.8. Delete Operation 1621 The Delete operation allows a client to request the removal of an 1622 entry from the Directory. The Delete Request is defined as follows: 1624 DelRequest ::= [APPLICATION 10] LDAPDN 1626 The Delete Request consists of the name of the entry to be deleted. 1627 The server SHALL NOT dereference aliases while resolving the name of 1628 the target entry to be removed. 1630 Lightweight Directory Access Protocol Version 3 1632 Only leaf entries (those with no subordinate entries) can be deleted 1633 with this operation. 1635 Upon receipt of a Delete Request, a server will attempt to perform 1636 the entry removal requested and return the result in the Delete 1637 Response defined as follows: 1639 DelResponse ::= [APPLICATION 11] LDAPResult 1641 4.9. Modify DN Operation 1643 The Modify DN operation allows a client to change the Relative 1644 Distinguished Name (RDN) of an entry in the Directory, and/or to move 1645 a subtree of entries to a new location in the Directory. The Modify 1646 DN Request is defined as follows: 1648 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE { 1649 entry LDAPDN, 1650 newrdn RelativeLDAPDN, 1651 deleteoldrdn BOOLEAN, 1652 newSuperior [0] LDAPDN OPTIONAL } 1654 Fields of the Modify DN Request are: 1656 - entry: the name of the entry to be changed. This entry may or may 1657 not have subordinate entries. 1659 - newrdn: the new RDN of the entry. The value of the old RDN is 1660 supplied when moving the entry to a new superior without changing 1661 its RDN. Attribute values of the new RDN not matching any 1662 attribute value of the entry are added to the entry and an 1663 appropriate error is returned if this fails. 1665 - deleteoldrdn: a boolean field that controls whether the old RDN 1666 attribute values are to be retained as attributes of the entry, or 1667 deleted from the entry. 1669 - newSuperior: if present, this is the name of an existing object 1670 entry which becomes the immediate superior (parent) of the 1671 existing entry. 1673 The server SHALL NOT dereference any aliases in locating the objects 1674 named in entry or newSuperior. 1676 Upon receipt of a ModifyDNRequest, a server will attempt to perform 1677 the name change and return the result in the Modify DN Response, 1678 defined as follows: 1680 ModifyDNResponse ::= [APPLICATION 13] LDAPResult 1682 For example, if the entry named in the entry field was , the newrdn field was , and the 1684 newSuperior field was absent, then this operation would attempt to 1686 Lightweight Directory Access Protocol Version 3 1688 rename the entry to be . If there was 1689 already an entry with that name, the operation would fail with the 1690 entryAlreadyExists result code. 1692 Servers MUST ensure that entries conform to user and system schema 1693 rules or other data model constraints. For attribute types which 1694 specify no equality matching, the rules in Section 2.5.1 of [Models] 1695 are followed (this pertains to newrdn and deleteoldrdn). 1697 The object named in newSuperior MUST exist. For example, if the 1698 client attempted to add , the 1699 entry did not exist, and the entry did 1700 exist, then the server would return the noSuchObject result code with 1701 the matchedDN field containing . 1703 If the deleteoldrdn field is TRUE, the attribute values forming the 1704 old RDN but not the new RDN are deleted from the entry. If the 1705 deleteoldrdn field is FALSE, the attribute values forming the old RDN 1706 will be retained as non-distinguished attribute values of the entry. 1708 Note that X.500 restricts the ModifyDN operation to only affect 1709 entries that are contained within a single server. If the LDAP server 1710 is mapped onto DAP, then this restriction will apply, and the 1711 affectsMultipleDSAs result code will be returned if this error 1712 occurred. In general, clients MUST NOT expect to be able to perform 1713 arbitrary movements of entries and subtrees between servers or 1714 between naming contexts. 1716 4.10. Compare Operation 1718 The Compare operation allows a client to compare an assertion value 1719 with the values of a particular attribute in a particular entry in 1720 the Directory. The Compare Request is defined as follows: 1722 CompareRequest ::= [APPLICATION 14] SEQUENCE { 1723 entry LDAPDN, 1724 ava AttributeValueAssertion } 1726 Fields of the Compare Request are: 1728 - entry: the name of the entry to be compared. The server SHALL NOT 1729 dereference any aliases in locating the entry to be compared. 1731 - ava: holds the attribute value assertion to be compared. 1733 Upon receipt of a Compare Request, a server will attempt to perform 1734 the requested comparison and return the result in the Compare 1735 Response, defined as follows: 1737 CompareResponse ::= [APPLICATION 15] LDAPResult 1739 The resultCode is set to compareTrue, compareFalse, or an appropriate 1740 error. compareTrue indicates that the assertion value in the ava 1742 Lightweight Directory Access Protocol Version 3 1744 field matches a value of the attribute or subtype according to the 1745 attribute's EQUALITY matching rule. compareFalse indicates that the 1746 assertion value in the ava field and the values of the attribute or 1747 subtype did not match. Other result codes indicate either that the 1748 result of the comparison was Undefined (Section 4.5.1), or that some 1749 error occurred. 1751 Note that some directory systems may establish access controls which 1752 permit the values of certain attributes (such as userPassword) to be 1753 compared but not interrogated by other means. 1755 4.11. Abandon Operation 1757 The function of the Abandon operation is to allow a client to request 1758 that the server abandon an uncompleted operation. The Abandon Request 1759 is defined as follows: 1761 AbandonRequest ::= [APPLICATION 16] MessageID 1763 The MessageID is that of an operation which was requested earlier at 1764 this LDAP message layer. The Abandon request itself has its own 1765 MessageID. This is distinct from the MessageID of the earlier 1766 operation being abandoned. 1768 There is no response defined in the Abandon operation. Upon receipt 1769 of an AbandonRequest, the server MAY abandon the operation identified 1770 by the MessageID. Since the client cannot tell the difference between 1771 a successfully abandoned operation and an uncompleted operation, the 1772 application of the Abandon operation is limited to uses where the 1773 client does not require an indication of its outcome. 1775 Abandon, Bind, Unbind, and StartTLS operations cannot be abandoned. 1777 In the event that a server receives an Abandon Request on a Search 1778 operation in the midst of transmitting responses to the Search, that 1779 server MUST cease transmitting entry responses to the abandoned 1780 request immediately, and MUST NOT send the SearchResponseDone. Of 1781 course, the server MUST ensure that only properly encoded LDAPMessage 1782 PDUs are transmitted. 1784 The ability to abandon other (particularly update) operations is at 1785 the discretion of the server. 1787 Clients should not send Abandon requests for the same operation 1788 multiple times, and MUST also be prepared to receive results from 1789 operations it has abandoned (since these may have been in transit 1790 when the Abandon was requested, or are not able to be abandoned). 1792 Servers MUST discard Abandon requests for message IDs they do not 1793 recognize, for operations which cannot be abandoned, and for 1794 operations which have already been abandoned. 1796 Lightweight Directory Access Protocol Version 3 1798 4.12. Extended Operation 1800 The Extended operation allows additional operations to be defined for 1801 services not already available in the protocol. For example, to Add 1802 operations to install transport layer security (see Section 4.14). 1804 The Extended operation allows clients to make requests and receive 1805 responses with predefined syntaxes and semantics. These may be 1806 defined in RFCs or be private to particular implementations. 1808 Each Extended operation consists of an Extended request and an 1809 Extended response. 1811 ExtendedRequest ::= [APPLICATION 23] SEQUENCE { 1812 requestName [0] LDAPOID, 1813 requestValue [1] OCTET STRING OPTIONAL } 1815 The requestName is a dotted-decimal representation of the unique 1816 OBJECT IDENTIFIER corresponding to the request. The requestValue is 1817 information in a form defined by that request, encapsulated inside an 1818 OCTET STRING. 1820 The server will respond to this with an LDAPMessage containing an 1821 ExtendedResponse. 1823 ExtendedResponse ::= [APPLICATION 24] SEQUENCE { 1824 COMPONENTS OF LDAPResult, 1825 responseName [10] LDAPOID OPTIONAL, 1826 responseValue [11] OCTET STRING OPTIONAL } 1828 The responseName is typically not required to be present as the 1829 syntax and semantics of the response (including the format of the 1830 responseValue) is implicitly known and associated with the request by 1831 the messageID. 1833 If the Extended operation associated with the requestName is not 1834 supported by the server, the server MUST NOT provide a responseName 1835 nor a responseValue and MUST return with resultCode set to 1836 protocolError. 1838 The requestValue and responseValue fields contain any information 1839 associated with the operation. The format of these fields is defined 1840 by the specification of the Extended operation. Implementations MUST 1841 be prepared to handle arbitrary contents of these fields, including 1842 zero bytes. Values that are defined in terms of ASN.1 and BER encoded 1843 according to Section 5.1, also follow the extensibility rules in 1844 Section 4. 1846 Servers list the requestName of Extended Requests they recognize in 1847 the 'supportedExtension' attribute in the root DSE (Section 5.1 of 1848 [Models]). 1850 Extended operations may be specified in other documents. The 1851 specification of an Extended operation consists of: 1853 Lightweight Directory Access Protocol Version 3 1855 - the OBJECT IDENTIFIER assigned to the requestName, 1857 - the OBJECT IDENTIFIER (if any) assigned to the responseName (note 1858 that the same OBJECT IDENTIFIER my be used for both the 1859 requestName and responseName), 1861 - the format of the contents of the requestValue and responseValue 1862 (if any), and 1864 - the semantics of the operation. 1866 4.13. IntermediateResponse Message 1868 While the Search operation provides a mechanism to return multiple 1869 response messages for a single Search request, other operations, by 1870 nature, do not provide for multiple response messages. 1872 The IntermediateResponse message provides a general mechanism for 1873 defining single-request/multiple-response operations in LDAP. This 1874 message is intended to be used in conjunction with the Extended 1875 operation to define new single-request/multiple-response operations 1876 or in conjunction with a control when extending existing LDAP 1877 operations in a way that requires them to return Intermediate 1878 response information. 1880 It is intended that the definitions and descriptions of Extended 1881 operations and controls that make use of the IntermediateResponse 1882 message will define the circumstances when an IntermediateResponse 1883 message can be sent by a server and the associated meaning of an 1884 IntermediateResponse message sent in a particular circumstance. 1886 IntermediateResponse ::= [APPLICATION 25] SEQUENCE { 1887 responseName [0] LDAPOID OPTIONAL, 1888 responseValue [1] OCTET STRING OPTIONAL } 1890 IntermediateResponse messages SHALL NOT be returned to the client 1891 unless the client issues a request that specifically solicits their 1892 return. This document defines two forms of solicitation: Extended 1893 operation and request control. IntermediateResponse messages are 1894 specified in documents describing the manner in which they are 1895 solicited (i.e. in the Extended operation or request control 1896 specification that uses them). These specifications include: 1898 - the OBJECT IDENTIFIER (if any) assigned to the responseName, 1900 - the format of the contents of the responseValue (if any), and 1902 - the semantics associated with the IntermediateResponse message. 1904 Extensions that allow the return of multiple types of 1905 IntermediateResponse messages SHALL identify those types using unique 1906 responseName values (note that one of these may specify no value). 1908 Lightweight Directory Access Protocol Version 3 1910 Sections 4.13.1 and 4.13.2 describe additional requirements on the 1911 inclusion of responseName and responseValue in IntermediateResponse 1912 messages. 1914 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse 1916 A single-request/multiple-response operation may be defined using a 1917 single ExtendedRequest message to solicit zero or more 1918 IntermediateResponse messages of one or more kinds followed by an 1919 ExtendedResponse message. 1921 4.13.2. Usage with LDAP Request Controls 1923 A control's semantics may include the return of zero or more 1924 IntermediateResponse messages prior to returning the final result 1925 code for the operation. One or more kinds of IntermediateResponse 1926 messages may be sent in response to a request control. 1928 All IntermediateResponse messages associated with request controls 1929 SHALL include a responseName. This requirement ensures that the 1930 client can correctly identify the source of IntermediateResponse 1931 messages when: 1933 - two or more controls using IntermediateResponse messages are 1934 included in a request for any LDAP operation or 1936 - one or more controls using IntermediateResponse messages are 1937 included in a request with an LDAP Extended operation that uses 1938 IntermediateResponse messages. 1940 4.14. StartTLS Operation 1942 The Start Transport Layer Security (StartTLS) operation's purpose is 1943 to initiate installation of a TLS layer. The StartTLS operation is 1944 defined using the Extended operation mechanism described in Section 1945 4.12. 1947 4.14.1. StartTLS Request 1949 A client requests TLS establishment by transmitting a StartTLS 1950 request PDU to the server. The StartTLS request is defined in terms 1951 of an ExtendedRequest. The requestName is "1.3.6.1.4.1.1466.20037", 1952 and the requestValue field is always absent. 1954 The client MUST NOT send any PDUs at this LDAP message layer 1955 following this request until it receives a StartTLS Extended response 1956 and, in the case of a successful response, completes TLS 1957 negotiations. 1959 Lightweight Directory Access Protocol Version 3 1961 Detected sequencing problems (particularly those detailed in Section 1962 3.1.1 of [AuthMeth]) result in the resultCode being set to 1963 operationsError. 1965 If the server does not support TLS (whether by design or by current 1966 configuration), it returns with the resultCode set to protocolError 1967 as described in Section 4.12. 1969 4.14.2. StartTLS Response 1971 When a StartTLS request is made, servers supporting the operation 1972 MUST return a StartTLS response PDU to the requestor. The 1973 responseName, if present, is also "1.3.6.1.4.1.1466.20037". The 1974 responseValue is absent. 1976 If the server is willing and able to negotiate TLS, it returns with 1977 the resultCode set to success. Refer to Section 4 of [AuthMeth] for 1978 details. 1980 If the server is otherwise unwilling or unable to perform this 1981 operation, the server is to return an appropriate result code 1982 indicating the nature of the problem. For example, if the TLS 1983 subsystem is not presently available, the server may indicate so by 1984 returning with the resultCode set to unavailable. 1986 4.14.3. Removal of the TLS Layer 1988 Two forms of TLS layer removal -- graceful and abrupt -- are 1989 provided. These do not involve LDAP PDUs, but are preformed at the 1990 underlying layers. 1992 If the transport connection is closed, uncompleted operations are 1993 handled as specified in Section 5.1. 1995 4.14.3.1. Graceful Removal 1997 Either the client or server MAY remove the TLS layer and leave the 1998 LDAP message layer intact by sending and receiving a TLS closure 1999 alert. 2001 The initiating protocol peer sends the TLS closure alert. If it 2002 wishes to leave the LDAP message layer intact, it then MUST cease to 2003 send further PDUs and MUST ignore any received LDAP PDUs until it 2004 receives a TLS closure alert from the other peer. 2006 Once the initiating protocol peer receives a TLS closure alert from 2007 the other peer it MAY send and receive LDAP PDUs. 2009 Lightweight Directory Access Protocol Version 3 2011 When a protocol peer receives the initial TLS closure alert, it may 2012 choose to allow the LDAP message layer to remain intact. In this 2013 case, it MUST immediately transmit a TLS closure alert. Following 2014 this, it MAY send and receive LDAP PDUs. 2016 Protocol peers MAY close the transport connection after sending or 2017 receiving a TLS closure alert. 2019 After the TLS layer has been removed, the server MUST NOT send 2020 responses to any request message received before the TLS closure 2021 alert. Thus, clients wishing to receive responses to messages sent 2022 while the TLS layer is intact MUST wait for those message responses 2023 before sending the TLS closure alert. 2025 4.14.3.2. Abrupt Removal 2027 Either the client or server MAY abruptly remove the TLS layer by 2028 closing the transport connection. In this circumstance, a server MAY 2029 send the client a Notice of Disconnection before closing the 2030 transport connection. 2032 5. Protocol Encoding, Connection, and Transfer 2034 This protocol is designed to run over connection-oriented, reliable 2035 transports, where the data stream is divided into octets (8-bit 2036 units), with each octet and each bit being significant. 2038 One underlying service, LDAP over TCP, is defined in Section 2039 5.2. This service is generally applicable to applications providing 2040 or consuming X.500-based directory services on the Internet. This 2041 specification was generally written with the TCP mapping in mind. 2042 Specifications detailing other mappings may encounter various 2043 obstacles. 2045 Implementations of LDAP over TCP MUST implement the mapping as 2046 described in Section 5.2. 2048 This table illustrates the relationship between the different layers 2049 involved in an exchange between two protocol peers: 2051 +----------------------+ 2052 | LDAP message layer | 2053 +----------------------+ > LDAP PDUs 2054 +----------------------+ < data 2055 | SASL layer | 2056 +----------------------+ > SASL-protected data 2057 +----------------------+ < data 2058 | TLS layer | 2059 Application +----------------------+ > TLS-protected data 2060 ------------+----------------------+ < data 2061 Transport | transport connection | 2063 Lightweight Directory Access Protocol Version 3 2065 +----------------------+ 2067 5.1. Protocol Encoding 2069 The protocol elements of LDAP SHALL be encoded for exchange using the 2070 Basic Encoding Rules [BER] of [ASN.1] with the following 2071 restrictions: 2073 - Only the definite form of length encoding is used. 2075 - OCTET STRING values are encoded in the primitive form only. 2077 - If the value of a BOOLEAN type is true, the encoding of the value 2078 octet is set to hex "FF". 2080 - If a value of a type is its default value, it is absent. Only some 2081 BOOLEAN and INTEGER types have default values in this protocol 2082 definition. 2084 These restrictions are meant to ease the overhead of encoding and 2085 decoding certain elements in BER. 2087 These restrictions do not apply to ASN.1 types encapsulated inside of 2088 OCTET STRING values, such as attribute values, unless otherwise 2089 stated. 2091 5.2. Transmission Control Protocol (TCP) 2093 The encoded LDAPMessage PDUs are mapped directly onto the [TCP] 2094 bytestream using the BER-based encoding described in Section 5.1. It 2095 is recommended that server implementations running over the TCP 2096 provide a protocol listener on the Internet Assigned Numbers 2097 Authority (IANA)-assigned LDAP port, 389 [PortReg]. Servers may 2098 instead provide a listener on a different port number. Clients MUST 2099 support contacting servers on any valid TCP port. 2101 6. Security Considerations 2103 This version of the protocol provides facilities for simple 2104 authentication using a cleartext password, as well as any [SASL] 2105 mechanism. Installing SASL and/or TLS layers can provide integrity 2106 and other data security services. 2108 It is also permitted that the server can return its credentials to 2109 the client, if it chooses to do so. 2111 Use of cleartext password is strongly discouraged where the 2112 underlying transport service cannot guarantee confidentiality and may 2113 result in disclosure of the password to unauthorized parties. 2115 Lightweight Directory Access Protocol Version 3 2117 Servers are encouraged to prevent directory modifications by clients 2118 that have authenticated anonymously [AuthMeth]. 2120 Security considerations for authentication methods, SASL mechanisms, 2121 and TLS are described in [AuthMeth]. 2123 It should be noted that SASL authentication exchanges do not provide 2124 data confidentiality nor integrity protection for the version or name 2125 fields of the BindRequest nor the resultCode, diagnosticMessage, or 2126 referral fields of the BindResponse nor of any information contained 2127 in controls attached to Bind requests or responses. Thus information 2128 contained in these fields SHOULD NOT be relied on unless otherwise 2129 protected (such as by establishing protections at the transport 2130 layer). 2132 Server implementors should plan for the possibility of (protocol or 2133 external) events which alter the information used to establish 2134 security factors (e.g., credentials, authorization identities, access 2135 controls) during the course of the LDAP session, and even during the 2136 performance of a particular operation, and should take steps to avoid 2137 insecure side effects of these changes. The ways in which these 2138 issues are addressed are application and/or implementation specific. 2140 Implementations which cache attributes and entries obtained via LDAP 2141 MUST ensure that access controls are maintained if that information 2142 is to be provided to multiple clients, since servers may have access 2143 control policies which prevent the return of entries or attributes in 2144 Search results except to particular authenticated clients. For 2145 example, caches could serve result information only to the client 2146 whose request caused it to be in the cache. 2148 Servers may return referrals or Search result references which 2149 redirect clients to peer servers. It is possible for a rogue 2150 application to inject such referrals into the data stream in an 2151 attempt to redirect a client to a rogue server. Clients are advised 2152 to be aware of this, and possibly reject referrals when 2153 confidentiality measures are not in place. Clients are advised to 2154 reject referrals from the StartTLS operation. 2156 The matchedDN and diagnosticMessage fields, as well as some 2157 resultCode values (e.g., attributeOrValueExists and 2158 entryAlreadyExists), could disclose the presence or absence of 2159 specific data in the directory which is subject to access and other 2160 administrative controls. Server implementations should restrict 2161 access to protected information equally under both normal and error 2162 conditions. 2164 Protocol peers MUST be prepared to handle invalid and arbitrary 2165 length protocol encodings. Invalid protocol encodings include: BER 2166 encoding exceptions, format string and UTF-8 encoding exceptions, 2167 overflow exceptions, integer value exceptions, and binary mode on/off 2168 flag exceptions. The LDAPv3 PROTOS [PROTOS-LDAP] test suite provides 2169 excellent examples of these exceptions and test cases used to 2170 discover flaws. 2172 Lightweight Directory Access Protocol Version 3 2174 7. Acknowledgements 2176 This document is based on RFC 2251 by Mark Wahl, Tim Howes, and Steve 2177 Kille. RFC 2251 was a product of the IETF ASID Working Group. 2179 It is also based on RFC 2830 by Jeff Hodges, RL "Bob" Morgan, and 2180 Mark Wahl. RFC 2830 was a product of the IETF LDAPEXT Working Group. 2182 It is also based on RFC 3771 by Roger Harrison, and Kurt Zeilenga. 2183 RFC 3771 was an individual submission to the IETF. 2185 This document is a product of the IETF LDAPBIS Working Group. 2186 Significant contributors of technical review and content include Kurt 2187 Zeilenga, Steven Legg, and Hallvard Furuseth. 2189 8. Normative References 2191 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2192 Specifications: ABNF", RFC 2234, November 1997. 2194 [ASN.1] ITU-T Recommendation X.680 (07/2002) | ISO/IEC 8824-1:2002 2195 "Information Technology - Abstract Syntax Notation One 2196 (ASN.1): Specification of basic notation" 2198 [AuthMeth] Harrison, R., "LDAP: Authentication Methods and Connection 2199 Level Security Mechanisms", draft-ietf-ldapbis-authmeth- 2200 xx.txt, (a work in progress). 2202 [BER] ITU-T Rec. X.690 (07/2002) | ISO/IEC 8825-1:2002, 2203 "Information technology - ASN.1 encoding rules: 2204 Specification of Basic Encoding Rules (BER), Canonical 2205 Encoding Rules (CER) and Distinguished Encoding Rules 2206 (DER)", 2002. 2208 [IP] Postel, J., "Internet Protocol", STD5 and RFC 791, 2209 September 1981 2211 [ISO10646] Universal Multiple-Octet Coded Character Set (UCS) - 2212 Architecture and Basic Multilingual Plane, ISO/IEC 10646-1 2213 : 1993. 2215 [Keyword] Bradner, S., "Key words for use in RFCs to Indicate 2216 Requirement Levels", RFC 2119, March 1997. 2218 [LDAPDN] Zeilenga, K., "LDAP: String Representation of 2219 Distinguished Names", draft-ietf-ldapbis-dn-xx.txt, (a 2220 work in progress). 2222 [LDAPIANA] Zeilenga, K., "IANA Considerations for LDAP", draft-ietf- 2223 ldapbis-bcp64-xx.txt, (a work in progress). 2225 Lightweight Directory Access Protocol Version 3 2227 [LDAPURL] Smith, M., "LDAP: Uniform Resource Locator", draft-ietf- 2228 ldapbis-url-xx.txt, (a work in progress). 2230 [Models] Zeilenga, K., "LDAP: Directory Information Models", draft- 2231 ietf-ldapbis-models-xx.txt (a work in progress). 2233 [Roadmap] Zeilenga, K., "LDAP: Technical Specification Road Map", 2234 draft-ietf-ldapbis-roadmap-xx.txt (a work in progress). 2236 [SASL] Melnikov, A., "Simple Authentication and Security Layer", 2237 draft-ietf-sasl-rfc2222bis-xx.txt (a work in progress). 2239 [SASLPrep] Zeilenga, K., "Stringprep profile for user names and 2240 passwords", draft-ietf-sasl-saslprep-xx.txt, (a work in 2241 progress). 2243 [StringPrep] Hoffman P. and M. Blanchet, "Preparation of 2244 Internationalized Strings ('stringprep')", draft-hoffman- 2245 rfc3454bis-xx.txt, a work in progress. 2247 [Syntaxes] Legg, S., and K. Dally, "LDAP: Syntaxes and Matching 2248 Rules", draft-ietf-ldapbis-syntaxes-xx.txt, (a work in 2249 progress). 2251 [TCP] Postel, J., "Transmission Control Protocol", STD7 and RFC 2252 793, September 1981 2254 [TLS] Dierks, T. and C. Allen. "The TLS Protocol Version 1.1", 2255 draft-ietf-tls-rfc2246-bis-xx.txt, a work in progress. 2257 [Unicode] The Unicode Consortium, "The Unicode Standard, Version 2258 3.2.0" is defined by "The Unicode Standard, Version 3.0" 2259 (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5), 2260 as amended by the "Unicode Standard Annex #27: Unicode 2261 3.1" (http://www.unicode.org/reports/tr27/) and by the 2262 "Unicode Standard Annex #28: Unicode 3.2" 2263 (http://www.unicode.org/reports/tr28/). 2265 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2266 Resource Identifiers (URI): Generic Syntax", RFC 2396, 2267 August 1998. 2269 [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO 2270 10646", STD63 and RFC3629, November 2003. 2272 [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts, 2273 Models and Service", 1993. 2275 [X.501] ITU-T Rec. X.501, "The Directory: Models", 1993. 2277 [X.511] ITU-T Rec. X.511, "The Directory: Abstract Service 2278 Definition", 1993. 2280 Lightweight Directory Access Protocol Version 3 2282 9. Informative References 2284 [Glossary] The Unicode Consortium, "Unicode Glossary", 2285 . 2287 [CharModel] Whistler, K. and M. Davis, "Unicode Technical Report 2288 #17, Character Encoding Model", UTR17, 2289 , August 2290 2000. 2292 [PROTOS-LDAP] University of Oulu, "PROTOS Test-Suite: c06-ldapv3" 2293 2296 [PortReg] IANA, "Port Numbers", 2297 http://www.iana.org/assignments/port-numbers 2299 10. IANA Considerations 2301 It is requested that the Internet Assigned Numbers Authority (IANA) 2302 update the LDAP result code registry to indicate that this document 2303 provides the definitive technical specification for result codes 0- 2304 36, 48-54, 64-70, 80-90. 2306 It is requested that the IANA update the LDAP Protocol Mechanism 2307 registry to indicate that this document and [AuthMeth] provides the 2308 definitive technical specification for the StartTLS 2309 (1.3.6.1.4.1.1466.20037) Extended operation. 2311 It is requested that the IANA update the occurrence of "RFC XXXX" in 2312 Appendix B with this RFC number at publication. 2314 11. Editor's Address 2316 Jim Sermersheim 2317 Novell, Inc. 2318 1800 South Novell Place 2319 Provo, Utah 84606, USA 2320 jimse@novell.com 2321 +1 801 861-3088 2323 Lightweight Directory Access Protocol Version 3 2325 Appendix A - LDAP Result Codes 2327 This normative appendix details additional considerations regarding 2328 LDAP result codes and provides a brief, general description of each 2329 LDAP result code enumerated in Section 4.1.9. 2331 Additional result codes MAY be defined for use with extensions 2332 [LDAPIANA]. Client implementations SHALL treat any result code which 2333 they do not recognize as an unknown error condition. 2335 Servers may substitute some result codes due to access controls which 2336 prevent their disclosure. 2338 A.1 Non-Error Result Codes 2340 These result codes (called "non-error" result codes) do not indicate 2341 an error condition: 2342 success (0), 2343 compareFalse (5), 2344 compareTrue (6), 2345 referral (10), and 2346 saslBindInProgress (14). 2348 The success, compareTrue, and compareFalse result codes indicate 2349 successful completion (and, hence, are referred to as "successful" 2350 result codes). 2352 The referral and saslBindInProgress result codes indicate the client 2353 needs to take additional action to complete the operation. 2355 A.2 Result Codes 2357 Existing LDAP result codes are described as follows: 2359 success (0) 2360 Indicates the successful completion of an operation. Note: 2361 this code is not used with the Compare operation. See 2362 compareFalse (5) and compareTrue (6). 2364 operationsError (1) 2365 Indicates that the operation is not properly sequenced with 2366 relation to other operations (of same or different type). 2368 For example, this code is returned if the client attempts to 2369 StartTLS [TLS] while there are other uncompleted operations 2370 or if a TLS layer was already installed. 2372 protocolError (2) 2373 Indicates the server received data which is not well-formed. 2375 Lightweight Directory Access Protocol Version 3 2377 For Bind operation only, this code is also used to indicate 2378 that the server does not support the requested protocol 2379 version. 2381 For Extended operations only, this code is also used to 2382 indicate that the server does not support (by design or 2383 configuration) the Extended operation associated with the 2384 requestName. 2386 For request operations specifying multiple controls, this may 2387 be used to indicate that the server cannot ignore the order 2388 of the controls as specified, or that the combination of the 2389 specified controls is invalid or unspecified. 2391 timeLimitExceeded (3) 2392 Indicates that the time limit specified by the client was 2393 exceeded before the operation could be completed. 2395 sizeLimitExceeded (4) 2396 Indicates that the size limit specified by the client was 2397 exceeded before the operation could be completed. 2399 compareFalse (5) 2400 Indicates that the Compare operation has successfully 2401 completed and the assertion has evaluated to FALSE or 2402 Undefined. 2404 compareTrue (6) 2405 Indicates that the Compare operation has successfully 2406 completed and the assertion has evaluated to TRUE. 2408 authMethodNotSupported (7) 2409 Indicates that the authentication method or mechanism is not 2410 supported. 2412 strongAuthRequired (8) 2413 Indicates the server requires the client to authenticate 2414 using a strong(er) mechanism. 2416 When used with the Notice of Disconnection operation, this 2417 code indicates that the server has detected that an 2418 established security association between the client and 2419 server has unexpectedly failed or been compromised. 2421 referral (10) 2422 Indicates that a referral needs to be chased to complete the 2423 operation (see Section 4.1.10). 2425 adminLimitExceeded (11) 2426 Indicates that an administrative limit has been exceeded. 2428 unavailableCriticalExtension (12) 2429 Indicates a critical control is unrecognized (see Section 2430 4.1.11). 2432 Lightweight Directory Access Protocol Version 3 2434 confidentialityRequired (13) 2435 Indicates that data confidentiality protections are required. 2437 saslBindInProgress (14) 2438 Indicates the server requires the client to send a new bind 2439 request, with the same SASL mechanism, to continue the 2440 authentication process (see Section 4.2). 2442 noSuchAttribute (16) 2443 Indicates that the named entry does not contain the specified 2444 attribute or attribute value. 2446 undefinedAttributeType (17) 2447 Indicates that a request field contains an unrecognized 2448 attribute description. 2450 inappropriateMatching (18) 2451 Indicates that an attempt was made (e.g. in an assertion) to 2452 use a matching rule not defined for the attribute type 2453 concerned. 2455 constraintViolation (19) 2456 Indicates that the client supplied an attribute value which 2457 does not conform to the constraints placed upon it by the 2458 data model. 2460 For example, this code is returned when multiple values are 2461 supplied to an attribute which has a SINGLE-VALUE constraint. 2463 attributeOrValueExists (20) 2464 Indicates that the client supplied an attribute or value to 2465 be added to an entry, but the attribute or value already 2466 exists. 2468 invalidAttributeSyntax (21) 2469 Indicates that a purported attribute value does not conform 2470 to the syntax of the attribute. 2472 noSuchObject (32) 2473 Indicates that the object does not exist in the DIT. 2475 aliasProblem (33) 2476 Indicates that an alias problem has occurred. For example, 2477 the code may used to indicate an alias has been dereferenced 2478 which names no object. 2480 invalidDNSyntax (34) 2481 Indicates that an LDAPDN or RelativeLDAPDN field (e.g. search 2482 base, target entry, ModifyDN newrdn, etc.) of a request does 2483 not conform to the required syntax or contains attribute 2484 values which do not conform to the syntax of the attribute's 2485 type. 2487 Lightweight Directory Access Protocol Version 3 2489 aliasDereferencingProblem (36) 2490 Indicates that a problem occurred while dereferencing an 2491 alias. Typically an alias was encountered in a situation 2492 where it was not allowed or where access was denied. 2494 inappropriateAuthentication (48) 2495 Indicates the server requires the client which had attempted 2496 to bind anonymously or without supplying credentials to 2497 provide some form of credentials. 2499 invalidCredentials (49) 2500 Indicates that the provided credentials (e.g. the user's name 2501 and password) are invalid. 2503 insufficientAccessRights (50) 2504 Indicates that the client does not have sufficient access 2505 rights to perform the operation. 2507 busy (51) 2508 Indicates that the server is too busy to service the 2509 operation. 2511 unavailable (52) 2512 Indicates that the server is shutting down or a subsystem 2513 necessary to complete the operation is offline. 2515 unwillingToPerform (53) 2516 Indicates that the server is unwilling to perform the 2517 operation. 2519 loopDetect (54) 2520 Indicates that the server has detected an internal loop (e.g. 2521 while dereferencing aliases or chaining an operation). 2523 namingViolation (64) 2524 Indicates that the entry's name violates naming restrictions. 2526 objectClassViolation (65) 2527 Indicates that the entry violates object class restrictions. 2529 notAllowedOnNonLeaf (66) 2530 Indicates that the operation is inappropriately acting upon a 2531 non-leaf entry. 2533 notAllowedOnRDN (67) 2534 Indicates that the operation is inappropriately attempting to 2535 remove a value which forms the entry's relative distinguished 2536 name. 2538 entryAlreadyExists (68) 2539 Indicates that the request cannot be fulfilled (added, moved, 2540 or renamed) as the target entry already exists. 2542 objectClassModsProhibited (69) 2544 Lightweight Directory Access Protocol Version 3 2546 Indicates that an attempt to modify the object class(es) of 2547 an entry's 'objectClass' attribute is prohibited. 2549 For example, this code is returned when a client attempts to 2550 modify the structural object class of an entry. 2552 affectsMultipleDSAs (71) 2553 Indicates that the operation cannot be performed as it would 2554 affect multiple servers (DSAs). 2556 other (80) 2557 Indicates the server has encountered an internal error. 2559 Lightweight Directory Access Protocol Version 3 2561 Appendix B - Complete ASN.1 Definition 2563 This appendix is normative. 2565 Lightweight-Directory-Access-Protocol-V3 2566 -- Copyright (C) The Internet Society (2004). This version of 2567 -- this ASN.1 module is part of RFC XXXX; see the RFC itself 2568 -- for full legal notices. 2569 DEFINITIONS 2570 IMPLICIT TAGS 2571 EXTENSIBILITY IMPLIED ::= 2573 BEGIN 2575 LDAPMessage ::= SEQUENCE { 2576 messageID MessageID, 2577 protocolOp CHOICE { 2578 bindRequest BindRequest, 2579 bindResponse BindResponse, 2580 unbindRequest UnbindRequest, 2581 searchRequest SearchRequest, 2582 searchResEntry SearchResultEntry, 2583 searchResDone SearchResultDone, 2584 searchResRef SearchResultReference, 2585 modifyRequest ModifyRequest, 2586 modifyResponse ModifyResponse, 2587 addRequest AddRequest, 2588 addResponse AddResponse, 2589 delRequest DelRequest, 2590 delResponse DelResponse, 2591 modDNRequest ModifyDNRequest, 2592 modDNResponse ModifyDNResponse, 2593 compareRequest CompareRequest, 2594 compareResponse CompareResponse, 2595 abandonRequest AbandonRequest, 2596 extendedReq ExtendedRequest, 2597 extendedResp ExtendedResponse, 2598 ..., 2599 intermediateResponse IntermediateResponse }, 2600 controls [0] Controls OPTIONAL } 2602 MessageID ::= INTEGER (0 .. maxInt) 2604 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) -- 2606 LDAPString ::= OCTET STRING -- UTF-8 encoded, 2607 -- [ISO10646] characters 2609 LDAPOID ::= OCTET STRING -- Constrained to [Models] 2611 LDAPDN ::= LDAPString -- Constrained to 2612 -- [LDAPDN] 2614 RelativeLDAPDN ::= LDAPString -- Constrained to 2616 Lightweight Directory Access Protocol Version 3 2618 -- [LDAPDN] 2620 AttributeDescription ::= LDAPString 2621 -- Constrained to 2622 -- [Models] 2624 AttributeValue ::= OCTET STRING 2626 AttributeValueAssertion ::= SEQUENCE { 2627 attributeDesc AttributeDescription, 2628 assertionValue AssertionValue } 2630 AssertionValue ::= OCTET STRING 2632 PartialAttribute ::= SEQUENCE { 2633 type AttributeDescription, 2634 vals SET OF value AttributeValue } 2636 Attribute ::= PartialAttribute(WITH COMPONENTS { 2637 ..., 2638 vals (SIZE(1..MAX))}) 2640 MatchingRuleId ::= LDAPString 2642 LDAPResult ::= SEQUENCE { 2643 resultCode ENUMERATED { 2644 success (0), 2645 operationsError (1), 2646 protocolError (2), 2647 timeLimitExceeded (3), 2648 sizeLimitExceeded (4), 2649 compareFalse (5), 2650 compareTrue (6), 2651 authMethodNotSupported (7), 2652 strongAuthRequired (8), 2653 -- 9 reserved -- 2654 referral (10), 2655 adminLimitExceeded (11), 2656 unavailableCriticalExtension (12), 2657 confidentialityRequired (13), 2658 saslBindInProgress (14), 2659 noSuchAttribute (16), 2660 undefinedAttributeType (17), 2661 inappropriateMatching (18), 2662 constraintViolation (19), 2663 attributeOrValueExists (20), 2664 invalidAttributeSyntax (21), 2665 -- 22-31 unused -- 2666 noSuchObject (32), 2667 aliasProblem (33), 2668 invalidDNSyntax (34), 2669 -- 35 reserved for undefined isLeaf -- 2670 aliasDereferencingProblem (36), 2671 -- 37-47 unused -- 2673 Lightweight Directory Access Protocol Version 3 2675 inappropriateAuthentication (48), 2676 invalidCredentials (49), 2677 insufficientAccessRights (50), 2678 busy (51), 2679 unavailable (52), 2680 unwillingToPerform (53), 2681 loopDetect (54), 2682 -- 55-63 unused -- 2683 namingViolation (64), 2684 objectClassViolation (65), 2685 notAllowedOnNonLeaf (66), 2686 notAllowedOnRDN (67), 2687 entryAlreadyExists (68), 2688 objectClassModsProhibited (69), 2689 -- 70 reserved for CLDAP -- 2690 affectsMultipleDSAs (71), 2691 -- 72-79 unused -- 2692 other (80), 2693 ... }, 2694 matchedDN LDAPDN, 2695 diagnosticMessage LDAPString, 2696 referral [3] Referral OPTIONAL } 2698 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI 2700 URI ::= LDAPString -- limited to characters permitted in 2701 -- URIs 2703 Controls ::= SEQUENCE OF control Control 2705 Control ::= SEQUENCE { 2706 controlType LDAPOID, 2707 criticality BOOLEAN DEFAULT FALSE, 2708 controlValue OCTET STRING OPTIONAL } 2710 BindRequest ::= [APPLICATION 0] SEQUENCE { 2711 version INTEGER (1 .. 127), 2712 name LDAPDN, 2713 authentication AuthenticationChoice } 2715 AuthenticationChoice ::= CHOICE { 2716 simple [0] OCTET STRING, 2717 -- 1 and 2 reserved 2718 sasl [3] SaslCredentials, 2719 ... } 2721 SaslCredentials ::= SEQUENCE { 2722 mechanism LDAPString, 2723 credentials OCTET STRING OPTIONAL } 2725 BindResponse ::= [APPLICATION 1] SEQUENCE { 2726 COMPONENTS OF LDAPResult, 2727 serverSaslCreds [7] OCTET STRING OPTIONAL } 2729 Lightweight Directory Access Protocol Version 3 2731 UnbindRequest ::= [APPLICATION 2] NULL 2733 SearchRequest ::= [APPLICATION 3] SEQUENCE { 2734 baseObject LDAPDN, 2735 scope ENUMERATED { 2736 baseObject (0), 2737 singleLevel (1), 2738 wholeSubtree (2), 2739 ... }, 2740 derefAliases ENUMERATED { 2741 neverDerefAliases (0), 2742 derefInSearching (1), 2743 derefFindingBaseObj (2), 2744 derefAlways (3) }, 2745 sizeLimit INTEGER (0 .. maxInt), 2746 timeLimit INTEGER (0 .. maxInt), 2747 typesOnly BOOLEAN, 2748 filter Filter, 2749 attributes AttributeSelection } 2751 AttributeSelection ::= SEQUENCE OF selector LDAPString 2752 -- The LDAPString is constrained to 2753 -- in Section 4.5.1 2755 Filter ::= CHOICE { 2756 and [0] SET SIZE (1..MAX) OF filter Filter, 2757 or [1] SET SIZE (1..MAX) OF filter Filter, 2758 not [2] Filter, 2759 equalityMatch [3] AttributeValueAssertion, 2760 substrings [4] SubstringFilter, 2761 greaterOrEqual [5] AttributeValueAssertion, 2762 lessOrEqual [6] AttributeValueAssertion, 2763 present [7] AttributeDescription, 2764 approxMatch [8] AttributeValueAssertion, 2765 extensibleMatch [9] MatchingRuleAssertion, 2766 ... } 2768 SubstringFilter ::= SEQUENCE { 2769 type AttributeDescription, 2770 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE { 2771 initial [0] AssertionValue, -- can occur at most once 2772 any [1] AssertionValue, 2773 final [2] AssertionValue } -- can occur at most once 2774 } 2776 MatchingRuleAssertion ::= SEQUENCE { 2777 matchingRule [1] MatchingRuleId OPTIONAL, 2778 type [2] AttributeDescription OPTIONAL, 2779 matchValue [3] AssertionValue, 2780 dnAttributes [4] BOOLEAN DEFAULT FALSE } 2782 SearchResultEntry ::= [APPLICATION 4] SEQUENCE { 2783 objectName LDAPDN, 2784 attributes PartialAttributeList } 2786 Lightweight Directory Access Protocol Version 3 2788 PartialAttributeList ::= SEQUENCE OF 2789 partialAttribute PartialAttribute 2791 SearchResultReference ::= [APPLICATION 19] SEQUENCE 2792 SIZE (1..MAX) OF uri URI 2794 SearchResultDone ::= [APPLICATION 5] LDAPResult 2796 ModifyRequest ::= [APPLICATION 6] SEQUENCE { 2797 object LDAPDN, 2798 changes SEQUENCE OF change SEQUENCE { 2799 operation ENUMERATED { 2800 add (0), 2801 delete (1), 2802 replace (2), 2803 ... }, 2804 modification PartialAttribute } } 2806 ModifyResponse ::= [APPLICATION 7] LDAPResult 2808 AddRequest ::= [APPLICATION 8] SEQUENCE { 2809 entry LDAPDN, 2810 attributes AttributeList } 2812 AttributeList ::= SEQUENCE OF attribute Attribute 2814 AddResponse ::= [APPLICATION 9] LDAPResult 2816 DelRequest ::= [APPLICATION 10] LDAPDN 2818 DelResponse ::= [APPLICATION 11] LDAPResult 2820 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE { 2821 entry LDAPDN, 2822 newrdn RelativeLDAPDN, 2823 deleteoldrdn BOOLEAN, 2824 newSuperior [0] LDAPDN OPTIONAL } 2826 ModifyDNResponse ::= [APPLICATION 13] LDAPResult 2828 CompareRequest ::= [APPLICATION 14] SEQUENCE { 2829 entry LDAPDN, 2830 ava AttributeValueAssertion } 2832 CompareResponse ::= [APPLICATION 15] LDAPResult 2834 AbandonRequest ::= [APPLICATION 16] MessageID 2836 ExtendedRequest ::= [APPLICATION 23] SEQUENCE { 2837 requestName [0] LDAPOID, 2838 requestValue [1] OCTET STRING OPTIONAL } 2840 ExtendedResponse ::= [APPLICATION 24] SEQUENCE { 2842 Lightweight Directory Access Protocol Version 3 2844 COMPONENTS OF LDAPResult, 2845 responseName [10] LDAPOID OPTIONAL, 2846 responseValue [11] OCTET STRING OPTIONAL } 2848 IntermediateResponse ::= [APPLICATION 25] SEQUENCE { 2849 responseName [0] LDAPOID OPTIONAL, 2850 responseValue [1] OCTET STRING OPTIONAL } 2852 END 2854 Lightweight Directory Access Protocol Version 3 2856 Appendix C - Changes 2858 This appendix is non-normative. 2860 This appendix summarizes substantive changes made to RFC 2251, RFC 2861 2830, and RFC 3771. 2863 C.1 Changes made to RFC 2251: 2865 This section summarizes the substantive changes made to Sections 1, 2866 2, 3.1, and 4 through the remainder of RFC 2251. Readers should 2867 consult [Models] and [AuthMeth] for summaries of changes to other 2868 sections. 2870 C.1.1 Section 1 (Status of this Memo) 2872 - Removed IESG note. Post publication of RFC 2251, mandatory LDAP 2873 authentication mechanisms have been standardized which are 2874 sufficient to remove this note. See [AuthMeth] for authentication 2875 mechanisms. 2877 C.1.2 Section 3.1 (Protocol Model) and others 2879 - Removed notes giving history between LDAP v1, v2 and v3. Instead, 2880 added sufficient language so that this document can stand on its 2881 own. 2883 C.1.3 Section 4 (Elements of Protocol) 2885 - Clarified where the extensibility features of ASN.1 apply to the 2886 protocol. This change affected various ASN.1 types by the 2887 inclusion of ellipses (...) to certain elements. 2888 - Removed the requirement that servers which implement version 3 or 2889 later MUST provide the 'supportedLDAPVersion' attribute. This 2890 statement provided no interoperability advantages. 2892 C.1.4 Section 4.1.1 (Message Envelope) 2894 - There was a mandatory requirement for the server to return a 2895 Notice of Disconnection and drop the transport connection when a 2896 PDU is malformed in a certain way. This has been updated such that 2897 the server SHOULD return the Notice of Disconnection, and MUST 2898 drop the transport connection. 2900 C.1.5 Section 4.1.1.1 (Message ID) 2902 - Required that the messageID of requests MUST be non-zero as the 2903 zero is reserved for Notice of Disconnection. 2905 Lightweight Directory Access Protocol Version 3 2907 - Specified when it is and isn't appropriate to return an already 2908 used message id. RFC 2251 accidentally imposed synchronous server 2909 behavior in its wording of this. 2911 C.1.6 Section 4.1.2 (String Types) 2913 - Stated that LDAPOID is constrained to from [Models]. 2915 C.1.7 Section 4.1.5.1 (Binary Option) and others 2917 - Removed the Binary Option from the specification. There are 2918 numerous interoperability problems associated with this method of 2919 alternate attribute type encoding. Work to specify a suitable 2920 replacement is ongoing. 2922 C.1.8 Section 4.1.8 (Attribute) 2924 - Combined the definitions of PartialAttribute and Attribute here, 2925 and defined Attribute in terms of PartialAttribute. 2927 C.1.9 Section 4.1.10 (Result Message) 2929 - Renamed "errorMessage" to "diagnosticMessage" as it is allowed to 2930 be sent for non-error results. 2931 - Moved some language into Appendix A, and refer the reader there. 2932 - Allowed matchedDN to be present for other result codes than those 2933 listed in RFC 2251. 2935 C.1.10 Section 4.1.11 (Referral) 2937 - Defined referrals in terms of URIs rather than URLs. 2938 - Removed the requirement that all referral URIs MUST be equally 2939 capable of progressing the operation. The statement was ambiguous 2940 and provided no instructions on how to carry it out. 2941 - Added the requirement that clients MUST NOT loop between servers. 2942 - Clarified the instructions for using LDAPURLs in referrals, and in 2943 doing so added a recommendation that the scope part be present. 2944 - Removed imperatives which required clients to use URLs in specific 2945 ways to progress an operation. These did nothing for 2946 interoperability. 2948 C.1.11 Section 4.1.12 (Controls) 2950 - Specified how control values defined in terms of ASN.1 are to be 2951 encoded. 2952 - Noted that the criticality field is only applied to request 2953 messages (except UnbindRequest), and must be ignored when present 2954 on response messages and UnbindRequest. 2956 Lightweight Directory Access Protocol Version 3 2958 - Added language regarding combinations of controls and the ordering 2959 of controls on a message. 2960 - Specified that when the semantics of the combination of controls 2961 is undefined or unknown, it results in a protocolError. 2962 - Changed "The server MUST be prepared" to "Implementations MUST be 2963 prepared" in the eighth paragraph to reflect that both client and 2964 server implementations must be able to handle this (as both parse 2965 controls). 2967 C.1.12 Section 4.2 (Bind Operation) 2969 - Mandated that servers return protocolError when the version is not 2970 supported. 2971 - Disambiguated behavior when the simple authentication is used, the 2972 name is empty and the password is non-empty. 2973 - Required servers to not dereference aliases for Bind. This was 2974 added for consistency with other operations and to help ensure 2975 data consistency. 2976 - Required that textual passwords be transferred as UTF-8 encoded 2977 Unicode, and added recommendations on string preparation. This was 2978 to help ensure interoperability of passwords being sent from 2979 different clients. 2981 C.1.13 Section 4.2.1 (Sequencing of the Bind Request) 2983 - This section was largely reorganized for readability and language 2984 was added to clarify the authentication state of failed and 2985 abandoned Bind operations. 2986 - Removed: "If a SASL transfer encryption or integrity mechanism has 2987 been negotiated, that mechanism does not support the changing of 2988 credentials from one identity to another, then the client MUST 2989 instead establish a new connection." 2990 If there are dependencies between multiple negotiations of a 2991 particular SASL mechanism, the technical specification for that 2992 SASL mechanism details how applications are to deal with them. 2993 LDAP should not require any special handling. 2994 - Dropped MUST imperative in paragraph 3 to align with [Keywords]. 2995 - Mandated that clients not send non-Bind operations while a Bind is 2996 in progress, and suggested that servers not process them if they 2997 are received. This is needed to ensure proper sequencing of the 2998 Bind in relationship to other operations. 3000 C.1.14 Section 4.2.3 (Bind Response) 3002 - Moved most error-related text to Appendix A, and added text 3003 regarding certain errors used in conjunction with the Bind 3004 operation. 3005 - Prohibited the server from specifying serverSaslCreds when not 3006 appropriate. 3008 Lightweight Directory Access Protocol Version 3 3010 C.1.15 Section 4.3 (Unbind Operation) 3012 - Specified that both peers are to cease transmission and close the 3013 transport connection for the Unbind operation. 3015 C.1.16 Section 4.4 (Unsolicited Notification) 3017 - Added instructions for future specifications of Unsolicited 3018 Notifications. 3020 C.1.17 Section 4.5.1 (Search Request) 3022 - SearchRequest attributes is now defined as an AttributeSelection 3023 type rather than AttributeDescriptionList, and an ABNF is 3024 provided. 3025 - SearchRequest attributes may contain duplicate attribute 3026 descriptions. This was previously prohibited. Now servers are 3027 instructed to ignore subsequent names when they are duplicated. 3028 This was relaxed in order to allow different short names and also 3029 OIDs to be requested for an attribute. 3030 - The Filter choice SubstringFilter substrings type is now defined 3031 with a lower bound of 1. 3032 - The SubstringFilter substrings 'initial, 'any', and 'final' types 3033 are now AssertionValue rather than LDAPString. Also, added 3034 imperatives stating that 'initial' (if present) must be listed 3035 first, and 'final' (if present) must be listed last. 3036 - Disambiguated the semantics of the derefAliases choices. There was 3037 question as to whether derefInSearching applied to the base object 3038 in a wholeSubtree Search. 3039 - Added instructions for equalityMatch, substrings, greaterOrEqual, 3040 lessOrEqual, and approxMatch. 3042 C.1.18 Section 4.5.2 (Search Result) 3044 - Recommended that servers not use attribute short names when it 3045 knows they are ambiguous or may cause interoperability problems. 3046 - Removed all mention of ExtendedResponse due to lack of 3047 implementation. 3049 C.1.19 Section 4.5.3 (Continuation References in the Search Result) 3051 - Made changes similar to those made to Section 4.1.11. 3053 C.1.20 Section 4.5.3.1 (Example) 3055 - Fixed examples to adhere to changes made to Section 4.5.3. 3057 C.1.21 Section 4.6 (Modify Operation) 3059 Lightweight Directory Access Protocol Version 3 3061 - Replaced AttributeTypeAndValues with Attribute as they are 3062 equivalent. 3063 - Spcified the types of modification changes which might temporarily 3064 violate schema. Some readers were under the impression that any 3065 temporary schema violation was allowed. 3067 C.1.22 Section 4.7 (Add Operation) 3069 - Aligned Add operation with X.511 in that the attributes of the RDN 3070 are used in conjunction with the listed attributes to create the 3071 entry. Previously, Add required that the distinguished values be 3072 present in the listed attributes. 3073 - Removed requirement that the objectclass attribute MUST be 3074 specified as some DSE types do not require this attribute. 3075 Instead, generic wording was added, requiring the added entry to 3076 adhere to the data model. 3077 - Removed recommendation regarding placement of objects. This is 3078 covered in the data model document. 3080 C.1.23 Section 4.9 (Modify DN Operation) 3082 - Required servers to not dereference aliases for Modify DN. This 3083 was added for consistency with other operations and to help ensure 3084 data consistency. 3085 - Allow Modify DN to fail when moving between naming contexts. 3086 - Specified what happens when the attributes of the newrdn are not 3087 present on the entry. 3089 C.1.24 Section 4.10 (Compare Operation) 3091 - Specified that compareFalse means that the Compare took place and 3092 the result is false. There was confusion which lead people to 3093 believe that an Undefined match resulted in compareFalse. 3094 - Required servers to not dereference aliases for Compare. This was 3095 added for consistency with other operations and to help ensure 3096 data consistency. 3098 C.1.25 Section 4.11 (Abandon Operation) 3100 - Explained that since Abandon returns no response, clients should 3101 not use it if they need to know the outcome. 3102 - Specified that Abandon and Unbind cannot be abandoned. 3104 C.1.26 Section 4.12 (Extended Operation) 3106 - Specified how values of Extended operations defined in terms of 3107 ASN.1 are to be encoded. 3109 Lightweight Directory Access Protocol Version 3 3111 - Added instructions on what Extended operation specifications 3112 consist of. 3113 - Added a recommendation that servers advertise supported Extended 3114 operations. 3116 C.1.27 Section 5.2 (Transfer Protocols) 3118 - Moved referral-specific instructions into referral-related 3119 sections. 3121 C.1.28 Section 7 (Security Considerations) 3123 - Reworded notes regarding SASL not protecting certain aspects of 3124 the LDAP Bind PDUs. 3125 - Noted that Servers are encouraged to prevent directory 3126 modifications by clients that have authenticated anonymously 3127 [AuthMeth]. 3128 - Added a note regarding the scenario where an identity is changed 3129 (deleted, privileges or credentials modified, etc.). 3130 - Warned against following referrals that may have been injected in 3131 the data stream. 3132 - Noted that servers should protect information equally, whether in 3133 an error condition or not, and mentioned specifically; matchedDN, 3134 diagnosticMessage, and resultCodes. 3135 - Added a note regarding malformed and long encodings. 3137 C.1.29 Appendix A (Complete ASN.1 Definition) 3139 - Added "EXTENSIBILITY IMPLIED" to ASN.1 definition. 3140 - Removed AttributeType. It is not used. 3142 C.2 Changes made to RFC 2830: 3144 This section summarizes the substantive changes made to Sections of 3145 RFC 2830. Readers should consult [AuthMeth] for summaries of changes 3146 to other sections. 3148 C.2.1 Section 2.3 (Response other than "success") 3150 - Removed wording indicating that referrals can be returned from 3151 StartTLS. 3152 - Removed requirement that only a narrow set of result codes can be 3153 returned. Some result codes are required in certain scenarios, but 3154 any other may be returned if appropriate. 3156 C.2.1 Section 4 (Closing a TLS Connection) 3158 Lightweight Directory Access Protocol Version 3 3160 - Reworded most of this section and added the requirement that after 3161 the TLS connection has been closed, the server MUST NOT send 3162 responses to any request message received before the TLS closure. 3164 C.3 Changes made to RFC 3771: 3166 - Rewrote to fit into this document. In general, semantics were 3167 preserved. Supporting and background language seen as redundant 3168 due to its presence in this document was omitted. 3169 - Specified that Intermediate responses to a request may be of 3170 different types, and one of the response types may be specified to 3171 have no response value. 3173 Lightweight Directory Access Protocol Version 3 3175 Intellectual Property Statement 3177 The IETF takes no position regarding the validity or scope of any 3178 Intellectual Property Rights or other rights that might be claimed to 3179 pertain to the implementation or use of the technology described in 3180 this document or the extent to which any license under such rights 3181 might or might not be available; nor does it represent that it has 3182 made any independent effort to identify any such rights. Information 3183 on the procedures with respect to rights in RFC documents can be 3184 found in BCP 78 and BCP 79. 3186 Copies of IPR disclosures made to the IETF Secretariat and any 3187 assurances of licenses to be made available, or the result of an 3188 attempt made to obtain a general license or permission for the use of 3189 such proprietary rights by implementers or users of this 3190 specification can be obtained from the IETF on-line IPR repository at 3191 . 3193 The IETF invites any interested party to bring to its attention any 3194 copyrights, patents or patent applications, or other proprietary 3195 rights that may cover technology that may be required to implement 3196 this standard. Please address the information to the IETF at ietf- 3197 ipr@ietf.org. 3199 Disclaimer of Validity 3201 This document and the information contained herein are provided on an 3202 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 3203 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 3204 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 3205 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 3206 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 3207 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3209 Copyright Statement 3211 Copyright (C) The Internet Society (2004). This document is subject 3212 to the rights, licenses and restrictions contained in BCP 78, and 3213 except as set forth therein, the authors retain all their rights. 3215 Acknowledgement 3217 Funding for the RFC Editor function is currently provided by the 3218 Internet Society.