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