idnits 2.17.1 draft-zeilenga-ldap-txn-15.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (17 December 2008) is 5606 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- -- No information found for draft-zeilenga-ldap-dontusecopy-xx - is the name correct? Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT Kurt D. Zeilenga 3 Intended Category: Experimental Isode Limited 4 Expires in six months 17 December 2008 6 LDAP Transactions 7 9 Status of Memo 11 This document is intended to be, after appropriate review and 12 revision, submitted to the RFC Editor for publication as an 13 Experimental RFC. Distribution of this memo is unlimited. Technical 14 discussion of this document will take place on the IETF LDAP 15 Extensions mailing list . Please send editorial 16 comments directly to the author . 18 This Internet-Draft is submitted to IETF in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering Task 22 Force (IETF), its areas, and its working groups. Note that other 23 groups may also distribute working documents as Internet-Drafts. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference material 28 or to cite them other than as "work in progress." 30 The list of current Internet-Drafts can be accessed at 31 http://www.ietf.org/1id-abstracts.html. 33 The list of Internet-Draft Shadow Directories can be accessed at 34 http://www.ietf.org/shadow.html. 36 Copyright (c) 20008 IETF Trust and the persons identified as the 37 document authors. 39 Please see the Full Copyright section near the end of this document 40 for more information. 42 Abstract 44 Lightweight Directory Access Protocol (LDAP) update operations, such 45 as Add, Delete, and Modify operations, have atomic, consistency, 46 isolation, durability (ACID) properties. Each of these update 47 operations act upon an entry. It is often desirable to update two or 48 more entries in a single unit of interaction, a transaction. 49 Transactions are necessary to support a number of applications 50 including resource provisioning. This document extends LDAP to 51 support transactions. 53 1. Overview 55 This document extends the Lightweight Directory Access Protocol (LDAP) 56 [RFC4510] to allow clients to relate a number of update operations 57 [RFC4511] and have them performed as one unit of interaction, a 58 transaction. As with distinct update operations, each transaction has 59 atomic, consistency, isolation, and durability (ACID) properties 60 [ACID]. 62 This extension consists of two extended operations, one control, and 63 one unsolicited notification message. The Start Transaction operation 64 is used to obtain a transaction identifier. This identifier is then 65 attached to multiple update operations to indicate that they belong to 66 the transaction using the Transaction Specification control. The End 67 Transaction is used to settle (commit or abort) the transaction. The 68 Aborted Transaction Notice is provided by the server to notify the 69 client that the server is no longer willing or able to process an 70 outstanding transaction. 72 1.1. Conventions and Terminology 74 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 75 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 76 document are to be interpreted as described in RFC 2119 [RFC2119]. 78 Protocol elements are described using ASN.1 [X.680] with implicit 79 tags. The term "BER-encoded" means the element is to be encoded using 80 the Basic Encoding Rules [X.690] under the restrictions detailed in 81 Section 5.1 of [RFC4511]. 83 DSA stands for "Directory System Agent" (a server). DSE stands for 84 "DSA-specific entry". 86 2. Elements of an LDAP Transaction 87 2.1. Start Transaction Request and Response 89 A Start Transaction Request is an LDAPMessage of CHOICE extendedReq 90 where the requestName is IANA-ASSIGNED-OID.1 and the requestValue is 91 absent. 93 A Start Transaction Response is an LDAPMessage of CHOICE extendedRes 94 sent in response to a Start Transaction Request. Its responseName is 95 absent. When the resultCode is success (0), responseValue is present 96 and contains a transaction identifier. Otherwise, the responseValue 97 is absent. 99 2.2. Transaction Specification Control 101 A Transaction Specification control is an LDAPControl where the 102 controlType is IANA-ASSIGNED-OID.2, the criticality is TRUE, and the 103 controlValue is a transaction identifier. The control is appropriate 104 for update requests including Add, Delete, Modify, and ModifyDN 105 (Rename) requests [RFC4511], as well as the Password Modify requests 106 [RFC3062]. 108 As discussed in Section 4, the Transaction Specification control can 109 be used in conjunction with request controls appropriate for the 110 update request. 112 2.3. End Transactions Request and Response 114 An End Transaction Request is an LDAPMessage of CHOICE extendedReq 115 where the requestName is IANA-ASSIGNED-OID.3 and the requestValue is 116 present and contains a BER-encoded txnEndReq. 118 txnEndReq ::= SEQUENCE { 119 commit BOOLEAN DEFAULT TRUE, 120 identifier OCTET STRING } 122 A commit value of TRUE indicates a request to commit the transaction 123 identified by the identifier. A commit value of FALSE indicates a 124 request to abort the identified transaction. 126 An End Transaction Response is an LDAPMessage sent in response to a 127 End Transaction Request. Its response name is absent. The 128 responseValue when present contains a BER-encoded txnEndRes. 130 txnEndRes ::= SEQUENCE { 131 messageID MessageID OPTIONAL, 132 -- msgid associated with non-success resultCode 134 updatesControls SEQUENCE OF updateControls SEQUENCE { 135 messageID MessageID, 136 -- msgid associated with controls 137 controls Controls 138 } OPTIONAL 139 } 140 -- where MessageID and Controls are as specified in RFC 4511 142 The txnEndRes.messageID provides the message id of the update request 143 associated with a non-success response. txnEndRes.messageID is absent 144 when resultCode of the End Transaction Response is success (0). 146 The txnEndRes.updatesControls provides a facility for returning 147 response controls that normally (i.e., in absence of transactions) 148 would be returned in an update response. The updateControls.messageID 149 provides the message id of the update request associated with the 150 response controls provided in updateControls.controls. 152 The txnEndRes.updatesControls is absent when there are no update 153 response controls to return. 155 If both txnEndRes.messageID and txnEndRes.updatesControl are absent, 156 the responseValue of the End Transaction Response is absent. 158 2.4. Aborted Transaction Notice 160 The Aborted Transaction Notice is an Unsolicited Notification message 161 where the responseName is IANA-ASSIGNED-OID.4 and responseValue is 162 present and contains a transaction identifier. 164 3. An LDAP Transaction 166 3.1. Extension Discovery 168 To allow clients to discover support for this extension, servers 169 implementing this specification SHOULD publish IANA-ASSIGNED-OID.1 and 170 IANA-ASSIGNED-OID.3 as values of the 'supportedExtension' attribute 171 [RFC4512] within the Root DSE, and publish the IANA-ASSIGNED-OID.2 as 172 a value of the 'supportedControl' attribute [RFC4512] of the Root DSE. 174 A server MAY choose to advertise this extension only when the client 175 is authorized to use it. 177 3.2. Starting a Transaction 178 A client wishing to perform a sequence of directory updates as an 179 transaction issues a Start Transaction Request. A server which is 180 willing and able to support transactions responds to this request with 181 a Start Transaction Response providing a transaction identifier and 182 with a resultCode of success (0). Otherwise, the server responds with 183 a Start Transaction Response with a result code other than success 184 indicating the nature of the failure. 186 The transaction identifier provided upon successful start of a 187 transaction is used in subsequent protocol messages to identify this 188 transaction. 190 3.3. Specification of a Transaction 192 The client then can issue one or more update requests, each with a 193 Transaction Specification control containing the transaction 194 identifier indicating the updates are to processed as part of the 195 transaction. Each of these update request MUST have a different 196 MessageID value. If the server is unwilling or unable to attempt to 197 process the requested update operation as part of the transaction, the 198 server immediately returns the appropriate response to the request 199 with a resultCode indicating the nature of the failure. Otherwise, 200 the server immediately returns success (0) and the defers further 201 processing of the operation is then deferred until settlement. 203 If the server becomes unwilling or unable to continue the 204 specification of a transaction, the server issues an Aborted 205 Transaction Notice with a non-success resultCode indicating the nature 206 of the failure. All operations that were to be processed as part of 207 the transaction are implicitly abandoned. Upon receipt of an Aborted 208 Transaction Notice, the client is to discontinue all use of the 209 transaction identifier as the transaction is null and void. Any 210 future use of identifier by the client will result in a response 211 containing a non-success resultCode. 213 3.4. Transaction Settlement 215 A client requests settlement of transaction by issuing an End 216 Transaction request for the transaction indicating whether it desires 217 the transaction to be committed or aborted. 219 Upon receipt of a request to abort the transaction, the server is to 220 abort the identified transaction (abandoning all operations which are 221 part of the transaction) and indicate that it has done so by returning 222 an End Transaction Response with a resultCode of success (0). 224 Upon receipt of a request to commit the transaction, the server 225 processes all update operations of the transaction as one atomic, 226 durable, isolated, and consistent action with each requested update 227 being processed in turn. Either all of the requested updates are to 228 be successfully applied or none of the requested are to be applied. 229 The server returns an End Transaction Response with a resultCode of 230 success (0) and no responseValue to indicate all the requested updates 231 were applied. Otherwise, the server returns an End Transaction with 232 an non-success resultCode indicating the nature of the failure. If 233 the failure is associated with a particular update request, the 234 txnEndRes.messageID in the responseValue is the messageID of this 235 update request. If the failure was not associated with any particular 236 update request, no txnEnd.messageID is provided. 238 There is no requirement that a server serialize transactions, or 239 updates requested outside of a transaction. That is, a server MAY 240 process multiple commit requests (from one or more clients) acting 241 upon different sets of entries concurrently. A server MUST avoid 242 deadlock. 244 3.5. Miscellaneous Issues 246 Transactions cannot be nested. 248 Each LDAP transaction should be initiated, specified, and settled 249 within a stable security context. Between the Start request and the 250 End response, the peers SHOULD avoid negotiating new security 251 associations and/or layers. 253 Upon receipt of a Bind or Unbind request, the server SHALL abort any 254 and all outstanding transactions without notice and nullify their 255 identifiers. 257 4. Interaction with Other Extensions 259 The LDAP Transaction extension may be used with many but not all LDAP 260 control extensions designed to extend Update (and possibly other) 261 operations. The remainder of this subsection discusses interaction 262 with a number of control extensions. Interaction with other control 263 extensions may be discussed in other documents, in particular in 264 control extension specifications. 266 4.1. Assertion Control 268 The Assertion [RFC4528] control is appropriate for use with update 269 requests specified as part of a transaction. The evaluation of the 270 assertion is performed as part of the transaction. 272 The Assertion control is inappropriate for use with either the 273 Transaction Start or End extended operations. 275 4.2. ManageDsaIT Control 277 The ManageDsaIT [RFC3296] control is appropriate for use with update 278 requests specified as part of a transaction. 280 The ManageDsaIT control is inappropriate for use with either the 281 Transaction Start or End extended operations. 283 4.4. Proxied Authorization Control 285 The Proxied Authorization [RFC4370] control is appropriate for use 286 with the Transaction Start extended operation, but not the Transaction 287 End extended operation or any update request specified as part of a 288 transaction. 290 To request that a transaction be performed under a different 291 authorization, the client provides a Proxied Authorization control 292 with the Transaction Start request. If the client is not authorized 293 to assume the requested authorization identity, the server is to 294 return the authorizationDenied (123) resultCode in its response. 295 Otherwise, further processing of the request and transaction is 296 performed under the requested authorization identity. 298 Any proxied authorization request attached to an update request 299 specified as part of a transaction, or attached to a Transaction end 300 request, is to be regarded as a protocol error. 302 4.5. Read Entry Controls 304 The Pre- and Post-Read Entry [RFC4527] request control are appropriate 305 for use with update requests specified as part of a transaction. 307 The response control produced in response to a Pre- or Post-Read Entry 308 request control is returned in the txnEndRes.updatesControls field of 309 responseValue of the End Transaction Response. 311 The Pre- and Post-Read Entry controls are inappropriate for use in the 312 LDAPMessage.controls field of the Transaction Start and End request 313 and response messages. 315 5. Distributed Directory Considerations 317 The LDAP/X.500 models provide for distributed directory operations, 318 including server-side chaining and client-side chasing of referrals. 320 This document does not preclude servers from chaining operations which 321 are part of a transaction. However, if a server does attempt such 322 chaining, it MUST ensure that transaction semantics are provided. 324 This mechanism defined by this document does not support client-side 325 chasing. Transaction identifiers are specific to a particular LDAP 326 association (as established via the LDAP Bind operation). 328 The LDAP/X.500 models provide for a single-master/multiple-shadow 329 replication architecture. There is no requirement that changes made 330 to the directory based upon processing a transaction be replicated as 331 one atomic action. Hence, clients SHOULD NOT assume tight data 332 consistency nor fast data convergence of shadow copies unless they 333 have prior knowledge that these properties are provided. Note that 334 DontUseCopy control [DONTUSECOPY] control may be used in conjunction 335 with the LDAP search request to ask for the return of the 336 authoritative copy of the entry. 338 6. Security Considerations 340 Transactions mechanisms may be the target of denial-of-service 341 attacks, especially where implementation lock shared resources for the 342 duration of a transaction. 344 General security considerations [RFC4510], especially those associated 345 with update operations [RFC4511], apply to this extension. 347 7. IANA Considerations 349 It is requested that Internet Assigned Numbers Authority (IANA) make 350 the following assignments. 352 7.1. Object Identifier 354 Assignment of an LDAP Object Identifier [RFC4520] to identify the 355 protocol elements specified in this document this document is 356 requested. 358 Subject: Request for LDAP Object Identifier Registration 359 Person & email address to contact for further information: 361 Kurt Zeilenga 362 Specification: RFC XXXX 363 Author/Change Controller: Kurt Zeilenga 364 Comments: Identifies protocol elements for LDAP Transactions 366 7.2. LDAP Protocol Mechanism 368 Registration of the protocol mechanisms [RFC4520] specified in this 369 document is requested. 371 Subject: Request for LDAP Protocol Mechanism Registration 372 Object Identifier: see table 373 Description: see table 374 Person & email address to contact for further information: 375 Kurt Zeilenga 376 Specification: RFC XXXX 377 Author/Change Controller: Kurt Zeilenga 378 Comments: 380 Object Identifier Type Description 381 ------------------- ---- ---------------------------------- 382 IANA-ASSIGNED-OID.1 E Start Transaction Extended Request 383 IANA-ASSIGNED-OID.2 C Transaction Specification Control 384 IANA-ASSIGNED-OID.3 E End Transaction Extended Request 385 IANA-ASSIGNED-OID.4 N Aborted Transaction Notice 387 Legend 388 ------------------------ 389 C => supportedControl 390 E => supportedExtension 391 N => Unsolicited Notice 393 8. Acknowledgments 395 The author gratefully acknowledges the contributions made by Internet 396 Engineering Task Force participants. 398 9. Author's Address 400 Kurt D. Zeilenga 401 Isode Limited 403 Email: Kurt.Zeilenga@Isode.COM 405 10. References 407 [[Note to the RFC Editor: please replace the citation tags used in 408 referencing Internet-Drafts with tags of the form RFCnnnn where 409 possible.]] 411 10.1. Normative References 413 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 414 Requirement Levels", BCP 14 (also RFC 2119), March 1997. 416 [RFC3062] Zeilenga, K., "LDAP Password Modify Extended Operation", 417 RFC 3062, February 2001. 419 [RFC3296] Zeilenga, K., "Named Subordinate References in 420 Lightweight Directory Access Protocol (LDAP) 421 Directories", RFC 3296, July 2002. 423 [RFC4370] Weltman, R., "LDAP Proxied Authentication Control", RFC 424 4370, Feb. 2006. 426 [RFC4510] Zeilenga, K. (editor), "LDAP: Technical Specification 427 Road Map", RFC 4510, June 2006. 429 [RFC4511] Sermersheim, J. (editor), "LDAP: The Protocol", RFC 430 4511, June 2006. 432 [RFC4512] Zeilenga, K. (editor), "LDAP: Directory Information 433 Models", RFC 4512, June 2006. 435 [RFC4527] Zeilenga, K., "LDAP Read Entry Controls", RFC 4527, June 436 2006. 438 [RFC4528] Zeilenga, K., "LDAP Assertion Control", RFC 4528, June 439 2006. 441 [X.680] International Telecommunication Union - 442 Telecommunication Standardization Sector, "Abstract 443 Syntax Notation One (ASN.1) - Specification of Basic 444 Notation", X.680(2002) (also ISO/IEC 8824-1:2002). 446 [X.690] International Telecommunication Union - 447 Telecommunication Standardization Sector, "Specification 448 of ASN.1 encoding rules: Basic Encoding Rules (BER), 449 Canonical Encoding Rules (CER), and Distinguished 450 Encoding Rules (DER)", X.690(2002) (also ISO/IEC 451 8825-1:2002). 453 10.2. Informative References 455 [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority 456 (IANA) Considerations for the Lightweight Directory 457 Access Protocol (LDAP)", RFC 4520, BCP 64, June 2006. 459 [ACID] Section 4 of ISO/IEC 10026-1:1992. 461 [DONTUSECOPY] Zeilenga, K., "LDAP Don't Use Copy Control", draft- 462 zeilenga-ldap-dontusecopy-xx.txt, a work in progress. 464 Full Copyright 466 Copyright (c) 2008 IETF Trust and the persons identified as the 467 document authors. All rights reserved. 469 This document is subject to BCP 78 and the IETF Trust's Legal 470 Provisions Relating to IETF Documents 471 (http://trustee.ietf.org/license-info) in effect on the date of 472 publication of this document. Please review these documents 473 carefully, as they describe your rights and restrictions with respect 474 to this document.