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