mirror of
https://git.openldap.org/openldap/openldap.git
synced 2024-12-21 03:10:25 +08:00
413 lines
15 KiB
Plaintext
413 lines
15 KiB
Plaintext
|
||
|
||
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<65>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
|