Commit d8afb52b authored by Kurt Zeilenga's avatar Kurt Zeilenga
Browse files

Add/Update LDAPext drafts

parent 9ef1a740
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
Internet-Draft David Chadwick
LDAPExt WG University of Salford
Intended Category: Standards Track Sean Mullan
Sun
Microsystems
Expires: 8 March 2000 8 September 1999
Returning Matched Values with LDAPv3
<draft-ietf-ldapext-matchedval-01.txt>
STATUS OF THIS MEMO
This document is an Internet-Draft and is in full conformance with
all the 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.
This Internet-Draft expires on 8 March 2000. Comments and suggestions
on this document are encouraged. Comments on this document should be
sent to the LDAPExt working group discussion list:
ietf-ldapext@netscape.com
or directly to the authors.
ABSTRACT
This document describes a control for the Lightweight Directory
Access Protocol v3 that is used to return a subset of attribute
values from an entry, specifically, only those values that
contributed to the search filter evaluating to TRUE. Without support
for this control, a client must retrieve all of an attribute's values
and search for specific values locally.
1. Introduction
When reading an attribute from an entry using LDAP v2 [1] or LDAPv3
[2], it is normally only possible to read either the attribute type,
or the attribute type and all its values. It is not possible to
selectively read just a few of the attribute values. If an attribute
holds many values, for example, the userCertificate attribute, or the
subschema publishing operational attributes objectClasses and
attributeTypes [3], then it may be desirable for the user to be able
to selectively retrieve a subset of the values, specifically, those
attribute values that match the selection criteria as specified by
the user in the filter. Without the control specified in this
[ID/standard] a client must read all of the attribute's values and
filter out the unwanted values, necessitating the client to implement
the matching rules. It also requires the client to potentially read
and process many irrelevant values, which can be inefficient if the
values are large or complex, or there are many values stored per
attribute.
This Internet Draft specifies an LDAPv3 control to enable a user to
return only those values that matched (i.e. returned TRUE to) one or
more elements of the Search filter. This control can be especially
useful when used in conjunction with extensible matching rules that
match on one or more components of complex binary attribute values.
The control has been described in such a way as to be fully
compatible with the matchedValuesOnly boolean of the X.500 DAP [4]
Search argument, as amended in the latest version [6].
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [5].
2. The matchedValuesOnly Control
The matchedValuesOnly control MAY be critical or non-critical as
determined by the user. It is only applicable to the Search
operation, and SHALL be ignored by the server if it is present on any
other LDAP operation (even if marked critical on such operations).
The object identifier for this control is 1.2.826.0.1.3344810.2.2
The controlValue is absent.
If the server supports this control, the server MUST make use of the
control as follows:
(1) If the typesOnly parameter of the Search Request is TRUE,
the control has no effect and the Search Request SHOULD be
processed as if the control had not been specified.
(2) If the attributes parameter of the Search Request consists
of a list containing only the attribute with OID "1.1"
(specifying that no attributes are to be returned), the control
has no effect and the Search Request SHOULD be processed as if
the control had not been specified.
(3) For each attribute listed in the attributes parameter of the
Search Request, the server MUST apply the control as follows:
i) Every attribute value that evaluates TRUE against one or
more filters, excluding the ignored filters (see below),
is logically marked by the server as contributing to the
filter matching.
ii) Attributes that have no values marked as contributing,
have all their values returned to the user.
iii) Attributes that have one or more values marked as
contributing have only the contributing values returned to
the user, whilst the other values of the same attribute
(if there are any) are not returned.
Certain filters are ignored for the purposes of marking the attribute
values as contributing. These are:
the ôpresentö filter, since this filter does not test against
any attribute values;
the ônotö filter, since this would have the effect of marking
all the attribute values except the one(s) that matched the
non-negated filter.
3. Relationship to X.500
The matchedValuesOnly control defined in this document is derived
from the matchedValuesOnly boolean parameter of the X.511 (93) DAP
Search operation [4]. Note however that in X.511 (93), the
matchedValuesOnly parameter is ignored when used with an "equality"
match FilterItem, and so the user must use the extensibleMatch filter
along with the equality matching rule if only matched values are
wanted with equality matching. This slightly spurious equality match
restriction has been removed from the 2000 version of X.511 [6]. For
LDAP servers acting as a gateway to an X.500 directory, the matched
valuesOnly control can be directly mapped onto the X.511
matchedValuesOnly Search parameter as follows:
(1) If the matchedValuesOnly control is specified, the
matchedValuesOnly DAP parameter MUST be set to true. If the
control criticality value is TRUE then bit 17 of the DAP
criticalExtensions MUST be set.
(2) If an equality matching rule is specified in the filter of
the LDAPv3 search operation, then if operating with a pre-2000
edition DSA, the corresponding equality FilterItem contained in
the X.511 filter parameter MUST NOT be used, but rather the
extensibleMatch filter item MUST be used instead (the assertion
consisting of the equality matching rule, the attribute type to
match on, and the asserted value). When operating with DSAs
that support the 2000 DAP enhancement, the equality FilterItem
MAY be used.
4. Examples
(1) The first example simply shows how the control can be used to
selectively read a subset of attribute values.
The entry below represents a groupOfNames object class containing
several members from different organizations.
cn: Cross Organizational Standards Body
member: cn=joe, o=acme
member: cn=alice, o=acme
member: cn=bob, o=foo
member: cn=sue, o=bar
An LDAP search operation is specified with a baseObject set to the
DN of the entry, a baseObject scope, a filter set to
"member=*o=acme", and the list of attributes to be returned set to
"member". In addition, a matchedValuesOnly control is attached to the
search request.
The search results returned by the server would consist of the
following entry:
cn: Cross Organizational Standards Body
member: cn=joe, o=acme
member: cn=alice, o=acme
(2) The second example shows how the control has no effect on
attributes that do not participate in the search filter.
The entries below represent inetOrgPerson [7] object classes located
below some distinguished name in the directory.
cn: Sean Mullan
mail: sean.mullan@sun.com
mail: mullan@east.sun.com
telephoneNumber: +1 781 442 0926
telephoneNumber: 555-9999
cn: David Chadwick
mail: d.w.chadwick@salford.ac.uk
An LDAP search operation is specified with a baseObject set to the
DN of the entry, a subtree scope, a filter set to
"(|(mail=sean.mullan@sun.com)(mail=d.w.chadwick@salford.ac.uk))", and
the list of attributes to be returned set to "mail telephoneNumber".
In addition, a matchedValuesOnly control is attached to the search
request.
The search results returned by the server would consist of the
following entries:
cn: Sean Mullan
mail: sean.mullan@sun.com
telephoneNumber: +1 781 442 0926
telephoneNumber: 555-9999
cn: David Chadwick
mail: d.w.chadwick@salford.ac.uk
Note that the control has no effect on the values returned for the
"telephoneNumber" attribute (all of the values are returned), since
it did not participate in the search filter.
5. Security Considerations