Network Working Group M. Wahl INTERNET-DRAFT Critical Angle Inc. Replaces: RFC 1777, RFC 1798 T. Howes Netscape Communications Corp. S. Kille ISODE Consortium Expires in six months from 22 October 1996 Intended Category: Standards Track Lightweight Directory Access Protocol (v3) Table of Contents - see end of document. 1. Status of this Memo This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." To learn the current status of any Internet-Draft, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). 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. Key aspects of this version of LDAP are: - All protocol elements of LDAP (RFC 1777) and CLDAP (RFC 1798) are supported. - Protocol elements are carried directly over TCP or other transport, bypassing much of the session/presentation overhead. Connectionless transport (UDP) is also supported for efficient lookup operations. - Most protocol data elements can be encoded as ordinary strings (e.g., Distinguished Names). Wahl, Howes & Kille [Page 1] INTERNET-DRAFT Lightweight Directory Access Protocol (v3) October 1996 - New features have been added, such as the abilities to retrieve attribute values in binary or search results in pages. - Important features of X.500(1993) and X.500(1997) are included. - Referrals to other servers can be returned. - The protocol can be extended to support bilaterally-defined operations. - Several session controls may be requested by the client. 3. Models Interest in X.500 [1] directory technologies in the Internet has lead 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: it updates the LDAP [2] protocol specification, adding support for new features, including some support for connecting to X.500 services that implement the 1993 or 1997 edition protocols. 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, which 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 utilizing 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 if requested. This allows servers, if requested by clients, to offload the work of contacting other servers to progress operations. Clients may also request that no referrals be returned, in which case the server must ensure that the operation is performed against the directory, or else return an error. This is the default. Wahl, Howes & Kille [Page 2] INTERNET-DRAFT Lightweight Directory Access Protocol (v3) October 1996 Note that this protocol 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 to perform extended operations. 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 values from the entry itself form its relative distinguished name (RDN), which must be unique among all its siblings. The concatenation of the relative distinguished names of the line 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 Consortium, 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. The largest collection of entries, starting an entry that is mastered by a particular server, and all its subordinates and their subordinates, down to an entry which is mastered by a different server, is termed a naming context. For example, in the following sample DIT, one server might master only the entry C=GB, and another server master both the entries O=Foo,C=US and O=Bar,C=US. Each of these entries are in a separate naming context. The root of the DIT is not an entry and not part of any naming context. (ROOT) | C=GB /------------/ \--------------\ O=Foo O=Bar 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, identified by a short descriptive name and an OID (object identifier), governs the maximum number of values permissible for an attribute of that type in an entry, the syntax to which the values must conform, the types of matching which can be performed on values of that attribute, and other functions. Wahl, Howes & Kille [Page 3] INTERNET-DRAFT Lightweight Directory Access Protocol (v3) October 1996 An example of an attribute is "mail". There may be one or more values of this attribute, they must be IA5 strings, and they are case insensitive (e.g. "foo@bar.com" will match "FOO@BAR.COM"). 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). A small number of attributes, termed operational attributes, are used by servers for administering the directory system itself. They are not returned in search results unless they were 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 subentry - 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 contain, among others, the following operational attributes, defined in [5]. These attributes are maintained automatically by the server are not modifiable by clients: - 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 subentry which controls the schema for this entry. - entryName: the Distinguished Name of the entry. Servers may implement other operational attributes. Servers which also make use of X.500(1993) protocols will provide support for more of the attributes defined in X.501, including administrativeRole and dseType. Some servers may permit the retrieval of subschema attributes directly from user entries. 3.2.2 Subschema Subentry A subentry is a special kind of entry which is used by servers and holds attributes for administering the directory system. Subentries are defined in clause 11.6 of X.501 [6]. Subschema subentries are used for administering information about the directory schema, in particular the object classes and attribute types supported by directory servers. Wahl, Howes & Kille [Page 4] INTERNET-DRAFT Lightweight Directory Access Protocol (v3) October 1996 A server may provide access to one or more subschema subentries to permit clients to interrogate the schema which is in force for entries in the directory. A server which masters entries and permits clients to modify these entries must implement and provide access to these subschema subentries, 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 subschema subentries as well. The following four attributes, defined in [6] with string representations in [5], must be present in all subschema subentries: - CN: this attribute must be used to form the RDN of the subschema subentry. - 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. Other operational attributes may be present in subschema subentries, in particular dseType, subtreeSpecification, ditStructureRules, nameForms, ditContentRules, matchingRules, matchingRuleUse, createTimestamp, creatorsName, modifyTimestamp, modifiersName, entryName, as described in [6]. Clients must only retrieve these attributes from a subentry by requesting them by name in a baseObject search of the subentry. 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 number 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, however they are subject to access control restrictions. They must not be included if the client performs a subtree search starting from the root. Servers in general will not allow clients to modify these attributes. Wahl, Howes & Kille [Page 5] INTERNET-DRAFT Lightweight Directory Access Protocol (v3) October 1996 The following attributes of the root DSE are defined in section 5.1.3 of [5]. Additional attributes may be defined in later documents. - administratorAddress: a URL containing address of administrator. - currentTime: the current time. - serverName: the Distinguished Name of the server. - certificationPath: the server's certificate path. - namingContexts: naming contexts held in the server. - subschemaSubentry: subschema subentries known by this server. - altServer: alternative servers in case this one is later unavailable. - supportedExtension: list of supported extended operations. - supportedControl: list of supported session controls. If the server does not master or shadow entries and does not know the locations of schema information, the subschemaSubentry attribute must not be present in the root DSE. If the server holds master or shadow copies of 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 [3]. It is typically transferred using a subset of the Basic Encoding Rules. In order to support future extensions to this protocol, clients and servers must ignore elements of SEQUENCEs 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.1.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). 4.1. Common Elements This section describes the LDAPMessage envelope PDU 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: Wahl, Howes & Kille [Page 6] INTERNET-DRAFT Lightweight Directory Access Protocol (v3) October 1996 LDAPMessage ::= SEQUENCE { messageID MessageID, cldapUserName LDAPDN OPTIONAL, protocolOp CHOICE { bindRequest BindRequest, bindResponse BindResponse, unbindRequest UnbindRequest, searchRequest SearchRequest, searchResEntry SearchResultEntry, searchResDone SearchResultDone, searchResRef SearchResultReference, searchResFull SearchResultFull, modifyRequest ModifyRequest, modifyResponse ModifyResponse, addRequest AddRequest, addResponse AddResponse, delRequest DelRequest, delResponse DelResponse, modDNRequest ModifyDNRequest, modDNResponse ModifyDNResponse, compareRequest CompareRequest, compareResponse CompareResponse, abandonRequest AbandonRequest, sessionRequest SessionRequest, sessionResponse SessionResponse, extendedReq ExtendedRequest, extendedResp ExtendedResponse } } 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 cldapUserName. All LDAPMessage envelopes encapsulating responses contain the messageID value of the request LDAPMessage. The message ID is required to 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 another request if the first request is outstanding. If it does so, the behavior is undefined. Typically a client will increment a counter for each request. For all requests except for search, unbind and abandon, the message ID is outstanding until the client receives the response for that operation. For a searchRequest which has not been abandoned, the message ID is outstanding until the SearchResultDone for that search is received. Wahl, Howes & Kille [Page 7] INTERNET-DRAFT Lightweight Directory Access Protocol (v3) October 1996 A client must not reuse the message id of an abandonRequest or 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. The cldapUserName identifies the requesting user for this message. It is only present for backwards compatibility with RFC 1798, if this LDAPMessage is carried in a connectionless transport protocol, such as UDP. Its significance is equivalent to a bind with a zero-length password. When the LDAP session is carried in a connection-oriented transport protocol this field must be absent. LDAPv3 client implementors must not use this field in connectionless requests, but instead concatenate a bind request with the other operations in the request. Concatenation and connectionless transport are described in section 5.1.3. 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 [15] character set (a superset of Unicode) is used, encoded following the UTF-8 algorithm [16]. Note that in the UTF-8 algorithm, characters which are the same as ASCII (0000 through 007F) 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 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 ::= ::= 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. Wahl, Howes & Kille [Page 8] INTERNET-DRAFT Lightweight Directory Access Protocol (v3) October 1996 4.1.4. Attribute Type and Description An AttributeType takes on as its value the textual string associated with that AttributeType in its specification. This string must begin with a letter, and only contain ASCII letters and digit characters. If this string is not known, the AttributeType will take the ASCII representation of its OBJECT IDENTIFIER, as decimal digits with components separated by periods, e.g., "2.5.4.10". The attribute type strings which are used in this version of LDAP are described in [5]. They are case insensitive. AttributeType ::= LDAPString 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: ::= [ ";" ] ::=