INTERNET-DRAFT Kurt D. Zeilenga Intended Category: Standard Track OpenLDAP Foundation Expires: 4 January 2001 4 July 2000 Named References in LDAP Directories 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 . Please send editorial comments directly to the author . 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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 This draft expires 4 Jan. 2001. Zeilenga [Page 12]