[Date Prev][Date Next]
[Chronological]
[Thread]
[Top]
Re: [ldapext] Distributed Operations Rough Draft
I fixed and added more stuff.
Jim
>>> "Jim Sermersheim" <jimse@novell.com> 8/1/04 2:33:10 PM >>>
All,
I just wanted to drop an update regarding the work I'm trying to do
with LDAP chained operations. At Mark Ennis' suggestion, I have
changed
the approach I was taking in the previous chained operation I-D I
posted. Instead, this draft I-D attempts a fuller explanation of
distributed directory procedures.
In it, I begin by discussing name resolution and operation evaluation,
and end by discussing operation distribution via chaining or referral
following. In the middle, I use a ContinuationReference data type to
tie
things together. The goal that prompted this is that I'd like to have
a
model where whether an operation is to be distributed via chaining
versus referral following, both methods have the same class of
service.
You may also note that I'm proposing to do certain things slightly
differently than X.518 does (namely, the targetObject is the name of
the
reference object causing the operation to be distributed, rather than
the parent of the next naming context being resolved or operated on. I
did this for two primary reasons 1) I view it as a much simpler model.
Some of the baggage that came with the X.518 method causes numerous
subtleties that escape the casual (and even focused) reader. 2) LDAP
has
already set a precedent in the way that referrals and
searchContinuationReferences are returned and handled.
You'll note that the later sections are sparse or just not filled in
yet. I have the information in different places, I just haven't
consolidated (editied) it all into this document yet.
If anyone would like to meet for impromptu meetings at IETF60, drop me
a note. Or if you're not in San Diego, feel free to review the
document,
but be aware that I'm scurrying to finish it. I do welcome any
feedback
regarding whether you think I'm on or off track in any areas though.
Thanks,
Jim
Network Working Group J. Sermersheim
Internet-Draft Novell, Inc
Expires: December 30, 2004 July 2004
Distributed Procedures for LDAP Operations
draft-sermersheim-ldap-distproc.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 December 30, 2004.
Copyright Notice
Copyright (C) The Internet Society (2004). All Rights Reserved.
Abstract
This document provides the data types and procedures used while
servicing Lightweight Directory Application 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 December 30, 2004 [Page 1]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
Table of Contents
1. Distributed Operations Overview . . . . . . . . . . . . . . 3
2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Distributed Operation Data Types . . . . . . . . . . . . . . 5
3.1 ContinuationReference . . . . . . . . . . . . . . . . . . 5
3.2 ChainedRequest . . . . . . . . . . . . . . . . . . . . . . 8
3.3 ChainedResponse . . . . . . . . . . . . . . . . . . . . . 10
4. Distributed Procedures . . . . . . . . . . . . . . . . . . . 12
4.1 Name resolution . . . . . . . . . . . . . . . . . . . . . 12
4.2 Operation Evaluation . . . . . . . . . . . . . . . . . . . 14
4.3 Populating the ContinuationReference . . . . . . . . . . . 16
4.4 Sending a ChainedRequest . . . . . . . . . . . . . . . . . 18
4.5 Receiving a ChainedRequest . . . . . . . . . . . . . . . . 21
4.6 Returning a ChainedResponse . . . . . . . . . . . . . . . 22
4.7 Receiving a ChainedResponse . . . . . . . . . . . . . . . 22
4.8 Returning a Referral or SearchResultReference . . . . . . 23
4.9 Acting on a Referral or SearchResultReference . . . . . . 23
4.10 Ensuring non-existence of an entry under an nssr . . . . 23
4.11 Using the ManageDsaIT control . . . . . . . . . . . . . 23
5. Security Considerations . . . . . . . . . . . . . . . . . . 24
6. Normative References . . . . . . . . . . . . . . . . . . . . 24
Author's Address . . . . . . . . . . . . . . . . . . . . . . 24
Intellectual Property and Copyright Statements . . . . . . . 26
Sermersheim Expires December 30, 2004 [Page 2]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
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 DSA interaction are defined to meet these requirements,
namely "chaining", "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, the request may be decomposed into
several subrequests prior to the interaction.
Sermersheim Expires December 30, 2004 [Page 3]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
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 December 30, 2004 [Page 4]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
3. Distributed Operation Data Types
The data types in this section are used by the chaining and referral
distributed operation mechanisms
3.1 ContinuationReference
As an operation is being processed by a DSA, it is useful to keep
track of information passed to and from 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 below. In general, a
ContinuationReference is used when indicating that directory
information being acted on is not present locally, but that it may be
present elsewhere.
A ContinuationReference field consists of one or more addresses to
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,
remoteName [1] LDAPDN OPTIONAL,
localReference [2] LDAPDN,
remainingName [3] RelativeLDAPDN OPTIONAL,
searchScope [4] SearchScope OPTIONAL,
searchedSubtrees [5] SearchedSubtrees OPTIONAL,
failedName [6] 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
SearchScope::= ENUMERATED {
baseObject [0],
singleLevel [1],
wholeSubtree [2],
subordinateSubtree [3],
... }
Sermersheim Expires December 30, 2004 [Page 5]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
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
This specifies (at minimum) the protocol and address of one or more
remote DSA(s) holding the data sought after. The format is that of
any valid URI which identifies the access point of a DSA. Each
referralURI value must convey the information (typically protocol and
address) needed to contact the identified DSE. In some cases,
referralURI values will contain other data which can be used while
distributing the operation. Sometimes similar data exists as fields
of the ContinuationReference (an example is where the referralURI is
an LDAP URL, holds a DN value, and the remoteName field is also
present). In these cases, the data held on the referralURI value
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], it
MUST be in the form of an LDAP URL [RFC2255]
The list of referralURI values is used by the receiver to progress
the operation.
<Editor's Note: Somewhere in the document, it's desirable to talk
about the requirements of creating new URI specifications which
identify DSAs for purposes of referrals. In this requirements
section, we would discuss the required and optional fields of the
URI, and possibly try to foster some an IANA registration template.
In doing this, we would also show how the specification of LDAP URLs
can be used to meet these requirements.>
3.1.2 ContinuationReference.remoteName
This field may be used to hold a new base DN for the operation to
use.
This field may be used if the DSA allows name mappings. That is, if
Sermersheim Expires December 30, 2004 [Page 6]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
an object residing on a remote DSA has a name that differs from the
local name of the reference which represents that remote object, this
field can be used to convey the name of the remote object. If the
DSA does not allow name mapping to occur, this field will not be used
for that purpose.
If a target DN is present in a referralURI value, it overrides this
field while that referralURI value is being operated upon.
3.1.3 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.
For purposes of determining a new target object name, if the
remoteName field is present, it overrides this field.
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
remainingName value of the new target object name. 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
Sermersheim Expires December 30, 2004 [Page 7]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
operations caused by the existence of a DSE of type nssr.
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 have
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.
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.
3.2 ChainedRequest
The Chained Request is sent as an LDAP extended operation. The
requestName is <OID-TBD>. 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,
traceInformation [1] ChainingTraceInformation,
searchScope [2] SearchScope OPTIONAL,
searchedSubtrees [3] SearchedSubtrees OPTIONAL}
ChainingTraceInformation ::= SET OF LDAPURL
OperationRequest ::= SEQUENCE {
Request ::= CHOICE {
bindRequest BindRequest,
searchRequest SearchRequest,
modifyRequest ModifyRequest,
addRequest AddRequest,
delRequest DelRequest,
modDNRequest ModifyDNRequest,
Sermersheim Expires December 30, 2004 [Page 8]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
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.
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.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.3 ChainedRequestValue.chainingArguments.searchScope
See Section 3.1.5
Sermersheim Expires December 30, 2004 [Page 9]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
If the receiver encounters a value of subordinateSubtree, 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.4 ChainedRequestValue.chainingArguments.searchedSubtrees
See Section 3.1.6
3.2.2 ChainedRequestValue.operationRequest
This holds the original LDAP operation request. This is restricted
to a subset of all LDAP operation. 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. If an unbind request
is unbinding a previously chained bind, the server servicing the
unbind request ensures that the unbind is properly chained.
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 operationRequest.
3.3 ChainedResponse
The Chained Response is sent as an LDAP extended operation. The
requestName is omitted. The requestValue is the BER encoding of the
following ChainedResponseValue ASN.1 definition.
ChainedResponseValue ::= SEQUENCE {
chainedResults ChainingResults,
operationResponse OperationResponse }
ChainingResults ::= SEQUENCE {
searchedSubtrees [0] SearchedSubtrees OPTIONAL,
... }
OperationResponse ::= SEQUENCE {
Response ::= CHOICE {
Sermersheim Expires December 30, 2004 [Page 10]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
bindResponse BindResponse,
searchResEntry SearchResultEntry,
searchResDone SearchResultDone,
searchResRef SearchResultReference,
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]
3.3.1 ChainedResponseValue.chainedResults
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 ChainedResponseValue.chainedResults.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 ChainedResponseValue.chainedResults.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.
3.3.2 ChainedResponseValue.operationResponse
This holds the response message tied to the
ChainedRequestValue.operationRequest.
<TODO: Discuss the relationship between the components of LDAPResult
in the operationResponse and the components of LDAPResult in the
extended response.>
Sermersheim Expires December 30, 2004 [Page 11]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
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. Name resolution is the act of locating 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. In
this case, the forwarding DSA sends a chained operation and a
receiving DSA receives the chained operation. Alternately, the DSA
may return a referral (or intermediate referral), and the client may
follow 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' refers to a referral returned during
the operation evaluation phase of an operation. These include
searchResultReferences, referrals returned with an
intermediateResponse <TODO: Ref>, 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 into these distributed operation modes
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
If it is found that the target does not name a local DSE nor a DSE
held by another DSA, it is said that the target does not exist, and
the operation fails with noSuchObject (subject to local policy).
Sermersheim Expires December 30, 2004 [Page 12]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
If it is found that the DSE named by target is non-local to the DSE,
but may reside elsewhere, name resolution is said to be incomplete.
In this case, the operation may be distributed by following the
instructions in <TODO>
4.1.1 Determining that a DSE is local to a DSA
If a DSE held by a DSA meets the following criteria, it is said to
be local to that DSA:
o It is or falls (hierarchically) under and administrative point.
o it is a DSE of any of the types:
* root
* cp
* entry
* alias
* admPoint
* subentry
4.1.2 Determining that a named target does not exist
A named target DN is said to to not exist if the following are met:
o At least one RDN has matched a DSE during name resolution.
o An RDN is encountered that names no DSE.
o The last DSE resolved is local to the DSA.
4.1.3 Determining that the target is non-local
If the following are met, then the DSE named by the target is said to
be non-local to a DSA:
o It is not found to be local to the DSA.
o It is not found to not exist
In this case, 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 the 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:
Sermersheim Expires December 30, 2004 [Page 13]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
o subr
o supr
o xr
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 found distributed
knowledge information is mis-configured, and the error <TODO: add a
new error for this> 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.10
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 target DN being modified. If either of these
result in a non-local name, the name causing the operation to be
distributed should be conveyed. Mechanisms for doing this are
discussed in <TODO: add ref> and <TODO: add ref>.
If during operation evaluation of a ModifyDN operation, the
newSuperior names a DSE 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 <TODO: add ref>.
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. This is done as specified in <todo>
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).
Sermersheim Expires December 30, 2004 [Page 14]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
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 in the search scope:
o subr
o nssr (see nssr note)
o xr
Note that due to alias dereferencing, locating any DSE of the above
types in the search scope may be possible.
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.
4.2.1.1 Search operation with singleLevel scope
If during operation evaluation of a search with a singleLevel scope
distributed knowledge information is found, it will cause the
subsequent distributed progression of the search to use a scope of
baseObject.
4.2.1.2 Search operation encountering a DSE of type nssr
When a search operation encounters a DSE type nssr during operation
evaluation, the following instructions are followed, but only if the
search requires that subordinates of the nssr DSE are to be examined.
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 subsequent distributed
progression of the search is caused to use a base of the found DSE,
and a scope of subordinateSubtree. This causes the receiving DSAs to
only apply the search to entries below the new target object.
Sermersheim Expires December 30, 2004 [Page 15]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
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. This
causes the receiving DSAs to 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, or if the ManageDsaIT control is
attached.
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, or if the ManageDsaIT control is attached.
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 any target DN in the referralURI
value(s), remoteName, 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 be populated without any
Sermersheim Expires December 30, 2004 [Page 16]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
target DN in the referralURI value(s), remoteName, localReference,
or remainingName.
remoteName is populated with the DN value of the refRemoteName
attribute (if present)
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.
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 found distributed knowledge is
not the same as the base DN of the operation, the
ContinuationReference must contain either the remoteName,
localReference, or DN part(s) in each referralURI value. It may also
contain a value in the remainingName field. Such cases include but
are not limited 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 which holds the
location of a DSA to be used in progressing the operation. 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 is
returned for each value of the ref attribute, where each intermediate
referral only holds a single referralURI value. <TODO: we may want
to use a special attribute for nssr knowledge information. That way
we can combine an nssr with a subr, and return the correct number of
referrals>.
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.
Sermersheim Expires December 30, 2004 [Page 17]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
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 resolved DSE 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) <TODO: Insert figure
similar to that in X.518>.
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 client may wish to know 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 this has happened, and
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
returning a value of <OID-TBD> in the supportedFeatures attribute on
the root DSE.
Sermersheim Expires December 30, 2004 [Page 18]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
4.4.1 Forming a ChainedRequest
The following fields are populated as instructed:
4.4.1.1 ChainedRequestValue.chainingArguments.targetObject
Intermediate referrals must and normal referrals may convey a new
target object. Each of the following fields is examined in order,
and if a DN value is present in any of them, it becomes the
ChainedRequestValue.chainingArguments.targetObject.
o The DN field of the ContinuationReference.referralURI.
o The ContinuationReference.targetObject field.
o The ContinuationReference.localReference field.
If there is no DN value in the ContinuationReference.referralURI, and
if the ContinuationReference.targetObject and
ContinuationReference.localReference fields are not present, the
target object is assumed to be that of the original directory
operation. Note that an empty value in the
ContinuationReference.targetObject or
ContinuationReference.localReference field denotes the root object.
After performing the above determination as to the target object, any
RDNSequence in ContinuationReference.remainingName is prepended to
the determined 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.traceInformation
This is populated as specified in Section 3.2.1.2.
4.4.1.3 ChainedRequestValue.chainingArguments.searchScope
This is populated with Referral.searchScope if present, and not
populated otherwise.
4.4.1.4 ChainedRequestValue.chainingArguments.searchedSubtrees
This is populated with Referral.excludeSubtree.
4.4.1.5 ChainedRequestValue.operationRequest
This is populated with the original directory operation request.
Sermersheim Expires December 30, 2004 [Page 19]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
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 one of unavailable, or busy. Note that
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.
4.4.3 Loop Prevention
Prior to sending a ChainedRequest, the DSA may attempt to prevent
looping scenarios by comparing 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.5.2). This is because the sending DSA is only aware of a
single address on which the receiving DSA accepts connections.
4.4.4 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 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
Sermersheim Expires December 30, 2004 [Page 20]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
return unavailableCriticalExtension for critical controls that it
cannot or will not chain.
4.4.4.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.
4.4.5 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.5 Receiving a ChainedRequest
A DSA which is able to receive and service a ChainedRequest may
advertise this feature by returning a value of <OID-TBD> in the
supportedExtension attribute of the root DSE.
The ChainedRequestValue data type is the requestValue of an
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.5.1 Target Object determination
Prior to checking for a loop condition, the target object must be
determined. If the ChainedRequestType.targetObject field is present,
its value becomes the target object. Otherwise, the base DN found in
the ChainedRequestType.operationRequest becomes the target object.
4.5.2 Loop Detection
The loop detection check happens when a DSA receives a chained
Sermersheim Expires December 30, 2004 [Page 21]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
operation, prior to acting on the operation. The DSA compares 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.5.1 matches the DN value found in the
ChainedRequestValue.traceInformation value. If a match is found the
DSA returns a loopDetect result.
4.5.3 Processing the ChainedRequestValue.operationRequest
In processing the operationRequest, the DSA uses the target object
determined in Section 4.5.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 ChainedResponse.
4.6 Returning a ChainedResponse
When returning responses to a ChainedRequest, the ChainedResponse is
used. If the ChainedResponseValue.operationResponse is a
searchResultDone, the
ChainedResponseValue.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.
4.6.1 ChainedResponse.resultCode
The resultCode for the ChainedResponse is distinct from the result
code of the ChainedResponse.operationResponse. 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.6.2 Returning referrals in the ChainedResponse
<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
4.7 Receiving a ChainedResponse
todo: talk about how the DSA knows when an operation is done
Sermersheim Expires December 30, 2004 [Page 22]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
4.8 Returning a Referral or SearchResultReference
4.9 Acting on a Referral or SearchResultReference
4.10 Ensuring non-existence of an entry under an nssr
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 <TODO: 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 is not able or allowed to chain, but is configured to
return referrals, it will return a referral and include the <TODO:
need another field which conveys the reference type. In this case it
would show that the reference type was NSSR>. The client (after
optionally contacting the DSAs in the referral to ensure the entry to
be added does not exist) may then decide to force the add operation
to be applied by re-sending the Add or ModifyDN request with the
ManageDsaIT control. This will effectively cause the DSA to skip the
check of remote DSAs and proceed with the operation.
<TODO: Alternate #1: If the DSA cannot chain, the operation fails
with affectsMultipleDSAs (ala X.518)>
<TODO: Alternate #2: The DSA assumes there is no entry with the same
name on a remote DSA>
<TODO: Alternate #3: We return a different error (like entryMayExist)
along with the referral. This lets the client know that it's an NSSR
(don't have to add another field to the referral)>
4.11 Using the ManageDsaIT control
This control 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.
Sermersheim Expires December 30, 2004 [Page 23]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
5. Security Considerations
<TODO: Add details.>
6 Normative References
[RFC2079] Smith, M., "Definition of an X.500 Attribute Type and an
Object Class to Hold Uniform Resource Identifiers (URIs)",
RFC 2079, January 1997.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2251] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory
Access Protocol (v3)", RFC 2251, December 1997.
[RFC2255] Howes, T. and M. Smith, "The LDAP URL Format", RFC 2255,
December 1997.
[RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access
Protocol (v3): Technical Specification", RFC 3377,
September 2002.
[X500] International Telephone and Telegraph Consultative
Committee, "The Directory - overview of concepts, models
and services", ITU-T Recommendation X.500, November 1993.
[X680] International International Telephone and Telegraph
Consultative Committee, "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.
Sermersheim Expires December 30, 2004 [Page 24]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
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 December 30, 2004 [Page 25]
Internet-Draft Distributed Procedures for LDAP Operations July 2004
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 (2004). 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 December 30, 2004 [Page 26]
_______________________________________________
Ldapext mailing list
Ldapext@ietf.org
https://www1.ietf.org/mailman/listinfo/ldapext