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