[Date Prev][Date Next] [Chronological] [Thread] [Top]


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

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-

             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-

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

     Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access  Pro-
     tocol (v3)", Standards Track, December, 1997. Available as RFC2251.

     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
   +1 650 937-5206

   Satoshi Kikuchi
   Hitachi Ltd.
   292 Yoshida-cho, Totsuka-ku,
   Yokohama, 244
   +81 45 881-1241

   Michiyasu Odaki
   Hitachi Ltd.
   TYG 11th Bldg. 16-1, Nakamachi 3-Chome,
   Atsugi-shi, 243
   +81 462 25-9360

Boreham, Kikuchi and Odaki                                      [Page 7]