idnits 2.17.1 draft-ietf-ldup-lcup-00.txt: ** The Abstract section seems to be numbered -(112): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(168): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(173): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(288): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(961): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(964): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document is more than 15 pages and seems to lack a Table of Contents. == There are 25 instances of lines with non-ascii characters in the document. == The page length should not exceed 58 lines per page, but there was 17 longer pages, the longest (page 2) being 59 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 7 instances of too long lines in the document, the longest one being 1 character in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: In response to the client's synchronization request, the server returns one or more SearchResultEntry PDU that fits the client�s specification. Each SearchResultEntry PDU also contains an entryUpdateControl which describes the LCUP state of the returned entry. To represent a deleted entry, the server attaches an entryUpdate control to the corresponding SearchResultEntry. The SearchResultEntry corresponding to a deleted entry MUST contain a valid DN and a valid Unique Identifier but, to reduce the amount of data sent to the client, it SHOULD not contain any other attributes. Distinguished names can change, so are therefore unreliable as identifiers. A Unique Identifier MUST therefore be assigned to each entry as it is created. The Unique Identifier allows the client to uniquely identify entries even in the presence of modrdn operations. The Unique Identifier is carried in the entryUUID attribute. -- 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 (May 2001) is 8380 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: '1' on line 302 == Missing Reference: 'LDAPv3' is mentioned on line 298, but not defined == Missing Reference: 'APPLICATION 23' is mentioned on line 300, but not defined -- Looks like a reference, but probably isn't: '0' on line 301 == Unused Reference: 'RFC2251' is defined on line 823, 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) Summary: 10 errors (**), 0 flaws (~~), 6 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet Draft R. Megginson, Editor 2 Document: M. Smith 3 Category: Proposed Standard Netscape Communications 4 Corp. 5 O. Natkovich 6 eTime Capital 7 J. Parham 8 Microsoft Corporation 9 May 2001 11 LDAP Client Update Protocol 13 Status of this Memo 15 This document is an Internet-Draft and is in full conformance with 16 all provisions of Section 10 of RFC2026 [1]. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six 24 months and may be updated, replaced, or obsoleted by other documents 25 at any time. It is inappropriate to use Internet- Drafts as 26 reference material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet- 30 Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 1. Abstract 35 This document defines the LDAP Client Update Protocol (LCUP). The 36 protocol is intended to allow an LDAP client to synchronize with the 37 content of a directory information tree (DIT) stored by an LDAP 38 server and to be notified about the changes to that content. 40 2. Conventions used in this document 42 In the protocol flow definition, the notation C->S and S->C 43 specifies the direction of the data flow from the client to the 44 server and from the server to the client respectively. 46 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 47 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 48 this document are to be interpreted as described in RFC-2119 49 [KEYWORDS]. 51 3. Overview 52 The LCUP protocol is intended to allow LDAP clients to synchronize 53 with the content stored by LDAP servers. 55 The problem areas addressed by the protocol include: 57 - mobile clients that maintain a local read-only copy of the 58 directory data. While off-line, the client uses the local copy of 59 the data. When the client connects to the network, it 60 synchronizes with the current directory content and can be 61 optionally notified about the changes that occur while it is on- 62 line. For example, a mail client can maintain a local copy of the 63 corporate address book that it synchronizes with the master copy 64 whenever the client gets connected to the corporate network. 66 - applications intending to synchronize heterogeneous data stores. 67 A meta directory application, for instance, would periodically 68 retrieve a list of modified entries from the directory, construct 69 the changes and apply them to a foreign data store. 71 - clients that need to take certain actions when a directory entry 72 is modified. For instance, an electronic mail repository may want 73 to perform a "create mailbox" task when a new person entry is 74 added to an LDAP directory and a "delete mailbox" task when a 75 person entry is removed. 77 The problem areas not being considered: 79 - directory server to directory server synchronization. The 80 replication protocol that is being defined by the LDUP IETF 81 working group should be used for this purpose. 83 Several features of the protocol distinguish it from LDUP 84 replication. First, the server does not maintain any state 85 information on behalf of its clients. The clients are responsible 86 for storing the information about how up to date they are with 87 respect to the server's content. Second, no predefined agreements 88 exist between the clients and the servers. The client decides when 89 and from where to retrieve the changes. Finally, the server never 90 pushes the data to the client; the client always initiates the 91 update session during which it pulls the changes from the server. 93 The set of clients that are allowed to synchronize with an LDAP 94 server is determined by the server defined policy. 96 There are currently several protocols in use for LDAP client server 97 synchronization. While each protocol addresses the needs of a 98 particular group of clients (e.g., on-line clients or off-line 99 clients) none satisfies the requirements of all clients in the 100 target group. For instance, a mobile client that was off-line and 101 wants to become up to date with the server and stay up to date while 102 connected can't be easily supported by any of the existing 103 protocols. 105 Megginson, et. al. Proposed Standard - Expires: November 2001 2 106 A server can define a naming context or some part thereof to 107 participate in LCUP. This document will refer to this as an LCUP 108 Context. For example, LDUP defines a replica, a part of the DIT 109 which may participate in replication. The LCUP context may be 110 coincident with the replicated area, depending on the server�s 111 implementation. It is assumed that most server implementations of 112 LCUP will make use of the server�s underlying replication mechanism, 113 but this does not have to be LDUP compliant. 115 4. Protocol Specification 117 This section describes the protocol elements and the protocol flow. 119 4.1 Unique Identifiers 121 Distinguished names can change, so are therefore unreliable 122 as identifiers. A Unique Identifier must therefore be 123 assigned to each entry as it is created. This identifier 124 will be stored as an operational attribute of the entry, 125 named `entryUUID'. The entryUUID attribute is single valued. 126 A consistent algorithm for generating such unique 127 identifiers may be standardized at some point in the future. 128 The definition of the entryUUID attribute type, written using the 129 BNF form of AttributeDescription described in RFC 2252 [RFC2252] is: 131 ( OID-To-Be-Specified 132 NAME 'entryUUID' 133 DESC 'unique entry identifier' 134 EQUALITY caseIgnoreMatch 135 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 136 SINGLE-VALUE 137 NO-USER-MODIFICATION 138 USAGE directoryOperation ) 140 4.2 Client Update Control Value 142 A client initiates a synchronization session with a server by 143 attaching a clientUpdate control to a search operation. The search 144 specification determines the part of the directory information tree 145 (DIT) the client wishes to synchronize with, the set of attributes 146 it is interested in and the amount of data the client is willing to 147 receive. The clientUpdate control contains the client's 148 synchronization specification. The controlType field for the 149 clientUpdate control is ClientUpdateControlOID (to be assigned). 150 The controlValue is an OCTET STRING, whose contents are the bytes of 151 the BER encoding of the following: 153 ClientUpdateControlValue ::= SEQUENCE { 154 updateType ENUMERATED { 155 synchronizeOnly (0), 156 synchronizeAndPersist (1), 157 persistOnly (2) }, 158 cookie OCTET STRING OPTIONAL 159 } 161 Megginson, et. al. Proposed Standard - Expires: November 2001 3 162 updateType � specifies the type of update requested by the client 164 synchronizeOnly � the server sends all the data needed to 165 synchronize the client with the server, then closes the 166 connection 168 synchronizeAndPersist � the server sends all the data needed to 169 synchronize the client with the server, then leaves open the 170 connection, sending to the client any new added, modified, or 171 deleted entries which satisfy the search criteria. 173 persistOnly � the server does not synchronize the data with the 174 client but leaves open the connection and sends over any new 175 added, modified, or deleted entries which satisfy the search 176 criteria. 178 cookie - an opaque cookie that represents the current state of the 179 client's data. If the cookie is invalid, the server MUST return 180 immediately with a SearchResultDone message with the 181 clientUpdateDone control attached with the reason set to the value 182 of lcupInvalidCookie (see below). Also, the LDAP result code MUST 183 be unwillingToPerform. 185 4.3 Entry Update Control Value 187 In response to the client's synchronization request, the server 188 returns one or more SearchResultEntry PDU that fits the client�s 189 specification. Each SearchResultEntry PDU also contains an 190 entryUpdateControl which describes the LCUP state of the returned 191 entry. To represent a deleted entry, the server attaches an 192 entryUpdate control to the corresponding SearchResultEntry. The 193 SearchResultEntry corresponding to a deleted entry MUST contain a 194 valid DN and a valid Unique Identifier but, to reduce the amount of 195 data sent to the client, it SHOULD not contain any other attributes. 196 Distinguished names can change, so are therefore unreliable as 197 identifiers. A Unique Identifier MUST therefore be assigned to each 198 entry as it is created. The Unique Identifier allows the client to 199 uniquely identify entries even in the presence of modrdn operations. 200 The Unique Identifier is carried in the entryUUID attribute. 202 Furthermore, the server may elect to periodically return to the 203 client the cookie that represents the state of the client's data. 204 This information is useful in case the client crashes or gets 205 disconnected. The cookie is also provided in the entryUpdate 206 control. The controlType field for the entryUpdate control is 207 EntryUpdateControlOID (to be assigned). The controlValue is an 208 OCTET STRING, whose contents are the bytes of the BER encoding of 209 the following: 211 EntryUpdateControlValue ::= SEQUENCE { 212 stateUpdate BOOLEAN, 213 entryDeleted BOOLEAN, 214 cookie OCTET STRING OPTIONAL 216 Megginson, et. al. Proposed Standard - Expires: November 2001 4 217 } 219 stateUpdate - if set to TRUE, indicates that the entry to which the 220 control is attached contains no changes and it is sent only to 221 communicate to the client the new cookie. In this case, the 222 entryDeleted field MUST be ignored and the cookie field MUST 223 contain the updated cookie. This feature allows updating the 224 client's cookie when there are no changes that effect the 225 client's data store. Note that the control MUST be attached to a 226 valid SearchResultEntry, i.e. the entry should contain a valid 227 dn. The server MAY send the entry at the root of the client's 228 tree. 230 entryDeleted - if set to TRUE, indicates that the entry to which 231 the control is attached was deleted. The server MAY also set 232 this to TRUE if the entry has left the client�s search result 233 set. As far as the client is concerned, a deleted entry is no 234 different than an entry which has left the result set. 236 cookie - an opaque cookie that represents the current state of the 237 client's data. 239 4.4 Client Update Done Control Value 241 When the server has finished processing the client's request, it 242 attaches a clientUpdateDone control to the SearchResultDone message 243 and sends it to the client. The controlType field for the 244 clientUpdateDone control is ClientUpdateDoneControlOID (to be 245 assigned). The controlValue is an OCTET STRING, whose contents are 246 the bytes of the BER encoding of the following: 248 ClientUpdateDoneControlValue ::= SEQUENCE { 249 reason INTEGER, 250 reasonText LDAPString, 251 cookie OCTET STRING 252 } 254 reason - reason for terminating the operation. Currently supported 255 values are 257 lcupSuccess (0) the operation was successfully 258 processed 259 lcupResourcesExhausted (1) the server is running out of resource 260 lcupSecurityViolation (2) the client is suspected of malicious 261 actions 262 lcupInvalidCookie (3) invalid cookie was supplied by the 263 client 264 lcupClientDisconnect (4) client requested search termination 265 lcupReloadRequired (5) indicates that client data needs to 266 be reinitialized. This reason is 267 returned if the server does not 268 contain sufficient information to 269 synchronize the client or that the 271 Megginson, et. al. Proposed Standard - Expires: November 2001 5 272 server's data was reloaded since the 273 last synchronization session 275 reasonText - The reasonText field of this construct may, at the 276 server's option, be used to return a string containing a textual, 277 human-readable (terminal control and page formatting characters 278 should be avoided) error diagnostic. As this error diagnostic is 279 not standardized, implementations MUST NOT rely on the values 280 returned. If the server chooses not to return a textual 281 diagnostic, the reasonText field of the 282 ClientUpdateDoneControlValue MUST contain a zero length string. 283 The character set for reasonText SHOULD be US-ASCII. 285 cookie - an opaque cookie that represents the current state of the 286 client's data. Although this value is OPTIONAL in other control 287 values, it MUST be set in the ClientUpdateDoneControlValue. This 288 provides a good �checksum� of what the server thinks the state of 289 the client is. 291 4.5 Stop Client Update Request and Response 293 The Stop Client Update operation is an LDAPv3 Extended Operation 294 [RFC2251, Section 4.12] and is identified by the OBJECT IDENTIFIER 295 stopClientUpdateOID (to be assigned). This section details the 296 syntax of the protocol. 298 An LDAPv3 Extended Request is defined in [LDAPv3] as follows: 300 ExtendedRequest ::= [APPLICATION 23] SEQUENCE { 301 requestName [0] LDAPOID, 302 requestValue [1] OCTET STRING OPTIONAL 303 } 305 If the client needs to terminate the synchronization process and it 306 wishes to obtain the cookie that represents the current state of its 307 data, it issues a stopClientUpdateRequest extended operation. The 308 operation carries the following data. The extended operation 309 requestValue is an OCTET STRING, whose contents are the bytes of the 310 BER encoding of the following: 312 StopClientUpdateRequestValue ::= INTEGER 314 StopClientUpdateRequestValue - the message ID of the search that 315 included the original clientUpdate control 317 The server responds immediately with a stopClientUpdateResponse 318 extended operation that carries no data. The server MAY send any 319 pending SearchResultEntry PDUs if the server cannot easily abort or 320 remove those search results from its outgoing queue. The server 321 SHOULD send as few of these remaining SearchResultEntry PDUs as 322 possible. Finally, the server sends the message SearchResultDone 323 with the clientUpdateDone control attached. The value of the reason 324 in the clientUpdateDone control value MUST be either an error code 325 (some value other than lcupSuccess) or lcupClientDisconnect. The 327 Megginson, et. al. Proposed Standard - Expires: November 2001 6 328 stopClientUpdateResponse is sent only to satisfy LDAP requirement 329 that every server must issue an extended response for each extended 330 request it receives. 332 If the client is not interested in the state information, it can 333 simply abandon the search operation or disconnect from the server. 335 If server resources become tight, the server can terminate one or 336 more search operations by sending a SearchResultDone message to the 337 client(s). Unless the client sets the updateType field to 338 persistOnly, the server attaches a clientUpdateDone control that 339 contains the cookie that corresponds to the current state of the 340 client's data and the value of the reason field is set to 341 lcupResourcesExhausted. A server set policy is used to decide which 342 searches to terminate. This can also be used as a security mechanism 343 to disconnect clients that are suspected of malicious actions, but 344 if the server can infer that the client is malicious, the server 345 should return lcupSecurityViolation in the reason field of the 346 response. 348 The stopClientUpdate extended operation indicates that the initiator 349 wishes to terminate the current update operation. 351 The requestName portion of the stopClientUpdate must be the 352 OID stopClientUpdateOID . The requestValue is the 353 message ID corresponding to the client�s search request. If the 354 message ID is not valid, the server MUST send back to the client an 355 LDAP error code of unwillingToPerform. 357 4.6 Protocol Flow 359 The client server interaction can proceed in three different ways 360 depending on the client's requirements. Protocol flows beginning 361 with an asterisk (*) are optional or conditional. 363 If the client's intent is not to synchronize data but to trigger 364 actions in response to directory modifications, the protocol 365 proceeds as follows: 367 C->S Sends a search operation with a clientUpdate control attached. 368 The search specification determines the part of the DIT the 369 client wishes to synchronize with and the set of attributes it 370 is interested in. The updateType field of the control value 371 should be set to persistOnly. 372 *S->C If there is an error (invalid search scope, invalid cookie) 373 the server returns the appropriate error codes and terminates 374 the request (SearchResultDone message with clientUpdateDone 375 control) 376 S->C Sends change notification to the client for each change to the 377 data within the client's search specification. Each 378 SearchResultEntry may have an entryUpdate control attached. 379 *S->C If the server starts to run out of resources or the client is 380 suspected of malicious actions, the server SHOULD terminate 381 the search operation by sending to the client a 383 Megginson, et. al. Proposed Standard - Expires: November 2001 7 384 SearchResultDone message with clientUpdateDone control 385 attached. The control contains the reason field set to 386 lcupResourcesExhausted or lcupSecurityViolation depending on 387 the reason for termination. The server MAY provide more 388 details to the client via the reasonText field of the control. 389 *C->S If the client receives lcupResourcesExhausted error from the 390 server, it MUST wait for a while before attempting another 391 synchronization session with the server. It is RECOMMENDED 392 that clients use an exponential backoff strategy. 393 C->S The client terminates the search. The client can do this by 394 abandoning the search operation, disconnecting from the 395 server, or by sending the stopClientUpdate extended operation. 396 *S->C If the server receives the stopClientUpdate extended op, it 397 will immediately send back the stopClientUpdate extended op 398 response 399 *S->C If the client sent the stopClientUpdate extended op, the 400 server MAY send any pending SearchResultEntry PDUs in its 401 outgoing queue 402 *S->C If the client sent the stopClientUpdate extended op, after the 403 server sends the response and any pending SearchResultEntry 404 PDUs, the server sends the SearchResultDone message with the 405 clientUpdateDone control attached. The value of the reason 406 field of the clientUpdateDone control value will be either 407 lcupClientDisconnect or some lcup error code (not 408 lcupSuccess). 409 S->C Stops sending changes to the client and closes the connection. 411 If the client's intent is to synchronize with the server and then 412 disconnect, the protocol proceeds as follows: 414 C->S Sends a search operation with the clientUpdate control 415 attached. The search specification determines the part of the 416 DIT the client wishes to synchronize with, the set of 417 attributes it is interested in and the amount of data the 418 client is willing to receive. If this is the initial 419 synchronization session, the client does not provide a cookie; 420 otherwise, the cookie field of the control is set to the 421 cookie received from the server at the end of the last 422 synchronization session. (Note that the client can synchronize 423 with different servers during different synchronization 424 sessions.) The updateType field of the control value is set to 425 synchronizeOnly. 426 *S->C If there is an error (invalid search scope, invalid cookie) 427 the server returns the appropriate error codes and terminates 428 the request (SearchResultDone message with clientUpdateDone 429 control) 430 *S->C If no cookie is specified in the clientUpdate control, the 431 server sends all data that matches the client's search 432 specification followed by the SearchResultDone message with a 433 clientUpdateDone control attached. The control contains the 434 cookie that corresponds to the current state of the client's 435 data and the reason flag set to lcupSuccess. 436 *S->C If an invalid cookie is specified, the server sends the 437 SearchResultDone message with clientUpdateDone control 439 Megginson, et. al. Proposed Standard - Expires: November 2001 8 440 attached. The reason field of the control is set to 441 lcupInvalidCookie and the reasonText field MAY contain 442 explanation of the error. 443 *S->C If a valid cookie is specified and the data that matches the 444 search specification has been reloaded or the server does not 445 contain enough state information to synchronize the client, 446 the server sends a SearchResultDone message with 447 clientUpdateDone control attached. The reason field of the 448 control is set to lcupReloadRequired and the reasonText field 449 MAY contain explanation of the error. 450 *S->C If the cookie is valid and the client is up to date, the 451 server sends a success response to the client. 452 S->C If the cookie is valid and there is data to be sent, the 453 server sends the modified entries to the client. Each 454 SearchResultEntry contains the attributes requested by the 455 client in the search specification regardless of whether they 456 were modified. An entryUpdate control with the entryDeleted 457 field set to TRUE MUST be attached to every deleted entry. The 458 server may also periodically attach an entryUpdate control to 459 the entries sent to the client to indicate the current state 460 of the client's data. In that case, the cookie field of the 461 control represents the state of the client's data including 462 the entry to which the control is attached. Once all the 463 changes are sent, the server sends a SearchResultDone with the 464 clientUpdateDone control attached. The control contains the 465 cookie that represents the current state of the client's data. 466 The reason field of the control is set to lcupSuccess. 467 The client stores the cookie received from the server until 468 the next synchronization session. 469 *C->S If the reason field of the control is set lcupReloadRequired, 470 the client clears its data store and repeats the 471 synchronization process by sending the search operation with 472 clientUpdate control that contains no cookie. 474 If the client's intent is to be synchronized with the server and 475 stay notified about data modifications, the protocol proceeds as 476 follows: 478 C->S The client behaves exactly as in the previous case except it 479 sets the updateType field in the control value to 480 synchronizeAndPersist. 481 S->C The server behaves exactly as in the previous case except the 482 connection is kept open after the initial set of changes is 483 sent to the client. A SearchResultDone message is not sent to 484 the client; instead, the server keeps sending changes to the 485 client. 486 *S->C If the server starts to run out of resources or the client is 487 suspected of malicious actions, the server SHOULD terminate 488 the search operation by sending to the client a 489 SearchResultDone message with clientUpdateDone control 490 attached. The control contains the reason field set to 491 lcupResourcesExhausted or lcupSecurityViolation depending on 492 the reason for termination. The server MAY provide more 493 details to the client via the reasonText field of the control. 495 Megginson, et. al. Proposed Standard - Expires: November 2001 9 496 *C->S If the client receives lcupResourcesExhausted error from the 497 server, it MUST wait for a while before attempting another 498 synchronization session with the server. We recommend 499 exponential backoff strategy. 500 C->S Sends a stopClientUpdateRequest extended operation to the 501 server to terminate the synchronization session. 502 S->C Responds with a stopClientUpdateResponse extended operation 503 followed by a SearchResultDone with the clientUpdateDone 504 control attached. The control contains the cookie that 505 represents the current state of the client's data. The value 506 of the reason field of the clientUpdateDone control value will 507 be either lcupClientDisconnect or some lcup error code (not 508 lcupSuccess). 510 4.7 Size and Time Limits 512 The search request size or the time limits can only be imposed for 513 non-persistent operations, those that set the updateType field of 514 the ClientUpdateControlValue to synchronizeOnly (for the entire 515 operation) or synchronizeAndPersist (for the initial synchronization 516 phase only). All other operations MUST set both limits to 0. The 517 server SHOULD ignore the limits set for persistent operations. 519 4.8 Changes vs. Operations 521 Since the server sends to the client the modified entries rather 522 than the operations, a MODDN operation performed on a subtree will 523 be seen by the client as a sequence of added or modified entries 524 depending on whether the operation moved the entries into the scope 525 of the client's search specification. 527 4.9 Operations on the Same Connection 529 It is permissible for the client to issue other LDAP operations on 530 the connection used by the protocol. Since each LDAP 531 request/response carries a message id there will be no ambiguity 532 about which PDU belongs to which operation. By sharing the 533 connection among multiple operations, the server will be able to 534 conserve its resources. 536 5. Additional Features 538 There are several features present in other protocols or considered 539 useful by clients that are currently not included in the protocol 540 primarily because they are difficult to implement on the server. 541 These features are briefly discussed in this section. This section 542 is intended to open a discussion on the merits of including and 543 approaches to implementing these features. 545 5.1 Change Type 547 This feature is present in the Triggered Search specification. A 548 flag is attached to each entry returned to the client indicating the 550 Megginson, et. al. Proposed Standard - Expires: November 2001 10 551 reason why this entry is returned. The possible reasons from the 552 draft are 553 "- notChange: the entry existed in the directory and matched the 554 search at the time the operation is being performed, 555 - enteredSet: the entry entered the result, 556 - leftSet: the entry left the result, 557 - modified: the entry was part of the result set, was modified or 558 renamed, and still is in the result set." 560 The leftSet feature is particularly useful because it indicates to 561 the client that an entry is no longer within the client's search 562 specification and the client can remove the associated data from its 563 data store. Ironically, this feature is the hardest to implement on 564 the server because the server does not keep track of the client's 565 state and has no easy way of telling which entries moved out of 566 scope between synchronization sessions with the client. 568 A compromise could be reached by only providing this feature for the 569 operations that occur while the client is connected to the server. 570 This is easier to accomplish because the decision about the change 571 type can be made based only on the change without need for any 572 historical information. This, however, would add complexity to the 573 protocol. 575 5.2 Sending Changes 577 Some earlier synchronization protocols sent the client(s) only the 578 modified attributes of the entry rather than the entire entry. While 579 this approach can significantly reduce the amount of data returned 580 to the client, it has several disadvantages. First, unless a 581 separate mechanism (like the change type described above) is used to 582 notify the client about entries moving into the search scope, 583 sending only the changes can result in the client having an 584 incomplete version of the data. Let's consider an example. An 585 attribute of an entry is modified. As a result of the change, the 586 entry enters the scope of the client's search. If only the changes 587 are sent, the client would never see the initial data of the entry. 588 Second, this feature is hard to implement since the server might not 589 contain sufficient information to construct the changes based solely 590 on the server's state and the client's cookie. On the other hand, 591 this feature can be easily implemented by the client assuming that 592 the client has the previous version of the data and can perform 593 value by value comparisons. 595 5.3 Data Size Limits 597 Some earlier synchronization protocols allowed clients to control 598 the amount of data sent to them in the search response. This feature 599 was intended to allow clients with limited resources to process 600 synchronization data in batches. However, an LDAP search operation 601 already provides the means for the client to specify the size limit 602 by setting the sizeLimit field in the SearchRequest to the maximum 603 number of entries the client is willing to receive. While the 604 granularity is not the same, the assumption is that LCUP protocol 606 Megginson, et. al. Proposed Standard - Expires: November 2001 11 607 will be implemented by regular LDAP clients that can deal with the 608 limitations of the LDAP protocol. 610 5.4 Data Ordering 612 Some earlier synchronization protocols allowed a client to specify 613 that parent entries should be sent before the children for add 614 operations and children entries sent before their parents during 615 delete operations. This ordering helps clients to maintain a 616 hierarchical view of the data in their data store. While possibly 617 useful, this feature is relatively hard to implement and is 618 expensive to perform. 620 Comments from M. Armijo: " Although I appreciate the difficulty in 621 implementing this, I believe we need to at least make it an option. 622 If we do not, we will need to define how clients handle issues where 623 changes are received out of order (stub entries, etc.) At the very 624 least we should define that the server must not return a cookie 625 until all parents involved in a series of operations have been 626 returned (does that make sense or should I reword it?). I am 627 concerned that a client can disconnect and be in what it considers 628 to be a 'valid' state while it's own DIT is no longer valid." 630 6. Client Side Considerations 632 There are several issues that the implementors of a synchronization 633 client need to consider: 635 - The cookie received from the server after a synchronization 636 session can only be used with the same or more restrictive search 637 specification than the search that generated the cookie. The 638 server will reject the search operation with a cookie that does 639 not satisfy this condition. This is because the client can end up 640 with an incomplete data store otherwise. A more restrictive 641 search specification is the one that generates a subset of the 642 data produced by the original search specification. 644 - Because an LCUP client specifies the area of the tree with which 645 it wishes to synchronize through the standard LDAP search 646 specification, the client can be returned noSuchObject error if 647 the root of the synchronization area was renamed between the 648 synchronization sessions. If this condition occurs, the client 649 can attempt to locate the root by using the root's Unique 650 Identifier saved in client's local data store. It then can repeat 651 the synchronization request using the new search base. In 652 general, a client can detect that an entry was renamed and apply 653 the changes received to the right entry by using the Unique 654 Identifier rather then DN based addressing. 656 - Each active persistent operation requires that an open TCP 657 connection be maintained between an LDAP client and an LDAP 658 server that might not otherwise be kept open. Therefore, client 659 implementors are encouraged to avoid using persistent operations 660 for non-essential tasks and to close idle LDAP connections as 662 Megginson, et. al. Proposed Standard - Expires: November 2001 12 663 soon as practical. The server may close connections if server 664 resources become tight. 666 - The client MAY receive a continuation reference 667 (SearchResultReference [RFC2251 SECTION 4.5.3]) if the search 668 request spans multiple parts of the DIT, some of which may 669 require a different LCUP cookie, some of which may not even be 670 managed by LCUP. The client SHOULD maintain a cache of the LDAP 671 URLs returned in the continuation references and the cookies 672 associated with them. The client is responsible for performing 673 another LCUP search to follow the references, and SHOULD use the 674 cookie corresponding to the LDAP URL for that reference (if it 675 has a cookie). 677 - Changes to meta-data in the server may affect the presence of 678 entries in the search set. Servers MAY notify LCUP clients of 679 changes to the search set that result from changes to meta-data 680 such as access control rules. But an LCUP client MUST NOT assume 681 that such notification will occur. Therefore, in the case where 682 a client is maintaining a cache of entries using LCUP, the data 683 held by the client may be a superset or a subset of the entries 684 that would be returned by a new search request. For example, if 685 access control meta information is changed to deny access to 686 particular entries in the search result set, and the access 687 control information is outside of the search scope (e.g., in a 688 parent entry), the client may have entries stored locally which 689 are no longer part of its desired search set. Similarly, if 690 entries are added to the search result set due to changes in 691 meta-data, the client's cache of entries may not include these 692 entries. 694 7. Server Implementation Considerations 696 By design, the protocol does not specify the format of the cookie. 697 This is to allow different implementations the flexibility of 698 storing any information applicable to their environment. A 699 reasonable implementation for an LDUP compliant server would be to 700 use the Replica Update Vector (RUV). For each master, RUV contains 701 the largest CSN seen from this master. In addition, the RUV 702 implemented by some directory servers (not yet in LDUP) contains 703 replica generation - an opaque string that identifies the replica's 704 data store. The replica generation value changes whenever the 705 replica's data is reloaded. Replica generation is intended to signal 706 the replication/synchronization peers that the replica's data was 707 reloaded and that all other replicas need to be reinitialized. RUV 708 satisfies the three most important properties of the cookie: (1) it 709 uniquely identifies the state of client's data, (2) it can be used 710 to synchronize with multiple servers, and (3) it can be used to 711 detect that the server's data was reloaded. 713 In addition, the cookie must contain enough information to allow the 714 server to determine whether the cookie can be safely used with the 715 search specification it is attached to. As discussed earlier in the 716 document, the cookie can only be used with the search specification 718 Megginson, et. al. Proposed Standard - Expires: November 2001 13 719 that is equally or more restrictive than the one for which the 720 cookie was generated. 722 An implementation must make sure that it can correctly update the 723 client's cookie when there is a size limit imposed on the search 724 results by either the client's request or by the server's 725 configuration. If RUV is used as the cookie, entries last modified 726 by a particular master must be sent to the client in the order of 727 their last modified CSN. This ordering guarantees that the RUV can 728 be updated after each entry is sent. 730 The server�s DIT may be partitioned into different sections which 731 may have different cookies associated with them. For example, some 732 servers may use some sort of replication mechanism to support LCUP. 733 If so, the DIT may be partitioned into multiple replicas. A client 734 may send an LCUP search request that spans multiple replicas. Some 735 parts of the DIT spanned by the search request scope may be managed 736 by LCUP and some may not. A part of the DIT which is enabled for 737 LCUP is referred to as an LCUP Context. The server SHOULD send a 738 SearchResultReference [RFC2251, SECTION 4.5.3] when the LCUP Context 739 for a returned entry changes. The server SHOULD return all entries 740 for a particular LCUP Context before returning a reference to other 741 LCUP Contexts or non LCUP enabled parts of the DIT, in order to 742 minimize the processing burden on the clients. The LDAP URL(s) 743 returned MUST contain the DN(s) of the base of another section of 744 the DIT (however the server implementation has partitioned the DIT). 745 The client will then issue another LCUP search using the LDAP URL 746 returned. Each section of the DIT MAY require a different cookie 747 value, so the client SHOULD maintain a cache, mapping the different 748 LDAP URL values to different cookies. 750 An implementation must be able to notify the client about all 751 entries deleted since the last implementation session. An LDUP 752 compliant implementation can achieve this through the use of entry 753 tombstones. The implementation should avoid aggressive tombstone 754 purging since lack of tombstones would cause client's data to be 755 reloaded. We suggest that only the tombstone content be removed 756 during the regular trimming cycle while tombstones themselves are 757 discarded much less frequently. 759 The specification makes no guarantees about how soon a server should 760 send notification of a changed entry to the client when the 761 connection between the client and the server is kept open. This is 762 intentional as any specific maximum delay would be impossible to 763 meet in a distributed directory service implementation. Server 764 implementors are encouraged to minimize the delay before sending 765 notifications to ensure that clients' needs for timeliness of change 766 notification are met. 768 Implementors of servers that support the mechanism described in this 769 document should ensure that their implementation scales well as the 770 number of active persistent operations and the number of changes 771 made in the directory increases. Server implementors are also 773 Megginson, et. al. Proposed Standard - Expires: November 2001 14 774 encouraged to support a large number of client connections if they 775 need to support large numbers of persistent operations. 777 8. Synchronizing Heterogeneous Data Stores 779 Clients, like a meta directory join engine, synchronizing multiple 780 writable data stores will only work correctly if each piece of 781 information is single mastered (for instance, only by an LDUP 782 compliant directory). This is because different systems have 783 different notions of time and different update resolution 784 procedures. As a result, a change applied on one system can be 785 discarded by the other, thus preventing the data stores from 786 converging. 788 9. Security Considerations 790 In some situations, it may be important to prevent general exposure 791 of information about changes that occur in an LDAP server. 792 Therefore, servers that implement the mechanism described in this 793 document SHOULD provide a means to enforce access control on the 794 entries returned and MAY also provide specific access control 795 mechanisms to control the use of the controls and extended 796 operations defined in this document. 798 As with normal LDAP search requests, a malicious client can initiate 799 a large number of persistent search requests in an attempt to 800 consume all available server resources and deny service to 801 legitimate clients. The protocol provides the means to stop 802 malicious clients by disconnecting them from the server. The servers 803 that implement the mechanism SHOULD provide the means to detect the 804 malicious clients. In addition, the servers SHOULD provide the means 805 to limit the number of resources that can be consumed by a single 806 client. 808 Access control on the data can be modified in such a way that the 809 data is no longer visible to the client. The specification does not 810 specify how the server should handle this condition. Moreover, data 811 consistency is not guaranteed if access control is changed from a 812 more restrictive to a less restrictive one. This is because access 813 control can be considered as an additional filter on the search 814 specification and the protocol does not support going from a more to 815 a less restrictive search specification. See Client Side 816 Considerations Section for more detailed explanation of the problem. 818 10. References 820 [KEYWORDS] S. Bradner, "Keywords for use in RFCs to Indicate 821 Requirement Levels", RFC 2119, March 1997. 823 [RFC2251] M. Wahl, T. Howes, S. Kille "Lightweight Directory 824 Access Protocol", RFC 2251, December 1997. 826 Megginson, et. al. Proposed Standard - Expires: November 2001 15 828 [RFC2252] M. Wahl, A. Coulbeck, T. Howes, S. Kille, �Lightweight 829 Directory Access Protocol (v3): Attribute Syntax 830 Definitions�, RFC 2252, December 1997. 832 11. Acknowledgements 834 The LCUP protocol is based in part on the Persistent Search Change 835 Notification Mechanism defined by Mark Smith, Gordon Good, Tim 836 Howes, and Rob Weltman, the LDAPv3 Triggered Search Control defined 837 by Mark Wahl, and the LDAP Control for Directory Synchronization 838 defined by Michael Armijo. 840 12. Author's Addresses 842 Rich Megginson 843 Netscape Communications Corp. 844 901 San Antonio Rd. 845 Palo Alto, CA 94303-4900 846 Mail Stop SCA17 - 201 847 Phone: +1 408 276-3752 848 Email: richm@netscape.com 850 Olga Natkovich 851 eTime Capital, Inc. 852 1154 E Arques Ave. 853 Sunnyvale, CA 94085 854 Phone: +1 408 830-2029 855 Email: olga@etimecapital.com 857 Mark Smith 858 Netscape Communications Corp. 859 901 San Antonio Rd. 860 Palo Alto, CA 94303-4900 861 Mail Stop SCA17 - 201 862 Phone: +1 650 937-3477 863 Email: mcs@netscape.com 865 Jeff Parham 866 Microsoft Corporation 867 One Microsoft Way 868 Redmond, WA 98052-6399 869 Phone: +1 425 882-8080 870 Email: jeffparh@microsoft.com 872 13. Full Copyright Statement 873 "Copyright (C) The Internet Society (date). All Rights Reserved. 874 This document and translations of it may be copied and furnished to 875 others, and derivative works that comment on or otherwise explain it 876 or assist in its implementation may be prepared, copied, published 877 and distributed, in whole or in part, without restriction of any 878 kind, provided that the above copyright notice and this paragraph 879 are included on all such copies and derivative works. However, this 880 document itself may not be modified in any way, such as by removing 881 the copyright notice or references to the Internet Society or other 883 Megginson, et. al. Proposed Standard - Expires: November 2001 16 884 Internet organizations, except as needed for the purpose of 885 developing Internet standards in which case the procedures for 886 copyrights defined in the Internet Standards process must be 887 followed, or as required to translate it into languages other than 888 English. 890 The limited permissions granted above are perpetual and will not be 891 revoked by the Internet Society or its successors or assigns. 893 This document and the information contained herein is provided on an 894 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 895 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 896 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 897 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 898 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 900 14. Appendix A - Summary of Changes 902 Changes new to version 00: 904 Added the definition for Unique Identifier (basically copied from 905 the LDUP model doc http://search.ietf.org/internet-drafts/draft- 906 ietf-ldup-model-06.txt. I needed to add the definition here 907 because LCUP needs a Unique Identifier but should not be dependent 908 on LDUP. 910 Removed all normative references to LDUP. I�ve left the 911 implementation suggestions that refer to LDUP, but LCUP should not 912 be dependent on LDUP. 914 Cleaned up the protocol flows. 916 Removed this text from section 4.8: �Clients MUST NOT issue 917 multiple synchronization requests on the same connection. This is 918 because the protocol includes an extended operation and it would 919 be impossible to decide which synchronization session it belongs 920 to.� � This is no longer true, since the extended operation now 921 includes the message ID of the search request. 923 �Client Side Consideration� section � the client will never 924 receive a referral or continuation reference 926 Added section 12. Acknowledgements 928 Removed normative references to documents not depended on. 930 Removed explicit references to software vendors. 932 Section 4.1 - Changed ClientUpdateControlValue to remove the 933 keepConnection and changesOnly fields and replace them with 934 updateType which is an ENUMERATED with three values: 935 synchronizeOnly, synchronizeAndPersist, and persistOnly. 937 Megginson, et. al. Proposed Standard - Expires: November 2001 17 938 Section 4.2 - The EntryUpdateControlValue fields stateUpdate and 939 entryDeleted no longer have DEFAULT values, they must be specified 940 � this eliminates any potential ambiguity. 942 Added this text to the description of the entryDeleted field 943 (section 4.2): �The server SHOULD also set this to TRUE if the 944 entry has left the clients search result set. As far as the client 945 is concerned, a deleted entry is no different than an entry which 946 has left the result set.� 947 Section 4.2 - Added an explanation of the concept and requirement 948 for the Unique Identifier. 950 Section 4.4 � Added to the extended operation a request value 951 containing the message id of the operation to stop. 953 Updated contact information for Olga. 955 Removed Michael Armijo and added Jeff Parham as an author. 957 Changes new to previous version: 959 �Authors� section - added Rich Megginson as the new editor. 961 �Client Side Consideration� section � added a note and a question 962 concerning referral and continuation reference handling. 964 �Client Update Control Value� section (4.1) - clarified the meaning 965 of keepConnection and added a table summarizing the effects of 966 different values of keepConnection and changesOnly. 968 �Stop Client Update Request and Response� � added section 4.4 969 describing this extended operation. 971 Megginson, et. al. Proposed Standard - Expires: November 2001 18