Network Working Group N. Popp Internet-Draft RealNames Corporation Expires: November 30, 2000 M. Mealling Network Solutions, Inc. M. Moseley Netword, Inc. June 2000 CNRP PROTOCOL SPECIFICATION draft-ietf-cnrp-04 Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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." To view the entire list of Internet-Draft Shadow Directories, see http://www.ietf.org/shadow.html. This Internet-Draft will expire on November 30, 2000. Copyright Notice Copyright (C) The Internet Society (2000). All Rights Reserved. Abstract Please send comments on this draft to CNRP-IETF@LISTS.INTERNIC.NET. People often refer to things in the real world by a common name or phrase, e.g., a trade name, company name, or a book title. These names are sometimes easier for people to remember and type than URLs. Furthermore, because of the limited syntax of URLs, companies and individuals are finding that the ones that might be most reasonable for their resources are being used elsewhere and so are unavailable. For the purposes of this document, a "common name" is a word or a phrase, without imposed syntactic structure, that may be associated with a resource. Popp, et. al. Expires November 30, 2000 [Page 1] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 This effort is about the creation of a protocol for client applications to communicate with common name resolution services, as exemplified in both the browser enhancement and search site paradigms. Although the protocol's primary function is resolution, it is intended to address the issues of internationalization and privacy as well. Name resolution services are not generic search services and thus do not need to provide complex Boolean query, relevance ranking or similar capabilities. The protocol is a simple, minimal interoperable core. Mechanisms for extension are provided, so that additional capabilities can be added. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 4 2. Important Notes . . . . . . . . . . . . . . . . . . . . . 5 2.1 Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 2.2 DTD is Definitive . . . . . . . . . . . . . . . . . . . . 5 2.3 Uniform Resource Identifiers . . . . . . . . . . . . . . . 5 3. Interaction Model . . . . . . . . . . . . . . . . . . . . 5 3.1 Services, Servers, Datasets and Referrals . . . . . . . . 5 3.2 Requests and Responses . . . . . . . . . . . . . . . . . . 6 3.3 Transport independence . . . . . . . . . . . . . . . . . . 6 3.4 Character sets . . . . . . . . . . . . . . . . . . . . . . 6 3.5 Queries . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.6 Hints . . . . . . . . . . . . . . . . . . . . . . . . . . 7 4. Object Model . . . . . . . . . . . . . . . . . . . . . . . 8 4.1 Properties . . . . . . . . . . . . . . . . . . . . . . . . 8 4.1.1 Core properties . . . . . . . . . . . . . . . . . . . . . 8 4.1.2 Abstract and custom properties . . . . . . . . . . . . . . 9 4.1.3 Base properties . . . . . . . . . . . . . . . . . . . . . 9 4.1.4 Common name string encoding and equivalence rules . . . . 10 4.2 Objects . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.2.1 Query . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.2.1.1 Logical operations within a Query . . . . . . . . . . . . 11 4.2.2 Results . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.2.2.1 ResourceDescriptor . . . . . . . . . . . . . . . . . . . . 12 4.2.3 Service . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.2.3.1 Datasets . . . . . . . . . . . . . . . . . . . . . . . . . 14 4.2.3.2 Servers . . . . . . . . . . . . . . . . . . . . . . . . . 15 4.2.4 Status Messages . . . . . . . . . . . . . . . . . . . . . 17 4.2.4.1 Status of CNRP, Not the Transport . . . . . . . . . . . . 17 4.2.4.2 Codes and Description . . . . . . . . . . . . . . . . . . 18 4.2.4.3 Status Codes . . . . . . . . . . . . . . . . . . . . . . . 18 4.2.5 Referral . . . . . . . . . . . . . . . . . . . . . . . . . 19 4.2.6 Discoverability: ServiceQuery and Schema . . . . . . . . . 20 5. XML DTD for CNRP . . . . . . . . . . . . . . . . . . . . . 22 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 24 6.1 Service Description Request . . . . . . . . . . . . . . . 24 6.2 Sending A Query and Getting A Response . . . . . . . . . . 26 Popp, et. al. Expires November 30, 2000 [Page 2] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 6.3 No Result . . . . . . . . . . . . . . . . . . . . . . . . 27 6.4 Error Conditions . . . . . . . . . . . . . . . . . . . . . 27 7. Transport . . . . . . . . . . . . . . . . . . . . . . . . 27 7.1 HTTP Transport . . . . . . . . . . . . . . . . . . . . . . 27 7.2 SMTP Transport . . . . . . . . . . . . . . . . . . . . . . 28 8. Security Considerations . . . . . . . . . . . . . . . . . 28 9. IANA Considerations . . . . . . . . . . . . . . . . . . . 28 References . . . . . . . . . . . . . . . . . . . . . . . . 29 Authors' Addresses . . . . . . . . . . . . . . . . . . . . 30 A. Appendix A: Well Known Property and Type Registration Templates . . . . . . . . . . . . . . . . . . . . . . . . 30 A.1 Properties . . . . . . . . . . . . . . . . . . . . . . . . 30 A.2 Types . . . . . . . . . . . . . . . . . . . . . . . . . . 31 B. Status Codes . . . . . . . . . . . . . . . . . . . . . . . 32 B.1 Level 1 (Informative) Codes . . . . . . . . . . . . . . . 32 B.2 Level 2 (Success) Codes . . . . . . . . . . . . . . . . . 32 B.3 Level 3 (Partial Success) Codes . . . . . . . . . . . . . 32 B.4 Level 4 (Transient Failure) Codes . . . . . . . . . . . . 33 B.5 Level 5 (Permanent Failures) Codes . . . . . . . . . . . . 33 Full Copyright Statement . . . . . . . . . . . . . . . . . 34 Popp, et. al. Expires November 30, 2000 [Page 3] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 1. Introduction Services are arising that offer a mapping from common names to Internet resources (e.g., as identified by a URI). These services often resolve common name categories such as company names, trade names, or common keywords. Thus, such a resolution service may operate in one or a small number of categories or domains, or may expect the client to limit the resolution scope to a limited number of categories or domains. For example, the phrase "Internet Engineering Task Force" is a common name in the "organization" category, as is "Moby Dick" in the book category. Two classes of clients of such services are being built, browser improvements and web accessible front-end services. Browser enhancements modify the "open" or "address" field of a browser so that a common name can be entered instead of a URL. Internet search sites integrate common name resolution services as a complement to search. In both cases, these may be clients of back-end resolution services. In the browser case, the browser must talk to a service that will resolve the common name. The search sites are accessed via a browser. In some cases, the search site may also be the back- end resolution service, but in others, the search site is a front-end to a collection of back-end services. This effort is about the creation of a protocol for client applications to communicate with common name resolution services, as exemplified in both the browser enhancement and search site paradigms. Although the protocol's primary function is resolution, it is intended to address the issues of internationalization and privacy as well. Name resolution services are not generic search services and thus do not need to provide complex Boolean query, relevance ranking or similar capabilities. The protocol is a simple, minimal interoperable core. Mechanisms for extension are provided, so that additional capabilities can be added. Several other issues, while of importance to the deployment of common name resolution services, are outside of the resolution protocol itself and are not in the initial scope of the proposed effort. These include discovery and selection of resolution service providers, administration of resolution services, name registration, name ownership, and methods for creating, identifying or insuring unique common names. For the purposes of this document, a "common name" is a word or a phrase, without imposed syntactic structure, that may be associated with a resource. These common names will be used primarily by humans, as opposed to machine agents. A common name "resolution service" handles these associations between common names and data (resources, information about resources, pointers to locations, Popp, et. al. Expires November 30, 2000 [Page 4] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 etc). A single common name may be associated with different data records, and more than one resolution service is expected to exist. Any common name may be used in any resolution service. Common names are not URIs (Uniform Resource Identifiers) in that they lack the syntactic structure imposed by URIs; furthermore, unlike URNs, there is no requirement of uniqueness or persistence of the association between a common name and a resource. (Note: common names may be expressed in a URI, the syntax for which is described herein.) This document will define a protocol for the parameterized resolution necessary to make common names useful. "Resolution" is defined as the retrieval of data associated (a priori) with descriptors that match the input request. "Parameterized" means the ability to have a multi-property descriptor. Descriptors are not required to provide unique identification, therefore 0 or more records may be returned to meet a specific input query. 2. Important Notes 2.1 Terminology 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[6]. 2.2 DTD is Definitive The descriptive portions of this document contain pieces of XML that are *illustrative examples only*. Section 5 of this document contains the XML DTD for CNRP, which is definitive. If any discrepancies are found, the DTD wins. 2.3 Uniform Resource Identifiers All URIs used within the CNRP protocol MUST adhere to the 'absoluteURI' production found in the ABNF of [3]. CNRP does not define the semantics of a Base and therefore is not capable of expressing the 'URI-Reference' production. 3. Interaction Model 3.1 Services, Servers, Datasets and Referrals CNRP assumes a particular interaction model where a generalized "service" provides common name resolution at one or more actual "servers". If the data contained in all its servers is identical Popp, et. al. Expires November 30, 2000 [Page 5] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 (mirrors), the service need not identify any particular subset of data. If, however, the service provides different collections of data through different servers (e.g., subsets, specialized collections, etc), it MUST indicate what subsets of its data that each server offers. This is done by using URIs to uniquely disambiguate one dataset from another. If the service offers a copy of a collection of data on agreement with a foreign service, the foreign service MUST provide a dataset URI to allow the collection to be identified as related to its own offerings. CNRP supports the concept of referrals. This is where a server can know that another Service exists that can provide further answers to a particular query but decides to forward that fact onto the client instead of chaining the query for the client. A referral is sent along with the rest of the results from a server (if any). Referrals to a service SHOULD indicate the particular dataseturi that triggered the referral, if it is known. 3.2 Requests and Responses The protocol consists of a simple request/response mechanism. A client sends one of a few types of requests to a server which responds with the results of that request. All requests and responses are encoded with XML[7] using the DTD found in Section 5. There are two types of requests. One is a general query for a common-name. The other is a request for an object that describes the service and its capabilities. There is only one type of response which is a set of results. Results can contain actual result items, referrals and/or errors. 3.3 Transport independence Since CNRP is completely encapsulated within its XML definition it can be considered transport-independent. However, because there must be a standardized way for a client to contact and negotiate with a server, CNRP requires support for HTTP 1.1 (RFC 2616)[2] or greater on the default CNRP port of 1096. A particular service may choose to change to a different transport (via statements within the XML DTD), but minimally, all initial contacts between a client and a server that the client knows nothing about can be assumed to function over HTTP. For a short explanation of how CNRP employs HTTP, see Section 7.1 of this document. If other transports are used they MUST be handled over a port other than the default CNRP port. 3.4 Character sets The character set encoding of a common name is always UTF-8. Popp, et. al. Expires November 30, 2000 [Page 6] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 Specifically: o Within an XML query or response, the common name is represented in UTF-8, WITHOUT any hex-encodings o Within a CNRP URI, the REPRESENTATION of the common name is hex-encoding of the UTF-8 common name -- because this is an issue for the CNRP URI, not the common name. o Similarly, in other environments (e.g., particular display devices) the common name may be _presented_ in a different character-set, but that is a display/data entry issue. It is not a "common name" unless it's encoded in UTF-8. 3.5 Queries Queries are sent by the client to the server. There are two types of queries. 1. A `special' initial query that establishes the schema for a particular CNRP database and communicates that to the client. The CNRP client will send this query, and in turn receive an XML document defining the query properties that the database supports. (In CNRP, XML[7] is used to define and express all objects.) This query is called the 'servicequery' in the DTD. In the case where a client does not now anything about the Service, the client MAY assume that it can at least issue the request via HTTP. 2. A `standard' query, which is the submission of the CNRP search string to the database. The query will conform to the schema that MAY have been previously retrieved from the service. There will be a set of query properties, listed below, treated as hints by the server. Note: a CNRP database will accept any correctly encoded CNRP query property; the extent to which a query result is responsive to those properties is a service differentiator. The base properties that are always supported are common name, language, geography, category, and range (start and length of the result set). CNRP allows database service providers to create unique data types and expose them to any CNRP client via the CNRP schema XML documents. 3.6 Hints A hint is an assertion by the user about himself, herself or itself and the context in which he/she/it is operating. There is no data type `hint'; a hint is expressed within the structure of the query itself and is limited or enabled by the richness of the defined query namespace. In effect, a query and any property within it is a hint. An example of this would be the required property "language", in which a query might be created that specifies the primary language Popp, et. al. Expires November 30, 2000 [Page 7] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 in which you want to see results, the secondary language, and so on. So seeing results in US English followed by European French and South American Spanish would be: en-US fr-FR sp-MX Note that the property statements say nothing about whether the language is primary, secondary,etc. In this example the ordering of the statement controls that--the first statement, being first, means that US English is the primary language. The second statement specifies the second region/language, and so on. *But this is only an example.* The extent to which hints are supported (or not) is a service differentiator. The fact that a hint exists does not mean that a CNRP database must respond to it. This best-effort approach is similar to relevance ranking in a search engine (high precision, low recall); hints are similar to a search engine's selection criteria. CNRP services will attempt to return the results "closest" to the selection criteria. This is quite different from a SQL database approach where a SQL query returns the entire results set and each result in the set must match all the requirements expressed by the qualifier (the SQL WHERE clause). 4. Object Model 4.1 Properties In CNRP, objects are property lists. A property is a named attribute. A property also has a well-defined type. Some properties can be part of the query or the results list or both. For simplicity, CNRP is limiting property values to string values. 4.1.1 Core properties CNRP introduces a set of core properties. Core properties are the minimal set of properties that all CNRP services MUST support in order to reach CNRP compliance. Hence, the core properties define the level of interoperability between all CNRP services. The core properties are: 1. CommonName: the common name associated with a resource. 2. ID: an opaque string that serves as a unique identifier for a result from a Service (typically a database ID). The ID is not globally unique, nor necessarily persistent (e.g., between queries at a given Service) 3. resourceURI: An 'absoluteURI' as defined in the collected ABNF found in RFC 2396[3]. 4. description: A free text description of the resource. Popp, et. al. Expires November 30, 2000 [Page 8] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 4.1.2 Abstract and custom properties In addition to core properties, CNRP introduces the notion of abstract properties. The abstract property element provides schema extensibility beyond the core properties. The notion of abstract property is extremely important in CNRP since it enables a wider range of CNRP based services than those based on the core properties. To create concrete custom properties, a CNRP service must define a property name and a property type. Therefore, there are really two ways to create a custom property. The first way is to create a new property name and define at least one type for it. Another way is to extend an existing property by defining a new type. The "geography" property discussed in the next section is an example of a multi-type property. Note that a type is only applicable to the property it is defined for. If a new property is defined, a new type MUST be defined even though the value set for that type may be identical to an existing type for an existing property. In other words, types are scoped to a given property. Custom properties MUST be registered with IANA. Details about the registration process for new properties can be found in Section 9. For example, let us assume that a CNRP service specialized on online books would like to introduce the ISBN property of type "number". This property would encapsulate the ISBN number of the book online and would have he following XML representation: 92347231 4.1.3 Base properties Illustrating the use of abstract property to extend the core schema, CNRP also defines a set of custom properties called base properties. In order to keep the requirements extremely simple, these properties are not mandatory to implement to reach CNRP compliance. Although, these properties are not required, it is expected that many services, especially large ones, will implement them. An equally important goal for introducing additional properties is to provide a results filtering mechanism. This is a requirement for large namespaces that contain several million names. The base properties and their types are defined in Appendix A but listed here for clarity: o Language: The language associated with a resource. The default type of this property is 'RFC1766' and the vocabulary is drawn from the list of languages in RFC 1766[4]. If RFC 1766 is updated then the values listed in the updated version are also valid for this Popp, et. al. Expires November 30, 2000 [Page 9] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 type. o Geography: The geographical region or location associated with a resource. Some of the possible types for: * 'freeform': a free form expression for a geographical location (e.g. "palo alto in california"). * 'ISO3166-1': geographical region expressed using a standard country code as defined by ISO3166-1 (e.g. "US"). * 'ISO3166-2': value = a geographical region expressed using a standard region and country codes as defined by ISO3166-2 (e.g. "US-CA"). * 'latitude-longitude-elevation': the latitude, longitude and elevation of a geographical location expressed in a comma delimited string (i.e. "latitude,longitude,elevation") * 'GPS': a geographical location expressed using the standard GPS coordinates system o Category: The category associated with a resource. There are large numbers of possible types for this property. Two possible ones are: 1. 'freeform': a free form expression for a category (e.g. "movies"). 2. 'NAICS': The North American Industry Code System. o Range: The range is a results set control property. The range property is used to specify the starting point and the length of a results set (e.g. I want 5 records starting at the 10th record). It should only ever have one type but, in the interest of extensibility and consistency, others can be created if there is a need. The default type is 'start-length' which takes the form of two integers separated by a dash. The first integer is the starting number and the second is the number of values to include. o Dataseturi: An absoluteURI (as defined in [3] that identifies a defined set of Common Names and associated data. NOTE: For many properties the default "type" is "freeform". The free form type value is important because it allows very simple user interface where the user can enter a value in a text field. It is up to the service to interpret the value correctly and take advantage of it to increase the relevance of results (using specialized dictionaries for instance). 4.1.4 Common name string encoding and equivalence rules CNRP specifies that common name strings should be encoded using UTF-8. CNRP does not specify any string equivalence rules for matching a common name in the query against a common name of a Resource. String equivalence rules are language and service dependent. They are specific to relevance ranking algorithms, hence Popp, et. al. Expires November 30, 2000 [Page 10] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 treated as CNRP services. Consequently, string equivalence rules are not part of the CNRP protocol specification. For example, the query member: bmw Should be read as a selection criterion for a resource with a common name LIKE (similar to) the string "bmw" where the exact definition of the LIKE operator is intuitive, yet specific to the queried CNRP service. 4.2 Objects 4.2.1 Query The Query object encapsulates all the query components such as CommonName, ID, and any properties. A Query cannot be empty. A Query must contain either a common name, or an ID. A Query can also contain the custom properties defined by a specific CNRP service. For example, a query for the first 5 resources whose common name is like "bmw" would be expressed as: bmw 1-5 4.2.1.1 Logical operations within a Query The Query syntax is extremely simple. CNRP does not extensively support Boolean logic operator such as OR, AND or NOT. However, there exist two implicit logical operations that can be expressed through the Query object and its properties. First, a query with multiple property-value pairs implicitly expresses an AND operation on the query terms. For instance, the CNRP query to request all the resources whose common name is like "bmw", AND whose language is "German" can be expressed as: bmw de-DE Note however, that because the server is only trying to best match the Query criteria, there is no guarantee that all or any of the resources in the results match both requirements. Popp, et. al. Expires November 30, 2000 [Page 11] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 In addition, CNRP allows the client to express a logical OR by specifying multiple values for the same property within the Query. For example, the logical expression: property = value1 OR property = value2 OR property = valueN Will be expressed as: value1 value2 valueN So if there are different properties expressed, CNRP ANDs them; if there are multiples of the same property expressed, CNRP ORs them. It is important to underline that this form is only applicable to properties. In particular, logical OR operations on the common name are not supported. Note that the ordering or the property-value pairs in the query implies a precedence. As a consequence, CNRP also introduces one special string value: "*". Not surprisingly, "*" means all admissible values for the typed property. For example, the following query requests all the resources whose common name is like BMW and whose language is preferably in German or French or any other language. bmw de-DE fr-FR * 4.2.2 Results The results object is a container for CNRP results. The type of objects contained in Results can be: ResourceDescriptor, Error, Referral and Schema. Results from a CNRP service are ordered by decreasing relevance. When the results set contains results from multiple CNRP services, the results can no longer be ordered (since relevance ranking is specific to a given service). In that case, however, note that results originating from the same service remain ordered. 4.2.2.1 ResourceDescriptor The ResourceDescriptor object describes an Internet resource (e.g. a Web page, a person, any object identified by a URI). Therefore, the ResourceDescriptor MUST always include the resourceURI property. The ResourceDescriptor can also contain the commonname, URI, ID (the ID of this entry in the service's database), description, language, Popp, et. al. Expires November 30, 2000 [Page 12] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 geography, and category of the resource. A ResourceDescriptor can also be augmented using custom properties and can reference a service object to indicate its origin (using the serviceRef element). http://cnrp.bar.com/ bmw foo.com:234364 http://www.bmw.de/ de-DE 4.2.3 Service The Service object provides an encapsulation of an instance of a CNRP service. A service is uniquely identified through the serviceuri tag. A Service object can include a a brief textual description of the service. http://cnrp.foo.com foo.com is a CNRP service specialized on cocktail recipes The service object can also be extended by including existing properties to further describe the service. For instance, a service that focuses on French companies could be expressed as: http://cnrp.foo.com companies FR Popp, et. al. Expires November 30, 2000 [Page 13] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 4.2.3.1 Datasets The dataset object represents a set of CN-to-URI mappings. For example, the database of AOL keywords and their URIs constitute a dataset. The dataset object allows a CNRP implementation to uniquely identify the database(s) of mapings that it resolves. In that respect, the notion of dataset allows a separation between resolution and data, providing the mechanism for a CNRP service to resolve common-names on behalf of another CNRP service or even multiple services. Conversely, the same dataset can be served by two distinct CNRP services. Since a CNRP service can resolve names within one or more datasets, the service object can contain one or more dataset objects (zero if the dataset is not formally declared). Within the service object, a dataset is uniquely defined using the dataseturi property. Other properties, such as language and description, can describe the dataset further. Like the service object, the dataset object has an ID attribute associated with it that is unique within a particular XML message. Like the service object's ID attribute, this ID is used by resourcedescriptors and referrals to specify which service and/or dataset they came from or are referring to. This example illustrates how the service object would look as it defines two datasets: http://acmecorp.com urn:oid:1.2.3.4.666.5.4.3.1 en-us en-gb This is an example of a complex CNRP service urn:oid:1.2.3.4.666.10.9.8.7.6 fr The dataseturi property can also be used within the query as a hint to the service for the dataset within which the commonname should be resolved: toys r us urn:oid:1.2.3.4.666.5.4.3.1 Popp, et. al. Expires November 30, 2000 [Page 14] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 It is important to note that resolution rules (i.e. string equivalence, relevance raking, etc) are likely to be dataset specific. This is true even if the resolution is provided by the same service. Another use of the dataseturi property is in a referral. In that case, the datasetref tag is used to pinpoint a specific dataset within the service. While the concept of datasets is important for services wishing to make their data available via other services, it is important to remember that the declaration and use of datasets is completely optional. Compliance with the CNRP protocol does not require a service object to define or reference any dataset object. The only requirement for compliance is that a client and/or server know the format of the particular XML tags and deal with them syntactically. If it chooses to ignore them then this is well within its rights. 4.2.3.2 Servers The service object also encapsulates a list of server objects. The server object is used to describe a CNRP server or set of servers. A server is identified through its serveruri. The URI used to identify a server is not a CNRP URI but instead is a URI of the scheme used as the CNRP transport mechanism. I.e. for a CNRP server that will communicate via the HTTP protocol to the host foo.com on port 6543, the serveruri would be http://foo.com:6543. If some other information is required in order for the correct transport to be used, then that information can be communicated via other properties. A server can serve one or more datasets declared by its service. The served databases are specified using the dataseturi property. As for other objects, a server can be further described using descriptive properties such as geography and description. The following XML completes the service definition from the previous example by defining two CNRP servers. One server is located in the US and the other is located in France. The US server is specialized and only serves the French dataset. Popp, et. al. Expires November 30, 2000 [Page 15] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 cnrp://router.us.widgetco.com:4321 US cnrp://router.fr.acmeco.com:4321 FR As we will see in a following section, the Service object can contain Schema objects. These Schema objects fully describe the query and response interfaces implemented by a CNRP service. In that regard, the Service object is essential to discoverability. It constitutes the main entry point for a CNRP client to dynamically discover the capabilities of a resolution service. For that purpose, the Service object can be returned as part of the response to any resolution query. Furthermore, the Service object is the dedicated response to the specialized servicequery (see Section 4.2.6). Another use of Service is for other objects to indicate their CNRP service of origin. System messages, referrals and resourcedescriptors can include a reference to their Service object. For example, imagine a CNRP service that acts as a proxy for multiple CNRP services. (it is actually a requirement that CNRP allows the aggregation of results from different sources). In this mode, the proxy service contacts each CNRP sub-services in parallel or serially. Then, the proxy combines the individual result sets into a unique response returned to the CNRP client. Since the aggregate result set contains resourcedescriptors from different services, the proxy adds a servicereference tag within each individual result to indicate their service of origin. In the event one of the referred services resolves names within multiple datasets, it is possible for these objects to refer to a specific dataset within the service by using the datasetref tag. This example is of a hybrid result set with resourcedescriptors referencing their service and dataset of origin: http://acmecorp.com urn:oid:1.2.3.4.666.5.4.3.1 Popp, et. al. Expires November 30, 2000 [Page 16] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 urn:oid:1.2.3.4.666.10.9.8.7.6 http://serverfarm.acmecorp.com http://servers.acmecorp.co.uk urn:oid:1.2.3.4.666.5.4.3.1 Fidonet 1333459455 http://www.fidonet.ca This is ye olde Canadian Fidonet Fidonet 1333459455 http://host:port/bla 4.2.4 Status Messages 4.2.4.1 Status of CNRP, Not the Transport The status messages defined here are only applicable to operations defined by CNRP itself. If some feature or operation is defined by the transport (security via HTTP, mail failure via SMTP, etc) then any status messages about that operation MUST be sent in accordance with that transport's reporting mechanism and not via CNRP. Popp, et. al. Expires November 30, 2000 [Page 17] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 4.2.4.2 Codes and Description A Status object indicates a message to the client in the results set. The object encapsulates two values: a status code and a description. The description can contain a textual description of the status being communicated. In many cases, additional diagnostic information can also be included. No attempt is made to standardize the description of a given status code since the only programmatic element that matters is the actual code. The CNRP foo.com database is temporarily unreachable 4.2.4.3 Status Codes The organization of status codes is taken from RFC 1893[9] which structures its codes in the form of x.yyy.zzz. Taken from RFC 1893 is the ABNF for the codes: status-code = class "." subject "." detail class = "2"/"3"/"4"/"5" subject = 1*3digit detail = 1*3digit The top level codes denote levels of severity of the status: o 1.X.X Informational * The information conveyed by the code has no bearing or indication of the success or failure of any request. It is strictly for informational purposes only. o 2.X.X Success * The request was processed and results were returned. In most cases this status class won't be sent since actual results themselves denote success. In other cases results were returned but some information needs to be returned to the client. o 3.X.X Partial Success * The request was processed and results were returned. In this case though, some values sent with the request were either invalid or ignored but in a way that the server still considers the response to be a successful one and not indicative of any true error condition. o 4.X.X Transient Failure * The request was valid as sent, but some temporary event prevents the successful completion of the request and/or sending of the results. Sending in the future may be possible. Popp, et. al. Expires November 30, 2000 [Page 18] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 o 5.X.X Permanent Failure * A permanent failure is one which is not likely to be resolved by re-sending the request in its current form. Some change to the request or the destination must be made for successful request. The second level codes denote the subject of the status messages. This value applies to each of the five classifications. The subject sub-code, if recognized, must be reported even if the additional detail provided by the detail sub-code is not recognized. The enumerated values for the subject sub-code are: o X.0.X Other or Undefined Status * No specific information is available about what subject class this message belongs to o X.1.X Query Related * Any status related to some specific way in which the query was encoded or its values with the exception of properties. o X.2.X Service Related * Any status related to the service in which this server is cooperating in providing. Appendix B contains a list of all predefined status codes 4.2.5 Referral A Referral object in the results set is a place holder for un-fetched results from a different service and possibly dataset. Referrals typically occur when a CNRP server knows of another service capable of providing relevant results for the query and wants to notify the client about this possibility. The client can decide whether it wants to follow the referral and resolve the extra results by contacting the referred-to service using the information contained within the Referral object (a Service object and possible properties). The Referral is a simple mechanism to enable hierarchical resolution as well as to join multiple resolution services together. Popp, et. al. Expires November 30, 2000 [Page 19] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 http://cnrp.bar.com/ urn:oid:1.3.6.1.4.1.782.1 urn:oid:1.3.6.1.4.1.782.2 bmw de-DE foo.com:234364 http://www.bmw.de/ urn:oid:1.3.6.1.4.1.782.2 Like other CNRP objects, a referral can be further described using custom properties. Specifically, the well known Base Property of 'dataseturi' is used by a referral to disambiguate between two Datasets offered by one Service. 4.2.6 Discoverability: ServiceQuery and Schema A subclass of Query, the ServiceQuery object supports the dynamic discovery of a specific CNRP service's characteristics. Note that CNRP compliance does not require that a service fully implements discoverability. In particular, returning the Service object with its serviceuri constitutes a minimal yet sufficient compliant implementation. Nevertheless, we expect that advanced CNRP services will choose to return a full description of their supported interfaces. The complete response to a servicequery returns the Service object described in section 5.3.2 with the following schema information. 1. The base and custom properties used by the CNRP service (Property schema), 2. The properties used to describe the Service object (Service schema) 3. The properties that belong to the query interface (Query schema) 4. The properties that belong to a resource within the results (Resource schema). Popp, et. al. Expires November 30, 2000 [Page 20] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 These leads to the following new object definitions: o propertyschema -- A property schema describes all the custom properties that are part of the service. o propertydeclaration -- A property declaration describes a base or custom property used by the CNRP service. A property declaration has a name and a type (the name and the type of the property that it refers to). Note that as part of the property schema, one MUST declare both existing and newly defined properties. o propertyreference -- A property reference is a reference to a property declaration so that a given schema (a service, query or resource schema) can declare the property within its interface. Note that a property reference specify whether the use of the property is required or optional only. o serviceschema -- The service schema defines the properties used to describe the service. o queryschema -- A query schema describes the structure of a query handled by the CNRP service. The properties referred within the query schema are part of the query interface of the resolution service. o resourcedescriptorschema -- A ResourceDescriptor schema describes the resource returned as a result by the CNRP service. For example, a CNRP query to discover a service's capabilities will be in the form: And for a CNRP service for cocktail recipes in French, the corresponding response would be: Popp, et. al. Expires November 30, 2000 [Page 21] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 language rfc1766 cocktailrecipe freeform This response stipulates that the service accepts the property language as part of the query interface and returns resourcedescriptors that contain both the language and cocktailRecipe properties. 5. XML DTD for CNRP Popp, et. al. Expires November 30, 2000 [Page 22] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 Popp, et. al. Expires November 30, 2000 [Page 23] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 6. Examples 6.1 Service Description Request This is what the client sends when it is requesting a servers schema. Popp, et. al. Expires November 30, 2000 [Page 24] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 This is the result. Notice how the Service tag is used to allow the service to describe itself in its own terms. urn:foo:bar http://host1.acmecorp.com:4321/foo? smtp://host2.acmecorp.com:4321/foo? This is the AcmeCorp CNRP Service 544554 http://adserver.acmecorp.com/ workgroupID freeform domainname BannerAdServer URI Popp, et. al. Expires November 30, 2000 [Page 25] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 6.2 Sending A Query and Getting A Response This is the query that is sent from the client to the server: Fido CA-QC CA fr-CA This is the result set. It is sent back in response to the query. This result set includes a referral and a non-fatal error. Popp, et. al. Expires November 30, 2000 [Page 26] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 http://acmecorp.com http://serverfarm.acmecorp.com http://servers.acmecorp.co.uk Fidonet 1333459455 http://www.fidonet.ca This is ye olde Canadian Fidonet Fidonet 1333459455 http://host:port/bla The language property 'fr-CA' was ignored 6.3 No Result 6.4 Error Conditions 7. Transport Two CNRP transport protocols are specified. HTTP is used due to its popularity and ease of integration with other web applications. SMTP is also used as a way to illustrate a protocol that has a much different range of latency than most protocols. 7.1 HTTP Transport The HTTP transport is fairly simple. The client connects to an HTTP based CNRP server and issues the POST method with the Content-type and Accept header set to "application/xml". The content of the POST Popp, et. al. Expires November 30, 2000 [Page 27] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 body is the CNRP XML document that is being sent. The results are sent back to the client with a Content-Type of "application/xml". The body of the result is the CNRP XML document being sent to the client. 7.2 SMTP Transport The SMTP transport is very similar to the HTTP transport. Since there is no method to specify, the CNRP XML document is simply sent to a particular SMTP endpoint with its Content-Type set to "application/xml". The server responds by sending a response to the originator of the request with the results in the body and the Content-Type set to "application/xml". 8. Security Considerations Three security threats exist for CNRP or applications that depend on it: Man in the Middle attacks, malicious agents posing as a service by spoofing a Service object, and denial of service attacks caused by adding a new level of indirection for resolution of a resource. The proposed solution for man in the middle attacks is to utilize transport level authentication and encryption where available. In the case where the transport can't provide the level of required authentication, individual entries or the entire response can be signed/encrypted. In the case of where a service attempts to pose as another by spoofing the serviceuri in the Service object, the Service object should be signed. A client can then verify the Service object's veracity by verifying the signature. How the client obtains that authoritative public key is out of scope since it depends on the service discovery problem. While this document cannot propose a solution for Denial Of Service (DOS) attacks it can illustrate that, like many other cases, any time a new level of indirection is created an opportunity for a DOS attack is created. Service providers are encouraged to be aware of this and to act accordingly to mitigate the effects of a DOS attack. 9. IANA Considerations The major consideration for the IANA is that the IANA will be registering well known properties, property types and status messages. It will not register values. Since this document does not discuss CNRP service discovery, the IANA will not be registering the existence of servers or Server objects. Popp, et. al. Expires November 30, 2000 [Page 28] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 There are three types of entities the IANA can register: properties, property types, and status messages. If a property or type is not registered with the IANA then they must start with "x-". Status messages can be created for local consumption and not registered. There is no requirement that new status messages are mandatory to implement unless this document is updated. Status message registrations are more for informational purposes. The required information for the registration of a new property is the property's name, its default type, and a general description. A new type requires the type's name, what properties it is valid for, and a description. A new status message requires the X.Y.ZZZ code and a brief description of the state being communicated. All properties, types and status messages are registered on a First Come First Served basis with no review by the IANA or any group of experts. If, at some future date, this policy needs to change this document will be updated. See Appendix A some example property and type registrations. References [1] United States, "North American Industry Classification System", January 1997. [2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. [3] Berners-Lee, T., Fielding, R.T. and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998. [4] Alvestrand, H., "Tags for the Identification of Languages", RFC 1766, March 1995. [5] Moats, R., "URN Syntax", RFC 2141, May 1997. [6] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, BCP 14, March 1997. [7] Bray, T., Paoli, J. and C. M. Sperberg-McQueen, "Extensible Markup Language (XML) 1.0", February 1998. [8] Mealling, M., "A URI Scheme for the Common Name Resolution Protocol", December 1999. [9] Vaudreuil, G., "Enhanced Mail System Status Codes", RFC 1893, Popp, et. al. Expires November 30, 2000 [Page 29] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 January 1996. [10] "Country and Region Codes", ISO 3166, January 1996. Authors' Addresses Nico Popp RealNames Corporation 2 Circle Star Way, 2nd Floor San Carlos, CA 94070-1350 US Phone: (650) 298 8080 EMail: nico@realnames.com Michael Mealling Network Solutions, Inc. 505 Huntmar Park Drive Herndon, VA 22070 US Phone: (703) 742-0400 EMail: michaelm@netsol.com Marshall Moseley Netword, Inc. 702 Russell Avenue Gaithersburg, MD 20877-2606 US Phone: (240) 631-1100 EMail: marshall@netword.com Appendix A. Appendix A: Well Known Property and Type Registration Templates A.1 Properties Property Name: geography Default Type: iso3166-1 Description: A geographic location Property Name: language Default Type: rfc1766 Description: A language specification Property Name: category Default Type: freeform Description: A node in some system of semantic relationships that is Popp, et. al. Expires November 30, 2000 [Page 30] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 considered relevant to the common-name. Property Name: range Default Type: range Description: A range given in the format "x,y" where x is the starting point and y is the length. This property is used by the client to tell the server that is is requesting a subrange of the results. Property Name: dataseturi Default Type: uri Description: A URI used to disambiguate between two Datasets offered by the same Service. A.2 Types Type: freeform Property: category Description: The value is to be interpreted by the server the best way it knows how. This value has no defined structure. Type: freeform Property: geography Description: The value is to be interpreted by the server the best way it knows how. This value has no defined structure. Type: freeform Property: language Description: The value is to be interpreted by the server the best way it knows how. This value has no defined structure. Type: iso3166-2 Property: geography Description: The combination of country and sub-region codes found in ISO 3166-2[10]. Type: iso3166-1 Property: Geography Description: Country Codes found in ISO 3166-1[10]. Type: postalcode Property: Geography Description: A postal code that is valid for some region. A good example is the Zip code system used in the US. Type: gps Property: Geography Description: A code in the format used by the Global Positioning System. Popp, et. al. Expires November 30, 2000 [Page 31] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 Type: rfc1766 Property: Language Description: language codes as defined by RFC 1766[4] Type: naics Property: Category Description: North American Industry Code System[1] Type: uri Property: dataseturi Description: A URI adhering to the 'absoluteURI' production of the Collected ABNF found in [3] Appendix B. Status Codes B.1 Level 1 (Informative) Codes 1.0.0 -- Undefined Information This code is used for any non-categorizable and informative message. If, for example, the server wanted to tell the client that the systems administrator's cat has blue hair, then this code would be the appropriate place for this information. 1.1.0 -- Query related information This code is used for any informative information concerning the query that client sent. For example, "The query you sent was rather interesting!". 1.2.0 -- An informative message pertaining to the Service This message concerns the Service in the general sense. B.2 Level 2 (Success) Codes 2.0.0 -- Something undefined succeeded There was success but the situation that this message concerns is undefined. 2.1.0 -- Query succeeded The query succeeded. This message MUST be returned when there were no results that matched the query. I.e. the query was successfully handled and the correct set of results contained no resources or referrals. The lack of results is not an error but a successful statement about the common-name. NOTE: The apparent lack of 2.X.X level codes is caused by success usually being indicated not by a status message but by the server returning only the objects that the client requested. B.3 Level 3 (Partial Success) Codes 3.0.0 -- Something undefined was only partially successful Some request by the client was only partially successful. The Popp, et. al. Expires November 30, 2000 [Page 32] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 exact situation or cause of that partial failure is not defined. 3.1.0 -- The query was only partially successful 3.1.1 -- The query contained invalid or unsupported properties The query contained invalid or unsupported property names, types or values. The invalid properties were ignored and the query processed. 3.1.2 -- The XML was well formed but invalid The XML sent by the client was well formed but invalid. The server was smart enough to figure out what the client was talking about and return some results. 3.2.0 -- The server caused a partially successful event Due to some internal server error, the results returned were incomplete. 3.2.1 -- Some referral server was unavailable This status message is used to denote that one or more of the referral services that are normally queried was unavailable. Results were generated but they may not be representative of a complete answer. B.4 Level 4 (Transient Failure) Codes 4.0.0 -- Something undefined caused a persistent transient failure 4.1.0 -- An error in the query caused an error 4.2.0 -- A service error caused a failure The query as specified was too complex for this Service to handle. 4.2.1 -- The Service was too busy Due to resource constraints, the entire service is too busy to handle requests. This means that any of the Servers cooperating in providing this Service would have also returned this same message. 4.2.2 -- The Server is in maintenance This server is now in maintenance mode. Try another server from this service or try again at a later time. B.5 Level 5 (Permanent Failures) Codes 5.0.0 -- Something undefined caused a permanent failure 5.1.0 -- The query permanently failed 5.2.0 -- The service had a permanent failure 5.2.1 -- This Service is no longer available. This Service has decided to no longer make itself available. 5.2.2 -- The Server had a permanent failure This server has permanently failed. Try another server from this service. Popp, et. al. Expires November 30, 2000 [Page 33] Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000 Full Copyright Statement Copyright (C) The Internet Society (2000). 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 implmentation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice 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. Acknowledgement Funding for the RFC editor function is currently provided by the Internet Society. Popp, et. al. Expires November 30, 2000 [Page 34]