diff options
Diffstat (limited to 'source4/ldap_server/devdocs/rfc3296.txt')
| -rw-r--r-- | source4/ldap_server/devdocs/rfc3296.txt | 787 |
1 files changed, 0 insertions, 787 deletions
diff --git a/source4/ldap_server/devdocs/rfc3296.txt b/source4/ldap_server/devdocs/rfc3296.txt deleted file mode 100644 index 32cf91cca7..0000000000 --- a/source4/ldap_server/devdocs/rfc3296.txt +++ /dev/null @@ -1,787 +0,0 @@ - - - - - - -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] - |