Network Working Group Chris Weider, Microsoft INTERNET DRAFT Andy Herron, Microsoft Expire in six months Tim Howes, Netscape February, 1997 LDAP Control Extension for Simple Paged Results Manipulation draft-ietf-asid-ldapv3-simplepaged-00.txt 1. Status of this Memo This document is an Internet-Draft. Internet-Drafts are working docu- ments of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet- Drafts as reference material or to cite them other than as ``work in progress.'' To learn the current status of any Internet-Draft, please check the ``1id-abstracts.txt'' listing contained in the Internet- Drafts Shadow Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). 2. Abstract This document describes an LDAPv3 control extension for simple paging of search results. This control extension allows a client to control the rate at which an LDAP server returns the results of an LDAP search operation. This control may be useful when the LDAP client has limited resources and may not be able to process the entire result set from a given LDAP query, or when the LDAP client is connected over a low- bandwidth connection. Other operations on the result set are not defined in this extension. This extension is not designed to provide more sophisticated result set management. The key words "MUST", "SHOULD", and "MAY" used in this document are to be interpreted as described in [bradner97]. 3. The Control This control is included in the searchRequest and searchResultDone mes- sages as part of the controls field of the LDAPMessage, as defined in Section 4.1.12 of [LDAPv3]. The structure of this control is as follows: Weider, Herron & Howes [Page 1] INTERNET DRAFT February 1997 pagedResultsControl ::= SEQUENCE { controlType 1.2.840.113556.1.4.319, criticality BOOLEAN DEFAULT FALSE, controlValue searchControlValue } The searchControlValue is an OCTET STRING wrapping the BER-encoded ver- sion of the following SEQUENCE: realSearchControlValue ::= SEQUENCE { size INTEGER (0..maxInt), -- requested page size from client -- result set size estimate from server cookie OCTET STRING } 4. Client-Server Interaction An LDAP client application that needs to control the rate at which results are returned MAY specify on the searchRequest a pagedResultsCon- trol with size set to the desired page size and cookie set to the zero- length string. The page size specified MAY be greater than zero and less than the sizeLimit value specified in the searchRequest. If the page size is greater than or equal to the sizeLimit value, or equal to zero, the server should ignore the control as the request can be satisfied in a single page. If the server does not support this con- trol, the server MUST return an error of unsupportedCriticalExtension if the client requested it as critical, otherwise the server SHOULD ignore the control. The remainder of this section assumes the server does not ignore the client's pagedResultsControl. Each time the server returns a set of results to the client when pro- cessing a search request containing the pagedResultsControl, the server includes the pagedResultsControl control in the searchResultDone mes- sage. In the control returned to the client, the size MAY be set to the server's estimate of the total number of entries in the entire result set. Servers that cannot provide such an estimate MAY set this size to zero (0). The cookie MUST be set to an empty value if there are no more entries to return (i.e., the page of search results returned was the last), or to an octet string of the server's choosing, used to resume the search. The client MUST consider the cookie to be an opaque structure and make no assumptions about its internal organization or value. When the client wants to retrieve more entries for the result set, it MUST send to the server a searchRequest with all values identical to the initial request Weider, Herron & Howes [Page 2] INTERNET DRAFT February 1997 with the exception of the messageID, the cookie, and optionally a modi- fied pageSize. The cookie MUST be the octet string on the last sear- chResultDone response returned by the server. Returning cookies from previous searchResultDone responses besides the last one is undefined, as the server implementation may restrict cookies from being reused. The server will then return the next set of results from the whole result set. This interaction will continue until the client has retrieved all the results, in which case the cookie in the searchResult- Done field will be empty, or the client abandons the result. If, for any reason, the server cannot resume a paged search operation for a client, then it SHOULD return the appropriate error in a searchResult- Done entry. If this occurs, both client and server should assume the paged result set is closed and no longer resumable. A client may have any number of outstanding search requests pending, any of which may have used the pagedResultsControl. A server implementation which requires a limit on the number of outstanding paged search requests from a given client MAY either return unwillingToPerform when the client attempts to create a new paged search request, or age out an older result set. If the server implementation ages out an older paged search request, it SHOULD return "unwilling to perform" if the client attempts to resume the paged search that was aged out. A client may safely assume that all entries that satisfy a given search query are returned once and only once during the set of paged search requests/responses necessary to enumerate the entire result set, unless the result set for that query has changed since the searchRequest start- ing the request/response sequence was processed. In that case, the client may receive a given entry multiple times and/or may not receive all entries matching the given search criteria. 5. Example The following example illustrates the client-server interaction between a client doing a search requesting a page size limit of 3. The entire result set returned by the server contains 5 entries. Lines beginning with "C:" indicate requests sent from client to server. Lines beginning with "S:" indicate responses sent from server to client. Lines beginning with "--" are comments to help explain the example. -- Client sends a search request asking for paged results -- with a page size of 3. C: SearchRequest + pagedResultsControl(3,"") -- Server responds with three entries plus an indication -- of 5 total entries in the search result and an opaque -- cooking to be used by the client when retrieving subsequent Weider, Herron & Howes [Page 3] INTERNET DRAFT February 1997 -- pages. S: SearchResultEntry S: SearchResultEntry S: SearchResultEntry S: SearchResultDone + pagedResultsControl(5, "opaque") -- Client sends an identical search request (except for -- message id), returning the opaque cooking, asking for -- the next page. C: SearchRequest + PagedResultsControl(3, "opaque") -- Server responds with two entries plus an indication -- that there are no more entries (null cookie). S: SearchResultEntry S: SearchResultEntry S: SearchResultDone + pagedResultsControl(5,"") 6. Security Considerations Security considerations are not discussed in this document. 7. References [LDAPv3] Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access Pro- tocol (v3)", Internet Draft, February, 1997. Available as draft- ietf-asid-ldapv3-protocol-04.txt. [Bradner97] Bradner, Scott, "Key Words for use in RFCs to Indicate Requirement Levels", Internet Draft, January, 1997. Available as draft- bradner-key-words-03.txt. 8. Author's Address Chris Weider Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA cweider@microsoft.com +1 206 882-8080 Andy Herron Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA andyhe@microsoft.com Weider, Herron & Howes [Page 4] INTERNET DRAFT February 1997 +1 206 882-8080 Tim Howes Netscape Communications Corp. 501 E. Middlefield Road Mountain View, CA 94043 USA howes@netscape.com +1 415 937-2600 Weider, Herron & Howes [Page 5]