idnits 2.17.1 draft-ietf-crisp-firs-core-03.txt: 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: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 1 character in excess of 72. -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Unrecognized Status in ' Category: Standards-Track', assuming Proposed Standard (Expected one of 'Standards Track', 'Full Standard', 'Draft Standard', 'Proposed Standard', 'Best Current Practice', 'Informational', 'Experimental', 'Informational', 'Historic'.) -- 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 (August 2003) is 7532 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: 'CRISP-REQ' is mentioned on line 1843, but not defined == Unused Reference: 'RFC1274' is defined on line 1858, but no explicit reference was found in the text == Unused Reference: 'RFC2252' is defined on line 1878, but no explicit reference was found in the text == Unused Reference: 'RFC2253' is defined on line 1883, but no explicit reference was found in the text == Unused Reference: 'RFC2254' is defined on line 1888, but no explicit reference was found in the text == Unused Reference: 'RFC2277' is defined on line 1898, but no explicit reference was found in the text == Unused Reference: 'RFC2596' is defined on line 1905, but no explicit reference was found in the text == Unused Reference: 'RFC2798' is defined on line 1912, but no explicit reference was found in the text ** Obsolete normative reference: RFC 1274 (Obsoleted by RFC 4524) ** Obsolete normative reference: RFC 2222 (Obsoleted by RFC 4422, RFC 4752) ** Obsolete normative reference: RFC 2251 (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) ** Obsolete normative reference: RFC 2252 (Obsoleted by RFC 4510, RFC 4512, RFC 4517, RFC 4523) ** Obsolete normative reference: RFC 2253 (Obsoleted by RFC 4510, RFC 4514) ** Obsolete normative reference: RFC 2254 (Obsoleted by RFC 4510, RFC 4515) ** Obsolete normative reference: RFC 2255 (Obsoleted by RFC 4510, RFC 4516) ** Obsolete normative reference: RFC 2256 (Obsoleted by RFC 4510, RFC 4512, RFC 4517, RFC 4519, RFC 4523) ** Obsolete normative reference: RFC 2596 (Obsoleted by RFC 3866) ** Downref: Normative reference to an Informational RFC: RFC 2798 ** Obsolete normative reference: RFC 3377 (Obsoleted by RFC 4510) ** Obsolete normative reference: RFC 3490 (Obsoleted by RFC 5890, RFC 5891) -- Possible downref: Normative reference to a draft: ref. 'FIRS-ARCH' -- Possible downref: Normative reference to a draft: ref. 'FIRS-ASN' -- Possible downref: Normative reference to a draft: ref. 'FIRS-CONTCT' -- Possible downref: Normative reference to a draft: ref. 'FIRS-DNS' -- Possible downref: Normative reference to a draft: ref. 'FIRS-DNSRR' -- Possible downref: Normative reference to a draft: ref. 'FIRS-IPV4' -- Possible downref: Normative reference to a draft: ref. 'FIRS-IPV6' Summary: 14 errors (**), 0 flaws (~~), 10 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT Eric A. Hall 3 Document: draft-ietf-crisp-firs-core-03.txt August 2003 4 Expires: March, 2004 5 Category: Standards-Track 7 The Federated Internet Registry Service: 8 Core Elements 10 Status of this Memo 12 This document is an Internet-Draft and is in full conformance with 13 all provisions of Section 10 of RFC 2026. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six 21 months and may be updated, replaced, or obsoleted by other 22 documents at any time. It is inappropriate to use Internet-Drafts 23 as reference material or to cite them other than as "work in 24 progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 Copyright Notice 34 Copyright (C) The Internet Society (2003). All Rights Reserved. 36 Abstract 38 This document describes the core technical elements of the 39 Federated Internet Registry Service (FIRS), a distributed service 40 for storing, locating and transferring information about Internet 41 resources using LDAPv3. 43 Table of Contents 45 1. Introduction...............................................3 46 2. Prerequisites and Terminology..............................3 47 3. The FIRS Namespace.........................................3 48 3.1. The domainComponent (dc=) Namespace Component...........4 49 3.2. The inetResources Namespace Component...................4 50 3.3. The Resource-Specific Namespace Component...............5 51 3.4. Attribute References....................................5 52 3.5. Referrals...............................................6 53 3.5.1. Referral source entries...........................6 54 3.5.2. Referral target data..............................7 55 3.5.3. Subordinate reference referrals..................11 56 3.5.4. Continuation reference referrals.................12 57 4. Global FIRS Object Classes and Attributes.................12 58 4.1. The inetResources Object Class.........................13 59 4.1.1. Naming syntax....................................13 60 4.1.2. Schema definition................................13 61 4.1.3. Example..........................................16 62 4.2. The inetAssociatedResources Object Class...............17 63 4.2.1. Naming syntax....................................17 64 4.2.2. Schema definition................................17 65 4.2.3. Example..........................................19 66 4.3. The referral Object Class..............................19 67 5. Global Query Processing Rules.............................20 68 5.1. Query Pre-Processing...................................21 69 5.2. Query Bootstrap Models.................................22 70 5.2.1. Targeted query processing........................23 71 5.2.2. Top-down processing..............................24 72 5.2.3. Bottom-up processing.............................27 73 5.2.4. SRV processing...................................30 74 5.3. Query Processing.......................................31 75 5.3.1. The inetResourcesControl server control..........31 76 5.3.2. Matching filters.................................34 77 5.3.3. Query-volume restrictions........................36 78 5.3.4. Authentication restrictions......................37 79 5.3.5. Extended attribute ACLs..........................37 80 5.3.6. Protocol and schema version controls.............39 81 5.4. Referral Processing....................................40 82 6. Security Considerations...................................42 83 7. IANA Considerations.......................................42 84 8. Normative References......................................42 85 9. Changes from Previous Versions............................44 86 10. Author's Address..........................................47 87 11. Acknowledgments...........................................47 88 12. Full Copyright Statement..................................48 89 1. Introduction 91 This specification defines the core object classes, attributes, 92 syntax rules, matching filters, and operational behaviors for the 93 FIRS service as a whole. Refer to [FIRS-ARCH] for information on 94 the FIRS architecture, and the resource-specific specifications 95 for definitions and rules which govern each of the different 96 resource-types. 98 The definitions in this specification are intended to be used with 99 FIRS. Their usage outside of FIRS is not prohibited, but any such 100 usage is beyond this specification's scope of authority. 102 2. Prerequisites and Terminology 104 The complete set of specifications in the FIRS collection 105 cumulative define a structured and distributed information service 106 using LDAPv3 [RFC3377] for the data-formatting and transport 107 functions. This specification should be read in the context of 108 that set, which currently includes [FIRS-ARCH], [FIRS-DNS], [FIRS- 109 DNSRR], [FIRS-CONTCT], [FIRS-ASN], [FIRS-IPV4] and [FIRS-IPV6]. 111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 112 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 113 in this document are to be interpreted as described in RFC 2119. 115 3. The FIRS Namespace 117 The FIRS namespace acts as an index to the federated partition 118 structure of the globally-distributed FIRS database. There are 119 three major components to this namespace, which are: 121 * The domainComponent entries. Each partition of the 122 globally-distributed FIRS database is uniquely represented 123 by a sequence of domainComponent relative distinguished 124 names. These sequences effectively identify the root scope 125 of authority for each partition in the global directory 126 database. Partitions MAY be replicated across one or more 127 servers, but every instance of a specific partition MUST 128 use the same sequence of domainComponent relative 129 distinguished names. 131 * An inetResources entry. All of the FIRS-related resource- 132 specific entries in the global database are required to be 133 stored within a well-known "cn=inetResources" container 134 entry at the root of each partition. These well-known 135 entries act as application-specific access points within 136 the globally distributed directory database, and also 137 provide some information about the partition and the 138 organization which manages that partition. 140 * The resource-specific entries. Each of the resource- 141 specific entries within the inetResources container entries 142 have their own unique naming rules, as defined in the 143 governing specifications for those resources. 145 Note that an inetResources container or any of the resource- 146 specific entries MAY exist as referral stub entries that redirect 147 clients to other entries in the FIRS database. 149 The naming rules associated with the different portions of the 150 FIRS namespace are discussed in more detail below. 152 3.1. The domainComponent (dc=) Namespace Component 154 The global FIRS directory database is divided into administrative 155 partitions, each of which represent a scope-of-authority for a 156 certain portion of the global database. The root of each partition 157 is represented by a sequence of domainComponent relative 158 distinguished names (RDNs), as defined in RFC 2247 [RFC2247]. In 159 this model, the scope-of-authority for a FIRS partition is derived 160 from a domain name in the global DNS directory, meaning that 161 whoever has authority over any particular domain name effectively 162 has authority over the related FIRS partition. 164 Note that the domainComponent attribute is restricted to seven-bit 165 character codes, and is therefore effectively limited to using 166 character codes from US-ASCII [US-ASCII]. Due to this limitation, 167 internationalized domain names MUST be converted into their ASCII- 168 compatible forms using the "ToASCII" process defined in RFC 3490 169 [RFC3490] before the domainComponent RDNs are used in the 170 directory database or LDAP messages. 172 3.2. The inetResources Namespace Component 174 The FIRS-specific directory entries are segregated from other 175 application-specific entries by the use of a container entry with 176 the MANDATORY name of "cn=inetResources". 178 Every FIRS-specific resource that is to be located via the FIRS 179 service MUST be stored within the inetResources container entry. 181 However, the entries themselves MAY exist as referrals which point 182 to entries in other LDAP partitions or namespace branches if this 183 is necessary or desirable (see section 3.5). 185 3.3. The Resource-Specific Namespace Component 187 Every resource-specific entry has a relative distinguished name 188 which identifies that resource within the context of the 189 inetResources container of a FIRS partition. Examples of these 190 entries can be seen in Figure 1 of [FIRS-ARCH], and include 191 "cn=example.com" which refers to the "example.com" DNS domain 192 resource, and "cn=admins@example.com" which refers to the 193 "admins@example.com" contact resource. 195 Each of the FIRS resource-types have their own specific naming 196 rules which govern those resources. Refer to the resource-specific 197 specifications for information on those rules. 199 3.4. Attribute References 201 Many of the core attributes provide pointers to other resources, 202 thereby allowing the client to initiate follow-up queries for 203 related data. For example, an entry for a domain name resource has 204 attributes for a variety of contacts for the domain name, and FIRS 205 clients are able to extract and use that data to generate 206 additional queries for any of those contact resources. 208 Pointers to resources that are stored within the global FIRS 209 database are generally provided as the identifier for the target 210 resource, using the syntax rules associated with the resource in 211 question. For example, a pointer to the contact entry of 212 "admins@example.com" will be provided as that resource name, using 213 the syntax rules associated with contact names. Examples of this 214 usage form can be seen in Figure 1 of [FIRS-ARCH]. 216 Note that traditional LDAP models often use URIs or distinguished 217 names to provide fully-qualified pointers to entries, although 218 these syntaxes usually require detailed knowledge about the target 219 resources or the servers for the target partition. However, FIRS 220 is much more distributed than traditional LDAP usages, and may 221 require pointing to data in an opaque partition, or where the 222 topology of the target partition is unknown. For these reasons, 223 attribute references in FIRS typically use the short name of the 224 target resource, with the expectation that the client will use the 225 attribute value as the query seed for new FIRS queries. 227 However, pointers to resource data that is likely to be stored 228 outside the global FIRS database (such as a web page) is generally 229 provided as a URI so that any necessary application and/or 230 protocol transfer services can be specified. For example, the 231 inetResources object class provides an attribute for the 232 organization which manages the resource, with a secondary 233 attribute for a URL associated with the target organization, thus 234 allowing additional (extra-directory) information to be specified 235 and retrieved where this would be useful. 237 In those cases where a URI provides an LDAP URL that references a 238 resource in the global FIRS directory, the URL data SHOULD use the 239 referral URL rules described in section 3.5. 241 3.5. Referrals 243 Entries in the namespace can refer to other entries, as necessary 244 or desirable. Specifically, FIRS allows certain entries to be 245 created as "placeholders" for other entries which contain the 246 canonical data, and also allows "stub" child entries to provide 247 reference pointers to additional data. 249 LDAP provides several methods for conveying and processing these 250 kinds of referrals, although FIRS only makes specific use of 251 subordinate reference referrals and continuation reference 252 referrals. Subordinate reference referrals indicate that the 253 search base in the original query is an alias for some other 254 entry, and that the query has to be restarted with a new search 255 base in order for the search operation to be processed. Meanwhile, 256 continuation reference referrals indicate that the search was 257 successfully initiated and that some data has been found, but that 258 additional queries for additional resources are required for the 259 query to be completely exhausted. 261 3.5.1. Referral source entries 263 Referral entries can be used in FIRS in two distinct scenarios, 264 with each scenario having different naming requirements for the 265 referral sources. 267 In the first instance, specific entries can be defined as 268 referrals so that queries for the entry always generate a single 269 referral. This may be necessary when an entire inetResources 270 container entry needs to be redirected to another inetResources 271 container entry in another tree, but can also be useful when 272 entries only exist as placeholders for other entries. 274 For example, a registrar can create referral entries for variant 275 domain names whenever a canonical domain name is registered, with 276 the variant entries only providing referrals to the canonical 277 entry. Similarly, an entry for the host named "www.example.com" 278 could exist as a referral which pointed to the domain name entry 279 for "www-1.example.net". In these scenarios, users who generate 280 queries for the alias domain name entries would always get 281 referred to the canonical domain name entries. 283 Most entries are expected to provide some kind of information, and 284 in this kind of situation, the canonical entry will have data, but 285 will need to be able to generate referrals to one or more other 286 entries where additional data about the resource can be retrieved. 287 For example, the entries in the partition for the "com" domain 288 registry can provide basic information about a domain, but can 289 also provide a referral to the domain registrar, while the 290 registrar can provide another referral to the domain operator. 292 In these cases, each partition would need to have an entry for the 293 resource in question, while child entries underneath each of those 294 entries would be used to generate the necessary referrals. For 295 example, the "example.com" domain would likely exist as a 296 canonical entry within a registry's partition, with that entry 297 providing information that the registry had about that domain 298 name. Meanwhile, the registry could have a child entry underneath 299 the canonical entry which provided a referral to the registrar's 300 partition, and so forth. 302 The relative distinguished name of a referral child entry is 303 usually irrelevant, and can therefore be defined according to 304 local policy rather than fixed rules. However, operators SHOULD 305 NOT use names that are likely to match against searches for other 306 resources. In the general case, using generalized relative 307 distinguished names such as "cn=ref1" or the like would be the 308 safest practice. 310 3.5.2. Referral target data 312 Referral entries MUST use the ref attribute and referral object 313 class, as defined in RFC 3296 [RFC3296]. 315 The referral target is provided to the client with the ref 316 attribute, which provides a URI as the destination pointer, 317 although there are some additional FIRS-specific restrictions 318 which are as follows: 320 * At least one of the URLs in a referral MUST be an LDAP URL 321 as specified in RFC 2255 [RFC2255], and FIRS clients MUST 322 ignore all non-LDAP URIs. Note that general-purpose LDAP 323 referrals are allowed to use any protocol, but FIRS clients 324 have a requirement to automatically process referrals, and 325 this requirement precludes the use of ambiguous services 326 and their data formats. As such, every FIRS referral MUST 327 specify at least one LDAP URL, and FIRS clients MUST only 328 use the LDAP URLs. 330 * Referral targets MUST use domainComponent ("dc=") naming 331 syntax for target partitions. If a referral needs to 332 specify an exact partition or container for the referral 333 target, the path to the referral target MUST be provided as 334 the search base of the LDAP URLs, and this data MUST be 335 used by FIRS clients when the subsequent query is built. 337 * The LDAP URL data MUST be escaped prior to being sent. For 338 example, domain names and contact names can contain UTF-8 339 character data, and some of those character codes will need 340 to be escaped in order to be passed as URL data. Similarly, 341 the IPv4 and IPv6 network address syntaxes defined in this 342 document make use of the forward-slash ("/") character to 343 indicate a subnet prefix, and if this character needs to be 344 provided in a URL, it must be provided in the escaped form 345 ("%2F" in this example). 347 In the general sense, referrals SHOULD NOT provide any more 348 information about the referral target than absolutely necessary. 349 For example, if a referral source for a domain name resource needs 350 to reference a referral target for another domain name resource, 351 then only the resource type and identifier SHOULD be provided 352 (this will give the client enough information to begin a new 353 query), while data such as the target partition or LDAP server 354 SHOULD NOT be provided since the authoritative forms of this 355 information will be detected as part of the subsequent query's 356 bootstrapping process. With this in mind, the following 357 recommendations apply to referral targets in the general sense, 358 and SHOULD be followed: 360 * In those cases where a referral points to a FIRS resource 361 of a known type and name (E.G., a domain name, or an IPv4 362 address), the referral URL MUST specify the matching filter 363 and assertion value of the referral target. For example, a 364 referral that points to a DNS domain resource MUST provide 365 the inetDnsDomainMatch matching filter and value in the 366 filter element of the LDAP URL (such as providing 367 "(1.3.6.1.4.1.7161.1.3.0.1:=example.com)" for a referral to 368 the "example.com" DNS domain). Clients MUST use this data 369 to seed the resource type and assertion value of the 370 subsequent query if it is provided. 372 * In those cases where a referral points to a FIRS resource 373 in a particular partition, the referral URL MUST specify 374 the search base element. For example, if an entry for the 375 "example.com" domain name resource in the "com" partition 376 needs to specify the "example.com" domain name resource in 377 the "registrar.com" partition, then the referral MUST 378 specify "dc=registrar,dc=com" in the search base element of 379 the LDAP URL. Clients MUST use this data to seed the boot 380 partition of the subsequent query if it is provided. 382 * In those cases where a referral points to some other kind 383 of entry, the referral target SHOULD specify as little 384 information as possible, while still providing an adequate 385 reference. For example, if a referral needs to point to a 386 contact in an alternate container of a specific partition, 387 the full path to the referral target SHOULD be specified in 388 the search base element of the URL. Clients MUST use the 389 additional information if it is provided. 391 * In the general case, referral sources and targets SHOULD 392 have the same resource-specific object classes defined, 393 although referral targets MAY specify other resource types 394 if needed. For example, the referral source and target for 395 a DNS domain resource should both have the inetDnsDomain 396 object class defined, although a referral may point to an 397 IPv4 host address if this is necessary. If a referral 398 target is known to have a different object class than the 399 referral source, a matching filter for the referral target 400 MUST be provided in the filter element of the LDAP URLs, 401 and this data MUST be used by FIRS clients when the 402 subsequent query is built. 404 * LDAP URLs SHOULD NOT provide host identifiers or port 405 numbers unless this is absolutely necessary, since the 406 client will usually discover this information during the 407 bootstrap process. If a referral provides this information, 408 it MUST be used by FIRS clients when the subsequent query 409 is built. 411 * Attribute lists, scope filters, and URL extensions SHOULD 412 NOT be provided, and these elements MUST be ignored by FIRS 413 clients unless an applicable specification details explicit 414 behavior for these elements. 416 * The operators of a partition MUST NOT restrict referral 417 data to verifiable referral targets. Providers MAY validate 418 the referral targets in URLs, but a lack of knowledge 419 regarding a target MUST NOT be treated as sufficient cause 420 to prevent the referral target from being specified. 422 * Referral targets MAY themselves be referrals to other 423 entries, but recursive referrals are discouraged. Clients 424 MAY discontinue referral processing after a reasonable 425 amount of effort (eight referrals is a reasonable 426 threshold, but the actual amount of processing is left to 427 the discretion of the clients). 429 An example referral is illustrated in Figure 1 of [FIRS-ARCH]. In 430 that example, the referral data provides an inetDnsDomainMatch 431 matching filter with the explicit assertion value of 432 "www-1.example.net". This data would inform the client of the 433 resource-type to be queried and the assertion value to use, which 434 collectively would give the client everything needed to begin 435 bootstrapping a new query. 437 As another example, a referral to a specific entry could look like 438 the following: 440 ldap://cn=admins@example.com,cn=inetResources, 441 dc=example,dc=com 443 In that example, the referral is pointing to an explicit entry in 444 an explicit container in an explicit partition. Although the 445 client would not be able to tell what kind of resource was being 446 queried for, it would be able to determine the resource-type once 447 an answer was received, based on the object class values of 448 resulting entry. 450 The client-side rules for processing referral URLs are given in 451 section 5.4. 453 Note that the "superior reference referral" defined in RFC 2251 454 [RFC2251] used as a "default referral" for out-of-scope searches 455 is explicitly unsupported in FIRS. Superior reference referrals 456 which are encountered as a part of this service are to be treated 457 as errors and silently ignored. 459 3.5.3. Subordinate reference referrals 461 Subordinate reference referrals are defined in [RFC3296], and are 462 returned whenever the search base specified in a query exists as a 463 referral to some other entry. This means that the query MUST be 464 restarted with the referral target. 466 Specifically, subordinate reference referrals are defined in 467 [RFC3296], and use the SearchResultDone response with a Referral 468 result code as defined in [RFC2251]. Subordinate reference 469 referrals use a subset of the labeledURI syntax as defined in 470 [RFC2079], and use the syntax definitions from [RFC2255] when LDAP 471 URLs in particular are provided, although section 3.5.2 of this 472 document also defines additional restrictions on the allowable URL 473 syntax. This condition means that the current search operation 474 cannot proceed past this point, and the search MUST be restarted. 475 This will most often occur when the inetResources entry for a 476 partition has been redirected to another directory partition. 478 Almost all of the search functions used with FIRS use the 479 inetResources container entry as the search base (the exceptions 480 to this rule are targeted searches for explicit entries), so 481 subordinate reference referrals will most commonly be seen when an 482 inetResources container entry has been redirected to an 483 inetResources container in another directory partition. 485 Servers MUST support the use of subordinate reference referrals, 486 and clients MUST be prepared to accept and process any subordinate 487 reference referrals they receive. 489 When subordinate reference referrals are used, the referral source 490 MUST be defined with the referral object class, and MUST also be 491 defined with the appropriate object class for that resource type. 492 For example, a "cn=inetResources" entry which provided a 493 subordinate reference referral would need to have both the 494 referral and inetResources object classes defined, while a DNS 495 domain resource such as "dc=example.com" would need to have both 496 the referral and inetDnsDomain object classes defined (among the 497 other object class definitions which were required for that 498 entry). Referral targets need to use whatever object classes are 499 appropriate for the resource in question, and MAY also be 500 referrals to other entries. 502 3.5.4. Continuation reference referrals 504 Continuation reference referrals are defined in RFC 2251 505 [RFC2251], and are returned when a search operation has been 506 successfully processed but the answer data also includes referrals 507 to other entries. These referrals are usually provided as 508 supplemental data to an answer, although it's also possible for a 509 continuation reference referral to be the only data in an answer. 511 Specifically, continuation reference referrals use the 512 SearchResultReference response, which is defined and described in 513 section 4.5.3 of [RFC2251]. Continuation reference referrals use a 514 subset of the labeledURI syntax as defined in [RFC2079], and use 515 the syntax definitions from [RFC2255] when LDAP URLs in particular 516 are to be provided, although section 3.5.2 of this document also 517 defines additional restrictions on the allowable URL syntax. This 518 condition means that the current search operation has partially 519 succeeded, but that additional searches SHOULD be started in order 520 for all of the answer data to be retrieved (in many cases, no 521 answer data will be provided, and in those situations, new queries 522 will be required for any data to be retrieved). This will occur 523 whenever the assertion value of a search has matched a resource 524 entry which is being managed by another directory partition, and 525 can occur with any of the search operations described in this 526 document. 528 Servers MUST support the use of continuation reference referrals, 529 and clients MUST be prepared to accept and process any subordinate 530 reference referrals that they receive. 532 When continuation reference referrals are used for this purpose, 533 entries MAY exist for the queried resource, but one or more 534 entries MUST exist with the referral object class defined, and 535 which provide LDAP URLs that point to other entries which have 536 additional information about the resource in question. 538 4. Global FIRS Object Classes and Attributes 540 Each of the schema definitions provided in this document include 541 attribute definitions, naming rules, and other definitions which 542 are designed to facilitate the consistent storage and retrieval of 543 information within the FIRS service. 545 4.1. The inetResources Object Class 547 The inetResources object class is a structural object class which 548 defines the attributes associated with the "cn=inetResources" 549 container entry, and which provides general information about the 550 network resources associated with the current directory partition. 552 4.1.1. Naming syntax 554 This document requires the presence of an entry named 555 "cn=inetResources" in the root of every directory partition which 556 provides FIRS services. 558 4.1.2. Schema definition 560 Every directory partition which provides public FIRS data MUST 561 have a "cn=inetResources" entry in the root of the directory 562 partition. The inetResources entry MUST exist with the top and 563 inetResources object classes defined. If the entry exists as a 564 referral source, the entry MUST also be defined with the referral 565 object class, in addition to the above requirements. 567 The inetResources object class is a structural object class which 568 is subordinate to the top abstract class, and which MUST be 569 treated as a container class capable of holding additional 570 subordinate entries. The inetResources object class has one 571 mandatory attribute which is "cn" (the naming attribute), and also 572 has several optional attributes. Each of the other object classes 573 defined for use with FIRS are subordinate to the inetResources 574 object class and inherit its attributes. 576 The schema definition for the inetResources object class is as 577 follows: 579 inetResources 580 ( 1.3.6.1.4.1.7161.1.1.1 581 NAME 'inetResources' 582 DESC 'The inetResources container for the FIRS service' 583 SUP top 584 STRUCTURAL 585 MUST cn 586 MAY ( inetLocalIdentifier $ o $ ou $ description $ 587 inetResourceComments $ businessCategory $ telephoneNumber $ 588 facsimileTelephoneNumber $ labeledURI $ 589 preferredDeliveryMethod $ physicalDeliveryOfficeName $ 590 postOfficeBox $ postalAddress $ postalCode $ street $ l $ 591 st $ c $ inetAbuseContacts $ inetGeneralContacts $ 592 inetSecurityContacts $ inetTechContacts $ 593 inetGeneralDisclaimer ) ) 595 The attributes from the inetResources object class are described 596 below: 598 businessCategory, see RFC 2256 [RFC2256], section 5.16 600 c (country), see [RFC2256], section 5.7 602 cn (commonName), see [RFC2256], section 5.4 604 description, see [RFC2256], section 5.14 606 facsimileTelephoneNumber, see [RFC2256], section 5.24 608 l (locality), see [RFC2256], section 5.8 610 labeledURI, see RFC 2079 [RFC2079] 612 o (organization), see [RFC2256], section 5.11 614 ou (organizational unit), see [RFC2256], section 5.12 616 physicalDeliveryOfficeName, see [RFC2256], section 5.20 618 postalAddress, see [RFC2256], section 5.17 619 postalCode, see [RFC2256], section 5.18 621 postOfficeBox, see [RFC2256], section 5.19 623 preferredDeliveryMethod, see [RFC2256], section 5.29 625 st (stateOrProvinceName), see [RFC2256], section 5.9 627 street (streetAddress), see [RFC2256], section 5.10 629 telephoneNumber, see [RFC2256], section 5.21 631 inetLocalIdentifier 632 ( 1.3.6.1.4.1.7161.1.1.2 633 NAME 'inetLocalIdentifier' 634 DESC 'Provider name for this entry' 635 EQUALITY caseIgnoreMatch 636 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{1024} ) 638 inetResourceComments 639 ( 1.3.6.1.4.1.7161.1.1.3 640 NAME 'inetResourceComments' 641 DESC 'General comments about this entry' 642 EQUALITY caseIgnoreMatch 643 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{1024} ) 645 inetGeneralDisclaimer 646 ( 1.3.6.1.4.1.7161.1.1.4 647 NAME 'inetGeneralDisclaimer' 648 DESC 'General disclaimer text regarding this data' 649 EQUALITY caseIgnoreMatch 650 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{1024} ) 652 inetGeneralContacts 653 ( 1.3.6.1.4.1.7161.1.1.5 654 NAME 'inetGeneralContacts' 655 DESC 'Contacts for general administrative issues.' 656 EQUALITY caseIgnoreMatch 657 SYNTAX 1.3.6.1.4.1.7161.1.7.1 ) 658 inetAbuseContacts 659 ( 1.3.6.1.4.1.7161.1.1.6 660 NAME 'inetAbuseContacts' 661 DESC 'Contacts for reporting abusive behavior or 662 acceptable-use policy violations.' 663 EQUALITY caseIgnoreMatch 664 SYNTAX 1.3.6.1.4.1.7161.1.7.1 ) 666 inetSecurityContacts 667 ( 1.3.6.1.4.1.7161.1.1.7 668 NAME 'inetSecurityContacts' 669 DESC 'Contacts for general security issues.' 670 EQUALITY caseIgnoreMatch 671 SYNTAX 1.3.6.1.4.1.7161.1.7.1 ) 673 inetTechContacts 674 ( 1.3.6.1.4.1.7161.1.1.8 675 NAME 'inetTechContacts' 676 DESC 'Contacts for general technical issues.' 677 EQUALITY caseIgnoreMatch 678 SYNTAX 1.3.6.1.4.1.7161.1.7.1 ) 680 4.1.3. Example 682 An example of the inetResources object class in use is shown in 683 Figure 1 below. 685 cn=inetResources,dc=example,dc=com 686 [top object class] 687 [inetResources object class] 688 | 689 +-attribute: o 690 | value: "Example Widgets' network resources" 691 | 692 +-attribute: inetGeneralContacts 693 | value: "admins@example.com" 694 | 695 +-attribute: telephoneNumber 696 | value: "1-800-555-1212" 697 | 698 +-attribute: inetResourceComments 699 value: "Please don't send complaints to the 700 postmaster@example.com mailbox." 702 Figure 1: The Example Widgets inetResources container entry. 704 4.2. The inetAssociatedResources Object Class 706 The inetAssociatedResources object class defines attributes which 707 are useful for cross-referencing entries with other resources. For 708 example, it allows inetOrgPerson entries to be associated with 709 IPv4 networks or DNS domains, providing generic cross-reference 710 pointer attributes (this information may be useful if a single 711 organization has multiple DNS domains registered). In short, any 712 resource can be associated with any other resource through the use 713 of this object class. 715 4.2.1. Naming syntax 717 The inetAssociatedResources object class is an auxiliary object 718 class, and not a structural object class. Entries which use this 719 object class definition are defined under the rules associated 720 with the structural object class that defines the Internet 721 resource in question. As such, the naming rules associated with 722 that entry take precedence, and the inetAssociatedResources object 723 class does not define an independent naming syntax. 725 4.2.2. Schema definition 727 The inetAssociatedResources object class is an auxiliary object 728 class which is subordinate to the top object class. The 729 inetAssociatedResources object class has no mandatory attributes, 730 and only has optional attributes. 732 The inetAssociatedResources is intended to be used with the 733 resource-specific structural object classes defined for use with 734 FIRS. The inetAssociatedResources object class is not likely to 735 provide much value when it is associated with the inetResources 736 object class, since the inetResources object class does not 737 specifically define any resources (and since it does not define 738 resources, it cannot define any associated resources). On the 739 other hand, it is reasonable for the inetAssociatedResources 740 object class to be associated with an inetOrgPerson object class 741 entry, particularly if the referenced person (or role) is 742 responsible for the management of multiple resources. 744 The inetAssociatedResources object class MUST NOT be associated 745 with an entry that only exists as a referral source. 747 Each of the associated resource attributes provide multi-valued 748 data, using the syntax notations which are specific to the 749 resource in question. For example, the inetAssociatedDnsDomain 750 attribute provides multiple associated DNS domain name resources 751 using a multi-valued array, with each domain name using the 752 inetDnsDomainSyntax naming rules defined in [FIRS-DNS]. 754 The schema definition for the inetAssociatedResources object class 755 is as follows: 757 inetAssociatedResources 758 ( 1.3.6.1.4.1.7161.1.2.1 759 NAME 'inetAssociatedResources' 760 DESC 'Internet resources associated with this resource.' 761 SUP top 762 AUXILIARY 763 MAY ( inetAssociatedContacts $ inetAssociatedDnsDomains $ 764 inetAssociatedIpv4Networks $ inetAssociatedIpv6Networks $ 765 inetAssociatedAsNumbers ) ) 767 The attributes from the inetAssociatedResources object class are 768 described below: 770 inetAssociatedAsNumbers 771 ( 1.3.6.1.4.1.7161.1.2.2 772 NAME 'inetAssociatedAsNumbers' 773 DESC 'Autonomous system numbers associated with this 774 Internet resource.' 775 EQUALITY caseIgnoreMatch 776 SYNTAX 1.3.6.1.4.1.7161.1.7.0 ) 778 inetAssociatedContacts 779 ( 1.3.6.1.4.1.7161.1.2.3 780 NAME 'inetAssociatedContacts' 781 DESC 'Other contacts associated with this Internet 782 resource.' 783 EQUALITY caseIgnoreMatch 784 SYNTAX 1.3.6.1.4.1.7161.1.4.0 ) 786 inetAssociatedDnsDomains 787 ( 1.3.6.1.4.1.7161.1.2.4 788 NAME 'inetAssociatedDnsDomains' 789 DESC 'DNS domains associated with this Internet resource.' 790 EQUALITY caseIgnoreMatch 791 SYNTAX 1.3.6.1.4.1.7161.1.3.0 ) 792 inetAssociatedIpv4Networks 793 ( 1.3.6.1.4.1.7161.1.2.5 794 NAME 'inetAssociatedIpv4Networks' 795 DESC 'IPv4 networks associated with this Internet 796 resource.' 797 EQUALITY caseIgnoreMatch 798 SYNTAX 1.3.6.1.4.1.7161.1.5.0 ) 800 inetAssociatedIpv6Networks 801 ( 1.3.6.1.4.1.7161.1.2.6 802 NAME 'inetAssociatedIpv6Networks' 803 DESC 'IPv6 networks associated with this entry.' 804 EQUALITY caseIgnoreMatch 805 SYNTAX 1.3.6.1.4.1.7161.1.6.0 ) 807 4.2.3. Example 809 An example of the inetAssociatedResources object class is shown in 810 Figure 2 below. 812 cn=192.0.2.0/24,cn=inetResources,dc=example,dc=com 813 [top object class] 814 [inetResources object class] 815 [inetIpv4Network object class] 816 [inetAssociatedResources object class] 817 | 818 +-attribute: description 819 | value: "The Example Widgets network" 820 | 821 +-attribute: inetAssociatedAsNumbers 822 | value: "65535" 823 | 824 +-attribute: inetAssociatedDnsDomains 825 value: "2.0.192.in-addr.arpa" 827 Figure 2: The inetAssociatedResources attributes associated with 828 the 192.0.2.0/24 IPv4 network entry. 830 4.3. The referral Object Class 832 Entries use the referral object class to define subordinate 833 reference referrals and continuation reference referrals, thereby 834 facilitating the programmatic redirection of queries in support of 835 the referral mechanisms defined in section 3.5. 837 Referral entries MUST conform to the schema specification defined 838 in [RFC3296]. 840 Referral sources MUST NOT contain any user-definable attributes 841 (other than the mandatory naming attribute), and MUST NOT have any 842 subordinate child entries. 844 Refer to section 3.5 for the rules that govern referral URLs in 845 FIRS. Refer to section 5.4 for information on processing referral 846 URLs in FIRS. 848 5. Global Query Processing Rules 850 Another critical aspect to FIRS is the query-processing behavior. 851 These rules govern the ways in which a client parses a query, 852 locates a server which is authoritative for the resource being 853 queried, generates LDAPv3 queries, and processes any resulting 854 referrals. More specifically: 856 * Query pre-processing. The first step is for the client to 857 prepare the query. Portions of this process require the 858 client to determine the type of resource being queried for, 859 and to determine the initial partition which should be used 860 for the query. Since this process is different for each 861 particular resource-type, the rules which govern this 862 behavior are defined in each of the resource-specific 863 specifications. 865 * Bootstrap processing. Once a partition has been determined, 866 the client must locate the LDAP servers which are 867 authoritative for the resource in question. Section 5.2 868 defines three different bootstrap models that clients can 869 use as part of this process, while each of the resource- 870 specific specifications define which of the models are to 871 be used for each particular resource-type. 873 * Query processing. Once a server has been located, the 874 client must submit the LDAP query which was formed during 875 the pre-preprocessing phase. Section 5.3 defines the global 876 considerations for all FIRS queries, while the resource- 877 specific specifications also define additional parameters. 879 * Query post-processing. FIRS explicitly supports different 880 types of LDAP referral mechanisms, any of which may result 881 in the client application restarting the query or 882 initiating a brand-new query. These mechanisms and their 883 behavioral rules are defined in section 5.4. 885 Each of these phases are discussed in more detail below. 887 5.1. Query Pre-Processing 889 Client input is generally limited to a single well-formed unit of 890 data, such as a domain name ("example.com") or an email address 891 ("admins@example.com"), and this single piece of information must 892 be used to subsequently build a fully-formed LDAPv3 query, 893 including the assertion value, the search base, the matching 894 filter, and so forth. All of these steps are part of the pre- 895 processing phase. 897 Although the exact sequence of steps will vary according to the 898 resource-type being queried, there are some commonalities between 899 each of them. Among these steps: 901 * Determine the resource type. Different kinds of resources 902 have different processing steps, validation mechanisms, and 903 so forth, each of which require that the resource-type be 904 appropriately identified. Clients MAY use any mechanisms 905 necessary to force this determination. 907 * Validate and normalize the data. In all cases, the input 908 data MUST be validated and normalized according to the 909 syntax rules defined in the specification which governs the 910 resource-type. As an example of this step, queries for 911 internationalized domain names must be validated and 912 normalized into a canonical UTF-8 form before any other 913 steps can be taken. Similarly, IPv6 addresses are required 914 to conform to specific syntax rules, and input address may 915 need to be expanded or compressed in order to comply with 916 the syntax requirements. 918 * Determine the authoritative directory partition for the 919 named resource. In most cases, the authoritative partition 920 will be a variation of the input query string, but this is 921 not always the case. For example, the default partition for 922 an email address will be extrapolated from the domain 923 component of the email address itself, while the 924 authoritative partition for an ASN uses a reserved 925 (special-purpose) domain name. In some cases, the 926 authoritative partition may change during the subsequent 927 query-processing steps. 929 * Determine the search base for the query. Each resource type 930 has resource-specific query-processing rules which will 931 dictate how the authoritative partitions are mapped to the 932 search base. In some cases, the cn=inetResources container 933 entry in the authoritative partition will be used "as-is", 934 while in other cases, the cn=inetResources container entry 935 in a delegation parent of the authoritative partition will 936 be used instead. In some cases, the search base may change 937 during subsequent query-processing steps. 939 * Determine the assertion value for the query. The assertion 940 value will usually be the normalized form of the input 941 query. In some cases, the assertion value may change during 942 subsequent query-processing steps. 944 * Determine the matching filter. Each resource-type has its 945 own matching filter rules. For example, contact entries are 946 matched with a simple equalityMatch comparison, while in 947 other cases the matching filter will be an extensibleMatch 948 which is peculiar to the resource-type in use. 950 Once all of the pre-processing steps have been successfully 951 completed, the client will have to locate an LDAPv3 server which 952 is authoritative for the search base before it can submit the 953 query. This process is described in section 5.2 below. 955 5.2. Query Bootstrap Models 957 Once a client has determined which partition should be queried for 958 the specified resource, the client will need to determine which 959 LDAP servers are authoritative for that partition. 961 The FIRS service supports three different bootstrap models for 962 this process, although these models only differ in relatively 963 minor ways; once a server has been located, the rest of the query 964 process follows the same basic path (issuing the LDAPv3 query, 965 following referrals, and so forth). 967 The three bootstrapping models defined for use with this service 968 are the "targeted" model which is functionally identical to 969 traditional lookups for LDAP servers, the "top-down" model which 970 causes a client to submit a query to the root of a delegation 971 hierarchy, and a "bottom-up" model which causes a client to work 972 up through a delegation hierarchy until a server has been located. 974 5.2.1. Targeted query processing 976 The "targeted" model is similar to the traditional model of LDAP 977 lookups, in that a client queries a specified LDAP server for a 978 particular resource under the assumption that the named resource 979 exists on the named server. If the known resource or the known 980 server do not exist or cannot be located (notwithstanding any 981 referrals which may be returned), then the query process exits. 983 The targeted model can be used when an application-specific 984 partition or resource has been specified, but can also be used if 985 the client prefers to use a "default" server for all operations. 986 The latter may occur when clients use proxy servers, caching 987 servers, or other fixed servers, in lieu of navigating the global 988 directory database with every query. 990 The targeted model is primarily suited for locating Internet 991 resources which are managed and delegated by a central body, but 992 which is not necessarily located in a directory partition under a 993 top-level domain. For example, AS numbers, IPv4 address blocks, 994 and IPv6 address blocks are all managed under specific partitions 995 which are not directly linked to a specific top-level domain, so 996 those queries have to be started at specific partitions, and would 997 not be efficiently served by partitions higher or lower in the 998 delegation hierarchy. 1000 The steps for processing targeted queries are described below: 1002 a. Determine the IP address and port number to be used (this 1003 information may be determined from user input, a 1004 configuration file, a URL, or from any other source). 1006 1. If a non-ASCII domain name has been specified for this 1007 purpose, convert the domain name into its ASCII- 1008 compatible form using the "ToASCII" process defined in 1009 [RFC3490] before performing any lookups. 1011 2. Locate the LDAP servers associated with the domain 1012 name through the SRV query steps provided in section 1013 5.2.4. If this step fails, use DNS lookups for A 1014 resource records instead. If no resource records are 1015 available, report the error to the user and exit. 1017 b. Once a server has been determined, submit the search 1018 operation. If the search operation fails, report the error 1019 to the user and exit. Otherwise, display any answer data 1020 which is returned. 1022 c. If the answer data contains a subordinate reference 1023 referral or a continuation reference referral, new query 1024 processes MUST be spawned. 1026 For subordinate reference referrals, process the URLs 1027 according to the rules described in section 5.4 and restart 1028 the query process at step 5.2.1.a. For each continuation 1029 reference referral, display the answer data received so 1030 far, process the LDAP URLs according to the rules described 1031 in section 5.4 and start new query processes for each 1032 referral at step 5.2.1.a, appending the output from these 1033 searches to the current output. 1035 Any additional subordinate reference referrals or 1036 continuation reference referrals which are encountered from 1037 any subsequent searches will need to be processed in the 1038 same manner as specified above, until no additional 1039 referrals are received. 1041 d. Exit the query operation. 1043 5.2.2. Top-down processing 1045 The top-down model uses an input string to construct an LDAP 1046 assertion value and search base, with DNS queries being used to 1047 locate the LDAP servers associated with the appropriate top-level 1048 delegation entity. Once this process completes, a query is issued 1049 to the specified servers. This query may be subsequently 1050 redirected to other servers through the use of LDAP referrals. 1052 The top-down model is primarily suited for locating Internet 1053 resources which are centrally managed and delegated, and where 1054 information about the delegation is available from a delegation 1055 body with a top-level domain. The best example of this is 1056 resources under the top-level domains themselves, such as queries 1057 for domain delegations under the "com" zone. 1059 Note that the top-down model does not use incrementally larger 1060 domain names for the bootstrap process. Instead, it is assumed 1061 that the root partition in the delegation tree will be able to 1062 provide any necessary redirection services. For example, if the 1063 domain name of "www.example.co.uk" is used in a query, the query 1064 will be sent to the "dc=uk" partition, which should provide a 1065 referral for the "dc=co,dc=uk" partition, which in turn should 1066 provide a referral for the "dc=example,dc=co,dc=uk" partition. 1068 The steps for processing top-down queries are described below: 1070 a. Determine the directory partition for the query. 1072 1. Separate the input string into discrete elements where 1073 this is possible. For a DNS domain name of 1074 "www.example.com", this would be "www", "example" and 1075 "com". For the IPv4 network number of "192.0.2.14", 1076 this would be "192", "0", "2" and "14". AS numbers 1077 only have a single value and require no separation. Do 1078 not discard the original query string. 1080 2. IP addresses and AS numbers require additional 1081 conversion. For IPv4 addresses, strip off the prefix 1082 and convert the input string into a reverse-lookup DNS 1083 domain name by reversing the order of the octets and 1084 appending "in-addr.arpa" to the right of the domain 1085 name. For IPv6 addresses, strip off the prefix and 1086 reverse the nibble order of the address (where each 1087 nibble is represented by a single hexadecimal 1088 character), and append "ip6.arpa". For AS numbers, 1089 append only the "arpa" domain name. 1091 b. Form the LDAP search base for the query. 1093 1. If the client application allows non-ASCII input, 1094 convert the domain name formed in step 5.2.2.a above 1095 into its ASCII-compatible form using the "ToASCII" 1096 process defined in RFC 3490. 1098 2. Convert the right-most element from the domain name 1099 formed in step 5.2.2.b.1 into a domainComponent DN 1100 (such as "dc=com" or "dc=arpa"). This represents the 1101 directory partition for the current query. 1103 3. Append "cn=inetResources" to the front of the 1104 domainComponent syntax ("cn=inetResources,dc=com"). 1105 This will form the fully-qualified search base for the 1106 LDAP query. 1108 c. Locate the LDAP servers associated with the resource by 1109 processing the domain name formed in step 5.2.2.a above 1110 through the SRV query steps provided in section 5.2.4. 1112 d. If the SRV lookup succeeds: 1114 1. Choose the best LDAP server, using the weighting 1115 formula described in RFC 2782 [RFC2782]. 1117 2. Formulate the LDAP search using the search base and 1118 search filter constructed earlier. For example, if the 1119 input query string was for "www.example.com", then the 1120 client would begin the process by submitting an 1121 inetDnsDomainMatch extensibleMatch search with the 1122 assertion value of "www.example.com", and with a 1123 search base of "dc=inetResources,dc=com". Similarly, 1124 if the input query string was "192.0.2.14", then the 1125 client would begin the process by submitting an 1126 inetIpv4NetworkMatch extensibleMatch search with the 1127 assertion value of "192.0.2.14/32", and with the 1128 search base of "cn=inetResources,dc=arpa". 1130 3. Submit the search operation to the chosen server and 1131 port number. If the operation fails, report the 1132 failure to the user and exit. Otherwise, display any 1133 answer data which is returned. 1135 4. If the answer data contains a subordinate reference 1136 referral or a continuation reference referral, new 1137 query processes MUST be spawned. 1139 For subordinate reference referrals, process the URLs 1140 according to the rules described in section 5.4 and 1141 restart the query process at step 5.2.2.b. For each 1142 continuation reference referral, display the answer 1143 data received so far, process the LDAP URLs according 1144 to the rules described in section 5.4 and start new 1145 query processes for each referral at step 5.2.2.b, 1146 appending the output from these searches to the 1147 current output. 1149 Any additional subordinate reference referrals or 1150 continuation reference referrals which are encountered 1151 from any subsequent searches will need to be processed 1152 in the same manner as specified above, until no 1153 additional referrals are received. 1155 e. If the SRV lookup fails (where failure is defined as any 1156 DNS response message other than an answer), report the 1157 failure to the user and exit the current search operation. 1159 f. Exit the query operation. 1161 5.2.3. Bottom-up processing 1163 The bottom-up model uses an input string to construct an LDAP 1164 assertion value and search base, with DNS queries being used to 1165 locate the LDAP servers which are associated with the management 1166 entity that is directly responsible for the resource in question. 1167 If no servers are available for that partition, the parent 1168 partition in the delegation hierarchy is used instead, with this 1169 process repeating until a server has been located. 1171 The bottom-up model is best used when a leaf-node partition needs 1172 to be queried directly, either because there is no direct 1173 delegation path for the resource in question, or because the user- 1174 managed partition is preferable to the centralized delegation 1175 information. For example, there is no global delegation body which 1176 assigns and manages contact identifiers, so these identifiers need 1177 to be directed towards the leaf-node partitions directly. The 1178 bottom-up model can also be used for other kinds of resources if 1179 desirable, although in most cases the bottom-down model will be 1180 more useful for those resources. 1182 The steps for processing bottom-up queries are described below: 1184 a. Determine the input type (DNS Domain, IPv4 Address, etc.) 1186 b. Determine the authoritative DNS domain for the resource. 1188 1. Separate the input string into discrete elements where 1189 this is possible. For a DNS domain name of 1190 "www.example.com", this would be "www", "example" and 1191 "com". For the IPv4 network number of "192.0.2.14", 1192 this would be "192", "0", "2" and "14". Do not discard 1193 the original query string. 1195 2. IP addresses require additional conversion. For IPv4 1196 addresses, strip off the prefix and convert the input 1197 string into a reverse-lookup DNS domain name by 1198 reversing the order of the octets and appending 1199 "in-addr.arpa" to the right of the resulting sequence. 1200 For IPv6 addresses, strip off the prefix and reverse 1201 the nibble order of the address (where each nibble is 1202 represented by a single hexadecimal character), and 1203 append "ip6.arpa" to the right of the resulting 1204 sequence. 1206 c. Form the LDAP search base for the query. 1208 1. If the client application allows non-ASCII input, 1209 convert the domain name formed in step 5.2.3.b above 1210 into its ASCII-compatible form using the "ToASCII" 1211 process defined in RFC 3490. 1213 2. Convert the domain name formed in step 5.2.3.c.1 above 1214 into a domainComponent DN (such as 1215 "dc=www,dc=example,dc=com" or "dc=0,dc=2,dc=0,dc=192, 1216 dc=in-addr,dc=arpa"). This represents the directory 1217 partition for the current query. 1219 3. Append the "cn=inetResources" RDN to the left of the 1220 domainComponent syntax (perhaps resulting in 1221 "cn=inetResources,dc=www,dc=example,dc=com"). This 1222 will become the search base for the LDAP query. 1224 d. Locate the LDAP servers associated with the resource by 1225 processing the domain name formed in step 5.2.3.b above 1226 through the SRV query steps provided in section 5.2.4. 1228 e. If the SRV lookup fails with an NXDOMAIN response code (as 1229 described in RFC 2308 [RFC2308]), then the domain name used 1230 for the SRV lookup does not exist, and a substitute LDAP 1231 server and search base must be used instead. This process 1232 involves determining the parent zone for the domain name in 1233 question, issuing an SRV lookup for that zone, and using 1234 the domain name of the zone as the new LDAP search base, 1235 with this process repeating until a search base can be 1236 located, or until a critical failure forces an exit. 1238 1. Remove the left-most label from the domain name formed 1239 in step 5.2.3.b. 1241 2. If this process has already resulted in a query domain 1242 name at a top-level domain such as "com" or "arpa", 1243 convert the query domain name to "." (to signify the 1244 root domain). 1246 3. If the queried domain name is already set to ".", the 1247 query can go no higher (this most likely indicates a 1248 malformed DNS configuration, a connectivity problem, 1249 or a typo in the query). Exit and report the failure 1250 to the user. 1252 4. Restart the process at step 5.2.2.b, using the domain 1253 name formed above. Repeat until a server is located or 1254 a critical failure forces an exit. 1256 For example, if the original input string of 1257 "www.example.com" resulted in a failed SRV lookup for 1258 "_ldap._tcp.www.example.com", then the first fallback 1259 SRV query would be for "_ldap._tcp.example.com", and 1260 the next fallback query would be for "_ldap._tcp.com", 1261 possibly being followed by "_ldap._tcp.", and possibly 1262 resulting in failure after that. 1264 f. If the SRV lookup succeeds: 1266 1. Choose the best LDAP server, using the weighting 1267 formula described in [RFC2782]. 1269 2. Formulate the LDAP search using the search base and 1270 search filter constructed above. For example, if the 1271 input query string was for "www.example.com", then the 1272 client would begin the process by submitting an 1273 inetDnsDomainMatch extensibleMatch search with the 1274 assertion value of "www.example.com", with the search 1275 base of "cn=inetResources,dc=www,dc=example,dc=com". 1276 If the SRV lookups had failed (resulting in "com" 1277 being used as the authoritative directory partition), 1278 then the search base for the query would also be 1279 trimmed accordingly ("cn=inetResources,dc=com"). 1281 3. Submit the search operation to the chosen server and 1282 port number. If the operation fails, report the 1283 failure to the user and exit. Otherwise, display any 1284 answer data which is returned. 1286 4. If the answer data contains a subordinate reference 1287 referral or a continuation reference referral, new 1288 query processes MUST be spawned. 1290 For subordinate reference referrals, process the URLs 1291 according to the rules described in section 5.4 and 1292 restart the query process at step 5.2.3.d. For each 1293 continuation reference referral, display the answer 1294 data received so far, process the LDAP URLs according 1295 to the rules described in section 5.4 and start new 1296 query processes for each referral at step 5.2.3.d, 1297 appending the output from these searches to the 1298 current output. 1300 Any additional subordinate reference referrals or 1301 continuation reference referrals which are encountered 1302 from any subsequent queries will need to be processed 1303 in the same manner as specified above, until no 1304 additional referrals are received. 1306 g. If a fatal DNS error condition occurs, report the error to 1307 the user and stop processing the current query. A fatal DNS 1308 error is any response message with an RCODE of FORMERR, 1309 SERVFAIL, NOTIMPL, or REFUSED, or where a query results in 1310 NODATA (implying that an "_ldap._tcp" domain name exists 1311 but it doesn't have an SRV resource record associated with 1312 it, which is most likely a configuration error). 1314 h. Exit the query operation. 1316 5.2.4. SRV processing 1318 The bootstrapping models described in this document make use of 1319 DNS SRV resource records to locate the LDAP servers associated 1320 with the resource provided in the query input. 1322 The procedure for constructing this SRV lookup is as follows: 1324 a. Construct an SRV-specific label pair for the service type. 1325 For LDAP queries, this will be "_ldap._tcp". 1327 b. If the client allows non-ASCII characters to be input, then 1328 convert the domain name input into its ASCII-compatible 1329 form by using the "ToASCII" process described in [RFC3490]. 1331 c. Append the SRV label pair to the left of the input domain 1332 name from step 5.2.4.b. In the case of a query for the 1333 "example.com" domain, this would result in an SRV-specific 1334 domain name of "_ldap._tcp.example.com". 1336 d. Issue a DNS query for the SRV resource records associated 1337 with the domain name formed in step 5.2.4.b. 1339 Multiple SRV resource records may be returned in response to a 1340 query. Each resource record identifies a different connection 1341 target, including the domain name of a server, and a port number 1342 for that server. The port number specified in a SRV resource 1343 record MUST be used for any subsequent bind and search operations. 1345 SRV resource records provide "priority" and "weight" values which 1346 MUST be used to determine the preferred server. If a server is 1347 unavailable or unreachable, a connection attempt must be made to 1348 the next-best server in the answer set. 1350 Refer to [RFC2782] for a detailed explanation of SRV resource 1351 records and their handling. 1353 If a preferred connection target is listed with multiple IP 1354 addresses, clients should cycle through the IP addresses before 1355 using the next-preferred connection target. 1357 5.3. Query Processing 1359 Once an authoritative server for the partition in question has 1360 been located, the LDAP query can be submitted. In order to ensure 1361 interoperability, this specification defines several behavioral 1362 rules which clients and servers SHOULD conform with. These 1363 guidelines are discussed in the following sections. 1365 5.3.1. The inetResourcesControl server control 1367 The inetResourcesControl server control is the master control 1368 object for the FIRS service, and provides the version of each 1369 object class that is available for use on the current server, and 1370 also lists the matching filters that the server is willing to use 1371 for each of the listed object classes. 1373 The OID for inetResourcesControl is 1.3.6.1.4.1.7161.1.0.0. This 1374 value MUST be provided in the OID field of the control. 1376 The value section of the inetResourcesControl contains nested 1377 sequences of data. The first element in each sequence identifies 1378 an object class, while first nested element identifies a matching 1379 filter which may be used for that object class, while the next set 1380 of nested elements identify the attributes that may be used with 1381 each matching filter. 1383 The structure of the value section of inetResourcesControl is 1384 illustrated by the following ASN.1 definition: 1386 inetResourcesControlValue ::= SEQUENCE { 1387 objectClass LDAPOID, 1388 matchingFilters SEQUENCE OF matchingFilter, 1389 attributes SEQUENCE OF attribute } 1391 matchingFilter ::= LDAPSTRING 1393 attribute ::= LDAPOID 1395 Each object class, matching filter, and attribute MUST be 1396 presented as a string. Object classes MUST be listed as OIDs so 1397 that clients can determine the supported object classes according 1398 to their version. Matching filters MUST also be provided as OIDs, 1399 except for the "stock" matching filter operators defined in 1400 [RFC2251], which MUST be presented with the textual identifiers 1401 shown therein. Attributes MUST be listed with their textual 1402 identifiers. 1404 At a minimum, servers MUST support the equalityMatch and 1405 extensibleMatch filters from [RFC2251] for every object class 1406 listed, and SHOULD always declare these filters. Furthermore, 1407 servers MUST support the "cn" attribute for every matching filter, 1408 and SHOULD declare these attributes. The Asterisk character ("*") 1409 MAY be provided as a wildcard to indicate that the server will 1410 accept any matching filter for the associated object class, or to 1411 indicate that the server will accept any attribute for the 1412 associated matching filter. Servers MUST allow any supported 1413 matching filter to be used as part of an extensibleMatch 1414 operation, and clients MAY assume that any allowed operation will 1415 be acceptable as part of an extensibleMatch. 1417 An example of an inetResourcesControl server control is shown 1418 below for illustration purposes: 1420 { 1.3.6.1.4.1.7161.1.0.0, FALSE, { 1421 1.3.6.1.4.1.7161.1.1.1 { 1422 equalityMatch {*}, 1423 extensibleMatch {*} } }, { 1424 1.3.6.1.4.1.7161.1.3.1 { 1425 1.3.6.1.4.1.7161.1.3.0.1 {*}, 1426 equalityMatch {*}, 1427 substringMatch {cn}, 1428 extensibleMatch {*} } } } 1430 Figure 3: An example inetResourcesControl server control. 1432 In the example shown in Figure 3, the inetResourcesControl type is 1433 identified by the OID of 1.3.6.1.4.1.7161.1.0.0, while the 1434 criticality field is set to FALSE, as per the requirements in 1435 [RFC2251]. The contents of the control value identify the current 1436 OID for the inetResources object class along with the [RFC2251] 1437 textual identifiers of the equalityMatch and extensibleMatch 1438 operators, each of which will accept any attributes. Figure 3 also 1439 identifies the OID for the inetDnsDomain object class along with 1440 the OID for the inetDnsDomainMatch and the [RFC2251] textual 1441 identifiers for the equalityMatch, substringMatch and 1442 extensibleMatch operators, although the substringMatch filter is 1443 only advertised for use with the "cn" attribute. 1445 FIRS-compliant servers SHOULD return the inetResourcesControl 1446 server control as an unsolicited response to a successful bind 1447 request. Clients MUST use the OID of the inetResourcesControl for 1448 the purpose of validating the contents of the control, and MUST 1449 use the OIDs of the listed object classes to discover schema 1450 versioning information. 1452 Servers MAY restrict the contents of the inetResourcesControl 1453 value according to the authenticated identity of the client. For 1454 example, servers can choose to enable computationally-intense 1455 searches for authorized users while refusing to provide the same 1456 searches for anonymous users. 1458 If a client does not receive a usable inetResourcesControl control 1459 as part of the bind response, the client SHOULD issue a request 1460 for the control before proceeding. If a client is still unable to 1461 obtain a usable inetResourcesControl server control, the client 1462 MAY choose a different server for the partition, or MAY choose to 1463 assume that the equalityMatch matching filter will be supported 1464 for any of the known types, or MAY choose to undergo any other 1465 recovery efforts. In any event, clients SHOULD NOT use the absence 1466 or contents of the control to completely abort query processing 1467 unless all of the servers for a partition have refused to provide 1468 service to the client. 1470 For example, if the server advertises support for the 1471 inetDnsDomain object class but does not advertise support for the 1472 inetDnsDomainMatch matching filter, the client MAY issue discrete 1473 equality searches for each of the specific domain name resources 1474 (note that this kind of query can fail to produce referrals in 1475 some cases, but will usually produce at least some answers). 1477 In all cases, if any given server advertises support for a 1478 particular object class or matching filter, the client MUST make 1479 use of the server-provided service. 1481 5.3.2. Matching filters 1483 LDAP search filters are fairly flexible, in that they allow for a 1484 wide variety of configurable elements, such as the maximum number 1485 of entries which are returned, the type of comparison operation 1486 that needs to be performed, and other details. In order to ensure 1487 interoperability, default values are defined here for many of 1488 these elements. 1490 [RFC2251] defines the LDAP search request specification, although 1491 it does not provide guidelines or recommended values for the 1492 filter settings. In an effort to promote interoperability among 1493 FIRS clients and servers, this document defines some recommended 1494 and mandatory values for searches within the FIRS service. 1496 NOTE: These rules ONLY apply to the FIRS search operations 1497 in particular. Any queries for other resources SHOULD NOT 1498 impose these restrictions. Also note that other documents 1499 which define additional resource types can also define 1500 different restrictions, and those definitions will take 1501 precedence over the global defaults. 1503 Servers MUST be prepared to enforce these rules independently of 1504 the client settings, and clients MUST be prepared to receive 1505 truncated search results accordingly. 1507 The default values of an LDAPv3 search filter in FIRS are: 1509 * Search base. The directory partition to be used in a search 1510 will vary for each query operation. The methodology for 1511 determining the current search base for a query is defined 1512 by the query-processing protocols described in section 5.1, 1513 although FIRS searches are normally constrained to the 1514 "cn=inetResources" container of a particular directory 1515 partition. 1517 * Scope. In order to successfully locate referral stub child 1518 entries, clients MUST use a sub-tree scope for FIRS 1519 searches. Servers MUST NOT arbitrarily limit the scope of 1520 search operations. 1522 * Dereference aliases. Although the FIRS service does not 1523 make direct use of alias entries, they are not prohibited. 1524 Clients SHOULD set the Dereference Aliases option to 1525 "Always" for FIRS searches. Servers SHOULD dereference any 1526 aliases which are encountered, where this is feasible (in 1527 particular, where the alias refers to another directory 1528 partition on the same server). 1530 * Size limit. The size limit field specifies the maximum 1531 number of entries that a server should return. For the FIRS 1532 service, this setting SHOULD be set to a value between 25 1533 and 100. This range ensures that the client is capable of 1534 receiving a sufficient number of entries and continuation 1535 references in a single response, but also works to prevent 1536 runaway queries that match everything (such as searches for 1537 "com", which can match every inetDnsDomain entry in the 1538 "cn=inetResources,dc=com" container). Servers MAY truncate 1539 answer sets if the client specifies a larger value. 1541 * Time limit. The time limit field specifies the maximum 1542 number of seconds that a server should process the search. 1543 For the FIRS service, this setting SHOULD be set to a value 1544 between 10 and 60 seconds. This range ensures that the 1545 server is able to process a sufficient number of entries, 1546 but also works to prevent runaway queries that match 1547 everything. Servers MAY stop processing queries after the 1548 time limit if the client specifies a larger value. 1550 * Types-only. The types-only setting is a Boolean flag which 1551 controls whether or not attribute values are returned in 1552 the answer sets. Since excessive queries are likely to be 1553 more burdensome than larger answer sets, this setting 1554 SHOULD be set to FALSE. Resource-constrained clients (such 1555 as PDAs) MAY set this value to TRUE, but these clients MUST 1556 be prepared to issue the necessary subsequent queries. 1558 * Filter. The search operation will depend on the type of 1559 data being queried. For FIRS queries, the filter MUST use 1560 the matching rules defined for the relevant resource type. 1562 * Attribute list. Clients MAY restrict the list of attributes 1563 which are returned in searches, but are discouraged from 1564 doing so without cause. 1566 5.3.3. Query-volume restrictions 1568 The restrictions listed in section 5.3.2 represent suggested 1569 defaults, although server operators MAY impose any kinds of usage 1570 limits they deem necessary or desirable. 1572 Specifically, server operators MAY restrict the amount of 1573 information provided to specific clients and/or users over a given 1574 amount of time, within reason. For example, servers MAY restrict 1575 clients to an arbitrary number of queries per-hour or per-day, or 1576 may impose mandatory time intervals between queries, and so forth. 1577 Similarly, servers MAY restrict clients to an arbitrary number of 1578 answers over a given time period, such as limiting clients to 100 1579 answers regardless of the number of queries which were used to 1580 generate those answers. 1582 Servers which refuse to process a query due to volume policy 1583 SHOULD use the "unwillingToPerform" response code ("53") to inform 1584 the client of these restrictions, and SHOULD provide explanatory 1585 text in the error message. These errors SHOULD be generated when 1586 the session is first established, if at all possible. 1588 In the worst cases, servers MAY deny all service to abusive 1589 clients. This can be implemented by rejecting the TCP connection 1590 outright, or by providing an explanatory error early in the 1591 session, or at any other point. 1593 Clients MUST be prepared for connection requests and queries to be 1594 denied for any reason, and MUST treat these conditions as non- 1595 permanent failures. Clients MAY retry the operations if a known 1596 error condition is corrected (such as authentication errors), but 1597 SHOULD NOT automatically generate retry attempts. 1599 5.3.4. Authentication restrictions 1601 Servers operators SHOULD allow anonymous authentication for read- 1602 only access to public delegation data. Clients SHOULD use 1603 anonymous authentication by default. 1605 Wherever a server operator requires or desires clients to 1606 authenticate for access, servers MUST support the simple 1607 authentication mechanism defined in RFC 2222 [RFC2222], although 1608 server operators MAY require the use of any authentication 1609 mechanisms in addition to or instead of the simple mechanism. 1611 Server operators MAY define any access controls on the data, as 1612 necessary for policy considerations. Server operators SHOULD NOT 1613 impose unreasonable requirements for proprietary authentication 1614 mechanisms for routine purposes. 1616 Server operators MAY withhold privileged information from non- 1617 privileged clients or users, as necessary. 1619 Clients MUST NOT equate the absence of any attributes with the 1620 absence of data, and SHOULD assume that the authenticated user is 1621 not authorized to view any data which has not been provided. 1623 If a client specifically requests an entry or an attribute which 1624 the server is unwilling to provide due to ACL settings, the server 1625 MUST use the appropriate LDAPv3 error message. For example, if the 1626 user is unable to view an entry or a requested attribute because 1627 it has not yet provided sufficient authentication credentials, the 1628 server MUST return the "invalidCredentials" error. Similarly, if 1629 the client has requested an entry or attribute which the server is 1630 unwilling to provide due to policy reasons, the server MUST return 1631 the unwillingToPerform error to the client. 1633 See section 5.3.5 for mechanisms that can be used to determine 1634 and/or describe usage restrictions on specific attribute values. 1636 5.3.5. Extended attribute ACLs 1638 In normal operations, attributes and values that the client is not 1639 authorized to view would not be returned in response to queries 1640 for that data, with the client equating a lack of data in a 1641 particular attribute with "no data that you are authorized to 1642 view". However, [CRISP-REQ] defines additional response types for 1643 conveying explicit restrictions on data (such as reporting that 1644 the data is restricted due to privacy considerations), and which 1645 requires more comprehensive reporting than simply omitting data 1646 that the user is not authorized to view. 1648 This extended data is provided through the use of LDAP attribute 1649 options, as described in section 4.1.5 of [RFC2251] (this is the 1650 same mechanism as used with language tags), using "inetExtAcl-" as 1651 the option prefix. 1653 The current-valid list of attribute options are: 1655 * InetExtAcl-S0 -- Security Restricted. Some attribute values 1656 have not been returned due to security requirements which 1657 have not been met. 1659 * InetExtAcl-P0 -- Privacy Restricted. Some attribute values 1660 have not been returned due to privacy requirements which 1661 have not been met. 1663 * InetExtAcl-S1 -- Security Cleared. The security 1664 requirements on the associated attribute values have been 1665 met and the user has been granted access to the data. 1667 * InetExtAcl-P1 -- Privacy Cleared. The privacy requirements 1668 on the associated attribute values have been met and the 1669 user has been granted access to the data. 1671 * InetExtAcl-R0 -- Do Not Distribute. The associated 1672 attribute values are not to be reused outside this session. 1674 Each attribute instance MUST have one of the above attribute 1675 options, but MUST NOT have more than one option. Multiple 1676 instances of the attribute option MAY be assigned to an attribute, 1677 although the instances SHOULD NOT have conflicting meanings. 1679 As a simple example, "mail;inetExtAcl-S1:admins@example.com" would 1680 indicate that this instance of the "mail" attribute had an ACL 1681 protecting it from normal use, but that the user was authorized to 1682 view the attribute data. Meanwhile, the attribute instance of 1683 "mail;inetExtAcl-S1;inetExt-R0:admins@example.com" would indicate 1684 that the user had been granted access to the data, but that the 1685 user must not distribute the data. 1687 Multiple and varying instances of an attribute can co-exist in an 1688 entry simultaneously if necessary. For example, the following 1689 entries can all co-exist within a single entry. 1691 mail:admins@example.com 1692 mail;inetExtAcl-S1:postmaster@example.com 1693 mail;inetExtAcl-P1:jack@example.com 1694 mail;inetExtAcl-P1:inetExtAcl-R0:jill@example.com 1696 In that example, searches for the "mail" attribute would produce 1697 the public information, while searches for the other attribute 1698 instances would produce the alternate data. 1700 Each instance of an attribute can have its own ACLs in the 1701 directory, thereby allowing specific instances of an attribute to 1702 be restricted to certain users. For example, ACLs on the 1703 inetExtAcl-S1 instance of an attribute can be defined so that the 1704 entry owner can view the data, while the inetExtAcl-S0 instance 1705 can be set such that help-desk operators are able to see that 1706 there are hidden attribute values (but without exposing the values 1707 to those users), but with both instances being hidden from 1708 anonymous users so that the general public does not know that 1709 there are any extended attribute options. 1711 Each instance of the attributes can be requested through normal 1712 query processes, although the inetExtAcl-S0 and inetExtAcl-P0 1713 attributes will always be empty (the presence of the attribute 1714 option implies that the related data could not be returned), and 1715 thus those instances will never be returned. 1717 In order to simplify these requests and responses, an 1718 inetExtAclControl client control is provided that specifically 1719 allows for the request of all extended ACL attribute options. The 1720 OID for the inetExtAclControl control is 1.3.6.1.4.1.7161.1.0.1. 1721 Clients MUST provide this control as part of the search request, 1722 and servers which support this control MUST return all of the 1723 regular and extended ACL attributes that are defined for an entry 1724 (according to the ACLs appropriate for the current user). 1726 5.3.6. Protocol and schema version controls 1728 The FIRS collection of specifications are explicitly bound to the 1729 LDAPv3 protocol, as defined by [RFC3377] and its subordinate 1730 specifications. If a new version of the LDAP protocol emerges, it 1731 is expected that some type of mechanism will be included for end- 1732 points to use when negotiating over the version in use. Lacking 1733 such a mechanism, FIRS is explicitly restricted to LDAPv3. 1735 LDAP attributes, object classes, syntaxes and matching filters 1736 have OIDs which uniquely identify the format of the data they 1737 provide, and which act as simple schema-version identifiers in the 1738 generic case. [RFC2251] defines standardized mechanisms for 1739 retrieving and reading the OIDs associated with object classes and 1740 attributes (among other resource types). These mechanisms MAY be 1741 used whenever a FIRS client reads an entry, and MUST be used 1742 whenever a FIRS client modifies or creates an entry (even though 1743 FIRS does not define mechanisms for updating entries, it is 1744 assumed that some clients will allow this behavior). 1746 The inetResourcesControl server control described in section 5.3.1 1747 provides a mechanism that clients can use to determine the version 1748 of an object class or matching filter that the server supports. 1750 Any modifications to any existing schema definitions MUST be 1751 accompanied by new OID assignments for the affected elements. 1753 5.4. Referral Processing 1755 As was discussed in section 3.5, FIRS supports two types of LDAP 1756 referrals, which are subordinate reference referrals and 1757 continuation reference referrals. Both referral types use URLs for 1758 the purpose of providing referral targets, using the rules 1759 described in section 3.5 of this document. 1761 Non-compliance with the URL formatting requirements provided in 1762 section 3.5.2 amounts to an error, and is sufficient cause for a 1763 client to stop processing a query. 1765 The procedure for processing referral URLs is as follows: 1767 a. [RFC2251] allows multiple URLs to be provided, although the 1768 URLs are not provided with any "preference" or "weighting" 1769 values. If a set of URLs are provided, only one of the URLs 1770 need to be tried (implementations MAY perform additional 1771 queries in an attempt to recover from temporary failures, 1772 although this is not required). Select one of the URLs at 1773 random ("round-robin"), and continue to the next step in 1774 the process. 1776 b. Locate the LDAP URLs in the referral data, and discard any 1777 URLs which use any other service types. FIRS clients MUST 1778 support LDAP URLs. URLs with other service type identifiers 1779 SHOULD be ignored. 1781 c. Extract any port number which may have been provided with 1782 the URL, and set it aside for possible use with the 1783 subsequent connection attempt. Use the port number 1784 discovered through any subsequent SRV lookups (as described 1785 below), or as a last resort use the default port number 1786 associated with the protocol identifier. 1788 d. Determine the authoritative partition and search base 1789 specified in the referral URL. 1791 1. If no distinguished name element was provided, 1792 determine the authoritative partition and search base 1793 from the provided assertion value, according to the 1794 procedures for the bootstrap model that is most 1795 relevant to the resource-type. 1797 2. Otherwise, use the distinguished name element for the 1798 search base of the subsequent search operation. 1800 3. Extract the sequence of domainComponent distinguished 1801 names from the search base, and use them as the 1802 authoritative partition. 1804 e. Determine the server address and port number specified in 1805 the referral URL. 1807 1. If a host identifier was not provided, map the 1808 domainComponent elements determined in step 5.4.d to a 1809 DNS domain name and submit a DNS lookup for the SRV 1810 resource records associated with that domain name. If 1811 this step fails, report the error to the user and exit 1812 the query. 1814 2. If the host identifier is an IP address, extract it 1815 and skip to step 5.4.f. 1817 3. If no port number was provided in the URL, submit a 1818 DNS lookup for the SRV resource records associated 1819 with the domain name, as described in section 5.2.4. 1820 If this lookup succeeds, skip to step 5.4.f. 1822 4. If the SRV lookup from the previous step fails, or if 1823 no port number was specified, submit a DNS lookup for 1824 the A resource records. 1826 f. Determine the new assertion value and/or matching filter 1827 specified in the referral URL. 1829 1. If the URL's path element does not contain a filter 1830 element, reuse the current matching filter and 1831 assertion value. 1833 2. If the URL's path element contains a filter element, 1834 use it to form the new matching filter and/or 1835 assertion value. 1837 g. Discard the remainder of the URL. 1839 h. Use the discovered parameter values to start a new query. 1841 Note that step 5.4.g requires the client to discard the remainder 1842 of the URL, although this step may be changed in subsequent 1843 versions of this specification. In particular, [CRISP-REQ] 1844 requires the ability to pass an inter-server "referral bag", and 1845 this mechanism may be implemented through the use of extensions in 1846 the LDAP URL. 1848 6. Security Considerations 1850 Security considerations are discussed in [FIRS-ARCH]. 1852 7. IANA Considerations 1854 IANA considerations are discussed in [FIRS-ARCH]. 1856 8. Normative References 1858 [RFC1274] Barker, P., and Kille, S. "The COSINE and 1859 Internet X.500 Schema", RFC 1274, November 1860 1991. 1862 [RFC2079] Smith, M. "Definition of an X.500 Attribute 1863 Type and an Object Class to Hold Uniform 1864 Resource Identifiers (URIs)", RFC 2079, 1865 January 1997. 1867 [RFC2222] Myers, J. "Simple Authentication and Security 1868 Layer (SASL)", RFC 2222, October 1997. 1870 [RFC2247] Kille, S., Wahl, M., Grimstad, A., Huber, R., 1871 and Sataluri, S. "Using Domains in LDAP/X.500 1872 DNs", RFC 2247, January 1998. 1874 [RFC2251] Wahl, M., Howes, T., and Kille, S. 1875 "Lightweight Directory Access Protocol (v3)", 1876 RFC 2251, December 1997. 1878 [RFC2252] Wahl, M., Coulbeck, A., Howes, T., and Kille, 1879 S. "Lightweight Directory Access Protocol 1880 (v3): Attribute Syntax Definitions", RFC 2252, 1881 December 1997. 1883 [RFC2253] Wahl, M., Kille, S., and Howes, T. 1884 "Lightweight Directory Access Protocol (v3): 1885 UTF-8 String Representation of DNs", RFC 2253, 1886 December 1997. 1888 [RFC2254] Howes, T. "The String Representation of LDAP 1889 Search Filters", RFC 2254, December 1997. 1891 [RFC2255] Howes, T., and Smith, M. "The LDAP URL 1892 Format", RFC 2255, December 1997. 1894 [RFC2256] Wahl, M. "A Summary of the X.500(96) User 1895 Schema for use with LDAPv3", RFC 2256, 1896 December 1997. 1898 [RFC2277] Alvestrand, H. "IETF Policy on Character Sets 1899 and Languages", BCP 18, RFC 2277, January 1900 1998. 1902 [RFC2308] Andrews, M. "Negative Caching of DNS Queries 1903 (DNS NCACHE)", RFC 2308, March 1998. 1905 [RFC2596] Wahl, M., and Howes, T. "Use of Language Codes 1906 in LDAP", RFC 2596, May 1999. 1908 [RFC2782] Gulbrandsen, A., Vixie, P., and Esibov, L. "A 1909 DNS RR for specifying the location of services 1910 (DNS SRV)", RFC 2782, February 2000. 1912 [RFC2798] Smith, M. "Definition of the inetOrgPerson 1913 LDAP Object Class", RFC 2798, April 2000. 1915 [RFC3296] Zeilenga, K. "Named Subordinate References in 1916 Lightweight Directory Access Protocol (LDAP) 1917 Directories", RFC 3296, July 2002. 1919 [RFC3377] Hodges, J., and Morgan, R. "Lightweight 1920 Directory Access Protocol (v3): Technical 1921 Specification", RFC 3377, September 2002. 1923 [RFC3490] Falstrom, P., Hoffman, P., and Costello, A. 1924 "Internationalizing Domain Names in 1925 Applications (IDNA)", RFC 3490, March 2003. 1927 [FIRS-ARCH] Hall, E. "The Federated Internet Registry 1928 Service: Architecture and Implementation 1929 Guide", draft-ietf-crisp-firs-arch-03, August 1930 2003. 1932 [FIRS-ASN] Hall, E. "Defining and Locating Autonomous 1933 System Numbers in the Federated Internet 1934 Registry Service", draft-ietf-crisp-firs-asn- 1935 03, August 2003. 1937 [FIRS-CONTCT] Hall, E. "Defining and Locating Contact 1938 Persons in the Federated Internet Registry 1939 Service", draft-ietf-crisp-firs-contact-03, 1940 August 2003. 1942 [FIRS-DNS] Hall, E. "Defining and Locating DNS Domains in 1943 the Federated Internet Registry Service", 1944 draft-ietf-crisp-firs-dns-03, August 2003. 1946 [FIRS-DNSRR] Hall, E. "Defining and Locating DNS Resource 1947 Records in the Federated Internet Registry 1948 Service", draft-ietf-crisp-firs-dnsrr-02, July 1949 2003. 1951 [FIRS-IPV4] Hall, E. "Defining and Locating IPv4 Address 1952 Blocks in the Federated Internet Registry 1953 Service", draft-ietf-crisp-firs-ipv4-03, 1954 August 2003. 1956 [FIRS-IPV6] Hall, E. "Defining and Locating IPv6 Address 1957 Blocks in the Federated Internet Registry 1958 Service", draft-ietf-crisp-firs-ipv6-03, 1959 August 2003. 1961 [US-ASCII] Cerf, V. "ASCII format for Network 1962 Interchange", RFC 20, October 1969. 1964 9. Changes from Previous Versions 1966 draft-ietf-crisp-firs-core-03: 1968 * Several clarifications and corrections have been made. 1970 * Added a discussion on attribute references. 1972 * Added a discussion on referral source entry names. 1974 * Clarified the rules for LDAP referral URLs. 1976 * Temporarily removed the examples for referral processing, 1977 pending additional clarification text. 1979 * Renamed the firsVersion control to inetResourcesControl and 1980 redefined its usage slightly. 1982 * Renamed inetPrivateIdentifier to inetLocalIdentifier 1984 * Added the inetExtAcl attribute option family, and defined 1985 the inetExtAcl client control. 1987 draft-ietf-crisp-firs-core-02: 1989 * Several clarifications and corrections have been made. 1991 * Changed the referral requirements so that servers are 1992 allowed to provide non-LDAP URLs but that FIRS clients are 1993 required to ignore non-LDAP URLs. This synchronizes 1994 referral mechanisms in the back-end data-stores, and moves 1995 the narrower requirement to the client. 1997 * Added an inetPrivateIdentifier attribute for storing 1998 operator-specific labels (E.G., legacy NIC handles). 2000 * Added the firsVersion server control, which provides a 2001 limited amount of version- and feature-negotiation support 2002 to FIRS. 2004 * Several attributes had their OIDs changed. NOTE THAT THIS 2005 IS AN INTERNET DRAFT, AND THAT THE OIDS ARE SUBJECT TO 2006 ADDITIONAL CHANGES AS THIS DOCUMENT IS EDITED. 2008 draft-ietf-crisp-firs-core-01: 2010 * Several clarifications and corrections have been made. 2012 * Significant portions of text were moved to [FIRS-ARCH]. 2014 draft-ietf-crisp-firs-core-00: 2016 * Restructured document set, separating the architectural 2017 discussion from the technical descriptions. Several 2018 sections were relocated to [FIRS-ARCH] as a result of this 2019 change. 2021 * "Attribute references" have been eliminated from the 2022 specification. All referential attributes now provide 2023 actual data instead of URL pointers to data. Clients that 2024 wish to retrieve these values will need to start new 2025 queries using the data values instead of URLs. 2027 * The various modified* operational attributes in the core 2028 schema have been eliminated as unnecessary. 2030 * Several attributes had their OIDs changed. NOTE THAT THIS 2031 IS AN INTERNET DRAFT, AND THAT THE OIDS ARE SUBJECT TO 2032 ADDITIONAL CHANGES AS THIS DOCUMENT IS EDITED. 2034 draft-ietf-crisp-lw-core-00: 2036 * As a result of the formation of the CRISP working group, 2037 the original monolithic document has been broken into 2038 multiple documents, with draft-ietf-crisp-lw-core 2039 describing the core service, while related documents 2040 describe the per-resource schema and access mechanisms. 2042 * References to the ldaps: URL scheme have been removed, 2043 since there is no standards-track specification for the 2044 ldaps: scheme. 2046 * An acknowledgements section was added. 2048 draft-hall-ldap-whois-01: 2050 * The "Objectives" section has been removed. [ir-dir-req] is 2051 now being used as the guiding document for this service. 2053 * Several typographical errors have been fixed. 2055 * Some unnecessary text has been removed. 2057 * Figures changed to show complete sets of object classes, to 2058 improve inheritance visibility. 2060 * Clarified the handling of reverse-lookup domains (zones 2061 within the in-addr.arpa portion of the DNS hierarchy) in 2062 the inetDnsDomain object class reference text. 2064 * Referrals now use regular LDAP URLs (multiple responses 2065 with explicit hostnames and port numbers). Prior editions 2066 of this specification used LDAP SRV resource records for 2067 all referrals. 2069 * The delegation status codes used by the 2070 inetDnsDelegationStatus, inetIpv4DelegationStatus, 2071 inetIpv6DelegationStatus and inetAsnDelegationStatus 2072 attributes have been condensed to a more logical set. 2074 * Added an inetDnsAuthServers attribute for publishing the 2075 authoritative DNS servers associated with a domain. NOTE 2076 THAT THIS IS A TEMPORARY ATTRIBUTE THAT WILL EVENTUALLY BE 2077 REPLACED BY GENERALIZED RESOURCE-RECORD ENTRIES AND 2078 ATTRIBUTES. 2080 * Added an inetGeneralDisclaimer attribute for publishing 2081 generalized disclaimers. 2083 * Added the inetAssociatedResources auxiliary object class 2084 for defining associated resources, and moved some of the IP 2085 addressing and ASN attributes to the new object class. 2087 * Several attributes had their OIDs changed. NOTE THAT THIS 2088 IS AN INTERNET DRAFT, AND THAT THE OIDS ARE SUBJECT TO 2089 ADDITIONAL CHANGES AS THIS DOCUMENT IS EDITED. 2091 10. Author's Address 2093 Eric A. Hall 2094 ehall@ehsco.com 2096 11. Acknowledgments 2098 Funding for the RFC editor function is currently provided by the 2099 Internet Society. 2101 Portions of this document were funded by VeriSign Labs. 2103 The first version of this specification was co-authored by Andrew 2104 Newton of VeriSign Labs, and subsequent versions continue to be 2105 developed with his active participation. Edward Lewis and Peter 2106 Gietz also contributed significant feedback to this specification 2107 in the later stages of its developments. 2109 12. Full Copyright Statement 2111 Copyright (C) The Internet Society (2003). All Rights Reserved. 2113 This document and translations of it may be copied and furnished 2114 to others, and derivative works that comment on or otherwise 2115 explain it or assist in its implementation may be prepared, 2116 copied, published and distributed, in whole or in part, without 2117 restriction of any kind, provided that the above copyright notice 2118 and this paragraph are included on all such copies and derivative 2119 works. However, this document itself may not be modified in any 2120 way, such as by removing the copyright notice or references to the 2121 Internet Society or other Internet organizations, except as needed 2122 for the purpose of developing Internet standards in which case the 2123 procedures for copyrights defined in the Internet Standards 2124 process must be followed, or as required to translate it into 2125 languages other than English. 2127 The limited permissions granted above are perpetual and will not 2128 be revoked by the Internet Society or its successors or assigns. 2130 This document and the information contained herein is provided on 2131 an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET 2132 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR 2133 IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 2134 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2135 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.