2 Internet-Draft Editor: J. Sermersheim
3 Intended Category: Standard Track Novell, Inc
4 Document: draft-ietf-ldapbis-protocol-31.txt May 2005
5 Obsoletes: RFCs 2251, 2830, 3771
13 This document is an Internet-Draft and is subject to all provisions
14 of section 3 of RFC 3667. By submitting this Internet-Draft, each
15 author represents that any applicable patent or other IPR claims of
16 which he or she is aware have been or will be disclosed, and any of
17 which he or she becomes aware will be disclosed, in accordance with
20 Internet-Drafts are working documents of the Internet Engineering
21 Task Force (IETF), its areas, and its working groups. Note that other
22 groups may also distribute working documents as Internet-Drafts.
24 Internet-Drafts are draft documents valid for a maximum of six months
25 and may be updated, replaced, or obsoleted by other documents at any
26 time. It is inappropriate to use Internet-Drafts as reference
27 material or to cite them other than as "work in progress".
29 The list of current Internet-Drafts can be accessed at
30 <http://www.ietf.org/ietf/1id-abstracts.txt>.
32 The list of Internet-Draft Shadow Directories can be accessed at
33 <http://www.ietf.org/shadow.html>.
35 This Internet-Draft will expire in November 2005.
37 Technical discussion of this document will take place on the IETF
38 LDAP Revision Working Group (LDAPbis) mailing list <ietf-
39 ldapbis@openldap.org>. Please send editorial comments directly to the
40 editor <jimse@novell.com>.
45 Copyright (C) The Internet Society (2005). All Rights Reserved.
49 This document describes the protocol elements, along with their
50 semantics and encodings, of the Lightweight Directory Access Protocol
51 (LDAP). LDAP provides access to distributed directory services that
52 act in accordance with X.500 data and service models. These protocol
53 elements are based on those described in the X.500 Directory Access
57 Sermersheim Internet-Draft - Expires Nov 2005 Page 1
59 Lightweight Directory Access Protocol Version 3
64 1. Introduction....................................................3
65 1.1. Relationship to Other LDAP Specifications.....................3
66 2. Conventions.....................................................3
67 3. Protocol Model..................................................4
68 3.1 Operation and LDAP Message Layer Relationship..................5
69 4. Elements of Protocol............................................5
70 4.1. Common Elements...............................................5
71 4.1.1. Message Envelope............................................5
72 4.1.2. String Types................................................7
73 4.1.3. Distinguished Name and Relative Distinguished Name..........7
74 4.1.4. Attribute Descriptions......................................8
75 4.1.5. Attribute Value.............................................8
76 4.1.6. Attribute Value Assertion...................................8
77 4.1.7. Attribute and PartialAttribute..............................9
78 4.1.8. Matching Rule Identifier....................................9
79 4.1.9. Result Message..............................................9
80 4.1.10. Referral..................................................11
81 4.1.11. Controls..................................................13
82 4.2. Bind Operation...............................................14
83 4.3. Unbind Operation.............................................17
84 4.4. Unsolicited Notification.....................................17
85 4.5. Search Operation.............................................18
86 4.6. Modify Operation.............................................29
87 4.7. Add Operation................................................31
88 4.8. Delete Operation.............................................31
89 4.9. Modify DN Operation..........................................32
90 4.10. Compare Operation...........................................33
91 4.11. Abandon Operation...........................................34
92 4.12. Extended Operation..........................................35
93 4.13. IntermediateResponse Message................................36
94 4.14. StartTLS Operation..........................................37
95 5. Protocol Encoding, Connection, and Transfer....................39
96 5.1. Protocol Encoding............................................39
97 5.2. Transmission Control Protocol (TCP)..........................40
98 5.3. Termination of the LDAP session..............................40
99 6. Security Considerations........................................40
100 7. Acknowledgements...............................................42
101 8. Normative References...........................................42
102 9. Informative References.........................................44
103 10. IANA Considerations...........................................44
104 11. Editor's Address..............................................45
105 Appendix A - LDAP Result Codes....................................46
106 A.1 Non-Error Result Codes........................................46
107 A.2 Result Codes..................................................46
108 Appendix B - Complete ASN.1 Definition............................51
109 Appendix C - Changes..............................................57
110 C.1 Changes made to RFC 2251:.....................................57
111 C.2 Changes made to RFC 2830:.....................................62
112 C.3 Changes made to RFC 3771:.....................................63
116 Sermersheim Internet-Draft - Expires Nov 2005 Page 2
118 Lightweight Directory Access Protocol Version 3
122 The Directory is "a collection of open systems cooperating to provide
123 directory services" [X.500]. A directory user, which may be a human
124 or other entity, accesses the Directory through a client (or
125 Directory User Agent (DUA)). The client, on behalf of the directory
126 user, interacts with one or more servers (or Directory System Agents
127 (DSA)). Clients interact with servers using a directory access
130 This document details the protocol elements of the Lightweight
131 Directory Access Protocol (LDAP), along with their semantics.
132 Following the description of protocol elements, it describes the way
133 in which the protocol elements are encoded and transferred.
136 1.1. Relationship to Other LDAP Specifications
138 This document is an integral part of the LDAP Technical Specification
139 [Roadmap] which obsoletes the previously defined LDAP technical
140 specification, RFC 3377, in its entirety.
142 This document, together with [Roadmap], [AuthMeth], and [Models],
143 obsoletes RFC 2251 in its entirety. Section 3.3 is obsoleted by
144 [Roadmap]. Sections 4.2.1 (portions), and 4.2.2 are obsoleted by
145 [AuthMeth]. Sections 3.2, 3.4, 4.1.3 (last paragraph), 4.1.4, 4.1.5,
146 4.1.5.1, 4.1.9 (last paragraph), 5.1, 6.1, and 6.2 (last paragraph)
147 are obsoleted by [Models]. The remainder of RFC 2251 is obsoleted by
148 this document. Appendix C.1 summarizes substantive changes in the
151 This document obsoletes RFC 2830, Sections 2 and 4. The remainder of
152 RFC 2830 is obsoleted by [AuthMeth]. Appendix C.2 summarizes
153 substantive changes to the remaining sections.
155 This document also obsoletes RFC 3771 in entirety.
160 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
161 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
162 to be interpreted as described in [Keyword].
164 Character names in this document use the notation for code points and
165 names from the Unicode Standard [Unicode]. For example, the letter
166 "a" may be represented as either <U+0061> or <LATIN SMALL LETTER A>.
168 Note: a glossary of terms used in Unicode can be found in [Glossary].
169 Information on the Unicode character encoding model can be found in
175 Sermersheim Internet-Draft - Expires Nov 2005 Page 3
177 Lightweight Directory Access Protocol Version 3
179 The term "transport connection" refers to the underlying transport
180 services used to carry the protocol exchange, as well as associations
181 established by these services.
183 The term "TLS layer" refers to TLS services used in providing
184 security services, as well as associations established by these
187 The term "SASL layer" refers to SASL services used in providing
188 security services, as well as associations established by these
191 The term "LDAP message layer" refers to the LDAP Message Protocol
192 Data Unit (PDU) services used in providing directory services, as
193 well as associations established by these services.
195 The term "LDAP session" refers to combined services (transport
196 connection, TLS layer, SASL layer, LDAP message layer) and their
199 See the table in Section 5 for an illustration of these four terms.
204 The general model adopted by this protocol is one of clients
205 performing protocol operations against servers. In this model, a
206 client transmits a protocol request describing the operation to be
207 performed to a server. The server is then responsible for performing
208 the necessary operation(s) in the Directory. Upon completion of an
209 operation, the server typically returns a response containing
210 appropriate data to the requesting client.
212 Protocol operations are generally independent of one another. Each
213 operation is processed as an atomic action, leaving the directory in
216 Although servers are required to return responses whenever such
217 responses are defined in the protocol, there is no requirement for
218 synchronous behavior on the part of either clients or servers.
219 Requests and responses for multiple operations generally may be
220 exchanged between a client and server in any order. If required,
221 synchronous behavior may be controlled by client applications.
223 The core protocol operations defined in this document can be mapped
224 to a subset of the X.500 (1993) Directory Abstract Service [X.511].
225 However there is not a one-to-one mapping between LDAP operations and
226 X.500 Directory Access Protocol (DAP) operations. Server
227 implementations acting as a gateway to X.500 directories may need to
228 make multiple DAP requests to service a single LDAP request.
234 Sermersheim Internet-Draft - Expires Nov 2005 Page 4
236 Lightweight Directory Access Protocol Version 3
239 3.1 Operation and LDAP Message Layer Relationship
241 Protocol operations are exchanged at the LDAP message layer. When the
242 transport connection is closed, any uncompleted operations at the
243 LDAP message layer, when possible, are abandoned, and when not
244 possible, are completed without transmission of the response. Also,
245 when the transport connection is closed, the client MUST NOT assume
246 that any uncompleted update operations have succeeded or failed.
249 4. Elements of Protocol
251 The protocol is described using Abstract Syntax Notation One
252 ([ASN.1]), and is transferred using a subset of ASN.1 Basic Encoding
253 Rules ([BER]). Section 5 specifies how the protocol elements are
254 encoded and transferred.
256 In order to support future extensions to this protocol, extensibility
257 is implied where it is allowed per ASN.1 (i.e. sequence, set, choice,
258 and enumerated types are extensible). In addition, ellipses (...)
259 have been supplied in ASN.1 types that are explicitly extensible as
260 discussed in [LDAPIANA]. Because of the implied extensibility,
261 clients and servers MUST (unless otherwise specified) ignore trailing
262 SEQUENCE components whose tags they do not recognize.
264 Changes to the protocol other than through the extension mechanisms
265 described here require a different version number. A client indicates
266 the version it is using as part of the BindRequest, described in
267 Section 4.2. If a client has not sent a Bind, the server MUST assume
268 the client is using version 3 or later.
270 Clients may attempt to determine the protocol versions a server
271 supports by reading the 'supportedLDAPVersion' attribute from the
272 root DSE (DSA-Specific Entry) [Models].
277 This section describes the LDAPMessage envelope Protocol Data Unit
278 (PDU) format, as well as data type definitions, which are used in the
282 4.1.1. Message Envelope
284 For the purposes of protocol exchanges, all protocol operations are
285 encapsulated in a common envelope, the LDAPMessage, which is defined
293 Sermersheim Internet-Draft - Expires Nov 2005 Page 5
295 Lightweight Directory Access Protocol Version 3
297 LDAPMessage ::= SEQUENCE {
300 bindRequest BindRequest,
301 bindResponse BindResponse,
302 unbindRequest UnbindRequest,
303 searchRequest SearchRequest,
304 searchResEntry SearchResultEntry,
305 searchResDone SearchResultDone,
306 searchResRef SearchResultReference,
307 modifyRequest ModifyRequest,
308 modifyResponse ModifyResponse,
309 addRequest AddRequest,
310 addResponse AddResponse,
311 delRequest DelRequest,
312 delResponse DelResponse,
313 modDNRequest ModifyDNRequest,
314 modDNResponse ModifyDNResponse,
315 compareRequest CompareRequest,
316 compareResponse CompareResponse,
317 abandonRequest AbandonRequest,
318 extendedReq ExtendedRequest,
319 extendedResp ExtendedResponse,
321 intermediateResponse IntermediateResponse },
322 controls [0] Controls OPTIONAL }
324 MessageID ::= INTEGER (0 .. maxInt)
326 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
328 The ASN.1 type Controls is defined in Section 4.1.11.
330 The function of the LDAPMessage is to provide an envelope containing
331 common fields required in all protocol exchanges. At this time the
332 only common fields are the messageID and the controls.
334 If the server receives an LDAPMessage from the client in which the
335 LDAPMessage SEQUENCE tag cannot be recognized, the messageID cannot
336 be parsed, the tag of the protocolOp is not recognized as a request,
337 or the encoding structures or lengths of data fields are found to be
338 incorrect, then the server SHOULD return the Notice of Disconnection
339 described in Section 4.4.1, with the resultCode set to protocolError,
340 and MUST immediately terminate the LDAP session as described in
343 In other cases where the client or server cannot parse an LDAP PDU,
344 it SHOULD abruptly terminate the LDAP session (Section 5.3) where
345 further communication (including providing notice) would be
346 pernicious. Otherwise, server implementations MUST return an
347 appropriate response to the request, with the resultCode set to
352 Sermersheim Internet-Draft - Expires Nov 2005 Page 6
354 Lightweight Directory Access Protocol Version 3
358 All LDAPMessage envelopes encapsulating responses contain the
359 messageID value of the corresponding request LDAPMessage.
361 The message ID of a request MUST have a non-zero value different from
362 the messageID of any other request in progress in the same LDAP
363 session. The zero value is reserved for the unsolicited notification
366 Typical clients increment a counter for each request.
368 A client MUST NOT send a request with the same message ID as an
369 earlier request in the same LDAP session unless it can be determined
370 that the server is no longer servicing the earlier request (e.g.
371 after the final response is received, or a subsequent Bind
372 completes). Otherwise the behavior is undefined. For this purpose,
373 note that Abandon and successfully abandoned operations do not send
379 The LDAPString is a notational convenience to indicate that, although
380 strings of LDAPString type encode as ASN.1 OCTET STRING types, the
381 [ISO10646] character set (a superset of [Unicode]) is used, encoded
382 following the [UTF-8] algorithm. Note that Unicode characters U+0000
383 through U+007F are the same as ASCII 0 through 127, respectively, and
384 have the same single octet UTF-8 encoding. Other Unicode characters
385 have a multiple octet UTF-8 encoding.
387 LDAPString ::= OCTET STRING -- UTF-8 encoded,
388 -- [ISO10646] characters
390 The LDAPOID is a notational convenience to indicate that the
391 permitted value of this string is a (UTF-8 encoded) dotted-decimal
392 representation of an OBJECT IDENTIFIER. Although an LDAPOID is
393 encoded as an OCTET STRING, values are limited to the definition of
394 <numericoid> given in Section 1.4 of [Models].
396 LDAPOID ::= OCTET STRING -- Constrained to <numericoid> [Models]
400 1.3.6.1.4.1.1466.1.2.3
403 4.1.3. Distinguished Name and Relative Distinguished Name
405 An LDAPDN is defined to be the representation of a Distinguished Name
406 (DN) after encoding according to the specification in [LDAPDN].
408 LDAPDN ::= LDAPString
409 -- Constrained to <distinguishedName> [LDAPDN]
411 Sermersheim Internet-Draft - Expires Nov 2005 Page 7
413 Lightweight Directory Access Protocol Version 3
416 A RelativeLDAPDN is defined to be the representation of a Relative
417 Distinguished Name (RDN) after encoding according to the
418 specification in [LDAPDN].
420 RelativeLDAPDN ::= LDAPString
421 -- Constrained to <name-component> [LDAPDN]
424 4.1.4. Attribute Descriptions
426 The definition and encoding rules for attribute descriptions are
427 defined in Section 2.5 of [Models]. Briefly, an attribute description
428 is an attribute type and zero or more options.
430 AttributeDescription ::= LDAPString
431 -- Constrained to <attributedescription>
435 4.1.5. Attribute Value
437 A field of type AttributeValue is an OCTET STRING containing an
438 encoded attribute value. The attribute value is encoded according to
439 the LDAP-specific encoding definition of its corresponding syntax.
440 The LDAP-specific encoding definitions for different syntaxes and
441 attribute types may be found in other documents and in particular
444 AttributeValue ::= OCTET STRING
446 Note that there is no defined limit on the size of this encoding;
447 thus protocol values may include multi-megabyte attribute values
450 Attribute values may be defined which have arbitrary and non-
451 printable syntax. Implementations MUST NOT display nor attempt to
452 decode an attribute value if its syntax is not known. The
453 implementation may attempt to discover the subschema of the source
454 entry, and retrieve the descriptions of 'attributeTypes' from it
457 Clients MUST only send attribute values in a request that are valid
458 according to the syntax defined for the attributes.
461 4.1.6. Attribute Value Assertion
463 The AttributeValueAssertion (AVA) type definition is similar to the
464 one in the X.500 Directory standards. It contains an attribute
465 description and a matching rule ([Models] Section 4.1.3) assertion
466 value suitable for that type. Elements of this type are typically
467 used to assert that the value in assertionValue matches a value of an
470 Sermersheim Internet-Draft - Expires Nov 2005 Page 8
472 Lightweight Directory Access Protocol Version 3
475 AttributeValueAssertion ::= SEQUENCE {
476 attributeDesc AttributeDescription,
477 assertionValue AssertionValue }
479 AssertionValue ::= OCTET STRING
481 The syntax of the AssertionValue depends on the context of the LDAP
482 operation being performed. For example, the syntax of the EQUALITY
483 matching rule for an attribute is used when performing a Compare
484 operation. Often this is the same syntax used for values of the
485 attribute type, but in some cases the assertion syntax differs from
486 the value syntax. See objectIdentiferFirstComponentMatch in
487 [Syntaxes] for an example.
490 4.1.7. Attribute and PartialAttribute
492 Attributes and partial attributes consist of an attribute description
493 and attribute values. A PartialAttribute allows zero values, while
494 Attribute requires at least one value.
496 PartialAttribute ::= SEQUENCE {
497 type AttributeDescription,
498 vals SET OF value AttributeValue }
500 Attribute ::= PartialAttribute(WITH COMPONENTS {
502 vals (SIZE(1..MAX))})
504 No two of the attribute values may be equivalent as described by
505 Section 2.3 of [Models]. The set of attribute values is unordered.
506 Implementations MUST NOT rely upon the ordering being repeatable.
509 4.1.8. Matching Rule Identifier
511 Matching rules are defined in Section 4.1.3 of [Models]. A matching
512 rule is identified in the protocol by the printable representation of
513 either its <numericoid>, or one of its short name descriptors
514 [Models], e.g. 'caseIgnoreMatch' or '2.5.13.2'.
516 MatchingRuleId ::= LDAPString
519 4.1.9. Result Message
521 The LDAPResult is the construct used in this protocol to return
522 success or failure indications from servers to clients. To various
523 requests, servers will return responses containing the elements found
524 in LDAPResult to indicate the final status of the protocol operation
529 Sermersheim Internet-Draft - Expires Nov 2005 Page 9
531 Lightweight Directory Access Protocol Version 3
533 LDAPResult ::= SEQUENCE {
534 resultCode ENUMERATED {
538 timeLimitExceeded (3),
539 sizeLimitExceeded (4),
542 authMethodNotSupported (7),
543 strongerAuthRequired (8),
546 adminLimitExceeded (11),
547 unavailableCriticalExtension (12),
548 confidentialityRequired (13),
549 saslBindInProgress (14),
550 noSuchAttribute (16),
551 undefinedAttributeType (17),
552 inappropriateMatching (18),
553 constraintViolation (19),
554 attributeOrValueExists (20),
555 invalidAttributeSyntax (21),
559 invalidDNSyntax (34),
560 -- 35 reserved for undefined isLeaf --
561 aliasDereferencingProblem (36),
563 inappropriateAuthentication (48),
564 invalidCredentials (49),
565 insufficientAccessRights (50),
568 unwillingToPerform (53),
571 namingViolation (64),
572 objectClassViolation (65),
573 notAllowedOnNonLeaf (66),
574 notAllowedOnRDN (67),
575 entryAlreadyExists (68),
576 objectClassModsProhibited (69),
577 -- 70 reserved for CLDAP --
578 affectsMultipleDSAs (71),
583 diagnosticMessage LDAPString,
584 referral [3] Referral OPTIONAL }
588 Sermersheim Internet-Draft - Expires Nov 2005 Page 10
590 Lightweight Directory Access Protocol Version 3
592 The resultCode enumeration is extensible as defined in Section 3.6 of
593 [LDAPIANA]. The meanings of the listed result codes are given in
594 Appendix A. If a server detects multiple errors for an operation,
595 only one result code is returned. The server should return the result
596 code that best indicates the nature of the error encountered.
598 The diagnosticMessage field of this construct may, at the server's
599 option, be used to return a string containing a textual, human-
600 readable (terminal control and page formatting characters should be
601 avoided) diagnostic message. As this diagnostic message is not
602 standardized, implementations MUST NOT rely on the values returned.
603 Diagnostic messages typically supplement the resultCode with
604 additional information. If the server chooses not to return a textual
605 diagnostic, the diagnosticMessage field MUST be empty.
607 For certain result codes (typically, but not restricted to
608 noSuchObject, aliasProblem, invalidDNSyntax and
609 aliasDereferencingProblem), the matchedDN field is set (subject to
610 access controls) to the name of the last entry (object or alias) used
611 in finding the target (or base) object. This will be a truncated form
612 of the provided name or, if an alias was dereferenced while
613 attempting to locate the entry, of the resulting name. Otherwise the
614 matchedDN field is empty.
619 The referral result code indicates that the contacted server cannot
620 or will not perform the operation and that one or more other servers
621 may be able to. Reasons for this include:
623 - The target entry of the request is not held locally, but the
624 server has knowledge of its possible existence elsewhere.
626 - The operation is restricted on this server -- perhaps due to a
627 read-only copy of an entry to be modified.
629 The referral field is present in an LDAPResult if the resultCode is
630 set to referral, and absent with all other result codes. It contains
631 one or more references to one or more servers or services that may be
632 accessed via LDAP or other protocols. Referrals can be returned in
633 response to any operation request (except Unbind and Abandon which do
634 not have responses). At least one URI MUST be present in the
637 During a Search operation, after the baseObject is located, and
638 entries are being evaluated, the referral is not returned. Instead,
639 continuation references, described in Section 4.5.3, are returned
640 when other servers would need to be contacted to complete the
643 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI
647 Sermersheim Internet-Draft - Expires Nov 2005 Page 11
649 Lightweight Directory Access Protocol Version 3
651 URI ::= LDAPString -- limited to characters permitted in
654 If the client wishes to progress the operation, it contacts one of
655 the supported services found in the referral. If multiple URIs are
656 present, the client assumes that any supported URI may be used to
657 progress the operation.
659 Clients that follow referrals MUST ensure that they do not loop
660 between servers. They MUST NOT repeatedly contact the same server for
661 the same request with the same parameters. Some clients use a counter
662 that is incremented each time referral handling occurs for an
663 operation, and these kinds of clients MUST be able to handle at least
664 ten nested referrals while progressing the operation.
666 A URI for a server implementing LDAP and accessible via [TCP]/[IP]
667 (v4 or v6) is written as an LDAP URL according to [LDAPURL].
669 Referral values which are LDAP URLs follow these rules:
671 - If an alias was dereferenced, the <dn> part of the LDAP URL MUST
672 be present, with the new target object name.
674 - It is RECOMMENDED that the <dn> part be present to avoid
677 - If the <dn> part is present, the client uses this name in its next
678 request to progress the operation, and if it is not present the
679 client uses the same name as in the original request.
681 - Some servers (e.g. participating in distributed indexing) may
682 provide a different filter in a URL of a referral for a Search
685 - If the <filter> part of the LDAP URL is present, the client uses
686 this filter in its next request to progress this Search, and if it
687 is not present the client uses the same filter as it used for that
690 - For Search, it is RECOMMENDED that the <scope> part be present to
693 - If the <scope> part is missing, the scope of the original Search
694 is used by the client to progress the operation.
696 - Other aspects of the new request may be the same as or different
697 from the request which generated the referral.
699 Other kinds of URIs may be returned. The syntax and semantics of such
700 URIs is left to future specifications. Clients may ignore URIs that
706 Sermersheim Internet-Draft - Expires Nov 2005 Page 12
708 Lightweight Directory Access Protocol Version 3
710 UTF-8 encoded characters appearing in the string representation of a
711 DN, search filter, or other fields of the referral value may not be
712 legal for URIs (e.g. spaces) and MUST be escaped using the % method
718 Controls provide a mechanism whereby the semantics and arguments of
719 existing LDAP operations may be extended. One or more controls may be
720 attached to a single LDAP message. A control only affects the
721 semantics of the message it is attached to.
723 Controls sent by clients are termed 'request controls' and those sent
724 by servers are termed 'response controls'.
726 Controls ::= SEQUENCE OF control Control
728 Control ::= SEQUENCE {
730 criticality BOOLEAN DEFAULT FALSE,
731 controlValue OCTET STRING OPTIONAL }
733 The controlType field is the dotted-decimal representation of an
734 OBJECT IDENTIFIER which uniquely identifies the control. This
735 provides unambiguous naming of controls. Often, response control(s)
736 solicited by a request control share controlType values with the
739 The criticality field only has meaning in controls attached to
740 request messages (except UnbindRequest). For controls attached to
741 response messages and the UnbindRequest, the criticality field SHOULD
742 be FALSE, and MUST be ignored by the receiving protocol peer. A value
743 of TRUE indicates that it is unacceptable to perform the operation
744 without applying the semantics of the control. Specifically, the
745 criticality field is applied as follows:
747 - If the server does not recognize the control type, determines that
748 it is not appropriate for the operation, or is otherwise unwilling
749 to perform the operation with the control, and the criticality
750 field is TRUE, the server MUST NOT perform the operation, and for
751 operations that have a response message, MUST return with the
752 resultCode set to unavailableCriticalExtension.
754 - If the server does not recognize the control type, determines that
755 it is not appropriate for the operation, or is otherwise unwilling
756 to perform the operation with the control, and the criticality
757 field is FALSE, the server MUST ignore the control.
759 - Regardless of criticality, if a control is applied to an
760 operation, it is applied consistently and impartially to the
765 Sermersheim Internet-Draft - Expires Nov 2005 Page 13
767 Lightweight Directory Access Protocol Version 3
769 The controlValue may contain information associated with the
770 controlType. Its format is defined by the specification of the
771 control. Implementations MUST be prepared to handle arbitrary
772 contents of the controlValue octet string, including zero bytes. It
773 is absent only if there is no value information which is associated
774 with a control of its type. When a controlValue is defined in terms
775 of ASN.1, and BER encoded according to Section 5.1, it also follows
776 the extensibility rules in Section 4.
778 Servers list the controlType of request controls they recognize in
779 the 'supportedControl' attribute in the root DSE (Section 5.1 of
782 Controls SHOULD NOT be combined unless the semantics of the
783 combination has been specified. The semantics of control
784 combinations, if specified, are generally found in the control
785 specification most recently published. When a combination of controls
786 is encountered whose semantics are invalid, not specified (or not
787 known), the message is considered to be not well-formed, thus the
788 operation fails with protocolError. Controls with a criticality of
789 FALSE may be ignored in order to arrive at a valid combination.
790 Additionally, unless order-dependent semantics are given in a
791 specification, the order of a combination of controls in the SEQUENCE
792 is ignored. Where the order is to be ignored but cannot be ignored by
793 the server, the message is considered not well-formed and the
794 operation fails with protocolError. Again, controls with a
795 criticality of FALSE may be ignored in order to arrive at a valid
798 This document does not specify any controls. Controls may be
799 specified in other documents. Documents detailing control extensions
800 are to provide for each control:
802 - the OBJECT IDENTIFIER assigned to the control,
804 - direction as to what value the sender should provide for the
805 criticality field (note: the semantics of the criticality field
806 are defined above should not be altered by the control's
809 - whether the controlValue field is present, and if so, the format
812 - the semantics of the control, and
814 - optionally, semantics regarding the combination of the control
824 Sermersheim Internet-Draft - Expires Nov 2005 Page 14
826 Lightweight Directory Access Protocol Version 3
828 The function of the Bind operation is to allow authentication
829 information to be exchanged between the client and server. The Bind
830 operation should be thought of as the "authenticate" operation.
831 Operational, authentication, and security-related semantics of this
832 operation are given in [AuthMeth].
834 The Bind request is defined as follows:
836 BindRequest ::= [APPLICATION 0] SEQUENCE {
837 version INTEGER (1 .. 127),
839 authentication AuthenticationChoice }
841 AuthenticationChoice ::= CHOICE {
842 simple [0] OCTET STRING,
844 sasl [3] SaslCredentials,
847 SaslCredentials ::= SEQUENCE {
848 mechanism LDAPString,
849 credentials OCTET STRING OPTIONAL }
851 Fields of the BindRequest are:
853 - version: A version number indicating the version of the protocol
854 to be used at the LDAP message layer. This document describes
855 version 3 of the protocol. There is no version negotiation. The
856 client sets this field to the version it desires. If the server
857 does not support the specified version, it MUST respond with a
858 BindResponse where the resultCode is set to protocolError.
860 - name: If not empty, the name of the Directory object that the
861 client wishes to bind as. This field may take on a null value (a
862 zero length string) for the purposes of anonymous binds
863 ([AuthMeth] Section 5.1) or when using Simple Authentication and
864 Security Layer [SASL] authentication ([AuthMeth] Section 3.3.2).
865 Where the server attempts to locate the named object, it SHALL NOT
866 perform alias dereferencing.
868 - authentication: information used in authentication. This type is
869 extensible as defined in Section 3.7 of [LDAPIANA]. Servers that
870 do not support a choice supplied by a client return a BindResponse
871 with the resultCode set to authMethodNotSupported.
873 Textual passwords (consisting of a character sequence with a known
874 character set and encoding) transferred to the server using the
875 simple AuthenticationChoice SHALL be transferred as [UTF-8]
876 encoded [Unicode]. Prior to transfer, clients SHOULD prepare text
877 passwords as "query" strings by applying the [SASLprep] profile of
878 the [Stringprep] algorithm. Passwords consisting of other data
879 (such as random octets) MUST NOT be altered. The determination of
880 whether a password is textual is a local client matter.
883 Sermersheim Internet-Draft - Expires Nov 2005 Page 15
885 Lightweight Directory Access Protocol Version 3
888 4.2.1. Processing of the Bind Request
890 Before processing a BindRequest, all uncompleted operations MUST
891 either complete or be abandoned. The server may either wait for the
892 uncompleted operations to complete, or abandon them. The server then
893 proceeds to authenticate the client in either a single-step, or
894 multi-step Bind process. Each step requires the server to return a
895 BindResponse to indicate the status of authentication.
897 After sending a BindRequest, clients MUST NOT send further LDAP PDUs
898 until receiving the BindResponse. Similarly, servers SHOULD NOT
899 process or respond to requests received while processing a
902 If the client did not bind before sending a request and receives an
903 operationsError to that request, it may then send a BindRequest. If
904 this also fails or the client chooses not to bind on the existing
905 LDAP session, it may terminate the LDAP session, re-establish it and
906 begin again by first sending a BindRequest. This will aid in
907 interoperating with servers implementing other versions of LDAP.
909 Clients may send multiple Bind requests to change the authentication
910 and/or security associations or to complete a multi-stage Bind
911 process. Authentication from earlier binds is subsequently ignored.
913 For some SASL authentication mechanisms, it may be necessary for the
914 client to invoke the BindRequest multiple times ([AuthMeth] Section
915 8.2). Clients MUST NOT invoke operations between two Bind requests
916 made as part of a multi-stage Bind.
918 A client may abort a SASL bind negotiation by sending a BindRequest
919 with a different value in the mechanism field of SaslCredentials, or
920 an AuthenticationChoice other than sasl.
922 If the client sends a BindRequest with the sasl mechanism field as an
923 empty string, the server MUST return a BindResponse with the
924 resultCode set to authMethodNotSupported. This will allow clients to
925 abort a negotiation if it wishes to try again with the same SASL
931 The Bind response is defined as follows.
933 BindResponse ::= [APPLICATION 1] SEQUENCE {
934 COMPONENTS OF LDAPResult,
935 serverSaslCreds [7] OCTET STRING OPTIONAL }
937 BindResponse consists simply of an indication from the server of the
938 status of the client's request for authentication.
942 Sermersheim Internet-Draft - Expires Nov 2005 Page 16
944 Lightweight Directory Access Protocol Version 3
946 A successful Bind operation is indicated by a BindResponse with a
947 resultCode set to success. Otherwise, an appropriate result code is
948 set in the BindResponse. For BindResponse, the protocolError result
949 code may be used to indicate that the version number supplied by the
950 client is unsupported.
952 If the client receives a BindResponse where the resultCode is set to
953 protocolError, it is to assume that the server does not support this
954 version of LDAP. While the client may be able proceed with another
955 version of this protocol (this may or may not require closing and re-
956 establishing the transport connection), how to proceed with another
957 version of this protocol is beyond the scope of this document.
958 Clients which are unable or unwilling to proceed SHOULD terminate the
961 The serverSaslCreds field is used as part of a SASL-defined bind
962 mechanism to allow the client to authenticate the server to which it
963 is communicating, or to perform "challenge-response" authentication.
964 If the client bound with the simple choice, or the SASL mechanism
965 does not require the server to return information to the client, then
966 this field SHALL NOT be included in the BindResponse.
969 4.3. Unbind Operation
971 The function of the Unbind operation is to terminate an LDAP session.
972 The Unbind operation is not the antithesis of the Bind operation as
973 the name implies. The naming of these operations are historical. The
974 Unbind operation should be thought of as the "quit" operation.
976 The Unbind operation is defined as follows:
978 UnbindRequest ::= [APPLICATION 2] NULL
980 The client, upon transmission of the UnbindRequest, and the server,
981 upon receipt of the UnbindRequest are to gracefully terminate the
982 LDAP session as described in Section 5.3.
984 Uncompleted operations are handled as specified in Section 3.1.
987 4.4. Unsolicited Notification
989 An unsolicited notification is an LDAPMessage sent from the server to
990 the client which is not in response to any LDAPMessage received by
991 the server. It is used to signal an extraordinary condition in the
992 server or in the LDAP session between the client and the server. The
993 notification is of an advisory nature, and the server will not expect
994 any response to be returned from the client.
1001 Sermersheim Internet-Draft - Expires Nov 2005 Page 17
1003 Lightweight Directory Access Protocol Version 3
1005 The unsolicited notification is structured as an LDAPMessage in which
1006 the messageID is zero and protocolOp is set to the extendedResp
1007 choice using the ExtendedResponse type (See Section 4.12). The
1008 responseName field of the ExtendedResponse always contains an LDAPOID
1009 which is unique for this notification.
1011 One unsolicited notification (Notice of Disconnection) is defined in
1012 this document. The specification of an unsolicited notification
1015 - the OBJECT IDENTIFIER assigned to the notification (to be
1016 specified in the responseName,
1018 - the format of the contents of the responseValue (if any),
1020 - the circumstances which will cause the notification to be sent,
1023 - the semantics of the message.
1026 4.4.1. Notice of Disconnection
1028 This notification may be used by the server to advise the client that
1029 the server is about to terminate the LDAP session on its own
1030 initiative. This notification is intended to assist clients in
1031 distinguishing between an exceptional server condition and a
1032 transient network failure. Note that this notification is not a
1033 response to an Unbind requested by the client. Uncompleted operations
1034 are handled as specified in Section 3.1.
1036 The responseName is 1.3.6.1.4.1.1466.20036, the responseValue field
1037 is absent, and the resultCode is used to indicate the reason for the
1038 disconnection. When the strongerAuthRequired resultCode is returned
1039 with this message, it indicates that the server has detected that an
1040 established security association between the client and server has
1041 unexpectedly failed or been compromised.
1043 Upon transmission of the Notice of Disconnection, the server
1044 gracefully terminates the LDAP session as described in Section 5.3.
1047 4.5. Search Operation
1049 The Search operation is used to request a server to return, subject
1050 to access controls and other restrictions, a set of entries matching
1051 a complex search criterion. This can be used to read attributes from
1052 a single entry, from entries immediately subordinate to a particular
1053 entry, or a whole subtree of entries.
1056 4.5.1. Search Request
1058 The Search request is defined as follows:
1060 Sermersheim Internet-Draft - Expires Nov 2005 Page 18
1062 Lightweight Directory Access Protocol Version 3
1065 SearchRequest ::= [APPLICATION 3] SEQUENCE {
1072 derefAliases ENUMERATED {
1073 neverDerefAliases (0),
1074 derefInSearching (1),
1075 derefFindingBaseObj (2),
1077 sizeLimit INTEGER (0 .. maxInt),
1078 timeLimit INTEGER (0 .. maxInt),
1081 attributes AttributeSelection }
1083 AttributeSelection ::= SEQUENCE OF selector LDAPString
1084 -- The LDAPString is constrained to
1085 -- <attributeSelector> in Section 4.5.1.7
1088 and [0] SET SIZE (1..MAX) OF filter Filter,
1089 or [1] SET SIZE (1..MAX) OF filter Filter,
1091 equalityMatch [3] AttributeValueAssertion,
1092 substrings [4] SubstringFilter,
1093 greaterOrEqual [5] AttributeValueAssertion,
1094 lessOrEqual [6] AttributeValueAssertion,
1095 present [7] AttributeDescription,
1096 approxMatch [8] AttributeValueAssertion,
1097 extensibleMatch [9] MatchingRuleAssertion,
1100 SubstringFilter ::= SEQUENCE {
1101 type AttributeDescription,
1102 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE {
1103 initial [0] AssertionValue, -- can occur at most once
1104 any [1] AssertionValue,
1105 final [2] AssertionValue } -- can occur at most once
1108 MatchingRuleAssertion ::= SEQUENCE {
1109 matchingRule [1] MatchingRuleId OPTIONAL,
1110 type [2] AttributeDescription OPTIONAL,
1111 matchValue [3] AssertionValue,
1112 dnAttributes [4] BOOLEAN DEFAULT FALSE }
1119 Sermersheim Internet-Draft - Expires Nov 2005 Page 19
1121 Lightweight Directory Access Protocol Version 3
1123 Note that an X.500 "list"-like operation can be emulated by the
1124 client requesting a singleLevel Search operation with a filter
1125 checking for the presence of the 'objectClass' attribute, and that an
1126 X.500 "read"-like operation can be emulated by a baseObject Search
1127 operation with the same filter. A server which provides a gateway to
1128 X.500 is not required to use the Read or List operations, although it
1129 may choose to do so, and if it does, it must provide the same
1130 semantics as the X.500 Search operation.
1133 4.5.1.1 SearchRequest.baseObject
1135 The name of the base object entry (or possibly the root) relative to
1136 which the Search is to be performed.
1139 4.5.1.2 SearchRequest.scope
1141 Specifies the scope of the Search to be performed. The semantics (as
1142 described in [X.511]) of the defined values of this field are:
1144 baseObject: The scope is constrained to the entry named by
1147 singleLevel: The scope is constrained to the immediate
1148 subordinates of the entry named by baseObject.
1150 wholeSubtree: the scope is constrained to the entry named by the
1151 baseObject, and all its subordinates.
1154 4.5.1.3 SearchRequest.derefAliases
1156 An indicator as to whether or not alias entries (as defined in
1157 [Models]) are to be dereferenced during stages of the Search
1160 The act of dereferencing an alias includes recursively dereferencing
1161 aliases which refer to aliases.
1163 Servers MUST detect looping while dereferencing aliases in order to
1164 prevent denial of service attacks of this nature.
1166 The semantics of the defined values of this field are:
1168 neverDerefAliases: Do not dereference aliases in searching or in
1169 locating the base object of the Search.
1178 Sermersheim Internet-Draft - Expires Nov 2005 Page 20
1180 Lightweight Directory Access Protocol Version 3
1182 derefInSearching: While searching subordinates of the base object,
1183 dereference any alias within the search scope. Dereferenced
1184 objects become the vertices of further search scopes where the
1185 Search operation is also applied. If the search scope is
1186 wholeSubtree, the Search continues in the subtree(s) of any
1187 dereferenced object. If the search scope is singleLevel, the
1188 search is applied to any dereferenced objects, and is not applied
1189 to their subordinates. Servers SHOULD eliminate duplicate entries
1190 that arise due to alias dereferencing while searching.
1192 derefFindingBaseObj: Dereference aliases in locating the base
1193 object of the Search, but not when searching subordinates of the
1196 derefAlways: Dereference aliases both in searching and in locating
1197 the base object of the Search.
1200 4.5.1.4 SearchRequest.sizeLimit
1202 A size limit that restricts the maximum number of entries to be
1203 returned as a result of the Search. A value of zero in this field
1204 indicates that no client-requested size limit restrictions are in
1205 effect for the Search. Servers may also enforce a maximum number of
1209 4.5.1.5 SearchRequest.timeLimit
1211 A time limit that restricts the maximum time (in seconds) allowed for
1212 a Search. A value of zero in this field indicates that no client-
1213 requested time limit restrictions are in effect for the Search.
1214 Servers may also enforce a maximum time limit for the Search.
1217 4.5.1.6 SearchRequest.typesOnly
1219 An indicator as to whether Search results are to contain both
1220 attribute descriptions and values, or just attribute descriptions.
1221 Setting this field to TRUE causes only attribute descriptions (no
1222 values) to be returned. Setting this field to FALSE causes both
1223 attribute descriptions and values to be returned.
1237 Sermersheim Internet-Draft - Expires Nov 2005 Page 21
1239 Lightweight Directory Access Protocol Version 3
1241 4.5.1.7 SearchRequest.filter
1243 A filter that defines the conditions that must be fulfilled in order
1244 for the Search to match a given entry.
1246 The 'and', 'or' and 'not' choices can be used to form combinations of
1247 filters. At least one filter element MUST be present in an 'and' or
1248 'or' choice. The others match against individual attribute values of
1249 entries in the scope of the Search. (Implementor's note: the 'not'
1250 filter is an example of a tagged choice in an implicitly-tagged
1251 module. In BER this is treated as if the tag was explicit.)
1253 A server MUST evaluate filters according to the three-valued logic of
1254 [X.511] (1993) Clause 7.8.1. In summary, a filter is evaluated to
1255 either "TRUE", "FALSE" or "Undefined". If the filter evaluates to
1256 TRUE for a particular entry, then the attributes of that entry are
1257 returned as part of the Search result (subject to any applicable
1258 access control restrictions). If the filter evaluates to FALSE or
1259 Undefined, then the entry is ignored for the Search.
1261 A filter of the "and" choice is TRUE if all the filters in the SET OF
1262 evaluate to TRUE, FALSE if at least one filter is FALSE, and
1263 otherwise Undefined. A filter of the "or" choice is FALSE if all of
1264 the filters in the SET OF evaluate to FALSE, TRUE if at least one
1265 filter is TRUE, and Undefined otherwise. A filter of the 'not' choice
1266 is TRUE if the filter being negated is FALSE, FALSE if it is TRUE,
1267 and Undefined if it is Undefined.
1269 A filter item evaluates to Undefined when the server would not be
1270 able to determine whether the assertion value matches an entry.
1273 - An attribute description in an equalityMatch, substrings,
1274 greaterOrEqual, lessOrEqual, approxMatch or extensibleMatch
1275 filter is not recognized by the server.
1277 - The attribute type does not define the appropriate matching
1280 - A MatchingRuleId in the extensibleMatch is not recognized by
1281 the server or is not valid for the attribute type.
1283 - The type of filtering requested is not implemented.
1285 - The assertion value is invalid.
1287 For example, if a server did not recognize the attribute type
1288 shoeSize, the filters (shoeSize=*), (shoeSize=12), (shoeSize>=12) and
1289 (shoeSize<=12) would each evaluate to Undefined.
1291 Servers MUST NOT return errors if attribute descriptions or matching
1292 rule ids are not recognized, assertion values are invalid, or the
1293 assertion syntax is not supported. More details of filter processing
1294 are given in Clause 7.8 of [X.511].
1296 Sermersheim Internet-Draft - Expires Nov 2005 Page 22
1298 Lightweight Directory Access Protocol Version 3
1302 4.5.1.7.1 SearchRequest.filter.equalityMatch
1304 The matching rule for an equalityMatch filter is defined by the
1305 EQUALITY matching rule for the attribute type or subtype. The filter
1306 is TRUE when the EQUALITY rule returns TRUE as applied to the
1307 attribute or subtype and the asserted value.
1310 4.5.1.7.2 SearchRequest.filter.substrings
1312 There SHALL be at most one 'initial', and at most one 'final' in the
1313 'substrings' of a SubstringFilter. If 'initial' is present, it SHALL
1314 be the first element of 'substrings'. If 'final' is present, it SHALL
1315 be the last element of 'substrings'.
1317 The matching rule for an AssertionValue in a substrings filter item
1318 is defined by the SUBSTR matching rule for the attribute type or
1319 subtype. The filter is TRUE when the SUBSTR rule returns TRUE as
1320 applied to the attribute or subtype and the asserted value.
1322 Note that the AssertionValue in a substrings filter item conforms to
1323 the assertion syntax of the EQUALITY matching rule for the attribute
1324 type rather than the assertion syntax of the SUBSTR matching rule for
1325 the attribute type. Conceptually, the entire SubstringFilter is
1326 converted into an assertion value of the substrings matching rule
1327 prior to applying the rule.
1330 4.5.1.7.3 SearchRequest.filter.greaterOrEqual
1332 The matching rule for a greaterOrEqual filter is defined by the
1333 ORDERING matching rule for the attribute type or subtype. The filter
1334 is TRUE when the ORDERING rule returns FALSE as applied to the
1335 attribute or subtype and the asserted value.
1338 4.5.1.7.4 SearchRequest.filter.lessOrEqual
1340 The matching rules for a lessOrEqual filter are defined by the
1341 ORDERING and EQUALITY matching rules for the attribute type or
1342 subtype. The filter is TRUE when either the ORDERING or EQUALITY rule
1343 returns TRUE as applied to the attribute or subtype and the asserted
1347 4.5.1.7.5 SearchRequest.filter.present
1349 A present filter is TRUE when there is an attribute or subtype of the
1350 specified attribute description present in an entry, FALSE when no
1351 attribute or subtype of the specified attribute description is
1352 present in an entry, and Undefined otherwise.
1355 Sermersheim Internet-Draft - Expires Nov 2005 Page 23
1357 Lightweight Directory Access Protocol Version 3
1360 4.5.1.7.6 SearchRequest.filter.approxMatch
1362 An approxMatch filter is TRUE when there is a value of the attribute
1363 type or subtype for which some locally-defined approximate matching
1364 algorithm (e.g. spelling variations, phonetic match, etc.) returns
1365 TRUE. If a value matches for equality, it also satisfies an
1366 approximate match. If approximate matching is not supported for the
1367 attribute, this filter item should be treated as an equalityMatch.
1370 4.5.1.7.7 SearchRequest.filter.extensibleMatch
1372 The fields of the extensibleMatch filter item are evaluated as
1375 - If the matchingRule field is absent, the type field MUST be
1376 present, and an equality match is performed for that type.
1378 - If the type field is absent and the matchingRule is present, the
1379 matchValue is compared against all attributes in an entry which
1380 support that matchingRule.
1382 - If the type field is present and the matchingRule is present, the
1383 matchValue is compared against the specified attribute type and
1386 - If the dnAttributes field is set to TRUE, the match is
1387 additionally applied against all the AttributeValueAssertions in
1388 an entry's distinguished name, and evaluates to TRUE if there is
1389 at least one attribute or subtype in the distinguished name for
1390 which the filter item evaluates to TRUE. The dnAttributes field is
1391 present to alleviate the need for multiple versions of generic
1392 matching rules (such as word matching), where one applies to
1393 entries and another applies to entries and DN attributes as well.
1395 The matchingRule used for evaluation determines the syntax for the
1396 assertion value. Once the matchingRule and attribute(s) have been
1397 determined, the filter item evaluates to TRUE if it matches at least
1398 one attribute type or subtype in the entry, FALSE if it does not
1399 match any attribute type or subtype in the entry, and Undefined if
1400 the matchingRule is not recognized, the matchingRule is unsuitable
1401 for use with the specified type, or the assertionValue is invalid.
1404 4.5.1.7 SearchRequest.attributes
1406 A selection list of the attributes to be returned from each entry
1407 which matches the search filter. Attributes which are subtypes of
1408 listed attributes are implicitly included. LDAPString values of this
1409 field are constrained to the following Augmented Backus-Naur Form
1412 attributeSelector = attributedescription / selectorspecial
1414 Sermersheim Internet-Draft - Expires Nov 2005 Page 24
1416 Lightweight Directory Access Protocol Version 3
1419 selectorspecial = noattrs / alluserattrs
1421 noattrs = %x31.2E.31 ; "1.1"
1423 alluserattrs = %x2A ; asterisk ("*")
1425 The <attributedescription> production is defined in Section 2.5 of
1428 There are three special cases which may appear in the attributes
1431 - an empty list with no attributes,
1433 - a list containing "*" (with zero or more attribute
1436 - a list containing only "1.1".
1438 An empty list requests the return of all user attributes.
1440 A list containing "*" requests the return of all user attributes
1441 in addition to other listed (operational) attributes.
1443 A list containing only the OID "1.1" indicates that no attributes
1444 are to be returned. If "1.1" is provided with other
1445 attributeSelector values, the "1.1" attributeSelector is ignored.
1446 This OID was chosen because it does not (and can not) correspond
1447 to any attribute in use.
1449 Client implementors should note that even if all user attributes are
1450 requested, some attributes and/or attribute values of the entry may
1451 not be included in Search results due to access controls or other
1452 restrictions. Furthermore, servers will not return operational
1453 attributes, such as objectClasses or attributeTypes, unless they are
1454 listed by name. Operational attributes are described in [Models].
1456 Attributes are returned at most once in an entry. If an attribute
1457 description is named more than once in the list, the subsequent names
1458 are ignored. If an attribute description in the list is not
1459 recognized, it is ignored by the server.
1462 4.5.2. Search Result
1464 The results of the Search operation are returned as zero or more
1465 SearchResultEntry and/or SearchResultReference messages, followed by
1466 a single SearchResultDone message.
1468 SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
1470 attributes PartialAttributeList }
1473 Sermersheim Internet-Draft - Expires Nov 2005 Page 25
1475 Lightweight Directory Access Protocol Version 3
1477 PartialAttributeList ::= SEQUENCE OF
1478 partialAttribute PartialAttribute
1480 SearchResultReference ::= [APPLICATION 19] SEQUENCE
1481 SIZE (1..MAX) OF uri URI
1483 SearchResultDone ::= [APPLICATION 5] LDAPResult
1485 Each SearchResultEntry represents an entry found during the Search.
1486 Each SearchResultReference represents an area not yet explored during
1487 the Search. The SearchResultEntry and SearchResultReference messages
1488 may come in any order. Following all the SearchResultReference and
1489 SearchResultEntry responses, the server returns a SearchResultDone
1490 response, which contains an indication of success, or detailing any
1491 errors that have occurred.
1493 Each entry returned in a SearchResultEntry will contain all
1494 appropriate attributes as specified in the attributes field of the
1495 Search Request, subject to access control and other administrative
1496 policy. Note that the PartialAttributeList may hold zero elements.
1497 This may happen when none of the attributes of an entry were
1498 requested, or could be returned. Note also that the partialAttribute
1499 vals set may hold zero elements. This may happen when typesOnly is
1500 requested, access controls prevent the return of values, or other
1503 Some attributes may be constructed by the server and appear in a
1504 SearchResultEntry attribute list, although they are not stored
1505 attributes of an entry. Clients SHOULD NOT assume that all attributes
1506 can be modified, even if permitted by access control.
1508 If the server's schema defines short names [Models] for an attribute
1509 type then the server SHOULD use one of those names in attribute
1510 descriptions for that attribute type (in preference to using the
1511 <numericoid> [Models] format of the attribute type's object
1512 identifier). The server SHOULD NOT use the short name if that name is
1513 known by the server to be ambiguous, or otherwise likely to cause
1514 interoperability problems.
1517 4.5.3. Continuation References in the Search Result
1519 If the server was able to locate the entry referred to by the
1520 baseObject but was unable or unwilling to search one or more non-
1521 local entries, the server may return one or more
1522 SearchResultReference messages, each containing a reference to
1523 another set of servers for continuing the operation. A server MUST
1524 NOT return any SearchResultReference messages if it has not located
1525 the baseObject and thus has not searched any entries; in this case it
1526 would return a SearchResultDone containing either a referral or
1527 noSuchObject result code (depending on the server's knowledge of the
1528 entry named in the baseObject).
1532 Sermersheim Internet-Draft - Expires Nov 2005 Page 26
1534 Lightweight Directory Access Protocol Version 3
1536 If a server holds a copy or partial copy of the subordinate naming
1537 context (Section 5 of [Models]), it may use the search filter to
1538 determine whether or not to return a SearchResultReference response.
1539 Otherwise SearchResultReference responses are always returned when in
1542 The SearchResultReference is of the same data type as the Referral.
1544 If the client wishes to progress the Search, it issues a new Search
1545 operation for each SearchResultReference that is returned. If
1546 multiple URIs are present, the client assumes that any supported URI
1547 may be used to progress the operation.
1549 Clients that follow search continuation references MUST ensure that
1550 they do not loop between servers. They MUST NOT repeatedly contact
1551 the same server for the same request with the same parameters. Some
1552 clients use a counter that is incremented each time search result
1553 reference handling occurs for an operation, and these kinds of
1554 clients MUST be able to handle at least ten nested referrals while
1555 progressing the operation.
1557 Note that the Abandon operation described in Section 4.11 applies
1558 only to a particular operation sent at the LDAP message layer between
1559 a client and server. The client must abandon subsequent Search
1560 operations it wishes to individually.
1562 A URI for a server implementing LDAP and accessible via [TCP]/[IP]
1563 (v4 or v6) is written as an LDAP URL according to [LDAPURL].
1565 SearchResultReference values which are LDAP URLs follow these rules:
1567 - The <dn> part of the LDAP URL MUST be present, with the new target
1568 object name. The client uses this name when following the
1571 - Some servers (e.g. participating in distributed indexing) may
1572 provide a different filter in the LDAP URL.
1574 - If the <filter> part of the LDAP URL is present, the client uses
1575 this filter in its next request to progress this Search, and if it
1576 is not present the client uses the same filter as it used for that
1579 - If the originating search scope was singleLevel, the <scope> part
1580 of the LDAP URL will be "base".
1582 - It is RECOMMENDED that the <scope> part be present to avoid
1583 ambiguity. In the absence of a <scope> part, the scope of the
1584 original Search request is assumed.
1586 - Other aspects of the new Search request may be the same as or
1587 different from the Search request which generated the
1588 SearchResultReference.
1591 Sermersheim Internet-Draft - Expires Nov 2005 Page 27
1593 Lightweight Directory Access Protocol Version 3
1595 - The name of an unexplored subtree in a SearchResultReference need
1596 not be subordinate to the base object.
1598 Other kinds of URIs may be returned. The syntax and semantics of such
1599 URIs is left to future specifications. Clients may ignore URIs that
1600 they do not support.
1602 UTF-8 encoded characters appearing in the string representation of a
1603 DN, search filter, or other fields of the referral value may not be
1604 legal for URIs (e.g. spaces) and MUST be escaped using the % method
1611 For example, suppose the contacted server (hosta) holds the entry
1612 <DC=Example,DC=NET> and the entry <CN=Manager,DC=Example,DC=NET>. It
1613 knows that both LDAP servers (hostb) and (hostc) hold
1614 <OU=People,DC=Example,DC=NET> (one is the master and the other server
1615 a shadow), and that LDAP-capable server (hostd) holds the subtree
1616 <OU=Roles,DC=Example,DC=NET>. If a wholeSubtree Search of
1617 <DC=Example,DC=NET> is requested to the contacted server, it may
1618 return the following:
1620 SearchResultEntry for DC=Example,DC=NET
1621 SearchResultEntry for CN=Manager,DC=Example,DC=NET
1622 SearchResultReference {
1623 ldap://hostb/OU=People,DC=Example,DC=NET??sub
1624 ldap://hostc/OU=People,DC=Example,DC=NET??sub }
1625 SearchResultReference {
1626 ldap://hostd/OU=Roles,DC=Example,DC=NET??sub }
1627 SearchResultDone (success)
1629 Client implementors should note that when following a
1630 SearchResultReference, additional SearchResultReference may be
1631 generated. Continuing the example, if the client contacted the server
1632 (hostb) and issued the Search request for the subtree
1633 <OU=People,DC=Example,DC=NET>, the server might respond as follows:
1635 SearchResultEntry for OU=People,DC=Example,DC=NET
1636 SearchResultReference {
1637 ldap://hoste/OU=Managers,OU=People,DC=Example,DC=NET??sub }
1638 SearchResultReference {
1639 ldap://hostf/OU=Consultants,OU=People,DC=Example,DC=NET??sub }
1640 SearchResultDone (success)
1642 Similarly, if a singleLevel Search of <DC=Example,DC=NET> is
1643 requested to the contacted server, it may return the following:
1650 Sermersheim Internet-Draft - Expires Nov 2005 Page 28
1652 Lightweight Directory Access Protocol Version 3
1654 SearchResultEntry for CN=Manager,DC=Example,DC=NET
1655 SearchResultReference {
1656 ldap://hostb/OU=People,DC=Example,DC=NET??base
1657 ldap://hostc/OU=People,DC=Example,DC=NET??base }
1658 SearchResultReference {
1659 ldap://hostd/OU=Roles,DC=Example,DC=NET??base }
1660 SearchResultDone (success)
1662 If the contacted server does not hold the base object for the Search,
1663 but has knowledge of its possible location, then it may return a
1664 referral to the client. In this case, if the client requests a
1665 subtree Search of <DC=Example,DC=ORG> to hosta, the server returns a
1666 SearchResultDone containing a referral.
1668 SearchResultDone (referral) {
1669 ldap://hostg/DC=Example,DC=ORG??sub }
1672 4.6. Modify Operation
1674 The Modify operation allows a client to request that a modification
1675 of an entry be performed on its behalf by a server. The Modify
1676 Request is defined as follows:
1678 ModifyRequest ::= [APPLICATION 6] SEQUENCE {
1680 changes SEQUENCE OF change SEQUENCE {
1681 operation ENUMERATED {
1686 modification PartialAttribute } }
1688 Fields of the Modify Request are:
1690 - object: The value of this field contains the name of the entry to
1691 be modified. The server SHALL NOT perform any alias dereferencing
1692 in determining the object to be modified.
1694 - changes: A list of modifications to be performed on the entry. The
1695 entire list of modifications MUST be performed in the order they
1696 are listed as a single atomic operation. While individual
1697 modifications may violate certain aspects of the directory schema
1698 (such as the object class definition and DIT content rule), the
1699 resulting entry after the entire list of modifications is
1700 performed MUST conform to the requirements of the directory model
1701 and controlling schema [Models].
1703 - operation: Used to specify the type of modification being
1704 performed. Each operation type acts on the following
1705 modification. The values of this field have the following
1706 semantics respectively:
1709 Sermersheim Internet-Draft - Expires Nov 2005 Page 29
1711 Lightweight Directory Access Protocol Version 3
1713 add: add values listed to the modification attribute,
1714 creating the attribute if necessary;
1716 delete: delete values listed from the modification attribute.
1717 If no values are listed, or if all current values of the
1718 attribute are listed, the entire attribute is removed;
1720 replace: replace all existing values of the modification
1721 attribute with the new values listed, creating the attribute
1722 if it did not already exist. A replace with no value will
1723 delete the entire attribute if it exists, and is ignored if
1724 the attribute does not exist.
1726 - modification: A PartialAttribute (which may have an empty SET
1727 of vals) used to hold the attribute type or attribute type and
1728 values being modified.
1730 Upon receipt of a Modify Request, the server attempts to perform the
1731 necessary modifications to the DIT and returns the result in a Modify
1732 Response, defined as follows:
1734 ModifyResponse ::= [APPLICATION 7] LDAPResult
1736 The server will return to the client a single Modify Response
1737 indicating either the successful completion of the DIT modification,
1738 or the reason that the modification failed. Due to the requirement
1739 for atomicity in applying the list of modifications in the Modify
1740 Request, the client may expect that no modifications of the DIT have
1741 been performed if the Modify Response received indicates any sort of
1742 error, and that all requested modifications have been performed if
1743 the Modify Response indicates successful completion of the Modify
1744 operation. Whether the modification was applied or not cannot be
1745 determined by the client if the Modify Response was not received
1746 (e.g. the LDAP session was terminated or the Modify operation was
1749 Servers MUST ensure that entries conform to user and system schema
1750 rules or other data model constraints. The Modify operation cannot be
1751 used to remove from an entry any of its distinguished values, i.e.
1752 those values which form the entry's relative distinguished name. An
1753 attempt to do so will result in the server returning the
1754 notAllowedOnRDN result code. The Modify DN operation described in
1755 Section 4.9 is used to rename an entry.
1757 For attribute types which specify no equality matching, the rules in
1758 Section 2.5.1 of [Models] are followed.
1760 Note that due to the simplifications made in LDAP, there is not a
1761 direct mapping of the changes in an LDAP ModifyRequest onto the
1762 changes of a DAP ModifyEntry operation, and different implementations
1763 of LDAP-DAP gateways may use different means of representing the
1764 change. If successful, the final effect of the operations on the
1765 entry MUST be identical.
1768 Sermersheim Internet-Draft - Expires Nov 2005 Page 30
1770 Lightweight Directory Access Protocol Version 3
1775 The Add operation allows a client to request the addition of an entry
1776 into the Directory. The Add Request is defined as follows:
1778 AddRequest ::= [APPLICATION 8] SEQUENCE {
1780 attributes AttributeList }
1782 AttributeList ::= SEQUENCE OF attribute Attribute
1784 Fields of the Add Request are:
1786 - entry: the name of the entry to be added. The server SHALL NOT
1787 dereference any aliases in locating the entry to be added.
1789 - attributes: the list of attributes that, along with those from the
1790 RDN, make up the content of the entry being added. Clients MAY or
1791 MAY NOT include the RDN attribute(s) in this list. Clients MUST
1792 NOT supply NO-USER-MODIFICATION attributes such as the
1793 createTimestamp or creatorsName attributes, since the server
1794 maintains these automatically.
1796 Servers MUST ensure that entries conform to user and system schema
1797 rules or other data model constraints. For attribute types which
1798 specify no equality matching, the rules in Section 2.5.1 of [Models]
1799 are followed (this applies to the naming attribute in addition to any
1800 multi-valued attributes being added).
1802 The entry named in the entry field of the AddRequest MUST NOT exist
1803 for the AddRequest to succeed. The immediate superior (parent) of an
1804 object or alias entry to be added MUST exist. For example, if the
1805 client attempted to add <CN=JS,DC=Example,DC=NET>, the
1806 <DC=Example,DC=NET> entry did not exist, and the <DC=NET> entry did
1807 exist, then the server would return the noSuchObject result code with
1808 the matchedDN field containing <DC=NET>.
1810 Upon receipt of an Add Request, a server will attempt to add the
1811 requested entry. The result of the Add attempt will be returned to
1812 the client in the Add Response, defined as follows:
1814 AddResponse ::= [APPLICATION 9] LDAPResult
1816 A response of success indicates that the new entry has been added to
1820 4.8. Delete Operation
1822 The Delete operation allows a client to request the removal of an
1823 entry from the Directory. The Delete Request is defined as follows:
1825 DelRequest ::= [APPLICATION 10] LDAPDN
1827 Sermersheim Internet-Draft - Expires Nov 2005 Page 31
1829 Lightweight Directory Access Protocol Version 3
1832 The Delete Request consists of the name of the entry to be deleted.
1833 The server SHALL NOT dereference aliases while resolving the name of
1834 the target entry to be removed.
1836 Only leaf entries (those with no subordinate entries) can be deleted
1837 with this operation.
1839 Upon receipt of a Delete Request, a server will attempt to perform
1840 the entry removal requested and return the result in the Delete
1841 Response defined as follows:
1843 DelResponse ::= [APPLICATION 11] LDAPResult
1846 4.9. Modify DN Operation
1848 The Modify DN operation allows a client to change the Relative
1849 Distinguished Name (RDN) of an entry in the Directory, and/or to move
1850 a subtree of entries to a new location in the Directory. The Modify
1851 DN Request is defined as follows:
1853 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
1855 newrdn RelativeLDAPDN,
1856 deleteoldrdn BOOLEAN,
1857 newSuperior [0] LDAPDN OPTIONAL }
1859 Fields of the Modify DN Request are:
1861 - entry: the name of the entry to be changed. This entry may or may
1862 not have subordinate entries.
1864 - newrdn: the new RDN of the entry. The value of the old RDN is
1865 supplied when moving the entry to a new superior without changing
1866 its RDN. Attribute values of the new RDN not matching any
1867 attribute value of the entry are added to the entry and an
1868 appropriate error is returned if this fails.
1870 - deleteoldrdn: a boolean field that controls whether the old RDN
1871 attribute values are to be retained as attributes of the entry, or
1872 deleted from the entry.
1874 - newSuperior: if present, this is the name of an existing object
1875 entry which becomes the immediate superior (parent) of the
1878 The server SHALL NOT dereference any aliases in locating the objects
1879 named in entry or newSuperior.
1881 Upon receipt of a ModifyDNRequest, a server will attempt to perform
1882 the name change and return the result in the Modify DN Response,
1886 Sermersheim Internet-Draft - Expires Nov 2005 Page 32
1888 Lightweight Directory Access Protocol Version 3
1890 ModifyDNResponse ::= [APPLICATION 13] LDAPResult
1892 For example, if the entry named in the entry field was <cn=John
1893 Smith,c=US>, the newrdn field was <cn=John Cougar Smith>, and the
1894 newSuperior field was absent, then this operation would attempt to
1895 rename the entry to be <cn=John Cougar Smith,c=US>. If there was
1896 already an entry with that name, the operation would fail with the
1897 entryAlreadyExists result code.
1899 Servers MUST ensure that entries conform to user and system schema
1900 rules or other data model constraints. For attribute types which
1901 specify no equality matching, the rules in Section 2.5.1 of [Models]
1902 are followed (this pertains to newrdn and deleteoldrdn).
1904 The object named in newSuperior MUST exist. For example, if the
1905 client attempted to add <CN=JS,DC=Example,DC=NET>, the
1906 <DC=Example,DC=NET> entry did not exist, and the <DC=NET> entry did
1907 exist, then the server would return the noSuchObject result code with
1908 the matchedDN field containing <DC=NET>.
1910 If the deleteoldrdn field is TRUE, the attribute values forming the
1911 old RDN but not the new RDN are deleted from the entry. If the
1912 deleteoldrdn field is FALSE, the attribute values forming the old RDN
1913 will be retained as non-distinguished attribute values of the entry.
1915 Note that X.500 restricts the ModifyDN operation to only affect
1916 entries that are contained within a single server. If the LDAP server
1917 is mapped onto DAP, then this restriction will apply, and the
1918 affectsMultipleDSAs result code will be returned if this error
1919 occurred. In general, clients MUST NOT expect to be able to perform
1920 arbitrary movements of entries and subtrees between servers or
1921 between naming contexts.
1924 4.10. Compare Operation
1926 The Compare operation allows a client to compare an assertion value
1927 with the values of a particular attribute in a particular entry in
1928 the Directory. The Compare Request is defined as follows:
1930 CompareRequest ::= [APPLICATION 14] SEQUENCE {
1932 ava AttributeValueAssertion }
1934 Fields of the Compare Request are:
1936 - entry: the name of the entry to be compared. The server SHALL NOT
1937 dereference any aliases in locating the entry to be compared.
1939 - ava: holds the attribute value assertion to be compared.
1941 Upon receipt of a Compare Request, a server will attempt to perform
1942 the requested comparison and return the result in the Compare
1943 Response, defined as follows:
1945 Sermersheim Internet-Draft - Expires Nov 2005 Page 33
1947 Lightweight Directory Access Protocol Version 3
1950 CompareResponse ::= [APPLICATION 15] LDAPResult
1952 The resultCode is set to compareTrue, compareFalse, or an appropriate
1953 error. compareTrue indicates that the assertion value in the ava
1954 field matches a value of the attribute or subtype according to the
1955 attribute's EQUALITY matching rule. compareFalse indicates that the
1956 assertion value in the ava field and the values of the attribute or
1957 subtype did not match. Other result codes indicate either that the
1958 result of the comparison was Undefined (Section 4.5.1), or that some
1961 Note that some directory systems may establish access controls which
1962 permit the values of certain attributes (such as userPassword) to be
1963 compared but not interrogated by other means.
1966 4.11. Abandon Operation
1968 The function of the Abandon operation is to allow a client to request
1969 that the server abandon an uncompleted operation. The Abandon Request
1970 is defined as follows:
1972 AbandonRequest ::= [APPLICATION 16] MessageID
1974 The MessageID is that of an operation which was requested earlier at
1975 this LDAP message layer. The Abandon request itself has its own
1976 MessageID. This is distinct from the MessageID of the earlier
1977 operation being abandoned.
1979 There is no response defined in the Abandon operation. Upon receipt
1980 of an AbandonRequest, the server MAY abandon the operation identified
1981 by the MessageID. Since the client cannot tell the difference between
1982 a successfully abandoned operation and an uncompleted operation, the
1983 application of the Abandon operation is limited to uses where the
1984 client does not require an indication of its outcome.
1986 Abandon, Bind, Unbind, and StartTLS operations cannot be abandoned.
1988 In the event that a server receives an Abandon Request on a Search
1989 operation in the midst of transmitting responses to the Search, that
1990 server MUST cease transmitting entry responses to the abandoned
1991 request immediately, and MUST NOT send the SearchResultDone. Of
1992 course, the server MUST ensure that only properly encoded LDAPMessage
1993 PDUs are transmitted.
1995 The ability to abandon other (particularly update) operations is at
1996 the discretion of the server.
1998 Clients should not send Abandon requests for the same operation
1999 multiple times, and MUST also be prepared to receive results from
2000 operations it has abandoned (since these may have been in transit
2001 when the Abandon was requested, or are not able to be abandoned).
2004 Sermersheim Internet-Draft - Expires Nov 2005 Page 34
2006 Lightweight Directory Access Protocol Version 3
2008 Servers MUST discard Abandon requests for message IDs they do not
2009 recognize, for operations which cannot be abandoned, and for
2010 operations which have already been abandoned.
2013 4.12. Extended Operation
2015 The Extended operation allows additional operations to be defined for
2016 services not already available in the protocol. For example, to Add
2017 operations to install transport layer security (see Section 4.14).
2019 The Extended operation allows clients to make requests and receive
2020 responses with predefined syntaxes and semantics. These may be
2021 defined in RFCs or be private to particular implementations.
2023 Each Extended operation consists of an Extended request and an
2026 ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
2027 requestName [0] LDAPOID,
2028 requestValue [1] OCTET STRING OPTIONAL }
2030 The requestName is a dotted-decimal representation of the unique
2031 OBJECT IDENTIFIER corresponding to the request. The requestValue is
2032 information in a form defined by that request, encapsulated inside an
2035 The server will respond to this with an LDAPMessage containing an
2038 ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
2039 COMPONENTS OF LDAPResult,
2040 responseName [10] LDAPOID OPTIONAL,
2041 responseValue [11] OCTET STRING OPTIONAL }
2043 The responseName is typically not required to be present as the
2044 syntax and semantics of the response (including the format of the
2045 responseValue) is implicitly known and associated with the request by
2048 If the Extended operation associated with the requestName is not
2049 supported by the server, the server MUST NOT provide a responseName
2050 nor a responseValue and MUST return with resultCode set to
2053 The requestValue and responseValue fields contain any information
2054 associated with the operation. The format of these fields is defined
2055 by the specification of the Extended operation. Implementations MUST
2056 be prepared to handle arbitrary contents of these fields, including
2057 zero bytes. Values that are defined in terms of ASN.1 and BER encoded
2058 according to Section 5.1, also follow the extensibility rules in
2063 Sermersheim Internet-Draft - Expires Nov 2005 Page 35
2065 Lightweight Directory Access Protocol Version 3
2067 Servers list the requestName of Extended Requests they recognize in
2068 the 'supportedExtension' attribute in the root DSE (Section 5.1 of
2071 Extended operations may be specified in other documents. The
2072 specification of an Extended operation consists of:
2074 - the OBJECT IDENTIFIER assigned to the requestName,
2076 - the OBJECT IDENTIFIER (if any) assigned to the responseName (note
2077 that the same OBJECT IDENTIFIER my be used for both the
2078 requestName and responseName),
2080 - the format of the contents of the requestValue and responseValue
2083 - the semantics of the operation.
2086 4.13. IntermediateResponse Message
2088 While the Search operation provides a mechanism to return multiple
2089 response messages for a single Search request, other operations, by
2090 nature, do not provide for multiple response messages.
2092 The IntermediateResponse message provides a general mechanism for
2093 defining single-request/multiple-response operations in LDAP. This
2094 message is intended to be used in conjunction with the Extended
2095 operation to define new single-request/multiple-response operations
2096 or in conjunction with a control when extending existing LDAP
2097 operations in a way that requires them to return Intermediate
2098 response information.
2100 It is intended that the definitions and descriptions of Extended
2101 operations and controls that make use of the IntermediateResponse
2102 message will define the circumstances when an IntermediateResponse
2103 message can be sent by a server and the associated meaning of an
2104 IntermediateResponse message sent in a particular circumstance.
2106 IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
2107 responseName [0] LDAPOID OPTIONAL,
2108 responseValue [1] OCTET STRING OPTIONAL }
2110 IntermediateResponse messages SHALL NOT be returned to the client
2111 unless the client issues a request that specifically solicits their
2112 return. This document defines two forms of solicitation: Extended
2113 operation and request control. IntermediateResponse messages are
2114 specified in documents describing the manner in which they are
2115 solicited (i.e. in the Extended operation or request control
2116 specification that uses them). These specifications include:
2118 - the OBJECT IDENTIFIER (if any) assigned to the responseName,
2120 - the format of the contents of the responseValue (if any), and
2122 Sermersheim Internet-Draft - Expires Nov 2005 Page 36
2124 Lightweight Directory Access Protocol Version 3
2127 - the semantics associated with the IntermediateResponse message.
2129 Extensions that allow the return of multiple types of
2130 IntermediateResponse messages SHALL identify those types using unique
2131 responseName values (note that one of these may specify no value).
2133 Sections 4.13.1 and 4.13.2 describe additional requirements on the
2134 inclusion of responseName and responseValue in IntermediateResponse
2138 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse
2140 A single-request/multiple-response operation may be defined using a
2141 single ExtendedRequest message to solicit zero or more
2142 IntermediateResponse messages of one or more kinds followed by an
2143 ExtendedResponse message.
2146 4.13.2. Usage with LDAP Request Controls
2148 A control's semantics may include the return of zero or more
2149 IntermediateResponse messages prior to returning the final result
2150 code for the operation. One or more kinds of IntermediateResponse
2151 messages may be sent in response to a request control.
2153 All IntermediateResponse messages associated with request controls
2154 SHALL include a responseName. This requirement ensures that the
2155 client can correctly identify the source of IntermediateResponse
2158 - two or more controls using IntermediateResponse messages are
2159 included in a request for any LDAP operation or
2161 - one or more controls using IntermediateResponse messages are
2162 included in a request with an LDAP Extended operation that uses
2163 IntermediateResponse messages.
2166 4.14. StartTLS Operation
2168 The Start Transport Layer Security (StartTLS) operation's purpose is
2169 to initiate installation of a TLS layer. The StartTLS operation is
2170 defined using the Extended operation mechanism described in Section
2181 Sermersheim Internet-Draft - Expires Nov 2005 Page 37
2183 Lightweight Directory Access Protocol Version 3
2185 4.14.1. StartTLS Request
2187 A client requests TLS establishment by transmitting a StartTLS
2188 request message to the server. The StartTLS request is defined in
2189 terms of an ExtendedRequest. The requestName is
2190 "1.3.6.1.4.1.1466.20037", and the requestValue field is always
2193 The client MUST NOT send any LDAP PDUs at this LDAP message layer
2194 following this request until it receives a StartTLS Extended response
2195 and, in the case of a successful response, completes TLS
2198 Detected sequencing problems (particularly those detailed in Section
2199 3.1.1 of [AuthMeth]) result in the resultCode being set to
2202 If the server does not support TLS (whether by design or by current
2203 configuration), it returns with the resultCode set to protocolError
2204 as described in Section 4.12.
2207 4.14.2. StartTLS Response
2209 When a StartTLS request is made, servers supporting the operation
2210 MUST return a StartTLS response message to the requestor. The
2211 responseName, if present, is also "1.3.6.1.4.1.1466.20037". The
2212 responseValue is absent.
2214 If the server is willing and able to negotiate TLS, it returns with
2215 the resultCode set to success. Refer to Section 4 of [AuthMeth] for
2218 If the server is otherwise unwilling or unable to perform this
2219 operation, the server is to return an appropriate result code
2220 indicating the nature of the problem. For example, if the TLS
2221 subsystem is not presently available, the server may indicate so by
2222 returning with the resultCode set to unavailable.
2225 4.14.3. Removal of the TLS Layer
2227 Either the client or server MAY remove the TLS layer and leave the
2228 LDAP message layer intact by sending and receiving a TLS closure
2231 The initiating protocol peer sends the TLS closure alert and MUST
2232 wait until it receives a TLS closure alert from the other peer before
2233 sending further LDAP PDUs.
2238 Sermersheim Internet-Draft - Expires Nov 2005 Page 38
2240 Lightweight Directory Access Protocol Version 3
2242 When a protocol peer receives the initial TLS closure alert, it may
2243 choose to allow the LDAP message layer to remain intact. In this
2244 case, it MUST immediately transmit a TLS closure alert. Following
2245 this, it MAY send and receive LDAP PDUs.
2247 Protocol peers MAY terminate the LDAP session after sending or
2248 receiving a TLS closure alert.
2251 5. Protocol Encoding, Connection, and Transfer
2253 This protocol is designed to run over connection-oriented, reliable
2254 transports, where the data stream is divided into octets (8-bit
2255 units), with each octet and each bit being significant.
2257 One underlying service, LDAP over TCP, is defined in Section
2258 5.2. This service is generally applicable to applications providing
2259 or consuming X.500-based directory services on the Internet. This
2260 specification was generally written with the TCP mapping in mind.
2261 Specifications detailing other mappings may encounter various
2264 Implementations of LDAP over TCP MUST implement the mapping as
2265 described in Section 5.2.
2267 This table illustrates the relationship between the different layers
2268 involved in an exchange between two protocol peers:
2270 +----------------------+
2271 | LDAP message layer |
2272 +----------------------+ > LDAP PDUs
2273 +----------------------+ < data
2275 +----------------------+ > SASL-protected data
2276 +----------------------+ < data
2278 Application +----------------------+ > TLS-protected data
2279 ------------+----------------------+ < data
2280 Transport | transport connection |
2281 +----------------------+
2284 5.1. Protocol Encoding
2286 The protocol elements of LDAP SHALL be encoded for exchange using the
2287 Basic Encoding Rules [BER] of [ASN.1] with the following
2290 - Only the definite form of length encoding is used.
2292 - OCTET STRING values are encoded in the primitive form only.
2297 Sermersheim Internet-Draft - Expires Nov 2005 Page 39
2299 Lightweight Directory Access Protocol Version 3
2301 - If the value of a BOOLEAN type is true, the encoding of the value
2302 octet is set to hex "FF".
2304 - If a value of a type is its default value, it is absent. Only some
2305 BOOLEAN and INTEGER types have default values in this protocol
2308 These restrictions are meant to ease the overhead of encoding and
2309 decoding certain elements in BER.
2311 These restrictions do not apply to ASN.1 types encapsulated inside of
2312 OCTET STRING values, such as attribute values, unless otherwise
2316 5.2. Transmission Control Protocol (TCP)
2318 The encoded LDAPMessage PDUs are mapped directly onto the [TCP]
2319 bytestream using the BER-based encoding described in Section 5.1. It
2320 is recommended that server implementations running over the TCP
2321 provide a protocol listener on the Internet Assigned Numbers
2322 Authority (IANA)-assigned LDAP port, 389 [PortReg]. Servers may
2323 instead provide a listener on a different port number. Clients MUST
2324 support contacting servers on any valid TCP port.
2327 5.3. Termination of the LDAP session
2329 Termination of the LDAP session is typically initiated by the client
2330 sending an UnbindRequest (Section 4.3), or by the server sending a
2331 Notice of Disconnection (Section 4.4.1). In these cases each protocol
2332 peer gracefully terminates the LDAP session by ceasing exchanges at
2333 the LDAP message layer, tearing down any SASL layer, tearing down any
2334 TLS layer, and closing the transport connection.
2336 A protocol peer may determine that the continuation of any
2337 communication would be pernicious, and in this case may abruptly
2338 terminate the session by ceasing communication and closing the
2339 transport connection.
2341 In either case, when the LDAP session is terminated, uncompleted
2342 operations are handled as specified in Section 3.1.
2345 6. Security Considerations
2347 This version of the protocol provides facilities for simple
2348 authentication using a cleartext password, as well as any [SASL]
2349 mechanism. Installing SASL and/or TLS layers can provide integrity
2350 and other data security services.
2352 It is also permitted that the server can return its credentials to
2353 the client, if it chooses to do so.
2356 Sermersheim Internet-Draft - Expires Nov 2005 Page 40
2358 Lightweight Directory Access Protocol Version 3
2360 Use of cleartext password is strongly discouraged where the
2361 underlying transport service cannot guarantee confidentiality and may
2362 result in disclosure of the password to unauthorized parties.
2364 Servers are encouraged to prevent directory modifications by clients
2365 that have authenticated anonymously [AuthMeth].
2367 Security considerations for authentication methods, SASL mechanisms,
2368 and TLS are described in [AuthMeth].
2370 It should be noted that SASL authentication exchanges do not provide
2371 data confidentiality nor integrity protection for the version or name
2372 fields of the BindRequest nor the resultCode, diagnosticMessage, or
2373 referral fields of the BindResponse nor of any information contained
2374 in controls attached to Bind requests or responses. Thus information
2375 contained in these fields SHOULD NOT be relied on unless otherwise
2376 protected (such as by establishing protections at the transport
2379 Implementors should note that various security factors, including
2380 authentication and authorization information and data security
2381 services may change during the course of the LDAP session, or even
2382 during the performance of a particular operation. For instance,
2383 credentials could expire, authorization identities or access controls
2384 could change, or the underlying security layer(s) could be replaced
2385 or terminated. Implementations should be robust in the handling of
2386 changing security factors.
2387 In some cases, it may be appropriate to continue the operation even
2388 in light of security factor changes. For instance, it may be
2389 appropriate to continue an Abandon operation regardless of the
2390 change, or to continue an operation when the change upgraded (or
2391 maintained) the security factor. In other cases, it may be
2392 appropriate to fail, or alter the processing of the operation. For
2393 instance, if confidential protections were removed, it would be
2394 appropriate to either fail a request to return sensitive data, or
2395 minimally, to exclude the return of sensitive data.
2397 Implementations which cache attributes and entries obtained via LDAP
2398 MUST ensure that access controls are maintained if that information
2399 is to be provided to multiple clients, since servers may have access
2400 control policies which prevent the return of entries or attributes in
2401 Search results except to particular authenticated clients. For
2402 example, caches could serve result information only to the client
2403 whose request caused it to be in the cache.
2405 Servers may return referrals or Search result references which
2406 redirect clients to peer servers. It is possible for a rogue
2407 application to inject such referrals into the data stream in an
2408 attempt to redirect a client to a rogue server. Clients are advised
2409 to be aware of this, and possibly reject referrals when
2410 confidentiality measures are not in place. Clients are advised to
2411 reject referrals from the StartTLS operation.
2415 Sermersheim Internet-Draft - Expires Nov 2005 Page 41
2417 Lightweight Directory Access Protocol Version 3
2419 The matchedDN and diagnosticMessage fields, as well as some
2420 resultCode values (e.g., attributeOrValueExists and
2421 entryAlreadyExists), could disclose the presence or absence of
2422 specific data in the directory which is subject to access and other
2423 administrative controls. Server implementations should restrict
2424 access to protected information equally under both normal and error
2427 Protocol peers MUST be prepared to handle invalid and arbitrary
2428 length protocol encodings. Invalid protocol encodings include: BER
2429 encoding exceptions, format string and UTF-8 encoding exceptions,
2430 overflow exceptions, integer value exceptions, and binary mode on/off
2431 flag exceptions. The LDAPv3 PROTOS [PROTOS-LDAP] test suite provides
2432 excellent examples of these exceptions and test cases used to
2435 In the event that a protocol peer senses an attack which in its
2436 nature could cause damage due to further communication at any layer
2437 in the LDAP session, the protocol peer should abruptly terminate the
2438 LDAP session as described in Section 5.3.
2443 This document is based on RFC 2251 by Mark Wahl, Tim Howes, and Steve
2444 Kille. RFC 2251 was a product of the IETF ASID Working Group.
2446 It is also based on RFC 2830 by Jeff Hodges, RL "Bob" Morgan, and
2447 Mark Wahl. RFC 2830 was a product of the IETF LDAPEXT Working Group.
2449 It is also based on RFC 3771 by Roger Harrison, and Kurt Zeilenga.
2450 RFC 3771 was an individual submission to the IETF.
2452 This document is a product of the IETF LDAPBIS Working Group.
2453 Significant contributors of technical review and content include Kurt
2454 Zeilenga, Steven Legg, and Hallvard Furuseth.
2457 8. Normative References
2459 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
2460 Specifications: ABNF", draft-crocker-abnf-rfc2234bis-
2461 xx.txt, (a work in progress).
2463 [ASN.1] ITU-T Recommendation X.680 (07/2002) | ISO/IEC 8824-1:2002
2464 "Information Technology - Abstract Syntax Notation One
2465 (ASN.1): Specification of basic notation"
2467 [AuthMeth] Harrison, R., "LDAP: Authentication Methods and Connection
2468 Level Security Mechanisms", draft-ietf-ldapbis-authmeth-
2469 xx.txt, (a work in progress).
2474 Sermersheim Internet-Draft - Expires Nov 2005 Page 42
2476 Lightweight Directory Access Protocol Version 3
2478 [BER] ITU-T Rec. X.690 (07/2002) | ISO/IEC 8825-1:2002,
2479 "Information technology - ASN.1 encoding rules:
2480 Specification of Basic Encoding Rules (BER), Canonical
2481 Encoding Rules (CER) and Distinguished Encoding Rules
2484 [IP] Postel, J., "Internet Protocol", STD5 and RFC 791,
2487 [ISO10646] Universal Multiple-Octet Coded Character Set (UCS) -
2488 Architecture and Basic Multilingual Plane, ISO/IEC 10646-1
2491 [Keyword] Bradner, S., "Key words for use in RFCs to Indicate
2492 Requirement Levels", RFC 2119, March 1997.
2494 [LDAPDN] Zeilenga, K., "LDAP: String Representation of
2495 Distinguished Names", draft-ietf-ldapbis-dn-xx.txt, (a
2498 [LDAPIANA] Zeilenga, K., "IANA Considerations for LDAP", draft-ietf-
2499 ldapbis-bcp64-xx.txt, (a work in progress).
2501 [LDAPURL] Smith, M., "LDAP: Uniform Resource Locator", draft-ietf-
2502 ldapbis-url-xx.txt, (a work in progress).
2504 [Models] Zeilenga, K., "LDAP: Directory Information Models", draft-
2505 ietf-ldapbis-models-xx.txt (a work in progress).
2507 [Roadmap] Zeilenga, K., "LDAP: Technical Specification Road Map",
2508 draft-ietf-ldapbis-roadmap-xx.txt (a work in progress).
2510 [SASL] Melnikov, A., "Simple Authentication and Security Layer",
2511 draft-ietf-sasl-rfc2222bis-xx.txt (a work in progress).
2513 [SASLPrep] Zeilenga, K., "Stringprep profile for user names and
2514 passwords", draft-ietf-sasl-saslprep-xx.txt, (a work in
2517 [StringPrep] Hoffman P. and M. Blanchet, "Preparation of
2518 Internationalized Strings ('stringprep')", draft-hoffman-
2519 rfc3454bis-xx.txt, a work in progress.
2521 [Syntaxes] Legg, S., and K. Dally, "LDAP: Syntaxes and Matching
2522 Rules", draft-ietf-ldapbis-syntaxes-xx.txt, (a work in
2525 [TCP] Postel, J., "Transmission Control Protocol", STD7 and RFC
2528 [TLS] Dierks, T. and C. Allen. "The TLS Protocol Version 1.1",
2529 draft-ietf-tls-rfc2246-bis-xx.txt, a work in progress.
2533 Sermersheim Internet-Draft - Expires Nov 2005 Page 43
2535 Lightweight Directory Access Protocol Version 3
2537 [Unicode] The Unicode Consortium, "The Unicode Standard, Version
2538 3.2.0" is defined by "The Unicode Standard, Version 3.0"
2539 (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5),
2540 as amended by the "Unicode Standard Annex #27: Unicode
2541 3.1" (http://www.unicode.org/reports/tr27/) and by the
2542 "Unicode Standard Annex #28: Unicode 3.2"
2543 (http://www.unicode.org/reports/tr28/).
2545 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
2546 Resource Identifiers (URI): Generic Syntax", RFC 2396,
2549 [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
2550 10646", STD63 and RFC3629, November 2003.
2552 [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts,
2553 Models and Service", 1993.
2555 [X.501] ITU-T Rec. X.501, "The Directory: Models", 1993.
2557 [X.511] ITU-T Rec. X.511, "The Directory: Abstract Service
2561 9. Informative References
2563 [Glossary] The Unicode Consortium, "Unicode Glossary",
2564 <http://www.unicode.org/glossary/>.
2566 [CharModel] Whistler, K. and M. Davis, "Unicode Technical Report
2567 #17, Character Encoding Model", UTR17,
2568 <http://www.unicode.org/unicode/reports/tr17/>, August
2571 [PROTOS-LDAP] University of Oulu, "PROTOS Test-Suite: c06-ldapv3"
2572 <http://www.ee.oulu.fi/research/ouspg/protos/testing/c06/l
2575 [PortReg] IANA, "Port Numbers",
2576 http://www.iana.org/assignments/port-numbers
2579 10. IANA Considerations
2581 It is requested that the Internet Assigned Numbers Authority (IANA)
2582 update the LDAP result code registry to indicate that this document
2583 provides the definitive technical specification for result codes 0-
2584 36, 48-54, 64-70, 80-90. It is also noted that one resultCode value
2585 (strongAuthRequired) has been renamed (to strongerAuthRequired).
2587 It is requested that the IANA update the LDAP Protocol Mechanism
2588 registry to indicate that this document and [AuthMeth] provides the
2589 definitive technical specification for the StartTLS
2590 (1.3.6.1.4.1.1466.20037) Extended operation.
2592 Sermersheim Internet-Draft - Expires Nov 2005 Page 44
2594 Lightweight Directory Access Protocol Version 3
2597 It is requested that the IANA update the occurrence of "RFC XXXX" in
2598 Appendix B with this RFC number at publication.
2601 11. Editor's Address
2605 1800 South Novell Place
2606 Provo, Utah 84606, USA
2651 Sermersheim Internet-Draft - Expires Nov 2005 Page 45
2653 Lightweight Directory Access Protocol Version 3
2655 Appendix A - LDAP Result Codes
2657 This normative appendix details additional considerations regarding
2658 LDAP result codes and provides a brief, general description of each
2659 LDAP result code enumerated in Section 4.1.9.
2661 Additional result codes MAY be defined for use with extensions
2662 [LDAPIANA]. Client implementations SHALL treat any result code which
2663 they do not recognize as an unknown error condition.
2665 Servers may substitute some result codes due to access controls which
2666 prevent their disclosure.
2669 A.1 Non-Error Result Codes
2671 These result codes (called "non-error" result codes) do not indicate
2677 saslBindInProgress (14).
2679 The success, compareTrue, and compareFalse result codes indicate
2680 successful completion (and, hence, are referred to as "successful"
2683 The referral and saslBindInProgress result codes indicate the client
2684 needs to take additional action to complete the operation.
2689 Existing LDAP result codes are described as follows:
2692 Indicates the successful completion of an operation. Note:
2693 this code is not used with the Compare operation. See
2694 compareFalse (5) and compareTrue (6).
2697 Indicates that the operation is not properly sequenced with
2698 relation to other operations (of same or different type).
2700 For example, this code is returned if the client attempts to
2701 StartTLS [TLS] while there are other uncompleted operations
2702 or if a TLS layer was already installed.
2705 Indicates the server received data which is not well-formed.
2710 Sermersheim Internet-Draft - Expires Nov 2005 Page 46
2712 Lightweight Directory Access Protocol Version 3
2714 For Bind operation only, this code is also used to indicate
2715 that the server does not support the requested protocol
2718 For Extended operations only, this code is also used to
2719 indicate that the server does not support (by design or
2720 configuration) the Extended operation associated with the
2723 For request operations specifying multiple controls, this may
2724 be used to indicate that the server cannot ignore the order
2725 of the controls as specified, or that the combination of the
2726 specified controls is invalid or unspecified.
2728 timeLimitExceeded (3)
2729 Indicates that the time limit specified by the client was
2730 exceeded before the operation could be completed.
2732 sizeLimitExceeded (4)
2733 Indicates that the size limit specified by the client was
2734 exceeded before the operation could be completed.
2737 Indicates that the Compare operation has successfully
2738 completed and the assertion has evaluated to FALSE or
2742 Indicates that the Compare operation has successfully
2743 completed and the assertion has evaluated to TRUE.
2745 authMethodNotSupported (7)
2746 Indicates that the authentication method or mechanism is not
2749 strongerAuthRequired (8)
2750 Indicates the server requires strong(er) authentication in
2751 order to complete the operation.
2753 When used with the Notice of Disconnection operation, this
2754 code indicates that the server has detected that an
2755 established security association between the client and
2756 server has unexpectedly failed or been compromised.
2759 Indicates that a referral needs to be chased to complete the
2760 operation (see Section 4.1.10).
2762 adminLimitExceeded (11)
2763 Indicates that an administrative limit has been exceeded.
2765 unavailableCriticalExtension (12)
2766 Indicates a critical control is unrecognized (see Section
2769 Sermersheim Internet-Draft - Expires Nov 2005 Page 47
2771 Lightweight Directory Access Protocol Version 3
2774 confidentialityRequired (13)
2775 Indicates that data confidentiality protections are required.
2777 saslBindInProgress (14)
2778 Indicates the server requires the client to send a new bind
2779 request, with the same SASL mechanism, to continue the
2780 authentication process (see Section 4.2).
2782 noSuchAttribute (16)
2783 Indicates that the named entry does not contain the specified
2784 attribute or attribute value.
2786 undefinedAttributeType (17)
2787 Indicates that a request field contains an unrecognized
2788 attribute description.
2790 inappropriateMatching (18)
2791 Indicates that an attempt was made (e.g. in an assertion) to
2792 use a matching rule not defined for the attribute type
2795 constraintViolation (19)
2796 Indicates that the client supplied an attribute value which
2797 does not conform to the constraints placed upon it by the
2800 For example, this code is returned when multiple values are
2801 supplied to an attribute which has a SINGLE-VALUE constraint.
2803 attributeOrValueExists (20)
2804 Indicates that the client supplied an attribute or value to
2805 be added to an entry, but the attribute or value already
2808 invalidAttributeSyntax (21)
2809 Indicates that a purported attribute value does not conform
2810 to the syntax of the attribute.
2813 Indicates that the object does not exist in the DIT.
2816 Indicates that an alias problem has occurred. For example,
2817 the code may used to indicate an alias has been dereferenced
2818 which names no object.
2820 invalidDNSyntax (34)
2821 Indicates that an LDAPDN or RelativeLDAPDN field (e.g. search
2822 base, target entry, ModifyDN newrdn, etc.) of a request does
2823 not conform to the required syntax or contains attribute
2824 values which do not conform to the syntax of the attribute's
2828 Sermersheim Internet-Draft - Expires Nov 2005 Page 48
2830 Lightweight Directory Access Protocol Version 3
2833 aliasDereferencingProblem (36)
2834 Indicates that a problem occurred while dereferencing an
2835 alias. Typically an alias was encountered in a situation
2836 where it was not allowed or where access was denied.
2838 inappropriateAuthentication (48)
2839 Indicates the server requires the client which had attempted
2840 to bind anonymously or without supplying credentials to
2841 provide some form of credentials.
2843 invalidCredentials (49)
2844 Indicates that the provided credentials (e.g. the user's name
2845 and password) are invalid.
2847 insufficientAccessRights (50)
2848 Indicates that the client does not have sufficient access
2849 rights to perform the operation.
2852 Indicates that the server is too busy to service the
2856 Indicates that the server is shutting down or a subsystem
2857 necessary to complete the operation is offline.
2859 unwillingToPerform (53)
2860 Indicates that the server is unwilling to perform the
2864 Indicates that the server has detected an internal loop (e.g.
2865 while dereferencing aliases or chaining an operation).
2867 namingViolation (64)
2868 Indicates that the entry's name violates naming restrictions.
2870 objectClassViolation (65)
2871 Indicates that the entry violates object class restrictions.
2873 notAllowedOnNonLeaf (66)
2874 Indicates that the operation is inappropriately acting upon a
2877 notAllowedOnRDN (67)
2878 Indicates that the operation is inappropriately attempting to
2879 remove a value which forms the entry's relative distinguished
2882 entryAlreadyExists (68)
2883 Indicates that the request cannot be fulfilled (added, moved,
2884 or renamed) as the target entry already exists.
2887 Sermersheim Internet-Draft - Expires Nov 2005 Page 49
2889 Lightweight Directory Access Protocol Version 3
2892 objectClassModsProhibited (69)
2893 Indicates that an attempt to modify the object class(es) of
2894 an entry's 'objectClass' attribute is prohibited.
2896 For example, this code is returned when a client attempts to
2897 modify the structural object class of an entry.
2899 affectsMultipleDSAs (71)
2900 Indicates that the operation cannot be performed as it would
2901 affect multiple servers (DSAs).
2904 Indicates the server has encountered an internal error.
2946 Sermersheim Internet-Draft - Expires Nov 2005 Page 50
2948 Lightweight Directory Access Protocol Version 3
2950 Appendix B - Complete ASN.1 Definition
2952 This appendix is normative.
2954 Lightweight-Directory-Access-Protocol-V3
2955 -- Copyright (C) The Internet Society (2005). This version of
2956 -- this ASN.1 module is part of RFC XXXX; see the RFC itself
2957 -- for full legal notices.
2960 EXTENSIBILITY IMPLIED ::=
2964 LDAPMessage ::= SEQUENCE {
2965 messageID MessageID,
2967 bindRequest BindRequest,
2968 bindResponse BindResponse,
2969 unbindRequest UnbindRequest,
2970 searchRequest SearchRequest,
2971 searchResEntry SearchResultEntry,
2972 searchResDone SearchResultDone,
2973 searchResRef SearchResultReference,
2974 modifyRequest ModifyRequest,
2975 modifyResponse ModifyResponse,
2976 addRequest AddRequest,
2977 addResponse AddResponse,
2978 delRequest DelRequest,
2979 delResponse DelResponse,
2980 modDNRequest ModifyDNRequest,
2981 modDNResponse ModifyDNResponse,
2982 compareRequest CompareRequest,
2983 compareResponse CompareResponse,
2984 abandonRequest AbandonRequest,
2985 extendedReq ExtendedRequest,
2986 extendedResp ExtendedResponse,
2988 intermediateResponse IntermediateResponse },
2989 controls [0] Controls OPTIONAL }
2991 MessageID ::= INTEGER (0 .. maxInt)
2993 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
2995 LDAPString ::= OCTET STRING -- UTF-8 encoded,
2996 -- [ISO10646] characters
2998 LDAPOID ::= OCTET STRING -- Constrained to <numericoid> [Models]
3000 LDAPDN ::= LDAPString -- Constrained to <distinguishedName>
3005 Sermersheim Internet-Draft - Expires Nov 2005 Page 51
3007 Lightweight Directory Access Protocol Version 3
3009 RelativeLDAPDN ::= LDAPString -- Constrained to <name-component>
3012 AttributeDescription ::= LDAPString
3013 -- Constrained to <attributedescription>
3016 AttributeValue ::= OCTET STRING
3018 AttributeValueAssertion ::= SEQUENCE {
3019 attributeDesc AttributeDescription,
3020 assertionValue AssertionValue }
3022 AssertionValue ::= OCTET STRING
3024 PartialAttribute ::= SEQUENCE {
3025 type AttributeDescription,
3026 vals SET OF value AttributeValue }
3028 Attribute ::= PartialAttribute(WITH COMPONENTS {
3030 vals (SIZE(1..MAX))})
3032 MatchingRuleId ::= LDAPString
3064 Sermersheim Internet-Draft - Expires Nov 2005 Page 52
3066 Lightweight Directory Access Protocol Version 3
3068 LDAPResult ::= SEQUENCE {
3069 resultCode ENUMERATED {
3071 operationsError (1),
3073 timeLimitExceeded (3),
3074 sizeLimitExceeded (4),
3077 authMethodNotSupported (7),
3078 strongerAuthRequired (8),
3081 adminLimitExceeded (11),
3082 unavailableCriticalExtension (12),
3083 confidentialityRequired (13),
3084 saslBindInProgress (14),
3085 noSuchAttribute (16),
3086 undefinedAttributeType (17),
3087 inappropriateMatching (18),
3088 constraintViolation (19),
3089 attributeOrValueExists (20),
3090 invalidAttributeSyntax (21),
3094 invalidDNSyntax (34),
3095 -- 35 reserved for undefined isLeaf --
3096 aliasDereferencingProblem (36),
3098 inappropriateAuthentication (48),
3099 invalidCredentials (49),
3100 insufficientAccessRights (50),
3103 unwillingToPerform (53),
3106 namingViolation (64),
3107 objectClassViolation (65),
3108 notAllowedOnNonLeaf (66),
3109 notAllowedOnRDN (67),
3110 entryAlreadyExists (68),
3111 objectClassModsProhibited (69),
3112 -- 70 reserved for CLDAP --
3113 affectsMultipleDSAs (71),
3118 diagnosticMessage LDAPString,
3119 referral [3] Referral OPTIONAL }
3121 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI
3123 Sermersheim Internet-Draft - Expires Nov 2005 Page 53
3125 Lightweight Directory Access Protocol Version 3
3128 URI ::= LDAPString -- limited to characters permitted in
3131 Controls ::= SEQUENCE OF control Control
3133 Control ::= SEQUENCE {
3134 controlType LDAPOID,
3135 criticality BOOLEAN DEFAULT FALSE,
3136 controlValue OCTET STRING OPTIONAL }
3138 BindRequest ::= [APPLICATION 0] SEQUENCE {
3139 version INTEGER (1 .. 127),
3141 authentication AuthenticationChoice }
3143 AuthenticationChoice ::= CHOICE {
3144 simple [0] OCTET STRING,
3146 sasl [3] SaslCredentials,
3149 SaslCredentials ::= SEQUENCE {
3150 mechanism LDAPString,
3151 credentials OCTET STRING OPTIONAL }
3153 BindResponse ::= [APPLICATION 1] SEQUENCE {
3154 COMPONENTS OF LDAPResult,
3155 serverSaslCreds [7] OCTET STRING OPTIONAL }
3157 UnbindRequest ::= [APPLICATION 2] NULL
3159 SearchRequest ::= [APPLICATION 3] SEQUENCE {
3166 derefAliases ENUMERATED {
3167 neverDerefAliases (0),
3168 derefInSearching (1),
3169 derefFindingBaseObj (2),
3171 sizeLimit INTEGER (0 .. maxInt),
3172 timeLimit INTEGER (0 .. maxInt),
3175 attributes AttributeSelection }
3177 AttributeSelection ::= SEQUENCE OF selector LDAPString
3178 -- The LDAPString is constrained to
3179 -- <attributeSelector> in Section 4.5.1.7
3182 Sermersheim Internet-Draft - Expires Nov 2005 Page 54
3184 Lightweight Directory Access Protocol Version 3
3187 and [0] SET SIZE (1..MAX) OF filter Filter,
3188 or [1] SET SIZE (1..MAX) OF filter Filter,
3190 equalityMatch [3] AttributeValueAssertion,
3191 substrings [4] SubstringFilter,
3192 greaterOrEqual [5] AttributeValueAssertion,
3193 lessOrEqual [6] AttributeValueAssertion,
3194 present [7] AttributeDescription,
3195 approxMatch [8] AttributeValueAssertion,
3196 extensibleMatch [9] MatchingRuleAssertion,
3199 SubstringFilter ::= SEQUENCE {
3200 type AttributeDescription,
3201 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE {
3202 initial [0] AssertionValue, -- can occur at most once
3203 any [1] AssertionValue,
3204 final [2] AssertionValue } -- can occur at most once
3207 MatchingRuleAssertion ::= SEQUENCE {
3208 matchingRule [1] MatchingRuleId OPTIONAL,
3209 type [2] AttributeDescription OPTIONAL,
3210 matchValue [3] AssertionValue,
3211 dnAttributes [4] BOOLEAN DEFAULT FALSE }
3213 SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
3215 attributes PartialAttributeList }
3217 PartialAttributeList ::= SEQUENCE OF
3218 partialAttribute PartialAttribute
3220 SearchResultReference ::= [APPLICATION 19] SEQUENCE
3221 SIZE (1..MAX) OF uri URI
3223 SearchResultDone ::= [APPLICATION 5] LDAPResult
3225 ModifyRequest ::= [APPLICATION 6] SEQUENCE {
3227 changes SEQUENCE OF change SEQUENCE {
3228 operation ENUMERATED {
3233 modification PartialAttribute } }
3235 ModifyResponse ::= [APPLICATION 7] LDAPResult
3237 AddRequest ::= [APPLICATION 8] SEQUENCE {
3239 attributes AttributeList }
3241 Sermersheim Internet-Draft - Expires Nov 2005 Page 55
3243 Lightweight Directory Access Protocol Version 3
3246 AttributeList ::= SEQUENCE OF attribute Attribute
3248 AddResponse ::= [APPLICATION 9] LDAPResult
3250 DelRequest ::= [APPLICATION 10] LDAPDN
3252 DelResponse ::= [APPLICATION 11] LDAPResult
3254 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
3256 newrdn RelativeLDAPDN,
3257 deleteoldrdn BOOLEAN,
3258 newSuperior [0] LDAPDN OPTIONAL }
3260 ModifyDNResponse ::= [APPLICATION 13] LDAPResult
3262 CompareRequest ::= [APPLICATION 14] SEQUENCE {
3264 ava AttributeValueAssertion }
3266 CompareResponse ::= [APPLICATION 15] LDAPResult
3268 AbandonRequest ::= [APPLICATION 16] MessageID
3270 ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
3271 requestName [0] LDAPOID,
3272 requestValue [1] OCTET STRING OPTIONAL }
3274 ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
3275 COMPONENTS OF LDAPResult,
3276 responseName [10] LDAPOID OPTIONAL,
3277 responseValue [11] OCTET STRING OPTIONAL }
3279 IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
3280 responseName [0] LDAPOID OPTIONAL,
3281 responseValue [1] OCTET STRING OPTIONAL }
3300 Sermersheim Internet-Draft - Expires Nov 2005 Page 56
3302 Lightweight Directory Access Protocol Version 3
3304 Appendix C - Changes
3306 This appendix is non-normative.
3308 This appendix summarizes substantive changes made to RFC 2251, RFC
3312 C.1 Changes made to RFC 2251:
3314 This section summarizes the substantive changes made to Sections 1,
3315 2, 3.1, and 4 through the remainder of RFC 2251. Readers should
3316 consult [Models] and [AuthMeth] for summaries of changes to other
3320 C.1.1 Section 1 (Status of this Memo)
3322 - Removed IESG note. Post publication of RFC 2251, mandatory LDAP
3323 authentication mechanisms have been standardized which are
3324 sufficient to remove this note. See [AuthMeth] for authentication
3328 C.1.2 Section 3.1 (Protocol Model) and others
3330 - Removed notes giving history between LDAP v1, v2 and v3. Instead,
3331 added sufficient language so that this document can stand on its
3335 C.1.3 Section 4 (Elements of Protocol)
3337 - Clarified where the extensibility features of ASN.1 apply to the
3338 protocol. This change affected various ASN.1 types by the
3339 inclusion of ellipses (...) to certain elements.
3340 - Removed the requirement that servers which implement version 3 or
3341 later MUST provide the 'supportedLDAPVersion' attribute. This
3342 statement provided no interoperability advantages.
3345 C.1.4 Section 4.1.1 (Message Envelope)
3347 - There was a mandatory requirement for the server to return a
3348 Notice of Disconnection and drop the transport connection when a
3349 PDU is malformed in a certain way. This has been updated such that
3350 the server SHOULD return the Notice of Disconnection, and MUST
3351 terminate the LDAP Session.
3354 C.1.5 Section 4.1.1.1 (Message ID)
3356 - Required that the messageID of requests MUST be non-zero as the
3357 zero is reserved for Notice of Disconnection.
3359 Sermersheim Internet-Draft - Expires Nov 2005 Page 57
3361 Lightweight Directory Access Protocol Version 3
3363 - Specified when it is and isn't appropriate to return an already
3364 used message id. RFC 2251 accidentally imposed synchronous server
3365 behavior in its wording of this.
3368 C.1.6 Section 4.1.2 (String Types)
3370 - Stated that LDAPOID is constrained to <numericoid> from [Models].
3373 C.1.7 Section 4.1.5.1 (Binary Option) and others
3375 - Removed the Binary Option from the specification. There are
3376 numerous interoperability problems associated with this method of
3377 alternate attribute type encoding. Work to specify a suitable
3378 replacement is ongoing.
3381 C.1.8 Section 4.1.8 (Attribute)
3383 - Combined the definitions of PartialAttribute and Attribute here,
3384 and defined Attribute in terms of PartialAttribute.
3387 C.1.9 Section 4.1.10 (Result Message)
3389 - Renamed "errorMessage" to "diagnosticMessage" as it is allowed to
3390 be sent for non-error results.
3391 - Moved some language into Appendix A, and refer the reader there.
3392 - Allowed matchedDN to be present for other result codes than those
3394 - renamed the code "strongAuthRequired" to "strongerAuthRequired" to
3395 clarify that this code may often be returned to indicate that a
3396 stronger authentication is needed to perform a given operation.
3399 C.1.10 Section 4.1.11 (Referral)
3401 - Defined referrals in terms of URIs rather than URLs.
3402 - Removed the requirement that all referral URIs MUST be equally
3403 capable of progressing the operation. The statement was ambiguous
3404 and provided no instructions on how to carry it out.
3405 - Added the requirement that clients MUST NOT loop between servers.
3406 - Clarified the instructions for using LDAPURLs in referrals, and in
3407 doing so added a recommendation that the scope part be present.
3408 - Removed imperatives which required clients to use URLs in specific
3409 ways to progress an operation. These did nothing for
3413 C.1.11 Section 4.1.12 (Controls)
3415 - Specified how control values defined in terms of ASN.1 are to be
3418 Sermersheim Internet-Draft - Expires Nov 2005 Page 58
3420 Lightweight Directory Access Protocol Version 3
3422 - Noted that the criticality field is only applied to request
3423 messages (except UnbindRequest), and must be ignored when present
3424 on response messages and UnbindRequest.
3425 - Specified that non-critical controls may be ignored at the
3426 server's discretion. There was confusion in the original wording
3427 which led some to believe that recognized controls may not be
3428 ignored as long as they were associated with a proper request.
3429 - Added language regarding combinations of controls and the ordering
3430 of controls on a message.
3431 - Specified that when the semantics of the combination of controls
3432 is undefined or unknown, it results in a protocolError.
3433 - Changed "The server MUST be prepared" to "Implementations MUST be
3434 prepared" in the eighth paragraph to reflect that both client and
3435 server implementations must be able to handle this (as both parse
3439 C.1.12 Section 4.2 (Bind Operation)
3441 - Mandated that servers return protocolError when the version is not
3443 - Disambiguated behavior when the simple authentication is used, the
3444 name is empty and the password is non-empty.
3445 - Required servers to not dereference aliases for Bind. This was
3446 added for consistency with other operations and to help ensure
3448 - Required that textual passwords be transferred as UTF-8 encoded
3449 Unicode, and added recommendations on string preparation. This was
3450 to help ensure interoperability of passwords being sent from
3454 C.1.13 Section 4.2.1 (Sequencing of the Bind Request)
3456 - This section was largely reorganized for readability and language
3457 was added to clarify the authentication state of failed and
3458 abandoned Bind operations.
3459 - Removed: "If a SASL transfer encryption or integrity mechanism has
3460 been negotiated, that mechanism does not support the changing of
3461 credentials from one identity to another, then the client MUST
3462 instead establish a new connection."
3463 If there are dependencies between multiple negotiations of a
3464 particular SASL mechanism, the technical specification for that
3465 SASL mechanism details how applications are to deal with them.
3466 LDAP should not require any special handling.
3467 - Dropped MUST imperative in paragraph 3 to align with [Keywords].
3468 - Mandated that clients not send non-Bind operations while a Bind is
3469 in progress, and suggested that servers not process them if they
3470 are received. This is needed to ensure proper sequencing of the
3471 Bind in relationship to other operations.
3477 Sermersheim Internet-Draft - Expires Nov 2005 Page 59
3479 Lightweight Directory Access Protocol Version 3
3481 C.1.14 Section 4.2.3 (Bind Response)
3483 - Moved most error-related text to Appendix A, and added text
3484 regarding certain errors used in conjunction with the Bind
3486 - Prohibited the server from specifying serverSaslCreds when not
3490 C.1.15 Section 4.3 (Unbind Operation)
3492 - Specified that both peers are to cease transmission and terminate
3493 the LDAP session for the Unbind operation.
3496 C.1.16 Section 4.4 (Unsolicited Notification)
3498 - Added instructions for future specifications of Unsolicited
3502 C.1.17 Section 4.5.1 (Search Request)
3504 - SearchRequest attributes is now defined as an AttributeSelection
3505 type rather than AttributeDescriptionList, and an ABNF is
3507 - SearchRequest attributes may contain duplicate attribute
3508 descriptions. This was previously prohibited. Now servers are
3509 instructed to ignore subsequent names when they are duplicated.
3510 This was relaxed in order to allow different short names and also
3511 OIDs to be requested for an attribute.
3512 - The present search filter now evaluates to Undefined when the
3513 specified attribute is not known to the server. It used to
3514 evaluate to FALSE, which caused behavior inconsistent with what
3515 most would expect, especially when the not operator was used.
3516 - The Filter choice SubstringFilter substrings type is now defined
3517 with a lower bound of 1.
3518 - The SubstringFilter substrings 'initial, 'any', and 'final' types
3519 are now AssertionValue rather than LDAPString. Also, added
3520 imperatives stating that 'initial' (if present) must be listed
3521 first, and 'final' (if present) must be listed last.
3522 - Disambiguated the semantics of the derefAliases choices. There was
3523 question as to whether derefInSearching applied to the base object
3524 in a wholeSubtree Search.
3525 - Added instructions for equalityMatch, substrings, greaterOrEqual,
3526 lessOrEqual, and approxMatch.
3529 C.1.18 Section 4.5.2 (Search Result)
3531 - Recommended that servers not use attribute short names when it
3532 knows they are ambiguous or may cause interoperability problems.
3533 - Removed all mention of ExtendedResponse due to lack of
3536 Sermersheim Internet-Draft - Expires Nov 2005 Page 60
3538 Lightweight Directory Access Protocol Version 3
3542 C.1.19 Section 4.5.3 (Continuation References in the Search Result)
3544 - Made changes similar to those made to Section 4.1.11.
3547 C.1.20 Section 4.5.3.1 (Example)
3549 - Fixed examples to adhere to changes made to Section 4.5.3.
3552 C.1.21 Section 4.6 (Modify Operation)
3554 - Replaced AttributeTypeAndValues with Attribute as they are
3556 - Specified the types of modification changes which might
3557 temporarily violate schema. Some readers were under the impression
3558 that any temporary schema violation was allowed.
3561 C.1.22 Section 4.7 (Add Operation)
3563 - Aligned Add operation with X.511 in that the attributes of the RDN
3564 are used in conjunction with the listed attributes to create the
3565 entry. Previously, Add required that the distinguished values be
3566 present in the listed attributes.
3567 - Removed requirement that the objectClass attribute MUST be
3568 specified as some DSE types do not require this attribute.
3569 Instead, generic wording was added, requiring the added entry to
3570 adhere to the data model.
3571 - Removed recommendation regarding placement of objects. This is
3572 covered in the data model document.
3575 C.1.23 Section 4.9 (Modify DN Operation)
3577 - Required servers to not dereference aliases for Modify DN. This
3578 was added for consistency with other operations and to help ensure
3580 - Allow Modify DN to fail when moving between naming contexts.
3581 - Specified what happens when the attributes of the newrdn are not
3582 present on the entry.
3585 C.1.24 Section 4.10 (Compare Operation)
3587 - Specified that compareFalse means that the Compare took place and
3588 the result is false. There was confusion which lead people to
3589 believe that an Undefined match resulted in compareFalse.
3590 - Required servers to not dereference aliases for Compare. This was
3591 added for consistency with other operations and to help ensure
3595 Sermersheim Internet-Draft - Expires Nov 2005 Page 61
3597 Lightweight Directory Access Protocol Version 3
3600 C.1.25 Section 4.11 (Abandon Operation)
3602 - Explained that since Abandon returns no response, clients should
3603 not use it if they need to know the outcome.
3604 - Specified that Abandon and Unbind cannot be abandoned.
3607 C.1.26 Section 4.12 (Extended Operation)
3609 - Specified how values of Extended operations defined in terms of
3610 ASN.1 are to be encoded.
3611 - Added instructions on what Extended operation specifications
3613 - Added a recommendation that servers advertise supported Extended
3617 C.1.27 Section 5.2 (Transfer Protocols)
3619 - Moved referral-specific instructions into referral-related
3623 C.1.28 Section 7 (Security Considerations)
3625 - Reworded notes regarding SASL not protecting certain aspects of
3626 the LDAP Bind messages.
3627 - Noted that Servers are encouraged to prevent directory
3628 modifications by clients that have authenticated anonymously
3630 - Added a note regarding the possibility of changes to security
3631 factors (authentication, authorization, data confidentiality).
3632 - Warned against following referrals that may have been injected in
3634 - Noted that servers should protect information equally, whether in
3635 an error condition or not, and mentioned specifically; matchedDN,
3636 diagnosticMessage, and resultCodes.
3637 - Added a note regarding malformed and long encodings.
3640 C.1.29 Appendix A (Complete ASN.1 Definition)
3642 - Added "EXTENSIBILITY IMPLIED" to ASN.1 definition.
3643 - Removed AttributeType. It is not used.
3646 C.2 Changes made to RFC 2830:
3648 This section summarizes the substantive changes made to Sections of
3649 RFC 2830. Readers should consult [AuthMeth] for summaries of changes
3654 Sermersheim Internet-Draft - Expires Nov 2005 Page 62
3656 Lightweight Directory Access Protocol Version 3
3658 C.2.1 Section 2.3 (Response other than "success")
3660 - Removed wording indicating that referrals can be returned from
3662 - Removed requirement that only a narrow set of result codes can be
3663 returned. Some result codes are required in certain scenarios, but
3664 any other may be returned if appropriate.
3667 C.2.1 Section 4 (Closing a TLS Connection)
3669 - Reworded most of this section to align with definitions of the
3670 LDAP protocol layers.
3671 - Removed instructions on abrupt closure as this is covered in other
3672 areas of the document (specifically, Section 5.3)
3675 C.3 Changes made to RFC 3771:
3677 - Rewrote to fit into this document. In general, semantics were
3678 preserved. Supporting and background language seen as redundant
3679 due to its presence in this document was omitted.
3680 - Specified that Intermediate responses to a request may be of
3681 different types, and one of the response types may be specified to
3682 have no response value.
3713 Sermersheim Internet-Draft - Expires Nov 2005 Page 63
3715 Lightweight Directory Access Protocol Version 3
3720 Intellectual Property Statement
3722 The IETF takes no position regarding the validity or scope of any
3723 Intellectual Property Rights or other rights that might be claimed to
3724 pertain to the implementation or use of the technology described in
3725 this document or the extent to which any license under such rights
3726 might or might not be available; nor does it represent that it has
3727 made any independent effort to identify any such rights. Information
3728 on the procedures with respect to rights in RFC documents can be
3729 found in BCP 78 and BCP 79.
3731 Copies of IPR disclosures made to the IETF Secretariat and any
3732 assurances of licenses to be made available, or the result of an
3733 attempt made to obtain a general license or permission for the use of
3734 such proprietary rights by implementers or users of this
3735 specification can be obtained from the IETF on-line IPR repository at
3736 <http://www.ietf.org/ipr>.
3738 The IETF invites any interested party to bring to its attention any
3739 copyrights, patents or patent applications, or other proprietary
3740 rights that may cover technology that may be required to implement
3741 this standard. Please address the information to the IETF at ietf-
3744 Disclaimer of Validity
3746 This document and the information contained herein are provided on an
3747 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
3748 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
3749 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
3750 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
3751 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
3752 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
3756 Copyright (C) The Internet Society (2005). This document is subject
3757 to the rights, licenses and restrictions contained in BCP 78, and
3758 except as set forth therein, the authors retain all their rights.
3762 Funding for the RFC Editor function is currently provided by the
3772 Sermersheim Internet-Draft - Expires Nov 2005 Page 64
projects / openldap / blob