idnits 2.17.1 draft-ietf-ldapext-referral-00.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-26) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 8 longer pages, the longest (page 2) being 59 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 6 instances of too long lines in the document, the longest one being 1 character in excess of 72. ** The abstract seems to contain references ([RFC2251], [RFC1738]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 70: '...laced in the attribute MUST conform to...' RFC 2119 keyword, line 74: '...he syntax. Future documents MAY enable...' RFC 2119 keyword, line 81: '...he ref attribute MAY be defined in sub...' RFC 2119 keyword, line 120: '...he ref attribute SHOULD have the same ...' RFC 2119 keyword, line 122: '... Administrators SHOULD avoid configur...' (13 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 144 has weird spacing: '...bc,c=us ref: ...' == Line 145 has weird spacing: '...bc,c=us objec...' == Line 267 has weird spacing: '...bc,c=us dn: r...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (March 1998) is 9539 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 1738 (Obsoleted by RFC 4248, RFC 4266) ** Obsolete normative reference: RFC 2251 (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) -- Unexpected draft version: The latest known version of draft-bradner-key-words is -02, but you're referring to -03. -- Possible downref: Non-RFC (?) normative reference: ref. 'X500' Summary: 14 errors (**), 0 flaws (~~), 5 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 IETF LDAPEXT Working Group Tim Howes 3 INTERNET-DRAFT Netscape Communications Corp. 4 Mark Wahl 5 Critical Angle, Inc. 6 March 1998 8 Referrals and Knowledge References in LDAP Directories 9 11 1. Status of this Memo 13 This document is an Internet-Draft. Internet-Drafts are working docu- 14 ments of the Internet Engineering Task Force (IETF), its areas, and its 15 working groups. Note that other groups may also distribute working 16 documents as Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six months 19 and may be updated, replaced, or obsoleted by other documents at any 20 time. It is inappropriate to use Internet- Drafts as reference material 21 or to cite them other than as ``work in progress.'' 23 To learn the current status of any Internet-Draft, please check the 24 ``1id-abstracts.txt'' listing contained in the Internet- Drafts Shadow 25 Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), 26 ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). 28 Distribution of this memo is unlimited. Editorial comments should be 29 sent to the authors. Technical discussion should take place on the IETF 30 LDAPEXT mailing list (ietf-ldapext@netscape.com). 32 This draft is a revision of a draft formerly published as draft-ietf- 33 asid-ldapv3-referral-00.txt. 35 2. Abstract 37 This document defines a "ref" attribute and associated "referral" object 38 class for representing generic knowledge information in LDAP directories 39 [RFC2251]. The attribute uses URIs [RFC1738] to represent knowledge, 40 enabling LDAP and non-LDAP services alike to be referenced. The object 41 class can be used to construct entries in an LDAP directory containing 42 references to other directories or services. This document also defines 43 procedures directory servers should follow when supporting these schema 44 elements. 46 3. Background and intended usage 48 The broadening of interest in LDAP directories beyond their use as front 49 ends to X.500 directories has created a need to represent knowledge 50 information in a more general way. Knowledge information is information 51 about one or more servers maintained in another server, used to link 52 servers and services together. 54 This document defines a general method of representing knowledge infor- 55 mation in LDAP directories, based on URIs. 57 The key words "MUST", "SHOULD", and "MAY" used in this document are to 58 be interpreted as described in [BRADNER97]. 60 4. The ref attribute type 62 This section defines the ref attribute type for holding general 63 knowledge reference information. 65 ( 2.16.840.1.113730.3.1.34 NAME 'ref' DESC 'URL reference' 66 EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 67 USAGE distributedOperation ) 69 The ref attribute type has IA5 syntax and is case sensitive. The ref 70 attribute is multivalued. Values placed in the attribute MUST conform to 71 the specification given for the labeledURI attribute defined in 72 [RFC2079]. The labeledURI specification defines a format that is a URI, 73 optionally followed by whitespace and a label. This document does not 74 make use of the label portion of the syntax. Future documents MAY enable 75 new functionality by imposing additional structure on the label portion 76 of the syntax as it appears in the ref attribute. 78 5. Use of the ref attribute 80 Three uses for the ref attribute are defined in this document. Other 81 uses of the ref attribute MAY be defined in subsequent documents, or by 82 bilateral agreement between cooperating clients and servers. 84 Except when the manageDsaIT control (documented in section 7 of this 85 document) is present in the operation request, the ref attribute is not 86 visible to clients, except as its value is returned in referrals or con- 87 tinuation references. 89 If the manageDsaIT control is not set, and the entry named in a request 90 contains the ref attribute, and the entry is not the root DSE, the 91 server returns an LDAPResult with the resultCode field set to "referral" 92 and the referral field set to contain the value(s) of the ref attribute. 94 If the manageDsaIT control is not set, and an entry containing the ref 95 attribute is otherwise in the scope of a one level or subtree search 96 request, the server returns a SearchResultReference for each such entry 97 containing the value(s) of the entry's ref attribute. 99 When the manageDsaIT control is present in a request, the server will 100 treat an entry containing the ref attribute as an ordinary entry, and 101 the ref attribute as an ordinary attribute, and the server will not 102 return referrals or continuation refernences corresponding to ref attri- 103 butes. 105 The following sections define three uses for the ref attribute. 107 5.1. Named reference 109 This use of the ref attribute is similar to the subordinate reference 110 concept found in X.500 [X500]. It is used to facilitate distributed name 111 resolution or search across multiple servers. The ref attribute appears 112 in an entry named in the referencing server. The value of the ref attri- 113 bute points to the corresponding entry maintained in the referenced 114 server. 116 While the distinguished name in a value of the ref attribute is typi- 117 cally that of an entry in a naming context below the naming context held 118 by the referencing server, it is permitted to be the distinguished name 119 of any entry. If the ref attribute is multi-valued all the DNs in the 120 values of the ref attribute SHOULD have the same value. It is the 121 responsibility of clients to not loop repeatedly if a naming loop is 122 present in the directory. Administrators SHOULD avoid configuring nam- 123 ing loops using referrals. 125 Clients SHOULD perform at least simple "depth-of-referral count" loop 126 detection by incrementing a counter each time a new set of referrals is 127 received. Clients MAY perform more sophisticated loop detection, for 128 example not chasing the same URI twice. 130 If an entry containing the ref attribute is immediately subordinate to 131 the base object named in a one level search request, then the referring 132 server MUST include a scope of "base" in any LDAP URIs returned in the 133 corresponding SearchResultReference. 135 5.1.1. Examples 137 A multi-valued ref attribute MAY be used to indicate different locations 138 for the same resource. An example configuration illustrating the use of 139 the ref attribute in this capacity is provided below. 141 |------------------------------------------------------------| 142 | Server A | 143 | dn: o=abc,c=us dn: o=xyz,c=us | 144 | ref: ldap://hostB/o=abc,c=us ref: ldap://hostD/o=xyz,c=us | 145 | ref: ldap://hostC/o=abc,c=us objectclass: referral | 146 | objectclass: referral | 147 |____________________________________________________________| 149 |---------------------| |---------------------| |---------------------| 150 | Server B | | Server D | | Server C | 151 | dn: o=abc,c=us | | dn: o=xyz,c=us | | dn: o=abc,c=us | 152 | o: abc | | o: xyz | | o: abc | 153 | other attributes... | | other attributes... | | other attributes... | 154 |_____________________| |_____________________| |_____________________| 156 In this example, Server A holds references for two entries: 157 "o=abc,c=us" and "o=xyz,c=us". For the "o=abc,c=us" entry, Server A 158 holds two references, one to Server B and one to Server C. The entries 159 referenced are replicas of each other. For the "o=xyz,c=us" entry, 160 Server A holds a single reference to the entry contained in Server D. 162 In the following protocol interaction examples, the client has contacted 163 Server A. Server A holds the naming context "c=us". 165 5.1.1.1. Subtree search from a superior naming context 167 If a client requests a subtree search of "c=us", then in addition to any 168 entries in the "c=us" naming context which match the filter, Server A 169 will also return two continuation references. One of the continuation 170 references will be for "o=abc,c=us", and the other continuation refer- 171 ence will be for "o=xyz,c=us". 173 The order in which the continuation references are returned, and the 174 order of LDAP URI values in each continuation reference, are not stand- 175 ardized. One possible response might be: 177 ... SearchResultEntry responses ... 179 SearchResultReference { 180 ldap://hostB/o=abc,c=us 181 ldap://hostC/o=abc,c=us 182 } 184 SearchResultReference { 185 ldap://hostD/o=xyz,c=us 186 } 188 SearchResultDone "success" 190 5.1.1.2. One level search from an immediately superior object 192 If the client requests a one level search of "c=us", then in addition to 193 any entries in the "c=us" naming context which match the filter, Server 194 A will also return two continuation references, as in the previous exam- 195 ple. One possible response might be: 197 ... SearchResultEntry responses ... 199 SearchResultReference { 200 ldap://hostB/o=abc,c=us??base 201 ldap://hostC/o=abc,c=us??base 202 } 204 SearchResultReference { 205 ldap://hostD/o=xyz,c=us??base 206 } 208 SearchResultDone "success" 210 Note the inclusion of the "base" scope in the returned URL continuation 211 references. This is required to maintain the one-level search semantics. 213 5.1.1.3. Other operations 215 If the client requests an operation in which the base or target entry 216 has a ref attribute, then the server returns an LDAPResult with the 217 resultCode field set to referral and the referral field set to the 218 value(s) of the ref attribute. If the operation is a search, the refer- 219 ring server does not return any SearchResultEntry or SearchResultRefer- 220 ence before the SearchResultDone. 222 For example, if the client had issued a subtree search of "o=abc,c=us", 223 the server would return 225 SearchResultDone "referral" { 226 ldap://hostB/o=abc,c=us 227 ldap://hostC/o=abc,c=us 228 } 230 Similarly, if the client had issued a modify of "o=xyz,c=us", the server 231 would return 233 ModifyResponse "referral" { 234 ldap://hostD/o=xyz,c=us 235 } 237 5.2. Superior Reference 239 This use of the ref attribute is similar to the superior reference con- 240 cept found in X.500 [X500]. An LDAP server's root DSE MAY contain the 241 "ref" attribute. The values of the ref attribute in the root DSE that 242 are LDAP URIs SHOULD NOT contain any dn part, just the host name and 243 optional port number. 245 When the server receives an operation for which the base or target entry 246 of the request is not contained in or subordinate to any naming context 247 held by the server, the server will return an LDAPResult with the 248 resultCode set to "referral", and with the referral field filled in 249 using the values from the "ref" attribute from the root DSE. 251 5.3. Unnamed reference 253 This use of the ref attribute is similar to the nonspecific subordinate 254 reference concept found in X.500 [X500]. It goes beyond this concept to 255 facilitate distributed searching or indexing across multiple servers. 256 The ref attribute is used to name an entry in the referencing server. 257 The reference entry may contain other attributes used to select the 258 reference during searching. 260 A multi-valued ref attribute MAY indicate the locations of different 261 resources all associated with the same LDAP entity. The following exam- 262 ple illustrates the use of the ref attribute to indicate two unnamed 263 references. 265 |------------------------------------------------------------------| 266 | Server A | 267 | dn: ref=ldap://hostB/o=abc,c=us dn: ref=ldap://hostC/o=xyz,c=us | 268 | cn: babs cn: babs | 269 | cn: gern cn: bob | 270 | cn: bob | 271 |__________________________________________________________________| 273 |-----------------------------| |-----------------------------| 274 | Server B | | Server C | 275 | dn: o=abc,c=us | | dn: o=xyz,c=us | 276 | o: abc | | o: xyz | 277 | other attributes... | | other attributes... | 278 | | | | 279 | dn: cn=babs,o=abc,c=us | | dn: cn=babs,o=xyz,c=us | 280 | cn: babs | | o: xyz | 281 | other attributes... | | other attributes... | 282 | | | | 283 | dn: cn=gern,o=abc,c=us | | dn: cn=bob,o=xyz,c=us | 284 | cn: gern | | cn: bob | 285 | other attributes... | | other attributes... | 286 | | |_____________________________| 287 | dn: cn=bob,o=abc,c=us | 288 | cn: bob | 289 | other attributes... | 290 |_____________________________| 292 In this example Server A contains two unnamed references to servers B 293 and C. The unnamed reference entries have additional cn attribute values 294 which may be used during a search operation to select the reference for 295 return to a client. 297 6. The referral object class 299 The referral object class is defined as follows. 301 ( 2.16.840.1.113730.3.2.6 NAME 'referral' SUP top STRUCTURAL 302 MAY ( ref $ * ) ) 304 The referral object class is a subclass of top and may contain the 305 referral attribute. It is a structural object class. The referral object 306 class may also contain any other attribute, as indicated by the "*" in 307 the MAY portion of the definition. This is required to support the nam- 308 ing attributes used in the entry's distinguished name. 310 Servers MAY support the ref attribute through use of the referral object 311 class. Servers MAY also support the ref attribute as an operational 312 attribute in any entry, or through use of other object classes. 314 7. The manageDsaIT control 316 A client MAY specify the following control when issuing a search, com- 317 pare, add, delete, modify, or modifyDN request. 319 The control type is 2.16.840.1.113730.3.4.2. The control SHOULD be 320 marked as critical. There is no value; the controlValue field is 321 absent. 323 This control causes entries with the "ref" attribute to be treated as 324 normal entries, allowing clients to read and modify these entries. 326 This control is not needed if the entry containing the referral attri- 327 bute is one used for directory administrative purposes, such as the root 328 DSE, or the server change log entries. Operations on these entries 329 never cause referrals or continuation references to be returned. 331 8. Relationship to X.500 Knowledge References 333 The X.500 standard defines several types of knowledge references, used 334 to bind together different parts of the X.500 namespace. In X.500, 335 knowledge references can be associated with a set of unnamed entries 336 (e.g., a reference, associated with an entry, to a server containing the 337 descendants of that entry). 339 This creates a potential problem for LDAP clients resolving an LDAPv3 340 URL referral referring to an LDAP directory back-ended by X.500. Sup- 341 pose the search is a subtree search, and that server A holds the base 342 object of the search, and server B holds the descendants of the base 343 object. The behavior of X.500(1993) subordinate references is that the 344 base object on server A is searched, and a single continuation reference 345 is returned pointing to all of the descendants held on server B. 347 An LDAP URL only allows the base object to be specified. It is not pos- 348 sible using standard LDAP URLs to indicate a search of several entries 349 whose names are not known to the server holding the superior entry. 351 X.500 solves this problem by having two fields, one indicating the pro- 352 gress of name resolution and the other indicating the target of the 353 search. In the above example, name resolution would be complete by the 354 time the query reached server B, indicating that it should not refer the 355 request. 357 This document does not address this problem. This problem will be 358 addressed in separate documents which define the changes to the X.500 359 distribution model and LDAPv3 extensions to indicate the progress of 360 name resolution. 362 9. Security Considerations 364 This document defines mechanisms that can be used to "glue" LDAP (and 365 other) servers together. The information used to specify this glue 366 information should be protected from unauthorized modification. If the 367 server topology information itself is not public information, the infor- 368 mation should be protected from unauthorized access as well. 370 10. References 372 [RFC1738] 373 Berners-Lee, T., Masinter, L., and McCahill, M., "Uniform Resource 374 Locators (URL)", RFC 1738, CERN, Xerox Corporation, University of 375 Minnesota, December 1994, 376 378 [RFC2251] 379 M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol 380 (v3)", RFC 2251, December 1997. 1997. 382 [BRADNER97] 383 S. Bradner, "Key Words for use in RFCs to Indicate Requirement Lev- 384 els", Internet Draft, draft-bradner-key-words-03.txt, January 1997. 386 [X500] 387 ITU-T Rec. X.501, "The Directory: Models", 1993. 389 [RFC2079] 390 M. Smith, "Definition of an X.500 Attribute Type and an Object Class 391 to Hold Uniform Resource Identifiers (URIs)", RFC 2079, January 392 1997. 394 11. Author's Address 396 Tim Howes 397 Netscape Communications Corp. 398 501 E. Middlefield Rd. 399 Mountain View, CA 94043 400 USA 401 EMail: howes@netscape.com 403 Mark Wahl 404 Critical Angle Inc. 405 4815 W Braker Lane #502-385 406 Austin, TX 78759 407 USA 408 EMail: M.Wahl@critical-angle.com