external/bsd/openldap/dist/doc/rfc/rfc3909.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                        K. Zeilenga
   8 Request for Comments: 3909                           OpenLDAP Foundation
   9 Category: Standards Track                                   October 2004
  10
  11
  12              Lightweight Directory Access Protocol (LDAP)
  13                             Cancel Operation
  14
  15 Status of this Memo
  16
  17    This document specifies an Internet standards track protocol for the
  18    Internet community, and requests discussion and suggestions for
  19    improvements.  Please refer to the current edition of the "Internet
  20    Official Protocol Standards" (STD 1) for the standardization state
  21    and status of this protocol.  Distribution of this memo is unlimited.
  22
  23 Copyright Notice
  24
  25    Copyright (C) The Internet Society (2004).
  26
  27 Abstract
  28
  29    This specification describes a Lightweight Directory Access Protocol
  30    (LDAP) extended operation to cancel (or abandon) an outstanding
  31    operation.  Unlike the LDAP Abandon operation, but like the X.511
  32    Directory Access Protocol (DAP) Abandon operation, this operation has
  33    a response which provides an indication of its outcome.
  34
  35 1.  Background and Intent of Use
  36
  37    The Lightweight Directory Access Protocol (LDAP) [RFC3377] provides
  38    an Abandon operation [RFC2251] which clients may use to cancel other
  39    operations.  The Abandon operation does not have a response and
  40    requires no response from the abandoned operation.  These semantics
  41    provide the client with no clear indication of the outcome of the
  42    Abandon operation.
  43
  44    The X.511 Directory Access Protocol (DAP) [X.511] provides an Abandon
  45    operation which has a response and also requires the abandoned
  46    operation to return a response indicating it was canceled.  The LDAP
  47    Cancel operation is modeled after the DAP Abandon operation.
  48
  49    The LDAP Cancel operation SHOULD be used instead of the LDAP Abandon
  50    operation when the client needs an indication of the outcome.  This
  51    operation may be used to cancel both interrogation and update
  52    operations.
  53
  54
  55
  56
  57
  58 Zeilenga                    Standards Track                     [Page 1]
  59 \f
  60 RFC 3909                 LDAP Cancel Operation              October 2004
  61
  62
  63    Protocol elements are described using ASN.1 [X.680] with implicit
  64    tags.  The term "BER-encoded" means the element is to be encoded
  65    using the Basic Encoding Rules [X.690] under the restrictions
  66    detailed in Section 5.1 of [RFC2251].
  67
  68    DSA stands for Directory System Agent (or server).
  69    DSE stands for DSA-specific Entry.
  70
  71    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  72    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
  73    document are to be interpreted as described in BCP 14 [RFC2119].
  74
  75 2.  Cancel Operation
  76
  77    The Cancel operation is defined as an LDAP Extended Operation
  78    [RFC2251, Section 4.12] identified by the object identifier
  79    1.3.6.1.1.8.  This section details the syntax of the Cancel request
  80    and response messages and defines additional LDAP resultCodes.
  81
  82 2.1.  Cancel Request
  83
  84    The Cancel request is an ExtendedRequest with the requestName field
  85    containing 1.3.6.1.1.8 and a requestValue field which contains a
  86    BER-encoded cancelRequestValue value.
  87
  88       cancelRequestValue ::= SEQUENCE {
  89           cancelID        MessageID
  90                           -- MessageID is as defined in [RFC2251]
  91       }
  92
  93    The cancelID field contains the message ID associated with the
  94    operation to be canceled.
  95
  96 2.2.  Cancel Response
  97
  98    A Cancel response is an ExtendedResponse where the responseName and
  99    response fields are absent.
 100
 101 2.3.  Additional Result Codes
 102
 103    Implementations of this specification SHALL recognize the following
 104    additional resultCode values:
 105
 106       canceled        (118)
 107       noSuchOperation (119)
 108       tooLate         (120)
 109       cannotCancel    (121)
 110
 111
 112
 113
 114 Zeilenga                    Standards Track                     [Page 2]
 115 \f
 116 RFC 3909                 LDAP Cancel Operation              October 2004
 117
 118
 119 3.  Operational Semantics
 120
 121    The function of the Cancel Operation is to request that the server
 122    cancel an outstanding operation issued within the same session.
 123
 124    The client requests the cancelation of an outstanding operation by
 125    issuing a Cancel Response with a cancelID set to the message ID of
 126    the outstanding operation.  The Cancel Request itself has a distinct
 127    message ID.  Clients SHOULD NOT request the cancelation of an
 128    operation multiple times.
 129
 130    If the server is willing and able to cancel the outstanding operation
 131    identified by the cancelId, the server SHALL return a Cancel Response
 132    with a success resultCode, and the canceled operation SHALL fail with
 133    canceled resultCode.  Otherwise the Cancel Response SHALL have a
 134    non-success resultCode and SHALL NOT have an impact upon the
 135    outstanding operation (if it exists).
 136
 137    The protocolError resultCode is returned if the server is unable to
 138    parse the requestValue or the requestValue is absent,
 139
 140    The noSuchOperation resultCode is returned if the server has no
 141    knowledge of the operation requested for cancelation.
 142
 143    The cannotCancel resultCode is returned if the identified operation
 144    does not support cancelation or the cancel operation could not be
 145    performed.  The following classes of operations are not cancelable:
 146
 147    -  operations which have no response,
 148
 149    -  operations which create, alter, or destroy authentication and/or
 150       authorization associations,
 151
 152    -  operations which establish, alter, or tear-down security services,
 153       and
 154
 155    -  operations which abandon or cancel other operations.
 156
 157    Specifically, the Abandon, Bind, Start TLS [RFC2830], Unbind, and
 158    Cancel operations are not cancelable.
 159
 160    The Cancel operation cannot be abandoned.
 161
 162    The tooLate resultCode is returned to indicate that it is too late to
 163    cancel the outstanding operation.  For example, the server may return
 164    tooLate for a request to cancel an outstanding modify operation which
 165    has already committed updates to the underlying data store.
 166
 167
 168
 169
 170 Zeilenga                    Standards Track                     [Page 3]
 171 \f
 172 RFC 3909                 LDAP Cancel Operation              October 2004
 173
 174
 175    Servers SHOULD indicate their support for this extended operation by
 176    providing 1.3.6.1.1.8 as a value of the 'supportedExtension'
 177    attribute type in their root DSE.  A server MAY choose to advertise
 178    this extension only when the client is authorized to use it.
 179
 180 4.  Security Considerations
 181
 182    This operation is intended to allow a user to cancel operations they
 183    previously issued during the current LDAP association.  In certain
 184    cases, such as when the Proxy Authorization Control is in use,
 185    different outstanding operations may be processed under different
 186    LDAP associations.  Servers MUST NOT allow a user to cancel an
 187    operation belonging to another user.
 188
 189    Some operations should not be cancelable for security reasons.  This
 190    specification disallows the cancelation of the Bind operation and
 191    Start TLS extended operation so as to avoid adding complexity to
 192    authentication, authorization, and security layer semantics.
 193    Designers of future extended operations and/or controls should
 194    disallow abandonment and cancelation when appropriate.
 195
 196 5.  IANA Considerations
 197
 198    The following values [RFC3383] have been registered by the IANA.
 199
 200 5.1.  Object Identifier
 201
 202    The IANA has registered upon Standards Action the LDAP Object
 203    Identifier 1.3.6.1.1.8 to identify the LDAP Cancel Operation as
 204    defined in this document.
 205
 206       Subject: Request for LDAP Object Identifier Registration
 207       Person & email address to contact for further information:
 208            Kurt Zeilenga <kurt@OpenLDAP.org>
 209       Specification: RFC 3909
 210       Author/Change Controller: IESG
 211       Comments:
 212            Identifies the LDAP Cancel Operation
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226 Zeilenga                    Standards Track                     [Page 4]
 227 \f
 228 RFC 3909                 LDAP Cancel Operation              October 2004
 229
 230
 231 5.2.  LDAP Protocol Mechanism
 232
 233    The IANA has registered upon Standards Action the LDAP Protocol
 234    Mechanism described in this document.
 235
 236       Subject: LDAP Protocol Mechanism Registration
 237       Object Identifier: 1.3.6.1.1.8
 238       Description: LDAP Cancel Operation
 239       Person & email address to contact for further information:
 240            Kurt Zeilenga <kurt@openldap.org>
 241       Usage: Extended Operation
 242       Specification: RFC 3909
 243       Author/Change Controller: IESG
 244       Comments: none
 245
 246 5.3.  LDAP Result Codes
 247
 248    The IANA has registered upon Standards Action the LDAP Result Codes
 249    described in this document.
 250
 251       Subject: LDAP Result Code Registration
 252       Person & email address to contact for further information:
 253            Kurt Zeilenga <kurt@OpenLDAP.org>
 254       Result Code Name: canceled (118)
 255       Result Code Name: noSuchOperation (119)
 256       Result Code Name: tooLate (120)
 257       Result Code Name: cannotCancel (121)
 258       Specification: RFC 3909
 259       Author/Change Controller: IESG
 260
 261 6.  Acknowledgment
 262
 263    The LDAP Cancel operation is modeled after the X.511 DAP Abandon
 264    operation.
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282 Zeilenga                    Standards Track                     [Page 5]
 283 \f
 284 RFC 3909                 LDAP Cancel Operation              October 2004
 285
 286
 287 7.  References
 288
 289 7.1.  Normative References
 290
 291    [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
 292               Requirement Levels", BCP 14, RFC 2119, March 1997.
 293
 294    [RFC2251]  Wahl, M., Howes, T., and S. Kille, "Lightweight Directory
 295               Access Protocol (v3)", RFC 2251, December 1997.
 296
 297    [RFC2830]  Hodges, J., Morgan, R., and M. Wahl, "Lightweight
 298               Directory Access Protocol (v3): Extension for Transport
 299               Layer Security", RFC 2830, May 2000.
 300
 301    [RFC3377]  Hodges, J. and R. Morgan, "Lightweight Directory Access
 302               Protocol (v3): Technical Specification", RFC 3377,
 303               September 2002.
 304
 305    [X.680]    International Telecommunication Union - Telecommunication
 306               Standardization Sector, "Abstract Syntax Notation One
 307               (ASN.1) - Specification of Basic Notation", X.680(1997)
 308               (also ISO/IEC 8824-1:1998).
 309
 310    [X.690]    International Telecommunication Union - Telecommunication
 311               Standardization Sector, "Specification of ASN.1 encoding
 312               rules: Basic Encoding Rules (BER), Canonical Encoding
 313               Rules (CER), and Distinguished Encoding Rules (DER)",
 314               X.690(1997) (also ISO/IEC 8825-1:1998).
 315
 316 7.2.  Informative References
 317
 318    [RFC3383]  Zeilenga, K., "Internet Assigned Numbers Authority (IANA)
 319               Considerations for the Lightweight Directory Access
 320               Protocol (LDAP)", BCP 64, RFC 3383, September 2002.
 321
 322    [X.511]    International Telecommunication Union - Telecommunication
 323               Standardization Sector, "The Directory: Abstract Service
 324               Definition", X.511(1993).
 325
 326 8.  Author's Address
 327
 328    Kurt D. Zeilenga
 329    OpenLDAP Foundation
 330
 331    EMail: Kurt@OpenLDAP.org
 332
 333
 334
 335
 336
 337
 338 Zeilenga                    Standards Track                     [Page 6]
 339 \f
 340 RFC 3909                 LDAP Cancel Operation              October 2004
 341
 342
 343 9.  Full Copyright Statement
 344
 345    Copyright (C) The Internet Society (2004).
 346
 347    This document is subject to the rights, licenses and restrictions
 348    contained in BCP 78, and at www.rfc-editor.org, and except as set
 349    forth therein, the authors retain all their rights.
 350
 351    This document and the information contained herein are provided on an
 352    "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
 353    OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
 354    ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
 355    INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
 356    INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
 357    WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
 358
 359 Intellectual Property
 360
 361    The IETF takes no position regarding the validity or scope of any
 362    Intellectual Property Rights or other rights that might be claimed to
 363    pertain to the implementation or use of the technology described in
 364    this document or the extent to which any license under such rights
 365    might or might not be available; nor does it represent that it has
 366    made any independent effort to identify any such rights.  Information
 367    on the ISOC's procedures with respect to rights in ISOC Documents can
 368    be found in BCP 78 and BCP 79.
 369
 370    Copies of IPR disclosures made to the IETF Secretariat and any
 371    assurances of licenses to be made available, or the result of an
 372    attempt made to obtain a general license or permission for the use of
 373    such proprietary rights by implementers or users of this
 374    specification can be obtained from the IETF on-line IPR repository at
 375    http://www.ietf.org/ipr.
 376
 377    The IETF invites any interested party to bring to its attention any
 378    copyrights, patents or patent applications, or other proprietary
 379    rights that may cover technology that may be required to implement
 380    this standard.  Please address the information to the IETF at ietf-
 381    ipr@ietf.org.
 382
 383 Acknowledgement
 384
 385    Funding for the RFC Editor function is currently provided by the
 386    Internet Society.
 387
 388
 389
 390
 391
 392
 393
 394 Zeilenga                    Standards Track                     [Page 7]
 395 \f