1
2
3
4
5
6
7Network Working Group                                        C. Weider
8Request for Comments: 2696                                   A. Herron
9Category: Informational                                     A. Anantha
10                                                             Microsoft
11                                                              T. Howes
12                                                              Netscape
13                                                        September 1999
14
15
16      LDAP Control Extension for Simple Paged Results Manipulation
17
18Status of this Memo
19
20   This memo provides information for the Internet community.  It does
21   not specify an Internet standard of any kind.  Distribution of this
22   memo is unlimited.
23
24Copyright Notice
25
26   Copyright (C) The Internet Society (1999).  All Rights Reserved.
27
281. Abstract
29
30   This document describes an LDAPv3 control extension for simple paging
31   of search results. This control extension allows a client to control
32   the rate at which an LDAP server returns the results of an LDAP
33   search operation. This control may be useful when the LDAP client has
34   limited resources and may not be able to process the entire result
35   set from a given LDAP query, or when the LDAP client is connected
36   over a low-bandwidth connection. Other operations on the result set
37   are not defined in this extension. This extension is not designed to
38   provide more sophisticated result set management.
39
40   The key words "MUST", "SHOULD", and "MAY" used in this document are
41   to be interpreted as described in [bradner97].
42
432. The Control
44
45   This control is included in the searchRequest and searchResultDone
46   messages as part of the controls field of the LDAPMessage, as defined
47   in Section 4.1.12 of [LDAPv3]. The structure of this control is as
48   follows:
49
50
51
52
53
54
55
56
57
58Weider, et al.               Informational                      [Page 1]
59
60RFC 2696       LDAP Control Ext. for Simple Paged Results September 1999
61
62
63pagedResultsControl ::= SEQUENCE {
64        controlType     1.2.840.113556.1.4.319,
65        criticality     BOOLEAN DEFAULT FALSE,
66        controlValue    searchControlValue
67}
68
69The searchControlValue is an OCTET STRING wrapping the BER-encoded
70version of the following SEQUENCE:
71
72realSearchControlValue ::= SEQUENCE {
73        size            INTEGER (0..maxInt),
74                                -- requested page size from client
75                                -- result set size estimate from server
76        cookie          OCTET STRING
77}
78
793. Client-Server Interaction
80
81   An LDAP client application that needs to control the rate at which
82   results are returned MAY specify on the searchRequest a
83   pagedResultsControl with size set to the desired page size and cookie
84   set to the zero-length string. The page size specified MAY be greater
85   than zero and less than the sizeLimit value specified in the
86   searchRequest.
87
88   If the page size is greater than or equal to the sizeLimit value, the
89   server should ignore the control as the request can be satisfied in a
90   single page. If the server does not support this control, the server
91   MUST return an error of unsupportedCriticalExtension if the client
92   requested it as critical, otherwise the server SHOULD ignore the
93   control. The remainder of this section assumes the server does not
94   ignore the client's pagedResultsControl.
95
96   Each time the server returns a set of results to the client when
97   processing a search request containing the pagedResultsControl, the
98   server includes the pagedResultsControl control in the
99   searchResultDone message. In the control returned to the client, the
100   size MAY be set to the server's estimate of the total number of
101   entries in the entire result set. Servers that cannot provide such an
102   estimate MAY set this size to zero (0).  The cookie MUST be set to an
103   empty value if there are no more entries to return (i.e., the page of
104   search results returned was the last), or, if there are more entries
105   to return, to an octet string of the server's choosing,used to resume
106   the search.
107
108   The client MUST consider the cookie to be an opaque structure and
109   make no assumptions about its internal organization or value. When
110   the client wants to retrieve more entries for the result set, it MUST
111
112
113
114Weider, et al.               Informational                      [Page 2]
115
116RFC 2696       LDAP Control Ext. for Simple Paged Results September 1999
117
118
119   send to the server a searchRequest with all values identical to the
120   initial request with the exception of the messageID, the cookie, and
121   optionally a modified pageSize. The cookie MUST be the octet string
122   on the last searchResultDone response returned by the server.
123   Returning cookies from previous searchResultDone responses besides
124   the last one is undefined, as the server implementation may restrict
125   cookies from being reused.
126
127   The server will then return the next set of results from the whole
128   result set. This interaction will continue until the client has
129   retrieved all the results, in which case the cookie in the
130   searchResultDone field will be empty, or until the client abandons
131   the search sequence as described below. Once the paged search
132   sequence has been completed, the cookie is no longer valid and MUST
133   NOT be used.
134
135   A sequence of paged search requests is abandoned by the client
136   sending a search request containing a pagedResultsControl with the
137   size set to zero (0) and the cookie set to the last cookie returned
138   by the server.  A client MAY use the LDAP Abandon operation to
139   abandon one paged search request in progress, but this is discouraged
140   as it MAY invalidate the client's cookie.
141
142   If, for any reason, the server cannot resume a paged search operation
143   for a client, then it SHOULD return the appropriate error in a
144   searchResultDone entry. If this occurs, both client and server should
145   assume the paged result set is closed and no longer resumable.
146
147   A client may have any number of outstanding search requests pending,
148   any of which may have used the pagedResultsControl.  A server
149   implementation which requires a limit on the number of outstanding
150   paged search requests from a given client MAY either return
151   unwillingToPerform when the client attempts to create a new paged
152   search request, or age out an older result set.  If the server
153   implementation ages out an older paged search request, it SHOULD
154   return "unwilling to perform" if the client attempts to resume the
155   paged search that was aged out.
156
157   A client may safely assume that all entries that satisfy a given
158   search query are returned once and only once during the set of paged
159   search requests/responses necessary to enumerate the entire result
160   set, unless the result set for that query has changed since the
161   searchRequest starting the request/response sequence was processed.
162   In that case, the client may receive a given entry multiple times
163   and/or may not receive all entries matching the given search
164   criteria.
165
166
167
168
169
170Weider, et al.               Informational                      [Page 3]
171
172RFC 2696       LDAP Control Ext. for Simple Paged Results September 1999
173
174
1754. Example
176
177   The following example illustrates the client-server interaction
178   between a client doing a search requesting a page size limit of 3.
179   The entire result set returned by the server contains 5 entries.
180
181   Lines beginning with "C:" indicate requests sent from client to
182   server. Lines beginning with "S:" indicate responses sent from server
183   to client. Lines beginning with "--" are comments to help explain the
184   example.
185
186   -- Client sends a search request asking for paged results
187   -- with a page size of 3.
188   C: SearchRequest + pagedResultsControl(3,"")
189   -- Server responds with three entries plus an indication
190   -- of 5 total entries in the search result and an opaque
191   -- cooking to be used by the client when retrieving subsequent
192   -- pages.
193   S: SearchResultEntry
194   S: SearchResultEntry
195   S: SearchResultEntry
196   S: SearchResultDone + pagedResultsControl(5, "opaque")
197   -- Client sends an identical search request (except for
198   -- message id), returning the opaque cooking, asking for
199   -- the next page.
200   C: SearchRequest + PagedResultsControl(3, "opaque")
201   -- Server responds with two entries plus an indication
202   -- that there are no more entries (null cookie).
203   S: SearchResultEntry
204   S: SearchResultEntry
205   S: SearchResultDone + pagedResultsControl(5,"")
206
2075. Relationship to X.500
208
209   For LDAP servers providing a front end to X.500 (93) directories, the
210   paged results control defined in this document may be mapped directly
211   onto the X.500 (93) PagedResultsRequest defined in X.511 [x500]. The
212   size parameter may be mapped onto pageSize.  The cookie parameter may
213   be mapped onto queryReference.  The sortKeys and reverse fields in
214   the X.500 PagedResultsRequest are excluded.
215
216
217
218
219
220
221
222
223
224
225
226Weider, et al.               Informational                      [Page 4]
227
228RFC 2696       LDAP Control Ext. for Simple Paged Results September 1999
229
230
2316. Security Considerations
232
233   Server implementors should consider the resources used when clients
234   send searches with the simple paged control, to ensure that a
235   client's misuse of this control does not lock out other legitimate
236   operations.
237
238   Servers implementations may enforce an overriding sizelimit, to
239   prevent the retrieval of large portions of a publically-accessible
240   directory.
241
242   Clients can, using this control, determine how many entries match a
243   particular filter, before the entries are returned to the client.
244   This may require special processing in servers which perform access
245   control checks on entries to determine whether the existence of the
246   entry can be disclosed to the client.
247
2487. References
249
250   [LDAPv3]    Wahl, M., Howes, T. and S. Kille, "Lightweight Directory
251               Access Protocol (v3)", RFC 2251, December 1997.
252
253   [Bradner97] Bradner, S., "Key Words for use in RFCs to Indicate
254               Requirement Levels", BCP 14, RFC 2119, March 1997.
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
282Weider, et al.               Informational                      [Page 5]
283
284RFC 2696       LDAP Control Ext. for Simple Paged Results September 1999
285
286
2878. Authors' Addresses
288
289   Chris Weider
290   Microsoft Corp.
291   1 Microsoft Way
292   Redmond, WA 98052
293   USA
294
295   Phone: +1 425 882-8080
296   EMail: cweider@microsoft.com
297
298
299   Andy Herron
300   Microsoft Corp.
301   1 Microsoft Way
302   Redmond, WA 98052
303   USA
304
305   Phone: +1 425 882-8080
306   EMail: andyhe@microsoft.com
307
308
309   Anoop Anantha
310   Microsoft Corp.
311   1 Microsoft Way
312   Redmond, WA 98052
313   USA
314
315   Phone: +1 425 882-8080
316   EMail: anoopa@microsoft.com
317
318
319   Tim Howes
320   Netscape Communications Corp.
321   501 E. Middlefield Road
322   Mountain View, CA 94043
323   USA
324
325   Phone: +1 415 937-2600
326   EMail: howes@netscape.com
327
328
329
330
331
332
333
334
335
336
337
338Weider, et al.               Informational                      [Page 6]
339
340RFC 2696       LDAP Control Ext. for Simple Paged Results September 1999
341
342
3439.  Full Copyright Statement
344
345   Copyright (C) The Internet Society (1999).  All Rights Reserved.
346
347   This document and translations of it may be copied and furnished to
348   others, and derivative works that comment on or otherwise explain it
349   or assist in its implementation may be prepared, copied, published
350   and distributed, in whole or in part, without restriction of any
351   kind, provided that the above copyright notice and this paragraph are
352   included on all such copies and derivative works.  However, this
353   document itself may not be modified in any way, such as by removing
354   the copyright notice or references to the Internet Society or other
355   Internet organizations, except as needed for the purpose of
356   developing Internet standards in which case the procedures for
357   copyrights defined in the Internet Standards process must be
358   followed, or as required to translate it into languages other than
359   English.
360
361   The limited permissions granted above are perpetual and will not be
362   revoked by the Internet Society or its successors or assigns.
363
364   This document and the information contained herein is provided on an
365   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
366   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
367   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
368   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
369   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
370
371Acknowledgement
372
373   Funding for the RFC Editor function is currently provided by the
374   Internet Society.
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394Weider, et al.               Informational                      [Page 7]
395
396