Network Working Group                                        Keith Moore
Internet-Draft                                   University of Tennessee
19 July 2001
Expires: 19 January 2002


                          The Resource Catalog

                      draft-moore-rescap-rc-01.txt

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.

Comments regarding this internet-draft should be sent to the mailing
list of the IETF rescap working group.  Refer to the IETF web site at
http://www.ietf.org/ for current contact information for IETF working
groups.  Please include the document identifier
"draft-moore-rescap-rc-01" in any comments regarding this document.

Abstract

This memo describes version 3 of the Resource Catalog.  The Resource
Catalog (RC) is a service for storing and obtaining metadata that
describes network-accessible resources.  This service is primarily
intended for use by clients prior to accessing, or attempting to access,
a particular resource.  The RC service may thus be used (for example) to
inform a client as to which of a variety of features are supported by
the resource, or which methods may be used to access the resource, or
which of a small set of locations may be used to access the resource.







Moore                    Expires 19 January 2002                [Page 1]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


1. Introduction

This memo describes version 3 of the Resource Catalog.  The Resource
Catalog is a service for storing and obtaining metadata that describes
network-accessible resources.   This service is primarily intended for
use by clients prior to accessing, or attempting to access, a particular
resource.  The RC service may thus be used (for example) to inform a
client as to which of a variety of features are supported by the
resource, or which methods may be used to access the resource, or which
of a small set of locations may be used to access the resource.

A 'network-accessible resource' is potentially any resource which is
accessible on the network and which has a distinguished name (probably a
URI) by which the metadata can be queried.  Such resources could
potentially include downloadable files, web pages, electronic mailboxes
(including voice and fax mailboxes), instant messaging mailboxes, real-
time text, voice, and/or video conferencing terminals, hosts, routers,
etc.  'Metadata' are represented as name-value pairs, each of which
describes some aspect of the resource.

NB:  The above examples of resources are intended only as illustration
of the flexibility of this approach. It is not expected that RC would,
if adopted, be used in all of these contexts (or for that matter, in any
particular context.)  Each application or service using RC as a
component would need to have an explicit definition for the metadata and
specific use of RC within that application or service, prior to
deployment of code.

Earlier versions of the Resource Catalog were designed for use in
research projects dealing with replicating network-accessible content
and distributed software repositories.  This version of the Resource
Catalog builds on experience with those earlier efforts, and is intended
to be suitable for standardization and widespread deployment.

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 [1].

2. Design Goals and Implications

Given the overall intended purpose of the service as described above
(and in the charter of the rescap working group) RC version 3 was
designed with several specific goals in mind.  These are reflected in
the protocol design as follows:







Moore                    Expires 19 January 2002                [Page 2]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


2.1. Federation

Ideally, the owner of a resource being described should be able to
control the metadata used to describe that resource within RC.  Such
control would be hampered if RC were a centralized service; this would
also impact RC's scalability.  It is therefore desirable for the owner
to be able to control both the cost and the quality of the RC service
which describes his/her/its resources.

The RC service is therefore federated according to resource name; it is
assumed that the network addresses of the servers that provide
authoritative metadata describing a particular named resource are
somehow obtainable from that name.  RC uses NAPTR [2] and SRV [3]
records to locate the RC servers for URIs which contain embedded DNS
names.  Similar mechanisms would need to be defined for other kinds of
resource names (as for instance the URN working group is defining
resolution mechanisms for URNs, and the ENUM working group is currently
defining a means of finding metadata associated with telephone numbers).

This approach further allows the maintainer of a DNS zone to specify the
locations of RC services for resource names for which the SRV records
are located in that zone; thus, the RC servers corresponding to a
particular resource name can be provided locally, outsourced, or some of
each.  This further implies that "RC service provider" and "resource
owner" are different roles, and that the capability to manipulate
resource attributes must therefore be delegated to the resource owner
through a standard interface.

The need to be able to outsource RC services also implies that an RC
query must self-contained, i.e. that no part of the question being asked
is implicit in the choice of a server to which the question is being
presented.

It is of course likely that the owner of a resource does not control all
of the DNS zones which are traversed in the process of finding the RC
servers for a resource name.  And while it is hoped that DNS names will
continue to be easily obtainable and inexpensive, some kinds of resource
names (such as URNs) inevitably lessen owner control of the resource
name in order to obtain increased stability of those names.  For this
reason, and because the RC service provider may be independent of the
resource owner, RC provides the capability for resource owners to
digitally sign any of the metadata associated with a resource.

2.2. Fast response to client queries

As RC is intended for use prior to accessing a resource, RC queries will
tend to increase the overall time required to access that resource.  It
is therefore essential that RC provide fast response.  This implies that



Moore                    Expires 19 January 2002                [Page 3]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


server operations should be cheap in terms of CPU cycles.  It further
implies (in the case of low bandwidth links) that payloads and protocol
overhead are small and (in the case of long delay links) that
unnecessary round-trips are avoided.

To this end, RC queries are designed to run over UDP and to require a
single UDP datagram in each direction.  Servers may also support TCP as
a transport.  RC is also optimized for small payloads, and it attempts
to impose minimal protocol overhead.  RC also provides a number of
features designed to minimize the transmission of unnecessary response
data, including the ability to query several named attributes in a
single transaction, and the ability to specify whether signatures (and
which types of signatures) should be returned with the response.

2.3. Scalability to large numbers of reading clients

If RC is used to provide essential metadata for heavily-used resources
it potentially imposes a barrier to access of those resources.  The
scalability of access to those resources would thus be limited by the
scalability of RC.  It is therefore necessary that RC be scalable to
handle large numbers of reading clients.   RC attempts to achieve this
by being implementable with minimal server overhead, and by allowing RC
queries to be distributed over several replicated RC servers, with a
well-defined model for consistency between servers.

2.4. Ease of implementation

In order to allow for quick deployment, the RC protocol is designed to
be simple and easy to implement, and for simple implementations to
perform acceptably on modern CPUs with moderate workloads.  However it
is naturally expected that high performance implementations will be more
complex and more difficult to implement.

2.5. Security

RC is designed with consideration of the following security threats:

-    Attempts by unauthorized parties to write metadata to servers.

     RC servers require writers (and optionally readers) to authenticate
     themselves via secure means; such requests will not be processed
     unless the authentication credentials can be verified.

-    Attempts to obtain authentication credentials via the network, via
     active or passive attacks.

     The RC protocol allows for multiple authentication methods in order
     to accommodate the needs of different environments, and to



Moore                    Expires 19 January 2002                [Page 4]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


     accommodate additional authentication methods which might be
     defined in the future.  The specific methods are to be determined,
     but will be chosen to minimize the risk of disclosing
     authentication credentials to eavesdroppers and active attackers,
     and/or to make such exposure computationally infeasible.

-    Attempts to replay a previously successful write request for the
     purpose of modifying metadata in unauthorized ways.

     Requests to update metadata include a serial number which must
     always be larger than the serial number of the previous request to
     update the metadata for that resource.  This serial number is
     authenticated and checked for integrity along with the rest of the
     request.  Attempts to replay write requests can therefore be
     detected, and unauthorized changes to the metadata avoided.

-    Attempts to substitute unauthorized or altered data in a response

     RC allows (but does not require) writers to cryptographically sign
     metadata that are stored in a server.  Reading clients may (but are
     not required to) request such signatures, attempt to verify them,
     and determine whether the party signing the metadata is authorized
     to make such assertions about the resource.  However such
     signatures are opaque to RC servers; the RC protocol does not
     attempt to verify signatures that are stored with a resource.

     When TLS [4] is used, the integrity protection provided by TLS will
     allow a client to detect responses altered in transit.  However
     there is no requirement that TLS be used; furthermore, the protocol
     setup and server CPU overhead associated with TLS serve as
     disincentives to use of TLS.

-    Alteration or deletion of unsigned data in responses, or addition
     of unsigned data to responses

     TLS may be used to protect the integrity of communications between
     client and server; however support for TLS is optional.  When TLS
     is not used, an active attacker might be able to introduce fake
     responses to queries, or to alter the authoritative server's
     responses to queries.

     A specific application using RC can require that the metadata used
     by the application be signed by a party authorized to make
     assertions about the resource.

-    Removal of signatures from responses





Moore                    Expires 19 January 2002                [Page 5]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


     When TLS is used, the integrity protection provided by TLS will
     allow a client to detect responses altered in transit.  However
     there is no requirement that TLS be used and there are
     disincentives to use TLS.

     NOTE: The protocol described in this document, could, with a very
     small modification, allow clients to request server-provided
     signatures on responses.  Such signatures would not authenticate
     the response as coming from an authoritative source, but would
     serve to thwart this and other attacks that alter responses.  If
     used frequently, such a facility would greatly increase server
     load, but probably no worse than if TLS were used frequently.
     Furthermore, as long as server signatures were optional, an
     attacker capable of modifying a response could presumably also
     modify a request to remove the request for a server signature.

RC does not attempt to ameliorate the following threats:

-    Attempts to direct clients to send queries to unauthorized servers

     Even if unauthorized servers contain data which are signed by
     authoritative sources, the data provided by unauthorized servers
     may be stale or obsolete.

     When DNS SRV and address records are used to direct queries to RC
     servers, DNSSEC may be useful in authenticating such records to
     clients.

     NOTE: TLS server certificates could be used by the client to
     determine whether the server can authentically claim to operate on
     behalf of a particular DNS name.  However, authority to operate on
     behalf of a DNS name does not necessarily imply authority to supply
     information about a resource name, particularly when the server
     operator may not be authoritative to make assertions about a
     particular resource, even if the server is the correct one to
     consult for information about that resource.  (e.g. the RC service
     might be outsourced)

-    Repudiation of unsigned assertions

-    Alteration of unsigned responses

-    Threats which require physical access to server hardware

-    Attempts to interfere with service by interfering with the
     transmission of requests or responses over the network





Moore                    Expires 19 January 2002                [Page 6]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


-    Attempts to interfere with service by flooding the server with
     requests

2.6. Provision for proxies

Due to the large number of environments which separate local users from
the public Internet with firewalls, and the anticipated use of this
protocol to describe public Internet resources, it is essential that RC
be usable through intermediaries.

2.7. Flexibility

RC is intended as a framework which can be used by a wide variety of
applications and services, to store information about many different
kinds of resources.  The protocol therefore needs to be flexible enough
to accommodate different applications' needs regarding (for instance)
metadata size, rates of change, and security.

The feature-set included in RCv3 was selected based on observations from
other information query protocols which have been in use for many years,
as well as experience with earlier versions of RC.

DNS  Though the resemblance may not be obvious, in many ways RC is
     heavily influenced by DNS [5].  Like DNS, RC is federated, handles
     multiple query types, and provides the ability to return
     "additional information" in response to a query.  In addition, and
     both RC and DNS provide signatures, with the capability to support
     multiple signature types. RC and DNS have similar models for
     replication, with the RC replication granularity being that of a
     resource name and the DNS replication granularity being that of a
     zone.

     However, RC attempts to generalize a number of DNS features.  In
     particular, RC servers have no knowledge of the characteristics of
     attribute names (corresponding to DNS resource record types and
     query types).  RC servers determine whether to perform "additional
     information" lookups based on explicit instructions in the query,
     rather than based on knowledge of the attribute name.  Neither do
     RC servers have knowledge of signature types; signatures are opaque
     to the servers. Server processing of signatures in RC is limited to
     storing signatures that are supplied by writers and returning
     signatures to readers who ask for them.  Finally, RC decouples the
     notion of "server ownership" from "resource name ownership" - the
     owner of the server is not inherently considered an authoritative
     source of information about any particular resource.

SNMP In some ways the service provided by RC is similar to that of an
     SNMP [6] agent.  In particular, RC borrows from SNMP the capability



Moore                    Expires 19 January 2002                [Page 7]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


     to query aggregates of individually addressable resource
     attributes, where the aggregates are based on the structure of the
     names.  However whereas SNMP uses ASN.1 object-identifiers (OIDs)
     for attribute names, RC uses human-readable ASCII strings.  RC also
     separates resource names from attribute names rather than combining
     the two into a single name.  Finally, RC lacks an analog to SNMP's
     trap mechanism, RC's information model is simpler than SNMP's SMI,
     and RC uses a simple presentation layer and RPC mechanism in
     contrast to SNMP's ASN.1 PDUs.

LDAP RC is heavily influenced by LDAP [7] in that RC avoids many of the
     design choices in LDAP which impose a barrier to the use of LDAP in
     applications for which RC is designed.  In particular,

     -    RC allows the use of UDP to avoid the delay and bandwidth
          consumption associated with TCP connection setup

     -    RC uses a simpler data model than ASN.1, and a simpler
          presentation encoding than BER, for ease of implementation and
          improved processing efficiency

     -    RC provides lookup by resource name, but not searching of
          contents, for server efficiency and scalability

     -    RC provides the ability to query for and return "additional
          information" based on results of the initial query, thus
          avoiding multiple round-trips

     -    RC has support for caching of data returned from queries

     -    RC defines a model for consistency between replicas which is
          usable by applications

3. Data Model

3.1 Format of resource descriptions

RC models the description of a resource (its "metadata") as a set of
(name, value) pairs called assertions.  Each assertion consists of:

-    an attribute name, which is a human-readable character string;

-    a value, which is often human-readable, but can potentially be any
     sequence of octets;

-    an optional time-to-live; and





Moore                    Expires 19 January 2002                [Page 8]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


-    an optional expiration-date.

The time-to-live is some number of seconds from the present time during
which the assertion is expected to remain valid.  The expiration-date is
an absolute time at which the assertion will no longer be valid.  Both
time-to-live and expiration-date may be supplied, in which case both
limitations to the validity of the assertion apply.

3.1 Caching

Intermediaries (e.g. proxies) MAY cache assertions and return cached
assertions in response to queries for specific resource_names during the
expected lifetime of the assertions.  However, all cached assertions
about a resource_name which are returned in a query response MUST have
been obtained from the same version of the description of that resource.
Intermediaries MUST NOT return cached responses to wildcard queries
unless those responses were returned from an earlier wildcard query of
greater or equal scope (i.e. a shorter prefix of the resource name) than
the current query.

3.2 Consistency between replicas

RC services for a particular portion of URI-space MAY be replicated so
that queries, updates, or other operations within that portion of URI-
space can be issued to any of the replicas.  A standard mechanism for
replication between servers is not yet defined, but individual
implementations MAY define their own mechanisms for doing so.

When the description of a resource is replicated between RC servers, the
servers MUST maintain the appearance of a linear change history for the
entire resource description across all of the servers.  In other words,
it is not acceptable for separate changes to be made to different
replicas of the resource description.  Servers MAY impose requirements
on writers in order to facilitate this (e.g. they may require that all
updates be sent to a single master server).

Replicated RC servers SHOULD make reasonable efforts to be synchronized
with one another.

3.3 Permission model

RC is intended for the dissemination of public information.  It is
possible for servers to refuse to answer queries sent by non-
authenticated parties or to specific parties who authenticate
themselves, and it is possible for servers to omit information from the
responses of queries sent by unauthorized parties.  Until the effect of
such restrictions on caching is understood, servers SHOULD NOT restrict
the ability of parties to query information.



Moore                    Expires 19 January 2002                [Page 9]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


RC servers which support the Update operation MUST be able to prevent
unauthorized parties from updating information about a particular
resource; however, the granularity with which this is done is not
defined.  Servers MAY restrict the ability to update particular resource
names, as well as particular attribute names.  However, perhaps
unfortunately, the currently defined status reporting mechanism provides
little information about why an update attempt failed.

4. Protocol

The protocol is defined in terms of RPC operations.  Each operation is
defined in terms of an request structure, result structure, and side-
effects that take place when a valid request is received.  The
structures are defined using the example abstract syntax from the Binary
Low-Overhead Block (BLOB) protocol [8], and BLOB is used as a
presentation format.

4.1 Operations

The following operations are defined:

4.1.1 Query operation

The Query operation returns information describing the named resource.

4.1.1.1 Query request structure

The Query request structure is defined as follows:

     BEGIN query_request
     int request_type               # QUERY=0
     string request_id
     string resource_name
     string<> attribute_names
     int<> attribute_flags
     # QUERY_RECURSE = 01
     # WANT_SIGNATURES = 02
     int<> signature_types
     END

The meanings of the individual fields are outlined below.

request_type
     A request_type of 0 indicates a Query request.

request_id
     The request_id is used to associate the response with the request.
     This is a string which is chosen to be unique for the client's IP



Moore                    Expires 19 January 2002               [Page 10]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


     address and port pair, for any amount of time during which any
     request from that host and port pair is likely to be pending or
     during which a response may be traveling through the network. It is
     RECOMMENDED that request_ids not be reused within at least an hour.

     The contents of the request_id are otherwise undefined; client
     implementations MAY generate them however they wish.  (however see
     the Security Considerations section).

resource_name
     The name of the resource for which information is being requested;
     for instance, a URI.  This field MUST be present.

attribute_names, attribute_flags
     These fields are parallel arrays.  attribute_names specifies the
     names of the attributes which are being requested for the resource,
     while attribute_flags specifies optional query features desired for
     each attribute_name.  attribute_flags[i] thus specifies the
     optional query features for attribute_names[i].  These two arrays
     MUST have the same number of elements, and servers MUST return an
     RC_DATA_FMT error in response to a Query operation for which the
     number of elements in these two arrays is different.

     Currently defined attribute_flags are as follows:

     -    The QUERY_RECURSE flag controls searching for additional
          information; see section 3.1.1.1 below.

     -    The WANT_SIGNATURES bit requests signatures for this
          attribute; see section 3.1.1.2 for a discussion of signatures.

     Note: as hinted in section 2.5, a WANT_SERVER_SIGNATURE bit could
     be added here to request that the server sign the response.  This
     would provide some protection against attacks that modify the
     response but would not by itself guarantee that the response came
     from an authoritative party.

     An attribute_name that ends in "*" is a wildcard; see section
     4.1.1.8.

signature_types
     The list of signature_types which are understood by the caller.
     Values for individual signature_types are to be defined.








Moore                    Expires 19 January 2002               [Page 11]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


4.1.1.2 Query result structure

The Query result structure is as follows:

     BEGIN query_result
     string request_id
     struct<> answers
     END


request_id
     This is the request_id from the Query structure, used to associate
     the response with the request.

answers
     The list of answers.  Each answer contains the results of the query
     for a particular resource_name.  The first answer is the one for
     the resource_name which was explicitly part of the Query structure.
     Any additional answers are the result of additional queries
     requested via the QUERY_RECURSE flag.

4.1.1.3 Answer structure

Each Answer is formatted as a blob using the following structure:

     BEGIN answer
     string resource_name
     int query_status
     int version_hi
     int version_lo
     struct<> assertions
     struct<> signatures
     END

Within an answer are the following fields:

resource_name
     The resource_name for which the following assertions are made.

query_status
     A code describing the result of the attempt to query this
     resource_name.  See section 3.5.

version_hi, version_lo
     An 8-byte version number (treated as a single 8-byte integer, but
     represented for the purpose of presentation as two 4-byte integers)
     for the resource information.  The version number increases (not
     necessarily by 1) each time the resource is modified.



Moore                    Expires 19 January 2002               [Page 12]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


assertions
     This is an array of blobs, each of which contains information about
     the named resource.  The structure of an assertion is defined
     below.

signatures
     This is an array of blobs, each of which contains a signature over
     some set of assertions.  The structure of signatures is defined
     below.

4.1.1.4 Assertion structure

An assertion has the following structure:

     BEGIN assertion
     string name
     string value
     int ttl
     int expire_date_lo
     int expire_date_hi
     int flags
     END


name This is the name of the attribute.

value
     This is the value associated with the attribute name.

ttl, expire_date_*
     The ttl and expire_date describe the lifetime during which the
     information is expected to be valid (and during which it may be
     cached by intermediaries).

     The ttl field is the number of seconds during which the assertion
     is expected to be valid; if the ttl field is 0x7fffffff then no TTL
     is assumed.

     The expire_date_* fields contain an absolute expiration date.
     expire_date_hi contains the day of expiration, expressed as the
     number of whole days (60*60*24 second periods) since Jan 1, 1970
     UTC.  expire_date_lo contains the number of seconds within the day
     following the number of days in expire_date_hi.  Any leap days
     which have occurred or will occur prior to the expiration date are
     included in expire_date_hi. Any leap seconds which have occurred or
     will occur prior to the expiration date are included in
     expire_date_lo.  Note that expire_date_lo can therefore be greater
     than 86400 seconds.  However most applications will not need that



Moore                    Expires 19 January 2002               [Page 13]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


     degree of precision, and most applications cannot count on having
     their clocks synchronized to that degree of precision.  An
     application supplying expiration dates to RC MAY fail to consider
     leap seconds in its calculations if the loss of precision is not
     considered significant for that application. If expire_date_hi and
     expire_date_lo are both zero, no expiration date is assumed.

flags
     These are single-bit characteristics of the attribute. They are for
     future use.

4.1.1.5 Signature structure

Signatures which can be used to verify authenticity and integrity of the
assertions.  Each signature is a blob formatted according to the
following structure:

     BEGIN signature
     int<> component_list
     int algorithm
     struct bits
     END


component_list
     This is an ordered list of the indices, relative to the start of
     the assertions array from the answer, of the assertions that are
     signed by this signature.  The first assertion of the answer is
     always index 0, even even if the implementation language uses one-
     based arrays.

     Note that the contents of the assertions are signed, and the
     indices are NOT signed.  The indicies have no significance outside
     of a particular Answer to a Query.

algorithm
     This is an integer which specifies both the method for translating
     an ordered list of assertions into a single linear octet string,
     and the digital signature algorithm used to create and verify the
     signature.

bits This is the actual signature, formatted according to the algorithm
     defined by the signature algorithm.

A signature is verified by concatenating the names and values of the
assertions in a manner specified by the signature algorithm, and then
verifying the result of that concatenation against the bits field, again
according to the manner specified by the signature algorithm.  NOTE: ttl



Moore                    Expires 19 January 2002               [Page 14]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


fields of assertions are NOT considered in signature calculations.

4.1.1.6 Recursive Processing

If the QUERY_RECURSE bit of attribute_flags[i] is set, it signifies that
if any attribute_values matching attribute_names[i] are found, they are
to be interpreted as resource_names, and additional queries (using the
same set of attribute_names and attribute_flags as the original query)
are performed for those resource names.  The server may decline to
service such "additional information" requests for any reason, including
for example that the server does not have authoritative information for
the resource name, or the query is being made by UDP and the result does
not fit within a reasonable UDP packet size, or processing of the
additional query would likely cause the caller's retransmission timer to
expire.

It is possible that an attribute_value of some answer will contain a
resource_name that has already been queried.  Servers MUST NOT return
multiple sets of answers for the same resource_name in the response to a
single Query operation.

4.1.1.7 Signature Processing

When any of the attributes in a Query operation has an attribute_flags
field with the WANT_SIGNATURES bit set, the server will return, along
with the attribute information, any signatures which cover the attribute
and which are included in the list of signature_types that the client
understands.  If those signatures include other attributes which are not
requested, those attributes are also included in the response.  Thus a
response may include more attributes than requested.

If the list of signature_types is empty but WANT_SIGNATURES is set for
any attribute, the server will return all available signatures for that
attribute.

A server MAY omit signatures (and the attributes needed to verify those
signatures) if including them would make the result too large for
transmission over UDP; however, inclusion of signatures takes precedence
over QUERY_RECURSE processing.

4.1.1.8 Wildcard attribute names

For the purposes of a query, an attribute_name ending in the character
'*' (ASCII 2A hex) causes information to be returned for each of the
attribute_names in the resource which begin with the portion of the
attribute_name prior to the '*'.  The character '*' MUST NOT appear in
an attribute_name parameter of a Query operation except as the last
character.  Issuing a query for an attribute_name of "*" causes all



Moore                    Expires 19 January 2002               [Page 15]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


attributes to be returned.

4.1.2 Update operation

Note: the rescap charter states that the update protocol is part of the
"second task" of the group's activity which has not yet begun. A sample
update protocol is included here only for the purpose of illustrating
how Query and Update might work together.  This part of the
specification is therefore, for the time being, incomplete.

The Update operation may be used to add attributes, change the values
associated with attributes, or delete attributes from the set of
attributes associated with a URI.  The Update protocol may also be used
to add or delete signatures to sets of attributes.  Servers SHOULD
support the Update protocol, but MAY provide alternate means to perform
these operations than via the Update protocol.

4.1.2.1 Update request structure

The Update request structure is as follows:

     BEGIN update_request
     int request_type         # UPDATE = 1
     string request_id
     int version_hi
     int version_lo
     string resource_name
     int flags
     # UPDATE_CREATE_NEW = 01
     # UPDATE_VERSION_MATCH = 02
     # UPDATE_CLOBBER_SIGS = 04
     int version_hi
     int version_lo
     struct<> assertions
     struct<> signatures
     END


request_type
     For an Update operation, the request_type is 1.

request_id
     This is used to associate the response with the request.  See the
     definition of request_id for the Query operation.

version_hi, version_lo
     These is the version number which the client expects corresponds to
     the server's current version number for that resource.  If the



Moore                    Expires 19 January 2002               [Page 16]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


     UPDATE_VERSION_MATCH flag is set, this version number is compared
     with the server's version number.  Otherwise, version_hi and
     version_lo are ignored.

resource_name
     The resource name for which attributes will be updated.

update_flags
     If the UPDATE_CREATE_NEW flag is set, and no record for
     resource_name exists, this requests that a new record be created.

     If the UPDATE_VERSION_MATCH flag is set, the update fails with
     status VERSION_MISMATCH unless the version_hi and version_lo field
     of the Update request match the version_hi and version_lo fields of
     the existing record.  A nonexistent record (before it is created)
     is treated as if version_hi and version_lo were set to zero.

     If the UPDATE_CLOBBER_SIGS flag is not set, and the update would
     modify some attributes covered by a signature without modifying all
     of those attributes, the operation fails with status
     WOULD_CLOBBER_SIGS.  Setting the UPDATE_CLOBBER_SIGS flag causes
     the signature to be deleted if the update would otherwise be
     successful.

assertions
     This is the list of assertions about resource_name to be added to,
     changed, or deleted, formatted according to the "assertions"
     structure defined above.  The assertions are updated as follows:

     -    If there is no assertion matching the attribute_name, the
          assertion from the Update request is added

     -    If there is already an assertion matching the attribute_name,
          the assertion from the Update request replaces the previous
          one from that principal.  however, if the ttl field in the
          Update request is 0, the previous assertion is deleted.

     -    If the attribute_name ends in '*', the Update operation
          applies to all attributes beginning with the prefix of the
          attribute_name.  However, this can only be used to delete old
          assertions (by setting ttl=0) or to update their ttls (by set-
          ting ttl to something other than 0) and expiration dates (by
          setting these to something other than 0).  Thus it is possible
          to update the ttl and/or expiration date of all assertions
          associated with a resource_name in a single Update operation.

signatures
     The signatures included in the update.  Each of the components of



Moore                    Expires 19 January 2002               [Page 17]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


     the signature (in component_list) is an index into the assertions
     array.  Signatures can only be provide for assertions included in
     the Update operation; if it is needed to sign assertions that are
     already included in the record, they must first be obtained using a
     Query option and then the signatures supplied using an Update
     operation (probably with the MATCH_VERSION option set).

4.1.2.2 Update response structure

The Update response structure is as follows:

     BEGIN update_response
     string request_id
     int status
     END


The update response is a single status code.  The entire Update
operation either succeeds or fails atomically.  Keeping this structure
simple makes it easier to handle retransmitted Update requests without
performing multiple Updates - the server only has to remember the status
of the most recently transmitted request, for that resource_name, from
any party authorized to Update that resource.

4.1.3 Authenticate operation

The Authenticate operation is used to authenticate another request via a
lightweight mechanism.  It is intended for use with requests (such as
Update) which require authentication, when the enclosing transport does
not provide sufficient authentication.  However, it MAY be used over any
transport.

The Authenticate operation only authenticates a single operation; it
DOES NOT establish authentication for subsequent operations between
those parties.
















Moore                    Expires 19 January 2002               [Page 18]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


4.1.3.1 Authenticate request structure

The Authenticate request structure is as follows:

     BEGIN authenticate_request
     int request_type    # AUTHENTICATE = 2
     string request_id
     string authentication_type
     struct authentication_credentials
     int serial_number_hi
     int serial_number_lo
     struct inner_request
     END


request_type
     For Authenticate, the request number is 2.

request_id
     See request_id as described for the Query operation.

authentication_type
     The type of authentication used.  These are to be determined.  The
     intent is to use SASL [9] or GSSAPI [10] mechanisms where
     applicable; however, it is desirable to provide integrity
     protection for the request and not all methods provide this
     service.

authentication_credentials
     This is an opaque data structure, specific to authentication_type,
     which is intended to assure the server of the client's identity and
     to provide integrity protection for the serial_number and the
     inner_request.

serial_number_hi, serial_number_lo
     This is a serial number, represented as two 4-byte integers.  It is
     used to thwart replay attacks.  Each request from a particular
     principal must have a greater serial number than the previous one.
     If a serial number is repeated, and the request is otherwise valid,
     the request will be processed in such a manner as to neither alter
     information on the server nor to return potentially sensitive
     information in the result.  However, for an Update request sent
     over UDP, it is appropriate to return the status of the previous
     operation, in case the duplicate request was caused by a legitimate
     retransmission.






Moore                    Expires 19 January 2002               [Page 19]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


4.1.3.2 Authenticate response structure

The Authenticate response structure is as follows:

     BEGIN authenticate_response
     string request_id
     int status
     struct inner_response
     END


4.2 Transport

4.2.1 Use over TCP and UDP

Clients MAY have the ability to use RC over either UDP or TCP.  Servers
MUST provide UDP support and SHOULD provide TCP support.

An RC server listens for requests on UDP port {TBD-IANA}.  When used
over UDP, each request or response is entirely contained within a single
UDP datagram.  The response is sent to the same address and port number
that appeared in the IP header of the request.  The request or response
datagrams MAY be fragmented into multiple IP packets; so support for
reassembly is required.  The maximum possible request or response is
constrained by the maximum UDP datagram size.  Clients SHOULD NOT use
UDP for a request when the response is expected to contain a large
amount of data.  Servers SHOULD have code to limit the amount of
additional information returned in a UDP response to some reasonable
figure.  Servers MUST detect when a response would be too large (either
larger than the maximum UDP datagram size or larger than some smaller
administrative limit) and return an appropriate error indication.

UDP clients MUST implement a retransmission timer to keep from swamping
the network - details are to be determined.

An RC server that supports TCP listens for requests on port {TBD-IANA}.
The responses are returned over the same connection.  Multiple requests
and responses may be sent over a single TCP connection.  The requests
and responses are self-delimiting, each beginning with a 4-octet integer
length field (in network byte order).  Multiple requests MAY be issued
before reading a response, but this introduces the possibility of
deadlock.  A client that issues multiple requests MUST be able to read
responses to earlier requests concurrently while issuing requests.  When
multiple outstanding requests are issued over a single TCP connection,
servers MAY service them out of order, so long as no request is
significantly delayed.  Servers MAY place a limit on the number of
outstanding requests from a single source, in which case they MUST
respond to requests in excess of that limit with a {TBD} error.



Moore                    Expires 19 January 2002               [Page 20]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


NB: the above needs work.  Since a response may be of arbitrary size, a
server might be unable to return "too many outstanding requests" because
a large response is blocking the return channel.

4.2.2 Use over TLS

Clients and servers MAY support TLS.  TLS is layered on top of TCP, and
an RC server which supports TLS uses the same port for RC-over-TLS-over-
TCP as for RC-over-TCP.  A client wishing to use TLS to communicate with
a server first opens up a TCP connection to that server, and then issues
a StartTLS request.

4.2.2.1 StartTLS request structure

A StartTLS request structure is defined as follows:

     BEGIN starttls_request
     int request_type    # STARTTLS = 3
     string request_id
     END


4.2.2.2 StartTLS response structure

The StartTLS response structure is:

     BEGIN starttls_response
     string request_id
     int status
     END


Servers which support TLS MUST support ciphersuite {TBD}.  The
appropriate use of TLS server certificates by clients, and the use of
TLS client certificates by servers, is yet to be defined.

4.3 Mapping from URIs to RC server locations

The specifics of this are currently undefined, but are intended to be
similar to the procedures defined in [11], [2], and [12], and consistent
with any standards developed in this area.

4.4 Operation Through Proxies

RC clients MAY make queries via a proxy.  Such proxies MAY cache results
(up until their ttls and or expiration dates expire) and return them in
response to subsequent Queries.  Proxies MAY alter the request_id fields
of requests passed to servers in order to better facilitate



Moore                    Expires 19 January 2002               [Page 21]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


demultiplexing and routing the responses to their clients.

4.5 Status Codes

RC_SUCCESS (0)
     successful operation

RC_NO_SUCH_NAME (1)
     operation failed; no record for this resource_name was found on
     this server

RC_NOT_AUTHORITATIVE (2)
     operation succeeded, but the answer returned is not authoritative

RC_RESULT_MISSING_SIGS (3)
     operation succeeded, but signatures could not be included in the
     response due to space limitations

RC_VERSION_MISMATCH (4)
     operation failed because VERSION_MATCH was set in the request but
     the version numbers did not match

RC_TEMPORARY_FAILURE (5)
     operation failed due to unspecified temporary conditions

RC_WOULD_CLOBBER_SIGS (6)
     operation failed because the Update would result in invalidation of
     existing signatures, and the DONT_CLOBBER_SIGS flag was set

RC_KEY_SYNTAX (7)
     operation failed; the syntax of the resource name was not valid

RC_CRED_VRFY (8)
     operation failed, could not verify credentials

RC_CRED_REVOKED (9)
     operation failed, credentials have been revoked or have expired

RC_NOPERM (10)
     client does not have permission to perform the operation

RC_DATA_FMT (11)
     the request was not in the proper format or could not be parsed

RC_REFUSED (12)
     query refused





Moore                    Expires 19 January 2002               [Page 22]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


RC_AUTH_INSUFF (13)
     The authentication method chosen by the client is not sufficiently
     secure for this operation; the actual operation was not attempted.

RC_AUTH_UNSUPP (14)
     The authentication method chosen by the client is not supported by
     the server.

5. Conventions for attribute names

Attribute names are human-meaningful ASCII strings consisting of the
characters "a".."z", "0".."9", "_" and ".".  They are chosen in such a
way that wildcard queries are useful.  Related attributes are grouped
together by having a common prefix followed by ".".  Thus for example
the set of attributes related to electronic mail might be grouped
together with the prefix "email.", and queries for "email.*" might be
issued to obtain all such attributes.

It is intended that a registry of attribute names be maintained by IANA
in order to discourage conflicting uses of the same names.  Assignment
of registry names is via the IETF Consensus process or with IESG
approval.  Prefixes MAY be delegated to other parties via the IETF
Consensus process.

The prefix "rc." is reserved for attributes used by RC itself.  The
prefix "x." is reserved for ad hoc user extensions.

5.1. Inheritance of attributes

The rescap charter specifies a requirement that it must be possible to
inherit attributes.  In RC this is accomplished as follows: the
attribute_name "rc.defaults" is defined.  The value associated with this
name should be a URI.  If an attribute named "rc.defaults" exists for a
particular resource_name, the default attributes for that resource_name
may be obtained by issuing a query for the same attribute_names to the
URI associated with "rc.defaults".

The defaults may thus easily be obtained by including the attribute_name
"rc.defaults" in the set of attributes requested, and by setting the
QUERY_RECURSE flag for that attribute_name.  Multiple levels of defaults
are possible, and each resource_name can have its own set of defaults.
(However, clients MUST take pains to detect circular references in
rc.defaults.)

6. IANA Considerations

-    A new TCP port and a new UDP port are needed




Moore                    Expires 19 January 2002               [Page 23]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


-    A registry of attribute_names, and procedures for assigning and
     delegating attribute naming prefixes, are needed.

-    A registry of signature algorithms, and a procedure for registering
     new signature algorithms identifiers, are needed.

7. Security Considerations

Many security considerations are discussed in section 2.5.  Here are
some others.

7.1 Privacy issues regarding choice of request_ids

Since request_ids need to be unique, it is tempting to define them in
terms of some other convenient globally-unique number such as a GUID,
network interface hardware address, (non-private) IP address, etc.  This
may result in inadvertent disclosure of information about usage patterns
to unauthorized parties.  Request-ids SHOULD be chosen in such a way as
to minimize the potential for disclosure of information which could be
associated with a particular person or host.  The fact that similar
information could be disclosed by other means does not lessen the burden
for RC client implementations to minimize their own potential for
disclosure through the request_id field.

Similarly, RC proxies that multiplex several clients' requests over the
same TCP stream may need to map between clients' request_ids and their
own request_ids for proxied requests, in order to ensure that each
request_id transmitted over a TCP stream is unique.  Such proxies SHOULD
avoid disclosing identifying information about clients via the
request_id field.

8. Differences from RC version 2

Just to provide some background, this section details major differences
between RCv2 and RCv3:

-    RCv2 had typed attributes; RCv3 makes all attributes octet-strings.

-    RCv2 used ONC XDR and RPC; RCv3 uses the BLOB encoding and defines
     its own RPC mechanism.  For a variety of reasons, most having
     little to do with protocol quality, use of ONC RPC was the single
     largest barrier to anyone using RCv2.  However the mechanism
     intended for use with RCv3 is easier to implement and more
     efficient to process than XDR.

-    RCv2 maintained separate records for attributes of resources (like
     RCv3's assertions) and locations of resources, allowing the caller
     to choose the closest of several locations for that resource.  The



Moore                    Expires 19 January 2002               [Page 24]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


     latter also included cached DNS A records in order to speed up
     accesses to the resource.  RCv3 does not have this separation.

-    RCv2 supported the principle of multiple 'asserters' for
     information about a resource.  it kept track of who made each
     assertion, and if different asserters made conflicting assertions,
     it would return all of the assertions.  RCv3 assumes that a small
     number of trusted parties will be allowed to make assertions about
     any particular resource, and that these parties will cooperate to
     the degree necessary to avoid making conflicting assertions about a
     resource.  The QUERY_RECURSE feature of RCv3 is intended to provide
     similar functionality in a more general fashion.

-    RCv2 supported the notion of redirects - the ability to redirect
     queries for portions of URI-space - at the protocol level; this is
     omitted in RCv3 because they were too much trouble to use.
     Redirects could be implemented in RCv3 by making them ordinary
     attributes and by using the QUERY_RECURSE bit in queries for that
     attribute name.

9. Author's Address

Keith Moore
University of Tennessee, Knoxville
1122 Volunteer Blvd, Suite 203
Knoxville TN, 37996-3450
USA
email: moore@cs.utk.edu


10. References

[1]  Bradner, S.  Key words for use in RFCs to Indicate Requirement
     Levels.  RFC 2119, March 1997.

[2]  Mealling, M., Daniel, R.  The Naming Authority Pointer (NAPTR) DNS
     Resource Record.  RFC 2915, September 2000.

[3]  Gulbrandsen, A., Vixie, P., Esibow, L.  A DNS RR for specifying the
     location of services (DNS SRV).  RFC 2782, February 2000.

[4]  Dierks, T., Allen, C.  The TLS Protocol Version 1.0.  RFC 2246,
     January 1999.

[5]  Mockapetris, P.V.  Domain names - implementation and specification.
     RFC 1035, November 1987.





Moore                    Expires 19 January 2002               [Page 25]


Resource Catalog (v3)        INTERNET-DRAFT                 19 July 2001


[6]  Case, J. Mundy, R., Partain, D., Stewart, B. Introduction to
     Version 3 of the Internet-standard Network Management Framework.
     RFC 2570, April 1999.

[7]  Wahl, M., Howes, T., Kille, S.  Lightweight Directory Access
     Protocol (v3).  RFC 2251, December 1997.

[8]  Moore, K.  The Binary Low-Overhead Block Presentation Protocol.
     work in progress, Internet-Draft draft-moore-rescap-blob-00.txt,
     July 12, 2001.

[9]  Myers, J.  Simple Authentication and Security Layer (SASL).  RFC
     2222, October 1997.

[10] Linn, J.  Generic Security Service Application Program Interface
     Version 2, Update 1.  RFC 2743, January 2000.

[11] Daniel, R., Mealling, M.  Resolution of Uniform Resource
     Identifiers using the Domain Name System.  RFC 2168, June 1997.

[12] Mealling, M.  A DDDS Database Using the Domain Name System.
     Internet-Draft draft-ietf-urn-dns-ddds-database-02.txt, November
     2000.  work in progress.




























Moore                    Expires 19 January 2002               [Page 26]