LDAPEXT Working Group B. Greenblatt Internet Draft Directory Tools and Application Services, Inc. Document: May 2001 Category: Standards Track Control for requesting DN object class in LDAP Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026 [1]. 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. 1. Abstract There are many circumstances in LDAP [1] when the result of a Search operation returns attribute values that have the distinguished name (DN) syntax. This document defines controls that allow the client to request that the server tag each DN with its object classes. This is a useful feature because object classes such as groups [3] may hold many DNs, each of which is a potentially different object class. When using this control in a search, the LDAP client request that the server return the object classes of each DN that is an attribute value of the search result. This control also defines a way to limit the kinds of DNs that should be returned in a Search result. 2. Conventions used in this document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC-2119 [5]. 3. Control for Requesting Object Class information Greenblatt Standards Track û Expires November 2001 1 DN Object Class Control for LDAP May 2001 This control is included in the SearchRequest message as part of the controls field of the LDAPMessage, as defined in Section 4.1.12 of [1]. The controlType is set to "1.3.6.1.4.1.5515.5.1". The criticality SHOULD be set to FALSE. If this control is included in a SearchRequest message, and the server understands the control, then a corresponding control that contains object class information is included in the SearchResultDone message as part of the controls field of the LDAPMessage. The controlValue is an OCTET STRING whose value is the BER-encoding of the following SEQUENCE: DNObjectClassRequest ::= SEQUENCE { listObjectClasses ENUMERATED { all (0), mostSubordinateOnly (1), omitAuxiliary (2), mostSubordinateStructural (3), none (4) } OPTIONAL, CHOICE { dnSelection [0] SEQUENCE OF LDAPString, dnOmission [1] SEQUENCE OF LDAPString } OPTIONAL } Upon receiving this control, a server that supports it MUST process this as a standard LDAPv3 search with the following changes: a) If listObjectClasses is "all" the DNObjectClassResponse request includes all object classes for each DN value in the SearchResult. If listObjectClasses is "mostSubordinateOnly", the DNObjectClassResponse contains only the most specific object class in the entries object class inheritance. For example, if a DN referred to an entry that was the object class of "Person", then the DNObjectClassResponse would only contain the information that the DN was a "person", instead of including the "top" object class information as well. If listObjectClasses is "omitAuxiliary", only the object classes that are included in the DNObjectClassResponse are those in the "structural" object classÆ inheritance. For example, if a DN referred to an entry that was the object class of "Person" and "StrongAuthenticationUser", then the DNObjectClassResponse would only contain the information that the DN was a "person" and "top". If listObjectClasses is "mostSubordinateStructural", only the object classes that are included in the DNObjectClassResponse is the most specific object class in the "structural" object classÆ inheritance. For example, if a DN referred to an entry that was the object class of "Person" and "StrongAuthenticationUser", then the DNObjectClassResponse would only contain the information that the DN was a "person". If listObjectClasses is "none" the DNObjectClassResponse does MUST NOT include any information about the object classes of the returned DN values. b) If dnSelection is present it lists the dn values, the object classes of which should be included in the Search Result. The Greenblatt Standards Track 2 DN Object Class Control for LDAP May 2001 LDAP Server should process the Search Request normally, but only include those DN values in the returned results which match one of the values in the list of object classes specified in the control. Object class values in the dnSelection that are unknown or invalid are ignored in the processing, but are listed in the ignoredDNValues of the DNObjectClassResponse. c) If dnOmission is present it lists the dn values, the object classes of which should be omitted the Search Result. The LDAP Server should process the Search Request normally, but exclude all of those DN values in the returned results which match one of the values in the list of object classes specified in the control. Object class values in the dnOmission that are unknown or invalid are ignored in the processing, but are listed in the ignoredDNValues of the DNObjectClassResponse. Servers that claim support for this control MUST support the listObjectClasses processing defined above. Support for processing dnSelection and dnOmission is OPTIONAL. Note that the processing of the DNObjectClassRequest never restricts the entries which are returned as a result of the processing of the submitted SearchRequest. 4. Control for Responding to Requests for Object Class information This control is included in the SearchRequestDone message as part of the controls field of the LDAPMessage, as defined in Section 4.1.12 of [1]. The controlType is set to "1.3.6.1.4.1.5515.5.2". The controlValue is an OCTET STRING whose value is the BER-encoding of the following SEQUENCE: DNObjectClassResponse ::= SEQUENCE { SEQUENCE OF { entry LDAPDN, objectClassList SEQUENCE of LDAPString }, ignoredDNValues LDAPString, dNObjectClassResult ENUMERATED { success (0), operationsError (1), timeLimitExceeded (3), busy (51), unwillingToPerform (53), dnSelectionOrOmissionIgnored (60) } The dNObjectClassResult codes that are common to the LDAP searchResponse (success, operationsError, timeLimitExceeded, busy, unwillingToPerform) have the same meanings as defined in [1], but they pertain specifically to the DN Object Class Request operation. For example, the server could exceed a time limit processing a SearchRequest with a DNObjectClassRequest control. However, the same time limit would not be exceeded should the client submit the same Greenblatt Standards Track 3 DN Object Class Control for LDAP May 2001 SearchRequest without the DNObjectClassRequest control. In this case, the client can determine that a time limit has been exceeded in servicing the DNObjectClassRequest, and can choose to resubmit the SearchRequest without the DNObjectClassRequest control. If the DNObjectClassRequest control includes dnSelection or dnOmission information and the Server only supports the listObjectClasses processing, then the Server MUST return the result code dnSelectionOrOmissionIgnored in the DNObjectClassResponse. 5. Examples Assume a Directory Information Tree (DIT) with the following entries: DN Most Subordinate Object Classes O=dtasi.com Organization Ou=sales, o=dtasi.com OrganizationalUnit Ou=eng, o=dtasi.com OrganizationalUnit Uid=bruceg, ou=sales, o=dtasi.com InetOrgPerson Uid=joe, ou=sales, o=dtasi.com InetOrgPerson, StrongAuthenticationUser Uid=mary, ou=sales, o=dtasi.com InetOrgPerson Cn=se, ou=sales, o=dtasi.com GroupOfNames Cn=cs, ou=sales, o=dtasi.com GroupOfNames Uid=tom, ou=eng, o=dtasi.com InetOrgPerson, StrongAuthenticationUser Uid=alice, ou=eng, o=dtasi.com InetOrgPerson, StrongAuthenticationUser Uid=fred, ou=eng, o=dtasi.com InetOrgPerson Uid=elmer, ou=eng, o=dtasi.com InetOrgPerson Cn=support, ou=eng, o=dtasi.com GroupOfNames Cn=qa, ou=eng, o=dtasi.com GroupOfNames Cn=dev, ou=eng, o=dtasi.com GroupOfNames Table 1 - Sample DIT Assume that the Groups in the DIT have the following member attribute values: Group DN Members Cn=se, ou=sales, o=dtasi.com Uid=joe, ou=sales, o=dtasi.com Cn=qa, ou=eng, o=dtasi.com Cn=cs, ou=sales, o=dtasi.com Uid=mary, ou=sales, o=dtasi.com Cn=support, ou=eng, o=dtasi.com Uid=alice, ou=eng, o=dtasi.com Cn=support, ou=eng, o=dtasi.com Uid=alice, ou=eng, o=dtasi.com Uid=bruceg, ou=sales, o=dtasi.com Cn=qa, ou=eng, o=dtasi.com Uid=fred, ou=eng, o=dtasi.com Uid=tom, ou=eng, o=dtasi.com Cn=dev, ou=eng, o=dtasi.com Cn=qa, ou=eng, o=dtasi.com Uid=elmer, ou=eng, o=dtasi.com Table 2 - Group membership information for the Sample DIT Greenblatt Standards Track 4 DN Object Class Control for LDAP May 2001 Consider the following Searches: a) Search Base: ou=sales, o=dtasi.com, scope: subtree, filter: "objectClass=groupOfNames", attributes: member. Assume that dnSelection and dnOmission are not present. This search matches all 5 groups in Table 2. Assuming that there are no problems in processing, the contents of the DNObjectClassResponse are: i. If listObjectClasses = "all": Uid=joe, ou=sales, o=dtasi.com: inetOrgPerson, organizationalPerson, Person, top, strongAuthenticationPerson; Cn=qa, ou=eng, o=dtasi.com: groupOfNames, top; Uid=mary, ou=sales, o=dtasi.com: inetOrgPerson, organizationalPerson, Person, top; Cn=support, ou=eng, o=dtasi.com: groupOfNames, top; Uid=alice, ou=eng, o=dtasi.com: inetOrgPerson, organizationalPerson, Person, top, strongAuthenticationUser; ii. If listObjectClasses = "mostSubordinateOnly": Uid=joe, ou=sales, o=dtasi.com: inetOrgPerson, strongAuthenticationPerson; Cn=qa, ou=eng, o=dtasi.com: groupOfNames; Uid=mary, ou=sales, o=dtasi.com: inetOrgPerson; Cn=support, ou=eng, o=dtasi.com: groupOfNames; Uid=alice, ou=eng, o=dtasi.com: inetOrgPerson, strongAuthenticationUser; iii. If listObjectClasses = "omitAuxiliary": Uid=joe, ou=sales, o=dtasi.com: inetOrgPerson, organizationalPerson, Person, top; Cn=qa, ou=eng, o=dtasi.com: groupOfNames, top; Uid=mary, ou=sales, o=dtasi.com: inetOrgPerson, organizationalPerson, Person, top; Cn=support, ou=eng, o=dtasi.com: groupOfNames, top; Uid=alice, ou=eng, o=dtasi.com: inetOrgPerson, organizationalPerson, Person, top; iv. If listObjectClasses = "mostSubordinateStructural": Uid=joe, ou=sales, o=dtasi.com: inetOrgPerson; Cn=qa, ou=eng, o=dtasi.com: groupOfNames; Uid=mary, ou=sales, o=dtasi.com: inetOrgPerson; Cn=support, ou=eng, o=dtasi.com: groupOfNames; Uid=alice, ou=eng, o=dtasi.com: inetOrgPerson; v. If listObjectClases = "none", the DNObjectClassResponse does not contain any object class information b) Search Base: o=dtasi.com, scope: subtree, filter: "member= Uid=alice, ou=eng, o=dtasi.com", attributes: member. Assume that dnSelection is "person", and dnOmission is not present. This search only the 2 groups in Table 2 in which alice is named as a member. The presence of the dnSelection indicates that the SearchResultEntry message only includes those DN attribute values in which the DN refers to an entry that specifies a person object. So, all of the group values of the member attribute that would have been returned if the DNObjectClassRequest had not been specified are omitted from the SearchResultEntry messages. This way, the client is able to ignore the nested groups in the specified group entries. Greenblatt Standards Track 5 DN Object Class Control for LDAP May 2001 Assuming that there are no problems in processing, the contents of the DNObjectClassResponse are: i. If listObjectClasses = "all": Uid=mary, ou=sales, o=dtasi.com: inetOrgPerson, organizationalPerson, Person, top; Uid=alice, ou=eng, o=dtasi.com: inetOrgPerson, organizationalPerson, person, top, strongAuthenticationUser; Uid=bruceg, ou=sales, o=dtasi.com: inetOrgPerson, organizationalPerson, person, top; ii. If listObjectClasses = "mostSubordinateOnly": Uid=mary, ou=sales, o=dtasi.com: inetOrgPerson; Uid=alice, ou=eng, o=dtasi.com: inetOrgPerson, strongAuthenticationUser; Uid=bruceg, ou=sales, o=dtasi.com: inetOrgPerson; iii. If listObjectClasses = "omitAuxiliary": Uid=mary, ou=sales, o=dtasi.com: inetOrgPerson, organizationalPerson, Person, top; Uid=alice, ou=eng, o=dtasi.com: inetOrgPerson, organizationalPerson, person, top; Uid=bruceg, ou=sales, o=dtasi.com: inetOrgPerson, organizationalPerson, person, top; iv. If listObjectClasses = "mostSubordinateStructural": Uid=mary, ou=sales, o=dtasi.com: inetOrgPerson; Uid=alice, ou=eng, o=dtasi.com: inetOrgPerson; Uid=bruceg, ou=sales, o=dtasi.com: inetOrgPerson; v. If listObjectClases = "none", the DNObjectClassResponse does not contain any object class information c) Search Base: o=dtasi.com, scope: subtree, filter: "member= Uid=alice, ou=eng, o=dtasi.com", attributes: member. Assume that dnOmission is "person", and dnSelection is not present. This search only the 2 groups in Table 2 in which alice is named as a member. The presence of the dnOmission indicates that the SearchResultEntry message only includes those DN attribute values in which the DN refers to an entry that specifies something other than a person object. So, all of the person values of the member attribute that would have been returned if the DNObjectClassRequest had not been specified are omitted from the SearchResultEntry messages. This way, the client is able to retrieve the nested groups from the specified group entries. Assuming that there are no problems in processing, the contents of the DNObjectClassResponse are: i. If listObjectClasses = "all": Cn=qa, ou=eng, o=dtasi.com: groupOfNames, top; ii. If listObjectClasses = "mostSubordinateOnly": Cn=qa, ou=eng, o=dtasi.com: groupOfNames; iii. If listObjectClasses = "omitAuxiliary": Cn=qa, ou=eng, o=dtasi.com: groupOfNames, top; iv. If listObjectClasses = "mostSubordinateStructural": Cn=qa, ou=eng, o=dtasi.com: groupOfNames; v. If listObjectClases = "none", the DNObjectClassResponse does not contain any object class information 6. Security Considerations Greenblatt Standards Track 6 DN Object Class Control for LDAP May 2001 This memo describes mechanism to enhance the retrieval of DN values when using LDAP search filters. This mechanism itself has no known security implications. However, LDAP search filters do have security implications, as defined in [1]. LDAP servers should take care to protect the data they maintain from unauthorized access. 7. References [1] Wahl, M., Kille, S. and Howes, T., "Lightweight Directory Access Protocol (v3)", Internet Standard, December, 1997. RFC2251. [2] Wahl, M., Coulbeck, A., Howes, T. and Kille, S., "Lightweight Directory Access Protocol (v3), Attribute Syntax Definitions", Internet Standard, December, 1997. RFC2252. [3] Wahl, M., "A Summary of the X.500(96) User Schema for use with LDAPv3", Internet Standard, December, 1997. RFC2256. [4] Crocker, D., and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 191 Bradner, S., "The Internet Standards Process -- Revision 3", BCP 9, RFC 2026, October 1996. [5] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997 8. Author's Address Bruce Greenblatt Directory Tools and Application Services, Inc. 6841 Heaton Moor Drive San Jose, CA 95119 Email: bgreenblatt@directory-applications.com Full Copyright Statement "Copyright (C) The Internet Society (date). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implmentation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING Greenblatt Standards Track 7 DN Object Class Control for LDAP May 2001 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Greenblatt Standards Track 8