1 2 3 4 5 6 7Network Working Group Y. Yaacovi 8Request for Comments: 2589 Microsoft 9Category: Standards Track M. Wahl 10 Innosoft International, Inc. 11 T. Genovese 12 Microsoft 13 May 1999 14 15 16 Lightweight Directory Access Protocol (v3): 17 Extensions for Dynamic Directory Services 18 19Status of this Memo 20 21 This document specifies an Internet standards track protocol for the 22 Internet community, and requests discussion and suggestions for 23 improvements. Please refer to the current edition of the "Internet 24 Official Protocol Standards" (STD 1) for the standardization state 25 and status of this protocol. Distribution of this memo is unlimited. 26 27Copyright Notice 28 29 Copyright (C) The Internet Society (1999). All Rights Reserved. 30 311. Abstract 32 33 This document defines the requirements for dynamic directory services 34 and specifies the format of request and response extended operations 35 for supporting client-server interoperation in a dynamic directories 36 environment. 37 38 The Lightweight Directory Access Protocol (LDAP) [1] supports 39 lightweight access to static directory services, allowing relatively 40 fast search and update access. Static directory services store 41 information about people that persists in its accuracy and value over 42 a long period of time. 43 44 Dynamic directory services are different in that they store 45 information that only persists in its accuracy and value when it is 46 being periodically refreshed. This information is stored as dynamic 47 entries in the directory. A typical use will be a client or a person 48 that is either online - in which case it has an entry in the 49 directory, or is offline - in which case its entry disappears from 50 the directory. Though the protocol operations and attributes used by 51 dynamic directory services are similar to the ones used for static 52 directory services, clients that store dynamic information in the 53 directory need to periodically refresh this information, in order to 54 prevent it from disappearing. If dynamic entries are not refreshed 55 56 57 58Yaacovi, et al. Standards Track [Page 1] 59 60RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 61 62 63 within a given timeout, they will be removed from the directory. For 64 example, this will happen if the client that set them goes offline. 65 66 A flow control mechanism from the server is also described that 67 allows a server to inform clients how often they should refresh their 68 presence. 69 702. Requirements 71 72 The protocol extensions must allow accessing dynamic information in a 73 directory in a standard LDAP manner, to allow clients to access 74 static and dynamic information in the same way. 75 76 By definition, dynamic entries are not persistent and clients may go 77 away gracefully or not. The proposed extensions must offer a way for 78 a server to tell if entries are still valid, and to do this in a way 79 that is scalable. There also must be a mechanism for clients to 80 reestablish their entry with the server. 81 82 There must be a way for clients to find out, in a standard LDAP 83 manner, if servers support the dynamic extensions. 84 85 Finally, to allow clients to broadly use the dynamic extensions, the 86 extensions need to be registered as standard LDAP extended 87 operations. 88 893. Description of Approach 90 91 The Lightweight Directory Access Protocol (LDAP) [1] permits 92 additional operation requests and responses to be added to the 93 protocol. This proposal takes advantage of these to support 94 directories which contain dynamic information in a manner which is 95 fully integrated with LDAP. 96 97 The approach described in this proposal defines dynamic entries in 98 order to allow implementing directories with dynamic information. An 99 implementation of dynamic directories, must be able to support 100 dynamic directory entries. 101 1023.1. Dynamic Entries and the dynamicObject object class 103 104 A dynamic entry is an object in the directory tree which has a time- 105 to-live associated with it. This time-to-live is set when the entry 106 is created. The time-to-live is automatically decremented, and when 107 it expires the dynamic entry disappears. By invoking the refresh 108 extended operation (defined below) to re-set the time-to-live, a 109 client can cause the entry to remain present a while longer. 110 111 112 113 114Yaacovi, et al. Standards Track [Page 2] 115 116RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 117 118 119 A dynamic entry is created by including the objectClass value given 120 in section 5 in the list of attributes when adding an entry. This 121 method is subject to standard access control restrictions. 122 123 The extended operation covered here, allows a client to refresh a 124 dynamic entry by invoking, at intervals, refresh operations 125 containing that entry's name. Dynamic entries will be treated the 126 same as non-dynamic entries when processing search, compare, add, 127 delete, modify and modifyDN operations. However if clients stop 128 sending refresh operations for an entry, then the server will 129 automatically and without notification remove that entry from the 130 directory. This removal will be treated the same as if the entry had 131 been deleted by an LDAP protocol operation. 132 133 There is no way to change a static entry into a dynamic one and 134 vice-versa. If the client is using Modify with an objectClass of 135 dynamicObject on a static entry, the server must return a service 136 error either "objectClassModsProhibited" (if the server does not 137 allow objectClass modifications at all) or "objectClassViolation" (if 138 the server does allow objectClass modifications in general). 139 140 A dynamic entry may be removed by the client using the delete 141 operation. This operation will be subject to access control 142 restrictions. 143 144 A non-dynamic entry cannot be added subordinate to a dynamic entry: 145 the server must return an appropriate update or service error if this 146 is attempted. 147 148 The support of dynamic attributes of an otherwise static object, are 149 outside the scope of this document. 150 1513.2 Dynamic meetings (conferences) 152 153 The way dynamicObject is defined, it has a time-to-live associated 154 with it, and that's about it. Though the most common dynamic object 155 is a person object, there is no specific type associated with the 156 dynamicObject as defined here. By the use of the dynamic object's 157 attributes, one can make this object represent practically anything. 158 159 Specifically, Meetings (conferences) can be represented by dynamic 160 objects. While full-featured meeting support requires special 161 semantics and handling by the server (and is not in the scope of this 162 document), the extensions described here, provide basic meetings 163 support. A meeting object can be refreshed by the meeting 164 participants, and when it is not, the meeting entry disappears. The 165 one meeting type that is naturally supported by the dynamic 166 extensions is creator-owned meeting. 167 168 169 170Yaacovi, et al. Standards Track [Page 3] 171 172RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 173 174 1753.2.1 Creator-owned meetings 176 177 Creator-owned meetings are created by a client that sets the time- 178 to-live attribute for the entry, and it is this client's 179 responsibility to refresh the meeting entry, so that it will not 180 disappear. Others might join the meeting, by modifying the 181 appropriate attribute, but they are not allowed to refresh the entry. 182 When the client that created the entry goes away, it can delete the 183 meeting entry, or it might disappear when its time-to-live expires. 184 This is consistent with the common model for dynamicObject as 185 described above. 186 1874. Protocol Additions 188 1894.1 Refresh Request 190 191 Refresh is a protocol operation sent by a client to tell the server 192 that the client is still alive and the dynamic directory entry is 193 still accurate and valuable. The client sends a Refresh request 194 periodically based on the value of the client refresh period (CRP). 195 The server can request that the client change this value. As long as 196 the server receives a Refresh request within the timeout period, the 197 directory entry is guaranteed to persist on the server. Client 198 implementers should be aware that since the intervening network 199 between the client and server is unreliable, a Refresh request packet 200 may be delayed or lost while in transit. If this occurs, the entry 201 may disappear, and the client will need to detect this and re-add the 202 entry. 203 204 A client may request this operation by transmitting an LDAP PDU 205 containing an ExtendedRequest. An LDAP ExtendedRequest is defined as 206 follows: 207 208 ExtendedRequest ::= [APPLICATION 23] SEQUENCE { 209 requestName [0] LDAPOID, 210 requestValue [1] OCTET STRING OPTIONAL } 211 212 The requestName field must be set to the string 213 "1.3.6.1.4.1.1466.101.119.1". 214 215 The requestValue field will contain as a value the DER-encoding of 216 the following ASN.1 data type: 217 218 SEQUENCE { 219 entryName [0] LDAPDN, 220 requestTtl [1] INTEGER 221 } 222 223 224 225 226Yaacovi, et al. Standards Track [Page 4] 227 228RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 229 230 231 The entryName field is the UTF-8 string representation of the name of 232 the dynamic entry [3]. This entry must already exist. 233 234 The requestTtl is a time in seconds (between 1 and 31557600) that the 235 client requests that the entry exists in the directory before being 236 automatically removed. Servers are not required to accept this value 237 and might return a different TTL value to the client. Clients must 238 be able to use this server-dictated value as their CRP. 239 2404.2 Refresh Response 241 242 If a server implements this extension, then when the request is made 243 it will return an LDAP PDU containing an ExtendedResponse. An LDAP 244 ExtendedResponse is defined as follows: 245 246 ExtendedResponse ::= [APPLICATION 24] SEQUENCE { 247 COMPONENTS OF LDAPResult, 248 responseName [10] LDAPOID OPTIONAL, 249 response [11] OCTET STRING OPTIONAL } 250 251 The responseName field contains the same string as that present in 252 the request. 253 254 The response field will contain as a value the DER-encoding of the 255 following ASN.1 data type: 256 257 SEQUENCE { 258 responseTtl [1] INTEGER 259 } 260 261 The responseTtl field is the time in seconds which the server chooses 262 to have as the time-to-live field for that entry. It must not be any 263 smaller than that which the client requested, and it may be larger. 264 However, to allow servers to maintain a relatively accurate 265 directory, and to prevent clients from abusing the dynamic 266 extensions, servers are permitted to shorten a client-requested 267 time-to-live value, down to a minimum of 86400 seconds (one day). 268 269 If the operation was successful, the errorCode field in the 270 standardResponse part of an ExtendedResponse will be set to success. 271 272 In case of an error, the responseTtl field will have the value 0, and 273 the errorCode field will contain an appropriate value, as follows: If 274 the entry named by entryName could not be located, the errorCode 275 field will contain "noSuchObject". If the entry is not dynamic, the 276 errorCode field will contain "objectClassViolation". If the 277 requester does not have permission to refresh the entry, the 278 279 280 281 282Yaacovi, et al. Standards Track [Page 5] 283 284RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 285 286 287 errorCode field will contain "insufficientAccessRights". If the 288 requestTtl field is too large, the errorCode field will contain 289 "sizeLimitExceeded". 290 291 If a server does not implement this extension, it will return an LDAP 292 PDU containing an ExtendedResponse, which contains only the 293 standardResponse element (the responseName and response elements will 294 be absent). The LDAPResult element will indicate the protocolError 295 result code. 296 297 This request is permitted to be invoked when LDAP is carried by a 298 connectionless transport. 299 300 When using a connection-oriented transport, there is no requirement 301 that this operation be on the same particular connection as any 302 other. A client may open multiple connections, or close and then 303 reopen a connection. 304 3054.3 X.500/DAP Modify(97) 306 307 X.500/DAP servers can map the Refresh request and response operations 308 into the X.500/DAP Modify(97) operation. 309 3105. Schema Additions 311 312 All dynamic entries must have the dynamicObject value in their 313 objectClass attribute. This object class is defined as follows 314 (using the ObjectClassDescription notation of [2]): 315 316 ( 1.3.6.1.4.1.1466.101.119.2 NAME 'dynamicObject' 317 DESC 'This class, if present in an entry, indicates that this entry 318 has a limited lifetime and may disappear automatically when 319 its time-to-live has reached 0. There are no mandatory 320 attributes of this class, however if the client has not 321 supplied a value for the entryTtl attribute, the server will 322 provide one.' 323 SUP top AUXILIARY ) 324 325 Furthermore, the dynamic entry must have the following operational 326 attribute. It is described using the AttributeTypeDescription 327 notation of [2]: 328 329 ( 1.3.6.1.4.1.1466.101.119.3 NAME 'entryTtl' 330 DESC 'This operational attribute is maintained by the server and 331 appears to be present in every dynamic entry. The attribute 332 is not present when the entry does not contain the 333 dynamicObject object class. The value of this attribute is 334 the time in seconds that the entry will continue to exist 335 336 337 338Yaacovi, et al. Standards Track [Page 6] 339 340RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 341 342 343 before disappearing from the directory. In the absence of 344 intervening refresh operations, the values returned by 345 reading the attribute in two successive searches are 346 guaranteed to be nonincreasing. The smallest permissible 347 value is 0, indicating that the entry may disappear without 348 warning. The attribute is marked NO-USER-MODIFICATION since 349 it may only be changed using the refresh operation.' 350 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE 351 NO-USER-MODIFICATION USAGE dSAOperation ) 352 353 To allow servers to support dynamic entries in only a part of the 354 DIT, the following operational attribute is defined. It is 355 described using the AttributeTypeDescription notation of [2]: 356 357 ( 1.3.6.1.4.1.1466.101.119.4 NAME 'dynamicSubtrees' 358 DESC 'This operational attribute is maintained by the server and is 359 present in the Root DSE, if the server supports the dynamic 360 extensions described in this memo. The attribute contains a 361 list of all the subtrees in this directory for which the 362 server supports the dynamic extensions.' 363 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 NO-USER-MODIFICATION 364 USAGE dSAOperation ) 365 3666. Client and Server Requirements 367 3686.1 Client Requirements 369 370 Clients can find out if a server supports the dynamic extensions by 371 checking the supportedExtension field in the root DSE, to see if the 372 OBJECT IDENTIFIER described in section 4 is present. Since servers 373 may select to support the dynamic extensions in only some of the 374 subtrees of the DIT, clients must check the dynamicSubtrees 375 operational attribute in the root DSE to find out if the dynamic 376 extensions are supported on a specific subtree. 377 378 Once a dynamic entry has been created, clients are responsible for 379 invoking the refresh extended operation, in order to keep that entry 380 present in the directory. 381 382 Clients must not expect that a dynamic entry will be present in the 383 DIT after it has timed out, however it must not require that the 384 server remove the entry immediately (some servers may only process 385 timing out entries at intervals). If the client wishes to ensure the 386 entry does not exist it should issue a RemoveRequest for that entry. 387 388 Initially, a client needs to know how often it should send refresh 389 requests to the server. This value is defined as the CRP (Client 390 Refresh Period) and is set by the server based on the entryTtl. 391 392 393 394Yaacovi, et al. Standards Track [Page 7] 395 396RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 397 398 399 Since the LDAP AddRequest operation is left unchanged and is not 400 modified in this proposal to return this value, a client must issue a 401 Refresh extended operation immediately after an Add that created a 402 dynamic entry. The Refresh Response will return the CRP (in 403 responseTtl) to the client. 404 405 Clients must not issue the refresh request for dynamic entries which 406 they have not created. If an anonymous client attempts to do so, a 407 server is permitted to return insufficientAccessRights (50) in the 408 RefreshResponse, enforcing the client to bind first. Please note that 409 servers which allow anonymous clients to create and refresh dynamic 410 entries will not be able to enforce the above. 411 412 Clients should always be ready to handle the case in which their 413 entry timed out. In such a case, the Refresh operation will fail 414 with an error code such as noSuchObject, and the client is expected 415 to re-create its entry. 416 417 Clients should be prepared to experience refresh operations failing 418 with protocolError, even though the add and any previous refresh 419 requests succeeded. This might happen if a proxy between the client 420 and the server goes down, and another proxy is used which does not 421 support the Refresh extended operation. 422 4236.2 Server Requirements 424 425 Servers are responsible for removing dynamic entries when they time 426 out. Servers are not required to do this immediately. 427 428 Servers must enforce the structural rules listed in above section 3. 429 430 Servers must ensure that the operational attribute described in 431 section 5 is present in dynamic entries 432 433 Servers may permit anonymous users to refresh entries. However, to 434 eliminate the possibility of a malicious use of the Refresh 435 operation, servers may require the refreshing client to bind first. A 436 server implementation can achieve this by presenting ACLs on the 437 entryTtl attribute, and returning insufficientAccessRights (50) in 438 the RefreshResponse, if the client is not allowed to refresh the 439 entry. Doing this, though, might have performance implications on the 440 server and might impact the server's scalability. 441 442 Servers may require that a client which attempts to create a dynamic 443 entry have a remove permission for that entry. 444 445 Servers which implement the dynamic extensions must have the OBJECT 446 IDENTIFIER, described above in section 4 for the request and 447 448 449 450Yaacovi, et al. Standards Track [Page 8] 451 452RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 453 454 455 response, present as a value of the supportedExtension field in the 456 root DSE. They must also have as values in the attributeTypes and 457 objectClasses attributes of their subschema subentries, the 458 AttributeTypeDescription and ObjectClassDescription from section 5. 459 460 Servers can limit the support of the dynamic extensions to only some 461 of the subtrees in the DIT. Servers indicate for which subtrees they 462 support the extensions, by specifying the OIDs for the supported 463 subtrees in the dynamicSubtrees attribute described in section 5. If 464 a server supports the dynamic extensions for all naming contexts it 465 holds, the dynamicSubtrees attribute may be absent. 466 4677. Implementation issues 468 4697.1 Storage of dynamic information 470 471 Dynamic information is expected to change very often. In addition, 472 Refresh requests are expected to arrive at the server very often. 473 Disk-based databases that static directory services often use are 474 likely inappropriate for storing dynamic information. We recommend 475 that server implementations store dynamic entries in memory 476 sufficient to avoid paging. This is not a requirement. 477 478 We expect LDAP servers to be able to store static and dynamic 479 entries. If an LDAP server does not support dynamic entries, it 480 should respond with an error code such as objectClassViolation. 481 4827.2 Client refresh behavior 483 484 In some cases, the client might not get a Refresh response. This may 485 happen as a result of a server crash after receiving the Refresh 486 request, the TCP/IP socket timing out in the connection case, or the 487 UDP packet getting lost in the connection-less case. 488 489 It is recommended that in such a case, the client will retry the 490 Refresh operation immediately, and if this Refresh request does not 491 get a response as well, it will resort to its original Refresh cycle, 492 i.e. send a Refresh request at its Client Refresh Period (CRP). 493 4947.3 Configuration of refresh times 495 496 We recommend that servers will provide administrators with the 497 ability to configure the default client refresh period (CRP), and 498 also a minimum and maximum CRP values. This, together with allowing 499 administrators to request that the server will not change the CRP 500 dynamically, will allow administrators to set CRP values which will 501 enforce a low refresh traffic, or - on the other extreme, an highly 502 up-to-date directory. 503 504 505 506Yaacovi, et al. Standards Track [Page 9] 507 508RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 509 510 5118. Replication 512 513 Replication is only partially addressed in this memo. There is a 514 separate effort in progress at the IETF on replication of static and 515 dynamic directories. 516 517 it is allowed to replicate a dynamic entry or a static entry with 518 dynamic attributes. Since the entryTtl is expressed as a relative 519 time (how many seconds till the entry will expire), replicating it 520 means that the replicated entry will be "off" by the replication 521 time. 522 5239. Localization 524 525 The are no localization issues for this extended operation. 526 52710. Security Considerations 528 529 Standard LDAP security rules and support apply for the extensions 530 described in this document, and there are no special security issues 531 for these extensions. Please note, though, that servers may permit 532 anonymous clients to refresh entries which they did not create. 533 Servers are also permitted to control a refresh access to an entry by 534 requiring clients to bind before issuing a RefreshRequest. This will 535 have implications on the server performance and scalability. 536 537 Also, Care should be taken in making use of information obtained from 538 directory servers that has been supplied by client, as it may now be 539 out of date. In many networks, for example, IP addresses are 540 automatically assigned when a host connects to the network, and may 541 be reassigned if that host later disconnects. An IP address obtained 542 from the directory may no longer be assigned to the host that placed 543 the address in the directory. This issue is not specific to LDAP or 544 dynamic directories. 545 54611. Acknowledgments 547 548 Design ideas included in this document are based on those discussed 549 in ASID and other IETF Working Groups. 550 551 552 553 554 555 556 557 558 559 560 561 562Yaacovi, et al. Standards Track [Page 10] 563 564RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 565 566 56712. Authors' Addresses 568 569 Yoram Yaacovi 570 Microsoft 571 One Microsoft way 572 Redmond, WA 98052 573 USA 574 575 Phone: +1 206-936-9629 576 EMail: yoramy@microsoft.com 577 578 579 Mark Wahl 580 Innosoft International, Inc. 581 8911 Capital of Texas Hwy #4140 582 Austin, TX 78759 583 USA 584 585 Email: M.Wahl@innosoft.com 586 587 588 Tony Genovese 589 Microsoft 590 One Microsoft way 591 Redmond, WA 98052 592 USA 593 594 Phone: +1 206-703-0852 595 EMail: tonyg@microsoft.com 596 59713. Bibliography 598 599 [1] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access 600 Protocol (Version 3)", RFC 2251, December 1997. 601 602 [2] Wahl, M. Coulbeck, A., Howes, T. and S. Kille, "Lightweight 603 Directory Access Protocol (v3): Attribute Syntax Definitions", 604 RFC 2252, December 1997. 605 606 [3] Wahl, M. and S. Kille, "Lightweight Directory Access Protocol 607 (v3): UTF-8 String Representation of Distinguished Names", RFC 608 2253, December 1997. 609 610 611 612 613 614 615 616 617 618Yaacovi, et al. Standards Track [Page 11] 619 620RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 621 622 62314. Full Copyright Statement 624 625 Copyright (C) The Internet Society (1999). All Rights Reserved. 626 627 This document and translations of it may be copied and furnished to 628 others, and derivative works that comment on or otherwise explain it 629 or assist in its implementation may be prepared, copied, published 630 and distributed, in whole or in part, without restriction of any 631 kind, provided that the above copyright notice and this paragraph are 632 included on all such copies and derivative works. However, this 633 document itself may not be modified in any way, such as by removing 634 the copyright notice or references to the Internet Society or other 635 Internet organizations, except as needed for the purpose of 636 developing Internet standards in which case the procedures for 637 copyrights defined in the Internet Standards process must be 638 followed, or as required to translate it into languages other than 639 English. 640 641 The limited permissions granted above are perpetual and will not be 642 revoked by the Internet Society or its successors or assigns. 643 644 This document and the information contained herein is provided on an 645 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 646 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 647 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 648 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 649 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 650 651Acknowledgement 652 653 Funding for the RFC Editor function is currently provided by the 654 Internet Society. 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674Yaacovi, et al. Standards Track [Page 12] 675 676