path: root/doc/rfc/rfc3771.txt

Network Working Group                                        R. Harrison
Request for Comments: 3771                                  Novell, Inc.
Updates: 2251                                                K. Zeilenga
Category: Standards Track                            OpenLDAP Foundation
                                                              April 2004


           The Lightweight Directory Access Protocol (LDAP)
                     Intermediate Response Message

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2004).  All Rights Reserved.

Abstract

   This document defines and describes the IntermediateResponse message,
   a general mechanism for defining single-request/multiple-response
   operations in Lightweight Directory Access Protocol (LDAP).  The
   IntermediateResponse message is defined in such a way that the
   protocol behavior of existing LDAP operations is maintained.  This
   message is intended to be used in conjunction with the LDAP
   ExtendedRequest and ExtendedResponse to define new single-
   request/multiple-response operations or in conjunction with a control
   when extending existing LDAP operations in a way that requires them
   to return intermediate response information.

















Harrison & Zeilenga         Standards Track                     [Page 1]
^L
RFC 3771               LDAP Intermediate Response             April 2004


1.  Introduction

   The Lightweight Directory Access Protocol (LDAP), version 3 [RFC3377]
   is an extensible protocol.  Extended operations ([RFC2251] Section
   4.12) are defined to allow for the addition of operations to LDAP,
   without requiring revisions of the protocol.  Similarly, controls
   ([RFC2251] Section 4.1.12) are defined to extend or modify the
   behavior of existing LDAP operations.

   LDAP 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 (i.e.,
   LDAP message).  While this single-request/single-response paradigm is
   sufficient for many operations (including all but one of those
   currently defined by [RFC3377]), both intuition and practical
   experience validate the notion that it is insufficient for others.

   For example, the LDAP 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 perform 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 to perform the
   operation more efficiently.

   Operations that are completed in stages or that progress through
   various states as they are completed might want to send intermediate
   responses to the client, thereby informing 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 is completed 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 each stage with the
   final response for the extended operation being sent after stage (3)
   is complete.





Harrison & Zeilenga         Standards Track                     [Page 2]
^L
RFC 3771               LDAP Intermediate Response             April 2004


   As LDAP [RFC3377] 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 LDAP,
   it is defined to be the one and only response message to an
   ExtendedRequest message ([RFC2251] Section 4.12), for unsolicited
   notifications ([RFC2251] Section 4.4), and to return intermediate
   responses for the search operation ([RFC3377] Section 4.5.2, also see
   Section 5 below).  The adaptation of ExtendedResponse 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) that the addition of a new
   message to carry intermediate result information is easier to
   implement and is less likely to cause interoperability problems with
   existing deployed implementations.

   This document defines and describes the LDAP IntermediateResponse
   message.  This message is intended to be used in conjunction with
   ExtendedRequest and ExtendedResponse to define new single-
   request/multiple-response operations or in conjunction with a control
   when extending existing LDAP 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 using the IntermediateResponse message will
   define the circumstances in which an IntermediateResponse message can
   be sent by a server and the associated meaning of the
   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.

   The LDAP Content Sync Operation [ZEILENGA] demonstrates one use of
   LDAP Intermediate Response messages.

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].

   The term "request control" is used to describe a control that is
   included in an LDAP request message sent from an LDAP client to an
   LDAP server.






Harrison & Zeilenga         Standards Track                     [Page 3]
^L
RFC 3771               LDAP Intermediate Response             April 2004


3.  The IntermediateResponse Message

   This document extends the protocolOp CHOICE of LDAPMessage ([RFC2251]
   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, IntermediateResponse messages usually have a
   predefined responseName and a responseValue.  The value of the
   responseName (if present), the syntax of the responseValue (if
   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 3.1 and 3.2 describe additional requirements for the
   inclusion of responseName and responseValue in IntermediateResponse
   messages.

3.1.  Usage with LDAP 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.







Harrison & Zeilenga         Standards Track                     [Page 4]
^L
RFC 3771               LDAP Intermediate Response             April 2004


3.2.  Usage with LDAP Request Controls

   Any LDAP operation may be extended by the addition of one or more
   controls ([RFC2251] Section 4.1.12).  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 LDAP operation or

      b) one or more controls using IntermediateResponse messages are
         included in a request with an LDAP 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.

4.  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
   supportedExtension ([RFC2252] Section 5.2.3) and supportedControl
   ([RFC2252] Section 5.2.4) attributes of the root DSE), there is no
   need for a separate means of advertising support for intermediate
   response messages.

5.  Use of IntermediateResponse and ExtendedResponse with Search

   It is noted that ExtendedResponse messages may be sent in response to
   LDAP search operations with controls ([RFC2251] Section 4.5.2).  This
   use of ExtendedResponse messages SHOULD be viewed as deprecated, in
   favor of use of the IntermediateResponse messages.





Harrison & Zeilenga         Standards Track                     [Page 5]
^L
RFC 3771               LDAP Intermediate Response             April 2004


6.  Security Considerations

   This document describes an enhancement to LDAP.  All security
   considerations of [RFC3377] apply to this document; however, it does
   not introduce any new security considerations to LDAP.

   Security considerations specific to each extension using this
   protocol mechanism shall be discussed in the technical specification
   detailing the extension.

7.  IANA Considerations

   Registration of the following value has been completed [RFC3383].

7.1.  LDAP Message Type

   The IANA has registered an LDAP Message Type (25) to identify the
   LDAP IntermediateResponse message as defined in section 3 of this
   document.

   The following registration template is suggested:

   Subject: Request for LDAP Message Type Registration
   Person & email address to contact for further information:
      Roger Harrison <roger_harrison@novell.com>
      Specification: RFC3771
      Author/Change Controller: IESG
      Comments: Identifies the LDAP IntermediateResponse Message

8.  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 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.

9.  References

9.1.  Normative References

   [RFC2119]  Bradner, S., "Key Words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2251]  Wahl, M., Howes, T. and S. Kille, "Lightweight Directory
              Access Protocol (v3)", RFC 2251, December 1997.




Harrison & Zeilenga         Standards Track                     [Page 6]
^L
RFC 3771               LDAP Intermediate Response             April 2004


   [RFC2252]  Wahl, M., Coulbeck, A., Howes, T. and S.  Kille,
              "Lightweight Directory Access Protocol (v3): Attribute
              Syntax Definitions", RFC 2252, December 1997.

   [RFC3377]  Hodges, J. and R. Morgan, "Lightweight Directory Access
              Protocol (v3): Technical Specification", RFC 3377,
              September 2002.

   [RFC3383]  Zeilenga, K., "Internet Assigned Numbers Authority (IANA)
              Considerations for the Lightweight Directory Access
              Protocol (LDAP)", BCP 64, RFC 3383, September 2002.

9.2.  Informative References

   [ZEILENGA] Zeilenga, K., "LDAP Content Synchronization Operation",
              Work in Progress, February 2004.

10.  Authors' Addresses

   Roger Harrison
   Novell, Inc.
   1800 S. Novell Place
   Provo, UT 84606

   Phone: +1 801 861 2642
   EMail: roger_harrison@novell.com


   Kurt D. Zeilenga
   OpenLDAP Foundation

   EMail: Kurt@OpenLDAP.org



















Harrison & Zeilenga         Standards Track                     [Page 7]
^L
RFC 3771               LDAP Intermediate Response             April 2004


11.  Full Copyright Statement

   Copyright (C) The Internet Society (2004).  This document is subject
   to the rights, licenses and restrictions contained in BCP 78, and
   except as set forth therein, the authors retain all their rights.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
   ENGINEERING TASK FORCE DISCLAIM 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.

Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at
   http://www.ietf.org/ipr.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at ietf-
   ipr@ietf.org.

Acknowledgement

   Funding for the RFC Editor function is currently provided by the
   Internet Society.









Harrison & Zeilenga         Standards Track                     [Page 8]
^L