mirror of
https://git.openldap.org/openldap/openldap.git
synced 2024-12-21 03:10:25 +08:00
Add/Update LDAPext drafts
This commit is contained in:
parent
9ef1a740c2
commit
d8afb52b7e
412
doc/drafts/draft-ietf-ldapext-ldapv3-dupent-xx.txt
Normal file
412
doc/drafts/draft-ietf-ldapext-ldapv3-dupent-xx.txt
Normal file
@ -0,0 +1,412 @@
|
||||
|
||||
|
||||
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
|
307
doc/drafts/draft-ietf-ldapext-matchedval-xx.txt
Normal file
307
doc/drafts/draft-ietf-ldapext-matchedval-xx.txt
Normal file
@ -0,0 +1,307 @@
|
||||
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
|
||||
|
||||
This Internet Draft does not discuss security issues at all.
|
||||
|
||||
Note that attribute values MUST only be returned if the access
|
||||
controls applied by the LDAP server allow them to be returned, and in
|
||||
this respect the effect of the matchedValuesOnly control is of no
|
||||
consequence.
|
||||
|
||||
Note that the matchedValuesOnly control may have a positive effect on
|
||||
the deployment of public key infrastructures. Certain PKI operations,
|
||||
like searching for specific certificates, become more practical (when
|
||||
combined with X.509 certificate matching rules at the server) and
|
||||
more scalable, since the control avoids the downloading of
|
||||
potentially large numbers of irrelevant certificates which would have
|
||||
to be processed and filtered locally (which in some cases is very
|
||||
difficult to perform).
|
||||
|
||||
6. Copyright
|
||||
|
||||
Copyright (C) The Internet Society (date). All Rights Reserved.
|
||||
|
||||
This document and translations of it may be copied and furnished to
|
||||
others, and derivative works that comment on or otherwise explain it
|
||||
or assist in its implementation may be prepared, copied, published
|
||||
and distributed, in whole or in part, without restriction of any
|
||||
kind, provided that the above copyright notice and this paragraph are
|
||||
included on all such copies and derivative works. However, this
|
||||
document itself may not be modified in any way, such as by removing
|
||||
the copyright notice or references to the Internet Society or other
|
||||
Internet organizations, except as needed for the purpose of
|
||||
developing Internet standards in which case the procedures for
|
||||
copyrights defined in the Internet Standards process must be
|
||||
followed, or as required to translate it into languages other than
|
||||
English.
|
||||
|
||||
The limited permissions granted above are perpetual and will not be
|
||||
revoked by the Internet Society or its successors or assigns.
|
||||
|
||||
This document and the information contained herein is provided on an
|
||||
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
|
||||
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
|
||||
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
|
||||
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
|
||||
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
|
||||
|
||||
7. References
|
||||
|
||||
[1] Yeong, W., Howes, T., and Kille, S. "Lightweight Directory Access
|
||||
Protocol", RFC 1777, March 1995.
|
||||
[2] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
|
||||
Protocol (v3)", Dec. 1997, RFC 2251
|
||||
[3] M. Wahl, A. Coulbeck, T. Howes, S. Kille, ôLightweight Directory
|
||||
Access Protocol (v3): Attribute Syntax Definitionsö, RFC 2252, Dec
|
||||
1997
|
||||
[4] ITU-T Rec. X.511, "The Directory: Abstract Service Definition",
|
||||
1993.
|
||||
[5] S.Bradner. "Key words for use in RFCs to Indicate Requirement
|
||||
Levels", RFC 2119, March 1997.
|
||||
[6] ôFPDAMs to ISO/IEC 9594 Parts 1, 2, 3, 4, 5, 6, 7 and 9 to
|
||||
support the ITU-T Rec. F.510 "Automated Directory Assistance, White
|
||||
Pages Service Definitions"ö, Collaborative ITU-T/SG7/Q15 and
|
||||
JTC1/SC6/WG7 OSI Directory Meeting 7-15 April 1999, Orlando, USA
|
||||
[7] M. Smith. "Definition of the inetOrgPerson LDAP Object Class",
|
||||
Internet Draft <draft-smith-ldap-inetorgperson-03.txt>, April 1999.
|
||||
|
||||
8. Authors Addresses
|
||||
|
||||
David Chadwick
|
||||
IS Institute
|
||||
University of Salford
|
||||
Salford M5 4WT
|
||||
England
|
||||
|
||||
Email: d.w.chadwick@salford.ac.uk
|
||||
|
||||
Sean Mullan
|
||||
Sun Microsystems Laboratories
|
||||
One Network Drive
|
||||
Burlington
|
||||
MA 01803-0902
|
||||
USA
|
||||
|
||||
Tel: +1 781 442-0926 Fax: +1 781 442-1692
|
||||
Email: sean.mullan@sun.com
|
||||
|
||||
Internet-Draft Returning Matched Values with LDAPv3 8 September 1999
|
||||
|
||||
5
|
463
doc/drafts/draft-ietf-ldapext-psearch-xx.txt
Normal file
463
doc/drafts/draft-ietf-ldapext-psearch-xx.txt
Normal file
@ -0,0 +1,463 @@
|
||||
|
||||
Network Working Group M. Smith, Editor
|
||||
INTERNET-DRAFT G. Good
|
||||
Intended Category: Informational R. Weltman
|
||||
Expires: September 2000 Netscape Communications Corp.
|
||||
T. Howes
|
||||
Loudcloud, Inc.
|
||||
|
||||
7 March 2000
|
||||
|
||||
|
||||
Persistent Search: A Simple LDAP Change Notification Mechanism
|
||||
<draft-ietf-ldapext-psearch-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 docu-
|
||||
ments 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 draft document will be submitted to the RFC Editor as an Informa-
|
||||
tional document. Distribution of this memo is unlimited. Technical dis-
|
||||
cussion of this document will take place on the IETF LDAP Extension
|
||||
Working Group mailing list <ietf-ldapext@netscape.com>. Please send
|
||||
editorial comments directly to the editor <mcs@netscape.com>.
|
||||
|
||||
Copyright (C) The Internet Society (1997-2000). All Rights Reserved.
|
||||
|
||||
Please see the Copyright section near the end of this document for more
|
||||
information.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Smith, et. al. Intended Category: Informational [Page 1]
|
||||
|
||||
LDAP Persistent Search 7 March 2000
|
||||
|
||||
|
||||
2. Abstract
|
||||
|
||||
This document defines two controls that extend the LDAPv3 [LDAP] search
|
||||
operation to provide a simple mechanism by which an LDAP client can
|
||||
receive notification of changes that occur in an LDAP server. The
|
||||
mechanism is designed to be very flexible yet easy for clients and
|
||||
servers to implement. Since the IETF is likely to pursue a different,
|
||||
more comprehensive solution in this area, this document will eventually
|
||||
be published with Informational status in order to document an existing
|
||||
practice.
|
||||
|
||||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
|
||||
"SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
|
||||
to be interpreted as described in RFC 2119 [KEYWORDS].
|
||||
|
||||
|
||||
|
||||
3. General Approach
|
||||
|
||||
The approach taken by the Persistent Search mechanism described in this
|
||||
document is to alter the standard LDAP search operation so that it does
|
||||
not end after the initial set of entries matching the search criteria
|
||||
are returned. Instead, LDAP servers keep the search operation going.
|
||||
This provides clients and servers participating in Persistent Search
|
||||
with an active channel through which entries that change (and additional
|
||||
information about the changes that occur) can be communicated.
|
||||
|
||||
|
||||
|
||||
4. Persistent Search Control
|
||||
|
||||
This control may be included in the Controls portion of an LDAPv3 Sear-
|
||||
chRequest message. The controlType is "2.16.840.1.113730.3.4.3".
|
||||
|
||||
PersistentSearch ::= SEQUENCE {
|
||||
changeTypes INTEGER,
|
||||
changesOnly BOOLEAN,
|
||||
returnECs BOOLEAN
|
||||
}
|
||||
|
||||
Upon receiving this control, a server that supports it MUST process this
|
||||
as a standard LDAPv3 search with the following exceptions:
|
||||
|
||||
|
||||
a) If changesOnly is TRUE, the server MUST NOT return any existing
|
||||
entries that match the search criteria. Entries are only
|
||||
returned when they are changed (added, modified, deleted, or
|
||||
subject to a modifyDN operation).
|
||||
|
||||
|
||||
|
||||
Smith, et. al. Intended Category: Informational [Page 2]
|
||||
|
||||
LDAP Persistent Search 7 March 2000
|
||||
|
||||
|
||||
b) The server MUST NOT return a SearchResult message. Instead, the
|
||||
search operation MUST be kept active until it is abandoned by
|
||||
the client or until the client unbinds.
|
||||
|
||||
|
||||
c) As changes are made to the server, the effected entries MUST be
|
||||
returned to the client if they match the standard search cri-
|
||||
teria and if the operation that caused the change is included in
|
||||
the changeTypes field. The changeTypes field is the logical OR
|
||||
of one or more of these values: add (1), delete (2), modify (4),
|
||||
modDN (8).
|
||||
|
||||
|
||||
d) If returnECs is TRUE, the server MUST return an Entry Change
|
||||
Notification control with each entry returned as the result of
|
||||
changes. This control is described in the next section.
|
||||
|
||||
|
||||
|
||||
5. Entry Change Notification Control
|
||||
|
||||
This control provides additional information about the change the caused
|
||||
a particular entry to be returned as the result of a persistent search.
|
||||
The controlType is "2.16.840.1.113730.3.4.7". If the client set the
|
||||
returnECs boolean to TRUE in the PersistentSearch control, servers MUST
|
||||
include an EntryChangeNotification control in the Controls portion of
|
||||
each SearchResultEntry that is returned due to an entry being added,
|
||||
deleted, or modified.
|
||||
|
||||
EntryChangeNotification ::= SEQUENCE {
|
||||
changeType ENUMERATED {
|
||||
add (1),
|
||||
delete (2),
|
||||
modify (4),
|
||||
modDN (8)
|
||||
},
|
||||
previousDN LDAPDN OPTIONAL, -- modifyDN ops. only
|
||||
changeNumber INTEGER OPTIONAL -- if supported
|
||||
}
|
||||
|
||||
changeType indicates what LDAP operation caused the entry to be
|
||||
returned.
|
||||
|
||||
previousDN is present only for modifyDN operations and gives the DN of
|
||||
the entry before it was renamed and/or moved. Servers MUST include this
|
||||
optional field only when returning change notifications as a result of
|
||||
modifyDN operations.
|
||||
|
||||
|
||||
|
||||
|
||||
Smith, et. al. Intended Category: Informational [Page 3]
|
||||
|
||||
LDAP Persistent Search 7 March 2000
|
||||
|
||||
|
||||
changeNumber is the change number [CHANGELOG] assigned by a server for
|
||||
the change. If a server supports an LDAP Change Log it SHOULD include
|
||||
this field.
|
||||
|
||||
|
||||
|
||||
6. Intended Use
|
||||
|
||||
Some of the scenarios that the Persistent Search mechanism described in
|
||||
this document is designed to support are described in this section.
|
||||
Other uses of the mechanism are possible as well, but please refer to
|
||||
the "Implementation Considerations" section for some issues to consider.
|
||||
|
||||
|
||||
6.1. Cache Consistency
|
||||
|
||||
An LDAP client application with high performance needs may want to main-
|
||||
tain a temporary, local cache of information obtained through LDAP
|
||||
search, compare, or bind operations. To improve performance, the local
|
||||
cache is always consulted before sending a request to an LDAP server.
|
||||
The client application can use Persistent Search(es) against the change-
|
||||
log [CHANGELOG] (if one is available) or against one or more subtrees
|
||||
within the LDAP server to enable it to maintain consistency between the
|
||||
data in its local cache and the data stored in the LDAP server. A Per-
|
||||
sistent Search request where the changesOnly flag is FALSE can be used
|
||||
if it is desirable to prime the cache; otherwise changesOnly would typi-
|
||||
cally be set to TRUE in the request.
|
||||
|
||||
Caches are used for reasons other than performance improvement as well.
|
||||
In some cases, they arise naturally out of a particular application's
|
||||
design. For example, an LDAP client designed for administration of
|
||||
information held in LDAP servers will undoubtedly generate screen
|
||||
displays that show information gleaned from an LDAP server. The screen
|
||||
display is a cache that is active and visible until the user of the
|
||||
application takes some action that causes different information to be
|
||||
displayed. A refresh button or similar control may be provided to the
|
||||
user to allow them to update the cached display. A Persistent Search
|
||||
request can be used instead by the administrative application to
|
||||
automatically refresh the screen display as soon as the underlying LDAP
|
||||
information changes.
|
||||
|
||||
|
||||
6.2. Synchronization
|
||||
|
||||
Some LDAP clients such as those that execute on a portable computer may
|
||||
maintain a partial or complete offline copy of the entries stored in an
|
||||
LDAP server. While connected to the network, such a client can direct
|
||||
all queries to the copy of data it holds and use a Persistent Search to
|
||||
|
||||
|
||||
|
||||
Smith, et. al. Intended Category: Informational [Page 4]
|
||||
|
||||
LDAP Persistent Search 7 March 2000
|
||||
|
||||
|
||||
actively maintain the contents of the offline copy (alternatively, the
|
||||
client could direct requests to the LDAP server that is the source of
|
||||
the data). While disconnected from the network, the client must satisfy
|
||||
all queries using its offline copy of the data. When the client recon-
|
||||
nects to the network, it can synchronize its own copy of the data with
|
||||
the one stored on the LDAP server and proceed to actively maintain its
|
||||
offline copy by issuing a Persistent Search with the changesOnly flag
|
||||
set to FALSE against the server's changelog [CHANGELOG]. A search
|
||||
filter like "(changeNumber>=NUM)" where NUM is an integer one greater
|
||||
than the last change the client processed would be used to limit the
|
||||
entries returned to the set of changes the client has not yet seen.
|
||||
|
||||
|
||||
6.3. Triggered Actions
|
||||
|
||||
An LDAP client application may want to take some action when an entry in
|
||||
the directory is changed. A Persistent Search request can be used to
|
||||
proactively monitor one or more LDAP servers for interesting changes
|
||||
that in turn cause specific actions to be taken by an application. For
|
||||
example, an electronic mail repository may want to perform a "create
|
||||
mailbox" task when a new person entry is added to an LDAP directory and
|
||||
a "delete mailbox" task when a person entry is deleted from an LDAP
|
||||
directory.
|
||||
|
||||
|
||||
|
||||
7. Implementation Considerations
|
||||
|
||||
Implementors of servers that support the mechanism described in this
|
||||
document should ensure that their implementation scales well as the
|
||||
number of active Persistent Search requests increases and as the number
|
||||
of changes made in the directory increases.
|
||||
|
||||
Each active Persistent Search request requires that an open TCP connec-
|
||||
tion be maintained between an LDAP client and an LDAP server that might
|
||||
not otherwise be kept open. Therefore, client implementors are
|
||||
encouraged to avoid using Persistent Search for non-essential tasks and
|
||||
to close idle LDAP connections as soon as practical. Server implemen-
|
||||
tors are encouraged to support a large number of client connections if
|
||||
they need to support large numbers of Persistent Search clients.
|
||||
|
||||
|
||||
This specification makes no guarantees about how soon a server should
|
||||
send notification of a changed entry to a Persistent Search client.
|
||||
This is intentional as any specific maximum delay would be impossible to
|
||||
meet in a distributed directory service implementation. Server imple-
|
||||
mentors are encouraged to minimize the delay before sending notifica-
|
||||
tions to ensure that clients' needs for timeliness of change
|
||||
|
||||
|
||||
|
||||
Smith, et. al. Intended Category: Informational [Page 5]
|
||||
|
||||
LDAP Persistent Search 7 March 2000
|
||||
|
||||
|
||||
notification are met.
|
||||
|
||||
|
||||
|
||||
8. Security Considerations
|
||||
|
||||
In some situations, it may be important to prevent general exposure of
|
||||
information about changes that occur in an LDAP server. Therefore,
|
||||
servers that implement the mechanism described in this document SHOULD
|
||||
provide a means to enforce access control on the entries returned and
|
||||
MAY also provide specific access control mechanisms to control the use
|
||||
of the PersistentSearch and EntryChangeNotification controls.
|
||||
|
||||
|
||||
As with normal LDAP search requests, a malicious client can initiate a
|
||||
large number of Persistent Search requests in an attempt to consume all
|
||||
available server resources and deny service to legitimate clients. For
|
||||
this reason, servers that implement the mechanism described in the docu-
|
||||
ment SHOULD provide a means to limit the number of resources that can be
|
||||
consumed by a single client.
|
||||
|
||||
|
||||
|
||||
9. Copyright
|
||||
|
||||
Copyright (C) The Internet Society (1997-2000). All Rights Reserved.
|
||||
|
||||
This document and translations of it may be copied and furnished to oth-
|
||||
ers, and derivative works that comment on or otherwise explain it or
|
||||
assist in its implementation may be prepared, copied, published and dis-
|
||||
tributed, in whole or in part, without restriction of any kind, provided
|
||||
that the above copyright notice and this paragraph are included on all
|
||||
such copies and derivative works. However, this document itself may not
|
||||
be modified in any way, such as by removing the copyright notice or
|
||||
references to the Internet Society or other Internet organizations,
|
||||
except as needed for the purpose of developing Internet standards in
|
||||
which case the procedures for copyrights defined in the Internet Stan-
|
||||
dards process must be followed, or as required to translate it into
|
||||
languages other than English.
|
||||
|
||||
The limited permissions granted above are perpetual and will not be
|
||||
revoked by the Internet Society or its successors or assigns.
|
||||
|
||||
This document and the information contained herein is provided on an "AS
|
||||
IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK
|
||||
FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT
|
||||
LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT
|
||||
INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR
|
||||
|
||||
|
||||
|
||||
Smith, et. al. Intended Category: Informational [Page 6]
|
||||
|
||||
LDAP Persistent Search 7 March 2000
|
||||
|
||||
|
||||
FITNESS FOR A PARTICULAR PURPOSE.
|
||||
|
||||
|
||||
|
||||
10. Bibliography
|
||||
|
||||
[KEYWORDS] S. Bradner, "Key words for use in RFCs to Indicate Require-
|
||||
ment Levels", RFC 2119, March 1997.
|
||||
|
||||
[LDAP] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
|
||||
Protocol (v3)", RFC 2251, December 1997.
|
||||
|
||||
[CHANGELOG] G. Good, "Definition of an Object Class to Hold LDAP Change
|
||||
Record", INTERNET-DRAFT <draft-ietf-asid-changelog-01.txt>,
|
||||
July 1997.
|
||||
|
||||
[PSEARCHAPI] M. Smith, "LDAP C API Extensions for Persistent Search",
|
||||
INTERNET-DRAFT <draft-ietf-ldapext-c-api-psearch-00.txt>,
|
||||
March 1998.
|
||||
|
||||
|
||||
|
||||
11. Authors' Addresses
|
||||
|
||||
Mark Smith
|
||||
Netscape Communications Corp.
|
||||
501 E. Middlefield Rd., Mailstop MV068
|
||||
Mountain View, CA 94043
|
||||
USA
|
||||
+1 650 937-3477
|
||||
mcs@netscape.com
|
||||
|
||||
Gordon Good
|
||||
Netscape Communications Corp.
|
||||
501 E. Middlefield Rd., Mailstop MV068
|
||||
Mountain View, CA 94043
|
||||
USA
|
||||
+1 650 937-3825
|
||||
ggood@netscape.com
|
||||
|
||||
Rob Weltman
|
||||
Netscape Communications Corp.
|
||||
501 E. Middlefield Rd., Mailstop MV068
|
||||
Mountain View, CA 94043
|
||||
USA
|
||||
+1 650 937-3301
|
||||
rweltman@netscape.com
|
||||
|
||||
|
||||
|
||||
|
||||
Smith, et. al. Intended Category: Informational [Page 7]
|
||||
|
||||
LDAP Persistent Search 7 March 2000
|
||||
|
||||
|
||||
Tim Howes
|
||||
Loudcloud, Inc.
|
||||
615 Tasman Dr.
|
||||
Sunnyvale, CA 94089
|
||||
USA
|
||||
+1 650 321 4565
|
||||
howes@loudcloud.com
|
||||
|
||||
|
||||
|
||||
12. Appendix A: Changes since draft-ietf-ldapext-psearch-01.txt
|
||||
|
||||
"Status of this Memo" section: changed "Intended Category" to Infor-
|
||||
mational. Also updated boilerplate text to reflect current I-D
|
||||
guidelines and updated copyright to include the year "2000."
|
||||
|
||||
"Abstract" section: added sentence that says why this will be pub-
|
||||
lished as Informational.
|
||||
|
||||
"Entry Change Notification Control" section: added the word "only" to
|
||||
clarify that the previousDN field is only returned for modifyDN
|
||||
operations.
|
||||
|
||||
"Authors' Addresses" section: updated Tim Howes' information.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Smith, et. al. Intended Category: Informational [Page 8]
|
||||
|
||||
|
||||
|
||||
1. Status of this Memo............................................1
|
||||
2. Abstract.......................................................2
|
||||
3. General Approach...............................................2
|
||||
4. Persistent Search Control......................................2
|
||||
5. Entry Change Notification Control..............................3
|
||||
6. Intended Use...................................................4
|
||||
6.1. Cache Consistency...........................................4
|
||||
6.2. Synchronization.............................................4
|
||||
6.3. Triggered Actions...........................................5
|
||||
7. Implementation Considerations..................................5
|
||||
8. Security Considerations........................................6
|
||||
9. Copyright......................................................6
|
||||
10. Bibliography...................................................7
|
||||
11. Authors' Addresses.............................................7
|
||||
12. Appendix A: Changes since draft-ietf-ldapext-psearch-01.txt...8
|
@ -1,45 +1,50 @@
|
||||
Network Working Group T. Howes, Netscape
|
||||
INTERNET DRAFT M. Wahl, Critical Angle Inc
|
||||
Intended Category: Standards Track A. Anantha, Microsoft
|
||||
Expires: December 5, 2000 June 5, 2000
|
||||
|
||||
Network Working Group A. Herron, Microsoft
|
||||
INTERNET DRAFT T. Howes, Netscape
|
||||
Expire in six months M. Wahl, Critical Angle Inc
|
||||
A. Anantha, Microsoft
|
||||
April 5, 1999
|
||||
|
||||
LDAP Control Extension for Server Side Sorting of Search Results
|
||||
draft-ietf-ldapext-sorting-02.txt
|
||||
draft-ietf-ldapext-sorting-03.txt
|
||||
|
||||
|
||||
1. Status of this Memo
|
||||
|
||||
This document is an Internet-Draft. Internet-Drafts are working docu-
|
||||
ments of the Internet Engineering Task Force (IETF), its areas, and its
|
||||
working groups. Note that other groups may also distribute working
|
||||
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.''
|
||||
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).
|
||||
The list of current Internet-Drafts can be accessed at
|
||||
http://www.ietf.org/ietf/1id-abstracts.txt.
|
||||
|
||||
This document expires on October 5, 1999.
|
||||
The list of Internet-Draft Shadow Directories can be accessed at
|
||||
http://www.ietf.org/shadow.html.
|
||||
|
||||
This draft document will be submitted to the RFC Editor as a Standards
|
||||
Track document. Distribution of this memo is unlimited. Technical
|
||||
discussion of this document will take place on the IETF LDAP Extension
|
||||
Working Group mailing list <ietf-ldapext@netscape.com>. Please send
|
||||
editorial comments directly to the authors.
|
||||
|
||||
2. Abstract
|
||||
|
||||
This document describes two LDAPv3 control extensions for server side
|
||||
This document describes two LDAPv3 control extensions for server side
|
||||
sorting of search results. These controls allows a client to specify the
|
||||
attribute types and matching rules a server should use when returning
|
||||
the results to an LDAP search request. The controls may be useful when
|
||||
the LDAP client has limited functionality or for some other reason
|
||||
cannot sort the results but still needs them sorted. Other permissible
|
||||
attribute types and matching rules a server should use when returning
|
||||
the results to an LDAP search request. The controls may be useful when
|
||||
the LDAP client has limited functionality or for some other reason
|
||||
cannot sort the results but still needs them sorted. Other permissible
|
||||
controls on search operations are not defined in this extension.
|
||||
|
||||
The sort controls allow a server to return a result code for the sorting
|
||||
of the results that is independent of the result code returned for the
|
||||
of the results that is independent of the result code returned for the
|
||||
search operation.
|
||||
|
||||
The key words "MUST", "SHOULD", and "MAY" used in this document are to
|
||||
@ -49,13 +54,14 @@ be interpreted as described in [bradner97].
|
||||
|
||||
3.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
|
||||
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 "1.2.840.113556.1.4.473". The criticality
|
||||
MAY be either TRUE or FALSE (where absent is also equivalent to
|
||||
FALSE) at the client's option. The controlValue is an OCTET STRING,
|
||||
FALSE) at the client's option. The controlValue is an OCTET STRING,
|
||||
whose value is the BER encoding of a value of the following SEQUENCE:
|
||||
|
||||
SortKeyList ::= SEQUENCE OF SEQUENCE {
|
||||
@ -66,27 +72,27 @@ whose value is the BER encoding of a value of the following SEQUENCE:
|
||||
The SortKeyList sequence is in order of highest to lowest sort key
|
||||
precedence.
|
||||
|
||||
The MatchingRuleID SHOULD be one that is valid for the attribute type
|
||||
it applies to. If it is not, the server MUST return unwillingToPerform.
|
||||
The MatchingRuleID SHOULD be one that is valid for the attribute type it
|
||||
applies to. If it is not, the server will return inappropriateMatching.
|
||||
|
||||
Each attributeType should only occur in the SortKeyList once. If an
|
||||
attributeType is included in the sort key list multiple times, the
|
||||
Each attributeType should only occur in the SortKeyList once. If an
|
||||
attributeType is included in the sort key list multiple times, the
|
||||
server should return an error in the sortResult of unwillingToPerform.
|
||||
|
||||
If the orderingRule is omitted, the ordering MatchingRule defined for use
|
||||
with this attribute MUST be used.
|
||||
If the orderingRule is omitted, the ordering MatchingRule defined for
|
||||
use with this attribute MUST be used.
|
||||
|
||||
Any conformant implementation of this control MUST allow a sort key
|
||||
list with at least one key.
|
||||
Any conformant implementation of this control MUST allow a sort key list
|
||||
with at least one key.
|
||||
|
||||
3.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
|
||||
controls field of the LDAPMessage, as defined in Section 4.1.12 of
|
||||
[LDAPv3].
|
||||
|
||||
The controlType is set to "1.2.840.113556.1.4.474". The criticality is
|
||||
FALSE (MAY be absent). The controlValue is an OCTET STRING, whose
|
||||
FALSE (MAY be absent). The controlValue is an OCTET STRING, whose
|
||||
value is the BER encoding of a value of the following SEQUENCE:
|
||||
|
||||
SortResult ::= SEQUENCE {
|
||||
@ -102,24 +108,26 @@ value is the BER encoding of a value of the following SEQUENCE:
|
||||
-- for the server to sort
|
||||
noSuchAttribute (16), -- unrecognized attribute
|
||||
-- type in sort key
|
||||
inappropriateMatching (18), -- unrecognized or inappro-
|
||||
-- priate matching rule in
|
||||
-- sort key
|
||||
inappropriateMatching (18), -- unrecognized or
|
||||
-- inappropriate matching
|
||||
-- rule in sort key
|
||||
insufficientAccessRights (50), -- refused to return sorted
|
||||
-- results to this client
|
||||
busy (51), -- too busy to process
|
||||
|
||||
unwillingToPerform (53), -- unable to sort
|
||||
other (80)
|
||||
},
|
||||
attributeType [0] AttributeDescription OPTIONAL }
|
||||
|
||||
|
||||
4. Client-Server Interaction
|
||||
|
||||
The sortKeyRequestControl specifies one or more attribute types and
|
||||
The sortKeyRequestControl specifies one or more attribute types and
|
||||
matching rules for the results returned by a search request. The server
|
||||
SHOULD return all results for the search request in the order specified
|
||||
by the sort keys. If the reverseOrder field is set to TRUE, then the
|
||||
entries will be presented in reverse sorted order for the specified
|
||||
by the sort keys. If the reverseOrder field is set to TRUE, then the
|
||||
entries will be presented in reverse sorted order for the specified
|
||||
key.
|
||||
|
||||
There are six possible scenarios that may occur as a result of the sort
|
||||
@ -128,13 +136,13 @@ control being included on the search request :
|
||||
1 - If the server does not support this sorting control and the client
|
||||
specified TRUE for the control's criticality field, then the server
|
||||
MUST return unavailableCriticalExtension as a return code in the
|
||||
searchResultDone message and not send back any other results. This
|
||||
searchResultDone message and not send back any other results. This
|
||||
behavior is specified in section 4.1.12 of [LDAPv3].
|
||||
|
||||
2 - If the server does not support this sorting control and the client
|
||||
specified FALSE for the control's criticality field, then the server
|
||||
MUST ignore the sort control and process the search request as if it
|
||||
were not present. This behavior is specified in section 4.1.12 of
|
||||
were not present. This behavior is specified in section 4.1.12 of
|
||||
[LDAPv3].
|
||||
|
||||
3 - If the server supports this sorting control but for some reason
|
||||
@ -163,18 +171,19 @@ searchResultDone message.
|
||||
|
||||
The client application is assured that the results are sorted in the
|
||||
specified key order if and only if the result code in the
|
||||
sortKeyResponseControl is success. If the server omits the
|
||||
sortKeyResponseControl is success. If the server omits the
|
||||
|
||||
sortKeyResponseControl from the searchResultDone message, the client
|
||||
SHOULD assume that the sort control was ignored by the server.
|
||||
|
||||
The sortKeyResponseControl, if included by the server in the
|
||||
searchResultDone message, should have the sortResult set to either
|
||||
success if the results were sorted in accordance with the keys
|
||||
success if the results were sorted in accordance with the keys
|
||||
specified in the sortKeyRequestControl or set to the appropriate error
|
||||
code as to why it could not sort the data (such as noSuchAttribute or
|
||||
inappropriateMatching). Optionally, the server MAY set the
|
||||
inappropriateMatching). Optionally, the server MAY set the
|
||||
attributeType to the first attribute type specified in the SortKeyList
|
||||
that was in error. The client SHOULD ignore the attributeType field if
|
||||
that was in error. The client SHOULD ignore the attributeType field if
|
||||
the sortResult is success.
|
||||
|
||||
The server may not be able to sort the results using the specified sort
|
||||
@ -190,53 +199,54 @@ prior to sending back the results.
|
||||
|
||||
4.1 Behavior in a chained environment
|
||||
|
||||
If a server receives a sort request, the client expects to receive a
|
||||
set of sorted results. If a client submits a sort request to a server
|
||||
which chains the request and gets entries from multiple servers, and
|
||||
the client has set the criticality of the sort extension to TRUE, the
|
||||
server MUST merge sort the results before returning them to the client
|
||||
If a server receives a sort request, the client expects to receive a
|
||||
set of sorted results. If a client submits a sort request to a server
|
||||
which chains the request and gets entries from multiple servers, and
|
||||
the client has set the criticality of the sort extension to TRUE, the
|
||||
server MUST merge sort the results before returning them to the client
|
||||
or MUST return unwillingToPerform.
|
||||
|
||||
4.2 Other sort issues
|
||||
|
||||
An entry that meets the search criteria may be missing one or more of
|
||||
the sort keys. In that case, the entry is considered to have a value of
|
||||
NULL for that key. This standard considers NULL to be a larger value
|
||||
than all other valid values for that key. For example, if only one key
|
||||
is specified, entries which meet the search criteria but do not have
|
||||
that key collate after all the entries which do have that key. If the
|
||||
reverseOrder flag is set, and only one key is specified, entries which
|
||||
meet the search criteria but do not have that key collate BEFORE all
|
||||
the entries which do have that key.
|
||||
An entry that meets the search criteria may be missing one or more of
|
||||
the sort keys. In that case, the entry is considered to have a value of
|
||||
NULL for that key. This standard considers NULL to be a larger value
|
||||
than all other valid values for that key. For example, if only one key
|
||||
is specified, entries which meet the search criteria but do not have
|
||||
that key collate after all the entries which do have that key. If the
|
||||
reverseOrder flag is set, and only one key is specified, entries which
|
||||
meet the search criteria but do not have that key collate BEFORE all
|
||||
the entries which do have that key.
|
||||
|
||||
If a sort key is a multi-valued attribute, and an entry happens to have
|
||||
multiple values for that attribute and no other controls are present that
|
||||
affect the sorting order, then the server SHOULD use the least value
|
||||
(according to the ORDERING rule for that attribute).
|
||||
If a sort key is a multi-valued attribute, and an entry happens to have
|
||||
multiple values for that attribute and no other controls are present
|
||||
that affect the sorting order, then the server SHOULD use the least
|
||||
value (according to the ORDERING rule for that attribute).
|
||||
|
||||
5. Interaction with other search controls
|
||||
|
||||
When the sortKeyRequestControl control is included with the
|
||||
pagedResultsControl control as specified in [LdapPaged], then the
|
||||
server should send the searchResultEntry messages sorted according to
|
||||
the sort keys applied to the entire result set. The server should not
|
||||
the sort keys applied to the entire result set. The server should not
|
||||
simply sort each page, as this will give erroneous results to the
|
||||
|
||||
client.
|
||||
|
||||
The sortKeyList must be present on each searchRequest message for the
|
||||
paged result. It also must not change between searchRequests for the
|
||||
same result set. If the server has sorted the data, then it SHOULD
|
||||
paged result. It also must not change between searchRequests for the
|
||||
same result set. If the server has sorted the data, then it SHOULD
|
||||
send back a sortKeyResponseControl control on every searchResultDone
|
||||
message for each page. This will allow clients to quickly determine
|
||||
message for each page. This will allow clients to quickly determine
|
||||
if the result set is sorted, rather than waiting to receive the entire
|
||||
result set.
|
||||
|
||||
|
||||
6. Security Considerations
|
||||
|
||||
Implementors and administrators should be aware that allowing sorting
|
||||
of results could enable the retrieval of a large number of records from
|
||||
a given directory service, irregardless of administrative limits set on
|
||||
Implementors and administrators should be aware that allowing sorting of
|
||||
results could enable the retrieval of a large number of records from
|
||||
a given directory service, regardless of administrative limits set on
|
||||
the maximum number of records to return.
|
||||
|
||||
A client that desired to pull all records out of a directory service
|
||||
@ -253,51 +263,40 @@ retrieved by a client.
|
||||
7. References
|
||||
|
||||
[LDAPv3]
|
||||
Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access
|
||||
Pro-
|
||||
tocol (v3)", RFC 2251, December, 1997.
|
||||
Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access
|
||||
Protocol (v3)", RFC 2251, December, 1997.
|
||||
|
||||
[Bradner97]
|
||||
Bradner, Scott, "Key Words for use in RFCs to Indicate
|
||||
Requirement
|
||||
Levels", RFC 2119, March, 1997.
|
||||
Bradner, Scott, "Key Words for use in RFCs to Indicate Requirement
|
||||
Levels", RFC 2119, March, 1997.
|
||||
|
||||
[LdapPaged]
|
||||
C. Weider, A. Herron, and T. Howes, "LDAP Control Extension for
|
||||
Simple Paged Results Manipulation", Internet Draft, February, 1997.
|
||||
Available as draft-ietf-asid-ldapv3-simplepaged-00.txt.
|
||||
C. Weider, A. Herron, A. Anantha and T. Howes, "LDAP Control
|
||||
Extension for Simple Paged Results Manipulation", RFC 2696,
|
||||
September 1999.
|
||||
|
||||
|
||||
8. Author's Address
|
||||
|
||||
Anoop Anantha
|
||||
Microsoft Corp.
|
||||
1 Microsoft Way
|
||||
Redmond, WA 98052
|
||||
USA
|
||||
Anoopa@microsoft.com
|
||||
+1 425 882-8080
|
||||
|
||||
Andy Herron
|
||||
Microsoft Corp.
|
||||
1 Microsoft Way
|
||||
Redmond, WA 98052
|
||||
USA
|
||||
andyhe@microsoft.com
|
||||
+1 425 882-8080
|
||||
Anoop Anantha
|
||||
Microsoft Corp.
|
||||
1 Microsoft Way
|
||||
Redmond, WA 98052
|
||||
USA
|
||||
anoopa@microsoft.com
|
||||
+1 425 882-8080
|
||||
|
||||
Tim Howes
|
||||
Loudcloud, Inc.
|
||||
615 Tasman Dr.
|
||||
Sunnyvale, CA 94089
|
||||
USA
|
||||
howes@loudcloud.com
|
||||
|
||||
Tim Howes
|
||||
Netscape Communications Corp.
|
||||
501 E. Middlefield Road
|
||||
Mountain View, CA 94043
|
||||
USA
|
||||
howes@netscape.com
|
||||
+1 415 937-2600
|
||||
Mark Wahl
|
||||
Sun Microsystems, Inc.
|
||||
8911 Capital of Texas Hwy Suite 4140
|
||||
Austin, TX 78759
|
||||
USA
|
||||
M.Wahl@innosoft.com
|
||||
|
||||
Mark Wahl
|
||||
Critical Angle Inc.
|
||||
4815 W Braker Lane #502-385
|
||||
Austin, TX 78759
|
||||
USA
|
||||
M.Wahl@critical-angle.com
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user