RFC 2251






Network Working Group                                            M. Wahl
Request for Comments: 2251                           Critical Angle Inc.
Category: Standards Track                                       T. Howes
                                           Netscape Communications Corp.
                                                                S. Kille
                                                           Isode Limited
                                                           December 1997


               Lightweight Directory Access Protocol (v3)

1. Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (1997).  All Rights Reserved.

IESG Note

   This document describes a directory access protocol that provides
   both read and update access.  Update access requires secure
   authentication, but this document does not mandate implementation of
   any satisfactory authentication mechanisms.

   In accordance with RFC 2026, section 4.4.1, this specification is
   being approved by IESG as a Proposed Standard despite this
   limitation, for the following reasons:

   a. to encourage implementation and interoperability testing of
      these protocols (with or without update access) before they
      are deployed, and

   b. to encourage deployment and use of these protocols in read-only
      applications.  (e.g. applications where LDAPv3 is used as
      a query language for directories which are updated by some
      secure mechanism other than LDAP), and

   c. to avoid delaying the advancement and deployment of other Internet
      standards-track protocols which require the ability to query, but
      not update, LDAPv3 directory servers.





Wahl, et. al.               Standards Track                     [Page 1]

RFC 2251                         LDAPv3                    December 1997


   Readers are hereby warned that until mandatory authentication
   mechanisms are standardized, clients and servers written according to
   this specification which make use of update functionality are
   UNLIKELY TO INTEROPERATE, or MAY INTEROPERATE ONLY IF AUTHENTICATION
   IS REDUCED TO AN UNACCEPTABLY WEAK LEVEL.

   Implementors are hereby discouraged from deploying LDAPv3 clients or
   servers which implement the update functionality, until a Proposed
   Standard for mandatory authentication in LDAPv3 has been approved and
   published as an RFC.

Table of Contents

   1.  Status of this Memo ....................................  1
       Copyright Notice .......................................  1
       IESG Note ..............................................  1
   2.  Abstract ...............................................  3
   3.  Models .................................................  4
   3.1. Protocol Model ........................................  4
   3.2. Data Model ............................................  5
   3.2.1. Attributes of Entries ...............................  5
   3.2.2. Subschema Entries and Subentries ....................  7
   3.3. Relationship to X.500 .................................  8
   3.4. Server-specific Data Requirements .....................  8
   4.  Elements of Protocol ...................................  9
   4.1. Common Elements .......................................  9
   4.1.1. Message Envelope ....................................  9
   4.1.1.1. Message ID ........................................ 11
   4.1.2. String Types ........................................ 11
   4.1.3. Distinguished Name and Relative Distinguished Name .. 11
   4.1.4. Attribute Type ...................................... 12
   4.1.5. Attribute Description ............................... 13
   4.1.5.1. Binary Option ..................................... 14
   4.1.6. Attribute Value ..................................... 14
   4.1.7. Attribute Value Assertion ........................... 15
   4.1.8. Attribute ........................................... 15
   4.1.9. Matching Rule Identifier ............................ 15
   4.1.10. Result Message ..................................... 16
   4.1.11. Referral ........................................... 18
   4.1.12. Controls ........................................... 19
   4.2. Bind Operation ........................................ 20
   4.2.1. Sequencing of the Bind Request ...................... 21
   4.2.2. Authentication and Other Security Services .......... 22
   4.2.3. Bind Response ....................................... 23
   4.3. Unbind Operation ...................................... 24
   4.4. Unsolicited Notification .............................. 24
   4.4.1. Notice of Disconnection ............................. 24
   4.5. Search Operation ...................................... 25



Wahl, et. al.               Standards Track                     [Page 2]

RFC 2251                         LDAPv3                    December 1997


   4.5.1. Search Request ...................................... 25
   4.5.2. Search Result ....................................... 29
   4.5.3. Continuation References in the Search Result ........ 31
   4.5.3.1. Example ........................................... 31
   4.6. Modify Operation ...................................... 32
   4.7. Add Operation ......................................... 34
   4.8. Delete Operation ...................................... 35
   4.9. Modify DN Operation ................................... 36
   4.10. Compare Operation .................................... 37
   4.11. Abandon Operation .................................... 38
   4.12. Extended Operation ................................... 38
   5.  Protocol Element Encodings and Transfer ................ 39
   5.1. Mapping Onto BER-based Transport Services ............. 39
   5.2. Transfer Protocols .................................... 40
   5.2.1. Transmission Control Protocol (TCP) ................. 40
   6.  Implementation Guidelines .............................. 40
   6.1. Server Implementations ................................ 40
   6.2. Client Implementations ................................ 40
   7.  Security Considerations ................................ 41
   8.  Acknowledgements ....................................... 41
   9.  Bibliography ........................................... 41
   10. Authors' Addresses ..................................... 42
   Appendix A - Complete ASN.1 Definition ..................... 44
   Full Copyright Statement ................................... 50

2.  Abstract

   The protocol described in this document is designed to provide access
   to directories supporting the X.500 models, while not incurring the
   resource requirements of the X.500 Directory Access Protocol (DAP).
   This protocol is specifically targeted at management applications and
   browser applications that provide read/write interactive access to
   directories. When used with a directory supporting the X.500
   protocols, it is intended to be a complement to the X.500 DAP.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED",  and "MAY" in this document
   are to be interpreted as described in RFC 2119 [10].

   Key aspects of this version of LDAP are:

   - All protocol elements of LDAPv2 (RFC 1777) are supported. The
     protocol is carried directly over TCP or other transport, bypassing
     much of the session/presentation overhead of X.500 DAP.

   - Most protocol data elements can be encoded as ordinary strings
     (e.g., Distinguished Names).




Wahl, et. al.               Standards Track                     [Page 3]

RFC 2251                         LDAPv3                    December 1997


   - Referrals to other servers may be returned.

   - SASL mechanisms may be used with LDAP to provide association
     security services.

   - Attribute values and Distinguished Names have been
     internationalized through the use of the ISO 10646 character set.

   - The protocol can be extended to support new operations, and
     controls may be used to extend existing operations.

   - Schema is published in the directory for use by clients.

3.  Models

   Interest in X.500 [1] directory technologies in the Internet has led
   to efforts to reduce the high cost of entry associated with use of
   these technologies.  This document continues the efforts to define
   directory protocol alternatives, updating the LDAP [2] protocol
   specification.

3.1. Protocol Model

   The general model adopted by this protocol is one of clients
   performing protocol operations against servers. In this model, a
   client transmits a protocol request describing the operation to be
   performed to a server. The server is then responsible for performing
   the necessary operation(s) in the directory. Upon completion of the
   operation(s), the server returns a response containing any results or
   errors to the requesting client.

   In keeping with the goal of easing the costs associated with use of
   the directory, it is an objective of this protocol to minimize the
   complexity of clients so as to facilitate widespread deployment of
   applications capable of using the directory.

   Note that although servers are required to return responses whenever
   such responses are defined in the protocol, there is no requirement
   for synchronous behavior on the part of either clients or servers.
   Requests and responses for multiple operations may be exchanged
   between a client and server in any order, provided the client
   eventually receives a response for every request that requires one.

   In LDAP versions 1 and 2, no provision was made for protocol servers
   returning referrals to clients.  However, for improved performance
   and distribution this version of the protocol permits servers to
   return to clients referrals to other servers.  This allows servers to
   offload the work of contacting other servers to progress operations.



Wahl, et. al.               Standards Track                     [Page 4]

RFC 2251                         LDAPv3                    December 1997


   Note that the core protocol operations defined in this document can
   be mapped to a strict subset of the X.500(1997) directory abstract
   service, so it can be cleanly provided by the DAP.  However there is
   not a one-to-one mapping between LDAP protocol operations and DAP
   operations: server implementations acting as a gateway to X.500
   directories may need to make multiple DAP requests.

3.2. Data Model

   This section provides a brief introduction to the X.500 data model,
   as used by LDAP.

   The LDAP protocol assumes there are one or more servers which jointly
   provide access to a Directory Information Tree (DIT).  The tree is
   made up of entries.  Entries have names: one or more attribute values
   from the entry form its relative distinguished name (RDN), which MUST
   be unique among all its siblings.  The concatenation of the relative
   distinguished names of the sequence of entries from a particular
   entry to an immediate subordinate of the root of the tree forms that
   entry's Distinguished Name (DN), which is unique in the tree.  An
   example of a Distinguished Name is

   CN=Steve Kille, O=Isode Limited, C=GB

   Some servers may hold cache or shadow copies of entries, which can be
   used to answer search and comparison queries, but will return
   referrals or contact other servers if modification operations are
   requested.

   Servers which perform caching or shadowing MUST ensure that they do
   not violate any access control constraints placed on the data by the
   originating server.

   The largest collection of entries, starting at an entry that is
   mastered by a particular server, and including all its subordinates
   and their subordinates, down to the entries which are mastered by
   different servers, is termed a naming context.  The root of the DIT
   is a DSA-specific Entry (DSE) and not part of any naming context:
   each server has different attribute values in the root DSE.  (DSA is
   an X.500 term for the directory server).

3.2.1. Attributes of Entries

   Entries consist of a set of attributes.  An attribute is a type with
   one or more associated values.  The attribute type is identified by a
   short descriptive name and an OID (object identifier). The attribute





Wahl, et. al.               Standards Track                     [Page 5]

RFC 2251                         LDAPv3                    December 1997


   type governs whether there can be more than one value of an attribute
   of that type in an entry, the syntax to which the values must
   conform, the kinds of matching which can be performed on values of
   that attribute, and other functions.

   An example of an attribute is "mail". There may be one or more values
   of this attribute, they must be IA5 (ASCII) strings, and they are
   case insensitive (e.g. "foo@bar.com" will match "FOO@BAR.COM").

   Schema is the collection of attribute type definitions, object class
   definitions and other information which a server uses to determine
   how to match a filter or attribute value assertion (in a compare
   operation) against the attributes of an entry, and whether to permit
   add and modify operations.  The definition of schema for use with
   LDAP is given in [5] and [6].  Additional schema elements may be
   defined in other documents.

   Each entry MUST have an objectClass attribute.  The objectClass
   attribute specifies the object classes of an entry, which along with
   the system and user schema determine the permitted attributes of an
   entry.  Values of this attribute may be modified by clients, but the
   objectClass attribute cannot be removed.  Servers may restrict the
   modifications of this attribute to prevent the basic structural class
   of the entry from being changed (e.g. one cannot change a person into
   a country).  When creating an entry or adding an objectClass value to
   an entry, all superclasses of the named classes are implicitly added
   as well if not already present, and the client must supply values for
   any mandatory attributes of new superclasses.

   Some attributes, termed operational attributes, are used by servers
   for administering the directory system itself.  They are not returned
   in search results unless explicitly requested by name.  Attributes
   which are not operational, such as "mail", will have their schema and
   syntax constraints enforced by servers, but servers will generally
   not make use of their values.

   Servers MUST NOT permit clients to add attributes to an entry unless
   those attributes are permitted by the object class definitions, the
   schema controlling that entry (specified in the subschema - see
   below), or are operational attributes known to that server and used
   for administrative purposes.  Note that there is a particular
   objectClass 'extensibleObject' defined in [5] which permits all user
   attributes to be present in an entry.

   Entries MAY contain, among others, the following operational
   attributes, defined in [5]. These attributes are maintained
   automatically by the server and are not modifiable by clients:




Wahl, et. al.               Standards Track                     [Page 6]

RFC 2251                         LDAPv3                    December 1997


   - creatorsName: the Distinguished Name of the user who added this
     entry to the directory.

   - createTimestamp: the time this entry was added to the directory.

   - modifiersName: the Distinguished Name of the user who last modified
     this entry.

   - modifyTimestamp: the time this entry was last modified.

   - subschemaSubentry:  the Distinguished Name of the subschema entry
     (or subentry) which controls the schema for this entry.

3.2.2. Subschema Entries and Subentries

   Subschema entries are used for administering information about the
   directory schema, in particular the object classes and attribute
   types supported by directory servers.  A single subschema entry
   contains all schema definitions used by entries in a particular part
   of the directory tree.

   Servers which follow X.500(93) models SHOULD implement subschema
   using the X.500 subschema mechanisms, and so these subschemas are not
   ordinary entries.  LDAP clients SHOULD NOT assume that servers
   implement any of the other aspects of X.500 subschema.  A server
   which masters entries and permits clients to modify these entries
   MUST implement and provide access to these subschema entries, so that
   its clients may discover the attributes and object classes which are
   permitted to be present. It is strongly recommended that all other
   servers implement this as well.

   The following four attributes MUST be present in all subschema
   entries:

   - cn: this attribute MUST be used to form the RDN of the subschema
     entry.

   - objectClass: the attribute MUST have at least the values "top" and
     "subschema".

   - objectClasses: each value of this attribute specifies an object
     class known to the server.

   - attributeTypes: each value of this attribute specifies an attribute
     type known to the server.

   These are defined in [5]. Other attributes MAY be present in
   subschema entries, to reflect additional supported capabilities.



Wahl, et. al.               Standards Track                     [Page 7]

RFC 2251                         LDAPv3                    December 1997


   These include matchingRules, matchingRuleUse, dITStructureRules,
   dITContentRules, nameForms and ldapSyntaxes.

   Servers SHOULD provide the attributes createTimestamp and
   modifyTimestamp in subschema entries, in order to allow clients to
   maintain their caches of schema information.

   Clients MUST only retrieve attributes from a subschema entry by
   requesting a base object search of the entry, where the search filter
   is "(objectClass=subschema)". (This will allow LDAPv3 servers which
   gateway to X.500(93) to detect that subentry information is being
   requested.)

3.3. Relationship to X.500

   This document defines LDAP in terms of X.500 as an X.500 access
   mechanism.  An LDAP server MUST act in accordance with the
   X.500(1993) series of ITU recommendations when providing the service.
   However, it is not required that an LDAP server make use of any X.500
   protocols in providing this service, e.g. LDAP can be mapped onto any
   other directory system so long as the X.500 data and service model as
   used in LDAP is not violated in the LDAP interface.

3.4. Server-specific Data Requirements

   An LDAP server MUST provide information about itself and other
   information that is specific to each server.  This is represented as
   a group of attributes located in the root DSE (DSA-Specific Entry),
   which is named with the zero-length LDAPDN.  These attributes are
   retrievable if a client performs a base object search of the root
   with filter "(objectClass=*)", however they are subject to access
   control restrictions.  The root DSE MUST NOT be included if the
   client performs a subtree search starting from the root.

   Servers may allow clients to modify these attributes.

   The following attributes of the root DSE are defined in section 5 of
   [5].  Additional attributes may be defined in other documents.

   - namingContexts: naming contexts held in the server. Naming contexts
     are defined in section 17 of X.501 [6].

   - subschemaSubentry: subschema entries (or subentries) known by this
     server.

   - altServer: alternative servers in case this one is later
     unavailable.




Wahl, et. al.               Standards Track                     [Page 8]

RFC 2251                         LDAPv3                    December 1997


   - supportedExtension: list of supported extended operations.

   - supportedControl: list of supported controls.

   - supportedSASLMechanisms: list of supported SASL security features.

   - supportedLDAPVersion: LDAP versions implemented by the server.

   If the server does not master entries and does not know the locations
   of schema information, the subschemaSubentry attribute is not present
   in the root DSE.  If the server masters directory entries under one
   or more schema rules, there may be any number of values of the
   subschemaSubentry attribute in the root DSE.

4.  Elements of Protocol

   The LDAP protocol is described using Abstract Syntax Notation 1
   (ASN.1) [3], and is typically transferred using a subset of ASN.1
   Basic Encoding Rules [11]. In order to support future extensions to
   this protocol, clients and servers MUST ignore elements of SEQUENCE
   encodings whose tags they do not recognize.

   Note that unlike X.500, each change to the LDAP protocol other than
   through the extension mechanisms will have a different version
   number.  A client will indicate the version it supports as part of
   the bind request, described in section 4.2.  If a client has not sent
   a bind, the server MUST assume that version 3 is supported in the
   client (since version 2 required that the client bind first).

   Clients may determine the protocol version a server supports by
   reading the supportedLDAPVersion attribute from the root DSE. Servers
   which implement version 3 or later versions MUST provide this
   attribute.  Servers which only implement version 2 may not provide
   this attribute.

4.1. Common Elements

   This section describes the LDAPMessage envelope PDU (Protocol Data
   Unit) format, as well as data type definitions which are used in the
   protocol operations.

4.1.1. Message Envelope

   For the purposes of protocol exchanges, all protocol operations are
   encapsulated in a common envelope, the LDAPMessage, which is defined
   as follows:

        LDAPMessage ::= SEQUENCE {



Wahl, et. al.               Standards Track                     [Page 9]

RFC 2251                         LDAPv3                    December 1997


                messageID       MessageID,
                protocolOp      CHOICE {
                        bindRequest     BindRequest,
                        bindResponse    BindResponse,
                        unbindRequest   UnbindRequest,
                        searchRequest   SearchRequest,
                        searchResEntry  SearchResultEntry,
                        searchResDone   SearchResultDone,
                        searchResRef    SearchResultReference,
                        modifyRequest   ModifyRequest,
                        modifyResponse  ModifyResponse,
                        addRequest      AddRequest,
                        addResponse     AddResponse,
                        delRequest      DelRequest,
                        delResponse     DelResponse,
                        modDNRequest    ModifyDNRequest,
                        modDNResponse   ModifyDNResponse,
                        compareRequest  CompareRequest,
                        compareResponse CompareResponse,
                        abandonRequest  AbandonRequest,
                        extendedReq     ExtendedRequest,
                        extendedResp    ExtendedResponse },
                 controls       [0] Controls OPTIONAL }

        MessageID ::= INTEGER (0 .. maxInt)

        maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --

   The function of the LDAPMessage is to provide an envelope containing
   common fields required in all protocol exchanges. At this time the
   only common fields are the message ID and the controls.

   If the server receives a PDU from the client in which the LDAPMessage
   SEQUENCE tag cannot be recognized, the messageID cannot be parsed,
   the tag of the protocolOp is not recognized as a request, or the
   encoding structures or lengths of data fields are found to be
   incorrect, then the server MUST return the notice of disconnection
   described in section 4.4.1, with resultCode protocolError, and
   immediately close the connection. In other cases that the server
   cannot parse the request received by the client, the server MUST
   return an appropriate response to the request, with the resultCode
   set to protocolError.

   If the client receives a PDU from the server which cannot be parsed,
   the client may discard the PDU, or may abruptly close the connection.

   The ASN.1 type Controls is defined in section 4.1.12.




Wahl, et. al.               Standards Track                    [Page 10]

RFC 2251                         LDAPv3                    December 1997


4.1.1.1. Message ID

   All LDAPMessage envelopes encapsulating responses contain the
   messageID value of the corresponding request LDAPMessage.

   The message ID of a request MUST have a value different from the
   values of any other requests outstanding in the LDAP session of which
   this message is a part.

   A client MUST NOT send a second request with the same message ID as
   an earlier request on the same connection if the client has not
   received the final response from the earlier request.  Otherwise the
   behavior is undefined.  Typical clients increment a counter for each
   request.

   A client MUST NOT reuse the message id of an abandonRequest or of the
   abandoned operation until it has received a response from the server
   for another request invoked subsequent to the abandonRequest, as the
   abandonRequest itself does not have a response.

4.1.2. String Types

   The LDAPString is a notational convenience to indicate that, although
   strings of LDAPString type encode as OCTET STRING types, the ISO
   10646 [13] character set (a superset of Unicode) is used, encoded
   following the UTF-8 algorithm [14]. Note that in the UTF-8 algorithm
   characters which are the same as ASCII (0x0000 through 0x007F) are
   represented as that same ASCII character in a single byte.  The other
   byte values are used to form a variable-length encoding of an
   arbitrary character.

        LDAPString ::= OCTET STRING

   The LDAPOID is a notational convenience to indicate that the
   permitted value of this string is a (UTF-8 encoded) dotted-decimal
   representation of an OBJECT IDENTIFIER.

        LDAPOID ::= OCTET STRING

   For example,

        1.3.6.1.4.1.1466.1.2.3

4.1.3. Distinguished Name and Relative Distinguished Name

   An LDAPDN and a RelativeLDAPDN are respectively defined to be the
   representation of a Distinguished Name and a Relative Distinguished
   Name after encoding according to the specification in [4], such that



Wahl, et. al.               Standards Track                    [Page 11]

RFC 2251                         LDAPv3                    December 1997


         ::= 

         ::= 

   where  and  are as defined in [4].

        LDAPDN ::= LDAPString

        RelativeLDAPDN ::= LDAPString

   Only Attribute Types can be present in a relative distinguished name
   component; the options of Attribute Descriptions (next section) MUST
   NOT be used in specifying distinguished names.

4.1.4. Attribute Type

   An AttributeType takes on as its value the textual string associated
   with that AttributeType in its specification.

        AttributeType ::= LDAPString

   Each attribute type has a unique OBJECT IDENTIFIER which has been
   assigned to it.  This identifier may be written as decimal digits
   with components separated by periods, e.g. "2.5.4.10".

   A specification may also assign one or more textual names for an
   attribute type.  These names MUST begin with a letter, and only
   contain ASCII letters, digit characters and hyphens.  They are case
   insensitive.  (These ASCII characters are identical to ISO 10646
   characters whose UTF-8 encoding is a single byte between 0x00 and
   0x7F.)

   If the server has a textual name for an attribute type, it MUST use a
   textual name for attributes returned in search results.  The dotted-
   decimal OBJECT IDENTIFIER is only used if there is no textual name
   for an attribute type.

   Attribute type textual names are non-unique, as two different
   specifications (neither in standards track RFCs) may choose the same
   name.

   A server which masters or shadows entries SHOULD list all the
   attribute types it supports in the subschema entries, using the
   attributeTypes attribute.  Servers which support an open-ended set of
   attributes SHOULD include at least the attributeTypes value for the
   'objectClass' attribute. Clients MAY retrieve the attributeTypes
   value from subschema entries in order to obtain the OBJECT IDENTIFIER
   and other information associated with attribute types.



Wahl, et. al.               Standards Track                    [Page 12]

RFC 2251                         LDAPv3                    December 1997


   Some attribute type names which are used in this version of LDAP are
   described in [5].  Servers may implement additional attribute types.

4.1.5. Attribute Description

   An AttributeDescription is a superset of the definition of the
   AttributeType.  It has the same ASN.1 definition, but allows
   additional options to be specified.  They are also case insensitive.

        AttributeDescription ::= LDAPString

   A value of AttributeDescription is based on the following BNF:

         ::=  [ ";"  ]

          ::=