WDIFF

draft-ietf-ldup-lcup-00.txt --> draft-ietf-ldup-lcup-01.txt

Internet Draft R. Megginson, Editor
Document: <draft-ietf-ldup-lcup-00.txt> <draft-ietf-ldup-lcup-01.txt> M. Smith
Category: Proposed Standard Netscape
Communications Corp.
O. Natkovich
eTime Capital
J. Parham
Microsoft Corporation
May
June 2001

LDAP Client Update Protocol

Status of this Memo

This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026 [1].

Internet-Drafts are working documents 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."

The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-
Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.

1. Abstract

This document defines the LDAP Client Update Protocol (LCUP). The
protocol is intended to allow an LDAP client to synchronize with the
content of a directory information tree (DIT) stored by an LDAP
server and to be notified about the changes to that content.

2. Conventions used in this document

In the protocol flow definition, the notation C->S and S->C
specifies the direction of the data flow from the client to the
server and from the server to the client respectively.

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
[KEYWORDS].

3. Overview

The LCUP protocol is intended to allow LDAP clients to synchronize
with the content stored by LDAP servers.

The problem areas addressed by the protocol include:

- mobile clients that maintain a local read-only copy of the
directory data. While off-line, the client uses the local copy of
the data. When the client connects to the network, it
synchronizes with the current directory content and can be
optionally notified about the changes that occur while it is on-
line. For example, a mail client can maintain a local copy of the
corporate address book that it synchronizes with the master copy
whenever the client gets connected to the corporate network.

- applications intending to synchronize heterogeneous data stores.
A meta directory application, for instance, would periodically
retrieve a list of modified entries from the directory, construct
the changes and apply them to a foreign data store.

- clients that need to take certain actions when a directory entry
is modified. For instance, an electronic mail repository may want
to perform a "create mailbox" task when a new person entry is
added to an LDAP directory and a "delete mailbox" task when a
person entry is removed.

The problem areas not being considered:

- directory server to directory server synchronization. The
replication protocol that is being defined by the LDUP IETF
working group should be used for this purpose.

Several features of the protocol distinguish it from LDUP
replication. First, the server does not maintain any state
information on behalf of its clients. The clients are responsible
for storing the information about how up to date they are with
respect to the server's content. Second, no predefined agreements
exist between the clients and the servers. The client decides when
and from where to retrieve the changes. Finally, the server never
pushes the data to the client; the client always initiates the
update session during which it pulls the changes from the server.

The set of clients that are allowed to synchronize with an LDAP
server is determined by the server defined policy.

There are currently several protocols in use for LDAP client server
synchronization. While each protocol addresses the needs of a
particular group of clients (e.g., on-line clients or off-line
clients) none satisfies the requirements of all clients in the
target group. For instance, a mobile client that was off-line and
wants to become up to date with the server and stay up to date while
connected can't be easily supported by any of the existing
protocols.

Megginson, et. al. Proposed Standard - Expires: November 2001 2

A server can define a naming context or some part thereof to
participate in LCUP. This document will refer to this as an LCUP
Context. For example, LDUP defines a replica, a part of the DIT
which may participate in replication. The LCUP context may be
coincident with the replicated area, depending on the serverÆs server's
implementation. It is assumed that most server implementations of
LCUP will make use of the serverÆs server's underlying replication mechanism,
but this does not have to be LDUP compliant.

4. Protocol Specification

This section describes the protocol elements and the protocol flow.

4.1 Unique Identifiers

Distinguished names can change, so are therefore unreliable
as identifiers. A Unique Identifier must therefore be
assigned to each entry as it is created. This identifier
will be stored as an operational attribute of the entry,
named `entryUUID'. The entryUUID attribute is single valued.
A consistent algorithm for generating such unique
identifiers may be standardized at some point in the future.
The definition of the entryUUID attribute type, written using the
BNF form of AttributeDescription described in RFC 2252 [RFC2252] is:

( OID-To-Be-Specified
NAME 'entryUUID' `entryUUID'
DESC 'unique `unique entry identifier'
EQUALITY caseIgnoreMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
SINGLE-VALUE
NO-USER-MODIFICATION
USAGE directoryOperation )

4.2 LCUP Cookie Value

The LCUP protocol uses a cookie to hold the state of the client's
data with respect to the server's data. This value is the bytes of
the BER encoding of the following:

lcupCookie ::= SEQUENCE {
scheme LDAPOID,
value OCTET STRING OPTIONAL
}

scheme - this is the OID which identifies the format of the value.
The scheme OID, like all object identifiers, MUST be unique for a
given cookie scheme. The cookie value may be opaque or it may be
exposed to LCUP clients. For cookie schemes that expose their
value, the preferred form of documentation is an RFC. It is
expected that there will be one or more standards track cookie
schemes where the value format is exposed and described in detail.

Megginson, et. al. Proposed Standard - Expires: November 2001 3

value - this is the actual data describing the state of the
client's data. This value may be opaque, or its value may have
some well known format, depending on the scheme. The cookie value
MUST be included except when a client has no stored state; i.e.,
when the client is requesting a full synchronization. When the
server sends back a cookie, the cookie value MUST be present.

Further uses of the LCUP Cookie value are described below.

4.3 LCUP Cookie Schemes Operational Attribute

The OIDs of the supported LCUP cookie schemes SHOULD be published
using the following operational attribute:

( OID-TBD
NAME 'lcupCookieScheme'
EQUALITY objectIdentifierMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.38
NO-USER-MODIFICATION
USAGE directoryOperation )

The lcupCookieScheme operational attribute SHOULD be present in
every directory entry that may be used as the baseObject for a
search request that contains an LCUP clientUpdate control. If a
client wants to determine what LCUP cookie schemes are supported, it
SHOULD use a base object search to read the lcupCookieScheme
attribute from the entry that will be used as the baseObject in
subsequent LCUP sessions. Clients SHOULD NOT search for entries
that contain lcupCookieScheme values; rather, it is RECOMMENDED that
servers support LCUP sessions based at as many different entries as
possible.

4.4 Client Update Control Value

A client initiates a synchronization session with a server by
attaching a clientUpdate control to a search operation. The search
specification determines the part of the directory information tree
(DIT) the client wishes to synchronize with, the set of attributes
it is interested in and the amount of data the client is willing to
receive. The clientUpdate control contains the client's
synchronization specification. The controlType field for the
clientUpdate control is ClientUpdateControlOID (to be assigned).
The controlValue is an OCTET STRING, whose contents are the bytes of
the BER encoding of the following:

ClientUpdateControlValue ::= SEQUENCE {
updateType ENUMERATED {
synchronizeOnly (0),
synchronizeAndPersist (1),
persistOnly (2) },
cookie OCTET STRING lcupCookie OPTIONAL
}

Megginson, et. al. Proposed Standard - Expires: November 2001 3

updateType û - specifies the type of update requested by the client

Megginson, et. al. Proposed Standard - Expires: November 2001 4

synchronizeOnly û - the server sends all the data needed to
synchronize the client with the server, then closes the
connection

synchronizeAndPersist û - the server sends all the data needed to
synchronize the client with the server, then leaves open the
connection, sending to the client any new added, modified, or
deleted entries which satisfy the search criteria.

persistOnly û - the server does not synchronize the data with the
client but leaves open the connection and sends over any new
added, modified, or deleted entries which satisfy the search
criteria.

cookie - an opaque cookie a value that represents the current state of the client's
data. If a cookie is provided, the server MUST use the enclosed
scheme throughout the duration of the LCUP session or until an
LCUP context boundary is crossed, since a new cookie may be
required in that case. If the value or scheme part of the cookie
is invalid, the server MUST return immediately with a
SearchResultDone message with the clientUpdateDone control
attached with the reason set to the value of lcupInvalidCookie
(see below). Also, the LDAP result code MUST be
unwillingToPerform.

4.3 If the scheme part of the cookie is a valid
OID, but is not supported, the server MUST return immediately
with a SearchResultDone message with the clientUpdateDone control
attached with the reason set to the value of
lcupUnsupportedScheme (see below). Also, the LDAP result code
MUST be unwillingToPerform.

If the cookie is omitted, the server MAY use any scheme it
supports.

4.5 Entry Update Control Value

In response to the client's synchronization request, the server
returns one or more SearchResultEntry PDU that fits the clientÆs client's
specification. Each SearchResultEntry PDU also contains an
entryUpdateControl which describes the LCUP state of the returned
entry. To represent a deleted entry, the server attaches an
entryUpdate control to the corresponding SearchResultEntry. The
SearchResultEntry corresponding to a deleted entry MUST contain a
valid DN and a valid Unique Identifier but, to reduce the amount of
data sent to the client, it SHOULD not contain any other attributes.
Distinguished names can change, so are therefore unreliable as
identifiers. A Unique Identifier MUST therefore be assigned to each
entry as it is created. The Unique Identifier allows the client to
uniquely identify entries even in the presence of modrdn operations.
The Unique Identifier is carried in the entryUUID attribute.

Furthermore, the server may elect to periodically return to the
client the cookie that represents the state of the client's data.
This information is useful in case the client crashes or gets

Megginson, et. al. Proposed Standard - Expires: November 2001 5

disconnected. The cookie is also provided in the entryUpdate
control. The controlType field for the entryUpdate control is
EntryUpdateControlOID (to be assigned). The controlValue is an
OCTET STRING, whose contents are the bytes of the BER encoding of
the following:

EntryUpdateControlValue ::= SEQUENCE {
stateUpdate BOOLEAN,
entryDeleted BOOLEAN,
cookie OCTET STRING lcupCookie OPTIONAL

Megginson, et. al. Proposed Standard - Expires: November 2001 4

}

stateUpdate - if set to TRUE, indicates that the entry to which the
control is attached contains no changes and it is sent only to
communicate to the client the new cookie. In this case, the
entryDeleted field MUST be ignored and the cookie field MUST
contain the updated cookie. This feature allows updating the
client's cookie when there are no changes that effect the
client's data store. Note that the control MUST be attached to a
valid SearchResultEntry, i.e. the entry should contain a valid
dn. The server MAY send the entry at the root of the client's
tree.

entryDeleted - if set to TRUE, indicates that the entry to which
the control is attached was deleted. The server MAY also set
this to TRUE if the entry has left the clientÆs client's search result
set. As far as the client is concerned, a deleted entry is no
different than an entry which has left the result set.

cookie - an opaque the LCUP cookie value that represents the current state of
the client's data.

4.4

4.6 Client Update Done Control Value

When the server has finished processing the client's request, it
attaches a clientUpdateDone control to the SearchResultDone message
and sends it to the client. The controlType field for the
clientUpdateDone control is ClientUpdateDoneControlOID (to be
assigned). The controlValue is an OCTET STRING, whose contents are
the bytes of the BER encoding of the following:

ClientUpdateDoneControlValue ::= SEQUENCE {
reason INTEGER,
reasonText LDAPString,
cookie OCTET STRING lcupCookie
}

reason - reason for terminating the operation. Currently supported
values are

lcupSuccess (0) the operation was successfully
processed
lcupResourcesExhausted (1) the server is running out of resource

Megginson, et. al. Proposed Standard - Expires: November 2001 6

lcupSecurityViolation (2) the client is suspected of malicious
actions
lcupInvalidCookie (3) invalid cookie was supplied by the
client
lcupClientDisconnect - both/either the scheme
and/or the value part was invalid
lcupUnsupportedScheme (4) The scheme part of the cookie is a
valid OID but is not supported by
this server
lcupClientDisconnect (5) client requested search termination
lcupReloadRequired (5) (6) indicates that client data needs to
be reinitialized. This reason is
returned if the server does not
contain sufficient information to
synchronize the client or that the

Megginson, et. al. Proposed Standard - Expires: November 2001 5
server's data was reloaded since the
last synchronization session

reasonText - The reasonText field of this construct may, at the
server's option, be used to return a string containing a textual,
human-readable (terminal control and page formatting characters
should be avoided) error diagnostic. As this error diagnostic is
not standardized, implementations MUST NOT rely on the values
returned. If the server chooses not to return a textual
diagnostic, the reasonText field of the
ClientUpdateDoneControlValue MUST contain a zero length string.
The character set for reasonText SHOULD be US-ASCII.

cookie - an opaque the LCUP cookie value that represents the current state of
the client's data. Although this value is OPTIONAL in other
control values, it MUST be set in the ClientUpdateDoneControlValue.
This provides a good ôchecksumö "checksum" of what the server thinks the state
of the client is.

4.5

4.7 Stop Client Update Request and Response

The Stop Client Update operation is an LDAPv3 Extended Operation
[RFC2251, Section 4.12] and is identified by the OBJECT IDENTIFIER
stopClientUpdateOID (to be assigned). This section details the
syntax of the protocol.

An LDAPv3 Extended Request is defined in [LDAPv3] as follows:

ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
requestName [0] LDAPOID,
requestValue [1] OCTET STRING OPTIONAL
}

If the client needs to terminate the synchronization process and it
wishes to obtain the cookie that represents the current state of its
data, it issues a stopClientUpdateRequest extended operation. The
operation carries the following data. The extended operation
requestValue is an OCTET STRING, whose contents are the bytes of the
BER encoding of the following:

Megginson, et. al. Proposed Standard - Expires: November 2001 7

StopClientUpdateRequestValue ::= INTEGER

StopClientUpdateRequestValue - the message ID of the search that
included the original clientUpdate control

The server responds immediately with a stopClientUpdateResponse
extended operation that carries no data. The server MAY send any
pending SearchResultEntry PDUs if the server cannot easily abort or
remove those search results from its outgoing queue. The server
SHOULD send as few of these remaining SearchResultEntry PDUs as
possible. Finally, the server sends the message SearchResultDone
with the clientUpdateDone control attached. The value of the reason
in the clientUpdateDone control value MUST be either an error code
(some value other than lcupSuccess) or lcupClientDisconnect. The

Megginson, et. al. Proposed Standard - Expires: November 2001 6
stopClientUpdateResponse is sent only to satisfy LDAP requirement
that every server must issue an extended response for each extended
request it receives.

If the client is not interested in the state information, it can
simply abandon the search operation or disconnect from the server.

If server resources become tight, the server can terminate one or
more search operations by sending a SearchResultDone message to the
client(s). Unless the client sets the updateType field to
persistOnly, the server attaches a clientUpdateDone control that
contains the cookie that corresponds to the current state of the
client's data and the value of the reason field is set to
lcupResourcesExhausted. A server set policy is used to decide which
searches to terminate. This can also be used as a security mechanism
to disconnect clients that are suspected of malicious actions, but
if the server can infer that the client is malicious, the server
should return lcupSecurityViolation in the reason field of the
response.

The stopClientUpdate extended operation indicates that the initiator
wishes to terminate the current update operation.

The requestName portion of the stopClientUpdate must be the
OID stopClientUpdateOID <TO BE DETERMINED>. The requestValue is the
message ID corresponding to the clientÆs client's search request. If the
message ID is not valid, the server MUST send back to the client an
LDAP error code of unwillingToPerform.

4.6

4.8 Protocol Flow

The client server interaction can proceed in three different ways
depending on the client's requirements. Protocol flows beginning
with an asterisk (*) are optional or conditional.

If the client's intent is not to synchronize data but to trigger
actions in response to directory modifications, the protocol
proceeds as follows:

C->S Sends a search operation with a clientUpdate control attached.

Megginson, et. al. Proposed Standard - Expires: November 2001 8

The search specification determines the part of the DIT the
client wishes to synchronize with and the set of attributes it
is interested in. The updateType field of the control value
should be set to persistOnly.
*S->C If there is an error (invalid search scope, invalid cookie)
the server returns the appropriate error codes and terminates
the request (SearchResultDone message with clientUpdateDone
control)
S->C Sends change notification to the client for each change to the
data within the client's search specification. Each
SearchResultEntry may have an entryUpdate control attached.
*S->C If the server starts to run out of resources or the client is
suspected of malicious actions, the server SHOULD terminate
the search operation by sending to the client a

Megginson, et. al. Proposed Standard - Expires: November 2001 7
SearchResultDone message with clientUpdateDone control
attached. The control contains the reason field set to
lcupResourcesExhausted or lcupSecurityViolation depending on
the reason for termination. The server MAY provide more
details to the client via the reasonText field of the control.
*C->S If the client receives lcupResourcesExhausted error from the
server, it MUST wait for a while before attempting another
synchronization session with the server. It is RECOMMENDED
that clients use an exponential backoff strategy.
C->S The client terminates the search. The client can do this by
abandoning the search operation, disconnecting from the
server, or by sending the stopClientUpdate extended operation.
*S->C If the server receives the stopClientUpdate extended op, it
will immediately send back the stopClientUpdate extended op
response
*S->C If the client sent the stopClientUpdate extended op, the
server MAY send any pending SearchResultEntry PDUs in its
outgoing queue
*S->C If the client sent the stopClientUpdate extended op, after the
server sends the response and any pending SearchResultEntry
PDUs, the server sends the SearchResultDone message with the
clientUpdateDone control attached. The value of the reason
field of the clientUpdateDone control value will be either
lcupClientDisconnect or some lcup error code (not
lcupSuccess).
S->C Stops sending changes to the client and closes the connection.

If the client's intent is to synchronize with the server and then
disconnect, the protocol proceeds as follows:

C->S Sends a search operation with the clientUpdate control
attached. The search specification determines the part of the
DIT the client wishes to synchronize with, the set of
attributes it is interested in and the amount of data the
client is willing to receive. If this is the initial
synchronization session, the client either does not provide a cookie;
cookie or provides a cookie with no value; otherwise, the
cookie field of the control is set to the cookie received from
the server at the end of the last synchronization session. If
the scheme field of the cookie was provided, the server MUST

Megginson, et. al. Proposed Standard - Expires: November 2001 9

use that scheme throughout the duration of the LCUP session or
until an LCUP boundary is crossed, since the server will
usually require a different cookie in that case anyway. (Note
that the client can synchronize with different servers during
different synchronization sessions.) The updateType field of
the control value is set to synchronizeOnly.
*S->C If there is an error (invalid search scope, invalid cookie)
the server returns the appropriate error codes and terminates
the request (SearchResultDone message with clientUpdateDone
control)
*S->C If no cookie is specified in the clientUpdate control, or if
the value field of the cookie is empty, the server sends all
data that matches the client's search specification followed
by the SearchResultDone message with a clientUpdateDone
control attached. The control contains the cookie that
corresponds to the current state of the client's data and the
reason flag set to lcupSuccess.
*S->C If an invalid cookie is specified, the server sends the
SearchResultDone message with clientUpdateDone control

Megginson, et. al. Proposed Standard - Expires: November 2001 8
attached. The reason field of the control is set to
lcupInvalidCookie and the reasonText field MAY contain
explanation of the error.
*S->C If a valid cookie is specified and the data that matches the
search specification has been reloaded or the server does not
contain enough state information to synchronize the client,
the server sends a SearchResultDone message with
clientUpdateDone control attached. The reason field of the
control is set to lcupReloadRequired and the reasonText field
MAY contain explanation of the error.
*S->C If the cookie is valid and the client is up to date, the
server sends a success response to the client.
S->C If the cookie is valid and there is data to be sent, the
server sends the modified entries to the client. Each
SearchResultEntry contains the attributes requested by the
client in the search specification regardless of whether they
were modified. An entryUpdate control with the entryDeleted
field set to TRUE MUST be attached to every deleted entry. The
server may also periodically attach an entryUpdate control to
the entries sent to the client to indicate the current state
of the client's data. In that case, the cookie field of the
control represents the state of the client's data including
the entry to which the control is attached. Once all the
changes are sent, the server sends a SearchResultDone with the
clientUpdateDone control attached. The control contains the
cookie that represents the current state of the client's data.
The reason field of the control is set to lcupSuccess.
The client stores the cookie received from the server until
the next synchronization session.
*C->S If the reason field of the control is set lcupReloadRequired,
the client clears its data store and repeats the
synchronization process by sending the search operation with
clientUpdate control that contains no cookie. cookie, or that contains
a cookie with no value field.

Megginson, et. al. Proposed Standard - Expires: November 2001 10

If the client's intent is to be synchronized with the server and
stay notified about data modifications, the protocol proceeds as
follows:

C->S The client behaves exactly as in the previous case except it
sets the updateType field in the control value to
synchronizeAndPersist.
S->C The server behaves exactly as in the previous case except the
connection is kept open after the initial set of changes is
sent to the client. A SearchResultDone message is not sent to
the client; instead, the server keeps sending changes to the
client.
*S->C If the server starts to run out of resources or the client is
suspected of malicious actions, the server SHOULD terminate
the search operation by sending to the client a
SearchResultDone message with clientUpdateDone control
attached. The control contains the reason field set to
lcupResourcesExhausted or lcupSecurityViolation depending on
the reason for termination. The server MAY provide more
details to the client via the reasonText field of the control.

Megginson, et. al. Proposed Standard - Expires: November 2001 9
*C->S If the client receives lcupResourcesExhausted error from the
server, it MUST wait for a while before attempting another
synchronization session with the server. We recommend
exponential backoff strategy.
C->S Sends a stopClientUpdateRequest extended operation to the
server to terminate the synchronization session.
S->C Responds with a stopClientUpdateResponse extended operation
followed by a SearchResultDone with the clientUpdateDone
control attached. The control contains the cookie that
represents the current state of the client's data. The value
of the reason field of the clientUpdateDone control value will
be either lcupClientDisconnect or some lcup error code (not
lcupSuccess).

4.7

4.9 Size and Time Limits

The search request size or the time limits can only be imposed for
non-persistent operations, those that set the updateType field of
the ClientUpdateControlValue to synchronizeOnly (for the entire
operation) or synchronizeAndPersist (for the initial synchronization
phase only). All other operations MUST set both limits to 0. The
server SHOULD ignore the limits set for persistent operations.

4.8

4.10 Changes vs. Operations

Since the server sends to the client the modified entries rather
than the operations, a MODDN operation performed on a subtree will
be seen by the client as a sequence of added or modified entries
depending on whether the operation moved the entries into the scope
of the client's search specification.

4.9

4.11 Operations on the Same Connection

Megginson, et. al. Proposed Standard - Expires: November 2001 11

It is permissible for the client to issue other LDAP operations on
the connection used by the protocol. Since each LDAP
request/response carries a message id there will be no ambiguity
about which PDU belongs to which operation. By sharing the
connection among multiple operations, the server will be able to
conserve its resources.

5. Additional Features

There are several features present in other protocols or considered
useful by clients that are currently not included in the protocol
primarily because they are difficult to implement on the server.
These features are briefly discussed in this section. This section
is intended to open a discussion on the merits of including and
approaches to implementing these features.

5.1 Change Type

This feature is present in the Triggered Search specification. A
flag is attached to each entry returned to the client indicating the

Megginson, et. al. Proposed Standard - Expires: November 2001 10
reason why this entry is returned. The possible reasons from the
draft are
"- notChange: the entry existed in the directory and matched the
search at the time the operation is being performed,
- enteredSet: the entry entered the result,
- leftSet: the entry left the result,
- modified: the entry was part of the result set, was modified or
renamed, and still is in the result set."

The leftSet feature is particularly useful because it indicates to
the client that an entry is no longer within the client's search
specification and the client can remove the associated data from its
data store. Ironically, this feature is the hardest to implement on
the server because the server does not keep track of the client's
state and has no easy way of telling which entries moved out of
scope between synchronization sessions with the client.

A compromise could be reached by only providing this feature for the
operations that occur while the client is connected to the server.
This is easier to accomplish because the decision about the change
type can be made based only on the change without need for any
historical information. This, however, would add complexity to the
protocol.

5.2 Sending Changes

Some earlier synchronization protocols sent the client(s) only the
modified attributes of the entry rather than the entire entry. While
this approach can significantly reduce the amount of data returned
to the client, it has several disadvantages. First, unless a
separate mechanism (like the change type described above) is used to
notify the client about entries moving into the search scope,
sending only the changes can result in the client having an
incomplete version of the data. Let's consider an example. An

Megginson, et. al. Proposed Standard - Expires: November 2001 12

attribute of an entry is modified. As a result of the change, the
entry enters the scope of the client's search. If only the changes
are sent, the client would never see the initial data of the entry.
Second, this feature is hard to implement since the server might not
contain sufficient information to construct the changes based solely
on the server's state and the client's cookie. On the other hand,
this feature can be easily implemented by the client assuming that
the client has the previous version of the data and can perform
value by value comparisons.

5.3 Data Size Limits

Some earlier synchronization protocols allowed clients to control
the amount of data sent to them in the search response. This feature
was intended to allow clients with limited resources to process
synchronization data in batches. However, an LDAP search operation
already provides the means for the client to specify the size limit
by setting the sizeLimit field in the SearchRequest to the maximum
number of entries the client is willing to receive. While the
granularity is not the same, the assumption is that LCUP protocol

Megginson, et. al. Proposed Standard - Expires: November 2001 11
will be implemented by regular LDAP clients that can deal with the
limitations of the LDAP protocol.

5.4 Data Ordering

Some earlier synchronization protocols allowed a client to specify
that parent entries should be sent before the children for add
operations and children entries sent before their parents during
delete operations. This ordering helps clients to maintain a
hierarchical view of the data in their data store. While possibly
useful, this feature is relatively hard to implement and is
expensive to perform.

Comments from M. Armijo: " Although I appreciate the difficulty in
implementing this, I believe we need to at least make it an option.
If we do not, we will need to define how clients handle issues where
changes are received out of order (stub entries, etc.) At the very
least we should define that the server must not return a cookie
until all parents involved in a series of operations have been
returned (does that make sense or should I reword it?). I am
concerned that a client can disconnect and be in what it considers
to be a 'valid' state while it's own DIT is no longer valid."

6. Client Side Considerations

There are several issues that the implementors of a synchronization
client need to consider:

- The cookie received from the server after a synchronization
session can only be used with the same or more restrictive search
specification than the search that generated the cookie. The
server will reject the search operation with a cookie that does
not satisfy this condition. This is because the client can end up
with an incomplete data store otherwise. A more restrictive

Megginson, et. al. Proposed Standard - Expires: November 2001 13

search specification is the one that generates a subset of the
data produced by the original search specification.

- Because an LCUP client specifies the area of the tree with which
it wishes to synchronize through the standard LDAP search
specification, the client can be returned noSuchObject error if
the root of the synchronization area was renamed between the
synchronization sessions. If this condition occurs, the client
can attempt to locate the root by using the root's Unique
Identifier saved in client's local data store. It then can repeat
the synchronization request using the new search base. In
general, a client can detect that an entry was renamed and apply
the changes received to the right entry by using the Unique
Identifier rather then DN based addressing.

- Each active persistent operation requires that an open TCP
connection be maintained between an LDAP client and an LDAP
server that might not otherwise be kept open. Therefore, client
implementors are encouraged to avoid using persistent operations
for non-essential tasks and to close idle LDAP connections as

Megginson, et. al. Proposed Standard - Expires: November 2001 12 LDAP connections as
soon as practical. The server may close connections if server
resources become tight.

- The client MAY receive a continuation reference
(SearchResultReference [RFC2251 SECTION 4.5.3]) if the search
request spans multiple parts of the DIT, some of which may
require a different LCUP cookie, some of which may not even be
managed by LCUP. The client SHOULD maintain a cache of the LDAP
URLs returned in the continuation references and the cookies
associated with them. The client is responsible for performing
another LCUP search to follow the references, and SHOULD use the
cookie corresponding to the LDAP URL for that reference (if it
has a cookie).

- Changes to meta-data in the server may affect the presence of
entries in the search set. Servers MAY notify LCUP clients of
changes to the search set that result from changes to meta-data
such as access control rules. But an LCUP client MUST NOT assume
that such notification will occur. Therefore, in the case where
a client is maintaining a cache of entries using LCUP, the data
held by the client may be a superset or a subset of the entries
that would be returned by a new search request. For example, if
access control meta information is changed to deny access to
particular entries in the search result set, and the access
control information is outside of the search scope (e.g., in a
parent entry), the client may have entries stored locally which
are no longer part of its desired search set. Similarly, if
entries are added to the search result set due to changes in
meta-data, the client's cache of entries may not include these
entries.

7. Server Implementation Considerations

Megginson, et. al. Proposed Standard - Expires: November 2001 14

By design, the protocol does not specify the format of the cookie. supports multiple cookie schemes. This is
to allow different implementations the flexibility of storing any
information applicable to their environment. A reasonable
implementation for an LDUP compliant server would be to use the
Replica Update Vector (RUV). For each master, RUV contains the
largest CSN seen from this master. In addition, the RUV implemented
by some directory servers (not yet in LDUP) contains replica
generation - an opaque string that identifies the replica's data
store. The replica generation value changes whenever the replica's
data is reloaded. Replica generation is intended to signal the
replication/synchronization peers that the replica's data was
reloaded and that all other replicas need to be reinitialized. RUV
satisfies the three most important properties of the cookie: (1) it
uniquely identifies the state of client's data, (2) it can be used
to synchronize with multiple servers, and (3) it can be used to
detect that the server's data was reloaded.

A server may support one or more LCUP cookie schemes. It is
expected that schemes will be published along with their OIDs as
RFCs. If a client initiates an LCUP session with a particular
scheme, the server MUST use that same scheme throughout the LCUP
session, or until an LCUP context boundary is crossed, in which case
the server will usually require a different cookie anyway.

In addition, the cookie must contain enough information to allow the
server to determine whether the cookie can be safely used with the
search specification it is attached to. As discussed earlier in the
document, the cookie can only be used with the search specification

Megginson, et. al. Proposed Standard - Expires: November 2001 13
that is equally or more restrictive than the one for which the
cookie was generated.

An implementation must make sure that it can correctly update the
client's cookie when there is a size limit imposed on the search
results by either the client's request or by the server's
configuration. If RUV is used as the cookie, entries last modified
by a particular master must be sent to the client in the order of
their last modified CSN. This ordering guarantees that the RUV can
be updated after each entry is sent.

The serverÆs server's DIT may be partitioned into different sections which
may have different cookies associated with them. For example, some
servers may use some sort of replication mechanism to support LCUP.
If so, the DIT may be partitioned into multiple replicas. A client
may send an LCUP search request that spans multiple replicas. Some
parts of the DIT spanned by the search request scope may be managed
by LCUP and some may not. A part of the DIT which is enabled for
LCUP is referred to as an LCUP Context. The server SHOULD send a
SearchResultReference [RFC2251, SECTION 4.5.3] when the LCUP Context
for a returned entry changes. The server SHOULD return all entries
for a particular LCUP Context before returning a reference to other
LCUP Contexts or non LCUP enabled parts of the DIT, in order to
minimize the processing burden on the clients. The LDAP URL(s)
returned MUST contain the DN(s) of the base of another section of
the DIT (however the server implementation has partitioned the DIT).

Megginson, et. al. Proposed Standard - Expires: November 2001 15

The client will then issue another LCUP search using the LDAP URL
returned. Each section of the DIT MAY require a different cookie
value, so the client SHOULD maintain a cache, mapping the different
LDAP URL values to different cookies. If the cookie changes, the
scheme may change as well, but the cookie scheme MUST be the same
within a given LCUP Context.

An implementation must be able to notify the client about all
entries deleted since the last implementation session. An LDUP
compliant implementation can achieve this through the use of entry
tombstones. The implementation should avoid aggressive tombstone
purging since lack of tombstones would cause client's data to be
reloaded. We suggest that only the tombstone content be removed
during the regular trimming cycle while tombstones themselves are
discarded much less frequently.

The specification makes no guarantees about how soon a server should
send notification of a changed entry to the client when the
connection between the client and the server is kept open. This is
intentional as any specific maximum delay would be impossible to
meet in a distributed directory service implementation. Server
implementors are encouraged to minimize the delay before sending
notifications to ensure that clients' needs for timeliness of change
notification are met.

Implementors of servers that support the mechanism described in this
document should ensure that their implementation scales well as the
number of active persistent operations and the number of changes
made in the directory increases. Server implementors are also

Megginson, et. al. Proposed Standard - Expires: November 2001 14
encouraged to support a large number of client connections if they
need to support large numbers of persistent operations.

8. Synchronizing Heterogeneous Data Stores

Clients, like a meta directory join engine, synchronizing multiple
writable data stores will only work correctly if each piece of
information is single mastered (for instance, only by an LDUP
compliant directory). This is because different systems have
different notions of time and different update resolution
procedures. As a result, a change applied on one system can be
discarded by the other, thus preventing the data stores from
converging.

9. Security Considerations

In some situations, it may be important to prevent general exposure
of information about changes that occur in an LDAP server.
Therefore, servers that implement the mechanism described in this
document SHOULD provide a means to enforce access control on the
entries returned and MAY also provide specific access control
mechanisms to control the use of the controls and extended
operations defined in this document.

Megginson, et. al. Proposed Standard - Expires: November 2001 16

As with normal LDAP search requests, a malicious client can initiate
a large number of persistent search requests in an attempt to
consume all available server resources and deny service to
legitimate clients. The protocol provides the means to stop
malicious clients by disconnecting them from the server. The servers
that implement the mechanism SHOULD provide the means to detect the
malicious clients. In addition, the servers SHOULD provide the means
to limit the number of resources that can be consumed by a single
client.

Access control on the data can be modified in such a way that the
data is no longer visible to the client. The specification does not
specify how the server should handle this condition. Moreover, data
consistency is not guaranteed if access control is changed from a
more restrictive to a less restrictive one. This is because access
control can be considered as an additional filter on the search
specification and the protocol does not support going from a more to
a less restrictive search specification. See Client Side
Considerations Section for more detailed explanation of the problem.

10. References

[KEYWORDS] S. Bradner, "Keywords for use in RFCs to Indicate
Requirement Levels", RFC 2119, March 1997.

[RFC2251] M. Wahl, T. Howes, S. Kille "Lightweight Directory
Access Protocol", RFC 2251, December 1997.

Megginson, et. al. Proposed Standard - Expires: November 2001 15

[RFC2252] M. Wahl, A. Coulbeck, T. Howes, S. Kille, ôLightweight "Lightweight
Directory Access Protocol (v3): Attribute Syntax
Definitionsö,
Definitions", RFC 2252, December 1997.

11. Acknowledgements

The LCUP protocol is based in part on the Persistent Search Change
Notification Mechanism defined by Mark Smith, Gordon Good, Tim
Howes, and Rob Weltman, the LDAPv3 Triggered Search Control defined
by Mark Wahl, and the LDAP Control for Directory Synchronization
defined by Michael Armijo.

12. Author's Addresses

Rich Megginson
Netscape Communications Corp.
901 San Antonio Rd.
Palo Alto, CA 94303-4900
Mail Stop SCA17 - 201
Phone: +1 408 276-3752
Email: richm@netscape.com

Olga Natkovich
eTime Capital, Inc.
1154 E Arques Ave.
Sunnyvale, CA 94085

Megginson, et. al. Proposed Standard - Expires: November 2001 17

Phone: +1 408 830-2029
Email: olga@etimecapital.com

Mark Smith
Netscape Communications Corp.
901 San Antonio Rd.
Palo Alto, CA 94303-4900
Mail Stop SCA17 - 201
Phone: +1 650 937-3477
Email: mcs@netscape.com

Jeff Parham
Microsoft Corporation
One Microsoft Way
Redmond, WA 98052-6399
Phone: +1 425 882-8080
Email: jeffparh@microsoft.com

13. Full Copyright Statement
"Copyright (C) The Internet Society (date). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph
are included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other

Megginson, et. al. Proposed Standard - Expires: November 2001 16
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.

The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.

This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

14. Appendix A - Summary of Changes

Changes new to version 01:

The opaque cookie has been split into two parts - a scheme which
is an OID, and a value. The value may or may not have a format
known to the client, depending on the specified scheme. Section
4.2 describes the new cookie format and defines the LCUP Cookie
Value.

Megginson, et. al. Proposed Standard - Expires: November 2001 18

Added new section 4.3 - the lcupCookieSchemes operational
attribute.

Changes new to version 00:

Added the definition for Unique Identifier (basically copied from
the LDUP model doc http://search.ietf.org/internet-drafts/draft-
ietf-ldup-model-06.txt. I needed to add the definition here
because LCUP needs a Unique Identifier but should not be dependent
on LDUP.

Removed all normative references to LDUP. IÆve I've left the
implementation suggestions that refer to LDUP, but LCUP should not
be dependent on LDUP.

Cleaned up the protocol flows.

Removed this text from section 4.8: ôClients "Clients MUST NOT issue
multiple synchronization requests on the same connection. This is
because the protocol includes an extended operation and it would
be impossible to decide which synchronization session it belongs
to.ö û
to." - This is no longer true, since the extended operation now
includes the message ID of the search request.

ôClient

"Client Side Considerationö Consideration" section û - the client will never
receive a referral or continuation reference

Added section 12. Acknowledgements

Removed normative references to documents not depended on.

Removed explicit references to software vendors.

Section 4.1 - Changed ClientUpdateControlValue to remove the
keepConnection and changesOnly fields and replace them with
updateType which is an ENUMERATED with three values:
synchronizeOnly, synchronizeAndPersist, and persistOnly.

Megginson, et. al. Proposed Standard - Expires: November 2001 17

Section 4.2 - The EntryUpdateControlValue fields stateUpdate and
entryDeleted no longer have DEFAULT values, they must be specified
û
- this eliminates any potential ambiguity.

Added this text to the description of the entryDeleted field
(section 4.2): ôThe "The server SHOULD also set this to TRUE if the
entry has left the clients search result set. As far as the client
is concerned, a deleted entry is no different than an entry which
has left the result set.ö set."
Section 4.2 - Added an explanation of the concept and requirement
for the Unique Identifier.

Section 4.4 û - Added to the extended operation a request value
containing the message id of the operation to stop.

Updated contact information for Olga.

Megginson, et. al. Proposed Standard - Expires: November 2001 19

Removed Michael Armijo and added Jeff Parham as an author.

Changes new to previous version:

ôAuthorsö

"Authors" section - added Rich Megginson as the new editor.

ôClient

"Client Side Considerationö Consideration" section û - added a note and a question
concerning referral and continuation reference handling.

ôClient

"Client Update Control Valueö Value" section (4.1) - clarified the meaning
of keepConnection and added a table summarizing the effects of
different values of keepConnection and changesOnly.

ôStop

"Stop Client Update Request and Responseö û Response" - added section 4.4
describing this extended operation.

Megginson, et. al. Proposed Standard - Expires: November 2001 18 20

----