Eliminate second session protocol version field.

[openldap] / doc / drafts / draft-ietf-ldapext-namedref-xx.txt

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]