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