mirror of
https://git.openldap.org/openldap/openldap.git
synced 2025-01-12 10:54:48 +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
|