idnits 2.17.1 draft-ietf-asid-ldapv3-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-03-28) 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 7 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 ([LDAP], [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 66: '...in the attribute MUST conform to the s...' RFC 2119 keyword, line 70: '...Future documents MAY enable new functi...' RFC 2119 keyword, line 77: '...he ref attribute MAY be defined in sub...' RFC 2119 keyword, line 116: '...he ref attribute SHOULD have the same ...' RFC 2119 keyword, line 118: '... Administrators SHOULD avoid configur...' (13 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 140 has weird spacing: '...bc,c=us ref: ...' == Line 141 has weird spacing: '...bc,c=us objec...' == Line 263 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 (May 1997) is 9814 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) == Outdated reference: A later version (-09) exists of draft-ietf-asid-ldapv3-protocol-04 -- 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: 13 errors (**), 0 flaws (~~), 6 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 IETF ASID Working Group Tim Howes 3 INTERNET-DRAFT Netscape Communications Corp. 4 Mark Wahl 5 Critical Angle, Inc. 6 May 1997 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 author (howes@netscape.com). Technical discussion should 30 take place on the IETF ASID mailing list (ietf-asid@umich.edu). 32 2. Abstract 34 This document defines a "ref" attribute and associated "referral" object 35 class for representing generic knowledge information in LDAP directories 36 [LDAP]. The attribute uses URIs [RFC1738] to represent knowledge, ena- 37 bling LDAP and non-LDAP services alike to be referenced. The object 38 class can be used to construct entries in an LDAP directory containing 39 references to other directories or services. This document also defines 40 procedures directory servers should follow when supporting these schema 41 elements. 43 3. Background and intended usage 45 The broadening of interest in LDAP directories beyond their use as front 46 ends to X.500 directories has created a need to represent knowledge 47 information in a more general way. Knowledge information is information 48 about one or more servers maintained in another server, used to link 49 servers and services together. 51 This document defines a general method of representing knowledge infor- 52 mation in LDAP directories, based on URIs. 54 The key words "MUST", "SHOULD", and "MAY" used in this document are to 55 be interpreted as described in [BRADNER97]. 57 4. The ref attribute type 59 This section defines the ref attribute type for holding general 60 knowledge reference information. 62 ( 2.16.840.1.113730.3.1.34 NAME 'ref' DESC 'URL reference' 63 EQUALITY caseExactIA5Match SYNTAX 'IA5String' USAGE dSAOperation ) 65 The ref attribute type has caseExactString syntax. The ref attribute is 66 multivalued. Values placed in the attribute MUST conform to the specifi- 67 cation given for the labeledURI attribute defined in [RFC2079]. The 68 labeledURI specification defines a format that is a URI, optionally fol- 69 lowed by whitespace and a label. This document does not make use of the 70 label portion of the syntax. Future documents MAY enable new functional- 71 ity by imposing additional structure on the label portion of the syntax 72 as it appears in the ref attribute. 74 5. Use of the ref attribute 76 Three uses for the ref attribute are defined in this document. Other 77 uses of the ref attribute MAY be defined in subsequent documents, or by 78 bilateral agreement between cooperating clients and servers. 80 Except when the manageDsaIT control (documented in section 7 of this 81 document) is present in the operation request, the ref attribute is not 82 visible to clients, except as its value is returned in referrals or con- 83 tinuation references. 85 If the manageDsaIT control is not set, and the entry named in a request 86 contains the ref attribute, and the entry is not the root DSE, the 87 server returns an LDAPResult with the resultCode field set to "referral" 88 and the referral field set to contain the value(s) of the ref attribute. 90 If the manageDsaIT control is not set, and an entry containing the ref 91 attribute is otherwise in the scope of a one level or subtree search 92 request, the server returns a SearchResultReference for each such entry 93 containing the value(s) of the entry's ref attribute. 95 When the manageDsaIT control is present in a request, the server will 96 treat an entry containing the ref attribute as an ordinary entry, and 97 the ref attribute as an ordinary attribute, and the server will not 98 return referrals or continuation refernences corresponding to ref attri- 99 butes. 101 The following sections define three uses for the ref attribute. 103 5.1. Named reference 105 This use of the ref attribute is similar to the subordinate reference 106 concept found in X.500 [X500]. It is used to facilitate distributed name 107 resolution or search across multiple servers. The ref attribute appears 108 in an entry named in the referencing server. The value of the ref attri- 109 bute points to the corresponding entry maintained in the referenced 110 server. 112 While the distinguished name in a value of the ref attribute is typi- 113 cally that of an entry in a naming context below the naming context held 114 by the referencing server, it is permitted to be the distinguished name 115 of any entry. If the ref attribute is multi-valued all the DNs in the 116 values of the ref attribute SHOULD have the same value. It is the 117 responsibility of clients to not loop repeatedly if a naming loop is 118 present in the directory. Administrators SHOULD avoid configuring nam- 119 ing loops using referrals. 121 Clients SHOULD perform at least simple "depth-of-referral count" loop 122 detection by incrementing a counter each time a new set of referrals is 123 received. Clients MAY perform more sophisticated loop detection, for 124 example not chasing the same URI twice. 126 If an entry containing the ref attribute is immediately subordinate to 127 the base object named in a one level search request, then the referring 128 server MUST include a scope of "base" in any LDAP URIs returned in the 129 corresponding SearchResultReference. 131 5.1.1. Examples 133 A multi-valued ref attribute MAY be used to indicate different locations 134 for the same resource. An example configuration illustrating the use of 135 the ref attribute in this capacity is provided below. 137 |------------------------------------------------------------| 138 | Server A | 139 | dn: o=abc,c=us dn: o=xyz,c=us | 140 | ref: ldap://hostB/o=abc,c=us ref: ldap://hostD/o=xyz,c=us | 141 | ref: ldap://hostC/o=abc,c=us objectclass: referral | 142 | objectclass: referral | 143 |____________________________________________________________| 145 |---------------------| |---------------------| |---------------------| 146 | Server B | | Server D | | Server C | 147 | dn: o=abc,c=us | | dn: o=xyz,c=us | | dn: o=abc,c=us | 148 | o: abc | | o: xyz | | o: abc | 149 | other attributes... | | other attributes... | | other attributes... | 150 |_____________________| |_____________________| |_____________________| 152 In this example, Server A holds references for two entries: 153 "o=abc,c=us" and o=xyz,c=us". For the "o=abc,c=us" entry, Server A holds 154 two references, one to Server B and one to Server C. The entries refer- 155 enced are replicas of each other. For the "o=xyz,c=us" entry, Server A 156 holds a single reference to the entry contained in Server D. 158 In the following protocol interaction examples, the client has contacted 159 Server A. Server A holds the naming context "c=us". 161 5.1.1.1. Subtree search from a superior naming context 163 If a client requests a subtree search of "c=us", then in addition to any 164 entries in the "c=us" naming context which match the filter, Server A 165 will also return two continuation references. One of the continuation 166 references will be for "o=abc,c=us", and the other continuation refer- 167 ence will be for "o=xyz,c=us". 169 The order in which the continuation references are returned, and the 170 order of LDAP URI values in each continuation reference, are not stand- 171 ardized. One possible response might be: 173 ... SearchResultEntry responses ... 175 SearchResultReference { 176 ldap://hostB/o=abc,c=us 177 ldap://hostC/o=abc,c=us 178 } 180 SearchResultReference { 181 ldap://hostD/o=xyz,c=us 182 } 184 SearchResultDone "success" 186 5.1.1.2. One level search from an immediately superior object 188 If the client requests a one level search of "c=us", then in addition to 189 any entries in the "c=us" naming context which match the filter, Server 190 A will also return two continuation references, as in the previous 191 example. One possible response might be: 193 ... SearchResultEntry responses ... 195 SearchResultReference { 196 ldap://hostB/o=abc,c=us??base 197 ldap://hostC/o=abc,c=us??base 198 } 200 SearchResultReference { 201 ldap://hostD/o=xyz,c=us??base 202 } 204 SearchResultDone "success" 206 Note the inclusion of the "base" scope in the returned URL continuation 207 references. This is required to maintain the one-level search semantics. 209 5.1.1.3. Other operations 211 If the client requests an operation in which the base or target entry 212 has a ref attribute, then the server returns an LDAPResult with the 213 resultCode field set to referral and the referral field set to the 214 value(s) of the ref attribute. If the operation is a search, the refer- 215 ring server does not return any SearchResultEntry or SearchResultRefer- 216 ence before the SearchResultDone. 218 For example, if the client had issued a subtree search of "o=abc,c=us", 219 the server would return 221 SearchResultDone "referral" { 222 ldap://hostB/o=abc,c=us 223 ldap://hostC/o=abc,c=us 224 } 226 Similarly, if the client had issued a modify of "o=xyz,c=us", the server 227 would return 229 ModifyResponse "referral" { 230 ldap://hostD/o=xyz,c=us 231 } 233 5.2. Superior Reference 235 This use of the ref attribute is similar to the superior reference con- 236 cept found in X.500 [X500]. An LDAP server's root DSE MAY contain the 237 "ref" attribute. The values of the ref attribute in the root DSE that 238 are LDAP URIs SHOULD NOT contain any dn part, just the host name and 239 optional port number. 241 When the server receives an operation for which the base or target entry 242 of the request is not contained in or subordinate to any naming context 243 held by the server, the server will return an LDAPResult with the 244 resultCode set to "referral", and with the referral field filled in 245 using the values from the "ref" attribute from the root DSE. 247 5.3. Unnamed reference 249 This use of the ref attribute is similar to the nonspecific subordinate 250 reference concept found in X.500 [X500]. It goes beyond this concept to 251 facilitate distributed searching or indexing across multiple servers. 252 The ref attribute is used to name an entry in the referencing server. 253 The reference entry may contain other attributes used to select the 254 reference during searching. 256 A multi-valued ref attribute MAY indicate the locations of different 257 resources all associated with the same LDAP entity. The following exam- 258 ple illustrates the use of the ref attribute to indicate two unnamed 259 references. 261 |------------------------------------------------------------------| 262 | Server A | 263 | dn: ref=ldap://hostB/o=abc,c=us dn: ref=ldap://hostC/o=xyz,c=us | 264 | cn: babs cn: babs | 265 | cn: gern cn: bob | 266 | cn: bob | 267 |__________________________________________________________________| 269 |-----------------------------| |-----------------------------| 270 | Server B | | Server C | 271 | dn: o=abc,c=us | | dn: o=xyz,c=us | 272 | o: abc | | o: xyz | 273 | other attributes... | | other attributes... | 274 | | | | 275 | dn: cn=babs,o=abc,c=us | | dn: cn=babs,o=xyz,c=us | 276 | cn: babs | | o: xyz | 277 | other attributes... | | other attributes... | 278 | | | | 279 | dn: cn=gern,o=abc,c=us | | dn: cn=bob,o=xyz,c=us | 280 | cn: gern | | cn: bob | 281 | other attributes... | | other attributes... | 282 | | |_____________________________| 283 | dn: cn=bob,o=abc,c=us | 284 | cn: bob | 285 | other attributes... | 286 |_____________________________| 288 In this example Server A contains two unnamed references to servers B 289 and C. The unnamed reference entries have additional cn attribute values 290 which may be used during a search operation to select the reference for 291 return to a client. 293 6. The referral object class 295 The referral object class is defined as follows. 297 ( 2.16.840.1.113730.3.2.6 NAME 'referral' SUP top STRUCTURAL 298 MAY ( referral $ * ) ) 300 The referral object class is a subclass of top and may contain the 301 referral attribute. It is a structural object class. The referral object 302 class may also contain any other attribute, as indicated by the "*" in 303 the MAY portion of the definition. This is required to support the nam- 304 ing attributes used in the entry's distinguished name. 306 Servers MAY support the ref attribute through use of the referral object 307 class. Servers MAY also support the ref attribute as an operational 308 attribute in any entry, or through use of other object classes. 310 7. The manageDsaIT control 312 A client MAY specify the following control when issuing a search, com- 313 pare, add, delete, modify, or modifyDN request. 315 The control type is 2.16.840.1.113730.3.4.2. The control SHOULD be 316 marked as critical. There is no value; the controlValue field is 317 absent. 319 This control causes entries with the "ref" attribute to be treated as 320 normal entries, allowing clients to read and modify these entries. 322 This control is not needed if the entry containing the referral attri- 323 bute is one used for directory administrative purposes, such as the root 324 DSE, or the server change log entries. Operations on these entries 325 never cause referrals or continuation references to be returned. 327 8. Security Considerations 329 This document defines mechanisms that can be used to "glue" LDAP (and 330 other) servers together. The information used to specify this glue 331 information should be protected from unauthorized modification. If the 332 server topology information itself is not public information, the infor- 333 mation should be protected from unauthorized access as well. 335 9. References 337 [RFC1738] 338 Berners-Lee, T., Masinter, L., and McCahill, M., "Uniform Resource 339 Locators (URL)", RFC 1738, CERN, Xerox Corporation, University of 340 Minnesota, December 1994, 341 343 [LDAP] 344 M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol 345 (v3)", Internet Draft draft-ietf-asid-ldapv3-protocol-04.txt, March, 346 1997. 348 [BRADNER97] 349 S. Bradner, "Key Words for use in RFCs to Indicate Requirement Lev- 350 els", Internet Draft, draft-bradner-key-words-03.txt, January 1997. 352 [X500] 353 ITU-T Rec. X.501, "The Directory: Models", 1993. 355 [RFC2079] 356 M. Smith, "Definition of an X.500 Attribute Type and an Object Class 357 to Hold Uniform Resource Identifiers (URIs)", RFC 2079, January 358 1997. 360 10. Author's Address 362 Tim Howes 363 Netscape Communications Corp. 364 501 E. Middlefield Rd. 365 Mountain View, CA 94043 366 USA 367 EMail: howes@netscape.com 369 Mark Wahl 370 Critical Angle Inc. 371 4815 W Braker Lane #502-385 372 Austin, TX 78759 373 USA 374 EMail: M.Wahl@critical-angle.com