Further to the brief discussion about transactions in LDAP
at the LA meeting, here is a draft which builds on work done
at Hitachi and Netscape over the past year.
I'm not posting this to the IETF repository because we feel
that it's not quite ready, but that the time is now right to
present the work to the list and open up a discussion.
LDAPEXT Working Group David Boreham, Netscape Request for Comments: DRAFT Satoshi Kikuchi, Hitachi Ltd Michiyasu Odaki, Hitachi Ltd April, 1998 LDAP Extensions for Simple Transactions draft-ietf-ldapext-ldapv3-txn-00.txt 1. Status of this Memo This document is an Internet-Draft. Internet-Drafts are working docu- ments of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet- Drafts as reference material or to cite them other than as ``work in progress.'' To learn the current status of any Internet-Draft, please check the ``1id-abstracts.txt'' listing contained in the Internet- Drafts Shadow Directories on ftp.ietf.org (US East Coast), nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). 2. Abstract While individual LDAP operations are themselves atomic [LDAPv3], clients have no such guarantee for a sequence of operations. Such a guarantee may be provided by allowing the client to group operations within tran- sactions. This document describes LDAPv3 Extended Operations and Control Extensions designed to expose simple transaction semantics from transaction-capable servers. This simple transaction service is designed to cater for those LDAP client applications which require atomicity over multiple LDAP operations to a single LDAP server. It does not address transactions which span more than one LDAP server. No support for two- phase commit is provided. 3. Background Directory Services are seeing increased use for purposes other than the traditional white pages application. In particular, information criti- cal to the functioning of networks and their services is being stored in the directory. Examples are DNS data, certificates, and application con- figuration data. When used in this "Network Repository" role, it becomes increasingly important to ensure integrity of the information stored within the directory. The lack of support for transactions in the LDAP Boreham, Kikuchi and Odaki [Page 1] RFC DRAFT April 1998 protocol is seen as a barrier to the more widespread use of the direc- tory for such purposes. Transactions permit an application to ensure consistency in the informa- tion it stores in the directory. For example, should an application need to maintain consistent information across more than one directory entry, without transactions the potential exists for a failure to occur after one entry has been modified but before the second one has. Transactions allow an application to undo the results of several LDAP operations. This can prove invaluable when an error is discovered in performing one of the later operations. All related prior modifications can be undone cleanly. An client which modifies information stored in the directory by perform- ing a sequence of read-modify-write operations is subject to the poten- tial that another client may be performing a similar sequence of opera- tions on the same entries and at the same time. This could lead to data corruption because one client writes based on data it read, but which has now been changed by another client. For example consider an applica- tion which maintains a count of login attempts in a user's directory entry. By placing the read and modify operations within the same tran- saction, this potential for corruption is removed. 4. General Approach Transaction Begin, Abort and Commit are implemented by means of a Tran- saction Request Extended Operation. Begin optionally passes a transac- tion ID from client to server, allowing nested transactions. Upon suc- cessfully processing a Begin operation, the server returns a new tran- saction ID to the client. This may be used in subsequent LDAP operation request messages, by means of a Transaction ID Control. The transaction ID control is also used in any subsequent Abort, Commit or nested Begin operation request. Transaction ID values are non-zero 32-bit integers. The special zero ID value is used in cases where the ID is not required or to indicate an invalid condition. The key words "MUST", "SHOULD", and "MAY" used in this document are to be interpreted as described in [Bradner97]. 5. The Operations and Controls Support for the transaction extended operation is indicated by the pres- ence of the OID "2.16.840.1.113730.3.5.1" in the supportedExtensions attribute of a server's root DSE. Boreham, Kikuchi and Odaki [Page 2] RFC DRAFT April 1998 5.1. Transaction Request A client may request this operation by transmitting an LDAP PDU contain- ing an ExtendedRequest. An LDAP ExtendedRequest is defined as follows: ExtendedRequest ::= [APPLICATION 23] SEQUENCE { requestName [0] LDAPOID, requestValue [1] OCTET STRING } The requestName field is set to the string "2.16.840.1.113730.3.5.1". The requestValue field will contain as a value the BER-encoding of the following ASN.1 data type: txnOp ENUMERATED { txnbegin (0), txncommit (1), txnabort (2), } txnOp indicates to the server whether this is a Begin, Commit or Abort operation request. Unless it carries a begin request with no parent transaction, the request MUST be accompanied by a Transaction ID Control (5.3). This control carries a transaction ID which identifies the transaction to be aborted or committed, or the parent transaction in the case of the begin operation. Where there is no parent transaction, the txnId value in a Transaction ID Control MUST be absent from the begin request. 5.2. Transaction Response If a server implements this extension, then when the Transaction Request operation is received, it will return an LDAP PDU containing an Exten- dedResponse. An LDAP ExtendedResponse is defined as follows: ExtendedResponse ::= [APPLICATION 24] SEQUENCE { COMPONENTS OF LDAPResult, responseName [10] LDAPOID OPTIONAL, responseValue [11] OCTET STRING OPTIONAL } The responseName field MUST be set to the string "2.16.840.1.113730.3.5.2". The responseValue field, when present, will contain as a value the DER-encoding of the following ASN.1 data type: txnId ::= INTEGER (0 .. maxInt) In response to a successful begin operation, txnId contains a newly allocated transaction ID. This txnID is valid for use in subsequent Boreham, Kikuchi and Odaki [Page 3] RFC DRAFT April 1998 Transaction ID request controls (see section 5.3). In response to suc- cessful commit and abort opertaions, the txnID contains the ID of the transaction committed or aborted. When no valid txnID is available, for example in the case that the client supplied an invalid ID, this field MUST be zero. The transaction ID supplied in txnId is valid for inclu- sion in Transaction ID control messages included in subsequent LDAP operations on the same LDAP connection, as long as no intervening Bind operation has been executed (see section 8). This response message MUST contain a Transaction Status Control (5.4) which indicates the success or reason for failure of the operation. 5.3. Transaction ID Control This control is included in any LDAP operation participating in the transaction as part of the controls field of the LDAPMessage, as defined in Section 4.1.12 of [LDAPv3]. The controlType is set to "2.16.840.1.113730.3.4.8". The criticality SHOULD be set to TRUE, where absence is equivalent to TRUE. The controlValue is an OCTET STRING whose value is the BER encoding of a value of the following SEQUENCE: TxnIdRequest::= txnId INTEGER (0 .. maxInt) Where the txnId is the transaction identifier of the transaction in which the operation carrying the control is to participate. 5.4. Transaction Status Control This control is included in the message as part of the controls field of the LDAPMessage, as defined in Section 4.1.12 of [LDAPv3]. The control- Type is set to "2.16.840.1.113730.3.4.11". The criticality is TRUE. The controlValue is an OCTET STRING whose value is the BER encoding of fol- lowing: txnStatus ::= ENUMERATED { success (0), -- operation succeeded operationsError (1), -- server internal failure adminLimitExceeded (11), -- transaction contravened -- an administration limit insufficientAccessRights (50), -- refused to carry out -- transaction operation invalidTxnId (60), -- ID not valid deadlockDetected (61), -- deadlock detected txnTimeLimitExceeded (62), -- timelimit reached txnMethodNotSupported (63), -- unsupported capability txnConcurrency (64), -- concurrent operations other (80) } txnStatus indicates the success or failure of the transaction with Boreham, Kikuchi and Odaki [Page 4] RFC DRAFT April 1998 respect to this operation. This control MAY be included in the result message relating to any operation subject to a transaction. Its absence indicates that there were no transaction-related errors encountered in processing the opera- tion. It MUST be included in the result message relating to any Tran- saction Request message. 6. Transaction Isolation Information read from the directory as part of a transaction is guaranteed to be stable for the duration of that transaction. Informa- tion written to the directory as part of an incomplete transaction is not visible to other readers, whether transacted or not, until the tran- saction is completed. The server MAY delay sending results to a client in order to satisfy these isolation conditions. 7. Ordering of Operations The LDAP protocol permits a client to issue a second operation before receiving indication from the server that the first has completed. This potential for multiple concurrent operations is problematic in the pres- ence of transactions, which imply some strict ordering of events. Accordingly, when transactions are used, clients are not permitted to send an operation request before receiving from the server the result of any previous request. If the server detects that this rule has been bro- ken, it MUST return a txnConcurrency error. Note that this rule does NOT apply to the Transaction Request Extended Operation. Thus it is possible for a client to send both the transac- tion begin request and the first operation subject to the transaction within the same network packet. This reduces the performance penalty paid for transaction support because no additional network round-trip is needed to setup the transaction. 8. Client-Server Interaction 1 - Upon receipt of a Bind operation, the server MUST abort all pending transactions on the connection. This is to ensure, for security rea- sons, that transactions begun under one authentication identity are ter- mintated when the connection's authentication identity changes. 2 - If a server receives a transaction ID which is not valid for the connection, it MUST return an invalidTxnId error. 3 - Server implementations are not required to allow infinitely long Boreham, Kikuchi and Odaki [Page 5] RFC DRAFT April 1998 transaction lifetime. If a server expires a transaction, it MUST abort the transaction and return a txnTimeLimitExceeded error for any opera- tion in progress. Should the client subsequently attempt to use the transaction ID, the server MUST signal an invalidTxnId error. The server MUST avoid re-using the same transaction Id to the same client connec- tion in the future. 4 - Server implementations are not required to allow a client to use up excessive resources by writing very large changes to the directory within a transaction. A server MAY abort a transaction due to resource usage, reporting the error to the client via an adminLimitExceeded status code. 5 - A server is allowed to unilaterally abort a transaction in order to avoid a deadlock condition. The fact that the transaction has been aborted is signaled to the client by means of the deadlockDetected error code. Clients using transactions MUST be designed to cope with this con- dition. 6 - Any replication mechanisms employed MUST observe the transaction semantics. For example, modifications made during an aborted transaction MUST NOT be propagated to other servers. 7 - If the client connection is closed for any reason, the server MUST abort all pending transactions on that connection. 9. Security Considerations Transactions themselves are not thought to carry any direct security implications because they do not permit access to information which would otherwise be inaccessible. However, transactions do provide ample potential for a client to consume excessive server resources. For this reason it is recommended that server implementers consider both adminis- trative limits to this resource consumption, and access control measures to limit the use of transactions to authorized entities. 10. References [LDAPv3] Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access Pro- tocol (v3)", Standards Track, December, 1997. Available as RFC2251. [Bradner97] Bradner, Scott, "Key Words for use in RFCs to Indicate Requirement Levels", Internet Draft, March, 1997. Available as RFC2119. Boreham, Kikuchi and Odaki [Page 6] RFC DRAFT April 1998 11. Author's Address David Boreham Netscape Communications Corp. 501 E. Middlefield Road Mountain View, CA 94043 USA dboreham@netscape.com +1 650 937-5206 Satoshi Kikuchi Hitachi Ltd. 292 Yoshida-cho, Totsuka-ku, Yokohama, 244 Japan s-kikuti@sdl.hitachi.co.jp +81 45 881-1241 Michiyasu Odaki Hitachi Ltd. TYG 11th Bldg. 16-1, Nakamachi 3-Chome, Atsugi-shi, 243 Japan odakim@soft.hitachi.co.jp +81 462 25-9360 Boreham, Kikuchi and Odaki [Page 7]