OwlCyberSecurity - MANAGER

Edit File: draft-sermersheim-ldap-distproc-xx.txt

Network Working Group J. Sermersheim Internet-Draft Novell, Inc Expires: August 26, 2005 February 22, 2005 Distributed Procedures for LDAP Operations draft-sermersheim-ldap-distproc-02.txt Status of this Memo This document is an Internet-Draft and is subject to all provisions of Section 3 of RFC 3667. By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she become aware will be disclosed, in accordance with RFC 3668. 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 August 26, 2005. Copyright Notice Copyright (C) The Internet Society (2005). Abstract This document provides the data types and procedures used while servicing Lightweight Directory Access Protocol (LDAP) user operations in order to participate in a distributed directory. In particular, it describes the way in which an LDAP user operation in a distributed directory environment finds its way to the proper DSA(s) for servicing. Sermersheim Expires August 26, 2005 [Page 1] Internet-Draft Distributed Procedures for LDAP Operations February 2005 Discussion Forum Technical discussion of this document will take place on the IETF LDAP Extensions mailing list <ldapext@ietf.org>. Please send editorial comments directly to the author. Table of Contents 1. Distributed Operations Overview . . . . . . . . . . . . . . 3 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Distributed Operation Data Types . . . . . . . . . . . . . . 5 3.1 ContinuationReference . . . . . . . . . . . . . . . . . . . 5 3.2 ChainedRequest . . . . . . . . . . . . . . . . . . . . . . . 9 3.3 Chained Response . . . . . . . . . . . . . . . . . . . . . . 11 4. Distributed Procedures . . . . . . . . . . . . . . . . . . . 14 4.1 Name resolution . . . . . . . . . . . . . . . . . . . . . . 14 4.2 Operation Evaluation . . . . . . . . . . . . . . . . . . . . 16 4.3 Populating the ContinuationReference . . . . . . . . . . . . 19 4.4 Sending a ChainedRequest . . . . . . . . . . . . . . . . . . 21 4.5 Emulating the Sending of a ChainedRequest . . . . . . . . . 23 4.6 Receiving a ChainedRequest . . . . . . . . . . . . . . . . . 24 4.7 Returning a Chained Response . . . . . . . . . . . . . . . . 25 4.8 Receiving a Chained Response . . . . . . . . . . . . . . . . 26 4.9 Returning a Referral or Intermediate Referral . . . . . . . 27 4.10 Acting on a Referral or Intermediate Referral . . . . . . . 30 4.11 Ensuring non-existence of an entry under an nssr . . . . . . 31 4.12 Mapping a referralURI to an LDAP URI . . . . . . . . . . . . 31 4.13 Using the ManageDsaIT control . . . . . . . . . . . . . . . 32 5. Security Considerations . . . . . . . . . . . . . . . . . . 33 6. Normative References . . . . . . . . . . . . . . . . . . . . 33 Author's Address . . . . . . . . . . . . . . . . . . . . . . 34 A. IANA Considerations . . . . . . . . . . . . . . . . . . . . 35 A.1 LDAP Object Identifier Registrations . . . . . . . . . . . . 35 A.2 LDAP Protocol Mechanism Registrations . . . . . . . . . . . 35 A.3 LDAP Descriptor Registrations . . . . . . . . . . . . . . . 37 A.4 LDAP Result Code Registrations . . . . . . . . . . . . . . . 38 Intellectual Property and Copyright Statements . . . . . . . 39 Sermersheim Expires August 26, 2005 [Page 2] Internet-Draft Distributed Procedures for LDAP Operations February 2005 1. Distributed Operations Overview One characteristic of X.500-based directory systems [X500] is that, given a distributed Directory Information Tree (DIT), a user should potentially be able to have any service request satisfied (subject to security, access control, and administrative policies) irrespective of the Directory Service Agent (DSA) to which the request was sent. To accommodate this requirement, it is necessary that any DSA involved in satisfying a particular service request have some knowledge (as specified in {TODO: Link to future Distributed Data Model doc}) of where the requested information is located and either return this knowledge to the requester or attempt to satisfy the request satisfied on the behalf of the requester (the requester may either be a Directory User Agent (DUA) or another DSA). Two modes of operation distribution are defined to meet these requirements, namely "chaining" and "returning referrals". "Chaining" refers to the attempt by a DSA to satisfy a request by sending one or more chained operations to other DSAs. "Returning referrals", is the act of returning distributed knowledge information to the requester, which may then itself interact with the DSA(s) identified by the distributed knowledge information. It is a goal of this document to provide the same level of service whether the chaining or referral mechanism is used to distribute an operation. The processing of an operation is talked about in two major phases, namely "name resolution", and "operation evaluation". Name resolution is the act of locating a local DSE held on a DSA given a distinguished name (DN). Operation evaluation is the act of performing the operation after the name resolution phase is complete. While distributing an operation, a request operation may be decomposed into several sub-operations. The distributed directory operation procedures described in this document assume the absense of the ManageDsaIT control defined in [RFC3296] and described in Section 4.13. Sermersheim Expires August 26, 2005 [Page 3] Internet-Draft Distributed Procedures for LDAP Operations February 2005 2. Conventions Imperative keywords defined in [RFC2119] are used in this document, and carry the meanings described there. All Basic Encoding Rules (BER) [X690] encodings follow the conventions found in Section 5.1 of [RFC2251]. Sermersheim Expires August 26, 2005 [Page 4] Internet-Draft Distributed Procedures for LDAP Operations February 2005 3. Distributed Operation Data Types The data types in this section are used by the chaining and referral distributed operation mechanisms described in Section 4 3.1 ContinuationReference As an operation is being processed by a DSA, it is useful to group the information passed between various procedures as a collection of data. The ContinuationReference data type is introduced for this purpose. This data type is populated and consumed by various procedures discussed in various sections of this document. In general, a ContinuationReference is used when indicating that directory information being acted on is not present locally, but may be present elsewhere. A ContinuationReference consists of one or more addresses which identify remote DSAs along with other information pertaining both to the distributed knowledge information held on the local DSA as well as information relevant to the operation. This data type is expressed here in Abstract Syntax Notation One (ASN.1) [X680]. ContinuationReference ::= SET { referralURI [0] SET SIZE (1..MAX) OF URI, localReference [2] LDAPDN, referenceType [3] ReferenceType, remainingName [4] RelativeLDAPDN OPTIONAL, searchScope [5] SearchScope OPTIONAL, searchedSubtrees [6] SearchedSubtrees OPTIONAL, failedName [7] LDAPDN OPTIONAL, ... } <Editor's Note: Planned for addition is a searchCriteria field which is used both for assuring that the remote object is in fact the object originally pointed to (this mechanism provides a security measure), and also to allow moved or renamed remote entries to be found. Typically the search criteria would have a filter value of (entryUUID=<something>)> URI ::= LDAPString -- limited to characters permitted in URIs [RFC2396]. ReferenceType ::= ENUMERATED { superior (0), subordinate (1), cross (2), nonSpecificSubordinate (3), Sermersheim Expires August 26, 2005 [Page 5] Internet-Draft Distributed Procedures for LDAP Operations February 2005 suplier (4), master (5), immediateSuperior (6), self (7), ... } SearchScope ::= ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2), subordinateSubtree (3), ... } SearchedSubtrees ::= SET OF RelativeLDAPDN LDAPDN, RelativeLDAPDN, and LDAPString, are defined in [RFC2251]. The following subsections introduce the fields of the ContinuationReference data type, but do not provide in-depth semantics or instructions on the population and consumption of the fields. These topics are discussed as part of the procedural instructions. 3.1.1 ContinuationReference.referralURI The list of referralURI values is used by the receiver to progress the operation. Each value specifies (at minimum) the protocol and address of one or more remote DSA(s) holding the data sought after. URI values which are placed in ContinuationReference.referralURI must allow for certain elements of data to be conveyed. Section 3.1.1.1 describes these data elements. Furthermore, a mapping must exist which relates the parts of a specified URI to these data elements. This document provides such a mapping for the LDAP URL [RFC2255] in Section 4.12. In some cases, a referralURI will contain data which has a counterpart in the fields of the ContinuationReference (an example is where the referralURI is an LDAP URL, holds a <scope> value, and the ContinuationReference.searchScope field is also present). In these cases, the data held on the referralURI overrides the field in the ContinuationReference. Specific examples of this are highlighted in other sections. Providing a means for these values to exist as fields of the ContinuationReference allows one value to be applied to all values of referralURI (as opposed to populating duplicate data on all referralURI values). If a referralURI value identifies an LDAP-enabled DSA [RFC3377], the LDAP URL form is used. Sermersheim Expires August 26, 2005 [Page 6] Internet-Draft Distributed Procedures for LDAP Operations February 2005 3.1.1.1 Elements of referralURI Values The following data elements must be allowed and identified for a specified URI type to be used to convey referral information. Each element is given a name which begins with 'referralURI.' for clarity when referencing the elements conceptually in other parts of this document. o referralURI.protocolIdentifier. There must be an indication of the protocol to be used to contact the DSA identified by the URI. o referralURI.accessPoint. The URI must identify a DSA in a manner that can be used to contact it using the protocol specified in protocolIdentifier. o referralURI.targetObject. Holds the name to be used as the base DN of the operation being progressed. This field must be allowed by the URI specification, but may be omitted in URI instances for various reasons. o referralURI.localReference. See Section 3.1.2. This field must be allowed by the URI specification, but may be omitted in URI instances for various reasons. o referralURI.searchScope. See Section 3.1.5. This field must be allowed by the URI specification, but may be omitted in URI instances for various reasons. o referralURI.searchedSubtrees. See Section 3.1.6. This field must be allowed by the URI specification, but may be omitted in URI instances for various reasons. o referralURI.failedName. See Section 3.1.7. This field must be allowed by the URI specification, but may be omitted in URI instances for various reasons. 3.1.2 ContinuationReference.localReference This names the DSE which was found to hold distributed knowledge information, and thus which caused the ContinuationReference to be formed. This field is primarily used to help convey the new target object name, but may also be used for purposes referential integrity (not discussed here). In the event that the root object holds the distributed knowledge information, this field is present and is populated with an empty DN. 3.1.3 ContinuationReference.referenceType Indicates the DSE Type of the ContinuationReference.localReference. This field may be used to determine how to progress an operations (i.e. if the value is nonSpecificSubordinate, a search continuation will exclude the ContinuationReference.referenceType). Sermersheim Expires August 26, 2005 [Page 7] Internet-Draft Distributed Procedures for LDAP Operations February 2005 3.1.4 ContinuationReference.remainingName In certain scenarios, the localReference does not completely name the DSE to be used as the new target object name. In these cases, remainingName is populated with the RDNSequence relative to the localReference of the target object name being resolved. Some examples of these scenarios include (but are not restricted to): o During name resolution, the name is not fully resolved, but a DSE holding distributed knowledge information is found, causing a ContinuationReference to be generated. o While searching, an alias is dereferenced. The aliasedObjectName points to a DSE of type glue which is subordinate to a DSE holding distributed knowledge information. 3.1.5 ContinuationReference.searchScope Under certain circumstances, when progressing a search operation, a search scope different than that of the original search request must be used. This field facilitates the conveyance of the proper search scope to be used when progressing the distributed operation. The scope of subordinateSubtree has been added to the values allowed by the LDAP SearchRequest.scope field. This scope includes the subtree of entries below the base DN, but does not include the base DN itself. This is used here when progressing distributed search operations caused by the existence of a DSE of type nssr. If a referralURI.searchScope is present, it overrides this field while that referralURI is being operated upon. 3.1.6 ContinuationReference.searchedSubtrees For ContinuationReferences generated while processing a search operation with a scope of wholeSubtree, each value of this field indicates that a particular subtree below the target object has already been searched. Consumers of this data use it to cause the progression of the search operation to exclude these subtrees as a mechanism to avoid receiving duplicate entries. If a referralURI.searchedSubtrees is present, it overrides this field while that referralURI is being operated upon. 3.1.7 ContinuationReference.failedName When an operation requires that multiple names be resolved (as is the case with the ModifyDN operation), this field is used to specify which name was found to be non-local. Sermersheim Expires August 26, 2005 [Page 8] Internet-Draft Distributed Procedures for LDAP Operations February 2005 If a referralURI.failedName is present, it overrides this field while that referralURI is being operated upon. 3.2 ChainedRequest The Chained Request is sent as an LDAP extended operation. The requestName is IANA-ASSIGNED-OID.1. The requestValue is the BER encoding of the following ChainedRequestValue ASN.1 definition: ChainedRequestValue ::= SEQUENCE { chainingArguments ChainingArguments, operationRequest OperationRequest } ChainingArguments ::= SEQUENCE { targetObject [0] LDAPDN OPTIONAL, referenceType [1] ReferenceType, traceInformation [2] ChainingTraceInformation, searchScope [3] SearchScope OPTIONAL, searchedSubtrees [4] SearchedSubtrees OPTIONAL} ChainingTraceInformation ::= SET OF LDAPURL OperationRequest ::= SEQUENCE { Request ::= CHOICE { bindRequest BindRequest, searchRequest SearchRequest, modifyRequest ModifyRequest, addRequest AddRequest, delRequest DelRequest, modDNRequest ModifyDNRequest, compareRequest CompareRequest, extendedReq ExtendedRequest, ... }, controls [0] Controls COPTIONAL } BindRequest, SearchRequest, ModifyRequest, AddRequest, DelRequest, ModifyDNRequest, CompareRequest, ExtendedRequest and Controls are defined in [RFC2251]. 3.2.1 ChainedRequestValue.chainingArguments In general, these fields assist in refining the original operation as it is to be executed on the receiving DSA. Sermersheim Expires August 26, 2005 [Page 9] Internet-Draft Distributed Procedures for LDAP Operations February 2005 3.2.1.1 ChainedRequestValue.chainingArguments.targetObject This field contains the new target (or base) DN for the operation. The sending DSA populates this under different scenarios including the case where an alias has been dereferenced while resolving the DN, and also the case where a referral carries a target name different from the reference object that caused the referral. This field can be omitted only if it would be the the same value as the object or base object parameter in the ChainedRequestValue.operationRequest, in which case its implied value is that value. The receiving DSA examines this field and (if present) uses it rather than the base DN held in the ChainedRequestValue.operationRequest. 3.2.1.2 ChainedRequestValue.chainingArguments.referenceType See Section 3.1.3. If the receiver encounters a value of nonSpecificSubordinate in this field, it indicates that the operation is being chained due to DSE of type nssr. In this case, the receiver allows (and expects) the base DN to name the immediate superior of a context prefix. 3.2.1.3 ChainedRequestValue.chainingArguments.traceInformation This contains a set of URIs. Each value represents the address of a DSA and DN that has already been contacted while attempting to service the operation. This field is used to detect looping while servicing a distributed operation. The sending DSA populates this with its own URI, and also the URIs of any DSAs that have already been chained to. The receiving DSA examines this list of URIs and returns a loopDetect error if it finds that any of the addresses and DNs in the listed URI's represent it's own. 3.2.1.4 ChainedRequestValue.chainingArguments.searchScope See Section 3.1.5. 3.2.1.5 ChainedRequestValue.chainingArguments.searchedSubtrees See Section 3.1.6. Sermersheim Expires August 26, 2005 [Page 10] Internet-Draft Distributed Procedures for LDAP Operations February 2005 3.2.2 ChainedRequestValue.operationRequest This holds the original LDAP operation request. This is restricted to a subset of all LDAP operations. Namely, the following LDAP operation types are not allowed: o Abandon/Cancel operations. When an abandon or cancel operation needs to be chained, it is sent to the remote DSA as-is. This is because there is no need to track it for loop detection or pass on any other information normally found in ChainingArguments. o Unbind. Again, there is no need to send chaining-related information to a DSA to perform an unbind. DSAs which chain operations maintain connections as they see fit. o Chained Operation. When a DSA receives a chained operation, and must again chain that operation to a remote DSA, it sends a ChainedRequest where the ChainedRequestValue.operationRequest is that of the incoming ChainedRequestValue.operationRequest. 3.3 Chained Response The Chained Response is sent as an LDAP IntermediateResponse [RFC3771], or LDAP ExtendedResponse [RFC2251], depending on whether the operation is complete or not. In either case, the responseName is omitted. For intermediate responses, the IntermediateResponse.responseValue is the BER encoding of the ChainedIntermediateResponseValue ASN.1 definition. For completed operations, the ExtendedResponse.value is the BER encoding of the ChainedFinalResponseValue ASN.1 definition. ChainedIntermediateResponseValue ::= SEQUENCE { chainedResults ChainingResults, operationResponse IntermediateResponse } ChainedFinalResponseValue ::= SEQUENCE { chainedResults ChainingResults, operationResponse FinalResponse } ChainingResults ::= SEQUENCE { searchedSubtrees [0] SearchedSubtrees OPTIONAL, ... } IntermediateResponse ::= SEQUENCE { Response ::= CHOICE { Sermersheim Expires August 26, 2005 [Page 11] Internet-Draft Distributed Procedures for LDAP Operations February 2005 searchResEntry SearchResultEntry, searchResRef SearchResultReference, intermediateResponse IntermediateResponse ... }, controls [0] Controls COPTIONAL } FinalResponse ::= SEQUENCE { Response ::= CHOICE { bindResponse BindResponse, searchResDone SearchResultDone, modifyResponse ModifyResponse, addResponse AddResponse, delResponse DelResponse, modDNResponse ModifyDNResponse, compareResponse CompareResponse, extendedResp ExtendedResponse, ... }, controls [0] Controls COPTIONAL } BindResponse, SearchResultEntry, SearchResultDone, SearchResultReference, ModifyResponse, AddResponse, DelResponse, ModifyDNResponse, CompareResponse, ExtendedResponse, and Controls are defined in [RFC2251]. IntermediateResponse is defined in [RFC3771]. 3.3.1 ChainingResults In general, this is used to convey additional information that may needed in the event that the operation needs to be progressed further. 3.3.1.1 ChainingResults.searchedSubtrees Each value of this field indicates that a particular subtree below the target object has already been searched. This is particularly useful while chaining search operations during operation evaluation caused by the presence of a DSA of type nssr. Each DSA referenced by the nssr holds one or more naming contexts subordinate to the nssr DSE. The ChainingResults.searchedSubtrees field allows the DSA being chained to, to inform the sending DSA which subordinate naming contexts have been searched. This information may be passed to further DSAs listed on the nssr in order to reduce the possibility of duplicate entries being returned. Sermersheim Expires August 26, 2005 [Page 12] Internet-Draft Distributed Procedures for LDAP Operations February 2005 3.3.2 ChainedIntermediateResponseValue.intermediateResponse and ChainedFinalResponseValue.finalResponse This holds the directory operation response message tied to the ChainedRequestValue.operationRequest. Sermersheim Expires August 26, 2005 [Page 13] Internet-Draft Distributed Procedures for LDAP Operations February 2005 4. Distributed Procedures For the purposes of describing a distributed operation, operations are said to consist of two major phases -- name resolution and operation evaluation. These terms are adopted from [X518]. Name resolution is the act of locating a DSE said to be held locally by a DSA given a distinguished name (DN). Operation evaluation is the act of performing the operation after the name resolution phase is complete. Furthermore, there are two modes of distributing an operation -- chaining, and returning referrals. Chaining is the act of forwarding an unfinished operation to another DSA for completion (this may happen during name resolution or operation evaluation). In this case, the forwarding DSA sends a chained operation to a receiving DSA, which attempts to complete the operation. Alternately, the DSA may return a referral (or intermediate referral), and the client may use that referral in order to forward the unfinished operation to another DSA. Whether the operation is distributed via chaining or referrals is a decision left to the DSA and or DUA. The term 'intermediate referral' describes a referral returned during the operation evaluation phase of an operation. These include searchResultReferences, referrals returned with an intermediateResponse [RFC3771], or future referrals which indicate that they are intermediate referrals. An operation which is distributed while in the operation evaluation phase is termed a 'sub-operation'. This document inserts a step between the two distributed operation phases in order to commonize the data and processes followed prior to chaining an operation or returning a referral. This step consists of populating a ContinuationReference data type. 4.1 Name resolution Before evaluating (enacting) most directory operations, the DSE named by the target (often called the base DN) of the operation must be located . This is done by evaluating the RDNs of the target DN one at a time, starting at the rootmost RDN. Each RDN is compared to the DSEs held by the DSA until the set of RDNs is exhausted, or an RDN cannot be found. If the DSE named by the target is found to be local, the name resolution phase of the operation completes and the operation evaluation phase begins. Sermersheim Expires August 26, 2005 [Page 14] Internet-Draft Distributed Procedures for LDAP Operations February 2005 If it is found that the target does not name a local DSE nor a DSE that may held by another DSA, it is said that the target does not exist, and the operation fails with noSuchObject (subject to local policy). If it is found that the DSE named by the target is non-local to the DSA, but may reside elsewhere, name resolution is said to be incomplete. In this case, the operation may be distributed by creating a ContinuationReference (Section 4.3) and either chaining the operation (Section 4.4 and Section 4.5)or returning a referral (Section 4.9). 4.1.1 Determining that a named DSE is local to a DSA If a DSE held by a DSA falls within a naming context held by the DSA, or is the root DSE on a first-level DSA, it is said to be local to that DSA 4.1.2 Determining that a named DSE does not exist A named DSE is said to not exist if, during name resolution the DSE is not found, but if found it would fall within a naming context held by the DSA. 4.1.3 Determining that a named DSE is non-local If a named DSE is niether found to be local to the DSA, nor found to not exist, it is said to be non-local to a DSA. In this case, it is indeterminate whether the named DSE exists. When a named DSE is found to be non-local, there should be distributed knowledge information available to be used to either return a referral or chain the operation. 4.1.3.1 Locating distributed knowledge information for a non-local target If it has been determined that a target names a non-local DSE, distributed knowledge information may be found by first examining the DSE named by the target, and subsequently all superior DSEs beginning with the immediate superior and ending with the root, until an examined DSE is one of types: {TODO: should DSE types be all caps? It would be easier to read.} o subr o supr o immsupr Sermersheim Expires August 26, 2005 [Page 15] Internet-Draft Distributed Procedures for LDAP Operations February 2005 o xr o nssr The examined DSE which is of one of these types holds the distributed knowledge information for the non-local named target. This DSE is said to be the found distributed knowledge information of the non-local target. This found distributed knowledge information may then be used to distribute the operation. If no examined DSEs are of any of these types, the distributed knowledge information is mis-configured, and the error invalidReference is returned. 4.1.4 Special case for the Add operation During the name resolution phase of the Add operation, the immediate parent of the base DN is resolved. If the immediate parent of the entry to be added is a DSE of type nssr, then further interrogation is needed to ensure that the entry to be added does not exist. Methods for doing this are found in Section 4.11. {TODO: don't make this mandatory. Also, it doesn't work without transaction semantics. Same prob in the mod dn below.}. 4.1.5 Special case for the ModifyDN operation When the modifyDN operation includes a newSuperior name, it must be resolved as well as the base DN being modified. If either of these result in a non-local name, the name causing the operation to be distributed should be conveyed (Section 4.3.5). {TODO: also mention access control problems, and mention (impl detail) that affectsmultidsa can be used.} If during operation evaluation of a ModifyDN operation, the newSuperior names a DSE type of nssr, then further interrogation is needed to ensure that the entry to be added does not exist. Methods for doing this are found in Section 4.11. 4.2 Operation Evaluation Once name resolution has completed. The DSE named in the target has been found to be local to a DSA. At this point the operation can be carried out. During operation evaluation distributed knowledge information may be found that may cause the DSA to distribute the operation. When this happens, the operation may be distributed by creating a ContinuationReference (Section 4.3) and either chaining the operation (Section 4.4 and Section 4.5)or returning a referral (Section 4.9). Sermersheim Expires August 26, 2005 [Page 16] Internet-Draft Distributed Procedures for LDAP Operations February 2005 If, during the location of the distributed knowledge information, the distributed knowledge information is found to be mis-configured, operation semantics are followed (some operations may call for an error to be returned, while others call for the error to be ignored). {TODO: either make this more specific, or less specific, or just toss it out.} 4.2.1 Search operation During operation evaluation of a search operation, the DSA must determine whether there is distributed knowledge information in the scope of the search. Any DSE in the search scope which is of the following types is considered to be 'found distributed knowledge information' {TODO: use a better term than found distributed knowledge information} in the search scope: o subr o nssr (see nssr note) o xr {TODO: I think xr only qualifies when an alias is dereferenced to an xr. Otherwisw, there should always be a subr above the xr if it falls in the search scope.} Note that due to alias dereferencing, the search scope may expand to include entries outside of the scope originally specified in the search operation. {TODO: note that an aliased object may be glue which needs to result in any subr or xr above it to be found} Nssr Note: A DSE of type nssr is only considered to be found distributed knowledge information when the scope of the search includes entries below it. For example, when the search scope is wholeSubtree or subordinateSubtree and a DSE of type nssr is found in the scope, or if the search scope is singleLevel and the target object names a DSE of type nsssr. {TODO: The following sections are talking about how the continuation reference is to be populated. Move to next secion. Can probably just say that whole subtree or subordinare subtree encountering nssr, and single level rooted at nssr result in a continuation reference. base at, and single level above do not result in a continuation reference.} 4.2.1.1 Search operation with singleLevel scope If distributed knowledge information is found during operation evaluation of a search with a singleLevel scope, it will cause the resulting ContinuationReference.searchScope to be set to baseObject. Sermersheim Expires August 26, 2005 [Page 17] Internet-Draft Distributed Procedures for LDAP Operations February 2005 4.2.1.2 Search operation encountering nssr knowledge reference When a search operation encounters distributed knowledge information which is a DSE type of nssr during operation evaluation, the following instructions are followed: Note that when a search operation is being progressed due to nssr knowledge information, the subsequent distributed progression of the search is caused to be applied to each DSA listed as non-specific knowledge information (This is talked about in Section 4.3.2). In the event that multiple DSAs listed in the knowledge information hold copies of the same directory entries, the 'already searched' and 'duplicate elimination' mechanisms SHOULD be used to prevent duplicate search result entries from ultimately being returned. 4.2.1.2.1 wholeSubtree search scope When the search scope is wholeSubtree, the ContinuationReference.searchScope is set to subordinateSubtree. Because the ContinuationReference.referrenceType is set to nonSpecificSubordinate, the receiving protocol peer allows (and expects) name resolution to stop at an immsupr DSE type which is treated as a local DSE. The subordinateSubtree scope instructs the receiving protocol peer to exclude the target object from the sub-search. 4.2.1.2.2 singleLevel search scope When the search scope is singleLevel, and the base DN is resolved to a DSE of type nssr, subsequent distributed progressions of the search are caused to use the same base DN, and a scope of singleLevel. Receiving protocol peers will only apply the search to entries below the target object. When the search scope is singleLevel and an evaluated DSE is of type nssr, no special handling is required. The search is applied to that DSE if it is of type entry. 4.2.1.2.3 baseObject search scope No special handling is needed when the search scope is baseObject and the base DN is an nssr DSEType. The search is applied to that DSE if it is of type entry. 4.2.1.3 Search operation rooted at an nssr DSE type (TODO: a subordinateSubtree scope needs to change to wholeSubtree if references are found.) Sermersheim Expires August 26, 2005 [Page 18] Internet-Draft Distributed Procedures for LDAP Operations February 2005 4.3 Populating the ContinuationReference When an entry is found to be non-local to a DSA (whether during name resolution or operation evaluation), the DSA prepares for operation distribution by generating a ContinuationReference. This is a conceptual step, given to help explain the interactions that occur between discovering that an operation must be distributing, and actually invoking the operation distribution mechanism. Implementations are not required to perform this step, but will effectively work with the same information. After the ContinuationReference has been created, the DSA may choose to chain the operation or return a referral (or intermediate referral(s)). the ContinuationReference is made up of data held on the found distributed knowledge information, as well as state information gained during name resolution or operation evaluation. 4.3.1 Conveying the Target Object The consumer of the ContinuationReference will examine various fields in order to determine the target object name of the operation being progressed. The fields examined are the localReference and remainingName. If name resolution did not complete, and the found distributed knowledge information names the same DSE as the base DN of the operation, the ContinuationReference MAY omit the localReference and/or remainingName fields. localReference is populated with the name of the found distributed knowledge information DSE. In the event that the root object holds the distributed knowledge information, this field will be populated with an empty DN. Contrast this with the omission of this field. referenceType is populated with a value reflecting the reference type of the localReference DSE. remainingName is populated with the RDNSequence which has not yet been resolved. This is the difference between the localReference value and the name of the DSE to be resolved. In cases where the DSE named by the {TODO, use a dash or different term to make 'found distributed knowledge' more like a single term} found distributed knowledge is not the same as the base DN of the operation, the ContinuationReference must contain the localReference and/or remainingName fields. Such cases include but are not limited Sermersheim Expires August 26, 2005 [Page 19] Internet-Draft Distributed Procedures for LDAP Operations February 2005 to: o Distributed knowledge information is found during operation evaluation. o Aliases were dereferenced during name resolution. o Name resolution did not complete and there were remaining RDNs to be resolved. 4.3.2 Conveying the Remote DSA The referralURI field must contain at least one value. Each referralURI value must hold a referralURI.accessPoint. Other requirements on this field as noted may also apply. Note for nssr DSE types: During operation evaluation, if a DSE of type nssr causes the operation to be distributed (the scenarios in Section 4.2.1.2 are an example), then an intermediate referral {TODO: this is talking about referral/intermediate referral, but this section is only dealing with populating continuation reference} is returned for each value of the ref attribute, where each intermediate referral only holds a single referralURI value. 4.3.3 Conveying new search scope During the evaluation of the search operation, the instructions in Section 4.2.1.2.1 and Section 4.2.1.2.2 are followed and the searchScope field is updated with the new search scope. 4.3.4 Preventing duplicates In order to prevent duplicate entries from being evaluated while progressing a search operation, the searchedSubtrees field is populated with any naming context below the ContinuationReference.targetObject which have been fully searched. During the evaluation of the search operation, if the scope is wholeSubtree, it is possible that the DSA may search the contents of a naming context which is subordinate to another naming context which is subordinate to the search base (See figure). Sermersheim Expires August 26, 2005 [Page 20] Internet-Draft Distributed Procedures for LDAP Operations February 2005 O X / \ / \ / \ / \ \_______O Y /|\ / | \ / | \ / | \ A B O C / \ / \ / \ / \ \_______/ In this figure, the DSA holds the naming context X and C,Y,X, but not Y,X. If the search base was X, an intermediate referral would be returned for Y,X. The DSA holding Y,X may also hold a copy of C,Y,X. In this case, the receiver of the ContinuationReference benefits by knowing that the DSA already searched C,Y,X so that it can prevent other DSAs from returning those entries again. Data already searched is in the form of an RDNSequence, consisting of the RDNs relative to the target object. 4.3.5 Conveying the Failed Name At least one DS operation (modifyDN) requires that multiple DNs be resolved (the entry being modified and the newSuperior entry). In this case, the failedName field will be populated with the DN being resolved which failed name resolution. This may aid in the determination of how the operation is to be progressed. If both names are found to be non-local, this field is omitted. 4.4 Sending a ChainedRequest When an entry is found to be non-local to a DSA (whether during name resolution or operation evaluation), the DSA may progress the operation by sending a chained operation to another DSA (or DSAs). The instructions in this section assume that a ContinuationReference has been generated which will be used to form the ChainedRequest. It is also assumed that it can be determined whether the operation is being progressed due to name resolution or due to operation evaluation. A DSA which is able to chain operations may advertise this by Sermersheim Expires August 26, 2005 [Page 21] Internet-Draft Distributed Procedures for LDAP Operations February 2005 returning a value of IANA-ASSIGNED-OID.2; in the supportedFeatures attribute on the root DSE. {TODO: does this and discovery of the extended op belong in a new 'discovery mechanisms' sections.} 4.4.1 Forming a ChainedRequest The following fields are populated as instructed: 4.4.1.1 ChainedRequestValue.chainingArguments.targetObject The ContinuationReference may convey a new target object. If present, the ContinuationReference.localReference field becomes the candidate target object. Otherwise the candidate target object is assumed to be that of the original directory operation. Note that an empty value in the ContinuationReference.localReference field denotes the root object. After performing the above determination as to the candidate target object, any RDNSequence in ContinuationReference.remainingName is prepended to the determined candidate target object. This value becomes the ChainedRequestValue.chainingArguments.targetObject. If this value matches the value of the original operation, this field may be omitted. 4.4.1.2 ChainedRequestValue.chainingArguments.referenceType This is populated with the ContinuationReference.referralURI.referenceType. 4.4.1.3 ChainedRequestValue.chainingArguments.traceInformation This is populated as specified in Section 3.2.1.3. 4.4.1.4 ChainedRequestValue.chainingArguments.searchScope This is populated with the ContinuationReference.referralURI.searchScope if present, otherwise by the ContinuationReference.searchScope if present, and not populated otherwise. 4.4.1.5 ChainedRequestValue.chainingArguments.searchedSubtrees This is populated with ContinuationReference.searchedSubtrees, as well as any previously received values of ChainedFinalResponseValue.chainingResults.searchedSubtrees or ChainedIntermediateResponseValue.chainingResults.searchedSubtrees which are subordinate, relative to the target object. (If thsi is relative to the target object, it can't contain non-relative Sermersheim Expires August 26, 2005 [Page 22] Internet-Draft Distributed Procedures for LDAP Operations February 2005 subtrees) 4.4.1.6 ChainedRequestValue.operationRequest This is populated with the original directory operation request. 4.4.2 Attempting Each Referral URI A ContinuationReference consists of one or more referralURIs which represent(s a) remote DSA(s). The chaining DSA attempts to chain to each of these DSAs until one succeeds in completing the operation. An operation is considered to be completed if it reaches the remote DSA and a response is sent back that indicates that the operation was executed. Operations which are sent to the remote DSA, but don't complete are indicated by a result code of unavailable or busy. A result code of protocolError may indicate that the DSA does not support the chained operation, and in this case, it is also treated as an uncompleted operation. Other errors may in the future specify that they also indicate non-completion. Note that the response may itself contain referral(s), these are still considered completed operations and thus would subsequently be handled and chained. {TODO: could use soft/hard, or transient/permanent referral/non-referral error terms here.} 4.4.3 Loop Prevention Prior to sending a ChainedRequest, the DSA may attempt to prevent looping scenarios by comparing {TODO: what matching rule is used? Suggest we don't convert dns names to ip addresses due to NATs} the address of the remote DSA and target object to the values of ChainedRequestValue.chainingArguments.traceInformation. If a match is found, the DSA returns a loopDetect error. Note that while this type of loop prevention aids in detecting loops prior to sending data to a remote DSA, it is not a substitute for loop detection (Section Section 4.6.2). This is because the sending DSA is only aware of a single address on which the receiving DSA accepts connections. 4.5 Emulating the Sending of a ChainedRequest When it is determined that the operation cannot be distributed by means of the ChainedRequest, the chaining DSA may instead emulate the steps involved in chaining the operation. These steps consist of performing loop prevention, forming a new directory operation request from the original request and possibly updating the base DN, search scope, and search filter(in order to emulate searchedSubtrees), and, similar to the steps in Section 4.4.2, attempting to send the operation request to each DSA listed in the ContinuationReference.referralURI until one succeeds in completing Sermersheim Expires August 26, 2005 [Page 23] Internet-Draft Distributed Procedures for LDAP Operations February 2005 the operation. {TODO: We need a way (control) to tell the receiver to allow name resolution to end on the parent of a cp (typically an immsupr). This would be sent when the ContinuationReference.referenceType is nonSpecificSubordinate} 4.5.1 Emulated Loop Detection For this step, the loop prevention instructions in Section 4.4.3 are followed. Note that this method of loop detection may actually allow some looping to occur before the loop is detected. 4.5.2 Forming the New Request The new directory operation request is formed from the fields of the original request, and the following fields may be updated: o The base DN is formed from the new target object as determined by following the instructions in Section 4.4.1.1 and using the value which would have been placed in ChainedRequestValue.chainingArguments.targetObject. o For the search operation, the scope is populated with ContinuationReference.searchScope if present, otherwise the scope of the original operation request is used. o For the search operation, if the ContinuationReference.searchedSubtrees field is present, causes the search filter to be augmented by adding a filter item of the 'and' CHOICE. The filter consists of {TODO: weasel Kurt into finishing his entryDN draft and reference the appropriate section there. See <http://www.openldap.org/lists/ietf-ldapext/200407/msg00000.html> for context} o Other fields (such as the messageID, and non-critical controls) may also need to be updated or excluded. If the service being chained to does not support directory operations, other operations may be used as long as they provide the same level as service as those provided by the analogous directory operation. 4.6 Receiving a ChainedRequest A DSA which is able to receive and service a ChainedRequest may advertise this feature by returning a value of IANA-ASSIGNED-OID.1 in the supportedExtension attribute of the root DSE. {TODO: move?} The ChainedRequestValue data type is the requestValue of an Sermersheim Expires August 26, 2005 [Page 24] Internet-Draft Distributed Procedures for LDAP Operations February 2005 extendedRequest. In general, receiving and servicing a ChainedRequest consists of performing loop detection and, using components of the ChainedRequestType.chainingArguments along with the ChainedRequestType.operationRequest, service the request. 4.6.1 Target Object determination Prior to checking for a loop condition, the target object must be determined. If the ChainedRequestType.chainingArguments.targetObject field is present, its value becomes the target object. Otherwise, the base DN found in the ChainedRequestType.operationRequest becomes the target object. 4.6.2 Loop Detection The loop detection check happens when a DSA receives a chained operation, prior to acting on the operation. The DSA compares {TODO: matching rule? DNS expansion?} each value of ChainedRequestValue.traceInformation to the list of addresses at which it accepts directory communications. A value of ChainedRequestValue.traceInformation matches when the DSA accepts directory communications on the address found in the ChainedRequestValue.traceInformation value, and the target object (as determined in Section 4.6.1 matches the DN {TODO: using DN matching?} value found in the ChainedRequestValue.traceInformation value. If a match is found the DSA returns a loopDetect result. 4.6.3 Processing the ChainedRequestValue.operationRequest In processing the operationRequest, the DSA uses the target object determined in Section 4.6.1. For search operations, it uses the scope found in ChainedRequestValue.chainingArguments.searchScope, and excludes any subtrees relative to the target object indicated in ChainedRequestValue.chainingArguments.searchedSubtrees. Responses are returned in the form of a Chained Response. 4.7 Returning a Chained Response When returning responses to a ChainedRequest, the Chained Response as documented in Section 3.3 is used. If the ChainedFinalResponseValue.operationResponse is a searchResultDone, the ChainedFinalResponseValue.chainingResults.searchedSubtrees field is populated with values consisting of the RDNSequence relative to the target object of naming contexts that the DSA searched. See Section 3.3.1.1 for details on why this is done. Sermersheim Expires August 26, 2005 [Page 25] Internet-Draft Distributed Procedures for LDAP Operations February 2005 4.7.1 Chained Response resultCode The resultCode for the Chained Response is distinct from the result code of the ChainedIntermediateResponseValue.intermediateResponse or ChainedFinalResponseValue.finalResponse. If the act of chaining the operation completed, then this value will be success. Other result codes refer to the chained operation itself, and not the result of the embedded operation. 4.7.2 Returning referrals in the Chained Response {TODO: it would be less complicated if rather than using the simple LDAP URL, we used the ContinuationReference type to return referrals and intermediate referrals.} {TODO: We need an example of why we should allow referrals on a chained response. Why not just use the referral field in the operation?} 4.8 Receiving a Chained Response Processing a received Chained Response is generally straight forward -- typically the response is simply extracted and returned, but there are some extra steps to be taken when chaining sub-operations. 4.8.1 Handling Sub-operation controls and result codes When sub-operations are chained, there is the possibility that different result codes will be encountered. Similarly, if controls which elicit response controls were attached to the operation, it's possible that multiple response controls will be encountered. Both of these possibilities require that the chaining DSA take appropriate steps to ensure that the response being returned is correct. In general, when a result code indicating an error is received, the operation will terminate and the error will be returned. In cases where multiple sub-operations are being concurrently serviced, the operation will terminate and the most relevant, or first received result code is returned -- determining the result code to be returned in this case is a local matter. A DSA which chains an operation having a control (or controls) attached must ensure that a properly formed response is returned. This requires that the DSA understand and know how to aggrigate the results of all controls which it allows to remain attached to an operation being chained. If the DSA does not understand or support a control which is marked non-critical, it removes the control prior to chaining the operation. The DSA may return unavailableCriticalExtension for critical controls that it cannot or will not chain. {TODO: give SSS as an example?} Sermersheim Expires August 26, 2005 [Page 26] Internet-Draft Distributed Procedures for LDAP Operations February 2005 4.8.1.1 Handling referrals during sub-operations If a referral is returned in response to a sub-operation, the sending DSA may attempt to further chain the operation. In the event that the DSA does not further chain the sub-operation, it will use the referral to construct an intermediate referral, and return it appropriately. When using a referral to construct an intermediate referral, certain transformations may have to happen. For example, when using a referral to construct a searchResultReference, it must be assured that the <dn> field is present, and that the <scope> field is properly updated. 4.8.2 Duplicate Elimination When search result references cause the DSA to chain a search, it is possible that duplicate objects will be returned by different remote DSAs. These duplicate objects must be sensed and not returned. {TODO: Even though there are costs associated with returning duplicates, is it a worthy exercise to build in an allowance for them to be returned? In other words, do we want to add a way for a client (or administrator) to say "it's ok, return the duplicates, let the client deal with them"? Allowing is seen as a cost benefit to the DSA.} 4.9 Returning a Referral or Intermediate Referral There are two ways in which the fields of the ContinuationReference may be conveyed in a response containing or consisting of referral or intermediate referral. A paired control is introduced for the purpose of soliciting and returning a ContinuationReference. In absence of this control, a referral or intermediate referral may be returned which conveys the information present in the ContinuationReference. A method of converting a ContinuationReference to an LDAP URL is provided for referrals and intermediate referrals which identify LDAP-enabled DSAs. Methods for converting a ContinuationReference to URIs which identify non-LDAP servers is not provided here, but may be specified in future documents, as long as they can represent the data needed to provide the same level of service. 4.9.1 ReturnContinuationReference controls This control is sent when a client wishes to receive a ContinuationReference in the event that a referral or intermediate referral is being returned. If returned, the ContinuationReference will hold all data but the referralURI field. the referralURI values will be held in the referral or intermediate referral (Referral, Sermersheim Expires August 26, 2005 [Page 27] Internet-Draft Distributed Procedures for LDAP Operations February 2005 SearchResultReference, etc.). 4.9.1.1 ReturnContinuationReference request control Solicits the return of a ReturnContinuationReference response control on messages consisting of (or carrying) a referral or intermediate referral. The controlType is IANA-ASSIGNED-OID.3, the criticality is set at the sender's discretion, the controlValue is omitted. 4.9.1.2 ReturnContinuationReference response control In response to the ReturnContinuationReference request control, this holds a ContinuationReference for messages consisting of (or carrying) a referral or intermediate referral. The controlType is IANA-ASSIGNED-OID.3, the controlValue is the BER-encoding of a ContinuationReference. Note that the referralURI field is optionally omitted when the ContinuationReference is sent in this control value. In this event, the URI(s) found in the referral or intermediate referral (Referral, SearchContinuationReference, etc.) are to be used in its stead. {TODO: is returining the referralURI outside an unneeded complication?} 4.9.2 Converting a ContinuationReference to an LDAP URL This section details the way in which an LDAP URL (from the referral or intermediate referral) is used to convey the fields of a ContinuationReference. Where existing LDAP URL fields are insufficient, extensions are introduced. Note that further extensions to the ContinuationReference type require further specifications here. {TODO: explain that each ldap url in the continuation refrerence is examined and converted} These instructions must be applied to each LDAP URL value within the referral or intermediate referral. 4.9.2.1 Conveying the target name If the <dn> part of the LDAP URL is already present, it is determined to be the candidate target object. Otherwise, the candidate target object comes from the ContinuationReference.localReference. Once the candidate target object is determined, the value of ContinuationReference.remainingName is prepended to the candidate target object. This new value becomes the target object and its string value (as specified by <distinguishedName> in [RFC2253]) is placed in the <dn> part of the LDAP URL. Sermersheim Expires August 26, 2005 [Page 28] Internet-Draft Distributed Procedures for LDAP Operations February 2005 4.9.2.2 ContinuationReference.localReference This is conveyed as an extension. The extype is IANA-ASSIGNED-OID.4 or the descriptor 'localReference', and the exvalue is the string DN encoding (as specified by <distinguishedName> in [RFC2253]) of the ContinuationReference.localReference value. 4.9.2.3 ContinuationReference.referenceType This is conveyed as an extension. The extype is IANA-ASSIGNED-OID.5 or the descriptor 'referenceType'. If the ContinuationReference.referenceType is one of superior, subordinate, cross, nonSpecificSubordinate, suplier, master, immediateSuperior, or self, the exvalue 'superior', 'subordinate', 'cross', 'nonSpecificSubordinate', 'suplier', 'master', 'immediateSuperior', or 'self' respectively. 4.9.2.4 ContinuationReference.searchScope If the search scope is one of baseObject, singleLevel, or wholeSubtree, then it may be conveyed in the 'scope' part of the LDAP URL as 'base', 'one', or 'sub' respectively. If the search scope is subordinateSubtree, then it may be conveyed in the <extension> form as documented in [LDAP-SUBORD]. If this extension is present, it MUST be marked critical. This ensures that a receiver which is unaware of this extension uses the proper search scope, or fails to progress the operation. 4.9.2.5 ContinuationReference.searchedSubtrees This field is conveyed as an extension. The extype is IANA-ASSIGNED-OID.6 or the descriptor 'searchedSubtrees', and the exvalue is the ContinuationReference.searchedSubtree value encoded according to the following searchedSubtrees ABNF: searchedSubtrees = 1*(LANGLE searchedSubtree RANGLE) searchedSubtree = <distinguishedName> from [RFC2253] LANGLE = %x3C ; left angle bracket ("<") RANGLE = %x3E ; right angle bracket (">") Each searchedSubtree represents one RDNSequence value in the ContinuationReference.searchedSubtree field. An example of a searchedSubtrees value containing two searched subtrees is: <dc=example,dc=com><cn=ralph,dc=users,dc=example,dc=com>. 4.9.2.6 ContinuationReference.failedName This field is conveyed as an extension. The extype is Sermersheim Expires August 26, 2005 [Page 29] Internet-Draft Distributed Procedures for LDAP Operations February 2005 IANA-ASSIGNED-OID.7 or the descriptor 'failedName', and the exvalue is the string DN encoding (as specified in [RFC2253]) of the ContinuationReference.failedName value. 4.10 Acting on a Referral or Intermediate Referral When a protocol peer receives a referral or intermediate referral, it may distribute the operation either by sending a ChainedRequest, or by emulating the ChainedRequest. Prior to taking these steps, the protocol peer effectively converts the referral or intermediate referral into a ContinuationReference. Then, acting in the same manner as a DSA would, follows the directions in Section 4.4 if sending a ChainedRequest, or Section 4.5 otherwise. 4.10.1 Converting a Referral or Intermediate Referral to a ContinuationReference A referral or intermediate referral may be converted (or conceptually converted) to a ContinuationReference type in order to follow the distributed operation procedures in Section 4.4, or Section 4.5. The following steps may only be used to convert a referral or intermediate referral containing LDAP URL values. Converting other types of URIs may be specified in future documents as long as the conversion provides the same level of service found here. o The ContinuationReference.referralURI is populated with all LDAP URL values in the referral or intermediate referral. o The ContinuationReference.localReference populate with the value of the localReference extension value (Section 4.9.2.2) if one exists. Otherwise it is omitted. o The ContinuationReference.referenceType populate with the value of the referenceType extension value (Section 4.9.2.3) if one exists. Otherwise it is omitted. o The ContinuationReference.remainingName is omitted. o The ContinuationReference.searchScope is populated with subordinateSubtree if the subordScope LDAP URL extension [LDAP-SUBORD] is present. If the <scope> field contains te value 'base', 'one', 'sub', or 'subordinates', this filed is populated with baseObject, singleLevel, wholeSubtree, or subordinateSubtree respectively. Otherwise this field is omitted. o The ContinuationReference.searchedSubtrees is populated with any searchedSubtrees LDAP URI extension Section 4.9.2.5 value found on an LDAP URI in the referral or intermediate referral. If none exist, this field is omitted. o The ContinuationReference.failedName is populated with any failedName LDAP URI extension Section 4.9.2.6 value found on an LDAP URI in the referral or intermediate referral. If none exist, this field is omitted. Sermersheim Expires August 26, 2005 [Page 30] Internet-Draft Distributed Procedures for LDAP Operations February 2005 Note that many fields are simply omitted. This is either because they are conveyed within the LDAP URL values themselves, and subsequent instructions will check for their presence, or because they are not needed (they are redundant or not used in further instructions). 4.11 Ensuring non-existence of an entry under an nssr {TODO: add a huge disclaimer here that says without transactional semantics, you can never be sure that the entry didn't get added. Maybe we should just punt on this and say it's a local matter} In order to ensure there are no entries matching the name of the entry to be added or renamed immediately subordinate to an nssr, these steps may be followed. If the DSA is able and allowed to chain operations, it may contact each of the DSAs listed as access points in the nssr (in the ref attribute) and using a base-level search operation it will determine whether or not the object to be added exists. Note that access control or other policies may hide the entry from the sending DSA. If the entry does not exist on any of the DSAs listed in the nssr, the operation may progress on the local DSA. If the DSA cannot make this determination, the operation fails with affectsMultipleDSAs. 4.12 Mapping a referralURI to an LDAP URI As with any URI specification which is intended to be used as a URI which conveys referral information, the LDAP URI specification is given a mapping to the elements of a referralURI as specified in. Section 3.1.1.1. These mappings are given here using the ABNF identifiers given in [RFC2255]. referralURI to LDAP URI mapping: +---------------------------------+---------------------------------+ | referralURI element | LDAP URL element | +---------------------------------+---------------------------------+ | protocolIdentifier | <scheme> | | | | | accessPoint | <hostport> | | | | | targetObject | <dn>. This must be encoded as a | | | <distinguishedName> as | | | specified in [RFC2253] | | | | | localReference | LDAP URL localReference | Sermersheim Expires August 26, 2005 [Page 31] Internet-Draft Distributed Procedures for LDAP Operations February 2005 | | extension as specified in | | | Section 4.9.2.2 | | | | | referenceType | LDAP URL referenceType | | | extension as specified in | | | Section 4.9.2.3 | | | | | searchScope | <scope> or LDAP URL subordScope | | | extension as specified in | | | Section 4.9.2.4 | | | | | searchedSubtrees | LDAP URL searchedSubtrees | | | extension as specified in | | | Section 4.9.2.5 | | | | | failedName | LDAP URL failedName extension | | | as specified in Section 4.9.2.6 | +---------------------------------+---------------------------------+ 4.13 Using the ManageDsaIT control This control, defined in [RFC3296], allows the management of the distributed knowledge information held by a DSA, and thus overrides the determinations made during name resolution and operation evaluation. When this control is attached to an operation, all resolved and acted upon DSEs are treated as being local to the DSA. This is true regardless of the phase the operation is in. Thus referrals are never returned and chaining never occurs. Sermersheim Expires August 26, 2005 [Page 32] Internet-Draft Distributed Procedures for LDAP Operations February 2005 5. Security Considerations This document introduces a mechanism (chaining) which can be used to propagate directory operation requests to servers which may be inaccessible otherwise. Implementers and deployers of this technology should be aware of this and take appropriate steps such that firewall mechanisms are not compromised. This document introduces the ability to return auxiliary data when returning referrals. Measures should be taken to ensure proper protection of his data. Implementers must ensure that any specified time, size, and administrative limits are not circumvented due to the mechanisms introduced here. 6. Normative References [LDAP-SUBORD] Sermersheim, J., "Subordinate Subtree Search Scope for LDAP", Internet-Draft draft-sermersheim-ldap-subordinate-scope, July 2004. [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. [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. [RFC3296] Zeilenga, K., "Named Subordinate References in Lightweight Directory Access Protocol (LDAP) Directories", RFC 3296, July 2002. Sermersheim Expires August 26, 2005 [Page 33] Internet-Draft Distributed Procedures for LDAP Operations February 2005 [RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. [RFC3383] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 3383, September 2002. [RFC3771] Harrison, R. and K. Zeilenga, "The Lightweight Directory Access Protocol (LDAP) Intermediate Response Message", RFC 3771, April 2004. [X500] International Telephone and Telegraph Consultative Committee, "The Directory - overview of concepts, models and services", ITU-T Recommendation X.500, November 1993. [X518] International Telephone and Telegraph Consultative Committee, "The Directory - The Directory: Procedures for distributed operation", ITU-T Recommendation X.518, November 1993. [X680] International Telecommunications Union, "Abstract Syntax Notation One (ASN.1): Specification of basic notation", ITU-T Recommendation X.680, July 2002. [X690] International Telecommunications Union, "Information Technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)", ITU-T Recommendation X.690, July 2002. Author's Address Jim Sermersheim Novell, Inc 1800 South Novell Place Provo, Utah 84606 USA Phone: +1 801 861-3088 Email: jimse@novell.com Sermersheim Expires August 26, 2005 [Page 34] Internet-Draft Distributed Procedures for LDAP Operations February 2005 Appendix A. IANA Considerations Registration of the following values is requested [RFC3383]. A.1 LDAP Object Identifier Registrations It is requested that IANA register upon Standards Action an LDAP Object Identifier in identifying the protocol elements defined in this technical specification. The following registration template is provided: Subject: Request for LDAP OID Registration Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Specification: RFCXXXX Author/Change Controller: IESG Comments: Seven delegations will be made under the assigned OID: IANA-ASSIGNED-OID.1 ChainedRequest LDAP Extended Operation IANA-ASSIGNED-OID.2 Supported Feature: Can Chain Operations IANA-ASSIGNED-OID.3 ReturnContinuationReference LDAP Controls IANA-ASSIGNED-OID.4 localReference: LDAP URL Extension IANA-ASSIGNED-OID.6 searchedSubtree: LDAP URL Extension IANA-ASSIGNED-OID.7 failedName: LDAP URL Extension A.2 LDAP Protocol Mechanism Registrations It is requested that IANA register upon Standards Action the LDAP protocol mechanism described in this document. The following registration templates are given: Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: IANA-ASSIGNED-OID.1 Description: ChainedRequest LDAP Extended Operation Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: Extension Specification: RFCXXXX Author/Change Controller: IESG Comments: none Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: IANA-ASSIGNED-OID.2 Description: Can Chain Operations Supported Feature Person & email address to contact for further information: Sermersheim Expires August 26, 2005 [Page 35] Internet-Draft Distributed Procedures for LDAP Operations February 2005 Jim Sermersheim jimse@novell.com Usage: Feature Specification: RFCXXXX Author/Change Controller: IESG Comments: none Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: IANA-ASSIGNED-OID.3 Description: ReturnContinuationReference LDAP Controls Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: Control Specification: RFCXXXX Author/Change Controller: IESG Comments: none Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: IANA-ASSIGNED-OID.4 Description: localReference LDAP URL Extension Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: Extension Specification: RFCXXXX Author/Change Controller: IESG Comments: none Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: IANA-ASSIGNED-OID.5 Description: referenceType LDAP URL Extension Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: Extension Specification: RFCXXXX Author/Change Controller: IESG Comments: none Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: IANA-ASSIGNED-OID.6 Description: searchedSubtree LDAP URL Extension Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: Extension Sermersheim Expires August 26, 2005 [Page 36] Internet-Draft Distributed Procedures for LDAP Operations February 2005 Specification: RFCXXXX Author/Change Controller: IESG Comments: none Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: IANA-ASSIGNED-OID.7 Description: failedName LDAP URL Extension Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: Extension Specification: RFCXXXX Author/Change Controller: IESG Comments: none A.3 LDAP Descriptor Registrations It is requested that IANA register upon Standards Action the LDAP descriptors described in this document. The following registration templates are given: Subject: Request for LDAP Descriptor Registration Descriptor (short name): localReference Object Identifier: IANA-ASSIGNED-OID.4 Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: URL Extension Specification: RFCXXXX Author/Change Controller: IESG Comments: none Subject: Request for LDAP Descriptor Registration Descriptor (short name): referenceType Object Identifier: IANA-ASSIGNED-OID.5 Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: URL Extension Specification: RFCXXXX Author/Change Controller: IESG Comments: none Subject: Request for LDAP Descriptor Registration Descriptor (short name): searchedSubtree Object Identifier: IANA-ASSIGNED-OID.6 Person & email address to contact for further information: Sermersheim Expires August 26, 2005 [Page 37] Internet-Draft Distributed Procedures for LDAP Operations February 2005 Jim Sermersheim jimse@novell.com Usage: URL Extension Specification: RFCXXXX Author/Change Controller: IESG Comments: none Subject: Request for LDAP Descriptor Registration Descriptor (short name): failedName Object Identifier: IANA-ASSIGNED-OID.7 Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: URL Extension Specification: RFCXXXX Author/Change Controller: IESG Comments: none A.4 LDAP Result Code Registrations It is requested that IANA register upon Standards Action the LDAP result codes described in this document. The following registration templates are given: Subject: Request for LDAP Result Code Registration Result Code Name: invalidReference Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: URL Extension Specification: RFCXXXX Author/Change Controller: IESG Comments: none Sermersheim Expires August 26, 2005 [Page 38] Internet-Draft Distributed Procedures for LDAP Operations February 2005 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Disclaimer of Validity This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM 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. Copyright Statement Copyright (C) The Internet Society (2005). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Sermersheim Expires August 26, 2005 [Page 39]