idnits 2.17.1 draft-ietf-ldapext-sorting-03.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 59 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 5, 2000) is 8716 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 117 -- Looks like a reference, but probably isn't: '1' on line 67 == Unused Reference: 'Bradner97' is defined on line 260, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2251 (ref. 'LDAPv3') (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) ** Downref: Normative reference to an Informational RFC: RFC 2696 (ref. 'LdapPaged') Summary: 8 errors (**), 0 flaws (~~), 3 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group T. Howes, Netscape 2 INTERNET DRAFT M. Wahl, Critical Angle Inc 3 Intended Category: Standards Track A. Anantha, Microsoft 4 Expires: December 5, 2000 June 5, 2000 6 LDAP Control Extension for Server Side Sorting of Search Results 7 draft-ietf-ldapext-sorting-03.txt 9 1. Status of this Memo 11 This document is an Internet-Draft and is in full conformance with all 12 provisions of Section 10 of RFC2026. Internet-Drafts are working 13 documents of the Internet Engineering Task Force (IETF), its areas, and 14 its working groups. Note that other groups may also distribute working 15 documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six months 18 and may be updated, replaced, or obsoleted by other documents at any 19 time. It is inappropriate to use Internet-Drafts as reference material 20 or to cite them other than as "work in progress." 22 The list of current Internet-Drafts can be accessed at 23 http://www.ietf.org/ietf/1id-abstracts.txt. 25 The list of Internet-Draft Shadow Directories can be accessed at 26 http://www.ietf.org/shadow.html. 28 This draft document will be submitted to the RFC Editor as a Standards 29 Track document. Distribution of this memo is unlimited. Technical 30 discussion of this document will take place on the IETF LDAP Extension 31 Working Group mailing list . Please send 32 editorial comments directly to the authors. 34 2. Abstract 36 This document describes two LDAPv3 control extensions for server side 37 sorting of search results. These controls allows a client to specify the 38 attribute types and matching rules a server should use when returning 39 the results to an LDAP search request. The controls may be useful when 40 the LDAP client has limited functionality or for some other reason 41 cannot sort the results but still needs them sorted. Other permissible 42 controls on search operations are not defined in this extension. 44 The sort controls allow a server to return a result code for the sorting 45 of the results that is independent of the result code returned for the 46 search operation. 48 The key words "MUST", "SHOULD", and "MAY" used in this document are to 49 be interpreted as described in [bradner97]. 51 3. The Controls 53 3.1 Request Control 55 This control is included in the searchRequest message as part of the 56 controls field of the LDAPMessage, as defined in Section 4.1.12 of 57 [LDAPv3]. 59 The controlType is set to "1.2.840.113556.1.4.473". The criticality 60 MAY be either TRUE or FALSE (where absent is also equivalent to 61 FALSE) at the client's option. The controlValue is an OCTET STRING, 62 whose value is the BER encoding of a value of the following SEQUENCE: 64 SortKeyList ::= SEQUENCE OF SEQUENCE { 65 attributeType AttributeDescription, 66 orderingRule [0] MatchingRuleId OPTIONAL, 67 reverseOrder [1] BOOLEAN DEFAULT FALSE } 69 The SortKeyList sequence is in order of highest to lowest sort key 70 precedence. 72 The MatchingRuleID SHOULD be one that is valid for the attribute type it 73 applies to. If it is not, the server will return inappropriateMatching. 75 Each attributeType should only occur in the SortKeyList once. If an 76 attributeType is included in the sort key list multiple times, the 77 server should return an error in the sortResult of unwillingToPerform. 79 If the orderingRule is omitted, the ordering MatchingRule defined for 80 use with this attribute MUST be used. 82 Any conformant implementation of this control MUST allow a sort key list 83 with at least one key. 85 3.2 Response Control 87 This control is included in the searchResultDone message as part of the 88 controls field of the LDAPMessage, as defined in Section 4.1.12 of 89 [LDAPv3]. 91 The controlType is set to "1.2.840.113556.1.4.474". The criticality is 92 FALSE (MAY be absent). The controlValue is an OCTET STRING, whose 93 value is the BER encoding of a value of the following SEQUENCE: 95 SortResult ::= SEQUENCE { 96 sortResult ENUMERATED { 97 success (0), -- results are sorted 98 operationsError (1), -- server internal failure 99 timeLimitExceeded (3), -- timelimit reached before 100 -- sorting was completed 101 strongAuthRequired (8), -- refused to return sorted 102 -- results via insecure 103 -- protocol 104 adminLimitExceeded (11), -- too many matching entries 105 -- for the server to sort 106 noSuchAttribute (16), -- unrecognized attribute 107 -- type in sort key 108 inappropriateMatching (18), -- unrecognized or 109 -- inappropriate matching 110 -- rule in sort key 111 insufficientAccessRights (50), -- refused to return sorted 112 -- results to this client 113 busy (51), -- too busy to process 114 unwillingToPerform (53), -- unable to sort 115 other (80) 116 }, 117 attributeType [0] AttributeDescription OPTIONAL } 119 4. Client-Server Interaction 121 The sortKeyRequestControl specifies one or more attribute types and 122 matching rules for the results returned by a search request. The server 123 SHOULD return all results for the search request in the order specified 124 by the sort keys. If the reverseOrder field is set to TRUE, then the 125 entries will be presented in reverse sorted order for the specified 126 key. 128 There are six possible scenarios that may occur as a result of the sort 129 control being included on the search request : 131 1 - If the server does not support this sorting control and the client 132 specified TRUE for the control's criticality field, then the server 133 MUST return unavailableCriticalExtension as a return code in the 134 searchResultDone message and not send back any other results. This 135 behavior is specified in section 4.1.12 of [LDAPv3]. 137 2 - If the server does not support this sorting control and the client 138 specified FALSE for the control's criticality field, then the server 139 MUST ignore the sort control and process the search request as if it 140 were not present. This behavior is specified in section 4.1.12 of 141 [LDAPv3]. 143 3 - If the server supports this sorting control but for some reason 144 cannot sort the search results using the specified sort keys and the 145 client specified TRUE for the control's criticality field, then the 146 server SHOULD do the following: return unavailableCriticalExtension as 147 a return code in the searchResultDone message; include the 148 sortKeyResponseControl in the searchResultDone message, and not send 149 back any search result entries. 151 4 - If the server supports this sorting control but for some reason 152 cannot sort the search results using the specified sort keys and the 153 client specified FALSE for the control's criticality field, then the 154 server should return all search results unsorted and include the 155 sortKeyResponseControl in the searchResultDone message. 157 5 - If the server supports this sorting control and can sort the search 158 results using the specified sort keys, then it should include the 159 sortKeyResponseControl in the searchResultDone message with a 160 sortResult of success. 162 6 - If the search request failed for any reason and/or there are no 163 searchResultEntry messages returned for the search response, then the 164 server SHOULD omit the sortKeyResponseControl from the 165 searchResultDone message. 167 The client application is assured that the results are sorted in the 168 specified key order if and only if the result code in the 169 sortKeyResponseControl is success. If the server omits the 170 sortKeyResponseControl from the searchResultDone message, the client 171 SHOULD assume that the sort control was ignored by the server. 173 The sortKeyResponseControl, if included by the server in the 174 searchResultDone message, should have the sortResult set to either 175 success if the results were sorted in accordance with the keys 176 specified in the sortKeyRequestControl or set to the appropriate error 177 code as to why it could not sort the data (such as noSuchAttribute or 178 inappropriateMatching). Optionally, the server MAY set the 179 attributeType to the first attribute type specified in the SortKeyList 180 that was in error. The client SHOULD ignore the attributeType field if 181 the sortResult is success. 183 The server may not be able to sort the results using the specified sort 184 keys because it may not recognize one of the attribute types, the 185 matching rule associated with an attribute type is not applicable, or 186 none of the attributes in the search response are of these types. 187 Servers may also restrict the number of keys allowed in the control, 188 such as only supporting a single key. 190 Servers that chain requests to other LDAP servers should ensure that 191 the server satisfying the client's request sort the entire result set 192 prior to sending back the results. 194 4.1 Behavior in a chained environment 196 If a server receives a sort request, the client expects to receive a 197 set of sorted results. If a client submits a sort request to a server 198 which chains the request and gets entries from multiple servers, and 199 the client has set the criticality of the sort extension to TRUE, the 200 server MUST merge sort the results before returning them to the client 201 or MUST return unwillingToPerform. 203 4.2 Other sort issues 205 An entry that meets the search criteria may be missing one or more of 206 the sort keys. In that case, the entry is considered to have a value of 207 NULL for that key. This standard considers NULL to be a larger value 208 than all other valid values for that key. For example, if only one key 209 is specified, entries which meet the search criteria but do not have 210 that key collate after all the entries which do have that key. If the 211 reverseOrder flag is set, and only one key is specified, entries which 212 meet the search criteria but do not have that key collate BEFORE all 213 the entries which do have that key. 215 If a sort key is a multi-valued attribute, and an entry happens to have 216 multiple values for that attribute and no other controls are present 217 that affect the sorting order, then the server SHOULD use the least 218 value (according to the ORDERING rule for that attribute). 220 5. Interaction with other search controls 222 When the sortKeyRequestControl control is included with the 223 pagedResultsControl control as specified in [LdapPaged], then the 224 server should send the searchResultEntry messages sorted according to 225 the sort keys applied to the entire result set. The server should not 226 simply sort each page, as this will give erroneous results to the 227 client. 229 The sortKeyList must be present on each searchRequest message for the 230 paged result. It also must not change between searchRequests for the 231 same result set. If the server has sorted the data, then it SHOULD 232 send back a sortKeyResponseControl control on every searchResultDone 233 message for each page. This will allow clients to quickly determine 234 if the result set is sorted, rather than waiting to receive the entire 235 result set. 237 6. Security Considerations 239 Implementors and administrators should be aware that allowing sorting of 240 results could enable the retrieval of a large number of records from 241 a given directory service, regardless of administrative limits set on 242 the maximum number of records to return. 244 A client that desired to pull all records out of a directory service 245 could use a combination of sorting and updating of search filters to 246 retrieve all records in a database in small result sets, thus 247 circumventing administrative limits. 249 This behavior can be overcome by the judicious use of permissions on 250 the directory entries by the administrator and by intelligent 251 implementations of administrative limits on the number of records 252 retrieved by a client. 254 7. References 256 [LDAPv3] 257 Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access 258 Protocol (v3)", RFC 2251, December, 1997. 260 [Bradner97] 261 Bradner, Scott, "Key Words for use in RFCs to Indicate Requirement 262 Levels", RFC 2119, March, 1997. 264 [LdapPaged] 265 C. Weider, A. Herron, A. Anantha and T. Howes, "LDAP Control 266 Extension for Simple Paged Results Manipulation", RFC 2696, 267 September 1999. 269 8. Author's Address 271 Anoop Anantha 272 Microsoft Corp. 273 1 Microsoft Way 274 Redmond, WA 98052 275 USA 276 anoopa@microsoft.com 277 +1 425 882-8080 278 Tim Howes 279 Loudcloud, Inc. 280 615 Tasman Dr. 281 Sunnyvale, CA 94089 282 USA 283 howes@loudcloud.com 285 Mark Wahl 286 Sun Microsystems, Inc. 287 8911 Capital of Texas Hwy Suite 4140 288 Austin, TX 78759 289 USA 290 M.Wahl@innosoft.com