3 Internet-Draft Editor: J. Sermersheim
\r
4 Intended Category: Standard Track Novell, Inc
\r
5 Document: draft-ietf-ldapbis-protocol-32.txt Oct 2005
\r
6 Obsoletes: RFCs 2251, 2830, 3771
\r
12 Status of this Memo
\r
14 By submitting this Internet-Draft, each
\r
15 author represents that any applicable patent or other IPR claims of
\r
16 which he or she is aware have been or will be disclosed, and any of
\r
17 which he or she becomes aware will be disclosed, in accordance with
\r
18 Section 6 of BCP 79.
\r
20 Internet-Drafts are working documents of the Internet Engineering
\r
21 Task Force (IETF), its areas, and its working groups. Note that other
\r
22 groups may also distribute working documents as Internet-Drafts.
\r
24 Internet-Drafts are draft documents valid for a maximum of six months
\r
25 and may be updated, replaced, or obsoleted by other documents at any
\r
26 time. It is inappropriate to use Internet-Drafts as reference
\r
27 material or to cite them other than as "work in progress".
\r
29 The list of current Internet-Drafts can be accessed at
\r
30 http://www.ietf.org/ietf/1id-abstracts.txt.
\r
32 The list of Internet-Draft Shadow Directories can be accessed at
\r
33 http://www.ietf.org/shadow.html.
\r
35 This Internet-Draft will expire in February 2005.
\r
37 Technical discussion of this document will take place on the IETF
\r
38 LDAP Revision Working Group (LDAPbis) mailing list <ietf-
\r
39 ldapbis@openldap.org>. Please send editorial comments directly to the
\r
40 editor <jimse@novell.com>.
\r
45 This document describes the protocol elements, along with their
\r
46 semantics and encodings, of the Lightweight Directory Access Protocol
\r
47 (LDAP). LDAP provides access to distributed directory services that
\r
48 act in accordance with X.500 data and service models. These protocol
\r
49 elements are based on those described in the X.500 Directory Access
\r
57 Sermersheim Internet-Draft - Expires April 2006 Page 1
\f\r
58 Lightweight Directory Access Protocol Version 3
\r
60 1. Introduction....................................................3
\r
61 1.1. Relationship to Other LDAP Specifications.....................3
\r
62 2. Conventions.....................................................3
\r
63 3. Protocol Model..................................................4
\r
64 3.1 Operation and LDAP Message Layer Relationship..................5
\r
65 4. Elements of Protocol............................................5
\r
66 4.1. Common Elements...............................................5
\r
67 4.1.1. Message Envelope............................................5
\r
68 4.1.2. String Types................................................7
\r
69 4.1.3. Distinguished Name and Relative Distinguished Name..........7
\r
70 4.1.4. Attribute Descriptions......................................8
\r
71 4.1.5. Attribute Value.............................................8
\r
72 4.1.6. Attribute Value Assertion...................................8
\r
73 4.1.7. Attribute and PartialAttribute..............................9
\r
74 4.1.8. Matching Rule Identifier....................................9
\r
75 4.1.9. Result Message..............................................9
\r
76 4.1.10. Referral..................................................11
\r
77 4.1.11. Controls..................................................13
\r
78 4.2. Bind Operation...............................................14
\r
79 4.3. Unbind Operation.............................................17
\r
80 4.4. Unsolicited Notification.....................................17
\r
81 4.5. Search Operation.............................................18
\r
82 4.6. Modify Operation.............................................29
\r
83 4.7. Add Operation................................................31
\r
84 4.8. Delete Operation.............................................31
\r
85 4.9. Modify DN Operation..........................................32
\r
86 4.10. Compare Operation...........................................33
\r
87 4.11. Abandon Operation...........................................34
\r
88 4.12. Extended Operation..........................................35
\r
89 4.13. IntermediateResponse Message................................36
\r
90 4.14. StartTLS Operation..........................................37
\r
91 5. Protocol Encoding, Connection, and Transfer....................39
\r
92 5.1. Protocol Encoding............................................39
\r
93 5.2. Transmission Control Protocol (TCP)..........................40
\r
94 5.3. Termination of the LDAP session..............................40
\r
95 6. Security Considerations........................................40
\r
96 7. Acknowledgements...............................................42
\r
97 8. Normative References...........................................42
\r
98 9. Informative References.........................................44
\r
99 10. IANA Considerations...........................................44
\r
100 11. Editor's Address..............................................45
\r
101 Appendix A - LDAP Result Codes....................................46
\r
102 A.1 Non-Error Result Codes........................................46
\r
103 A.2 Result Codes..................................................46
\r
104 Appendix B - Complete ASN.1 Definition............................51
\r
105 Appendix C - Changes..............................................57
\r
106 C.1 Changes made to RFC 2251:.....................................57
\r
107 C.2 Changes made to RFC 2830:.....................................62
\r
108 C.3 Changes made to RFC 3771:.....................................63
\r
115 Sermersheim Internet-Draft - Expires April 2006 Page 2
\f\r
116 Lightweight Directory Access Protocol Version 3
\r
120 The Directory is "a collection of open systems cooperating to provide
\r
121 directory services" [X.500]. A directory user, which may be a human
\r
122 or other entity, accesses the Directory through a client (or
\r
123 Directory User Agent (DUA)). The client, on behalf of the directory
\r
124 user, interacts with one or more servers (or Directory System Agents
\r
125 (DSA)). Clients interact with servers using a directory access
\r
128 This document details the protocol elements of the Lightweight
\r
129 Directory Access Protocol (LDAP), along with their semantics.
\r
130 Following the description of protocol elements, it describes the way
\r
131 in which the protocol elements are encoded and transferred.
\r
134 1.1. Relationship to Other LDAP Specifications
\r
136 This document is an integral part of the LDAP Technical Specification
\r
137 [Roadmap] which obsoletes the previously defined LDAP technical
\r
138 specification, RFC 3377, in its entirety.
\r
140 This document, together with [Roadmap], [AuthMeth], and [Models],
\r
141 obsoletes RFC 2251 in its entirety. Section 3.3 is obsoleted by
\r
142 [Roadmap]. Sections 4.2.1 (portions), and 4.2.2 are obsoleted by
\r
143 [AuthMeth]. Sections 3.2, 3.4, 4.1.3 (last paragraph), 4.1.4, 4.1.5,
\r
144 4.1.5.1, 4.1.9 (last paragraph), 5.1, 6.1, and 6.2 (last paragraph)
\r
145 are obsoleted by [Models]. The remainder of RFC 2251 is obsoleted by
\r
146 this document. Appendix C.1 summarizes substantive changes in the
\r
149 This document obsoletes RFC 2830, Sections 2 and 4. The remainder of
\r
150 RFC 2830 is obsoleted by [AuthMeth]. Appendix C.2 summarizes
\r
151 substantive changes to the remaining sections.
\r
153 This document also obsoletes RFC 3771 in entirety.
\r
158 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
\r
159 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
\r
160 to be interpreted as described in [Keyword].
\r
162 Character names in this document use the notation for code points and
\r
163 names from the Unicode Standard [Unicode]. For example, the letter
\r
164 "a" may be represented as either <U+0061> or <LATIN SMALL LETTER A>.
\r
166 Note: a glossary of terms used in Unicode can be found in [Glossary].
\r
167 Information on the Unicode character encoding model can be found in
\r
173 Sermersheim Internet-Draft - Expires April 2006 Page 3
\f\r
174 Lightweight Directory Access Protocol Version 3
\r
176 The term "transport connection" refers to the underlying transport
\r
177 services used to carry the protocol exchange, as well as associations
\r
178 established by these services.
\r
180 The term "TLS layer" refers to TLS services used in providing
\r
181 security services, as well as associations established by these
\r
184 The term "SASL layer" refers to SASL services used in providing
\r
185 security services, as well as associations established by these
\r
188 The term "LDAP message layer" refers to the LDAP Message Protocol
\r
189 Data Unit (PDU) services used in providing directory services, as
\r
190 well as associations established by these services.
\r
192 The term "LDAP session" refers to combined services (transport
\r
193 connection, TLS layer, SASL layer, LDAP message layer) and their
\r
196 See the table in Section 5 for an illustration of these four terms.
\r
201 The general model adopted by this protocol is one of clients
\r
202 performing protocol operations against servers. In this model, a
\r
203 client transmits a protocol request describing the operation to be
\r
204 performed to a server. The server is then responsible for performing
\r
205 the necessary operation(s) in the Directory. Upon completion of an
\r
206 operation, the server typically returns a response containing
\r
207 appropriate data to the requesting client.
\r
209 Protocol operations are generally independent of one another. Each
\r
210 operation is processed as an atomic action, leaving the directory in
\r
211 a consistent state.
\r
213 Although servers are required to return responses whenever such
\r
214 responses are defined in the protocol, there is no requirement for
\r
215 synchronous behavior on the part of either clients or servers.
\r
216 Requests and responses for multiple operations generally may be
\r
217 exchanged between a client and server in any order. If required,
\r
218 synchronous behavior may be controlled by client applications.
\r
220 The core protocol operations defined in this document can be mapped
\r
221 to a subset of the X.500 (1993) Directory Abstract Service [X.511].
\r
222 However there is not a one-to-one mapping between LDAP operations and
\r
223 X.500 Directory Access Protocol (DAP) operations. Server
\r
224 implementations acting as a gateway to X.500 directories may need to
\r
225 make multiple DAP requests to service a single LDAP request.
\r
231 Sermersheim Internet-Draft - Expires April 2006 Page 4
\f\r
232 Lightweight Directory Access Protocol Version 3
\r
235 3.1. Operation and LDAP Message Layer Relationship
\r
237 Protocol operations are exchanged at the LDAP message layer. When the
\r
238 transport connection is closed, any uncompleted operations at the
\r
239 LDAP message layer, when possible, are abandoned, and when not
\r
240 possible, are completed without transmission of the response. Also,
\r
241 when the transport connection is closed, the client MUST NOT assume
\r
242 that any uncompleted update operations have succeeded or failed.
\r
245 4. Elements of Protocol
\r
247 The protocol is described using Abstract Syntax Notation One
\r
248 ([ASN.1]), and is transferred using a subset of ASN.1 Basic Encoding
\r
249 Rules ([BER]). Section 5 specifies how the protocol elements are
\r
250 encoded and transferred.
\r
252 In order to support future extensions to this protocol, extensibility
\r
253 is implied where it is allowed per ASN.1 (i.e. sequence, set, choice,
\r
254 and enumerated types are extensible). In addition, ellipses (...)
\r
255 have been supplied in ASN.1 types that are explicitly extensible as
\r
256 discussed in [LDAPIANA]. Because of the implied extensibility,
\r
257 clients and servers MUST (unless otherwise specified) ignore trailing
\r
258 SEQUENCE components whose tags they do not recognize.
\r
260 Changes to the protocol other than through the extension mechanisms
\r
261 described here require a different version number. A client indicates
\r
262 the version it is using as part of the BindRequest, described in
\r
263 Section 4.2. If a client has not sent a Bind, the server MUST assume
\r
264 the client is using version 3 or later.
\r
266 Clients may attempt to determine the protocol versions a server
\r
267 supports by reading the 'supportedLDAPVersion' attribute from the
\r
268 root DSE (DSA-Specific Entry) [Models].
\r
271 4.1. Common Elements
\r
273 This section describes the LDAPMessage envelope Protocol Data Unit
\r
274 (PDU) format, as well as data type definitions, which are used in the
\r
275 protocol operations.
\r
278 4.1.1. Message Envelope
\r
280 For the purposes of protocol exchanges, all protocol operations are
\r
281 encapsulated in a common envelope, the LDAPMessage, which is defined
\r
289 Sermersheim Internet-Draft - Expires April 2006 Page 5
\f\r
290 Lightweight Directory Access Protocol Version 3
\r
292 LDAPMessage ::= SEQUENCE {
\r
293 messageID MessageID,
\r
294 protocolOp CHOICE {
\r
295 bindRequest BindRequest,
\r
296 bindResponse BindResponse,
\r
297 unbindRequest UnbindRequest,
\r
298 searchRequest SearchRequest,
\r
299 searchResEntry SearchResultEntry,
\r
300 searchResDone SearchResultDone,
\r
301 searchResRef SearchResultReference,
\r
302 modifyRequest ModifyRequest,
\r
303 modifyResponse ModifyResponse,
\r
304 addRequest AddRequest,
\r
305 addResponse AddResponse,
\r
306 delRequest DelRequest,
\r
307 delResponse DelResponse,
\r
308 modDNRequest ModifyDNRequest,
\r
309 modDNResponse ModifyDNResponse,
\r
310 compareRequest CompareRequest,
\r
311 compareResponse CompareResponse,
\r
312 abandonRequest AbandonRequest,
\r
313 extendedReq ExtendedRequest,
\r
314 extendedResp ExtendedResponse,
\r
316 intermediateResponse IntermediateResponse },
\r
317 controls [0] Controls OPTIONAL }
\r
319 MessageID ::= INTEGER (0 .. maxInt)
\r
321 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
\r
323 The ASN.1 type Controls is defined in Section 4.1.11.
\r
325 The function of the LDAPMessage is to provide an envelope containing
\r
326 common fields required in all protocol exchanges. At this time the
\r
327 only common fields are the messageID and the controls.
\r
329 If the server receives an LDAPMessage from the client in which the
\r
330 LDAPMessage SEQUENCE tag cannot be recognized, the messageID cannot
\r
331 be parsed, the tag of the protocolOp is not recognized as a request,
\r
332 or the encoding structures or lengths of data fields are found to be
\r
333 incorrect, then the server SHOULD return the Notice of Disconnection
\r
334 described in Section 4.4.1, with the resultCode set to protocolError,
\r
335 and MUST immediately terminate the LDAP session as described in
\r
338 In other cases where the client or server cannot parse an LDAP PDU,
\r
339 it SHOULD abruptly terminate the LDAP session (Section 5.3) where
\r
340 further communication (including providing notice) would be
\r
341 pernicious. Otherwise, server implementations MUST return an
\r
342 appropriate response to the request, with the resultCode set to
\r
347 Sermersheim Internet-Draft - Expires April 2006 Page 6
\f\r
348 Lightweight Directory Access Protocol Version 3
\r
350 4.1.1.1. Message ID
\r
352 All LDAPMessage envelopes encapsulating responses contain the
\r
353 messageID value of the corresponding request LDAPMessage.
\r
355 The message ID of a request MUST have a non-zero value different from
\r
356 the messageID of any other request in progress in the same LDAP
\r
357 session. The zero value is reserved for the unsolicited notification
\r
360 Typical clients increment a counter for each request.
\r
362 A client MUST NOT send a request with the same message ID as an
\r
363 earlier request in the same LDAP session unless it can be determined
\r
364 that the server is no longer servicing the earlier request (e.g.
\r
365 after the final response is received, or a subsequent Bind
\r
366 completes). Otherwise the behavior is undefined. For this purpose,
\r
367 note that Abandon and successfully abandoned operations do not send
\r
371 4.1.2. String Types
\r
373 The LDAPString is a notational convenience to indicate that, although
\r
374 strings of LDAPString type encode as ASN.1 OCTET STRING types, the
\r
375 [ISO10646] character set (a superset of [Unicode]) is used, encoded
\r
376 following the [UTF-8] algorithm. Note that Unicode characters U+0000
\r
377 through U+007F are the same as ASCII 0 through 127, respectively, and
\r
378 have the same single octet UTF-8 encoding. Other Unicode characters
\r
379 have a multiple octet UTF-8 encoding.
\r
381 LDAPString ::= OCTET STRING -- UTF-8 encoded,
\r
382 -- [ISO10646] characters
\r
384 The LDAPOID is a notational convenience to indicate that the
\r
385 permitted value of this string is a (UTF-8 encoded) dotted-decimal
\r
386 representation of an OBJECT IDENTIFIER. Although an LDAPOID is
\r
387 encoded as an OCTET STRING, values are limited to the definition of
\r
388 <numericoid> given in Section 1.4 of [Models].
\r
390 LDAPOID ::= OCTET STRING -- Constrained to <numericoid> [Models]
\r
394 1.3.6.1.4.1.1466.1.2.3
\r
397 4.1.3. Distinguished Name and Relative Distinguished Name
\r
399 An LDAPDN is defined to be the representation of a Distinguished Name
\r
400 (DN) after encoding according to the specification in [LDAPDN].
\r
402 LDAPDN ::= LDAPString
\r
403 -- Constrained to <distinguishedName> [LDAPDN]
\r
405 Sermersheim Internet-Draft - Expires April 2006 Page 7
\f\r
406 Lightweight Directory Access Protocol Version 3
\r
409 A RelativeLDAPDN is defined to be the representation of a Relative
\r
410 Distinguished Name (RDN) after encoding according to the
\r
411 specification in [LDAPDN].
\r
413 RelativeLDAPDN ::= LDAPString
\r
414 -- Constrained to <name-component> [LDAPDN]
\r
417 4.1.4. Attribute Descriptions
\r
419 The definition and encoding rules for attribute descriptions are
\r
420 defined in Section 2.5 of [Models]. Briefly, an attribute description
\r
421 is an attribute type and zero or more options.
\r
423 AttributeDescription ::= LDAPString
\r
424 -- Constrained to <attributedescription>
\r
428 4.1.5. Attribute Value
\r
430 A field of type AttributeValue is an OCTET STRING containing an
\r
431 encoded attribute value. The attribute value is encoded according to
\r
432 the LDAP-specific encoding definition of its corresponding syntax.
\r
433 The LDAP-specific encoding definitions for different syntaxes and
\r
434 attribute types may be found in other documents and in particular
\r
437 AttributeValue ::= OCTET STRING
\r
439 Note that there is no defined limit on the size of this encoding;
\r
440 thus protocol values may include multi-megabyte attribute values
\r
441 (e.g. photographs).
\r
443 Attribute values may be defined which have arbitrary and non-
\r
444 printable syntax. Implementations MUST NOT display nor attempt to
\r
445 decode an attribute value if its syntax is not known. The
\r
446 implementation may attempt to discover the subschema of the source
\r
447 entry, and retrieve the descriptions of 'attributeTypes' from it
\r
450 Clients MUST only send attribute values in a request that are valid
\r
451 according to the syntax defined for the attributes.
\r
454 4.1.6. Attribute Value Assertion
\r
456 The AttributeValueAssertion (AVA) type definition is similar to the
\r
457 one in the X.500 Directory standards. It contains an attribute
\r
458 description and a matching rule ([Models] Section 4.1.3) assertion
\r
459 value suitable for that type. Elements of this type are typically
\r
460 used to assert that the value in assertionValue matches a value of an
\r
463 Sermersheim Internet-Draft - Expires April 2006 Page 8
\f\r
464 Lightweight Directory Access Protocol Version 3
\r
467 AttributeValueAssertion ::= SEQUENCE {
\r
468 attributeDesc AttributeDescription,
\r
469 assertionValue AssertionValue }
\r
471 AssertionValue ::= OCTET STRING
\r
473 The syntax of the AssertionValue depends on the context of the LDAP
\r
474 operation being performed. For example, the syntax of the EQUALITY
\r
475 matching rule for an attribute is used when performing a Compare
\r
476 operation. Often this is the same syntax used for values of the
\r
477 attribute type, but in some cases the assertion syntax differs from
\r
478 the value syntax. See objectIdentiferFirstComponentMatch in
\r
479 [Syntaxes] for an example.
\r
482 4.1.7. Attribute and PartialAttribute
\r
484 Attributes and partial attributes consist of an attribute description
\r
485 and attribute values. A PartialAttribute allows zero values, while
\r
486 Attribute requires at least one value.
\r
488 PartialAttribute ::= SEQUENCE {
\r
489 type AttributeDescription,
\r
490 vals SET OF value AttributeValue }
\r
492 Attribute ::= PartialAttribute(WITH COMPONENTS {
\r
494 vals (SIZE(1..MAX))})
\r
496 No two of the attribute values may be equivalent as described by
\r
497 Section 2.3 of [Models]. The set of attribute values is unordered.
\r
498 Implementations MUST NOT rely upon the ordering being repeatable.
\r
501 4.1.8. Matching Rule Identifier
\r
503 Matching rules are defined in Section 4.1.3 of [Models]. A matching
\r
504 rule is identified in the protocol by the printable representation of
\r
505 either its <numericoid>, or one of its short name descriptors
\r
506 [Models], e.g. 'caseIgnoreMatch' or '2.5.13.2'.
\r
508 MatchingRuleId ::= LDAPString
\r
511 4.1.9. Result Message
\r
513 The LDAPResult is the construct used in this protocol to return
\r
514 success or failure indications from servers to clients. To various
\r
515 requests, servers will return responses containing the elements found
\r
516 in LDAPResult to indicate the final status of the protocol operation
\r
521 Sermersheim Internet-Draft - Expires April 2006 Page 9
\f\r
522 Lightweight Directory Access Protocol Version 3
\r
524 LDAPResult ::= SEQUENCE {
\r
525 resultCode ENUMERATED {
\r
527 operationsError (1),
\r
528 protocolError (2),
\r
529 timeLimitExceeded (3),
\r
530 sizeLimitExceeded (4),
\r
533 authMethodNotSupported (7),
\r
534 strongerAuthRequired (8),
\r
537 adminLimitExceeded (11),
\r
538 unavailableCriticalExtension (12),
\r
539 confidentialityRequired (13),
\r
540 saslBindInProgress (14),
\r
541 noSuchAttribute (16),
\r
542 undefinedAttributeType (17),
\r
543 inappropriateMatching (18),
\r
544 constraintViolation (19),
\r
545 attributeOrValueExists (20),
\r
546 invalidAttributeSyntax (21),
\r
547 -- 22-31 unused --
\r
548 noSuchObject (32),
\r
549 aliasProblem (33),
\r
550 invalidDNSyntax (34),
\r
551 -- 35 reserved for undefined isLeaf --
\r
552 aliasDereferencingProblem (36),
\r
553 -- 37-47 unused --
\r
554 inappropriateAuthentication (48),
\r
555 invalidCredentials (49),
\r
556 insufficientAccessRights (50),
\r
559 unwillingToPerform (53),
\r
561 -- 55-63 unused --
\r
562 namingViolation (64),
\r
563 objectClassViolation (65),
\r
564 notAllowedOnNonLeaf (66),
\r
565 notAllowedOnRDN (67),
\r
566 entryAlreadyExists (68),
\r
567 objectClassModsProhibited (69),
\r
568 -- 70 reserved for CLDAP --
\r
569 affectsMultipleDSAs (71),
\r
570 -- 72-79 unused --
\r
574 diagnosticMessage LDAPString,
\r
575 referral [3] Referral OPTIONAL }
\r
579 Sermersheim Internet-Draft - Expires April 2006 Page 10
\f\r
580 Lightweight Directory Access Protocol Version 3
\r
582 The resultCode enumeration is extensible as defined in Section 3.6 of
\r
583 [LDAPIANA]. The meanings of the listed result codes are given in
\r
584 Appendix A. If a server detects multiple errors for an operation,
\r
585 only one result code is returned. The server should return the result
\r
586 code that best indicates the nature of the error encountered. Servers
\r
587 may return substituted result codes to prevent unauthorized
\r
590 The diagnosticMessage field of this construct may, at the server's
\r
591 option, be used to return a string containing a textual, human-
\r
592 readable (terminal control and page formatting characters should be
\r
593 avoided) diagnostic message. As this diagnostic message is not
\r
594 standardized, implementations MUST NOT rely on the values returned.
\r
595 Diagnostic messages typically supplement the resultCode with
\r
596 additional information. If the server chooses not to return a textual
\r
597 diagnostic, the diagnosticMessage field MUST be empty.
\r
599 For certain result codes (typically, but not restricted to
\r
600 noSuchObject, aliasProblem, invalidDNSyntax and
\r
601 aliasDereferencingProblem), the matchedDN field is set (subject to
\r
602 access controls) to the name of the last entry (object or alias) used
\r
603 in finding the target (or base) object. This will be a truncated form
\r
604 of the provided name or, if an alias was dereferenced while
\r
605 attempting to locate the entry, of the resulting name. Otherwise the
\r
606 matchedDN field is empty.
\r
611 The referral result code indicates that the contacted server cannot
\r
612 or will not perform the operation and that one or more other servers
\r
613 may be able to. Reasons for this include:
\r
615 - The target entry of the request is not held locally, but the
\r
616 server has knowledge of its possible existence elsewhere.
\r
618 - The operation is restricted on this server -- perhaps due to a
\r
619 read-only copy of an entry to be modified.
\r
621 The referral field is present in an LDAPResult if the resultCode is
\r
622 set to referral, and absent with all other result codes. It contains
\r
623 one or more references to one or more servers or services that may be
\r
624 accessed via LDAP or other protocols. Referrals can be returned in
\r
625 response to any operation request (except Unbind and Abandon which do
\r
626 not have responses). At least one URI MUST be present in the
\r
629 During a Search operation, after the baseObject is located, and
\r
630 entries are being evaluated, the referral is not returned. Instead,
\r
631 continuation references, described in Section 4.5.3, are returned
\r
632 when other servers would need to be contacted to complete the
\r
635 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI
\r
637 Sermersheim Internet-Draft - Expires April 2006 Page 11
\f\r
638 Lightweight Directory Access Protocol Version 3
\r
641 URI ::= LDAPString -- limited to characters permitted in
\r
644 If the client wishes to progress the operation, it contacts one of
\r
645 the supported services found in the referral. If multiple URIs are
\r
646 present, the client assumes that any supported URI may be used to
\r
647 progress the operation.
\r
649 Clients that follow referrals MUST ensure that they do not loop
\r
650 between servers. They MUST NOT repeatedly contact the same server for
\r
651 the same request with the same parameters. Some clients use a counter
\r
652 that is incremented each time referral handling occurs for an
\r
653 operation, and these kinds of clients MUST be able to handle at least
\r
654 ten nested referrals while progressing the operation.
\r
656 A URI for a server implementing LDAP and accessible via [TCP]/[IP]
\r
657 (v4 or v6) is written as an LDAP URL according to [LDAPURL].
\r
659 Referral values which are LDAP URLs follow these rules:
\r
661 - If an alias was dereferenced, the <dn> part of the LDAP URL MUST
\r
662 be present, with the new target object name.
\r
664 - It is RECOMMENDED that the <dn> part be present to avoid
\r
667 - If the <dn> part is present, the client uses this name in its next
\r
668 request to progress the operation, and if it is not present the
\r
669 client uses the same name as in the original request.
\r
671 - Some servers (e.g. participating in distributed indexing) may
\r
672 provide a different filter in a URL of a referral for a Search
\r
675 - If the <filter> part of the LDAP URL is present, the client uses
\r
676 this filter in its next request to progress this Search, and if it
\r
677 is not present the client uses the same filter as it used for that
\r
680 - For Search, it is RECOMMENDED that the <scope> part be present to
\r
683 - If the <scope> part is missing, the scope of the original Search
\r
684 is used by the client to progress the operation.
\r
686 - Other aspects of the new request may be the same as or different
\r
687 from the request which generated the referral.
\r
689 Other kinds of URIs may be returned. The syntax and semantics of such
\r
690 URIs is left to future specifications. Clients may ignore URIs that
\r
691 they do not support.
\r
695 Sermersheim Internet-Draft - Expires April 2006 Page 12
\f\r
696 Lightweight Directory Access Protocol Version 3
\r
698 UTF-8 encoded characters appearing in the string representation of a
\r
699 DN, search filter, or other fields of the referral value may not be
\r
700 legal for URIs (e.g. spaces) and MUST be escaped using the % method
\r
706 Controls provide a mechanism whereby the semantics and arguments of
\r
707 existing LDAP operations may be extended. One or more controls may be
\r
708 attached to a single LDAP message. A control only affects the
\r
709 semantics of the message it is attached to.
\r
711 Controls sent by clients are termed 'request controls' and those sent
\r
712 by servers are termed 'response controls'.
\r
714 Controls ::= SEQUENCE OF control Control
\r
716 Control ::= SEQUENCE {
\r
717 controlType LDAPOID,
\r
718 criticality BOOLEAN DEFAULT FALSE,
\r
719 controlValue OCTET STRING OPTIONAL }
\r
721 The controlType field is the dotted-decimal representation of an
\r
722 OBJECT IDENTIFIER which uniquely identifies the control. This
\r
723 provides unambiguous naming of controls. Often, response control(s)
\r
724 solicited by a request control share controlType values with the
\r
727 The criticality field only has meaning in controls attached to
\r
728 request messages (except UnbindRequest). For controls attached to
\r
729 response messages and the UnbindRequest, the criticality field SHOULD
\r
730 be FALSE, and MUST be ignored by the receiving protocol peer. A value
\r
731 of TRUE indicates that it is unacceptable to perform the operation
\r
732 without applying the semantics of the control. Specifically, the
\r
733 criticality field is applied as follows:
\r
735 - If the server does not recognize the control type, determines that
\r
736 it is not appropriate for the operation, or is otherwise unwilling
\r
737 to perform the operation with the control, and the criticality
\r
738 field is TRUE, the server MUST NOT perform the operation, and for
\r
739 operations that have a response message, MUST return with the
\r
740 resultCode set to unavailableCriticalExtension.
\r
742 - If the server does not recognize the control type, determines that
\r
743 it is not appropriate for the operation, or is otherwise unwilling
\r
744 to perform the operation with the control, and the criticality
\r
745 field is FALSE, the server MUST ignore the control.
\r
747 - Regardless of criticality, if a control is applied to an
\r
748 operation, it is applied consistently and impartially to the
\r
753 Sermersheim Internet-Draft - Expires April 2006 Page 13
\f\r
754 Lightweight Directory Access Protocol Version 3
\r
756 The controlValue may contain information associated with the
\r
757 controlType. Its format is defined by the specification of the
\r
758 control. Implementations MUST be prepared to handle arbitrary
\r
759 contents of the controlValue octet string, including zero bytes. It
\r
760 is absent only if there is no value information which is associated
\r
761 with a control of its type. When a controlValue is defined in terms
\r
762 of ASN.1, and BER encoded according to Section 5.1, it also follows
\r
763 the extensibility rules in Section 4.
\r
765 Servers list the controlType of request controls they recognize in
\r
766 the 'supportedControl' attribute in the root DSE (Section 5.1 of
\r
769 Controls SHOULD NOT be combined unless the semantics of the
\r
770 combination has been specified. The semantics of control
\r
771 combinations, if specified, are generally found in the control
\r
772 specification most recently published. When a combination of controls
\r
773 is encountered whose semantics are invalid, not specified (or not
\r
774 known), the message is considered to be not well-formed, thus the
\r
775 operation fails with protocolError. Controls with a criticality of
\r
776 FALSE may be ignored in order to arrive at a valid combination.
\r
777 Additionally, unless order-dependent semantics are given in a
\r
778 specification, the order of a combination of controls in the SEQUENCE
\r
779 is ignored. Where the order is to be ignored but cannot be ignored by
\r
780 the server, the message is considered not well-formed and the
\r
781 operation fails with protocolError. Again, controls with a
\r
782 criticality of FALSE may be ignored in order to arrive at a valid
\r
785 This document does not specify any controls. Controls may be
\r
786 specified in other documents. Documents detailing control extensions
\r
787 are to provide for each control:
\r
789 - the OBJECT IDENTIFIER assigned to the control,
\r
791 - direction as to what value the sender should provide for the
\r
792 criticality field (note: the semantics of the criticality field
\r
793 are defined above should not be altered by the control's
\r
796 - whether the controlValue field is present, and if so, the format
\r
799 - the semantics of the control, and
\r
801 - optionally, semantics regarding the combination of the control
\r
802 with other controls.
\r
805 4.2. Bind Operation
\r
811 Sermersheim Internet-Draft - Expires April 2006 Page 14
\f\r
812 Lightweight Directory Access Protocol Version 3
\r
814 The function of the Bind operation is to allow authentication
\r
815 information to be exchanged between the client and server. The Bind
\r
816 operation should be thought of as the "authenticate" operation.
\r
817 Operational, authentication, and security-related semantics of this
\r
818 operation are given in [AuthMeth].
\r
820 The Bind request is defined as follows:
\r
822 BindRequest ::= [APPLICATION 0] SEQUENCE {
\r
823 version INTEGER (1 .. 127),
\r
825 authentication AuthenticationChoice }
\r
827 AuthenticationChoice ::= CHOICE {
\r
828 simple [0] OCTET STRING,
\r
829 -- 1 and 2 reserved
\r
830 sasl [3] SaslCredentials,
\r
833 SaslCredentials ::= SEQUENCE {
\r
834 mechanism LDAPString,
\r
835 credentials OCTET STRING OPTIONAL }
\r
837 Fields of the BindRequest are:
\r
839 - version: A version number indicating the version of the protocol
\r
840 to be used at the LDAP message layer. This document describes
\r
841 version 3 of the protocol. There is no version negotiation. The
\r
842 client sets this field to the version it desires. If the server
\r
843 does not support the specified version, it MUST respond with a
\r
844 BindResponse where the resultCode is set to protocolError.
\r
846 - name: If not empty, the name of the Directory object that the
\r
847 client wishes to bind as. This field may take on a null value (a
\r
848 zero length string) for the purposes of anonymous binds
\r
849 ([AuthMeth] Section 5.1) or when using Simple Authentication and
\r
850 Security Layer [SASL] authentication ([AuthMeth] Section 5.2).
\r
851 Where the server attempts to locate the named object, it SHALL NOT
\r
852 perform alias dereferencing.
\r
854 - authentication: information used in authentication. This type is
\r
855 extensible as defined in Section 3.7 of [LDAPIANA]. Servers that
\r
856 do not support a choice supplied by a client return a BindResponse
\r
857 with the resultCode set to authMethodNotSupported.
\r
859 Textual passwords (consisting of a character sequence with a known
\r
860 character set and encoding) transferred to the server using the
\r
861 simple AuthenticationChoice SHALL be transferred as [UTF-8]
\r
862 encoded [Unicode]. Prior to transfer, clients SHOULD prepare text
\r
863 passwords as "query" strings by applying the [SASLprep] profile of
\r
864 the [Stringprep] algorithm. Passwords consisting of other data
\r
865 (such as random octets) MUST NOT be altered. The determination of
\r
866 whether a password is textual is a local client matter.
\r
869 Sermersheim Internet-Draft - Expires April 2006 Page 15
\f\r
870 Lightweight Directory Access Protocol Version 3
\r
873 4.2.1. Processing of the Bind Request
\r
875 Before processing a BindRequest, all uncompleted operations MUST
\r
876 either complete or be abandoned. The server may either wait for the
\r
877 uncompleted operations to complete, or abandon them. The server then
\r
878 proceeds to authenticate the client in either a single-step, or
\r
879 multi-step Bind process. Each step requires the server to return a
\r
880 BindResponse to indicate the status of authentication.
\r
882 After sending a BindRequest, clients MUST NOT send further LDAP PDUs
\r
883 until receiving the BindResponse. Similarly, servers SHOULD NOT
\r
884 process or respond to requests received while processing a
\r
887 If the client did not bind before sending a request and receives an
\r
888 operationsError to that request, it may then send a BindRequest. If
\r
889 this also fails or the client chooses not to bind on the existing
\r
890 LDAP session, it may terminate the LDAP session, re-establish it and
\r
891 begin again by first sending a BindRequest. This will aid in
\r
892 interoperating with servers implementing other versions of LDAP.
\r
894 Clients may send multiple Bind requests to change the authentication
\r
895 and/or security associations or to complete a multi-stage Bind
\r
896 process. Authentication from earlier binds is subsequently ignored.
\r
898 For some SASL authentication mechanisms, it may be necessary for the
\r
899 client to invoke the BindRequest multiple times ([AuthMeth] Section
\r
900 5.2). Clients MUST NOT invoke operations between two Bind requests
\r
901 made as part of a multi-stage Bind.
\r
903 A client may abort a SASL bind negotiation by sending a BindRequest
\r
904 with a different value in the mechanism field of SaslCredentials, or
\r
905 an AuthenticationChoice other than sasl.
\r
907 If the client sends a BindRequest with the sasl mechanism field as an
\r
908 empty string, the server MUST return a BindResponse with the
\r
909 resultCode set to authMethodNotSupported. This will allow clients to
\r
910 abort a negotiation if it wishes to try again with the same SASL
\r
914 4.2.2. Bind Response
\r
916 The Bind response is defined as follows.
\r
918 BindResponse ::= [APPLICATION 1] SEQUENCE {
\r
919 COMPONENTS OF LDAPResult,
\r
920 serverSaslCreds [7] OCTET STRING OPTIONAL }
\r
922 BindResponse consists simply of an indication from the server of the
\r
923 status of the client's request for authentication.
\r
927 Sermersheim Internet-Draft - Expires April 2006 Page 16
\f\r
928 Lightweight Directory Access Protocol Version 3
\r
930 A successful Bind operation is indicated by a BindResponse with a
\r
931 resultCode set to success. Otherwise, an appropriate result code is
\r
932 set in the BindResponse. For BindResponse, the protocolError result
\r
933 code may be used to indicate that the version number supplied by the
\r
934 client is unsupported.
\r
936 If the client receives a BindResponse where the resultCode is set to
\r
937 protocolError, it is to assume that the server does not support this
\r
938 version of LDAP. While the client may be able proceed with another
\r
939 version of this protocol (this may or may not require closing and re-
\r
940 establishing the transport connection), how to proceed with another
\r
941 version of this protocol is beyond the scope of this document.
\r
942 Clients which are unable or unwilling to proceed SHOULD terminate the
\r
945 The serverSaslCreds field is used as part of a SASL-defined bind
\r
946 mechanism to allow the client to authenticate the server to which it
\r
947 is communicating, or to perform "challenge-response" authentication.
\r
948 If the client bound with the simple choice, or the SASL mechanism
\r
949 does not require the server to return information to the client, then
\r
950 this field SHALL NOT be included in the BindResponse.
\r
953 4.3. Unbind Operation
\r
955 The function of the Unbind operation is to terminate an LDAP session.
\r
956 The Unbind operation is not the antithesis of the Bind operation as
\r
957 the name implies. The naming of these operations are historical. The
\r
958 Unbind operation should be thought of as the "quit" operation.
\r
960 The Unbind operation is defined as follows:
\r
962 UnbindRequest ::= [APPLICATION 2] NULL
\r
964 The client, upon transmission of the UnbindRequest, and the server,
\r
965 upon receipt of the UnbindRequest are to gracefully terminate the
\r
966 LDAP session as described in Section 5.3.
\r
968 Uncompleted operations are handled as specified in Section 3.1.
\r
971 4.4. Unsolicited Notification
\r
973 An unsolicited notification is an LDAPMessage sent from the server to
\r
974 the client which is not in response to any LDAPMessage received by
\r
975 the server. It is used to signal an extraordinary condition in the
\r
976 server or in the LDAP session between the client and the server. The
\r
977 notification is of an advisory nature, and the server will not expect
\r
978 any response to be returned from the client.
\r
985 Sermersheim Internet-Draft - Expires April 2006 Page 17
\f\r
986 Lightweight Directory Access Protocol Version 3
\r
988 The unsolicited notification is structured as an LDAPMessage in which
\r
989 the messageID is zero and protocolOp is set to the extendedResp
\r
990 choice using the ExtendedResponse type (See Section 4.12). The
\r
991 responseName field of the ExtendedResponse always contains an LDAPOID
\r
992 which is unique for this notification.
\r
994 One unsolicited notification (Notice of Disconnection) is defined in
\r
995 this document. The specification of an unsolicited notification
\r
998 - the OBJECT IDENTIFIER assigned to the notification (to be
\r
999 specified in the responseName,
\r
1001 - the format of the contents of the responseValue (if any),
\r
1003 - the circumstances which will cause the notification to be sent,
\r
1006 - the semantics of the message.
\r
1009 4.4.1. Notice of Disconnection
\r
1011 This notification may be used by the server to advise the client that
\r
1012 the server is about to terminate the LDAP session on its own
\r
1013 initiative. This notification is intended to assist clients in
\r
1014 distinguishing between an exceptional server condition and a
\r
1015 transient network failure. Note that this notification is not a
\r
1016 response to an Unbind requested by the client. Uncompleted operations
\r
1017 are handled as specified in Section 3.1.
\r
1019 The responseName is 1.3.6.1.4.1.1466.20036, the responseValue field
\r
1020 is absent, and the resultCode is used to indicate the reason for the
\r
1021 disconnection. When the strongerAuthRequired resultCode is returned
\r
1022 with this message, it indicates that the server has detected that an
\r
1023 established security association between the client and server has
\r
1024 unexpectedly failed or been compromised.
\r
1026 Upon transmission of the Notice of Disconnection, the server
\r
1027 gracefully terminates the LDAP session as described in Section 5.3.
\r
1030 4.5. Search Operation
\r
1032 The Search operation is used to request a server to return, subject
\r
1033 to access controls and other restrictions, a set of entries matching
\r
1034 a complex search criterion. This can be used to read attributes from
\r
1035 a single entry, from entries immediately subordinate to a particular
\r
1036 entry, or a whole subtree of entries.
\r
1039 4.5.1. Search Request
\r
1041 The Search request is defined as follows:
\r
1043 Sermersheim Internet-Draft - Expires April 2006 Page 18
\f\r
1044 Lightweight Directory Access Protocol Version 3
\r
1047 SearchRequest ::= [APPLICATION 3] SEQUENCE {
\r
1048 baseObject LDAPDN,
\r
1049 scope ENUMERATED {
\r
1052 wholeSubtree (2),
\r
1054 derefAliases ENUMERATED {
\r
1055 neverDerefAliases (0),
\r
1056 derefInSearching (1),
\r
1057 derefFindingBaseObj (2),
\r
1058 derefAlways (3) },
\r
1059 sizeLimit INTEGER (0 .. maxInt),
\r
1060 timeLimit INTEGER (0 .. maxInt),
\r
1061 typesOnly BOOLEAN,
\r
1063 attributes AttributeSelection }
\r
1065 AttributeSelection ::= SEQUENCE OF selector LDAPString
\r
1066 -- The LDAPString is constrained to
\r
1067 -- <attributeSelector> in Section 4.5.1.7
\r
1069 Filter ::= CHOICE {
\r
1070 and [0] SET SIZE (1..MAX) OF filter Filter,
\r
1071 or [1] SET SIZE (1..MAX) OF filter Filter,
\r
1073 equalityMatch [3] AttributeValueAssertion,
\r
1074 substrings [4] SubstringFilter,
\r
1075 greaterOrEqual [5] AttributeValueAssertion,
\r
1076 lessOrEqual [6] AttributeValueAssertion,
\r
1077 present [7] AttributeDescription,
\r
1078 approxMatch [8] AttributeValueAssertion,
\r
1079 extensibleMatch [9] MatchingRuleAssertion,
\r
1082 SubstringFilter ::= SEQUENCE {
\r
1083 type AttributeDescription,
\r
1084 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE {
\r
1085 initial [0] AssertionValue, -- can occur at most once
\r
1086 any [1] AssertionValue,
\r
1087 final [2] AssertionValue } -- can occur at most once
\r
1090 MatchingRuleAssertion ::= SEQUENCE {
\r
1091 matchingRule [1] MatchingRuleId OPTIONAL,
\r
1092 type [2] AttributeDescription OPTIONAL,
\r
1093 matchValue [3] AssertionValue,
\r
1094 dnAttributes [4] BOOLEAN DEFAULT FALSE }
\r
1101 Sermersheim Internet-Draft - Expires April 2006 Page 19
\f\r
1102 Lightweight Directory Access Protocol Version 3
\r
1104 Note that an X.500 "list"-like operation can be emulated by the
\r
1105 client requesting a singleLevel Search operation with a filter
\r
1106 checking for the presence of the 'objectClass' attribute, and that an
\r
1107 X.500 "read"-like operation can be emulated by a baseObject Search
\r
1108 operation with the same filter. A server which provides a gateway to
\r
1109 X.500 is not required to use the Read or List operations, although it
\r
1110 may choose to do so, and if it does, it must provide the same
\r
1111 semantics as the X.500 Search operation.
\r
1114 4.5.1.1. SearchRequest.baseObject
\r
1116 The name of the base object entry (or possibly the root) relative to
\r
1117 which the Search is to be performed.
\r
1120 4.5.1.2. SearchRequest.scope
\r
1122 Specifies the scope of the Search to be performed. The semantics (as
\r
1123 described in [X.511]) of the defined values of this field are:
\r
1125 baseObject: The scope is constrained to the entry named by
\r
1128 singleLevel: The scope is constrained to the immediate
\r
1129 subordinates of the entry named by baseObject.
\r
1131 wholeSubtree: the scope is constrained to the entry named by the
\r
1132 baseObject, and all its subordinates.
\r
1135 4.5.1.3. SearchRequest.derefAliases
\r
1137 An indicator as to whether or not alias entries (as defined in
\r
1138 [Models]) are to be dereferenced during stages of the Search
\r
1141 The act of dereferencing an alias includes recursively dereferencing
\r
1142 aliases which refer to aliases.
\r
1144 Servers MUST detect looping while dereferencing aliases in order to
\r
1145 prevent denial of service attacks of this nature.
\r
1147 The semantics of the defined values of this field are:
\r
1149 neverDerefAliases: Do not dereference aliases in searching or in
\r
1150 locating the base object of the Search.
\r
1159 Sermersheim Internet-Draft - Expires April 2006 Page 20
\f\r
1160 Lightweight Directory Access Protocol Version 3
\r
1162 derefInSearching: While searching subordinates of the base object,
\r
1163 dereference any alias within the search scope. Dereferenced
\r
1164 objects become the vertices of further search scopes where the
\r
1165 Search operation is also applied. If the search scope is
\r
1166 wholeSubtree, the Search continues in the subtree(s) of any
\r
1167 dereferenced object. If the search scope is singleLevel, the
\r
1168 search is applied to any dereferenced objects, and is not applied
\r
1169 to their subordinates. Servers SHOULD eliminate duplicate entries
\r
1170 that arise due to alias dereferencing while searching.
\r
1172 derefFindingBaseObj: Dereference aliases in locating the base
\r
1173 object of the Search, but not when searching subordinates of the
\r
1176 derefAlways: Dereference aliases both in searching and in locating
\r
1177 the base object of the Search.
\r
1180 4.5.1.4. SearchRequest.sizeLimit
\r
1182 A size limit that restricts the maximum number of entries to be
\r
1183 returned as a result of the Search. A value of zero in this field
\r
1184 indicates that no client-requested size limit restrictions are in
\r
1185 effect for the Search. Servers may also enforce a maximum number of
\r
1186 entries to return.
\r
1189 4.5.1.5. SearchRequest.timeLimit
\r
1191 A time limit that restricts the maximum time (in seconds) allowed for
\r
1192 a Search. A value of zero in this field indicates that no client-
\r
1193 requested time limit restrictions are in effect for the Search.
\r
1194 Servers may also enforce a maximum time limit for the Search.
\r
1197 4.5.1.6. SearchRequest.typesOnly
\r
1199 An indicator as to whether Search results are to contain both
\r
1200 attribute descriptions and values, or just attribute descriptions.
\r
1201 Setting this field to TRUE causes only attribute descriptions (no
\r
1202 values) to be returned. Setting this field to FALSE causes both
\r
1203 attribute descriptions and values to be returned.
\r
1217 Sermersheim Internet-Draft - Expires April 2006 Page 21
\f\r
1218 Lightweight Directory Access Protocol Version 3
\r
1220 4.5.1.7. SearchRequest.filter
\r
1222 A filter that defines the conditions that must be fulfilled in order
\r
1223 for the Search to match a given entry.
\r
1225 The 'and', 'or' and 'not' choices can be used to form combinations of
\r
1226 filters. At least one filter element MUST be present in an 'and' or
\r
1227 'or' choice. The others match against individual attribute values of
\r
1228 entries in the scope of the Search. (Implementor's note: the 'not'
\r
1229 filter is an example of a tagged choice in an implicitly-tagged
\r
1230 module. In BER this is treated as if the tag was explicit.)
\r
1232 A server MUST evaluate filters according to the three-valued logic of
\r
1233 [X.511] (1993) Clause 7.8.1. In summary, a filter is evaluated to
\r
1234 either "TRUE", "FALSE" or "Undefined". If the filter evaluates to
\r
1235 TRUE for a particular entry, then the attributes of that entry are
\r
1236 returned as part of the Search result (subject to any applicable
\r
1237 access control restrictions). If the filter evaluates to FALSE or
\r
1238 Undefined, then the entry is ignored for the Search.
\r
1240 A filter of the "and" choice is TRUE if all the filters in the SET OF
\r
1241 evaluate to TRUE, FALSE if at least one filter is FALSE, and
\r
1242 otherwise Undefined. A filter of the "or" choice is FALSE if all of
\r
1243 the filters in the SET OF evaluate to FALSE, TRUE if at least one
\r
1244 filter is TRUE, and Undefined otherwise. A filter of the 'not' choice
\r
1245 is TRUE if the filter being negated is FALSE, FALSE if it is TRUE,
\r
1246 and Undefined if it is Undefined.
\r
1248 A filter item evaluates to Undefined when the server would not be
\r
1249 able to determine whether the assertion value matches an entry.
\r
1250 Examples include:
\r
1252 - An attribute description in an equalityMatch, substrings,
\r
1253 greaterOrEqual, lessOrEqual, approxMatch or extensibleMatch
\r
1254 filter is not recognized by the server.
\r
1256 - The attribute type does not define the appropriate matching
\r
1259 - A MatchingRuleId in the extensibleMatch is not recognized by
\r
1260 the server or is not valid for the attribute type.
\r
1262 - The type of filtering requested is not implemented.
\r
1264 - The assertion value is invalid.
\r
1266 For example, if a server did not recognize the attribute type
\r
1267 shoeSize, the filters (shoeSize=*), (shoeSize=12), (shoeSize>=12) and
\r
1268 (shoeSize<=12) would each evaluate to Undefined.
\r
1270 Servers MUST NOT return errors if attribute descriptions or matching
\r
1271 rule ids are not recognized, assertion values are invalid, or the
\r
1272 assertion syntax is not supported. More details of filter processing
\r
1273 are given in Clause 7.8 of [X.511].
\r
1275 Sermersheim Internet-Draft - Expires April 2006 Page 22
\f\r
1276 Lightweight Directory Access Protocol Version 3
\r
1280 4.5.1.7.1. SearchRequest.filter.equalityMatch
\r
1282 The matching rule for an equalityMatch filter is defined by the
\r
1283 EQUALITY matching rule for the attribute type or subtype. The filter
\r
1284 is TRUE when the EQUALITY rule returns TRUE as applied to the
\r
1285 attribute or subtype and the asserted value.
\r
1288 4.5.1.7.2. SearchRequest.filter.substrings
\r
1290 There SHALL be at most one 'initial', and at most one 'final' in the
\r
1291 'substrings' of a SubstringFilter. If 'initial' is present, it SHALL
\r
1292 be the first element of 'substrings'. If 'final' is present, it SHALL
\r
1293 be the last element of 'substrings'.
\r
1295 The matching rule for an AssertionValue in a substrings filter item
\r
1296 is defined by the SUBSTR matching rule for the attribute type or
\r
1297 subtype. The filter is TRUE when the SUBSTR rule returns TRUE as
\r
1298 applied to the attribute or subtype and the asserted value.
\r
1300 Note that the AssertionValue in a substrings filter item conforms to
\r
1301 the assertion syntax of the EQUALITY matching rule for the attribute
\r
1302 type rather than the assertion syntax of the SUBSTR matching rule for
\r
1303 the attribute type. Conceptually, the entire SubstringFilter is
\r
1304 converted into an assertion value of the substrings matching rule
\r
1305 prior to applying the rule.
\r
1308 4.5.1.7.3. SearchRequest.filter.greaterOrEqual
\r
1310 The matching rule for a greaterOrEqual filter is defined by the
\r
1311 ORDERING matching rule for the attribute type or subtype. The filter
\r
1312 is TRUE when the ORDERING rule returns FALSE as applied to the
\r
1313 attribute or subtype and the asserted value.
\r
1316 4.5.1.7.4. SearchRequest.filter.lessOrEqual
\r
1318 The matching rules for a lessOrEqual filter are defined by the
\r
1319 ORDERING and EQUALITY matching rules for the attribute type or
\r
1320 subtype. The filter is TRUE when either the ORDERING or EQUALITY rule
\r
1321 returns TRUE as applied to the attribute or subtype and the asserted
\r
1325 4.5.1.7.5. SearchRequest.filter.present
\r
1327 A present filter is TRUE when there is an attribute or subtype of the
\r
1328 specified attribute description present in an entry, FALSE when no
\r
1329 attribute or subtype of the specified attribute description is
\r
1330 present in an entry, and Undefined otherwise.
\r
1333 Sermersheim Internet-Draft - Expires April 2006 Page 23
\f\r
1334 Lightweight Directory Access Protocol Version 3
\r
1337 4.5.1.7.6. SearchRequest.filter.approxMatch
\r
1339 An approxMatch filter is TRUE when there is a value of the attribute
\r
1340 type or subtype for which some locally-defined approximate matching
\r
1341 algorithm (e.g. spelling variations, phonetic match, etc.) returns
\r
1342 TRUE. If a value matches for equality, it also satisfies an
\r
1343 approximate match. If approximate matching is not supported for the
\r
1344 attribute, this filter item should be treated as an equalityMatch.
\r
1347 4.5.1.7.7. SearchRequest.filter.extensibleMatch
\r
1349 The fields of the extensibleMatch filter item are evaluated as
\r
1352 - If the matchingRule field is absent, the type field MUST be
\r
1353 present, and an equality match is performed for that type.
\r
1355 - If the type field is absent and the matchingRule is present, the
\r
1356 matchValue is compared against all attributes in an entry which
\r
1357 support that matchingRule.
\r
1359 - If the type field is present and the matchingRule is present, the
\r
1360 matchValue is compared against the specified attribute type and
\r
1363 - If the dnAttributes field is set to TRUE, the match is
\r
1364 additionally applied against all the AttributeValueAssertions in
\r
1365 an entry's distinguished name, and evaluates to TRUE if there is
\r
1366 at least one attribute or subtype in the distinguished name for
\r
1367 which the filter item evaluates to TRUE. The dnAttributes field is
\r
1368 present to alleviate the need for multiple versions of generic
\r
1369 matching rules (such as word matching), where one applies to
\r
1370 entries and another applies to entries and DN attributes as well.
\r
1372 The matchingRule used for evaluation determines the syntax for the
\r
1373 assertion value. Once the matchingRule and attribute(s) have been
\r
1374 determined, the filter item evaluates to TRUE if it matches at least
\r
1375 one attribute type or subtype in the entry, FALSE if it does not
\r
1376 match any attribute type or subtype in the entry, and Undefined if
\r
1377 the matchingRule is not recognized, the matchingRule is unsuitable
\r
1378 for use with the specified type, or the assertionValue is invalid.
\r
1381 4.5.1.7. SearchRequest.attributes
\r
1383 A selection list of the attributes to be returned from each entry
\r
1384 which matches the search filter. Attributes which are subtypes of
\r
1385 listed attributes are implicitly included. LDAPString values of this
\r
1386 field are constrained to the following Augmented Backus-Naur Form
\r
1389 attributeSelector = attributedescription / selectorspecial
\r
1391 Sermersheim Internet-Draft - Expires April 2006 Page 24
\f\r
1392 Lightweight Directory Access Protocol Version 3
\r
1395 selectorspecial = noattrs / alluserattrs
\r
1397 noattrs = %x31.2E.31 ; "1.1"
\r
1399 alluserattrs = %x2A ; asterisk ("*")
\r
1401 The <attributedescription> production is defined in Section 2.5 of
\r
1404 There are three special cases which may appear in the attributes
\r
1407 - an empty list with no attributes,
\r
1409 - a list containing "*" (with zero or more attribute
\r
1410 descriptions), and
\r
1412 - a list containing only "1.1".
\r
1414 An empty list requests the return of all user attributes.
\r
1416 A list containing "*" requests the return of all user attributes
\r
1417 in addition to other listed (operational) attributes.
\r
1419 A list containing only the OID "1.1" indicates that no attributes
\r
1420 are to be returned. If "1.1" is provided with other
\r
1421 attributeSelector values, the "1.1" attributeSelector is ignored.
\r
1422 This OID was chosen because it does not (and can not) correspond
\r
1423 to any attribute in use.
\r
1425 Client implementors should note that even if all user attributes are
\r
1426 requested, some attributes and/or attribute values of the entry may
\r
1427 not be included in Search results due to access controls or other
\r
1428 restrictions. Furthermore, servers will not return operational
\r
1429 attributes, such as objectClasses or attributeTypes, unless they are
\r
1430 listed by name. Operational attributes are described in [Models].
\r
1432 Attributes are returned at most once in an entry. If an attribute
\r
1433 description is named more than once in the list, the subsequent names
\r
1434 are ignored. If an attribute description in the list is not
\r
1435 recognized, it is ignored by the server.
\r
1438 4.5.2. Search Result
\r
1440 The results of the Search operation are returned as zero or more
\r
1441 SearchResultEntry and/or SearchResultReference messages, followed by
\r
1442 a single SearchResultDone message.
\r
1444 SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
\r
1445 objectName LDAPDN,
\r
1446 attributes PartialAttributeList }
\r
1449 Sermersheim Internet-Draft - Expires April 2006 Page 25
\f\r
1450 Lightweight Directory Access Protocol Version 3
\r
1452 PartialAttributeList ::= SEQUENCE OF
\r
1453 partialAttribute PartialAttribute
\r
1455 SearchResultReference ::= [APPLICATION 19] SEQUENCE
\r
1456 SIZE (1..MAX) OF uri URI
\r
1458 SearchResultDone ::= [APPLICATION 5] LDAPResult
\r
1460 Each SearchResultEntry represents an entry found during the Search.
\r
1461 Each SearchResultReference represents an area not yet explored during
\r
1462 the Search. The SearchResultEntry and SearchResultReference messages
\r
1463 may come in any order. Following all the SearchResultReference and
\r
1464 SearchResultEntry responses, the server returns a SearchResultDone
\r
1465 response, which contains an indication of success, or detailing any
\r
1466 errors that have occurred.
\r
1468 Each entry returned in a SearchResultEntry will contain all
\r
1469 appropriate attributes as specified in the attributes field of the
\r
1470 Search Request, subject to access control and other administrative
\r
1471 policy. Note that the PartialAttributeList may hold zero elements.
\r
1472 This may happen when none of the attributes of an entry were
\r
1473 requested, or could be returned. Note also that the partialAttribute
\r
1474 vals set may hold zero elements. This may happen when typesOnly is
\r
1475 requested, access controls prevent the return of values, or other
\r
1478 Some attributes may be constructed by the server and appear in a
\r
1479 SearchResultEntry attribute list, although they are not stored
\r
1480 attributes of an entry. Clients SHOULD NOT assume that all attributes
\r
1481 can be modified, even if permitted by access control.
\r
1483 If the server's schema defines short names [Models] for an attribute
\r
1484 type then the server SHOULD use one of those names in attribute
\r
1485 descriptions for that attribute type (in preference to using the
\r
1486 <numericoid> [Models] format of the attribute type's object
\r
1487 identifier). The server SHOULD NOT use the short name if that name is
\r
1488 known by the server to be ambiguous, or otherwise likely to cause
\r
1489 interoperability problems.
\r
1492 4.5.3. Continuation References in the Search Result
\r
1494 If the server was able to locate the entry referred to by the
\r
1495 baseObject but was unable or unwilling to search one or more non-
\r
1496 local entries, the server may return one or more
\r
1497 SearchResultReference messages, each containing a reference to
\r
1498 another set of servers for continuing the operation. A server MUST
\r
1499 NOT return any SearchResultReference messages if it has not located
\r
1500 the baseObject and thus has not searched any entries; in this case it
\r
1501 would return a SearchResultDone containing either a referral or
\r
1502 noSuchObject result code (depending on the server's knowledge of the
\r
1503 entry named in the baseObject).
\r
1507 Sermersheim Internet-Draft - Expires April 2006 Page 26
\f\r
1508 Lightweight Directory Access Protocol Version 3
\r
1510 If a server holds a copy or partial copy of the subordinate naming
\r
1511 context (Section 5 of [Models]), it may use the search filter to
\r
1512 determine whether or not to return a SearchResultReference response.
\r
1513 Otherwise SearchResultReference responses are always returned when in
\r
1516 The SearchResultReference is of the same data type as the Referral.
\r
1518 If the client wishes to progress the Search, it issues a new Search
\r
1519 operation for each SearchResultReference that is returned. If
\r
1520 multiple URIs are present, the client assumes that any supported URI
\r
1521 may be used to progress the operation.
\r
1523 Clients that follow search continuation references MUST ensure that
\r
1524 they do not loop between servers. They MUST NOT repeatedly contact
\r
1525 the same server for the same request with the same parameters. Some
\r
1526 clients use a counter that is incremented each time search result
\r
1527 reference handling occurs for an operation, and these kinds of
\r
1528 clients MUST be able to handle at least ten nested referrals while
\r
1529 progressing the operation.
\r
1531 Note that the Abandon operation described in Section 4.11 applies
\r
1532 only to a particular operation sent at the LDAP message layer between
\r
1533 a client and server. The client must abandon subsequent Search
\r
1534 operations it wishes to individually.
\r
1536 A URI for a server implementing LDAP and accessible via [TCP]/[IP]
\r
1537 (v4 or v6) is written as an LDAP URL according to [LDAPURL].
\r
1539 SearchResultReference values which are LDAP URLs follow these rules:
\r
1541 - The <dn> part of the LDAP URL MUST be present, with the new target
\r
1542 object name. The client uses this name when following the
\r
1545 - Some servers (e.g. participating in distributed indexing) may
\r
1546 provide a different filter in the LDAP URL.
\r
1548 - If the <filter> part of the LDAP URL is present, the client uses
\r
1549 this filter in its next request to progress this Search, and if it
\r
1550 is not present the client uses the same filter as it used for that
\r
1553 - If the originating search scope was singleLevel, the <scope> part
\r
1554 of the LDAP URL will be "base".
\r
1556 - It is RECOMMENDED that the <scope> part be present to avoid
\r
1557 ambiguity. In the absence of a <scope> part, the scope of the
\r
1558 original Search request is assumed.
\r
1560 - Other aspects of the new Search request may be the same as or
\r
1561 different from the Search request which generated the
\r
1562 SearchResultReference.
\r
1565 Sermersheim Internet-Draft - Expires April 2006 Page 27
\f\r
1566 Lightweight Directory Access Protocol Version 3
\r
1568 - The name of an unexplored subtree in a SearchResultReference need
\r
1569 not be subordinate to the base object.
\r
1571 Other kinds of URIs may be returned. The syntax and semantics of such
\r
1572 URIs is left to future specifications. Clients may ignore URIs that
\r
1573 they do not support.
\r
1575 UTF-8 encoded characters appearing in the string representation of a
\r
1576 DN, search filter, or other fields of the referral value may not be
\r
1577 legal for URIs (e.g. spaces) and MUST be escaped using the % method
\r
1582 4.5.3.1. Examples
\r
1584 For example, suppose the contacted server (hosta) holds the entry
\r
1585 <DC=Example,DC=NET> and the entry <CN=Manager,DC=Example,DC=NET>. It
\r
1586 knows that both LDAP servers (hostb) and (hostc) hold
\r
1587 <OU=People,DC=Example,DC=NET> (one is the master and the other server
\r
1588 a shadow), and that LDAP-capable server (hostd) holds the subtree
\r
1589 <OU=Roles,DC=Example,DC=NET>. If a wholeSubtree Search of
\r
1590 <DC=Example,DC=NET> is requested to the contacted server, it may
\r
1591 return the following:
\r
1593 SearchResultEntry for DC=Example,DC=NET
\r
1594 SearchResultEntry for CN=Manager,DC=Example,DC=NET
\r
1595 SearchResultReference {
\r
1596 ldap://hostb/OU=People,DC=Example,DC=NET??sub
\r
1597 ldap://hostc/OU=People,DC=Example,DC=NET??sub }
\r
1598 SearchResultReference {
\r
1599 ldap://hostd/OU=Roles,DC=Example,DC=NET??sub }
\r
1600 SearchResultDone (success)
\r
1602 Client implementors should note that when following a
\r
1603 SearchResultReference, additional SearchResultReference may be
\r
1604 generated. Continuing the example, if the client contacted the server
\r
1605 (hostb) and issued the Search request for the subtree
\r
1606 <OU=People,DC=Example,DC=NET>, the server might respond as follows:
\r
1608 SearchResultEntry for OU=People,DC=Example,DC=NET
\r
1609 SearchResultReference {
\r
1610 ldap://hoste/OU=Managers,OU=People,DC=Example,DC=NET??sub }
\r
1611 SearchResultReference {
\r
1612 ldap://hostf/OU=Consultants,OU=People,DC=Example,DC=NET??sub }
\r
1613 SearchResultDone (success)
\r
1615 Similarly, if a singleLevel Search of <DC=Example,DC=NET> is
\r
1616 requested to the contacted server, it may return the following:
\r
1623 Sermersheim Internet-Draft - Expires April 2006 Page 28
\f\r
1624 Lightweight Directory Access Protocol Version 3
\r
1626 SearchResultEntry for CN=Manager,DC=Example,DC=NET
\r
1627 SearchResultReference {
\r
1628 ldap://hostb/OU=People,DC=Example,DC=NET??base
\r
1629 ldap://hostc/OU=People,DC=Example,DC=NET??base }
\r
1630 SearchResultReference {
\r
1631 ldap://hostd/OU=Roles,DC=Example,DC=NET??base }
\r
1632 SearchResultDone (success)
\r
1634 If the contacted server does not hold the base object for the Search,
\r
1635 but has knowledge of its possible location, then it may return a
\r
1636 referral to the client. In this case, if the client requests a
\r
1637 subtree Search of <DC=Example,DC=ORG> to hosta, the server returns a
\r
1638 SearchResultDone containing a referral.
\r
1640 SearchResultDone (referral) {
\r
1641 ldap://hostg/DC=Example,DC=ORG??sub }
\r
1644 4.6. Modify Operation
\r
1646 The Modify operation allows a client to request that a modification
\r
1647 of an entry be performed on its behalf by a server. The Modify
\r
1648 Request is defined as follows:
\r
1650 ModifyRequest ::= [APPLICATION 6] SEQUENCE {
\r
1652 changes SEQUENCE OF change SEQUENCE {
\r
1653 operation ENUMERATED {
\r
1658 modification PartialAttribute } }
\r
1660 Fields of the Modify Request are:
\r
1662 - object: The value of this field contains the name of the entry to
\r
1663 be modified. The server SHALL NOT perform any alias dereferencing
\r
1664 in determining the object to be modified.
\r
1666 - changes: A list of modifications to be performed on the entry. The
\r
1667 entire list of modifications MUST be performed in the order they
\r
1668 are listed as a single atomic operation. While individual
\r
1669 modifications may violate certain aspects of the directory schema
\r
1670 (such as the object class definition and DIT content rule), the
\r
1671 resulting entry after the entire list of modifications is
\r
1672 performed MUST conform to the requirements of the directory model
\r
1673 and controlling schema [Models].
\r
1675 - operation: Used to specify the type of modification being
\r
1676 performed. Each operation type acts on the following
\r
1677 modification. The values of this field have the following
\r
1678 semantics respectively:
\r
1681 Sermersheim Internet-Draft - Expires April 2006 Page 29
\f\r
1682 Lightweight Directory Access Protocol Version 3
\r
1684 add: add values listed to the modification attribute,
\r
1685 creating the attribute if necessary;
\r
1687 delete: delete values listed from the modification attribute.
\r
1688 If no values are listed, or if all current values of the
\r
1689 attribute are listed, the entire attribute is removed;
\r
1691 replace: replace all existing values of the modification
\r
1692 attribute with the new values listed, creating the attribute
\r
1693 if it did not already exist. A replace with no value will
\r
1694 delete the entire attribute if it exists, and is ignored if
\r
1695 the attribute does not exist.
\r
1697 - modification: A PartialAttribute (which may have an empty SET
\r
1698 of vals) used to hold the attribute type or attribute type and
\r
1699 values being modified.
\r
1701 Upon receipt of a Modify Request, the server attempts to perform the
\r
1702 necessary modifications to the DIT and returns the result in a Modify
\r
1703 Response, defined as follows:
\r
1705 ModifyResponse ::= [APPLICATION 7] LDAPResult
\r
1707 The server will return to the client a single Modify Response
\r
1708 indicating either the successful completion of the DIT modification,
\r
1709 or the reason that the modification failed. Due to the requirement
\r
1710 for atomicity in applying the list of modifications in the Modify
\r
1711 Request, the client may expect that no modifications of the DIT have
\r
1712 been performed if the Modify Response received indicates any sort of
\r
1713 error, and that all requested modifications have been performed if
\r
1714 the Modify Response indicates successful completion of the Modify
\r
1715 operation. Whether the modification was applied or not cannot be
\r
1716 determined by the client if the Modify Response was not received
\r
1717 (e.g. the LDAP session was terminated or the Modify operation was
\r
1720 Servers MUST ensure that entries conform to user and system schema
\r
1721 rules or other data model constraints. The Modify operation cannot be
\r
1722 used to remove from an entry any of its distinguished values, i.e.
\r
1723 those values which form the entry's relative distinguished name. An
\r
1724 attempt to do so will result in the server returning the
\r
1725 notAllowedOnRDN result code. The Modify DN operation described in
\r
1726 Section 4.9 is used to rename an entry.
\r
1728 For attribute types which specify no equality matching, the rules in
\r
1729 Section 2.5.1 of [Models] are followed.
\r
1731 Note that due to the simplifications made in LDAP, there is not a
\r
1732 direct mapping of the changes in an LDAP ModifyRequest onto the
\r
1733 changes of a DAP ModifyEntry operation, and different implementations
\r
1734 of LDAP-DAP gateways may use different means of representing the
\r
1735 change. If successful, the final effect of the operations on the
\r
1736 entry MUST be identical.
\r
1739 Sermersheim Internet-Draft - Expires April 2006 Page 30
\f\r
1740 Lightweight Directory Access Protocol Version 3
\r
1743 4.7. Add Operation
\r
1745 The Add operation allows a client to request the addition of an entry
\r
1746 into the Directory. The Add Request is defined as follows:
\r
1748 AddRequest ::= [APPLICATION 8] SEQUENCE {
\r
1750 attributes AttributeList }
\r
1752 AttributeList ::= SEQUENCE OF attribute Attribute
\r
1754 Fields of the Add Request are:
\r
1756 - entry: the name of the entry to be added. The server SHALL NOT
\r
1757 dereference any aliases in locating the entry to be added.
\r
1759 - attributes: the list of attributes that, along with those from the
\r
1760 RDN, make up the content of the entry being added. Clients MAY or
\r
1761 MAY NOT include the RDN attribute(s) in this list. Clients MUST
\r
1762 NOT supply NO-USER-MODIFICATION attributes such as the
\r
1763 createTimestamp or creatorsName attributes, since the server
\r
1764 maintains these automatically.
\r
1766 Servers MUST ensure that entries conform to user and system schema
\r
1767 rules or other data model constraints. For attribute types which
\r
1768 specify no equality matching, the rules in Section 2.5.1 of [Models]
\r
1769 are followed (this applies to the naming attribute in addition to any
\r
1770 multi-valued attributes being added).
\r
1772 The entry named in the entry field of the AddRequest MUST NOT exist
\r
1773 for the AddRequest to succeed. The immediate superior (parent) of an
\r
1774 object or alias entry to be added MUST exist. For example, if the
\r
1775 client attempted to add <CN=JS,DC=Example,DC=NET>, the
\r
1776 <DC=Example,DC=NET> entry did not exist, and the <DC=NET> entry did
\r
1777 exist, then the server would return the noSuchObject result code with
\r
1778 the matchedDN field containing <DC=NET>.
\r
1780 Upon receipt of an Add Request, a server will attempt to add the
\r
1781 requested entry. The result of the Add attempt will be returned to
\r
1782 the client in the Add Response, defined as follows:
\r
1784 AddResponse ::= [APPLICATION 9] LDAPResult
\r
1786 A response of success indicates that the new entry has been added to
\r
1790 4.8. Delete Operation
\r
1792 The Delete operation allows a client to request the removal of an
\r
1793 entry from the Directory. The Delete Request is defined as follows:
\r
1795 DelRequest ::= [APPLICATION 10] LDAPDN
\r
1797 Sermersheim Internet-Draft - Expires April 2006 Page 31
\f\r
1798 Lightweight Directory Access Protocol Version 3
\r
1801 The Delete Request consists of the name of the entry to be deleted.
\r
1802 The server SHALL NOT dereference aliases while resolving the name of
\r
1803 the target entry to be removed.
\r
1805 Only leaf entries (those with no subordinate entries) can be deleted
\r
1806 with this operation.
\r
1808 Upon receipt of a Delete Request, a server will attempt to perform
\r
1809 the entry removal requested and return the result in the Delete
\r
1810 Response defined as follows:
\r
1812 DelResponse ::= [APPLICATION 11] LDAPResult
\r
1815 4.9. Modify DN Operation
\r
1817 The Modify DN operation allows a client to change the Relative
\r
1818 Distinguished Name (RDN) of an entry in the Directory, and/or to move
\r
1819 a subtree of entries to a new location in the Directory. The Modify
\r
1820 DN Request is defined as follows:
\r
1822 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
\r
1824 newrdn RelativeLDAPDN,
\r
1825 deleteoldrdn BOOLEAN,
\r
1826 newSuperior [0] LDAPDN OPTIONAL }
\r
1828 Fields of the Modify DN Request are:
\r
1830 - entry: the name of the entry to be changed. This entry may or may
\r
1831 not have subordinate entries.
\r
1833 - newrdn: the new RDN of the entry. The value of the old RDN is
\r
1834 supplied when moving the entry to a new superior without changing
\r
1835 its RDN. Attribute values of the new RDN not matching any
\r
1836 attribute value of the entry are added to the entry and an
\r
1837 appropriate error is returned if this fails.
\r
1839 - deleteoldrdn: a boolean field that controls whether the old RDN
\r
1840 attribute values are to be retained as attributes of the entry, or
\r
1841 deleted from the entry.
\r
1843 - newSuperior: if present, this is the name of an existing object
\r
1844 entry which becomes the immediate superior (parent) of the
\r
1847 The server SHALL NOT dereference any aliases in locating the objects
\r
1848 named in entry or newSuperior.
\r
1850 Upon receipt of a ModifyDNRequest, a server will attempt to perform
\r
1851 the name change and return the result in the Modify DN Response,
\r
1852 defined as follows:
\r
1855 Sermersheim Internet-Draft - Expires April 2006 Page 32
\f\r
1856 Lightweight Directory Access Protocol Version 3
\r
1858 ModifyDNResponse ::= [APPLICATION 13] LDAPResult
\r
1860 For example, if the entry named in the entry field was <cn=John
\r
1861 Smith,c=US>, the newrdn field was <cn=John Cougar Smith>, and the
\r
1862 newSuperior field was absent, then this operation would attempt to
\r
1863 rename the entry to be <cn=John Cougar Smith,c=US>. If there was
\r
1864 already an entry with that name, the operation would fail with the
\r
1865 entryAlreadyExists result code.
\r
1867 Servers MUST ensure that entries conform to user and system schema
\r
1868 rules or other data model constraints. For attribute types which
\r
1869 specify no equality matching, the rules in Section 2.5.1 of [Models]
\r
1870 are followed (this pertains to newrdn and deleteoldrdn).
\r
1872 The object named in newSuperior MUST exist. For example, if the
\r
1873 client attempted to add <CN=JS,DC=Example,DC=NET>, the
\r
1874 <DC=Example,DC=NET> entry did not exist, and the <DC=NET> entry did
\r
1875 exist, then the server would return the noSuchObject result code with
\r
1876 the matchedDN field containing <DC=NET>.
\r
1878 If the deleteoldrdn field is TRUE, the attribute values forming the
\r
1879 old RDN but not the new RDN are deleted from the entry. If the
\r
1880 deleteoldrdn field is FALSE, the attribute values forming the old RDN
\r
1881 will be retained as non-distinguished attribute values of the entry.
\r
1883 Note that X.500 restricts the ModifyDN operation to only affect
\r
1884 entries that are contained within a single server. If the LDAP server
\r
1885 is mapped onto DAP, then this restriction will apply, and the
\r
1886 affectsMultipleDSAs result code will be returned if this error
\r
1887 occurred. In general, clients MUST NOT expect to be able to perform
\r
1888 arbitrary movements of entries and subtrees between servers or
\r
1889 between naming contexts.
\r
1892 4.10. Compare Operation
\r
1894 The Compare operation allows a client to compare an assertion value
\r
1895 with the values of a particular attribute in a particular entry in
\r
1896 the Directory. The Compare Request is defined as follows:
\r
1898 CompareRequest ::= [APPLICATION 14] SEQUENCE {
\r
1900 ava AttributeValueAssertion }
\r
1902 Fields of the Compare Request are:
\r
1904 - entry: the name of the entry to be compared. The server SHALL NOT
\r
1905 dereference any aliases in locating the entry to be compared.
\r
1907 - ava: holds the attribute value assertion to be compared.
\r
1909 Upon receipt of a Compare Request, a server will attempt to perform
\r
1910 the requested comparison and return the result in the Compare
\r
1911 Response, defined as follows:
\r
1913 Sermersheim Internet-Draft - Expires April 2006 Page 33
\f\r
1914 Lightweight Directory Access Protocol Version 3
\r
1917 CompareResponse ::= [APPLICATION 15] LDAPResult
\r
1919 The resultCode is set to compareTrue, compareFalse, or an appropriate
\r
1920 error. compareTrue indicates that the assertion value in the ava
\r
1921 field matches a value of the attribute or subtype according to the
\r
1922 attribute's EQUALITY matching rule. compareFalse indicates that the
\r
1923 assertion value in the ava field and the values of the attribute or
\r
1924 subtype did not match. Other result codes indicate either that the
\r
1925 result of the comparison was Undefined (Section 4.5.1), or that some
\r
1928 Note that some directory systems may establish access controls which
\r
1929 permit the values of certain attributes (such as userPassword) to be
\r
1930 compared but not interrogated by other means.
\r
1933 4.11. Abandon Operation
\r
1935 The function of the Abandon operation is to allow a client to request
\r
1936 that the server abandon an uncompleted operation. The Abandon Request
\r
1937 is defined as follows:
\r
1939 AbandonRequest ::= [APPLICATION 16] MessageID
\r
1941 The MessageID is that of an operation which was requested earlier at
\r
1942 this LDAP message layer. The Abandon request itself has its own
\r
1943 MessageID. This is distinct from the MessageID of the earlier
\r
1944 operation being abandoned.
\r
1946 There is no response defined in the Abandon operation. Upon receipt
\r
1947 of an AbandonRequest, the server MAY abandon the operation identified
\r
1948 by the MessageID. Since the client cannot tell the difference between
\r
1949 a successfully abandoned operation and an uncompleted operation, the
\r
1950 application of the Abandon operation is limited to uses where the
\r
1951 client does not require an indication of its outcome.
\r
1953 Abandon, Bind, Unbind, and StartTLS operations cannot be abandoned.
\r
1955 In the event that a server receives an Abandon Request on a Search
\r
1956 operation in the midst of transmitting responses to the Search, that
\r
1957 server MUST cease transmitting entry responses to the abandoned
\r
1958 request immediately, and MUST NOT send the SearchResultDone. Of
\r
1959 course, the server MUST ensure that only properly encoded LDAPMessage
\r
1960 PDUs are transmitted.
\r
1962 The ability to abandon other (particularly update) operations is at
\r
1963 the discretion of the server.
\r
1965 Clients should not send Abandon requests for the same operation
\r
1966 multiple times, and MUST also be prepared to receive results from
\r
1967 operations it has abandoned (since these may have been in transit
\r
1968 when the Abandon was requested, or are not able to be abandoned).
\r
1971 Sermersheim Internet-Draft - Expires April 2006 Page 34
\f\r
1972 Lightweight Directory Access Protocol Version 3
\r
1974 Servers MUST discard Abandon requests for message IDs they do not
\r
1975 recognize, for operations which cannot be abandoned, and for
\r
1976 operations which have already been abandoned.
\r
1979 4.12. Extended Operation
\r
1981 The Extended operation allows additional operations to be defined for
\r
1982 services not already available in the protocol. For example, to Add
\r
1983 operations to install transport layer security (see Section 4.14).
\r
1985 The Extended operation allows clients to make requests and receive
\r
1986 responses with predefined syntaxes and semantics. These may be
\r
1987 defined in RFCs or be private to particular implementations.
\r
1989 Each Extended operation consists of an Extended request and an
\r
1990 Extended response.
\r
1992 ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
\r
1993 requestName [0] LDAPOID,
\r
1994 requestValue [1] OCTET STRING OPTIONAL }
\r
1996 The requestName is a dotted-decimal representation of the unique
\r
1997 OBJECT IDENTIFIER corresponding to the request. The requestValue is
\r
1998 information in a form defined by that request, encapsulated inside an
\r
2001 The server will respond to this with an LDAPMessage containing an
\r
2002 ExtendedResponse.
\r
2004 ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
\r
2005 COMPONENTS OF LDAPResult,
\r
2006 responseName [10] LDAPOID OPTIONAL,
\r
2007 responseValue [11] OCTET STRING OPTIONAL }
\r
2009 The responseName field, when present, contains an LDAPOID which is
\r
2010 unique for this extended operation or response. This field is
\r
2011 optional (even when the extension specification specifies an LDAPOID
\r
2012 to be returned in the field). The field will be absent whenever the
\r
2013 server is unable or unwilling to determine the appropriate LDAPOID to
\r
2014 return, for instance when the requestName cannot be parsed or its
\r
2015 value is not recognized.
\r
2017 Where the requestName is not recognized, the server returns
\r
2018 protocolError (The server may return protocolError in other cases).
\r
2020 The requestValue and responseValue fields contain information
\r
2021 associated with the operation. The format of these fields is defined
\r
2022 by the specification of the Extended operation. Implementations MUST
\r
2023 be prepared to handle arbitrary contents of these fields, including
\r
2024 zero bytes. Values that are defined in terms of ASN.1 and BER encoded
\r
2025 according to Section 5.1, also follow the extensibility rules in
\r
2029 Sermersheim Internet-Draft - Expires April 2006 Page 35
\f\r
2030 Lightweight Directory Access Protocol Version 3
\r
2032 Servers list the requestName of Extended Requests they recognize in
\r
2033 the 'supportedExtension' attribute in the root DSE (Section 5.1 of
\r
2036 Extended operations may be specified in other documents. The
\r
2037 specification of an Extended operation consists of:
\r
2039 - the OBJECT IDENTIFIER assigned to the requestName,
\r
2041 - the OBJECT IDENTIFIER (if any) assigned to the responseName (note
\r
2042 that the same OBJECT IDENTIFIER may be used for both the
\r
2043 requestName and responseName),
\r
2045 - the format of the contents of the requestValue and responseValue
\r
2048 - the semantics of the operation.
\r
2051 4.13. IntermediateResponse Message
\r
2053 While the Search operation provides a mechanism to return multiple
\r
2054 response messages for a single Search request, other operations, by
\r
2055 nature, do not provide for multiple response messages.
\r
2057 The IntermediateResponse message provides a general mechanism for
\r
2058 defining single-request/multiple-response operations in LDAP. This
\r
2059 message is intended to be used in conjunction with the Extended
\r
2060 operation to define new single-request/multiple-response operations
\r
2061 or in conjunction with a control when extending existing LDAP
\r
2062 operations in a way that requires them to return Intermediate
\r
2063 response information.
\r
2065 It is intended that the definitions and descriptions of Extended
\r
2066 operations and controls that make use of the IntermediateResponse
\r
2067 message will define the circumstances when an IntermediateResponse
\r
2068 message can be sent by a server and the associated meaning of an
\r
2069 IntermediateResponse message sent in a particular circumstance.
\r
2071 IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
\r
2072 responseName [0] LDAPOID OPTIONAL,
\r
2073 responseValue [1] OCTET STRING OPTIONAL }
\r
2075 IntermediateResponse messages SHALL NOT be returned to the client
\r
2076 unless the client issues a request that specifically solicits their
\r
2077 return. This document defines two forms of solicitation: Extended
\r
2078 operation and request control. IntermediateResponse messages are
\r
2079 specified in documents describing the manner in which they are
\r
2080 solicited (i.e. in the Extended operation or request control
\r
2081 specification that uses them). These specifications include:
\r
2083 - the OBJECT IDENTIFIER (if any) assigned to the responseName,
\r
2085 - the format of the contents of the responseValue (if any), and
\r
2087 Sermersheim Internet-Draft - Expires April 2006 Page 36
\f\r
2088 Lightweight Directory Access Protocol Version 3
\r
2091 - the semantics associated with the IntermediateResponse message.
\r
2093 Extensions that allow the return of multiple types of
\r
2094 IntermediateResponse messages SHALL identify those types using unique
\r
2095 responseName values (note that one of these may specify no value).
\r
2097 Sections 4.13.1 and 4.13.2 describe additional requirements on the
\r
2098 inclusion of responseName and responseValue in IntermediateResponse
\r
2102 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse
\r
2104 A single-request/multiple-response operation may be defined using a
\r
2105 single ExtendedRequest message to solicit zero or more
\r
2106 IntermediateResponse messages of one or more kinds followed by an
\r
2107 ExtendedResponse message.
\r
2110 4.13.2. Usage with LDAP Request Controls
\r
2112 A control's semantics may include the return of zero or more
\r
2113 IntermediateResponse messages prior to returning the final result
\r
2114 code for the operation. One or more kinds of IntermediateResponse
\r
2115 messages may be sent in response to a request control.
\r
2117 All IntermediateResponse messages associated with request controls
\r
2118 SHALL include a responseName. This requirement ensures that the
\r
2119 client can correctly identify the source of IntermediateResponse
\r
2122 - two or more controls using IntermediateResponse messages are
\r
2123 included in a request for any LDAP operation or
\r
2125 - one or more controls using IntermediateResponse messages are
\r
2126 included in a request with an LDAP Extended operation that uses
\r
2127 IntermediateResponse messages.
\r
2130 4.14. StartTLS Operation
\r
2132 The Start Transport Layer Security (StartTLS) operation's purpose is
\r
2133 to initiate installation of a TLS layer. The StartTLS operation is
\r
2134 defined using the Extended operation mechanism described in Section
\r
2145 Sermersheim Internet-Draft - Expires April 2006 Page 37
\f\r
2146 Lightweight Directory Access Protocol Version 3
\r
2148 4.14.1. StartTLS Request
\r
2150 A client requests TLS establishment by transmitting a StartTLS
\r
2151 request message to the server. The StartTLS request is defined in
\r
2152 terms of an ExtendedRequest. The requestName is
\r
2153 "1.3.6.1.4.1.1466.20037", and the requestValue field is always
\r
2156 The client MUST NOT send any LDAP PDUs at this LDAP message layer
\r
2157 following this request until it receives a StartTLS Extended response
\r
2158 and, in the case of a successful response, completes TLS
\r
2161 Detected sequencing problems (particularly those detailed in Section
\r
2162 3.1.1 of [AuthMeth]) result in the resultCode being set to
\r
2165 If the server does not support TLS (whether by design or by current
\r
2166 configuration), it returns with the resultCode set to protocolError
\r
2167 as described in Section 4.12.
\r
2170 4.14.2. StartTLS Response
\r
2172 When a StartTLS request is received, servers supporting the operation
\r
2173 MUST return a StartTLS response message to the requestor. The
\r
2174 responseName is "1.3.6.1.4.1.1466.20037" when provided (See 4.12).
\r
2175 The responseValue is always absent.
\r
2177 If the server is willing and able to negotiate TLS, it returns the
\r
2178 StartTLS response with the resultCode set to success. Upon client
\r
2179 receipt of a successful StartTLS response, protocol peers may
\r
2180 commence with TLS negotiation as discussed in Section 3 of
\r
2183 If the server is otherwise unwilling or unable to perform this
\r
2184 operation, the server is to return an appropriate result code
\r
2185 indicating the nature of the problem. For example, if the TLS
\r
2186 subsystem is not presently available, the server may indicate so by
\r
2187 returning with the resultCode set to unavailable. In cases where a
\r
2188 non-success result code is returned, the LDAP session is left without
\r
2192 4.14.3. Removal of the TLS Layer
\r
2194 Either the client or server MAY remove the TLS layer and leave the
\r
2195 LDAP message layer intact by sending and receiving a TLS closure
\r
2201 Sermersheim Internet-Draft - Expires April 2006 Page 38
\f\r
2202 Lightweight Directory Access Protocol Version 3
\r
2204 The initiating protocol peer sends the TLS closure alert and MUST
\r
2205 wait until it receives a TLS closure alert from the other peer before
\r
2206 sending further LDAP PDUs.
\r
2208 When a protocol peer receives the initial TLS closure alert, it may
\r
2209 choose to allow the LDAP message layer to remain intact. In this
\r
2210 case, it MUST immediately transmit a TLS closure alert. Following
\r
2211 this, it MAY send and receive LDAP PDUs.
\r
2213 Protocol peers MAY terminate the LDAP session after sending or
\r
2214 receiving a TLS closure alert.
\r
2217 5. Protocol Encoding, Connection, and Transfer
\r
2219 This protocol is designed to run over connection-oriented, reliable
\r
2220 transports, where the data stream is divided into octets (8-bit
\r
2221 units), with each octet and each bit being significant.
\r
2223 One underlying service, LDAP over TCP, is defined in Section
\r
2224 5.2. This service is generally applicable to applications providing
\r
2225 or consuming X.500-based directory services on the Internet. This
\r
2226 specification was generally written with the TCP mapping in mind.
\r
2227 Specifications detailing other mappings may encounter various
\r
2230 Implementations of LDAP over TCP MUST implement the mapping as
\r
2231 described in Section 5.2.
\r
2233 This table illustrates the relationship between the different layers
\r
2234 involved in an exchange between two protocol peers:
\r
2236 +----------------------+
\r
2237 | LDAP message layer |
\r
2238 +----------------------+ > LDAP PDUs
\r
2239 +----------------------+ < data
\r
2241 +----------------------+ > SASL-protected data
\r
2242 +----------------------+ < data
\r
2244 Application +----------------------+ > TLS-protected data
\r
2245 ------------+----------------------+ < data
\r
2246 Transport | transport connection |
\r
2247 +----------------------+
\r
2250 5.1. Protocol Encoding
\r
2252 The protocol elements of LDAP SHALL be encoded for exchange using the
\r
2253 Basic Encoding Rules [BER] of [ASN.1] with the following
\r
2256 - Only the definite form of length encoding is used.
\r
2259 Sermersheim Internet-Draft - Expires April 2006 Page 39
\f\r
2260 Lightweight Directory Access Protocol Version 3
\r
2263 - OCTET STRING values are encoded in the primitive form only.
\r
2265 - If the value of a BOOLEAN type is true, the encoding of the value
\r
2266 octet is set to hex "FF".
\r
2268 - If a value of a type is its default value, it is absent. Only some
\r
2269 BOOLEAN and INTEGER types have default values in this protocol
\r
2272 These restrictions are meant to ease the overhead of encoding and
\r
2273 decoding certain elements in BER.
\r
2275 These restrictions do not apply to ASN.1 types encapsulated inside of
\r
2276 OCTET STRING values, such as attribute values, unless otherwise
\r
2280 5.2. Transmission Control Protocol (TCP)
\r
2282 The encoded LDAPMessage PDUs are mapped directly onto the [TCP]
\r
2283 bytestream using the BER-based encoding described in Section 5.1. It
\r
2284 is recommended that server implementations running over the TCP
\r
2285 provide a protocol listener on the Internet Assigned Numbers
\r
2286 Authority (IANA)-assigned LDAP port, 389 [PortReg]. Servers may
\r
2287 instead provide a listener on a different port number. Clients MUST
\r
2288 support contacting servers on any valid TCP port.
\r
2291 5.3. Termination of the LDAP session
\r
2293 Termination of the LDAP session is typically initiated by the client
\r
2294 sending an UnbindRequest (Section 4.3), or by the server sending a
\r
2295 Notice of Disconnection (Section 4.4.1). In these cases each protocol
\r
2296 peer gracefully terminates the LDAP session by ceasing exchanges at
\r
2297 the LDAP message layer, tearing down any SASL layer, tearing down any
\r
2298 TLS layer, and closing the transport connection.
\r
2300 A protocol peer may determine that the continuation of any
\r
2301 communication would be pernicious, and in this case may abruptly
\r
2302 terminate the session by ceasing communication and closing the
\r
2303 transport connection.
\r
2305 In either case, when the LDAP session is terminated, uncompleted
\r
2306 operations are handled as specified in Section 3.1.
\r
2309 6. Security Considerations
\r
2311 This version of the protocol provides facilities for simple
\r
2312 authentication using a cleartext password, as well as any [SASL]
\r
2313 mechanism. Installing SASL and/or TLS layers can provide integrity
\r
2314 and other data security services.
\r
2317 Sermersheim Internet-Draft - Expires April 2006 Page 40
\f\r
2318 Lightweight Directory Access Protocol Version 3
\r
2320 It is also permitted that the server can return its credentials to
\r
2321 the client, if it chooses to do so.
\r
2323 Use of cleartext password is strongly discouraged where the
\r
2324 underlying transport service cannot guarantee confidentiality and may
\r
2325 result in disclosure of the password to unauthorized parties.
\r
2327 Servers are encouraged to prevent directory modifications by clients
\r
2328 that have authenticated anonymously [AuthMeth].
\r
2330 Security considerations for authentication methods, SASL mechanisms,
\r
2331 and TLS are described in [AuthMeth].
\r
2333 It should be noted that SASL authentication exchanges do not provide
\r
2334 data confidentiality nor integrity protection for the version or name
\r
2335 fields of the BindRequest nor the resultCode, diagnosticMessage, or
\r
2336 referral fields of the BindResponse nor of any information contained
\r
2337 in controls attached to Bind requests or responses. Thus information
\r
2338 contained in these fields SHOULD NOT be relied on unless otherwise
\r
2339 protected (such as by establishing protections at the transport
\r
2342 Implementors should note that various security factors, including
\r
2343 authentication and authorization information and data security
\r
2344 services may change during the course of the LDAP session, or even
\r
2345 during the performance of a particular operation. For instance,
\r
2346 credentials could expire, authorization identities or access controls
\r
2347 could change, or the underlying security layer(s) could be replaced
\r
2348 or terminated. Implementations should be robust in the handling of
\r
2349 changing security factors.
\r
2350 In some cases, it may be appropriate to continue the operation even
\r
2351 in light of security factor changes. For instance, it may be
\r
2352 appropriate to continue an Abandon operation regardless of the
\r
2353 change, or to continue an operation when the change upgraded (or
\r
2354 maintained) the security factor. In other cases, it may be
\r
2355 appropriate to fail, or alter the processing of the operation. For
\r
2356 instance, if confidential protections were removed, it would be
\r
2357 appropriate to either fail a request to return sensitive data, or
\r
2358 minimally, to exclude the return of sensitive data.
\r
2360 Implementations which cache attributes and entries obtained via LDAP
\r
2361 MUST ensure that access controls are maintained if that information
\r
2362 is to be provided to multiple clients, since servers may have access
\r
2363 control policies which prevent the return of entries or attributes in
\r
2364 Search results except to particular authenticated clients. For
\r
2365 example, caches could serve result information only to the client
\r
2366 whose request caused it to be in the cache.
\r
2375 Sermersheim Internet-Draft - Expires April 2006 Page 41
\f\r
2376 Lightweight Directory Access Protocol Version 3
\r
2378 Servers may return referrals or Search result references which
\r
2379 redirect clients to peer servers. It is possible for a rogue
\r
2380 application to inject such referrals into the data stream in an
\r
2381 attempt to redirect a client to a rogue server. Clients are advised
\r
2382 to be aware of this, and possibly reject referrals when
\r
2383 confidentiality measures are not in place. Clients are advised to
\r
2384 reject referrals from the StartTLS operation.
\r
2386 The matchedDN and diagnosticMessage fields, as well as some
\r
2387 resultCode values (e.g., attributeOrValueExists and
\r
2388 entryAlreadyExists), could disclose the presence or absence of
\r
2389 specific data in the directory which is subject to access and other
\r
2390 administrative controls. Server implementations should restrict
\r
2391 access to protected information equally under both normal and error
\r
2394 Protocol peers MUST be prepared to handle invalid and arbitrary
\r
2395 length protocol encodings. Invalid protocol encodings include: BER
\r
2396 encoding exceptions, format string and UTF-8 encoding exceptions,
\r
2397 overflow exceptions, integer value exceptions, and binary mode on/off
\r
2398 flag exceptions. The LDAPv3 PROTOS [PROTOS-LDAP] test suite provides
\r
2399 excellent examples of these exceptions and test cases used to
\r
2402 In the event that a protocol peer senses an attack which in its
\r
2403 nature could cause damage due to further communication at any layer
\r
2404 in the LDAP session, the protocol peer should abruptly terminate the
\r
2405 LDAP session as described in Section 5.3.
\r
2408 7. Acknowledgements
\r
2410 This document is based on RFC 2251 by Mark Wahl, Tim Howes, and Steve
\r
2411 Kille. RFC 2251 was a product of the IETF ASID Working Group.
\r
2413 It is also based on RFC 2830 by Jeff Hodges, RL "Bob" Morgan, and
\r
2414 Mark Wahl. RFC 2830 was a product of the IETF LDAPEXT Working Group.
\r
2416 It is also based on RFC 3771 by Roger Harrison, and Kurt Zeilenga.
\r
2417 RFC 3771 was an individual submission to the IETF.
\r
2419 This document is a product of the IETF LDAPBIS Working Group.
\r
2420 Significant contributors of technical review and content include Kurt
\r
2421 Zeilenga, Steven Legg, and Hallvard Furuseth.
\r
2424 8. Normative References
\r
2426 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
\r
2427 Specifications: ABNF", draft-crocker-abnf-rfc2234bis-
\r
2428 xx.txt, (a work in progress).
\r
2433 Sermersheim Internet-Draft - Expires April 2006 Page 42
\f\r
2434 Lightweight Directory Access Protocol Version 3
\r
2436 [ASN.1] ITU-T Recommendation X.680 (07/2002) | ISO/IEC 8824-1:2002
\r
2437 "Information Technology - Abstract Syntax Notation One
\r
2438 (ASN.1): Specification of basic notation"
\r
2440 [AuthMeth] Harrison, R., "LDAP: Authentication Methods and Connection
\r
2441 Level Security Mechanisms", draft-ietf-ldapbis-authmeth-
\r
2442 xx.txt, (a work in progress).
\r
2444 [BER] ITU-T Rec. X.690 (07/2002) | ISO/IEC 8825-1:2002,
\r
2445 "Information technology - ASN.1 encoding rules:
\r
2446 Specification of Basic Encoding Rules (BER), Canonical
\r
2447 Encoding Rules (CER) and Distinguished Encoding Rules
\r
2450 [IP] Postel, J., "Internet Protocol", STD5 and RFC 791,
\r
2453 [ISO10646] Universal Multiple-Octet Coded Character Set (UCS) -
\r
2454 Architecture and Basic Multilingual Plane, ISO/IEC 10646-1
\r
2457 [Keyword] Bradner, S., "Key words for use in RFCs to Indicate
\r
2458 Requirement Levels", RFC 2119, March 1997.
\r
2460 [LDAPDN] Zeilenga, K., "LDAP: String Representation of
\r
2461 Distinguished Names", draft-ietf-ldapbis-dn-xx.txt, (a
\r
2462 work in progress).
\r
2464 [LDAPIANA] Zeilenga, K., "IANA Considerations for LDAP", draft-ietf-
\r
2465 ldapbis-bcp64-xx.txt, (a work in progress).
\r
2467 [LDAPURL] Smith, M., "LDAP: Uniform Resource Locator", draft-ietf-
\r
2468 ldapbis-url-xx.txt, (a work in progress).
\r
2470 [Models] Zeilenga, K., "LDAP: Directory Information Models", draft-
\r
2471 ietf-ldapbis-models-xx.txt (a work in progress).
\r
2473 [Roadmap] Zeilenga, K., "LDAP: Technical Specification Road Map",
\r
2474 draft-ietf-ldapbis-roadmap-xx.txt (a work in progress).
\r
2476 [SASL] Melnikov, A., "Simple Authentication and Security Layer",
\r
2477 draft-ietf-sasl-rfc2222bis-xx.txt (a work in progress).
\r
2479 [SASLPrep] Zeilenga, K., "Stringprep profile for user names and
\r
2480 passwords", draft-ietf-sasl-saslprep-xx.txt, (a work in
\r
2483 [StringPrep] Hoffman P. and M. Blanchet, "Preparation of
\r
2484 Internationalized Strings ('stringprep')", draft-hoffman-
\r
2485 rfc3454bis-xx.txt, a work in progress.
\r
2487 [Syntaxes] Legg, S., and K. Dally, "LDAP: Syntaxes and Matching
\r
2488 Rules", draft-ietf-ldapbis-syntaxes-xx.txt, (a work in
\r
2491 Sermersheim Internet-Draft - Expires April 2006 Page 43
\f\r
2492 Lightweight Directory Access Protocol Version 3
\r
2495 [TCP] Postel, J., "Transmission Control Protocol", STD7 and RFC
\r
2496 793, September 1981
\r
2498 [TLS] Dierks, T. and C. Allen. "The TLS Protocol Version 1.1",
\r
2499 draft-ietf-tls-rfc2246-bis-xx.txt, a work in progress.
\r
2501 [Unicode] The Unicode Consortium, "The Unicode Standard, Version
\r
2502 3.2.0" is defined by "The Unicode Standard, Version 3.0"
\r
2503 (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5),
\r
2504 as amended by the "Unicode Standard Annex #27: Unicode
\r
2505 3.1" (http://www.unicode.org/reports/tr27/) and by the
\r
2506 "Unicode Standard Annex #28: Unicode 3.2"
\r
2507 (http://www.unicode.org/reports/tr28/).
\r
2509 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
\r
2510 Resource Identifiers (URI): Generic Syntax", RFC 2396,
\r
2513 [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
\r
2514 10646", STD63 and RFC3629, November 2003.
\r
2516 [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts,
\r
2517 Models and Service", 1993.
\r
2519 [X.501] ITU-T Rec. X.501, "The Directory: Models", 1993.
\r
2521 [X.511] ITU-T Rec. X.511, "The Directory: Abstract Service
\r
2522 Definition", 1993.
\r
2525 9. Informative References
\r
2527 [Glossary] The Unicode Consortium, "Unicode Glossary",
\r
2528 <http://www.unicode.org/glossary/>.
\r
2530 [CharModel] Whistler, K. and M. Davis, "Unicode Technical Report
\r
2531 #17, Character Encoding Model", UTR17,
\r
2532 <http://www.unicode.org/unicode/reports/tr17/>, August
\r
2535 [PROTOS-LDAP] University of Oulu, "PROTOS Test-Suite: c06-ldapv3"
\r
2536 <http://www.ee.oulu.fi/research/ouspg/protos/testing/c06/l
\r
2539 [PortReg] IANA, "Port Numbers",
\r
2540 http://www.iana.org/assignments/port-numbers
\r
2543 10. IANA Considerations
\r
2549 Sermersheim Internet-Draft - Expires April 2006 Page 44
\f\r
2550 Lightweight Directory Access Protocol Version 3
\r
2552 It is requested that the Internet Assigned Numbers Authority (IANA)
\r
2553 update the LDAP result code registry to indicate that this document
\r
2554 provides the definitive technical specification for result codes 0-
\r
2555 36, 48-54, 64-70, 80-90. It is also noted that one resultCode value
\r
2556 (strongAuthRequired) has been renamed (to strongerAuthRequired).
\r
2558 It is requested that the IANA update the LDAP Protocol Mechanism
\r
2559 registry to indicate that this document and [AuthMeth] provides the
\r
2560 definitive technical specification for the StartTLS
\r
2561 (1.3.6.1.4.1.1466.20037) Extended operation.
\r
2563 It is requested that the IANA update the occurrence of "RFC XXXX" in
\r
2564 this section and Appendix B with this RFC number at publication.
\r
2566 It is requested that IANA assign upon Standards Action an LDAP Object
\r
2567 Identifier [LDAPIANA] to identify the ASN.1 module defined in this
\r
2570 Subject: Request for LDAP Object Identifier Registration
\r
2571 Person & email address to contact for further information:
\r
2572 Jim Sermersheim <jimse@novell.com>
\r
2573 Specification: RFC XXXX
\r
2574 Author/Change Controller: IESG
\r
2576 Identifies the LDAP ASN.1 module
\r
2578 [[Note to RFC Editor: please replace the occurrence of <IANA-
\r
2579 ASSIGNED-DIRECTORY-NUMBER> in Appendix B with the IANA assigned
\r
2583 11. Editor's Address
\r
2587 1800 South Novell Place
\r
2588 Provo, Utah 84606, USA
\r
2607 Sermersheim Internet-Draft - Expires April 2006 Page 45
\f\r
2608 Lightweight Directory Access Protocol Version 3
\r
2610 Appendix A. LDAP Result Codes
\r
2612 This normative appendix details additional considerations regarding
\r
2613 LDAP result codes and provides a brief, general description of each
\r
2614 LDAP result code enumerated in Section 4.1.9.
\r
2616 Additional result codes MAY be defined for use with extensions
\r
2617 [LDAPIANA]. Client implementations SHALL treat any result code which
\r
2618 they do not recognize as an unknown error condition.
\r
2620 The descriptions provided here do not fully account for result code
\r
2621 substitutions used to prevent unauthorized disclosures (such as
\r
2622 substitution of noSuchObject for insufficientAccessRights, or
\r
2623 invalidCredentials for insufficientAccessRights).
\r
2626 A.1. Non-Error Result Codes
\r
2628 These result codes (called "non-error" result codes) do not indicate
\r
2629 an error condition:
\r
2631 compareFalse (5),
\r
2633 referral (10), and
\r
2634 saslBindInProgress (14).
\r
2636 The success, compareTrue, and compareFalse result codes indicate
\r
2637 successful completion (and, hence, are referred to as "successful"
\r
2640 The referral and saslBindInProgress result codes indicate the client
\r
2641 needs to take additional action to complete the operation.
\r
2644 A.2. Result Codes
\r
2646 Existing LDAP result codes are described as follows:
\r
2649 Indicates the successful completion of an operation. Note:
\r
2650 this code is not used with the Compare operation. See
\r
2651 compareFalse (5) and compareTrue (6).
\r
2653 operationsError (1)
\r
2654 Indicates that the operation is not properly sequenced with
\r
2655 relation to other operations (of same or different type).
\r
2657 For example, this code is returned if the client attempts to
\r
2658 StartTLS [TLS] while there are other uncompleted operations
\r
2659 or if a TLS layer was already installed.
\r
2661 protocolError (2)
\r
2662 Indicates the server received data which is not well-formed.
\r
2665 Sermersheim Internet-Draft - Expires April 2006 Page 46
\f\r
2666 Lightweight Directory Access Protocol Version 3
\r
2668 For Bind operation only, this code is also used to indicate
\r
2669 that the server does not support the requested protocol
\r
2672 For Extended operations only, this code is also used to
\r
2673 indicate that the server does not support (by design or
\r
2674 configuration) the Extended operation associated with the
\r
2677 For request operations specifying multiple controls, this may
\r
2678 be used to indicate that the server cannot ignore the order
\r
2679 of the controls as specified, or that the combination of the
\r
2680 specified controls is invalid or unspecified.
\r
2682 timeLimitExceeded (3)
\r
2683 Indicates that the time limit specified by the client was
\r
2684 exceeded before the operation could be completed.
\r
2686 sizeLimitExceeded (4)
\r
2687 Indicates that the size limit specified by the client was
\r
2688 exceeded before the operation could be completed.
\r
2691 Indicates that the Compare operation has successfully
\r
2692 completed and the assertion has evaluated to FALSE or
\r
2696 Indicates that the Compare operation has successfully
\r
2697 completed and the assertion has evaluated to TRUE.
\r
2699 authMethodNotSupported (7)
\r
2700 Indicates that the authentication method or mechanism is not
\r
2703 strongerAuthRequired (8)
\r
2704 Indicates the server requires strong(er) authentication in
\r
2705 order to complete the operation.
\r
2707 When used with the Notice of Disconnection operation, this
\r
2708 code indicates that the server has detected that an
\r
2709 established security association between the client and
\r
2710 server has unexpectedly failed or been compromised.
\r
2713 Indicates that a referral needs to be chased to complete the
\r
2714 operation (see Section 4.1.10).
\r
2716 adminLimitExceeded (11)
\r
2717 Indicates that an administrative limit has been exceeded.
\r
2719 unavailableCriticalExtension (12)
\r
2720 Indicates a critical control is unrecognized (see Section
\r
2723 Sermersheim Internet-Draft - Expires April 2006 Page 47
\f\r
2724 Lightweight Directory Access Protocol Version 3
\r
2727 confidentialityRequired (13)
\r
2728 Indicates that data confidentiality protections are required.
\r
2730 saslBindInProgress (14)
\r
2731 Indicates the server requires the client to send a new bind
\r
2732 request, with the same SASL mechanism, to continue the
\r
2733 authentication process (see Section 4.2).
\r
2735 noSuchAttribute (16)
\r
2736 Indicates that the named entry does not contain the specified
\r
2737 attribute or attribute value.
\r
2739 undefinedAttributeType (17)
\r
2740 Indicates that a request field contains an unrecognized
\r
2741 attribute description.
\r
2743 inappropriateMatching (18)
\r
2744 Indicates that an attempt was made (e.g. in an assertion) to
\r
2745 use a matching rule not defined for the attribute type
\r
2748 constraintViolation (19)
\r
2749 Indicates that the client supplied an attribute value which
\r
2750 does not conform to the constraints placed upon it by the
\r
2753 For example, this code is returned when multiple values are
\r
2754 supplied to an attribute which has a SINGLE-VALUE constraint.
\r
2756 attributeOrValueExists (20)
\r
2757 Indicates that the client supplied an attribute or value to
\r
2758 be added to an entry, but the attribute or value already
\r
2761 invalidAttributeSyntax (21)
\r
2762 Indicates that a purported attribute value does not conform
\r
2763 to the syntax of the attribute.
\r
2765 noSuchObject (32)
\r
2766 Indicates that the object does not exist in the DIT.
\r
2768 aliasProblem (33)
\r
2769 Indicates that an alias problem has occurred. For example,
\r
2770 the code may used to indicate an alias has been dereferenced
\r
2771 which names no object.
\r
2773 invalidDNSyntax (34)
\r
2774 Indicates that an LDAPDN or RelativeLDAPDN field (e.g. search
\r
2775 base, target entry, ModifyDN newrdn, etc.) of a request does
\r
2776 not conform to the required syntax or contains attribute
\r
2777 values which do not conform to the syntax of the attribute's
\r
2781 Sermersheim Internet-Draft - Expires April 2006 Page 48
\f\r
2782 Lightweight Directory Access Protocol Version 3
\r
2785 aliasDereferencingProblem (36)
\r
2786 Indicates that a problem occurred while dereferencing an
\r
2787 alias. Typically an alias was encountered in a situation
\r
2788 where it was not allowed or where access was denied.
\r
2790 inappropriateAuthentication (48)
\r
2791 Indicates the server requires the client which had attempted
\r
2792 to bind anonymously or without supplying credentials to
\r
2793 provide some form of credentials.
\r
2795 invalidCredentials (49)
\r
2796 Indicates that the provided credentials (e.g. the user's name
\r
2797 and password) are invalid.
\r
2799 insufficientAccessRights (50)
\r
2800 Indicates that the client does not have sufficient access
\r
2801 rights to perform the operation.
\r
2804 Indicates that the server is too busy to service the
\r
2808 Indicates that the server is shutting down or a subsystem
\r
2809 necessary to complete the operation is offline.
\r
2811 unwillingToPerform (53)
\r
2812 Indicates that the server is unwilling to perform the
\r
2816 Indicates that the server has detected an internal loop (e.g.
\r
2817 while dereferencing aliases or chaining an operation).
\r
2819 namingViolation (64)
\r
2820 Indicates that the entry's name violates naming restrictions.
\r
2822 objectClassViolation (65)
\r
2823 Indicates that the entry violates object class restrictions.
\r
2825 notAllowedOnNonLeaf (66)
\r
2826 Indicates that the operation is inappropriately acting upon a
\r
2829 notAllowedOnRDN (67)
\r
2830 Indicates that the operation is inappropriately attempting to
\r
2831 remove a value which forms the entry's relative distinguished
\r
2834 entryAlreadyExists (68)
\r
2835 Indicates that the request cannot be fulfilled (added, moved,
\r
2836 or renamed) as the target entry already exists.
\r
2839 Sermersheim Internet-Draft - Expires April 2006 Page 49
\f\r
2840 Lightweight Directory Access Protocol Version 3
\r
2843 objectClassModsProhibited (69)
\r
2844 Indicates that an attempt to modify the object class(es) of
\r
2845 an entry's 'objectClass' attribute is prohibited.
\r
2847 For example, this code is returned when a client attempts to
\r
2848 modify the structural object class of an entry.
\r
2850 affectsMultipleDSAs (71)
\r
2851 Indicates that the operation cannot be performed as it would
\r
2852 affect multiple servers (DSAs).
\r
2855 Indicates the server has encountered an internal error.
\r
2897 Sermersheim Internet-Draft - Expires April 2006 Page 50
\f\r
2898 Lightweight Directory Access Protocol Version 3
\r
2900 Appendix B. Complete ASN.1 Definition
\r
2902 This appendix is normative.
\r
2904 Lightweight-Directory-Access-Protocol-V3 {1 3 6 1 1 <IANA-
\r
2905 ASSIGNED-DIRECTORY-NUMBER>}
\r
2906 -- Copyright (C) The Internet Society (2005). This version of
\r
2907 -- this ASN.1 module is part of RFC XXXX; see the RFC itself
\r
2908 -- for full legal notices.
\r
2911 EXTENSIBILITY IMPLIED ::=
\r
2915 LDAPMessage ::= SEQUENCE {
\r
2916 messageID MessageID,
\r
2917 protocolOp CHOICE {
\r
2918 bindRequest BindRequest,
\r
2919 bindResponse BindResponse,
\r
2920 unbindRequest UnbindRequest,
\r
2921 searchRequest SearchRequest,
\r
2922 searchResEntry SearchResultEntry,
\r
2923 searchResDone SearchResultDone,
\r
2924 searchResRef SearchResultReference,
\r
2925 modifyRequest ModifyRequest,
\r
2926 modifyResponse ModifyResponse,
\r
2927 addRequest AddRequest,
\r
2928 addResponse AddResponse,
\r
2929 delRequest DelRequest,
\r
2930 delResponse DelResponse,
\r
2931 modDNRequest ModifyDNRequest,
\r
2932 modDNResponse ModifyDNResponse,
\r
2933 compareRequest CompareRequest,
\r
2934 compareResponse CompareResponse,
\r
2935 abandonRequest AbandonRequest,
\r
2936 extendedReq ExtendedRequest,
\r
2937 extendedResp ExtendedResponse,
\r
2939 intermediateResponse IntermediateResponse },
\r
2940 controls [0] Controls OPTIONAL }
\r
2942 MessageID ::= INTEGER (0 .. maxInt)
\r
2944 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
\r
2946 LDAPString ::= OCTET STRING -- UTF-8 encoded,
\r
2947 -- [ISO10646] characters
\r
2949 LDAPOID ::= OCTET STRING -- Constrained to <numericoid> [Models]
\r
2951 LDAPDN ::= LDAPString -- Constrained to <distinguishedName>
\r
2955 Sermersheim Internet-Draft - Expires April 2006 Page 51
\f\r
2956 Lightweight Directory Access Protocol Version 3
\r
2958 RelativeLDAPDN ::= LDAPString -- Constrained to <name-component>
\r
2961 AttributeDescription ::= LDAPString
\r
2962 -- Constrained to <attributedescription>
\r
2965 AttributeValue ::= OCTET STRING
\r
2967 AttributeValueAssertion ::= SEQUENCE {
\r
2968 attributeDesc AttributeDescription,
\r
2969 assertionValue AssertionValue }
\r
2971 AssertionValue ::= OCTET STRING
\r
2973 PartialAttribute ::= SEQUENCE {
\r
2974 type AttributeDescription,
\r
2975 vals SET OF value AttributeValue }
\r
2977 Attribute ::= PartialAttribute(WITH COMPONENTS {
\r
2979 vals (SIZE(1..MAX))})
\r
2981 MatchingRuleId ::= LDAPString
\r
3013 Sermersheim Internet-Draft - Expires April 2006 Page 52
\f\r
3014 Lightweight Directory Access Protocol Version 3
\r
3016 LDAPResult ::= SEQUENCE {
\r
3017 resultCode ENUMERATED {
\r
3019 operationsError (1),
\r
3020 protocolError (2),
\r
3021 timeLimitExceeded (3),
\r
3022 sizeLimitExceeded (4),
\r
3023 compareFalse (5),
\r
3025 authMethodNotSupported (7),
\r
3026 strongerAuthRequired (8),
\r
3029 adminLimitExceeded (11),
\r
3030 unavailableCriticalExtension (12),
\r
3031 confidentialityRequired (13),
\r
3032 saslBindInProgress (14),
\r
3033 noSuchAttribute (16),
\r
3034 undefinedAttributeType (17),
\r
3035 inappropriateMatching (18),
\r
3036 constraintViolation (19),
\r
3037 attributeOrValueExists (20),
\r
3038 invalidAttributeSyntax (21),
\r
3039 -- 22-31 unused --
\r
3040 noSuchObject (32),
\r
3041 aliasProblem (33),
\r
3042 invalidDNSyntax (34),
\r
3043 -- 35 reserved for undefined isLeaf --
\r
3044 aliasDereferencingProblem (36),
\r
3045 -- 37-47 unused --
\r
3046 inappropriateAuthentication (48),
\r
3047 invalidCredentials (49),
\r
3048 insufficientAccessRights (50),
\r
3050 unavailable (52),
\r
3051 unwillingToPerform (53),
\r
3053 -- 55-63 unused --
\r
3054 namingViolation (64),
\r
3055 objectClassViolation (65),
\r
3056 notAllowedOnNonLeaf (66),
\r
3057 notAllowedOnRDN (67),
\r
3058 entryAlreadyExists (68),
\r
3059 objectClassModsProhibited (69),
\r
3060 -- 70 reserved for CLDAP --
\r
3061 affectsMultipleDSAs (71),
\r
3062 -- 72-79 unused --
\r
3065 matchedDN LDAPDN,
\r
3066 diagnosticMessage LDAPString,
\r
3067 referral [3] Referral OPTIONAL }
\r
3069 Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI
\r
3071 Sermersheim Internet-Draft - Expires April 2006 Page 53
\f\r
3072 Lightweight Directory Access Protocol Version 3
\r
3075 URI ::= LDAPString -- limited to characters permitted in
\r
3078 Controls ::= SEQUENCE OF control Control
\r
3080 Control ::= SEQUENCE {
\r
3081 controlType LDAPOID,
\r
3082 criticality BOOLEAN DEFAULT FALSE,
\r
3083 controlValue OCTET STRING OPTIONAL }
\r
3085 BindRequest ::= [APPLICATION 0] SEQUENCE {
\r
3086 version INTEGER (1 .. 127),
\r
3088 authentication AuthenticationChoice }
\r
3090 AuthenticationChoice ::= CHOICE {
\r
3091 simple [0] OCTET STRING,
\r
3092 -- 1 and 2 reserved
\r
3093 sasl [3] SaslCredentials,
\r
3096 SaslCredentials ::= SEQUENCE {
\r
3097 mechanism LDAPString,
\r
3098 credentials OCTET STRING OPTIONAL }
\r
3100 BindResponse ::= [APPLICATION 1] SEQUENCE {
\r
3101 COMPONENTS OF LDAPResult,
\r
3102 serverSaslCreds [7] OCTET STRING OPTIONAL }
\r
3104 UnbindRequest ::= [APPLICATION 2] NULL
\r
3106 SearchRequest ::= [APPLICATION 3] SEQUENCE {
\r
3107 baseObject LDAPDN,
\r
3108 scope ENUMERATED {
\r
3111 wholeSubtree (2),
\r
3113 derefAliases ENUMERATED {
\r
3114 neverDerefAliases (0),
\r
3115 derefInSearching (1),
\r
3116 derefFindingBaseObj (2),
\r
3117 derefAlways (3) },
\r
3118 sizeLimit INTEGER (0 .. maxInt),
\r
3119 timeLimit INTEGER (0 .. maxInt),
\r
3120 typesOnly BOOLEAN,
\r
3122 attributes AttributeSelection }
\r
3124 AttributeSelection ::= SEQUENCE OF selector LDAPString
\r
3125 -- The LDAPString is constrained to
\r
3126 -- <attributeSelector> in Section 4.5.1.7
\r
3129 Sermersheim Internet-Draft - Expires April 2006 Page 54
\f\r
3130 Lightweight Directory Access Protocol Version 3
\r
3132 Filter ::= CHOICE {
\r
3133 and [0] SET SIZE (1..MAX) OF filter Filter,
\r
3134 or [1] SET SIZE (1..MAX) OF filter Filter,
\r
3136 equalityMatch [3] AttributeValueAssertion,
\r
3137 substrings [4] SubstringFilter,
\r
3138 greaterOrEqual [5] AttributeValueAssertion,
\r
3139 lessOrEqual [6] AttributeValueAssertion,
\r
3140 present [7] AttributeDescription,
\r
3141 approxMatch [8] AttributeValueAssertion,
\r
3142 extensibleMatch [9] MatchingRuleAssertion,
\r
3145 SubstringFilter ::= SEQUENCE {
\r
3146 type AttributeDescription,
\r
3147 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE {
\r
3148 initial [0] AssertionValue, -- can occur at most once
\r
3149 any [1] AssertionValue,
\r
3150 final [2] AssertionValue } -- can occur at most once
\r
3153 MatchingRuleAssertion ::= SEQUENCE {
\r
3154 matchingRule [1] MatchingRuleId OPTIONAL,
\r
3155 type [2] AttributeDescription OPTIONAL,
\r
3156 matchValue [3] AssertionValue,
\r
3157 dnAttributes [4] BOOLEAN DEFAULT FALSE }
\r
3159 SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
\r
3160 objectName LDAPDN,
\r
3161 attributes PartialAttributeList }
\r
3163 PartialAttributeList ::= SEQUENCE OF
\r
3164 partialAttribute PartialAttribute
\r
3166 SearchResultReference ::= [APPLICATION 19] SEQUENCE
\r
3167 SIZE (1..MAX) OF uri URI
\r
3169 SearchResultDone ::= [APPLICATION 5] LDAPResult
\r
3171 ModifyRequest ::= [APPLICATION 6] SEQUENCE {
\r
3173 changes SEQUENCE OF change SEQUENCE {
\r
3174 operation ENUMERATED {
\r
3179 modification PartialAttribute } }
\r
3181 ModifyResponse ::= [APPLICATION 7] LDAPResult
\r
3183 AddRequest ::= [APPLICATION 8] SEQUENCE {
\r
3185 attributes AttributeList }
\r
3187 Sermersheim Internet-Draft - Expires April 2006 Page 55
\f\r
3188 Lightweight Directory Access Protocol Version 3
\r
3191 AttributeList ::= SEQUENCE OF attribute Attribute
\r
3193 AddResponse ::= [APPLICATION 9] LDAPResult
\r
3195 DelRequest ::= [APPLICATION 10] LDAPDN
\r
3197 DelResponse ::= [APPLICATION 11] LDAPResult
\r
3199 ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
\r
3201 newrdn RelativeLDAPDN,
\r
3202 deleteoldrdn BOOLEAN,
\r
3203 newSuperior [0] LDAPDN OPTIONAL }
\r
3205 ModifyDNResponse ::= [APPLICATION 13] LDAPResult
\r
3207 CompareRequest ::= [APPLICATION 14] SEQUENCE {
\r
3209 ava AttributeValueAssertion }
\r
3211 CompareResponse ::= [APPLICATION 15] LDAPResult
\r
3213 AbandonRequest ::= [APPLICATION 16] MessageID
\r
3215 ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
\r
3216 requestName [0] LDAPOID,
\r
3217 requestValue [1] OCTET STRING OPTIONAL }
\r
3219 ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
\r
3220 COMPONENTS OF LDAPResult,
\r
3221 responseName [10] LDAPOID OPTIONAL,
\r
3222 responseValue [11] OCTET STRING OPTIONAL }
\r
3224 IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
\r
3225 responseName [0] LDAPOID OPTIONAL,
\r
3226 responseValue [1] OCTET STRING OPTIONAL }
\r
3245 Sermersheim Internet-Draft - Expires April 2006 Page 56
\f\r
3246 Lightweight Directory Access Protocol Version 3
\r
3248 Appendix C. Changes
\r
3250 This appendix is non-normative.
\r
3252 This appendix summarizes substantive changes made to RFC 2251, RFC
\r
3253 2830, and RFC 3771.
\r
3256 C.1. Changes made to RFC 2251:
\r
3258 This section summarizes the substantive changes made to Sections 1,
\r
3259 2, 3.1, and 4 through the remainder of RFC 2251. Readers should
\r
3260 consult [Models] and [AuthMeth] for summaries of changes to other
\r
3264 C.1.1. Section 1 (Status of this Memo)
\r
3266 - Removed IESG note. Post publication of RFC 2251, mandatory LDAP
\r
3267 authentication mechanisms have been standardized which are
\r
3268 sufficient to remove this note. See [AuthMeth] for authentication
\r
3272 C.1.2. Section 3.1 (Protocol Model) and others
\r
3274 - Removed notes giving history between LDAP v1, v2 and v3. Instead,
\r
3275 added sufficient language so that this document can stand on its
\r
3279 C.1.3. Section 4 (Elements of Protocol)
\r
3281 - Clarified where the extensibility features of ASN.1 apply to the
\r
3282 protocol. This change affected various ASN.1 types by the
\r
3283 inclusion of ellipses (...) to certain elements.
\r
3284 - Removed the requirement that servers which implement version 3 or
\r
3285 later MUST provide the 'supportedLDAPVersion' attribute. This
\r
3286 statement provided no interoperability advantages.
\r
3289 C.1.4. Section 4.1.1 (Message Envelope)
\r
3291 - There was a mandatory requirement for the server to return a
\r
3292 Notice of Disconnection and drop the transport connection when a
\r
3293 PDU is malformed in a certain way. This has been updated such that
\r
3294 the server SHOULD return the Notice of Disconnection, and MUST
\r
3295 terminate the LDAP Session.
\r
3298 C.1.5. Section 4.1.1.1 (Message ID)
\r
3300 - Required that the messageID of requests MUST be non-zero as the
\r
3301 zero is reserved for Notice of Disconnection.
\r
3303 Sermersheim Internet-Draft - Expires April 2006 Page 57
\f\r
3304 Lightweight Directory Access Protocol Version 3
\r
3306 - Specified when it is and isn't appropriate to return an already
\r
3307 used message id. RFC 2251 accidentally imposed synchronous server
\r
3308 behavior in its wording of this.
\r
3311 C.1.6. Section 4.1.2 (String Types)
\r
3313 - Stated that LDAPOID is constrained to <numericoid> from [Models].
\r
3316 C.1.7. Section 4.1.5.1 (Binary Option) and others
\r
3318 - Removed the Binary Option from the specification. There are
\r
3319 numerous interoperability problems associated with this method of
\r
3320 alternate attribute type encoding. Work to specify a suitable
\r
3321 replacement is ongoing.
\r
3324 C.1.8. Section 4.1.8 (Attribute)
\r
3326 - Combined the definitions of PartialAttribute and Attribute here,
\r
3327 and defined Attribute in terms of PartialAttribute.
\r
3330 C.1.9. Section 4.1.10 (Result Message)
\r
3332 - Renamed "errorMessage" to "diagnosticMessage" as it is allowed to
\r
3333 be sent for non-error results.
\r
3334 - Moved some language into Appendix A, and refer the reader there.
\r
3335 - Allowed matchedDN to be present for other result codes than those
\r
3336 listed in RFC 2251.
\r
3337 - renamed the code "strongAuthRequired" to "strongerAuthRequired" to
\r
3338 clarify that this code may often be returned to indicate that a
\r
3339 stronger authentication is needed to perform a given operation.
\r
3342 C.1.10. Section 4.1.11 (Referral)
\r
3344 - Defined referrals in terms of URIs rather than URLs.
\r
3345 - Removed the requirement that all referral URIs MUST be equally
\r
3346 capable of progressing the operation. The statement was ambiguous
\r
3347 and provided no instructions on how to carry it out.
\r
3348 - Added the requirement that clients MUST NOT loop between servers.
\r
3349 - Clarified the instructions for using LDAPURLs in referrals, and in
\r
3350 doing so added a recommendation that the scope part be present.
\r
3351 - Removed imperatives which required clients to use URLs in specific
\r
3352 ways to progress an operation. These did nothing for
\r
3353 interoperability.
\r
3356 C.1.11. Section 4.1.12 (Controls)
\r
3358 - Specified how control values defined in terms of ASN.1 are to be
\r
3361 Sermersheim Internet-Draft - Expires April 2006 Page 58
\f\r
3362 Lightweight Directory Access Protocol Version 3
\r
3364 - Noted that the criticality field is only applied to request
\r
3365 messages (except UnbindRequest), and must be ignored when present
\r
3366 on response messages and UnbindRequest.
\r
3367 - Specified that non-critical controls may be ignored at the
\r
3368 server's discretion. There was confusion in the original wording
\r
3369 which led some to believe that recognized controls may not be
\r
3370 ignored as long as they were associated with a proper request.
\r
3371 - Added language regarding combinations of controls and the ordering
\r
3372 of controls on a message.
\r
3373 - Specified that when the semantics of the combination of controls
\r
3374 is undefined or unknown, it results in a protocolError.
\r
3375 - Changed "The server MUST be prepared" to "Implementations MUST be
\r
3376 prepared" in the eighth paragraph to reflect that both client and
\r
3377 server implementations must be able to handle this (as both parse
\r
3381 C.1.12. Section 4.2 (Bind Operation)
\r
3383 - Mandated that servers return protocolError when the version is not
\r
3385 - Disambiguated behavior when the simple authentication is used, the
\r
3386 name is empty and the password is non-empty.
\r
3387 - Required servers to not dereference aliases for Bind. This was
\r
3388 added for consistency with other operations and to help ensure
\r
3389 data consistency.
\r
3390 - Required that textual passwords be transferred as UTF-8 encoded
\r
3391 Unicode, and added recommendations on string preparation. This was
\r
3392 to help ensure interoperability of passwords being sent from
\r
3393 different clients.
\r
3396 C.1.13. Section 4.2.1 (Sequencing of the Bind Request)
\r
3398 - This section was largely reorganized for readability and language
\r
3399 was added to clarify the authentication state of failed and
\r
3400 abandoned Bind operations.
\r
3401 - Removed: "If a SASL transfer encryption or integrity mechanism has
\r
3402 been negotiated, that mechanism does not support the changing of
\r
3403 credentials from one identity to another, then the client MUST
\r
3404 instead establish a new connection."
\r
3405 If there are dependencies between multiple negotiations of a
\r
3406 particular SASL mechanism, the technical specification for that
\r
3407 SASL mechanism details how applications are to deal with them.
\r
3408 LDAP should not require any special handling.
\r
3409 - Dropped MUST imperative in paragraph 3 to align with [Keywords].
\r
3410 - Mandated that clients not send non-Bind operations while a Bind is
\r
3411 in progress, and suggested that servers not process them if they
\r
3412 are received. This is needed to ensure proper sequencing of the
\r
3413 Bind in relationship to other operations.
\r
3419 Sermersheim Internet-Draft - Expires April 2006 Page 59
\f\r
3420 Lightweight Directory Access Protocol Version 3
\r
3422 C.1.14. Section 4.2.3 (Bind Response)
\r
3424 - Moved most error-related text to Appendix A, and added text
\r
3425 regarding certain errors used in conjunction with the Bind
\r
3427 - Prohibited the server from specifying serverSaslCreds when not
\r
3431 C.1.15. Section 4.3 (Unbind Operation)
\r
3433 - Specified that both peers are to cease transmission and terminate
\r
3434 the LDAP session for the Unbind operation.
\r
3437 C.1.16. Section 4.4 (Unsolicited Notification)
\r
3439 - Added instructions for future specifications of Unsolicited
\r
3443 C.1.17. Section 4.5.1 (Search Request)
\r
3445 - SearchRequest attributes is now defined as an AttributeSelection
\r
3446 type rather than AttributeDescriptionList, and an ABNF is
\r
3448 - SearchRequest attributes may contain duplicate attribute
\r
3449 descriptions. This was previously prohibited. Now servers are
\r
3450 instructed to ignore subsequent names when they are duplicated.
\r
3451 This was relaxed in order to allow different short names and also
\r
3452 OIDs to be requested for an attribute.
\r
3453 - The present search filter now evaluates to Undefined when the
\r
3454 specified attribute is not known to the server. It used to
\r
3455 evaluate to FALSE, which caused behavior inconsistent with what
\r
3456 most would expect, especially when the not operator was used.
\r
3457 - The Filter choice SubstringFilter substrings type is now defined
\r
3458 with a lower bound of 1.
\r
3459 - The SubstringFilter substrings 'initial, 'any', and 'final' types
\r
3460 are now AssertionValue rather than LDAPString. Also, added
\r
3461 imperatives stating that 'initial' (if present) must be listed
\r
3462 first, and 'final' (if present) must be listed last.
\r
3463 - Disambiguated the semantics of the derefAliases choices. There was
\r
3464 question as to whether derefInSearching applied to the base object
\r
3465 in a wholeSubtree Search.
\r
3466 - Added instructions for equalityMatch, substrings, greaterOrEqual,
\r
3467 lessOrEqual, and approxMatch.
\r
3470 C.1.18. Section 4.5.2 (Search Result)
\r
3472 - Recommended that servers not use attribute short names when it
\r
3473 knows they are ambiguous or may cause interoperability problems.
\r
3474 - Removed all mention of ExtendedResponse due to lack of
\r
3477 Sermersheim Internet-Draft - Expires April 2006 Page 60
\f\r
3478 Lightweight Directory Access Protocol Version 3
\r
3482 C.1.19. Section 4.5.3 (Continuation References in the Search Result)
\r
3484 - Made changes similar to those made to Section 4.1.11.
\r
3487 C.1.20. Section 4.5.3.1 (Example)
\r
3489 - Fixed examples to adhere to changes made to Section 4.5.3.
\r
3492 C.1.21. Section 4.6 (Modify Operation)
\r
3494 - Replaced AttributeTypeAndValues with Attribute as they are
\r
3496 - Specified the types of modification changes which might
\r
3497 temporarily violate schema. Some readers were under the impression
\r
3498 that any temporary schema violation was allowed.
\r
3501 C.1.22. Section 4.7 (Add Operation)
\r
3503 - Aligned Add operation with X.511 in that the attributes of the RDN
\r
3504 are used in conjunction with the listed attributes to create the
\r
3505 entry. Previously, Add required that the distinguished values be
\r
3506 present in the listed attributes.
\r
3507 - Removed requirement that the objectClass attribute MUST be
\r
3508 specified as some DSE types do not require this attribute.
\r
3509 Instead, generic wording was added, requiring the added entry to
\r
3510 adhere to the data model.
\r
3511 - Removed recommendation regarding placement of objects. This is
\r
3512 covered in the data model document.
\r
3515 C.1.23. Section 4.9 (Modify DN Operation)
\r
3517 - Required servers to not dereference aliases for Modify DN. This
\r
3518 was added for consistency with other operations and to help ensure
\r
3519 data consistency.
\r
3520 - Allow Modify DN to fail when moving between naming contexts.
\r
3521 - Specified what happens when the attributes of the newrdn are not
\r
3522 present on the entry.
\r
3525 C.1.24. Section 4.10 (Compare Operation)
\r
3527 - Specified that compareFalse means that the Compare took place and
\r
3528 the result is false. There was confusion which lead people to
\r
3529 believe that an Undefined match resulted in compareFalse.
\r
3530 - Required servers to not dereference aliases for Compare. This was
\r
3531 added for consistency with other operations and to help ensure
\r
3532 data consistency.
\r
3535 Sermersheim Internet-Draft - Expires April 2006 Page 61
\f\r
3536 Lightweight Directory Access Protocol Version 3
\r
3539 C.1.25. Section 4.11 (Abandon Operation)
\r
3541 - Explained that since Abandon returns no response, clients should
\r
3542 not use it if they need to know the outcome.
\r
3543 - Specified that Abandon and Unbind cannot be abandoned.
\r
3546 C.1.26. Section 4.12 (Extended Operation)
\r
3548 - Specified how values of Extended operations defined in terms of
\r
3549 ASN.1 are to be encoded.
\r
3550 - Added instructions on what Extended operation specifications
\r
3552 - Added a recommendation that servers advertise supported Extended
\r
3556 C.1.27. Section 5.2 (Transfer Protocols)
\r
3558 - Moved referral-specific instructions into referral-related
\r
3562 C.1.28. Section 7 (Security Considerations)
\r
3564 - Reworded notes regarding SASL not protecting certain aspects of
\r
3565 the LDAP Bind messages.
\r
3566 - Noted that Servers are encouraged to prevent directory
\r
3567 modifications by clients that have authenticated anonymously
\r
3569 - Added a note regarding the possibility of changes to security
\r
3570 factors (authentication, authorization, data confidentiality).
\r
3571 - Warned against following referrals that may have been injected in
\r
3573 - Noted that servers should protect information equally, whether in
\r
3574 an error condition or not, and mentioned specifically; matchedDN,
\r
3575 diagnosticMessage, and resultCodes.
\r
3576 - Added a note regarding malformed and long encodings.
\r
3579 C.1.29. Appendix A (Complete ASN.1 Definition)
\r
3581 - Added "EXTENSIBILITY IMPLIED" to ASN.1 definition.
\r
3582 - Removed AttributeType. It is not used.
\r
3585 C.2. Changes made to RFC 2830:
\r
3587 This section summarizes the substantive changes made to Sections of
\r
3588 RFC 2830. Readers should consult [AuthMeth] for summaries of changes
\r
3589 to other sections.
\r
3593 Sermersheim Internet-Draft - Expires April 2006 Page 62
\f\r
3594 Lightweight Directory Access Protocol Version 3
\r
3596 C.2.1. Section 2.3 (Response other than "success")
\r
3598 - Removed wording indicating that referrals can be returned from
\r
3600 - Removed requirement that only a narrow set of result codes can be
\r
3601 returned. Some result codes are required in certain scenarios, but
\r
3602 any other may be returned if appropriate.
\r
3603 - Removed requirement that the ExtendedResponse.responseName MUST be
\r
3604 present. There are circumstances where this is impossible, and
\r
3605 requiring this is at odds with language in Section 4.12.
\r
3608 C.2.1. Section 4 (Closing a TLS Connection)
\r
3610 - Reworded most of this section to align with definitions of the
\r
3611 LDAP protocol layers.
\r
3612 - Removed instructions on abrupt closure as this is covered in other
\r
3613 areas of the document (specifically, Section 5.3)
\r
3616 C.3. Changes made to RFC 3771:
\r
3618 - Rewrote to fit into this document. In general, semantics were
\r
3619 preserved. Supporting and background language seen as redundant
\r
3620 due to its presence in this document was omitted.
\r
3621 - Specified that Intermediate responses to a request may be of
\r
3622 different types, and one of the response types may be specified to
\r
3623 have no response value.
\r
3651 Sermersheim Internet-Draft - Expires April 2006 Page 63
\f\r
3652 Lightweight Directory Access Protocol Version 3
\r
3657 Intellectual Property Statement
\r
3659 The IETF takes no position regarding the validity or scope of any
\r
3660 Intellectual Property Rights or other rights that might be claimed to
\r
3661 pertain to the implementation or use of the technology described in
\r
3662 this document or the extent to which any license under such rights
\r
3663 might or might not be available; nor does it represent that it has
\r
3664 made any independent effort to identify any such rights. Information
\r
3665 on the procedures with respect to rights in RFC documents can be
\r
3666 found in BCP 78 and BCP 79.
\r
3668 Copies of IPR disclosures made to the IETF Secretariat and any
\r
3669 assurances of licenses to be made available, or the result of an
\r
3670 attempt made to obtain a general license or permission for the use of
\r
3671 such proprietary rights by implementers or users of this
\r
3672 specification can be obtained from the IETF on-line IPR repository at
\r
3673 http://www.ietf.org/ipr.
\r
3675 The IETF invites any interested party to bring to its attention any
\r
3676 copyrights, patents or patent applications, or other proprietary
\r
3677 rights that may cover technology that may be required to implement
\r
3678 this standard. Please address the information to the IETF at ietf-
\r
3681 Disclaimer of Validity
\r
3683 This document and the information contained herein are provided on an
\r
3684 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
\r
3685 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
\r
3686 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
\r
3687 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
\r
3688 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
\r
3689 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
\r
3691 Copyright Statement
\r
3693 Copyright (C) The Internet Society (2005).
\r
3695 This document is subject to the rights, licenses and restrictions
\r
3696 contained in BCP 78, and except as set forth therein, the authors
\r
3697 retain all their rights.
\r
3701 Funding for the RFC Editor function is currently provided by the
\r
3702 Internet Society.
\r
3709 Sermersheim Internet-Draft - Expires April 2006 Page 64
\f
projects / openldap / blob