Network Working Group T. Howes
Request for Comments: 2891 Loudcloud
Category: Standards Track M. Wahl
Sun Microsystems
A. Anantha
Microsoft
August 2000
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
用于搜索结果服务器端排序的LDAP控件扩展
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.
本文件规定了互联网社区的互联网标准跟踪协议，并要求进行讨论和提出改进建议。有关本协议的标准化状态和状态，请参考当前版本的“互联网官方协议标准”（STD 1）。本备忘录的分发不受限制。
Copyright Notice
版权公告
Copyright (C) The Internet Society (2000). All Rights Reserved.
版权所有（C）互联网协会（2000年）。版权所有。
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.
本文档描述了用于搜索结果服务器端排序的两个LDAPv3控件扩展。这些控件允许客户端指定服务器在将结果返回到LDAP搜索请求时应使用的属性类型和匹配规则。当LDAP客户端功能有限或由于某些其他原因无法对结果进行排序但仍需要对其进行排序时，这些控件可能很有用。本扩展中未定义搜索操作的其他允许控制。
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].
本文件中使用的关键词“必须”、“应该”和“可能”应按照[bradner97]中所述进行解释。
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].
如[LDAPv3]第4.1.12节所定义，该控件作为LDAPMessage控件字段的一部分包含在searchRequest消息中。
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:
控制类型设置为“1.2.840.113556.1.4.473”。关键性可以是真的，也可以是假的（如果不存在也等于假），由客户选择。controlValue是一个八位字符串，其值是以下序列值的BER编码：
SortKeyList ::= SEQUENCE OF SEQUENCE {
attributeType AttributeDescription,
orderingRule [0] MatchingRuleId OPTIONAL,
reverseOrder [1] BOOLEAN DEFAULT FALSE }
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.
SortKeyList序列按排序键优先级从高到低的顺序排列。
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.
[LDAPv3]第4.1.9节中定义的MatchingRuleId应该对其应用的属性类型有效。如果不是，服务器将返回不适当的匹配。
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.
每个attributeType只能在SortKeyList中出现一次。如果attributeType多次包含在排序键列表中，服务器应在UnwillingOperForm的sortResult中返回一个错误。
If the orderingRule is omitted, the ordering MatchingRule defined for use with this attribute MUST be used.
如果省略orderingRule，则必须使用为与此属性一起使用而定义的OrderingMatchingRule。
Any conformant implementation of this control MUST allow a sort key list with at least one key.
此控件的任何一致性实现都必须允许至少有一个键的排序键列表。
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].
此控件包含在SearchResultOne消息中，作为LDAPMessage控件字段的一部分，如[LDAPv3]第4.1.12节所定义。
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:
控制类型设置为“1.2.840.113556.1.4.474”。临界值为假（可能不存在）。controlValue是一个八位字符串，其值是以下序列值的BER编码：
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 }
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 }
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.
sortKeyRequestControl为搜索请求返回的结果指定一个或多个属性类型和匹配规则。服务器应按照排序键指定的顺序返回搜索请求的所有结果。如果reverseOrder字段设置为TRUE，则条目将按指定键的反向排序顺序显示。
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].
1-如果服务器不支持此排序控件，并且客户端为控件的关键性字段指定了TRUE，则服务器必须在SearchResultOne消息中返回unavailableCriticalExtension作为返回代码，并且不发送任何其他结果。[LDAPv3]第4.1.12节规定了该行为。
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].
2-如果服务器不支持此排序控件，并且客户端为控件的关键性字段指定了FALSE，则服务器必须忽略排序控件并处理搜索请求，就像它不存在一样。[LDAPv3]第4.1.12节规定了该行为。
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.
3-如果服务器支持此排序控件，但由于某种原因无法使用指定的排序键和客户端为控件的关键性字段指定的TRUE对搜索结果进行排序，则服务器应执行以下操作：在SearchResultOne消息中返回unavailableCriticalExtension作为返回代码；在SearchResultOne消息中包含sortKeyResponseControl，并且不发回任何搜索结果条目。
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.
4-如果服务器支持此排序控件，但由于某种原因无法使用指定的排序键和客户端为控件的关键性字段指定的FALSE对搜索结果进行排序，则服务器应返回所有未排序的搜索结果，并在SearchResultOne消息中包含sortKeyResponseControl。
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.
5-如果服务器支持此排序控件，并且可以使用指定的排序键对搜索结果进行排序，那么它应该在SearchResultOne消息中包含sortKeyResponseControl，并显示sortResult成功。
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.
6-如果搜索请求因任何原因失败和/或没有为搜索响应返回searchResultEntry消息，则服务器应从SearchResultOne消息中省略sortKeyResponseControl。
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.
当且仅当sortKeyResponseControl中的结果代码成功时，客户端应用程序才能确保结果按指定的键顺序排序。如果服务器从SearchResultOne消息中忽略了sortKeyResponseControl，则客户端应假定服务器忽略了排序控制。
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.
如果服务器在SearchResultOne消息中包含sortKeyResponseControl，则如果结果按照sortKeyRequestControl中指定的键进行排序，则sortResult应设置为success，或者设置为相应的错误代码，说明其无法对数据进行排序的原因（例如noSuchAttribute或不适当的匹配）。或者，服务器可以将attributeType设置为在SortKeyList中指定的第一个出错的属性类型。如果sortResult成功，客户端应忽略attributeType字段。
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.
将请求链接到其他LDAP服务器的服务器应确保满足客户端请求的服务器在返回结果之前对整个结果集进行排序。
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.
如果服务器收到排序请求，则客户端希望收到一组排序结果。如果客户端向服务器提交排序请求，该服务器链接该请求并从多个服务器获取条目，并且客户端已将排序扩展的临界性设置为TRUE，则服务器必须在将结果返回到客户端之前合并排序结果，或者必须返回不愿意的操作。
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.
符合搜索条件的条目可能缺少一个或多个排序键。在这种情况下，该项被认为具有该键的NULL值。此标准认为NULL的值大于该键的所有其他有效值。例如，如果只指定了一个键，则符合搜索条件但没有该键的条目将在所有具有该键的条目之后进行排序。如果设置了reverseOrder标志，并且只指定了一个键，则符合搜索条件但没有该键的条目将在所有具有该键的条目之前进行排序。
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).
如果排序键是多值属性，并且一个条目恰好具有该属性的多个值，并且不存在影响排序顺序的其他控件，则服务器应使用最小值（根据该属性的排序规则）。
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.
当[LdapPaged]中指定的pagedResultsControl控件包含sortKeyRequestControl控件时，服务器应发送根据应用于整个结果集的排序键排序的searchResultEntry消息。服务器不应该简单地对每个页面进行排序，因为这会给客户端带来错误的结果。
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.
对于分页结果，sortKeyList必须出现在每个searchRequest消息上。它也不能在同一结果集的搜索请求之间更改。如果服务器已经对数据进行了排序，那么它应该在每个页面的每个SearchResultOne消息上返回一个sortKeyResponseControl控件。这将允许客户端快速确定结果集是否已排序，而不是等待接收整个结果集。
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.
通过管理员明智地使用目录项的权限，以及智能地实现对客户端检索的记录数的管理限制，可以克服这种行为。
[LDAPv3] Wahl, M, Kille, S. and T. Howes, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997.
[LDAPv3]Wahl，M，Kille，S.和T.Howes，“轻量级目录访问协议（v3）”，RFC 2251，1997年12月。
[Bradner97] Bradner, S., "Key Words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[Bradner97]Bradner，S.，“RFC中用于表示需求水平的关键词”，BCP 14，RFC 2119，1997年3月。
[LdapPaged] Weider, C., Herron, A., Anantha, A. and T. Howes, "LDAP Control Extension for Simple Paged Results Manipulation", RFC 2696, September 1999.
[LdapPaged]Weider，C.，Herron，A.，Anantha，A.和T.Howes，“用于简单分页结果操作的LDAP控件扩展”，RFC 26961999年9月。
Anoop Anantha Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA
Anoop Anantha微软公司美国华盛顿州雷德蒙微软路1号，邮编：98052
Phone: +1 425 882-8080
EMail: anoopa@microsoft.com
Phone: +1 425 882-8080
EMail: anoopa@microsoft.com
Tim Howes Loudcloud, Inc. 615 Tasman Dr. Sunnyvale, CA 94089 USA
Tim Howes Loudcloud，Inc.美国加利福尼亚州桑尼维尔市塔斯曼博士615号，邮编94089
EMail: howes@loudcloud.com
EMail: howes@loudcloud.com
Mark Wahl Sun Microsystems, Inc. 8911 Capital of Texas Hwy Suite 4140 Austin, TX 78759 USA
Mark Wahl Sun Microsystems，Inc.德克萨斯州首府8911号高速公路4140室德克萨斯州奥斯汀78759
EMail: Mark.Wahl@sun.com
EMail: Mark.Wahl@sun.com
Copyright (C) The Internet Society (2000). All Rights Reserved.
版权所有（C）互联网协会（2000年）。版权所有。
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.
RFC编辑功能的资金目前由互联网协会提供。