source4/ldap_server/devdocs/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