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

   1
   2
   3 INTERNET-DRAFT                                              R. Harrison
   4 draft-rharrison-ldap-intermediate-resp-01.txt              Novell, Inc.
   5 Updates: 2251                                               K. Zeilenga
   6 Intended Category: Standards Track                  OpenLDAP Foundation
   7                                                          March 28, 2003
   8
   9
  10             The Lightweight Directory Access Protocol (LDAP)
  11                      Intermediate Response Message
  12
  13
  14 Status of this Memo
  15
  16    This document is an Internet-Draft and is in full conformance with
  17    all provisions of Section 10 of RFC2026.
  18
  19    This document is intended to be, after appropriate review and
  20    revision, submitted to the RFC Editor as a Standard Track document.
  21
  22    Distribution of this memo is unlimited.  Technical discussion of
  23    this document will take place on the IETF LDAP Extensions Working
  24    Group (ldapext) mailing list <ietf-ldapext@netscape.com>.  Please
  25    send editorial comments directly to the document editor
  26    <roger_harrison@novell.com>
  27
  28    Internet-Drafts are working documents of the Internet Engineering
  29    Task Force (IETF), its areas, and its working groups.  Note that
  30    other groups may also distribute working documents as Internet-
  31    Drafts.  Internet-Drafts are draft documents valid for a maximum of
  32    six months and may be updated, replaced, or obsoleted by other
  33    documents at any time.  It is inappropriate to use Internet-Drafts
  34    as reference material or to cite them other than as "work in
  35    progress."
  36
  37    The list of current Internet-Drafts can be accessed at
  38    http://www.ietf.org/ietf/1id-abstracts.txt
  39    The list of Internet-Draft Shadow Directories can be accessed at
  40    http://www.ietf.org/shadow.html.
  41
  42 Copyright Notice
  43
  44    Copyright (C) The Internet Society (2003).  All Rights Reserved.
  45
  46 Abstract
  47
  48    The Lightweight Directory Access Protocol (LDAP) version 3 is a
  49    client-request/server-response based protocol.  With the exception
  50    of the search operation, the entire response to an operation request
  51    is returned in a single LDAP message.  While this single-
  52    request/single-response paradigm is sufficient for many operations
  53    (including all but one of those currently defined by LDAP), both
  54    intuition and practical experience validate the notion that it is
  55    insufficient for some operations.  When multiple messages are sent
  56
  57
  58 Harrison & Zeilenga        Expires September 28, 2003         [Page 1]
  59 \f
  60 Internet-Draft        LDAP Intermediate Response         28 March 2003
  61
  62
  63    in response to a single request, all but the last of these response
  64    messages are referred to as "intermediate responses".
  65
  66    This document defines and describes the IntermediateResponse
  67    message, a general mechanism for defining single-request/multiple-
  68    response operations in LDAP.  The IntermediateResponse message is
  69    defined in a way that maintains the protocol behavior of existing
  70    LDAP operations.  This message is intended to be used in conjunction
  71    with the LDAP ExtendedRequest and ExtendedResponse to define new
  72    single-request/multiple-response operations or in conjunction with a
  73    control when extending existing LDAP operations in a way that
  74    requires them to return intermediate response information.
  75
  76 1. Introduction
  77
  78    The Lightweight Directory Access Protocol (LDAP), version 3
  79    [RFC3377] is an extensible protocol.  Extended operations ([RFC2251]
  80    Section 4.12) are defined to allow operations to be added to LDAP
  81    without requiring a new revision of the protocol.  Similarly,
  82    controls ([RFC2251] section 4.1.12) are defined to extend or modify
  83    the behavior of existing LDAP operations.
  84
  85    LDAP is a client-request/server-response based protocol.  With the
  86    exception of the search operation, the entire response to an
  87    operation request is returned in a single protocol data unit (i.e.
  88    LDAP message).  While this single-request/single-response paradigm
  89    is sufficient for many operations (including all but one of those
  90    currently defined by [RFC3377]), both intuition and practical
  91    experience validate the notion that it is insufficient for some
  92    operations.
  93
  94    For example, the LDAP delete operation could be extended via a
  95    subtree control to mean that an entire subtree is to be deleted.  A
  96    subtree delete operation needs to return continuation references
  97    based upon subordinate knowledge information contained in the server
  98    so that the client can complete the operation.  Returning references
  99    as they are found instead of with the final result allows the client
 100    to progress the operation more efficiently because it does not have
 101    to wait for the final result to get this continuation reference
 102    information.
 103
 104    Similarly, an engineer might choose to design the subtree delete
 105    operation as an extended operation of its own rather than using a
 106    subtree control in conjunction with the delete operation.  Once
 107    again, the same continuation reference information is needed by the
 108    client to complete the operation, and sending the continuation
 109    references as they are found would allow the client progress the
 110    operation more efficiently.
 111
 112    Operations that complete in stages or that progress through various
 113    states as they complete might want to send intermediate responses to
 114    the client, thereby informing it of the status of the operation.
 115    For example, an LDAP implementation might define an extended
 116
 117 Harrison & Zeilenga         Expires September 28, 2003        [Page 2]
 118 \f
 119 Internet-Draft        LDAP Intermediate Response         28 March 2003
 120
 121
 122    operation to create a new replica of an administrative area on a
 123    server, and the operation completes in three stages: (1) begin
 124    creation of replica, (2) send replica data to server, (3) replica
 125    creation complete.  Intermediate messages might be sent from the
 126    server to the client at the beginning of each stage with the final
 127    response for the extended operation being sent after stage (3) is
 128    complete.
 129
 130    As LDAP [RFC3377] is currently defined, there is no general LDAP
 131    message type that can be used to return intermediate results.  A
 132    single, reusable LDAP message for carrying intermediate response
 133    information is desired to avoid repeated modification of the
 134    protocol.  Although the ExtendedResponse message is defined in LDAP,
 135    it is defined to be the one and only response message to an
 136    ExtendedRequest message ([RFC2251] Section 4.12), for unsolicited
 137    responses (LDAP Section 4.4), and to return intermediate responses
 138    for the search operation ([RFC3377] Section 4.5.2, also see Section
 139    5 below).  The adaptation of ExtendedResponse as a general
 140    intermediate response mechanism would be problematic.  In
 141    particular, existing APIs would likely have to be redesigned.  It is
 142    believed (based upon operational experience) that the addition of a
 143    new message to carry intermediate result information is easier to
 144    implement and is less likely to cause interoperability problems with
 145    existing deployed implementations.
 146
 147    This document defines and describes the LDAP IntermediateResponse
 148    message.  This message is intended to be used in conjunction with
 149    ExtendedRequest and ExtendedResponse to define new single-
 150    request/multiple-response operations or in conjunction with a
 151    control when extending existing LDAP operations in a way that
 152    requires them to return intermediate response information.
 153
 154    It is intended that the definitions and descriptions of extended
 155    operations and controls that make use of the IntermediateResponse
 156    message will define the circumstances when an IntermediateResponse
 157    message can be sent by a server and the associated meaning of an
 158    IntermediateResponse message sent in a particular circumstance.
 159    Similarly, it is intended that clients will explicitly solicit
 160    IntermediateResponse messages by issuing operations that
 161    specifically call for their return.
 162
 163    The LDAP Content Sync Operation [draft-zeilenga-ldup-sync] (a work
 164    in progress) demonstrates one use of LDAP Intermediate Response
 165    messages.
 166
 167 2. Conventions used in this document
 168
 169    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 170    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
 171    document are to be interpreted as described in [RFC2119].
 172
 173
 174
 175
 176 Harrison & Zeilenga         Expires September 28, 2003        [Page 3]
 177 \f
 178 Internet-Draft        LDAP Intermediate Response         28 March 2003
 179
 180
 181    The term "request control" is used to describe a control that is
 182    included in an LDAP request message sent from an LDAP client to an
 183    LDAP server.
 184
 185 3. The IntermediateResponse Message
 186
 187    This document extends the protocolOp CHOICE of LDAPMessage
 188    ([RFC2251] Section 4.1.1) to include the field:
 189
 190            intermediateResponse  IntermediateResponse
 191
 192    where IntermediateResponse is defined as:
 193
 194            IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
 195                    responseName     [0] LDAPOID OPTIONAL,
 196                    responseValue    [1] OCTET STRING OPTIONAL }
 197
 198    IntermediateResponse messages SHALL NOT be returned to the client
 199    unless the client issues a request that specifically solicits their
 200    return.  This document defines two forms of solicitation: extended
 201    operation and request control.
 202
 203    Although the responseName and responseValue are optional in some
 204    circumstances, generally speaking IntermediateResponse messages have
 205    a predefined responseName and a responseValue.  The value of the
 206    responseName (if present), the syntax of the responseValue (if
 207    present) and the semantics associated with a particular
 208    IntermediateResponse message MUST be specified in documents
 209    describing the extended operation or request control that uses them.
 210    Sections 3.1 and 3.2 describe additional requirements on the
 211    inclusion of responseName and responseValue in IntermediateResponse
 212    messages.
 213
 214 3.1. Usage with LDAP ExtendedRequest and ExtendedResponse
 215
 216    A single-request/multiple-response operation may be defined using a
 217    single ExtendedRequest message to solicit zero or more
 218    IntermediateResponse messages of one or more kinds followed by an
 219    ExtendedResponse message.
 220
 221    An extended operation that defines the return of multiple kinds of
 222    IntermediateResponse messages MUST provide and document a mechanism
 223    for the client to distinguish the kind of IntermediateResponse
 224    message being sent.  This SHALL be accomplished by using different
 225    responseName values for each type of IntermediateResponse message
 226    associated with the extended operation or by including identifying
 227    information in the responseValue of each type of
 228    IntermediateResponse message associated with the extended operation.
 229
 230 3.2. Usage with LDAP Request Controls
 231
 232    Any LDAP operation may be extended by the addition of one or more
 233    controls ([RFC2251] Section 4.1.12).  A control's semantics may
 234
 235 Harrison & Zeilenga         Expires September 28, 2003        [Page 4]
 236 \f
 237 Internet-Draft        LDAP Intermediate Response         28 March 2003
 238
 239
 240    include the return of zero or more IntermediateResponse messages
 241    prior to returning the final result code for the operation.  One or
 242    more kinds of IntermediateResponse messages may be sent in response
 243    to a request control.
 244
 245    All IntermediateResponse messages associated with request controls
 246    SHALL include a responseName.  This requirement ensures that the
 247    client can correctly identify the source of IntermediateResponse
 248    messages when
 249
 250            (a) two or more controls using IntermediateResponse messages
 251                are included in a request for any LDAP operation or
 252
 253            (b) one or more controls using IntermediateResponse messages
 254                are included in a request with an LDAP extended
 255                operation that uses IntermediateResponse messages.
 256
 257    A request control that defines the return of multiple kinds of
 258    IntermediateResponse messages MUST provide and document a mechanism
 259    for the client to distinguish the kind of IntermediateResponse
 260    message being sent.  This SHALL be accomplished by using different
 261    responseName values for each type of IntermediateResponse message
 262    associated with the request control or by including identifying
 263    information in the responseValue of each type of
 264    IntermediateResponse message associated with the request control.
 265
 266 4. Advertising Support for IntermediateResponse Messages
 267
 268    Because IntermediateResponse messages are associated with extended
 269    operations or controls and LDAP provides a means for advertising the
 270    extended operations and controls supported by a server (using the
 271    supportedExtensions and supportedControls attributes of the root DSE
 272    attributes), no separate means for advertising support for
 273    IntermediateResponse messages is needed (or provided).
 274
 275 5. Use of IntermediateResponse and ExtendedResponse with Search
 276
 277    It is noted that ExtendedResponse messages may be sent in response
 278    to LDAP search operations with controls ([RFC2251] Section 4.5.1).
 279    This use of ExtendedResponse messages SHOULD be viewed as deprecated
 280    in favor of use of the IntermediateResponse messages.
 281
 282 6. Security Considerations
 283
 284    This document describes an enhancement to LDAP.  All security
 285    considerations of [RFC3377] apply to this document, however it does
 286    not introduce any new security considerations to LDAP.
 287
 288    Security considerations specific to each extension using this
 289    protocol mechanism shall be discussed in the technical specification
 290    detailing the extension.
 291
 292 7. IANA Considerations
 293
 294 Harrison & Zeilenga         Expires September 28, 2003        [Page 5]
 295 \f
 296 Internet-Draft        LDAP Intermediate Response         28 March 2003
 297
 298
 299
 300    Registration of the following value is requested [RFC3383].
 301
 302 7.1. LDAP Message Type
 303
 304    It is requested that IANA register upon Standards Action an LDAP
 305    Message Type to identify the LDAP IntermediateResponse message as
 306    defined in section 3 of this document.
 307
 308
 309    The following registration template is suggested:
 310
 311    Subject: Request for LDAP Message Type Registration
 312    Person & email address to contact for further information:
 313       Roger Harrison <roger_harrison@novell.com>
 314       Specification: RFCXXXX
 315       Author/Change Controller: IESG
 316       Comments: Identifies the LDAP IntermediateResponse Message
 317
 318 Acknowledgments
 319
 320    The authors would like to acknowledge the members of the IETF LDAP
 321    Extensions (ldapext) working group mail list who responded to the
 322    suggestion that a multiple-response paradigm might be useful for
 323    LDAP extended requests.  Special thanks go to two individuals: David
 324    Wilbur who first introduced the idea on the working group list, and
 325    Thomas Salter, who succinctly summarized the group's discussion.
 326
 327 Normative References
 328
 329     [RFC2119]
 330         Bradner, S., "Key Words for use in RFCs to Indicate Requirement
 331         Levels", BCP 14, RFC 2119, March 1997.
 332
 333     [RFC2251]
 334         Wahl, M., Howes, T., and S. Kille, "Lightweight Directory
 335         Access Protocol (v3)", RFC 2251, December 1997.
 336
 337    [RFC3377]
 338         Hodges, J. and R. Morgan, "Lightweight Directory Access
 339         Protocol (v3): Technical Specification", RFC 3377, September
 340         2002.
 341
 342    [RFC3383]
 343         Zeilenga, K., "Internet Assigned Numbers Authority (IANA)
 344         Considerations for the Lightweight Directory Access Protocol
 345         (LDAP)", RFC 3383, September 2002.
 346
 347 Informative References
 348
 349    [draft-zeilenga-ldup-sync]
 350
 351
 352
 353 Harrison & Zeilenga         Expires September 28, 2003        [Page 6]
 354 \f
 355 Internet-Draft        LDAP Intermediate Response         28 March 2003
 356
 357
 358         Zeilenga, K., "LDAP Content Synchronization Operation", Work in
 359         Progress.
 360
 361 Authors' Addresses
 362
 363    Roger Harrison
 364    Novell, Inc.
 365    1800 S. Novell Place
 366    Provo, UT 84606
 367    +1 801 861 2642
 368    roger_harrison@novell.com
 369
 370
 371    Kurt D. Zeilenga
 372    OpenLDAP Foundation
 373    Kurt@OpenLDAP.org
 374
 375 Full Copyright Statement
 376
 377    "Copyright (C) The Internet Society (date).  All Rights Reserved.
 378    This document and translations of it may be copied and furnished to
 379    others, and derivative works that comment on or otherwise explain it
 380    or assist in its implementation may be prepared, copied, published
 381    and distributed, in whole or in part, without restriction of any
 382    kind, provided that the above copyright notice and this paragraph
 383    are included on all such copies and derivative works.  However, this
 384    document itself may not be modified in any way, such as by removing
 385    the copyright notice or references to the Internet Society or other
 386    Internet organizations, except as needed for the purpose of
 387    developing Internet standards in which case the procedures for
 388    copyrights defined in the Internet Standards process must be
 389    followed, or as required to translate it into languages other than
 390    English.
 391
 392    The limited permissions granted above are perpetual and will not be
 393    revoked by the Internet Society or its successors or assigns.
 394
 395    This document and the information contained herein is provided on an
 396    "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
 397    TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
 398    BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
 399    HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
 400    MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
 401
 402 Appendix A - Document Revision History
 403    Editors' Note: this appendix should be removed prior to publication
 404    as an RFC.  It is provided as an aid to reviewers of this "work in
 405    progress."
 406
 407 A.1. draft-rharrison-ldap-extPartResp-00.txt
 408
 409    Initial revision of draft.
 410
 411
 412 Harrison & Zeilenga         Expires September 28, 2003        [Page 7]
 413 \f
 414 Internet-Draft        LDAP Intermediate Response         28 March 2003
 415
 416
 417 A.2. draft-rharrison-ldap-extPartResp-01.txt
 418
 419    Changed responseName to be optional to align with [RFC3377]
 420    definition of ExtendedResponse.
 421
 422 A.3. draft-rharrison-ldap-extPartResp-02.txt
 423
 424    Minor terminology corrections.  Clarified use of
 425    ExtendedPartialResponse with LDAP extended operations and other LDAP
 426    operations with controls.
 427
 428 A.4. draft-rharrison-ldap-intermediateResp-00.txt
 429
 430    - Changed name of ExtendedPartialResponse to IntermediateResponse.
 431
 432    - Retitled "Motivation" section to "Background and Intended Usage"
 433      and expanded its contents.
 434
 435    - Added detail surrounding the use of the IntermediateResponse with
 436      extended operations and request controls.
 437
 438    - Generalized the way that Intermediate response fits into the ASN.1
 439      definition of LDAP.
 440
 441    - Added information on advertising IntermediateResponse.
 442
 443    - Added information on the use of IntermediateResponse with the
 444      search operation.
 445
 446 A.5. draft-rharrison-ldap-intermediateResp-01.txt
 447
 448    This draft was oriented primarily to preparing the draft for
 449    publication in accordance with established RFC formatting
 450    guidelines. No substantial change in overall content was made.
 451    Changes included the following:
 452
 453    - Retitled document
 454
 455    - Rewrote abstract
 456
 457    - Retitled "Background and Intended Usage" section to "Introduction"
 458      and expanded its contents.
 459
 460    - Retitled Section 3 from "The Intermediate Response PDU" to "The
 461      Intermediate Response Message".
 462
 463    - Renamed references to [RFCnnnn] format
 464
 465    - Added IANA Considerations section
 466
 467    - Retitled "References" section to "Normative References"
 468
 469    - Other small edits to bring draft in line with RFC formatting
 470
 471 Harrison & Zeilenga         Expires September 28, 2003        [Page 8]
 472 \f
 473 Internet-Draft        LDAP Intermediate Response         28 March 2003
 474
 475
 476      guidelines.
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530 Harrison & Zeilenga         Expires September 28, 2003        [Page 9]
 531 \f