Request for Comments: 3928 Netscape Communications Corp.
Category: Standards Track M. Smith
Pearl Crescent, LLC
O. Natkovich
Yahoo
J. Parham
Microsoft Corporation
October 2004
Lightweight Directory Access Protocol (LDAP)
Client Update Protocol (LCUP)
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2004).
Abstract
This document defines the Lightweight Directory Access Protocol
(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.
Table of Contents
1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Applicability. . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Specification of Protocol Elements . . . . . . . . . . . . . . 5
3.1. ASN.1 Considerations . . . . . . . . . . . . . . . . . . 5
3.2. Universally Unique Identifiers . . . . . . . . . . . . . 5
3.3. LCUP Scheme and LCUP Cookie. . . . . . . . . . . . . . . 5
3.4. LCUP Context . . . . . . . . . . . . . . . . . . . . . . 6
3.5. Additional LDAP Result Codes defined by LCUP . . . . . . 6
3.6. Sync Request Control . . . . . . . . . . . . . . . . . . 7
3.7. Sync Update Control. . . . . . . . . . . . . . . . . . . 7
3.8. Sync Done Control. . . . . . . . . . . . . . . . . . . . 8
4. Protocol Usage and Flow. . . . . . . . . . . . . . . . . . . . 8
4.1. LCUP Search Requests . . . . . . . . . . . . . . . . . . 8
4.1.1. Initial Synchronization and Full Resync . . . . . 9
4.1.2. Incremental or Update Synchronization . . . . . . 10
4.1.3. Persistent Only . . . . . . . . . . . . . . . . . 10
4.2. LCUP Search Responses. . . . . . . . . . . . . . . . . . 10
4.2.1. Sync Update Informational Responses . . . . . . . 11
4.2.2. Cookie Return Frequency . . . . . . . . . . . . . 11
4.2.3. Definition of an Entry That Has Entered the
Result Set. . . . . . . . . . . . . . . . . . . . 12
4.2.4. Definition of an Entry That Has Changed . . . . . 13
4.2.5. Definition of an Entry That Has Left the
Result Set. . . . . . . . . . . . . . . . . . . . 13
4.2.6. Results For Entries Present in the Result Set . . 14
4.2.7. Results For Entries That Have Left the Result
Set . . . . . . . . . . . . . . . . . . . . . . . 14
4.3. Responses Requiring Special Consideration . . . . . . . . 15
4.3.1. Returning Results During the Persistent Phase . . 15
4.3.2. No Mixing of Sync Phase with Persist Phase. . . . 16
4.3.3. Returning Updated Results During the Sync Phase . 16
4.3.4. Operational Attributes and Administrative
Entries . . . . . . . . . . . . . . . . . . . . . 16
4.3.5. Virtual Attributes. . . . . . . . . . . . . . . . 17
4.3.6. Modify DN and Delete Operations Applied to
Subtrees. . . . . . . . . . . . . . . . . . . . . 17
4.3.7. Convergence Guarantees. . . . . . . . . . . . . . 18
4.4. LCUP Search Termination. . . . . . . . . . . . . . . . . 18
4.4.1. Server Initiated Termination. . . . . . . . . . . 18
4.4.2. Client Initiated Termination. . . . . . . . . . . 19
4.5. Size and Time Limits . . . . . . . . . . . . . . . . . . 19
4.6. Operations on the Same Connection. . . . . . . . . . . . 19
4.7. Interactions with Other Controls . . . . . . . . . . . . 19
4.8. Replication Considerations . . . . . . . . . . . . . . . 20
5. Client Side Considerations . . . . . . . . . . . . . . . . . . 20
5.1. Using Cookies with Different Search Criteria . . . . . . 20
5.2. Renaming the Base Object . . . . . . . . . . . . . . . . 20
5.3. Use of Persistent Searches With Respect to Resources . . 21
5.4. Continuation References to Other LCUP Contexts . . . . . 21
5.5. Referral Handling. . . . . . . . . . . . . . . . . . . . 21
5.6. Multiple Copies of Same Entry During Sync Phase. . . . . 21
5.7. Handling Server Out of Resources Condition . . . . . . . 21
6. Server Implementation Considerations . . . . . . . . . . . . . 22
6.1. Server Support for UUIDs . . . . . . . . . . . . . . . . 22
6.2. Example of Using an RUV as the Cookie Value. . . . . . . 22
6.3. Cookie Support Issues. . . . . . . . . . . . . . . . . . 22
6.3.1. Support for Multiple Cookie Schemes . . . . . . . 22
6.3.2. Information Contained in the Cookie . . . . . . . 23
6.4. Persist Phase Response Time. . . . . . . . . . . . . . . 23
6.5. Scaling Considerations . . . . . . . . . . . . . . . . . 23
6.6. Alias Dereferencing. . . . . . . . . . . . . . . . . . . 24
7. Synchronizing Heterogeneous Data Stores. . . . . . . . . . . . 24
8. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 24
9. Security Considerations. . . . . . . . . . . . . . . . . . . . 24
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25
10.1. Normative References . . . . . . . . . . . . . . . . . . 25
10.2. Informative References . . . . . . . . . . . . . . . . . 26
11. Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . . 26
Appendix - Features Left Out of LCUP . . . . . . . . . . . . . . . 27
Authors’ Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29
Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 30
1. 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 optionally
receive notification 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 is 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 IETF is
developing a LDAP replication protocol, called LDUP [RFC3384],
which is specifically designed to address this problem area.
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.
LCUP is designed such that the server does not need to maintain state
information specific to individual clients. The server may need to
maintain additional state information about attribute modifications,
deleted entries, and moved/renamed entries. The clients are
responsible for storing the information about how up to date they are
with respect to the server’s content. LCUP design avoids the need
for LCUP-specific update agreements to be made between client and
server prior to LCUP use. The client decides when and from where to
retrieve the changes. LCUP design requires clients to initiate the
update session and "pull" the changes from server.
LCUP operations are subject to administrative and access control
policies enforced by the server.
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 BCP 14, RFC 2119
[RFC2119].
2. Applicability
LCUP will work best if the following conditions are met:
1) The server stores some degree of historical state or change
information to reduce the amount of wire traffic required for
incremental synchronizations. The optimal balance between server
state and wire traffic varies amongst implementations and usage
scenarios, and is therefore left in the hands of implementers.
2) The client cannot be assumed to understand the physical
information model (virtual attributes, operational attributes,
subentries, etc.) implemented by the server. Optimizations would
be possible if such assumptions could be made.
3) Meta data changes and renames and deletions of large subtrees are
very infrequent. LCUP makes these assumptions in order to reduce
client complexity required to deal with these special operations,
though when they do occur they may result in a large number of
incremental update messages or a full resync.
3. Specification of Protocol Elements
The following sections define the new elements required to use this
protocol.
3.1. ASN.1 Considerations
Protocol elements are described using ASN.1 [X.680]. The term "BER-
encoded" means the element is to be encoded using the Basic Encoding
Rules [X.690] under the restrictions detailed in Section 5.1 of
[RFC2251]. All ASN.1 in this document uses implicit tags.
3.2. Universally Unique Identifiers
Distinguished names can change, so are therefore unreliable as
identifiers. A Universally Unique Identifier (or UUID for short)
MUST be used to uniquely identify entries used with LCUP. The UUID
is part of the Sync Update control value (see below) returned with
each search result. The server SHOULD provide the UUID as a single
valued operational attribute of the entry (e.g., "entryUUID"). We
RECOMMEND that the server provides a way to do efficient (i.e.,
indexed) searches for values of UUID, e.g., by using a search filter
like (entryUUID=<some UUID value>) to quickly search for and retrieve
an entry based on its UUID. Servers SHOULD use a UUID format as
specified in [UUID]. The UUID used by LCUP is a value of the
following ASN.1 type:
LCUPUUID ::= OCTET STRING
3.3. LCUP Scheme and LCUP Cookie
The LCUP protocol uses a cookie to hold the state of the client’s
data with respect to the server’s data. Each cookie format is
uniquely identified by its scheme. The LCUP Scheme is a value of the
following ASN.1 type:
LCUPScheme ::= LDAPOID
This is the OID which identifies the format of the LCUP Cookie value.
The scheme OID, as 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.
The LCUP Cookie is a value of the following ASN.1 type:
LCUPCookie ::= OCTET STRING
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.
Further uses of the LCUP Cookie value are described below.
3.4. LCUP Context
A part of the DIT which is enabled for LCUP is referred to as an LCUP
Context. A server may support one or more LCUP Contexts. For
example, a server with two naming contexts may support LCUP in one
naming context but not the other, or support different LCUP cookie
schemes in each naming context. Each LCUP Context MAY use a
different cookie scheme. An LCUP search will not cross an LCUP
Context boundary, but will instead return a SearchResultReference
message, with the LDAP URL specifying the same host and port as
currently being searched, and with the baseDN set to the baseDN of
the new LCUP Context. The client is then responsible for issuing
another search using the new baseDN, and possibly a different cookie
if that LCUP Context uses a different cookie. The client is
responsible for maintaining a mapping of the LDAP URL to its
corresponding cookie.
3.5. Additional LDAP Result Codes defined by LCUP
Implementations of this specification SHALL recognize the following
additional resultCode values. The LDAP result code names and numbers
defined in the following table have been assigned by IANA per RFC
3383 [RFC3383].
lcupResourcesExhausted (113) the server is running out of resources
lcupSecurityViolation (114) the client is suspected of malicious
actions
lcupInvalidData (115) invalid scheme or cookie was supplied
by the client
lcupUnsupportedScheme (116) The cookie scheme is a valid OID but
is not supported by this server
lcupReloadRequired (117) 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 if the
server’s data was reloaded since the
last synchronization session
The uses of these codes are described below.
3.6. Sync Request Control
The Sync Request Control is an LDAP Control [RFC2251, Section 4.1.2]
where the controlType is the object identifier 1.3.6.1.1.7.1 and the
controlValue, an OCTET STRING, contains a BER-encoded
syncRequestControlValue.
syncRequestControlValue ::= SEQUENCE {
updateType ENUMERATED {
syncOnly (0),
syncAndPersist (1),
persistOnly (2) },
sendCookieInterval [0] INTEGER OPTIONAL,
scheme [1] LCUPScheme OPTIONAL,
cookie [2] LCUPCookie OPTIONAL
}
sendCookieInterval - the server SHOULD send the cookie back in the
Sync Update control value (defined below) for every
sendCookieInterval number of SearchResultEntry and
SearchResultReference PDUs returned to the client. For example, if
the value is 5, the server SHOULD send the cookie back in the Sync
Update control value for every 5 search results returned to the
client. If this value is absent, zero or less than zero, the server
chooses the interval.
The Sync Request Control is only applicable to the searchRequest
message. Use of this control is described below.
3.7. Sync Update Control
The Sync Update Control is an LDAP Control [RFC2251, Section 4.1.2]
where the controlType is the object identifier 1.3.6.1.1.7.2 and the
controlValue, an OCTET STRING, contains a BER-encoded
syncUpdateControlValue.
syncUpdateControlValue ::= SEQUENCE {
stateUpdate BOOLEAN,
entryUUID [0] LCUPUUID OPTIONAL, -- REQUIRED for entries --
UUIDAttribute [1] AttributeType OPTIONAL,
entryLeftSet [2] BOOLEAN,
persistPhase [3] BOOLEAN,
scheme [4] LCUPScheme OPTIONAL,
cookie [5] LCUPCookie OPTIONAL
}
The field UUIDAttribute contains the name or OID of the attribute
that the client should use to perform searches for entries based on
the UUID. The client should be able to use it in an equality search
filter, e.g., "(<uuid attribute>=<entry UUID value>)" and should be
able to use it in the attribute list of the search request to return
its value. The UUIDAttribute field may be omitted if the server does
not support searching on the UUID values.
The Sync Update Control is only applicable to SearchResultEntry and
SearchResultReference messages. Although entryUUID is OPTIONAL, it
MUST be used with SearchResultEntry messages. Use of this control is
described below.
3.8. Sync Done Control
The Sync Done Control is an LDAP Control [RFC2251, Section 4.1.2]
where the controlType is the object identifier 1.3.6.1.1.7.3 and the
controlValue contains a BER-encoded syncDoneValue.
syncDoneValue ::= SEQUENCE {
scheme [0] LCUPScheme OPTIONAL,
cookie [1] LCUPCookie OPTIONAL
}
The Sync Done Control is only applicable to SearchResultDone message.
Use of this control is described below.
4. Protocol Usage and Flow
4.1. LCUP Search Requests
A client initiates a synchronization or persistent search session
with a server by attaching a Sync Request control to an LDAP
searchRequest message. 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 Sync Request
control contains the client’s request specification.
If there is an error condition, the server MUST immediately return a
SearchResultDone message with the resultCode set to an error code.
This table maps a condition to its corresponding behavior and
resultCode.
Condition Behavior or resultCode
Sync Request Control is not Server behaves as [RFC2251, Section
supported 4.1.2] - specifically, if the
criticality of the control is FALSE,
the server will process the request
as a normal search request
Scheme is not supported lcupUnsupportedScheme
A control value field is lcupInvalidData
invalid (e.g., illegal
updateType, or the scheme is
not a valid OID, or the cookie
is invalid)
Server is running out of lcupResourcesExhausted
resources
Server suspects client of lcupSecurityViolation
malicious behavior (frequent
connects/disconnects, etc.)
The server cannot bring the lcupReloadRequired
client up to date (server data
has been reloaded, or other
changes prevent
convergence)
4.1.1. Initial Synchronization and Full Resync
For an initial synchronization or full resync, the fields of the Sync