home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / ldapsdk.zip / doc / rfc / rfc2696.txt < prev    next >
Text File  |  2000-06-14  |  13KB  |  396 lines
  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.  
  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.  
  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.  
  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.  
  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.  
  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.  
  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.  
  396.