Network Working Group Keith Moore Internet-Draft University of Tennessee 11 January 2001 Expires: 11 July 2001 The Resource Catalog draft-moore-rescap-rc-00.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-00" in any comments regarding this document. Abstract 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. Moore Expires 11 July 2001 [Page 1] Resource Catalog (v3) INTERNET-DRAFT 11 January 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 11 July 2001 [Page 2] Resource Catalog (v3) INTERNET-DRAFT 11 January 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 therefore 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. Moore Expires 11 July 2001 [Page 3] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 It is therefore essential that RC provide fast response. This implies that 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. TCP is allowed as an option. RC is also optimized for small payloads, and it attempts to impose minimal protocol overhead. Finally, it 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. Moore Expires 11 July 2001 [Page 4] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 The RC protocol allows for multiple authentication methods in order to accommodate the needs of different environments, and to accomodate 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 altered responses. 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 this 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. Moore Expires 11 July 2001 [Page 5] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 - Removal of signatures from responses When TLS is used, the integrity protection provided by TLS will allow a client to detect altered responses. 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 11 July 2001 [Page 6] Resource Catalog (v3) INTERNET-DRAFT 11 January 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 11 July 2001 [Page 7] Resource Catalog (v3) INTERNET-DRAFT 11 January 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 uses human-readable ASCII strings rather than OIDs to name data elements, to encourage definition of standard data elements and to encourage reuse of such elements between applications where it makes sense to do so - 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; Moore Expires 11 July 2001 [Page 8] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 - a value, which is often human-readable, but can potentially be any sequence of octets; - an optional time-to-live; and - 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 Cacheing 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- Moore Expires 11 July 2001 [Page 9] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 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. 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 are 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 in terms of an abstract syntax (similar to the C language). The basic data types that can appear in structures are: (32 bit) int, string, struct, and arrays. strings are sequences that may (at least as far as the presentation layer is concerned) consist of arbitrary octets. arrays are homogeneous sequences of ints, strings, or structs, and are of variable length. structs are potentially heterogeneous sequences (also of variable length) that can contain elements consisting of any of the above types, including other structs. Strings, arrays, and structs of zero length are legal. It is also possible for a string, array, or struct to be NULL or omitted from the enclosing structure (which is not the same thing as zero length, and the two can be distinguished from one another). As far as the encoding is concerned, all structs are the same type; thus 'struct opaque' is used as a notation for a struct which could contain a variety of types. The mapping between the abstract syntax and the on-the-wire presentation will be defined in a separate document. The presentation is intended to be very easy and efficient to encode, decode, and sanity check (to minimize processing overhead); to have a single valid representation for any set of arguments (so things are always in "canonical form"); and to be reasonably compact. 4.1 Operations The following operations are defined: Moore Expires 11 July 2001 [Page 10] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 4.1.1 Query operation The Query operation returns information describing the named resource. Query request structure: struct query_request { int request_number; /* QUERY = 0 */ string request_id; string resource_name; int num_attributes; struct attribute { string attribute_name; int attribute_flags; #define QUERY_RECURSE 01 #define WANT_SIGNATURES 02 } attributes [num_attributes]; int num_signature_types; int signature_types [num_signature_types]; }; request number For a Query request, this MUST be 0. request_id This is a string which is chosen to be unique for the client's IP address and port pair, for any amount of time during which a request is likely to be pending, and which is used to associate the response with the request. 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. num_attributes The number of attributes which are being requested for the resource. A query with num_attributes of 0 is an undefined operation. attributes The list of attributes that are being requested for the resource. Each attribute request consists of an attribute_name and a set of attribute_flags which specify optional features of the query. An Moore Expires 11 July 2001 [Page 11] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 attribute_name ending in "*" is a wildcard; see section 3.1.1.3. There MUST be exactly num_attributes elements in the array. The QUERY_RECURSE flag controls searching for additional information; see section 3.1.1.1 below. The WANT_SIGNATURES bit requests signatures; 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 authortative party. num_signature_types The number of signature types in the signature_types array. See section 3.1.1.2. signature_types The list of signature_types which are understood by the caller. It MUST be exactly num_signature_types elements long. Moore Expires 11 July 2001 [Page 12] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 Query result structure: struct query_result { string request_id; int num_answers; struct answer { string resource_name; int query_status; int version_hi; int version_lo; int num_assertions; struct assertion { string attribute_name; string attribute_value; int ttl; int expire_date_hi; int expire_date_lo; } assertions [num_assertions]; int num_signatures; struct signature { int num_components; int component_list[num_components]; int signature_algorithm; struct opaque signature_bits; } signatures [num_signatures]; } answers [num_answers]; }; request_id This is the request_id from the Query structure, used to associate the response with the request. num_answers The number of answers included in the result. answers The list of answers. The first answer is the one which directly corresponded to the query; any additional answers are the result of additional queries requested via the QUERY_RECURSE flag. 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 Moore Expires 11 July 2001 [Page 13] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 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. num_assertions The number of assertions made about the named resource. assertions Information about the named resource. Each assertion consists of an attribute_name, an attribute_value, ttl, expire_date, and a set of flags. The attribute_value is the value associated with the attribute_name. 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). Both are optional; if both are included then the resource is expected to be valid until either the ttl elapses or the expire_date is reached, whichever comes first. 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 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. num_signatures The number of signatures returned. Moore Expires 11 July 2001 [Page 14] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 signatures Signatures which can be used to verify authenticity and integrity of the assertions. Each signature consists of a signature_algorithm and an ordered list of components. signature_algorithm 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. Each component is an index into the assertions array for this answer. NOTE: ttl fields of assertions are NOT considered in signature calculations. 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 signature_bits, again according to the manner specified by the signature algorithm. 4.1.1.1 Recursive Processing If the QUERY_RECURSE bit of attribute_flags is set, it signifies that if any attribute_values matching this attribute_name 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.2 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. Moore Expires 11 July 2001 [Page 15] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 If num_signature_types is 0 (i.e. the list 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.3 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 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 illus- trating 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 val- ues 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 sup- port the Update protocol, but MAY provide alternate means to perform these operations than via the Update protocol. Moore Expires 11 July 2001 [Page 16] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 Update request structure: struct update_request { int request_number; /* UPDATE = 1 */ string request_id; int serial_number_hi; int serial_number_lo; string resource_name; int update_flags; #define UPDATE_CREATE_NEW 01 #define UPDATE_VERSION_MATCH 02 #define UPDATE_CLOBBER_SIGS 04 int version_hi; int version_lo; int num_assertions; struct attribute { string attribute_name; string attribute_value; int ttl; int expire_date_hi; int expire_date_lo; } assertions[num_assertions]; int num_signatures; struct signature { int num_components; int component_list[num_components]; int signature_algorithm; string signature_bits; } signatures [num_signatures]; }; request_number For an Update operation, the request_number is 1. request_id This is used to associate the response with the request. See the definition of request_id for the Query operation. 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 current version of the record Moore Expires 11 July 2001 [Page 17] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 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. num_assertions The number of assertions which are being changed. assertions This is the list of assertions about resource_name to be added to, changed, or deleted. 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. 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. num_signatures The number of signatures included in the update. Each of the com- ponents of 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 asser- tions 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). Moore Expires 11 July 2001 [Page 18] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 Update response structure: struct update_response { string request_id; int status; }; The update response is a single status code. The entire Update operation either succeeds or fails atomically. Keeping this struc- ture simple makes it easier to handle retransmitted Update requests without performing multiple Updates - the server only has to remem- ber 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. Authenticate request structure: struct authenticate_request { int request_number; /* AUTHENTICATE = 2 */ string request_id; string authentication_type; struct opaque authentication_credentials; int serial_number_hi, serial_number_lo; struct opaque inner_request; }; Authenticate response structure: struct authenticate_response { string request_id; int status; struct opaque inner_response; }; Moore Expires 11 July 2001 [Page 19] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 request_number 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 [8] or GSSAPI [9] mechanisms where applica- ble; 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. 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 Moore Expires 11 July 2001 [Page 20] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 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 begnning 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. 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. StartTLS request structure: struct starttls_request { int request_number; /* STARTTLS = 3 */ string request_id; }; StartTLS response structure: struct starttls_response { string request_id; int status; }; Moore Expires 11 July 2001 [Page 21] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 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 [10], [2], and [11], 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 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 succeeeded, 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 Moore Expires 11 July 2001 [Page 22] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 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 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 Moore Expires 11 July 2001 [Page 23] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 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 assocaited 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 - A registry of attribute_names is neeeded 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: Moore Expires 11 July 2001 [Page 24] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 - RCv2 had typed attributes; RCv3 makes all attributes octet-strings. - RCv2 used ONC XDR and RPC; RCv3 defines its own encoding and 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 much more efficient to process and easier to implement 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 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 informa- tion 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 par- ticular resource, and that these parties will cooperate to the degree necessary to avoid making conflicting assertions about a resource. - 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. Redi- rects could be implemented in RCv3 by making them ordinary attributes and by using the RC_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 Lev- els. RFC 2119, March 1997. [2] Mealling, M., Daniel, R. The Naming Authority Pointer (NAPTR) DNS Resource Record. RFC 2915, September 2000. Moore Expires 11 July 2001 [Page 25] Resource Catalog (v3) INTERNET-DRAFT 11 January 2001 [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. [6] Case, J. Mundy, R., Partain, D., Stewart, B. Introduction to Ver- sion 3 of the Internet-standard Network Management Framework. RFC 2570, April 1999. [7] Wahl, M., Howes, T., Kille, S. Lightweight Directory Access Proto- col (v3). RFC 2251, December 1997. [8] Myers, J. Simple Authentication and Security Layer (SASL). RFC 2222, October 1997. [9] Linn, J. Generic Security Service Application Program Interface Version 2, Update 1. RFC 2743, January 2000. [10] Daniel, R., Mealling, M. Resolution of Uniform Resource Identi- fiers using the Domain Name System. RFC 2168, June 1997. [11] Mealling, M. A DDDS Database Using the Domain Name System. Inter- net-Draft draft-ietf-urn-dns-ddds-database-02.txt, November 2000. work in progress. Moore Expires 11 July 2001 [Page 26]