7 INTERNET-DRAFT Kurt D. Zeilenga
8 Intended Category: Standard Track OpenLDAP Foundation
9 Expires in six months 5 March 2006
13 <draft-zeilenga-ldap-txn-07.txt>
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>.
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.
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.
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."
39 The list of current Internet-Drafts can be accessed at
40 http://www.ietf.org/1id-abstracts.html
42 The list of Internet-Draft Shadow Directories can be accessed at
43 http://www.ietf.org/shadow.html
46 Copyright (C) The Internet Society (2006). All Rights Reserved.
48 Please see the Full Copyright section near the end of this document
54 Lightweight Directory Access Protocol (LDAP) update operations, such
58 Zeilenga LDAP Transactions [Page 1]
60 INTERNET-DRAFT draft-zeilenga-ldap-txn-07 5 March 2006
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
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
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.
92 1.1. Conventions and Terminology
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].
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].
103 DSA stands for "Directory System Agent" (a server). DSE stands for
104 "DSA-specific entry".
107 2. Elements of an LDAP Transaction
109 2.1. Start Transaction Request and Response
114 Zeilenga LDAP Transactions [Page 2]
116 INTERNET-DRAFT draft-zeilenga-ldap-txn-07 5 March 2006
119 A Start Transaction Request is an LDAPMessage of CHOICE extendedReq
120 where the requestName is IANA-ASSIGNED-OID.1 and the requestValue is
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
130 2.2. Transaction Specification Control
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
138 2.3. End Transactions Request and Response
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.
144 settlementValue ::= SEQUENCE {
145 commit BOOLEAN DEFAULT TRUE,
146 identifier OCTET STRING }
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.
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.
157 2.5. Aborted Transaction Notice
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.
164 3. An LDAP Transaction
166 3.1. Extension Discovery
170 Zeilenga LDAP Transactions [Page 3]
172 INTERNET-DRAFT draft-zeilenga-ldap-txn-07 5 March 2006
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.
181 A server MAY choose to advertise this extension only when the client
182 is authorized to use it.
185 3.2. Starting an Transactions
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.
195 The transaction identifier provided upon successful start of a
196 transaction is used in subseqent protocol messages to identify this
200 3.3. Specification of a Transaction
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.
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.
226 Zeilenga LDAP Transactions [Page 4]
228 INTERNET-DRAFT draft-zeilenga-ldap-txn-07 5 March 2006
231 3.4. Transaction Settlement
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.
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.
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.
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
262 4. Distributed Directory Considerations
264 The LDAP/X.500 models provide for distributed directory operations
265 including server-side chaining and client-side chasing of operations.
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.
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.
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
282 Zeilenga LDAP Transactions [Page 5]
284 INTERNET-DRAFT draft-zeilenga-ldap-txn-07 5 March 2006
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.
292 The LDAP/X.500 models do not currently support a multi-master
293 replication architecture and, hence, not considered by this
297 5. Security Considerations
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.
303 General security considerations [Roadmap], especially associated with
304 update operations [Protocol], apply to this extension.
307 6. IANA Considerations
309 In accordance with [BCP64bis], it is requested that Internet Assigned
310 Numbers Authority (IANA) make the following assignments.
313 6.1. Object Identifier
315 Assignment of an LDAP Object Identifier to identify the protocol
316 elements specified in this document this document is requested.
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
326 6.2. LDAP Protocol Mechanism
328 Registration of the protocol mechanisms specified in this document is
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:
338 Zeilenga LDAP Transactions [Page 6]
340 INTERNET-DRAFT draft-zeilenga-ldap-txn-07 5 March 2006
343 Kurt Zeilenga <kurt@openldap.org>
344 Specification: RFC XXXX
345 Author/Change Controller: IESG
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
357 The author gratefully acknowledges the contributions made by members
358 of the Internet Engineering Task Force.
366 Email: Kurt@OpenLDAP.org
371 [[Note to the RFC Editor: please replace the citation tags used in
372 referencing Internet-Drafts with tags of the form RFCnnnn where
376 9.1. Normative References
378 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
379 Requirement Levels", BCP 14 (also RFC 2119), March 1997.
381 [Roadmap] Zeilenga, K. (editor), "LDAP: Technical Specification
382 Road Map", draft-ietf-ldapbis-roadmap-xx.txt, a work in
385 [Protocol] Sermersheim, J. (editor), "LDAP: The Protocol",
386 draft-ietf-ldapbis-protocol-xx.txt, a work in progress.
388 [Models] Zeilenga, K. (editor), "LDAP: Directory Information
389 Models", draft-ietf-ldapbis-models-xx.txt, a work in
394 Zeilenga LDAP Transactions [Page 7]
396 INTERNET-DRAFT draft-zeilenga-ldap-txn-07 5 March 2006
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).
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
412 9.2. Informative References
414 [ACID] Section 4 of ISO/IEC 10026-1:1992.
416 [BCP64bis] Zeilenga, K., "IANA Considerations for LDAP",
417 draft-ietf-ldapbis-bcp64-xx.txt, a work in progress.
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).
424 [X.501] International Telecommunication Union -
425 Telecommunication Standardization Sector, "The Directory
426 -- Models," X.501(1993) (also ISO/IEC 9594-2:1994).
430 Intellectual Property Rights
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.
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.
450 Zeilenga LDAP Transactions [Page 8]
452 INTERNET-DRAFT draft-zeilenga-ldap-txn-07 5 March 2006
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
465 Copyright (C) The Internet Society (2006).
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.
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.
506 Zeilenga LDAP Transactions [Page 9]