From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc2589.txt | 675 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 675 insertions(+) create mode 100644 doc/rfc/rfc2589.txt (limited to 'doc/rfc/rfc2589.txt') diff --git a/doc/rfc/rfc2589.txt b/doc/rfc/rfc2589.txt new file mode 100644 index 0000000..0023851 --- /dev/null +++ b/doc/rfc/rfc2589.txt @@ -0,0 +1,675 @@ + + + + + + +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] + -- cgit v1.2.3