git.sur5r.net Git - openldap/blob - doc/rfc/rfc5805.txt

   1
   2
   3
   4
   5
   6
   7 Independent Submission                                       K. Zeilenga
   8 Request for Comments: 5805                                 Isode Limited
   9 Category: Experimental                                        March 2010
  10 ISSN: 2070-1721
  11
  12
  13        Lightweight Directory Access Protocol (LDAP) Transactions
  14
  15 Abstract
  16
  17    Lightweight Directory Access Protocol (LDAP) update operations, such
  18    as Add, Delete, and Modify operations, have atomic, consistency,
  19    isolation, durability (ACID) properties.  Each of these update
  20    operations act upon an entry.  It is often desirable to update two or
  21    more entries in a single unit of interaction, a transaction.
  22    Transactions are necessary to support a number of applications
  23    including resource provisioning.  This document extends LDAP to
  24    support transactions.
  25
  26 Status of This Memo
  27
  28    This document is not an Internet Standards Track specification; it is
  29    published for examination, experimental implementation, and
  30    evaluation.
  31
  32    This document defines an Experimental Protocol for the Internet
  33    community.  This is a contribution to the RFC Series, independently
  34    of any other RFC stream.  The RFC Editor has chosen to publish this
  35    document at its discretion and makes no statement about its value for
  36    implementation or deployment.  Documents approved for publication by
  37    the RFC Editor are not a candidate for any level of Internet
  38    Standard; see Section 2 of RFC 5741.
  39
  40    Information about the current status of this document, any errata,
  41    and how to provide feedback on it may be obtained at
  42    http://www.rfc-editor.org/info/rfc5805.
  43
  44 Copyright Notice
  45
  46    Copyright (c) 2010 IETF Trust and the persons identified as the
  47    document authors.  All rights reserved.
  48
  49    This document is subject to BCP 78 and the IETF Trust's Legal
  50    Provisions Relating to IETF Documents
  51    (http://trustee.ietf.org/license-info) in effect on the date of
  52    publication of this document.  Please review these documents
  53    carefully, as they describe your rights and restrictions with respect
  54    to this document.
  55
  56
  57
  58 Zeilenga                      Experimental                      [Page 1]
  59 \f
  60 RFC 5805                    LDAP Transactions                 March 2010
  61
  62
  63 1.  Overview
  64
  65    This document extends the Lightweight Directory Access Protocol
  66    (LDAP) [RFC4510] to allow clients to relate a number of update
  67    operations [RFC4511] and have them performed as one unit of
  68    interaction, a transaction.  As with distinct update operations, each
  69    transaction has atomic, consistency, isolation, and durability (ACID)
  70    properties [ACID].
  71
  72    This extension consists of two extended operations, one control, and
  73    one unsolicited notification message.  The Start Transaction
  74    operation is used to obtain a transaction identifier.  This
  75    identifier is then attached to multiple update operations to indicate
  76    that they belong to the transaction using the Transaction
  77    Specification control.  The End Transaction is used to settle (commit
  78    or abort) the transaction.  The Aborted Transaction Notice is
  79    provided by the server to notify the client that the server is no
  80    longer willing or able to process an outstanding transaction.
  81
  82 1.1.  Conventions and Terminology
  83
  84    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  85    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
  86    document are to be interpreted as described in RFC 2119 [RFC2119].
  87
  88    Protocol elements are described using ASN.1 [X.680] with implicit
  89    tags.  The term "BER-encoded" means the element is to be encoded
  90    using the Basic Encoding Rules [X.690] under the restrictions
  91    detailed in Section 5.1 of [RFC4511].
  92
  93    DSA stands for "Directory System Agent" (a server).  DSE stands for
  94    "DSA-specific entry".
  95
  96 2.  Elements of an LDAP Transaction
  97
  98 2.1.  Start Transaction Request and Response
  99
 100    A Start Transaction Request is an LDAPMessage of CHOICE extendedReq
 101    where the requestName is 1.3.6.1.1.21.1 and the requestValue is
 102    absent.
 103
 104    A Start Transaction Response is an LDAPMessage of CHOICE extendedRes
 105    sent in response to a Start Transaction Request.  Its responseName is
 106    absent.  When the resultCode is success (0), responseValue is present
 107    and contains a transaction identifier.  Otherwise, the responseValue
 108    is absent.
 109
 110
 111
 112
 113
 114 Zeilenga                      Experimental                      [Page 2]
 115 \f
 116 RFC 5805                    LDAP Transactions                 March 2010
 117
 118
 119 2.2.  Transaction Specification Control
 120
 121    A Transaction Specification Control is an LDAPControl where the
 122    controlType is 1.3.6.1.1.21.2, the criticality is TRUE, and the
 123    controlValue is a transaction identifier.  The control is appropriate
 124    for update requests including Add, Delete, Modify, and ModifyDN
 125    (Rename) requests [RFC4511], as well as the Password Modify requests
 126    [RFC3062].
 127
 128    As discussed in Section 4, the Transaction Specification control can
 129    be used in conjunction with request controls appropriate for the
 130    update request.
 131
 132 2.3.  End Transactions Request and Response
 133
 134    An End Transaction Request is an LDAPMessage of CHOICE extendedReq
 135    where the requestName is 1.3.6.1.1.21.3 and the requestValue is
 136    present and contains a BER-encoded txnEndReq.
 137
 138       txnEndReq ::= SEQUENCE {
 139            commit         BOOLEAN DEFAULT TRUE,
 140            identifier     OCTET STRING }
 141
 142    A commit value of TRUE indicates a request to commit the transaction
 143    identified by the identifier.  A commit value of FALSE indicates a
 144    request to abort the identified transaction.
 145
 146    An End Transaction Response is an LDAPMessage sent in response to a
 147    End Transaction Request.  Its response name is absent.  The
 148    responseValue when present contains a BER-encoded txnEndRes.
 149
 150       txnEndRes ::= SEQUENCE {
 151            messageID MessageID OPTIONAL,
 152                 -- msgid associated with non-success resultCode
 153            updatesControls SEQUENCE OF updateControls SEQUENCE {
 154                 messageID MessageID,
 155                      -- msgid associated with controls
 156                 controls  Controls
 157            } OPTIONAL
 158       }
 159       -- where MessageID and Controls are as specified in RFC 4511
 160
 161    The txnEndRes.messageID provides the message id of the update request
 162    associated with a non-success response.  txnEndRes.messageID is
 163    absent when resultCode of the End Transaction Response is success
 164    (0).
 165
 166
 167
 168
 169
 170 Zeilenga                      Experimental                      [Page 3]
 171 \f
 172 RFC 5805                    LDAP Transactions                 March 2010
 173
 174
 175    The txnEndRes.updatesControls provides a facility for returning
 176    response controls that normally (i.e., in the absence of
 177    transactions) would be returned in an update response.  The
 178    updateControls.messageID provides the message id of the update
 179    request associated with the response controls provided in
 180    updateControls.controls.
 181
 182    The txnEndRes.updatesControls is absent when there are no update
 183    response controls to return.
 184
 185    If both txnEndRes.messageID and txnEndRes.updatesControl are absent,
 186    the responseValue of the End Transaction Response is absent.
 187
 188 2.4.  Aborted Transaction Notice
 189
 190    The Aborted Transaction Notice is an Unsolicited Notification message
 191    where the responseName is 1.3.6.1.1.21.4 and responseValue is present
 192    and contains a transaction identifier.
 193
 194 3.  An LDAP Transaction
 195
 196 3.1.  Extension Discovery
 197
 198    To allow clients to discover support for this extension, servers
 199    implementing this specification SHOULD publish 1.3.6.1.1.21.1 and
 200    1.3.6.1.1.21.3 as values of the 'supportedExtension' attribute
 201    [RFC4512] within the Root DSE, and publish the 1.3.6.1.1.21.2 as a
 202    value of the 'supportedControl' attribute [RFC4512] of the Root DSE.
 203
 204    A server MAY choose to advertise this extension only when the client
 205    is authorized to use it.
 206
 207 3.2.  Starting a Transaction
 208
 209    A client wishing to perform a sequence of directory updates as a
 210    transaction issues a Start Transaction Request.  A server that is
 211    willing and able to support transactions responds to this request
 212    with a Start Transaction Response providing a transaction identifier
 213    and with a resultCode of success (0).  Otherwise, the server responds
 214    with a Start Transaction Response with a resultCode other than
 215    success indicating the nature of the failure.
 216
 217    The transaction identifier provided upon successful start of a
 218    transaction is used in subsequent protocol messages to identify this
 219    transaction.
 220
 221
 222
 223
 224
 225
 226 Zeilenga                      Experimental                      [Page 4]
 227 \f
 228 RFC 5805                    LDAP Transactions                 March 2010
 229
 230
 231 3.3.  Specification of a Transaction
 232
 233    The client then can issue one or more update requests, each with a
 234    Transaction Specification control containing the transaction
 235    identifier indicating the updates are to be processed as part of the
 236    transaction.  Each of these update requests MUST have a different
 237    MessageID value.  If the server is unwilling or unable to attempt to
 238    process the requested update operation as part of the transaction,
 239    the server immediately returns the appropriate response to the
 240    request with a resultCode indicating the nature of the failure.
 241    Otherwise, the server immediately returns a resultCode of success (0)
 242    and the defers further processing of the operation is then deferred
 243    until settlement.
 244
 245    If the server becomes unwilling or unable to continue the
 246    specification of a transaction, the server issues an Aborted
 247    Transaction Notice with a non-success resultCode indicating the
 248    nature of the failure.  All operations that were to be processed as
 249    part of the transaction are implicitly abandoned.  Upon receipt of an
 250    Aborted Transaction Notice, the client is to discontinue all use of
 251    the transaction identifier as the transaction is null and void.  Any
 252    future use of identifier by the client will result in a response
 253    containing a non-success resultCode.
 254
 255 3.4.  Transaction Settlement
 256
 257    A client requests settlement of transaction by issuing an End
 258    Transaction Request for the transaction indicating whether it desires
 259    the transaction to be committed or aborted.
 260
 261    Upon receipt of a request to abort the transaction, the server is to
 262    abort the identified transaction (abandoning all operations that are
 263    part of the transaction) and indicate that it has done so by
 264    returning an End Transaction Response with a resultCode of success
 265    (0).
 266
 267    Upon receipt of a request to commit the transaction, the server
 268    processes all update operations of the transaction as one atomic,
 269    durable, isolated, and consistent action with each requested update
 270    being processed in turn.  Either all of the requested updates are to
 271    be successfully applied or none of the requested are to be applied.
 272    The server returns an End Transaction Response with a resultCode of
 273    success (0) and no responseValue to indicate all the requested
 274    updates were applied.  Otherwise, the server returns an End
 275    Transaction Response with a non-success resultCode indicating the
 276    nature of the failure.  If the failure is associated with a
 277
 278
 279
 280
 281
 282 Zeilenga                      Experimental                      [Page 5]
 283 \f
 284 RFC 5805                    LDAP Transactions                 March 2010
 285
 286
 287    particular update request, the txnEndRes.messageID in the
 288    responseValue is the message id of this update request.  If the
 289    failure was not associated with any particular update request, no
 290    txnEnd.messageID is provided.
 291
 292    There is no requirement that a server serialize transactions or
 293    updates requested outside of a transaction.  That is, a server MAY
 294    process multiple commit requests (from one or more clients) acting
 295    upon different sets of entries concurrently.  A server MUST avoid
 296    deadlock.
 297
 298 3.5.  Miscellaneous Issues
 299
 300    Transactions cannot be nested.
 301
 302    Each LDAP transaction should be initiated, specified, and settled
 303    within a stable security context.  Between the Start Request and the
 304    End Response, the peers SHOULD avoid negotiating new security
 305    associations and/or layers.
 306
 307    Upon receipt of a Bind or Unbind request, the server SHALL abort any
 308    and all outstanding transactions without notice and nullify their
 309    identifiers.
 310
 311 4.  Interaction with Other Extensions
 312
 313    The LDAP Transaction extension may be used with many but not all LDAP
 314    control extensions designed to extend update (and possibly other)
 315    operations.  The subsections that follow discuss interaction with a
 316    number of control extensions.  Interaction with other control
 317    extensions may be discussed in other documents, in particular in
 318    control extension specifications.
 319
 320 4.1.  Assertion Control
 321
 322    The Assertion [RFC4528] control is appropriate for use with update
 323    requests specified as part of a transaction.  The evaluation of the
 324    assertion is performed as part of the transaction.
 325
 326    The Assertion control is inappropriate for use with either the Start
 327    or End Transaction Extended operations.
 328
 329 4.2.  ManageDsaIT Control
 330
 331    The ManageDsaIT [RFC3296] control is appropriate for use with update
 332    requests specified as part of a transaction.
 333
 334
 335
 336
 337
 338 Zeilenga                      Experimental                      [Page 6]
 339 \f
 340 RFC 5805                    LDAP Transactions                 March 2010
 341
 342
 343    The ManageDsaIT control is inappropriate for use with either the
 344    Start or End Transaction Extended operations.
 345
 346 4.4.  Proxied Authorization Control
 347
 348    The Proxied Authorization [RFC4370] control is appropriate for use
 349    with the Start Transaction Extended operation, but not the End
 350    Transaction Extended operation or any update request specified as
 351    part of a transaction.
 352
 353    To request that a transaction be performed under a different
 354    authorization, the client provides a Proxied Authorization control
 355    with the Transaction Start Request.  If the client is not authorized
 356    to assume the requested authorization identity, the server is to
 357    return the authorizationDenied (123) resultCode in its response.
 358    Otherwise, further processing of the request and transaction is
 359    performed under the requested authorization identity.
 360
 361    Any proxied authorization request attached to an update request
 362    specified as part of a transaction, or attached to a Transaction End
 363    Request, is to be regarded as a protocol error.
 364
 365 4.5.  Read Entry Controls
 366
 367    The Pre- and Post-Read Entry [RFC4527] request control are
 368    appropriate for use with update requests specified as part of a
 369    transaction.
 370
 371    The response control produced in response to a Pre- or Post-Read
 372    Entry request control is returned in the txnEndRes.updatesControls
 373    field of responseValue of the End Transaction Response.
 374
 375    The Pre- and Post-Read Entry controls are inappropriate for use in
 376    the LDAPMessage.controls field of the Transaction Start and End
 377    Request and Response messages.
 378
 379 5.  Distributed Directory Considerations
 380
 381    The LDAP/X.500 models provide for distributed directory operations,
 382    including server-side chaining and client-side chasing of referrals.
 383
 384    This document does not preclude servers from chaining operations that
 385    are part of a transaction.  However, if a server does attempt such
 386    chaining, it MUST ensure that transaction semantics are provided.
 387
 388    The mechanism defined by this document does not support client-side
 389    chasing.  Transaction identifiers are specific to a particular LDAP
 390    association (as established via the LDAP Bind operation).
 391
 392
 393
 394 Zeilenga                      Experimental                      [Page 7]
 395 \f
 396 RFC 5805                    LDAP Transactions                 March 2010
 397
 398
 399    The LDAP/X.500 models provide for a single-master/multiple-shadow
 400    replication architecture.  There is no requirement that changes made
 401    to the directory based upon processing a transaction be replicated as
 402    one atomic action.  Hence, clients SHOULD NOT assume tight data
 403    consistency nor fast data convergence of shadow copies unless they
 404    have prior knowledge that these properties are provided.  Note that
 405    DontUseCopy control [DONTUSECOPY] may be used in conjunction with the
 406    LDAP search request to ask for the return of the authoritative copy
 407    of the entry.
 408
 409 6.  Security Considerations
 410
 411    Transaction mechanisms may be the target of denial-of-service
 412    attacks, especially where implementations lock shared resources for
 413    the duration of a transaction.
 414
 415    General security considerations [RFC4510], especially those
 416    associated with update operations [RFC4511], apply to this extension.
 417
 418 7.  IANA Considerations
 419
 420    The Internet Assigned Numbers Authority (IANA) has made the following
 421    assignments.
 422
 423 7.1.  Object Identifier
 424
 425    IANA has assigned an LDAP Object Identifier (21) [RFC4520] to
 426    identify the protocol elements specified in this document.
 427
 428       Subject: Request for LDAP Object Identifier Registration
 429       Person & email address to contact for further information:
 430           Kurt Zeilenga <Kurt.Zeilenga@Isode.COM>
 431       Specification: RFC 5805
 432       Author/Change Controller: Kurt Zeilenga <Kurt.Zeilenga@Isode.COM>
 433       Comments: Identifies protocol elements for LDAP Transactions
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450 Zeilenga                      Experimental                      [Page 8]
 451 \f
 452 RFC 5805                    LDAP Transactions                 March 2010
 453
 454
 455 7.2.  LDAP Protocol Mechanism
 456
 457    IANA has registered the protocol mechanisms [RFC4520] specified in
 458    this document.
 459
 460       Subject: Request for LDAP Protocol Mechanism Registration
 461       Object Identifier: see table
 462       Description: see table
 463       Person & email address to contact for further information:
 464           Kurt Zeilenga <Kurt.Zeilenga@Isode.COM>
 465       Specification: RFC 5805
 466       Author/Change Controller: Kurt Zeilenga <Kurt.Zeilenga@Isode.COM>
 467       Comments:
 468
 469       Object Identifier   Type  Description
 470       ------------------- ----  ----------------------------------
 471       1.3.6.1.1.21.1      E     Start Transaction Extended Request
 472       1.3.6.1.1.21.2      C     Transaction Specification Control
 473       1.3.6.1.1.21.3      E     End Transaction Extended Request
 474       1.3.6.1.1.21.4      N     Aborted Transaction Notice
 475
 476       Legend
 477       ------------------------
 478       C => supportedControl
 479       E => supportedExtension
 480       N => Unsolicited Notice
 481
 482 8.  Acknowledgments
 483
 484    The author gratefully acknowledges the contributions made by Internet
 485    Engineering Task Force participants.
 486
 487 9.  References
 488
 489 9.1.  Normative References
 490
 491    [RFC2119]     Bradner, S., "Key words for use in RFCs to Indicate
 492                  Requirement Levels", BCP 14, RFC 2119, March 1997.
 493
 494    [RFC3062]     Zeilenga, K., "LDAP Password Modify Extended
 495                  Operation", RFC 3062, February 2001.
 496
 497    [RFC3296]     Zeilenga, K., "Named Subordinate References in
 498                  Lightweight Directory Access Protocol (LDAP)
 499                  Directories", RFC 3296, July 2002.
 500
 501
 502
 503
 504
 505
 506 Zeilenga                      Experimental                      [Page 9]
 507 \f
 508 RFC 5805                    LDAP Transactions                 March 2010
 509
 510
 511    [RFC4370]     Weltman, R., "Lightweight Directory Access Protocol
 512                  (LDAP) Proxied Authorization Control", RFC 4370,
 513                  February 2006.
 514
 515    [RFC4510]     Zeilenga, K., Ed., "Lightweight Directory Access
 516                  Protocol (LDAP): Technical Specification Road Map", RFC
 517                  4510, June 2006.
 518
 519    [RFC4511]     Sermersheim, J., Ed., "Lightweight Directory Access
 520                  Protocol (LDAP): The Protocol", RFC 4511, June 2006.
 521
 522    [RFC4512]     Zeilenga, K., Ed., "Lightweight Directory Access
 523                  Protocol (LDAP): Directory Information Models", RFC
 524                  4512, June 2006.
 525
 526    [RFC4527]     Zeilenga, K., "Lightweight Directory Access Protocol
 527                  (LDAP) Read Entry Controls", RFC 4527, June 2006.
 528
 529    [RFC4528]     Zeilenga, K., "Lightweight Directory Access Protocol
 530                  (LDAP) Assertion Control", RFC 4528, June 2006.
 531
 532    [X.680]       International Telecommunication Union -
 533                  Telecommunication Standardization Sector, "Abstract
 534                  Syntax Notation One (ASN.1) - Specification of Basic
 535                  Notation", X.680(2002) (also ISO/IEC 8824-1:2002).
 536
 537    [X.690]       International Telecommunication Union -
 538                  Telecommunication Standardization Sector,
 539                  "Specification of ASN.1 encoding rules: Basic Encoding
 540                  Rules (BER), Canonical Encoding Rules (CER), and
 541                  Distinguished Encoding Rules (DER)", X.690(2002) (also
 542                  ISO/IEC 8825-1:2002).
 543
 544 9.2.  Informative References
 545
 546    [RFC4520]     Zeilenga, K., "Internet Assigned Numbers Authority
 547                  (IANA) Considerations for the Lightweight Directory
 548                  Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006.
 549
 550    [ACID]        "Information technology -- Open Systems Interconnection
 551                  -- Distributed Transaction Processing -- Part 1: OSI TP
 552                  Model", Section 4, ISO/IEC 10026-1:1992.
 553
 554    [DONTUSECOPY] Zeilenga, K., "The LDAP Don't Use Copy Control", Work
 555                  in Progress, December 2009.
 556
 557
 558
 559
 560
 561
 562 Zeilenga                      Experimental                     [Page 10]
 563 \f
 564 RFC 5805                    LDAP Transactions                 March 2010
 565
 566
 567 Author's Address
 568
 569    Kurt D. Zeilenga
 570    Isode Limited
 571
 572    EMail: Kurt.Zeilenga@Isode.COM
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618 Zeilenga                      Experimental                     [Page 11]
 619 \f