mirror of
https://git.openldap.org/openldap/openldap.git
synced 2024-12-09 02:52:04 +08:00
452 lines
16 KiB
Plaintext
452 lines
16 KiB
Plaintext
|
||
|
||
|
||
|
||
|
||
|
||
Network Working Group T. Howes
|
||
Request for Comments: 2891 Loudcloud
|
||
Category: Standards Track M. Wahl
|
||
Sun Microsystems
|
||
A. Anantha
|
||
Microsoft
|
||
August 2000
|
||
|
||
|
||
LDAP Control Extension for Server Side Sorting of Search Results
|
||
|
||
Status of this Memo
|
||
|
||
This document specifies an Internet standards track protocol for the
|
||
Internet community, and requests discussion and suggestions for
|
||
improvements. Please refer to the current edition of the "Internet
|
||
Official Protocol Standards" (STD 1) for the standardization state
|
||
and status of this protocol. Distribution of this memo is unlimited.
|
||
|
||
Copyright Notice
|
||
|
||
Copyright (C) The Internet Society (2000). All Rights Reserved.
|
||
|
||
Abstract
|
||
|
||
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 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 search operation.
|
||
|
||
The key words "MUST", "SHOULD", and "MAY" used in this document are
|
||
to be interpreted as described in [bradner97].
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Howes, et al. Standards Track [Page 1]
|
||
|
||
RFC 2891 LDAP Control Extension for Server Side Sorting August 2000
|
||
|
||
|
||
1. The Controls
|
||
|
||
1.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 "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,
|
||
whose value is the BER encoding of a value of the following SEQUENCE:
|
||
|
||
SortKeyList ::= SEQUENCE OF SEQUENCE {
|
||
attributeType AttributeDescription,
|
||
orderingRule [0] MatchingRuleId OPTIONAL,
|
||
reverseOrder [1] BOOLEAN DEFAULT FALSE }
|
||
|
||
The SortKeyList sequence is in order of highest to lowest sort key
|
||
precedence.
|
||
|
||
The MatchingRuleId, as defined in section 4.1.9 of [LDAPv3], 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
|
||
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.
|
||
|
||
Any conformant implementation of this control MUST allow a sort key
|
||
list with at least one key.
|
||
|
||
1.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 "1.2.840.113556.1.4.474". The criticality
|
||
is FALSE (MAY be absent). The controlValue is an OCTET STRING, whose
|
||
value is the BER encoding of a value of the following SEQUENCE:
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Howes, et al. Standards Track [Page 2]
|
||
|
||
RFC 2891 LDAP Control Extension for Server Side Sorting August 2000
|
||
|
||
|
||
SortResult ::= SEQUENCE {
|
||
sortResult ENUMERATED {
|
||
success (0), -- results are sorted
|
||
operationsError (1), -- server internal failure
|
||
timeLimitExceeded (3), -- timelimit reached before
|
||
-- sorting was completed
|
||
strongAuthRequired (8), -- refused to return sorted
|
||
-- results via insecure
|
||
-- protocol
|
||
adminLimitExceeded (11), -- too many matching entries
|
||
-- for the server to sort
|
||
noSuchAttribute (16), -- unrecognized attribute
|
||
-- type 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 }
|
||
|
||
2. Client-Server Interaction
|
||
|
||
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 key.
|
||
|
||
There are six possible scenarios that may occur as a result of the
|
||
sort 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 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 [LDAPv3].
|
||
|
||
|
||
|
||
Howes, et al. Standards Track [Page 3]
|
||
|
||
RFC 2891 LDAP Control Extension for Server Side Sorting August 2000
|
||
|
||
|
||
3 - If the server supports this sorting control but for some reason
|
||
cannot sort the search results using the specified sort keys and
|
||
the client specified TRUE for the control's criticality field,
|
||
then the server SHOULD do the following: return
|
||
unavailableCriticalExtension as a return code in the
|
||
searchResultDone message; include the sortKeyResponseControl in
|
||
the searchResultDone message, and not send back any search result
|
||
entries.
|
||
|
||
4 - If the server supports this sorting control but for some reason
|
||
cannot sort the search results using the specified sort keys and
|
||
the client specified FALSE for the control's criticality field,
|
||
then the server should return all search results unsorted and
|
||
include the sortKeyResponseControl in the searchResultDone
|
||
message.
|
||
|
||
5 - If the server supports this sorting control and can sort the
|
||
search results using the specified sort keys, then it should
|
||
include the sortKeyResponseControl in the searchResultDone
|
||
message with a sortResult of success.
|
||
|
||
6 - If the search request failed for any reason and/or there are no
|
||
searchResultEntry messages returned for the search response, then
|
||
the server SHOULD omit the sortKeyResponseControl from the
|
||
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 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
|
||
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 attributeType to the first attribute type specified in the
|
||
SortKeyList 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 keys because it may not recognize one of the attribute types,
|
||
the matching rule associated with an attribute type is not
|
||
applicable, or none of the attributes in the search response are of
|
||
these types. Servers may also restrict the number of keys allowed in
|
||
the control, such as only supporting a single key.
|
||
|
||
|
||
|
||
Howes, et al. Standards Track [Page 4]
|
||
|
||
RFC 2891 LDAP Control Extension for Server Side Sorting August 2000
|
||
|
||
|
||
Servers that chain requests to other LDAP servers should ensure that
|
||
the server satisfying the client's request sort the entire result set
|
||
prior to sending back the results.
|
||
|
||
2.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 or MUST return unwillingToPerform.
|
||
|
||
2.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.
|
||
|
||
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).
|
||
|
||
3. 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
|
||
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
|
||
send back a sortKeyResponseControl control on every searchResultDone
|
||
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.
|
||
|
||
|
||
|
||
|
||
|
||
Howes, et al. Standards Track [Page 5]
|
||
|
||
RFC 2891 LDAP Control Extension for Server Side Sorting August 2000
|
||
|
||
|
||
4. 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, 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
|
||
could use a combination of sorting and updating of search filters to
|
||
retrieve all records in a database in small result sets, thus
|
||
circumventing administrative limits.
|
||
|
||
This behavior can be overcome by the judicious use of permissions on
|
||
the directory entries by the administrator and by intelligent
|
||
implementations of administrative limits on the number of records
|
||
retrieved by a client.
|
||
|
||
5. References
|
||
|
||
[LDAPv3] Wahl, M, Kille, S. and T. Howes, "Lightweight Directory
|
||
Access Protocol (v3)", RFC 2251, December 1997.
|
||
|
||
[Bradner97] Bradner, S., "Key Words for use in RFCs to Indicate
|
||
Requirement Levels", BCP 14, RFC 2119, March 1997.
|
||
|
||
[LdapPaged] Weider, C., Herron, A., Anantha, A. and T. Howes, "LDAP
|
||
Control Extension for Simple Paged Results Manipulation",
|
||
RFC 2696, September 1999.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Howes, et al. Standards Track [Page 6]
|
||
|
||
RFC 2891 LDAP Control Extension for Server Side Sorting August 2000
|
||
|
||
|
||
6. Authors' Addresses
|
||
|
||
Anoop Anantha
|
||
Microsoft Corp.
|
||
1 Microsoft Way
|
||
Redmond, WA 98052
|
||
USA
|
||
|
||
Phone: +1 425 882-8080
|
||
EMail: anoopa@microsoft.com
|
||
|
||
|
||
Tim Howes
|
||
Loudcloud, Inc.
|
||
615 Tasman Dr.
|
||
Sunnyvale, CA 94089
|
||
USA
|
||
|
||
EMail: howes@loudcloud.com
|
||
|
||
|
||
Mark Wahl
|
||
Sun Microsystems, Inc.
|
||
8911 Capital of Texas Hwy Suite 4140
|
||
Austin, TX 78759
|
||
USA
|
||
|
||
EMail: Mark.Wahl@sun.com
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Howes, et al. Standards Track [Page 7]
|
||
|
||
RFC 2891 LDAP Control Extension for Server Side Sorting August 2000
|
||
|
||
|
||
7. Full Copyright Statement
|
||
|
||
Copyright (C) The Internet Society (2000). 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.
|
||
|
||
Acknowledgement
|
||
|
||
Funding for the RFC Editor function is currently provided by the
|
||
Internet Society.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Howes, et al. Standards Track [Page 8]
|
||
|