mirror/openldap
2
0
Fork 0
mirror of https://git.openldap.org/openldap/openldap.git synced 2024-12-21 03:10:25 +08:00
Code Issues Packages Projects Releases Wiki Activity

Replace expired LDAPext namedref I-D with Zeilenga namedref I-D.

Browse Source 
Add LDAPext refer I-D.
This commit is contained in:
Kurt Zeilenga 2000-07-19 01:24:06 +00:00
parent e82c3ff6b2
commit 368ba56311
3 changed files with 1403 additions and 774 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

774
doc/drafts/draft-ietf-ldapext-namedref-xx.txt
View File

@ -1,774 +0,0 @@
IETF LDAPEXT Working Group Christopher Lukas [Editor]
INTERNET-DRAFT Internet Scout Project
Tim Howes
Netscape Communications Corp.
Michael Roszkowski
Internet Scout Project
Mark C. Smith
Netscape Communications Corp.
Mark Wahl
Critial Angle, Inc.
June 1999
Named Referrals in LDAP Directories
<draft-ietf-ldapext-namedref-00.txt>
1. Status of this Memo
This document is an Internet-Draft and is in full conformance with all
provisions of Section 10 of RFC2026.
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.
Distribution of this document is unlimited. Please send comments to the
authors or the LDAPEXT mailing list, ietf-ldapext@netscape.com.
Copyright Notice: Copyright (C) The Internet Society (1999). All Rights
Reserved.
This draft is a revision of a draft formerly published as draft-ietf-
ldapext-referral-00.txt.
This draft expires December 6, 1999.
Howes, et al. IETF LDAPEXT Working Group [Page 1]
INTERNET-DRAFT LDAPv3 Named Referrals March 1999
2. Abstract
This document defines a "ref" attribute and associated "referral" object
class for representing generic knowledge information in LDAP directories
[RFC2251]. The attribute uses URIs [RFC1738] to represent knowledge,
enabling LDAP and non-LDAP services alike to be referenced. The object
class can be used to construct entries in an LDAP directory containing
references to other directories or services. This document also defines
procedures directory servers should follow when supporting these schema
elements and when responding to requests for which the directory server
does not contain the requested object but may contain some knowledge of
the location of the requested object.
3. Background and intended usage
The broadening of interest in LDAP directories beyond their use as front
ends to X.500 directories has created a need to represent knowledge
information in a more general way. Knowledge information is information
about one or more servers maintained in another server, used to link
servers and services together.
This document defines a general method of representing knowledge infor-
mation in LDAP directories, based on URIs.
The key words "MUST", "SHOULD", and "MAY" used in this document are to
be interpreted as described in [RFC2119].
4. The ref attribute type
This section defines the ref attribute type for holding general
knowledge reference information.
( 2.16.840.1.113730.3.1.34 NAME 'ref' DESC 'URL reference'
EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
USAGE distributedOperation )
The ref attribute type has IA5 syntax and is case sensitive. The ref
attribute is multivalued. Values placed in the attribute MUST conform to
the specification given for the labeledURI attribute defined in
[RFC2079]. The labeledURI specification defines a format that is a URI,
optionally followed by whitespace and a label. This document does not
make use of the label portion of the syntax. Future documents MAY enable
new functionality by imposing additional structure on the label portion
of the syntax as it appears in the ref attribute.
If the URI contained in the ref attribute refers to an LDAPv3 server, it
must be in the LDAP URI format described in [RFC2255].
Howes, et al. IETF LDAPEXT Working Group [Page 2]
INTERNET-DRAFT LDAPv3 Named Referrals March 1999
When returning a referral result, the server must not return the label
portion of the labeledURI as part of the referral. Only the URI portion
of the ref attribute should be returned.
5. Use of the ref attribute
One usage of the ref attribute is defined in this document. Other uses
of the ref attribute MAY be defined in subsequent documents, or by bila-
teral agreement between cooperating clients and servers.
Except when the manageDsaIT control (documented in section 8 of this
document) is present in the operation request, the ref attribute is not
visible to clients, except as its value is returned in referrals or con-
tinuation references.
If the manageDsaIT control is not set, and the entry named in a request
contains the ref attribute, and the entry is not the root DSE, the
server returns an LDAPResult with the resultCode field set to "referral"
and the referral field set to contain the value(s) of the ref attribute
minus any optional trailing whitespace and labels that might be present.
If the manageDsaIT control is not set, and an entry containing the ref
attribute is in the scope of a one level or subtree search request, the
server returns a SearchResultReference for each such entry containing
the value(s) of the entry's ref attribute.
When the manageDsaIT control is present in a request, the server will
treat an entry containing the ref attribute as an ordinary entry, and
the ref attribute as an ordinary attribute, and the server will not
return referrals or continuation references corresponding to ref attri-
butes.
The following sections detail these usages of the ref attribute.
5.1. Named reference
This use of the ref attribute is to facilitate distributed name resolu-
tion or search across multiple servers. The ref attribute appears in an
entry named in the referencing server. The value of the ref attribute
points to the corresponding entry maintained in the referenced server.
While the distinguished name in a value of the ref attribute is typi-
cally that of an entry in a naming context below the naming context held
by the referencing server, it is permitted to be the distinguished name
of any entry. If the ref attribute is multi-valued all the DNs in the
values of the ref attribute SHOULD have the same value. It is the
responsibility of clients to not loop repeatedly if a naming loop is
present in the directory. Administrators SHOULD avoid configuring
Howes, et al. IETF LDAPEXT Working Group [Page 3]
INTERNET-DRAFT LDAPv3 Named Referrals March 1999
naming loops using referrals.
Clients SHOULD perform at least simple "depth-of-referral count" loop
detection by incrementing a counter each time a new set of referrals is
received. Clients MAY perform more sophisticated loop detection, for
example not chasing the same URI twice.
If an entry containing the ref attribute is immediately subordinate to
the base object named in a one level search request, then the referring
server MUST include a scope of "base" in any LDAP URIs returned in the
corresponding SearchResultReference.
5.1.1. Scenarios
The following sections contain specifications of how the ref attribute
should be used in different scenarios followed by examples that illus-
trate that usage. The scenarios described consist of referral operation
when finding a base or target object, referral operation when performing
a one level search, and referral operation when performing a subtree
search.
It is to be noted that, in this document, a search operation is concep-
tually divided into two distinct, sequential phases: (1) finding the
base object where the search is to begin, and (2) performing the search
itself. The operation of the server with respect to referrals in phase
(1) is almost identical to the operation of the server while finding the
target object for a non-search operation.
It is to also be noted that multiple ref attributes are allowed in any
entry and, where these sections refer to a single ref attribute, multi-
ple ref attributes may be substituted and should be processed and
returned as a group in an LDAPResult or search result in the same way as
described for a single attribute. The order of the returned continuation
references within a result is not defined.
5.1.1.1. Example configuration
Howes, et al. IETF LDAPEXT Working Group [Page 4]
INTERNET-DRAFT LDAPv3 Named Referrals March 1999
|------------------------------------------------------------|
| Server A |
| dn: o=abc,c=us dn: o=xyz,c=us |
| o: abc o: xyz |
| ref: ldap://hostB/o=abc,c=us ref: ldap://hostD/o=xyz,c=us |
| ref: ldap://hostC/o=abc,c=us objectclass: referral |
| objectclass: referral objectclass: extensibleObject|
| objectclass: extensibleObject |
|____________________________________________________________|
|---------------------| |---------------------| |---------------------|
| Server B | | Server D | | Server C |
| dn: o=abc,c=us | | dn: o=xyz,c=us | | dn: o=abc,c=us |
| o: abc | | o: xyz | | o: abc |
| other attributes... | | other attributes... | | other attributes... |
|_____________________| |_____________________| |_____________________|
In this example, Server A holds references for two entries: "o=abc,c=us"
and "o=xyz,c=us". For the "o=abc,c=us" entry, Server A holds two refer-
ences, one to Server B and one to Server C. The entries referenced are
replicas of each other. For the "o=xyz,c=us" entry, Server A holds a
single reference to the entry contained in Server D.
In the following protocol interaction examples, the client has contacted
Server A. Server A holds the naming context "c=us".
5.1.1.2. Base or target object considerations
As previously described, the process of generating referrals for a
search can be described in two phases. The first, which is described in
this section, is generating referrals based on the base object specified
in the search. This process is identical to the process of generating
referrals based on the target object while processing other operations
(modify, add, delete, modify DN, and compare) with the sole exception
that for these other operations, the DN in the referral must be modified
in some cases.
If a client requests any of these operations, there are four cases that
the server must handle with respect to the base or target object speci-
fied in the request.
Case 1: The base or target object is not held by the server and is not
subordinate to any object held by the server with a ref attribute.
The handling of this case is described in section 6.
Case 2: The base or target object is held by the server and contains a
ref attribute
Howes, et al. IETF LDAPEXT Working Group [Page 5]
INTERNET-DRAFT LDAPv3 Named Referrals March 1999
In this case, if the type of operation requested is a search or the URI
contained in the ref attribute of the requested base object is NOT an
LDAP URI as defined in [RFC2255], the server should return the URI value
contained in the ref attribute of the base object whose DN is the DN
requested by the client as the base for the operation.
Example:
If the client issues a search in which the base object is "o=xyz,c=us",
server A will return
SearchResultDone "referral" {
ldap://hostD/o=xyz,c=us
}
If the type of operation requested is not a search and the URI contained
in the ref attribute of the requested target object is an LDAP URI
[RFC2255], the server should return a modified form of this URL. The
returned URL must have only the protocol, host, port, and trailing "/"
portion of the URL contained in the ref attribute. The server should
strip any dn, attributes, scope, and filter parts of the URL.
Example:
If the client issues a modify request for the target object of
"o=abc,c=us", server A will return
ModifyResponse "referral" {
ldap://hostB/
ldap://hostC/
}
Case 3: The base or target object is not held by the server, but is
subordinate to an object with a ref attribute held by the server.
If a client requests an operation for which the base or target object is
not held by the server, but is subordinate to one or more objects with a
ref attribute held by the server, the server must return the referral
from the superior held object nearest to the requested base or target
object. Nearest superior object with a referral, in this document, means
an object superior to the base or target object with the DN that has the
most attribute values in common with the DN of the base or target object
and contains a ref attribute.
The process of finding the nearest superior object can be envisioned as
walking up the locally held part of the DIT from the requested base or
target object checking each superior object until either an object with
Howes, et al. IETF LDAPEXT Working Group [Page 6]
INTERNET-DRAFT LDAPv3 Named Referrals March 1999
a ref attribute is found or the top-most locally held object is reached.
Once possible implementation of this algorithm is as follows:
1. Remove the leftmost attribute/value pair from the DN of the
requested base or target object.
2. If the remaining DN represents a locally held object that contains
a ref attribute, that object is the nearest superior object with a
referral. Stop and process the referral as described below.
3. If the remaining DN is the root of the locally held part of the
DIT, stop and proceed as described in section 6.
4. Continue with step 1.
Once the nearest superior object has been identified, if the referral
contained in that object is not an LDAP URI [RFC2255], it should be
returned as-is. If the referral is an LDAP URI, the referral must be
modified, regardless of the type of operation, as case 2 describes for a
non-search requuest. That is, the dn, attributes, scope, and filter
parts of the URL must be stripped from the referral and the referral
returned.
Example:
If the client issues an add request where the target object has a DN of
"cn=Chris Lukas,o=abc,c=us", server A will return
AddResponse "referral" {
ldap://hostB/
ldap://hostC/
}
5.1.1.3. Search with one level scope
For search operations, once the base object has been found and deter-
mined not to contain a ref attribute, the search may progress. Any
entries matching the filter and scope of the search that do NOT contain
a ref attribute are returned to the client normally as described in
[RFC2251]. Any entries matching the filter and one level scope that do
contain a ref attribute must be returned as referrals as described here.
If a matching entry contains a ref attribute and the URI contained in
the ref attribute is NOT an LDAP URI [RFC2255], the server should return
the URI value contained in the ref attribute of that entry in a Sear-
chResultReference.
If a matching entry contains a ref attribute in the LDAP URI syntax
Howes, et al. IETF LDAPEXT Working Group [Page 7]
INTERNET-DRAFT LDAPv3 Named Referrals March 1999
[RFC2255], the URL from the ref attribute must be modified before it is
returned by adding or substituting a "base" scope into the URL. If the
URL does not contain a scope specifier, the "base" scope specifier must
be added. If the URL does contain a scope specifier, the existing scope
specifier must be replaced by the "base" scope.
Example:
If a client requests a one level search of "c=US" then, in addition to
any entries one level below the "c=US" naming context matching the
filter (shown below as "... SearchResultEntry responses ..."), the
server will also return referrals modified to include the "base" scope
to maintain the one level search semantics.
The order of the SearchResultEntry responses and the SearchResultRefer-
ence responses is undefined. One possible sequence is shown.
... SearchResultEntry responses ...
SearchResultReference {
ldap://hostB/o=abc,c=us??base
ldap://hostC/o=abc,c=us??base
}
SearchResultReference {
ldap://hostD/o=xyz,c=us??base
}
SearchResultDone "success"
5.1.1.4. Search with subtree scope
For a search operation with a subtree scope, once the base object has
been found, the search progresses. As with the one level search, any
entries matching the filter and scope of the search that do NOT contain
a ref attribute are returned to the client normally as described in
[RFC2251].
If an entry matching the requested scope and filter contains a ref
attribute, the server should return the URI value in a SearchResul-
tReference.
Example:
If a client requests a subtree search of "c=us", then in addition to any
entries in the "c=us" naming context which match the filter, Server A
will also return two continuation references. As described in the
Howes, et al. IETF LDAPEXT Working Group [Page 8]
INTERNET-DRAFT LDAPv3 Named Referrals March 1999
preceding section, the order of the responses is not defined.
One possible response might be:
... SearchResultEntry responses ...
SearchResultReference {
ldap://hostB/o=abc,c=us
ldap://hostC/o=abc,c=us
}
SearchResultReference {
ldap://hostD/o=xyz,c=us
}
SearchResultDone "success"
6. Superior Reference
An LDAP server may be configured to return a superior reference in the
case where the server does not hold either the requested base object or
an object containing a ref attribute that is superior to that base
object.
An LDAP server's root DSE MAY contain a ref attribute. The values of the
ref attribute in the root DSE that are LDAP URIs SHOULD NOT contain any
dn part, just the host name and optional port number.
If the LDAP server's root DSE contains a ref attribute and a client
requests an object not held by the server and not subordinate to any
held object, the server must return the URI component of the values in
the ref attribute of the root DSE as illustrated in the example.
If the LDAP server's root DSE does not contain a ref attribute, the
server may return one or more references that the server determines via
a method not defined in this document to be appropriate.
The default reference may be to any server that might contain more
knowledge of the namespace than the responding server. In particular,
the client must not expect the superior reference to be identical from
session to session as the reference may be dynamically created by the
server based on the details of the query submitted by the client.
When the server receives an operation for which the base or target entry
of the request is not contained in or subordinate to any naming context
held by the server or a referral entry, the server will return an
LDAPResult with the resultCode set to "referral", and with the referral
Howes, et al. IETF LDAPEXT Working Group [Page 9]
INTERNET-DRAFT LDAPv3 Named Referrals March 1999
field filled with a referral that the server has determined to be
appropriate.
Example:
If a client requests a subtree search of "c=de" from server A in the
example configuration, and server A has the following ref attribute
defined in it's root DSE:
ref: ldap://hostG/
then server A will return
SearchResultDone "referral" {
ldap://hostG/
}
7. The referral object class
The referral object class is defined as follows.
( 2.16.840.1.113730.3.2.6 NAME 'referral' SUP top STRUCTURAL
MAY ( ref ) )
The referral object class is a subclass of top and may contain the
referral attribute. The referral object class should, in general, be
used in conjunction with the extensibleObject object class to support
the naming attributes used in the entry's distinguished name.
Servers must support the ref attribute through use of the referral
object class. Any named reference must be of the referral object class
and will likely also be of the extensibleObject object class to support
naming and use of other attributes.
8. The manageDsaIT control
A client MAY specify the following control when issuing a search, com-
pare, add, delete, modify, or modifyDN request or an extended operation
for which the control is defined.
The control type is 2.16.840.1.113730.3.4.2. The control SHOULD be
marked as critical. There is no value; the controlValue field is
absent.
This control causes entries with the "ref" attribute to be treated as
normal entries, allowing clients to read and modify these entries.
Howes, et al. IETF LDAPEXT Working Group [Page 10]
INTERNET-DRAFT LDAPv3 Named Referrals March 1999
This control is not needed if the entry containing the referral attri-
bute is one used for directory administrative purposes, such as the root
DSE, or the server change log entries. Operations on these entries
never cause referrals or continuation references to be returned.
9. Relationship to X.500 Knowledge References
The X.500 standard defines several types of knowledge references, used
to bind together different parts of the X.500 namespace. In X.500,
knowledge references can be associated with a set of unnamed entries
(e.g., a reference, associated with an entry, to a server containing the
descendants of that entry).
This creates a potential problem for LDAP clients resolving an LDAPv3
URL referral referring to an LDAP directory back-ended by X.500. Sup-
pose the search is a subtree search, and that server A holds the base
object of the search, and server B holds the descendants of the base
object. The behavior of X.500(1993) subordinate references is that the
base object on server A is searched, and a single continuation reference
is returned pointing to all of the descendants held on server B.
An LDAP URI only allows the base object to be specified. It is not pos-
sible using standard LDAP URIs to indicate a search of several entries
whose names are not known to the server holding the superior entry.
X.500 solves this problem by having two fields, one indicating the pro-
gress of name resolution and the other indicating the target of the
search. In the above example, name resolution would be complete by the
time the query reached server B, indicating that it should not refer the
request.
This document does not address this problem. This problem will be
addressed in separate documents which define the changes to the X.500
distribution model and LDAPv3 extensions to indicate the progress of
name resolution.
10. Security Considerations
This document defines mechanisms that can be used to "glue" LDAP (and
other) servers together. The information used to specify this glue
information should be protected from unauthorized modification. If the
server topology information itself is not public information, the infor-
mation should be protected from unauthorized access as well.
Clients should use caution when re-using credentials while following
referrals as the client may be directed to any server which may or may
not respect or use those credentials appropriately.
Howes, et al. IETF LDAPEXT Working Group [Page 11]
INTERNET-DRAFT LDAPv3 Named Referrals March 1999
11. References
[RFC1738]
Berners-Lee, T., Masinter, L., and McCahill, M., "Uniform Resource
Locators (URL)", RFC 1738, CERN, Xerox Corporation, University of
Minnesota, December 1994.
[RFC2079]
M. Smith, "Definition of an X.500 Attribute Type and an Object Class
to Hold Uniform Resource Identifiers (URIs)", RFC 2079, January
1997.
[RFC2119]
S. Bradner, "Key Words for use in RFCs to Indicate Requirement Lev-
els", RFC 2119, March 1997. (Format: TXT=4723 bytes) (Also BCP0014)
(Status: BEST CURRENT PRACTICE)
[RFC2251]
M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
(v3)", RFC 2251, December 1997.
[RFC2255]
T. Howes, M. Smith, "The LDAP URL Format", RFC 2255, December, 1997.
(Format: TXT=20685 bytes) (Status: PROPOSED STANDARD)
[X500]
ITU-T Rec. X.501, "The Directory: Models", 1993.
12. Author's Address
Tim Howes
Netscape Communications Corp.
501 E. Middlefield Rd.
Mailstop MV068
Mountain View, CA 94043
USA
+1 650 937-3419
EMail: howes@netscape.com
Christopher E. Lukas
Internet Scout Project
Computer Sciences Dept.
University of Wisconsin-Madison
1210 W. Dayton St.
Madison, WI 53706
USA
EMail: lukas@cs.wisc.edu
Howes, et al. IETF LDAPEXT Working Group [Page 12]
INTERNET-DRAFT LDAPv3 Named Referrals March 1999
Michael Roszkowski
Internet Scout Project
Computer Sciences Dept.
University of Wisconsin-Madison
1210 W. Dayton St.
Madison, WI 53706
USA
EMail: mfr@cs.wisc.edu
Mark C. Smith
Netscape Communications Corp.
501 E. Middlefield Rd.
Mailstop MV068
Mountain View, CA 94043
USA
EMail: mcs@netscape.com
Mark Wahl
Innosoft International, Inc.
8911 Capital of Texas Hwy #4140
Austin TX 78759
EMail: M.Wahl@innosoft.com
This draft expires December 6, 1999.
Howes, et al. IETF LDAPEXT Working Group [Page 13]

728
doc/drafts/draft-ietf-ldapext-refer-xx.txt Normal file
View File

@ -0,0 +1,728 @@
IETF LDAPEXT Working Group Roland Hedberg
Internet-Draft Catalogix
Expires: January 12, 2000 July 12, 2000
Referrals in LDAP Directories
<draft-ietf-ldapext-refer-00.txt>
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
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 January 12, 2000.
Copyright Notice
Copyright (C) The Internet Society (2000). All Rights Reserved.
Hedberg Expires September 30, 2000 [Page 1]
Internet-Draft LDAP Knowledge references July 2000
Abstract
This document defines two reference attributes and associated "referral"
object class for representing generic knowledge information in LDAP
directories [RFC2251].
The attribute uses URIs [RFC1738] to represent knowledge,
enabling LDAP and non-LDAP services alike to be referenced.
The object class can be used to construct entries in an LDAP directory
containing references to other directories or services. This document
also defines procedures directory servers should follow when supporting
these schema elements and when responding to requests for which the
directory server does not contain the requested object but may contain
some knowledge of the location of the requested object.
1. Background and intended usage
The broadening of interest in LDAP directories beyond their use as front
ends to X.500 directories has created a need to represent knowledge
information in a more general way. Knowledge information is information
about one or more servers maintained in another server, used to link
servers and services together.
This document is based on the following basic assumptions:
- several naming domains
The usage of LDAP as a access protocol to other than X.500 servers has
created islands of directory service systems containing one or more
LDAP servers. Each of these islands are free to pick their own naming
domain. And that they also do; some use the old country,organization,
organizationalUnit naming scheme[X.521], some use the newer domain name
based naming scheme but these two are in no way the only ones in use. The
existence of several naming domains are in itself no real problem as
long as they produce unique names for the objects in the directory.
Still naming schemes like the domain name based one, might easily create
non-continues naming structures because some toplevel domain names
might no find organizations that are interested and/or willing
to manage them. Therefor tree transversal might not longer be possible
except in parts of the whole tree.
- authoritive structure vs directory structure
In some instances even if a part of the tree is delegated to one
organization, the organization doing the delegation might want to
remain as the authority for the baseobject of the delegated tree.
- support for onelevel searches
At points in the tree where the responsibility for all or almost all
of the children of a object is delegated to different organizations
and resides in different directory servers a one-level search is not
very efficient if not supported by special facilities in the directory
as such.
Hedberg Expires September 30, 2000 [Page 2]
Internet-Draft LDAP Knowledge references July 2000
-- directory server discovery
LDAP servers that do not use dc nameing or are not registered with
SRV records in the DNS are very hard to find.
This document defines a general method of representing knowledge
information in LDAP directories, based on URIs.
Two types of knowledge reference are defined: refer and subRefer.
The key words "MUST", "SHOULD", and "MAY" used in this document are to
be interpreted as described in [RFC2119].
2. Knowledge references
2.1 The refer attribute
( 1.2.752.17.1.100
NAME 'refer'
DESC 'URL reference'
EQUALITY caseExactIA5Match
SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
USAGE distributedOperation )
The refer attribute type has IA5 syntax and is case sensitive.
It is multivalued. Values placed in the attribute MUST conform to the
specification given for the labeledURI attribute as defined in [RFC2079].
The labeledURI specification defines a format that is a URI,
optionally followed by whitespace and a label. This document does not
make use of the label portion of the syntax. Future documents MAY enable
new functionality by imposing additional structure on the label portion
of the syntax as it appears in a refer attribute.
If the URI contained in a refer attribute refers to an LDAP
server, it must be in the LDAP URI format described in [RFC2255].
When returning a referral result, the server must not return the label
portion of the labeledURI as part of the referral. Only the URI portion
of the refer attributes should be returned.
The refer attribute can be further specified by the use of options as
defined in section 4.1.5 of [RFC2251]. This document defines five
options and their use. Future documents might defined other options.
The options defined are:
"me", "sup", "cross", "nssr" and "sub" .
'refer;me' is used to hold the reference of this server, and is always
held in the root DSE
'refer;sup' is used to hold the reference of a server superior to this
one in this global LDAP naming domain e.g. a server holding the dc=com,
dc=se, or the c=se node. The 'refer;sup' is always held in the root DSE.
Hedberg Expires September 30, 2000 [Page 3]
Internet-Draft LDAP Knowledge references July 2000
'refer;cross' indicates that this is a cross reference pointing to another
naming context within or outside this global LDAP naming domain.
'refer;sub' indicates that this is a subordinate reference pointing to
a subordinate naming context in this global LDAP naming domain.
'refer;nssr' indicates that this is a non-specific subordinate reference
pointing to a subordinate naming context in this global LDAP naming domain.
3. Use of the knowledge attribute
Except when the manageDsaIT control (documented in section 6 of this
document) is present in the operation request, the refer attribute is not
visible to clients, except as its value is returned in referrals or con-
tinuation references.
If the manageDsaIT control is not set, and the entry named in a request
contains the refer attribute, and the entry is not the root DSE, the
server returns an LDAPResult with the resultCode field set to "referral"
and the referral field set to contain the value(s) of the refer attribute
minus any optional trailing whitespace and labels that might be present.
If the manageDsaIT control is not set, and an entry containing the ref
attribute is in the scope of a one level or subtree search request, the
server returns a SearchResultReference for each such entry containing
the value(s) of the entry's refer attribute.
When the manageDsaIT control is present in a request, the server will
treat an entry containing the refer attribute as an ordinary entry, and
the refer attribute as an ordinary attribute, and the server will not
return referrals or continuation references corresponding to refer
attributes.
4 Behaviour specification
4.1 Name resolution for any operation
Clients SHOULD perform at least simple "depth-of-referral count" loop
detection by incrementing a counter each time a new set of referrals is
received. (The maximum value for this count SHOULD be twice the number
of RDNs in the target object less one, to allow for ascending and
descending the DIT.) Clients MAY perform more sophisticated loop
detection, for example not chasing the same referral twice.
Case 1: The target entry is not held by the server and is
superior to some entry held by the server.
If the server DSE contains a "refer;sup" attribute then
the server will return an LDAPResult with the result code field set
Hedberg Expires September 30, 2000 [Page 4]
Internet-Draft LDAP Knowledge references July 2000
to referral, and the referral field set to contain the value(s) of
the "refer;sup" attribute minus any optional trailing whitespace and
labels that might be present.
Case 2: The target entry is not held by the server and is
subordinate to some entry, held by the server, that contains a
refer attribute.
The server will return an LDAPResult with the result code field set
to referral, and the referral field set to contain the value(s) of
the refer attribute minus any optional trailing whitespace and labels
that might be present.
Case 3: The target entry is held by the server and contains a
refer attribute without the 'nssr' option.
The server will return an LDAPResult with the result code field set
to referral, and the referral field set to contain the value(s) of
the refer attribute minus any optional trailing whitespace and labels
that might be present.
Case 4: The target entry is not held by the server, and is not
subordinate or superior to any object held by the server.
If the server contains a "refer;cross" attribute
in the root DSE with a baseobject that is either the same or
superior to the target entry then
the server will return an LDAPResult with the result code field set
to referral, and the referral field set to contain the value(s) of
these refer attributes minus any optional trailing whitespace and labels
that might be present.
4.2 Search evaluation
For search operations, once the base object has been found and
determined NOT to contain a refer attribute without the 'nssr'
option, the search may progress.
4.2.1 base-level
If the entry matches the filter and does NOT contain a refer attribute
it will be returned to the client as described in [RFC2251].
If the entry matches the filter contains a refer attribute without
the 'nssr' option it will be returned as a referral as described here.
If a matching entry contains a refer attribute and the URI
contained in the refer attribute is NOT an LDAP URI [RFC2255],
the server should return the URI value contained in the refer
attribute of that entry in a SearchResultReference.
Hedberg Expires September 30, 2000 [Page 5]
Internet-Draft LDAP Knowledge references July 2000
If a matching entry contains a refer attribute in the LDAP
URI syntax, the server will return an SearchResultReference
containing the value(s) of the refer attribute minus any optional
trailing whitespace and labels that might be present.
The URL from the refer attribute must be modified before it is
returned by adding or substituting a "base" scope into the URL. If the
URL does not contain a scope specifier, the "base" scope specifier must
be added. If the URL does contain a scope specifier, the existing scope
specifier must be replaced by the "base" scope.
4.2.2 One-level
Any entries matching the filter and one level scope that
do NOT contain a refer attribute are returned to the client normally as
described in [RFC2251]. Any entries matching the filter and one level
scope that contains a refer attribute without the 'nssr' option must
be returned as referrals as described here.
If a matching entry contains a refer attribute and the URI
contained in the refer attribute is NOT an LDAP URI [RFC2255],
the server should return the URI value contained in the refer
attribute of that entry in a SearchResultReference.
If a matching entry contains a refer attribute in the LDAP
URI syntax, the server will return an SearchResultReference
containing the value(s) of the refer attribute minus any optional
trailing whitespace and labels that might be present.
The URL from the refer attribute must be modified before it is
returned by adding or substituting a "base" scope into the URL. If the
URL does not contain a scope specifier, the "base" scope specifier must
be added. If the URL does contain a scope specifier, the existing scope
specifier must be replaced by the "base" scope.
4.2.3 Subtree search evaluation
Any entries, held by the server, matching the filter and
subtree scope that do NOT contain a refer attribute or contains
a refer attribute with the 'nssr' option are
returned to the client normally as described in [RFC2251].
Any entries matching the subtree scope and containing a refer
attribute must be returned as referrals as described here.
If a matching entry contains a refer attribute and the URI
contained in that attribute is NOT an LDAP URI [RFC2255],
the server should return the URI value contained in the refer
attribute of that entry in a SearchResultReference.
Hedberg Expires September 30, 2000 [Page 6]
Internet-Draft LDAP Knowledge references July 2000
If a matching entry contains a refer attribute in the LDAP
URI syntax, the server will return an SearchResultReference
containing the value(s) of the refer attribute minus any
optional trailing whitespace and labels that might be present.
N.B. in subtree search evaluation a entry containing a
refer attribut with the 'nssr' option might appear twice in the
result, first as a entry and then as a reference. A client
following all references might therefore end up with a resultset
containing two representations of the same entry, one from the
server getting the original query and one from the server
that the 'nssr' reference points to.
5. The referral object class
The referral object class is defined as follows.
( 1.2.752.17.2.10
NAME 'referral'
SUP top
STRUCTURAL
MAY ( refer ) )
The referral object class is a subclass of top and may contain the
refer attribute. The referral object class should, in general,
be used in conjunction with the extensibleObject object class to support
the naming attributes used in the entry's distinguished name.
Servers must support the refer attributes through use of the
referral object class. Any named reference must be of the referral
object class and will likely also be of the extensibleObject object
class to support naming and use of other attributes.
6. The manageDsaIT control
A client MAY specify the following control when issuing a search, com-
pare, add, delete, modify, or modifyDN request.
The control type is 2.16.840.1.113730.3.4.2. The control SHOULD be
marked as critical. There is no value; the controlValue field is
absent.
This control causes entries with the knowledge reference attributes to be
treated as normal entries, allowing clients to read and modify these entries.
Hedberg Expires September 30, 2000 [Page 7]
Internet-Draft LDAP Knowledge references July 2000
7. Superior Reference
This document defines two types of knowledge references that point to
parts of the naming context that is above of beyone the part held by a server.
The 'sup' option when referring to a LDAP server that holds a
naming context that is closer to the root of the same naming context and
'other' when referring to a LDAP server that holds a naming
context that belongs to a different naming domain then the one the
server belongs to.
Thus if the server receives a request for an operation where the
target entry is a entry closer to the root than the naming
context held the server and if the server holds a 'refer;sup' attribute
in the DSE, then the server MUST return an LDAPResult with the result
code field set to referral, and the referral field set to contain the
value(s) of the 'refer;sub' attribute minus any optional trailing
whitespace and labels that might be present.
On the other hand if the server receives a request for an operation
where the target entry is a entry that belongs to a other naming domain
and if there is any 'refer;other' attributes in the DSE with a base entry
that belongs to the same naming domain as the target entry and is
closer to the root then the target entry, then the server SHOULD return
an LDAPResult with the result code field set to referral, and the referral
field set to contain the value(s) of the 'refer;other' attribute minus
any optional trailing hitespace and labels that might be present.
8. Security Considerations
This document defines mechanisms that can be used to "glue" LDAP (and
other) servers together. The information used to specify this glue
information should be protected from unauthorized modification. If the
server topology information itself is not public information, the
information should be protected from unauthorized access as well.
9. References
[RFC1738]
Berners-Lee, T., Masinter, L., and McCahill, M., "Uniform Resource
Locators (URL)", RFC 1738, CERN, Xerox Corporation, University of
Minnesota, December 1994,
[RFC2079]
M. Smith, "Definition of an X.500 Attribute Type and an Object Class
to Hold Uniform Resource Identifiers (URIs)", RFC 2079, January
1997.
Hedberg Expires September 30, 2000 [Page 8]
Internet-Draft LDAP Knowledge references July 2000
[RFC2119]
S. Bradner, "Key Words for use in RFCs to Indicate Requirement Lev-
els", RFC 2119, March 1997. (Format: TXT=4723 bytes) (Also BCP0014)
(Status: BEST CURRENT PRACTICE)
[RFC2251]
M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
(v3)", RFC 2251, December 1997. 1997.
[RFC2255]
T. Howes, M. Smith, "The LDAP URL Format", RFC 2255, December, 1997.
(Format: TXT=20685 bytes) (Status: PROPOSED STANDARD)
[X500]
ITU-T Rec. X.501, "The Directory: Models", 1993.
[X521]
ITU-T Rec. X.521, "---------------------", 1993.
12. Acknowledgements
This draft is heavily based on the previous drafts on knowledge
references in LDAP written by Christopher Lukas, Tim Howes,
Michael Roszkowski, Mark C. Smith, Mark Wahl and David Chadwick.
Peter Valkenburg and Henny Bekker has also made valueable
contributions.
13. Authors Address
Roland Hedberg
Catalogix
Dalsveien 53
0775 Oslo
Norway
EMail: Roland@catalogix.se
Hedberg Expires September 30, 2000 [Page 9]
Internet-Draft LDAP Knowledge references July 2000
Appendix A
Example of usage.
Information stored in a server.
dn:
objectclass: referral
refer;me: ldap://hostCAT/dc=cat,dc=se
refer;sup: ldap://hostSE/dc=se
refer;cross: ldap://hostNO/dc=no
refer;cross: ldap://hostNL/c=nl
dn: dc=cat,dc=se
objectclass: domain
dc: cat
dn: dc=one,dc=cat,dc=se
objectclass: extendedObject
objectclass: referral
refer;nssr: ldap://hostCAT1/dc=one,dc=cat,dc=se
ou: one
l: umea
dc: dc=two,dc=cat,dc=se
objectclass: referral
objectclass: extendedObject
refer;sub: ldap://hostCAT2/dc=two,dc=cat,dc=se
dn: dc=three,dc=cat,dc=se
objectclass: referral
objectclass: extendedObject
refer;cross: ldap://hostCAT3/dc=cat,dc=nl
dc: dc=four,dc=cat,dc=se
objectclass: domain
objectclass: extendedObject
ou: four
l: umea
Hedberg Expires September 30, 2000 [Page 10]
Internet-Draft LDAP Knowledge references July 2000
==========================================
A number of descriptive cases
==========================================
case 1: One-level search, target object on the server
search
baseobject: dc=cat,dc=se
scope: onelevel
filter: (objectclass=*)
attributes: ou
returns
searchResultEntry {
dn: dc=one,dc=cat,dc=se
ou: one
}
searchResultReference {
ldapurl: ldap://hostCAT2/dc=two,dc=cat,dc=se
}
searchResultReference {
ldapurl: ldap://hostCAT3/dc=cat,dc=nl
}
searchResultEntry {
dn: dc=four,dc=cat,dc=se
ou: four
}
searchResultDone {
resultCode: success
}
case 2: Subtree search, target object on the server
search
baseobject: dc=cat,dc=se
scope: subtree
filter: (objectclass=*)
attributes: ou
returns
searchResultEntry {
dn: dc=one,dc=cat,dc=se
ou: one
}
searchResultReference {
ldapurl: ldap://hostCAT1/dc=one,dc=cat,dc=se
}
searchResultReference {
ldapurl: ldap://hostCAT2/dc=two,dc=cat,dc=se
}
Hedberg Expires September 30, 2000 [Page 11]
Internet-Draft LDAP Knowledge references July 2000
searchResultReference {
ldapurl: ldap://hostCAT3/dc=cat,dc=nl
}
searchResultEntry {
dn: dc=four,dc=cat,dc=se
ou: four
}
searchResultDone {
resultCode: success
}
case 3: base search, target entry contains a 'refer;nssr' attribute
search
baseobject: dc=one,dc=cat,dc=se
scope: base
filter: (objectclass=*)
attributes: ou
returns
searchResultEntry {
dn: dc=one,dc=cat,dc=se
ou: four
}
searchResultDone {
resultCode: success
}
case 4: base search, target entry contains a 'refer;sub' attribute
search
baseobject: dc=two,dc=cat,dc=se
scope: base
filter: (objectclass=*)
attributes: ou
returns
searchResultDone {
resultCode: referral
matchedDN: dc=two,dc=cat,dc=se
referral: ldap://hostCAT2/dc=two,dc=cat,dc=se
}
Hedberg Expires September 30, 2000 [Page 12]
Internet-Draft LDAP Knowledge references July 2000
case 5: one-level search, target entry contains a 'refer;nssr' attribute
search
baseobject: dc=one,dc=cat,dc=se
scope: onelevel
filter: (objectclass=*)
attributes: ou
searchResultDone {
resultCode: referral
matchedDN: dc=one,dc=cat,dc=se
referral: ldap://hostCAT1/dc=one,dc=cat,dc=nu
}
case 6: Search on area above the baseobject of the server
search
baseobject: dc=pi,dc=se
scope: subtree
filter: (objectclass=*)
attributes: ou
returns
searchResultDone {
resultCode: referral
matchedDN: dc=se
referral: ldap://hostSE/dc=se
}
case 7: Search on area beyond, but not below the baseobject
of the server
search
baseobject: o=surfnet,c=nl
scope: base
filter: (objectclass=*)
returns
searchResultDone {
resultCode: referral
matchedDN: c=nl
referral: ldap://hostNL/c=NL
}
Hedberg Expires September 30, 2000 [Page 13]

675
doc/drafts/draft-zeilenga-ldap-namedref-xx.txt Normal file
View File

@ -0,0 +1,675 @@
INTERNET-DRAFT Kurt D. Zeilenga
Intended Category: Standard Track OpenLDAP Foundation
Expires: 4 January 2001 4 July 2000
Named References in LDAP Directories
<draft-zeilenga-ldap-namedref-00.txt>
1. Status of this Memo
This document is an Internet-Draft and is in full conformance with all
provisions of Section 10 of RFC2026.
This document is intended to be, after appropriate review and
revision, submitted to the RFC Editor as a Standard Track document.
Distribution of this memo is unlimited. Technical discussion of this
document will take place on the IETF LDAP Extension Working Group
mailing list <ietf-ldapext@netscape.com>. Please send editorial
comments directly to the author <Kurt@OpenLDAP.org>.
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.
Copyright 2000, The Internet Society. All Rights Reserved.
Please see the Copyright section near the end of this document for
more information.
2. Abstract
This document defines schema and protocol elements for representing
and manipulating generic knowledge information in LDAP [RFC2251]
directories. An attribute type "ref" is used to store URIs [RFC1738]
which may refer to LDAP and non-LDAP services. An object class
"referral" is used to construct entries in an LDAP directory which
references to other directories or services. An control, ManageDsaIT,
is defined to allow clients to manipulate referral objects as normal
entries. The document describes procedures directory servers should
follow when supporting these elements.
Zeilenga [Page 1]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
3. Background and intended usage
The broadening of interest in LDAP directories beyond their use as
front ends to X.500 directories has created a need to represent
knowledge information in a more general way. Knowledge information is
information about one or more servers maintained in another server,
used to link servers and services together.
This document defines a general method of representing knowledge
information in LDAP directories, based on URIs.
This document does not detail client processing of referral and search
reference responses. This is detailed in RFC 2251 or subsequent
documents.
The key words "SHALL", "SHALL NOT", "MUST", "MUST NOT", "SHOULD",
"SHOULD NOT", "MAY" and "MAY NOT" used in this document are to be
interpreted as described in [RFC2119].
4. Schema
4.1 The ref attribute type
This section defines the ref attribute type for holding general
knowledge reference information.
( 2.16.840.1.113730.3.1.34
NAME 'ref'
DESC 'URI reference'
EQUALITY caseExactIA5Match
SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
USAGE distributedOperation )
The ref attribute type has IA5 syntax and is case sensitive. The ref
attribute is multi valued. Values placed in the attribute MUST conform
to the specification given for the labeledURI attribute defined in
[RFC2079]. The labeledURI specification defines a format that is a
URI, optionally followed by whitespace and a label. This document does
not make use of the label portion of the syntax. Future documents MAY
enable new functionality by imposing additional structure on the label
portion of the syntax as it appears in the ref attribute.
If the URI contained in a ref attribute value refers to an LDAPv3
server, it MUST be in the LDAP URI scheme described in [RFC2255].
Other URI schemes MAY be used but MUST refer to services which are
capable of completing operations referred to the services. The URI
values, regardless of scheme, contained in a ref attribute must point
Zeilenga [Page 2]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
to services which are equally capable of handling operations refer to
said services.
The integrity of the URI SHALL NOT be validated by the server holding
or returning the reference.
When returning a referral result, the server MUST NOT return the label
portion of the labeledURI as part of the referral. Only the URI
portion of the ref attribute SHOULD be returned.
The ref attribute SHOULD NOT be used for naming.
4.2. The referral object class
The referral object class is defined as follows.
( 2.16.840.1.113730.3.2.6
NAME 'referral'
DESC 'named reference object'
STRUCTURAL MUST ref )
The referral object class is a structural object class used to
represent a named reference in the directory. The referral object
class SHOULD be used in conjunction with the extensibleObject object
class to support the naming attributes used in the entry's
distinguished name.
In the presence of a ManageDsaIT control, referral objects are treated
as normal entries. Note that the ref attribute is operational and
will only returned in a search entry response when requested.
In the absence of a ManageDsaIT control, referral objects contents are
used to construct referrals and search references and, as such, the
referral entries themselves are general visible to clients.
5. Use of the ref attribute
Two uses the ref attribute is defined in this document. The first
use, in conjunction with the referral object class, represents a named
reference. The second use, in conjunction with the Root DSE,
represents superior reference. The following sections detail these
usages of the ref attribute.
Other uses of the ref attribute MAY be defined in subsequent
documents, or by bilateral agreement between cooperating clients and
servers and SHOULD be defined in conjunction with an object class
Zeilenga [Page 3]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
indicating the usage.
5.1. Named reference
A named reference is used to facilitate distributed name resolution or
search across multiple servers. The ref attribute appears in an
referral object (an entry with object class of referral) named in the
referencing server. The value of the ref attribute points to the
corresponding entry maintained in the referenced server.
While the distinguished name in a value of the ref attribute is
typically that of an entry in a naming context below the naming
context held by the referencing server, it is permitted to be the
distinguished name of any entry. If the ref attribute is multi-valued
all the DNs in the values of the ref attribute SHOULD have the same
value. Administrators SHOULD avoid configuring naming loops using
referrals.
The URI SHOULD NOT explicitly define a scope and the server SHOULD NOT
explicitly add a scope to the URI before returning it to the client as
a referral or search reference as the scope is implied by the
operation.
Named references MUST be treated as normal entries if the request
includes the ManageDsaIT control. The remainder of this section
describes processing of requests which do not include the ManageDsaIT
control.
5.1.1. Scenarios
The following sections contain specifications of how referral objects
should be used in different scenarios followed by examples that
illustrate that usage. The scenarios described consist of referral
operation when finding target of a non-search operation, when finding
the base of a search operation, and when generating search references.
It is to be noted that, in this document, a search operation is
conceptually divided into two distinct, sequential phases: (1) finding
the base object where the search is to begin, and (2) performing the
search itself. The operation of the server with respect to referrals
in phase (1) is similar to the operation of the server while finding
the target object for a non-search operations.
It is to also be noted that the ref attribute may have multiple values
and, where these sections refer to a single ref attribute value,
multiple ref attribute values may be substituted and SHOULD be
Zeilenga [Page 4]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
processed and returned as a group in a referral or search reference in
the same way as described for a single ref attribute value.
Search references returned for a given request may be returned in any
order.
5.1.1.1. Example configuration
|------------------------------------------------------------|
| Server A |
| dn: o=abc,c=us dn: o=xyz,c=us |
| o: abc o: xyz |
| ref: ldap://hostB/o=abc,c=us ref: ldap://hostD/o=xyz,c=us |
| ref: ldap://hostC/o=abc,c=us objectclass: referral |
| objectclass: referral objectclass: extensibleObject|
| objectclass: extensibleObject |
|____________________________________________________________|
|------------------| |------------------| |------------------|
| Server B | | Server D | | Server C |
| dn: o=abc,c=us | | dn: o=xyz,c=us | | dn: o=abc,c=us |
| o: abc | | o: xyz | | o: abc |
| other attributes | | other attributes | | other attributes |
|__________________| |__________________| |__________________|
In this example, Server A holds references for two entries:
"o=abc,c=us" and "o=xyz,c=us". For the "o=abc,c=us" entry, Server A
holds two references, one to Server B and one to Server C. The
entries referenced are replicas of each other. For the "o=xyz,c=us"
entry, Server A holds a single reference to the entry contained in
Server D.
In the following protocol interaction examples, the client has
contacted Server A. Server A holds the naming context "c=us".
5.1.1.2. Base or Target object considerations
As previously described, the process of generating referrals for a
search can be described in two phases. The first, which is described
in this section, is generating referrals based on the base object
specified in the search. This process is similar to the process of
generating referrals based on the target object while processing other
operations (modify, add, delete, modify DN, and compare) with the sole
exception that for these other operations, the DN in the referral must
be modified in some cases.
Zeilenga [Page 5]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
If a client requests any of these operations, there are four cases
that the server must handle with respect to the base or target object
specified in the request.
Case 1: The base or target object is not held by the server and is not
within or subordinate to any naming context nor is subordinate to any
referral object held by the server.
The handling of this case is described in section 6.
Case 2: The base or target object is held by the server and is a
referral object.
In this case, if the type of operation requested is a search or the
URI contained in the ref attribute of the requested base object is NOT
an LDAP URI, the server SHOULD return the URI value contained in the
ref attribute of the base object whose DN is the DN requested by the
client as the base for the operation.
Example:
If the client issues a search in which the base object is
"o=xyz,c=us", server A will return
SearchResultDone "referral" {
ldap://hostD/o=xyz,c=us
}
If the type of operation requested is not a search and the URI
contained in the ref attribute of the requested target object is an
LDAP URI, the server SHOULD return a modified form of this URI. The
returned URI MUST have only the protocol, host, port, and trailing "/"
portion of the URI contained in the ref attribute. The server SHOULD
strip any DN, attributes, scope, and filter parts of the URI.
Example:
If the client issues a modify request for the target object of
"o=abc,c=us", server A will return
ModifyResponse "referral" {
ldap://hostB/
ldap://hostC/
}
Case 3: The base or target object is not held by the server, but is
object where the nearest naming context contains no referral object
which the base or target object is subordinate to.
Zeilenga [Page 6]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
In the context of this document, the nearest naming context means the
deepest context which the object is within. That is, if the object is
within multiple naming contexts, the nearest naming context the one
which is subordinate to all other naming contexts the object is
within.
If the nearest naming context contains no referral object which the
base or target object is subordinate to the request, request SHOULD be
process normally as appropriate for a nonexistent base or target
object (generally return noSuchObject).
Case 4: The base or target object is not held by the server, but is
object where the nearest naming context contains a referral object
which the base or target object is subordinate to.
As noted above, the nearest naming context means the deepest context
which the object is within.
If a client requests an operation for which the base or target object
is not held by the server but the nearest naming context contains a
referral object which the base or target object is subordinate to, the
server MUST return a referral response which contains referral values
constructed from the URI components of ref attribute values of the
referral object.
For each ref attribute value, if the URI component is not an LDAP
URIs, it SHOULD be returned as-is. If URI component is an LDAP URI,
the URI MUST be modified, regardless of the type of operation, as case
2 describes for a non-search request. That is, the DN, attributes,
scope, and filter parts of the URI MUST be stripped from the returned
URI.
Example:
If the client issues an add request where the target object has a DN
of "cn=Chris Lukas,o=abc,c=us", server A will return
AddResponse "referral" {
ldap://hostB/
ldap://hostC/
}
5.1.1.3. Search with one level or subtree scope
For search operations, once the base object has been found and
determined not to be a referral object, the search may progress. Any
entries matching the filter and scope of the search which is not a
Zeilenga [Page 7]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
referral object are returned to the client normally as described in
[RFC2251].
For each referral object within the requested scope, regardless of the
filter, the server SHOULD return a SearchResultReference which is
constructed from the URI component of values of the ref attribute. If
the URI component is not an LDAP URI, it should be returned as is. If
the URI component is an LDAP URI, the URI must be modified to remove
any explicit scope specifier.
One Level Example:
If a client requests a one level search of "c=US" then, in addition to
any entries one level below the "c=US" naming context matching the
filter (shown below as "... SearchResultEntry responses ..."), the
server will also return search references for any referral object
within the scope of the search.
The order of the SearchResultEntry responses and the
SearchResultReference responses is undefined. One possible sequence
is shown.
... SearchResultEntry responses ...
SearchResultReference {
ldap://hostB/o=abc,c=us
ldap://hostC/o=abc,c=us
}
SearchResultReference {
ldap://hostD/o=xyz,c=us
}
SearchResultDone "success"
Subtree Example:
If a client requests a subtree search of "c=us", then in addition to
any entries in the "c=us" naming context which match the filter,
Server A will also return two continuation references. As described in
the preceding section, the order of the responses is not defined.
One possible response might be:
SearchResultReference {
ldap://hostB/o=abc,c=us
ldap://hostC/o=abc,c=us
Zeilenga [Page 8]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
}
... SearchResultEntry responses ...
SearchResultReference {
ldap://hostD/o=xyz,c=us
}
SearchResultDone "success"
6. Superior Reference
An LDAP server may be configured to return a superior reference in the
case where the requested base or target object is not contained within
or subordinate to a naming context held by the server or referral
object.
An LDAP server's root DSE MAY contain a ref attribute. The values of
the ref attribute in the root DSE that are LDAP URIs SHOULD NOT
contain any DN part nor other search parameters (scope, filter,
attribute list). They MUST include the URI hostpart.
If the LDAP server's root DSE contains a ref attribute and a client
requests a target or base object not held by the server and not
contained within or subordinate to any naming context held by the
server or referral object, the server MUST return the URI component of
the values in the ref attribute of the root DSE as illustrated in the
example.
If the LDAP server's root DSE does not contain a ref attribute, the
server may return referral result with or more URIs determined via an
appropriate method, return noSuchObject, or other appropriate
resultCode.
The presence of the ref attribute within the root DSE SHALL NOT cause
operations upon the root DSE to generate a referral.
Example:
If a client requests a subtree search of "c=de" from server A in the
example configuration, and server A has the following ref attribute
defined in it's root DSE:
ref: ldap://hostG/
then server A will return
Zeilenga [Page 9]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
SearchResultDone "referral" {
ldap://hostG/
}
8. The ManageDsaIT control
The ManageDsaIT control indicates that the operation has been
requested so that the DSA (server) Information Tree is managed. The
controls causes DSEs, regardless of type, to be treated as normal
entries allowing clients to interrogate and update these entries using
LDAP operations. This control is analogous to the ManageDsaIT option
described in X.511(93) [X.511].
A client MAY specify the following control when issuing an add,
compare, delete, modify, modifyDN, search request or an extended
operation for which the control is defined.
The control type is 2.16.840.1.113730.3.4.2. The control criticality
may be TRUE or FALSE. There is no value; the controlValue field is
absent.
When present in the request, the server SHALL NOT generate a referral
or continuation reference for any referral object and instead perform
treat the referral object as an normal entry. When not present,
referral objects SHALL be handled as described above.
The control MAY cause other objects to be treated as normal entries as
defined by subsequent documents.
9. Relationship to X.500 Knowledge References
The X.500 standard defines several types of knowledge references, used
to bind together different parts of the X.500 namespace. In X.500,
knowledge references can be associated with a set of unnamed entries
(e.g., a reference, associated with an entry, to a server containing
the descendants of that entry).
This creates a potential problem for LDAP clients resolving an LDAPv3
URI referral referring to an LDAP directory back-ended by X.500.
Suppose the search is a subtree search, and that server A holds the
base object of the search, and server B holds the descendants of the
base object. The behavior of X.500(1993) subordinate references is
that the base object on server A is searched, and a single
continuation reference is returned pointing to all of the descendants
held on server B.
Zeilenga [Page 10]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
An LDAP URI only allows the base object to be specified. It is not
possible using standard LDAP URIs to indicate a search of several
entries whose names are not known to the server holding the superior
entry.
X.500 solves this problem by having two fields, one indicating the
progress of name resolution and the other indicating the target of the
search. In the above example, name resolution would be complete by the
time the query reached server B, indicating that it should not refer
the request.
This document does not address this problem. This problem will be
addressed in separate documents which define the changes to the X.500
distribution model and LDAPv3 extensions to indicate the progress of
name resolution.
10. Security Considerations
This document defines mechanisms that can be used to "glue" LDAP (and
other) servers together. The information used to specify this glue
information should be protected from unauthorized modification. If
the server topology information itself is not public information, the
information should be protected from unauthorized access as well.
11. References
[RFC1738] Berners-Lee, T., Masinter, L., and McCahill, M., "Uniform
Resource Locators (URL)", RFC 1738, CERN, Xerox Corporation,
University of Minnesota, December 1994.
[RFC2079] M. Smith, "Definition of an X.500 Attribute Type and an
Object Class to Hold Uniform Resource Identifiers (URIs)",
RFC 2079, January 1997.
[RFC2119] S. Bradner, "Key Words for use in RFCs to Indicate
Requirement Levels", RFC 2119 (Also BCP0014), March 1997.
[RFC2251] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
Protocol (v3)", RFC 2251, December 1997.
[RFC2255] T. Howes, M. Smith, "The LDAP URL Format", RFC 2255,
December, 1997.
[X.500] ITU-T Rec. X.501, "The Directory: Models", 1993.
[X.511] ITU-T Rec. X.511, "The Directory: Abstract Service
Zeilenga [Page 11]
INTERNET-DRAFT draft-zeilenga-ldap-namedref-00 4 July 2000
Definition", 1993.
12. Acknowledgments
This document is borrows heavily from previous work by IETF LDAPext
working group. In particular, this document is based upon "Named
Referral in LDAP Directories" (a work in progress) by Christopher
Lukes, Tim Howes, Michael Roszkowski, Mark C. Smith, and Mark Wahl.
13. Author's Address
Kurt D. Zeilenga
OpenLDAP Foundation
<Kurt@OpenLDAP.org>
This draft expires 4 Jan. 2001.
Zeilenga [Page 12]