]> git.sur5r.net Git - openldap/blob - doc/rfc/rfc2251.txt
Sync with HEAD
[openldap] / doc / rfc / rfc2251.txt
1
2
3
4
5
6
7 Network Working Group                                            M. Wahl
8 Request for Comments: 2251                           Critical Angle Inc.
9 Category: Standards Track                                       T. Howes
10                                            Netscape Communications Corp.
11                                                                 S. Kille
12                                                            Isode Limited
13                                                            December 1997
14
15
16                Lightweight Directory Access Protocol (v3)
17
18 1. Status of this Memo
19
20    This document specifies an Internet standards track protocol for the
21    Internet community, and requests discussion and suggestions for
22    improvements.  Please refer to the current edition of the "Internet
23    Official Protocol Standards" (STD 1) for the standardization state
24    and status of this protocol.  Distribution of this memo is unlimited.
25
26 Copyright Notice
27
28    Copyright (C) The Internet Society (1997).  All Rights Reserved.
29
30 IESG Note
31
32    This document describes a directory access protocol that provides
33    both read and update access.  Update access requires secure
34    authentication, but this document does not mandate implementation of
35    any satisfactory authentication mechanisms.
36
37    In accordance with RFC 2026, section 4.4.1, this specification is
38    being approved by IESG as a Proposed Standard despite this
39    limitation, for the following reasons:
40
41    a. to encourage implementation and interoperability testing of
42       these protocols (with or without update access) before they
43       are deployed, and
44
45    b. to encourage deployment and use of these protocols in read-only
46       applications.  (e.g. applications where LDAPv3 is used as
47       a query language for directories which are updated by some
48       secure mechanism other than LDAP), and
49
50    c. to avoid delaying the advancement and deployment of other Internet
51       standards-track protocols which require the ability to query, but
52       not update, LDAPv3 directory servers.
53
54
55
56
57
58 Wahl, et. al.               Standards Track                     [Page 1]
59 \f
60 RFC 2251                         LDAPv3                    December 1997
61
62
63    Readers are hereby warned that until mandatory authentication
64    mechanisms are standardized, clients and servers written according to
65    this specification which make use of update functionality are
66    UNLIKELY TO INTEROPERATE, or MAY INTEROPERATE ONLY IF AUTHENTICATION
67    IS REDUCED TO AN UNACCEPTABLY WEAK LEVEL.
68
69    Implementors are hereby discouraged from deploying LDAPv3 clients or
70    servers which implement the update functionality, until a Proposed
71    Standard for mandatory authentication in LDAPv3 has been approved and
72    published as an RFC.
73
74 Table of Contents
75
76    1.  Status of this Memo ....................................  1
77        Copyright Notice .......................................  1
78        IESG Note ..............................................  1
79    2.  Abstract ...............................................  3
80    3.  Models .................................................  4
81    3.1. Protocol Model ........................................  4
82    3.2. Data Model ............................................  5
83    3.2.1. Attributes of Entries ...............................  5
84    3.2.2. Subschema Entries and Subentries ....................  7
85    3.3. Relationship to X.500 .................................  8
86    3.4. Server-specific Data Requirements .....................  8
87    4.  Elements of Protocol ...................................  9
88    4.1. Common Elements .......................................  9
89    4.1.1. Message Envelope ....................................  9
90    4.1.1.1. Message ID ........................................ 11
91    4.1.2. String Types ........................................ 11
92    4.1.3. Distinguished Name and Relative Distinguished Name .. 11
93    4.1.4. Attribute Type ...................................... 12
94    4.1.5. Attribute Description ............................... 13
95    4.1.5.1. Binary Option ..................................... 14
96    4.1.6. Attribute Value ..................................... 14
97    4.1.7. Attribute Value Assertion ........................... 15
98    4.1.8. Attribute ........................................... 15
99    4.1.9. Matching Rule Identifier ............................ 15
100    4.1.10. Result Message ..................................... 16
101    4.1.11. Referral ........................................... 18
102    4.1.12. Controls ........................................... 19
103    4.2. Bind Operation ........................................ 20
104    4.2.1. Sequencing of the Bind Request ...................... 21
105    4.2.2. Authentication and Other Security Services .......... 22
106    4.2.3. Bind Response ....................................... 23
107    4.3. Unbind Operation ...................................... 24
108    4.4. Unsolicited Notification .............................. 24
109    4.4.1. Notice of Disconnection ............................. 24
110    4.5. Search Operation ...................................... 25
111
112
113
114 Wahl, et. al.               Standards Track                     [Page 2]
115 \f
116 RFC 2251                         LDAPv3                    December 1997
117
118
119    4.5.1. Search Request ...................................... 25
120    4.5.2. Search Result ....................................... 29
121    4.5.3. Continuation References in the Search Result ........ 31
122    4.5.3.1. Example ........................................... 31
123    4.6. Modify Operation ...................................... 32
124    4.7. Add Operation ......................................... 34
125    4.8. Delete Operation ...................................... 35
126    4.9. Modify DN Operation ................................... 36
127    4.10. Compare Operation .................................... 37
128    4.11. Abandon Operation .................................... 38
129    4.12. Extended Operation ................................... 38
130    5.  Protocol Element Encodings and Transfer ................ 39
131    5.1. Mapping Onto BER-based Transport Services ............. 39
132    5.2. Transfer Protocols .................................... 40
133    5.2.1. Transmission Control Protocol (TCP) ................. 40
134    6.  Implementation Guidelines .............................. 40
135    6.1. Server Implementations ................................ 40
136    6.2. Client Implementations ................................ 40
137    7.  Security Considerations ................................ 41
138    8.  Acknowledgements ....................................... 41
139    9.  Bibliography ........................................... 41
140    10. Authors' Addresses ..................................... 42
141    Appendix A - Complete ASN.1 Definition ..................... 44
142    Full Copyright Statement ................................... 50
143
144 2.  Abstract
145
146    The protocol described in this document is designed to provide access
147    to directories supporting the X.500 models, while not incurring the
148    resource requirements of the X.500 Directory Access Protocol (DAP).
149    This protocol is specifically targeted at management applications and
150    browser applications that provide read/write interactive access to
151    directories. When used with a directory supporting the X.500
152    protocols, it is intended to be a complement to the X.500 DAP.
153
154    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
155    "SHOULD", "SHOULD NOT", "RECOMMENDED",  and "MAY" in this document
156    are to be interpreted as described in RFC 2119 [10].
157
158    Key aspects of this version of LDAP are:
159
160    - All protocol elements of LDAPv2 (RFC 1777) are supported. The
161      protocol is carried directly over TCP or other transport, bypassing
162      much of the session/presentation overhead of X.500 DAP.
163
164    - Most protocol data elements can be encoded as ordinary strings
165      (e.g., Distinguished Names).
166
167
168
169
170 Wahl, et. al.               Standards Track                     [Page 3]
171 \f
172 RFC 2251                         LDAPv3                    December 1997
173
174
175    - Referrals to other servers may be returned.
176
177    - SASL mechanisms may be used with LDAP to provide association
178      security services.
179
180    - Attribute values and Distinguished Names have been
181      internationalized through the use of the ISO 10646 character set.
182
183    - The protocol can be extended to support new operations, and
184      controls may be used to extend existing operations.
185
186    - Schema is published in the directory for use by clients.
187
188 3.  Models
189
190    Interest in X.500 [1] directory technologies in the Internet has led
191    to efforts to reduce the high cost of entry associated with use of
192    these technologies.  This document continues the efforts to define
193    directory protocol alternatives, updating the LDAP [2] protocol
194    specification.
195
196 3.1. Protocol Model
197
198    The general model adopted by this protocol is one of clients
199    performing protocol operations against servers. In this model, a
200    client transmits a protocol request describing the operation to be
201    performed to a server. The server is then responsible for performing
202    the necessary operation(s) in the directory. Upon completion of the
203    operation(s), the server returns a response containing any results or
204    errors to the requesting client.
205
206    In keeping with the goal of easing the costs associated with use of
207    the directory, it is an objective of this protocol to minimize the
208    complexity of clients so as to facilitate widespread deployment of
209    applications capable of using the directory.
210
211    Note that although servers are required to return responses whenever
212    such responses are defined in the protocol, there is no requirement
213    for synchronous behavior on the part of either clients or servers.
214    Requests and responses for multiple operations may be exchanged
215    between a client and server in any order, provided the client
216    eventually receives a response for every request that requires one.
217
218    In LDAP versions 1 and 2, no provision was made for protocol servers
219    returning referrals to clients.  However, for improved performance
220    and distribution this version of the protocol permits servers to
221    return to clients referrals to other servers.  This allows servers to
222    offload the work of contacting other servers to progress operations.
223
224
225
226 Wahl, et. al.               Standards Track                     [Page 4]
227 \f
228 RFC 2251                         LDAPv3                    December 1997
229
230
231    Note that the core protocol operations defined in this document can
232    be mapped to a strict subset of the X.500(1997) directory abstract
233    service, so it can be cleanly provided by the DAP.  However there is
234    not a one-to-one mapping between LDAP protocol operations and DAP
235    operations: server implementations acting as a gateway to X.500
236    directories may need to make multiple DAP requests.
237
238 3.2. Data Model
239
240    This section provides a brief introduction to the X.500 data model,
241    as used by LDAP.
242
243    The LDAP protocol assumes there are one or more servers which jointly
244    provide access to a Directory Information Tree (DIT).  The tree is
245    made up of entries.  Entries have names: one or more attribute values
246    from the entry form its relative distinguished name (RDN), which MUST
247    be unique among all its siblings.  The concatenation of the relative
248    distinguished names of the sequence of entries from a particular
249    entry to an immediate subordinate of the root of the tree forms that
250    entry's Distinguished Name (DN), which is unique in the tree.  An
251    example of a Distinguished Name is
252
253    CN=Steve Kille, O=Isode Limited, C=GB
254
255    Some servers may hold cache or shadow copies of entries, which can be
256    used to answer search and comparison queries, but will return
257    referrals or contact other servers if modification operations are
258    requested.
259
260    Servers which perform caching or shadowing MUST ensure that they do
261    not violate any access control constraints placed on the data by the
262    originating server.
263
264    The largest collection of entries, starting at an entry that is
265    mastered by a particular server, and including all its subordinates
266    and their subordinates, down to the entries which are mastered by
267    different servers, is termed a naming context.  The root of the DIT
268    is a DSA-specific Entry (DSE) and not part of any naming context:
269    each server has different attribute values in the root DSE.  (DSA is
270    an X.500 term for the directory server).
271
272 3.2.1. Attributes of Entries
273
274    Entries consist of a set of attributes.  An attribute is a type with
275    one or more associated values.  The attribute type is identified by a
276    short descriptive name and an OID (object identifier). The attribute
277
278
279
280
281
282 Wahl, et. al.               Standards Track                     [Page 5]
283 \f
284 RFC 2251                         LDAPv3                    December 1997
285
286
287    type governs whether there can be more than one value of an attribute
288    of that type in an entry, the syntax to which the values must
289    conform, the kinds of matching which can be performed on values of
290    that attribute, and other functions.
291
292    An example of an attribute is "mail". There may be one or more values
293    of this attribute, they must be IA5 (ASCII) strings, and they are
294    case insensitive (e.g. "foo@bar.com" will match "FOO@BAR.COM").
295
296    Schema is the collection of attribute type definitions, object class
297    definitions and other information which a server uses to determine
298    how to match a filter or attribute value assertion (in a compare
299    operation) against the attributes of an entry, and whether to permit
300    add and modify operations.  The definition of schema for use with
301    LDAP is given in [5] and [6].  Additional schema elements may be
302    defined in other documents.
303
304    Each entry MUST have an objectClass attribute.  The objectClass
305    attribute specifies the object classes of an entry, which along with
306    the system and user schema determine the permitted attributes of an
307    entry.  Values of this attribute may be modified by clients, but the
308    objectClass attribute cannot be removed.  Servers may restrict the
309    modifications of this attribute to prevent the basic structural class
310    of the entry from being changed (e.g. one cannot change a person into
311    a country).  When creating an entry or adding an objectClass value to
312    an entry, all superclasses of the named classes are implicitly added
313    as well if not already present, and the client must supply values for
314    any mandatory attributes of new superclasses.
315
316    Some attributes, termed operational attributes, are used by servers
317    for administering the directory system itself.  They are not returned
318    in search results unless explicitly requested by name.  Attributes
319    which are not operational, such as "mail", will have their schema and
320    syntax constraints enforced by servers, but servers will generally
321    not make use of their values.
322
323    Servers MUST NOT permit clients to add attributes to an entry unless
324    those attributes are permitted by the object class definitions, the
325    schema controlling that entry (specified in the subschema - see
326    below), or are operational attributes known to that server and used
327    for administrative purposes.  Note that there is a particular
328    objectClass 'extensibleObject' defined in [5] which permits all user
329    attributes to be present in an entry.
330
331    Entries MAY contain, among others, the following operational
332    attributes, defined in [5]. These attributes are maintained
333    automatically by the server and are not modifiable by clients:
334
335
336
337
338 Wahl, et. al.               Standards Track                     [Page 6]
339 \f
340 RFC 2251                         LDAPv3                    December 1997
341
342
343    - creatorsName: the Distinguished Name of the user who added this
344      entry to the directory.
345
346    - createTimestamp: the time this entry was added to the directory.
347
348    - modifiersName: the Distinguished Name of the user who last modified
349      this entry.
350
351    - modifyTimestamp: the time this entry was last modified.
352
353    - subschemaSubentry:  the Distinguished Name of the subschema entry
354      (or subentry) which controls the schema for this entry.
355
356 3.2.2. Subschema Entries and Subentries
357
358    Subschema entries are used for administering information about the
359    directory schema, in particular the object classes and attribute
360    types supported by directory servers.  A single subschema entry
361    contains all schema definitions used by entries in a particular part
362    of the directory tree.
363
364    Servers which follow X.500(93) models SHOULD implement subschema
365    using the X.500 subschema mechanisms, and so these subschemas are not
366    ordinary entries.  LDAP clients SHOULD NOT assume that servers
367    implement any of the other aspects of X.500 subschema.  A server
368    which masters entries and permits clients to modify these entries
369    MUST implement and provide access to these subschema entries, so that
370    its clients may discover the attributes and object classes which are
371    permitted to be present. It is strongly recommended that all other
372    servers implement this as well.
373
374    The following four attributes MUST be present in all subschema
375    entries:
376
377    - cn: this attribute MUST be used to form the RDN of the subschema
378      entry.
379
380    - objectClass: the attribute MUST have at least the values "top" and
381      "subschema".
382
383    - objectClasses: each value of this attribute specifies an object
384      class known to the server.
385
386    - attributeTypes: each value of this attribute specifies an attribute
387      type known to the server.
388
389    These are defined in [5]. Other attributes MAY be present in
390    subschema entries, to reflect additional supported capabilities.
391
392
393
394 Wahl, et. al.               Standards Track                     [Page 7]
395 \f
396 RFC 2251                         LDAPv3                    December 1997
397
398
399    These include matchingRules, matchingRuleUse, dITStructureRules,
400    dITContentRules, nameForms and ldapSyntaxes.
401
402    Servers SHOULD provide the attributes createTimestamp and
403    modifyTimestamp in subschema entries, in order to allow clients to
404    maintain their caches of schema information.
405
406    Clients MUST only retrieve attributes from a subschema entry by
407    requesting a base object search of the entry, where the search filter
408    is "(objectClass=subschema)". (This will allow LDAPv3 servers which
409    gateway to X.500(93) to detect that subentry information is being
410    requested.)
411
412 3.3. Relationship to X.500
413
414    This document defines LDAP in terms of X.500 as an X.500 access
415    mechanism.  An LDAP server MUST act in accordance with the
416    X.500(1993) series of ITU recommendations when providing the service.
417    However, it is not required that an LDAP server make use of any X.500
418    protocols in providing this service, e.g. LDAP can be mapped onto any
419    other directory system so long as the X.500 data and service model as
420    used in LDAP is not violated in the LDAP interface.
421
422 3.4. Server-specific Data Requirements
423
424    An LDAP server MUST provide information about itself and other
425    information that is specific to each server.  This is represented as
426    a group of attributes located in the root DSE (DSA-Specific Entry),
427    which is named with the zero-length LDAPDN.  These attributes are
428    retrievable if a client performs a base object search of the root
429    with filter "(objectClass=*)", however they are subject to access
430    control restrictions.  The root DSE MUST NOT be included if the
431    client performs a subtree search starting from the root.
432
433    Servers may allow clients to modify these attributes.
434
435    The following attributes of the root DSE are defined in section 5 of
436    [5].  Additional attributes may be defined in other documents.
437
438    - namingContexts: naming contexts held in the server. Naming contexts
439      are defined in section 17 of X.501 [6].
440
441    - subschemaSubentry: subschema entries (or subentries) known by this
442      server.
443
444    - altServer: alternative servers in case this one is later
445      unavailable.
446
447
448
449
450 Wahl, et. al.               Standards Track                     [Page 8]
451 \f
452 RFC 2251                         LDAPv3                    December 1997
453
454
455    - supportedExtension: list of supported extended operations.
456
457    - supportedControl: list of supported controls.
458
459    - supportedSASLMechanisms: list of supported SASL security features.
460
461    - supportedLDAPVersion: LDAP versions implemented by the server.
462
463    If the server does not master entries and does not know the locations
464    of schema information, the subschemaSubentry attribute is not present
465    in the root DSE.  If the server masters directory entries under one
466    or more schema rules, there may be any number of values of the
467    subschemaSubentry attribute in the root DSE.
468
469 4.  Elements of Protocol
470
471    The LDAP protocol is described using Abstract Syntax Notation 1
472    (ASN.1) [3], and is typically transferred using a subset of ASN.1
473    Basic Encoding Rules [11]. In order to support future extensions to
474    this protocol, clients and servers MUST ignore elements of SEQUENCE
475    encodings whose tags they do not recognize.
476
477    Note that unlike X.500, each change to the LDAP protocol other than
478    through the extension mechanisms will have a different version
479    number.  A client will indicate the version it supports as part of
480    the bind request, described in section 4.2.  If a client has not sent
481    a bind, the server MUST assume that version 3 is supported in the
482    client (since version 2 required that the client bind first).
483
484    Clients may determine the protocol version a server supports by
485    reading the supportedLDAPVersion attribute from the root DSE. Servers
486    which implement version 3 or later versions MUST provide this
487    attribute.  Servers which only implement version 2 may not provide
488    this attribute.
489
490 4.1. Common Elements
491
492    This section describes the LDAPMessage envelope PDU (Protocol Data
493    Unit) format, as well as data type definitions which are used in the
494    protocol operations.
495
496 4.1.1. Message Envelope
497
498    For the purposes of protocol exchanges, all protocol operations are
499    encapsulated in a common envelope, the LDAPMessage, which is defined
500    as follows:
501
502         LDAPMessage ::= SEQUENCE {
503
504
505
506 Wahl, et. al.               Standards Track                     [Page 9]
507 \f
508 RFC 2251                         LDAPv3                    December 1997
509
510
511                 messageID       MessageID,
512                 protocolOp      CHOICE {
513                         bindRequest     BindRequest,
514                         bindResponse    BindResponse,
515                         unbindRequest   UnbindRequest,
516                         searchRequest   SearchRequest,
517                         searchResEntry  SearchResultEntry,
518                         searchResDone   SearchResultDone,
519                         searchResRef    SearchResultReference,
520                         modifyRequest   ModifyRequest,
521                         modifyResponse  ModifyResponse,
522                         addRequest      AddRequest,
523                         addResponse     AddResponse,
524                         delRequest      DelRequest,
525                         delResponse     DelResponse,
526                         modDNRequest    ModifyDNRequest,
527                         modDNResponse   ModifyDNResponse,
528                         compareRequest  CompareRequest,
529                         compareResponse CompareResponse,
530                         abandonRequest  AbandonRequest,
531                         extendedReq     ExtendedRequest,
532                         extendedResp    ExtendedResponse },
533                  controls       [0] Controls OPTIONAL }
534
535         MessageID ::= INTEGER (0 .. maxInt)
536
537         maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
538
539    The function of the LDAPMessage is to provide an envelope containing
540    common fields required in all protocol exchanges. At this time the
541    only common fields are the message ID and the controls.
542
543    If the server receives a PDU from the client in which the LDAPMessage
544    SEQUENCE tag cannot be recognized, the messageID cannot be parsed,
545    the tag of the protocolOp is not recognized as a request, or the
546    encoding structures or lengths of data fields are found to be
547    incorrect, then the server MUST return the notice of disconnection
548    described in section 4.4.1, with resultCode protocolError, and
549    immediately close the connection. In other cases that the server
550    cannot parse the request received by the client, the server MUST
551    return an appropriate response to the request, with the resultCode
552    set to protocolError.
553
554    If the client receives a PDU from the server which cannot be parsed,
555    the client may discard the PDU, or may abruptly close the connection.
556
557    The ASN.1 type Controls is defined in section 4.1.12.
558
559
560
561
562 Wahl, et. al.               Standards Track                    [Page 10]
563 \f
564 RFC 2251                         LDAPv3                    December 1997
565
566
567 4.1.1.1. Message ID
568
569    All LDAPMessage envelopes encapsulating responses contain the
570    messageID value of the corresponding request LDAPMessage.
571
572    The message ID of a request MUST have a value different from the
573    values of any other requests outstanding in the LDAP session of which
574    this message is a part.
575
576    A client MUST NOT send a second request with the same message ID as
577    an earlier request on the same connection if the client has not
578    received the final response from the earlier request.  Otherwise the
579    behavior is undefined.  Typical clients increment a counter for each
580    request.
581
582    A client MUST NOT reuse the message id of an abandonRequest or of the
583    abandoned operation until it has received a response from the server
584    for another request invoked subsequent to the abandonRequest, as the
585    abandonRequest itself does not have a response.
586
587 4.1.2. String Types
588
589    The LDAPString is a notational convenience to indicate that, although
590    strings of LDAPString type encode as OCTET STRING types, the ISO
591    10646 [13] character set (a superset of Unicode) is used, encoded
592    following the UTF-8 algorithm [14]. Note that in the UTF-8 algorithm
593    characters which are the same as ASCII (0x0000 through 0x007F) are
594    represented as that same ASCII character in a single byte.  The other
595    byte values are used to form a variable-length encoding of an
596    arbitrary character.
597
598         LDAPString ::= OCTET STRING
599
600    The LDAPOID is a notational convenience to indicate that the
601    permitted value of this string is a (UTF-8 encoded) dotted-decimal
602    representation of an OBJECT IDENTIFIER.
603
604         LDAPOID ::= OCTET STRING
605
606    For example,
607
608         1.3.6.1.4.1.1466.1.2.3
609
610 4.1.3. Distinguished Name and Relative Distinguished Name
611
612    An LDAPDN and a RelativeLDAPDN are respectively defined to be the
613    representation of a Distinguished Name and a Relative Distinguished
614    Name after encoding according to the specification in [4], such that
615
616
617
618 Wahl, et. al.               Standards Track                    [Page 11]
619 \f
620 RFC 2251                         LDAPv3                    December 1997
621
622
623         <distinguished-name> ::= <name>
624
625         <relative-distinguished-name> ::= <name-component>
626
627    where <name> and <name-component> are as defined in [4].
628
629         LDAPDN ::= LDAPString
630
631         RelativeLDAPDN ::= LDAPString
632
633    Only Attribute Types can be present in a relative distinguished name
634    component; the options of Attribute Descriptions (next section) MUST
635    NOT be used in specifying distinguished names.
636
637 4.1.4. Attribute Type
638
639    An AttributeType takes on as its value the textual string associated
640    with that AttributeType in its specification.
641
642         AttributeType ::= LDAPString
643
644    Each attribute type has a unique OBJECT IDENTIFIER which has been
645    assigned to it.  This identifier may be written as decimal digits
646    with components separated by periods, e.g. "2.5.4.10".
647
648    A specification may also assign one or more textual names for an
649    attribute type.  These names MUST begin with a letter, and only
650    contain ASCII letters, digit characters and hyphens.  They are case
651    insensitive.  (These ASCII characters are identical to ISO 10646
652    characters whose UTF-8 encoding is a single byte between 0x00 and
653    0x7F.)
654
655    If the server has a textual name for an attribute type, it MUST use a
656    textual name for attributes returned in search results.  The dotted-
657    decimal OBJECT IDENTIFIER is only used if there is no textual name
658    for an attribute type.
659
660    Attribute type textual names are non-unique, as two different
661    specifications (neither in standards track RFCs) may choose the same
662    name.
663
664    A server which masters or shadows entries SHOULD list all the
665    attribute types it supports in the subschema entries, using the
666    attributeTypes attribute.  Servers which support an open-ended set of
667    attributes SHOULD include at least the attributeTypes value for the
668    'objectClass' attribute. Clients MAY retrieve the attributeTypes
669    value from subschema entries in order to obtain the OBJECT IDENTIFIER
670    and other information associated with attribute types.
671
672
673
674 Wahl, et. al.               Standards Track                    [Page 12]
675 \f
676 RFC 2251                         LDAPv3                    December 1997
677
678
679    Some attribute type names which are used in this version of LDAP are
680    described in [5].  Servers may implement additional attribute types.
681
682 4.1.5. Attribute Description
683
684    An AttributeDescription is a superset of the definition of the
685    AttributeType.  It has the same ASN.1 definition, but allows
686    additional options to be specified.  They are also case insensitive.
687
688         AttributeDescription ::= LDAPString
689
690    A value of AttributeDescription is based on the following BNF:
691
692         <AttributeDescription> ::= <AttributeType> [ ";" <options> ]
693
694         <options>  ::= <option> | <option> ";" <options>
695
696         <option>   ::= <opt-char> <opt-char>*
697
698         <opt-char> ::=  ASCII-equivalent letters, numbers and hyphen
699
700    Examples of valid AttributeDescription:
701
702         cn
703         userCertificate;binary
704
705    One option, "binary", is defined in this document.  Additional
706    options may be defined in IETF standards-track and experimental RFCs.
707    Options beginning with "x-" are reserved for private experiments.
708    Any option could be associated with any AttributeType, although not
709    all combinations may be supported by a server.
710
711    An AttributeDescription with one or more options is treated as a
712    subtype of the attribute type without any options.  Options present
713    in an AttributeDescription are never mutually exclusive.
714    Implementations MUST generate the <options> list sorted in ascending
715    order, and servers MUST treat any two AttributeDescription with the
716    same AttributeType and options as equivalent.  A server will treat an
717    AttributeDescription with any options it does not implement as an
718    unrecognized attribute type.
719
720    The data type "AttributeDescriptionList" describes a list of 0 or
721    more attribute types.  (A list of zero elements has special
722    significance in the Search request.)
723
724         AttributeDescriptionList ::= SEQUENCE OF
725                 AttributeDescription
726
727
728
729
730 Wahl, et. al.               Standards Track                    [Page 13]
731 \f
732 RFC 2251                         LDAPv3                    December 1997
733
734
735 4.1.5.1. Binary Option
736
737    If the "binary" option is present in an AttributeDescription, it
738    overrides any string-based encoding representation defined for that
739    attribute in [5]. Instead the attribute is to be transferred as a
740    binary value encoded using the Basic Encoding Rules [11].  The syntax
741    of the binary value is an ASN.1 data type definition which is
742    referenced by the "SYNTAX" part of the attribute type definition.
743
744    The presence or absence of the "binary" option only affects the
745    transfer of attribute values in protocol; servers store any
746    particular attribute in a single format.  If a client requests that a
747    server return an attribute in the binary format, but the server
748    cannot generate that format, the server MUST treat this attribute
749    type as an unrecognized attribute type.  Similarly, clients MUST NOT
750    expect servers to return an attribute in binary format if the client
751    requested that attribute by name without the binary option.
752
753    This option is intended to be used with attributes whose syntax is a
754    complex ASN.1 data type, and the structure of values of that type is
755    needed by clients.  Examples of this kind of syntax are "Certificate"
756    and "CertificateList".
757
758 4.1.6. Attribute Value
759
760    A field of type AttributeValue takes on as its value either a string
761    encoding of a AttributeValue data type, or an OCTET STRING containing
762    an encoded binary value, depending on whether the "binary" option is
763    present in the companion AttributeDescription to this AttributeValue.
764
765    The definition of string encodings for different syntaxes and types
766    may be found in other documents, and in particular [5].
767
768         AttributeValue ::= OCTET STRING
769
770    Note that there is no defined limit on the size of this encoding;
771    thus protocol values may include multi-megabyte attributes (e.g.
772    photographs).
773
774    Attributes may be defined which have arbitrary and non-printable
775    syntax.  Implementations MUST NEITHER simply display nor attempt to
776    decode as ASN.1 a value if its syntax is not known.  The
777    implementation may attempt to discover the subschema of the source
778    entry, and retrieve the values of attributeTypes from it.
779
780    Clients MUST NOT send attribute values in a request which are not
781    valid according to the syntax defined for the attributes.
782
783
784
785
786 Wahl, et. al.               Standards Track                    [Page 14]
787 \f
788 RFC 2251                         LDAPv3                    December 1997
789
790
791 4.1.7. Attribute Value Assertion
792
793    The AttributeValueAssertion type definition is similar to the one in
794    the X.500 directory standards.  It contains an attribute description
795    and a matching rule assertion value suitable for that type.
796
797         AttributeValueAssertion ::= SEQUENCE {
798                 attributeDesc   AttributeDescription,
799                 assertionValue  AssertionValue }
800
801         AssertionValue ::= OCTET STRING
802
803    If the "binary" option is present in attributeDesc, this signals to
804    the server that the assertionValue is a binary encoding of the
805    assertion value.
806
807    For all the string-valued user attributes described in [5], the
808    assertion value syntax is the same as the value syntax.  Clients may
809    use attribute values as assertion values in compare requests and
810    search filters.
811
812    Note however that the assertion syntax may be different from the
813    value syntax for other attributes or for non-equality matching rules.
814    These may have an assertion syntax which contains only part of the
815    value.  See section 20.2.1.8 of X.501 [6] for examples.
816
817 4.1.8. Attribute
818
819    An attribute consists of a type and one or more values of that type.
820    (Though attributes MUST have at least one value when stored, due to
821    access control restrictions the set may be empty when transferred in
822    protocol.  This is described in section 4.5.2, concerning the
823    PartialAttributeList type.)
824
825         Attribute ::= SEQUENCE {
826                 type    AttributeDescription,
827                 vals    SET OF AttributeValue }
828
829    Each attribute value is distinct in the set (no duplicates).  The
830    order of attribute values within the vals set is undefined and
831    implementation-dependent, and MUST NOT be relied upon.
832
833 4.1.9. Matching Rule Identifier
834
835    A matching rule is a means of expressing how a server should compare
836    an AssertionValue received in a search filter with an abstract data
837    value.  The matching rule defines the syntax of the assertion value
838    and the process to be performed in the server.
839
840
841
842 Wahl, et. al.               Standards Track                    [Page 15]
843 \f
844 RFC 2251                         LDAPv3                    December 1997
845
846
847    An X.501(1993) Matching Rule is identified in the LDAP protocol by
848    the printable representation of its OBJECT IDENTIFIER, either as one
849    of the strings given in [5], or as decimal digits with components
850    separated by periods, e.g. "caseIgnoreIA5Match" or
851    "1.3.6.1.4.1.453.33.33".
852
853         MatchingRuleId ::= LDAPString
854
855    Servers which support matching rules for use in the extensibleMatch
856    search filter MUST list the matching rules they implement in
857    subschema entries, using the matchingRules attributes.  The server
858    SHOULD also list there, using the matchingRuleUse attribute, the
859    attribute types with which each matching rule can be used.  More
860    information is given in section 4.4 of [5].
861
862 4.1.10. Result Message
863
864    The LDAPResult is the construct used in this protocol to return
865    success or failure indications from servers to clients. In response
866    to various requests servers will return responses containing fields
867    of type LDAPResult to indicate the final status of a protocol
868    operation request.
869
870         LDAPResult ::= SEQUENCE {
871                 resultCode      ENUMERATED {
872                              success                      (0),
873                              operationsError              (1),
874                              protocolError                (2),
875                              timeLimitExceeded            (3),
876                              sizeLimitExceeded            (4),
877                              compareFalse                 (5),
878                              compareTrue                  (6),
879
880                              authMethodNotSupported       (7),
881                              strongAuthRequired           (8),
882                                         -- 9 reserved --
883                              referral                     (10),  -- new
884                              adminLimitExceeded           (11),  -- new
885                              unavailableCriticalExtension (12),  -- new
886                              confidentialityRequired      (13),  -- new
887                              saslBindInProgress           (14),  -- new
888                              noSuchAttribute              (16),
889                              undefinedAttributeType       (17),
890                              inappropriateMatching        (18),
891                              constraintViolation          (19),
892                              attributeOrValueExists       (20),
893                              invalidAttributeSyntax       (21),
894                                         -- 22-31 unused --
895
896
897
898 Wahl, et. al.               Standards Track                    [Page 16]
899 \f
900 RFC 2251                         LDAPv3                    December 1997
901
902
903                              noSuchObject                 (32),
904                              aliasProblem                 (33),
905                              invalidDNSyntax              (34),
906                              -- 35 reserved for undefined isLeaf --
907                              aliasDereferencingProblem    (36),
908                                         -- 37-47 unused --
909                              inappropriateAuthentication  (48),
910                              invalidCredentials           (49),
911                              insufficientAccessRights     (50),
912                              busy                         (51),
913                              unavailable                  (52),
914                              unwillingToPerform           (53),
915                              loopDetect                   (54),
916                                         -- 55-63 unused --
917                              namingViolation              (64),
918                              objectClassViolation         (65),
919                              notAllowedOnNonLeaf          (66),
920                              notAllowedOnRDN              (67),
921                              entryAlreadyExists           (68),
922                              objectClassModsProhibited    (69),
923                                         -- 70 reserved for CLDAP --
924                              affectsMultipleDSAs          (71), -- new
925                                         -- 72-79 unused --
926                              other                        (80) },
927                              -- 81-90 reserved for APIs --
928                 matchedDN       LDAPDN,
929                 errorMessage    LDAPString,
930                 referral        [3] Referral OPTIONAL }
931
932    All the result codes with the exception of success, compareFalse and
933    compareTrue are to be treated as meaning the operation could not be
934    completed in its entirety.
935
936    Most of the result codes are based on problem indications from X.511
937    error data types.  Result codes from 16 to 21 indicate an
938    AttributeProblem, codes 32, 33, 34 and 36 indicate a NameProblem,
939    codes 48, 49 and 50 indicate a SecurityProblem, codes 51 to 54
940    indicate a ServiceProblem, and codes 64 to 69 and 71 indicates an
941    UpdateProblem.
942
943    If a client receives a result code which is not listed above, it is
944    to be treated as an unknown error condition.
945
946    The errorMessage field of this construct may, at the server's option,
947    be used to return a string containing a textual, human-readable
948    (terminal control and page formatting characters should be avoided)
949    error diagnostic. As this error diagnostic is not standardized,
950
951
952
953
954 Wahl, et. al.               Standards Track                    [Page 17]
955 \f
956 RFC 2251                         LDAPv3                    December 1997
957
958
959    implementations MUST NOT rely on the values returned.  If the server
960    chooses not to return a textual diagnostic, the errorMessage field of
961    the LDAPResult type MUST contain a zero length string.
962
963    For result codes of noSuchObject, aliasProblem, invalidDNSyntax and
964    aliasDereferencingProblem, the matchedDN field is set to the name of
965    the lowest entry (object or alias) in the directory that was matched.
966    If no aliases were dereferenced while attempting to locate the entry,
967    this will be a truncated form of the name provided, or if aliases
968    were dereferenced, of the resulting name, as defined in section 12.5
969    of X.511 [8]. The matchedDN field is to be set to a zero length
970    string with all other result codes.
971
972 4.1.11. Referral
973
974    The referral error indicates that the contacted server does not hold
975    the target entry of the request.  The referral field is present in an
976    LDAPResult if the LDAPResult.resultCode field value is referral, and
977    absent with all other result codes.  It contains a reference to
978    another server (or set of servers) which may be accessed via LDAP or
979    other protocols.  Referrals can be returned in response to any
980    operation request (except unbind and abandon which do not have
981    responses). At least one URL MUST be present in the Referral.
982
983    The referral is not returned for a singleLevel or wholeSubtree search
984    in which the search scope spans multiple naming contexts, and several
985    different servers would need to be contacted to complete the
986    operation. Instead, continuation references, described in section
987    4.5.3, are returned.
988
989         Referral ::= SEQUENCE OF LDAPURL  -- one or more
990
991         LDAPURL ::= LDAPString -- limited to characters permitted in URLs
992
993    If the client wishes to progress the operation, it MUST follow the
994    referral by contacting any one of servers.  All the URLs MUST be
995    equally capable of being used to progress the operation.  (The
996    mechanisms for how this is achieved by multiple servers are outside
997    the scope of this document.)
998
999    URLs for servers implementing the LDAP protocol are written according
1000    to [9].  If an alias was dereferenced, the <dn> part of the URL MUST
1001    be present, with the new target object name.  If the <dn> part is
1002    present, the client MUST use this name in its next request to
1003    progress the operation, and if it is not present the client will use
1004    the same name as in the original request.  Some servers (e.g.
1005    participating in distributed indexing) may provide a different filter
1006    in a referral for a search operation.  If the filter part of the URL
1007
1008
1009
1010 Wahl, et. al.               Standards Track                    [Page 18]
1011 \f
1012 RFC 2251                         LDAPv3                    December 1997
1013
1014
1015    is present in an LDAPURL, the client MUST use this filter in its next
1016    request to progress this search, and if it is not present the client
1017    MUST use the same filter as it used for that search.  Other aspects
1018    of the new request may be the same or different as the request which
1019    generated the referral.
1020
1021    Note that UTF-8 characters appearing in a DN or search filter may not
1022    be legal for URLs (e.g. spaces) and MUST be escaped using the %
1023    method in RFC 1738 [7].
1024
1025    Other kinds of URLs may be returned, so long as the operation could
1026    be performed using that protocol.
1027
1028 4.1.12. Controls
1029
1030    A control is a way to specify extension information. Controls which
1031    are sent as part of a request apply only to that request and are not
1032    saved.
1033
1034         Controls ::= SEQUENCE OF Control
1035
1036         Control ::= SEQUENCE {
1037                 controlType             LDAPOID,
1038                 criticality             BOOLEAN DEFAULT FALSE,
1039                 controlValue            OCTET STRING OPTIONAL }
1040
1041    The controlType field MUST be a UTF-8 encoded dotted-decimal
1042    representation of an OBJECT IDENTIFIER which uniquely identifies the
1043    control.  This prevents conflicts between control names.
1044
1045    The criticality field is either TRUE or FALSE.
1046
1047    If the server recognizes the control type and it is appropriate for
1048    the operation, the server will make use of the control when
1049    performing the operation.
1050
1051    If the server does not recognize the control type and the criticality
1052    field is TRUE, the server MUST NOT perform the operation, and MUST
1053    instead return the resultCode unsupportedCriticalExtension.
1054
1055    If the control is not appropriate for the operation and criticality
1056    field is TRUE, the server MUST NOT perform the operation, and MUST
1057    instead return the resultCode unsupportedCriticalExtension.
1058
1059    If the control is unrecognized or inappropriate but the criticality
1060    field is FALSE, the server MUST ignore the control.
1061
1062
1063
1064
1065
1066 Wahl, et. al.               Standards Track                    [Page 19]
1067 \f
1068 RFC 2251                         LDAPv3                    December 1997
1069
1070
1071    The controlValue contains any information associated with the
1072    control, and its format is defined for the control.  The server MUST
1073    be prepared to handle arbitrary contents of the controlValue octet
1074    string, including zero bytes.  It is absent only if there is no value
1075    information which is associated with a control of its type.
1076
1077    This document does not define any controls.  Controls may be defined
1078    in other documents.  The definition of a control consists of:
1079
1080      - the OBJECT IDENTIFIER assigned to the control,
1081
1082      - whether the control is always noncritical, always critical, or
1083        critical at the client's option,
1084
1085      - the format of the controlValue contents of the control.
1086
1087    Servers list the controls which they recognize in the
1088    supportedControl attribute in the root DSE.
1089
1090 4.2. Bind Operation
1091
1092    The function of the Bind Operation is to allow authentication
1093    information to be exchanged between the client and server.
1094
1095    The Bind Request is defined as follows:
1096
1097         BindRequest ::= [APPLICATION 0] SEQUENCE {
1098                 version                 INTEGER (1 .. 127),
1099                 name                    LDAPDN,
1100                 authentication          AuthenticationChoice }
1101
1102         AuthenticationChoice ::= CHOICE {
1103                 simple                  [0] OCTET STRING,
1104                                          -- 1 and 2 reserved
1105                 sasl                    [3] SaslCredentials }
1106
1107         SaslCredentials ::= SEQUENCE {
1108                 mechanism               LDAPString,
1109                 credentials             OCTET STRING OPTIONAL }
1110
1111    Parameters of the Bind Request are:
1112
1113    - version: A version number indicating the version of the protocol to
1114      be used in this protocol session.  This document describes version
1115      3 of the LDAP protocol.  Note that there is no version negotiation,
1116      and the client just sets this parameter to the version it desires.
1117      If the client requests protocol version 2, a server that supports
1118      the version 2 protocol as described in [2] will not return any v3-
1119
1120
1121
1122 Wahl, et. al.               Standards Track                    [Page 20]
1123 \f
1124 RFC 2251                         LDAPv3                    December 1997
1125
1126
1127      specific protocol fields.  (Note that not all LDAP servers will
1128      support protocol version 2, since they may be unable to generate
1129      the attribute syntaxes associated with version 2.)
1130
1131    - name: The name of the directory object that the client wishes to
1132      bind as.  This field may take on a null value (a zero length
1133      string) for the purposes of anonymous binds, when authentication
1134      has been performed at a lower layer, or when using SASL credentials
1135      with a mechanism that includes the LDAPDN in the credentials.
1136
1137    - authentication: information used to authenticate the name, if any,
1138      provided in the Bind Request.
1139
1140    Upon receipt of a Bind Request, a protocol server will authenticate
1141    the requesting client, if necessary.  The server will then return a
1142    Bind Response to the client indicating the status of the
1143    authentication.
1144
1145    Authorization is the use of this authentication information when
1146    performing operations.  Authorization MAY be affected by factors
1147    outside of the LDAP Bind request, such as lower layer security
1148    services.
1149
1150 4.2.1. Sequencing of the Bind Request
1151
1152    For some SASL authentication mechanisms, it may be necessary for the
1153    client to invoke the BindRequest multiple times.  If at any stage the
1154    client wishes to abort the bind process it MAY unbind and then drop
1155    the underlying connection.  Clients MUST NOT invoke operations
1156    between two Bind requests made as part of a multi-stage bind.
1157
1158    A client may abort a SASL bind negotiation by sending a BindRequest
1159    with a different value in the mechanism field of SaslCredentials, or
1160    an AuthenticationChoice other than sasl.
1161
1162    If the client sends a BindRequest with the sasl mechanism field as an
1163    empty string, the server MUST return a BindResponse with
1164    authMethodNotSupported as the resultCode.  This will allow clients to
1165    abort a negotiation if it wishes to try again with the same SASL
1166    mechanism.
1167
1168    Unlike LDAP v2, the client need not send a Bind Request in the first
1169    PDU of the connection.  The client may request any operations and the
1170    server MUST treat these as unauthenticated. If the server requires
1171    that the client bind before browsing or modifying the directory, the
1172    server MAY reject a request other than binding, unbinding or an
1173    extended request with the "operationsError" result.
1174
1175
1176
1177
1178 Wahl, et. al.               Standards Track                    [Page 21]
1179 \f
1180 RFC 2251                         LDAPv3                    December 1997
1181
1182
1183    If the client did not bind before sending a request and receives an
1184    operationsError, it may then send a Bind Request.  If this also fails
1185    or the client chooses not to bind on the existing connection, it will
1186    close the connection, reopen it and begin again by first sending a
1187    PDU with a Bind Request.  This will aid in interoperating with
1188    servers implementing other versions of LDAP.
1189
1190    Clients MAY send multiple bind requests on a connection to change
1191    their credentials.  A subsequent bind process has the effect of
1192    abandoning all operations outstanding on the connection.  (This
1193    simplifies server implementation.)  Authentication from earlier binds
1194    are subsequently ignored, and so if the bind fails, the connection
1195    will be treated as anonymous. If a SASL transfer encryption or
1196    integrity mechanism has been negotiated, and that mechanism does not
1197    support the changing of credentials from one identity to another,
1198    then the client MUST instead establish a new connection.
1199
1200 4.2.2. Authentication and Other Security Services
1201
1202    The simple authentication option provides minimal authentication
1203    facilities, with the contents of the authentication field consisting
1204    only of a cleartext password.  Note that the use of cleartext
1205    passwords is not recommended over open networks when there is no
1206    authentication or encryption being performed by a lower layer; see
1207    the "Security Considerations" section.
1208
1209    If no authentication is to be performed, then the simple
1210    authentication option MUST be chosen, and the password be of zero
1211    length.  (This is often done by LDAPv2 clients.)  Typically the DN is
1212    also of zero length.
1213
1214    The sasl choice allows for any mechanism defined for use with SASL
1215    [12].  The mechanism field contains the name of the mechanism.  The
1216    credentials field contains the arbitrary data used for
1217    authentication, inside an OCTET STRING wrapper.  Note that unlike
1218    some Internet application protocols where SASL is used, LDAP is not
1219    text-based, thus no base64 transformations are performed on the
1220    credentials.
1221
1222    If any SASL-based integrity or confidentiality services are enabled,
1223    they take effect following the transmission by the server and
1224    reception by the client of the final BindResponse with resultCode
1225    success.
1226
1227    The client can request that the server use authentication information
1228    from a lower layer protocol by using the SASL EXTERNAL mechanism.
1229
1230
1231
1232
1233
1234 Wahl, et. al.               Standards Track                    [Page 22]
1235 \f
1236 RFC 2251                         LDAPv3                    December 1997
1237
1238
1239 4.2.3. Bind Response
1240
1241    The Bind Response is defined as follows.
1242
1243         BindResponse ::= [APPLICATION 1] SEQUENCE {
1244              COMPONENTS OF LDAPResult,
1245              serverSaslCreds    [7] OCTET STRING OPTIONAL }
1246
1247     BindResponse consists simply of an indication from the server of he
1248    status of the client's request for authentication.
1249
1250    f the bind was successful, the resultCode will be success, therwise
1251    it will be one of:
1252
1253    - operationsError: server encountered an internal error,
1254
1255    - protocolError: unrecognized version number or incorrect PDU
1256      structure,
1257
1258    - authMethodNotSupported: unrecognized SASL mechanism name,
1259
1260    - strongAuthRequired: the server requires authentication be
1261      performed with a SASL mechanism,
1262
1263    - referral: this server cannot accept this bind and the client
1264      should try another,
1265
1266    - saslBindInProgress: the server requires the client to send a
1267      new bind request, with the same sasl mechanism, to continue the
1268      authentication process,
1269
1270    - inappropriateAuthentication: the server requires the client
1271      which had attempted to bind anonymously or without supplying
1272      credentials to provide some form of credentials,
1273
1274    - invalidCredentials: the wrong password was supplied or the SASL
1275      credentials could not be processed,
1276
1277    - unavailable: the server is shutting down.
1278
1279    If the server does not support the client's requested protocol
1280    version, it MUST set the resultCode to protocolError.
1281
1282    If the client receives a BindResponse response where the resultCode
1283    was protocolError, it MUST close the connection as the server will be
1284    unwilling to accept further operations.  (This is for compatibility
1285    with earlier versions of LDAP, in which the bind was always the first
1286    operation, and there was no negotiation.)
1287
1288
1289
1290 Wahl, et. al.               Standards Track                    [Page 23]
1291 \f
1292 RFC 2251                         LDAPv3                    December 1997
1293
1294
1295    The serverSaslCreds are used as part of a SASL-defined bind mechanism
1296    to allow the client to authenticate the server to which it is
1297    communicating, or to perform "challenge-response" authentication. If
1298    the client bound with the password choice, or the SASL mechanism does
1299    not require the server to return information to the client, then this
1300    field is not to be included in the result.
1301
1302 4.3. Unbind Operation
1303
1304    The function of the Unbind Operation is to terminate a protocol
1305    session.  The Unbind Operation is defined as follows:
1306
1307         UnbindRequest ::= [APPLICATION 2] NULL
1308
1309    The Unbind Operation has no response defined. Upon transmission of an
1310    UnbindRequest, a protocol client may assume that the protocol session
1311    is terminated. Upon receipt of an UnbindRequest, a protocol server
1312    may assume that the requesting client has terminated the session and
1313    that all outstanding requests may be discarded, and may close the
1314    connection.
1315
1316 4.4. Unsolicited Notification
1317
1318    An unsolicited notification is an LDAPMessage sent from the server to
1319    the client which is not in response to any LDAPMessage received by
1320    the server. It is used to signal an extraordinary condition in the
1321    server or in the connection between the client and the server.  The
1322    notification is of an advisory nature, and the server will not expect
1323    any response to be returned from the client.
1324
1325    The unsolicited notification is structured as an LDAPMessage in which
1326    the messageID is 0 and protocolOp is of the extendedResp form.  The
1327    responseName field of the ExtendedResponse is present. The LDAPOID
1328    value MUST be unique for this notification, and not be used in any
1329    other situation.
1330
1331    One unsolicited notification is defined in this document.
1332
1333 4.4.1. Notice of Disconnection
1334
1335    This notification may be used by the server to advise the client that
1336    the server is about to close the connection due to an error
1337    condition.  Note that this notification is NOT a response to an
1338    unbind requested by the client: the server MUST follow the procedures
1339    of section 4.3. This notification is intended to assist clients in
1340    distinguishing between an error condition and a transient network
1341
1342
1343
1344
1345
1346 Wahl, et. al.               Standards Track                    [Page 24]
1347 \f
1348 RFC 2251                         LDAPv3                    December 1997
1349
1350
1351    failure.  As with a connection close due to network failure, the
1352    client MUST NOT assume that any outstanding requests which modified
1353    the directory have succeeded or failed.
1354
1355    The responseName is 1.3.6.1.4.1.1466.20036, the response field is
1356    absent, and the resultCode is used to indicate the reason for the
1357    disconnection.
1358
1359    The following resultCode values are to be used in this notification:
1360
1361    - protocolError: The server has received data from the client in
1362    which
1363      the LDAPMessage structure could not be parsed.
1364
1365    - strongAuthRequired: The server has detected that an established
1366      underlying security association protecting communication between
1367      the client and server has unexpectedly failed or been compromised.
1368
1369    - unavailable: This server will stop accepting new connections and
1370      operations on all existing connections, and be unavailable for an
1371      extended period of time.  The client may make use of an alternative
1372      server.
1373
1374    After sending this notice, the server MUST close the connection.
1375    After receiving this notice, the client MUST NOT transmit any further
1376    on the connection, and may abruptly close the connection.
1377
1378 4.5. Search Operation
1379
1380    The Search Operation allows a client to request that a search be
1381    performed on its behalf by a server.  This can be used to read
1382    attributes from a single entry, from entries immediately below a
1383    particular entry, or a whole subtree of entries.
1384
1385 4.5.1. Search Request
1386
1387    The Search Request is defined as follows:
1388
1389         SearchRequest ::= [APPLICATION 3] SEQUENCE {
1390                 baseObject      LDAPDN,
1391                 scope           ENUMERATED {
1392                         baseObject              (0),
1393                         singleLevel             (1),
1394                         wholeSubtree            (2) },
1395                 derefAliases    ENUMERATED {
1396                         neverDerefAliases       (0),
1397                         derefInSearching        (1),
1398                         derefFindingBaseObj     (2),
1399
1400
1401
1402 Wahl, et. al.               Standards Track                    [Page 25]
1403 \f
1404 RFC 2251                         LDAPv3                    December 1997
1405
1406
1407                         derefAlways             (3) },
1408                 sizeLimit       INTEGER (0 .. maxInt),
1409                 timeLimit       INTEGER (0 .. maxInt),
1410                 typesOnly       BOOLEAN,
1411                 filter          Filter,
1412                 attributes      AttributeDescriptionList }
1413
1414         Filter ::= CHOICE {
1415                 and             [0] SET OF Filter,
1416                 or              [1] SET OF Filter,
1417                 not             [2] Filter,
1418                 equalityMatch   [3] AttributeValueAssertion,
1419                 substrings      [4] SubstringFilter,
1420                 greaterOrEqual  [5] AttributeValueAssertion,
1421                 lessOrEqual     [6] AttributeValueAssertion,
1422                 present         [7] AttributeDescription,
1423                 approxMatch     [8] AttributeValueAssertion,
1424                 extensibleMatch [9] MatchingRuleAssertion }
1425
1426         SubstringFilter ::= SEQUENCE {
1427                 type            AttributeDescription,
1428                 -- at least one must be present
1429                 substrings      SEQUENCE OF CHOICE {
1430                         initial [0] LDAPString,
1431                         any     [1] LDAPString,
1432                         final   [2] LDAPString } }
1433
1434         MatchingRuleAssertion ::= SEQUENCE {
1435                 matchingRule    [1] MatchingRuleId OPTIONAL,
1436                 type            [2] AttributeDescription OPTIONAL,
1437                 matchValue      [3] AssertionValue,
1438                 dnAttributes    [4] BOOLEAN DEFAULT FALSE }
1439
1440    Parameters of the Search Request are:
1441
1442    - baseObject: An LDAPDN that is the base object entry relative to
1443      which the search is to be performed.
1444
1445    - scope: An indicator of the scope of the search to be performed. The
1446      semantics of the possible values of this field are identical to the
1447      semantics of the scope field in the X.511 Search Operation.
1448
1449    - derefAliases: An indicator as to how alias objects (as defined in
1450      X.501) are to be handled in searching.  The semantics of the
1451      possible values of this field are:
1452
1453              neverDerefAliases: do not dereference aliases in searching
1454              or in locating the base object of the search;
1455
1456
1457
1458 Wahl, et. al.               Standards Track                    [Page 26]
1459 \f
1460 RFC 2251                         LDAPv3                    December 1997
1461
1462
1463              derefInSearching: dereference aliases in subordinates of
1464              the base object in searching, but not in locating the
1465              base object of the search;
1466
1467              derefFindingBaseObj: dereference aliases in locating
1468              the base object of the search, but not when searching
1469              subordinates of the base object;
1470
1471              derefAlways: dereference aliases both in searching and in
1472              locating the base object of the search.
1473
1474    - sizelimit: A sizelimit that restricts the maximum number of entries
1475      to be returned as a result of the search. A value of 0 in this
1476      field indicates that no client-requested sizelimit restrictions are
1477      in effect for the search.  Servers may enforce a maximum number of
1478      entries to return.
1479
1480    - timelimit: A timelimit that restricts the maximum time (in seconds)
1481      allowed for a search. A value of 0 in this field indicates that no
1482      client-requested timelimit restrictions are in effect for the
1483      search.
1484
1485    - typesOnly: An indicator as to whether search results will contain
1486      both attribute types and values, or just attribute types.  Setting
1487      this field to TRUE causes only attribute types (no values) to be
1488      returned.  Setting this field to FALSE causes both attribute types
1489      and values to be returned.
1490
1491    - filter: A filter that defines the conditions that must be fulfilled
1492      in order for the search to match a given entry.
1493
1494      The 'and', 'or' and 'not' choices can be used to form combinations of
1495      filters. At least one filter element MUST be present in an 'and' or
1496      'or' choice.  The others match against individual attribute values of
1497      entries in the scope of the search.  (Implementor's note: the 'not'
1498      filter is an example of a tagged choice in an implicitly-tagged
1499      module.  In BER this is treated as if the tag was explicit.)
1500
1501      A server MUST evaluate filters according to the three-valued logic
1502      of X.511(93) section 7.8.1.  In summary, a filter is evaluated to
1503      either "TRUE", "FALSE" or "Undefined".  If the filter evaluates
1504      to TRUE for a particular entry, then the attributes of that entry
1505      are returned as part of the search result (subject to any applicable
1506      access control restrictions). If the filter evaluates to FALSE or
1507      Undefined, then the entry is ignored for the search.
1508
1509
1510
1511
1512
1513
1514 Wahl, et. al.               Standards Track                    [Page 27]
1515 \f
1516 RFC 2251                         LDAPv3                    December 1997
1517
1518
1519      A filter of the "and" choice is TRUE if all the filters in the SET
1520      OF evaluate to TRUE, FALSE if at least one filter is FALSE, and
1521      otherwise Undefined.  A filter of the "or" choice is FALSE if all
1522      of the filters in the SET OF evaluate to FALSE, TRUE if at least
1523      one filter is TRUE, and Undefined otherwise.  A filter of the "not"
1524      choice is TRUE if the filter being negated is FALSE, FALSE if it is
1525      TRUE, and Undefined if it is Undefined.
1526
1527      The present match evaluates to TRUE where there is an attribute or
1528      subtype of the specified attribute description present in an entry,
1529      and FALSE otherwise (including a presence test with an unrecognized
1530      attribute description.)
1531
1532      The extensibleMatch is new in this version of LDAP.  If the
1533      matchingRule field is absent, the type field MUST be present, and
1534      the equality match is performed for that type.  If the type field is
1535      absent and matchingRule is present, the matchValue is compared
1536      against all attributes in an entry which support that matchingRule,
1537      and the matchingRule determines the syntax for the assertion value
1538      (the filter item evaluates to TRUE if it matches with at least
1539      one attribute in the entry, FALSE if it does not match any attribute
1540      in the entry, and Undefined if the matchingRule is not recognized
1541      or the assertionValue cannot be parsed.)  If the type field is
1542      present and matchingRule is present, the matchingRule MUST be one
1543      permitted for use with that type, otherwise the filter item is
1544      undefined.  If the dnAttributes field is set to TRUE, the match is
1545      applied against all the attributes in an entry's distinguished name
1546      as well, and also evaluates to TRUE if there is at least one
1547      attribute in the distinguished name for which the filter item
1548      evaluates to TRUE.  (Editors note: The dnAttributes field is present
1549      so that there does not need to be multiple versions of generic
1550      matching rules such as for word matching, one to apply to entries
1551      and another to apply to entries and dn attributes as well).
1552
1553      A filter item evaluates to Undefined when the server would not
1554      be able to determine whether the assertion value matches an
1555      entry.  If an attribute description in an equalityMatch, substrings,
1556      greaterOrEqual, lessOrEqual, approxMatch or extensibleMatch
1557      filter is not recognized by the server, a matching rule id in the
1558      extensibleMatch is not recognized by the server, the assertion
1559      value cannot be parsed, or the type of filtering requested is not
1560      implemented, then the filter is Undefined.  Thus for example if a
1561      server did not recognize the attribute type shoeSize, a filter of
1562      (shoeSize=*) would evaluate to FALSE, and the filters (shoeSize=12),
1563      (shoeSize>=12) and (shoeSize<=12) would evaluate to Undefined.
1564
1565
1566
1567
1568
1569
1570 Wahl, et. al.               Standards Track                    [Page 28]
1571 \f
1572 RFC 2251                         LDAPv3                    December 1997
1573
1574
1575      Servers MUST NOT return errors if attribute descriptions or matching
1576      rule ids are not recognized, or assertion values cannot be parsed.
1577      More details of filter processing are given in section 7.8 of X.511
1578      [8].
1579
1580    - attributes: A list of the attributes to be returned from each entry
1581      which matches the search filter. There are two special values which
1582      may be used: an empty list with no attributes, and the attribute
1583      description string "*".  Both of these signify that all user
1584      attributes are to be returned.  (The "*" allows the client to
1585      request all user attributes in addition to specific operational
1586      attributes).
1587
1588      Attributes MUST be named at most once in the list, and are returned
1589      at most once in an entry.   If there are attribute descriptions in
1590      the list which are not recognized, they are ignored by the server.
1591
1592      If the client does not want any attributes returned, it can specify
1593      a list containing only the attribute with OID "1.1".  This OID was
1594      chosen arbitrarily and does not correspond to any attribute in use.
1595
1596      Client implementors should note that even if all user attributes are
1597      requested, some attributes of the entry may not be included in
1598      search results due to access control or other restrictions.
1599      Furthermore, servers will not return operational attributes, such
1600      as objectClasses or attributeTypes, unless they are listed by name,
1601      since there may be extremely large number of values for certain
1602      operational attributes. (A list of operational attributes for use
1603      in LDAP is given in [5].)
1604
1605    Note that an X.500 "list"-like operation can be emulated by the client
1606    requesting a one-level LDAP search operation with a filter checking
1607    for the existence of the objectClass attribute, and that an X.500
1608    "read"-like operation can be emulated by a base object LDAP search
1609    operation with the same filter.  A server which provides a gateway to
1610    X.500 is not required to use the Read or List operations, although it
1611    may choose to do so, and if it does must provide the same semantics
1612    as the X.500 search operation.
1613
1614 4.5.2. Search Result
1615
1616    The results of the search attempted by the server upon receipt of a
1617    Search Request are returned in Search Responses, which are LDAP
1618    messages containing either SearchResultEntry, SearchResultReference,
1619    ExtendedResponse or SearchResultDone data types.
1620
1621         SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
1622                 objectName      LDAPDN,
1623
1624
1625
1626 Wahl, et. al.               Standards Track                    [Page 29]
1627 \f
1628 RFC 2251                         LDAPv3                    December 1997
1629
1630
1631                 attributes      PartialAttributeList }
1632
1633         PartialAttributeList ::= SEQUENCE OF SEQUENCE {
1634                 type    AttributeDescription,
1635                 vals    SET OF AttributeValue }
1636         -- implementors should note that the PartialAttributeList may
1637         -- have zero elements (if none of the attributes of that entry
1638         -- were requested, or could be returned), and that the vals set
1639         -- may also have zero elements (if types only was requested, or
1640         -- all values were excluded from the result.)
1641
1642         SearchResultReference ::= [APPLICATION 19] SEQUENCE OF LDAPURL
1643         -- at least one LDAPURL element must be present
1644
1645         SearchResultDone ::= [APPLICATION 5] LDAPResult
1646
1647    Upon receipt of a Search Request, a server will perform the necessary
1648    search of the DIT.
1649
1650    If the LDAP session is operating over a connection-oriented transport
1651    such as TCP, the server will return to the client a sequence of
1652    responses in separate LDAP messages.  There may be zero or more
1653    responses containing SearchResultEntry, one for each entry found
1654    during the search.  There may also be zero or more responses
1655    containing SearchResultReference, one for each area not explored by
1656    this server during the search.  The SearchResultEntry and
1657    SearchResultReference PDUs may come in any order. Following all the
1658    SearchResultReference responses and all SearchResultEntry responses
1659    to be returned by the server, the server will return a response
1660    containing the SearchResultDone, which contains an indication of
1661    success, or detailing any errors that have occurred.
1662
1663    Each entry returned in a SearchResultEntry will contain all
1664    attributes, complete with associated values if necessary, as
1665    specified in the attributes field of the Search Request.  Return of
1666    attributes is subject to access control and other administrative
1667    policy.  Some attributes may be returned in binary format (indicated
1668    by the AttributeDescription in the response having the binary option
1669    present).
1670
1671    Some attributes may be constructed by the server and appear in a
1672    SearchResultEntry attribute list, although they are not stored
1673    attributes of an entry. Clients MUST NOT assume that all attributes
1674    can be modified, even if permitted by access control.
1675
1676    LDAPMessage responses of the ExtendedResponse form are reserved for
1677    returning information associated with a control requested by the
1678    client.  These may be defined in future versions of this document.
1679
1680
1681
1682 Wahl, et. al.               Standards Track                    [Page 30]
1683 \f
1684 RFC 2251                         LDAPv3                    December 1997
1685
1686
1687 4.5.3. Continuation References in the Search Result
1688
1689    If the server was able to locate the entry referred to by the
1690    baseObject but was unable to search all the entries in the scope at
1691    and under the baseObject, the server may return one or more
1692    SearchResultReference, each containing a reference to another set of
1693    servers for continuing the operation.  A server MUST NOT return any
1694    SearchResultReference if it has not located the baseObject and
1695    thus has not searched any entries; in this case it would return a
1696    SearchResultDone containing a referral resultCode.
1697
1698    In the absence of indexing information provided to a server from
1699    servers holding subordinate naming contexts, SearchResultReference
1700    responses are not affected by search filters and are always returned
1701    when in scope.
1702
1703    The SearchResultReference is of the same data type as the Referral.
1704    URLs for servers implementing the LDAP protocol are written according
1705    to [9].  The <dn> part MUST be present in the URL, with the new target
1706    object name.  The client MUST use this name in its next request.
1707    Some servers (e.g. part of a distributed index exchange system) may
1708    provide a different filter in the URLs of the SearchResultReference.
1709    If the filter part of the URL is present in an LDAP URL, the client
1710    MUST use the new filter in its next request to progress the search,
1711    and if the filter part is absent the client will use again the same
1712    filter.  Other aspects of the new search request may be the same or
1713    different as the search which generated the continuation references.
1714
1715    Other kinds of URLs may be returned so long as the operation could be
1716    performed using that protocol.
1717
1718    The name of an unexplored subtree in a SearchResultReference need not
1719    be subordinate to the base object.
1720
1721    In order to complete the search, the client MUST issue a new search
1722    operation for each SearchResultReference that is returned.  Note that
1723    the abandon operation described in section 4.11 applies only to a
1724    particular operation sent on a connection between a client and server,
1725    and if the client has multiple outstanding search operations to
1726    different servers, it MUST abandon each operation individually.
1727
1728 4.5.3.1. Example
1729
1730    For example, suppose the contacted server (hosta) holds the entry
1731    "O=MNN,C=WW" and the entry "CN=Manager,O=MNN,C=WW".  It knows that
1732    either LDAP-capable servers (hostb) or (hostc) hold
1733    "OU=People,O=MNN,C=WW" (one is the master and the other server a
1734
1735
1736
1737
1738 Wahl, et. al.               Standards Track                    [Page 31]
1739 \f
1740 RFC 2251                         LDAPv3                    December 1997
1741
1742
1743    shadow), and that LDAP-capable server (hostd) holds the subtree
1744    "OU=Roles,O=MNN,C=WW".  If a subtree search of "O=MNN,C=WW" is
1745    requested to the contacted server, it may return the following:
1746
1747      SearchResultEntry for O=MNN,C=WW
1748      SearchResultEntry for CN=Manager,O=MNN,C=WW
1749      SearchResultReference {
1750        ldap://hostb/OU=People,O=MNN,C=WW
1751        ldap://hostc/OU=People,O=MNN,C=WW
1752      }
1753      SearchResultReference {
1754        ldap://hostd/OU=Roles,O=MNN,C=WW
1755      }
1756      SearchResultDone (success)
1757
1758    Client implementors should note that when following a
1759    SearchResultReference, additional SearchResultReference may be
1760    generated.  Continuing the example, if the client contacted the
1761    server (hostb) and issued the search for the subtree
1762    "OU=People,O=MNN,C=WW", the server might respond as follows:
1763
1764      SearchResultEntry for OU=People,O=MNN,C=WW
1765      SearchResultReference {
1766       ldap://hoste/OU=Managers,OU=People,O=MNN,C=WW
1767      }
1768      SearchResultReference {
1769       ldap://hostf/OU=Consultants,OU=People,O=MNN,C=WW
1770      }
1771      SearchResultDone (success)
1772
1773    If the contacted server does not hold the base object for the search,
1774    then it will return a referral to the client.  For example, if the
1775    client requests a subtree search of "O=XYZ,C=US" to hosta, the server
1776    may return only a SearchResultDone containing a referral.
1777
1778      SearchResultDone (referral) {
1779        ldap://hostg/
1780      }
1781
1782 4.6. Modify Operation
1783
1784    The Modify Operation allows a client to request that a modification
1785    of an entry be performed on its behalf by a server.  The Modify
1786    Request is defined as follows:
1787
1788         ModifyRequest ::= [APPLICATION 6] SEQUENCE {
1789                 object          LDAPDN,
1790                 modification    SEQUENCE OF SEQUENCE {
1791
1792
1793
1794 Wahl, et. al.               Standards Track                    [Page 32]
1795 \f
1796 RFC 2251                         LDAPv3                    December 1997
1797
1798
1799                         operation       ENUMERATED {
1800                                                 add     (0),
1801                                                 delete  (1),
1802                                                 replace (2) },
1803                         modification    AttributeTypeAndValues } }
1804
1805         AttributeTypeAndValues ::= SEQUENCE {
1806                 type    AttributeDescription,
1807                 vals    SET OF AttributeValue }
1808
1809    Parameters of the Modify Request are:
1810
1811    - object: The object to be modified. The value of this field contains
1812      the DN of the entry to be modified.  The server will not perform
1813      any alias dereferencing in determining the object to be modified.
1814
1815    - modification: A list of modifications to be performed on the entry.
1816      The entire list of entry modifications MUST be performed
1817      in the order they are listed, as a single atomic operation.  While
1818      individual modifications may violate the directory schema, the
1819      resulting entry after the entire list of modifications is performed
1820      MUST conform to the requirements of the directory schema. The
1821      values that may be taken on by the 'operation' field in each
1822      modification construct have the following semantics respectively:
1823
1824              add: add values listed to the given attribute, creating
1825              the attribute if necessary;
1826
1827              delete: delete values listed from the given attribute,
1828              removing the entire attribute if no values are listed, or
1829              if all current values of the attribute are listed for
1830              deletion;
1831
1832              replace: replace all existing values of the given attribute
1833              with the new values listed, creating the attribute if it
1834              did not already exist.  A replace with no value will delete
1835              the entire attribute if it exists, and is ignored if the
1836              attribute does not exist.
1837
1838    The result of the modify attempted by the server upon receipt of a
1839    Modify Request is returned in a Modify Response, defined as follows:
1840
1841         ModifyResponse ::= [APPLICATION 7] LDAPResult
1842
1843    Upon receipt of a Modify Request, a server will perform the necessary
1844    modifications to the DIT.
1845
1846
1847
1848
1849
1850 Wahl, et. al.               Standards Track                    [Page 33]
1851 \f
1852 RFC 2251                         LDAPv3                    December 1997
1853
1854
1855    The server will return to the client a single Modify Response
1856    indicating either the successful completion of the DIT modification,
1857    or the reason that the modification failed. Note that due to the
1858    requirement for atomicity in applying the list of modifications in
1859    the Modify Request, the client may expect that no modifications of
1860    the DIT have been performed if the Modify Response received indicates
1861    any sort of error, and that all requested modifications have been
1862    performed if the Modify Response indicates successful completion of
1863    the Modify Operation.  If the connection fails, whether the
1864    modification occurred or not is indeterminate.
1865
1866    The Modify Operation cannot be used to remove from an entry any of
1867    its distinguished values, those values which form the entry's
1868    relative distinguished name.  An attempt to do so will result in the
1869    server returning the error notAllowedOnRDN.  The Modify DN Operation
1870    described in section 4.9 is used to rename an entry.
1871
1872    If an equality match filter has not been defined for an attribute type,
1873    clients MUST NOT attempt to delete individual values of that attribute
1874    from an entry using the "delete" form of a modification, and MUST
1875    instead use the "replace" form.
1876
1877    Note that due to the simplifications made in LDAP, there is not a
1878    direct mapping of the modifications in an LDAP ModifyRequest onto the
1879    EntryModifications of a DAP ModifyEntry operation, and different
1880    implementations of LDAP-DAP gateways may use different means of
1881    representing the change.  If successful, the final effect of the
1882    operations on the entry MUST be identical.
1883
1884 4.7. Add Operation
1885
1886    The Add Operation allows a client to request the addition of an entry
1887    into the directory. The Add Request is defined as follows:
1888
1889         AddRequest ::= [APPLICATION 8] SEQUENCE {
1890                 entry           LDAPDN,
1891                 attributes      AttributeList }
1892
1893         AttributeList ::= SEQUENCE OF SEQUENCE {
1894                 type    AttributeDescription,
1895                 vals    SET OF AttributeValue }
1896
1897    Parameters of the Add Request are:
1898
1899    - entry: the Distinguished Name of the entry to be added. Note that
1900      the server will not dereference any aliases in locating the entry
1901      to be added.
1902
1903
1904
1905
1906 Wahl, et. al.               Standards Track                    [Page 34]
1907 \f
1908 RFC 2251                         LDAPv3                    December 1997
1909
1910
1911    - attributes: the list of attributes that make up the content of the
1912      entry being added.  Clients MUST include distinguished values
1913      (those forming the entry's own RDN) in this list, the objectClass
1914      attribute, and values of any mandatory attributes of the listed
1915      object classes.  Clients MUST NOT supply the createTimestamp or
1916      creatorsName attributes, since these will be generated
1917      automatically by the server.
1918
1919    The entry named in the entry field of the AddRequest MUST NOT exist
1920    for the AddRequest to succeed.  The parent of the entry to be added
1921    MUST exist.  For example, if the client attempted to add
1922    "CN=JS,O=Foo,C=US", the "O=Foo,C=US" entry did not exist, and the
1923    "C=US" entry did exist, then the server would return the error
1924    noSuchObject with the matchedDN field containing "C=US".  If the
1925    parent entry exists but is not in a naming context held by the
1926    server, the server SHOULD return a referral to the server holding the
1927    parent entry.
1928
1929    Servers implementations SHOULD NOT restrict where entries can be
1930    located in the directory.  Some servers MAY allow the administrator
1931    to restrict the classes of entries which can be added to the
1932    directory.
1933
1934    Upon receipt of an Add Request, a server will attempt to perform the
1935    add requested.  The result of the add attempt will be returned to the
1936    client in the Add Response, defined as follows:
1937
1938         AddResponse ::= [APPLICATION 9] LDAPResult
1939
1940    A response of success indicates that the new entry is present in the
1941    directory.
1942
1943 4.8. Delete Operation
1944
1945    The Delete Operation allows a client to request the removal of an
1946    entry from the directory. The Delete Request is defined as follows:
1947
1948         DelRequest ::= [APPLICATION 10] LDAPDN
1949
1950    The Delete Request consists of the Distinguished Name of the entry to
1951    be deleted. Note that the server will not dereference aliases while
1952    resolving the name of the target entry to be removed, and that only
1953    leaf entries (those with no subordinate entries) can be deleted with
1954    this operation.
1955
1956    The result of the delete attempted by the server upon receipt of a
1957    Delete Request is returned in the Delete Response, defined as
1958    follows:
1959
1960
1961
1962 Wahl, et. al.               Standards Track                    [Page 35]
1963 \f
1964 RFC 2251                         LDAPv3                    December 1997
1965
1966
1967         DelResponse ::= [APPLICATION 11] LDAPResult
1968
1969    Upon receipt of a Delete Request, a server will attempt to perform
1970    the entry removal requested. The result of the delete attempt will be
1971    returned to the client in the Delete Response.
1972
1973 4.9. Modify DN Operation
1974
1975    The Modify DN Operation allows a client to change the leftmost (least
1976    significant) component of the name of an entry in the directory, or
1977    to move a subtree of entries to a new location in the directory.  The
1978    Modify DN Request is defined as follows:
1979
1980         ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
1981                 entry           LDAPDN,
1982                 newrdn          RelativeLDAPDN,
1983                 deleteoldrdn    BOOLEAN,
1984                 newSuperior     [0] LDAPDN OPTIONAL }
1985
1986    Parameters of the Modify DN Request are:
1987
1988    - entry: the Distinguished Name of the entry to be changed.  This
1989      entry may or may not have subordinate entries.
1990
1991    - newrdn: the RDN that will form the leftmost component of the new
1992      name of the entry.
1993
1994    - deleteoldrdn: a boolean parameter that controls whether the old RDN
1995      attribute values are to be retained as attributes of the entry, or
1996      deleted from the entry.
1997
1998    - newSuperior: if present, this is the Distinguished Name of the entry
1999      which becomes the immediate superior of the existing entry.
2000
2001    The result of the name change attempted by the server upon receipt of
2002    a Modify DN Request is returned in the Modify DN Response, defined
2003    as follows:
2004
2005         ModifyDNResponse ::= [APPLICATION 13] LDAPResult
2006
2007    Upon receipt of a ModifyDNRequest, a server will attempt to
2008    perform the name change. The result of the name change attempt will
2009    be returned to the client in the Modify DN Response.
2010
2011    For example, if the entry named in the "entry" parameter was
2012    "cn=John Smith,c=US", the newrdn parameter was "cn=John Cougar Smith",
2013    and the newSuperior parameter was absent, then this operation would
2014
2015
2016
2017
2018 Wahl, et. al.               Standards Track                    [Page 36]
2019 \f
2020 RFC 2251                         LDAPv3                    December 1997
2021
2022
2023    attempt to rename the entry to be "cn=John Cougar Smith,c=US".  If
2024    there was already an entry with that name, the operation would fail
2025    with error code entryAlreadyExists.
2026
2027    If the deleteoldrdn parameter is TRUE, the values forming the old
2028    RDN are deleted from the entry.  If the deleteoldrdn parameter is
2029    FALSE, the values forming the old RDN will be retained as
2030    non-distinguished attribute values of the entry.  The server may
2031    not perform the operation and return an error code if the setting of
2032    the deleteoldrdn parameter would cause a schema inconsistency in the
2033    entry.
2034
2035    Note that X.500 restricts the ModifyDN operation to only affect
2036    entries that are contained within a single server.  If the LDAP
2037    server is mapped onto DAP, then this restriction will apply, and the
2038    resultCode affectsMultipleDSAs will be returned if this error
2039    occurred.  In general clients MUST NOT expect to be able to perform
2040    arbitrary movements of entries and subtrees between servers.
2041
2042 4.10. Compare Operation
2043
2044    The Compare Operation allows a client to compare an assertion
2045    provided with an entry in the directory. The Compare Request is
2046    defined as follows:
2047
2048         CompareRequest ::= [APPLICATION 14] SEQUENCE {
2049                 entry           LDAPDN,
2050                 ava             AttributeValueAssertion }
2051
2052    Parameters of the Compare Request are:
2053
2054    - entry: the name of the entry to be compared with.
2055
2056    - ava: the assertion with which an attribute in the entry is to be
2057      compared.
2058
2059    The result of the compare attempted by the server upon receipt of a
2060    Compare Request is returned in the Compare Response, defined as
2061    follows:
2062
2063         CompareResponse ::= [APPLICATION 15] LDAPResult
2064
2065    Upon receipt of a Compare Request, a server will attempt to perform
2066    the requested comparison. The result of the comparison will be
2067    returned to the client in the Compare Response. Note that errors and
2068    the result of comparison are all returned in the same construct.
2069
2070
2071
2072
2073
2074 Wahl, et. al.               Standards Track                    [Page 37]
2075 \f
2076 RFC 2251                         LDAPv3                    December 1997
2077
2078
2079    Note that some directory systems may establish access controls which
2080    permit the values of certain attributes (such as userPassword) to be
2081    compared but not read.  In a search result, it may be that an
2082    attribute of that type would be returned, but with an empty set of
2083    values.
2084
2085 4.11. Abandon Operation
2086
2087    The function of the Abandon Operation is to allow a client to request
2088    that the server abandon an outstanding operation.  The Abandon
2089    Request is defined as follows:
2090
2091         AbandonRequest ::= [APPLICATION 16] MessageID
2092
2093    The MessageID MUST be that of a an operation which was requested
2094    earlier in this connection.
2095
2096    (The abandon request itself has its own message id.  This is distinct
2097     from the id of the earlier operation being abandoned.)
2098
2099    There is no response defined in the Abandon Operation. Upon
2100    transmission of an Abandon Operation, a client may expect that the
2101    operation identified by the Message ID in the Abandon Request has
2102    been abandoned. In the event that a server receives an Abandon
2103    Request on a Search Operation in the midst of transmitting responses
2104    to the search, that server MUST cease transmitting entry responses to
2105    the abandoned request immediately, and MUST NOT send the
2106    SearchResponseDone.  Of course, the server MUST ensure that only
2107    properly encoded LDAPMessage PDUs are transmitted.
2108
2109    Clients MUST NOT send abandon requests for the same operation
2110    multiple times, and MUST also be prepared to receive results from
2111    operations it has abandoned (since these may have been in transit
2112    when the abandon was requested).
2113
2114    Servers MUST discard abandon requests for message IDs they do not
2115    recognize, for operations which cannot be abandoned, and for
2116    operations which have already been abandoned.
2117
2118 4.12. Extended Operation
2119
2120    An extension mechanism has been added in this version of LDAP, in
2121    order to allow additional operations to be defined for services not
2122    available elsewhere in this protocol, for instance digitally signed
2123    operations and results.
2124
2125
2126
2127
2128
2129
2130 Wahl, et. al.               Standards Track                    [Page 38]
2131 \f
2132 RFC 2251                         LDAPv3                    December 1997
2133
2134
2135    The extended operation allows clients to make requests and receive
2136    responses with predefined syntaxes and semantics.  These may be
2137    defined in RFCs or be private to particular implementations.  Each
2138    request MUST have a unique OBJECT IDENTIFIER assigned to it.
2139
2140         ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
2141                 requestName      [0] LDAPOID,
2142                 requestValue     [1] OCTET STRING OPTIONAL }
2143
2144    The requestName is a dotted-decimal representation of the OBJECT
2145    IDENTIFIER corresponding to the request. The requestValue is
2146    information in a form defined by that request, encapsulated inside an
2147    OCTET STRING.
2148
2149    The server will respond to this with an LDAPMessage containing the
2150    ExtendedResponse.
2151
2152         ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
2153                 COMPONENTS OF LDAPResult,
2154                 responseName     [10] LDAPOID OPTIONAL,
2155                 response         [11] OCTET STRING OPTIONAL }
2156
2157    If the server does not recognize the request name, it MUST return
2158    only the response fields from LDAPResult, containing the
2159    protocolError result code.
2160
2161 5.  Protocol Element Encodings and Transfer
2162
2163    One underlying service is defined here.  Clients and servers SHOULD
2164    implement the mapping of LDAP over TCP described in 5.2.1.
2165
2166 5.1. Mapping Onto BER-based Transport Services
2167
2168    The protocol elements of LDAP are encoded for exchange using the
2169    Basic Encoding Rules (BER) [11] of ASN.1 [3]. However, due to the
2170    high overhead involved in using certain elements of the BER, the
2171    following additional restrictions are placed on BER-encodings of LDAP
2172    protocol elements:
2173
2174    (1) Only the definite form of length encoding will be used.
2175
2176    (2) OCTET STRING values will be encoded in the primitive form only.
2177
2178    (3) If the value of a BOOLEAN type is true, the encoding MUST have
2179        its contents octets set to hex "FF".
2180
2181
2182
2183
2184
2185
2186 Wahl, et. al.               Standards Track                    [Page 39]
2187 \f
2188 RFC 2251                         LDAPv3                    December 1997
2189
2190
2191    (4) If a value of a type is its default value, it MUST be absent.
2192        Only some BOOLEAN and INTEGER types have default values in this
2193        protocol definition.
2194
2195    These restrictions do not apply to ASN.1 types encapsulated inside of
2196    OCTET STRING values, such as attribute values, unless otherwise
2197    noted.
2198
2199 5.2. Transfer Protocols
2200
2201    This protocol is designed to run over connection-oriented, reliable
2202    transports, with all 8 bits in an octet being significant in the data
2203    stream.
2204
2205 5.2.1. Transmission Control Protocol (TCP)
2206
2207    The LDAPMessage PDUs are mapped directly onto the TCP bytestream.  It
2208    is recommended that server implementations running over the TCP MAY
2209    provide a protocol listener on the assigned port, 389.  Servers may
2210    instead provide a listener on a different port number. Clients MUST
2211    support contacting servers on any valid TCP port.
2212
2213 6.  Implementation Guidelines
2214
2215    This document describes an Internet protocol.
2216
2217 6.1. Server Implementations
2218
2219    The server MUST be capable of recognizing all the mandatory attribute
2220    type names and implement the syntaxes specified in [5].  Servers MAY
2221    also recognize additional attribute type names.
2222
2223 6.2. Client Implementations
2224
2225    Clients which request referrals MUST ensure that they do not loop
2226    between servers. They MUST NOT repeatedly contact the same server for
2227    the same request with the same target entry name, scope and filter.
2228    Some clients may be using a counter that is incremented each time
2229    referral handling occurs for an operation, and these kinds of clients
2230    MUST be able to handle a DIT with at least ten layers of naming
2231    contexts between the root and a leaf entry.
2232
2233    In the absence of prior agreements with servers, clients SHOULD NOT
2234    assume that servers support any particular schemas beyond those
2235    referenced in section 6.1. Different schemas can have different
2236    attribute types with the same names.  The client can retrieve the
2237    subschema entries referenced by the subschemaSubentry attribute in
2238    the server's root DSE or in entries held by the server.
2239
2240
2241
2242 Wahl, et. al.               Standards Track                    [Page 40]
2243 \f
2244 RFC 2251                         LDAPv3                    December 1997
2245
2246
2247 7.  Security Considerations
2248
2249    When used with a connection-oriented transport, this version of the
2250    protocol provides facilities for the LDAP v2 authentication
2251    mechanism, simple authentication using a cleartext password, as well
2252    as any SASL mechanism [12].  SASL allows for integrity and privacy
2253    services to be negotiated.
2254
2255    It is also permitted that the server can return its credentials to
2256    the client, if it chooses to do so.
2257
2258    Use of cleartext password is strongly discouraged where the
2259    underlying transport service cannot guarantee confidentiality and may
2260    result in disclosure of the password to unauthorized parties.
2261
2262    When used with SASL, it should be noted that the name field of the
2263    BindRequest is not protected against modification.  Thus if the
2264    distinguished name of the client (an LDAPDN) is agreed through the
2265    negotiation of the credentials, it takes precedence over any value in
2266    the unprotected name field.
2267
2268    Implementations which cache attributes and entries obtained via LDAP
2269    MUST ensure that access controls are maintained if that information
2270    is to be provided to multiple clients, since servers may have access
2271    control policies which prevent the return of entries or attributes in
2272    search results except to particular authenticated clients.  For
2273    example, caches could serve result information only to the client
2274    whose request caused it to be cache.
2275
2276 8.  Acknowledgements
2277
2278    This document is an update to RFC 1777, by Wengyik Yeong, Tim Howes,
2279    and Steve Kille.  Design ideas included in this document are based on
2280    those discussed in ASID and other IETF Working Groups.  The
2281    contributions of individuals in these working groups is gratefully
2282    acknowledged.
2283
2284 9.  Bibliography
2285
2286    [1] ITU-T Rec. X.500, "The Directory: Overview of Concepts, Models
2287        and Service",  1993.
2288
2289    [2] Yeong, W., Howes, T., and S. Kille, "Lightweight Directory Access
2290        Protocol", RFC 1777, March 1995.
2291
2292    [3] ITU-T Rec. X.680, "Abstract Syntax Notation One (ASN.1) -
2293        Specification of Basic Notation", 1994.
2294
2295
2296
2297
2298 Wahl, et. al.               Standards Track                    [Page 41]
2299 \f
2300 RFC 2251                         LDAPv3                    December 1997
2301
2302
2303    [4] Kille, S., Wahl, M., and T. Howes, "Lightweight Directory Access
2304        Protocol (v3): UTF-8 String Representation of Distinguished
2305        Names", RFC 2253, December 1997.
2306
2307    [5] Wahl, M., Coulbeck, A., Howes, T., and S. Kille, "Lightweight
2308        Directory Access Protocol (v3): Attribute Syntax Definitions",
2309        RFC 2252, December 1997.
2310
2311    [6] ITU-T Rec. X.501, "The Directory: Models", 1993.
2312
2313    [7] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform
2314        Resource  Locators (URL)", RFC 1738, December 1994.
2315
2316    [8] ITU-T Rec. X.511, "The Directory: Abstract Service Definition",
2317        1993.
2318
2319    [9] Howes, T., and M. Smith, "The LDAP URL Format", RFC 2255,
2320        December 1997.
2321
2322    [10] Bradner, S., "Key words for use in RFCs to Indicate Requirement
2323         Levels", RFC 2119, March 1997.
2324
2325    [11] ITU-T Rec. X.690, "Specification of ASN.1 encoding rules: Basic,
2326         Canonical, and Distinguished Encoding Rules", 1994.
2327
2328    [12] Meyers, J., "Simple Authentication and Security Layer",
2329         RFC 2222, October 1997.
2330
2331    [13] Universal Multiple-Octet Coded Character Set (UCS) -
2332         Architecture and Basic Multilingual Plane, ISO/IEC 10646-1 :
2333         1993.
2334
2335    [14] Yergeau, F., "UTF-8, a transformation format of Unicode and ISO
2336         10646", RFC 2044, October 1996.
2337
2338 10. Authors' Addresses
2339
2340    Mark Wahl
2341    Critical Angle Inc.
2342    4815 W Braker Lane #502-385
2343    Austin, TX 78759
2344    USA
2345
2346    Phone:  +1 512 372-3160
2347    EMail:  M.Wahl@critical-angle.com
2348
2349
2350
2351
2352
2353
2354 Wahl, et. al.               Standards Track                    [Page 42]
2355 \f
2356 RFC 2251                         LDAPv3                    December 1997
2357
2358
2359    Tim Howes
2360    Netscape Communications Corp.
2361    501 E. Middlefield Rd., MS MV068
2362    Mountain View, CA 94043
2363    USA
2364
2365    Phone:  +1 650 937-3419
2366    EMail:   howes@netscape.com
2367
2368    Steve Kille
2369    Isode Limited
2370    The Dome, The Square
2371    Richmond
2372    TW9 1DT
2373    UK
2374
2375    Phone:  +44-181-332-9091
2376    EMail:  S.Kille@isode.com
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410 Wahl, et. al.               Standards Track                    [Page 43]
2411 \f
2412 RFC 2251                         LDAPv3                    December 1997
2413
2414
2415 Appendix A - Complete ASN.1 Definition
2416
2417         Lightweight-Directory-Access-Protocol-V3 DEFINITIONS
2418         IMPLICIT TAGS ::=
2419
2420         BEGIN
2421
2422         LDAPMessage ::= SEQUENCE {
2423                 messageID       MessageID,
2424                 protocolOp      CHOICE {
2425                         bindRequest     BindRequest,
2426                         bindResponse    BindResponse,
2427                         unbindRequest   UnbindRequest,
2428                         searchRequest   SearchRequest,
2429                         searchResEntry  SearchResultEntry,
2430                         searchResDone   SearchResultDone,
2431                         searchResRef    SearchResultReference,
2432                         modifyRequest   ModifyRequest,
2433                         modifyResponse  ModifyResponse,
2434                         addRequest      AddRequest,
2435                         addResponse     AddResponse,
2436                         delRequest      DelRequest,
2437                         delResponse     DelResponse,
2438                         modDNRequest    ModifyDNRequest,
2439                         modDNResponse   ModifyDNResponse,
2440                         compareRequest  CompareRequest,
2441                         compareResponse CompareResponse,
2442                         abandonRequest  AbandonRequest,
2443                         extendedReq     ExtendedRequest,
2444                         extendedResp    ExtendedResponse },
2445                  controls       [0] Controls OPTIONAL }
2446
2447         MessageID ::= INTEGER (0 .. maxInt)
2448
2449         maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
2450
2451         LDAPString ::= OCTET STRING
2452
2453         LDAPOID ::= OCTET STRING
2454
2455         LDAPDN ::= LDAPString
2456
2457         RelativeLDAPDN ::= LDAPString
2458
2459         AttributeType ::= LDAPString
2460
2461         AttributeDescription ::= LDAPString
2462
2463
2464
2465
2466 Wahl, et. al.               Standards Track                    [Page 44]
2467 \f
2468 RFC 2251                         LDAPv3                    December 1997
2469
2470
2471         AttributeDescriptionList ::= SEQUENCE OF
2472                 AttributeDescription
2473
2474         AttributeValue ::= OCTET STRING
2475
2476         AttributeValueAssertion ::= SEQUENCE {
2477                 attributeDesc   AttributeDescription,
2478                 assertionValue  AssertionValue }
2479
2480         AssertionValue ::= OCTET STRING
2481
2482         Attribute ::= SEQUENCE {
2483                 type    AttributeDescription,
2484                 vals    SET OF AttributeValue }
2485
2486         MatchingRuleId ::= LDAPString
2487
2488         LDAPResult ::= SEQUENCE {
2489                 resultCode      ENUMERATED {
2490                              success                      (0),
2491                              operationsError              (1),
2492                              protocolError                (2),
2493                              timeLimitExceeded            (3),
2494                              sizeLimitExceeded            (4),
2495                              compareFalse                 (5),
2496                              compareTrue                  (6),
2497                              authMethodNotSupported       (7),
2498                              strongAuthRequired           (8),
2499                                         -- 9 reserved --
2500                              referral                     (10),  -- new
2501                              adminLimitExceeded           (11),  -- new
2502                              unavailableCriticalExtension (12),  -- new
2503                              confidentialityRequired      (13),  -- new
2504                              saslBindInProgress           (14),  -- new
2505                              noSuchAttribute              (16),
2506                              undefinedAttributeType       (17),
2507                              inappropriateMatching        (18),
2508                              constraintViolation          (19),
2509                              attributeOrValueExists       (20),
2510                              invalidAttributeSyntax       (21),
2511                                         -- 22-31 unused --
2512                              noSuchObject                 (32),
2513                              aliasProblem                 (33),
2514                              invalidDNSyntax              (34),
2515                              -- 35 reserved for undefined isLeaf --
2516                              aliasDereferencingProblem    (36),
2517                                         -- 37-47 unused --
2518                              inappropriateAuthentication  (48),
2519
2520
2521
2522 Wahl, et. al.               Standards Track                    [Page 45]
2523 \f
2524 RFC 2251                         LDAPv3                    December 1997
2525
2526
2527                              invalidCredentials           (49),
2528                              insufficientAccessRights     (50),
2529                              busy                         (51),
2530                              unavailable                  (52),
2531                              unwillingToPerform           (53),
2532                              loopDetect                   (54),
2533                                         -- 55-63 unused --
2534                              namingViolation              (64),
2535                              objectClassViolation         (65),
2536                              notAllowedOnNonLeaf          (66),
2537                              notAllowedOnRDN              (67),
2538                              entryAlreadyExists           (68),
2539                              objectClassModsProhibited    (69),
2540                                         -- 70 reserved for CLDAP --
2541                              affectsMultipleDSAs          (71), -- new
2542                                         -- 72-79 unused --
2543                              other                        (80) },
2544                              -- 81-90 reserved for APIs --
2545                 matchedDN       LDAPDN,
2546                 errorMessage    LDAPString,
2547                 referral        [3] Referral OPTIONAL }
2548
2549         Referral ::= SEQUENCE OF LDAPURL
2550
2551         LDAPURL ::= LDAPString -- limited to characters permitted in URLs
2552
2553         Controls ::= SEQUENCE OF Control
2554
2555         Control ::= SEQUENCE {
2556                 controlType             LDAPOID,
2557                 criticality             BOOLEAN DEFAULT FALSE,
2558                 controlValue            OCTET STRING OPTIONAL }
2559
2560         BindRequest ::= [APPLICATION 0] SEQUENCE {
2561                 version                 INTEGER (1 .. 127),
2562                 name                    LDAPDN,
2563                 authentication          AuthenticationChoice }
2564
2565         AuthenticationChoice ::= CHOICE {
2566                 simple                  [0] OCTET STRING,
2567                                          -- 1 and 2 reserved
2568                 sasl                    [3] SaslCredentials }
2569
2570         SaslCredentials ::= SEQUENCE {
2571                 mechanism               LDAPString,
2572                 credentials             OCTET STRING OPTIONAL }
2573
2574         BindResponse ::= [APPLICATION 1] SEQUENCE {
2575
2576
2577
2578 Wahl, et. al.               Standards Track                    [Page 46]
2579 \f
2580 RFC 2251                         LDAPv3                    December 1997
2581
2582
2583              COMPONENTS OF LDAPResult,
2584              serverSaslCreds    [7] OCTET STRING OPTIONAL }
2585
2586         UnbindRequest ::= [APPLICATION 2] NULL
2587
2588         SearchRequest ::= [APPLICATION 3] SEQUENCE {
2589                 baseObject      LDAPDN,
2590                 scope           ENUMERATED {
2591                         baseObject              (0),
2592                         singleLevel             (1),
2593                         wholeSubtree            (2) },
2594                 derefAliases    ENUMERATED {
2595                         neverDerefAliases       (0),
2596                         derefInSearching        (1),
2597                         derefFindingBaseObj     (2),
2598                         derefAlways             (3) },
2599                 sizeLimit       INTEGER (0 .. maxInt),
2600                 timeLimit       INTEGER (0 .. maxInt),
2601                 typesOnly       BOOLEAN,
2602                 filter          Filter,
2603                 attributes      AttributeDescriptionList }
2604
2605         Filter ::= CHOICE {
2606                 and             [0] SET OF Filter,
2607                 or              [1] SET OF Filter,
2608                 not             [2] Filter,
2609                 equalityMatch   [3] AttributeValueAssertion,
2610                 substrings      [4] SubstringFilter,
2611                 greaterOrEqual  [5] AttributeValueAssertion,
2612                 lessOrEqual     [6] AttributeValueAssertion,
2613                 present         [7] AttributeDescription,
2614                 approxMatch     [8] AttributeValueAssertion,
2615                 extensibleMatch [9] MatchingRuleAssertion }
2616
2617         SubstringFilter ::= SEQUENCE {
2618                 type            AttributeDescription,
2619                 -- at least one must be present
2620                 substrings      SEQUENCE OF CHOICE {
2621                         initial [0] LDAPString,
2622                         any     [1] LDAPString,
2623                         final   [2] LDAPString } }
2624
2625         MatchingRuleAssertion ::= SEQUENCE {
2626                 matchingRule    [1] MatchingRuleId OPTIONAL,
2627                 type            [2] AttributeDescription OPTIONAL,
2628                 matchValue      [3] AssertionValue,
2629                 dnAttributes    [4] BOOLEAN DEFAULT FALSE }
2630
2631
2632
2633
2634 Wahl, et. al.               Standards Track                    [Page 47]
2635 \f
2636 RFC 2251                         LDAPv3                    December 1997
2637
2638
2639         SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
2640                 objectName      LDAPDN,
2641                 attributes      PartialAttributeList }
2642
2643         PartialAttributeList ::= SEQUENCE OF SEQUENCE {
2644                 type    AttributeDescription,
2645                 vals    SET OF AttributeValue }
2646
2647         SearchResultReference ::= [APPLICATION 19] SEQUENCE OF LDAPURL
2648
2649         SearchResultDone ::= [APPLICATION 5] LDAPResult
2650
2651         ModifyRequest ::= [APPLICATION 6] SEQUENCE {
2652                 object          LDAPDN,
2653                 modification    SEQUENCE OF SEQUENCE {
2654                         operation       ENUMERATED {
2655                                                 add     (0),
2656                                                 delete  (1),
2657                                                 replace (2) },
2658                         modification    AttributeTypeAndValues } }
2659
2660         AttributeTypeAndValues ::= SEQUENCE {
2661                 type    AttributeDescription,
2662                 vals    SET OF AttributeValue }
2663
2664         ModifyResponse ::= [APPLICATION 7] LDAPResult
2665
2666         AddRequest ::= [APPLICATION 8] SEQUENCE {
2667                 entry           LDAPDN,
2668                 attributes      AttributeList }
2669
2670         AttributeList ::= SEQUENCE OF SEQUENCE {
2671                 type    AttributeDescription,
2672                 vals    SET OF AttributeValue }
2673
2674         AddResponse ::= [APPLICATION 9] LDAPResult
2675
2676         DelRequest ::= [APPLICATION 10] LDAPDN
2677
2678         DelResponse ::= [APPLICATION 11] LDAPResult
2679
2680         ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
2681                 entry           LDAPDN,
2682                 newrdn          RelativeLDAPDN,
2683                 deleteoldrdn    BOOLEAN,
2684                 newSuperior     [0] LDAPDN OPTIONAL }
2685
2686         ModifyDNResponse ::= [APPLICATION 13] LDAPResult
2687
2688
2689
2690 Wahl, et. al.               Standards Track                    [Page 48]
2691 \f
2692 RFC 2251                         LDAPv3                    December 1997
2693
2694
2695         CompareRequest ::= [APPLICATION 14] SEQUENCE {
2696                 entry           LDAPDN,
2697                 ava             AttributeValueAssertion }
2698
2699         CompareResponse ::= [APPLICATION 15] LDAPResult
2700
2701         AbandonRequest ::= [APPLICATION 16] MessageID
2702
2703         ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
2704                 requestName      [0] LDAPOID,
2705                 requestValue     [1] OCTET STRING OPTIONAL }
2706
2707         ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
2708                 COMPONENTS OF LDAPResult,
2709                 responseName     [10] LDAPOID OPTIONAL,
2710                 response         [11] OCTET STRING OPTIONAL }
2711
2712         END
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746 Wahl, et. al.               Standards Track                    [Page 49]
2747 \f
2748 RFC 2251                         LDAPv3                    December 1997
2749
2750
2751 Full Copyright Statement
2752
2753    Copyright (C) The Internet Society (1997).  All Rights Reserved.
2754
2755    This document and translations of it may be copied and furnished to
2756    others, and derivative works that comment on or otherwise explain it
2757    or assist in its implementation may be prepared, copied, published
2758    and distributed, in whole or in part, without restriction of any
2759    kind, provided that the above copyright notice and this paragraph are
2760    included on all such copies and derivative works.  However, this
2761    document itself may not be modified in any way, such as by removing
2762    the copyright notice or references to the Internet Society or other
2763    Internet organizations, except as needed for the purpose of
2764    developing Internet standards in which case the procedures for
2765    copyrights defined in the Internet Standards process must be
2766    followed, or as required to translate it into languages other than
2767    English.
2768
2769    The limited permissions granted above are perpetual and will not be
2770    revoked by the Internet Society or its successors or assigns.
2771
2772    This document and the information contained herein is provided on an
2773    "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
2774    TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
2775    BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
2776    HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
2777    MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802 Wahl, et. al.               Standards Track                    [Page 50]
2803 \f