]> git.sur5r.net Git - openldap/blob - doc/rfc/rfc4511.txt
Remove many (but not all) references to slurpd(8).
[openldap] / doc / rfc / rfc4511.txt
1
2
3
4
5
6
7 Network Working Group                                J. Sermersheim, Ed.
8 Request for Comments: 4511                                  Novell, Inc.
9 Obsoletes: 2251, 2830, 3771                                    June 2006
10 Category: Standards Track
11
12
13       Lightweight Directory Access Protocol (LDAP): The Protocol
14
15 Status of This Memo
16
17    This document specifies an Internet standards track protocol for the
18    Internet community, and requests discussion and suggestions for
19    improvements.  Please refer to the current edition of the "Internet
20    Official Protocol Standards" (STD 1) for the standardization state
21    and status of this protocol.  Distribution of this memo is unlimited.
22
23 Copyright Notice
24
25    Copyright (C) The Internet Society (2006).
26
27 Abstract
28
29    This document describes the protocol elements, along with their
30    semantics and encodings, of the Lightweight Directory Access Protocol
31    (LDAP).  LDAP provides access to distributed directory services that
32    act in accordance with X.500 data and service models.  These protocol
33    elements are based on those described in the X.500 Directory Access
34    Protocol (DAP).
35
36 Table of Contents
37
38    1. Introduction ....................................................3
39       1.1. Relationship to Other LDAP Specifications ..................3
40    2. Conventions .....................................................3
41    3. Protocol Model ..................................................4
42       3.1. Operation and LDAP Message Layer Relationship ..............5
43    4. Elements of Protocol ............................................5
44       4.1. Common Elements ............................................5
45            4.1.1. Message Envelope ....................................6
46            4.1.2. String Types ........................................7
47            4.1.3. Distinguished Name and Relative Distinguished Name ..8
48            4.1.4. Attribute Descriptions ..............................8
49            4.1.5. Attribute Value .....................................8
50            4.1.6. Attribute Value Assertion ...........................9
51            4.1.7. Attribute and PartialAttribute ......................9
52            4.1.8. Matching Rule Identifier ...........................10
53            4.1.9. Result Message .....................................10
54            4.1.10. Referral ..........................................12
55
56
57
58 Sermersheim                 Standards Track                     [Page 1]
59 \f
60 RFC 4511                         LDAPv3                        June 2006
61
62
63            4.1.11. Controls ..........................................14
64       4.2. Bind Operation ............................................16
65            4.2.1. Processing of the Bind Request .....................17
66            4.2.2. Bind Response ......................................18
67       4.3. Unbind Operation ..........................................18
68       4.4. Unsolicited Notification ..................................19
69            4.4.1. Notice of Disconnection ............................19
70       4.5. Search Operation ..........................................20
71            4.5.1. Search Request .....................................20
72            4.5.2. Search Result ......................................27
73            4.5.3. Continuation References in the Search Result .......28
74       4.6. Modify Operation ..........................................31
75       4.7. Add Operation .............................................33
76       4.8. Delete Operation ..........................................34
77       4.9. Modify DN Operation .......................................34
78       4.10. Compare Operation ........................................36
79       4.11. Abandon Operation ........................................36
80       4.12. Extended Operation .......................................37
81       4.13. IntermediateResponse Message .............................39
82            4.13.1. Usage with LDAP ExtendedRequest and
83                    ExtendedResponse ..................................40
84            4.13.2. Usage with LDAP Request Controls ..................40
85       4.14. StartTLS Operation .......................................40
86            4.14.1. StartTLS Request ..................................40
87            4.14.2. StartTLS Response .................................41
88            4.14.3. Removal of the TLS Layer ..........................41
89    5. Protocol Encoding, Connection, and Transfer ....................42
90       5.1. Protocol Encoding .........................................42
91       5.2. Transmission Control Protocol (TCP) .......................43
92       5.3. Termination of the LDAP session ...........................43
93    6. Security Considerations ........................................43
94    7. Acknowledgements ...............................................45
95    8. Normative References ...........................................46
96    9. Informative References .........................................48
97    10. IANA Considerations ...........................................48
98    Appendix A. LDAP Result Codes .....................................49
99       A.1. Non-Error Result Codes ....................................49
100       A.2. Result Codes ..............................................49
101    Appendix B. Complete ASN.1 Definition .............................54
102    Appendix C. Changes ...............................................60
103       C.1. Changes Made to RFC 2251 ..................................60
104       C.2. Changes Made to RFC 2830 ..................................66
105       C.3. Changes Made to RFC 3771 ..................................66
106
107
108
109
110
111
112
113
114 Sermersheim                 Standards Track                     [Page 2]
115 \f
116 RFC 4511                         LDAPv3                        June 2006
117
118
119 1.  Introduction
120
121    The Directory is "a collection of open systems cooperating to provide
122    directory services" [X.500].  A directory user, which may be a human
123    or other entity, accesses the Directory through a client (or
124    Directory User Agent (DUA)).  The client, on behalf of the directory
125    user, interacts with one or more servers (or Directory System Agents
126    (DSA)).  Clients interact with servers using a directory access
127    protocol.
128
129    This document details the protocol elements of the Lightweight
130    Directory Access Protocol (LDAP), along with their semantics.
131    Following the description of protocol elements, it describes the way
132    in which the protocol elements are encoded and transferred.
133
134 1.1.  Relationship to Other LDAP Specifications
135
136    This document is an integral part of the LDAP Technical Specification
137    [RFC4510], which obsoletes the previously defined LDAP technical
138    specification, RFC 3377, in its entirety.
139
140    This document, together with [RFC4510], [RFC4513], and [RFC4512],
141    obsoletes RFC 2251 in its entirety.  Section 3.3 is obsoleted by
142    [RFC4510].  Sections 4.2.1 (portions) and 4.2.2 are obsoleted by
143    [RFC4513].  Sections 3.2, 3.4, 4.1.3 (last paragraph), 4.1.4, 4.1.5,
144    4.1.5.1, 4.1.9 (last paragraph), 5.1, 6.1, and 6.2 (last paragraph)
145    are obsoleted by [RFC4512].  The remainder of RFC 2251 is obsoleted
146    by this document.  Appendix C.1 summarizes substantive changes in the
147    remainder.
148
149    This document obsoletes RFC 2830, Sections 2 and 4.  The remainder of
150    RFC 2830 is obsoleted by [RFC4513].  Appendix C.2 summarizes
151    substantive changes to the remaining sections.
152
153    This document also obsoletes RFC 3771 in entirety.
154
155 2.  Conventions
156
157    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
158    "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
159    to be interpreted as described in [RFC2119].
160
161    Character names in this document use the notation for code points and
162    names from the Unicode Standard [Unicode].  For example, the letter
163    "a" may be represented as either <U+0061> or <LATIN SMALL LETTER A>.
164
165
166
167
168
169
170 Sermersheim                 Standards Track                     [Page 3]
171 \f
172 RFC 4511                         LDAPv3                        June 2006
173
174
175    Note: a glossary of terms used in Unicode can be found in [Glossary].
176    Information on the Unicode character encoding model can be found in
177    [CharModel].
178
179    The term "transport connection" refers to the underlying transport
180    services used to carry the protocol exchange, as well as associations
181    established by these services.
182
183    The term "TLS layer" refers to Transport Layer Security (TLS)
184    services used in providing security services, as well as associations
185    established by these services.
186
187    The term "SASL layer" refers to Simply Authentication and Security
188    Layer (SASL) services used in providing security services, as well as
189    associations established by these services.
190
191    The term "LDAP message layer" refers to the LDAP Message Protocol
192    Data Unit (PDU) services used in providing directory services, as
193    well as associations established by these services.
194
195    The term "LDAP session" refers to combined services (transport
196    connection, TLS layer, SASL layer, LDAP message layer) and their
197    associations.
198
199    See the table in Section 5 for an illustration of these four terms.
200
201 3.  Protocol Model
202
203    The general model adopted by this protocol is one of clients
204    performing protocol operations against servers.  In this model, a
205    client transmits a protocol request describing the operation to be
206    performed to a server.  The server is then responsible for performing
207    the necessary operation(s) in the Directory.  Upon completion of an
208    operation, the server typically returns a response containing
209    appropriate data to the requesting client.
210
211    Protocol operations are generally independent of one another.  Each
212    operation is processed as an atomic action, leaving the directory in
213    a consistent state.
214
215    Although servers are required to return responses whenever such
216    responses are defined in the protocol, there is no requirement for
217    synchronous behavior on the part of either clients or servers.
218    Requests and responses for multiple operations generally may be
219    exchanged between a client and server in any order.  If required,
220    synchronous behavior may be controlled by client applications.
221
222
223
224
225
226 Sermersheim                 Standards Track                     [Page 4]
227 \f
228 RFC 4511                         LDAPv3                        June 2006
229
230
231    The core protocol operations defined in this document can be mapped
232    to a subset of the X.500 (1993) Directory Abstract Service [X.511].
233    However, there is not a one-to-one mapping between LDAP operations
234    and X.500 Directory Access Protocol (DAP) operations.  Server
235    implementations acting as a gateway to X.500 directories may need to
236    make multiple DAP requests to service a single LDAP request.
237
238 3.1.  Operation and LDAP Message Layer Relationship
239
240    Protocol operations are exchanged at the LDAP message layer.  When
241    the transport connection is closed, any uncompleted operations at the
242    LDAP message layer are abandoned (when possible) or are completed
243    without transmission of the response (when abandoning them is not
244    possible).  Also, when the transport connection is closed, the client
245    MUST NOT assume that any uncompleted update operations have succeeded
246    or failed.
247
248 4.  Elements of Protocol
249
250    The protocol is described using Abstract Syntax Notation One
251    ([ASN.1]) and is transferred using a subset of ASN.1 Basic Encoding
252    Rules ([BER]).  Section 5 specifies how the protocol elements are
253    encoded and transferred.
254
255    In order to support future extensions to this protocol, extensibility
256    is implied where it is allowed per ASN.1 (i.e., sequence, set,
257    choice, and enumerated types are extensible).  In addition, ellipses
258    (...) have been supplied in ASN.1 types that are explicitly
259    extensible as discussed in [RFC4520].  Because of the implied
260    extensibility, clients and servers MUST (unless otherwise specified)
261    ignore trailing SEQUENCE components whose tags they do not recognize.
262
263    Changes to the protocol other than through the extension mechanisms
264    described here require a different version number.  A client
265    indicates the version it is using as part of the BindRequest,
266    described in Section 4.2.  If a client has not sent a Bind, the
267    server MUST assume the client is using version 3 or later.
268
269    Clients may attempt to determine the protocol versions a server
270    supports by reading the 'supportedLDAPVersion' attribute from the
271    root DSE (DSA-Specific Entry) [RFC4512].
272
273 4.1.  Common Elements
274
275    This section describes the LDAPMessage envelope Protocol Data Unit
276    (PDU) format, as well as data type definitions, which are used in the
277    protocol operations.
278
279
280
281
282 Sermersheim                 Standards Track                     [Page 5]
283 \f
284 RFC 4511                         LDAPv3                        June 2006
285
286
287 4.1.1.  Message Envelope
288
289    For the purposes of protocol exchanges, all protocol operations are
290    encapsulated in a common envelope, the LDAPMessage, which is defined
291    as follows:
292
293         LDAPMessage ::= SEQUENCE {
294              messageID       MessageID,
295              protocolOp      CHOICE {
296                   bindRequest           BindRequest,
297                   bindResponse          BindResponse,
298                   unbindRequest         UnbindRequest,
299                   searchRequest         SearchRequest,
300                   searchResEntry        SearchResultEntry,
301                   searchResDone         SearchResultDone,
302                   searchResRef          SearchResultReference,
303                   modifyRequest         ModifyRequest,
304                   modifyResponse        ModifyResponse,
305                   addRequest            AddRequest,
306                   addResponse           AddResponse,
307                   delRequest            DelRequest,
308                   delResponse           DelResponse,
309                   modDNRequest          ModifyDNRequest,
310                   modDNResponse         ModifyDNResponse,
311                   compareRequest        CompareRequest,
312                   compareResponse       CompareResponse,
313                   abandonRequest        AbandonRequest,
314                   extendedReq           ExtendedRequest,
315                   extendedResp          ExtendedResponse,
316                   ...,
317                   intermediateResponse  IntermediateResponse },
318              controls       [0] Controls OPTIONAL }
319
320         MessageID ::= INTEGER (0 ..  maxInt)
321
322         maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
323
324    The ASN.1 type Controls is defined in Section 4.1.11.
325
326    The function of the LDAPMessage is to provide an envelope containing
327    common fields required in all protocol exchanges.  At this time, the
328    only common fields are the messageID and the controls.
329
330    If the server receives an LDAPMessage from the client in which the
331    LDAPMessage SEQUENCE tag cannot be recognized, the messageID cannot
332    be parsed, the tag of the protocolOp is not recognized as a request,
333    or the encoding structures or lengths of data fields are found to be
334    incorrect, then the server SHOULD return the Notice of Disconnection
335
336
337
338 Sermersheim                 Standards Track                     [Page 6]
339 \f
340 RFC 4511                         LDAPv3                        June 2006
341
342
343    described in Section 4.4.1, with the resultCode set to protocolError,
344    and MUST immediately terminate the LDAP session as described in
345    Section 5.3.
346
347    In other cases where the client or server cannot parse an LDAP PDU,
348    it SHOULD abruptly terminate the LDAP session (Section 5.3) where
349    further communication (including providing notice) would be
350    pernicious.  Otherwise, server implementations MUST return an
351    appropriate response to the request, with the resultCode set to
352    protocolError.
353
354 4.1.1.1.  MessageID
355
356    All LDAPMessage envelopes encapsulating responses contain the
357    messageID value of the corresponding request LDAPMessage.
358
359    The messageID of a request MUST have a non-zero value different from
360    the messageID of any other request in progress in the same LDAP
361    session.  The zero value is reserved for the unsolicited notification
362    message.
363
364    Typical clients increment a counter for each request.
365
366    A client MUST NOT send a request with the same messageID as an
367    earlier request in the same LDAP session unless it can be determined
368    that the server is no longer servicing the earlier request (e.g.,
369    after the final response is received, or a subsequent Bind
370    completes).  Otherwise, the behavior is undefined.  For this purpose,
371    note that Abandon and successfully abandoned operations do not send
372    responses.
373
374 4.1.2.  String Types
375
376    The LDAPString is a notational convenience to indicate that, although
377    strings of LDAPString type encode as ASN.1 OCTET STRING types, the
378    [ISO10646] character set (a superset of [Unicode]) is used, encoded
379    following the UTF-8 [RFC3629] algorithm.  Note that Unicode
380    characters U+0000 through U+007F are the same as ASCII 0 through 127,
381    respectively, and have the same single octet UTF-8 encoding.  Other
382    Unicode characters have a multiple octet UTF-8 encoding.
383
384         LDAPString ::= OCTET STRING -- UTF-8 encoded,
385                                     -- [ISO10646] characters
386
387    The LDAPOID is a notational convenience to indicate that the
388    permitted value of this string is a (UTF-8 encoded) dotted-decimal
389    representation of an OBJECT IDENTIFIER.  Although an LDAPOID is
390
391
392
393
394 Sermersheim                 Standards Track                     [Page 7]
395 \f
396 RFC 4511                         LDAPv3                        June 2006
397
398
399    encoded as an OCTET STRING, values are limited to the definition of
400    <numericoid> given in Section 1.4 of [RFC4512].
401
402         LDAPOID ::= OCTET STRING -- Constrained to <numericoid>
403                                  -- [RFC4512]
404
405    For example,
406
407         1.3.6.1.4.1.1466.1.2.3
408
409 4.1.3.  Distinguished Name and Relative Distinguished Name
410
411    An LDAPDN is defined to be the representation of a Distinguished Name
412    (DN) after encoding according to the specification in [RFC4514].
413
414         LDAPDN ::= LDAPString
415                    -- Constrained to <distinguishedName> [RFC4514]
416
417    A RelativeLDAPDN is defined to be the representation of a Relative
418    Distinguished Name (RDN) after encoding according to the
419    specification in [RFC4514].
420
421         RelativeLDAPDN ::= LDAPString
422                            -- Constrained to <name-component> [RFC4514]
423
424 4.1.4.  Attribute Descriptions
425
426    The definition and encoding rules for attribute descriptions are
427    defined in Section 2.5 of [RFC4512].  Briefly, an attribute
428    description is an attribute type and zero or more options.
429
430         AttributeDescription ::= LDAPString
431                                 -- Constrained to <attributedescription>
432                                 -- [RFC4512]
433
434 4.1.5.  Attribute Value
435
436    A field of type AttributeValue is an OCTET STRING containing an
437    encoded attribute value.  The attribute value is encoded according to
438    the LDAP-specific encoding definition of its corresponding syntax.
439    The LDAP-specific encoding definitions for different syntaxes and
440    attribute types may be found in other documents and in particular
441    [RFC4517].
442
443         AttributeValue ::= OCTET STRING
444
445
446
447
448
449
450 Sermersheim                 Standards Track                     [Page 8]
451 \f
452 RFC 4511                         LDAPv3                        June 2006
453
454
455    Note that there is no defined limit on the size of this encoding;
456    thus, protocol values may include multi-megabyte attribute values
457    (e.g., photographs).
458
459    Attribute values may be defined that have arbitrary and non-printable
460    syntax.  Implementations MUST NOT display or attempt to decode an
461    attribute value if its syntax is not known.  The implementation may
462    attempt to discover the subschema of the source entry and to retrieve
463    the descriptions of 'attributeTypes' from it [RFC4512].
464
465    Clients MUST only send attribute values in a request that are valid
466    according to the syntax defined for the attributes.
467
468 4.1.6.  Attribute Value Assertion
469
470    The AttributeValueAssertion (AVA) type definition is similar to the
471    one in the X.500 Directory standards.  It contains an attribute
472    description and a matching rule ([RFC4512], Section 4.1.3) assertion
473    value suitable for that type.  Elements of this type are typically
474    used to assert that the value in assertionValue matches a value of an
475    attribute.
476
477         AttributeValueAssertion ::= SEQUENCE {
478              attributeDesc   AttributeDescription,
479              assertionValue  AssertionValue }
480
481         AssertionValue ::= OCTET STRING
482
483    The syntax of the AssertionValue depends on the context of the LDAP
484    operation being performed.  For example, the syntax of the EQUALITY
485    matching rule for an attribute is used when performing a Compare
486    operation.  Often this is the same syntax used for values of the
487    attribute type, but in some cases the assertion syntax differs from
488    the value syntax.  See objectIdentiferFirstComponentMatch in
489    [RFC4517] for an example.
490
491 4.1.7.  Attribute and PartialAttribute
492
493    Attributes and partial attributes consist of an attribute description
494    and attribute values.  A PartialAttribute allows zero values, while
495    Attribute requires at least one value.
496
497         PartialAttribute ::= SEQUENCE {
498              type       AttributeDescription,
499              vals       SET OF value AttributeValue }
500
501
502
503
504
505
506 Sermersheim                 Standards Track                     [Page 9]
507 \f
508 RFC 4511                         LDAPv3                        June 2006
509
510
511         Attribute ::= PartialAttribute(WITH COMPONENTS {
512              ...,
513              vals (SIZE(1..MAX))})
514
515    No two of the attribute values may be equivalent as described by
516    Section 2.2 of [RFC4512].  The set of attribute values is unordered.
517    Implementations MUST NOT rely upon the ordering being repeatable.
518
519 4.1.8.  Matching Rule Identifier
520
521    Matching rules are defined in Section 4.1.3 of [RFC4512].  A matching
522    rule is identified in the protocol by the printable representation of
523    either its <numericoid> or one of its short name descriptors
524    [RFC4512], e.g., 'caseIgnoreMatch' or '2.5.13.2'.
525
526         MatchingRuleId ::= LDAPString
527
528 4.1.9.  Result Message
529
530    The LDAPResult is the construct used in this protocol to return
531    success or failure indications from servers to clients.  To various
532    requests, servers will return responses containing the elements found
533    in LDAPResult to indicate the final status of the protocol operation
534    request.
535
536         LDAPResult ::= SEQUENCE {
537              resultCode         ENUMERATED {
538                   success                      (0),
539                   operationsError              (1),
540                   protocolError                (2),
541                   timeLimitExceeded            (3),
542                   sizeLimitExceeded            (4),
543                   compareFalse                 (5),
544                   compareTrue                  (6),
545                   authMethodNotSupported       (7),
546                   strongerAuthRequired         (8),
547                        -- 9 reserved --
548                   referral                     (10),
549                   adminLimitExceeded           (11),
550                   unavailableCriticalExtension (12),
551                   confidentialityRequired      (13),
552                   saslBindInProgress           (14),
553                   noSuchAttribute              (16),
554                   undefinedAttributeType       (17),
555                   inappropriateMatching        (18),
556                   constraintViolation          (19),
557                   attributeOrValueExists       (20),
558                   invalidAttributeSyntax       (21),
559
560
561
562 Sermersheim                 Standards Track                    [Page 10]
563 \f
564 RFC 4511                         LDAPv3                        June 2006
565
566
567                        -- 22-31 unused --
568                   noSuchObject                 (32),
569                   aliasProblem                 (33),
570                   invalidDNSyntax              (34),
571                        -- 35 reserved for undefined isLeaf --
572                   aliasDereferencingProblem    (36),
573                        -- 37-47 unused --
574                   inappropriateAuthentication  (48),
575                   invalidCredentials           (49),
576                   insufficientAccessRights     (50),
577                   busy                         (51),
578                   unavailable                  (52),
579                   unwillingToPerform           (53),
580                   loopDetect                   (54),
581                        -- 55-63 unused --
582                   namingViolation              (64),
583                   objectClassViolation         (65),
584                   notAllowedOnNonLeaf          (66),
585                   notAllowedOnRDN              (67),
586                   entryAlreadyExists           (68),
587                   objectClassModsProhibited    (69),
588                        -- 70 reserved for CLDAP --
589                   affectsMultipleDSAs          (71),
590                        -- 72-79 unused --
591                   other                        (80),
592                   ...  },
593              matchedDN          LDAPDN,
594              diagnosticMessage  LDAPString,
595              referral           [3] Referral OPTIONAL }
596
597    The resultCode enumeration is extensible as defined in Section 3.8 of
598    [RFC4520].  The meanings of the listed result codes are given in
599    Appendix A.  If a server detects multiple errors for an operation,
600    only one result code is returned.  The server should return the
601    result code that best indicates the nature of the error encountered.
602    Servers may return substituted result codes to prevent unauthorized
603    disclosures.
604
605    The diagnosticMessage field of this construct may, at the server's
606    option, be used to return a string containing a textual, human-
607    readable diagnostic message (terminal control and page formatting
608    characters should be avoided).  As this diagnostic message is not
609    standardized, implementations MUST NOT rely on the values returned.
610    Diagnostic messages typically supplement the resultCode with
611    additional information.  If the server chooses not to return a
612    textual diagnostic, the diagnosticMessage field MUST be empty.
613
614
615
616
617
618 Sermersheim                 Standards Track                    [Page 11]
619 \f
620 RFC 4511                         LDAPv3                        June 2006
621
622
623    For certain result codes (typically, but not restricted to
624    noSuchObject, aliasProblem, invalidDNSyntax, and
625    aliasDereferencingProblem), the matchedDN field is set (subject to
626    access controls) to the name of the last entry (object or alias) used
627    in finding the target (or base) object.  This will be a truncated
628    form of the provided name or, if an alias was dereferenced while
629    attempting to locate the entry, of the resulting name.  Otherwise,
630    the matchedDN field is empty.
631
632 4.1.10.  Referral
633
634    The referral result code indicates that the contacted server cannot
635    or will not perform the operation and that one or more other servers
636    may be able to.  Reasons for this include:
637
638    - The target entry of the request is not held locally, but the server
639      has knowledge of its possible existence elsewhere.
640
641    - The operation is restricted on this server -- perhaps due to a
642      read-only copy of an entry to be modified.
643
644    The referral field is present in an LDAPResult if the resultCode is
645    set to referral, and it is absent with all other result codes.  It
646    contains one or more references to one or more servers or services
647    that may be accessed via LDAP or other protocols.  Referrals can be
648    returned in response to any operation request (except Unbind and
649    Abandon, which do not have responses).  At least one URI MUST be
650    present in the Referral.
651
652    During a Search operation, after the baseObject is located, and
653    entries are being evaluated, the referral is not returned.  Instead,
654    continuation references, described in Section 4.5.3, are returned
655    when other servers would need to be contacted to complete the
656    operation.
657
658         Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI
659
660         URI ::= LDAPString     -- limited to characters permitted in
661                                -- URIs
662
663    If the client wishes to progress the operation, it contacts one of
664    the supported services found in the referral.  If multiple URIs are
665    present, the client assumes that any supported URI may be used to
666    progress the operation.
667
668    Clients that follow referrals MUST ensure that they do not loop
669    between servers.  They MUST NOT repeatedly contact the same server
670    for the same request with the same parameters.  Some clients use a
671
672
673
674 Sermersheim                 Standards Track                    [Page 12]
675 \f
676 RFC 4511                         LDAPv3                        June 2006
677
678
679    counter that is incremented each time referral handling occurs for an
680    operation, and these kinds of clients MUST be able to handle at least
681    ten nested referrals while progressing the operation.
682
683    A URI for a server implementing LDAP and accessible via TCP/IP (v4 or
684    v6) [RFC793][RFC791] is written as an LDAP URL according to
685    [RFC4516].
686
687    Referral values that are LDAP URLs follow these rules:
688
689    - If an alias was dereferenced, the <dn> part of the LDAP URL MUST be
690      present, with the new target object name.
691
692    - It is RECOMMENDED that the <dn> part be present to avoid ambiguity.
693
694    - If the <dn> part is present, the client uses this name in its next
695      request to progress the operation, and if it is not present the
696      client uses the same name as in the original request.
697
698    - Some servers (e.g., participating in distributed indexing) may
699      provide a different filter in a URL of a referral for a Search
700      operation.
701
702    - If the <filter> part of the LDAP URL is present, the client uses
703      this filter in its next request to progress this Search, and if it
704      is not present the client uses the same filter as it used for that
705      Search.
706
707    - For Search, it is RECOMMENDED that the <scope> part be present to
708      avoid ambiguity.
709
710    - If the <scope> part is missing, the scope of the original Search is
711      used by the client to progress the operation.
712
713    - Other aspects of the new request may be the same as or different
714      from the request that generated the referral.
715
716    Other kinds of URIs may be returned.  The syntax and semantics of
717    such URIs is left to future specifications.  Clients may ignore URIs
718    that they do not support.
719
720    UTF-8 encoded characters appearing in the string representation of a
721    DN, search filter, or other fields of the referral value may not be
722    legal for URIs (e.g., spaces) and MUST be escaped using the % method
723    in [RFC3986].
724
725
726
727
728
729
730 Sermersheim                 Standards Track                    [Page 13]
731 \f
732 RFC 4511                         LDAPv3                        June 2006
733
734
735 4.1.11.  Controls
736
737    Controls provide a mechanism whereby the semantics and arguments of
738    existing LDAP operations may be extended.  One or more controls may
739    be attached to a single LDAP message.  A control only affects the
740    semantics of the message it is attached to.
741
742    Controls sent by clients are termed 'request controls', and those
743    sent by servers are termed 'response controls'.
744
745         Controls ::= SEQUENCE OF control Control
746
747         Control ::= SEQUENCE {
748              controlType             LDAPOID,
749              criticality             BOOLEAN DEFAULT FALSE,
750              controlValue            OCTET STRING OPTIONAL }
751
752    The controlType field is the dotted-decimal representation of an
753    OBJECT IDENTIFIER that uniquely identifies the control.  This
754    provides unambiguous naming of controls.  Often, response control(s)
755    solicited by a request control share controlType values with the
756    request control.
757
758    The criticality field only has meaning in controls attached to
759    request messages (except UnbindRequest).  For controls attached to
760    response messages and the UnbindRequest, the criticality field SHOULD
761    be FALSE, and MUST be ignored by the receiving protocol peer.  A
762    value of TRUE indicates that it is unacceptable to perform the
763    operation without applying the semantics of the control.
764    Specifically, the criticality field is applied as follows:
765
766    - If the server does not recognize the control type, determines that
767      it is not appropriate for the operation, or is otherwise unwilling
768      to perform the operation with the control, and if the criticality
769      field is TRUE, the server MUST NOT perform the operation, and for
770      operations that have a response message, it MUST return with the
771      resultCode set to unavailableCriticalExtension.
772
773    - If the server does not recognize the control type, determines that
774      it is not appropriate for the operation, or is otherwise unwilling
775      to perform the operation with the control, and if the criticality
776      field is FALSE, the server MUST ignore the control.
777
778    - Regardless of criticality, if a control is applied to an
779      operation, it is applied consistently and impartially to the
780      entire operation.
781
782
783
784
785
786 Sermersheim                 Standards Track                    [Page 14]
787 \f
788 RFC 4511                         LDAPv3                        June 2006
789
790
791    The controlValue may contain information associated with the
792    controlType.  Its format is defined by the specification of the
793    control.  Implementations MUST be prepared to handle arbitrary
794    contents of the controlValue octet string, including zero bytes.  It
795    is absent only if there is no value information that is associated
796    with a control of its type.  When a controlValue is defined in terms
797    of ASN.1, and BER-encoded according to Section 5.1, it also follows
798    the extensibility rules in Section 4.
799
800    Servers list the controlType of request controls they recognize in
801    the 'supportedControl' attribute in the root DSE (Section 5.1 of
802    [RFC4512]).
803
804    Controls SHOULD NOT be combined unless the semantics of the
805    combination has been specified.  The semantics of control
806    combinations, if specified, are generally found in the control
807    specification most recently published.  When a combination of
808    controls is encountered whose semantics are invalid, not specified
809    (or not known), the message is considered not well-formed; thus, the
810    operation fails with protocolError.  Controls with a criticality of
811    FALSE may be ignored in order to arrive at a valid combination.
812    Additionally, unless order-dependent semantics are given in a
813    specification, the order of a combination of controls in the SEQUENCE
814    is ignored.  Where the order is to be ignored but cannot be ignored
815    by the server, the message is considered not well-formed, and the
816    operation fails with protocolError.  Again, controls with a
817    criticality of FALSE may be ignored in order to arrive at a valid
818    combination.
819
820    This document does not specify any controls.  Controls may be
821    specified in other documents.  Documents detailing control extensions
822    are to provide for each control:
823
824    - the OBJECT IDENTIFIER assigned to the control,
825
826    - direction as to what value the sender should provide for the
827      criticality field (note: the semantics of the criticality field are
828      defined above should not be altered by the control's
829      specification),
830
831    - whether the controlValue field is present, and if so, the format of
832      its contents,
833
834    - the semantics of the control, and
835
836    - optionally, semantics regarding the combination of the control with
837      other controls.
838
839
840
841
842 Sermersheim                 Standards Track                    [Page 15]
843 \f
844 RFC 4511                         LDAPv3                        June 2006
845
846
847 4.2.  Bind Operation
848
849    The function of the Bind operation is to allow authentication
850    information to be exchanged between the client and server.  The Bind
851    operation should be thought of as the "authenticate" operation.
852    Operational, authentication, and security-related semantics of this
853    operation are given in [RFC4513].
854
855    The Bind request is defined as follows:
856
857         BindRequest ::= [APPLICATION 0] SEQUENCE {
858              version                 INTEGER (1 ..  127),
859              name                    LDAPDN,
860              authentication          AuthenticationChoice }
861
862         AuthenticationChoice ::= CHOICE {
863              simple                  [0] OCTET STRING,
864                                      -- 1 and 2 reserved
865              sasl                    [3] SaslCredentials,
866              ...  }
867
868         SaslCredentials ::= SEQUENCE {
869              mechanism               LDAPString,
870              credentials             OCTET STRING OPTIONAL }
871
872    Fields of the BindRequest are:
873
874    - version: A version number indicating the version of the protocol to
875      be used at the LDAP message layer.  This document describes version
876      3 of the protocol.  There is no version negotiation.  The client
877      sets this field to the version it desires.  If the server does not
878      support the specified version, it MUST respond with a BindResponse
879      where the resultCode is set to protocolError.
880
881    - name: If not empty, the name of the Directory object that the
882      client wishes to bind as.  This field may take on a null value (a
883      zero-length string) for the purposes of anonymous binds ([RFC4513],
884      Section 5.1) or when using SASL [RFC4422] authentication
885      ([RFC4513], Section 5.2).  Where the server attempts to locate the
886      named object, it SHALL NOT perform alias dereferencing.
887
888    - authentication: Information used in authentication.  This type is
889      extensible as defined in Section 3.7 of [RFC4520].  Servers that do
890      not support a choice supplied by a client return a BindResponse
891      with the resultCode set to authMethodNotSupported.
892
893
894
895
896
897
898 Sermersheim                 Standards Track                    [Page 16]
899 \f
900 RFC 4511                         LDAPv3                        June 2006
901
902
903      Textual passwords (consisting of a character sequence with a known
904      character set and encoding) transferred to the server using the
905      simple AuthenticationChoice SHALL be transferred as UTF-8 [RFC3629]
906      encoded [Unicode].  Prior to transfer, clients SHOULD prepare text
907      passwords as "query" strings by applying the SASLprep [RFC4013]
908      profile of the stringprep [RFC3454] algorithm.  Passwords
909      consisting of other data (such as random octets) MUST NOT be
910      altered.  The determination of whether a password is textual is a
911      local client matter.
912
913 4.2.1.  Processing of the Bind Request
914
915    Before processing a BindRequest, all uncompleted operations MUST
916    either complete or be abandoned.  The server may either wait for the
917    uncompleted operations to complete, or abandon them.  The server then
918    proceeds to authenticate the client in either a single-step or
919    multi-step Bind process.  Each step requires the server to return a
920    BindResponse to indicate the status of authentication.
921
922    After sending a BindRequest, clients MUST NOT send further LDAP PDUs
923    until receiving the BindResponse.  Similarly, servers SHOULD NOT
924    process or respond to requests received while processing a
925    BindRequest.
926
927    If the client did not bind before sending a request and receives an
928    operationsError to that request, it may then send a BindRequest.  If
929    this also fails or the client chooses not to bind on the existing
930    LDAP session, it may terminate the LDAP session, re-establish it, and
931    begin again by first sending a BindRequest.  This will aid in
932    interoperating with servers implementing other versions of LDAP.
933
934    Clients may send multiple Bind requests to change the authentication
935    and/or security associations or to complete a multi-stage Bind
936    process.  Authentication from earlier binds is subsequently ignored.
937
938    For some SASL authentication mechanisms, it may be necessary for the
939    client to invoke the BindRequest multiple times ([RFC4513], Section
940    5.2).  Clients MUST NOT invoke operations between two Bind requests
941    made as part of a multi-stage Bind.
942
943    A client may abort a SASL bind negotiation by sending a BindRequest
944    with a different value in the mechanism field of SaslCredentials, or
945    an AuthenticationChoice other than sasl.
946
947
948
949
950
951
952
953
954 Sermersheim                 Standards Track                    [Page 17]
955 \f
956 RFC 4511                         LDAPv3                        June 2006
957
958
959    If the client sends a BindRequest with the sasl mechanism field as an
960    empty string, the server MUST return a BindResponse with the
961    resultCode set to authMethodNotSupported.  This will allow the client
962    to abort a negotiation if it wishes to try again with the same SASL
963    mechanism.
964
965 4.2.2.  Bind Response
966
967    The Bind response is defined as follows.
968
969         BindResponse ::= [APPLICATION 1] SEQUENCE {
970              COMPONENTS OF LDAPResult,
971              serverSaslCreds    [7] OCTET STRING OPTIONAL }
972
973    BindResponse consists simply of an indication from the server of the
974    status of the client's request for authentication.
975
976    A successful Bind operation is indicated by a BindResponse with a
977    resultCode set to success.  Otherwise, an appropriate result code is
978    set in the BindResponse.  For BindResponse, the protocolError result
979    code may be used to indicate that the version number supplied by the
980    client is unsupported.
981
982    If the client receives a BindResponse where the resultCode is set to
983    protocolError, it is to assume that the server does not support this
984    version of LDAP.  While the client may be able proceed with another
985    version of this protocol (which may or may not require closing and
986    re-establishing the transport connection), how to proceed with
987    another version of this protocol is beyond the scope of this
988    document.  Clients that are unable or unwilling to proceed SHOULD
989    terminate the LDAP session.
990
991    The serverSaslCreds field is used as part of a SASL-defined bind
992    mechanism to allow the client to authenticate the server to which it
993    is communicating, or to perform "challenge-response" authentication.
994    If the client bound with the simple choice, or the SASL mechanism
995    does not require the server to return information to the client, then
996    this field SHALL NOT be included in the BindResponse.
997
998 4.3.  Unbind Operation
999
1000    The function of the Unbind operation is to terminate an LDAP session.
1001    The Unbind operation is not the antithesis of the Bind operation as
1002    the name implies.  The naming of these operations are historical.
1003    The Unbind operation should be thought of as the "quit" operation.
1004
1005
1006
1007
1008
1009
1010 Sermersheim                 Standards Track                    [Page 18]
1011 \f
1012 RFC 4511                         LDAPv3                        June 2006
1013
1014
1015    The Unbind operation is defined as follows:
1016
1017         UnbindRequest ::= [APPLICATION 2] NULL
1018
1019    The client, upon transmission of the UnbindRequest, and the server,
1020    upon receipt of the UnbindRequest, are to gracefully terminate the
1021    LDAP session as described in Section 5.3.  Uncompleted operations are
1022    handled as specified in Section 3.1.
1023
1024 4.4.  Unsolicited Notification
1025
1026    An unsolicited notification is an LDAPMessage sent from the server to
1027    the client that is not in response to any LDAPMessage received by the
1028    server.  It is used to signal an extraordinary condition in the
1029    server or in the LDAP session between the client and the server.  The
1030    notification is of an advisory nature, and the server will not expect
1031    any response to be returned from the client.
1032
1033    The unsolicited notification is structured as an LDAPMessage in which
1034    the messageID is zero and protocolOp is set to the extendedResp
1035    choice using the ExtendedResponse type (See Section 4.12).  The
1036    responseName field of the ExtendedResponse always contains an LDAPOID
1037    that is unique for this notification.
1038
1039    One unsolicited notification (Notice of Disconnection) is defined in
1040    this document.  The specification of an unsolicited notification
1041    consists of:
1042
1043    - the OBJECT IDENTIFIER assigned to the notification (to be specified
1044      in the responseName,
1045
1046    - the format of the contents of the responseValue (if any),
1047
1048    - the circumstances which will cause the notification to be sent, and
1049
1050    - the semantics of the message.
1051
1052 4.4.1.  Notice of Disconnection
1053
1054    This notification may be used by the server to advise the client that
1055    the server is about to terminate the LDAP session on its own
1056    initiative.  This notification is intended to assist clients in
1057    distinguishing between an exceptional server condition and a
1058    transient network failure.  Note that this notification is not a
1059    response to an Unbind requested by the client.  Uncompleted
1060    operations are handled as specified in Section 3.1.
1061
1062
1063
1064
1065
1066 Sermersheim                 Standards Track                    [Page 19]
1067 \f
1068 RFC 4511                         LDAPv3                        June 2006
1069
1070
1071    The responseName is 1.3.6.1.4.1.1466.20036, the responseValue field
1072    is absent, and the resultCode is used to indicate the reason for the
1073    disconnection.  When the strongerAuthRequired resultCode is returned
1074    with this message, it indicates that the server has detected that an
1075    established security association between the client and server has
1076    unexpectedly failed or been compromised.
1077
1078    Upon transmission of the Notice of Disconnection, the server
1079    gracefully terminates the LDAP session as described in Section 5.3.
1080
1081 4.5.  Search Operation
1082
1083    The Search operation is used to request a server to return, subject
1084    to access controls and other restrictions, a set of entries matching
1085    a complex search criterion.  This can be used to read attributes from
1086    a single entry, from entries immediately subordinate to a particular
1087    entry, or from a whole subtree of entries.
1088
1089 4.5.1.  Search Request
1090
1091    The Search request is defined as follows:
1092
1093         SearchRequest ::= [APPLICATION 3] SEQUENCE {
1094              baseObject      LDAPDN,
1095              scope           ENUMERATED {
1096                   baseObject              (0),
1097                   singleLevel             (1),
1098                   wholeSubtree            (2),
1099                   ...  },
1100              derefAliases    ENUMERATED {
1101                   neverDerefAliases       (0),
1102                   derefInSearching        (1),
1103                   derefFindingBaseObj     (2),
1104                   derefAlways             (3) },
1105              sizeLimit       INTEGER (0 ..  maxInt),
1106              timeLimit       INTEGER (0 ..  maxInt),
1107              typesOnly       BOOLEAN,
1108              filter          Filter,
1109              attributes      AttributeSelection }
1110
1111         AttributeSelection ::= SEQUENCE OF selector LDAPString
1112                         -- The LDAPString is constrained to
1113                         -- <attributeSelector> in Section 4.5.1.8
1114
1115         Filter ::= CHOICE {
1116              and             [0] SET SIZE (1..MAX) OF filter Filter,
1117              or              [1] SET SIZE (1..MAX) OF filter Filter,
1118              not             [2] Filter,
1119
1120
1121
1122 Sermersheim                 Standards Track                    [Page 20]
1123 \f
1124 RFC 4511                         LDAPv3                        June 2006
1125
1126
1127              equalityMatch   [3] AttributeValueAssertion,
1128              substrings      [4] SubstringFilter,
1129              greaterOrEqual  [5] AttributeValueAssertion,
1130              lessOrEqual     [6] AttributeValueAssertion,
1131              present         [7] AttributeDescription,
1132              approxMatch     [8] AttributeValueAssertion,
1133              extensibleMatch [9] MatchingRuleAssertion,
1134              ...  }
1135
1136         SubstringFilter ::= SEQUENCE {
1137              type           AttributeDescription,
1138              substrings     SEQUENCE SIZE (1..MAX) OF substring CHOICE {
1139                   initial [0] AssertionValue,  -- can occur at most once
1140                   any     [1] AssertionValue,
1141                   final   [2] AssertionValue } -- can occur at most once
1142              }
1143
1144         MatchingRuleAssertion ::= SEQUENCE {
1145              matchingRule    [1] MatchingRuleId OPTIONAL,
1146              type            [2] AttributeDescription OPTIONAL,
1147              matchValue      [3] AssertionValue,
1148              dnAttributes    [4] BOOLEAN DEFAULT FALSE }
1149
1150    Note that an X.500 "list"-like operation can be emulated by the
1151    client requesting a singleLevel Search operation with a filter
1152    checking for the presence of the 'objectClass' attribute, and that an
1153    X.500 "read"-like operation can be emulated by a baseObject Search
1154    operation with the same filter.  A server that provides a gateway to
1155    X.500 is not required to use the Read or List operations, although it
1156    may choose to do so, and if it does, it must provide the same
1157    semantics as the X.500 Search operation.
1158
1159 4.5.1.1.  SearchRequest.baseObject
1160
1161    The name of the base object entry (or possibly the root) relative to
1162    which the Search is to be performed.
1163
1164 4.5.1.2.  SearchRequest.scope
1165
1166    Specifies the scope of the Search to be performed.  The semantics (as
1167    described in [X.511]) of the defined values of this field are:
1168
1169       baseObject: The scope is constrained to the entry named by
1170       baseObject.
1171
1172       singleLevel: The scope is constrained to the immediate
1173       subordinates of the entry named by baseObject.
1174
1175
1176
1177
1178 Sermersheim                 Standards Track                    [Page 21]
1179 \f
1180 RFC 4511                         LDAPv3                        June 2006
1181
1182
1183       wholeSubtree: The scope is constrained to the entry named by
1184       baseObject and to all its subordinates.
1185
1186 4.5.1.3.  SearchRequest.derefAliases
1187
1188    An indicator as to whether or not alias entries (as defined in
1189    [RFC4512]) are to be dereferenced during stages of the Search
1190    operation.
1191
1192    The act of dereferencing an alias includes recursively dereferencing
1193    aliases that refer to aliases.
1194
1195    Servers MUST detect looping while dereferencing aliases in order to
1196    prevent denial-of-service attacks of this nature.
1197
1198    The semantics of the defined values of this field are:
1199
1200       neverDerefAliases: Do not dereference aliases in searching or in
1201       locating the base object of the Search.
1202
1203       derefInSearching: While searching subordinates of the base object,
1204       dereference any alias within the search scope.  Dereferenced
1205       objects become the vertices of further search scopes where the
1206       Search operation is also applied.  If the search scope is
1207       wholeSubtree, the Search continues in the subtree(s) of any
1208       dereferenced object.  If the search scope is singleLevel, the
1209       search is applied to any dereferenced objects and is not applied
1210       to their subordinates.  Servers SHOULD eliminate duplicate entries
1211       that arise due to alias dereferencing while searching.
1212
1213       derefFindingBaseObj: Dereference aliases in locating the base
1214       object of the Search, but not when searching subordinates of the
1215       base object.
1216
1217       derefAlways: Dereference aliases both in searching and in locating
1218       the base object of the Search.
1219
1220 4.5.1.4.  SearchRequest.sizeLimit
1221
1222    A size limit that restricts the maximum number of entries to be
1223    returned as a result of the Search.  A value of zero in this field
1224    indicates that no client-requested size limit restrictions are in
1225    effect for the Search.  Servers may also enforce a maximum number of
1226    entries to return.
1227
1228
1229
1230
1231
1232
1233
1234 Sermersheim                 Standards Track                    [Page 22]
1235 \f
1236 RFC 4511                         LDAPv3                        June 2006
1237
1238
1239 4.5.1.5.  SearchRequest.timeLimit
1240
1241    A time limit that restricts the maximum time (in seconds) allowed for
1242    a Search.  A value of zero in this field indicates that no client-
1243    requested time limit restrictions are in effect for the Search.
1244    Servers may also enforce a maximum time limit for the Search.
1245
1246 4.5.1.6.  SearchRequest.typesOnly
1247
1248    An indicator as to whether Search results are to contain both
1249    attribute descriptions and values, or just attribute descriptions.
1250    Setting this field to TRUE causes only attribute descriptions (and
1251    not values) to be returned.  Setting this field to FALSE causes both
1252    attribute descriptions and values to be returned.
1253
1254 4.5.1.7.  SearchRequest.filter
1255
1256    A filter that defines the conditions that must be fulfilled in order
1257    for the Search to match a given entry.
1258
1259    The 'and', 'or', and 'not' choices can be used to form combinations
1260    of filters.  At least one filter element MUST be present in an 'and'
1261    or 'or' choice.  The others match against individual attribute values
1262    of entries in the scope of the Search.  (Implementor's note: the
1263    'not' filter is an example of a tagged choice in an implicitly-tagged
1264    module.  In BER this is treated as if the tag were explicit.)
1265
1266    A server MUST evaluate filters according to the three-valued logic of
1267    [X.511] (1993), Clause 7.8.1.  In summary, a filter is evaluated to
1268    "TRUE", "FALSE", or "Undefined".  If the filter evaluates to TRUE for
1269    a particular entry, then the attributes of that entry are returned as
1270    part of the Search result (subject to any applicable access control
1271    restrictions).  If the filter evaluates to FALSE or Undefined, then
1272    the entry is ignored for the Search.
1273
1274    A filter of the "and" choice is TRUE if all the filters in the SET OF
1275    evaluate to TRUE, FALSE if at least one filter is FALSE, and
1276    Undefined otherwise.  A filter of the "or" choice is FALSE if all the
1277    filters in the SET OF evaluate to FALSE, TRUE if at least one filter
1278    is TRUE, and Undefined otherwise.  A filter of the 'not' choice is
1279    TRUE if the filter being negated is FALSE, FALSE if it is TRUE, and
1280    Undefined if it is Undefined.
1281
1282    A filter item evaluates to Undefined when the server would not be
1283    able to determine whether the assertion value matches an entry.
1284    Examples include:
1285
1286
1287
1288
1289
1290 Sermersheim                 Standards Track                    [Page 23]
1291 \f
1292 RFC 4511                         LDAPv3                        June 2006
1293
1294
1295    - An attribute description in an equalityMatch, substrings,
1296      greaterOrEqual, lessOrEqual, approxMatch, or extensibleMatch filter
1297      is not recognized by the server.
1298
1299    - The attribute type does not define the appropriate matching rule.
1300
1301    - A MatchingRuleId in the extensibleMatch is not recognized by the
1302      server or is not valid for the attribute type.
1303
1304    - The type of filtering requested is not implemented.
1305
1306    - The assertion value is invalid.
1307
1308    For example, if a server did not recognize the attribute type
1309    shoeSize, the filters (shoeSize=*), (shoeSize=12), (shoeSize>=12),
1310    and (shoeSize<=12) would each evaluate to Undefined.
1311
1312    Servers MUST NOT return errors if attribute descriptions or matching
1313    rule ids are not recognized, assertion values are invalid, or the
1314    assertion syntax is not supported.  More details of filter processing
1315    are given in Clause 7.8 of [X.511].
1316
1317 4.5.1.7.1.  SearchRequest.filter.equalityMatch
1318
1319    The matching rule for an equalityMatch filter is defined by the
1320    EQUALITY matching rule for the attribute type or subtype.  The filter
1321    is TRUE when the EQUALITY rule returns TRUE as applied to the
1322    attribute or subtype and the asserted value.
1323
1324 4.5.1.7.2.  SearchRequest.filter.substrings
1325
1326    There SHALL be at most one 'initial' and at most one 'final' in the
1327    'substrings' of a SubstringFilter.  If 'initial' is present, it SHALL
1328    be the first element of 'substrings'.  If 'final' is present, it
1329    SHALL be the last element of 'substrings'.
1330
1331    The matching rule for an AssertionValue in a substrings filter item
1332    is defined by the SUBSTR matching rule for the attribute type or
1333    subtype.  The filter is TRUE when the SUBSTR rule returns TRUE as
1334    applied to the attribute or subtype and the asserted value.
1335
1336    Note that the AssertionValue in a substrings filter item conforms to
1337    the assertion syntax of the EQUALITY matching rule for the attribute
1338    type rather than to the assertion syntax of the SUBSTR matching rule
1339    for the attribute type.  Conceptually, the entire SubstringFilter is
1340    converted into an assertion value of the substrings matching rule
1341    prior to applying the rule.
1342
1343
1344
1345
1346 Sermersheim                 Standards Track                    [Page 24]
1347 \f
1348 RFC 4511                         LDAPv3                        June 2006
1349
1350
1351 4.5.1.7.3.  SearchRequest.filter.greaterOrEqual
1352
1353    The matching rule for a greaterOrEqual filter is defined by the
1354    ORDERING matching rule for the attribute type or subtype.  The filter
1355    is TRUE when the ORDERING rule returns FALSE as applied to the
1356    attribute or subtype and the asserted value.
1357
1358 4.5.1.7.4.  SearchRequest.filter.lessOrEqual
1359
1360    The matching rules for a lessOrEqual filter are defined by the
1361    ORDERING and EQUALITY matching rules for the attribute type or
1362    subtype.  The filter is TRUE when either the ORDERING or EQUALITY
1363    rule returns TRUE as applied to the attribute or subtype and the
1364    asserted value.
1365
1366 4.5.1.7.5.  SearchRequest.filter.present
1367
1368    A present filter is TRUE when there is an attribute or subtype of the
1369    specified attribute description present in an entry, FALSE when no
1370    attribute or subtype of the specified attribute description is
1371    present in an entry, and Undefined otherwise.
1372
1373 4.5.1.7.6.  SearchRequest.filter.approxMatch
1374
1375    An approxMatch filter is TRUE when there is a value of the attribute
1376    type or subtype for which some locally-defined approximate matching
1377    algorithm (e.g., spelling variations, phonetic match, etc.) returns
1378    TRUE.  If a value matches for equality, it also satisfies an
1379    approximate match.  If approximate matching is not supported for the
1380    attribute, this filter item should be treated as an equalityMatch.
1381
1382 4.5.1.7.7.  SearchRequest.filter.extensibleMatch
1383
1384    The fields of the extensibleMatch filter item are evaluated as
1385    follows:
1386
1387    - If the matchingRule field is absent, the type field MUST be
1388      present, and an equality match is performed for that type.
1389
1390    - If the type field is absent and the matchingRule is present, the
1391      matchValue is compared against all attributes in an entry that
1392      support that matchingRule.
1393
1394    - If the type field is present and the matchingRule is present, the
1395      matchValue is compared against the specified attribute type and its
1396      subtypes.
1397
1398
1399
1400
1401
1402 Sermersheim                 Standards Track                    [Page 25]
1403 \f
1404 RFC 4511                         LDAPv3                        June 2006
1405
1406
1407    - If the dnAttributes field is set to TRUE, the match is additionally
1408      applied against all the AttributeValueAssertions in an entry's
1409      distinguished name, and it evaluates to TRUE if there is at least
1410      one attribute or subtype in the distinguished name for which the
1411      filter item evaluates to TRUE.  The dnAttributes field is present
1412      to alleviate the need for multiple versions of generic matching
1413      rules (such as word matching), where one applies to entries and
1414      another applies to entries and DN attributes as well.
1415
1416    The matchingRule used for evaluation determines the syntax for the
1417    assertion value.  Once the matchingRule and attribute(s) have been
1418    determined, the filter item evaluates to TRUE if it matches at least
1419    one attribute type or subtype in the entry, FALSE if it does not
1420    match any attribute type or subtype in the entry, and Undefined if
1421    the matchingRule is not recognized, the matchingRule is unsuitable
1422    for use with the specified type, or the assertionValue is invalid.
1423
1424 4.5.1.8.  SearchRequest.attributes
1425
1426    A selection list of the attributes to be returned from each entry
1427    that matches the search filter.  Attributes that are subtypes of
1428    listed attributes are implicitly included.  LDAPString values of this
1429    field are constrained to the following Augmented Backus-Naur Form
1430    (ABNF) [RFC4234]:
1431
1432       attributeSelector = attributedescription / selectorspecial
1433
1434       selectorspecial = noattrs / alluserattrs
1435
1436       noattrs = %x31.2E.31 ; "1.1"
1437
1438       alluserattrs = %x2A ; asterisk ("*")
1439
1440       The <attributedescription> production is defined in Section 2.5 of
1441       [RFC4512].
1442
1443       There are three special cases that may appear in the attributes
1444       selection list:
1445
1446       1. An empty list with no attributes requests the return of all
1447          user attributes.
1448
1449       2. A list containing "*" (with zero or more attribute
1450          descriptions) requests the return of all user attributes in
1451          addition to other listed (operational) attributes.
1452
1453
1454
1455
1456
1457
1458 Sermersheim                 Standards Track                    [Page 26]
1459 \f
1460 RFC 4511                         LDAPv3                        June 2006
1461
1462
1463       3. A list containing only the OID "1.1" indicates that no
1464          attributes are to be returned.  If "1.1" is provided with other
1465          attributeSelector values, the "1.1" attributeSelector is
1466          ignored.  This OID was chosen because it does not (and can not)
1467          correspond to any attribute in use.
1468
1469    Client implementors should note that even if all user attributes are
1470    requested, some attributes and/or attribute values of the entry may
1471    not be included in Search results due to access controls or other
1472    restrictions.  Furthermore, servers will not return operational
1473    attributes, such as objectClasses or attributeTypes, unless they are
1474    listed by name.  Operational attributes are described in [RFC4512].
1475
1476    Attributes are returned at most once in an entry.  If an attribute
1477    description is named more than once in the list, the subsequent names
1478    are ignored.  If an attribute description in the list is not
1479    recognized, it is ignored by the server.
1480
1481 4.5.2.  Search Result
1482
1483    The results of the Search operation are returned as zero or more
1484    SearchResultEntry and/or SearchResultReference messages, followed by
1485    a single SearchResultDone message.
1486
1487         SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
1488              objectName      LDAPDN,
1489              attributes      PartialAttributeList }
1490
1491         PartialAttributeList ::= SEQUENCE OF
1492                              partialAttribute PartialAttribute
1493
1494         SearchResultReference ::= [APPLICATION 19] SEQUENCE
1495                                   SIZE (1..MAX) OF uri URI
1496
1497         SearchResultDone ::= [APPLICATION 5] LDAPResult
1498
1499    Each SearchResultEntry represents an entry found during the Search.
1500    Each SearchResultReference represents an area not yet explored during
1501    the Search.  The SearchResultEntry and SearchResultReference messages
1502    may come in any order.  Following all the SearchResultReference and
1503    SearchResultEntry responses, the server returns a SearchResultDone
1504    response, which contains an indication of success or details any
1505    errors that have occurred.
1506
1507    Each entry returned in a SearchResultEntry will contain all
1508    appropriate attributes as specified in the attributes field of the
1509    Search Request, subject to access control and other administrative
1510    policy.  Note that the PartialAttributeList may hold zero elements.
1511
1512
1513
1514 Sermersheim                 Standards Track                    [Page 27]
1515 \f
1516 RFC 4511                         LDAPv3                        June 2006
1517
1518
1519    This may happen when none of the attributes of an entry were
1520    requested or could be returned.  Note also that the partialAttribute
1521    vals set may hold zero elements.  This may happen when typesOnly is
1522    requested, access controls prevent the return of values, or other
1523    reasons.
1524
1525    Some attributes may be constructed by the server and appear in a
1526    SearchResultEntry attribute list, although they are not stored
1527    attributes of an entry.  Clients SHOULD NOT assume that all
1528    attributes can be modified, even if this is permitted by access
1529    control.
1530
1531    If the server's schema defines short names [RFC4512] for an attribute
1532    type, then the server SHOULD use one of those names in attribute
1533    descriptions for that attribute type (in preference to using the
1534    <numericoid> [RFC4512] format of the attribute type's object
1535    identifier).  The server SHOULD NOT use the short name if that name
1536    is known by the server to be ambiguous, or if it is otherwise likely
1537    to cause interoperability problems.
1538
1539 4.5.3.  Continuation References in the Search Result
1540
1541    If the server was able to locate the entry referred to by the
1542    baseObject but was unable or unwilling to search one or more non-
1543    local entries, the server may return one or more
1544    SearchResultReference messages, each containing a reference to
1545    another set of servers for continuing the operation.  A server MUST
1546    NOT return any SearchResultReference messages if it has not located
1547    the baseObject and thus has not searched any entries.  In this case,
1548    it would return a SearchResultDone containing either a referral or
1549    noSuchObject result code (depending on the server's knowledge of the
1550    entry named in the baseObject).
1551
1552    If a server holds a copy or partial copy of the subordinate naming
1553    context (Section 5 of [RFC4512]), it may use the search filter to
1554    determine whether or not to return a SearchResultReference response.
1555    Otherwise, SearchResultReference responses are always returned when
1556    in scope.
1557
1558    The SearchResultReference is of the same data type as the Referral.
1559
1560    If the client wishes to progress the Search, it issues a new Search
1561    operation for each SearchResultReference that is returned.  If
1562    multiple URIs are present, the client assumes that any supported URI
1563    may be used to progress the operation.
1564
1565
1566
1567
1568
1569
1570 Sermersheim                 Standards Track                    [Page 28]
1571 \f
1572 RFC 4511                         LDAPv3                        June 2006
1573
1574
1575    Clients that follow search continuation references MUST ensure that
1576    they do not loop between servers.  They MUST NOT repeatedly contact
1577    the same server for the same request with the same parameters.  Some
1578    clients use a counter that is incremented each time search result
1579    reference handling occurs for an operation, and these kinds of
1580    clients MUST be able to handle at least ten nested referrals while
1581    progressing the operation.
1582
1583    Note that the Abandon operation described in Section 4.11 applies
1584    only to a particular operation sent at the LDAP message layer between
1585    a client and server.  The client must individually abandon subsequent
1586    Search operations it wishes to.
1587
1588    A URI for a server implementing LDAP and accessible via TCP/IP (v4 or
1589    v6) [RFC793][RFC791] is written as an LDAP URL according to
1590    [RFC4516].
1591
1592    SearchResultReference values that are LDAP URLs follow these rules:
1593
1594    - The <dn> part of the LDAP URL MUST be present, with the new target
1595      object name.  The client uses this name when following the
1596      reference.
1597
1598    - Some servers (e.g., participating in distributed indexing) may
1599      provide a different filter in the LDAP URL.
1600
1601    - If the <filter> part of the LDAP URL is present, the client uses
1602      this filter in its next request to progress this Search, and if it
1603      is not present the client uses the same filter as it used for that
1604      Search.
1605
1606    - If the originating search scope was singleLevel, the <scope> part
1607      of the LDAP URL will be "base".
1608
1609    - It is RECOMMENDED that the <scope> part be present to avoid
1610      ambiguity.  In the absence of a <scope> part, the scope of the
1611      original Search request is assumed.
1612
1613    - Other aspects of the new Search request may be the same as or
1614      different from the Search request that generated the
1615      SearchResultReference.
1616
1617    - The name of an unexplored subtree in a SearchResultReference need
1618      not be subordinate to the base object.
1619
1620    Other kinds of URIs may be returned.  The syntax and semantics of
1621    such URIs is left to future specifications.  Clients may ignore URIs
1622    that they do not support.
1623
1624
1625
1626 Sermersheim                 Standards Track                    [Page 29]
1627 \f
1628 RFC 4511                         LDAPv3                        June 2006
1629
1630
1631    UTF-8-encoded characters appearing in the string representation of a
1632    DN, search filter, or other fields of the referral value may not be
1633    legal for URIs (e.g., spaces) and MUST be escaped using the % method
1634    in [RFC3986].
1635
1636 4.5.3.1.  Examples
1637
1638    For example, suppose the contacted server (hosta) holds the entry
1639    <DC=Example,DC=NET> and the entry <CN=Manager,DC=Example,DC=NET>.  It
1640    knows that both LDAP servers (hostb) and (hostc) hold
1641    <OU=People,DC=Example,DC=NET> (one is the master and the other server
1642    a shadow), and that LDAP-capable server (hostd) holds the subtree
1643    <OU=Roles,DC=Example,DC=NET>.  If a wholeSubtree Search of
1644    <DC=Example,DC=NET> is requested to the contacted server, it may
1645    return the following:
1646
1647      SearchResultEntry for DC=Example,DC=NET
1648      SearchResultEntry for CN=Manager,DC=Example,DC=NET
1649      SearchResultReference {
1650        ldap://hostb/OU=People,DC=Example,DC=NET??sub
1651        ldap://hostc/OU=People,DC=Example,DC=NET??sub }
1652      SearchResultReference {
1653        ldap://hostd/OU=Roles,DC=Example,DC=NET??sub }
1654      SearchResultDone (success)
1655
1656    Client implementors should note that when following a
1657    SearchResultReference, additional SearchResultReference may be
1658    generated.  Continuing the example, if the client contacted the
1659    server (hostb) and issued the Search request for the subtree
1660    <OU=People,DC=Example,DC=NET>, the server might respond as follows:
1661
1662      SearchResultEntry for OU=People,DC=Example,DC=NET
1663      SearchResultReference {
1664        ldap://hoste/OU=Managers,OU=People,DC=Example,DC=NET??sub }
1665      SearchResultReference {
1666        ldap://hostf/OU=Consultants,OU=People,DC=Example,DC=NET??sub }
1667      SearchResultDone (success)
1668
1669    Similarly, if a singleLevel Search of <DC=Example,DC=NET> is
1670    requested to the contacted server, it may return the following:
1671
1672      SearchResultEntry for CN=Manager,DC=Example,DC=NET
1673      SearchResultReference {
1674        ldap://hostb/OU=People,DC=Example,DC=NET??base
1675        ldap://hostc/OU=People,DC=Example,DC=NET??base }
1676      SearchResultReference {
1677        ldap://hostd/OU=Roles,DC=Example,DC=NET??base }
1678      SearchResultDone (success)
1679
1680
1681
1682 Sermersheim                 Standards Track                    [Page 30]
1683 \f
1684 RFC 4511                         LDAPv3                        June 2006
1685
1686
1687    If the contacted server does not hold the base object for the Search,
1688    but has knowledge of its possible location, then it may return a
1689    referral to the client.  In this case, if the client requests a
1690    subtree Search of <DC=Example,DC=ORG> to hosta, the server returns a
1691    SearchResultDone containing a referral.
1692
1693      SearchResultDone (referral) {
1694        ldap://hostg/DC=Example,DC=ORG??sub }
1695
1696 4.6.  Modify Operation
1697
1698    The Modify operation allows a client to request that a modification
1699    of an entry be performed on its behalf by a server.  The Modify
1700    Request is defined as follows:
1701
1702         ModifyRequest ::= [APPLICATION 6] SEQUENCE {
1703              object          LDAPDN,
1704              changes         SEQUENCE OF change SEQUENCE {
1705                   operation       ENUMERATED {
1706                        add     (0),
1707                        delete  (1),
1708                        replace (2),
1709                        ...  },
1710                   modification    PartialAttribute } }
1711
1712    Fields of the Modify Request are:
1713
1714    - object: The value of this field contains the name of the entry to
1715      be modified.  The server SHALL NOT perform any alias dereferencing
1716      in determining the object to be modified.
1717
1718    - changes: A list of modifications to be performed on the entry.  The
1719      entire list of modifications MUST be performed in the order they
1720      are listed as a single atomic operation.  While individual
1721      modifications may violate certain aspects of the directory schema
1722      (such as the object class definition and Directory Information Tree
1723      (DIT) content rule), the resulting entry after the entire list of
1724      modifications is performed MUST conform to the requirements of the
1725      directory model and controlling schema [RFC4512].
1726
1727      -  operation: Used to specify the type of modification being
1728         performed.  Each operation type acts on the following
1729         modification.  The values of this field have the following
1730         semantics, respectively:
1731
1732            add: add values listed to the modification attribute,
1733            creating the attribute if necessary.
1734
1735
1736
1737
1738 Sermersheim                 Standards Track                    [Page 31]
1739 \f
1740 RFC 4511                         LDAPv3                        June 2006
1741
1742
1743            delete: delete values listed from the modification attribute.
1744            If no values are listed, or if all current values of the
1745            attribute are listed, the entire attribute is removed.
1746
1747            replace: replace all existing values of the modification
1748            attribute with the new values listed, creating the attribute
1749            if it did not already exist.  A replace with no value will
1750            delete the entire attribute if it exists, and it is ignored
1751            if the attribute does not exist.
1752
1753      -  modification: A PartialAttribute (which may have an empty SET
1754         of vals) used to hold the attribute type or attribute type and
1755         values being modified.
1756
1757    Upon receipt of a Modify Request, the server attempts to perform the
1758    necessary modifications to the DIT and returns the result in a Modify
1759    Response, defined as follows:
1760
1761         ModifyResponse ::= [APPLICATION 7] LDAPResult
1762
1763    The server will return to the client a single Modify Response
1764    indicating either the successful completion of the DIT modification,
1765    or the reason that the modification failed.  Due to the requirement
1766    for atomicity in applying the list of modifications in the Modify
1767    Request, the client may expect that no modifications of the DIT have
1768    been performed if the Modify Response received indicates any sort of
1769    error, and that all requested modifications have been performed if
1770    the Modify Response indicates successful completion of the Modify
1771    operation.  Whether or not the modification was applied cannot be
1772    determined by the client if the Modify Response was not received
1773    (e.g., the LDAP session was terminated or the Modify operation was
1774    abandoned).
1775
1776    Servers MUST ensure that entries conform to user and system schema
1777    rules or other data model constraints.  The Modify operation cannot
1778    be used to remove from an entry any of its distinguished values,
1779    i.e., those values which form the entry's relative distinguished
1780    name.  An attempt to do so will result in the server returning the
1781    notAllowedOnRDN result code.  The Modify DN operation described in
1782    Section 4.9 is used to rename an entry.
1783
1784    For attribute types that specify no equality matching, the rules in
1785    Section 2.5.1 of [RFC4512] are followed.
1786
1787    Note that due to the simplifications made in LDAP, there is not a
1788    direct mapping of the changes in an LDAP ModifyRequest onto the
1789    changes of a DAP ModifyEntry operation, and different implementations
1790
1791
1792
1793
1794 Sermersheim                 Standards Track                    [Page 32]
1795 \f
1796 RFC 4511                         LDAPv3                        June 2006
1797
1798
1799    of LDAP-DAP gateways may use different means of representing the
1800    change.  If successful, the final effect of the operations on the
1801    entry MUST be identical.
1802
1803 4.7.  Add Operation
1804
1805    The Add operation allows a client to request the addition of an entry
1806    into the Directory.  The Add Request is defined as follows:
1807
1808         AddRequest ::= [APPLICATION 8] SEQUENCE {
1809              entry           LDAPDN,
1810              attributes      AttributeList }
1811
1812         AttributeList ::= SEQUENCE OF attribute Attribute
1813
1814    Fields of the Add Request are:
1815
1816    - entry: the name of the entry to be added.  The server SHALL NOT
1817      dereference any aliases in locating the entry to be added.
1818
1819    - attributes: the list of attributes that, along with those from the
1820      RDN, make up the content of the entry being added.  Clients MAY or
1821      MAY NOT include the RDN attribute(s) in this list.  Clients MUST
1822      NOT supply NO-USER-MODIFICATION attributes such as the
1823      createTimestamp or creatorsName attributes, since the server
1824      maintains these automatically.
1825
1826    Servers MUST ensure that entries conform to user and system schema
1827    rules or other data model constraints.  For attribute types that
1828    specify no equality matching, the rules in Section 2.5.1 of [RFC4512]
1829    are followed (this applies to the naming attribute in addition to any
1830    multi-valued attributes being added).
1831
1832    The entry named in the entry field of the AddRequest MUST NOT exist
1833    for the AddRequest to succeed.  The immediate superior (parent) of an
1834    object or alias entry to be added MUST exist.  For example, if the
1835    client attempted to add <CN=JS,DC=Example,DC=NET>, the
1836    <DC=Example,DC=NET> entry did not exist, and the <DC=NET> entry did
1837    exist, then the server would return the noSuchObject result code with
1838    the matchedDN field containing <DC=NET>.
1839
1840    Upon receipt of an Add Request, a server will attempt to add the
1841    requested entry.  The result of the Add attempt will be returned to
1842    the client in the Add Response, defined as follows:
1843
1844         AddResponse ::= [APPLICATION 9] LDAPResult
1845
1846
1847
1848
1849
1850 Sermersheim                 Standards Track                    [Page 33]
1851 \f
1852 RFC 4511                         LDAPv3                        June 2006
1853
1854
1855    A response of success indicates that the new entry has been added to
1856    the Directory.
1857
1858 4.8.  Delete Operation
1859
1860    The Delete operation allows a client to request the removal of an
1861    entry from the Directory.  The Delete Request is defined as follows:
1862
1863         DelRequest ::= [APPLICATION 10] LDAPDN
1864
1865    The Delete Request consists of the name of the entry to be deleted.
1866    The server SHALL NOT dereference aliases while resolving the name of
1867    the target entry to be removed.
1868
1869    Only leaf entries (those with no subordinate entries) can be deleted
1870    with this operation.
1871
1872    Upon receipt of a Delete Request, a server will attempt to perform
1873    the entry removal requested and return the result in the Delete
1874    Response defined as follows:
1875
1876         DelResponse ::= [APPLICATION 11] LDAPResult
1877
1878 4.9.  Modify DN Operation
1879
1880    The Modify DN operation allows a client to change the Relative
1881    Distinguished Name (RDN) of an entry in the Directory and/or to move
1882    a subtree of entries to a new location in the Directory.  The Modify
1883    DN Request is defined as follows:
1884
1885         ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
1886              entry           LDAPDN,
1887              newrdn          RelativeLDAPDN,
1888              deleteoldrdn    BOOLEAN,
1889              newSuperior     [0] LDAPDN OPTIONAL }
1890
1891    Fields of the Modify DN Request are:
1892
1893    - entry: the name of the entry to be changed.  This entry may or may
1894      not have subordinate entries.
1895
1896    - newrdn: the new RDN of the entry.  The value of the old RDN is
1897      supplied when moving the entry to a new superior without changing
1898      its RDN.  Attribute values of the new RDN not matching any
1899      attribute value of the entry are added to the entry, and an
1900      appropriate error is returned if this fails.
1901
1902
1903
1904
1905
1906 Sermersheim                 Standards Track                    [Page 34]
1907 \f
1908 RFC 4511                         LDAPv3                        June 2006
1909
1910
1911    - deleteoldrdn: a boolean field that controls whether the old RDN
1912      attribute values are to be retained as attributes of the entry or
1913      deleted from the entry.
1914
1915    - newSuperior: if present, this is the name of an existing object
1916      entry that becomes the immediate superior (parent) of the
1917      existing entry.
1918
1919    The server SHALL NOT dereference any aliases in locating the objects
1920    named in entry or newSuperior.
1921
1922    Upon receipt of a ModifyDNRequest, a server will attempt to perform
1923    the name change and return the result in the Modify DN Response,
1924    defined as follows:
1925
1926         ModifyDNResponse ::= [APPLICATION 13] LDAPResult
1927
1928    For example, if the entry named in the entry field was <cn=John
1929    Smith,c=US>, the newrdn field was <cn=John Cougar Smith>, and the
1930    newSuperior field was absent, then this operation would attempt to
1931    rename the entry as <cn=John Cougar Smith,c=US>.  If there was
1932    already an entry with that name, the operation would fail with the
1933    entryAlreadyExists result code.
1934
1935    Servers MUST ensure that entries conform to user and system schema
1936    rules or other data model constraints.  For attribute types that
1937    specify no equality matching, the rules in Section 2.5.1 of [RFC4512]
1938    are followed (this pertains to newrdn and deleteoldrdn).
1939
1940    The object named in newSuperior MUST exist.  For example, if the
1941    client attempted to add <CN=JS,DC=Example,DC=NET>, the
1942    <DC=Example,DC=NET> entry did not exist, and the <DC=NET> entry did
1943    exist, then the server would return the noSuchObject result code with
1944    the matchedDN field containing <DC=NET>.
1945
1946    If the deleteoldrdn field is TRUE, the attribute values forming the
1947    old RDN (but not the new RDN) are deleted from the entry.  If the
1948    deleteoldrdn field is FALSE, the attribute values forming the old RDN
1949    will be retained as non-distinguished attribute values of the entry.
1950
1951    Note that X.500 restricts the ModifyDN operation to affect only
1952    entries that are contained within a single server.  If the LDAP
1953    server is mapped onto DAP, then this restriction will apply, and the
1954    affectsMultipleDSAs result code will be returned if this error
1955    occurred.  In general, clients MUST NOT expect to be able to perform
1956    arbitrary movements of entries and subtrees between servers or
1957    between naming contexts.
1958
1959
1960
1961
1962 Sermersheim                 Standards Track                    [Page 35]
1963 \f
1964 RFC 4511                         LDAPv3                        June 2006
1965
1966
1967 4.10.  Compare Operation
1968
1969    The Compare operation allows a client to compare an assertion value
1970    with the values of a particular attribute in a particular entry in
1971    the Directory.  The Compare Request is defined as follows:
1972
1973         CompareRequest ::= [APPLICATION 14] SEQUENCE {
1974              entry           LDAPDN,
1975              ava             AttributeValueAssertion }
1976
1977    Fields of the Compare Request are:
1978
1979    - entry: the name of the entry to be compared.  The server SHALL NOT
1980      dereference any aliases in locating the entry to be compared.
1981
1982    - ava: holds the attribute value assertion to be compared.
1983
1984    Upon receipt of a Compare Request, a server will attempt to perform
1985    the requested comparison and return the result in the Compare
1986    Response, defined as follows:
1987
1988         CompareResponse ::= [APPLICATION 15] LDAPResult
1989
1990    The resultCode is set to compareTrue, compareFalse, or an appropriate
1991    error.  compareTrue indicates that the assertion value in the ava
1992    field matches a value of the attribute or subtype according to the
1993    attribute's EQUALITY matching rule.  compareFalse indicates that the
1994    assertion value in the ava field and the values of the attribute or
1995    subtype did not match.  Other result codes indicate either that the
1996    result of the comparison was Undefined (Section 4.5.1.7), or that
1997    some error occurred.
1998
1999    Note that some directory systems may establish access controls that
2000    permit the values of certain attributes (such as userPassword) to be
2001    compared but not interrogated by other means.
2002
2003 4.11.  Abandon Operation
2004
2005    The function of the Abandon operation is to allow a client to request
2006    that the server abandon an uncompleted operation.  The Abandon
2007    Request is defined as follows:
2008
2009         AbandonRequest ::= [APPLICATION 16] MessageID
2010
2011    The MessageID is that of an operation that was requested earlier at
2012    this LDAP message layer.  The Abandon request itself has its own
2013    MessageID.  This is distinct from the MessageID of the earlier
2014    operation being abandoned.
2015
2016
2017
2018 Sermersheim                 Standards Track                    [Page 36]
2019 \f
2020 RFC 4511                         LDAPv3                        June 2006
2021
2022
2023    There is no response defined in the Abandon operation.  Upon receipt
2024    of an AbandonRequest, the server MAY abandon the operation identified
2025    by the MessageID.  Since the client cannot tell the difference
2026    between a successfully abandoned operation and an uncompleted
2027    operation, the application of the Abandon operation is limited to
2028    uses where the client does not require an indication of its outcome.
2029
2030    Abandon, Bind, Unbind, and StartTLS operations cannot be abandoned.
2031
2032    In the event that a server receives an Abandon Request on a Search
2033    operation in the midst of transmitting responses to the Search, that
2034    server MUST cease transmitting entry responses to the abandoned
2035    request immediately, and it MUST NOT send the SearchResultDone.  Of
2036    course, the server MUST ensure that only properly encoded LDAPMessage
2037    PDUs are transmitted.
2038
2039    The ability to abandon other (particularly update) operations is at
2040    the discretion of the server.
2041
2042    Clients should not send Abandon requests for the same operation
2043    multiple times, and they MUST also be prepared to receive results
2044    from operations they have abandoned (since these might have been in
2045    transit when the Abandon was requested or might not be able to be
2046    abandoned).
2047
2048    Servers MUST discard Abandon requests for messageIDs they do not
2049    recognize, for operations that cannot be abandoned, and for
2050    operations that have already been abandoned.
2051
2052 4.12.  Extended Operation
2053
2054    The Extended operation allows additional operations to be defined for
2055    services not already available in the protocol; for example, to Add
2056    operations to install transport layer security (see Section 4.14).
2057
2058    The Extended operation allows clients to make requests and receive
2059    responses with predefined syntaxes and semantics.  These may be
2060    defined in RFCs or be private to particular implementations.
2061
2062    Each Extended operation consists of an Extended request and an
2063    Extended response.
2064
2065         ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
2066              requestName      [0] LDAPOID,
2067              requestValue     [1] OCTET STRING OPTIONAL }
2068
2069
2070
2071
2072
2073
2074 Sermersheim                 Standards Track                    [Page 37]
2075 \f
2076 RFC 4511                         LDAPv3                        June 2006
2077
2078
2079    The requestName is a dotted-decimal representation of the unique
2080    OBJECT IDENTIFIER corresponding to the request.  The requestValue is
2081    information in a form defined by that request, encapsulated inside an
2082    OCTET STRING.
2083
2084    The server will respond to this with an LDAPMessage containing an
2085    ExtendedResponse.
2086
2087         ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
2088              COMPONENTS OF LDAPResult,
2089              responseName     [10] LDAPOID OPTIONAL,
2090              responseValue    [11] OCTET STRING OPTIONAL }
2091
2092    The responseName field, when present, contains an LDAPOID that is
2093    unique for this extended operation or response.  This field is
2094    optional (even when the extension specification defines an LDAPOID
2095    for use in this field).  The field will be absent whenever the server
2096    is unable or unwilling to determine the appropriate LDAPOID to
2097    return, for instance, when the requestName cannot be parsed or its
2098    value is not recognized.
2099
2100    Where the requestName is not recognized, the server returns
2101    protocolError.  (The server may return protocolError in other cases.)
2102
2103    The requestValue and responseValue fields contain information
2104    associated with the operation.  The format of these fields is defined
2105    by the specification of the Extended operation.  Implementations MUST
2106    be prepared to handle arbitrary contents of these fields, including
2107    zero bytes.  Values that are defined in terms of ASN.1 and BER-
2108    encoded according to Section 5.1 also follow the extensibility rules
2109    in Section 4.
2110
2111    Servers list the requestName of Extended Requests they recognize in
2112    the 'supportedExtension' attribute in the root DSE (Section 5.1 of
2113    [RFC4512]).
2114
2115    Extended operations may be specified in other documents.  The
2116    specification of an Extended operation consists of:
2117
2118    - the OBJECT IDENTIFIER assigned to the requestName,
2119
2120    - the OBJECT IDENTIFIER (if any) assigned to the responseName (note
2121      that the same OBJECT IDENTIFIER may be used for both the
2122      requestName and responseName),
2123
2124
2125
2126
2127
2128
2129
2130 Sermersheim                 Standards Track                    [Page 38]
2131 \f
2132 RFC 4511                         LDAPv3                        June 2006
2133
2134
2135    - the format of the contents of the requestValue and responseValue
2136      (if any), and
2137
2138    - the semantics of the operation.
2139
2140 4.13.  IntermediateResponse Message
2141
2142    While the Search operation provides a mechanism to return multiple
2143    response messages for a single Search request, other operations, by
2144    nature, do not provide for multiple response messages.
2145
2146    The IntermediateResponse message provides a general mechanism for
2147    defining single-request/multiple-response operations in LDAP.  This
2148    message is intended to be used in conjunction with the Extended
2149    operation to define new single-request/multiple-response operations
2150    or in conjunction with a control when extending existing LDAP
2151    operations in a way that requires them to return Intermediate
2152    response information.
2153
2154    It is intended that the definitions and descriptions of Extended
2155    operations and controls that make use of the IntermediateResponse
2156    message will define the circumstances when an IntermediateResponse
2157    message can be sent by a server and the associated meaning of an
2158    IntermediateResponse message sent in a particular circumstance.
2159
2160         IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
2161                 responseName     [0] LDAPOID OPTIONAL,
2162                 responseValue    [1] OCTET STRING OPTIONAL }
2163
2164    IntermediateResponse messages SHALL NOT be returned to the client
2165    unless the client issues a request that specifically solicits their
2166    return.  This document defines two forms of solicitation: Extended
2167    operation and request control.  IntermediateResponse messages are
2168    specified in documents describing the manner in which they are
2169    solicited (i.e., in the Extended operation or request control
2170    specification that uses them).  These specifications include:
2171
2172    - the OBJECT IDENTIFIER (if any) assigned to the responseName,
2173
2174    - the format of the contents of the responseValue (if any), and
2175
2176    - the semantics associated with the IntermediateResponse message.
2177
2178    Extensions that allow the return of multiple types of
2179    IntermediateResponse messages SHALL identify those types using unique
2180    responseName values (note that one of these may specify no value).
2181
2182
2183
2184
2185
2186 Sermersheim                 Standards Track                    [Page 39]
2187 \f
2188 RFC 4511                         LDAPv3                        June 2006
2189
2190
2191    Sections 4.13.1 and 4.13.2 describe additional requirements on the
2192    inclusion of responseName and responseValue in IntermediateResponse
2193    messages.
2194
2195 4.13.1.  Usage with LDAP ExtendedRequest and ExtendedResponse
2196
2197    A single-request/multiple-response operation may be defined using a
2198    single ExtendedRequest message to solicit zero or more
2199    IntermediateResponse messages of one or more kinds, followed by an
2200    ExtendedResponse message.
2201
2202 4.13.2.  Usage with LDAP Request Controls
2203
2204    A control's semantics may include the return of zero or more
2205    IntermediateResponse messages prior to returning the final result
2206    code for the operation.  One or more kinds of IntermediateResponse
2207    messages may be sent in response to a request control.
2208
2209    All IntermediateResponse messages associated with request controls
2210    SHALL include a responseName.  This requirement ensures that the
2211    client can correctly identify the source of IntermediateResponse
2212    messages when:
2213
2214    - two or more controls using IntermediateResponse messages are
2215      included in a request for any LDAP operation or
2216
2217    - one or more controls using IntermediateResponse messages are
2218      included in a request with an LDAP Extended operation that uses
2219      IntermediateResponse messages.
2220
2221 4.14.  StartTLS Operation
2222
2223    The Start Transport Layer Security (StartTLS) operation's purpose is
2224    to initiate installation of a TLS layer.  The StartTLS operation is
2225    defined using the Extended operation mechanism described in Section
2226    4.12.
2227
2228 4.14.1.  StartTLS Request
2229
2230    A client requests TLS establishment by transmitting a StartTLS
2231    request message to the server.  The StartTLS request is defined in
2232    terms of an ExtendedRequest.  The requestName is
2233    "1.3.6.1.4.1.1466.20037", and the requestValue field is always
2234    absent.
2235
2236
2237
2238
2239
2240
2241
2242 Sermersheim                 Standards Track                    [Page 40]
2243 \f
2244 RFC 4511                         LDAPv3                        June 2006
2245
2246
2247    The client MUST NOT send any LDAP PDUs at this LDAP message layer
2248    following this request until it receives a StartTLS Extended response
2249    and, in the case of a successful response, completes TLS
2250    negotiations.
2251
2252    Detected sequencing problems (particularly those detailed in Section
2253    3.1.1 of [RFC4513]) result in the resultCode being set to
2254    operationsError.
2255
2256    If the server does not support TLS (whether by design or by current
2257    configuration), it returns with the resultCode set to protocolError
2258    as described in Section 4.12.
2259
2260 4.14.2.  StartTLS Response
2261
2262    When a StartTLS request is received, servers supporting the operation
2263    MUST return a StartTLS response message to the requestor.  The
2264    responseName is "1.3.6.1.4.1.1466.20037" when provided (see Section
2265    4.12).  The responseValue is always absent.
2266
2267    If the server is willing and able to negotiate TLS, it returns the
2268    StartTLS response with the resultCode set to success.  Upon client
2269    receipt of a successful StartTLS response, protocol peers may
2270    commence with TLS negotiation as discussed in Section 3 of [RFC4513].
2271
2272    If the server is otherwise unwilling or unable to perform this
2273    operation, the server is to return an appropriate result code
2274    indicating the nature of the problem.  For example, if the TLS
2275    subsystem is not presently available, the server may indicate this by
2276    returning with the resultCode set to unavailable.  In cases where a
2277    non-success result code is returned, the LDAP session is left without
2278    a TLS layer.
2279
2280 4.14.3.  Removal of the TLS Layer
2281
2282    Either the client or server MAY remove the TLS layer and leave the
2283    LDAP message layer intact by sending and receiving a TLS closure
2284    alert.
2285
2286    The initiating protocol peer sends the TLS closure alert and MUST
2287    wait until it receives a TLS closure alert from the other peer before
2288    sending further LDAP PDUs.
2289
2290    When a protocol peer receives the initial TLS closure alert, it may
2291    choose to allow the LDAP message layer to remain intact.  In this
2292    case, it MUST immediately transmit a TLS closure alert.  Following
2293    this, it MAY send and receive LDAP PDUs.
2294
2295
2296
2297
2298 Sermersheim                 Standards Track                    [Page 41]
2299 \f
2300 RFC 4511                         LDAPv3                        June 2006
2301
2302
2303    Protocol peers MAY terminate the LDAP session after sending or
2304    receiving a TLS closure alert.
2305
2306 5.  Protocol Encoding, Connection, and Transfer
2307
2308    This protocol is designed to run over connection-oriented, reliable
2309    transports, where the data stream is divided into octets (8-bit
2310    units), with each octet and each bit being significant.
2311
2312    One underlying service, LDAP over TCP, is defined in Section 5.2.
2313    This service is generally applicable to applications providing or
2314    consuming X.500-based directory services on the Internet.  This
2315    specification was generally written with the TCP mapping in mind.
2316    Specifications detailing other mappings may encounter various
2317    obstacles.
2318
2319    Implementations of LDAP over TCP MUST implement the mapping as
2320    described in Section 5.2.
2321
2322    This table illustrates the relationship among the different layers
2323    involved in an exchange between two protocol peers:
2324
2325                +----------------------+
2326                |  LDAP message layer  |
2327                +----------------------+ > LDAP PDUs
2328                +----------------------+ < data
2329                |      SASL layer      |
2330                +----------------------+ > SASL-protected data
2331                +----------------------+ < data
2332                |       TLS layer      |
2333    Application +----------------------+ > TLS-protected data
2334    ------------+----------------------+ < data
2335      Transport | transport connection |
2336                +----------------------+
2337
2338 5.1.  Protocol Encoding
2339
2340    The protocol elements of LDAP SHALL be encoded for exchange using the
2341    Basic Encoding Rules [BER] of [ASN.1] with the following
2342    restrictions:
2343
2344    - Only the definite form of length encoding is used.
2345
2346    - OCTET STRING values are encoded in the primitive form only.
2347
2348    - If the value of a BOOLEAN type is true, the encoding of the value
2349      octet is set to hex "FF".
2350
2351
2352
2353
2354 Sermersheim                 Standards Track                    [Page 42]
2355 \f
2356 RFC 4511                         LDAPv3                        June 2006
2357
2358
2359    - If a value of a type is its default value, it is absent.  Only some
2360      BOOLEAN and INTEGER types have default values in this protocol
2361      definition.
2362
2363    These restrictions are meant to ease the overhead of encoding and
2364    decoding certain elements in BER.
2365
2366    These restrictions do not apply to ASN.1 types encapsulated inside of
2367    OCTET STRING values, such as attribute values, unless otherwise
2368    stated.
2369
2370 5.2.  Transmission Control Protocol (TCP)
2371
2372    The encoded LDAPMessage PDUs are mapped directly onto the TCP
2373    [RFC793] bytestream using the BER-based encoding described in Section
2374    5.1.  It is recommended that server implementations running over the
2375    TCP provide a protocol listener on the Internet Assigned Numbers
2376    Authority (IANA)-assigned LDAP port, 389 [PortReg].  Servers may
2377    instead provide a listener on a different port number.  Clients MUST
2378    support contacting servers on any valid TCP port.
2379
2380 5.3.  Termination of the LDAP session
2381
2382    Termination of the LDAP session is typically initiated by the client
2383    sending an UnbindRequest (Section 4.3), or by the server sending a
2384    Notice of Disconnection (Section 4.4.1).  In these cases, each
2385    protocol peer gracefully terminates the LDAP session by ceasing
2386    exchanges at the LDAP message layer, tearing down any SASL layer,
2387    tearing down any TLS layer, and closing the transport connection.
2388
2389    A protocol peer may determine that the continuation of any
2390    communication would be pernicious, and in this case, it may abruptly
2391    terminate the session by ceasing communication and closing the
2392    transport connection.
2393
2394    In either case, when the LDAP session is terminated, uncompleted
2395    operations are handled as specified in Section 3.1.
2396
2397 6.  Security Considerations
2398
2399    This version of the protocol provides facilities for simple
2400    authentication using a cleartext password, as well as any SASL
2401    [RFC4422] mechanism.  Installing SASL and/or TLS layers can provide
2402    integrity and other data security services.
2403
2404    It is also permitted that the server can return its credentials to
2405    the client, if it chooses to do so.
2406
2407
2408
2409
2410 Sermersheim                 Standards Track                    [Page 43]
2411 \f
2412 RFC 4511                         LDAPv3                        June 2006
2413
2414
2415    Use of cleartext password is strongly discouraged where the
2416    underlying transport service cannot guarantee confidentiality and may
2417    result in disclosure of the password to unauthorized parties.
2418
2419    Servers are encouraged to prevent directory modifications by clients
2420    that have authenticated anonymously [RFC4513].
2421
2422    Security considerations for authentication methods, SASL mechanisms,
2423    and TLS are described in [RFC4513].
2424
2425    Note that SASL authentication exchanges do not provide data
2426    confidentiality or integrity protection for the version or name
2427    fields of the BindRequest or the resultCode, diagnosticMessage, or
2428    referral fields of the BindResponse, nor for any information
2429    contained in controls attached to Bind requests or responses.  Thus,
2430    information contained in these fields SHOULD NOT be relied on unless
2431    it is otherwise protected (such as by establishing protections at the
2432    transport layer).
2433
2434    Implementors should note that various security factors (including
2435    authentication and authorization information and data security
2436    services) may change during the course of the LDAP session or even
2437    during the performance of a particular operation.  For instance,
2438    credentials could expire, authorization identities or access controls
2439    could change, or the underlying security layer(s) could be replaced
2440    or terminated.  Implementations should be robust in the handling of
2441    changing security factors.
2442
2443    In some cases, it may be appropriate to continue the operation even
2444    in light of security factor changes.  For instance, it may be
2445    appropriate to continue an Abandon operation regardless of the
2446    change, or to continue an operation when the change upgraded (or
2447    maintained) the security factor.  In other cases, it may be
2448    appropriate to fail or alter the processing of the operation.  For
2449    instance, if confidential protections were removed, it would be
2450    appropriate either to fail a request to return sensitive data or,
2451    minimally, to exclude the return of sensitive data.
2452
2453    Implementations that cache attributes and entries obtained via LDAP
2454    MUST ensure that access controls are maintained if that information
2455    is to be provided to multiple clients, since servers may have access
2456    control policies that prevent the return of entries or attributes in
2457    Search results except to particular authenticated clients.  For
2458    example, caches could serve result information only to the client
2459    whose request caused it to be in the cache.
2460
2461
2462
2463
2464
2465
2466 Sermersheim                 Standards Track                    [Page 44]
2467 \f
2468 RFC 4511                         LDAPv3                        June 2006
2469
2470
2471    Servers may return referrals or Search result references that
2472    redirect clients to peer servers.  It is possible for a rogue
2473    application to inject such referrals into the data stream in an
2474    attempt to redirect a client to a rogue server.  Clients are advised
2475    to be aware of this and possibly reject referrals when
2476    confidentiality measures are not in place.  Clients are advised to
2477    reject referrals from the StartTLS operation.
2478
2479    The matchedDN and diagnosticMessage fields, as well as some
2480    resultCode values (e.g., attributeOrValueExists and
2481    entryAlreadyExists), could disclose the presence or absence of
2482    specific data in the directory that is subject to access and other
2483    administrative controls.  Server implementations should restrict
2484    access to protected information equally under both normal and error
2485    conditions.
2486
2487    Protocol peers MUST be prepared to handle invalid and arbitrary-
2488    length protocol encodings.  Invalid protocol encodings include: BER
2489    encoding exceptions, format string and UTF-8 encoding exceptions,
2490    overflow exceptions, integer value exceptions, and binary mode on/off
2491    flag exceptions.  The LDAPv3 PROTOS [PROTOS-LDAP] test suite provides
2492    excellent examples of these exceptions and test cases used to
2493    discover flaws.
2494
2495    In the event that a protocol peer senses an attack that in its nature
2496    could cause damage due to further communication at any layer in the
2497    LDAP session, the protocol peer should abruptly terminate the LDAP
2498    session as described in Section 5.3.
2499
2500 7.  Acknowledgements
2501
2502    This document is based on RFC 2251 by Mark Wahl, Tim Howes, and Steve
2503    Kille.  RFC 2251 was a product of the IETF ASID Working Group.
2504
2505    It is also based on RFC 2830 by Jeff Hodges, RL "Bob" Morgan, and
2506    Mark Wahl.  RFC 2830 was a product of the IETF LDAPEXT Working Group.
2507
2508    It is also based on RFC 3771 by Roger Harrison and Kurt Zeilenga.
2509    RFC 3771 was an individual submission to the IETF.
2510
2511    This document is a product of the IETF LDAPBIS Working Group.
2512    Significant contributors of technical review and content include Kurt
2513    Zeilenga, Steven Legg, and Hallvard Furuseth.
2514
2515
2516
2517
2518
2519
2520
2521
2522 Sermersheim                 Standards Track                    [Page 45]
2523 \f
2524 RFC 4511                         LDAPv3                        June 2006
2525
2526
2527 8.  Normative References
2528
2529    [ASN.1]       ITU-T Recommendation X.680 (07/2002) | ISO/IEC 8824-
2530                  1:2002 "Information Technology - Abstract Syntax
2531                  Notation One (ASN.1): Specification of basic notation".
2532
2533    [BER]         ITU-T Rec. X.690 (07/2002) | ISO/IEC 8825-1:2002,
2534                  "Information technology - ASN.1 encoding rules:
2535                  Specification of Basic Encoding Rules (BER), Canonical
2536                  Encoding Rules (CER) and Distinguished Encoding Rules
2537                  (DER)", 2002.
2538
2539    [ISO10646]    Universal Multiple-Octet Coded Character Set (UCS) -
2540                  Architecture and Basic Multilingual Plane, ISO/IEC
2541                  10646-1 : 1993.
2542
2543    [RFC791]      Postel, J., "Internet Protocol", STD 5, RFC 791,
2544                  September 1981.
2545
2546    [RFC793]      Postel, J., "Transmission Control Protocol", STD 7, RFC
2547                  793, September 1981.
2548
2549    [RFC2119]     Bradner, S., "Key words for use in RFCs to Indicate
2550                  Requirement Levels", BCP 14, RFC 2119, March 1997.
2551
2552    [RFC3454]     Hoffman P. and M. Blanchet, "Preparation of
2553                  Internationalized Strings ('stringprep')", RFC 3454,
2554                  December 2002.
2555
2556    [RFC3629]     Yergeau, F., "UTF-8, a transformation format of ISO
2557                  10646", STD 63, RFC 3629, November 2003.
2558
2559    [RFC3986]     Berners-Lee, T., Fielding, R., and L. Masinter,
2560                  "Uniform Resource Identifier (URI): Generic Syntax",
2561                  STD 66, RFC 3986, January 2005.
2562
2563    [RFC4013]     Zeilenga, K., "SASLprep: Stringprep Profile for User
2564                  Names and Passwords", RFC 4013, February 2005.
2565
2566    [RFC4234]     Crocker, D. and P. Overell, "Augmented BNF for Syntax
2567                  Specifications: ABNF", RFC 4234, October 2005.
2568
2569    [RFC4346]     Dierks, T. and E. Rescorla, "The TLS Protocol Version
2570                  1.1", RFC 4346, March 2006.
2571
2572    [RFC4422]     Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple
2573                  Authentication and Security Layer (SASL)", RFC 4422,
2574                  June 2006.
2575
2576
2577
2578 Sermersheim                 Standards Track                    [Page 46]
2579 \f
2580 RFC 4511                         LDAPv3                        June 2006
2581
2582
2583    [RFC4510]     Zeilenga, K., Ed., "Lightweight Directory Access
2584                  Protocol (LDAP): Technical Specification Road Map", RFC
2585                  4510, June 2006.
2586
2587    [RFC4512]     Zeilenga, K., Lightweight Directory Access Protocol
2588                  (LDAP): Directory Information Models", RFC 4512, June
2589                  2006.
2590
2591    [RFC4513]     Harrison, R., Ed., "Lightweight Directory Access
2592                  Protocol (LDAP): Authentication Methods and Security
2593                  Mechanisms", RFC 4513, June 2006.
2594
2595    [RFC4514]     Zeilenga, K., Ed., "Lightweight Directory Access
2596                  Protocol (LDAP): String Representation of Distinguished
2597                  Names", RFC 4514, June 2006.
2598
2599    [RFC4516]     Smith, M., Ed. and T. Howes, "Lightweight Directory
2600                  Access Protocol (LDAP): Uniform Resource Locator", RFC
2601                  4516, June 2006.
2602
2603    [RFC4517]     Legg, S., Ed., "Lightweight Directory Access Protocol
2604                  (LDAP): Syntaxes and Matching Rules", RFC 4517, June
2605                  2006.
2606
2607    [RFC4520]     Zeilenga, K., "Internet Assigned Numbers Authority
2608                  (IANA) Considerations for the Lightweight Directory
2609                  Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006.
2610
2611    [Unicode]     The Unicode Consortium, "The Unicode Standard, Version
2612                  3.2.0" is defined by "The Unicode Standard, Version
2613                  3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-
2614                  61633-5), as amended by the "Unicode Standard Annex
2615                  #27: Unicode 3.1"
2616                  (http://www.unicode.org/reports/tr27/) and by the
2617                  "Unicode Standard Annex #28: Unicode 3.2"
2618                  (http://www.unicode.org/reports/tr28/).
2619
2620    [X.500]       ITU-T Rec. X.500, "The Directory: Overview of Concepts,
2621                  Models and Service", 1993.
2622
2623    [X.511]       ITU-T Rec. X.511, "The Directory: Abstract Service
2624                  Definition", 1993.
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634 Sermersheim                 Standards Track                    [Page 47]
2635 \f
2636 RFC 4511                         LDAPv3                        June 2006
2637
2638
2639 9.  Informative References
2640
2641    [CharModel]   Whistler, K. and M. Davis, "Unicode Technical Report
2642                  #17, Character Encoding Model", UTR17,
2643                  <http://www.unicode.org/unicode/reports/tr17/>, August
2644                  2000.
2645
2646    [Glossary]    The Unicode Consortium, "Unicode Glossary",
2647                  <http://www.unicode.org/glossary/>.
2648
2649    [PortReg]     IANA, "Port Numbers",
2650                  <http://www.iana.org/assignments/port-numbers>.
2651
2652    [PROTOS-LDAP] University of Oulu, "PROTOS Test-Suite: c06-ldapv3"
2653                  <http://www.ee.oulu.fi/research/ouspg/protos/testing/
2654                  c06/ldapv3/>.
2655
2656 10.  IANA Considerations
2657
2658    The Internet Assigned Numbers Authority (IANA) has updated the LDAP
2659    result code registry to indicate that this document provides the
2660    definitive technical specification for result codes 0-36, 48-54, 64-
2661    70, 80-90.  It is also noted that one resultCode value
2662    (strongAuthRequired) has been renamed (to strongerAuthRequired).
2663
2664    The IANA has also updated the LDAP Protocol Mechanism registry to
2665    indicate that this document and [RFC4513] provides the definitive
2666    technical specification for the StartTLS (1.3.6.1.4.1.1466.20037)
2667    Extended operation.
2668
2669    IANA has assigned LDAP Object Identifier 18 [RFC4520] to identify the
2670    ASN.1 module defined in this document.
2671
2672         Subject: Request for LDAP Object Identifier Registration
2673         Person & email address to contact for further information:
2674              Jim Sermersheim <jimse@novell.com>
2675         Specification: RFC 4511
2676         Author/Change Controller: IESG
2677         Comments:
2678              Identifies the LDAP ASN.1 module
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690 Sermersheim                 Standards Track                    [Page 48]
2691 \f
2692 RFC 4511                         LDAPv3                        June 2006
2693
2694
2695 Appendix A.  LDAP Result Codes
2696
2697    This normative appendix details additional considerations regarding
2698    LDAP result codes and provides a brief, general description of each
2699    LDAP result code enumerated in Section 4.1.9.
2700
2701    Additional result codes MAY be defined for use with extensions
2702    [RFC4520].  Client implementations SHALL treat any result code that
2703    they do not recognize as an unknown error condition.
2704
2705    The descriptions provided here do not fully account for result code
2706    substitutions used to prevent unauthorized disclosures (such as
2707    substitution of noSuchObject for insufficientAccessRights, or
2708    invalidCredentials for insufficientAccessRights).
2709
2710 A.1.  Non-Error Result Codes
2711
2712    These result codes (called "non-error" result codes) do not indicate
2713    an error condition:
2714
2715         success (0),
2716         compareFalse (5),
2717         compareTrue (6),
2718         referral (10), and
2719         saslBindInProgress (14).
2720
2721    The success, compareTrue, and compareFalse result codes indicate
2722    successful completion (and, hence, are referred to as "successful"
2723    result codes).
2724
2725    The referral and saslBindInProgress result codes indicate the client
2726    needs to take additional action to complete the operation.
2727
2728 A.2.  Result Codes
2729
2730    Existing LDAP result codes are described as follows:
2731
2732       success (0)
2733          Indicates the successful completion of an operation.  Note:
2734          this code is not used with the Compare operation.  See
2735          compareFalse (5) and compareTrue (6).
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746 Sermersheim                 Standards Track                    [Page 49]
2747 \f
2748 RFC 4511                         LDAPv3                        June 2006
2749
2750
2751       operationsError (1)
2752          Indicates that the operation is not properly sequenced with
2753          relation to other operations (of same or different type).
2754
2755          For example, this code is returned if the client attempts to
2756          StartTLS [RFC4346] while there are other uncompleted operations
2757          or if a TLS layer was already installed.
2758
2759       protocolError (2)
2760          Indicates the server received data that is not well-formed.
2761
2762          For Bind operation only, this code is also used to indicate
2763          that the server does not support the requested protocol
2764          version.
2765
2766          For Extended operations only, this code is also used to
2767          indicate that the server does not support (by design or
2768          configuration) the Extended operation associated with the
2769          requestName.
2770
2771          For request operations specifying multiple controls, this may
2772          be used to indicate that the server cannot ignore the order
2773          of the controls as specified, or that the combination of the
2774          specified controls is invalid or unspecified.
2775
2776       timeLimitExceeded (3)
2777          Indicates that the time limit specified by the client was
2778          exceeded before the operation could be completed.
2779
2780       sizeLimitExceeded (4)
2781          Indicates that the size limit specified by the client was
2782          exceeded before the operation could be completed.
2783
2784       compareFalse (5)
2785          Indicates that the Compare operation has successfully
2786          completed and the assertion has evaluated to FALSE or
2787          Undefined.
2788
2789       compareTrue (6)
2790          Indicates that the Compare operation has successfully
2791          completed and the assertion has evaluated to TRUE.
2792
2793       authMethodNotSupported (7)
2794          Indicates that the authentication method or mechanism is not
2795          supported.
2796
2797
2798
2799
2800
2801
2802 Sermersheim                 Standards Track                    [Page 50]
2803 \f
2804 RFC 4511                         LDAPv3                        June 2006
2805
2806
2807       strongerAuthRequired (8)
2808          Indicates the server requires strong(er) authentication in
2809          order to complete the operation.
2810
2811          When used with the Notice of Disconnection operation, this
2812          code indicates that the server has detected that an
2813          established security association between the client and
2814          server has unexpectedly failed or been compromised.
2815
2816       referral (10)
2817          Indicates that a referral needs to be chased to complete the
2818          operation (see Section 4.1.10).
2819
2820       adminLimitExceeded (11)
2821          Indicates that an administrative limit has been exceeded.
2822
2823       unavailableCriticalExtension (12)
2824          Indicates a critical control is unrecognized (see Section
2825          4.1.11).
2826
2827       confidentialityRequired (13)
2828          Indicates that data confidentiality protections are required.
2829
2830       saslBindInProgress (14)
2831          Indicates the server requires the client to send a new bind
2832          request, with the same SASL mechanism, to continue the
2833          authentication process (see Section 4.2).
2834
2835       noSuchAttribute (16)
2836          Indicates that the named entry does not contain the specified
2837          attribute or attribute value.
2838
2839       undefinedAttributeType (17)
2840          Indicates that a request field contains an unrecognized
2841          attribute description.
2842
2843       inappropriateMatching (18)
2844          Indicates that an attempt was made (e.g., in an assertion) to
2845          use a matching rule not defined for the attribute type
2846          concerned.
2847
2848       constraintViolation (19)
2849          Indicates that the client supplied an attribute value that
2850          does not conform to the constraints placed upon it by the
2851          data model.
2852
2853          For example, this code is returned when multiple values are
2854          supplied to an attribute that has a SINGLE-VALUE constraint.
2855
2856
2857
2858 Sermersheim                 Standards Track                    [Page 51]
2859 \f
2860 RFC 4511                         LDAPv3                        June 2006
2861
2862
2863       attributeOrValueExists (20)
2864          Indicates that the client supplied an attribute or value to
2865          be added to an entry, but the attribute or value already
2866          exists.
2867
2868       invalidAttributeSyntax (21)
2869          Indicates that a purported attribute value does not conform
2870          to the syntax of the attribute.
2871
2872       noSuchObject (32)
2873          Indicates that the object does not exist in the DIT.
2874
2875       aliasProblem (33)
2876          Indicates that an alias problem has occurred.  For example,
2877          the code may used to indicate an alias has been dereferenced
2878          that names no object.
2879
2880       invalidDNSyntax (34)
2881          Indicates that an LDAPDN or RelativeLDAPDN field (e.g., search
2882          base, target entry, ModifyDN newrdn, etc.) of a request does
2883          not conform to the required syntax or contains attribute
2884          values that do not conform to the syntax of the attribute's
2885          type.
2886
2887       aliasDereferencingProblem (36)
2888          Indicates that a problem occurred while dereferencing an
2889          alias.  Typically, an alias was encountered in a situation
2890          where it was not allowed or where access was denied.
2891
2892       inappropriateAuthentication (48)
2893          Indicates the server requires the client that had attempted
2894          to bind anonymously or without supplying credentials to
2895          provide some form of credentials.
2896
2897       invalidCredentials (49)
2898          Indicates that the provided credentials (e.g., the user's name
2899          and password) are invalid.
2900
2901       insufficientAccessRights (50)
2902          Indicates that the client does not have sufficient access
2903          rights to perform the operation.
2904
2905       busy (51)
2906          Indicates that the server is too busy to service the
2907          operation.
2908
2909
2910
2911
2912
2913
2914 Sermersheim                 Standards Track                    [Page 52]
2915 \f
2916 RFC 4511                         LDAPv3                        June 2006
2917
2918
2919       unavailable (52)
2920          Indicates that the server is shutting down or a subsystem
2921          necessary to complete the operation is offline.
2922
2923       unwillingToPerform (53)
2924          Indicates that the server is unwilling to perform the
2925          operation.
2926
2927       loopDetect (54)
2928          Indicates that the server has detected an internal loop (e.g.,
2929          while dereferencing aliases or chaining an operation).
2930
2931       namingViolation (64)
2932          Indicates that the entry's name violates naming restrictions.
2933
2934       objectClassViolation (65)
2935          Indicates that the entry violates object class restrictions.
2936
2937       notAllowedOnNonLeaf (66)
2938          Indicates that the operation is inappropriately acting upon a
2939          non-leaf entry.
2940
2941       notAllowedOnRDN (67)
2942          Indicates that the operation is inappropriately attempting to
2943          remove a value that forms the entry's relative distinguished
2944          name.
2945
2946       entryAlreadyExists (68)
2947          Indicates that the request cannot be fulfilled (added, moved,
2948          or renamed) as the target entry already exists.
2949
2950       objectClassModsProhibited (69)
2951          Indicates that an attempt to modify the object class(es) of
2952          an entry's 'objectClass' attribute is prohibited.
2953
2954          For example, this code is returned when a client attempts to
2955          modify the structural object class of an entry.
2956
2957       affectsMultipleDSAs (71)
2958          Indicates that the operation cannot be performed as it would
2959          affect multiple servers (DSAs).
2960
2961       other (80)
2962          Indicates the server has encountered an internal error.
2963
2964
2965
2966
2967
2968
2969
2970 Sermersheim                 Standards Track                    [Page 53]
2971 \f
2972 RFC 4511                         LDAPv3                        June 2006
2973
2974
2975 Appendix B.  Complete ASN.1 Definition
2976
2977    This appendix is normative.
2978
2979         Lightweight-Directory-Access-Protocol-V3 {1 3 6 1 1 18}
2980         -- Copyright (C) The Internet Society (2006).  This version of
2981         -- this ASN.1 module is part of RFC 4511; see the RFC itself
2982         -- for full legal notices.
2983         DEFINITIONS
2984         IMPLICIT TAGS
2985         EXTENSIBILITY IMPLIED ::=
2986
2987         BEGIN
2988
2989         LDAPMessage ::= SEQUENCE {
2990              messageID       MessageID,
2991              protocolOp      CHOICE {
2992                   bindRequest           BindRequest,
2993                   bindResponse          BindResponse,
2994                   unbindRequest         UnbindRequest,
2995                   searchRequest         SearchRequest,
2996                   searchResEntry        SearchResultEntry,
2997                   searchResDone         SearchResultDone,
2998                   searchResRef          SearchResultReference,
2999                   modifyRequest         ModifyRequest,
3000                   modifyResponse        ModifyResponse,
3001                   addRequest            AddRequest,
3002                   addResponse           AddResponse,
3003                   delRequest            DelRequest,
3004                   delResponse           DelResponse,
3005                   modDNRequest          ModifyDNRequest,
3006                   modDNResponse         ModifyDNResponse,
3007                   compareRequest        CompareRequest,
3008                   compareResponse       CompareResponse,
3009                   abandonRequest        AbandonRequest,
3010                   extendedReq           ExtendedRequest,
3011                   extendedResp          ExtendedResponse,
3012                   ...,
3013                   intermediateResponse  IntermediateResponse },
3014              controls       [0] Controls OPTIONAL }
3015
3016         MessageID ::= INTEGER (0 ..  maxInt)
3017
3018         maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
3019
3020         LDAPString ::= OCTET STRING -- UTF-8 encoded,
3021                                     -- [ISO10646] characters
3022
3023
3024
3025
3026 Sermersheim                 Standards Track                    [Page 54]
3027 \f
3028 RFC 4511                         LDAPv3                        June 2006
3029
3030
3031         LDAPOID ::= OCTET STRING -- Constrained to <numericoid>
3032                                  -- [RFC4512]
3033
3034         LDAPDN ::= LDAPString -- Constrained to <distinguishedName>
3035                               -- [RFC4514]
3036
3037         RelativeLDAPDN ::= LDAPString -- Constrained to <name-component>
3038                                       -- [RFC4514]
3039
3040         AttributeDescription ::= LDAPString
3041                                 -- Constrained to <attributedescription>
3042                                 -- [RFC4512]
3043
3044         AttributeValue ::= OCTET STRING
3045
3046         AttributeValueAssertion ::= SEQUENCE {
3047              attributeDesc   AttributeDescription,
3048              assertionValue  AssertionValue }
3049
3050         AssertionValue ::= OCTET STRING
3051
3052         PartialAttribute ::= SEQUENCE {
3053              type       AttributeDescription,
3054              vals       SET OF value AttributeValue }
3055
3056         Attribute ::= PartialAttribute(WITH COMPONENTS {
3057              ...,
3058              vals (SIZE(1..MAX))})
3059
3060         MatchingRuleId ::= LDAPString
3061
3062         LDAPResult ::= SEQUENCE {
3063              resultCode         ENUMERATED {
3064                   success                      (0),
3065                   operationsError              (1),
3066                   protocolError                (2),
3067                   timeLimitExceeded            (3),
3068                   sizeLimitExceeded            (4),
3069                   compareFalse                 (5),
3070                   compareTrue                  (6),
3071                   authMethodNotSupported       (7),
3072                   strongerAuthRequired         (8),
3073                        -- 9 reserved --
3074                   referral                     (10),
3075                   adminLimitExceeded           (11),
3076                   unavailableCriticalExtension (12),
3077                   confidentialityRequired      (13),
3078                   saslBindInProgress           (14),
3079
3080
3081
3082 Sermersheim                 Standards Track                    [Page 55]
3083 \f
3084 RFC 4511                         LDAPv3                        June 2006
3085
3086
3087                   noSuchAttribute              (16),
3088                   undefinedAttributeType       (17),
3089                   inappropriateMatching        (18),
3090                   constraintViolation          (19),
3091                   attributeOrValueExists       (20),
3092                   invalidAttributeSyntax       (21),
3093                        -- 22-31 unused --
3094                   noSuchObject                 (32),
3095                   aliasProblem                 (33),
3096                   invalidDNSyntax              (34),
3097                        -- 35 reserved for undefined isLeaf --
3098                   aliasDereferencingProblem    (36),
3099                        -- 37-47 unused --
3100                   inappropriateAuthentication  (48),
3101                   invalidCredentials           (49),
3102                   insufficientAccessRights     (50),
3103                   busy                         (51),
3104                   unavailable                  (52),
3105                   unwillingToPerform           (53),
3106                   loopDetect                   (54),
3107                        -- 55-63 unused --
3108                   namingViolation              (64),
3109                   objectClassViolation         (65),
3110                   notAllowedOnNonLeaf          (66),
3111                   notAllowedOnRDN              (67),
3112                   entryAlreadyExists           (68),
3113                   objectClassModsProhibited    (69),
3114                        -- 70 reserved for CLDAP --
3115                   affectsMultipleDSAs          (71),
3116                        -- 72-79 unused --
3117                   other                        (80),
3118                   ...  },
3119              matchedDN          LDAPDN,
3120              diagnosticMessage  LDAPString,
3121              referral           [3] Referral OPTIONAL }
3122
3123         Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI
3124
3125         URI ::= LDAPString     -- limited to characters permitted in
3126                                -- URIs
3127
3128         Controls ::= SEQUENCE OF control Control
3129
3130         Control ::= SEQUENCE {
3131              controlType             LDAPOID,
3132              criticality             BOOLEAN DEFAULT FALSE,
3133              controlValue            OCTET STRING OPTIONAL }
3134
3135
3136
3137
3138 Sermersheim                 Standards Track                    [Page 56]
3139 \f
3140 RFC 4511                         LDAPv3                        June 2006
3141
3142
3143         BindRequest ::= [APPLICATION 0] SEQUENCE {
3144              version                 INTEGER (1 ..  127),
3145              name                    LDAPDN,
3146              authentication          AuthenticationChoice }
3147
3148         AuthenticationChoice ::= CHOICE {
3149              simple                  [0] OCTET STRING,
3150                                      -- 1 and 2 reserved
3151              sasl                    [3] SaslCredentials,
3152              ...  }
3153
3154         SaslCredentials ::= SEQUENCE {
3155              mechanism               LDAPString,
3156              credentials             OCTET STRING OPTIONAL }
3157
3158         BindResponse ::= [APPLICATION 1] SEQUENCE {
3159              COMPONENTS OF LDAPResult,
3160              serverSaslCreds    [7] OCTET STRING OPTIONAL }
3161
3162         UnbindRequest ::= [APPLICATION 2] NULL
3163
3164         SearchRequest ::= [APPLICATION 3] SEQUENCE {
3165              baseObject      LDAPDN,
3166              scope           ENUMERATED {
3167                   baseObject              (0),
3168                   singleLevel             (1),
3169                   wholeSubtree            (2),
3170                   ...  },
3171              derefAliases    ENUMERATED {
3172                   neverDerefAliases       (0),
3173                   derefInSearching        (1),
3174                   derefFindingBaseObj     (2),
3175                   derefAlways             (3) },
3176              sizeLimit       INTEGER (0 ..  maxInt),
3177              timeLimit       INTEGER (0 ..  maxInt),
3178              typesOnly       BOOLEAN,
3179              filter          Filter,
3180              attributes      AttributeSelection }
3181
3182         AttributeSelection ::= SEQUENCE OF selector LDAPString
3183                        -- The LDAPString is constrained to
3184                        -- <attributeSelector> in Section 4.5.1.8
3185
3186         Filter ::= CHOICE {
3187              and             [0] SET SIZE (1..MAX) OF filter Filter,
3188              or              [1] SET SIZE (1..MAX) OF filter Filter,
3189              not             [2] Filter,
3190              equalityMatch   [3] AttributeValueAssertion,
3191
3192
3193
3194 Sermersheim                 Standards Track                    [Page 57]
3195 \f
3196 RFC 4511                         LDAPv3                        June 2006
3197
3198
3199              substrings      [4] SubstringFilter,
3200              greaterOrEqual  [5] AttributeValueAssertion,
3201              lessOrEqual     [6] AttributeValueAssertion,
3202              present         [7] AttributeDescription,
3203              approxMatch     [8] AttributeValueAssertion,
3204              extensibleMatch [9] MatchingRuleAssertion,
3205              ...  }
3206
3207         SubstringFilter ::= SEQUENCE {
3208              type           AttributeDescription,
3209              substrings     SEQUENCE SIZE (1..MAX) OF substring CHOICE {
3210                   initial [0] AssertionValue,  -- can occur at most once
3211                   any     [1] AssertionValue,
3212                   final   [2] AssertionValue } -- can occur at most once
3213              }
3214
3215         MatchingRuleAssertion ::= SEQUENCE {
3216              matchingRule    [1] MatchingRuleId OPTIONAL,
3217              type            [2] AttributeDescription OPTIONAL,
3218              matchValue      [3] AssertionValue,
3219              dnAttributes    [4] BOOLEAN DEFAULT FALSE }
3220
3221         SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
3222              objectName      LDAPDN,
3223              attributes      PartialAttributeList }
3224
3225         PartialAttributeList ::= SEQUENCE OF
3226                              partialAttribute PartialAttribute
3227
3228         SearchResultReference ::= [APPLICATION 19] SEQUENCE
3229                                   SIZE (1..MAX) OF uri URI
3230
3231         SearchResultDone ::= [APPLICATION 5] LDAPResult
3232
3233         ModifyRequest ::= [APPLICATION 6] SEQUENCE {
3234              object          LDAPDN,
3235              changes         SEQUENCE OF change SEQUENCE {
3236                   operation       ENUMERATED {
3237                        add     (0),
3238                        delete  (1),
3239                        replace (2),
3240                        ...  },
3241                   modification    PartialAttribute } }
3242
3243         ModifyResponse ::= [APPLICATION 7] LDAPResult
3244
3245
3246
3247
3248
3249
3250 Sermersheim                 Standards Track                    [Page 58]
3251 \f
3252 RFC 4511                         LDAPv3                        June 2006
3253
3254
3255         AddRequest ::= [APPLICATION 8] SEQUENCE {
3256              entry           LDAPDN,
3257              attributes      AttributeList }
3258
3259         AttributeList ::= SEQUENCE OF attribute Attribute
3260
3261         AddResponse ::= [APPLICATION 9] LDAPResult
3262
3263         DelRequest ::= [APPLICATION 10] LDAPDN
3264
3265         DelResponse ::= [APPLICATION 11] LDAPResult
3266
3267         ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
3268              entry           LDAPDN,
3269              newrdn          RelativeLDAPDN,
3270              deleteoldrdn    BOOLEAN,
3271              newSuperior     [0] LDAPDN OPTIONAL }
3272
3273         ModifyDNResponse ::= [APPLICATION 13] LDAPResult
3274
3275         CompareRequest ::= [APPLICATION 14] SEQUENCE {
3276              entry           LDAPDN,
3277              ava             AttributeValueAssertion }
3278
3279         CompareResponse ::= [APPLICATION 15] LDAPResult
3280
3281         AbandonRequest ::= [APPLICATION 16] MessageID
3282
3283         ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
3284              requestName      [0] LDAPOID,
3285              requestValue     [1] OCTET STRING OPTIONAL }
3286
3287         ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
3288              COMPONENTS OF LDAPResult,
3289              responseName     [10] LDAPOID OPTIONAL,
3290              responseValue    [11] OCTET STRING OPTIONAL }
3291
3292         IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
3293              responseName     [0] LDAPOID OPTIONAL,
3294              responseValue    [1] OCTET STRING OPTIONAL }
3295
3296         END
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306 Sermersheim                 Standards Track                    [Page 59]
3307 \f
3308 RFC 4511                         LDAPv3                        June 2006
3309
3310
3311 Appendix C.  Changes
3312
3313    This appendix is non-normative.
3314
3315    This appendix summarizes substantive changes made to RFC 2251, RFC
3316    2830, and RFC 3771.
3317
3318 C.1.  Changes Made to RFC 2251
3319
3320    This section summarizes the substantive changes made to Sections 1,
3321    2, 3.1, and 4, and the remainder of RFC 2251.  Readers should
3322    consult [RFC4512] and [RFC4513] for summaries of changes to other
3323    sections.
3324
3325 C.1.1.  Section 1 (Status of this Memo)
3326
3327    - Removed IESG note.  Post publication of RFC 2251, mandatory LDAP
3328      authentication mechanisms have been standardized which are
3329      sufficient to remove this note.  See [RFC4513] for authentication
3330      mechanisms.
3331
3332 C.1.2.  Section 3.1 (Protocol Model) and others
3333
3334    - Removed notes giving history between LDAP v1, v2, and v3.  Instead,
3335      added sufficient language so that this document can stand on its
3336      own.
3337
3338 C.1.3.  Section 4 (Elements of Protocol)
3339
3340    - Clarified where the extensibility features of ASN.1 apply to the
3341      protocol.  This change affected various ASN.1 types by the
3342      inclusion of ellipses (...) to certain elements.
3343    - Removed the requirement that servers that implement version 3 or
3344      later MUST provide the 'supportedLDAPVersion' attribute.  This
3345      statement provided no interoperability advantages.
3346
3347 C.1.4.  Section 4.1.1 (Message Envelope)
3348
3349    - There was a mandatory requirement for the server to return a
3350      Notice of Disconnection and drop the transport connection when a
3351      PDU is malformed in a certain way.  This has been updated such that
3352      the server SHOULD return the Notice of Disconnection, and it MUST
3353      terminate the LDAP Session.
3354
3355 C.1.5.  Section 4.1.1.1 (Message ID)
3356
3357    - Required that the messageID of requests MUST be non-zero as the
3358      zero is reserved for Notice of Disconnection.
3359
3360
3361
3362 Sermersheim                 Standards Track                    [Page 60]
3363 \f
3364 RFC 4511                         LDAPv3                        June 2006
3365
3366
3367    - Specified when it is and isn't appropriate to return an already
3368      used messageID.  RFC 2251 accidentally imposed synchronous server
3369      behavior in its wording of this.
3370
3371 C.1.6.  Section 4.1.2 (String Types)
3372
3373    - Stated that LDAPOID is constrained to <numericoid> from [RFC4512].
3374
3375 C.1.7.  Section 4.1.5.1 (Binary Option) and others
3376
3377    - Removed the Binary Option from the specification.  There are
3378      numerous interoperability problems associated with this method of
3379      alternate attribute type encoding.  Work to specify a suitable
3380      replacement is ongoing.
3381
3382 C.1.8.  Section 4.1.8 (Attribute)
3383
3384    - Combined the definitions of PartialAttribute and Attribute here,
3385      and defined Attribute in terms of PartialAttribute.
3386
3387 C.1.9.  Section 4.1.10 (Result Message)
3388
3389    - Renamed "errorMessage" to "diagnosticMessage" as it is allowed to
3390      be sent for non-error results.
3391    - Moved some language into Appendix A, and referred the reader there.
3392    - Allowed matchedDN to be present for other result codes than those
3393      listed in RFC 2251.
3394    - Renamed the code "strongAuthRequired" to "strongerAuthRequired" to
3395      clarify that this code may often be returned to indicate that a
3396      stronger authentication is needed to perform a given operation.
3397
3398 C.1.10.  Section 4.1.11 (Referral)
3399
3400    - Defined referrals in terms of URIs rather than URLs.
3401    - Removed the requirement that all referral URIs MUST be equally
3402      capable of progressing the operation.  The statement was ambiguous
3403      and provided no instructions on how to carry it out.
3404    - Added the requirement that clients MUST NOT loop between servers.
3405    - Clarified the instructions for using LDAPURLs in referrals, and in
3406      doing so added a recommendation that the scope part be present.
3407    - Removed imperatives which required clients to use URLs in specific
3408      ways to progress an operation.  These did nothing for
3409      interoperability.
3410
3411
3412
3413
3414
3415
3416
3417
3418 Sermersheim                 Standards Track                    [Page 61]
3419 \f
3420 RFC 4511                         LDAPv3                        June 2006
3421
3422
3423 C.1.11.  Section 4.1.12 (Controls)
3424
3425    - Specified how control values defined in terms of ASN.1 are to be
3426      encoded.
3427    - Noted that the criticality field is only applied to request
3428      messages (except UnbindRequest), and must be ignored when present
3429      on response messages and UnbindRequest.
3430    - Specified that non-critical controls may be ignored at the
3431      server's discretion.  There was confusion in the original wording
3432      which led some to believe that recognized controls may not be
3433      ignored as long as they were associated with a proper request.
3434    - Added language regarding combinations of controls and the ordering
3435      of controls on a message.
3436    - Specified that when the semantics of the combination of controls
3437      is undefined or unknown, it results in a protocolError.
3438    - Changed "The server MUST be prepared" to "Implementations MUST be
3439      prepared" in paragraph 8 to reflect that both client and server
3440      implementations must be able to handle this (as both parse
3441      controls).
3442
3443 C.1.12.  Section 4.2 (Bind Operation)
3444
3445    - Mandated that servers return protocolError when the version is not
3446      supported.
3447    - Disambiguated behavior when the simple authentication is used, the
3448      name is empty, and the password is non-empty.
3449    - Required servers to not dereference aliases for Bind.  This was
3450      added for consistency with other operations and to help ensure
3451      data consistency.
3452    - Required that textual passwords be transferred as UTF-8 encoded
3453      Unicode, and added recommendations on string preparation.  This was
3454      to help ensure interoperability of passwords being sent from
3455      different clients.
3456
3457 C.1.13.  Section 4.2.1 (Sequencing of the Bind Request)
3458
3459    - This section was largely reorganized for readability, and language
3460      was added to clarify the authentication state of failed and
3461      abandoned Bind operations.
3462    - Removed: "If a SASL transfer encryption or integrity mechanism has
3463      been negotiated, that mechanism does not support the changing of
3464      credentials from one identity to another, then the client MUST
3465      instead establish a new connection."
3466      If there are dependencies between multiple negotiations of a
3467      particular SASL mechanism, the technical specification for that
3468      SASL mechanism details how applications are to deal with them.
3469      LDAP should not require any special handling.
3470    - Dropped MUST imperative in paragraph 3 to align with [RFC2119].
3471
3472
3473
3474 Sermersheim                 Standards Track                    [Page 62]
3475 \f
3476 RFC 4511                         LDAPv3                        June 2006
3477
3478
3479    - Mandated that clients not send non-Bind operations while a Bind is
3480      in progress, and suggested that servers not process them if they
3481      are received.  This is needed to ensure proper sequencing of the
3482      Bind in relationship to other operations.
3483
3484 C.1.14.  Section 4.2.3 (Bind Response)
3485
3486    - Moved most error-related text to Appendix A, and added text
3487      regarding certain errors used in conjunction with the Bind
3488      operation.
3489    - Prohibited the server from specifying serverSaslCreds when not
3490      appropriate.
3491
3492 C.1.15.  Section 4.3 (Unbind Operation)
3493
3494    - Specified that both peers are to cease transmission and terminate
3495      the LDAP session for the Unbind operation.
3496
3497 C.1.16.  Section 4.4 (Unsolicited Notification)
3498
3499    - Added instructions for future specifications of Unsolicited
3500      Notifications.
3501
3502 C.1.17.  Section 4.5.1 (Search Request)
3503
3504    - SearchRequest attributes is now defined as an AttributeSelection
3505      type rather than AttributeDescriptionList, and an ABNF is
3506      provided.
3507    - SearchRequest attributes may contain duplicate attribute
3508      descriptions.  This was previously prohibited.  Now servers are
3509      instructed to ignore subsequent names when they are duplicated.
3510      This was relaxed in order to allow different short names and also
3511      OIDs to be requested for an attribute.
3512    - The present search filter now evaluates to Undefined when the
3513      specified attribute is not known to the server.  It used to
3514      evaluate to FALSE, which caused behavior inconsistent with what
3515      most would expect, especially when the 'not' operator was used.
3516    - The Filter choice SubstringFilter substrings type is now defined
3517      with a lower bound of 1.
3518    - The SubstringFilter substrings 'initial, 'any', and 'final' types
3519      are now AssertionValue rather than LDAPString.  Also, added
3520      imperatives stating that 'initial' (if present) must be listed
3521      first, and 'final' (if present) must be listed last.
3522    - Disambiguated the semantics of the derefAliases choices.  There was
3523      question as to whether derefInSearching applied to the base object
3524      in a wholeSubtree Search.
3525    - Added instructions for equalityMatch, substrings, greaterOrEqual,
3526      lessOrEqual, and approxMatch.
3527
3528
3529
3530 Sermersheim                 Standards Track                    [Page 63]
3531 \f
3532 RFC 4511                         LDAPv3                        June 2006
3533
3534
3535
3536 C.1.18.  Section 4.5.2 (Search Result)
3537
3538    - Recommended that servers not use attribute short names when it
3539      knows they are ambiguous or may cause interoperability problems.
3540    - Removed all mention of ExtendedResponse due to lack of
3541      implementation.
3542
3543 C.1.19.  Section 4.5.3 (Continuation References in the Search Result)
3544
3545    - Made changes similar to those made to Section 4.1.11.
3546
3547 C.1.20.  Section 4.5.3.1 (Example)
3548
3549    - Fixed examples to adhere to changes made to Section 4.5.3.
3550
3551 C.1.21.  Section 4.6 (Modify Operation)
3552
3553    - Replaced AttributeTypeAndValues with Attribute as they are
3554      equivalent.
3555    - Specified the types of modification changes that might
3556      temporarily violate schema.  Some readers were under the impression
3557      that any temporary schema violation was allowed.
3558
3559 C.1.22.  Section 4.7 (Add Operation)
3560
3561    - Aligned Add operation with X.511 in that the attributes of the RDN
3562      are used in conjunction with the listed attributes to create the
3563      entry.  Previously, Add required that the distinguished values be
3564      present in the listed attributes.
3565    - Removed requirement that the objectClass attribute MUST be
3566      specified as some DSE types do not require this attribute.
3567      Instead, generic wording was added, requiring the added entry to
3568      adhere to the data model.
3569    - Removed recommendation regarding placement of objects.  This is
3570      covered in the data model document.
3571
3572 C.1.23.  Section 4.9 (Modify DN Operation)
3573
3574    - Required servers to not dereference aliases for Modify DN.  This
3575      was added for consistency with other operations and to help ensure
3576      data consistency.
3577    - Allow Modify DN to fail when moving between naming contexts.
3578    - Specified what happens when the attributes of the newrdn are not
3579      present on the entry.
3580
3581
3582
3583
3584
3585
3586 Sermersheim                 Standards Track                    [Page 64]
3587 \f
3588 RFC 4511                         LDAPv3                        June 2006
3589
3590
3591 C.1.24.  Section 4.10 (Compare Operation)
3592
3593    - Specified that compareFalse means that the Compare took place and
3594      the result is false.  There was confusion that led people to
3595      believe that an Undefined match resulted in compareFalse.
3596    - Required servers to not dereference aliases for Compare.  This was
3597      added for consistency with other operations and to help ensure
3598      data consistency.
3599
3600 C.1.25.  Section 4.11 (Abandon Operation)
3601
3602    - Explained that since Abandon returns no response, clients should
3603      not use it if they need to know the outcome.
3604    - Specified that Abandon and Unbind cannot be abandoned.
3605
3606 C.1.26.  Section 4.12 (Extended Operation)
3607
3608    - Specified how values of Extended operations defined in terms of
3609      ASN.1 are to be encoded.
3610    - Added instructions on what Extended operation specifications
3611      consist of.
3612    - Added a recommendation that servers advertise supported Extended
3613      operations.
3614
3615 C.1.27.  Section 5.2 (Transfer Protocols)
3616
3617    - Moved referral-specific instructions into referral-related
3618      sections.
3619
3620 C.1.28.  Section 7 (Security Considerations)
3621
3622    - Reworded notes regarding SASL not protecting certain aspects of
3623      the LDAP Bind messages.
3624    - Noted that Servers are encouraged to prevent directory
3625      modifications by clients that have authenticated anonymously
3626      [RFC4513].
3627    - Added a note regarding the possibility of changes to security
3628      factors (authentication, authorization, and data confidentiality).
3629    - Warned against following referrals that may have been injected in
3630      the data stream.
3631    - Noted that servers should protect information equally, whether in
3632      an error condition or not, and mentioned matchedDN,
3633      diagnosticMessage, and resultCodes specifically.
3634    - Added a note regarding malformed and long encodings.
3635
3636
3637
3638
3639
3640
3641
3642 Sermersheim                 Standards Track                    [Page 65]
3643 \f
3644 RFC 4511                         LDAPv3                        June 2006
3645
3646
3647 C.1.29.  Appendix A (Complete ASN.1 Definition)
3648
3649    - Added "EXTENSIBILITY IMPLIED" to ASN.1 definition.
3650    - Removed AttributeType.  It is not used.
3651
3652 C.2.  Changes Made to RFC 2830
3653
3654    This section summarizes the substantive changes made to Sections of
3655    RFC 2830.  Readers should consult [RFC4513] for summaries of changes
3656    to other sections.
3657
3658 C.2.1.  Section 2.3 (Response other than "success")
3659
3660    - Removed wording indicating that referrals can be returned from
3661      StartTLS.
3662    - Removed requirement that only a narrow set of result codes can be
3663      returned.  Some result codes are required in certain scenarios, but
3664      any other may be returned if appropriate.
3665    - Removed requirement that the ExtendedResponse.responseName MUST be
3666      present.  There are circumstances where this is impossible, and
3667      requiring this is at odds with language in Section 4.12.
3668
3669 C.2.1.  Section 4 (Closing a TLS Connection)
3670
3671    - Reworded most of this section to align with definitions of the
3672      LDAP protocol layers.
3673    - Removed instructions on abrupt closure as this is covered in other
3674      areas of the document (specifically, Section 5.3)
3675
3676 C.3.  Changes Made to RFC 3771
3677
3678    - Rewrote to fit into this document.  In general, semantics were
3679      preserved.  Supporting and background language seen as redundant
3680      due to its presence in this document was omitted.
3681
3682    - Specified that Intermediate responses to a request may be of
3683      different types, and one of the response types may be specified to
3684      have no response value.
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698 Sermersheim                 Standards Track                    [Page 66]
3699 \f
3700 RFC 4511                         LDAPv3                        June 2006
3701
3702
3703 Editor's Address
3704
3705    Jim Sermersheim
3706    Novell, Inc.
3707    1800 South Novell Place
3708    Provo, Utah 84606, USA
3709
3710    Phone: +1 801 861-3088
3711    EMail: jimse@novell.com
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754 Sermersheim                 Standards Track                    [Page 67]
3755 \f
3756 RFC 4511                         LDAPv3                        June 2006
3757
3758
3759 Full Copyright Statement
3760
3761    Copyright (C) The Internet Society (2006).
3762
3763    This document is subject to the rights, licenses and restrictions
3764    contained in BCP 78, and except as set forth therein, the authors
3765    retain all their rights.
3766
3767    This document and the information contained herein are provided on an
3768    "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
3769    OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
3770    ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
3771    INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
3772    INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
3773    WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
3774
3775 Intellectual Property
3776
3777    The IETF takes no position regarding the validity or scope of any
3778    Intellectual Property Rights or other rights that might be claimed to
3779    pertain to the implementation or use of the technology described in
3780    this document or the extent to which any license under such rights
3781    might or might not be available; nor does it represent that it has
3782    made any independent effort to identify any such rights.  Information
3783    on the procedures with respect to rights in RFC documents can be
3784    found in BCP 78 and BCP 79.
3785
3786    Copies of IPR disclosures made to the IETF Secretariat and any
3787    assurances of licenses to be made available, or the result of an
3788    attempt made to obtain a general license or permission for the use of
3789    such proprietary rights by implementers or users of this
3790    specification can be obtained from the IETF on-line IPR repository at
3791    http://www.ietf.org/ipr.
3792
3793    The IETF invites any interested party to bring to its attention any
3794    copyrights, patents or patent applications, or other proprietary
3795    rights that may cover technology that may be required to implement
3796    this standard.  Please address the information to the IETF at
3797    ietf-ipr@ietf.org.
3798
3799 Acknowledgement
3800
3801    Funding for the RFC Editor function is provided by the IETF
3802    Administrative Support Activity (IASA).
3803
3804
3805
3806
3807
3808
3809
3810 Sermersheim                 Standards Track                    [Page 68]
3811 \f