1 Internet-Draft Editor: J. Sermersheim
2 Intended Category: Standard Track Novell, Inc
3 Document: draft-ietf-ldapbis-protocol-30.txt Feb 2005
4 Obsoletes: RFCs 2251, 2830, 3771
12 This document is an Internet-Draft and is subject to all provisions
13 of section 3 of RFC 3667. By submitting this Internet-Draft, each
14 author represents that any applicable patent or other IPR claims of
15 which he or she is aware have been or will be disclosed, and any of
16 which he or she become aware will be disclosed, in accordance with
19 Internet-Drafts are working documents of the Internet Engineering
20 Task Force (IETF), its areas, and its working groups. Note that other
21 groups may also distribute working documents as Internet-Drafts.
23 Internet-Drafts are draft documents valid for a maximum of six months
24 and may be updated, replaced, or obsoleted by other documents at any
25 time. It is inappropriate to use Internet-Drafts as reference
26 material or to cite them other than as "work in progress".
28 The list of current Internet-Drafts can be accessed at
29 <http://www.ietf.org/ietf/1id-abstracts.txt>.
31 The list of Internet-Draft Shadow Directories can be accessed at
32 <http://www.ietf.org/shadow.html>.
34 This Internet-Draft will expire in February 2005.
36 Technical discussion of this document will take place on the IETF
37 LDAP Revision Working Group (LDAPbis) mailing list <ietf-
38 ldapbis@openldap.org>. Please send editorial comments directly to the
39 editor <jimse@novell.com>.
44 Copyright (C) The Internet Society 2004. All Rights Reserved.
48 This document describes the protocol elements, along with their
49 semantics and encodings, of the Lightweight Directory Access Protocol
50 (LDAP). LDAP provides access to distributed directory services that
51 act in accordance with X.500 data and service models. These protocol
52 elements are based on those described in the X.500 Directory Access
56 Sermersheim Internet-Draft - Expires Aug 2005 Page 1
58 Lightweight Directory Access Protocol Version 3
63 1. Introduction....................................................3
64 1.1. Relationship to Other LDAP Specifications.....................3
65 2. Conventions.....................................................3
66 3. Protocol Model..................................................4
67 3.1 Operation and LDAP Message Layer Relationship..................5
68 4. Elements of Protocol............................................5
69 4.1. Common Elements...............................................5
70 4.1.1. Message Envelope............................................5
71 4.1.2. String Types................................................7
72 4.1.3. Distinguished Name and Relative Distinguished Name..........7
73 4.1.4. Attribute Descriptions......................................8
74 4.1.5. Attribute Value.............................................8
75 4.1.6. Attribute Value Assertion...................................8
76 4.1.7. Attribute and PartialAttribute..............................9
77 4.1.8. Matching Rule Identifier....................................9
78 4.1.9. Result Message..............................................9
79 4.1.10. Referral..................................................11
80 4.1.11. Controls..................................................13
81 4.2. Bind Operation...............................................14
82 4.3. Unbind Operation.............................................17
83 4.4. Unsolicited Notification.....................................17
84 4.5. Search Operation.............................................18
85 4.6. Modify Operation.............................................29
86 4.7. Add Operation................................................31
87 4.8. Delete Operation.............................................31
88 4.9. Modify DN Operation..........................................32
89 4.10. Compare Operation...........................................33
90 4.11. Abandon Operation...........................................34
91 4.12. Extended Operation..........................................35
92 4.13. IntermediateResponse Message................................36
93 4.14. StartTLS Operation..........................................37
94 5. Protocol Encoding, Connection, and Transfer....................39
95 5.1. Protocol Encoding............................................40
96 5.2. Transmission Control Protocol (TCP)..........................40
97 5.3. Termination of the LDAP session..............................40
98 6. Security Considerations........................................41
99 7. Acknowledgements...............................................42
100 8. Normative References...........................................42
101 9. Informative References.........................................44
102 10. IANA Considerations...........................................44
103 11. Editor's Address..............................................45
104 Appendix A - LDAP Result Codes....................................46
105 A.1 Non-Error Result Codes........................................46
106 A.2 Result Codes..................................................46
107 Appendix B - Complete ASN.1 Definition............................51
108 Appendix C - Changes..............................................57
109 C.1 Changes made to RFC 2251:.....................................57
110 C.2 Changes made to RFC 2830:.....................................62
111 C.3 Changes made to RFC 3771:.....................................63
115 Sermersheim Internet-Draft - Expires Aug 2005 Page 2
117 Lightweight Directory Access Protocol Version 3
121 The Directory is "a collection of open systems cooperating to provide
122 directory services" [X.500]. A directory user, which may be a human
123 or other entity, accesses the Directory through a client (or
124 Directory User Agent (DUA)). The client, on behalf of the directory
125 user, interacts with one or more servers (or Directory System Agents
126 (DSA)). Clients interact with servers using a directory access
129 This document details the protocol elements of the Lightweight
130 Directory Access Protocol (LDAP), along with their semantics.
131 Following the description of protocol elements, it describes the way
132 in which the protocol elements are encoded and transferred.
135 1.1. Relationship to Other LDAP Specifications
137 This document is an integral part of the LDAP Technical Specification
138 [Roadmap] which obsoletes the previously defined LDAP technical
139 specification, RFC 3377, in its entirety.
141 This document obsoletes all of RFC 2251 except the following:
142 Sections 3.2, 3.4, 4.1.3 (last paragraph), 4.1.4, 4.1.5, 4.1.5.1,
143 4.1.9 (last paragraph), 5.1, 6.1, and 6.2 (last paragraph) are
144 obsoleted by [Models].
145 Section 3.3 is obsoleted by [Roadmap].
146 Sections 4.2.1 (portions), and 4.2.2 are obsoleted by [AuthMeth].
148 Appendix C.1 summarizes substantive changes to the remaining
151 This document obsoletes RFC 2830, Sections 2 and 4 in entirety. The
152 remainder of RFC 2830 is obsoleted by [AuthMeth]. Appendix C.2
153 summarizes substantive changes to the remaining sections.
155 This document also obsoletes RFC 3771 in entirety.
160 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
161 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
162 to be interpreted as described in [Keyword].
164 Character names in this document use the notation for code points and
165 names from the Unicode Standard [Unicode]. For example, the letter
166 "a" may be represented as either <U+0061> or <LATIN SMALL LETTER A>.
168 Note: a glossary of terms used in Unicode can be found in [Glossary].
169 Information on the Unicode character encoding model can be found in
174 Sermersheim Internet-Draft - Expires Aug 2005 Page 3
176 Lightweight Directory Access Protocol Version 3
178 The term "transport connection" refers to the underlying transport
179 services used to carry the protocol exchange, as well as associations
180 established by these services.
182 The term "TLS layer" refers to TLS services used in providing
183 security services, as well as associations established by these
186 The term "SASL layer" refers to SASL services used in providing
187 security services, as well as associations established by these
190 The term "LDAP message layer" refers to the LDAP Message (PDU)
191 services used in providing directory services, as well as
192 associations established by these services.
194 The term "LDAP session" refers to combined services (transport
195 connection, TLS layer, SASL layer, LDAP message layer) and their
198 See the table in Section 5 for an illustration of these four terms.
203 The general model adopted by this protocol is one of clients
204 performing protocol operations against servers. In this model, a
205 client transmits a protocol request describing the operation to be
206 performed to a server. The server is then responsible for performing
207 the necessary operation(s) in the Directory. Upon completion of an
208 operation, the server typically returns a response containing
209 appropriate data to the requesting client.
211 Protocol operations are generally independent of one another. Each
212 operation is processed as an atomic action, leaving the directory in
215 Although servers are required to return responses whenever such
216 responses are defined in the protocol, there is no requirement for
217 synchronous behavior on the part of either clients or servers.
218 Requests and responses for multiple operations generally may be
219 exchanged between a client and server in any order. If required,
220 synchronous behavior may be controlled by client applications.
222 The core protocol operations defined in this document can be mapped
223 to a subset of the X.500 (1993) Directory Abstract Service [X.511].
224 However there is not a one-to-one mapping between LDAP operations and
225 X.500 Directory Access Protocol (DAP) operations. Server
226 implementations acting as a gateway to X.500 directories may need to
227 make multiple DAP requests to service a single LDAP request.
233 Sermersheim Internet-Draft - Expires Aug 2005 Page 4
235 Lightweight Directory Access Protocol Version 3
238 3.1 Operation and LDAP Message Layer Relationship
240 Protocol operations are exchanged at the LDAP message layer. When the
241 transport connection is closed, any uncompleted operations at the
242 LDAP message layer, when possible, are abandoned, and when not
243 possible, are completed without transmission of the response. Also,
244 when the transport connection is closed, the client MUST NOT assume
245 that any uncompleted update operations have succeeded or failed.
248 4. Elements of Protocol
250 The protocol is described using Abstract Syntax Notation One
251 ([ASN.1]), and is transferred using a subset of ASN.1 Basic Encoding
252 Rules ([BER]). Section 5 specifies how the protocol elements are
253 encoded and transferred.
255 In order to support future extensions to this protocol, extensibility
256 is implied where it is allowed per ASN.1 (i.e. sequence, set, choice,
257 and enumerated types are extensible). In addition, ellipses (...)
258 have been supplied in ASN.1 types that are explicitly extensible as
259 discussed in [LDAPIANA]. Because of the implied extensibility,
260 clients and servers MUST (unless otherwise specified) ignore trailing
261 SEQUENCE components whose tags they do not recognize.
263 Changes to the protocol other than through the extension mechanisms
264 described here require a different version number. A client indicates
265 the version it is using as part of the BindRequest, described in
266 Section 4.2. If a client has not sent a Bind, the server MUST assume
267 the client is using version 3 or later.
269 Clients may attempt to determine the protocol versions a server
270 supports by reading the 'supportedLDAPVersion' attribute from the
271 root DSE (DSA-Specific Entry) [Models].
276 This section describes the LDAPMessage envelope Protocol Data Unit
277 (PDU) format, as well as data type definitions, which are used in the
281 4.1.1. Message Envelope
283 For the purposes of protocol exchanges, all protocol operations are
284 encapsulated in a common envelope, the LDAPMessage, which is defined
292 Sermersheim Internet-Draft - Expires Aug 2005 Page 5
294 Lightweight Directory Access Protocol Version 3
296 LDAPMessage ::= SEQUENCE {
299 bindRequest BindRequest,
300 bindResponse BindResponse,
301 unbindRequest UnbindRequest,
302 searchRequest SearchRequest,
303 searchResEntry SearchResultEntry,
304 searchResDone SearchResultDone,
305 searchResRef SearchResultReference,
306 modifyRequest ModifyRequest,
307 modifyResponse ModifyResponse,
308 addRequest AddRequest,
309 addResponse AddResponse,
310 delRequest DelRequest,
311 delResponse DelResponse,
312 modDNRequest ModifyDNRequest,
313 modDNResponse ModifyDNResponse,
314 compareRequest CompareRequest,
315 compareResponse CompareResponse,
316 abandonRequest AbandonRequest,
317 extendedReq ExtendedRequest,
318 extendedResp ExtendedResponse,
320 intermediateResponse IntermediateResponse },
321 controls [0] Controls OPTIONAL }
323 MessageID ::= INTEGER (0 .. maxInt)
325 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
327 The ASN.1 type Controls is defined in Section 4.1.11.
329 The function of the LDAPMessage is to provide an envelope containing
330 common fields required in all protocol exchanges. At this time the
331 only common fields are the messageID and the controls.
333 If the server receives a PDU from the client in which the LDAPMessage
334 SEQUENCE tag cannot be recognized, the messageID cannot be parsed,
335 the tag of the protocolOp is not recognized as a request, or the
336 encoding structures or lengths of data fields are found to be
337 incorrect, then the server SHOULD return the Notice of Disconnection
338 described in Section 4.4.1, with the resultCode set to protocolError,
339 and MUST immediately terminate the LDAP session as described in
342 In other cases where the client or server cannot parse a PDU, it
343 SHOULD abruptly terminate the LDAP session (Section 5.3) where
344 further communication (including providing notice) would be
345 pernicious. Otherwise, server implementations MUST return an
346 appropriate response to the request, with the resultCode set to
351 Sermersheim Internet-Draft - Expires Aug 2005 Page 6
353 Lightweight Directory Access Protocol Version 3
357 All LDAPMessage envelopes encapsulating responses contain the
358 messageID value of the corresponding request LDAPMessage.
360 The message ID of a request MUST have a non-zero value different from
361 the messageID of any other request in progress in the same LDAP
362 session. The zero value is reserved for the unsolicited notification
365 Typical clients increment a counter for each request.
367 A client MUST NOT send a request with the same message ID as an
368 earlier request in the same LDAP session unless it can be determined
369 that the server is no longer servicing the earlier request (e.g.
370 after the final response is received, or a subsequent Bind
371 completes). Otherwise the behavior is undefined. For this purpose,
372 note that Abandon and successfully abandoned operations do not send
378 The LDAPString is a notational convenience to indicate that, although
379 strings of LDAPString type encode as ASN.1 OCTET STRING types, the
380 [ISO10646] character set (a superset of [Unicode]) is used, encoded
381 following the [UTF-8] algorithm. Note that Unicode characters U+0000
382 through U+007F are the same as ASCII 0 through 127, respectively, and
383 have the same single octet UTF-8 encoding. Other Unicode characters
384 have a multiple octet UTF-8 encoding.
386 LDAPString ::= OCTET STRING -- UTF-8 encoded,
387 -- [ISO10646] characters
389 The LDAPOID is a notational convenience to indicate that the
390 permitted value of this string is a (UTF-8 encoded) dotted-decimal
391 representation of an OBJECT IDENTIFIER. Although an LDAPOID is
392 encoded as an OCTET STRING, values are limited to the definition of
393 <numericoid> given in Section 1.4 of [Models].
395 LDAPOID ::= OCTET STRING -- Constrained to <numericoid> [Models]
399 1.3.6.1.4.1.1466.1.2.3
402 4.1.3. Distinguished Name and Relative Distinguished Name
404 An LDAPDN is defined to be the representation of a Distinguished Name
405 (DN) after encoding according to the specification in [LDAPDN].
407 LDAPDN ::= LDAPString
408 -- Constrained to <distinguishedName> [LDAPDN]
410 Sermersheim Internet-Draft - Expires Aug 2005 Page 7
412 Lightweight Directory Access Protocol Version 3
415 A RelativeLDAPDN is defined to be the representation of a Relative
416 Distinguished Name (RDN) after encoding according to the
417 specification in [LDAPDN].
419 RelativeLDAPDN ::= LDAPString
420 -- Constrained to <name-component> [LDAPDN]
423 4.1.4. Attribute Descriptions
425 The definition and encoding rules for attribute descriptions are
426 defined in Section 2.5 of [Models]. Briefly, an attribute description
427 is an attribute type and zero or more options.
429 AttributeDescription ::= LDAPString
430 -- Constrained to <attributedescription>
434 4.1.5. Attribute Value
436 A field of type AttributeValue is an OCTET STRING containing an
437 encoded attribute value. The attribute value is encoded according to
438 the LDAP-specific encoding definition of its corresponding syntax.
439 The LDAP-specific encoding definitions for different syntaxes and
440 attribute types may be found in other documents and in particular
443 AttributeValue ::= OCTET STRING
445 Note that there is no defined limit on the size of this encoding;
446 thus protocol values may include multi-megabyte attribute values
449 Attribute values may be defined which have arbitrary and non-
450 printable syntax. Implementations MUST NOT display nor attempt to
451 decode an attribute value if its syntax is not known. The
452 implementation may attempt to discover the subschema of the source
453 entry, and retrieve the descriptions of 'attributeTypes' from it
456 Clients MUST only send attribute values in a request that are valid
457 according to the syntax defined for the attributes.
460 4.1.6. Attribute Value Assertion
462 The AttributeValueAssertion (AVA) type definition is similar to the
463 one in the X.500 Directory standards. It contains an attribute
464 description and a matching rule ([Models] Section 4.1.3) assertion
465 value suitable for that type. Elements of this type are typically
466 used to assert that the value in assertionValue matches a value of an
469 Sermersheim Internet-Draft - Expires Aug 2005 Page 8
471 Lightweight Directory Access Protocol Version 3
474 AttributeValueAssertion ::= SEQUENCE {
475 attributeDesc AttributeDescription,
476 assertionValue AssertionValue }
478 AssertionValue ::= OCTET STRING
480 The syntax of the AssertionValue depends on the context of the LDAP
481 operation being performed. For example, the syntax of the EQUALITY
482 matching rule for an attribute is used when performing a Compare
483 operation. Often this is the same syntax used for values of the
484 attribute type, but in some cases the assertion syntax differs from
485 the value syntax. See objectIdentiferFirstComponentMatch in
486 [Syntaxes] for an example.
489 4.1.7. Attribute and PartialAttribute
491 Attributes and partial attributes consist of an attribute description
492 and attribute values. A PartialAttribute allows zero values, while
493 Attribute requires at least one value.
495 PartialAttribute ::= SEQUENCE {
496 type AttributeDescription,
497 vals SET OF value AttributeValue }
499 Attribute ::= PartialAttribute(WITH COMPONENTS {
501 vals (SIZE(1..MAX))})
503 No two of the attribute values may be equivalent as described by
504 Section 2.3 of [Models]. The set of attribute values is unordered.
505 Implementations MUST NOT rely upon the ordering being repeatable.
508 4.1.8. Matching Rule Identifier
510 Matching rules are defined in Section 4.1.3 of [Models]. A matching
511 rule is identified in the protocol by the printable representation of
512 either its <numericoid>, or one of its short name descriptors
513 [Models], e.g. 'caseIgnoreMatch' or '2.5.13.2'.
515 MatchingRuleId ::= LDAPString
518 4.1.9. Result Message
520 The LDAPResult is the construct used in this protocol to return
521 success or failure indications from servers to clients. To various
522 requests, servers will return responses containing the elements found
523 in LDAPResult to indicate the final status of the protocol operation
528 Sermersheim Internet-Draft - Expires Aug 2005 Page 9
530 Lightweight Directory Access Protocol Version 3
532 LDAPResult ::= SEQUENCE {
533 resultCode ENUMERATED {
537 timeLimitExceeded (3),
538 sizeLimitExceeded (4),
541 authMethodNotSupported (7),
542 strongerAuthRequired (8),
545 adminLimitExceeded (11),
546 unavailableCriticalExtension (12),
547 confidentialityRequired (13),
548 saslBindInProgress (14),
549 noSuchAttribute (16),
550 undefinedAttributeType (17),
551 inappropriateMatching (18),
552 constraintViolation (19),
553 attributeOrValueExists (20),
554 invalidAttributeSyntax (21),
558 invalidDNSyntax (34),
559 -- 35 reserved for undefined isLeaf --
560 aliasDereferencingProblem (36),
562 inappropriateAuthentication (48),
563 invalidCredentials (49),
564 insufficientAccessRights (50),
567 unwillingToPerform (53),
570 namingViolation (64),
571 objectClassViolation (65),
572 notAllowedOnNonLeaf (66),
573 notAllowedOnRDN (67),
574 entryAlreadyExists (68),
575 objectClassModsProhibited (69),
576 -- 70 reserved for CLDAP --
577 affectsMultipleDSAs (71),
582 diagnosticMessage LDAPString,
583 referral [3] Referral OPTIONAL }
587 Sermersheim Internet-Draft - Expires Aug 2005 Page 10
589 Lightweight Directory Access Protocol Version 3
591 The resultCode enumeration is extensible as defined in Section 3.6 of
592 [LDAPIANA]. The meanings of the listed result codes are given in
593 Appendix A. If a server detects multiple errors for an operation,
594 only one result code is returned. The server should return the result
595 code that best indicates the nature of the error encountered.
597 The diagnosticMessage field of this construct may, at the server's
598 option, be used to return a string containing a textual, human-
599 readable (terminal control and page formatting characters should be
600 avoided) diagnostic message. As this diagnostic message is not
601 standardized, implementations MUST NOT rely on the values returned.
602 Diagnostic messages typically supplement the resultCode with
603 additional information. If the server chooses not to return a textual
604 diagnostic, the diagnosticMessage field MUST be empty.
606 For certain result codes (typically, but not restricted to
607 noSuchObject, aliasProblem, invalidDNSyntax and
608 aliasDereferencingProblem), the matchedDN field is set (subject to
609 access controls) to the name of the last entry (object or alias) used
610 in finding the target (or base) object. This will be a truncated form
611 of the provided name or, if an alias was dereferenced while
612 attempting to locate the entry, of the resulting name. Otherwise the
613 matchedDN field is empty.
618 The referral result code indicates that the contacted server cannot
619 or will not perform the operation and that one or more other servers
620 may be able to. Reasons for this include:
622 - The target entry of the request is not held locally, but the
623 server has knowledge of its possible existence elsewhere.
625 - The operation is restricted on this server -- perhaps due to a
626 read-only copy of an entry to be modified.
628 The referral field is present in an LDAPResult if the resultCode is
629 set to referral, and absent with all other result codes. It contains
630 one or more references to one or more servers or services that may be
631 accessed via LDAP or other protocols. Referrals can be returned in
632 response to any operation request (except Unbind and Abandon which do
633 not have responses). At least one URI MUST be present in the
636 During a Search operation, after the baseObject is located, and
637 entries are being evaluated, the referral is not returned. Instead,
638 continuation references, described in Section 4.5.3, are returned
639 when other servers would need to be contacted to complete the
642 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI
646 Sermersheim Internet-Draft - Expires Aug 2005 Page 11
648 Lightweight Directory Access Protocol Version 3
650 URI ::= LDAPString -- limited to characters permitted in
653 If the client wishes to progress the operation, it contacts one of
654 the supported services found in the referral. If multiple URIs are
655 present, the client assumes that any supported URI may be used to
656 progress the operation.
658 Clients that follow referrals MUST ensure that they do not loop
659 between servers. They MUST NOT repeatedly contact the same server for
660 the same request with the same parameters. Some clients use a counter
661 that is incremented each time referral handling occurs for an
662 operation, and these kinds of clients MUST be able to handle at least
663 ten nested referrals while progressing the operation.
665 A URI for a server implementing LDAP and accessible via [TCP]/[IP]
666 (v4 or v6) is written as an LDAP URL according to [LDAPURL].
668 Referral values which are LDAP URLs follow these rules:
670 - If an alias was dereferenced, the <dn> part of the LDAP URL MUST
671 be present, with the new target object name.
673 - It is RECOMMENDED that the <dn> part be present to avoid
676 - If the <dn> part is present, the client uses this name in its next
677 request to progress the operation, and if it is not present the
678 client uses the same name as in the original request.
680 - Some servers (e.g. participating in distributed indexing) may
681 provide a different filter in a URL of a referral for a Search
684 - If the <filter> part of the LDAP URL is present, the client uses
685 this filter in its next request to progress this Search, and if it
686 is not present the client uses the same filter as it used for that
689 - For Search, it is RECOMMENDED that the <scope> part be present to
692 - If the <scope> part is missing, the scope of the original Search
693 is used by the client to progress the operation.
695 - Other aspects of the new request may be the same as or different
696 from the request which generated the referral.
698 Other kinds of URIs may be returned. The syntax and semantics of such
699 URIs is left to future specifications. Clients may ignore URIs that
705 Sermersheim Internet-Draft - Expires Aug 2005 Page 12
707 Lightweight Directory Access Protocol Version 3
709 UTF-8 encoded characters appearing in the string representation of a
710 DN, search filter, or other fields of the referral value may not be
711 legal for URIs (e.g. spaces) and MUST be escaped using the % method
717 Controls provide a mechanism whereby the semantics and arguments of
718 existing LDAP operations may be extended. One or more controls may be
719 attached to a single LDAP message. A control only affects the
720 semantics of the message it is attached to.
722 Controls sent by clients are termed 'request controls' and those sent
723 by servers are termed 'response controls'.
725 Controls ::= SEQUENCE OF control Control
727 Control ::= SEQUENCE {
729 criticality BOOLEAN DEFAULT FALSE,
730 controlValue OCTET STRING OPTIONAL }
732 The controlType field is the dotted-decimal representation of an
733 OBJECT IDENTIFIER which uniquely identifies the control. This
734 provides unambiguous naming of controls. Often, response control(s)
735 solicited by a request control share controlType values with the
738 The criticality field only has meaning in controls attached to
739 request messages (except UnbindRequest). For controls attached to
740 response messages and the UnbindRequest, the criticality field SHOULD
741 be FALSE, and MUST be ignored by the receiving protocol peer. A value
742 of TRUE indicates that it is unacceptable to perform the operation
743 without applying the semantics of the control. Specifically, the
744 criticality field is applied as follows:
746 - Regardless of the value of the criticality field, if the server
747 recognizes the control type and it is appropriate for the
748 operation, the server is to make use of the control when
749 performing the operation.
751 - If the server does not recognize the control type or it is not
752 appropriate for the operation, and the criticality field is TRUE,
753 the server MUST NOT perform the operation, and for operations that
754 have a response message, MUST return with the resultCode set to
755 unavailableCriticalExtension.
757 - If the server does not recognize the control type or it is not
758 appropriate for the operation, and the criticality field is FALSE,
759 the server MUST ignore the control.
764 Sermersheim Internet-Draft - Expires Aug 2005 Page 13
766 Lightweight Directory Access Protocol Version 3
768 The controlValue may contain information associated with the
769 controlType. Its format is defined by the specification of the
770 control. Implementations MUST be prepared to handle arbitrary
771 contents of the controlValue octet string, including zero bytes. It
772 is absent only if there is no value information which is associated
773 with a control of its type. When a controlValue is defined in terms
774 of ASN.1, and BER encoded according to Section 5.1, it also follows
775 the extensibility rules in Section 4.
777 Servers list the controlType of request controls they recognize in
778 the 'supportedControl' attribute in the root DSE (Section 5.1 of
781 Controls SHOULD NOT be combined unless the semantics of the
782 combination has been specified. The semantics of control
783 combinations, if specified, are generally found in the control
784 specification most recently published. When a combination of controls
785 is encountered whose semantics are invalid, not specified (or not
786 known), the message is considered to be not well-formed, thus the
787 operation fails with protocolError. Additionally, unless order-
788 dependent semantics are given in a specification, the order of a
789 combination of controls in the SEQUENCE is ignored. Where the order
790 is to be ignored but cannot be ignored by the server, the message is
791 considered not well-formed and the operation fails with
794 This document does not specify any controls. Controls may be
795 specified in other documents. Documents detailing control extensions
796 are to provide for each control:
798 - the OBJECT IDENTIFIER assigned to the control,
800 - direction as to what value the sender should provide for the
801 criticality field (note: the semantics of the criticality field
802 are defined above should not be altered by the control's
805 - whether the controlValue field is present, and if so, the format
808 - the semantics of the control, and
810 - optionally, semantics regarding the combination of the control
816 The function of the Bind operation is to allow authentication
817 information to be exchanged between the client and server. The Bind
818 operation should be thought of as the "authenticate" operation.
819 Operational, authentication, and security-related semantics of this
820 operation are given in [AuthMeth].
823 Sermersheim Internet-Draft - Expires Aug 2005 Page 14
825 Lightweight Directory Access Protocol Version 3
827 The Bind request is defined as follows:
829 BindRequest ::= [APPLICATION 0] SEQUENCE {
830 version INTEGER (1 .. 127),
832 authentication AuthenticationChoice }
834 AuthenticationChoice ::= CHOICE {
835 simple [0] OCTET STRING,
837 sasl [3] SaslCredentials,
840 SaslCredentials ::= SEQUENCE {
841 mechanism LDAPString,
842 credentials OCTET STRING OPTIONAL }
844 Fields of the BindRequest are:
846 - version: A version number indicating the version of the protocol
847 to be used at the LDAP message layer. This document describes
848 version 3 of the protocol. There is no version negotiation. The
849 client sets this field to the version it desires. If the server
850 does not support the specified version, it MUST respond with a
851 BindResponse where the resultCode is set to protocolError.
853 - name: If not empty, the name of the Directory object that the
854 client wishes to bind as. This field may take on a null value (a
855 zero length string) for the purposes of anonymous binds
856 ([AuthMeth] Section 5.1) or when using Simple Authentication and
857 Security Layer [SASL] authentication ([AuthMeth] Section 3.3.2).
858 Where the server attempts to locate the named object, it SHALL NOT
859 perform alias dereferencing.
861 - authentication: information used in authentication. This type is
862 extensible as defined in Section 3.7 of [LDAPIANA]. Servers that
863 do not support a choice supplied by a client return a BindResponse
864 with the resultCode set to authMethodNotSupported.
866 Textual passwords (consisting of a character sequence with a known
867 character set and encoding) transferred to the server using the
868 simple AuthenticationChoice SHALL be transferred as [UTF-8]
869 encoded [Unicode]. Prior to transfer, clients SHOULD prepare text
870 passwords by applying the [SASLprep] profile of the [Stringprep]
871 algorithm. Passwords consisting of other data (such as random
872 octets) MUST NOT be altered. The determination of whether a
873 password is textual is a local client matter.
882 Sermersheim Internet-Draft - Expires Aug 2005 Page 15
884 Lightweight Directory Access Protocol Version 3
886 4.2.1. Processing of the Bind Request
888 Before processing a BindRequest, all uncompleted operations MUST
889 either complete or be abandoned. The server may either wait for the
890 uncompleted operations to complete, or abandon them. The server then
891 proceeds to authenticate the client in either a single-step, or
892 multi-step Bind process. Each step requires the server to return a
893 BindResponse to indicate the status of authentication.
895 After sending a BindRequest, clients MUST NOT send further LDAP PDUs
896 until receiving the BindResponse. Similarly, servers SHOULD NOT
897 process or respond to requests received while processing a
900 If the client did not bind before sending a request and receives an
901 operationsError to that request, it may then send a BindRequest. If
902 this also fails or the client chooses not to bind on the existing
903 LDAP session, it may terminate the LDAP session, re-establish it and
904 begin again by first sending a PDU with a BindRequest. This will aid
905 in interoperating with servers implementing other versions of LDAP.
907 Clients may send multiple Bind requests to change the authentication
908 and/or security associations or to complete a multi-stage Bind
909 process. Authentication from earlier binds is subsequently ignored.
911 For some SASL authentication mechanisms, it may be necessary for the
912 client to invoke the BindRequest multiple times ([AuthMeth] Section
913 8.2). Clients MUST NOT invoke operations between two Bind requests
914 made as part of a multi-stage Bind.
916 A client may abort a SASL bind negotiation by sending a BindRequest
917 with a different value in the mechanism field of SaslCredentials, or
918 an AuthenticationChoice other than sasl.
920 If the client sends a BindRequest with the sasl mechanism field as an
921 empty string, the server MUST return a BindResponse with the
922 resultCode set to authMethodNotSupported. This will allow clients to
923 abort a negotiation if it wishes to try again with the same SASL
929 The Bind response is defined as follows.
931 BindResponse ::= [APPLICATION 1] SEQUENCE {
932 COMPONENTS OF LDAPResult,
933 serverSaslCreds [7] OCTET STRING OPTIONAL }
935 BindResponse consists simply of an indication from the server of the
936 status of the client's request for authentication.
941 Sermersheim Internet-Draft - Expires Aug 2005 Page 16
943 Lightweight Directory Access Protocol Version 3
945 A successful Bind operation is indicated by a BindResponse with a
946 resultCode set to success. Otherwise, an appropriate result code is
947 set in the BindResponse. For BindResponse, the protocolError result
948 code may be used to indicate that the version number supplied by the
949 client is unsupported.
951 If the client receives a BindResponse where the resultCode is set to
952 protocolError, it is to assume that the server does not support this
953 version of LDAP. While the client may be able proceed with another
954 version of this protocol (this may or may not require closing and re-
955 establishing the transport connection), how to proceed with another
956 version of this protocol is beyond the scope of this document.
957 Clients which are unable or unwilling to proceed SHOULD terminate the
960 The serverSaslCreds field is used as part of a SASL-defined bind
961 mechanism to allow the client to authenticate the server to which it
962 is communicating, or to perform "challenge-response" authentication.
963 If the client bound with the simple choice, or the SASL mechanism
964 does not require the server to return information to the client, then
965 this field SHALL NOT be included in the BindResponse.
968 4.3. Unbind Operation
970 The function of the Unbind operation is to terminate an LDAP session.
971 The Unbind operation is not the antithesis of the Bind operation as
972 the name implies. The naming of these operations are historical. The
973 Unbind operation should be thought of as the "quit" operation.
975 The Unbind operation is defined as follows:
977 UnbindRequest ::= [APPLICATION 2] NULL
979 The client, upon transmission of the UnbindRequest, and the server,
980 upon receipt of the UnbindRequest are to gracefully terminate the
981 LDAP session as described in Section 5.3.
983 Uncompleted operations are handled as specified in Section 3.1.
986 4.4. Unsolicited Notification
988 An unsolicited notification is an LDAPMessage sent from the server to
989 the client which is not in response to any LDAPMessage received by
990 the server. It is used to signal an extraordinary condition in the
991 server or in the LDAP session between the client and the server. The
992 notification is of an advisory nature, and the server will not expect
993 any response to be returned from the client.
1000 Sermersheim Internet-Draft - Expires Aug 2005 Page 17
1002 Lightweight Directory Access Protocol Version 3
1004 The unsolicited notification is structured as an LDAPMessage in which
1005 the messageID is zero and protocolOp is set to the extendedResp
1006 choice using the ExtendedResponse type (See Section 4.12). The
1007 responseName field of the ExtendedResponse always contains an LDAPOID
1008 which is unique for this notification.
1010 One unsolicited notification (Notice of Disconnection) is defined in
1011 this document. The specification of an unsolicited notification
1014 - the OBJECT IDENTIFIER assigned to the notification (to be
1015 specified in the responseName,
1017 - the format of the contents of the responseValue (if any),
1019 - the circumstances which will cause the notification to be sent,
1022 - the semantics of the message.
1025 4.4.1. Notice of Disconnection
1027 This notification may be used by the server to advise the client that
1028 the server is about to terminate the LDAP session on its own
1029 initiative. This notification is intended to assist clients in
1030 distinguishing between an exceptional server condition and a
1031 transient network failure. Note that this notification is not a
1032 response to an Unbind requested by the client. Uncompleted operations
1033 are handled as specified in Section 3.1.
1035 The responseName is 1.3.6.1.4.1.1466.20036, the responseValue field
1036 is absent, and the resultCode is used to indicate the reason for the
1037 disconnection. When the strongerAuthRequired resultCode is returned
1038 with this message, it indicates that the server has detected that an
1039 established security association between the client and server has
1040 unexpectedly failed or been compromised.
1042 Upon transmission of the Notice of Disconnection, the server
1043 gracefully terminates the LDAP session as described in Section 5.3.
1046 4.5. Search Operation
1048 The Search operation is used to request a server to return, subject
1049 to access controls and other restrictions, a set of entries matching
1050 a complex search criterion. This can be used to read attributes from
1051 a single entry, from entries immediately subordinate to a particular
1052 entry, or a whole subtree of entries.
1055 4.5.1. Search Request
1057 The Search request is defined as follows:
1059 Sermersheim Internet-Draft - Expires Aug 2005 Page 18
1061 Lightweight Directory Access Protocol Version 3
1064 SearchRequest ::= [APPLICATION 3] SEQUENCE {
1071 derefAliases ENUMERATED {
1072 neverDerefAliases (0),
1073 derefInSearching (1),
1074 derefFindingBaseObj (2),
1076 sizeLimit INTEGER (0 .. maxInt),
1077 timeLimit INTEGER (0 .. maxInt),
1080 attributes AttributeSelection }
1082 AttributeSelection ::= SEQUENCE OF selector LDAPString
1083 -- The LDAPString is constrained to
1084 -- <attributeSelector> in Section 4.5.1.7
1087 and [0] SET SIZE (1..MAX) OF filter Filter,
1088 or [1] SET SIZE (1..MAX) OF filter Filter,
1090 equalityMatch [3] AttributeValueAssertion,
1091 substrings [4] SubstringFilter,
1092 greaterOrEqual [5] AttributeValueAssertion,
1093 lessOrEqual [6] AttributeValueAssertion,
1094 present [7] AttributeDescription,
1095 approxMatch [8] AttributeValueAssertion,
1096 extensibleMatch [9] MatchingRuleAssertion,
1099 SubstringFilter ::= SEQUENCE {
1100 type AttributeDescription,
1101 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE {
1102 initial [0] AssertionValue, -- can occur at most once
1103 any [1] AssertionValue,
1104 final [2] AssertionValue } -- can occur at most once
1107 MatchingRuleAssertion ::= SEQUENCE {
1108 matchingRule [1] MatchingRuleId OPTIONAL,
1109 type [2] AttributeDescription OPTIONAL,
1110 matchValue [3] AssertionValue,
1111 dnAttributes [4] BOOLEAN DEFAULT FALSE }
1118 Sermersheim Internet-Draft - Expires Aug 2005 Page 19
1120 Lightweight Directory Access Protocol Version 3
1122 Note that an X.500 "list"-like operation can be emulated by the
1123 client requesting a singleLevel Search operation with a filter
1124 checking for the presence of the 'objectClass' attribute, and that an
1125 X.500 "read"-like operation can be emulated by a baseObject Search
1126 operation with the same filter. A server which provides a gateway to
1127 X.500 is not required to use the Read or List operations, although it
1128 may choose to do so, and if it does, it must provide the same
1129 semantics as the X.500 Search operation.
1132 4.5.1.1 SearchRequest.baseObject
1134 The name of the base object entry (or possibly the root) relative to
1135 which the Search is to be performed.
1138 4.5.1.2 SearchRequest.scope
1140 Specifies the scope of the Search to be performed. The semantics (as
1141 described in [X.511]) of the defined values of this field are:
1143 baseObject: The scope is constrained to the entry named by
1146 singleLevel: The scope is constrained to the immediate
1147 subordinates of the entry named by baseObject.
1149 wholeSubtree: the scope is constrained to the entry named by the
1150 baseObject, and all its subordinates.
1153 4.5.1.3 SearchRequest.derefAliases
1155 An indicator as to whether or not alias entries (as defined in
1156 [Models]) are to be dereferenced during stages of the Search
1159 The act of dereferencing an alias includes recursively dereferencing
1160 aliases which refer to aliases.
1162 Servers MUST detect looping while dereferencing aliases in order to
1163 prevent denial of service attacks of this nature.
1165 The semantics of the defined values of this field are:
1167 neverDerefAliases: Do not dereference aliases in searching or in
1168 locating the base object of the Search.
1177 Sermersheim Internet-Draft - Expires Aug 2005 Page 20
1179 Lightweight Directory Access Protocol Version 3
1181 derefInSearching: While searching subordinates of the base object,
1182 dereference any alias within the search scope. Dereferenced
1183 objects become the vertices of further search scopes where the
1184 Search operation is also applied. If the search scope is
1185 wholeSubtree, the Search continues in the subtree(s) of any
1186 dereferenced object. If the search scope is singleLevel, the
1187 search is applied to any dereferenced objects, and is not applied
1188 to their subordinates. Servers SHOULD eliminate duplicate entries
1189 that arise due to alias dereferencing while searching.
1191 derefFindingBaseObj: Dereference aliases in locating the base
1192 object of the Search, but not when searching subordinates of the
1195 derefAlways: Dereference aliases both in searching and in locating
1196 the base object of the Search.
1199 4.5.1.4 SearchRequest.sizeLimit
1201 A size limit that restricts the maximum number of entries to be
1202 returned as a result of the Search. A value of zero in this field
1203 indicates that no client-requested size limit restrictions are in
1204 effect for the Search. Servers may also enforce a maximum number of
1208 4.5.1.5 SearchRequest.timeLimit
1210 A time limit that restricts the maximum time (in seconds) allowed for
1211 a Search. A value of zero in this field indicates that no client-
1212 requested time limit restrictions are in effect for the Search.
1213 Servers may also enforce a maximum time limit for the Search.
1216 4.5.1.6 SearchRequest.typesOnly
1218 An indicator as to whether Search results are to contain both
1219 attribute descriptions and values, or just attribute descriptions.
1220 Setting this field to TRUE causes only attribute descriptions (no
1221 values) to be returned. Setting this field to FALSE causes both
1222 attribute descriptions and values to be returned.
1236 Sermersheim Internet-Draft - Expires Aug 2005 Page 21
1238 Lightweight Directory Access Protocol Version 3
1240 4.5.1.7 SearchRequest.filter
1242 A filter that defines the conditions that must be fulfilled in order
1243 for the Search to match a given entry.
1245 The 'and', 'or' and 'not' choices can be used to form combinations of
1246 filters. At least one filter element MUST be present in an 'and' or
1247 'or' choice. The others match against individual attribute values of
1248 entries in the scope of the Search. (Implementor's note: the 'not'
1249 filter is an example of a tagged choice in an implicitly-tagged
1250 module. In BER this is treated as if the tag was explicit.)
1252 A server MUST evaluate filters according to the three-valued logic of
1253 [X.511] (1993) Clause 7.8.1. In summary, a filter is evaluated to
1254 either "TRUE", "FALSE" or "Undefined". If the filter evaluates to
1255 TRUE for a particular entry, then the attributes of that entry are
1256 returned as part of the Search result (subject to any applicable
1257 access control restrictions). If the filter evaluates to FALSE or
1258 Undefined, then the entry is ignored for the Search.
1260 A filter of the "and" choice is TRUE if all the filters in the SET OF
1261 evaluate to TRUE, FALSE if at least one filter is FALSE, and
1262 otherwise Undefined. A filter of the "or" choice is FALSE if all of
1263 the filters in the SET OF evaluate to FALSE, TRUE if at least one
1264 filter is TRUE, and Undefined otherwise. A filter of the 'not' choice
1265 is TRUE if the filter being negated is FALSE, FALSE if it is TRUE,
1266 and Undefined if it is Undefined.
1268 A filter item evaluates to Undefined when the server would not be
1269 able to determine whether the assertion value matches an entry.
1272 - An attribute description in an equalityMatch, substrings,
1273 greaterOrEqual, lessOrEqual, approxMatch or extensibleMatch
1274 filter is not recognized by the server.
1276 - The attribute type does not define the appropriate matching
1279 - A MatchingRuleId in the extensibleMatch is not recognized by
1280 the server or is not valid for the attribute type.
1282 - The type of filtering requested is not implemented.
1284 - The assertion value is invalid.
1295 Sermersheim Internet-Draft - Expires Aug 2005 Page 22
1297 Lightweight Directory Access Protocol Version 3
1299 For example, if a server did not recognize the attribute type
1300 shoeSize, a filter of (shoeSize=*) would evaluate to FALSE, and the
1301 filters (shoeSize=12), (shoeSize>=12) and (shoeSize<=12) would each
1302 evaluate to Undefined.
1304 Servers MUST NOT return errors if attribute descriptions or matching
1305 rule ids are not recognized, assertion values are invalid, or the
1306 assertion syntax is not supported. More details of filter processing
1307 are given in Clause 7.8 of [X.511].
1310 4.5.1.7.1 SearchRequest.filter.equalityMatch
1312 The matching rule for equalityMatch filter items is defined by the
1313 EQUALITY matching rule for the attribute type.
1316 4.5.1.7.2 SearchRequest.filter.substrings
1318 There SHALL be at most one 'initial', and at most one 'final' in the
1319 'substrings' of a SubstringFilter. If 'initial' is present, it SHALL
1320 be the first element of 'substrings'. If 'final' is present, it SHALL
1321 be the last element of 'substrings'.
1323 The matching rule for an AssertionValue in a substrings filter item
1324 is defined by the SUBSTR matching rule for the attribute type. Note
1325 that the AssertionValue in a substrings filter item conforms to the
1326 assertion syntax of the EQUALITY matching rule for the attribute type
1327 rather than the assertion syntax of the SUBSTR matching rule for the
1328 attribute type. Conceptually, the entire SubstringFilter is converted
1329 into an assertion value of the substrings matching rule prior to
1333 4.5.1.7.3 SearchRequest.filter.greaterOrEqual
1335 The matching rule for the greaterOrEqual filter item is defined by
1336 the ORDERING and EQUALITY matching rules for the attribute type.
1339 4.5.1.7.4 SearchRequest.filter.lessOrEqual
1341 The matching rule for the lessOrEqual filter item is defined by the
1342 ORDERING matching rule for the attribute type.
1345 4.5.1.7.5 SearchRequest.filter.present
1347 The present match evaluates to TRUE where there is an attribute or
1348 subtype of the specified attribute description present in an entry,
1349 and FALSE otherwise (including a presence test with an unrecognized
1350 attribute description).
1354 Sermersheim Internet-Draft - Expires Aug 2005 Page 23
1356 Lightweight Directory Access Protocol Version 3
1358 4.5.1.7.6 SearchRequest.filter.approxMatch
1360 An approxMatch filter item evaluates to TRUE when there is a value of
1361 the attribute or subtype for which some locally-defined approximate
1362 matching algorithm (e.g. spelling variations, phonetic match, etc.)
1363 returns TRUE. If an item matches for equality, it also satisfies an
1364 approximate match. If approximate matching is not supported for the
1365 attribute, this filter item should be treated as an equalityMatch.
1368 4.5.1.7.7 SearchRequest.filter.extensibleMatch
1370 The fields of the extensibleMatch filter item are evaluated as
1373 - If the matchingRule field is absent, the type field MUST be
1374 present, and an equality match is performed for that type.
1376 - If the type field is absent and the matchingRule is present, the
1377 matchValue is compared against all attributes in an entry which
1378 support that matchingRule.
1380 - If the type field is present and the matchingRule is present, the
1381 matchValue is compared against entry attributes of the specified
1384 - If the dnAttributes field is set to TRUE, the match is
1385 additionally applied against all the AttributeValueAssertions in
1386 an entry's distinguished name, and evaluates to TRUE if there is
1387 at least one attribute in the distinguished name for which the
1388 filter item evaluates to TRUE. The dnAttributes field is present
1389 to alleviate the need for multiple versions of generic matching
1390 rules (such as word matching), where one applies to entries and
1391 another applies to entries and DN attributes as well.
1393 The matchingRule used for evaluation determines the syntax for the
1394 assertion value. Once the matchingRule and attribute(s) have been
1395 determined, the filter item evaluates to TRUE if it matches with at
1396 least one attribute in the entry, FALSE if it does not match any
1397 attribute in the entry, and Undefined if the matchingRule is not
1398 recognized, the matchingRule is unsuitable for use with the specified
1399 type, or the assertionValue is invalid.
1402 4.5.1.7 SearchRequest.attributes
1404 A selection list of the attributes to be returned from each entry
1405 which matches the search filter. LDAPString values of this field are
1406 constrained to the following Augmented Backus-Naur Form ([ABNF]):
1408 attributeSelector = attributedescription / selectorspecial
1410 selectorspecial = noattrs / alluserattrs
1413 Sermersheim Internet-Draft - Expires Aug 2005 Page 24
1415 Lightweight Directory Access Protocol Version 3
1417 noattrs = %x31.2E.31 ; "1.1"
1419 alluserattrs = %x2A ; asterisk ("*")
1421 The <attributedescription> production is defined in Section 2.5 of
1424 There are three special cases which may appear in the attributes
1427 - an empty list with no attributes,
1429 - a list containing "*" (with zero or more attribute
1432 - a list containing only "1.1".
1434 An empty list requests the return of all user attributes.
1436 A list containing "*" requests the return of all user attributes
1437 in addition to other listed (operational) attributes.
1439 A list containing only the OID "1.1" indicates that no attributes
1440 are to be returned. If "1.1" is provided with other
1441 attributeSelector values, the "1.1" attributeSelector is ignored.
1442 This OID was chosen because it does not (and can not) correspond
1443 to any attribute in use.
1445 Client implementors should note that even if all user attributes are
1446 requested, some attributes and/or attribute values of the entry may
1447 not be included in Search results due to access controls or other
1448 restrictions. Furthermore, servers will not return operational
1449 attributes, such as objectClasses or attributeTypes, unless they are
1450 listed by name. Operational attributes are described in [Models].
1452 Attributes are returned at most once in an entry. If an attribute
1453 description is named more than once in the list, the subsequent names
1454 are ignored. If an attribute description in the list is not
1455 recognized, it is ignored by the server.
1458 4.5.2. Search Result
1460 The results of the Search operation are returned as zero or more
1461 SearchResultEntry and/or SearchResultReference messages, followed by
1462 a single SearchResultDone message.
1464 SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
1466 attributes PartialAttributeList }
1468 PartialAttributeList ::= SEQUENCE OF
1469 partialAttribute PartialAttribute
1472 Sermersheim Internet-Draft - Expires Aug 2005 Page 25
1474 Lightweight Directory Access Protocol Version 3
1476 SearchResultReference ::= [APPLICATION 19] SEQUENCE
1477 SIZE (1..MAX) OF uri URI
1479 SearchResultDone ::= [APPLICATION 5] LDAPResult
1481 Each SearchResultEntry represents an entry found during the Search.
1482 Each SearchResultReference represents an area not yet explored during
1483 the Search. The SearchResultEntry and SearchResultReference PDUs may
1484 come in any order. Following all the SearchResultReference and
1485 SearchResultEntry responses, the server returns a SearchResultDone
1486 response, which contains an indication of success, or detailing any
1487 errors that have occurred.
1489 Each entry returned in a SearchResultEntry will contain all
1490 appropriate attributes as specified in the attributes field of the
1491 Search Request, subject to access control and other administrative
1492 policy. Note that the PartialAttributeList may hold zero elements.
1493 This may happen when none of the attributes of an entry were
1494 requested, or could be returned. Note also that the partialAttribute
1495 vals set may hold zero elements. This may happen when typesOnly is
1496 requested, access controls prevent the return of values, or other
1499 Some attributes may be constructed by the server and appear in a
1500 SearchResultEntry attribute list, although they are not stored
1501 attributes of an entry. Clients SHOULD NOT assume that all attributes
1502 can be modified, even if permitted by access control.
1504 If the server's schema defines short names [Models] for an attribute
1505 type then the server SHOULD use one of those names in attribute
1506 descriptions for that attribute type (in preference to using the
1507 <numericoid> [Models] format of the attribute type's object
1508 identifier). The server SHOULD NOT use the short name if that name is
1509 known by the server to be ambiguous, or otherwise likely to cause
1510 interoperability problems.
1513 4.5.3. Continuation References in the Search Result
1515 If the server was able to locate the entry referred to by the
1516 baseObject but was unable or unwilling to search one or more non-
1517 local entries, the server may return one or more
1518 SearchResultReference messages, each containing a reference to
1519 another set of servers for continuing the operation. A server MUST
1520 NOT return any SearchResultReference messages if it has not located
1521 the baseObject and thus has not searched any entries; in this case it
1522 would return a SearchResultDone containing either a referral or
1523 noSuchObject result code (depending on the server's knowledge of the
1524 entry named in the baseObject).
1531 Sermersheim Internet-Draft - Expires Aug 2005 Page 26
1533 Lightweight Directory Access Protocol Version 3
1535 If a server holds a copy or partial copy of the subordinate naming
1536 context (Section 5 of [Models]), it may use the search filter to
1537 determine whether or not to return a SearchResultReference response.
1538 Otherwise SearchResultReference responses are always returned when in
1541 The SearchResultReference is of the same data type as the Referral.
1543 If the client wishes to progress the Search, it issues a new Search
1544 operation for each SearchResultReference that is returned. If
1545 multiple URIs are present, the client assumes that any supported URI
1546 may be used to progress the operation.
1548 Clients that follow search continuation references MUST ensure that
1549 they do not loop between servers. They MUST NOT repeatedly contact
1550 the same server for the same request with the same parameters. Some
1551 clients use a counter that is incremented each time search result
1552 reference handling occurs for an operation, and these kinds of
1553 clients MUST be able to handle at least ten nested referrals while
1554 progressing the operation.
1556 Note that the Abandon operation described in Section 4.11 applies
1557 only to a particular operation sent at the LDAP message layer between
1558 a client and server. The client must abandon subsequent Search
1559 operations it wishes to individually.
1561 A URI for a server implementing LDAP and accessible via [TCP]/[IP]
1562 (v4 or v6) is written as an LDAP URL according to [LDAPURL].
1564 SearchResultReference values which are LDAP URLs follow these rules:
1566 - The <dn> part of the LDAP URL MUST be present, with the new target
1567 object name. The client uses this name when following the
1570 - Some servers (e.g. participating in distributed indexing) may
1571 provide a different filter in the LDAP URL.
1573 - If the <filter> part of the LDAP URL is present, the client uses
1574 this filter in its next request to progress this Search, and if it
1575 is not present the client uses the same filter as it used for that
1578 - If the originating search scope was singleLevel, the <scope> part
1579 of the LDAP URL will be "base".
1581 - It is RECOMMENDED that the <scope> part be present to avoid
1582 ambiguity. In the absence of a <scope> part, the scope of the
1583 original Search request is assumed.
1585 - Other aspects of the new Search request may be the same as or
1586 different from the Search request which generated the
1587 SearchResultReference.
1590 Sermersheim Internet-Draft - Expires Aug 2005 Page 27
1592 Lightweight Directory Access Protocol Version 3
1594 - The name of an unexplored subtree in a SearchResultReference need
1595 not be subordinate to the base object.
1597 Other kinds of URIs may be returned. The syntax and semantics of such
1598 URIs is left to future specifications. Clients may ignore URIs that
1599 they do not support.
1601 UTF-8 encoded characters appearing in the string representation of a
1602 DN, search filter, or other fields of the referral value may not be
1603 legal for URIs (e.g. spaces) and MUST be escaped using the % method
1610 For example, suppose the contacted server (hosta) holds the entry
1611 <DC=Example,DC=NET> and the entry <CN=Manager,DC=Example,DC=NET>. It
1612 knows that both LDAP servers (hostb) and (hostc) hold
1613 <OU=People,DC=Example,DC=NET> (one is the master and the other server
1614 a shadow), and that LDAP-capable server (hostd) holds the subtree
1615 <OU=Roles,DC=Example,DC=NET>. If a wholeSubtree Search of
1616 <DC=Example,DC=NET> is requested to the contacted server, it may
1617 return the following:
1619 SearchResultEntry for DC=Example,DC=NET
1620 SearchResultEntry for CN=Manager,DC=Example,DC=NET
1621 SearchResultReference {
1622 ldap://hostb/OU=People,DC=Example,DC=NET??sub
1623 ldap://hostc/OU=People,DC=Example,DC=NET??sub }
1624 SearchResultReference {
1625 ldap://hostd/OU=Roles,DC=Example,DC=NET??sub }
1626 SearchResultDone (success)
1628 Client implementors should note that when following a
1629 SearchResultReference, additional SearchResultReference may be
1630 generated. Continuing the example, if the client contacted the server
1631 (hostb) and issued the Search request for the subtree
1632 <OU=People,DC=Example,DC=NET>, the server might respond as follows:
1634 SearchResultEntry for OU=People,DC=Example,DC=NET
1635 SearchResultReference {
1636 ldap://hoste/OU=Managers,OU=People,DC=Example,DC=NET??sub }
1637 SearchResultReference {
1638 ldap://hostf/OU=Consultants,OU=People,DC=Example,DC=NET??sub }
1639 SearchResultDone (success)
1641 Similarly, if a singleLevel Search of <DC=Example,DC=NET> is
1642 requested to the contacted server, it may return the following:
1649 Sermersheim Internet-Draft - Expires Aug 2005 Page 28
1651 Lightweight Directory Access Protocol Version 3
1653 SearchResultEntry for CN=Manager,DC=Example,DC=NET
1654 SearchResultReference {
1655 ldap://hostb/OU=People,DC=Example,DC=NET??base
1656 ldap://hostc/OU=People,DC=Example,DC=NET??base }
1657 SearchResultReference {
1658 ldap://hostd/OU=Roles,DC=Example,DC=NET??base }
1659 SearchResultDone (success)
1661 If the contacted server does not hold the base object for the Search,
1662 but has knowledge of its possible location, then it may return a
1663 referral to the client. In this case, if the client requests a
1664 subtree Search of <DC=Example,DC=ORG> to hosta, the server returns a
1665 SearchResultDone containing a referral.
1667 SearchResultDone (referral) {
1668 ldap://hostg/DC=Example,DC=ORG??sub }
1671 4.6. Modify Operation
1673 The Modify operation allows a client to request that a modification
1674 of an entry be performed on its behalf by a server. The Modify
1675 Request is defined as follows:
1677 ModifyRequest ::= [APPLICATION 6] SEQUENCE {
1679 changes SEQUENCE OF change SEQUENCE {
1680 operation ENUMERATED {
1685 modification PartialAttribute } }
1687 Fields of the Modify Request are:
1689 - object: The value of this field contains the name of the entry to
1690 be modified. The server SHALL NOT perform any alias dereferencing
1691 in determining the object to be modified.
1693 - changes: A list of modifications to be performed on the entry. The
1694 entire list of modifications MUST be performed in the order they
1695 are listed as a single atomic operation. While individual
1696 modifications may violate certain aspects of the directory schema
1697 (such as the object class definition and DIT content rule), the
1698 resulting entry after the entire list of modifications is
1699 performed MUST conform to the requirements of the directory model
1700 and controlling schema [Models].
1702 - operation: Used to specify the type of modification being
1703 performed. Each operation type acts on the following
1704 modification. The values of this field have the following
1705 semantics respectively:
1708 Sermersheim Internet-Draft - Expires Aug 2005 Page 29
1710 Lightweight Directory Access Protocol Version 3
1712 add: add values listed to the modification attribute,
1713 creating the attribute if necessary;
1715 delete: delete values listed from the modification attribute.
1716 If no values are listed, or if all current values of the
1717 attribute are listed, the entire attribute is removed;
1719 replace: replace all existing values of the modification
1720 attribute with the new values listed, creating the attribute
1721 if it did not already exist. A replace with no value will
1722 delete the entire attribute if it exists, and is ignored if
1723 the attribute does not exist.
1725 - modification: A PartialAttribute (which may have an empty SET
1726 of vals) used to hold the attribute type or attribute type and
1727 values being modified.
1729 Upon receipt of a Modify Request, the server attempts to perform the
1730 necessary modifications to the DIT and returns the result in a Modify
1731 Response, defined as follows:
1733 ModifyResponse ::= [APPLICATION 7] LDAPResult
1735 The server will return to the client a single Modify Response
1736 indicating either the successful completion of the DIT modification,
1737 or the reason that the modification failed. Due to the requirement
1738 for atomicity in applying the list of modifications in the Modify
1739 Request, the client may expect that no modifications of the DIT have
1740 been performed if the Modify Response received indicates any sort of
1741 error, and that all requested modifications have been performed if
1742 the Modify Response indicates successful completion of the Modify
1743 operation. Whether the modification was applied or not cannot be
1744 determined by the client if the Modify Response was not received
1745 (e.g. the LDAP session was terminated or the Modify operation was
1748 Servers MUST ensure that entries conform to user and system schema
1749 rules or other data model constraints. The Modify operation cannot be
1750 used to remove from an entry any of its distinguished values, i.e.
1751 those values which form the entry's relative distinguished name. An
1752 attempt to do so will result in the server returning the
1753 notAllowedOnRDN result code. The Modify DN operation described in
1754 Section 4.9 is used to rename an entry.
1756 For attribute types which specify no equality matching, the rules in
1757 Section 2.5.1 of [Models] are followed.
1759 Note that due to the simplifications made in LDAP, there is not a
1760 direct mapping of the changes in an LDAP ModifyRequest onto the
1761 changes of a DAP ModifyEntry operation, and different implementations
1762 of LDAP-DAP gateways may use different means of representing the
1763 change. If successful, the final effect of the operations on the
1764 entry MUST be identical.
1767 Sermersheim Internet-Draft - Expires Aug 2005 Page 30
1769 Lightweight Directory Access Protocol Version 3
1774 The Add operation allows a client to request the addition of an entry
1775 into the Directory. The Add Request is defined as follows:
1777 AddRequest ::= [APPLICATION 8] SEQUENCE {
1779 attributes AttributeList }
1781 AttributeList ::= SEQUENCE OF attribute Attribute
1783 Fields of the Add Request are:
1785 - entry: the name of the entry to be added. The server SHALL NOT
1786 dereference any aliases in locating the entry to be added.
1788 - attributes: the list of attributes that, along with those from the
1789 RDN, make up the content of the entry being added. Clients MAY or
1790 MAY NOT include the RDN attribute(s) in this list. Clients MUST
1791 NOT supply NO-USER-MODIFICATION attributes such as the
1792 createTimestamp or creatorsName attributes, since the server
1793 maintains these automatically.
1795 Servers MUST ensure that entries conform to user and system schema
1796 rules or other data model constraints. For attribute types which
1797 specify no equality matching, the rules in Section 2.5.1 of [Models]
1798 are followed (this applies to the naming attribute in addition to any
1799 multi-valued attributes being added).
1801 The entry named in the entry field of the AddRequest MUST NOT exist
1802 for the AddRequest to succeed. The immediate superior (parent) of an
1803 object or alias entry to be added MUST exist. For example, if the
1804 client attempted to add <CN=JS,DC=Example,DC=NET>, the
1805 <DC=Example,DC=NET> entry did not exist, and the <DC=NET> entry did
1806 exist, then the server would return the noSuchObject result code with
1807 the matchedDN field containing <DC=NET>.
1809 Upon receipt of an Add Request, a server will attempt to add the
1810 requested entry. The result of the Add attempt will be returned to
1811 the client in the Add Response, defined as follows:
1813 AddResponse ::= [APPLICATION 9] LDAPResult
1815 A response of success indicates that the new entry has been added to
1819 4.8. Delete Operation
1821 The Delete operation allows a client to request the removal of an
1822 entry from the Directory. The Delete Request is defined as follows:
1824 DelRequest ::= [APPLICATION 10] LDAPDN
1826 Sermersheim Internet-Draft - Expires Aug 2005 Page 31
1828 Lightweight Directory Access Protocol Version 3
1831 The Delete Request consists of the name of the entry to be deleted.
1832 The server SHALL NOT dereference aliases while resolving the name of
1833 the target entry to be removed.
1835 Only leaf entries (those with no subordinate entries) can be deleted
1836 with this operation.
1838 Upon receipt of a Delete Request, a server will attempt to perform
1839 the entry removal requested and return the result in the Delete
1840 Response defined as follows:
1842 DelResponse ::= [APPLICATION 11] LDAPResult
1845 4.9. Modify DN Operation
1847 The Modify DN operation allows a client to change the Relative
1848 Distinguished Name (RDN) of an entry in the Directory, and/or to move
1849 a subtree of entries to a new location in the Directory. The Modify
1850 DN Request is defined as follows:
1852 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
1854 newrdn RelativeLDAPDN,
1855 deleteoldrdn BOOLEAN,
1856 newSuperior [0] LDAPDN OPTIONAL }
1858 Fields of the Modify DN Request are:
1860 - entry: the name of the entry to be changed. This entry may or may
1861 not have subordinate entries.
1863 - newrdn: the new RDN of the entry. The value of the old RDN is
1864 supplied when moving the entry to a new superior without changing
1865 its RDN. Attribute values of the new RDN not matching any
1866 attribute value of the entry are added to the entry and an
1867 appropriate error is returned if this fails.
1869 - deleteoldrdn: a boolean field that controls whether the old RDN
1870 attribute values are to be retained as attributes of the entry, or
1871 deleted from the entry.
1873 - newSuperior: if present, this is the name of an existing object
1874 entry which becomes the immediate superior (parent) of the
1877 The server SHALL NOT dereference any aliases in locating the objects
1878 named in entry or newSuperior.
1880 Upon receipt of a ModifyDNRequest, a server will attempt to perform
1881 the name change and return the result in the Modify DN Response,
1885 Sermersheim Internet-Draft - Expires Aug 2005 Page 32
1887 Lightweight Directory Access Protocol Version 3
1889 ModifyDNResponse ::= [APPLICATION 13] LDAPResult
1891 For example, if the entry named in the entry field was <cn=John
1892 Smith,c=US>, the newrdn field was <cn=John Cougar Smith>, and the
1893 newSuperior field was absent, then this operation would attempt to
1894 rename the entry to be <cn=John Cougar Smith,c=US>. If there was
1895 already an entry with that name, the operation would fail with the
1896 entryAlreadyExists result code.
1898 Servers MUST ensure that entries conform to user and system schema
1899 rules or other data model constraints. For attribute types which
1900 specify no equality matching, the rules in Section 2.5.1 of [Models]
1901 are followed (this pertains to newrdn and deleteoldrdn).
1903 The object named in newSuperior MUST exist. For example, if the
1904 client attempted to add <CN=JS,DC=Example,DC=NET>, the
1905 <DC=Example,DC=NET> entry did not exist, and the <DC=NET> entry did
1906 exist, then the server would return the noSuchObject result code with
1907 the matchedDN field containing <DC=NET>.
1909 If the deleteoldrdn field is TRUE, the attribute values forming the
1910 old RDN but not the new RDN are deleted from the entry. If the
1911 deleteoldrdn field is FALSE, the attribute values forming the old RDN
1912 will be retained as non-distinguished attribute values of the entry.
1914 Note that X.500 restricts the ModifyDN operation to only affect
1915 entries that are contained within a single server. If the LDAP server
1916 is mapped onto DAP, then this restriction will apply, and the
1917 affectsMultipleDSAs result code will be returned if this error
1918 occurred. In general, clients MUST NOT expect to be able to perform
1919 arbitrary movements of entries and subtrees between servers or
1920 between naming contexts.
1923 4.10. Compare Operation
1925 The Compare operation allows a client to compare an assertion value
1926 with the values of a particular attribute in a particular entry in
1927 the Directory. The Compare Request is defined as follows:
1929 CompareRequest ::= [APPLICATION 14] SEQUENCE {
1931 ava AttributeValueAssertion }
1933 Fields of the Compare Request are:
1935 - entry: the name of the entry to be compared. The server SHALL NOT
1936 dereference any aliases in locating the entry to be compared.
1938 - ava: holds the attribute value assertion to be compared.
1940 Upon receipt of a Compare Request, a server will attempt to perform
1941 the requested comparison and return the result in the Compare
1942 Response, defined as follows:
1944 Sermersheim Internet-Draft - Expires Aug 2005 Page 33
1946 Lightweight Directory Access Protocol Version 3
1949 CompareResponse ::= [APPLICATION 15] LDAPResult
1951 The resultCode is set to compareTrue, compareFalse, or an appropriate
1952 error. compareTrue indicates that the assertion value in the ava
1953 field matches a value of the attribute or subtype according to the
1954 attribute's EQUALITY matching rule. compareFalse indicates that the
1955 assertion value in the ava field and the values of the attribute or
1956 subtype did not match. Other result codes indicate either that the
1957 result of the comparison was Undefined (Section 4.5.1), or that some
1960 Note that some directory systems may establish access controls which
1961 permit the values of certain attributes (such as userPassword) to be
1962 compared but not interrogated by other means.
1965 4.11. Abandon Operation
1967 The function of the Abandon operation is to allow a client to request
1968 that the server abandon an uncompleted operation. The Abandon Request
1969 is defined as follows:
1971 AbandonRequest ::= [APPLICATION 16] MessageID
1973 The MessageID is that of an operation which was requested earlier at
1974 this LDAP message layer. The Abandon request itself has its own
1975 MessageID. This is distinct from the MessageID of the earlier
1976 operation being abandoned.
1978 There is no response defined in the Abandon operation. Upon receipt
1979 of an AbandonRequest, the server MAY abandon the operation identified
1980 by the MessageID. Since the client cannot tell the difference between
1981 a successfully abandoned operation and an uncompleted operation, the
1982 application of the Abandon operation is limited to uses where the
1983 client does not require an indication of its outcome.
1985 Abandon, Bind, Unbind, and StartTLS operations cannot be abandoned.
1987 In the event that a server receives an Abandon Request on a Search
1988 operation in the midst of transmitting responses to the Search, that
1989 server MUST cease transmitting entry responses to the abandoned
1990 request immediately, and MUST NOT send the SearchResultDone. Of
1991 course, the server MUST ensure that only properly encoded LDAPMessage
1992 PDUs are transmitted.
1994 The ability to abandon other (particularly update) operations is at
1995 the discretion of the server.
1997 Clients should not send Abandon requests for the same operation
1998 multiple times, and MUST also be prepared to receive results from
1999 operations it has abandoned (since these may have been in transit
2000 when the Abandon was requested, or are not able to be abandoned).
2003 Sermersheim Internet-Draft - Expires Aug 2005 Page 34
2005 Lightweight Directory Access Protocol Version 3
2007 Servers MUST discard Abandon requests for message IDs they do not
2008 recognize, for operations which cannot be abandoned, and for
2009 operations which have already been abandoned.
2012 4.12. Extended Operation
2014 The Extended operation allows additional operations to be defined for
2015 services not already available in the protocol. For example, to Add
2016 operations to install transport layer security (see Section 4.14).
2018 The Extended operation allows clients to make requests and receive
2019 responses with predefined syntaxes and semantics. These may be
2020 defined in RFCs or be private to particular implementations.
2022 Each Extended operation consists of an Extended request and an
2025 ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
2026 requestName [0] LDAPOID,
2027 requestValue [1] OCTET STRING OPTIONAL }
2029 The requestName is a dotted-decimal representation of the unique
2030 OBJECT IDENTIFIER corresponding to the request. The requestValue is
2031 information in a form defined by that request, encapsulated inside an
2034 The server will respond to this with an LDAPMessage containing an
2037 ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
2038 COMPONENTS OF LDAPResult,
2039 responseName [10] LDAPOID OPTIONAL,
2040 responseValue [11] OCTET STRING OPTIONAL }
2042 The responseName is typically not required to be present as the
2043 syntax and semantics of the response (including the format of the
2044 responseValue) is implicitly known and associated with the request by
2047 If the Extended operation associated with the requestName is not
2048 supported by the server, the server MUST NOT provide a responseName
2049 nor a responseValue and MUST return with resultCode set to
2052 The requestValue and responseValue fields contain any information
2053 associated with the operation. The format of these fields is defined
2054 by the specification of the Extended operation. Implementations MUST
2055 be prepared to handle arbitrary contents of these fields, including
2056 zero bytes. Values that are defined in terms of ASN.1 and BER encoded
2057 according to Section 5.1, also follow the extensibility rules in
2062 Sermersheim Internet-Draft - Expires Aug 2005 Page 35
2064 Lightweight Directory Access Protocol Version 3
2066 Servers list the requestName of Extended Requests they recognize in
2067 the 'supportedExtension' attribute in the root DSE (Section 5.1 of
2070 Extended operations may be specified in other documents. The
2071 specification of an Extended operation consists of:
2073 - the OBJECT IDENTIFIER assigned to the requestName,
2075 - the OBJECT IDENTIFIER (if any) assigned to the responseName (note
2076 that the same OBJECT IDENTIFIER my be used for both the
2077 requestName and responseName),
2079 - the format of the contents of the requestValue and responseValue
2082 - the semantics of the operation.
2085 4.13. IntermediateResponse Message
2087 While the Search operation provides a mechanism to return multiple
2088 response messages for a single Search request, other operations, by
2089 nature, do not provide for multiple response messages.
2091 The IntermediateResponse message provides a general mechanism for
2092 defining single-request/multiple-response operations in LDAP. This
2093 message is intended to be used in conjunction with the Extended
2094 operation to define new single-request/multiple-response operations
2095 or in conjunction with a control when extending existing LDAP
2096 operations in a way that requires them to return Intermediate
2097 response information.
2099 It is intended that the definitions and descriptions of Extended
2100 operations and controls that make use of the IntermediateResponse
2101 message will define the circumstances when an IntermediateResponse
2102 message can be sent by a server and the associated meaning of an
2103 IntermediateResponse message sent in a particular circumstance.
2105 IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
2106 responseName [0] LDAPOID OPTIONAL,
2107 responseValue [1] OCTET STRING OPTIONAL }
2109 IntermediateResponse messages SHALL NOT be returned to the client
2110 unless the client issues a request that specifically solicits their
2111 return. This document defines two forms of solicitation: Extended
2112 operation and request control. IntermediateResponse messages are
2113 specified in documents describing the manner in which they are
2114 solicited (i.e. in the Extended operation or request control
2115 specification that uses them). These specifications include:
2117 - the OBJECT IDENTIFIER (if any) assigned to the responseName,
2119 - the format of the contents of the responseValue (if any), and
2121 Sermersheim Internet-Draft - Expires Aug 2005 Page 36
2123 Lightweight Directory Access Protocol Version 3
2126 - the semantics associated with the IntermediateResponse message.
2128 Extensions that allow the return of multiple types of
2129 IntermediateResponse messages SHALL identify those types using unique
2130 responseName values (note that one of these may specify no value).
2132 Sections 4.13.1 and 4.13.2 describe additional requirements on the
2133 inclusion of responseName and responseValue in IntermediateResponse
2137 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse
2139 A single-request/multiple-response operation may be defined using a
2140 single ExtendedRequest message to solicit zero or more
2141 IntermediateResponse messages of one or more kinds followed by an
2142 ExtendedResponse message.
2145 4.13.2. Usage with LDAP Request Controls
2147 A control's semantics may include the return of zero or more
2148 IntermediateResponse messages prior to returning the final result
2149 code for the operation. One or more kinds of IntermediateResponse
2150 messages may be sent in response to a request control.
2152 All IntermediateResponse messages associated with request controls
2153 SHALL include a responseName. This requirement ensures that the
2154 client can correctly identify the source of IntermediateResponse
2157 - two or more controls using IntermediateResponse messages are
2158 included in a request for any LDAP operation or
2160 - one or more controls using IntermediateResponse messages are
2161 included in a request with an LDAP Extended operation that uses
2162 IntermediateResponse messages.
2165 4.14. StartTLS Operation
2167 The Start Transport Layer Security (StartTLS) operation's purpose is
2168 to initiate installation of a TLS layer. The StartTLS operation is
2169 defined using the Extended operation mechanism described in Section
2180 Sermersheim Internet-Draft - Expires Aug 2005 Page 37
2182 Lightweight Directory Access Protocol Version 3
2184 4.14.1. StartTLS Request
2186 A client requests TLS establishment by transmitting a StartTLS
2187 request PDU to the server. The StartTLS request is defined in terms
2188 of an ExtendedRequest. The requestName is "1.3.6.1.4.1.1466.20037",
2189 and the requestValue field is always absent.
2191 The client MUST NOT send any PDUs at this LDAP message layer
2192 following this request until it receives a StartTLS Extended response
2193 and, in the case of a successful response, completes TLS
2196 Detected sequencing problems (particularly those detailed in Section
2197 3.1.1 of [AuthMeth]) result in the resultCode being set to
2200 If the server does not support TLS (whether by design or by current
2201 configuration), it returns with the resultCode set to protocolError
2202 as described in Section 4.12.
2205 4.14.2. StartTLS Response
2207 When a StartTLS request is made, servers supporting the operation
2208 MUST return a StartTLS response PDU to the requestor. The
2209 responseName, if present, is also "1.3.6.1.4.1.1466.20037". The
2210 responseValue is absent.
2212 If the server is willing and able to negotiate TLS, it returns with
2213 the resultCode set to success. Refer to Section 4 of [AuthMeth] for
2216 If the server is otherwise unwilling or unable to perform this
2217 operation, the server is to return an appropriate result code
2218 indicating the nature of the problem. For example, if the TLS
2219 subsystem is not presently available, the server may indicate so by
2220 returning with the resultCode set to unavailable.
2223 4.14.3. Removal of the TLS Layer
2225 Either the client or server MAY remove the TLS layer and leave the
2226 LDAP message layer intact by sending and receiving a TLS closure
2229 The initiating protocol peer sends the TLS closure alert. If it
2230 wishes to leave the LDAP message layer intact, it then MUST cease to
2231 send further PDUs and MUST ignore any received LDAP PDUs until it
2232 receives a TLS closure alert from the other peer.
2234 Once the initiating protocol peer receives a TLS closure alert from
2235 the other peer it MAY send and receive LDAP PDUs.
2237 Sermersheim Internet-Draft - Expires Aug 2005 Page 38
2239 Lightweight Directory Access Protocol Version 3
2242 When a protocol peer receives the initial TLS closure alert, it may
2243 choose to allow the LDAP message layer to remain intact. In this
2244 case, it MUST immediately transmit a TLS closure alert. Following
2245 this, it MAY send and receive LDAP PDUs.
2247 Protocol peers MAY terminate the LDAP session after sending or
2248 receiving a TLS closure alert.
2250 After the TLS layer has been removed, the server MUST NOT send
2251 responses to any request message received before the TLS closure
2252 alert. Thus, clients wishing to receive responses to messages sent
2253 while the TLS layer is intact MUST wait for those message responses
2254 before sending the TLS closure alert.
2257 5. Protocol Encoding, Connection, and Transfer
2259 This protocol is designed to run over connection-oriented, reliable
2260 transports, where the data stream is divided into octets (8-bit
2261 units), with each octet and each bit being significant.
2263 One underlying service, LDAP over TCP, is defined in Section
2264 5.2. This service is generally applicable to applications providing
2265 or consuming X.500-based directory services on the Internet. This
2266 specification was generally written with the TCP mapping in mind.
2267 Specifications detailing other mappings may encounter various
2270 Implementations of LDAP over TCP MUST implement the mapping as
2271 described in Section 5.2.
2273 This table illustrates the relationship between the different layers
2274 involved in an exchange between two protocol peers:
2276 +----------------------+
2277 | LDAP message layer |
2278 +----------------------+ > LDAP PDUs
2279 +----------------------+ < data
2281 +----------------------+ > SASL-protected data
2282 +----------------------+ < data
2284 Application +----------------------+ > TLS-protected data
2285 ------------+----------------------+ < data
2286 Transport | transport connection |
2287 +----------------------+
2296 Sermersheim Internet-Draft - Expires Aug 2005 Page 39
2298 Lightweight Directory Access Protocol Version 3
2301 5.1. Protocol Encoding
2303 The protocol elements of LDAP SHALL be encoded for exchange using the
2304 Basic Encoding Rules [BER] of [ASN.1] with the following
2307 - Only the definite form of length encoding is used.
2309 - OCTET STRING values are encoded in the primitive form only.
2311 - If the value of a BOOLEAN type is true, the encoding of the value
2312 octet is set to hex "FF".
2314 - If a value of a type is its default value, it is absent. Only some
2315 BOOLEAN and INTEGER types have default values in this protocol
2318 These restrictions are meant to ease the overhead of encoding and
2319 decoding certain elements in BER.
2321 These restrictions do not apply to ASN.1 types encapsulated inside of
2322 OCTET STRING values, such as attribute values, unless otherwise
2326 5.2. Transmission Control Protocol (TCP)
2328 The encoded LDAPMessage PDUs are mapped directly onto the [TCP]
2329 bytestream using the BER-based encoding described in Section 5.1. It
2330 is recommended that server implementations running over the TCP
2331 provide a protocol listener on the Internet Assigned Numbers
2332 Authority (IANA)-assigned LDAP port, 389 [PortReg]. Servers may
2333 instead provide a listener on a different port number. Clients MUST
2334 support contacting servers on any valid TCP port.
2337 5.3. Termination of the LDAP session
2339 Termination of the LDAP session is typically initiated by the client
2340 sending an UnbindRequst (Section 4.3), or by the server sending a
2341 Notice of Disconnection (Section 4.4.1). In these cases each protocol
2342 peer gracefully terminates the LDAP session by ceasing exchanges at
2343 the LDAP message layer, tearing down any SASL layer, tearing down any
2344 TLS layer, and closing the transport connection.
2346 A protocol peer may determine that the continuation of any
2347 communication would be pernicious, and in this case may abruptly
2348 terminate the session by ceasing communication and closing the
2349 transport connection.
2351 In either case, when the LDAP session is terminated, uncompleted
2352 operations are handled as specified in Section 3.1.
2355 Sermersheim Internet-Draft - Expires Aug 2005 Page 40
2357 Lightweight Directory Access Protocol Version 3
2361 6. Security Considerations
2363 This version of the protocol provides facilities for simple
2364 authentication using a cleartext password, as well as any [SASL]
2365 mechanism. Installing SASL and/or TLS layers can provide integrity
2366 and other data security services.
2368 It is also permitted that the server can return its credentials to
2369 the client, if it chooses to do so.
2371 Use of cleartext password is strongly discouraged where the
2372 underlying transport service cannot guarantee confidentiality and may
2373 result in disclosure of the password to unauthorized parties.
2375 Servers are encouraged to prevent directory modifications by clients
2376 that have authenticated anonymously [AuthMeth].
2378 Security considerations for authentication methods, SASL mechanisms,
2379 and TLS are described in [AuthMeth].
2381 It should be noted that SASL authentication exchanges do not provide
2382 data confidentiality nor integrity protection for the version or name
2383 fields of the BindRequest nor the resultCode, diagnosticMessage, or
2384 referral fields of the BindResponse nor of any information contained
2385 in controls attached to Bind requests or responses. Thus information
2386 contained in these fields SHOULD NOT be relied on unless otherwise
2387 protected (such as by establishing protections at the transport
2390 Server implementors should plan for the possibility of (protocol or
2391 external) events which alter the information used to establish
2392 security factors (e.g., credentials, authorization identities, access
2393 controls) during the course of the LDAP session, and even during the
2394 performance of a particular operation, and should take steps to avoid
2395 insecure side effects of these changes. The ways in which these
2396 issues are addressed are application and/or implementation specific.
2398 Implementations which cache attributes and entries obtained via LDAP
2399 MUST ensure that access controls are maintained if that information
2400 is to be provided to multiple clients, since servers may have access
2401 control policies which prevent the return of entries or attributes in
2402 Search results except to particular authenticated clients. For
2403 example, caches could serve result information only to the client
2404 whose request caused it to be in the cache.
2406 Servers may return referrals or Search result references which
2407 redirect clients to peer servers. It is possible for a rogue
2408 application to inject such referrals into the data stream in an
2409 attempt to redirect a client to a rogue server. Clients are advised
2410 to be aware of this, and possibly reject referrals when
2411 confidentiality measures are not in place. Clients are advised to
2412 reject referrals from the StartTLS operation.
2414 Sermersheim Internet-Draft - Expires Aug 2005 Page 41
2416 Lightweight Directory Access Protocol Version 3
2419 The matchedDN and diagnosticMessage fields, as well as some
2420 resultCode values (e.g., attributeOrValueExists and
2421 entryAlreadyExists), could disclose the presence or absence of
2422 specific data in the directory which is subject to access and other
2423 administrative controls. Server implementations should restrict
2424 access to protected information equally under both normal and error
2427 Protocol peers MUST be prepared to handle invalid and arbitrary
2428 length protocol encodings. Invalid protocol encodings include: BER
2429 encoding exceptions, format string and UTF-8 encoding exceptions,
2430 overflow exceptions, integer value exceptions, and binary mode on/off
2431 flag exceptions. The LDAPv3 PROTOS [PROTOS-LDAP] test suite provides
2432 excellent examples of these exceptions and test cases used to
2435 In the event that a protocol peer senses an attack which in its
2436 nature could cause damage due to further communication at any layer
2437 in the LDAP session, the protocol peer should abruptly terminate the
2438 LDAP session as described in Section 5.3.
2443 This document is based on RFC 2251 by Mark Wahl, Tim Howes, and Steve
2444 Kille. RFC 2251 was a product of the IETF ASID Working Group.
2446 It is also based on RFC 2830 by Jeff Hodges, RL "Bob" Morgan, and
2447 Mark Wahl. RFC 2830 was a product of the IETF LDAPEXT Working Group.
2449 It is also based on RFC 3771 by Roger Harrison, and Kurt Zeilenga.
2450 RFC 3771 was an individual submission to the IETF.
2452 This document is a product of the IETF LDAPBIS Working Group.
2453 Significant contributors of technical review and content include Kurt
2454 Zeilenga, Steven Legg, and Hallvard Furuseth.
2457 8. Normative References
2459 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
2460 Specifications: ABNF", RFC 2234, November 1997.
2462 [ASN.1] ITU-T Recommendation X.680 (07/2002) | ISO/IEC 8824-1:2002
2463 "Information Technology - Abstract Syntax Notation One
2464 (ASN.1): Specification of basic notation"
2466 [AuthMeth] Harrison, R., "LDAP: Authentication Methods and Connection
2467 Level Security Mechanisms", draft-ietf-ldapbis-authmeth-
2468 xx.txt, (a work in progress).
2473 Sermersheim Internet-Draft - Expires Aug 2005 Page 42
2475 Lightweight Directory Access Protocol Version 3
2477 [BER] ITU-T Rec. X.690 (07/2002) | ISO/IEC 8825-1:2002,
2478 "Information technology - ASN.1 encoding rules:
2479 Specification of Basic Encoding Rules (BER), Canonical
2480 Encoding Rules (CER) and Distinguished Encoding Rules
2483 [IP] Postel, J., "Internet Protocol", STD5 and RFC 791,
2486 [ISO10646] Universal Multiple-Octet Coded Character Set (UCS) -
2487 Architecture and Basic Multilingual Plane, ISO/IEC 10646-1
2490 [Keyword] Bradner, S., "Key words for use in RFCs to Indicate
2491 Requirement Levels", RFC 2119, March 1997.
2493 [LDAPDN] Zeilenga, K., "LDAP: String Representation of
2494 Distinguished Names", draft-ietf-ldapbis-dn-xx.txt, (a
2497 [LDAPIANA] Zeilenga, K., "IANA Considerations for LDAP", draft-ietf-
2498 ldapbis-bcp64-xx.txt, (a work in progress).
2500 [LDAPURL] Smith, M., "LDAP: Uniform Resource Locator", draft-ietf-
2501 ldapbis-url-xx.txt, (a work in progress).
2503 [Models] Zeilenga, K., "LDAP: Directory Information Models", draft-
2504 ietf-ldapbis-models-xx.txt (a work in progress).
2506 [Roadmap] Zeilenga, K., "LDAP: Technical Specification Road Map",
2507 draft-ietf-ldapbis-roadmap-xx.txt (a work in progress).
2509 [SASL] Melnikov, A., "Simple Authentication and Security Layer",
2510 draft-ietf-sasl-rfc2222bis-xx.txt (a work in progress).
2512 [SASLPrep] Zeilenga, K., "Stringprep profile for user names and
2513 passwords", draft-ietf-sasl-saslprep-xx.txt, (a work in
2516 [StringPrep] Hoffman P. and M. Blanchet, "Preparation of
2517 Internationalized Strings ('stringprep')", draft-hoffman-
2518 rfc3454bis-xx.txt, a work in progress.
2520 [Syntaxes] Legg, S., and K. Dally, "LDAP: Syntaxes and Matching
2521 Rules", draft-ietf-ldapbis-syntaxes-xx.txt, (a work in
2524 [TCP] Postel, J., "Transmission Control Protocol", STD7 and RFC
2527 [TLS] Dierks, T. and C. Allen. "The TLS Protocol Version 1.1",
2528 draft-ietf-tls-rfc2246-bis-xx.txt, a work in progress.
2532 Sermersheim Internet-Draft - Expires Aug 2005 Page 43
2534 Lightweight Directory Access Protocol Version 3
2536 [Unicode] The Unicode Consortium, "The Unicode Standard, Version
2537 3.2.0" is defined by "The Unicode Standard, Version 3.0"
2538 (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5),
2539 as amended by the "Unicode Standard Annex #27: Unicode
2540 3.1" (http://www.unicode.org/reports/tr27/) and by the
2541 "Unicode Standard Annex #28: Unicode 3.2"
2542 (http://www.unicode.org/reports/tr28/).
2544 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
2545 Resource Identifiers (URI): Generic Syntax", RFC 2396,
2548 [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
2549 10646", STD63 and RFC3629, November 2003.
2551 [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts,
2552 Models and Service", 1993.
2554 [X.501] ITU-T Rec. X.501, "The Directory: Models", 1993.
2556 [X.511] ITU-T Rec. X.511, "The Directory: Abstract Service
2560 9. Informative References
2562 [Glossary] The Unicode Consortium, "Unicode Glossary",
2563 <http://www.unicode.org/glossary/>.
2565 [CharModel] Whistler, K. and M. Davis, "Unicode Technical Report
2566 #17, Character Encoding Model", UTR17,
2567 <http://www.unicode.org/unicode/reports/tr17/>, August
2570 [PROTOS-LDAP] University of Oulu, "PROTOS Test-Suite: c06-ldapv3"
2571 <http://www.ee.oulu.fi/research/ouspg/protos/testing/c06/l
2574 [PortReg] IANA, "Port Numbers",
2575 http://www.iana.org/assignments/port-numbers
2578 10. IANA Considerations
2580 It is requested that the Internet Assigned Numbers Authority (IANA)
2581 update the LDAP result code registry to indicate that this document
2582 provides the definitive technical specification for result codes 0-
2583 36, 48-54, 64-70, 80-90.
2585 It is requested that the IANA update the LDAP Protocol Mechanism
2586 registry to indicate that this document and [AuthMeth] provides the
2587 definitive technical specification for the StartTLS
2588 (1.3.6.1.4.1.1466.20037) Extended operation.
2591 Sermersheim Internet-Draft - Expires Aug 2005 Page 44
2593 Lightweight Directory Access Protocol Version 3
2595 It is requested that the IANA update the occurrence of "RFC XXXX" in
2596 Appendix B with this RFC number at publication.
2599 11. Editor's Address
2603 1800 South Novell Place
2604 Provo, Utah 84606, USA
2650 Sermersheim Internet-Draft - Expires Aug 2005 Page 45
2652 Lightweight Directory Access Protocol Version 3
2654 Appendix A - LDAP Result Codes
2656 This normative appendix details additional considerations regarding
2657 LDAP result codes and provides a brief, general description of each
2658 LDAP result code enumerated in Section 4.1.9.
2660 Additional result codes MAY be defined for use with extensions
2661 [LDAPIANA]. Client implementations SHALL treat any result code which
2662 they do not recognize as an unknown error condition.
2664 Servers may substitute some result codes due to access controls which
2665 prevent their disclosure.
2668 A.1 Non-Error Result Codes
2670 These result codes (called "non-error" result codes) do not indicate
2676 saslBindInProgress (14).
2678 The success, compareTrue, and compareFalse result codes indicate
2679 successful completion (and, hence, are referred to as "successful"
2682 The referral and saslBindInProgress result codes indicate the client
2683 needs to take additional action to complete the operation.
2688 Existing LDAP result codes are described as follows:
2691 Indicates the successful completion of an operation. Note:
2692 this code is not used with the Compare operation. See
2693 compareFalse (5) and compareTrue (6).
2696 Indicates that the operation is not properly sequenced with
2697 relation to other operations (of same or different type).
2699 For example, this code is returned if the client attempts to
2700 StartTLS [TLS] while there are other uncompleted operations
2701 or if a TLS layer was already installed.
2704 Indicates the server received data which is not well-formed.
2709 Sermersheim Internet-Draft - Expires Aug 2005 Page 46
2711 Lightweight Directory Access Protocol Version 3
2713 For Bind operation only, this code is also used to indicate
2714 that the server does not support the requested protocol
2717 For Extended operations only, this code is also used to
2718 indicate that the server does not support (by design or
2719 configuration) the Extended operation associated with the
2722 For request operations specifying multiple controls, this may
2723 be used to indicate that the server cannot ignore the order
2724 of the controls as specified, or that the combination of the
2725 specified controls is invalid or unspecified.
2727 timeLimitExceeded (3)
2728 Indicates that the time limit specified by the client was
2729 exceeded before the operation could be completed.
2731 sizeLimitExceeded (4)
2732 Indicates that the size limit specified by the client was
2733 exceeded before the operation could be completed.
2736 Indicates that the Compare operation has successfully
2737 completed and the assertion has evaluated to FALSE or
2741 Indicates that the Compare operation has successfully
2742 completed and the assertion has evaluated to TRUE.
2744 authMethodNotSupported (7)
2745 Indicates that the authentication method or mechanism is not
2748 strongerAuthRequired (8)
2749 Indicates the server requires strong(er) authentication in
2750 order to complete the operation.
2752 When used with the Notice of Disconnection operation, this
2753 code indicates that the server has detected that an
2754 established security association between the client and
2755 server has unexpectedly failed or been compromised.
2758 Indicates that a referral needs to be chased to complete the
2759 operation (see Section 4.1.10).
2761 adminLimitExceeded (11)
2762 Indicates that an administrative limit has been exceeded.
2764 unavailableCriticalExtension (12)
2765 Indicates a critical control is unrecognized (see Section
2768 Sermersheim Internet-Draft - Expires Aug 2005 Page 47
2770 Lightweight Directory Access Protocol Version 3
2773 confidentialityRequired (13)
2774 Indicates that data confidentiality protections are required.
2776 saslBindInProgress (14)
2777 Indicates the server requires the client to send a new bind
2778 request, with the same SASL mechanism, to continue the
2779 authentication process (see Section 4.2).
2781 noSuchAttribute (16)
2782 Indicates that the named entry does not contain the specified
2783 attribute or attribute value.
2785 undefinedAttributeType (17)
2786 Indicates that a request field contains an unrecognized
2787 attribute description.
2789 inappropriateMatching (18)
2790 Indicates that an attempt was made (e.g. in an assertion) to
2791 use a matching rule not defined for the attribute type
2794 constraintViolation (19)
2795 Indicates that the client supplied an attribute value which
2796 does not conform to the constraints placed upon it by the
2799 For example, this code is returned when multiple values are
2800 supplied to an attribute which has a SINGLE-VALUE constraint.
2802 attributeOrValueExists (20)
2803 Indicates that the client supplied an attribute or value to
2804 be added to an entry, but the attribute or value already
2807 invalidAttributeSyntax (21)
2808 Indicates that a purported attribute value does not conform
2809 to the syntax of the attribute.
2812 Indicates that the object does not exist in the DIT.
2815 Indicates that an alias problem has occurred. For example,
2816 the code may used to indicate an alias has been dereferenced
2817 which names no object.
2819 invalidDNSyntax (34)
2820 Indicates that an LDAPDN or RelativeLDAPDN field (e.g. search
2821 base, target entry, ModifyDN newrdn, etc.) of a request does
2822 not conform to the required syntax or contains attribute
2823 values which do not conform to the syntax of the attribute's
2827 Sermersheim Internet-Draft - Expires Aug 2005 Page 48
2829 Lightweight Directory Access Protocol Version 3
2832 aliasDereferencingProblem (36)
2833 Indicates that a problem occurred while dereferencing an
2834 alias. Typically an alias was encountered in a situation
2835 where it was not allowed or where access was denied.
2837 inappropriateAuthentication (48)
2838 Indicates the server requires the client which had attempted
2839 to bind anonymously or without supplying credentials to
2840 provide some form of credentials.
2842 invalidCredentials (49)
2843 Indicates that the provided credentials (e.g. the user's name
2844 and password) are invalid.
2846 insufficientAccessRights (50)
2847 Indicates that the client does not have sufficient access
2848 rights to perform the operation.
2851 Indicates that the server is too busy to service the
2855 Indicates that the server is shutting down or a subsystem
2856 necessary to complete the operation is offline.
2858 unwillingToPerform (53)
2859 Indicates that the server is unwilling to perform the
2863 Indicates that the server has detected an internal loop (e.g.
2864 while dereferencing aliases or chaining an operation).
2866 namingViolation (64)
2867 Indicates that the entry's name violates naming restrictions.
2869 objectClassViolation (65)
2870 Indicates that the entry violates object class restrictions.
2872 notAllowedOnNonLeaf (66)
2873 Indicates that the operation is inappropriately acting upon a
2876 notAllowedOnRDN (67)
2877 Indicates that the operation is inappropriately attempting to
2878 remove a value which forms the entry's relative distinguished
2881 entryAlreadyExists (68)
2882 Indicates that the request cannot be fulfilled (added, moved,
2883 or renamed) as the target entry already exists.
2886 Sermersheim Internet-Draft - Expires Aug 2005 Page 49
2888 Lightweight Directory Access Protocol Version 3
2891 objectClassModsProhibited (69)
2892 Indicates that an attempt to modify the object class(es) of
2893 an entry's 'objectClass' attribute is prohibited.
2895 For example, this code is returned when a client attempts to
2896 modify the structural object class of an entry.
2898 affectsMultipleDSAs (71)
2899 Indicates that the operation cannot be performed as it would
2900 affect multiple servers (DSAs).
2903 Indicates the server has encountered an internal error.
2945 Sermersheim Internet-Draft - Expires Aug 2005 Page 50
2947 Lightweight Directory Access Protocol Version 3
2949 Appendix B - Complete ASN.1 Definition
2951 This appendix is normative.
2953 Lightweight-Directory-Access-Protocol-V3
2954 -- Copyright (C) The Internet Society (2004). This version of
2955 -- this ASN.1 module is part of RFC XXXX; see the RFC itself
2956 -- for full legal notices.
2959 EXTENSIBILITY IMPLIED ::=
2963 LDAPMessage ::= SEQUENCE {
2964 messageID MessageID,
2966 bindRequest BindRequest,
2967 bindResponse BindResponse,
2968 unbindRequest UnbindRequest,
2969 searchRequest SearchRequest,
2970 searchResEntry SearchResultEntry,
2971 searchResDone SearchResultDone,
2972 searchResRef SearchResultReference,
2973 modifyRequest ModifyRequest,
2974 modifyResponse ModifyResponse,
2975 addRequest AddRequest,
2976 addResponse AddResponse,
2977 delRequest DelRequest,
2978 delResponse DelResponse,
2979 modDNRequest ModifyDNRequest,
2980 modDNResponse ModifyDNResponse,
2981 compareRequest CompareRequest,
2982 compareResponse CompareResponse,
2983 abandonRequest AbandonRequest,
2984 extendedReq ExtendedRequest,
2985 extendedResp ExtendedResponse,
2987 intermediateResponse IntermediateResponse },
2988 controls [0] Controls OPTIONAL }
2990 MessageID ::= INTEGER (0 .. maxInt)
2992 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
2994 LDAPString ::= OCTET STRING -- UTF-8 encoded,
2995 -- [ISO10646] characters
2997 LDAPOID ::= OCTET STRING -- Constrained to <numericoid> [Models]
2999 LDAPDN ::= LDAPString -- Constrained to <distinguishedName>
3004 Sermersheim Internet-Draft - Expires Aug 2005 Page 51
3006 Lightweight Directory Access Protocol Version 3
3008 RelativeLDAPDN ::= LDAPString -- Constrained to <name-component>
3011 AttributeDescription ::= LDAPString
3012 -- Constrained to <attributedescription>
3015 AttributeValue ::= OCTET STRING
3017 AttributeValueAssertion ::= SEQUENCE {
3018 attributeDesc AttributeDescription,
3019 assertionValue AssertionValue }
3021 AssertionValue ::= OCTET STRING
3023 PartialAttribute ::= SEQUENCE {
3024 type AttributeDescription,
3025 vals SET OF value AttributeValue }
3027 Attribute ::= PartialAttribute(WITH COMPONENTS {
3029 vals (SIZE(1..MAX))})
3031 MatchingRuleId ::= LDAPString
3063 Sermersheim Internet-Draft - Expires Aug 2005 Page 52
3065 Lightweight Directory Access Protocol Version 3
3067 LDAPResult ::= SEQUENCE {
3068 resultCode ENUMERATED {
3070 operationsError (1),
3072 timeLimitExceeded (3),
3073 sizeLimitExceeded (4),
3076 authMethodNotSupported (7),
3077 strongerAuthRequired (8),
3080 adminLimitExceeded (11),
3081 unavailableCriticalExtension (12),
3082 confidentialityRequired (13),
3083 saslBindInProgress (14),
3084 noSuchAttribute (16),
3085 undefinedAttributeType (17),
3086 inappropriateMatching (18),
3087 constraintViolation (19),
3088 attributeOrValueExists (20),
3089 invalidAttributeSyntax (21),
3093 invalidDNSyntax (34),
3094 -- 35 reserved for undefined isLeaf --
3095 aliasDereferencingProblem (36),
3097 inappropriateAuthentication (48),
3098 invalidCredentials (49),
3099 insufficientAccessRights (50),
3102 unwillingToPerform (53),
3105 namingViolation (64),
3106 objectClassViolation (65),
3107 notAllowedOnNonLeaf (66),
3108 notAllowedOnRDN (67),
3109 entryAlreadyExists (68),
3110 objectClassModsProhibited (69),
3111 -- 70 reserved for CLDAP --
3112 affectsMultipleDSAs (71),
3117 diagnosticMessage LDAPString,
3118 referral [3] Referral OPTIONAL }
3120 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI
3122 Sermersheim Internet-Draft - Expires Aug 2005 Page 53
3124 Lightweight Directory Access Protocol Version 3
3127 URI ::= LDAPString -- limited to characters permitted in
3130 Controls ::= SEQUENCE OF control Control
3132 Control ::= SEQUENCE {
3133 controlType LDAPOID,
3134 criticality BOOLEAN DEFAULT FALSE,
3135 controlValue OCTET STRING OPTIONAL }
3137 BindRequest ::= [APPLICATION 0] SEQUENCE {
3138 version INTEGER (1 .. 127),
3140 authentication AuthenticationChoice }
3142 AuthenticationChoice ::= CHOICE {
3143 simple [0] OCTET STRING,
3145 sasl [3] SaslCredentials,
3148 SaslCredentials ::= SEQUENCE {
3149 mechanism LDAPString,
3150 credentials OCTET STRING OPTIONAL }
3152 BindResponse ::= [APPLICATION 1] SEQUENCE {
3153 COMPONENTS OF LDAPResult,
3154 serverSaslCreds [7] OCTET STRING OPTIONAL }
3156 UnbindRequest ::= [APPLICATION 2] NULL
3158 SearchRequest ::= [APPLICATION 3] SEQUENCE {
3165 derefAliases ENUMERATED {
3166 neverDerefAliases (0),
3167 derefInSearching (1),
3168 derefFindingBaseObj (2),
3170 sizeLimit INTEGER (0 .. maxInt),
3171 timeLimit INTEGER (0 .. maxInt),
3174 attributes AttributeSelection }
3176 AttributeSelection ::= SEQUENCE OF selector LDAPString
3177 -- The LDAPString is constrained to
3178 -- <attributeSelector> in Section 4.5.1.7
3181 Sermersheim Internet-Draft - Expires Aug 2005 Page 54
3183 Lightweight Directory Access Protocol Version 3
3186 and [0] SET SIZE (1..MAX) OF filter Filter,
3187 or [1] SET SIZE (1..MAX) OF filter Filter,
3189 equalityMatch [3] AttributeValueAssertion,
3190 substrings [4] SubstringFilter,
3191 greaterOrEqual [5] AttributeValueAssertion,
3192 lessOrEqual [6] AttributeValueAssertion,
3193 present [7] AttributeDescription,
3194 approxMatch [8] AttributeValueAssertion,
3195 extensibleMatch [9] MatchingRuleAssertion,
3198 SubstringFilter ::= SEQUENCE {
3199 type AttributeDescription,
3200 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE {
3201 initial [0] AssertionValue, -- can occur at most once
3202 any [1] AssertionValue,
3203 final [2] AssertionValue } -- can occur at most once
3206 MatchingRuleAssertion ::= SEQUENCE {
3207 matchingRule [1] MatchingRuleId OPTIONAL,
3208 type [2] AttributeDescription OPTIONAL,
3209 matchValue [3] AssertionValue,
3210 dnAttributes [4] BOOLEAN DEFAULT FALSE }
3212 SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
3214 attributes PartialAttributeList }
3216 PartialAttributeList ::= SEQUENCE OF
3217 partialAttribute PartialAttribute
3219 SearchResultReference ::= [APPLICATION 19] SEQUENCE
3220 SIZE (1..MAX) OF uri URI
3222 SearchResultDone ::= [APPLICATION 5] LDAPResult
3224 ModifyRequest ::= [APPLICATION 6] SEQUENCE {
3226 changes SEQUENCE OF change SEQUENCE {
3227 operation ENUMERATED {
3232 modification PartialAttribute } }
3234 ModifyResponse ::= [APPLICATION 7] LDAPResult
3236 AddRequest ::= [APPLICATION 8] SEQUENCE {
3238 attributes AttributeList }
3240 Sermersheim Internet-Draft - Expires Aug 2005 Page 55
3242 Lightweight Directory Access Protocol Version 3
3245 AttributeList ::= SEQUENCE OF attribute Attribute
3247 AddResponse ::= [APPLICATION 9] LDAPResult
3249 DelRequest ::= [APPLICATION 10] LDAPDN
3251 DelResponse ::= [APPLICATION 11] LDAPResult
3253 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
3255 newrdn RelativeLDAPDN,
3256 deleteoldrdn BOOLEAN,
3257 newSuperior [0] LDAPDN OPTIONAL }
3259 ModifyDNResponse ::= [APPLICATION 13] LDAPResult
3261 CompareRequest ::= [APPLICATION 14] SEQUENCE {
3263 ava AttributeValueAssertion }
3265 CompareResponse ::= [APPLICATION 15] LDAPResult
3267 AbandonRequest ::= [APPLICATION 16] MessageID
3269 ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
3270 requestName [0] LDAPOID,
3271 requestValue [1] OCTET STRING OPTIONAL }
3273 ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
3274 COMPONENTS OF LDAPResult,
3275 responseName [10] LDAPOID OPTIONAL,
3276 responseValue [11] OCTET STRING OPTIONAL }
3278 IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
3279 responseName [0] LDAPOID OPTIONAL,
3280 responseValue [1] OCTET STRING OPTIONAL }
3299 Sermersheim Internet-Draft - Expires Aug 2005 Page 56
3301 Lightweight Directory Access Protocol Version 3
3303 Appendix C - Changes
3305 This appendix is non-normative.
3307 This appendix summarizes substantive changes made to RFC 2251, RFC
3311 C.1 Changes made to RFC 2251:
3313 This section summarizes the substantive changes made to Sections 1,
3314 2, 3.1, and 4 through the remainder of RFC 2251. Readers should
3315 consult [Models] and [AuthMeth] for summaries of changes to other
3319 C.1.1 Section 1 (Status of this Memo)
3321 - Removed IESG note. Post publication of RFC 2251, mandatory LDAP
3322 authentication mechanisms have been standardized which are
3323 sufficient to remove this note. See [AuthMeth] for authentication
3327 C.1.2 Section 3.1 (Protocol Model) and others
3329 - Removed notes giving history between LDAP v1, v2 and v3. Instead,
3330 added sufficient language so that this document can stand on its
3334 C.1.3 Section 4 (Elements of Protocol)
3336 - Clarified where the extensibility features of ASN.1 apply to the
3337 protocol. This change affected various ASN.1 types by the
3338 inclusion of ellipses (...) to certain elements.
3339 - Removed the requirement that servers which implement version 3 or
3340 later MUST provide the 'supportedLDAPVersion' attribute. This
3341 statement provided no interoperability advantages.
3344 C.1.4 Section 4.1.1 (Message Envelope)
3346 - There was a mandatory requirement for the server to return a
3347 Notice of Disconnection and drop the transport connection when a
3348 PDU is malformed in a certain way. This has been updated such that
3349 the server SHOULD return the Notice of Disconnection, and MUST
3350 terminate the LDAP Session.
3353 C.1.5 Section 4.1.1.1 (Message ID)
3355 - Required that the messageID of requests MUST be non-zero as the
3356 zero is reserved for Notice of Disconnection.
3358 Sermersheim Internet-Draft - Expires Aug 2005 Page 57
3360 Lightweight Directory Access Protocol Version 3
3362 - Specified when it is and isn't appropriate to return an already
3363 used message id. RFC 2251 accidentally imposed synchronous server
3364 behavior in its wording of this.
3367 C.1.6 Section 4.1.2 (String Types)
3369 - Stated that LDAPOID is constrained to <numericoid> from [Models].
3372 C.1.7 Section 4.1.5.1 (Binary Option) and others
3374 - Removed the Binary Option from the specification. There are
3375 numerous interoperability problems associated with this method of
3376 alternate attribute type encoding. Work to specify a suitable
3377 replacement is ongoing.
3380 C.1.8 Section 4.1.8 (Attribute)
3382 - Combined the definitions of PartialAttribute and Attribute here,
3383 and defined Attribute in terms of PartialAttribute.
3386 C.1.9 Section 4.1.10 (Result Message)
3388 - Renamed "errorMessage" to "diagnosticMessage" as it is allowed to
3389 be sent for non-error results.
3390 - Moved some language into Appendix A, and refer the reader there.
3391 - Allowed matchedDN to be present for other result codes than those
3393 - renamed the code "strongAuthRequired" to "strongerAuthRequired" to
3394 clarify that this code may often be returned to indicate that a
3395 stronger authentication is needed to perform a given operation.
3398 C.1.10 Section 4.1.11 (Referral)
3400 - Defined referrals in terms of URIs rather than URLs.
3401 - Removed the requirement that all referral URIs MUST be equally
3402 capable of progressing the operation. The statement was ambiguous
3403 and provided no instructions on how to carry it out.
3404 - Added the requirement that clients MUST NOT loop between servers.
3405 - Clarified the instructions for using LDAPURLs in referrals, and in
3406 doing so added a recommendation that the scope part be present.
3407 - Removed imperatives which required clients to use URLs in specific
3408 ways to progress an operation. These did nothing for
3412 C.1.11 Section 4.1.12 (Controls)
3414 - Specified how control values defined in terms of ASN.1 are to be
3417 Sermersheim Internet-Draft - Expires Aug 2005 Page 58
3419 Lightweight Directory Access Protocol Version 3
3421 - Noted that the criticality field is only applied to request
3422 messages (except UnbindRequest), and must be ignored when present
3423 on response messages and UnbindRequest.
3424 - Added language regarding combinations of controls and the ordering
3425 of controls on a message.
3426 - Specified that when the semantics of the combination of controls
3427 is undefined or unknown, it results in a protocolError.
3428 - Changed "The server MUST be prepared" to "Implementations MUST be
3429 prepared" in the eighth paragraph to reflect that both client and
3430 server implementations must be able to handle this (as both parse
3434 C.1.12 Section 4.2 (Bind Operation)
3436 - Mandated that servers return protocolError when the version is not
3438 - Disambiguated behavior when the simple authentication is used, the
3439 name is empty and the password is non-empty.
3440 - Required servers to not dereference aliases for Bind. This was
3441 added for consistency with other operations and to help ensure
3443 - Required that textual passwords be transferred as UTF-8 encoded
3444 Unicode, and added recommendations on string preparation. This was
3445 to help ensure interoperability of passwords being sent from
3449 C.1.13 Section 4.2.1 (Sequencing of the Bind Request)
3451 - This section was largely reorganized for readability and language
3452 was added to clarify the authentication state of failed and
3453 abandoned Bind operations.
3454 - Removed: "If a SASL transfer encryption or integrity mechanism has
3455 been negotiated, that mechanism does not support the changing of
3456 credentials from one identity to another, then the client MUST
3457 instead establish a new connection."
3458 If there are dependencies between multiple negotiations of a
3459 particular SASL mechanism, the technical specification for that
3460 SASL mechanism details how applications are to deal with them.
3461 LDAP should not require any special handling.
3462 - Dropped MUST imperative in paragraph 3 to align with [Keywords].
3463 - Mandated that clients not send non-Bind operations while a Bind is
3464 in progress, and suggested that servers not process them if they
3465 are received. This is needed to ensure proper sequencing of the
3466 Bind in relationship to other operations.
3469 C.1.14 Section 4.2.3 (Bind Response)
3471 - Moved most error-related text to Appendix A, and added text
3472 regarding certain errors used in conjunction with the Bind
3476 Sermersheim Internet-Draft - Expires Aug 2005 Page 59
3478 Lightweight Directory Access Protocol Version 3
3480 - Prohibited the server from specifying serverSaslCreds when not
3484 C.1.15 Section 4.3 (Unbind Operation)
3486 - Specified that both peers are to cease transmission and terminate
3487 the LDAP session for the Unbind operation.
3490 C.1.16 Section 4.4 (Unsolicited Notification)
3492 - Added instructions for future specifications of Unsolicited
3496 C.1.17 Section 4.5.1 (Search Request)
3498 - SearchRequest attributes is now defined as an AttributeSelection
3499 type rather than AttributeDescriptionList, and an ABNF is
3501 - SearchRequest attributes may contain duplicate attribute
3502 descriptions. This was previously prohibited. Now servers are
3503 instructed to ignore subsequent names when they are duplicated.
3504 This was relaxed in order to allow different short names and also
3505 OIDs to be requested for an attribute.
3506 - The Filter choice SubstringFilter substrings type is now defined
3507 with a lower bound of 1.
3508 - The SubstringFilter substrings 'initial, 'any', and 'final' types
3509 are now AssertionValue rather than LDAPString. Also, added
3510 imperatives stating that 'initial' (if present) must be listed
3511 first, and 'final' (if present) must be listed last.
3512 - Disambiguated the semantics of the derefAliases choices. There was
3513 question as to whether derefInSearching applied to the base object
3514 in a wholeSubtree Search.
3515 - Added instructions for equalityMatch, substrings, greaterOrEqual,
3516 lessOrEqual, and approxMatch.
3519 C.1.18 Section 4.5.2 (Search Result)
3521 - Recommended that servers not use attribute short names when it
3522 knows they are ambiguous or may cause interoperability problems.
3523 - Removed all mention of ExtendedResponse due to lack of
3527 C.1.19 Section 4.5.3 (Continuation References in the Search Result)
3529 - Made changes similar to those made to Section 4.1.11.
3535 Sermersheim Internet-Draft - Expires Aug 2005 Page 60
3537 Lightweight Directory Access Protocol Version 3
3539 C.1.20 Section 4.5.3.1 (Example)
3541 - Fixed examples to adhere to changes made to Section 4.5.3.
3544 C.1.21 Section 4.6 (Modify Operation)
3546 - Replaced AttributeTypeAndValues with Attribute as they are
3548 - Specified the types of modification changes which might
3549 temporarily violate schema. Some readers were under the impression
3550 that any temporary schema violation was allowed.
3553 C.1.22 Section 4.7 (Add Operation)
3555 - Aligned Add operation with X.511 in that the attributes of the RDN
3556 are used in conjunction with the listed attributes to create the
3557 entry. Previously, Add required that the distinguished values be
3558 present in the listed attributes.
3559 - Removed requirement that the objectClass attribute MUST be
3560 specified as some DSE types do not require this attribute.
3561 Instead, generic wording was added, requiring the added entry to
3562 adhere to the data model.
3563 - Removed recommendation regarding placement of objects. This is
3564 covered in the data model document.
3567 C.1.23 Section 4.9 (Modify DN Operation)
3569 - Required servers to not dereference aliases for Modify DN. This
3570 was added for consistency with other operations and to help ensure
3572 - Allow Modify DN to fail when moving between naming contexts.
3573 - Specified what happens when the attributes of the newrdn are not
3574 present on the entry.
3577 C.1.24 Section 4.10 (Compare Operation)
3579 - Specified that compareFalse means that the Compare took place and
3580 the result is false. There was confusion which lead people to
3581 believe that an Undefined match resulted in compareFalse.
3582 - Required servers to not dereference aliases for Compare. This was
3583 added for consistency with other operations and to help ensure
3587 C.1.25 Section 4.11 (Abandon Operation)
3589 - Explained that since Abandon returns no response, clients should
3590 not use it if they need to know the outcome.
3591 - Specified that Abandon and Unbind cannot be abandoned.
3594 Sermersheim Internet-Draft - Expires Aug 2005 Page 61
3596 Lightweight Directory Access Protocol Version 3
3599 C.1.26 Section 4.12 (Extended Operation)
3601 - Specified how values of Extended operations defined in terms of
3602 ASN.1 are to be encoded.
3603 - Added instructions on what Extended operation specifications
3605 - Added a recommendation that servers advertise supported Extended
3609 C.1.27 Section 5.2 (Transfer Protocols)
3611 - Moved referral-specific instructions into referral-related
3615 C.1.28 Section 7 (Security Considerations)
3617 - Reworded notes regarding SASL not protecting certain aspects of
3619 - Noted that Servers are encouraged to prevent directory
3620 modifications by clients that have authenticated anonymously
3622 - Added a note regarding the scenario where an identity is changed
3623 (deleted, privileges or credentials modified, etc.).
3624 - Warned against following referrals that may have been injected in
3626 - Noted that servers should protect information equally, whether in
3627 an error condition or not, and mentioned specifically; matchedDN,
3628 diagnosticMessage, and resultCodes.
3629 - Added a note regarding malformed and long encodings.
3632 C.1.29 Appendix A (Complete ASN.1 Definition)
3634 - Added "EXTENSIBILITY IMPLIED" to ASN.1 definition.
3635 - Removed AttributeType. It is not used.
3638 C.2 Changes made to RFC 2830:
3640 This section summarizes the substantive changes made to Sections of
3641 RFC 2830. Readers should consult [AuthMeth] for summaries of changes
3645 C.2.1 Section 2.3 (Response other than "success")
3647 - Removed wording indicating that referrals can be returned from
3649 - Removed requirement that only a narrow set of result codes can be
3650 returned. Some result codes are required in certain scenarios, but
3651 any other may be returned if appropriate.
3653 Sermersheim Internet-Draft - Expires Aug 2005 Page 62
3655 Lightweight Directory Access Protocol Version 3
3659 C.2.1 Section 4 (Closing a TLS Connection)
3661 - Reworded most of this section and added the requirement that after
3662 the TLS connection has been closed, the server MUST NOT send
3663 responses to any request message received before the TLS closure.
3664 - Removed instructions on abrupt closure as this is covered in other
3665 areas of the document (specifically, Section 5.3)
3668 C.3 Changes made to RFC 3771:
3670 - Rewrote to fit into this document. In general, semantics were
3671 preserved. Supporting and background language seen as redundant
3672 due to its presence in this document was omitted.
3673 - Specified that Intermediate responses to a request may be of
3674 different types, and one of the response types may be specified to
3675 have no response value.
3712 Sermersheim Internet-Draft - Expires Aug 2005 Page 63
3714 Lightweight Directory Access Protocol Version 3
3719 Intellectual Property Statement
3721 The IETF takes no position regarding the validity or scope of any
3722 Intellectual Property Rights or other rights that might be claimed to
3723 pertain to the implementation or use of the technology described in
3724 this document or the extent to which any license under such rights
3725 might or might not be available; nor does it represent that it has
3726 made any independent effort to identify any such rights. Information
3727 on the procedures with respect to rights in RFC documents can be
3728 found in BCP 78 and BCP 79.
3730 Copies of IPR disclosures made to the IETF Secretariat and any
3731 assurances of licenses to be made available, or the result of an
3732 attempt made to obtain a general license or permission for the use of
3733 such proprietary rights by implementers or users of this
3734 specification can be obtained from the IETF on-line IPR repository at
3735 <http://www.ietf.org/ipr>.
3737 The IETF invites any interested party to bring to its attention any
3738 copyrights, patents or patent applications, or other proprietary
3739 rights that may cover technology that may be required to implement
3740 this standard. Please address the information to the IETF at ietf-
3743 Disclaimer of Validity
3745 This document and the information contained herein are provided on an
3746 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
3747 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
3748 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
3749 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
3750 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
3751 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
3755 Copyright (C) The Internet Society (2004). This document is subject
3756 to the rights, licenses and restrictions contained in BCP 78, and
3757 except as set forth therein, the authors retain all their rights.
3761 Funding for the RFC Editor function is currently provided by the
3771 Sermersheim Internet-Draft - Expires Aug 2005 Page 64
projects / openldap / blob