openldap/doc/drafts/draft-zeilenga-ldap-namedref-xx.txt

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]