From 368ba563119127921fd07f46ccb1487cf08cd6ef Mon Sep 17 00:00:00 2001 From: Kurt Zeilenga Date: Wed, 19 Jul 2000 01:24:06 +0000 Subject: [PATCH 1/1] Replace expired LDAPext namedref I-D with Zeilenga namedref I-D. Add LDAPext refer I-D. --- doc/drafts/draft-ietf-ldapext-namedref-xx.txt | 774 ------------------ doc/drafts/draft-ietf-ldapext-refer-xx.txt | 728 ++++++++++++++++ .../draft-zeilenga-ldap-namedref-xx.txt | 675 +++++++++++++++ 3 files changed, 1403 insertions(+), 774 deletions(-) delete mode 100644 doc/drafts/draft-ietf-ldapext-namedref-xx.txt create mode 100644 doc/drafts/draft-ietf-ldapext-refer-xx.txt create mode 100644 doc/drafts/draft-zeilenga-ldap-namedref-xx.txt diff --git a/doc/drafts/draft-ietf-ldapext-namedref-xx.txt b/doc/drafts/draft-ietf-ldapext-namedref-xx.txt deleted file mode 100644 index 05bb5cbb3f..0000000000 --- a/doc/drafts/draft-ietf-ldapext-namedref-xx.txt +++ /dev/null @@ -1,774 +0,0 @@ -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] - - diff --git a/doc/drafts/draft-ietf-ldapext-refer-xx.txt b/doc/drafts/draft-ietf-ldapext-refer-xx.txt new file mode 100644 index 0000000000..184e801efb --- /dev/null +++ b/doc/drafts/draft-ietf-ldapext-refer-xx.txt @@ -0,0 +1,728 @@ +IETF LDAPEXT Working Group Roland Hedberg +Internet-Draft Catalogix +Expires: January 12, 2000 July 12, 2000 + + + + + + Referrals in LDAP Directories + + + + + +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] + diff --git a/doc/drafts/draft-zeilenga-ldap-namedref-xx.txt b/doc/drafts/draft-zeilenga-ldap-namedref-xx.txt new file mode 100644 index 0000000000..c4fc770f75 --- /dev/null +++ b/doc/drafts/draft-zeilenga-ldap-namedref-xx.txt @@ -0,0 +1,675 @@ + + + + + + +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] + -- 2.39.5