]> git.sur5r.net Git - openldap/blob - doc/rfc/rfc4533.txt
Fix prev commit
[openldap] / doc / rfc / rfc4533.txt
1
2
3
4
5
6
7 Network Working Group                                        K. Zeilenga
8 Request for Comments: 4533                           OpenLDAP Foundation
9 Category: Experimental                                         J.H. Choi
10                                                          IBM Corporation
11                                                                June 2006
12
13
14            The Lightweight Directory Access Protocol (LDAP)
15                    Content Synchronization Operation
16
17 Status of This Memo
18
19    This memo defines an Experimental Protocol for the Internet
20    community.  It does not specify an Internet standard of any kind.
21    Discussion and suggestions for improvement are requested.
22    Distribution of this memo is unlimited.
23
24 Copyright Notice
25
26    Copyright (C) The Internet Society (2006).
27
28 IESG Note
29
30    The IESG notes that this work was originally discussed in the LDUP
31    working group.  The group came to consensus on a different approach,
32    documented in RFC 3928; that document is on the standards track and
33    should be reviewed by those considering implementation of this
34    proposal.
35
36 Abstract
37
38    This specification describes the Lightweight Directory Access
39    Protocol (LDAP) Content Synchronization Operation.  The operation
40    allows a client to maintain a copy of a fragment of the Directory
41    Information Tree (DIT).  It supports both polling for changes and
42    listening for changes.  The operation is defined as an extension of
43    the LDAP Search Operation.
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58 Zeilenga & Choi               Experimental                      [Page 1]
59 \f
60 RFC 4533         LDAP Content Synchronization Operation        June 2006
61
62
63 Table of Contents
64
65    1. Introduction ....................................................3
66       1.1. Background .................................................3
67       1.2. Intended Usage .............................................4
68       1.3. Overview ...................................................5
69       1.4. Conventions ................................................8
70    2. Elements of the Sync Operation ..................................8
71       2.1. Common ASN.1 Elements ......................................9
72       2.2. Sync Request Control .......................................9
73       2.3. Sync State Control ........................................10
74       2.4. Sync Done Control .........................................10
75       2.5. Sync Info Message .........................................11
76       2.6. Sync Result Codes .........................................11
77    3. Content Synchronization ........................................11
78       3.1. Synchronization Session ...................................12
79       3.2. Content Determination .....................................12
80       3.3. refreshOnly Mode ..........................................13
81       3.4. refreshAndPersist Mode ....................................16
82       3.5. Search Request Parameters .................................17
83       3.6. objectName ................................................18
84       3.7. Canceling the Sync Operation ..............................19
85       3.8. Refresh Required ..........................................19
86       3.9. Chattiness Considerations .................................20
87       3.10. Operation Multiplexing ...................................21
88    4. Meta Information Considerations ................................22
89       4.1. Entry DN ..................................................22
90       4.2. Operational Attributes ....................................22
91       4.3. Collective Attributes .....................................23
92       4.4. Access and Other Administrative Controls ..................23
93    5. Interaction with Other Controls ................................23
94       5.1. ManageDsaIT Control .......................................24
95       5.2. Subentries Control ........................................24
96    6. Shadowing Considerations .......................................24
97    7. Security Considerations ........................................25
98    8. IANA Considerations ............................................26
99       8.1. Object Identifier .........................................26
100       8.2. LDAP Protocol Mechanism ...................................26
101       8.3. LDAP Result Codes .........................................26
102    9. Acknowledgements ...............................................26
103    10. Normative References ..........................................27
104    11. Informative References ........................................28
105    Appendix A.  CSN-based Implementation Considerations ..............29
106
107
108
109
110
111
112
113
114 Zeilenga & Choi               Experimental                      [Page 2]
115 \f
116 RFC 4533         LDAP Content Synchronization Operation        June 2006
117
118
119 1.  Introduction
120
121    The Lightweight Directory Access Protocol (LDAP) [RFC4510] provides a
122    mechanism, the search operation [RFC4511], that allows a client to
123    request directory content matching a complex set of assertions and to
124    request that the server return this content, subject to access
125    control and other restrictions, to the client.  However, LDAP does
126    not provide (despite the introduction of numerous extensions in this
127    area) an effective and efficient mechanism for maintaining
128    synchronized copies of directory content.  This document introduces a
129    new mechanism specifically designed to meet the content
130    synchronization requirements of sophisticated directory applications.
131
132    This document defines the LDAP Content Synchronization Operation, or
133    Sync Operation for short, which allows a client to maintain a
134    synchronized copy of a fragment of a Directory Information Tree
135    (DIT).  The Sync Operation is defined as a set of controls and other
136    protocol elements that extend the Search Operation.
137
138 1.1.  Background
139
140    Over the years, a number of content synchronization approaches have
141    been suggested for use in LDAP directory services.  These approaches
142    are inadequate for one or more of the following reasons:
143
144       -  failure to ensure a reasonable level of convergence;
145
146       -  failure to detect that convergence cannot be achieved (without
147          reload);
148
149       -  require pre-arranged synchronization agreements;
150
151       -  require the server to maintain histories of past changes to DIT
152          content and/or meta information;
153
154       -  require the server to maintain synchronization state on a per-
155          client basis; and/or
156
157       -  are overly chatty.
158
159    The Sync Operation provides eventual convergence of synchronized
160    content when possible and, when not, notification that a full reload
161    is required.
162
163    The Sync Operation does not require pre-arranged synchronization
164    agreements.
165
166
167
168
169
170 Zeilenga & Choi               Experimental                      [Page 3]
171 \f
172 RFC 4533         LDAP Content Synchronization Operation        June 2006
173
174
175    The Sync Operation does not require that servers maintain or use any
176    history of past changes to the DIT or to meta information.  However,
177    servers may maintain and use histories (e.g., change logs,
178    tombstones, DIT snapshots) to reduce the number of messages generated
179    and to reduce their size.  As it is not always feasible to maintain
180    and use histories, the operation may be implemented using purely
181    (current) state-based approaches.  The Sync Operation allows use of
182    either the state-based approach or the history-based approach on an
183    operation-by-operation basis to balance the size of history and the
184    amount of traffic.  The Sync Operation also allows the combined use
185    of the state-based and the history-based approaches.
186
187    The Sync Operation does not require that servers maintain
188    synchronization state on a per-client basis.  However, servers may
189    maintain and use per-client state information to reduce the number of
190    messages generated and the size of such messages.
191
192    A synchronization mechanism can be considered overly chatty when
193    synchronization traffic is not reasonably bounded.  The Sync
194    Operation traffic is bounded by the size of updated (or new) entries
195    and the number of unchanged entries in the content.  The operation is
196    designed to avoid full content exchanges, even when the history
197    information available to the server is insufficient to determine the
198    client's state.  The operation is also designed to avoid transmission
199    of out-of-content history information, as its size is not bounded by
200    the content and it is not always feasible to transmit such history
201    information due to security reasons.
202
203    This document includes a number of non-normative appendices providing
204    additional information to server implementors.
205
206 1.2.  Intended Usage
207
208    The Sync Operation is intended to be used in applications requiring
209    eventually-convergent content synchronization.  Upon completion of
210    each synchronization stage of the operation, all information to
211    construct a synchronized client copy of the content has been provided
212    to the client or the client has been notified that a complete content
213    reload is necessary.  Except for transient inconsistencies due to
214    concurrent operation (or other) processing at the server, the client
215    copy is an accurate reflection of the content held by the server.
216    Transient inconsistencies will be resolved by subsequent
217    synchronization operations.
218
219
220
221
222
223
224
225
226 Zeilenga & Choi               Experimental                      [Page 4]
227 \f
228 RFC 4533         LDAP Content Synchronization Operation        June 2006
229
230
231    Possible uses include the following:
232
233       -  White page service applications may use the Sync Operation to
234          maintain a current copy of a DIT fragment, for example, a mail
235          user agent that uses the sync operation to maintain a local
236          copy of an enterprise address book.
237
238       -  Meta-information engines may use the Sync Operation to maintain
239          a copy of a DIT fragment.
240
241       -  Caching proxy services may use the Sync Operation to maintain a
242          coherent content cache.
243
244       -  Lightweight master-slave replication between heterogeneous
245          directory servers.  For example, the Sync Operation can be used
246          by a slave server to maintain a shadow copy of a DIT fragment.
247          (Note: The International Telephone Union (ITU) has defined the
248          X.500 Directory [X.500] Information Shadowing Protocol (DISP)
249          [X.525], which may be used for master-slave replication between
250          directory servers.  Other experimental LDAP replication
251          protocols also exist.)
252
253    This protocol is not intended to be used in applications requiring
254    transactional data consistency.
255
256    As this protocol transfers all visible values of entries belonging to
257    the content upon change instead of change deltas, this protocol is
258    not appropriate for bandwidth-challenged applications or deployments.
259
260 1.3.  Overview
261
262    This section provides an overview of basic ways the Sync Operation
263    can be used to maintain a synchronized client copy of a DIT fragment.
264
265       -  Polling for changes: refreshOnly mode
266
267       -  Listening for changes: refreshAndPersist mode
268
269 1.3.1.  Polling for Changes (refreshOnly)
270
271    To obtain its initial client copy, the client issues a Sync request:
272    a search request with the Sync Request Control with mode set to
273    refreshOnly.  The server, much like it would with a normal search
274    operation, returns (subject to access controls and other
275    restrictions) the content matching the search criteria (baseObject,
276    scope, filter, attributes).  Additionally, with each entry returned,
277    the server provides a Sync State Control indicating state add.  This
278    control contains the Universally Unique Identifier (UUID) [UUID] of
279
280
281
282 Zeilenga & Choi               Experimental                      [Page 5]
283 \f
284 RFC 4533         LDAP Content Synchronization Operation        June 2006
285
286
287    the entry [RFC4530].  Unlike the Distinguished Name (DN), which may
288    change over time, an entry's UUID is stable.  The initial content is
289    followed by a SearchResultDone with a Sync Done Control.  The Sync
290    Done Control provides a syncCookie.  The syncCookie represents
291    session state.
292
293    To poll for updates to the client copy, the client reissues the Sync
294    Operation with the syncCookie previously returned.  The server, much
295    as it would with a normal search operation, determines which content
296    would be returned as if the operation were a normal search operation.
297    However, using the syncCookie as an indicator of what content the
298    client was sent previously, the server sends copies of entries that
299    have changed with a Sync State Control indicating state add.  For
300    each changed entry, all (modified or unmodified) attributes belonging
301    to the content are sent.
302
303    The server may perform either or both of the two distinct
304    synchronization phases that are distinguished by how to synchronize
305    entries deleted from the content: the present and the delete phases.
306    When the server uses a single phase for the refresh stage, each phase
307    is marked as ended by a SearchResultDone with a Sync Done Control.  A
308    present phase is identified by a FALSE refreshDeletes value in the
309    Sync Done Control.  A delete phase is identified by a TRUE
310    refreshDeletes value.  The present phase may be followed by a delete
311    phase.  The two phases are delimited by a refreshPresent Sync Info
312    Message having a FALSE refreshDone value.  In the case that both the
313    phases are used, the present phase is used to bring the client copy
314    up to the state at which the subsequent delete phase can begin.
315
316    In the present phase, the server sends an empty entry (i.e., no
317    attributes) with a Sync State Control indicating state present for
318    each unchanged entry.
319
320    The delete phase may be used when the server can reliably determine
321    which entries in the prior client copy are no longer present in the
322    content and the number of such entries is less than or equal to the
323    number of unchanged entries.  In the delete mode, the server sends an
324    empty entry with a Sync State Control indicating state delete for
325    each entry that is no longer in the content, instead of returning an
326    empty entry with state present for each present entry.
327
328    The server may send syncIdSet Sync Info Messages containing the set
329    of UUIDs of either unchanged present entries or deleted entries,
330    instead of sending multiple individual messages.  If refreshDeletes
331    of syncIdSet is set to FALSE, the UUIDs of unchanged present entries
332    are contained in the syncUUIDs set; if refreshDeletes of syncIdSet is
333    set to TRUE, the UUIDs of the entries no longer present in the
334    content are contained in the syncUUIDs set.  An optional cookie can
335
336
337
338 Zeilenga & Choi               Experimental                      [Page 6]
339 \f
340 RFC 4533         LDAP Content Synchronization Operation        June 2006
341
342
343    be included in the syncIdSet to represent the state of the content
344    after synchronizing the presence or the absence of the entries
345    contained in the syncUUIDs set.
346
347    The synchronized copy of the DIT fragment is constructed by the
348    client.
349
350    If refreshDeletes of syncDoneValue is FALSE, the new copy includes
351    all changed entries returned by the reissued Sync Operation, as well
352    as all unchanged entries identified as being present by the reissued
353    Sync Operation, but whose content is provided by the previous Sync
354    Operation.  The unchanged entries not identified as being present are
355    deleted from the client content.  They had been either deleted,
356    moved, or otherwise scoped-out from the content.
357
358    If refreshDeletes of syncDoneValue is TRUE, the new copy includes all
359    changed entries returned by the reissued Sync Operation, as well as
360    all other entries of the previous copy except for those that are
361    identified as having been deleted from the content.
362
363    The client can, at some later time, re-poll for changes to this
364    synchronized client copy.
365
366 1.3.2.  Listening for Changes (refreshAndPersist)
367
368    Polling for changes can be expensive in terms of server, client, and
369    network resources.  The refreshAndPersist mode allows for active
370    updates of changed entries in the content.
371
372    By selecting the refreshAndPersist mode, the client requests that the
373    server send updates of entries that are changed after the initial
374    refresh content is determined.  Instead of sending a SearchResultDone
375    Message as in polling, the server sends a Sync Info Message to the
376    client indicating that the refresh stage is complete and then enters
377    the persist stage.  After receipt of this Sync Info Message, the
378    client will construct a synchronized copy as described in Section
379    1.3.1.
380
381    The server may then send change notifications as the result of the
382    original Sync search request, which now remains persistent in the
383    server.  For entries to be added to the returned content, the server
384    sends a SearchResultEntry (with attributes) with a Sync State Control
385    indicating state add.  For entries to be deleted from the content,
386    the server sends a SearchResultEntry containing no attributes and a
387    Sync State Control indicating state delete.  For entries to be
388    modified in the return content, the server sends a SearchResultEntry
389    (with attributes) with a Sync State Control indicating state modify.
390
391
392
393
394 Zeilenga & Choi               Experimental                      [Page 7]
395 \f
396 RFC 4533         LDAP Content Synchronization Operation        June 2006
397
398
399    Upon modification of an entry, all (modified or unmodified)
400    attributes belonging to the content are sent.
401
402    Note that renaming an entry of the DIT may cause an add state change
403    where the entry is renamed into the content, a delete state change
404    where the entry is renamed out of the content, and a modify state
405    change where the entry remains in the content.  Also note that a
406    modification of an entry of the DIT may cause an add, delete, or
407    modify state change to the content.
408
409    Upon receipt of a change notification, the client updates its copy of
410    the content.
411
412    If the server desires to update the syncCookie during the persist
413    stage, it may include the syncCookie in any Sync State Control or
414    Sync Info Message returned.
415
416    The operation persists until canceled [RFC3909] by the client or
417    terminated by the server.  A Sync Done Control shall be attached to
418    SearchResultDone Message to provide a new syncCookie.
419
420 1.4.  Conventions
421
422    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
423    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
424    document are to be interpreted as described in BCP 14 [RFC2119].
425
426    Protocol elements are described using ASN.1 [X.680] with implicit
427    tags.  The term "BER-encoded" means the element is to be encoded
428    using the Basic Encoding Rules [X.690] under the restrictions
429    detailed in Section 5.1 of [RFC4511].
430
431 2.  Elements of the Sync Operation
432
433    The Sync Operation is defined as an extension to the LDAP Search
434    Operation [RFC4511] where the directory user agent (DUA or client)
435    submits a SearchRequest Message with a Sync Request Control and the
436    directory system agent (DSA or server) responds with zero or more
437    SearchResultEntry Messages, each with a Sync State Control; zero or
438    more SearchResultReference Messages, each with a Sync State Control;
439    zero or more Sync Info Intermediate Response Messages; and a
440    SearchResultDone Message with a Sync Done Control.
441
442    To allow clients to discover support for this operation, servers
443    implementing this operation SHOULD publish 1.3.6.1.4.1.4203.1.9.1.1
444    as a value of the 'supportedControl' attribute [RFC4512] of the root
445    DSA-specific entry (DSE).  A server MAY choose to advertise this
446    extension only when the client is authorized to use it.
447
448
449
450 Zeilenga & Choi               Experimental                      [Page 8]
451 \f
452 RFC 4533         LDAP Content Synchronization Operation        June 2006
453
454
455 2.1.  Common ASN.1 Elements
456
457 2.1.1.  syncUUID
458
459    The syncUUID data type is an OCTET STRING holding a 128-bit
460    (16-octet) Universally Unique Identifier (UUID) [UUID].
461
462       syncUUID ::= OCTET STRING (SIZE(16))
463            -- constrained to UUID
464
465 2.1.2.  syncCookie
466
467    The syncCookie is a notational convenience to indicate that, while
468    the syncCookie type is encoded as an OCTET STRING, its value is an
469    opaque value containing information about the synchronization session
470    and its state.  Generally, the session information would include a
471    hash of the operation parameters that the server requires not be
472    changed and the synchronization state information would include a
473    commit (log) sequence number, a change sequence number, or a time
474    stamp.  For convenience of description, the term "no cookie" refers
475    either to a null cookie or to a cookie with pre-initialized
476    synchronization state.
477
478       syncCookie ::= OCTET STRING
479
480 2.2.  Sync Request Control
481
482    The Sync Request Control is an LDAP Control [RFC4511] where the
483    controlType is the object identifier 1.3.6.1.4.1.4203.1.9.1.1 and the
484    controlValue, an OCTET STRING, contains a BER-encoded
485    syncRequestValue.  The criticality field is either TRUE or FALSE.
486
487       syncRequestValue ::= SEQUENCE {
488           mode ENUMERATED {
489               -- 0 unused
490               refreshOnly       (1),
491               -- 2 reserved
492               refreshAndPersist (3)
493           },
494           cookie     syncCookie OPTIONAL,
495           reloadHint BOOLEAN DEFAULT FALSE
496       }
497
498    The Sync Request Control is only applicable to the SearchRequest
499    Message.
500
501
502
503
504
505
506 Zeilenga & Choi               Experimental                      [Page 9]
507 \f
508 RFC 4533         LDAP Content Synchronization Operation        June 2006
509
510
511 2.3.  Sync State Control
512
513    The Sync State Control is an LDAP Control [RFC4511] where the
514    controlType is the object identifier 1.3.6.1.4.1.4203.1.9.1.2 and the
515    controlValue, an OCTET STRING, contains a BER-encoded syncStateValue.
516    The criticality is FALSE.
517
518       syncStateValue ::= SEQUENCE {
519           state ENUMERATED {
520               present (0),
521               add (1),
522               modify (2),
523               delete (3)
524           },
525           entryUUID syncUUID,
526           cookie    syncCookie OPTIONAL
527       }
528
529    The Sync State Control is only applicable to SearchResultEntry and
530    SearchResultReference Messages.
531
532 2.4.  Sync Done Control
533
534    The Sync Done Control is an LDAP Control [RFC4511] where the
535    controlType is the object identifier 1.3.6.1.4.1.4203.1.9.1.3 and the
536    controlValue contains a BER-encoded syncDoneValue.  The criticality
537    is FALSE (and hence absent).
538
539       syncDoneValue ::= SEQUENCE {
540           cookie          syncCookie OPTIONAL,
541           refreshDeletes  BOOLEAN DEFAULT FALSE
542       }
543
544    The Sync Done Control is only applicable to the SearchResultDone
545    Message.
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562 Zeilenga & Choi               Experimental                     [Page 10]
563 \f
564 RFC 4533         LDAP Content Synchronization Operation        June 2006
565
566
567 2.5.  Sync Info Message
568
569    The Sync Info Message is an LDAP Intermediate Response Message
570    [RFC4511] where responseName is the object identifier
571    1.3.6.1.4.1.4203.1.9.1.4 and responseValue contains a BER-encoded
572    syncInfoValue.  The criticality is FALSE (and hence absent).
573
574       syncInfoValue ::= CHOICE {
575           newcookie      [0] syncCookie,
576           refreshDelete  [1] SEQUENCE {
577               cookie         syncCookie OPTIONAL,
578               refreshDone    BOOLEAN DEFAULT TRUE
579           },
580           refreshPresent [2] SEQUENCE {
581               cookie         syncCookie OPTIONAL,
582               refreshDone    BOOLEAN DEFAULT TRUE
583           },
584           syncIdSet      [3] SEQUENCE {
585               cookie         syncCookie OPTIONAL,
586               refreshDeletes BOOLEAN DEFAULT FALSE,
587               syncUUIDs      SET OF syncUUID
588           }
589       }
590
591 2.6.  Sync Result Codes
592
593    The following LDAP resultCode [RFC4511] is defined:
594
595       e-syncRefreshRequired (4096)
596
597 3.  Content Synchronization
598
599    The Sync Operation is invoked when the client sends a SearchRequest
600    Message with a Sync Request Control.
601
602    The absence of a cookie or an initialized synchronization state in a
603    cookie indicates a request for initial content, while the presence of
604    a cookie representing a state of a client copy indicates a request
605    for a content update.  Synchronization Sessions are discussed in
606    Section 3.1.  Content Determination is discussed in Section 3.2.
607
608    The mode is either refreshOnly or refreshAndPersist.  The refreshOnly
609    and refreshAndPersist modes are discussed in Sections 3.3 and 3.4,
610    respectively.  The refreshOnly mode consists only of a refresh stage,
611    while the refreshAndPersist mode consists of a refresh stage and a
612    subsequent persist stage.
613
614
615
616
617
618 Zeilenga & Choi               Experimental                     [Page 11]
619 \f
620 RFC 4533         LDAP Content Synchronization Operation        June 2006
621
622
623 3.1.  Synchronization Session
624
625    A sequence of Sync Operations where the last cookie returned by the
626    server for one operation is provided by the client in the next
627    operation is said to belong to the same Synchronization Session.
628
629    The client MUST specify the same content-controlling parameters (see
630    Section 3.5) in each Search Request of the session.  The client
631    SHOULD also issue each Sync request of a session under the same
632    authentication and authorization associations with equivalent
633    integrity and protections.  If the server does not recognize the
634    request cookie or the request is made under different associations or
635    non-equivalent protections, the server SHALL return the initial
636    content as if no cookie had been provided or return an empty content
637    with the e-syncRefreshRequired LDAP result code.  The decision
638    between the return of the initial content and the return of the empty
639    content with the e-syncRefreshRequired result code MAY be based on
640    reloadHint in the Sync Request Control from the client.  If the
641    server recognizes the request cookie as representing empty or initial
642    synchronization state of the client copy, the server SHALL return the
643    initial content.
644
645    A Synchronization Session may span multiple LDAP sessions between the
646    client and the server.  The client SHOULD issue each Sync request of
647    a session to the same server.  (Note: Shadowing considerations are
648    discussed in Section 6.)
649
650 3.2.  Content Determination
651
652    The content to be provided is determined by parameters of the Search
653    Request, as described in [RFC4511], and possibly other controls.  The
654    same content parameters SHOULD be used in each Sync request of a
655    session.  If different content is requested and the server is
656    unwilling or unable to process the request, the server SHALL return
657    the initial content as if no cookie had been provided or return an
658    empty content with the e-syncRefreshRequired LDAP result code.  The
659    decision between the return of the initial content and the return of
660    the empty content with the e-syncRefreshRequired result code MAY be
661    based on reloadHint in the Sync Request Control from the client.
662
663    The content may not necessarily include all entries or references
664    that would be returned by a normal search operation, nor, for those
665    entries included, all attributes returned by a normal search.  When
666    the server is unwilling or unable to provide synchronization for any
667    attribute for a set of entries, the server MUST treat all filter
668    components matching against these attributes as Undefined and MUST
669    NOT return these attributes in SearchResultEntry responses.
670
671
672
673
674 Zeilenga & Choi               Experimental                     [Page 12]
675 \f
676 RFC 4533         LDAP Content Synchronization Operation        June 2006
677
678
679    Servers SHOULD support synchronization for all non-collective user-
680    application attributes for all entries.
681
682    The server may also return continuation references to other servers
683    or to itself.  The latter is allowed as the server may partition the
684    entries it holds into separate synchronization contexts.
685
686    The client may chase all or some of these continuations, each as a
687    separate content synchronization session.
688
689 3.3.  refreshOnly Mode
690
691    A Sync request with mode refreshOnly and with no cookie is a poll for
692    initial content.  A Sync request with mode refreshOnly and with a
693    cookie representing a synchronization state is a poll for content
694    update.
695
696 3.3.1.  Initial Content Poll
697
698    Upon receipt of the request, the server provides the initial content
699    using a set of zero or more SearchResultEntry and
700    SearchResultReference Messages followed by a SearchResultDone
701    Message.
702
703    Each SearchResultEntry Message SHALL include a Sync State Control of
704    state add, an entryUUID containing the entry's UUID, and no cookie.
705    Each SearchResultReference Message SHALL include a Sync State Control
706    of state add, an entryUUID containing the UUID associated with the
707    reference (normally the UUID of the associated named referral
708    [RFC3296] object), and no cookie.  The SearchResultDone Message SHALL
709    include a Sync Done Control having refreshDeletes set to FALSE.
710
711    A resultCode value of success indicates that the operation
712    successfully completed.  Otherwise, the result code indicates the
713    nature of the failure.  The server may return e-syncRefreshRequired
714    result code on the initial content poll if it is safe to do so when
715    it is unable to perform the operation due to various reasons.
716    reloadHint is set to FALSE in the SearchRequest Message requesting
717    the initial content poll.
718
719    If the operation is successful, a cookie representing the
720    synchronization state of the current client copy SHOULD be returned
721    for use in subsequent Sync Operations.
722
723 3.3.2.  Content Update Poll
724
725    Upon receipt of the request, the server provides the content refresh
726    using a set of zero or more SearchResultEntry and
727
728
729
730 Zeilenga & Choi               Experimental                     [Page 13]
731 \f
732 RFC 4533         LDAP Content Synchronization Operation        June 2006
733
734
735    SearchResultReference Messages followed by a SearchResultDone
736    Message.
737
738    The server is REQUIRED to:
739
740       a) provide the sequence of messages necessary for eventual
741          convergence of the client's copy of the content to the server's
742          copy,
743
744       b) treat the request as an initial content request (e.g., ignore
745          the cookie or the synchronization state represented in the
746          cookie),
747
748       c) indicate that the incremental convergence is not possible by
749          returning e-syncRefreshRequired,
750
751       d) return a resultCode other than success or e-
752          syncRefreshRequired.
753
754    A Sync Operation may consist of a single present phase, a single
755    delete phase, or a present phase followed by a delete phase.
756
757    In each phase, for each entry or reference that has been added to the
758    content or been changed since the previous Sync Operation indicated
759    by the cookie, the server returns a SearchResultEntry or
760    SearchResultReference Message, respectively, each with a Sync State
761    Control consisting of state add, an entryUUID containing the UUID of
762    the entry or reference, and no cookie.  Each SearchResultEntry
763    Message represents the current state of a changed entry.  Each
764    SearchResultReference Message represents the current state of a
765    changed reference.
766
767    In the present phase, for each entry that has not been changed since
768    the previous Sync Operation, an empty SearchResultEntry is returned
769    whose objectName reflects the entry's current DN, whose attributes
770    field is empty, and whose Sync State Control consists of state
771    present, an entryUUID containing the UUID of the entry, and no
772    cookie.  For each reference that has not been changed since the
773    previous Sync Operation, an empty SearchResultReference containing an
774    empty SEQUENCE OF LDAPURL is returned with a Sync State Control
775    consisting of state present, an entryUUID containing the UUID of the
776    entry, and no cookie.  No messages are sent for entries or references
777    that are no longer in the content.
778
779    Multiple empty entries with a Sync State Control of state present
780    SHOULD be coalesced into one or more Sync Info Messages of syncIdSet
781    value with refreshDeletes set to FALSE.  syncUUIDs contain a set of
782    UUIDs of the entries and references unchanged since the last Sync
783
784
785
786 Zeilenga & Choi               Experimental                     [Page 14]
787 \f
788 RFC 4533         LDAP Content Synchronization Operation        June 2006
789
790
791    Operation.  syncUUIDs may be empty.  The Sync Info Message of
792    syncIdSet may contain a cookie to represent the state of the content
793    after performing the synchronization of the entries in the set.
794
795    In the delete phase, for each entry no longer in the content, the
796    server returns a SearchResultEntry whose objectName reflects a past
797    DN of the entry or is empty, whose attributes field is empty, and
798    whose Sync State Control consists of state delete, an entryUUID
799    containing the UUID of the deleted entry, and no cookie.  For each
800    reference no longer in the content, a SearchResultReference
801    containing an empty SEQUENCE OF LDAPURL is returned with a Sync State
802    Control consisting of state delete, an entryUUID containing the UUID
803    of the deleted reference, and no cookie.
804
805    Multiple empty entries with a Sync State Control of state delete
806    SHOULD be coalesced into one or more Sync Info Messages of syncIdSet
807    value with refreshDeletes set to TRUE.  syncUUIDs contain a set of
808    UUIDs of the entries and references that have been deleted from the
809    content since the last Sync Operation.  syncUUIDs may be empty.  The
810    Sync Info Message of syncIdSet may contain a cookie to represent the
811    state of the content after performing the synchronization of the
812    entries in the set.
813
814    When a present phase is followed by a delete phase, the two phases
815    are delimited by a Sync Info Message containing syncInfoValue of
816    refreshPresent, which may contain a cookie representing the state
817    after completing the present phase.  The refreshPresent contains
818    refreshDone, which is always FALSE in the refreshOnly mode of Sync
819    Operation because it is followed by a delete phase.
820
821    If a Sync Operation consists of a single phase, each phase and hence
822    the Sync Operation are marked as ended by a SearchResultDone Message
823    with Sync Done Control, which SHOULD contain a cookie representing
824    the state of the content after completing the Sync Operation.  The
825    Sync Done Control contains refreshDeletes, which is set to FALSE for
826    the present phase and set to TRUE for the delete phase.
827
828    If a Sync Operation consists of a present phase followed by a delete
829    phase, the Sync Operation is marked as ended at the end of the delete
830    phase by a SearchResultDone Message with Sync Done Control, which
831    SHOULD contain a cookie representing the state of the content after
832    completing the Sync Operation.  The Sync Done Control contains
833    refreshDeletes, which is set to TRUE.
834
835    The client can specify whether it prefers to receive an initial
836    content by supplying reloadHint of TRUE or to receive a e-
837    syncRefreshRequired resultCode by supplying reloadHint of FALSE
838    (hence absent), in the case that the server determines that it is
839
840
841
842 Zeilenga & Choi               Experimental                     [Page 15]
843 \f
844 RFC 4533         LDAP Content Synchronization Operation        June 2006
845
846
847    impossible or inefficient to achieve the eventual convergence by
848    continuing the current incremental synchronization thread.
849
850    A resultCode value of success indicates that the operation is
851    successfully completed.  A resultCode value of e-syncRefreshRequired
852    indicates that a full or partial refresh is needed.  Otherwise, the
853    result code indicates the nature of failure.  A cookie is provided in
854    the Sync Done Control for use in subsequent Sync Operations for
855    incremental synchronization.
856
857 3.4.  refreshAndPersist Mode
858
859    A Sync request with mode refreshAndPersist asks for initial content
860    or content update (during the refresh stage) followed by change
861    notifications (during the persist stage).
862
863 3.4.1.  refresh Stage
864
865    The content refresh is provided as described in Section 3.3, except
866    that the successful completion of content refresh is indicated by
867    sending a Sync Info Message of refreshDelete or refreshPresent with a
868    refreshDone value set to TRUE instead of a SearchResultDone Message
869    with resultCode success.  A cookie SHOULD be returned in the Sync
870    Info Message to represent the state of the content after finishing
871    the refresh stage of the Sync Operation.
872
873 3.4.2.  persist Stage
874
875    Change notifications are provided during the persist stage.
876
877    As updates are made to the DIT, the server notifies the client of
878    changes to the content.  DIT updates may cause entries and references
879    to be added to the content, deleted from the content, or modified
880    within the content.  DIT updates may also cause references to be
881    added, deleted, or modified within the content.
882
883    Where DIT updates cause an entry to be added to the content, the
884    server provides a SearchResultEntry Message that represents the entry
885    as it appears in the content.  The message SHALL include a Sync State
886    Control with state of add, an entryUUID containing the entry's UUID,
887    and an optional cookie.
888
889    Where DIT updates cause a reference to be added to the content, the
890    server provides a SearchResultReference Message that represents the
891    reference in the content.  The message SHALL include a Sync State
892    Control with state of add, an entryUUID containing the UUID
893    associated with the reference, and an optional cookie.
894
895
896
897
898 Zeilenga & Choi               Experimental                     [Page 16]
899 \f
900 RFC 4533         LDAP Content Synchronization Operation        June 2006
901
902
903    Where DIT updates cause an entry to be modified within the content,
904    the server provides a SearchResultEntry Message that represents the
905    entry as it appears in the content.  The message SHALL include a Sync
906    State Control with state of modify, an entryUUID containing the
907    entry's UUID, and an optional cookie.
908
909    Where DIT updates cause a reference to be modified within the
910    content, the server provides a SearchResultReference Message that
911    represents the reference in the content.  The message SHALL include a
912    Sync State Control with state of modify, an entryUUID containing the
913    UUID associated with the reference, and an optional cookie.
914
915    Where DIT updates cause an entry to be deleted from the content, the
916    server provides a SearchResultEntry Message with no attributes.  The
917    message SHALL include a Sync State Control with state of delete, an
918    entryUUID containing the entry's UUID, and an optional cookie.
919
920    Where DIT updates cause a reference to be deleted from the content,
921    the server provides a SearchResultReference Message with an empty
922    SEQUENCE OF LDAPURL.  The message SHALL include a Sync State Control
923    with state of delete, an entryUUID containing the UUID associated
924    with the reference, and an optional cookie.
925
926    Multiple empty entries with a Sync State Control of state delete
927    SHOULD be coalesced into one or more Sync Info Messages of syncIdSet
928    value with refreshDeletes set to TRUE. syncUUIDs contain a set of
929    UUIDs of the entries and references that have been deleted from the
930    content.  The Sync Info Message of syncIdSet may contain a cookie to
931    represent the state of the content after performing the
932    synchronization of the entries in the set.
933
934    With each of these messages, the server may provide a new cookie to
935    be used in subsequent Sync Operations.  Additionally, the server may
936    also return Sync Info Messages of choice newCookie to provide a new
937    cookie.  The client SHOULD use the newest (last) cookie it received
938    from the server in subsequent Sync Operations.
939
940 3.5.  Search Request Parameters
941
942    As stated in Section 3.1, the client SHOULD specify the same
943    content-controlling parameters in each Search Request of the session.
944    All fields of the SearchRequest Message are considered content-
945    controlling parameters except for sizeLimit and timeLimit.
946
947
948
949
950
951
952
953
954 Zeilenga & Choi               Experimental                     [Page 17]
955 \f
956 RFC 4533         LDAP Content Synchronization Operation        June 2006
957
958
959 3.5.1.  baseObject
960
961    As with the normal search operation, the refresh and persist stages
962    are not isolated from DIT changes.  It is possible that the entry
963    referred to by the baseObject is deleted, renamed, or moved.  It is
964    also possible that the alias object used in finding the entry
965    referred to by the baseObject is changed such that the baseObject
966    refers to a different entry.
967
968    If the DIT is updated during processing of the Sync Operation in a
969    manner that causes the baseObject no longer to refer to any entry or
970    in a manner that changes the entry the baseObject refers to, the
971    server SHALL return an appropriate non-success result code, such as
972    noSuchObject, aliasProblem, aliasDereferencingProblem, referral, or
973    e-syncRefreshRequired.
974
975 3.5.2.  derefAliases
976
977    This operation does not support alias dereferencing during searching.
978    The client SHALL specify neverDerefAliases or derefFindingBaseObj for
979    the SearchRequest derefAliases parameter.  The server SHALL treat
980    other values (e.g., derefInSearching, derefAlways) as protocol
981    errors.
982
983 3.5.3.  sizeLimit
984
985    The sizeLimit applies only to entries (regardless of their state in
986    Sync State Control) returned during the refreshOnly operation or the
987    refresh stage of the refreshAndPersist operation.
988
989 3.5.4.  timeLimit
990
991    For a refreshOnly Sync Operation, the timeLimit applies to the whole
992    operation.  For a refreshAndPersist operation, the timeLimit applies
993    only to the refresh stage including the generation of the Sync Info
994    Message with a refreshDone value of TRUE.
995
996 3.5.5.  filter
997
998    The client SHOULD avoid filter assertions that apply to the values of
999    the attributes likely to be considered by the server as ones holding
1000    meta-information.  See Section 4.
1001
1002 3.6.  objectName
1003
1004    The Sync Operation uses entryUUID values provided in the Sync State
1005    Control as the primary keys to entries.  The client MUST use these
1006    entryUUIDs to correlate synchronization messages.
1007
1008
1009
1010 Zeilenga & Choi               Experimental                     [Page 18]
1011 \f
1012 RFC 4533         LDAP Content Synchronization Operation        June 2006
1013
1014
1015    In some circumstances, the DN returned may not reflect the entry's
1016    current DN.  In particular, when the entry is being deleted from the
1017    content, the server may provide an empty DN if the server does not
1018    wish to disclose the entry's current DN (or, if deleted from the DIT,
1019    the entry's last DN).
1020
1021    Also note that the entry's DN may be viewed as meta information (see
1022    Section 4.1).
1023
1024 3.7.  Canceling the Sync Operation
1025
1026    Servers MUST implement the LDAP Cancel [RFC3909] Operation and
1027    support cancellation of outstanding Sync Operations as described
1028    here.
1029
1030    To cancel an outstanding Sync Operation, the client issues an LDAP
1031    Cancel [RFC3909] Operation.
1032
1033    If at any time the server becomes unwilling or unable to continue
1034    processing a Sync Operation, the server SHALL return a
1035    SearchResultDone with a non-success resultCode indicating the reason
1036    for the termination of the operation.
1037
1038    Whether the client or the server initiated the termination, the
1039    server may provide a cookie in the Sync Done Control for use in
1040    subsequent Sync Operations.
1041
1042 3.8.  Refresh Required
1043
1044    In order to achieve the eventually-convergent synchronization, the
1045    server may terminate the Sync Operation in the refresh or persist
1046    stages by returning an e-syncRefreshRequired resultCode to the
1047    client.  If no cookie is provided, a full refresh is needed.  If a
1048    cookie representing a synchronization state is provided in this
1049    response, an incremental refresh is needed.
1050
1051    To obtain a full refresh, the client then issues a new
1052    synchronization request with no cookie.  To obtain an incremental
1053    reload, the client issues a new synchronization with the provided
1054    cookie.
1055
1056    The server may choose to provide a full copy in the refresh stage
1057    (e.g., ignore the cookie or the synchronization state represented in
1058    the cookie) instead of providing an incremental refresh in order to
1059    achieve the eventual convergence.
1060
1061
1062
1063
1064
1065
1066 Zeilenga & Choi               Experimental                     [Page 19]
1067 \f
1068 RFC 4533         LDAP Content Synchronization Operation        June 2006
1069
1070
1071    The decision between the return of the initial content and the return
1072    of the e-syncRefreshRequired result code may be based on reloadHint
1073    in the Sync Request Control from the client.
1074
1075    In the case of persist stage Sync, the server returns the resultCode
1076    of e-syncRefreshRequired to the client to indicate that the client
1077    needs to issue a new Sync Operation in order to obtain a synchronized
1078    copy of the content.  If no cookie is provided, a full refresh is
1079    needed.  If a cookie representing a synchronization state is
1080    provided, an incremental refresh is needed.
1081
1082    The server may also return e-syncRefreshRequired if it determines
1083    that a refresh would be more efficient than sending all the messages
1084    required for convergence.
1085
1086    Note that the client may receive one or more of SearchResultEntry,
1087    SearchResultReference, and/or Sync Info Messages before it receives a
1088    SearchResultDone Message with the e-syncRefreshRequired result code.
1089
1090 3.9.  Chattiness Considerations
1091
1092    The server MUST ensure that the number of entry messages generated to
1093    refresh the client content does not exceed the number of entries
1094    presently in the content.  While there is no requirement for servers
1095    to maintain history information, if the server has sufficient history
1096    to allow it to reliably determine which entries in the prior client
1097    copy are no longer present in the content and the number of such
1098    entries is less than or equal to the number of unchanged entries, the
1099    server SHOULD generate delete entry messages instead of present entry
1100    messages (see Section 3.3.2).
1101
1102    When the amount of history information maintained in the server is
1103    not enough for the clients to perform infrequent refreshOnly Sync
1104    Operations, it is likely that the server has incomplete history
1105    information (e.g., due to truncation) by the time those clients
1106    connect again.
1107
1108    The server SHOULD NOT resort to full reload when the history
1109    information is not enough to generate delete entry messages.  The
1110    server SHOULD generate either present entry messages only or present
1111    entry messages followed by delete entry messages to bring the client
1112    copy to the current state.  In the latter case, the present entry
1113    messages bring the client copy to a state covered by the history
1114    information maintained in the server.
1115
1116    The server SHOULD maintain enough (current or historical) state
1117    information (such as a context-wide last modify time stamp) to
1118    determine if no changes were made in the context since the content
1119
1120
1121
1122 Zeilenga & Choi               Experimental                     [Page 20]
1123 \f
1124 RFC 4533         LDAP Content Synchronization Operation        June 2006
1125
1126
1127    refresh was provided and, when no changes were made, generate zero
1128    delete entry messages instead of present messages.
1129
1130    The server SHOULD NOT use the history information when its use does
1131    not reduce the synchronization traffic or when its use can expose
1132    sensitive information not allowed to be received by the client.
1133
1134    The server implementor should also consider chattiness issues that
1135    span multiple Sync Operations of a session.  As noted in Section 3.8,
1136    the server may return e-syncRefreshRequired if it determines that a
1137    reload would be more efficient than continuing under the current
1138    operation.  If reloadHint in the Sync Request is TRUE, the server may
1139    initiate a reload without directing the client to request a reload.
1140
1141    The server SHOULD transfer a new cookie frequently to avoid having to
1142    transfer information already provided to the client.  Even where DIT
1143    changes do not cause content synchronization changes to be
1144    transferred, it may be advantageous to provide a new cookie using a
1145    Sync Info Message.  However, the server SHOULD avoid overloading the
1146    client or network with Sync Info Messages.
1147
1148    During persist mode, the server SHOULD coalesce multiple outstanding
1149    messages updating the same entry.  The server MAY delay generation of
1150    an entry update in anticipation of subsequent changes to that entry
1151    that could be coalesced.  The length of the delay should be long
1152    enough to allow coalescing of update requests issued back to back but
1153    short enough that the transient inconsistency induced by the delay is
1154    corrected in a timely manner.
1155
1156    The server SHOULD use the syncIdSet Sync Info Message when there are
1157    multiple delete or present messages to reduce the amount of
1158    synchronization traffic.
1159
1160    Also note that there may be many clients interested in a particular
1161    directory change, and that servers attempting to service all of these
1162    at once may cause congestion on the network.  The congestion issues
1163    are magnified when the change requires a large transfer to each
1164    interested client.  Implementors and deployers of servers should take
1165    steps to prevent and manage network congestion.
1166
1167 3.10.  Operation Multiplexing
1168
1169    The LDAP protocol model [RFC4511] allows operations to be multiplexed
1170    over a single LDAP session.  Clients SHOULD NOT maintain multiple
1171    LDAP sessions with the same server.  Servers SHOULD ensure that
1172    responses from concurrently processed operations are interleaved
1173    fairly.
1174
1175
1176
1177
1178 Zeilenga & Choi               Experimental                     [Page 21]
1179 \f
1180 RFC 4533         LDAP Content Synchronization Operation        June 2006
1181
1182
1183    Clients SHOULD combine Sync Operations whose result set is largely
1184    overlapping.  This avoids having to return multiple messages, once
1185    for each overlapping session, for changes to entries in the overlap.
1186
1187    Clients SHOULD NOT combine Sync Operations whose result sets are
1188    largely non-overlapping.  This ensures that an event requiring an
1189    e-syncRefreshRequired response can be limited to as few result sets
1190    as possible.
1191
1192 4.  Meta Information Considerations
1193
1194 4.1.  Entry DN
1195
1196    As an entry's DN is constructed from its relative DN (RDN) and the
1197    entry's parent's DN, it is often viewed as meta information.
1198
1199    While renaming or moving to a new superior causes the entry's DN to
1200    change, that change SHOULD NOT, by itself, cause synchronization
1201    messages to be sent for that entry.  However, if the renaming or the
1202    moving could cause the entry to be added or deleted from the content,
1203    appropriate synchronization messages should be generated to indicate
1204    this to the client.
1205
1206    When a server treats the entry's DN as meta information, the server
1207    SHALL either
1208
1209       -  evaluate all MatchingRuleAssertions [RFC4511] to TRUE if
1210          matching a value of an attribute of the entry, otherwise
1211          Undefined, or
1212
1213       -  evaluate all MatchingRuleAssertion with dnAttributes of TRUE as
1214          Undefined.
1215
1216    The latter choice is offered for ease of server implementation.
1217
1218 4.2.  Operational Attributes
1219
1220    Where values of an operational attribute are determined by values not
1221    held as part of the entry it appears in, the operational attribute
1222    SHOULD NOT support synchronization of that operational attribute.
1223
1224    For example, in servers that implement the X.501 subschema model
1225    [X.501], servers should not support synchronization of the
1226    subschemaSubentry attribute as its value is determined by values held
1227    and administrated in subschema subentries.
1228
1229
1230
1231
1232
1233
1234 Zeilenga & Choi               Experimental                     [Page 22]
1235 \f
1236 RFC 4533         LDAP Content Synchronization Operation        June 2006
1237
1238
1239    As a counter example, servers that implement aliases [RFC4512][X.501]
1240    can support synchronization of the aliasedObjectName attribute as its
1241    values are held and administrated as part of the alias entries.
1242
1243    Servers SHOULD support synchronization of the following operational
1244    attributes: createTimestamp, modifyTimestamp, creatorsName,
1245    modifiersName [RFC4512].  Servers MAY support synchronization of
1246    other operational attributes.
1247
1248 4.3.  Collective Attributes
1249
1250    A collective attribute is "a user attribute whose values are the same
1251    for each member of an entry collection" [X.501].  Use of collective
1252    attributes in LDAP is discussed in [RFC3671].
1253
1254    Modification of a collective attribute generally affects the content
1255    of multiple entries, which are the members of the collection.  It is
1256    inefficient to include values of collective attributes visible in
1257    entries of the collection, as a single modification of a collective
1258    attribute requires transmission of multiple SearchResultEntry (one
1259    for each entry of the collection that the modification affected).
1260
1261    Servers SHOULD NOT synchronize collective attributes appearing in
1262    entries of any collection.  Servers MAY support synchronization of
1263    collective attributes appearing in collective attribute subentries.
1264
1265 4.4.  Access and Other Administrative Controls
1266
1267    Entries are commonly subject to access and other administrative
1268    Controls.  While portions of the policy information governing a
1269    particular entry may be held in the entry, policy information is
1270    often held elsewhere (in superior entries, in subentries, in the root
1271    DSE, in configuration files, etc.).  Because of this, changes to
1272    policy information make it difficult to ensure eventual convergence
1273    during incremental synchronization.
1274
1275    Where it is impractical or infeasible to generate content changes
1276    resulting from a change to policy information, servers may opt to
1277    return e-syncRefreshRequired or to treat the Sync Operation as an
1278    initial content request (e.g., ignore the cookie or the
1279    synchronization state represented in the cookie).
1280
1281 5.  Interaction with Other Controls
1282
1283    The Sync Operation may be used with:
1284
1285       - ManageDsaIT Control [RFC3296]
1286
1287
1288
1289
1290 Zeilenga & Choi               Experimental                     [Page 23]
1291 \f
1292 RFC 4533         LDAP Content Synchronization Operation        June 2006
1293
1294
1295       - Subentries Control [RFC3672]
1296
1297    as described below.  The Sync Operation may be used with other LDAP
1298    extensions as detailed in other documents.
1299
1300 5.1.  ManageDsaIT Control
1301
1302    The ManageDsaIT Control [RFC3296] indicates that the operation acts
1303    upon the DSA Information Tree and causes referral and other special
1304    entries to be treated as object entries with respect to the
1305    operation.
1306
1307 5.2.  Subentries Control
1308
1309    The Subentries Control is used with the search operation "to control
1310    the visibility of entries and subentries which are within scope"
1311    [RFC3672].  When used with the Sync Operation, the subentries control
1312    and other factors (search scope, filter, etc.) are used to determine
1313    whether an entry or subentry appears in the content.
1314
1315 6.  Shadowing Considerations
1316
1317    As noted in [RFC4511], some servers may hold shadow copies of entries
1318    that can be used to answer search and comparison queries.  Such
1319    servers may also support content synchronization requests.  This
1320    section discusses considerations for implementors and deployers for
1321    the implementation and deployment of the Sync operation in shadowed
1322    directories.
1323
1324    While a client may know of multiple servers that are equally capable
1325    of being used to obtain particular directory content from, a client
1326    SHOULD NOT assume that each of these servers is equally capable of
1327    continuing a content synchronization session.  As stated in Section
1328    3.1, the client SHOULD issue each Sync request of a Sync session to
1329    the same server.
1330
1331    However, through domain naming or IP address redirection or other
1332    techniques, multiple physical servers can be made to appear as one
1333    logical server to a client.  Only servers that are equally capable in
1334    regards to their support for the Sync operation and that hold equally
1335    complete copies of the entries should be made to appear as one
1336    logical server.  In particular, each physical server acting as one
1337    logical server SHOULD be equally capable of continuing a content
1338    synchronization based upon cookies provided by any of the other
1339    physical servers without requiring a full reload.  Because there is
1340    no standard LDAP shadowing mechanism, the specification of how to
1341    independently implement equally capable servers (as well as the
1342    precise definition of "equally capable") is left to future documents.
1343
1344
1345
1346 Zeilenga & Choi               Experimental                     [Page 24]
1347 \f
1348 RFC 4533         LDAP Content Synchronization Operation        June 2006
1349
1350
1351    Note that it may be difficult for the server to reliably determine
1352    what content was provided to the client by another server, especially
1353    in the shadowing environments that allow shadowing events to be
1354    coalesced.  For these servers, the use of the delete phase discussed
1355    in Section 3.3.2 may not be applicable.
1356
1357 7.  Security Considerations
1358
1359    In order to maintain a synchronized copy of the content, a client is
1360    to delete information from its copy of the content as described
1361    above.  However, the client may maintain knowledge of information
1362    disclosed to it by the server separate from its copy of the content
1363    used for synchronization.  Management of this knowledge is beyond the
1364    scope of this document.  Servers should be careful not to disclose
1365    information for content the client is not authorized to have
1366    knowledge of and/or about.
1367
1368    While the information provided by a series of refreshOnly Sync
1369    Operations is similar to that provided by a series of Search
1370    Operations, persist stage may disclose additional information.  A
1371    client may be able to discern information about the particular
1372    sequence of update operations that caused content change.
1373
1374    Implementors should take precautions against malicious cookie
1375    content, including malformed cookies or valid cookies used with
1376    different security associations and/or protections in an attempt to
1377    obtain unauthorized access to information.  Servers may include a
1378    digital signature in the cookie to detect tampering.
1379
1380    The operation may be the target of direct denial-of-service attacks.
1381    Implementors should provide safeguards to ensure the operation is not
1382    abused.  Servers may place access control or other restrictions upon
1383    the use of this operation.
1384
1385    Note that even small updates to the directory may cause a significant
1386    amount of traffic to be generated to clients using this operation.  A
1387    user could abuse its update privileges to mount an indirect denial of
1388    service to these clients, other clients, and/or portions of the
1389    network.  Servers should provide safeguards to ensure that update
1390    operations are not abused.
1391
1392    Implementors of this (or any) LDAP extension should be familiar with
1393    general LDAP security considerations [RFC4510].
1394
1395
1396
1397
1398
1399
1400
1401
1402 Zeilenga & Choi               Experimental                     [Page 25]
1403 \f
1404 RFC 4533         LDAP Content Synchronization Operation        June 2006
1405
1406
1407 8.  IANA Considerations
1408
1409    Registration of the following values have been completed by the IANA
1410    [RFC4520].
1411
1412 8.1.  Object Identifier
1413
1414    The OID arc 1.3.6.1.4.1.4203.1.9.1 was assigned [ASSIGN] by the
1415    OpenLDAP Foundation, under its IANA-assigned private enterprise
1416    allocation [PRIVATE], for use in this specification.
1417
1418 8.2.  LDAP Protocol Mechanism
1419
1420    The IANA has registered the LDAP Protocol Mechanism described in this
1421    document.
1422
1423       Subject: Request for LDAP Protocol Mechanism Registration
1424       Object Identifier: 1.3.6.1.4.1.4203.1.9.1.1
1425       Description: LDAP Content Synchronization Control
1426       Person & email address to contact for further information:
1427           Kurt Zeilenga <kurt@openldap.org>
1428       Usage: Control
1429       Specification: RFC 4533
1430       Author/Change Controller: Kurt D. Zeilenga, Jong Hyuk Choi
1431       Comments: none
1432
1433 8.3.  LDAP Result Codes
1434
1435    The IANA has registered the LDAP Result Code described in this
1436    document.
1437
1438       Subject: LDAP Result Code Registration
1439       Person & email address to contact for further information:
1440           Kurt Zeilenga <kurt@OpenLDAP.org>
1441       Result Code Name: e-syncRefreshRequired (4096)
1442       Specification: RFC 4533
1443       Author/Change Controller: Kurt D. Zeilenga, Jong Hyuk Choi
1444       Comments:  none
1445
1446 9.  Acknowledgements
1447
1448    This document borrows significantly from the LDAP Client Update
1449    Protocol [RFC3928], a product of the IETF LDUP working group.  This
1450    document also benefited from Persistent Search [PSEARCH], Triggered
1451    Search [TSEARCH], and Directory Synchronization [DIRSYNC] works.
1452    This document also borrows from "Lightweight Directory Access
1453    Protocol (v3)" [RFC2251].
1454
1455
1456
1457
1458 Zeilenga & Choi               Experimental                     [Page 26]
1459 \f
1460 RFC 4533         LDAP Content Synchronization Operation        June 2006
1461
1462
1463 10.  Normative References
1464
1465    [RFC2119]   Bradner, S., "Key words for use in RFCs to Indicate
1466                Requirement Levels", BCP 14, RFC 2119, March 1997.
1467
1468    [RFC3296]   Zeilenga, K., "Named Subordinate References in
1469                Lightweight Directory Access Protocol (LDAP)
1470                Directories", RFC 3296, July 2002.
1471
1472    [RFC3671]   Zeilenga, K., "Collective Attributes in the Lightweight
1473                Directory Access Protocol (LDAP)", RFC 3671, December
1474                2003.
1475
1476    [RFC3672]   Zeilenga, K., "Subentries in the Lightweight Directory
1477                Access Protocol (LDAP)", RFC 3672, December 2003.
1478
1479    [RFC3909]   Zeilenga, K., "Lightweight Directory Access Protocol
1480                (LDAP) Cancel Operation", RFC 3909, October 2004.
1481
1482    [RFC4510]   Zeilenga, K., Ed., "Lightweight Directory Access Protocol
1483                (LDAP): Technical Specification Road Map", RFC 4510, June
1484                2006.
1485
1486    [RFC4511]   Sermersheim, J., Ed., "Lightweight Directory Access
1487                Protocol (LDAP): The Protocol", RFC 4511, June 2006.
1488
1489    [RFC4512]   Zeilenga, K., "Lightweight Directory Access Protocol
1490                (LDAP): Directory Information Models", RFC 4512, June
1491                2006.
1492
1493    [RFC4530]   Zeilenga, K., "Lightweight Directory Access Protocol
1494                (LDAP) entryUUID Operational Attribute", RFC 4530, June
1495                2006.
1496
1497    [UUID]      International Organization for Standardization (ISO),
1498                "Information technology - Open Systems Interconnection -
1499                Remote Procedure Call", ISO/IEC 11578:1996
1500
1501    [X.501]     International Telecommunication Union - Telecommunication
1502                Standardization Sector, "The Directory -- Models,"
1503                X.501(1993) (also ISO/IEC 9594-2:1994).
1504
1505    [X.680]     International Telecommunication Union - Telecommunication
1506                Standardization Sector, "Abstract Syntax Notation One
1507                (ASN.1) - Specification of Basic Notation", X.680(1997)
1508                (also ISO/IEC 8824-1:1998).
1509
1510
1511
1512
1513
1514 Zeilenga & Choi               Experimental                     [Page 27]
1515 \f
1516 RFC 4533         LDAP Content Synchronization Operation        June 2006
1517
1518
1519    [X.690]     International Telecommunication Union - Telecommunication
1520                Standardization Sector, "Specification of ASN.1 encoding
1521                rules: Basic Encoding Rules (BER), Canonical Encoding
1522                Rules (CER), and Distinguished Encoding Rules (DER)",
1523                X.690(1997) (also ISO/IEC 8825-1:1998).
1524
1525 11.  Informative References
1526
1527    [RFC2251]   Wahl, M., Howes, T., and S. Kille, "Lightweight Directory
1528                Access Protocol (v3)", RFC 2251, December 1997.
1529
1530    [RFC3928]   Megginson, R., Ed., Smith, M., Natkovich, O., and J.
1531                Parham, "Lightweight Directory Access Protocol (LDAP)
1532                Client Update Protocol (LCUP)", RFC 3928, October 2004.
1533
1534    [RFC4520]   Zeilenga, K., "Internet Assigned Numbers Authority (IANA)
1535                Considerations for the Lightweight Directory Access
1536                Protocol (LDAP)", BCP 64, RFC 4520, June 2006.
1537
1538    [PRIVATE]   IANA, "Private Enterprise Numbers",
1539                http://www.iana.org/assignments/enterprise-numbers.
1540
1541    [ASSIGN]    OpenLDAP Foundation, "OpenLDAP OID Delegations",
1542                http://www.openldap.org/foundation/oid-delegate.txt.
1543
1544    [X.500]     International Telecommunication Union - Telecommunication
1545                Standardization Sector, "The Directory -- Overview of
1546                concepts, models and services," X.500(1993) (also ISO/IEC
1547                9594-1:1994).
1548
1549    [X.525]     International Telecommunication Union - Telecommunication
1550                Standardization Sector, "The Directory: Replication",
1551                X.525(1993).
1552
1553    [DIRSYNC]   Armijo, M., "Microsoft LDAP Control for Directory
1554                Synchronization", Work in Progress.
1555
1556    [PSEARCH]   Smith, M., et al., "Persistent Search: A Simple LDAP
1557                Change Notification Mechanism", Work in Progress.
1558
1559    [TSEARCH]   Wahl, M., "LDAPv3 Triggered Search Control", Work in
1560                Progress.
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570 Zeilenga & Choi               Experimental                     [Page 28]
1571 \f
1572 RFC 4533         LDAP Content Synchronization Operation        June 2006
1573
1574
1575 Appendix A.  CSN-based Implementation Considerations
1576
1577    This appendix is provided for informational purposes only; it is not
1578    a normative part of the LDAP Content Synchronization Operation's
1579    technical specification.
1580
1581    This appendix discusses LDAP Content Synchronization Operation server
1582    implementation considerations associated with Change Sequence Number
1583    based approaches.
1584
1585    Change Sequence Number based approaches are targeted for use in
1586    servers that do not maintain history information (e.g., change logs,
1587    state snapshots) about changes made to the Directory and hence, must
1588    rely on current directory state and minimal synchronization state
1589    information embedded in Sync Cookie.  Servers that maintain history
1590    information should consider other approaches that exploit the history
1591    information.
1592
1593    A Change Sequence Number is effectively a time stamp that has
1594    sufficient granularity to ensure that the precedence relationship in
1595    time of two updates to the same object can be determined.  Change
1596    Sequence Numbers are not to be confused with Commit Sequence Numbers
1597    or Commit Log Record Numbers.  A Commit Sequence Number allows one to
1598    determine how two commits (to the same object or different objects)
1599    relate to each other in time.  A Change Sequence Number associated
1600    with different entries may be committed out of order.  In the
1601    remainder of this Appendix, the term CSN refers to a Change Sequence
1602    Number.
1603
1604    In these approaches, the server not only maintains a CSN for each
1605    directory entry (the entry CSN) but also maintains a value that we
1606    will call the context CSN.  The context CSN is the greatest committed
1607    entry CSN that is not greater than any outstanding (uncommitted)
1608    entry CSNs for all entries in a directory context.  The values of
1609    context CSN are used in syncCookie values as synchronization state
1610    indicators.
1611
1612    As search operations are not isolated from individual directory
1613    update operations and individual update operations cannot be assumed
1614    to be serialized, one cannot assume that the returned content
1615    incorporates each relevant change whose change sequence number is
1616    less than or equal to the greatest entry CSN in the content.  The
1617    content incorporates all the relevant changes whose change sequence
1618    numbers are less than or equal to context CSN before search
1619    processing.  The content may also incorporate any subset of the
1620    changes whose change sequence number is greater than context CSN
1621    before search processing but less than or equal to the context CSN
1622    after search processing.  The content does not incorporate any of the
1623
1624
1625
1626 Zeilenga & Choi               Experimental                     [Page 29]
1627 \f
1628 RFC 4533         LDAP Content Synchronization Operation        June 2006
1629
1630
1631    changes whose CSN is greater than the context CSN after search
1632    processing.
1633
1634    A simple server implementation could use the value of the context CSN
1635    before search processing to indicate state.  Such an implementation
1636    would embed this value into each SyncCookie returned.  We'll call
1637    this the cookie CSN.  When a refresh was requested, the server would
1638    simply generate "update" messages for all entries in the content
1639    whose CSN is greater than the supplied cookie CSN and generate
1640    "present" messages for all other entries in the content.  However, if
1641    the current context CSN is the same as the cookie CSN, the server
1642    should instead generate zero "updates" and zero "delete" messages and
1643    indicate a refreshDeletes of TRUE, as the directory has not changed.
1644
1645    The implementation should also consider the impact of changes to meta
1646    information, such as access controls, that affect content
1647    determination.  One approach is for the server to maintain a
1648    context-wide meta information CSN or meta CSN.  This meta CSN would
1649    be updated whenever meta information affecting content determination
1650    was changed.  If the value of the meta CSN is greater than the cookie
1651    CSN, the server should ignore the cookie and treat the request as an
1652    initial request for content.
1653
1654    Additionally, servers may want to consider maintaining some per-
1655    session history information to reduce the number of messages needed
1656    to be transferred during incremental refreshes.  Specifically, a
1657    server could record information about entries as they leave the scope
1658    of a disconnected sync session and later use this information to
1659    generate delete messages instead of present messages.
1660
1661    When the history information is truncated, the CSN of the latest
1662    truncated history information entry may be recorded as the truncated
1663    CSN of the history information.  The truncated CSN may be used to
1664    determine whether a client copy can be covered by the history
1665    information by comparing it to the synchronization state contained in
1666    the cookie supplied by the client.
1667
1668    When there is a large number of sessions, it may make sense to
1669    maintain such history only for the selected clients.  Also, servers
1670    taking this approach need to consider resource consumption issues to
1671    ensure reasonable server operation and to protect against abuse.  It
1672    may be appropriate to restrict this mode of operation by policy.
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682 Zeilenga & Choi               Experimental                     [Page 30]
1683 \f
1684 RFC 4533         LDAP Content Synchronization Operation        June 2006
1685
1686
1687 Authors' Addresses
1688
1689    Kurt D. Zeilenga
1690    OpenLDAP Foundation
1691
1692    EMail: Kurt@OpenLDAP.org
1693
1694
1695    Jong Hyuk Choi
1696    IBM Corporation
1697
1698    EMail: jongchoi@us.ibm.com
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738 Zeilenga & Choi               Experimental                     [Page 31]
1739 \f
1740 RFC 4533         LDAP Content Synchronization Operation        June 2006
1741
1742
1743 Full Copyright Statement
1744
1745    Copyright (C) The Internet Society (2006).
1746
1747    This document is subject to the rights, licenses and restrictions
1748    contained in BCP 78 and at www.rfc-editor.org/copyright.html, and
1749    except as set forth therein, the authors retain all their rights.
1750
1751    This document and the information contained herein are provided on an
1752    "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
1753    OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
1754    ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
1755    INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
1756    INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
1757    WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1758
1759 Intellectual Property
1760
1761    The IETF takes no position regarding the validity or scope of any
1762    Intellectual Property Rights or other rights that might be claimed to
1763    pertain to the implementation or use of the technology described in
1764    this document or the extent to which any license under such rights
1765    might or might not be available; nor does it represent that it has
1766    made any independent effort to identify any such rights.  Information
1767    on the procedures with respect to rights in RFC documents can be
1768    found in BCP 78 and BCP 79.
1769
1770    Copies of IPR disclosures made to the IETF Secretariat and any
1771    assurances of licenses to be made available, or the result of an
1772    attempt made to obtain a general license or permission for the use of
1773    such proprietary rights by implementers or users of this
1774    specification can be obtained from the IETF on-line IPR repository at
1775    http://www.ietf.org/ipr.
1776
1777    The IETF invites any interested party to bring to its attention any
1778    copyrights, patents or patent applications, or other proprietary
1779    rights that may cover technology that may be required to implement
1780    this standard.  Please address the information to the IETF at
1781    ietf-ipr@ietf.org.
1782
1783 Acknowledgement
1784
1785    Funding for the RFC Editor function is provided by the IETF
1786    Administrative Support Activity (IASA).
1787
1788
1789
1790
1791
1792
1793
1794 Zeilenga & Choi               Experimental                     [Page 32]
1795 \f