]> git.sur5r.net Git - openldap/blob - doc/rfc/rfc5805.txt
Fix prev commit
[openldap] / 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