]> git.sur5r.net Git - openldap/blob - doc/rfc/rfc3909.txt
Sync with HEAD
[openldap] / 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