2 Internet-Draft Editor: J. Sermersheim
3 Intended Category: Standard Track Novell, Inc
4 Document: draft-ietf-ldapbis-protocol-26.txt Aug 2004
5 Obsoletes: RFCs 2251, 2830, 3771
13 This document is an Internet-Draft and is subject to all provisions
14 of section 3 of RFC 3667. By submitting this Internet-Draft, each
15 author represents that any applicable patent or other IPR claims of
16 which he or she is aware have been or will be disclosed, and any of
17 which he or she become aware will be disclosed, in accordance with
20 Internet-Drafts are working documents of the Internet Engineering
21 Task Force (IETF), its areas, and its working groups. Note that
22 other groups may also distribute working documents as Internet-
25 Internet-Drafts are draft documents valid for a maximum of six months
26 and may be updated, replaced, or obsoleted by other documents at any
27 time. It is inappropriate to use Internet-Drafts as reference
28 material or to cite them other than as "work in progress."
30 The list of current Internet-Drafts can be accessed at
31 http://www.ietf.org/ietf/1id-abstracts.txt.
33 The list of Internet-Draft Shadow Directories can be accessed at
34 http://www.ietf.org/shadow.html.
36 Technical discussion of this document will take place on the IETF
37 LDAP Revision Working Group (LDAPbis) mailing list <ietf-
38 ldapbis@openldap.org>. Please send editorial comments directly to the
39 editor <jimse@novell.com>.
44 Copyright (C) The Internet Society 2004.
48 This document describes the protocol elements, along with their
49 semantics and encodings, of the Lightweight Directory Access Protocol
50 (LDAP). LDAP provides access to distributed directory services that
51 act in accordance with X.500 data and service models. These protocol
52 elements are based on those described in the X.500 Directory Access
57 Sermersheim Internet-Draft - Expires Feb 2005 Page 1
59 Lightweight Directory Access Protocol Version 3
63 1. Introduction....................................................3
64 1.1. Relationship to Obsolete Specifications.......................3
65 2. Conventions.....................................................3
66 3. Protocol Model..................................................4
67 3.1 Operation and LDAP Exchange Relationship.......................4
68 4. Elements of Protocol............................................5
69 4.1. Common Elements...............................................5
70 4.1.1. Message Envelope............................................5
71 4.1.2. String Types................................................7
72 4.1.3. Distinguished Name and Relative Distinguished Name..........7
73 4.1.4. Attribute Descriptions......................................7
74 4.1.5. Attribute Value.............................................8
75 4.1.6. Attribute Value Assertion...................................8
76 4.1.7. Attribute and PartialAttribute..............................9
77 4.1.8. Matching Rule Identifier....................................9
78 4.1.9. Result Message..............................................9
79 4.1.10. Referral..................................................11
80 4.1.11. Controls..................................................12
81 4.2. Bind Operation...............................................14
82 4.3. Unbind Operation.............................................17
83 4.4. Unsolicited Notification.....................................17
84 4.5. Search Operation.............................................18
85 4.6. Modify Operation.............................................27
86 4.7. Add Operation................................................28
87 4.8. Delete Operation.............................................29
88 4.9. Modify DN Operation..........................................30
89 4.10. Compare Operation...........................................31
90 4.11. Abandon Operation...........................................32
91 4.12. Extended Operation..........................................32
92 4.13. IntermediateResponse Message................................34
93 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse......35
94 4.13.2. Usage with LDAP Request Controls..........................35
95 4.14. StartTLS Operation..........................................35
96 5. Protocol Encoding, Connection, and Transfer....................37
97 5.2. Protocol Encoding............................................38
98 5.3. Transmission Control Protocol (TCP)..........................38
99 6. Security Considerations........................................39
100 7. Acknowledgements...............................................40
101 8. Normative References...........................................40
102 9. Informative References.........................................42
103 10. IANA Considerations...........................................42
104 11. Editor's Address..............................................43
105 Appendix A - LDAP Result Codes....................................44
106 A.1 Non-Error Result Codes........................................44
107 A.2 Result Codes..................................................44
108 Appendix B - Complete ASN.1 Definition............................49
109 Appendix C - Changes..............................................55
110 C.1 Changes made to RFC 2251:.....................................55
111 C.2 Changes made to RFC 2830:.....................................60
112 C.3 Changes made to RFC 3771:.....................................61
116 Sermersheim Internet-Draft - Expires Feb 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 Obsolete 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 obsoletes all of RFC 2251 except the following:
143 Sections 3.2, 3.4, 4.1.3 (last paragraph), 4.1.4, 4.1.5, 4.1.5.1,
144 4.1.9 (last paragraph), 5.1, 6.1, and 6.2 (last paragraph) are
145 obsoleted by [Models].
146 Section 3.3 is obsoleted by [Roadmap].
147 Sections 4.2.1 (portions), and 4.2.2 are obsoleted by [AuthMeth].
149 Appendix C.1 summarizes substantive changes to the remaining
152 This document obsoletes RFC 2830, Sections 2 and 4 in entirety. The
153 remainder of RFC 2830 is obsoleted by [AuthMeth]. Appendix C.2
154 summarizes substantive changes to the remaining sections.
156 This document also obsoletes RFC 3771 in entirety.
161 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
162 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
163 to be interpreted as described in [Keyword].
165 The term "connection" refers to the underlying transport service used
166 to carry the protocol exchange.
168 The term "LDAP exchange" refers to application layer where LDAP PDUs
169 are exchanged between protocol peers.
171 The term "TLS layer" refers to a layer inserted between the
172 connection and the LDAP exchange that utilizes Transport Layer
173 Security ([TLS]) to protect the exchange of LDAP PDUs.
175 Sermersheim Internet-Draft - Expires Feb 2005 Page 3
177 Lightweight Directory Access Protocol Version 3
180 The term "SASL layer" refers to a layer inserted between the
181 connection and the LDAP exchange that utilizes Simple Authentication
182 and Security Layer ([SASL]) to protect the exchange of LDAP PDUs.
184 See the table in Section 5 for an illustration of these four terms.
186 The term "TLS-protected LDAP exchange" refers to an LDAP exchange
187 protected by a TLS-layer.
189 The term "association" refers to the association of the LDAP exchange
190 and its current authentication and authorization state.
192 Character names in this document use the notation for code points and
193 names from the Unicode Standard [Unicode]. For example, the letter
194 "a" may be represented as either <U+0061> or <LATIN SMALL LETTER A>.
196 Note: a glossary of terms used in Unicode can be found in [Glossary].
197 Information on the Unicode character encoding model can be found in
203 The general model adopted by this protocol is one of clients
204 performing protocol operations against servers. In this model, a
205 client transmits a protocol request describing the operation to be
206 performed to a server. The server is then responsible for performing
207 the necessary operation(s) in the Directory. Upon completion of an
208 operation, the server typically returns a response containing
209 appropriate data to the requesting client.
211 Protocol operations are generally independent of one another. Each
212 operation is processed as an atomic action, leaving the directory in
215 Although servers are required to return responses whenever such
216 responses are defined in the protocol, there is no requirement for
217 synchronous behavior on the part of either clients or servers.
218 Requests and responses for multiple operations generally may be
219 exchanged between a client and server in any order. If required,
220 synchronous behavior may be controlled by client applications.
222 The core protocol operations defined in this document can be mapped
223 to a subset of the X.500 (1993) Directory Abstract Service [X.511].
224 However there is not a one-to-one mapping between LDAP operations and
225 X.500 Directory Access Protocol (DAP) operations. Server
226 implementations acting as a gateway to X.500 directories may need to
227 make multiple DAP requests to service a single LDAP request.
230 3.1 Operation and LDAP Exchange Relationship
234 Sermersheim Internet-Draft - Expires Feb 2005 Page 4
236 Lightweight Directory Access Protocol Version 3
238 Protocol operations are tied to an LDAP exchange. When the connection
239 is closed, any uncompleted operations tied to the LDAP exchange are,
240 when possible, abandoned, and when not possible, completed without
241 transmission of the response. Also, when the connection is closed,
242 the client MUST NOT assume that any uncompleted update operations
243 tied to the LDAP exchange have succeeded or failed.
246 4. Elements of Protocol
248 The protocol is described using Abstract Syntax Notation One
249 ([ASN.1]), and is transferred using a subset of ASN.1 Basic Encoding
250 Rules ([BER]). Section 5 specifies how the protocol elements are
251 encoded and transferred.
253 In order to support future extensions to this protocol, extensibility
254 is implied where it is allowed per ASN.1 (i.e. sequence, set, choice,
255 and enumerated types are extensible). In addition, ellipses (...)
256 have been supplied in ASN.1 types that are explicitly extensible as
257 discussed in [LDAPIANA]. Because of the implied extensibility,
258 clients and servers MUST (unless otherwise specified) ignore trailing
259 SEQUENCE components whose tags they do not recognize.
261 Changes to the protocol other than through the extension mechanisms
262 described here require a different version number. A client indicates
263 the version it is using as part of the bind request, described in
264 Section 4.2. If a client has not sent a bind, the server MUST assume
265 the client is using version 3 or later.
267 Clients may determine the protocol versions a server supports by
268 reading the 'supportedLDAPVersion' attribute from the root DSE (DSA-
269 Specific Entry) [Models].
274 This section describes the LDAPMessage envelope Protocol Data Unit
275 (PDU) format, as well as data type definitions, which are used in the
279 4.1.1. Message Envelope
281 For the purposes of protocol exchanges, all protocol operations are
282 encapsulated in a common envelope, the LDAPMessage, which is defined
285 LDAPMessage ::= SEQUENCE {
288 bindRequest BindRequest,
289 bindResponse BindResponse,
290 unbindRequest UnbindRequest,
291 searchRequest SearchRequest,
293 Sermersheim Internet-Draft - Expires Feb 2005 Page 5
295 Lightweight Directory Access Protocol Version 3
297 searchResEntry SearchResultEntry,
298 searchResDone SearchResultDone,
299 searchResRef SearchResultReference,
300 modifyRequest ModifyRequest,
301 modifyResponse ModifyResponse,
302 addRequest AddRequest,
303 addResponse AddResponse,
304 delRequest DelRequest,
305 delResponse DelResponse,
306 modDNRequest ModifyDNRequest,
307 modDNResponse ModifyDNResponse,
308 compareRequest CompareRequest,
309 compareResponse CompareResponse,
310 abandonRequest AbandonRequest,
311 extendedReq ExtendedRequest,
312 extendedResp ExtendedResponse,
314 intermediateResponse IntermediateResponse },
315 controls [0] Controls OPTIONAL }
317 MessageID ::= INTEGER (0 .. maxInt)
319 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
321 The ASN.1 type Controls is defined in Section 4.1.11.
323 The function of the LDAPMessage is to provide an envelope containing
324 common fields required in all protocol exchanges. At this time the
325 only common fields are the messageID and the controls.
327 If the server receives a PDU from the client in which the LDAPMessage
328 SEQUENCE tag cannot be recognized, the messageID cannot be parsed,
329 the tag of the protocolOp is not recognized as a request, or the
330 encoding structures or lengths of data fields are found to be
331 incorrect, then the server SHOULD return the Notice of Disconnection
332 described in Section 4.4.1, with the resultCode set to protocolError,
333 and MUST immediately close the connection.
335 In other cases where the client or server cannot parse a PDU, it
336 SHOULD abruptly close the connection where further communication
337 (including providing notice) would be pernicious. Otherwise, server
338 implementations MUST return an appropriate response to the request,
339 with the resultCode set to protocolError.
344 All LDAPMessage envelopes encapsulating responses contain the
345 messageID value of the corresponding request LDAPMessage.
347 The message ID of a request MUST have a non-zero value different from
348 the values of any other uncompleted requests in the LDAP association
349 of which this message is a part. The zero value is reserved for the
350 unsolicited notification message.
352 Sermersheim Internet-Draft - Expires Feb 2005 Page 6
354 Lightweight Directory Access Protocol Version 3
357 Typical clients increment a counter for each request.
359 A client MUST NOT send a request with the same message ID as an
360 earlier request on the same LDAP association unless it can be
361 determined that the server is no longer servicing the earlier request
362 (e.g. after the final response is received, or a subsequent bind
363 completes). Otherwise the behavior is undefined. For this purpose,
364 note that abandon and abandoned operations do not send responses.
369 The LDAPString is a notational convenience to indicate that, although
370 strings of LDAPString type encode as ASN.1 OCTET STRING types, the
371 [ISO10646] character set (a superset of [Unicode]) is used, encoded
372 following the [UTF-8] algorithm. Note that Unicode characters U+0000
373 through U+007F are the same as ASCII 0 through 127, respectively, and
374 have the same single octet UTF-8 encoding. Other Unicode characters
375 have a multiple octet UTF-8 encoding.
377 LDAPString ::= OCTET STRING -- UTF-8 encoded,
378 -- [ISO10646] characters
380 The LDAPOID is a notational convenience to indicate that the
381 permitted value of this string is a (UTF-8 encoded) dotted-decimal
382 representation of an OBJECT IDENTIFIER. Although an LDAPOID is
383 encoded as an OCTET STRING, values are limited to the definition of
384 <numericoid> given in Section 1.4 of [Models].
386 LDAPOID ::= OCTET STRING -- Constrained to <numericoid> [Models]
390 1.3.6.1.4.1.1466.1.2.3
393 4.1.3. Distinguished Name and Relative Distinguished Name
395 An LDAPDN is defined to be the representation of a Distinguished Name
396 (DN) after encoding according to the specification in [LDAPDN].
398 LDAPDN ::= LDAPString
399 -- Constrained to <distinguishedName> [LDAPDN]
401 A RelativeLDAPDN is defined to be the representation of a Relative
402 Distinguished Name (RDN) after encoding according to the
403 specification in [LDAPDN].
405 RelativeLDAPDN ::= LDAPString
406 -- Constrained to <name-component> [LDAPDN]
409 4.1.4. Attribute Descriptions
411 Sermersheim Internet-Draft - Expires Feb 2005 Page 7
413 Lightweight Directory Access Protocol Version 3
416 The definition and encoding rules for attribute descriptions are
417 defined in Section 2.5 of [Models]. Briefly, an attribute description
418 is an attribute type and zero or more options.
420 AttributeDescription ::= LDAPString
421 -- Constrained to <attributedescription>
425 4.1.5. Attribute Value
427 A field of type AttributeValue is an OCTET STRING containing an
428 encoded attribute value. The attribute value is encoded according to
429 the LDAP-specific encoding definition of its corresponding syntax.
430 The LDAP-specific encoding definitions for different syntaxes and
431 attribute types may be found in other documents and in particular
434 AttributeValue ::= OCTET STRING
436 Note that there is no defined limit on the size of this encoding;
437 thus protocol values may include multi-megabyte attribute values
440 Attribute values may be defined which have arbitrary and non-
441 printable syntax. Implementations MUST NOT display nor attempt to
442 decode an attribute value if its syntax is not known. The
443 implementation may attempt to discover the subschema of the source
444 entry, and retrieve the descriptions of 'attributeTypes' from it
447 Clients MUST only send attribute values in a request that are valid
448 according to the syntax defined for the attributes.
451 4.1.6. Attribute Value Assertion
453 The AttributeValueAssertion (AVA) type definition is similar to the
454 one in the X.500 Directory standards. It contains an attribute
455 description and a matching rule ([Models Section 4.1.3) assertion
456 value suitable for that type. Elements of this type are typically
457 used to assert that the value in assertionValue matches a value of an
460 AttributeValueAssertion ::= SEQUENCE {
461 attributeDesc AttributeDescription,
462 assertionValue AssertionValue }
464 AssertionValue ::= OCTET STRING
466 The syntax of the AssertionValue depends on the context of the LDAP
467 operation being performed. For example, the syntax of the EQUALITY
468 matching rule for an attribute is used when performing a Compare
470 Sermersheim Internet-Draft - Expires Feb 2005 Page 8
472 Lightweight Directory Access Protocol Version 3
474 operation. Often this is the same syntax used for values of the
475 attribute type, but in some cases the assertion syntax differs from
476 the value syntax. See objectIdentiferFirstComponentMatch in
477 [Syntaxes] for an example.
480 4.1.7. Attribute and PartialAttribute
482 Attributes and partial attributes consist of an attribute description
483 and attribute values. A PartialAttribute allows zero values, while
484 Attribute requires at least one value.
486 PartialAttribute ::= SEQUENCE {
487 type AttributeDescription,
488 vals SET OF value AttributeValue }
490 Attribute ::= PartialAttribute(WITH COMPONENTS {
492 vals (SIZE(1..MAX))})
494 No two attribute values may be equivalent as described by Section 2.3
495 of [Models]. The set of attribute values is unordered.
496 Implementations MUST NOT rely upon the ordering being repeatable.
499 4.1.8. Matching Rule Identifier
501 Matching rules are defined in Section 4.1.3 of [Models]. A matching
502 rule is identified in the protocol by the printable representation of
503 either its <numericoid>, or one of its short name descriptors
504 [Models], e.g. 'caseIgnoreMatch' or '2.5.13.2'.
506 MatchingRuleId ::= LDAPString
509 4.1.9. Result Message
511 The LDAPResult is the construct used in this protocol to return
512 success or failure indications from servers to clients. To various
513 requests, servers will return responses of LDAPResult or responses
514 containing the components of LDAPResult to indicate the final status
515 of a protocol operation request.
517 LDAPResult ::= SEQUENCE {
518 resultCode ENUMERATED {
522 timeLimitExceeded (3),
523 sizeLimitExceeded (4),
526 authMethodNotSupported (7),
527 strongAuthRequired (8),
529 Sermersheim Internet-Draft - Expires Feb 2005 Page 9
531 Lightweight Directory Access Protocol Version 3
535 adminLimitExceeded (11),
536 unavailableCriticalExtension (12),
537 confidentialityRequired (13),
538 saslBindInProgress (14),
539 noSuchAttribute (16),
540 undefinedAttributeType (17),
541 inappropriateMatching (18),
542 constraintViolation (19),
543 attributeOrValueExists (20),
544 invalidAttributeSyntax (21),
548 invalidDNSyntax (34),
549 -- 35 reserved for undefined isLeaf --
550 aliasDereferencingProblem (36),
552 inappropriateAuthentication (48),
553 invalidCredentials (49),
554 insufficientAccessRights (50),
557 unwillingToPerform (53),
560 namingViolation (64),
561 objectClassViolation (65),
562 notAllowedOnNonLeaf (66),
563 notAllowedOnRDN (67),
564 entryAlreadyExists (68),
565 objectClassModsProhibited (69),
566 -- 70 reserved for CLDAP --
567 affectsMultipleDSAs (71),
572 diagnosticMessage LDAPString,
573 referral [3] Referral OPTIONAL }
575 The resultCode enumeration is extensible as defined in Section 3.6 of
576 [LDAPIANA]. The meanings of the listed result codes are given in
577 Appendix A. If a server detects multiple errors for an operation,
578 only one result code is returned. The server should return the result
579 code that best indicates the nature of the error encountered.
581 The diagnosticMessage field of this construct may, at the server's
582 option, be used to return a string containing a textual, human-
583 readable (terminal control and page formatting characters should be
584 avoided) diagnostic message. As this diagnostic message is not
585 standardized, implementations MUST NOT rely on the values returned.
588 Sermersheim Internet-Draft - Expires Feb 2005 Page 10
590 Lightweight Directory Access Protocol Version 3
592 If the server chooses not to return a textual diagnostic, the
593 diagnosticMessage field MUST be empty.
595 For certain result codes (typically, but not restricted to
596 noSuchObject, aliasProblem, invalidDNSyntax and
597 aliasDereferencingProblem), the matchedDN field is set to the name of
598 the lowest entry (object or alias) in the Directory that was matched.
599 If no aliases were dereferenced while attempting to locate the entry,
600 this will be a truncated form of the name provided, or if aliases
601 were dereferenced, of the resulting name, as defined in Section 12.5
602 of [X.511]. Otherwise the matchedDN field is empty.
607 The referral result code indicates that the contacted server cannot
608 or will not perform the operation and that one or more other servers
609 may be able to. Reasons for this include:
611 - The target entry of the request is not held locally, but the
612 server has knowledge of its possible existence elsewhere.
614 - The operation is restricted on this server -- perhaps due to a
615 read-only copy of an entry to be modified.
617 The referral field is present in an LDAPResult if the resultCode
618 field value is referral, and absent with all other result codes. It
619 contains one or more references to one or more servers or services
620 that may be accessed via LDAP or other protocols. Referrals can be
621 returned in response to any operation request (except unbind and
622 abandon which do not have responses). At least one URI MUST be
623 present in the Referral.
625 During a search operation, after the baseObject is located, and
626 entries are being evaluated, the referral is not returned. Instead,
627 continuation references, described in Section 4.5.3, are returned
628 when other servers would need to be contacted to complete the
631 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI
633 URI ::= LDAPString -- limited to characters permitted in
636 If the client wishes to progress the operation, it MUST follow the
637 referral by contacting one of the supported services. If multiple
638 URIs are present, the client assumes that any supported URI may be
639 used to progress the operation.
641 Protocol peers that follow referrals MUST ensure that they do not
642 loop between servers. They MUST NOT repeatedly contact the same
643 server for the same request with the same target entry name, scope
644 and filter. Some implementations use a counter that is incremented
645 each time referral handling occurs for an operation, and these kinds
647 Sermersheim Internet-Draft - Expires Feb 2005 Page 11
649 Lightweight Directory Access Protocol Version 3
651 of implementations MUST be able to handle at least ten nested
652 referrals between the root and a leaf entry.
654 A URI for a server implementing LDAP and accessible via [TCP]/[IP]
655 (v4 or v6) is written as an LDAP URL according to [LDAPURL].
657 When an LDAP URL is used, the following instructions are followed:
659 - If an alias was dereferenced, the <dn> part of the URL MUST be
660 present, with the new target object name. UTF-8 encoded characters
661 appearing in the string representation of a DN or search filter
662 may not be legal for URLs (e.g. spaces) and MUST be escaped using
663 the % method in [URI].
665 - It is RECOMMENDED that the <dn> part be present to avoid
668 - If the <dn> part is present, the client MUST use this name in its
669 next request to progress the operation, and if it is not present
670 the client will use the same name as in the original request.
672 - Some servers (e.g. participating in distributed indexing) may
673 provide a different filter in a URL of a referral for a search
676 - If the <filter> part of the LDAP URL is present, the client MUST
677 use this filter in its next request to progress this search, and
678 if it is not present the client MUST use the same filter as it
679 used for that search.
681 - For search, it is RECOMMENDED that the <scope> part be present to
684 - If the <scope> part is missing, the scope of the original search
685 is used by the client to progress the operation.
687 - Other aspects of the new request may be the same as or different
688 from the request which generated the referral.
690 Other kinds of URIs may be returned. The syntax and semantics of such
691 URIs is left to future specifications. Clients may ignore URIs that
697 Controls provide a mechanism whereby the semantics and arguments of
698 existing LDAP operations may be extended. One or more controls may be
699 attached to a single LDAP message. A control only affects the
700 semantics of the message it is attached to.
702 Controls sent by clients are termed 'request controls' and those sent
703 by servers are termed 'response controls'.
706 Sermersheim Internet-Draft - Expires Feb 2005 Page 12
708 Lightweight Directory Access Protocol Version 3
710 Controls ::= SEQUENCE OF control Control
712 Control ::= SEQUENCE {
714 criticality BOOLEAN DEFAULT FALSE,
715 controlValue OCTET STRING OPTIONAL }
717 The controlType field is the dotted-decimal representation of an
718 OBJECT IDENTIFIER which uniquely identifies the control. This
719 provides unambiguous naming of controls. Often, response control(s)
720 solicited by a request control share controlType values with the
723 The criticality field only has meaning in controls attached to
724 request messages (except unbindRequest). For controls attached to
725 response messages and the unbindRequest, the criticality field SHOULD
726 be FALSE, and MUST be ignored by the receiving protocol peer. A value
727 of TRUE indicates that it is unacceptable to perform the operation
728 without applying the semantics of the control and FALSE otherwise.
729 Specifically, the criticality field is applied as follows:
731 - Regardless of the value of the criticality field, if the server
732 recognizes the control type and it is appropriate for the
733 operation, the server is to make use of the control when
734 performing the operation.
736 - If the server does not recognize the control type or it is not
737 appropriate for the operation, and the criticality field is TRUE,
738 the server MUST NOT perform the operation, and for operations that
739 have a response message, MUST return unavailableCriticalExtension
742 - If the server does not recognize the control type or it is not
743 appropriate for the operation, and the criticality field is FALSE,
744 the server MUST ignore the control.
746 The controlValue may contain information associated with the
747 controlType. Its format is defined by the specification of the
748 control. Implementations MUST be prepared to handle arbitrary
749 contents of the controlValue octet string, including zero bytes. It
750 is absent only if there is no value information which is associated
751 with a control of its type. When a controlValue is defined in terms
752 of ASN.1, and BER encoded according to Section 5.2, it also follows
753 the extensibility rules in Section 4.
755 Servers list the controlType of request controls they recognize in
756 the 'supportedControl' attribute in the root DSE (Section 5.1 of
759 Controls SHOULD NOT be combined unless the semantics of the
760 combination has been specified. The semantics of control
761 combinations, if specified, are generally found in the control
762 specification most recently published. When a combination of controls
763 is encountered whose semantics are invalid, not specified (or not
765 Sermersheim Internet-Draft - Expires Feb 2005 Page 13
767 Lightweight Directory Access Protocol Version 3
769 known), the message is considered to be not well-formed, thus the
770 operation fails with protocolError. Additionally, unless order-
771 dependent semantics are given in a specification, the order of a
772 combination of controls in the SEQUENCE is ignored. Where the order
773 is to be ignored but cannot be ignored by the server, the message is
774 considered not well-formed and the operation fails with
777 This document does not specify any controls. Controls may be
778 specified in other documents. Documents detailing control extensions
779 are to provide for each control:
781 - the OBJECT IDENTIFIER assigned to the control,
783 - direction as to what value the sender should provide for the
784 criticality field (note: the semantics of the criticality field
785 are defined above should not be altered by the control's
788 - whether information is to be present in the controlValue field,
789 and if so, the format of the controlValue contents,
791 - the semantics of the control, and
793 - optionally, semantics regarding the combination of the control
799 The function of the Bind Operation is to allow authentication
800 information to be exchanged between the client and server. The Bind
801 operation should be thought of as the "authenticate" operation.
802 Operational, authentication, and security-related semantics of this
803 operation are given in [AuthMeth].
805 The Bind Request is defined as follows:
807 BindRequest ::= [APPLICATION 0] SEQUENCE {
808 version INTEGER (1 .. 127),
810 authentication AuthenticationChoice }
812 AuthenticationChoice ::= CHOICE {
813 simple [0] OCTET STRING,
815 sasl [3] SaslCredentials,
818 SaslCredentials ::= SEQUENCE {
819 mechanism LDAPString,
820 credentials OCTET STRING OPTIONAL }
822 Fields of the Bind Request are:
824 Sermersheim Internet-Draft - Expires Feb 2005 Page 14
826 Lightweight Directory Access Protocol Version 3
829 - version: A version number indicating the version of the protocol
830 to be used in this LDAP association. This document describes
831 version 3 of the protocol. There is no version negotiation. The
832 client sets this field to the version it desires. If the server
833 does not support the specified version, it MUST respond with
834 protocolError in the resultCode field of the BindResponse.
836 - name: The name of the Directory object that the client wishes to
837 bind as. This field may take on a null value (a zero length
838 string) for the purposes of anonymous binds ([AuthMeth] Section
839 5.1) or when using Simple Authentication and Security Layer [SASL]
840 authentication ([AuthMeth] Section 3.3.2). Where the server
841 attempts to locate the named object, it SHALL NOT perform alias
844 - authentication: information used in authentication. This type is
845 extensible as defined in Section 3.7 of [LDAPIANA]. Servers that
846 do not support a choice supplied by a client return
847 authMethodNotSupported in the resultCode field of the
850 Textual passwords (consisting of a character sequence with a known
851 character set and encoding) transferred to the server using the
852 simple AuthenticationChoice SHALL be transferred as [UTF-8]
853 encoded [Unicode]. Prior to transfer, clients SHOULD prepare text
854 passwords by applying the [SASLprep] profile of the [Stringprep]
855 algorithm. Passwords consisting of other data (such as random
856 octets) MUST NOT be altered. The determination of whether a
857 password is textual is a local client matter.
859 Authorization is the decision of which access an operation has to the
860 directory. Among other things, the process of authorization takes as
861 input authentication information obtained during the bind operation
862 and/or other acts of authentication (such as lower layer security
866 4.2.1. Processing of the Bind Request
868 Before processing a BindRequest, all uncompleted operations MUST
869 either complete or be abandoned. The server may either wait for the
870 uncompleted operations to complete, or abandon them. The server then
871 proceeds to authenticate the client in either a single-step, or
872 multi-step bind process. Each step requires the server to return a
873 BindResponse to indicate the status of authentication.
875 After sending a BindRequest, clients MUST NOT send further LDAP PDUs
876 until receiving the BindResponse. Similarly, servers SHOULD NOT
877 process or respond to requests received while processing a
880 If the client did not bind before sending a request and receives an
881 operationsError to that request, it may then send a Bind Request. If
883 Sermersheim Internet-Draft - Expires Feb 2005 Page 15
885 Lightweight Directory Access Protocol Version 3
887 this also fails or the client chooses not to bind on the existing
888 LDAP exchange, it may close the connection, reopen it and begin again
889 by first sending a PDU with a Bind Request. This will aid in
890 interoperating with servers implementing other versions of LDAP.
892 Clients may send multiple Bind Requests on an LDAP exchange to change
893 the authentication and/or security associations or to complete a
894 multi-stage bind process. Authentication from earlier binds is
895 subsequently ignored.
897 For some SASL authentication mechanisms, it may be necessary for the
898 client to invoke the BindRequest multiple times ([AuthMeth] Section
899 8.2). Clients MUST NOT invoke operations between two Bind Requests
900 made as part of a multi-stage bind.
902 A client may abort a SASL bind negotiation by sending a BindRequest
903 with a different value in the mechanism field of SaslCredentials, or
904 an AuthenticationChoice other than sasl.
906 If the client sends a BindRequest with the sasl mechanism field as an
907 empty string, the server MUST return a BindResponse with
908 authMethodNotSupported as the resultCode. This will allow clients to
909 abort a negotiation if it wishes to try again with the same SASL
915 The Bind Response is defined as follows.
917 BindResponse ::= [APPLICATION 1] SEQUENCE {
918 COMPONENTS OF LDAPResult,
919 serverSaslCreds [7] OCTET STRING OPTIONAL }
921 BindResponse consists simply of an indication from the server of the
922 status of the client's request for authentication.
924 A successful bind operation is indicated by a BindResponse with a
925 resultCode set to success. Otherwise, an appropriate result code is
926 set in the BindResponse. For bind, the protocolError result code may
927 be used to indicate that the version number supplied by the client is
930 If the client receives a BindResponse where the resultCode field is
931 protocolError, it is to assume that the server does not support this
932 version of LDAP. While the client may be able proceed with another
933 version of this protocol (this may or may not require closing and re-
934 establishing the connection), how to proceed with another version of
935 this protocol is beyond the scope of this document. Clients which are
936 unable or unwilling to proceed SHOULD close the connection.
938 The serverSaslCreds field is used as part of a SASL-defined bind
939 mechanism to allow the client to authenticate the server to which it
940 is communicating, or to perform "challenge-response" authentication.
942 Sermersheim Internet-Draft - Expires Feb 2005 Page 16
944 Lightweight Directory Access Protocol Version 3
946 If the client bound with the simple choice, or the SASL mechanism
947 does not require the server to return information to the client, then
948 this field SHALL NOT be included in the BindResponse.
951 4.3. Unbind Operation
953 The function of the Unbind Operation is to terminate an LDAP
954 association and close the connection. The Unbind operation is not the
955 antithesis of the Bind operation as the name implies. The naming of
956 these operations is historical. The Unbind operation should be
957 thought of as the "quit" operation.
959 The Unbind Operation is defined as follows:
961 UnbindRequest ::= [APPLICATION 2] NULL
963 The Unbind Operation has no response defined. Upon transmission of
964 the UnbindRequest, each protocol peer is to consider the LDAP
965 association terminated, MUST cease transmission of messages to the
966 other peer, and MUST close the connection. Uncompleted operations are
967 handled as specified in Section 5.1.
970 4.4. Unsolicited Notification
972 An unsolicited notification is an LDAPMessage sent from the server to
973 the client which is not in response to any LDAPMessage received by
974 the server. It is used to signal an extraordinary condition in the
975 server or in the LDAP exchange or connection between the client and
976 the server. The notification is of an advisory nature, and the server
977 will not expect any response to be returned from the client.
979 The unsolicited notification is structured as an LDAPMessage in which
980 the messageID is zero and protocolOp is of the extendedResp form (See
981 Section 4.12). The responseName field of the ExtendedResponse always
982 contains an LDAPOID which is unique for this notification.
984 One unsolicited notification (Notice of Disconnection) is defined in
985 this document. The specification of an unsolicited notification
988 - the OBJECT IDENTIFIER assigned to the notification (to be
989 specified in the responseName,
991 - the format of the contents (if any) of the responseValue,
993 - the circumstances which will cause the notification to be
996 - the semantics of the operation.
999 4.4.1. Notice of Disconnection
1001 Sermersheim Internet-Draft - Expires Feb 2005 Page 17
1003 Lightweight Directory Access Protocol Version 3
1006 This notification may be used by the server to advise the client that
1007 the server is about to close the connection due to an error
1008 condition. This notification is intended to assist clients in
1009 distinguishing between an error condition and a transient network
1010 failure. Note that this notification is not a response to an unbind
1011 requested by the client. Uncompleted operations are handled as
1012 specified in Section 5.1.
1014 The responseName is 1.3.6.1.4.1.1466.20036, the responseValue field
1015 is absent, and the resultCode is used to indicate the reason for the
1018 The following result codes have these meanings when used in this
1021 - protocolError: The server has received data from the client in
1022 which the LDAPMessage structure could not be parsed.
1024 - strongAuthRequired: The server has detected that an established
1025 security association between the client and server has
1026 unexpectedly failed or been compromised, or that the server now
1027 requires the client to authenticate using a strong(er) mechanism.
1029 - unavailable: This server will stop accepting new connections and
1030 operations on all existing LDAP exchanges, and be unavailable for
1031 an extended period of time. The client may make use of an
1034 Upon transmission of the Notice of Disconnection, the server is to
1035 consider the LDAP association terminated, MUST cease transmission of
1036 messages to the client, and MUST close the connection.
1039 4.5. Search Operation
1041 The Search Operation is used to request a server to return, subject
1042 to access controls and other restrictions, a set of entries matching
1043 a complex search criterion. This can be used to read attributes from
1044 a single entry, from entries immediately subordinate to a particular
1045 entry, or a whole subtree of entries.
1048 4.5.1. Search Request
1050 The Search Request is defined as follows:
1052 SearchRequest ::= [APPLICATION 3] SEQUENCE {
1058 derefAliases ENUMERATED {
1060 Sermersheim Internet-Draft - Expires Feb 2005 Page 18
1062 Lightweight Directory Access Protocol Version 3
1064 neverDerefAliases (0),
1065 derefInSearching (1),
1066 derefFindingBaseObj (2),
1068 sizeLimit INTEGER (0 .. maxInt),
1069 timeLimit INTEGER (0 .. maxInt),
1072 attributes AttributeSelection }
1074 AttributeSelection ::= SEQUENCE OF selector LDAPString
1075 -- The LDAPString is constrained to
1076 -- <attributeSelector> below
1079 and [0] SET SIZE (1..MAX) OF filter Filter,
1080 or [1] SET SIZE (1..MAX) OF filter Filter,
1082 equalityMatch [3] AttributeValueAssertion,
1083 substrings [4] SubstringFilter,
1084 greaterOrEqual [5] AttributeValueAssertion,
1085 lessOrEqual [6] AttributeValueAssertion,
1086 present [7] AttributeDescription,
1087 approxMatch [8] AttributeValueAssertion,
1088 extensibleMatch [9] MatchingRuleAssertion }
1090 SubstringFilter ::= SEQUENCE {
1091 type AttributeDescription,
1092 -- initial and final can occur at most once
1093 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE {
1094 initial [0] AssertionValue,
1095 any [1] AssertionValue,
1096 final [2] AssertionValue } }
1098 MatchingRuleAssertion ::= SEQUENCE {
1099 matchingRule [1] MatchingRuleId OPTIONAL,
1100 type [2] AttributeDescription OPTIONAL,
1101 matchValue [3] AssertionValue,
1102 dnAttributes [4] BOOLEAN DEFAULT FALSE }
1104 Fields of the Search Request are:
1106 - baseObject: The name of the base object entry relative to which
1107 the search is to be performed.
1109 - scope: Specifies the scope of the search to be performed. The
1110 semantics (as described in [X.511]) of the possible values of this
1113 baseObject: The scope is constrained to the entry named by
1116 singleLevel: The scope is constrained to the immediate
1117 subordinates of the entry named by baseObject.
1119 Sermersheim Internet-Draft - Expires Feb 2005 Page 19
1121 Lightweight Directory Access Protocol Version 3
1124 wholeSubtree: the scope is constrained to the entry named by
1125 the baseObject, and all its subordinates.
1128 - derefAliases: An indicator as to how alias entries (as defined in
1129 [Models]) are to be handled in searching. The semantics of the
1130 possible values of this field are:
1132 neverDerefAliases: Do not dereference aliases in searching or
1133 in locating the base object of the search.
1135 derefInSearching: While searching, dereference any alias entry
1136 subordinate to the base object which is also in the search
1137 scope. The filter is applied to the dereferenced object(s). If
1138 the search scope is wholeSubtree, the search continues in the
1139 subtree of any dereferenced object. Aliases in that subtree are
1140 also dereferenced. Servers SHOULD eliminate duplicate entries
1141 that arise due to alias dereferencing while searching.
1143 derefFindingBaseObj: Dereference aliases in locating the base
1144 object of the search, but not when searching subordinates of
1147 derefAlways: Dereference aliases both in searching and in
1148 locating the base object of the search.
1149 Servers MUST detect looping while dereferencing aliases in order
1150 to prevent denial of service attacks of this nature.
1152 - sizeLimit: A size limit that restricts the maximum number of
1153 entries to be returned as a result of the search. A value of zero
1154 in this field indicates that no client-requested size limit
1155 restrictions are in effect for the search. Servers may also
1156 enforce a maximum number of entries to return.
1158 - timeLimit: A time limit that restricts the maximum time (in
1159 seconds) allowed for a search. A value of zero in this field
1160 indicates that no client-requested time limit restrictions are in
1161 effect for the search. Servers may also enforce a maximum time
1162 limit for the search.
1164 - typesOnly: An indicator as to whether search results are to
1165 contain both attribute descriptions and values, or just attribute
1166 descriptions. Setting this field to TRUE causes only attribute
1167 descriptions (no values) to be returned. Setting this field to
1168 FALSE causes both attribute descriptions and values to be
1171 - filter: A filter that defines the conditions that must be
1172 fulfilled in order for the search to match a given entry.
1174 The 'and', 'or' and 'not' choices can be used to form combinations
1175 of filters. At least one filter element MUST be present in an
1176 'and' or 'or' choice. The others match against individual
1178 Sermersheim Internet-Draft - Expires Feb 2005 Page 20
1180 Lightweight Directory Access Protocol Version 3
1182 attribute values of entries in the scope of the search.
1183 (Implementor's note: the 'not' filter is an example of a tagged
1184 choice in an implicitly-tagged module. In BER this is treated as
1185 if the tag was explicit.)
1187 A server MUST evaluate filters according to the three-valued logic
1188 of X.511 (1993) Section 7.8.1. In summary, a filter is evaluated
1189 to either "TRUE", "FALSE" or "Undefined". If the filter evaluates
1190 to TRUE for a particular entry, then the attributes of that entry
1191 are returned as part of the search result (subject to any
1192 applicable access control restrictions). If the filter evaluates
1193 to FALSE or Undefined, then the entry is ignored for the search.
1195 A filter of the "and" choice is TRUE if all the filters in the SET
1196 OF evaluate to TRUE, FALSE if at least one filter is FALSE, and
1197 otherwise Undefined. A filter of the "or" choice is FALSE if all
1198 of the filters in the SET OF evaluate to FALSE, TRUE if at least
1199 one filter is TRUE, and Undefined otherwise. A filter of the 'not'
1200 choice is TRUE if the filter being negated is FALSE, FALSE if it
1201 is TRUE, and Undefined if it is Undefined.
1203 The present match evaluates to TRUE where there is an attribute or
1204 subtype of the specified attribute description present in an
1205 entry, and FALSE otherwise (including a presence test with an
1206 unrecognized attribute description.)
1208 The matching rule for equalityMatch filter items is defined by the
1209 EQUALITY matching rule for the attribute type.
1211 There SHALL be at most one 'initial', and at most one 'final' in
1212 the 'substrings' of a SubstringFilter. If 'initial' is present, it
1213 SHALL be the first element of 'substrings'. If 'final' is present,
1214 it SHALL be the last element of 'substrings'.
1215 The matching rule for AssertionValues in a substrings filter item
1216 is defined by the SUBSTR matching rule for the attribute type.
1217 Note that the AssertionValue in a substrings filter item conforms
1218 to the assertion syntax of the EQUALITY matching rule for the
1219 attribute type rather than the assertion syntax of the SUBSTR
1220 matching rule for the attribute type. Conceptually, the entire
1221 SubstringFilter is converted into an assertion value of the
1222 substrings matching rule prior to applying the rule.
1224 The matching rule for the greaterOrEqual filter item is defined by
1225 the ORDERING and EQUALITY matching rules for the attribute type.
1227 The matching rule for the lessOrEqual filter item is defined by
1228 the ORDERING matching rule for the attribute type.
1230 An approxMatch filter item evaluates to TRUE when there is a value
1231 of the attribute or subtype for which some locally-defined
1232 approximate matching algorithm (e.g. spelling variations, phonetic
1233 match, etc.) returns TRUE. If an item matches for equality, it
1234 also satisfies an approximate match. If approximate matching is
1235 not supported for the attribute, this filter item should be
1237 Sermersheim Internet-Draft - Expires Feb 2005 Page 21
1239 Lightweight Directory Access Protocol Version 3
1241 treated as an equalityMatch.
1243 An extensibleMatch filter item is evaluated as follows:
1245 If the matchingRule field is absent, the type field MUST be
1246 present, and an equality match is performed for that type.
1248 If the type field is absent and the matchingRule is present, the
1249 matchValue is compared against all attributes in an entry which
1250 support that matchingRule. The matchingRule determines the
1251 syntax for the assertion value. The filter item evaluates to
1252 TRUE if it matches with at least one attribute in the entry,
1253 FALSE if it does not match any attribute in the entry, and
1254 Undefined if the matchingRule is not recognized or the
1255 assertionValue is invalid.
1257 If the type field is present and the matchingRule is present,
1258 the matchValue is compared against entry attributes of the
1259 specified type. In this case, the matchingRule MUST be one
1260 suitable for use with the specified type (see [Syntaxes]),
1261 otherwise the filter item is Undefined.
1263 If the dnAttributes field is set to TRUE, the match is
1264 additionally applied against all the AttributeValueAssertions in
1265 an entry's distinguished name, and evaluates to TRUE if there is
1266 at least one attribute in the distinguished name for which the
1267 filter item evaluates to TRUE. The dnAttributes field is present
1268 to alleviate the need for multiple versions of generic matching
1269 rules (such as word matching), where one applies to entries and
1270 another applies to entries and dn attributes as well.
1272 A filter item evaluates to Undefined when the server would not be
1273 able to determine whether the assertion value matches an entry. If
1274 an attribute description in an equalityMatch, substrings,
1275 greaterOrEqual, lessOrEqual, approxMatch or extensibleMatch filter
1276 is not recognized by the server, a MatchingRuleId in the
1277 extensibleMatch is not recognized by the server, the assertion
1278 value is invalid, or the type of filtering requested is not
1279 implemented, then the filter is Undefined. Thus for example if a
1280 server did not recognize the attribute type shoeSize, a filter of
1281 (shoeSize=*) would evaluate to FALSE, and the filters
1282 (shoeSize=12), (shoeSize>=12) and (shoeSize<=12) would evaluate to
1285 Servers MUST NOT return errors if attribute descriptions or
1286 matching rule ids are not recognized, assertion values are
1287 invalid, or the assertion syntax is not supported. More details of
1288 filter processing are given in Section 7.8 of [X.511].
1290 - attributes: A selection list of the attributes to be returned from
1291 each entry which matches the search filter. LDAPString values of
1292 this field are constrained to the following Augmented Backus-Naur
1296 Sermersheim Internet-Draft - Expires Feb 2005 Page 22
1298 Lightweight Directory Access Protocol Version 3
1300 attributeSelector = attributedescription / selectorpecial
1302 selectorspecial = noattrs / alluserattrs
1304 noattrs = %x31.2E.31 ; "1.1"
1306 alluserattrs = %x2A ; asterisk ("*")
1308 The <attributedescription> production is defined in Section 2.5 of
1311 There are three special cases which may appear in the attributes
1314 - an empty list with no attributes,
1316 - a list containing "*" (with zero or more attribute
1319 - a list containing only "1.1".
1321 An empty list requests the return of all user attributes.
1323 A list containing "*" requests the return of all user attributes
1324 in addition to other listed (operational) attributes.
1326 A list containing only the OID "1.1" indicates that no attributes
1327 are to be returned. If "1.1" is provided with other
1328 attributeSelector values, the "1.1" attributeSelector is ignored.
1329 This OID was chosen because it does not (and can not) correspond
1330 to any attribute in use.
1332 Client implementors should note that even if all user attributes
1333 are requested, some attributes and/or attribute values of the
1334 entry may not be included in search results due to access controls
1335 or other restrictions. Furthermore, servers will not return
1336 operational attributes, such as objectClasses or attributeTypes,
1337 unless they are listed by name. Operational attributes are
1338 described in [Models].
1340 Attributes are returned at most once in an entry. If an attribute
1341 description is named more than once in the list, the subsequent
1342 names are ignored. If an attribute description in the list is not
1343 recognized, it is ignored by the server.
1345 Note that an X.500 "list"-like operation can be emulated by the
1346 client requesting a one-level LDAP search operation with a filter
1347 checking for the presence of the 'objectClass' attribute, and that an
1348 X.500 "read"-like operation can be emulated by a base object LDAP
1349 search operation with the same filter. A server which provides a
1350 gateway to X.500 is not required to use the Read or List operations,
1351 although it may choose to do so, and if it does, it must provide the
1352 same semantics as the X.500 search operation.
1355 Sermersheim Internet-Draft - Expires Feb 2005 Page 23
1357 Lightweight Directory Access Protocol Version 3
1360 4.5.2. Search Result
1362 The results of the search operation are returned as zero or more
1363 searchResultEntry messages, zero or more SearchResultReference
1364 messages, followed by a single searchResultDone message.
1366 SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
1368 attributes PartialAttributeList }
1370 PartialAttributeList ::= SEQUENCE OF
1371 partialAttribute PartialAttribute
1372 -- Note that the PartialAttributeList may hold zero elements.
1373 -- This may happen when none of the attributes of an entry
1374 -- were requested, or could be returned.
1375 -- Note also that the partialAttribute vals set may hold zero
1376 -- elements. This may happen when typesOnly is requested, access
1377 -- controls prevent the return of values, or other reasons.
1379 SearchResultReference ::= [APPLICATION 19] SEQUENCE
1380 SIZE (1..MAX) OF uri URI
1382 SearchResultDone ::= [APPLICATION 5] LDAPResult
1384 Each SearchResultEntry represents an entry found during the search.
1385 Each SearchResultReference represents an area not yet explored during
1386 the search. The SearchResultEntry and SearchResultReference PDUs may
1387 come in any order. Following all the SearchResultReference and
1388 SearchResultEntry responses, the server returns a SearchResultDone
1389 response, which contains an indication of success, or detailing any
1390 errors that have occurred.
1392 Each entry returned in a SearchResultEntry will contain all
1393 appropriate attributes as specified in the attributes field of the
1394 Search Request. Return of attributes is subject to access control and
1395 other administrative policy.
1397 Some attributes may be constructed by the server and appear in a
1398 SearchResultEntry attribute list, although they are not stored
1399 attributes of an entry. Clients SHOULD NOT assume that all attributes
1400 can be modified, even if permitted by access control.
1402 If the server's schema defines short names [Models] for an attribute
1403 type then the server SHOULD use one of those names in attribute
1404 descriptions for that attribute type (in preference to using the
1405 <numericoid> [Models] format of the attribute type's object
1406 identifier). The server SHOULD NOT use the short name if that name is
1407 known by the server to be ambiguous, or otherwise likely to cause
1408 interoperability problems.
1411 4.5.3. Continuation References in the Search Result
1414 Sermersheim Internet-Draft - Expires Feb 2005 Page 24
1416 Lightweight Directory Access Protocol Version 3
1418 If the server was able to locate the entry referred to by the
1419 baseObject but was unable to search one or more non-local entries,
1420 the server may return one or more SearchResultReference entries, each
1421 containing a reference to another set of servers for continuing the
1422 operation. A server MUST NOT return any SearchResultReference if it
1423 has not located the baseObject and thus has not searched any entries;
1424 in this case it would return a SearchResultDone containing either a
1425 referral or noSuchObject result code (depending on the server's
1426 knowledge of the entry named in the baseObject).
1428 If a server holds a copy or partial copy of the subordinate naming
1429 context [Section 5 of Models], it may use the search filter to
1430 determine whether or not to return a SearchResultReference response.
1431 Otherwise SearchResultReference responses are always returned when in
1434 The SearchResultReference is of the same data type as the Referral.
1436 A URI for a server implementing LDAP and accessible via [TCP]/[IP]
1437 (v4 or v6) is written as an LDAP URL according to [LDAPURL].
1439 In order to complete the search, the client issues a new search
1440 operation for each SearchResultReference that is returned. Note that
1441 the abandon operation described in Section 4.11 applies only to a
1442 particular operation sent on an association between a client and
1443 server. The client must abandon subsequent search operations it
1444 wishes to individually.
1446 Clients that follow search continuation references MUST ensure that
1447 they do not loop between servers. They MUST NOT repeatedly contact
1448 the same server for the same request with the same target entry name,
1449 scope and filter. Some clients use a counter that is incremented each
1450 time search result reference handling occurs for an operation, and
1451 these kinds of clients MUST be able to handle at least ten nested
1452 search result references between the root and a leaf entry.
1454 When an LDAP URL is used, the following instructions are followed:
1456 - The <dn> part of the URL MUST be present, with the new target
1457 object name. The client MUST use this name when following the
1458 reference. UTF-8 encoded characters appearing in the string
1459 representation of a DN or search filter may not be legal for URLs
1460 (e.g. spaces) and MUST be escaped using the % method in [URI].
1462 - Some servers (e.g. participating in distributed indexing) may
1463 provide a different filter in a URL of a SearchResultReference.
1465 - If the <filter> part of the URL is present, the client MUST use
1466 this filter in its next request to progress this search, and if it
1467 is not present the client MUST use the same filter as it used for
1470 - If the originating search scope was singleLevel, the <scope> part
1471 of the URL will be "base".
1473 Sermersheim Internet-Draft - Expires Feb 2005 Page 25
1475 Lightweight Directory Access Protocol Version 3
1478 - it is RECOMMENDED that the <scope> part be present to avoid
1481 - Other aspects of the new search request may be the same as or
1482 different from the search request which generated the
1483 SearchResultReference.
1485 - The name of an unexplored subtree in a SearchResultReference need
1486 not be subordinate to the base object.
1488 Other kinds of URIs may be returned. The syntax and semantics of such
1489 URIs is left to future specifications. Clients may ignore URIs that
1490 they do not support.
1495 For example, suppose the contacted server (hosta) holds the entry
1496 <DC=Example,DC=NET> and the entry <CN=Manager,DC=Example,DC=NET>. It
1497 knows that either LDAP-capable servers (hostb) or (hostc) hold
1498 <OU=People,DC=Example,DC=NET> (one is the master and the other server
1499 a shadow), and that LDAP-capable server (hostd) holds the subtree
1500 <OU=Roles,DC=Example,DC=NET>. If a wholeSubtree search of
1501 <DC=Example,DC=NET> is requested to the contacted server, it may
1502 return the following:
1504 SearchResultEntry for DC=Example,DC=NET
1505 SearchResultEntry for CN=Manager,DC=Example,DC=NET
1506 SearchResultReference {
1507 ldap://hostb/OU=People,DC=Example,DC=NET??sub
1508 ldap://hostc/OU=People,DC=Example,DC=NET??sub }
1509 SearchResultReference {
1510 ldap://hostd/OU=Roles,DC=Example,DC=NET??sub }
1511 SearchResultDone (success)
1513 Client implementors should note that when following a
1514 SearchResultReference, additional SearchResultReference may be
1515 generated. Continuing the example, if the client contacted the server
1516 (hostb) and issued the search for the subtree
1517 <OU=People,DC=Example,DC=NET>, the server might respond as follows:
1519 SearchResultEntry for OU=People,DC=Example,DC=NET
1520 SearchResultReference {
1521 ldap://hoste/OU=Managers,OU=People,DC=Example,DC=NET??sub }
1522 SearchResultReference {
1523 ldap://hostf/OU=Consultants,OU=People,DC=Example,DC=NET??sub }
1524 SearchResultDone (success)
1526 Similarly, if a singleLevel search of <DC=Example,DC=NET> is
1527 requested to the contacted server, it may return the following:
1529 SearchResultEntry for CN=Manager,DC=Example,DC=NET
1530 SearchResultReference {
1532 Sermersheim Internet-Draft - Expires Feb 2005 Page 26
1534 Lightweight Directory Access Protocol Version 3
1536 ldap://hostb/OU=People,DC=Example,DC=NET??base
1537 ldap://hostc/OU=People,DC=Example,DC=NET??base }
1538 SearchResultReference {
1539 ldap://hostd/OU=Roles,DC=Example,DC=NET??base }
1540 SearchResultDone (success)
1542 If the contacted server does not hold the base object for the search,
1543 but has knowledge of its possible location, then it may return a
1544 referral to the client. In this case, if the client requests a
1545 subtree search of <DC=Example,DC=ORG> to hosta, the server returns a
1546 SearchResultDone containing a referral.
1548 SearchResultDone (referral) {
1549 ldap://hostg/DC=Example,DC=ORG??sub }
1552 4.6. Modify Operation
1554 The Modify Operation allows a client to request that a modification
1555 of an entry be performed on its behalf by a server. The Modify
1556 Request is defined as follows:
1558 ModifyRequest ::= [APPLICATION 6] SEQUENCE {
1560 changes SEQUENCE OF change SEQUENCE {
1561 operation ENUMERATED {
1565 modification PartialAttribute } }
1567 Fields of the Modify Request are:
1569 - object: The name of the object to be modified. The value of this
1570 field contains the DN of the entry to be modified. The server
1571 SHALL NOT perform any alias dereferencing in determining the
1572 object to be modified.
1574 - changes: A list of modifications to be performed on the entry. The
1575 entire list of modifications MUST be performed in the order they
1576 are listed as a single atomic operation. While individual
1577 modifications may violate certain aspects of the directory schema
1578 (such as the object class definition and DIT content rule), the
1579 resulting entry after the entire list of modifications is
1580 performed MUST conform to the requirements of the directory model
1581 and controlling schema [Models].
1583 - operation: Used to specify the type of modification being
1584 performed. Each operation type acts on the following
1585 modification. The values of this field have the following
1586 semantics respectively:
1588 add: add values listed to the modification attribute,
1589 creating the attribute if necessary;
1591 Sermersheim Internet-Draft - Expires Feb 2005 Page 27
1593 Lightweight Directory Access Protocol Version 3
1596 delete: delete values listed from the modification attribute,
1597 removing the entire attribute if no values are listed, or if
1598 all current values of the attribute are listed for deletion;
1600 replace: replace all existing values of the modification
1601 attribute with the new values listed, creating the attribute
1602 if it did not already exist. A replace with no value will
1603 delete the entire attribute if it exists, and is ignored if
1604 the attribute does not exist.
1606 - modification: A PartialAttribute (which may have an empty SET
1607 of vals) used to hold the attribute type or attribute type and
1608 values being modified.
1610 Upon receipt of a Modify Request, the server attempts to perform the
1611 necessary modifications to the DIT and returns the result in a Modify
1612 Response, defined as follows:
1614 ModifyResponse ::= [APPLICATION 7] LDAPResult
1616 The server will return to the client a single Modify Response
1617 indicating either the successful completion of the DIT modification,
1618 or the reason that the modification failed. Due to the requirement
1619 for atomicity in applying the list of modifications in the Modify
1620 Request, the client may expect that no modifications of the DIT have
1621 been performed if the Modify Response received indicates any sort of
1622 error, and that all requested modifications have been performed if
1623 the Modify Response indicates successful completion of the Modify
1624 Operation. If the association changes or the connection fails,
1625 whether the modification occurred or not is indeterminate.
1627 The Modify Operation cannot be used to remove from an entry any of
1628 its distinguished values, i.e. those values which form the entry's
1629 relative distinguished name. An attempt to do so will result in the
1630 server returning the notAllowedOnRDN result code. The Modify DN
1631 Operation described in Section 4.9 is used to rename an entry.
1633 Note that due to the simplifications made in LDAP, there is not a
1634 direct mapping of the changes in an LDAP ModifyRequest onto the
1635 changes of a DAP ModifyEntry operation, and different implementations
1636 of LDAP-DAP gateways may use different means of representing the
1637 change. If successful, the final effect of the operations on the
1638 entry MUST be identical.
1643 The Add Operation allows a client to request the addition of an entry
1644 into the Directory. The Add Request is defined as follows:
1646 AddRequest ::= [APPLICATION 8] SEQUENCE {
1648 attributes AttributeList }
1650 Sermersheim Internet-Draft - Expires Feb 2005 Page 28
1652 Lightweight Directory Access Protocol Version 3
1655 AttributeList ::= SEQUENCE OF attribute Attribute
1657 Fields of the Add Request are:
1659 - entry: the name of the entry to be added. The server SHALL NOT
1660 dereference any aliases in locating the entry to be added.
1662 - attributes: the list of attributes that, along with those from the
1663 RDN, make up the content of the entry being added. Clients MAY or
1664 MAY NOT include the RDN attribute in this list. Clients MUST
1665 include the 'objectClass' attribute, and values of any mandatory
1666 attributes of the listed object classes. Clients MUST NOT supply
1667 NO-USER-MODIFICATION attributes such as the createTimestamp or
1668 creatorsName attributes, since the server maintains these
1671 The entry named in the entry field of the AddRequest MUST NOT exist
1672 for the AddRequest to succeed. The immediate superior (parent) of an
1673 object or alias entry to be added MUST exist. For example, if the
1674 client attempted to add <CN=JS,DC=Example,DC=NET>, the
1675 <DC=Example,DC=NET> entry did not exist, and the <DC=NET> entry did
1676 exist, then the server would return the noSuchObject result code with
1677 the matchedDN field containing <DC=NET>.
1679 Server implementations SHOULD NOT restrict where entries can be
1680 located in the Directory unless DIT structure rules are in place.
1681 Some servers allow the administrator to restrict the classes of
1682 entries which can be added to the Directory.
1684 Upon receipt of an Add Request, a server will attempt to add the
1685 requested entry. The result of the add attempt will be returned to
1686 the client in the Add Response, defined as follows:
1688 AddResponse ::= [APPLICATION 9] LDAPResult
1690 A response of success indicates that the new entry has been added to
1694 4.8. Delete Operation
1696 The Delete Operation allows a client to request the removal of an
1697 entry from the Directory. The Delete Request is defined as follows:
1699 DelRequest ::= [APPLICATION 10] LDAPDN
1701 The Delete Request consists of the name of the entry to be deleted.
1702 The server SHALL NOT dereference aliases while resolving the name of
1703 the target entry to be removed.
1705 Only leaf entries (those with no subordinate entries) can be deleted
1706 with this operation.
1709 Sermersheim Internet-Draft - Expires Feb 2005 Page 29
1711 Lightweight Directory Access Protocol Version 3
1713 Upon receipt of a Delete Request, a server will attempt to perform
1714 the entry removal requested and return the result in the Delete
1715 Response defined as follows:
1717 DelResponse ::= [APPLICATION 11] LDAPResult
1720 4.9. Modify DN Operation
1722 The Modify DN Operation allows a client to change the Relative
1723 Distinguished Name (RDN) of an entry in the Directory, and/or to move
1724 a subtree of entries to a new location in the Directory. The Modify
1725 DN Request is defined as follows:
1727 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
1729 newrdn RelativeLDAPDN,
1730 deleteoldrdn BOOLEAN,
1731 newSuperior [0] LDAPDN OPTIONAL }
1733 Fields of the Modify DN Request are:
1735 - entry: the name of the entry to be changed. This entry may or may
1736 not have subordinate entries.
1738 - newrdn: the new RDN of the entry. If the operation moves the entry
1739 to a new superior without changing its RDN, the value of the old
1740 RDN is supplied for this parameter.
1741 Attribute values of the new RDN not matching any attribute value
1742 of the entry are added to the entry and an appropriate error is
1743 returned if this fails.
1745 - deleteoldrdn: a boolean field that controls whether the old RDN
1746 attribute values are to be retained as attributes of the entry, or
1747 deleted from the entry.
1749 - newSuperior: if present, this is the name of an existing object
1750 entry which becomes the immediate superior (parent) of the
1753 The server SHALL NOT dereference any aliases in locating the objects
1754 named in entry or newSuperior.
1756 Upon receipt of a ModifyDNRequest, a server will attempt to perform
1757 the name change and return the result in the Modify DN Response,
1760 ModifyDNResponse ::= [APPLICATION 13] LDAPResult
1762 For example, if the entry named in the entry field was <cn=John
1763 Smith,c=US>, the newrdn field was <cn=John Cougar Smith>, and the
1764 newSuperior field was absent, then this operation would attempt to
1765 rename the entry to be <cn=John Cougar Smith,c=US>. If there was
1768 Sermersheim Internet-Draft - Expires Feb 2005 Page 30
1770 Lightweight Directory Access Protocol Version 3
1772 already an entry with that name, the operation would fail with the
1773 entryAlreadyExists result code.
1775 The object named in newSuperior MUST exist. For example, if the
1776 client attempted to add <CN=JS,DC=Example,DC=NET>, the
1777 <DC=Example,DC=NET> entry did not exist, and the <DC=NET> entry did
1778 exist, then the server would return the noSuchObject result code with
1779 the matchedDN field containing <DC=NET>.
1781 If the deleteoldrdn field is TRUE, the attribute values forming the
1782 old RDN but not the new RDN are deleted from the entry. If the
1783 deleteoldrdn field is FALSE, the attribute values forming the old RDN
1784 will be retained as non-distinguished attribute values of the entry.
1785 The server MUST fail the operation and return an error in the result
1786 code if the setting of the deleteoldrdn field would cause a schema
1787 inconsistency in the entry.
1789 Note that X.500 restricts the ModifyDN operation to only affect
1790 entries that are contained within a single server. If the LDAP server
1791 is mapped onto DAP, then this restriction will apply, and the
1792 affectsMultipleDSAs result code will be returned if this error
1793 occurred. In general, clients MUST NOT expect to be able to perform
1794 arbitrary movements of entries and subtrees between servers or
1795 between naming contexts.
1798 4.10. Compare Operation
1800 The Compare Operation allows a client to compare an assertion value
1801 with the values of a particular attribute in a particular entry in
1802 the Directory. The Compare Request is defined as follows:
1804 CompareRequest ::= [APPLICATION 14] SEQUENCE {
1806 ava AttributeValueAssertion }
1808 Fields of the Compare Request are:
1810 - entry: the name of the entry to be compared. The server SHALL NOT
1811 dereference any aliases in locating the entry to be compared.
1813 - ava: holds the attribute value assertion to be compared.
1815 Upon receipt of a Compare Request, a server will attempt to perform
1816 the requested comparison and return the result in the Compare
1817 Response, defined as follows:
1819 CompareResponse ::= [APPLICATION 15] LDAPResult
1821 The resultCode field is set to compareTrue, compareFalse, or an
1822 appropriate error. compareTrue indicates that the assertion value in
1823 the ava field matches a value of the attribute or subtype according
1824 to the attribute's EQUALITY matching rule. compareFalse indicates
1825 that the assertion value in the ava field and the values of the
1827 Sermersheim Internet-Draft - Expires Feb 2005 Page 31
1829 Lightweight Directory Access Protocol Version 3
1831 attribute or subtype did not match. Other result codes indicate
1832 either that the result of the comparison was Undefined (Section
1833 4.5.1), or that some error occurred.
1835 Note that some directory systems may establish access controls which
1836 permit the values of certain attributes (such as userPassword) to be
1837 compared but not interrogated by other means.
1840 4.11. Abandon Operation
1842 The function of the Abandon Operation is to allow a client to request
1843 that the server abandon an uncompleted operation. The Abandon Request
1844 is defined as follows:
1846 AbandonRequest ::= [APPLICATION 16] MessageID
1848 The MessageID is that of an operation which was requested earlier in
1849 this LDAP association. The abandon request itself has its own
1850 MessageID. This is distinct from the MessageID of the earlier
1851 operation being abandoned.
1853 There is no response defined in the Abandon operation. Upon receipt
1854 of an AbandonRequest, the server MAY abandon the operation identified
1855 by the MessageID. Since the client cannot tell the difference between
1856 a successfully abandoned operation and an uncompleted operation, the
1857 application of the Abandon operation is limited to uses where the
1858 client does not require an indication of its outcome.
1860 Abandon, Bind, Unbind, and StartTLS operations cannot be abandoned.
1862 In the event that a server receives an Abandon Request on a Search
1863 Operation in the midst of transmitting responses to the search, that
1864 server MUST cease transmitting entry responses to the abandoned
1865 request immediately, and MUST NOT send the SearchResponseDone. Of
1866 course, the server MUST ensure that only properly encoded LDAPMessage
1867 PDUs are transmitted.
1869 The ability to abandon other (particularly update) operations is at
1870 the discretion of the server.
1872 Clients should not send abandon requests for the same operation
1873 multiple times, and MUST also be prepared to receive results from
1874 operations it has abandoned (since these may have been in transit
1875 when the abandon was requested, or are not able to be abandoned).
1877 Servers MUST discard abandon requests for message IDs they do not
1878 recognize, for operations which cannot be abandoned, and for
1879 operations which have already been abandoned.
1882 4.12. Extended Operation
1886 Sermersheim Internet-Draft - Expires Feb 2005 Page 32
1888 Lightweight Directory Access Protocol Version 3
1890 The extended operation allows additional operations to be defined for
1891 services not already available in the protocol. For example, to add
1892 operations to install transport layer security (see Section 4.14).
1894 The extended operation allows clients to make requests and receive
1895 responses with predefined syntaxes and semantics. These may be
1896 defined in RFCs or be private to particular implementations.
1898 Each extended operation consists of an extended request and an
1901 ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
1902 requestName [0] LDAPOID,
1903 requestValue [1] OCTET STRING OPTIONAL }
1905 The requestName is a dotted-decimal representation of the unique
1906 OBJECT IDENTIFIER corresponding to the request. The requestValue is
1907 information in a form defined by that request, encapsulated inside an
1910 The server will respond to this with an LDAPMessage containing an
1913 ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
1914 COMPONENTS OF LDAPResult,
1915 responseName [10] LDAPOID OPTIONAL,
1916 responseValue [11] OCTET STRING OPTIONAL }
1918 The responseName is typically not required to be present as the
1919 syntax and semantics of the response (including the format of the
1920 responseValue) is implicitly known and associated with the request by
1923 If the extended operation associated with the requestName is not
1924 supported by the server, the server MUST NOT provide a responseName
1925 nor a responseValue and MUST return a resultCode of protocolError.
1927 The requestValue and responseValue fields contain any information
1928 associated with the operation. The format of these fields is defined
1929 by the specification of the extended operation. Implementations MUST
1930 be prepared to handle arbitrary contents of these fields, including
1931 zero bytes. Values that are defined in terms of ASN.1 and BER encoded
1932 according to Section 5.2, also follow the extensibility rules in
1935 Servers list the requestName of Extended Requests they recognize in
1936 the ' supportedExtension ' attribute in the root DSE (Section 5.1 of
1939 Extended operations may be specified in other documents. The
1940 specification of an extended operation consists of:
1942 - the OBJECT IDENTIFIER assigned to the requestName,
1945 Sermersheim Internet-Draft - Expires Feb 2005 Page 33
1947 Lightweight Directory Access Protocol Version 3
1949 - the OBJECT IDENTIFIER (if any) assigned to the responseName (note
1950 that the same OBJECT IDENTIFIER my be used for both the
1951 requestName and responseName),
1953 - the format of the contents of the requestValue and responseValue
1956 - the semantics of the operation.
1959 4.13. IntermediateResponse Message
1961 While the Search operation provides a mechanism to return multiple
1962 response messages for a single search request, other operations, by
1963 nature, do not provide for multiple response messages.
1965 The IntermediateResponse message provides a general mechanism for
1966 defining single-request/multiple-response operations in LDAP. This
1967 message is intended to be used in conjunction with the extended
1968 operation to define new single-request/multiple-response operations
1969 or in conjunction with a control when extending existing LDAP
1970 operations in a way that requires them to return intermediate
1971 response information.
1973 It is intended that the definitions and descriptions of extended
1974 operations and controls that make use of the IntermediateResponse
1975 message will define the circumstances when an IntermediateResponse
1976 message can be sent by a server and the associated meaning of an
1977 IntermediateResponse message sent in a particular circumstance.
1979 IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
1980 responseName [0] LDAPOID OPTIONAL,
1981 responseValue [1] OCTET STRING OPTIONAL }
1983 IntermediateResponse messages SHALL NOT be returned to the client
1984 unless the client issues a request that specifically solicits their
1985 return. This document defines two forms of solicitation: extended
1986 operation and request control. IntermediateResponse messages are
1987 specified in documents describing the manner in which they are
1988 solicited (i.e. in the extended operation or request control
1989 specification that uses them). These specifications include:
1991 - the OBJECT IDENTIFIER (if any) assigned to the responseName,
1993 - the format of the contents of the responseValue, and
1995 - the semantics associated with the IntermediateResponse message.
1997 Extensions that allow the return of multiple types of
1998 IntermediateResponse messages SHALL identify those types using unique
1999 responseName values (note that one of these may specify no value).
2004 Sermersheim Internet-Draft - Expires Feb 2005 Page 34
2006 Lightweight Directory Access Protocol Version 3
2008 Sections 4.13.1 and 4.13.2 describe additional requirements on the
2009 inclusion of responseName and responseValue in IntermediateResponse
2013 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse
2015 A single-request/multiple-response operation may be defined using a
2016 single ExtendedRequest message to solicit zero or more
2017 IntermediateResponse messages of one or more kinds followed by an
2018 ExtendedResponse message.
2021 4.13.2. Usage with LDAP Request Controls
2023 A control's semantics may include the return of zero or more
2024 IntermediateResponse messages prior to returning the final result
2025 code for the operation. One or more kinds of IntermediateResponse
2026 messages may be sent in response to a request control.
2028 All IntermediateResponse messages associated with request controls
2029 SHALL include a responseName. This requirement ensures that the
2030 client can correctly identify the source of IntermediateResponse
2033 - two or more controls using IntermediateResponse messages are
2034 included in a request for any LDAP operation or
2036 - one or more controls using IntermediateResponse messages are
2037 included in a request with an LDAP extended operation that uses
2038 IntermediateResponse messages.
2041 4.14. StartTLS Operation
2043 The Start Transport Layer Security (StartTLS) operation provides the
2044 ability to establish a TLS-protected LDAP exchange. The StartTLS
2045 operation is defined using the extended operation mechanism described
2049 4.14.1. StartTLS Request
2051 A client requests TLS establishment by transmitting a StartTLS
2052 request PDU to the server. The StartTLS request is defined in terms
2053 of an ExtendedRequest. The requestName is "1.3.6.1.4.1.1466.20037",
2054 and the requestValue field is always absent.
2056 The client MUST NOT send any PDUs on this LDAP exchange following
2057 this request until it receives a StartTLS extended response and, in
2058 the case of a successful response, completes TLS negotiations.
2062 Sermersheim Internet-Draft - Expires Feb 2005 Page 35
2064 Lightweight Directory Access Protocol Version 3
2066 4.14.2. StartTLS Response
2068 When a StartTLS request is made, servers supporting the operation
2069 MUST return a StartTLS response PDU to the requestor. The
2070 responseName, if present, is also "1.3.6.1.4.1.1466.20037". The
2071 responseValue is absent.
2073 The server provides a resultCode field to either success or one of
2074 the other values outlined in Section 4.14.2.2.
2077 4.14.2.1. "Success" Response
2079 If the StartTLS Response contains a resultCode of success, this
2080 indicates that the server is willing and able to negotiate TLS. Refer
2081 to Section 4 of [AuthMeth] for details.
2084 4.14.2.2. Response other than "success"
2086 If the ExtendedResponse contains a result code other than success,
2087 this indicates that the server is unwilling or unable to negotiate
2088 TLS. The following result codes have these meanings for this
2091 - operationsError: operations sequencing incorrect; e.g. TLS is
2092 already established.
2094 - protocolError: TLS is not supported or incorrect PDU structure.
2096 - unavailable: Some major problem with TLS, or the server is
2099 The server MUST return operationsError if the client violates any of
2100 the StartTLS extended operation sequencing requirements described in
2101 Section 4 of [AuthMeth].
2103 If the server does not support TLS (whether by design or by current
2104 configuration), it MUST return the protocolError resultCode. In this
2105 event, the client may proceed with any LDAP operation, or it may
2106 close the connection.
2108 The server MUST return unavailable if it supports TLS but cannot
2109 install the TLS layer for some reason, e.g. the certificate server
2110 not responding, it cannot contact its TLS implementation, or if the
2111 server is in process of shutting down. The client may retry the
2112 StartTLS operation, or it may proceed with any other LDAP operation,
2113 or it may close the connection.
2116 4.14.3. Removal of the TLS Layer
2120 Sermersheim Internet-Draft - Expires Feb 2005 Page 36
2122 Lightweight Directory Access Protocol Version 3
2124 Two forms of TLS layer removal -- graceful and abrupt -- are
2125 provided. These do not involve LDAP PDUs, but are preformed at the
2128 If the connection is closed, uncompleted operations are handled as
2129 specified in Section 5.1.
2132 4.14.3.1. Graceful Removal
2134 Either the client or server MAY remove the TLS layer and leave the
2135 LDAP exchange intact by sending and receiving a TLS closure alert.
2137 The initiating protocol peer sends the TLS closure alert. If it
2138 wishes to leave the LDAP exchange intact, it then MUST cease to send
2139 further PDUs and MUST ignore any received LDAP PDUs until it receives
2140 a TLS closure alert from the other peer.
2142 Once the initiating protocol peer receives a TLS closure alert from
2143 the other peer it MAY send and receive LDAP PDUs.
2145 When a protocol peer receives the initial TLS closure alert, it may
2146 choose to allow the LDAP exchange to remain intact. In this case, it
2147 MUST immediately transmit a TLS closure alert. Following this, it MAY
2148 send and receive LDAP PDUs.
2150 Protocol peers MAY close the connection after sending or receiving a
2153 After the TLS layer has been removed, the server MUST NOT send
2154 responses to any request message received before the TLS closure
2155 alert. Thus, clients wishing to receive responses to messages sent
2156 while the TLS layer is intact MUST wait for those message responses
2157 before sending the TLS closure alert.
2160 4.14.3.2. Abrupt Removal
2162 Either the client or server MAY abruptly remove the TLS layer by
2163 closing the connection. In this circumstance, a server MAY send the
2164 client a Notice of Disconnection before closing the connection.
2167 5. Protocol Encoding, Connection, and Transfer
2169 This protocol is designed to run over connection-oriented, reliable
2170 transports, where the data stream is divided into octets (8-bit
2171 units), with each octet and each bit being significant.
2173 One underlying service, LDAP over TCP, is defined in Section
2174 5.3. This service is generally applicable to applications providing
2175 or consuming X.500-based directory services on the Internet. This
2176 specification was generally written with the TCP mapping in mind.
2178 Sermersheim Internet-Draft - Expires Feb 2005 Page 37
2180 Lightweight Directory Access Protocol Version 3
2182 Specifications detailing other mappings may encounter various
2185 Implementations of LDAP over TCP MUST implement the mapping as
2186 described in Section 5.3.
2188 This table illustrates the relationship between the different layers
2189 involved in an exchange between two protocol peers:
2193 +---------------+ > LDAP PDUs
2194 +---------------+ < data
2196 +---------------+ > SASL-protected data
2197 +---------------+ < data
2199 Application +---------------+ > TLS-protected data
2200 ------------+---------------+ < data
2201 Transport | connection |
2205 5.2. Protocol Encoding
2207 The protocol elements of LDAP SHALL be encoded for exchange using the
2208 Basic Encoding Rules [BER] of [ASN.1] with the following
2211 - Only the definite form of length encoding is used.
2213 - OCTET STRING values are encoded in the primitive form only.
2215 - If the value of a BOOLEAN type is true, the encoding of the value
2216 octet is set to hex "FF".
2218 - If a value of a type is its default value, it is absent. Only some
2219 BOOLEAN and INTEGER types have default values in this protocol
2222 These restrictions are meant to ease the overhead of encoding and
2223 decoding certain elements in BER.
2225 These restrictions do not apply to ASN.1 types encapsulated inside of
2226 OCTET STRING values, such as attribute values, unless otherwise
2230 5.3. Transmission Control Protocol (TCP)
2232 The encoded LDAPMessage PDUs are mapped directly onto the [TCP]
2233 bytestream using the BER-based encoding described in Section 5.2. It
2234 is recommended that server implementations running over the TCP
2235 provide a protocol listener on the Internet Assigned Numbers
2236 Authority (IANA)-assigned LDAP port, 389 [PortReg]. Servers may
2238 Sermersheim Internet-Draft - Expires Feb 2005 Page 38
2240 Lightweight Directory Access Protocol Version 3
2242 instead provide a listener on a different port number. Clients MUST
2243 support contacting servers on any valid TCP port.
2246 6. Security Considerations
2248 This version of the protocol provides facilities for simple
2249 authentication using a cleartext password, as well as any [SASL]
2250 mechanism. Installing SASL layers can provide integrity and other
2251 data security services.
2253 It is also permitted that the server can return its credentials to
2254 the client, if it chooses to do so.
2256 Use of cleartext password is strongly discouraged where the
2257 underlying transport service cannot guarantee confidentiality and may
2258 result in disclosure of the password to unauthorized parties.
2260 Servers are encouraged to prevent directory modifications by clients
2261 that have authenticated anonymously [AuthMeth].
2263 Security considerations for authentication methods, SASL mechanisms,
2264 and TLS are described in [AuthMeth].
2266 It should be noted that SASL authentication exchanges do not provide
2267 data confidentiality nor integrity protection for the version or name
2268 fields of the bind request nor the resultCode, diagnosticMessage, or
2269 referral fields of the bind response nor of any information contained
2270 in controls attached to bind request or responses. Thus information
2271 contained in these fields SHOULD NOT be relied on unless otherwise
2272 protected (such as by establishing protections at the transport
2275 Server implementors should plan for the possibility of an identity in
2276 and association being deleted, renamed, or modified, and take
2277 appropriate actions to prevent insecure side effects. Likewise,
2278 server implementors should plan for the possibility of an associated
2279 identity's credentials becoming invalid, or an identity's privileges
2280 being changed. The ways in which these issues are addressed are
2281 application and/or implementation specific.
2283 Implementations which cache attributes and entries obtained via LDAP
2284 MUST ensure that access controls are maintained if that information
2285 is to be provided to multiple clients, since servers may have access
2286 control policies which prevent the return of entries or attributes in
2287 search results except to particular authenticated clients. For
2288 example, caches could serve result information only to the client
2289 whose request caused it to be in the cache.
2291 Servers may return referrals or search result references which
2292 redirect clients to peer servers. It is possible for a rogue
2293 application to inject such referrals into the data stream in an
2294 attempt to redirect a client to a rogue server. Clients are advised
2295 to be aware of this, and possibly reject referrals when
2297 Sermersheim Internet-Draft - Expires Feb 2005 Page 39
2299 Lightweight Directory Access Protocol Version 3
2301 confidentiality measures are not in place. Clients are advised to
2302 reject referrals from the StartTLS operation.
2304 The matchedDN and diagnosticMessage fields, as well as some
2305 resultCode values (e.g., attributeOrValueExists and
2306 entryAlreadyExists), could disclose the presence the specific data in
2307 the directory which is subject to access and other administrative
2308 controls. Server implementations should restrict access to protected
2309 information equally under both normal and error conditions.
2312 Protocol peers MUST be prepared to handle invalid and arbitrary
2313 length protocol encodings. Invalid protocol encodings include: BER
2314 encoding exceptions, format string and UTF-8 encoding exceptions,
2315 overflow exceptions, integer value exceptions, and binary mode on/off
2316 flag exceptions. The LDAPv3 PROTOS [PROTOS-LDAP] test suite provides
2317 excellent examples of these exceptions and test cases used to
2323 This document is based on RFC 2251 by Mark Wahl, Tim Howes, and Steve
2324 Kille. RFC 2251 was a product of the IETF ASID Working Group.
2326 It is also based on RFC 2830 by Jeff Hodges, RL "Bob" Morgan, and
2327 Mark Wahl. RFC 2830 was a product of the IETF LDAPEXT Working Group.
2329 It is also based on RFC 3771 by Roger Harrison, and Kurt Zeilenga.
2330 RFC 3771 was an individual submission to the IETF.
2332 This document is a product of the LDAPBIS Working Group. Significant
2333 contributors of technical review and content include Kurt Zeilenga,
2334 Steven Legg, and Hallvard Furuseth.
2337 8. Normative References
2339 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
2340 Specifications: ABNF", RFC 2234, November 1997.
2342 Sermersheim Internet-Draft - Expires Feb 2005 Page 40
2344 Lightweight Directory Access Protocol Version 3
2347 [ASN.1] ITU-T Recommendation X.680 (07/2002) | ISO/IEC 8824-1:2002
2348 "Information Technology - Abstract Syntax Notation One
2349 (ASN.1): Specification of basic notation"
2351 [AuthMeth] Harrison, R., "LDAP: Authentication Methods and Connection
2352 Level Security Mechanisms", draft-ietf-ldapbis-authmeth-
2353 xx.txt, (a work in progress).
2355 [BER] ITU-T Rec. X.690 (07/2002) | ISO/IEC 8825-1:2002,
2356 "Information technology - ASN.1 encoding rules:
2357 Specification of Basic Encoding Rules (BER), Canonical
2358 Encoding Rules (CER) and Distinguished Encoding Rules
2361 [IP] Postel, J., "Internet Protocol", STD5 and RFC 791,
2364 [ISO10646] Universal Multiple-Octet Coded Character Set (UCS) -
2365 Architecture and Basic Multilingual Plane, ISO/IEC 10646-1
2368 [Keyword] Bradner, S., "Key words for use in RFCs to Indicate
2369 Requirement Levels", RFC 2119, March 1997.
2371 [LDAPDN] Zeilenga, K., "LDAP: String Representation of
2372 Distinguished Names", draft-ietf-ldapbis-dn-xx.txt, (a
2375 [LDAPIANA] Zeilenga, K., "IANA Considerations for LDAP", draft-ietf-
2376 ldapbis-bcp64-xx.txt, (a work in progress).
2378 [LDAPURL] Smith, M., "LDAP: Uniform Resource Locator", draft-ietf-
2379 ldapbis-url-xx.txt, (a work in progress).
2381 [Models] Zeilenga, K., "LDAP: Directory Information Models", draft-
2382 ietf-ldapbis-models-xx.txt (a work in progress).
2384 [Roadmap] Zeilenga, K., "LDAP: Technical Specification Road Map",
2385 draft-ietf-ldapbis-roadmap-xx.txt (a work in progress).
2387 [SASL] Melnikov, A., "Simple Authentication and Security Layer",
2388 draft-ietf-sasl-rfc2222bis-xx.txt (a work in progress).
2390 [SASLPrep] Zeilenga, K., "Stringprep profile for user names and
2391 passwords", draft-ietf-sasl-saslprep-xx.txt, (a work in
2394 [StringPrep] Hoffman P. and M. Blanchet, "Preparation of
2395 Internationalized Strings ('stringprep')", draft-hoffman-
2396 rfc3454bis-xx.txt, a work in progress.
2401 Sermersheim Internet-Draft - Expires Feb 2005 Page 41
2403 Lightweight Directory Access Protocol Version 3
2405 [Syntaxes] Legg, S., and K. Dally, "LDAP: Syntaxes and Matching
2406 Rules", draft-ietf-ldapbis-syntaxes-xx.txt, (a work in
2409 [TCP] Postel, J., "Transmission Control Protocol", STD7 and RFC
2412 [TLS] Dierks, T. and C. Allen. "The TLS Protocol Version 1.1",
2413 draft-ietf-tls-rfc2246-bis-xx.txt, a work in progress.
2415 [Unicode] The Unicode Consortium, "The Unicode Standard, Version
2416 3.2.0" is defined by "The Unicode Standard, Version 3.0"
2417 (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5),
2418 as amended by the "Unicode Standard Annex #27: Unicode
2419 3.1" (http://www.unicode.org/reports/tr27/) and by the
2420 "Unicode Standard Annex #28: Unicode 3.2"
2421 (http://www.unicode.org/reports/tr28/).
2423 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
2424 Resource Identifiers (URI): Generic Syntax", RFC 2396,
2427 [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
2428 10646", STD63 and RFC3629, November 2003.
2430 [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts,
2431 Models and Service", 1993.
2433 [X.501] ITU-T Rec. X.501, "The Directory: Models", 1993.
2435 [X.511] ITU-T Rec. X.511, "The Directory: Abstract Service
2439 9. Informative References
2441 [Glossary] The Unicode Consortium, "Unicode Glossary",
2442 <http://www.unicode.org/glossary/>.
2444 [CharModel] Whistler, K. and M. Davis, "Unicode Technical Report
2445 #17, Character Encoding Model", UTR17,
2446 <http://www.unicode.org/unicode/reports/tr17/>, August
2449 [PROTOS-LDAP] University of Oulu, "PROTOS Test-Suite: c06-ldapv3"
2450 <http://www.ee.oulu.fi/research/ouspg/protos/testing/c06/l
2453 [PortReg] IANA, "Port Numbers",
2454 http://www.iana.org/assignments/port-numbers
2457 10. IANA Considerations
2460 Sermersheim Internet-Draft - Expires Feb 2005 Page 42
2462 Lightweight Directory Access Protocol Version 3
2464 It is requested that the Internet Assigned Numbers Authority (IANA)
2465 update the LDAP result code registry to indicate that this document
2466 provides the definitive technical specification for result codes 0-
2467 36, 48-54, 64-70, 80-90.
2469 It is requested that the IANA update the LDAP Protocol Mechanism
2470 registry to indicate that this document and [AuthMeth] provides the
2471 definitive technical specification for the StartTLS
2472 (1.3.6.1.4.1.1466.20037) extended operation.
2474 It is requested that the IANA update the occurrence of "RFC XXXX" in
2475 Appendix B with this RFC number at publication.
2478 11. Editor's Address
2482 1800 South Novell Place
2483 Provo, Utah 84606, USA
2519 Sermersheim Internet-Draft - Expires Feb 2005 Page 43
2521 Lightweight Directory Access Protocol Version 3
2523 Appendix A - LDAP Result Codes
2525 This normative appendix details additional considerations regarding
2526 LDAP result codes and provides a brief, general description of each
2527 LDAP result code enumerated in Section 4.1.9.
2529 Additional result codes MAY be defined for use with extensions
2530 [LDAPIANA]. Client implementations SHALL treat any result code which
2531 they do not recognize as an unknown error condition.
2534 A.1 Non-Error Result Codes
2536 These result codes (called "non-error" result codes) do not indicate
2542 saslBindInProgress (14).
2544 The success, compareTrue, and compareFalse result codes indicate
2545 successful completion (and, hence, are referred to as "successful"
2548 The referral and saslBindInProgress result codes indicate the client
2549 is required to take additional action to complete the operation.
2554 Existing LDAP result codes are described as follows:
2557 Indicates the successful completion of an operation. Note:
2558 this code is not used with the compare operation. See
2559 compareFalse (5) and compareTrue (6).
2562 Indicates that the operation is not properly sequenced with
2563 relation to other operations (of same or different type).
2565 For example, this code is returned if the client attempts to
2566 StartTLS [TLS] while there are other uncompleted operations
2567 or if a TLS layer was already installed.
2570 Indicates the server received data which is not well-formed.
2572 For bind operation only, this code is also used to indicate
2573 that the server does not support the requested protocol
2578 Sermersheim Internet-Draft - Expires Feb 2005 Page 44
2580 Lightweight Directory Access Protocol Version 3
2582 For extended operations only, this code indicates that the
2583 server does not support (by design or configuration) the
2584 extended operation associated with the requestName.
2586 For request operations specifying multiple controls, this may
2587 be used to indicate that the server cannot ignore the order
2588 of the controls as specified, or that the combination of the
2589 specified controls is invalid or unspecified.
2591 timeLimitExceeded (3)
2592 Indicates that the time limit specified by the client was
2593 exceeded before the operation could be completed.
2595 sizeLimitExceeded (4)
2596 Indicates that the size limit specified by the client was
2597 exceeded before the operation could be completed.
2600 Indicates that the compare operation has successfully
2601 completed and the assertion has evaluated to FALSE or
2605 Indicates that the compare operation has successfully
2606 completed and the assertion has evaluated to TRUE.
2608 authMethodNotSupported (7)
2609 Indicates that the authentication method or mechanism is not
2612 strongAuthRequired (8)
2613 Indicates that the server has detected that an established
2614 security association between the client and server has
2615 unexpectedly failed or been compromised, or that the server
2616 now requires the client to authenticate using a strong(er)
2620 Indicates that a referral needs to be chased to complete the
2621 operation (see Section 4.1.10).
2623 adminLimitExceeded (11)
2624 Indicates that an administrative limit has been exceeded.
2626 unavailableCriticalExtension (12)
2627 Indicates a critical control is unrecognized (see Section
2630 confidentialityRequired (13)
2631 Indicates that data confidentiality protections are required.
2633 saslBindInProgress (14)
2637 Sermersheim Internet-Draft - Expires Feb 2005 Page 45
2639 Lightweight Directory Access Protocol Version 3
2641 Indicates the server requires the client to send a new bind
2642 request, with the same SASL mechanism, to continue the
2643 authentication process (see Section 4.2).
2645 noSuchAttribute (16)
2646 Indicates that the named entry does not contain the specified
2647 attribute or attribute value.
2649 undefinedAttributeType (17)
2650 Indicates that a request field contains an unrecognized
2651 attribute description.
2653 inappropriateMatching (18)
2654 Indicates that an attempt was made (e.g. in an assertion) to
2655 use a matching rule not defined for the attribute type
2658 constraintViolation (19)
2659 Indicates that the client supplied an attribute value which
2660 does not conform to the constraints placed upon it by the
2663 For example, this code is returned when multiple values are
2664 supplied to an attribute which has a SINGLE-VALUE constraint.
2666 attributeOrValueExists (20)
2667 Indicates that the client supplied an attribute or value to
2668 be added to an entry, but the attribute or value already
2671 invalidAttributeSyntax (21)
2672 Indicates that a purported attribute value does not conform
2673 to the syntax of the attribute.
2676 Indicates that the object does not exist in the DIT.
2679 Indicates that an alias problem has occurred. For example,
2680 the code may used to indicate an alias has been dereferenced
2681 which names no object.
2683 invalidDNSyntax (34)
2684 Indicates that an LDAPDN or RelativeLDAPDN field (e.g. search
2685 base, target entry, ModifyDN newrdn, etc.) of a request does
2686 not conform to the required syntax or contains attribute
2687 values which do not conform to the syntax of the attribute's
2690 aliasDereferencingProblem (36)
2691 Indicates that a problem occurred while dereferencing an
2692 alias. Typically an alias was encountered in a situation
2693 where it was not allowed or where access was denied.
2696 Sermersheim Internet-Draft - Expires Feb 2005 Page 46
2698 Lightweight Directory Access Protocol Version 3
2700 inappropriateAuthentication (48)
2701 Indicates the server requires the client which had attempted
2702 to bind anonymously or without supplying credentials to
2703 provide some form of credentials.
2705 invalidCredentials (49)
2706 Indicates that the provided credentials (e.g. the user's name
2707 and password) are invalid.
2709 insufficientAccessRights (50)
2710 Indicates that the client does not have sufficient access
2711 rights to perform the operation.
2714 Indicates that the server is too busy to service the
2718 Indicates that the server is shutting down or a subsystem
2719 necessary to complete the operation is offline.
2721 unwillingToPerform (53)
2722 Indicates that the server is unwilling to perform the
2726 Indicates that the server has detected an internal loop (e.g.
2727 while dereferencing aliases or chaining an operation).
2729 namingViolation (64)
2730 Indicates that the entry's name violates naming restrictions.
2732 objectClassViolation (65)
2733 Indicates that the entry violates object class restrictions.
2735 notAllowedOnNonLeaf (66)
2736 Indicates that the operation is inappropriately acting upon a
2739 notAllowedOnRDN (67)
2740 Indicates that the operation is inappropriately attempting to
2741 remove a value which forms the entry's relative distinguished
2744 entryAlreadyExists (68)
2745 Indicates that the request cannot be fulfilled (added, moved,
2746 or renamed) as the target entry already exists.
2748 objectClassModsProhibited (69)
2749 Indicates that an attempt to modify the object class(es) of
2750 an entry's 'objectClass' attribute is prohibited.
2752 For example, this code is returned when a client attempts to
2753 modify the structural object class of an entry.
2755 Sermersheim Internet-Draft - Expires Feb 2005 Page 47
2757 Lightweight Directory Access Protocol Version 3
2760 affectsMultipleDSAs (71)
2761 Indicates that the operation cannot be performed as it would
2762 affect multiple servers (DSAs).
2765 Indicates the server has encountered an internal error.
2814 Sermersheim Internet-Draft - Expires Feb 2005 Page 48
2816 Lightweight Directory Access Protocol Version 3
2818 Appendix B - Complete ASN.1 Definition
2820 This appendix is normative.
2822 Lightweight-Directory-Access-Protocol-V3
2823 -- Copyright (C) The Internet Society (2004). This version of
2824 -- this ASN.1 module is part of RFC XXXX; see the RFC itself
2825 -- for full legal notices.
2828 EXTENSIBILITY IMPLIED ::=
2832 LDAPMessage ::= SEQUENCE {
2833 messageID MessageID,
2835 bindRequest BindRequest,
2836 bindResponse BindResponse,
2837 unbindRequest UnbindRequest,
2838 searchRequest SearchRequest,
2839 searchResEntry SearchResultEntry,
2840 searchResDone SearchResultDone,
2841 searchResRef SearchResultReference,
2842 modifyRequest ModifyRequest,
2843 modifyResponse ModifyResponse,
2844 addRequest AddRequest,
2845 addResponse AddResponse,
2846 delRequest DelRequest,
2847 delResponse DelResponse,
2848 modDNRequest ModifyDNRequest,
2849 modDNResponse ModifyDNResponse,
2850 compareRequest CompareRequest,
2851 compareResponse CompareResponse,
2852 abandonRequest AbandonRequest,
2853 extendedReq ExtendedRequest,
2854 extendedResp ExtendedResponse,
2856 intermediateResponse IntermediateResponse },
2857 controls [0] Controls OPTIONAL }
2859 MessageID ::= INTEGER (0 .. maxInt)
2861 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
2863 LDAPString ::= OCTET STRING -- UTF-8 encoded,
2864 -- [ISO10646] characters
2866 LDAPOID ::= OCTET STRING -- Constrained to <numericoid> [Models]
2868 LDAPDN ::= LDAPString -- Constrained to <distinguishedName>
2871 RelativeLDAPDN ::= LDAPString -- Constrained to <name-component>
2873 Sermersheim Internet-Draft - Expires Feb 2005 Page 49
2875 Lightweight Directory Access Protocol Version 3
2879 AttributeDescription ::= LDAPString
2880 -- Constrained to <attributedescription>
2883 AttributeValue ::= OCTET STRING
2885 AttributeValueAssertion ::= SEQUENCE {
2886 attributeDesc AttributeDescription,
2887 assertionValue AssertionValue }
2889 AssertionValue ::= OCTET STRING
2891 PartialAttribute ::= SEQUENCE {
2892 type AttributeDescription,
2893 vals SET OF value AttributeValue }
2895 Attribute ::= PartialAttribute(WITH COMPONENTS {
2897 vals (SIZE(1..MAX))})
2899 MatchingRuleId ::= LDAPString
2901 LDAPResult ::= SEQUENCE {
2902 resultCode ENUMERATED {
2904 operationsError (1),
2906 timeLimitExceeded (3),
2907 sizeLimitExceeded (4),
2910 authMethodNotSupported (7),
2911 strongAuthRequired (8),
2914 adminLimitExceeded (11),
2915 unavailableCriticalExtension (12),
2916 confidentialityRequired (13),
2917 saslBindInProgress (14),
2918 noSuchAttribute (16),
2919 undefinedAttributeType (17),
2920 inappropriateMatching (18),
2921 constraintViolation (19),
2922 attributeOrValueExists (20),
2923 invalidAttributeSyntax (21),
2927 invalidDNSyntax (34),
2928 -- 35 reserved for undefined isLeaf --
2929 aliasDereferencingProblem (36),
2932 Sermersheim Internet-Draft - Expires Feb 2005 Page 50
2934 Lightweight Directory Access Protocol Version 3
2936 inappropriateAuthentication (48),
2937 invalidCredentials (49),
2938 insufficientAccessRights (50),
2941 unwillingToPerform (53),
2944 namingViolation (64),
2945 objectClassViolation (65),
2946 notAllowedOnNonLeaf (66),
2947 notAllowedOnRDN (67),
2948 entryAlreadyExists (68),
2949 objectClassModsProhibited (69),
2950 -- 70 reserved for CLDAP --
2951 affectsMultipleDSAs (71),
2956 diagnosticMessage LDAPString,
2957 referral [3] Referral OPTIONAL }
2959 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI
2961 URI ::= LDAPString -- limited to characters permitted in
2964 Controls ::= SEQUENCE OF control Control
2966 Control ::= SEQUENCE {
2967 controlType LDAPOID,
2968 criticality BOOLEAN DEFAULT FALSE,
2969 controlValue OCTET STRING OPTIONAL }
2971 BindRequest ::= [APPLICATION 0] SEQUENCE {
2972 version INTEGER (1 .. 127),
2974 authentication AuthenticationChoice }
2976 AuthenticationChoice ::= CHOICE {
2977 simple [0] OCTET STRING,
2979 sasl [3] SaslCredentials,
2982 SaslCredentials ::= SEQUENCE {
2983 mechanism LDAPString,
2984 credentials OCTET STRING OPTIONAL }
2986 BindResponse ::= [APPLICATION 1] SEQUENCE {
2987 COMPONENTS OF LDAPResult,
2988 serverSaslCreds [7] OCTET STRING OPTIONAL }
2991 Sermersheim Internet-Draft - Expires Feb 2005 Page 51
2993 Lightweight Directory Access Protocol Version 3
2995 UnbindRequest ::= [APPLICATION 2] NULL
2997 SearchRequest ::= [APPLICATION 3] SEQUENCE {
3003 derefAliases ENUMERATED {
3004 neverDerefAliases (0),
3005 derefInSearching (1),
3006 derefFindingBaseObj (2),
3008 sizeLimit INTEGER (0 .. maxInt),
3009 timeLimit INTEGER (0 .. maxInt),
3012 attributes AttributeSelection }
3014 AttributeSelection ::= SEQUENCE OF selector LDAPString
3015 -- The LDAPString is constrained to
3016 -- <attributeSelection> in Section 4.5.1
3019 and [0] SET SIZE (1..MAX) OF filter Filter,
3020 or [1] SET SIZE (1..MAX) OF filter Filter,
3022 equalityMatch [3] AttributeValueAssertion,
3023 substrings [4] SubstringFilter,
3024 greaterOrEqual [5] AttributeValueAssertion,
3025 lessOrEqual [6] AttributeValueAssertion,
3026 present [7] AttributeDescription,
3027 approxMatch [8] AttributeValueAssertion,
3028 extensibleMatch [9] MatchingRuleAssertion }
3030 SubstringFilter ::= SEQUENCE {
3031 type AttributeDescription,
3032 -- at least one must be present,
3033 -- initial and final can occur at most once
3034 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE {
3035 initial [0] AssertionValue,
3036 any [1] AssertionValue,
3037 final [2] AssertionValue } }
3039 MatchingRuleAssertion ::= SEQUENCE {
3040 matchingRule [1] MatchingRuleId OPTIONAL,
3041 type [2] AttributeDescription OPTIONAL,
3042 matchValue [3] AssertionValue,
3043 dnAttributes [4] BOOLEAN DEFAULT FALSE }
3045 SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
3047 attributes PartialAttributeList }
3050 Sermersheim Internet-Draft - Expires Feb 2005 Page 52
3052 Lightweight Directory Access Protocol Version 3
3054 PartialAttributeList ::= SEQUENCE OF
3055 partialAttribute PartialAttribute
3057 SearchResultReference ::= [APPLICATION 19] SEQUENCE
3058 SIZE (1..MAX) OF uri URI
3060 SearchResultDone ::= [APPLICATION 5] LDAPResult
3062 ModifyRequest ::= [APPLICATION 6] SEQUENCE {
3064 changes SEQUENCE OF change SEQUENCE {
3065 operation ENUMERATED {
3069 modification PartialAttribute } }
3071 ModifyResponse ::= [APPLICATION 7] LDAPResult
3073 AddRequest ::= [APPLICATION 8] SEQUENCE {
3075 attributes AttributeList }
3077 AttributeList ::= SEQUENCE OF attribute Attribute
3079 AddResponse ::= [APPLICATION 9] LDAPResult
3081 DelRequest ::= [APPLICATION 10] LDAPDN
3083 DelResponse ::= [APPLICATION 11] LDAPResult
3085 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
3087 newrdn RelativeLDAPDN,
3088 deleteoldrdn BOOLEAN,
3089 newSuperior [0] LDAPDN OPTIONAL }
3091 ModifyDNResponse ::= [APPLICATION 13] LDAPResult
3093 CompareRequest ::= [APPLICATION 14] SEQUENCE {
3095 ava AttributeValueAssertion }
3097 CompareResponse ::= [APPLICATION 15] LDAPResult
3099 AbandonRequest ::= [APPLICATION 16] MessageID
3101 ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
3102 requestName [0] LDAPOID,
3103 requestValue [1] OCTET STRING OPTIONAL }
3105 ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
3106 COMPONENTS OF LDAPResult,
3107 responseName [10] LDAPOID OPTIONAL,
3109 Sermersheim Internet-Draft - Expires Feb 2005 Page 53
3111 Lightweight Directory Access Protocol Version 3
3113 responseValue [11] OCTET STRING OPTIONAL }
3115 IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
3116 responseName [0] LDAPOID OPTIONAL,
3117 responseValue [1] OCTET STRING OPTIONAL }
3168 Sermersheim Internet-Draft - Expires Feb 2005 Page 54
3170 Lightweight Directory Access Protocol Version 3
3172 Appendix C - Changes
3174 This appendix is non-normative.
3176 This appendix summarizes substantive changes made to RFC 2251 and RFC
3180 C.1 Changes made to RFC 2251:
3182 This section summarizes the substantive changes made to Sections 1,
3183 2, 3.1, and 4 through the remainder of RFC 2251. Readers should
3184 consult [Models] and [AuthMeth] for summaries of changes to other
3190 - Removed IESG note. Post publication of RFC 2251, mandatory LDAP
3191 authentication mechanisms have been standardized which are
3192 sufficient to remove this note. See [AuthMeth] for authentication
3196 C.1.2 Section 3.1 and others
3198 - Removed notes giving history between LDAP v1, v2 and v3. Instead,
3199 added sufficient language so that this document can stand on its
3205 - Clarified where the extensibility features of ASN.1 apply to the
3206 protocol. This change also affected various ASN.1 types.
3207 - Removed the requirement that servers which implement version 3 or
3208 later MUST provide the 'supportedLDAPVersion' attribute. This
3209 statement provided no interoperability advantages.
3214 - There was a mandatory requirement for the server to return a
3215 Notice of Disconnection and drop the connection when a PDU is
3216 malformed in a certain way. This has been clarified such that the
3217 server SHOULD return the Notice of Disconnection, and MUST drop
3221 C.1.5 Section 4.1.1.1
3223 - Clarified that the messageID of requests MUST be non-zero.
3227 Sermersheim Internet-Draft - Expires Feb 2005 Page 55
3229 Lightweight Directory Access Protocol Version 3
3231 - Clarified when it is and isn't appropriate to return an already
3232 used message id. RFC 2251 accidentally imposed synchronous server
3233 behavior in its wording of this.
3238 - Stated that LDAPOID is constrained to <numericoid> from [Models].
3241 C.1.7 Section 4.1.5.1
3243 - Removed the Binary Option from the specification. There are
3244 numerous interoperability problems associated with this method of
3245 alternate attribute type encoding. Work to specify a suitable
3246 replacement is ongoing.
3251 - Removed references to the "binary" encoding as it has been removed
3252 from the specification.
3257 - Removed references to the "binary" encoding as it has been removed
3258 from the specification.
3261 C.1.10 Section 4.1.8
3263 - Combined the definitions of PartialAttribute and Attribute here,
3264 and defined Attribute in terms of PartialAttribute.
3267 C.1.11 Section 4.1.10
3269 - Renamed "errorMessage" to "diagnosticMessage" as it is allowed to
3270 be sent for non-error results.
3271 - Moved some language into Appendix A, and refer the reader there.
3272 - Allowed matchedDN to be present for other result codes than those
3276 C.1.12 Section 4.1.11
3278 - Defined referrals in terms of URIs rather than URLs.
3279 - Removed the requirement that all referral URIs MUST be equally
3280 capable of progressing the operation. The statement was ambiguous
3281 and provided no instructions on how to carry it out.
3282 - Added the requirement that clients MUST NOT loop between servers.
3283 - Clarified the instructions for using LDAPURLs in referrals, and in
3284 doing so added a recommendation that the scope part be present.
3286 Sermersheim Internet-Draft - Expires Feb 2005 Page 56
3288 Lightweight Directory Access Protocol Version 3
3292 C.1.13 Section 4.1.12
3294 - Specified how control values defined in terms of ASN.1 are to be
3296 - Noted that the criticality field is only applied to request
3297 messages (except unbindRequest), and must be ignored when present
3298 on response messages and unbindRequest.
3299 - Added language regarding combinations of controls and the ordering
3300 of controls on a message.
3301 - Specified that when the semantics of the combination of controls
3302 is undefined or unknown, it results in a protocolError.
3303 - Changed "The server MUST be prepared" to "Implementations MUST be
3304 prepared" in the eighth paragraph to reflect that both client and
3305 server implementations must be able to handle this (as both parse
3311 - Mandated that servers return protocolError when the version is not
3313 - Clarified behavior when the simple authentication is used, the
3314 name is empty and the password is non-empty.
3315 - Required servers to not dereference aliases for bind. This was
3316 added for consistency with other operations and to help ensure
3318 - Required that textual passwords be transferred as UTF-8 encoded
3319 Unicode, and added recommendations on string preparation. This was
3320 to help ensure interoperability of passwords being sent from
3324 C.1.15 Section 4.2.1
3326 - This section was largely reorganized for readability and language
3327 was added to clarify the authentication state of failed and
3328 abandoned bind operations.
3329 - Removed: "If a SASL transfer encryption or integrity mechanism has
3330 been negotiated, that mechanism does not support the changing of
3331 credentials from one identity to another, then the client MUST
3332 instead establish a new connection."
3333 Each SASL negotiation is, generally, independent of other SASL
3334 negotiations. If there were dependencies between multiple
3335 negotiations of a particular mechanism, the mechanism technical
3336 specification should detail how applications are to deal with
3337 them. LDAP should not require any special handling. And if an LDAP
3338 client had used such a mechanism, it would have the option of
3339 using another mechanism.
3340 - Dropped MUST imperative in paragraph 3 to align with [Keywords].
3341 - Mandated that clients not send non-bind operations while a bind is
3342 in progress, and suggested that servers not process them if they
3345 Sermersheim Internet-Draft - Expires Feb 2005 Page 57
3347 Lightweight Directory Access Protocol Version 3
3349 are received. This is needed to ensure proper sequencing of the
3350 bind in relationship to other operations.
3353 C.1.16 Section 4.2.3
3355 - Moved most error-related text to Appendix A, and added text
3356 regarding certain errors used in conjunction with the bind
3358 - Prohibited the server from specifying serverSaslCreds when not
3364 - Required both peers to cease transmission and close the LDAP
3365 exchange for the unbind operation.
3370 - Added instructions for future specifications of Unsolicited
3374 C.1.19 Section 4.5.1
3376 - SearchRequest attributes is now defined as an AttributeSelection
3377 type rather than AttributeDescriptionList, and an ABNF is
3379 - SearchRequest attributes may contain duplicate attribute
3380 descriptions. This was previously prohibited. Now servers are
3381 instructed to ignore subsequent names when they are duplicated.
3382 This was relaxed in order to allow different short names and also
3383 OIDs to be requested for an attribute.
3384 - The Filter choices 'and' and 'or', and the SubstringFilter
3385 substrings types are now defined with a lower bound of 1.
3386 - The SubstringFilter substrings 'initial, 'any', and 'final' types
3387 are now AssertionValue rather than LDAPString. Also, added
3388 imperatives stating that 'initial' (if present) must be listed
3389 first, and 'final' (if present) must be listed last.
3390 - Clarified the semantics of the derefAliases choices.
3391 - Added instructions for equalityMatch, substrings, greaterOrEqual,
3392 lessOrEqual, and approxMatch.
3395 C.1.20 Section 4.5.2
3397 - Recommended that servers not use attribute short names when it
3398 knows they are ambiguous or may cause interoperability problems.
3399 - Removed all mention of ExtendedResponse due to lack of
3404 Sermersheim Internet-Draft - Expires Feb 2005 Page 58
3406 Lightweight Directory Access Protocol Version 3
3408 C.1.21 Section 4.5.3
3410 - Made changes similar to those made to Section 4.1.11.
3413 C.1.22 Section 4.5.3.1
3415 - Fixed examples to adhere to changes made to Section 4.5.3.
3420 - Removed restriction that required an EQUALITY matching rule in
3421 order to perform value delete modifications. It is sufficiently
3422 documented that in absence of an equality matching rule, octet
3424 - Replaced AttributeTypeAndValues with Attribute as they are
3426 - Clarified what type of modification changes might temporarily
3432 - Aligned Add operation with X.511 in that the attributes of the RDN
3433 are used in conjunction with the listed attributes to create the
3434 entry. Previously, Add required that the distinguished values be
3435 present in the listed attributes.
3440 - Required servers to not dereference aliases for modify DN. This
3441 was added for consistency with other operations and to help ensure
3443 - Allow modify DN to fail when moving between naming contexts.
3444 - Specified what happens when the attributes of the newrdn are no
3445 present on the entry.
3450 - Clarified that compareFalse means that the compare took place and
3451 the result is false. There was confusion which lead people to
3452 believe that an Undefined match resulted in compareFalse.
3453 - Required servers to not dereference aliases for compare. This was
3454 added for consistency with other operations and to help ensure
3460 - Explained that since abandon returns no response, clients should
3461 not use it if they need to know the outcome.
3463 Sermersheim Internet-Draft - Expires Feb 2005 Page 59
3465 Lightweight Directory Access Protocol Version 3
3467 - Specified that Abandon and Unbind cannot be abandoned.
3472 - Specified how values of extended operations defined in terms of
3473 ASN.1 are to be encoded.
3474 - Added instructions on what extended operation specifications
3476 - Added a recommendation that servers advertise supported extended
3482 - Moved referral-specific instructions into referral-related
3488 - Reworded notes regarding SASL not protecting certain aspects of
3490 - Noted that Servers are encouraged to prevent directory
3491 modifications by clients that have authenticated anonymously
3493 - Added a note regarding the scenario where an identity is changed
3494 (deleted, privileges or credentials modified, etc.).
3495 - Warned against following referrals that may have been injected in
3497 - Noted that servers should protect information equally, whether in
3498 an error condition or not, and mentioned specifically; matchedDN,
3499 diagnosticMessage, and resultCodes.
3500 - Added a note regarding malformed and long encodings.
3505 - Added "EXTESIBILITY IMPLIED" to ASN.1 definition.
3506 - Removed AttributeType. It is not used.
3509 C.2 Changes made to RFC 2830:
3511 This section summarizes the substantive changes made to Sections of
3512 RFC 2830. Readers should consult [AuthMeth] for summaries of changes
3518 - Removed wording indicating that referrals can be returned from
3522 Sermersheim Internet-Draft - Expires Feb 2005 Page 60
3524 Lightweight Directory Access Protocol Version 3
3526 - Removed requirement that only a narrow set of result codes can be
3527 returned. Some result codes are required in certain scenarios, but
3528 any other may be returned if appropriate.
3531 C.2.1 Section 4.13.3.1
3533 - Reworded most of this section and added the requirement that after
3534 the TLS connection has been closed, the server MUST NOT send
3535 responses to any request message received before the TLS closure.
3538 C.3 Changes made to RFC 3771:
3540 - In general, all technical language was transferred in whole.
3541 Supporting and background language seen as redundant due to its
3542 presence in this document was omitted.
3581 Sermersheim Internet-Draft - Expires Feb 2005 Page 61
3583 Lightweight Directory Access Protocol Version 3
3588 Intellectual Property Statement
3590 The IETF takes no position regarding the validity or scope of any
3591 Intellectual Property Rights or other rights that might be claimed to
3592 pertain to the implementation or use of the technology described in
3593 this document or the extent to which any license under such rights
3594 might or might not be available; nor does it represent that it has
3595 made any independent effort to identify any such rights. Information
3596 on the IETF's procedures with respect to rights in IETF Documents can
3597 be found in BCP 78 and BCP 79.
3599 Copies of IPR disclosures made to the IETF Secretariat and any
3600 assurances of licenses to be made available, or the result of an
3601 attempt made to obtain a general license or permission for the use of
3602 such proprietary rights by implementers or users of this
3603 specification can be obtained from the IETF on-line IPR repository at
3604 http://www.ietf.org/ipr.
3606 The IETF invites any interested party to bring to its attention any
3607 copyrights, patents or patent applications, or other proprietary
3608 rights that may cover technology that may be required to implement
3609 this standard. Please address the information to the IETF at ietf-
3615 This document is subject to the rights, licenses and restrictions
3616 contained in BCP 78, and except as set forth therein, the authors
3617 retain all their rights.
3620 Disclaimer of Validity
3622 This document and the information contained herein are provided on an
3623 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
3624 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
3625 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
3626 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
3627 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
3628 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
3640 Sermersheim Internet-Draft - Expires Feb 2005 Page 62
projects / openldap / blob