idnits 2.17.1 draft-watts-ldapext-x500-referrals-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-23) 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 11 longer pages, the longest (page 1) being 61 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** 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. ** 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 -- however, there's a paragraph with a matching beginning. Boilerplate error? RFC 2119 keyword, line 309: '...1578918.2.1.2.1. The control SHOULD be...' RFC 2119 keyword, line 318: '...lue OCTET STRING OPTIONAL }...' RFC 2119 keyword, line 329: '...ts extension, it MUST NOT process the ...' RFC 2119 keyword, line 331: '...ntexts extension MAY choose to process...' RFC 2119 keyword, line 332: '...the URL or MAY choose not to process i...' (8 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 181 has weird spacing: '...rketing ou=...' -- 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 (April 1998) is 9505 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) -- Unexpected draft version: The latest known version of draft-bradner-key-words is -02, but you're referring to -03. ** Obsolete normative reference: RFC 1777 (ref. 'LDAPv2') (Obsoleted by RFC 3494) -- Unexpected draft version: The latest known version of draft-ietf-asid-ldapv3-url is -03, but you're referring to -04. -- Possible downref: Non-RFC (?) normative reference: ref. 'X518' Summary: 12 errors (**), 0 flaws (~~), 3 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 IETF LDAPEXT Working Group David Watts 3 INTERNET-DRAFT Data Connection Ltd. 4 Steve Orbell 5 Data Connection Ltd. 6 April 1998 8 Efficient Referral Chasing 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 view the entire list of current Internet-Drafts, please check 24 the "1id-abstracts.txt" listing contained in the Internet-Drafts 25 Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net 26 (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au 27 (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu 28 (US West Coast). 30 Distribution of this memo is unlimited. Editorial comments should be 31 sent to the authors. Technical discussion should take place on the IETF 32 IETF LDAP Extension Working Group mailing list 33 . 35 2. Abstract 37 This document defines an extension to the LDAP URL format and a 38 control on a LDAP search operation which, together, permit LDAP 39 clients to chase LDAP referrals in a more efficient and more 40 X.500-like manner. 42 3. Contents of this Document 44 The remaining sections in this document are as follows. 46 - Section 4 gives some background on distributed directories and 47 referrals. 49 - Section 5 describes the limitations of LDAP referrals and explains 50 why these limitations are unacceptable. 52 - Sections 6 and 7 formally define the new URL extension and the new 53 search control. 55 - Sections 8 and 9 give the formal rules governing client and server 56 behaviour with respect to the new extension and control. 58 - Sections 10 to 12 cover security, references and authors' addresses. 60 The key words "MUST", "MUST NOT", "SHOULD", and "MAY" used in this 61 document are to be interpreted as described in [BRADNER97]. 63 4. Background - Distributed Directories and Referrals 65 4.1 Centralised and Distributed Directories 67 In the LDAP/X.500 model, a directory may be centralised in a single 68 server or distributed over several servers. 70 4.1.1 Centralised Directories 72 In the centralised model, the single server performs all operations, 73 returning either results or errors. 75 There is no requirement to communicate with other servers, because they 76 are outside the scope of the model. 78 4.1.2 Distributed Directories 80 In the distributed model, when a server receives an operation which it 81 cannot satisfy (or can only satisfy partially), it can do one of two 82 things. 84 - It can chain the request to a second server which can satisfy the 85 request. This second server performs the operation and passes the 86 results back to the first server. The first server merges those 87 results with any which have been produced locally or returned from 88 other chained requests, and passes the combined result back to the 89 client. 91 The client has no further work to perform. 93 - It can pass a continuation reference (i.e. a referral) back to the 94 requestor, along with any results which have been produced locally. 95 The client may then use the information in the referral to contact 96 other servers and continue processing the operation. 98 This requires the client, not only to contact the other servers, but 99 also to perform server functions such as merging results, discarding 100 any duplicates, referral loop detection, and managing size and time 101 limits. 103 The latter behaviour is typical of unmanaged directories and of 104 low-end servers which do not implement chaining. 106 The former behaviour is preferable in managed directories. It allows 107 truly lightweight clients to be deployed and avoids the network and 108 processing overhead of clients connecting to, and authenticating with, 109 multiple servers. 111 4.2 LDAPv2 113 LDAPv2 [LDAPv2] defines a simplified version of the X.500 Directory 114 Access Protocol (DAP). It permits access to a directory using a 115 restricted set of ASN.1 encodings, and without requiring an OSI stack. 117 LDAPv2 thus circumvents some of the overhead associated with DAP and 118 allows more lightweight directory access clients to be deployed. 120 Like DAP, LDAPv2 defines abstract operations for accessing a directory. 121 LDAPv2 does not define either: 123 - a chaining mechanism (because LDAP is an access protocol) 125 - a referral mechanism (for simplicity, because LDAP is lightweight). 127 4.3 The Requirement for Referrals 129 Referrals are required in a distributed directory when the servers 130 are incapable of chaining. 132 Even when servers are capable of chaining, referrals may still be 133 useful. If a server tries to chain to a second server, but the second 134 server is busy or unavailable, the first server should return a 135 referral to the client to indicate that the operation could not be 136 completed. 138 In the case where the server is capable of chaining, the client will 139 not generally chase the returned referrals, since the server will 140 already have tried to contact the referred-to server. The information 141 in the referral may still be of use, for example to: 143 - indicate the partial nature of the results to the human user 145 - chase the referral later (by which time the referred-to server might 146 no longer be unavailable/busy). 148 4.4 LDAPv3 150 One of the ways in which LDAPv3 [LDAPv3] extends LDAPv2 is by defining 151 a referral mechanism. Referrals are LDAP URLs, defined in [URL] to 152 contain the following fields. All fields are optional. 153 - name/address/port of the referred-to server 154 - DN of the base object of Search (or other operation) 155 - attributes to be returned from Search 156 - scope of Search (base-object/one-level/whole-subtree) 157 - filter for Search 158 - extensions 159 5. Limitations of LDAPv3 Referrals 161 LDAP URLs as defined in [URL] suffer from the following limitations. 162 - They can be inefficient. 163 - They are incompatible with X.500 referrals. 165 5.1 Inefficient Referrals 167 A common topology for managing a distributed directory is to divide 168 the naming contexts amongst the cooperating servers in a strictly 169 hierarchical manner. 171 Example - Distributed Directory for ACME Corp 173 level 1 c=US 174 | 175 | 176 | 177 level 2 o=ACME 178 | 179 ---------------|---------------- 180 | | | 181 level 3 ou=Sales ou=Marketing ou=Research 182 | | | 183 ... ... ... 185 level 4 187 2 servers hold the directory for ACME Corp: 188 - server A contains levels 1 and 2 (i.e. US, ACME) 189 - server B contains level 3 (Sales, Marketing, Research) and 190 subordinate levels 192 Servers A and B hold knowledge of the sections of the DIT held by 193 each other. 195 If server A is unable to chain to server B, then a LDAPv3 196 whole-subtree Search from o=ACME,c=US will return: 197 - an entry for ACME (if it matches the filter) 198 - a referral to server B, to search from ou=Sales,o=ACME,c=US 199 - a referral to server B, to search from ou=Marketing,o=ACME,c=US 200 - a referral to server B, to search from ou=Research,o=ACME,c=US 202 Thus when the client chases the referrals to continue the search 203 in server B, it has to chase 3 different referrals, even though 204 they are referrals to the same server at sibling nodes. 206 It would be far more efficient to have a single referral to server B, 207 with semantic 209 "search from all the sibling nodes just below o=ACME,c=US" 211 Chasing three referrals instead of one is not terribly inefficient, but 212 in real-life directory deployments, the number of subordinates at each 213 level may be much larger - perhaps several thousand. 215 5.2 Incompatibility with X.500 referrals 217 X.500 referrals are defined in X.518 [X518]. In addition to the 218 information contained in a LDAP URL, they contain a field 219 nameResolutionPhase. 221 - nameResolutionPhase 'not completed' indicates that the referral 222 contains the DN of entry from which to continue the search. 224 - nameResolutionPhase 'completed' indicates that the referral contains 225 the DN of PARENT of the entry from which to continue the search. 227 In the ACMECorp example in 5.1, if server A is unable to chain to 228 server B, then it will return: 230 - an entry for ACME (if it matches the filter) 232 - a single referral to server B, to search from all the naming contexts 233 which are immediately subordinate to o=ACME,c=US 234 (i.e. with nameResolutionPhase = 'completed') 236 If this X.500 referral is converted to a LDAP referral 238 ldap://serverb/o=ACME,c=US 240 and the client converts this to a search operation to be passed 241 to server B, then the nameResolutionPhase = 'completed' information 242 will be lost. 244 Server B will therefore attempt to continue the search from 245 o=ACME,c=US (rather than each of its subordinates). Server B, when it 246 follows the Find DSE procedure in [X518] section 18, will either chain 247 or refer back to server A. This will then lead to a referral loop 248 between servers A and B. 250 Note that this problem cannot be overcome by 'munging' the X.500 251 referral when it comes to convert it to LDAP. The information 252 which would be required to produce usable LDAP referrals: 254 ldap://serverb/ou=Sales,o=ACME,c=US 255 ldap://serverb/ou=Marketing,o=ACME,c=US 256 ldap://serverb/ou=Research,o=ACME,c=US 258 (i.e. the RDNs) is not contained in the X.500 referral. 260 This information may not even be available to the server which is 261 converting from the X.500 referral to the LDAP referral. 263 - The X.500 referral may have been produced by a different server. 265 - The knowledge of server B may be contained in an NSSR, rather than 266 in 3 subordinate references. 268 Thus LDAP referrals are incompatible with X.500 referrals. This means 269 that LDAPv3 cannot be mapped to a strict subset of the X.500 270 Directory Abstract Service, and thus fails to meet one of its 271 principal design goals ([LDAPv3] section 3.1). 273 5.3 Summary 275 LDAP referrals are inefficient in certain distributed configurations, 276 and are incompatible with X.500 referrals. 278 These limitations are related because, as shown above, the extra 279 information contained in X.500 referrals overcomes the inefficiency 280 inherent in LDAP referrals. 282 6. The subcontexts URL Extension 284 This section defines a LDAP URL extension. The extension indicates 285 that the URL does not refer to the entry named in the URL, but instead 286 refers to all the context prefix entries which are immediately 287 subordinate to the entry named in the URL. 289 The extension type is "subcontexts". The extension value is absent. 290 The extension is critical. 292 eg: 294 ldap://serverb/o=ACME,c=US????!subcontexts 296 The subcontexts URL extension is returned within a LDAP URL which is 297 part of a SearchResultReference, as defined in section 4.5.2 of 298 [LDAPv3]. 300 7. The Subordinate Contexts Control 302 A client may specify the following control when issuing a search 303 request. 305 This control is included in the searchRequest message as part of the 306 controls field of the LDAPMessage, as defined in Section 4.1.12 of 307 [LDAPv3]. 309 The control type is 1.2.826.0.1.1578918.2.1.2.1. The control SHOULD be 310 marked as critical. There is no value - the controlValue field is 311 absent. 313 The ASN.1 production for Control defined in [LDAPv3] is: 315 Control ::= SEQUENCE { 316 controlType LDAPOID, 317 criticality BOOLEAN DEFAULT FALSE, 318 controlValue OCTET STRING OPTIONAL } 320 The Subordinate Contexts Control is therefore encoded as follows: 322 3020 323 041B 312E322E3832362E302E312E313537383931382E322E312E322E31 324 0101 FF 326 8. Client Behaviour 328 The subcontexts URL extension is critical. Therefore, if a client does 329 not support the subcontexts extension, it MUST NOT process the URL. 331 Clients which support the subcontexts extension MAY choose to process 332 the URL or MAY choose not to process it. If the client chooses to 333 process the URL, the search operation which is passed to the 334 referred-to server MUST include the Subordinate Contexts Control. 336 9. Server Behaviour 338 There are two aspects to the Server behaviour: 339 - Returning the subcontexts URL extension 340 - Processing the Subordinate Contexts Control. 342 9.1 Returning the subcontexts URL extension 344 If a server is processing a Search and has found the base object, but 345 does not hold the entire search area and is unable to chain, then each 346 of the LDAP URLs which it returns may take one of the following forms. 348 - The DN refers to the entry from which to continue the search, and 349 the subcontexts URL extension is absent. 351 (This is the format defined in [URL].) 353 - The DN refers to the parent of all the context prefix entries from 354 which to continue the search, and the subcontexts URL extension is 355 present. 357 The formal rules governing the presence of the subcontexts URL 358 extension are as follows. 360 - The subcontexts URL extension MUST NOT be returned in a URL which 361 is returned from a non-Search operation, or in a URL for a Search 362 operation where the server has been unable to find the base object. 364 i.e. the subcontexts URL extension MUST NOT be present in a URL 365 which is contained in a referral error. 367 - The subcontexts URL extension MAY be returned in a URL for a Search 368 operation where the server has found the base object. 370 i.e. the subcontexts URL extension MAY be returned in a URL which is 371 contained in a SearchResultReference. 373 - If a server is unable to complete a search, and the search needs to 374 be continued at many sibling context prefix nodes, all of which are 375 stored in the same server, then the server SHOULD return a single 376 URL with the subcontexts extension (in preference to many URLs 377 without the subcontexts extension). 379 This allows clients to chase the referrals more efficiently. 381 9.2 Processing the Subordinate Contexts Control 383 The Subordinate Contexts Control is critical. Therefore, if a server 384 does not support it, it MUST NOT perform the operation, and MUST 385 instead return the resultCode unsupportedCriticalExtension. 387 Servers which support the Subordinate Contexts Control MUST continue 388 the Search from all of the entries which are context prefix 389 subordinates of the baseObject. If there are no context prefix entries 390 which are immediately subordinate to the baseObject, then the server 391 MUST return the result code invalidReference. 393 10. Security Considerations 395 The server decision to return a referral containing the DN of the 396 parent, rather than the DN of the entry itself, involves disclosing 397 less, rather than more, information to the client. 399 There are therefore no security considerations over and above those 400 involved in the decision to return a LDAP URL as considered in [URL]. 402 11. References 404 [BRADNER97] 405 S. Bradner, "Key Words for use in RFCs to Indicate Requirement Lev- 406 els", Internet Draft, draft-bradner-key-words-03.txt, January 1997. 408 [LDAPv2] 409 W . Yeong, T. Howes, S. Kille, "Lightweight Directory Access 410 Protocol", RFC 1777, March, 1995. 412 [LDAPv3] 413 M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol 414 (v3)", Internet Draft draft-ietf-asid-ldapv3-protocol-09.txt, 415 November, 1997. 417 [URL] 418 T. Howes, "The LDAP URL Format", Internet draft draft-ietf-asid- 419 ldapv3-url-04.txt, August 1997. 421 [X518] 422 ITU-T Rec. X.518, "The Directory: Procedures for Distributed 423 Operation", 1993. 425 12. Authors' Addresses 427 David Watts 428 Data Connection Ltd. 429 100 Church Street 430 Enfield 431 Middlesex 432 England 433 EN2 6BQ 434 EMail: djw@datcon.co.uk 436 Steve Orbell 437 Data Connection Ltd. 438 100 Church Street 439 Enfield 440 Middlesex 441 England 442 EN2 6BQ 443 EMail: so@datcon.co.uk