--- /dev/null
+IETF LDAPEXT Working Group Christopher Lukas [Editor]
+INTERNET-DRAFT Internet Scout Project
+ Tim Howes
+ Netscape Communications Corp.
+ Michael Roszkowski
+ Internet Scout Project
+ Mark C. Smith
+ Netscape Communications Corp.
+ Mark Wahl
+ Critial Angle, Inc.
+ June 1999
+
+
+ Named Referrals in LDAP Directories
+ <draft-ietf-ldapext-namedref-00.txt>
+
+
+
+1. 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.
+
+Distribution of this document is unlimited. Please send comments to the
+authors or the LDAPEXT mailing list, ietf-ldapext@netscape.com.
+
+Copyright Notice: Copyright (C) The Internet Society (1999). All Rights
+Reserved.
+
+This draft is a revision of a draft formerly published as draft-ietf-
+ldapext-referral-00.txt.
+
+This draft expires December 6, 1999.
+
+
+
+Howes, et al. IETF LDAPEXT Working Group [Page 1]
+
+
+
+
+
+INTERNET-DRAFT LDAPv3 Named Referrals March 1999
+
+
+2. Abstract
+
+This document defines a "ref" attribute 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.
+
+3. 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 defines a general method of representing knowledge infor-
+mation in LDAP directories, based on URIs.
+
+The key words "MUST", "SHOULD", and "MAY" used in this document are to
+be interpreted as described in [RFC2119].
+
+4. The ref attribute type
+
+This section defines the ref attribute type for holding general
+knowledge reference information.
+
+( 2.16.840.1.113730.3.1.34 NAME 'ref' DESC 'URL reference'
+ EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
+ USAGE distributedOperation )
+
+The ref attribute type has IA5 syntax and is case sensitive. The ref
+attribute is multivalued. Values placed in the attribute MUST conform to
+the specification given for the labeledURI attribute 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 the ref attribute.
+
+If the URI contained in the ref attribute refers to an LDAPv3 server, it
+must be in the LDAP URI format described in [RFC2255].
+
+
+
+
+Howes, et al. IETF LDAPEXT Working Group [Page 2]
+
+
+
+
+
+INTERNET-DRAFT LDAPv3 Named Referrals March 1999
+
+
+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 ref attribute should be returned.
+
+5. Use of the ref attribute
+
+One usage of the ref attribute is defined in this document. Other uses
+of the ref attribute MAY be defined in subsequent documents, or by bila-
+teral agreement between cooperating clients and servers.
+
+Except when the manageDsaIT control (documented in section 8 of this
+document) is present in the operation request, the ref 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 ref 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 ref 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 ref attribute.
+
+When the manageDsaIT control is present in a request, the server will
+treat an entry containing the ref attribute as an ordinary entry, and
+the ref attribute as an ordinary attribute, and the server will not
+return referrals or continuation references corresponding to ref attri-
+butes.
+
+The following sections detail these usages of the ref attribute.
+
+5.1. Named reference
+
+This use of the ref attribute is to facilitate distributed name resolu-
+tion or search across multiple servers. The ref attribute appears in an
+entry named in the referencing server. The value of the ref attribute
+points to the corresponding entry maintained in the referenced server.
+
+While the distinguished name in a value of the ref attribute is typi-
+cally that of an entry in a naming context below the naming context held
+by the referencing server, it is permitted to be the distinguished name
+of any entry. If the ref attribute is multi-valued all the DNs in the
+values of the ref attribute SHOULD have the same value. It is the
+responsibility of clients to not loop repeatedly if a naming loop is
+present in the directory. Administrators SHOULD avoid configuring
+
+
+
+Howes, et al. IETF LDAPEXT Working Group [Page 3]
+
+
+
+
+
+INTERNET-DRAFT LDAPv3 Named Referrals March 1999
+
+
+naming loops using referrals.
+
+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. Clients MAY perform more sophisticated loop detection, for
+example not chasing the same URI twice.
+
+If an entry containing the ref attribute is immediately subordinate to
+the base object named in a one level search request, then the referring
+server MUST include a scope of "base" in any LDAP URIs returned in the
+corresponding SearchResultReference.
+
+5.1.1. Scenarios
+
+The following sections contain specifications of how the ref attribute
+should be used in different scenarios followed by examples that illus-
+trate that usage. The scenarios described consist of referral operation
+when finding a base or target object, referral operation when performing
+a one level search, and referral operation when performing a subtree
+search.
+
+It is to be noted that, in this document, a search operation is concep-
+tually divided into two distinct, sequential phases: (1) finding the
+base object where the search is to begin, and (2) performing the search
+itself. The operation of the server with respect to referrals in phase
+(1) is almost identical to the operation of the server while finding the
+target object for a non-search operation.
+
+It is to also be noted that multiple ref attributes are allowed in any
+entry and, where these sections refer to a single ref attribute, multi-
+ple ref attributes may be substituted and should be processed and
+returned as a group in an LDAPResult or search result in the same way as
+described for a single attribute. The order of the returned continuation
+references within a result is not defined.
+
+
+5.1.1.1. Example configuration
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Howes, et al. IETF LDAPEXT Working Group [Page 4]
+
+
+
+
+
+INTERNET-DRAFT LDAPv3 Named Referrals March 1999
+
+
+ |------------------------------------------------------------|
+ | Server A |
+ | dn: o=abc,c=us dn: o=xyz,c=us |
+ | o: abc o: xyz |
+ | ref: ldap://hostB/o=abc,c=us ref: ldap://hostD/o=xyz,c=us |
+ | ref: ldap://hostC/o=abc,c=us objectclass: referral |
+ | objectclass: referral objectclass: extensibleObject|
+ | objectclass: extensibleObject |
+ |____________________________________________________________|
+
+ |---------------------| |---------------------| |---------------------|
+ | Server B | | Server D | | Server C |
+ | dn: o=abc,c=us | | dn: o=xyz,c=us | | dn: o=abc,c=us |
+ | o: abc | | o: xyz | | o: abc |
+ | other attributes... | | other attributes... | | other attributes... |
+ |_____________________| |_____________________| |_____________________|
+
+In this example, Server A holds references for two entries: "o=abc,c=us"
+and "o=xyz,c=us". For the "o=abc,c=us" entry, Server A holds two refer-
+ences, one to Server B and one to Server C. The entries referenced are
+replicas of each other. For the "o=xyz,c=us" entry, Server A holds a
+single reference to the entry contained in Server D.
+
+In the following protocol interaction examples, the client has contacted
+Server A. Server A holds the naming context "c=us".
+
+5.1.1.2. Base or target object considerations
+
+As previously described, the process of generating referrals for a
+search can be described in two phases. The first, which is described in
+this section, is generating referrals based on the base object specified
+in the search. This process is identical to the process of generating
+referrals based on the target object while processing other operations
+(modify, add, delete, modify DN, and compare) with the sole exception
+that for these other operations, the DN in the referral must be modified
+in some cases.
+
+If a client requests any of these operations, there are four cases that
+the server must handle with respect to the base or target object speci-
+fied in the request.
+
+Case 1: The base or target object is not held by the server and is not
+subordinate to any object held by the server with a ref attribute.
+
+The handling of this case is described in section 6.
+
+Case 2: The base or target object is held by the server and contains a
+ref attribute
+
+
+
+Howes, et al. IETF LDAPEXT Working Group [Page 5]
+
+
+
+
+
+INTERNET-DRAFT LDAPv3 Named Referrals March 1999
+
+
+In this case, if the type of operation requested is a search or the URI
+contained in the ref attribute of the requested base object is NOT an
+LDAP URI as defined in [RFC2255], the server should return the URI value
+contained in the ref attribute of the base object whose DN is the DN
+requested by the client as the base for the operation.
+
+Example:
+
+If the client issues a search in which the base object is "o=xyz,c=us",
+server A will return
+
+ SearchResultDone "referral" {
+ ldap://hostD/o=xyz,c=us
+ }
+
+If the type of operation requested is not a search and the URI contained
+in the ref attribute of the requested target object is an LDAP URI
+[RFC2255], the server should return a modified form of this URL. The
+returned URL must have only the protocol, host, port, and trailing "/"
+portion of the URL contained in the ref attribute. The server should
+strip any dn, attributes, scope, and filter parts of the URL.
+
+Example:
+
+If the client issues a modify request for the target object of
+"o=abc,c=us", server A will return
+
+ ModifyResponse "referral" {
+ ldap://hostB/
+ ldap://hostC/
+ }
+
+Case 3: The base or target object is not held by the server, but is
+subordinate to an object with a ref attribute held by the server.
+
+
+If a client requests an operation for which the base or target object is
+not held by the server, but is subordinate to one or more objects with a
+ref attribute held by the server, the server must return the referral
+from the superior held object nearest to the requested base or target
+object. Nearest superior object with a referral, in this document, means
+an object superior to the base or target object with the DN that has the
+most attribute values in common with the DN of the base or target object
+and contains a ref attribute.
+
+The process of finding the nearest superior object can be envisioned as
+walking up the locally held part of the DIT from the requested base or
+target object checking each superior object until either an object with
+
+
+
+Howes, et al. IETF LDAPEXT Working Group [Page 6]
+
+
+
+
+
+INTERNET-DRAFT LDAPv3 Named Referrals March 1999
+
+
+a ref attribute is found or the top-most locally held object is reached.
+Once possible implementation of this algorithm is as follows:
+
+ 1. Remove the leftmost attribute/value pair from the DN of the
+ requested base or target object.
+ 2. If the remaining DN represents a locally held object that contains
+ a ref attribute, that object is the nearest superior object with a
+ referral. Stop and process the referral as described below.
+ 3. If the remaining DN is the root of the locally held part of the
+ DIT, stop and proceed as described in section 6.
+ 4. Continue with step 1.
+
+Once the nearest superior object has been identified, if the referral
+contained in that object is not an LDAP URI [RFC2255], it should be
+returned as-is. If the referral is an LDAP URI, the referral must be
+modified, regardless of the type of operation, as case 2 describes for a
+non-search requuest. That is, the dn, attributes, scope, and filter
+parts of the URL must be stripped from the referral and the referral
+returned.
+
+Example:
+
+If the client issues an add request where the target object has a DN of
+"cn=Chris Lukas,o=abc,c=us", server A will return
+
+ AddResponse "referral" {
+ ldap://hostB/
+ ldap://hostC/
+ }
+
+
+
+
+5.1.1.3. Search with one level scope
+
+For search operations, once the base object has been found and deter-
+mined not to contain a ref attribute, the search may progress. Any
+entries matching the filter and scope of the search that do NOT contain
+a ref attribute are returned to the client normally as described in
+[RFC2251]. Any entries matching the filter and one level scope that do
+contain a ref attribute must be returned as referrals as described here.
+
+If a matching entry contains a ref attribute and the URI contained in
+the ref attribute is NOT an LDAP URI [RFC2255], the server should return
+the URI value contained in the ref attribute of that entry in a Sear-
+chResultReference.
+
+If a matching entry contains a ref attribute in the LDAP URI syntax
+
+
+
+Howes, et al. IETF LDAPEXT Working Group [Page 7]
+
+
+
+
+
+INTERNET-DRAFT LDAPv3 Named Referrals March 1999
+
+
+[RFC2255], the URL from the ref 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.
+
+Example:
+
+If a client requests a one level search of "c=US" then, in addition to
+any entries one level below the "c=US" naming context matching the
+filter (shown below as "... SearchResultEntry responses ..."), the
+server will also return referrals modified to include the "base" scope
+to maintain the one level search semantics.
+
+The order of the SearchResultEntry responses and the SearchResultRefer-
+ence responses is undefined. One possible sequence is shown.
+
+ ... SearchResultEntry responses ...
+
+ SearchResultReference {
+ ldap://hostB/o=abc,c=us??base
+ ldap://hostC/o=abc,c=us??base
+ }
+
+ SearchResultReference {
+ ldap://hostD/o=xyz,c=us??base
+ }
+
+ SearchResultDone "success"
+
+
+5.1.1.4. Search with subtree scope
+
+For a search operation with a subtree scope, once the base object has
+been found, the search progresses. As with the one level search, any
+entries matching the filter and scope of the search that do NOT contain
+a ref attribute are returned to the client normally as described in
+[RFC2251].
+
+If an entry matching the requested scope and filter contains a ref
+attribute, the server should return the URI value in a SearchResul-
+tReference.
+
+Example:
+
+If a client requests a subtree search of "c=us", then in addition to any
+entries in the "c=us" naming context which match the filter, Server A
+will also return two continuation references. As described in the
+
+
+
+Howes, et al. IETF LDAPEXT Working Group [Page 8]
+
+
+
+
+
+INTERNET-DRAFT LDAPv3 Named Referrals March 1999
+
+
+preceding section, the order of the responses is not defined.
+
+One possible response might be:
+
+ ... SearchResultEntry responses ...
+
+ SearchResultReference {
+ ldap://hostB/o=abc,c=us
+ ldap://hostC/o=abc,c=us
+ }
+
+ SearchResultReference {
+ ldap://hostD/o=xyz,c=us
+ }
+
+ SearchResultDone "success"
+
+
+6. Superior Reference
+
+An LDAP server may be configured to return a superior reference in the
+case where the server does not hold either the requested base object or
+an object containing a ref attribute that is superior to that base
+object.
+
+An LDAP server's root DSE MAY contain a ref attribute. The values of the
+ref attribute in the root DSE that are LDAP URIs SHOULD NOT contain any
+dn part, just the host name and optional port number.
+
+If the LDAP server's root DSE contains a ref attribute and a client
+requests an object not held by the server and not subordinate to any
+held object, the server must return the URI component of the values in
+the ref attribute of the root DSE as illustrated in the example.
+
+If the LDAP server's root DSE does not contain a ref attribute, the
+server may return one or more references that the server determines via
+a method not defined in this document to be appropriate.
+
+The default reference may be to any server that might contain more
+knowledge of the namespace than the responding server. In particular,
+the client must not expect the superior reference to be identical from
+session to session as the reference may be dynamically created by the
+server based on the details of the query submitted by the client.
+
+When the server receives an operation for which the base or target entry
+of the request is not contained in or subordinate to any naming context
+held by the server or a referral entry, the server will return an
+LDAPResult with the resultCode set to "referral", and with the referral
+
+
+
+Howes, et al. IETF LDAPEXT Working Group [Page 9]
+
+
+
+
+
+INTERNET-DRAFT LDAPv3 Named Referrals March 1999
+
+
+field filled with a referral that the server has determined to be
+appropriate.
+
+Example:
+
+If a client requests a subtree search of "c=de" from server A in the
+example configuration, and server A has the following ref attribute
+defined in it's root DSE:
+
+ ref: ldap://hostG/
+
+then server A will return
+
+ SearchResultDone "referral" {
+ ldap://hostG/
+ }
+
+
+7. The referral object class
+
+The referral object class is defined as follows.
+
+( 2.16.840.1.113730.3.2.6 NAME 'referral' SUP top STRUCTURAL
+ MAY ( ref ) )
+
+The referral object class is a subclass of top and may contain the
+referral 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 ref attribute 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.
+
+8. The manageDsaIT control
+
+A client MAY specify the following control when issuing a search, com-
+pare, add, delete, modify, or modifyDN request or an extended operation
+for which the control is defined.
+
+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 "ref" attribute to be treated as
+normal entries, allowing clients to read and modify these entries.
+
+
+
+
+Howes, et al. IETF LDAPEXT Working Group [Page 10]
+
+
+
+
+
+INTERNET-DRAFT LDAPv3 Named Referrals March 1999
+
+
+This control is not needed if the entry containing the referral attri-
+bute is one used for directory administrative purposes, such as the root
+DSE, or the server change log entries. Operations on these entries
+never cause referrals or continuation references to be returned.
+
+9. Relationship to X.500 Knowledge References
+
+The X.500 standard defines several types of knowledge references, used
+to bind together different parts of the X.500 namespace. In X.500,
+knowledge references can be associated with a set of unnamed entries
+(e.g., a reference, associated with an entry, to a server containing the
+descendants of that entry).
+
+This creates a potential problem for LDAP clients resolving an LDAPv3
+URL referral referring to an LDAP directory back-ended by X.500. Sup-
+pose the search is a subtree search, and that server A holds the base
+object of the search, and server B holds the descendants of the base
+object. The behavior of X.500(1993) subordinate references is that the
+base object on server A is searched, and a single continuation reference
+is returned pointing to all of the descendants held on server B.
+
+An LDAP URI only allows the base object to be specified. It is not pos-
+sible using standard LDAP URIs to indicate a search of several entries
+whose names are not known to the server holding the superior entry.
+
+X.500 solves this problem by having two fields, one indicating the pro-
+gress of name resolution and the other indicating the target of the
+search. In the above example, name resolution would be complete by the
+time the query reached server B, indicating that it should not refer the
+request.
+
+This document does not address this problem. This problem will be
+addressed in separate documents which define the changes to the X.500
+distribution model and LDAPv3 extensions to indicate the progress of
+name resolution.
+
+10. 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 infor-
+mation should be protected from unauthorized access as well.
+
+Clients should use caution when re-using credentials while following
+referrals as the client may be directed to any server which may or may
+not respect or use those credentials appropriately.
+
+
+
+
+Howes, et al. IETF LDAPEXT Working Group [Page 11]
+
+
+
+
+
+INTERNET-DRAFT LDAPv3 Named Referrals March 1999
+
+
+11. 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.
+
+[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.
+
+[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.
+
+12. Author's Address
+
+Tim Howes
+Netscape Communications Corp.
+501 E. Middlefield Rd.
+Mailstop MV068
+Mountain View, CA 94043
+USA
++1 650 937-3419
+EMail: howes@netscape.com
+
+Christopher E. Lukas
+Internet Scout Project
+Computer Sciences Dept.
+University of Wisconsin-Madison
+1210 W. Dayton St.
+Madison, WI 53706
+USA
+EMail: lukas@cs.wisc.edu
+
+
+
+
+Howes, et al. IETF LDAPEXT Working Group [Page 12]
+
+
+
+
+
+INTERNET-DRAFT LDAPv3 Named Referrals March 1999
+
+
+Michael Roszkowski
+Internet Scout Project
+Computer Sciences Dept.
+University of Wisconsin-Madison
+1210 W. Dayton St.
+Madison, WI 53706
+USA
+EMail: mfr@cs.wisc.edu
+
+Mark C. Smith
+Netscape Communications Corp.
+501 E. Middlefield Rd.
+Mailstop MV068
+Mountain View, CA 94043
+USA
+EMail: mcs@netscape.com
+
+Mark Wahl
+Innosoft International, Inc.
+8911 Capital of Texas Hwy #4140
+Austin TX 78759
+EMail: M.Wahl@innosoft.com
+
+
+This draft expires December 6, 1999.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Howes, et al. IETF LDAPEXT Working Group [Page 13]
+
+
projects / openldap / commitdiff