1 Internet-Draft Editor: J. Sermersheim
2 Intended Category: Standard Track Novell, Inc
3 Document: draft-ietf-ldapbis-protocol-27.txt Oct 2004
4 Obsoletes: RFCs 2251, 2830, 3771
12 This document is an Internet-Draft and is subject to all provisions
13 of section 3 of RFC 3667. By submitting this Internet-Draft, each
14 author represents that any applicable patent or other IPR claims of
15 which he or she is aware have been or will be disclosed, and any of
16 which he or she become aware will be disclosed, in accordance with
19 Internet-Drafts are working documents of the Internet Engineering
20 Task Force (IETF), its areas, and its working groups. Note that other
21 groups may also distribute working documents as Internet-Drafts.
23 Internet-Drafts are draft documents valid for a maximum of six months
24 and may be updated, replaced, or obsoleted by other documents at any
25 time. It is inappropriate to use Internet-Drafts as reference
26 material or to cite them other than as "work in progress".
28 The list of current Internet-Drafts can be accessed at
29 <http://www.ietf.org/ietf/1id-abstracts.txt>.
31 The list of Internet-Draft Shadow Directories can be accessed at
32 <http://www.ietf.org/shadow.html>.
34 This Internet-Draft will expire in February 2005.
36 Technical discussion of this document will take place on the IETF
37 LDAP Revision Working Group (LDAPbis) mailing list <ietf-
38 ldapbis@openldap.org>. Please send editorial comments directly to the
39 editor <jimse@novell.com>.
44 Copyright (C) The Internet Society 2004. All Rights Reserved.
48 This document describes the protocol elements, along with their
49 semantics and encodings, of the Lightweight Directory Access Protocol
50 (LDAP). LDAP provides access to distributed directory services that
51 act in accordance with X.500 data and service models. These protocol
52 elements are based on those described in the X.500 Directory Access
56 Sermersheim Internet-Draft - Expires Apr 2005 Page 1
57 Lightweight Directory Access Protocol Version 3
62 1. Introduction....................................................3
63 1.1. Relationship to Obsolete Specifications.......................3
64 2. Conventions.....................................................3
65 3. Protocol Model..................................................4
66 3.1 Operation and LDAP Exchange Relationship.......................4
67 4. Elements of Protocol............................................5
68 4.1. Common Elements...............................................5
69 4.1.1. Message Envelope............................................5
70 4.1.2. String Types................................................7
71 4.1.3. Distinguished Name and Relative Distinguished Name..........7
72 4.1.4. Attribute Descriptions......................................7
73 4.1.5. Attribute Value.............................................8
74 4.1.6. Attribute Value Assertion...................................8
75 4.1.7. Attribute and PartialAttribute..............................9
76 4.1.8. Matching Rule Identifier....................................9
77 4.1.9. Result Message..............................................9
78 4.1.10. Referral..................................................11
79 4.1.11. Controls..................................................12
80 4.2. Bind Operation...............................................14
81 4.3. Unbind Operation.............................................17
82 4.4. Unsolicited Notification.....................................17
83 4.5. Search Operation.............................................18
84 4.6. Modify Operation.............................................27
85 4.7. Add Operation................................................28
86 4.8. Delete Operation.............................................29
87 4.9. Modify DN Operation..........................................30
88 4.10. Compare Operation...........................................31
89 4.11. Abandon Operation...........................................32
90 4.12. Extended Operation..........................................32
91 4.13. IntermediateResponse Message................................34
92 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse......34
93 4.13.2. Usage with LDAP Request Controls..........................35
94 4.14. StartTLS Operation..........................................35
95 5. Protocol Encoding, Connection, and Transfer....................37
96 5.2. Protocol Encoding............................................37
97 5.3. Transmission Control Protocol (TCP)..........................38
98 6. Security Considerations........................................38
99 7. Acknowledgements...............................................39
100 8. Normative References...........................................40
101 9. Informative References.........................................41
102 10. IANA Considerations...........................................42
103 11. Editor's Address..............................................42
104 Appendix A - LDAP Result Codes....................................43
105 A.1 Non-Error Result Codes........................................43
106 A.2 Result Codes..................................................43
107 Appendix B - Complete ASN.1 Definition............................48
108 Appendix C - Changes..............................................54
109 C.1 Changes made to RFC 2251:.....................................54
110 C.2 Changes made to RFC 2830:.....................................59
111 C.3 Changes made to RFC 3771:.....................................59
114 Sermersheim Internet-Draft - Expires Apr 2005 Page 2
115 Lightweight Directory Access Protocol Version 3
120 The Directory is "a collection of open systems cooperating to provide
121 directory services" [X.500]. A directory user, which may be a human
122 or other entity, accesses the Directory through a client (or
123 Directory User Agent (DUA)). The client, on behalf of the directory
124 user, interacts with one or more servers (or Directory System Agents
125 (DSA)). Clients interact with servers using a directory access
128 This document details the protocol elements of the Lightweight
129 Directory Access Protocol (LDAP), along with their semantics.
130 Following the description of protocol elements, it describes the way
131 in which the protocol elements are encoded and transferred.
134 1.1. Relationship to Obsolete Specifications
136 This document is an integral part of the LDAP Technical Specification
137 [Roadmap] which obsoletes the previously defined LDAP technical
138 specification, RFC 3377, in its entirety.
140 This document obsoletes all of RFC 2251 except the following:
141 Sections 3.2, 3.4, 4.1.3 (last paragraph), 4.1.4, 4.1.5, 4.1.5.1,
142 4.1.9 (last paragraph), 5.1, 6.1, and 6.2 (last paragraph) are
143 obsoleted by [Models].
144 Section 3.3 is obsoleted by [Roadmap].
145 Sections 4.2.1 (portions), and 4.2.2 are obsoleted by [AuthMeth].
147 Appendix C.1 summarizes substantive changes to the remaining
150 This document obsoletes RFC 2830, Sections 2 and 4 in entirety. The
151 remainder of RFC 2830 is obsoleted by [AuthMeth]. Appendix C.2
152 summarizes substantive changes to the remaining sections.
154 This document also obsoletes RFC 3771 in entirety.
159 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
160 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
161 to be interpreted as described in [Keyword].
163 Character names in this document use the notation for code points and
164 names from the Unicode Standard [Unicode]. For example, the letter
165 "a" may be represented as either <U+0061> or <LATIN SMALL LETTER A>.
167 Note: a glossary of terms used in Unicode can be found in [Glossary].
168 Information on the Unicode character encoding model can be found in
172 Sermersheim Internet-Draft - Expires Apr 2005 Page 3
173 Lightweight Directory Access Protocol Version 3
175 The term "connection" refers to the underlying transport service used
176 to carry the protocol exchange.
178 The term "LDAP exchange" refers to the layer where LDAP PDUs are
179 exchanged between protocol peers.
181 The term "TLS layer" refers to a layer inserted between the
182 connection and the LDAP exchange that utilizes Transport Layer
183 Security ([TLS]) to protect the exchange of LDAP PDUs.
185 The term "SASL layer" refers to a layer inserted between the
186 connection and the LDAP exchange that utilizes Simple Authentication
187 and Security Layer ([SASL]) to protect the exchange of LDAP PDUs.
189 See the table in Section 5 for an illustration of these four terms.
194 The general model adopted by this protocol is one of clients
195 performing protocol operations against servers. In this model, a
196 client transmits a protocol request describing the operation to be
197 performed to a server. The server is then responsible for performing
198 the necessary operation(s) in the Directory. Upon completion of an
199 operation, the server typically returns a response containing
200 appropriate data to the requesting client.
202 Protocol operations are generally independent of one another. Each
203 operation is processed as an atomic action, leaving the directory in
206 Although servers are required to return responses whenever such
207 responses are defined in the protocol, there is no requirement for
208 synchronous behavior on the part of either clients or servers.
209 Requests and responses for multiple operations generally may be
210 exchanged between a client and server in any order. If required,
211 synchronous behavior may be controlled by client applications.
213 The core protocol operations defined in this document can be mapped
214 to a subset of the X.500 (1993) Directory Abstract Service [X.511].
215 However there is not a one-to-one mapping between LDAP operations and
216 X.500 Directory Access Protocol (DAP) operations. Server
217 implementations acting as a gateway to X.500 directories may need to
218 make multiple DAP requests to service a single LDAP request.
221 3.1 Operation and LDAP Exchange Relationship
223 Protocol operations are tied to an LDAP exchange. When the connection
224 is closed, any uncompleted operations tied to the LDAP exchange are,
225 when possible, abandoned, and when not possible, completed without
226 transmission of the response. Also, when the connection is closed,
227 the client MUST NOT assume that any uncompleted update operations
228 tied to the LDAP exchange have succeeded or failed.
230 Sermersheim Internet-Draft - Expires Apr 2005 Page 4
231 Lightweight Directory Access Protocol Version 3
235 4. Elements of Protocol
237 The protocol is described using Abstract Syntax Notation One
238 ([ASN.1]), and is transferred using a subset of ASN.1 Basic Encoding
239 Rules ([BER]). Section 5 specifies how the protocol elements are
240 encoded and transferred.
242 In order to support future extensions to this protocol, extensibility
243 is implied where it is allowed per ASN.1 (i.e. sequence, set, choice,
244 and enumerated types are extensible). In addition, ellipses (...)
245 have been supplied in ASN.1 types that are explicitly extensible as
246 discussed in [LDAPIANA]. Because of the implied extensibility,
247 clients and servers MUST (unless otherwise specified) ignore trailing
248 SEQUENCE components whose tags they do not recognize.
250 Changes to the protocol other than through the extension mechanisms
251 described here require a different version number. A client indicates
252 the version it is using as part of the bind request, described in
253 Section 4.2. If a client has not sent a bind, the server MUST assume
254 the client is using version 3 or later.
256 Clients may determine the protocol versions a server supports by
257 reading the 'supportedLDAPVersion' attribute from the root DSE (DSA-
258 Specific Entry) [Models].
263 This section describes the LDAPMessage envelope Protocol Data Unit
264 (PDU) format, as well as data type definitions, which are used in the
268 4.1.1. Message Envelope
270 For the purposes of protocol exchanges, all protocol operations are
271 encapsulated in a common envelope, the LDAPMessage, which is defined
274 LDAPMessage ::= SEQUENCE {
277 bindRequest BindRequest,
278 bindResponse BindResponse,
279 unbindRequest UnbindRequest,
280 searchRequest SearchRequest,
281 searchResEntry SearchResultEntry,
282 searchResDone SearchResultDone,
283 searchResRef SearchResultReference,
284 modifyRequest ModifyRequest,
285 modifyResponse ModifyResponse,
286 addRequest AddRequest,
288 Sermersheim Internet-Draft - Expires Apr 2005 Page 5
289 Lightweight Directory Access Protocol Version 3
291 addResponse AddResponse,
292 delRequest DelRequest,
293 delResponse DelResponse,
294 modDNRequest ModifyDNRequest,
295 modDNResponse ModifyDNResponse,
296 compareRequest CompareRequest,
297 compareResponse CompareResponse,
298 abandonRequest AbandonRequest,
299 extendedReq ExtendedRequest,
300 extendedResp ExtendedResponse,
302 intermediateResponse IntermediateResponse },
303 controls [0] Controls OPTIONAL }
305 MessageID ::= INTEGER (0 .. maxInt)
307 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
309 The ASN.1 type Controls is defined in Section 4.1.11.
311 The function of the LDAPMessage is to provide an envelope containing
312 common fields required in all protocol exchanges. At this time the
313 only common fields are the messageID and the controls.
315 If the server receives a PDU from the client in which the LDAPMessage
316 SEQUENCE tag cannot be recognized, the messageID cannot be parsed,
317 the tag of the protocolOp is not recognized as a request, or the
318 encoding structures or lengths of data fields are found to be
319 incorrect, then the server SHOULD return the Notice of Disconnection
320 described in Section 4.4.1, with the resultCode set to protocolError,
321 and MUST immediately close the connection.
323 In other cases where the client or server cannot parse a PDU, it
324 SHOULD abruptly close the connection where further communication
325 (including providing notice) would be pernicious. Otherwise, server
326 implementations MUST return an appropriate response to the request,
327 with the resultCode set to protocolError.
332 All LDAPMessage envelopes encapsulating responses contain the
333 messageID value of the corresponding request LDAPMessage.
335 The message ID of a request MUST have a non-zero value different from
336 the the messageID of any other uncompleted requests in the LDAP
337 exchange. The zero value is reserved for the unsolicited notification
340 Typical clients increment a counter for each request.
342 A client MUST NOT send a request with the same message ID as an
343 earlier request in the same LDAP exchange unless it can be determined
344 that the server is no longer servicing the earlier request (e.g.
346 Sermersheim Internet-Draft - Expires Apr 2005 Page 6
347 Lightweight Directory Access Protocol Version 3
349 after the final response is received, or a subsequent bind
350 completes). Otherwise the behavior is undefined. For this purpose,
351 note that abandon and abandoned operations do not send responses.
356 The LDAPString is a notational convenience to indicate that, although
357 strings of LDAPString type encode as ASN.1 OCTET STRING types, the
358 [ISO10646] character set (a superset of [Unicode]) is used, encoded
359 following the [UTF-8] algorithm. Note that Unicode characters U+0000
360 through U+007F are the same as ASCII 0 through 127, respectively, and
361 have the same single octet UTF-8 encoding. Other Unicode characters
362 have a multiple octet UTF-8 encoding.
364 LDAPString ::= OCTET STRING -- UTF-8 encoded,
365 -- [ISO10646] characters
367 The LDAPOID is a notational convenience to indicate that the
368 permitted value of this string is a (UTF-8 encoded) dotted-decimal
369 representation of an OBJECT IDENTIFIER. Although an LDAPOID is
370 encoded as an OCTET STRING, values are limited to the definition of
371 <numericoid> given in Section 1.4 of [Models].
373 LDAPOID ::= OCTET STRING -- Constrained to <numericoid> [Models]
377 1.3.6.1.4.1.1466.1.2.3
380 4.1.3. Distinguished Name and Relative Distinguished Name
382 An LDAPDN is defined to be the representation of a Distinguished Name
383 (DN) after encoding according to the specification in [LDAPDN].
385 LDAPDN ::= LDAPString
386 -- Constrained to <distinguishedName> [LDAPDN]
388 A RelativeLDAPDN is defined to be the representation of a Relative
389 Distinguished Name (RDN) after encoding according to the
390 specification in [LDAPDN].
392 RelativeLDAPDN ::= LDAPString
393 -- Constrained to <name-component> [LDAPDN]
396 4.1.4. Attribute Descriptions
398 The definition and encoding rules for attribute descriptions are
399 defined in Section 2.5 of [Models]. Briefly, an attribute description
400 is an attribute type and zero or more options.
402 AttributeDescription ::= LDAPString
404 Sermersheim Internet-Draft - Expires Apr 2005 Page 7
405 Lightweight Directory Access Protocol Version 3
407 -- Constrained to <attributedescription>
411 4.1.5. Attribute Value
413 A field of type AttributeValue is an OCTET STRING containing an
414 encoded attribute value. The attribute value is encoded according to
415 the LDAP-specific encoding definition of its corresponding syntax.
416 The LDAP-specific encoding definitions for different syntaxes and
417 attribute types may be found in other documents and in particular
420 AttributeValue ::= OCTET STRING
422 Note that there is no defined limit on the size of this encoding;
423 thus protocol values may include multi-megabyte attribute values
426 Attribute values may be defined which have arbitrary and non-
427 printable syntax. Implementations MUST NOT display nor attempt to
428 decode an attribute value if its syntax is not known. The
429 implementation may attempt to discover the subschema of the source
430 entry, and retrieve the descriptions of 'attributeTypes' from it
433 Clients MUST only send attribute values in a request that are valid
434 according to the syntax defined for the attributes.
437 4.1.6. Attribute Value Assertion
439 The AttributeValueAssertion (AVA) type definition is similar to the
440 one in the X.500 Directory standards. It contains an attribute
441 description and a matching rule ([Models Section 4.1.3) assertion
442 value suitable for that type. Elements of this type are typically
443 used to assert that the value in assertionValue matches a value of an
446 AttributeValueAssertion ::= SEQUENCE {
447 attributeDesc AttributeDescription,
448 assertionValue AssertionValue }
450 AssertionValue ::= OCTET STRING
452 The syntax of the AssertionValue depends on the context of the LDAP
453 operation being performed. For example, the syntax of the EQUALITY
454 matching rule for an attribute is used when performing a Compare
455 operation. Often this is the same syntax used for values of the
456 attribute type, but in some cases the assertion syntax differs from
457 the value syntax. See objectIdentiferFirstComponentMatch in
458 [Syntaxes] for an example.
462 Sermersheim Internet-Draft - Expires Apr 2005 Page 8
463 Lightweight Directory Access Protocol Version 3
465 4.1.7. Attribute and PartialAttribute
467 Attributes and partial attributes consist of an attribute description
468 and attribute values. A PartialAttribute allows zero values, while
469 Attribute requires at least one value.
471 PartialAttribute ::= SEQUENCE {
472 type AttributeDescription,
473 vals SET OF value AttributeValue }
475 Attribute ::= PartialAttribute(WITH COMPONENTS {
477 vals (SIZE(1..MAX))})
479 No two attribute values may be equivalent as described by Section 2.3
480 of [Models]. The set of attribute values is unordered.
481 Implementations MUST NOT rely upon the ordering being repeatable.
484 4.1.8. Matching Rule Identifier
486 Matching rules are defined in Section 4.1.3 of [Models]. A matching
487 rule is identified in the protocol by the printable representation of
488 either its <numericoid>, or one of its short name descriptors
489 [Models], e.g. 'caseIgnoreMatch' or '2.5.13.2'.
491 MatchingRuleId ::= LDAPString
494 4.1.9. Result Message
496 The LDAPResult is the construct used in this protocol to return
497 success or failure indications from servers to clients. To various
498 requests, servers will return responses of LDAPResult or responses
499 containing the components of LDAPResult to indicate the final status
500 of a protocol operation request.
502 LDAPResult ::= SEQUENCE {
503 resultCode ENUMERATED {
507 timeLimitExceeded (3),
508 sizeLimitExceeded (4),
511 authMethodNotSupported (7),
512 strongAuthRequired (8),
515 adminLimitExceeded (11),
516 unavailableCriticalExtension (12),
517 confidentialityRequired (13),
518 saslBindInProgress (14),
520 Sermersheim Internet-Draft - Expires Apr 2005 Page 9
521 Lightweight Directory Access Protocol Version 3
523 noSuchAttribute (16),
524 undefinedAttributeType (17),
525 inappropriateMatching (18),
526 constraintViolation (19),
527 attributeOrValueExists (20),
528 invalidAttributeSyntax (21),
532 invalidDNSyntax (34),
533 -- 35 reserved for undefined isLeaf --
534 aliasDereferencingProblem (36),
536 inappropriateAuthentication (48),
537 invalidCredentials (49),
538 insufficientAccessRights (50),
541 unwillingToPerform (53),
544 namingViolation (64),
545 objectClassViolation (65),
546 notAllowedOnNonLeaf (66),
547 notAllowedOnRDN (67),
548 entryAlreadyExists (68),
549 objectClassModsProhibited (69),
550 -- 70 reserved for CLDAP --
551 affectsMultipleDSAs (71),
556 diagnosticMessage LDAPString,
557 referral [3] Referral OPTIONAL }
559 The resultCode enumeration is extensible as defined in Section 3.6 of
560 [LDAPIANA]. The meanings of the listed result codes are given in
561 Appendix A. If a server detects multiple errors for an operation,
562 only one result code is returned. The server should return the result
563 code that best indicates the nature of the error encountered.
565 The diagnosticMessage field of this construct may, at the server's
566 option, be used to return a string containing a textual, human-
567 readable (terminal control and page formatting characters should be
568 avoided) diagnostic message. As this diagnostic message is not
569 standardized, implementations MUST NOT rely on the values returned.
570 If the server chooses not to return a textual diagnostic, the
571 diagnosticMessage field MUST be empty.
573 For certain result codes (typically, but not restricted to
574 noSuchObject, aliasProblem, invalidDNSyntax and
575 aliasDereferencingProblem), the matchedDN field is set (subject to
576 access controls) to the name of the last entry (object or alias) used
578 Sermersheim Internet-Draft - Expires Apr 2005 Page 10
579 Lightweight Directory Access Protocol Version 3
581 in finding the target (or base) object. If no aliases were
582 dereferenced while attempting to locate the entry, this will be a
583 truncated form of the name provided or if aliases were dereferenced,
584 of the resulting name, as defined in Section 12.5 of [X.511].
585 Otherwise the matchedDN field is empty.
590 The referral result code indicates that the contacted server cannot
591 or will not perform the operation and that one or more other servers
592 may be able to. Reasons for this include:
594 - The target entry of the request is not held locally, but the
595 server has knowledge of its possible existence elsewhere.
597 - The operation is restricted on this server -- perhaps due to a
598 read-only copy of an entry to be modified.
600 The referral field is present in an LDAPResult if the resultCode
601 field value is referral, and absent with all other result codes. It
602 contains one or more references to one or more servers or services
603 that may be accessed via LDAP or other protocols. Referrals can be
604 returned in response to any operation request (except unbind and
605 abandon which do not have responses). At least one URI MUST be
606 present in the Referral.
608 During a search operation, after the baseObject is located, and
609 entries are being evaluated, the referral is not returned. Instead,
610 continuation references, described in Section 4.5.3, are returned
611 when other servers would need to be contacted to complete the
614 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI
616 URI ::= LDAPString -- limited to characters permitted in
619 If the client wishes to progress the operation, it MUST follow the
620 referral by contacting one of the supported services. If multiple
621 URIs are present, the client assumes that any supported URI may be
622 used to progress the operation.
624 Protocol peers that follow referrals MUST ensure that they do not
625 loop between servers. They MUST NOT repeatedly contact the same
626 server for the same request with the same target entry name, scope
627 and filter. Some implementations use a counter that is incremented
628 each time referral handling occurs for an operation, and these kinds
629 of implementations MUST be able to handle at least ten nested
630 referrals between the root and a leaf entry.
632 A URI for a server implementing LDAP and accessible via [TCP]/[IP]
633 (v4 or v6) is written as an LDAP URL according to [LDAPURL].
636 Sermersheim Internet-Draft - Expires Apr 2005 Page 11
637 Lightweight Directory Access Protocol Version 3
639 When an LDAP URL is used, the following instructions are followed:
641 - If an alias was dereferenced, the <dn> part of the URL MUST be
642 present, with the new target object name. UTF-8 encoded characters
643 appearing in the string representation of a DN or search filter
644 may not be legal for URLs (e.g. spaces) and MUST be escaped using
645 the % method in [URI].
647 - It is RECOMMENDED that the <dn> part be present to avoid
650 - If the <dn> part is present, the client MUST use this name in its
651 next request to progress the operation, and if it is not present
652 the client will use the same name as in the original request.
654 - Some servers (e.g. participating in distributed indexing) may
655 provide a different filter in a URL of a referral for a search
658 - If the <filter> part of the LDAP URL is present, the client MUST
659 use this filter in its next request to progress this search, and
660 if it is not present the client MUST use the same filter as it
661 used for that search.
663 - For search, it is RECOMMENDED that the <scope> part be present to
666 - If the <scope> part is missing, the scope of the original search
667 is used by the client to progress the operation.
669 - Other aspects of the new request may be the same as or different
670 from the request which generated the referral.
672 Other kinds of URIs may be returned. The syntax and semantics of such
673 URIs is left to future specifications. Clients may ignore URIs that
679 Controls provide a mechanism whereby the semantics and arguments of
680 existing LDAP operations may be extended. One or more controls may be
681 attached to a single LDAP message. A control only affects the
682 semantics of the message it is attached to.
684 Controls sent by clients are termed 'request controls' and those sent
685 by servers are termed 'response controls'.
687 Controls ::= SEQUENCE OF control Control
689 Control ::= SEQUENCE {
691 criticality BOOLEAN DEFAULT FALSE,
692 controlValue OCTET STRING OPTIONAL }
694 Sermersheim Internet-Draft - Expires Apr 2005 Page 12
695 Lightweight Directory Access Protocol Version 3
698 The controlType field is the dotted-decimal representation of an
699 OBJECT IDENTIFIER which uniquely identifies the control. This
700 provides unambiguous naming of controls. Often, response control(s)
701 solicited by a request control share controlType values with the
704 The criticality field only has meaning in controls attached to
705 request messages (except unbindRequest). For controls attached to
706 response messages and the unbindRequest, the criticality field SHOULD
707 be FALSE, and MUST be ignored by the receiving protocol peer. A value
708 of TRUE indicates that it is unacceptable to perform the operation
709 without applying the semantics of the control and FALSE otherwise.
710 Specifically, the criticality field is applied as follows:
712 - Regardless of the value of the criticality field, if the server
713 recognizes the control type and it is appropriate for the
714 operation, the server is to make use of the control when
715 performing the operation.
717 - If the server does not recognize the control type or it is not
718 appropriate for the operation, and the criticality field is TRUE,
719 the server MUST NOT perform the operation, and for operations that
720 have a response message, MUST return unavailableCriticalExtension
723 - If the server does not recognize the control type or it is not
724 appropriate for the operation, and the criticality field is FALSE,
725 the server MUST ignore the control.
727 The controlValue may contain information associated with the
728 controlType. Its format is defined by the specification of the
729 control. Implementations MUST be prepared to handle arbitrary
730 contents of the controlValue octet string, including zero bytes. It
731 is absent only if there is no value information which is associated
732 with a control of its type. When a controlValue is defined in terms
733 of ASN.1, and BER encoded according to Section 5.2, it also follows
734 the extensibility rules in Section 4.
736 Servers list the controlType of request controls they recognize in
737 the 'supportedControl' attribute in the root DSE (Section 5.1 of
740 Controls SHOULD NOT be combined unless the semantics of the
741 combination has been specified. The semantics of control
742 combinations, if specified, are generally found in the control
743 specification most recently published. When a combination of controls
744 is encountered whose semantics are invalid, not specified (or not
745 known), the message is considered to be not well-formed, thus the
746 operation fails with protocolError. Additionally, unless order-
747 dependent semantics are given in a specification, the order of a
748 combination of controls in the SEQUENCE is ignored. Where the order
749 is to be ignored but cannot be ignored by the server, the message is
753 Sermersheim Internet-Draft - Expires Apr 2005 Page 13
754 Lightweight Directory Access Protocol Version 3
756 considered not well-formed and the operation fails with
759 This document does not specify any controls. Controls may be
760 specified in other documents. Documents detailing control extensions
761 are to provide for each control:
763 - the OBJECT IDENTIFIER assigned to the control,
765 - direction as to what value the sender should provide for the
766 criticality field (note: the semantics of the criticality field
767 are defined above should not be altered by the control's
770 - whether information is to be present in the controlValue field,
771 and if so, the format of the controlValue contents,
773 - the semantics of the control, and
775 - optionally, semantics regarding the combination of the control
781 The function of the Bind Operation is to allow authentication
782 information to be exchanged between the client and server. The Bind
783 operation should be thought of as the "authenticate" operation.
784 Operational, authentication, and security-related semantics of this
785 operation are given in [AuthMeth].
787 The Bind Request is defined as follows:
789 BindRequest ::= [APPLICATION 0] SEQUENCE {
790 version INTEGER (1 .. 127),
792 authentication AuthenticationChoice }
794 AuthenticationChoice ::= CHOICE {
795 simple [0] OCTET STRING,
797 sasl [3] SaslCredentials,
800 SaslCredentials ::= SEQUENCE {
801 mechanism LDAPString,
802 credentials OCTET STRING OPTIONAL }
804 Fields of the Bind Request are:
806 - version: A version number indicating the version of the protocol
807 to be used for the LDAP exchange. This document describes version
808 3 of the protocol. There is no version negotiation. The client
809 sets this field to the version it desires. If the server does not
811 Sermersheim Internet-Draft - Expires Apr 2005 Page 14
812 Lightweight Directory Access Protocol Version 3
814 support the specified version, it MUST respond with protocolError
815 in the resultCode field of the BindResponse.
817 - name: If not empty, the name of the Directory object that the
818 client wishes to bind as. This field may take on a null value (a
819 zero length string) for the purposes of anonymous binds
820 ([AuthMeth] Section 5.1) or when using Simple Authentication and
821 Security Layer [SASL] authentication ([AuthMeth] Section 3.3.2).
822 Where the server attempts to locate the named object, it SHALL NOT
823 perform alias dereferencing.
825 - authentication: information used in authentication. This type is
826 extensible as defined in Section 3.7 of [LDAPIANA]. Servers that
827 do not support a choice supplied by a client return
828 authMethodNotSupported in the resultCode field of the
831 Textual passwords (consisting of a character sequence with a known
832 character set and encoding) transferred to the server using the
833 simple AuthenticationChoice SHALL be transferred as [UTF-8]
834 encoded [Unicode]. Prior to transfer, clients SHOULD prepare text
835 passwords by applying the [SASLprep] profile of the [Stringprep]
836 algorithm. Passwords consisting of other data (such as random
837 octets) MUST NOT be altered. The determination of whether a
838 password is textual is a local client matter.
840 Authorization is the decision of which access an operation has to the
841 directory. Among other things, the process of authorization takes as
842 input authentication information obtained during the bind operation
843 and/or other acts of authentication (such as lower layer security
847 4.2.1. Processing of the Bind Request
849 Before processing a BindRequest, all uncompleted operations MUST
850 either complete or be abandoned. The server may either wait for the
851 uncompleted operations to complete, or abandon them. The server then
852 proceeds to authenticate the client in either a single-step, or
853 multi-step bind process. Each step requires the server to return a
854 BindResponse to indicate the status of authentication.
856 After sending a BindRequest, clients MUST NOT send further LDAP PDUs
857 until receiving the BindResponse. Similarly, servers SHOULD NOT
858 process or respond to requests received while processing a
861 If the client did not bind before sending a request and receives an
862 operationsError to that request, it may then send a Bind Request. If
863 this also fails or the client chooses not to bind on the existing
864 LDAP exchange, it may close the connection, reopen it and begin again
865 by first sending a PDU with a Bind Request. This will aid in
866 interoperating with servers implementing other versions of LDAP.
869 Sermersheim Internet-Draft - Expires Apr 2005 Page 15
870 Lightweight Directory Access Protocol Version 3
872 Clients may send multiple Bind Requests on an LDAP exchange to change
873 the authentication and/or security associations or to complete a
874 multi-stage bind process. Authentication from earlier binds is
875 subsequently ignored.
877 For some SASL authentication mechanisms, it may be necessary for the
878 client to invoke the BindRequest multiple times ([AuthMeth] Section
879 8.2). Clients MUST NOT invoke operations between two Bind Requests
880 made as part of a multi-stage bind.
882 A client may abort a SASL bind negotiation by sending a BindRequest
883 with a different value in the mechanism field of SaslCredentials, or
884 an AuthenticationChoice other than sasl.
886 If the client sends a BindRequest with the sasl mechanism field as an
887 empty string, the server MUST return a BindResponse with
888 authMethodNotSupported as the resultCode. This will allow clients to
889 abort a negotiation if it wishes to try again with the same SASL
895 The Bind Response is defined as follows.
897 BindResponse ::= [APPLICATION 1] SEQUENCE {
898 COMPONENTS OF LDAPResult,
899 serverSaslCreds [7] OCTET STRING OPTIONAL }
901 BindResponse consists simply of an indication from the server of the
902 status of the client's request for authentication.
904 A successful bind operation is indicated by a BindResponse with a
905 resultCode set to success. Otherwise, an appropriate result code is
906 set in the BindResponse. For bind, the protocolError result code may
907 be used to indicate that the version number supplied by the client is
910 If the client receives a BindResponse where the resultCode field is
911 protocolError, it is to assume that the server does not support this
912 version of LDAP. While the client may be able proceed with another
913 version of this protocol (this may or may not require closing and re-
914 establishing the connection), how to proceed with another version of
915 this protocol is beyond the scope of this document. Clients which are
916 unable or unwilling to proceed SHOULD close the connection.
918 The serverSaslCreds field is used as part of a SASL-defined bind
919 mechanism to allow the client to authenticate the server to which it
920 is communicating, or to perform "challenge-response" authentication.
921 If the client bound with the simple choice, or the SASL mechanism
922 does not require the server to return information to the client, then
923 this field SHALL NOT be included in the BindResponse.
927 Sermersheim Internet-Draft - Expires Apr 2005 Page 16
928 Lightweight Directory Access Protocol Version 3
930 4.3. Unbind Operation
932 The function of the Unbind Operation is to terminate an LDAP exchange
933 and close the connection. The Unbind operation is not the antithesis
934 of the Bind operation as the name implies. The naming of these
935 operations is historical. The Unbind operation should be thought of
936 as the "quit" operation.
938 The Unbind Operation is defined as follows:
940 UnbindRequest ::= [APPLICATION 2] NULL
942 The Unbind Operation has no response defined. Upon transmission of
943 the UnbindRequest, each protocol peer is to consider the LDAP
944 exchange terminated, MUST cease transmission of messages to the other
945 peer, and MUST close the connection. Uncompleted operations are
946 handled as specified in Section 5.1.
949 4.4. Unsolicited Notification
951 An unsolicited notification is an LDAPMessage sent from the server to
952 the client which is not in response to any LDAPMessage received by
953 the server. It is used to signal an extraordinary condition in the
954 server or in the LDAP exchange or connection between the client and
955 the server. The notification is of an advisory nature, and the server
956 will not expect any response to be returned from the client.
958 The unsolicited notification is structured as an LDAPMessage in which
959 the messageID is zero and protocolOp is of the extendedResp form (See
960 Section 4.12). The responseName field of the ExtendedResponse always
961 contains an LDAPOID which is unique for this notification.
963 One unsolicited notification (Notice of Disconnection) is defined in
964 this document. The specification of an unsolicited notification
967 - the OBJECT IDENTIFIER assigned to the notification (to be
968 specified in the responseName,
970 - the format of the contents (if any) of the responseValue,
972 - the circumstances which will cause the notification to be
975 - the semantics of the operation.
978 4.4.1. Notice of Disconnection
980 This notification may be used by the server to advise the client that
981 the server is about to close the connection due to an error
982 condition. This notification is intended to assist clients in
983 distinguishing between an error condition and a transient network
985 Sermersheim Internet-Draft - Expires Apr 2005 Page 17
986 Lightweight Directory Access Protocol Version 3
988 failure. Note that this notification is not a response to an unbind
989 requested by the client. Uncompleted operations are handled as
990 specified in Section 5.1.
992 The responseName is 1.3.6.1.4.1.1466.20036, the responseValue field
993 is absent, and the resultCode is used to indicate the reason for the
996 Upon transmission of the Notice of Disconnection, the server is to
997 consider the LDAP exchange terminated, MUST cease transmission of
998 messages to the client, and MUST close the connection.
1001 4.5. Search Operation
1003 The Search Operation is used to request a server to return, subject
1004 to access controls and other restrictions, a set of entries matching
1005 a complex search criterion. This can be used to read attributes from
1006 a single entry, from entries immediately subordinate to a particular
1007 entry, or a whole subtree of entries.
1010 4.5.1. Search Request
1012 The Search Request is defined as follows:
1014 SearchRequest ::= [APPLICATION 3] SEQUENCE {
1020 derefAliases ENUMERATED {
1021 neverDerefAliases (0),
1022 derefInSearching (1),
1023 derefFindingBaseObj (2),
1025 sizeLimit INTEGER (0 .. maxInt),
1026 timeLimit INTEGER (0 .. maxInt),
1029 attributes AttributeSelection }
1031 AttributeSelection ::= SEQUENCE OF selector LDAPString
1032 -- The LDAPString is constrained to
1033 -- <attributeSelector> below
1036 and [0] SET OF filter Filter,
1037 or [1] SET OF filter Filter,
1039 equalityMatch [3] AttributeValueAssertion,
1040 substrings [4] SubstringFilter,
1041 greaterOrEqual [5] AttributeValueAssertion,
1043 Sermersheim Internet-Draft - Expires Apr 2005 Page 18
1044 Lightweight Directory Access Protocol Version 3
1046 lessOrEqual [6] AttributeValueAssertion,
1047 present [7] AttributeDescription,
1048 approxMatch [8] AttributeValueAssertion,
1049 extensibleMatch [9] MatchingRuleAssertion }
1051 SubstringFilter ::= SEQUENCE {
1052 type AttributeDescription,
1053 -- initial and final can occur at most once
1054 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE {
1055 initial [0] AssertionValue,
1056 any [1] AssertionValue,
1057 final [2] AssertionValue } }
1059 MatchingRuleAssertion ::= SEQUENCE {
1060 matchingRule [1] MatchingRuleId OPTIONAL,
1061 type [2] AttributeDescription OPTIONAL,
1062 matchValue [3] AssertionValue,
1063 dnAttributes [4] BOOLEAN DEFAULT FALSE }
1065 Fields of the Search Request are:
1067 - baseObject: The name of the base object entry relative to which
1068 the search is to be performed.
1070 - scope: Specifies the scope of the search to be performed. The
1071 semantics (as described in [X.511]) of the possible values of this
1074 baseObject: The scope is constrained to the entry named by
1077 singleLevel: The scope is constrained to the immediate
1078 subordinates of the entry named by baseObject.
1080 wholeSubtree: the scope is constrained to the entry named by
1081 the baseObject, and all its subordinates.
1084 - derefAliases: An indicator as to how alias entries (as defined in
1085 [Models]) are to be handled in searching. The semantics of the
1086 possible values of this field are:
1088 neverDerefAliases: Do not dereference aliases in searching or
1089 in locating the base object of the search.
1091 derefInSearching: While searching, dereference any alias entry
1092 subordinate to the base object which is also in the search
1093 scope. The filter is applied to the dereferenced object(s). If
1094 the search scope is wholeSubtree, the search continues in the
1095 subtree of any dereferenced object. Aliases in that subtree are
1096 also dereferenced. Servers SHOULD eliminate duplicate entries
1097 that arise due to alias dereferencing while searching.
1102 Sermersheim Internet-Draft - Expires Apr 2005 Page 19
1103 Lightweight Directory Access Protocol Version 3
1105 derefFindingBaseObj: Dereference aliases in locating the base
1106 object of the search, but not when searching subordinates of
1109 derefAlways: Dereference aliases both in searching and in
1110 locating the base object of the search.
1111 Servers MUST detect looping while dereferencing aliases in order
1112 to prevent denial of service attacks of this nature.
1114 - sizeLimit: A size limit that restricts the maximum number of
1115 entries to be returned as a result of the search. A value of zero
1116 in this field indicates that no client-requested size limit
1117 restrictions are in effect for the search. Servers may also
1118 enforce a maximum number of entries to return.
1120 - timeLimit: A time limit that restricts the maximum time (in
1121 seconds) allowed for a search. A value of zero in this field
1122 indicates that no client-requested time limit restrictions are in
1123 effect for the search. Servers may also enforce a maximum time
1124 limit for the search.
1126 - typesOnly: An indicator as to whether search results are to
1127 contain both attribute descriptions and values, or just attribute
1128 descriptions. Setting this field to TRUE causes only attribute
1129 descriptions (no values) to be returned. Setting this field to
1130 FALSE causes both attribute descriptions and values to be
1133 - filter: A filter that defines the conditions that must be
1134 fulfilled in order for the search to match a given entry.
1136 The 'and', 'or' and 'not' choices can be used to form combinations
1137 of filters. At least one filter element MUST be present in an
1138 'and' or 'or' choice. The others match against individual
1139 attribute values of entries in the scope of the search.
1140 (Implementor's note: the 'not' filter is an example of a tagged
1141 choice in an implicitly-tagged module. In BER this is treated as
1142 if the tag was explicit.)
1144 A server MUST evaluate filters according to the three-valued logic
1145 of X.511 (1993) Section 7.8.1. In summary, a filter is evaluated
1146 to either "TRUE", "FALSE" or "Undefined". If the filter evaluates
1147 to TRUE for a particular entry, then the attributes of that entry
1148 are returned as part of the search result (subject to any
1149 applicable access control restrictions). If the filter evaluates
1150 to FALSE or Undefined, then the entry is ignored for the search.
1152 A filter of the "and" choice is TRUE if all the filters in the SET
1153 OF evaluate to TRUE, FALSE if at least one filter is FALSE, and
1154 otherwise Undefined. A filter of the "or" choice is FALSE if all
1155 of the filters in the SET OF evaluate to FALSE, TRUE if at least
1156 one filter is TRUE, and Undefined otherwise. A filter of the 'not'
1157 choice is TRUE if the filter being negated is FALSE, FALSE if it
1158 is TRUE, and Undefined if it is Undefined.
1160 Sermersheim Internet-Draft - Expires Apr 2005 Page 20
1161 Lightweight Directory Access Protocol Version 3
1164 The present match evaluates to TRUE where there is an attribute or
1165 subtype of the specified attribute description present in an
1166 entry, and FALSE otherwise (including a presence test with an
1167 unrecognized attribute description.)
1169 The matching rule for equalityMatch filter items is defined by the
1170 EQUALITY matching rule for the attribute type.
1172 There SHALL be at most one 'initial', and at most one 'final' in
1173 the 'substrings' of a SubstringFilter. If 'initial' is present, it
1174 SHALL be the first element of 'substrings'. If 'final' is present,
1175 it SHALL be the last element of 'substrings'.
1176 The matching rule for AssertionValues in a substrings filter item
1177 is defined by the SUBSTR matching rule for the attribute type.
1178 Note that the AssertionValue in a substrings filter item conforms
1179 to the assertion syntax of the EQUALITY matching rule for the
1180 attribute type rather than the assertion syntax of the SUBSTR
1181 matching rule for the attribute type. Conceptually, the entire
1182 SubstringFilter is converted into an assertion value of the
1183 substrings matching rule prior to applying the rule.
1185 The matching rule for the greaterOrEqual filter item is defined by
1186 the ORDERING and EQUALITY matching rules for the attribute type.
1188 The matching rule for the lessOrEqual filter item is defined by
1189 the ORDERING matching rule for the attribute type.
1191 An approxMatch filter item evaluates to TRUE when there is a value
1192 of the attribute or subtype for which some locally-defined
1193 approximate matching algorithm (e.g. spelling variations, phonetic
1194 match, etc.) returns TRUE. If an item matches for equality, it
1195 also satisfies an approximate match. If approximate matching is
1196 not supported for the attribute, this filter item should be
1197 treated as an equalityMatch.
1199 An extensibleMatch filter item is evaluated as follows:
1201 If the matchingRule field is absent, the type field MUST be
1202 present, and an equality match is performed for that type.
1204 If the type field is absent and the matchingRule is present, the
1205 matchValue is compared against all attributes in an entry which
1206 support that matchingRule. The matchingRule determines the
1207 syntax for the assertion value. The filter item evaluates to
1208 TRUE if it matches with at least one attribute in the entry,
1209 FALSE if it does not match any attribute in the entry, and
1210 Undefined if the matchingRule is not recognized or the
1211 assertionValue is invalid.
1213 If the type field is present and the matchingRule is present,
1214 the matchValue is compared against entry attributes of the
1215 specified type. In this case, the matchingRule MUST be one
1219 Sermersheim Internet-Draft - Expires Apr 2005 Page 21
1220 Lightweight Directory Access Protocol Version 3
1222 suitable for use with the specified type (see [Syntaxes]),
1223 otherwise the filter item is Undefined.
1225 If the dnAttributes field is set to TRUE, the match is
1226 additionally applied against all the AttributeValueAssertions in
1227 an entry's distinguished name, and evaluates to TRUE if there is
1228 at least one attribute in the distinguished name for which the
1229 filter item evaluates to TRUE. The dnAttributes field is present
1230 to alleviate the need for multiple versions of generic matching
1231 rules (such as word matching), where one applies to entries and
1232 another applies to entries and dn attributes as well.
1234 A filter item evaluates to Undefined when the server would not be
1235 able to determine whether the assertion value matches an entry.
1238 - An attribute description in an equalityMatch, substrings,
1239 greaterOrEqual, lessOrEqual, approxMatch or extensibleMatch
1240 filter is not recognized by the server.
1242 - The attribute type does not define the appropriate matching
1245 - A MatchingRuleId in the extensibleMatch is not recognized by
1246 the server or is not valid for the attribute type.
1248 - The type of filtering requested is not implemented.
1250 - The assertion value is invalid.
1252 For example, if a server did not recognize the attribute type
1253 shoeSize, a filter of (shoeSize=*) would evaluate to FALSE, and
1254 the filters (shoeSize=12), (shoeSize>=12) and (shoeSize<=12) would
1255 each evaluate to Undefined.
1257 Servers MUST NOT return errors if attribute descriptions or
1258 matching rule ids are not recognized, assertion values are
1259 invalid, or the assertion syntax is not supported. More details of
1260 filter processing are given in Section 7.8 of [X.511].
1262 - attributes: A selection list of the attributes to be returned from
1263 each entry which matches the search filter. LDAPString values of
1264 this field are constrained to the following Augmented Backus-Naur
1267 attributeSelector = attributedescription / selectorpecial
1269 selectorspecial = noattrs / alluserattrs
1271 noattrs = %x31.2E.31 ; "1.1"
1273 alluserattrs = %x2A ; asterisk ("*")
1278 Sermersheim Internet-Draft - Expires Apr 2005 Page 22
1279 Lightweight Directory Access Protocol Version 3
1281 The <attributedescription> production is defined in Section 2.5 of
1284 There are three special cases which may appear in the attributes
1287 - an empty list with no attributes,
1289 - a list containing "*" (with zero or more attribute
1292 - a list containing only "1.1".
1294 An empty list requests the return of all user attributes.
1296 A list containing "*" requests the return of all user attributes
1297 in addition to other listed (operational) attributes.
1299 A list containing only the OID "1.1" indicates that no attributes
1300 are to be returned. If "1.1" is provided with other
1301 attributeSelector values, the "1.1" attributeSelector is ignored.
1302 This OID was chosen because it does not (and can not) correspond
1303 to any attribute in use.
1305 Client implementors should note that even if all user attributes
1306 are requested, some attributes and/or attribute values of the
1307 entry may not be included in search results due to access controls
1308 or other restrictions. Furthermore, servers will not return
1309 operational attributes, such as objectClasses or attributeTypes,
1310 unless they are listed by name. Operational attributes are
1311 described in [Models].
1313 Attributes are returned at most once in an entry. If an attribute
1314 description is named more than once in the list, the subsequent
1315 names are ignored. If an attribute description in the list is not
1316 recognized, it is ignored by the server.
1318 Note that an X.500 "list"-like operation can be emulated by the
1319 client requesting a one-level LDAP search operation with a filter
1320 checking for the presence of the 'objectClass' attribute, and that an
1321 X.500 "read"-like operation can be emulated by a base object LDAP
1322 search operation with the same filter. A server which provides a
1323 gateway to X.500 is not required to use the Read or List operations,
1324 although it may choose to do so, and if it does, it must provide the
1325 same semantics as the X.500 search operation.
1328 4.5.2. Search Result
1330 The results of the search operation are returned as zero or more
1331 searchResultEntry messages, zero or more SearchResultReference
1332 messages, followed by a single searchResultDone message.
1334 SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
1336 Sermersheim Internet-Draft - Expires Apr 2005 Page 23
1337 Lightweight Directory Access Protocol Version 3
1340 attributes PartialAttributeList }
1342 PartialAttributeList ::= SEQUENCE OF
1343 partialAttribute PartialAttribute
1344 -- Note that the PartialAttributeList may hold zero elements.
1345 -- This may happen when none of the attributes of an entry
1346 -- were requested, or could be returned.
1347 -- Note also that the partialAttribute vals set may hold zero
1348 -- elements. This may happen when typesOnly is requested, access
1349 -- controls prevent the return of values, or other reasons.
1351 SearchResultReference ::= [APPLICATION 19] SEQUENCE
1352 SIZE (1..MAX) OF uri URI
1354 SearchResultDone ::= [APPLICATION 5] LDAPResult
1356 Each SearchResultEntry represents an entry found during the search.
1357 Each SearchResultReference represents an area not yet explored during
1358 the search. The SearchResultEntry and SearchResultReference PDUs may
1359 come in any order. Following all the SearchResultReference and
1360 SearchResultEntry responses, the server returns a SearchResultDone
1361 response, which contains an indication of success, or detailing any
1362 errors that have occurred.
1364 Each entry returned in a SearchResultEntry will contain all
1365 appropriate attributes as specified in the attributes field of the
1366 Search Request. Return of attributes is subject to access control and
1367 other administrative policy.
1369 Some attributes may be constructed by the server and appear in a
1370 SearchResultEntry attribute list, although they are not stored
1371 attributes of an entry. Clients SHOULD NOT assume that all attributes
1372 can be modified, even if permitted by access control.
1374 If the server's schema defines short names [Models] for an attribute
1375 type then the server SHOULD use one of those names in attribute
1376 descriptions for that attribute type (in preference to using the
1377 <numericoid> [Models] format of the attribute type's object
1378 identifier). The server SHOULD NOT use the short name if that name is
1379 known by the server to be ambiguous, or otherwise likely to cause
1380 interoperability problems.
1383 4.5.3. Continuation References in the Search Result
1385 If the server was able to locate the entry referred to by the
1386 baseObject but was unable to search one or more non-local entries,
1387 the server may return one or more SearchResultReference entries, each
1388 containing a reference to another set of servers for continuing the
1389 operation. A server MUST NOT return any SearchResultReference if it
1390 has not located the baseObject and thus has not searched any entries;
1391 in this case it would return a SearchResultDone containing either a
1395 Sermersheim Internet-Draft - Expires Apr 2005 Page 24
1396 Lightweight Directory Access Protocol Version 3
1398 referral or noSuchObject result code (depending on the server's
1399 knowledge of the entry named in the baseObject).
1401 If a server holds a copy or partial copy of the subordinate naming
1402 context [Section 5 of Models], it may use the search filter to
1403 determine whether or not to return a SearchResultReference response.
1404 Otherwise SearchResultReference responses are always returned when in
1407 The SearchResultReference is of the same data type as the Referral.
1409 A URI for a server implementing LDAP and accessible via [TCP]/[IP]
1410 (v4 or v6) is written as an LDAP URL according to [LDAPURL].
1412 In order to complete the search, the client issues a new search
1413 operation for each SearchResultReference that is returned. Note that
1414 the abandon operation described in Section 4.11 applies only to a
1415 particular operation sent on the LDAP exchange between a client and
1416 server. The client must abandon subsequent search operations it
1417 wishes to individually.
1419 Clients that follow search continuation references MUST ensure that
1420 they do not loop between servers. They MUST NOT repeatedly contact
1421 the same server for the same request with the same target entry name,
1422 scope and filter. Some clients use a counter that is incremented each
1423 time search result reference handling occurs for an operation, and
1424 these kinds of clients MUST be able to handle at least ten nested
1425 search result references between the root and a leaf entry.
1427 When an LDAP URL is used, the following instructions are followed:
1429 - The <dn> part of the URL MUST be present, with the new target
1430 object name. The client MUST use this name when following the
1431 reference. UTF-8 encoded characters appearing in the string
1432 representation of a DN or search filter may not be legal for URLs
1433 (e.g. spaces) and MUST be escaped using the % method in [URI].
1435 - Some servers (e.g. participating in distributed indexing) may
1436 provide a different filter in a URL of a SearchResultReference.
1438 - If the <filter> part of the URL is present, the client MUST use
1439 this filter in its next request to progress this search, and if it
1440 is not present the client MUST use the same filter as it used for
1443 - If the originating search scope was singleLevel, the <scope> part
1444 of the URL will be "base".
1446 - It is RECOMMENDED that the <scope> part be present to avoid
1449 - Other aspects of the new search request may be the same as or
1450 different from the search request which generated the
1451 SearchResultReference.
1453 Sermersheim Internet-Draft - Expires Apr 2005 Page 25
1454 Lightweight Directory Access Protocol Version 3
1457 - The name of an unexplored subtree in a SearchResultReference need
1458 not be subordinate to the base object.
1460 Other kinds of URIs may be returned. The syntax and semantics of such
1461 URIs is left to future specifications. Clients may ignore URIs that
1462 they do not support.
1467 For example, suppose the contacted server (hosta) holds the entry
1468 <DC=Example,DC=NET> and the entry <CN=Manager,DC=Example,DC=NET>. It
1469 knows that either LDAP-capable servers (hostb) or (hostc) hold
1470 <OU=People,DC=Example,DC=NET> (one is the master and the other server
1471 a shadow), and that LDAP-capable server (hostd) holds the subtree
1472 <OU=Roles,DC=Example,DC=NET>. If a wholeSubtree search of
1473 <DC=Example,DC=NET> is requested to the contacted server, it may
1474 return the following:
1476 SearchResultEntry for DC=Example,DC=NET
1477 SearchResultEntry for CN=Manager,DC=Example,DC=NET
1478 SearchResultReference {
1479 ldap://hostb/OU=People,DC=Example,DC=NET??sub
1480 ldap://hostc/OU=People,DC=Example,DC=NET??sub }
1481 SearchResultReference {
1482 ldap://hostd/OU=Roles,DC=Example,DC=NET??sub }
1483 SearchResultDone (success)
1485 Client implementors should note that when following a
1486 SearchResultReference, additional SearchResultReference may be
1487 generated. Continuing the example, if the client contacted the server
1488 (hostb) and issued the search for the subtree
1489 <OU=People,DC=Example,DC=NET>, the server might respond as follows:
1491 SearchResultEntry for OU=People,DC=Example,DC=NET
1492 SearchResultReference {
1493 ldap://hoste/OU=Managers,OU=People,DC=Example,DC=NET??sub }
1494 SearchResultReference {
1495 ldap://hostf/OU=Consultants,OU=People,DC=Example,DC=NET??sub }
1496 SearchResultDone (success)
1498 Similarly, if a singleLevel search of <DC=Example,DC=NET> is
1499 requested to the contacted server, it may return the following:
1501 SearchResultEntry for CN=Manager,DC=Example,DC=NET
1502 SearchResultReference {
1503 ldap://hostb/OU=People,DC=Example,DC=NET??base
1504 ldap://hostc/OU=People,DC=Example,DC=NET??base }
1505 SearchResultReference {
1506 ldap://hostd/OU=Roles,DC=Example,DC=NET??base }
1507 SearchResultDone (success)
1512 Sermersheim Internet-Draft - Expires Apr 2005 Page 26
1513 Lightweight Directory Access Protocol Version 3
1515 If the contacted server does not hold the base object for the search,
1516 but has knowledge of its possible location, then it may return a
1517 referral to the client. In this case, if the client requests a
1518 subtree search of <DC=Example,DC=ORG> to hosta, the server returns a
1519 SearchResultDone containing a referral.
1521 SearchResultDone (referral) {
1522 ldap://hostg/DC=Example,DC=ORG??sub }
1525 4.6. Modify Operation
1527 The Modify Operation allows a client to request that a modification
1528 of an entry be performed on its behalf by a server. The Modify
1529 Request is defined as follows:
1531 ModifyRequest ::= [APPLICATION 6] SEQUENCE {
1533 changes SEQUENCE OF change SEQUENCE {
1534 operation ENUMERATED {
1538 modification PartialAttribute } }
1540 Fields of the Modify Request are:
1542 - object: The name of the object to be modified. The value of this
1543 field contains the DN of the entry to be modified. The server
1544 SHALL NOT perform any alias dereferencing in determining the
1545 object to be modified.
1547 - changes: A list of modifications to be performed on the entry. The
1548 entire list of modifications MUST be performed in the order they
1549 are listed as a single atomic operation. While individual
1550 modifications may violate certain aspects of the directory schema
1551 (such as the object class definition and DIT content rule), the
1552 resulting entry after the entire list of modifications is
1553 performed MUST conform to the requirements of the directory model
1554 and controlling schema [Models].
1556 - operation: Used to specify the type of modification being
1557 performed. Each operation type acts on the following
1558 modification. The values of this field have the following
1559 semantics respectively:
1561 add: add values listed to the modification attribute,
1562 creating the attribute if necessary;
1564 delete: delete values listed from the modification attribute,
1565 removing the entire attribute if no values are listed, or if
1566 all current values of the attribute are listed for deletion;
1571 Sermersheim Internet-Draft - Expires Apr 2005 Page 27
1572 Lightweight Directory Access Protocol Version 3
1574 replace: replace all existing values of the modification
1575 attribute with the new values listed, creating the attribute
1576 if it did not already exist. A replace with no value will
1577 delete the entire attribute if it exists, and is ignored if
1578 the attribute does not exist.
1580 - modification: A PartialAttribute (which may have an empty SET
1581 of vals) used to hold the attribute type or attribute type and
1582 values being modified.
1584 Upon receipt of a Modify Request, the server attempts to perform the
1585 necessary modifications to the DIT and returns the result in a Modify
1586 Response, defined as follows:
1588 ModifyResponse ::= [APPLICATION 7] LDAPResult
1590 The server will return to the client a single Modify Response
1591 indicating either the successful completion of the DIT modification,
1592 or the reason that the modification failed. Due to the requirement
1593 for atomicity in applying the list of modifications in the Modify
1594 Request, the client may expect that no modifications of the DIT have
1595 been performed if the Modify Response received indicates any sort of
1596 error, and that all requested modifications have been performed if
1597 the Modify Response indicates successful completion of the Modify
1598 Operation. The result of the modification is indeterminate if the
1599 Modify Response is not received (e.g. the LDA exchange is terminated
1600 or the Modify Operation is abandoned).
1602 The Modify Operation cannot be used to remove from an entry any of
1603 its distinguished values, i.e. those values which form the entry's
1604 relative distinguished name. An attempt to do so will result in the
1605 server returning the notAllowedOnRDN result code. The Modify DN
1606 Operation described in Section 4.9 is used to rename an entry.
1608 Note that due to the simplifications made in LDAP, there is not a
1609 direct mapping of the changes in an LDAP ModifyRequest onto the
1610 changes of a DAP ModifyEntry operation, and different implementations
1611 of LDAP-DAP gateways may use different means of representing the
1612 change. If successful, the final effect of the operations on the
1613 entry MUST be identical.
1618 The Add Operation allows a client to request the addition of an entry
1619 into the Directory. The Add Request is defined as follows:
1621 AddRequest ::= [APPLICATION 8] SEQUENCE {
1623 attributes AttributeList }
1625 AttributeList ::= SEQUENCE OF attribute Attribute
1627 Fields of the Add Request are:
1629 Sermersheim Internet-Draft - Expires Apr 2005 Page 28
1630 Lightweight Directory Access Protocol Version 3
1633 - entry: the name of the entry to be added. The server SHALL NOT
1634 dereference any aliases in locating the entry to be added.
1636 - attributes: the list of attributes that, along with those from the
1637 RDN, make up the content of the entry being added. Clients MAY or
1638 MAY NOT include the RDN attribute in this list. Clients MUST
1639 include the 'objectClass' attribute, and values of any mandatory
1640 attributes of the listed object classes. Clients MUST NOT supply
1641 NO-USER-MODIFICATION attributes such as the createTimestamp or
1642 creatorsName attributes, since the server maintains these
1645 The entry named in the entry field of the AddRequest MUST NOT exist
1646 for the AddRequest to succeed. The immediate superior (parent) of an
1647 object or alias entry to be added MUST exist. For example, if the
1648 client attempted to add <CN=JS,DC=Example,DC=NET>, the
1649 <DC=Example,DC=NET> entry did not exist, and the <DC=NET> entry did
1650 exist, then the server would return the noSuchObject result code with
1651 the matchedDN field containing <DC=NET>.
1653 Server implementations SHOULD NOT restrict where entries can be
1654 located in the Directory unless DIT structure rules are in place.
1655 Some servers allow the administrator to restrict the classes of
1656 entries which can be added to the Directory.
1658 Upon receipt of an Add Request, a server will attempt to add the
1659 requested entry. The result of the add attempt will be returned to
1660 the client in the Add Response, defined as follows:
1662 AddResponse ::= [APPLICATION 9] LDAPResult
1664 A response of success indicates that the new entry has been added to
1668 4.8. Delete Operation
1670 The Delete Operation allows a client to request the removal of an
1671 entry from the Directory. The Delete Request is defined as follows:
1673 DelRequest ::= [APPLICATION 10] LDAPDN
1675 The Delete Request consists of the name of the entry to be deleted.
1676 The server SHALL NOT dereference aliases while resolving the name of
1677 the target entry to be removed.
1679 Only leaf entries (those with no subordinate entries) can be deleted
1680 with this operation.
1682 Upon receipt of a Delete Request, a server will attempt to perform
1683 the entry removal requested and return the result in the Delete
1684 Response defined as follows:
1687 Sermersheim Internet-Draft - Expires Apr 2005 Page 29
1688 Lightweight Directory Access Protocol Version 3
1690 DelResponse ::= [APPLICATION 11] LDAPResult
1693 4.9. Modify DN Operation
1695 The Modify DN Operation allows a client to change the Relative
1696 Distinguished Name (RDN) of an entry in the Directory, and/or to move
1697 a subtree of entries to a new location in the Directory. The Modify
1698 DN Request is defined as follows:
1700 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
1702 newrdn RelativeLDAPDN,
1703 deleteoldrdn BOOLEAN,
1704 newSuperior [0] LDAPDN OPTIONAL }
1706 Fields of the Modify DN Request are:
1708 - entry: the name of the entry to be changed. This entry may or may
1709 not have subordinate entries.
1711 - newrdn: the new RDN of the entry. If the operation moves the entry
1712 to a new superior without changing its RDN, the value of the old
1713 RDN is supplied for this parameter.
1714 Attribute values of the new RDN not matching any attribute value
1715 of the entry are added to the entry and an appropriate error is
1716 returned if this fails.
1718 - deleteoldrdn: a boolean field that controls whether the old RDN
1719 attribute values are to be retained as attributes of the entry, or
1720 deleted from the entry.
1722 - newSuperior: if present, this is the name of an existing object
1723 entry which becomes the immediate superior (parent) of the
1726 The server SHALL NOT dereference any aliases in locating the objects
1727 named in entry or newSuperior.
1729 Upon receipt of a ModifyDNRequest, a server will attempt to perform
1730 the name change and return the result in the Modify DN Response,
1733 ModifyDNResponse ::= [APPLICATION 13] LDAPResult
1735 For example, if the entry named in the entry field was <cn=John
1736 Smith,c=US>, the newrdn field was <cn=John Cougar Smith>, and the
1737 newSuperior field was absent, then this operation would attempt to
1738 rename the entry to be <cn=John Cougar Smith,c=US>. If there was
1739 already an entry with that name, the operation would fail with the
1740 entryAlreadyExists result code.
1742 The object named in newSuperior MUST exist. For example, if the
1743 client attempted to add <CN=JS,DC=Example,DC=NET>, the
1745 Sermersheim Internet-Draft - Expires Apr 2005 Page 30
1746 Lightweight Directory Access Protocol Version 3
1748 <DC=Example,DC=NET> entry did not exist, and the <DC=NET> entry did
1749 exist, then the server would return the noSuchObject result code with
1750 the matchedDN field containing <DC=NET>.
1752 If the deleteoldrdn field is TRUE, the attribute values forming the
1753 old RDN but not the new RDN are deleted from the entry. If the
1754 deleteoldrdn field is FALSE, the attribute values forming the old RDN
1755 will be retained as non-distinguished attribute values of the entry.
1756 The server MUST fail the operation and return an error in the result
1757 code if the setting of the deleteoldrdn field would cause a schema
1758 inconsistency in the entry.
1760 Note that X.500 restricts the ModifyDN operation to only affect
1761 entries that are contained within a single server. If the LDAP server
1762 is mapped onto DAP, then this restriction will apply, and the
1763 affectsMultipleDSAs result code will be returned if this error
1764 occurred. In general, clients MUST NOT expect to be able to perform
1765 arbitrary movements of entries and subtrees between servers or
1766 between naming contexts.
1769 4.10. Compare Operation
1771 The Compare Operation allows a client to compare an assertion value
1772 with the values of a particular attribute in a particular entry in
1773 the Directory. The Compare Request is defined as follows:
1775 CompareRequest ::= [APPLICATION 14] SEQUENCE {
1777 ava AttributeValueAssertion }
1779 Fields of the Compare Request are:
1781 - entry: the name of the entry to be compared. The server SHALL NOT
1782 dereference any aliases in locating the entry to be compared.
1784 - ava: holds the attribute value assertion to be compared.
1786 Upon receipt of a Compare Request, a server will attempt to perform
1787 the requested comparison and return the result in the Compare
1788 Response, defined as follows:
1790 CompareResponse ::= [APPLICATION 15] LDAPResult
1792 The resultCode field is set to compareTrue, compareFalse, or an
1793 appropriate error. compareTrue indicates that the assertion value in
1794 the ava field matches a value of the attribute or subtype according
1795 to the attribute's EQUALITY matching rule. compareFalse indicates
1796 that the assertion value in the ava field and the values of the
1797 attribute or subtype did not match. Other result codes indicate
1798 either that the result of the comparison was Undefined (Section
1799 4.5.1), or that some error occurred.
1804 Sermersheim Internet-Draft - Expires Apr 2005 Page 31
1805 Lightweight Directory Access Protocol Version 3
1807 Note that some directory systems may establish access controls which
1808 permit the values of certain attributes (such as userPassword) to be
1809 compared but not interrogated by other means.
1812 4.11. Abandon Operation
1814 The function of the Abandon Operation is to allow a client to request
1815 that the server abandon an uncompleted operation. The Abandon Request
1816 is defined as follows:
1818 AbandonRequest ::= [APPLICATION 16] MessageID
1820 The MessageID is that of an operation which was requested earlier in
1821 this LDAP exchange. The abandon request itself has its own MessageID.
1822 This is distinct from the MessageID of the earlier operation being
1825 There is no response defined in the Abandon operation. Upon receipt
1826 of an AbandonRequest, the server MAY abandon the operation identified
1827 by the MessageID. Since the client cannot tell the difference between
1828 a successfully abandoned operation and an uncompleted operation, the
1829 application of the Abandon operation is limited to uses where the
1830 client does not require an indication of its outcome.
1832 Abandon, Bind, Unbind, and StartTLS operations cannot be abandoned.
1834 In the event that a server receives an Abandon Request on a Search
1835 Operation in the midst of transmitting responses to the search, that
1836 server MUST cease transmitting entry responses to the abandoned
1837 request immediately, and MUST NOT send the SearchResponseDone. Of
1838 course, the server MUST ensure that only properly encoded LDAPMessage
1839 PDUs are transmitted.
1841 The ability to abandon other (particularly update) operations is at
1842 the discretion of the server.
1844 Clients should not send abandon requests for the same operation
1845 multiple times, and MUST also be prepared to receive results from
1846 operations it has abandoned (since these may have been in transit
1847 when the abandon was requested, or are not able to be abandoned).
1849 Servers MUST discard abandon requests for message IDs they do not
1850 recognize, for operations which cannot be abandoned, and for
1851 operations which have already been abandoned.
1854 4.12. Extended Operation
1856 The extended operation allows additional operations to be defined for
1857 services not already available in the protocol. For example, to add
1858 operations to install transport layer security (see Section 4.14).
1863 Sermersheim Internet-Draft - Expires Apr 2005 Page 32
1864 Lightweight Directory Access Protocol Version 3
1866 The extended operation allows clients to make requests and receive
1867 responses with predefined syntaxes and semantics. These may be
1868 defined in RFCs or be private to particular implementations.
1870 Each extended operation consists of an extended request and an
1873 ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
1874 requestName [0] LDAPOID,
1875 requestValue [1] OCTET STRING OPTIONAL }
1877 The requestName is a dotted-decimal representation of the unique
1878 OBJECT IDENTIFIER corresponding to the request. The requestValue is
1879 information in a form defined by that request, encapsulated inside an
1882 The server will respond to this with an LDAPMessage containing an
1885 ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
1886 COMPONENTS OF LDAPResult,
1887 responseName [10] LDAPOID OPTIONAL,
1888 responseValue [11] OCTET STRING OPTIONAL }
1890 The responseName is typically not required to be present as the
1891 syntax and semantics of the response (including the format of the
1892 responseValue) is implicitly known and associated with the request by
1895 If the extended operation associated with the requestName is not
1896 supported by the server, the server MUST NOT provide a responseName
1897 nor a responseValue and MUST return a resultCode of protocolError.
1899 The requestValue and responseValue fields contain any information
1900 associated with the operation. The format of these fields is defined
1901 by the specification of the extended operation. Implementations MUST
1902 be prepared to handle arbitrary contents of these fields, including
1903 zero bytes. Values that are defined in terms of ASN.1 and BER encoded
1904 according to Section 5.2, also follow the extensibility rules in
1907 Servers list the requestName of Extended Requests they recognize in
1908 the 'supportedExtension' attribute in the root DSE (Section 5.1 of
1911 Extended operations may be specified in other documents. The
1912 specification of an extended operation consists of:
1914 - the OBJECT IDENTIFIER assigned to the requestName,
1916 - the OBJECT IDENTIFIER (if any) assigned to the responseName (note
1917 that the same OBJECT IDENTIFIER my be used for both the
1918 requestName and responseName),
1921 Sermersheim Internet-Draft - Expires Apr 2005 Page 33
1922 Lightweight Directory Access Protocol Version 3
1924 - the format of the contents of the requestValue and responseValue
1927 - the semantics of the operation.
1930 4.13. IntermediateResponse Message
1932 While the Search operation provides a mechanism to return multiple
1933 response messages for a single search request, other operations, by
1934 nature, do not provide for multiple response messages.
1936 The IntermediateResponse message provides a general mechanism for
1937 defining single-request/multiple-response operations in LDAP. This
1938 message is intended to be used in conjunction with the extended
1939 operation to define new single-request/multiple-response operations
1940 or in conjunction with a control when extending existing LDAP
1941 operations in a way that requires them to return intermediate
1942 response information.
1944 It is intended that the definitions and descriptions of extended
1945 operations and controls that make use of the IntermediateResponse
1946 message will define the circumstances when an IntermediateResponse
1947 message can be sent by a server and the associated meaning of an
1948 IntermediateResponse message sent in a particular circumstance.
1950 IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
1951 responseName [0] LDAPOID OPTIONAL,
1952 responseValue [1] OCTET STRING OPTIONAL }
1954 IntermediateResponse messages SHALL NOT be returned to the client
1955 unless the client issues a request that specifically solicits their
1956 return. This document defines two forms of solicitation: extended
1957 operation and request control. IntermediateResponse messages are
1958 specified in documents describing the manner in which they are
1959 solicited (i.e. in the extended operation or request control
1960 specification that uses them). These specifications include:
1962 - the OBJECT IDENTIFIER (if any) assigned to the responseName,
1964 - the format of the contents of the responseValue, and
1966 - the semantics associated with the IntermediateResponse message.
1968 Extensions that allow the return of multiple types of
1969 IntermediateResponse messages SHALL identify those types using unique
1970 responseName values (note that one of these may specify no value).
1972 Sections 4.13.1 and 4.13.2 describe additional requirements on the
1973 inclusion of responseName and responseValue in IntermediateResponse
1977 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse
1979 Sermersheim Internet-Draft - Expires Apr 2005 Page 34
1980 Lightweight Directory Access Protocol Version 3
1983 A single-request/multiple-response operation may be defined using a
1984 single ExtendedRequest message to solicit zero or more
1985 IntermediateResponse messages of one or more kinds followed by an
1986 ExtendedResponse message.
1989 4.13.2. Usage with LDAP Request Controls
1991 A control's semantics may include the return of zero or more
1992 IntermediateResponse messages prior to returning the final result
1993 code for the operation. One or more kinds of IntermediateResponse
1994 messages may be sent in response to a request control.
1996 All IntermediateResponse messages associated with request controls
1997 SHALL include a responseName. This requirement ensures that the
1998 client can correctly identify the source of IntermediateResponse
2001 - two or more controls using IntermediateResponse messages are
2002 included in a request for any LDAP operation or
2004 - one or more controls using IntermediateResponse messages are
2005 included in a request with an LDAP extended operation that uses
2006 IntermediateResponse messages.
2009 4.14. StartTLS Operation
2011 The Start Transport Layer Security (StartTLS) operationÆs purpose is
2012 to initiate installation of a TLS layer. The StartTLS operation is
2013 defined using the extended operation mechanism described in Section
2017 4.14.1. StartTLS Request
2019 A client requests TLS establishment by transmitting a StartTLS
2020 request PDU to the server. The StartTLS request is defined in terms
2021 of an ExtendedRequest. The requestName is "1.3.6.1.4.1.1466.20037",
2022 and the requestValue field is always absent.
2024 The client MUST NOT send any PDUs on this LDAP exchange following
2025 this request until it receives a StartTLS extended response and, in
2026 the case of a successful response, completes TLS negotiations.
2028 Sequencing problems (particularly those detailed in Section 3.1.1 of
2029 [AuthMeth] result in an operationsError being returned in the
2032 If the server does not support TLS (whether by design or by current
2033 configuration), it returns the protocolError resultCode as described
2036 Sermersheim Internet-Draft - Expires Apr 2005 Page 35
2037 Lightweight Directory Access Protocol Version 3
2041 4.14.2. StartTLS Response
2043 When a StartTLS request is made, servers supporting the operation
2044 MUST return a StartTLS response PDU to the requestor. The
2045 responseName, if present, is also "1.3.6.1.4.1.1466.20037". The
2046 responseValue is absent.
2048 If the server is willing and able to negotiate TLS, it returns a
2049 success resultCode. Refer to Section 4 of [AuthMeth] for details.
2051 If the server is otherwise unwilling or unable to perform this
2052 operation, the server is to return an appropriate result code
2053 indicating the nature of the problem. For example, if the TLS
2054 subsystem is not presently available, the server may return indicate
2055 so by returning the unavailable resultCode.
2058 4.14.3. Removal of the TLS Layer
2060 Two forms of TLS layer removal -- graceful and abrupt -- are
2061 provided. These do not involve LDAP PDUs, but are preformed at the
2064 If the connection is closed, uncompleted operations are handled as
2065 specified in Section 5.1.
2068 4.14.3.1. Graceful Removal
2070 Either the client or server MAY remove the TLS layer and leave the
2071 LDAP exchange intact by sending and receiving a TLS closure alert.
2073 The initiating protocol peer sends the TLS closure alert. If it
2074 wishes to leave the LDAP exchange intact, it then MUST cease to send
2075 further PDUs and MUST ignore any received LDAP PDUs until it receives
2076 a TLS closure alert from the other peer.
2078 Once the initiating protocol peer receives a TLS closure alert from
2079 the other peer it MAY send and receive LDAP PDUs.
2081 When a protocol peer receives the initial TLS closure alert, it may
2082 choose to allow the LDAP exchange to remain intact. In this case, it
2083 MUST immediately transmit a TLS closure alert. Following this, it MAY
2084 send and receive LDAP PDUs.
2086 Protocol peers MAY close the connection after sending or receiving a
2089 After the TLS layer has been removed, the server MUST NOT send
2090 responses to any request message received before the TLS closure
2092 Sermersheim Internet-Draft - Expires Apr 2005 Page 36
2093 Lightweight Directory Access Protocol Version 3
2095 alert. Thus, clients wishing to receive responses to messages sent
2096 while the TLS layer is intact MUST wait for those message responses
2097 before sending the TLS closure alert.
2100 4.14.3.2. Abrupt Removal
2102 Either the client or server MAY abruptly remove the TLS layer by
2103 closing the connection. In this circumstance, a server MAY send the
2104 client a Notice of Disconnection before closing the connection.
2107 5. Protocol Encoding, Connection, and Transfer
2109 This protocol is designed to run over connection-oriented, reliable
2110 transports, where the data stream is divided into octets (8-bit
2111 units), with each octet and each bit being significant.
2113 One underlying service, LDAP over TCP, is defined in Section
2114 5.3. This service is generally applicable to applications providing
2115 or consuming X.500-based directory services on the Internet. This
2116 specification was generally written with the TCP mapping in mind.
2117 Specifications detailing other mappings may encounter various
2120 Implementations of LDAP over TCP MUST implement the mapping as
2121 described in Section 5.3.
2123 This table illustrates the relationship between the different layers
2124 involved in an exchange between two protocol peers:
2128 +---------------+ > LDAP PDUs
2129 +---------------+ < data
2131 +---------------+ > SASL-protected data
2132 +---------------+ < data
2134 Application +---------------+ > TLS-protected data
2135 ------------+---------------+ < data
2136 Transport | connection |
2140 5.2. Protocol Encoding
2142 The protocol elements of LDAP SHALL be encoded for exchange using the
2143 Basic Encoding Rules [BER] of [ASN.1] with the following
2146 - Only the definite form of length encoding is used.
2149 Sermersheim Internet-Draft - Expires Apr 2005 Page 37
2150 Lightweight Directory Access Protocol Version 3
2152 - OCTET STRING values are encoded in the primitive form only.
2154 - If the value of a BOOLEAN type is true, the encoding of the value
2155 octet is set to hex "FF".
2157 - If a value of a type is its default value, it is absent. Only some
2158 BOOLEAN and INTEGER types have default values in this protocol
2161 These restrictions are meant to ease the overhead of encoding and
2162 decoding certain elements in BER.
2164 These restrictions do not apply to ASN.1 types encapsulated inside of
2165 OCTET STRING values, such as attribute values, unless otherwise
2169 5.3. Transmission Control Protocol (TCP)
2171 The encoded LDAPMessage PDUs are mapped directly onto the [TCP]
2172 bytestream using the BER-based encoding described in Section 5.2. It
2173 is recommended that server implementations running over the TCP
2174 provide a protocol listener on the Internet Assigned Numbers
2175 Authority (IANA)-assigned LDAP port, 389 [PortReg]. Servers may
2176 instead provide a listener on a different port number. Clients MUST
2177 support contacting servers on any valid TCP port.
2180 6. Security Considerations
2182 This version of the protocol provides facilities for simple
2183 authentication using a cleartext password, as well as any [SASL]
2184 mechanism. Installing SASL layers can provide integrity and other
2185 data security services.
2187 It is also permitted that the server can return its credentials to
2188 the client, if it chooses to do so.
2190 Use of cleartext password is strongly discouraged where the
2191 underlying transport service cannot guarantee confidentiality and may
2192 result in disclosure of the password to unauthorized parties.
2194 Servers are encouraged to prevent directory modifications by clients
2195 that have authenticated anonymously [AuthMeth].
2197 Security considerations for authentication methods, SASL mechanisms,
2198 and TLS are described in [AuthMeth].
2200 It should be noted that SASL authentication exchanges do not provide
2201 data confidentiality nor integrity protection for the version or name
2202 fields of the bind request nor the resultCode, diagnosticMessage, or
2203 referral fields of the bind response nor of any information contained
2204 in controls attached to bind request or responses. Thus information
2205 contained in these fields SHOULD NOT be relied on unless otherwise
2207 Sermersheim Internet-Draft - Expires Apr 2005 Page 38
2208 Lightweight Directory Access Protocol Version 3
2210 protected (such as by establishing protections at the transport
2213 Server implementors should plan for the possibility of (protocol or
2214 external) events which alter the information used to establish
2215 security factors (e.g., credentials, authorization identities, access
2216 controls) during the course of the LDAP exchange, and even during the
2217 performance of a particular operation, and should take steps to avoid
2218 insecure side effects of these changes. The ways in which these
2219 issues are addressed are application and/or implementation specific.
2221 Implementations which cache attributes and entries obtained via LDAP
2222 MUST ensure that access controls are maintained if that information
2223 is to be provided to multiple clients, since servers may have access
2224 control policies which prevent the return of entries or attributes in
2225 search results except to particular authenticated clients. For
2226 example, caches could serve result information only to the client
2227 whose request caused it to be in the cache.
2229 Servers may return referrals or search result references which
2230 redirect clients to peer servers. It is possible for a rogue
2231 application to inject such referrals into the data stream in an
2232 attempt to redirect a client to a rogue server. Clients are advised
2233 to be aware of this, and possibly reject referrals when
2234 confidentiality measures are not in place. Clients are advised to
2235 reject referrals from the StartTLS operation.
2237 The matchedDN and diagnosticMessage fields, as well as some
2238 resultCode values (e.g., attributeOrValueExists and
2239 entryAlreadyExists), could disclose the presence the specific data in
2240 the directory which is subject to access and other administrative
2241 controls. Server implementations should restrict access to protected
2242 information equally under both normal and error conditions.
2244 Protocol peers MUST be prepared to handle invalid and arbitrary
2245 length protocol encodings. Invalid protocol encodings include: BER
2246 encoding exceptions, format string and UTF-8 encoding exceptions,
2247 overflow exceptions, integer value exceptions, and binary mode on/off
2248 flag exceptions. The LDAPv3 PROTOS [PROTOS-LDAP] test suite provides
2249 excellent examples of these exceptions and test cases used to
2255 This document is based on RFC 2251 by Mark Wahl, Tim Howes, and Steve
2256 Kille. RFC 2251 was a product of the IETF ASID Working Group.
2258 It is also based on RFC 2830 by Jeff Hodges, RL "Bob" Morgan, and
2259 Mark Wahl. RFC 2830 was a product of the IETF LDAPEXT Working Group.
2261 It is also based on RFC 3771 by Roger Harrison, and Kurt Zeilenga.
2262 RFC 3771 was an individual submission to the IETF.
2265 Sermersheim Internet-Draft - Expires Apr 2005 Page 39
2266 Lightweight Directory Access Protocol Version 3
2268 This document is a product of the IETF LDAPBIS Working Group.
2269 Significant contributors of technical review and content include Kurt
2270 Zeilenga, Steven Legg, and Hallvard Furuseth.
2273 8. Normative References
2275 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
2276 Specifications: ABNF", RFC 2234, November 1997.
2278 [ASN.1] ITU-T Recommendation X.680 (07/2002) | ISO/IEC 8824-1:2002
2279 "Information Technology - Abstract Syntax Notation One
2280 (ASN.1): Specification of basic notation"
2282 [AuthMeth] Harrison, R., "LDAP: Authentication Methods and Connection
2283 Level Security Mechanisms", draft-ietf-ldapbis-authmeth-
2284 xx.txt, (a work in progress).
2286 [BER] ITU-T Rec. X.690 (07/2002) | ISO/IEC 8825-1:2002,
2287 "Information technology - ASN.1 encoding rules:
2288 Specification of Basic Encoding Rules (BER), Canonical
2289 Encoding Rules (CER) and Distinguished Encoding Rules
2292 [IP] Postel, J., "Internet Protocol", STD5 and RFC 791,
2295 [ISO10646] Universal Multiple-Octet Coded Character Set (UCS) -
2296 Architecture and Basic Multilingual Plane, ISO/IEC 10646-1
2299 [Keyword] Bradner, S., "Key words for use in RFCs to Indicate
2300 Requirement Levels", RFC 2119, March 1997.
2302 [LDAPDN] Zeilenga, K., "LDAP: String Representation of
2303 Distinguished Names", draft-ietf-ldapbis-dn-xx.txt, (a
2306 [LDAPIANA] Zeilenga, K., "IANA Considerations for LDAP", draft-ietf-
2307 ldapbis-bcp64-xx.txt, (a work in progress).
2309 [LDAPURL] Smith, M., "LDAP: Uniform Resource Locator", draft-ietf-
2310 ldapbis-url-xx.txt, (a work in progress).
2312 [Models] Zeilenga, K., "LDAP: Directory Information Models", draft-
2313 ietf-ldapbis-models-xx.txt (a work in progress).
2315 [Roadmap] Zeilenga, K., "LDAP: Technical Specification Road Map",
2316 draft-ietf-ldapbis-roadmap-xx.txt (a work in progress).
2318 [SASL] Melnikov, A., "Simple Authentication and Security Layer",
2319 draft-ietf-sasl-rfc2222bis-xx.txt (a work in progress).
2324 Sermersheim Internet-Draft - Expires Apr 2005 Page 40
2325 Lightweight Directory Access Protocol Version 3
2327 [SASLPrep] Zeilenga, K., "Stringprep profile for user names and
2328 passwords", draft-ietf-sasl-saslprep-xx.txt, (a work in
2331 [StringPrep] Hoffman P. and M. Blanchet, "Preparation of
2332 Internationalized Strings ('stringprep')", draft-hoffman-
2333 rfc3454bis-xx.txt, a work in progress.
2335 [Syntaxes] Legg, S., and K. Dally, "LDAP: Syntaxes and Matching
2336 Rules", draft-ietf-ldapbis-syntaxes-xx.txt, (a work in
2339 [TCP] Postel, J., "Transmission Control Protocol", STD7 and RFC
2342 [TLS] Dierks, T. and C. Allen. "The TLS Protocol Version 1.1",
2343 draft-ietf-tls-rfc2246-bis-xx.txt, a work in progress.
2345 [Unicode] The Unicode Consortium, "The Unicode Standard, Version
2346 3.2.0" is defined by "The Unicode Standard, Version 3.0"
2347 (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5),
2348 as amended by the "Unicode Standard Annex #27: Unicode
2349 3.1" (http://www.unicode.org/reports/tr27/) and by the
2350 "Unicode Standard Annex #28: Unicode 3.2"
2351 (http://www.unicode.org/reports/tr28/).
2353 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
2354 Resource Identifiers (URI): Generic Syntax", RFC 2396,
2357 [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
2358 10646", STD63 and RFC3629, November 2003.
2360 [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts,
2361 Models and Service", 1993.
2363 [X.501] ITU-T Rec. X.501, "The Directory: Models", 1993.
2365 [X.511] ITU-T Rec. X.511, "The Directory: Abstract Service
2369 9. Informative References
2371 [Glossary] The Unicode Consortium, "Unicode Glossary",
2372 <http://www.unicode.org/glossary/>.
2374 [CharModel] Whistler, K. and M. Davis, "Unicode Technical Report
2375 #17, Character Encoding Model", UTR17,
2376 <http://www.unicode.org/unicode/reports/tr17/>, August
2383 Sermersheim Internet-Draft - Expires Apr 2005 Page 41
2384 Lightweight Directory Access Protocol Version 3
2386 [PROTOS-LDAP] University of Oulu, "PROTOS Test-Suite: c06-ldapv3"
2387 <http://www.ee.oulu.fi/research/ouspg/protos/testing/c06/l
2390 [PortReg] IANA, "Port Numbers",
2391 http://www.iana.org/assignments/port-numbers
2394 10. IANA Considerations
2396 It is requested that the Internet Assigned Numbers Authority (IANA)
2397 update the LDAP result code registry to indicate that this document
2398 provides the definitive technical specification for result codes 0-
2399 36, 48-54, 64-70, 80-90.
2401 It is requested that the IANA update the LDAP Protocol Mechanism
2402 registry to indicate that this document and [AuthMeth] provides the
2403 definitive technical specification for the StartTLS
2404 (1.3.6.1.4.1.1466.20037) extended operation.
2406 It is requested that the IANA update the occurrence of "RFC XXXX" in
2407 Appendix B with this RFC number at publication.
2410 11. Editor's Address
2414 1800 South Novell Place
2415 Provo, Utah 84606, USA
2442 Sermersheim Internet-Draft - Expires Apr 2005 Page 42
2443 Lightweight Directory Access Protocol Version 3
2445 Appendix A - LDAP Result Codes
2447 This normative appendix details additional considerations regarding
2448 LDAP result codes and provides a brief, general description of each
2449 LDAP result code enumerated in Section 4.1.9.
2451 Additional result codes MAY be defined for use with extensions
2452 [LDAPIANA]. Client implementations SHALL treat any result code which
2453 they do not recognize as an unknown error condition.
2456 A.1 Non-Error Result Codes
2458 These result codes (called "non-error" result codes) do not indicate
2464 saslBindInProgress (14).
2466 The success, compareTrue, and compareFalse result codes indicate
2467 successful completion (and, hence, are referred to as "successful"
2470 The referral and saslBindInProgress result codes indicate the client
2471 is required to take additional action to complete the operation.
2476 Existing LDAP result codes are described as follows:
2479 Indicates the successful completion of an operation. Note:
2480 this code is not used with the compare operation. See
2481 compareFalse (5) and compareTrue (6).
2484 Indicates that the operation is not properly sequenced with
2485 relation to other operations (of same or different type).
2487 For example, this code is returned if the client attempts to
2488 StartTLS [TLS] while there are other uncompleted operations
2489 or if a TLS layer was already installed.
2492 Indicates the server received data which is not well-formed.
2494 For bind operation only, this code is also used to indicate
2495 that the server does not support the requested protocol
2501 Sermersheim Internet-Draft - Expires Apr 2005 Page 43
2502 Lightweight Directory Access Protocol Version 3
2504 For extended operations only, this code indicates that the
2505 server does not support (by design or configuration) the
2506 extended operation associated with the requestName.
2508 For request operations specifying multiple controls, this may
2509 be used to indicate that the server cannot ignore the order
2510 of the controls as specified, or that the combination of the
2511 specified controls is invalid or unspecified.
2513 timeLimitExceeded (3)
2514 Indicates that the time limit specified by the client was
2515 exceeded before the operation could be completed.
2517 sizeLimitExceeded (4)
2518 Indicates that the size limit specified by the client was
2519 exceeded before the operation could be completed.
2522 Indicates that the compare operation has successfully
2523 completed and the assertion has evaluated to FALSE or
2527 Indicates that the compare operation has successfully
2528 completed and the assertion has evaluated to TRUE.
2530 authMethodNotSupported (7)
2531 Indicates that the authentication method or mechanism is not
2534 strongAuthRequired (8)
2535 Indicates that the server has detected that an established
2536 security association between the client and server has
2537 unexpectedly failed or been compromised, or that the server
2538 now requires the client to authenticate using a strong(er)
2542 Indicates that a referral needs to be chased to complete the
2543 operation (see Section 4.1.10).
2545 adminLimitExceeded (11)
2546 Indicates that an administrative limit has been exceeded.
2548 unavailableCriticalExtension (12)
2549 Indicates a critical control is unrecognized (see Section
2552 confidentialityRequired (13)
2553 Indicates that data confidentiality protections are required.
2555 saslBindInProgress (14)
2560 Sermersheim Internet-Draft - Expires Apr 2005 Page 44
2561 Lightweight Directory Access Protocol Version 3
2563 Indicates the server requires the client to send a new bind
2564 request, with the same SASL mechanism, to continue the
2565 authentication process (see Section 4.2).
2567 noSuchAttribute (16)
2568 Indicates that the named entry does not contain the specified
2569 attribute or attribute value.
2571 undefinedAttributeType (17)
2572 Indicates that a request field contains an unrecognized
2573 attribute description.
2575 inappropriateMatching (18)
2576 Indicates that an attempt was made (e.g. in an assertion) to
2577 use a matching rule not defined for the attribute type
2580 constraintViolation (19)
2581 Indicates that the client supplied an attribute value which
2582 does not conform to the constraints placed upon it by the
2585 For example, this code is returned when multiple values are
2586 supplied to an attribute which has a SINGLE-VALUE constraint.
2588 attributeOrValueExists (20)
2589 Indicates that the client supplied an attribute or value to
2590 be added to an entry, but the attribute or value already
2593 invalidAttributeSyntax (21)
2594 Indicates that a purported attribute value does not conform
2595 to the syntax of the attribute.
2598 Indicates that the object does not exist in the DIT.
2601 Indicates that an alias problem has occurred. For example,
2602 the code may used to indicate an alias has been dereferenced
2603 which names no object.
2605 invalidDNSyntax (34)
2606 Indicates that an LDAPDN or RelativeLDAPDN field (e.g. search
2607 base, target entry, ModifyDN newrdn, etc.) of a request does
2608 not conform to the required syntax or contains attribute
2609 values which do not conform to the syntax of the attribute's
2612 aliasDereferencingProblem (36)
2613 Indicates that a problem occurred while dereferencing an
2614 alias. Typically an alias was encountered in a situation
2615 where it was not allowed or where access was denied.
2618 Sermersheim Internet-Draft - Expires Apr 2005 Page 45
2619 Lightweight Directory Access Protocol Version 3
2621 inappropriateAuthentication (48)
2622 Indicates the server requires the client which had attempted
2623 to bind anonymously or without supplying credentials to
2624 provide some form of credentials.
2626 invalidCredentials (49)
2627 Indicates that the provided credentials (e.g. the user's name
2628 and password) are invalid.
2630 insufficientAccessRights (50)
2631 Indicates that the client does not have sufficient access
2632 rights to perform the operation.
2635 Indicates that the server is too busy to service the
2639 Indicates that the server is shutting down or a subsystem
2640 necessary to complete the operation is offline.
2642 unwillingToPerform (53)
2643 Indicates that the server is unwilling to perform the
2647 Indicates that the server has detected an internal loop (e.g.
2648 while dereferencing aliases or chaining an operation).
2650 namingViolation (64)
2651 Indicates that the entry's name violates naming restrictions.
2653 objectClassViolation (65)
2654 Indicates that the entry violates object class restrictions.
2656 notAllowedOnNonLeaf (66)
2657 Indicates that the operation is inappropriately acting upon a
2660 notAllowedOnRDN (67)
2661 Indicates that the operation is inappropriately attempting to
2662 remove a value which forms the entry's relative distinguished
2665 entryAlreadyExists (68)
2666 Indicates that the request cannot be fulfilled (added, moved,
2667 or renamed) as the target entry already exists.
2669 objectClassModsProhibited (69)
2670 Indicates that an attempt to modify the object class(es) of
2671 an entry's 'objectClass' attribute is prohibited.
2673 For example, this code is returned when a client attempts to
2674 modify the structural object class of an entry.
2676 Sermersheim Internet-Draft - Expires Apr 2005 Page 46
2677 Lightweight Directory Access Protocol Version 3
2680 affectsMultipleDSAs (71)
2681 Indicates that the operation cannot be performed as it would
2682 affect multiple servers (DSAs).
2685 Indicates the server has encountered an internal error.
2735 Sermersheim Internet-Draft - Expires Apr 2005 Page 47
2736 Lightweight Directory Access Protocol Version 3
2738 Appendix B - Complete ASN.1 Definition
2740 This appendix is normative.
2742 Lightweight-Directory-Access-Protocol-V3
2743 -- Copyright (C) The Internet Society (2004). This version of
2744 -- this ASN.1 module is part of RFC XXXX; see the RFC itself
2745 -- for full legal notices.
2748 EXTENSIBILITY IMPLIED ::=
2752 LDAPMessage ::= SEQUENCE {
2753 messageID MessageID,
2755 bindRequest BindRequest,
2756 bindResponse BindResponse,
2757 unbindRequest UnbindRequest,
2758 searchRequest SearchRequest,
2759 searchResEntry SearchResultEntry,
2760 searchResDone SearchResultDone,
2761 searchResRef SearchResultReference,
2762 modifyRequest ModifyRequest,
2763 modifyResponse ModifyResponse,
2764 addRequest AddRequest,
2765 addResponse AddResponse,
2766 delRequest DelRequest,
2767 delResponse DelResponse,
2768 modDNRequest ModifyDNRequest,
2769 modDNResponse ModifyDNResponse,
2770 compareRequest CompareRequest,
2771 compareResponse CompareResponse,
2772 abandonRequest AbandonRequest,
2773 extendedReq ExtendedRequest,
2774 extendedResp ExtendedResponse,
2776 intermediateResponse IntermediateResponse },
2777 controls [0] Controls OPTIONAL }
2779 MessageID ::= INTEGER (0 .. maxInt)
2781 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
2783 LDAPString ::= OCTET STRING -- UTF-8 encoded,
2784 -- [ISO10646] characters
2786 LDAPOID ::= OCTET STRING -- Constrained to <numericoid> [Models]
2788 LDAPDN ::= LDAPString -- Constrained to <distinguishedName>
2791 RelativeLDAPDN ::= LDAPString -- Constrained to <name-component>
2793 Sermersheim Internet-Draft - Expires Apr 2005 Page 48
2794 Lightweight Directory Access Protocol Version 3
2798 AttributeDescription ::= LDAPString
2799 -- Constrained to <attributedescription>
2802 AttributeValue ::= OCTET STRING
2804 AttributeValueAssertion ::= SEQUENCE {
2805 attributeDesc AttributeDescription,
2806 assertionValue AssertionValue }
2808 AssertionValue ::= OCTET STRING
2810 PartialAttribute ::= SEQUENCE {
2811 type AttributeDescription,
2812 vals SET OF value AttributeValue }
2814 Attribute ::= PartialAttribute(WITH COMPONENTS {
2816 vals (SIZE(1..MAX))})
2818 MatchingRuleId ::= LDAPString
2820 LDAPResult ::= SEQUENCE {
2821 resultCode ENUMERATED {
2823 operationsError (1),
2825 timeLimitExceeded (3),
2826 sizeLimitExceeded (4),
2829 authMethodNotSupported (7),
2830 strongAuthRequired (8),
2833 adminLimitExceeded (11),
2834 unavailableCriticalExtension (12),
2835 confidentialityRequired (13),
2836 saslBindInProgress (14),
2837 noSuchAttribute (16),
2838 undefinedAttributeType (17),
2839 inappropriateMatching (18),
2840 constraintViolation (19),
2841 attributeOrValueExists (20),
2842 invalidAttributeSyntax (21),
2846 invalidDNSyntax (34),
2847 -- 35 reserved for undefined isLeaf --
2848 aliasDereferencingProblem (36),
2851 Sermersheim Internet-Draft - Expires Apr 2005 Page 49
2852 Lightweight Directory Access Protocol Version 3
2854 inappropriateAuthentication (48),
2855 invalidCredentials (49),
2856 insufficientAccessRights (50),
2859 unwillingToPerform (53),
2862 namingViolation (64),
2863 objectClassViolation (65),
2864 notAllowedOnNonLeaf (66),
2865 notAllowedOnRDN (67),
2866 entryAlreadyExists (68),
2867 objectClassModsProhibited (69),
2868 -- 70 reserved for CLDAP --
2869 affectsMultipleDSAs (71),
2874 diagnosticMessage LDAPString,
2875 referral [3] Referral OPTIONAL }
2877 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI
2879 URI ::= LDAPString -- limited to characters permitted in
2882 Controls ::= SEQUENCE OF control Control
2884 Control ::= SEQUENCE {
2885 controlType LDAPOID,
2886 criticality BOOLEAN DEFAULT FALSE,
2887 controlValue OCTET STRING OPTIONAL }
2889 BindRequest ::= [APPLICATION 0] SEQUENCE {
2890 version INTEGER (1 .. 127),
2892 authentication AuthenticationChoice }
2894 AuthenticationChoice ::= CHOICE {
2895 simple [0] OCTET STRING,
2897 sasl [3] SaslCredentials,
2900 SaslCredentials ::= SEQUENCE {
2901 mechanism LDAPString,
2902 credentials OCTET STRING OPTIONAL }
2904 BindResponse ::= [APPLICATION 1] SEQUENCE {
2905 COMPONENTS OF LDAPResult,
2906 serverSaslCreds [7] OCTET STRING OPTIONAL }
2909 Sermersheim Internet-Draft - Expires Apr 2005 Page 50
2910 Lightweight Directory Access Protocol Version 3
2912 UnbindRequest ::= [APPLICATION 2] NULL
2914 SearchRequest ::= [APPLICATION 3] SEQUENCE {
2920 derefAliases ENUMERATED {
2921 neverDerefAliases (0),
2922 derefInSearching (1),
2923 derefFindingBaseObj (2),
2925 sizeLimit INTEGER (0 .. maxInt),
2926 timeLimit INTEGER (0 .. maxInt),
2929 attributes AttributeSelection }
2931 AttributeSelection ::= SEQUENCE OF selector LDAPString
2932 -- The LDAPString is constrained to
2933 -- <attributeSelection> in Section 4.5.1
2936 and [0] SET OF filter Filter,
2937 or [1] SET OF filter Filter,
2939 equalityMatch [3] AttributeValueAssertion,
2940 substrings [4] SubstringFilter,
2941 greaterOrEqual [5] AttributeValueAssertion,
2942 lessOrEqual [6] AttributeValueAssertion,
2943 present [7] AttributeDescription,
2944 approxMatch [8] AttributeValueAssertion,
2945 extensibleMatch [9] MatchingRuleAssertion }
2947 SubstringFilter ::= SEQUENCE {
2948 type AttributeDescription,
2949 -- at least one must be present,
2950 -- initial and final can occur at most once
2951 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE {
2952 initial [0] AssertionValue,
2953 any [1] AssertionValue,
2954 final [2] AssertionValue } }
2956 MatchingRuleAssertion ::= SEQUENCE {
2957 matchingRule [1] MatchingRuleId OPTIONAL,
2958 type [2] AttributeDescription OPTIONAL,
2959 matchValue [3] AssertionValue,
2960 dnAttributes [4] BOOLEAN DEFAULT FALSE }
2962 SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
2964 attributes PartialAttributeList }
2967 Sermersheim Internet-Draft - Expires Apr 2005 Page 51
2968 Lightweight Directory Access Protocol Version 3
2970 PartialAttributeList ::= SEQUENCE OF
2971 partialAttribute PartialAttribute
2973 SearchResultReference ::= [APPLICATION 19] SEQUENCE
2974 SIZE (1..MAX) OF uri URI
2976 SearchResultDone ::= [APPLICATION 5] LDAPResult
2978 ModifyRequest ::= [APPLICATION 6] SEQUENCE {
2980 changes SEQUENCE OF change SEQUENCE {
2981 operation ENUMERATED {
2985 modification PartialAttribute } }
2987 ModifyResponse ::= [APPLICATION 7] LDAPResult
2989 AddRequest ::= [APPLICATION 8] SEQUENCE {
2991 attributes AttributeList }
2993 AttributeList ::= SEQUENCE OF attribute Attribute
2995 AddResponse ::= [APPLICATION 9] LDAPResult
2997 DelRequest ::= [APPLICATION 10] LDAPDN
2999 DelResponse ::= [APPLICATION 11] LDAPResult
3001 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
3003 newrdn RelativeLDAPDN,
3004 deleteoldrdn BOOLEAN,
3005 newSuperior [0] LDAPDN OPTIONAL }
3007 ModifyDNResponse ::= [APPLICATION 13] LDAPResult
3009 CompareRequest ::= [APPLICATION 14] SEQUENCE {
3011 ava AttributeValueAssertion }
3013 CompareResponse ::= [APPLICATION 15] LDAPResult
3015 AbandonRequest ::= [APPLICATION 16] MessageID
3017 ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
3018 requestName [0] LDAPOID,
3019 requestValue [1] OCTET STRING OPTIONAL }
3021 ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
3022 COMPONENTS OF LDAPResult,
3023 responseName [10] LDAPOID OPTIONAL,
3025 Sermersheim Internet-Draft - Expires Apr 2005 Page 52
3026 Lightweight Directory Access Protocol Version 3
3028 responseValue [11] OCTET STRING OPTIONAL }
3030 IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
3031 responseName [0] LDAPOID OPTIONAL,
3032 responseValue [1] OCTET STRING OPTIONAL }
3084 Sermersheim Internet-Draft - Expires Apr 2005 Page 53
3085 Lightweight Directory Access Protocol Version 3
3087 Appendix C - Changes
3089 This appendix is non-normative.
3091 This appendix summarizes substantive changes made to RFC 2251 and RFC
3095 C.1 Changes made to RFC 2251:
3097 This section summarizes the substantive changes made to Sections 1,
3098 2, 3.1, and 4 through the remainder of RFC 2251. Readers should
3099 consult [Models] and [AuthMeth] for summaries of changes to other
3105 - Removed IESG note. Post publication of RFC 2251, mandatory LDAP
3106 authentication mechanisms have been standardized which are
3107 sufficient to remove this note. See [AuthMeth] for authentication
3111 C.1.2 Section 3.1 and others
3113 - Removed notes giving history between LDAP v1, v2 and v3. Instead,
3114 added sufficient language so that this document can stand on its
3120 - Clarified where the extensibility features of ASN.1 apply to the
3121 protocol. This change also affected various ASN.1 types.
3122 - Removed the requirement that servers which implement version 3 or
3123 later MUST provide the 'supportedLDAPVersion' attribute. This
3124 statement provided no interoperability advantages.
3129 - There was a mandatory requirement for the server to return a
3130 Notice of Disconnection and drop the connection when a PDU is
3131 malformed in a certain way. This has been clarified such that the
3132 server SHOULD return the Notice of Disconnection, and MUST drop
3136 C.1.5 Section 4.1.1.1
3138 - Clarified that the messageID of requests MUST be non-zero.
3143 Sermersheim Internet-Draft - Expires Apr 2005 Page 54
3144 Lightweight Directory Access Protocol Version 3
3146 - Clarified when it is and isn't appropriate to return an already
3147 used message id. RFC 2251 accidentally imposed synchronous server
3148 behavior in its wording of this.
3153 - Stated that LDAPOID is constrained to <numericoid> from [Models].
3156 C.1.7 Section 4.1.5.1 and others
3158 - Removed the Binary Option from the specification. There are
3159 numerous interoperability problems associated with this method of
3160 alternate attribute type encoding. Work to specify a suitable
3161 replacement is ongoing.
3166 - Combined the definitions of PartialAttribute and Attribute here,
3167 and defined Attribute in terms of PartialAttribute.
3170 C.1.9 Section 4.1.10
3172 - Renamed "errorMessage" to "diagnosticMessage" as it is allowed to
3173 be sent for non-error results.
3174 - Moved some language into Appendix A, and refer the reader there.
3175 - Allowed matchedDN to be present for other result codes than those
3179 C.1.10 Section 4.1.11
3181 - Defined referrals in terms of URIs rather than URLs.
3182 - Removed the requirement that all referral URIs MUST be equally
3183 capable of progressing the operation. The statement was ambiguous
3184 and provided no instructions on how to carry it out.
3185 - Added the requirement that clients MUST NOT loop between servers.
3186 - Clarified the instructions for using LDAPURLs in referrals, and in
3187 doing so added a recommendation that the scope part be present.
3190 C.1.11 Section 4.1.12
3192 - Specified how control values defined in terms of ASN.1 are to be
3194 - Noted that the criticality field is only applied to request
3195 messages (except unbindRequest), and must be ignored when present
3196 on response messages and unbindRequest.
3197 - Added language regarding combinations of controls and the ordering
3198 of controls on a message.
3202 Sermersheim Internet-Draft - Expires Apr 2005 Page 55
3203 Lightweight Directory Access Protocol Version 3
3205 - Specified that when the semantics of the combination of controls
3206 is undefined or unknown, it results in a protocolError.
3207 - Changed "The server MUST be prepared" to "Implementations MUST be
3208 prepared" in the eighth paragraph to reflect that both client and
3209 server implementations must be able to handle this (as both parse
3215 - Mandated that servers return protocolError when the version is not
3217 - Clarified behavior when the simple authentication is used, the
3218 name is empty and the password is non-empty.
3219 - Required servers to not dereference aliases for bind. This was
3220 added for consistency with other operations and to help ensure
3222 - Required that textual passwords be transferred as UTF-8 encoded
3223 Unicode, and added recommendations on string preparation. This was
3224 to help ensure interoperability of passwords being sent from
3228 C.1.13 Section 4.2.1
3230 - This section was largely reorganized for readability and language
3231 was added to clarify the authentication state of failed and
3232 abandoned bind operations.
3233 - Removed: "If a SASL transfer encryption or integrity mechanism has
3234 been negotiated, that mechanism does not support the changing of
3235 credentials from one identity to another, then the client MUST
3236 instead establish a new connection."
3237 Each SASL negotiation is, generally, independent of other SASL
3238 negotiations. If there were dependencies between multiple
3239 negotiations of a particular mechanism, the mechanism technical
3240 specification should detail how applications are to deal with
3241 them. LDAP should not require any special handling. And if an LDAP
3242 client had used such a mechanism, it would have the option of
3243 using another mechanism.
3244 - Dropped MUST imperative in paragraph 3 to align with [Keywords].
3245 - Mandated that clients not send non-bind operations while a bind is
3246 in progress, and suggested that servers not process them if they
3247 are received. This is needed to ensure proper sequencing of the
3248 bind in relationship to other operations.
3251 C.1.14 Section 4.2.3
3253 - Moved most error-related text to Appendix A, and added text
3254 regarding certain errors used in conjunction with the bind
3256 - Prohibited the server from specifying serverSaslCreds when not
3260 Sermersheim Internet-Draft - Expires Apr 2005 Page 56
3261 Lightweight Directory Access Protocol Version 3
3266 - Required both peers to cease transmission and close the LDAP
3267 exchange for the unbind operation.
3272 - Added instructions for future specifications of Unsolicited
3276 C.1.17 Section 4.5.1
3278 - SearchRequest attributes is now defined as an AttributeSelection
3279 type rather than AttributeDescriptionList, and an ABNF is
3281 - SearchRequest attributes may contain duplicate attribute
3282 descriptions. This was previously prohibited. Now servers are
3283 instructed to ignore subsequent names when they are duplicated.
3284 This was relaxed in order to allow different short names and also
3285 OIDs to be requested for an attribute.
3286 - The Filter choice SubstringFilter substrings type is now defined
3287 with a lower bound of 1.
3288 - The SubstringFilter substrings 'initial, 'any', and 'final' types
3289 are now AssertionValue rather than LDAPString. Also, added
3290 imperatives stating that 'initial' (if present) must be listed
3291 first, and 'final' (if present) must be listed last.
3292 - Clarified the semantics of the derefAliases choices.
3293 - Added instructions for equalityMatch, substrings, greaterOrEqual,
3294 lessOrEqual, and approxMatch.
3297 C.1.18 Section 4.5.2
3299 - Recommended that servers not use attribute short names when it
3300 knows they are ambiguous or may cause interoperability problems.
3301 - Removed all mention of ExtendedResponse due to lack of
3305 C.1.19 Section 4.5.3
3307 - Made changes similar to those made to Section 4.1.11.
3310 C.1.20 Section 4.5.3.1
3312 - Fixed examples to adhere to changes made to Section 4.5.3.
3318 Sermersheim Internet-Draft - Expires Apr 2005 Page 57
3319 Lightweight Directory Access Protocol Version 3
3321 - Removed restriction that required an EQUALITY matching rule in
3322 order to perform value delete modifications. It is sufficiently
3323 documented that in absence of an equality matching rule, octet
3325 - Replaced AttributeTypeAndValues with Attribute as they are
3327 - Clarified what type of modification changes might temporarily
3333 - Aligned Add operation with X.511 in that the attributes of the RDN
3334 are used in conjunction with the listed attributes to create the
3335 entry. Previously, Add required that the distinguished values be
3336 present in the listed attributes.
3341 - Required servers to not dereference aliases for modify DN. This
3342 was added for consistency with other operations and to help ensure
3344 - Allow modify DN to fail when moving between naming contexts.
3345 - Specified what happens when the attributes of the newrdn are no
3346 present on the entry.
3351 - Clarified that compareFalse means that the compare took place and
3352 the result is false. There was confusion which lead people to
3353 believe that an Undefined match resulted in compareFalse.
3354 - Required servers to not dereference aliases for compare. This was
3355 added for consistency with other operations and to help ensure
3361 - Explained that since abandon returns no response, clients should
3362 not use it if they need to know the outcome.
3363 - Specified that Abandon and Unbind cannot be abandoned.
3368 - Specified how values of extended operations defined in terms of
3369 ASN.1 are to be encoded.
3370 - Added instructions on what extended operation specifications
3372 - Added a recommendation that servers advertise supported extended
3376 Sermersheim Internet-Draft - Expires Apr 2005 Page 58
3377 Lightweight Directory Access Protocol Version 3
3382 - Moved referral-specific instructions into referral-related
3388 - Reworded notes regarding SASL not protecting certain aspects of
3390 - Noted that Servers are encouraged to prevent directory
3391 modifications by clients that have authenticated anonymously
3393 - Added a note regarding the scenario where an identity is changed
3394 (deleted, privileges or credentials modified, etc.).
3395 - Warned against following referrals that may have been injected in
3397 - Noted that servers should protect information equally, whether in
3398 an error condition or not, and mentioned specifically; matchedDN,
3399 diagnosticMessage, and resultCodes.
3400 - Added a note regarding malformed and long encodings.
3405 - Added "EXTENSIBILITY IMPLIED" to ASN.1 definition.
3406 - Removed AttributeType. It is not used.
3409 C.2 Changes made to RFC 2830:
3411 This section summarizes the substantive changes made to Sections of
3412 RFC 2830. Readers should consult [AuthMeth] for summaries of changes
3418 - Removed wording indicating that referrals can be returned from
3420 - Removed requirement that only a narrow set of result codes can be
3421 returned. Some result codes are required in certain scenarios, but
3422 any other may be returned if appropriate.
3425 C.2.1 Section 4.13.3.1
3427 - Reworded most of this section and added the requirement that after
3428 the TLS connection has been closed, the server MUST NOT send
3429 responses to any request message received before the TLS closure.
3432 C.3 Changes made to RFC 3771:
3434 Sermersheim Internet-Draft - Expires Apr 2005 Page 59
3435 Lightweight Directory Access Protocol Version 3
3438 - In general, all technical language was transferred in whole.
3439 Supporting and background language seen as redundant due to its
3440 presence in this document was omitted.
3493 Sermersheim Internet-Draft - Expires Apr 2005 Page 60
3494 Lightweight Directory Access Protocol Version 3
3499 Intellectual Property Statement
3501 The IETF takes no position regarding the validity or scope of any
3502 Intellectual Property Rights or other rights that might be claimed to
3503 pertain to the implementation or use of the technology described in
3504 this document or the extent to which any license under such rights
3505 might or might not be available; nor does it represent that it has
3506 made any independent effort to identify any such rights. Information
3507 on the procedures with respect to rights in RFC documents can be
3508 found in BCP 78 and BCP 79.
3510 Copies of IPR disclosures made to the IETF Secretariat and any
3511 assurances of licenses to be made available, or the result of an
3512 attempt made to obtain a general license or permission for the use of
3513 such proprietary rights by implementers or users of this
3514 specification can be obtained from the IETF on-line IPR repository at
3515 <http://www.ietf.org/ipr>.
3517 The IETF invites any interested party to bring to its attention any
3518 copyrights, patents or patent applications, or other proprietary
3519 rights that may cover technology that may be required to implement
3520 this standard. Please address the information to the IETF at ietf-
3523 Disclaimer of Validity
3525 This document and the information contained herein are provided on an
3526 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
3527 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
3528 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
3529 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
3530 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
3531 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
3535 Copyright (C) The Internet Society (2004). This document is subject
3536 to the rights, licenses and restrictions contained in BCP 78, and
3537 except as set forth therein, the authors retain all their rights.
3541 Funding for the RFC Editor function is currently provided by the
3552 Sermersheim Internet-Draft - Expires Apr 2005 Page 61
projects / openldap / blob