git.sur5r.net Git - openldap/blob - 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                   OpenLDAP Foundation
   9 Expires in six months                                      5 March 2006
  10
  11
  12                             LDAP Transactions
  13                      <draft-zeilenga-ldap-txn-07.txt>
  14
  15
  16 Status of Memo
  17
  18   This document is intended to be, after appropriate review and
  19   revision, submitted to the IESG for consideration as a Proposed
  20   Standard.  Distribution of this memo is unlimited.  Technical
  21   discussion of this document will take place on the IETF LDAP
  22   Extensions mailing list <ldapext@ietf.org>.  Please send editorial
  23   comments directly to the author <Kurt@OpenLDAP.org>.
  24
  25   By submitting this Internet-Draft, each author represents that any
  26   applicable patent or other IPR claims of which he or she is aware have
  27   been or will be disclosed, and any of which he or she becomes aware
  28   will be disclosed, in accordance with Section 6 of BCP 79.
  29
  30   Internet-Drafts are working documents of the Internet Engineering Task
  31   Force (IETF), its areas, and its working groups. Note that other
  32   groups may also distribute working documents as Internet-Drafts.
  33
  34   Internet-Drafts are draft documents valid for a maximum of six months
  35   and may be updated, replaced, or obsoleted by other documents at any
  36   time. It is inappropriate to use Internet-Drafts as reference material
  37   or to cite them other than as "work in progress."
  38
  39   The list of current Internet-Drafts can be accessed at
  40   http://www.ietf.org/1id-abstracts.html
  41
  42   The list of Internet-Draft Shadow Directories can be accessed at
  43   http://www.ietf.org/shadow.html
  44
  45
  46   Copyright (C) The Internet Society (2006).  All Rights Reserved.
  47
  48   Please see the Full Copyright section near the end of this document
  49   for more information.
  50
  51
  52 Abstract
  53
  54   Lightweight Directory Access Protocol (LDAP) update operations, such
  55
  56
  57
  58 Zeilenga                    LDAP Transactions                   [Page 1]
  59 \f
  60 INTERNET-DRAFT         draft-zeilenga-ldap-txn-07           5 March 2006
  61
  62
  63   as Add, Delete, and Modify operations, have atomic, consistency,
  64   isolation, durability (ACID) properties.  Each of these update
  65   operations act upon an entry.  However, It is often desirable to
  66   update two or more entries in a single unit of interaction, a
  67   transaction.  Transactions are necessary to support a number of
  68   applications including resource provisioning and information
  69   replication.  This document defines an LDAP extension to support
  70   transactions.
  71
  72
  73 1. Overview
  74
  75   This document extends the Lightweight Directory Access Protocol (LDAP)
  76   [Roadmap] to allow clients to group a number of related update
  77   operations [Protocol] and have them preformed as one unit of
  78   interaction, a transaction.  As with distinct update operations, each
  79   transaction has atomic, consistency, isolation, and durability
  80   ([ACID]) properties.
  81
  82   This extension consists of two extended operations, one control, and
  83   one unsolicited notification message.  The Start Transaction operation
  84   is used to obtain a transaction identifier.  This identifier is then
  85   attached to multiple update operations to indicate that they belong to
  86   transaction using the Transaction Specification control.  The End
  87   Transaction is used to settle (commit or abort) the transaction.  The
  88   Aborted Tranaction Notice is used notify the client the server is no
  89   longer willing or able to process an outstanding transaction.
  90
  91
  92 1.1. Conventions and Terminology
  93
  94   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  95   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
  96   document are to be interpreted as described in BCP 14 [RFC2119].
  97
  98   Protocol elements are described using ASN.1 [X.680] with implicit
  99   tags.  The term "BER-encoded" means the element is to be encoded using
 100   the Basic Encoding Rules [X.690] under the restrictions detailed in
 101   Section 5.2 of [Protocol].
 102
 103   DSA stands for "Directory System Agent" (a server).  DSE stands for
 104   "DSA-specific entry".
 105
 106
 107 2.  Elements of an LDAP Transaction
 108
 109 2.1.  Start Transaction Request and Response
 110
 111
 112
 113
 114 Zeilenga                    LDAP Transactions                   [Page 2]
 115 \f
 116 INTERNET-DRAFT         draft-zeilenga-ldap-txn-07           5 March 2006
 117
 118
 119   A Start Transaction Request is an LDAPMessage of CHOICE extendedReq
 120   where the requestName is IANA-ASSIGNED-OID.1 and the requestValue is
 121   absent.
 122
 123   A Start Transaction Response is an LDAPMessage of CHOICE extendedRes
 124   sent in response to a Start Transaction Request.  Its responesName is
 125   absent.  When the resultCode is success, responseValue is present and
 126   contains a transaction identifier.  Otherwise, the responseValue is
 127   absent.
 128
 129
 130 2.2.  Transaction Specification Control
 131
 132   A Transaction Specification Control is an LDAPControl where the
 133   controlType is IANA-ASSIGNED-OID.2, the criticality is TRUE, and the
 134   controlValue is a transaction identifer.  The control is appropriate
 135   for update requests including Add, Delete, Modify, and ModifyDN
 136   requests [Protocol].
 137
 138 2.3.  End Transactions Request and Response
 139
 140   An End Transaction Request is an LDAPMessage of CHOICE extendedReq
 141   where the requestName is IANA-ASSIGNED-OID.3 and the requestValue is
 142   present and contains a BER-encoded settlementValue.
 143
 144        settlementValue ::= SEQUENCE {
 145             commit         BOOLEAN DEFAULT TRUE,
 146             identifier     OCTET STRING }
 147
 148   A commit value of TRUE indicates a request to commit the transaction
 149   identified by the identifier.  A commit value of FALSE indicates a
 150   request to abort the identified transaction.
 151
 152   An End Transaction Response is an LDAPMessage sent in response to a
 153   End Transaction Request.  Its response name is absent.  The
 154   responseValue when present contains a BER-encoded MessageID.
 155
 156
 157 2.5. Aborted Transaction Notice
 158
 159   The Aborted Transaction Notice is an Unsolicited Notification message
 160   where the responseName is IANA-ASSIGNED-OID.4 and responseValue is
 161   present and contains a transaction identifier.
 162
 163
 164 3. An LDAP Transaction
 165
 166 3.1. Extension Discovery
 167
 168
 169
 170 Zeilenga                    LDAP Transactions                   [Page 3]
 171 \f
 172 INTERNET-DRAFT         draft-zeilenga-ldap-txn-07           5 March 2006
 173
 174
 175   To allow clients to discover support for this extension, servers
 176   implementing this specification SHOULD publish IANA-ASSIGNED-OID.1 and
 177   IANA-ASSIGNED-OID.3 as values of the 'supportedExtension' attribute
 178   [Models] within the Root DSE, and publish the IANA-ASSIGNED-OID.2 as a
 179   value of the 'supportedControl' attribute [Models] of the Root DSE.
 180
 181   A server MAY choose to advertise this extension only when the client
 182   is authorized to use it.
 183
 184
 185 3.2. Starting an Transactions
 186
 187   A client wishing to preform a sequence of directory updates as an
 188   transaction issues a Start Transaction Request.  A server which is
 189   willing and able to support transactions responds to this request with
 190   a Start Transaction Response providing a transaction identifier and
 191   with a resultCode of success.  Otherwise, the server responds with a
 192   Start Transaction Response wth a result code other than success
 193   indicating the nature of the failure.
 194
 195   The transaction identifier provided upon successful start of a
 196   transaction is used in subseqent protocol messages to identify this
 197   transaction.
 198
 199
 200 3.3. Specification of a Transaction
 201
 202   The client then may issue may issue one or more update (add, delete,
 203   modify, modifyDN) requests, each with a Transaction Specification
 204   control containing the transaction identifier indicating the updates
 205   are to processed as part of the transaction.  Each of these update
 206   request MUST have a different MessageId value.  If the server is
 207   unwilling or unable to attempt to process the requested update
 208   operation as part of the transaction, the server immediately returns
 209   the approrpiate response to the request with a resultCode indicating
 210   the nature of the failure.  Otherwise, the server immediately returns
 211   success and the defers further processing of the operation is then
 212   deferred until settlement.
 213
 214   If the server becomes unwilling or unable to continue the
 215   specification of a transaction, the server issues an Aborted
 216   Transaction Notice with a non-success resultCode indicating the nature
 217   of the failure.  All operations that were to be processed as part of
 218   the transaction are implicitly abandoned.  Upon receipt of an Aborted
 219   Transaction Notice, the client is to discontinue all use of the
 220   transaction identifier as the transaction is null and void.  Any
 221   future use of identifier by the client will result in a response
 222   containing a non-success resultCode.
 223
 224
 225
 226 Zeilenga                    LDAP Transactions                   [Page 4]
 227 \f
 228 INTERNET-DRAFT         draft-zeilenga-ldap-txn-07           5 March 2006
 229
 230
 231 3.4. Transaction Settlement
 232
 233   A client requests settlement of transaction by issuing an End
 234   Transaction request for the transaction indicating whether it desires
 235   the transaction to be committed or aborted.
 236
 237   Upon receipt of a request to abort the transaction, the server is to
 238   abort the identified transaction (abandoning all operations which are
 239   part of the transaction) and indicate that it has done so by returning
 240   an End Transaction response with a resultCode of success.
 241
 242   Upon receipt of a request to commit the transaction, the server
 243   processes all update operations of the transaction as one atomic,
 244   isolated action with each requested update being processed in turn.
 245   Either all of the requested updates are to be successfully applied or
 246   none of the requested are to be applied.  The server returns an End
 247   Transaction Response with a resultCode of success and no responseValue
 248   to indicate all the requested updates were applied.  Otherwise, the
 249   server returns an End Transaction with an non-success resultCode
 250   indicating the nature of the failure.  If the failure is associated
 251   with a particular update request, a responseValue containing its
 252   MessageID is returned.  If the failure was not associated with any
 253   particular update request, no responseValue is returned.
 254
 255   There is no requirement that a server serialize transactions, or
 256   updates requested outside of a transaction.  That is, a server MAY
 257   process multiple commit requests (from one or more clients) acting
 258   upon different sets of entries concurrently.   A server MUST avoid
 259   deadlock.
 260
 261
 262 4. Distributed Directory Considerations
 263
 264   The LDAP/X.500 models provide for distributed directory operations
 265   including server-side chaining and client-side chasing of operations.
 266
 267   This document does not preclude servers from chaining operations which
 268   are part of a transaction.  However, if a server does allow such
 269   chaining, it MUST ensure that transaction semantics are provided.
 270
 271   This mechanism defined by this document does not support client-side
 272   chasing.  Grouping cookies used to identify the transaction are
 273   specific to a particular client/server session.
 274
 275   The LDAP/X.500 models provide for a single-master/multiple-shadow
 276   replication architecture.  This document states no requirement that
 277   changes made to the directory based upon processing a transaction be
 278   replicated as one atomic action.  That is, the client SHOULD NOT
 279
 280
 281
 282 Zeilenga                    LDAP Transactions                   [Page 5]
 283 \f
 284 INTERNET-DRAFT         draft-zeilenga-ldap-txn-07           5 March 2006
 285
 286
 287   assume tight data consistency nor fast data convergence at shadow
 288   servers unless they have prior knowledge that such service is
 289   provided.  Though this mechanism could be used to support replication,
 290   use in replication is not described in this document.
 291
 292   The LDAP/X.500 models do not currently support a multi-master
 293   replication architecture and, hence, not considered by this
 294   specification.
 295
 296
 297 5. Security Considerations
 298
 299   Transactions mechanisms may be the target of denial of service
 300   attacks.  Implementors should provide safeguards to ensure these
 301   mechanisms are not abused.
 302
 303   General security considerations [Roadmap], especially associated with
 304   update operations [Protocol], apply to this extension.
 305
 306
 307 6. IANA Considerations
 308
 309   In accordance with [BCP64bis], it is requested that Internet Assigned
 310   Numbers Authority (IANA) make the following assignments.
 311
 312
 313 6.1.  Object Identifier
 314
 315   Assignment of an LDAP Object Identifier to identify the protocol
 316   elements specified in this document this document is requested.
 317
 318       Subject: Request for LDAP Object Identifier Registration
 319       Person & email address to contact for further information:
 320           Kurt Zeilenga <kurt@OpenLDAP.org>
 321       Specification: RFC XXXX
 322       Author/Change Controller: IESG
 323       Comments: Identifies protocol elements for LDAP Transactions
 324
 325
 326 6.2.  LDAP Protocol Mechanism
 327
 328   Registration of the protocol mechanisms specified in this document is
 329   requested.
 330
 331   Subject: Request for LDAP Protocol Mechanism Registration
 332   Object Identifier: see table
 333   Description: see table
 334   Person & email address to contact for further information:
 335
 336
 337
 338 Zeilenga                    LDAP Transactions                   [Page 6]
 339 \f
 340 INTERNET-DRAFT         draft-zeilenga-ldap-txn-07           5 March 2006
 341
 342
 343        Kurt Zeilenga <kurt@openldap.org>
 344   Specification: RFC XXXX
 345   Author/Change Controller: IESG
 346   Comments:
 347
 348   Object Identifier   Type  Description
 349   ------------------- ----  -----------------------------------------
 350   IANA-ASSIGNED-OID.1 E     Start Transaction Extended Request
 351   IANA-ASSIGNED-OID.2 C     Transaction Specification Control
 352   IANA-ASSIGNED-OID.3 E     End Transaction Extended Request
 353
 354
 355 7. Acknowledgments
 356
 357   The author gratefully acknowledges the contributions made by members
 358   of the Internet Engineering Task Force.
 359
 360
 361 8. Author's Address
 362
 363   Kurt D. Zeilenga
 364   OpenLDAP Foundation
 365
 366   Email: Kurt@OpenLDAP.org
 367
 368
 369 9. References
 370
 371   [[Note to the RFC Editor: please replace the citation tags used in
 372   referencing Internet-Drafts with tags of the form RFCnnnn where
 373   possible.]]
 374
 375
 376 9.1. Normative References
 377
 378   [RFC2119]     Bradner, S., "Key words for use in RFCs to Indicate
 379                 Requirement Levels", BCP 14 (also RFC 2119), March 1997.
 380
 381   [Roadmap]     Zeilenga, K. (editor), "LDAP: Technical Specification
 382                 Road Map", draft-ietf-ldapbis-roadmap-xx.txt, a work in
 383                 progress.
 384
 385   [Protocol]    Sermersheim, J. (editor), "LDAP: The Protocol",
 386                 draft-ietf-ldapbis-protocol-xx.txt, a work in progress.
 387
 388   [Models]      Zeilenga, K. (editor), "LDAP: Directory Information
 389                 Models", draft-ietf-ldapbis-models-xx.txt, a work in
 390                 progress.
 391
 392
 393
 394 Zeilenga                    LDAP Transactions                   [Page 7]
 395 \f
 396 INTERNET-DRAFT         draft-zeilenga-ldap-txn-07           5 March 2006
 397
 398
 399   [X.680]       International Telecommunication Union -
 400                 Telecommunication Standardization Sector, "Abstract
 401                 Syntax Notation One (ASN.1) - Specification of Basic
 402                 Notation", X.680(2002) (also ISO/IEC 8824-1:2002).
 403
 404   [X.690]       International Telecommunication Union -
 405                 Telecommunication Standardization Sector, "Specification
 406                 of ASN.1 encoding rules: Basic Encoding Rules (BER),
 407                 Canonical Encoding Rules (CER), and Distinguished
 408                 Encoding Rules (DER)", X.690(2002) (also ISO/IEC
 409                 8825-1:2002).
 410
 411
 412 9.2. Informative References
 413
 414   [ACID]        Section 4 of ISO/IEC 10026-1:1992.
 415
 416   [BCP64bis]    Zeilenga, K., "IANA Considerations for LDAP",
 417                 draft-ietf-ldapbis-bcp64-xx.txt, a work in progress.
 418
 419   [X.500]       International Telecommunication Union -
 420                 Telecommunication Standardization Sector, "The Directory
 421                 -- Overview of concepts, models and services,"
 422                 X.500(1993) (also ISO/IEC 9594-1:1994).
 423
 424   [X.501]       International Telecommunication Union -
 425                 Telecommunication Standardization Sector, "The Directory
 426                 -- Models," X.501(1993) (also ISO/IEC 9594-2:1994).
 427
 428
 429
 430 Intellectual Property Rights
 431
 432   The IETF takes no position regarding the validity or scope of any
 433   Intellectual Property Rights or other rights that might be claimed to
 434   pertain to the implementation or use of the technology described in
 435   this document or the extent to which any license under such rights
 436   might or might not be available; nor does it represent that it has
 437   made any independent effort to identify any such rights.  Information
 438   on the procedures with respect to rights in RFC documents can be found
 439   in BCP 78 and BCP 79.
 440
 441   Copies of IPR disclosures made to the IETF Secretariat and any
 442   assurances of licenses to be made available, or the result of an
 443   attempt made to obtain a general license or permission for the use of
 444   such proprietary rights by implementers or users of this specification
 445   can be obtained from the IETF on-line IPR repository at
 446   http://www.ietf.org/ipr.
 447
 448
 449
 450 Zeilenga                    LDAP Transactions                   [Page 8]
 451 \f
 452 INTERNET-DRAFT         draft-zeilenga-ldap-txn-07           5 March 2006
 453
 454
 455   The IETF invites any interested party to bring to its attention any
 456   copyrights, patents or patent applications, or other proprietary
 457   rights that may cover technology that may be required to implement
 458   this standard.  Please address the information to the IETF at
 459   ietf-ipr@ietf.org.
 460
 461
 462
 463 Full Copyright
 464
 465   Copyright (C) The Internet Society (2006).
 466
 467   This document is subject to the rights, licenses and restrictions
 468   contained in BCP 78, and except as set forth therein, the authors
 469   retain all their rights.
 470
 471   This document and the information contained herein are provided on an
 472   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
 473   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
 474   ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
 475   INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
 476   INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
 477   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
 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 Zeilenga                    LDAP Transactions                   [Page 9]
 507 \f