Do not require ac/string.h for lber_pvt.h

[openldap] / doc / drafts / 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]