1 2 3 4 5 6 7Network Working Group K. Zeilenga 8Request for Comments: 4533 OpenLDAP Foundation 9Category: Experimental J.H. Choi 10 IBM Corporation 11 June 2006 12 13 14 The Lightweight Directory Access Protocol (LDAP) 15 Content Synchronization Operation 16 17Status 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 24Copyright Notice 25 26 Copyright (C) The Internet Society (2006). 27 28IESG 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 36Abstract 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 58Zeilenga & Choi Experimental [Page 1] 59 60RFC 4533 LDAP Content Synchronization Operation June 2006 61 62 63Table 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 114Zeilenga & Choi Experimental [Page 2] 115 116RFC 4533 LDAP Content Synchronization Operation June 2006 117 118 1191. 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 1381.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 170Zeilenga & Choi Experimental [Page 3] 171 172RFC 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 2061.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 226Zeilenga & Choi Experimental [Page 4] 227 228RFC 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 2601.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 2691.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 282Zeilenga & Choi Experimental [Page 5] 283 284RFC 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 338Zeilenga & Choi Experimental [Page 6] 339 340RFC 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 3661.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 394Zeilenga & Choi Experimental [Page 7] 395 396RFC 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 4201.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 4312. 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 450Zeilenga & Choi Experimental [Page 8] 451 452RFC 4533 LDAP Content Synchronization Operation June 2006 453 454 4552.1. Common ASN.1 Elements 456 4572.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 4652.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 4802.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 506Zeilenga & Choi Experimental [Page 9] 507 508RFC 4533 LDAP Content Synchronization Operation June 2006 509 510 5112.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 5322.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 562Zeilenga & Choi Experimental [Page 10] 563 564RFC 4533 LDAP Content Synchronization Operation June 2006 565 566 5672.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 5912.6. Sync Result Codes 592 593 The following LDAP resultCode [RFC4511] is defined: 594 595 e-syncRefreshRequired (4096) 596 5973. 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 618Zeilenga & Choi Experimental [Page 11] 619 620RFC 4533 LDAP Content Synchronization Operation June 2006 621 622 6233.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 6503.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 674Zeilenga & Choi Experimental [Page 12] 675 676RFC 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 6893.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 6963.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 7233.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 730Zeilenga & Choi Experimental [Page 13] 731 732RFC 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 786Zeilenga & Choi Experimental [Page 14] 787 788RFC 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 842Zeilenga & Choi Experimental [Page 15] 843 844RFC 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 8573.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 8633.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 8733.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 898Zeilenga & Choi Experimental [Page 16] 899 900RFC 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 9403.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 954Zeilenga & Choi Experimental [Page 17] 955 956RFC 4533 LDAP Content Synchronization Operation June 2006 957 958 9593.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 9753.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 9833.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 9893.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 9963.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 10023.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 1010Zeilenga & Choi Experimental [Page 18] 1011 1012RFC 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 10243.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 10423.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 1066Zeilenga & Choi Experimental [Page 19] 1067 1068RFC 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 10903.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 1122Zeilenga & Choi Experimental [Page 20] 1123 1124RFC 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 11673.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 1178Zeilenga & Choi Experimental [Page 21] 1179 1180RFC 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 11924. Meta Information Considerations 1193 11944.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 12184.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 1234Zeilenga & Choi Experimental [Page 22] 1235 1236RFC 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 12484.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 12654.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 12815. Interaction with Other Controls 1282 1283 The Sync Operation may be used with: 1284 1285 - ManageDsaIT Control [RFC3296] 1286 1287 1288 1289 1290Zeilenga & Choi Experimental [Page 23] 1291 1292RFC 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 13005.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 13075.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 13156. 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 1346Zeilenga & Choi Experimental [Page 24] 1347 1348RFC 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 13577. 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 1402Zeilenga & Choi Experimental [Page 25] 1403 1404RFC 4533 LDAP Content Synchronization Operation June 2006 1405 1406 14078. IANA Considerations 1408 1409 Registration of the following values have been completed by the IANA 1410 [RFC4520]. 1411 14128.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 14188.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 14338.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 14469. 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 1458Zeilenga & Choi Experimental [Page 26] 1459 1460RFC 4533 LDAP Content Synchronization Operation June 2006 1461 1462 146310. 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 1514Zeilenga & Choi Experimental [Page 27] 1515 1516RFC 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 152511. 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 1570Zeilenga & Choi Experimental [Page 28] 1571 1572RFC 4533 LDAP Content Synchronization Operation June 2006 1573 1574 1575Appendix 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 1626Zeilenga & Choi Experimental [Page 29] 1627 1628RFC 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 1682Zeilenga & Choi Experimental [Page 30] 1683 1684RFC 4533 LDAP Content Synchronization Operation June 2006 1685 1686 1687Authors' 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 1738Zeilenga & Choi Experimental [Page 31] 1739 1740RFC 4533 LDAP Content Synchronization Operation June 2006 1741 1742 1743Full 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 1759Intellectual 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 1783Acknowledgement 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 1794Zeilenga & Choi Experimental [Page 32] 1795 1796