idnits 2.17.1 draft-ietf-asid-ldapv3-simplepaged-03.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-19) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 240 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 72: '...lts are returned MAY specify on the se...' RFC 2119 keyword, line 74: '...The page size specified MAY be greater...' RFC 2119 keyword, line 81: '...trol, the server MUST return an error ...' RFC 2119 keyword, line 83: '...rwise the server SHOULD ignore the con...' RFC 2119 keyword, line 90: '... to the client, the size MAY be set to...' (11 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 56 has weird spacing: '...olValue sea...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (August 7, 1998) is 9387 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'Bradner97' is defined on line 200, but no explicit reference was found in the text == Outdated reference: A later version (-09) exists of draft-ietf-asid-ldapv3-protocol-04 -- Unexpected draft version: The latest known version of draft-bradner-key-words is -02, but you're referring to -03. Summary: 11 errors (**), 0 flaws (~~), 5 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group Chris Weider, Microsoft 2 INTERNET DRAFT Andy Herron, Microsoft 3 Anoop Anantha, Microsoft 4 Tim Howes, Netscape 5 August 7, 1998 7 LDAP Control Extension for Simple Paged Results Manipulation 8 10 0. Status of this Memo 12 This document is an Internet-Draft. Internet-Drafts are working 13 documents of the Internet Engineering Task Force (IETF), its 14 areas, and its working groups. Note that other groups may also 15 distribute working documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six 18 months and may be updated, replaced, or obsoleted by other 19 documents at any time. It is inappropriate to use Internet- 20 Drafts as reference material or to cite them other than as 21 ``work in progress.'' 23 To learn the current status of any Internet-Draft, please check 24 the ``1id-abstracts.txt'' listing contained in the Internet- 25 Drafts Shadow Directories on ftp.ietf.org (US East Coast), 26 nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or 27 munnari.oz.au (Pacific Rim). 29 This draft expires February 7, 1999. 31 1. Abstract 33 This document describes an LDAPv3 control extension for simple paging 34 of search results. This control extension allows a client to control 35 the rate at which an LDAP server returns the results of an LDAP search 36 operation. This control may be useful when the LDAP client has limited 37 resources and may not be able to process the entire result set from a 38 given LDAP query, or when the LDAP client is connected over a 39 low-bandwidth connection. Other operations on the result set are not 40 defined in this extension. This extension is not designed to provide 41 more sophisticated result set management. 43 The key words "MUST", "SHOULD", and "MAY" used in this document are to 44 be interpreted as described in [bradner97]. 46 2. The Control 48 This control is included in the searchRequest and searchResultDone 49 messages as part of the controls field of the LDAPMessage, as defined 50 in Section 4.1.12 of [LDAPv3]. The structure of this control is as 51 follows: 53 pagedResultsControl ::= SEQUENCE { 54 controlType 1.2.840.113556.1.4.319, 55 criticality BOOLEAN DEFAULT FALSE, 56 controlValue searchControlValue 57 } 59 The searchControlValue is an OCTET STRING wrapping the BER-encoded 60 version of the following SEQUENCE: 62 realSearchControlValue ::= SEQUENCE { 63 size INTEGER (0..maxInt), 64 -- requested page size from client 65 -- result set size estimate from server 66 cookie OCTET STRING 67 } 69 3. Client-Server Interaction 71 An LDAP client application that needs to control the rate at which 72 results are returned MAY specify on the searchRequest a 73 pagedResultsControl with size set to the desired page size and cookie 74 set to the zero-length string. The page size specified MAY be greater 75 than zero and less than the sizeLimit value specified in the 76 searchRequest. 78 If the page size is greater than or equal to the sizeLimit value, 79 the server should ignore the control as the request can 80 be satisfied in a single page. If the server does not support this 81 control, the server MUST return an error of 82 unsupportedCriticalExtension if the client requested it as critical, 83 otherwise the server SHOULD ignore the control. The remainder of this 84 section assumes the server does not ignore the client's 85 pagedResultsControl. 87 Each time the server returns a set of results to the client when 88 processing a search request containing the pagedResultsControl, the 89 server includes the pagedResultsControl control in the searchResultDone 90 message. In the control returned to the client, the size MAY be set to 91 the server's estimate of the total number of entries in the entire 92 result set. Servers that cannot provide such an estimate MAY set this 93 size to zero (0). The cookie MUST be set to an empty value if there 94 are no more entries to return (i.e., the page of search results 95 returned was the last), or, if there are more entries to return, 96 to an octet string of the server's choosing,used to resume the search. 98 The client MUST consider the cookie to be an opaque structure and make 99 no assumptions about its internal organization or value. When the 100 client wants to retrieve more entries for the result set, it MUST send 101 to the server a searchRequest with all values identical to the initial 102 request with the exception of the messageID, the cookie, and optionally 103 a modified pageSize. The cookie MUST be the octet string on the last 104 searchResultDone response returned by the server. Returning cookies 105 from previous searchResultDone responses besides the last one is 106 undefined, as the server implementation may restrict cookies from being 107 reused. 109 The server will then return the next set of results from the whole 110 result set. This interaction will continue until the client has 111 retrieved all the results, in which case the cookie in the 112 searchResultDone field will be empty, or until the client abandons the 113 search sequence as described below. Once the paged search sequence 114 has been completed, the cookie is no longer valid and MUST NOT be 115 used. 117 A sequence of paged search requests is abandoned by the client sending 118 a search request containing a pagedResultsControl with the size set to 119 zero (0) and the cookie set to the last cookie returned by the server. 120 A client MAY use the LDAP Abandon operation to abandon one paged search 121 request in progress, but this is discouraged as it MAY invalidate the 122 client's cookie. 124 If, for any reason, the server cannot resume a paged search operation 125 for a client, then it SHOULD return the appropriate error in a 126 searchResultDone entry. If this occurs, both client and server should 127 assume the paged result set is closed and no longer resumable. 129 A client may have any number of outstanding search requests pending, 130 any of which may have used the pagedResultsControl. A server 131 implementation which requires a limit on the number of outstanding 132 paged search requests from a given client MAY either return 133 unwillingToPerform when the client attempts to create a new paged 134 search request, or age out an older result set. If the server 135 implementation ages out an older paged search request, it SHOULD return 136 "unwilling to perform" if the client attempts to resume the paged search 137 that 138 was aged out. 140 A client may safely assume that all entries that satisfy a given search 141 query are returned once and only once during the set of paged search 142 requests/responses necessary to enumerate the entire result set, unless 143 the result set for that query has changed since the searchRequest 144 starting the request/response sequence was processed. In that case, the 145 client may receive a given entry multiple times and/or may not receive 146 all entries matching the given search criteria. 148 4. Example 150 The following example illustrates the client-server interaction between 151 a client doing a search requesting a page size limit of 3. The entire 152 result set returned by the server contains 5 entries. 154 Lines beginning with "C:" indicate requests sent from client to 155 server. Lines beginning with "S:" indicate responses sent from 156 server to client. Lines beginning with "--" are comments to 157 help explain the example. 159 -- Client sends a search request asking for paged results 160 -- with a page size of 3. 161 C: SearchRequest + pagedResultsControl(3,"") 162 -- Server responds with three entries plus an indication 163 -- of 5 total entries in the search result and an opaque 164 -- cooking to be used by the client when retrieving subsequent 165 -- pages. 166 S: SearchResultEntry 167 S: SearchResultEntry 168 S: SearchResultEntry 169 S: SearchResultDone + pagedResultsControl(5, "opaque") 170 -- Client sends an identical search request (except for 171 -- message id), returning the opaque cooking, asking for 172 -- the next page. 173 C: SearchRequest + PagedResultsControl(3, "opaque") 174 -- Server responds with two entries plus an indication 175 -- that there are no more entries (null cookie). 176 S: SearchResultEntry 177 S: SearchResultEntry 178 S: SearchResultDone + pagedResultsControl(5,"") 180 5. Relationship to X.500 182 For LDAP servers providing a front end to X.500 (93) directories, 183 the paged results control defined in this document may be 184 mapped directly onto the X.500 (93) PagedResultsRequest defined 185 in X.511 [x500]. The size parameter may be mapped onto pageSize. 186 The cookie parameter may be mapped onto queryReference. 187 The sortKeys and reverse fields in the X.500 PagedResultsRequest 188 are excluded. 190 6. Security Considerations 192 Security considerations are not discussed in this document. 194 7. References 195 [LDAPv3] 196 Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access Protocol 197 (v3)", Internet Draft, February, 1997. Available as 198 draft-ietf-asid-ldapv3-protocol-04.txt. 200 [Bradner97] 201 Bradner, Scott, "Key Words for use in RFCs to Indicate Requirement 202 Levels", 203 Internet Draft, January, 1997. Available as 204 draft-bradner-key-words-03.txt. 206 8. Author's Address 208 Chris Weider 209 Microsoft Corp. 210 1 Microsoft Way 211 Redmond, WA 98052 212 USA 213 cweider@microsoft.com 214 +1 425 882-8080 216 Andy Herron 217 Microsoft Corp. 218 1 Microsoft Way 219 Redmond, WA 98052 220 USA 221 andyhe@microsoft.com 222 +1 425 882-8080 224 Anoop Anantha 225 Microsoft Corp. 226 1 Microsoft Way 227 Redmond, WA 98052 228 USA 229 anoopa@microsoft.com 230 +1 425 882-8080 232 Tim Howes 233 Netscape Communications Corp. 234 501 E. Middlefield Road 235 Mountain View, CA 94043 236 USA 237 howes@netscape.com 238 +1 415 937-2600