From: Kurt Zeilenga Date: Fri, 18 Aug 2000 19:09:21 +0000 (+0000) Subject: Server Side Sorting now RFC2891 X-Git-Tag: LDBM_PRE_GIANT_RWLOCK~2226 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=43613d460b7dc31a36aa4edab114064ba5bd5590;p=openldap Server Side Sorting now RFC2891 --- diff --git a/doc/drafts/draft-ietf-ldapext-sorting-xx.txt b/doc/drafts/draft-ietf-ldapext-sorting-xx.txt deleted file mode 100644 index 6db7343359..0000000000 --- a/doc/drafts/draft-ietf-ldapext-sorting-xx.txt +++ /dev/null @@ -1,302 +0,0 @@ -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 - - - LDAP Control Extension for Server Side Sorting of Search Results - draft-ietf-ldapext-sorting-03.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 -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 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 . Please send -editorial comments directly to the authors. - -2. 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]. - -3. The Controls - -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 - -[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 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. - -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 -[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: - - 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 } - - -4. 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]. - -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. - -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. - -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 -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. - -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 -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. - - -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, 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. - - -7. References - -[LDAPv3] - 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. - -[LdapPaged] - 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 - -Tim Howes -Loudcloud, Inc. -615 Tasman Dr. -Sunnyvale, CA 94089 -USA -howes@loudcloud.com - -Mark Wahl -Sun Microsystems, Inc. -8911 Capital of Texas Hwy Suite 4140 -Austin, TX 78759 -USA -M.Wahl@innosoft.com - diff --git a/doc/rfc/INDEX b/doc/rfc/INDEX index b599d3b1e8..c3acca4354 100644 --- a/doc/rfc/INDEX +++ b/doc/rfc/INDEX @@ -47,6 +47,7 @@ rfc2829.txt LDAPv3: Authentication Methods (PS) rfc2830.txt LDAPv3: StartTLS (PS) rfc2831.txt SASL/DIGEST-MD5 (PS) rfc2849.txt LDIFv1 (PS) +rfc2891.txt LDAPv3: Server Side Sorting of Search Results (PS) Legend: STD Standard diff --git a/doc/rfc/rfc2891.txt b/doc/rfc/rfc2891.txt new file mode 100644 index 0000000000..1d91e07783 --- /dev/null +++ b/doc/rfc/rfc2891.txt @@ -0,0 +1,451 @@ + + + + + + +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] +