--- 1/draft-ietf-ldapbis-protocol-03.txt 2006-02-05 00:11:45.000000000 +0100 +++ 2/draft-ietf-ldapbis-protocol-04.txt 2006-02-05 00:11:45.000000000 +0100 @@ -1,14 +1,14 @@ Internet-Draft Editor: J. Sermersheim Intended Category: Standard Track Novell, Inc -Document: draft-ietf-ldapbis-protocol-03.txt October 2001 +Document: draft-ietf-ldapbis-protocol-04.txt October 2001 Obsoletes: RFC 2251 Lightweight Directory Access Protocol (v3) 1. Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of [RFC2026]. Internet-Drafts are working documents of the Internet Engineering @@ -26,154 +26,103 @@ http://www.ietf.org/shadow.html. Distribution of this memo is unlimited. Technical discussion of this document will take place on the IETF LDAP Revision Working Group (LDAPbis) mailing list . Please send editorial comments directly to the editor . Table of Contents 1. Status of this Memo..............................................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 + 2. Abstract.........................................................2 + 3. Models...........................................................3 + 3.1. Protocol Model.................................................3 + 3.2. Data Model.....................................................4 + 3.2.1. Attributes of Entries........................................4 + 3.2.2. Subschema Entries and Subentries.............................6 3.3. Relationship to X.500..........................................7 - 3.4. Server-specific Data Requirements..............................8 - 4. Elements of Protocol.............................................8 - 4.1. Common Elements................................................9 - 4.1.1. Message Envelope.............................................9 - 4.1.1.1. Message ID................................................10 - 4.1.2. String Types................................................10 - 4.1.3. Distinguished Name and Relative Distinguished Name..........11 - 4.1.4. Attribute Type..............................................11 - 4.1.5. Attribute Description.......................................12 - 4.1.5.1. Binary Option.............................................13 + 3.4. Server-specific Data Requirements..............................7 + 4. Elements of Protocol.............................................7 + 4.1. Common Elements................................................8 + 4.1.1. Message Envelope.............................................8 + 4.1.1.1. Message ID.................................................9 + 4.1.2. String Types.................................................9 + 4.1.3. Distinguished Name and Relative Distinguished Name..........10 + 4.1.4. Attribute Type..............................................10 + 4.1.5. Attribute Description.......................................11 + 4.1.5.1. Binary Option.............................................12 4.1.6. Attribute Value.............................................13 Lightweight Directory Access Protocol Version 3 - 4.1.7. Attribute Value Assertion...................................14 + 4.1.7. Attribute Value Assertion...................................13 4.1.8. Attribute...................................................14 4.1.9. Matching Rule Identifier....................................14 - 4.1.10. Result Message.............................................15 - 4.1.11. Referral...................................................17 - 4.1.12. Controls...................................................18 - 4.2. Bind Operation................................................19 - 4.2.1. Sequencing of the Bind Request..............................20 + 4.1.10. Result Message.............................................14 + 4.1.11. Referral...................................................16 + 4.1.12. Controls...................................................17 + 4.2. Bind Operation................................................18 + 4.2.1. Sequencing of the Bind Request..............................19 4.2.2. Authentication and Other Security Services..................20 - 4.2.3. Bind Response...............................................21 - 4.3. Unbind Operation..............................................22 + 4.2.3. Bind Response...............................................20 + 4.3. Unbind Operation..............................................21 4.4. Unsolicited Notification......................................22 - 4.4.1. Notice of Disconnection.....................................23 + 4.4.1. Notice of Disconnection.....................................22 4.5. Search Operation..............................................23 4.5.1. Search Request..............................................23 4.5.2. Search Result...............................................27 4.5.3. Continuation References in the Search Result................28 - 4.6. Modify Operation..............................................30 + 4.6. Modify Operation..............................................29 4.7. Add Operation.................................................31 4.8. Delete Operation..............................................32 - 4.9. Modify DN Operation...........................................33 - 4.10. Compare Operation............................................34 + 4.9. Modify DN Operation...........................................32 + 4.10. Compare Operation............................................33 4.11. Abandon Operation............................................34 4.12. Extended Operation...........................................35 - 5. Protocol Element Encodings and Transfer.........................36 - 5.1. Mapping Onto BER-based Transport Services.....................36 + 5. Protocol Element Encodings and Transfer.........................35 + 5.1. Protocol Encoding.............................................35 5.2. Transfer Protocols............................................36 5.2.1. Transmission Control Protocol (TCP).........................36 6. Implementation Guidelines.......................................36 6.1. Server Implementations........................................36 - 6.2. Client Implementations........................................37 - 7. Security Considerations.........................................37 + 6.2. Client Implementations........................................36 + 7. Security Considerations.........................................36 8. Acknowledgements................................................37 - 9. Bibliography....................................................38 - 10. Editor's Address...............................................39 - Appendix A - Complete ASN.1 Definition.............................40 - Appendix B - Change History........................................45 - B.1 Editorial......................................................45 - B.2 Section 1......................................................45 - B.3 Section 9......................................................45 - B.4 Section 4.1.6..................................................45 - B.5 Section 4.1.7..................................................45 - B.6 Sections 4.2, 4.9, 4.10........................................45 - B.7 Sections 4.5 and Appendix A....................................46 - B.8 Section 3.4....................................................46 - B.9 Section 4.1.12.................................................46 - B.10 Section 4.2...................................................46 - B.11 Section 4.2.(various).........................................46 - B.12 Section 4.2.2.................................................46 - B.13 Section 4.5.2.................................................46 - B.14 Section 4.....................................................46 - B.15 Section 4.1.8.................................................47 - B.17 Section 4.1.11................................................47 - B.18 Section 4.1.12................................................47 - - Lightweight Directory Access Protocol Version 3 - - B.19 Section 4.4...................................................47 - B.20 Section 4.5.1.................................................47 - B.21 Section 4.5.3.................................................48 - B.22 Section 4.6...................................................48 - B.23 Section 4.7...................................................48 - B.24 Section 4.11..................................................48 - Appendix C - Outstanding Work Items................................48 - C.1 Integrate result codes draft...................................48 - C.2 Section 3.1....................................................48 - C.3 Section 4......................................................48 - C.4 Section 4.1.1..................................................49 - C.5 Section 4.1.1.1................................................49 - C.6 Section 4.1.2..................................................49 - C.7 Section 4.1.4..................................................49 - C.8 Section 4.1.5..................................................49 - C.9 Section 4.1.5.1................................................49 - C.11 Section 4.1.7.................................................50 - C.13 Section 4.1.11................................................50 - C.14 Section 4.1.12................................................50 - C.15 Section 4.2...................................................50 - C.17 Section 4.2.2.................................................50 - C.18 Section 4.2.3.................................................50 - C.19 Section 4.3...................................................51 - C.20 Section 4.4...................................................51 - C.21 Section 4.5.1.................................................51 - C.22 Section 4.5.2.................................................51 - C.23 Section 4.5.3.................................................51 - C.24 Section 4.5.3.1...............................................51 - C.25 Section 4.6...................................................51 - C.26 Section 4.7...................................................52 - C.27 Section 4.10..................................................52 - C.28 Section 4.11..................................................52 - C.29 Section 4.12..................................................52 - C.30 Section 5.1...................................................52 - C.31 Section 5.2.1.................................................52 - C.32 Section 6.1...................................................52 - C.33 Section 7.....................................................52 + 9. Bibliography....................................................37 + 10. Editor's Address...............................................38 + Appendix A - Complete ASN.1 Definition.............................39 + Appendix B - Change History........................................44 + B.1 Changes made to RFC 2251:......................................44 + B.2 Changes made to draft-ietf-ldapbis-protocol-00.txt:............44 + B.3 Changes made to draft-ietf-ldapbis-protocol-01.txt:............45 + B.4 Changes made to draft-ietf-ldapbis-protocol-02.txt:............45 + B.5 Changes made to draft-ietf-ldapbis-protocol-03.txt:............47 + Appendix C - Outstanding Work Items................................49 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. + Lightweight Directory Access Protocol Version 3 + 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 [RFC2119]. Key aspects of this version of LDAP are: - Lightweight Directory Access Protocol Version 3 - - All protocol elements of LDAPv2 [RFC1777] 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). - Referrals to other servers may be returned. - SASL mechanisms may be used with LDAP to provide association @@ -209,28 +158,28 @@ 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. + Lightweight Directory Access Protocol Version 3 + 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. - Lightweight Directory Access Protocol Version 3 - 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, @@ -260,30 +209,30 @@ 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 - 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. + Entries consist of a set of attributes. An attribute is a description + (a type and zero or more options) with one or more associated values. + The attribute type governs whether the attribute can have multiple + values, the syntax and matching rules used to construct and compare Lightweight Directory Access Protocol Version 3 + values of that attribute, and other functions. Options indicate modes + of transfer 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 [RFC2252] and [X.501]. Additional schema elements may be @@ -321,24 +270,24 @@ 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. - Lightweight Directory Access Protocol Version 3 + - 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. @@ -377,24 +326,24 @@ 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 - Lightweight Directory Access Protocol Version 3 +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 @@ -432,27 +381,27 @@ 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, the schema for each entry is found by reading the subschemaSubentry attribute for that entry. 4. Elements of Protocol The LDAP protocol is described using Abstract Syntax Notation 1 (ASN.1) [X.680], and is transferred using a subset of ASN.1 Basic - Encoding Rules [X.690] In order to support future extensions to this - protocol, clients and servers MUST ignore elements of SEQUENCE + Encoding Rules [X.690]. In order to support future extensions to this Lightweight Directory Access Protocol Version 3 - encodings whose tags they do not recognize. Section 5.1 specifies the - encoding rules for the LDAP protocol. + protocol, clients and servers MUST ignore elements of SEQUENCE + encodings whose tags they do not recognize. Section 5.1 specifies how + the protocol is encoded and transferred. 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 or later is supported in the client (since version 2 required that the client bind first). Clients may determine the protocol versions a server supports by reading the supportedLDAPVersion attribute from the root DSE. Servers @@ -490,24 +439,24 @@ delResponse DelResponse, modDNRequest ModifyDNRequest, modDNResponse ModifyDNResponse, compareRequest CompareRequest, compareResponse CompareResponse, abandonRequest AbandonRequest, extendedReq ExtendedRequest, extendedResp ExtendedResponse }, controls [0] Controls OPTIONAL } - MessageID ::= INTEGER (0 .. maxInt) - Lightweight Directory Access Protocol Version 3 + 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 @@ -557,20 +506,32 @@ Lightweight Directory Access Protocol Version 3 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 + A value of LDAPOID is defined by the following ABNF [RFC2234]: + + ldapOID = number *( DOT number ) + + number = ( LDIGIT *DIGIT ) / DIGIT + + DOT = %x2E ; "." + + LDIGIT = %x31-39 ; 1-9 + + DIGIT = %x30 / LDIGIT ; 0-9 + 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 [RFC2253], such that: @@ -589,36 +550,35 @@ 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 + Lightweight Directory Access Protocol Version 3 + 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". + assigned to it. This identifier may be written as defined by ldapOID + in section 4.1.2. 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- - - Lightweight Directory Access Protocol Version 3 - 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 @@ -632,50 +592,60 @@ 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: + A value of AttributeDescription is based on the following ABNF: - ::= [ ";" ] + attributeDescription = attributeType options - ::=