idnits 2.17.1 draft-ietf-ldapbis-protocol-32.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 on line 15. -- Found old boilerplate from RFC 3978, Section 5.5 on line 3237. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 3214. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 3221. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 3227. ** 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. == 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: ---------------------------------------------------------------------------- No issues found here. 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 (Oct 2005) is 6768 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 2866 -- Looks like a reference, but probably isn't: '3' on line 2800 == Missing Reference: 'APPLICATION 0' is mentioned on line 2732, but not defined == Missing Reference: 'SASLprep' is mentioned on line 784, but not defined == Missing Reference: 'Stringprep' is mentioned on line 785, but not defined == Missing Reference: 'APPLICATION 1' is mentioned on line 2747, but not defined -- Looks like a reference, but probably isn't: '7' on line 2784 == Missing Reference: 'APPLICATION 2' is mentioned on line 2751, but not defined == Missing Reference: 'APPLICATION 3' is mentioned on line 2753, but not defined -- Looks like a reference, but probably isn't: '1' on line 2867 -- Looks like a reference, but probably isn't: '2' on line 2799 -- Looks like a reference, but probably isn't: '4' on line 2801 -- Looks like a reference, but probably isn't: '5' on line 2782 -- Looks like a reference, but probably isn't: '6' on line 2783 -- Looks like a reference, but probably isn't: '8' on line 2785 -- Looks like a reference, but probably isn't: '9' on line 2786 == Missing Reference: 'APPLICATION 4' is mentioned on line 2803, but not defined == Missing Reference: 'APPLICATION 19' is mentioned on line 2810, but not defined == Missing Reference: 'APPLICATION 5' is mentioned on line 2813, but not defined == Missing Reference: 'APPLICATION 6' is mentioned on line 2815, but not defined == Missing Reference: 'APPLICATION 7' is mentioned on line 2825, but not defined == Missing Reference: 'APPLICATION 8' is mentioned on line 2827, but not defined == Missing Reference: 'APPLICATION 9' is mentioned on line 2834, but not defined == Missing Reference: 'APPLICATION 10' is mentioned on line 2836, but not defined == Missing Reference: 'APPLICATION 11' is mentioned on line 2838, but not defined == Missing Reference: 'APPLICATION 12' is mentioned on line 2840, but not defined == Missing Reference: 'APPLICATION 13' is mentioned on line 2846, but not defined == Missing Reference: 'APPLICATION 14' is mentioned on line 2848, but not defined == Missing Reference: 'APPLICATION 15' is mentioned on line 2852, but not defined == Missing Reference: 'APPLICATION 16' is mentioned on line 2854, but not defined == Missing Reference: 'APPLICATION 23' is mentioned on line 2856, but not defined == Missing Reference: 'APPLICATION 24' is mentioned on line 2860, but not defined -- Looks like a reference, but probably isn't: '10' on line 2862 -- Looks like a reference, but probably isn't: '11' on line 2863 == Missing Reference: 'APPLICATION 25' is mentioned on line 2865, but not defined == Missing Reference: 'Keywords' is mentioned on line 3017, but not defined == Unused Reference: 'IP' is defined on line 2216, but no explicit reference was found in the text == Unused Reference: 'SASLPrep' is defined on line 2245, but no explicit reference was found in the text == Unused Reference: 'StringPrep' is defined on line 2249, but no explicit reference was found in the text -- No information found for draft-crocker-abnf-rfc2234bis-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'ABNF' -- 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: 5 errors (**), 0 flaws (~~), 33 warnings (==), 49 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet-Draft Editor: J. Sermersheim 3 Intended Category: Standard Track Novell, Inc 4 Document: draft-ietf-ldapbis-protocol-32.txt Oct 2005 5 Obsoletes: RFCs 2251, 2830, 3771 7 LDAP: The Protocol 9 Status of this Memo 11 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 becomes aware will be disclosed, in accordance with 15 Section 6 of BCP 79. 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 http://www.ietf.org/ietf/1id-abstracts.txt. 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 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 Abstract 41 This document describes the protocol elements, along with their 42 semantics and encodings, of the Lightweight Directory Access Protocol 43 (LDAP). LDAP provides access to distributed directory services that 44 act in accordance with X.500 data and service models. These protocol 45 elements are based on those described in the X.500 Directory Access 46 Protocol (DAP). 48 Table of Contents 49 Lightweight Directory Access Protocol Version 3 51 1. Introduction....................................................3 52 1.1. Relationship to Other LDAP Specifications.....................3 53 2. Conventions.....................................................3 54 3. Protocol Model..................................................4 55 3.1 Operation and LDAP Message Layer Relationship..................5 56 4. Elements of Protocol............................................5 57 4.1. Common Elements...............................................5 58 4.1.1. Message Envelope............................................5 59 4.1.2. String Types................................................7 60 4.1.3. Distinguished Name and Relative Distinguished Name..........7 61 4.1.4. Attribute Descriptions......................................8 62 4.1.5. Attribute Value.............................................8 63 4.1.6. Attribute Value Assertion...................................8 64 4.1.7. Attribute and PartialAttribute..............................9 65 4.1.8. Matching Rule Identifier....................................9 66 4.1.9. Result Message..............................................9 67 4.1.10. Referral..................................................11 68 4.1.11. Controls..................................................13 69 4.2. Bind Operation...............................................14 70 4.3. Unbind Operation.............................................17 71 4.4. Unsolicited Notification.....................................17 72 4.5. Search Operation.............................................18 73 4.6. Modify Operation.............................................29 74 4.7. Add Operation................................................31 75 4.8. Delete Operation.............................................31 76 4.9. Modify DN Operation..........................................32 77 4.10. Compare Operation...........................................33 78 4.11. Abandon Operation...........................................34 79 4.12. Extended Operation..........................................35 80 4.13. IntermediateResponse Message................................36 81 4.14. StartTLS Operation..........................................37 82 5. Protocol Encoding, Connection, and Transfer....................39 83 5.1. Protocol Encoding............................................39 84 5.2. Transmission Control Protocol (TCP)..........................40 85 5.3. Termination of the LDAP session..............................40 86 6. Security Considerations........................................40 87 7. Acknowledgements...............................................42 88 8. Normative References...........................................42 89 9. Informative References.........................................44 90 10. IANA Considerations...........................................44 91 11. Editor's Address..............................................45 92 Appendix A - LDAP Result Codes....................................46 93 A.1 Non-Error Result Codes........................................46 94 A.2 Result Codes..................................................46 95 Appendix B - Complete ASN.1 Definition............................51 96 Appendix C - Changes..............................................57 97 C.1 Changes made to RFC 2251:.....................................57 98 C.2 Changes made to RFC 2830:.....................................62 99 C.3 Changes made to RFC 3771:.....................................63 100 Lightweight Directory Access Protocol Version 3 102 1. Introduction 104 The Directory is "a collection of open systems cooperating to provide 105 directory services" [X.500]. A directory user, which may be a human 106 or other entity, accesses the Directory through a client (or 107 Directory User Agent (DUA)). The client, on behalf of the directory 108 user, interacts with one or more servers (or Directory System Agents 109 (DSA)). Clients interact with servers using a directory access 110 protocol. 112 This document details the protocol elements of the Lightweight 113 Directory Access Protocol (LDAP), along with their semantics. 114 Following the description of protocol elements, it describes the way 115 in which the protocol elements are encoded and transferred. 117 1.1. Relationship to Other LDAP Specifications 119 This document is an integral part of the LDAP Technical Specification 120 [Roadmap] which obsoletes the previously defined LDAP technical 121 specification, RFC 3377, in its entirety. 123 This document, together with [Roadmap], [AuthMeth], and [Models], 124 obsoletes RFC 2251 in its entirety. Section 3.3 is obsoleted by 125 [Roadmap]. Sections 4.2.1 (portions), and 4.2.2 are obsoleted by 126 [AuthMeth]. Sections 3.2, 3.4, 4.1.3 (last paragraph), 4.1.4, 4.1.5, 127 4.1.5.1, 4.1.9 (last paragraph), 5.1, 6.1, and 6.2 (last paragraph) 128 are obsoleted by [Models]. The remainder of RFC 2251 is obsoleted by 129 this document. Appendix C.1 summarizes substantive changes in the 130 remainder. 132 This document obsoletes RFC 2830, Sections 2 and 4. The remainder of 133 RFC 2830 is obsoleted by [AuthMeth]. Appendix C.2 summarizes 134 substantive changes to the remaining sections. 136 This document also obsoletes RFC 3771 in entirety. 138 2. Conventions 140 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 141 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are 142 to be interpreted as described in [Keyword]. 144 Character names in this document use the notation for code points and 145 names from the Unicode Standard [Unicode]. For example, the letter 146 "a" may be represented as either or . 148 Note: a glossary of terms used in Unicode can be found in [Glossary]. 149 Information on the Unicode character encoding model can be found in 150 [CharModel]. 152 Lightweight Directory Access Protocol Version 3 154 The term "transport connection" refers to the underlying transport 155 services used to carry the protocol exchange, as well as associations 156 established by these services. 158 The term "TLS layer" refers to TLS services used in providing 159 security services, as well as associations established by these 160 services. 162 The term "SASL layer" refers to SASL services used in providing 163 security services, as well as associations established by these 164 services. 166 The term "LDAP message layer" refers to the LDAP Message Protocol 167 Data Unit (PDU) services used in providing directory services, as 168 well as associations established by these services. 170 The term "LDAP session" refers to combined services (transport 171 connection, TLS layer, SASL layer, LDAP message layer) and their 172 associations. 174 See the table in Section 5 for an illustration of these four terms. 176 3. Protocol Model 178 The general model adopted by this protocol is one of clients 179 performing protocol operations against servers. In this model, a 180 client transmits a protocol request describing the operation to be 181 performed to a server. The server is then responsible for performing 182 the necessary operation(s) in the Directory. Upon completion of an 183 operation, the server typically returns a response containing 184 appropriate data to the requesting client. 186 Protocol operations are generally independent of one another. Each 187 operation is processed as an atomic action, leaving the directory in 188 a consistent state. 190 Although servers are required to return responses whenever such 191 responses are defined in the protocol, there is no requirement for 192 synchronous behavior on the part of either clients or servers. 193 Requests and responses for multiple operations generally may be 194 exchanged between a client and server in any order. If required, 195 synchronous behavior may be controlled by client applications. 197 The core protocol operations defined in this document can be mapped 198 to a subset of the X.500 (1993) Directory Abstract Service [X.511]. 199 However there is not a one-to-one mapping between LDAP operations and 200 X.500 Directory Access Protocol (DAP) operations. Server 201 implementations acting as a gateway to X.500 directories may need to 202 make multiple DAP requests to service a single LDAP request. 204 Lightweight Directory Access Protocol Version 3 206 3.1. Operation and LDAP Message Layer Relationship 208 Protocol operations are exchanged at the LDAP message layer. When the 209 transport connection is closed, any uncompleted operations at the 210 LDAP message layer, when possible, are abandoned, and when not 211 possible, are completed without transmission of the response. Also, 212 when the transport connection is closed, the client MUST NOT assume 213 that any uncompleted update operations have succeeded or failed. 215 4. Elements of Protocol 217 The protocol is described using Abstract Syntax Notation One 218 ([ASN.1]), and is transferred using a subset of ASN.1 Basic Encoding 219 Rules ([BER]). Section 5 specifies how the protocol elements are 220 encoded and transferred. 222 In order to support future extensions to this protocol, extensibility 223 is implied where it is allowed per ASN.1 (i.e. sequence, set, choice, 224 and enumerated types are extensible). In addition, ellipses (...) 225 have been supplied in ASN.1 types that are explicitly extensible as 226 discussed in [LDAPIANA]. Because of the implied extensibility, 227 clients and servers MUST (unless otherwise specified) ignore trailing 228 SEQUENCE components whose tags they do not recognize. 230 Changes to the protocol other than through the extension mechanisms 231 described here require a different version number. A client indicates 232 the version it is using as part of the BindRequest, described in 233 Section 4.2. If a client has not sent a Bind, the server MUST assume 234 the client is using version 3 or later. 236 Clients may attempt to determine the protocol versions a server 237 supports by reading the 'supportedLDAPVersion' attribute from the 238 root DSE (DSA-Specific Entry) [Models]. 240 4.1. Common Elements 242 This section describes the LDAPMessage envelope Protocol Data Unit 243 (PDU) format, as well as data type definitions, which are used in the 244 protocol operations. 246 4.1.1. Message Envelope 248 For the purposes of protocol exchanges, all protocol operations are 249 encapsulated in a common envelope, the LDAPMessage, which is defined 250 as follows: 252 Lightweight Directory Access Protocol Version 3 254 LDAPMessage ::= SEQUENCE { 255 messageID MessageID, 256 protocolOp CHOICE { 257 bindRequest BindRequest, 258 bindResponse BindResponse, 259 unbindRequest UnbindRequest, 260 searchRequest SearchRequest, 261 searchResEntry SearchResultEntry, 262 searchResDone SearchResultDone, 263 searchResRef SearchResultReference, 264 modifyRequest ModifyRequest, 265 modifyResponse ModifyResponse, 266 addRequest AddRequest, 267 addResponse AddResponse, 268 delRequest DelRequest, 269 delResponse DelResponse, 270 modDNRequest ModifyDNRequest, 271 modDNResponse ModifyDNResponse, 272 compareRequest CompareRequest, 273 compareResponse CompareResponse, 274 abandonRequest AbandonRequest, 275 extendedReq ExtendedRequest, 276 extendedResp ExtendedResponse, 277 ..., 278 intermediateResponse IntermediateResponse }, 279 controls [0] Controls OPTIONAL } 281 MessageID ::= INTEGER (0 .. maxInt) 283 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) -- 285 The ASN.1 type Controls is defined in Section 4.1.11. 287 The function of the LDAPMessage is to provide an envelope containing 288 common fields required in all protocol exchanges. At this time the 289 only common fields are the messageID and the controls. 291 If the server receives an LDAPMessage from the client in which the 292 LDAPMessage SEQUENCE tag cannot be recognized, the messageID cannot 293 be parsed, the tag of the protocolOp is not recognized as a request, 294 or the encoding structures or lengths of data fields are found to be 295 incorrect, then the server SHOULD return the Notice of Disconnection 296 described in Section 4.4.1, with the resultCode set to protocolError, 297 and MUST immediately terminate the LDAP session as described in 298 Section 5.3. 300 In other cases where the client or server cannot parse an LDAP PDU, 301 it SHOULD abruptly terminate the LDAP session (Section 5.3) where 302 further communication (including providing notice) would be 303 pernicious. Otherwise, server implementations MUST return an 304 appropriate response to the request, with the resultCode set to 305 protocolError. 307 Lightweight Directory Access Protocol Version 3 309 4.1.1.1. Message ID 311 All LDAPMessage envelopes encapsulating responses contain the 312 messageID value of the corresponding request LDAPMessage. 314 The message ID of a request MUST have a non-zero value different from 315 the messageID of any other request in progress in the same LDAP 316 session. The zero value is reserved for the unsolicited notification 317 message. 319 Typical clients increment a counter for each request. 321 A client MUST NOT send a request with the same message ID as an 322 earlier request in the same LDAP session unless it can be determined 323 that the server is no longer servicing the earlier request (e.g. 324 after the final response is received, or a subsequent Bind 325 completes). Otherwise the behavior is undefined. For this purpose, 326 note that Abandon and successfully abandoned operations do not send 327 responses. 329 4.1.2. String Types 331 The LDAPString is a notational convenience to indicate that, although 332 strings of LDAPString type encode as ASN.1 OCTET STRING types, the 333 [ISO10646] character set (a superset of [Unicode]) is used, encoded 334 following the [UTF-8] algorithm. Note that Unicode characters U+0000 335 through U+007F are the same as ASCII 0 through 127, respectively, and 336 have the same single octet UTF-8 encoding. Other Unicode characters 337 have a multiple octet UTF-8 encoding. 339 LDAPString ::= OCTET STRING -- UTF-8 encoded, 340 -- [ISO10646] characters 342 The LDAPOID is a notational convenience to indicate that the 343 permitted value of this string is a (UTF-8 encoded) dotted-decimal 344 representation of an OBJECT IDENTIFIER. Although an LDAPOID is 345 encoded as an OCTET STRING, values are limited to the definition of 346 given in Section 1.4 of [Models]. 348 LDAPOID ::= OCTET STRING -- Constrained to [Models] 350 For example, 352 1.3.6.1.4.1.1466.1.2.3 354 4.1.3. Distinguished Name and Relative Distinguished Name 356 An LDAPDN is defined to be the representation of a Distinguished Name 357 (DN) after encoding according to the specification in [LDAPDN]. 359 LDAPDN ::= LDAPString 360 -- Constrained to [LDAPDN] 361 Lightweight Directory Access Protocol Version 3 363 A RelativeLDAPDN is defined to be the representation of a Relative 364 Distinguished Name (RDN) after encoding according to the 365 specification in [LDAPDN]. 367 RelativeLDAPDN ::= LDAPString 368 -- Constrained to [LDAPDN] 370 4.1.4. Attribute Descriptions 372 The definition and encoding rules for attribute descriptions are 373 defined in Section 2.5 of [Models]. Briefly, an attribute description 374 is an attribute type and zero or more options. 376 AttributeDescription ::= LDAPString 377 -- Constrained to 378 -- [Models] 380 4.1.5. Attribute Value 382 A field of type AttributeValue is an OCTET STRING containing an 383 encoded attribute value. The attribute value is encoded according to 384 the LDAP-specific encoding definition of its corresponding syntax. 385 The LDAP-specific encoding definitions for different syntaxes and 386 attribute types may be found in other documents and in particular 387 [Syntaxes]. 389 AttributeValue ::= OCTET STRING 391 Note that there is no defined limit on the size of this encoding; 392 thus protocol values may include multi-megabyte attribute values 393 (e.g. photographs). 395 Attribute values may be defined which have arbitrary and non- 396 printable syntax. Implementations MUST NOT display nor attempt to 397 decode an attribute value if its syntax is not known. The 398 implementation may attempt to discover the subschema of the source 399 entry, and retrieve the descriptions of 'attributeTypes' from it 400 [Models]. 402 Clients MUST only send attribute values in a request that are valid 403 according to the syntax defined for the attributes. 405 4.1.6. Attribute Value Assertion 407 The AttributeValueAssertion (AVA) type definition is similar to the 408 one in the X.500 Directory standards. It contains an attribute 409 description and a matching rule ([Models] Section 4.1.3) assertion 410 value suitable for that type. Elements of this type are typically 411 used to assert that the value in assertionValue matches a value of an 412 attribute. 414 Lightweight Directory Access Protocol Version 3 416 AttributeValueAssertion ::= SEQUENCE { 417 attributeDesc AttributeDescription, 418 assertionValue AssertionValue } 420 AssertionValue ::= OCTET STRING 422 The syntax of the AssertionValue depends on the context of the LDAP 423 operation being performed. For example, the syntax of the EQUALITY 424 matching rule for an attribute is used when performing a Compare 425 operation. Often this is the same syntax used for values of the 426 attribute type, but in some cases the assertion syntax differs from 427 the value syntax. See objectIdentiferFirstComponentMatch in 428 [Syntaxes] for an example. 430 4.1.7. Attribute and PartialAttribute 432 Attributes and partial attributes consist of an attribute description 433 and attribute values. A PartialAttribute allows zero values, while 434 Attribute requires at least one value. 436 PartialAttribute ::= SEQUENCE { 437 type AttributeDescription, 438 vals SET OF value AttributeValue } 440 Attribute ::= PartialAttribute(WITH COMPONENTS { 441 ..., 442 vals (SIZE(1..MAX))}) 444 No two of the attribute values may be equivalent as described by 445 Section 2.3 of [Models]. The set of attribute values is unordered. 446 Implementations MUST NOT rely upon the ordering being repeatable. 448 4.1.8. Matching Rule Identifier 450 Matching rules are defined in Section 4.1.3 of [Models]. A matching 451 rule is identified in the protocol by the printable representation of 452 either its , or one of its short name descriptors 453 [Models], e.g. 'caseIgnoreMatch' or '2.5.13.2'. 455 MatchingRuleId ::= LDAPString 457 4.1.9. Result Message 459 The LDAPResult is the construct used in this protocol to return 460 success or failure indications from servers to clients. To various 461 requests, servers will return responses containing the elements found 462 in LDAPResult to indicate the final status of the protocol operation 463 request. 465 Lightweight Directory Access Protocol Version 3 467 LDAPResult ::= SEQUENCE { 468 resultCode ENUMERATED { 469 success (0), 470 operationsError (1), 471 protocolError (2), 472 timeLimitExceeded (3), 473 sizeLimitExceeded (4), 474 compareFalse (5), 475 compareTrue (6), 476 authMethodNotSupported (7), 477 strongerAuthRequired (8), 478 -- 9 reserved -- 479 referral (10), 480 adminLimitExceeded (11), 481 unavailableCriticalExtension (12), 482 confidentialityRequired (13), 483 saslBindInProgress (14), 484 noSuchAttribute (16), 485 undefinedAttributeType (17), 486 inappropriateMatching (18), 487 constraintViolation (19), 488 attributeOrValueExists (20), 489 invalidAttributeSyntax (21), 490 -- 22-31 unused -- 491 noSuchObject (32), 492 aliasProblem (33), 493 invalidDNSyntax (34), 494 -- 35 reserved for undefined isLeaf -- 495 aliasDereferencingProblem (36), 496 -- 37-47 unused -- 497 inappropriateAuthentication (48), 498 invalidCredentials (49), 499 insufficientAccessRights (50), 500 busy (51), 501 unavailable (52), 502 unwillingToPerform (53), 503 loopDetect (54), 504 -- 55-63 unused -- 505 namingViolation (64), 506 objectClassViolation (65), 507 notAllowedOnNonLeaf (66), 508 notAllowedOnRDN (67), 509 entryAlreadyExists (68), 510 objectClassModsProhibited (69), 511 -- 70 reserved for CLDAP -- 512 affectsMultipleDSAs (71), 513 -- 72-79 unused -- 514 other (80), 515 ... }, 516 matchedDN LDAPDN, 517 diagnosticMessage LDAPString, 518 referral [3] Referral OPTIONAL } 519 Lightweight Directory Access Protocol Version 3 521 The resultCode enumeration is extensible as defined in Section 3.6 of 522 [LDAPIANA]. The meanings of the listed result codes are given in 523 Appendix A. If a server detects multiple errors for an operation, 524 only one result code is returned. The server should return the result 525 code that best indicates the nature of the error encountered. Servers 526 may return substituted result codes to prevent unauthorized 527 disclosures. 529 The diagnosticMessage field of this construct may, at the server's 530 option, be used to return a string containing a textual, human- 531 readable (terminal control and page formatting characters should be 532 avoided) diagnostic message. As this diagnostic message is not 533 standardized, implementations MUST NOT rely on the values returned. 534 Diagnostic messages typically supplement the resultCode with 535 additional information. If the server chooses not to return a textual 536 diagnostic, the diagnosticMessage field MUST be empty. 538 For certain result codes (typically, but not restricted to 539 noSuchObject, aliasProblem, invalidDNSyntax and 540 aliasDereferencingProblem), the matchedDN field is set (subject to 541 access controls) to the name of the last entry (object or alias) used 542 in finding the target (or base) object. This will be a truncated form 543 of the provided name or, if an alias was dereferenced while 544 attempting to locate the entry, of the resulting name. Otherwise the 545 matchedDN field is empty. 547 4.1.10. Referral 549 The referral result code indicates that the contacted server cannot 550 or will not perform the operation and that one or more other servers 551 may be able to. Reasons for this include: 553 - The target entry of the request is not held locally, but the 554 server has knowledge of its possible existence elsewhere. 556 - The operation is restricted on this server -- perhaps due to a 557 read-only copy of an entry to be modified. 559 The referral field is present in an LDAPResult if the resultCode is 560 set to referral, and absent with all other result codes. It contains 561 one or more references to one or more servers or services that may be 562 accessed via LDAP or other protocols. Referrals can be returned in 563 response to any operation request (except Unbind and Abandon which do 564 not have responses). At least one URI MUST be present in the 565 Referral. 567 During a Search operation, after the baseObject is located, and 568 entries are being evaluated, the referral is not returned. Instead, 569 continuation references, described in Section 4.5.3, are returned 570 when other servers would need to be contacted to complete the 571 operation. 573 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI 574 Lightweight Directory Access Protocol Version 3 576 URI ::= LDAPString -- limited to characters permitted in 577 -- URIs 579 If the client wishes to progress the operation, it contacts one of 580 the supported services found in the referral. If multiple URIs are 581 present, the client assumes that any supported URI may be used to 582 progress the operation. 584 Clients that follow referrals MUST ensure that they do not loop 585 between servers. They MUST NOT repeatedly contact the same server for 586 the same request with the same parameters. Some clients use a counter 587 that is incremented each time referral handling occurs for an 588 operation, and these kinds of clients MUST be able to handle at least 589 ten nested referrals while progressing the operation. 591 A URI for a server implementing LDAP and accessible via [TCP]/[IP] 592 (v4 or v6) is written as an LDAP URL according to [LDAPURL]. 594 Referral values which are LDAP URLs follow these rules: 596 - If an alias was dereferenced, the part of the LDAP URL MUST 597 be present, with the new target object name. 599 - It is RECOMMENDED that the part be present to avoid 600 ambiguity. 602 - If the part is present, the client uses this name in its next 603 request to progress the operation, and if it is not present the 604 client uses the same name as in the original request. 606 - Some servers (e.g. participating in distributed indexing) may 607 provide a different filter in a URL of a referral for a Search 608 operation. 610 - If the part of the LDAP URL is present, the client uses 611 this filter in its next request to progress this Search, and if it 612 is not present the client uses the same filter as it used for that 613 Search. 615 - For Search, it is RECOMMENDED that the part be present to 616 avoid ambiguity. 618 - If the part is missing, the scope of the original Search 619 is used by the client to progress the operation. 621 - Other aspects of the new request may be the same as or different 622 from the request which generated the referral. 624 Other kinds of URIs may be returned. The syntax and semantics of such 625 URIs is left to future specifications. Clients may ignore URIs that 626 they do not support. 628 Lightweight Directory Access Protocol Version 3 630 UTF-8 encoded characters appearing in the string representation of a 631 DN, search filter, or other fields of the referral value may not be 632 legal for URIs (e.g. spaces) and MUST be escaped using the % method 633 in [URI]. 635 4.1.11. Controls 637 Controls provide a mechanism whereby the semantics and arguments of 638 existing LDAP operations may be extended. One or more controls may be 639 attached to a single LDAP message. A control only affects the 640 semantics of the message it is attached to. 642 Controls sent by clients are termed 'request controls' and those sent 643 by servers are termed 'response controls'. 645 Controls ::= SEQUENCE OF control Control 647 Control ::= SEQUENCE { 648 controlType LDAPOID, 649 criticality BOOLEAN DEFAULT FALSE, 650 controlValue OCTET STRING OPTIONAL } 652 The controlType field is the dotted-decimal representation of an 653 OBJECT IDENTIFIER which uniquely identifies the control. This 654 provides unambiguous naming of controls. Often, response control(s) 655 solicited by a request control share controlType values with the 656 request control. 658 The criticality field only has meaning in controls attached to 659 request messages (except UnbindRequest). For controls attached to 660 response messages and the UnbindRequest, the criticality field SHOULD 661 be FALSE, and MUST be ignored by the receiving protocol peer. A value 662 of TRUE indicates that it is unacceptable to perform the operation 663 without applying the semantics of the control. Specifically, the 664 criticality field is applied as follows: 666 - If the server does not recognize the control type, determines that 667 it is not appropriate for the operation, or is otherwise unwilling 668 to perform the operation with the control, and the criticality 669 field is TRUE, the server MUST NOT perform the operation, and for 670 operations that have a response message, MUST return with the 671 resultCode set to unavailableCriticalExtension. 673 - If the server does not recognize the control type, determines that 674 it is not appropriate for the operation, or is otherwise unwilling 675 to perform the operation with the control, and the criticality 676 field is FALSE, the server MUST ignore the control. 678 - Regardless of criticality, if a control is applied to an 679 operation, it is applied consistently and impartially to the 680 entire operation. 682 Lightweight Directory Access Protocol Version 3 684 The controlValue may contain information associated with the 685 controlType. Its format is defined by the specification of the 686 control. Implementations MUST be prepared to handle arbitrary 687 contents of the controlValue octet string, including zero bytes. It 688 is absent only if there is no value information which is associated 689 with a control of its type. When a controlValue is defined in terms 690 of ASN.1, and BER encoded according to Section 5.1, it also follows 691 the extensibility rules in Section 4. 693 Servers list the controlType of request controls they recognize in 694 the 'supportedControl' attribute in the root DSE (Section 5.1 of 695 [Models]). 697 Controls SHOULD NOT be combined unless the semantics of the 698 combination has been specified. The semantics of control 699 combinations, if specified, are generally found in the control 700 specification most recently published. When a combination of controls 701 is encountered whose semantics are invalid, not specified (or not 702 known), the message is considered to be not well-formed, thus the 703 operation fails with protocolError. Controls with a criticality of 704 FALSE may be ignored in order to arrive at a valid combination. 705 Additionally, unless order-dependent semantics are given in a 706 specification, the order of a combination of controls in the SEQUENCE 707 is ignored. Where the order is to be ignored but cannot be ignored by 708 the server, the message is considered not well-formed and the 709 operation fails with protocolError. Again, controls with a 710 criticality of FALSE may be ignored in order to arrive at a valid 711 combination. 713 This document does not specify any controls. Controls may be 714 specified in other documents. Documents detailing control extensions 715 are to provide for each control: 717 - the OBJECT IDENTIFIER assigned to the control, 719 - direction as to what value the sender should provide for the 720 criticality field (note: the semantics of the criticality field 721 are defined above should not be altered by the control's 722 specification), 724 - whether the controlValue field is present, and if so, the format 725 of its contents, 727 - the semantics of the control, and 729 - optionally, semantics regarding the combination of the control 730 with other controls. 732 4.2. Bind Operation 733 Lightweight Directory Access Protocol Version 3 735 The function of the Bind operation is to allow authentication 736 information to be exchanged between the client and server. The Bind 737 operation should be thought of as the "authenticate" operation. 738 Operational, authentication, and security-related semantics of this 739 operation are given in [AuthMeth]. 741 The Bind request is defined as follows: 743 BindRequest ::= [APPLICATION 0] SEQUENCE { 744 version INTEGER (1 .. 127), 745 name LDAPDN, 746 authentication AuthenticationChoice } 748 AuthenticationChoice ::= CHOICE { 749 simple [0] OCTET STRING, 750 -- 1 and 2 reserved 751 sasl [3] SaslCredentials, 752 ... } 754 SaslCredentials ::= SEQUENCE { 755 mechanism LDAPString, 756 credentials OCTET STRING OPTIONAL } 758 Fields of the BindRequest are: 760 - version: A version number indicating the version of the protocol 761 to be used at the LDAP message layer. This document describes 762 version 3 of the protocol. There is no version negotiation. The 763 client sets this field to the version it desires. If the server 764 does not support the specified version, it MUST respond with a 765 BindResponse where the resultCode is set to protocolError. 767 - name: If not empty, the name of the Directory object that the 768 client wishes to bind as. This field may take on a null value (a 769 zero length string) for the purposes of anonymous binds 770 ([AuthMeth] Section 5.1) or when using Simple Authentication and 771 Security Layer [SASL] authentication ([AuthMeth] Section 5.2). 772 Where the server attempts to locate the named object, it SHALL NOT 773 perform alias dereferencing. 775 - authentication: information used in authentication. This type is 776 extensible as defined in Section 3.7 of [LDAPIANA]. Servers that 777 do not support a choice supplied by a client return a BindResponse 778 with the resultCode set to authMethodNotSupported. 780 Textual passwords (consisting of a character sequence with a known 781 character set and encoding) transferred to the server using the 782 simple AuthenticationChoice SHALL be transferred as [UTF-8] 783 encoded [Unicode]. Prior to transfer, clients SHOULD prepare text 784 passwords as "query" strings by applying the [SASLprep] profile of 785 the [Stringprep] algorithm. Passwords consisting of other data 786 (such as random octets) MUST NOT be altered. The determination of 787 whether a password is textual is a local client matter. 789 Lightweight Directory Access Protocol Version 3 791 4.2.1. Processing of the Bind Request 793 Before processing a BindRequest, all uncompleted operations MUST 794 either complete or be abandoned. The server may either wait for the 795 uncompleted operations to complete, or abandon them. The server then 796 proceeds to authenticate the client in either a single-step, or 797 multi-step Bind process. Each step requires the server to return a 798 BindResponse to indicate the status of authentication. 800 After sending a BindRequest, clients MUST NOT send further LDAP PDUs 801 until receiving the BindResponse. Similarly, servers SHOULD NOT 802 process or respond to requests received while processing a 803 BindRequest. 805 If the client did not bind before sending a request and receives an 806 operationsError to that request, it may then send a BindRequest. If 807 this also fails or the client chooses not to bind on the existing 808 LDAP session, it may terminate the LDAP session, re-establish it and 809 begin again by first sending a BindRequest. This will aid in 810 interoperating with servers implementing other versions of LDAP. 812 Clients may send multiple Bind requests to change the authentication 813 and/or security associations or to complete a multi-stage Bind 814 process. Authentication from earlier binds is subsequently ignored. 816 For some SASL authentication mechanisms, it may be necessary for the 817 client to invoke the BindRequest multiple times ([AuthMeth] Section 818 5.2). Clients MUST NOT invoke operations between two Bind requests 819 made as part of a multi-stage Bind. 821 A client may abort a SASL bind negotiation by sending a BindRequest 822 with a different value in the mechanism field of SaslCredentials, or 823 an AuthenticationChoice other than sasl. 825 If the client sends a BindRequest with the sasl mechanism field as an 826 empty string, the server MUST return a BindResponse with the 827 resultCode set to authMethodNotSupported. This will allow clients to 828 abort a negotiation if it wishes to try again with the same SASL 829 mechanism. 831 4.2.2. Bind Response 833 The Bind response is defined as follows. 835 BindResponse ::= [APPLICATION 1] SEQUENCE { 836 COMPONENTS OF LDAPResult, 837 serverSaslCreds [7] OCTET STRING OPTIONAL } 839 BindResponse consists simply of an indication from the server of the 840 status of the client's request for authentication. 842 Lightweight Directory Access Protocol Version 3 844 A successful Bind operation is indicated by a BindResponse with a 845 resultCode set to success. Otherwise, an appropriate result code is 846 set in the BindResponse. For BindResponse, the protocolError result 847 code may be used to indicate that the version number supplied by the 848 client is unsupported. 850 If the client receives a BindResponse where the resultCode is set to 851 protocolError, it is to assume that the server does not support this 852 version of LDAP. While the client may be able proceed with another 853 version of this protocol (this may or may not require closing and re- 854 establishing the transport connection), how to proceed with another 855 version of this protocol is beyond the scope of this document. 856 Clients which are unable or unwilling to proceed SHOULD terminate the 857 LDAP session. 859 The serverSaslCreds field is used as part of a SASL-defined bind 860 mechanism to allow the client to authenticate the server to which it 861 is communicating, or to perform "challenge-response" authentication. 862 If the client bound with the simple choice, or the SASL mechanism 863 does not require the server to return information to the client, then 864 this field SHALL NOT be included in the BindResponse. 866 4.3. Unbind Operation 868 The function of the Unbind operation is to terminate an LDAP session. 869 The Unbind operation is not the antithesis of the Bind operation as 870 the name implies. The naming of these operations are historical. The 871 Unbind operation should be thought of as the "quit" operation. 873 The Unbind operation is defined as follows: 875 UnbindRequest ::= [APPLICATION 2] NULL 877 The client, upon transmission of the UnbindRequest, and the server, 878 upon receipt of the UnbindRequest are to gracefully terminate the 879 LDAP session as described in Section 5.3. 881 Uncompleted operations are handled as specified in Section 3.1. 883 4.4. Unsolicited Notification 885 An unsolicited notification is an LDAPMessage sent from the server to 886 the client which is not in response to any LDAPMessage received by 887 the server. It is used to signal an extraordinary condition in the 888 server or in the LDAP session between the client and the server. The 889 notification is of an advisory nature, and the server will not expect 890 any response to be returned from the client. 892 Lightweight Directory Access Protocol Version 3 894 The unsolicited notification is structured as an LDAPMessage in which 895 the messageID is zero and protocolOp is set to the extendedResp 896 choice using the ExtendedResponse type (See Section 4.12). The 897 responseName field of the ExtendedResponse always contains an LDAPOID 898 which is unique for this notification. 900 One unsolicited notification (Notice of Disconnection) is defined in 901 this document. The specification of an unsolicited notification 902 consists of: 904 - the OBJECT IDENTIFIER assigned to the notification (to be 905 specified in the responseName, 907 - the format of the contents of the responseValue (if any), 909 - the circumstances which will cause the notification to be sent, 910 and 912 - the semantics of the message. 914 4.4.1. Notice of Disconnection 916 This notification may be used by the server to advise the client that 917 the server is about to terminate the LDAP session on its own 918 initiative. This notification is intended to assist clients in 919 distinguishing between an exceptional server condition and a 920 transient network failure. Note that this notification is not a 921 response to an Unbind requested by the client. Uncompleted operations 922 are handled as specified in Section 3.1. 924 The responseName is 1.3.6.1.4.1.1466.20036, the responseValue field 925 is absent, and the resultCode is used to indicate the reason for the 926 disconnection. When the strongerAuthRequired resultCode is returned 927 with this message, it indicates that the server has detected that an 928 established security association between the client and server has 929 unexpectedly failed or been compromised. 931 Upon transmission of the Notice of Disconnection, the server 932 gracefully terminates the LDAP session as described in Section 5.3. 934 4.5. Search Operation 936 The Search operation is used to request a server to return, subject 937 to access controls and other restrictions, a set of entries matching 938 a complex search criterion. This can be used to read attributes from 939 a single entry, from entries immediately subordinate to a particular 940 entry, or a whole subtree of entries. 942 4.5.1. Search Request 944 The Search request is defined as follows: 946 Lightweight Directory Access Protocol Version 3 948 SearchRequest ::= [APPLICATION 3] SEQUENCE { 949 baseObject LDAPDN, 950 scope ENUMERATED { 951 baseObject (0), 952 singleLevel (1), 953 wholeSubtree (2), 954 ... }, 955 derefAliases ENUMERATED { 956 neverDerefAliases (0), 957 derefInSearching (1), 958 derefFindingBaseObj (2), 959 derefAlways (3) }, 960 sizeLimit INTEGER (0 .. maxInt), 961 timeLimit INTEGER (0 .. maxInt), 962 typesOnly BOOLEAN, 963 filter Filter, 964 attributes AttributeSelection } 966 AttributeSelection ::= SEQUENCE OF selector LDAPString 967 -- The LDAPString is constrained to 968 -- in Section 4.5.1.7 970 Filter ::= CHOICE { 971 and [0] SET SIZE (1..MAX) OF filter Filter, 972 or [1] SET SIZE (1..MAX) OF filter Filter, 973 not [2] Filter, 974 equalityMatch [3] AttributeValueAssertion, 975 substrings [4] SubstringFilter, 976 greaterOrEqual [5] AttributeValueAssertion, 977 lessOrEqual [6] AttributeValueAssertion, 978 present [7] AttributeDescription, 979 approxMatch [8] AttributeValueAssertion, 980 extensibleMatch [9] MatchingRuleAssertion, 981 ... } 983 SubstringFilter ::= SEQUENCE { 984 type AttributeDescription, 985 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE { 986 initial [0] AssertionValue, -- can occur at most once 987 any [1] AssertionValue, 988 final [2] AssertionValue } -- can occur at most once 989 } 991 MatchingRuleAssertion ::= SEQUENCE { 992 matchingRule [1] MatchingRuleId OPTIONAL, 993 type [2] AttributeDescription OPTIONAL, 994 matchValue [3] AssertionValue, 995 dnAttributes [4] BOOLEAN DEFAULT FALSE } 996 Lightweight Directory Access Protocol Version 3 998 Note that an X.500 "list"-like operation can be emulated by the 999 client requesting a singleLevel Search operation with a filter 1000 checking for the presence of the 'objectClass' attribute, and that an 1001 X.500 "read"-like operation can be emulated by a baseObject Search 1002 operation with the same filter. A server which provides a gateway to 1003 X.500 is not required to use the Read or List operations, although it 1004 may choose to do so, and if it does, it must provide the same 1005 semantics as the X.500 Search operation. 1007 4.5.1.1. SearchRequest.baseObject 1009 The name of the base object entry (or possibly the root) relative to 1010 which the Search is to be performed. 1012 4.5.1.2. SearchRequest.scope 1014 Specifies the scope of the Search to be performed. The semantics (as 1015 described in [X.511]) of the defined values of this field are: 1017 baseObject: The scope is constrained to the entry named by 1018 baseObject. 1020 singleLevel: The scope is constrained to the immediate 1021 subordinates of the entry named by baseObject. 1023 wholeSubtree: the scope is constrained to the entry named by the 1024 baseObject, and all its subordinates. 1026 4.5.1.3. SearchRequest.derefAliases 1028 An indicator as to whether or not alias entries (as defined in 1029 [Models]) are to be dereferenced during stages of the Search 1030 operation. 1032 The act of dereferencing an alias includes recursively dereferencing 1033 aliases which refer to aliases. 1035 Servers MUST detect looping while dereferencing aliases in order to 1036 prevent denial of service attacks of this nature. 1038 The semantics of the defined values of this field are: 1040 neverDerefAliases: Do not dereference aliases in searching or in 1041 locating the base object of the Search. 1043 Lightweight Directory Access Protocol Version 3 1045 derefInSearching: While searching subordinates of the base object, 1046 dereference any alias within the search scope. Dereferenced 1047 objects become the vertices of further search scopes where the 1048 Search operation is also applied. If the search scope is 1049 wholeSubtree, the Search continues in the subtree(s) of any 1050 dereferenced object. If the search scope is singleLevel, the 1051 search is applied to any dereferenced objects, and is not applied 1052 to their subordinates. Servers SHOULD eliminate duplicate entries 1053 that arise due to alias dereferencing while searching. 1055 derefFindingBaseObj: Dereference aliases in locating the base 1056 object of the Search, but not when searching subordinates of the 1057 base object. 1059 derefAlways: Dereference aliases both in searching and in locating 1060 the base object of the Search. 1062 4.5.1.4. SearchRequest.sizeLimit 1064 A size limit that restricts the maximum number of entries to be 1065 returned as a result of the Search. A value of zero in this field 1066 indicates that no client-requested size limit restrictions are in 1067 effect for the Search. Servers may also enforce a maximum number of 1068 entries to return. 1070 4.5.1.5. SearchRequest.timeLimit 1072 A time limit that restricts the maximum time (in seconds) allowed for 1073 a Search. A value of zero in this field indicates that no client- 1074 requested time limit restrictions are in effect for the Search. 1075 Servers may also enforce a maximum time limit for the Search. 1077 4.5.1.6. SearchRequest.typesOnly 1079 An indicator as to whether Search results are to contain both 1080 attribute descriptions and values, or just attribute descriptions. 1081 Setting this field to TRUE causes only attribute descriptions (no 1082 values) to be returned. Setting this field to FALSE causes both 1083 attribute descriptions and values to be returned. 1085 Lightweight Directory Access Protocol Version 3 1087 4.5.1.7. SearchRequest.filter 1089 A filter that defines the conditions that must be fulfilled in order 1090 for the Search to match a given entry. 1092 The 'and', 'or' and 'not' choices can be used to form combinations of 1093 filters. At least one filter element MUST be present in an 'and' or 1094 'or' choice. The others match against individual attribute values of 1095 entries in the scope of the Search. (Implementor's note: the 'not' 1096 filter is an example of a tagged choice in an implicitly-tagged 1097 module. In BER this is treated as if the tag was explicit.) 1099 A server MUST evaluate filters according to the three-valued logic of 1100 [X.511] (1993) Clause 7.8.1. In summary, a filter is evaluated to 1101 either "TRUE", "FALSE" or "Undefined". If the filter evaluates to 1102 TRUE for a particular entry, then the attributes of that entry are 1103 returned as part of the Search result (subject to any applicable 1104 access control restrictions). If the filter evaluates to FALSE or 1105 Undefined, then the entry is ignored for the Search. 1107 A filter of the "and" choice is TRUE if all the filters in the SET OF 1108 evaluate to TRUE, FALSE if at least one filter is FALSE, and 1109 otherwise Undefined. A filter of the "or" choice is FALSE if all of 1110 the filters in the SET OF evaluate to FALSE, TRUE if at least one 1111 filter is TRUE, and Undefined otherwise. A filter of the 'not' choice 1112 is TRUE if the filter being negated is FALSE, FALSE if it is TRUE, 1113 and Undefined if it is Undefined. 1115 A filter item evaluates to Undefined when the server would not be 1116 able to determine whether the assertion value matches an entry. 1117 Examples include: 1119 - An attribute description in an equalityMatch, substrings, 1120 greaterOrEqual, lessOrEqual, approxMatch or extensibleMatch 1121 filter is not recognized by the server. 1123 - The attribute type does not define the appropriate matching 1124 rule. 1126 - A MatchingRuleId in the extensibleMatch is not recognized by 1127 the server or is not valid for the attribute type. 1129 - The type of filtering requested is not implemented. 1131 - The assertion value is invalid. 1133 For example, if a server did not recognize the attribute type 1134 shoeSize, the filters (shoeSize=*), (shoeSize=12), (shoeSize>=12) and 1135 (shoeSize<=12) would each evaluate to Undefined. 1137 Servers MUST NOT return errors if attribute descriptions or matching 1138 rule ids are not recognized, assertion values are invalid, or the 1139 assertion syntax is not supported. More details of filter processing 1140 are given in Clause 7.8 of [X.511]. 1142 Lightweight Directory Access Protocol Version 3 1144 4.5.1.7.1. SearchRequest.filter.equalityMatch 1146 The matching rule for an equalityMatch filter is defined by the 1147 EQUALITY matching rule for the attribute type or subtype. The filter 1148 is TRUE when the EQUALITY rule returns TRUE as applied to the 1149 attribute or subtype and the asserted value. 1151 4.5.1.7.2. SearchRequest.filter.substrings 1153 There SHALL be at most one 'initial', and at most one 'final' in the 1154 'substrings' of a SubstringFilter. If 'initial' is present, it SHALL 1155 be the first element of 'substrings'. If 'final' is present, it SHALL 1156 be the last element of 'substrings'. 1158 The matching rule for an AssertionValue in a substrings filter item 1159 is defined by the SUBSTR matching rule for the attribute type or 1160 subtype. The filter is TRUE when the SUBSTR rule returns TRUE as 1161 applied to the attribute or subtype and the asserted value. 1163 Note that the AssertionValue in a substrings filter item conforms to 1164 the assertion syntax of the EQUALITY matching rule for the attribute 1165 type rather than the assertion syntax of the SUBSTR matching rule for 1166 the attribute type. Conceptually, the entire SubstringFilter is 1167 converted into an assertion value of the substrings matching rule 1168 prior to applying the rule. 1170 4.5.1.7.3. SearchRequest.filter.greaterOrEqual 1172 The matching rule for a greaterOrEqual filter is defined by the 1173 ORDERING matching rule for the attribute type or subtype. The filter 1174 is TRUE when the ORDERING rule returns FALSE as applied to the 1175 attribute or subtype and the asserted value. 1177 4.5.1.7.4. SearchRequest.filter.lessOrEqual 1179 The matching rules for a lessOrEqual filter are defined by the 1180 ORDERING and EQUALITY matching rules for the attribute type or 1181 subtype. The filter is TRUE when either the ORDERING or EQUALITY rule 1182 returns TRUE as applied to the attribute or subtype and the asserted 1183 value. 1185 4.5.1.7.5. SearchRequest.filter.present 1187 A present filter is TRUE when there is an attribute or subtype of the 1188 specified attribute description present in an entry, FALSE when no 1189 attribute or subtype of the specified attribute description is 1190 present in an entry, and Undefined otherwise. 1192 Lightweight Directory Access Protocol Version 3 1194 4.5.1.7.6. SearchRequest.filter.approxMatch 1196 An approxMatch filter is TRUE when there is a value of the attribute 1197 type or subtype for which some locally-defined approximate matching 1198 algorithm (e.g. spelling variations, phonetic match, etc.) returns 1199 TRUE. If a value matches for equality, it also satisfies an 1200 approximate match. If approximate matching is not supported for the 1201 attribute, this filter item should be treated as an equalityMatch. 1203 4.5.1.7.7. SearchRequest.filter.extensibleMatch 1205 The fields of the extensibleMatch filter item are evaluated as 1206 follows: 1208 - If the matchingRule field is absent, the type field MUST be 1209 present, and an equality match is performed for that type. 1211 - If the type field is absent and the matchingRule is present, the 1212 matchValue is compared against all attributes in an entry which 1213 support that matchingRule. 1215 - If the type field is present and the matchingRule is present, the 1216 matchValue is compared against the specified attribute type and 1217 its subtypes. 1219 - If the dnAttributes field is set to TRUE, the match is 1220 additionally applied against all the AttributeValueAssertions in 1221 an entry's distinguished name, and evaluates to TRUE if there is 1222 at least one attribute or subtype in the distinguished name for 1223 which the filter item evaluates to TRUE. The dnAttributes field is 1224 present to alleviate the need for multiple versions of generic 1225 matching rules (such as word matching), where one applies to 1226 entries and another applies to entries and DN attributes as well. 1228 The matchingRule used for evaluation determines the syntax for the 1229 assertion value. Once the matchingRule and attribute(s) have been 1230 determined, the filter item evaluates to TRUE if it matches at least 1231 one attribute type or subtype in the entry, FALSE if it does not 1232 match any attribute type or subtype in the entry, and Undefined if 1233 the matchingRule is not recognized, the matchingRule is unsuitable 1234 for use with the specified type, or the assertionValue is invalid. 1236 4.5.1.7. SearchRequest.attributes 1238 A selection list of the attributes to be returned from each entry 1239 which matches the search filter. Attributes which are subtypes of 1240 listed attributes are implicitly included. LDAPString values of this 1241 field are constrained to the following Augmented Backus-Naur Form 1242 ([ABNF]): 1244 attributeSelector = attributedescription / selectorspecial 1245 Lightweight Directory Access Protocol Version 3 1247 selectorspecial = noattrs / alluserattrs 1249 noattrs = %x31.2E.31 ; "1.1" 1251 alluserattrs = %x2A ; asterisk ("*") 1253 The production is defined in Section 2.5 of 1254 [Models]. 1256 There are three special cases which may appear in the attributes 1257 selection list: 1259 - an empty list with no attributes, 1261 - a list containing "*" (with zero or more attribute 1262 descriptions), and 1264 - a list containing only "1.1". 1266 An empty list requests the return of all user attributes. 1268 A list containing "*" requests the return of all user attributes 1269 in addition to other listed (operational) attributes. 1271 A list containing only the OID "1.1" indicates that no attributes 1272 are to be returned. If "1.1" is provided with other 1273 attributeSelector values, the "1.1" attributeSelector is ignored. 1274 This OID was chosen because it does not (and can not) correspond 1275 to any attribute in use. 1277 Client implementors should note that even if all user attributes are 1278 requested, some attributes and/or attribute values of the entry may 1279 not be included in Search results due to access controls or other 1280 restrictions. Furthermore, servers will not return operational 1281 attributes, such as objectClasses or attributeTypes, unless they are 1282 listed by name. Operational attributes are described in [Models]. 1284 Attributes are returned at most once in an entry. If an attribute 1285 description is named more than once in the list, the subsequent names 1286 are ignored. If an attribute description in the list is not 1287 recognized, it is ignored by the server. 1289 4.5.2. Search Result 1291 The results of the Search operation are returned as zero or more 1292 SearchResultEntry and/or SearchResultReference messages, followed by 1293 a single SearchResultDone message. 1295 SearchResultEntry ::= [APPLICATION 4] SEQUENCE { 1296 objectName LDAPDN, 1297 attributes PartialAttributeList } 1298 Lightweight Directory Access Protocol Version 3 1300 PartialAttributeList ::= SEQUENCE OF 1301 partialAttribute PartialAttribute 1303 SearchResultReference ::= [APPLICATION 19] SEQUENCE 1304 SIZE (1..MAX) OF uri URI 1306 SearchResultDone ::= [APPLICATION 5] LDAPResult 1308 Each SearchResultEntry represents an entry found during the Search. 1309 Each SearchResultReference represents an area not yet explored during 1310 the Search. The SearchResultEntry and SearchResultReference messages 1311 may come in any order. Following all the SearchResultReference and 1312 SearchResultEntry responses, the server returns a SearchResultDone 1313 response, which contains an indication of success, or detailing any 1314 errors that have occurred. 1316 Each entry returned in a SearchResultEntry will contain all 1317 appropriate attributes as specified in the attributes field of the 1318 Search Request, subject to access control and other administrative 1319 policy. Note that the PartialAttributeList may hold zero elements. 1320 This may happen when none of the attributes of an entry were 1321 requested, or could be returned. Note also that the partialAttribute 1322 vals set may hold zero elements. This may happen when typesOnly is 1323 requested, access controls prevent the return of values, or other 1324 reasons. 1326 Some attributes may be constructed by the server and appear in a 1327 SearchResultEntry attribute list, although they are not stored 1328 attributes of an entry. Clients SHOULD NOT assume that all attributes 1329 can be modified, even if permitted by access control. 1331 If the server's schema defines short names [Models] for an attribute 1332 type then the server SHOULD use one of those names in attribute 1333 descriptions for that attribute type (in preference to using the 1334 [Models] format of the attribute type's object 1335 identifier). The server SHOULD NOT use the short name if that name is 1336 known by the server to be ambiguous, or otherwise likely to cause 1337 interoperability problems. 1339 4.5.3. Continuation References in the Search Result 1341 If the server was able to locate the entry referred to by the 1342 baseObject but was unable or unwilling to search one or more non- 1343 local entries, the server may return one or more 1344 SearchResultReference messages, each containing a reference to 1345 another set of servers for continuing the operation. A server MUST 1346 NOT return any SearchResultReference messages if it has not located 1347 the baseObject and thus has not searched any entries; in this case it 1348 would return a SearchResultDone containing either a referral or 1349 noSuchObject result code (depending on the server's knowledge of the 1350 entry named in the baseObject). 1352 Lightweight Directory Access Protocol Version 3 1354 If a server holds a copy or partial copy of the subordinate naming 1355 context (Section 5 of [Models]), it may use the search filter to 1356 determine whether or not to return a SearchResultReference response. 1357 Otherwise SearchResultReference responses are always returned when in 1358 scope. 1360 The SearchResultReference is of the same data type as the Referral. 1362 If the client wishes to progress the Search, it issues a new Search 1363 operation for each SearchResultReference that is returned. If 1364 multiple URIs are present, the client assumes that any supported URI 1365 may be used to progress the operation. 1367 Clients that follow search continuation references MUST ensure that 1368 they do not loop between servers. They MUST NOT repeatedly contact 1369 the same server for the same request with the same parameters. Some 1370 clients use a counter that is incremented each time search result 1371 reference handling occurs for an operation, and these kinds of 1372 clients MUST be able to handle at least ten nested referrals while 1373 progressing the operation. 1375 Note that the Abandon operation described in Section 4.11 applies 1376 only to a particular operation sent at the LDAP message layer between 1377 a client and server. The client must abandon subsequent Search 1378 operations it wishes to individually. 1380 A URI for a server implementing LDAP and accessible via [TCP]/[IP] 1381 (v4 or v6) is written as an LDAP URL according to [LDAPURL]. 1383 SearchResultReference values which are LDAP URLs follow these rules: 1385 - The part of the LDAP URL MUST be present, with the new target 1386 object name. The client uses this name when following the 1387 reference. 1389 - Some servers (e.g. participating in distributed indexing) may 1390 provide a different filter in the LDAP URL. 1392 - If the part of the LDAP URL is present, the client uses 1393 this filter in its next request to progress this Search, and if it 1394 is not present the client uses the same filter as it used for that 1395 Search. 1397 - If the originating search scope was singleLevel, the part 1398 of the LDAP URL will be "base". 1400 - It is RECOMMENDED that the part be present to avoid 1401 ambiguity. In the absence of a part, the scope of the 1402 original Search request is assumed. 1404 - Other aspects of the new Search request may be the same as or 1405 different from the Search request which generated the 1406 SearchResultReference. 1408 Lightweight Directory Access Protocol Version 3 1410 - The name of an unexplored subtree in a SearchResultReference need 1411 not be subordinate to the base object. 1413 Other kinds of URIs may be returned. The syntax and semantics of such 1414 URIs is left to future specifications. Clients may ignore URIs that 1415 they do not support. 1417 UTF-8 encoded characters appearing in the string representation of a 1418 DN, search filter, or other fields of the referral value may not be 1419 legal for URIs (e.g. spaces) and MUST be escaped using the % method 1420 in [URI]. 1422 4.5.3.1. Examples 1424 For example, suppose the contacted server (hosta) holds the entry 1425 and the entry . It 1426 knows that both LDAP servers (hostb) and (hostc) hold 1427 (one is the master and the other server 1428 a shadow), and that LDAP-capable server (hostd) holds the subtree 1429 . If a wholeSubtree Search of 1430 is requested to the contacted server, it may 1431 return the following: 1433 SearchResultEntry for DC=Example,DC=NET 1434 SearchResultEntry for CN=Manager,DC=Example,DC=NET 1435 SearchResultReference { 1436 ldap://hostb/OU=People,DC=Example,DC=NET??sub 1437 ldap://hostc/OU=People,DC=Example,DC=NET??sub } 1438 SearchResultReference { 1439 ldap://hostd/OU=Roles,DC=Example,DC=NET??sub } 1440 SearchResultDone (success) 1442 Client implementors should note that when following a 1443 SearchResultReference, additional SearchResultReference may be 1444 generated. Continuing the example, if the client contacted the server 1445 (hostb) and issued the Search request for the subtree 1446 , the server might respond as follows: 1448 SearchResultEntry for OU=People,DC=Example,DC=NET 1449 SearchResultReference { 1450 ldap://hoste/OU=Managers,OU=People,DC=Example,DC=NET??sub } 1451 SearchResultReference { 1452 ldap://hostf/OU=Consultants,OU=People,DC=Example,DC=NET??sub } 1453 SearchResultDone (success) 1455 Similarly, if a singleLevel Search of is 1456 requested to the contacted server, it may return the following: 1458 Lightweight Directory Access Protocol Version 3 1460 SearchResultEntry for CN=Manager,DC=Example,DC=NET 1461 SearchResultReference { 1462 ldap://hostb/OU=People,DC=Example,DC=NET??base 1463 ldap://hostc/OU=People,DC=Example,DC=NET??base } 1464 SearchResultReference { 1465 ldap://hostd/OU=Roles,DC=Example,DC=NET??base } 1466 SearchResultDone (success) 1468 If the contacted server does not hold the base object for the Search, 1469 but has knowledge of its possible location, then it may return a 1470 referral to the client. In this case, if the client requests a 1471 subtree Search of to hosta, the server returns a 1472 SearchResultDone containing a referral. 1474 SearchResultDone (referral) { 1475 ldap://hostg/DC=Example,DC=ORG??sub } 1477 4.6. Modify Operation 1479 The Modify operation allows a client to request that a modification 1480 of an entry be performed on its behalf by a server. The Modify 1481 Request is defined as follows: 1483 ModifyRequest ::= [APPLICATION 6] SEQUENCE { 1484 object LDAPDN, 1485 changes SEQUENCE OF change SEQUENCE { 1486 operation ENUMERATED { 1487 add (0), 1488 delete (1), 1489 replace (2), 1490 ... }, 1491 modification PartialAttribute } } 1493 Fields of the Modify Request are: 1495 - object: The value of this field contains the name of the entry to 1496 be modified. The server SHALL NOT perform any alias dereferencing 1497 in determining the object to be modified. 1499 - changes: A list of modifications to be performed on the entry. The 1500 entire list of modifications MUST be performed in the order they 1501 are listed as a single atomic operation. While individual 1502 modifications may violate certain aspects of the directory schema 1503 (such as the object class definition and DIT content rule), the 1504 resulting entry after the entire list of modifications is 1505 performed MUST conform to the requirements of the directory model 1506 and controlling schema [Models]. 1508 - operation: Used to specify the type of modification being 1509 performed. Each operation type acts on the following 1510 modification. The values of this field have the following 1511 semantics respectively: 1513 Lightweight Directory Access Protocol Version 3 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 replace: replace all existing values of the modification 1523 attribute with the new values listed, creating the attribute 1524 if it did not already exist. A replace with no value will 1525 delete the entire attribute if it exists, and is ignored if 1526 the attribute does not exist. 1528 - modification: A PartialAttribute (which may have an empty SET 1529 of vals) used to hold the attribute type or attribute type and 1530 values being modified. 1532 Upon receipt of a Modify Request, the server attempts to perform the 1533 necessary modifications to the DIT and returns the result in a Modify 1534 Response, defined as follows: 1536 ModifyResponse ::= [APPLICATION 7] LDAPResult 1538 The server will return to the client a single Modify Response 1539 indicating either the successful completion of the DIT modification, 1540 or the reason that the modification failed. Due to the requirement 1541 for atomicity in applying the list of modifications in the Modify 1542 Request, the client may expect that no modifications of the DIT have 1543 been performed if the Modify Response received indicates any sort of 1544 error, and that all requested modifications have been performed if 1545 the Modify Response indicates successful completion of the Modify 1546 operation. Whether the modification was applied or not cannot be 1547 determined by the client if the Modify Response was not received 1548 (e.g. the LDAP session was terminated or the Modify operation was 1549 abandoned). 1551 Servers MUST ensure that entries conform to user and system schema 1552 rules or other data model constraints. The Modify operation cannot be 1553 used to remove from an entry any of its distinguished values, i.e. 1554 those values which form the entry's relative distinguished name. An 1555 attempt to do so will result in the server returning the 1556 notAllowedOnRDN result code. The Modify DN operation described in 1557 Section 4.9 is used to rename an entry. 1559 For attribute types which specify no equality matching, the rules in 1560 Section 2.5.1 of [Models] are followed. 1562 Note that due to the simplifications made in LDAP, there is not a 1563 direct mapping of the changes in an LDAP ModifyRequest onto the 1564 changes of a DAP ModifyEntry operation, and different implementations 1565 of LDAP-DAP gateways may use different means of representing the 1566 change. If successful, the final effect of the operations on the 1567 entry MUST be identical. 1569 Lightweight Directory Access Protocol Version 3 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 AddRequest ::= [APPLICATION 8] SEQUENCE { 1577 entry LDAPDN, 1578 attributes AttributeList } 1580 AttributeList ::= SEQUENCE OF attribute Attribute 1582 Fields of the Add Request are: 1584 - entry: the name of the entry to be added. The server SHALL NOT 1585 dereference any aliases in locating the entry to be added. 1587 - attributes: the list of attributes that, along with those from the 1588 RDN, make up the content of the entry being added. Clients MAY or 1589 MAY NOT include the RDN attribute(s) in this list. Clients MUST 1590 NOT supply NO-USER-MODIFICATION attributes such as the 1591 createTimestamp or creatorsName attributes, since the server 1592 maintains these automatically. 1594 Servers MUST ensure that entries conform to user and system schema 1595 rules or other data model constraints. For attribute types which 1596 specify no equality matching, the rules in Section 2.5.1 of [Models] 1597 are followed (this applies to the naming attribute in addition to any 1598 multi-valued attributes being added). 1600 The entry named in the entry field of the AddRequest MUST NOT exist 1601 for the AddRequest to succeed. The immediate superior (parent) of an 1602 object or alias entry to be added MUST exist. For example, if the 1603 client attempted to add , the 1604 entry did not exist, and the entry did 1605 exist, then the server would return the noSuchObject result code with 1606 the matchedDN field containing . 1608 Upon receipt of an Add Request, a server will attempt to add the 1609 requested entry. The result of the Add attempt will be returned to 1610 the client in the Add Response, defined as follows: 1612 AddResponse ::= [APPLICATION 9] LDAPResult 1614 A response of success indicates that the new entry has been added to 1615 the Directory. 1617 4.8. Delete Operation 1619 The Delete operation allows a client to request the removal of an 1620 entry from the Directory. The Delete Request is defined as follows: 1622 DelRequest ::= [APPLICATION 10] LDAPDN 1623 Lightweight Directory Access Protocol Version 3 1625 The Delete Request consists of the name of the entry to be deleted. 1626 The server SHALL NOT dereference aliases while resolving the name of 1627 the target entry to be removed. 1629 Only leaf entries (those with no subordinate entries) can be deleted 1630 with this operation. 1632 Upon receipt of a Delete Request, a server will attempt to perform 1633 the entry removal requested and return the result in the Delete 1634 Response defined as follows: 1636 DelResponse ::= [APPLICATION 11] LDAPResult 1638 4.9. Modify DN Operation 1640 The Modify DN operation allows a client to change the Relative 1641 Distinguished Name (RDN) of an entry in the Directory, and/or to move 1642 a subtree of entries to a new location in the Directory. The Modify 1643 DN Request is defined as follows: 1645 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE { 1646 entry LDAPDN, 1647 newrdn RelativeLDAPDN, 1648 deleteoldrdn BOOLEAN, 1649 newSuperior [0] LDAPDN OPTIONAL } 1651 Fields of the Modify DN Request are: 1653 - entry: the name of the entry to be changed. This entry may or may 1654 not have subordinate entries. 1656 - newrdn: the new RDN of the entry. The value of the old RDN is 1657 supplied when moving the entry to a new superior without changing 1658 its RDN. Attribute values of the new RDN not matching any 1659 attribute value of the entry are added to the entry and an 1660 appropriate error is returned if this fails. 1662 - deleteoldrdn: a boolean field that controls whether the old RDN 1663 attribute values are to be retained as attributes of the entry, or 1664 deleted from the entry. 1666 - newSuperior: if present, this is the name of an existing object 1667 entry which becomes the immediate superior (parent) of the 1668 existing entry. 1670 The server SHALL NOT dereference any aliases in locating the objects 1671 named in entry or newSuperior. 1673 Upon receipt of a ModifyDNRequest, a server will attempt to perform 1674 the name change and return the result in the Modify DN Response, 1675 defined as follows: 1677 Lightweight Directory Access Protocol Version 3 1679 ModifyDNResponse ::= [APPLICATION 13] LDAPResult 1681 For example, if the entry named in the entry field was , the newrdn field was , and the 1683 newSuperior field was absent, then this operation would attempt to 1684 rename the entry to be . If there was 1685 already an entry with that name, the operation would fail with the 1686 entryAlreadyExists result code. 1688 Servers MUST ensure that entries conform to user and system schema 1689 rules or other data model constraints. For attribute types which 1690 specify no equality matching, the rules in Section 2.5.1 of [Models] 1691 are followed (this pertains to newrdn and deleteoldrdn). 1693 The object named in newSuperior MUST exist. For example, if the 1694 client attempted to add , the 1695 entry did not exist, and the entry did 1696 exist, then the server would return the noSuchObject result code with 1697 the matchedDN field containing . 1699 If the deleteoldrdn field is TRUE, the attribute values forming the 1700 old RDN but not the new RDN are deleted from the entry. If the 1701 deleteoldrdn field is FALSE, the attribute values forming the old RDN 1702 will be retained as non-distinguished attribute values of the entry. 1704 Note that X.500 restricts the ModifyDN operation to only affect 1705 entries that are contained within a single server. If the LDAP server 1706 is mapped onto DAP, then this restriction will apply, and the 1707 affectsMultipleDSAs result code will be returned if this error 1708 occurred. In general, clients MUST NOT expect to be able to perform 1709 arbitrary movements of entries and subtrees between servers or 1710 between naming contexts. 1712 4.10. Compare Operation 1714 The Compare operation allows a client to compare an assertion value 1715 with the values of a particular attribute in a particular entry in 1716 the Directory. The Compare Request is defined as follows: 1718 CompareRequest ::= [APPLICATION 14] SEQUENCE { 1719 entry LDAPDN, 1720 ava AttributeValueAssertion } 1722 Fields of the Compare Request are: 1724 - entry: the name of the entry to be compared. The server SHALL NOT 1725 dereference any aliases in locating the entry to be compared. 1727 - ava: holds the attribute value assertion to be compared. 1729 Upon receipt of a Compare Request, a server will attempt to perform 1730 the requested comparison and return the result in the Compare 1731 Response, defined as follows: 1733 Lightweight Directory Access Protocol Version 3 1735 CompareResponse ::= [APPLICATION 15] LDAPResult 1737 The resultCode is set to compareTrue, compareFalse, or an appropriate 1738 error. compareTrue indicates that the assertion value in the ava 1739 field matches a value of the attribute or subtype according to the 1740 attribute's EQUALITY matching rule. compareFalse indicates that the 1741 assertion value in the ava field and the values of the attribute or 1742 subtype did not match. Other result codes indicate either that the 1743 result of the comparison was Undefined (Section 4.5.1), or that some 1744 error occurred. 1746 Note that some directory systems may establish access controls which 1747 permit the values of certain attributes (such as userPassword) to be 1748 compared but not interrogated by other means. 1750 4.11. Abandon Operation 1752 The function of the Abandon operation is to allow a client to request 1753 that the server abandon an uncompleted operation. The Abandon Request 1754 is defined as follows: 1756 AbandonRequest ::= [APPLICATION 16] MessageID 1758 The MessageID is that of an operation which was requested earlier at 1759 this LDAP message layer. The Abandon request itself has its own 1760 MessageID. This is distinct from the MessageID of the earlier 1761 operation being abandoned. 1763 There is no response defined in the Abandon operation. Upon receipt 1764 of an AbandonRequest, the server MAY abandon the operation identified 1765 by the MessageID. Since the client cannot tell the difference between 1766 a successfully abandoned operation and an uncompleted operation, the 1767 application of the Abandon operation is limited to uses where the 1768 client does not require an indication of its outcome. 1770 Abandon, Bind, Unbind, and StartTLS operations cannot be abandoned. 1772 In the event that a server receives an Abandon Request on a Search 1773 operation in the midst of transmitting responses to the Search, that 1774 server MUST cease transmitting entry responses to the abandoned 1775 request immediately, and MUST NOT send the SearchResultDone. Of 1776 course, the server MUST ensure that only properly encoded LDAPMessage 1777 PDUs are transmitted. 1779 The ability to abandon other (particularly update) operations is at 1780 the discretion of the server. 1782 Clients should not send Abandon requests for the same operation 1783 multiple times, and MUST also be prepared to receive results from 1784 operations it has abandoned (since these may have been in transit 1785 when the Abandon was requested, or are not able to be abandoned). 1787 Lightweight Directory Access Protocol Version 3 1789 Servers MUST discard Abandon requests for message IDs they do not 1790 recognize, for operations which cannot be abandoned, and for 1791 operations which have already been abandoned. 1793 4.12. Extended Operation 1795 The Extended operation allows additional operations to be defined for 1796 services not already available in the protocol. For example, to Add 1797 operations to install transport layer security (see Section 4.14). 1799 The Extended operation allows clients to make requests and receive 1800 responses with predefined syntaxes and semantics. These may be 1801 defined in RFCs or be private to particular implementations. 1803 Each Extended operation consists of an Extended request and an 1804 Extended response. 1806 ExtendedRequest ::= [APPLICATION 23] SEQUENCE { 1807 requestName [0] LDAPOID, 1808 requestValue [1] OCTET STRING OPTIONAL } 1810 The requestName is a dotted-decimal representation of the unique 1811 OBJECT IDENTIFIER corresponding to the request. The requestValue is 1812 information in a form defined by that request, encapsulated inside an 1813 OCTET STRING. 1815 The server will respond to this with an LDAPMessage containing an 1816 ExtendedResponse. 1818 ExtendedResponse ::= [APPLICATION 24] SEQUENCE { 1819 COMPONENTS OF LDAPResult, 1820 responseName [10] LDAPOID OPTIONAL, 1821 responseValue [11] OCTET STRING OPTIONAL } 1823 The responseName field, when present, contains an LDAPOID which is 1824 unique for this extended operation or response. This field is 1825 optional (even when the extension specification specifies an LDAPOID 1826 to be returned in the field). The field will be absent whenever the 1827 server is unable or unwilling to determine the appropriate LDAPOID to 1828 return, for instance when the requestName cannot be parsed or its 1829 value is not recognized. 1831 Where the requestName is not recognized, the server returns 1832 protocolError (The server may return protocolError in other cases). 1834 The requestValue and responseValue fields contain information 1835 associated with the operation. The format of these fields is defined 1836 by the specification of the Extended operation. Implementations MUST 1837 be prepared to handle arbitrary contents of these fields, including 1838 zero bytes. Values that are defined in terms of ASN.1 and BER encoded 1839 according to Section 5.1, also follow the extensibility rules in 1840 Section 4. 1842 Lightweight Directory Access Protocol Version 3 1844 Servers list the requestName of Extended Requests they recognize in 1845 the 'supportedExtension' attribute in the root DSE (Section 5.1 of 1846 [Models]). 1848 Extended operations may be specified in other documents. The 1849 specification of an Extended operation consists of: 1851 - the OBJECT IDENTIFIER assigned to the requestName, 1853 - the OBJECT IDENTIFIER (if any) assigned to the responseName (note 1854 that the same OBJECT IDENTIFIER may be used for both the 1855 requestName and responseName), 1857 - the format of the contents of the requestValue and responseValue 1858 (if any), and 1860 - the semantics of the operation. 1862 4.13. IntermediateResponse Message 1864 While the Search operation provides a mechanism to return multiple 1865 response messages for a single Search request, other operations, by 1866 nature, do not provide for multiple response messages. 1868 The IntermediateResponse message provides a general mechanism for 1869 defining single-request/multiple-response operations in LDAP. This 1870 message is intended to be used in conjunction with the Extended 1871 operation to define new single-request/multiple-response operations 1872 or in conjunction with a control when extending existing LDAP 1873 operations in a way that requires them to return Intermediate 1874 response information. 1876 It is intended that the definitions and descriptions of Extended 1877 operations and controls that make use of the IntermediateResponse 1878 message will define the circumstances when an IntermediateResponse 1879 message can be sent by a server and the associated meaning of an 1880 IntermediateResponse message sent in a particular circumstance. 1882 IntermediateResponse ::= [APPLICATION 25] SEQUENCE { 1883 responseName [0] LDAPOID OPTIONAL, 1884 responseValue [1] OCTET STRING OPTIONAL } 1886 IntermediateResponse messages SHALL NOT be returned to the client 1887 unless the client issues a request that specifically solicits their 1888 return. This document defines two forms of solicitation: Extended 1889 operation and request control. IntermediateResponse messages are 1890 specified in documents describing the manner in which they are 1891 solicited (i.e. in the Extended operation or request control 1892 specification that uses them). These specifications include: 1894 - the OBJECT IDENTIFIER (if any) assigned to the responseName, 1896 - the format of the contents of the responseValue (if any), and 1897 Lightweight Directory Access Protocol Version 3 1899 - the semantics associated with the IntermediateResponse message. 1901 Extensions that allow the return of multiple types of 1902 IntermediateResponse messages SHALL identify those types using unique 1903 responseName values (note that one of these may specify no value). 1905 Sections 4.13.1 and 4.13.2 describe additional requirements on the 1906 inclusion of responseName and responseValue in IntermediateResponse 1907 messages. 1909 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse 1911 A single-request/multiple-response operation may be defined using a 1912 single ExtendedRequest message to solicit zero or more 1913 IntermediateResponse messages of one or more kinds followed by an 1914 ExtendedResponse message. 1916 4.13.2. Usage with LDAP Request Controls 1918 A control's semantics may include the return of zero or more 1919 IntermediateResponse messages prior to returning the final result 1920 code for the operation. One or more kinds of IntermediateResponse 1921 messages may be sent in response to a request control. 1923 All IntermediateResponse messages associated with request controls 1924 SHALL include a responseName. This requirement ensures that the 1925 client can correctly identify the source of IntermediateResponse 1926 messages when: 1928 - two or more controls using IntermediateResponse messages are 1929 included in a request for any LDAP operation or 1931 - one or more controls using IntermediateResponse messages are 1932 included in a request with an LDAP Extended operation that uses 1933 IntermediateResponse messages. 1935 4.14. StartTLS Operation 1937 The Start Transport Layer Security (StartTLS) operation's purpose is 1938 to initiate installation of a TLS layer. The StartTLS operation is 1939 defined using the Extended operation mechanism described in Section 1940 4.12. 1942 Lightweight Directory Access Protocol Version 3 1944 4.14.1. StartTLS Request 1946 A client requests TLS establishment by transmitting a StartTLS 1947 request message to the server. The StartTLS request is defined in 1948 terms of an ExtendedRequest. The requestName is 1949 "1.3.6.1.4.1.1466.20037", and the requestValue field is always 1950 absent. 1952 The client MUST NOT send any LDAP PDUs at this LDAP message layer 1953 following this request until it receives a StartTLS Extended response 1954 and, in the case of a successful response, completes TLS 1955 negotiations. 1957 Detected sequencing problems (particularly those detailed in Section 1958 3.1.1 of [AuthMeth]) result in the resultCode being set to 1959 operationsError. 1961 If the server does not support TLS (whether by design or by current 1962 configuration), it returns with the resultCode set to protocolError 1963 as described in Section 4.12. 1965 4.14.2. StartTLS Response 1967 When a StartTLS request is received, servers supporting the operation 1968 MUST return a StartTLS response message to the requestor. The 1969 responseName is "1.3.6.1.4.1.1466.20037" when provided (See 4.12). 1970 The responseValue is always absent. 1972 If the server is willing and able to negotiate TLS, it returns the 1973 StartTLS response with the resultCode set to success. Upon client 1974 receipt of a successful StartTLS response, protocol peers may 1975 commence with TLS negotiation as discussed in Section 3 of 1976 [AuthMeth]. 1978 If the server is otherwise unwilling or unable to perform this 1979 operation, the server is to return an appropriate result code 1980 indicating the nature of the problem. For example, if the TLS 1981 subsystem is not presently available, the server may indicate so by 1982 returning with the resultCode set to unavailable. In cases where a 1983 non-success result code is returned, the LDAP session is left without 1984 a TLS layer. 1986 4.14.3. Removal of the TLS Layer 1988 Either the client or server MAY remove the TLS layer and leave the 1989 LDAP message layer intact by sending and receiving a TLS closure 1990 alert. 1992 Lightweight Directory Access Protocol Version 3 1994 The initiating protocol peer sends the TLS closure alert and MUST 1995 wait until it receives a TLS closure alert from the other peer before 1996 sending further LDAP PDUs. 1998 When a protocol peer receives the initial TLS closure alert, it may 1999 choose to allow the LDAP message layer to remain intact. In this 2000 case, it MUST immediately transmit a TLS closure alert. Following 2001 this, it MAY send and receive LDAP PDUs. 2003 Protocol peers MAY terminate the LDAP session after sending or 2004 receiving a TLS closure alert. 2006 5. Protocol Encoding, Connection, and Transfer 2008 This protocol is designed to run over connection-oriented, reliable 2009 transports, where the data stream is divided into octets (8-bit 2010 units), with each octet and each bit being significant. 2012 One underlying service, LDAP over TCP, is defined in Section 2013 5.2. This service is generally applicable to applications providing 2014 or consuming X.500-based directory services on the Internet. This 2015 specification was generally written with the TCP mapping in mind. 2016 Specifications detailing other mappings may encounter various 2017 obstacles. 2019 Implementations of LDAP over TCP MUST implement the mapping as 2020 described in Section 5.2. 2022 This table illustrates the relationship between the different layers 2023 involved in an exchange between two protocol peers: 2025 +----------------------+ 2026 | LDAP message layer | 2027 +----------------------+ > LDAP PDUs 2028 +----------------------+ < data 2029 | SASL layer | 2030 +----------------------+ > SASL-protected data 2031 +----------------------+ < data 2032 | TLS layer | 2033 Application +----------------------+ > TLS-protected data 2034 ------------+----------------------+ < data 2035 Transport | transport connection | 2036 +----------------------+ 2038 5.1. Protocol Encoding 2040 The protocol elements of LDAP SHALL be encoded for exchange using the 2041 Basic Encoding Rules [BER] of [ASN.1] with the following 2042 restrictions: 2044 - Only the definite form of length encoding is used. 2046 Lightweight Directory Access Protocol Version 3 2048 - OCTET STRING values are encoded in the primitive form only. 2050 - If the value of a BOOLEAN type is true, the encoding of the value 2051 octet is set to hex "FF". 2053 - If a value of a type is its default value, it is absent. Only some 2054 BOOLEAN and INTEGER types have default values in this protocol 2055 definition. 2057 These restrictions are meant to ease the overhead of encoding and 2058 decoding certain elements in BER. 2060 These restrictions do not apply to ASN.1 types encapsulated inside of 2061 OCTET STRING values, such as attribute values, unless otherwise 2062 stated. 2064 5.2. Transmission Control Protocol (TCP) 2066 The encoded LDAPMessage PDUs are mapped directly onto the [TCP] 2067 bytestream using the BER-based encoding described in Section 5.1. It 2068 is recommended that server implementations running over the TCP 2069 provide a protocol listener on the Internet Assigned Numbers 2070 Authority (IANA)-assigned LDAP port, 389 [PortReg]. Servers may 2071 instead provide a listener on a different port number. Clients MUST 2072 support contacting servers on any valid TCP port. 2074 5.3. Termination of the LDAP session 2076 Termination of the LDAP session is typically initiated by the client 2077 sending an UnbindRequest (Section 4.3), or by the server sending a 2078 Notice of Disconnection (Section 4.4.1). In these cases each protocol 2079 peer gracefully terminates the LDAP session by ceasing exchanges at 2080 the LDAP message layer, tearing down any SASL layer, tearing down any 2081 TLS layer, and closing the transport connection. 2083 A protocol peer may determine that the continuation of any 2084 communication would be pernicious, and in this case may abruptly 2085 terminate the session by ceasing communication and closing the 2086 transport connection. 2088 In either case, when the LDAP session is terminated, uncompleted 2089 operations are handled as specified in Section 3.1. 2091 6. Security Considerations 2093 This version of the protocol provides facilities for simple 2094 authentication using a cleartext password, as well as any [SASL] 2095 mechanism. Installing SASL and/or TLS layers can provide integrity 2096 and other data security services. 2098 Lightweight Directory Access Protocol Version 3 2100 It is also permitted that the server can return its credentials to 2101 the client, if it chooses to do so. 2103 Use of cleartext password is strongly discouraged where the 2104 underlying transport service cannot guarantee confidentiality and may 2105 result in disclosure of the password to unauthorized parties. 2107 Servers are encouraged to prevent directory modifications by clients 2108 that have authenticated anonymously [AuthMeth]. 2110 Security considerations for authentication methods, SASL mechanisms, 2111 and TLS are described in [AuthMeth]. 2113 It should be noted that SASL authentication exchanges do not provide 2114 data confidentiality nor integrity protection for the version or name 2115 fields of the BindRequest nor the resultCode, diagnosticMessage, or 2116 referral fields of the BindResponse nor of any information contained 2117 in controls attached to Bind requests or responses. Thus information 2118 contained in these fields SHOULD NOT be relied on unless otherwise 2119 protected (such as by establishing protections at the transport 2120 layer). 2122 Implementors should note that various security factors, including 2123 authentication and authorization information and data security 2124 services may change during the course of the LDAP session, or even 2125 during the performance of a particular operation. For instance, 2126 credentials could expire, authorization identities or access controls 2127 could change, or the underlying security layer(s) could be replaced 2128 or terminated. Implementations should be robust in the handling of 2129 changing security factors. 2130 In some cases, it may be appropriate to continue the operation even 2131 in light of security factor changes. For instance, it may be 2132 appropriate to continue an Abandon operation regardless of the 2133 change, or to continue an operation when the change upgraded (or 2134 maintained) the security factor. In other cases, it may be 2135 appropriate to fail, or alter the processing of the operation. For 2136 instance, if confidential protections were removed, it would be 2137 appropriate to either fail a request to return sensitive data, or 2138 minimally, to exclude the return of sensitive data. 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 Lightweight Directory Access Protocol Version 3 2150 Servers may return referrals or Search result references which 2151 redirect clients to peer servers. It is possible for a rogue 2152 application to inject such referrals into the data stream in an 2153 attempt to redirect a client to a rogue server. Clients are advised 2154 to be aware of this, and possibly reject referrals when 2155 confidentiality measures are not in place. Clients are advised to 2156 reject referrals from the StartTLS operation. 2158 The matchedDN and diagnosticMessage fields, as well as some 2159 resultCode values (e.g., attributeOrValueExists and 2160 entryAlreadyExists), could disclose the presence or absence of 2161 specific data in the directory which is subject to access and other 2162 administrative controls. Server implementations should restrict 2163 access to protected information equally under both normal and error 2164 conditions. 2166 Protocol peers MUST be prepared to handle invalid and arbitrary 2167 length protocol encodings. Invalid protocol encodings include: BER 2168 encoding exceptions, format string and UTF-8 encoding exceptions, 2169 overflow exceptions, integer value exceptions, and binary mode on/off 2170 flag exceptions. The LDAPv3 PROTOS [PROTOS-LDAP] test suite provides 2171 excellent examples of these exceptions and test cases used to 2172 discover flaws. 2174 In the event that a protocol peer senses an attack which in its 2175 nature could cause damage due to further communication at any layer 2176 in the LDAP session, the protocol peer should abruptly terminate the 2177 LDAP session as described in Section 5.3. 2179 7. Acknowledgements 2181 This document is based on RFC 2251 by Mark Wahl, Tim Howes, and Steve 2182 Kille. RFC 2251 was a product of the IETF ASID Working Group. 2184 It is also based on RFC 2830 by Jeff Hodges, RL "Bob" Morgan, and 2185 Mark Wahl. RFC 2830 was a product of the IETF LDAPEXT Working Group. 2187 It is also based on RFC 3771 by Roger Harrison, and Kurt Zeilenga. 2188 RFC 3771 was an individual submission to the IETF. 2190 This document is a product of the IETF LDAPBIS Working Group. 2191 Significant contributors of technical review and content include Kurt 2192 Zeilenga, Steven Legg, and Hallvard Furuseth. 2194 8. Normative References 2196 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2197 Specifications: ABNF", draft-crocker-abnf-rfc2234bis- 2198 xx.txt, (a work in progress). 2200 Lightweight Directory Access Protocol Version 3 2202 [ASN.1] ITU-T Recommendation X.680 (07/2002) | ISO/IEC 8824-1:2002 2203 "Information Technology - Abstract Syntax Notation One 2204 (ASN.1): Specification of basic notation" 2206 [AuthMeth] Harrison, R., "LDAP: Authentication Methods and Connection 2207 Level Security Mechanisms", draft-ietf-ldapbis-authmeth- 2208 xx.txt, (a work in progress). 2210 [BER] ITU-T Rec. X.690 (07/2002) | ISO/IEC 8825-1:2002, 2211 "Information technology - ASN.1 encoding rules: 2212 Specification of Basic Encoding Rules (BER), Canonical 2213 Encoding Rules (CER) and Distinguished Encoding Rules 2214 (DER)", 2002. 2216 [IP] Postel, J., "Internet Protocol", STD5 and RFC 791, 2217 September 1981 2219 [ISO10646] Universal Multiple-Octet Coded Character Set (UCS) - 2220 Architecture and Basic Multilingual Plane, ISO/IEC 10646-1 2221 : 1993. 2223 [Keyword] Bradner, S., "Key words for use in RFCs to Indicate 2224 Requirement Levels", RFC 2119, March 1997. 2226 [LDAPDN] Zeilenga, K., "LDAP: String Representation of 2227 Distinguished Names", draft-ietf-ldapbis-dn-xx.txt, (a 2228 work in progress). 2230 [LDAPIANA] Zeilenga, K., "IANA Considerations for LDAP", draft-ietf- 2231 ldapbis-bcp64-xx.txt, (a work in progress). 2233 [LDAPURL] Smith, M., "LDAP: Uniform Resource Locator", draft-ietf- 2234 ldapbis-url-xx.txt, (a work in progress). 2236 [Models] Zeilenga, K., "LDAP: Directory Information Models", draft- 2237 ietf-ldapbis-models-xx.txt (a work in progress). 2239 [Roadmap] Zeilenga, K., "LDAP: Technical Specification Road Map", 2240 draft-ietf-ldapbis-roadmap-xx.txt (a work in progress). 2242 [SASL] Melnikov, A., "Simple Authentication and Security Layer", 2243 draft-ietf-sasl-rfc2222bis-xx.txt (a work in progress). 2245 [SASLPrep] Zeilenga, K., "Stringprep profile for user names and 2246 passwords", draft-ietf-sasl-saslprep-xx.txt, (a work in 2247 progress). 2249 [StringPrep] Hoffman P. and M. Blanchet, "Preparation of 2250 Internationalized Strings ('stringprep')", draft-hoffman- 2251 rfc3454bis-xx.txt, a work in progress. 2253 [Syntaxes] Legg, S., and K. Dally, "LDAP: Syntaxes and Matching 2254 Rules", draft-ietf-ldapbis-syntaxes-xx.txt, (a work in 2255 progress). 2257 Lightweight Directory Access Protocol Version 3 2259 [TCP] Postel, J., "Transmission Control Protocol", STD7 and RFC 2260 793, September 1981 2262 [TLS] Dierks, T. and C. Allen. "The TLS Protocol Version 1.1", 2263 draft-ietf-tls-rfc2246-bis-xx.txt, a work in progress. 2265 [Unicode] The Unicode Consortium, "The Unicode Standard, Version 2266 3.2.0" is defined by "The Unicode Standard, Version 3.0" 2267 (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5), 2268 as amended by the "Unicode Standard Annex #27: Unicode 2269 3.1" (http://www.unicode.org/reports/tr27/) and by the 2270 "Unicode Standard Annex #28: Unicode 3.2" 2271 (http://www.unicode.org/reports/tr28/). 2273 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2274 Resource Identifiers (URI): Generic Syntax", RFC 2396, 2275 August 1998. 2277 [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO 2278 10646", STD63 and RFC3629, November 2003. 2280 [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts, 2281 Models and Service", 1993. 2283 [X.501] ITU-T Rec. X.501, "The Directory: Models", 1993. 2285 [X.511] ITU-T Rec. X.511, "The Directory: Abstract Service 2286 Definition", 1993. 2288 9. Informative References 2290 [Glossary] The Unicode Consortium, "Unicode Glossary", 2291 . 2293 [CharModel] Whistler, K. and M. Davis, "Unicode Technical Report 2294 #17, Character Encoding Model", UTR17, 2295 , August 2296 2000. 2298 [PROTOS-LDAP] University of Oulu, "PROTOS Test-Suite: c06-ldapv3" 2299 2302 [PortReg] IANA, "Port Numbers", 2303 http://www.iana.org/assignments/port-numbers 2305 10. IANA Considerations 2306 Lightweight Directory Access Protocol Version 3 2308 It is requested that the Internet Assigned Numbers Authority (IANA) 2309 update the LDAP result code registry to indicate that this document 2310 provides the definitive technical specification for result codes 0- 2311 36, 48-54, 64-70, 80-90. It is also noted that one resultCode value 2312 (strongAuthRequired) has been renamed (to strongerAuthRequired). 2314 It is requested that the IANA update the LDAP Protocol Mechanism 2315 registry to indicate that this document and [AuthMeth] provides the 2316 definitive technical specification for the StartTLS 2317 (1.3.6.1.4.1.1466.20037) Extended operation. 2319 It is requested that the IANA update the occurrence of "RFC XXXX" in 2320 this section and Appendix B with this RFC number at publication. 2322 It is requested that IANA assign upon Standards Action an LDAP Object 2323 Identifier [LDAPIANA] to identify the ASN.1 module defined in this 2324 document. 2326 Subject: Request for LDAP Object Identifier Registration 2327 Person & email address to contact for further information: 2328 Jim Sermersheim 2329 Specification: RFC XXXX 2330 Author/Change Controller: IESG 2331 Comments: 2332 Identifies the LDAP ASN.1 module 2334 [[Note to RFC Editor: please replace the occurrence of in Appendix B with the IANA assigned 2336 OID.]] 2338 11. Editor's Address 2340 Jim Sermersheim 2341 Novell, Inc. 2342 1800 South Novell Place 2343 Provo, Utah 84606, USA 2344 jimse@novell.com 2345 +1 801 861-3088 2346 Lightweight Directory Access Protocol Version 3 2348 Appendix A. LDAP Result Codes 2350 This normative appendix details additional considerations regarding 2351 LDAP result codes and provides a brief, general description of each 2352 LDAP result code enumerated in Section 4.1.9. 2354 Additional result codes MAY be defined for use with extensions 2355 [LDAPIANA]. Client implementations SHALL treat any result code which 2356 they do not recognize as an unknown error condition. 2358 The descriptions provided here do not fully account for result code 2359 substitutions used to prevent unauthorized disclosures (such as 2360 substitution of noSuchObject for insufficientAccessRights, or 2361 invalidCredentials for insufficientAccessRights). 2363 A.1. Non-Error Result Codes 2365 These result codes (called "non-error" result codes) do not indicate 2366 an error condition: 2367 success (0), 2368 compareFalse (5), 2369 compareTrue (6), 2370 referral (10), and 2371 saslBindInProgress (14). 2373 The success, compareTrue, and compareFalse result codes indicate 2374 successful completion (and, hence, are referred to as "successful" 2375 result codes). 2377 The referral and saslBindInProgress result codes indicate the client 2378 needs to take additional action to complete the operation. 2380 A.2. Result Codes 2382 Existing LDAP result codes are described as follows: 2384 success (0) 2385 Indicates the successful completion of an operation. Note: 2386 this code is not used with the Compare operation. See 2387 compareFalse (5) and compareTrue (6). 2389 operationsError (1) 2390 Indicates that the operation is not properly sequenced with 2391 relation to other operations (of same or different type). 2393 For example, this code is returned if the client attempts to 2394 StartTLS [TLS] while there are other uncompleted operations 2395 or if a TLS layer was already installed. 2397 protocolError (2) 2398 Indicates the server received data which is not well-formed. 2400 Lightweight Directory Access Protocol Version 3 2402 For Bind operation only, this code is also used to indicate 2403 that the server does not support the requested protocol 2404 version. 2406 For Extended operations only, this code is also used to 2407 indicate that the server does not support (by design or 2408 configuration) the Extended operation associated with the 2409 requestName. 2411 For request operations specifying multiple controls, this may 2412 be used to indicate that the server cannot ignore the order 2413 of the controls as specified, or that the combination of the 2414 specified controls is invalid or unspecified. 2416 timeLimitExceeded (3) 2417 Indicates that the time limit specified by the client was 2418 exceeded before the operation could be completed. 2420 sizeLimitExceeded (4) 2421 Indicates that the size limit specified by the client was 2422 exceeded before the operation could be completed. 2424 compareFalse (5) 2425 Indicates that the Compare operation has successfully 2426 completed and the assertion has evaluated to FALSE or 2427 Undefined. 2429 compareTrue (6) 2430 Indicates that the Compare operation has successfully 2431 completed and the assertion has evaluated to TRUE. 2433 authMethodNotSupported (7) 2434 Indicates that the authentication method or mechanism is not 2435 supported. 2437 strongerAuthRequired (8) 2438 Indicates the server requires strong(er) authentication in 2439 order to complete the operation. 2441 When used with the Notice of Disconnection operation, this 2442 code indicates that the server has detected that an 2443 established security association between the client and 2444 server has unexpectedly failed or been compromised. 2446 referral (10) 2447 Indicates that a referral needs to be chased to complete the 2448 operation (see Section 4.1.10). 2450 adminLimitExceeded (11) 2451 Indicates that an administrative limit has been exceeded. 2453 unavailableCriticalExtension (12) 2454 Indicates a critical control is unrecognized (see Section 2455 4.1.11). 2457 Lightweight Directory Access Protocol Version 3 2459 confidentialityRequired (13) 2460 Indicates that data confidentiality protections are required. 2462 saslBindInProgress (14) 2463 Indicates the server requires the client to send a new bind 2464 request, with the same SASL mechanism, to continue the 2465 authentication process (see Section 4.2). 2467 noSuchAttribute (16) 2468 Indicates that the named entry does not contain the specified 2469 attribute or attribute value. 2471 undefinedAttributeType (17) 2472 Indicates that a request field contains an unrecognized 2473 attribute description. 2475 inappropriateMatching (18) 2476 Indicates that an attempt was made (e.g. in an assertion) to 2477 use a matching rule not defined for the attribute type 2478 concerned. 2480 constraintViolation (19) 2481 Indicates that the client supplied an attribute value which 2482 does not conform to the constraints placed upon it by the 2483 data model. 2485 For example, this code is returned when multiple values are 2486 supplied to an attribute which has a SINGLE-VALUE constraint. 2488 attributeOrValueExists (20) 2489 Indicates that the client supplied an attribute or value to 2490 be added to an entry, but the attribute or value already 2491 exists. 2493 invalidAttributeSyntax (21) 2494 Indicates that a purported attribute value does not conform 2495 to the syntax of the attribute. 2497 noSuchObject (32) 2498 Indicates that the object does not exist in the DIT. 2500 aliasProblem (33) 2501 Indicates that an alias problem has occurred. For example, 2502 the code may used to indicate an alias has been dereferenced 2503 which names no object. 2505 invalidDNSyntax (34) 2506 Indicates that an LDAPDN or RelativeLDAPDN field (e.g. search 2507 base, target entry, ModifyDN newrdn, etc.) of a request does 2508 not conform to the required syntax or contains attribute 2509 values which do not conform to the syntax of the attribute's 2510 type. 2512 Lightweight Directory Access Protocol Version 3 2514 aliasDereferencingProblem (36) 2515 Indicates that a problem occurred while dereferencing an 2516 alias. Typically an alias was encountered in a situation 2517 where it was not allowed or where access was denied. 2519 inappropriateAuthentication (48) 2520 Indicates the server requires the client which had attempted 2521 to bind anonymously or without supplying credentials to 2522 provide some form of credentials. 2524 invalidCredentials (49) 2525 Indicates that the provided credentials (e.g. the user's name 2526 and password) are invalid. 2528 insufficientAccessRights (50) 2529 Indicates that the client does not have sufficient access 2530 rights to perform the operation. 2532 busy (51) 2533 Indicates that the server is too busy to service the 2534 operation. 2536 unavailable (52) 2537 Indicates that the server is shutting down or a subsystem 2538 necessary to complete the operation is offline. 2540 unwillingToPerform (53) 2541 Indicates that the server is unwilling to perform the 2542 operation. 2544 loopDetect (54) 2545 Indicates that the server has detected an internal loop (e.g. 2546 while dereferencing aliases or chaining an operation). 2548 namingViolation (64) 2549 Indicates that the entry's name violates naming restrictions. 2551 objectClassViolation (65) 2552 Indicates that the entry violates object class restrictions. 2554 notAllowedOnNonLeaf (66) 2555 Indicates that the operation is inappropriately acting upon a 2556 non-leaf entry. 2558 notAllowedOnRDN (67) 2559 Indicates that the operation is inappropriately attempting to 2560 remove a value which forms the entry's relative distinguished 2561 name. 2563 entryAlreadyExists (68) 2564 Indicates that the request cannot be fulfilled (added, moved, 2565 or renamed) as the target entry already exists. 2567 Lightweight Directory Access Protocol Version 3 2569 objectClassModsProhibited (69) 2570 Indicates that an attempt to modify the object class(es) of 2571 an entry's 'objectClass' attribute is prohibited. 2573 For example, this code is returned when a client attempts to 2574 modify the structural object class of an entry. 2576 affectsMultipleDSAs (71) 2577 Indicates that the operation cannot be performed as it would 2578 affect multiple servers (DSAs). 2580 other (80) 2581 Indicates the server has encountered an internal error. 2583 Lightweight Directory Access Protocol Version 3 2585 Appendix B. Complete ASN.1 Definition 2587 This appendix is normative. 2589 Lightweight-Directory-Access-Protocol-V3 {1 3 6 1 1 } 2591 -- Copyright (C) The Internet Society (2005). This version of 2592 -- this ASN.1 module is part of RFC XXXX; see the RFC itself 2593 -- for full legal notices. 2594 DEFINITIONS 2595 IMPLICIT TAGS 2596 EXTENSIBILITY IMPLIED ::= 2598 BEGIN 2600 LDAPMessage ::= SEQUENCE { 2601 messageID MessageID, 2602 protocolOp CHOICE { 2603 bindRequest BindRequest, 2604 bindResponse BindResponse, 2605 unbindRequest UnbindRequest, 2606 searchRequest SearchRequest, 2607 searchResEntry SearchResultEntry, 2608 searchResDone SearchResultDone, 2609 searchResRef SearchResultReference, 2610 modifyRequest ModifyRequest, 2611 modifyResponse ModifyResponse, 2612 addRequest AddRequest, 2613 addResponse AddResponse, 2614 delRequest DelRequest, 2615 delResponse DelResponse, 2616 modDNRequest ModifyDNRequest, 2617 modDNResponse ModifyDNResponse, 2618 compareRequest CompareRequest, 2619 compareResponse CompareResponse, 2620 abandonRequest AbandonRequest, 2621 extendedReq ExtendedRequest, 2622 extendedResp ExtendedResponse, 2623 ..., 2624 intermediateResponse IntermediateResponse }, 2625 controls [0] Controls OPTIONAL } 2627 MessageID ::= INTEGER (0 .. maxInt) 2629 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) -- 2631 LDAPString ::= OCTET STRING -- UTF-8 encoded, 2632 -- [ISO10646] characters 2634 LDAPOID ::= OCTET STRING -- Constrained to [Models] 2636 LDAPDN ::= LDAPString -- Constrained to 2637 -- [LDAPDN] 2638 Lightweight Directory Access Protocol Version 3 2640 RelativeLDAPDN ::= LDAPString -- Constrained to 2641 -- [LDAPDN] 2643 AttributeDescription ::= LDAPString 2644 -- Constrained to 2645 -- [Models] 2647 AttributeValue ::= OCTET STRING 2649 AttributeValueAssertion ::= SEQUENCE { 2650 attributeDesc AttributeDescription, 2651 assertionValue AssertionValue } 2653 AssertionValue ::= OCTET STRING 2655 PartialAttribute ::= SEQUENCE { 2656 type AttributeDescription, 2657 vals SET OF value AttributeValue } 2659 Attribute ::= PartialAttribute(WITH COMPONENTS { 2660 ..., 2661 vals (SIZE(1..MAX))}) 2663 MatchingRuleId ::= LDAPString 2664 Lightweight Directory Access Protocol Version 3 2666 LDAPResult ::= SEQUENCE { 2667 resultCode ENUMERATED { 2668 success (0), 2669 operationsError (1), 2670 protocolError (2), 2671 timeLimitExceeded (3), 2672 sizeLimitExceeded (4), 2673 compareFalse (5), 2674 compareTrue (6), 2675 authMethodNotSupported (7), 2676 strongerAuthRequired (8), 2677 -- 9 reserved -- 2678 referral (10), 2679 adminLimitExceeded (11), 2680 unavailableCriticalExtension (12), 2681 confidentialityRequired (13), 2682 saslBindInProgress (14), 2683 noSuchAttribute (16), 2684 undefinedAttributeType (17), 2685 inappropriateMatching (18), 2686 constraintViolation (19), 2687 attributeOrValueExists (20), 2688 invalidAttributeSyntax (21), 2689 -- 22-31 unused -- 2690 noSuchObject (32), 2691 aliasProblem (33), 2692 invalidDNSyntax (34), 2693 -- 35 reserved for undefined isLeaf -- 2694 aliasDereferencingProblem (36), 2695 -- 37-47 unused -- 2696 inappropriateAuthentication (48), 2697 invalidCredentials (49), 2698 insufficientAccessRights (50), 2699 busy (51), 2700 unavailable (52), 2701 unwillingToPerform (53), 2702 loopDetect (54), 2703 -- 55-63 unused -- 2704 namingViolation (64), 2705 objectClassViolation (65), 2706 notAllowedOnNonLeaf (66), 2707 notAllowedOnRDN (67), 2708 entryAlreadyExists (68), 2709 objectClassModsProhibited (69), 2710 -- 70 reserved for CLDAP -- 2711 affectsMultipleDSAs (71), 2712 -- 72-79 unused -- 2713 other (80), 2714 ... }, 2715 matchedDN LDAPDN, 2716 diagnosticMessage LDAPString, 2717 referral [3] Referral OPTIONAL } 2719 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI 2720 Lightweight Directory Access Protocol Version 3 2722 URI ::= LDAPString -- limited to characters permitted in 2723 -- URIs 2725 Controls ::= SEQUENCE OF control Control 2727 Control ::= SEQUENCE { 2728 controlType LDAPOID, 2729 criticality BOOLEAN DEFAULT FALSE, 2730 controlValue OCTET STRING OPTIONAL } 2732 BindRequest ::= [APPLICATION 0] SEQUENCE { 2733 version INTEGER (1 .. 127), 2734 name LDAPDN, 2735 authentication AuthenticationChoice } 2737 AuthenticationChoice ::= CHOICE { 2738 simple [0] OCTET STRING, 2739 -- 1 and 2 reserved 2740 sasl [3] SaslCredentials, 2741 ... } 2743 SaslCredentials ::= SEQUENCE { 2744 mechanism LDAPString, 2745 credentials OCTET STRING OPTIONAL } 2747 BindResponse ::= [APPLICATION 1] SEQUENCE { 2748 COMPONENTS OF LDAPResult, 2749 serverSaslCreds [7] OCTET STRING OPTIONAL } 2751 UnbindRequest ::= [APPLICATION 2] NULL 2753 SearchRequest ::= [APPLICATION 3] SEQUENCE { 2754 baseObject LDAPDN, 2755 scope ENUMERATED { 2756 baseObject (0), 2757 singleLevel (1), 2758 wholeSubtree (2), 2759 ... }, 2760 derefAliases ENUMERATED { 2761 neverDerefAliases (0), 2762 derefInSearching (1), 2763 derefFindingBaseObj (2), 2764 derefAlways (3) }, 2765 sizeLimit INTEGER (0 .. maxInt), 2766 timeLimit INTEGER (0 .. maxInt), 2767 typesOnly BOOLEAN, 2768 filter Filter, 2769 attributes AttributeSelection } 2771 AttributeSelection ::= SEQUENCE OF selector LDAPString 2772 -- The LDAPString is constrained to 2773 -- in Section 4.5.1.7 2774 Lightweight Directory Access Protocol Version 3 2776 Filter ::= CHOICE { 2777 and [0] SET SIZE (1..MAX) OF filter Filter, 2778 or [1] SET SIZE (1..MAX) OF filter Filter, 2779 not [2] Filter, 2780 equalityMatch [3] AttributeValueAssertion, 2781 substrings [4] SubstringFilter, 2782 greaterOrEqual [5] AttributeValueAssertion, 2783 lessOrEqual [6] AttributeValueAssertion, 2784 present [7] AttributeDescription, 2785 approxMatch [8] AttributeValueAssertion, 2786 extensibleMatch [9] MatchingRuleAssertion, 2787 ... } 2789 SubstringFilter ::= SEQUENCE { 2790 type AttributeDescription, 2791 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE { 2792 initial [0] AssertionValue, -- can occur at most once 2793 any [1] AssertionValue, 2794 final [2] AssertionValue } -- can occur at most once 2795 } 2797 MatchingRuleAssertion ::= SEQUENCE { 2798 matchingRule [1] MatchingRuleId OPTIONAL, 2799 type [2] AttributeDescription OPTIONAL, 2800 matchValue [3] AssertionValue, 2801 dnAttributes [4] BOOLEAN DEFAULT FALSE } 2803 SearchResultEntry ::= [APPLICATION 4] SEQUENCE { 2804 objectName LDAPDN, 2805 attributes PartialAttributeList } 2807 PartialAttributeList ::= SEQUENCE OF 2808 partialAttribute PartialAttribute 2810 SearchResultReference ::= [APPLICATION 19] SEQUENCE 2811 SIZE (1..MAX) OF uri URI 2813 SearchResultDone ::= [APPLICATION 5] LDAPResult 2815 ModifyRequest ::= [APPLICATION 6] SEQUENCE { 2816 object LDAPDN, 2817 changes SEQUENCE OF change SEQUENCE { 2818 operation ENUMERATED { 2819 add (0), 2820 delete (1), 2821 replace (2), 2822 ... }, 2823 modification PartialAttribute } } 2825 ModifyResponse ::= [APPLICATION 7] LDAPResult 2827 AddRequest ::= [APPLICATION 8] SEQUENCE { 2828 entry LDAPDN, 2829 attributes AttributeList } 2830 Lightweight Directory Access Protocol Version 3 2832 AttributeList ::= SEQUENCE OF attribute Attribute 2834 AddResponse ::= [APPLICATION 9] LDAPResult 2836 DelRequest ::= [APPLICATION 10] LDAPDN 2838 DelResponse ::= [APPLICATION 11] LDAPResult 2840 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE { 2841 entry LDAPDN, 2842 newrdn RelativeLDAPDN, 2843 deleteoldrdn BOOLEAN, 2844 newSuperior [0] LDAPDN OPTIONAL } 2846 ModifyDNResponse ::= [APPLICATION 13] LDAPResult 2848 CompareRequest ::= [APPLICATION 14] SEQUENCE { 2849 entry LDAPDN, 2850 ava AttributeValueAssertion } 2852 CompareResponse ::= [APPLICATION 15] LDAPResult 2854 AbandonRequest ::= [APPLICATION 16] MessageID 2856 ExtendedRequest ::= [APPLICATION 23] SEQUENCE { 2857 requestName [0] LDAPOID, 2858 requestValue [1] OCTET STRING OPTIONAL } 2860 ExtendedResponse ::= [APPLICATION 24] SEQUENCE { 2861 COMPONENTS OF LDAPResult, 2862 responseName [10] LDAPOID OPTIONAL, 2863 responseValue [11] OCTET STRING OPTIONAL } 2865 IntermediateResponse ::= [APPLICATION 25] SEQUENCE { 2866 responseName [0] LDAPOID OPTIONAL, 2867 responseValue [1] OCTET STRING OPTIONAL } 2869 END 2870 Lightweight Directory Access Protocol Version 3 2872 Appendix C. Changes 2874 This appendix is non-normative. 2876 This appendix summarizes substantive changes made to RFC 2251, RFC 2877 2830, and RFC 3771. 2879 C.1. Changes made to RFC 2251: 2881 This section summarizes the substantive changes made to Sections 1, 2882 2, 3.1, and 4 through the remainder of RFC 2251. Readers should 2883 consult [Models] and [AuthMeth] for summaries of changes to other 2884 sections. 2886 C.1.1. Section 1 (Status of this Memo) 2888 - Removed IESG note. Post publication of RFC 2251, mandatory LDAP 2889 authentication mechanisms have been standardized which are 2890 sufficient to remove this note. See [AuthMeth] for authentication 2891 mechanisms. 2893 C.1.2. Section 3.1 (Protocol Model) and others 2895 - Removed notes giving history between LDAP v1, v2 and v3. Instead, 2896 added sufficient language so that this document can stand on its 2897 own. 2899 C.1.3. Section 4 (Elements of Protocol) 2901 - Clarified where the extensibility features of ASN.1 apply to the 2902 protocol. This change affected various ASN.1 types by the 2903 inclusion of ellipses (...) to certain elements. 2904 - Removed the requirement that servers which implement version 3 or 2905 later MUST provide the 'supportedLDAPVersion' attribute. This 2906 statement provided no interoperability advantages. 2908 C.1.4. Section 4.1.1 (Message Envelope) 2910 - There was a mandatory requirement for the server to return a 2911 Notice of Disconnection and drop the transport connection when a 2912 PDU is malformed in a certain way. This has been updated such that 2913 the server SHOULD return the Notice of Disconnection, and MUST 2914 terminate the LDAP Session. 2916 C.1.5. Section 4.1.1.1 (Message ID) 2918 - Required that the messageID of requests MUST be non-zero as the 2919 zero is reserved for Notice of Disconnection. 2921 Lightweight Directory Access Protocol Version 3 2923 - Specified when it is and isn't appropriate to return an already 2924 used message id. RFC 2251 accidentally imposed synchronous server 2925 behavior in its wording of this. 2927 C.1.6. Section 4.1.2 (String Types) 2929 - Stated that LDAPOID is constrained to from [Models]. 2931 C.1.7. Section 4.1.5.1 (Binary Option) and others 2933 - Removed the Binary Option from the specification. There are 2934 numerous interoperability problems associated with this method of 2935 alternate attribute type encoding. Work to specify a suitable 2936 replacement is ongoing. 2938 C.1.8. Section 4.1.8 (Attribute) 2940 - Combined the definitions of PartialAttribute and Attribute here, 2941 and defined Attribute in terms of PartialAttribute. 2943 C.1.9. Section 4.1.10 (Result Message) 2945 - Renamed "errorMessage" to "diagnosticMessage" as it is allowed to 2946 be sent for non-error results. 2947 - Moved some language into Appendix A, and refer the reader there. 2948 - Allowed matchedDN to be present for other result codes than those 2949 listed in RFC 2251. 2950 - renamed the code "strongAuthRequired" to "strongerAuthRequired" to 2951 clarify that this code may often be returned to indicate that a 2952 stronger authentication is needed to perform a given operation. 2954 C.1.10. Section 4.1.11 (Referral) 2956 - Defined referrals in terms of URIs rather than URLs. 2957 - Removed the requirement that all referral URIs MUST be equally 2958 capable of progressing the operation. The statement was ambiguous 2959 and provided no instructions on how to carry it out. 2960 - Added the requirement that clients MUST NOT loop between servers. 2961 - Clarified the instructions for using LDAPURLs in referrals, and in 2962 doing so added a recommendation that the scope part be present. 2963 - Removed imperatives which required clients to use URLs in specific 2964 ways to progress an operation. These did nothing for 2965 interoperability. 2967 C.1.11. Section 4.1.12 (Controls) 2969 - Specified how control values defined in terms of ASN.1 are to be 2970 encoded. 2972 Lightweight Directory Access Protocol Version 3 2974 - Noted that the criticality field is only applied to request 2975 messages (except UnbindRequest), and must be ignored when present 2976 on response messages and UnbindRequest. 2977 - Specified that non-critical controls may be ignored at the 2978 server's discretion. There was confusion in the original wording 2979 which led some to believe that recognized controls may not be 2980 ignored as long as they were associated with a proper request. 2981 - Added language regarding combinations of controls and the ordering 2982 of controls on a message. 2983 - Specified that when the semantics of the combination of controls 2984 is undefined or unknown, it results in a protocolError. 2985 - Changed "The server MUST be prepared" to "Implementations MUST be 2986 prepared" in the eighth paragraph to reflect that both client and 2987 server implementations must be able to handle this (as both parse 2988 controls). 2990 C.1.12. Section 4.2 (Bind Operation) 2992 - Mandated that servers return protocolError when the version is not 2993 supported. 2994 - Disambiguated behavior when the simple authentication is used, the 2995 name is empty and the password is non-empty. 2996 - Required servers to not dereference aliases for Bind. This was 2997 added for consistency with other operations and to help ensure 2998 data consistency. 2999 - Required that textual passwords be transferred as UTF-8 encoded 3000 Unicode, and added recommendations on string preparation. This was 3001 to help ensure interoperability of passwords being sent from 3002 different clients. 3004 C.1.13. Section 4.2.1 (Sequencing of the Bind Request) 3006 - This section was largely reorganized for readability and language 3007 was added to clarify the authentication state of failed and 3008 abandoned Bind operations. 3009 - Removed: "If a SASL transfer encryption or integrity mechanism has 3010 been negotiated, that mechanism does not support the changing of 3011 credentials from one identity to another, then the client MUST 3012 instead establish a new connection." 3013 If there are dependencies between multiple negotiations of a 3014 particular SASL mechanism, the technical specification for that 3015 SASL mechanism details how applications are to deal with them. 3016 LDAP should not require any special handling. 3017 - Dropped MUST imperative in paragraph 3 to align with [Keywords]. 3018 - Mandated that clients not send non-Bind operations while a Bind is 3019 in progress, and suggested that servers not process them if they 3020 are received. This is needed to ensure proper sequencing of the 3021 Bind in relationship to other operations. 3023 Lightweight Directory Access Protocol Version 3 3025 C.1.14. Section 4.2.3 (Bind Response) 3027 - Moved most error-related text to Appendix A, and added text 3028 regarding certain errors used in conjunction with the Bind 3029 operation. 3030 - Prohibited the server from specifying serverSaslCreds when not 3031 appropriate. 3033 C.1.15. Section 4.3 (Unbind Operation) 3035 - Specified that both peers are to cease transmission and terminate 3036 the LDAP session for the Unbind operation. 3038 C.1.16. Section 4.4 (Unsolicited Notification) 3040 - Added instructions for future specifications of Unsolicited 3041 Notifications. 3043 C.1.17. Section 4.5.1 (Search Request) 3045 - SearchRequest attributes is now defined as an AttributeSelection 3046 type rather than AttributeDescriptionList, and an ABNF is 3047 provided. 3048 - SearchRequest attributes may contain duplicate attribute 3049 descriptions. This was previously prohibited. Now servers are 3050 instructed to ignore subsequent names when they are duplicated. 3051 This was relaxed in order to allow different short names and also 3052 OIDs to be requested for an attribute. 3053 - The present search filter now evaluates to Undefined when the 3054 specified attribute is not known to the server. It used to 3055 evaluate to FALSE, which caused behavior inconsistent with what 3056 most would expect, especially when the not operator was used. 3057 - The Filter choice SubstringFilter substrings type is now defined 3058 with a lower bound of 1. 3059 - The SubstringFilter substrings 'initial, 'any', and 'final' types 3060 are now AssertionValue rather than LDAPString. Also, added 3061 imperatives stating that 'initial' (if present) must be listed 3062 first, and 'final' (if present) must be listed last. 3063 - Disambiguated the semantics of the derefAliases choices. There was 3064 question as to whether derefInSearching applied to the base object 3065 in a wholeSubtree Search. 3066 - Added instructions for equalityMatch, substrings, greaterOrEqual, 3067 lessOrEqual, and approxMatch. 3069 C.1.18. Section 4.5.2 (Search Result) 3071 - Recommended that servers not use attribute short names when it 3072 knows they are ambiguous or may cause interoperability problems. 3073 - Removed all mention of ExtendedResponse due to lack of 3074 implementation. 3076 Lightweight Directory Access Protocol Version 3 3078 C.1.19. Section 4.5.3 (Continuation References in the Search Result) 3080 - Made changes similar to those made to Section 4.1.11. 3082 C.1.20. Section 4.5.3.1 (Example) 3084 - Fixed examples to adhere to changes made to Section 4.5.3. 3086 C.1.21. Section 4.6 (Modify Operation) 3088 - Replaced AttributeTypeAndValues with Attribute as they are 3089 equivalent. 3090 - Specified the types of modification changes which might 3091 temporarily violate schema. Some readers were under the impression 3092 that any temporary schema violation was allowed. 3094 C.1.22. Section 4.7 (Add Operation) 3096 - Aligned Add operation with X.511 in that the attributes of the RDN 3097 are used in conjunction with the listed attributes to create the 3098 entry. Previously, Add required that the distinguished values be 3099 present in the listed attributes. 3100 - Removed requirement that the objectClass attribute MUST be 3101 specified as some DSE types do not require this attribute. 3102 Instead, generic wording was added, requiring the added entry to 3103 adhere to the data model. 3104 - Removed recommendation regarding placement of objects. This is 3105 covered in the data model document. 3107 C.1.23. Section 4.9 (Modify DN Operation) 3109 - Required servers to not dereference aliases for Modify DN. This 3110 was added for consistency with other operations and to help ensure 3111 data consistency. 3112 - Allow Modify DN to fail when moving between naming contexts. 3113 - Specified what happens when the attributes of the newrdn are not 3114 present on the entry. 3116 C.1.24. Section 4.10 (Compare Operation) 3118 - Specified that compareFalse means that the Compare took place and 3119 the result is false. There was confusion which lead people to 3120 believe that an Undefined match resulted in compareFalse. 3121 - Required servers to not dereference aliases for Compare. This was 3122 added for consistency with other operations and to help ensure 3123 data consistency. 3125 Lightweight Directory Access Protocol Version 3 3127 C.1.25. Section 4.11 (Abandon Operation) 3129 - Explained that since Abandon returns no response, clients should 3130 not use it if they need to know the outcome. 3131 - Specified that Abandon and Unbind cannot be abandoned. 3133 C.1.26. Section 4.12 (Extended Operation) 3135 - Specified how values of Extended operations defined in terms of 3136 ASN.1 are to be encoded. 3137 - Added instructions on what Extended operation specifications 3138 consist of. 3139 - Added a recommendation that servers advertise supported Extended 3140 operations. 3142 C.1.27. Section 5.2 (Transfer Protocols) 3144 - Moved referral-specific instructions into referral-related 3145 sections. 3147 C.1.28. Section 7 (Security Considerations) 3149 - Reworded notes regarding SASL not protecting certain aspects of 3150 the LDAP Bind messages. 3151 - Noted that Servers are encouraged to prevent directory 3152 modifications by clients that have authenticated anonymously 3153 [AuthMeth]. 3154 - Added a note regarding the possibility of changes to security 3155 factors (authentication, authorization, data confidentiality). 3156 - Warned against following referrals that may have been injected in 3157 the data stream. 3158 - Noted that servers should protect information equally, whether in 3159 an error condition or not, and mentioned specifically; matchedDN, 3160 diagnosticMessage, and resultCodes. 3161 - Added a note regarding malformed and long encodings. 3163 C.1.29. Appendix A (Complete ASN.1 Definition) 3165 - Added "EXTENSIBILITY IMPLIED" to ASN.1 definition. 3166 - Removed AttributeType. It is not used. 3168 C.2. Changes made to RFC 2830: 3170 This section summarizes the substantive changes made to Sections of 3171 RFC 2830. Readers should consult [AuthMeth] for summaries of changes 3172 to other sections. 3174 Lightweight Directory Access Protocol Version 3 3176 C.2.1. Section 2.3 (Response other than "success") 3178 - Removed wording indicating that referrals can be returned from 3179 StartTLS. 3180 - Removed requirement that only a narrow set of result codes can be 3181 returned. Some result codes are required in certain scenarios, but 3182 any other may be returned if appropriate. 3183 - Removed requirement that the ExtendedResponse.responseName MUST be 3184 present. There are circumstances where this is impossible, and 3185 requiring this is at odds with language in Section 4.12. 3187 C.2.1. Section 4 (Closing a TLS Connection) 3189 - Reworded most of this section to align with definitions of the 3190 LDAP protocol layers. 3191 - Removed instructions on abrupt closure as this is covered in other 3192 areas of the document (specifically, Section 5.3) 3194 C.3. Changes made to RFC 3771: 3196 - Rewrote to fit into this document. In general, semantics were 3197 preserved. Supporting and background language seen as redundant 3198 due to its presence in this document was omitted. 3199 - Specified that Intermediate responses to a request may be of 3200 different types, and one of the response types may be specified to 3201 have no response value. 3203 Lightweight Directory Access Protocol Version 3 3205 Intellectual Property Statement 3207 The IETF takes no position regarding the validity or scope of any 3208 Intellectual Property Rights or other rights that might be claimed to 3209 pertain to the implementation or use of the technology described in 3210 this document or the extent to which any license under such rights 3211 might or might not be available; nor does it represent that it has 3212 made any independent effort to identify any such rights. Information 3213 on the procedures with respect to rights in RFC documents can be 3214 found in BCP 78 and BCP 79. 3216 Copies of IPR disclosures made to the IETF Secretariat and any 3217 assurances of licenses to be made available, or the result of an 3218 attempt made to obtain a general license or permission for the use of 3219 such proprietary rights by implementers or users of this 3220 specification can be obtained from the IETF on-line IPR repository at 3221 http://www.ietf.org/ipr. 3223 The IETF invites any interested party to bring to its attention any 3224 copyrights, patents or patent applications, or other proprietary 3225 rights that may cover technology that may be required to implement 3226 this standard. Please address the information to the IETF at ietf- 3227 ipr@ietf.org. 3229 Disclaimer of Validity 3231 This document and the information contained herein are provided on an 3232 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 3233 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 3234 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 3235 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 3236 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 3237 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3239 Copyright Statement 3241 Copyright (C) The Internet Society (2005). 3243 This document is subject to the rights, licenses and restrictions 3244 contained in BCP 78, and except as set forth therein, the authors 3245 retain all their rights. 3247 Acknowledgement 3249 Funding for the RFC Editor function is currently provided by the 3250 Internet Society.