GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools


rfc:rfc3771

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

/data/webs/external/dokuwiki/data/pages/rfc/rfc3771.txt · Last modified: 2004/04/26 20:42 (external edit)