[Date Prev][Date Next]
[Chronological]
[Thread]
[Top]
draft-ietf-ldapext-ldapv3-dupent-00.txt
I submitted this but I fear it may have not slipped through before the cutoff time.
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.
Welcoming and comments or co-authors.
Jim
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 <To Be Determined> 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 <To Be Determined>). 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 <TBD>. 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]