Lightweight Directory Access Protocol (LDAP) Client Update Protocol (LCUP)
Extracted elements (29)
LCUP is designed so the server does not maintain per-client state; clients are responsible for storing the cookie that captures how up-to-date they are relative to the server. This avoids the need for LCUP-specific update agreements before use and lets the client choose when and from where to pull changes.
LCUP sends complete entries rather than only changed attributes. Sending only deltas is hard to implement server-side and can leave clients with incomplete data when an entry enters scope due to a modification—the client would never see the initial attribute values.
Multiple cookie schemes are supported (identified by OID) to give implementations flexibility in what state they encode. A Replica Update Vector (RUV) is given as an example scheme: it uniquely identifies client state, supports multi-server sync, and detects server data reloads.
No guarantee is specified for how quickly a server must notify the client of changes during the persist phase, because any specific maximum delay would be impossible to meet in a distributed directory service. Server implementers are encouraged to minimize delay in practice.
A cookie SHOULD only be reused with the same search specification that generated it. Some servers MAY accept a cookie with a more restrictive search specification. If the server does not accept the cookie, it MUST return lcupInvalidData.
The server MUST send a SearchResultReference when the LCUP Context changes during a search spanning multiple DIT sections. The client SHOULD maintain a cache mapping LDAP URLs to their corresponding cookies and SHOULD issue separate LCUP searches to follow references.
Use of an LCUP cookie across multiple DSAs in a replicated environment is not defined by LCUP. Clients MAY submit a cookie from one DSA to another; the receiving server determines whether it recognizes the cookie and returns an appropriate result code if not.
A UUID MUST be used to uniquely identify entries in LCUP. Servers MUST support UUIDs and SHOULD expose them as a single-valued operational attribute (e.g., 'entryUUID') with efficient indexed search support.
Clients MUST specify derefAliases as either neverDerefAliases or derefFindingBaseObj. Servers MUST return protocolError if the client specifies derefInSearching or derefAlways.
During the sync phase the server MUST NOT return any entries with persistPhase set to TRUE; during the persist phase all entries returned MUST have persistPhase set to TRUE. Sync phase entries MUST be returned before any persist phase entries.
For incremental or update synchronization, the Sync Request control MUST include both scheme and cookie fields. The client SHOULD always use the latest cookie it received from the server.
For initial synchronization or full resync, the Sync Request control cookie field MUST NOT be set. The updateType MUST be syncOnly or syncAndPersist; scheme MAY be set, and if set the server MUST use that scheme or return lcupUnsupportedScheme.
If the client initiates termination via LDAP Cancel, the server MUST set resultCode to 'canceled' and the cookie MUST be set in the Sync Done control, allowing the client to resume later from that point.
If the server determines it cannot guarantee eventual convergence of the client's data—due to server reload, metadata changes, or an outdated cookie—it SHOULD immediately terminate the LCUP search with resultCode lcupReloadRequired.
Implementations SHALL recognize the five LCUP-specific result codes (113–117). If the Sync Request Control is unsupported and its criticality is FALSE, the server processes the request as a normal LDAP search per RFC 2251.
The cookie MUST be set in the Sync Done control when the SearchResultDone resultCode is success or canceled. The server SHOULD also set the cookie when resultCode is lcupResourcesExhausted, timeLimitExceeded, sizeLimitExceeded, or adminLimitExceeded.
The scheme field in the Sync Update control MUST be set whenever the cookie is set and the cookie format has changed; otherwise it MAY be omitted. Within a given LCUP Context, the cookie scheme MUST remain the same.
When a Modify DN or Delete is applied to a subtree base within an LCUP search scope, the server MUST either return each affected entry as renamed or removed, or force the client to resync by returning lcupReloadRequired.
When transitioning from sync to persist phase in a syncAndPersist request, the server MUST send a Sync Update Informational Response (stateUpdate=TRUE, persistPhase=TRUE) immediately after the last sync-phase entry and before any persist-phase entry.
A UUID (LCUPUUID ::= OCTET STRING) MUST be used to uniquely identify each entry because distinguished names can change and are therefore unreliable as stable identifiers. The UUID is carried in the Sync Update control value returned with each search result.
An LCUP Context is a portion of the DIT enabled for LCUP. A server may support one or more LCUP Contexts, each potentially using a different cookie scheme. An LCUP search will not cross an LCUP Context boundary; instead it returns a SearchResultReference so the client can issue a separate search for the new context.
The LCUP Cookie (LCUPCookie ::= OCTET STRING) holds the state of the client's data relative to the server. Each cookie format is identified by an LCUPScheme (LDAPOID); the scheme OID MUST be unique for a given cookie format. The cookie value may be opaque or have a well-known format depending on the scheme.
Five LDAP result codes are registered by IANA: lcupResourcesExhausted (113), lcupSecurityViolation (114), lcupInvalidData (115), lcupUnsupportedScheme (116), and lcupReloadRequired (117). Three LDAP Protocol Mechanism OIDs are registered under 1.3.6.1.1.7: Sync Request Control (.1), Sync Update Control (.2), Sync Done Control (.3).
A malicious client can initiate large numbers of persistent searches to exhaust server resources. Servers SHOULD detect such clients, SHOULD limit per-client resource consumption, and SHOULD return lcupSecurityViolation when malicious behavior is inferred. Clients that receive lcupResourcesExhausted or lcupSecurityViolation SHOULD wait at least 5 seconds and SHOULD use exponential backoff before retrying.
Servers implementing LCUP SHOULD provide access control mechanisms to prevent general exposure of directory change information and MAY provide specific controls over the use of the LCUP controls and extended operations.
An LCUP search has two phases: sync phase (server sends current or changed entries) and persist phase (server notifies client of ongoing changes in real time). The updateType controls which phases occur: syncOnly (sync only), syncAndPersist (both), persistOnly (persist only). Transition from sync to persist is signaled by a stateUpdate informational response with persistPhase=TRUE.
The Sync Done Control (OID 1.3.6.1.1.7.3) carries a BER-encoded syncDoneValue SEQUENCE with optional scheme LCUPScheme and optional cookie LCUPCookie. It is attached only to SearchResultDone messages.
The Sync Request Control (OID 1.3.6.1.1.7.1) carries a BER-encoded syncRequestControlValue SEQUENCE containing: updateType ENUMERATED {syncOnly(0), syncAndPersist(1), persistOnly(2)}, optional sendCookieInterval INTEGER, optional scheme LCUPScheme, and optional cookie LCUPCookie.
The Sync Update Control (OID 1.3.6.1.1.7.2) carries a BER-encoded syncUpdateControlValue SEQUENCE with fields: stateUpdate BOOLEAN, optional entryUUID LCUPUUID (REQUIRED for SearchResultEntry), optional UUIDAttribute, entryLeftSet BOOLEAN, persistPhase BOOLEAN, optional scheme, and optional cookie.