From: Kurt Zeilenga Date: Wed, 24 Jul 2002 15:48:27 +0000 (+0000) Subject: namedref is now a Proposed Standard RFC X-Git-Tag: NO_SLAP_OP_BLOCKS~1343 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=fcae7e4286282130767e66a924c44848f4c43ebc;p=openldap namedref is now a Proposed Standard RFC --- diff --git a/doc/drafts/draft-zeilenga-ldap-namedref-xx.txt b/doc/drafts/draft-zeilenga-ldap-namedref-xx.txt deleted file mode 100644 index 06c2593fbf..0000000000 --- a/doc/drafts/draft-zeilenga-ldap-namedref-xx.txt +++ /dev/null @@ -1,731 +0,0 @@ - - - - - - -INTERNET-DRAFT Editor: Kurt D. Zeilenga -Intended Category: Standard Track OpenLDAP Foundation -Expires: 20 May 2002 20 November 2001 - - - - Named Subordinate References 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. - - 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 - . The list of - Internet-Draft Shadow Directories can be accessed at - . - - Copyright 2001, The Internet Society. All Rights Reserved. - - Please see the Copyright section near the end of this document for - more information. - - -Abstract - - This document details schema and protocol elements for representing - and managing named subordinate references in LDAP directories. - - -Conventions - - - -Zeilenga LDAP NamedRef [Page 1] - -INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001 - - - Schema definitions are provided using LDAPv3 description formats - [RFC2252]. Definitions provided here are formatted (line wrapped) for - readability. - - 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 BCP 14 [RFC2119]. - - -1. Background and Intended Usage - - The broadening of interest in LDAP (Lightweight Directory Access - Protocol) [RFC2251] directories beyond their use as front ends to - X.500 [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 details schema and protocol elements for representing - and manipulating named subordinate references in LDAP directories. A - referral object is used to hold subordinate reference information in - the directory. These referral objects hold one or more URIs [RFC2396] - contained in values of the ref attribute type and are used to generate - protocol referrals and continuations. - - A control, ManageDsaIT, is defined to allow manipulation of referral - and other special objects as normal objects. As the name of control - implies, it is intended to be analogous to the ManageDsaIT service - option described in X.511(97) [X.511]. - - Other forms of knowledge information are not detailed by this - document. These forms may be described in subsequent documents. - - This document details subordinate referral processing requirements for - servers. This document does not describe protocol syntax and - semantics. This is detailed in RFC 2251 [RFC2251]. - - This document does not detail use of subordinate knowledge references - to support replicated environments nor distributed operations (e.g., - chaining of operations from one server to other servers). - - -2. Schema - -2.1. The referral Object Class - - A referral object is a directory entry whose structural object class - is (or is derived from) the referral object class. - - - -Zeilenga LDAP NamedRef [Page 2] - -INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001 - - - ( 2.16.840.1.113730.3.2.6 - NAME 'referral' - DESC 'named subordinate reference object' - STRUCTURAL - MUST ref ) - - The referral object class is a structural object class used to - represent a subordinate 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 (DN) [RFC2253]. Referral objects are directory - entries whose structural object class is (or is derived from) - referral. - - Referral objects are normally instantiated at DSEs immediately - subordinate to object entries within a naming context held by the DSA. - Referral objects are analogous to X.500 subordinate knowledge (subr) - DSEs [X.501]. - - In the presence of a ManageDsaIT control, referral objects are treated - as normal entries as described in section 3. 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, the content of referral - objects are used to construct referrals and search references as - described in section 4 and, as such, the referral entries are not - themselves visible to clients. - - -2.2 The ref Attribute Type - - ( 2.16.840.1.113730.3.1.34 - NAME 'ref' - DESC 'named reference - a labeledURI' - EQUALITY caseExactMatch - SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 - USAGE distributedOperation ) - - The ref attribute type has directoryString 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 [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. - - - -Zeilenga LDAP NamedRef [Page 3] - -INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001 - - - If the URI contained in a ref attribute value refers to a LDAP - [RFC2251] server, it MUST be in the form of a LDAP URL [RFC2255]. The - LDAP URL SHOULD NOT contain an explicit scope specifier, filter, - attribute description list, or any extensions. The LDAP URL SHOULD - contain a non-empty DN. The handling of LDAP URLs with absent or - empty DN parts or with explicit scope specifier is not defined by this - specification. - - Other URI schemes MAY be used so long as all operations returning - referrals based upon the value could be performed. This document does - not detail use of non-LDAP URIs. This is left to future - specifications. - - The referential integrity of the URI SHOULD NOT be validated by the - server holding or returning the URI (whether as a value of the - attribute or as part of a referral result or search reference - response). - - When returning a referral result or search continuation, the server - MUST NOT return the separator or label portions of the attribute - values as part of the reference. When the attribute contains multiple - values, the URI part of each value is used to construct the referral - result or search continuation. - - The ref attribute values SHOULD NOT be used as a relative - name-component of an entry's DN [RFC2253]. - - This document uses the ref attribute in conjunction with the referral - object class to represent subordinate references. The ref attribute - may be used for other purposes as defined by other documents. - - -3. The ManageDsaIT Control - - The client may provide the ManageDsaIT control with an operation to - indicate that the operation is intended to manage objects within the - DSA (server) Information Tree. The control causes Directory-specific - entries (DSEs), regardless of type, to be treated as normal entries - allowing clients to interrogate and update these entries using LDAP - operations. - - 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, if FALSE, absent. The control value is absent. - - - - -Zeilenga LDAP NamedRef [Page 4] - -INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001 - - - When the control is present in the request, the server SHALL NOT - generate a referral or continuation reference based upon information - held in referral objects and instead SHALL treat the referral object - as a normal entry. The server, however, is still free to return - referrals for other reasons. 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. - - -4. Named Subordinate References - - A named subordinate reference is constructed by instantiating a - referral object in the referencing server with ref attribute values - which point to the corresponding subtree maintained in the referenced - server. In general, the name of the referral object is the same as - the referenced object and this referenced object is a context prefix - [X.501]. - - That is, if server A holds "DC=example,DC=net" and server B holds - "DC=sub,DC=example,DC=net", server A may contain a referral object - named "DC=sub,DC=example,DC=net" which contains a ref attribute with - value of "ldap://B/DC=sub,DC=example,DC=net". - - dn: DC=sub,DC=example,DC=net - dc: sub - ref: ldap://B/DC=sub,DC=example,DC=net - objectClass: referral - objectClass: extensibleObject - - Typically the DN of the referral object and the DN of the object in - the referenced server are the same. - - If the ref attribute has multiple values, all the DNs contained within - the LDAP URLs SHOULD be equivalent. Administrators SHOULD avoid - configuring naming loops using referrals. - - Named references MUST be treated as normal entries if the request - includes the ManageDsaIT control as described in section 3. - - -5. 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 here consist of - referral object handling when finding target of a non-search - - - -Zeilenga LDAP NamedRef [Page 5] - -INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001 - - - operation, when finding the base of a search operation, and when - generating search references. Lastly, other operation processing - considerations are presented. - - 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 first phase is similar to, but not the same as, - finding the target of a non-search operation. - - It should 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 - processed and returned (in any order) 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. Example Configuration - - For example, suppose the contacted server (hosta) holds the entry - "O=MNN,C=WW" and the entry "CN=Manager,O=MNN,C=WW" and the following - referral objects: - - dn: OU=People,O=MNN,C=WW - ou: People - ref: ldap://hostb/OU=People,O=MNN,C=US - ref: ldap://hostc/OU=People,O=MNN,C=US - objectClass: referral - objectClass: extensibleObject - - dn: OU=Roles,O=MNN,C=WW - ou: Roles - ref: ldap://hostd/OU=Roles,O=MNN,C=WW - objectClass: referral - objectClass: extensibleObject - - The first referral object provides the server with the knowledge that - subtree "OU=People,O=MNN,C=WW" is held by hostb and hostc (e.g., one - is the master and the other a shadow). The second referral object - provides the server with the knowledge that the subtree - "OU=Roles,O=MNN,C=WW" is held by hostd. - - Also, in the context of this document, the "nearest naming context" - means the deepest context which the object is within. That is, if the - - - -Zeilenga LDAP NamedRef [Page 6] - -INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001 - - - object is within multiple naming contexts, the nearest naming context - is the one which is subordinate to all other naming contexts the - object is within. - - -5.2. Target object considerations - - This section details referral handling for add, compare, delete, - modify, and modify DN operations. If the client requests any of these - operations, there are four cases that the server must handle with - respect to the target object. - - The DN part MUST be modified such that it refers to the appropriate - target in the referenced server (as detailed below). Even where the - DN to be returned is the same as the target DN, the DN part SHOULD NOT - be trimmed. - - In cases where the URI to be returned is a LDAP URL, the server SHOULD - trim any present scope, filter, or attribute list from the URI before - returning it. Critical extensions MUST NOT be trimmed or modified. - - Case 1: The target object is not held by the server and is not within - or subordinate to any naming context nor subordinate to any - referral object held by the server. - - The server SHOULD process the request normally as appropriate for - a non-existent base which is not within any naming context of the - server (generally return noSuchObject or a referral based upon - superior knowledge reference information). This document does not - detail management or processing of superior knowledge reference - information. - - Case 2: The target object is held by the server and is a referral - object. - - The server SHOULD return the URI value contained in the ref - attribute of the referral object appropriately modified as - described above. - - Example: If the client issues a modify request for the target object - of "OU=People,O=MNN,c=WW", the server will return: - - ModifyResponse (referral) { - ldap://hostb/OU=People,O=MNN,C=WW - ldap://hostc/OU=People,O=MNN,C=WW - } - - - - - -Zeilenga LDAP NamedRef [Page 7] - -INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001 - - - Case 3: The target object is not held by the server, but the nearest - naming context contains no referral object which the target object - is subordinate to. - - If the nearest naming context contains no referral object which - the target is subordinate to, the server SHOULD process the - request as appropriate for a nonexistent target (generally return - noSuchObject). - - Case 4: The target object is not held by the server, but the nearest - naming context contains a referral object which the target object - is subordinate to. - - If a client requests an operation for which the target object is - not held by the server and the nearest naming context contains a - referral object which the target object is subordinate to, the - server SHOULD return a referral response constructed from the URI - portion of the ref value of the referral object. - - Example: If the client issues an add request where the target object - has a DN of "CN=Manager,OU=Roles,O=MNN,C=WW", the server will - return - - AddResponse (referral) { - ldap://hostd/CN=Manager,OU=Roles,O=MNN,C=WW" - } - - Note that the DN part of the LDAP URL is modified such that it - refers to the appropriate entry in the referenced server. - - -5.3. Base Object Considerations - - This section details referral handling for base object processing - within search operations. Like target object considerations for non- - search operations, there are the four cases. - - In cases where the URI to be returned is a LDAP URL, the server MUST - provide an explicit scope specifier from the LDAP URL prior to - returning it. In addition, the DN part MUST be modified such that it - refers to the appropriate target in the referenced server (as detailed - below). - - If aliasing dereferencing was necessary in finding the referral - object, the DN part of the URI MUST be replaced with the base DN as - modified by the alias dereferencing such that the return URL refers to - the new target object per [RFC2251, 4.1.11]. - - - - -Zeilenga LDAP NamedRef [Page 8] - -INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001 - - - Critical extensions MUST NOT be trimmed nor modified. - - Case 1: The base object is not held by the server and is not within - nor subordinate to any naming context held by the server. - - The server SHOULD process the request normally as appropriate for - a non-existent base which not within any naming context of the - server (generally return a superior referral or noSuchObject). - This document does not detail management or processing of superior - knowledge references. - - Case 2: The base object is held by the server and is a referral - object. - - The server SHOULD return the URI value contained in the ref - attribute of the referral object appropriately modified as - described above. - - - Example: If the client issues a subtree search in which the base - object is "OU=Roles,O=MNN,C=WW", the server will return - - SearchResultDone (referral) { - ldap://hostd/OU=Roles,O=MNN,C=WW??sub - } - - If the client were to issue a base or oneLevel search instead of - subtree, the returned LDAP URL would explicitly specify "base" or - "one", respectively, instead of "sub". - - Case 3: The base object is not held by the server, but the nearest - naming context contains no referral object which the base object - is subordinate to. - - If the nearest naming context contains no referral object which - the base is subordinate to, the request SHOULD be processed - normally as appropriate for a nonexistent base (generally return - noSuchObject). - - Case 4: The base object is not held by the server, but the nearest - naming context contains a referral object which the base object is - subordinate to. - - If a client requests an operation for which the target object is - not held by the server and the nearest naming context contains a - referral object which the target object is subordinate to, the - server SHOULD return a referral response which is constructed from - the URI portion of the ref value of the referral object. - - - -Zeilenga LDAP NamedRef [Page 9] - -INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001 - - - Example: If the client issues a base search request for - "CN=Manager,OU=Roles,O=MNN,C=WW", the server will return - - SearchResultDone (referral) { - ldap://hostd/CN=Manager,OU=Roles,O=MNN,C=WW??base" - } - - If the client were to issue a subtree or oneLevel search instead - of subtree, the returned LDAP URL would explicitly specify "sub" - or "one", respectively, instead of "base". - - Note that the DN part of the LDAP URL is modified such that it - refers to the appropriate entry in the referenced server. - - -5.4. Search Continuation Considerations - - For search operations, once the base object has been found and - determined not to be a referral object, the search may progress. Any - entry matching the filter and scope of the search which is not a - referral object is returned to the client normally as described in - [RFC2251]. - - For each referral object within the requested scope, regardless of the - search 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 a LDAP URL, it should be returned as is. - If the LDAP URL's DN part is absent or empty, the DN part must be - modified to contain the DN of the referral object. If the URI - component is a LDAP URL, the URI SHOULD be modified to add an explicit - scope specifier. - - Subtree Example: - - If a client requests a subtree search of "O=MNN,C=WW", then in - addition to any entries within scope which match the filter, hosta - will also return two search references as the two referral objects - are within scope. One possible response might be: - - SearchEntry for O=MNN,C=WW - SearchResultReference { - ldap://hostb/OU=People,O=MNN,C=WW??sub - ldap://hostc/OU=People,O=MNN,C=WW??sub - } - SearchEntry for CN=Manager,O=MNN,C=WW - SearchResultReference { - ldap://hostd/OU=Roles,O=MNN,C=WW??sub - } - - - -Zeilenga LDAP NamedRef [Page 10] - -INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001 - - - SearchResultDone (success) - - One Level Example: - - If a client requests a one level search of "O=MNN,C=WW" then, in - addition to any entries one level below the "O=MNN,C=WW" entry - matching the filter, the server will also return two search - references as the two referral objects are within scope. One - possible sequence is shown: - - SearchResultReference { - ldap://hostb/OU=People,O=MNN,C=WW??base - ldap://hostc/OU=People,O=MNN,C=WW??base - } - SearchEntry for CN=Manager,O=MNN,C=WW - SearchResultReference { - ldap://hostd/OU=Roles,O=MNN,C=WW??base - } - SearchResultDone (success) - - Note: Unlike the examples in Section 4.5.3.1 of RFC 2251, the LDAP - URLs returned with the SearchResultReference messages contain, - as required by this specification, an explicit scope specifier. - - -5.6. Other Considerations - - This section details processing considerations for other operations. - - -5.6.1 Bind - - Servers SHOULD NOT return referral result code if the bind name (or - authentication identity or authorization identity) is (or is - subordinate to) a referral object but MAY use the knowledge - information to process the bind request (such as in support a future - distributed operation specification). Where the server makes no use - of the knowledge information, the server processes the request - normally as appropriate for a non-existent authentication or - authorization identity (e.g., return invalidCredentials). - - -5.6.2 Modify DN - - If the newSuperior is a referral object or is subordinate to a - referral object, the server SHOULD return affectsMultipleDSAs. If the - newRDN already exists but is a referral object, the server SHOULD - return affectsMultipleDSAs instead of entryAlreadyExists. - - - -Zeilenga LDAP NamedRef [Page 11] - -INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001 - - -6. Security Considerations - - This document defines mechanisms that can be used to tie LDAP (and - other) servers together. The information used to tie services - together should be protected from unauthorized modification. If the - server topology information is not public information, it should be - protected from unauthorized disclosure as well. - - -7. Acknowledgments - - This document borrows heavily from previous work by IETF LDAPext - Working Group. In particular, this document is based upon "Named - Referral in LDAP Directories" (an expired Internet Draft) by - Christopher Lukas, Tim Howes, Michael Roszkowski, Mark C. Smith, and - Mark Wahl. - - -8. Author's Address - - Kurt D. Zeilenga - OpenLDAP Foundation - - - -9. Normative References - - [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", BCP 14 (also RFC 2119), March 1997. - - [RFC2251] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access - Protocol (v3)", RFC 2251, December 1997. - - [RFC2252] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight - Directory Access Protocol (v3): Attribute Syntax - Definitions", RFC 2252, December 1997. - - [RFC2253] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access - Protocol (v3): UTF-8 String Representation of Distinguished - Names", RFC 2253, December 1997. - - [RFC2255] T. Howes, M. Smith, "The LDAP URL Format", RFC 2255, - December, 1997. - - - - -Zeilenga LDAP NamedRef [Page 12] - -INTERNET-DRAFT draft-zeilenga-ldap-namedref-05 20 November 2001 - - - [RFC2396] Berners-Lee, T., R. Fielding, L. Masinter, "Uniform Resource - Identifiers (URI): Generic Syntax", RFC 2396, August 1998. - - [X.501] ITU-T, "The Directory: Models", X.501, 1993. - - -10. Informative References - - [X.500] ITU-T, "The Directory: Overview of Concepts, Models, and - Services", X.500, 1993. - - [X.511] ITU-T, "The Directory: Abstract Service Definition", X.500, - 1993. - - -Copyright 2001, The Internet Society. All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published and - distributed, in whole or in part, without restriction of any kind, - provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be followed, - or as required to translate it into languages other than English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, - INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE - INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED - WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - - - - - - - - - - - - -Zeilenga LDAP NamedRef [Page 13] - diff --git a/doc/rfc/INDEX b/doc/rfc/INDEX index 27e5596db9..9cce0bd2b7 100644 --- a/doc/rfc/INDEX +++ b/doc/rfc/INDEX @@ -29,6 +29,7 @@ rfc3045.txt Storing Vendor Information in the LDAP root DSE (I) rfc3062.txt LDAP Password Modify Extended Operation (PS) rfc3088.txt OpenLDAP Root Service (E) rfc3112.txt LDAP Authentication Password Schema (I) +rfc3296.txt Named Subordinate References in LDAP (PS) Legend: STD Standard diff --git a/doc/rfc/rfc3296.txt b/doc/rfc/rfc3296.txt new file mode 100644 index 0000000000..32cf91cca7 --- /dev/null +++ b/doc/rfc/rfc3296.txt @@ -0,0 +1,787 @@ + + + + + + +Network Working Group K. Zeilenga +Request for Comments: 3296 OpenLDAP Foundation +Category: Standards Track July 2002 + + + Named Subordinate References in + Lightweight Directory Access Protocol (LDAP) Directories + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2002). All Rights Reserved. + +Abstract + + This document details schema and protocol elements for representing + and managing named subordinate references in Lightweight Directory + Access Protocol (LDAP) Directories. + +Conventions + + Schema definitions are provided using LDAPv3 description formats + [RFC2252]. Definitions provided here are formatted (line wrapped) + for readability. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" used in + this document are to be interpreted as described in BCP 14 [RFC2119]. + +1. Background and Intended Usage + + The broadening of interest in LDAP (Lightweight Directory Access + Protocol) [RFC2251] directories beyond their use as front ends to + X.500 [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 details schema and protocol elements for representing + and manipulating named subordinate references in LDAP directories. A + referral object is used to hold subordinate reference information in + + + +Zeilenga Standards Track [Page 1] + +RFC 3296 Named Subordinate References in LDAP Directories July 2002 + + + the directory. These referral objects hold one or more URIs + [RFC2396] contained in values of the ref attribute type and are used + to generate protocol referrals and continuations. + + A control, ManageDsaIT, is defined to allow manipulation of referral + and other special objects as normal objects. As the name of control + implies, it is intended to be analogous to the ManageDsaIT service + option described in X.511(97) [X.511]. + + Other forms of knowledge information are not detailed by this + document. These forms may be described in subsequent documents. + + This document details subordinate referral processing requirements + for servers. This document does not describe protocol syntax and + semantics. This is detailed in RFC 2251 [RFC2251]. + + This document does not detail use of subordinate knowledge references + to support replicated environments nor distributed operations (e.g., + chaining of operations from one server to other servers). + +2. Schema + +2.1. The referral Object Class + + A referral object is a directory entry whose structural object class + is (or is derived from) the referral object class. + + ( 2.16.840.1.113730.3.2.6 + NAME 'referral' + DESC 'named subordinate reference object' + STRUCTURAL + MUST ref ) + + The referral object class is a structural object class used to + represent a subordinate 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 (DN) [RFC2253]. + + Referral objects are normally instantiated at DSEs immediately + subordinate to object entries within a naming context held by the + DSA. Referral objects are analogous to X.500 subordinate knowledge + (subr) DSEs [X.501]. + + + + + + + + +Zeilenga Standards Track [Page 2] + +RFC 3296 Named Subordinate References in LDAP Directories July 2002 + + + In the presence of a ManageDsaIT control, referral objects are + treated as normal entries as described in section 3. Note that the + ref attribute is operational and will only be returned in a search + entry response when requested. + + In the absence of a ManageDsaIT control, the content of referral + objects are used to construct referrals and search references as + described in Section 4 and, as such, the referral entries are not + themselves visible to clients. + +2.2 The ref Attribute Type + + ( 2.16.840.1.113730.3.1.34 + NAME 'ref' + DESC 'named reference - a labeledURI' + EQUALITY caseExactMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 + USAGE distributedOperation ) + + The ref attribute type has directoryString 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 [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 a LDAP + [RFC2251] server, it MUST be in the form of a LDAP URL [RFC2255]. + The LDAP URL SHOULD NOT contain an explicit scope specifier, filter, + attribute description list, or any extensions. The LDAP URL SHOULD + contain a non-empty DN. The handling of LDAP URLs with absent or + empty DN parts or with explicit scope specifier is not defined by + this specification. + + Other URI schemes MAY be used so long as all operations returning + referrals based upon the value could be performed. This document + does not detail use of non-LDAP URIs. This is left to future + specifications. + + The referential integrity of the URI SHOULD NOT be validated by the + server holding or returning the URI (whether as a value of the + attribute or as part of a referral result or search reference + response). + + + + + +Zeilenga Standards Track [Page 3] + +RFC 3296 Named Subordinate References in LDAP Directories July 2002 + + + When returning a referral result or search continuation, the server + MUST NOT return the separator or label portions of the attribute + values as part of the reference. When the attribute contains + multiple values, the URI part of each value is used to construct the + referral result or search continuation. + + The ref attribute values SHOULD NOT be used as a relative name- + component of an entry's DN [RFC2253]. + + This document uses the ref attribute in conjunction with the referral + object class to represent subordinate references. The ref attribute + may be used for other purposes as defined by other documents. + +3. The ManageDsaIT Control + + The client may provide the ManageDsaIT control with an operation to + indicate that the operation is intended to manage objects within the + DSA (server) Information Tree. The control causes Directory-specific + entries (DSEs), regardless of type, to be treated as normal entries + allowing clients to interrogate and update these entries using LDAP + operations. + + 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, if FALSE, absent. The control value is absent. + + When the control is present in the request, the server SHALL NOT + generate a referral or continuation reference based upon information + held in referral objects and instead SHALL treat the referral object + as a normal entry. The server, however, is still free to return + referrals for other reasons. 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. + +4. Named Subordinate References + + A named subordinate reference is constructed by instantiating a + referral object in the referencing server with ref attribute values + which point to the corresponding subtree maintained in the referenced + server. In general, the name of the referral object is the same as + the referenced object and this referenced object is a context prefix + [X.501]. + + + + +Zeilenga Standards Track [Page 4] + +RFC 3296 Named Subordinate References in LDAP Directories July 2002 + + + That is, if server A holds "DC=example,DC=net" and server B holds + "DC=sub,DC=example,DC=net", server A may contain a referral object + named "DC=sub,DC=example,DC=net" which contains a ref attribute with + value of "ldap://B/DC=sub,DC=example,DC=net". + + dn: DC=sub,DC=example,DC=net + dc: sub + ref: ldap://B/DC=sub,DC=example,DC=net + objectClass: referral + objectClass: extensibleObject + + Typically the DN of the referral object and the DN of the object in + the referenced server are the same. + + If the ref attribute has multiple values, all the DNs contained + within the LDAP URLs SHOULD be equivalent. Administrators SHOULD + avoid configuring naming loops using referrals. + + Named references MUST be treated as normal entries if the request + includes the ManageDsaIT control as described in section 3. + +5. 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 here consist of + referral object handling when finding target of a non-search + operation, when finding the base of a search operation, and when + generating search references. Lastly, other operation processing + considerations are presented. + + 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 first phase is similar to, but not + the same as, finding the target of a non-search operation. + + It should 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 + processed and returned (in any order) 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. + + + + + +Zeilenga Standards Track [Page 5] + +RFC 3296 Named Subordinate References in LDAP Directories July 2002 + + +5.1. Example Configuration + + For example, suppose the contacted server (hosta) holds the entry + "O=MNN,C=WW" and the entry "CN=Manager,O=MNN,C=WW" and the following + referral objects: + + dn: OU=People,O=MNN,C=WW + ou: People + ref: ldap://hostb/OU=People,O=MNN,C=US + ref: ldap://hostc/OU=People,O=MNN,C=US + objectClass: referral + objectClass: extensibleObject + + dn: OU=Roles,O=MNN,C=WW + ou: Roles + ref: ldap://hostd/OU=Roles,O=MNN,C=WW + objectClass: referral + objectClass: extensibleObject + + The first referral object provides the server with the knowledge that + subtree "OU=People,O=MNN,C=WW" is held by hostb and hostc (e.g., one + is the master and the other a shadow). The second referral object + provides the server with the knowledge that the subtree + "OU=Roles,O=MNN,C=WW" is held by hostd. + + Also, 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 is the one which is subordinate to all other naming contexts + the object is within. + +5.2. Target Object Considerations + + This section details referral handling for add, compare, delete, + modify, and modify DN operations. If the client requests any of + these operations, there are four cases that the server must handle + with respect to the target object. + + The DN part MUST be modified such that it refers to the appropriate + target in the referenced server (as detailed below). Even where the + DN to be returned is the same as the target DN, the DN part SHOULD + NOT be trimmed. + + In cases where the URI to be returned is a LDAP URL, the server + SHOULD trim any present scope, filter, or attribute list from the URI + before returning it. Critical extensions MUST NOT be trimmed or + modified. + + + + +Zeilenga Standards Track [Page 6] + +RFC 3296 Named Subordinate References in LDAP Directories July 2002 + + + Case 1: The target object is not held by the server and is not within + or subordinate to any naming context nor subordinate to any + referral object held by the server. + + The server SHOULD process the request normally as appropriate for + a non-existent base which is not within any naming context of the + server (generally return noSuchObject or a referral based upon + superior knowledge reference information). This document does not + detail management or processing of superior knowledge reference + information. + + Case 2: The target object is held by the server and is a referral + object. + + The server SHOULD return the URI value contained in the ref + attribute of the referral object appropriately modified as + described above. + + Example: If the client issues a modify request for the target object + of "OU=People,O=MNN,c=WW", the server will return: + + ModifyResponse (referral) { + ldap://hostb/OU=People,O=MNN,C=WW + ldap://hostc/OU=People,O=MNN,C=WW + } + + Case 3: The target object is not held by the server, but the nearest + naming context contains no referral object which the target object + is subordinate to. + + If the nearest naming context contains no referral object which + the target is subordinate to, the server SHOULD process the + request as appropriate for a nonexistent target (generally return + noSuchObject). + + Case 4: The target object is not held by the server, but the nearest + naming context contains a referral object which the target object + is subordinate to. + + If a client requests an operation for which the target object is + not held by the server and the nearest naming context contains a + referral object which the target object is subordinate to, the + server SHOULD return a referral response constructed from the URI + portion of the ref value of the referral object. + + + + + + + +Zeilenga Standards Track [Page 7] + +RFC 3296 Named Subordinate References in LDAP Directories July 2002 + + + Example: If the client issues an add request where the target object + has a DN of "CN=Manager,OU=Roles,O=MNN,C=WW", the server will + return: + + AddResponse (referral) { + ldap://hostd/CN=Manager,OU=Roles,O=MNN,C=WW" + } + + Note that the DN part of the LDAP URL is modified such that it + refers to the appropriate entry in the referenced server. + +5.3. Base Object Considerations + + This section details referral handling for base object processing + within search operations. Like target object considerations for + non-search operations, there are the four cases. + + In cases where the URI to be returned is a LDAP URL, the server MUST + provide an explicit scope specifier from the LDAP URL prior to + returning it. In addition, the DN part MUST be modified such that it + refers to the appropriate target in the referenced server (as + detailed below). + + If aliasing dereferencing was necessary in finding the referral + object, the DN part of the URI MUST be replaced with the base DN as + modified by the alias dereferencing such that the return URL refers + to the new target object per [RFC2251, 4.1.11]. + + Critical extensions MUST NOT be trimmed nor modified. + + Case 1: The base object is not held by the server and is not within + nor subordinate to any naming context held by the server. + + The server SHOULD process the request normally as appropriate for + a non-existent base which not within any naming context of the + server (generally return a superior referral or noSuchObject). + This document does not detail management or processing of superior + knowledge references. + + Case 2: The base object is held by the server and is a referral + object. + + The server SHOULD return the URI value contained in the ref + attribute of the referral object appropriately modified as + described above. + + + + + + +Zeilenga Standards Track [Page 8] + +RFC 3296 Named Subordinate References in LDAP Directories July 2002 + + + Example: If the client issues a subtree search in which the base + object is "OU=Roles,O=MNN,C=WW", the server will return + + SearchResultDone (referral) { + ldap://hostd/OU=Roles,O=MNN,C=WW??sub + } + + If the client were to issue a base or oneLevel search instead of + subtree, the returned LDAP URL would explicitly specify "base" or + "one", respectively, instead of "sub". + + Case 3: The base object is not held by the server, but the nearest + naming context contains no referral object which the base object + is subordinate to. + + If the nearest naming context contains no referral object which + the base is subordinate to, the request SHOULD be processed + normally as appropriate for a nonexistent base (generally return + noSuchObject). + + Case 4: The base object is not held by the server, but the nearest + naming context contains a referral object which the base object is + subordinate to. + + If a client requests an operation for which the target object is + not held by the server and the nearest naming context contains a + referral object which the target object is subordinate to, the + server SHOULD return a referral response which is constructed from + the URI portion of the ref value of the referral object. + + Example: If the client issues a base search request for + "CN=Manager,OU=Roles,O=MNN,C=WW", the server will return + + SearchResultDone (referral) { + ldap://hostd/CN=Manager,OU=Roles,O=MNN,C=WW??base" + } + + If the client were to issue a subtree or oneLevel search instead + of subtree, the returned LDAP URL would explicitly specify "sub" + or "one", respectively, instead of "base". + + Note that the DN part of the LDAP URL is modified such that it + refers to the appropriate entry in the referenced server. + + + + + + + + +Zeilenga Standards Track [Page 9] + +RFC 3296 Named Subordinate References in LDAP Directories July 2002 + + +5.4. Search Continuation Considerations + + For search operations, once the base object has been found and + determined not to be a referral object, the search may progress. Any + entry matching the filter and scope of the search which is not a + referral object is returned to the client normally as described in + [RFC2251]. + + For each referral object within the requested scope, regardless of + the search 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 a LDAP URL, it should be + returned as is. If the LDAP URL's DN part is absent or empty, the DN + part must be modified to contain the DN of the referral object. If + the URI component is a LDAP URL, the URI SHOULD be modified to add an + explicit scope specifier. + + Subtree Example: + + If a client requests a subtree search of "O=MNN,C=WW", then in + addition to any entries within scope which match the filter, hosta + will also return two search references as the two referral objects + are within scope. One possible response might be: + + SearchEntry for O=MNN,C=WW + SearchResultReference { + ldap://hostb/OU=People,O=MNN,C=WW??sub + ldap://hostc/OU=People,O=MNN,C=WW??sub + } + SearchEntry for CN=Manager,O=MNN,C=WW + SearchResultReference { + ldap://hostd/OU=Roles,O=MNN,C=WW??sub + } + SearchResultDone (success) + + One Level Example: + + If a client requests a one level search of "O=MNN,C=WW" then, in + addition to any entries one level below the "O=MNN,C=WW" entry + matching the filter, the server will also return two search + references as the two referral objects are within scope. One + possible sequence is shown: + + + + + + + + + +Zeilenga Standards Track [Page 10] + +RFC 3296 Named Subordinate References in LDAP Directories July 2002 + + + SearchResultReference { + ldap://hostb/OU=People,O=MNN,C=WW??base + ldap://hostc/OU=People,O=MNN,C=WW??base + } + SearchEntry for CN=Manager,O=MNN,C=WW + SearchResultReference { + ldap://hostd/OU=Roles,O=MNN,C=WW??base + } + SearchResultDone (success) + + Note: Unlike the examples in Section 4.5.3.1 of RFC 2251, the LDAP + URLs returned with the SearchResultReference messages contain, as + required by this specification, an explicit scope specifier. + +5.6. Other Considerations + + This section details processing considerations for other operations. + +5.6.1 Bind + + Servers SHOULD NOT return referral result code if the bind name (or + authentication identity or authorization identity) is (or is + subordinate to) a referral object but MAY use the knowledge + information to process the bind request (such as in support a future + distributed operation specification). Where the server makes no use + of the knowledge information, the server processes the request + normally as appropriate for a non-existent authentication or + authorization identity (e.g., return invalidCredentials). + +5.6.2 Modify DN + + If the newSuperior is a referral object or is subordinate to a + referral object, the server SHOULD return affectsMultipleDSAs. If + the newRDN already exists but is a referral object, the server SHOULD + return affectsMultipleDSAs instead of entryAlreadyExists. + +6. Security Considerations + + This document defines mechanisms that can be used to tie LDAP (and + other) servers together. The information used to tie services + together should be protected from unauthorized modification. If the + server topology information is not public information, it should be + protected from unauthorized disclosure as well. + + + + + + + + +Zeilenga Standards Track [Page 11] + +RFC 3296 Named Subordinate References in LDAP Directories July 2002 + + +7. Acknowledgments + + This document borrows heavily from previous work by IETF LDAPext + Working Group. In particular, this document is based upon "Named + Referral in LDAP Directories" (an expired Internet Draft) by + Christopher Lukas, Tim Howes, Michael Roszkowski, Mark C. Smith, and + Mark Wahl. + +8. Normative References + + [RFC2079] Smith, M., "Definition of an X.500 Attribute Type and an + Object Class to Hold Uniform Resource Identifiers (URIs)", + RFC 2079, January 1997. + + [RFC2119] Bradner, S., "Key Words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2251] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory + Access Protocol (v3)", RFC 2251, December 1997. + + [RFC2252] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, + "Lightweight Directory Access Protocol (v3): Attribute + Syntax Definitions", RFC 2252, December 1997. + + [RFC2253] Wahl, M., Kille, S. and T. Howes, "Lightweight Directory + Access Protocol (v3): UTF-8 String Representation of + Distinguished Names", RFC 2253, December 1997. + + [RFC2255] Howes, T. and M. Smith, "The LDAP URL Format", RFC 2255, + December, 1997. + + [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform + Resource Identifiers (URI): Generic Syntax", RFC 2396, + August 1998. + + [X.501] ITU-T, "The Directory: Models", X.501, 1993. + +9. Informative References + + [X.500] ITU-T, "The Directory: Overview of Concepts, Models, and + Services", X.500, 1993. + + [X.511] ITU-T, "The Directory: Abstract Service Definition", X.500, + 1997. + + + + + + + +Zeilenga Standards Track [Page 12] + +RFC 3296 Named Subordinate References in LDAP Directories July 2002 + + +10. Author's Address + + Kurt D. Zeilenga + OpenLDAP Foundation + + EMail: Kurt@OpenLDAP.org + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Zeilenga Standards Track [Page 13] + +RFC 3296 Named Subordinate References in LDAP Directories July 2002 + + +11. Full Copyright Statement + + Copyright (C) The Internet Society (2002). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Zeilenga Standards Track [Page 14] +