idnits 2.17.1 draft-ietf-ldup-lcup-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 4 instances of too long lines in the document, the longest one being 2 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 1072 has weird spacing: '...Servers are t...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (August 2003) is 7558 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 357 -- Looks like a reference, but probably isn't: '1' on line 358 -- Looks like a reference, but probably isn't: '2' on line 331 -- Looks like a reference, but probably isn't: '3' on line 332 -- Looks like a reference, but probably isn't: '4' on line 333 -- Looks like a reference, but probably isn't: '5' on line 334 == Missing Reference: 'Section 5' is mentioned on line 866, but not defined == Unused Reference: 'RFC2252' is defined on line 1140, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2251 (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) ** Obsolete normative reference: RFC 2252 (Obsoleted by RFC 4510, RFC 4512, RFC 4517, RFC 4523) -- No information found for draft-zeilenga-ldap-cancel-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'CANCEL' -- Possible downref: Non-RFC (?) normative reference: ref. 'UUID' ** Obsolete normative reference: RFC 3383 (Obsoleted by RFC 4520) -- No information found for draft-zeilenga-ldap-subentry-xx - is the name correct? -- No information found for draft-zeilenga-ldap-collective-xx - is the name correct? Summary: 5 errors (**), 0 flaws (~~), 4 warnings (==), 13 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 LDUP 2 Internet Draft R. Megginson, Editor 3 Document: draft-ietf-ldup-lcup-06.txt M. Smith 4 Category: Proposed Standard Netscape 5 Expires: February 2004 Communications 6 Corp. 7 O. Natkovich 8 Yahoo 9 J. Parham 10 Microsoft 11 Corporation 13 August 2003 15 LDAP Client Update Protocol 17 Status of this Memo 19 This document is an Internet-Draft and is in full conformance with 20 all provisions of Section 10 of RFC 2026 [RFC2026]. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF), its areas, and its working groups. Note that 24 other groups may also distribute working documents as Internet- 25 Drafts. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 The list of current Internet-Drafts can be accessed at 33 http://www.ietf.org/ietf/1id-abstracts.txt 34 The list of Internet-Draft Shadow Directories can be accessed at 35 http://www.ietf.org/shadow.html. 37 Abstract 39 This document defines the Lightweight Directory Access Protocol 40 (LDAP) Client Update Protocol (LCUP). The protocol is intended to 41 allow an LDAP client to synchronize with the content of a directory 42 information tree (DIT) stored by an LDAP server and to be notified 43 about the changes to that content. 45 Conventions used in this document 46 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 47 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 48 document are to be interpreted as described in RFC 2119 [RFC2119]. 50 Table of Contents 52 1. Overview......................................................3 53 2. Applicability.................................................4 54 3. Specification of Protocol Elements............................5 55 3.1 ASN.1 Considerations.......................................5 56 3.2 Universally Unique Identifiers.............................5 57 3.3 LCUP Scheme and LCUP Cookie................................5 58 3.4 LCUP Context...............................................6 59 3.5 Additional LDAP Result Codes defined by LCUP...............6 60 3.6 Sync Request Control.......................................7 61 3.7 Sync Update Control........................................7 62 3.8 Sync Done Control..........................................8 63 4. Protocol Usage and Flow.......................................8 64 4.1 LCUP Search Requests.......................................8 65 4.1.1 Initial Synchronization and Full Resync................9 66 4.1.2 Incremental or Update Synchronization..................9 67 4.1.3 Persistent Only.......................................10 68 4.2 LCUP Search Responses.....................................10 69 4.2.1 Sync Update Informational Responses...................10 70 4.2.2 Cookie Return Frequency...............................11 71 4.2.3 Definition of an Entry That Has Entered the Result Set12 72 4.2.4 Definition of an Entry That Has Changed...............12 73 4.2.5 Definition of an Entry That Has Left the Result Set...13 74 4.2.6 Results For Entries Present in the Result Set.........13 75 4.2.7 Results For Entries That Have Left the Result Set.....14 76 4.3 Responses Requiring Special Consideration.................15 77 4.3.1 Returning Results During the Persistent Phase.........15 78 4.3.2 No Mixing of Sync Phase with Persist Phase............15 79 4.3.3 Returning Updated Results During the Sync Phase.......15 80 4.3.4 Operational Attributes and Administrative Entries.....15 81 4.3.5 Virtual Attributes....................................16 82 4.3.6 Modify DN and Delete Operations Applied to Subtrees...16 83 4.3.7 Convergence Guarantees................................17 84 4.4 LCUP Search Termination...................................17 85 4.4.1 Server Initiated Termination..........................17 86 4.4.2 Client Initiated Termination..........................18 87 4.5 Size and Time Limits......................................18 88 4.6 Operations on the Same Connection.........................18 89 4.7 Interactions with Other Controls..........................19 90 4.8 Replication Considerations................................19 91 5. Client Side Considerations...................................19 92 5.1 Using Cookies with Different Search Criteria..............19 93 5.2 Renaming the Base Object..................................19 94 5.3 Use of Persistent Searches With Respect to Resources......20 95 5.4 Continuation References to Other LCUP Contexts............20 96 5.5 Referral Handling.........................................20 97 5.6 Multiple Copies of Same Entry During Sync Phase...........20 98 5.7 Handling Server Out of Resources Condition................20 99 6. Server Implementation Considerations.........................21 100 6.1 Server Support for UUIDs..................................21 101 6.2 Example of Using an RUV as the Cookie Value...............21 102 6.3 Cookie Support Issues.....................................21 103 6.3.1 Support for Multiple Cookie Schemes...................21 104 6.3.2 Information Contained in the Cookie...................22 105 6.4 Persist Phase Response Time...............................22 106 6.5 Scaling Considerations....................................22 107 6.6 Alias Dereferencing.......................................22 108 7. Synchronizing Heterogeneous Data Stores......................23 109 IANA Considerations.............................................23 110 Security Considerations.........................................23 111 Normative References............................................24 112 Informative References..........................................24 113 Acknowledgments.................................................25 114 Author's Addresses..............................................25 115 Full Copyright Statement........................................25 116 Appendix - Features Left Out of LCUP............................26 118 1. Overview 120 The LCUP protocol is intended to allow LDAP clients to synchronize 121 with the content stored by LDAP servers. 123 The problem areas addressed by the protocol include: 125 - Mobile clients that maintain a local read-only copy of the 126 directory data. While off-line, the client uses the local copy of 127 the data. When the client connects to the network, it synchronizes 128 with the current directory content and can optionally receive 129 notification about the changes that occur while it is on-line. For 130 example, a mail client can maintain a local copy of the corporate 131 address book that it synchronizes with the master copy whenever the 132 client is connected to the corporate network. 134 - Applications intending to synchronize heterogeneous data stores. A 135 meta directory application, for instance, would periodically 136 retrieve a list of modified entries from the directory, construct 137 the changes and apply them to a foreign data store. 139 - Clients that need to take certain actions when a directory entry is 140 modified. For instance, an electronic mail repository may want to 141 perform a "create mailbox" task when a new person entry is added to 142 an LDAP directory and a "delete mailbox" task when a person entry 143 is removed. 145 The problem areas not being considered: 147 - directory server to directory server synchronization. The IETF is 148 developing a LDAP replication protocol, called LDUP [RFC3384], 149 which is specifically designed to address this problem area. 151 There are currently several protocols in use for LDAP client server 152 synchronization. While each protocol addresses the needs of a 153 particular group of clients (e.g., on-line clients or off-line 154 clients), none satisfies the requirements of all clients in the 155 target group. For instance, a mobile client that was off-line and 156 wants to become up to date with the server and stay up to date while 157 connected can't be easily supported by any of the existing protocols. 159 LCUP is designed such that the server does not need to maintain state 160 information specific to individual clients. The server may need to 161 maintain additional state information about attribute modifications, 162 deleted entries, and moved/renamed entries. The clients are 163 responsible for storing the information about how up to date they are 164 with respect to the server's content. LCUP design avoids the need 165 for LCUP-specific update agreements to be made between client and 166 server prior to LCUP use. The client decides when and from where to 167 retrieve the changes. LCUP design requires clients to initiate the 168 update session and "pull" the changes from server. 170 LCUP operations are subject to administrative and access control 171 policies enforced by the server. 173 2. Applicability 175 LCUP will work best if the following conditions are met: 177 1) The server stores some degree of historical state or change 178 information to reduce the amount of wire traffic required for 179 incremental synchronizations. The optimal balance between server 180 state and wire traffic varies amongst implementations and usage 181 scenarios, and is therefore left in the hands of implementers. 183 2) The client cannot be assumed to understand the physical 184 information model (virtual attributes, operational attributes, 185 subentries, etc.) implemented by the server. Optimizations would be 186 possible if such assumptions could be made. 188 3) Meta data changes and renames and deletions of large subtrees are 189 very infrequent. LCUP makes these assumptions in order to reduce 190 client complexity required to deal with these special operations, 191 though when they do occur they may result in a large number of 192 incremental update messages or a full resync. 194 3. Specification of Protocol Elements 196 The following sections define the new elements required to use this 197 protocol. 199 3.1 ASN.1 Considerations 201 Protocol elements are described using ASN.1 [X.680]. The term "BER- 202 encoded" means the element is to be encoded using the Basic Encoding 203 Rules [X.690] under the restrictions detailed in Section 5.1 of 204 [RFC2251]. All ASN.1 in this document uses implicit tags. 206 3.2 Universally Unique Identifiers 208 Distinguished names can change, so are therefore unreliable as 209 identifiers. A Universally Unique Identifier (or UUID for short) 210 MUST be used to uniquely identify entries used with LCUP. The UUID 211 is part of the Sync Update control value (see below) returned with 212 each search result. The server SHOULD provide the UUID as a single 213 valued operational attribute of the entry (e.g. "entryUUID"). We 214 RECOMMEND that the server provides a way to do efficient (i.e. 215 indexed) searches for values of UUID e.g. by using a search filter 216 like (entryUUID=) to quickly search for and retrieve 217 an entry based on its UUID. Servers SHOULD use a UUID format as 218 specified in [UUID]. The UUID used by LCUP is a value of the 219 following ASN.1 type: 221 LCUPUUID ::= OCTET STRING 223 3.3 LCUP Scheme and LCUP Cookie 225 The LCUP protocol uses a cookie to hold the state of the client's 226 data with respect to the server's data. Each cookie format is 227 uniquely identified by its scheme. The LCUP Scheme is a value of the 228 following ASN.1 type: 230 LCUPScheme ::= LDAPOID 232 This is the OID which identifies the format of the LCUP Cookie value. 233 The scheme OID, as all object identifiers, MUST be unique for a given 234 cookie scheme. The cookie value may be opaque or it may be exposed 235 to LCUP clients. For cookie schemes that expose their value, the 236 preferred form of documentation is an RFC. It is expected that there 237 will be one or more standards track cookie schemes where the value 238 format is exposed and described in detail. 240 The LCUP Cookie is a value of the following ASN.1 type: 242 LCUPCookie ::= OCTET STRING 244 This is the actual data describing the state of the client's data. 245 This value may be opaque, or its value may have some well-known 246 format, depending on the scheme. 248 Further uses of the LCUP Cookie value are described below. 250 3.4 LCUP Context 252 A part of the DIT which is enabled for LCUP is referred to as an LCUP 253 Context. A server may support one or more LCUP Contexts. For 254 example, a server with two naming contexts may support LCUP in one 255 naming context but not the other, or support different LCUP cookie 256 schemes in each naming context. Each LCUP Context MAY use a 257 different cookie scheme. An LCUP search will not cross an LCUP 258 Context boundary, but will instead return a SearchResultReference 259 message, with the LDAP URL specifying the same host and port as 260 currently being searched, and with the baseDN set to the baseDN of 261 the new LCUP Context. The client is then responsible for issuing 262 another search using the new baseDN, and possibly a different cookie 263 if that LCUP Context uses a different cookie. The client is 264 responsible for maintaining a mapping of the LDAP URL to its 265 corresponding cookie. 267 3.5 Additional LDAP Result Codes defined by LCUP 269 Implementations of this specification SHALL recognize the following 270 additional resultCode values. The LDAP result code names and numbers 271 defined in the following table are to be replaced with IANA assigned 272 result code names and numbers per RFC 3383 [RFC3383]. 274 lcupResourcesExhausted (TBD) the server is running out of resources 275 lcupSecurityViolation (TBD) the client is suspected of malicious 276 actions 277 lcupInvalidData (TBD) invalid scheme or cookie was supplied by 278 the client 279 lcupUnsupportedScheme (TBD) The cookie scheme is a valid OID but is 280 not supported by this server 281 lcupReloadRequired (TBD) indicates that client data needs to be 282 reinitialized. This reason is returned 283 if the server does not contain 284 sufficient information to synchronize 285 the client or if the server's data was 286 reloaded since the last synchronization 287 session 289 The uses of these codes are described below. 291 3.6 Sync Request Control 293 The Sync Request Control is an LDAP Control [RFC2251, Section 4.1.2] 294 where the controlType is the object identifier IANA-ASSIGNED-OID.1 295 and the controlValue, an OCTET STRING, contains a BER-encoded 296 syncRequestControlValue. 298 syncRequestControlValue ::= SEQUENCE { 299 updateType ENUMERATED { 300 syncOnly (0), 301 syncAndPersist (1), 302 persistOnly (2) }, 303 sendCookieInterval [0] INTEGER OPTIONAL, 304 scheme [1] LCUPScheme OPTIONAL, 305 cookie [2] LCUPCookie OPTIONAL 306 } 308 sendCookieInterval - the server SHOULD send the cookie back in the 309 Sync Update control value (defined below) for every 310 sendCookieInterval number of SearchResultEntry and 311 SearchResultReference PDUs returned to the client. For example, if 312 the value is 5, the server SHOULD send the cookie back in the Sync 313 Update control value for every 5 search results returned to the 314 client. If this value is absent, zero or less than zero, the server 315 chooses the interval. 317 The Sync Request Control is only applicable to the searchRequest 318 message. Use of this control is described below. 320 3.7 Sync Update Control 322 The Sync Update Control is an LDAP Control [RFC2251, Section 4.1.2] 323 where the controlType is the object identifier IANA-ASSIGNED-OID.2 324 and the controlValue, an OCTET STRING, contains a BER-encoded 325 syncUpdateControlValue. 327 syncUpdateControlValue ::= SEQUENCE { 328 stateUpdate BOOLEAN, 329 entryUUID [0] LCUPUUID OPTIONAL, -- REQUIRED for entries -- 330 UUIDAttribute [1] AttributeType OPTIONAL, 331 entryLeftSet [2] BOOLEAN, 332 persistPhase [3] BOOLEAN, 333 scheme [4] LCUPScheme OPTIONAL, 334 cookie [5] LCUPCookie OPTIONAL 335 } 337 The field UUIDAttribute contains the name or OID of the attribute 338 that the client should use to perform searches for entries based on 339 the UUID. The client should be able to use it in an equality search 340 filter e.g. "(=)" and should be 341 able to use it in the attribute list of the search request to return 342 its value. The UUIDAttribute field may be omitted if the server does 343 not support searching on the UUID values. 345 The Sync Update Control is only applicable to SearchResultEntry and 346 SearchResultReference messages. Although entryUUID is OPTIONAL, it 347 MUST be used with SearchResultEntry messages. Use of this control is 348 described below. 350 3.8 Sync Done Control 352 The Sync Done Control is an LDAP Control [RFC2251, Section 4.1.2] 353 where the controlType is the object identifier IANA-ASSIGNED-OID.3 354 and the controlValue contains a BER-encoded syncDoneValue. 356 syncDoneValue ::= SEQUENCE { 357 scheme [0] LCUPScheme OPTIONAL, 358 cookie [1] LCUPCookie OPTIONAL 359 } 361 The Sync Done Control is only applicable to SearchResultDone message. 362 Use of this control is described below. 364 4. Protocol Usage and Flow 366 4.1 LCUP Search Requests 368 A client initiates a synchronization or persistent search session 369 with a server by attaching a Sync Request control to an LDAP 370 searchRequest message. The search specification determines the part 371 of the directory information tree (DIT) the client wishes to 372 synchronize with, the set of attributes it is interested in and the 373 amount of data the client is willing to receive. The Sync Request 374 control contains the client's request specification. 376 If there is an error condition, the server MUST immediately return a 377 SearchResultDone message with the resultCode set to an error code. 378 This table maps a condition to its corresponding behavior and 379 resultCode. 381 Condition Behavior or resultCode 383 Sync Request Control is not Server behaves as [RFC2251, Section 384 supported 4.1.2] - specifically, if the 385 criticality of the control is FALSE, 386 the server will process the request 387 as a normal search request 389 Scheme is not supported lcupUnsupportedScheme 391 A control value field is lcupInvalidData 392 invalid (e.g. illegal 393 updateType, or the scheme is 394 not a valid OID, or the cookie 395 is invalid) 397 Server is running out of lcupResourcesExhausted 398 resources 400 Server suspects client of lcupSecurityViolation 401 malicious behavior (frequent 402 connects/disconnects, etc.) 404 The server cannot bring the lcupReloadRequired 405 client up to date (server data 406 has been reloaded, or other 407 changes that prevent 408 convergence) 410 4.1.1 Initial Synchronization and Full Resync 412 For an initial synchronization or full resync, the fields of the Sync 413 Request control MUST be specified as follows: 415 updateType - MUST be set to syncOnly or syncAndPersist 416 sendCookieInterval - MAY be set 417 scheme - MAY be set - if set, the server MUST use this specified 418 scheme or return lcupUnsupportedScheme (see above) - if not set, the 419 server MAY use any scheme it supports. 420 cookie - MUST NOT be set 422 If the request was successful, the client will receive results as 423 described in the section "LCUP Search Responses" below. 425 4.1.2 Incremental or Update Synchronization 427 For an incremental or update synchronization, the fields of the Sync 428 Request control MUST be specified as follows: 430 updateType - MUST be set to syncOnly or syncAndPersist 431 sendCookieInterval - MAY be set 432 scheme - MUST be set 433 cookie - MUST be set 434 The client SHOULD always use the latest cookie it received from the 435 server. 437 If the request was successful, the client will receive results as 438 described in the section "LCUP Search Responses" below. 440 4.1.3 Persistent Only 442 For persistent only search request, the fields of the Sync Request 443 MUST be specified as follows: 445 updateType - MUST be set to persistOnly 446 sendCookieInterval - MAY be set 447 scheme - MAY be set - if set, the server MUST use this specified 448 scheme or return lcupUnsupportedScheme (see above) - if not set, the 449 server MAY use any scheme it supports. 450 cookie - MAY be set, but the server MUST ignore it 452 If the request was successful, the client will receive results as 453 described in the section "LCUP Search Responses" below. 455 4.2 LCUP Search Responses 457 In response to the client's LCUP request, the server returns zero or 458 more SearchResultEntry or SearchResultReference PDU that fits the 459 client's specification, followed by a SearchResultDone PDU. The 460 behavior is as specified in [RFC2251 Section 4.5]. Each 461 SearchResultEntry or SearchResultReference PDU also contains a Sync 462 Update control that describes the LCUP state of the returned entry. 463 The SearchResultDone PDU contains a Sync Done control. The following 464 sections specify behaviors in addition to [RFC2251 Section 4.5]. 466 4.2.1 Sync Update Informational Responses 468 The server may use the Sync Update control to return information not 469 related to a particular entry. It MAY do this at any time to return 470 a cookie to the client, or to inform the client that the sync phase 471 of a syncAndPersist search is complete and the persist phase has 472 begun. It MAY do this during the persist phase even though no entry 473 has changed that would have normally triggered a response. In order 474 to do this it is REQUIRED to return the following: 476 - A SearchResultEntry PDU with the objectName field set to the DN of 477 the baseObject of the search request and with an empty attribute 478 list. 479 - A Sync Update control value with the fields set to the following: 480 stateUpdate - MUST be set to TRUE 481 entryUUID - SHOULD be set to the UUID of the baseObject of the 482 search request 484 entryLeftSet - MUST be set to FALSE 485 persistPhase - MUST be FALSE if the search is in the sync phase 486 of a request, and MUST be TRUE if the search is in the 487 persist phase 488 UUIDAttribute - SHOULD only be set if this is either the first 489 result returned or if the attribute has changed 490 scheme - MUST be set if the cookie is set and the cookie format 491 has changed; otherwise, it MAY be omitted 492 cookie - SHOULD be set 494 If the server merely wants to return a cookie to the client, it 495 should return as above with the cookie field set. 497 During a syncAndPersist request, the server MUST return as above 498 immediately after the last entry of the sync phase has been sent and 499 before the first entry of the persist phase has been sent. In this 500 case, the persistPhase field MUST be set to TRUE. This lets the 501 client know that the sync phase is complete and the persist phase is 502 starting. 504 4.2.2 Cookie Return Frequency 506 The cookie field of the Sync Update control value MAY be set in any 507 returned result, during both the sync phase and the persist phase. 508 The server should return the cookie to the client often enough for 509 the client to resync in a reasonable period of time in case the 510 search is disconnected or otherwise terminated. The 511 sendCookieInterval field in the Sync Request control is a suggestion 512 to the server of how often to return the cookie in the Sync Update 513 control. The server SHOULD respect this value. 515 The scheme field of the Sync Update control value MUST be set if the 516 cookie is set and the cookie format has changed; otherwise, it MAY be 517 omitted. 519 Some clients may have unreliable connections, for example, a wireless 520 device or a WAN connection. These clients may want to insure that 521 the cookie is returned often in the Sync Update control value, so 522 that if they have to reconnect, they do not have to process many 523 redundant entries. These clients should set the sendCookieInterval 524 in the Sync Request control value to a low number, perhaps even 1. 525 Some clients may have a limited bandwidth connection, and may not 526 want to receive the cookie very often, or even at all (however, the 527 cookie is always sent back in the Sync Done control value upon 528 successful completion). These clients should set the 529 sendCookieInterval in the Sync Request control value to a high 530 number. 532 A reasonable behavior of the server is to return the cookie only when 533 data in the LCUP context has changed, even if the client has 534 specified a frequent sendCookieInterval. If nothing has changed, the 535 server can probably save some bandwidth by not returning the cookie. 537 4.2.3 Definition of an Entry That Has Entered the Result Set 539 An entry SHALL BE considered to have entered the client's search 540 result set if one of the following conditions is met: 542 - During the sync phase for an incremental sync operation, the entry 543 is present in the search result set but was not present before; this 544 can be due to the entry being added via an LDAP Add operation, or by 545 the entry being moved into the result set by an LDAP Modify DN 546 operation, or by some modification to the entry that causes it to 547 enter the result set (e.g. adding an attribute value that matches the 548 clients search filter), or by some meta-data change that causes the 549 entry to enter the result set (e.g. relaxing of some access control 550 that permits the entry to be visible to the client) 552 - During the persist phase for a persistent search operation, the 553 entry enters the search result set; this can be due to the entry 554 being added via an LDAP Add operation, or by the entry being moved 555 into the result set by an LDAP Modify DN operation, or by some 556 modification to the entry that causes it to enter the result set 557 (e.g. adding an attribute value that matches the clients search 558 filter), or by some meta-data change that causes the entry to enter 559 the result set (e.g. relaxing of some access control that permits the 560 entry to be visible to the client) 562 4.2.4 Definition of an Entry That Has Changed 564 An entry SHALL BE considered to be changed if one or more of the 565 attributes in the attribute list in the search request have been 566 modified. For example, if the search request listed the attributes 567 "cn sn uid", and there is an entry in the client's search result set 568 with the "cn" attribute that has been modified, the entry is 569 considered to be modified. The modification may be due to an LDAP 570 Modify operation or by some change to the meta-data for the entry 571 (e.g. virtual attributes) that causes some change to the value of the 572 specified attributes. 574 The converse of this is that an entry SHALL NOT BE considered to be 575 changed if none of the attributes in the attribute list of the search 576 request are modified attributes of the entry. For example, if the 577 search request listed the attributes "cn sn uid", and there is an 578 entry in the client's search result set with the "foo" attribute that 579 has been modified, and none of the "cn" or "sn" or "uid" attributes 580 have been modified, the entry is NOT considered to be changed. 582 4.2.5 Definition of an Entry That Has Left the Result Set 584 An entry SHALL BE considered to have left the client's search result 585 set if one of the following conditions is met: 587 - During the sync phase for an incremental sync operation, the entry 588 is not present in the search result set but was present before; this 589 can be due to the entry being deleted via an LDAP Delete operation, 590 or by the entry leaving the result set via an LDAP Modify DN 591 operation, or by some modification to the entry that causes it to 592 leave the result set (e.g. changing/removing an attribute value so 593 that it no longer matches the client's search filter), or by some 594 meta-data change that causes the entry to leave the result set (e.g. 595 adding of some access control that denies the entry to be visible to 596 the client) 598 - During the persist phase for a persistent search operation, the 599 entry leaves the search result set; this can be due to the entry 600 being deleted via an LDAP Delete operation, or by the entry leaving 601 the result set via an LDAP Modify DN operation, or by some 602 modification to the entry that causes it to leave the result set 603 (e.g. changing/removing an attribute value so that it no longer 604 matches the client's search filter), or by some meta-data change that 605 causes the entry to leave the result set (e.g. adding of some access 606 control that denies the entry to be visible to the client). 608 4.2.6 Results For Entries Present in the Result Set 610 An entry SHOULD be returned as present under the following 611 conditions: 613 - The request is an initial synchronization or full resync request 614 and the entry is present in the client's search result set 615 - The request is an incremental synchronization and the entry has 616 changed or entered the result set since the last sync 617 - The search is in the persist phase and the entry enters the result 618 set or changes 620 For a SearchResultEntry return, the fields of the Sync Update control 621 value MUST be set as follows: 623 stateUpdate - MUST be set to FALSE 624 entryUUID - MUST be set to the UUID of the entry 625 entryLeftSet - MUST be set to FALSE 626 persistPhase - MUST be set to FALSE if during the sync phase or 627 TRUE if during the persist phase 628 UUIDAttribute - SHOULD only be set if this is either the first 629 result returned or if the attribute has changed 631 scheme - as above 632 cookie - as above 634 The searchResultReference return will look the same, except that the 635 entryUUID is not required. If it is specified, it MUST contain the 636 UUID of the DSE holding the reference knowledge. 638 4.2.7 Results For Entries That Have Left the Result Set 640 An entry SHOULD be returned as having left the result set under the 641 following conditions: 643 - The request is an incremental synchronization during the sync phase 644 and the entry has left the result set 645 - The search is in the persist phase and the entry has left the 646 result set 647 - The entry has left the result set as a result of an LDAP Delete or 648 LDAP Modify DN operation against the entry itself (i.e. not as a 649 result of an operation against its parent or ancestor) 651 For a SearchResultEntry return where the entry has left the result 652 set, the fields of the Sync Update control value MUST be set as 653 follows: 655 stateUpdate - MUST be set to FALSE 656 entryUUID - MUST be set to the UUID of the entry that left the 657 result set 658 entryLeftSet - MUST be set to TRUE 659 persistPhase - MUST be set to FALSE if during the sync phase or 660 TRUE if during the persist phase 661 UUIDAttribute - SHOULD only be set if this is either the first 662 result returned or if the attribute has changed 663 scheme - as above 664 cookie - as above 666 The searchResultReference return will look the same, except that the 667 entryUUID is not required. If it is specified, it MUST contain the 668 UUID of the DSE holding the reference knowledge. 670 Some server implementations keep track of deleted entries using a 671 tombstone - a hidden entry that keeps track of the state, but not all 672 of the data, of an entry that has been deleted. In this case, the 673 tombstone may not contain all of the original attributes of the 674 entry, and therefore it may be impossible for the server to determine 675 if an entry should be removed from the result set based on the 676 attributes in the client's search request. Servers SHOULD keep 677 enough information about the attributes in the deleted entries to 678 determine if an entry should be removed from the result set. Since 679 this may not be possible, the server MAY return an entry as having 680 left the result set even if it is not or never was in the client's 681 result set. Clients MUST ignore these notifications. 683 4.3 Responses Requiring Special Consideration 685 The following sections describe special handling that may be required 686 when returning results. 688 4.3.1 Returning Results During the Persistent Phase 690 During the persistent phase, the server SHOULD return the changed 691 entries to the client as quickly as possible. 693 4.3.2 No Mixing of Sync Phase with Persist Phase 695 During a sync phase, the server MUST NOT return any entries with the 696 persistPhase flag set to TRUE, and during the persist phase, all 697 entries returned MUST have the persistPhase flag set to TRUE. The 698 server MUST NOT mix and match sync phase entries with persist phase 699 entries. If there are any sync phase entries to return, they MUST be 700 returned before any persist phase entries are returned. 702 4.3.3 Returning Updated Results During the Sync Phase 704 There may be updates to the entries in the result set of a sync phase 705 search during the actual search operation. If the DSA is under a 706 heavy update load, and it attempts to send all of those updated 707 entries to the client in addition to the other updates it was already 708 planning to send for the sync phase, the server may never get to the 709 end of the sync phase. Therefore, it is left up to the discretion of 710 the server implementation to decide when the client is "in sync" - 711 that is, when to end a syncOnly request, or when to send the Sync 712 Update Informational Response between the sync phase and the persist 713 phase of a syncAndPersist request. The server MAY send the same 714 entry multiple times during the sync phase if the entry changes 715 during the sync phase. 717 A reasonable behavior is for the server to generate a cookie based on 718 the server state at the time the client initiated the LCUP request, 719 and only send entries up to that point during the sync phase. 720 Entries updated after that point will be returned only during the 721 persist phase of a syncAndPersist request, or only upon an 722 incremental synchronization. 724 4.3.4 Operational Attributes and Administrative Entries 726 An operational attribute SHOULD be returned if it is specified in the 727 attributes list and would normally be returned as subject to the 728 constraints of [RFC2251 Section 4.5]. If the server does not support 729 syncing of operational attributes, the server MUST return a 730 SearchResultDone message with a resultCode of unwillingToPerform. 732 LDAP Subentries [SUBENTRY] SHOULD be returned if they would normally 733 be returned by the search request. If the server does not support 734 syncing of LDAP Subentries, and the server can determine from the 735 search request that the client has requested LDAP Subentries to be 736 returned (e.g. search control or search filter), the server MUST 737 return a SearchResultDone message with a resultCode of 738 unwillingToPerform. Otherwise, the server MAY simply omit returning 739 LDAP Subentries. 741 4.3.5 Virtual Attributes 743 An entry may have attributes whose presence in the entry, or presence 744 of values of the attribute, is generated on the fly, possibly by some 745 mechanism outside of the entry, elsewhere in the DIT. An example of 746 this is collective attributes [COLLECTIVE]. These attributes shall 747 be referred to in this document as virtual attributes. 749 LCUP treats these attributes the same way as normal, non-virtual 750 attributes. A virtual attribute SHOULD be returned if it is 751 specified in the attributes list and would normally be returned as 752 subject to the constraints of [RFC2251 Section 4.5]. If the server 753 does not support syncing of virtual attributes, the server MUST 754 return a SearchResultDone message with a resultCode of 755 unwillingToPerform. 757 One consequence of this is that if you change the definition of a 758 virtual attribute such that it makes the value of that attribute 759 change in many entries in the client's search scope, this means that 760 a server may have to return many entries to the client as a result of 761 that one change. It is not anticipated that this will be a frequent 762 occurrence, and the server has the option to simply force the client 763 to resync if necessary. 765 It is also possible that a future LDAP control will allow the client 766 to request only virtual or only non-virtual attributes. 768 4.3.6 Modify DN and Delete Operations Applied to Subtrees 770 There is a special case where a Modify DN or a Delete operation is 771 applied to the base entry of a subtree, and either that base entry or 772 entries in the subtree are within the scope of an LCUP search 773 request. In this case, all of the entries in the subtree are 774 implicitly renamed or removed. 776 In either of these cases, the server MUST do one of the following: 778 - treat all of these entries as having been renamed or removed and 779 return each entry to the client as such 780 - decide that this would be prohibitively expensive, and force the 781 client to resync 783 If the search base object has been renamed, and the client has 784 received a noSuchObject as the result of a search request, the client 785 MAY use the entryUUID and UUIDAttribute to locate the new DN that is 786 the result of the modify DN operation. 788 4.3.7 Convergence Guarantees 790 If at any time during an LCUP search, either during the sync phase or 791 the persist phase, the server determines that it cannot guarantee 792 that it can bring the client's copy of the data to eventual 793 convergence, it SHOULD immediately terminate the LCUP search request 794 and return a SearchResultDone message with a resultCode of 795 lcupReloadRequired. This can also happen at the beginning of an 796 incremental synchronization request, if the client presents a cookie 797 that is out of date or otherwise unable to be processed. The client 798 should then issue an initial synchronization request. 800 This can happen, for example, if the data on the server is reloaded, 801 or if there has been some change to the meta-data that makes it 802 impossible for the server to determine if a particular entry should 803 or should not be part of the search result set, or if the meta-data 804 change makes it too resource intensive for the server to calculate 805 the proper result set. 807 The server can also return lcupReloadRequired if it determines that 808 it would be more efficient for the client to perform a reload, for 809 example, if too many entries have changed and a simple reload would 810 be much faster. 812 4.4 LCUP Search Termination 814 4.4.1 Server Initiated Termination 816 When the server has successfully finished processing the client's 817 request, it attaches a Sync Done control to the SearchResultDone 818 message and sends it to the client. However, if the SearchResultDone 819 message contains a resultCode that is not success or canceled, the 820 Sync Done control MAY be omitted. Although the LCUP cookie is 821 OPTIONAL in the Sync Done control value, it MUST be set if the 822 SearchResultDone resultCode is success or canceled. The server 823 SHOULD also set the cookie if the resultCode is 824 lcupResourcesExhausted, timeLimitExceeded, sizeLimitExceeded, or 825 adminLimitExceeded. This allows the client to more easily resync 826 later. If some error occurred, either an LDAP search error (e.g. 828 insufficientAccessRights) or an LCUP error (e.g. 829 lcupUnsupportedScheme), the cookie MAY be omitted. If the cookie is 830 set, the scheme MUST be set also if the cookie format has changed, 831 otherwise, it MAY be omitted. 833 If server resources become tight, the server can terminate one or 834 more search operations by sending a SearchResultDone message to the 835 client(s) with a resultCode of lcupResourcesExhausted. The server 836 SHOULD attach a Sync Done control with the cookie set. A server side 837 policy is used to decide which searches to terminate. This can also 838 be used as a security mechanism to disconnect clients that are 839 suspected of malicious actions, but if the server can infer that the 840 client is malicious, the server SHOULD return lcupSecurityViolation 841 instead. 843 4.4.2 Client Initiated Termination 845 If the client needs to terminate the synchronization process and it 846 wishes to obtain the cookie that represents the current state of its 847 data, it issues an LDAP Cancel operation [CANCEL]. The server 848 responds immediately with a LDAP Cancel response [CANCEL]. The 849 server MAY send any pending SearchResultEntry or 850 SearchResultReference PDUs if the server cannot easily abort or 851 remove those search results from its outgoing queue. The server 852 SHOULD send as few of these remaining messages as possible. Finally, 853 the server sends the message SearchResultDone with the Sync Done 854 control attached. If the search was successful up to that point, the 855 resultCode field of the SearchResultDone message MUST be canceled 856 [CANCEL], and the cookie MUST be set in the Sync Done control. If 857 there is an error condition, the server MAY return as described in 858 section 4.4.1 above, or MAY return as described in [CANCEL]. 860 If the client is not interested in the state information, it can 861 simply abandon the search operation or disconnect from the server. 863 4.5 Size and Time Limits 865 The server SHALL support size and time limits as specified in 866 [RFC2251, Section 5]. The server SHOULD ensure that if the operation 867 is terminated due to these conditions, the cookie is sent back to the 868 client. 870 4.6 Operations on the Same Connection 872 It is permissible for the client to issue other LDAP operations on 873 the connection used by the protocol. Since each LDAP request/response 874 carries a message id there will be no ambiguity about which PDU 875 belongs to which operation. By sharing the connection among multiple 876 operations, the server will be able to conserve its resources. 878 4.7 Interactions with Other Controls 880 LCUP defines neither restrictions nor guarantees about the ability to 881 use the controls defined in this document in conjunction with other 882 LDAP controls, except for the following: A server MAY ignore non- 883 critical controls supplied with the LCUP control. A server MAY 884 ignore an LCUP defined control if it is non-critical and it is 885 supplied with other critical controls. If a server receives a 886 critical LCUP control with another critical control, and the server 887 does not support both controls at the same time, the server SHOULD 888 return unavailableCriticalExtension. 890 It is up to the server implementation to determine if the server 891 supports controls such as the Sort or VLV or similar controls that 892 change the order of the entries sent to the client. But note that it 893 may be difficult or impossible for a server to perform an incremental 894 synchronization in the presence of such controls, since the cookie 895 will typically be based off a change number, or CSN, or timestamp, or 896 some criteria other than an alphabetical order. 898 4.8 Replication Considerations 900 Use of an LCUP cookie with multiple DSAs in a replicated environment 901 is not defined by LCUP. An implementation of LCUP may support 902 continuation of an LCUP session with another DSA holding a replica of 903 the LCUP context. Clients MAY submit cookies returned by one DSA to a 904 different DSA; it is up to the server to determine if a cookie is one 905 they recognize or not and to return an appropriate result code if 906 not. 908 5. Client Side Considerations 910 5.1 Using Cookies with Different Search Criteria 912 The cookie received from the server after a synchronization session 913 SHOULD only be used with the same search specification as the search 914 that generated the cookie. Some servers MAY allow the cookie to be 915 used with a more restrictive search specification than the search 916 that generated the cookie. If the server does not support the 917 cookie, it MUST return lcupInvalidCookie. This is because the client 918 can end up with an incomplete data store otherwise. A more 919 restrictive search specification is one that would generate a subset 920 of the data produced by the original search specification. 922 5.2 Renaming the Base Object 924 Because an LCUP client specifies the area of the tree with which it 925 wishes to synchronize through the standard LDAP search specification, 926 the client can be returned noSuchObject error if the root of the 927 synchronization area was renamed between the synchronization sessions 928 or during a synchronization session. If this condition occurs, the 929 client can attempt to locate the root by using the root's UUID saved 930 in client's local data store. It then can repeat the synchronization 931 request using the new search base. In general, a client can detect 932 that an entry was renamed and apply the changes received to the right 933 entry by using the UUID rather than DN based addressing. 935 5.3 Use of Persistent Searches With Respect to Resources 937 Each active persistent operation requires that an open TCP connection 938 be maintained between an LDAP client and an LDAP server that might 939 not otherwise be kept open. Therefore, client implementors are 940 encouraged to avoid using persistent operations for non-essential 941 tasks and to close idle LDAP connections as soon as practical. The 942 server may close connections if server resources become tight. 944 5.4 Continuation References to Other LCUP Contexts 946 The client MAY receive a continuation reference 947 (SearchResultReference [RFC2251 SECTION 4.5.3]) if the search request 948 spans multiple parts of the DIT, some of which may require a 949 different LCUP cookie, some of which may not even be managed by LCUP. 950 The client SHOULD maintain a cache of the LDAP URLs returned in the 951 continuation references and the cookies associated with them. The 952 client is responsible for performing another LCUP search to follow 953 the references, and SHOULD use the cookie corresponding to the LDAP 954 URL for that reference (if it has a cookie). 956 5.5 Referral Handling 958 The client may receive a referral (Referral [RFC2251 SECTION 4.1.11]) 959 when the search base is a subordinate reference, and this will end 960 the operation. 962 5.6 Multiple Copies of Same Entry During Sync Phase 964 The server MAY send the same entry multiple times during a sync phase 965 if the entry changes during the sync phase. The client SHOULD use 966 the last sent copy of the entry as the current one. 968 5.7 Handling Server Out of Resources Condition 970 If the client receives an lcupResourcesExhausted or 971 lcupSecurityViolation resultCode, the client SHOULD wait at least 5 972 seconds before attempting another operation. It is RECOMMENDED that 973 the client use an exponential backoff strategy, but different clients 974 may want to use different backoff strategies. 976 6. Server Implementation Considerations 978 6.1 Server Support for UUIDs 980 Servers MUST support UUIDs. UUIDs are required in the Sync Update 981 control. Additionally, server implementers SHOULD make the UUID 982 values for the entries available as an attribute of the entry, and 983 provide indexing or other mechanisms to allow clients to search for 984 an entry using the UUID attribute in the search filter. The 985 syncUpdate control provides a field UUIDAttribute to allow the server 986 to let the client know the name or OID of the attribute to use to 987 search for an entry by UUID. 989 6.2 Example of Using an RUV as the Cookie Value 991 By design, the protocol supports multiple cookie schemes. This is to 992 allow different implementations the flexibility of storing any 993 information applicable to their environment. A reasonable 994 implementation for an LDUP compliant server would be to use the 995 Replica Update Vector (RUV). For each master, RUV contains the 996 largest CSN seen from this master. In addition, RUV implemented by 997 some directory servers (not yet in LDUP) contains replica generation 998 - an opaque string that identifies the replica's data store. The 999 replica generation value changes whenever the replica's data is 1000 reloaded. Replica generation is intended to signal the 1001 replication/synchronization peers that the replica's data was 1002 reloaded and that all other replicas need to be reinitialized. RUV 1003 satisfies the three most important properties of the cookie: (1) it 1004 uniquely identifies the state of client's data, (2) it can be used to 1005 synchronize with multiple servers, and (3) it can be used to detect 1006 that the server's data was reloaded. If RUV is used as the cookie, 1007 entries last modified by a particular master must be sent to the 1008 client in the order of their last modified CSN. This ordering 1009 guarantees that the RUV can be updated after each entry is sent. 1011 6.3 Cookie Support Issues 1013 6.3.1 Support for Multiple Cookie Schemes 1015 A server may support one or more LCUP cookie schemes. It is expected 1016 that schemes will be published along with their OIDs as RFCs. The 1017 server's DIT may be partitioned into different sections which may 1018 have different cookies associated with them. For example, some 1019 servers may use some sort of replication mechanism to support LCUP. 1020 If so, the DIT may be partitioned into multiple replicas. A client 1021 may send an LCUP search request that spans multiple replicas. Some 1022 parts of the DIT spanned by the search request scope may support LCUP 1023 and some may not. The server MUST send a SearchResultReference 1025 [RFC2251, SECTION 4.5.3] when the LCUP Context for a returned entry 1026 changes. The server SHOULD send all references to other LCUP 1027 Contexts in the search scope first, in order to allow the clients to 1028 process these searches in parallel. The LDAP URL(s) returned MUST 1029 contain the DN(s) of the base of another section of the DIT (however 1030 the server implementation has partitioned the DIT). The client will 1031 then issue another LCUP search using the LDAP URL returned. Each 1032 section of the DIT MAY require a different cookie value, so the 1033 client SHOULD maintain a cache, mapping the different LDAP URL values 1034 to different cookies. If the cookie changes, the scheme may change 1035 as well, but the cookie scheme MUST be the same within a given LCUP 1036 Context. 1038 6.3.2 Information Contained in the Cookie 1040 The cookie must contain enough information to allow the server to 1041 determine whether the cookie can be safely used with the search 1042 specification it is attached to. As discussed earlier in the 1043 document, the cookie SHOULD only be used with the search 1044 specification that is equal to the one for which the cookie was 1045 generated, but some servers MAY support using a cookie with a search 1046 specification that is more restrictive than the one used to generate 1047 the cookie. 1049 6.4 Persist Phase Response Time 1051 The specification makes no guarantees about how soon a server should 1052 send notification of a changed entry to the client during the persist 1053 phase. This is intentional as any specific maximum delay would be 1054 impossible to meet in a distributed directory service implementation. 1055 Server implementers are encouraged to minimize the delay before 1056 sending notifications to ensure that clients' needs for timeliness of 1057 change notification are met. 1059 6.5 Scaling Considerations 1061 Implementers of servers that support the mechanism described in this 1062 document should ensure that their implementation scales well as the 1063 number of active persistent operations and the number of changes made 1064 in the directory increases. Server implementers are also encouraged 1065 to support a large number of client connections if they need to 1066 support large numbers of persistent operations. 1068 6.6 Alias Dereferencing 1070 LCUP design does not consider issues associated with alias 1071 dereferencing in search. Clients MUST specify derefAliases as either 1072 neverDerefAliases or derefFindingBaseObj. Servers are to return 1073 protocolError if the client specifies either derefInSearching or 1074 derefAlways. 1076 7. Synchronizing Heterogeneous Data Stores 1078 Clients, like a meta directory join engine, synchronizing multiple 1079 writable data stores, will only work correctly if each piece of 1080 information comes from a single authoritative data source. In a 1081 replicated environment, an LCUP Context should employ the same 1082 conflict resolution scheme across all its replicas. This is because 1083 different systems have different notions of time and different update 1084 resolution procedures. As a result, a change applied on one system 1085 can be discarded by the other, thus preventing the data stores from 1086 converging. 1088 IANA Considerations 1090 This document lists several values that are to be assigned by IANA. 1091 The following LDAP result codes are to be assigned by IANA as 1092 described in section 3.6 of [RFC3383]: 1094 lcupResourcesExhausted 1095 lcupSecurityViolation 1096 lcupInvalidData 1097 lcupUnsupportedScheme 1098 lcupReloadRequired 1100 The three controls defined in this document are to be registed as 1101 LDAP Protocol Mechanisms as described in section 3.2 of [RFC3383]. 1102 One OID, IANA-ASSIGNED-OID, is to be assigned by IANA as described in 1103 section 3.1 of [RFC3383]. The OIDs for the controls defined in this 1104 document are derived as follows from the one assigned by IANA: 1106 Sync Request Control IANA-ASSIGNED-OID.1 1107 Sync Update Control IANA-ASSIGNED-OID.2 1108 Sync Done Control IANA-ASSIGNED-OID.3 1110 Security Considerations 1112 In some situations, it may be important to prevent general exposure 1113 of information about changes that occur in an LDAP server. 1114 Therefore, servers that implement the mechanism described in this 1115 document SHOULD provide a means to enforce access control on the 1116 entries returned and MAY also provide specific access control 1117 mechanisms to control the use of the controls and extended operations 1118 defined in this document. 1120 As with normal LDAP search requests, a malicious client can initiate 1121 a large number of persistent search requests in an attempt to consume 1122 all available server resources and deny service to legitimate 1123 clients. The protocol provides the means to stop malicious clients 1124 by disconnecting them from the server. The servers that implement the 1125 mechanism SHOULD provide the means to detect the malicious clients. 1126 In addition, the servers SHOULD provide the means to limit the number 1127 of resources that can be consumed by a single client. 1129 Normative References 1131 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 1132 3", BCP 9, RFC 2026, October 1996. 1134 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate 1135 Requirement Levels", BCP 14 (also RFC 2119), March 1997. 1137 [RFC2251] M. Wahl, T. Howes, S. Kille, "Lightweight Directory 1138 Access Protocol (v3)", RFC 2251, December 1997. 1140 [RFC2252] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight 1141 Directory Access Protocol (v3): Attribute Syntax 1142 Definitions", RFC 2252, December 1997. 1144 [X.680] ITU-T, "Abstract Syntax Notation One (ASN.1) - 1145 Specification of Basic Notation", X.680, 1994. 1147 [X.690] ITU-T, "Specification of ASN.1 encoding rules: Basic, 1148 Canonical, and Distinguished Encoding Rules", X.690, 1149 1994. 1151 [CANCEL] K. Zeilenga, "LDAP Cancel Extended Operation", draft- 1152 zeilenga-ldap-cancel-xx.txt, a work in progress. 1154 [UUID] International Organization for Standardization (ISO), 1155 "Information technology - Open Systems Interconnection - 1156 Remote Procedure Call", ISO/IEC 11578:1996. 1158 [RFC3383] K. Zeilenga, "IANA Considerations for LDAP", BCP 64 also 1159 RFC 3383), September 2002. 1161 Informative References 1163 [RFC3384] E. Stokes, et. al., "LDAPv3 Replication Requirements", 1164 RFC3384, October 2002. 1166 [SUBENTRY] K. Zeilenga, S. Legg, "Subentries in LDAP", draft- 1167 zeilenga-ldap-subentry-xx.txt, a work in progress. 1169 [COLLECTIVE] K. Zeilenga, "Collective Attributes in LDAP", draft- 1170 zeilenga-ldap-collective-xx.txt, a work in progress. 1172 Acknowledgments 1174 The LCUP protocol is based in part on the Persistent Search Change 1175 Notification Mechanism defined by Mark Smith, Gordon Good, Tim Howes, 1176 and Rob Weltman, the LDAPv3 Triggered Search Control defined by Mark 1177 Wahl, and the LDAP Control for Directory Synchronization defined by 1178 Michael Armijo. The members of the IETF LDUP working group made 1179 significant contributions to this document. 1181 Author's Addresses 1183 Rich Megginson 1184 Netscape Communications Corp., an America Online company. 1185 360 W. Caribbean Drive 1186 Sunnyvale, CA 94089 1187 USA 1188 Phone: +1 505 797-7762 1189 Email: richm@netscape.com 1191 Olga Natkovich 1192 Yahoo, Inc. 1193 701 First Ave. 1194 Sunnyvale, CA 94089 1195 Phone: +1 408 349-6153 1196 Email: olgan@yahoo-inc.com 1198 Mark Smith 1199 Netscape Communications Corp., an America Online company. 1200 360 W. Caribbean Drive 1201 Sunnyvale, CA 94089 1202 USA 1203 Phone: +1 650 937-3477 1204 Email: mcs@netscape.com 1206 Jeff Parham 1207 Microsoft Corporation 1208 One Microsoft Way 1209 Redmond, WA 98052-6399 1210 Phone: +1 425 882-8080 1211 Email: jeffparh@microsoft.com 1213 Full Copyright Statement 1215 Copyright (C) The Internet Society (2003). All Rights Reserved. 1217 This document and translations of it may be copied and furnished to 1218 others, and derivative works that comment on or otherwise explain it 1219 or assist in its implementation may be prepared, copied, published 1220 and distributed, in whole or in part, without restriction of any 1221 kind, provided that the above copyright notice and this paragraph are 1222 included on all such copies and derivative works. However, this 1223 document itself may not be modified in any way, such as by removing 1224 the copyright notice or references to the Internet Society or other 1225 Internet organizations, except as needed for the purpose of 1226 developing Internet standards in which case the procedures for 1227 copyrights defined in the Internet Standards process must be 1228 followed, or as required to translate it into languages other than 1229 English. 1231 The limited permissions granted above are perpetual and will not be 1232 revoked by the Internet Society or its successors or assigns. 1234 This document and the information contained herein is provided on an 1235 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1236 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1237 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1238 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1239 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1241 Appendix - Features Left Out of LCUP 1243 There are several features present in other protocols or considered 1244 useful by clients that are currently not included in the protocol 1245 primarily because they are difficult to implement on the server. 1246 These features are briefly discussed in this section. 1248 Triggered Search Change Type 1250 This feature is present in the Triggered Search specification. A flag 1251 is attached to each entry returned to the client indicating the 1252 reason why this entry is returned. The possible reasons from the 1253 draft are 1254 - notChange: the entry existed in the directory and matched the 1255 search at the time the operation is being performed, 1256 - enteredSet: the entry entered the result, 1257 - leftSet: the entry left the result, 1258 - modified: the entry was part of the result set, was modified or 1259 renamed, and still is in the result set. 1261 The leftSet feature is particularly useful because it indicates to 1262 the client that an entry is no longer within the client's search 1263 specification and the client can remove the associated data from its 1264 data store. Ironically, this feature is the hardest to implement on 1265 the server because the server does not keep track of the client's 1266 state and has no easy way of telling which entries moved out of scope 1267 between synchronization sessions with the client. A compromise could 1268 be reached by only providing this feature for the operations that 1269 occur while the client is connected to the server. This is easier to 1270 accomplish because the decision about the change type can be made 1271 based only on the change without need for any historical information. 1272 This, however, would add complexity to the protocol. 1274 Persistent Search Change Type 1276 This feature is present in the Persistent Search specification. 1277 Persistent search has the notion of changeTypes. The client specifies 1278 which type of updates will cause entries to be returned, and 1279 optionally whether the server tags each returned entry with the type 1280 of change that caused that entry to be returned. 1282 For LCUP, the intention is full synchronization, not partial. Each 1283 entry returned by an LCUP search will have some change associated 1284 with it that may concern the client. The client may have to have a 1285 local index of entries by DN or UUID to determine if the entry has 1286 been added or just modified. It is easy for clients to determine if 1287 the entry has been deleted because the entryLeftSet value of the Sync 1288 Update control will be TRUE. 1290 Sending Changes 1292 Some earlier synchronization protocols sent the client(s) only the 1293 modified attributes of the entry rather than the entire entry. While 1294 this approach can significantly reduce the amount of data returned to 1295 the client, it has several disadvantages. First, unless a separate 1296 mechanism (like the change type described above) is used to notify 1297 the client about entries moving into the search scope, sending only 1298 the changes can result in the client having an incomplete version of 1299 the data. Let's consider an example. An attribute of an entry is 1300 modified. As a result of the change, the entry enters the scope of 1301 the client's search. If only the changes are sent, the client would 1302 never see the initial data of the entry. Second, this feature is hard 1303 to implement since the server might not contain sufficient 1304 information to construct the changes based solely on the server's 1305 state and the client's cookie. On the other hand, this feature can be 1306 easily implemented by the client assuming that the client has the 1307 previous version of the data and can perform value by value 1308 comparisons. 1310 Data Size Limits 1312 Some earlier synchronization protocols allowed clients to control the 1313 amount of data sent to them in the search response. This feature was 1314 intended to allow clients with limited resources to process 1315 synchronization data in batches. However, an LDAP search operation 1316 already provides the means for the client to specify the size limit 1317 by setting the sizeLimit field in the SearchRequest to the maximum 1318 number of entries the client is willing to receive. While the 1319 granularity is not the same, the assumption is that regular LDAP 1320 clients that can deal with the limitations of the LDAP protocol will 1321 implement LCUP. 1323 Data Ordering 1325 Some earlier synchronization protocols allowed a client to specify 1326 that parent entries should be sent before the children for add 1327 operations and children entries sent before their parents during 1328 delete operations. This ordering helps clients to maintain a 1329 hierarchical view of the data in their data store. While possibly 1330 useful, this feature is relatively hard to implement and is expensive 1331 to perform.