RFC 2589

Lightweight Directory Access Protocol (v3): Extensions for Dynamic Directory Services

📅 published May 1999, from ietf

RFC 2589: Lightweight Directory Access Protocol (v3): Extensions for Dynamic Directory Services ✨

okay bestie, this is RFC 2589 🦋 and it's from May 1999. It's a Standards Track doc 🎀, so it's an actual Internet standards-track protocol spec. It was written by Y. Yaacovi (Microsoft), M. Wahl (Innosoft International, Inc.), and T. Genovese (Microsoft) 💜. It doesn't obsolete or update any other RFC, so it's a fresh start 🌸.

Status of this Memo ✨

okay so this one is an Internet standards track protocol for the whole Internet community 🌈, and it's open for discussion and suggestions for improvements 💬. If you want to know where it stands on the standardization ladder, check the current edition of the "Internet Official Protocol Standards" (STD 1) 📖. And the distribution of this memo is unlimited, so share it with everyone 🫶.

Copyright (C) The Internet Society (1999). All Rights Reserved. 🔒

1. Abstract 🌸

so the vibe of this doc is that it defines what dynamic directory services need and lays out the request and response format for extended operations 🎀. Those extended operations are how a client and a server talk to each other in a dynamic directory environment, and honestly it's giving main character energy 👑.

the Lightweight Directory Access Protocol (LDAP) [1] is the base here 🧚. LDAP gives you lightweight access to static directory services, which means quick searching and updating ⚡. Static directory services hold info about people that stays accurate and useful for a long time 📚.

dynamic directory services are the twist 🌀. They hold info that's only accurate while it keeps getting refreshed 🔄. This info lives in the directory as dynamic entries 💖. Most of the time it's a client, or a person, who's either online (so they have an entry in the directory) or offline (so their entry is gone) 🟢⚫.

the protocol operations and attributes are pretty similar to the static ones, but clients that store dynamic info have to keep refreshing it periodically so it doesn't disappear 😭. If a dynamic entry isn't refreshed within its timeout, it gets removed from the directory 🗑️. Like, if the client that set it goes offline, that's exactly what happens 🙈.

also, the server can send a flow control mechanism 🚦 that tells clients how often they should refresh their presence 💜.

2. Requirements 📋

the extensions must let you access dynamic info in a directory in a standard LDAP way 🎀, so clients can reach static and dynamic info the same way. no extra steps, no drama ✨.

dynamic entries aren't persistent by definition 🫠, and clients might leave gracefully or not at all 👋. So the extensions must give the server a way to tell if entries are still valid 🔍, and it has to scale 📈. There also must be a mechanism for clients to re-establish their entry with the server 🔁.

clients need a way to find out, in a standard LDAP way, whether servers support the dynamic extensions 🕵️‍♀️.

and last but not least, so clients can actually use the dynamic extensions broadly 🌍, the extensions need to be registered as standard LDAP extended operations 📝. ugh, it's a whole vibe 💅.

3. Description of Approach 🦋

LDAP [1] lets you add extra operation requests and responses to the protocol 🧩. This proposal uses that to support directories with dynamic info in a way that's fully integrated with LDAP 💞.

the approach defines dynamic entries so you can build directories with dynamic info 🏗️. 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 that has a time-to-live attached to it ⏳. That time-to-live gets set when the entry is created ⏰. It gets automatically decremented, and when it expires, the dynamic entry disappears 💨. To keep it around a little longer, a client invokes the refresh extended operation (defined below) to reset the time-to-live 🔄. so the client is in charge of its own survival, bestie 💪.

a dynamic entry gets created by including the objectClass value given in section 5 in the list of attributes when you add an entry 🧾. standard access control restrictions apply to this, so no sneaking 🕶️.

the extended operation here lets a client refresh a dynamic entry by invoking refresh operations at intervals, each one containing that entry's name 🔁. dynamic entries get treated the same as non-dynamic ones for search, compare, add, delete, modify, and modifyDN operations 🤝. BUT if clients stop sending refresh operations for an entry, the server will automatically and without notification remove that entry from the directory 💀. That removal counts the same as if the entry was deleted by an LDAP protocol operation 🫥.

you can't turn a static entry into a dynamic one or the other way around 🚫. If a client uses Modify with an objectClass of dynamicObject on a static entry, the server must return a service error. It's either objectClassModsProhibited (if the server doesn't allow objectClass modifications at all) or objectClassViolation (if the server does allow objectClass modifications in general) ⚠️.

a dynamic entry can be removed by the client with the delete operation 🗑️. That operation is subject to access control restrictions 🔐.

a non-dynamic entry cannot be added subordinate to a dynamic entry 🙅‍♀️. If someone tries, the server must return an appropriate update or service error 🚨.

and the support of dynamic attributes on an otherwise static object is outside the scope of this document 🤷‍♀️, so that's a different story 📕.

3.2 Dynamic meetings (conferences) 🎉

so the way dynamicObject is defined, it has a time-to-live attached to it, and that's pretty much it 🫶. The most common dynamic object is a person object, but there's no specific type for dynamicObject as defined here 🌈. You can use the dynamic object's attributes to make it represent basically anything ✨.

meetings (conferences) can be represented by dynamic objects 📅. Full-featured meeting support needs special semantics and handling by the server, and that's not in this document's scope 🙅‍♀️. But the extensions here do give you basic meeting support 🎀. A meeting object can be refreshed by its participants, and when it's not refreshed, the meeting entry disappears 👻. The one meeting type that the dynamic extensions naturally support is the creator-owned meeting 👑.

3.2.1 Creator-owned meetings 💜

creator-owned meetings are created by a client that sets the time-to-live attribute for the entry 🧁. That client is responsible for refreshing the meeting entry so it doesn't disappear 🫡. Other people can join the meeting by modifying the appropriate attribute, but they aren't allowed to refresh the entry 🚫. When the creating client goes away, it can delete the meeting entry, or the entry might disappear once its time-to-live expires 🌙. This lines up with the common model for dynamicObject described above 💅.

4. Protocol Additions 🧚

4.1 Refresh Request 💖

okay, refresh is a protocol operation a client sends to tell the server it's still alive and that the dynamic directory entry is still accurate and valuable 🫶. The client sends Refresh requests periodically, based on the value of the client refresh period (CRP) ⏱️. The server can ask the client to change this value 🔧. As long as the server gets a Refresh request within the timeout period, the directory entry is guaranteed to persist on the server 🛡️.

client implementers should be aware that the network between the client and server is unreliable 🌪️. So a Refresh request packet may be delayed or lost while in transit 📦. If that happens, 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 like this:

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 holds, as its 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 [3] 🏷️. This entry must already exist 👀.

the requestTtl is a time in seconds (between 1 and 31557600) that the client asks the entry to exist in the directory before it's automatically removed ⏳. Servers are not required to accept this value, and they might return a different TTL value to the client 🙃. Clients must be able to use this server-dictated value as their CRP 💅. that's the whole vibe, bestie 🎀✨

4.2 Refresh Response ✨

okay so if a server supports this extension, it's going to send back an LDAP PDU with an ExtendedResponse when the request comes in 💅 The ExtendedResponse is defined like this:

    ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
            COMPONENTS OF LDAPResult,
            responseName     [10] LDAPOID OPTIONAL,
            response         [11] OCTET STRING OPTIONAL }

the responseName field has the same string that was in the request, so the two lineup perfectly 🎀

the response field holds a value that's the DER-encoding of this ASN.1 data type:

     SEQUENCE {
             responseTtl [1] INTEGER
     }

the responseTtl field is the number of seconds the server picks as the time-to-live for that entry ⏳ it can't be any smaller than what the client asked for, but it can be bigger. the twist is that servers are allowed to shorten a client's requested TTL to keep the directory accurate and stop clients from abusing the dynamic extensions 🙈 the floor for that shortening is 86400 seconds, which is one whole day.

if the operation worked, the errorCode field in the standardResponse part of the ExtendedResponse gets set to success 🎉

if something goes wrong, responseTtl is 0 and errorCode says what happened:

  • if the entry named by entryName can't be found, the errorCode is "noSuchObject" 👀
  • if the entry isn't dynamic, the errorCode is "objectClassViolation"
  • if the requester isn't allowed to refresh the entry, the errorCode is "insufficientAccessRights"
  • if the requestTtl field is too large, the errorCode is "sizeLimitExceeded"

if a server doesn't implement this extension, it sends back an LDAP PDU with an ExtendedResponse that only has the standardResponse element. the responseName and response elements are missing. the LDAPResult says protocolError 💀

this request is allowed to be used when LDAP rides on a connectionless transport 🦋

with a connection-oriented transport, there's no rule saying this operation has to happen on the same connection as anything else. a client can open multiple connections, or close one and reopen it. totally fine, no drama 🫶

4.3 X.500/DAP Modify(97)

okay bestie, X.500/DAP servers can map the Refresh request and response operations onto the X.500/DAP Modify(97) operation 🧚

5. Schema Additions

every dynamic entry needs the dynamicObject value in its objectClass attribute 💜 this object class is defined like this, using the ObjectClassDescription notation from [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 )

on top of that, the dynamic entry also has to have this operational attribute. it's described using the AttributeTypeDescription notation from [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
          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 )

so to let servers support dynamic entries in only part of the DIT, there's another operational attribute called dynamicSubtrees 🌸 it's described using the AttributeTypeDescription notation from [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 check if a server supports the dynamic extensions by looking at the supportedExtension field in the root DSE and seeing if the OBJECT IDENTIFIER from section 4 is there 🔍 servers can pick which subtrees they support the dynamic extensions in, so clients also have to check the dynamicSubtrees operational attribute in the root DSE to see whether a specific subtree is covered 🧐

once a dynamic entry has been created, clients are the ones in charge of calling the refresh extended operation, so the entry stays in the directory 💖

clients can't count on a dynamic entry still being there after it times out 💀 but they also can't make the server delete it right away, because some servers only clean up timed-out entries every so often. if a client wants to be sure an entry is gone, it should send a RemoveRequest for that entry 🗑️

a client needs to know how often to send refresh requests. that value is the CRP (Client Refresh Period), and the server sets it based on the entryTtl ⏰

the LDAP AddRequest operation is unchanged in this proposal and doesn't return this value, so a client has to send a Refresh extended operation right after an Add that created a dynamic entry 🚀 the Refresh Response then gives the client the CRP in responseTtl.

clients must not send refresh requests for dynamic entries they didn't create 🙅‍♀️ if an anonymous client tries anyway, a server is allowed to return insufficientAccessRights (50) in the RefreshResponse, which forces the client to bind first. heads up though: servers that let anonymous clients create and refresh dynamic entries can't enforce any of that 😬

clients should always be ready for the case where their entry timed out. then the Refresh fails with an error like noSuchObject, and the client is expected to re-create its entry 🔁

clients should also be ready for refresh operations to fail with protocolError, even if the add and every earlier refresh worked. this can happen if a proxy between the client and the server goes down and a different proxy is used that doesn't support the Refresh extended operation 🌈

6.2 Server Requirements

servers are in charge of removing dynamic entries when they time out 🧹 they don't have to do it immediately.

servers have to enforce the structural rules listed in above section 3 👑

servers have to make sure the operational attribute from section 5 is present in dynamic entries

servers can let anonymous users refresh entries ✨ but to rule out malicious use of the Refresh operation, servers can also require the refreshing client to bind first. one way to do that is to put ACLs on the entryTtl attribute and return insufficientAccessRights (50) in the RefreshResponse when the client isn't allowed to refresh the entry. just know that doing this could affect server performance and scalability 🙈

servers can require that a client trying to create a dynamic entry has remove permission for that entry 🔐

servers that implement the dynamic extensions have to have the OBJECT IDENTIFIER from section 4 (for the request and response) as a value of the supportedExtension field in the root DSE. they also have to have the AttributeTypeDescription and ObjectClassDescription from section 5 as values in the attributeTypes and objectClasses attributes of their subschema subentries 📚

servers can limit dynamic extension support to only some subtrees in the DIT. to show which subtrees they cover, they list the OIDs of the supported subtrees in the dynamicSubtrees attribute from section 5 🌳 if a server supports the dynamic extensions for every naming context it holds, the dynamicSubtrees attribute can be left out.

7. Implementation issues

7.1 Storage of dynamic information

dynamic info changes super often, and refresh requests show up at the server super often too 🔥 the disk-based databases that static directory services usually use probably aren't a good fit for storing dynamic information 💀 we recommend that server implementations keep dynamic entries in memory, enough to avoid paging. this isn't a requirement, just a vibe check 💅

we expect LDAP servers to be able to store static and dynamic entries together 🫶 if an LDAP server doesn't support dynamic entries, it should respond with an error like objectClassViolation.

7.2 Client refresh behavior

sometimes a client won't get a Refresh response back 😭 that could happen if the server crashes after getting the Refresh request, if the TCP/IP socket times out in the connection case, or if the UDP packet gets lost in the connectionless case.

in that situation, it's recommended that the client retries the Refresh operation right away. if that retry doesn't get a response either, the client goes back to its original Refresh cycle and sends a Refresh request at its Client Refresh Period (CRP) 🦋

7.3 Configuration of refresh times

we recommend that servers give administrators the ability to configure the default client refresh period (CRP), plus a minimum and maximum CRP. admins can also ask the server not to change the CRP dynamically 👑 with those options, admins can pick a setup with low refresh traffic, or go all the way to the other end for a super up-to-date directory ⭐

8. Replication

replication is only partly covered in this memo 🌸 there's a separate effort going on at the IETF for replicating static and dynamic directories.

it's allowed to replicate a dynamic entry, or a static entry with dynamic attributes 🧚 since entryTtl is a relative time (how many seconds until the entry expires), replicating it means the replicated entry is "off" by the replication time ⏳

9. Localization

the are no localization issues for this extended operation 🌍

10. Security Considerations ✨

okay bestie, security time 🔐 the good news is that the standard LDAP security rules and support apply to these extensions too, so there are no special security issues just for this stuff 💖

but there are a couple of things to keep in mind 👀 servers might let anonymous clients refresh entries they didn't create. servers are also allowed to control refresh access to an entry by making clients bind before they send a RefreshRequest 🔒 that choice has implications for server performance and scalability, so it's a real tradeoff 💀

also, be careful with info that a client put into a directory server, because it may be out of date by the time you read it 🙈 for example, lots of networks auto-assign IP addresses when a host connects and reassign them when that host disconnects. so an IP address you grab from the directory might not belong to the host that originally posted it anymore 😭 this isn't just an LDAP or dynamic directory problem, it's a general vibe ✨

11. Acknowledgments 🫶

the design ideas in this document are based on the ones discussed in ASID and other IETF Working Groups 🌸 thank u to everyone who came before 🙏

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.

okay the legal part, and yes it matters 📜 this is the original wording, kept complete on purpose 💜

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 🌈 and that's a wrap on RFC 2589, periodt ✨

📦 where this page comes from