idnits 2.17.1 draft-ietf-ldapbis-protocol-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. 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 : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) == 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. 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 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 (March 2002) is 8070 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 2313 -- Looks like a reference, but probably isn't: '3' on line 2250 == Missing Reference: 'APPLICATION 0' is mentioned on line 2186, but not defined == Missing Reference: 'APPLICATION 1' is mentioned on line 2201, but not defined -- Looks like a reference, but probably isn't: '7' on line 2234 == Missing Reference: 'APPLICATION 2' is mentioned on line 2205, but not defined == Missing Reference: 'APPLICATION 3' is mentioned on line 2207, but not defined -- Looks like a reference, but probably isn't: '1' on line 2314 -- Looks like a reference, but probably isn't: '2' on line 2249 -- Looks like a reference, but probably isn't: '4' on line 2251 -- Looks like a reference, but probably isn't: '5' on line 2860 -- Looks like a reference, but probably isn't: '6' on line 2233 -- Looks like a reference, but probably isn't: '8' on line 2235 -- Looks like a reference, but probably isn't: '9' on line 2236 == Missing Reference: 'APPLICATION 4' is mentioned on line 2253, but not defined == Missing Reference: 'APPLICATION 19' is mentioned on line 2261, but not defined == Missing Reference: 'APPLICATION 5' is mentioned on line 2263, but not defined == Missing Reference: 'APPLICATION 6' is mentioned on line 2265, but not defined == Missing Reference: 'APPLICATION 7' is mentioned on line 2280, but not defined == Missing Reference: 'APPLICATION 8' is mentioned on line 2282, but not defined == Missing Reference: 'APPLICATION 9' is mentioned on line 2290, but not defined == Missing Reference: 'APPLICATION 10' is mentioned on line 2292, but not defined == Missing Reference: 'APPLICATION 11' is mentioned on line 2294, but not defined == Missing Reference: 'APPLICATION 12' is mentioned on line 2296, but not defined == Missing Reference: 'APPLICATION 13' is mentioned on line 2302, but not defined == Missing Reference: 'APPLICATION 14' is mentioned on line 2304, but not defined == Missing Reference: 'APPLICATION 15' is mentioned on line 2308, but not defined == Missing Reference: 'APPLICATION 16' is mentioned on line 2310, but not defined == Missing Reference: 'APPLICATION 23' is mentioned on line 2312, but not defined == Missing Reference: 'APPLICATION 24' is mentioned on line 2316, but not defined -- Looks like a reference, but probably isn't: '10' on line 2318 -- Looks like a reference, but probably isn't: '11' on line 2319 == Missing Reference: 'X511' is mentioned on line 1799, but not defined == Missing Reference: 'RFC2830' is mentioned on line 2997, but not defined ** Obsolete undefined reference: RFC 2830 (Obsoleted by RFC 4510, RFC 4511, RFC 4513) == Missing Reference: 'RFC2252' is mentioned on line 2862, but not defined ** Obsolete undefined reference: RFC 2252 (Obsoleted by RFC 4510, RFC 4512, RFC 4517, RFC 4523) == Missing Reference: 'RFC2829' is mentioned on line 3003, but not defined ** Obsolete undefined reference: RFC 2829 (Obsoleted by RFC 4510, RFC 4513) -- 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-ldapbis-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'LDAPIANA' -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO10646' ** Obsolete normative reference: RFC 2044 (Obsoleted by RFC 2279) -- 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-dn-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'LDAPDN' -- 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 2396 (Obsoleted by RFC 3986) -- No information found for draft-ietf-ldapbis-authmeth-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'AuthMeth' ** Obsolete normative reference: RFC 2222 (Obsoleted by RFC 4422, RFC 4752) Summary: 8 errors (**), 0 flaws (~~), 27 warnings (==), 27 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-07.txt March 2002 5 Obsoletes: RFC 2251 7 LDAP: The Protocol 9 Status of this Memo 11 This document is an Internet-Draft and is in full conformance with 12 all provisions of Section 10 of RFC2026. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that other 16 groups may also distribute working documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six months 18 and may be updated, replaced, or obsoleted by other documents at any 19 time. It is inappropriate to use Internet-Drafts as reference 20 material or to cite them other than as "work in progress." 22 The list of current Internet-Drafts can be accessed at 23 http://www.ietf.org/ietf/1id-abstracts.txt 25 The list of Internet-Draft Shadow Directories can be accessed at 26 http://www.ietf.org/shadow.html. 28 Distribution of this memo is unlimited. Technical discussion of this 29 document will take place on the IETF LDAP Revision Working Group 30 (LDAPbis) mailing list . Please send 31 editorial comments directly to the editor . 33 Abstract 35 This document describes the protocol elements, along with their 36 semantics and encodings, for the Lightweight Directory Access 37 Protocol (LDAP). LDAP provides access to distributed directory 38 services that act in accordance with X.500 data and service models. 39 These protocol elements are based on those described in the X.500 40 Directory Access Protocol (DAP). 42 Table of Contents 44 1. Introduction.....................................................2 45 2. Conventions......................................................3 46 3. Protocol Model...................................................3 47 4. Elements of Protocol.............................................3 48 4.1. Common Elements................................................4 49 4.1.1. Message Envelope.............................................4 50 4.1.1.1. Message ID.................................................5 51 4.1.2. String Types.................................................6 52 Lightweight Directory Access Protocol Version 3 54 4.1.3. Distinguished Name and Relative Distinguished Name...........6 55 4.1.5. Attribute Description........................................6 56 4.1.5.1. Binary Transfer Option.....................................7 57 4.1.6. Attribute Value..............................................8 58 4.1.7. Attribute Value Assertion....................................8 59 4.1.8. Attribute....................................................9 60 4.1.9. Matching Rule Identifier.....................................9 61 4.1.10. Result Message.............................................10 62 4.1.11. Referral...................................................11 63 4.1.12. Controls...................................................12 64 4.2. Bind Operation................................................13 65 4.2.1. Sequencing of the Bind Request..............................14 66 4.2.3. Bind Response...............................................15 67 4.3. Unbind Operation..............................................16 68 4.4. Unsolicited Notification......................................16 69 4.4.1. Notice of Disconnection.....................................17 70 4.5. Search Operation..............................................17 71 4.5.1. Search Request..............................................17 72 4.5.2. Search Result...............................................21 73 4.5.3. Continuation References in the Search Result................22 74 4.6. Modify Operation..............................................24 75 4.7. Add Operation.................................................25 76 4.8. Delete Operation..............................................26 77 4.9. Modify DN Operation...........................................27 78 4.10. Compare Operation............................................28 79 4.11. Abandon Operation............................................29 80 4.12. Extended Operation...........................................29 81 5. Protocol Element Encodings and Transfer.........................30 82 5.1. Protocol Encoding.............................................30 83 5.2. Transfer Protocols............................................30 84 5.2.1. Transmission Control Protocol (TCP).........................31 85 6. Implementation Guidelines.......................................31 86 6.1. Server Implementations........................................31 87 6.2. Client Implementations........................................31 88 7. Security Considerations.........................................31 89 8. Acknowledgements................................................32 90 9. Normative References............................................32 91 10. Editor's Address...............................................33 92 Appendix A - LDAP Result Codes.....................................34 93 A.1 Non-Error Result Codes.........................................34 94 A.2 Error Result Codes.............................................34 95 A.3 Classes and Precedence of Error Result Codes...................34 96 Appendix C - Change History........................................45 97 C.1 Changes made to RFC 2251:......................................45 98 C.2 Changes made to draft-ietf-ldapbis-protocol-00.txt:............45 99 C.3 Changes made to draft-ietf-ldapbis-protocol-01.txt:............46 100 C.4 Changes made to draft-ietf-ldapbis-protocol-02.txt:............46 101 C.5 Changes made to draft-ietf-ldapbis-protocol-03.txt:............48 102 C.6 Changes made to draft-ietf-ldapbis-protocol-04.txt:............50 103 C.7 Changes made to draft-ietf-ldapbis-protocol-05.txt:............50 104 Appendix D - Outstanding Work Items................................54 106 1. Introduction 107 Lightweight Directory Access Protocol Version 3 109 The Directory is "a collection of open systems cooperating to provide 110 directory services" [X.500]. A Directory user, which may be a human 111 or other entity, accesses the Directory through a client (or 112 Directory User Agent (DUA)). The client, on behalf of the directory 113 user, interacts with one or more servers (or Directory System Agents 114 (DSA)). Clients interact with servers using a directory access 115 protocol. 117 This document details the protocol elements of Lightweight Directory 118 Access Protocol, along with their semantic meanings. Following the 119 description of protocol elements, it describes the way in which the 120 protocol is encoded and transferred. 122 This document is an integral part of the LDAP Technical Specification 123 [Roadmap]. 125 This document replaces RFC 2251. Appendix C holds a detailed log of 126 changes to RFC 2251. At publication time, this appendix will be 127 distilled to a summary of changes to RFC 2251. 129 2. Conventions 131 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 132 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document 133 are to be interpreted as described in [RFC2119]. 135 3. Protocol Model 137 The general model adopted by this protocol is one of clients 138 performing protocol operations against servers. In this model, a 139 client transmits a protocol request describing the operation to be 140 performed to a server. The server is then responsible for performing 141 the necessary operation(s) in the directory. Upon completion of the 142 operation(s), the server returns a response containing any results or 143 errors to the requesting client. 145 Note that although servers are required to return responses whenever 146 such responses are defined in the protocol, there is no requirement 147 for synchronous behavior on the part of either clients or servers. 148 Requests and responses for multiple operations may be exchanged 149 between a client and server in any order, provided the client 150 eventually receives a response for every request that requires one. 152 Note that the core protocol operations defined in this document can 153 be mapped to a strict subset of the X.500(1997) directory abstract 154 service. However there is not a one-to-one mapping between LDAP 155 protocol operations and DAP operations. Server implementations 156 acting as a gateway to X.500 directories may need to make multiple 157 DAP requests. 159 4. Elements of Protocol 160 Lightweight Directory Access Protocol Version 3 162 The LDAP protocol is described using Abstract Syntax Notation 1 163 (ASN.1) [X.680], and is transferred using a subset of ASN.1 Basic 164 Encoding Rules [X.690]. Section 5.1 specifies how the protocol is 165 encoded and transferred. 167 In order to support future extensions to this protocol, extensibility 168 is implied where it is allowed (per ASN.1). In addition, ellipses 169 (...) have been supplied in ASN.1 types that are explicitly 170 extensible as discussed in [LDAPIANA]. Because of the implied 171 extensibility, clients and servers MUST ignore trailing SEQUENCE 172 elements whose tags they do not recognize. 174 Changes to the LDAP protocol other than those described in [LDAPIANA] 175 require a different version number. A client indicates the version it 176 is using as part of the bind request, described in section 4.2. If a 177 client has not sent a bind, the server MUST assume the client is 178 using version 3 or later. 180 Clients may determine the protocol versions a server supports by 181 reading the supportedLDAPVersion attribute from the root DSE 182 [Models]. Servers which implement version 3 or later versions MUST 183 provide this attribute. 185 4.1. Common Elements 187 This section describes the LDAPMessage envelope PDU (Protocol Data 188 Unit) format, as well as data type definitions, which are used in the 189 protocol operations. 191 4.1.1. Message Envelope 193 For the purposes of protocol exchanges, all protocol operations are 194 encapsulated in a common envelope, the LDAPMessage, which is defined 195 as follows: 197 LDAPMessage ::= SEQUENCE { 198 messageID MessageID, 199 protocolOp CHOICE { 200 bindRequest BindRequest, 201 bindResponse BindResponse, 202 unbindRequest UnbindRequest, 203 searchRequest SearchRequest, 204 searchResEntry SearchResultEntry, 205 searchResDone SearchResultDone, 206 searchResRef SearchResultReference, 207 modifyRequest ModifyRequest, 208 modifyResponse ModifyResponse, 209 addRequest AddRequest, 210 addResponse AddResponse, 211 delRequest DelRequest, 212 delResponse DelResponse, 213 Lightweight Directory Access Protocol Version 3 215 modDNRequest ModifyDNRequest, 216 modDNResponse ModifyDNResponse, 217 compareRequest CompareRequest, 218 compareResponse CompareResponse, 219 abandonRequest AbandonRequest, 220 extendedReq ExtendedRequest, 221 extendedResp ExtendedResponse }, 222 controls [0] Controls OPTIONAL } 224 MessageID ::= INTEGER (0 .. maxInt) 226 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) -- 228 The function of the LDAPMessage is to provide an envelope containing 229 common fields required in all protocol exchanges. At this time the 230 only common fields are the message ID and the controls. 232 If the server receives a PDU from the client in which the LDAPMessage 233 SEQUENCE tag cannot be recognized, the messageID cannot be parsed, 234 the tag of the protocolOp is not recognized as a request, or the 235 encoding structures or lengths of data fields are found to be 236 incorrect, then the server MUST return the notice of disconnection 237 described in section 4.4.1, with resultCode protocolError, and 238 immediately close the connection. In other cases that the server 239 cannot parse the request received by the client, the server MUST 240 return an appropriate response to the request, with the resultCode 241 set to protocolError. 243 If the client receives a PDU from the server, which cannot be parsed, 244 the client may discard the PDU, or may abruptly close the connection. 246 The ASN.1 type Controls is defined in section 4.1.12. 248 4.1.1.1. Message ID 250 All LDAPMessage envelopes encapsulating responses contain the 251 messageID value of the corresponding request LDAPMessage. 253 The message ID of a request MUST have a non-zero value different from 254 the values of any other requests outstanding in the LDAP session of 255 which this message is a part. The zero value is reserved for the 256 unsolicited notification message. 258 A client MUST NOT send a second request with the same message ID as 259 an earlier request on the same connection if the client has not 260 received the final response from the earlier request. Otherwise the 261 behavior is undefined. Typical clients increment a counter for each 262 request. 264 A client MUST NOT reuse the message id of an abandonRequest or of the 265 abandoned operation until it has received a response from the server 266 for another request invoked subsequent to the abandonRequest, as the 267 abandonRequest itself does not have a response. 269 Lightweight Directory Access Protocol Version 3 271 4.1.2. String Types 273 The LDAPString is a notational convenience to indicate that, although 274 strings of LDAPString type encode as OCTET STRING types, the 275 [ISO10646] character set (a superset of Unicode) is used, encoded 276 following the UTF-8 algorithm [RFC2044]. Note that in the UTF-8 277 algorithm characters which are the same as ASCII (0x0000 through 278 0x007F) are represented as that same ASCII character in a single 279 byte. The other byte values are used to form a variable-length 280 encoding of an arbitrary character. 282 LDAPString ::= OCTET STRING -- UTF-8 encoded, 283 -- ISO 10646 characters 285 The LDAPOID is a notational convenience to indicate that the 286 permitted value of this string is a (UTF-8 encoded) dotted-decimal 287 representation of an OBJECT IDENTIFIER. Although an LDAPOID is 288 encoded as an OCTET STRING, values are limited to the definition of 289 numericoid given in Section 1.3 of [Models]. 291 LDAPOID ::= OCTET STRING -- Constrained to numericoid [Models] 293 For example, 295 1.3.6.1.4.1.1466.1.2.3 297 4.1.3. Distinguished Name and Relative Distinguished Name 299 An LDAPDN and a RelativeLDAPDN are respectively defined to be the 300 representation of a distinguished-name and a relative-distinguished- 301 name after encoding according to the specification in [LDAPDN]. 303 LDAPDN ::= LDAPString 304 -- Constrained to distinguishedName [LDAPDN] 306 RelativeLDAPDN ::= LDAPString 307 -- Constrained to name-component [LDAPDN] 309 4.1.5. Attribute Descriptions 311 The definition and encoding rules for attribute descriptions are 312 defined in Section 2.5 of [Models]. Briefly, an attribute description 313 is an attribute type and zero or more options. 315 AttributeDescription ::= LDAPString 316 -- Constrained to attributedescription 317 -- [Models] 319 Examples of valid AttributeDescription: 321 Lightweight Directory Access Protocol Version 3 323 cn 324 userCertificate;binary 326 Not all options can be associated with attributes held in the 327 directory. A server will treat an AttributeDescription with any 328 options it does not implement or support as unrecognized. The order 329 in which options appear in the list MUST NOT be used to impart any 330 semantic meaning. Servers MUST treat any two AttributeDescription 331 with the same AttributeType and options as equivalent. 333 AttributeDescriptionList describes a list of 0 or more attribute 334 descriptions. (A list of zero elements has special significance in 335 the Search request.) 337 AttributeDescriptionList ::= SEQUENCE OF 338 AttributeDescription 340 4.1.5.1 Transfer Options 342 Transfer options are not held in the directory, they only affect the 343 encoding used to transfer values. The absence of a transfer option 344 implies the native encoding. 346 Transfer options are mutually exclusive. Specifying a transfer option 347 when requesting attributes to be returned in a SearchRequest causes 348 that encoding to be used for that attribute and its subtypes. That 349 is, requesting name;binary requests the attribute name and its 350 subtypes (e.g., cn, sn, cn;lang_en, etc.) be returned using binary 351 transfer. 353 When specifying return attributes for a SearchRequest, clients SHOULD 354 avoid requesting the return of attributes related to each other in 355 the attribute subtyping hierarchy with different transfer encodings. 356 For example, requesting name;lang_en;binary and cn should be avoided 357 as it ambiguous as to how cn;lang_en is to be transferred. In such 358 cases, the server's behavior is undefined (the server can return the 359 values in either, neither, or both encodings). 361 One transfer option, "binary", is defined in this document. 362 Additional options may be defined in IETF standards-track and 363 experimental RFCs. Options beginning with "x-" are reserved for 364 private experiments. 366 4.1.5.2. Binary Transfer Option 368 If the "binary" option is present in an AttributeDescription, it 369 specifies that data within the AttributeValue(s) of the attribute be 370 transferred in protocol as BER encoded data according to the ASN.1 371 data type corresponding to the attribute's LDAP syntax. The LDAP 372 syntax is indicated by the "SYNTAX" part of the 373 AttributeTypeDescription. 375 Lightweight Directory Access Protocol Version 3 377 The presence or absence of the "binary" option only affects the 378 transfer of attribute values in protocol; servers store any 379 particular attribute in a server-defined format. If a client requests 380 that a server return an attribute in the "binary" format, but the 381 server cannot generate that format, the server MUST treat the 382 attribute type as unrecognized. Similarly, clients MUST NOT expect 383 servers to return an attribute with the "binary" option if the client 384 requested that attribute by name without the "binary" option. 386 This option is intended to be used with attributes whose syntax is a 387 complex ASN.1 data type, but may be associated with any attribute 388 whose ASN.1 type is known. 390 4.1.6. Attribute Value 392 A field of type AttributeValue is an OCTET STRING containing an 393 encoded value of an AttributeValue data type. The value is encoded 394 according to its native encoding definition, unless an option 395 specifying the transfer encoding is present in the companion 396 AttributeDescription to the AttributeValue (e.g. "binary"). 398 The native encoding definitions for different syntaxes and attribute 399 types may be found in other documents, and in particular [Syntaxes]. 401 At the time of this writing, there is only one AttributeDescription 402 option used to specify transfer encoding--"binary", described in 403 section 4.1.5.2. 405 AttributeValue ::= OCTET STRING 407 Note that there is no defined limit on the size of this encoding; 408 thus protocol values may include multi-megabyte attributes (e.g. 409 photographs). 411 Attributes may be defined which have arbitrary and non-printable 412 syntax. Implementations MUST NOT display nor attempt to decode as 413 ASN.1, a value if its syntax is not known. The implementation may 414 attempt to discover the subschema of the source entry, and retrieve 415 the values of attributeTypes from it. 417 Clients MUST NOT send attribute values in a request that are not 418 valid according to the syntax defined for the attributes. 420 4.1.7. Attribute Value Assertion 422 The AttributeValueAssertion type definition is similar to the one in 423 the X.500 directory standards. It contains an attribute description 424 and a matching rule assertion value suitable for that type. 426 AttributeValueAssertion ::= SEQUENCE { 427 Lightweight Directory Access Protocol Version 3 429 attributeDesc AttributeDescription, 430 assertionValue AssertionValue } 432 AssertionValue ::= OCTET STRING 434 If a transfer option is present in attributeDesc, the assertionValue 435 is encoded as specified by the option. For example, if the "binary" 436 option is present in the attributeDesc, the AssertionValue is BER 437 encoded. 439 For all the string-valued user attributes described in [Syntaxes], 440 the assertion value syntax is the same as the value syntax. Clients 441 may use attribute values as assertion values in compare requests and 442 search filters. 444 Note however that the assertion syntax may be different from the 445 value syntax for other attributes or for non-equality matching rules. 446 These may have an assertion syntax which contains only part of the 447 value. See section 20.2.1.8 of [X.501] for examples. 449 4.1.8. Attribute 451 An attribute consists of an attribute description and one or more 452 values of that attribute description. (Though attributes MUST have at 453 least one value when stored, due to access control restrictions the 454 set may be empty when transferred from the server to the client. This 455 is described in section 4.5.2, concerning the PartialAttributeList 456 type.) 458 Attribute ::= SEQUENCE { 459 type AttributeDescription, 460 vals SET OF AttributeValue } 462 Each attribute value is distinct in the set (no duplicates). The set 463 of attribute values is unordered. Implementations MUST NOT reply upon 464 any apparent ordering being repeatable. 466 4.1.9. Matching Rule Identifier 468 A matching rule is a means of expressing how a server should compare 469 an AssertionValue received in a search filter with an abstract data 470 value. The matching rule defines the syntax of the assertion value 471 and the process to be performed in the server. 473 An X.501 (1993) Matching Rule is identified in the LDAP protocol by 474 the printable representation of its OBJECT IDENTIFIER, either as one 475 of the strings given in [Syntaxes], or as decimal digits with 476 components separated by periods, e.g. "caseIgnoreIA5Match" or 477 "1.3.6.1.4.1.453.33.33". 479 MatchingRuleId ::= LDAPString 480 Lightweight Directory Access Protocol Version 3 482 Servers which support matching rules for use in the extensibleMatch 483 search filter MUST list the matching rules they implement in 484 subschema entries, using the matchingRules attributes. The server 485 SHOULD also list there, using the matchingRuleUse attribute, the 486 attribute types with which each matching rule can be used. More 487 information is given in section 4.5 of [Syntaxes]. 489 4.1.10. Result Message 491 The LDAPResult is the construct used in this protocol to return 492 success or failure indications from servers to clients. To various 493 requests, servers will return responses of LDAPResult or responses 494 containing the components of LDAPResponse to indicate the final 495 status of a protocol operation request. 497 LDAPResult ::= SEQUENCE { 498 resultCode ENUMERATED { 499 success (0), 500 operationsError (1), 501 protocolError (2), 502 timeLimitExceeded (3), 503 sizeLimitExceeded (4), 504 compareFalse (5), 505 compareTrue (6), 506 authMethodNotSupported (7), 507 strongAuthRequired (8), 508 -- 9 reserved -- 509 referral (10), 510 adminLimitExceeded (11), 511 unavailableCriticalExtension (12), 512 confidentialityRequired (13), 513 saslBindInProgress (14), 514 noSuchAttribute (16), 515 undefinedAttributeType (17), 516 inappropriateMatching (18), 517 constraintViolation (19), 518 attributeOrValueExists (20), 519 invalidAttributeSyntax (21), 520 -- 22-31 unused -- 521 noSuchObject (32), 522 aliasProblem (33), 523 invalidDNSyntax (34), 524 -- 35 reserved for undefined isLeaf -- 525 aliasDereferencingProblem (36), 526 -- 37-47 unused -- 527 inappropriateAuthentication (48), 528 invalidCredentials (49), 529 insufficientAccessRights (50), 530 busy (51), 531 unavailable (52), 532 unwillingToPerform (53), 533 loopDetect (54), 534 -- 55-63 unused -- 535 Lightweight Directory Access Protocol Version 3 537 namingViolation (64), 538 objectClassViolation (65), 539 notAllowedOnNonLeaf (66), 540 notAllowedOnRDN (67), 541 entryAlreadyExists (68), 542 objectClassModsProhibited (69), 543 -- 70 reserved for CLDAP -- 544 affectsMultipleDSAs (71), 545 -- 72-79 unused -- 546 other (80), 547 ... }, 548 -- 81-90 reserved for APIs -- 549 matchedDN LDAPDN, 550 errorMessage LDAPString, 551 referral [3] Referral OPTIONAL } 553 The result codes enumeration is extensible as defined in Section 3.5 554 of [LDAPIANA]. The meanings of the result codes are given in Appendix 555 A. 557 The errorMessage field of this construct may, at the server's option, 558 be used to return a string containing a textual, human-readable 559 (terminal control and page formatting characters should be avoided) 560 error diagnostic. As this error diagnostic is not standardized, 561 implementations MUST NOT rely on the values returned. If the server 562 chooses not to return a textual diagnostic, the errorMessage field of 563 the LDAPResult type MUST contain a zero length string. 565 For result codes of noSuchObject, aliasProblem, invalidDNSyntax and 566 aliasDereferencingProblem, the matchedDN field is set to the name of 567 the lowest entry (object or alias) in the directory that was matched. 568 If no aliases were dereferenced while attempting to locate the entry, 569 this will be a truncated form of the name provided, or if aliases 570 were dereferenced, of the resulting name, as defined in section 12.5 571 of [X.511]. The matchedDN field contains a zero length string with 572 all other result codes. 574 4.1.11. Referral 576 The referral result code indicates that the contacted server does not 577 hold the target entry of the request. The referral field is present 578 in an LDAPResult if the LDAPResult.resultCode field value is 579 referral, and absent with all other result codes. It contains one or 580 more references to one or more servers or services that may be 581 accessed via LDAP or other protocols. Referrals can be returned in 582 response to any operation request (except unbind and abandon which do 583 not have responses). At least one URL MUST be present in the 584 Referral. 586 The referral is not returned for a singleLevel or wholeSubtree search 587 in which the search scope spans multiple naming contexts, and several 588 different servers would need to be contacted to complete the 589 Lightweight Directory Access Protocol Version 3 591 operation. Instead, continuation references, described in section 592 4.5.3, are returned. 594 Referral ::= SEQUENCE OF LDAPURL -- one or more 596 LDAPURL ::= LDAPString -- limited to characters permitted in 597 -- URLs 599 If the client wishes to progress the operation, it MUST follow the 600 referral by contacting one of the servers. If multiple URLs are 601 present, the client assumes that any URL may be used to progress the 602 operation. 604 URLs for servers implementing the LDAP protocol are written according 605 to [LDAPDN]. If an alias was dereferenced, the part of the URL 606 MUST be present, with the new target object name. If the part is 607 present, the client MUST use this name in its next request to 608 progress the operation, and if it is not present the client will use 609 the same name as in the original request. Some servers (e.g. 610 participating in distributed indexing) may provide a different filter 611 in a referral for a search operation. If the filter part of the URL 612 is present in an LDAPURL, the client MUST use this filter in its next 613 request to progress this search, and if it is not present the client 614 MUST use the same filter as it used for that search. Other aspects of 615 the new request may be the same or different as the request which 616 generated the referral. 618 Note that UTF-8 characters appearing in a DN or search filter may not 619 be legal for URLs (e.g. spaces) and MUST be escaped using the % 620 method in [RFC2396]. 622 Other kinds of URLs may be returned, so long as the operation could 623 be performed using that protocol. 625 4.1.12. Controls 627 A control is a way to specify extension information. Controls which 628 are sent as part of a request apply only to that request and are not 629 saved. 631 Controls ::= SEQUENCE OF Control 633 Control ::= SEQUENCE { 634 controlType LDAPOID, 635 criticality BOOLEAN DEFAULT FALSE, 636 controlValue OCTET STRING OPTIONAL } 638 The controlType field MUST be a UTF-8 encoded dotted-decimal 639 representation of an OBJECT IDENTIFIER which uniquely identifies the 640 control. This prevents conflicts between control names. 642 The criticality field is either TRUE or FALSE and is only used when a 643 control accompanies one of the following requests: bindRequest, 644 Lightweight Directory Access Protocol Version 3 646 searchRequest, modifyRequest, addRequest, delRequest, modDNRequest, 647 compareRequest, or extendedReq. The use of the criticality field for 648 a control that is part of any other operation is ignored and treated 649 as FALSE. 651 If the server recognizes the control type and it is appropriate for 652 the operation, the server will make use of the control when 653 performing the operation. 655 If the server does not recognize the control type or it is not 656 appropriate for the operation, and the criticality field is TRUE, the 657 server MUST NOT perform the operation, and MUST instead return the 658 resultCode unavailableCriticalExtension. 660 If the control is unrecognized or inappropriate but the criticality 661 field is FALSE, the server MUST ignore the control. 663 The controlValue contains any information associated with the 664 control, and its format is defined for the control. Implementations 665 MUST be prepared to handle arbitrary contents of the controlValue 666 octet string, including zero bytes. It is absent only if there is no 667 value information which is associated with a control of its type. 669 This document does not define any controls. Controls may be defined 670 in other documents. The definition of a control consists of: 672 - the OBJECT IDENTIFIER assigned to the control, 674 - whether the control is always noncritical, always critical, or 675 critical at the client's option, 677 - the format of the controlValue contents of the control. 679 Servers list the controlType of all recognized controls in the 680 supportedControl attribute in the root DSE. 682 4.2. Bind Operation 684 The function of the Bind Operation is to allow authentication 685 information to be exchanged between the client and server. Prior to 686 the BindRequest, the implied identity is anonymous. Refer to 687 [AuthMeth] for the authentication-related semantics of this 688 operation. 690 The Bind Request is defined as follows: 692 BindRequest ::= [APPLICATION 0] SEQUENCE { 693 version INTEGER (1 .. 127), 694 name LDAPDN, 695 authentication AuthenticationChoice } 697 AuthenticationChoice ::= CHOICE { 698 simple [0] OCTET STRING, 699 Lightweight Directory Access Protocol Version 3 701 -- 1 and 2 reserved 702 sasl [3] SaslCredentials, 703 ... } 705 SaslCredentials ::= SEQUENCE { 706 mechanism LDAPString, 707 credentials OCTET STRING OPTIONAL } 709 Parameters of the Bind Request are: 711 - version: A version number indicating the version of the protocol 712 to be used in this protocol session. This document describes 713 version 3 of the LDAP protocol. Note that there is no version 714 negotiation, and the client just sets this parameter to the 715 version it desires. If the server does not support the specified 716 version, it responds with protocolError in the resultCode field of 717 the BindResponse. 719 - name: The name of the directory object that the client wishes to 720 bind as. This field may take on a null value (a zero length 721 string) for the purposes of anonymous binds, when authentication 722 has been performed at a lower layer, or when using SASL 723 credentials with a mechanism that includes the name in the 724 credentials. Server behavior is undefined when the name is a null 725 value, simple authentication is used, and a password is specified. 726 Note that the server SHOULD NOT perform any alias dereferencing in 727 determining the object to bind as. 729 - authentication: information used to authenticate the name, if any, 730 provided in the Bind Request. This type is extensible as defined 731 in Section 3.6 of [LDAPIANA]. Servers that do not support a choice 732 supplied by a client will return authMethodNotSupported in the 733 result code of the BindResponse. 735 Upon receipt of a Bind Request, a protocol server will authenticate 736 the requesting client, if necessary. The server will then return a 737 Bind Response to the client indicating the status of the 738 authentication. 740 Authorization is the use of this authentication information when 741 performing operations. Authorization MAY be affected by factors 742 outside of the LDAP Bind request, such as lower layer security 743 services. 745 4.2.1. Sequencing of the Bind Request 747 For some SASL authentication mechanisms, it may be necessary for the 748 client to invoke the BindRequest multiple times. If at any stage the 749 client wishes to abort the bind process it MAY unbind and then drop 750 the underlying connection. Clients MUST NOT invoke operations between 751 two Bind requests made as part of a multi-stage bind. 753 Lightweight Directory Access Protocol Version 3 755 A client may abort a SASL bind negotiation by sending a BindRequest 756 with a different value in the mechanism field of SaslCredentials, or 757 an AuthenticationChoice other than sasl. 759 If the client sends a BindRequest with the sasl mechanism field as an 760 empty string, the server MUST return a BindResponse with 761 authMethodNotSupported as the resultCode. This will allow clients to 762 abort a negotiation if it wishes to try again with the same SASL 763 mechanism. 765 If the client did not bind before sending a request and receives an 766 operationsError, it may then send a Bind Request. If this also fails 767 or the client chooses not to bind on the existing connection, it will 768 close the connection, reopen it and begin again by first sending a 769 PDU with a Bind Request. This will aid in interoperating with servers 770 implementing other versions of LDAP. 772 4.2.3. Bind Response 774 The Bind Response is defined as follows. 776 BindResponse ::= [APPLICATION 1] SEQUENCE { 777 COMPONENTS OF LDAPResult, 778 serverSaslCreds [7] OCTET STRING OPTIONAL } 780 BindResponse consists simply of an indication from the server of the 781 status of the client's request for authentication. 783 If the bind was successful, the resultCode will be success, otherwise 784 it will be one of: 786 - operationsError: server encountered an internal error. 788 - protocolError: unrecognized version number or incorrect PDU 789 structure. 791 - authMethodNotSupported: unrecognized SASL mechanism name. 793 - strongAuthRequired: the server requires authentication be 794 performed with a SASL mechanism. 796 - referral: this server cannot accept this bind and the client 797 should try another. 799 - saslBindInProgress: the server requires the client to send a new 800 bind request, with the same sasl mechanism, to continue the 801 authentication process. 803 - inappropriateAuthentication: the server requires the client which 804 had attempted to bind anonymously or without supplying credentials 805 to provide some form of credentials. 807 Lightweight Directory Access Protocol Version 3 809 - invalidCredentials: the wrong password was supplied or the SASL 810 credentials could not be processed. 812 - unavailable: the server is shutting down. 814 If the server does not support the client's requested protocol 815 version, it MUST set the resultCode to protocolError. 817 If the client receives a BindResponse response where the resultCode 818 was protocolError, it MUST close the connection as the server will be 819 unwilling to accept further operations. (This is for compatibility 820 with earlier versions of LDAP, in which the bind was always the first 821 operation, and there was no negotiation.) 823 The serverSaslCreds are used as part of a SASL-defined bind mechanism 824 to allow the client to authenticate the server to which it is 825 communicating, or to perform "challenge-response" authentication. If 826 the client bound with the password choice, or the SASL mechanism does 827 not require the server to return information to the client, then this 828 field is not to be included in the result. 830 4.3. Unbind Operation 832 The function of the Unbind Operation is to terminate a protocol 833 session. The Unbind Operation is defined as follows: 835 UnbindRequest ::= [APPLICATION 2] NULL 837 The Unbind Operation has no response defined. Upon transmission of an 838 UnbindRequest, a protocol client may assume that the protocol session 839 is terminated. Upon receipt of an UnbindRequest, a protocol server 840 may assume that the requesting client has terminated the session and 841 that all outstanding requests may be discarded, and may close the 842 connection. 844 4.4. Unsolicited Notification 846 An unsolicited notification is an LDAPMessage sent from the server to 847 the client which is not in response to any LDAPMessage received by 848 the server. It is used to signal an extraordinary condition in the 849 server or in the connection between the client and the server. The 850 notification is of an advisory nature, and the server will not expect 851 any response to be returned from the client. 853 The unsolicited notification is structured as an LDAPMessage in which 854 the messageID is 0 and protocolOp is of the extendedResp form. The 855 responseName field of the ExtendedResponse is present. The LDAPOID 856 value MUST be unique for this notification, and not be used in any 857 other situation. 859 One unsolicited notification (Notice of Disconnection) is defined in 860 this document. 862 Lightweight Directory Access Protocol Version 3 864 4.4.1. Notice of Disconnection 866 This notification may be used by the server to advise the client that 867 the server is about to close the connection due to an error 868 condition. Note that this notification is NOT a response to an unbind 869 requested by the client: the server MUST follow the procedures of 870 section 4.3. This notification is intended to assist clients in 871 distinguishing between an error condition and a transient network 872 failure. As with a connection close due to network failure, the 873 client MUST NOT assume that any outstanding requests which modified 874 the directory have succeeded or failed. 876 The responseName is 1.3.6.1.4.1.1466.20036, the response field is 877 absent, and the resultCode is used to indicate the reason for the 878 disconnection. 880 The following resultCode values are to be used in this notification: 882 - protocolError: The server has received data from the client in 883 which the LDAPMessage structure could not be parsed. 885 - strongAuthRequired: The server has detected that an established 886 underlying security association protecting communication between 887 the client and server has unexpectedly failed or been compromised. 889 - unavailable: This server will stop accepting new connections and 890 operations on all existing connections, and be unavailable for an 891 extended period of time. The client may make use of an alternative 892 server. 894 After sending this notice, the server MUST close the connection. 895 After receiving this notice, the client MUST NOT transmit any further 896 on the connection, and may abruptly close the connection. 898 4.5. Search Operation 900 The Search Operation allows a client to request that a search be 901 performed on its behalf by a server. This can be used to read 902 attributes from a single entry, from entries immediately below a 903 particular entry, or a whole subtree of entries. 905 4.5.1. Search Request 907 The Search Request is defined as follows: 909 SearchRequest ::= [APPLICATION 3] SEQUENCE { 910 baseObject LDAPDN, 911 scope ENUMERATED { 912 baseObject (0), 913 singleLevel (1), 914 Lightweight Directory Access Protocol Version 3 916 wholeSubtree (2) }, 917 derefAliases ENUMERATED { 918 neverDerefAliases (0), 919 derefInSearching (1), 920 derefFindingBaseObj (2), 921 derefAlways (3) }, 922 sizeLimit INTEGER (0 .. maxInt), 923 timeLimit INTEGER (0 .. maxInt), 924 typesOnly BOOLEAN, 925 filter Filter, 926 attributes AttributeDescriptionList } 928 Filter ::= CHOICE { 929 and [0] SET SIZE (1..MAX) OF Filter, 930 or [1] SET SIZE (1..MAX) OF Filter, 931 not [2] Filter, 932 equalityMatch [3] AttributeValueAssertion, 933 substrings [4] SubstringFilter, 934 greaterOrEqual [5] AttributeValueAssertion, 935 lessOrEqual [6] AttributeValueAssertion, 936 present [7] AttributeDescription, 937 approxMatch [8] AttributeValueAssertion, 938 extensibleMatch [9] MatchingRuleAssertion } 940 SubstringFilter ::= SEQUENCE { 941 type AttributeDescription, 942 -- at least one must be present, 943 -- initial and final can occur at most once 944 substrings SEQUENCE OF CHOICE { 945 initial [0] AssertionValue, 946 any [1] AssertionValue, 947 final [2] AssertionValue } } 949 MatchingRuleAssertion ::= SEQUENCE { 950 matchingRule [1] MatchingRuleId OPTIONAL, 951 type [2] AttributeDescription OPTIONAL, 952 matchValue [3] AssertionValue, 953 dnAttributes [4] BOOLEAN DEFAULT FALSE } 955 Parameters of the Search Request are: 957 - baseObject: An LDAPDN that is the base object entry relative to 958 which the search is to be performed. 960 - scope: An indicator of the scope of the search to be performed. 961 The semantics of the possible values of this field are identical 962 to the semantics of the scope field in the X.511 Search Operation. 964 - derefAliases: An indicator as to how alias objects (as defined in 965 X.501) are to be handled in searching. The semantics of the 966 possible values of this field are: 968 neverDerefAliases: do not dereference aliases in searching 969 or in locating the base object of the search; 970 Lightweight Directory Access Protocol Version 3 972 derefInSearching: dereference aliases in subordinates of 973 the base object in searching, but not in locating the base 974 object of the search; 976 derefFindingBaseObj: dereference aliases in locating the 977 base object of the search, but not when searching 978 subordinates of the base object; 980 derefAlways: dereference aliases both in searching and in 981 locating the base object of the search. 983 - sizeLimit: A size limit that restricts the maximum number of 984 entries to be returned as a result of the search. A value of 0 in 985 this field indicates that no client-requested size limit 986 restrictions are in effect for the search. Servers may enforce a 987 maximum number of entries to return. 989 - timeLimit: A time limit that restricts the maximum time (in 990 seconds) allowed for a search. A value of 0 in this field 991 indicates that no client-requested time limit restrictions are in 992 effect for the search. 994 - typesOnly: An indicator as to whether search results will contain 995 both attribute types and values, or just attribute types. Setting 996 this field to TRUE causes only attribute types (no values) to be 997 returned. Setting this field to FALSE causes both attribute types 998 and values to be returned. 1000 - filter: A filter that defines the conditions that must be 1001 fulfilled in order for the search to match a given entry. 1003 The 'and', 'or' and 'not' choices can be used to form combinations 1004 of filters. At least one filter element MUST be present in an 1005 'and' or 'or' choice. The others match against individual 1006 attribute values of entries in the scope of the search. 1007 (Implementor's note: the 'not' filter is an example of a tagged 1008 choice in an implicitly-tagged module. In BER this is treated as 1009 if the tag was explicit.) 1011 A server MUST evaluate filters according to the three-valued logic 1012 of X.511 (1993) section 7.8.1. In summary, a filter is evaluated 1013 to either "TRUE", "FALSE" or "Undefined". If the filter evaluates 1014 to TRUE for a particular entry, then the attributes of that entry 1015 are returned as part of the search result (subject to any 1016 applicable access control restrictions). If the filter evaluates 1017 to FALSE or Undefined, then the entry is ignored for the search. 1019 A filter of the "and" choice is TRUE if all the filters in the SET 1020 OF evaluate to TRUE, FALSE if at least one filter is FALSE, and 1021 otherwise Undefined. A filter of the "or" choice is FALSE if all 1022 of the filters in the SET OF evaluate to FALSE, TRUE if at least 1023 one filter is TRUE, and Undefined otherwise. A filter of the "not" 1024 choice is TRUE if the filter being negated is FALSE, FALSE if it 1025 Lightweight Directory Access Protocol Version 3 1027 is TRUE, and Undefined if it is Undefined. 1029 The present match evaluates to TRUE where there is an attribute or 1030 subtype of the specified attribute description present in an 1031 entry, and FALSE otherwise (including a presence test with an 1032 unrecognized attribute description.) 1034 The extensibleMatch is new in this version of LDAP. If the 1035 matchingRule field is absent, the type field MUST be present, and 1036 the equality match is performed for that type. If the type field 1037 is absent and matchingRule is present, the matchValue is compared 1038 against all attributes in an entry which support that 1039 matchingRule, and the matchingRule determines the syntax for the 1040 assertion value (the filter item evaluates to TRUE if it matches 1041 with at least one attribute in the entry, FALSE if it does not 1042 match any attribute in the entry, and Undefined if the 1043 matchingRule is not recognized or the assertionValue cannot be 1044 parsed.) If the type field is present and matchingRule is present, 1045 the matchingRule MUST be one permitted for use with that type, 1046 otherwise the filter item is undefined. If the dnAttributes field 1047 is set to TRUE, the match is applied against all the attributes in 1048 an entry's distinguished name as well, and also evaluates to TRUE 1049 if there is at least one attribute in the distinguished name for 1050 which the filter item evaluates to TRUE. (Editors note: The 1051 dnAttributes field is present so that there does not need to be 1052 multiple versions of generic matching rules such as for word 1053 matching, one to apply to entries and another to apply to entries 1054 and dn attributes as well). 1056 A filter item evaluates to Undefined when the server would not be 1057 able to determine whether the assertion value matches an entry. If 1058 an attribute description in an equalityMatch, substrings, 1059 greaterOrEqual, lessOrEqual, approxMatch or extensibleMatch filter 1060 is not recognized by the server, a matching rule id in the 1061 extensibleMatch is not recognized by the server, the assertion 1062 value cannot be parsed, or the type of filtering requested is not 1063 implemented, then the filter is Undefined. Thus for example if a 1064 server did not recognize the attribute type shoeSize, a filter of 1065 (shoeSize=*) would evaluate to FALSE, and the filters 1066 (shoeSize=12), (shoeSize>=12) and (shoeSize<=12) would evaluate to 1067 Undefined. 1069 Servers MUST NOT return errors if attribute descriptions or 1070 matching rule ids are not recognized, or assertion values cannot 1071 be parsed. More details of filter processing are given in section 1072 7.8 of [X.511]. 1074 - attributes: A list of the attributes to be returned from each 1075 entry which matches the search filter. There are two special 1076 values which may be used: an empty list with no attributes, and 1077 the attribute description string "*". Both of these signify that 1078 all user attributes are to be returned. (The "*" allows the client 1079 to request all user attributes in addition to any specified 1080 operational attributes). 1082 Lightweight Directory Access Protocol Version 3 1084 Attributes MUST be named at most once in the list, and are 1085 returned at most once in an entry. If there are attribute 1086 descriptions in the list which are not recognized, they are 1087 ignored by the server. 1089 If the client does not want any attributes returned, it can 1090 specify a list containing only the attribute with OID "1.1". This 1091 OID was chosen arbitrarily and does not correspond to any 1092 attribute in use. 1094 Client implementors should note that even if all user attributes 1095 are requested, some attributes of the entry may not be included in 1096 search results due to access controls or other restrictions. 1097 Furthermore, servers will not return operational attributes, such 1098 as objectClasses or attributeTypes, unless they are listed by 1099 name, since there may be extremely large number of values for 1100 certain operational attributes. (A list of operational attributes 1101 for use in LDAP is given in [Syntaxes].) 1103 Note that an X.500 "list"-like operation can be emulated by the 1104 client requesting a one-level LDAP search operation with a filter 1105 checking for the presence of the objectClass attribute, and that an 1106 X.500 "read"-like operation can be emulated by a base object LDAP 1107 search operation with the same filter. A server which provides a 1108 gateway to X.500 is not required to use the Read or List operations, 1109 although it may choose to do so, and if it does, it must provide the 1110 same semantics as the X.500 search operation. 1112 4.5.2. Search Result 1114 The results of the search attempted by the server upon receipt of a 1115 Search Request are returned in Search Responses, which are LDAP 1116 messages containing either SearchResultEntry, SearchResultReference, 1117 or SearchResultDone data types. 1119 SearchResultEntry ::= [APPLICATION 4] SEQUENCE { 1120 objectName LDAPDN, 1121 attributes PartialAttributeList } 1123 PartialAttributeList ::= SEQUENCE OF SEQUENCE { 1124 type AttributeDescription, 1125 vals SET OF AttributeValue } 1126 -- implementors should note that the PartialAttributeList may 1127 -- have zero elements (if none of the attributes of that entry 1128 -- were requested, or could be returned), and that the vals set 1129 -- may also have zero elements (if types only was requested, or 1130 -- all values were excluded from the result.) 1132 SearchResultReference ::= [APPLICATION 19] SEQUENCE OF LDAPURL 1133 -- at least one LDAPURL element must be present 1135 SearchResultDone ::= [APPLICATION 5] LDAPResult 1136 Lightweight Directory Access Protocol Version 3 1138 Upon receipt of a Search Request, a server will perform the necessary 1139 search of the DIT. 1141 If the LDAP session is operating over a connection-oriented transport 1142 such as TCP, the server will return to the client a sequence of 1143 responses in separate LDAP messages. There may be zero or more 1144 responses containing SearchResultEntry, one for each entry found 1145 during the search. There may also be zero or more responses 1146 containing SearchResultReference, one for each area not explored by 1147 this server during the search. The SearchResultEntry and 1148 SearchResultReference PDUs may come in any order. Following all the 1149 SearchResultReference responses and all SearchResultEntry responses 1150 to be returned by the server, the server will return a response 1151 containing the SearchResultDone, which contains an indication of 1152 success, or detailing any errors that have occurred. 1154 Each entry returned in a SearchResultEntry will contain all 1155 attributes, complete with associated values if necessary, as 1156 specified in the attributes field of the Search Request. Return of 1157 attributes is subject to access control and other administrative 1158 policy. Some attributes may be returned in binary format (indicated 1159 by the AttributeDescription in the response having the "binary" 1160 option present). 1162 Some attributes may be constructed by the server and appear in a 1163 SearchResultEntry attribute list, although they are not stored 1164 attributes of an entry. Clients MUST NOT assume that all attributes 1165 can be modified, even if permitted by access control. 1167 4.5.3. Continuation References in the Search Result 1169 If the server was able to locate the entry referred to by the 1170 baseObject but was unable to search all the entries in the scope at 1171 and under the baseObject, the server may return one or more 1172 SearchResultReference entries, each containing a reference to another 1173 set of servers for continuing the operation. A server MUST NOT return 1174 any SearchResultReference if it has not located the baseObject and 1175 thus has not searched any entries; in this case it would return a 1176 SearchResultDone containing a referral resultCode. 1178 In the absence of indexing information provided to a server from 1179 servers holding subordinate naming contexts, SearchResultReference 1180 responses are not affected by search filters and are always returned 1181 when in scope. 1183 The SearchResultReference is of the same data type as the Referral. 1184 URLs for servers implementing the LDAP protocol are written according 1185 to [LDAPDN]. The part MUST be present in the URL, with the new 1186 target object name. The client MUST use this name in its next 1187 request. Some servers (e.g. part of a distributed index exchange 1188 system) may provide a different filter in the URLs of the 1189 SearchResultReference. If the filter part of the URL is present in an 1190 Lightweight Directory Access Protocol Version 3 1192 LDAP URL, the client MUST use the new filter in its next request to 1193 progress the search, and if the filter part is absent the client will 1194 use again the same filter. If the originating search scope was 1195 singleLevel, the scope part of the URL will be baseObject. Other 1196 aspects of the new search request may be the same or different as the 1197 search which generated the continuation references. 1198 Other kinds of URLs may be returned so long as the operation could be 1199 performed using that protocol. 1201 The name of an unexplored subtree in a SearchResultReference need not 1202 be subordinate to the base object. 1204 In order to complete the search, the client MUST issue a new search 1205 operation for each SearchResultReference that is returned. Note that 1206 the abandon operation described in section 4.11 applies only to a 1207 particular operation sent on a connection between a client and 1208 server, and if the client has multiple outstanding search operations, 1209 it MUST abandon each operation individually. 1211 4.5.3.1. Example 1213 For example, suppose the contacted server (hosta) holds the entry 1214 "O=MNN,C=WW" and the entry "CN=Manager,O=MNN,C=WW". It knows that 1215 either LDAP-capable servers (hostb) or (hostc) hold 1216 "OU=People,O=MNN,C=WW" (one is the master and the other server a 1217 shadow), and that LDAP-capable server (hostd) holds the subtree 1218 "OU=Roles,O=MNN,C=WW". If a subtree search of "O=MNN,C=WW" is 1219 requested to the contacted server, it may return the following: 1221 SearchResultEntry for O=MNN,C=WW 1222 SearchResultEntry for CN=Manager,O=MNN,C=WW 1223 SearchResultReference { 1224 ldap://hostb/OU=People,O=MNN,C=WW 1225 ldap://hostc/OU=People,O=MNN,C=WW 1226 } 1227 SearchResultReference { 1228 ldap://hostd/OU=Roles,O=MNN,C=WW 1229 } 1230 SearchResultDone (success) 1232 Client implementors should note that when following a 1233 SearchResultReference, additional SearchResultReference may be 1234 generated. Continuing the example, if the client contacted the server 1235 (hostb) and issued the search for the subtree "OU=People,O=MNN,C=WW", 1236 the server might respond as follows: 1238 SearchResultEntry for OU=People,O=MNN,C=WW 1239 SearchResultReference { 1240 ldap://hoste/OU=Managers,OU=People,O=MNN,C=WW 1241 } 1242 SearchResultReference { 1243 ldap://hostf/OU=Consultants,OU=People,O=MNN,C=WW 1244 } 1245 Lightweight Directory Access Protocol Version 3 1247 SearchResultDone (success) 1249 If the contacted server does not hold the base object for the search, 1250 then it will return a referral to the client. For example, if the 1251 client requests a subtree search of "O=XYZ,C=US" to hosta, the server 1252 may return only a SearchResultDone containing a referral. 1254 SearchResultDone (referral) { 1255 ldap://hostg/ 1256 } 1258 4.6. Modify Operation 1260 The Modify Operation allows a client to request that a modification 1261 of an entry be performed on its behalf by a server. The Modify 1262 Request is defined as follows: 1264 ModifyRequest ::= [APPLICATION 6] SEQUENCE { 1265 object LDAPDN, 1266 modification SEQUENCE OF SEQUENCE { 1267 operation ENUMERATED { 1268 add (0), 1269 delete (1), 1270 replace (2) }, 1271 modification AttributeTypeAndValues } } 1273 AttributeTypeAndValues ::= SEQUENCE { 1274 type AttributeDescription, 1275 vals SET OF AttributeValue } 1277 Parameters of the Modify Request are: 1279 - object: The object to be modified. The value of this field 1280 contains the DN of the entry to be modified. The server will not 1281 perform any alias dereferencing in determining the object to be 1282 modified. 1284 - modification: A list of modifications to be performed on the 1285 entry. The entire list of entry modifications MUST be performed in 1286 the order they are listed, as a single atomic operation. While 1287 individual modifications may violate the directory schema, the 1288 resulting entry after the entire list of modifications is 1289 performed MUST conform to the requirements of the directory 1290 schema. The values that may be taken on by the 'operation' field 1291 in each modification construct have the following semantics 1292 respectively: 1294 add: add values listed to the given attribute, creating the 1295 attribute if necessary; 1297 delete: delete values listed from the given attribute, 1298 removing the entire attribute if no values are listed, or 1299 Lightweight Directory Access Protocol Version 3 1301 if all current values of the attribute are listed for 1302 deletion; 1304 replace: replace all existing values of the given attribute 1305 with the new values listed, creating the attribute if it 1306 did not already exist. A replace with no value will delete 1307 the entire attribute if it exists, and is ignored if the 1308 attribute does not exist. 1310 The result of the modify attempted by the server upon receipt of a 1311 Modify Request is returned in a Modify Response, defined as follows: 1313 ModifyResponse ::= [APPLICATION 7] LDAPResult 1315 Upon receipt of a Modify Request, a server will perform the necessary 1316 modifications to the DIT. 1318 The server will return to the client a single Modify Response 1319 indicating either the successful completion of the DIT modification, 1320 or the reason that the modification failed. Note that due to the 1321 requirement for atomicity in applying the list of modifications in 1322 the Modify Request, the client may expect that no modifications of 1323 the DIT have been performed if the Modify Response received indicates 1324 any sort of error, and that all requested modifications have been 1325 performed if the Modify Response indicates successful completion of 1326 the Modify Operation. If the connection fails, whether the 1327 modification occurred or not is indeterminate. 1329 The Modify Operation cannot be used to remove from an entry any of 1330 its distinguished values, those values which form the entry's 1331 relative distinguished name. An attempt to do so will result in the 1332 server returning the error notAllowedOnRDN. The Modify DN Operation 1333 described in section 4.9 is used to rename an entry. 1335 If an equality match filter has not been defined for an attribute 1336 type, clients MUST NOT attempt to add or delete individual values of 1337 that attribute from an entry using the "add" or "delete" form of a 1338 modification, and MUST instead use the "replace" form. 1340 Note that due to the simplifications made in LDAP, there is not a 1341 direct mapping of the modifications in an LDAP ModifyRequest onto the 1342 EntryModifications of a DAP ModifyEntry operation, and different 1343 implementations of LDAP-DAP gateways may use different means of 1344 representing the change. If successful, the final effect of the 1345 operations on the entry MUST be identical. 1347 4.7. Add Operation 1349 The Add Operation allows a client to request the addition of an entry 1350 into the directory. The Add Request is defined as follows: 1352 AddRequest ::= [APPLICATION 8] SEQUENCE { 1353 entry LDAPDN, 1354 Lightweight Directory Access Protocol Version 3 1356 attributes AttributeList } 1358 AttributeList ::= SEQUENCE OF SEQUENCE { 1359 type AttributeDescription, 1360 vals SET OF AttributeValue } 1362 Parameters of the Add Request are: 1364 - entry: the Distinguished Name of the entry to be added. Note that 1365 the server will not dereference any aliases in locating the entry 1366 to be added. 1368 - attributes: the list of attributes that make up the content of the 1369 entry being added. Clients MUST include distinguished values 1370 (those forming the entry's own RDN) in this list, the objectClass 1371 attribute, and values of any mandatory attributes of the listed 1372 object classes. Clients MUST NOT supply NO-USER-MODIFICATION 1373 attributes such as the createTimestamp or creatorsName attributes, 1374 since the server maintains these automatically. 1376 The entry named in the entry field of the AddRequest MUST NOT exist 1377 for the AddRequest to succeed. The parent of the entry to be added 1378 MUST exist. For example, if the client attempted to add 1379 "CN=JS,O=Foo,C=US", the "O=Foo,C=US" entry did not exist, and the 1380 "C=US" entry did exist, then the server would return the error 1381 noSuchObject with the matchedDN field containing "C=US". If the 1382 parent entry exists but is not in a naming context held by the 1383 server, the server SHOULD return a referral to the server holding the 1384 parent entry. 1386 Servers implementations SHOULD NOT restrict where entries can be 1387 located in the directory. Some servers MAY allow the administrator to 1388 restrict the classes of entries which can be added to the directory. 1390 Upon receipt of an Add Request, a server will attempt to perform the 1391 add requested. The result of the add attempt will be returned to the 1392 client in the Add Response, defined as follows: 1394 AddResponse ::= [APPLICATION 9] LDAPResult 1396 A response of success indicates that the new entry is present in the 1397 directory. 1399 4.8. Delete Operation 1401 The Delete Operation allows a client to request the removal of an 1402 entry from the directory. The Delete Request is defined as follows: 1404 DelRequest ::= [APPLICATION 10] LDAPDN 1406 The Delete Request consists of the Distinguished Name of the entry to 1407 be deleted. Note that the server will not dereference aliases while 1408 resolving the name of the target entry to be removed, and that only 1409 Lightweight Directory Access Protocol Version 3 1411 leaf entries (those with no subordinate entries) can be deleted with 1412 this operation. 1414 The result of the delete attempted by the server upon receipt of a 1415 Delete Request is returned in the Delete Response, defined as 1416 follows: 1418 DelResponse ::= [APPLICATION 11] LDAPResult 1420 Upon receipt of a Delete Request, a server will attempt to perform 1421 the entry removal requested. The result of the delete attempt will be 1422 returned to the client in the Delete Response. 1424 4.9. Modify DN Operation 1426 The Modify DN Operation allows a client to change the leftmost (least 1427 significant) component of the name of an entry in the directory, or 1428 to move a subtree of entries to a new location in the directory. The 1429 Modify DN Request is defined as follows: 1431 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE { 1432 entry LDAPDN, 1433 newrdn RelativeLDAPDN, 1434 deleteoldrdn BOOLEAN, 1435 newSuperior [0] LDAPDN OPTIONAL } 1437 Parameters of the Modify DN Request are: 1439 - entry: the Distinguished Name of the entry to be changed. This 1440 entry may or may not have subordinate entries. Note that the 1441 server will not dereference any aliases in locating the entry to 1442 be changed. 1444 - newrdn: the RDN that will form the leftmost component of the new 1445 name of the entry. 1447 - deleteoldrdn: a boolean parameter that controls whether the old 1448 RDN attribute values are to be retained as attributes of the 1449 entry, or deleted from the entry. 1451 - newSuperior: if present, this is the Distinguished Name of the 1452 entry which becomes the immediate superior of the existing entry. 1454 The result of the name change attempted by the server upon receipt of 1455 a Modify DN Request is returned in the Modify DN Response, defined as 1456 follows: 1458 ModifyDNResponse ::= [APPLICATION 13] LDAPResult 1460 Upon receipt of a ModifyDNRequest, a server will attempt to perform 1461 the name change. The result of the name change attempt will be 1462 returned to the client in the Modify DN Response. 1464 Lightweight Directory Access Protocol Version 3 1466 For example, if the entry named in the "entry" parameter was "cn=John 1467 Smith,c=US", the newrdn parameter was "cn=John Cougar Smith", and the 1468 newSuperior parameter was absent, then this operation would attempt 1469 to rename the entry to be "cn=John Cougar Smith,c=US". If there was 1470 already an entry with that name, the operation would fail with error 1471 code entryAlreadyExists. 1473 If the deleteoldrdn parameter is TRUE, the values forming the old RDN 1474 are deleted from the entry. If the deleteoldrdn parameter is FALSE, 1475 the values forming the old RDN will be retained as non-distinguished 1476 attribute values of the entry. The server may not perform the 1477 operation and return an error code if the setting of the deleteoldrdn 1478 parameter would cause a schema inconsistency in the entry. 1480 Note that X.500 restricts the ModifyDN operation to only affect 1481 entries that are contained within a single server. If the LDAP server 1482 is mapped onto DAP, then this restriction will apply, and the 1483 resultCode affectsMultipleDSAs will be returned if this error 1484 occurred. In general clients MUST NOT expect to be able to perform 1485 arbitrary movements of entries and subtrees between servers. 1487 4.10. Compare Operation 1489 The Compare Operation allows a client to compare an assertion 1490 provided with an entry in the directory. The Compare Request is 1491 defined as follows: 1493 CompareRequest ::= [APPLICATION 14] SEQUENCE { 1494 entry LDAPDN, 1495 ava AttributeValueAssertion } 1497 Parameters of the Compare Request are: 1499 - entry: the name of the entry to be compared with. Note that the 1500 server SHOULD NOT dereference any aliases in locating the entry to 1501 be compared with. 1503 - ava: the assertion with which an attribute in the entry is to be 1504 compared. 1506 The result of the compare attempted by the server upon receipt of a 1507 Compare Request is returned in the Compare Response, defined as 1508 follows: 1510 CompareResponse ::= [APPLICATION 15] LDAPResult 1512 Upon receipt of a Compare Request, a server will attempt to perform 1513 the requested comparison. The result of the comparison will be 1514 returned to the client in the Compare Response. Note that errors and 1515 the result of comparison are all returned in the same construct. 1517 Note that some directory systems may establish access controls which 1518 permit the values of certain attributes (such as userPassword) to be 1519 Lightweight Directory Access Protocol Version 3 1521 compared but not read. In a search result, it may be that an 1522 attribute of that type would be returned, but with an empty set of 1523 values. 1525 4.11. Abandon Operation 1527 The function of the Abandon Operation is to allow a client to request 1528 that the server abandon an outstanding operation. The Abandon Request 1529 is defined as follows: 1531 AbandonRequest ::= [APPLICATION 16] MessageID 1533 The MessageID MUST be that of an operation which was requested 1534 earlier in this connection. 1536 (The abandon request itself has its own message id. This is distinct 1537 from the id of the earlier operation being abandoned.) 1539 There is no response defined in the Abandon Operation. Upon 1540 transmission of an Abandon Operation, a client may expect that the 1541 operation identified by the Message ID in the Abandon Request will be 1542 abandoned. In the event that a server receives an Abandon Request on 1543 a Search Operation in the midst of transmitting responses to the 1544 search, that server MUST cease transmitting entry responses to the 1545 abandoned request immediately, and MUST NOT send the 1546 SearchResponseDone. Of course, the server MUST ensure that only 1547 properly encoded LDAPMessage PDUs are transmitted. 1549 Clients MUST NOT send abandon requests for the same operation 1550 multiple times, and MUST also be prepared to receive results from 1551 operations it has abandoned (since these may have been in transit 1552 when the abandon was requested). 1554 Servers MUST discard abandon requests for message IDs they do not 1555 recognize, for operations which cannot be abandoned, and for 1556 operations which have already been abandoned. 1558 4.12. Extended Operation 1560 An extension mechanism has been added in this version of LDAP, in 1561 order to allow additional operations to be defined for services not 1562 available elsewhere in this protocol, for instance digitally signed 1563 operations and results. 1565 The extended operation allows clients to make requests and receive 1566 responses with predefined syntaxes and semantics. These may be 1567 defined in RFCs or be private to particular implementations. Each 1568 request MUST have a unique OBJECT IDENTIFIER assigned to it. 1570 ExtendedRequest ::= [APPLICATION 23] SEQUENCE { 1571 requestName [0] LDAPOID, 1572 requestValue [1] OCTET STRING OPTIONAL } 1573 Lightweight Directory Access Protocol Version 3 1575 The requestName is a dotted-decimal representation of the OBJECT 1576 IDENTIFIER corresponding to the request. The requestValue is 1577 information in a form defined by that request, encapsulated inside an 1578 OCTET STRING. 1580 The server will respond to this with an LDAPMessage containing the 1581 ExtendedResponse. 1583 ExtendedResponse ::= [APPLICATION 24] SEQUENCE { 1584 COMPONENTS OF LDAPResult, 1585 responseName [10] LDAPOID OPTIONAL, 1586 response [11] OCTET STRING OPTIONAL } 1588 If the server does not recognize the request name, it MUST return 1589 only the response fields from LDAPResult, containing the 1590 protocolError result code. 1592 5. Protocol Element Encodings and Transfer 1594 One underlying service is defined here. Clients and servers SHOULD 1595 implement the mapping of LDAP over TCP described in 5.2.1. 1597 5.1. Protocol Encoding 1599 The protocol elements of LDAP are encoded for exchange using the 1600 Basic Encoding Rules (BER) [X.690] of ASN.1 [X.680]. However, due to 1601 the high overhead involved in using certain elements of the BER, the 1602 following additional restrictions are placed on BER-encodings of LDAP 1603 protocol elements: 1605 (1) Only the definite form of length encoding will be used. 1607 (2) OCTET STRING values will be encoded in the primitive form only. 1609 (3) If the value of a BOOLEAN type is true, the encoding MUST have 1610 its contents octets set to hex "FF". 1612 (4) If a value of a type is its default value, it MUST be absent. 1613 Only some BOOLEAN and INTEGER types have default values in this 1614 protocol definition. 1616 These restrictions do not apply to ASN.1 types encapsulated inside of 1617 OCTET STRING values, such as attribute values, unless otherwise 1618 noted. 1620 5.2. Transfer Protocols 1622 This protocol is designed to run over connection-oriented, reliable 1623 transports, with all 8 bits in an octet being significant in the data 1624 stream. 1626 Lightweight Directory Access Protocol Version 3 1628 5.2.1. Transmission Control Protocol (TCP) 1630 The encoded LDAPMessage PDUs are mapped directly onto the TCP 1631 bytestream. It is recommended that server implementations running 1632 over the TCP MAY provide a protocol listener on the assigned port, 1633 389. Servers may instead provide a listener on a different port 1634 number. Clients MUST support contacting servers on any valid TCP 1635 port. 1637 6. Implementation Guidelines 1639 This document describes an Internet protocol. 1641 6.1. Server Implementations 1643 The server MUST be capable of recognizing all the mandatory attribute 1644 type names and implement the syntaxes specified in [Syntaxes]. 1645 Servers MAY also recognize additional attribute type names. 1647 6.2. Client Implementations 1649 Clients which request referrals MUST ensure that they do not loop 1650 between servers. They MUST NOT repeatedly contact the same server for 1651 the same request with the same target entry name, scope and filter. 1652 Some clients may be using a counter that is incremented each time 1653 referral handling occurs for an operation, and these kinds of clients 1654 MUST be able to handle a DIT with at least ten layers of naming 1655 contexts between the root and a leaf entry. 1657 In the absence of prior agreements with servers, clients SHOULD NOT 1658 assume that servers support any particular schemas beyond those 1659 referenced in section 6.1. Different schemas can have different 1660 attribute types with the same names. The client can retrieve the 1661 subschema entries referenced by the subschemaSubentry attribute in 1662 the server's root DSE or in entries held by the server. 1664 7. Security Considerations 1666 When used with a connection-oriented transport, this version of the 1667 protocol provides facilities for simple authentication using a 1668 cleartext password, as well as any SASL mechanism [RFC2222]. SASL 1669 allows for integrity and privacy services to be negotiated. 1671 It is also permitted that the server can return its credentials to 1672 the client, if it chooses to do so. 1674 Lightweight Directory Access Protocol Version 3 1676 Use of cleartext password is strongly discouraged where the 1677 underlying transport service cannot guarantee confidentiality and may 1678 result in disclosure of the password to unauthorized parties. 1680 When used with SASL, it should be noted that the name field of the 1681 BindRequest is not protected against modification. Thus if the 1682 distinguished name of the client (an LDAPDN) is agreed through the 1683 negotiation of the credentials, it takes precedence over any value in 1684 the unprotected name field. 1686 Implementations which cache attributes and entries obtained via LDAP 1687 MUST ensure that access controls are maintained if that information 1688 is to be provided to multiple clients, since servers may have access 1689 control policies which prevent the return of entries or attributes in 1690 search results except to particular authenticated clients. For 1691 example, caches could serve result information only to the client 1692 whose request caused it to be in the cache. 1694 8. Acknowledgements 1696 This document is an update to RFC 2251, by Mark Wahl, Tim Howes, and 1697 Steve Kille. Their work along with the input of individuals of the 1698 IETF LDAPEXT, LDUP, LDAPBIS, and other Working Groups is gratefully 1699 acknowledged. 1701 9. Normative References 1703 [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts, 1704 Models and Service", 1993. 1706 [Roadmap] K. Zeilenga (editor), "LDAP: Technical Specification Road 1707 Map", draft-ietf-ldapbis-roadmap-xx.txt (a work in progress). 1709 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1710 Requirement Levels", RFC 2119, March 1997. 1712 [X.680] ITU-T Recommendation X.680 (1997) | ISO/IEC 8824-1:1998 1713 Information Technology - Abstract Syntax Notation One 1714 (ASN.1): Specification of basic notation 1716 [X.690] ITU-T Rec. X.690, "Specification of ASN.1 encoding rules: 1717 Basic, Canonical, and Distinguished Encoding Rules", 1994. 1719 [LDAPIANA] K. Zeilenga, "IANA Considerations for LDAP", draft-ietf- 1720 ldapbis-xx.txt (a work in progress). 1722 [ISO10646] Universal Multiple-Octet Coded Character Set (UCS) - 1723 Architecture and Basic Multilingual Plane, ISO/IEC 10646-1 1724 : 1993. 1726 [RFC2044] Yergeau, F., "UTF-8, a transformation format of Unicode 1727 and ISO 10646", RFC 2044, October 1996. 1729 Lightweight Directory Access Protocol Version 3 1731 [Models] K. Zeilenga, "LDAP: The Models", draft-ietf-ldapbis- 1732 models-xx.txt (a work in progress). 1734 [LDAPDN] K. Zeilenga (editor), "LDAP: String Representation of 1735 Distinguished Names", draft-ietf-ldapbis-dn-xx.txt, (a 1736 work in progress). 1738 [Syntaxes] K. Dally (editor), "LDAP: Syntaxes", draft-ietf-ldapbis- 1739 syntaxes-xx.txt, (a work in progress). 1741 [X.501] ITU-T Rec. X.501, "The Directory: Models", 1993. 1743 [X.511] ITU-T Rec. X.511, "The Directory: Abstract Service 1744 Definition", 1993. 1746 [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter Uniform 1747 Resource Identifiers (URI): Generic Syntax", RFC 2396, 1748 August 1998. 1750 [AuthMeth] R. Harrison (editor), "LDAP: Authentication Methods", 1751 draft-ietf-ldapbis-authmeth-xx.txt, (a work in progress). 1753 [RFC2222] Meyers, J., "Simple Authentication and Security Layer", 1754 RFC 2222, October 1997. 1756 10. Editor's Address 1758 Jim Sermersheim 1759 Novell, Inc. 1760 1800 South Novell Place 1761 Provo, Utah 84606, USA 1762 jimse@novell.com 1763 +1 801 861-3088 1764 Lightweight Directory Access Protocol Version 3 1766 Appendix A - LDAP Result Codes 1768 This normative appendix details additional considerations regarding 1769 LDAP result codes and provides a brief, general description of each 1770 LDAP result code enumerated in Section 4.1.10. 1772 Additional result codes MAY be defined for use with extensions. 1773 Client implementations SHALL treat any result code which they do not 1774 recognize as an unknown error condition. 1776 A.1 Non-Error Result Codes 1777 These result codes (called "non-error" result codes) do not indicate 1778 an error condition: 1779 success(0), 1780 compareTrue(6), 1781 compareFalse(7), 1782 referral(10), and 1783 saslBindInProgress(14). 1785 The success(0), compareTrue(6), and compare(7) result codes indicate 1786 successful completion (and, hence, are called to as "successful" 1787 result codes). 1789 The referral(10) and saslBindInProgress(14) indicate the client is 1790 required to take additional action to complete the operation 1792 A.2 Error Result Codes 1794 A.3 Classes and Precedence of Error Result Codes 1796 Result codes that indicate error conditions (and, hence, are called 1797 "error" result codes) fall into 6 classes. The following list 1798 specifies the precedence of error classes to be used when more than 1799 one error is detected [X511]: 1800 1) Name Errors (codes 32 - 34, 36) 1801 - a problem related to a name (DN or RDN), 1802 2) Update Errors (codes 64 - 69, 71) 1803 - a problem related to an update operation, 1804 3) Attribute Errors (codes 16 - 21) 1805 - a problem related to a supplied attribute, 1806 4) Security Errors (codes 8, 13, 48 - 50) 1807 - a security related problem, 1808 5) Service Problem (codes 3, 4, 7, 11, 12, 51 - 54, 80) 1809 - a problem related to the provision of the service, and 1810 6) Protocol Problem (codes 1, 2) 1811 - a problem related to protocol structure or semantics. 1813 Server implementations SHALL NOT continue processing an operation 1814 after it has determined that an error is to be reported. If the 1815 server detects multiple errors simultaneously, the server SHOULD 1816 report the error with the highest precedence. 1818 Existing LDAP result codes are described as follows: 1820 Lightweight Directory Access Protocol Version 3 1822 success (0) 1824 Indicates successful completion of an operation. 1826 This result code is normally not returned by the compare 1827 operation, see compareFalse (5) and compareTrue (6). 1829 operationsError (1) 1831 Indicates that the operation is not properly sequenced with 1832 relation to other operations (of same or different type). 1834 For example, this code is returned if the client attempts to 1835 Start TLS [RFC2830] while there are other operations 1836 outstanding or if TLS was already established. 1838 For the bind operation only, the code indicates the server 1839 encountered an internal error. 1841 protocolError (2) 1843 Indicates the server received data which has incorrect 1844 structure. 1846 For bind operation only, the code may be resulted to indicate 1847 the server does not support the requested protocol version. 1849 timeLimitExceeded (3) 1851 Indicates that the time limit specified by the client was 1852 exceeded before the operation could be completed. 1854 sizeLimitExceeded (4) 1856 Indicates that the size limit specified by the client was 1857 exceeded before the operation could be completed. 1859 compareFalse (5) 1861 Indicates that the operation successfully completes and the 1862 assertion has evaluated to TRUE. 1864 This result code is normally only returned by the compare 1865 operation. 1867 compareTrue (6) 1868 Lightweight Directory Access Protocol Version 3 1870 Indicates that the operation successfully completes and the 1871 assertion has evaluated to FALSE. 1873 This result code is normally only returned by the compare 1874 operation. 1876 authMethodNotSupported (7) 1878 Indicates that authentication method or mechanism is not 1879 supported. 1881 strongAuthRequired (8) 1883 Except when returned in a Notice of Disconnect (see section 1884 4.4.1), this indicates that the server requires the client to 1885 authentication using a strong(er) mechanism. 1887 referral (10) 1889 Indicates that a referral needs to be chased to complete the 1890 operation (see section 4.1.11). 1892 adminLimitExceeded (11) 1894 Indicates that an admnistrative limit has been exceeded. 1896 unavailableCriticalExtension (12) 1898 Indicates that server cannot perform a critical extension 1899 (see section 4.1.12). 1901 confidentialityRequired (13) 1903 Indicates that data confidentiality protections are required. 1905 saslBindInProgress (14) 1907 Indicates the server requires the client to send a new bind 1908 request, with the same sasl mechanism, to continue the 1909 authentication process (see section 4.2). 1911 noSuchAttribute (16) 1913 Indicates that the named entry does not contain the specified 1914 attribute or attribute value. 1916 Lightweight Directory Access Protocol Version 3 1918 undefinedAttributeType (17) 1920 Indicates that a request field contains an undefined 1921 attribute type. 1923 inappropriateMatching (18) 1925 Indicates that a request cannot be completed due to an 1926 inappropriate matching. 1928 constraintViolation (19) 1930 Indicates that the client supplied an attribute value which 1931 does not conform to constraints placed upon it by the data 1932 model. 1934 For example, this code is returned when the multiple values 1935 are supplied to an attribute which has a SINGLE-VALUE 1936 constraint. 1938 attributeOrValueExists (20) 1940 Indicates that the client supplied an attribute or value to 1941 be added to an entry already exists. 1943 invalidAttributeSyntax (21) 1945 Indicates that a purported attribute value does not conform 1946 to the syntax of the attribute. 1948 noSuchObject (32) 1950 Indicates that the object does not exist in the DIT. 1952 aliasProblem (33) 1954 Indicates that an alias problem has occurred. 1956 invalidDNSyntax (34) 1958 Indicates that a LDAPDN or RelativeLDAPDN field (e.g. search 1959 base, target entry, ModifyDN newrdn, etc.) of a request does 1960 not conform to the required syntax or contains attribute 1961 values which do not conform to the syntax of the attribute's 1962 type. 1964 Lightweight Directory Access Protocol Version 3 1966 aliasDereferencingProblem (36) 1968 Indicates that a problem in dereferencing an alias. 1970 inappropriateAuthentication (48) 1972 Indicates the server requires the client which had attempted 1973 to bind anonymously or without supplying credentials to 1974 provide some form of credentials, 1976 invalidCredentials (49) 1978 Indicates the supplied credentials are invalid. 1980 insufficientAccessRights (50) 1982 Indicates that the client does not have sufficient access 1983 rights to perform the operation. 1985 busy (51) 1987 Indicates that the server is busy. 1989 unavailable (52) 1991 Indicates that the server is shutting down or a subsystem 1992 necessary to complete the operation is offline. 1994 unwillingToPerform (53) 1996 Indicates that the server is unwilling to perform the 1997 operation. 1999 loopDetect (54) 2001 Indicates that the server has detected an internal loop. 2003 namingViolation (64) 2005 Indicates that the entry name violates naming restrictions. 2007 objectClassViolation (65) 2009 Indicates that the entry violates object class restrictions. 2011 Lightweight Directory Access Protocol Version 3 2013 notAllowedOnNonLeaf (66) 2015 Indicates that operation is inappropriately acting upon a 2016 non-leaf entry. 2018 notAllowedOnRDN (67) 2020 Indicates that the operation is inappropriately attempting to 2021 remove a value which forms the entry's relative distinguished 2022 name. 2024 entryAlreadyExists (68) 2026 Indicates that the request cannot be added fulfilled as the 2027 entry already exists. 2029 objectClassModsProhibited (69) 2031 Indicates that the attempt to modify the object class(es) of 2032 an entry objectClass attribute is prohibited. 2034 For example, this code is returned when a when a client 2035 attempts to modify the structural object class of an entry. 2037 affectsMultipleDSAs (71) 2039 Indicates that the operation cannot be completed as it 2040 affects multiple servers (DSAs). 2042 other (80) 2044 Indicates the server has encountered an internal error. 2046 Lightweight Directory Access Protocol Version 3 2048 Appendix B - Complete ASN.1 Definition 2050 This appendix is normative. 2052 Lightweight-Directory-Access-Protocol-V3 DEFINITIONS 2053 IMPLICIT TAGS 2054 EXTENSIBILITY IMPLIED ::= 2056 BEGIN 2058 LDAPMessage ::= SEQUENCE { 2059 messageID MessageID, 2060 protocolOp CHOICE { 2061 bindRequest BindRequest, 2062 bindResponse BindResponse, 2063 unbindRequest UnbindRequest, 2064 searchRequest SearchRequest, 2065 searchResEntry SearchResultEntry, 2066 searchResDone SearchResultDone, 2067 searchResRef SearchResultReference, 2068 modifyRequest ModifyRequest, 2069 modifyResponse ModifyResponse, 2070 addRequest AddRequest, 2071 addResponse AddResponse, 2072 delRequest DelRequest, 2073 delResponse DelResponse, 2074 modDNRequest ModifyDNRequest, 2075 modDNResponse ModifyDNResponse, 2076 compareRequest CompareRequest, 2077 compareResponse CompareResponse, 2078 abandonRequest AbandonRequest, 2079 extendedReq ExtendedRequest, 2080 extendedResp ExtendedResponse }, 2081 controls [0] Controls OPTIONAL } 2083 MessageID ::= INTEGER (0 .. maxInt) 2085 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) -- 2087 LDAPString ::= OCTET STRING -- UTF-8 encoded, 2088 -- [ISO10646] characters 2090 LDAPOID ::= OCTET STRING -- Constrained to numericoid [Models] 2092 LDAPDN ::= LDAPString 2094 RelativeLDAPDN ::= LDAPString 2096 AttributeDescription ::= LDAPString 2097 -- Constrained to attributedescription 2098 -- [Models] 2100 AttributeDescriptionList ::= SEQUENCE OF 2101 AttributeDescription 2102 Lightweight Directory Access Protocol Version 3 2104 AttributeValue ::= OCTET STRING 2106 AttributeValueAssertion ::= SEQUENCE { 2107 attributeDesc AttributeDescription, 2108 assertionValue AssertionValue } 2110 AssertionValue ::= OCTET STRING 2112 Attribute ::= SEQUENCE { 2113 type AttributeDescription, 2114 vals SET OF AttributeValue } 2116 MatchingRuleId ::= LDAPString 2118 LDAPResult ::= SEQUENCE { 2119 resultCode ENUMERATED { 2120 success (0), 2121 operationsError (1), 2122 protocolError (2), 2123 timeLimitExceeded (3), 2124 sizeLimitExceeded (4), 2125 compareFalse (5), 2126 compareTrue (6), 2127 authMethodNotSupported (7), 2128 strongAuthRequired (8), 2129 -- 9 reserved -- 2130 referral (10), 2131 adminLimitExceeded (11), 2132 unavailableCriticalExtension (12), 2133 confidentialityRequired (13), 2134 saslBindInProgress (14), 2135 noSuchAttribute (16), 2136 undefinedAttributeType (17), 2137 inappropriateMatching (18), 2138 constraintViolation (19), 2139 attributeOrValueExists (20), 2140 invalidAttributeSyntax (21), 2141 -- 22-31 unused -- 2142 noSuchObject (32), 2143 aliasProblem (33), 2144 invalidDNSyntax (34), 2145 -- 35 reserved for undefined isLeaf -- 2146 aliasDereferencingProblem (36), 2147 -- 37-47 unused -- 2148 inappropriateAuthentication (48), 2149 invalidCredentials (49), 2150 insufficientAccessRights (50), 2151 busy (51), 2152 unavailable (52), 2153 unwillingToPerform (53), 2154 loopDetect (54), 2155 -- 55-63 unused -- 2156 namingViolation (64), 2157 Lightweight Directory Access Protocol Version 3 2159 objectClassViolation (65), 2160 notAllowedOnNonLeaf (66), 2161 notAllowedOnRDN (67), 2162 entryAlreadyExists (68), 2163 objectClassModsProhibited (69), 2164 -- 70 reserved for CLDAP -- 2165 affectsMultipleDSAs (71), 2166 -- 72-79 unused -- 2167 other (80), 2168 ... }, 2169 -- 81-90 reserved for APIs -- 2170 matchedDN LDAPDN, 2171 errorMessage LDAPString, 2172 referral [3] Referral OPTIONAL } 2174 Referral ::= SEQUENCE OF LDAPURL 2176 LDAPURL ::= LDAPString -- limited to characters permitted in 2177 -- URLs 2179 Controls ::= SEQUENCE OF Control 2181 Control ::= SEQUENCE { 2182 controlType LDAPOID, 2183 criticality BOOLEAN DEFAULT FALSE, 2184 controlValue OCTET STRING OPTIONAL } 2186 BindRequest ::= [APPLICATION 0] SEQUENCE { 2187 version INTEGER (1 .. 127), 2188 name LDAPDN, 2189 authentication AuthenticationChoice } 2191 AuthenticationChoice ::= CHOICE { 2192 simple [0] OCTET STRING, 2193 -- 1 and 2 reserved 2194 sasl [3] SaslCredentials, 2195 ... } 2197 SaslCredentials ::= SEQUENCE { 2198 mechanism LDAPString, 2199 credentials OCTET STRING OPTIONAL } 2201 BindResponse ::= [APPLICATION 1] SEQUENCE { 2202 COMPONENTS OF LDAPResult, 2203 serverSaslCreds [7] OCTET STRING OPTIONAL } 2205 UnbindRequest ::= [APPLICATION 2] NULL 2207 SearchRequest ::= [APPLICATION 3] SEQUENCE { 2208 baseObject LDAPDN, 2209 scope ENUMERATED { 2210 baseObject (0), 2211 singleLevel (1), 2212 wholeSubtree (2) }, 2213 Lightweight Directory Access Protocol Version 3 2215 derefAliases ENUMERATED { 2216 neverDerefAliases (0), 2217 derefInSearching (1), 2218 derefFindingBaseObj (2), 2219 derefAlways (3) }, 2220 sizeLimit INTEGER (0 .. maxInt), 2221 timeLimit INTEGER (0 .. maxInt), 2222 typesOnly BOOLEAN, 2223 filter Filter, 2224 attributes AttributeDescriptionList } 2226 Filter ::= CHOICE { 2227 and [0] SET SIZE (1..MAX) OF Filter, 2228 or [1] SET SIZE (1..MAX) OF Filter, 2229 not [2] Filter, 2230 equalityMatch [3] AttributeValueAssertion, 2231 substrings [4] SubstringFilter, 2232 greaterOrEqual [5] AttributeValueAssertion, 2233 lessOrEqual [6] AttributeValueAssertion, 2234 present [7] AttributeDescription, 2235 approxMatch [8] AttributeValueAssertion, 2236 extensibleMatch [9] MatchingRuleAssertion } 2238 SubstringFilter ::= SEQUENCE { 2239 type AttributeDescription, 2240 -- at least one must be present, 2241 -- initial and final can occur at most once 2242 substrings SEQUENCE OF CHOICE { 2243 initial [0] AssertionValue, 2244 any [1] AssertionValue, 2245 final [2] AssertionValue } } 2247 MatchingRuleAssertion ::= SEQUENCE { 2248 matchingRule [1] MatchingRuleId OPTIONAL, 2249 type [2] AttributeDescription OPTIONAL, 2250 matchValue [3] AssertionValue, 2251 dnAttributes [4] BOOLEAN DEFAULT FALSE } 2253 SearchResultEntry ::= [APPLICATION 4] SEQUENCE { 2254 objectName LDAPDN, 2255 attributes PartialAttributeList } 2257 PartialAttributeList ::= SEQUENCE OF SEQUENCE { 2258 type AttributeDescription, 2259 vals SET OF AttributeValue } 2261 SearchResultReference ::= [APPLICATION 19] SEQUENCE OF LDAPURL 2263 SearchResultDone ::= [APPLICATION 5] LDAPResult 2265 ModifyRequest ::= [APPLICATION 6] SEQUENCE { 2266 object LDAPDN, 2267 modification SEQUENCE OF SEQUENCE { 2268 operation ENUMERATED { 2269 Lightweight Directory Access Protocol Version 3 2271 add (0), 2272 delete (1), 2273 replace (2) }, 2274 modification AttributeTypeAndValues } } 2276 AttributeTypeAndValues ::= SEQUENCE { 2277 type AttributeDescription, 2278 vals SET OF AttributeValue } 2280 ModifyResponse ::= [APPLICATION 7] LDAPResult 2282 AddRequest ::= [APPLICATION 8] SEQUENCE { 2283 entry LDAPDN, 2284 attributes AttributeList } 2286 AttributeList ::= SEQUENCE OF SEQUENCE { 2287 type AttributeDescription, 2288 vals SET OF AttributeValue } 2290 AddResponse ::= [APPLICATION 9] LDAPResult 2292 DelRequest ::= [APPLICATION 10] LDAPDN 2294 DelResponse ::= [APPLICATION 11] LDAPResult 2296 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE { 2297 entry LDAPDN, 2298 newrdn RelativeLDAPDN, 2299 deleteoldrdn BOOLEAN, 2300 newSuperior [0] LDAPDN OPTIONAL } 2302 ModifyDNResponse ::= [APPLICATION 13] LDAPResult 2304 CompareRequest ::= [APPLICATION 14] SEQUENCE { 2305 entry LDAPDN, 2306 ava AttributeValueAssertion } 2308 CompareResponse ::= [APPLICATION 15] LDAPResult 2310 AbandonRequest ::= [APPLICATION 16] MessageID 2312 ExtendedRequest ::= [APPLICATION 23] SEQUENCE { 2313 requestName [0] LDAPOID, 2314 requestValue [1] OCTET STRING OPTIONAL } 2316 ExtendedResponse ::= [APPLICATION 24] SEQUENCE { 2317 COMPONENTS OF LDAPResult, 2318 responseName [10] LDAPOID OPTIONAL, 2319 response [11] OCTET STRING OPTIONAL } 2321 END 2322 Lightweight Directory Access Protocol Version 3 2324 Appendix C - Change History 2326 C.1 Changes made to RFC 2251: 2328 C.1.1 Editorial 2330 - Bibliography References: Changed all bibliography references to 2331 use a long name form for readability. 2332 - Changed occurrences of "unsupportedCriticalExtension" 2333 "unavailableCriticalExtension" 2334 - Fixed a small number of misspellings (mostly dropped letters). 2336 C.1.2 Section 1 2338 - Removed IESG note. 2340 C.1.3 Section 9 2342 - Added references to RFCs 1823, 2234, 2829 and 2830. 2344 C.2 Changes made to draft-ietf-ldapbis-protocol-00.txt: 2346 C.2.1 Section 4.1.6 2348 - In the first paragraph, clarified what the contents of an 2349 AttributeValue are. There was confusion regarding whether or not 2350 an AttributeValue that is BER encoded (due to the "binary" option) 2351 is to be wrapped in an extra OCTET STRING. 2352 - To the first paragraph, added wording that doesn't restrict other 2353 transfer encoding specifiers from being used. The previous wording 2354 only allowed for the string encoding and the ;binary encoding. 2355 - To the first paragraph, added a statement restricting multiple 2356 options that specify transfer encoding from being present. This 2357 was never specified in the previous version and was seen as a 2358 potential interoperability problem. 2359 - Added a third paragraph stating that the ;binary option is 2360 currently the only option defined that specifies the transfer 2361 encoding. This is for completeness. 2363 C.2.2 Section 4.1.7 2365 - Generalized the second paragraph to read "If an option specifying 2366 the transfer encoding is present in attributeDesc, the 2367 AssertionValue is encoded as specified by the option...". 2368 Previously, only the ;binary option was mentioned. 2370 C.2.3 Sections 4.2, 4.9, 4.10 2372 - Added alias dereferencing specifications. In the case of modDN, 2373 followed precedent set on other update operations (... alias is 2374 not dereferenced...) In the case of bind and compare stated that 2375 servers SHOULD NOT dereference aliases. Specifications were added 2376 because they were missing from the previous version and caused 2377 Lightweight Directory Access Protocol Version 3 2379 interoperability problems. Concessions were made for bind and 2380 compare (neither should have ever allowed alias dereferencing) by 2381 using SHOULD NOT language, due to the behavior of some existing 2382 implementations. 2384 C.2.4 Sections 4.5 and Appendix A 2386 - Changed SubstringFilter.substrings.initial, any, and all from 2387 LDAPString to AssertionValue. This was causing an incompatibility 2388 with X.500 and confusion among other TS RFCs. 2390 C.3 Changes made to draft-ietf-ldapbis-protocol-01.txt: 2392 C.3.1 Section 3.4 2394 - Reworded text surrounding subschemaSubentry to reflect that it is 2395 a single-valued attribute that holds the schema for the root DSE. 2396 Also noted that if the server masters entries that use differing 2397 schema, each entry's subschemaSubentry attribute must be 2398 interrogated. This may change as further fine-tuning is done to 2399 the data model. 2401 C.3.2 Section 4.1.12 2403 - Specified that the criticality field is only used for requests and 2404 not for unbind or abandon. Noted that it is ignored for all other 2405 operations. 2407 C.3.3 Section 4.2 2409 - Noted that Server behavior is undefined when the name is a null 2410 value, simple authentication is used, and a password is specified. 2412 C.3.4 Section 4.2.(various) 2414 - Changed "unauthenticated" to "anonymous" and "DN" and "LDAPDN" to 2415 "name" 2417 C.3.5 Section 4.2.2 2419 - Changed "there is no authentication or encryption being performed 2420 by a lower layer" to "the underlying transport service cannot 2421 guarantee confidentiality" 2423 C.3.6 Section 4.5.2 2425 - Removed all mention of ExtendedResponse due to lack of 2426 implementation. 2428 C.4 Changes made to draft-ietf-ldapbis-protocol-02.txt: 2430 C.4.1 Section 4 2431 Lightweight Directory Access Protocol Version 3 2433 - Removed "typically" from "and is typically transferred" in the 2434 first paragraph. We know of no (and can conceive of no) case where 2435 this isn't true. 2436 - Added "Section 5.1 specifies how the LDAP protocol is encoded." To 2437 the first paragraph. Added this cross reference for readability. 2438 - Changed "version 3 " to "version 3 or later" in the second 2439 paragraph. This was added to clarify the original intent. 2440 - Changed "protocol version" to "protocol versions" in the third 2441 paragraph. This attribute is multi-valued with the intent of 2442 holding all supported versions, not just one. 2444 C.4.2 Section 4.1.8 2446 - Changed "when transferred in protocol" to "when transferred from 2447 the server to the client" in the first paragraph. This is to 2448 clarify that this behavior only happens when attributes are being 2449 sent from the server. 2451 C.4.3 Section 4.1.10 2453 - Changed "servers will return responses containing fields of type 2454 LDAPResult" to "servers will return responses of LDAPResult or 2455 responses containing the components of LDAPResponse". This 2456 statement was incorrect and at odds with the ASN.1. The fix here 2457 reflects the original intent. 2458 - Dropped '--new' from result codes ASN.1. This simplification in 2459 comments just reduces unneeded verbiage. 2461 C.4.4 Section 4.1.11 2463 - Changed "It contains a reference to another server (or set of 2464 servers)" to "It contains one or more references to one or more 2465 servers or services" in the first paragraph. This reflects the 2466 original intent and clarifies that the URL may point to non-LDAP 2467 services. 2469 C.4.5 Section 4.1.12 2471 - Changed "The server MUST be prepared" to "Implementations MUST be 2472 prepared" in the eighth paragraph to reflect that both client and 2473 server implementations must be able to handle this (as both parse 2474 controls). 2476 C.4.6 Section 4.4 2478 - Changed "One unsolicited notification is defined" to "One 2479 unsolicited notification (Notice of Disconnection) is defined" in 2480 the third paragraph. For clarity and readability. 2482 C.4.7 Section 4.5.1 2484 - Changed "checking for the existence of the objectClass attribute" 2485 to "checking for the presence of the objectClass attribute" in the 2486 last paragraph. This was done as a measure of consistency (we use 2487 Lightweight Directory Access Protocol Version 3 2489 the terms present and presence rather than exists and existence in 2490 search filters). 2492 C.4.8 Section 4.5.3 2494 - Changed "outstanding search operations to different servers," to 2495 "outstanding search operations" in the fifth paragraph as they may 2496 be to the same server. This is a point of clarification. 2498 C.4.9 Section 4.6 2500 - Changed "clients MUST NOT attempt to delete" to "clients MUST NOT 2501 attempt to add or delete" in the second to last paragraph. 2502 - Change "using the "delete" form" to "using the "add" or "delete" 2503 form" in the second to last paragraph. 2505 C.4.10 Section 4.7 2507 - Changed "Clients MUST NOT supply the createTimestamp or 2508 creatorsName attributes, since these will be generated 2509 automatically by the server." to "Clients MUST NOT supply NO-USER- 2510 MODIFICATION attributes such as createTimestamp or creatorsName 2511 attributes, since these are provided by the server." in the 2512 definition of the attributes field. This tightens the language to 2513 reflect the original intent and to not leave a hole in which one 2514 could interpret the two attributes mentioned as the only non- 2515 writable attributes. 2517 C.4.11 Section 4.11 2519 - Changed "has been" to "will be" in the fourth paragraph. This 2520 clarifies that the server will (not has) abandon the operation. 2522 C.5 Changes made to draft-ietf-ldapbis-protocol-03.txt: 2524 C.5.1 Section 3.2.1 2526 - Changed "An attribute is a type with one or more associated 2527 values. The attribute type is identified by a short descriptive 2528 name and an OID (object identifier). The attribute type governs 2529 whether there can be more than one value of an attribute of that 2530 type in an entry, the syntax to which the values must conform, the 2531 kinds of matching which can be performed on values of that 2532 attribute, and other functions." to " An attribute is a 2533 description (a type and zero or more options) with one or more 2534 associated values. The attribute type governs whether the 2535 attribute can have multiple values, the syntax and matching rules 2536 used to construct and compare values of that attribute, and other 2537 functions. Options indicate modes of transfer and other 2538 functions.". This points out that an attribute consists of both 2539 the type and options. 2541 C.5.2 Section 4 2542 Lightweight Directory Access Protocol Version 3 2544 - Changed "Section 5.1 specifies the encoding rules for the LDAP 2545 protocol" to "Section 5.1 specifies how the protocol is encoded 2546 and transferred." 2548 C.5.3 Section 4.1.2 2550 - Added ABNF for the textual representation of LDAPOID. Previously, 2551 there was no formal BNF for this construct. 2553 C.5.4 Section 4.1.4 2555 - Changed "This identifier may be written as decimal digits with 2556 components separated by periods, e.g. "2.5.4.10"" to "may be 2557 written as defined by ldapOID in section 4.1.2" in the second 2558 paragraph. This was done because we now have a formal BNF 2559 definition of an oid. 2561 C.5.5 Section 4.1.5 2563 - Changed the BNF for AttributeDescription to ABNF. This was done 2564 for readability and consistency (no functional changes involved). 2565 - Changed "Options present in an AttributeDescription are never 2566 mutually exclusive." to "Options MAY be mutually exclusive. An 2567 AttributeDescription with mutually exclusive options is treated as 2568 an undefined attribute type." for clarity. It is generally 2569 understood that this is the original intent, but the wording could 2570 be easily misinterpreted. 2571 - Changed "Any option could be associated with any AttributeType, 2572 although not all combinations may be supported by a server." to 2573 "Though any option or set of options could be associated with any 2574 AttributeType, the server support for certain combinations may be 2575 restricted by attribute type, syntaxes, or other factors.". This 2576 is to clarify the meaning of 'combination' (it applies both to 2577 combination of attribute type and options, and combination of 2578 options). It also gives examples of *why* they might be 2579 unsupported. 2581 C.5.6 Section 4.1.11 2583 - Changed the wording regarding 'equally capable' referrals to "If 2584 multiple URLs are present, the client assumes that any URL may be 2585 used to progress the operation.". The previous language implied 2586 that the server MUST enforce rules that it was practically 2587 incapable of. The new language highlights the original intent-- 2588 that is, that any of the referrals may be used to progress the 2589 operation, there is no inherent 'weighting' mechanism. 2591 C.5.7 Section 4.5.1 and Appendix A 2593 - Added the comment "-- initial and final can occur at most once", 2594 to clarify this restriction. 2596 C.5.8 Section 5.1 2597 Lightweight Directory Access Protocol Version 3 2599 - Changed heading from "Mapping Onto BER-based Transport Services" 2600 to "Protocol Encoding". 2602 C.5.9 Section 5.2.1 2604 - Changed "The LDAPMessage PDUs" to "The encoded LDAPMessage PDUs" 2605 to point out that the PDUs are encoded before being streamed to 2606 TCP. 2608 C.6 Changes made to draft-ietf-ldapbis-protocol-04.txt: 2610 C.6.1 Section 4.5.1 and Appendix A 2612 - Changed the ASN.1 for the and and or choices of Filter to have a 2613 lower range of 1. This was an omission in the original ASN.1 2615 C.6.2 Various 2617 - Fixed various typo's 2619 C.7 Changes made to draft-ietf-ldapbis-protocol-05.txt: 2621 C.7.1 Section 3.2.1 2623 - Added "(as defined in Section 12.4.1 of [X.501])" to the fifth 2624 paragraph when talking about "operational attributes". This is 2625 because the term "operational attributes" is never defined. 2626 Alternately, we could drag a definition into the spec, for now, 2627 I'm just pointing to the reference in X.501. 2629 C.7.2 Section 4.1.5 2631 - Changed "And is also case insensitive" to "The entire 2632 AttributeDescription is case insensitive". This is to clarify 2633 whether we're talking about the entire attribute description, or 2634 just the options. 2636 - Expounded on the definition of attribute description options. This 2637 doc now specifies a difference between transfer and tagging 2638 options and describes the semantics of each, and how and when 2639 subtyping rules apply. Now allow options to be transmitted in any 2640 order but disallow any ordering semantics to be implied. These 2641 changes are the result of ongoing input from an engineering team 2642 designed to deal with ambiguity issues surrounding attribute 2643 options. 2645 C.7.3 Sections 4.1.5.1 and 4.1.6 2647 - Refer to non "binary" transfer encodings as "native encoding" 2648 rather than "string" encoding to clarify and avoid confusion. 2650 C.8 Changes made to draft-ietf-ldapbis-protocol-05.txt: 2652 Lightweight Directory Access Protocol Version 3 2654 C.8.1 Title 2656 - Changed to "LDAP: The Protocol" to be consisted with other working 2657 group documents 2659 C.8.2 Abstract 2661 - Moved above TOC to conform to new guidelines 2663 - Reworded to make consistent with other WG documents. 2665 - Moved 2119 conventions to "Conventions" section 2667 C.8.3 Introduction 2669 - Created to conform to new guidelines 2671 C.8.4 Models 2673 - Removed section. There is only one model in this document 2674 (Protocol Model) 2676 C.8.5 Protocol Model 2678 - Removed antiquated paragraph: "In keeping with the goal of easing 2679 the costs associated with use of the directory, it is an objective 2680 of this protocol to minimize the complexity of clients so as to 2681 facilitate widespread deployment of applications capable of using 2682 the directory." 2684 - Removed antiquated paragraph concerning LDAP v1 and v2 and 2685 referrals. 2687 C.8.6 Data Model 2689 - Removed Section 3.2 and subsections. These have been moved to 2690 [Models] 2692 C.8.7 Relationship to X.500 2694 - Removed section. It has been moved to [Roadmap] 2696 C.8.8 Server Specific Data Requirements 2698 - Removed section. It has been moved to [Models] 2700 C.8.9 Elements of Protocol 2702 - Added "Section 5.1 specifies how the protocol is encoded and 2703 transferred." to the end of the first paragraph for reference. 2705 - Reworded notes about extensibility, and now talk about implied 2706 extensibility and the use of ellipses in the ASN.1 2707 Lightweight Directory Access Protocol Version 3 2709 - Removed references to LDAPv2 in third and fourth paragraphs. 2711 C.8.10 Message ID 2713 - Reworded second paragraph to "The message ID of a request MUST 2714 have a non-zero value different from the values of any other 2715 requests outstanding in the LDAP session of which this message is 2716 a part. The zero value is reserved for the unsolicited 2717 notification message." (Added notes about non-zero and the zero 2718 value). 2720 C.8.11 String Types 2722 - Removed ABNF for LDAPOID and added "Although an LDAPOID is encoded 2723 as an OCTET STRING, values are limited to the definition of 2724 numericoid given in Section 1.3 of [Models]." 2726 C.8.12 Distinguished Name and Relative Distinguished Name 2728 - Removed ABNF and referred to [Models] and [LDAPDN] where this is 2729 defined. 2731 C.8.13 Attribute Type 2733 - Removed sections. It's now in the [Models] doc. 2735 C.8.14 Attribute Description 2737 - Removed ABNF and aligned section with [Models] 2739 - Moved AttributeDescriptionList here. 2741 C.8.15 Transfer Options 2743 - Added section and consumed much of old options language (while 2744 aligning with [Models] 2746 C.8.16 Binary Transfer Option 2748 - Clarified intent regarding exactly what is to be BER encoded. 2750 - Clarified that clients must not expect ;binary when not asking for 2751 it (;binary, as opposed to ber encoded data). 2753 C.8.17 Attribute 2755 - Use the term "attribute description" in lieu of "type" 2757 - Clarified the fact that clients cannot rely on any apparent 2758 ordering of attribute values. 2760 Lightweight Directory Access Protocol Version 3 2762 C.8.18 LDAPResult 2764 - To resultCode, added ellipses "..." to the enumeration to indicate 2765 extensibility. and added a note, pointing to [LDAPIANA] 2767 - Removed error groupings ad refer to Appendix A. 2769 C.8.19 Bind Operation 2771 - Added "Prior to the BindRequest, the implied identity is 2772 anonymous. Refer to [AuthMeth] for the authentication-related 2773 semantics of this operation." to the first paragraph. 2775 - Added ellipses "..." to AuthenticationChoice and added a note 2776 "This type is extensible as defined in Section 3.6 of [LDAPIANA]. 2777 Servers that do not support a choice supplied by a client will 2778 return authMethodNotSupported in the result code of the 2779 BindResponse." 2781 - Simplified text regarding how the server handles unknown versions. 2782 Removed references to LDAPv2 2784 C.8.20 Sequencing of the Bind Request 2786 - Aligned with [AuthMeth] In particular, paragraphs 4 and 6 were 2787 removed, while a portion of 4 was retained (see C.8.9) 2789 C.8.21 Authentication and other Security Service 2791 - Section was removed. Now in [AuthMeth] 2793 C.8.22 Continuation References in the Search Result 2795 - Added "If the originating search scope was singleLevel, the scope 2796 part of the URL will be baseObject." 2798 C.8.23 Security Considerations 2800 - Removed reference to LDAPv2 2802 C.8.24 Result Codes 2804 - Added as normative appendix A 2806 C.8.25 ASN.1 2808 - Added EXTENSIBILITY IMPLIED 2810 - Added a number of comments holding referenced to [Models] and 2811 [ISO10646]. 2813 - Removed AttributeType. It is not used. 2815 Lightweight Directory Access Protocol Version 3 2817 Appendix D - Outstanding Work Items 2819 D.1 Integrate result codes draft. 2821 - The result codes draft should be reconciled with this draft. 2822 Operation-specific instructions will reside with operations while 2823 the error-specific sections will be added as an appendix. Note 2824 that there is a result codes appendix now. Still need to reconcile 2825 with each operation. 2827 D.2 Verify references. 2829 - Many referenced documents have changed. Ensure references and 2830 section numbers are correct. 2832 D.3 Usage of Naming Context 2834 - Make sure occurrences of "namingcontext" and naming context" are 2835 consistent with [Models]. 2837 D.5 Section 4.1.1.1 2839 - Remove "or of the abandoned operation until it has received a 2840 response from the server for another request invoked subsequent to 2841 the abandonRequest," from the fourth paragraph as this imposes 2842 synchronous behavior on the server. 2844 D.9 Section 4.1.5.2 2846 - Add "Servers SHOULD only return attributes with printable string 2847 representations as binary when clients request binary transfer." 2848 to the second paragraph. 2849 - Clarify whether the "binary" attribute type option is to be 2850 treated as a subtype. 2852 D.10 Section 4.1.6 2854 - Change "containing an encoded value of an AttributeValue data 2855 type" to "containing an encoded attribute value data type" 2857 D.11 Section 4.1.7 2859 - Change "For all the string-valued user attributes described in 2860 [5], the assertion value syntax is the same as the value syntax." 2861 to "The assertion value syntax for all attributes using human- 2862 readable syntaxes as described in [RFC2252] is the same as the 2863 value syntax unless otherwise noted (an example being 2864 objectIdentifierFirstComponentMatch)." in the third paragraph. 2865 - Find out what the last sentence in third paragraph means (Clients 2866 may use attributes...) 2868 D.13 Section 4.1.11 2870 - Add "after locating the target entry" to the first paragraph. 2872 Lightweight Directory Access Protocol Version 3 2874 D.14 Section 4.1.12 2876 - Specify whether or not servers are to advertise the OIDs of known 2877 response controls. 2879 D.15 Section 4.2 2881 - Change "LDAPDN" to "identity" in the definition of the name field. 2882 - Rework definition of the name field to enumerate empty password and 2883 name combinations. 2885 D.17 Section 4.2.2 2887 - Add "as the authentication identity" to second paragraph. 2889 D.18 Section 4.2.3 2891 - Change "If the bind was successful, the resultCode will be 2892 success, otherwise it will be one of" to "If the bind was 2893 successful, the resultCode will be success, otherwise it MAY be 2894 one of" in the third paragraph. . 2896 - Change "operationsError" to "other" as a result code. 2897 - Change "If the client bound with the password choice" to "If the 2898 client bound with the simple choice" in the last paragraph. 2900 D.19 Section 4.3 2902 - Change "a protocol client may assume that the protocol session is 2903 terminated and MAY close the connection." to "a protocol client 2904 MUST assume that the protocol session is terminated and MAY close 2905 the connection." in the second paragraph. 2906 - Change "a protocol server may assume" to "a protocol server MUST 2907 assume" in the second paragraph. 2908 - Change "and may close the connection" to "and MUST close the 2909 connection" in the second paragraph. 2911 D.20 Section 4.4 2913 - Add "Servers SHOULD NOT assume LDAPv3 clients understand or 2914 recognize unsolicited notifications or unsolicited controls other 2915 than Notice of Disconnection defined below. Servers SHOULD avoid 2916 sending unsolicited notifications unless they know (by related 2917 request or other means) that the client can make use of the 2918 notification." as a fourth paragraph. 2920 D.21 Section 4.5.1 2922 - Make sure the use of "subordinates" in the derefInSearching 2923 definition is correct. See "derefInSearching" on list. 2925 D.22 Section 4.5.2 2926 Lightweight Directory Access Protocol Version 3 2928 - Add "associated with a search operation" to the sixth paragraph. 2929 - Same problem as in D.5. 2931 D.23 Section 4.5.3 2933 - Add "Similarly, a server MUST NOT return a SearchResultReference 2934 when the scope of the search is baseObject. If a client receives 2935 such a SearchResultReference it MUST interpret is as a protocol 2936 error and MUST NOT follow it." to the first paragraph. 2937 - Add "If the scope part of the LDAP URL is present, the client MUST 2938 use the new scope in its next request to progress the search. If 2939 the scope part is absent the client MUST use subtree scope to 2940 complete subtree searches and base scope to complete one level 2941 searches." to the third paragraph. 2943 D.24 Section 4.5.3.1 2945 - Change examples to use dc naming. 2947 D.25 Section 4.6 2949 - Resolve the meaning of "and is ignored if the attribute does not 2950 exist". See "modify: "non-existent attribute"" on the list. 2952 D.26 Section 4.7 2954 - Change examples to use dc naming. 2955 - Clarify the paragraph that talks about structure rules. See 2956 "discussing structure rules" on the list. 2958 D.27 Section 4.10 2960 - Specify what happens when the attr is missing vs. attr isn't in 2961 schema. Also what happens if there's no equality matching rule. 2963 D.28 Section 4.11 2965 - Change "(since these may have been in transit when the abandon was 2966 requested)." to "(since these may either have been in transit when 2967 the abandon was requested, or are not able to be abandoned)." in 2968 the fifth paragraph. 2969 - Add "Abandon and Unbind operations are not able to be abandoned. 2970 Other operations, in particular update operations, or operations 2971 that have been chained, may not be abandonable (or immediately 2972 abandonable)." as the sixth paragraph. 2974 D.29 Section 4.12 2976 - Change "digitally signed operations and results" to "for instance 2977 StartTLS [RFC2830]" 2979 D.30 Section 5.1 2980 Lightweight Directory Access Protocol Version 3 2982 - Add "control and extended operation values" to last paragraph. See 2983 "LBER (BER Restrictions)" on list. 2985 D.31 Section 5.2.1 2987 - Add "using the BER-based described in section 5.1". 2989 D.32 Section 6.1 2991 - Add "that are used by those attributes" to the first paragraph. 2992 - Add "Servers which support update operations MUST, and other 2993 servers SHOULD, support strong authentication mechanisms described 2994 in [RFC2829]." as a second paragraph. 2995 - Add "Servers which provide access to sensitive information MUST, 2996 and other servers SHOULD support privacy protections such as those 2997 described in [RFC2829] and [RFC2830]." as a third paragraph. 2999 D.33 Section 7 3001 - Add "Servers which support update operations MUST, and other 3002 servers SHOULD, support strong authentication mechanisms described 3003 in [RFC2829]." as a fourth paragraph. 3004 - Add "In order to automatically follow referrals, clients may need 3005 to hold authentication secrets. This poses significant privacy and 3006 security concerns and SHOULD be avoided." as a sixth paragraph. 3007 - Add "This document provides a mechanism which clients may use to 3008 discover operational attributes. Those relying on security by 3009 obscurity should implement appropriate access controls to 3010 restricts access to operational attributes per local policy." as 3011 an eighth paragraph. 3012 - Add "This document provides a mechanism which clients may use to 3013 discover operational attributes. Those relying on security by 3014 obscurity should implement appropriate access controls to 3015 restricts access to operational attributes per local policy." as 3016 an eighth paragraph. 3018 Lightweight Directory Access Protocol Version 3 3020 Full Copyright Statement 3022 Copyright (C) The Internet Society (2002). All Rights Reserved. 3024 This document and translations of it may be copied and furnished to 3025 others, and derivative works that comment on or otherwise explain it 3026 or assist in its implementation may be prepared, copied, published 3027 and distributed, in whole or in part, without restriction of any 3028 kind, provided that the above copyright notice and this paragraph are 3029 included on all such copies and derivative works. However, this 3030 document itself may not be modified in any way, such as by removing 3031 the copyright notice or references to the Internet Society or other 3032 Internet organizations, except as needed for the purpose of 3033 developing Internet standards in which case the procedures for 3034 copyrights defined in the Internet Standards process must be 3035 followed, or as required to translate it into languages other than 3036 English. 3038 The limited permissions granted above are perpetual and will not be 3039 revoked by the Internet Society or its successors or assigns. 3041 This document and the information contained herein is provided on an 3042 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 3043 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 3044 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 3045 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 3046 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.