draft-ietf-ldapext-ldapv3-dupent-xx.txt

LDAPEXT Working Group                                    J. Sermersheim
Internet Draft                                              Novell, Inc
Document: draft-ietf-ldapext-ldapv3-dupent-03.txt            March 2000
Category: Proposed Standard


  LDAP Control for a Duplicate Entry Representation of Search Results


1. 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.

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.

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.

   An application may need to produce an ordered list of entries,
   sorted by a multi-valued attribute, where each attribute value is
   represented in the list.  In order to do this, a separate control is
   needed which causes the set of entries to be expanded sufficiently
   to represent each attribute value prior to sorting.


 Sermersheim      Standards Track - Expires Sep 2000            Page 1

LDAP Control for a Duplicate Entry Representation of Search Results


   This document describes controls, which allow duplicate entries in
   the result set of search, where each entry represents a distinct
   value of a given multiple valued attribute.

   An example of this would be a sorted list of all telephone numbers
   in an organization.  Because any 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.

   Another example would be an application that needs to display an
   ordered list of all members of a group.  It would use this control
   to create a result set of duplicate groupOfNames entries, each with
   a single, unique value in its member attribute.

   The key words "MUST", "SHOULD", and "MAY" used in this document
   carry the meanings described in [Bradner97].

4. The Controls

   Support for the controls is advertised by the presence of their OID
   in the supportedControl attribute of a server's root DSE.  The OID
   for the request control is "2.16.840.1.113719.1.27.101.1" and the
   OID for the response control is "2.16.840.1.113719.1.27.101.2".

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 "2.16.840.1.113719.1.27.101.1". 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 "AttributeDescriptionList" data type is described in 4.1.5 of
   [LDAPv3] and describes a list of 0 or more AttributeDescription
   types as also described in 4.1.5 of [LDAPv3]. Both definitions are
   repeated here for convenience:

        AttributeDescriptionList ::= SEQUENCE OF
                AttributeDescription

        AttributeDescription ::= <AttributeType> [ ";" <options> ]

   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


Sermersheim       Standards Track - Expires Sep 2000            Page 2

LDAP Control for a Duplicate Entry Representation of Search Results


   holds a single, unique value from the original set of values of that
   attribute.

   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. Because of the potential complexity involved in servicing
   multiple attribute types, server implementations MAY choose to
   support a limited number of attribute types in the control.

   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 "2.16.840.1.113719.1.27.101.2". 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 }

   A result field is provided here to allow feedback in the case where
   the criticality of the request control is FALSE, and the server
   could not process the control - yet it could complete the search
   operation successfully. If the request control's criticality is
   TRUE, and the server cannot process the control, the resultCode of
   the LDAPResult is used to report the error.

Sermersheim       Standards Track - Expires Sep 2000            Page 3

LDAP Control for a Duplicate Entry Representation of Search Results



   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.

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" organizational unit of "Looney
   Tunes".  Let's say the following three entries exist in this
   organization;

   dn: cn=Bugs Bunny,ou=Acting,o=Looney Tunes
   telephoneNumber: 555-0123

   dn: cn=Daffy Duck,ou=Acting,o=Looney Tunes
   telephoneNumber: 555-8854
   telephoneNumber: 555-4588
   telephoneNumber: 555-5884

   dn: cn=Porky Pig,ou=Acting,o=Looney Tunes
   telephoneNumber: 555-9425
   telephoneNumber: 555-7992

   First an LDAP search is specified with a baseDN of "ou=Acting,
   o=Looney Tunes ", 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:

   dn: cn=Bugs Bunny,ou=Acting,o=Looney Tunes
   telephoneNumber: 555-0123

   dn: cn=Daffy Duck,ou=Acting,o=Looney Tunes
   telephoneNumber: 555-8854

   dn: cn=Daffy Duck,ou=Acting,o=Looney Tunes
   telephoneNumber: 555-4588

   dn: cn=Daffy Duck,ou=Acting,o=Looney Tunes
   telephoneNumber: 555-5884

   dn: cn=Porky Pig,ou=Acting,o=Looney Tunes
   telephoneNumber: 555-9425

   dn: cn=Porky Pig,ou=Acting,o=Looney Tunes
   telephoneNumber: 555-7992


Sermersheim       Standards Track - Expires Sep 2000            Page 4

LDAP Control for a Duplicate Entry Representation of Search Results


   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.

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:

   dn: cn=Bugs Bunny,ou=Acting,o=Looney Tunes
   givenName: Bugs
   mail: bbunny@looneytunes.com

   dn: cn=Elmer Fudd,ou=Acting,o=Looney Tunes
   givenName: Elmer
   givenName: Doc
   mail: efudd@looneytunes.com
   mail: bunnyhunter@nra.org

   And both "mail" and "givenName" are specified as attribute types in
   this control, the resulting set of entries would be this:

   dn: cn=Bugs Bunny,ou=Acting,o=Looney Tunes
   givenName: Bugs
   mail: bbunny@looneytunes.com

   dn: cn=Elmer Fudd,ou=Acting,o=Looney Tunes
   givenName: Elmer
   mail: efudd@looneytunes.com

   dn: cn=Elmer Fudd,ou=Acting,o=Looney Tunes
   givenName: Elmer
   mail: bunnyhunter@nra.org

   dn: cn=Elmer Fudd,ou=Acting,o=Looney Tunes
   givenName: Doc
   mail: efudd@looneytunes.com

   dn: cn=Elmer Fudd,ou=Acting,o=Looney Tunes
   givenName: Doc
   mail: bunnyhunter@nra.org

5.3 Listing the members of a groupOfNames

   This example shows how the controls can be used to turn a single
   groupOfNames entry into multiple duplicate entries.  LetÆs say this
   is our groupOfNames entry:

   dn: cn=Administrators,o=acme
   cn: Administrators
   member: cn=aBaker,o=acme
   member: cn=cDavis,o=acme

Sermersheim       Standards Track - Expires Sep 2000            Page 5

LDAP Control for a Duplicate Entry Representation of Search Results


   member: cn=bChilds,o=acme
   member: cn=dEvans,o=acme

   We could set our search base to "cn=Administrators,o=acme", filter
   to "objectClass=*", use an object scope (to restrict it to this
   entry) and send the duplicateEntryRequest control with "member" as
   its attribute value.  The resulting set would look like this:

   dn: cn=Administrators,o=acme
   member: cn=aBaker,o=acme

   dn: cn=Administrators,o=acme
   member: cn=cDavis,o=acme

   dn: cn=Administrators,o=acme
   member: cn=bChilds,o=acme

   dn: cn=Administrators,o=acme
   member: cn=dEvans,o=acme

   This list can then be sorted by member and displayed (also by
   member) in a list.

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.

   This control may also be used with the Virtual List View [VLV]
   control (which has a dependency on the Server Side Sort control).
   The nature of the dependency between the VLV control and the Sort
   control is such that the Sorting takes place first. Because the sort
   happens first, and because this control is processed before the sort
   control, the impact of this control on the VLV control is minimal.
   Some server implementations may need to carefully consider how to
   handle the typedown functionality of the VLV control when paired
   with this control. The details of this are heavily implementation
   dependent and are beyond the scope of this document.

7. Notes for Implementers

   Both client and server implementations should be aware that using
   this control could potentially result in a very large set of search
   results. Servers MAY return an adminLimitExceeded result in the
   response control due to inordinate consumption of resources. This
   may be due to some a priori knowledge such as a server restriction
   of the number of attribute types in the request control that it's


Sermersheim       Standards Track - Expires Sep 2000            Page 6

LDAP Control for a Duplicate Entry Representation of Search Results


   willing to service, or it may be due to the server attempting to
   service the control and running out of resources.

   Client implementations must be aware that search entries returned,
   when using this control will contain a subset of the values of any
   specified attribute.

8. Acknowledgments

   The author gratefully thanks the input and support of participants
   of the LDAP-EXT working group.

9. 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-ldapext-sorting-02.txt.

   [VLV]
   Boreham, D, Sermersheim, J, Anantha, A, Armijo, M, "LDAP Extensions
   for Scrolling View Browsing of Search Results", Internet Draft,
   June, 1999.
   Available as draft-ietf-ldapext-ldapv3-vlv-03.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






Sermersheim       Standards Track - Expires Sep 2000            Page 7