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 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 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.'' 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). This document expires on October 5, 1999. 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 MUST return unwillingToPerform. 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 inappro- -- priate 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, irregardless 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 Pro- tocol (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, and T. Howes, "LDAP Control Extension for Simple Paged Results Manipulation", Internet Draft, February, 1997. Available as draft-ietf-asid-ldapv3-simplepaged-00.txt. 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 Tim Howes Netscape Communications Corp. 501 E. Middlefield Road Mountain View, CA 94043 USA howes@netscape.com +1 415 937-2600 Mark Wahl Critical Angle Inc. 4815 W Braker Lane #502-385 Austin, TX 78759 USA M.Wahl@critical-angle.com