INTERNET-DRAFT Kurt D. Zeilenga Intended Category: Standard Track OpenLDAP Foundation Expires: 4 January 2001 4 July 2000 LDAPv3bis Suggestions: Lightweight Directory Access Protocol (v3) Status of Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. This document is intended to be, after appropriate review and revision, submitted to the RFC Editor as a Standard Track document. Distribution of this memo is unlimited. Technical discussion of this document will take place on the IETF LDAP Extension Working Group mailing list . Please send editorial comments directly to the author . 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.'' The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Copyright 2000, The Internet Society. All Rights Reserved. Please see the Copyright section near the end of this document for more information. Forward This Internet Draft suggests a number of updates to "Lightweight Directory Access Protocol (v3)" [RFC2251]. This document is not intended to be published as an RFC but used to identify LDAPv3bis work items. The remainer of this documents incorporates the substantive portion of RFC 2251 text (less status of memo, appendices, etc). Comments and Zeilenga [Page 1] INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2251-00 4 July 2000 suggested updates to this text are inserted as inline notes prefixed with '//'. // Start RFC-2251 text 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. // Note that LDAPv3 and LDAPv2 are cannot generally coexist // in the real world due to inconsistent implementation of // LDAPv2 (in particular, character set requirements). - Most protocol data elements can be encoded as ordinary strings (e.g., Distinguished Names). - Referrals to other servers may be returned. // s/servers/directory servers or services/ - 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 Zeilenga [Page 2] INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2251-00 4 July 2000 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. // note that this offloading is increases the complexity of clients 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. Zeilenga [Page 3] INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2251-00 4 July 2000 // This section could be moved to a separate document which more // fully described the data model used by LDAP as well as pointing // out differences between the LDAP and X.500 data models. 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 // suggest using DC naming to promote DNS based service location // uid=jdoe, dc=Example, dc=COM // as no global infrastructure exists to support geopolitical naming 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. // a non-empty set ... 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). // Attributes can have multiple names: Zeilenga [Page 4] INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2251-00 4 July 2000 // s/a short descriptive name/short descriptive names/ // These names are not globally unique. Suggest replace with: // The attribute is identified by an OID (object identifier) but // usually referred to by one of the attributes types short // descriptive names. The attribute 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"). // s/bar.com/example.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. // system and user? // Suggest s/system and user schema/the controlling/ 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. // Does this require the server to modify the value of // objectClass to include superclasses such that when // entry is later returned with complete list? Some attributes, termed operational attributes, are used by servers for administering the directory system itself. They are not returned Zeilenga [Page 5] INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2251-00 4 July 2000 in search results unless explicitly requested by name. Attributes // s/requested by name/requested/ // per zeilenga-ldapv3bis-opattrs I-D 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. // The clause "will have their schema and syntax constraints // enforced by servers" in this sentence, it implies that // operational attributes don't have to conform to schema // and syntax constraints. Suggest the clause be // from this sentence and an additional sentence be added: // "The server shall enforce schema and syntax constraints // upon all attribute types." 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. // s/permits all user attributes/permits all defined user attributes/ 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: - 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 Zeilenga [Page 6] INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2251-00 4 July 2000 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. // Are not all servers are required to implemented X.500(93) // models per 3.3? LDAP clients SHOULD NOT assume that servers implement any of the other aspects of X.500 subschema. // Which aspects of the X.500 subschema may clients assume servers // implement? 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 above should be reworded such that all servers SHOULD publish // subschema for readable entries and MUST publish subschema for // all entries which may be updated. // Insert formal specification for objectclass subschema here or // in related RFC. // Address differences between objectclass subentry and // LDAPSubentry. Address entry (or subentry) issues. 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. // s/MUST/SHOULD/ to allow servers to avoid naming conflicts - 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 Zeilenga [Page 7] INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2251-00 4 July 2000 type known to the server. These are defined in [5]. Other attributes MAY be present in subschema entries, to reflect additional supported capabilities. 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.) // Additional information should be added clarifying how to // locate the subschema subentry controlling an existing entry: // by examining the subschemaSubentry attribute of the entry // locate the subschema subentry which would control an // newly added entry // by examining the subschemaSubentry attribute of the entry // at the root of the naming context. // Additionally, // no mechanism is obtaining necessary subschema for // creating the entry at the root of a naming context. // (chicken and egg problem) // Additionally, a client MUST NOT assume the subschemaSubentry // value applies to any entry other than the Root DSE itself. // See notes regarding Root DSE subschemaSubentry below. 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. // s/MUST/SHOULD/ // // a) The above requirement is ambiguous (all X.500 rec.?) // b) The above requirement is too limiting (disallows servers // from using X.500(1997) recommendations) // c) The above requirement is not necessary to ensure // interoperability between protocol peers (per RFC 2119). // d) This MUST takes precedence over any SHOULD or MAY in Zeilenga [Page 8] INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2251-00 4 July 2000 // this or other LDAPv3 specification. 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. // This paragraph appears to allow variance in contraction to // the above MUST. Suggest this section be reworded to allow // this protocol to be used with a wide range of directory // systems as long as the LDAP interface is not violated. 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=*)", // which objectclass(es) are present? if no objectclass, // then client should use an filter which always evaluates // to true. 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. // Many of attributes contained within the root DSE are // operational and hence only returned if requested. // // Servers SHOULD support compare operations upon attributes // of the root DSE. 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]. // naming contexts were defined above in 3.2. - subschemaSubentry: subschema entries (or subentries) known by this server. Zeilenga [Page 9] INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2251-00 4 July 2000 // To allow publication of location of subschema entry controlling // root DSE itself and to conform to attribute type's syntax // (single valued) replace above with: // - subschemaSubentry: subschema entry (or subentry) controlling // the root DSE. // See note above regarding locating controlling subschema - altServer: alternative servers in case this one is later unavailable. - supportedExtension: list of supported extended operations. - supportedControl: list of supported controls. - supportedSASLMechanisms: list of supported SASL security features. // s/security features/mechanisms/ - 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. // This paragraph suggests a mechanism for schema discovery // which: // 1) disallows discovery of the root DSE controlling schema // 2) violates the constraints upon subschemaSubentry // 3) is inadequate (only works if DSA has single subschema // which applies to all entries). // // Suggest the above paragraph be replaced with: // // -- subschemaSubentry: the DN of the entry (or subentry) // containing the subschema which controls the root DSE // itself. // // Note: Clients should use the mechanism described in X.Y // to for locating controlling subschema of other entries. // // (as described above). 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 Zeilenga [Page 10] INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2251-00 4 July 2000 Basic Encoding Rules [11]. // typically? The protocol is transferred using the subset // of BER known as the Data Encoding Rules. (or does this // belong below). 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. // or provide a root DSE. 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 { messageID MessageID, protocolOp CHOICE { bindRequest BindRequest, bindResponse BindResponse, unbindRequest UnbindRequest, searchRequest SearchRequest, searchResEntry SearchResultEntry, searchResDone SearchResultDone, searchResRef SearchResultReference, modifyRequest ModifyRequest, Zeilenga [Page 11] INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2251-00 4 July 2000 modifyResponse ModifyResponse, addRequest AddRequest, addResponse AddResponse, delRequest DelRequest, delResponse DelResponse, modDNRequest ModifyDNRequest, modDNResponse ModifyDNResponse, compareRequest CompareRequest, compareResponse CompareResponse, abandonRequest AbandonRequest, extendedReq ExtendedRequest, extendedResp ExtendedResponse }, // Added ExtendedPartialResponse // Add note below that this CHOICE may be extended. 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. 4.1.1.1. Message ID All LDAPMessage envelopes encapsulating responses contain the messageID value of the corresponding request LDAPMessage. // Add: // Unsolicited notifications, as defined in section 4.4, Zeilenga [Page 12] INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2251-00 4 July 2000 // MUST have a zero valued message ID. 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. // s/a value/a non-zero value/ // a zero value request would generate responses which cannot // easily be distinguished from unsolicited notifications. 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. // This implies that a server must defer responding to requests // received after an abandon request until after it processed // the abandon request (or completed the operation to be // abandon). 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 // s/byte/octet byte values are used to form a variable-length encoding of an // s/byte/octet 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. Zeilenga [Page 13] INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2251-00 4 July 2000 // A formal, definitive specification for the dotted-decimal // representation should be provided here and then referenced // as needed below and in related documents. 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. 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". // refer to formal dotted-decimal spec. 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 Zeilenga [Page 14] INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2251-00 4 July 2000 0x7F.) // s/byte/octet/ 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. // Given that textual names are non-unique, a server MUST be allowed // to respond with a OID of the attribute type where it's names are // known to non-unique in the controlling subschema. OR require // names of schema elements must be unique within a particular // subschema. 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. 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: ::= [ ";" ] ::=