Network Working Group N. Popp
Internet-Draft RealNames Corporation
Expires: December 15, 2000 M. Mealling
Network Solutions, Inc.
M. Moseley
Netword, Inc.
June 16, 2000
CNRP PROTOCOL SPECIFICATION
draft-ietf-cnrp-03.txt
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."
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.
This Internet-Draft will expire on December 15, 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 December 15, 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.3.1 Geography . . . . . . . . . . . . . . . . . . . . . . . 10
4.1.3.2 Category . . . . . . . . . . . . . . . . . . . . . . . . 10
4.1.3.3 Common name string encoding and equivalence rules . . . 11
4.1.4 Objects . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1.4.1 Query . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1.4.1.1 Logical operations within a Query . . . . . . . . . . . 11
4.1.4.2 Results . . . . . . . . . . . . . . . . . . . . . . . . 12
4.1.4.2.1 ResourceDescriptor . . . . . . . . . . . . . . . . . . . 13
4.1.4.3 Service . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1.5 Status Messages . . . . . . . . . . . . . . . . . . . . 16
4.1.5.1 Status of CNRP, Not the Transport . . . . . . . . . . . 16
4.1.5.2 Codes and Description . . . . . . . . . . . . . . . . . 16
4.1.5.3 Status Codes . . . . . . . . . . . . . . . . . . . . . . 16
4.1.6 Referral . . . . . . . . . . . . . . . . . . . . . . . . 18
4.1.7 Discoverability: ServiceQuery and Schema . . . . . . . . 18
5. XML DTD for CNRP . . . . . . . . . . . . . . . . . . . . 20
6. Examples . . . . . . . . . . . . . . . . . . . . . . . . 22
6.1 Service Description Request . . . . . . . . . . . . . . 22
6.2 Sending A Query and Getting A Response . . . . . . . . . 24
Popp, et. al. Expires December 15, 2000 [Page 2]
Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000
6.3 No Result . . . . . . . . . . . . . . . . . . . . . . . 25
6.4 Error Conditions . . . . . . . . . . . . . . . . . . . . 25
7. Transport . . . . . . . . . . . . . . . . . . . . . . . 25
7.1 HTTP Transport . . . . . . . . . . . . . . . . . . . . . 25
7.2 SMTP Transport . . . . . . . . . . . . . . . . . . . . . 26
8. Security Considerations . . . . . . . . . . . . . . . . 26
9. IANA Considerations . . . . . . . . . . . . . . . . . . 26
References . . . . . . . . . . . . . . . . . . . . . . . 27
Authors' Addresses . . . . . . . . . . . . . . . . . . . 28
A. Appendix A: Well Known Property and Type Registration
Templates . . . . . . . . . . . . . . . . . . . . . . . 28
A.1 Properties . . . . . . . . . . . . . . . . . . . . . . . 28
A.2 Types . . . . . . . . . . . . . . . . . . . . . . . . . 29
B. Status Codes . . . . . . . . . . . . . . . . . . . . . . 30
B.1 Level 1 (Informative) Codes . . . . . . . . . . . . . . 30
B.2 Level 2 (Success) Codes . . . . . . . . . . . . . . . . 30
B.3 Level 3 (Partial Success) Codes . . . . . . . . . . . . 30
B.4 Level 4 (Transient Failure) Codes . . . . . . . . . . . 31
B.5 Level 5 (Permanent Failures) Codes . . . . . . . . . . . 31
Full Copyright Statement . . . . . . . . . . . . . . . . 32
Popp, et. al. Expires December 15, 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 December 15, 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
discrepencies 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 December 15, 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 reponses
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
knothing 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 names is always UTF-8.
Popp, et. al. Expires December 15, 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 December 15, 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
proposed 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].
Popp, et. al. Expires December 15, 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 property. The abstract property element provides schema
extensibility beyond the core properties. CNRP does not allow for
new objects definition. However, objects are loosely typed, and
existing objects can be augmented using newly defined 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 call the 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 powerful results filtering mechanism.
This is a requirement for large namespaces that contain several
million names. The base properties are defined in Appendix A but
listed here for clarity:
1. Language: The language associated with a resource.
2. Geography: The geographical region or location associated with a
resource.
3. Category: The category associated with a resource.
Popp, et. al. Expires December 15, 2000 [Page 9]
Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000
4. Description: A short text abstract associated with a resource.
5. 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)
6. Dataseturi: An absoluteURI (as defined in [3] that identifies a
defined set of Common Names and associated data.
The language property is expressed using language values as defined
by RFC1766[4].
As custom properties, the "geography", "category" and "language"
properties introduced in the CNRP model can be expressed using many
different value sets. For example, geography can be specified in
terms of a country code, a postal code or in terms of spatial
coordinates. Therefore, for such properties, CNRP introduces a
"type" attribute. To facilitate interoperability, CNRP defines the
main primitive types as well. As previously mentioned, property
types can be extended by a specific service through the definition
of new type values.
The multi-type properties and their types are listed below and
defined in Appendix A:
4.1.3.1 Geography
1. type = "freeform" value = a free form expression for a
geographical location (e.g. "palo alto in california").
2. type = "ISO3166-1" value = a geographical region expressed using
a standard country code as defined by ISO3166-1 (e.g. "US").
3. type = "ISO3166-2" value = a geographical region expressed using
a standard region and country codes as defined by ISO3166-2
(e.g. "US-CA").type = "latitude- longitude-elevation " value =
the latitude, longitude and elevation of a geographical location.
4. type = "GPS" value = a geographical location expressed using the
standard GPS coordinates system (e.g. ???)1
5. type = "LLE" value = a geographical location expressed using the
Latitude-Longitude-Elevation coordinates system (e.g. ???2)
4.1.3.2 Category
1. type = "freeform" value = a free form expression for a category
(e.g. "movies").
2. type = "NAICS" value = The North American Industry Code System.
When the "type" is unspecified, the value defaults to "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 serviced to interpret the value correctly and take
advantage of it to increase the relevance of results (using
Popp, et. al. Expires December 15, 2000 [Page 10]
Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000
specialized dictionaries for instance).
4.1.3.3 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
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.1.4 Objects
4.1.4.1 Query
The Query object encapsulates all the query properties such as
CommonName, ID, language, geography, category, and range. 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.1.4.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:
Popp, et. al. Expires December 15, 2000 [Page 11]
Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000
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.
In addition, for enumerated value types only (e.g. language), 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
enumerated types. 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.1.4.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
Popp, et. al. Expires December 15, 2000 [Page 12]
Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000
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.1.4.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 includes the resourceURI property.
The ResourceDescriptor can also contain the commonname, URI, ID,
description, language, 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.1.4.3 Service
The Service object provides an encapsulation of an instance of a
CNRP service. A service is uniquely identified through the
serviceuri property. A Service object can include a description, 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:
Popp, et. al. Expires December 15, 2000 [Page 13]
Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000
http://cnrp.foo.com
companies
FR
The service object also encapsulates a list of server objects. The
server object is used to describe a CNRP server (or a cluster 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 be further described using existing properties. For
example, the following example defines two clusters of CNRP servers
one in the US and one in France.
http://cnrp.foo.com
http://router.us.widgetco.com:4321/foo?
US
http://router.fr.acmeco.com:4321/foo?
FR
As we will see in a following section, the Service object can
contain the 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.1.7).
Another use of Service is for other objects to indicate their CNRP
Popp, et. al. Expires December 15, 2000 [Page 14]
Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000
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.
An example of hybrid result sets with resourcedescriptors
referencing their service of origin and dataset is given below:
http://acmecorp.com
urn:oid:1.2.3.4.666.5.4.3.1
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
urn:oid:1.2.3.4.666.5.4.3.1
Popp, et. al. Expires December 15, 2000 [Page 15]
Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000
Fidonet
1333459455
http://host:port/bla
urn:oid:1.2.3.4.666.10.9.8.7.6
4.1.5 Status Messages
NOTE: This section is still under review by the working group.
changes are expected.
4.1.5.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.
4.1.5.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.1.5.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:
Popp, et. al. Expires December 15, 2000 [Page 16]
Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000
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.
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
Popp, et. al. Expires December 15, 2000 [Page 17]
Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000
4.1.6 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.
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.1.7 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
Popp, et. al. Expires December 15, 2000 [Page 18]
Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000
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).
These leads to the following new objects 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 December 15, 2000 [Page 19]
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 December 15, 2000 [Page 20]
Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000
Popp, et. al. Expires December 15, 2000 [Page 21]
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 December 15, 2000 [Page 22]
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 December 15, 2000 [Page 23]
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 December 15, 2000 [Page 24]
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
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
Popp, et. al. Expires December 15, 2000 [Page 25]
Internet-Draft CNRP PROTOCOL SPECIFICATION June 2000
and Accept header set to "application/xml". The content of the POST
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 December 15, 2000 [Page 26]
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 December 15, 2000 [Page 27]
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
Paramater 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 December 15, 2000 [Page 28]
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 December 15, 2000 [Page 29]
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 adhereing 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 December 15, 2000 [Page 30]
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 December 15, 2000 [Page 31]
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 December 15, 2000 [Page 32]