3 Internet-Draft Editor: J. Sermersheim
4 Intended Category: Standard Track Novell, Inc
5 Document: draft-ietf-ldapbis-protocol-13.txt Mar 2003
14 This document is an Internet-Draft and is in full conformance with
15 all provisions of Section 10 of RFC2026.
17 Internet-Drafts are working documents of the Internet Engineering
18 Task Force (IETF), its areas, and its working groups. Note that other
19 groups may also distribute working documents as Internet-Drafts.
20 Internet-Drafts are draft documents valid for a maximum of six months
21 and may be updated, replaced, or obsoleted by other documents at any
22 time. It is inappropriate to use Internet-Drafts as reference
23 material or to cite them other than as "work in progress."
25 The list of current Internet-Drafts can be accessed at
26 http://www.ietf.org/ietf/1id-abstracts.txt
28 The list of Internet-Draft Shadow Directories can be accessed at
29 http://www.ietf.org/shadow.html.
31 Distribution of this memo is unlimited. Technical discussion of this
32 document will take place on the IETF LDAP Revision Working Group
33 (LDAPbis) mailing list <ietf-ldapbis@openldap.org>. Please send
34 editorial comments directly to the editor <jimse@novell.com>.
39 This document describes the protocol elements, along with their
40 semantics and encodings, for the Lightweight Directory Access
41 Protocol (LDAP). LDAP provides access to distributed directory
42 services that act in accordance with X.500 data and service models.
43 These protocol elements are based on those described in the X.500
44 Directory Access Protocol (DAP).
49 1. Introduction.....................................................2
50 2. Conventions......................................................3
51 3. Protocol Model...................................................3
52 4. Elements of Protocol.............................................3
53 4.1. Common Elements................................................4
54 4.1.1. Message Envelope.............................................4
55 4.1.2. String Types.................................................6
56 4.1.3. Distinguished Name and Relative Distinguished Name...........6
58 Sermersheim Internet-Draft - Expires Sep 2003 Page 1
\f
59 Lightweight Directory Access Protocol Version 3
61 4.1.4. Attribute Descriptions.......................................6
62 4.1.5. Attribute Value..............................................7
63 4.1.6. Attribute Value Assertion....................................7
64 4.1.7. Attribute....................................................7
65 4.1.8. Matching Rule Identifier.....................................8
66 4.1.9. Result Message...............................................8
67 4.1.10. Referral...................................................10
68 4.1.11. Controls...................................................11
69 4.2. Bind Operation................................................12
70 4.3. Unbind Operation..............................................14
71 4.4. Unsolicited Notification......................................15
72 4.5. Search Operation..............................................16
73 4.6. Modify Operation..............................................23
74 4.7. Add Operation.................................................24
75 4.8. Delete Operation..............................................25
76 4.9. Modify DN Operation...........................................26
77 4.10. Compare Operation............................................27
78 4.11. Abandon Operation............................................28
79 4.12. Extended Operation...........................................28
80 4.13. Start TLS Operation..........................................29
81 5. Protocol Element Encodings and Transfer.........................31
82 5.1. Protocol Encoding.............................................31
83 5.2. Transfer Protocols............................................31
84 6. Implementation Guidelines.......................................32
85 6.1. Server Implementations........................................32
86 6.2. Client Implementations........................................32
87 7. Security Considerations.........................................32
88 8. Acknowledgements................................................33
89 9. Normative References............................................33
90 10. Editor's Address...............................................34
91 Appendix A - LDAP Result Codes.....................................35
92 A.1 Non-Error Result Codes.........................................35
93 A.2 Error Result Codes.............................................35
94 A.3 Classes and Precedence of Error Result Codes...................35
95 Appendix C - Change History........................................46
96 C.1 Changes made to RFC 2251:......................................46
97 C.2 Changes made to draft-ietf-ldapbis-protocol-00.txt:............46
98 C.3 Changes made to draft-ietf-ldapbis-protocol-01.txt:............47
99 C.4 Changes made to draft-ietf-ldapbis-protocol-02.txt:............47
100 C.5 Changes made to draft-ietf-ldapbis-protocol-03.txt:............49
101 C.6 Changes made to draft-ietf-ldapbis-protocol-04.txt:............51
102 C.7 Changes made to draft-ietf-ldapbis-protocol-05.txt:............51
103 C.8 Changes made to draft-ietf-ldapbis-protocol-06.txt:............52
104 C.9 Changes made to draft-ietf-ldapbis-protocol-07.txt:............55
105 C.10 Changes made to draft-ietf-ldapbis-protocol-08.txt:...........55
106 C.11 Changes made to draft-ietf-ldapbis-protocol-09.txt:...........55
107 C.12 Changes made to draft-ietf-ldapbis-protocol-10.txt:...........55
108 C.13 Changes made to draft-ietf-ldapbis-protocol-11.txt:...........56
109 C.14 Changes made to draft-ietf-ldapbis-protocol-12.txt:...........56
110 Appendix D - Outstanding Work Items................................56
116 Sermersheim Internet-Draft - Expires Sep 2003 Page 2
\f
117 Lightweight Directory Access Protocol Version 3
119 The Directory is "a collection of open systems cooperating to provide
120 directory services" [X.500]. A Directory user, which may be a human
121 or other entity, accesses the Directory through a client (or
122 Directory User Agent (DUA)). The client, on behalf of the directory
123 user, interacts with one or more servers (or Directory System Agents
124 (DSA)). Clients interact with servers using a directory access
127 This document details the protocol elements of Lightweight Directory
128 Access Protocol, along with their semantics. Following the
129 description of protocol elements, it describes the way in which the
130 protocol is encoded and transferred.
132 This document is an integral part of the LDAP Technical Specification
135 This document replaces RFC 2251. Appendix C holds a detailed log of
136 changes to RFC 2251. Prior to Working Group Last Call, this appendix
137 will be distilled to a summary of changes to RFC 2251.
142 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
143 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
144 to be interpreted as described in [RFC2119].
149 The general model adopted by this protocol is one of clients
150 performing protocol operations against servers. In this model, a
151 client transmits a protocol request describing the operation to be
152 performed to a server. The server is then responsible for performing
153 the necessary operation(s) in the directory. Upon completion of the
154 operation(s), the server returns a response containing any results or
155 errors to the requesting client.
157 Note that although servers are required to return responses whenever
158 such responses are defined in the protocol, there is no requirement
159 for synchronous behavior on the part of either clients or servers.
160 Requests and responses for multiple operations may be exchanged
161 between a client and server in any order, provided the client
162 eventually receives a response for every request that requires one.
164 Note that the core protocol operations defined in this document can
165 be mapped to a subset of the X.500(1997) directory abstract service.
166 However there is not a one-to-one mapping between LDAP protocol
167 operations and DAP operations. Server implementations acting as a
168 gateway to X.500 directories may need to make multiple DAP requests.
171 4. Elements of Protocol
174 Sermersheim Internet-Draft - Expires Sep 2003 Page 3
\f
175 Lightweight Directory Access Protocol Version 3
177 The LDAP protocol is described using Abstract Syntax Notation 1
178 (ASN.1) [X.680], and is transferred using a subset of ASN.1 Basic
179 Encoding Rules [X.690]. Section 5.1 specifies how the protocol is
180 encoded and transferred.
182 In order to support future Standards Track extensions to this
183 protocol, extensibility is implied where it is allowed (per ASN.1).
184 In addition, ellipses (...) have been supplied in ASN.1 types that
185 are explicitly extensible as discussed in [LDAPIANA]. Because of the
186 implied extensibility, clients and servers MUST ignore trailing
187 SEQUENCE elements whose tags they do not recognize.
189 Changes to the LDAP protocol other than through the extension
190 mechanisms described here require a different version number. A
191 client indicates the version it is using as part of the bind request,
192 described in section 4.2. If a client has not sent a bind, the server
193 MUST assume the client is using version 3 or later.
195 Clients may determine the protocol versions a server supports by
196 reading the supportedLDAPVersion attribute from the root DSE
197 [Models]. Servers which implement version 3 or later MUST provide
203 This section describes the LDAPMessage envelope PDU (Protocol Data
204 Unit) format, as well as data type definitions, which are used in the
208 4.1.1. Message Envelope
210 For the purposes of protocol exchanges, all protocol operations are
211 encapsulated in a common envelope, the LDAPMessage, which is defined
214 LDAPMessage ::= SEQUENCE {
217 bindRequest BindRequest,
218 bindResponse BindResponse,
219 unbindRequest UnbindRequest,
220 searchRequest SearchRequest,
221 searchResEntry SearchResultEntry,
222 searchResDone SearchResultDone,
223 searchResRef SearchResultReference,
224 modifyRequest ModifyRequest,
225 modifyResponse ModifyResponse,
226 addRequest AddRequest,
227 addResponse AddResponse,
228 delRequest DelRequest,
229 delResponse DelResponse,
230 modDNRequest ModifyDNRequest,
232 Sermersheim Internet-Draft - Expires Sep 2003 Page 4
\f
233 Lightweight Directory Access Protocol Version 3
235 modDNResponse ModifyDNResponse,
236 compareRequest CompareRequest,
237 compareResponse CompareResponse,
238 abandonRequest AbandonRequest,
239 extendedReq ExtendedRequest,
240 extendedResp ExtendedResponse,
242 controls [0] Controls OPTIONAL }
244 MessageID ::= INTEGER (0 .. maxInt)
246 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
248 The function of the LDAPMessage is to provide an envelope containing
249 common fields required in all protocol exchanges. At this time the
250 only common fields are the message ID and the controls.
252 If the server receives a PDU from the client in which the LDAPMessage
253 SEQUENCE tag cannot be recognized, the messageID cannot be parsed,
254 the tag of the protocolOp is not recognized as a request, or the
255 encoding structures or lengths of data fields are found to be
256 incorrect, then the server MAY return the Notice of Disconnection
257 described in section 4.4.1, with resultCode protocolError, and MUST
258 immediately close the connection.
260 In other cases where the client or server cannot parse a PDU, it
261 SHOULD abruptly close the connection where further communication
262 (including providing notice) would be pernicious. Otherwise, server
263 implementations MUST return an appropriate response to the request,
264 with the resultCode set to protocolError.
266 The ASN.1 type Controls is defined in section 4.1.11.
271 All LDAPMessage envelopes encapsulating responses contain the
272 messageID value of the corresponding request LDAPMessage.
274 The message ID of a request MUST have a non-zero value different from
275 the values of any other requests outstanding in the LDAP session of
276 which this message is a part. The zero value is reserved for the
277 unsolicited notification message.
279 Typical clients increment a counter for each request.
281 A client MUST NOT send a request with the same message ID as an
282 earlier request on the same connection unless it can be determined
283 that the server is no longer servicing the earlier request. Otherwise
284 the behavior is undefined. For operations that do not return
285 responses (unbind, abandon, and abandoned operations), the client
286 SHOULD assume the operation is in progress until a subsequent bind
290 Sermersheim Internet-Draft - Expires Sep 2003 Page 5
\f
291 Lightweight Directory Access Protocol Version 3
296 The LDAPString is a notational convenience to indicate that, although
297 strings of LDAPString type encode as OCTET STRING types, the
298 [ISO10646] character set (a superset of Unicode) is used, encoded
299 following the UTF-8 algorithm [RFC2279]. Note that in the UTF-8
300 algorithm characters which are the same as ASCII (0x0000 through
301 0x007F) are represented as that same ASCII character in a single
302 byte. The other byte values are used to form a variable-length
303 encoding of an arbitrary character.
305 LDAPString ::= OCTET STRING -- UTF-8 encoded,
306 -- ISO 10646 characters
308 The LDAPOID is a notational convenience to indicate that the
309 permitted value of this string is a (UTF-8 encoded) dotted-decimal
310 representation of an OBJECT IDENTIFIER. Although an LDAPOID is
311 encoded as an OCTET STRING, values are limited to the definition of
312 numericoid given in Section 1.3 of [Models].
314 LDAPOID ::= OCTET STRING -- Constrained to numericoid [Models]
318 1.3.6.1.4.1.1466.1.2.3
321 4.1.3. Distinguished Name and Relative Distinguished Name
323 An LDAPDN and a RelativeLDAPDN are respectively defined to be the
324 representation of a distinguished-name and a relative-distinguished-
325 name after encoding according to the specification in [LDAPDN].
327 LDAPDN ::= LDAPString
328 -- Constrained to distinguishedName [LDAPDN]
330 RelativeLDAPDN ::= LDAPString
331 -- Constrained to name-component [LDAPDN]
334 4.1.4. Attribute Descriptions
336 The definition and encoding rules for attribute descriptions are
337 defined in Section 2.5 of [Models]. Briefly, an attribute description
338 is an attribute type and zero or more options.
340 AttributeDescription ::= LDAPString
341 -- Constrained to attributedescription
344 An AttributeDescriptionList describes a list of 0 or more attribute
345 descriptions. (A list of zero elements has special significance in
348 Sermersheim Internet-Draft - Expires Sep 2003 Page 6
\f
349 Lightweight Directory Access Protocol Version 3
352 AttributeDescriptionList ::= SEQUENCE OF
356 4.1.5. Attribute Value
358 A field of type AttributeValue is an OCTET STRING containing an
359 encoded attribute value data type. The value is encoded according to
360 its LDAP-specific encoding definition. The LDAP-specific encoding
361 definitions for different syntaxes and attribute types may be found
362 in other documents, and in particular [Syntaxes].
364 AttributeValue ::= OCTET STRING
366 Note that there is no defined limit on the size of this encoding;
367 thus protocol values may include multi-megabyte attributes (e.g.
370 Attributes may be defined which have arbitrary and non-printable
371 syntax. Implementations MUST NOT display nor attempt to decode as
372 ASN.1, a value if its syntax is not known. The implementation may
373 attempt to discover the subschema of the source entry, and retrieve
374 the values of attributeTypes from it.
376 Clients MUST NOT send attribute values in a request that are not
377 valid according to the syntax defined for the attributes.
380 4.1.6. Attribute Value Assertion
382 The AttributeValueAssertion type definition is similar to the one in
383 the X.500 directory standards. It contains an attribute description
384 and a matching rule assertion value suitable for that type.
386 AttributeValueAssertion ::= SEQUENCE {
387 attributeDesc AttributeDescription,
388 assertionValue AssertionValue }
390 AssertionValue ::= OCTET STRING
392 The syntax of the AssertionValue depends on the context of the LDAP
393 operation being performed. For example, the syntax of the EQUALITY
394 matching rule for an attribute is used when performing a Compare
395 operation. Often this is the same syntax used for values of the
396 attribute type, but in some cases the assertion syntax differs from
397 the value syntax. See objectIdentiferFirstComponentMatch in
398 [Syntaxes] for an example.
403 An attribute consists of an attribute description and one or more
404 values of that attribute description. (Though attributes MUST have at
406 Sermersheim Internet-Draft - Expires Sep 2003 Page 7
\f
407 Lightweight Directory Access Protocol Version 3
409 least one value when stored, due to access control restrictions the
410 set may be empty when transferred from the server to the client. This
411 is described in section 4.5.2, concerning the PartialAttributeList
414 Attribute ::= SEQUENCE {
415 type AttributeDescription,
416 vals SET OF AttributeValue }
418 Each attribute value is distinct in the set (no duplicates). The set
419 of attribute values is unordered. Implementations MUST NOT reply upon
420 any apparent ordering being repeatable.
423 4.1.8. Matching Rule Identifier
425 Matching rules are defined in 4.1.3 of [Models]. A matching rule is
426 identified in the LDAP protocol by the printable representation of
427 either its numericoid, or one of its short name descriptors, e.g.
428 "caseIgnoreIA5Match" or "1.3.6.1.4.1.453.33.33".
430 MatchingRuleId ::= LDAPString
432 Servers which support matching rules for use in the extensibleMatch
433 search filter MUST list the matching rules they implement in
434 subschema entries, using the matchingRules attributes. The server
435 SHOULD also list there, using the matchingRuleUse attribute, the
436 attribute types with which each matching rule can be used. More
437 information is given in section 4.5 of [Syntaxes].
440 4.1.9. Result Message
442 The LDAPResult is the construct used in this protocol to return
443 success or failure indications from servers to clients. To various
444 requests, servers will return responses of LDAPResult or responses
445 containing the components of LDAPResult to indicate the final status
446 of a protocol operation request.
448 LDAPResult ::= SEQUENCE {
449 resultCode ENUMERATED {
453 timeLimitExceeded (3),
454 sizeLimitExceeded (4),
457 authMethodNotSupported (7),
458 strongAuthRequired (8),
461 adminLimitExceeded (11),
462 unavailableCriticalExtension (12),
464 Sermersheim Internet-Draft - Expires Sep 2003 Page 8
\f
465 Lightweight Directory Access Protocol Version 3
467 confidentialityRequired (13),
468 saslBindInProgress (14),
469 noSuchAttribute (16),
470 undefinedAttributeType (17),
471 inappropriateMatching (18),
472 constraintViolation (19),
473 attributeOrValueExists (20),
474 invalidAttributeSyntax (21),
478 invalidDNSyntax (34),
479 -- 35 reserved for undefined isLeaf --
480 aliasDereferencingProblem (36),
482 inappropriateAuthentication (48),
483 invalidCredentials (49),
484 insufficientAccessRights (50),
487 unwillingToPerform (53),
490 namingViolation (64),
491 objectClassViolation (65),
492 notAllowedOnNonLeaf (66),
493 notAllowedOnRDN (67),
494 entryAlreadyExists (68),
495 objectClassModsProhibited (69),
496 -- 70 reserved for CLDAP --
497 affectsMultipleDSAs (71),
501 -- 81-90 reserved for APIs --
503 diagnosticMessage LDAPString,
504 referral [3] Referral OPTIONAL }
506 The result codes enumeration is extensible as defined in Section 3.5
507 of [LDAPIANA]. The meanings of the result codes are given in Appendix
510 The diagnosticMessage field of this construct may, at the server's
511 option, be used to return a string containing a textual, human-
512 readable (terminal control and page formatting characters should be
513 avoided) diagnostic message. As this diagnostic message is not
514 standardized, implementations MUST NOT rely on the values returned.
515 If the server chooses not to return a textual diagnostic, the
516 diagnosticMessage field of the LDAPResult type MUST contain a zero
519 For certain result codes (typically, but not restricted to
520 noSuchObject, aliasProblem, invalidDNSyntax and
522 Sermersheim Internet-Draft - Expires Sep 2003 Page 9
\f
523 Lightweight Directory Access Protocol Version 3
525 aliasDereferencingProblem), the matchedDN field is set to the name of
526 the lowest entry (object or alias) in the directory that was matched.
527 If no aliases were dereferenced while attempting to locate the entry,
528 this will be a truncated form of the name provided, or if aliases
529 were dereferenced, of the resulting name, as defined in section 12.5
530 of [X.511]. The matchedDN field contains a zero length string with
531 all other result codes.
536 The referral result code indicates that the contacted server does not
537 hold the target entry of the request. The referral field is present
538 in an LDAPResult if the LDAPResult.resultCode field value is
539 referral, and absent with all other result codes. It contains one or
540 more references to one or more servers or services that may be
541 accessed via LDAP or other protocols. Referrals can be returned in
542 response to any operation request (except unbind and abandon which do
543 not have responses). At least one URL MUST be present in the
546 During a search operation, after the baseObject is located, and
547 entries are being evaluated, the referral is not returned. Instead,
548 continuation references, described in section 4.5.3, are returned
549 when the search scope spans multiple naming contexts, and several
550 different servers would need to be contacted to complete the
553 Referral ::= SEQUENCE OF LDAPURL -- one or more
555 LDAPURL ::= LDAPString -- limited to characters permitted in
558 If the client wishes to progress the operation, it MUST follow the
559 referral by contacting one of the servers. If multiple URLs are
560 present, the client assumes that any URL may be used to progress the
563 URLs for servers implementing the LDAP protocol are written according
564 to [LDAPURL]. If an alias was dereferenced, the <dn> part of the URL
565 MUST be present, with the new target object name. If the <dn> part is
566 present, the client MUST use this name in its next request to
567 progress the operation, and if it is not present the client will use
568 the same name as in the original request. Some servers (e.g.
569 participating in distributed indexing) may provide a different filter
570 in a referral for a search operation. If the filter part of the URL
571 is present in an LDAPURL, the client MUST use this filter in its next
572 request to progress this search, and if it is not present the client
573 MUST use the same filter as it used for that search. Other aspects of
574 the new request may be the same or different as the request which
575 generated the referral.
580 Sermersheim Internet-Draft - Expires Sep 2003 Page 10
\f
581 Lightweight Directory Access Protocol Version 3
583 Note that UTF-8 characters appearing in a DN or search filter may not
584 be legal for URLs (e.g. spaces) and MUST be escaped using the %
587 Other kinds of URLs may be returned, so long as the operation could
588 be performed using that protocol.
593 A control is a way to specify extension information for an LDAP
594 message. A control only alters the semantics of the message it is
597 Controls ::= SEQUENCE OF Control
599 Control ::= SEQUENCE {
601 criticality BOOLEAN DEFAULT FALSE,
602 controlValue OCTET STRING OPTIONAL }
604 The controlType field MUST be a UTF-8 encoded dotted-decimal
605 representation of an OBJECT IDENTIFIER which uniquely identifies the
606 control. This prevents conflicts between control names.
608 The criticality field is either TRUE or FALSE and only applies to
609 request messages that have a corresponding response message. For all
610 other messages (such as abandonRequest, unbindRequest and all
611 response messages), the criticality field is treated as FALSE.
613 If the server recognizes the control type and it is appropriate for
614 the operation, the server will make use of the control when
615 performing the operation.
617 If the server does not recognize the control type or it is not
618 appropriate for the operation, and the criticality field is TRUE, the
619 server MUST NOT perform the operation, and MUST instead return the
620 resultCode unavailableCriticalExtension.
622 If the control is unrecognized or inappropriate but the criticality
623 field is FALSE, the server MUST ignore the control.
625 The controlValue contains any information associated with the
626 control, and its format is defined for the control. Implementations
627 MUST be prepared to handle arbitrary contents of the controlValue
628 octet string, including zero bytes. It is absent only if there is no
629 value information which is associated with a control of its type.
631 This document does not specify any controls. Controls may be
632 specified in other documents. The specification of a control consists
635 - the OBJECT IDENTIFIER assigned to the control,
638 Sermersheim Internet-Draft - Expires Sep 2003 Page 11
\f
639 Lightweight Directory Access Protocol Version 3
641 - whether the control is always noncritical, always critical, or
642 critical at the client's option,
644 - the format of the controlValue contents of the control,
646 - the semantics of the control,
648 - and optionally, semantics regarding the combination of the control
651 Servers list the controlType of all request controls they recognize
652 in the supportedControl attribute [Models] in the root DSE.
654 Controls should not be combined unless the semantics of the
655 combination has been specified. The semantics of control
656 combinations, if specified, are generally found in the control
657 specification most recently published. In the absence of combination
658 semantics, the behavior of the operation is undefined.
659 Additionally, the order of a combination of controls in the SEQUENCE
660 is ignored unless the control specification(s) describe(s)
661 combination semantics.
666 The function of the Bind Operation is to allow authentication
667 information to be exchanged between the client and server. Prior to
668 the first BindRequest, the implied identity is anonymous. Refer to
669 [AuthMeth] for the authentication-related semantics of this
672 The Bind Request is defined as follows:
674 BindRequest ::= [APPLICATION 0] SEQUENCE {
675 version INTEGER (1 .. 127),
677 authentication AuthenticationChoice }
679 AuthenticationChoice ::= CHOICE {
680 simple [0] OCTET STRING,
682 sasl [3] SaslCredentials,
685 SaslCredentials ::= SEQUENCE {
686 mechanism LDAPString,
687 credentials OCTET STRING OPTIONAL }
689 Parameters of the Bind Request are:
691 - version: A version number indicating the version of the protocol
692 to be used in this protocol session. This document describes
693 version 3 of the LDAP protocol. Note that there is no version
694 negotiation, and the client just sets this parameter to the
696 Sermersheim Internet-Draft - Expires Sep 2003 Page 12
\f
697 Lightweight Directory Access Protocol Version 3
699 version it desires. If the server does not support the specified
700 version, it responds with protocolError in the resultCode field of
703 - name: The name of the directory object that the client wishes to
704 bind as. This field may take on a null value (a zero length
705 string) for the purposes of anonymous binds ([AuthMeth] section 7)
706 or when using SASL authentication ([AuthMeth] section 4.3). Server
707 behavior is undefined when the name is a null value, simple
708 authentication is used, and a password is specified. The server
709 SHOULD NOT perform any alias dereferencing in determining the
712 - authentication: information used to authenticate the name, if any,
713 provided in the Bind Request. This type is extensible as defined
714 in Section 3.6 of [LDAPIANA]. Servers that do not support a choice
715 supplied by a client will return authMethodNotSupported in the
716 result code of the BindResponse.
718 Authorization is the use of this authentication information when
719 performing operations. Authorization MAY be affected by factors
720 outside of the LDAP Bind Request, such as lower layer security
724 4.2.1. Processing of the Bind Request
726 Upon receipt of a BindRequest, the server MUST ensure there are no
727 outstanding operations in progress on the connection (This simplifies
728 server implementation). The server then proceeds to authenticate the
729 client in either a single-step, or multi-step bind process. Each step
730 requires the server to return a BindResponse to indicate the status
733 If the client did not bind before sending a request and receives an
734 operationsError, it may then send a Bind Request. If this also fails
735 or the client chooses not to bind on the existing connection, it may
736 close the connection, reopen it and begin again by first sending a
737 PDU with a Bind Request. This will aid in interoperating with servers
738 implementing other versions of LDAP.
740 Clients MAY send multiple Bind Requests on a connection to change
741 their credentials. Authentication from earlier binds is subsequently
742 ignored. A failed or abandoned Bind Operation has the effect of
743 leaving the connection in an anonymous state. To arrive at a known
744 authentication state after abandoning a bind operation, clients may
745 unbind, rebind, or make use of the BindResponse. If a SASL transfer
746 encryption or integrity mechanism has been negotiated, and that
747 mechanism does not support the changing of credentials from one
748 identity to another, then the client MUST instead establish a new
751 For some SASL authentication mechanisms, it may be necessary for the
752 client to invoke the BindRequest multiple times. This is indicated by
754 Sermersheim Internet-Draft - Expires Sep 2003 Page 13
\f
755 Lightweight Directory Access Protocol Version 3
757 the server sending a BindResponse with the resultCode set to
758 saslBindInProgress. This indicates that the server requires the
759 client to send a new bind request, with the same sasl mechanism, to
760 continue the authentication process. If at any stage the client
761 wishes to abort the bind process it MAY unbind and then drop the
762 underlying connection. Clients MUST NOT invoke operations between two
763 Bind Requests made as part of a multi-stage bind.
765 A client may abort a SASL bind negotiation by sending a BindRequest
766 with a different value in the mechanism field of SaslCredentials, or
767 an AuthenticationChoice other than sasl.
769 If the client sends a BindRequest with the sasl mechanism field as an
770 empty string, the server MUST return a BindResponse with
771 authMethodNotSupported as the resultCode. This will allow clients to
772 abort a negotiation if it wishes to try again with the same SASL
778 The Bind Response is defined as follows.
780 BindResponse ::= [APPLICATION 1] SEQUENCE {
781 COMPONENTS OF LDAPResult,
782 serverSaslCreds [7] OCTET STRING OPTIONAL }
784 BindResponse consists simply of an indication from the server of the
785 status of the client's request for authentication.
787 A successful bind operation is indicated by a BindResponse with a
788 resultCode set to success (0). Otherwise, an appropriate resultCode
789 is set in the BindResponse. For bind, the protocolError (2)
790 resultCode may be used to indicate that the version number supplied
791 by the client is unsupported.
793 If the server does not support the client's requested protocol
794 version, it MUST set the resultCode to protocolError.
796 If the client receives a BindResponse response where the resultCode
797 was protocolError, it MUST close the connection as the server will be
798 unwilling to accept further operations. (This is for compatibility
799 with earlier versions of LDAP, in which the bind was always the first
800 operation, and there was no negotiation.)
802 The serverSaslCreds are used as part of a SASL-defined bind mechanism
803 to allow the client to authenticate the server to which it is
804 communicating, or to perform "challenge-response" authentication. If
805 the client bound with the simple choice, or the SASL mechanism does
806 not require the server to return information to the client, then this
807 field is not to be included in the result.
810 4.3. Unbind Operation
812 Sermersheim Internet-Draft - Expires Sep 2003 Page 14
\f
813 Lightweight Directory Access Protocol Version 3
816 The function of the Unbind Operation is to terminate a protocol
817 session. The Unbind Operation is defined as follows:
819 UnbindRequest ::= [APPLICATION 2] NULL
821 The Unbind Operation has no response defined. Upon transmission of an
822 UnbindRequest, a protocol client MUST assume that the protocol
823 session is terminated. Upon receipt of an UnbindRequest, a protocol
824 server MUST assume that the requesting client has terminated the
825 session and that all outstanding requests may be discarded, and MUST
826 close the connection.
829 4.4. Unsolicited Notification
831 An unsolicited notification is an LDAPMessage sent from the server to
832 the client which is not in response to any LDAPMessage received by
833 the server. It is used to signal an extraordinary condition in the
834 server or in the connection between the client and the server. The
835 notification is of an advisory nature, and the server will not expect
836 any response to be returned from the client.
838 The unsolicited notification is structured as an LDAPMessage in which
839 the messageID is 0 and protocolOp is of the extendedResp form. The
840 responseName field of the ExtendedResponse is present. The LDAPOID
841 value MUST be unique for this notification, and not be used in any
844 One unsolicited notification (Notice of Disconnection) is defined in
848 4.4.1. Notice of Disconnection
850 This notification may be used by the server to advise the client that
851 the server is about to close the connection due to an error
852 condition. Note that this notification is NOT a response to an unbind
853 requested by the client: the server MUST follow the procedures of
854 section 4.3. This notification is intended to assist clients in
855 distinguishing between an error condition and a transient network
856 failure. As with a connection close due to network failure, the
857 client MUST NOT assume that any outstanding requests which modified
858 the directory have succeeded or failed.
860 The responseName is 1.3.6.1.4.1.1466.20036, the response field is
861 absent, and the resultCode is used to indicate the reason for the
864 The following resultCode values are to be used in this notification:
866 - protocolError: The server has received data from the client in
867 which the LDAPMessage structure could not be parsed.
870 Sermersheim Internet-Draft - Expires Sep 2003 Page 15
\f
871 Lightweight Directory Access Protocol Version 3
873 - strongAuthRequired: The server has detected that an established
874 underlying security association protecting communication between
875 the client and server has unexpectedly failed or been compromised.
877 - unavailable: This server will stop accepting new connections and
878 operations on all existing connections, and be unavailable for an
879 extended period of time. The client may make use of an alternative
882 After sending this notice, the server MUST close the connection.
883 After receiving this notice, the client MUST NOT transmit any further
884 on the connection, and may abruptly close the connection.
887 4.5. Search Operation
889 The Search Operation allows a client to request that a search be
890 performed on its behalf by a server. This can be used to read
891 attributes from a single entry, from entries immediately below a
892 particular entry, or a whole subtree of entries.
895 4.5.1. Search Request
897 The Search Request is defined as follows:
899 SearchRequest ::= [APPLICATION 3] SEQUENCE {
905 derefAliases ENUMERATED {
906 neverDerefAliases (0),
907 derefInSearching (1),
908 derefFindingBaseObj (2),
910 sizeLimit INTEGER (0 .. maxInt),
911 timeLimit INTEGER (0 .. maxInt),
914 attributes AttributeDescriptionList }
917 and [0] SET SIZE (1..MAX) OF Filter,
918 or [1] SET SIZE (1..MAX) OF Filter,
920 equalityMatch [3] AttributeValueAssertion,
921 substrings [4] SubstringFilter,
922 greaterOrEqual [5] AttributeValueAssertion,
923 lessOrEqual [6] AttributeValueAssertion,
924 present [7] AttributeDescription,
925 approxMatch [8] AttributeValueAssertion,
926 extensibleMatch [9] MatchingRuleAssertion }
928 Sermersheim Internet-Draft - Expires Sep 2003 Page 16
\f
929 Lightweight Directory Access Protocol Version 3
932 SubstringFilter ::= SEQUENCE {
933 type AttributeDescription,
934 -- at least one must be present,
935 -- initial and final can occur at most once
936 substrings SEQUENCE OF CHOICE {
937 initial [0] AssertionValue,
938 any [1] AssertionValue,
939 final [2] AssertionValue } }
941 MatchingRuleAssertion ::= SEQUENCE {
942 matchingRule [1] MatchingRuleId OPTIONAL,
943 type [2] AttributeDescription OPTIONAL,
944 matchValue [3] AssertionValue,
945 dnAttributes [4] BOOLEAN DEFAULT FALSE }
947 Parameters of the Search Request are:
949 - baseObject: An LDAPDN that is the base object entry relative to
950 which the search is to be performed.
952 - scope: An indicator of the scope of the search to be performed.
953 The semantics of the possible values of this field are identical
954 to the semantics of the scope field in the X.511 Search Operation.
956 - derefAliases: An indicator as to how alias objects (as defined in
957 X.501) are to be handled in searching. The semantics of the
958 possible values of this field are:
960 neverDerefAliases: do not dereference aliases in searching
961 or in locating the base object of the search;
963 derefInSearching: dereference aliases in subordinates of
964 the base object in searching, but not in locating the base
965 object of the search;
967 derefFindingBaseObj: dereference aliases in locating the
968 base object of the search, but not when searching
969 subordinates of the base object;
971 derefAlways: dereference aliases both in searching and in
972 locating the base object of the search.
974 - sizeLimit: A size limit that restricts the maximum number of
975 entries to be returned as a result of the search. A value of 0 in
976 this field indicates that no client-requested size limit
977 restrictions are in effect for the search. Servers may enforce a
978 maximum number of entries to return.
980 - timeLimit: A time limit that restricts the maximum time (in
981 seconds) allowed for a search. A value of 0 in this field
982 indicates that no client-requested time limit restrictions are in
983 effect for the search.
986 Sermersheim Internet-Draft - Expires Sep 2003 Page 17
\f
987 Lightweight Directory Access Protocol Version 3
989 - typesOnly: An indicator as to whether search results will contain
990 both attribute descriptions and values, or just attribute
991 descriptions. Setting this field to TRUE causes only attribute
992 descriptions (no values) to be returned. Setting this field to
993 FALSE causes both attribute descriptions and values to be
996 - filter: A filter that defines the conditions that must be
997 fulfilled in order for the search to match a given entry.
999 The 'and', 'or' and 'not' choices can be used to form combinations
1000 of filters. At least one filter element MUST be present in an
1001 'and' or 'or' choice. The others match against individual
1002 attribute values of entries in the scope of the search.
1003 (Implementor's note: the 'not' filter is an example of a tagged
1004 choice in an implicitly-tagged module. In BER this is treated as
1005 if the tag was explicit.)
1007 A server MUST evaluate filters according to the three-valued logic
1008 of X.511 (1993) section 7.8.1. In summary, a filter is evaluated
1009 to either "TRUE", "FALSE" or "Undefined". If the filter evaluates
1010 to TRUE for a particular entry, then the attributes of that entry
1011 are returned as part of the search result (subject to any
1012 applicable access control restrictions). If the filter evaluates
1013 to FALSE or Undefined, then the entry is ignored for the search.
1015 A filter of the "and" choice is TRUE if all the filters in the SET
1016 OF evaluate to TRUE, FALSE if at least one filter is FALSE, and
1017 otherwise Undefined. A filter of the "or" choice is FALSE if all
1018 of the filters in the SET OF evaluate to FALSE, TRUE if at least
1019 one filter is TRUE, and Undefined otherwise. A filter of the "not"
1020 choice is TRUE if the filter being negated is FALSE, FALSE if it
1021 is TRUE, and Undefined if it is Undefined.
1023 The present match evaluates to TRUE where there is an attribute or
1024 subtype of the specified attribute description present in an
1025 entry, and FALSE otherwise (including a presence test with an
1026 unrecognized attribute description.)
1028 The matching rule for equalityMatch filter items is defined by the
1029 EQUALITY matching rule for the attribute type.
1031 The matching rule and assertion syntax for AssertionValues in a
1032 substrings filter item is defined by the SUBSTR matching rule for
1035 The matching rule for greaterOrEqual and lessOrEqual filter items
1036 is defined by the ORDERING matching rule for the attribute type.
1038 The matching rule for approxMatch filter items is implementation-
1039 defined. If approximate matching is not supported by the server,
1040 the filter item should be treated as an equalityMatch.
1042 The extensibleMatch is new in this version of LDAP. If the
1044 Sermersheim Internet-Draft - Expires Sep 2003 Page 18
\f
1045 Lightweight Directory Access Protocol Version 3
1047 matchingRule field is absent, the type field MUST be present, and
1048 the equality match is performed for that type. If the type field
1049 is absent and matchingRule is present, the matchValue is compared
1050 against all attributes in an entry which support that
1051 matchingRule, and the matchingRule determines the syntax for the
1052 assertion value (the filter item evaluates to TRUE if it matches
1053 with at least one attribute in the entry, FALSE if it does not
1054 match any attribute in the entry, and Undefined if the
1055 matchingRule is not recognized or the assertionValue cannot be
1056 parsed.) If the type field is present and matchingRule is present,
1057 the matchingRule MUST be one permitted for use with that type,
1058 otherwise the filter item is undefined. If the dnAttributes field
1059 is set to TRUE, the match is applied against all the
1060 AttributeValueAssertions in an entry's distinguished name as well,
1061 and also evaluates to TRUE if there is at least one attribute in
1062 the distinguished name for which the filter item evaluates to
1063 TRUE. (Editors note: The dnAttributes field is present so that
1064 there does not need to be multiple versions of generic matching
1065 rules such as for word matching, one to apply to entries and
1066 another to apply to entries and dn attributes as well).
1068 A filter item evaluates to Undefined when the server would not be
1069 able to determine whether the assertion value matches an entry. If
1070 an attribute description in an equalityMatch, substrings,
1071 greaterOrEqual, lessOrEqual, approxMatch or extensibleMatch filter
1072 is not recognized by the server, a matching rule id in the
1073 extensibleMatch is not recognized by the server, the assertion
1074 value cannot be parsed, or the type of filtering requested is not
1075 implemented, then the filter is Undefined. Thus for example if a
1076 server did not recognize the attribute type shoeSize, a filter of
1077 (shoeSize=*) would evaluate to FALSE, and the filters
1078 (shoeSize=12), (shoeSize>=12) and (shoeSize<=12) would evaluate to
1081 Servers MUST NOT return errors if attribute descriptions or
1082 matching rule ids are not recognized, or assertion values cannot
1083 be parsed. More details of filter processing are given in section
1086 - attributes: A list of the attributes to be returned from each
1087 entry which matches the search filter. There are two special
1088 values which may be used: an empty list with no attributes, and
1089 the attribute description string "*". Both of these signify that
1090 all user attributes are to be returned. (The "*" allows the client
1091 to request all user attributes in addition to any specified
1092 operational attributes).
1094 Attributes MUST be named at most once in the list, and are
1095 returned at most once in an entry. If there are attribute
1096 descriptions in the list which are not recognized, they are
1097 ignored by the server.
1099 If the client does not want any attributes returned, it can
1100 specify a list containing only the attribute with OID "1.1". This
1102 Sermersheim Internet-Draft - Expires Sep 2003 Page 19
\f
1103 Lightweight Directory Access Protocol Version 3
1105 OID was chosen arbitrarily and does not correspond to any
1108 Client implementors should note that even if all user attributes
1109 are requested, some attributes of the entry may not be included in
1110 search results due to access controls or other restrictions.
1111 Furthermore, servers will not return operational attributes, such
1112 as objectClasses or attributeTypes, unless they are listed by
1113 name, since there may be extremely large number of values for
1114 certain operational attributes. (A list of operational attributes
1115 for use in LDAP is given in [Syntaxes].)
1117 Note that an X.500 "list"-like operation can be emulated by the
1118 client requesting a one-level LDAP search operation with a filter
1119 checking for the presence of the objectClass attribute, and that an
1120 X.500 "read"-like operation can be emulated by a base object LDAP
1121 search operation with the same filter. A server which provides a
1122 gateway to X.500 is not required to use the Read or List operations,
1123 although it may choose to do so, and if it does, it must provide the
1124 same semantics as the X.500 search operation.
1127 4.5.2. Search Result
1129 The results of the search attempted by the server upon receipt of a
1130 Search Request are returned in Search Responses, which are LDAP
1131 messages containing either SearchResultEntry, SearchResultReference,
1132 or SearchResultDone data types.
1134 SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
1136 attributes PartialAttributeList }
1138 PartialAttributeList ::= SEQUENCE OF SEQUENCE {
1139 type AttributeDescription,
1140 vals SET OF AttributeValue }
1141 -- implementors should note that the PartialAttributeList may
1142 -- have zero elements (if none of the attributes of that entry
1143 -- were requested, or could be returned), and that the vals set
1144 -- may also have zero elements (if types only was requested, or
1145 -- all values were excluded from the result.)
1147 SearchResultReference ::= [APPLICATION 19] SEQUENCE OF LDAPURL
1148 -- at least one LDAPURL element must be present
1150 SearchResultDone ::= [APPLICATION 5] LDAPResult
1152 Upon receipt of a Search Request, a server will perform the necessary
1155 If the LDAP session is operating over a connection-oriented transport
1156 such as TCP, the server will return to the client a sequence of
1157 responses in separate LDAP messages. There may be zero or more
1158 responses containing SearchResultEntry, one for each entry found
1160 Sermersheim Internet-Draft - Expires Sep 2003 Page 20
\f
1161 Lightweight Directory Access Protocol Version 3
1163 during the search. There may also be zero or more responses
1164 containing SearchResultReference, one for each area not explored by
1165 this server during the search. The SearchResultEntry and
1166 SearchResultReference PDUs may come in any order. Following all the
1167 SearchResultReference responses and all SearchResultEntry responses
1168 to be returned by the server, the server will return a response
1169 containing the SearchResultDone, which contains an indication of
1170 success, or detailing any errors that have occurred.
1172 Each entry returned in a SearchResultEntry will contain all
1173 appropriate attributes as specified in the attributes field of the
1174 Search Request. Return of attributes is subject to access control and
1175 other administrative policy.
1177 Some attributes may be constructed by the server and appear in a
1178 SearchResultEntry attribute list, although they are not stored
1179 attributes of an entry. Clients SHOULD NOT assume that all attributes
1180 can be modified, even if permitted by access control.
1182 If the server's schema defines a textual name for an attribute type,
1183 it MUST use a textual name for attributes of that attribute type by
1184 specifying one of the textual names as the value of the attribute
1185 type. Otherwise, the server uses the object identifier for the
1186 attribute type by specifying the object identifier, in ldapOID form,
1187 as the value of attribute type.
1190 4.5.3. Continuation References in the Search Result
1192 If the server was able to locate the entry referred to by the
1193 baseObject but was unable to search all the entries in the scope at
1194 and under the baseObject, the server may return one or more
1195 SearchResultReference entries, each containing a reference to another
1196 set of servers for continuing the operation. A server MUST NOT return
1197 any SearchResultReference if it has not located the baseObject and
1198 thus has not searched any entries; in this case it would return a
1199 SearchResultDone containing a referral resultCode.
1201 If a server holds a copy or partial copy of the subordinate naming
1202 context, it may use the search filter to determine whether or not to
1203 return a SearchResultReference response. Otherwise
1204 SearchResultReference responses are always returned when in scope.
1206 The SearchResultReference is of the same data type as the Referral.
1207 URLs for servers implementing the LDAP protocol are written according
1208 to [LDAPURL]. The <dn> part MUST be present in the URL, with the new
1209 target object name. The client MUST use this name in its next
1210 request. Some servers (e.g. part of a distributed index exchange
1211 system) may provide a different filter in the URLs of the
1212 SearchResultReference. If the filter part of the URL is present in an
1213 LDAP URL, the client MUST use the new filter in its next request to
1214 progress the search, and if the filter part is absent the client will
1215 use again the same filter. If the originating search scope was
1216 singleLevel, the scope part of the URL will be baseObject. Other
1218 Sermersheim Internet-Draft - Expires Sep 2003 Page 21
\f
1219 Lightweight Directory Access Protocol Version 3
1221 aspects of the new search request may be the same or different as the
1222 search which generated the continuation references.
1223 Other kinds of URLs may be returned so long as the operation could be
1224 performed using that protocol.
1226 The name of an unexplored subtree in a SearchResultReference need not
1227 be subordinate to the base object.
1229 In order to complete the search, the client MUST issue a new search
1230 operation for each SearchResultReference that is returned. Note that
1231 the abandon operation described in section 4.11 applies only to a
1232 particular operation sent on a connection between a client and
1233 server, and if the client has multiple outstanding search operations,
1234 it MUST abandon each operation individually.
1239 For example, suppose the contacted server (hosta) holds the entry
1240 "DC=Example,DC=NET" and the entry "CN=Manager,DC=Example,DC=NET". It
1241 knows that either LDAP-capable servers (hostb) or (hostc) hold
1242 "OU=People,DC=Example,DC=NET" (one is the master and the other server
1243 a shadow), and that LDAP-capable server (hostd) holds the subtree
1244 "OU=Roles,DC=Example,DC=NET". If a subtree search of
1245 "DC=Example,DC=NET" is requested to the contacted server, it may
1246 return the following:
1248 SearchResultEntry for DC=Example,DC=NET
1249 SearchResultEntry for CN=Manager,DC=Example,DC=NET
1250 SearchResultReference {
1251 ldap://hostb/OU=People,DC=Example,DC=NET
1252 ldap://hostc/OU=People,DC=Example,DC=NET
1254 SearchResultReference {
1255 ldap://hostd/OU=Roles,DC=Example,DC=NET
1257 SearchResultDone (success)
1259 Client implementors should note that when following a
1260 SearchResultReference, additional SearchResultReference may be
1261 generated. Continuing the example, if the client contacted the server
1262 (hostb) and issued the search for the subtree
1263 "OU=People,DC=Example,DC=NET", the server might respond as follows:
1265 SearchResultEntry for OU=People,DC=Example,DC=NET
1266 SearchResultReference {
1267 ldap://hoste/OU=Managers,OU=People,DC=Example,DC=NET
1269 SearchResultReference {
1270 ldap://hostf/OU=Consultants,OU=People,DC=Example,DC=NET
1272 SearchResultDone (success)
1276 Sermersheim Internet-Draft - Expires Sep 2003 Page 22
\f
1277 Lightweight Directory Access Protocol Version 3
1279 If the contacted server does not hold the base object for the search,
1280 then it will return a referral to the client. For example, if the
1281 client requests a subtree search of "DC=Example,DC=ORG" to hosta, the
1282 server may return only a SearchResultDone containing a referral.
1284 SearchResultDone (referral) {
1285 ldap://hostg/DC=Example,DC=ORG??sub
1289 4.6. Modify Operation
1291 The Modify Operation allows a client to request that a modification
1292 of an entry be performed on its behalf by a server. The Modify
1293 Request is defined as follows:
1295 ModifyRequest ::= [APPLICATION 6] SEQUENCE {
1297 modification SEQUENCE OF SEQUENCE {
1298 operation ENUMERATED {
1302 modification AttributeTypeAndValues } }
1304 AttributeTypeAndValues ::= SEQUENCE {
1305 type AttributeDescription,
1306 vals SET OF AttributeValue }
1308 Parameters of the Modify Request are:
1310 - object: The object to be modified. The value of this field
1311 contains the DN of the entry to be modified. The server will not
1312 perform any alias dereferencing in determining the object to be
1315 - modification: A list of modifications to be performed on the
1316 entry. The entire list of entry modifications MUST be performed in
1317 the order they are listed, as a single atomic operation. While
1318 individual modifications may violate the directory schema, the
1319 resulting entry after the entire list of modifications is
1320 performed MUST conform to the requirements of the directory
1321 schema. The values that may be taken on by the 'operation' field
1322 in each modification construct have the following semantics
1325 add: add values listed to the given attribute, creating the
1326 attribute if necessary;
1328 delete: delete values listed from the given attribute,
1329 removing the entire attribute if no values are listed, or
1330 if all current values of the attribute are listed for
1334 Sermersheim Internet-Draft - Expires Sep 2003 Page 23
\f
1335 Lightweight Directory Access Protocol Version 3
1337 replace: replace all existing values of the given attribute
1338 with the new values listed, creating the attribute if it
1339 did not already exist. A replace with no value will delete
1340 the entire attribute if it exists, and is ignored if the
1341 attribute does not exist.
1343 The result of the modification attempted by the server upon receipt
1344 of a Modify Request is returned in a Modify Response, defined as
1347 ModifyResponse ::= [APPLICATION 7] LDAPResult
1349 Upon receipt of a Modify Request, a server will perform the necessary
1350 modifications to the DIT.
1352 The server will return to the client a single Modify Response
1353 indicating either the successful completion of the DIT modification,
1354 or the reason that the modification failed. Note that due to the
1355 requirement for atomicity in applying the list of modifications in
1356 the Modify Request, the client may expect that no modifications of
1357 the DIT have been performed if the Modify Response received indicates
1358 any sort of error, and that all requested modifications have been
1359 performed if the Modify Response indicates successful completion of
1360 the Modify Operation. If the connection fails, whether the
1361 modification occurred or not is indeterminate.
1363 The Modify Operation cannot be used to remove from an entry any of
1364 its distinguished values, those values which form the entry's
1365 relative distinguished name. An attempt to do so will result in the
1366 server returning the error notAllowedOnRDN. The Modify DN Operation
1367 described in section 4.9 is used to rename an entry.
1369 Note that due to the simplifications made in LDAP, there is not a
1370 direct mapping of the modifications in an LDAP ModifyRequest onto the
1371 EntryModifications of a DAP ModifyEntry operation, and different
1372 implementations of LDAP-DAP gateways may use different means of
1373 representing the change. If successful, the final effect of the
1374 operations on the entry MUST be identical.
1379 The Add Operation allows a client to request the addition of an entry
1380 into the directory. The Add Request is defined as follows:
1382 AddRequest ::= [APPLICATION 8] SEQUENCE {
1384 attributes AttributeList }
1386 AttributeList ::= SEQUENCE OF SEQUENCE {
1387 type AttributeDescription,
1388 vals SET OF AttributeValue }
1390 Parameters of the Add Request are:
1392 Sermersheim Internet-Draft - Expires Sep 2003 Page 24
\f
1393 Lightweight Directory Access Protocol Version 3
1396 - entry: the Distinguished Name of the entry to be added. Note that
1397 the server will not dereference any aliases in locating the entry
1400 - attributes: the list of attributes that make up the content of the
1401 entry being added. Clients MUST include distinguished values
1402 (those forming the entry's own RDN) in this list, the objectClass
1403 attribute, and values of any mandatory attributes of the listed
1404 object classes. Clients MUST NOT supply NO-USER-MODIFICATION
1405 attributes such as the createTimestamp or creatorsName attributes,
1406 since the server maintains these automatically.
1408 The entry named in the entry field of the AddRequest MUST NOT exist
1409 for the AddRequest to succeed. The parent of the object and alias
1410 entries to be added MUST exist. For example, if the client attempted
1411 to add "CN=JS,DC=Example,DC=NET", the "DC=Example,DC=NET" entry did
1412 not exist, and the "DC=NET" entry did exist, then the server would
1413 return the error noSuchObject with the matchedDN field containing
1414 "DC=NET". If the parent entry exists but is not in a naming context
1415 held by the server, the server SHOULD return a referral to the server
1416 holding the parent entry.
1418 Server implementations SHOULD NOT restrict where entries can be
1419 located in the directory unless DIT structure rules are in place.
1420 Some servers MAY allow the administrator to restrict the classes of
1421 entries which can be added to the directory.
1423 Upon receipt of an Add Request, a server will attempt to add the
1424 requested entry. The result of the add attempt will be returned to
1425 the client in the Add Response, defined as follows:
1427 AddResponse ::= [APPLICATION 9] LDAPResult
1429 A response of success indicates that the new entry is present in the
1433 4.8. Delete Operation
1435 The Delete Operation allows a client to request the removal of an
1436 entry from the directory. The Delete Request is defined as follows:
1438 DelRequest ::= [APPLICATION 10] LDAPDN
1440 The Delete Request consists of the Distinguished Name of the entry to
1441 be deleted. Note that the server will not dereference aliases while
1442 resolving the name of the target entry to be removed, and that only
1443 leaf entries (those with no subordinate entries) can be deleted with
1446 The result of the delete attempted by the server upon receipt of a
1447 Delete Request is returned in the Delete Response, defined as
1450 Sermersheim Internet-Draft - Expires Sep 2003 Page 25
\f
1451 Lightweight Directory Access Protocol Version 3
1454 DelResponse ::= [APPLICATION 11] LDAPResult
1456 Upon receipt of a Delete Request, a server will attempt to perform
1457 the entry removal requested. The result of the delete attempt will be
1458 returned to the client in the Delete Response.
1461 4.9. Modify DN Operation
1463 The Modify DN Operation allows a client to change the leftmost (least
1464 significant) component of the name of an entry in the directory,
1465 and/or to move a subtree of entries to a new location in the
1466 directory. The Modify DN Request is defined as follows:
1468 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
1470 newrdn RelativeLDAPDN,
1471 deleteoldrdn BOOLEAN,
1472 newSuperior [0] LDAPDN OPTIONAL }
1474 Parameters of the Modify DN Request are:
1476 - entry: the Distinguished Name of the entry to be changed. This
1477 entry may or may not have subordinate entries. Note that the
1478 server will not dereference any aliases in locating the entry to
1481 - newrdn: the RDN that will form the leftmost component of the new
1484 - deleteoldrdn: a boolean parameter that controls whether the old
1485 RDN attribute values are to be retained as attributes of the
1486 entry, or deleted from the entry.
1488 - newSuperior: if present, this is the Distinguished Name of an
1489 existing object entry which becomes the immediate superior of the
1492 The result of the name change attempted by the server upon receipt of
1493 a Modify DN Request is returned in the Modify DN Response, defined as
1496 ModifyDNResponse ::= [APPLICATION 13] LDAPResult
1498 Upon receipt of a ModifyDNRequest, a server will attempt to perform
1499 the name change. The result of the name change attempt will be
1500 returned to the client in the Modify DN Response.
1502 For example, if the entry named in the "entry" parameter was "cn=John
1503 Smith,c=US", the newrdn parameter was "cn=John Cougar Smith", and the
1504 newSuperior parameter was absent, then this operation would attempt
1505 to rename the entry to be "cn=John Cougar Smith,c=US". If there was
1508 Sermersheim Internet-Draft - Expires Sep 2003 Page 26
\f
1509 Lightweight Directory Access Protocol Version 3
1511 already an entry with that name, the operation would fail with error
1512 code entryAlreadyExists.
1514 If the deleteoldrdn parameter is TRUE, the values forming the old RDN
1515 are deleted from the entry. If the deleteoldrdn parameter is FALSE,
1516 the values forming the old RDN will be retained as non-distinguished
1517 attribute values of the entry. The server may not perform the
1518 operation and return an error code if the setting of the deleteoldrdn
1519 parameter would cause a schema inconsistency in the entry.
1521 Note that X.500 restricts the ModifyDN operation to only affect
1522 entries that are contained within a single server. If the LDAP server
1523 is mapped onto DAP, then this restriction will apply, and the
1524 resultCode affectsMultipleDSAs will be returned if this error
1525 occurred. In general clients MUST NOT expect to be able to perform
1526 arbitrary movements of entries and subtrees between servers.
1529 4.10. Compare Operation
1531 The Compare Operation allows a client to compare an assertion
1532 provided with an entry in the directory. The Compare Request is
1535 CompareRequest ::= [APPLICATION 14] SEQUENCE {
1537 ava AttributeValueAssertion }
1539 Parameters of the Compare Request are:
1541 - entry: the name of the entry to be compared with. Note that the
1542 server SHOULD NOT dereference any aliases in locating the entry to
1545 - ava: the assertion with which an attribute in the entry is to be
1548 The result of the compare attempted by the server upon receipt of a
1549 Compare Request is returned in the Compare Response, defined as
1552 CompareResponse ::= [APPLICATION 15] LDAPResult
1554 Upon receipt of a Compare Request, a server will attempt to perform
1555 the requested comparison using the EQUALITY matching rule for the
1556 attribute type. The result of the comparison will be returned to the
1557 client in the Compare Response. Note that errors and the result of
1558 comparison are all returned in the same construct.
1560 Note that some directory systems may establish access controls which
1561 permit the values of certain attributes (such as userPassword) to be
1562 compared but not interrogated by other means.
1566 Sermersheim Internet-Draft - Expires Sep 2003 Page 27
\f
1567 Lightweight Directory Access Protocol Version 3
1569 4.11. Abandon Operation
1571 The function of the Abandon Operation is to allow a client to request
1572 that the server abandon an outstanding operation. The Abandon Request
1573 is defined as follows:
1575 AbandonRequest ::= [APPLICATION 16] MessageID
1577 The MessageID MUST be that of an operation which was requested
1578 earlier in this connection. The abandon request itself has its own
1579 message id. This is distinct from the id of the earlier operation
1582 There is no response defined in the Abandon Operation. Upon
1583 transmission of an Abandon Operation, the server MAY abandon the
1584 operation identified by the Message ID in the Abandon Request.
1585 Operation responses are not sent for successfully abandoned
1586 operations. Clients can determine that an operation has been
1587 abandoned by performing a subsequent bind operation.
1589 Abandon and Unbind operations cannot be abandoned. The ability to
1590 abandon other (particularly update) operations is at the discretion
1593 In the event that a server receives an Abandon Request on a Search
1594 Operation in the midst of transmitting responses to the search, that
1595 server MUST cease transmitting entry responses to the abandoned
1596 request immediately, and MUST NOT send the SearchResponseDone. Of
1597 course, the server MUST ensure that only properly encoded LDAPMessage
1598 PDUs are transmitted.
1600 Clients MUST NOT send abandon requests for the same operation
1601 multiple times, and MUST also be prepared to receive results from
1602 operations it has abandoned (since these may have been in transit
1603 when the abandon was requested, or are not able to be abandoned).
1605 Servers MUST discard abandon requests for message IDs they do not
1606 recognize, for operations which cannot be abandoned, and for
1607 operations which have already been abandoned.
1610 4.12. Extended Operation
1612 An extension mechanism has been added in this version of LDAP, in
1613 order to allow additional operations to be defined for services not
1614 available elsewhere in this protocol, for instance digitally signed
1615 operations and results.
1617 The extended operation allows clients to make requests and receive
1618 responses with predefined syntaxes and semantics. These may be
1619 defined in RFCs or be private to particular implementations. Each
1620 request MUST have a unique OBJECT IDENTIFIER assigned to it.
1622 ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
1624 Sermersheim Internet-Draft - Expires Sep 2003 Page 28
\f
1625 Lightweight Directory Access Protocol Version 3
1627 requestName [0] LDAPOID,
1628 requestValue [1] OCTET STRING OPTIONAL }
1630 The requestName is a dotted-decimal representation of the OBJECT
1631 IDENTIFIER corresponding to the request. The requestValue is
1632 information in a form defined by that request, encapsulated inside an
1635 The server will respond to this with an LDAPMessage containing the
1638 ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
1639 COMPONENTS OF LDAPResult,
1640 responseName [10] LDAPOID OPTIONAL,
1641 response [11] OCTET STRING OPTIONAL }
1643 If the server does not recognize the request name, it MUST return
1644 only the response fields from LDAPResult, containing the
1645 protocolError result code.
1647 4.13. Start TLS Operation
1649 The Start Transport Layer Security (StartTLS) operation provides the
1650 ability to establish Transport Layer Security [RFC2246] on an LDAP
1653 4.13.1. Start TLS Request
1655 A client requests TLS establishment by transmitting a Start TLS
1656 request PDU to the server. The Start TLS request is defined in terms
1657 of an ExtendedRequest. The requestName is "1.3.6.1.4.1.1466.20037",
1658 and the requestValue field is absent.
1660 The client MUST NOT send any PDUs on this connection following this
1661 request until it receives a Start TLS extended response.
1663 4.13.2. Start TLS Response
1665 When a Start TLS request is made, servers supporting the operation
1666 MUST return a Start TLS response PDU to the requestor. The Start TLS
1667 response responseName is also "1.3.6.1.4.1.1466.20037", and the
1668 response field is absent.
1670 The server MUST set the resultCode field to either success or one of
1671 the other values outlined in section 4.13.2.2.
1673 4.13.2.1. "Success" Response
1675 If the Start TLS Response contains a resultCode of success, this
1676 indicates that the server is willing and able to negotiate TLS. Refer
1677 to section 5.3 of [AuthMeth] for details.
1679 4.13.2.2. Response other than "success"
1681 Sermersheim Internet-Draft - Expires Sep 2003 Page 29
\f
1682 Lightweight Directory Access Protocol Version 3
1685 If the ExtendedResponse contains a resultCode other than success,
1686 this indicates that the server is unwilling or unable to negotiate
1689 If the Start TLS extended request was not successful, the resultCode
1692 operationsError (operations sequencing incorrect; e.g. TLS already
1695 protocolError (TLS not supported or incorrect PDU structure)
1697 referral (this server doesn't do TLS, try this one)
1699 unavailable (e.g. some major problem with TLS, or server is
1702 The server MUST return operationsError if the client violates any of
1703 the Start TLS extended operation sequencing requirements described in
1704 section 5.3 of [AuthMeth].
1706 If the server does not support TLS (whether by design or by current
1707 configuration), it MUST set the resultCode to protocolError, or to
1708 referral. The server MUST include an actual referral value in the
1709 LDAP Result if it returns a resultCode of referral. The client's
1710 current session is unaffected if the server does not support TLS. The
1711 client MAY proceed with any LDAP operation, or it MAY close the
1714 The server MUST return unavailable if it supports TLS but cannot
1715 establish a TLS connection for some reason, e.g. the certificate
1716 server not responding, it cannot contact its TLS implementation, or
1717 if the server is in process of shutting down. The client MAY retry
1718 the StartTLS operation, or it MAY proceed with any other LDAP
1719 operation, or it MAY close the connection.
1721 4.13.3. Closing a TLS Connection
1723 Two forms of TLS connection closure--graceful and abrupt--are
1726 4.13.3.1. Graceful Closure
1728 Either the client or server MAY terminate the TLS connection and
1729 leave the LDAP session intact by sending a TLS closure alert.
1731 Before sending a TLS closure alert, the client MUST either wait for
1732 any outstanding LDAP operations to complete, or explicitly abandon
1735 After the initiator of a close has sent a TLS closure alert, it MUST
1736 discard any TLS messages until it has received a TLS closure alert
1738 Sermersheim Internet-Draft - Expires Sep 2003 Page 30
\f
1739 Lightweight Directory Access Protocol Version 3
1741 from the other party. It will cease to send TLS Record Protocol
1742 PDUs, and following the receipt of the alert, MAY send and receive
1745 The other party, if it receives a TLS closure alert, MUST immediately
1746 transmit a TLS closure alert. It will subsequently cease to send TLS
1747 Record Protocol PDUs, and MAY send and receive LDAP PDUs.
1749 4.13.3.2. Abrupt Closure
1751 Either the client or server MAY abruptly close the TLS connection by
1752 dropping the underlying transfer protocol connection. In this
1753 circumstance, a server MAY send the client a Notice of Disconnection
1754 before dropping the underlying connection.
1757 5. Protocol Element Encodings and Transfer
1759 One underlying service is defined here. Clients and servers SHOULD
1760 implement the mapping of LDAP over TCP described in 5.2.1.
1763 5.1. Protocol Encoding
1765 The protocol elements of LDAP are encoded for exchange using the
1766 Basic Encoding Rules (BER) [X.690] of ASN.1 [X.680]. However, due to
1767 the high overhead involved in using certain elements of the BER, the
1768 following additional restrictions are placed on BER-encodings of LDAP
1771 (1) Only the definite form of length encoding will be used.
1773 (2) OCTET STRING values will be encoded in the primitive form only.
1775 (3) If the value of a BOOLEAN type is true, the encoding MUST have
1776 its contents octets set to hex "FF".
1778 (4) If a value of a type is its default value, it MUST be absent.
1779 Only some BOOLEAN and INTEGER types have default values in this
1780 protocol definition.
1782 These restrictions do not apply to ASN.1 types encapsulated inside of
1783 OCTET STRING values, such as attribute values, unless otherwise
1787 5.2. Transfer Protocols
1789 This protocol is designed to run over connection-oriented, reliable
1790 transports, with all 8 bits in an octet being significant in the data
1795 Sermersheim Internet-Draft - Expires Sep 2003 Page 31
\f
1796 Lightweight Directory Access Protocol Version 3
1798 5.2.1. Transmission Control Protocol (TCP)
1800 The encoded LDAPMessage PDUs are mapped directly onto the TCP
1801 bytestream using the BER-based encoding described in section 5.1. It
1802 is recommended that server implementations running over the TCP
1803 provide a protocol listener on the assigned port, 389. Servers may
1804 instead provide a listener on a different port number. Clients MUST
1805 support contacting servers on any valid TCP port.
1808 6. Implementation Guidelines
1811 6.1. Server Implementations
1813 The server MUST be capable of recognizing all the mandatory attribute
1814 type names and implement the syntaxes specified in [Syntaxes].
1815 Servers MAY also recognize additional attribute type names.
1818 6.2. Client Implementations
1820 Clients that follow referrals or search continuation references MUST
1821 ensure that they do not loop between servers. They MUST NOT
1822 repeatedly contact the same server for the same request with the same
1823 target entry name, scope and filter. Some clients use a counter that
1824 is incremented each time referral handling occurs for an operation,
1825 and these kinds of clients MUST be able to handle a DIT with at least
1826 ten layers of naming contexts between the root and a leaf entry.
1828 In the absence of prior agreements with servers, clients SHOULD NOT
1829 assume that servers support any particular schemas beyond those
1830 referenced in section 6.1. Different schemas can have different
1831 attribute types with the same names. The client can retrieve the
1832 subschema entries referenced by the subschemaSubentry attribute in
1833 the entries held by the server.
1836 7. Security Considerations
1838 When used with a connection-oriented transport, this version of the
1839 protocol provides facilities for simple authentication using a
1840 cleartext password, as well as any SASL mechanism [RFC2222]. SASL
1841 allows for integrity and privacy services to be negotiated.
1843 It is also permitted that the server can return its credentials to
1844 the client, if it chooses to do so.
1846 Use of cleartext password is strongly discouraged where the
1847 underlying transport service cannot guarantee confidentiality and may
1848 result in disclosure of the password to unauthorized parties.
1850 When used with SASL, it should be noted that the name field of the
1851 BindRequest is not protected against modification. Thus if the
1853 Sermersheim Internet-Draft - Expires Sep 2003 Page 32
\f
1854 Lightweight Directory Access Protocol Version 3
1856 distinguished name of the client (an LDAPDN) is agreed through the
1857 negotiation of the credentials, it takes precedence over any value in
1858 the unprotected name field.
1860 Implementations which cache attributes and entries obtained via LDAP
1861 MUST ensure that access controls are maintained if that information
1862 is to be provided to multiple clients, since servers may have access
1863 control policies which prevent the return of entries or attributes in
1864 search results except to particular authenticated clients. For
1865 example, caches could serve result information only to the client
1866 whose request caused it to be in the cache.
1868 Protocol servers may return referrals which redirect protocol clients
1869 to peer servers. It is possible for a rogue application to inject
1870 such referrals into the data stream in an attempt to redirect a
1871 client to a rogue server. Protocol clients are advised to be aware of
1872 this, and possibly reject referrals when confidentiality measures are
1873 in place. Protocol clients are advised to ignore referrals from the
1874 Start TLS operation.
1879 This document is an update to RFC 2251, by Mark Wahl, Tim Howes, and
1880 Steve Kille. Their work along with the input of individuals of the
1881 IETF LDAPEXT, LDUP, LDAPBIS, and other Working Groups is gratefully
1885 9. Normative References
1887 [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts,
1888 Models and Service", 1993.
1890 [Roadmap] K. Zeilenga (editor), "LDAP: Technical Specification Road
1891 Map", draft-ietf-ldapbis-roadmap-xx.txt (a work in
1894 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1895 Requirement Levels", RFC 2119, March 1997.
1897 [X.680] ITU-T Recommendation X.680 (1997) | ISO/IEC 8824-1:1998
1898 Information Technology - Abstract Syntax Notation One
1899 (ASN.1): Specification of basic notation
1901 [X.690] ITU-T Rec. X.690, "Specification of ASN.1 encoding rules:
1902 Basic, Canonical, and Distinguished Encoding Rules", 1994.
1904 [LDAPIANA] K. Zeilenga, "IANA Considerations for LDAP", draft-ietf-
1905 ldapbis-xx.txt (a work in progress).
1907 [ISO10646] Universal Multiple-Octet Coded Character Set (UCS) -
1908 Architecture and Basic Multilingual Plane, ISO/IEC 10646-1
1911 Sermersheim Internet-Draft - Expires Sep 2003 Page 33
\f
1912 Lightweight Directory Access Protocol Version 3
1915 [RFC2279] Yergeau, F., "UTF-8, a transformation format of Unicode
1916 and ISO 10646", RFC 2279, January 1998.
1918 [Models] K. Zeilenga, "LDAP: The Models", draft-ietf-ldapbis-
1919 models-xx.txt (a work in progress).
1921 [LDAPDN] K. Zeilenga (editor), "LDAP: String Representation of
1922 Distinguished Names", draft-ietf-ldapbis-dn-xx.txt, (a
1925 [Syntaxes] K. Dally (editor), "LDAP: Syntaxes", draft-ietf-ldapbis-
1926 syntaxes-xx.txt, (a work in progress).
1928 [X.501] ITU-T Rec. X.501, "The Directory: Models", 1993.
1930 [X.511] ITU-T Rec. X.511, "The Directory: Abstract Service
1933 [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter Uniform
1934 Resource Identifiers (URI): Generic Syntax", RFC 2396,
1937 [AuthMeth] R. Harrison (editor), "LDAP: Authentication Methods",
1938 draft-ietf-ldapbis-authmeth-xx.txt, (a work in progress).
1940 [RFC2222] Meyers, J., "Simple Authentication and Security Layer",
1941 RFC 2222, October 1997.
1944 10. Editor's Address
1948 1800 South Novell Place
1949 Provo, Utah 84606, USA
1969 Sermersheim Internet-Draft - Expires Sep 2003 Page 34
\f
1970 Lightweight Directory Access Protocol Version 3
1972 Appendix A - LDAP Result Codes
1974 This normative appendix details additional considerations regarding
1975 LDAP result codes and provides a brief, general description of each
1976 LDAP result code enumerated in Section 4.1.10.
1978 Additional result codes MAY be defined for use with extensions.
1979 Client implementations SHALL treat any result code which they do not
1980 recognize as an unknown error condition.
1982 A.1 Non-Error Result Codes
1983 These result codes (called "non-error" result codes) do not indicate
1989 saslBindInProgress(14).
1991 The success(0), compareTrue(6), and compare(7) result codes indicate
1992 successful completion (and, hence, are called to as "successful"
1995 The referral(10) and saslBindInProgress(14) indicate the client is
1996 required to take additional action to complete the operation
1999 A.2 Error Result Codes
2001 A.3 Classes and Precedence of Error Result Codes
2003 Result codes that indicate error conditions (and, hence, are called
2004 "error" result codes) fall into 6 classes. The following list
2005 specifies the precedence of error classes to be used when more than
2006 one error is detected [X511]:
2007 1) Name Errors (codes 32 - 34, 36)
2008 - a problem related to a name (DN or RDN),
2009 2) Update Errors (codes 64 - 69, 71)
2010 - a problem related to an update operation,
2011 3) Attribute Errors (codes 16 - 21)
2012 - a problem related to a supplied attribute,
2013 4) Security Errors (codes 8, 13, 48 - 50)
2014 - a security related problem,
2015 5) Service Problem (codes 3, 4, 7, 11, 12, 51 - 54, 80)
2016 - a problem related to the provision of the service, and
2017 6) Protocol Problem (codes 1, 2)
2018 - a problem related to protocol structure or semantics.
2020 If the server detects multiple errors simultaneously, the server
2021 SHOULD report the error with the highest precedence.
2023 Existing LDAP result codes are described as follows:
2027 Sermersheim Internet-Draft - Expires Sep 2003 Page 35
\f
2028 Lightweight Directory Access Protocol Version 3
2031 Indicates successful completion of an operation.
2033 This result code is normally not returned by the compare
2034 operation, see compareFalse (5) and compareTrue (6). It is
2035 possible that a future extension mechanism would allow this
2036 to be returned by a compare operation.
2041 Indicates that the operation is not properly sequenced with
2042 relation to other operations (of same or different type).
2044 For example, this code is returned if the client attempts to
2045 Start TLS [RFC2246] while there are other operations
2046 outstanding or if TLS was already established.
2052 Indicates the server received data which has incorrect
2055 For bind operation only, the code may be resulted to indicate
2056 the server does not support the requested protocol version.
2059 timeLimitExceeded (3)
2061 Indicates that the time limit specified by the client was
2062 exceeded before the operation could be completed.
2065 sizeLimitExceeded (4)
2067 Indicates that the size limit specified by the client was
2068 exceeded before the operation could be completed.
2073 Indicates that the operation successfully completes and the
2074 assertion has evaluated to FALSE.
2076 This result code is normally only returned by the compare
2082 Indicates that the operation successfully completes and the
2083 assertion has evaluated to TRUE.
2085 Sermersheim Internet-Draft - Expires Sep 2003 Page 36
\f
2086 Lightweight Directory Access Protocol Version 3
2089 This result code is normally only returned by the compare
2093 authMethodNotSupported (7)
2095 Indicates that the authentication method or mechanism is not
2099 strongAuthRequired (8)
2101 Except when returned in a Notice of Disconnect (see section
2102 4.4.1), this indicates that the server requires the client to
2103 authentication using a strong(er) mechanism.
2108 Indicates that a referral needs to be chased to complete the
2109 operation (see section 4.1.11).
2112 adminLimitExceeded (11)
2114 Indicates that an administrative limit has been exceeded.
2117 unavailableCriticalExtension (12)
2119 Indicates that server cannot perform a critical extension
2120 (see section 4.1.12).
2123 confidentialityRequired (13)
2125 Indicates that data confidentiality protections are required.
2128 saslBindInProgress (14)
2130 Indicates the server requires the client to send a new bind
2131 request, with the same SASL mechanism, to continue the
2132 authentication process (see section 4.2).
2135 noSuchAttribute (16)
2137 Indicates that the named entry does not contain the specified
2138 attribute or attribute value.
2141 undefinedAttributeType (17)
2143 Sermersheim Internet-Draft - Expires Sep 2003 Page 37
\f
2144 Lightweight Directory Access Protocol Version 3
2147 Indicates that a request field contains an undefined
2151 inappropriateMatching (18)
2153 Indicates that a request cannot be completed due to an
2154 inappropriate matching.
2157 constraintViolation (19)
2159 Indicates that the client supplied an attribute value which
2160 does not conform to constraints placed upon it by the data
2163 For example, this code is returned when the multiple values
2164 are supplied to an attribute which has a SINGLE-VALUE
2168 attributeOrValueExists (20)
2170 Indicates that the client supplied an attribute or value to
2171 be added to an entry already exists.
2174 invalidAttributeSyntax (21)
2176 Indicates that a purported attribute value does not conform
2177 to the syntax of the attribute.
2182 Indicates that the object does not exist in the DIT.
2187 Indicates that an alias problem has occurred. Typically an
2188 alias has been dereferenced which names no object.
2191 invalidDNSyntax (34)
2193 Indicates that a LDAPDN or RelativeLDAPDN field (e.g. search
2194 base, target entry, ModifyDN newrdn, etc.) of a request does
2195 not conform to the required syntax or contains attribute
2196 values which do not conform to the syntax of the attribute's
2201 Sermersheim Internet-Draft - Expires Sep 2003 Page 38
\f
2202 Lightweight Directory Access Protocol Version 3
2204 aliasDereferencingProblem (36)
2206 Indicates that a problem occurred while dereferencing an
2207 alias. Typically an alias was encountered in a situation
2208 where it was not allowed or where access was denied.
2211 inappropriateAuthentication (48)
2213 Indicates the server requires the client which had attempted
2214 to bind anonymously or without supplying credentials to
2215 provide some form of credentials,
2218 invalidCredentials (49)
2220 Indicates the supplied password or SASL credentials are
2224 insufficientAccessRights (50)
2226 Indicates that the client does not have sufficient access
2227 rights to perform the operation.
2232 Indicates that the server is busy.
2237 Indicates that the server is shutting down or a subsystem
2238 necessary to complete the operation is offline.
2241 unwillingToPerform (53)
2243 Indicates that the server is unwilling to perform the
2249 Indicates that the server has detected an internal loop.
2252 namingViolation (64)
2254 Indicates that the entry name violates naming restrictions.
2256 objectClassViolation (65)
2259 Sermersheim Internet-Draft - Expires Sep 2003 Page 39
\f
2260 Lightweight Directory Access Protocol Version 3
2262 Indicates that the entry violates object class restrictions.
2265 notAllowedOnNonLeaf (66)
2267 Indicates that operation is inappropriately acting upon a
2271 notAllowedOnRDN (67)
2273 Indicates that the operation is inappropriately attempting to
2274 remove a value which forms the entry's relative distinguished
2278 entryAlreadyExists (68)
2280 Indicates that the request cannot be added fulfilled as the
2281 entry already exists.
2284 objectClassModsProhibited (69)
2286 Indicates that the attempt to modify the object class(es) of
2287 an entry objectClass attribute is prohibited.
2289 For example, this code is returned when a when a client
2290 attempts to modify the structural object class of an entry.
2293 affectsMultipleDSAs (71)
2295 Indicates that the operation cannot be completed as it
2296 affects multiple servers (DSAs).
2301 Indicates the server has encountered an internal error.
2317 Sermersheim Internet-Draft - Expires Sep 2003 Page 40
\f
2318 Lightweight Directory Access Protocol Version 3
2320 Appendix B - Complete ASN.1 Definition
2322 This appendix is normative.
2324 Lightweight-Directory-Access-Protocol-V3 DEFINITIONS
2326 EXTENSIBILITY IMPLIED ::=
2330 LDAPMessage ::= SEQUENCE {
2331 messageID MessageID,
2333 bindRequest BindRequest,
2334 bindResponse BindResponse,
2335 unbindRequest UnbindRequest,
2336 searchRequest SearchRequest,
2337 searchResEntry SearchResultEntry,
2338 searchResDone SearchResultDone,
2339 searchResRef SearchResultReference,
2340 modifyRequest ModifyRequest,
2341 modifyResponse ModifyResponse,
2342 addRequest AddRequest,
2343 addResponse AddResponse,
2344 delRequest DelRequest,
2345 delResponse DelResponse,
2346 modDNRequest ModifyDNRequest,
2347 modDNResponse ModifyDNResponse,
2348 compareRequest CompareRequest,
2349 compareResponse CompareResponse,
2350 abandonRequest AbandonRequest,
2351 extendedReq ExtendedRequest,
2352 extendedResp ExtendedResponse,
2354 controls [0] Controls OPTIONAL }
2356 MessageID ::= INTEGER (0 .. maxInt)
2358 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
2360 LDAPString ::= OCTET STRING -- UTF-8 encoded,
2361 -- [ISO10646] characters
2363 LDAPOID ::= OCTET STRING -- Constrained to numericoid [Models]
2365 LDAPDN ::= LDAPString
2367 RelativeLDAPDN ::= LDAPString
2369 AttributeDescription ::= LDAPString
2370 -- Constrained to attributedescription
2373 AttributeDescriptionList ::= SEQUENCE OF
2375 Sermersheim Internet-Draft - Expires Sep 2003 Page 41
\f
2376 Lightweight Directory Access Protocol Version 3
2378 AttributeDescription
2380 AttributeValue ::= OCTET STRING
2382 AttributeValueAssertion ::= SEQUENCE {
2383 attributeDesc AttributeDescription,
2384 assertionValue AssertionValue }
2386 AssertionValue ::= OCTET STRING
2388 Attribute ::= SEQUENCE {
2389 type AttributeDescription,
2390 vals SET OF AttributeValue }
2392 MatchingRuleId ::= LDAPString
2394 LDAPResult ::= SEQUENCE {
2395 resultCode ENUMERATED {
2397 operationsError (1),
2399 timeLimitExceeded (3),
2400 sizeLimitExceeded (4),
2403 authMethodNotSupported (7),
2404 strongAuthRequired (8),
2407 adminLimitExceeded (11),
2408 unavailableCriticalExtension (12),
2409 confidentialityRequired (13),
2410 saslBindInProgress (14),
2411 noSuchAttribute (16),
2412 undefinedAttributeType (17),
2413 inappropriateMatching (18),
2414 constraintViolation (19),
2415 attributeOrValueExists (20),
2416 invalidAttributeSyntax (21),
2420 invalidDNSyntax (34),
2421 -- 35 reserved for undefined isLeaf --
2422 aliasDereferencingProblem (36),
2424 inappropriateAuthentication (48),
2425 invalidCredentials (49),
2426 insufficientAccessRights (50),
2429 unwillingToPerform (53),
2433 Sermersheim Internet-Draft - Expires Sep 2003 Page 42
\f
2434 Lightweight Directory Access Protocol Version 3
2436 namingViolation (64),
2437 objectClassViolation (65),
2438 notAllowedOnNonLeaf (66),
2439 notAllowedOnRDN (67),
2440 entryAlreadyExists (68),
2441 objectClassModsProhibited (69),
2442 -- 70 reserved for CLDAP --
2443 affectsMultipleDSAs (71),
2447 -- 81-90 reserved for APIs --
2449 diagnosticMessage LDAPString,
2450 referral [3] Referral OPTIONAL }
2452 Referral ::= SEQUENCE OF LDAPURL
2454 LDAPURL ::= LDAPString -- limited to characters permitted in
2457 Controls ::= SEQUENCE OF Control
2459 Control ::= SEQUENCE {
2460 controlType LDAPOID,
2461 criticality BOOLEAN DEFAULT FALSE,
2462 controlValue OCTET STRING OPTIONAL }
2464 BindRequest ::= [APPLICATION 0] SEQUENCE {
2465 version INTEGER (1 .. 127),
2467 authentication AuthenticationChoice }
2469 AuthenticationChoice ::= CHOICE {
2470 simple [0] OCTET STRING,
2472 sasl [3] SaslCredentials,
2475 SaslCredentials ::= SEQUENCE {
2476 mechanism LDAPString,
2477 credentials OCTET STRING OPTIONAL }
2479 BindResponse ::= [APPLICATION 1] SEQUENCE {
2480 COMPONENTS OF LDAPResult,
2481 serverSaslCreds [7] OCTET STRING OPTIONAL }
2483 UnbindRequest ::= [APPLICATION 2] NULL
2485 SearchRequest ::= [APPLICATION 3] SEQUENCE {
2491 Sermersheim Internet-Draft - Expires Sep 2003 Page 43
\f
2492 Lightweight Directory Access Protocol Version 3
2495 derefAliases ENUMERATED {
2496 neverDerefAliases (0),
2497 derefInSearching (1),
2498 derefFindingBaseObj (2),
2500 sizeLimit INTEGER (0 .. maxInt),
2501 timeLimit INTEGER (0 .. maxInt),
2504 attributes AttributeDescriptionList }
2507 and [0] SET SIZE (1..MAX) OF Filter,
2508 or [1] SET SIZE (1..MAX) OF Filter,
2510 equalityMatch [3] AttributeValueAssertion,
2511 substrings [4] SubstringFilter,
2512 greaterOrEqual [5] AttributeValueAssertion,
2513 lessOrEqual [6] AttributeValueAssertion,
2514 present [7] AttributeDescription,
2515 approxMatch [8] AttributeValueAssertion,
2516 extensibleMatch [9] MatchingRuleAssertion }
2518 SubstringFilter ::= SEQUENCE {
2519 type AttributeDescription,
2520 -- at least one must be present,
2521 -- initial and final can occur at most once
2522 substrings SEQUENCE OF CHOICE {
2523 initial [0] AssertionValue,
2524 any [1] AssertionValue,
2525 final [2] AssertionValue } }
2527 MatchingRuleAssertion ::= SEQUENCE {
2528 matchingRule [1] MatchingRuleId OPTIONAL,
2529 type [2] AttributeDescription OPTIONAL,
2530 matchValue [3] AssertionValue,
2531 dnAttributes [4] BOOLEAN DEFAULT FALSE }
2533 SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
2535 attributes PartialAttributeList }
2537 PartialAttributeList ::= SEQUENCE OF SEQUENCE {
2538 type AttributeDescription,
2539 vals SET OF AttributeValue }
2541 SearchResultReference ::= [APPLICATION 19] SEQUENCE OF LDAPURL
2543 SearchResultDone ::= [APPLICATION 5] LDAPResult
2545 ModifyRequest ::= [APPLICATION 6] SEQUENCE {
2547 modification SEQUENCE OF SEQUENCE {
2549 Sermersheim Internet-Draft - Expires Sep 2003 Page 44
\f
2550 Lightweight Directory Access Protocol Version 3
2552 operation ENUMERATED {
2556 modification AttributeTypeAndValues } }
2558 AttributeTypeAndValues ::= SEQUENCE {
2559 type AttributeDescription,
2560 vals SET OF AttributeValue }
2562 ModifyResponse ::= [APPLICATION 7] LDAPResult
2564 AddRequest ::= [APPLICATION 8] SEQUENCE {
2566 attributes AttributeList }
2568 AttributeList ::= SEQUENCE OF SEQUENCE {
2569 type AttributeDescription,
2570 vals SET OF AttributeValue }
2572 AddResponse ::= [APPLICATION 9] LDAPResult
2574 DelRequest ::= [APPLICATION 10] LDAPDN
2576 DelResponse ::= [APPLICATION 11] LDAPResult
2578 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
2580 newrdn RelativeLDAPDN,
2581 deleteoldrdn BOOLEAN,
2582 newSuperior [0] LDAPDN OPTIONAL }
2584 ModifyDNResponse ::= [APPLICATION 13] LDAPResult
2586 CompareRequest ::= [APPLICATION 14] SEQUENCE {
2588 ava AttributeValueAssertion }
2590 CompareResponse ::= [APPLICATION 15] LDAPResult
2592 AbandonRequest ::= [APPLICATION 16] MessageID
2594 ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
2595 requestName [0] LDAPOID,
2596 requestValue [1] OCTET STRING OPTIONAL }
2598 ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
2599 COMPONENTS OF LDAPResult,
2600 responseName [10] LDAPOID OPTIONAL,
2601 response [11] OCTET STRING OPTIONAL }
2607 Sermersheim Internet-Draft - Expires Sep 2003 Page 45
\f
2608 Lightweight Directory Access Protocol Version 3
2610 Appendix C - Change History
2611 <Note to RFC editor: This section is to be removed prior to RFC
2614 C.1 Changes made to RFC 2251:
2618 - Bibliography References: Changed all bibliography references to
2619 use a long name form for readability.
2620 - Changed occurrences of "unsupportedCriticalExtension"
2621 "unavailableCriticalExtension"
2622 - Fixed a small number of misspellings (mostly dropped letters).
2626 - Removed IESG note.
2630 - Added references to RFCs 1823, 2234, 2829 and 2830.
2633 C.2 Changes made to draft-ietf-ldapbis-protocol-00.txt:
2637 - In the first paragraph, clarified what the contents of an
2638 AttributeValue are. There was confusion regarding whether or not
2639 an AttributeValue that is BER encoded (due to the "binary" option)
2640 is to be wrapped in an extra OCTET STRING.
2641 - To the first paragraph, added wording that doesn't restrict other
2642 transfer encoding specifiers from being used. The previous wording
2643 only allowed for the string encoding and the ;binary encoding.
2644 - To the first paragraph, added a statement restricting multiple
2645 options that specify transfer encoding from being present. This
2646 was never specified in the previous version and was seen as a
2647 potential interoperability problem.
2648 - Added a third paragraph stating that the ;binary option is
2649 currently the only option defined that specifies the transfer
2650 encoding. This is for completeness.
2654 - Generalized the second paragraph to read "If an option specifying
2655 the transfer encoding is present in attributeDesc, the
2656 AssertionValue is encoded as specified by the option...".
2657 Previously, only the ;binary option was mentioned.
2659 C.2.3 Sections 4.2, 4.9, 4.10
2661 - Added alias dereferencing specifications. In the case of modDN,
2662 followed precedent set on other update operations (... alias is
2663 not dereferenced...) In the case of bind and compare stated that
2665 Sermersheim Internet-Draft - Expires Sep 2003 Page 46
\f
2666 Lightweight Directory Access Protocol Version 3
2668 servers SHOULD NOT dereference aliases. Specifications were added
2669 because they were missing from the previous version and caused
2670 interoperability problems. Concessions were made for bind and
2671 compare (neither should have ever allowed alias dereferencing) by
2672 using SHOULD NOT language, due to the behavior of some existing
2675 C.2.4 Sections 4.5 and Appendix A
2677 - Changed SubstringFilter.substrings.initial, any, and all from
2678 LDAPString to AssertionValue. This was causing an incompatibility
2679 with X.500 and confusion among other TS RFCs.
2682 C.3 Changes made to draft-ietf-ldapbis-protocol-01.txt:
2686 - Reworded text surrounding subschemaSubentry to reflect that it is
2687 a single-valued attribute that holds the schema for the root DSE.
2688 Also noted that if the server masters entries that use differing
2689 schema, each entry's subschemaSubentry attribute must be
2690 interrogated. This may change as further fine-tuning is done to
2693 C.3.2 Section 4.1.12
2695 - Specified that the criticality field is only used for requests and
2696 not for unbind or abandon. Noted that it is ignored for all other
2701 - Noted that Server behavior is undefined when the name is a null
2702 value, simple authentication is used, and a password is specified.
2704 C.3.4 Section 4.2.(various)
2706 - Changed "unauthenticated" to "anonymous" and "DN" and "LDAPDN" to
2711 - Changed "there is no authentication or encryption being performed
2712 by a lower layer" to "the underlying transport service cannot
2713 guarantee confidentiality"
2717 - Removed all mention of ExtendedResponse due to lack of
2720 C.4 Changes made to draft-ietf-ldapbis-protocol-02.txt:
2723 Sermersheim Internet-Draft - Expires Sep 2003 Page 47
\f
2724 Lightweight Directory Access Protocol Version 3
2728 - Removed "typically" from "and is typically transferred" in the
2729 first paragraph. We know of no (and can conceive of no) case where
2731 - Added "Section 5.1 specifies how the LDAP protocol is encoded." To
2732 the first paragraph. Added this cross reference for readability.
2733 - Changed "version 3 " to "version 3 or later" in the second
2734 paragraph. This was added to clarify the original intent.
2735 - Changed "protocol version" to "protocol versions" in the third
2736 paragraph. This attribute is multi-valued with the intent of
2737 holding all supported versions, not just one.
2741 - Changed "when transferred in protocol" to "when transferred from
2742 the server to the client" in the first paragraph. This is to
2743 clarify that this behavior only happens when attributes are being
2744 sent from the server.
2746 C.4.3 Section 4.1.10
2748 - Changed "servers will return responses containing fields of type
2749 LDAPResult" to "servers will return responses of LDAPResult or
2750 responses containing the components of LDAPResponse". This
2751 statement was incorrect and at odds with the ASN.1. The fix here
2752 reflects the original intent.
2753 - Dropped '--new' from result codes ASN.1. This simplification in
2754 comments just reduces unneeded verbiage.
2756 C.4.4 Section 4.1.11
2758 - Changed "It contains a reference to another server (or set of
2759 servers)" to "It contains one or more references to one or more
2760 servers or services" in the first paragraph. This reflects the
2761 original intent and clarifies that the URL may point to non-LDAP
2764 C.4.5 Section 4.1.12
2766 - Changed "The server MUST be prepared" to "Implementations MUST be
2767 prepared" in the eighth paragraph to reflect that both client and
2768 server implementations must be able to handle this (as both parse
2773 - Changed "One unsolicited notification is defined" to "One
2774 unsolicited notification (Notice of Disconnection) is defined" in
2775 the third paragraph. For clarity and readability.
2781 Sermersheim Internet-Draft - Expires Sep 2003 Page 48
\f
2782 Lightweight Directory Access Protocol Version 3
2784 - Changed "checking for the existence of the objectClass attribute"
2785 to "checking for the presence of the objectClass attribute" in the
2786 last paragraph. This was done as a measure of consistency (we use
2787 the terms present and presence rather than exists and existence in
2792 - Changed "outstanding search operations to different servers," to
2793 "outstanding search operations" in the fifth paragraph as they may
2794 be to the same server. This is a point of clarification.
2798 - Changed "clients MUST NOT attempt to delete" to "clients MUST NOT
2799 attempt to add or delete" in the second to last paragraph.
2800 - Change "using the "delete" form" to "using the "add" or "delete"
2801 form" in the second to last paragraph.
2805 - Changed "Clients MUST NOT supply the createTimestamp or
2806 creatorsName attributes, since these will be generated
2807 automatically by the server." to "Clients MUST NOT supply NO-USER-
2808 MODIFICATION attributes such as createTimestamp or creatorsName
2809 attributes, since these are provided by the server." in the
2810 definition of the attributes field. This tightens the language to
2811 reflect the original intent and to not leave a hole in which one
2812 could interpret the two attributes mentioned as the only non-
2813 writable attributes.
2817 - Changed "has been" to "will be" in the fourth paragraph. This
2818 clarifies that the server will (not has) abandon the operation.
2821 C.5 Changes made to draft-ietf-ldapbis-protocol-03.txt:
2825 - Changed "An attribute is a type with one or more associated
2826 values. The attribute type is identified by a short descriptive
2827 name and an OID (object identifier). The attribute type governs
2828 whether there can be more than one value of an attribute of that
2829 type in an entry, the syntax to which the values must conform, the
2830 kinds of matching which can be performed on values of that
2831 attribute, and other functions." to " An attribute is a
2832 description (a type and zero or more options) with one or more
2833 associated values. The attribute type governs whether the
2834 attribute can have multiple values, the syntax and matching rules
2835 used to construct and compare values of that attribute, and other
2836 functions. Options indicate modes of transfer and other
2839 Sermersheim Internet-Draft - Expires Sep 2003 Page 49
\f
2840 Lightweight Directory Access Protocol Version 3
2842 functions.". This points out that an attribute consists of both
2843 the type and options.
2847 - Changed "Section 5.1 specifies the encoding rules for the LDAP
2848 protocol" to "Section 5.1 specifies how the protocol is encoded
2853 - Added ABNF for the textual representation of LDAPOID. Previously,
2854 there was no formal BNF for this construct.
2858 - Changed "This identifier may be written as decimal digits with
2859 components separated by periods, e.g. "2.5.4.10"" to "may be
2860 written as defined by ldapOID in section 4.1.2" in the second
2861 paragraph. This was done because we now have a formal BNF
2862 definition of an oid.
2866 - Changed the BNF for AttributeDescription to ABNF. This was done
2867 for readability and consistency (no functional changes involved).
2868 - Changed "Options present in an AttributeDescription are never
2869 mutually exclusive." to "Options MAY be mutually exclusive. An
2870 AttributeDescription with mutually exclusive options is treated as
2871 an undefined attribute type." for clarity. It is generally
2872 understood that this is the original intent, but the wording could
2873 be easily misinterpreted.
2874 - Changed "Any option could be associated with any AttributeType,
2875 although not all combinations may be supported by a server." to
2876 "Though any option or set of options could be associated with any
2877 AttributeType, the server support for certain combinations may be
2878 restricted by attribute type, syntaxes, or other factors.". This
2879 is to clarify the meaning of 'combination' (it applies both to
2880 combination of attribute type and options, and combination of
2881 options). It also gives examples of *why* they might be
2884 C.5.6 Section 4.1.11
2886 - Changed the wording regarding 'equally capable' referrals to "If
2887 multiple URLs are present, the client assumes that any URL may be
2888 used to progress the operation.". The previous language implied
2889 that the server MUST enforce rules that it was practically
2890 incapable of. The new language highlights the original intent--
2891 that is, that any of the referrals may be used to progress the
2892 operation, there is no inherent 'weighting' mechanism.
2894 C.5.7 Section 4.5.1 and Appendix A
2897 Sermersheim Internet-Draft - Expires Sep 2003 Page 50
\f
2898 Lightweight Directory Access Protocol Version 3
2900 - Added the comment "-- initial and final can occur at most once",
2901 to clarify this restriction.
2905 - Changed heading from "Mapping Onto BER-based Transport Services"
2906 to "Protocol Encoding".
2910 - Changed "The LDAPMessage PDUs" to "The encoded LDAPMessage PDUs"
2911 to point out that the PDUs are encoded before being streamed to
2914 C.6 Changes made to draft-ietf-ldapbis-protocol-04.txt:
2916 C.6.1 Section 4.5.1 and Appendix A
2918 - Changed the ASN.1 for the and and or choices of Filter to have a
2919 lower range of 1. This was an omission in the original ASN.1
2923 - Fixed various typo's
2925 C.7 Changes made to draft-ietf-ldapbis-protocol-05.txt:
2929 - Added "(as defined in Section 12.4.1 of [X.501])" to the fifth
2930 paragraph when talking about "operational attributes". This is
2931 because the term "operational attributes" is never defined.
2932 Alternately, we could drag a definition into the spec, for now,
2933 I'm just pointing to the reference in X.501.
2937 - Changed "And is also case insensitive" to "The entire
2938 AttributeDescription is case insensitive". This is to clarify
2939 whether we're talking about the entire attribute description, or
2942 - Expounded on the definition of attribute description options. This
2943 doc now specifies a difference between transfer and tagging
2944 options and describes the semantics of each, and how and when
2945 subtyping rules apply. Now allow options to be transmitted in any
2946 order but disallow any ordering semantics to be implied. These
2947 changes are the result of ongoing input from an engineering team
2948 designed to deal with ambiguity issues surrounding attribute
2951 C.7.3 Sections 4.1.5.1 and 4.1.6
2955 Sermersheim Internet-Draft - Expires Sep 2003 Page 51
\f
2956 Lightweight Directory Access Protocol Version 3
2958 - Refer to non "binary" transfer encodings as "native encoding"
2959 rather than "string" encoding to clarify and avoid confusion.
2961 C.8 Changes made to draft-ietf-ldapbis-protocol-06.txt:
2965 - Changed to "LDAP: The Protocol" to be consisted with other working
2970 - Moved above TOC to conform to new guidelines
2972 - Reworded to make consistent with other WG documents.
2974 - Moved 2119 conventions to "Conventions" section
2978 - Created to conform to new guidelines
2982 - Removed section. There is only one model in this document
2985 C.8.5 Protocol Model
2987 - Removed antiquated paragraph: "In keeping with the goal of easing
2988 the costs associated with use of the directory, it is an objective
2989 of this protocol to minimize the complexity of clients so as to
2990 facilitate widespread deployment of applications capable of using
2993 - Removed antiquated paragraph concerning LDAP v1 and v2 and
2998 - Removed Section 3.2 and subsections. These have been moved to
3001 C.8.7 Relationship to X.500
3003 - Removed section. It has been moved to [Roadmap]
3005 C.8.8 Server Specific Data Requirements
3007 - Removed section. It has been moved to [Models]
3009 C.8.9 Elements of Protocol
3013 Sermersheim Internet-Draft - Expires Sep 2003 Page 52
\f
3014 Lightweight Directory Access Protocol Version 3
3016 - Added "Section 5.1 specifies how the protocol is encoded and
3017 transferred." to the end of the first paragraph for reference.
3019 - Reworded notes about extensibility, and now talk about implied
3020 extensibility and the use of ellipses in the ASN.1
3022 - Removed references to LDAPv2 in third and fourth paragraphs.
3026 - Reworded second paragraph to "The message ID of a request MUST
3027 have a non-zero value different from the values of any other
3028 requests outstanding in the LDAP session of which this message is
3029 a part. The zero value is reserved for the unsolicited
3030 notification message." (Added notes about non-zero and the zero
3035 - Removed ABNF for LDAPOID and added "Although an LDAPOID is encoded
3036 as an OCTET STRING, values are limited to the definition of
3037 numericoid given in Section 1.3 of [Models]."
3039 C.8.12 Distinguished Name and Relative Distinguished Name
3041 - Removed ABNF and referred to [Models] and [LDAPDN] where this is
3044 C.8.13 Attribute Type
3046 - Removed sections. It's now in the [Models] doc.
3048 C.8.14 Attribute Description
3050 - Removed ABNF and aligned section with [Models]
3052 - Moved AttributeDescriptionList here.
3054 C.8.15 Transfer Options
3056 - Added section and consumed much of old options language (while
3057 aligning with [Models]
3059 C.8.16 Binary Transfer Option
3061 - Clarified intent regarding exactly what is to be BER encoded.
3063 - Clarified that clients must not expect ;binary when not asking for
3064 it (;binary, as opposed to ber encoded data).
3069 - Use the term "attribute description" in lieu of "type"
3071 Sermersheim Internet-Draft - Expires Sep 2003 Page 53
\f
3072 Lightweight Directory Access Protocol Version 3
3075 - Clarified the fact that clients cannot rely on any apparent
3076 ordering of attribute values.
3080 - To resultCode, added ellipses "..." to the enumeration to indicate
3081 extensibility. and added a note, pointing to [LDAPIANA]
3083 - Removed error groupings ad refer to Appendix A.
3085 C.8.19 Bind Operation
3087 - Added "Prior to the BindRequest, the implied identity is
3088 anonymous. Refer to [AuthMeth] for the authentication-related
3089 semantics of this operation." to the first paragraph.
3091 - Added ellipses "..." to AuthenticationChoice and added a note
3092 "This type is extensible as defined in Section 3.6 of [LDAPIANA].
3093 Servers that do not support a choice supplied by a client will
3094 return authMethodNotSupported in the result code of the
3097 - Simplified text regarding how the server handles unknown versions.
3098 Removed references to LDAPv2
3100 C.8.20 Sequencing of the Bind Request
3102 - Aligned with [AuthMeth] In particular, paragraphs 4 and 6 were
3103 removed, while a portion of 4 was retained (see C.8.9)
3105 C.8.21 Authentication and other Security Service
3107 - Section was removed. Now in [AuthMeth]
3109 C.8.22 Continuation References in the Search Result
3111 - Added "If the originating search scope was singleLevel, the scope
3112 part of the URL will be baseObject."
3114 C.8.23 Security Considerations
3116 - Removed reference to LDAPv2
3120 - Added as normative appendix A
3124 - Added EXTENSIBILITY IMPLIED
3126 - Added a number of comments holding referenced to [Models] and
3129 Sermersheim Internet-Draft - Expires Sep 2003 Page 54
\f
3130 Lightweight Directory Access Protocol Version 3
3133 - Removed AttributeType. It is not used.
3136 C.9 Changes made to draft-ietf-ldapbis-protocol-07.txt:
3138 - Removed all mention of transfer encodings and the binary attribute
3141 - Further alignment with [Models].
3143 - Added extensibility ellipsis to protocol op choice
3145 - In 4.1.1, clarified when connections may be dropped due to
3148 - Specified which matching rules and syntaxes are used for various
3151 C.10 Changes made to draft-ietf-ldapbis-protocol-08.txt:
3153 C.10.1 Section 4.1.1.1:
3155 - Clarified when it is and isn't appropriate to return an already
3158 C.10.2 Section 4.1.11:
3160 - Clarified that a control only applies to the message it's attached
3163 - Explained that the criticality field is only applicable to certain
3166 - Added language regarding the combination of controls.
3168 C.10.3 Section 4.11:
3170 - Explained that Abandon and Unbind cannot be abandoned, and
3171 illustrated how to determine whether an operation has been
3175 C.11 Changes made to draft-ietf-ldapbis-protocol-09.txt:
3180 C.12 Changes made to draft-ietf-ldapbis-protocol-10.txt:
3182 C.12.1 Section 4.1.4:
3184 - Removed second paragraph as this language exists in MODELS
3187 Sermersheim Internet-Draft - Expires Sep 2003 Page 55
\f
3188 Lightweight Directory Access Protocol Version 3
3190 C.12.2 Section 4.2.1:
3192 - Replaced fourth paragraph. It was accidentally removed in an
3195 C.12.2 Section 4.13:
3197 - Added section describing the StartTLS operation (moved from
3200 C.13 Changes made to draft-ietf-ldapbis-protocol-11.txt:
3202 C.13.1 Section 4.1.9
3204 - Changed "errorMessage" to "diagnosticMessage". Simply to indicate
3205 that the field may be non-empty even if a non-error resultCode is
3210 - Reconciled language in "name" definition with [AuthMeth]
3212 C.13.3 Section 4.2.1
3214 - Renamed to "Processing of the Bind Request", and moved some text
3215 from 4.2 into this section.
3217 - Rearranged paragraphs to flow better.
3219 - Specified that (as well as failed) an abandoned bind operation
3220 will leave the connection in an anonymous state.
3222 C.13.4 Section 4.5.3
3224 - Generalized the second paragraph which cited indexing and
3225 searchreferralreferences.
3227 C.14 Changes made to draft-ietf-ldapbis-protocol-12.txt:
3229 - Reworked bind errors.
3230 - General clarifications and edits
3232 Appendix D - Outstanding Work Items
3235 - Integrate notational consistency agreements WG will discuss
3236 notation consistency. Once agreement happens, reconcile draft.
3238 - Reconcile problems with [Models]. Section 3.2 was wholly removed.
3239 There were some protocol semantics in that section that need to be
3240 brought back. Specifically, there was the notion of the server
3241 implicitly adding objectclass superclasses when a value is added.
3243 D.1 Make result code usage consistent.
3245 Sermersheim Internet-Draft - Expires Sep 2003 Page 56
\f
3246 Lightweight Directory Access Protocol Version 3
3249 - While there is a result code appendix, ensure it speaks of result
3250 codes in a general sense, and only highlight specific result codes
3251 in the context of an operation when that operation ties more
3252 specific meanings to that result code.
3255 D.2 Verify references.
3257 - Many referenced documents have changed. Ensure references and
3258 section numbers are correct.
3260 D.3 Usage of Naming Context
3262 - Make sure occurrences of "namingcontext" and "naming context" are
3263 consistent with [Models]. Use in section 6.2 should be reworked.
3264 It's layers of indirection that matter, not number of contexts.
3265 (That is, referrals can be returned for a number of reasons (cross
3266 reference, superior, subordinate, busy, not master, etc.)
3268 Other uses are fine.
3270 D.4 Review 2119 usage
3273 D.5 Reconcile with I-D Nits
3278 - A server MUST NOT return any SearchResultReference if it has not
3279 located the baseObject and thus has not searched any entries; in
3280 this case it would return a SearchResultDone containing a referral
3283 - Add "Similarly, a server MUST NOT return a SearchResultReference
3284 when the scope of the search is baseObject. If a client receives
3285 such a SearchResultReference it MUST interpret is as a protocol
3286 error and MUST NOT follow it." to the first paragraph.
3287 The technical specification doesn't have to describe how a
3288 protocol peer should react when its partner violates an absolute.
3290 OR return noSuchObject.
3292 - Add "If the scope part of the LDAP URL is present, the client MUST
3293 use the new scope in its next request to progress the search. If
3294 the scope part is absent the client MUST use subtree scope to
3295 complete subtree searches and base scope to complete one level
3296 searches." to the third paragraph.
3302 Sermersheim Internet-Draft - Expires Sep 2003 Page 57
\f
3303 Lightweight Directory Access Protocol Version 3
3305 - Resolve the meaning of "and is ignored if the attribute does not
3306 exist". See "modify: "non-existent attribute"" on the list. Not
3307 sure if there's really an issue here. Will look at archive
3311 - Specify what happens when the attr is missing vs. attr isn't in
3312 schema. Also what happens if there's no equality matching rule.
3313 noSuchAttribute, undefinedAttributeType, inappropriateMatching
3317 - Add "control and extended operation values" to last paragraph. See
3318 "LBER (BER Restrictions)" on list.
3322 - Add "that are used by those attributes" to the first paragraph.
3323 - Add "Servers which support update operations MUST, and other
3324 servers SHOULD, support strong authentication mechanisms described
3325 in [RFC2829]." as a second paragraph. Likely should just say
3326 Requirements of authentication methods, SASL mechanisms, and TLS
3327 are described in [AUTHMETH]." (also apply to next two below)
3328 - Add "Servers which provide access to sensitive information MUST,
3329 and other servers SHOULD support privacy protections such as those
3330 described in [RFC2829] and [RFC2830]." as a third paragraph.
3334 - Add "Servers which support update operations MUST, and other
3335 servers SHOULD, support strong authentication mechanisms described
3336 in [RFC2829]." as a fourth paragraph.
3337 - Add "In order to automatically follow referrals, clients may need
3338 to hold authentication secrets. This poses significant privacy and
3339 security concerns and SHOULD be avoided." as a sixth paragraph.
3340 There are concerns with "automatic" chasing regardless of which,
3341 if any, authentication method/mechanism is used.
3343 - Add notes regarding DoS attack found by CERT advisories.
3347 - C.9. Explain why we removed ;binary, and what clients can do to
3348 get around potential problems (likely refer to an I-D)
3360 Sermersheim Internet-Draft - Expires Sep 2003 Page 58
\f
3361 Lightweight Directory Access Protocol Version 3
3363 Full Copyright Statement
3365 Copyright (C) The Internet Society (2002). All Rights Reserved.
3367 This document and translations of it may be copied and furnished to
3368 others, and derivative works that comment on or otherwise explain it
3369 or assist in its implementation may be prepared, copied, published
3370 and distributed, in whole or in part, without restriction of any
3371 kind, provided that the above copyright notice and this paragraph are
3372 included on all such copies and derivative works. However, this
3373 document itself may not be modified in any way, such as by removing
3374 the copyright notice or references to the Internet Society or other
3375 Internet organizations, except as needed for the purpose of
3376 developing Internet standards in which case the procedures for
3377 copyrights defined in the Internet Standards process must be
3378 followed, or as required to translate it into languages other than
3381 The limited permissions granted above are perpetual and will not be
3382 revoked by the Internet Society or its successors or assigns.
3384 This document and the information contained herein is provided on an
3385 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
3386 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
3387 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
3388 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
3389 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
3418 Sermersheim Internet-Draft - Expires Sep 2003 Page 59
\f
projects / openldap / blob