]> git.sur5r.net Git - openldap/blob - doc/rfc/rfc3771.txt
Sync with HEAD
[openldap] / doc / rfc / rfc3771.txt
1
2
3
4
5
6
7 Network Working Group                                        R. Harrison
8 Request for Comments: 3771                                  Novell, Inc.
9 Updates: 2251                                                K. Zeilenga
10 Category: Standards Track                            OpenLDAP Foundation
11                                                               April 2004
12
13
14            The Lightweight Directory Access Protocol (LDAP)
15                      Intermediate Response Message
16
17 Status of this Memo
18
19    This document specifies an Internet standards track protocol for the
20    Internet community, and requests discussion and suggestions for
21    improvements.  Please refer to the current edition of the "Internet
22    Official Protocol Standards" (STD 1) for the standardization state
23    and status of this protocol.  Distribution of this memo is unlimited.
24
25 Copyright Notice
26
27    Copyright (C) The Internet Society (2004).  All Rights Reserved.
28
29 Abstract
30
31    This document defines and describes the IntermediateResponse message,
32    a general mechanism for defining single-request/multiple-response
33    operations in Lightweight Directory Access Protocol (LDAP).  The
34    IntermediateResponse message is defined in such a way that the
35    protocol behavior of existing LDAP operations is maintained.  This
36    message is intended to be used in conjunction with the LDAP
37    ExtendedRequest and ExtendedResponse to define new single-
38    request/multiple-response operations or in conjunction with a control
39    when extending existing LDAP operations in a way that requires them
40    to return intermediate response information.
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58 Harrison & Zeilenga         Standards Track                     [Page 1]
59 \f
60 RFC 3771               LDAP Intermediate Response             April 2004
61
62
63 1.  Introduction
64
65    The Lightweight Directory Access Protocol (LDAP), version 3 [RFC3377]
66    is an extensible protocol.  Extended operations ([RFC2251] Section
67    4.12) are defined to allow for the addition of operations to LDAP,
68    without requiring revisions of the protocol.  Similarly, controls
69    ([RFC2251] Section 4.1.12) are defined to extend or modify the
70    behavior of existing LDAP operations.
71
72    LDAP is a client-request/server-response based protocol.  With the
73    exception of the search operation, the entire response to an
74    operation request is returned in a single protocol data unit (i.e.,
75    LDAP message).  While this single-request/single-response paradigm is
76    sufficient for many operations (including all but one of those
77    currently defined by [RFC3377]), both intuition and practical
78    experience validate the notion that it is insufficient for others.
79
80    For example, the LDAP delete operation could be extended via a
81    subtree control to mean that an entire subtree is to be deleted.  A
82    subtree delete operation needs to return continuation references
83    based upon subordinate knowledge information contained in the server
84    so that the client can complete the operation.  Returning references
85    as they are found, instead of with the final result, allows the
86    client to perform the operation more efficiently because it does not
87    have to wait for the final result to get this continuation reference
88    information.
89
90    Similarly, an engineer might choose to design the subtree delete
91    operation as an extended operation of its own rather than using a
92    subtree control in conjunction with the delete operation.  Once
93    again, the same continuation reference information is needed by the
94    client to complete the operation, and sending the continuation
95    references as they are found would allow the client to perform the
96    operation more efficiently.
97
98    Operations that are completed in stages or that progress through
99    various states as they are completed might want to send intermediate
100    responses to the client, thereby informing it of the status of the
101    operation.  For example, an LDAP implementation might define an
102    extended operation to create a new replica of an administrative area
103    on a server, and the operation is completed in three stages: (1)
104    begin creation of replica, (2) send replica data to server, (3)
105    replica creation complete.  Intermediate messages might be sent from
106    the server to the client at the beginning of each stage with the
107    final response for the extended operation being sent after stage (3)
108    is complete.
109
110
111
112
113
114 Harrison & Zeilenga         Standards Track                     [Page 2]
115 \f
116 RFC 3771               LDAP Intermediate Response             April 2004
117
118
119    As LDAP [RFC3377] is currently defined, there is no general LDAP
120    message type that can be used to return intermediate results.  A
121    single, reusable LDAP message for carrying intermediate response
122    information is desired to avoid repeated modification of the
123    protocol.  Although the ExtendedResponse message is defined in LDAP,
124    it is defined to be the one and only response message to an
125    ExtendedRequest message ([RFC2251] Section 4.12), for unsolicited
126    notifications ([RFC2251] Section 4.4), and to return intermediate
127    responses for the search operation ([RFC3377] Section 4.5.2, also see
128    Section 5 below).  The adaptation of ExtendedResponse as a general
129    intermediate response mechanism would be problematic.  In particular,
130    existing APIs would likely have to be redesigned.  It is believed
131    (based upon operational experience) that the addition of a new
132    message to carry intermediate result information is easier to
133    implement and is less likely to cause interoperability problems with
134    existing deployed implementations.
135
136    This document defines and describes the LDAP IntermediateResponse
137    message.  This message is intended to be used in conjunction with
138    ExtendedRequest and ExtendedResponse to define new single-
139    request/multiple-response operations or in conjunction with a control
140    when extending existing LDAP operations in a way that requires them
141    to return intermediate response information.
142
143    It is intended that the definitions and descriptions of extended
144    operations and controls using the IntermediateResponse message will
145    define the circumstances in which an IntermediateResponse message can
146    be sent by a server and the associated meaning of the
147    IntermediateResponse message sent in a particular circumstance.
148    Similarly, it is intended that clients will explicitly solicit
149    IntermediateResponse messages by issuing operations that specifically
150    call for their return.
151
152    The LDAP Content Sync Operation [ZEILENGA] demonstrates one use of
153    LDAP Intermediate Response messages.
154
155 2.  Conventions used in this document
156
157    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
158    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
159    document are to be interpreted as described in [RFC2119].
160
161    The term "request control" is used to describe a control that is
162    included in an LDAP request message sent from an LDAP client to an
163    LDAP server.
164
165
166
167
168
169
170 Harrison & Zeilenga         Standards Track                     [Page 3]
171 \f
172 RFC 3771               LDAP Intermediate Response             April 2004
173
174
175 3.  The IntermediateResponse Message
176
177    This document extends the protocolOp CHOICE of LDAPMessage ([RFC2251]
178    Section 4.1.1) to include the field:
179
180            intermediateResponse  IntermediateResponse
181
182    where IntermediateResponse is defined as:
183
184            IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
185                    responseName     [0] LDAPOID OPTIONAL,
186                    responseValue    [1] OCTET STRING OPTIONAL }
187
188    IntermediateResponse messages SHALL NOT be returned to the client
189    unless the client issues a request that specifically solicits their
190    return.  This document defines two forms of solicitation: extended
191    operation and request control.
192
193    Although the responseName and responseValue are optional in some
194    circumstances, IntermediateResponse messages usually have a
195    predefined responseName and a responseValue.  The value of the
196    responseName (if present), the syntax of the responseValue (if
197    present) and the semantics associated with a particular
198    IntermediateResponse message MUST be specified in documents
199    describing the extended operation or request control that uses them.
200    Sections 3.1 and 3.2 describe additional requirements for the
201    inclusion of responseName and responseValue in IntermediateResponse
202    messages.
203
204 3.1.  Usage with LDAP ExtendedRequest and ExtendedResponse
205
206    A single-request/multiple-response operation may be defined using a
207    single ExtendedRequest message to solicit zero or more
208    IntermediateResponse messages, of one or more kinds, followed by an
209    ExtendedResponse message.
210
211    An extended operation that defines the return of multiple kinds of
212    IntermediateResponse messages MUST provide and document a mechanism
213    for the client to distinguish the kind of IntermediateResponse
214    message being sent.  This SHALL be accomplished by using different
215    responseName values for each type of IntermediateResponse message
216    associated with the extended operation or by including identifying
217    information in the responseValue of each type of IntermediateResponse
218    message associated with the extended operation.
219
220
221
222
223
224
225
226 Harrison & Zeilenga         Standards Track                     [Page 4]
227 \f
228 RFC 3771               LDAP Intermediate Response             April 2004
229
230
231 3.2.  Usage with LDAP Request Controls
232
233    Any LDAP operation may be extended by the addition of one or more
234    controls ([RFC2251] Section 4.1.12).  A control's semantics may
235    include the return of zero or more IntermediateResponse messages
236    prior to returning the final result code for the operation.  One or
237    more kinds of IntermediateResponse messages may be sent in response
238    to a request control.
239
240    All IntermediateResponse messages associated with request controls
241    SHALL include a responseName.  This requirement ensures that the
242    client can correctly identify the source of IntermediateResponse
243    messages when:
244
245       a) two or more controls using IntermediateResponse messages are
246          included in a request for any LDAP operation or
247
248       b) one or more controls using IntermediateResponse messages are
249          included in a request with an LDAP extended operation that uses
250          IntermediateResponse messages.
251
252    A request control that defines the return of multiple kinds of
253    IntermediateResponse messages MUST provide and document a mechanism
254    for the client to distinguish the kind of IntermediateResponse
255    message being sent.  This SHALL be accomplished by using different
256    responseName values for each type of IntermediateResponse message
257    associated with the request control or by including identifying
258    information in the responseValue of each type of IntermediateResponse
259    message associated with the request control.
260
261 4.  Advertising Support for IntermediateResponse Messages
262
263    Because IntermediateResponse messages are associated with extended
264    operations or controls and LDAP provides a means for advertising the
265    extended operations and controls supported by a server (using the
266    supportedExtension ([RFC2252] Section 5.2.3) and supportedControl
267    ([RFC2252] Section 5.2.4) attributes of the root DSE), there is no
268    need for a separate means of advertising support for intermediate
269    response messages.
270
271 5.  Use of IntermediateResponse and ExtendedResponse with Search
272
273    It is noted that ExtendedResponse messages may be sent in response to
274    LDAP search operations with controls ([RFC2251] Section 4.5.2).  This
275    use of ExtendedResponse messages SHOULD be viewed as deprecated, in
276    favor of use of the IntermediateResponse messages.
277
278
279
280
281
282 Harrison & Zeilenga         Standards Track                     [Page 5]
283 \f
284 RFC 3771               LDAP Intermediate Response             April 2004
285
286
287 6.  Security Considerations
288
289    This document describes an enhancement to LDAP.  All security
290    considerations of [RFC3377] apply to this document; however, it does
291    not introduce any new security considerations to LDAP.
292
293    Security considerations specific to each extension using this
294    protocol mechanism shall be discussed in the technical specification
295    detailing the extension.
296
297 7.  IANA Considerations
298
299    Registration of the following value has been completed [RFC3383].
300
301 7.1.  LDAP Message Type
302
303    The IANA has registered an LDAP Message Type (25) to identify the
304    LDAP IntermediateResponse message as defined in section 3 of this
305    document.
306
307    The following registration template is suggested:
308
309    Subject: Request for LDAP Message Type Registration
310    Person & email address to contact for further information:
311       Roger Harrison <roger_harrison@novell.com>
312       Specification: RFC3771
313       Author/Change Controller: IESG
314       Comments: Identifies the LDAP IntermediateResponse Message
315
316 8.  Acknowledgments
317
318    The authors would like to acknowledge the members of the IETF LDAP
319    Extensions (ldapext) working group mail list who responded to the
320    suggestion that a multiple-response paradigm might be useful for LDAP
321    extended requests.  Special thanks to two individuals: David Wilbur
322    who first introduced the idea on the working group list, and Thomas
323    Salter, who succinctly summarized the group's discussion.
324
325 9.  References
326
327 9.1.  Normative References
328
329    [RFC2119]  Bradner, S., "Key Words for use in RFCs to Indicate
330               Requirement Levels", BCP 14, RFC 2119, March 1997.
331
332    [RFC2251]  Wahl, M., Howes, T. and S. Kille, "Lightweight Directory
333               Access Protocol (v3)", RFC 2251, December 1997.
334
335
336
337
338 Harrison & Zeilenga         Standards Track                     [Page 6]
339 \f
340 RFC 3771               LDAP Intermediate Response             April 2004
341
342
343    [RFC2252]  Wahl, M., Coulbeck, A., Howes, T. and S.  Kille,
344               "Lightweight Directory Access Protocol (v3): Attribute
345               Syntax Definitions", RFC 2252, December 1997.
346
347    [RFC3377]  Hodges, J. and R. Morgan, "Lightweight Directory Access
348               Protocol (v3): Technical Specification", RFC 3377,
349               September 2002.
350
351    [RFC3383]  Zeilenga, K., "Internet Assigned Numbers Authority (IANA)
352               Considerations for the Lightweight Directory Access
353               Protocol (LDAP)", BCP 64, RFC 3383, September 2002.
354
355 9.2.  Informative References
356
357    [ZEILENGA] Zeilenga, K., "LDAP Content Synchronization Operation",
358               Work in Progress, February 2004.
359
360 10.  Authors' Addresses
361
362    Roger Harrison
363    Novell, Inc.
364    1800 S. Novell Place
365    Provo, UT 84606
366
367    Phone: +1 801 861 2642
368    EMail: roger_harrison@novell.com
369
370
371    Kurt D. Zeilenga
372    OpenLDAP Foundation
373
374    EMail: Kurt@OpenLDAP.org
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394 Harrison & Zeilenga         Standards Track                     [Page 7]
395 \f
396 RFC 3771               LDAP Intermediate Response             April 2004
397
398
399 11.  Full Copyright Statement
400
401    Copyright (C) The Internet Society (2004).  This document is subject
402    to the rights, licenses and restrictions contained in BCP 78, and
403    except as set forth therein, the authors retain all their rights.
404
405    This document and the information contained herein are provided on an
406    "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
407    OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
408    ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
409    INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
410    INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
411    WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
412
413 Intellectual Property
414
415    The IETF takes no position regarding the validity or scope of any
416    Intellectual Property Rights or other rights that might be claimed to
417    pertain to the implementation or use of the technology described in
418    this document or the extent to which any license under such rights
419    might or might not be available; nor does it represent that it has
420    made any independent effort to identify any such rights.  Information
421    on the procedures with respect to rights in RFC documents can be
422    found in BCP 78 and BCP 79.
423
424    Copies of IPR disclosures made to the IETF Secretariat and any
425    assurances of licenses to be made available, or the result of an
426    attempt made to obtain a general license or permission for the use of
427    such proprietary rights by implementers or users of this
428    specification can be obtained from the IETF on-line IPR repository at
429    http://www.ietf.org/ipr.
430
431    The IETF invites any interested party to bring to its attention any
432    copyrights, patents or patent applications, or other proprietary
433    rights that may cover technology that may be required to implement
434    this standard.  Please address the information to the IETF at ietf-
435    ipr@ietf.org.
436
437 Acknowledgement
438
439    Funding for the RFC Editor function is currently provided by the
440    Internet Society.
441
442
443
444
445
446
447
448
449
450 Harrison & Zeilenga         Standards Track                     [Page 8]
451 \f