From: Kurt Zeilenga Date: Wed, 18 Aug 1999 20:16:33 +0000 (+0000) Subject: draft-ietf-ldapext-namedref-00.txt X-Git-Tag: TWEB_OL_BASE~169 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=90d82fc10bf2915e387419dfa18a4fd133b4e2ef;p=openldap draft-ietf-ldapext-namedref-00.txt --- diff --git a/doc/drafts/draft-ietf-ldapext-namedref-xx.txt b/doc/drafts/draft-ietf-ldapext-namedref-xx.txt new file mode 100644 index 0000000000..05bb5cbb3f --- /dev/null +++ b/doc/drafts/draft-ietf-ldapext-namedref-xx.txt @@ -0,0 +1,774 @@ +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 + + + + +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] + +