2 Internet-Draft Editor: J. Sermersheim
3 Intended Category: Standard Track Novell, Inc
4 Document: draft-ietf-ldapbis-protocol-29.txt Feb 2005
5 Obsoletes: RFCs 2251, 2830, 3771
13 This document is an Internet-Draft and is subject to all provisions
14 of section 3 of RFC 3667. By submitting this Internet-Draft, each
15 author represents that any applicable patent or other IPR claims of
16 which he or she is aware have been or will be disclosed, and any of
17 which he or she become aware will be disclosed, in accordance with
20 Internet-Drafts are working documents of the Internet Engineering
21 Task Force (IETF), its areas, and its working groups. Note that other
22 groups may also distribute working documents as Internet-Drafts.
24 Internet-Drafts are draft documents valid for a maximum of six months
25 and may be updated, replaced, or obsoleted by other documents at any
26 time. It is inappropriate to use Internet-Drafts as reference
27 material or to cite them other than as "work in progress".
29 The list of current Internet-Drafts can be accessed at
30 <http://www.ietf.org/ietf/1id-abstracts.txt>.
32 The list of Internet-Draft Shadow Directories can be accessed at
33 <http://www.ietf.org/shadow.html>.
35 This Internet-Draft will expire in February 2005.
37 Technical discussion of this document will take place on the IETF
38 LDAP Revision Working Group (LDAPbis) mailing list <ietf-
39 ldapbis@openldap.org>. Please send editorial comments directly to the
40 editor <jimse@novell.com>.
45 Copyright (C) The Internet Society 2004. All Rights Reserved.
49 This document describes the protocol elements, along with their
50 semantics and encodings, of the Lightweight Directory Access Protocol
51 (LDAP). LDAP provides access to distributed directory services that
52 act in accordance with X.500 data and service models. These protocol
53 elements are based on those described in the X.500 Directory Access
57 Sermersheim Internet-Draft - Expires Aug 2005 Page 1
59 Lightweight Directory Access Protocol Version 3
64 1. Introduction....................................................3
65 1.1. Relationship to Other LDAP Specifications.....................3
66 2. Conventions.....................................................3
67 3. Protocol Model..................................................4
68 3.1 Operation and LDAP Message Layer Relationship..................4
69 4. Elements of Protocol............................................5
70 4.1. Common Elements...............................................5
71 4.1.1. Message Envelope............................................5
72 4.1.2. String Types................................................7
73 4.1.3. Distinguished Name and Relative Distinguished Name..........7
74 4.1.4. Attribute Descriptions......................................8
75 4.1.5. Attribute Value.............................................8
76 4.1.6. Attribute Value Assertion...................................8
77 4.1.7. Attribute and PartialAttribute..............................9
78 4.1.8. Matching Rule Identifier....................................9
79 4.1.9. Result Message..............................................9
80 4.1.10. Referral..................................................11
81 4.1.11. Controls..................................................12
82 4.2. Bind Operation...............................................14
83 4.3. Unbind Operation.............................................17
84 4.4. Unsolicited Notification.....................................17
85 4.6. Modify Operation.............................................28
86 4.7. Add Operation................................................29
87 4.8. Delete Operation.............................................30
88 4.9. Modify DN Operation..........................................31
89 4.10. Compare Operation...........................................32
90 4.11. Abandon Operation...........................................33
91 4.12. Extended Operation..........................................34
92 4.13. IntermediateResponse Message................................35
93 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse......36
94 4.13.2. Usage with LDAP Request Controls..........................36
95 4.14. StartTLS Operation..........................................36
96 5. Protocol Encoding, Connection, and Transfer....................38
97 5.1. Protocol Encoding............................................38
98 5.2. Transmission Control Protocol (TCP)..........................39
99 5.3. Termination of the LDAP session..............................39
100 6. Security Considerations........................................39
101 7. Acknowledgements...............................................41
102 8. Normative References...........................................41
103 9. Informative References.........................................43
104 10. IANA Considerations...........................................43
105 11. Editor's Address..............................................43
106 Appendix A - LDAP Result Codes....................................45
107 A.1 Non-Error Result Codes........................................45
108 A.2 Result Codes..................................................45
109 Appendix B - Complete ASN.1 Definition............................50
110 Appendix C - Changes..............................................56
111 C.1 Changes made to RFC 2251:.....................................56
112 C.2 Changes made to RFC 2830:.....................................61
113 C.3 Changes made to RFC 3771:.....................................62
116 Sermersheim Internet-Draft - Expires Aug 2005 Page 2
118 Lightweight Directory Access Protocol Version 3
123 The Directory is "a collection of open systems cooperating to provide
124 directory services" [X.500]. A directory user, which may be a human
125 or other entity, accesses the Directory through a client (or
126 Directory User Agent (DUA)). The client, on behalf of the directory
127 user, interacts with one or more servers (or Directory System Agents
128 (DSA)). Clients interact with servers using a directory access
131 This document details the protocol elements of the Lightweight
132 Directory Access Protocol (LDAP), along with their semantics.
133 Following the description of protocol elements, it describes the way
134 in which the protocol elements are encoded and transferred.
137 1.1. Relationship to Other LDAP Specifications
139 This document is an integral part of the LDAP Technical Specification
140 [Roadmap] which obsoletes the previously defined LDAP technical
141 specification, RFC 3377, in its entirety.
143 This document obsoletes all of RFC 2251 except the following:
144 Sections 3.2, 3.4, 4.1.3 (last paragraph), 4.1.4, 4.1.5, 4.1.5.1,
145 4.1.9 (last paragraph), 5.1, 6.1, and 6.2 (last paragraph) are
146 obsoleted by [Models].
147 Section 3.3 is obsoleted by [Roadmap].
148 Sections 4.2.1 (portions), and 4.2.2 are obsoleted by [AuthMeth].
150 Appendix C.1 summarizes substantive changes to the remaining
153 This document obsoletes RFC 2830, Sections 2 and 4 in entirety. The
154 remainder of RFC 2830 is obsoleted by [AuthMeth]. Appendix C.2
155 summarizes substantive changes to the remaining sections.
157 This document also obsoletes RFC 3771 in entirety.
162 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
163 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
164 to be interpreted as described in [Keyword].
166 Character names in this document use the notation for code points and
167 names from the Unicode Standard [Unicode]. For example, the letter
168 "a" may be represented as either <U+0061> or <LATIN SMALL LETTER A>.
170 Note: a glossary of terms used in Unicode can be found in [Glossary].
171 Information on the Unicode character encoding model can be found in
175 Sermersheim Internet-Draft - Expires Aug 2005 Page 3
177 Lightweight Directory Access Protocol Version 3
179 The term "transport connection" refers to the underlying transport
180 services used to carry the protocol exchange, as well as associations
181 established by these services.
183 The term "TLS layer" refers to TLS services used in providing
184 security services, as well as associations established by these
187 The term "SASL layer" refers to SASL services used in providing
188 security services, as well as associations established by these
191 The term "LDAP message layer" refers to the LDAP Message (PDU)
192 services used in providing directory services, as well as
193 associations established by these services.
195 The term "LDAP session" refers to combined services (transport
196 connection, TLS layer, SASL layer, LDAP message layer) and their
199 See the table in Section 5 for an illustration of these four terms.
204 The general model adopted by this protocol is one of clients
205 performing protocol operations against servers. In this model, a
206 client transmits a protocol request describing the operation to be
207 performed to a server. The server is then responsible for performing
208 the necessary operation(s) in the Directory. Upon completion of an
209 operation, the server typically returns a response containing
210 appropriate data to the requesting client.
212 Protocol operations are generally independent of one another. Each
213 operation is processed as an atomic action, leaving the directory in
216 Although servers are required to return responses whenever such
217 responses are defined in the protocol, there is no requirement for
218 synchronous behavior on the part of either clients or servers.
219 Requests and responses for multiple operations generally may be
220 exchanged between a client and server in any order. If required,
221 synchronous behavior may be controlled by client applications.
223 The core protocol operations defined in this document can be mapped
224 to a subset of the X.500 (1993) Directory Abstract Service [X.511].
225 However there is not a one-to-one mapping between LDAP operations and
226 X.500 Directory Access Protocol (DAP) operations. Server
227 implementations acting as a gateway to X.500 directories may need to
228 make multiple DAP requests to service a single LDAP request.
231 3.1 Operation and LDAP Message Layer Relationship
234 Sermersheim Internet-Draft - Expires Aug 2005 Page 4
236 Lightweight Directory Access Protocol Version 3
238 Protocol operations are exchanged at the LDAP message layer. When the
239 transport connection is closed, any uncompleted operations at the
240 LDAP message layer, when possible, are abandoned, and when not
241 possible, are completed without transmission of the response. Also,
242 when the transport connection is closed, the client MUST NOT assume
243 that any uncompleted update operations have succeeded or failed.
246 4. Elements of Protocol
248 The protocol is described using Abstract Syntax Notation One
249 ([ASN.1]), and is transferred using a subset of ASN.1 Basic Encoding
250 Rules ([BER]). Section 5 specifies how the protocol elements are
251 encoded and transferred.
253 In order to support future extensions to this protocol, extensibility
254 is implied where it is allowed per ASN.1 (i.e. sequence, set, choice,
255 and enumerated types are extensible). In addition, ellipses (...)
256 have been supplied in ASN.1 types that are explicitly extensible as
257 discussed in [LDAPIANA]. Because of the implied extensibility,
258 clients and servers MUST (unless otherwise specified) ignore trailing
259 SEQUENCE components whose tags they do not recognize.
261 Changes to the protocol other than through the extension mechanisms
262 described here require a different version number. A client indicates
263 the version it is using as part of the BindRequest, described in
264 Section 4.2. If a client has not sent a Bind, the server MUST assume
265 the client is using version 3 or later.
267 Clients may attempt to determine the protocol versions a server
268 supports by reading the 'supportedLDAPVersion' attribute from the
269 root DSE (DSA-Specific Entry) [Models].
274 This section describes the LDAPMessage envelope Protocol Data Unit
275 (PDU) format, as well as data type definitions, which are used in the
279 4.1.1. Message Envelope
281 For the purposes of protocol exchanges, all protocol operations are
282 encapsulated in a common envelope, the LDAPMessage, which is defined
285 LDAPMessage ::= SEQUENCE {
288 bindRequest BindRequest,
289 bindResponse BindResponse,
290 unbindRequest UnbindRequest,
291 searchRequest SearchRequest,
293 Sermersheim Internet-Draft - Expires Aug 2005 Page 5
295 Lightweight Directory Access Protocol Version 3
297 searchResEntry SearchResultEntry,
298 searchResDone SearchResultDone,
299 searchResRef SearchResultReference,
300 modifyRequest ModifyRequest,
301 modifyResponse ModifyResponse,
302 addRequest AddRequest,
303 addResponse AddResponse,
304 delRequest DelRequest,
305 delResponse DelResponse,
306 modDNRequest ModifyDNRequest,
307 modDNResponse ModifyDNResponse,
308 compareRequest CompareRequest,
309 compareResponse CompareResponse,
310 abandonRequest AbandonRequest,
311 extendedReq ExtendedRequest,
312 extendedResp ExtendedResponse,
314 intermediateResponse IntermediateResponse },
315 controls [0] Controls OPTIONAL }
317 MessageID ::= INTEGER (0 .. maxInt)
319 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
321 The ASN.1 type Controls is defined in Section 4.1.11.
323 The function of the LDAPMessage is to provide an envelope containing
324 common fields required in all protocol exchanges. At this time the
325 only common fields are the messageID and the controls.
327 If the server receives a PDU from the client in which the LDAPMessage
328 SEQUENCE tag cannot be recognized, the messageID cannot be parsed,
329 the tag of the protocolOp is not recognized as a request, or the
330 encoding structures or lengths of data fields are found to be
331 incorrect, then the server SHOULD return the Notice of Disconnection
332 described in Section 4.4.1, with the resultCode set to protocolError,
333 and MUST immediately terminate the LDAP session as described in
336 In other cases where the client or server cannot parse a PDU, it
337 SHOULD abruptly terminate the LDAP session (Section 5.3) where
338 further communication (including providing notice) would be
339 pernicious. Otherwise, server implementations MUST return an
340 appropriate response to the request, with the resultCode set to
346 All LDAPMessage envelopes encapsulating responses contain the
347 messageID value of the corresponding request LDAPMessage.
349 The message ID of a request MUST have a non-zero value different from
350 the messageID of any other request in progress in the same LDAP
352 Sermersheim Internet-Draft - Expires Aug 2005 Page 6
354 Lightweight Directory Access Protocol Version 3
356 session. The zero value is reserved for the unsolicited notification
359 Typical clients increment a counter for each request.
361 A client MUST NOT send a request with the same message ID as an
362 earlier request in the same LDAP session unless it can be determined
363 that the server is no longer servicing the earlier request (e.g.
364 after the final response is received, or a subsequent Bind
365 completes). Otherwise the behavior is undefined. For this purpose,
366 note that Abandon and successfully abandoned operations do not send
372 The LDAPString is a notational convenience to indicate that, although
373 strings of LDAPString type encode as ASN.1 OCTET STRING types, the
374 [ISO10646] character set (a superset of [Unicode]) is used, encoded
375 following the [UTF-8] algorithm. Note that Unicode characters U+0000
376 through U+007F are the same as ASCII 0 through 127, respectively, and
377 have the same single octet UTF-8 encoding. Other Unicode characters
378 have a multiple octet UTF-8 encoding.
380 LDAPString ::= OCTET STRING -- UTF-8 encoded,
381 -- [ISO10646] characters
383 The LDAPOID is a notational convenience to indicate that the
384 permitted value of this string is a (UTF-8 encoded) dotted-decimal
385 representation of an OBJECT IDENTIFIER. Although an LDAPOID is
386 encoded as an OCTET STRING, values are limited to the definition of
387 <numericoid> given in Section 1.4 of [Models].
389 LDAPOID ::= OCTET STRING -- Constrained to <numericoid> [Models]
393 1.3.6.1.4.1.1466.1.2.3
396 4.1.3. Distinguished Name and Relative Distinguished Name
398 An LDAPDN is defined to be the representation of a Distinguished Name
399 (DN) after encoding according to the specification in [LDAPDN].
401 LDAPDN ::= LDAPString
402 -- Constrained to <distinguishedName> [LDAPDN]
404 A RelativeLDAPDN is defined to be the representation of a Relative
405 Distinguished Name (RDN) after encoding according to the
406 specification in [LDAPDN].
408 RelativeLDAPDN ::= LDAPString
409 -- Constrained to <name-component> [LDAPDN]
411 Sermersheim Internet-Draft - Expires Aug 2005 Page 7
413 Lightweight Directory Access Protocol Version 3
417 4.1.4. Attribute Descriptions
419 The definition and encoding rules for attribute descriptions are
420 defined in Section 2.5 of [Models]. Briefly, an attribute description
421 is an attribute type and zero or more options.
423 AttributeDescription ::= LDAPString
424 -- Constrained to <attributedescription>
428 4.1.5. Attribute Value
430 A field of type AttributeValue is an OCTET STRING containing an
431 encoded attribute value. The attribute value is encoded according to
432 the LDAP-specific encoding definition of its corresponding syntax.
433 The LDAP-specific encoding definitions for different syntaxes and
434 attribute types may be found in other documents and in particular
437 AttributeValue ::= OCTET STRING
439 Note that there is no defined limit on the size of this encoding;
440 thus protocol values may include multi-megabyte attribute values
443 Attribute values may be defined which have arbitrary and non-
444 printable syntax. Implementations MUST NOT display nor attempt to
445 decode an attribute value if its syntax is not known. The
446 implementation may attempt to discover the subschema of the source
447 entry, and retrieve the descriptions of 'attributeTypes' from it
450 Clients MUST only send attribute values in a request that are valid
451 according to the syntax defined for the attributes.
454 4.1.6. Attribute Value Assertion
456 The AttributeValueAssertion (AVA) type definition is similar to the
457 one in the X.500 Directory standards. It contains an attribute
458 description and a matching rule ([Models] Section 4.1.3) assertion
459 value suitable for that type. Elements of this type are typically
460 used to assert that the value in assertionValue matches a value of an
463 AttributeValueAssertion ::= SEQUENCE {
464 attributeDesc AttributeDescription,
465 assertionValue AssertionValue }
467 AssertionValue ::= OCTET STRING
470 Sermersheim Internet-Draft - Expires Aug 2005 Page 8
472 Lightweight Directory Access Protocol Version 3
474 The syntax of the AssertionValue depends on the context of the LDAP
475 operation being performed. For example, the syntax of the EQUALITY
476 matching rule for an attribute is used when performing a Compare
477 operation. Often this is the same syntax used for values of the
478 attribute type, but in some cases the assertion syntax differs from
479 the value syntax. See objectIdentiferFirstComponentMatch in
480 [Syntaxes] for an example.
483 4.1.7. Attribute and PartialAttribute
485 Attributes and partial attributes consist of an attribute description
486 and attribute values. A PartialAttribute allows zero values, while
487 Attribute requires at least one value.
489 PartialAttribute ::= SEQUENCE {
490 type AttributeDescription,
491 vals SET OF value AttributeValue }
493 Attribute ::= PartialAttribute(WITH COMPONENTS {
495 vals (SIZE(1..MAX))})
497 No two of the attribute values may be equivalent as described by
498 Section 2.3 of [Models]. The set of attribute values is unordered.
499 Implementations MUST NOT rely upon the ordering being repeatable.
502 4.1.8. Matching Rule Identifier
504 Matching rules are defined in Section 4.1.3 of [Models]. A matching
505 rule is identified in the protocol by the printable representation of
506 either its <numericoid>, or one of its short name descriptors
507 [Models], e.g. 'caseIgnoreMatch' or '2.5.13.2'.
509 MatchingRuleId ::= LDAPString
512 4.1.9. Result Message
514 The LDAPResult is the construct used in this protocol to return
515 success or failure indications from servers to clients. To various
516 requests, servers will return responses containing the elements found
517 in LDAPResult to indicate the final status of the protocol operation
520 LDAPResult ::= SEQUENCE {
521 resultCode ENUMERATED {
525 timeLimitExceeded (3),
526 sizeLimitExceeded (4),
529 Sermersheim Internet-Draft - Expires Aug 2005 Page 9
531 Lightweight Directory Access Protocol Version 3
534 authMethodNotSupported (7),
535 strongerAuthRequired (8),
538 adminLimitExceeded (11),
539 unavailableCriticalExtension (12),
540 confidentialityRequired (13),
541 saslBindInProgress (14),
542 noSuchAttribute (16),
543 undefinedAttributeType (17),
544 inappropriateMatching (18),
545 constraintViolation (19),
546 attributeOrValueExists (20),
547 invalidAttributeSyntax (21),
551 invalidDNSyntax (34),
552 -- 35 reserved for undefined isLeaf --
553 aliasDereferencingProblem (36),
555 inappropriateAuthentication (48),
556 invalidCredentials (49),
557 insufficientAccessRights (50),
560 unwillingToPerform (53),
563 namingViolation (64),
564 objectClassViolation (65),
565 notAllowedOnNonLeaf (66),
566 notAllowedOnRDN (67),
567 entryAlreadyExists (68),
568 objectClassModsProhibited (69),
569 -- 70 reserved for CLDAP --
570 affectsMultipleDSAs (71),
575 diagnosticMessage LDAPString,
576 referral [3] Referral OPTIONAL }
578 The resultCode enumeration is extensible as defined in Section 3.6 of
579 [LDAPIANA]. The meanings of the listed result codes are given in
580 Appendix A. If a server detects multiple errors for an operation,
581 only one result code is returned. The server should return the result
582 code that best indicates the nature of the error encountered.
584 The diagnosticMessage field of this construct may, at the server's
585 option, be used to return a string containing a textual, human-
586 readable (terminal control and page formatting characters should be
588 Sermersheim Internet-Draft - Expires Aug 2005 Page 10
590 Lightweight Directory Access Protocol Version 3
592 avoided) diagnostic message. As this diagnostic message is not
593 standardized, implementations MUST NOT rely on the values returned.
594 Diagnostic messages typically supplement the resultCode with
595 additional information. If the server chooses not to return a textual
596 diagnostic, the diagnosticMessage field MUST be empty.
598 For certain result codes (typically, but not restricted to
599 noSuchObject, aliasProblem, invalidDNSyntax and
600 aliasDereferencingProblem), the matchedDN field is set (subject to
601 access controls) to the name of the last entry (object or alias) used
602 in finding the target (or base) object. This will be a truncated form
603 of the provided name or, if an alias was dereferenced while
604 attempting to locate the entry, of the resulting name. Otherwise the
605 matchedDN field is empty.
610 The referral result code indicates that the contacted server cannot
611 or will not perform the operation and that one or more other servers
612 may be able to. Reasons for this include:
614 - The target entry of the request is not held locally, but the
615 server has knowledge of its possible existence elsewhere.
617 - The operation is restricted on this server -- perhaps due to a
618 read-only copy of an entry to be modified.
620 The referral field is present in an LDAPResult if the resultCode is
621 set to referral, and absent with all other result codes. It contains
622 one or more references to one or more servers or services that may be
623 accessed via LDAP or other protocols. Referrals can be returned in
624 response to any operation request (except Unbind and Abandon which do
625 not have responses). At least one URI MUST be present in the
628 During a Search operation, after the baseObject is located, and
629 entries are being evaluated, the referral is not returned. Instead,
630 continuation references, described in Section 4.5.3, are returned
631 when other servers would need to be contacted to complete the
634 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI
636 URI ::= LDAPString -- limited to characters permitted in
639 If the client wishes to progress the operation, it contacts one of
640 the supported services found in the referral. If multiple URIs are
641 present, the client assumes that any supported URI may be used to
642 progress the operation.
644 Clients that follow referrals MUST ensure that they do not loop
645 between servers. They MUST NOT repeatedly contact the same server for
647 Sermersheim Internet-Draft - Expires Aug 2005 Page 11
649 Lightweight Directory Access Protocol Version 3
651 the same request with the same parameters. Some clients use a counter
652 that is incremented each time referral handling occurs for an
653 operation, and these kinds of clients MUST be able to handle at least
654 ten nested referrals while progressing the operation.
656 A URI for a server implementing LDAP and accessible via [TCP]/[IP]
657 (v4 or v6) is written as an LDAP URL according to [LDAPURL].
659 Referral values which are LDAP URLs follow these rules:
661 - If an alias was dereferenced, the <dn> part of the LDAP URL MUST
662 be present, with the new target object name.
664 - It is RECOMMENDED that the <dn> part be present to avoid
667 - If the <dn> part is present, the client uses this name in its next
668 request to progress the operation, and if it is not present the
669 client uses the same name as in the original request.
671 - Some servers (e.g. participating in distributed indexing) may
672 provide a different filter in a URL of a referral for a Search
675 - If the <filter> part of the LDAP URL is present, the client uses
676 this filter in its next request to progress this Search, and if it
677 is not present the client uses the same filter as it used for that
680 - For Search, it is RECOMMENDED that the <scope> part be present to
683 - If the <scope> part is missing, the scope of the original Search
684 is used by the client to progress the operation.
686 - Other aspects of the new request may be the same as or different
687 from the request which generated the referral.
689 Other kinds of URIs may be returned. The syntax and semantics of such
690 URIs is left to future specifications. Clients may ignore URIs that
693 UTF-8 encoded characters appearing in the string representation of a
694 DN, search filter, or other fields of the referral value may not be
695 legal for URIs (e.g. spaces) and MUST be escaped using the % method
701 Controls provide a mechanism whereby the semantics and arguments of
702 existing LDAP operations may be extended. One or more controls may be
703 attached to a single LDAP message. A control only affects the
704 semantics of the message it is attached to.
706 Sermersheim Internet-Draft - Expires Aug 2005 Page 12
708 Lightweight Directory Access Protocol Version 3
711 Controls sent by clients are termed 'request controls' and those sent
712 by servers are termed 'response controls'.
714 Controls ::= SEQUENCE OF control Control
716 Control ::= SEQUENCE {
718 criticality BOOLEAN DEFAULT FALSE,
719 controlValue OCTET STRING OPTIONAL }
721 The controlType field is the dotted-decimal representation of an
722 OBJECT IDENTIFIER which uniquely identifies the control. This
723 provides unambiguous naming of controls. Often, response control(s)
724 solicited by a request control share controlType values with the
727 The criticality field only has meaning in controls attached to
728 request messages (except UnbindRequest). For controls attached to
729 response messages and the UnbindRequest, the criticality field SHOULD
730 be FALSE, and MUST be ignored by the receiving protocol peer. A value
731 of TRUE indicates that it is unacceptable to perform the operation
732 without applying the semantics of the control. Specifically, the
733 criticality field is applied as follows:
735 - Regardless of the value of the criticality field, if the server
736 recognizes the control type and it is appropriate for the
737 operation, the server is to make use of the control when
738 performing the operation.
740 - If the server does not recognize the control type or it is not
741 appropriate for the operation, and the criticality field is TRUE,
742 the server MUST NOT perform the operation, and for operations that
743 have a response message, MUST return with the resultCode set to
744 unavailableCriticalExtension.
746 - If the server does not recognize the control type or it is not
747 appropriate for the operation, and the criticality field is FALSE,
748 the server MUST ignore the control.
750 The controlValue may contain information associated with the
751 controlType. Its format is defined by the specification of the
752 control. Implementations MUST be prepared to handle arbitrary
753 contents of the controlValue octet string, including zero bytes. It
754 is absent only if there is no value information which is associated
755 with a control of its type. When a controlValue is defined in terms
756 of ASN.1, and BER encoded according to Section 5.1, it also follows
757 the extensibility rules in Section 4.
759 Servers list the controlType of request controls they recognize in
760 the 'supportedControl' attribute in the root DSE (Section 5.1 of
765 Sermersheim Internet-Draft - Expires Aug 2005 Page 13
767 Lightweight Directory Access Protocol Version 3
769 Controls SHOULD NOT be combined unless the semantics of the
770 combination has been specified. The semantics of control
771 combinations, if specified, are generally found in the control
772 specification most recently published. When a combination of controls
773 is encountered whose semantics are invalid, not specified (or not
774 known), the message is considered to be not well-formed, thus the
775 operation fails with protocolError. Additionally, unless order-
776 dependent semantics are given in a specification, the order of a
777 combination of controls in the SEQUENCE is ignored. Where the order
778 is to be ignored but cannot be ignored by the server, the message is
779 considered not well-formed and the operation fails with
782 This document does not specify any controls. Controls may be
783 specified in other documents. Documents detailing control extensions
784 are to provide for each control:
786 - the OBJECT IDENTIFIER assigned to the control,
788 - direction as to what value the sender should provide for the
789 criticality field (note: the semantics of the criticality field
790 are defined above should not be altered by the control's
793 - whether the controlValue field is present, and if so, the format
796 - the semantics of the control, and
798 - optionally, semantics regarding the combination of the control
804 The function of the Bind operation is to allow authentication
805 information to be exchanged between the client and server. The Bind
806 operation should be thought of as the "authenticate" operation.
807 Operational, authentication, and security-related semantics of this
808 operation are given in [AuthMeth].
810 The Bind request is defined as follows:
812 BindRequest ::= [APPLICATION 0] SEQUENCE {
813 version INTEGER (1 .. 127),
815 authentication AuthenticationChoice }
817 AuthenticationChoice ::= CHOICE {
818 simple [0] OCTET STRING,
820 sasl [3] SaslCredentials,
824 Sermersheim Internet-Draft - Expires Aug 2005 Page 14
826 Lightweight Directory Access Protocol Version 3
828 SaslCredentials ::= SEQUENCE {
829 mechanism LDAPString,
830 credentials OCTET STRING OPTIONAL }
832 Fields of the BindRequest are:
834 - version: A version number indicating the version of the protocol
835 to be used at the LDAP message layer. This document describes
836 version 3 of the protocol. There is no version negotiation. The
837 client sets this field to the version it desires. If the server
838 does not support the specified version, it MUST respond with a
839 BindResponse where the resultCode is set to protocolError.
841 - name: If not empty, the name of the Directory object that the
842 client wishes to bind as. This field may take on a null value (a
843 zero length string) for the purposes of anonymous binds
844 ([AuthMeth] Section 5.1) or when using Simple Authentication and
845 Security Layer [SASL] authentication ([AuthMeth] Section 3.3.2).
846 Where the server attempts to locate the named object, it SHALL NOT
847 perform alias dereferencing.
849 - authentication: information used in authentication. This type is
850 extensible as defined in Section 3.7 of [LDAPIANA]. Servers that
851 do not support a choice supplied by a client return a BindResponse
852 with the resultCode set to authMethodNotSupported.
854 Textual passwords (consisting of a character sequence with a known
855 character set and encoding) transferred to the server using the
856 simple AuthenticationChoice SHALL be transferred as [UTF-8]
857 encoded [Unicode]. Prior to transfer, clients SHOULD prepare text
858 passwords by applying the [SASLprep] profile of the [Stringprep]
859 algorithm. Passwords consisting of other data (such as random
860 octets) MUST NOT be altered. The determination of whether a
861 password is textual is a local client matter.
864 4.2.1. Processing of the Bind Request
866 Before processing a BindRequest, all uncompleted operations MUST
867 either complete or be abandoned. The server may either wait for the
868 uncompleted operations to complete, or abandon them. The server then
869 proceeds to authenticate the client in either a single-step, or
870 multi-step Bind process. Each step requires the server to return a
871 BindResponse to indicate the status of authentication.
873 After sending a BindRequest, clients MUST NOT send further LDAP PDUs
874 until receiving the BindResponse. Similarly, servers SHOULD NOT
875 process or respond to requests received while processing a
878 If the client did not bind before sending a request and receives an
879 operationsError to that request, it may then send a BindRequest. If
880 this also fails or the client chooses not to bind on the existing
881 LDAP session, it may terminate the LDAP session, re-establish it and
883 Sermersheim Internet-Draft - Expires Aug 2005 Page 15
885 Lightweight Directory Access Protocol Version 3
887 begin again by first sending a PDU with a BindRequest. This will aid
888 in interoperating with servers implementing other versions of LDAP.
890 Clients may send multiple Bind requests to change the authentication
891 and/or security associations or to complete a multi-stage Bind
892 process. Authentication from earlier binds is subsequently ignored.
894 For some SASL authentication mechanisms, it may be necessary for the
895 client to invoke the BindRequest multiple times ([AuthMeth] Section
896 8.2). Clients MUST NOT invoke operations between two Bind requests
897 made as part of a multi-stage Bind.
899 A client may abort a SASL bind negotiation by sending a BindRequest
900 with a different value in the mechanism field of SaslCredentials, or
901 an AuthenticationChoice other than sasl.
903 If the client sends a BindRequest with the sasl mechanism field as an
904 empty string, the server MUST return a BindResponse with the
905 resultCode set to authMethodNotSupported. This will allow clients to
906 abort a negotiation if it wishes to try again with the same SASL
912 The Bind response is defined as follows.
914 BindResponse ::= [APPLICATION 1] SEQUENCE {
915 COMPONENTS OF LDAPResult,
916 serverSaslCreds [7] OCTET STRING OPTIONAL }
918 BindResponse consists simply of an indication from the server of the
919 status of the client's request for authentication.
921 A successful Bind operation is indicated by a BindResponse with a
922 resultCode set to success. Otherwise, an appropriate result code is
923 set in the BindResponse. For BindResponse, the protocolError result
924 code may be used to indicate that the version number supplied by the
925 client is unsupported.
927 If the client receives a BindResponse where the resultCode is set to
928 protocolError, it is to assume that the server does not support this
929 version of LDAP. While the client may be able proceed with another
930 version of this protocol (this may or may not require closing and re-
931 establishing the transport connection), how to proceed with another
932 version of this protocol is beyond the scope of this document.
933 Clients which are unable or unwilling to proceed SHOULD terminate the
936 The serverSaslCreds field is used as part of a SASL-defined bind
937 mechanism to allow the client to authenticate the server to which it
938 is communicating, or to perform "challenge-response" authentication.
939 If the client bound with the simple choice, or the SASL mechanism
942 Sermersheim Internet-Draft - Expires Aug 2005 Page 16
944 Lightweight Directory Access Protocol Version 3
946 does not require the server to return information to the client, then
947 this field SHALL NOT be included in the BindResponse.
950 4.3. Unbind Operation
952 The function of the Unbind operation is to terminate an LDAP session.
953 The Unbind operation is not the antithesis of the Bind operation as
954 the name implies. The naming of these operations are historical. The
955 Unbind operation should be thought of as the "quit" operation.
957 The Unbind operation is defined as follows:
959 UnbindRequest ::= [APPLICATION 2] NULL
961 The client, upon transmission of the UnbindRequest, and the server,
962 upon receipt of the UnbindRequest are to gracefully terminate the
963 LDAP session as described in Section 5.3.
965 Uncompleted operations are handled as specified in Section 3.1.
968 4.4. Unsolicited Notification
970 An unsolicited notification is an LDAPMessage sent from the server to
971 the client which is not in response to any LDAPMessage received by
972 the server. It is used to signal an extraordinary condition in the
973 server or in the LDAP session between the client and the server. The
974 notification is of an advisory nature, and the server will not expect
975 any response to be returned from the client.
977 The unsolicited notification is structured as an LDAPMessage in which
978 the messageID is zero and protocolOp is set to the extendedResp
979 choice using the ExtendedResponse type (See Section 4.12). The
980 responseName field of the ExtendedResponse always contains an LDAPOID
981 which is unique for this notification.
983 One unsolicited notification (Notice of Disconnection) is defined in
984 this document. The specification of an unsolicited notification
987 - the OBJECT IDENTIFIER assigned to the notification (to be
988 specified in the responseName,
990 - the format of the contents of the responseValue (if any),
992 - the circumstances which will cause the notification to be sent,
995 - the semantics of the message.
998 4.4.1. Notice of Disconnection
1001 Sermersheim Internet-Draft - Expires Aug 2005 Page 17
1003 Lightweight Directory Access Protocol Version 3
1005 This notification may be used by the server to advise the client that
1006 the server is about to terminate the LDAP session on its own
1007 initiative. This notification is intended to assist clients in
1008 distinguishing between an exceptional server condition and a
1009 transient network failure. Note that this notification is not a
1010 response to an Unbind requested by the client. Uncompleted operations
1011 are handled as specified in Section 3.1.
1013 The responseName is 1.3.6.1.4.1.1466.20036, the responseValue field
1014 is absent, and the resultCode is used to indicate the reason for the
1015 disconnection. When the strongerAuthRequired resultCode is returned
1016 with this message, it indicates that the server has detected that an
1017 established security association between the client and server has
1018 unexpectedly failed or been compromised.
1020 Upon transmission of the Notice of Disconnection, the server
1021 gracefully terminates the LDAP session as described in Section 5.3.
1024 4.5. Search Operation
1026 The Search operation is used to request a server to return, subject
1027 to access controls and other restrictions, a set of entries matching
1028 a complex search criterion. This can be used to read attributes from
1029 a single entry, from entries immediately subordinate to a particular
1030 entry, or a whole subtree of entries.
1033 4.5.1. Search Request
1035 The Search request is defined as follows:
1037 SearchRequest ::= [APPLICATION 3] SEQUENCE {
1044 derefAliases ENUMERATED {
1045 neverDerefAliases (0),
1046 derefInSearching (1),
1047 derefFindingBaseObj (2),
1049 sizeLimit INTEGER (0 .. maxInt),
1050 timeLimit INTEGER (0 .. maxInt),
1053 attributes AttributeSelection }
1055 AttributeSelection ::= SEQUENCE OF selector LDAPString
1056 -- The LDAPString is constrained to
1057 -- <attributeSelector> in Section 4.5.1.7
1060 Sermersheim Internet-Draft - Expires Aug 2005 Page 18
1062 Lightweight Directory Access Protocol Version 3
1065 and [0] SET SIZE (1..MAX) OF filter Filter,
1066 or [1] SET SIZE (1..MAX) OF filter Filter,
1068 equalityMatch [3] AttributeValueAssertion,
1069 substrings [4] SubstringFilter,
1070 greaterOrEqual [5] AttributeValueAssertion,
1071 lessOrEqual [6] AttributeValueAssertion,
1072 present [7] AttributeDescription,
1073 approxMatch [8] AttributeValueAssertion,
1074 extensibleMatch [9] MatchingRuleAssertion,
1077 SubstringFilter ::= SEQUENCE {
1078 type AttributeDescription,
1079 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE {
1080 initial [0] AssertionValue, -- can occur at most once
1081 any [1] AssertionValue,
1082 final [2] AssertionValue } -- can occur at most once
1085 MatchingRuleAssertion ::= SEQUENCE {
1086 matchingRule [1] MatchingRuleId OPTIONAL,
1087 type [2] AttributeDescription OPTIONAL,
1088 matchValue [3] AssertionValue,
1089 dnAttributes [4] BOOLEAN DEFAULT FALSE }
1091 Note that an X.500 "list"-like operation can be emulated by the
1092 client requesting a singleLevel Search operation with a filter
1093 checking for the presence of the 'objectClass' attribute, and that an
1094 X.500 "read"-like operation can be emulated by a baseObject Search
1095 operation with the same filter. A server which provides a gateway to
1096 X.500 is not required to use the Read or List operations, although it
1097 may choose to do so, and if it does, it must provide the same
1098 semantics as the X.500 Search operation.
1101 4.5.1.1 SearchRequest.baseObject
1103 The name of the base object entry (or possibly the root) relative to
1104 which the Search is to be performed.
1107 4.5.1.2 SearchRequest.scope
1109 Specifies the scope of the Search to be performed. The semantics (as
1110 described in [X.511]) of the defined values of this field are:
1112 baseObject: The scope is constrained to the entry named by
1115 singleLevel: The scope is constrained to the immediate
1116 subordinates of the entry named by baseObject.
1119 Sermersheim Internet-Draft - Expires Aug 2005 Page 19
1121 Lightweight Directory Access Protocol Version 3
1123 wholeSubtree: the scope is constrained to the entry named by the
1124 baseObject, and all its subordinates.
1127 4.5.1.3 SearchRequest.derefAliases
1129 An indicator as to whether or not alias entries (as defined in
1130 [Models]) are to be dereferenced during stages of the Search
1133 The act of dereferencing an alias includes recursively dereferencing
1134 aliases which refer to aliases.
1136 Servers MUST detect looping while dereferencing aliases in order to
1137 prevent denial of service attacks of this nature.
1139 The semantics of the defined values of this field are:
1141 neverDerefAliases: Do not dereference aliases in searching or in
1142 locating the base object of the Search.
1144 derefInSearching: While searching subordinates of the base object,
1145 dereference any alias within the search scope. Dereferenced
1146 objects become the vertices of further search scopes where the
1147 Search operation is also applied. If the search scope is
1148 wholeSubtree, the Search continues in the subtree(s) of any
1149 dereferenced object. If the search scope is singleLevel, the
1150 search is applied to any dereferenced objects, and is not applied
1151 to their subordinates. Servers SHOULD eliminate duplicate entries
1152 that arise due to alias dereferencing while searching.
1154 derefFindingBaseObj: Dereference aliases in locating the base
1155 object of the Search, but not when searching subordinates of the
1158 derefAlways: Dereference aliases both in searching and in locating
1159 the base object of the Search.
1162 4.5.1.4 SearchRequest.sizeLimit
1164 A size limit that restricts the maximum number of entries to be
1165 returned as a result of the Search. A value of zero in this field
1166 indicates that no client-requested size limit restrictions are in
1167 effect for the Search. Servers may also enforce a maximum number of
1171 4.5.1.5 SearchRequest.timeLimit
1173 A time limit that restricts the maximum time (in seconds) allowed for
1174 a Search. A value of zero in this field indicates that no client-
1175 requested time limit restrictions are in effect for the Search.
1176 Servers may also enforce a maximum time limit for the Search.
1178 Sermersheim Internet-Draft - Expires Aug 2005 Page 20
1180 Lightweight Directory Access Protocol Version 3
1184 4.5.1.6 SearchRequest.typesOnly
1186 An indicator as to whether Search results are to contain both
1187 attribute descriptions and values, or just attribute descriptions.
1188 Setting this field to TRUE causes only attribute descriptions (no
1189 values) to be returned. Setting this field to FALSE causes both
1190 attribute descriptions and values to be returned.
1193 4.5.1.7 SearchRequest.filter
1195 A filter that defines the conditions that must be fulfilled in order
1196 for the Search to match a given entry.
1198 The 'and', 'or' and 'not' choices can be used to form combinations of
1199 filters. At least one filter element MUST be present in an 'and' or
1200 'or' choice. The others match against individual attribute values of
1201 entries in the scope of the Search. (Implementor's note: the 'not'
1202 filter is an example of a tagged choice in an implicitly-tagged
1203 module. In BER this is treated as if the tag was explicit.)
1205 A server MUST evaluate filters according to the three-valued logic of
1206 [X.511] (1993) Clause 7.8.1. In summary, a filter is evaluated to
1207 either "TRUE", "FALSE" or "Undefined". If the filter evaluates to
1208 TRUE for a particular entry, then the attributes of that entry are
1209 returned as part of the Search result (subject to any applicable
1210 access control restrictions). If the filter evaluates to FALSE or
1211 Undefined, then the entry is ignored for the Search.
1213 A filter of the "and" choice is TRUE if all the filters in the SET OF
1214 evaluate to TRUE, FALSE if at least one filter is FALSE, and
1215 otherwise Undefined. A filter of the "or" choice is FALSE if all of
1216 the filters in the SET OF evaluate to FALSE, TRUE if at least one
1217 filter is TRUE, and Undefined otherwise. A filter of the 'not' choice
1218 is TRUE if the filter being negated is FALSE, FALSE if it is TRUE,
1219 and Undefined if it is Undefined.
1221 A filter item evaluates to Undefined when the server would not be
1222 able to determine whether the assertion value matches an entry.
1225 - An attribute description in an equalityMatch, substrings,
1226 greaterOrEqual, lessOrEqual, approxMatch or extensibleMatch
1227 filter is not recognized by the server.
1229 - The attribute type does not define the appropriate matching
1232 - A MatchingRuleId in the extensibleMatch is not recognized by
1233 the server or is not valid for the attribute type.
1235 - The type of filtering requested is not implemented.
1237 Sermersheim Internet-Draft - Expires Aug 2005 Page 21
1239 Lightweight Directory Access Protocol Version 3
1242 - The assertion value is invalid.
1244 For example, if a server did not recognize the attribute type
1245 shoeSize, a filter of (shoeSize=*) would evaluate to FALSE, and the
1246 filters (shoeSize=12), (shoeSize>=12) and (shoeSize<=12) would each
1247 evaluate to Undefined.
1249 Servers MUST NOT return errors if attribute descriptions or matching
1250 rule ids are not recognized, assertion values are invalid, or the
1251 assertion syntax is not supported. More details of filter processing
1252 are given in Clause 7.8 of [X.511].
1255 4.5.1.7.1 SearchRequest.filter.equalityMatch
1257 The matching rule for equalityMatch filter items is defined by the
1258 EQUALITY matching rule for the attribute type.
1261 4.5.1.7.2 SearchRequest.filter.substrings
1263 There SHALL be at most one 'initial', and at most one 'final' in the
1264 'substrings' of a SubstringFilter. If 'initial' is present, it SHALL
1265 be the first element of 'substrings'. If 'final' is present, it SHALL
1266 be the last element of 'substrings'.
1268 The matching rule for an AssertionValue in a substrings filter item
1269 is defined by the SUBSTR matching rule for the attribute type. Note
1270 that the AssertionValue in a substrings filter item conforms to the
1271 assertion syntax of the EQUALITY matching rule for the attribute type
1272 rather than the assertion syntax of the SUBSTR matching rule for the
1273 attribute type. Conceptually, the entire SubstringFilter is converted
1274 into an assertion value of the substrings matching rule prior to
1278 4.5.1.7.3 SearchRequest.filter.greaterOrEqual
1280 The matching rule for the greaterOrEqual filter item is defined by
1281 the ORDERING and EQUALITY matching rules for the attribute type.
1284 4.5.1.7.4 SearchRequest.filter.lessOrEqual
1286 The matching rule for the lessOrEqual filter item is defined by the
1287 ORDERING matching rule for the attribute type.
1290 4.5.1.7.5 SearchRequest.filter.present
1292 The present match evaluates to TRUE where there is an attribute or
1293 subtype of the specified attribute description present in an entry,
1296 Sermersheim Internet-Draft - Expires Aug 2005 Page 22
1298 Lightweight Directory Access Protocol Version 3
1300 and FALSE otherwise (including a presence test with an unrecognized
1301 attribute description).
1304 4.5.1.7.6 SearchRequest.filter.approxMatch
1306 An approxMatch filter item evaluates to TRUE when there is a value of
1307 the attribute or subtype for which some locally-defined approximate
1308 matching algorithm (e.g. spelling variations, phonetic match, etc.)
1309 returns TRUE. If an item matches for equality, it also satisfies an
1310 approximate match. If approximate matching is not supported for the
1311 attribute, this filter item should be treated as an equalityMatch.
1314 4.5.1.7.7 SearchRequest.filter.extensibleMatch
1316 The fields of the extensibleMatch filter item are evaluated as
1319 - If the matchingRule field is absent, the type field MUST be
1320 present, and an equality match is performed for that type.
1322 - If the type field is absent and the matchingRule is present, the
1323 matchValue is compared against all attributes in an entry which
1324 support that matchingRule.
1326 - If the type field is present and the matchingRule is present, the
1327 matchValue is compared against entry attributes of the specified
1330 - If the dnAttributes field is set to TRUE, the match is
1331 additionally applied against all the AttributeValueAssertions in
1332 an entry's distinguished name, and evaluates to TRUE if there is
1333 at least one attribute in the distinguished name for which the
1334 filter item evaluates to TRUE. The dnAttributes field is present
1335 to alleviate the need for multiple versions of generic matching
1336 rules (such as word matching), where one applies to entries and
1337 another applies to entries and DN attributes as well.
1339 The matchingRule used for evaluation determines the syntax for the
1340 assertion value. Once the matchingRule and attribute(s) have been
1341 determined, the filter item evaluates to TRUE if it matches with at
1342 least one attribute in the entry, FALSE if it does not match any
1343 attribute in the entry, and Undefined if the matchingRule is not
1344 recognized, the matchingRule is unsuitable for use with the specified
1345 type, or the assertionValue is invalid.
1348 4.5.1.7 SearchRequest.attributes
1350 A selection list of the attributes to be returned from each entry
1351 which matches the search filter. LDAPString values of this field are
1352 constrained to the following Augmented Backus-Naur Form ([ABNF]):
1355 Sermersheim Internet-Draft - Expires Aug 2005 Page 23
1357 Lightweight Directory Access Protocol Version 3
1359 attributeSelector = attributedescription / selectorspecial
1361 selectorspecial = noattrs / alluserattrs
1363 noattrs = %x31.2E.31 ; "1.1"
1365 alluserattrs = %x2A ; asterisk ("*")
1367 The <attributedescription> production is defined in Section 2.5 of
1370 There are three special cases which may appear in the attributes
1373 - an empty list with no attributes,
1375 - a list containing "*" (with zero or more attribute
1378 - a list containing only "1.1".
1380 An empty list requests the return of all user attributes.
1382 A list containing "*" requests the return of all user attributes
1383 in addition to other listed (operational) attributes.
1385 A list containing only the OID "1.1" indicates that no attributes
1386 are to be returned. If "1.1" is provided with other
1387 attributeSelector values, the "1.1" attributeSelector is ignored.
1388 This OID was chosen because it does not (and can not) correspond
1389 to any attribute in use.
1391 Client implementors should note that even if all user attributes are
1392 requested, some attributes and/or attribute values of the entry may
1393 not be included in Search results due to access controls or other
1394 restrictions. Furthermore, servers will not return operational
1395 attributes, such as objectClasses or attributeTypes, unless they are
1396 listed by name. Operational attributes are described in [Models].
1398 Attributes are returned at most once in an entry. If an attribute
1399 description is named more than once in the list, the subsequent names
1400 are ignored. If an attribute description in the list is not
1401 recognized, it is ignored by the server.
1404 4.5.2. Search Result
1406 The results of the Search operation are returned as zero or more
1407 SearchResultEntry and/or SearchResultReference messages, followed by
1408 a single SearchResultDone message.
1410 SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
1412 attributes PartialAttributeList }
1414 Sermersheim Internet-Draft - Expires Aug 2005 Page 24
1416 Lightweight Directory Access Protocol Version 3
1419 PartialAttributeList ::= SEQUENCE OF
1420 partialAttribute PartialAttribute
1422 SearchResultReference ::= [APPLICATION 19] SEQUENCE
1423 SIZE (1..MAX) OF uri URI
1425 SearchResultDone ::= [APPLICATION 5] LDAPResult
1427 Each SearchResultEntry represents an entry found during the Search.
1428 Each SearchResultReference represents an area not yet explored during
1429 the Search. The SearchResultEntry and SearchResultReference PDUs may
1430 come in any order. Following all the SearchResultReference and
1431 SearchResultEntry responses, the server returns a SearchResultDone
1432 response, which contains an indication of success, or detailing any
1433 errors that have occurred.
1435 Each entry returned in a SearchResultEntry will contain all
1436 appropriate attributes as specified in the attributes field of the
1437 Search Request, subject to access control and other administrative
1438 policy. Note that the PartialAttributeList may hold zero elements.
1439 This may happen when none of the attributes of an entry were
1440 requested, or could be returned. Note also that the partialAttribute
1441 vals set may hold zero elements. This may happen when typesOnly is
1442 requested, access controls prevent the return of values, or other
1445 Some attributes may be constructed by the server and appear in a
1446 SearchResultEntry attribute list, although they are not stored
1447 attributes of an entry. Clients SHOULD NOT assume that all attributes
1448 can be modified, even if permitted by access control.
1450 If the server's schema defines short names [Models] for an attribute
1451 type then the server SHOULD use one of those names in attribute
1452 descriptions for that attribute type (in preference to using the
1453 <numericoid> [Models] format of the attribute type's object
1454 identifier). The server SHOULD NOT use the short name if that name is
1455 known by the server to be ambiguous, or otherwise likely to cause
1456 interoperability problems.
1459 4.5.3. Continuation References in the Search Result
1461 If the server was able to locate the entry referred to by the
1462 baseObject but was unable or unwilling to search one or more non-
1463 local entries, the server may return one or more
1464 SearchResultReference messages, each containing a reference to
1465 another set of servers for continuing the operation. A server MUST
1466 NOT return any SearchResultReference messages if it has not located
1467 the baseObject and thus has not searched any entries; in this case it
1468 would return a SearchResultDone containing either a referral or
1469 noSuchObject result code (depending on the server's knowledge of the
1470 entry named in the baseObject).
1473 Sermersheim Internet-Draft - Expires Aug 2005 Page 25
1475 Lightweight Directory Access Protocol Version 3
1477 If a server holds a copy or partial copy of the subordinate naming
1478 context (Section 5 of [Models]), it may use the search filter to
1479 determine whether or not to return a SearchResultReference response.
1480 Otherwise SearchResultReference responses are always returned when in
1483 The SearchResultReference is of the same data type as the Referral.
1485 If the client wishes to progress the Search, it issues a new Search
1486 operation for each SearchResultReference that is returned. If
1487 multiple URIs are present, the client assumes that any supported URI
1488 may be used to progress the operation.
1490 Clients that follow search continuation references MUST ensure that
1491 they do not loop between servers. They MUST NOT repeatedly contact
1492 the same server for the same request with the same parameters. Some
1493 clients use a counter that is incremented each time search result
1494 reference handling occurs for an operation, and these kinds of
1495 clients MUST be able to handle at least ten nested referrals while
1496 progressing the operation.
1498 Note that the Abandon operation described in Section 4.11 applies
1499 only to a particular operation sent at the LDAP message layer between
1500 a client and server. The client must abandon subsequent Search
1501 operations it wishes to individually.
1503 A URI for a server implementing LDAP and accessible via [TCP]/[IP]
1504 (v4 or v6) is written as an LDAP URL according to [LDAPURL].
1506 SearchResultReference values which are LDAP URLs follow these rules:
1508 - The <dn> part of the LDAP URL MUST be present, with the new target
1509 object name. The client uses this name when following the
1512 - Some servers (e.g. participating in distributed indexing) may
1513 provide a different filter in the LDAP URL.
1515 - If the <filter> part of the LDAP URL is present, the client uses
1516 this filter in its next request to progress this Search, and if it
1517 is not present the client uses the same filter as it used for that
1520 - If the originating search scope was singleLevel, the <scope> part
1521 of the LDAP URL will be "base".
1523 - It is RECOMMENDED that the <scope> part be present to avoid
1524 ambiguity. In the absence of a <scope> part, the scope of the
1525 original Search request is assumed.
1527 - Other aspects of the new Search request may be the same as or
1528 different from the Search request which generated the
1529 SearchResultReference.
1532 Sermersheim Internet-Draft - Expires Aug 2005 Page 26
1534 Lightweight Directory Access Protocol Version 3
1536 - The name of an unexplored subtree in a SearchResultReference need
1537 not be subordinate to the base object.
1539 Other kinds of URIs may be returned. The syntax and semantics of such
1540 URIs is left to future specifications. Clients may ignore URIs that
1541 they do not support.
1543 UTF-8 encoded characters appearing in the string representation of a
1544 DN, search filter, or other fields of the referral value may not be
1545 legal for URIs (e.g. spaces) and MUST be escaped using the % method
1552 For example, suppose the contacted server (hosta) holds the entry
1553 <DC=Example,DC=NET> and the entry <CN=Manager,DC=Example,DC=NET>. It
1554 knows that both LDAP servers (hostb) and (hostc) hold
1555 <OU=People,DC=Example,DC=NET> (one is the master and the other server
1556 a shadow), and that LDAP-capable server (hostd) holds the subtree
1557 <OU=Roles,DC=Example,DC=NET>. If a wholeSubtree Search of
1558 <DC=Example,DC=NET> is requested to the contacted server, it may
1559 return the following:
1561 SearchResultEntry for DC=Example,DC=NET
1562 SearchResultEntry for CN=Manager,DC=Example,DC=NET
1563 SearchResultReference {
1564 ldap://hostb/OU=People,DC=Example,DC=NET??sub
1565 ldap://hostc/OU=People,DC=Example,DC=NET??sub }
1566 SearchResultReference {
1567 ldap://hostd/OU=Roles,DC=Example,DC=NET??sub }
1568 SearchResultDone (success)
1570 Client implementors should note that when following a
1571 SearchResultReference, additional SearchResultReference may be
1572 generated. Continuing the example, if the client contacted the server
1573 (hostb) and issued the Search request for the subtree
1574 <OU=People,DC=Example,DC=NET>, the server might respond as follows:
1576 SearchResultEntry for OU=People,DC=Example,DC=NET
1577 SearchResultReference {
1578 ldap://hoste/OU=Managers,OU=People,DC=Example,DC=NET??sub }
1579 SearchResultReference {
1580 ldap://hostf/OU=Consultants,OU=People,DC=Example,DC=NET??sub }
1581 SearchResultDone (success)
1583 Similarly, if a singleLevel Search of <DC=Example,DC=NET> is
1584 requested to the contacted server, it may return the following:
1586 SearchResultEntry for CN=Manager,DC=Example,DC=NET
1587 SearchResultReference {
1588 ldap://hostb/OU=People,DC=Example,DC=NET??base
1589 ldap://hostc/OU=People,DC=Example,DC=NET??base }
1591 Sermersheim Internet-Draft - Expires Aug 2005 Page 27
1593 Lightweight Directory Access Protocol Version 3
1595 SearchResultReference {
1596 ldap://hostd/OU=Roles,DC=Example,DC=NET??base }
1597 SearchResultDone (success)
1599 If the contacted server does not hold the base object for the Search,
1600 but has knowledge of its possible location, then it may return a
1601 referral to the client. In this case, if the client requests a
1602 subtree Search of <DC=Example,DC=ORG> to hosta, the server returns a
1603 SearchResultDone containing a referral.
1605 SearchResultDone (referral) {
1606 ldap://hostg/DC=Example,DC=ORG??sub }
1609 4.6. Modify Operation
1611 The Modify operation allows a client to request that a modification
1612 of an entry be performed on its behalf by a server. The Modify
1613 Request is defined as follows:
1615 ModifyRequest ::= [APPLICATION 6] SEQUENCE {
1617 changes SEQUENCE OF change SEQUENCE {
1618 operation ENUMERATED {
1623 modification PartialAttribute } }
1625 Fields of the Modify Request are:
1627 - object: The value of this field contains the name of the entry to
1628 be modified. The server SHALL NOT perform any alias dereferencing
1629 in determining the object to be modified.
1631 - changes: A list of modifications to be performed on the entry. The
1632 entire list of modifications MUST be performed in the order they
1633 are listed as a single atomic operation. While individual
1634 modifications may violate certain aspects of the directory schema
1635 (such as the object class definition and DIT content rule), the
1636 resulting entry after the entire list of modifications is
1637 performed MUST conform to the requirements of the directory model
1638 and controlling schema [Models].
1640 - operation: Used to specify the type of modification being
1641 performed. Each operation type acts on the following
1642 modification. The values of this field have the following
1643 semantics respectively:
1645 add: add values listed to the modification attribute,
1646 creating the attribute if necessary;
1650 Sermersheim Internet-Draft - Expires Aug 2005 Page 28
1652 Lightweight Directory Access Protocol Version 3
1654 delete: delete values listed from the modification attribute.
1655 If no values are listed, or if all current values of the
1656 attribute are listed, the entire attribute is removed;
1658 replace: replace all existing values of the modification
1659 attribute with the new values listed, creating the attribute
1660 if it did not already exist. A replace with no value will
1661 delete the entire attribute if it exists, and is ignored if
1662 the attribute does not exist.
1664 - modification: A PartialAttribute (which may have an empty SET
1665 of vals) used to hold the attribute type or attribute type and
1666 values being modified.
1668 Upon receipt of a Modify Request, the server attempts to perform the
1669 necessary modifications to the DIT and returns the result in a Modify
1670 Response, defined as follows:
1672 ModifyResponse ::= [APPLICATION 7] LDAPResult
1674 The server will return to the client a single Modify Response
1675 indicating either the successful completion of the DIT modification,
1676 or the reason that the modification failed. Due to the requirement
1677 for atomicity in applying the list of modifications in the Modify
1678 Request, the client may expect that no modifications of the DIT have
1679 been performed if the Modify Response received indicates any sort of
1680 error, and that all requested modifications have been performed if
1681 the Modify Response indicates successful completion of the Modify
1682 operation. Whether the modification was applied or not cannot be
1683 determined by the client if the Modify Response was not received
1684 (e.g. the LDAP session was terminated or the Modify operation was
1687 Servers MUST ensure that entries conform to user and system schema
1688 rules or other data model constraints. The Modify operation cannot be
1689 used to remove from an entry any of its distinguished values, i.e.
1690 those values which form the entry's relative distinguished name. An
1691 attempt to do so will result in the server returning the
1692 notAllowedOnRDN result code. The Modify DN operation described in
1693 Section 4.9 is used to rename an entry.
1695 For attribute types which specify no equality matching, the rules in
1696 Section 2.5.1 of [Models] are followed.
1698 Note that due to the simplifications made in LDAP, there is not a
1699 direct mapping of the changes in an LDAP ModifyRequest onto the
1700 changes of a DAP ModifyEntry operation, and different implementations
1701 of LDAP-DAP gateways may use different means of representing the
1702 change. If successful, the final effect of the operations on the
1703 entry MUST be identical.
1709 Sermersheim Internet-Draft - Expires Aug 2005 Page 29
1711 Lightweight Directory Access Protocol Version 3
1713 The Add operation allows a client to request the addition of an entry
1714 into the Directory. The Add Request is defined as follows:
1716 AddRequest ::= [APPLICATION 8] SEQUENCE {
1718 attributes AttributeList }
1720 AttributeList ::= SEQUENCE OF attribute Attribute
1722 Fields of the Add Request are:
1724 - entry: the name of the entry to be added. The server SHALL NOT
1725 dereference any aliases in locating the entry to be added.
1727 - attributes: the list of attributes that, along with those from the
1728 RDN, make up the content of the entry being added. Clients MAY or
1729 MAY NOT include the RDN attribute(s) in this list. Clients MUST
1730 NOT supply NO-USER-MODIFICATION attributes such as the
1731 createTimestamp or creatorsName attributes, since the server
1732 maintains these automatically.
1734 Servers MUST ensure that entries conform to user and system schema
1735 rules or other data model constraints. For attribute types which
1736 specify no equality matching, the rules in Section 2.5.1 of [Models]
1737 are followed (this applies to the naming attribute in addition to any
1738 multi-valued attributes being added).
1740 The entry named in the entry field of the AddRequest MUST NOT exist
1741 for the AddRequest to succeed. The immediate superior (parent) of an
1742 object or alias entry to be added MUST exist. For example, if the
1743 client attempted to add <CN=JS,DC=Example,DC=NET>, the
1744 <DC=Example,DC=NET> entry did not exist, and the <DC=NET> entry did
1745 exist, then the server would return the noSuchObject result code with
1746 the matchedDN field containing <DC=NET>.
1748 Upon receipt of an Add Request, a server will attempt to add the
1749 requested entry. The result of the Add attempt will be returned to
1750 the client in the Add Response, defined as follows:
1752 AddResponse ::= [APPLICATION 9] LDAPResult
1754 A response of success indicates that the new entry has been added to
1758 4.8. Delete Operation
1760 The Delete operation allows a client to request the removal of an
1761 entry from the Directory. The Delete Request is defined as follows:
1763 DelRequest ::= [APPLICATION 10] LDAPDN
1768 Sermersheim Internet-Draft - Expires Aug 2005 Page 30
1770 Lightweight Directory Access Protocol Version 3
1772 The Delete Request consists of the name of the entry to be deleted.
1773 The server SHALL NOT dereference aliases while resolving the name of
1774 the target entry to be removed.
1776 Only leaf entries (those with no subordinate entries) can be deleted
1777 with this operation.
1779 Upon receipt of a Delete Request, a server will attempt to perform
1780 the entry removal requested and return the result in the Delete
1781 Response defined as follows:
1783 DelResponse ::= [APPLICATION 11] LDAPResult
1786 4.9. Modify DN Operation
1788 The Modify DN operation allows a client to change the Relative
1789 Distinguished Name (RDN) of an entry in the Directory, and/or to move
1790 a subtree of entries to a new location in the Directory. The Modify
1791 DN Request is defined as follows:
1793 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
1795 newrdn RelativeLDAPDN,
1796 deleteoldrdn BOOLEAN,
1797 newSuperior [0] LDAPDN OPTIONAL }
1799 Fields of the Modify DN Request are:
1801 - entry: the name of the entry to be changed. This entry may or may
1802 not have subordinate entries.
1804 - newrdn: the new RDN of the entry. The value of the old RDN is
1805 supplied when moving the entry to a new superior without changing
1806 its RDN. Attribute values of the new RDN not matching any
1807 attribute value of the entry are added to the entry and an
1808 appropriate error is returned if this fails.
1810 - deleteoldrdn: a boolean field that controls whether the old RDN
1811 attribute values are to be retained as attributes of the entry, or
1812 deleted from the entry.
1814 - newSuperior: if present, this is the name of an existing object
1815 entry which becomes the immediate superior (parent) of the
1818 The server SHALL NOT dereference any aliases in locating the objects
1819 named in entry or newSuperior.
1821 Upon receipt of a ModifyDNRequest, a server will attempt to perform
1822 the name change and return the result in the Modify DN Response,
1825 ModifyDNResponse ::= [APPLICATION 13] LDAPResult
1827 Sermersheim Internet-Draft - Expires Aug 2005 Page 31
1829 Lightweight Directory Access Protocol Version 3
1832 For example, if the entry named in the entry field was <cn=John
1833 Smith,c=US>, the newrdn field was <cn=John Cougar Smith>, and the
1834 newSuperior field was absent, then this operation would attempt to
1835 rename the entry to be <cn=John Cougar Smith,c=US>. If there was
1836 already an entry with that name, the operation would fail with the
1837 entryAlreadyExists result code.
1839 Servers MUST ensure that entries conform to user and system schema
1840 rules or other data model constraints. For attribute types which
1841 specify no equality matching, the rules in Section 2.5.1 of [Models]
1842 are followed (this pertains to newrdn and deleteoldrdn).
1844 The object named in newSuperior MUST exist. For example, if the
1845 client attempted to add <CN=JS,DC=Example,DC=NET>, the
1846 <DC=Example,DC=NET> entry did not exist, and the <DC=NET> entry did
1847 exist, then the server would return the noSuchObject result code with
1848 the matchedDN field containing <DC=NET>.
1850 If the deleteoldrdn field is TRUE, the attribute values forming the
1851 old RDN but not the new RDN are deleted from the entry. If the
1852 deleteoldrdn field is FALSE, the attribute values forming the old RDN
1853 will be retained as non-distinguished attribute values of the entry.
1855 Note that X.500 restricts the ModifyDN operation to only affect
1856 entries that are contained within a single server. If the LDAP server
1857 is mapped onto DAP, then this restriction will apply, and the
1858 affectsMultipleDSAs result code will be returned if this error
1859 occurred. In general, clients MUST NOT expect to be able to perform
1860 arbitrary movements of entries and subtrees between servers or
1861 between naming contexts.
1864 4.10. Compare Operation
1866 The Compare operation allows a client to compare an assertion value
1867 with the values of a particular attribute in a particular entry in
1868 the Directory. The Compare Request is defined as follows:
1870 CompareRequest ::= [APPLICATION 14] SEQUENCE {
1872 ava AttributeValueAssertion }
1874 Fields of the Compare Request are:
1876 - entry: the name of the entry to be compared. The server SHALL NOT
1877 dereference any aliases in locating the entry to be compared.
1879 - ava: holds the attribute value assertion to be compared.
1881 Upon receipt of a Compare Request, a server will attempt to perform
1882 the requested comparison and return the result in the Compare
1883 Response, defined as follows:
1886 Sermersheim Internet-Draft - Expires Aug 2005 Page 32
1888 Lightweight Directory Access Protocol Version 3
1890 CompareResponse ::= [APPLICATION 15] LDAPResult
1892 The resultCode is set to compareTrue, compareFalse, or an appropriate
1893 error. compareTrue indicates that the assertion value in the ava
1894 field matches a value of the attribute or subtype according to the
1895 attribute's EQUALITY matching rule. compareFalse indicates that the
1896 assertion value in the ava field and the values of the attribute or
1897 subtype did not match. Other result codes indicate either that the
1898 result of the comparison was Undefined (Section 4.5.1), or that some
1901 Note that some directory systems may establish access controls which
1902 permit the values of certain attributes (such as userPassword) to be
1903 compared but not interrogated by other means.
1906 4.11. Abandon Operation
1908 The function of the Abandon operation is to allow a client to request
1909 that the server abandon an uncompleted operation. The Abandon Request
1910 is defined as follows:
1912 AbandonRequest ::= [APPLICATION 16] MessageID
1914 The MessageID is that of an operation which was requested earlier at
1915 this LDAP message layer. The Abandon request itself has its own
1916 MessageID. This is distinct from the MessageID of the earlier
1917 operation being abandoned.
1919 There is no response defined in the Abandon operation. Upon receipt
1920 of an AbandonRequest, the server MAY abandon the operation identified
1921 by the MessageID. Since the client cannot tell the difference between
1922 a successfully abandoned operation and an uncompleted operation, the
1923 application of the Abandon operation is limited to uses where the
1924 client does not require an indication of its outcome.
1926 Abandon, Bind, Unbind, and StartTLS operations cannot be abandoned.
1928 In the event that a server receives an Abandon Request on a Search
1929 operation in the midst of transmitting responses to the Search, that
1930 server MUST cease transmitting entry responses to the abandoned
1931 request immediately, and MUST NOT send the SearchResultDone. Of
1932 course, the server MUST ensure that only properly encoded LDAPMessage
1933 PDUs are transmitted.
1935 The ability to abandon other (particularly update) operations is at
1936 the discretion of the server.
1938 Clients should not send Abandon requests for the same operation
1939 multiple times, and MUST also be prepared to receive results from
1940 operations it has abandoned (since these may have been in transit
1941 when the Abandon was requested, or are not able to be abandoned).
1945 Sermersheim Internet-Draft - Expires Aug 2005 Page 33
1947 Lightweight Directory Access Protocol Version 3
1949 Servers MUST discard Abandon requests for message IDs they do not
1950 recognize, for operations which cannot be abandoned, and for
1951 operations which have already been abandoned.
1954 4.12. Extended Operation
1956 The Extended operation allows additional operations to be defined for
1957 services not already available in the protocol. For example, to Add
1958 operations to install transport layer security (see Section 4.14).
1960 The Extended operation allows clients to make requests and receive
1961 responses with predefined syntaxes and semantics. These may be
1962 defined in RFCs or be private to particular implementations.
1964 Each Extended operation consists of an Extended request and an
1967 ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
1968 requestName [0] LDAPOID,
1969 requestValue [1] OCTET STRING OPTIONAL }
1971 The requestName is a dotted-decimal representation of the unique
1972 OBJECT IDENTIFIER corresponding to the request. The requestValue is
1973 information in a form defined by that request, encapsulated inside an
1976 The server will respond to this with an LDAPMessage containing an
1979 ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
1980 COMPONENTS OF LDAPResult,
1981 responseName [10] LDAPOID OPTIONAL,
1982 responseValue [11] OCTET STRING OPTIONAL }
1984 The responseName is typically not required to be present as the
1985 syntax and semantics of the response (including the format of the
1986 responseValue) is implicitly known and associated with the request by
1989 If the Extended operation associated with the requestName is not
1990 supported by the server, the server MUST NOT provide a responseName
1991 nor a responseValue and MUST return with resultCode set to
1994 The requestValue and responseValue fields contain any information
1995 associated with the operation. The format of these fields is defined
1996 by the specification of the Extended operation. Implementations MUST
1997 be prepared to handle arbitrary contents of these fields, including
1998 zero bytes. Values that are defined in terms of ASN.1 and BER encoded
1999 according to Section 5.1, also follow the extensibility rules in
2004 Sermersheim Internet-Draft - Expires Aug 2005 Page 34
2006 Lightweight Directory Access Protocol Version 3
2008 Servers list the requestName of Extended Requests they recognize in
2009 the 'supportedExtension' attribute in the root DSE (Section 5.1 of
2012 Extended operations may be specified in other documents. The
2013 specification of an Extended operation consists of:
2015 - the OBJECT IDENTIFIER assigned to the requestName,
2017 - the OBJECT IDENTIFIER (if any) assigned to the responseName (note
2018 that the same OBJECT IDENTIFIER my be used for both the
2019 requestName and responseName),
2021 - the format of the contents of the requestValue and responseValue
2024 - the semantics of the operation.
2027 4.13. IntermediateResponse Message
2029 While the Search operation provides a mechanism to return multiple
2030 response messages for a single Search request, other operations, by
2031 nature, do not provide for multiple response messages.
2033 The IntermediateResponse message provides a general mechanism for
2034 defining single-request/multiple-response operations in LDAP. This
2035 message is intended to be used in conjunction with the Extended
2036 operation to define new single-request/multiple-response operations
2037 or in conjunction with a control when extending existing LDAP
2038 operations in a way that requires them to return Intermediate
2039 response information.
2041 It is intended that the definitions and descriptions of Extended
2042 operations and controls that make use of the IntermediateResponse
2043 message will define the circumstances when an IntermediateResponse
2044 message can be sent by a server and the associated meaning of an
2045 IntermediateResponse message sent in a particular circumstance.
2047 IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
2048 responseName [0] LDAPOID OPTIONAL,
2049 responseValue [1] OCTET STRING OPTIONAL }
2051 IntermediateResponse messages SHALL NOT be returned to the client
2052 unless the client issues a request that specifically solicits their
2053 return. This document defines two forms of solicitation: Extended
2054 operation and request control. IntermediateResponse messages are
2055 specified in documents describing the manner in which they are
2056 solicited (i.e. in the Extended operation or request control
2057 specification that uses them). These specifications include:
2059 - the OBJECT IDENTIFIER (if any) assigned to the responseName,
2061 - the format of the contents of the responseValue (if any), and
2063 Sermersheim Internet-Draft - Expires Aug 2005 Page 35
2065 Lightweight Directory Access Protocol Version 3
2068 - the semantics associated with the IntermediateResponse message.
2070 Extensions that allow the return of multiple types of
2071 IntermediateResponse messages SHALL identify those types using unique
2072 responseName values (note that one of these may specify no value).
2074 Sections 4.13.1 and 4.13.2 describe additional requirements on the
2075 inclusion of responseName and responseValue in IntermediateResponse
2079 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse
2081 A single-request/multiple-response operation may be defined using a
2082 single ExtendedRequest message to solicit zero or more
2083 IntermediateResponse messages of one or more kinds followed by an
2084 ExtendedResponse message.
2087 4.13.2. Usage with LDAP Request Controls
2089 A control's semantics may include the return of zero or more
2090 IntermediateResponse messages prior to returning the final result
2091 code for the operation. One or more kinds of IntermediateResponse
2092 messages may be sent in response to a request control.
2094 All IntermediateResponse messages associated with request controls
2095 SHALL include a responseName. This requirement ensures that the
2096 client can correctly identify the source of IntermediateResponse
2099 - two or more controls using IntermediateResponse messages are
2100 included in a request for any LDAP operation or
2102 - one or more controls using IntermediateResponse messages are
2103 included in a request with an LDAP Extended operation that uses
2104 IntermediateResponse messages.
2107 4.14. StartTLS Operation
2109 The Start Transport Layer Security (StartTLS) operation's purpose is
2110 to initiate installation of a TLS layer. The StartTLS operation is
2111 defined using the Extended operation mechanism described in Section
2115 4.14.1. StartTLS Request
2117 A client requests TLS establishment by transmitting a StartTLS
2118 request PDU to the server. The StartTLS request is defined in terms
2121 Sermersheim Internet-Draft - Expires Aug 2005 Page 36
2123 Lightweight Directory Access Protocol Version 3
2125 of an ExtendedRequest. The requestName is "1.3.6.1.4.1.1466.20037",
2126 and the requestValue field is always absent.
2128 The client MUST NOT send any PDUs at this LDAP message layer
2129 following this request until it receives a StartTLS Extended response
2130 and, in the case of a successful response, completes TLS
2133 Detected sequencing problems (particularly those detailed in Section
2134 3.1.1 of [AuthMeth]) result in the resultCode being set to
2137 If the server does not support TLS (whether by design or by current
2138 configuration), it returns with the resultCode set to protocolError
2139 as described in Section 4.12.
2142 4.14.2. StartTLS Response
2144 When a StartTLS request is made, servers supporting the operation
2145 MUST return a StartTLS response PDU to the requestor. The
2146 responseName, if present, is also "1.3.6.1.4.1.1466.20037". The
2147 responseValue is absent.
2149 If the server is willing and able to negotiate TLS, it returns with
2150 the resultCode set to success. Refer to Section 4 of [AuthMeth] for
2153 If the server is otherwise unwilling or unable to perform this
2154 operation, the server is to return an appropriate result code
2155 indicating the nature of the problem. For example, if the TLS
2156 subsystem is not presently available, the server may indicate so by
2157 returning with the resultCode set to unavailable.
2160 4.14.3. Removal of the TLS Layer
2162 Either the client or server MAY remove the TLS layer and leave the
2163 LDAP message layer intact by sending and receiving a TLS closure
2166 The initiating protocol peer sends the TLS closure alert. If it
2167 wishes to leave the LDAP message layer intact, it then MUST cease to
2168 send further PDUs and MUST ignore any received LDAP PDUs until it
2169 receives a TLS closure alert from the other peer.
2171 Once the initiating protocol peer receives a TLS closure alert from
2172 the other peer it MAY send and receive LDAP PDUs.
2174 When a protocol peer receives the initial TLS closure alert, it may
2175 choose to allow the LDAP message layer to remain intact. In this
2178 Sermersheim Internet-Draft - Expires Aug 2005 Page 37
2180 Lightweight Directory Access Protocol Version 3
2182 case, it MUST immediately transmit a TLS closure alert. Following
2183 this, it MAY send and receive LDAP PDUs.
2185 Protocol peers MAY terminate the LDAP session after sending or
2186 receiving a TLS closure alert.
2188 After the TLS layer has been removed, the server MUST NOT send
2189 responses to any request message received before the TLS closure
2190 alert. Thus, clients wishing to receive responses to messages sent
2191 while the TLS layer is intact MUST wait for those message responses
2192 before sending the TLS closure alert.
2195 5. Protocol Encoding, Connection, and Transfer
2197 This protocol is designed to run over connection-oriented, reliable
2198 transports, where the data stream is divided into octets (8-bit
2199 units), with each octet and each bit being significant.
2201 One underlying service, LDAP over TCP, is defined in Section
2202 5.2. This service is generally applicable to applications providing
2203 or consuming X.500-based directory services on the Internet. This
2204 specification was generally written with the TCP mapping in mind.
2205 Specifications detailing other mappings may encounter various
2208 Implementations of LDAP over TCP MUST implement the mapping as
2209 described in Section 5.2.
2211 This table illustrates the relationship between the different layers
2212 involved in an exchange between two protocol peers:
2214 +----------------------+
2215 | LDAP message layer |
2216 +----------------------+ > LDAP PDUs
2217 +----------------------+ < data
2219 +----------------------+ > SASL-protected data
2220 +----------------------+ < data
2222 Application +----------------------+ > TLS-protected data
2223 ------------+----------------------+ < data
2224 Transport | transport connection |
2225 +----------------------+
2228 5.1. Protocol Encoding
2230 The protocol elements of LDAP SHALL be encoded for exchange using the
2231 Basic Encoding Rules [BER] of [ASN.1] with the following
2234 - Only the definite form of length encoding is used.
2237 Sermersheim Internet-Draft - Expires Aug 2005 Page 38
2239 Lightweight Directory Access Protocol Version 3
2242 - OCTET STRING values are encoded in the primitive form only.
2244 - If the value of a BOOLEAN type is true, the encoding of the value
2245 octet is set to hex "FF".
2247 - If a value of a type is its default value, it is absent. Only some
2248 BOOLEAN and INTEGER types have default values in this protocol
2251 These restrictions are meant to ease the overhead of encoding and
2252 decoding certain elements in BER.
2254 These restrictions do not apply to ASN.1 types encapsulated inside of
2255 OCTET STRING values, such as attribute values, unless otherwise
2259 5.2. Transmission Control Protocol (TCP)
2261 The encoded LDAPMessage PDUs are mapped directly onto the [TCP]
2262 bytestream using the BER-based encoding described in Section 5.1. It
2263 is recommended that server implementations running over the TCP
2264 provide a protocol listener on the Internet Assigned Numbers
2265 Authority (IANA)-assigned LDAP port, 389 [PortReg]. Servers may
2266 instead provide a listener on a different port number. Clients MUST
2267 support contacting servers on any valid TCP port.
2270 5.3. Termination of the LDAP session
2272 Termination of the LDAP session is typically initiated by the client
2273 sending an UnbindRequst (Section 4.3), or by the server sending a
2274 Notice of Disconnection (Section 4.4.1). In these cases each protocol
2275 peer gracefully terminates the LDAP session by ceasing exchanges at
2276 the LDAP message layer, tearing down any SASL layer, tearing down any
2277 TLS layer, and closing the transport connection.
2279 A protocol peer may determine that the continuation of any
2280 communication would be pernicious, and in this case may abruptly
2281 terminate the session by ceasing communication and closing the
2282 transport connection.
2284 In either case, when the LDAP session is terminated, uncompleted
2285 operations are handled as specified in Section 3.1.
2288 6. Security Considerations
2290 This version of the protocol provides facilities for simple
2291 authentication using a cleartext password, as well as any [SASL]
2292 mechanism. Installing SASL and/or TLS layers can provide integrity
2293 and other data security services.
2296 Sermersheim Internet-Draft - Expires Aug 2005 Page 39
2298 Lightweight Directory Access Protocol Version 3
2300 It is also permitted that the server can return its credentials to
2301 the client, if it chooses to do so.
2303 Use of cleartext password is strongly discouraged where the
2304 underlying transport service cannot guarantee confidentiality and may
2305 result in disclosure of the password to unauthorized parties.
2307 Servers are encouraged to prevent directory modifications by clients
2308 that have authenticated anonymously [AuthMeth].
2310 Security considerations for authentication methods, SASL mechanisms,
2311 and TLS are described in [AuthMeth].
2313 It should be noted that SASL authentication exchanges do not provide
2314 data confidentiality nor integrity protection for the version or name
2315 fields of the BindRequest nor the resultCode, diagnosticMessage, or
2316 referral fields of the BindResponse nor of any information contained
2317 in controls attached to Bind requests or responses. Thus information
2318 contained in these fields SHOULD NOT be relied on unless otherwise
2319 protected (such as by establishing protections at the transport
2322 Server implementors should plan for the possibility of (protocol or
2323 external) events which alter the information used to establish
2324 security factors (e.g., credentials, authorization identities, access
2325 controls) during the course of the LDAP session, and even during the
2326 performance of a particular operation, and should take steps to avoid
2327 insecure side effects of these changes. The ways in which these
2328 issues are addressed are application and/or implementation specific.
2330 Implementations which cache attributes and entries obtained via LDAP
2331 MUST ensure that access controls are maintained if that information
2332 is to be provided to multiple clients, since servers may have access
2333 control policies which prevent the return of entries or attributes in
2334 Search results except to particular authenticated clients. For
2335 example, caches could serve result information only to the client
2336 whose request caused it to be in the cache.
2338 Servers may return referrals or Search result references which
2339 redirect clients to peer servers. It is possible for a rogue
2340 application to inject such referrals into the data stream in an
2341 attempt to redirect a client to a rogue server. Clients are advised
2342 to be aware of this, and possibly reject referrals when
2343 confidentiality measures are not in place. Clients are advised to
2344 reject referrals from the StartTLS operation.
2346 The matchedDN and diagnosticMessage fields, as well as some
2347 resultCode values (e.g., attributeOrValueExists and
2348 entryAlreadyExists), could disclose the presence or absence of
2349 specific data in the directory which is subject to access and other
2350 administrative controls. Server implementations should restrict
2351 access to protected information equally under both normal and error
2355 Sermersheim Internet-Draft - Expires Aug 2005 Page 40
2357 Lightweight Directory Access Protocol Version 3
2359 Protocol peers MUST be prepared to handle invalid and arbitrary
2360 length protocol encodings. Invalid protocol encodings include: BER
2361 encoding exceptions, format string and UTF-8 encoding exceptions,
2362 overflow exceptions, integer value exceptions, and binary mode on/off
2363 flag exceptions. The LDAPv3 PROTOS [PROTOS-LDAP] test suite provides
2364 excellent examples of these exceptions and test cases used to
2367 In the event that a protocol peer senses an attack which in its
2368 nature could cause damage due to further communication at any layer
2369 in the LDAP session, the protocol peer should abruptly terminate the
2370 LDAP session as described in Section 5.3.
2375 This document is based on RFC 2251 by Mark Wahl, Tim Howes, and Steve
2376 Kille. RFC 2251 was a product of the IETF ASID Working Group.
2378 It is also based on RFC 2830 by Jeff Hodges, RL "Bob" Morgan, and
2379 Mark Wahl. RFC 2830 was a product of the IETF LDAPEXT Working Group.
2381 It is also based on RFC 3771 by Roger Harrison, and Kurt Zeilenga.
2382 RFC 3771 was an individual submission to the IETF.
2384 This document is a product of the IETF LDAPBIS Working Group.
2385 Significant contributors of technical review and content include Kurt
2386 Zeilenga, Steven Legg, and Hallvard Furuseth.
2389 8. Normative References
2391 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
2392 Specifications: ABNF", RFC 2234, November 1997.
2394 [ASN.1] ITU-T Recommendation X.680 (07/2002) | ISO/IEC 8824-1:2002
2395 "Information Technology - Abstract Syntax Notation One
2396 (ASN.1): Specification of basic notation"
2398 [AuthMeth] Harrison, R., "LDAP: Authentication Methods and Connection
2399 Level Security Mechanisms", draft-ietf-ldapbis-authmeth-
2400 xx.txt, (a work in progress).
2402 [BER] ITU-T Rec. X.690 (07/2002) | ISO/IEC 8825-1:2002,
2403 "Information technology - ASN.1 encoding rules:
2404 Specification of Basic Encoding Rules (BER), Canonical
2405 Encoding Rules (CER) and Distinguished Encoding Rules
2408 [IP] Postel, J., "Internet Protocol", STD5 and RFC 791,
2414 Sermersheim Internet-Draft - Expires Aug 2005 Page 41
2416 Lightweight Directory Access Protocol Version 3
2418 [ISO10646] Universal Multiple-Octet Coded Character Set (UCS) -
2419 Architecture and Basic Multilingual Plane, ISO/IEC 10646-1
2422 [Keyword] Bradner, S., "Key words for use in RFCs to Indicate
2423 Requirement Levels", RFC 2119, March 1997.
2425 [LDAPDN] Zeilenga, K., "LDAP: String Representation of
2426 Distinguished Names", draft-ietf-ldapbis-dn-xx.txt, (a
2429 [LDAPIANA] Zeilenga, K., "IANA Considerations for LDAP", draft-ietf-
2430 ldapbis-bcp64-xx.txt, (a work in progress).
2432 [LDAPURL] Smith, M., "LDAP: Uniform Resource Locator", draft-ietf-
2433 ldapbis-url-xx.txt, (a work in progress).
2435 [Models] Zeilenga, K., "LDAP: Directory Information Models", draft-
2436 ietf-ldapbis-models-xx.txt (a work in progress).
2438 [Roadmap] Zeilenga, K., "LDAP: Technical Specification Road Map",
2439 draft-ietf-ldapbis-roadmap-xx.txt (a work in progress).
2441 [SASL] Melnikov, A., "Simple Authentication and Security Layer",
2442 draft-ietf-sasl-rfc2222bis-xx.txt (a work in progress).
2444 [SASLPrep] Zeilenga, K., "Stringprep profile for user names and
2445 passwords", draft-ietf-sasl-saslprep-xx.txt, (a work in
2448 [StringPrep] Hoffman P. and M. Blanchet, "Preparation of
2449 Internationalized Strings ('stringprep')", draft-hoffman-
2450 rfc3454bis-xx.txt, a work in progress.
2452 [Syntaxes] Legg, S., and K. Dally, "LDAP: Syntaxes and Matching
2453 Rules", draft-ietf-ldapbis-syntaxes-xx.txt, (a work in
2456 [TCP] Postel, J., "Transmission Control Protocol", STD7 and RFC
2459 [TLS] Dierks, T. and C. Allen. "The TLS Protocol Version 1.1",
2460 draft-ietf-tls-rfc2246-bis-xx.txt, a work in progress.
2462 [Unicode] The Unicode Consortium, "The Unicode Standard, Version
2463 3.2.0" is defined by "The Unicode Standard, Version 3.0"
2464 (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5),
2465 as amended by the "Unicode Standard Annex #27: Unicode
2466 3.1" (http://www.unicode.org/reports/tr27/) and by the
2467 "Unicode Standard Annex #28: Unicode 3.2"
2468 (http://www.unicode.org/reports/tr28/).
2473 Sermersheim Internet-Draft - Expires Aug 2005 Page 42
2475 Lightweight Directory Access Protocol Version 3
2477 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
2478 Resource Identifiers (URI): Generic Syntax", RFC 2396,
2481 [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
2482 10646", STD63 and RFC3629, November 2003.
2484 [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts,
2485 Models and Service", 1993.
2487 [X.501] ITU-T Rec. X.501, "The Directory: Models", 1993.
2489 [X.511] ITU-T Rec. X.511, "The Directory: Abstract Service
2493 9. Informative References
2495 [Glossary] The Unicode Consortium, "Unicode Glossary",
2496 <http://www.unicode.org/glossary/>.
2498 [CharModel] Whistler, K. and M. Davis, "Unicode Technical Report
2499 #17, Character Encoding Model", UTR17,
2500 <http://www.unicode.org/unicode/reports/tr17/>, August
2503 [PROTOS-LDAP] University of Oulu, "PROTOS Test-Suite: c06-ldapv3"
2504 <http://www.ee.oulu.fi/research/ouspg/protos/testing/c06/l
2507 [PortReg] IANA, "Port Numbers",
2508 http://www.iana.org/assignments/port-numbers
2511 10. IANA Considerations
2513 It is requested that the Internet Assigned Numbers Authority (IANA)
2514 update the LDAP result code registry to indicate that this document
2515 provides the definitive technical specification for result codes 0-
2516 36, 48-54, 64-70, 80-90.
2518 It is requested that the IANA update the LDAP Protocol Mechanism
2519 registry to indicate that this document and [AuthMeth] provides the
2520 definitive technical specification for the StartTLS
2521 (1.3.6.1.4.1.1466.20037) Extended operation.
2523 It is requested that the IANA update the occurrence of "RFC XXXX" in
2524 Appendix B with this RFC number at publication.
2527 11. Editor's Address
2532 Sermersheim Internet-Draft - Expires Aug 2005 Page 43
2534 Lightweight Directory Access Protocol Version 3
2536 1800 South Novell Place
2537 Provo, Utah 84606, USA
2591 Sermersheim Internet-Draft - Expires Aug 2005 Page 44
2593 Lightweight Directory Access Protocol Version 3
2595 Appendix A - LDAP Result Codes
2597 This normative appendix details additional considerations regarding
2598 LDAP result codes and provides a brief, general description of each
2599 LDAP result code enumerated in Section 4.1.9.
2601 Additional result codes MAY be defined for use with extensions
2602 [LDAPIANA]. Client implementations SHALL treat any result code which
2603 they do not recognize as an unknown error condition.
2605 Servers may substitute some result codes due to access controls which
2606 prevent their disclosure.
2609 A.1 Non-Error Result Codes
2611 These result codes (called "non-error" result codes) do not indicate
2617 saslBindInProgress (14).
2619 The success, compareTrue, and compareFalse result codes indicate
2620 successful completion (and, hence, are referred to as "successful"
2623 The referral and saslBindInProgress result codes indicate the client
2624 needs to take additional action to complete the operation.
2629 Existing LDAP result codes are described as follows:
2632 Indicates the successful completion of an operation. Note:
2633 this code is not used with the Compare operation. See
2634 compareFalse (5) and compareTrue (6).
2637 Indicates that the operation is not properly sequenced with
2638 relation to other operations (of same or different type).
2640 For example, this code is returned if the client attempts to
2641 StartTLS [TLS] while there are other uncompleted operations
2642 or if a TLS layer was already installed.
2645 Indicates the server received data which is not well-formed.
2650 Sermersheim Internet-Draft - Expires Aug 2005 Page 45
2652 Lightweight Directory Access Protocol Version 3
2654 For Bind operation only, this code is also used to indicate
2655 that the server does not support the requested protocol
2658 For Extended operations only, this code is also used to
2659 indicate that the server does not support (by design or
2660 configuration) the Extended operation associated with the
2663 For request operations specifying multiple controls, this may
2664 be used to indicate that the server cannot ignore the order
2665 of the controls as specified, or that the combination of the
2666 specified controls is invalid or unspecified.
2668 timeLimitExceeded (3)
2669 Indicates that the time limit specified by the client was
2670 exceeded before the operation could be completed.
2672 sizeLimitExceeded (4)
2673 Indicates that the size limit specified by the client was
2674 exceeded before the operation could be completed.
2677 Indicates that the Compare operation has successfully
2678 completed and the assertion has evaluated to FALSE or
2682 Indicates that the Compare operation has successfully
2683 completed and the assertion has evaluated to TRUE.
2685 authMethodNotSupported (7)
2686 Indicates that the authentication method or mechanism is not
2689 strongerAuthRequired (8)
2690 Indicates the server requires strong(er) authentication in
2691 order to complete the operation.
2693 When used with the Notice of Disconnection operation, this
2694 code indicates that the server has detected that an
2695 established security association between the client and
2696 server has unexpectedly failed or been compromised.
2699 Indicates that a referral needs to be chased to complete the
2700 operation (see Section 4.1.10).
2702 adminLimitExceeded (11)
2703 Indicates that an administrative limit has been exceeded.
2705 unavailableCriticalExtension (12)
2706 Indicates a critical control is unrecognized (see Section
2709 Sermersheim Internet-Draft - Expires Aug 2005 Page 46
2711 Lightweight Directory Access Protocol Version 3
2714 confidentialityRequired (13)
2715 Indicates that data confidentiality protections are required.
2717 saslBindInProgress (14)
2718 Indicates the server requires the client to send a new bind
2719 request, with the same SASL mechanism, to continue the
2720 authentication process (see Section 4.2).
2722 noSuchAttribute (16)
2723 Indicates that the named entry does not contain the specified
2724 attribute or attribute value.
2726 undefinedAttributeType (17)
2727 Indicates that a request field contains an unrecognized
2728 attribute description.
2730 inappropriateMatching (18)
2731 Indicates that an attempt was made (e.g. in an assertion) to
2732 use a matching rule not defined for the attribute type
2735 constraintViolation (19)
2736 Indicates that the client supplied an attribute value which
2737 does not conform to the constraints placed upon it by the
2740 For example, this code is returned when multiple values are
2741 supplied to an attribute which has a SINGLE-VALUE constraint.
2743 attributeOrValueExists (20)
2744 Indicates that the client supplied an attribute or value to
2745 be added to an entry, but the attribute or value already
2748 invalidAttributeSyntax (21)
2749 Indicates that a purported attribute value does not conform
2750 to the syntax of the attribute.
2753 Indicates that the object does not exist in the DIT.
2756 Indicates that an alias problem has occurred. For example,
2757 the code may used to indicate an alias has been dereferenced
2758 which names no object.
2760 invalidDNSyntax (34)
2761 Indicates that an LDAPDN or RelativeLDAPDN field (e.g. search
2762 base, target entry, ModifyDN newrdn, etc.) of a request does
2763 not conform to the required syntax or contains attribute
2764 values which do not conform to the syntax of the attribute's
2768 Sermersheim Internet-Draft - Expires Aug 2005 Page 47
2770 Lightweight Directory Access Protocol Version 3
2772 aliasDereferencingProblem (36)
2773 Indicates that a problem occurred while dereferencing an
2774 alias. Typically an alias was encountered in a situation
2775 where it was not allowed or where access was denied.
2777 inappropriateAuthentication (48)
2778 Indicates the server requires the client which had attempted
2779 to bind anonymously or without supplying credentials to
2780 provide some form of credentials.
2782 invalidCredentials (49)
2783 Indicates that the provided credentials (e.g. the user's name
2784 and password) are invalid.
2786 insufficientAccessRights (50)
2787 Indicates that the client does not have sufficient access
2788 rights to perform the operation.
2791 Indicates that the server is too busy to service the
2795 Indicates that the server is shutting down or a subsystem
2796 necessary to complete the operation is offline.
2798 unwillingToPerform (53)
2799 Indicates that the server is unwilling to perform the
2803 Indicates that the server has detected an internal loop (e.g.
2804 while dereferencing aliases or chaining an operation).
2806 namingViolation (64)
2807 Indicates that the entry's name violates naming restrictions.
2809 objectClassViolation (65)
2810 Indicates that the entry violates object class restrictions.
2812 notAllowedOnNonLeaf (66)
2813 Indicates that the operation is inappropriately acting upon a
2816 notAllowedOnRDN (67)
2817 Indicates that the operation is inappropriately attempting to
2818 remove a value which forms the entry's relative distinguished
2821 entryAlreadyExists (68)
2822 Indicates that the request cannot be fulfilled (added, moved,
2823 or renamed) as the target entry already exists.
2825 objectClassModsProhibited (69)
2827 Sermersheim Internet-Draft - Expires Aug 2005 Page 48
2829 Lightweight Directory Access Protocol Version 3
2831 Indicates that an attempt to modify the object class(es) of
2832 an entry's 'objectClass' attribute is prohibited.
2834 For example, this code is returned when a client attempts to
2835 modify the structural object class of an entry.
2837 affectsMultipleDSAs (71)
2838 Indicates that the operation cannot be performed as it would
2839 affect multiple servers (DSAs).
2842 Indicates the server has encountered an internal error.
2886 Sermersheim Internet-Draft - Expires Aug 2005 Page 49
2888 Lightweight Directory Access Protocol Version 3
2890 Appendix B - Complete ASN.1 Definition
2892 This appendix is normative.
2894 Lightweight-Directory-Access-Protocol-V3
2895 -- Copyright (C) The Internet Society (2004). This version of
2896 -- this ASN.1 module is part of RFC XXXX; see the RFC itself
2897 -- for full legal notices.
2900 EXTENSIBILITY IMPLIED ::=
2904 LDAPMessage ::= SEQUENCE {
2905 messageID MessageID,
2907 bindRequest BindRequest,
2908 bindResponse BindResponse,
2909 unbindRequest UnbindRequest,
2910 searchRequest SearchRequest,
2911 searchResEntry SearchResultEntry,
2912 searchResDone SearchResultDone,
2913 searchResRef SearchResultReference,
2914 modifyRequest ModifyRequest,
2915 modifyResponse ModifyResponse,
2916 addRequest AddRequest,
2917 addResponse AddResponse,
2918 delRequest DelRequest,
2919 delResponse DelResponse,
2920 modDNRequest ModifyDNRequest,
2921 modDNResponse ModifyDNResponse,
2922 compareRequest CompareRequest,
2923 compareResponse CompareResponse,
2924 abandonRequest AbandonRequest,
2925 extendedReq ExtendedRequest,
2926 extendedResp ExtendedResponse,
2928 intermediateResponse IntermediateResponse },
2929 controls [0] Controls OPTIONAL }
2931 MessageID ::= INTEGER (0 .. maxInt)
2933 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
2935 LDAPString ::= OCTET STRING -- UTF-8 encoded,
2936 -- [ISO10646] characters
2938 LDAPOID ::= OCTET STRING -- Constrained to <numericoid> [Models]
2940 LDAPDN ::= LDAPString -- Constrained to <distinguishedName>
2943 RelativeLDAPDN ::= LDAPString -- Constrained to <name-component>
2945 Sermersheim Internet-Draft - Expires Aug 2005 Page 50
2947 Lightweight Directory Access Protocol Version 3
2951 AttributeDescription ::= LDAPString
2952 -- Constrained to <attributedescription>
2955 AttributeValue ::= OCTET STRING
2957 AttributeValueAssertion ::= SEQUENCE {
2958 attributeDesc AttributeDescription,
2959 assertionValue AssertionValue }
2961 AssertionValue ::= OCTET STRING
2963 PartialAttribute ::= SEQUENCE {
2964 type AttributeDescription,
2965 vals SET OF value AttributeValue }
2967 Attribute ::= PartialAttribute(WITH COMPONENTS {
2969 vals (SIZE(1..MAX))})
2971 MatchingRuleId ::= LDAPString
2973 LDAPResult ::= SEQUENCE {
2974 resultCode ENUMERATED {
2976 operationsError (1),
2978 timeLimitExceeded (3),
2979 sizeLimitExceeded (4),
2982 authMethodNotSupported (7),
2983 strongerAuthRequired (8),
2986 adminLimitExceeded (11),
2987 unavailableCriticalExtension (12),
2988 confidentialityRequired (13),
2989 saslBindInProgress (14),
2990 noSuchAttribute (16),
2991 undefinedAttributeType (17),
2992 inappropriateMatching (18),
2993 constraintViolation (19),
2994 attributeOrValueExists (20),
2995 invalidAttributeSyntax (21),
2999 invalidDNSyntax (34),
3000 -- 35 reserved for undefined isLeaf --
3001 aliasDereferencingProblem (36),
3004 Sermersheim Internet-Draft - Expires Aug 2005 Page 51
3006 Lightweight Directory Access Protocol Version 3
3008 inappropriateAuthentication (48),
3009 invalidCredentials (49),
3010 insufficientAccessRights (50),
3013 unwillingToPerform (53),
3016 namingViolation (64),
3017 objectClassViolation (65),
3018 notAllowedOnNonLeaf (66),
3019 notAllowedOnRDN (67),
3020 entryAlreadyExists (68),
3021 objectClassModsProhibited (69),
3022 -- 70 reserved for CLDAP --
3023 affectsMultipleDSAs (71),
3028 diagnosticMessage LDAPString,
3029 referral [3] Referral OPTIONAL }
3031 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI
3033 URI ::= LDAPString -- limited to characters permitted in
3036 Controls ::= SEQUENCE OF control Control
3038 Control ::= SEQUENCE {
3039 controlType LDAPOID,
3040 criticality BOOLEAN DEFAULT FALSE,
3041 controlValue OCTET STRING OPTIONAL }
3043 BindRequest ::= [APPLICATION 0] SEQUENCE {
3044 version INTEGER (1 .. 127),
3046 authentication AuthenticationChoice }
3048 AuthenticationChoice ::= CHOICE {
3049 simple [0] OCTET STRING,
3051 sasl [3] SaslCredentials,
3054 SaslCredentials ::= SEQUENCE {
3055 mechanism LDAPString,
3056 credentials OCTET STRING OPTIONAL }
3058 BindResponse ::= [APPLICATION 1] SEQUENCE {
3059 COMPONENTS OF LDAPResult,
3060 serverSaslCreds [7] OCTET STRING OPTIONAL }
3063 Sermersheim Internet-Draft - Expires Aug 2005 Page 52
3065 Lightweight Directory Access Protocol Version 3
3067 UnbindRequest ::= [APPLICATION 2] NULL
3069 SearchRequest ::= [APPLICATION 3] SEQUENCE {
3076 derefAliases ENUMERATED {
3077 neverDerefAliases (0),
3078 derefInSearching (1),
3079 derefFindingBaseObj (2),
3081 sizeLimit INTEGER (0 .. maxInt),
3082 timeLimit INTEGER (0 .. maxInt),
3085 attributes AttributeSelection }
3087 AttributeSelection ::= SEQUENCE OF selector LDAPString
3088 -- The LDAPString is constrained to
3089 -- <attributeSelector> in Section 4.5.1.7
3092 and [0] SET SIZE (1..MAX) OF filter Filter,
3093 or [1] SET SIZE (1..MAX) OF filter Filter,
3095 equalityMatch [3] AttributeValueAssertion,
3096 substrings [4] SubstringFilter,
3097 greaterOrEqual [5] AttributeValueAssertion,
3098 lessOrEqual [6] AttributeValueAssertion,
3099 present [7] AttributeDescription,
3100 approxMatch [8] AttributeValueAssertion,
3101 extensibleMatch [9] MatchingRuleAssertion,
3104 SubstringFilter ::= SEQUENCE {
3105 type AttributeDescription,
3106 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE {
3107 initial [0] AssertionValue, -- can occur at most once
3108 any [1] AssertionValue,
3109 final [2] AssertionValue } -- can occur at most once
3112 MatchingRuleAssertion ::= SEQUENCE {
3113 matchingRule [1] MatchingRuleId OPTIONAL,
3114 type [2] AttributeDescription OPTIONAL,
3115 matchValue [3] AssertionValue,
3116 dnAttributes [4] BOOLEAN DEFAULT FALSE }
3118 SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
3120 attributes PartialAttributeList }
3122 Sermersheim Internet-Draft - Expires Aug 2005 Page 53
3124 Lightweight Directory Access Protocol Version 3
3127 PartialAttributeList ::= SEQUENCE OF
3128 partialAttribute PartialAttribute
3130 SearchResultReference ::= [APPLICATION 19] SEQUENCE
3131 SIZE (1..MAX) OF uri URI
3133 SearchResultDone ::= [APPLICATION 5] LDAPResult
3135 ModifyRequest ::= [APPLICATION 6] SEQUENCE {
3137 changes SEQUENCE OF change SEQUENCE {
3138 operation ENUMERATED {
3143 modification PartialAttribute } }
3145 ModifyResponse ::= [APPLICATION 7] LDAPResult
3147 AddRequest ::= [APPLICATION 8] SEQUENCE {
3149 attributes AttributeList }
3151 AttributeList ::= SEQUENCE OF attribute Attribute
3153 AddResponse ::= [APPLICATION 9] LDAPResult
3155 DelRequest ::= [APPLICATION 10] LDAPDN
3157 DelResponse ::= [APPLICATION 11] LDAPResult
3159 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
3161 newrdn RelativeLDAPDN,
3162 deleteoldrdn BOOLEAN,
3163 newSuperior [0] LDAPDN OPTIONAL }
3165 ModifyDNResponse ::= [APPLICATION 13] LDAPResult
3167 CompareRequest ::= [APPLICATION 14] SEQUENCE {
3169 ava AttributeValueAssertion }
3171 CompareResponse ::= [APPLICATION 15] LDAPResult
3173 AbandonRequest ::= [APPLICATION 16] MessageID
3175 ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
3176 requestName [0] LDAPOID,
3177 requestValue [1] OCTET STRING OPTIONAL }
3179 ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
3181 Sermersheim Internet-Draft - Expires Aug 2005 Page 54
3183 Lightweight Directory Access Protocol Version 3
3185 COMPONENTS OF LDAPResult,
3186 responseName [10] LDAPOID OPTIONAL,
3187 responseValue [11] OCTET STRING OPTIONAL }
3189 IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
3190 responseName [0] LDAPOID OPTIONAL,
3191 responseValue [1] OCTET STRING OPTIONAL }
3240 Sermersheim Internet-Draft - Expires Aug 2005 Page 55
3242 Lightweight Directory Access Protocol Version 3
3244 Appendix C - Changes
3246 This appendix is non-normative.
3248 This appendix summarizes substantive changes made to RFC 2251, RFC
3252 C.1 Changes made to RFC 2251:
3254 This section summarizes the substantive changes made to Sections 1,
3255 2, 3.1, and 4 through the remainder of RFC 2251. Readers should
3256 consult [Models] and [AuthMeth] for summaries of changes to other
3260 C.1.1 Section 1 (Status of this Memo)
3262 - Removed IESG note. Post publication of RFC 2251, mandatory LDAP
3263 authentication mechanisms have been standardized which are
3264 sufficient to remove this note. See [AuthMeth] for authentication
3268 C.1.2 Section 3.1 (Protocol Model) and others
3270 - Removed notes giving history between LDAP v1, v2 and v3. Instead,
3271 added sufficient language so that this document can stand on its
3275 C.1.3 Section 4 (Elements of Protocol)
3277 - Clarified where the extensibility features of ASN.1 apply to the
3278 protocol. This change affected various ASN.1 types by the
3279 inclusion of ellipses (...) to certain elements.
3280 - Removed the requirement that servers which implement version 3 or
3281 later MUST provide the 'supportedLDAPVersion' attribute. This
3282 statement provided no interoperability advantages.
3285 C.1.4 Section 4.1.1 (Message Envelope)
3287 - There was a mandatory requirement for the server to return a
3288 Notice of Disconnection and drop the transport connection when a
3289 PDU is malformed in a certain way. This has been updated such that
3290 the server SHOULD return the Notice of Disconnection, and MUST
3291 terminate the LDAP Session.
3294 C.1.5 Section 4.1.1.1 (Message ID)
3296 - Required that the messageID of requests MUST be non-zero as the
3297 zero is reserved for Notice of Disconnection.
3299 Sermersheim Internet-Draft - Expires Aug 2005 Page 56
3301 Lightweight Directory Access Protocol Version 3
3303 - Specified when it is and isn't appropriate to return an already
3304 used message id. RFC 2251 accidentally imposed synchronous server
3305 behavior in its wording of this.
3308 C.1.6 Section 4.1.2 (String Types)
3310 - Stated that LDAPOID is constrained to <numericoid> from [Models].
3313 C.1.7 Section 4.1.5.1 (Binary Option) and others
3315 - Removed the Binary Option from the specification. There are
3316 numerous interoperability problems associated with this method of
3317 alternate attribute type encoding. Work to specify a suitable
3318 replacement is ongoing.
3321 C.1.8 Section 4.1.8 (Attribute)
3323 - Combined the definitions of PartialAttribute and Attribute here,
3324 and defined Attribute in terms of PartialAttribute.
3327 C.1.9 Section 4.1.10 (Result Message)
3329 - Renamed "errorMessage" to "diagnosticMessage" as it is allowed to
3330 be sent for non-error results.
3331 - Moved some language into Appendix A, and refer the reader there.
3332 - Allowed matchedDN to be present for other result codes than those
3334 - renamed the code "strongAuthRequired" to "strongerAuthRequired" to
3335 clarify that this code may often be returned to indicate that a
3336 stronger authentication is needed to perform a given operation.
3339 C.1.10 Section 4.1.11 (Referral)
3341 - Defined referrals in terms of URIs rather than URLs.
3342 - Removed the requirement that all referral URIs MUST be equally
3343 capable of progressing the operation. The statement was ambiguous
3344 and provided no instructions on how to carry it out.
3345 - Added the requirement that clients MUST NOT loop between servers.
3346 - Clarified the instructions for using LDAPURLs in referrals, and in
3347 doing so added a recommendation that the scope part be present.
3348 - Removed imperatives which required clients to use URLs in specific
3349 ways to progress an operation. These did nothing for
3353 C.1.11 Section 4.1.12 (Controls)
3355 - Specified how control values defined in terms of ASN.1 are to be
3358 Sermersheim Internet-Draft - Expires Aug 2005 Page 57
3360 Lightweight Directory Access Protocol Version 3
3362 - Noted that the criticality field is only applied to request
3363 messages (except UnbindRequest), and must be ignored when present
3364 on response messages and UnbindRequest.
3365 - Added language regarding combinations of controls and the ordering
3366 of controls on a message.
3367 - Specified that when the semantics of the combination of controls
3368 is undefined or unknown, it results in a protocolError.
3369 - Changed "The server MUST be prepared" to "Implementations MUST be
3370 prepared" in the eighth paragraph to reflect that both client and
3371 server implementations must be able to handle this (as both parse
3375 C.1.12 Section 4.2 (Bind Operation)
3377 - Mandated that servers return protocolError when the version is not
3379 - Disambiguated behavior when the simple authentication is used, the
3380 name is empty and the password is non-empty.
3381 - Required servers to not dereference aliases for Bind. This was
3382 added for consistency with other operations and to help ensure
3384 - Required that textual passwords be transferred as UTF-8 encoded
3385 Unicode, and added recommendations on string preparation. This was
3386 to help ensure interoperability of passwords being sent from
3390 C.1.13 Section 4.2.1 (Sequencing of the Bind Request)
3392 - This section was largely reorganized for readability and language
3393 was added to clarify the authentication state of failed and
3394 abandoned Bind operations.
3395 - Removed: "If a SASL transfer encryption or integrity mechanism has
3396 been negotiated, that mechanism does not support the changing of
3397 credentials from one identity to another, then the client MUST
3398 instead establish a new connection."
3399 If there are dependencies between multiple negotiations of a
3400 particular SASL mechanism, the technical specification for that
3401 SASL mechanism details how applications are to deal with them.
3402 LDAP should not require any special handling.
3403 - Dropped MUST imperative in paragraph 3 to align with [Keywords].
3404 - Mandated that clients not send non-Bind operations while a Bind is
3405 in progress, and suggested that servers not process them if they
3406 are received. This is needed to ensure proper sequencing of the
3407 Bind in relationship to other operations.
3410 C.1.14 Section 4.2.3 (Bind Response)
3412 - Moved most error-related text to Appendix A, and added text
3413 regarding certain errors used in conjunction with the Bind
3417 Sermersheim Internet-Draft - Expires Aug 2005 Page 58
3419 Lightweight Directory Access Protocol Version 3
3421 - Prohibited the server from specifying serverSaslCreds when not
3425 C.1.15 Section 4.3 (Unbind Operation)
3427 - Specified that both peers are to cease transmission and terminate
3428 the LDAP session for the Unbind operation.
3431 C.1.16 Section 4.4 (Unsolicited Notification)
3433 - Added instructions for future specifications of Unsolicited
3437 C.1.17 Section 4.5.1 (Search Request)
3439 - SearchRequest attributes is now defined as an AttributeSelection
3440 type rather than AttributeDescriptionList, and an ABNF is
3442 - SearchRequest attributes may contain duplicate attribute
3443 descriptions. This was previously prohibited. Now servers are
3444 instructed to ignore subsequent names when they are duplicated.
3445 This was relaxed in order to allow different short names and also
3446 OIDs to be requested for an attribute.
3447 - The Filter choice SubstringFilter substrings type is now defined
3448 with a lower bound of 1.
3449 - The SubstringFilter substrings 'initial, 'any', and 'final' types
3450 are now AssertionValue rather than LDAPString. Also, added
3451 imperatives stating that 'initial' (if present) must be listed
3452 first, and 'final' (if present) must be listed last.
3453 - Disambiguated the semantics of the derefAliases choices. There was
3454 question as to whether derefInSearching applied to the base object
3455 in a wholeSubtree Search.
3456 - Added instructions for equalityMatch, substrings, greaterOrEqual,
3457 lessOrEqual, and approxMatch.
3460 C.1.18 Section 4.5.2 (Search Result)
3462 - Recommended that servers not use attribute short names when it
3463 knows they are ambiguous or may cause interoperability problems.
3464 - Removed all mention of ExtendedResponse due to lack of
3468 C.1.19 Section 4.5.3 (Continuation References in the Search Result)
3470 - Made changes similar to those made to Section 4.1.11.
3473 C.1.20 Section 4.5.3.1 (Example)
3476 Sermersheim Internet-Draft - Expires Aug 2005 Page 59
3478 Lightweight Directory Access Protocol Version 3
3480 - Fixed examples to adhere to changes made to Section 4.5.3.
3483 C.1.21 Section 4.6 (Modify Operation)
3485 - Replaced AttributeTypeAndValues with Attribute as they are
3487 - Specified the types of modification changes which might
3488 temporarily violate schema. Some readers were under the impression
3489 that any temporary schema violation was allowed.
3492 C.1.22 Section 4.7 (Add Operation)
3494 - Aligned Add operation with X.511 in that the attributes of the RDN
3495 are used in conjunction with the listed attributes to create the
3496 entry. Previously, Add required that the distinguished values be
3497 present in the listed attributes.
3498 - Removed requirement that the objectClass attribute MUST be
3499 specified as some DSE types do not require this attribute.
3500 Instead, generic wording was added, requiring the added entry to
3501 adhere to the data model.
3502 - Removed recommendation regarding placement of objects. This is
3503 covered in the data model document.
3506 C.1.23 Section 4.9 (Modify DN Operation)
3508 - Required servers to not dereference aliases for Modify DN. This
3509 was added for consistency with other operations and to help ensure
3511 - Allow Modify DN to fail when moving between naming contexts.
3512 - Specified what happens when the attributes of the newrdn are not
3513 present on the entry.
3516 C.1.24 Section 4.10 (Compare Operation)
3518 - Specified that compareFalse means that the Compare took place and
3519 the result is false. There was confusion which lead people to
3520 believe that an Undefined match resulted in compareFalse.
3521 - Required servers to not dereference aliases for Compare. This was
3522 added for consistency with other operations and to help ensure
3526 C.1.25 Section 4.11 (Abandon Operation)
3528 - Explained that since Abandon returns no response, clients should
3529 not use it if they need to know the outcome.
3530 - Specified that Abandon and Unbind cannot be abandoned.
3533 C.1.26 Section 4.12 (Extended Operation)
3535 Sermersheim Internet-Draft - Expires Aug 2005 Page 60
3537 Lightweight Directory Access Protocol Version 3
3540 - Specified how values of Extended operations defined in terms of
3541 ASN.1 are to be encoded.
3542 - Added instructions on what Extended operation specifications
3544 - Added a recommendation that servers advertise supported Extended
3548 C.1.27 Section 5.2 (Transfer Protocols)
3550 - Moved referral-specific instructions into referral-related
3554 C.1.28 Section 7 (Security Considerations)
3556 - Reworded notes regarding SASL not protecting certain aspects of
3558 - Noted that Servers are encouraged to prevent directory
3559 modifications by clients that have authenticated anonymously
3561 - Added a note regarding the scenario where an identity is changed
3562 (deleted, privileges or credentials modified, etc.).
3563 - Warned against following referrals that may have been injected in
3565 - Noted that servers should protect information equally, whether in
3566 an error condition or not, and mentioned specifically; matchedDN,
3567 diagnosticMessage, and resultCodes.
3568 - Added a note regarding malformed and long encodings.
3571 C.1.29 Appendix A (Complete ASN.1 Definition)
3573 - Added "EXTENSIBILITY IMPLIED" to ASN.1 definition.
3574 - Removed AttributeType. It is not used.
3577 C.2 Changes made to RFC 2830:
3579 This section summarizes the substantive changes made to Sections of
3580 RFC 2830. Readers should consult [AuthMeth] for summaries of changes
3584 C.2.1 Section 2.3 (Response other than "success")
3586 - Removed wording indicating that referrals can be returned from
3588 - Removed requirement that only a narrow set of result codes can be
3589 returned. Some result codes are required in certain scenarios, but
3590 any other may be returned if appropriate.
3594 Sermersheim Internet-Draft - Expires Aug 2005 Page 61
3596 Lightweight Directory Access Protocol Version 3
3598 C.2.1 Section 4 (Closing a TLS Connection)
3600 - Reworded most of this section and added the requirement that after
3601 the TLS connection has been closed, the server MUST NOT send
3602 responses to any request message received before the TLS closure.
3603 - Removed instructions on abrupt closure as this is covered in other
3604 areas of the document (specifically, Section 5.3)
3607 C.3 Changes made to RFC 3771:
3609 - Rewrote to fit into this document. In general, semantics were
3610 preserved. Supporting and background language seen as redundant
3611 due to its presence in this document was omitted.
3612 - Specified that Intermediate responses to a request may be of
3613 different types, and one of the response types may be specified to
3614 have no response value.
3653 Sermersheim Internet-Draft - Expires Aug 2005 Page 62
3655 Lightweight Directory Access Protocol Version 3
3660 Intellectual Property Statement
3662 The IETF takes no position regarding the validity or scope of any
3663 Intellectual Property Rights or other rights that might be claimed to
3664 pertain to the implementation or use of the technology described in
3665 this document or the extent to which any license under such rights
3666 might or might not be available; nor does it represent that it has
3667 made any independent effort to identify any such rights. Information
3668 on the procedures with respect to rights in RFC documents can be
3669 found in BCP 78 and BCP 79.
3671 Copies of IPR disclosures made to the IETF Secretariat and any
3672 assurances of licenses to be made available, or the result of an
3673 attempt made to obtain a general license or permission for the use of
3674 such proprietary rights by implementers or users of this
3675 specification can be obtained from the IETF on-line IPR repository at
3676 <http://www.ietf.org/ipr>.
3678 The IETF invites any interested party to bring to its attention any
3679 copyrights, patents or patent applications, or other proprietary
3680 rights that may cover technology that may be required to implement
3681 this standard. Please address the information to the IETF at ietf-
3684 Disclaimer of Validity
3686 This document and the information contained herein are provided on an
3687 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
3688 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
3689 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
3690 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
3691 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
3692 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
3696 Copyright (C) The Internet Society (2004). This document is subject
3697 to the rights, licenses and restrictions contained in BCP 78, and
3698 except as set forth therein, the authors retain all their rights.
3702 Funding for the RFC Editor function is currently provided by the
3712 Sermersheim Internet-Draft - Expires Aug 2005 Page 63
projects / openldap / blob