git.sur5r.net Git - openldap/blob - doc/drafts/draft-rharrison-ldap-intermediate-resp-xx.txt

   1
   2
   3 Individual Submission to ldapext Working Group        Roger G. Harrison
   4 Internet Draft                                             Novell, Inc.
   5 Intended Category: Standards Track
   6                                                        Kurt D. Zeilenga
   7                                                     OpenLDAP Foundation
   8
   9                                                          March 30, 2001
  10
  11
  12
  13                        LDAP Intermediate Response
  14              <draft-rharrison-ldap-intermediate-resp-00.txt>
  15
  16
  17 Status of this Memo
  18
  19    This document is an Internet-Draft and is in full conformance with
  20    all provisions of Section 10 of RFC2026.
  21
  22    This document is intended to be, after appropriate review and
  23    revision, submitted to the RFC Editor as a Standard Track document.
  24
  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>.
  30
  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."
  38
  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.
  43
  44 1. Abstract
  45
  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.
  49
  50
  51 2. Background and Intended Usage
  52
  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
  57
  58 Harrison & Zeilenga        Expires September 30, 2001         [Page 1]
  59 \f
  60                      LDAPv3 Intermediate Response       March 30, 2001
  61
  62
  63    4.1.12) are defined to extend or modify the behavior of existing
  64    LDAP operations.
  65
  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
  73    operations.
  74
  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
  83    information.
  84
  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.
  92
  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).
 103
 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)
 116
 117 Harrison & Zeilenga         Expires September 30, 2001        [Page 2]
 118 \f
 119                      LDAPv3 Intermediate Response       March 30, 2001
 120
 121
 122    the addition of a new message to carry intermediate result
 123    information is easier to implement.
 124
 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.
 131
 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.
 140
 141
 142 3. Conventions used in this document
 143
 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].
 147
 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
 150    an LDAPv3 server.
 151
 152
 153 4. The IntermediateResponse PDU
 154
 155    This document extends the protocolOp CHOICE of LDAPMessage ([LDAPv3]
 156    Section 4.1.1) to include the field:
 157
 158            intermediateResponse  IntermediateResponse
 159
 160    where IntermediateResponse is defined as:
 161
 162            IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
 163                    responseName     [0] LDAPOID OPTIONAL,
 164                    responseValue    [1] OCTET STRING OPTIONAL }
 165
 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.
 170
 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
 175
 176 Harrison & Zeilenga         Expires September 30, 2001        [Page 3]
 177 \f
 178                      LDAPv3 Intermediate Response       March 30, 2001
 179
 180
 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
 186    messages.
 187
 188
 189 4.1. Usage with LDAPv3 ExtendedRequest and ExtendedResponse
 190
 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.
 195
 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.
 204
 205 4.2. Usage with LDAPv3 Request Controls
 206
 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
 212    control.
 213
 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
 217    messages when
 218
 219            (a) two or more controls using IntermediateResponse messages
 220                are included in a request for any LDAPv3 operation or
 221
 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.
 225
 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.
 234
 235 Harrison & Zeilenga         Expires September 30, 2001        [Page 4]
 236 \f
 237                      LDAPv3 Intermediate Response       March 30, 2001
 238
 239
 240
 241 5. Advertising Support for IntermediateResponse Messages
 242
 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).
 249
 250 6. Use of IntermediateResponse and ExtendedResponse with Search
 251
 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.
 256
 257
 258 7. Security Considerations
 259
 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.
 263
 264 8. References
 265
 266     [LDAPv3]
 267         Wahl, M., Howes, T., and S. Kille, "Lightweight Directory
 268         Access Protocol (v3)", RFC 2251, December 1997.
 269
 270    [ReqsKeywords]
 271         Scott Bradner. "Key Words for use in RFCs to Indicate
 272         Requirement Levels". RFC 2119.
 273
 274
 275 9. Acknowledgments
 276
 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.
 283
 284 10. Authors' Addresses
 285
 286    Roger Harrison
 287    Novell, Inc.
 288    1800 S. Novell Place
 289    Provo, UT 84606
 290    +1 801 861 2642
 291    roger_harrison@novell.com
 292
 293
 294 Harrison & Zeilenga         Expires September 30, 2001        [Page 5]
 295 \f
 296                      LDAPv3 Intermediate Response       March 30, 2001
 297
 298
 299    Kurt D. Zeilenga
 300    OpenLDAP Foundation
 301    Kurt@OpenLDAP.org
 302
 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."
 307
 308 A.1. draft-rharrison-ldap-extPartResp-00.txt
 309
 310    Initial revision of draft.
 311
 312 A.2. draft-rharrison-ldap-extPartResp-01.txt
 313
 314    Changed responseName to be optional to align with [LDAPv3]
 315    definition of ExtendedResponse.
 316
 317 A.3. draft-rharrison-ldap-extPartResp-02.txt
 318
 319    Minor terminology corrections. Clarified use of
 320    ExtendedPartialResponse with LDAPv3 extended operations and other
 321    LDAPv3 operations with controls.
 322
 323 A.4. draft-rharrison-ldap-intermediateResp-00.txt
 324
 325    - Changed name of ExtendedPartialResponse to IntermediateResponse.
 326
 327    - Retitled "Motivation" section to "Background and Intended Usage"
 328      and expanded its contents.
 329
 330    - Added detail surrounding the use of the IntermediateResponse with
 331      extended operations and request controls.
 332
 333    - Generalized the way that Intermediate response fits into the ASN.1
 334      definition of LDAPv3.
 335
 336    - Added information on advertising IntermediateResponse.
 337
 338    - Added information on the use of IntermediateResponse with the
 339      search operation.
 340
 341 Full Copyright Statement
 342
 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
 352
 353 Harrison & Zeilenga         Expires September 30, 2001        [Page 6]
 354 \f
 355                      LDAPv3 Intermediate Response       March 30, 2001
 356
 357
 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
 362    English.
 363
 364    The limited permissions granted above are perpetual and will not be
 365    revoked by the Internet Society or its successors or assigns.
 366
 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.
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412 Harrison & Zeilenga         Expires September 30, 2001        [Page 7]
 413 \f