idnits 2.17.1 draft-zeilenga-ldup-sync-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3667, Section 5.1 on line 23. -- Found old boilerplate from RFC 3978, Section 5.5 on line 1439. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1412. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1419. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1425. ** Found boilerplate matching RFC 3978, Section 5.4, paragraph 1 (on line 1431), which is fine, but *also* found old RFC 2026, Section 10.4C, paragraph 1 text on line 39. ** The document seems to lack an RFC 3978 Section 5.1 IPR Disclosure Acknowledgement -- however, there's a paragraph with a matching beginning. Boilerplate error? ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. ** The document uses RFC 3667 boilerplate or RFC 3978-like boilerplate instead of verbatim RFC 3978 boilerplate. After 6 May 2005, submission of drafts without verbatim RFC 3978 boilerplate is not accepted. The following non-3978 patterns matched text found in the document. That text should be removed or replaced: By submitting this Internet-Draft, I certify that any applicable patent or other IPR claims of which I am aware have been disclosed, or will be disclosed, and any of which I become aware will be disclosed, in accordance with RFC 3668. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 9 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 440 has weird spacing: '... cookie syn...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (27 September 2004) is 7144 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '0' on line 467 -- Looks like a reference, but probably isn't: '1' on line 468 -- Looks like a reference, but probably isn't: '2' on line 472 -- Looks like a reference, but probably isn't: '3' on line 476 == Missing Reference: 'RFC3371' is mentioned on line 1030, but not defined == Unused Reference: 'RFC3671' is defined on line 1222, but no explicit reference was found in the text == Unused Reference: 'RFC3383' is defined on line 1260, but no explicit reference was found in the text == Unused Reference: 'UUIDinfo' is defined on line 1282, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2251 (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) ** Obsolete normative reference: RFC 2252 (Obsoleted by RFC 4510, RFC 4512, RFC 4517, RFC 4523) ** Obsolete normative reference: RFC 3377 (Obsoleted by RFC 4510) -- No information found for draft-zeilenga-ldap-cancel-xx - is the name correct? -- No information found for draft-zeilenga-ldap-uuid-xx - is the name correct? == Outdated reference: A later version (-01) exists of draft-rharrison-ldap-intermediate-resp-00 -- Obsolete informational reference (is this intentional?): RFC 2256 (Obsoleted by RFC 4510, RFC 4512, RFC 4517, RFC 4519, RFC 4523) -- Obsolete informational reference (is this intentional?): RFC 3383 (Obsoleted by RFC 4520) -- No information found for draft-armijo-ldap-dirsync-xx - is the name correct? -- No information found for draft-ietf-ldup-lcup-xx - is the name correct? -- No information found for draft-ietf-ldapext-psearch-xx - is the name correct? -- No information found for draft-ietf-ldapext-trigger-xx - is the name correct? Summary: 13 errors (**), 0 flaws (~~), 8 warnings (==), 19 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT Kurt D. Zeilenga 3 Intended Category: Experimental OpenLDAP Foundation 4 Expires in six months Jong Hyuk Choi 5 IBM Corporation 7 27 September 2004 9 The LDAP Content Synchronization Operation 10 12 Status of this Memo 14 Distribution of this memo is unlimited. Technical discussion of this 15 document will take place on the IETF LDUP Working Group mailing list 16 at . Please send editorial comments directly to 17 the document editor at . 19 By submitting this Internet-Draft, I accept the provisions of Section 20 4 of RFC 3667. By submitting this Internet-Draft, I certify that any 21 applicable patent or other IPR claims of which I am aware have been 22 disclosed, or will be disclosed, and any of which I become aware will 23 be disclosed, in accordance with RFC 3668. 25 Internet-Drafts are working documents of the Internet Engineering Task 26 Force (IETF), its areas, and its working groups. Note that other 27 groups may also distribute working documents as Internet-Drafts. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference material 32 or to cite them other than as "work in progress." 34 The list of current Internet-Drafts can be accessed at 35 . The list of 36 Internet-Draft Shadow Directories can be accessed at 37 . 39 Copyright (C) The Internet Society (2004). All Rights Reserved. 41 Please see the Full Copyright section near the end of this document 42 for more information. 44 Abstract 46 This specification describes the LDAP (Lightweight Directory Access 47 Protocol) Content Synchronization Operation. The operation allows a 48 client to maintain a copy of a fragment of directory information tree. 49 It supports both polling for changes and listening for changes. The 50 operation is defined as an extension of the LDAP Search Operation. 52 Table of Contents 54 Status of this Memo 1 55 Abstract 2 56 Table of Contents 57 1. Introduction 3 58 1.1. Background 59 1.2. Intended Usage 4 60 1.3. Overview 5 61 1.4. Conventions 8 62 2. Elements of the Sync Operation 63 2.1. Common ASN.1 Elements 9 64 2.2. Sync Request Control 65 2.3. Sync State Control 10 66 2.4. Sync Done Control 67 2.5. Sync Info Message 68 2.6. Sync Result Codes 11 69 3. Content Synchronization 70 3.1. Synchronization Session 12 71 3.2. Content Determination 72 3.3. refreshOnly Mode 13 73 3.4. refreshAndPersist Mode 16 74 3.5. Search Request Parameters 17 75 3.6. objectName Issues 18 76 3.7. Canceling the Sync Operation 19 77 3.8. Refresh Required 78 3.9. Chattiness Considerations 20 79 3.10. Operation Multiplexing 21 80 4. Meta Information Considerations 22 81 4.1. Entry DN 82 4.2. Operational Attributes 83 4.3. Collective Attributes 23 84 4.4. Access and Other Administrative Controls 85 5. Interaction with Other Controls 24 86 5.1. ManageDsaIT Control 87 5.2. Subentries Control 88 6. Shadowing Considerations 89 7. Security Considerations 25 90 8. IANA Considerations 26 91 8.1. Object Identifier 92 8.2. LDAP Protocol Mechanism 93 8.3. LDAP Result Codes 94 9. Acknowledgments 95 10. Normative References 27 96 11. Informative References 28 97 12. Authors' Addresses 29 98 Appendix A. CSN-based Implementation Considerations 99 Intellectual Property Rights 31 100 Full Copyright 32 102 1. Introduction 104 The Lightweight Directory Access Protocol (LDAP) [RFC3377] provides a 105 mechanism, the search operation [RFC2251], which allows a client to 106 request directory content matching a complex set of assertions and for 107 the server to return this content, subject to access control and other 108 restrictions, to the client. However, LDAP does not provide (despite 109 the introduction of numerous extensions in this area) an effective and 110 efficient mechanism for maintaining synchronized copies of directory 111 content. This document introduces a new mechanism specifically 112 designed to met the content synchronization requirements of 113 sophisticated directory applications. 115 This document defines the LDAP Content Synchronization Operation, or 116 Sync Operation for short, which allows a client to maintain a 117 synchronized copy of a fragment of a Directory Information Tree (DIT). 118 The Sync Operation is defined as a set of controls and other protocol 119 elements which extend the Search Operation. 121 1.1. Background 123 Over the years, a number of content synchronization approaches have 124 been suggested for use in LDAP directory services. These approaches 125 are inadequate for one or more of the following reasons: 127 - fail to ensure a reasonable level of convergence; 128 - fail to detect that convergence cannot be achieved (without 129 reload); 130 - require pre-arranged synchronization agreements; 131 - require the server to maintain histories of past changes to DIT 132 content and/or meta information; 133 - require the server to maintain synchronization state on a per 134 client basis; and/or 135 - are overly chatty. 137 The Sync Operation provides eventual convergence of synchronized 138 content when possible and, when not, notification that a full reload 139 is required. 141 The Sync Operation does not require pre-arranged synchronization 142 agreements. 144 The Sync Operation does not require servers to maintain nor to use any 145 history of past changes to the DIT or to meta information. However, 146 servers may maintain and use histories (e.g., change logs, tombstones, 147 DIT snapshots) to reduce the number of messages generated and to 148 reduce their size. As it is not always feasible to maintain and use 149 histories, the operation may be implemented using purely (current) 150 state-based approaches. The Sync Operation allows use of either the 151 state-based approach or the history-based approach in an operation by 152 operation basis to balance the size of history and the amount of 153 traffic. The Sync Operation also allows the combined use of the 154 state-based and the history-based approaches. 156 The Sync Operation does not require servers to maintain 157 synchronization state on a per client basis. However, servers may 158 maintain and use per client state information to reduce the number of 159 messages generated and the size of such messages. 161 A synchronization mechanism can be considered overly chatty when 162 synchronization traffic is not reasonably bounded. The Sync Operation 163 traffic is bounded by the size of updated (or new) entries and the 164 number of unchanged entries in the content. The operation is designed 165 to avoid full content exchanges even in the case that the history 166 information available to the server is insufficient to determine the 167 client's state. The operation is also designed to avoid transmission 168 of out-of-content history information, as its size is not bounded by 169 the content and it is not always feasible to transmit such history 170 information due to security reasons. 172 This document includes a number of non-normative appendices providing 173 additional information to server implementors. 175 1.2. Intended Usage 177 The Sync Operation is intended to be used in applications requiring 178 eventually-convergent content synchronization. Upon completion of 179 each synchronization stage of the operation, all information to 180 construct a synchronized client copy of the content has been provided 181 to the client or the client has been notified that a complete content 182 reload is necessary. Except for transient inconsistencies due to 183 concurrent operation (or other) processing at the server, the client 184 copy is an accurate reflection of the content held by the server. 185 Transient inconsistencies will be resolved by subsequent 186 synchronization operations. 188 Possible uses include: 189 - White page service applications may use the Sync Operation to 190 maintain current copy of a DIT fragment. For example, a mail user 191 agent which uses the sync operation to maintain a local copy of an 192 enterprise address book. 194 - Meta-information engines may use the Sync Operation to maintain a 195 copy of a DIT fragment. 197 - Caching proxy services may use the Sync Operation to maintain a 198 coherent content cache. 200 - Lightweight master-slave replication between heterogeneous 201 directory servers. For example, the Sync Operation can be used by 202 a slave server to maintain a shadow copy of a DIT fragment. 203 (Note: The International Telephone Union (ITU) has defined the 204 X.500 Directory [X.500] Information Shadowing Protocol (DISP) 205 [X.525] which may be used for master-slave replication between 206 directory servers. Other experimental LDAP replication protocols 207 also exist.) 209 This protocol is not intended to be used in applications requiring 210 transactional data consistency. 212 As this protocol transfers all visible values of entries belonging to 213 the content upon change instead of change deltas, this protocol is not 214 appropriate for bandwidth-challenged applications or deployments. 216 1.3. Overview 218 This section provides an overview of basic ways the Sync Operation can 219 be used to maintain a synchronized client copy of a DIT fragment. 221 - Polling for Changes: refreshOnly mode 222 - Listening for Changes: refreshAndPersist mode 224 1.3.1. Polling for Changes (refreshOnly) 226 To obtain its initial client copy, the client issues a Sync request: a 227 search request with the Sync Request Control with mode set to 228 refreshOnly. The server, much like it would with a normal search 229 operation, returns (subject to access controls and other restrictions) 230 the content matching the search criteria (baseObject, scope, filter, 231 attributes). Additionally, with each entry returned, the server 232 provides a Sync State Control indicating state add. This control 233 contains the Universally Unique Identifier (UUID) [UUID] of the entry 234 [EntryUUID]. Unlike the Distinguished Name (DN), which may change 235 over time, an entry's UUID is stable. The initial content is followed 236 by a SearchResultDone with a Sync Done Control. The Sync Done Control 237 provides a syncCookie. The syncCookie represents session state. 239 To poll for updates to the client copy, the client reissues the Sync 240 Operation with the syncCookie previously returned. The server, much 241 as it would with a normal search operation, determines which content 242 would be returned as if the operation was a normal search operation. 243 However, using the syncCookie as an indicator of what content the 244 client was sent previously, the server sends copies of entries which 245 have changed with a Sync State Control indicating state add. For each 246 changed entry, all (modified or unmodified) attributes belonging to 247 the content are sent. 249 The server may perform either or both of the two distinct 250 synchronization phases which are distinguished by how to synchronize 251 entries deleted from the content: the present and the delete phases. 252 When the server uses a single phase for the refresh stage, each phase 253 is marked as ended by a SearchResultDone with a Sync Done Control. A 254 present phase is identified by a FALSE refreshDeletes value in the 255 Sync Done Control. A delete phase is identified by a TRUE 256 refreshDeletes value. The present phase may be followed by a delete 257 phase. The two phases are delimited by a refreshPresent Sync Info 258 Message having a FALSE refreshDone value. In the case that both the 259 phases are used, the present phase is used to bring the client copy up 260 to the state at which the subsequent delete phase can begin. 262 In the present phase, the server sends an empty entry (i.e., no 263 attributes) with a Sync State Control indicating state present for 264 each unchanged entry. 266 The delete phase may be used when the server can reliably determine 267 which entries in the prior client copy are no longer present in the 268 content and the number of such entries is less than or equal to the 269 number of unchanged entries. In the delete mode, the server sends an 270 empty entry with a Sync State Control indicating state delete for each 271 entry which is no longer in the content, instead of returning an empty 272 entry with state present for each present entry. 274 The server may send syncIdSet Sync Info Messages containing the set of 275 UUIDs of either unchanged present entries or deleted entries, instead 276 of sending multiple individual messages. If refreshDeletes of 277 syncIdSet is set to FALSE, the UUIDs of unchanged present entries are 278 contained in the syncUUIDs set; if refreshDeletes of syncIdSet is set 279 to TRUE, the UUIDs of the entries no longer present in the content are 280 contained in the syncUUIDs set. An optional cookie can be included in 281 the syncIdSet to represent the state of the content after 282 synchronizing the presence or the absence of the entries contained in 283 the syncUUIDs set. 285 The synchronized copy of the DIT fragment is constructed by the 286 client. 288 If refreshDeletes of syncDoneValue is FALSE, the new copy includes all 289 changed entries returned by the reissued Sync Operation as well as all 290 unchanged entries identified as being present by the reissued Sync 291 Operation, but whose content is provided by the previous Sync 292 Operation. The unchanged entries not identified as being present are 293 deleted from the client content. They had been either deleted, moved, 294 or otherwise scoped-out from the content. 296 If refreshDeletes of syncDoneValue is TRUE, the new copy includes all 297 changed entries returned by the reissued Sync Operation as well as all 298 other entries of the previous copy except for those which are 299 identified as having been deleted from the content. 301 The client can, at some later time, re-poll for changes to this 302 synchronized client copy. 304 1.3.2. Listening for Changes (refreshAndPersist) 306 Polling for changes can be expensive in terms of server, client, and 307 network resources. The refreshAndPersist mode allows for active 308 updates of changed entries in the content. 310 By selecting the refreshAndPersist mode, the client requests the 311 server to send updates of entries that are changed after the initial 312 refresh content is determined. Instead of sending a SearchResultDone 313 Message as in polling, the server sends a Sync Info Message to the 314 client indicating that the refresh stage is complete and then enters 315 the persist stage. After receipt of this Sync Info Message, the 316 client will construct a synchronized copy as described in Section 317 1.3.1. 319 The server may then send change notifications as the result of the 320 original Sync search request which now remains persistent in the 321 server. For entries to be added to the returned content, the server 322 sends a SearchResultEntry (with attributes) with a Sync State Control 323 indicating state add. For entries to be deleted from the content, the 324 server sends a SearchResultEntry containing no attributes and a Sync 325 State Control indicating state delete. For entries to be modified in 326 the return content, the server sends a SearchResultEntry (with 327 attributes) with a Sync State Control indicating state modify. Upon 328 modification of an entry, all (modified or unmodified) attributes 329 belonging to the content are sent. 331 Note that renaming an entry of the DIT may cause an add state change 332 where the entry is renamed into the content, a delete state change 333 where the entry is renamed out of the content, and a modify state 334 change where the entry remains in the content. Also note that a 335 modification of an entry of the DIT may cause an add, delete, or 336 modify state change to the content. 338 Upon receipt of a change notification, the client updates its copy of 339 the content. 341 If the server desires to update the syncCookie during the persist 342 stage, it may include the syncCookie in any Sync State Control or Sync 343 Info Message returned. 345 The operation persists until canceled [CANCEL] by the client or 346 terminated by the server. A Sync Done Control shall be attached to 347 SearchResultDone Message to provide a new syncCookie. 349 1.4. Conventions 351 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 352 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 353 document are to be interpreted as described in BCP 14 [RFC2119]. 355 Protocol elements are described using ASN.1 [X.680] with implicit 356 tags. The term "BER-encoded" means the element is to be encoded using 357 the Basic Encoding Rules [X.690] under the restrictions detailed in 358 Section 5.1 of [RFC2251]. 360 2. Elements of the Sync Operation 362 The Sync Operation is defined as an extension to the LDAP Search 363 Operation [RFC2251] where the directory user agent (DUA or client) 364 submits a SearchRequest Message with a Sync Request Control and the 365 directory system agent (DSA or server) responses with zero or more 366 SearchResultEntry Messages, each with a Sync State Control; zero or 367 more SearchResultReference Messages, each with a Sync State Control; 368 zero or more Sync Info Intermediate Response Messages; and a 369 SearchResultDone Message with a Sync Done Control. 371 To allow clients to discover support for this operation, servers 372 implementing this operation SHOULD publish the 373 1.3.6.1.4.1.4203.1.9.1.1 as a value of 'supportedControl' attribute 374 [RFC2252] of the root DSA-specific entry (DSE). A server MAY choose 375 to advertise this extension only when the client is authorized to use 376 it. 378 2.1 Common ASN.1 Elements 380 2.1.1 syncUUID 382 The syncUUID data type is an OCTET STRING holding a 128-bit (16-octet) 383 Universally Unique Identifier (UUID) [UUID]. 385 syncUUID ::= OCTET STRING (SIZE(16)) 386 -- constrained to UUID 388 2.1.2 syncCookie 390 The syncCookie is a notational convenience to indicate that, while the 391 syncCookie type is encoded as an OCTET STRING, its value is an opaque 392 value containing information about the synchronization session and its 393 state. Generally, the session information would include a hash of the 394 operation parameters which the server requires not be changed and the 395 synchronization state information would include a commit (log) 396 sequence number, a change sequence number, or a time stamp. For 397 convenience of description, the term no cookie refers either to null 398 cookie or to a cookie with pre-initialized synchronization state. 400 syncCookie ::= OCTET STRING 402 2.2 Sync Request Control 404 The Sync Request Control is an LDAP Control [RFC2251, Section 4.1.2] 405 where the controlType is the object identifier 406 1.3.6.1.4.1.4203.1.9.1.1 and the controlValue, an OCTET STRING, 407 contains a BER-encoded syncRequestValue. The criticality field is 408 either TRUE or FALSE. 410 syncRequestValue ::= SEQUENCE { 411 mode ENUMERATED { 412 -- 0 unused 413 refreshOnly (1), 414 -- 2 reserved 415 refreshAndPersist (3) 417 }, 418 cookie syncCookie OPTIONAL, 419 reloadHint BOOLEAN DEFAULT FALSE 420 } 422 The Sync Request Control is only applicable to the SearchRequest 423 Message. 425 2.3 Sync State Control 427 The Sync State Control is an LDAP Control [RFC2251, Section 4.1.2] 428 where the controlType is the object identifier 429 1.3.6.1.4.1.4203.1.9.1.2 and the controlValue, an OCTET STRING, 430 contains a BER-encoded syncStateValue. The criticality is FALSE. 432 syncStateValue ::= SEQUENCE { 433 state ENUMERATED { 434 present (0), 435 add (1), 436 modify (2), 437 delete (3) 438 }, 439 entryUUID syncUUID, 440 cookie syncCookie OPTIONAL 441 } 443 The Sync State Control is only applicable to SearchResultEntry and 444 SearchResultReference Messages. 446 2.4 Sync Done Control 448 The Sync Done Control is an LDAP Control [RFC2251, Section 4.1.2] 449 where the controlType is the object identifier 450 1.3.6.1.4.1.4203.1.9.1.3 and the controlValue contains a BER-encoded 451 syncDoneValue. The criticality is FALSE (and hence absent). 453 syncDoneValue ::= SEQUENCE { 454 cookie syncCookie OPTIONAL, 455 refreshDeletes BOOLEAN DEFAULT FALSE 456 } 458 The Sync Done Control is only applicable to SearchResultDone Message. 460 2.5 Sync Info Message 461 The Sync Info Message is an LDAP Intermediate Response Message 462 [LDAPIRM] where responseName is the object identifier 463 1.3.6.1.4.1.4203.1.9.1.4 and responseValue contains a BER-encoded 464 syncInfoValue. The criticality is FALSE (and hence absent). 466 syncInfoValue ::= CHOICE { 467 newcookie [0] syncCookie, 468 refreshDelete [1] SEQUENCE { 469 cookie syncCookie OPTIONAL, 470 refreshDone BOOLEAN DEFAULT TRUE 471 }, 472 refreshPresent [2] SEQUENCE { 473 cookie syncCookie OPTIONAL, 474 refreshDone BOOLEAN DEFAULT TRUE 475 }, 476 syncIdSet [3] SEQUENCE { 477 cookie syncCookie OPTIONAL, 478 refreshDeletes BOOLEAN DEFAULT FALSE, 479 syncUUIDs SET OF syncUUID 480 } 481 } 483 2.6 Sync Result Codes 485 The following LDAP resultCode [RFC2251] is defined: 487 e-syncRefreshRequired (IANA-ASSIGNED-CODE) 489 3. Content Synchronization 491 The Sync Operation is invoked by the client sending a SearchRequest 492 Message with a Sync Request Control. 494 The absence of a cookie or an initialized synchronization state in a 495 cookie indicates a request for initial content while the presence of a 496 cookie representing a state of a client copy indicates a request for 497 content update. Synchronization Sessions are discussed in Section 498 3.1. Content Determination is discussed in Section 3.2. 500 The mode is either refreshOnly or refreshAndPersist. The refreshOnly 501 and refreshAndPersist modes are discussed in Section 3.3 and Section 502 3.4, respectively. The refreshOnly mode consists only of a refresh 503 stage, while the refreshAndPersist mode consists of a refresh stage 504 and a subsequent persist stage. 506 3.1. Synchronization Session 508 A sequence of Sync Operations where the last cookie returned by the 509 server for one operation is provided by the client in the next 510 operation are said to belong to the same Synchronization Session. 512 The client MUST specify the same content controlling parameters (see 513 Section 3.5) in each Search Request of the session. The client SHOULD 514 also issue each Sync request of a session under the same 515 authentication and authorization associations with equivalent 516 integrity and protections. If the server does not recognize the 517 request cookie or the request is made under different associations or 518 non-equivalent protections, the server SHALL return the initial 519 content as if no cookie had been provided or return an empty content 520 with the e-syncRefreshRequired LDAP result code. The decision between 521 the return of the initial content and the return of the empty content 522 with the e-syncRefreshRequired result code MAY be based on reloadHint 523 in the Sync Request Control from the client. If the server recognizes 524 the request cookie as representing empty or initial synchronization 525 state of the client copy, the server SHALL return the initial content. 527 A Synchronization Session may span multiple LDAP sessions between the 528 client and the server. The client SHOULD issue each Sync request of a 529 session to the same server. (Note: Shadowing considerations are 530 discussed in Section 6.) 532 3.2. Content Determination 534 The content to be provided is determined by parameters of the Search 535 Request, as described in [RFC2251], and possibly other controls. The 536 same content parameters SHOULD be used in each Sync request of a 537 session. If different content is requested and the server is 538 unwilling or unable to process the request, the server SHALL return 539 the initial content as if no cookie had been provided or return an 540 empty content with the e-syncRefreshRequired LDAP result code. The 541 decision between the return of the initial content and the return of 542 the empty content with the e-syncRefreshRequired result code MAY be 543 based on reloadHint in the Sync Request Control from the client. 545 The content may not necessarily include all entries or references 546 which would be returned by a normal search operation nor, for those 547 entries included, not all attributes returned by a normal search. 548 When the server is unwilling or unable to provide synchronization for 549 any attribute for a set of entries, the server MUST treat all filter 550 components matching against these attributes as Undefined and MUST NOT 551 return these attributes in SearchResultEntry responses. 553 Servers SHOULD support synchronization for all non-collective 554 user-application attributes for all entries. 556 The server may also return continuation references to other servers or 557 to itself. The latter is allowed as the server may partition the 558 entries it holds into separate synchronization contexts. 560 The client may chase all or some of these continuations, each as a 561 separate content synchronization session. 563 3.3. refreshOnly Mode 565 A Sync request with mode refreshOnly and with no cookie is a poll for 566 initial content. A Sync request with mode refreshOnly and with a 567 cookie representing a synchronization state is a poll for content 568 update. 570 3.3.1. Initial Content Poll 572 Upon receipt of the request, the server provides the initial content 573 using a set of zero or more SearchResultEntry and 574 SearchResultReference Messages followed by a SearchResultDone Message. 576 Each SearchResultEntry Message SHALL include a Sync State Control of 577 state add, entryUUID containing the entry's UUID, and no cookie. Each 578 SearchResultReference Message SHALL include a Sync State Control of 579 state add, entryUUID containing the UUID associated with the reference 580 (normally the UUID of the associated named referral [RFC3296] object), 581 and no cookie. The SearchResultDone Message SHALL include a Sync Done 582 Control having refreshDeletes set to FALSE. 584 A resultCode value of success indicates the operation successfully 585 completed. Otherwise, the result code indicates the nature of 586 failure. The server may return e-syncRefreshRequired result code on 587 the initial content poll if it is safe to do so when it is unable to 588 perform the operation due to various reasons. reloadHint is set to 589 FALSE in the SearchRequest Message requesting the initial content 590 poll. 592 If the operation is successful, a cookie representing the 593 synchronization state of the current client copy SHOULD be returned 594 for use in subsequent Sync Operations. 596 3.3.2. Content Update Poll 597 Upon receipt of the request the server provides the content refresh 598 using a set of zero or more SearchResultEntry and 599 SearchResultReference Messages followed by a SearchResultDone Message. 601 The server is REQUIRED to either: 602 a) provide the sequence of messages necessary for eventual 603 convergence of the client's copy of the content to the server's 604 copy, 606 b) treat the request as an initial content request (e.g., ignore 607 the cookie or the synchronization state represented in the 608 cookie), 610 c) indicate that the incremental convergence is not possible by 611 returning e-syncRefreshRequired, 613 d) return a resultCode other than success or 614 e-syncRefreshRequired. 616 A Sync Operation may consist of a single present phase, a single 617 delete phase, or a present phase followed by a delete phase. 619 In each phase, for each entry or reference which has been added to the 620 content or been changed since the previous Sync Operation indicated by 621 the cookie, the server returns a SearchResultEntry or 622 SearchResultReference Message, respectively, each with a Sync State 623 Control consisting of state add, entryUUID containing the UUID of the 624 entry or reference, and no cookie. Each SearchResultEntry Message 625 represents the current state of a changed entry. Each 626 SearchResultReference Message represents the current state of a 627 changed reference. 629 In the present phase, for each entry which has not been changed since 630 the previous Sync Operation, an empty SearchResultEntry is returned 631 whose objectName reflects the entry's current DN, the attributes field 632 is empty, and a Sync State Control consisting of state present, 633 entryUUID containing the UUID of the entry, and no cookie. For each 634 reference which has not been changed since the previous Sync 635 Operation, an empty SearchResultReference containing an empty SEQUENCE 636 OF LDAPURL is returned with a Sync State Control consisting of state 637 present, entryUUID containing the UUID of the entry, and no cookie. 638 No messages are sent for entries or references which are no longer in 639 the content. 641 Multiple empty entries with a Sync State Control of state present 642 SHOULD be coalesced into one or more Sync Info Messages of syncIdSet 643 value with refreshDeletes set to FALSE. syncUUIDs contain a set of 644 UUIDs of the entries and references unchanged since the last Sync 645 Operation. syncUUIDs may be empty. The Sync Info Message of 646 syncIdSet may contain cookie to represent the state of the content 647 after performing the synchronization of the entries in the set. 649 In the delete phase, for each entry no longer in the content, the 650 server returns a SearchResultEntry whose objectName reflects a past DN 651 of the entry or is empty, the attributes field is empty, and a Sync 652 State Control consisting of state delete, entryUUID containing the 653 UUID of the deleted entry, and no cookie. For each reference no 654 longer in the content, a SearchResultReference containing an empty 655 SEQUENCE OF LDAPURL is returned with a Sync State Control consisting 656 of state delete, entryUUID containing the UUID of the deleted 657 reference, and no cookie. 659 Multiple empty entries with a Sync State Control of state delete 660 SHOULD be coalesced into one or more Sync Info Messages of syncIdSet 661 value with refreshDeletes set to TRUE. syncUUIDs contain a set of 662 UUIDs of the entries and references which has been deleted from the 663 content since the last Sync Operation. syncUUIDs may be empty. The 664 Sync Info Message of syncIdSet may contain cookie to represent the 665 state of the content after performing the synchronization of the 666 entries in the set. 668 When a present phase is followed by a delete phase, the two phases are 669 delimited by a Sync Info Message containing syncInfoValue of 670 refreshPresent, which may contain cookie representing the state after 671 completing the present phase. The refreshPresent contains refreshDone 672 which is always FALSE in the refreshOnly mode of Sync Operation 673 because it is followed by a delete phase. 675 If a Sync Operation consists of a single phase, each phase and hence 676 the Sync Operation are marked ended by a SearchResultDone Message with 677 Sync Done Control which SHOULD contain cookie representing the state 678 of the content after completing the Sync Operation. The Sync Done 679 Control contains refreshDeletes which is set to FALSE for the present 680 phase and set to TRUE for the delete phase. 682 If a Sync Operation consists of a present phase followed by a delete 683 phase, the Sync Operation are marked ended at the end of the delete 684 phase by a SearchResultDone Message with Sync Done Control which 685 SHOULD contain cookie representing the state of the content after 686 completing the Sync Operation. The Sync Done Control contains 687 refreshDeletes which is set to TRUE. 689 The client can specify whether it prefers to receive an initial 690 content by supplying reloadHint of TRUE or to receive a 691 e-syncRefreshRequired resultCode by supplying reloadHint of FALSE 692 (hence absent), in the case that the server determines that it is 693 impossible or inefficient to achieve the eventual convergence by 694 continuing the current incremental synchronization thread. 696 A resultCode value of success indicates the operation is successfully 697 completed. A resultCode value of e-syncRefreshRequired indicates that 698 a full or partial refresh is needed. Otherwise, the result code 699 indicates the nature of failure. A cookie is provided in the Sync 700 Done Control for use in subsequent Sync Operations for incremental 701 synchronization. 703 3.4. refreshAndPersist Mode 705 A Sync request with mode refreshAndPersist asks for initial content or 706 content update (during the refresh stage) followed by change 707 notifications (during the persist stage). 709 3.4.1. refresh Stage 711 The content refresh is provided as described in Section 3.3 excepting 712 that the successful completion of content refresh is indicated by 713 sending a Sync Info Message of refreshDelete or refreshPresent with a 714 refreshDone value set to TRUE instead of a SearchResultDone Message 715 with resultCode success. A cookie SHOULD be returned in the Sync Info 716 Message to represent the state of the content after finishing the 717 refresh stage of the Sync Operation. 719 3.4.2. persist Stage 721 Change notifications are provided during the persist stage. 723 As updates are made to the DIT the server notifies the client of 724 changes to the content. DIT updates may cause entries and references 725 to be added to the content, deleted from the content, or modified 726 within the content. DIT updates may also cause references to be 727 added, deleted, or modified within the content. 729 Where DIT updates cause an entry to be added to the content, the 730 server provides a SearchResultEntry Message which represents the entry 731 as it appears in the content. The message SHALL include a Sync State 732 Control with state of add, entryUUID containing the entry's UUID, and 733 an optional cookie. 735 Where DIT updates cause a reference to be added to the content, the 736 server provides a SearchResultReference Message which represents the 737 reference in the content. The message SHALL include a Sync State 738 Control with state of add, entryUUID containing the UUID associated 739 with the reference, and an optional cookie. 741 Where DIT updates cause an entry to be modified within the content, 742 the server provides a SearchResultEntry Message which represents the 743 entry as it appears in the content. The message SHALL include a Sync 744 State Control with state of modify, entryUUID containing the entry's 745 UUID, and an optional cookie. 747 Where DIT updates cause a reference to be modified within the content, 748 the server provides a SearchResultEntry Message which represents the 749 reference in the content. The message SHALL include a Sync State 750 Control with state of modify, entryUUID containing the UUID associated 751 with the reference, and an optional cookie. 753 Where DIT updates cause an entry to be deleted from the content, the 754 server provides a SearchResultReference Message with an empty SEQUENCE 755 OF LDAPURL. The message SHALL include a Sync State Control with state 756 of delete, entryUUID containing the UUID associated with the 757 reference, and an optional cookie. 759 Where DIT updates cause a reference to be deleted from the content, 760 the server provides a SearchResultEntry Message with no attributes. 761 The message SHALL include a Sync State Control with state of delete, 762 entryUUID containing the entry's UUID, and an optional cookie. 764 Multiple empty entries with a Sync State Control of state delete 765 SHOULD be coalesced into one or more Sync Info Messages of syncIdSet 766 value with refreshDeletes set to TRUE. syncUUIDs contain a set of 767 UUIDs of the entries and references which has been deleted from the 768 content. The Sync Info Message of syncIdSet may contain cookie to 769 represent the state of the content after performing the 770 synchronization of the entries in the set. 772 With each of these messages, the server may provide a new cookie to be 773 used in subsequent Sync Operations. Additionally, the server may also 774 return Sync Info Messages of choice newCookie to provide a new cookie. 775 The client SHOULD use the newest (last) cookie it received from the 776 server in subsequent Sync Operations. 778 3.5. Search Request Parameters 780 As stated in Section 3.1, the client SHOULD specify the same content 781 controlling parameters in each Search Request of the session. All 782 fields of the SearchRequest Message are considered content controlling 783 parameters except for sizeLimit and timeLimit. 785 3.5.1. baseObject 787 As with the normal search operation, the refresh and persist stages 788 are not isolated from DIT changes. It is possible that the entry 789 referred to by the baseObject is deleted, renamed, or moved. It is 790 also possible that alias object used in finding the entry referred to 791 by the baseObject is changed such that the baseObject refers to a 792 different entry. 794 If the DIT is updated during processing of the Sync Operation in a 795 manner that causes the baseObject to no longer refer to any entry or 796 in a manner that changes the entry the baseObject refers to, the 797 server SHALL return an appropriate non-success result code such as 798 noSuchObject, aliasProblem, aliasDereferencingProblem, referral, or 799 e-syncRefreshRequired. 801 3.5.2. derefAliases 803 This operation does not support alias dereferencing during searching. 804 The client SHALL specify neverDerefAliases or derefFindingBaseObj for 805 the SearchRequest derefAliases parameter. The server SHALL treat 806 other values (e.g., derefInSearching, derefAlways) as protocol errors. 808 3.5.3. sizeLimit 810 The sizeLimit applies only to entries (regardless of their state in 811 Sync State Control) returned during the refreshOnly operation or the 812 refresh stage of the refreshAndPersist operation. 814 3.5.4. timeLimit 816 For a refreshOnly Sync Operation, the timeLimit applies to the whole 817 operation. For a refreshAndPersist operation, the timeLimit applies 818 only to the refresh stage including the generation of the Sync Info 819 Message with a refreshDone value of TRUE. 821 3.5.5. filter 823 The client SHOULD avoid filter assertions which apply to the values of 824 the attributes likely to be considered by the server as ones holding 825 meta-information. See Section 4. 827 3.6. objectName 828 The Sync Operation uses entryUUID values provided in the Sync State 829 Control as the primary keys to entries. The client MUST use these 830 entryUUIDs to correlate synchronization messages. 832 In some circumstances the DN returned may not reflect the entry's 833 current DN. In particular, when the entry is being deleted from the 834 content, the server may provide an empty DN if the server does not 835 wish to disclose the entry's current DN (or, if deleted from the DIT, 836 the entry's last DN). 838 It should also be noted that the entry's DN may be viewed as meta 839 information (see Section 4.1). 841 3.7. Canceling the Sync Operation 843 Servers MUST implement the LDAP Cancel [CANCEL] Operation and support 844 cancellation of outstanding Sync Operations as described here. 846 To cancel an outstanding Sync Operation, the client issues an LDAP 847 Cancel [CANCEL] Operation. 849 If at any time the server becomes unwilling or unable to continue 850 processing a Sync Operation, the server SHALL return a 851 SearchResultDone with a non-success resultCode indicating the reason 852 for the termination of the operation. 854 Whether the client or the server initiated the termination, the server 855 may provide a cookie in the Sync Done Control for use in subsequent 856 Sync Operations. 858 3.8. Refresh Required 860 In order to achieve the eventually-convergent synchronization, the 861 server may terminate the Sync Operation in the refresh or the persist 862 stage by returning a e-syncRefreshRequired resultCode to the client. 863 If no cookie is provided, a full refresh is needed. If a cookie 864 representing a synchronization state is provided in this response, an 865 incremental refresh is needed. 867 To obtain a full refresh, the client then issues a new synchronization 868 request with no cookie. To obtain an incremental reload, the client 869 issues a new synchronization with the provided cookie. 871 The server may choose to provide a full copy in the refresh stage 872 (e.g., ignore the cookie or the synchronization state represented in 873 the cookie) instead of providing an incremental refresh in order to 874 achieve the eventual convergence. 876 The decision between the return of the initial content and the return 877 of the e-syncRefreshRequired result code may be based on reloadHint in 878 the Sync Request Control from the client. 880 In the case of persist stage Sync, the server returns the resultCode 881 of e-syncRefreshRequired to the client to indicate that the client 882 needs to issue a new Sync Operation in order to obtain a synchronized 883 copy of the content. If no cookie is provided, a full refresh is 884 needed. If a cookie representing a synchronization state is provided, 885 an incremental refresh is needed. 887 The server may also return e-syncRefreshRequired if it determines that 888 a refresh would be more efficient than sending all the messages 889 required for convergence. 891 It is noted that the client may receive one or more of 892 SearchResultEntry, SearchResultReference, and/or Sync Info Messages 893 before it receives SearchResultDone Message with the 894 e-syncRefreshRequired result code. 896 3.9. Chattiness Considerations 898 The server MUST ensure that the number of entry messages generated to 899 refresh the client content does not exceed the number of entries 900 presently in the content. While there is no requirement for servers 901 to maintain history information, if the server has sufficient history 902 to allow it to reliably determine which entries in the prior client 903 copy are no longer present in the content and the number of such 904 entries is less than or equal to the number of unchanged entries, the 905 server SHOULD generate delete entry messages instead of present entry 906 messages (see Section 3.3.2). 908 When the amount of history information maintained in the server is not 909 enough for the clients to perform infrequent refreshOnly Sync 910 Operations, it is likely that the server has incomplete history 911 information (e.g. due to truncation) by the time those clients connect 912 again. 914 The server SHOULD NOT resort to full reload when the history 915 information is not enough to generate delete entry messages. The 916 server SHOULD generate either present entry messages only or present 917 entry messages followed by delete entry messages to bring the client 918 copy to the current state. In the latter case, the present entry 919 messages bring the client copy to a state covered by the history 920 information maintained in the server. 922 The server SHOULD maintain enough (current or historical) state 923 information (such as a context-wide last modify time stamp) to 924 determine if no changes were made in the context since the content 925 refresh was provided and, and when no changes were made, generate zero 926 delete entry messages instead of present messages. 928 The server SHOULD NOT use the history information when its use does 929 not reduce the synchronization traffic or when its use can expose 930 sensitive information not allowed to be received by the client. 932 The server implementor should also consider chattiness issues which 933 span multiple Sync Operations of a session. As noted in Section 3.8, 934 the server may return e-syncRefreshRequired if it determines that a 935 reload would be more efficient than continuing under the current 936 operation. If reloadHint in the Sync Request is TRUE, the server may 937 initiate a reload without directing the client to request a reload. 939 The server SHOULD transfer a new cookie frequently to avoid having to 940 transfer information already provided to the client. Even where DIT 941 changes do not cause content synchronization changes to be 942 transferred, it may be advantageous to provide a new cookie using a 943 Sync Info Message. However, the server SHOULD avoid overloading the 944 client or network with Sync Info Messages. 946 During persist mode, the server SHOULD coalesce multiple outstanding 947 messages updating the same entry. The server MAY delay generation of 948 an entry update in anticipation of subsequent changes to that entry 949 which could be coalesced. The length of the delay should be long 950 enough to allow coalescing of update requests issued back to back but 951 short enough that the transient inconsistency induced by the delay is 952 corrected in a timely manner. 954 The server SHOULD use syncIdSet Sync Info Message when there are 955 multiple delete or present messages to reduce the amount of 956 synchronization traffic. 958 It is also noted that there may be many clients interested in a 959 particular directory change, and servers attempting to service all of 960 these at once may cause congestion on the network. The congestion 961 issues are magnified when the change requires a large transfer to each 962 interested client. Implementors and deployers of servers should take 963 steps to prevent and manage network congestion. 965 3.10. Operation Multiplexing 967 The LDAP protocol model [RFC2251] allows operations to be multiplexed 968 over a single LDAP session. Clients SHOULD NOT maintain multiple LDAP 969 sessions with the same server. Servers SHOULD ensure that responses 970 from concurrently processed operations are interleaved fairly. 972 Clients SHOULD combine Sync Operations whose result set is largely 973 overlapping. This avoids having to return multiple messages, once for 974 each overlapping session, for changes to entries in the overlap. 976 Clients SHOULD NOT combine Sync Operations whose result sets are 977 largely non-overlapping with each other. This ensures that an event 978 requiring a e-syncRefreshRequired response can be limited to as few 979 result sets as possible. 981 4. Meta Information Considerations 983 4.1. Entry DN 985 As an entry's DN is constructed from its relative DN (RDN) and the 986 entry's parent's DN, it is often viewed as meta information. 988 While renaming or moving to a new superior causes the entry's DN to 989 change, that change SHOULD NOT, by itself, cause synchronization 990 messages to be sent for that entry. However, if the renaming or the 991 moving could cause the entry to be added or deleted from the content, 992 appropriate synchronization messages should be generated to indicate 993 this to the client. 995 When a server treats the entry's DN as meta information, the server 996 SHALL either 998 - evaluate all MatchingRuleAssertions [RFC2251] to TRUE if 999 matching a value of an attribute of the entry and otherwise 1000 Undefined, or 1001 - evaluate all MatchingRuleAssertion with dnAttributes of TRUE as 1002 Undefined. 1004 The latter choice is offered for ease of server implementation. 1006 4.2. Operational Attributes 1008 Where values of an operational attribute is determined by values not 1009 held as part of the entry it appears in, the operational attribute 1010 SHOULD NOT support synchronization of that operational attribute. 1012 For example, in servers which implement X.501 subschema model [X.501], 1013 servers should not support synchronization of the subschemaSubentry 1014 attribute as its value is determined by values held and administrated 1015 in subschema subentries. 1017 As a counter example, servers which implement aliases [RFC2256][X.501] 1018 can support synchronization of the aliasedObjectName attribute as its 1019 values are held and administrated as part of the alias entries. 1021 Servers SHOULD support synchronization of the following operational 1022 attributes: createTimestamp, modifyTimestamp, creatorsName, 1023 modifiersName [RFC2252]. Servers MAY support synchronization of other 1024 operational attributes. 1026 4.3. Collective Attributes 1028 A collective attribute is "a user attribute whose values are the same 1029 for each member of an entry collection" [X.501]. Use of collective 1030 attributes in LDAP is discussed in [RFC3371]. 1032 Modification of a collective attribute generally affects the content 1033 of multiple entries, which are the members of the collection. It is 1034 inefficient to include values of collective attributes visible in 1035 entries of the collection, as a single modification of a collective 1036 attribute requires transmission of multiple SearchResultEntry (one for 1037 each entry of the collection which the modification affected) to be 1038 transmitted. 1040 Servers SHOULD NOT synchronize collective attributes appearing in 1041 entries of any collection. Servers MAY support synchronization of 1042 collective attributes appearing in collective attribute subentries. 1044 4.4. Access and Other Administrative Controls 1046 Entries are commonly subject to access and other administrative 1047 Controls. While portions of the policy information governing a 1048 particular entry may be held in the entry, policy information is often 1049 held elsewhere (in superior entries, in subentries, in the root DSE, 1050 in configuration files etc.). Because of this, changes to policy 1051 information make it difficult to ensure eventual convergence during 1052 incremental synchronization. 1054 Where it is impractical or infeasible to generate content changes 1055 resulting from a change to policy information, servers may opt to 1056 return e-syncRefreshRequired or treat the Sync Operation as an initial 1057 content request (e.g., ignore the cookie or the synchronization state 1058 represented in the cookie). 1060 5. Interaction with Other Controls 1062 The Sync Operation may be used with: 1064 - ManageDsaIT Control [RFC3296] 1065 - Subentries Control [RFC3672] 1067 as described below. The Sync Operation may be used with other LDAP 1068 extensions as detailed in other documents. 1070 5.1. ManageDsaIT Control 1072 The ManageDsaIT Control [RFC3296] indicates that the operation acts 1073 upon the DSA Information Tree and causes referral and other special 1074 entries to be treated as object entries with respect to the operation. 1076 5.2. Subentries Control 1078 The Subentries Control is used with the search operation "to control 1079 the visibility of entries and subentries which are within scope" 1080 [RFC3672]. When used with the Sync Operation, the subentries control 1081 and other factors (search scope, filter, etc.) are used to determine 1082 whether an entry or subentry appear in the content or not. 1084 6. Shadowing Considerations 1086 As noted in [RFC2251], some servers may hold shadow copies of entries 1087 which can be used to answer search and comparison queries. Such 1088 servers may also support content synchronization requests. This 1089 section discusses considerations for implementors and deployers for 1090 the implementation and deployment of the Sync operation in shadowed 1091 directories. 1093 While a client may know of multiple servers which are equally capable 1094 of being used to obtain particular directory content from, a client 1095 SHOULD NOT assume that each of these server is equally capable of 1096 continuing a content synchronization session. As stated in Section 1097 3.1, the client SHOULD issue each Sync request of a Sync session to 1098 the same server. 1100 However, through domain naming or IP address redirection or other 1101 techniques, multiple physical servers can be made to appear as one 1102 logical server to a client. Only servers which are equally capable in 1103 regards to their support for the Sync operation and which hold equally 1104 complete copies of the entries should be made to appear as one logical 1105 server. In particular, each physical server acting as one logical 1106 server SHOULD be equally capable of continuing a content 1107 synchronization based upon cookies provided by any of the other 1108 physical servers without requiring a full reload. Because there is no 1109 standard LDAP shadowing mechanism, the specification of how to 1110 independently implement equally capable servers (as well as the 1111 precise definition of "equally capable") is left to future documents. 1113 It is noted that it may be difficult for the server to reliably 1114 determine what content was provided to the client by another server, 1115 especially in the shadowing environments which allow shadowing events 1116 to be coalesced. Where so, the use of the delete phase discussed in 1117 Section 3.3.2 may not be applicable. 1119 7. Security Considerations 1121 In order to maintain a synchronized copy of the content, a client is 1122 to delete information from its copy of the content as described above. 1123 However, the client may maintain knowledge of information disclosed to 1124 it by the server separate from its copy of the content used for 1125 synchronization. Management of this knowledge is beyond the scope of 1126 this document. Servers should be careful not to disclose information 1127 for content which the client is not authorized to have knowledge of 1128 and/or about. 1130 While the information provided by a series of refreshOnly Sync 1131 Operations is similar to that provided by a series of Search 1132 Operations, persist stage may disclose additional information. A 1133 client may be able to discern information about the particular 1134 sequence of update operations which caused content change. 1136 Implementors should take precautions against malicious cookie content, 1137 including malformed cookies or valid cookies used with different 1138 security associations and/or protections in attempt to obtain 1139 unauthorized access to information. Servers may include a digital 1140 signature in the cookie to detect tampering. 1142 The operation may be the target of direct denial of service attacks. 1143 Implementors should provide safeguards to ensure the operation is not 1144 abused. Servers may place access control or other restrictions upon 1145 the use of this operation. 1147 It is noted that even small updates to the directory may cause 1148 significant amount of traffic to be generated to clients using this 1149 operation. A user could abuse its update privileges to mount an 1150 indirect denial of service to these clients, other clients, and/or 1151 portions of the network. Servers should provide safeguards to ensure 1152 update operations are not abused. 1154 Implementors of this (or any) LDAP extension should be familiar with 1155 general LDAP security considerations [RFC3377]. 1157 8. IANA Considerations 1159 Registration of the following values is requested. 1161 The OID arc 1.3.6.1.4.1.4203.1.9.1 was assigned [ASSIGN] by OpenLDAP 1162 Foundation, under its IANA-assigned private enterprise allocation 1163 [PRIVATE], for use in this specification. 1165 8.2. LDAP Protocol Mechanism 1167 It is requested that IANA register the LDAP Protocol Mechanism 1168 described in this document. 1170 Subject: Request for LDAP Protocol Mechanism Registration 1171 Object Identifier: 1.3.6.1.4.1.4203.1.9.1.1 1172 Description: LDAP Content Synchronization Control 1173 Person & email address to contact for further information: 1174 Kurt Zeilenga 1175 Usage: Control 1176 Specification: RFC XXXX 1177 Author/Change Controller: IESG 1178 Comments: none 1180 8.3. LDAP Result Codes 1182 It is requested that IANA register the LDAP Result Code described in 1183 this document. 1185 Subject: LDAP Result Code Registration 1186 Person & email address to contact for further information: 1187 Kurt Zeilenga 1188 Result Code Name: e-syncRefreshRequired (IANA-ASSIGNED-CODE) 1189 Specification: RFC XXXX 1190 Author/Change Controller: IESG 1191 Comments: none 1193 9. Acknowledgments 1195 This document borrows significantly from the LDAP Client Update 1196 Protocol [LCUP], a product of the IETF LDUP working group. This 1197 document also benefited from Persistent Search [PSEARCH], Triggered 1198 Search [TSEARCH], and Directory Synchronization [DIRSYNC] works. This 1199 document also borrows from "Lightweight Directory Access Protocol 1200 (v3)" [RFC2251]. 1202 10. Normative References 1204 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1205 Requirement Levels", BCP 14 (also RFC 2119), March 1997. 1207 [RFC2251] Wahl, M., T. Howes and S. Kille, "Lightweight Directory 1208 Access Protocol (v3)", RFC 2251, December 1997. 1210 [RFC2252] Wahl, M., A. Coulbeck, T. Howes, and S. Kille, 1211 "Lightweight Directory Access Protocol (v3): Attribute 1212 Syntax Definitions", RFC 2252, December 1997. 1214 [RFC3296] Zeilenga, K., "Named Subordinate References in 1215 Lightweight Directory Access Protocol (LDAP) 1216 Directories", RFC 3296, July 2002. 1218 [RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access 1219 Protocol (v3): Technical Specification", RFC 3377, 1220 September 2002. 1222 [RFC3671] Zeilenga, K., "Collective Attributes in LDAP", RFC 3671, 1223 December 2003. 1225 [RFC3672] Zeilenga, K. and S. Legg, "Subentries in LDAP", RFC 1226 3672, December 2003. 1228 [CANCEL] Zeilenga, K., "LDAP Cancel Extended Operation", 1229 draft-zeilenga-ldap-cancel-xx.txt, a work in progress. 1230 [EntryUUID] Zeilenga, K., "The LDAP EntryUUID Operational 1231 Attribute", draft-zeilenga-ldap-uuid-xx.txt, a work in 1232 progress. 1234 [LDAPIRM] Harrison, R. and Zeilenga, K., "LDAP Intermediate 1235 Response", 1236 draft-rharrison-ldap-intermediate-resp-00.txt, a work in 1237 progress. 1239 [UUID] International Organization for Standardization (ISO), 1240 "Information technology - Open Systems Interconnection - 1241 Remote Procedure Call", ISO/IEC 11578:1996 1243 [X.680] International Telecommunication Union - 1244 Telecommunication Standardization Sector, "Abstract 1245 Syntax Notation One (ASN.1) - Specification of Basic 1246 Notation", X.680(1997) (also ISO/IEC 8824-1:1998). 1248 [X.690] International Telecommunication Union - 1249 Telecommunication Standardization Sector, "Specification 1250 of ASN.1 encoding rules: Basic Encoding Rules (BER), 1251 Canonical Encoding Rules (CER), and Distinguished 1252 Encoding Rules (DER)", X.690(1997) (also ISO/IEC 1253 8825-1:1998). 1255 11. Informative References 1257 [RFC2256] Wahl, M., "A Summary of the X.500(96) User Schema for 1258 use with LDAPv3", RFC 2256, December 1997. 1260 [RFC3383] Zeilenga, K., "IANA Considerations for LDAP", BCP 64 1261 (also RFC 3383), September 2002. 1263 [PRIVATE] IANA, "Private Enterprise Numbers", 1264 http://www.iana.org/assignments/enterprise-numbers. 1266 [ASSIGN] OpenLDAP Foundation, "OpenLDAP OID Delegations", 1267 http://www.openldap.org/foundation/oid-delegate.txt. 1269 [X.500] International Telecommunication Union - 1270 Telecommunication Standardization Sector, "The Directory 1271 -- Overview of concepts, models and services," 1272 X.500(1993) (also ISO/IEC 9594-1:1994). 1274 [X.511] International Telecommunication Union - 1275 Telecommunication Standardization Sector, "The 1276 Directory: Abstract Service Definition", X.511(1993). 1278 [X.525] International Telecommunication Union - 1279 Telecommunication Standardization Sector, "The 1280 Directory: Replication", X.525(1993). 1282 [UUIDinfo] The Open Group, "Universally Unique Identifier" appendix 1283 of the CAE Specification "DCE 1.1: Remote Procedure 1284 Calls", Document Number C706, 1285 1286 (appendix available at: 1287 ), 1288 August 1997. 1290 [DIRSYNC] Armijo, M., "Microsoft LDAP Control for Directory 1291 Synchronization", draft-armijo-ldap-dirsync-xx.txt, a 1292 work in progress. 1294 [LCUP] Megginson, R., et. al., "LDAP Client Update Protocol", 1295 draft-ietf-ldup-lcup-xx.txt, a work in progress. 1297 [PSEARCH] Smith, M., et. al., "Persistent Search: A Simple LDAP 1298 Change Notification Mechanism", 1299 draft-ietf-ldapext-psearch-xx.txt, a work in progress. 1301 [TSEARCH] Wahl, M., "LDAPv3 Triggered Search Control", 1302 draft-ietf-ldapext-trigger-xx.txt, a work in progress. 1304 12. Authors' Addresses 1306 Kurt D. Zeilenga 1307 OpenLDAP Foundation 1308 1310 Jong Hyuk Choi 1311 IBM Corporation 1312 1314 Appendix A. CSN-based Implementation Considerations 1316 This appendix is provided for informational purposes only, it is not a 1317 normative part of the LDAP Content Synchronization Operation's 1318 technical specification. 1320 This appendix discusses LDAP Content Synchronization Operation server 1321 implementation considerations associated with a Change Sequence Number 1322 based approaches. 1324 Change Sequence Number based approaches are targeted for use in 1325 servers which do not maintain history information (e.g., change logs, 1326 state snapshots, etc.) about changes made to the Directory and hence, 1327 must rely on current directory state and minimal synchronization state 1328 information embedded in Sync Cookie. Servers which maintain history 1329 information should consider other approaches which exploit the history 1330 information. 1332 A Change Sequence Number is effectively a time stamp which has 1333 sufficient granularity to ensure that the precedence relationship in 1334 time of two updates to the same object can be determined. Change 1335 Sequence Numbers are not to be confused with Commit Sequence Numbers 1336 or Commit Log Record Numbers. A Commit Sequence Number allows one to 1337 determine how two commits (to the same object or different objects) 1338 relate to each other in time. Change Sequence Number associated with 1339 different entries may be committed out of order. In the remainder of 1340 this Appendix, the term CSN refers to a Change Sequence Number. 1342 In these approaches, the server not only maintains a CSN for each 1343 directory entry (the entry CSN), but also maintains a value which we 1344 will call the context CSN. The context CSN is the greatest committed 1345 entry CSN which is not greater than any outstanding (uncommitted) 1346 entry CSNs for all entries in a directory context. The values of 1347 context CSN are used in syncCookie values as synchronization state 1348 indicators. 1350 As search operations are not isolated from individual directory update 1351 operations and individual update operations cannot be assumed to be 1352 serialized, one cannot assume that the returned content incorporates 1353 all relevant changes whose change sequence number is less than or 1354 equal to the greatest entry CSN in the content. The content 1355 incorporates all the relevant changes whose change sequence number is 1356 less than or equal to context CSN before search processing. The 1357 content may also incorporate any subset of the changes whose change 1358 sequence number is greater than context CSN before search processing 1359 but less than or equal to the context CSN after search processing. 1360 The content does not incorporate any of the changes whose CSN is 1361 greater than the context CSN after search processing. 1363 A simple server implementation could use value of the context CSN 1364 before search processing to indicate state. Such an implementation 1365 would embed this value into each SyncCookie returned. We'll call this 1366 the cookie CSN. When a refresh was requested, the server would simply 1367 generate "update" messages for all entries in the content whose CSN is 1368 greater than the supplied cookie CSN and generate "present" messages 1369 for all other entries in the content. However, if the current context 1370 CSN is the same as the cookie CSN, the server should instead generate 1371 zero "updates" and zero "delete" messages, and indicate refreshDeletes 1372 of TRUE as the directory has not changed. 1374 The implementation should also consider the impact of changes to meta 1375 information, such as access controls, which affects content 1376 determination. One approach is for the server to maintain a context 1377 wide meta information CSN or meta CSN. This meta CSN would be updated 1378 whenever meta information affecting content determination was changed. 1379 If the value of the meta CSN is greater than cookie CSN, the server 1380 should ignore the cookie and treat the request as an initial request 1381 for content. 1383 Additionally, servers may want to consider maintaining some 1384 per-session history information to reduce the number of messages 1385 needed to be transferred during incremental refreshes. Specifically, 1386 a server could record information about entries as they leave the 1387 scope of a disconnected sync session and later use this information to 1388 generate delete messages instead of present messages. 1390 When the history information is truncated, the CSN of the latest 1391 truncated history information entry may be recorded as the truncated 1392 CSN of the history information. The truncated CSN may be used to 1393 determine whether a client copy can be covered by the history 1394 information by comparing it to the synchronization state contained in 1395 the cookie supplied by the client. 1397 When there are a large number of sessions, it may make sense to 1398 maintain such history only for the selected clients. Also, servers 1399 taking this approach need to consider resource consumption issues to 1400 ensure reasonable server operation and to protect against abuse. It 1401 may be appropriate to restrict this mode of operation by policy. 1403 Intellectual Property Rights 1405 The IETF takes no position regarding the validity or scope of any 1406 Intellectual Property Rights or other rights that might be claimed to 1407 pertain to the implementation or use of the technology described in 1408 this document or the extent to which any license under such rights 1409 might or might not be available; nor does it represent that it has 1410 made any independent effort to identify any such rights. Information 1411 on the procedures with respect to rights in RFC documents can be found 1412 in BCP 78 and BCP 79. 1414 Copies of IPR disclosures made to the IETF Secretariat and any 1415 assurances of licenses to be made available, or the result of an 1416 attempt made to obtain a general license or permission for the use of 1417 such proprietary rights by implementers or users of this specification 1418 can be obtained from the IETF on-line IPR repository at 1419 http://www.ietf.org/ipr. 1421 The IETF invites any interested party to bring to its attention any 1422 copyrights, patents or patent applications, or other proprietary 1423 rights that may cover technology that may be required to implement 1424 this standard. Please address the information to the IETF at 1425 ietf-ipr@ietf.org. 1427 Full Copyright 1429 Copyright (C) The Internet Society (2004). This document is subject 1430 to the rights, licenses and restrictions contained in BCP 78, and 1431 except as set forth therein, the authors retain all their rights. 1433 This document and the information contained herein are provided on an 1434 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1435 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 1436 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 1437 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 1438 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1439 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.