1 2 3 4 5 6 7Network Working Group J. Sermersheim, Ed. 8Request for Comments: 4511 Novell, Inc. 9Obsoletes: 2251, 2830, 3771 June 2006 10Category: Standards Track 11 12 13 Lightweight Directory Access Protocol (LDAP): The Protocol 14 15Status of This Memo 16 17 This document specifies an Internet standards track protocol for the 18 Internet community, and requests discussion and suggestions for 19 improvements. Please refer to the current edition of the "Internet 20 Official Protocol Standards" (STD 1) for the standardization state 21 and status of this protocol. Distribution of this memo is unlimited. 22 23Copyright Notice 24 25 Copyright (C) The Internet Society (2006). 26 27Abstract 28 29 This document describes the protocol elements, along with their 30 semantics and encodings, of the Lightweight Directory Access Protocol 31 (LDAP). LDAP provides access to distributed directory services that 32 act in accordance with X.500 data and service models. These protocol 33 elements are based on those described in the X.500 Directory Access 34 Protocol (DAP). 35 36Table of Contents 37 38 1. Introduction ....................................................3 39 1.1. Relationship to Other LDAP Specifications ..................3 40 2. Conventions .....................................................3 41 3. Protocol Model ..................................................4 42 3.1. Operation and LDAP Message Layer Relationship ..............5 43 4. Elements of Protocol ............................................5 44 4.1. Common Elements ............................................5 45 4.1.1. Message Envelope ....................................6 46 4.1.2. String Types ........................................7 47 4.1.3. Distinguished Name and Relative Distinguished Name ..8 48 4.1.4. Attribute Descriptions ..............................8 49 4.1.5. Attribute Value .....................................8 50 4.1.6. Attribute Value Assertion ...........................9 51 4.1.7. Attribute and PartialAttribute ......................9 52 4.1.8. Matching Rule Identifier ...........................10 53 4.1.9. Result Message .....................................10 54 4.1.10. Referral ..........................................12 55 56 57 58Sermersheim Standards Track [Page 1] 59 60RFC 4511 LDAPv3 June 2006 61 62 63 4.1.11. Controls ..........................................14 64 4.2. Bind Operation ............................................16 65 4.2.1. Processing of the Bind Request .....................17 66 4.2.2. Bind Response ......................................18 67 4.3. Unbind Operation ..........................................18 68 4.4. Unsolicited Notification ..................................19 69 4.4.1. Notice of Disconnection ............................19 70 4.5. Search Operation ..........................................20 71 4.5.1. Search Request .....................................20 72 4.5.2. Search Result ......................................27 73 4.5.3. Continuation References in the Search Result .......28 74 4.6. Modify Operation ..........................................31 75 4.7. Add Operation .............................................33 76 4.8. Delete Operation ..........................................34 77 4.9. Modify DN Operation .......................................34 78 4.10. Compare Operation ........................................36 79 4.11. Abandon Operation ........................................36 80 4.12. Extended Operation .......................................37 81 4.13. IntermediateResponse Message .............................39 82 4.13.1. Usage with LDAP ExtendedRequest and 83 ExtendedResponse ..................................40 84 4.13.2. Usage with LDAP Request Controls ..................40 85 4.14. StartTLS Operation .......................................40 86 4.14.1. StartTLS Request ..................................40 87 4.14.2. StartTLS Response .................................41 88 4.14.3. Removal of the TLS Layer ..........................41 89 5. Protocol Encoding, Connection, and Transfer ....................42 90 5.1. Protocol Encoding .........................................42 91 5.2. Transmission Control Protocol (TCP) .......................43 92 5.3. Termination of the LDAP session ...........................43 93 6. Security Considerations ........................................43 94 7. Acknowledgements ...............................................45 95 8. Normative References ...........................................46 96 9. Informative References .........................................48 97 10. IANA Considerations ...........................................48 98 Appendix A. LDAP Result Codes .....................................49 99 A.1. Non-Error Result Codes ....................................49 100 A.2. Result Codes ..............................................49 101 Appendix B. Complete ASN.1 Definition .............................54 102 Appendix C. Changes ...............................................60 103 C.1. Changes Made to RFC 2251 ..................................60 104 C.2. Changes Made to RFC 2830 ..................................66 105 C.3. Changes Made to RFC 3771 ..................................66 106 107 108 109 110 111 112 113 114Sermersheim Standards Track [Page 2] 115 116RFC 4511 LDAPv3 June 2006 117 118 1191. Introduction 120 121 The Directory is "a collection of open systems cooperating to provide 122 directory services" [X.500]. A directory user, which may be a human 123 or other entity, accesses the Directory through a client (or 124 Directory User Agent (DUA)). The client, on behalf of the directory 125 user, interacts with one or more servers (or Directory System Agents 126 (DSA)). Clients interact with servers using a directory access 127 protocol. 128 129 This document details the protocol elements of the Lightweight 130 Directory Access Protocol (LDAP), along with their semantics. 131 Following the description of protocol elements, it describes the way 132 in which the protocol elements are encoded and transferred. 133 1341.1. Relationship to Other LDAP Specifications 135 136 This document is an integral part of the LDAP Technical Specification 137 [RFC4510], which obsoletes the previously defined LDAP technical 138 specification, RFC 3377, in its entirety. 139 140 This document, together with [RFC4510], [RFC4513], and [RFC4512], 141 obsoletes RFC 2251 in its entirety. Section 3.3 is obsoleted by 142 [RFC4510]. Sections 4.2.1 (portions) and 4.2.2 are obsoleted by 143 [RFC4513]. Sections 3.2, 3.4, 4.1.3 (last paragraph), 4.1.4, 4.1.5, 144 4.1.5.1, 4.1.9 (last paragraph), 5.1, 6.1, and 6.2 (last paragraph) 145 are obsoleted by [RFC4512]. The remainder of RFC 2251 is obsoleted 146 by this document. Appendix C.1 summarizes substantive changes in the 147 remainder. 148 149 This document obsoletes RFC 2830, Sections 2 and 4. The remainder of 150 RFC 2830 is obsoleted by [RFC4513]. Appendix C.2 summarizes 151 substantive changes to the remaining sections. 152 153 This document also obsoletes RFC 3771 in entirety. 154 1552. Conventions 156 157 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 158 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are 159 to be interpreted as described in [RFC2119]. 160 161 Character names in this document use the notation for code points and 162 names from the Unicode Standard [Unicode]. For example, the letter 163 "a" may be represented as either <U+0061> or <LATIN SMALL LETTER A>. 164 165 166 167 168 169 170Sermersheim Standards Track [Page 3] 171 172RFC 4511 LDAPv3 June 2006 173 174 175 Note: a glossary of terms used in Unicode can be found in [Glossary]. 176 Information on the Unicode character encoding model can be found in 177 [CharModel]. 178 179 The term "transport connection" refers to the underlying transport 180 services used to carry the protocol exchange, as well as associations 181 established by these services. 182 183 The term "TLS layer" refers to Transport Layer Security (TLS) 184 services used in providing security services, as well as associations 185 established by these services. 186 187 The term "SASL layer" refers to Simply Authentication and Security 188 Layer (SASL) services used in providing security services, as well as 189 associations established by these services. 190 191 The term "LDAP message layer" refers to the LDAP Message Protocol 192 Data Unit (PDU) services used in providing directory services, as 193 well as associations established by these services. 194 195 The term "LDAP session" refers to combined services (transport 196 connection, TLS layer, SASL layer, LDAP message layer) and their 197 associations. 198 199 See the table in Section 5 for an illustration of these four terms. 200 2013. Protocol Model 202 203 The general model adopted by this protocol is one of clients 204 performing protocol operations against servers. In this model, a 205 client transmits a protocol request describing the operation to be 206 performed to a server. The server is then responsible for performing 207 the necessary operation(s) in the Directory. Upon completion of an 208 operation, the server typically returns a response containing 209 appropriate data to the requesting client. 210 211 Protocol operations are generally independent of one another. Each 212 operation is processed as an atomic action, leaving the directory in 213 a consistent state. 214 215 Although servers are required to return responses whenever such 216 responses are defined in the protocol, there is no requirement for 217 synchronous behavior on the part of either clients or servers. 218 Requests and responses for multiple operations generally may be 219 exchanged between a client and server in any order. If required, 220 synchronous behavior may be controlled by client applications. 221 222 223 224 225 226Sermersheim Standards Track [Page 4] 227 228RFC 4511 LDAPv3 June 2006 229 230 231 The core protocol operations defined in this document can be mapped 232 to a subset of the X.500 (1993) Directory Abstract Service [X.511]. 233 However, there is not a one-to-one mapping between LDAP operations 234 and X.500 Directory Access Protocol (DAP) operations. Server 235 implementations acting as a gateway to X.500 directories may need to 236 make multiple DAP requests to service a single LDAP request. 237 2383.1. Operation and LDAP Message Layer Relationship 239 240 Protocol operations are exchanged at the LDAP message layer. When 241 the transport connection is closed, any uncompleted operations at the 242 LDAP message layer are abandoned (when possible) or are completed 243 without transmission of the response (when abandoning them is not 244 possible). Also, when the transport connection is closed, the client 245 MUST NOT assume that any uncompleted update operations have succeeded 246 or failed. 247 2484. Elements of Protocol 249 250 The protocol is described using Abstract Syntax Notation One 251 ([ASN.1]) and is transferred using a subset of ASN.1 Basic Encoding 252 Rules ([BER]). Section 5 specifies how the protocol elements are 253 encoded and transferred. 254 255 In order to support future extensions to this protocol, extensibility 256 is implied where it is allowed per ASN.1 (i.e., sequence, set, 257 choice, and enumerated types are extensible). In addition, ellipses 258 (...) have been supplied in ASN.1 types that are explicitly 259 extensible as discussed in [RFC4520]. Because of the implied 260 extensibility, clients and servers MUST (unless otherwise specified) 261 ignore trailing SEQUENCE components whose tags they do not recognize. 262 263 Changes to the protocol other than through the extension mechanisms 264 described here require a different version number. A client 265 indicates the version it is using as part of the BindRequest, 266 described in Section 4.2. If a client has not sent a Bind, the 267 server MUST assume the client is using version 3 or later. 268 269 Clients may attempt to determine the protocol versions a server 270 supports by reading the 'supportedLDAPVersion' attribute from the 271 root DSE (DSA-Specific Entry) [RFC4512]. 272 2734.1. Common Elements 274 275 This section describes the LDAPMessage envelope Protocol Data Unit 276 (PDU) format, as well as data type definitions, which are used in the 277 protocol operations. 278 279 280 281 282Sermersheim Standards Track [Page 5] 283 284RFC 4511 LDAPv3 June 2006 285 286 2874.1.1. Message Envelope 288 289 For the purposes of protocol exchanges, all protocol operations are 290 encapsulated in a common envelope, the LDAPMessage, which is defined 291 as follows: 292 293 LDAPMessage ::= SEQUENCE { 294 messageID MessageID, 295 protocolOp CHOICE { 296 bindRequest BindRequest, 297 bindResponse BindResponse, 298 unbindRequest UnbindRequest, 299 searchRequest SearchRequest, 300 searchResEntry SearchResultEntry, 301 searchResDone SearchResultDone, 302 searchResRef SearchResultReference, 303 modifyRequest ModifyRequest, 304 modifyResponse ModifyResponse, 305 addRequest AddRequest, 306 addResponse AddResponse, 307 delRequest DelRequest, 308 delResponse DelResponse, 309 modDNRequest ModifyDNRequest, 310 modDNResponse ModifyDNResponse, 311 compareRequest CompareRequest, 312 compareResponse CompareResponse, 313 abandonRequest AbandonRequest, 314 extendedReq ExtendedRequest, 315 extendedResp ExtendedResponse, 316 ..., 317 intermediateResponse IntermediateResponse }, 318 controls [0] Controls OPTIONAL } 319 320 MessageID ::= INTEGER (0 .. maxInt) 321 322 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) -- 323 324 The ASN.1 type Controls is defined in Section 4.1.11. 325 326 The function of the LDAPMessage is to provide an envelope containing 327 common fields required in all protocol exchanges. At this time, the 328 only common fields are the messageID and the controls. 329 330 If the server receives an LDAPMessage from the client in which the 331 LDAPMessage SEQUENCE tag cannot be recognized, the messageID cannot 332 be parsed, the tag of the protocolOp is not recognized as a request, 333 or the encoding structures or lengths of data fields are found to be 334 incorrect, then the server SHOULD return the Notice of Disconnection 335 336 337 338Sermersheim Standards Track [Page 6] 339 340RFC 4511 LDAPv3 June 2006 341 342 343 described in Section 4.4.1, with the resultCode set to protocolError, 344 and MUST immediately terminate the LDAP session as described in 345 Section 5.3. 346 347 In other cases where the client or server cannot parse an LDAP PDU, 348 it SHOULD abruptly terminate the LDAP session (Section 5.3) where 349 further communication (including providing notice) would be 350 pernicious. Otherwise, server implementations MUST return an 351 appropriate response to the request, with the resultCode set to 352 protocolError. 353 3544.1.1.1. MessageID 355 356 All LDAPMessage envelopes encapsulating responses contain the 357 messageID value of the corresponding request LDAPMessage. 358 359 The messageID of a request MUST have a non-zero value different from 360 the messageID of any other request in progress in the same LDAP 361 session. The zero value is reserved for the unsolicited notification 362 message. 363 364 Typical clients increment a counter for each request. 365 366 A client MUST NOT send a request with the same messageID as an 367 earlier request in the same LDAP session unless it can be determined 368 that the server is no longer servicing the earlier request (e.g., 369 after the final response is received, or a subsequent Bind 370 completes). Otherwise, the behavior is undefined. For this purpose, 371 note that Abandon and successfully abandoned operations do not send 372 responses. 373 3744.1.2. String Types 375 376 The LDAPString is a notational convenience to indicate that, although 377 strings of LDAPString type encode as ASN.1 OCTET STRING types, the 378 [ISO10646] character set (a superset of [Unicode]) is used, encoded 379 following the UTF-8 [RFC3629] algorithm. Note that Unicode 380 characters U+0000 through U+007F are the same as ASCII 0 through 127, 381 respectively, and have the same single octet UTF-8 encoding. Other 382 Unicode characters have a multiple octet UTF-8 encoding. 383 384 LDAPString ::= OCTET STRING -- UTF-8 encoded, 385 -- [ISO10646] characters 386 387 The LDAPOID is a notational convenience to indicate that the 388 permitted value of this string is a (UTF-8 encoded) dotted-decimal 389 representation of an OBJECT IDENTIFIER. Although an LDAPOID is 390 391 392 393 394Sermersheim Standards Track [Page 7] 395 396RFC 4511 LDAPv3 June 2006 397 398 399 encoded as an OCTET STRING, values are limited to the definition of 400 <numericoid> given in Section 1.4 of [RFC4512]. 401 402 LDAPOID ::= OCTET STRING -- Constrained to <numericoid> 403 -- [RFC4512] 404 405 For example, 406 407 1.3.6.1.4.1.1466.1.2.3 408 4094.1.3. Distinguished Name and Relative Distinguished Name 410 411 An LDAPDN is defined to be the representation of a Distinguished Name 412 (DN) after encoding according to the specification in [RFC4514]. 413 414 LDAPDN ::= LDAPString 415 -- Constrained to <distinguishedName> [RFC4514] 416 417 A RelativeLDAPDN is defined to be the representation of a Relative 418 Distinguished Name (RDN) after encoding according to the 419 specification in [RFC4514]. 420 421 RelativeLDAPDN ::= LDAPString 422 -- Constrained to <name-component> [RFC4514] 423 4244.1.4. Attribute Descriptions 425 426 The definition and encoding rules for attribute descriptions are 427 defined in Section 2.5 of [RFC4512]. Briefly, an attribute 428 description is an attribute type and zero or more options. 429 430 AttributeDescription ::= LDAPString 431 -- Constrained to <attributedescription> 432 -- [RFC4512] 433 4344.1.5. Attribute Value 435 436 A field of type AttributeValue is an OCTET STRING containing an 437 encoded attribute value. The attribute value is encoded according to 438 the LDAP-specific encoding definition of its corresponding syntax. 439 The LDAP-specific encoding definitions for different syntaxes and 440 attribute types may be found in other documents and in particular 441 [RFC4517]. 442 443 AttributeValue ::= OCTET STRING 444 445 446 447 448 449 450Sermersheim Standards Track [Page 8] 451 452RFC 4511 LDAPv3 June 2006 453 454 455 Note that there is no defined limit on the size of this encoding; 456 thus, protocol values may include multi-megabyte attribute values 457 (e.g., photographs). 458 459 Attribute values may be defined that have arbitrary and non-printable 460 syntax. Implementations MUST NOT display or attempt to decode an 461 attribute value if its syntax is not known. The implementation may 462 attempt to discover the subschema of the source entry and to retrieve 463 the descriptions of 'attributeTypes' from it [RFC4512]. 464 465 Clients MUST only send attribute values in a request that are valid 466 according to the syntax defined for the attributes. 467 4684.1.6. Attribute Value Assertion 469 470 The AttributeValueAssertion (AVA) type definition is similar to the 471 one in the X.500 Directory standards. It contains an attribute 472 description and a matching rule ([RFC4512], Section 4.1.3) assertion 473 value suitable for that type. Elements of this type are typically 474 used to assert that the value in assertionValue matches a value of an 475 attribute. 476 477 AttributeValueAssertion ::= SEQUENCE { 478 attributeDesc AttributeDescription, 479 assertionValue AssertionValue } 480 481 AssertionValue ::= OCTET STRING 482 483 The syntax of the AssertionValue depends on the context of the LDAP 484 operation being performed. For example, the syntax of the EQUALITY 485 matching rule for an attribute is used when performing a Compare 486 operation. Often this is the same syntax used for values of the 487 attribute type, but in some cases the assertion syntax differs from 488 the value syntax. See objectIdentiferFirstComponentMatch in 489 [RFC4517] for an example. 490 4914.1.7. Attribute and PartialAttribute 492 493 Attributes and partial attributes consist of an attribute description 494 and attribute values. A PartialAttribute allows zero values, while 495 Attribute requires at least one value. 496 497 PartialAttribute ::= SEQUENCE { 498 type AttributeDescription, 499 vals SET OF value AttributeValue } 500 501 502 503 504 505 506Sermersheim Standards Track [Page 9] 507 508RFC 4511 LDAPv3 June 2006 509 510 511 Attribute ::= PartialAttribute(WITH COMPONENTS { 512 ..., 513 vals (SIZE(1..MAX))}) 514 515 No two of the attribute values may be equivalent as described by 516 Section 2.2 of [RFC4512]. The set of attribute values is unordered. 517 Implementations MUST NOT rely upon the ordering being repeatable. 518 5194.1.8. Matching Rule Identifier 520 521 Matching rules are defined in Section 4.1.3 of [RFC4512]. A matching 522 rule is identified in the protocol by the printable representation of 523 either its <numericoid> or one of its short name descriptors 524 [RFC4512], e.g., 'caseIgnoreMatch' or '2.5.13.2'. 525 526 MatchingRuleId ::= LDAPString 527 5284.1.9. Result Message 529 530 The LDAPResult is the construct used in this protocol to return 531 success or failure indications from servers to clients. To various 532 requests, servers will return responses containing the elements found 533 in LDAPResult to indicate the final status of the protocol operation 534 request. 535 536 LDAPResult ::= SEQUENCE { 537 resultCode ENUMERATED { 538 success (0), 539 operationsError (1), 540 protocolError (2), 541 timeLimitExceeded (3), 542 sizeLimitExceeded (4), 543 compareFalse (5), 544 compareTrue (6), 545 authMethodNotSupported (7), 546 strongerAuthRequired (8), 547 -- 9 reserved -- 548 referral (10), 549 adminLimitExceeded (11), 550 unavailableCriticalExtension (12), 551 confidentialityRequired (13), 552 saslBindInProgress (14), 553 noSuchAttribute (16), 554 undefinedAttributeType (17), 555 inappropriateMatching (18), 556 constraintViolation (19), 557 attributeOrValueExists (20), 558 invalidAttributeSyntax (21), 559 560 561 562Sermersheim Standards Track [Page 10] 563 564RFC 4511 LDAPv3 June 2006 565 566 567 -- 22-31 unused -- 568 noSuchObject (32), 569 aliasProblem (33), 570 invalidDNSyntax (34), 571 -- 35 reserved for undefined isLeaf -- 572 aliasDereferencingProblem (36), 573 -- 37-47 unused -- 574 inappropriateAuthentication (48), 575 invalidCredentials (49), 576 insufficientAccessRights (50), 577 busy (51), 578 unavailable (52), 579 unwillingToPerform (53), 580 loopDetect (54), 581 -- 55-63 unused -- 582 namingViolation (64), 583 objectClassViolation (65), 584 notAllowedOnNonLeaf (66), 585 notAllowedOnRDN (67), 586 entryAlreadyExists (68), 587 objectClassModsProhibited (69), 588 -- 70 reserved for CLDAP -- 589 affectsMultipleDSAs (71), 590 -- 72-79 unused -- 591 other (80), 592 ... }, 593 matchedDN LDAPDN, 594 diagnosticMessage LDAPString, 595 referral [3] Referral OPTIONAL } 596 597 The resultCode enumeration is extensible as defined in Section 3.8 of 598 [RFC4520]. The meanings of the listed result codes are given in 599 Appendix A. If a server detects multiple errors for an operation, 600 only one result code is returned. The server should return the 601 result code that best indicates the nature of the error encountered. 602 Servers may return substituted result codes to prevent unauthorized 603 disclosures. 604 605 The diagnosticMessage field of this construct may, at the server's 606 option, be used to return a string containing a textual, human- 607 readable diagnostic message (terminal control and page formatting 608 characters should be avoided). As this diagnostic message is not 609 standardized, implementations MUST NOT rely on the values returned. 610 Diagnostic messages typically supplement the resultCode with 611 additional information. If the server chooses not to return a 612 textual diagnostic, the diagnosticMessage field MUST be empty. 613 614 615 616 617 618Sermersheim Standards Track [Page 11] 619 620RFC 4511 LDAPv3 June 2006 621 622 623 For certain result codes (typically, but not restricted to 624 noSuchObject, aliasProblem, invalidDNSyntax, and 625 aliasDereferencingProblem), the matchedDN field is set (subject to 626 access controls) to the name of the last entry (object or alias) used 627 in finding the target (or base) object. This will be a truncated 628 form of the provided name or, if an alias was dereferenced while 629 attempting to locate the entry, of the resulting name. Otherwise, 630 the matchedDN field is empty. 631 6324.1.10. Referral 633 634 The referral result code indicates that the contacted server cannot 635 or will not perform the operation and that one or more other servers 636 may be able to. Reasons for this include: 637 638 - The target entry of the request is not held locally, but the server 639 has knowledge of its possible existence elsewhere. 640 641 - The operation is restricted on this server -- perhaps due to a 642 read-only copy of an entry to be modified. 643 644 The referral field is present in an LDAPResult if the resultCode is 645 set to referral, and it is absent with all other result codes. It 646 contains one or more references to one or more servers or services 647 that may be accessed via LDAP or other protocols. Referrals can be 648 returned in response to any operation request (except Unbind and 649 Abandon, which do not have responses). At least one URI MUST be 650 present in the Referral. 651 652 During a Search operation, after the baseObject is located, and 653 entries are being evaluated, the referral is not returned. Instead, 654 continuation references, described in Section 4.5.3, are returned 655 when other servers would need to be contacted to complete the 656 operation. 657 658 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI 659 660 URI ::= LDAPString -- limited to characters permitted in 661 -- URIs 662 663 If the client wishes to progress the operation, it contacts one of 664 the supported services found in the referral. If multiple URIs are 665 present, the client assumes that any supported URI may be used to 666 progress the operation. 667 668 Clients that follow referrals MUST ensure that they do not loop 669 between servers. They MUST NOT repeatedly contact the same server 670 for the same request with the same parameters. Some clients use a 671 672 673 674Sermersheim Standards Track [Page 12] 675 676RFC 4511 LDAPv3 June 2006 677 678 679 counter that is incremented each time referral handling occurs for an 680 operation, and these kinds of clients MUST be able to handle at least 681 ten nested referrals while progressing the operation. 682 683 A URI for a server implementing LDAP and accessible via TCP/IP (v4 or 684 v6) [RFC793][RFC791] is written as an LDAP URL according to 685 [RFC4516]. 686 687 Referral values that are LDAP URLs follow these rules: 688 689 - If an alias was dereferenced, the <dn> part of the LDAP URL MUST be 690 present, with the new target object name. 691 692 - It is RECOMMENDED that the <dn> part be present to avoid ambiguity. 693 694 - If the <dn> part is present, the client uses this name in its next 695 request to progress the operation, and if it is not present the 696 client uses the same name as in the original request. 697 698 - Some servers (e.g., participating in distributed indexing) may 699 provide a different filter in a URL of a referral for a Search 700 operation. 701 702 - If the <filter> part of the LDAP URL is present, the client uses 703 this filter in its next request to progress this Search, and if it 704 is not present the client uses the same filter as it used for that 705 Search. 706 707 - For Search, it is RECOMMENDED that the <scope> part be present to 708 avoid ambiguity. 709 710 - If the <scope> part is missing, the scope of the original Search is 711 used by the client to progress the operation. 712 713 - Other aspects of the new request may be the same as or different 714 from the request that generated the referral. 715 716 Other kinds of URIs may be returned. The syntax and semantics of 717 such URIs is left to future specifications. Clients may ignore URIs 718 that they do not support. 719 720 UTF-8 encoded characters appearing in the string representation of a 721 DN, search filter, or other fields of the referral value may not be 722 legal for URIs (e.g., spaces) and MUST be escaped using the % method 723 in [RFC3986]. 724 725 726 727 728 729 730Sermersheim Standards Track [Page 13] 731 732RFC 4511 LDAPv3 June 2006 733 734 7354.1.11. Controls 736 737 Controls provide a mechanism whereby the semantics and arguments of 738 existing LDAP operations may be extended. One or more controls may 739 be attached to a single LDAP message. A control only affects the 740 semantics of the message it is attached to. 741 742 Controls sent by clients are termed 'request controls', and those 743 sent by servers are termed 'response controls'. 744 745 Controls ::= SEQUENCE OF control Control 746 747 Control ::= SEQUENCE { 748 controlType LDAPOID, 749 criticality BOOLEAN DEFAULT FALSE, 750 controlValue OCTET STRING OPTIONAL } 751 752 The controlType field is the dotted-decimal representation of an 753 OBJECT IDENTIFIER that uniquely identifies the control. This 754 provides unambiguous naming of controls. Often, response control(s) 755 solicited by a request control share controlType values with the 756 request control. 757 758 The criticality field only has meaning in controls attached to 759 request messages (except UnbindRequest). For controls attached to 760 response messages and the UnbindRequest, the criticality field SHOULD 761 be FALSE, and MUST be ignored by the receiving protocol peer. A 762 value of TRUE indicates that it is unacceptable to perform the 763 operation without applying the semantics of the control. 764 Specifically, the criticality field is applied as follows: 765 766 - If the server does not recognize the control type, determines that 767 it is not appropriate for the operation, or is otherwise unwilling 768 to perform the operation with the control, and if the criticality 769 field is TRUE, the server MUST NOT perform the operation, and for 770 operations that have a response message, it MUST return with the 771 resultCode set to unavailableCriticalExtension. 772 773 - If the server does not recognize the control type, determines that 774 it is not appropriate for the operation, or is otherwise unwilling 775 to perform the operation with the control, and if the criticality 776 field is FALSE, the server MUST ignore the control. 777 778 - Regardless of criticality, if a control is applied to an 779 operation, it is applied consistently and impartially to the 780 entire operation. 781 782 783 784 785 786Sermersheim Standards Track [Page 14] 787 788RFC 4511 LDAPv3 June 2006 789 790 791 The controlValue may contain information associated with the 792 controlType. Its format is defined by the specification of the 793 control. Implementations MUST be prepared to handle arbitrary 794 contents of the controlValue octet string, including zero bytes. It 795 is absent only if there is no value information that is associated 796 with a control of its type. When a controlValue is defined in terms 797 of ASN.1, and BER-encoded according to Section 5.1, it also follows 798 the extensibility rules in Section 4. 799 800 Servers list the controlType of request controls they recognize in 801 the 'supportedControl' attribute in the root DSE (Section 5.1 of 802 [RFC4512]). 803 804 Controls SHOULD NOT be combined unless the semantics of the 805 combination has been specified. The semantics of control 806 combinations, if specified, are generally found in the control 807 specification most recently published. When a combination of 808 controls is encountered whose semantics are invalid, not specified 809 (or not known), the message is considered not well-formed; thus, the 810 operation fails with protocolError. Controls with a criticality of 811 FALSE may be ignored in order to arrive at a valid combination. 812 Additionally, unless order-dependent semantics are given in a 813 specification, the order of a combination of controls in the SEQUENCE 814 is ignored. Where the order is to be ignored but cannot be ignored 815 by the server, the message is considered not well-formed, and the 816 operation fails with protocolError. Again, controls with a 817 criticality of FALSE may be ignored in order to arrive at a valid 818 combination. 819 820 This document does not specify any controls. Controls may be 821 specified in other documents. Documents detailing control extensions 822 are to provide for each control: 823 824 - the OBJECT IDENTIFIER assigned to the control, 825 826 - direction as to what value the sender should provide for the 827 criticality field (note: the semantics of the criticality field are 828 defined above should not be altered by the control's 829 specification), 830 831 - whether the controlValue field is present, and if so, the format of 832 its contents, 833 834 - the semantics of the control, and 835 836 - optionally, semantics regarding the combination of the control with 837 other controls. 838 839 840 841 842Sermersheim Standards Track [Page 15] 843 844RFC 4511 LDAPv3 June 2006 845 846 8474.2. Bind Operation 848 849 The function of the Bind operation is to allow authentication 850 information to be exchanged between the client and server. The Bind 851 operation should be thought of as the "authenticate" operation. 852 Operational, authentication, and security-related semantics of this 853 operation are given in [RFC4513]. 854 855 The Bind request is defined as follows: 856 857 BindRequest ::= [APPLICATION 0] SEQUENCE { 858 version INTEGER (1 .. 127), 859 name LDAPDN, 860 authentication AuthenticationChoice } 861 862 AuthenticationChoice ::= CHOICE { 863 simple [0] OCTET STRING, 864 -- 1 and 2 reserved 865 sasl [3] SaslCredentials, 866 ... } 867 868 SaslCredentials ::= SEQUENCE { 869 mechanism LDAPString, 870 credentials OCTET STRING OPTIONAL } 871 872 Fields of the BindRequest are: 873 874 - version: A version number indicating the version of the protocol to 875 be used at the LDAP message layer. This document describes version 876 3 of the protocol. There is no version negotiation. The client 877 sets this field to the version it desires. If the server does not 878 support the specified version, it MUST respond with a BindResponse 879 where the resultCode is set to protocolError. 880 881 - name: If not empty, the name of the Directory object that the 882 client wishes to bind as. This field may take on a null value (a 883 zero-length string) for the purposes of anonymous binds ([RFC4513], 884 Section 5.1) or when using SASL [RFC4422] authentication 885 ([RFC4513], Section 5.2). Where the server attempts to locate the 886 named object, it SHALL NOT perform alias dereferencing. 887 888 - authentication: Information used in authentication. This type is 889 extensible as defined in Section 3.7 of [RFC4520]. Servers that do 890 not support a choice supplied by a client return a BindResponse 891 with the resultCode set to authMethodNotSupported. 892 893 894 895 896 897 898Sermersheim Standards Track [Page 16] 899 900RFC 4511 LDAPv3 June 2006 901 902 903 Textual passwords (consisting of a character sequence with a known 904 character set and encoding) transferred to the server using the 905 simple AuthenticationChoice SHALL be transferred as UTF-8 [RFC3629] 906 encoded [Unicode]. Prior to transfer, clients SHOULD prepare text 907 passwords as "query" strings by applying the SASLprep [RFC4013] 908 profile of the stringprep [RFC3454] algorithm. Passwords 909 consisting of other data (such as random octets) MUST NOT be 910 altered. The determination of whether a password is textual is a 911 local client matter. 912 9134.2.1. Processing of the Bind Request 914 915 Before processing a BindRequest, all uncompleted operations MUST 916 either complete or be abandoned. The server may either wait for the 917 uncompleted operations to complete, or abandon them. The server then 918 proceeds to authenticate the client in either a single-step or 919 multi-step Bind process. Each step requires the server to return a 920 BindResponse to indicate the status of authentication. 921 922 After sending a BindRequest, clients MUST NOT send further LDAP PDUs 923 until receiving the BindResponse. Similarly, servers SHOULD NOT 924 process or respond to requests received while processing a 925 BindRequest. 926 927 If the client did not bind before sending a request and receives an 928 operationsError to that request, it may then send a BindRequest. If 929 this also fails or the client chooses not to bind on the existing 930 LDAP session, it may terminate the LDAP session, re-establish it, and 931 begin again by first sending a BindRequest. This will aid in 932 interoperating with servers implementing other versions of LDAP. 933 934 Clients may send multiple Bind requests to change the authentication 935 and/or security associations or to complete a multi-stage Bind 936 process. Authentication from earlier binds is subsequently ignored. 937 938 For some SASL authentication mechanisms, it may be necessary for the 939 client to invoke the BindRequest multiple times ([RFC4513], Section 940 5.2). Clients MUST NOT invoke operations between two Bind requests 941 made as part of a multi-stage Bind. 942 943 A client may abort a SASL bind negotiation by sending a BindRequest 944 with a different value in the mechanism field of SaslCredentials, or 945 an AuthenticationChoice other than sasl. 946 947 948 949 950 951 952 953 954Sermersheim Standards Track [Page 17] 955 956RFC 4511 LDAPv3 June 2006 957 958 959 If the client sends a BindRequest with the sasl mechanism field as an 960 empty string, the server MUST return a BindResponse with the 961 resultCode set to authMethodNotSupported. This will allow the client 962 to abort a negotiation if it wishes to try again with the same SASL 963 mechanism. 964 9654.2.2. Bind Response 966 967 The Bind response is defined as follows. 968 969 BindResponse ::= [APPLICATION 1] SEQUENCE { 970 COMPONENTS OF LDAPResult, 971 serverSaslCreds [7] OCTET STRING OPTIONAL } 972 973 BindResponse consists simply of an indication from the server of the 974 status of the client's request for authentication. 975 976 A successful Bind operation is indicated by a BindResponse with a 977 resultCode set to success. Otherwise, an appropriate result code is 978 set in the BindResponse. For BindResponse, the protocolError result 979 code may be used to indicate that the version number supplied by the 980 client is unsupported. 981 982 If the client receives a BindResponse where the resultCode is set to 983 protocolError, it is to assume that the server does not support this 984 version of LDAP. While the client may be able proceed with another 985 version of this protocol (which may or may not require closing and 986 re-establishing the transport connection), how to proceed with 987 another version of this protocol is beyond the scope of this 988 document. Clients that are unable or unwilling to proceed SHOULD 989 terminate the LDAP session. 990 991 The serverSaslCreds field is used as part of a SASL-defined bind 992 mechanism to allow the client to authenticate the server to which it 993 is communicating, or to perform "challenge-response" authentication. 994 If the client bound with the simple choice, or the SASL mechanism 995 does not require the server to return information to the client, then 996 this field SHALL NOT be included in the BindResponse. 997 9984.3. Unbind Operation 999 1000 The function of the Unbind operation is to terminate an LDAP session. 1001 The Unbind operation is not the antithesis of the Bind operation as 1002 the name implies. The naming of these operations are historical. 1003 The Unbind operation should be thought of as the "quit" operation. 1004 1005 1006 1007 1008 1009 1010Sermersheim Standards Track [Page 18] 1011 1012RFC 4511 LDAPv3 June 2006 1013 1014 1015 The Unbind operation is defined as follows: 1016 1017 UnbindRequest ::= [APPLICATION 2] NULL 1018 1019 The client, upon transmission of the UnbindRequest, and the server, 1020 upon receipt of the UnbindRequest, are to gracefully terminate the 1021 LDAP session as described in Section 5.3. Uncompleted operations are 1022 handled as specified in Section 3.1. 1023 10244.4. Unsolicited Notification 1025 1026 An unsolicited notification is an LDAPMessage sent from the server to 1027 the client that is not in response to any LDAPMessage received by the 1028 server. It is used to signal an extraordinary condition in the 1029 server or in the LDAP session between the client and the server. The 1030 notification is of an advisory nature, and the server will not expect 1031 any response to be returned from the client. 1032 1033 The unsolicited notification is structured as an LDAPMessage in which 1034 the messageID is zero and protocolOp is set to the extendedResp 1035 choice using the ExtendedResponse type (See Section 4.12). The 1036 responseName field of the ExtendedResponse always contains an LDAPOID 1037 that is unique for this notification. 1038 1039 One unsolicited notification (Notice of Disconnection) is defined in 1040 this document. The specification of an unsolicited notification 1041 consists of: 1042 1043 - the OBJECT IDENTIFIER assigned to the notification (to be specified 1044 in the responseName, 1045 1046 - the format of the contents of the responseValue (if any), 1047 1048 - the circumstances which will cause the notification to be sent, and 1049 1050 - the semantics of the message. 1051 10524.4.1. Notice of Disconnection 1053 1054 This notification may be used by the server to advise the client that 1055 the server is about to terminate the LDAP session on its own 1056 initiative. This notification is intended to assist clients in 1057 distinguishing between an exceptional server condition and a 1058 transient network failure. Note that this notification is not a 1059 response to an Unbind requested by the client. Uncompleted 1060 operations are handled as specified in Section 3.1. 1061 1062 1063 1064 1065 1066Sermersheim Standards Track [Page 19] 1067 1068RFC 4511 LDAPv3 June 2006 1069 1070 1071 The responseName is 1.3.6.1.4.1.1466.20036, the responseValue field 1072 is absent, and the resultCode is used to indicate the reason for the 1073 disconnection. When the strongerAuthRequired resultCode is returned 1074 with this message, it indicates that the server has detected that an 1075 established security association between the client and server has 1076 unexpectedly failed or been compromised. 1077 1078 Upon transmission of the Notice of Disconnection, the server 1079 gracefully terminates the LDAP session as described in Section 5.3. 1080 10814.5. Search Operation 1082 1083 The Search operation is used to request a server to return, subject 1084 to access controls and other restrictions, a set of entries matching 1085 a complex search criterion. This can be used to read attributes from 1086 a single entry, from entries immediately subordinate to a particular 1087 entry, or from a whole subtree of entries. 1088 10894.5.1. Search Request 1090 1091 The Search request is defined as follows: 1092 1093 SearchRequest ::= [APPLICATION 3] SEQUENCE { 1094 baseObject LDAPDN, 1095 scope ENUMERATED { 1096 baseObject (0), 1097 singleLevel (1), 1098 wholeSubtree (2), 1099 ... }, 1100 derefAliases ENUMERATED { 1101 neverDerefAliases (0), 1102 derefInSearching (1), 1103 derefFindingBaseObj (2), 1104 derefAlways (3) }, 1105 sizeLimit INTEGER (0 .. maxInt), 1106 timeLimit INTEGER (0 .. maxInt), 1107 typesOnly BOOLEAN, 1108 filter Filter, 1109 attributes AttributeSelection } 1110 1111 AttributeSelection ::= SEQUENCE OF selector LDAPString 1112 -- The LDAPString is constrained to 1113 -- <attributeSelector> in Section 4.5.1.8 1114 1115 Filter ::= CHOICE { 1116 and [0] SET SIZE (1..MAX) OF filter Filter, 1117 or [1] SET SIZE (1..MAX) OF filter Filter, 1118 not [2] Filter, 1119 1120 1121 1122Sermersheim Standards Track [Page 20] 1123 1124RFC 4511 LDAPv3 June 2006 1125 1126 1127 equalityMatch [3] AttributeValueAssertion, 1128 substrings [4] SubstringFilter, 1129 greaterOrEqual [5] AttributeValueAssertion, 1130 lessOrEqual [6] AttributeValueAssertion, 1131 present [7] AttributeDescription, 1132 approxMatch [8] AttributeValueAssertion, 1133 extensibleMatch [9] MatchingRuleAssertion, 1134 ... } 1135 1136 SubstringFilter ::= SEQUENCE { 1137 type AttributeDescription, 1138 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE { 1139 initial [0] AssertionValue, -- can occur at most once 1140 any [1] AssertionValue, 1141 final [2] AssertionValue } -- can occur at most once 1142 } 1143 1144 MatchingRuleAssertion ::= SEQUENCE { 1145 matchingRule [1] MatchingRuleId OPTIONAL, 1146 type [2] AttributeDescription OPTIONAL, 1147 matchValue [3] AssertionValue, 1148 dnAttributes [4] BOOLEAN DEFAULT FALSE } 1149 1150 Note that an X.500 "list"-like operation can be emulated by the 1151 client requesting a singleLevel Search operation with a filter 1152 checking for the presence of the 'objectClass' attribute, and that an 1153 X.500 "read"-like operation can be emulated by a baseObject Search 1154 operation with the same filter. A server that provides a gateway to 1155 X.500 is not required to use the Read or List operations, although it 1156 may choose to do so, and if it does, it must provide the same 1157 semantics as the X.500 Search operation. 1158 11594.5.1.1. SearchRequest.baseObject 1160 1161 The name of the base object entry (or possibly the root) relative to 1162 which the Search is to be performed. 1163 11644.5.1.2. SearchRequest.scope 1165 1166 Specifies the scope of the Search to be performed. The semantics (as 1167 described in [X.511]) of the defined values of this field are: 1168 1169 baseObject: The scope is constrained to the entry named by 1170 baseObject. 1171 1172 singleLevel: The scope is constrained to the immediate 1173 subordinates of the entry named by baseObject. 1174 1175 1176 1177 1178Sermersheim Standards Track [Page 21] 1179 1180RFC 4511 LDAPv3 June 2006 1181 1182 1183 wholeSubtree: The scope is constrained to the entry named by 1184 baseObject and to all its subordinates. 1185 11864.5.1.3. SearchRequest.derefAliases 1187 1188 An indicator as to whether or not alias entries (as defined in 1189 [RFC4512]) are to be dereferenced during stages of the Search 1190 operation. 1191 1192 The act of dereferencing an alias includes recursively dereferencing 1193 aliases that refer to aliases. 1194 1195 Servers MUST detect looping while dereferencing aliases in order to 1196 prevent denial-of-service attacks of this nature. 1197 1198 The semantics of the defined values of this field are: 1199 1200 neverDerefAliases: Do not dereference aliases in searching or in 1201 locating the base object of the Search. 1202 1203 derefInSearching: While searching subordinates of the base object, 1204 dereference any alias within the search scope. Dereferenced 1205 objects become the vertices of further search scopes where the 1206 Search operation is also applied. If the search scope is 1207 wholeSubtree, the Search continues in the subtree(s) of any 1208 dereferenced object. If the search scope is singleLevel, the 1209 search is applied to any dereferenced objects and is not applied 1210 to their subordinates. Servers SHOULD eliminate duplicate entries 1211 that arise due to alias dereferencing while searching. 1212 1213 derefFindingBaseObj: Dereference aliases in locating the base 1214 object of the Search, but not when searching subordinates of the 1215 base object. 1216 1217 derefAlways: Dereference aliases both in searching and in locating 1218 the base object of the Search. 1219 12204.5.1.4. SearchRequest.sizeLimit 1221 1222 A size limit that restricts the maximum number of entries to be 1223 returned as a result of the Search. A value of zero in this field 1224 indicates that no client-requested size limit restrictions are in 1225 effect for the Search. Servers may also enforce a maximum number of 1226 entries to return. 1227 1228 1229 1230 1231 1232 1233 1234Sermersheim Standards Track [Page 22] 1235 1236RFC 4511 LDAPv3 June 2006 1237 1238 12394.5.1.5. SearchRequest.timeLimit 1240 1241 A time limit that restricts the maximum time (in seconds) allowed for 1242 a Search. A value of zero in this field indicates that no client- 1243 requested time limit restrictions are in effect for the Search. 1244 Servers may also enforce a maximum time limit for the Search. 1245 12464.5.1.6. SearchRequest.typesOnly 1247 1248 An indicator as to whether Search results are to contain both 1249 attribute descriptions and values, or just attribute descriptions. 1250 Setting this field to TRUE causes only attribute descriptions (and 1251 not values) to be returned. Setting this field to FALSE causes both 1252 attribute descriptions and values to be returned. 1253 12544.5.1.7. SearchRequest.filter 1255 1256 A filter that defines the conditions that must be fulfilled in order 1257 for the Search to match a given entry. 1258 1259 The 'and', 'or', and 'not' choices can be used to form combinations 1260 of filters. At least one filter element MUST be present in an 'and' 1261 or 'or' choice. The others match against individual attribute values 1262 of entries in the scope of the Search. (Implementor's note: the 1263 'not' filter is an example of a tagged choice in an implicitly-tagged 1264 module. In BER this is treated as if the tag were explicit.) 1265 1266 A server MUST evaluate filters according to the three-valued logic of 1267 [X.511] (1993), Clause 7.8.1. In summary, a filter is evaluated to 1268 "TRUE", "FALSE", or "Undefined". If the filter evaluates to TRUE for 1269 a particular entry, then the attributes of that entry are returned as 1270 part of the Search result (subject to any applicable access control 1271 restrictions). If the filter evaluates to FALSE or Undefined, then 1272 the entry is ignored for the Search. 1273 1274 A filter of the "and" choice is TRUE if all the filters in the SET OF 1275 evaluate to TRUE, FALSE if at least one filter is FALSE, and 1276 Undefined otherwise. A filter of the "or" choice is FALSE if all the 1277 filters in the SET OF evaluate to FALSE, TRUE if at least one filter 1278 is TRUE, and Undefined otherwise. A filter of the 'not' choice is 1279 TRUE if the filter being negated is FALSE, FALSE if it is TRUE, and 1280 Undefined if it is Undefined. 1281 1282 A filter item evaluates to Undefined when the server would not be 1283 able to determine whether the assertion value matches an entry. 1284 Examples include: 1285 1286 1287 1288 1289 1290Sermersheim Standards Track [Page 23] 1291 1292RFC 4511 LDAPv3 June 2006 1293 1294 1295 - An attribute description in an equalityMatch, substrings, 1296 greaterOrEqual, lessOrEqual, approxMatch, or extensibleMatch filter 1297 is not recognized by the server. 1298 1299 - The attribute type does not define the appropriate matching rule. 1300 1301 - A MatchingRuleId in the extensibleMatch is not recognized by the 1302 server or is not valid for the attribute type. 1303 1304 - The type of filtering requested is not implemented. 1305 1306 - The assertion value is invalid. 1307 1308 For example, if a server did not recognize the attribute type 1309 shoeSize, the filters (shoeSize=*), (shoeSize=12), (shoeSize>=12), 1310 and (shoeSize<=12) would each evaluate to Undefined. 1311 1312 Servers MUST NOT return errors if attribute descriptions or matching 1313 rule ids are not recognized, assertion values are invalid, or the 1314 assertion syntax is not supported. More details of filter processing 1315 are given in Clause 7.8 of [X.511]. 1316 13174.5.1.7.1. SearchRequest.filter.equalityMatch 1318 1319 The matching rule for an equalityMatch filter is defined by the 1320 EQUALITY matching rule for the attribute type or subtype. The filter 1321 is TRUE when the EQUALITY rule returns TRUE as applied to the 1322 attribute or subtype and the asserted value. 1323 13244.5.1.7.2. SearchRequest.filter.substrings 1325 1326 There SHALL be at most one 'initial' and at most one 'final' in the 1327 'substrings' of a SubstringFilter. If 'initial' is present, it SHALL 1328 be the first element of 'substrings'. If 'final' is present, it 1329 SHALL be the last element of 'substrings'. 1330 1331 The matching rule for an AssertionValue in a substrings filter item 1332 is defined by the SUBSTR matching rule for the attribute type or 1333 subtype. The filter is TRUE when the SUBSTR rule returns TRUE as 1334 applied to the attribute or subtype and the asserted value. 1335 1336 Note that the AssertionValue in a substrings filter item conforms to 1337 the assertion syntax of the EQUALITY matching rule for the attribute 1338 type rather than to the assertion syntax of the SUBSTR matching rule 1339 for the attribute type. Conceptually, the entire SubstringFilter is 1340 converted into an assertion value of the substrings matching rule 1341 prior to applying the rule. 1342 1343 1344 1345 1346Sermersheim Standards Track [Page 24] 1347 1348RFC 4511 LDAPv3 June 2006 1349 1350 13514.5.1.7.3. SearchRequest.filter.greaterOrEqual 1352 1353 The matching rule for a greaterOrEqual filter is defined by the 1354 ORDERING matching rule for the attribute type or subtype. The filter 1355 is TRUE when the ORDERING rule returns FALSE as applied to the 1356 attribute or subtype and the asserted value. 1357 13584.5.1.7.4. SearchRequest.filter.lessOrEqual 1359 1360 The matching rules for a lessOrEqual filter are defined by the 1361 ORDERING and EQUALITY matching rules for the attribute type or 1362 subtype. The filter is TRUE when either the ORDERING or EQUALITY 1363 rule returns TRUE as applied to the attribute or subtype and the 1364 asserted value. 1365 13664.5.1.7.5. SearchRequest.filter.present 1367 1368 A present filter is TRUE when there is an attribute or subtype of the 1369 specified attribute description present in an entry, FALSE when no 1370 attribute or subtype of the specified attribute description is 1371 present in an entry, and Undefined otherwise. 1372 13734.5.1.7.6. SearchRequest.filter.approxMatch 1374 1375 An approxMatch filter is TRUE when there is a value of the attribute 1376 type or subtype for which some locally-defined approximate matching 1377 algorithm (e.g., spelling variations, phonetic match, etc.) returns 1378 TRUE. If a value matches for equality, it also satisfies an 1379 approximate match. If approximate matching is not supported for the 1380 attribute, this filter item should be treated as an equalityMatch. 1381 13824.5.1.7.7. SearchRequest.filter.extensibleMatch 1383 1384 The fields of the extensibleMatch filter item are evaluated as 1385 follows: 1386 1387 - If the matchingRule field is absent, the type field MUST be 1388 present, and an equality match is performed for that type. 1389 1390 - If the type field is absent and the matchingRule is present, the 1391 matchValue is compared against all attributes in an entry that 1392 support that matchingRule. 1393 1394 - If the type field is present and the matchingRule is present, the 1395 matchValue is compared against the specified attribute type and its 1396 subtypes. 1397 1398 1399 1400 1401 1402Sermersheim Standards Track [Page 25] 1403 1404RFC 4511 LDAPv3 June 2006 1405 1406 1407 - If the dnAttributes field is set to TRUE, the match is additionally 1408 applied against all the AttributeValueAssertions in an entry's 1409 distinguished name, and it evaluates to TRUE if there is at least 1410 one attribute or subtype in the distinguished name for which the 1411 filter item evaluates to TRUE. The dnAttributes field is present 1412 to alleviate the need for multiple versions of generic matching 1413 rules (such as word matching), where one applies to entries and 1414 another applies to entries and DN attributes as well. 1415 1416 The matchingRule used for evaluation determines the syntax for the 1417 assertion value. Once the matchingRule and attribute(s) have been 1418 determined, the filter item evaluates to TRUE if it matches at least 1419 one attribute type or subtype in the entry, FALSE if it does not 1420 match any attribute type or subtype in the entry, and Undefined if 1421 the matchingRule is not recognized, the matchingRule is unsuitable 1422 for use with the specified type, or the assertionValue is invalid. 1423 14244.5.1.8. SearchRequest.attributes 1425 1426 A selection list of the attributes to be returned from each entry 1427 that matches the search filter. Attributes that are subtypes of 1428 listed attributes are implicitly included. LDAPString values of this 1429 field are constrained to the following Augmented Backus-Naur Form 1430 (ABNF) [RFC4234]: 1431 1432 attributeSelector = attributedescription / selectorspecial 1433 1434 selectorspecial = noattrs / alluserattrs 1435 1436 noattrs = %x31.2E.31 ; "1.1" 1437 1438 alluserattrs = %x2A ; asterisk ("*") 1439 1440 The <attributedescription> production is defined in Section 2.5 of 1441 [RFC4512]. 1442 1443 There are three special cases that may appear in the attributes 1444 selection list: 1445 1446 1. An empty list with no attributes requests the return of all 1447 user attributes. 1448 1449 2. A list containing "*" (with zero or more attribute 1450 descriptions) requests the return of all user attributes in 1451 addition to other listed (operational) attributes. 1452 1453 1454 1455 1456 1457 1458Sermersheim Standards Track [Page 26] 1459 1460RFC 4511 LDAPv3 June 2006 1461 1462 1463 3. A list containing only the OID "1.1" indicates that no 1464 attributes are to be returned. If "1.1" is provided with other 1465 attributeSelector values, the "1.1" attributeSelector is 1466 ignored. This OID was chosen because it does not (and can not) 1467 correspond to any attribute in use. 1468 1469 Client implementors should note that even if all user attributes are 1470 requested, some attributes and/or attribute values of the entry may 1471 not be included in Search results due to access controls or other 1472 restrictions. Furthermore, servers will not return operational 1473 attributes, such as objectClasses or attributeTypes, unless they are 1474 listed by name. Operational attributes are described in [RFC4512]. 1475 1476 Attributes are returned at most once in an entry. If an attribute 1477 description is named more than once in the list, the subsequent names 1478 are ignored. If an attribute description in the list is not 1479 recognized, it is ignored by the server. 1480 14814.5.2. Search Result 1482 1483 The results of the Search operation are returned as zero or more 1484 SearchResultEntry and/or SearchResultReference messages, followed by 1485 a single SearchResultDone message. 1486 1487 SearchResultEntry ::= [APPLICATION 4] SEQUENCE { 1488 objectName LDAPDN, 1489 attributes PartialAttributeList } 1490 1491 PartialAttributeList ::= SEQUENCE OF 1492 partialAttribute PartialAttribute 1493 1494 SearchResultReference ::= [APPLICATION 19] SEQUENCE 1495 SIZE (1..MAX) OF uri URI 1496 1497 SearchResultDone ::= [APPLICATION 5] LDAPResult 1498 1499 Each SearchResultEntry represents an entry found during the Search. 1500 Each SearchResultReference represents an area not yet explored during 1501 the Search. The SearchResultEntry and SearchResultReference messages 1502 may come in any order. Following all the SearchResultReference and 1503 SearchResultEntry responses, the server returns a SearchResultDone 1504 response, which contains an indication of success or details any 1505 errors that have occurred. 1506 1507 Each entry returned in a SearchResultEntry will contain all 1508 appropriate attributes as specified in the attributes field of the 1509 Search Request, subject to access control and other administrative 1510 policy. Note that the PartialAttributeList may hold zero elements. 1511 1512 1513 1514Sermersheim Standards Track [Page 27] 1515 1516RFC 4511 LDAPv3 June 2006 1517 1518 1519 This may happen when none of the attributes of an entry were 1520 requested or could be returned. Note also that the partialAttribute 1521 vals set may hold zero elements. This may happen when typesOnly is 1522 requested, access controls prevent the return of values, or other 1523 reasons. 1524 1525 Some attributes may be constructed by the server and appear in a 1526 SearchResultEntry attribute list, although they are not stored 1527 attributes of an entry. Clients SHOULD NOT assume that all 1528 attributes can be modified, even if this is permitted by access 1529 control. 1530 1531 If the server's schema defines short names [RFC4512] for an attribute 1532 type, then the server SHOULD use one of those names in attribute 1533 descriptions for that attribute type (in preference to using the 1534 <numericoid> [RFC4512] format of the attribute type's object 1535 identifier). The server SHOULD NOT use the short name if that name 1536 is known by the server to be ambiguous, or if it is otherwise likely 1537 to cause interoperability problems. 1538 15394.5.3. Continuation References in the Search Result 1540 1541 If the server was able to locate the entry referred to by the 1542 baseObject but was unable or unwilling to search one or more non- 1543 local entries, the server may return one or more 1544 SearchResultReference messages, each containing a reference to 1545 another set of servers for continuing the operation. A server MUST 1546 NOT return any SearchResultReference messages if it has not located 1547 the baseObject and thus has not searched any entries. In this case, 1548 it would return a SearchResultDone containing either a referral or 1549 noSuchObject result code (depending on the server's knowledge of the 1550 entry named in the baseObject). 1551 1552 If a server holds a copy or partial copy of the subordinate naming 1553 context (Section 5 of [RFC4512]), it may use the search filter to 1554 determine whether or not to return a SearchResultReference response. 1555 Otherwise, SearchResultReference responses are always returned when 1556 in scope. 1557 1558 The SearchResultReference is of the same data type as the Referral. 1559 1560 If the client wishes to progress the Search, it issues a new Search 1561 operation for each SearchResultReference that is returned. If 1562 multiple URIs are present, the client assumes that any supported URI 1563 may be used to progress the operation. 1564 1565 1566 1567 1568 1569 1570Sermersheim Standards Track [Page 28] 1571 1572RFC 4511 LDAPv3 June 2006 1573 1574 1575 Clients that follow search continuation references MUST ensure that 1576 they do not loop between servers. They MUST NOT repeatedly contact 1577 the same server for the same request with the same parameters. Some 1578 clients use a counter that is incremented each time search result 1579 reference handling occurs for an operation, and these kinds of 1580 clients MUST be able to handle at least ten nested referrals while 1581 progressing the operation. 1582 1583 Note that the Abandon operation described in Section 4.11 applies 1584 only to a particular operation sent at the LDAP message layer between 1585 a client and server. The client must individually abandon subsequent 1586 Search operations it wishes to. 1587 1588 A URI for a server implementing LDAP and accessible via TCP/IP (v4 or 1589 v6) [RFC793][RFC791] is written as an LDAP URL according to 1590 [RFC4516]. 1591 1592 SearchResultReference values that are LDAP URLs follow these rules: 1593 1594 - The <dn> part of the LDAP URL MUST be present, with the new target 1595 object name. The client uses this name when following the 1596 reference. 1597 1598 - Some servers (e.g., participating in distributed indexing) may 1599 provide a different filter in the LDAP URL. 1600 1601 - If the <filter> part of the LDAP URL is present, the client uses 1602 this filter in its next request to progress this Search, and if it 1603 is not present the client uses the same filter as it used for that 1604 Search. 1605 1606 - If the originating search scope was singleLevel, the <scope> part 1607 of the LDAP URL will be "base". 1608 1609 - It is RECOMMENDED that the <scope> part be present to avoid 1610 ambiguity. In the absence of a <scope> part, the scope of the 1611 original Search request is assumed. 1612 1613 - Other aspects of the new Search request may be the same as or 1614 different from the Search request that generated the 1615 SearchResultReference. 1616 1617 - The name of an unexplored subtree in a SearchResultReference need 1618 not be subordinate to the base object. 1619 1620 Other kinds of URIs may be returned. The syntax and semantics of 1621 such URIs is left to future specifications. Clients may ignore URIs 1622 that they do not support. 1623 1624 1625 1626Sermersheim Standards Track [Page 29] 1627 1628RFC 4511 LDAPv3 June 2006 1629 1630 1631 UTF-8-encoded characters appearing in the string representation of a 1632 DN, search filter, or other fields of the referral value may not be 1633 legal for URIs (e.g., spaces) and MUST be escaped using the % method 1634 in [RFC3986]. 1635 16364.5.3.1. Examples 1637 1638 For example, suppose the contacted server (hosta) holds the entry 1639 <DC=Example,DC=NET> and the entry <CN=Manager,DC=Example,DC=NET>. It 1640 knows that both LDAP servers (hostb) and (hostc) hold 1641 <OU=People,DC=Example,DC=NET> (one is the master and the other server 1642 a shadow), and that LDAP-capable server (hostd) holds the subtree 1643 <OU=Roles,DC=Example,DC=NET>. If a wholeSubtree Search of 1644 <DC=Example,DC=NET> is requested to the contacted server, it may 1645 return the following: 1646 1647 SearchResultEntry for DC=Example,DC=NET 1648 SearchResultEntry for CN=Manager,DC=Example,DC=NET 1649 SearchResultReference { 1650 ldap://hostb/OU=People,DC=Example,DC=NET??sub 1651 ldap://hostc/OU=People,DC=Example,DC=NET??sub } 1652 SearchResultReference { 1653 ldap://hostd/OU=Roles,DC=Example,DC=NET??sub } 1654 SearchResultDone (success) 1655 1656 Client implementors should note that when following a 1657 SearchResultReference, additional SearchResultReference may be 1658 generated. Continuing the example, if the client contacted the 1659 server (hostb) and issued the Search request for the subtree 1660 <OU=People,DC=Example,DC=NET>, the server might respond as follows: 1661 1662 SearchResultEntry for OU=People,DC=Example,DC=NET 1663 SearchResultReference { 1664 ldap://hoste/OU=Managers,OU=People,DC=Example,DC=NET??sub } 1665 SearchResultReference { 1666 ldap://hostf/OU=Consultants,OU=People,DC=Example,DC=NET??sub } 1667 SearchResultDone (success) 1668 1669 Similarly, if a singleLevel Search of <DC=Example,DC=NET> is 1670 requested to the contacted server, it may return the following: 1671 1672 SearchResultEntry for CN=Manager,DC=Example,DC=NET 1673 SearchResultReference { 1674 ldap://hostb/OU=People,DC=Example,DC=NET??base 1675 ldap://hostc/OU=People,DC=Example,DC=NET??base } 1676 SearchResultReference { 1677 ldap://hostd/OU=Roles,DC=Example,DC=NET??base } 1678 SearchResultDone (success) 1679 1680 1681 1682Sermersheim Standards Track [Page 30] 1683 1684RFC 4511 LDAPv3 June 2006 1685 1686 1687 If the contacted server does not hold the base object for the Search, 1688 but has knowledge of its possible location, then it may return a 1689 referral to the client. In this case, if the client requests a 1690 subtree Search of <DC=Example,DC=ORG> to hosta, the server returns a 1691 SearchResultDone containing a referral. 1692 1693 SearchResultDone (referral) { 1694 ldap://hostg/DC=Example,DC=ORG??sub } 1695 16964.6. Modify Operation 1697 1698 The Modify operation allows a client to request that a modification 1699 of an entry be performed on its behalf by a server. The Modify 1700 Request is defined as follows: 1701 1702 ModifyRequest ::= [APPLICATION 6] SEQUENCE { 1703 object LDAPDN, 1704 changes SEQUENCE OF change SEQUENCE { 1705 operation ENUMERATED { 1706 add (0), 1707 delete (1), 1708 replace (2), 1709 ... }, 1710 modification PartialAttribute } } 1711 1712 Fields of the Modify Request are: 1713 1714 - object: The value of this field contains the name of the entry to 1715 be modified. The server SHALL NOT perform any alias dereferencing 1716 in determining the object to be modified. 1717 1718 - changes: A list of modifications to be performed on the entry. The 1719 entire list of modifications MUST be performed in the order they 1720 are listed as a single atomic operation. While individual 1721 modifications may violate certain aspects of the directory schema 1722 (such as the object class definition and Directory Information Tree 1723 (DIT) content rule), the resulting entry after the entire list of 1724 modifications is performed MUST conform to the requirements of the 1725 directory model and controlling schema [RFC4512]. 1726 1727 - operation: Used to specify the type of modification being 1728 performed. Each operation type acts on the following 1729 modification. The values of this field have the following 1730 semantics, respectively: 1731 1732 add: add values listed to the modification attribute, 1733 creating the attribute if necessary. 1734 1735 1736 1737 1738Sermersheim Standards Track [Page 31] 1739 1740RFC 4511 LDAPv3 June 2006 1741 1742 1743 delete: delete values listed from the modification attribute. 1744 If no values are listed, or if all current values of the 1745 attribute are listed, the entire attribute is removed. 1746 1747 replace: replace all existing values of the modification 1748 attribute with the new values listed, creating the attribute 1749 if it did not already exist. A replace with no value will 1750 delete the entire attribute if it exists, and it is ignored 1751 if the attribute does not exist. 1752 1753 - modification: A PartialAttribute (which may have an empty SET 1754 of vals) used to hold the attribute type or attribute type and 1755 values being modified. 1756 1757 Upon receipt of a Modify Request, the server attempts to perform the 1758 necessary modifications to the DIT and returns the result in a Modify 1759 Response, defined as follows: 1760 1761 ModifyResponse ::= [APPLICATION 7] LDAPResult 1762 1763 The server will return to the client a single Modify Response 1764 indicating either the successful completion of the DIT modification, 1765 or the reason that the modification failed. Due to the requirement 1766 for atomicity in applying the list of modifications in the Modify 1767 Request, the client may expect that no modifications of the DIT have 1768 been performed if the Modify Response received indicates any sort of 1769 error, and that all requested modifications have been performed if 1770 the Modify Response indicates successful completion of the Modify 1771 operation. Whether or not the modification was applied cannot be 1772 determined by the client if the Modify Response was not received 1773 (e.g., the LDAP session was terminated or the Modify operation was 1774 abandoned). 1775 1776 Servers MUST ensure that entries conform to user and system schema 1777 rules or other data model constraints. The Modify operation cannot 1778 be used to remove from an entry any of its distinguished values, 1779 i.e., those values which form the entry's relative distinguished 1780 name. An attempt to do so will result in the server returning the 1781 notAllowedOnRDN result code. The Modify DN operation described in 1782 Section 4.9 is used to rename an entry. 1783 1784 For attribute types that specify no equality matching, the rules in 1785 Section 2.5.1 of [RFC4512] are followed. 1786 1787 Note that due to the simplifications made in LDAP, there is not a 1788 direct mapping of the changes in an LDAP ModifyRequest onto the 1789 changes of a DAP ModifyEntry operation, and different implementations 1790 1791 1792 1793 1794Sermersheim Standards Track [Page 32] 1795 1796RFC 4511 LDAPv3 June 2006 1797 1798 1799 of LDAP-DAP gateways may use different means of representing the 1800 change. If successful, the final effect of the operations on the 1801 entry MUST be identical. 1802 18034.7. Add Operation 1804 1805 The Add operation allows a client to request the addition of an entry 1806 into the Directory. The Add Request is defined as follows: 1807 1808 AddRequest ::= [APPLICATION 8] SEQUENCE { 1809 entry LDAPDN, 1810 attributes AttributeList } 1811 1812 AttributeList ::= SEQUENCE OF attribute Attribute 1813 1814 Fields of the Add Request are: 1815 1816 - entry: the name of the entry to be added. The server SHALL NOT 1817 dereference any aliases in locating the entry to be added. 1818 1819 - attributes: the list of attributes that, along with those from the 1820 RDN, make up the content of the entry being added. Clients MAY or 1821 MAY NOT include the RDN attribute(s) in this list. Clients MUST 1822 NOT supply NO-USER-MODIFICATION attributes such as the 1823 createTimestamp or creatorsName attributes, since the server 1824 maintains these automatically. 1825 1826 Servers MUST ensure that entries conform to user and system schema 1827 rules or other data model constraints. For attribute types that 1828 specify no equality matching, the rules in Section 2.5.1 of [RFC4512] 1829 are followed (this applies to the naming attribute in addition to any 1830 multi-valued attributes being added). 1831 1832 The entry named in the entry field of the AddRequest MUST NOT exist 1833 for the AddRequest to succeed. The immediate superior (parent) of an 1834 object or alias entry to be added MUST exist. For example, if the 1835 client attempted to add <CN=JS,DC=Example,DC=NET>, the 1836 <DC=Example,DC=NET> entry did not exist, and the <DC=NET> entry did 1837 exist, then the server would return the noSuchObject result code with 1838 the matchedDN field containing <DC=NET>. 1839 1840 Upon receipt of an Add Request, a server will attempt to add the 1841 requested entry. The result of the Add attempt will be returned to 1842 the client in the Add Response, defined as follows: 1843 1844 AddResponse ::= [APPLICATION 9] LDAPResult 1845 1846 1847 1848 1849 1850Sermersheim Standards Track [Page 33] 1851 1852RFC 4511 LDAPv3 June 2006 1853 1854 1855 A response of success indicates that the new entry has been added to 1856 the Directory. 1857 18584.8. Delete Operation 1859 1860 The Delete operation allows a client to request the removal of an 1861 entry from the Directory. The Delete Request is defined as follows: 1862 1863 DelRequest ::= [APPLICATION 10] LDAPDN 1864 1865 The Delete Request consists of the name of the entry to be deleted. 1866 The server SHALL NOT dereference aliases while resolving the name of 1867 the target entry to be removed. 1868 1869 Only leaf entries (those with no subordinate entries) can be deleted 1870 with this operation. 1871 1872 Upon receipt of a Delete Request, a server will attempt to perform 1873 the entry removal requested and return the result in the Delete 1874 Response defined as follows: 1875 1876 DelResponse ::= [APPLICATION 11] LDAPResult 1877 18784.9. Modify DN Operation 1879 1880 The Modify DN operation allows a client to change the Relative 1881 Distinguished Name (RDN) of an entry in the Directory and/or to move 1882 a subtree of entries to a new location in the Directory. The Modify 1883 DN Request is defined as follows: 1884 1885 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE { 1886 entry LDAPDN, 1887 newrdn RelativeLDAPDN, 1888 deleteoldrdn BOOLEAN, 1889 newSuperior [0] LDAPDN OPTIONAL } 1890 1891 Fields of the Modify DN Request are: 1892 1893 - entry: the name of the entry to be changed. This entry may or may 1894 not have subordinate entries. 1895 1896 - newrdn: the new RDN of the entry. The value of the old RDN is 1897 supplied when moving the entry to a new superior without changing 1898 its RDN. Attribute values of the new RDN not matching any 1899 attribute value of the entry are added to the entry, and an 1900 appropriate error is returned if this fails. 1901 1902 1903 1904 1905 1906Sermersheim Standards Track [Page 34] 1907 1908RFC 4511 LDAPv3 June 2006 1909 1910 1911 - deleteoldrdn: a boolean field that controls whether the old RDN 1912 attribute values are to be retained as attributes of the entry or 1913 deleted from the entry. 1914 1915 - newSuperior: if present, this is the name of an existing object 1916 entry that becomes the immediate superior (parent) of the 1917 existing entry. 1918 1919 The server SHALL NOT dereference any aliases in locating the objects 1920 named in entry or newSuperior. 1921 1922 Upon receipt of a ModifyDNRequest, a server will attempt to perform 1923 the name change and return the result in the Modify DN Response, 1924 defined as follows: 1925 1926 ModifyDNResponse ::= [APPLICATION 13] LDAPResult 1927 1928 For example, if the entry named in the entry field was <cn=John 1929 Smith,c=US>, the newrdn field was <cn=John Cougar Smith>, and the 1930 newSuperior field was absent, then this operation would attempt to 1931 rename the entry as <cn=John Cougar Smith,c=US>. If there was 1932 already an entry with that name, the operation would fail with the 1933 entryAlreadyExists result code. 1934 1935 Servers MUST ensure that entries conform to user and system schema 1936 rules or other data model constraints. For attribute types that 1937 specify no equality matching, the rules in Section 2.5.1 of [RFC4512] 1938 are followed (this pertains to newrdn and deleteoldrdn). 1939 1940 The object named in newSuperior MUST exist. For example, if the 1941 client attempted to add <CN=JS,DC=Example,DC=NET>, the 1942 <DC=Example,DC=NET> entry did not exist, and the <DC=NET> entry did 1943 exist, then the server would return the noSuchObject result code with 1944 the matchedDN field containing <DC=NET>. 1945 1946 If the deleteoldrdn field is TRUE, the attribute values forming the 1947 old RDN (but not the new RDN) are deleted from the entry. If the 1948 deleteoldrdn field is FALSE, the attribute values forming the old RDN 1949 will be retained as non-distinguished attribute values of the entry. 1950 1951 Note that X.500 restricts the ModifyDN operation to affect only 1952 entries that are contained within a single server. If the LDAP 1953 server is mapped onto DAP, then this restriction will apply, and the 1954 affectsMultipleDSAs result code will be returned if this error 1955 occurred. In general, clients MUST NOT expect to be able to perform 1956 arbitrary movements of entries and subtrees between servers or 1957 between naming contexts. 1958 1959 1960 1961 1962Sermersheim Standards Track [Page 35] 1963 1964RFC 4511 LDAPv3 June 2006 1965 1966 19674.10. Compare Operation 1968 1969 The Compare operation allows a client to compare an assertion value 1970 with the values of a particular attribute in a particular entry in 1971 the Directory. The Compare Request is defined as follows: 1972 1973 CompareRequest ::= [APPLICATION 14] SEQUENCE { 1974 entry LDAPDN, 1975 ava AttributeValueAssertion } 1976 1977 Fields of the Compare Request are: 1978 1979 - entry: the name of the entry to be compared. The server SHALL NOT 1980 dereference any aliases in locating the entry to be compared. 1981 1982 - ava: holds the attribute value assertion to be compared. 1983 1984 Upon receipt of a Compare Request, a server will attempt to perform 1985 the requested comparison and return the result in the Compare 1986 Response, defined as follows: 1987 1988 CompareResponse ::= [APPLICATION 15] LDAPResult 1989 1990 The resultCode is set to compareTrue, compareFalse, or an appropriate 1991 error. compareTrue indicates that the assertion value in the ava 1992 field matches a value of the attribute or subtype according to the 1993 attribute's EQUALITY matching rule. compareFalse indicates that the 1994 assertion value in the ava field and the values of the attribute or 1995 subtype did not match. Other result codes indicate either that the 1996 result of the comparison was Undefined (Section 4.5.1.7), or that 1997 some error occurred. 1998 1999 Note that some directory systems may establish access controls that 2000 permit the values of certain attributes (such as userPassword) to be 2001 compared but not interrogated by other means. 2002 20034.11. Abandon Operation 2004 2005 The function of the Abandon operation is to allow a client to request 2006 that the server abandon an uncompleted operation. The Abandon 2007 Request is defined as follows: 2008 2009 AbandonRequest ::= [APPLICATION 16] MessageID 2010 2011 The MessageID is that of an operation that was requested earlier at 2012 this LDAP message layer. The Abandon request itself has its own 2013 MessageID. This is distinct from the MessageID of the earlier 2014 operation being abandoned. 2015 2016 2017 2018Sermersheim Standards Track [Page 36] 2019 2020RFC 4511 LDAPv3 June 2006 2021 2022 2023 There is no response defined in the Abandon operation. Upon receipt 2024 of an AbandonRequest, the server MAY abandon the operation identified 2025 by the MessageID. Since the client cannot tell the difference 2026 between a successfully abandoned operation and an uncompleted 2027 operation, the application of the Abandon operation is limited to 2028 uses where the client does not require an indication of its outcome. 2029 2030 Abandon, Bind, Unbind, and StartTLS operations cannot be abandoned. 2031 2032 In the event that a server receives an Abandon Request on a Search 2033 operation in the midst of transmitting responses to the Search, that 2034 server MUST cease transmitting entry responses to the abandoned 2035 request immediately, and it MUST NOT send the SearchResultDone. Of 2036 course, the server MUST ensure that only properly encoded LDAPMessage 2037 PDUs are transmitted. 2038 2039 The ability to abandon other (particularly update) operations is at 2040 the discretion of the server. 2041 2042 Clients should not send Abandon requests for the same operation 2043 multiple times, and they MUST also be prepared to receive results 2044 from operations they have abandoned (since these might have been in 2045 transit when the Abandon was requested or might not be able to be 2046 abandoned). 2047 2048 Servers MUST discard Abandon requests for messageIDs they do not 2049 recognize, for operations that cannot be abandoned, and for 2050 operations that have already been abandoned. 2051 20524.12. Extended Operation 2053 2054 The Extended operation allows additional operations to be defined for 2055 services not already available in the protocol; for example, to Add 2056 operations to install transport layer security (see Section 4.14). 2057 2058 The Extended operation allows clients to make requests and receive 2059 responses with predefined syntaxes and semantics. These may be 2060 defined in RFCs or be private to particular implementations. 2061 2062 Each Extended operation consists of an Extended request and an 2063 Extended response. 2064 2065 ExtendedRequest ::= [APPLICATION 23] SEQUENCE { 2066 requestName [0] LDAPOID, 2067 requestValue [1] OCTET STRING OPTIONAL } 2068 2069 2070 2071 2072 2073 2074Sermersheim Standards Track [Page 37] 2075 2076RFC 4511 LDAPv3 June 2006 2077 2078 2079 The requestName is a dotted-decimal representation of the unique 2080 OBJECT IDENTIFIER corresponding to the request. The requestValue is 2081 information in a form defined by that request, encapsulated inside an 2082 OCTET STRING. 2083 2084 The server will respond to this with an LDAPMessage containing an 2085 ExtendedResponse. 2086 2087 ExtendedResponse ::= [APPLICATION 24] SEQUENCE { 2088 COMPONENTS OF LDAPResult, 2089 responseName [10] LDAPOID OPTIONAL, 2090 responseValue [11] OCTET STRING OPTIONAL } 2091 2092 The responseName field, when present, contains an LDAPOID that is 2093 unique for this extended operation or response. This field is 2094 optional (even when the extension specification defines an LDAPOID 2095 for use in this field). The field will be absent whenever the server 2096 is unable or unwilling to determine the appropriate LDAPOID to 2097 return, for instance, when the requestName cannot be parsed or its 2098 value is not recognized. 2099 2100 Where the requestName is not recognized, the server returns 2101 protocolError. (The server may return protocolError in other cases.) 2102 2103 The requestValue and responseValue fields contain information 2104 associated with the operation. The format of these fields is defined 2105 by the specification of the Extended operation. Implementations MUST 2106 be prepared to handle arbitrary contents of these fields, including 2107 zero bytes. Values that are defined in terms of ASN.1 and BER- 2108 encoded according to Section 5.1 also follow the extensibility rules 2109 in Section 4. 2110 2111 Servers list the requestName of Extended Requests they recognize in 2112 the 'supportedExtension' attribute in the root DSE (Section 5.1 of 2113 [RFC4512]). 2114 2115 Extended operations may be specified in other documents. The 2116 specification of an Extended operation consists of: 2117 2118 - the OBJECT IDENTIFIER assigned to the requestName, 2119 2120 - the OBJECT IDENTIFIER (if any) assigned to the responseName (note 2121 that the same OBJECT IDENTIFIER may be used for both the 2122 requestName and responseName), 2123 2124 2125 2126 2127 2128 2129 2130Sermersheim Standards Track [Page 38] 2131 2132RFC 4511 LDAPv3 June 2006 2133 2134 2135 - the format of the contents of the requestValue and responseValue 2136 (if any), and 2137 2138 - the semantics of the operation. 2139 21404.13. IntermediateResponse Message 2141 2142 While the Search operation provides a mechanism to return multiple 2143 response messages for a single Search request, other operations, by 2144 nature, do not provide for multiple response messages. 2145 2146 The IntermediateResponse message provides a general mechanism for 2147 defining single-request/multiple-response operations in LDAP. This 2148 message is intended to be used in conjunction with the Extended 2149 operation to define new single-request/multiple-response operations 2150 or in conjunction with a control when extending existing LDAP 2151 operations in a way that requires them to return Intermediate 2152 response information. 2153 2154 It is intended that the definitions and descriptions of Extended 2155 operations and controls that make use of the IntermediateResponse 2156 message will define the circumstances when an IntermediateResponse 2157 message can be sent by a server and the associated meaning of an 2158 IntermediateResponse message sent in a particular circumstance. 2159 2160 IntermediateResponse ::= [APPLICATION 25] SEQUENCE { 2161 responseName [0] LDAPOID OPTIONAL, 2162 responseValue [1] OCTET STRING OPTIONAL } 2163 2164 IntermediateResponse messages SHALL NOT be returned to the client 2165 unless the client issues a request that specifically solicits their 2166 return. This document defines two forms of solicitation: Extended 2167 operation and request control. IntermediateResponse messages are 2168 specified in documents describing the manner in which they are 2169 solicited (i.e., in the Extended operation or request control 2170 specification that uses them). These specifications include: 2171 2172 - the OBJECT IDENTIFIER (if any) assigned to the responseName, 2173 2174 - the format of the contents of the responseValue (if any), and 2175 2176 - the semantics associated with the IntermediateResponse message. 2177 2178 Extensions that allow the return of multiple types of 2179 IntermediateResponse messages SHALL identify those types using unique 2180 responseName values (note that one of these may specify no value). 2181 2182 2183 2184 2185 2186Sermersheim Standards Track [Page 39] 2187 2188RFC 4511 LDAPv3 June 2006 2189 2190 2191 Sections 4.13.1 and 4.13.2 describe additional requirements on the 2192 inclusion of responseName and responseValue in IntermediateResponse 2193 messages. 2194 21954.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse 2196 2197 A single-request/multiple-response operation may be defined using a 2198 single ExtendedRequest message to solicit zero or more 2199 IntermediateResponse messages of one or more kinds, followed by an 2200 ExtendedResponse message. 2201 22024.13.2. Usage with LDAP Request Controls 2203 2204 A control's semantics may include the return of zero or more 2205 IntermediateResponse messages prior to returning the final result 2206 code for the operation. One or more kinds of IntermediateResponse 2207 messages may be sent in response to a request control. 2208 2209 All IntermediateResponse messages associated with request controls 2210 SHALL include a responseName. This requirement ensures that the 2211 client can correctly identify the source of IntermediateResponse 2212 messages when: 2213 2214 - two or more controls using IntermediateResponse messages are 2215 included in a request for any LDAP operation or 2216 2217 - one or more controls using IntermediateResponse messages are 2218 included in a request with an LDAP Extended operation that uses 2219 IntermediateResponse messages. 2220 22214.14. StartTLS Operation 2222 2223 The Start Transport Layer Security (StartTLS) operation's purpose is 2224 to initiate installation of a TLS layer. The StartTLS operation is 2225 defined using the Extended operation mechanism described in Section 2226 4.12. 2227 22284.14.1. StartTLS Request 2229 2230 A client requests TLS establishment by transmitting a StartTLS 2231 request message to the server. The StartTLS request is defined in 2232 terms of an ExtendedRequest. The requestName is 2233 "1.3.6.1.4.1.1466.20037", and the requestValue field is always 2234 absent. 2235 2236 2237 2238 2239 2240 2241 2242Sermersheim Standards Track [Page 40] 2243 2244RFC 4511 LDAPv3 June 2006 2245 2246 2247 The client MUST NOT send any LDAP PDUs at this LDAP message layer 2248 following this request until it receives a StartTLS Extended response 2249 and, in the case of a successful response, completes TLS 2250 negotiations. 2251 2252 Detected sequencing problems (particularly those detailed in Section 2253 3.1.1 of [RFC4513]) result in the resultCode being set to 2254 operationsError. 2255 2256 If the server does not support TLS (whether by design or by current 2257 configuration), it returns with the resultCode set to protocolError 2258 as described in Section 4.12. 2259 22604.14.2. StartTLS Response 2261 2262 When a StartTLS request is received, servers supporting the operation 2263 MUST return a StartTLS response message to the requestor. The 2264 responseName is "1.3.6.1.4.1.1466.20037" when provided (see Section 2265 4.12). The responseValue is always absent. 2266 2267 If the server is willing and able to negotiate TLS, it returns the 2268 StartTLS response with the resultCode set to success. Upon client 2269 receipt of a successful StartTLS response, protocol peers may 2270 commence with TLS negotiation as discussed in Section 3 of [RFC4513]. 2271 2272 If the server is otherwise unwilling or unable to perform this 2273 operation, the server is to return an appropriate result code 2274 indicating the nature of the problem. For example, if the TLS 2275 subsystem is not presently available, the server may indicate this by 2276 returning with the resultCode set to unavailable. In cases where a 2277 non-success result code is returned, the LDAP session is left without 2278 a TLS layer. 2279 22804.14.3. Removal of the TLS Layer 2281 2282 Either the client or server MAY remove the TLS layer and leave the 2283 LDAP message layer intact by sending and receiving a TLS closure 2284 alert. 2285 2286 The initiating protocol peer sends the TLS closure alert and MUST 2287 wait until it receives a TLS closure alert from the other peer before 2288 sending further LDAP PDUs. 2289 2290 When a protocol peer receives the initial TLS closure alert, it may 2291 choose to allow the LDAP message layer to remain intact. In this 2292 case, it MUST immediately transmit a TLS closure alert. Following 2293 this, it MAY send and receive LDAP PDUs. 2294 2295 2296 2297 2298Sermersheim Standards Track [Page 41] 2299 2300RFC 4511 LDAPv3 June 2006 2301 2302 2303 Protocol peers MAY terminate the LDAP session after sending or 2304 receiving a TLS closure alert. 2305 23065. Protocol Encoding, Connection, and Transfer 2307 2308 This protocol is designed to run over connection-oriented, reliable 2309 transports, where the data stream is divided into octets (8-bit 2310 units), with each octet and each bit being significant. 2311 2312 One underlying service, LDAP over TCP, is defined in Section 5.2. 2313 This service is generally applicable to applications providing or 2314 consuming X.500-based directory services on the Internet. This 2315 specification was generally written with the TCP mapping in mind. 2316 Specifications detailing other mappings may encounter various 2317 obstacles. 2318 2319 Implementations of LDAP over TCP MUST implement the mapping as 2320 described in Section 5.2. 2321 2322 This table illustrates the relationship among the different layers 2323 involved in an exchange between two protocol peers: 2324 2325 +----------------------+ 2326 | LDAP message layer | 2327 +----------------------+ > LDAP PDUs 2328 +----------------------+ < data 2329 | SASL layer | 2330 +----------------------+ > SASL-protected data 2331 +----------------------+ < data 2332 | TLS layer | 2333 Application +----------------------+ > TLS-protected data 2334 ------------+----------------------+ < data 2335 Transport | transport connection | 2336 +----------------------+ 2337 23385.1. Protocol Encoding 2339 2340 The protocol elements of LDAP SHALL be encoded for exchange using the 2341 Basic Encoding Rules [BER] of [ASN.1] with the following 2342 restrictions: 2343 2344 - Only the definite form of length encoding is used. 2345 2346 - OCTET STRING values are encoded in the primitive form only. 2347 2348 - If the value of a BOOLEAN type is true, the encoding of the value 2349 octet is set to hex "FF". 2350 2351 2352 2353 2354Sermersheim Standards Track [Page 42] 2355 2356RFC 4511 LDAPv3 June 2006 2357 2358 2359 - If a value of a type is its default value, it is absent. Only some 2360 BOOLEAN and INTEGER types have default values in this protocol 2361 definition. 2362 2363 These restrictions are meant to ease the overhead of encoding and 2364 decoding certain elements in BER. 2365 2366 These restrictions do not apply to ASN.1 types encapsulated inside of 2367 OCTET STRING values, such as attribute values, unless otherwise 2368 stated. 2369 23705.2. Transmission Control Protocol (TCP) 2371 2372 The encoded LDAPMessage PDUs are mapped directly onto the TCP 2373 [RFC793] bytestream using the BER-based encoding described in Section 2374 5.1. It is recommended that server implementations running over the 2375 TCP provide a protocol listener on the Internet Assigned Numbers 2376 Authority (IANA)-assigned LDAP port, 389 [PortReg]. Servers may 2377 instead provide a listener on a different port number. Clients MUST 2378 support contacting servers on any valid TCP port. 2379 23805.3. Termination of the LDAP session 2381 2382 Termination of the LDAP session is typically initiated by the client 2383 sending an UnbindRequest (Section 4.3), or by the server sending a 2384 Notice of Disconnection (Section 4.4.1). In these cases, each 2385 protocol peer gracefully terminates the LDAP session by ceasing 2386 exchanges at the LDAP message layer, tearing down any SASL layer, 2387 tearing down any TLS layer, and closing the transport connection. 2388 2389 A protocol peer may determine that the continuation of any 2390 communication would be pernicious, and in this case, it may abruptly 2391 terminate the session by ceasing communication and closing the 2392 transport connection. 2393 2394 In either case, when the LDAP session is terminated, uncompleted 2395 operations are handled as specified in Section 3.1. 2396 23976. Security Considerations 2398 2399 This version of the protocol provides facilities for simple 2400 authentication using a cleartext password, as well as any SASL 2401 [RFC4422] mechanism. Installing SASL and/or TLS layers can provide 2402 integrity and other data security services. 2403 2404 It is also permitted that the server can return its credentials to 2405 the client, if it chooses to do so. 2406 2407 2408 2409 2410Sermersheim Standards Track [Page 43] 2411 2412RFC 4511 LDAPv3 June 2006 2413 2414 2415 Use of cleartext password is strongly discouraged where the 2416 underlying transport service cannot guarantee confidentiality and may 2417 result in disclosure of the password to unauthorized parties. 2418 2419 Servers are encouraged to prevent directory modifications by clients 2420 that have authenticated anonymously [RFC4513]. 2421 2422 Security considerations for authentication methods, SASL mechanisms, 2423 and TLS are described in [RFC4513]. 2424 2425 Note that SASL authentication exchanges do not provide data 2426 confidentiality or integrity protection for the version or name 2427 fields of the BindRequest or the resultCode, diagnosticMessage, or 2428 referral fields of the BindResponse, nor for any information 2429 contained in controls attached to Bind requests or responses. Thus, 2430 information contained in these fields SHOULD NOT be relied on unless 2431 it is otherwise protected (such as by establishing protections at the 2432 transport layer). 2433 2434 Implementors should note that various security factors (including 2435 authentication and authorization information and data security 2436 services) may change during the course of the LDAP session or even 2437 during the performance of a particular operation. For instance, 2438 credentials could expire, authorization identities or access controls 2439 could change, or the underlying security layer(s) could be replaced 2440 or terminated. Implementations should be robust in the handling of 2441 changing security factors. 2442 2443 In some cases, it may be appropriate to continue the operation even 2444 in light of security factor changes. For instance, it may be 2445 appropriate to continue an Abandon operation regardless of the 2446 change, or to continue an operation when the change upgraded (or 2447 maintained) the security factor. In other cases, it may be 2448 appropriate to fail or alter the processing of the operation. For 2449 instance, if confidential protections were removed, it would be 2450 appropriate either to fail a request to return sensitive data or, 2451 minimally, to exclude the return of sensitive data. 2452 2453 Implementations that cache attributes and entries obtained via LDAP 2454 MUST ensure that access controls are maintained if that information 2455 is to be provided to multiple clients, since servers may have access 2456 control policies that prevent the return of entries or attributes in 2457 Search results except to particular authenticated clients. For 2458 example, caches could serve result information only to the client 2459 whose request caused it to be in the cache. 2460 2461 2462 2463 2464 2465 2466Sermersheim Standards Track [Page 44] 2467 2468RFC 4511 LDAPv3 June 2006 2469 2470 2471 Servers may return referrals or Search result references that 2472 redirect clients to peer servers. It is possible for a rogue 2473 application to inject such referrals into the data stream in an 2474 attempt to redirect a client to a rogue server. Clients are advised 2475 to be aware of this and possibly reject referrals when 2476 confidentiality measures are not in place. Clients are advised to 2477 reject referrals from the StartTLS operation. 2478 2479 The matchedDN and diagnosticMessage fields, as well as some 2480 resultCode values (e.g., attributeOrValueExists and 2481 entryAlreadyExists), could disclose the presence or absence of 2482 specific data in the directory that is subject to access and other 2483 administrative controls. Server implementations should restrict 2484 access to protected information equally under both normal and error 2485 conditions. 2486 2487 Protocol peers MUST be prepared to handle invalid and arbitrary- 2488 length protocol encodings. Invalid protocol encodings include: BER 2489 encoding exceptions, format string and UTF-8 encoding exceptions, 2490 overflow exceptions, integer value exceptions, and binary mode on/off 2491 flag exceptions. The LDAPv3 PROTOS [PROTOS-LDAP] test suite provides 2492 excellent examples of these exceptions and test cases used to 2493 discover flaws. 2494 2495 In the event that a protocol peer senses an attack that in its nature 2496 could cause damage due to further communication at any layer in the 2497 LDAP session, the protocol peer should abruptly terminate the LDAP 2498 session as described in Section 5.3. 2499 25007. Acknowledgements 2501 2502 This document is based on RFC 2251 by Mark Wahl, Tim Howes, and Steve 2503 Kille. RFC 2251 was a product of the IETF ASID Working Group. 2504 2505 It is also based on RFC 2830 by Jeff Hodges, RL "Bob" Morgan, and 2506 Mark Wahl. RFC 2830 was a product of the IETF LDAPEXT Working Group. 2507 2508 It is also based on RFC 3771 by Roger Harrison and Kurt Zeilenga. 2509 RFC 3771 was an individual submission to the IETF. 2510 2511 This document is a product of the IETF LDAPBIS Working Group. 2512 Significant contributors of technical review and content include Kurt 2513 Zeilenga, Steven Legg, and Hallvard Furuseth. 2514 2515 2516 2517 2518 2519 2520 2521 2522Sermersheim Standards Track [Page 45] 2523 2524RFC 4511 LDAPv3 June 2006 2525 2526 25278. Normative References 2528 2529 [ASN.1] ITU-T Recommendation X.680 (07/2002) | ISO/IEC 8824- 2530 1:2002 "Information Technology - Abstract Syntax 2531 Notation One (ASN.1): Specification of basic notation". 2532 2533 [BER] ITU-T Rec. X.690 (07/2002) | ISO/IEC 8825-1:2002, 2534 "Information technology - ASN.1 encoding rules: 2535 Specification of Basic Encoding Rules (BER), Canonical 2536 Encoding Rules (CER) and Distinguished Encoding Rules 2537 (DER)", 2002. 2538 2539 [ISO10646] Universal Multiple-Octet Coded Character Set (UCS) - 2540 Architecture and Basic Multilingual Plane, ISO/IEC 2541 10646-1 : 1993. 2542 2543 [RFC791] Postel, J., "Internet Protocol", STD 5, RFC 791, 2544 September 1981. 2545 2546 [RFC793] Postel, J., "Transmission Control Protocol", STD 7, RFC 2547 793, September 1981. 2548 2549 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2550 Requirement Levels", BCP 14, RFC 2119, March 1997. 2551 2552 [RFC3454] Hoffman P. and M. Blanchet, "Preparation of 2553 Internationalized Strings ('stringprep')", RFC 3454, 2554 December 2002. 2555 2556 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2557 10646", STD 63, RFC 3629, November 2003. 2558 2559 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, 2560 "Uniform Resource Identifier (URI): Generic Syntax", 2561 STD 66, RFC 3986, January 2005. 2562 2563 [RFC4013] Zeilenga, K., "SASLprep: Stringprep Profile for User 2564 Names and Passwords", RFC 4013, February 2005. 2565 2566 [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2567 Specifications: ABNF", RFC 4234, October 2005. 2568 2569 [RFC4346] Dierks, T. and E. Rescorla, "The TLS Protocol Version 2570 1.1", RFC 4346, March 2006. 2571 2572 [RFC4422] Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple 2573 Authentication and Security Layer (SASL)", RFC 4422, 2574 June 2006. 2575 2576 2577 2578Sermersheim Standards Track [Page 46] 2579 2580RFC 4511 LDAPv3 June 2006 2581 2582 2583 [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access 2584 Protocol (LDAP): Technical Specification Road Map", RFC 2585 4510, June 2006. 2586 2587 [RFC4512] Zeilenga, K., Lightweight Directory Access Protocol 2588 (LDAP): Directory Information Models", RFC 4512, June 2589 2006. 2590 2591 [RFC4513] Harrison, R., Ed., "Lightweight Directory Access 2592 Protocol (LDAP): Authentication Methods and Security 2593 Mechanisms", RFC 4513, June 2006. 2594 2595 [RFC4514] Zeilenga, K., Ed., "Lightweight Directory Access 2596 Protocol (LDAP): String Representation of Distinguished 2597 Names", RFC 4514, June 2006. 2598 2599 [RFC4516] Smith, M., Ed. and T. Howes, "Lightweight Directory 2600 Access Protocol (LDAP): Uniform Resource Locator", RFC 2601 4516, June 2006. 2602 2603 [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol 2604 (LDAP): Syntaxes and Matching Rules", RFC 4517, June 2605 2006. 2606 2607 [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority 2608 (IANA) Considerations for the Lightweight Directory 2609 Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. 2610 2611 [Unicode] The Unicode Consortium, "The Unicode Standard, Version 2612 3.2.0" is defined by "The Unicode Standard, Version 2613 3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201- 2614 61633-5), as amended by the "Unicode Standard Annex 2615 #27: Unicode 3.1" 2616 (http://www.unicode.org/reports/tr27/) and by the 2617 "Unicode Standard Annex #28: Unicode 3.2" 2618 (http://www.unicode.org/reports/tr28/). 2619 2620 [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts, 2621 Models and Service", 1993. 2622 2623 [X.511] ITU-T Rec. X.511, "The Directory: Abstract Service 2624 Definition", 1993. 2625 2626 2627 2628 2629 2630 2631 2632 2633 2634Sermersheim Standards Track [Page 47] 2635 2636RFC 4511 LDAPv3 June 2006 2637 2638 26399. Informative References 2640 2641 [CharModel] Whistler, K. and M. Davis, "Unicode Technical Report 2642 #17, Character Encoding Model", UTR17, 2643 <http://www.unicode.org/unicode/reports/tr17/>, August 2644 2000. 2645 2646 [Glossary] The Unicode Consortium, "Unicode Glossary", 2647 <http://www.unicode.org/glossary/>. 2648 2649 [PortReg] IANA, "Port Numbers", 2650 <http://www.iana.org/assignments/port-numbers>. 2651 2652 [PROTOS-LDAP] University of Oulu, "PROTOS Test-Suite: c06-ldapv3" 2653 <http://www.ee.oulu.fi/research/ouspg/protos/testing/ 2654 c06/ldapv3/>. 2655 265610. IANA Considerations 2657 2658 The Internet Assigned Numbers Authority (IANA) has updated the LDAP 2659 result code registry to indicate that this document provides the 2660 definitive technical specification for result codes 0-36, 48-54, 64- 2661 70, 80-90. It is also noted that one resultCode value 2662 (strongAuthRequired) has been renamed (to strongerAuthRequired). 2663 2664 The IANA has also updated the LDAP Protocol Mechanism registry to 2665 indicate that this document and [RFC4513] provides the definitive 2666 technical specification for the StartTLS (1.3.6.1.4.1.1466.20037) 2667 Extended operation. 2668 2669 IANA has assigned LDAP Object Identifier 18 [RFC4520] to identify the 2670 ASN.1 module defined in this document. 2671 2672 Subject: Request for LDAP Object Identifier Registration 2673 Person & email address to contact for further information: 2674 Jim Sermersheim <jimse@novell.com> 2675 Specification: RFC 4511 2676 Author/Change Controller: IESG 2677 Comments: 2678 Identifies the LDAP ASN.1 module 2679 2680 2681 2682 2683 2684 2685 2686 2687 2688 2689 2690Sermersheim Standards Track [Page 48] 2691 2692RFC 4511 LDAPv3 June 2006 2693 2694 2695Appendix A. LDAP Result Codes 2696 2697 This normative appendix details additional considerations regarding 2698 LDAP result codes and provides a brief, general description of each 2699 LDAP result code enumerated in Section 4.1.9. 2700 2701 Additional result codes MAY be defined for use with extensions 2702 [RFC4520]. Client implementations SHALL treat any result code that 2703 they do not recognize as an unknown error condition. 2704 2705 The descriptions provided here do not fully account for result code 2706 substitutions used to prevent unauthorized disclosures (such as 2707 substitution of noSuchObject for insufficientAccessRights, or 2708 invalidCredentials for insufficientAccessRights). 2709 2710A.1. Non-Error Result Codes 2711 2712 These result codes (called "non-error" result codes) do not indicate 2713 an error condition: 2714 2715 success (0), 2716 compareFalse (5), 2717 compareTrue (6), 2718 referral (10), and 2719 saslBindInProgress (14). 2720 2721 The success, compareTrue, and compareFalse result codes indicate 2722 successful completion (and, hence, are referred to as "successful" 2723 result codes). 2724 2725 The referral and saslBindInProgress result codes indicate the client 2726 needs to take additional action to complete the operation. 2727 2728A.2. Result Codes 2729 2730 Existing LDAP result codes are described as follows: 2731 2732 success (0) 2733 Indicates the successful completion of an operation. Note: 2734 this code is not used with the Compare operation. See 2735 compareFalse (5) and compareTrue (6). 2736 2737 2738 2739 2740 2741 2742 2743 2744 2745 2746Sermersheim Standards Track [Page 49] 2747 2748RFC 4511 LDAPv3 June 2006 2749 2750 2751 operationsError (1) 2752 Indicates that the operation is not properly sequenced with 2753 relation to other operations (of same or different type). 2754 2755 For example, this code is returned if the client attempts to 2756 StartTLS [RFC4346] while there are other uncompleted operations 2757 or if a TLS layer was already installed. 2758 2759 protocolError (2) 2760 Indicates the server received data that is not well-formed. 2761 2762 For Bind operation only, this code is also used to indicate 2763 that the server does not support the requested protocol 2764 version. 2765 2766 For Extended operations only, this code is also used to 2767 indicate that the server does not support (by design or 2768 configuration) the Extended operation associated with the 2769 requestName. 2770 2771 For request operations specifying multiple controls, this may 2772 be used to indicate that the server cannot ignore the order 2773 of the controls as specified, or that the combination of the 2774 specified controls is invalid or unspecified. 2775 2776 timeLimitExceeded (3) 2777 Indicates that the time limit specified by the client was 2778 exceeded before the operation could be completed. 2779 2780 sizeLimitExceeded (4) 2781 Indicates that the size limit specified by the client was 2782 exceeded before the operation could be completed. 2783 2784 compareFalse (5) 2785 Indicates that the Compare operation has successfully 2786 completed and the assertion has evaluated to FALSE or 2787 Undefined. 2788 2789 compareTrue (6) 2790 Indicates that the Compare operation has successfully 2791 completed and the assertion has evaluated to TRUE. 2792 2793 authMethodNotSupported (7) 2794 Indicates that the authentication method or mechanism is not 2795 supported. 2796 2797 2798 2799 2800 2801 2802Sermersheim Standards Track [Page 50] 2803 2804RFC 4511 LDAPv3 June 2006 2805 2806 2807 strongerAuthRequired (8) 2808 Indicates the server requires strong(er) authentication in 2809 order to complete the operation. 2810 2811 When used with the Notice of Disconnection operation, this 2812 code indicates that the server has detected that an 2813 established security association between the client and 2814 server has unexpectedly failed or been compromised. 2815 2816 referral (10) 2817 Indicates that a referral needs to be chased to complete the 2818 operation (see Section 4.1.10). 2819 2820 adminLimitExceeded (11) 2821 Indicates that an administrative limit has been exceeded. 2822 2823 unavailableCriticalExtension (12) 2824 Indicates a critical control is unrecognized (see Section 2825 4.1.11). 2826 2827 confidentialityRequired (13) 2828 Indicates that data confidentiality protections are required. 2829 2830 saslBindInProgress (14) 2831 Indicates the server requires the client to send a new bind 2832 request, with the same SASL mechanism, to continue the 2833 authentication process (see Section 4.2). 2834 2835 noSuchAttribute (16) 2836 Indicates that the named entry does not contain the specified 2837 attribute or attribute value. 2838 2839 undefinedAttributeType (17) 2840 Indicates that a request field contains an unrecognized 2841 attribute description. 2842 2843 inappropriateMatching (18) 2844 Indicates that an attempt was made (e.g., in an assertion) to 2845 use a matching rule not defined for the attribute type 2846 concerned. 2847 2848 constraintViolation (19) 2849 Indicates that the client supplied an attribute value that 2850 does not conform to the constraints placed upon it by the 2851 data model. 2852 2853 For example, this code is returned when multiple values are 2854 supplied to an attribute that has a SINGLE-VALUE constraint. 2855 2856 2857 2858Sermersheim Standards Track [Page 51] 2859 2860RFC 4511 LDAPv3 June 2006 2861 2862 2863 attributeOrValueExists (20) 2864 Indicates that the client supplied an attribute or value to 2865 be added to an entry, but the attribute or value already 2866 exists. 2867 2868 invalidAttributeSyntax (21) 2869 Indicates that a purported attribute value does not conform 2870 to the syntax of the attribute. 2871 2872 noSuchObject (32) 2873 Indicates that the object does not exist in the DIT. 2874 2875 aliasProblem (33) 2876 Indicates that an alias problem has occurred. For example, 2877 the code may used to indicate an alias has been dereferenced 2878 that names no object. 2879 2880 invalidDNSyntax (34) 2881 Indicates that an LDAPDN or RelativeLDAPDN field (e.g., search 2882 base, target entry, ModifyDN newrdn, etc.) of a request does 2883 not conform to the required syntax or contains attribute 2884 values that do not conform to the syntax of the attribute's 2885 type. 2886 2887 aliasDereferencingProblem (36) 2888 Indicates that a problem occurred while dereferencing an 2889 alias. Typically, an alias was encountered in a situation 2890 where it was not allowed or where access was denied. 2891 2892 inappropriateAuthentication (48) 2893 Indicates the server requires the client that had attempted 2894 to bind anonymously or without supplying credentials to 2895 provide some form of credentials. 2896 2897 invalidCredentials (49) 2898 Indicates that the provided credentials (e.g., the user's name 2899 and password) are invalid. 2900 2901 insufficientAccessRights (50) 2902 Indicates that the client does not have sufficient access 2903 rights to perform the operation. 2904 2905 busy (51) 2906 Indicates that the server is too busy to service the 2907 operation. 2908 2909 2910 2911 2912 2913 2914Sermersheim Standards Track [Page 52] 2915 2916RFC 4511 LDAPv3 June 2006 2917 2918 2919 unavailable (52) 2920 Indicates that the server is shutting down or a subsystem 2921 necessary to complete the operation is offline. 2922 2923 unwillingToPerform (53) 2924 Indicates that the server is unwilling to perform the 2925 operation. 2926 2927 loopDetect (54) 2928 Indicates that the server has detected an internal loop (e.g., 2929 while dereferencing aliases or chaining an operation). 2930 2931 namingViolation (64) 2932 Indicates that the entry's name violates naming restrictions. 2933 2934 objectClassViolation (65) 2935 Indicates that the entry violates object class restrictions. 2936 2937 notAllowedOnNonLeaf (66) 2938 Indicates that the operation is inappropriately acting upon a 2939 non-leaf entry. 2940 2941 notAllowedOnRDN (67) 2942 Indicates that the operation is inappropriately attempting to 2943 remove a value that forms the entry's relative distinguished 2944 name. 2945 2946 entryAlreadyExists (68) 2947 Indicates that the request cannot be fulfilled (added, moved, 2948 or renamed) as the target entry already exists. 2949 2950 objectClassModsProhibited (69) 2951 Indicates that an attempt to modify the object class(es) of 2952 an entry's 'objectClass' attribute is prohibited. 2953 2954 For example, this code is returned when a client attempts to 2955 modify the structural object class of an entry. 2956 2957 affectsMultipleDSAs (71) 2958 Indicates that the operation cannot be performed as it would 2959 affect multiple servers (DSAs). 2960 2961 other (80) 2962 Indicates the server has encountered an internal error. 2963 2964 2965 2966 2967 2968 2969 2970Sermersheim Standards Track [Page 53] 2971 2972RFC 4511 LDAPv3 June 2006 2973 2974 2975Appendix B. Complete ASN.1 Definition 2976 2977 This appendix is normative. 2978 2979 Lightweight-Directory-Access-Protocol-V3 {1 3 6 1 1 18} 2980 -- Copyright (C) The Internet Society (2006). This version of 2981 -- this ASN.1 module is part of RFC 4511; see the RFC itself 2982 -- for full legal notices. 2983 DEFINITIONS 2984 IMPLICIT TAGS 2985 EXTENSIBILITY IMPLIED ::= 2986 2987 BEGIN 2988 2989 LDAPMessage ::= SEQUENCE { 2990 messageID MessageID, 2991 protocolOp CHOICE { 2992 bindRequest BindRequest, 2993 bindResponse BindResponse, 2994 unbindRequest UnbindRequest, 2995 searchRequest SearchRequest, 2996 searchResEntry SearchResultEntry, 2997 searchResDone SearchResultDone, 2998 searchResRef SearchResultReference, 2999 modifyRequest ModifyRequest, 3000 modifyResponse ModifyResponse, 3001 addRequest AddRequest, 3002 addResponse AddResponse, 3003 delRequest DelRequest, 3004 delResponse DelResponse, 3005 modDNRequest ModifyDNRequest, 3006 modDNResponse ModifyDNResponse, 3007 compareRequest CompareRequest, 3008 compareResponse CompareResponse, 3009 abandonRequest AbandonRequest, 3010 extendedReq ExtendedRequest, 3011 extendedResp ExtendedResponse, 3012 ..., 3013 intermediateResponse IntermediateResponse }, 3014 controls [0] Controls OPTIONAL } 3015 3016 MessageID ::= INTEGER (0 .. maxInt) 3017 3018 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) -- 3019 3020 LDAPString ::= OCTET STRING -- UTF-8 encoded, 3021 -- [ISO10646] characters 3022 3023 3024 3025 3026Sermersheim Standards Track [Page 54] 3027 3028RFC 4511 LDAPv3 June 2006 3029 3030 3031 LDAPOID ::= OCTET STRING -- Constrained to <numericoid> 3032 -- [RFC4512] 3033 3034 LDAPDN ::= LDAPString -- Constrained to <distinguishedName> 3035 -- [RFC4514] 3036 3037 RelativeLDAPDN ::= LDAPString -- Constrained to <name-component> 3038 -- [RFC4514] 3039 3040 AttributeDescription ::= LDAPString 3041 -- Constrained to <attributedescription> 3042 -- [RFC4512] 3043 3044 AttributeValue ::= OCTET STRING 3045 3046 AttributeValueAssertion ::= SEQUENCE { 3047 attributeDesc AttributeDescription, 3048 assertionValue AssertionValue } 3049 3050 AssertionValue ::= OCTET STRING 3051 3052 PartialAttribute ::= SEQUENCE { 3053 type AttributeDescription, 3054 vals SET OF value AttributeValue } 3055 3056 Attribute ::= PartialAttribute(WITH COMPONENTS { 3057 ..., 3058 vals (SIZE(1..MAX))}) 3059 3060 MatchingRuleId ::= LDAPString 3061 3062 LDAPResult ::= SEQUENCE { 3063 resultCode ENUMERATED { 3064 success (0), 3065 operationsError (1), 3066 protocolError (2), 3067 timeLimitExceeded (3), 3068 sizeLimitExceeded (4), 3069 compareFalse (5), 3070 compareTrue (6), 3071 authMethodNotSupported (7), 3072 strongerAuthRequired (8), 3073 -- 9 reserved -- 3074 referral (10), 3075 adminLimitExceeded (11), 3076 unavailableCriticalExtension (12), 3077 confidentialityRequired (13), 3078 saslBindInProgress (14), 3079 3080 3081 3082Sermersheim Standards Track [Page 55] 3083 3084RFC 4511 LDAPv3 June 2006 3085 3086 3087 noSuchAttribute (16), 3088 undefinedAttributeType (17), 3089 inappropriateMatching (18), 3090 constraintViolation (19), 3091 attributeOrValueExists (20), 3092 invalidAttributeSyntax (21), 3093 -- 22-31 unused -- 3094 noSuchObject (32), 3095 aliasProblem (33), 3096 invalidDNSyntax (34), 3097 -- 35 reserved for undefined isLeaf -- 3098 aliasDereferencingProblem (36), 3099 -- 37-47 unused -- 3100 inappropriateAuthentication (48), 3101 invalidCredentials (49), 3102 insufficientAccessRights (50), 3103 busy (51), 3104 unavailable (52), 3105 unwillingToPerform (53), 3106 loopDetect (54), 3107 -- 55-63 unused -- 3108 namingViolation (64), 3109 objectClassViolation (65), 3110 notAllowedOnNonLeaf (66), 3111 notAllowedOnRDN (67), 3112 entryAlreadyExists (68), 3113 objectClassModsProhibited (69), 3114 -- 70 reserved for CLDAP -- 3115 affectsMultipleDSAs (71), 3116 -- 72-79 unused -- 3117 other (80), 3118 ... }, 3119 matchedDN LDAPDN, 3120 diagnosticMessage LDAPString, 3121 referral [3] Referral OPTIONAL } 3122 3123 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI 3124 3125 URI ::= LDAPString -- limited to characters permitted in 3126 -- URIs 3127 3128 Controls ::= SEQUENCE OF control Control 3129 3130 Control ::= SEQUENCE { 3131 controlType LDAPOID, 3132 criticality BOOLEAN DEFAULT FALSE, 3133 controlValue OCTET STRING OPTIONAL } 3134 3135 3136 3137 3138Sermersheim Standards Track [Page 56] 3139 3140RFC 4511 LDAPv3 June 2006 3141 3142 3143 BindRequest ::= [APPLICATION 0] SEQUENCE { 3144 version INTEGER (1 .. 127), 3145 name LDAPDN, 3146 authentication AuthenticationChoice } 3147 3148 AuthenticationChoice ::= CHOICE { 3149 simple [0] OCTET STRING, 3150 -- 1 and 2 reserved 3151 sasl [3] SaslCredentials, 3152 ... } 3153 3154 SaslCredentials ::= SEQUENCE { 3155 mechanism LDAPString, 3156 credentials OCTET STRING OPTIONAL } 3157 3158 BindResponse ::= [APPLICATION 1] SEQUENCE { 3159 COMPONENTS OF LDAPResult, 3160 serverSaslCreds [7] OCTET STRING OPTIONAL } 3161 3162 UnbindRequest ::= [APPLICATION 2] NULL 3163 3164 SearchRequest ::= [APPLICATION 3] SEQUENCE { 3165 baseObject LDAPDN, 3166 scope ENUMERATED { 3167 baseObject (0), 3168 singleLevel (1), 3169 wholeSubtree (2), 3170 ... }, 3171 derefAliases ENUMERATED { 3172 neverDerefAliases (0), 3173 derefInSearching (1), 3174 derefFindingBaseObj (2), 3175 derefAlways (3) }, 3176 sizeLimit INTEGER (0 .. maxInt), 3177 timeLimit INTEGER (0 .. maxInt), 3178 typesOnly BOOLEAN, 3179 filter Filter, 3180 attributes AttributeSelection } 3181 3182 AttributeSelection ::= SEQUENCE OF selector LDAPString 3183 -- The LDAPString is constrained to 3184 -- <attributeSelector> in Section 4.5.1.8 3185 3186 Filter ::= CHOICE { 3187 and [0] SET SIZE (1..MAX) OF filter Filter, 3188 or [1] SET SIZE (1..MAX) OF filter Filter, 3189 not [2] Filter, 3190 equalityMatch [3] AttributeValueAssertion, 3191 3192 3193 3194Sermersheim Standards Track [Page 57] 3195 3196RFC 4511 LDAPv3 June 2006 3197 3198 3199 substrings [4] SubstringFilter, 3200 greaterOrEqual [5] AttributeValueAssertion, 3201 lessOrEqual [6] AttributeValueAssertion, 3202 present [7] AttributeDescription, 3203 approxMatch [8] AttributeValueAssertion, 3204 extensibleMatch [9] MatchingRuleAssertion, 3205 ... } 3206 3207 SubstringFilter ::= SEQUENCE { 3208 type AttributeDescription, 3209 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE { 3210 initial [0] AssertionValue, -- can occur at most once 3211 any [1] AssertionValue, 3212 final [2] AssertionValue } -- can occur at most once 3213 } 3214 3215 MatchingRuleAssertion ::= SEQUENCE { 3216 matchingRule [1] MatchingRuleId OPTIONAL, 3217 type [2] AttributeDescription OPTIONAL, 3218 matchValue [3] AssertionValue, 3219 dnAttributes [4] BOOLEAN DEFAULT FALSE } 3220 3221 SearchResultEntry ::= [APPLICATION 4] SEQUENCE { 3222 objectName LDAPDN, 3223 attributes PartialAttributeList } 3224 3225 PartialAttributeList ::= SEQUENCE OF 3226 partialAttribute PartialAttribute 3227 3228 SearchResultReference ::= [APPLICATION 19] SEQUENCE 3229 SIZE (1..MAX) OF uri URI 3230 3231 SearchResultDone ::= [APPLICATION 5] LDAPResult 3232 3233 ModifyRequest ::= [APPLICATION 6] SEQUENCE { 3234 object LDAPDN, 3235 changes SEQUENCE OF change SEQUENCE { 3236 operation ENUMERATED { 3237 add (0), 3238 delete (1), 3239 replace (2), 3240 ... }, 3241 modification PartialAttribute } } 3242 3243 ModifyResponse ::= [APPLICATION 7] LDAPResult 3244 3245 3246 3247 3248 3249 3250Sermersheim Standards Track [Page 58] 3251 3252RFC 4511 LDAPv3 June 2006 3253 3254 3255 AddRequest ::= [APPLICATION 8] SEQUENCE { 3256 entry LDAPDN, 3257 attributes AttributeList } 3258 3259 AttributeList ::= SEQUENCE OF attribute Attribute 3260 3261 AddResponse ::= [APPLICATION 9] LDAPResult 3262 3263 DelRequest ::= [APPLICATION 10] LDAPDN 3264 3265 DelResponse ::= [APPLICATION 11] LDAPResult 3266 3267 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE { 3268 entry LDAPDN, 3269 newrdn RelativeLDAPDN, 3270 deleteoldrdn BOOLEAN, 3271 newSuperior [0] LDAPDN OPTIONAL } 3272 3273 ModifyDNResponse ::= [APPLICATION 13] LDAPResult 3274 3275 CompareRequest ::= [APPLICATION 14] SEQUENCE { 3276 entry LDAPDN, 3277 ava AttributeValueAssertion } 3278 3279 CompareResponse ::= [APPLICATION 15] LDAPResult 3280 3281 AbandonRequest ::= [APPLICATION 16] MessageID 3282 3283 ExtendedRequest ::= [APPLICATION 23] SEQUENCE { 3284 requestName [0] LDAPOID, 3285 requestValue [1] OCTET STRING OPTIONAL } 3286 3287 ExtendedResponse ::= [APPLICATION 24] SEQUENCE { 3288 COMPONENTS OF LDAPResult, 3289 responseName [10] LDAPOID OPTIONAL, 3290 responseValue [11] OCTET STRING OPTIONAL } 3291 3292 IntermediateResponse ::= [APPLICATION 25] SEQUENCE { 3293 responseName [0] LDAPOID OPTIONAL, 3294 responseValue [1] OCTET STRING OPTIONAL } 3295 3296 END 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306Sermersheim Standards Track [Page 59] 3307 3308RFC 4511 LDAPv3 June 2006 3309 3310 3311Appendix C. Changes 3312 3313 This appendix is non-normative. 3314 3315 This appendix summarizes substantive changes made to RFC 2251, RFC 3316 2830, and RFC 3771. 3317 3318C.1. Changes Made to RFC 2251 3319 3320 This section summarizes the substantive changes made to Sections 1, 3321 2, 3.1, and 4, and the remainder of RFC 2251. Readers should 3322 consult [RFC4512] and [RFC4513] for summaries of changes to other 3323 sections. 3324 3325C.1.1. Section 1 (Status of this Memo) 3326 3327 - Removed IESG note. Post publication of RFC 2251, mandatory LDAP 3328 authentication mechanisms have been standardized which are 3329 sufficient to remove this note. See [RFC4513] for authentication 3330 mechanisms. 3331 3332C.1.2. Section 3.1 (Protocol Model) and others 3333 3334 - Removed notes giving history between LDAP v1, v2, and v3. Instead, 3335 added sufficient language so that this document can stand on its 3336 own. 3337 3338C.1.3. Section 4 (Elements of Protocol) 3339 3340 - Clarified where the extensibility features of ASN.1 apply to the 3341 protocol. This change affected various ASN.1 types by the 3342 inclusion of ellipses (...) to certain elements. 3343 - Removed the requirement that servers that implement version 3 or 3344 later MUST provide the 'supportedLDAPVersion' attribute. This 3345 statement provided no interoperability advantages. 3346 3347C.1.4. Section 4.1.1 (Message Envelope) 3348 3349 - There was a mandatory requirement for the server to return a 3350 Notice of Disconnection and drop the transport connection when a 3351 PDU is malformed in a certain way. This has been updated such that 3352 the server SHOULD return the Notice of Disconnection, and it MUST 3353 terminate the LDAP Session. 3354 3355C.1.5. Section 4.1.1.1 (Message ID) 3356 3357 - Required that the messageID of requests MUST be non-zero as the 3358 zero is reserved for Notice of Disconnection. 3359 3360 3361 3362Sermersheim Standards Track [Page 60] 3363 3364RFC 4511 LDAPv3 June 2006 3365 3366 3367 - Specified when it is and isn't appropriate to return an already 3368 used messageID. RFC 2251 accidentally imposed synchronous server 3369 behavior in its wording of this. 3370 3371C.1.6. Section 4.1.2 (String Types) 3372 3373 - Stated that LDAPOID is constrained to <numericoid> from [RFC4512]. 3374 3375C.1.7. Section 4.1.5.1 (Binary Option) and others 3376 3377 - Removed the Binary Option from the specification. There are 3378 numerous interoperability problems associated with this method of 3379 alternate attribute type encoding. Work to specify a suitable 3380 replacement is ongoing. 3381 3382C.1.8. Section 4.1.8 (Attribute) 3383 3384 - Combined the definitions of PartialAttribute and Attribute here, 3385 and defined Attribute in terms of PartialAttribute. 3386 3387C.1.9. Section 4.1.10 (Result Message) 3388 3389 - Renamed "errorMessage" to "diagnosticMessage" as it is allowed to 3390 be sent for non-error results. 3391 - Moved some language into Appendix A, and referred the reader there. 3392 - Allowed matchedDN to be present for other result codes than those 3393 listed in RFC 2251. 3394 - Renamed the code "strongAuthRequired" to "strongerAuthRequired" to 3395 clarify that this code may often be returned to indicate that a 3396 stronger authentication is needed to perform a given operation. 3397 3398C.1.10. Section 4.1.11 (Referral) 3399 3400 - Defined referrals in terms of URIs rather than URLs. 3401 - Removed the requirement that all referral URIs MUST be equally 3402 capable of progressing the operation. The statement was ambiguous 3403 and provided no instructions on how to carry it out. 3404 - Added the requirement that clients MUST NOT loop between servers. 3405 - Clarified the instructions for using LDAPURLs in referrals, and in 3406 doing so added a recommendation that the scope part be present. 3407 - Removed imperatives which required clients to use URLs in specific 3408 ways to progress an operation. These did nothing for 3409 interoperability. 3410 3411 3412 3413 3414 3415 3416 3417 3418Sermersheim Standards Track [Page 61] 3419 3420RFC 4511 LDAPv3 June 2006 3421 3422 3423C.1.11. Section 4.1.12 (Controls) 3424 3425 - Specified how control values defined in terms of ASN.1 are to be 3426 encoded. 3427 - Noted that the criticality field is only applied to request 3428 messages (except UnbindRequest), and must be ignored when present 3429 on response messages and UnbindRequest. 3430 - Specified that non-critical controls may be ignored at the 3431 server's discretion. There was confusion in the original wording 3432 which led some to believe that recognized controls may not be 3433 ignored as long as they were associated with a proper request. 3434 - Added language regarding combinations of controls and the ordering 3435 of controls on a message. 3436 - Specified that when the semantics of the combination of controls 3437 is undefined or unknown, it results in a protocolError. 3438 - Changed "The server MUST be prepared" to "Implementations MUST be 3439 prepared" in paragraph 8 to reflect that both client and server 3440 implementations must be able to handle this (as both parse 3441 controls). 3442 3443C.1.12. Section 4.2 (Bind Operation) 3444 3445 - Mandated that servers return protocolError when the version is not 3446 supported. 3447 - Disambiguated behavior when the simple authentication is used, the 3448 name is empty, and the password is non-empty. 3449 - Required servers to not dereference aliases for Bind. This was 3450 added for consistency with other operations and to help ensure 3451 data consistency. 3452 - Required that textual passwords be transferred as UTF-8 encoded 3453 Unicode, and added recommendations on string preparation. This was 3454 to help ensure interoperability of passwords being sent from 3455 different clients. 3456 3457C.1.13. Section 4.2.1 (Sequencing of the Bind Request) 3458 3459 - This section was largely reorganized for readability, and language 3460 was added to clarify the authentication state of failed and 3461 abandoned Bind operations. 3462 - Removed: "If a SASL transfer encryption or integrity mechanism has 3463 been negotiated, that mechanism does not support the changing of 3464 credentials from one identity to another, then the client MUST 3465 instead establish a new connection." 3466 If there are dependencies between multiple negotiations of a 3467 particular SASL mechanism, the technical specification for that 3468 SASL mechanism details how applications are to deal with them. 3469 LDAP should not require any special handling. 3470 - Dropped MUST imperative in paragraph 3 to align with [RFC2119]. 3471 3472 3473 3474Sermersheim Standards Track [Page 62] 3475 3476RFC 4511 LDAPv3 June 2006 3477 3478 3479 - Mandated that clients not send non-Bind operations while a Bind is 3480 in progress, and suggested that servers not process them if they 3481 are received. This is needed to ensure proper sequencing of the 3482 Bind in relationship to other operations. 3483 3484C.1.14. Section 4.2.3 (Bind Response) 3485 3486 - Moved most error-related text to Appendix A, and added text 3487 regarding certain errors used in conjunction with the Bind 3488 operation. 3489 - Prohibited the server from specifying serverSaslCreds when not 3490 appropriate. 3491 3492C.1.15. Section 4.3 (Unbind Operation) 3493 3494 - Specified that both peers are to cease transmission and terminate 3495 the LDAP session for the Unbind operation. 3496 3497C.1.16. Section 4.4 (Unsolicited Notification) 3498 3499 - Added instructions for future specifications of Unsolicited 3500 Notifications. 3501 3502C.1.17. Section 4.5.1 (Search Request) 3503 3504 - SearchRequest attributes is now defined as an AttributeSelection 3505 type rather than AttributeDescriptionList, and an ABNF is 3506 provided. 3507 - SearchRequest attributes may contain duplicate attribute 3508 descriptions. This was previously prohibited. Now servers are 3509 instructed to ignore subsequent names when they are duplicated. 3510 This was relaxed in order to allow different short names and also 3511 OIDs to be requested for an attribute. 3512 - The present search filter now evaluates to Undefined when the 3513 specified attribute is not known to the server. It used to 3514 evaluate to FALSE, which caused behavior inconsistent with what 3515 most would expect, especially when the 'not' operator was used. 3516 - The Filter choice SubstringFilter substrings type is now defined 3517 with a lower bound of 1. 3518 - The SubstringFilter substrings 'initial, 'any', and 'final' types 3519 are now AssertionValue rather than LDAPString. Also, added 3520 imperatives stating that 'initial' (if present) must be listed 3521 first, and 'final' (if present) must be listed last. 3522 - Disambiguated the semantics of the derefAliases choices. There was 3523 question as to whether derefInSearching applied to the base object 3524 in a wholeSubtree Search. 3525 - Added instructions for equalityMatch, substrings, greaterOrEqual, 3526 lessOrEqual, and approxMatch. 3527 3528 3529 3530Sermersheim Standards Track [Page 63] 3531 3532RFC 4511 LDAPv3 June 2006 3533 3534 3535 3536C.1.18. Section 4.5.2 (Search Result) 3537 3538 - Recommended that servers not use attribute short names when it 3539 knows they are ambiguous or may cause interoperability problems. 3540 - Removed all mention of ExtendedResponse due to lack of 3541 implementation. 3542 3543C.1.19. Section 4.5.3 (Continuation References in the Search Result) 3544 3545 - Made changes similar to those made to Section 4.1.11. 3546 3547C.1.20. Section 4.5.3.1 (Example) 3548 3549 - Fixed examples to adhere to changes made to Section 4.5.3. 3550 3551C.1.21. Section 4.6 (Modify Operation) 3552 3553 - Replaced AttributeTypeAndValues with Attribute as they are 3554 equivalent. 3555 - Specified the types of modification changes that might 3556 temporarily violate schema. Some readers were under the impression 3557 that any temporary schema violation was allowed. 3558 3559C.1.22. Section 4.7 (Add Operation) 3560 3561 - Aligned Add operation with X.511 in that the attributes of the RDN 3562 are used in conjunction with the listed attributes to create the 3563 entry. Previously, Add required that the distinguished values be 3564 present in the listed attributes. 3565 - Removed requirement that the objectClass attribute MUST be 3566 specified as some DSE types do not require this attribute. 3567 Instead, generic wording was added, requiring the added entry to 3568 adhere to the data model. 3569 - Removed recommendation regarding placement of objects. This is 3570 covered in the data model document. 3571 3572C.1.23. Section 4.9 (Modify DN Operation) 3573 3574 - Required servers to not dereference aliases for Modify DN. This 3575 was added for consistency with other operations and to help ensure 3576 data consistency. 3577 - Allow Modify DN to fail when moving between naming contexts. 3578 - Specified what happens when the attributes of the newrdn are not 3579 present on the entry. 3580 3581 3582 3583 3584 3585 3586Sermersheim Standards Track [Page 64] 3587 3588RFC 4511 LDAPv3 June 2006 3589 3590 3591C.1.24. Section 4.10 (Compare Operation) 3592 3593 - Specified that compareFalse means that the Compare took place and 3594 the result is false. There was confusion that led people to 3595 believe that an Undefined match resulted in compareFalse. 3596 - Required servers to not dereference aliases for Compare. This was 3597 added for consistency with other operations and to help ensure 3598 data consistency. 3599 3600C.1.25. Section 4.11 (Abandon Operation) 3601 3602 - Explained that since Abandon returns no response, clients should 3603 not use it if they need to know the outcome. 3604 - Specified that Abandon and Unbind cannot be abandoned. 3605 3606C.1.26. Section 4.12 (Extended Operation) 3607 3608 - Specified how values of Extended operations defined in terms of 3609 ASN.1 are to be encoded. 3610 - Added instructions on what Extended operation specifications 3611 consist of. 3612 - Added a recommendation that servers advertise supported Extended 3613 operations. 3614 3615C.1.27. Section 5.2 (Transfer Protocols) 3616 3617 - Moved referral-specific instructions into referral-related 3618 sections. 3619 3620C.1.28. Section 7 (Security Considerations) 3621 3622 - Reworded notes regarding SASL not protecting certain aspects of 3623 the LDAP Bind messages. 3624 - Noted that Servers are encouraged to prevent directory 3625 modifications by clients that have authenticated anonymously 3626 [RFC4513]. 3627 - Added a note regarding the possibility of changes to security 3628 factors (authentication, authorization, and data confidentiality). 3629 - Warned against following referrals that may have been injected in 3630 the data stream. 3631 - Noted that servers should protect information equally, whether in 3632 an error condition or not, and mentioned matchedDN, 3633 diagnosticMessage, and resultCodes specifically. 3634 - Added a note regarding malformed and long encodings. 3635 3636 3637 3638 3639 3640 3641 3642Sermersheim Standards Track [Page 65] 3643 3644RFC 4511 LDAPv3 June 2006 3645 3646 3647C.1.29. Appendix A (Complete ASN.1 Definition) 3648 3649 - Added "EXTENSIBILITY IMPLIED" to ASN.1 definition. 3650 - Removed AttributeType. It is not used. 3651 3652C.2. Changes Made to RFC 2830 3653 3654 This section summarizes the substantive changes made to Sections of 3655 RFC 2830. Readers should consult [RFC4513] for summaries of changes 3656 to other sections. 3657 3658C.2.1. Section 2.3 (Response other than "success") 3659 3660 - Removed wording indicating that referrals can be returned from 3661 StartTLS. 3662 - Removed requirement that only a narrow set of result codes can be 3663 returned. Some result codes are required in certain scenarios, but 3664 any other may be returned if appropriate. 3665 - Removed requirement that the ExtendedResponse.responseName MUST be 3666 present. There are circumstances where this is impossible, and 3667 requiring this is at odds with language in Section 4.12. 3668 3669C.2.1. Section 4 (Closing a TLS Connection) 3670 3671 - Reworded most of this section to align with definitions of the 3672 LDAP protocol layers. 3673 - Removed instructions on abrupt closure as this is covered in other 3674 areas of the document (specifically, Section 5.3) 3675 3676C.3. Changes Made to RFC 3771 3677 3678 - Rewrote to fit into this document. In general, semantics were 3679 preserved. Supporting and background language seen as redundant 3680 due to its presence in this document was omitted. 3681 3682 - Specified that Intermediate responses to a request may be of 3683 different types, and one of the response types may be specified to 3684 have no response value. 3685 3686 3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3697 3698Sermersheim Standards Track [Page 66] 3699 3700RFC 4511 LDAPv3 June 2006 3701 3702 3703Editor's Address 3704 3705 Jim Sermersheim 3706 Novell, Inc. 3707 1800 South Novell Place 3708 Provo, Utah 84606, USA 3709 3710 Phone: +1 801 861-3088 3711 EMail: jimse@novell.com 3712 3713 3714 3715 3716 3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754Sermersheim Standards Track [Page 67] 3755 3756RFC 4511 LDAPv3 June 2006 3757 3758 3759Full Copyright Statement 3760 3761 Copyright (C) The Internet Society (2006). 3762 3763 This document is subject to the rights, licenses and restrictions 3764 contained in BCP 78, and except as set forth therein, the authors 3765 retain all their rights. 3766 3767 This document and the information contained herein are provided on an 3768 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 3769 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 3770 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 3771 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 3772 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 3773 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3774 3775Intellectual Property 3776 3777 The IETF takes no position regarding the validity or scope of any 3778 Intellectual Property Rights or other rights that might be claimed to 3779 pertain to the implementation or use of the technology described in 3780 this document or the extent to which any license under such rights 3781 might or might not be available; nor does it represent that it has 3782 made any independent effort to identify any such rights. Information 3783 on the procedures with respect to rights in RFC documents can be 3784 found in BCP 78 and BCP 79. 3785 3786 Copies of IPR disclosures made to the IETF Secretariat and any 3787 assurances of licenses to be made available, or the result of an 3788 attempt made to obtain a general license or permission for the use of 3789 such proprietary rights by implementers or users of this 3790 specification can be obtained from the IETF on-line IPR repository at 3791 http://www.ietf.org/ipr. 3792 3793 The IETF invites any interested party to bring to its attention any 3794 copyrights, patents or patent applications, or other proprietary 3795 rights that may cover technology that may be required to implement 3796 this standard. Please address the information to the IETF at 3797 ietf-ipr@ietf.org. 3798 3799Acknowledgement 3800 3801 Funding for the RFC Editor function is provided by the IETF 3802 Administrative Support Activity (IASA). 3803 3804 3805 3806 3807 3808 3809 3810Sermersheim Standards Track [Page 68] 3811 3812