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]