1 2 3 4 5 6 7Independent Submission K. Zeilenga 8Request for Comments: 5805 Isode Limited 9Category: Experimental March 2010 10ISSN: 2070-1721 11 12 13 Lightweight Directory Access Protocol (LDAP) Transactions 14 15Abstract 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 26Status 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 44Copyright 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 58Zeilenga Experimental [Page 1] 59 60RFC 5805 LDAP Transactions March 2010 61 62 631. 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 821.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 962. Elements of an LDAP Transaction 97 982.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 114Zeilenga Experimental [Page 2] 115 116RFC 5805 LDAP Transactions March 2010 117 118 1192.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 1322.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 170Zeilenga Experimental [Page 3] 171 172RFC 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 1882.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 1943. An LDAP Transaction 195 1963.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 2073.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 226Zeilenga Experimental [Page 4] 227 228RFC 5805 LDAP Transactions March 2010 229 230 2313.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 2553.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 282Zeilenga Experimental [Page 5] 283 284RFC 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 2983.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 3114. 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 3204.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 3294.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 338Zeilenga Experimental [Page 6] 339 340RFC 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 3464.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 3654.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 3795. 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 394Zeilenga Experimental [Page 7] 395 396RFC 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 4096. 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 4187. IANA Considerations 419 420 The Internet Assigned Numbers Authority (IANA) has made the following 421 assignments. 422 4237.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 450Zeilenga Experimental [Page 8] 451 452RFC 5805 LDAP Transactions March 2010 453 454 4557.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 4828. Acknowledgments 483 484 The author gratefully acknowledges the contributions made by Internet 485 Engineering Task Force participants. 486 4879. References 488 4899.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 506Zeilenga Experimental [Page 9] 507 508RFC 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 5449.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 562Zeilenga Experimental [Page 10] 563 564RFC 5805 LDAP Transactions March 2010 565 566 567Author'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 618Zeilenga Experimental [Page 11] 619 620