1 2 3 4 5 6 7 Network Working Group T. Howes 8 Request for Comments: 2891 Loudcloud 9 Category: Standards Track M. Wahl 10 Sun Microsystems 11 A. Anantha 12 Microsoft 13 August 2000 14 15 16 LDAP Control Extension for Server Side Sorting of Search Results 17 18 Status of this Memo 19 20 This document specifies an Internet standards track protocol for the 21 Internet community, and requests discussion and suggestions for 22 improvements. Please refer to the current edition of the "Internet 23 Official Protocol Standards" (STD 1) for the standardization state 24 and status of this protocol. Distribution of this memo is unlimited. 25 26 Copyright Notice 27 28 Copyright (C) The Internet Society (2000). All Rights Reserved. 29 30 Abstract 31 32 This document describes two LDAPv3 control extensions for server side 33 sorting of search results. These controls allows a client to specify 34 the attribute types and matching rules a server should use when 35 returning the results to an LDAP search request. The controls may be 36 useful when the LDAP client has limited functionality or for some 37 other reason cannot sort the results but still needs them sorted. 38 Other permissible controls on search operations are not defined in 39 this extension. 40 41 The sort controls allow a server to return a result code for the 42 sorting of the results that is independent of the result code 43 returned for the search operation. 44 45 The key words "MUST", "SHOULD", and "MAY" used in this document are 46 to be interpreted as described in [bradner97]. 47 48 49 50 51 52 53 54 55 56 57 58 Howes, et al. Standards Track [Page 1] 59 61 RFC 2891 LDAP Control Extension for Server Side Sorting August 2000 62 63 64 1. The Controls 65 66 1.1 Request Control 67 68 This control is included in the searchRequest message as part of the 69 controls field of the LDAPMessage, as defined in Section 4.1.12 of 70 [LDAPv3]. 71 72 The controlType is set to "1.2.840.113556.1.4.473". The criticality 73 MAY be either TRUE or FALSE (where absent is also equivalent to 74 FALSE) at the client's option. The controlValue is an OCTET STRING, 75 whose value is the BER encoding of a value of the following SEQUENCE: 76 77 SortKeyList ::= SEQUENCE OF SEQUENCE { 78 attributeType AttributeDescription, 79 orderingRule [0] MatchingRuleId OPTIONAL, 80 reverseOrder [1] BOOLEAN DEFAULT FALSE } 81 82 The SortKeyList sequence is in order of highest to lowest sort key 83 precedence. 84 85 The MatchingRuleId, as defined in section 4.1.9 of [LDAPv3], SHOULD 86 be one that is valid for the attribute type it applies to. If it is 87 not, the server will return inappropriateMatching. 88 89 Each attributeType should only occur in the SortKeyList once. If an 90 attributeType is included in the sort key list multiple times, the 91 server should return an error in the sortResult of 92 unwillingToPerform. 93 94 If the orderingRule is omitted, the ordering MatchingRule defined for 95 use with this attribute MUST be used. 96 97 Any conformant implementation of this control MUST allow a sort key 98 list with at least one key. 99 100 1.2 Response Control 101 102 This control is included in the searchResultDone message as part of 103 the controls field of the LDAPMessage, as defined in Section 4.1.12 104 of [LDAPv3]. 105 106 The controlType is set to "1.2.840.113556.1.4.474". The criticality 107 is FALSE (MAY be absent). The controlValue is an OCTET STRING, whose 108 value is the BER encoding of a value of the following SEQUENCE: 109 110 111 112 113 114 115 Howes, et al. Standards Track [Page 2] 116 118 RFC 2891 LDAP Control Extension for Server Side Sorting August 2000 119 120 121 SortResult ::= SEQUENCE { 122 sortResult ENUMERATED { 123 success (0), -- results are sorted 124 operationsError (1), -- server internal failure 125 timeLimitExceeded (3), -- timelimit reached before 126 -- sorting was completed 127 strongAuthRequired (8), -- refused to return sorted 128 -- results via insecure 129 -- protocol 130 adminLimitExceeded (11), -- too many matching entries 131 -- for the server to sort 132 noSuchAttribute (16), -- unrecognized attribute 133 -- type in sort key 134 inappropriateMatching (18), -- unrecognized or 135 -- inappropriate matching 136 -- rule in sort key 137 insufficientAccessRights (50), -- refused to return sorted 138 -- results to this client 139 busy (51), -- too busy to process 140 unwillingToPerform (53), -- unable to sort 141 other (80) 142 }, 143 attributeType [0] AttributeDescription OPTIONAL } 144 145 2. Client-Server Interaction 146 147 The sortKeyRequestControl specifies one or more attribute types and 148 matching rules for the results returned by a search request. The 149 server SHOULD return all results for the search request in the order 150 specified by the sort keys. If the reverseOrder field is set to TRUE, 151 then the entries will be presented in reverse sorted order for the 152 specified key. 153 154 There are six possible scenarios that may occur as a result of the 155 sort control being included on the search request: 156 157 1 - If the server does not support this sorting control and the 158 client specified TRUE for the control's criticality field, then 159 the server MUST return unavailableCriticalExtension as a return 160 code in the searchResultDone message and not send back any other 161 results. This behavior is specified in section 4.1.12 of 162 [LDAPv3]. 163 164 2 - If the server does not support this sorting control and the 165 client specified FALSE for the control's criticality field, then 166 the server MUST ignore the sort control and process the search 167 request as if it were not present. This behavior is specified in 168 section 4.1.12 of [LDAPv3]. 169 170 171 172 Howes, et al. Standards Track [Page 3] 173 175 RFC 2891 LDAP Control Extension for Server Side Sorting August 2000 176 177 178 3 - If the server supports this sorting control but for some reason 179 cannot sort the search results using the specified sort keys and 180 the client specified TRUE for the control's criticality field, 181 then the server SHOULD do the following: return 182 unavailableCriticalExtension as a return code in the 183 searchResultDone message; include the sortKeyResponseControl in 184 the searchResultDone message, and not send back any search result 185 entries. 186 187 4 - If the server supports this sorting control but for some reason 188 cannot sort the search results using the specified sort keys and 189 the client specified FALSE for the control's criticality field, 190 then the server should return all search results unsorted and 191 include the sortKeyResponseControl in the searchResultDone 192 message. 193 194 5 - If the server supports this sorting control and can sort the 195 search results using the specified sort keys, then it should 196 include the sortKeyResponseControl in the searchResultDone 197 message with a sortResult of success. 198 199 6 - If the search request failed for any reason and/or there are no 200 searchResultEntry messages returned for the search response, then 201 the server SHOULD omit the sortKeyResponseControl from the 202 searchResultDone message. 203 204 The client application is assured that the results are sorted in the 205 specified key order if and only if the result code in the 206 sortKeyResponseControl is success. If the server omits the 207 sortKeyResponseControl from the searchResultDone message, the client 208 SHOULD assume that the sort control was ignored by the server. 209 210 The sortKeyResponseControl, if included by the server in the 211 searchResultDone message, should have the sortResult set to either 212 success if the results were sorted in accordance with the keys 213 specified in the sortKeyRequestControl or set to the appropriate 214 error code as to why it could not sort the data (such as 215 noSuchAttribute or inappropriateMatching). Optionally, the server MAY 216 set the attributeType to the first attribute type specified in the 217 SortKeyList that was in error. The client SHOULD ignore the 218 attributeType field if the sortResult is success. 219 220 The server may not be able to sort the results using the specified 221 sort keys because it may not recognize one of the attribute types, 222 the matching rule associated with an attribute type is not 223 applicable, or none of the attributes in the search response are of 224 these types. Servers may also restrict the number of keys allowed in 225 the control, such as only supporting a single key. 226 227 228 229 Howes, et al. Standards Track [Page 4] 230 232 RFC 2891 LDAP Control Extension for Server Side Sorting August 2000 233 234 235 Servers that chain requests to other LDAP servers should ensure that 236 the server satisfying the client's request sort the entire result set 237 prior to sending back the results. 238 239 2.1 Behavior in a chained environment 240 241 If a server receives a sort request, the client expects to receive a 242 set of sorted results. If a client submits a sort request to a server 243 which chains the request and gets entries from multiple servers, and 244 the client has set the criticality of the sort extension to TRUE, the 245 server MUST merge sort the results before returning them to the 246 client or MUST return unwillingToPerform. 247 248 2.2 Other sort issues 249 250 An entry that meets the search criteria may be missing one or more of 251 the sort keys. In that case, the entry is considered to have a value 252 of NULL for that key. This standard considers NULL to be a larger 253 value than all other valid values for that key. For example, if only 254 one key is specified, entries which meet the search criteria but do 255 not have that key collate after all the entries which do have that 256 key. If the reverseOrder flag is set, and only one key is specified, 257 entries which meet the search criteria but do not have that key 258 collate BEFORE all the entries which do have that key. 259 260 If a sort key is a multi-valued attribute, and an entry happens to 261 have multiple values for that attribute and no other controls are 262 present that affect the sorting order, then the server SHOULD use the 263 least value (according to the ORDERING rule for that attribute). 264 265 3. Interaction with other search controls 266 267 When the sortKeyRequestControl control is included with the 268 pagedResultsControl control as specified in [LdapPaged], then the 269 server should send the searchResultEntry messages sorted according to 270 the sort keys applied to the entire result set. The server should not 271 simply sort each page, as this will give erroneous results to the 272 client. 273 274 The sortKeyList must be present on each searchRequest message for the 275 paged result. It also must not change between searchRequests for the 276 same result set. If the server has sorted the data, then it SHOULD 277 send back a sortKeyResponseControl control on every searchResultDone 278 message for each page. This will allow clients to quickly determine 279 if the result set is sorted, rather than waiting to receive the 280 entire result set. 281 282 283 284 285 286 Howes, et al. Standards Track [Page 5] 287 289 RFC 2891 LDAP Control Extension for Server Side Sorting August 2000 290 291 292 4. Security Considerations 293 294 Implementors and administrators should be aware that allowing sorting 295 of results could enable the retrieval of a large number of records 296 from a given directory service, regardless of administrative limits 297 set on the maximum number of records to return. 298 299 A client that desired to pull all records out of a directory service 300 could use a combination of sorting and updating of search filters to 301 retrieve all records in a database in small result sets, thus 302 circumventing administrative limits. 303 304 This behavior can be overcome by the judicious use of permissions on 305 the directory entries by the administrator and by intelligent 306 implementations of administrative limits on the number of records 307 retrieved by a client. 308 309 5. References 310 311 [LDAPv3] Wahl, M, Kille, S. and T. Howes, "Lightweight Directory 312 Access Protocol (v3)", RFC 2251, December 1997. 313 314 [Bradner97] Bradner, S., "Key Words for use in RFCs to Indicate 315 Requirement Levels", BCP 14, RFC 2119, March 1997. 316 317 [LdapPaged] Weider, C., Herron, A., Anantha, A. and T. Howes, "LDAP 318 Control Extension for Simple Paged Results Manipulation", 319 RFC 2696, September 1999. 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 Howes, et al. Standards Track [Page 6] 344 346 RFC 2891 LDAP Control Extension for Server Side Sorting August 2000 347 348 349 6. Authors' Addresses 350 351 Anoop Anantha 352 Microsoft Corp. 353 1 Microsoft Way 354 Redmond, WA 98052 355 USA 356 357 Phone: +1 425 882-8080 358 EMail: anoopa (a] microsoft.com 359 360 361 Tim Howes 362 Loudcloud, Inc. 363 615 Tasman Dr. 364 Sunnyvale, CA 94089 365 USA 366 367 EMail: howes (a] loudcloud.com 368 369 370 Mark Wahl 371 Sun Microsystems, Inc. 372 8911 Capital of Texas Hwy Suite 4140 373 Austin, TX 78759 374 USA 375 376 EMail: Mark.Wahl (a] sun.com 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 Howes, et al. Standards Track [Page 7] 401 403 RFC 2891 LDAP Control Extension for Server Side Sorting August 2000 404 405 406 7. Full Copyright Statement 407 408 Copyright (C) The Internet Society (2000). All Rights Reserved. 409 410 This document and translations of it may be copied and furnished to 411 others, and derivative works that comment on or otherwise explain it 412 or assist in its implementation may be prepared, copied, published 413 and distributed, in whole or in part, without restriction of any 414 kind, provided that the above copyright notice and this paragraph are 415 included on all such copies and derivative works. However, this 416 document itself may not be modified in any way, such as by removing 417 the copyright notice or references to the Internet Society or other 418 Internet organizations, except as needed for the purpose of 419 developing Internet standards in which case the procedures for 420 copyrights defined in the Internet Standards process must be 421 followed, or as required to translate it into languages other than 422 English. 423 424 The limited permissions granted above are perpetual and will not be 425 revoked by the Internet Society or its successors or assigns. 426 427 This document and the information contained herein is provided on an 428 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 429 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 430 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 431 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 432 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 433 434 Acknowledgement 435 436 Funding for the RFC Editor function is currently provided by the 437 Internet Society. 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 Howes, et al. Standards Track [Page 8] 458 460
Indexes created Mon Sep 14 00:24:24 UTC 2026