RFC 5805

Title block (the basics, bestie) 🎀

• Title: Lightweight Directory Access Protocol (LDAP) Transactions
• Stream: Independent Submission
• Request for Comments: 5805
• Author: K. Zeilenga, Isode Limited
• Category: Experimental
• Date: March 2010
• ISSN: 2070-1721
• Obsoletes / Updates: the title block doesn't list anything this one obsoletes or updates 🫶

---

Abstract ✨

okay so LDAP update operations like Add, Delete, and Modify are all ACID (atomic, consistency, isolation, durability) 💅 but each one only acts on a single entry. Sometimes you need to change two or more entries as one unit of interaction, and that's a transaction 🦋. Transactions are needed for a bunch of apps, including resource provisioning. This document extends LDAP so it can do transactions, and it's giving main character energy 👑

Status of This Memo 🌸

This document is not an Internet Standards Track specification. It's published for examination, experimental implementation, and evaluation, so it's very much a "try it out and tell us" kind of thing 🧪

This document defines an Experimental Protocol for the Internet community. It's a contribution to the RFC Series, independent of any other RFC stream. The RFC Editor picked to publish it at their discretion and makes no statement about its value for implementation or deployment. Documents the RFC Editor approves for publication aren't a candidate for any level of Internet Standard, see Section 2 of RFC 5741 💜

Info about the current status of this document, any errata, and how to give feedback is at http://www.rfc-editor.org/info/rfc5805 🔗

Copyright Notice 🌈

Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, because they describe your rights and restrictions with respect to this document. Read the fine print, bestie 🙈

1. Overview ✨

This document extends the Lightweight Directory Access Protocol (LDAP) [RFC4510] so clients can relate a bunch of update operations [RFC4511] and have them performed as one unit of interaction, a transaction. Just like distinct update operations, each transaction has atomic, consistency, isolation, and durability (ACID) properties [ACID] 💖

This extension is made of two extended operations, one control, and one unsolicited notification message. The Start Transaction operation gets you a transaction identifier. That identifier then gets attached to multiple update operations to show they belong to the transaction, using the Transaction Specification control. The End Transaction operation settles the transaction (commit or abort) 🎀. The Aborted Transaction Notice is sent by the server to tell the client that it's no longer willing or able to process an outstanding transaction. Rip 💀

1.1. Conventions and Terminology 🧚

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. Those words are the important ones, so pay attention to them 🔥

Protocol elements are described using ASN.1 [X.680] with implicit tags. The term "BER-encoded" means the element is to be encoded using the Basic Encoding Rules [X.690] under the restrictions detailed in Section 5.1 of [RFC4511] 🍓

DSA stands for "Directory System Agent" (a server). DSE stands for "DSA-specific entry" 💅

2. Elements of an LDAP Transaction 🦋

2.1. Start Transaction Request and Response

A Start Transaction Request is an LDAPMessage of CHOICE extendedReq where the requestName is 1.3.6.1.1.21.1 and the requestValue is absent ✨

A Start Transaction Response is an LDAPMessage of CHOICE extendedRes sent in response to a Start Transaction Request. Its responseName is absent. When the resultCode is success (0), responseValue is present and contains a transaction identifier. Otherwise, the responseValue is absent 🫶

2.2. Transaction Specification Control

A Transaction Specification Control is an LDAPControl where the controlType is 1.3.6.1.1.21.2, the criticality is TRUE, and the controlValue is a transaction identifier. The control is appropriate for update requests including Add, Delete, Modify, and ModifyDN (Rename) requests [RFC4511], as well as the Password Modify requests [RFC3062] 💜

As discussed in Section 4, the Transaction Specification control can be used together with request controls that are appropriate for the update request 🌸

2.3. End Transactions Request and Response

An End Transaction Request is an LDAPMessage of CHOICE extendedReq where the requestName is 1.3.6.1.1.21.3 and the requestValue is present and contains a BER-encoded txnEndReq 🎀

      txnEndReq ::= SEQUENCE {
           commit         BOOLEAN DEFAULT TRUE,
           identifier     OCTET STRING }

A commit value of TRUE means a request to commit the transaction identified by the identifier. A commit value of FALSE means a request to abort the identified transaction 🔥

An End Transaction Response is an LDAPMessage sent in response to an End Transaction Request. Its response name is absent. The responseValue, when present, contains a BER-encoded txnEndRes 🌈

      txnEndRes ::= SEQUENCE {
           messageID MessageID OPTIONAL,
                -- msgid associated with non-success resultCode
           updatesControls SEQUENCE OF updateControls SEQUENCE {
                messageID MessageID,
                     -- msgid associated with controls
                controls  Controls
           } OPTIONAL
      }
      -- where MessageID and Controls are as specified in RFC 4511

The txnEndRes.messageID gives the message id of the update request linked to a non-success response. txnEndRes.messageID is absent when the resultCode of the End Transaction Response is success (0) 🧚

The txnEndRes.updatesControls is a way of returning response controls that would normally (aka without transactions) come back in an update response. The updateControls.messageID gives the message id of the update request linked to the response controls in updateControls.controls ✨

The txnEndRes.updatesControls is absent when there are no update response controls to return 💅

If both txnEndRes.messageID and txnEndRes.updatesControl are absent, the responseValue of the End Transaction Response is absent too 🙈

2.4. Aborted Transaction Notice

The Aborted Transaction Notice is an Unsolicited Notification message where the responseName is 1.3.6.1.1.21.4 and the responseValue is present and contains a transaction identifier 💀

3. An LDAP Transaction 🍓

3.1. Extension Discovery

So clients can find out whether a server supports this extension, servers implementing this specification SHOULD publish 1.3.6.1.1.21.1 and 1.3.6.1.1.21.3 as values of the 'supportedExtension' attribute [RFC4512] within the Root DSE, and publish 1.3.6.1.1.21.2 as a value of the 'supportedControl' attribute [RFC4512] of the Root DSE 🔍

A server MAY choose to advertise this extension only when the client is authorized to use it 🔐

3.2. Starting a Transaction

A client that wants to do a sequence of directory updates as a transaction issues a Start Transaction Request. A server that is willing and able to support transactions responds to this request with a Start Transaction Response that gives a transaction identifier and a resultCode of success (0). Otherwise, the server responds with a Start Transaction Response carrying a resultCode other than success, which says what went wrong 😭

The transaction identifier given on a successful start is used in later protocol messages to identify this transaction 🫶

3.3. Specification of a Transaction

The client can then issue one or more update requests, each with a Transaction Specification control containing the transaction identifier, which tells the server the updates are part of the transaction. Each of these update requests MUST have a different MessageID value. If the server is unwilling or unable to try processing the requested update operation as part of the transaction, the server immediately returns the appropriate response to the request, with a resultCode saying what went wrong. Otherwise, the server immediately returns a resultCode of success (0), and the defers further processing of the operation is then deferred until settlement ✨

If the server becomes unwilling or unable to keep specifying a transaction, the server issues an Aborted Transaction Notice with a non-success resultCode that says what went wrong. All operations that were going to be processed as part of the transaction are implicitly abandoned. When the client gets an Aborted Transaction Notice, it is to stop using the transaction identifier entirely, because the transaction is null and void. Any future use of that identifier by the client will get a response with a non-success resultCode 💀

3.4. Transaction Settlement

A client asks for a transaction to be settled by issuing an End Transaction Request for it, saying whether it wants the transaction committed or aborted 🎀

When the server gets a request to abort the transaction, it is to abort the identified transaction (abandoning all operations that were part of it) and show that it did so by returning an End Transaction Response with a resultCode of success (0) 🌸

When the server gets a request to commit the transaction, it processes all update operations of the transaction as one atomic, durable, isolated, and consistent action, with each requested update processed in turn. Either all of the requested updates are successfully applied or none of them are applied. The server returns an End Transaction Response with a resultCode of success (0) and no responseValue to show all the requested updates were applied. Otherwise, the server returns an End Transaction Response with a non-success resultCode saying what went wrong. If the failure is linked to a particular update request, the txnEndRes.messageID in the responseValue is the message id of that update request. If the failure isn't linked to any particular update request, no txnEnd.messageID is provided 🔥

There is no requirement that a server serialize transactions or updates requested outside of a transaction. That means a server MAY process multiple commit requests (from one or more clients) acting upon different sets of entries concurrently. A server MUST avoid deadlock 💜

3.5. Miscellaneous Issues 🧚

Transactions cannot be nested 🙅‍♀️

Each LDAP transaction should be started, specified, and settled within a stable security context. Between the Start Request and the End Response, the peers SHOULD avoid negotiating new security associations and/or layers 🔐

When the server gets a Bind or Unbind request, it SHALL abort any and all outstanding transactions without notice and nullify their identifiers. No warning, no tea, just gone 💀✨

4. Interaction with Other Extensions ✨

okay so the LDAP Transaction extension plays nicely with lots of control extensions, just not all of them 💅 these ones are designed to extend update operations (and maybe other stuff too). the subsections below walk through a few of them. other control extensions might get their own talk in other docs, especially in their own control extension specs 🎀

4.1. Assertion Control

the Assertion [RFC4528] control is a great match for update requests that are part of a transaction 🦋 the assertion gets checked as part of the transaction itself, so it's giving everything in one tidy bundle.

the Assertion control is a no-go with either the Start or End Transaction Extended operations 🙈

4.2. ManageDsaIT Control

the ManageDsaIT [RFC3296] control works for update requests specified as part of a transaction 🌸

the ManageDsaIT control is a no-go with either the Start or End Transaction Extended operations 💀

4.4. Proxied Authorization Control

the Proxied Authorization [RFC4370] control is for the Start Transaction Extended operation ONLY, not the End Transaction Extended operation or any update request inside a transaction 👑

so if the client wants a transaction to run under a different authorization, it attaches a Proxied Authorization control to the Transaction Start Request ✨ if the client isn't allowed to take on that authorization identity, the server returns the authorizationDenied (123) resultCode in its response. if it IS allowed, everything after that (the processing of the request and the transaction) happens under the requested authorization identity 🧚

any proxied authorization request stuck on an update request inside a transaction, or on a Transaction End Request, counts as a protocol error. no exceptions, bestie 😭

4.5. Read Entry Controls

the Pre- and Post-Read Entry [RFC4527] request controls are a vibe for update requests inside a transaction 🫶

the response control you get back from a Pre- or Post-Read Entry request control shows up in the txnEndRes.updatesControls field of the responseValue in the End Transaction Response 💜

the Pre- and Post-Read Entry controls are NOT it for the LDAPMessage.controls field of the Transaction Start and End Request and Response messages 🙅‍♀️

5. Distributed Directory Considerations 🌈

okay, the LDAP/X.500 models support distributed directory operations, including server-side chaining and client-side chasing of referrals 🗺️

this document doesn't stop servers from chaining operations that are part of a transaction. BUT if a server does go ahead and chain like that, it MUST make sure transaction semantics are still provided 🔥

the mechanism in this document does NOT support client-side chasing. transaction identifiers are tied to one specific LDAP association (the one set up by the LDAP Bind operation) 🎀

the LDAP/X.500 models also have a single-master/multiple-shadow replication setup. there's no requirement that changes made to the directory from processing a transaction get replicated as one atomic action 💅 so, clients SHOULD NOT assume tight data consistency or fast data convergence across shadow copies, unless they already know those properties are provided 🙈 also, the DontUseCopy control [DONTUSECOPY] can be used with an LDAP search request to ask for the authoritative copy of the entry back ✨

6. Security Considerations 💀

transaction mechanisms can be the target of denial-of-service attacks, especially when implementations lock shared resources for the whole duration of a transaction 😭 this one's a real concern, bestie, so don't sleep on it.

general security considerations [RFC4510] apply to this extension, especially the ones tied to update operations [RFC4511] 🔐

7. IANA Considerations 📋

the Internet Assigned Numbers Authority (IANA) has made the following assignments 🌸

7.1. Object Identifier

IANA has assigned an LDAP Object Identifier (21) [RFC4520] to identify the protocol elements specified in this document 🦋

   Subject: Request for LDAP Object Identifier Registration
   Person & email address to contact for further information:
       Kurt Zeilenga <Kurt.Zeilenga@Isode.COM>
   Specification: RFC 5805
   Author/Change Controller: Kurt Zeilenga <Kurt.Zeilenga@Isode.COM>
   Comments: Identifies protocol elements for LDAP Transactions

7.2. LDAP Protocol Mechanism

IANA has registered the protocol mechanisms [RFC4520] specified in this document 🎀

   Subject: Request for LDAP Protocol Mechanism Registration
   Object Identifier: see table
   Description: see table
   Person & email address to contact for further information:
       Kurt Zeilenga <Kurt.Zeilenga@Isode.COM>
   Specification: RFC 5805
   Author/Change Controller: Kurt Zeilenga <Kurt.Zeilenga@Isode.COM>
   Comments:

   Object Identifier   Type  Description
   ------------------- ----  ----------------------------------
   1.3.6.1.1.21.1      E     Start Transaction Extended Request
   1.3.6.1.1.21.2      C     Transaction Specification Control
   1.3.6.1.1.21.3      E     End Transaction Extended Request
   1.3.6.1.1.21.4      N     Aborted Transaction Notice

   Legend
   ------------------------
   C => supportedControl
   E => supportedExtension
   N => Unsolicited Notice

8. Acknowledgments 🫶

the author gratefully thanks the Internet Engineering Task Force participants who contributed 💖

9. References 📚

9.1. Normative References

[RFC2119]     Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

[RFC3062]     Zeilenga, K., "LDAP Password Modify Extended
              Operation", RFC 3062, February 2001.

[RFC3296]     Zeilenga, K., "Named Subordinate References in
              Lightweight Directory Access Protocol (LDAP)
              Directories", RFC 3296, July 2002.

[RFC4370]     Weltman, R., "Lightweight Directory Access Protocol
              (LDAP) Proxied Authorization Control", RFC 4370,
              February 2006.

[RFC4510]     Zeilenga, K., Ed., "Lightweight Directory Access
              Protocol (LDAP): Technical Specification Road Map", RFC
              4510, June 2006.

[RFC4511]     Sermersheim, J., Ed., "Lightweight Directory Access
              Protocol (LDAP): The Protocol", RFC 4511, June 2006.

[RFC4512]     Zeilenga, K., Ed., "Lightweight Directory Access
              Protocol (LDAP): Directory Information Models", RFC
              4512, June 2006.

[RFC4527]     Zeilenga, K., "Lightweight Directory Access Protocol
              (LDAP) Read Entry Controls", RFC 4527, June 2006.

[RFC4528]     Zeilenga, K., "Lightweight Directory Access Protocol
              (LDAP) Assertion Control", RFC 4528, June 2006.

[X.680]       International Telecommunication Union -
              Telecommunication Standardization Sector, "Abstract
              Syntax Notation One (ASN.1) - Specification of Basic
              Notation", X.680(2002) (also ISO/IEC 8824-1:2002).

[X.690]       International Telecommunication Union -
              Telecommunication Standardization Sector,
              "Specification of ASN.1 encoding rules: Basic Encoding
              Rules (BER), Canonical Encoding Rules (CER), and
              Distinguished Encoding Rules (DER)", X.690(2002) (also
              ISO/IEC 8825-1:2002).

9.2. Informative References

[RFC4520]     Zeilenga, K., "Internet Assigned Numbers Authority
              (IANA) Considerations for the Lightweight Directory
              Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006.

[ACID]        "Information technology -- Open Systems Interconnection
              -- Distributed Transaction Processing -- Part 1: OSI TP
              Model", Section 4, ISO/IEC 10026-1:1992.

[DONTUSECOPY] Zeilenga, K., "The LDAP Don't Use Copy Control", Work
              in Progress, December 2009.

Author's Address 🌟

Kurt D. Zeilenga
Isode Limited

EMail: Kurt.Zeilenga@Isode.COM