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