]> git.sur5r.net Git - openldap/commitdiff
Replace extended partial response with intermediate response draft.
authorKurt Zeilenga <kurt@openldap.org>
Fri, 8 Jun 2001 01:43:03 +0000 (01:43 +0000)
committerKurt Zeilenga <kurt@openldap.org>
Fri, 8 Jun 2001 01:43:03 +0000 (01:43 +0000)
doc/drafts/draft-rharrison-ldap-extpartresp-xx.txt [deleted file]
doc/drafts/draft-rharrison-ldap-intermediate-resp-xx.txt [new file with mode: 0644]

diff --git a/doc/drafts/draft-rharrison-ldap-extpartresp-xx.txt b/doc/drafts/draft-rharrison-ldap-extpartresp-xx.txt
deleted file mode 100644 (file)
index 76a1a47..0000000
+++ /dev/null
@@ -1,159 +0,0 @@
-
-Individual Submission to LDAPExt Working Group              R. Harrison
-Internet Draft                                             Novell, Inc.
-Document: draft-rharrison-ldap-extpartresp-01.txt            June, 2000
-Category: Proposed Standard
-
-
-                       Extended Partial Response
-                    Protocol Enhancement to LDAP v3
-
-
-Status of this Memo
-
-   This document is an Internet-Draft and is in full conformance with
-   all provisions of Section 10 of RFC2026 [1].
-
-   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.
-
-
-1. Abstract
-
-   This document describes the ExtendedPartialResponse, an element of
-   LDAP v3 protocol which allows multiple responses to LDAP v3 extended
-   requests.  Extended partial responses are backward compatible with
-   the existing LDAP v3 Extended Operation defined in [LDAPv3].
-
-2. Conventions used in this document
-
-   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
-   "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in
-   this document are to be interpreted as described in [RFC2119].
-
-
-3. Motivation for the Extended Partial Response
-
-   The Extended Operation ([LDAPv3] Section 4.12) was defined in LDAP
-   v3 to allow additional operations to be defined as part of the
-   protocol without requiring a new revision of the protocol.
-
-   The LDAP v3 Extended Operation allows for a single extended response
-   to each extended request, but this paradigm may not be sufficient
-   for some directory operations.  For instance, the LDAP search
-   operation is a directory operation that is much more efficient when
-   multiple partial responses are used to service a single request. The
-\f
-                  LDAP v3 Extended Partial Response         June, 2000
-
-
-   extended partial response generalizes the current extended operation
-   definition to give LDAP server implementers the ability to make use
-   of a single-request-multiple-response paradigm for extended LDAP
-   operations that require it or that would benefit from it.
-
-4. Element of Protocol
-
-   The ExtendedPartialResponse is defined as
-
-   ExtendedPartialResponse ::= [APPLICATION 25] SEQUENCE {
-           responseName     [0] LDAPOID OPTIONAL,
-           response         [1] OCTET STRING OPTIONAL }
-
-   An LDAP server responds to an LDAP v3 ExtendedRequest with zero or
-   more ExtendedPartialResponses followed by one ExtendedResponse. This
-   ensures backward compatibility with existing LDAP extensions which
-   do not make use of the ExtendedPartialResponse.  As with all LDAP
-   extensions, LDAP extensions that make use of the
-   ExtendedPartialResponse have predefined syntax and semantics that
-   are defined in RFCs or are private to a particular implementation.
-
-5. Security Considerations
-
-   This draft describes an enhancement to the LDAP v3 protocol
-   [LDAPv3].  All security considerations of [LDAPv3] apply to this
-   draft, however it does not introduce any new security considerations
-   to the LDAP v3 protocol.
-
-6. References
-
-    [LDAPv3]
-        Wahl, M., Howes, T., and S. Kille, "Lightweight Directory
-        Access Protocol (v3)", RFC 2251, December 1997.
-
-   [ReqsKeywords]
-        Scott Bradner. "Key Words for use in RFCs to Indicate
-        Requirement Levels". RFC 2119.
-
-
-7. Acknowledgments
-
-   The author would like to acknowledge the readers of the LDAP
-   Extensions working group mail list who responded to the suggestion
-   that a multiple-response paradigm might be useful for LDAP extended
-   requests.  Special thanks go to two individuals: David Wilbur who
-   first introduced the idea on the working group list, and Thomas
-   Salter, who succinctly summarized the discussion and suggested the
-   name ExtendedPartialResponse in his summary.
-
-8. Author's Addresses
-
-   Roger Harrison
-   Novell, Inc.
-\f
-                  LDAP v3 Extended Partial Response         June, 2000
-
-
-   1800 S. Novell Place
-   Provo, UT 84606
-   +1 801 861 2642
-   roger_harrison@novell.com
-
-
-Appendix A - Document Revision History
-
-A.1 draft-rharrison-ldap-extPartResp-00.doc
-
-   Initial revision of draft.
-
-A.2 draft-rharrison-ldap-extPartResp-01.doc
-
-   Changed responseName to be optional to align with [LDAPv3]
-   definition of ExtendedResponse.
-
-Full Copyright Statement
-
-   "Copyright (C) The Internet Society (date). 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 implmentation 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.
diff --git a/doc/drafts/draft-rharrison-ldap-intermediate-resp-xx.txt b/doc/drafts/draft-rharrison-ldap-intermediate-resp-xx.txt
new file mode 100644 (file)
index 0000000..d61f511
--- /dev/null
@@ -0,0 +1,413 @@
+
+
+Individual Submission to ldapext Working Group        Roger G. Harrison
+Internet Draft                                             Novell, Inc.
+Intended Category: Standards Track
+                                                       Kurt D. Zeilenga
+                                                    OpenLDAP Foundation
+
+                                                         March 30, 2001
+
+
+
+                       LDAP Intermediate Response
+             <draft-rharrison-ldap-intermediate-resp-00.txt>
+
+
+Status of this Memo
+
+   This document is an Internet-Draft and is in full conformance with
+   all provisions of Section 10 of RFC2026.
+
+   This document is intended to be, after appropriate review and
+   revision, submitted to the RFC Editor as a Standard Track document.
+
+   Distribution of this memo is unlimited.  Technical discussion of
+   this document will take place on the IETF LDAP Extensions Working
+   Group (ldapext) mailing list <ietf-ldapext@netscape.com>.  Please
+   send editorial comments directly to the document editor
+   <roger_harrison@novell.com>.
+
+   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.
+
+1. Abstract
+
+   This document extends LDAPv3 to provide a general mechanism for
+   defining single-request/multiple-response operations by defining and
+   describing the IntermediateResponse message.
+
+
+2. Background and Intended Usage
+
+   The Lightweight Directory Access Protocol, version 3 [LDAPv3] is an
+   extensible protocol. Extended operations ([LDAPv3] Section 4.12) are
+   defined to allow operations to be added to LDAP without requiring a
+   new revision of the protocol. Similarly, controls ([LDAPv3] section
+
+Harrison & Zeilenga        Expires September 30, 2001         [Page 1]
+\f
+                     LDAPv3 Intermediate Response       March 30, 2001
+
+
+   4.1.12) are defined to extend or modify the behavior of existing
+   LDAP operations.
+
+   LDAPv3 is a client-request/server-response based protocol. With the
+   exception of the search operation, the entire response to an
+   operation request is returned in a single protocol data unit (LDAP
+   message).  While this single-request/single-response paradigm is
+   sufficient for many operations (including almost all but one of
+   those currently defined by [LDAPv3]), both intuition and practical
+   experience validate the notion that it is insufficient for some
+   operations.
+
+   For example, the LDAPv3 delete operation could be extended via a
+   subtree control to mean that an entire subtree is to be deleted. A
+   subtree delete operation needs to return continuation references
+   based upon subordinate knowledge information contained in the server
+   so that the client can complete the operation. Returning references
+   as they are found instead of with the final result allows the client
+   to progress the operation more efficiently because it does not have
+   to wait for the final result to get this continuation reference
+   information.
+
+   Similarly, an engineer might choose to design the subtree delete
+   operation as an extended operation of its own rather than using a
+   subtree control in conjunction with the delete operation. Once
+   again, the same continuation reference information is needed by the
+   client to complete the operation, and sending the continuation
+   references as they are found would allow the client progress the
+   operation more efficiently.
+
+   Operations that complete in stages or that progress through various
+   states as they complete might want to send intermediate responses to
+   the client apprising it of the status of the operation. For example,
+   an LDAP implementation might define an extended operation to create
+   a new replica of an administrative area on a server, and the
+   operation completes in three stages: (1) begin creation of replica,
+   (2) send replica data to server, (3) replica creation complete.
+   Intermediate messages might be sent from the server to the client at
+   the beginning of stages (1) and (2) with the final response for the
+   extended operation being sent for stage (3).
+
+   As LDAPv3 is currently defined, there is no general LDAP message
+   type that can be used to return intermediate results.  A single,
+   reusable LDAP message for carrying intermediate response information
+   is desired to avoid repeated modification of the protocol.  Although
+   the ExtendedResponse message is defined in LDAPv3, it is defined to
+   be the one and only response message to an ExtendedRequest message
+   ([LDAPv3] Section 4.12, also see Section 6 below), for unsolicited
+   responses (LDAPv3 Section 4.4), and to return intermediate responses
+   for the search operation ([LDAPv3] Section 4.5.2). The adaptation of
+   ExpendedResponse as a general intermediate response mechanism would
+   be problematic.  In particular, existing APIs would likely have to
+   be redesigned.  It is believed (based upon operational experience)
+
+Harrison & Zeilenga         Expires September 30, 2001        [Page 2]
+\f
+                     LDAPv3 Intermediate Response       March 30, 2001
+
+
+   the addition of a new message to carry intermediate result
+   information is easier to implement.
+
+   This document defines the LDAPv3 IntermediateResponse message. This
+   message is intended to be used (1) in conjunction with
+   ExtendedRequest and ExtendedResponse to define new single-
+   request/multiple-response operations and (2) in conjunction with a
+   control when extending existing operations in a way that requires
+   them to return intermediate response information.
+
+   It is intended that the definitions and descriptions of extended
+   operations and controls that make use of the IntermediateResponse
+   message will define the circumstances when a IntermediateResponse
+   message can be sent by a server and the associated meaning of a
+   IntermediateResponse message sent in a particular circumstance.
+   Similarly, it is intended that clients will explicitly solicit
+   IntermediateResponse messages by issuing operations that
+   specifically call for their return.
+
+
+3. Conventions used in this document
+
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+   "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in
+   this document are to be interpreted as described in [ReqsKeywords].
+
+   The term "request control" is used to describe a control that is
+   included in an LDAPv3 request message sent from an LDAPv3 client to
+   an LDAPv3 server.
+
+
+4. The IntermediateResponse PDU
+
+   This document extends the protocolOp CHOICE of LDAPMessage ([LDAPv3]
+   Section 4.1.1) to include the field:
+
+           intermediateResponse  IntermediateResponse
+
+   where IntermediateResponse is defined as:
+
+           IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
+                   responseName     [0] LDAPOID OPTIONAL,
+                   responseValue    [1] OCTET STRING OPTIONAL }
+
+   IntermediateResponse messages SHALL NOT be returned to the client
+   unless the client issues a request that specifically solicits their
+   return.  This document defines two forms of solicitation: extended
+   operation and request control.
+
+   Although the responseName and responseValue are optional in some
+   circumstances, generally speaking IntermediateResponse messages have
+   a predefined responseName and a responseValue. The value of the
+   responseName (if present), the syntax of the responseValue (if
+
+Harrison & Zeilenga         Expires September 30, 2001        [Page 3]
+\f
+                     LDAPv3 Intermediate Response       March 30, 2001
+
+
+   present) and the semantics associated with a particular
+   IntermediateResponse message MUST be specified in documents
+   describing the extended operation or request control that uses them.
+   Sections 4.1 and 4.2 describe additional requirements on the
+   inclusion of responseName and responseValue in IntermediateResponse
+   messages.
+
+
+4.1. Usage with LDAPv3 ExtendedRequest and ExtendedResponse
+
+   A single-request/multiple-response operation may be defined using a
+   single ExtendedRequest message to solicit zero or more
+   IntermediateResponse messages of one or more kinds followed by an
+   ExtendedResponse message.
+
+   An extended operation that defines the return of multiple kinds of
+   IntermediateResponse messages MUST provide and document a mechanism
+   for the client to distinguish the kind of IntermediateResponse
+   message being sent. This SHALL be accomplished by using different
+   responseName values for each type of IntermediateResponse message
+   associated with the extended operation or by including identifying
+   information in the responseValue of each type of
+   IntermediateResponse message associated with the extended operation.
+
+4.2. Usage with LDAPv3 Request Controls
+
+   Any LDAPv3 operation may be extended by the addition of one or more
+   controls. A control's semantics may include the return of zero or
+   more IntermediateResponse messages prior to returning the final
+   result code for the operation. One or more kinds of
+   IntermediateResponse messages may be sent in response to a request
+   control.
+
+   All IntermediateResponse messages associated with request controls
+   SHALL include a responseName. This requirement ensures that the
+   client can correctly identify the source of IntermediateResponse
+   messages when
+
+           (a) two or more controls using IntermediateResponse messages
+               are included in a request for any LDAPv3 operation or
+
+           (b) one or more controls using IntermediateResponse messages
+               are included in a request with an LDAPv3 extended
+               operation that uses IntermediateResponse messages.
+
+   A request control that defines the return of multiple kinds of
+   IntermediateResponse messages MUST provide and document a mechanism
+   for the client to distinguish the kind of IntermediateResponse
+   message being sent. This SHALL be accomplished by using different
+   responseName values for each type of IntermediateResponse message
+   associated with the request control or by including identifying
+   information in the responseValue of each type of
+   IntermediateResponse message associated with the request control.
+
+Harrison & Zeilenga         Expires September 30, 2001        [Page 4]
+\f
+                     LDAPv3 Intermediate Response       March 30, 2001
+
+
+
+5. Advertising Support for IntermediateResponse Messages
+
+   Because IntermediateResponse messages are associated with extended
+   operations or controls and LDAP provides a means for advertising the
+   extended operations and controls supported by a server (using the
+   supportedExtensions and supportedControls attributes of the root DSE
+   attributes), no separate means for advertising support for
+   IntermediateResponse messages is needed (or provided).
+
+6. Use of IntermediateResponse and ExtendedResponse with Search
+
+   It is noted that ExtendedResponse messages may be sent in response
+   to LDAPv3 search operations with controls ([LDAPv3] Section 4.5.1).
+   This use of ExtendedResponse messages SHOULD be viewed as deprecated
+   in favor of use of the IntermediateResponse messages.
+
+
+7. Security Considerations
+
+   This document describes an enhancement to LDAPv3.  All security
+   considerations of [LDAPv3] apply to this document, however it does
+   not introduce any new security considerations to the LDAPv3.
+
+8. References
+
+    [LDAPv3]
+        Wahl, M., Howes, T., and S. Kille, "Lightweight Directory
+        Access Protocol (v3)", RFC 2251, December 1997.
+
+   [ReqsKeywords]
+        Scott Bradner. "Key Words for use in RFCs to Indicate
+        Requirement Levels". RFC 2119.
+
+
+9. Acknowledgments
+
+   The authors would like to acknowledge the members of the IETF LDAP
+   Extensions (ldapext) working group mail list who responded to the
+   suggestion that a multiple-response paradigm might be useful for
+   LDAP extended requests.  Special thanks go to two individuals: David
+   Wilbur who first introduced the idea on the working group list, and
+   Thomas Salter, who succinctly summarized the group's discussion.
+
+10. Authors' Addresses
+
+   Roger Harrison
+   Novell, Inc.
+   1800 S. Novell Place
+   Provo, UT 84606
+   +1 801 861 2642
+   roger_harrison@novell.com
+
+
+Harrison & Zeilenga         Expires September 30, 2001        [Page 5]
+\f
+                     LDAPv3 Intermediate Response       March 30, 2001
+
+
+   Kurt D. Zeilenga
+   OpenLDAP Foundation
+   Kurt@OpenLDAP.org
+
+Appendix A - Document Revision History
+   Editors' Note: this non-normative appendix should be removed prior
+   to publication as an RFC.  It is provided as an aid to reviewers of
+   this "work in progress."
+
+A.1. draft-rharrison-ldap-extPartResp-00.txt
+
+   Initial revision of draft.
+
+A.2. draft-rharrison-ldap-extPartResp-01.txt
+
+   Changed responseName to be optional to align with [LDAPv3]
+   definition of ExtendedResponse.
+
+A.3. draft-rharrison-ldap-extPartResp-02.txt
+
+   Minor terminology corrections. Clarified use of
+   ExtendedPartialResponse with LDAPv3 extended operations and other
+   LDAPv3 operations with controls.
+
+A.4. draft-rharrison-ldap-intermediateResp-00.txt
+
+   - Changed name of ExtendedPartialResponse to IntermediateResponse.
+
+   - Retitled "Motivation" section to "Background and Intended Usage"
+     and expanded its contents.
+
+   - Added detail surrounding the use of the IntermediateResponse with
+     extended operations and request controls.
+
+   - Generalized the way that Intermediate response fits into the ASN.1
+     definition of LDAPv3.
+
+   - Added information on advertising IntermediateResponse.
+
+   - Added information on the use of IntermediateResponse with the
+     search operation.
+
+Full Copyright Statement
+
+   "Copyright (C) The Internet Society (date). 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
+
+Harrison & Zeilenga         Expires September 30, 2001        [Page 6]
+\f
+                     LDAPv3 Intermediate Response       March 30, 2001
+
+
+   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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Harrison & Zeilenga         Expires September 30, 2001        [Page 7]
+\f