Add LDAPext refer I-D.
+++ /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]
-
-
--- /dev/null
+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]
+
--- /dev/null
+
+
+
+
+
+
+INTERNET-DRAFT Kurt D. Zeilenga
+Intended Category: Standard Track OpenLDAP Foundation
+Expires: 4 January 2001 4 July 2000
+
+
+ Named References in LDAP Directories
+ <draft-zeilenga-ldap-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.
+
+ This document is intended to be, after appropriate review and
+ revision, submitted to the RFC Editor as a Standard Track document.
+ Distribution of this memo is unlimited. Technical discussion of this
+ document will take place on the IETF LDAP Extension Working Group
+ mailing list <ietf-ldapext@netscape.com>. Please send editorial
+ comments directly to the author <Kurt@OpenLDAP.org>.
+
+ 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.
+
+ Copyright 2000, The Internet Society. All Rights Reserved.
+
+ Please see the Copyright section near the end of this document for
+ more information.
+
+2. Abstract
+
+ This document defines schema and protocol elements for representing
+ and manipulating generic knowledge information in LDAP [RFC2251]
+ directories. An attribute type "ref" is used to store URIs [RFC1738]
+ which may refer to LDAP and non-LDAP services. An object class
+ "referral" is used to construct entries in an LDAP directory which
+ references to other directories or services. An control, ManageDsaIT,
+ is defined to allow clients to manipulate referral objects as normal
+ entries. The document describes procedures directory servers should
+ follow when supporting these elements.
+
+
+
+Zeilenga [Page 1]
+\f
+INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
+
+
+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
+ information in LDAP directories, based on URIs.
+
+ This document does not detail client processing of referral and search
+ reference responses. This is detailed in RFC 2251 or subsequent
+ documents.
+
+ The key words "SHALL", "SHALL NOT", "MUST", "MUST NOT", "SHOULD",
+ "SHOULD NOT", "MAY" and "MAY NOT" used in this document are to be
+ interpreted as described in [RFC2119].
+
+
+4. Schema
+
+4.1 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 'URI 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 multi valued. 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 a ref attribute value refers to an LDAPv3
+ server, it MUST be in the LDAP URI scheme described in [RFC2255].
+ Other URI schemes MAY be used but MUST refer to services which are
+ capable of completing operations referred to the services. The URI
+ values, regardless of scheme, contained in a ref attribute must point
+
+
+
+Zeilenga [Page 2]
+\f
+INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
+
+
+ to services which are equally capable of handling operations refer to
+ said services.
+
+ The integrity of the URI SHALL NOT be validated by the server holding
+ or returning the reference.
+
+ 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.
+
+ The ref attribute SHOULD NOT be used for naming.
+
+
+4.2. The referral object class
+
+ The referral object class is defined as follows.
+
+ ( 2.16.840.1.113730.3.2.6
+ NAME 'referral'
+ DESC 'named reference object'
+ STRUCTURAL MUST ref )
+
+ The referral object class is a structural object class used to
+ represent a named reference in the directory. The referral object
+ class SHOULD be used in conjunction with the extensibleObject object
+ class to support the naming attributes used in the entry's
+ distinguished name.
+
+ In the presence of a ManageDsaIT control, referral objects are treated
+ as normal entries. Note that the ref attribute is operational and
+ will only returned in a search entry response when requested.
+
+ In the absence of a ManageDsaIT control, referral objects contents are
+ used to construct referrals and search references and, as such, the
+ referral entries themselves are general visible to clients.
+
+
+5. Use of the ref attribute
+
+ Two uses the ref attribute is defined in this document. The first
+ use, in conjunction with the referral object class, represents a named
+ reference. The second use, in conjunction with the Root DSE,
+ represents superior reference. The following sections detail these
+ usages of the ref attribute.
+
+ Other uses of the ref attribute MAY be defined in subsequent
+ documents, or by bilateral agreement between cooperating clients and
+ servers and SHOULD be defined in conjunction with an object class
+
+
+
+Zeilenga [Page 3]
+\f
+INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
+
+
+ indicating the usage.
+
+
+5.1. Named reference
+
+ A named reference is used to facilitate distributed name resolution or
+ search across multiple servers. The ref attribute appears in an
+ referral object (an entry with object class of referral) 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
+ typically 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. Administrators SHOULD avoid configuring naming loops using
+ referrals.
+
+ The URI SHOULD NOT explicitly define a scope and the server SHOULD NOT
+ explicitly add a scope to the URI before returning it to the client as
+ a referral or search reference as the scope is implied by the
+ operation.
+
+ Named references MUST be treated as normal entries if the request
+ includes the ManageDsaIT control. The remainder of this section
+ describes processing of requests which do not include the ManageDsaIT
+ control.
+
+
+5.1.1. Scenarios
+
+ The following sections contain specifications of how referral objects
+ should be used in different scenarios followed by examples that
+ illustrate that usage. The scenarios described consist of referral
+ operation when finding target of a non-search operation, when finding
+ the base of a search operation, and when generating search references.
+
+ It is to be noted that, in this document, a search operation is
+ conceptually 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 similar to the operation of the server while finding
+ the target object for a non-search operations.
+
+ It is to also be noted that the ref attribute may have multiple values
+ and, where these sections refer to a single ref attribute value,
+ multiple ref attribute values may be substituted and SHOULD be
+
+
+
+Zeilenga [Page 4]
+\f
+INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
+
+
+ processed and returned as a group in a referral or search reference in
+ the same way as described for a single ref attribute value.
+
+ Search references returned for a given request may be returned in any
+ order.
+
+
+5.1.1.1. Example configuration
+
+
+ |------------------------------------------------------------|
+ | 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 references, 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 similar 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.
+
+
+
+Zeilenga [Page 5]
+\f
+INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
+
+
+ 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
+ specified in the request.
+
+ Case 1: The base or target object is not held by the server and is not
+ within or subordinate to any naming context nor is subordinate to any
+ referral object held by the server.
+
+ The handling of this case is described in section 6.
+
+ Case 2: The base or target object is held by the server and is a
+ referral object.
+
+ 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, 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, the server SHOULD return a modified form of this URI. The
+ returned URI MUST have only the protocol, host, port, and trailing "/"
+ portion of the URI contained in the ref attribute. The server SHOULD
+ strip any DN, attributes, scope, and filter parts of the URI.
+
+ 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
+ object where the nearest naming context contains no referral object
+ which the base or target object is subordinate to.
+
+
+
+Zeilenga [Page 6]
+\f
+INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
+
+
+ In the context of this document, the nearest naming context means the
+ deepest context which the object is within. That is, if the object is
+ within multiple naming contexts, the nearest naming context the one
+ which is subordinate to all other naming contexts the object is
+ within.
+
+ If the nearest naming context contains no referral object which the
+ base or target object is subordinate to the request, request SHOULD be
+ process normally as appropriate for a nonexistent base or target
+ object (generally return noSuchObject).
+
+ Case 4: The base or target object is not held by the server, but is
+ object where the nearest naming context contains a referral object
+ which the base or target object is subordinate to.
+
+ As noted above, the nearest naming context means the deepest context
+ which the object is within.
+
+ If a client requests an operation for which the base or target object
+ is not held by the server but the nearest naming context contains a
+ referral object which the base or target object is subordinate to, the
+ server MUST return a referral response which contains referral values
+ constructed from the URI components of ref attribute values of the
+ referral object.
+
+ For each ref attribute value, if the URI component is not an LDAP
+ URIs, it SHOULD be returned as-is. If URI component is an LDAP URI,
+ the URI MUST be modified, regardless of the type of operation, as case
+ 2 describes for a non-search request. That is, the DN, attributes,
+ scope, and filter parts of the URI MUST be stripped from the returned
+ URI.
+
+ 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 or subtree scope
+
+ For search operations, once the base object has been found and
+ determined not to be a referral object, the search may progress. Any
+ entries matching the filter and scope of the search which is not a
+
+
+
+Zeilenga [Page 7]
+\f
+INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
+
+
+ referral object are returned to the client normally as described in
+ [RFC2251].
+
+ For each referral object within the requested scope, regardless of the
+ filter, the server SHOULD return a SearchResultReference which is
+ constructed from the URI component of values of the ref attribute. If
+ the URI component is not an LDAP URI, it should be returned as is. If
+ the URI component is an LDAP URI, the URI must be modified to remove
+ any explicit scope specifier.
+
+ One Level 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 search references for any referral object
+ within the scope of the search.
+
+ The order of the SearchResultEntry responses and the
+ SearchResultReference responses is undefined. One possible sequence
+ is shown.
+
+ ... SearchResultEntry responses ...
+
+ SearchResultReference {
+ ldap://hostB/o=abc,c=us
+ ldap://hostC/o=abc,c=us
+ }
+
+ SearchResultReference {
+ ldap://hostD/o=xyz,c=us
+ }
+
+ SearchResultDone "success"
+
+
+ Subtree 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 preceding section, the order of the responses is not defined.
+
+ One possible response might be:
+
+ SearchResultReference {
+ ldap://hostB/o=abc,c=us
+ ldap://hostC/o=abc,c=us
+
+
+
+Zeilenga [Page 8]
+\f
+INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
+
+
+ }
+
+ ... SearchResultEntry responses ...
+
+ 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 requested base or target object is not contained within
+ or subordinate to a naming context held by the server or referral
+ 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 nor other search parameters (scope, filter,
+ attribute list). They MUST include the URI hostpart.
+
+ If the LDAP server's root DSE contains a ref attribute and a client
+ requests a target or base object not held by the server and not
+ contained within or subordinate to any naming context held by the
+ server or referral 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 referral result with or more URIs determined via an
+ appropriate method, return noSuchObject, or other appropriate
+ resultCode.
+
+ The presence of the ref attribute within the root DSE SHALL NOT cause
+ operations upon the root DSE to generate a referral.
+
+ 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
+
+
+
+
+Zeilenga [Page 9]
+\f
+INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
+
+
+ SearchResultDone "referral" {
+ ldap://hostG/
+ }
+
+
+8. The ManageDsaIT control
+
+ The ManageDsaIT control indicates that the operation has been
+ requested so that the DSA (server) Information Tree is managed. The
+ controls causes DSEs, regardless of type, to be treated as normal
+ entries allowing clients to interrogate and update these entries using
+ LDAP operations. This control is analogous to the ManageDsaIT option
+ described in X.511(93) [X.511].
+
+ A client MAY specify the following control when issuing an add,
+ compare, delete, modify, modifyDN, search 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 criticality
+ may be TRUE or FALSE. There is no value; the controlValue field is
+ absent.
+
+ When present in the request, the server SHALL NOT generate a referral
+ or continuation reference for any referral object and instead perform
+ treat the referral object as an normal entry. When not present,
+ referral objects SHALL be handled as described above.
+
+ The control MAY cause other objects to be treated as normal entries as
+ defined by subsequent documents.
+
+
+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
+ URI referral referring to an LDAP directory back-ended by X.500.
+ Suppose 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.
+
+
+
+
+Zeilenga [Page 10]
+\f
+INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
+
+
+ An LDAP URI only allows the base object to be specified. It is not
+ possible 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
+ progress 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
+ information should be protected from unauthorized access as well.
+
+
+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 Levels", RFC 2119 (Also BCP0014), March 1997.
+
+ [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.
+
+ [X.500] ITU-T Rec. X.501, "The Directory: Models", 1993.
+
+ [X.511] ITU-T Rec. X.511, "The Directory: Abstract Service
+
+
+
+Zeilenga [Page 11]
+\f
+INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
+
+
+ Definition", 1993.
+
+
+
+12. Acknowledgments
+
+ This document is borrows heavily from previous work by IETF LDAPext
+ working group. In particular, this document is based upon "Named
+ Referral in LDAP Directories" (a work in progress) by Christopher
+ Lukes, Tim Howes, Michael Roszkowski, Mark C. Smith, and Mark Wahl.
+
+
+13. Author's Address
+
+ Kurt D. Zeilenga
+ OpenLDAP Foundation
+ <Kurt@OpenLDAP.org>
+
+
+ This draft expires 4 Jan. 2001.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Zeilenga [Page 12]
+\f
projects / openldap / commitdiff