Edit File: rfc2589.txt
Network Working Group Y. Yaacovi Request for Comments: 2589 Microsoft Category: Standards Track M. Wahl Innosoft International, Inc. T. Genovese Microsoft May 1999 Lightweight Directory Access Protocol (v3): Extensions for Dynamic Directory Services Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (1999). All Rights Reserved. 1. Abstract This document defines the requirements for dynamic directory services and specifies the format of request and response extended operations for supporting client-server interoperation in a dynamic directories environment. The Lightweight Directory Access Protocol (LDAP) [1] supports lightweight access to static directory services, allowing relatively fast search and update access. Static directory services store information about people that persists in its accuracy and value over a long period of time. Dynamic directory services are different in that they store information that only persists in its accuracy and value when it is being periodically refreshed. This information is stored as dynamic entries in the directory. A typical use will be a client or a person that is either online - in which case it has an entry in the directory, or is offline - in which case its entry disappears from the directory. Though the protocol operations and attributes used by dynamic directory services are similar to the ones used for static directory services, clients that store dynamic information in the directory need to periodically refresh this information, in order to prevent it from disappearing. If dynamic entries are not refreshed Yaacovi, et al. Standards Track [Page 1] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 within a given timeout, they will be removed from the directory. For example, this will happen if the client that set them goes offline. A flow control mechanism from the server is also described that allows a server to inform clients how often they should refresh their presence. 2. Requirements The protocol extensions must allow accessing dynamic information in a directory in a standard LDAP manner, to allow clients to access static and dynamic information in the same way. By definition, dynamic entries are not persistent and clients may go away gracefully or not. The proposed extensions must offer a way for a server to tell if entries are still valid, and to do this in a way that is scalable. There also must be a mechanism for clients to reestablish their entry with the server. There must be a way for clients to find out, in a standard LDAP manner, if servers support the dynamic extensions. Finally, to allow clients to broadly use the dynamic extensions, the extensions need to be registered as standard LDAP extended operations. 3. Description of Approach The Lightweight Directory Access Protocol (LDAP) [1] permits additional operation requests and responses to be added to the protocol. This proposal takes advantage of these to support directories which contain dynamic information in a manner which is fully integrated with LDAP. The approach described in this proposal defines dynamic entries in order to allow implementing directories with dynamic information. An implementation of dynamic directories, must be able to support dynamic directory entries. 3.1. Dynamic Entries and the dynamicObject object class A dynamic entry is an object in the directory tree which has a time- to-live associated with it. This time-to-live is set when the entry is created. The time-to-live is automatically decremented, and when it expires the dynamic entry disappears. By invoking the refresh extended operation (defined below) to re-set the time-to-live, a client can cause the entry to remain present a while longer. Yaacovi, et al. Standards Track [Page 2] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 A dynamic entry is created by including the objectClass value given in section 5 in the list of attributes when adding an entry. This method is subject to standard access control restrictions. The extended operation covered here, allows a client to refresh a dynamic entry by invoking, at intervals, refresh operations containing that entry's name. Dynamic entries will be treated the same as non-dynamic entries when processing search, compare, add, delete, modify and modifyDN operations. However if clients stop sending refresh operations for an entry, then the server will automatically and without notification remove that entry from the directory. This removal will be treated the same as if the entry had been deleted by an LDAP protocol operation. There is no way to change a static entry into a dynamic one and vice-versa. If the client is using Modify with an objectClass of dynamicObject on a static entry, the server must return a service error either "objectClassModsProhibited" (if the server does not allow objectClass modifications at all) or "objectClassViolation" (if the server does allow objectClass modifications in general). A dynamic entry may be removed by the client using the delete operation. This operation will be subject to access control restrictions. A non-dynamic entry cannot be added subordinate to a dynamic entry: the server must return an appropriate update or service error if this is attempted. The support of dynamic attributes of an otherwise static object, are outside the scope of this document. 3.2 Dynamic meetings (conferences) The way dynamicObject is defined, it has a time-to-live associated with it, and that's about it. Though the most common dynamic object is a person object, there is no specific type associated with the dynamicObject as defined here. By the use of the dynamic object's attributes, one can make this object represent practically anything. Specifically, Meetings (conferences) can be represented by dynamic objects. While full-featured meeting support requires special semantics and handling by the server (and is not in the scope of this document), the extensions described here, provide basic meetings support. A meeting object can be refreshed by the meeting participants, and when it is not, the meeting entry disappears. The one meeting type that is naturally supported by the dynamic extensions is creator-owned meeting. Yaacovi, et al. Standards Track [Page 3] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 3.2.1 Creator-owned meetings Creator-owned meetings are created by a client that sets the time- to-live attribute for the entry, and it is this client's responsibility to refresh the meeting entry, so that it will not disappear. Others might join the meeting, by modifying the appropriate attribute, but they are not allowed to refresh the entry. When the client that created the entry goes away, it can delete the meeting entry, or it might disappear when its time-to-live expires. This is consistent with the common model for dynamicObject as described above. 4. Protocol Additions 4.1 Refresh Request Refresh is a protocol operation sent by a client to tell the server that the client is still alive and the dynamic directory entry is still accurate and valuable. The client sends a Refresh request periodically based on the value of the client refresh period (CRP). The server can request that the client change this value. As long as the server receives a Refresh request within the timeout period, the directory entry is guaranteed to persist on the server. Client implementers should be aware that since the intervening network between the client and server is unreliable, a Refresh request packet may be delayed or lost while in transit. If this occurs, the entry may disappear, and the client will need to detect this and re-add the entry. A client may request this operation by transmitting an LDAP PDU containing an ExtendedRequest. An LDAP ExtendedRequest is defined as follows: ExtendedRequest ::= [APPLICATION 23] SEQUENCE { requestName [0] LDAPOID, requestValue [1] OCTET STRING OPTIONAL } The requestName field must be set to the string "1.3.6.1.4.1.1466.101.119.1". The requestValue field will contain as a value the DER-encoding of the following ASN.1 data type: SEQUENCE { entryName [0] LDAPDN, requestTtl [1] INTEGER } Yaacovi, et al. Standards Track [Page 4] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 The entryName field is the UTF-8 string representation of the name of the dynamic entry [3]. This entry must already exist. The requestTtl is a time in seconds (between 1 and 31557600) that the client requests that the entry exists in the directory before being automatically removed. Servers are not required to accept this value and might return a different TTL value to the client. Clients must be able to use this server-dictated value as their CRP. 4.2 Refresh Response If a server implements this extension, then when the request is made it will return an LDAP PDU containing an ExtendedResponse. An LDAP ExtendedResponse is defined as follows: ExtendedResponse ::= [APPLICATION 24] SEQUENCE { COMPONENTS OF LDAPResult, responseName [10] LDAPOID OPTIONAL, response [11] OCTET STRING OPTIONAL } The responseName field contains the same string as that present in the request. The response field will contain as a value the DER-encoding of the following ASN.1 data type: SEQUENCE { responseTtl [1] INTEGER } The responseTtl field is the time in seconds which the server chooses to have as the time-to-live field for that entry. It must not be any smaller than that which the client requested, and it may be larger. However, to allow servers to maintain a relatively accurate directory, and to prevent clients from abusing the dynamic extensions, servers are permitted to shorten a client-requested time-to-live value, down to a minimum of 86400 seconds (one day). If the operation was successful, the errorCode field in the standardResponse part of an ExtendedResponse will be set to success. In case of an error, the responseTtl field will have the value 0, and the errorCode field will contain an appropriate value, as follows: If the entry named by entryName could not be located, the errorCode field will contain "noSuchObject". If the entry is not dynamic, the errorCode field will contain "objectClassViolation". If the requester does not have permission to refresh the entry, the Yaacovi, et al. Standards Track [Page 5] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 errorCode field will contain "insufficientAccessRights". If the requestTtl field is too large, the errorCode field will contain "sizeLimitExceeded". If a server does not implement this extension, it will return an LDAP PDU containing an ExtendedResponse, which contains only the standardResponse element (the responseName and response elements will be absent). The LDAPResult element will indicate the protocolError result code. This request is permitted to be invoked when LDAP is carried by a connectionless transport. When using a connection-oriented transport, there is no requirement that this operation be on the same particular connection as any other. A client may open multiple connections, or close and then reopen a connection. 4.3 X.500/DAP Modify(97) X.500/DAP servers can map the Refresh request and response operations into the X.500/DAP Modify(97) operation. 5. Schema Additions All dynamic entries must have the dynamicObject value in their objectClass attribute. This object class is defined as follows (using the ObjectClassDescription notation of [2]): ( 1.3.6.1.4.1.1466.101.119.2 NAME 'dynamicObject' DESC 'This class, if present in an entry, indicates that this entry has a limited lifetime and may disappear automatically when its time-to-live has reached 0. There are no mandatory attributes of this class, however if the client has not supplied a value for the entryTtl attribute, the server will provide one.' SUP top AUXILIARY ) Furthermore, the dynamic entry must have the following operational attribute. It is described using the AttributeTypeDescription notation of [2]: ( 1.3.6.1.4.1.1466.101.119.3 NAME 'entryTtl' DESC 'This operational attribute is maintained by the server and appears to be present in every dynamic entry. The attribute is not present when the entry does not contain the dynamicObject object class. The value of this attribute is the time in seconds that the entry will continue to exist Yaacovi, et al. Standards Track [Page 6] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 before disappearing from the directory. In the absence of intervening refresh operations, the values returned by reading the attribute in two successive searches are guaranteed to be nonincreasing. The smallest permissible value is 0, indicating that the entry may disappear without warning. The attribute is marked NO-USER-MODIFICATION since it may only be changed using the refresh operation.' SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE NO-USER-MODIFICATION USAGE dSAOperation ) To allow servers to support dynamic entries in only a part of the DIT, the following operational attribute is defined. It is described using the AttributeTypeDescription notation of [2]: ( 1.3.6.1.4.1.1466.101.119.4 NAME 'dynamicSubtrees' DESC 'This operational attribute is maintained by the server and is present in the Root DSE, if the server supports the dynamic extensions described in this memo. The attribute contains a list of all the subtrees in this directory for which the server supports the dynamic extensions.' SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 NO-USER-MODIFICATION USAGE dSAOperation ) 6. Client and Server Requirements 6.1 Client Requirements Clients can find out if a server supports the dynamic extensions by checking the supportedExtension field in the root DSE, to see if the OBJECT IDENTIFIER described in section 4 is present. Since servers may select to support the dynamic extensions in only some of the subtrees of the DIT, clients must check the dynamicSubtrees operational attribute in the root DSE to find out if the dynamic extensions are supported on a specific subtree. Once a dynamic entry has been created, clients are responsible for invoking the refresh extended operation, in order to keep that entry present in the directory. Clients must not expect that a dynamic entry will be present in the DIT after it has timed out, however it must not require that the server remove the entry immediately (some servers may only process timing out entries at intervals). If the client wishes to ensure the entry does not exist it should issue a RemoveRequest for that entry. Initially, a client needs to know how often it should send refresh requests to the server. This value is defined as the CRP (Client Refresh Period) and is set by the server based on the entryTtl. Yaacovi, et al. Standards Track [Page 7] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 Since the LDAP AddRequest operation is left unchanged and is not modified in this proposal to return this value, a client must issue a Refresh extended operation immediately after an Add that created a dynamic entry. The Refresh Response will return the CRP (in responseTtl) to the client. Clients must not issue the refresh request for dynamic entries which they have not created. If an anonymous client attempts to do so, a server is permitted to return insufficientAccessRights (50) in the RefreshResponse, enforcing the client to bind first. Please note that servers which allow anonymous clients to create and refresh dynamic entries will not be able to enforce the above. Clients should always be ready to handle the case in which their entry timed out. In such a case, the Refresh operation will fail with an error code such as noSuchObject, and the client is expected to re-create its entry. Clients should be prepared to experience refresh operations failing with protocolError, even though the add and any previous refresh requests succeeded. This might happen if a proxy between the client and the server goes down, and another proxy is used which does not support the Refresh extended operation. 6.2 Server Requirements Servers are responsible for removing dynamic entries when they time out. Servers are not required to do this immediately. Servers must enforce the structural rules listed in above section 3. Servers must ensure that the operational attribute described in section 5 is present in dynamic entries Servers may permit anonymous users to refresh entries. However, to eliminate the possibility of a malicious use of the Refresh operation, servers may require the refreshing client to bind first. A server implementation can achieve this by presenting ACLs on the entryTtl attribute, and returning insufficientAccessRights (50) in the RefreshResponse, if the client is not allowed to refresh the entry. Doing this, though, might have performance implications on the server and might impact the server's scalability. Servers may require that a client which attempts to create a dynamic entry have a remove permission for that entry. Servers which implement the dynamic extensions must have the OBJECT IDENTIFIER, described above in section 4 for the request and Yaacovi, et al. Standards Track [Page 8] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 response, present as a value of the supportedExtension field in the root DSE. They must also have as values in the attributeTypes and objectClasses attributes of their subschema subentries, the AttributeTypeDescription and ObjectClassDescription from section 5. Servers can limit the support of the dynamic extensions to only some of the subtrees in the DIT. Servers indicate for which subtrees they support the extensions, by specifying the OIDs for the supported subtrees in the dynamicSubtrees attribute described in section 5. If a server supports the dynamic extensions for all naming contexts it holds, the dynamicSubtrees attribute may be absent. 7. Implementation issues 7.1 Storage of dynamic information Dynamic information is expected to change very often. In addition, Refresh requests are expected to arrive at the server very often. Disk-based databases that static directory services often use are likely inappropriate for storing dynamic information. We recommend that server implementations store dynamic entries in memory sufficient to avoid paging. This is not a requirement. We expect LDAP servers to be able to store static and dynamic entries. If an LDAP server does not support dynamic entries, it should respond with an error code such as objectClassViolation. 7.2 Client refresh behavior In some cases, the client might not get a Refresh response. This may happen as a result of a server crash after receiving the Refresh request, the TCP/IP socket timing out in the connection case, or the UDP packet getting lost in the connection-less case. It is recommended that in such a case, the client will retry the Refresh operation immediately, and if this Refresh request does not get a response as well, it will resort to its original Refresh cycle, i.e. send a Refresh request at its Client Refresh Period (CRP). 7.3 Configuration of refresh times We recommend that servers will provide administrators with the ability to configure the default client refresh period (CRP), and also a minimum and maximum CRP values. This, together with allowing administrators to request that the server will not change the CRP dynamically, will allow administrators to set CRP values which will enforce a low refresh traffic, or - on the other extreme, an highly up-to-date directory. Yaacovi, et al. Standards Track [Page 9] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 8. Replication Replication is only partially addressed in this memo. There is a separate effort in progress at the IETF on replication of static and dynamic directories. it is allowed to replicate a dynamic entry or a static entry with dynamic attributes. Since the entryTtl is expressed as a relative time (how many seconds till the entry will expire), replicating it means that the replicated entry will be "off" by the replication time. 9. Localization The are no localization issues for this extended operation. 10. Security Considerations Standard LDAP security rules and support apply for the extensions described in this document, and there are no special security issues for these extensions. Please note, though, that servers may permit anonymous clients to refresh entries which they did not create. Servers are also permitted to control a refresh access to an entry by requiring clients to bind before issuing a RefreshRequest. This will have implications on the server performance and scalability. Also, Care should be taken in making use of information obtained from directory servers that has been supplied by client, as it may now be out of date. In many networks, for example, IP addresses are automatically assigned when a host connects to the network, and may be reassigned if that host later disconnects. An IP address obtained from the directory may no longer be assigned to the host that placed the address in the directory. This issue is not specific to LDAP or dynamic directories. 11. Acknowledgments Design ideas included in this document are based on those discussed in ASID and other IETF Working Groups. Yaacovi, et al. Standards Track [Page 10] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 12. Authors' Addresses Yoram Yaacovi Microsoft One Microsoft way Redmond, WA 98052 USA Phone: +1 206-936-9629 EMail: yoramy@microsoft.com Mark Wahl Innosoft International, Inc. 8911 Capital of Texas Hwy #4140 Austin, TX 78759 USA Email: M.Wahl@innosoft.com Tony Genovese Microsoft One Microsoft way Redmond, WA 98052 USA Phone: +1 206-703-0852 EMail: tonyg@microsoft.com 13. Bibliography [1] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (Version 3)", RFC 2251, December 1997. [2] Wahl, M. Coulbeck, A., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, December 1997. [3] Wahl, M. and S. Kille, "Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names", RFC 2253, December 1997. Yaacovi, et al. Standards Track [Page 11] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 14. Full Copyright Statement Copyright (C) The Internet Society (1999). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Yaacovi, et al. Standards Track [Page 12]