IETF LDAPEXT Working Group                                Roland Hedberg
Internet-Draft                                                 Catalogix
Expires: January 12, 2000                                  July 12, 2000
                                                         




                    Referrals in LDAP Directories
                  <draft-ietf-ldapext-refer-00.txt>




Status of this Memo

   This document is an Internet-Draft and is in full conformance with
   all provisions of Section 10 of RFC2026.

   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."


     The list of current Internet-Drafts can be accessed at
     http://www.ietf.org/ietf/1id-abstracts.txt

     The list of Internet-Draft Shadow Directories can be accessed at
     http://www.ietf.org/shadow.html.


   This Internet-Draft will expire on January 12, 2000.

Copyright Notice

   Copyright (C) The Internet Society (2000). All Rights Reserved.
                         











Hedberg           Expires September 30, 2000                   [Page 1]

Internet-Draft    LDAP Knowledge references                   July 2000

Abstract

   This document defines two reference attributes and associated "referral"
   object class for representing generic knowledge information in LDAP
   directories [RFC2251].
   The attribute uses URIs [RFC1738] to represent knowledge,
   enabling LDAP and non-LDAP services alike to be referenced.
   The object class can be used to construct entries in an LDAP directory
   containing references to other directories or services. This document
   also defines procedures directory servers should follow when supporting
   these schema elements and when responding to requests for which the
   directory server does not contain the requested object but may contain
   some knowledge of the location of the requested object.


1.  Background and intended usage

   The broadening of interest in LDAP directories beyond their use as front
   ends to X.500 directories has created a need to represent knowledge
   information in a more general way. Knowledge information is information
   about one or more servers maintained in another server, used to link
   servers and services together.
                     
   This document is based on the following basic assumptions:

   - several naming domains
   The usage of LDAP as a access protocol to other than X.500 servers has
   created islands of directory service systems containing one or more
   LDAP servers. Each of these islands are free to pick their own naming
   domain. And that they also do; some use the old country,organization,
   organizationalUnit naming scheme[X.521], some use the newer domain name
   based naming scheme but these two are in no way the only ones in use. The
   existence of several naming domains are in itself no real problem as
   long as they produce unique names for the objects in the directory.
   Still naming schemes like the domain name based one, might easily create
   non-continues naming structures because some toplevel domain names
   might no find organizations that are interested and/or willing
   to manage them. Therefor tree transversal might not longer be possible
   except in parts of the whole tree.
      
   - authoritive structure vs directory structure
   In some instances even if a part of the tree is delegated to one
   organization, the organization doing the delegation might want to
   remain as the authority for the baseobject of the delegated tree.

   - support for onelevel searches
   At points in the tree where the responsibility for all or almost all
   of the children of a object is delegated to different organizations
   and resides in different directory servers a one-level search is not
   very efficient if not supported by special facilities in the directory
   as such.

Hedberg           Expires September 30, 2000                    [Page 2]

Internet-Draft    LDAP Knowledge references                   July 2000

   -- directory server discovery
   LDAP servers that do not use dc nameing or are not registered with
   SRV records in the DNS are very hard to find.

   This document defines a general method of representing knowledge
   information in LDAP directories, based on URIs.
   Two types of knowledge reference are defined: refer and subRefer.

   The key words "MUST", "SHOULD", and "MAY" used in this document are to
   be interpreted as described in [RFC2119].

2. Knowledge references

2.1 The refer attribute

   ( 1.2.752.17.1.100
     NAME 'refer'
     DESC 'URL reference'
     EQUALITY caseExactIA5Match
     SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
     USAGE distributedOperation )

   The refer attribute type has IA5 syntax and is case sensitive.
   It is multivalued. Values placed in the attribute MUST conform to the
   specification given for the labeledURI attribute as defined in [RFC2079].

   The labeledURI specification defines a format that is a URI,
   optionally followed by whitespace and a label. This document does not
   make use of the label portion of the syntax. Future documents MAY enable
   new functionality by imposing additional structure on the label portion
   of the syntax as it appears in a refer attribute.
   If the URI contained in a refer attribute refers to an LDAP
   server, it must be in the LDAP URI format described in [RFC2255].

   When returning a referral result, the server must not return the label
   portion of the labeledURI as part of the referral. Only the URI portion
   of the refer attributes should be returned.

   The refer attribute can be further specified by the use of options as
   defined in section 4.1.5 of [RFC2251]. This document defines five
   options and their use. Future documents might defined other options.

   The options defined are:
  "me", "sup", "cross", "nssr" and "sub" .

   'refer;me' is used to hold the reference of this server, and is always
   held in the root DSE

   'refer;sup' is used to hold the reference of a server superior to this
   one in this global LDAP naming domain e.g. a server holding the dc=com,
   dc=se, or the c=se node. The 'refer;sup' is always held in the root DSE.

Hedberg           Expires September 30, 2000                    [Page 3]

Internet-Draft    LDAP Knowledge references                   July 2000

   'refer;cross' indicates that this is a cross reference pointing to another
   naming context within or outside this global LDAP naming domain.

   'refer;sub' indicates that this is a subordinate reference pointing to
   a subordinate naming context in this global LDAP naming domain.

   'refer;nssr' indicates that this is a non-specific subordinate reference
   pointing to a subordinate naming context in this global LDAP naming domain.


3. Use of the knowledge attribute

   Except when the manageDsaIT control (documented in section 6 of this
   document) is present in the operation request, the refer attribute is not
   visible to clients, except as its value is returned in referrals or con-
   tinuation references.

   If the manageDsaIT control is not set, and the entry named in a request
   contains the refer attribute, and the entry is not the root DSE, the
   server returns an LDAPResult with the resultCode field set to "referral"
   and the referral field set to contain the value(s) of the refer attribute
   minus any optional trailing whitespace and labels that might be present.

   If the manageDsaIT control is not set, and an entry containing the ref
   attribute is in the scope of a one level or subtree search request, the
   server returns a SearchResultReference for each such entry containing
   the value(s) of the entry's refer attribute.

   When the manageDsaIT control is present in a request, the server will
   treat an entry containing the refer attribute as an ordinary entry, and
   the refer attribute as an ordinary attribute, and the server will not
   return referrals or continuation references corresponding to refer
   attributes.


4 Behaviour specification

4.1 Name resolution for any operation

   Clients SHOULD perform at least simple "depth-of-referral count" loop
   detection by incrementing a counter each time a new set of referrals is
   received. (The maximum value for this count SHOULD be twice the number
   of RDNs in the target object less one, to allow for ascending and
   descending the DIT.) Clients MAY perform more sophisticated loop
   detection, for example not chasing the same referral twice.

   Case 1: The target entry is not held by the server and is
   superior to some entry held by the server.

   If the server DSE contains a "refer;sup" attribute then
   the server will return an LDAPResult with the result code field set

Hedberg           Expires September 30, 2000                    [Page 4]

Internet-Draft    LDAP Knowledge references                   July 2000

   to referral, and the referral field set to contain the value(s) of
   the "refer;sup" attribute minus any optional trailing whitespace and
   labels that might be present.

   Case 2: The target entry is not held by the server and is
   subordinate to some entry, held by the server, that contains a
   refer attribute.

   The server will return an LDAPResult with the result code field set
   to referral, and the referral field set to contain the value(s) of
   the refer attribute minus any optional trailing whitespace and labels
   that might be present.

   Case 3: The target entry is held by the server and contains a
   refer attribute without the 'nssr' option.

   The server will return an LDAPResult with the result code field set
   to referral, and the referral field set to contain the value(s) of
   the refer attribute minus any optional trailing whitespace and labels
   that might be present.

   Case 4: The target entry is not held by the server, and is not
   subordinate or superior to any object held by the server.

   If the server contains a "refer;cross" attribute
   in the root DSE with a baseobject that is either the same or
   superior to the target entry then
   the server will return an LDAPResult with the result code field set
   to referral, and the referral field set to contain the value(s) of
   these refer attributes minus any optional trailing whitespace and labels
   that might be present.


4.2 Search evaluation

   For search operations, once the base object has been found and
   determined NOT to contain a refer attribute without the 'nssr'
   option, the search may progress.

4.2.1 base-level

   If the entry matches the filter and does NOT contain a refer attribute
   it will be returned to the client as described in [RFC2251].
   If the entry matches the filter contains a refer attribute without
   the 'nssr' option it will be returned as a referral as described here.

   If a matching entry contains a refer attribute and the URI
   contained in the refer attribute is NOT an LDAP URI [RFC2255],
   the server should return the URI value contained in the refer
   attribute of that entry in a SearchResultReference.
        

Hedberg           Expires September 30, 2000                    [Page 5]

Internet-Draft    LDAP Knowledge references                   July 2000


   If a matching entry contains a refer attribute in the LDAP
   URI syntax, the server will return an SearchResultReference
   containing the value(s) of the refer attribute minus any optional
   trailing whitespace and labels that might be present.
   The URL from the refer attribute must be modified before it is
   returned by adding or substituting a "base" scope into the URL. If the
   URL does not contain a scope specifier, the "base" scope specifier must
   be added. If the URL does contain a scope specifier, the existing scope
   specifier must be replaced by the "base" scope.

4.2.2 One-level

   Any entries matching the filter and one level scope that
   do NOT contain a refer attribute are returned to the client normally as
   described in [RFC2251]. Any entries matching the filter and one level
   scope that contains a refer attribute without the 'nssr' option must
   be returned as referrals as described here.

   If a matching entry contains a refer attribute and the URI
   contained in the refer attribute is NOT an LDAP URI [RFC2255],
   the server should return the URI value contained in the refer
   attribute of that entry in a SearchResultReference.
        
   If a matching entry contains a refer attribute in the LDAP
   URI syntax, the server will return an SearchResultReference
   containing the value(s) of the refer attribute minus any optional
   trailing whitespace and labels that might be present.
   The URL from the refer attribute must be modified before it is
   returned by adding or substituting a "base" scope into the URL. If the
   URL does not contain a scope specifier, the "base" scope specifier must
   be added. If the URL does contain a scope specifier, the existing scope
   specifier must be replaced by the "base" scope.

4.2.3 Subtree search evaluation

   Any entries, held by the server, matching the filter and
   subtree scope that do NOT contain a refer attribute or contains
   a refer attribute with the 'nssr' option are
   returned to the client normally as described in [RFC2251].
   Any entries matching the subtree scope and containing a refer
   attribute must be returned as referrals as described here.

   If a matching entry contains a refer attribute and the URI
   contained in that attribute is NOT an LDAP URI [RFC2255],
   the server should return the URI value contained in the refer
   attribute of that entry in a SearchResultReference.
 




Hedberg           Expires September 30, 2000                    [Page 6]

Internet-Draft    LDAP Knowledge references                   July 2000

   If a matching entry contains a refer attribute in the LDAP
   URI syntax, the server will return an SearchResultReference
   containing the value(s) of the refer attribute minus any
   optional trailing whitespace and labels that might be present.

   N.B. in subtree search evaluation a entry containing a 
   refer attribut with the 'nssr' option might appear twice in the
   result, first as a entry and then as a reference. A client
   following all references might therefore end up with a resultset
   containing two representations of the same entry, one from the
   server getting the original query and one from the server 
   that the 'nssr' reference points to.


5. The referral object class

   The referral object class is defined as follows.

   ( 1.2.752.17.2.10
     NAME 'referral'
     SUP top
     STRUCTURAL
     MAY ( refer ) )

   The referral object class is a subclass of top and may contain the
   refer attribute. The referral object class should, in general,
   be used in conjunction with the extensibleObject object class to support
   the naming attributes used in the entry's distinguished name.

   Servers must support the refer attributes through use of the
   referral object class. Any named reference must be of the referral
   object class and will likely also be of the extensibleObject object
   class to support naming and use of other attributes.


6. The manageDsaIT control

   A client MAY specify the following control when issuing a search, com-
   pare, add, delete, modify, or modifyDN request.

   The control type is 2.16.840.1.113730.3.4.2.  The control SHOULD be
   marked as critical.  There is no value; the controlValue field is
   absent.

   This control causes entries with the knowledge reference attributes to be
   treated as normal entries, allowing clients to read and modify these entries.






Hedberg           Expires September 30, 2000                    [Page 7]

Internet-Draft    LDAP Knowledge references                   July 2000


7. Superior Reference

   This document defines two types of knowledge references that point to
   parts of the naming context that is above of beyone the part held by a server.
   The 'sup' option when referring to a LDAP server that holds a
   naming context that is closer to the root of the same naming context and
   'other' when referring to a LDAP server that holds a naming
   context that belongs to a different naming domain then the one the
   server belongs to.

   Thus if the server receives a request for an operation where the
   target entry is a entry closer to the root than the naming
   context held the server and if the server holds a 'refer;sup' attribute
   in the DSE, then the server MUST return an LDAPResult with the result
   code field set to referral, and the referral field set to contain the
   value(s) of the 'refer;sub' attribute minus any optional trailing
   whitespace and labels that might be present.

   On the other hand if the server receives a request for an operation
   where the target entry is a entry that belongs to a other naming domain
   and if there is any 'refer;other' attributes in the DSE with a base entry
   that belongs to the same naming domain as the target entry and is
   closer to the root then the target entry, then the server SHOULD return
   an LDAPResult with the result code field set to referral, and the referral
   field set to contain the value(s) of the 'refer;other' attribute minus
   any optional trailing hitespace and labels that might be present.


8. Security Considerations

   This document defines mechanisms that can be used to "glue" LDAP (and
   other) servers together. The information used to specify this glue
   information should be protected from unauthorized modification.  If the
   server topology information itself is not public information, the
   information should be protected from unauthorized access as well.


9. References

   [RFC1738]
    Berners-Lee, T., Masinter, L., and McCahill, M., "Uniform Resource
    Locators (URL)", RFC 1738, CERN, Xerox Corporation, University of
    Minnesota, December 1994,

   [RFC2079]
    M. Smith, "Definition of an X.500 Attribute Type and an Object Class
    to Hold Uniform Resource Identifiers (URIs)", RFC 2079, January
    1997.



Hedberg           Expires September 30, 2000                    [Page 8]

Internet-Draft    LDAP Knowledge references                   July 2000


   [RFC2119]
    S. Bradner, "Key Words for use in RFCs to Indicate Requirement Lev-
    els", RFC 2119, March 1997. (Format: TXT=4723 bytes) (Also BCP0014)
    (Status: BEST CURRENT PRACTICE)

   [RFC2251]
    M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
    (v3)", RFC 2251, December 1997.  1997.

   [RFC2255]
    T. Howes, M. Smith, "The LDAP URL Format", RFC 2255, December, 1997.
    (Format: TXT=20685 bytes) (Status: PROPOSED STANDARD)

   [X500]
    ITU-T Rec. X.501, "The Directory: Models", 1993.

   [X521]
    ITU-T Rec. X.521, "---------------------", 1993.


12. Acknowledgements

   This draft is heavily based on the previous drafts on knowledge
   references in LDAP written by Christopher Lukas, Tim Howes,
   Michael Roszkowski, Mark C. Smith, Mark Wahl and David Chadwick.
   Peter Valkenburg and Henny Bekker has also made valueable
   contributions.


13. Authors Address

   Roland Hedberg
   Catalogix
   Dalsveien 53
   0775 Oslo
   Norway
   EMail: Roland@catalogix.se














Hedberg           Expires September 30, 2000                    [Page 9]

Internet-Draft    LDAP Knowledge references                   July 2000


   Appendix A

   Example of usage.
   Information stored in a server.

     dn:
     objectclass: referral
     refer;me: ldap://hostCAT/dc=cat,dc=se
     refer;sup: ldap://hostSE/dc=se
     refer;cross: ldap://hostNO/dc=no
     refer;cross: ldap://hostNL/c=nl
   
     dn: dc=cat,dc=se
     objectclass: domain
     dc: cat
   
     dn: dc=one,dc=cat,dc=se
     objectclass: extendedObject
     objectclass: referral
     refer;nssr: ldap://hostCAT1/dc=one,dc=cat,dc=se
     ou: one
     l: umea
   
     dc: dc=two,dc=cat,dc=se
     objectclass: referral
     objectclass: extendedObject
     refer;sub: ldap://hostCAT2/dc=two,dc=cat,dc=se
   
     dn: dc=three,dc=cat,dc=se
     objectclass: referral
     objectclass: extendedObject
     refer;cross: ldap://hostCAT3/dc=cat,dc=nl
   
     dc: dc=four,dc=cat,dc=se
     objectclass: domain
     objectclass: extendedObject
     ou: four
     l: umea













Hedberg           Expires September 30, 2000                    [Page 10]

Internet-Draft    LDAP Knowledge references                   July 2000


   ==========================================
      A number of descriptive cases
   ==========================================

   case 1: One-level search, target object on the server
     search
       baseobject: dc=cat,dc=se
       scope:      onelevel
       filter:     (objectclass=*)
       attributes: ou

     returns
       searchResultEntry {
         dn: dc=one,dc=cat,dc=se
         ou: one
       }
       searchResultReference {
         ldapurl: ldap://hostCAT2/dc=two,dc=cat,dc=se
       }
       searchResultReference {
         ldapurl: ldap://hostCAT3/dc=cat,dc=nl
       }
       searchResultEntry {
         dn: dc=four,dc=cat,dc=se
         ou: four
       }
       searchResultDone {
         resultCode: success
       }

   case 2: Subtree search, target object on the server
     search
       baseobject: dc=cat,dc=se
       scope:      subtree
       filter:     (objectclass=*)
       attributes: ou
   
     returns
       searchResultEntry {
         dn: dc=one,dc=cat,dc=se
         ou: one
       }
       searchResultReference {
         ldapurl: ldap://hostCAT1/dc=one,dc=cat,dc=se
       }
       searchResultReference {
         ldapurl: ldap://hostCAT2/dc=two,dc=cat,dc=se
       }



Hedberg           Expires September 30, 2000                  [Page 11]

Internet-Draft    LDAP Knowledge references                   July 2000


       searchResultReference {
         ldapurl: ldap://hostCAT3/dc=cat,dc=nl
       }
       searchResultEntry {
         dn: dc=four,dc=cat,dc=se
         ou: four
       }
       searchResultDone {
         resultCode: success
       }

   case 3: base search, target entry contains a 'refer;nssr' attribute
     search
       baseobject: dc=one,dc=cat,dc=se
       scope:      base
       filter:     (objectclass=*)
       attributes: ou
   
     returns
       searchResultEntry {
         dn: dc=one,dc=cat,dc=se
         ou: four
       }
       searchResultDone {
         resultCode: success
       }

   case 4: base search, target entry contains a 'refer;sub' attribute
     search
       baseobject: dc=two,dc=cat,dc=se
       scope:      base
       filter:     (objectclass=*)
       attributes: ou

     returns
       searchResultDone {
         resultCode: referral
         matchedDN: dc=two,dc=cat,dc=se
         referral: ldap://hostCAT2/dc=two,dc=cat,dc=se
       }











Hedberg           Expires September 30, 2000                    [Page 12]

Internet-Draft    LDAP Knowledge references                   July 2000


  case 5: one-level search, target entry contains a 'refer;nssr' attribute
     search
       baseobject: dc=one,dc=cat,dc=se
       scope:      onelevel
       filter:     (objectclass=*)
       attributes: ou
   
       searchResultDone {
         resultCode: referral
         matchedDN: dc=one,dc=cat,dc=se
         referral: ldap://hostCAT1/dc=one,dc=cat,dc=nu
       }
   
  case 6: Search on area above the baseobject of the server
     search
       baseobject: dc=pi,dc=se
       scope:      subtree
       filter:     (objectclass=*)
       attributes: ou
   
     returns
       searchResultDone {
         resultCode: referral
         matchedDN:  dc=se
         referral:   ldap://hostSE/dc=se
      }



  case 7: Search on area beyond, but not below the baseobject
        of the server
     search
       baseobject: o=surfnet,c=nl
       scope:      base
       filter:     (objectclass=*)
   
     returns
       searchResultDone {
         resultCode: referral
         matchedDN:  c=nl
         referral:   ldap://hostNL/c=NL
       }









Hedberg           Expires September 30, 2000                    [Page 13]

