From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc5805.txt | 619 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 619 insertions(+) create mode 100644 doc/rfc/rfc5805.txt (limited to 'doc/rfc/rfc5805.txt') diff --git a/doc/rfc/rfc5805.txt b/doc/rfc/rfc5805.txt new file mode 100644 index 0000000..55b6b9e --- /dev/null +++ b/doc/rfc/rfc5805.txt @@ -0,0 +1,619 @@ + + + + + + +Independent Submission K. Zeilenga +Request for Comments: 5805 Isode Limited +Category: Experimental March 2010 +ISSN: 2070-1721 + + + Lightweight Directory Access Protocol (LDAP) Transactions + +Abstract + + Lightweight Directory Access Protocol (LDAP) update operations, such + as Add, Delete, and Modify operations, have atomic, consistency, + isolation, durability (ACID) properties. Each of these update + operations act upon an entry. It is often desirable to update two or + more entries in a single unit of interaction, a transaction. + Transactions are necessary to support a number of applications + including resource provisioning. This document extends LDAP to + support transactions. + +Status of This Memo + + This document is not an Internet Standards Track specification; it is + published for examination, experimental implementation, and + evaluation. + + This document defines an Experimental Protocol for the Internet + community. This is a contribution to the RFC Series, independently + of any other RFC stream. The RFC Editor has chosen to publish this + document at its discretion and makes no statement about its value for + implementation or deployment. Documents approved for publication by + the RFC Editor are not a candidate for any level of Internet + Standard; see Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained 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, as they describe your rights and restrictions with respect + to this document. + + + +Zeilenga Experimental [Page 1] + +RFC 5805 LDAP Transactions March 2010 + + +1. Overview + + This document extends the Lightweight Directory Access Protocol + (LDAP) [RFC4510] to allow clients to relate a number of update + operations [RFC4511] and have them performed as one unit of + interaction, a transaction. As with distinct update operations, each + transaction has atomic, consistency, isolation, and durability (ACID) + properties [ACID]. + + This extension consists of two extended operations, one control, and + one unsolicited notification message. The Start Transaction + operation is used to obtain a transaction identifier. This + identifier is then attached to multiple update operations to indicate + that they belong to the transaction using the Transaction + Specification control. The End Transaction is used to settle (commit + or abort) the transaction. The Aborted Transaction Notice is + provided by the server to notify the client that the server is no + longer willing or able to process an outstanding transaction. + +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]. + + 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. + + + + + +Zeilenga Experimental [Page 2] + +RFC 5805 LDAP Transactions March 2010 + + +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 in conjunction with request controls 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 indicates a request to commit the transaction + identified by the identifier. A commit value of FALSE indicates a + request to abort the identified transaction. + + An End Transaction Response is an LDAPMessage sent in response to a + 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 provides the message id of the update request + associated with a non-success response. txnEndRes.messageID is + absent when resultCode of the End Transaction Response is success + (0). + + + + + +Zeilenga Experimental [Page 3] + +RFC 5805 LDAP Transactions March 2010 + + + The txnEndRes.updatesControls provides a facility for returning + response controls that normally (i.e., in the absence of + transactions) would be returned in an update response. The + updateControls.messageID provides the message id of the update + request associated with the response controls provided 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. + +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 responseValue is present + and contains a transaction identifier. + +3. An LDAP Transaction + +3.1. Extension Discovery + + To allow clients to discover support for 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 the 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 wishing to perform 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 providing a transaction identifier + and with a resultCode of success (0). Otherwise, the server responds + with a Start Transaction Response with a resultCode other than + success indicating the nature of the failure. + + The transaction identifier provided upon successful start of a + transaction is used in subsequent protocol messages to identify this + transaction. + + + + + + +Zeilenga Experimental [Page 4] + +RFC 5805 LDAP Transactions March 2010 + + +3.3. Specification of a Transaction + + The client then can issue one or more update requests, each with a + Transaction Specification control containing the transaction + identifier indicating the updates are to be processed as part of the + transaction. Each of these update requests MUST have a different + MessageID value. If the server is unwilling or unable to attempt to + process the requested update operation as part of the transaction, + the server immediately returns the appropriate response to the + request with a resultCode indicating the nature of the failure. + 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 continue the + specification of a transaction, the server issues an Aborted + Transaction Notice with a non-success resultCode indicating the + nature of the failure. All operations that were to be processed as + part of the transaction are implicitly abandoned. Upon receipt of an + Aborted Transaction Notice, the client is to discontinue all use of + the transaction identifier as the transaction is null and void. Any + future use of identifier by the client will result in a response + containing a non-success resultCode. + +3.4. Transaction Settlement + + A client requests settlement of transaction by issuing an End + Transaction Request for the transaction indicating whether it desires + the transaction to be committed or aborted. + + Upon receipt of a request to abort the transaction, the server is to + abort the identified transaction (abandoning all operations that are + part of the transaction) and indicate that it has done so by + returning an End Transaction Response with a resultCode of success + (0). + + Upon receipt of a request to commit the transaction, the server + processes all update operations of the transaction as one atomic, + durable, isolated, and consistent action with each requested update + being processed in turn. Either all of the requested updates are to + be successfully applied or none of the requested are to be applied. + The server returns an End Transaction Response with a resultCode of + success (0) and no responseValue to indicate all the requested + updates were applied. Otherwise, the server returns an End + Transaction Response with a non-success resultCode indicating the + nature of the failure. If the failure is associated with a + + + + + +Zeilenga Experimental [Page 5] + +RFC 5805 LDAP Transactions March 2010 + + + particular update request, the txnEndRes.messageID in the + responseValue is the message id of this update request. If the + failure was not associated with 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 is, 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 initiated, 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. + + Upon receipt of a Bind or Unbind request, the server SHALL abort any + and all outstanding transactions without notice and nullify their + identifiers. + +4. Interaction with Other Extensions + + The LDAP Transaction extension may be used with many but not all LDAP + control extensions designed to extend update (and possibly other) + operations. The subsections that follow discuss interaction with a + number of control extensions. Interaction with other control + extensions may be discussed in other documents, in particular in + control extension specifications. + +4.1. Assertion Control + + The Assertion [RFC4528] control is appropriate for use with update + requests specified as part of a transaction. The evaluation of the + assertion is performed as part of the transaction. + + The Assertion control is inappropriate for use with either the Start + or End Transaction Extended operations. + +4.2. ManageDsaIT Control + + The ManageDsaIT [RFC3296] control is appropriate for use with update + requests specified as part of a transaction. + + + + + +Zeilenga Experimental [Page 6] + +RFC 5805 LDAP Transactions March 2010 + + + The ManageDsaIT control is inappropriate for use with either the + Start or End Transaction Extended operations. + +4.4. Proxied Authorization Control + + The Proxied Authorization [RFC4370] control is appropriate for use + with the Start Transaction Extended operation, but not the End + Transaction Extended operation or any update request specified as + part of a transaction. + + To request that a transaction be performed under a different + authorization, the client provides a Proxied Authorization control + with the Transaction Start Request. If the client is not authorized + to assume the requested authorization identity, the server is to + return the authorizationDenied (123) resultCode in its response. + Otherwise, further processing of the request and transaction is + performed under the requested authorization identity. + + Any proxied authorization request attached to an update request + specified as part of a transaction, or attached to a Transaction End + Request, is to be regarded as a protocol error. + +4.5. Read Entry Controls + + The Pre- and Post-Read Entry [RFC4527] request control are + appropriate for use with update requests specified as part of a + transaction. + + The response control produced in response to a Pre- or Post-Read + Entry request control is returned in the txnEndRes.updatesControls + field of responseValue of the End Transaction Response. + + The Pre- and Post-Read Entry controls are inappropriate for use in + the LDAPMessage.controls field of the Transaction Start and End + Request and Response messages. + +5. Distributed Directory Considerations + + The LDAP/X.500 models provide for distributed directory operations, + including server-side chaining and client-side chasing of referrals. + + This document does not preclude servers from chaining operations that + are part of a transaction. However, if a server does attempt such + chaining, it MUST ensure that transaction semantics are provided. + + The mechanism defined by this document does not support client-side + chasing. Transaction identifiers are specific to a particular LDAP + association (as established via the LDAP Bind operation). + + + +Zeilenga Experimental [Page 7] + +RFC 5805 LDAP Transactions March 2010 + + + The LDAP/X.500 models provide for a single-master/multiple-shadow + replication architecture. There is no requirement that changes made + to the directory based upon processing a transaction be replicated as + one atomic action. Hence, clients SHOULD NOT assume tight data + consistency nor fast data convergence of shadow copies unless they + have prior knowledge that these properties are provided. Note that + DontUseCopy control [DONTUSECOPY] may be used in conjunction with the + LDAP search request to ask for the return of the authoritative copy + of the entry. + +6. Security Considerations + + Transaction mechanisms may be the target of denial-of-service + attacks, especially where implementations lock shared resources for + the duration of a transaction. + + General security considerations [RFC4510], especially those + associated with update operations [RFC4511], apply to this extension. + +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 + Specification: RFC 5805 + Author/Change Controller: Kurt Zeilenga + Comments: Identifies protocol elements for LDAP Transactions + + + + + + + + + + + + + + + + +Zeilenga Experimental [Page 8] + +RFC 5805 LDAP Transactions March 2010 + + +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 + Specification: RFC 5805 + Author/Change Controller: Kurt Zeilenga + 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 acknowledges the contributions made by Internet + Engineering Task Force participants. + +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. + + + + + + +Zeilenga Experimental [Page 9] + +RFC 5805 LDAP Transactions March 2010 + + + [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. + + + + + + +Zeilenga Experimental [Page 10] + +RFC 5805 LDAP Transactions March 2010 + + +Author's Address + + Kurt D. Zeilenga + Isode Limited + + EMail: Kurt.Zeilenga@Isode.COM + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Zeilenga Experimental [Page 11] + -- cgit v1.2.3