git.sur5r.net Git - openldap/blob - 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