rfc3296.txt

samba最新软件

Network Working Group                                        K. Zeilenga
Request for Comments: 3296                           OpenLDAP Foundation
Category: Standards Track                                      July 2002


                    Named Subordinate References in
        Lightweight Directory Access Protocol (LDAP) Directories

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2002).  All Rights Reserved.

Abstract

   This document details schema and protocol elements for representing
   and managing named subordinate references in Lightweight Directory
   Access Protocol (LDAP) Directories.

Conventions

   Schema definitions are provided using LDAPv3 description formats
   [RFC2252].  Definitions provided here are formatted (line wrapped)
   for readability.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" used in
   this document are to be interpreted as described in BCP 14 [RFC2119].

1.  Background and Intended Usage

   The broadening of interest in LDAP (Lightweight Directory Access
   Protocol) [RFC2251] directories beyond their use as front ends to
   X.500 [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 details schema and protocol elements for representing
   and manipulating named subordinate references in LDAP directories.  A
   referral object is used to hold subordinate reference information in



Zeilenga                    Standards Track                     [Page 1]

RFC 3296    Named Subordinate References in LDAP Directories   July 2002


   the directory.  These referral objects hold one or more URIs
   [RFC2396] contained in values of the ref attribute type and are used
   to generate protocol referrals and continuations.

   A control, ManageDsaIT, is defined to allow manipulation of referral
   and other special objects as normal objects.  As the name of control
   implies, it is intended to be analogous to the ManageDsaIT service
   option described in X.511(97) [X.511].

   Other forms of knowledge information are not detailed by this
   document.  These forms may be described in subsequent documents.

   This document details subordinate referral processing requirements
   for servers.  This document does not describe protocol syntax and
   semantics.  This is detailed in RFC 2251 [RFC2251].

   This document does not detail use of subordinate knowledge references
   to support replicated environments nor distributed operations (e.g.,
   chaining of operations from one server to other servers).

2.  Schema

2.1.  The referral Object Class

   A referral object is a directory entry whose structural object class
   is (or is derived from) the referral object class.

      ( 2.16.840.1.113730.3.2.6
          NAME 'referral'
          DESC 'named subordinate reference object'
          STRUCTURAL
          MUST ref )

   The referral object class is a structural object class used to
   represent a subordinate 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 (DN) [RFC2253].

   Referral objects are normally instantiated at DSEs immediately
   subordinate to object entries within a naming context held by the
   DSA.  Referral objects are analogous to X.500 subordinate knowledge
   (subr) DSEs [X.501].








Zeilenga                    Standards Track                     [Page 2]

RFC 3296    Named Subordinate References in LDAP Directories   July 2002


   In the presence of a ManageDsaIT control, referral objects are
   treated as normal entries as described in section 3.  Note that the
   ref attribute is operational and will only be returned in a search
   entry response when requested.

   In the absence of a ManageDsaIT control, the content of referral
   objects are used to construct referrals and search references as
   described in Section 4 and, as such, the referral entries are not
   themselves visible to clients.

2.2  The ref Attribute Type

      ( 2.16.840.1.113730.3.1.34
          NAME 'ref'
          DESC 'named reference - a labeledURI'
          EQUALITY caseExactMatch
          SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
          USAGE distributedOperation )

   The ref attribute type has directoryString 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 [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 a LDAP
   [RFC2251] server, it MUST be in the form of a LDAP URL [RFC2255].
   The LDAP URL SHOULD NOT contain an explicit scope specifier, filter,
   attribute description list, or any extensions.  The LDAP URL SHOULD
   contain a non-empty DN.  The handling of LDAP URLs with absent or
   empty DN parts or with explicit scope specifier is not defined by
   this specification.

   Other URI schemes MAY be used so long as all operations returning
   referrals based upon the value could be performed.  This document
   does not detail use of non-LDAP URIs.  This is left to future
   specifications.

   The referential integrity of the URI SHOULD NOT be validated by the
   server holding or returning the URI (whether as a value of the
   attribute or as part of a referral result or search reference
   response).





Zeilenga                    Standards Track                     [Page 3]

RFC 3296    Named Subordinate References in LDAP Directories   July 2002


   When returning a referral result or search continuation, the server
   MUST NOT return the separator or label portions of the attribute
   values as part of the reference.  When the attribute contains
   multiple values, the URI part of each value is used to construct the
   referral result or search continuation.

   The ref attribute values SHOULD NOT be used as a relative name-
   component of an entry's DN [RFC2253].

   This document uses the ref attribute in conjunction with the referral
   object class to represent subordinate references.  The ref attribute
   may be used for other purposes as defined by other documents.

3.  The ManageDsaIT Control

   The client may provide the ManageDsaIT control with an operation to
   indicate that the operation is intended to manage objects within the
   DSA (server) Information Tree.  The control causes Directory-specific
   entries (DSEs), regardless of type, to be treated as normal entries
   allowing clients to interrogate and update these entries using LDAP
   operations.

   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, if FALSE, absent.  The control value is absent.

   When the control is present in the request, the server SHALL NOT
   generate a referral or continuation reference based upon information
   held in referral objects and instead SHALL treat the referral object
   as a normal entry.  The server, however, is still free to return
   referrals for other reasons.  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.

4.  Named Subordinate References

   A named subordinate reference is constructed by instantiating a
   referral object in the referencing server with ref attribute values
   which point to the corresponding subtree maintained in the referenced
   server.  In general, the name of the referral object is the same as
   the referenced object and this referenced object is a context prefix
   [X.501].




Zeilenga                    Standards Track                     [Page 4]

RFC 3296    Named Subordinate References in LDAP Directories   July 2002


   That is, if server A holds "DC=example,DC=net" and server B holds
   "DC=sub,DC=example,DC=net", server A may contain a referral object
   named "DC=sub,DC=example,DC=net" which contains a ref attribute with
   value of "ldap://B/DC=sub,DC=example,DC=net".

      dn: DC=sub,DC=example,DC=net
      dc: sub
      ref: ldap://B/DC=sub,DC=example,DC=net
      objectClass: referral
      objectClass: extensibleObject

   Typically the DN of the referral object and the DN of the object in
   the referenced server are the same.

   If the ref attribute has multiple values, all the DNs contained
   within the LDAP URLs SHOULD be equivalent.  Administrators SHOULD
   avoid configuring naming loops using referrals.

   Named references MUST be treated as normal entries if the request
   includes the ManageDsaIT control as described in section 3.

5.  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 here consist of
   referral object handling when finding target of a non-search
   operation, when finding the base of a search operation, and when
   generating search references.  Lastly, other operation processing
   considerations are presented.

   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 first phase is similar to, but not
   the same as, finding the target of a non-search operation.

   It should 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
   processed and returned (in any order) 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.





Zeilenga                    Standards Track                     [Page 5]

RFC 3296    Named Subordinate References in LDAP Directories   July 2002


5.1.  Example Configuration

   For example, suppose the contacted server (hosta) holds the entry
   "O=MNN,C=WW" and the entry "CN=Manager,O=MNN,C=WW" and the following
   referral objects:

      dn: OU=People,O=MNN,C=WW
      ou: People
      ref: ldap://hostb/OU=People,O=MNN,C=US
      ref: ldap://hostc/OU=People,O=MNN,C=US
      objectClass: referral
      objectClass: extensibleObject

      dn: OU=Roles,O=MNN,C=WW
      ou: Roles
      ref: ldap://hostd/OU=Roles,O=MNN,C=WW
      objectClass: referral
      objectClass: extensibleObject

   The first referral object provides the server with the knowledge that
   subtree "OU=People,O=MNN,C=WW" is held by hostb and hostc (e.g., one
   is the master and the other a shadow).  The second referral object
   provides the server with the knowledge that the subtree
   "OU=Roles,O=MNN,C=WW" is held by hostd.

   Also, 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 is the one which is subordinate to all other naming contexts
   the object is within.

5.2.  Target Object Considerations

   This section details referral handling for add, compare, delete,
   modify, and modify DN operations.  If the client requests any of
   these operations, there are four cases that the server must handle
   with respect to the target object.

   The DN part MUST be modified such that it refers to the appropriate
   target in the referenced server (as detailed below).  Even where the
   DN to be returned is the same as the target DN, the DN part SHOULD
   NOT be trimmed.

   In cases where the URI to be returned is a LDAP URL, the server
   SHOULD trim any present scope, filter, or attribute list from the URI
   before returning it.  Critical extensions MUST NOT be trimmed or
   modified.




Zeilenga                    Standards Track                     [Page 6]

RFC 3296    Named Subordinate References in LDAP Directories   July 2002


   Case 1: The target object is not held by the server and is not within
      or subordinate to any naming context nor subordinate to any
      referral object held by the server.

      The server SHOULD process the request normally as appropriate for
      a non-existent base which is not within any naming context of the
      server (generally return noSuchObject or a referral based upon
      superior knowledge reference information).  This document does not
      detail management or processing of superior knowledge reference
      information.

   Case 2: The target object is held by the server and is a referral
      object.

      The server SHOULD return the URI value contained in the ref
      attribute of the referral object appropriately modified as
      described above.

   Example: If the client issues a modify request for the target object
      of "OU=People,O=MNN,c=WW", the server will return:

         ModifyResponse (referral) {
             ldap://hostb/OU=People,O=MNN,C=WW
             ldap://hostc/OU=People,O=MNN,C=WW
         }

   Case 3: The target object is not held by the server, but the nearest
      naming context contains no referral object which the target object
      is subordinate to.

      If the nearest naming context contains no referral object which
      the target is subordinate to, the server SHOULD process the
      request as appropriate for a nonexistent target (generally return
      noSuchObject).

   Case 4: The target object is not held by the server, but the nearest
      naming context contains a referral object which the target object
      is subordinate to.

      If a client requests an operation for which the target object is
      not held by the server and the nearest naming context contains a
      referral object which the target object is subordinate to, the
      server SHOULD return a referral response constructed from the URI
      portion of the ref value of the referral object.







Zeilenga                    Standards Track                     [Page 7]