INTERNET-DRAFT Jim Sermersheim, Novell ldapext Working Group 18 November, 1998 LDAP Control for a Duplicate Entry Representation of Search Results draft-ietf-ldapext-ldapv3-dupent-00.txt This document expires on 18 March 1999 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 This document describes a Duplicate Entry Representation control extension for the LDAP Search operation. By using the control with an LDAP search, a client requests that the server return separate entries for each value held in the specified attributes. For instance, if a specified attribute of an entry holds multiple values, the search operation will return multiple instances of that entry, each instance holding a separate single value in that attribute. Sermersheim [Page 1] INTERNET DRAFT November 1998 3. Overview The Server-Side Sorting control [SSS] allows the server to order search result entries based on attribute values (sort keys). It does not allow one to specify behavior when an attribute contains multiple values. The default behavior, as outlined in 7.9 of [X.511], is to use the smallest value as the sort key. If the goal of an application is to produce an ordered list of entries, sorted by a multi-valued attribute, where each attribute value is represented in the list, a separate control is needed which causes the set of entries to be expanded sufficiently to represent each attribute value prior to sorting. An example of this would be a sorted list of all telephone numbers in an organization. Because an entry may have multiple telephone numbers, and the list is to be sorted by telephone number, the list must be able to contain duplicate entries, each with its own unique telephone number. The focus of these controls is to allow duplicate entries in the result set of search, where each entry represents a distinct value of a given multiple valued attribute. The key words "MUST", "SHOULD", and "MAY" used in this document carry the meanings described in [Bradner97]. 4. The Controls Support for the Duplicate Entry Control is indicated by the presence of the OID in the supportedExtensions attribute of a server's root DSE. 4.1 Request Control 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 [LDAPv3]. The controlType is set to ). The criticality MAY be set to either TRUE or FALSE. The controlValue is an OCTET STRING, whose value is the BER encoding of the following type: DuplicateEntryRequest ::= AttributeDescriptionList The data type "AttributeDescriptionList" describes a list of 0 or more AttributeDescription types as described in 4.1.5 of [LDAPv3]. While processing a search request, a server implementation examines this list. If a specified attribute exists in an entry to be returned by search, one instance of that entry per attribute value is returned. In this case, the specified attribute in each entry holds a single, unique value from the original set of values of that attribute. Sermersheim [Page 2] INTERNET DRAFT November 1998 An AttributeDescription should only occur once in the list. If an AttributeDescription is included in the DuplicateEntryRequest multiple times, the server should return an unwillingToPerform error in the DuplicateEntryResponse. When two or more attribute types are specified by this control, the number of duplicate entries is the combination of all values in each attribute. There is a special case where either no attributes are specified, or an attribute description value of "*" is specified. In this case, all attributes are used. (The "*" allows the client to request all user attributes in addition to specific operational attributes). 4.2 Response Control This control is included in the searchResultDone message as part of the controls field of the LDAPMessage, as defined in Section 4.1.12 of [LDAPv3]. The controlType is set to . The criticality is FALSE (MAY be absent). The controlValue is an OCTET STRING, whose value is the BER encoding of the following SEQUENCE: DuplicateEntryResponse ::= SEQUENCE { result ENUMERATED { success (0), operations error (1), -- server internal failure timeLimitExceeded (3), -- time limit reached before -- attribute values could be -- processed sizeLimitExceeded (4), -- size limit reached as a -- result of this control adminLimitExceeded (11), -- result set too large for -- server to handle noSuchAttribute (16), -- unrecognized attribute -- description busy (51), unwillingToPerform (53), other (80) }, attributeType AttributeDescription OPTIONAL } attributeType MAY be set to the value of the first attribute type specified by the DuplicateEntryRequest that was in error. The client MUST ignore the attributeType field if the result is success. Sermersheim [Page 3] INTERNET DRAFT November 1998 5. Protocol Examples 5.1 Simple example This example will show this control being used to produce a list of all telephone numbers in the "Acting" organization of the US Company "Looney Tunes". Let's say the following three entries exist in this organization; cn=Bugs Bunny telephoneNumber=555-0123 cn=Daffy Duck telephoneNumber=555-8854, 555-4588, 555-5884 cn=Porky Pig telephoneNumber=555-9425, 555-7992 First an LDAP search is specified with a baseDN of "ou=Acting, o=Looney Tunes, c=us", subtree scope, filter set to "telephoneNumber=*". A DuplicateEntryRequest control is attached to the search, specifying "telephoneNumber" as the attribute description, and the search request is sent to the server. The set of search results returned by the server would then consist of the following entries: cn=Bugs Bunny telephoneNumber=555-0123 cn=Daffy Duck telephoneNumber=555-8854 cn=Daffy Duck telephoneNumber=555-4588 cn=Daffy Duck telephoneNumber=555-5884 cn=Porky Pig telephoneNumber=555-9425 cn=Porky Pig telephoneNumber=555-7992 Note that it is not necessary to use an attribute type in this control, that is specified in the search filter. This example only does so, because the result was to obtain a list of telephone numbers. Sermersheim [Page 4] INTERNET DRAFT November 1998 5.2 Specifying multiple attributes A more complicated example involving multiple attributes will result in more entries. If we assume these entries in the directory: cn=Bugs Bunny givenName=Bugs mail=bbunny@looneytunes.com cn=Elmer Fudd givenName=Elmer, Doc mail=efudd@looneytunes.com, bunnyhunter@nra.org And both "telephoneNumber" and "givenName" are specified as attribute types in this control, the resulting set of entries would be this: cn=Bugs Bunny givenName=Bugs mail=bbunny@looneytunes.com cn=Elmer Fudd givenName=Elmer mail=efudd@looneytunes.com cn=Elmer Fudd givenName=Elmer mail=bunnyhunter@nra.org cn=Elmer Fudd givenName=Doc mail=efudd@looneytunes.com cn=Elmer Fudd givenName=Doc mail=bunnyhunter@nra.org 6 Relationship to other controls This control is intended (but not limited) to be used with the Server Side Sorting control [SSS]. By pairing this control with the Server Side Sorting control, One can produce a set of entries, sorted by attribute values, where each attribute value is represented in the sorted set. Server implementations should ensure that this control is processed before sorting the result of a search, as this control alters the result set of search. Sermersheim [Page 5] INTERNET DRAFT November 1998 7. Notes for Implementors Both client and server implementations should be aware that using this control could potentially result in a very large set of search results. Servers are free to return an adminLimitExceeded result in the response control due to inordinate consumption of resources. Client implementations must be aware that search entries returned, when using this control, may contain a subset of the values of any specified attribute. 8. References [LDAPv3] Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access Protocol (v3)", Internet Standard, December, 1997. Available as RFC2251. [SSS] Wahl, M, A. Herron and T. Howes, "LDAP Control Extension for Server Side Sorting of Search Results", Internet Draft, March, 1998. Available as draft-ietf-asid-ldapv3-sorting-01.txt. [X.511] ITU-T Rec. X.511, "The Directory: Abstract Service Definition", 1993. [Bradner97] Bradner, Scott, "Key Words for use in RFCs to Indicate Requirement Levels", Internet Draft, March, 1997. Available as RFC2119. 10. Author's Address Jim Sermersheim Novell, Inc. 122 East 1700 South Provo, Utah 84606, USA jimse@novell.com +1 801 861-3088 This document expires on 18 May 1999 Sermersheim [Page 6]