[Docs] [txt|pdf] [Tracker] [Email] [Nits]

Versions: 00

   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


Html markup produced by rfcmarkup 1.129c, available from https://tools.ietf.org/tools/rfcmarkup/