]> git.sur5r.net Git - openldap/blob - doc/rfc/rfc2696.txt
Fix prev commit
[openldap] / doc / rfc / rfc2696.txt
1
2
3
4
5
6
7 Network Working Group                                        C. Weider
8 Request for Comments: 2696                                   A. Herron
9 Category: 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
18 Status 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
24 Copyright Notice
25
26    Copyright (C) The Internet Society (1999).  All Rights Reserved.
27
28 1. 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
43 2. 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
58 Weider, et al.               Informational                      [Page 1]
59 \f
60 RFC 2696       LDAP Control Ext. for Simple Paged Results September 1999
61
62
63 pagedResultsControl ::= SEQUENCE {
64         controlType     1.2.840.113556.1.4.319,
65         criticality     BOOLEAN DEFAULT FALSE,
66         controlValue    searchControlValue
67 }
68
69 The searchControlValue is an OCTET STRING wrapping the BER-encoded
70 version of the following SEQUENCE:
71
72 realSearchControlValue ::= 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
79 3. 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
114 Weider, et al.               Informational                      [Page 2]
115 \f
116 RFC 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
170 Weider, et al.               Informational                      [Page 3]
171 \f
172 RFC 2696       LDAP Control Ext. for Simple Paged Results September 1999
173
174
175 4. 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
207 5. 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
226 Weider, et al.               Informational                      [Page 4]
227 \f
228 RFC 2696       LDAP Control Ext. for Simple Paged Results September 1999
229
230
231 6. 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
248 7. 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
282 Weider, et al.               Informational                      [Page 5]
283 \f
284 RFC 2696       LDAP Control Ext. for Simple Paged Results September 1999
285
286
287 8. 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
338 Weider, et al.               Informational                      [Page 6]
339 \f
340 RFC 2696       LDAP Control Ext. for Simple Paged Results September 1999
341
342
343 9.  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
371 Acknowledgement
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
394 Weider, et al.               Informational                      [Page 7]
395 \f