have been queried. It is up to the client to decide what to do with
these messages and how closely it attempts to do loop detection.
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).
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:
<cnrp> <servicequery/> </cnrp>
And for a CNRP service for cocktail recipes in French, the
corresponding response would be:
<service>
<serviceuri>http://cnrp.recipe.com</serviceuri>
<propertyschema>
<propertydeclaration id="i1">
<propertyname>language</propertyname>
<propertytype>rfc1766</propertytype>
</propertydeclaration>
<propertydeclaration id="i2">
<propertyname>cocktailrecipe</propertyname>
<propertytype>freeform</propertytype>
</propertydeclaration>
</propertyschema>
<queryschema>
<propertyreference required="yes" ref="i1"/>
</queryschema>
<resourcedescriptorschema>
<propertyreference required="yes" ref="i1"/>
<propertyreference required="yes" ref="i2"/>
</resourcedescriptorschema>
</service>
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
<!-- The document tag -->
<!ELEMENT cnrp (query|results|servicequery)>
<!-- Used to request a Service object -->
<!ELEMENT servicequery EMPTY>
<!-- A query can either request a schema, a specific record by -->
<!-- id, or a common-name with a set of properties (or -->
<!-- assertions) about the entity doing the query. -->
<!ELEMENT query (id|(commonname,property*))>
<!ELEMENT id (#PCDATA)>
<!ELEMENT commonname (#PCDATA)>
<!-- NOTE: CNRP defines several well known properties -->
<!-- and types. See Appendix A for details. -->
<!ELEMENT property (#PCDATA)>
<!-- The name of the property -->
<!ATTLIST property name CDATA #REQUIRED>
<!-- The type of the property -->
<!ATTLIST property type CDATA "freeform">
<!ELEMENT results (status? |
( service+,
( status | resourcedescriptor | referral )*
)*
)>
<!ELEMENT resourcedescriptor (commonname,id,resourceuri,
serviceref, datasetref?,
description,
property*)>
<!ATTLIST resourcedescriptor id ID #IMPLIED>
<!-- The entire point of all this... -->
<!ELEMENT resourceuri (#PCDATA)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT referral (serviceref, datasetref?)>
<!ATTLIST referral id ID #IMPLIED>
<!ELEMENT status (#PCDATA)>
<!ATTLIST status code CDATA #REQUIRED>
<!ATTLIST status ref IDREF #IMPLIED>
<!-- serviceRef is used to point to one of a set of provided -->
<!-- service objects. This is so that a resource can point to -->
<!-- which service it came from. We could include the entire -->
<!-- service object but then we would be repeating large -->
<!-- amounts of information. -->
<!ELEMENT serviceref EMPTY>
<!ATTLIST serviceref ref IDREF #IMPLIED>
<!ELEMENT service (serviceuri, dataset*,
servers?,
description?,
property*,propertyschema?,queryschema?,resourcedescriptorschema?,
serviceschema?)>
<!-- The time to live of the schema in seconds since it was -->
<!-- retrieved -->
<!ATTLIST service ttl CDATA "0">
<!ATTLIST service id ID #IMPLIED>
<!ELEMENT serviceuri (#PCDATA)>
<!ELEMENT servers (server+)>
<!ELEMENT server (serveruri, property*)>
<!ELEMENT serveruri (#PCDATA)>
<!ELEMENT dataset (property*)>
<!ATTLIST dataset id ID #IMPLIED>
<!ELEMENT datasetref EMPTY>
<!ATTLIST datasetref ref IDREF #IMPLIED>
<!ELEMENT propertyschema (propertydeclaration*)>
<!ELEMENT propertydeclaration (propertyname, propertytype*)>
<!ATTLIST propertydeclaration id ID #IMPLIED>
<!ELEMENT propertyname (#PCDATA)>
<!ELEMENT propertytype (#PCDATA)>
<!-- This specifies if the type is meant to be the default -->
<!-- type. This is usually reserved for "freeform". -->
<!ATTLIST propertytype default (no|yes) "no">
<!-- The properties you can use in a query -->
<!ELEMENT queryschema (propertyreference*)>
<!-- The properties you can expect to see in an Resource -->
<!ELEMENT resourcedescriptorschema (propertyreference*)>
<!-- The properties you can expect to find in a Service -->
<!-- definition -->
<!ELEMENT serviceschema (propertyreference*)>
<!ELEMENT propertyreference EMPTY>
<!-- This specifies if a property is required as part of -->
<!-- the query. -->
<!ATTLIST propertyreference ref IDREF #REQUIRED>
<!ATTLIST propertyreference required (no|yes) "no">
6. Examples
6.1 Service Description Request
This is what the client sends when it is requesting a servers schema.
<?xml version="1.0"?>
<!DOCTYPE cnrp PUBLIC "-//IETF//DTD CNRP 1.0//EN"
"http://ietf.org/dtd/cnrp-1.0.dtd">
<cnrp>
<servicequery />
</cnrp>
This is the result. Notice how the Service tag is used to allow the
service to describe itself in its own terms.
<?xml version="1.0"?>
<!DOCTYPE cnrp PUBLIC "-//IETF//DTD CNRP 1.0//EN"
"http://ietf.org/dtd/cnrp-1.0.dtd">
<cnrp>
<results>
<service ttl="43200">
<serviceuri>urn:foo:bar</serviceuri>
<servers>
<server>
<serveruri>http://host1.acmecorp.com:4321/foo?</serveruri>
</server>
<server>
<serveruri>smtp://host2.acmecorp.com:4321/foo?</serveruri>
</server>
</servers>
<description>This is the Acme CNRP Service</description>
<!-- This property means that Acme specializes in
tradename services -->
<property name="category" type="naics">544554</property>
<property name="BannerAdServer" type="uri">
http://adserver.acmecorp.com/
</property>
<propertyschema>
<propertydeclaration id="i1">
<propertyname>workgroupID</propertyname>
<propertytype default="yes">freeform</propertytype>
<propertytype default="no">domainname</propertytype>
</propertydeclaration>
<propertydeclaration id="i2">
<propertyname>BannerAdServer</propertyname>
<propertytype default="yes">URI</propertytype>
</propertydeclaration>
</propertyschema>
<queryschema>
<propertyreference ref="i1" required="yes" />
</queryschema>
<resourcedescriptorschema>
<propertyreference ref="i1" required="yes" />
</resourcedescriptorschema>
<serviceschema>
<propertyreference ref="i2" required="yes" />
</serviceschema>
</service>
</results>
</cnrp>
6.2 Sending A Query and Getting A Response
This is the query that is sent from the client to the server:
<?xml version="1.0"?>
<!DOCTYPE cnrp PUBLIC "-//IETF//DTD CNRP 1.0//EN"
"http://ietf.org/dtd/cnrp-1.0.dtd">
<cnrp>
<query>
<commonname>Fido</commonname>
<property name="geography" type="iso3166-2">
CA-QC</property>
<property name="geography" type="iso3166-1">CA</property>
<property name="language" type="rfc1766">fr-CA</property>
</query>
</cnrp>
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.
<?xml version="1.0"?>
<!DOCTYPE cnrp PUBLIC "-//IETF//DTD CNRP 1.0//EN"
"http://ietf.org/dtd/cnrp-1.0.dtd">
<cnrp>
<results>
<service id="i0">
<serviceuri>http://acmecorp.com</serviceuri>
</service>
<service id="i1">
<serviceuri>http://serverfarm.acmecorp.com</serviceuri>
</service>
<service id="i2">
<serviceuri>http://servers.acmecorp.co.uk</serviceuri>
</service>
<resourcedescriptor>
<commonname>Fidonet</commonname>
<id>1333459455</id>
<resourceuri>http://www.fidonet.ca</resourceuri>
<serviceref ref="i0" />
<description>This is ye olde Canadian Fidonet</description>
</resourcedescriptor>
<resourcedescriptor>
<commonname>Fidonet</commonname>
<id>1333459455</id>
<resourceuri>http://host:port/bla</resourceuri>
<serviceref ref="i1" />
<description>An old Fidonet node</description>
</resourcedescriptor>
<referral><serviceref ref="i2" /></referral>
<status code="3.1.1">
The language property 'fr-CA' was ignored
</status>
</results>
</cnrp>
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.
In the cases where transports use MIME Media Types (HTTP and SMTP
being examples of such), the CNRP payload MUST use the
'application/cnrp+xml' media type. See Section 8 for the
registration template for this media type. One important note about
this media type is that, since CNRP always uses UTF-8, there is no
charset attribute.
7.1 HTTP Transport
The HTTP transport is fairly simple. The client connects to an HTTP
based CNRP server and issues a request using the POST method to the
"/" path with the Content-type and Accept header set to
"application/cnrp+xml". The content of the POST body is the CNRP XML
document that is being sent. All HTTP 1.1 features are allowed
during the request.
The results are sent back to the client with a Content-Type of
"application/cnrp+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/cnrp+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/cnrp+xml". The Service MUST specify
at least one SMTP target (email address) to contact.
8. Registration: application/cnrp+xml
This is the registration template for 'application/cnrp+xml' per [6].
MIME media type name: application
MIME subtype name: cnrp+xml
Required parameters: none
Optional parameters: none
Encoding considerations: This media type consists of 8bit text which
may necessitate the use of an appropriate content transfer
encoding on some transports. Since these considerations are the
same as XML in general, RFC3023's [6] discussion of XML and MIME
is applicable.
Security considerations: none specific to this media type. See
Section 9 for general CNRP considerations.
Interoperability considerations: n/a
Published specification: This media type is a proper subset of the
the XML 1.0 specification [8] except for the limitations placed on
tags and encodings by this document.
Applications which use this media type: any CNRP client/server
wishing to send or receive CNRP requests or responses
Additional Information: none
Contact for further information: c.f., the "Author's Address" section
of this memo
Intended usage: limited use
Author/Change controller: the IESG
9. 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 using XML signature methods being developed by the
XMLDSIG Working Group.
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.
10. 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.
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. The consensus opinion of the CNRP Working Group is that
review of property registrations should occur once there is
operational experience with the protocol and an actual need for the
review. If, at some future date, this policy needs to change, this
document will be updated.
The property and type registration templates found in Appendix A
should be registered by the IANA at publication time of this
document.
The IANA is also directed to register the Media Type specified in
Section 8.
References
[1] United States, "North American Industry Classification System",
January 1997, <http://www.census.gov/epcd/www/naics.html>.
[2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L.,
Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol --
HTTP/1.1", RFC2616, June 1999.
[3] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
Resource Identifiers (URI): Generic Syntax", RFC2396, August
1998.
[4] Alvestrand, H., "Tags for the Identification of Languages", RFC
1766, March 1995.
[5] Moats, R., "URN Syntax", RFC2141, May 1997.
[6] Murata, M., St. Laurent, S. and D. Kohn, "XML Media Types", RFC
3023, January 2001.
[7] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC2119, March 1997.
[8] Bray, T., Paoli, J. and C. Sperberg-McQueen, "Extensible Markup
Language (XML) 1.0", February 1998.
[9] Mealling, M., "The 'go' URI Scheme for the Common Name
Resolution Protocol", RFC3368, August 2002.
[10] Vaudreuil, G., "Enhanced Mail System Status Codes", RFC1893,
January 1996.
[11] "Country and Region Codes", ISO 3166, January 1996.
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
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 [11].
Type: iso3166-1
Property: Geography
Description: Country Codes found in ISO 3166-1 [11].
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: lat-long
Property: Geography
Description:
Values for latitude and longitude shall be expressed as decimal
fractions of degrees. Whole degrees of latitude shall be
represented by a two-digit decimal number ranging from 0 through
90. Whole degrees of longitude shall be represented by a decimal
number ranging from 0 through 180. When a decimal fraction of a
degree is specified, it shall be separated from the whole number
of degrees by a decimal point. Decimal fractions of a degree may
be expressed to the precision desired.
Latitudes north of the equator shall be specified by a plus sign
(+), or by the absence of a minus sign (-), preceding the
designating degrees. Latitudes south of the Equator shall be
designated by a minus sign (-) preceding the two digits
designating degrees. A point on the Equator shall be assigned to
the Northern Hemisphere.
Longitudes east of the prime meridian shall be specified by a plus
sign (+), or by the Longitudes west of the meridian shall be
designated by minus sign (-) preceding the digits designating
degrees. A point on the prime meridian shall be assigned to the
Eastern Hemisphere. A point on the 180th meridian shall be
assigned to the Western Hemisphere. One exception to this last
convention is permitted. For the special condition of describing
a band of latitude around the earth, the East Bounding Coordinate
data element shall be assigned the value +180 (180) degrees.
Any spatial address with a latitude of +90 (90) or -90 degrees
will specify the position at the North or South Pole,
respectively. The component for longitude may have any legal
value.
With the exception of the special condition described above, this
form is specified in Department of Commerce, 1986, Representation
of geographic point locations for information interchange (Federal
Information Processing Standard 70-1): Washington, Department of
Commerce, National Institute of Standards and Technology.
DEGREES = *PLUSMINUS DIGITS '.' DIGITS
PLUSMINUS = + | -
DIGITS = DIGIT *DIGIT
DIGIT = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
Type: rfc1766
Property: Language
Description: language codes as defined by RFC1766 [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
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.1.3 Server does not support datasets
This status should be generated by servers that do not handle
datasets. A server can send this status message at any time, but
it especially useful for when a server receives a query from a
client that contains a dataseturi. In this case and if the client
is doing rigorous loop detection, the client should consider this
entire service to have been visited.
3.1.4 The first dataset in the list of datasets you gave in the
query was the only one used.
This status message is used by a server to indicate the situation
where a client has included several dataseturis in its query and
the server can only support one at a time. In this case the
server is explicitly stating that it used the first dataseturi
only. The client should consider that only the first dataseturi
specified was processed correctly. The client should consider
that the remaining datasets in the query were ignored completely.
They would need to be sent individually as referrals if the client
really cares about those results. Only the first
serviceuri/dataseturi pair should be marked as visited if loop
detection is being handled.
3.1.5 This dataset not supported.
This message is used to indicate that a specific dataseturi sent
in a query by a client is not supported by the server. This
serviceuri/dataseturi pair should be considered as visited by the
client. If this message is sent in reply to a query specifying
multiple datasets, the client should behave the same as if it
received the 3.1.3 message from above. It should be considered
bad form for a server to send this status message back in response
to a query with multiple datasets because it is ambiguous.
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 -- There was an error in the query that made it unable to be
interpreted.
4.2.0 -- The query was to complex
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.
4.2.3 -- The Server had an internal error
There was an internal error that caused the server to fail
completely.
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.
Authors' Addresses
Nico Popp
VeriSign, Inc.
487 East Middlefield Road
Mountain View, CA 94043
Phone: (650) 426-3291
EMail: npopp@verisign.com
Michael Mealling
VeriSign, Inc.
21345 Ridgetop Circle
Sterling, VA 20166
US
EMail: michael@verisignlabs.com
Marshall Moseley
Netword, Inc.
702 Russell Avenue
Gaithersburg, MD 20877-2606
US
Phone: (240) 631-1100
EMail: marshall@netword.com
Full Copyright Statement
Copyright (C) The Internet Society (2002). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice 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 RFCEditor function is currently provided by the
Internet Society.