1 2 3 4 5 6 7Network Working Group R. Megginson, Ed. 8Request for Comments: 3928 Netscape Communications Corp. 9Category: Standards Track M. Smith 10 Pearl Crescent, LLC 11 O. Natkovich 12 Yahoo 13 J. Parham 14 Microsoft Corporation 15 October 2004 16 17 18 Lightweight Directory Access Protocol (LDAP) 19 Client Update Protocol (LCUP) 20 21Status of this Memo 22 23 This document specifies an Internet standards track protocol for the 24 Internet community, and requests discussion and suggestions for 25 improvements. Please refer to the current edition of the "Internet 26 Official Protocol Standards" (STD 1) for the standardization state 27 and status of this protocol. Distribution of this memo is unlimited. 28 29Copyright Notice 30 31 Copyright (C) The Internet Society (2004). 32 33Abstract 34 35 This document defines the Lightweight Directory Access Protocol 36 (LDAP) Client Update Protocol (LCUP). The protocol is intended to 37 allow an LDAP client to synchronize with the content of a directory 38 information tree (DIT) stored by an LDAP server and to be notified 39 about the changes to that content. 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58Megginson, et al. Standards Track [Page 1] 59 60RFC 3928 LDAP Client Update Protocol October 2004 61 62 63Table of Contents 64 65 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Applicability. . . . . . . . . . . . . . . . . . . . . . . . . 4 67 3. Specification of Protocol Elements . . . . . . . . . . . . . . 5 68 3.1. ASN.1 Considerations . . . . . . . . . . . . . . . . . . 5 69 3.2. Universally Unique Identifiers . . . . . . . . . . . . . 5 70 3.3. LCUP Scheme and LCUP Cookie. . . . . . . . . . . . . . . 5 71 3.4. LCUP Context . . . . . . . . . . . . . . . . . . . . . . 6 72 3.5. Additional LDAP Result Codes defined by LCUP . . . . . . 6 73 3.6. Sync Request Control . . . . . . . . . . . . . . . . . . 7 74 3.7. Sync Update Control. . . . . . . . . . . . . . . . . . . 7 75 3.8. Sync Done Control. . . . . . . . . . . . . . . . . . . . 8 76 4. Protocol Usage and Flow. . . . . . . . . . . . . . . . . . . . 8 77 4.1. LCUP Search Requests . . . . . . . . . . . . . . . . . . 8 78 4.1.1. Initial Synchronization and Full Resync . . . . . 9 79 4.1.2. Incremental or Update Synchronization . . . . . . 10 80 4.1.3. Persistent Only . . . . . . . . . . . . . . . . . 10 81 4.2. LCUP Search Responses. . . . . . . . . . . . . . . . . . 10 82 4.2.1. Sync Update Informational Responses . . . . . . . 11 83 4.2.2. Cookie Return Frequency . . . . . . . . . . . . . 11 84 4.2.3. Definition of an Entry That Has Entered the 85 Result Set. . . . . . . . . . . . . . . . . . . . 12 86 4.2.4. Definition of an Entry That Has Changed . . . . . 13 87 4.2.5. Definition of an Entry That Has Left the 88 Result Set. . . . . . . . . . . . . . . . . . . . 13 89 4.2.6. Results For Entries Present in the Result Set . . 14 90 4.2.7. Results For Entries That Have Left the Result 91 Set . . . . . . . . . . . . . . . . . . . . . . . 14 92 4.3. Responses Requiring Special Consideration . . . . . . . . 15 93 4.3.1. Returning Results During the Persistent Phase . . 15 94 4.3.2. No Mixing of Sync Phase with Persist Phase. . . . 16 95 4.3.3. Returning Updated Results During the Sync Phase . 16 96 4.3.4. Operational Attributes and Administrative 97 Entries . . . . . . . . . . . . . . . . . . . . . 16 98 4.3.5. Virtual Attributes. . . . . . . . . . . . . . . . 17 99 4.3.6. Modify DN and Delete Operations Applied to 100 Subtrees. . . . . . . . . . . . . . . . . . . . . 17 101 4.3.7. Convergence Guarantees. . . . . . . . . . . . . . 18 102 4.4. LCUP Search Termination. . . . . . . . . . . . . . . . . 18 103 4.4.1. Server Initiated Termination. . . . . . . . . . . 18 104 4.4.2. Client Initiated Termination. . . . . . . . . . . 19 105 4.5. Size and Time Limits . . . . . . . . . . . . . . . . . . 19 106 4.6. Operations on the Same Connection. . . . . . . . . . . . 19 107 4.7. Interactions with Other Controls . . . . . . . . . . . . 19 108 4.8. Replication Considerations . . . . . . . . . . . . . . . 20 109 5. Client Side Considerations . . . . . . . . . . . . . . . . . . 20 110 5.1. Using Cookies with Different Search Criteria . . . . . . 20 111 112 113 114Megginson, et al. Standards Track [Page 2] 115 116RFC 3928 LDAP Client Update Protocol October 2004 117 118 119 5.2. Renaming the Base Object . . . . . . . . . . . . . . . . 20 120 5.3. Use of Persistent Searches With Respect to Resources . . 21 121 5.4. Continuation References to Other LCUP Contexts . . . . . 21 122 5.5. Referral Handling. . . . . . . . . . . . . . . . . . . . 21 123 5.6. Multiple Copies of Same Entry During Sync Phase. . . . . 21 124 5.7. Handling Server Out of Resources Condition . . . . . . . 21 125 6. Server Implementation Considerations . . . . . . . . . . . . . 22 126 6.1. Server Support for UUIDs . . . . . . . . . . . . . . . . 22 127 6.2. Example of Using an RUV as the Cookie Value. . . . . . . 22 128 6.3. Cookie Support Issues. . . . . . . . . . . . . . . . . . 22 129 6.3.1. Support for Multiple Cookie Schemes . . . . . . . 22 130 6.3.2. Information Contained in the Cookie . . . . . . . 23 131 6.4. Persist Phase Response Time. . . . . . . . . . . . . . . 23 132 6.5. Scaling Considerations . . . . . . . . . . . . . . . . . 23 133 6.6. Alias Dereferencing. . . . . . . . . . . . . . . . . . . 24 134 7. Synchronizing Heterogeneous Data Stores. . . . . . . . . . . . 24 135 8. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 24 136 9. Security Considerations. . . . . . . . . . . . . . . . . . . . 24 137 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25 138 10.1. Normative References . . . . . . . . . . . . . . . . . . 25 139 10.2. Informative References . . . . . . . . . . . . . . . . . 26 140 11. Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . . 26 141 Appendix - Features Left Out of LCUP . . . . . . . . . . . . . . . 27 142 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29 143 Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 30 144 1451. Overview 146 147 The LCUP protocol is intended to allow LDAP clients to synchronize 148 with the content stored by LDAP servers. 149 150 The problem areas addressed by the protocol include: 151 152 - Mobile clients that maintain a local read-only copy of the 153 directory data. While off-line, the client uses the local copy of 154 the data. When the client connects to the network, it 155 synchronizes with the current directory content and can optionally 156 receive notification about the changes that occur while it is on- 157 line. For example, a mail client can maintain a local copy of the 158 corporate address book that it synchronizes with the master copy 159 whenever the client is connected to the corporate network. 160 161 - Applications intending to synchronize heterogeneous data stores. 162 A meta directory application, for instance, would periodically 163 retrieve a list of modified entries from the directory, construct 164 the changes and apply them to a foreign data store. 165 166 167 168 169 170Megginson, et al. Standards Track [Page 3] 171 172RFC 3928 LDAP Client Update Protocol October 2004 173 174 175 - Clients that need to take certain actions when a directory entry 176 is modified. For instance, an electronic mail repository may want 177 to perform a "create mailbox" task when a new person entry is 178 added to an LDAP directory and a "delete mailbox" task when a 179 person entry is removed. 180 181 The problem areas not being considered: 182 183 - Directory server to directory server synchronization. The IETF is 184 developing a LDAP replication protocol, called LDUP [RFC3384], 185 which is specifically designed to address this problem area. 186 187 There are currently several protocols in use for LDAP client server 188 synchronization. While each protocol addresses the needs of a 189 particular group of clients (e.g., on-line clients or off-line 190 clients), none satisfies the requirements of all clients in the 191 target group. For instance, a mobile client that was off-line and 192 wants to become up to date with the server and stay up to date while 193 connected can't be easily supported by any of the existing protocols. 194 195 LCUP is designed such that the server does not need to maintain state 196 information specific to individual clients. The server may need to 197 maintain additional state information about attribute modifications, 198 deleted entries, and moved/renamed entries. The clients are 199 responsible for storing the information about how up to date they are 200 with respect to the server's content. LCUP design avoids the need 201 for LCUP-specific update agreements to be made between client and 202 server prior to LCUP use. The client decides when and from where to 203 retrieve the changes. LCUP design requires clients to initiate the 204 update session and "pull" the changes from server. 205 206 LCUP operations are subject to administrative and access control 207 policies enforced by the server. 208 209 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 210 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 211 document are to be interpreted as described in BCP 14, RFC 2119 212 [RFC2119]. 213 2142. Applicability 215 216 LCUP will work best if the following conditions are met: 217 218 1) The server stores some degree of historical state or change 219 information to reduce the amount of wire traffic required for 220 incremental synchronizations. The optimal balance between server 221 state and wire traffic varies amongst implementations and usage 222 scenarios, and is therefore left in the hands of implementers. 223 224 225 226Megginson, et al. Standards Track [Page 4] 227 228RFC 3928 LDAP Client Update Protocol October 2004 229 230 231 2) The client cannot be assumed to understand the physical 232 information model (virtual attributes, operational attributes, 233 subentries, etc.) implemented by the server. Optimizations would 234 be possible if such assumptions could be made. 235 236 3) Meta data changes and renames and deletions of large subtrees are 237 very infrequent. LCUP makes these assumptions in order to reduce 238 client complexity required to deal with these special operations, 239 though when they do occur they may result in a large number of 240 incremental update messages or a full resync. 241 2423. Specification of Protocol Elements 243 244 The following sections define the new elements required to use this 245 protocol. 246 2473.1. ASN.1 Considerations 248 249 Protocol elements are described using ASN.1 [X.680]. The term "BER- 250 encoded" means the element is to be encoded using the Basic Encoding 251 Rules [X.690] under the restrictions detailed in Section 5.1 of 252 [RFC2251]. All ASN.1 in this document uses implicit tags. 253 2543.2. Universally Unique Identifiers 255 256 Distinguished names can change, so are therefore unreliable as 257 identifiers. A Universally Unique Identifier (or UUID for short) 258 MUST be used to uniquely identify entries used with LCUP. The UUID 259 is part of the Sync Update control value (see below) returned with 260 each search result. The server SHOULD provide the UUID as a single 261 valued operational attribute of the entry (e.g., "entryUUID"). We 262 RECOMMEND that the server provides a way to do efficient (i.e., 263 indexed) searches for values of UUID, e.g., by using a search filter 264 like (entryUUID=<some UUID value>) to quickly search for and retrieve 265 an entry based on its UUID. Servers SHOULD use a UUID format as 266 specified in [UUID]. The UUID used by LCUP is a value of the 267 following ASN.1 type: 268 269 LCUPUUID ::= OCTET STRING 270 2713.3. LCUP Scheme and LCUP Cookie 272 273 The LCUP protocol uses a cookie to hold the state of the client's 274 data with respect to the server's data. Each cookie format is 275 uniquely identified by its scheme. The LCUP Scheme is a value of the 276 following ASN.1 type: 277 278 LCUPScheme ::= LDAPOID 279 280 281 282Megginson, et al. Standards Track [Page 5] 283 284RFC 3928 LDAP Client Update Protocol October 2004 285 286 287 This is the OID which identifies the format of the LCUP Cookie value. 288 The scheme OID, as all object identifiers, MUST be unique for a given 289 cookie scheme. The cookie value may be opaque or it may be exposed 290 to LCUP clients. For cookie schemes that expose their value, the 291 preferred form of documentation is an RFC. It is expected that there 292 will be one or more standards track cookie schemes where the value 293 format is exposed and described in detail. 294 295 The LCUP Cookie is a value of the following ASN.1 type: 296 297 LCUPCookie ::= OCTET STRING 298 299 This is the actual data describing the state of the client's data. 300 This value may be opaque, or its value may have some well-known 301 format, depending on the scheme. 302 303 Further uses of the LCUP Cookie value are described below. 304 3053.4. LCUP Context 306 307 A part of the DIT which is enabled for LCUP is referred to as an LCUP 308 Context. A server may support one or more LCUP Contexts. For 309 example, a server with two naming contexts may support LCUP in one 310 naming context but not the other, or support different LCUP cookie 311 schemes in each naming context. Each LCUP Context MAY use a 312 different cookie scheme. An LCUP search will not cross an LCUP 313 Context boundary, but will instead return a SearchResultReference 314 message, with the LDAP URL specifying the same host and port as 315 currently being searched, and with the baseDN set to the baseDN of 316 the new LCUP Context. The client is then responsible for issuing 317 another search using the new baseDN, and possibly a different cookie 318 if that LCUP Context uses a different cookie. The client is 319 responsible for maintaining a mapping of the LDAP URL to its 320 corresponding cookie. 321 3223.5. Additional LDAP Result Codes defined by LCUP 323 324 Implementations of this specification SHALL recognize the following 325 additional resultCode values. The LDAP result code names and numbers 326 defined in the following table have been assigned by IANA per RFC 327 3383 [RFC3383]. 328 329 lcupResourcesExhausted (113) the server is running out of resources 330 lcupSecurityViolation (114) the client is suspected of malicious 331 actions 332 lcupInvalidData (115) invalid scheme or cookie was supplied 333 by the client 334 335 336 337 338Megginson, et al. Standards Track [Page 6] 339 340RFC 3928 LDAP Client Update Protocol October 2004 341 342 343 lcupUnsupportedScheme (116) The cookie scheme is a valid OID but 344 is not supported by this server 345 lcupReloadRequired (117) indicates that client data needs to be 346 reinitialized. This reason is 347 returned if the server does not 348 contain sufficient information to 349 synchronize the client or if the 350 server's data was reloaded since the 351 last synchronization session 352 353 The uses of these codes are described below. 354 3553.6. Sync Request Control 356 357 The Sync Request Control is an LDAP Control [RFC2251, Section 4.1.2] 358 where the controlType is the object identifier 1.3.6.1.1.7.1 and the 359 controlValue, an OCTET STRING, contains a BER-encoded 360 syncRequestControlValue. 361 362 syncRequestControlValue ::= SEQUENCE { 363 updateType ENUMERATED { 364 syncOnly (0), 365 syncAndPersist (1), 366 persistOnly (2) }, 367 sendCookieInterval [0] INTEGER OPTIONAL, 368 scheme [1] LCUPScheme OPTIONAL, 369 cookie [2] LCUPCookie OPTIONAL 370 } 371 372 sendCookieInterval - the server SHOULD send the cookie back in the 373 Sync Update control value (defined below) for every 374 sendCookieInterval number of SearchResultEntry and 375 SearchResultReference PDUs returned to the client. For example, if 376 the value is 5, the server SHOULD send the cookie back in the Sync 377 Update control value for every 5 search results returned to the 378 client. If this value is absent, zero or less than zero, the server 379 chooses the interval. 380 381 The Sync Request Control is only applicable to the searchRequest 382 message. Use of this control is described below. 383 3843.7. Sync Update Control 385 386 The Sync Update Control is an LDAP Control [RFC2251, Section 4.1.2] 387 where the controlType is the object identifier 1.3.6.1.1.7.2 and the 388 controlValue, an OCTET STRING, contains a BER-encoded 389 syncUpdateControlValue. 390 391 392 393 394Megginson, et al. Standards Track [Page 7] 395 396RFC 3928 LDAP Client Update Protocol October 2004 397 398 399 syncUpdateControlValue ::= SEQUENCE { 400 stateUpdate BOOLEAN, 401 entryUUID [0] LCUPUUID OPTIONAL, -- REQUIRED for entries -- 402 UUIDAttribute [1] AttributeType OPTIONAL, 403 entryLeftSet [2] BOOLEAN, 404 persistPhase [3] BOOLEAN, 405 scheme [4] LCUPScheme OPTIONAL, 406 cookie [5] LCUPCookie OPTIONAL 407 } 408 409 The field UUIDAttribute contains the name or OID of the attribute 410 that the client should use to perform searches for entries based on 411 the UUID. The client should be able to use it in an equality search 412 filter, e.g., "(<uuid attribute>=<entry UUID value>)" and should be 413 able to use it in the attribute list of the search request to return 414 its value. The UUIDAttribute field may be omitted if the server does 415 not support searching on the UUID values. 416 417 The Sync Update Control is only applicable to SearchResultEntry and 418 SearchResultReference messages. Although entryUUID is OPTIONAL, it 419 MUST be used with SearchResultEntry messages. Use of this control is 420 described below. 421 4223.8. Sync Done Control 423 424 The Sync Done Control is an LDAP Control [RFC2251, Section 4.1.2] 425 where the controlType is the object identifier 1.3.6.1.1.7.3 and the 426 controlValue contains a BER-encoded syncDoneValue. 427 428 syncDoneValue ::= SEQUENCE { 429 scheme [0] LCUPScheme OPTIONAL, 430 cookie [1] LCUPCookie OPTIONAL 431 } 432 433 The Sync Done Control is only applicable to SearchResultDone message. 434 Use of this control is described below. 435 4364. Protocol Usage and Flow 437 4384.1. LCUP Search Requests 439 440 A client initiates a synchronization or persistent search session 441 with a server by attaching a Sync Request control to an LDAP 442 searchRequest message. The search specification determines the part 443 of the directory information tree (DIT) the client wishes to 444 synchronize with, the set of attributes it is interested in and the 445 amount of data the client is willing to receive. The Sync Request 446 control contains the client's request specification. 447 448 449 450Megginson, et al. Standards Track [Page 8] 451 452RFC 3928 LDAP Client Update Protocol October 2004 453 454 455 If there is an error condition, the server MUST immediately return a 456 SearchResultDone message with the resultCode set to an error code. 457 This table maps a condition to its corresponding behavior and 458 resultCode. 459 460 Condition Behavior or resultCode 461 462 Sync Request Control is not Server behaves as [RFC2251, Section 463 supported 4.1.2] - specifically, if the 464 criticality of the control is FALSE, 465 the server will process the request 466 as a normal search request 467 468 Scheme is not supported lcupUnsupportedScheme 469 470 A control value field is lcupInvalidData 471 invalid (e.g., illegal 472 updateType, or the scheme is 473 not a valid OID, or the cookie 474 is invalid) 475 476 Server is running out of lcupResourcesExhausted 477 resources 478 479 Server suspects client of lcupSecurityViolation 480 malicious behavior (frequent 481 connects/disconnects, etc.) 482 483 The server cannot bring the lcupReloadRequired 484 client up to date (server data 485 has been reloaded, or other 486 changes prevent 487 convergence) 488 4894.1.1. Initial Synchronization and Full Resync 490 491 For an initial synchronization or full resync, the fields of the Sync 492 Request control MUST be specified as follows: 493 494 updateType - MUST be set to syncOnly or syncAndPersist 495 sendCookieInterval - MAY be set 496 scheme - MAY be set - if set, the server MUST use this 497 specified scheme or return lcupUnsupportedScheme 498 (see above) - if not set, the server MAY use any 499 scheme it supports. 500 cookie - MUST NOT be set 501 502 503 504 505 506Megginson, et al. Standards Track [Page 9] 507 508RFC 3928 LDAP Client Update Protocol October 2004 509 510 511 If the request was successful, the client will receive results as 512 described in the section "LCUP Search Responses" below. 513 5144.1.2. Incremental or Update Synchronization 515 516 For an incremental or update synchronization, the fields of the Sync 517 Request control MUST be specified as follows: 518 519 updateType - MUST be set to syncOnly or syncAndPersist 520 sendCookieInterval - MAY be set 521 scheme - MUST be set 522 cookie - MUST be set 523 524 The client SHOULD always use the latest cookie it received from the 525 server. 526 527 If the request was successful, the client will receive results as 528 described in the section "LCUP Search Responses" below. 529 5304.1.3. Persistent Only 531 532 For persistent only search request, the fields of the Sync Request 533 MUST be specified as follows: 534 535 updateType - MUST be set to persistOnly 536 sendCookieInterval - MAY be set 537 scheme - MAY be set - if set, the server MUST use this 538 specified scheme or return 539 lcupUnsupportedScheme (see above) - if not set, 540 the server MAY use any scheme it supports. 541 cookie - MAY be set, but the server MUST ignore it 542 543 If the request was successful, the client will receive results as 544 described in the section "LCUP Search Responses" below. 545 5464.2. LCUP Search Responses 547 548 In response to the client's LCUP request, the server returns zero or 549 more SearchResultEntry or SearchResultReference PDUs that fit the 550 client's specification, followed by a SearchResultDone PDU. The 551 behavior is as specified in [RFC2251 Section 4.5]. Each 552 SearchResultEntry or SearchResultReference PDU also contains a Sync 553 Update control that describes the LCUP state of the returned entry. 554 The SearchResultDone PDU contains a Sync Done control. The following 555 sections specify behaviors in addition to [RFC2251 Section 4.5]. 556 557 558 559 560 561 562Megginson, et al. Standards Track [Page 10] 563 564RFC 3928 LDAP Client Update Protocol October 2004 565 566 5674.2.1 Sync Update Informational Responses 568 569 The server may use the Sync Update control to return information not 570 related to a particular entry. It MAY do this at any time to return 571 a cookie to the client, or to inform the client that the sync phase 572 of a syncAndPersist search is complete and the persist phase has 573 begun. It MAY do this during the persist phase even though no entry 574 has changed that would have normally triggered a response. In order 575 to do this, it is REQUIRED to return the following: 576 577 - A SearchResultEntry PDU with the objectName field set to the DN of 578 the baseObject of the search request and with an empty attribute 579 list. 580 581 - A Sync Update control value with the fields set to the following: 582 583 stateUpdate - MUST be set to TRUE 584 entryUUID - SHOULD be set to the UUID of the baseObject of the 585 search request 586 entryLeftSet - MUST be set to FALSE 587 persistPhase - MUST be FALSE if the search is in the sync phase of a 588 request, and MUST be TRUE if the search is in the 589 persist phase 590 UUIDAttribute - SHOULD only be set if this is either the first result 591 returned or if the attribute has changed 592 scheme - MUST be set if the cookie is set and the cookie 593 format has changed; otherwise, it MAY be omitted 594 cookie - SHOULD be set 595 596 If the server merely wants to return a cookie to the client, it 597 should return as above with the cookie field set. 598 599 During a syncAndPersist request, the server MUST return (as above) 600 immediately after the last entry of the sync phase has been sent and 601 before the first entry of the persist phase has been sent. In this 602 case, the persistPhase field MUST be set to TRUE. This allows the 603 client to know that the sync phase is complete and the persist phase 604 is starting. 605 6064.2.2 Cookie Return Frequency 607 608 The cookie field of the Sync Update control value MAY be set in any 609 returned result, during both the sync phase and the persist phase. 610 The server should return the cookie to the client often enough for 611 the client to resync in a reasonable period of time in case the 612 search is disconnected or otherwise terminated. The 613 sendCookieInterval field in the Sync Request control is a suggestion 614 615 616 617 618Megginson, et al. Standards Track [Page 11] 619 620RFC 3928 LDAP Client Update Protocol October 2004 621 622 623 to the server of how often to return the cookie in the Sync Update 624 control. The server SHOULD respect this value. 625 626 The scheme field of the Sync Update control value MUST be set if the 627 cookie is set and the cookie format has changed; otherwise, it MAY be 628 omitted. 629 630 Some clients may have unreliable connections, for example, a wireless 631 device or a WAN connection. These clients may want to insure that 632 the cookie is returned often in the Sync Update control value, so 633 that if they have to reconnect, they do not have to process many 634 redundant entries. These clients should set the sendCookieInterval 635 in the Sync Request control value to a low number, perhaps even 1. 636 Some clients may have a limited bandwidth connection, and may not 637 want to receive the cookie very often, or even at all (however, the 638 cookie is always sent back in the Sync Done control value upon 639 successful completion). These clients should set the 640 sendCookieInterval in the Sync Request control value to a high 641 number. 642 643 A reasonable behavior of the server is to return the cookie only when 644 data in the LCUP context has changed, even if the client has 645 specified a frequent sendCookieInterval. If nothing has changed, the 646 server can probably save some bandwidth by not returning the cookie. 647 6484.2.3. Definition of an Entry That Has Entered the Result Set 649 650 An entry SHALL BE considered to have entered the client's search 651 result set if one of the following conditions is met: 652 653 - During the sync phase for an incremental sync operation, the entry 654 is present in the search result set but was not present before; 655 this can be due to the entry being added via an LDAP Add 656 operation, or by the entry being moved into the result set by an 657 LDAP Modify DN operation, or by some modification to the entry 658 that causes it to enter the result set (e.g., adding an attribute 659 value that matches the clients search filter), or by some meta- 660 data change that causes the entry to enter the result set (e.g., 661 relaxing of some access control that permits the entry to be 662 visible to the client). 663 664 - During the persist phase for a persistent search operation, the 665 entry enters the search result set; this can be due to the entry 666 being added via an LDAP Add operation, or by the entry being moved 667 into the result set by an LDAP Modify DN operation, or by some 668 modification to the entry that causes it to enter the result set 669 (e.g., adding an attribute value that matches the clients search 670 filter), or by some meta-data change that causes the entry to 671 672 673 674Megginson, et al. Standards Track [Page 12] 675 676RFC 3928 LDAP Client Update Protocol October 2004 677 678 679 enter the result set (e.g., relaxing of some access control that 680 permits the entry to be visible to the client). 681 6824.2.4. Definition of an Entry That Has Changed 683 684 An entry SHALL BE considered to be changed if one or more of the 685 attributes in the attribute list in the search request have been 686 modified. For example, if the search request listed the attributes 687 "cn sn uid", and there is an entry in the client's search result set 688 with the "cn" attribute that has been modified, the entry is 689 considered to be modified. The modification may be due to an LDAP 690 Modify operation or by some change to the meta-data for the entry 691 (e.g., virtual attributes) that causes some change to the value of 692 the specified attributes. 693 694 The converse of this is that an entry SHALL NOT BE considered to be 695 changed if none of the attributes in the attribute list of the search 696 request are modified attributes of the entry. For example, if the 697 search request listed the attributes "cn sn uid", and there is an 698 entry in the client's search result set with the "foo" attribute that 699 has been modified, and none of the "cn" or "sn" or "uid" attributes 700 have been modified, the entry is NOT considered to be changed. 701 7024.2.5. Definition of an Entry That Has Left the Result Set 703 704 An entry SHALL BE considered to have left the client's search result 705 set if one of the following conditions is met: 706 707 - During the sync phase for an incremental sync operation, the entry 708 is not present in the search result set but was present before; 709 this can be due to the entry being deleted via an LDAP Delete 710 operation, or by the entry leaving the result set via an LDAP 711 Modify DN operation, or by some modification to the entry that 712 causes it to leave the result set (e.g., changing/removing an 713 attribute value so that it no longer matches the client's search 714 filter), or by some meta-data change that causes the entry to 715 leave the result set (e.g., adding of some access control that 716 denies the entry to be visible to the client). 717 718 - During the persist phase for a persistent search operation, the 719 entry leaves the search result set; this can be due to the entry 720 being deleted via an LDAP Delete operation, or by the entry 721 leaving the result set via an LDAP Modify DN operation, or by some 722 modification to the entry that causes it to leave the result set 723 (e.g., changing/removing an attribute value so that it no longer 724 matches the client's search filter), or by some meta-data change 725 726 727 728 729 730Megginson, et al. Standards Track [Page 13] 731 732RFC 3928 LDAP Client Update Protocol October 2004 733 734 735 that causes the entry to leave the result set (e.g., adding of 736 some access control that denies the entry to be visible to the 737 client). 738 7394.2.6. Results For Entries Present in the Result Set 740 741 An entry SHOULD be returned as present under the following 742 conditions: 743 744 - The request is an initial synchronization or full resync request 745 and the entry is present in the client's search result set 746 747 - The request is an incremental synchronization and the entry has 748 changed or entered the result set since the last sync 749 750 - The search is in the persist phase and the entry enters the result 751 set or changes 752 753 For a SearchResultEntry return, the fields of the Sync Update control 754 value MUST be set as follows: 755 756 stateUpdate - MUST be set to FALSE 757 entryUUID - MUST be set to the UUID of the entry 758 entryLeftSet - MUST be set to FALSE 759 persistPhase - MUST be set to FALSE if during the sync phase or TRUE 760 if during the persist phase 761 UUIDAttribute - SHOULD only be set if this is either the first result 762 returned or if the attribute has changed 763 scheme - as above 764 cookie - as above 765 766 The searchResultReference return will look the same, except that the 767 entryUUID is not required. If it is specified, it MUST contain the 768 UUID of the DSE holding the reference knowledge. 769 7704.2.7. Results For Entries That Have Left the Result Set 771 772 An entry SHOULD be returned as having left the result set under the 773 following conditions: 774 775 - The request is an incremental synchronization during the sync 776 phase and the entry has left the result set 777 778 - The search is in the persist phase and the entry has left the 779 result set 780 781 782 783 784 785 786Megginson, et al. Standards Track [Page 14] 787 788RFC 3928 LDAP Client Update Protocol October 2004 789 790 791 - The entry has left the result set as a result of an LDAP Delete or 792 LDAP Modify DN operation against the entry itself (i.e., not as a 793 result of an operation against its parent or ancestor) 794 795 For a SearchResultEntry return where the entry has left the result 796 set, the fields of the Sync Update control value MUST be set as 797 follows: 798 799 stateUpdate - MUST be set to FALSE 800 entryUUID - MUST be set to the UUID of the entry that left the 801 result set 802 entryLeftSet - MUST be set to TRUE 803 persistPhase - MUST be set to FALSE if during the sync phase or TRUE 804 if during the persist phase 805 UUIDAttribute - SHOULD only be set if this is either the first result 806 returned or if the attribute has changed 807 scheme - as above 808 cookie - as above 809 810 The searchResultReference return will look the same, except that the 811 entryUUID is not required. If it is specified, it MUST contain the 812 UUID of the DSE holding the reference knowledge. 813 814 Some server implementations keep track of deleted entries using a 815 tombstone - a hidden entry that keeps track of the state, but not all 816 of the data, of an entry that has been deleted. In this case, the 817 tombstone may not contain all of the original attributes of the 818 entry, and therefore it may be impossible for the server to determine 819 if an entry should be removed from the result set based on the 820 attributes in the client's search request. Servers SHOULD keep 821 enough information about the attributes in the deleted entries to 822 determine if an entry should be removed from the result set. Since 823 this may not be possible, the server MAY return an entry as having 824 left the result set even if it is not or never was in the client's 825 result set. Clients MUST ignore these notifications. 826 8274.3. Responses Requiring Special Consideration 828 829 The following sections describe special handling that may be required 830 when returning results. 831 8324.3.1. Returning Results During the Persistent Phase 833 834 During the persistent phase, the server SHOULD return the changed 835 entries to the client as quickly as possible. 836 837 838 839 840 841 842Megginson, et al. Standards Track [Page 15] 843 844RFC 3928 LDAP Client Update Protocol October 2004 845 846 8474.3.2. No Mixing of Sync Phase with Persist Phase 848 849 During a sync phase, the server MUST NOT return any entries with the 850 persistPhase flag set to TRUE, and during the persist phase, all 851 entries returned MUST have the persistPhase flag set to TRUE. The 852 server MUST NOT mix and match sync phase entries with persist phase 853 entries. If there are any sync phase entries to return, they MUST be 854 returned before any persist phase entries are returned. 855 8564.3.3. Returning Updated Results During the Sync Phase 857 858 There may be updates to the entries in the result set of a sync phase 859 search during the actual search operation. If the DSA is under a 860 heavy update load, and it attempts to send all of those updated 861 entries to the client in addition to the other updates it was already 862 planning to send for the sync phase, the server may never get to the 863 end of the sync phase. Therefore, it is left up to the discretion of 864 the server implementation to decide when the client is "in sync" - 865 that is, when to end a syncOnly request, or when to send the Sync 866 Update Informational Response between the sync phase and the persist 867 phase of a syncAndPersist request. The server MAY send the same 868 entry multiple times during the sync phase if the entry changes 869 during the sync phase. 870 871 A reasonable behavior is for the server to generate a cookie based on 872 the server state at the time the client initiated the LCUP request, 873 and only send entries up to that point during the sync phase. Entries 874 updated after that point will be returned only during the persist 875 phase of a syncAndPersist request, or only upon an incremental 876 synchronization. 877 8784.3.4. Operational Attributes and Administrative Entries 879 880 An operational attribute SHOULD be returned if it is specified in the 881 attributes list and would normally be returned as subject to the 882 constraints of [RFC2251 Section 4.5]. If the server does not support 883 syncing of operational attributes, the server MUST return a 884 SearchResultDone message with a resultCode of unwillingToPerform. 885 886 LDAP Subentries [RFC3672] SHOULD be returned if they would normally 887 be returned by the search request. If the server does not support 888 syncing of LDAP Subentries, and the server can determine from the 889 search request that the client has requested LDAP Subentries to be 890 returned (e.g., search control or search filter), the server MUST 891 return a SearchResultDone message with a resultCode of 892 unwillingToPerform. Otherwise, the server MAY simply omit returning 893 LDAP Subentries. 894 895 896 897 898Megginson, et al. Standards Track [Page 16] 899 900RFC 3928 LDAP Client Update Protocol October 2004 901 902 9034.3.5. Virtual Attributes 904 905 An entry may have attributes whose presence in the entry, or presence 906 of values of the attribute, is generated on the fly, possibly by some 907 mechanism outside of the entry, elsewhere in the DIT. An example of 908 this is collective attributes [RFC3671]. These attributes shall be 909 referred to in this document as virtual attributes. 910 911 LCUP treats these attributes the same way as normal, non-virtual 912 attributes. A virtual attribute SHOULD be returned if it is 913 specified in the attributes list and would normally be returned as 914 subject to the constraints of [RFC2251 Section 4.5]. If the server 915 does not support syncing of virtual attributes, the server MUST 916 return a SearchResultDone message with a resultCode of 917 unwillingToPerform. 918 919 One consequence of this is that if you change the definition of a 920 virtual attribute such that it makes the value of that attribute 921 change in many entries in the client's search scope, this means that 922 a server may have to return many entries to the client as a result of 923 that one change. It is not anticipated that this will be a frequent 924 occurrence, and the server has the option to simply force the client 925 to resync if necessary. 926 927 It is also possible that a future LDAP control will allow the client 928 to request only virtual or only non-virtual attributes. 929 9304.3.6. Modify DN and Delete Operations Applied to Subtrees 931 932 There is a special case where a Modify DN or a Delete operation is 933 applied to the base entry of a subtree, and either that base entry or 934 entries in the subtree are within the scope of an LCUP search 935 request. In this case, all of the entries in the subtree are 936 implicitly renamed or removed. 937 938 In either of these cases, the server MUST do one of the following: 939 940 - treat all of these entries as having been renamed or removed and 941 return each entry to the client as such 942 943 - decide that this would be prohibitively expensive, and force the 944 client to resync 945 946 If the search base object has been renamed, and the client has 947 received a noSuchObject as the result of a search request, the client 948 MAY use the entryUUID and UUIDAttribute to locate the new DN that is 949 the result of the modify DN operation. 950 951 952 953 954Megginson, et al. Standards Track [Page 17] 955 956RFC 3928 LDAP Client Update Protocol October 2004 957 958 9594.3.7. Convergence Guarantees 960 961 If at any time during an LCUP search, either during the sync phase or 962 the persist phase, the server determines that it cannot guarantee 963 that it can bring the client's copy of the data to eventual 964 convergence, it SHOULD immediately terminate the LCUP search request 965 and return a SearchResultDone message with a resultCode of 966 lcupReloadRequired. This can also happen at the beginning of an 967 incremental synchronization request, if the client presents a cookie 968 that is out of date or otherwise unable to be processed. The client 969 should then issue an initial synchronization request. 970 971 This can happen, for example, if the data on the server is reloaded, 972 or if there has been some change to the meta-data that makes it 973 impossible for the server to determine if a particular entry should 974 or should not be part of the search result set, or if the meta-data 975 change makes it too resource intensive for the server to calculate 976 the proper result set. 977 978 The server can also return lcupReloadRequired if it determines that 979 it would be more efficient for the client to perform a reload, for 980 example, if too many entries have changed and a simple reload would 981 be much faster. 982 9834.4. LCUP Search Termination 984 9854.4.1. Server Initiated Termination 986 987 When the server has successfully finished processing the client's 988 request, it attaches a Sync Done control to the SearchResultDone 989 message and sends it to the client. However, if the SearchResultDone 990 message contains a resultCode that is not success or canceled, the 991 Sync Done control MAY be omitted. Although the LCUP cookie is 992 OPTIONAL in the Sync Done control value, it MUST be set if the 993 SearchResultDone resultCode is success or canceled. The server 994 SHOULD also set the cookie if the resultCode is 995 lcupResourcesExhausted, timeLimitExceeded, sizeLimitExceeded, or 996 adminLimitExceeded. This allows the client to more easily resync 997 later. If some error occurred, either an LDAP search error (e.g., 998 insufficientAccessRights) or an LCUP error (e.g., 999 lcupUnsupportedScheme), the cookie MAY be omitted. If the cookie is 1000 set, the scheme MUST be set also if the cookie format has changed, 1001 otherwise, it MAY be omitted. 1002 1003 If server resources become tight, the server can terminate one or 1004 more search operations by sending a SearchResultDone message to the 1005 client(s) with a resultCode of lcupResourcesExhausted. The server 1006 SHOULD attach a Sync Done control with the cookie set. A server side 1007 1008 1009 1010Megginson, et al. Standards Track [Page 18] 1011 1012RFC 3928 LDAP Client Update Protocol October 2004 1013 1014 1015 policy is used to decide which searches to terminate. This can also 1016 be used as a security mechanism to disconnect clients that are 1017 suspected of malicious actions, but if the server can infer that the 1018 client is malicious, the server SHOULD return lcupSecurityViolation 1019 instead. 1020 10214.4.2. Client Initiated Termination 1022 1023 If the client needs to terminate the synchronization process and it 1024 wishes to obtain the cookie that represents the current state of its 1025 data, it issues an LDAP Cancel operation [RFC3909]. The server 1026 responds immediately with a LDAP Cancel response [RFC3909]. The 1027 server MAY send any pending SearchResultEntry or 1028 SearchResultReference PDUs if the server cannot easily abort or 1029 remove those search results from its outgoing queue. The server 1030 SHOULD send as few of these remaining messages as possible. Finally, 1031 the server sends the message SearchResultDone with the Sync Done 1032 control attached. If the search was successful up to that point, the 1033 resultCode field of the SearchResultDone message MUST be canceled 1034 [RFC3909], and the cookie MUST be set in the Sync Done control. If 1035 there is an error condition, the server MAY return as described in 1036 section 4.4.1 above, or MAY return as described in [RFC3909]. 1037 1038 If the client is not interested in the state information, it can 1039 simply abandon the search operation or disconnect from the server. 1040 10414.5. Size and Time Limits 1042 1043 The server SHALL support size and time limits as specified in 1044 [RFC2251, Section 5]. The server SHOULD ensure that if the operation 1045 is terminated due to these conditions, the cookie is sent back to the 1046 client. 1047 10484.6. Operations on the Same Connection 1049 1050 It is permissible for the client to issue other LDAP operations on 1051 the connection used by the protocol. Since each LDAP 1052 request/response carries a message id there will be no ambiguity 1053 about which PDU belongs to which operation. By sharing the 1054 connection among multiple operations, the server will be able to 1055 conserve its resources. 1056 10574.7. Interactions with Other Controls 1058 1059 LCUP defines neither restrictions nor guarantees about the ability to 1060 use the controls defined in this document in conjunction with other 1061 LDAP controls, except for the following: A server MAY ignore non- 1062 critical controls supplied with the LCUP control. A server MAY 1063 1064 1065 1066Megginson, et al. Standards Track [Page 19] 1067 1068RFC 3928 LDAP Client Update Protocol October 2004 1069 1070 1071 ignore an LCUP defined control if it is non-critical and it is 1072 supplied with other critical controls. If a server receives a 1073 critical LCUP control with another critical control, and the server 1074 does not support both controls at the same time, the server SHOULD 1075 return unavailableCriticalExtension. 1076 1077 It is up to the server implementation to determine if the server 1078 supports controls such as the Sort or VLV or similar controls that 1079 change the order of the entries sent to the client. But note that it 1080 may be difficult or impossible for a server to perform an incremental 1081 synchronization in the presence of such controls, since the cookie 1082 will typically be based off a change number, or Change Sequence 1083 Number (CSN), or timestamp, or some criteria other than an 1084 alphabetical order. 1085 10864.8. Replication Considerations 1087 1088 Use of an LCUP cookie with multiple DSAs in a replicated environment 1089 is not defined by LCUP. An implementation of LCUP may support 1090 continuation of an LCUP session with another DSA holding a replica of 1091 the LCUP context. Clients MAY submit cookies returned by one DSA to 1092 a different DSA; it is up to the server to determine if a cookie is 1093 one they recognize or not and to return an appropriate result code if 1094 not. 1095 10965. Client Side Considerations 1097 10985.1. Using Cookies with Different Search Criteria 1099 1100 The cookie received from the server after a synchronization session 1101 SHOULD only be used with the same search specification as the search 1102 that generated the cookie. Some servers MAY allow the cookie to be 1103 used with a more restrictive search specification than the search 1104 that generated the cookie. If the server does not support the 1105 cookie, it MUST return lcupInvalidCookie. This is because the client 1106 can end up with an incomplete data store otherwise. A more 1107 restrictive search specification is one that would generate a subset 1108 of the data produced by the original search specification. 1109 11105.2. Renaming the Base Object 1111 1112 Because an LCUP client specifies the area of the tree with which it 1113 wishes to synchronize through the standard LDAP search specification, 1114 the client can be returned noSuchObject error if the root of the 1115 synchronization area was renamed between the synchronization sessions 1116 or during a synchronization session. If this condition occurs, the 1117 client can attempt to locate the root by using the root's UUID saved 1118 in client's local data store. It then can repeat the synchronization 1119 1120 1121 1122Megginson, et al. Standards Track [Page 20] 1123 1124RFC 3928 LDAP Client Update Protocol October 2004 1125 1126 1127 request using the new search base. In general, a client can detect 1128 that an entry was renamed and apply the changes received to the right 1129 entry by using the UUID rather than DN based addressing. 1130 11315.3. Use of Persistent Searches With Respect to Resources 1132 1133 Each active persistent operation requires that an open TCP connection 1134 be maintained between an LDAP client and an LDAP server that might 1135 not otherwise be kept open. Therefore, client implementors are 1136 encouraged to avoid using persistent operations for non-essential 1137 tasks and to close idle LDAP connections as soon as practical. The 1138 server may close connections if server resources become tight. 1139 11405.4. Continuation References to Other LCUP Contexts 1141 1142 The client MAY receive a continuation reference 1143 (SearchResultReference [RFC2251 SECTION 4.5.3]) if the search request 1144 spans multiple parts of the DIT, some of which may require a 1145 different LCUP cookie, some of which may not even be managed by LCUP. 1146 The client SHOULD maintain a cache of the LDAP URLs returned in the 1147 continuation references and the cookies associated with them. The 1148 client is responsible for performing another LCUP search to follow 1149 the references, and SHOULD use the cookie corresponding to the LDAP 1150 URL for that reference (if it has a cookie). 1151 11525.5. Referral Handling 1153 1154 The client may receive a referral (Referral [RFC2251 SECTION 4.1.11]) 1155 when the search base is a subordinate reference, and this will end 1156 the operation. 1157 11585.6. Multiple Copies of Same Entry During Sync Phase 1159 1160 The server MAY send the same entry multiple times during a sync phase 1161 if the entry changes during the sync phase. The client SHOULD use 1162 the last sent copy of the entry as the current one. 1163 11645.7. Handling Server Out of Resources Condition 1165 1166 If the client receives an lcupResourcesExhausted or 1167 lcupSecurityViolation resultCode, the client SHOULD wait at least 5 1168 seconds before attempting another operation. It is RECOMMENDED that 1169 the client use an exponential backoff strategy, but different clients 1170 may want to use different backoff strategies. 1171 1172 1173 1174 1175 1176 1177 1178Megginson, et al. Standards Track [Page 21] 1179 1180RFC 3928 LDAP Client Update Protocol October 2004 1181 1182 11836. Server Implementation Considerations 1184 11856.1. Server Support for UUIDs 1186 1187 Servers MUST support UUIDs. UUIDs are required in the Sync Update 1188 control. Additionally, server implementers SHOULD make the UUID 1189 values for the entries available as an attribute of the entry, and 1190 provide indexing or other mechanisms to allow clients to search for 1191 an entry using the UUID attribute in the search filter. The 1192 syncUpdate control provides a field UUIDAttribute to allow the server 1193 to let the client know the name or OID of the attribute to use to 1194 search for an entry by UUID. 1195 11966.2. Example of Using an RUV as the Cookie Value 1197 1198 By design, the protocol supports multiple cookie schemes. This is to 1199 allow different implementations the flexibility of storing any 1200 information applicable to their environment. A reasonable 1201 implementation for an LDUP compliant server would be to use the 1202 Replica Update Vector (RUV). For each master, RUV contains the 1203 largest CSN seen from this master. In addition, RUV implemented by 1204 some directory servers (not yet in LDUP) contains replica generation 1205 - an opaque string that identifies the replica's data store. The 1206 replica generation value changes whenever the replica's data is 1207 reloaded. Replica generation is intended to signal the 1208 replication/synchronization peers that the replica's data was 1209 reloaded and that all other replicas need to be reinitialized. RUV 1210 satisfies the three most important properties of the cookie: (1) it 1211 uniquely identifies the state of client's data, (2) it can be used to 1212 synchronize with multiple servers, and (3) it can be used to detect 1213 that the server's data was reloaded. If RUV is used as the cookie, 1214 entries last modified by a particular master must be sent to the 1215 client in the order of their last modified CSN. This ordering 1216 guarantees that the RUV can be updated after each entry is sent. 1217 12186.3. Cookie Support Issues 1219 12206.3.1. Support for Multiple Cookie Schemes 1221 1222 A server may support one or more LCUP cookie schemes. It is expected 1223 that schemes will be published along with their OIDs as RFCs. The 1224 server's DIT may be partitioned into different sections which may 1225 have different cookies associated with them. For example, some 1226 servers may use some sort of replication mechanism to support LCUP. 1227 If so, the DIT may be partitioned into multiple replicas. A client 1228 may send an LCUP search request that spans multiple replicas. Some 1229 parts of the DIT spanned by the search request scope may support LCUP 1230 and some may not. The server MUST send a SearchResultReference 1231 1232 1233 1234Megginson, et al. Standards Track [Page 22] 1235 1236RFC 3928 LDAP Client Update Protocol October 2004 1237 1238 1239 [RFC2251, SECTION 4.5.3] when the LCUP Context for a returned entry 1240 changes. The server SHOULD send all references to other LCUP 1241 Contexts in the search scope first, in order to allow the clients to 1242 process these searches in parallel. The LDAP URL(s) returned MUST 1243 contain the DN(s) of the base of another section of the DIT (however 1244 the server implementation has partitioned the DIT). The client will 1245 then issue another LCUP search using the LDAP URL returned. Each 1246 section of the DIT MAY require a different cookie value, so the 1247 client SHOULD maintain a cache, mapping the different LDAP URL values 1248 to different cookies. If the cookie changes, the scheme may change 1249 as well, but the cookie scheme MUST be the same within a given LCUP 1250 Context. 1251 12526.3.2. Information Contained in the Cookie 1253 1254 The cookie must contain enough information to allow the server to 1255 determine whether the cookie can be safely used with the search 1256 specification it is attached to. As discussed earlier in the 1257 document, the cookie SHOULD only be used with the search 1258 specification that is equal to the one for which the cookie was 1259 generated, but some servers MAY support using a cookie with a search 1260 specification that is more restrictive than the one used to generate 1261 the cookie. 1262 12636.4. Persist Phase Response Time 1264 1265 The specification makes no guarantees about how soon a server should 1266 send notification of a changed entry to the client during the persist 1267 phase. This is intentional as any specific maximum delay would be 1268 impossible to meet in a distributed directory service implementation. 1269 Server implementers are encouraged to minimize the delay before 1270 sending notifications to ensure that clients' needs for timeliness of 1271 change notification are met. 1272 12736.5. Scaling Considerations 1274 1275 Implementers of servers that support the mechanism described in this 1276 document should ensure that their implementation scales well as the 1277 number of active persistent operations and the number of changes made 1278 in the directory increases. Server implementers are also encouraged 1279 to support a large number of client connections if they need to 1280 support large numbers of persistent operations. 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290Megginson, et al. Standards Track [Page 23] 1291 1292RFC 3928 LDAP Client Update Protocol October 2004 1293 1294 12956.6. Alias Dereferencing 1296 1297 LCUP design does not consider issues associated with alias 1298 dereferencing in search. Clients MUST specify derefAliases as either 1299 neverDerefAliases or derefFindingBaseObj. Servers are to return 1300 protocolError if the client specifies either derefInSearching or 1301 derefAlways. 1302 13037. Synchronizing Heterogeneous Data Stores 1304 1305 Clients, like a meta directory join engine, synchronizing multiple 1306 writable data stores, will only work correctly if each piece of 1307 information comes from a single authoritative data source. In a 1308 replicated environment, an LCUP Context should employ the same 1309 conflict resolution scheme across all its replicas. This is because 1310 different systems have different notions of time and different update 1311 resolution procedures. As a result, a change applied on one system 1312 can be discarded by the other, thus preventing the data stores from 1313 converging. 1314 13158. IANA Considerations 1316 1317 This document lists several values that have been registered by the 1318 IANA. The following LDAP result codes have been assigned by IANA as 1319 described in section 3.6 of [RFC3383]: 1320 1321 lcupResourcesExhausted 113 1322 lcupSecurityViolation 114 1323 lcupInvalidData 115 1324 lcupUnsupportedScheme 116 1325 lcupReloadRequired 117 1326 1327 The three controls defined in this document have been registered as 1328 LDAP Protocol Mechanisms as described in section 3.2 of [RFC3383]. 1329 One OID, 1.3.6.1.1.7, has been assigned by IANA as described in 1330 section 3.1 of [RFC3383]. The OIDs for the controls defined in this 1331 document are derived as follows from the one assigned by IANA: 1332 1333 LCUP Sync Request Control 1.3.6.1.1.7.1 1334 LCUP Sync Update Control 1.3.6.1.1.7.2 1335 LCUP Sync Done Control 1.3.6.1.1.7.3 1336 13379. Security Considerations 1338 1339 In some situations, it may be important to prevent general exposure 1340 of information about changes that occur in an LDAP server. Therefore, 1341 servers that implement the mechanism described in this document 1342 SHOULD provide a means to enforce access control on the entries 1343 1344 1345 1346Megginson, et al. Standards Track [Page 24] 1347 1348RFC 3928 LDAP Client Update Protocol October 2004 1349 1350 1351 returned and MAY also provide specific access control mechanisms to 1352 control the use of the controls and extended operations defined in 1353 this document. 1354 1355 As with normal LDAP search requests, a malicious client can initiate 1356 a large number of persistent search requests in an attempt to consume 1357 all available server resources and deny service to legitimate 1358 clients. The protocol provides the means to stop malicious clients 1359 by disconnecting them from the server. The servers that implement 1360 the mechanism SHOULD provide the means to detect the malicious 1361 clients. In addition, the servers SHOULD provide the means to limit 1362 the number of resources that can be consumed by a single client. 1363 136410. References 1365 136610.1. Normative References 1367 1368 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1369 Requirement Levels", BCP 14, RFC 2119, March 1997. 1370 1371 [RFC2251] Wahl, M., Howes, T., and S. Kille, "Lightweight 1372 Directory Access Protocol (v3)", RFC 2251, December 1373 1997. 1374 1375 [RFC3383] Zeilenga, K., "Internet Assigned Numbers Authority 1376 (IANA) Considerations for Lightweight Directory Access 1377 Protocol (LDAP)", BCP 64, RFC 3383, September 2002. 1378 1379 [RFC3909] Zeilenga, K., "Lightweight Directory Access Protocol 1380 (LDAP) Cancel Operation", RFC 3909, October 2004. 1381 1382 [X.680] ITU-T, "Abstract Syntax Notation One (ASN.1) - 1383 Specification of Basic Notation", X.680, 1994. 1384 1385 [X.690] ITU-T, "Specification of ASN.1 encoding rules: Basic, 1386 Canonical, and Distinguished Encoding Rules", X.690, 1387 1994. 1388 1389 [UUID] International Organization for Standardization (ISO), 1390 "Information technology - Open Systems Interconnection - 1391 Remote Procedure Call", ISO/IEC 11578:1996. 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402Megginson, et al. Standards Track [Page 25] 1403 1404RFC 3928 LDAP Client Update Protocol October 2004 1405 1406 140710.2. Informative References 1408 1409 [RFC3384] Stokes, E., Weiser, R., Moats, R., and R. Huber, 1410 "Lightweight Directory Access Protocol (version 3) 1411 Replication Requirements", RFC 3384, October 2002. 1412 1413 [RFC3671] Zeilenga, K., "Collective Attributes in the Lightweight 1414 Directory Access Protocol (LDAP)", RFC 3671, December 1415 2003. 1416 1417 [RFC3672] Zeilenga, K. and S. Legg, "Subentries in the Lightweight 1418 Directory Access Protocol (LDAP)", RFC 3672, December 1419 2003. 1420 142111. Acknowledgments 1422 1423 The LCUP protocol is based in part on the Persistent Search Change 1424 Notification Mechanism defined by Mark Smith, Gordon Good, Tim Howes, 1425 and Rob Weltman, the LDAPv3 Triggered Search Control defined by Mark 1426 Wahl, and the LDAP Control for Directory Synchronization defined by 1427 Michael Armijo. The members of the IETF LDUP working group made 1428 significant contributions to this document. 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458Megginson, et al. Standards Track [Page 26] 1459 1460RFC 3928 LDAP Client Update Protocol October 2004 1461 1462 1463Appendix - Features Left Out of LCUP 1464 1465 There are several features present in other protocols or considered 1466 useful by clients that are currently not included in the protocol 1467 primarily because they are difficult to implement on the server. 1468 These features are briefly discussed in this section. 1469 1470Triggered Search Change Type 1471 1472 This feature is present in the Triggered Search specification. A 1473 flag is attached to each entry returned to the client indicating the 1474 reason why this entry is returned. The possible reasons from the 1475 document are: 1476 1477 - notChange: the entry existed in the directory and matched the 1478 search at the time the operation is being performed, 1479 1480 - enteredSet: the entry entered the result, 1481 1482 - leftSet: the entry left the result, 1483 1484 - modified: the entry was part of the result set, was modified or 1485 renamed, and still is in the result set. 1486 1487 The leftSet feature is particularly useful because it indicates to 1488 the client that an entry is no longer within the client's search 1489 specification and the client can remove the associated data from its 1490 data store. Ironically, this feature is the hardest to implement on 1491 the server because the server does not keep track of the client's 1492 state and has no easy way of telling which entries moved out of scope 1493 between synchronization sessions with the client. A compromise could 1494 be reached by only providing this feature for the operations that 1495 occur while the client is connected to the server. This is easier to 1496 accomplish because the decision about the change type can be made 1497 based only on the change without need for any historical information. 1498 This, however, would add complexity to the protocol. 1499 1500Persistent Search Change Type 1501 1502 This feature is present in the Persistent Search specification. 1503 Persistent search has the notion of changeTypes. The client 1504 specifies which type of updates will cause entries to be returned, 1505 and optionally whether the server tags each returned entry with the 1506 type of change that caused that entry to be returned. 1507 1508 For LCUP, the intention is full synchronization, not partial. Each 1509 entry returned by an LCUP search will have some change associated 1510 with it that may concern the client. The client may have to have a 1511 1512 1513 1514Megginson, et al. Standards Track [Page 27] 1515 1516RFC 3928 LDAP Client Update Protocol October 2004 1517 1518 1519 local index of entries by DN or UUID to determine if the entry has 1520 been added or just modified. It is easy for clients to determine if 1521 the entry has been deleted because the entryLeftSet value of the Sync 1522 Update control will be TRUE. 1523 1524Sending Changes 1525 1526 Some earlier synchronization protocols sent the client(s) only the 1527 modified attributes of the entry rather than the entire entry. While 1528 this approach can significantly reduce the amount of data returned to 1529 the client, it has several disadvantages. First, unless a separate 1530 mechanism (like the change type described above) is used to notify 1531 the client about entries moving into the search scope, sending only 1532 the changes can result in the client having an incomplete version of 1533 the data. Let's consider an example. An attribute of an entry is 1534 modified. As a result of the change, the entry enters the scope of 1535 the client's search. If only the changes are sent, the client would 1536 never see the initial data of the entry. Second, this feature is 1537 hard to implement since the server might not contain sufficient 1538 information to construct the changes based solely on the server's 1539 state and the client's cookie. On the other hand, this feature can 1540 be easily implemented by the client assuming that the client has the 1541 previous version of the data and can perform value by value 1542 comparisons. 1543 1544Data Size Limits 1545 1546 Some earlier synchronization protocols allowed clients to control the 1547 amount of data sent to them in the search response. This feature was 1548 intended to allow clients with limited resources to process 1549 synchronization data in batches. However, an LDAP search operation 1550 already provides the means for the client to specify the size limit 1551 by setting the sizeLimit field in the SearchRequest to the maximum 1552 number of entries the client is willing to receive. While the 1553 granularity is not the same, the assumption is that regular LDAP 1554 clients that can deal with the limitations of the LDAP protocol will 1555 implement LCUP. 1556 1557Data Ordering 1558 1559 Some earlier synchronization protocols allowed a client to specify 1560 that parent entries should be sent before the children for add 1561 operations and children entries sent before their parents during 1562 delete operations. This ordering helps clients to maintain a 1563 hierarchical view of the data in their data store. While possibly 1564 useful, this feature is relatively hard to implement and is expensive 1565 to perform. 1566 1567 1568 1569 1570Megginson, et al. Standards Track [Page 28] 1571 1572RFC 3928 LDAP Client Update Protocol October 2004 1573 1574 1575Authors' Addresses 1576 1577 Rich Megginson 1578 Netscape Communications Corp., an America Online company. 1579 360 W. Caribbean Drive 1580 Sunnyvale, CA 94089 1581 USA 1582 1583 Phone: +1 505 797-7762 1584 EMail: rmegginson0224@aol.com 1585 1586 1587 Olga Natkovich 1588 Yahoo, Inc. 1589 701 First Ave. 1590 Sunnyvale, CA 94089 1591 USA 1592 1593 Phone: +1 408 349-6153 1594 EMail: olgan@yahoo-inc.com 1595 1596 1597 Mark Smith 1598 Pearl Crescent, LLC 1599 447 Marlpool Drive 1600 Saline, MI 48176 1601 USA 1602 1603 Phone: +1 734 944-2856 1604 EMail: mcs@pearlcrescent.com 1605 1606 1607 Jeff Parham 1608 Microsoft Corporation 1609 One Microsoft Way 1610 Redmond, WA 98052-6399 1611 USA 1612 1613 Phone: +1 425 882-8080 1614 EMail: jeffparh@microsoft.com 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626Megginson, et al. Standards Track [Page 29] 1627 1628RFC 3928 LDAP Client Update Protocol October 2004 1629 1630 1631Full Copyright Statement 1632 1633 Copyright (C) The Internet Society (2004). 1634 1635 This document is subject to the rights, licenses and restrictions 1636 contained in BCP 78, and at www.rfc-editor.org, and except as set 1637 forth therein, the authors retain all their rights. 1638 1639 This document and the information contained herein are provided on an 1640 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1641 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 1642 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 1643 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 1644 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1645 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1646 1647Intellectual Property 1648 1649 The IETF takes no position regarding the validity or scope of any 1650 Intellectual Property Rights or other rights that might be claimed to 1651 pertain to the implementation or use of the technology described in 1652 this document or the extent to which any license under such rights 1653 might or might not be available; nor does it represent that it has 1654 made any independent effort to identify any such rights. Information 1655 on the ISOC's procedures with respect to rights in ISOC Documents can 1656 be found in BCP 78 and BCP 79. 1657 1658 Copies of IPR disclosures made to the IETF Secretariat and any 1659 assurances of licenses to be made available, or the result of an 1660 attempt made to obtain a general license or permission for the use of 1661 such proprietary rights by implementers or users of this 1662 specification can be obtained from the IETF on-line IPR repository at 1663 http://www.ietf.org/ipr. 1664 1665 The IETF invites any interested party to bring to its attention any 1666 copyrights, patents or patent applications, or other proprietary 1667 rights that may cover technology that may be required to implement 1668 this standard. Please address the information to the IETF at ietf- 1669 ipr@ietf.org. 1670 1671Acknowledgement 1672 1673 Funding for the RFC Editor function is currently provided by the 1674 Internet Society. 1675 1676 1677 1678 1679 1680 1681 1682Megginson, et al. Standards Track [Page 30] 1683 1684