INTERNET-DRAFT Eric A. Hall Document: draft-hall-firs-svc-01.txt August 2003 Expires: March, 2004 Category: Experimental Defining and Locating Network Services in the Federated Internet Registry Service Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC 2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Copyright Notice Copyright (C) The Internet Society (2003). All Rights Reserved. Abstract This document defines LDAP schema and searching rules for general network services, in support of the Federated Internet Registry Service (FIRS) described in [FIRS-ARCH] and [FIRS-CORE]. Internet Draft draft-hall-firs-svc-01.txt August 2003 Table of Contents 1. Introduction...............................................2 2. Prerequisites and Terminology..............................3 3. Naming Syntax..............................................3 4. Object Classes and Attributes..............................4 5. Query Processing Rules.....................................7 5.1. Query Pre-Processing....................................8 5.2. LDAP Matching...........................................8 5.3. Example Query...........................................9 6. Security Considerations...................................10 7. IANA Considerations.......................................10 8. Normative References......................................10 9. Author's Addresses........................................11 10. Acknowledgments...........................................11 11. Full Copyright Statement..................................11 1. Introduction This specification defines the naming syntax, object classes, attributes, matching filters, and query processing rules for storing and locating generalized network services in the FIRS service. Refer to [FIRS-ARCH] for information on the FIRS architecture and [FIRS-CORE] for the schema definitions and rules which govern the FIRS service as a whole. In the model proposed in this document, network services are identified by their mnemonic name, with each instance of a service being associated with an existing network resource. In this model, it is possible for multiple instances of a service to be created in the global directory, with each instance being represented by an entry which is subordinate to an existing host, network, domain, or contact entry. This model allows services to exist as heavily-virtualized resources, which in turn allows for a myriad of discovery options. For example, this would allow a client to query for the service- specific data which was associated with a known user, but if that data was not available (either because it did not exist, or because the client did not have permission to read the entry), then the client could query for the service-specific data which was associated with the user's domain. Note that this specification only defines the basic schema and default behavioral rules for service-discovery in general, and Hall I-D Expires: March 2004 [page 2] Internet Draft draft-hall-firs-svc-01.txt August 2003 does not define the schema and behavioral rules for all Internet services, or for any Internet service in particular. In order for this specification to have any significance to any particular Internet service, a standards-track specification which governs that service MUST be defined which explicitly details the schema and/or behavioral rules to be used in support of the model put forth in this specification. The definitions in this specification are intended to be used with FIRS. Their usage outside of FIRS is not prohibited, but any such usage is beyond this specification's scope of authority. 2. Prerequisites and Terminology The complete set of specifications in the FIRS collection cumulatively define a structured and distributed information service using LDAPv3 [RFC3377] for the data-formatting and transport functions. This specification should be read in the context of that set, which currently includes [FIRS-ARCH], [FIRS-CORE], [FIRS-DNS], [FIRS-DNSRR], [FIRS-CONTCT], [FIRS-ASN], [FIRS-IPV4] and [FIRS-IPV6]. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. 3. Naming Syntax The naming syntax for network services in FIRS MUST follow the form of "cn=,,cn=inetResources, ", where is the network service resource, where is the entry of the parent resource that this instance of the service is specifically associated with, and where is a sequence of domainComponent relative distinguished names which identifies the scope of authority for the selected directory partition. The inetService element uses the standardized Directory String syntax with case neutral matching rules, allowing any UTF-8 character code to be used for the service name. However, service names are not entirely free-form. In particular, service names MUST use the friendly name of well-known services from STD1 [STD1] as registered with IANA, and entry names SHOULD be created using the same capitalization as those service names. Hall I-D Expires: March 2004 [page 3] Internet Draft draft-hall-firs-svc-01.txt August 2003 The element can reference any parent resource, specifically including any domain name, IP address, or contact email address, as described in [FIRS-DNS], [FIRS-IPV4], [FIRS-IPV6] and [FIRS-CNTCT] respectively. In this model, services can be specifically associated with a particular host, network, domain, or contact. The client which formulates the query is responsible for determining the scope of the query, and is responsible for crafting the entry name and search base correctly. Note that entries MAY exist as referrals to other entries, and in this regard it is possible to redirect queries for a resource- specific service to another resource, such as redirecting queries for a host-specific service to an entry for a network-wide service, or vice-versa. Refer to [FIRS-ARCH] and [FIRS-CORE] for information about the inetResources container and the domainComponent elements. An example of an typical entry is as follows: cn=http,cn=www.example.com,cn=inetResources,dc=example,dc=com That entry would specifically identify the "http" service associated with the "www.example.com" resource in the directory partition associated with the example.com domain. 4. Object Classes and Attributes Network service entries in FIRS MUST use the inetService object class, in addition to the mandatory object classes defined in [FIRS-CORE]. Network service entries MUST be treated as containers capable of holding subordinate entries. If an entry exists as a referral source, the entry MUST be defined with the referral object class, in addition to the other object classes defined above. Referral sources MUST NOT contain subordinate entries. Refer to section 3.5 of [FIRS-CORE] for more information on referral entries in FIRS. Note that additional service-related schema definitions and behavioral rules are explicitly allowed for any service. For example, a standards-track specification for a particular service MAY define or require specific schema or behavioral rules for that service which are subsequently used by the application agents which ultimately provide that network service. Hall I-D Expires: March 2004 [page 4] Internet Draft draft-hall-firs-svc-01.txt August 2003 The inetService object class is a structural object class which is subordinate to the inetResources object class. The inetService object class has no mandatory attributes, although it does have several optional attributes. The inetService object class also inherits the attributes defined in the inetResources object class, including the "cn" naming attribute. Network service entries MUST NOT have any resource-specific object classes defined other than the inetService object class (this specifically includes any resource-specific object classes which may be associated with a parent resource). The presence of additional resource-specific object classes (such as inetDnsDomain, for example) can cause false matches for some queries, and this MUST be avoided. The schema definition for the inetService object class is as follows: inetService ( 1.3.6.1.4.1.7161.1.9.1 NAME 'inetService' DESC 'General network service attributes.' SUP inetResources STRUCTURAL MAY ( inetServiceContacts $ inetServiceTargets ) ) The attributes from the inetService object class are described below: inetServiceContacts ( 1.3.6.1.4.1.7161.1.9.2 NAME 'inetServiceContacts' DESC 'Contacts for general administrative issues concerning this network service.' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.7161.1.4.0 ) inetServiceTargets ( 1.3.6.1.4.1.7161.1.9.3 NAME 'inetServiceTargets' DESC 'Connection information for this service.' EQUALITY caseIgnoreMatch SYNTAX inetServiceTargetSyntax ) Hall I-D Expires: March 2004 [page 5] Internet Draft draft-hall-firs-svc-01.txt August 2003 The inetServiceTargets attribute is a structured (SEQUENCE) attribute, containing multiple subordinate attributes. The subordinate attributes explicitly identify a target host by domain name, a transport protocol (decimal value), a port number (decimal value), a preference value for the specified target, and a non- descript weighting value. This allows multiple targets to be associated with each entry, with each target identifying different hosts, transport protocols, and port numbers, as necessary. The preference value simply gives a fixed preference using inverse weighting, with a value of zero have the highest preference and a value of 65,535 having the lowest preference. Targets with equal preference values are to be randomly selected by default, although service-specific profiles may define additional requirements (e.g., a service-specific profile may require that the client analyze the target's domain name or IP address in order to determine the "closest" target). The meaning of the weighting value is undefined in this specification. It is provided so that additional specifications can define any load-balancing mechanisms they may require. The inetServiceTargetSyntax syntax is defined in ASN.1 as follows: inetServiceTargetSyntax ::= SEQUENCE { Hostname inetDnsDomainSyntax, Transport INTEGER (0..65535), Port INTEGER (0..65535), Preference INTEGER (0..65535), Weight INTEGER (0..65535) } Hall I-D Expires: March 2004 [page 6] Internet Draft draft-hall-firs-svc-01.txt August 2003 An example of the inetService object class is shown in Figure 1 below. cn=http,cn=www.example.com,cn=inetResources, dc=example,dc=com [top object class] [inetResources object class] [inetService object class] | +-attribute: description | value: "The http service on www.example.com" | +-attribute: inetServiceContacts | value: "webmaster@example.com" | +-attribute: inetServiceTargets value: (www.example.com, 6, 80, 0, 0) value: (server1.example.net, 6, 80, 100, 0) value: (server2.example.net, 6, 80, 100, 0) Figure 1: The "http" service associated with the www.example.com resource in the dc=example,dc=com directory partition. In the example shown in Figure 1 shows three distinct resource targets, with tcp/80 on "www.example.com" having the greatest preference, and with tcp/80 on "server1.example.net" and "server2.example.net" both having equally lesser preferences. In this example, if the www.example.com host were unavailable, the client could choose from either of the two remaining hosts. Note that this example assumes that the "http" profile would actually specify the described behavior. This document is not authoritative for the http service, and as such this example is only provided for illustration purposes. 5. Query Processing Rules Queries for network services have several special requirements, as discussed in the following sections. Refer to [FIRS-CORE] for general information about FIRS queries. Hall I-D Expires: March 2004 [page 7] Internet Draft draft-hall-firs-svc-01.txt August 2003 5.1. Query Pre-Processing FIRS clients MUST use the targeted bootstrap model by default for network service queries (note that individual service-specific definitions may specify any alternative behavior necessary). As such, the search base for default queries would be set to the complete sequence of domainComponent relative distinguished names of the authoritative partition. FIRS clients MAY use the top-down or bottom-up bootstrap models for queries if necessary or desirable. However, it is not likely that entries will be found for all possible services using the top-down model (the "dc=com" partition is not likely to have entries for all of the services in the "dc=example,dc=com" hierarchy, for example), while the bottom-up recovery model is likely to generate excessive errors and delays. As such, the targeted bootstrap model will be the most useful in most cases, and MUST be used by default. This specification uses two inputs to form the query -- the service name, and the associated target resource -- both of which must be dealt with explicitly and separately. The service name will be used to form an assertion value, while the associated target resource will be used as part of the search base. Clients MUST ensure that the name of the service is properly formulated, in compliance with the rules described in section 3. Clients MUST normalize the target name of the query according to the syntax rules associated with the resource-type in question. For example, if the target specifies a domain name, that element MUST conform to the inetDnsDomainSyntax rules defined in [FIRS-DNS], but if the target specifies an IPv4 address, that element MUST conform to the inetIpv4NetworkSyntax rules defined in [FIRS-IPV4], and so forth. 5.2. LDAP Matching FIRS clients MUST specify equalityMatch matching filters in LDAP searches for network service entries. In order to ensure that all of the relevant entries are found (including any referrals), the search filters for these resources MUST specify the inetService object class and the naming element of the service. For example, "(&(objectclass=inetService) Hall I-D Expires: March 2004 [page 8] Internet Draft draft-hall-firs-svc-01.txt August 2003 (cn=http))" with a search base of "cn=inetResources,dc=example,dc=com" would find all of the inetService object class entries with a cn value of "http" in the "dc=example,dc=com" partition. The matching filters defined in this specification MUST be supported by FIRS clients and servers. FIRS servers MAY support additional matching filters, although FIRS clients MUST NOT expect any additional filters to be available. 5.3. Example Query The following example assumes that the user wants to locate the "http" service entry associated with the www.example.com host: a. Normalize the elements into relative distinguished names, which would be "cn=http" and "cn=www.example.com" in this example. Prepare to use the service name as the seed for the assertion value, and the target name as part of the search base. b. Determine the canonical authoritative partition, which will be based on the specified target in the default case. Using the bottom-up model and this example, the authoritative partition would be "dc=www,dc=example,dc=com" by default. c. Determine the search base for the query, which will be "cn=www.example.com,cn=inetResources,dc=www,dc=example, dc=com" if the defaults are used. d. Initiate a DNS lookup for the SRV resource records associated with "_ldap._tcp.www.example.com." For the purpose of this example, assume that this lookup fails, and that a subsequent fall-back query is issued for the parent partition (as per the bottom-up processing rules as defined in [FIRS-CORE]). 1. Reset the default partition to "dc=example,dc=com". 2. Reset the search base to "cn=www.example.com, cn=inetResources,dc=example,dc=com". 3. Initiate a new DNS lookup for the SRV resource records associated with "_ldap._tcp.example.com." For the purpose of this example, assume that this lookup Hall I-D Expires: March 2004 [page 9] Internet Draft draft-hall-firs-svc-01.txt August 2003 succeeds, with the DNS response message indicating that the "firs.example.com" is the preferred server. e. Submit an LDAPv3 query to the specified server, using "(&(objectClass=inetService)(cn:dn:http)" as the matching filter, "cn=www.example.com,cn=inetResources,dc=example, dc=com" as the search base, and the global query defaults defined in [FIRS-CORE]. f. Assume that no referrals are received. Display the answer data which has been received and exit the query. 6. Security Considerations Security considerations are discussed in [FIRS-ARCH]. 7. IANA Considerations Usage profiles for individual services MUST be defined in standards-track specifications for each service in order for those definitions to have meaning. For example, the "http" service examples described in this document are not valid unless and until a formal specification describing that usage is defined in a standards-track specification. This specification requires that service names and transport protocols be registered with IANA. This requirement also specifically includes non-Internet services which are expected to be used with this specification. Additional IANA considerations are discussed in [FIRS-ARCH]. 8. Normative References [FIRS-ARCH] Hall, E. "The Federated Internet Registry Service: Architecture and Implementation Guide", draft-ietf-crisp-firs-arch-03, May 2003. [FIRS-ASN] Hall, E. "Defining and Locating Autonomous System Numbers in the Federated Internet Registry Service", draft-ietf-crisp-firs-asn- 03, May 2003. [FIRS-CONTCT] Hall, E. "Defining and Locating Contact Persons in the Federated Internet Registry Service", draft-ietf-crisp-firs-contact-03, May 2003. Hall I-D Expires: March 2004 [page 10] Internet Draft draft-hall-firs-svc-01.txt August 2003 [FIRS-CORE] Hall, E. "The Federated Internet Registry Service: Core Elements", draft-ietf-crisp- firs-core-03, May 2003. [FIRS-DNS] Hall, E. "Defining and Locating DNS Domains in the Federated Internet Registry Service", draft-ietf-crisp-firs-dns-03, May 2003. [FIRS-DNSRR] Hall, E. "Defining and Locating DNS Resource Records in the Federated Internet Registry Service", draft-ietf-crisp-firs-dnsrr-03, May 2003. [FIRS-IPV4] Hall, E. "Defining and Locating IPv4 Address Blocks in the Federated Internet Registry Service", draft-ietf-crisp-firs-ipv4-03, May 2003. [FIRS-IPV6] Hall, E. "Defining and Locating IPv6 Address Blocks in the Federated Internet Registry Service", draft-ietf-crisp-firs-ipv6-03, May 2003. [RFC3377] Hodges, J., and Morgan, R. "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. [STD1] http://www.iana.org/assignments/port-numbers 9. Author's Addresses Eric A. Hall ehall@ehsco.com 10. Acknowledgments Funding for the RFC editor function is currently provided by the Internet Society. 11. Full Copyright Statement Copyright (C) The Internet Society (2003). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice Hall I-D Expires: March 2004 [page 11] Internet Draft draft-hall-firs-svc-01.txt August 2003 and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Hall I-D Expires: March 2004 [page 12]