LDAP Control Extension for Simple Paged Results Manipulation
RFC 2696
Document | Type | RFC - Informational (September 1999) Errata | |
---|---|---|---|
Authors | Andrew Herron , Anoop Anantha , Tim Howes , Chris Weider | ||
Last updated | 2023-01-07 | ||
RFC stream | Internet Engineering Task Force (IETF) | ||
Formats | |||
Additional resources | Mailing list discussion | ||
IESG | Responsible AD | (None) | |
Send notices to | (None) |
RFC 2696
Network Working Group C. Weider Request for Comments: 2696 A. Herron Category: Informational A. Anantha Microsoft T. Howes Netscape September 1999 LDAP Control Extension for Simple Paged Results Manipulation Status of this Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (1999). All Rights Reserved. 1. 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]. 2. The Control This control is included in the searchRequest and searchResultDone messages 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, et al. Informational [Page 1] RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999 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 application that needs to control the rate at which results are returned MAY specify on the searchRequest a pagedResultsControl 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, the server should ignore the control as the request can be satisfied in a single page. If the server does not support this control, 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 processing a search request containing the pagedResultsControl, the server includes the pagedResultsControl control in the searchResultDone message. 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, if there are more entries to return, 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 Weider, et al. Informational [Page 2] RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999 send to the server a searchRequest with all values identical to the initial request with the exception of the messageID, the cookie, and optionally a modified pageSize. The cookie MUST be the octet string on the last searchResultDone 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 searchResultDone field will be empty, or until the client abandons the search sequence as described below. Once the paged search sequence has been completed, the cookie is no longer valid and MUST NOT be used. A sequence of paged search requests is abandoned by the client sending a search request containing a pagedResultsControl with the size set to zero (0) and the cookie set to the last cookie returned by the server. A client MAY use the LDAP Abandon operation to abandon one paged search request in progress, but this is discouraged as it MAY invalidate the client's cookie. If, for any reason, the server cannot resume a paged search operation for a client, then it SHOULD return the appropriate error in a searchResultDone 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 starting 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. Weider, et al. Informational [Page 3] RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999 4. 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 -- 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 providing a front end to 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. Weider, et al. Informational [Page 4] RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999 6. Security Considerations Server implementors should consider the resources used when clients send searches with the simple paged control, to ensure that a client"A Link Set consists of Link Tuples, each representing a single link indexed by the local and remote interface pair. Each Link Set from NHDP is extended by OLSRv2 by the following fields: (L_in_metric (olsrv2IibLinkSetInMetricValue), L_out_metric (olsrv2IibLinkSetOutMetricValue), L_mpr_selector (olsrv2IibLinkSetMprSelector))" REFERENCE "RFC 7181 - The Optimized Link State Routing Protocol Version 2, Clausen, T., Dearlove, C., Jacquet, P., and U. Herberg, April 2014." AUGMENTS { nhdpIibLinkSetEntry } ::= { olsrv2IibLinkSetTable 1 } Olsrv2IibLinkSetEntry ::= SEQUENCE { olsrv2IibLinkSetInMetricValue Olsrv2MetricValueCompressedFormTC, olsrv2IibLinkSetOutMetricValue Olsrv2MetricValueCompressedFormTC, olsrv2IibLinkSetMprSelector TruthValue } olsrv2IibLinkSetInMetricValue OBJECT-TYPE SYNTAX Olsrv2MetricValueCompressedFormTC MAX-ACCESS read-only STATUS current Herberg, et al. Standards Track [Page 29] RFC 7184 The OLSRv2-MIB April 2014 DESCRIPTION "olsrv2IibLinkSetInMetricValue is the metric of the link from the OLSRv2 interface with addresses L_neighbor_iface_addr_list to this OLSRv2 interface. The L_neighbor_iface_addr_list is identified by the nhdpDiscIfIndex, which is an index to the nhdpIibLinkSetTable, which this table augments." REFERENCE "RFC 7181 - The Optimized Link State Routing Protocol Version 2, Clausen, T., Dearlove, C., Jacquet, P., and U. Herberg, April 2014." ::= { olsrv2IibLinkSetEntry 1 } olsrv2IibLinkSetOutMetricValue OBJECT-TYPE SYNTAX Olsrv2MetricValueCompressedFormTC MAX-ACCESS read-write STATUS current DESCRIPTION "olsrv2IibLinkSetOutMetricValue is the metric of the link to the OLSRv2 interface with addresses L_neighbor_iface_addr_list from this OLSRv2 interface. The L_neighbor_iface_addr_list is identified by the nhdpDiscIfIndex, which is an index to the nhdpIibLinkSetTable, which this table augments." REFERENCE "RFC 7181 - The Optimized Link State Routing Protocol Version 2, Clausen, T., Dearlove, C., Jacquet, P., and U. Herberg, April 2014." ::= { olsrv2IibLinkSetEntry 2 } olsrv2IibLinkSetMprSelector OBJECT-TYPE SYNTAX TruthValue MAX-ACCESS read-only STATUS current DESCRIPTION "olsrv2IibLinkSetMprSelector is a boolean flag, recording whether this neighbor has selected this router as a flooding MPR, i.e., is a flooding MPR selector of this router." REFERENCE "RFC 7181 - The Optimized Link State Routing Protocol Version 2, Clausen, T., Dearlove, C., Jacquet, P., and U. Herberg, April 2014." ::= { olsrv2IibLinkSetEntry 3 } -- -- 2-Hop Set; from RFC 6130, extended by OLSRv2 by the -- following fields: N2_in_metric, N2_out_metric Herberg, et al. Standards Track [Page 30] RFC 7184 The OLSRv2-MIB April 2014 -- olsrv2Iib2HopSetTable OBJECT-TYPE SYNTAX SEQUENCE OF Olsrv2Iib2HopSetEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "A 2-Hop Set of an interface records network addresses of symmetric 2-hop neighbors, and the symmetric links to symmetric 1-hop neighbors through which these symmetric 2-hop neighbors can be reached. It consists of 2-Hop Tuples." REFERENCE "RFC 7181 - The Optimized Link State Routing Protocol Version 2, Clausen, T., Dearlove, C., Jacquet, P., and U. Herberg, April 2014." ::= { olsrv2StateGroup 2 } olsrv2Iib2HopSetEntry OBJECT-TYPE SYNTAX Olsrv2Iib2HopSetEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "olsrv2Iib2HopSetTable consists of 2-Hop Tuples, each representing a single network address of a symmetric 2-hop neighbor and a single MANET interface of a symmetric 1-hop neighbor. Each 2-Hop Set from NHDP is extended by OLSRv2 by the following fields: (N2_in_metric (olsrv2Iib2HopSetInMetricValue), N2_out_metric (olsrv2Iib2HopSetOutMetricValue))" REFERENCE "RFC 7181 - The Optimized Link State Routing Protocol Version 2, Clausen, T., Dearlove, C., Jacquet, P., and U. Herberg, April 2014." AUGMENTS { nhdpIib2HopSetEntry } ::= { olsrv2Iib2HopSetTable 1 } Olsrv2Iib2HopSetEntry ::= SEQUENCE { olsrv2Iib2HopSetInMetricValue Olsrv2MetricValueCompressedFormTC, olsrv2Iib2HopSetOutMetricValue Olsrv2MetricValueCompressedFormTC } olsrv2Iib2HopSetInMetricValue OBJECT-TYPE Herberg, et al. Standards Track [Page 31] RFC 7184 The OLSRv2-MIB April 2014 SYNTAX Olsrv2MetricValueCompressedFormTC MAX-ACCESS read-only STATUS current DESCRIPTION "olsrv2Iib2HopSetInMetricValue is the neighbor metric from the router with address N2_2hop_iface_addr to the router with OLSRv2 interface addresses N2_neighbor_iface_addr_list. The N2_2hop_iface_addr is identified by the (nhdpIib2HopSetIpAddressType, nhdpIib2HopSetIpAddress) pair from the nhdpIibLinkSetTable, which this table augments. The N2_neighbor_iface_addr_list is defined by the nhdpDiscIfIndex, which is an index of the nhdpIibLinkSetTable, which this table augments." REFERENCE "RFC 7181 - The Optimized Link State Routing Protocol Version 2, Clausen, T., Dearlove, C., Jacquet, P., and U. Herberg, April 2014. and RFC 6779 - Definition of Managed Objects for the Neighborhood Discovery Process, Herberg, U., Cole, R., and I. Chakeres, October 2012." ::= { olsrv2Iib2HopSetEntry 1 } olsrv2Iib2HopSetOutMetricValue OBJECT-TYPE SYNTAX Olsrv2MetricValueCompressedFormTC MAX-ACCESS read-only STATUS current DESCRIPTION "olsrv2Iib2HopSetOutMetricValue is the neighbor metric to the router with address N2_2hop_iface_addr from the router with OLSRv2 interface addresses N2_neighbor_iface_addr_list. The N2_2hop_iface_addr is identified by the (nhdpIib2HopSetIpAddressType, nhdpIib2HopSetIpAddress) pair from the nhdpIibLinkSetTable, which this table augments. The N2_neighbor_iface_addr_list is defined by the nhdpDiscIfIndex, which is an index of the nhdpIibLinkSetTable, which this table augments." Herberg, et al. Standards Track [Page 32] RFC 7184 The OLSRv2-MIB April 2014 REFERENCE "RFC 7181 - The Optimized Link State Routing Protocol Version 2, Clausen, T., Dearlove, C., Jacquet, P., and U. Herberg, April 2014. and RFC 6779 - Definition of Managed Objects for the Neighborhood Discovery Process, Herberg, U., Cole, R., and I. Chakeres, October 2012." ::= { olsrv2Iib2HopSetEntry 2 } -- -- Local Information Base - as defined in RFC 6130, -- extended by the addition of an Originator Set, -- defined in Section 6.1 and a Local Attached -- Network Set, defined in Section 6.2. -- -- -- Originator Set -- olsrv2LibOrigSetTable OBJECT-TYPE SYNTAX SEQUENCE OF Olsrv2LibOrigSetEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "A router's Originator Set records addresses that were recently used as originator addresses by this router." REFERENCE "RFC 7181 - The Optimized Link State Routing Protocol Version 2, Clausen, T., Dearlove, C., Jacquet, P., and U. Herberg, April 2014." ::= { olsrv2StateGroup 3 } olsrv2LibOrigSetEntry OBJECT-TYPE SYNTAX Olsrv2LibOrigSetEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "A router's Originator Set consists of Originator Tuples: (O_orig_addr (olsrv2LibOrigSetIpAddrType and olsrv2LibOrigSetIpAddr), O_time (olsrv2LibOrigSetExpireTime))." Herberg, et al. Standards Track [Page 33] RFC 7184 The OLSRv2-MIB April 2014 REFERENCE "RFC 7181 - The Optimized Link State Routing Protocol Version 2, Clausen, T., Dearlove, C., Jacquet, P., and U. Herberg, April 2014." INDEX { olsrv2LibOrigSetIpAddrType, olsrv2LibOrigSetIpAddr } ::= { olsrv2LibOrigSetTable 1 } Olsrv2LibOrigSetEntry ::= SEQUENCE { olsrv2LibOrigSetIpAddrType InetAddressType, olsrv2LibOrigSetIpAddr InetAddress, olsrv2LibOrigSetExpireTime TimeStamp } olsrv2LibOrigSetIpAddrType OBJECT-TYPE SYNTAX InetAddressType { ipv4(1) , ipv6(2) } MAX-ACCESS not-accessible STATUS current DESCRIPTION "The type of the olsrv2LibOrigSetIpAddr, as defined in the InetAddress MIB (RFC4001). Only the values 'ipv4(1)' and 'ipv6(2)' are supported." REFERENCE "RFC 7181 - The Optimized Link State Routing Protocol Version 2, Clausen, T., Dearlove, C., Jacquet, P., and U. Herberg, April 2014." ::= { olsrv2LibOrigSetEntry 1 } olsrv2LibOrigSetIpAddr OBJECT-TYPE SYNTAX InetAddress (SIZE(4|16)) MAX-ACCESS not-accessible STATUS current DESCRIPTION "An originator address recently employed by this router." REFERENCE 's misuse of this control does not lock out other legitimate operations. Servers implementations may enforce an overriding sizelimit, to prevent the retrieval of large portions of a publically-accessible directory. Clients can, using this control, determine how many entries match a particular filter, before the entries are returned to the client. This may require special processing in servers which perform access control checks on entries to determine whether the existence of the 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. Weider, et al. Informational [Page 5] RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999 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 Weider, et al. Informational [Page 6] RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999 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. Weider, et al. Informational [Page 7]