File: rfc2891.txt

package info (click to toggle)
doc-rfc 20181229-2
  • links: PTS, VCS
  • area: non-free
  • in suites: buster
  • size: 570,944 kB
  • sloc: xml: 285,646; sh: 107; python: 90; perl: 42; makefile: 14
file content (451 lines) | stat: -rw-r--r-- 15,833 bytes parent folder | download | duplicates (8)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451






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

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.

Copyright Notice

   Copyright (C) The Internet Society (2000).  All Rights Reserved.

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].











Howes, et al.               Standards Track                     [Page 1]

RFC 2891     LDAP Control Extension for Server Side Sorting  August 2000


1.  The Controls

1.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, 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.

   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.

1.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:






Howes, et al.               Standards Track                     [Page 2]

RFC 2891     LDAP Control Extension for Server Side Sorting  August 2000


      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 }

2.  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].



Howes, et al.               Standards Track                     [Page 3]

RFC 2891     LDAP Control Extension for Server Side Sorting  August 2000


   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.



Howes, et al.               Standards Track                     [Page 4]

RFC 2891     LDAP Control Extension for Server Side Sorting  August 2000


   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.

2.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.

2.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).

3.  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.





Howes, et al.               Standards Track                     [Page 5]

RFC 2891     LDAP Control Extension for Server Side Sorting  August 2000


4.  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, 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.

5.  References

   [LDAPv3]    Wahl, M, Kille, S. and T. Howes, "Lightweight Directory
               Access Protocol (v3)", RFC 2251, December 1997.

   [Bradner97] Bradner, S., "Key Words for use in RFCs to Indicate
               Requirement Levels", BCP 14, RFC 2119, March 1997.

   [LdapPaged] Weider, C., Herron, A., Anantha, A. and T. Howes, "LDAP
               Control Extension for Simple Paged Results Manipulation",
               RFC 2696, September 1999.























Howes, et al.               Standards Track                     [Page 6]

RFC 2891     LDAP Control Extension for Server Side Sorting  August 2000


6.  Authors' Addresses

   Anoop Anantha
   Microsoft Corp.
   1 Microsoft Way
   Redmond, WA 98052
   USA

   Phone: +1 425 882-8080
   EMail: anoopa@microsoft.com


   Tim Howes
   Loudcloud, Inc.
   615 Tasman Dr.
   Sunnyvale, CA 94089
   USA

   EMail: howes@loudcloud.com


   Mark Wahl
   Sun Microsystems, Inc.
   8911 Capital of Texas Hwy Suite 4140
   Austin, TX 78759
   USA

   EMail: Mark.Wahl@sun.com























Howes, et al.               Standards Track                     [Page 7]

RFC 2891     LDAP Control Extension for Server Side Sorting  August 2000


7.  Full Copyright Statement

   Copyright (C) The Internet Society (2000).  All Rights Reserved.

   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.



















Howes, et al.               Standards Track                     [Page 8]