]> git.sur5r.net Git - openldap/blob - doc/drafts/draft-zeilenga-ldap-txn-xx.txt
ITS#5973 re-enable patch
[openldap] / doc / drafts / draft-zeilenga-ldap-txn-xx.txt
1
2
3
4
5
6
7 INTERNET-DRAFT                                         Kurt D. Zeilenga
8 Intended Category: Standard Track                         Isode Limited
9 Expires in six months                                  18 November 2007
10
11
12
13                             LDAP Transactions
14                      <draft-zeilenga-ldap-txn-11.txt>
15
16
17 Status of Memo
18
19   This document is intended to be, after appropriate review and
20   revision, submitted to the IESG for consideration as a Proposed
21   Standard.  Distribution of this memo is unlimited.  Technical
22   discussion of this document will take place on the IETF LDAP
23   Extensions mailing list <ldapext@ietf.org>.  Please send editorial
24   comments directly to the author <Kurt.Zeilenga@Isode.COM>.
25
26   By submitting this Internet-Draft, each author represents that any
27   applicable patent or other IPR claims of which he or she is aware have
28   been or will be disclosed, and any of which he or she becomes aware
29   will be disclosed, in accordance with Section 6 of BCP 79.
30
31   Internet-Drafts are working documents of the Internet Engineering Task
32   Force (IETF), its areas, and its working groups. Note that other
33   groups may also distribute working documents as Internet-Drafts.
34
35   Internet-Drafts are draft documents valid for a maximum of six months
36   and may be updated, replaced, or obsoleted by other documents at any
37   time. It is inappropriate to use Internet-Drafts as reference material
38   or to cite them other than as "work in progress."
39
40   The list of current Internet-Drafts can be accessed at
41   http://www.ietf.org/1id-abstracts.html.
42
43   The list of Internet-Draft Shadow Directories can be accessed at
44   http://www.ietf.org/shadow.html.
45
46
47   Copyright (C) The IETF Trust (2007).
48
49   Please see the Full Copyright section near the end of this document
50   for more information.
51
52
53
54
55
56
57
58 Zeilenga                    LDAP Transactions                   [Page 1]
59 \f
60 INTERNET-DRAFT         draft-zeilenga-ldap-txn-11       18 November 2007
61
62
63 Abstract
64
65   Lightweight Directory Access Protocol (LDAP) update operations, such
66   as Add, Delete, and Modify operations, have atomic, consistency,
67   isolation, durability (ACID) properties.  Each of these update
68   operations act upon an entry.  It is often desirable to update two or
69   more entries in a single unit of interaction, a transaction.
70   Transactions are necessary to support a number of applications
71   including resource provisioning.  This document extends LDAP to
72   support transactions.
73
74
75 1. Overview
76
77   This document extends the Lightweight Directory Access Protocol (LDAP)
78   [RFC4510] to allow clients to relate a number of update operations
79   [RFC4511] and have them performed as one unit of interaction, a
80   transaction.  As with distinct update operations, each transaction has
81   atomic, consistency, isolation, and durability (ACID) properties
82   [ACID].
83
84   This extension consists of two extended operations, one control, and
85   one unsolicited notification message.  The Start Transaction operation
86   is used to obtain a transaction identifier.  This identifier is then
87   attached to multiple update operations to indicate that they belong to
88   the transaction using the Transaction Specification control.  The End
89   Transaction is used to settle (commit or abort) the transaction.  The
90   Aborted Transaction Notice is provided by the server to notify the
91   client that the server is no longer willing or able to process an
92   outstanding transaction.
93
94
95 1.1. Conventions and Terminology
96
97   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
98   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
99   document are to be interpreted as described in BCP 14 [RFC2119].
100
101   Protocol elements are described using ASN.1 [X.680] with implicit
102   tags.  The term "BER-encoded" means the element is to be encoded using
103   the Basic Encoding Rules [X.690] under the restrictions detailed in
104   Section 5.1 of [RFC4511].
105
106   DSA stands for "Directory System Agent" (a server).  DSE stands for
107   "DSA-specific entry".
108
109
110 2.  Elements of an LDAP Transaction
111
112
113
114 Zeilenga                    LDAP Transactions                   [Page 2]
115 \f
116 INTERNET-DRAFT         draft-zeilenga-ldap-txn-11       18 November 2007
117
118
119 2.1.  Start Transaction Request and Response
120
121   A Start Transaction Request is an LDAPMessage of CHOICE extendedReq
122   where the requestName is IANA-ASSIGNED-OID.1 and the requestValue is
123   absent.
124
125   A Start Transaction Response is an LDAPMessage of CHOICE extendedRes
126   sent in response to a Start Transaction Request.  Its responseName is
127   absent.  When the resultCode is success (0), responseValue is present
128   and contains a transaction identifier.  Otherwise, the responseValue
129   is absent.
130
131
132 2.2.  Transaction Specification Control
133
134   A Transaction Specification control is an LDAPControl where the
135   controlType is IANA-ASSIGNED-OID.2, the criticality is TRUE, and the
136   controlValue is a transaction identifier.  The control is appropriate
137   for update requests including Add, Delete, Modify, and ModifyDN
138   (Rename) requests [RFC4511], as well as the Password Modify requests
139   [RFC3062].
140
141   As discussed in Section 4, the Transaction Specification control can
142   be used in conjunction with request controls appropriate for the
143   update request.
144
145
146 2.3.  End Transactions Request and Response
147
148   An End Transaction Request is an LDAPMessage of CHOICE extendedReq
149   where the requestName is IANA-ASSIGNED-OID.3 and the requestValue is
150   present and contains a BER-encoded txnEndReq.
151
152        txnEndReq ::= SEQUENCE {
153             commit         BOOLEAN DEFAULT TRUE,
154             identifier     OCTET STRING }
155
156   A commit value of TRUE indicates a request to commit the transaction
157   identified by the identifier.  A commit value of FALSE indicates a
158   request to abort the identified transaction.
159
160   An End Transaction Response is an LDAPMessage sent in response to a
161   End Transaction Request.  Its response name is absent.  The
162   responseValue when present contains a BER-encoded txnEndRes.
163
164        txnEndRes ::= SEQUENCE {
165             messageID MessageID OPTIONAL,
166                  -- msgid associated with non-success resultCode
167
168
169
170 Zeilenga                    LDAP Transactions                   [Page 3]
171 \f
172 INTERNET-DRAFT         draft-zeilenga-ldap-txn-11       18 November 2007
173
174
175             updatesControls SEQUENCE OF updateControls SEQUENCE {
176                  messageID MessageID,
177                       -- msgid associated with controls
178                  controls  Controls
179             } OPTIONAL
180        }
181        -- where MessageID and Controls are as specified in RFC 4511
182
183   The txnEndRes.messageID provides the message id of the update request
184   associated with a non-success response.  txnEndRes.messageID is absent
185   when resultCode of the End Transaction Response is success (0).
186
187   The txnEndRes.updatesControls provides a facility for returning
188   response controls that normally (i.e., in absence of transactions)
189   would be returned in an update response.  The updateControls.messageID
190   provides the message id of the update request associated with the
191   response controls provided in updateControls.controls.
192
193   The txnEndRes.updatesControls is absent when there are no update
194   response controls to return.
195
196   If both txnEndRes.messageID and txnEndRes.updatesControl are absent,
197   the responseValue of the End Transaction Response is absent.
198
199
200 2.4. Aborted Transaction Notice
201
202   The Aborted Transaction Notice is an Unsolicited Notification message
203   where the responseName is IANA-ASSIGNED-OID.4 and responseValue is
204   present and contains a transaction identifier.
205
206
207 3. An LDAP Transaction
208
209 3.1. Extension Discovery
210
211   To allow clients to discover support for this extension, servers
212   implementing this specification SHOULD publish IANA-ASSIGNED-OID.1 and
213   IANA-ASSIGNED-OID.3 as values of the 'supportedExtension' attribute
214   [RFC4512] within the Root DSE, and publish the IANA-ASSIGNED-OID.2 as
215   a value of the 'supportedControl' attribute [RFC4512] of the Root DSE.
216
217   A server MAY choose to advertise this extension only when the client
218   is authorized to use it.
219
220
221 3.2. Starting a Transaction
222
223
224
225
226 Zeilenga                    LDAP Transactions                   [Page 4]
227 \f
228 INTERNET-DRAFT         draft-zeilenga-ldap-txn-11       18 November 2007
229
230
231   A client wishing to perform a sequence of directory updates as an
232   transaction issues a Start Transaction Request.  A server which is
233   willing and able to support transactions responds to this request with
234   a Start Transaction Response providing a transaction identifier and
235   with a resultCode of success (0).  Otherwise, the server responds with
236   a Start Transaction Response with a result code other than success
237   indicating the nature of the failure.
238
239   The transaction identifier provided upon successful start of a
240   transaction is used in subsequent protocol messages to identify this
241   transaction.
242
243
244 3.3. Specification of a Transaction
245
246   The client then can issue one or more update requests, each with a
247   Transaction Specification control containing the transaction
248   identifier indicating the updates are to processed as part of the
249   transaction.  Each of these update request MUST have a different
250   MessageID value.  If the server is unwilling or unable to attempt to
251   process the requested update operation as part of the transaction, the
252   server immediately returns the appropriate response to the request
253   with a resultCode indicating the nature of the failure.  Otherwise,
254   the server immediately returns success (0) and the defers further
255   processing of the operation is then deferred until settlement.
256
257   If the server becomes unwilling or unable to continue the
258   specification of a transaction, the server issues an Aborted
259   Transaction Notice with a non-success resultCode indicating the nature
260   of the failure.  All operations that were to be processed as part of
261   the transaction are implicitly abandoned.  Upon receipt of an Aborted
262   Transaction Notice, the client is to discontinue all use of the
263   transaction identifier as the transaction is null and void.  Any
264   future use of identifier by the client will result in a response
265   containing a non-success resultCode.
266
267
268 3.4. Transaction Settlement
269
270   A client requests settlement of transaction by issuing an End
271   Transaction request for the transaction indicating whether it desires
272   the transaction to be committed or aborted.
273
274   Upon receipt of a request to abort the transaction, the server is to
275   abort the identified transaction (abandoning all operations which are
276   part of the transaction) and indicate that it has done so by returning
277   an End Transaction Response with a resultCode of success (0).
278
279
280
281
282 Zeilenga                    LDAP Transactions                   [Page 5]
283 \f
284 INTERNET-DRAFT         draft-zeilenga-ldap-txn-11       18 November 2007
285
286
287   Upon receipt of a request to commit the transaction, the server
288   processes all update operations of the transaction as one atomic,
289   durable, isolated, and consistent action with each requested update
290   being processed in turn.  Either all of the requested updates are to
291   be successfully applied or none of the requested are to be applied.
292   The server returns an End Transaction Response with a resultCode of
293   success (0) and no responseValue to indicate all the requested updates
294   were applied.  Otherwise, the server returns an End Transaction with
295   an non-success resultCode indicating the nature of the failure.  If
296   the failure is associated with a particular update request, the
297   txnEndRes.messageID in the responseValue is the messageID of this
298   update request.  If the failure was not associated with any particular
299   update request, no txnEnd.messageID is provided.
300
301   There is no requirement that a server serialize transactions, or
302   updates requested outside of a transaction.  That is, a server MAY
303   process multiple commit requests (from one or more clients) acting
304   upon different sets of entries concurrently.   A server MUST avoid
305   deadlock.
306
307
308 3.5. Miscellaneous Issues
309
310   Transactions cannot be nested.
311
312   Each LDAP transaction should be initiated, specified, and settled
313   within a stable security context.   Between the Start request and the
314   End response, the peers SHOULD avoid negotiating new security
315   associations and/or layers.
316
317   Upon receipt of a Bind or Unbind request, the server SHALL abort any
318   and all outstanding transactions without notice and nullify their
319   identifiers.
320
321
322 4. Interaction with Other Extensions
323
324   The LDAP Transaction extension may be used with many but not all LDAP
325   control extensions designed to extend Update (and possibly other)
326   operations.  The remainder of this subsection discusses interaction
327   with a number of control extensions.  Interaction with other control
328   extensions may be discussed in other documents, in particular in
329   control extension specifications.
330
331
332 4.1. Assertion Control
333
334   The Assertion [RFC4528] control is appropriate for use with update
335
336
337
338 Zeilenga                    LDAP Transactions                   [Page 6]
339 \f
340 INTERNET-DRAFT         draft-zeilenga-ldap-txn-11       18 November 2007
341
342
343   requests specified as part of a transaction.  The evaluation of the
344   assertion is performed as part of the transaction.
345
346   The Assertion control is inappropriate for use with either the
347   Transaction Start or End extended operations.
348
349
350 4.2. ManageDsaIT Control
351
352   The ManageDsaIT [RFC3296] control is appropriate for use with update
353   requests specified as part of a transaction.
354
355   The ManageDsaIT control is inappropriate for use with either the
356   Transaction Start or End extended operations.
357
358
359 4.3. No-Op Control
360
361   The No-Op [NO-OP] control is appropriate for use with the Transaction
362   Start or End extended operations.
363
364   The No-Op control is not appropriate for update requests specified as
365   part of a transaction.  A server supporting both the No-Op control
366   extension and this extension SHALL regard a request containing both
367   controls as a protocol violation.  As both of the No-Op and
368   Transaction Specification request controls are required to be marked
369   as critical, a server implementing one of these request controls, or
370   neither, is expected to return unavailableCriticalExtension as
371   prescribed by [RFC4511].
372
373
374 4.4. Proxied Authorization Control
375
376   The Proxied Authorization [RFC4370] control is appropriate for use
377   with the Transaction Start extended operation, but not the Transaction
378   End extended operation or any update request specified as part of a
379   transaction.
380
381   To request that a transaction be performed under a different
382   authorization, the client provides a Proxied Authorization control
383   with the Transaction Start request.  If the client is not authorized
384   to assume the requested authorization identity, the server is to
385   return the authorizationDenied (123) resultCode in its response.
386   Otherwise, further processing of the request and transaction is
387   performed under the requested authorization identity.
388
389   Any proxied authorization request attached to an update request
390   specified as part of a transaction, or attached to a Transaction end
391
392
393
394 Zeilenga                    LDAP Transactions                   [Page 7]
395 \f
396 INTERNET-DRAFT         draft-zeilenga-ldap-txn-11       18 November 2007
397
398
399   request, is to be regarded as a protocol error.
400
401
402 4.5. Read Entry Controls
403
404   The Pre- and Post-Read Entry [RFC4527] request control are appropriate
405   for use with update requests specified as part of a transaction.
406
407   The response control produced in response to a Pre- or Post-Read Entry
408   request control is returned in the txnEndRes.updatesControls field of
409   responseValue of the End Transaction Response.
410
411   The Pre- and Post-Read Entry controls are inappropriate for use in the
412   LDAPMessage.controls field of the Transaction Start and End request
413   and response messages.
414
415
416 4.6. Relax Rules Control
417
418   The Relax Rules [RELAX] control is appropriate for use with update
419   requests specified as part of a transaction.
420
421   The Relax Rules control is inappropriate for use with either the
422   Transaction Start or End extended operations.
423
424
425 5. Distributed Directory Considerations
426
427   The LDAP/X.500 models provide for distributed directory operations,
428   including server-side chaining and client-side chasing of referrals.
429
430   This document does not preclude servers from chaining operations which
431   are part of a transaction.  However, if a server does attempt such
432   chaining, it MUST ensure that transaction semantics are provided.
433
434   This mechanism defined by this document does not support client-side
435   chasing.  Grouping cookies used to identify the transaction are
436   specific to a particular client/server session.
437
438   The LDAP/X.500 models provide for a single-master/multiple-shadow
439   replication architecture.  There is no requirement that changes made
440   to the directory based upon processing a transaction be replicated as
441   one atomic action.  Hence, clients SHOULD NOT assume tight data
442   consistency nor fast data convergence of shadow copies unless they
443   have prior knowledge that these properties are provided.  Note that
444   DontUseCopy control [DONTUSECOPY] control may be used in conjunction
445   with the LDAP search request to ask for the return of the
446   authoritative copy of the entry.
447
448
449
450 Zeilenga                    LDAP Transactions                   [Page 8]
451 \f
452 INTERNET-DRAFT         draft-zeilenga-ldap-txn-11       18 November 2007
453
454
455 6. Security Considerations
456
457   Transactions mechanisms may be the target of denial-of-service
458   attacks, especially where implementation lock shared resources for the
459   duration of a transaction.
460
461   General security considerations [RFC4510], especially those associated
462   with update operations [RFC4511], apply to this extension.
463
464
465 7. IANA Considerations
466
467   It is requested that Internet Assigned Numbers Authority (IANA) make
468   the following assignments.
469
470
471 7.1.  Object Identifier
472
473   Assignment of an LDAP Object Identifier [RFC4520] to identify the
474   protocol elements specified in this document this document is
475   requested.
476
477       Subject: Request for LDAP Object Identifier Registration
478       Person & email address to contact for further information:
479           Kurt Zeilenga <Kurt.Zeilenga@Isode.COM>
480       Specification: RFC XXXX
481       Author/Change Controller: IESG
482       Comments: Identifies protocol elements for LDAP Transactions
483
484
485 7.2.  LDAP Protocol Mechanism
486
487   Registration of the protocol mechanisms [RFC4520] specified in this
488   document is requested.
489
490       Subject: Request for LDAP Protocol Mechanism Registration
491       Object Identifier: see table
492       Description: see table
493       Person & email address to contact for further information:
494           Kurt Zeilenga <Kurt.Zeilenga@Isode.COM>
495       Specification: RFC XXXX
496       Author/Change Controller: IESG
497       Comments:
498
499       Object Identifier   Type  Description
500       ------------------- ----  ----------------------------------
501       IANA-ASSIGNED-OID.1 E     Start Transaction Extended Request
502       IANA-ASSIGNED-OID.2 C     Transaction Specification Control
503
504
505
506 Zeilenga                    LDAP Transactions                   [Page 9]
507 \f
508 INTERNET-DRAFT         draft-zeilenga-ldap-txn-11       18 November 2007
509
510
511       IANA-ASSIGNED-OID.3 E     End Transaction Extended Request
512       IANA-ASSIGNED-OID.4 N     Aborted Transaction Notice
513
514       Legend
515       ------------------------
516       C => supportedControl
517       E => supportedExtension
518       N => Unsolicited Notice
519
520
521 8. Acknowledgments
522
523   The author gratefully acknowledges the contributions made by Internet
524   Engineering Task Force participants.
525
526
527 9. Author's Address
528
529   Kurt D. Zeilenga
530   Isode Limited
531
532   Email: Kurt.Zeilenga@Isode.COM
533
534
535 10. References
536
537   [[Note to the RFC Editor: please replace the citation tags used in
538   referencing Internet-Drafts with tags of the form RFCnnnn where
539   possible.]]
540
541
542 10.1. Normative References
543
544   [RFC2119]     Bradner, S., "Key words for use in RFCs to Indicate
545                 Requirement Levels", BCP 14 (also RFC 2119), March 1997.
546
547   [RFC3062]     Zeilenga, K., "LDAP Password Modify Extended Operation",
548                 RFC 3062, February 2000.
549
550   [RFC3296]     Zeilenga, K., "Named Subordinate References in
551                 Lightweight Directory Access Protocol (LDAP)
552                 Directories", RFC 3296, July 2002.
553
554   [RFC4370]     Weltman, R., "LDAP Proxied Authentication Control", RFC
555                 4370, Feb. 2006.
556
557   [RFC4510]     Zeilenga, K. (editor), "LDAP: Technical Specification
558                 Road Map", RFC 4510, June 2006.
559
560
561
562 Zeilenga                    LDAP Transactions                  [Page 10]
563 \f
564 INTERNET-DRAFT         draft-zeilenga-ldap-txn-11       18 November 2007
565
566
567   [RFC4511]     Sermersheim, J. (editor), "LDAP: The Protocol", RFC
568                 4511, June 2006.
569
570   [RFC4512]     Zeilenga, K. (editor), "LDAP: Directory Information
571                 Models", RFC 4512, June 2006.
572
573   [RFC4527]     Zeilenga, K., "LDAP Read Entry Controls", RFC 4527, June
574                 2006.
575
576   [RFC4528]     Zeilenga, K., "LDAP Assertion Control", RFC 4528, June
577                 2006.
578
579   [X.680]       International Telecommunication Union -
580                 Telecommunication Standardization Sector, "Abstract
581                 Syntax Notation One (ASN.1) - Specification of Basic
582                 Notation", X.680(2002) (also ISO/IEC 8824-1:2002).
583
584   [X.690]       International Telecommunication Union -
585                 Telecommunication Standardization Sector, "Specification
586                 of ASN.1 encoding rules: Basic Encoding Rules (BER),
587                 Canonical Encoding Rules (CER), and Distinguished
588                 Encoding Rules (DER)", X.690(2002) (also ISO/IEC
589                 8825-1:2002).
590
591   [NO-OP]       Zeilenga, K., "LDAP No-Operation Control", draft-
592                 zeilenga-ldap-noop-xx.txt, a work in progress.
593
594   [RELAX]       Zeilenga, K., "LDAP Relax Rules Control", draft-
595                 zeilenga-ldap-relax-xx.txt, a work in progress.
596
597
598 10.2. Informative References
599
600   [RFC4520]     Zeilenga, K., "Internet Assigned Numbers Authority
601                 (IANA) Considerations for the Lightweight Directory
602                 Access Protocol (LDAP)", RFC 4520, BCP 64, June 2006.
603
604   [ACID]        Section 4 of ISO/IEC 10026-1:1992.
605
606   [DONTUSECOPY] Zeilenga, K., "LDAP Don't Use Copy Control", draft-
607                 zeilenga-ldap-dontusecopy-xx.txt, a work in progress.
608
609
610
611 Intellectual Property
612
613   The IETF takes no position regarding the validity or scope of any
614   Intellectual Property Rights or other rights that might be claimed to
615
616
617
618 Zeilenga                    LDAP Transactions                  [Page 11]
619 \f
620 INTERNET-DRAFT         draft-zeilenga-ldap-txn-11       18 November 2007
621
622
623   pertain to the implementation or use of the technology described in
624   this document or the extent to which any license under such rights
625   might or might not be available; nor does it represent that it has
626   made any independent effort to identify any such rights.  Information
627   on the procedures with respect to rights in RFC documents can be found
628   in BCP 78 and BCP 79.
629
630   Copies of IPR disclosures made to the IETF Secretariat and any
631   assurances of licenses to be made available, or the result of an
632   attempt made to obtain a general license or permission for the use of
633   such proprietary rights by implementers or users of this specification
634   can be obtained from the IETF on-line IPR repository at
635   http://www.ietf.org/ipr.
636
637   The IETF invites any interested party to bring to its attention any
638   copyrights, patents or patent applications, or other proprietary
639   rights that may cover technology that may be required to implement
640   this standard.  Please address the information to the IETF at
641   ietf-ipr@ietf.org.
642
643
644
645 Full Copyright
646
647   Copyright (C) The IETF Trust (2007).
648
649   This document is subject to the rights, licenses and restrictions
650   contained in BCP 78, and except as set forth therein, the authors
651   retain all their rights.
652
653   This document and the information contained herein are provided on an
654   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
655   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
656   THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
657   OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
658   THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
659   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674 Zeilenga                    LDAP Transactions                  [Page 12]
675 \f