HTTP/1.1 200 OK Date: Tue, 09 Apr 2002 00:53:52 GMT Server: Apache/1.3.20 (Unix) Last-Modified: Wed, 16 Apr 1997 22:16:00 GMT ETag: "304d9b-65b6-33554fa0" Accept-Ranges: bytes Content-Length: 26038 Connection: close Content-Type: text/plain ASID Working Group Y. Yaacovi INTERNET-DRAFT Microsoft M. Wahl Critical Angle Inc. K. Settle Microsoft T. Genovese Microsoft Expires in six months from 25 March 1997 Intended Category: Standards Track Lightweight Directory Access Protocol: Extensions for Dynamic Directory Services 1. Status of this Memo This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." To learn the current status of any Internet-Draft, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). 2. 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 about people that only persists in its accuracy and value when it is being periodically refreshed. This information is stored as dynamic entries and/or dynamic attributes. A typical use will be a client or a person that is either online - in which case it has an entry or attributes in the directory, or is offline - in which case its entry or attributes disappear 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 or attributes are not refreshed within a given timeout, they will be removed from the directory. For example, this will happen if the client that set them goes offline. In addition, static directories may include dynamic information, in the form of dynamic attributes in an otherwise static entry. Such information needs to be refreshed periodically in the same manner. A flow control mechanism from the server is also described that allows a server to inform clients how often they should refresh their presence. 3. 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 or dynamic attributes 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 or attributes 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 or attributes with the server. Finally, to allow clients to broadly use the dynamic extensions, the extensions need to be registered as standard LDAP extended operations. 4. 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 and dynamic attributes in order to allow implementing directories with dynamic information. An implementation of dynamic directories, must be able to support both dynamic directory entries and dynamic attributes. 4.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. A dynamic entry is created by including the objectClass value given in section 6 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. 4.2. Dynamic Attributes A similar concept is dynamic attributes. These attributes behave the same as ordinary user attributes to Search, Compare and Modify requests, except that if they time out they disappear from the entry in which they are located. (Unlike the dynamicObject class, the entry itself does not disappear, and non-dynamic attributes are unaffected). Like dynamic entries, a static entry with dynamic attributes must have the entryTtl attribute which is described in section 6 below. Dynamic attributes do not necessarily introduce a new set of attributes in the schema. Any static attribute in the schema can be made dynamic by including the ;dynamic attribute modifier with the typename. It is allowed to introduce new dynamic attributes which are not useful in the static domain. Such attributes will still require including the ;dynamic attribute modifier with the typename to define them as dynamic. A dynamic attribute may be a subtype of a non-dynamic attribute, but a non-dynamic attribute must not be a subtype of a dynamic attribute. Operational attributes and collective attributes must not be dynamic. All dynamic attributes are considered to be user attributes, however they are not guaranteed to be present in shadow copies of entries. A client may introduce dynamic attributes into an entry by using a Modify request to add them, or by including them in the attribute list of an Add Request. If the attribute type is permitted in the entry then the dynamic attribute is also permitted. The client would specify that the attribute is dynamic by including the tag ";dynamic" with the typename. Dynamic values may be changed, and the attributes removed, by using the Modify request as normal. If the entry is deleted, dynamic attributes disappear immediately along with all the non-dynamic. A ;dynamic modifier on an attribute may not be used in a compare request, or in a search request (either in the filter or attributes requested for return). This is in keeping with the philosophy that dynamic attributes be indistinguishable from static attributes as much as possible. In such a case, a server is expected to reject the request, returning 'invalidAttributeSyntax'. The granularity of a dynamic attribute is the entire attribute including all values. Dynamic and static values may not be mixed within a single attribute. For example, suppose an existing static entry had an attribute called "ipAddress" with the value "1.2.3.4". A modification of the entry to add the value "5.4.3.2" to the attribute "ipAddress;dynamic" would fail with a "constraintViolation" error. The addition and modification of dynamic attributes are subject to schema and access control restrictions, as with non-dynamic attributes. Thus unless the extensibleObject object class is present, generally an object class or content rule must be defined to permit those attributes to be present in an entry. If their presence is controlled by an object class, then just as with non-dynamic attributes, the object class value must have already been added before the attributes are added. The dynamicObject object class described in section 4.1 does not itself permit any particular dynamic attributes. Dynamic attributes in a particular entry are refreshed using the Refresh extended operation. All of the entry's dynamic attributes are refreshed by a single refresh request. The TTL given in the refresh response applies to all of the entry's dynamic attributes. There is no way to refresh particular dynamic attributes within an entry at different times, or to have different TTLs apply to different dynamic attributes. If not refreshed, all dynamic attributes in an entry time out simultaneously. All the attributes which are dynamic with all their values disappear atomically, as if the server had done a ModifyEntry specifying that all the dynamic types were to be deleted from that entry. The client must not expect any dynamic attributes to be present in an entry after the time-to-live for that entry has reached zero. However the attributes may not disappear immediately as servers may only process timing out attributes at intervals (e.g. every few minutes). Note that if an object class definition references a dynamic attribute as a mandatory attribute, the entry will still time out, but a schema inconsistency will be present in that entry. (The objectClass attribute and its values always remain since objectClass is not a dynamic attribute.) Thus it is strongly recommended that designers not specify dynamic attributes as anything other than optional attributes of auxiliary classes. Dynamic attributes may be used within dynamic entries (i.e., entries containing object class "dynamicObject", defined below), but since all of such an entry's attributes are implicitly dynamic, such use is superfluous. 5. Protocol Additions 5.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 or the dynamic attributes of the entry are 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. Clients 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 or the dynamic attributes may disappear, and the client will need to detect this and re-add the entry or the attributes. 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 } 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 } The entryName field is the UTF-8 string representation of the name of the dynamic entry or the entry containing dynamic attributes [3]. This entry must already exist. The requestTtl is a time in seconds (between 1 and 31557600) that the client requests that the entry or the dynamic attributes 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. 5.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 { responseName [0] LDAPOID OPTIONAL, response [1] OCTET STRING OPTIONAL, standardResponse [2] LDAPResult } 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. Please note that for the case of a static entry with dynamic attributes, this time-to-live applies to all the dynamic attributes in this entry. 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, or does not have dynamic attributes, the errorCode field will contain "objectClassViolation". If the requester does not have permission to refresh the entry, the 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. 6. 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 or the static entry with dynamic attributes 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 or an entry that contains dynamic attributes. The attribute is not present when the entry does not contain the dynamicObject object class or dynamic attributes. The value of this attribute is the time in seconds that the entry or the dynamic attributes in a static entry will continue to exist 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 'Integer' SINGLE-VALUE NO-USER-MODIFICATION USAGE dSAOperation ) 7. Client and Server Requirements 7.1 Client Requirements 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. The same holds true for keeping dynamic attributes present on a static entry. Clients must not expect that a dynamic entry will be present in the DIT after it has timed out, however it must not either 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. Again, dynamic attributes behave the same: they will not be present in the DIT after they timed out, but the client should not require their immediate removal. 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. Since the AddRequest 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 or for static entries to which they did not add dynamic attributes. Please note that when a client refreshes a static entry to which it added dynamic attribute(s), it refreshes ALL the dynamic attributes in this entry, including ones added by other clients. Also note that servers which allow anonymous clients to create and refresh dynamic entries and attributes will not be able to enforce the above. Clients should always be ready to handle the case in which their entry or dynamic attributes 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 or re-add the dynamic attributes. 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. 7.2 Server Requirements Servers are responsible for removing dynamic entries and dynamic attributes when they time out. Servers are not required to do this immediately. Servers must enforce the structural rules listed in above section 4. Servers must ensure that the operational attribute described in section 6 is present in dynamic entries or in static entries that contain dynamic attributes. Servers are permitted to check the authentication of the client invoking a refresh extended operation, and only permit the operation if it matches that of the client which created the dynamic entry or added dynamic attributes to this entry (please see a note about that in section 7.1). Servers may permit anonymous users to refresh entries. Servers may require that a client which attempts to create a dynamic entry have a remove permission for that entry. Servers which implement this extension must have the OBJECT IDENTIFIERs, described above in section 5 for the request and response, present as values 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 6. An implementation of dynamic directories, must be able to support both dynamic directory entries and dynamic attributes. 8. Implementation issues 8.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. Such a server might still support setting dynamic attributes on a static entry. 8.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). 9. Localization The are no localization issues for this extended operation. 10. Security Considerations Security issues are not addressed in this document. Please note, though, that anonymous clients are able to refresh entries which they did not create. 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. 12. Authors Addresses Yoram Yaacovi Microsoft One Microsoft way Redmond, WA 98052 USA Phone: +1 206-936-9629 EMail: yoramy@microsoft.com Mark Wahl Critical Angle Inc. 4815 W. Braker Lane #502-385 Austin, TX 78759 USA EMail: M.Wahl@critical-angle.com Kent Settle Microsoft One Microsoft way Redmond, WA 98052 USA Phone: +1 206-936-3027 EMail: kentse@microsoft.com Tony Genovese Microsoft One Microsoft way Redmond, WA 98052 USA Phone: +1 206-703-0852 EMail: tonyg@microsoft.com 13. Bibliography [1] M.Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol (Version 3)". INTERNET DRAFT [2] M.Wahl, A.Coulbeck, T. Howes, S. Kille, "Lightweight Directory Access Protocol Standard and Pilot Attributes". INTERNET DRAFT [3] M.Wahl, S.Kille, "Lightweight Directory Access Protocol UTF-8 String Representation of Distinguished Names". INTERNET DRAFT Expires on six months from the post date (see top).