RFC 2696

LDAP Control Extension for Simple Paged Results Manipulation 💖

Okay bestie, let's get into it 🎀 This is RFC 2696, put out by the Network Working Group in September 1999 📅 It's Informational, so it's giving "here's useful info," not a rule you have to follow 🧚 The authors are Chris Weider, Andy Herron, and Anoop Anantha from Microsoft, plus Tim Howes from Netscape 🫶 The header doesn't list anything it obsoletes or updates, so no drama there ✨

---

Status of this Memo 🌸

This memo gives information to the Internet community. It doesn't specify an Internet standard of any kind. Distribution is unlimited 🦋

Copyright Notice 💜

Copyright (C) The Internet Society (1999). All Rights Reserved. 💅

1. Abstract ✨

Okay so this doc describes an LDAPv3 control extension for simple paging of search results 📄 It lets a client control the rate at which an LDAP server sends back the results of a search 🐢 This is lowkey useful when the client has limited resources and can't handle the whole result set from a query, or when it's connected over a low-bandwidth connection 📶 Other operations on the result set aren't defined here, and this extension isn't built for fancy, sophisticated result set management. It's a simple paging tool, bestie 🍓

The key words "MUST", "SHOULD", and "MAY" used in this document are to be interpreted as described in [bradner97]. 🔑

2. The Control 🎀

This control rides along in the searchRequest and searchResultDone messages, inside the controls field of the LDAPMessage, as defined in Section 4.1.12 of [LDAPv3]. The structure looks like this:

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 version of the following SEQUENCE:

realSearchControlValue ::= SEQUENCE {
        size            INTEGER (0..maxInt),
                                -- requested page size from client
                                -- result set size estimate from server
        cookie          OCTET STRING
}

3. Client-Server Interaction 🧚

An LDAP client that wants to control how fast results come back MAY put a pagedResultsControl on the searchRequest 💫 Set size to the page size you want and cookie to the zero-length string. The page size MAY be greater than zero and less than the sizeLimit value in the searchRequest.

If the page size is greater than or equal to the sizeLimit value, the server should ignore the control, since the request can be handled in one page anyway 🙈 If the server doesn't support this control, it MUST return an error of unsupportedCriticalExtension when the client marked it as critical. Otherwise the server SHOULD ignore the control. The rest of this section assumes the server does not ignore the client's pagedResultsControl.

Every time the server returns a batch of results for a search request that includes the pagedResultsControl, it puts the pagedResultsControl in the searchResultDone message 📬 In the control sent back, size MAY be set to the server's estimate of the total number of entries in the whole result set. Servers that can't give an estimate MAY set this size to zero (0). The cookie MUST be set to an empty value if there are no more entries (aka the page you got was the last one). If there are more entries, the cookie is an octet string the server picks, used to resume the search 🔁

The client MUST treat the cookie as an opaque structure and make no assumptions about its internal organization or value. 🔒 When the client wants more entries, it MUST send the server a searchRequest where everything matches the initial request except the messageID, the cookie, and optionally a modified pageSize. The cookie MUST be the octet string from the last searchResultDone the server returned. Using cookies from earlier searchResultDone responses (not the last one) is undefined, since the server implementation may stop cookies from being reused ⚠️

The server then returns the next batch from the whole result set. This keeps going until the client has everything, which is when the cookie in the searchResultDone field comes back empty, or until the client bails on the search as described below 🏁 Once the paged search sequence is done, the cookie is no longer valid and MUST NOT be used. Don't try it again, bestie 💀

A client abandons a sequence of paged search requests by sending a search request with a pagedResultsControl where size is zero (0) and cookie is the last cookie the server returned 🛑 A client MAY use the LDAP Abandon operation to abandon one paged search in progress, but this is discouraged, since it MAY invalidate the client's cookie 😬

If the server can't resume a paged search for a client, for any reason, it SHOULD return the appropriate error in a searchResultDone entry. When that happens, both client and server should assume the paged result set is closed and can't be resumed 🚫

A client can have any number of outstanding search requests pending, and any of them may have used the pagedResultsControl 📚 A server implementation that needs a limit on outstanding paged search requests from a given client MAY either return unwillingToPerform when the client tries to create a new paged search request, or age out an older result set. If the server ages out an older paged search request, it SHOULD return "unwilling to perform" if the client tries to resume that aged-out search 🥀

A client can safely assume that all entries matching a given search query come back once and only once across the set of paged search requests and responses needed to enumerate the entire result set. The exception is if the result set for that query changed after the searchRequest starting the sequence was processed. In that case, the client may get a given entry more than once and/or may miss some entries that match the search criteria 👀

4. Example 🍓

This example shows the client-server interaction for a client doing a search that asks for a page size limit of 3. The entire result set the server returns contains 5 entries 📊

Lines starting with "C:" are requests from client to server. Lines starting with "S:" are responses from server to client. Lines starting with "--" are comments that 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
-- 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,"")

5. Relationship to X.500 🌈

For LDAP servers that front X.500 (93) directories, the paged results control defined in this document may be mapped directly onto the X.500 (93) PagedResultsRequest defined in X.511 [x500]. The size parameter may be mapped onto pageSize. The cookie parameter may be mapped onto queryReference. The sortKeys and reverse fields in the X.500 PagedResultsRequest are excluded ✨

6. Security Considerations 🔐

Okay this section is serious, bestie, so read it carefully 🙈

Server implementors should consider the resources used when clients send searches with the simple paged control. The goal is to make sure a client misusing this control doesn't lock out other legitimate operations 🚨

Server implementations may enforce an overriding sizelimit, which prevents retrieval of large portions of a publically-accessible directory 🛡️

Clients can use this control to find out how many entries match a particular filter before those entries are returned to the client. This may need special processing in servers that do access control checks on entries to decide whether the existence of an entry can be disclosed to the client 👁️

7. References 📚

[LDAPv3] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997.

[Bradner97] Bradner, S., "Key Words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.

8. Authors' Addresses 🗺️

Chris Weider Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA

Phone: +1 425 882-8080 EMail: cweider@microsoft.com

Andy Herron Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA

Phone: +1 425 882-8080 EMail: andyhe@microsoft.com

Anoop Anantha Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA

Phone: +1 425 882-8080 EMail: anoopa@microsoft.com

Tim Howes Netscape Communications Corp. 501 E. Middlefield Road Mountain View, CA 94043 USA

Phone: +1 415 937-2600 EMail: howes@netscape.com

9. Full Copyright Statement 💖

Copyright (C) The Internet Society (1999). All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Acknowledgement 🫶

Funding for the RFC Editor function is currently provided by the Internet Society. ✨