idnits 2.17.1 draft-kashi-incremental-00.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): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. 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 abstract seems to contain references ([1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- 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.) -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2251 (ref. '1') (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) Summary: 7 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT Asaf Kashi 2 Category: Standards Track Richard Randall 3 Microsoft Corporation 4 Expires: May 2002 6 Incremental Retrieval of Multi-valued Properties 8 1. Status of this Memo 10 This document is an Internet-Draft and is in full conformance with 11 all provisions of Section 10 of RFC2026. 13 Internet-Drafts are working documents of the Internet Engineering 14 Task Force (IETF), its areas, and its working groups. Note that 15 other groups may also distribute working documents as Internet- 16 Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six 19 months and may be updated, replaced, or obsoleted by other documents 20 at any time. It is inappropriate to use Internet-Drafts as 21 reference material or to cite them other than as "work in progress." 23 The list of current Internet-Drafts can be accessed at 24 http://www.ietf.org/ietf/1id-abstracts.txt 26 The list of Internet-Draft Shadow Directories can be accessed at 27 http://www.ietf.org/shadow.html. 29 This document is intended to be submitted, after review and 30 revision, as a Standards Track document. Distribution of this memo 31 is unlimited. It is filed as , and 32 expires May, 2002. 34 Please send comments to the authors. 36 2. Abstract 38 The Lightweight Directory Access protocol [1] provides a means for 39 clients to read and write information stored in a distributed 40 directory system. This information is stored as attributes of 41 entries. The attributes may be multi-valued. The LDAP protocol 42 reads a multi-valued attribute as a single entity. This can be 43 inconvenient or even impossible when the number of values in a 44 multi-valued attribute becomes large. 45 This document defines an option ("Range") that can be specified as 46 part of an attribute description to retrieve the values of a multi- 47 valued attribute incrementally. Servers MAY honor the range option. 49 Incremental Retrieval of November 2001 50 Multi-valued Properties 52 3. Conventions used in this document 53 The key words ``MUST'', ``MUST NOT'', ``REQUIRED'', ``SHALL'', 54 ``SHALL NOT'', ``SHOULD'', ``SHOULD NOT'', ``RECOMMENDED'', and 55 ``MAY'' in this document are to be interpreted as described in RFC 56 2119 [2]. 58 4. The Range Option 60 Servers that support the range option MUST include the OID 61 1.2.840.113556.1.4.802 in the "supportedControls" operational 62 property on the Root DSE. Clients SHOULD NOT use the Range option 63 unless this OID is present. The Range option is a constant, case- 64 insensitive string value, "Range=", followed by a range-specifier as 65 defined below in 5.1. 67 5. Use of the Range Option in LDAP 69 This section defines how LDAP implementations MUST interpret Range 70 specifiers in performing operations. 72 An attribute with the Range option is considered to be a subtype of 73 the attribute without the Range option. If a server does not 74 support incremental retrieval of multi-valued attributes, then it 75 MUST always treat an attribute with a Range option as an 76 unrecognized attribute. 78 AttributeDescriptions containing the Range option are valid only 79 when presented by the client in the "attributes" field of a 80 SearchRequest or returned by the server in the "attributes" field of 81 a SearchResultEntry. If a client presents an AttributeDescription 82 containing the Range option in any other context the server SHOULD 83 treat it as an unrecognized attribute. 85 5.1 Attribute Description 87 An attribute consists of a type, a list of options for that type, 88 and a set of one or more values. In LDAP, the type and the options 89 are combined into the AttributeDescription, defined in section 4.1.5 90 of [1]. This is represented as an attribute type name and a 91 possibly-empty list of options. One of these options specifies the 92 zero-relative range of elements to be retrieved when presented in a 93 SearchRequest message. 95 range-option ::= "Range=" 96 range-specifier ::= ["-" ] 97 range-initial ::= *(0-9) 98 range-terminal::= (*(0-9))| 99 end-of-range ::= "*" 100 Incremental Retrieval of November 2001 101 Multi-valued Properties 103 There can be at most one Range option an AttributeDescription. 104 Examples of valid AttributeDescription: 106 member;Range=0-500 107 otherTelephoneNumber;Range=0-* 108 userCertificate;Range=21-305 110 5.2 Server Behavior 112 This section describes the behavior that all servers supporting 113 incremental retrieval of multi-valued properties via the Range 114 option MUST implement. A client MAY request all or any contiguous 115 subset of the elements of a multi-valued attribute using the range 116 specifier. The special character "*" indicates the end of the range 117 when used as the terminal value in a range specifier. The server 118 MUST return a Range option in the SearchResultEntry for all 119 attributes in the SearchRequest that contained a valid Range option. 120 A given Range option is treated as valid by the server if: 122 it is well-formed according to 5.1 123 range-initial is less than or equal to range-terminal 124 range-initial is less than or equal to the actual count of 125 values stored in the multi-valued attribute 127 The server MUST treat any AttributeDescription containing a valid 128 attribute type with an invalid Range option as an error and return 129 an empty set of values for the attribute in the SearchResultEntry 130 message. 132 The Range option returned by the server in any given 133 AttributeDescription indicates the actual range returned. The 134 server MUST return the "*" character as the terminal value for a 135 range when the last element in the multi-valued property is returned 136 in the SearchResultEntry message. The server MAY omit the Range 137 option if the complete set of values for the attribute is returned. 138 If the server omits the Range option in a returned 139 AttributeDescription the client SHOULD assume the complete set of 140 values has been returned. Examples of valid AttributeDescriptions 141 returned by the server: 143 member;Range=0-384 144 otherTelephoneNumber;Range=0-2 145 userCertificate;Range=21 146 userCertificate;Range=11-* 148 The server MAY return fewer elements than requested by the client. 149 The client SHOULD make additional requests to obtain the remainder. 151 Example of a server returning fewer elements than requested: 153 Client Request Server Response 154 member;Range=0-5000 member;Range=0-500 155 Incremental Retrieval of November 2001 156 Multi-valued Properties 158 member;Range=501-5000 member;Range=501-* 160 A server that supports the Range option MAY limit the maximum number 161 of elements for a given multi-valued attribute that can be returned 162 in a single request. This allows the server to control the amount 163 of resources required to service the retrieval of multi-valued 164 properties. 166 Example of a client server exchange with a server that limits 167 retrievals to 500 items: 169 Client Request Server Response 170 member;Range=0-* member;Range=0-500 171 member;Range=501-* member;Range=501-1000 172 member;Range=1001-* member;Range=1000-1307 174 The server MUST NOT return an AttributeDescription with a Range 175 option specified for any attribute unless the client specified a 176 Range option for that AttributeDescription in the SearchRequest. 178 If the client does not provide the Range option for a given 179 property, and the server cannot return all elements of that property 180 because doing so would exceed the administrative limit, then the 181 server MUST return: 183 an empty result for the requested attribute 184 an additional AttributeDescription with a Range option for the 185 requested Attribute populated with values per the range specifier. 187 This allows a server to limit the number of elements returned for a 188 multi-valued property for which no Range option was specified and 189 report the number of elements returned. 191 Example of a client server exchange between a client specifying no 192 explicit range and a server that limits retrievals to 500 items and 193 where the number of elements in the multi-valued property exceeds 194 the administrative limit: 196 Client Request Server Response 197 member member=,member;Range= 198 0-499="member1;member2,�,member500" 200 5.3 Element Ordering 202 For a client to specify a range of elements in a multi-valued 203 Attribute, there must be some concept of order. There is no implied 204 ordering in the values of a multi-valued property (see [1], 4.1.8). 205 The order of elements returned by the Range option is arbitrary 206 (e.g. unsorted) but constant for the duration of a given LDAP 207 connection if and only if the Attribute is not modified by another 208 client between successive range requests. Modification of a multi- 209 valued property while it is being fetched by successive range 210 Incremental Retrieval of November 2001 211 Multi-valued Properties 213 requests may result in overlapping, duplicated, or skipped elements 214 in the SearchResultEntry messages sent in response to the range 215 requests. Logically adjacent range requests issued on different 216 LDAP Sessions are not guaranteed to return contiguous result sets 217 and clients SHOULD NOT issue requests in this manner. 219 6. Security Considerations 221 There are no known security considerations for this document. See 222 the security considerations sections of [1] for security 223 considerations of LDAP in general. 225 7. Acknowledgements 227 This document is based upon work done by S. Judd, A. Herron, and T. 228 Williams. 230 8. References 232 [1] Wahl, M., Kille, S. and Howes, T., "Lightweight Directory Access 233 Protocol (v3)", Internet Standard, RFC 2251, December, 1997. 235 [2] Bradner, S., "Key words for use in RFCs to Indicate Requirement 236 Levels", BCP 14, RFC 2119, March 1997. 238 9. Author's Addresses 240 Asaf Kashi 241 Microsoft Corp. 242 1 Microsoft Way 243 Redmond, WA 98052 244 USA 245 asafk@microsoft.com 246 +1 425 882-8080 248 Richard Randall 249 Microsoft Corp. 250 1 Microsoft Way 251 Redmond, WA 98052 252 USA 253 rrandall@microsoft.com 254 +1 425 882-8080 256 10. Full Copyright Statement 258 Copyright (C) The Internet Society (2001). All Rights Reserved. 259 This document and translations of it may be copied and furnished to 260 Incremental Retrieval of November 2001 261 Multi-valued Properties 263 others, and derivative works that comment on or otherwise explain it 264 or assist in its implementation may be prepared, copied, published 265 and distributed, in whole or in part, without restriction of any 266 kind, provided that the above copyright notice and this paragraph 267 are included on all such copies and derivative works. However, this 268 document itself may not be modified in any way, such as by removing 269 the copyright notice or references to the Internet Society or other 270 Internet organizations, except as needed for the purpose of 271 developing Internet standards in which case the procedures for 272 copyrights defined in the Internet Standards process must be 273 followed, or as required to translate it into languages other than 274 English. The limited permissions granted above are perpetual and 275 will not be revoked by the Internet Society or its successors or 276 assigns. This document and the information contained herein is 277 provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE 278 INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR 279 IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 280 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 281 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."