
   INTERNET-DRAFT                                            Asaf Kashi 
   Category: Standards Track                            Richard Randall 
   <draft-kashi-incremental-00.txt>               Microsoft Corporation 
   Expires: May 2002 
    
    
             Incremental Retrieval of Multi-valued Properties 
    
    
1. Status of this Memo 
 
   This document is an Internet-Draft and is in full conformance with 
   all provisions of Section 10 of RFC2026. 
    
   Internet-Drafts are working documents 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." 
    
   The list of current Internet-Drafts can be accessed at 
   http://www.ietf.org/ietf/1id-abstracts.txt 
    
   The list of Internet-Draft Shadow Directories can be accessed at 
   http://www.ietf.org/shadow.html. 
    
   This document is intended to be submitted, after review and 
   revision, as a Standards Track document.  Distribution of this memo 
   is unlimited.  It is filed as <draft-kashi-incremental-00.txt>, and 
   expires May, 2002. 
    
   Please send comments to the authors. 
    
    
2. Abstract 
    
   The Lightweight Directory Access protocol [1] provides a means for 
   clients to read and write information stored in a distributed 
   directory system.  This information is stored as attributes of 
   entries.  The attributes may be multi-valued.  The LDAP protocol 
   reads a multi-valued attribute as a single entity.  This can be 
   inconvenient or even impossible when the number of values in a 
   multi-valued attribute becomes large.   
   This document defines an option ("Range") that can be specified as 
   part of an attribute description to retrieve the values of a multi-
   valued attribute incrementally.  Servers MAY honor the range option. 
    
    
     
   Kashi and Randall       Standards Track                          1 
                       Incremental Retrieval of          November 2001 
                       Multi-valued Properties 
    
3. Conventions used in this document 
   The key words ``MUST'', ``MUST NOT'', ``REQUIRED'', ``SHALL'', 
   ``SHALL NOT'', ``SHOULD'', ``SHOULD NOT'', ``RECOMMENDED'', and 
   ``MAY'' in this document are to be interpreted as described in RFC 
   2119 [2]. 
    
    
4. The Range Option 
    
   Servers that support the range option MUST include the OID 
   1.2.840.113556.1.4.802 in the "supportedControls" operational 
   property on the Root DSE.  Clients SHOULD NOT use the Range option 
   unless this OID is present.  The Range option is a constant, case-
   insensitive string value, "Range=", followed by a range-specifier as 
   defined below in 5.1. 
    
    
5. Use of the Range Option in LDAP 
    
   This section defines how LDAP implementations MUST interpret Range 
   specifiers in performing operations. 
    
   An attribute with the Range option is considered to be a subtype of 
   the attribute without the Range option.  If a server does not 
   support incremental retrieval of multi-valued attributes, then it 
   MUST always treat an attribute with a Range option as an 
   unrecognized attribute. 
    
   AttributeDescriptions containing the Range option are valid only 
   when presented by the client in the "attributes" field of a 
   SearchRequest or returned by the server in the "attributes" field of 
   a SearchResultEntry.  If a client presents an AttributeDescription 
   containing the Range option in any other context the server SHOULD   
   treat it as an unrecognized attribute. 
    
    
5.1 Attribute Description 
    
   An attribute consists of a type, a list of options for that type, 
   and a set of one or more values.  In LDAP, the type and the options 
   are combined into the AttributeDescription, defined in section 4.1.5 
   of [1]. This is represented as an attribute type name and a 
   possibly-empty list of options.  One of these options specifies the 
   zero-relative range of elements to be retrieved when presented in a  
   SearchRequest message. 
    
           range-option ::= "Range=" <range-specifier> 
           range-specifier ::= <range-initial> ["-" <range-terminal>] 
           range-initial ::= *(0-9) 
           range-terminal::= (*(0-9))| <end-of-range> 
           end-of-range ::= "*" 
    
    
   Kashi and Randall       Standards Track                          2 
                       Incremental Retrieval of          November 2001 
                       Multi-valued Properties 
    
   There can be at most one Range option an AttributeDescription. 
   Examples of valid AttributeDescription: 
    
           member;Range=0-500 
           otherTelephoneNumber;Range=0-* 
           userCertificate;Range=21-305 
    
    
5.2 Server Behavior 
    
   This section describes the behavior that all servers supporting 
   incremental retrieval of multi-valued properties via the Range 
   option MUST implement.  A client MAY request all or any contiguous 
   subset of the elements of a multi-valued attribute using the range 
   specifier.  The special character "*" indicates the end of the range 
   when used as the terminal value in a range specifier.  The server 
   MUST return a Range option in the SearchResultEntry for all 
   attributes in the SearchRequest that contained a valid Range option.  
   A given Range option is treated as valid by the server if: 
    
        it is well-formed according to 5.1 
        range-initial is less than or equal to range-terminal 
        range-initial is less than or equal to the actual count of 
   values stored in the multi-valued attribute 
    
   The server MUST treat any AttributeDescription containing a valid 
   attribute type with an invalid Range option as an error and return 
   an empty set of values for the attribute in the SearchResultEntry 
   message. 
    
   The Range option returned by the server in any given 
   AttributeDescription indicates the actual range returned.  The 
   server MUST return the "*" character as the terminal value for a 
   range when the last element in the multi-valued property is returned 
   in the SearchResultEntry message.  The server MAY omit the Range 
   option if the complete set of values for the attribute is returned.  
   If the server omits the Range option in a returned 
   AttributeDescription the client SHOULD assume the complete set of 
   values has been returned. Examples of valid AttributeDescriptions 
   returned by the server: 
    
           member;Range=0-384 
           otherTelephoneNumber;Range=0-2 
           userCertificate;Range=21 
           userCertificate;Range=11-* 
    
   The server MAY return fewer elements than requested by the client.  
   The client SHOULD make additional requests to obtain the remainder. 
    
   Example of a server returning fewer elements than requested: 
    
           Client Request          Server Response 
           member;Range=0-5000     member;Range=0-500 
    
   Kashi and Randall       Standards Track                          3 
                       Incremental Retrieval of          November 2001 
                       Multi-valued Properties 
    
           member;Range=501-5000   member;Range=501-* 
    
   A server that supports the Range option MAY limit the maximum number 
   of elements for a given multi-valued attribute that can be returned 
   in a single request.  This allows the server to control the amount 
   of resources required to service the retrieval of multi-valued 
   properties.   
    
   Example of a client server exchange with a server that limits 
   retrievals to 500 items: 
    
           Client Request        Server Response 
           member;Range=0-*      member;Range=0-500 
           member;Range=501-*    member;Range=501-1000 
           member;Range=1001-*   member;Range=1000-1307 
    
   The server MUST NOT return an AttributeDescription with a Range 
   option specified for any attribute unless the client specified a 
   Range option for that AttributeDescription in the SearchRequest.  
    
   If the client does not provide the Range option for a given 
   property, and the server cannot return all elements of that property 
   because doing so would exceed the administrative limit, then the 
   server MUST return: 
    
        an empty result for the requested attribute 
        an additional AttributeDescription with a Range option for the 
   requested Attribute populated with values per the range specifier. 
    
   This allows a server to limit the number of elements returned for a 
   multi-valued property for which no Range option was specified and 
   report the number of elements returned. 
    
   Example of a client server exchange between a client specifying no 
   explicit range and a server that limits retrievals to 500 items and 
   where the number of elements in the multi-valued property exceeds 
   the administrative limit: 
    
           Client Request        Server Response 
           member                member=,member;Range= 
                                 0-499="member1;member2,,member500" 
    
    
5.3 Element Ordering 
    
   For a client to specify a range of elements in a multi-valued 
   Attribute, there must be some concept of order.  There is no implied 
   ordering in the values of a multi-valued property (see [1], 4.1.8). 
   The order of elements returned by the Range option is arbitrary 
   (e.g. unsorted) but constant for the duration of a given LDAP 
   connection if and only if the Attribute is not modified by another 
   client between successive range requests.  Modification of a multi-
   valued property while it is being fetched by successive range 
    
   Kashi and Randall       Standards Track                          4 
                       Incremental Retrieval of          November 2001 
                       Multi-valued Properties 
    
   requests may result in overlapping, duplicated, or skipped elements 
   in the SearchResultEntry messages sent in response to the range 
   requests.  Logically adjacent range requests issued on different 
   LDAP Sessions are not guaranteed to return contiguous result sets 
   and clients SHOULD NOT issue requests in this manner. 
    
    
6. Security Considerations 
    
   There are no known security considerations for this document.  See 
   the security considerations sections of [1] for security 
   considerations of LDAP in general. 
    
    
7. Acknowledgements 
    
   This document is based upon work done by S. Judd, A. Herron, and T. 
   Williams. 
    
    
8. References 
    
   [1] Wahl, M., Kille, S. and Howes, T., "Lightweight Directory Access 
       Protocol (v3)", Internet Standard, RFC 2251, December, 1997. 
    
   [2] Bradner, S., "Key words for use in RFCs to Indicate Requirement 
       Levels", BCP 14, RFC 2119, March 1997. 
    
    
9. Author's Addresses 
    
   Asaf Kashi 
   Microsoft Corp. 
   1 Microsoft Way 
   Redmond, WA 98052 
   USA 
   asafk@microsoft.com 
   +1 425 882-8080 
    
   Richard Randall 
   Microsoft Corp. 
   1 Microsoft Way 
   Redmond, WA 98052 
   USA 
   rrandall@microsoft.com 
   +1 425 882-8080 
    
    
10. Full Copyright Statement 
    
   Copyright (C) The Internet Society (2001).  All Rights Reserved. 
   This document and translations of it may be copied and furnished to 
    
   Kashi and Randall       Standards Track                          5 
                       Incremental Retrieval of          November 2001 
                       Multi-valued Properties 
    
   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." 
    
    
    
   Kashi and Randall       Standards Track                          6 
