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