idnits 2.17.1 draft-ietf-ldapext-namedref-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): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. 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 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 12 longer pages, the longest (page 2) being 60 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 13 pages 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. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 183 has weird spacing: '...bc,c=us ref: ...' == Line 184 has weird spacing: '...bc,c=us objec...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- 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 (June 1999) is 9074 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) == Missing Reference: 'Editor' is mentioned on line 1, but not defined == Unused Reference: 'X500' is defined on line 533, but no explicit reference was found in the text ** 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) ** Obsolete normative reference: RFC 2255 (Obsoleted by RFC 4510, RFC 4516) -- Possible downref: Non-RFC (?) normative reference: ref. 'X500' Summary: 11 errors (**), 0 flaws (~~), 9 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 IETF LDAPEXT Working Group Christopher Lukas [Editor] 2 INTERNET-DRAFT Internet Scout Project 3 Tim Howes 4 Netscape Communications Corp. 5 Michael Roszkowski 6 Internet Scout Project 7 Mark C. Smith 8 Netscape Communications Corp. 9 Mark Wahl 10 Critial Angle, Inc. 11 June 1999 13 Named Referrals in LDAP Directories 14 16 1. Status of this Memo 18 This document is an Internet-Draft and is in full conformance with all 19 provisions of Section 10 of RFC2026. 21 Internet-Drafts are working documents of the Internet Engineering Task 22 Force (IETF), its areas, and its working groups. Note that other groups 23 may also distribute working documents as Internet-Drafts. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet- Drafts as reference material 28 or to cite them other than as "work in progress." 30 The list of current Internet-Drafts can be accessed at 31 http://www.ietf.org/ietf/1id-abstracts.txt 33 The list of Internet-Draft Shadow Directories can be accessed at 34 http://www.ietf.org/shadow.html. 36 Distribution of this document is unlimited. Please send comments to the 37 authors or the LDAPEXT mailing list, ietf-ldapext@netscape.com. 39 Copyright Notice: Copyright (C) The Internet Society (1999). All Rights 40 Reserved. 42 This draft is a revision of a draft formerly published as draft-ietf- 43 ldapext-referral-00.txt. 45 This draft expires December 6, 1999. 47 2. Abstract 49 This document defines a "ref" attribute and associated "referral" object 50 class for representing generic knowledge information in LDAP directories 51 [RFC2251]. The attribute uses URIs [RFC1738] to represent knowledge, 52 enabling LDAP and non-LDAP services alike to be referenced. The object 53 class can be used to construct entries in an LDAP directory containing 54 references to other directories or services. This document also defines 55 procedures directory servers should follow when supporting these schema 56 elements and when responding to requests for which the directory server 57 does not contain the requested object but may contain some knowledge of 58 the location of the requested object. 60 3. Background and intended usage 62 The broadening of interest in LDAP directories beyond their use as front 63 ends to X.500 directories has created a need to represent knowledge 64 information in a more general way. Knowledge information is information 65 about one or more servers maintained in another server, used to link 66 servers and services together. 68 This document defines a general method of representing knowledge infor- 69 mation in LDAP directories, based on URIs. 71 The key words "MUST", "SHOULD", and "MAY" used in this document are to 72 be interpreted as described in [RFC2119]. 74 4. The ref attribute type 76 This section defines the ref attribute type for holding general 77 knowledge reference information. 79 ( 2.16.840.1.113730.3.1.34 NAME 'ref' DESC 'URL reference' 80 EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 81 USAGE distributedOperation ) 83 The ref attribute type has IA5 syntax and is case sensitive. The ref 84 attribute is multivalued. Values placed in the attribute MUST conform to 85 the specification given for the labeledURI attribute defined in 86 [RFC2079]. The labeledURI specification defines a format that is a URI, 87 optionally followed by whitespace and a label. This document does not 88 make use of the label portion of the syntax. Future documents MAY enable 89 new functionality by imposing additional structure on the label portion 90 of the syntax as it appears in the ref attribute. 92 If the URI contained in the ref attribute refers to an LDAPv3 server, it 93 must be in the LDAP URI format described in [RFC2255]. 95 When returning a referral result, the server must not return the label 96 portion of the labeledURI as part of the referral. Only the URI portion 97 of the ref attribute should be returned. 99 5. Use of the ref attribute 101 One usage of the ref attribute is defined in this document. Other uses 102 of the ref attribute MAY be defined in subsequent documents, or by bila- 103 teral agreement between cooperating clients and servers. 105 Except when the manageDsaIT control (documented in section 8 of this 106 document) is present in the operation request, the ref attribute is not 107 visible to clients, except as its value is returned in referrals or con- 108 tinuation references. 110 If the manageDsaIT control is not set, and the entry named in a request 111 contains the ref attribute, and the entry is not the root DSE, the 112 server returns an LDAPResult with the resultCode field set to "referral" 113 and the referral field set to contain the value(s) of the ref attribute 114 minus any optional trailing whitespace and labels that might be present. 116 If the manageDsaIT control is not set, and an entry containing the ref 117 attribute is in the scope of a one level or subtree search request, the 118 server returns a SearchResultReference for each such entry containing 119 the value(s) of the entry's ref attribute. 121 When the manageDsaIT control is present in a request, the server will 122 treat an entry containing the ref attribute as an ordinary entry, and 123 the ref attribute as an ordinary attribute, and the server will not 124 return referrals or continuation references corresponding to ref attri- 125 butes. 127 The following sections detail these usages of the ref attribute. 129 5.1. Named reference 131 This use of the ref attribute is to facilitate distributed name resolu- 132 tion or search across multiple servers. The ref attribute appears in an 133 entry named in the referencing server. The value of the ref attribute 134 points to the corresponding entry maintained in the referenced server. 136 While the distinguished name in a value of the ref attribute is typi- 137 cally that of an entry in a naming context below the naming context held 138 by the referencing server, it is permitted to be the distinguished name 139 of any entry. If the ref attribute is multi-valued all the DNs in the 140 values of the ref attribute SHOULD have the same value. It is the 141 responsibility of clients to not loop repeatedly if a naming loop is 142 present in the directory. Administrators SHOULD avoid configuring 143 naming loops using referrals. 145 Clients SHOULD perform at least simple "depth-of-referral count" loop 146 detection by incrementing a counter each time a new set of referrals is 147 received. Clients MAY perform more sophisticated loop detection, for 148 example not chasing the same URI twice. 150 If an entry containing the ref attribute is immediately subordinate to 151 the base object named in a one level search request, then the referring 152 server MUST include a scope of "base" in any LDAP URIs returned in the 153 corresponding SearchResultReference. 155 5.1.1. Scenarios 157 The following sections contain specifications of how the ref attribute 158 should be used in different scenarios followed by examples that illus- 159 trate that usage. The scenarios described consist of referral operation 160 when finding a base or target object, referral operation when performing 161 a one level search, and referral operation when performing a subtree 162 search. 164 It is to be noted that, in this document, a search operation is concep- 165 tually divided into two distinct, sequential phases: (1) finding the 166 base object where the search is to begin, and (2) performing the search 167 itself. The operation of the server with respect to referrals in phase 168 (1) is almost identical to the operation of the server while finding the 169 target object for a non-search operation. 171 It is to also be noted that multiple ref attributes are allowed in any 172 entry and, where these sections refer to a single ref attribute, multi- 173 ple ref attributes may be substituted and should be processed and 174 returned as a group in an LDAPResult or search result in the same way as 175 described for a single attribute. The order of the returned continuation 176 references within a result is not defined. 178 5.1.1.1. Example configuration 179 |------------------------------------------------------------| 180 | Server A | 181 | dn: o=abc,c=us dn: o=xyz,c=us | 182 | o: abc o: xyz | 183 | ref: ldap://hostB/o=abc,c=us ref: ldap://hostD/o=xyz,c=us | 184 | ref: ldap://hostC/o=abc,c=us objectclass: referral | 185 | objectclass: referral objectclass: extensibleObject| 186 | objectclass: extensibleObject | 187 |____________________________________________________________| 189 |---------------------| |---------------------| |---------------------| 190 | Server B | | Server D | | Server C | 191 | dn: o=abc,c=us | | dn: o=xyz,c=us | | dn: o=abc,c=us | 192 | o: abc | | o: xyz | | o: abc | 193 | other attributes... | | other attributes... | | other attributes... | 194 |_____________________| |_____________________| |_____________________| 196 In this example, Server A holds references for two entries: "o=abc,c=us" 197 and "o=xyz,c=us". For the "o=abc,c=us" entry, Server A holds two refer- 198 ences, one to Server B and one to Server C. The entries referenced are 199 replicas of each other. For the "o=xyz,c=us" entry, Server A holds a 200 single reference to the entry contained in Server D. 202 In the following protocol interaction examples, the client has contacted 203 Server A. Server A holds the naming context "c=us". 205 5.1.1.2. Base or target object considerations 207 As previously described, the process of generating referrals for a 208 search can be described in two phases. The first, which is described in 209 this section, is generating referrals based on the base object specified 210 in the search. This process is identical to the process of generating 211 referrals based on the target object while processing other operations 212 (modify, add, delete, modify DN, and compare) with the sole exception 213 that for these other operations, the DN in the referral must be modified 214 in some cases. 216 If a client requests any of these operations, there are four cases that 217 the server must handle with respect to the base or target object speci- 218 fied in the request. 220 Case 1: The base or target object is not held by the server and is not 221 subordinate to any object held by the server with a ref attribute. 223 The handling of this case is described in section 6. 225 Case 2: The base or target object is held by the server and contains a 226 ref attribute 227 In this case, if the type of operation requested is a search or the URI 228 contained in the ref attribute of the requested base object is NOT an 229 LDAP URI as defined in [RFC2255], the server should return the URI value 230 contained in the ref attribute of the base object whose DN is the DN 231 requested by the client as the base for the operation. 233 Example: 235 If the client issues a search in which the base object is "o=xyz,c=us", 236 server A will return 238 SearchResultDone "referral" { 239 ldap://hostD/o=xyz,c=us 240 } 242 If the type of operation requested is not a search and the URI contained 243 in the ref attribute of the requested target object is an LDAP URI 244 [RFC2255], the server should return a modified form of this URL. The 245 returned URL must have only the protocol, host, port, and trailing "/" 246 portion of the URL contained in the ref attribute. The server should 247 strip any dn, attributes, scope, and filter parts of the URL. 249 Example: 251 If the client issues a modify request for the target object of 252 "o=abc,c=us", server A will return 254 ModifyResponse "referral" { 255 ldap://hostB/ 256 ldap://hostC/ 257 } 259 Case 3: The base or target object is not held by the server, but is 260 subordinate to an object with a ref attribute held by the server. 262 If a client requests an operation for which the base or target object is 263 not held by the server, but is subordinate to one or more objects with a 264 ref attribute held by the server, the server must return the referral 265 from the superior held object nearest to the requested base or target 266 object. Nearest superior object with a referral, in this document, means 267 an object superior to the base or target object with the DN that has the 268 most attribute values in common with the DN of the base or target object 269 and contains a ref attribute. 271 The process of finding the nearest superior object can be envisioned as 272 walking up the locally held part of the DIT from the requested base or 273 target object checking each superior object until either an object with 274 a ref attribute is found or the top-most locally held object is reached. 275 Once possible implementation of this algorithm is as follows: 277 1. Remove the leftmost attribute/value pair from the DN of the 278 requested base or target object. 279 2. If the remaining DN represents a locally held object that contains 280 a ref attribute, that object is the nearest superior object with a 281 referral. Stop and process the referral as described below. 282 3. If the remaining DN is the root of the locally held part of the 283 DIT, stop and proceed as described in section 6. 284 4. Continue with step 1. 286 Once the nearest superior object has been identified, if the referral 287 contained in that object is not an LDAP URI [RFC2255], it should be 288 returned as-is. If the referral is an LDAP URI, the referral must be 289 modified, regardless of the type of operation, as case 2 describes for a 290 non-search requuest. That is, the dn, attributes, scope, and filter 291 parts of the URL must be stripped from the referral and the referral 292 returned. 294 Example: 296 If the client issues an add request where the target object has a DN of 297 "cn=Chris Lukas,o=abc,c=us", server A will return 299 AddResponse "referral" { 300 ldap://hostB/ 301 ldap://hostC/ 302 } 304 5.1.1.3. Search with one level scope 306 For search operations, once the base object has been found and deter- 307 mined not to contain a ref attribute, the search may progress. Any 308 entries matching the filter and scope of the search that do NOT contain 309 a ref attribute are returned to the client normally as described in 310 [RFC2251]. Any entries matching the filter and one level scope that do 311 contain a ref attribute must be returned as referrals as described here. 313 If a matching entry contains a ref attribute and the URI contained in 314 the ref attribute is NOT an LDAP URI [RFC2255], the server should return 315 the URI value contained in the ref attribute of that entry in a Sear- 316 chResultReference. 318 If a matching entry contains a ref attribute in the LDAP URI syntax 319 [RFC2255], the URL from the ref attribute must be modified before it is 320 returned by adding or substituting a "base" scope into the URL. If the 321 URL does not contain a scope specifier, the "base" scope specifier must 322 be added. If the URL does contain a scope specifier, the existing scope 323 specifier must be replaced by the "base" scope. 325 Example: 327 If a client requests a one level search of "c=US" then, in addition to 328 any entries one level below the "c=US" naming context matching the 329 filter (shown below as "... SearchResultEntry responses ..."), the 330 server will also return referrals modified to include the "base" scope 331 to maintain the one level search semantics. 333 The order of the SearchResultEntry responses and the SearchResultRefer- 334 ence responses is undefined. One possible sequence is shown. 336 ... SearchResultEntry responses ... 338 SearchResultReference { 339 ldap://hostB/o=abc,c=us??base 340 ldap://hostC/o=abc,c=us??base 341 } 343 SearchResultReference { 344 ldap://hostD/o=xyz,c=us??base 345 } 347 SearchResultDone "success" 349 5.1.1.4. Search with subtree scope 351 For a search operation with a subtree scope, once the base object has 352 been found, the search progresses. As with the one level search, any 353 entries matching the filter and scope of the search that do NOT contain 354 a ref attribute are returned to the client normally as described in 355 [RFC2251]. 357 If an entry matching the requested scope and filter contains a ref 358 attribute, the server should return the URI value in a SearchResul- 359 tReference. 361 Example: 363 If a client requests a subtree search of "c=us", then in addition to any 364 entries in the "c=us" naming context which match the filter, Server A 365 will also return two continuation references. As described in the 366 preceding section, the order of the responses is not defined. 368 One possible response might be: 370 ... SearchResultEntry responses ... 372 SearchResultReference { 373 ldap://hostB/o=abc,c=us 374 ldap://hostC/o=abc,c=us 375 } 377 SearchResultReference { 378 ldap://hostD/o=xyz,c=us 379 } 381 SearchResultDone "success" 383 6. Superior Reference 385 An LDAP server may be configured to return a superior reference in the 386 case where the server does not hold either the requested base object or 387 an object containing a ref attribute that is superior to that base 388 object. 390 An LDAP server's root DSE MAY contain a ref attribute. The values of the 391 ref attribute in the root DSE that are LDAP URIs SHOULD NOT contain any 392 dn part, just the host name and optional port number. 394 If the LDAP server's root DSE contains a ref attribute and a client 395 requests an object not held by the server and not subordinate to any 396 held object, the server must return the URI component of the values in 397 the ref attribute of the root DSE as illustrated in the example. 399 If the LDAP server's root DSE does not contain a ref attribute, the 400 server may return one or more references that the server determines via 401 a method not defined in this document to be appropriate. 403 The default reference may be to any server that might contain more 404 knowledge of the namespace than the responding server. In particular, 405 the client must not expect the superior reference to be identical from 406 session to session as the reference may be dynamically created by the 407 server based on the details of the query submitted by the client. 409 When the server receives an operation for which the base or target entry 410 of the request is not contained in or subordinate to any naming context 411 held by the server or a referral entry, the server will return an 412 LDAPResult with the resultCode set to "referral", and with the referral 413 field filled with a referral that the server has determined to be 414 appropriate. 416 Example: 418 If a client requests a subtree search of "c=de" from server A in the 419 example configuration, and server A has the following ref attribute 420 defined in it's root DSE: 422 ref: ldap://hostG/ 424 then server A will return 426 SearchResultDone "referral" { 427 ldap://hostG/ 428 } 430 7. The referral object class 432 The referral object class is defined as follows. 434 ( 2.16.840.1.113730.3.2.6 NAME 'referral' SUP top STRUCTURAL 435 MAY ( ref ) ) 437 The referral object class is a subclass of top and may contain the 438 referral attribute. The referral object class should, in general, be 439 used in conjunction with the extensibleObject object class to support 440 the naming attributes used in the entry's distinguished name. 442 Servers must support the ref attribute through use of the referral 443 object class. Any named reference must be of the referral object class 444 and will likely also be of the extensibleObject object class to support 445 naming and use of other attributes. 447 8. The manageDsaIT control 449 A client MAY specify the following control when issuing a search, com- 450 pare, add, delete, modify, or modifyDN request or an extended operation 451 for which the control is defined. 453 The control type is 2.16.840.1.113730.3.4.2. The control SHOULD be 454 marked as critical. There is no value; the controlValue field is 455 absent. 457 This control causes entries with the "ref" attribute to be treated as 458 normal entries, allowing clients to read and modify these entries. 460 This control is not needed if the entry containing the referral attri- 461 bute is one used for directory administrative purposes, such as the root 462 DSE, or the server change log entries. Operations on these entries 463 never cause referrals or continuation references to be returned. 465 9. Relationship to X.500 Knowledge References 467 The X.500 standard defines several types of knowledge references, used 468 to bind together different parts of the X.500 namespace. In X.500, 469 knowledge references can be associated with a set of unnamed entries 470 (e.g., a reference, associated with an entry, to a server containing the 471 descendants of that entry). 473 This creates a potential problem for LDAP clients resolving an LDAPv3 474 URL referral referring to an LDAP directory back-ended by X.500. Sup- 475 pose the search is a subtree search, and that server A holds the base 476 object of the search, and server B holds the descendants of the base 477 object. The behavior of X.500(1993) subordinate references is that the 478 base object on server A is searched, and a single continuation reference 479 is returned pointing to all of the descendants held on server B. 481 An LDAP URI only allows the base object to be specified. It is not pos- 482 sible using standard LDAP URIs to indicate a search of several entries 483 whose names are not known to the server holding the superior entry. 485 X.500 solves this problem by having two fields, one indicating the pro- 486 gress of name resolution and the other indicating the target of the 487 search. In the above example, name resolution would be complete by the 488 time the query reached server B, indicating that it should not refer the 489 request. 491 This document does not address this problem. This problem will be 492 addressed in separate documents which define the changes to the X.500 493 distribution model and LDAPv3 extensions to indicate the progress of 494 name resolution. 496 10. Security Considerations 498 This document defines mechanisms that can be used to "glue" LDAP (and 499 other) servers together. The information used to specify this glue 500 information should be protected from unauthorized modification. If the 501 server topology information itself is not public information, the infor- 502 mation should be protected from unauthorized access as well. 504 Clients should use caution when re-using credentials while following 505 referrals as the client may be directed to any server which may or may 506 not respect or use those credentials appropriately. 508 11. References 510 [RFC1738] 511 Berners-Lee, T., Masinter, L., and McCahill, M., "Uniform Resource 512 Locators (URL)", RFC 1738, CERN, Xerox Corporation, University of 513 Minnesota, December 1994. 515 [RFC2079] 516 M. Smith, "Definition of an X.500 Attribute Type and an Object Class 517 to Hold Uniform Resource Identifiers (URIs)", RFC 2079, January 518 1997. 520 [RFC2119] 521 S. Bradner, "Key Words for use in RFCs to Indicate Requirement Lev- 522 els", RFC 2119, March 1997. (Format: TXT=4723 bytes) (Also BCP0014) 523 (Status: BEST CURRENT PRACTICE) 525 [RFC2251] 526 M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol 527 (v3)", RFC 2251, December 1997. 529 [RFC2255] 530 T. Howes, M. Smith, "The LDAP URL Format", RFC 2255, December, 1997. 531 (Format: TXT=20685 bytes) (Status: PROPOSED STANDARD) 533 [X500] 534 ITU-T Rec. X.501, "The Directory: Models", 1993. 536 12. Author's Address 538 Tim Howes 539 Netscape Communications Corp. 540 501 E. Middlefield Rd. 541 Mailstop MV068 542 Mountain View, CA 94043 543 USA 544 +1 650 937-3419 545 EMail: howes@netscape.com 547 Christopher E. Lukas 548 Internet Scout Project 549 Computer Sciences Dept. 550 University of Wisconsin-Madison 551 1210 W. Dayton St. 552 Madison, WI 53706 553 USA 554 EMail: lukas@cs.wisc.edu 555 Michael Roszkowski 556 Internet Scout Project 557 Computer Sciences Dept. 558 University of Wisconsin-Madison 559 1210 W. Dayton St. 560 Madison, WI 53706 561 USA 562 EMail: mfr@cs.wisc.edu 564 Mark C. Smith 565 Netscape Communications Corp. 566 501 E. Middlefield Rd. 567 Mailstop MV068 568 Mountain View, CA 94043 569 USA 570 EMail: mcs@netscape.com 572 Mark Wahl 573 Innosoft International, Inc. 574 8911 Capital of Texas Hwy #4140 575 Austin TX 78759 576 EMail: M.Wahl@innosoft.com 578 This draft expires December 6, 1999.