One document matched: draft-ietf-ldapext-ldapv3-dupent-02.txt
Differences from draft-ietf-ldapext-ldapv3-dupent-01.txt
LDAP Control for a Duplicate Entry Representation of Search Results
draft-ietf-ldapext-ldapv3-dupent-02.txt
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
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
Sermersheim Internet Draft [Page 1]
Internet-Draft October 1999
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.
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
Sermersheim Internet Draft [Page 2]
Internet-Draft October 1999
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
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.
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
Sermersheim Internet Draft [Page 3]
Internet-Draft October 1999
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.
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
telephoneNumber: 555-4588
telephoneNumber: 555-5884
cn: Porky Pig
telephoneNumber: 555-9425
telephoneNumber: 555-7992
Sermersheim Internet Draft [Page 4]
Internet-Draft October 1999
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.
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
Sermersheim Internet Draft [Page 5]
Internet-Draft October 1999
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:
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
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
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:
Sermersheim Internet Draft [Page 6]
Internet-Draft October 1999
cn: Administrators
member: cn=aBaker,o=acme
cn: Administrators
member: cn=cDavis,o=acme
cn: Administrators
member: cn=bChilds,o=acme
cn: Administrators
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.
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 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 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]
Sermersheim Internet Draft [Page 7]
Internet-Draft October 1999
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
Appendix A -- Changes since last publication
October 13, 1999.
Revised version number of document
Changed OID numbers.
November 16, 1999.
Added OID numbers.
Added text and an example explaining use as a way to sort members
of a group.
This document expires in April 2000
Sermersheim Internet Draft [Page 8]
| PAFTECH AB 2003-2026 | 2026-04-24 03:08:17 |