3 Individual Submission to ldapext Working Group Roger G. Harrison
4 Internet Draft Novell, Inc.
5 Intended Category: Standards Track
13 LDAP Intermediate Response
14 <draft-rharrison-ldap-intermediate-resp-00.txt>
19 This document is an Internet-Draft and is in full conformance with
20 all provisions of Section 10 of RFC2026.
22 This document is intended to be, after appropriate review and
23 revision, submitted to the RFC Editor as a Standard Track document.
25 Distribution of this memo is unlimited. Technical discussion of
26 this document will take place on the IETF LDAP Extensions Working
27 Group (ldapext) mailing list <ietf-ldapext@netscape.com>. Please
28 send editorial comments directly to the document editor
29 <roger_harrison@novell.com>.
31 Internet-Drafts are working documents of the Internet Engineering
32 Task Force (IETF), its areas, and its working groups. Note that
33 other groups may also distribute working documents as Internet-
34 Drafts. Internet-Drafts are draft documents valid for a maximum of
35 six months and may be updated, replaced, or obsoleted by other
36 documents at any time. It is inappropriate to use Internet-Drafts as
37 reference material or to cite them other than as "work in progress."
39 The list of current Internet-Drafts can be accessed at
40 http://www.ietf.org/ietf/1id-abstracts.txt
41 The list of Internet-Draft Shadow Directories can be accessed at
42 http://www.ietf.org/shadow.html.
46 This document extends LDAPv3 to provide a general mechanism for
47 defining single-request/multiple-response operations by defining and
48 describing the IntermediateResponse message.
51 2. Background and Intended Usage
53 The Lightweight Directory Access Protocol, version 3 [LDAPv3] is an
54 extensible protocol. Extended operations ([LDAPv3] Section 4.12) are
55 defined to allow operations to be added to LDAP without requiring a
56 new revision of the protocol. Similarly, controls ([LDAPv3] section
58 Harrison & Zeilenga Expires September 30, 2001 [Page 1]
60 LDAPv3 Intermediate Response March 30, 2001
63 4.1.12) are defined to extend or modify the behavior of existing
66 LDAPv3 is a client-request/server-response based protocol. With the
67 exception of the search operation, the entire response to an
68 operation request is returned in a single protocol data unit (LDAP
69 message). While this single-request/single-response paradigm is
70 sufficient for many operations (including almost all but one of
71 those currently defined by [LDAPv3]), both intuition and practical
72 experience validate the notion that it is insufficient for some
75 For example, the LDAPv3 delete operation could be extended via a
76 subtree control to mean that an entire subtree is to be deleted. A
77 subtree delete operation needs to return continuation references
78 based upon subordinate knowledge information contained in the server
79 so that the client can complete the operation. Returning references
80 as they are found instead of with the final result allows the client
81 to progress the operation more efficiently because it does not have
82 to wait for the final result to get this continuation reference
85 Similarly, an engineer might choose to design the subtree delete
86 operation as an extended operation of its own rather than using a
87 subtree control in conjunction with the delete operation. Once
88 again, the same continuation reference information is needed by the
89 client to complete the operation, and sending the continuation
90 references as they are found would allow the client progress the
91 operation more efficiently.
93 Operations that complete in stages or that progress through various
94 states as they complete might want to send intermediate responses to
95 the client apprising it of the status of the operation. For example,
96 an LDAP implementation might define an extended operation to create
97 a new replica of an administrative area on a server, and the
98 operation completes in three stages: (1) begin creation of replica,
99 (2) send replica data to server, (3) replica creation complete.
100 Intermediate messages might be sent from the server to the client at
101 the beginning of stages (1) and (2) with the final response for the
102 extended operation being sent for stage (3).
104 As LDAPv3 is currently defined, there is no general LDAP message
105 type that can be used to return intermediate results. A single,
106 reusable LDAP message for carrying intermediate response information
107 is desired to avoid repeated modification of the protocol. Although
108 the ExtendedResponse message is defined in LDAPv3, it is defined to
109 be the one and only response message to an ExtendedRequest message
110 ([LDAPv3] Section 4.12, also see Section 6 below), for unsolicited
111 responses (LDAPv3 Section 4.4), and to return intermediate responses
112 for the search operation ([LDAPv3] Section 4.5.2). The adaptation of
113 ExpendedResponse as a general intermediate response mechanism would
114 be problematic. In particular, existing APIs would likely have to
115 be redesigned. It is believed (based upon operational experience)
117 Harrison & Zeilenga Expires September 30, 2001 [Page 2]
119 LDAPv3 Intermediate Response March 30, 2001
122 the addition of a new message to carry intermediate result
123 information is easier to implement.
125 This document defines the LDAPv3 IntermediateResponse message. This
126 message is intended to be used (1) in conjunction with
127 ExtendedRequest and ExtendedResponse to define new single-
128 request/multiple-response operations and (2) in conjunction with a
129 control when extending existing operations in a way that requires
130 them to return intermediate response information.
132 It is intended that the definitions and descriptions of extended
133 operations and controls that make use of the IntermediateResponse
134 message will define the circumstances when a IntermediateResponse
135 message can be sent by a server and the associated meaning of a
136 IntermediateResponse message sent in a particular circumstance.
137 Similarly, it is intended that clients will explicitly solicit
138 IntermediateResponse messages by issuing operations that
139 specifically call for their return.
142 3. Conventions used in this document
144 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
145 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
146 this document are to be interpreted as described in [ReqsKeywords].
148 The term "request control" is used to describe a control that is
149 included in an LDAPv3 request message sent from an LDAPv3 client to
153 4. The IntermediateResponse PDU
155 This document extends the protocolOp CHOICE of LDAPMessage ([LDAPv3]
156 Section 4.1.1) to include the field:
158 intermediateResponse IntermediateResponse
160 where IntermediateResponse is defined as:
162 IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
163 responseName [0] LDAPOID OPTIONAL,
164 responseValue [1] OCTET STRING OPTIONAL }
166 IntermediateResponse messages SHALL NOT be returned to the client
167 unless the client issues a request that specifically solicits their
168 return. This document defines two forms of solicitation: extended
169 operation and request control.
171 Although the responseName and responseValue are optional in some
172 circumstances, generally speaking IntermediateResponse messages have
173 a predefined responseName and a responseValue. The value of the
174 responseName (if present), the syntax of the responseValue (if
176 Harrison & Zeilenga Expires September 30, 2001 [Page 3]
178 LDAPv3 Intermediate Response March 30, 2001
181 present) and the semantics associated with a particular
182 IntermediateResponse message MUST be specified in documents
183 describing the extended operation or request control that uses them.
184 Sections 4.1 and 4.2 describe additional requirements on the
185 inclusion of responseName and responseValue in IntermediateResponse
189 4.1. Usage with LDAPv3 ExtendedRequest and ExtendedResponse
191 A single-request/multiple-response operation may be defined using a
192 single ExtendedRequest message to solicit zero or more
193 IntermediateResponse messages of one or more kinds followed by an
194 ExtendedResponse message.
196 An extended operation that defines the return of multiple kinds of
197 IntermediateResponse messages MUST provide and document a mechanism
198 for the client to distinguish the kind of IntermediateResponse
199 message being sent. This SHALL be accomplished by using different
200 responseName values for each type of IntermediateResponse message
201 associated with the extended operation or by including identifying
202 information in the responseValue of each type of
203 IntermediateResponse message associated with the extended operation.
205 4.2. Usage with LDAPv3 Request Controls
207 Any LDAPv3 operation may be extended by the addition of one or more
208 controls. A control's semantics may include the return of zero or
209 more IntermediateResponse messages prior to returning the final
210 result code for the operation. One or more kinds of
211 IntermediateResponse messages may be sent in response to a request
214 All IntermediateResponse messages associated with request controls
215 SHALL include a responseName. This requirement ensures that the
216 client can correctly identify the source of IntermediateResponse
219 (a) two or more controls using IntermediateResponse messages
220 are included in a request for any LDAPv3 operation or
222 (b) one or more controls using IntermediateResponse messages
223 are included in a request with an LDAPv3 extended
224 operation that uses IntermediateResponse messages.
226 A request control that defines the return of multiple kinds of
227 IntermediateResponse messages MUST provide and document a mechanism
228 for the client to distinguish the kind of IntermediateResponse
229 message being sent. This SHALL be accomplished by using different
230 responseName values for each type of IntermediateResponse message
231 associated with the request control or by including identifying
232 information in the responseValue of each type of
233 IntermediateResponse message associated with the request control.
235 Harrison & Zeilenga Expires September 30, 2001 [Page 4]
237 LDAPv3 Intermediate Response March 30, 2001
241 5. Advertising Support for IntermediateResponse Messages
243 Because IntermediateResponse messages are associated with extended
244 operations or controls and LDAP provides a means for advertising the
245 extended operations and controls supported by a server (using the
246 supportedExtensions and supportedControls attributes of the root DSE
247 attributes), no separate means for advertising support for
248 IntermediateResponse messages is needed (or provided).
250 6. Use of IntermediateResponse and ExtendedResponse with Search
252 It is noted that ExtendedResponse messages may be sent in response
253 to LDAPv3 search operations with controls ([LDAPv3] Section 4.5.1).
254 This use of ExtendedResponse messages SHOULD be viewed as deprecated
255 in favor of use of the IntermediateResponse messages.
258 7. Security Considerations
260 This document describes an enhancement to LDAPv3. All security
261 considerations of [LDAPv3] apply to this document, however it does
262 not introduce any new security considerations to the LDAPv3.
267 Wahl, M., Howes, T., and S. Kille, "Lightweight Directory
268 Access Protocol (v3)", RFC 2251, December 1997.
271 Scott Bradner. "Key Words for use in RFCs to Indicate
272 Requirement Levels". RFC 2119.
277 The authors would like to acknowledge the members of the IETF LDAP
278 Extensions (ldapext) working group mail list who responded to the
279 suggestion that a multiple-response paradigm might be useful for
280 LDAP extended requests. Special thanks go to two individuals: David
281 Wilbur who first introduced the idea on the working group list, and
282 Thomas Salter, who succinctly summarized the group's discussion.
284 10. Authors' Addresses
291 roger_harrison@novell.com
294 Harrison & Zeilenga Expires September 30, 2001 [Page 5]
296 LDAPv3 Intermediate Response March 30, 2001
303 Appendix A - Document Revision History
304 Editors' Note: this non-normative appendix should be removed prior
305 to publication as an RFC. It is provided as an aid to reviewers of
306 this "work in progress."
308 A.1. draft-rharrison-ldap-extPartResp-00.txt
310 Initial revision of draft.
312 A.2. draft-rharrison-ldap-extPartResp-01.txt
314 Changed responseName to be optional to align with [LDAPv3]
315 definition of ExtendedResponse.
317 A.3. draft-rharrison-ldap-extPartResp-02.txt
319 Minor terminology corrections. Clarified use of
320 ExtendedPartialResponse with LDAPv3 extended operations and other
321 LDAPv3 operations with controls.
323 A.4. draft-rharrison-ldap-intermediateResp-00.txt
325 - Changed name of ExtendedPartialResponse to IntermediateResponse.
327 - Retitled "Motivation" section to "Background and Intended Usage"
328 and expanded its contents.
330 - Added detail surrounding the use of the IntermediateResponse with
331 extended operations and request controls.
333 - Generalized the way that Intermediate response fits into the ASN.1
334 definition of LDAPv3.
336 - Added information on advertising IntermediateResponse.
338 - Added information on the use of IntermediateResponse with the
341 Full Copyright Statement
343 "Copyright (C) The Internet Society (date). All Rights Reserved.
344 This document and translations of it may be copied and furnished to
345 others, and derivative works that comment on or otherwise explain it
346 or assist in its implementation may be prepared, copied, published
347 and distributed, in whole or in part, without restriction of any
348 kind, provided that the above copyright notice and this paragraph
349 are included on all such copies and derivative works. However, this
350 document itself may not be modified in any way, such as by removing
351 the copyright notice or references to the Internet Society or other
353 Harrison & Zeilenga Expires September 30, 2001 [Page 6]
355 LDAPv3 Intermediate Response March 30, 2001
358 Internet organizations, except as needed for the purpose of
359 developing Internet standards in which case the procedures for
360 copyrights defined in the Internet Standards process must be
361 followed, or as required to translate it into languages other than
364 The limited permissions granted above are perpetual and will not be
365 revoked by the Internet Society or its successors or assigns.
367 This document and the information contained herein is provided on an
368 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
369 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
370 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
371 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
372 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
412 Harrison & Zeilenga Expires September 30, 2001 [Page 7]