ASID Working Group
INTERNET-DRAFT                                          Network Solutions, Inc.
draft-ietf-asid-rwhois-00.txt                                     July 30, 1997
Expires: Jan 30, 1998
Intended category: Standards Track

                    Referral Whois Protocol (RWhois) 2.0

Status of this Memo

This document is an Internet-Draft. Internet-Drafts are working documents
of the Internet Engineering Task Force (IETF), its areas, and its working
groups. Note that other groups may also distribute working documents as
Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any time.
It is inappropriate to use Internet-Drafts as reference material or to
cite them other than as work in progress.

To learn the current status of any Internet-Draft, please check the
1id-abstracts.txt listing contained in the Internet-Drafts Shadow Directories
on ds.internic.net (US East Coast), nic.nordu.net (Europe), ftp.isi.edu
(US West Coast), or munnari.oz.au (Pacific Rim).

Abstract

This memo describes Version 2.0 of the client/server interaction of RWhois.
RWhois provides a distributed system for the display of hierarchical and
non-hierarchical information. This system is primarily hierarchical by
design, allowing for the deterministic reduction of a query and the referral
of the user closer to the maintainer of the information. It also identifies
the attributes that are non-hierarchical so that they may be indexed into a
mesh.

RWhois differentiates itself from other directory service protocols with its
ability to reduce the query (narrow in on a hierarchical server that may be
able to help) and with its integrated awareness of authority areas.



Table of Contents

   * Abstract
   * Summary Of Changes Between RWhois Spec 1.5 And 2.0
   * Open Issues
   * 1.0 Introduction
        o 1.1 Definitions
   * 2.0 Connection Model
        o 2.1 Standard Query (TCP)
        o 2.2 Quick Query (UDP)
   * 3.0 Client/Server Interaction Model
        o 3.1 Banner
             + 3.1.1 From the Server
             + 3.1.2 From the Client
        o 3.2 Base MIME Objects
             + 3.2.1 Directives
             + 3.2.2 Responses
             + 3.2.3 Results
        o 3.3 Directive and Response Specifications
             + 3.3.1 rwhois
             + 3.3.2 directive
             + 3.3.3 display
             + 3.3.4 forward
             + 3.3.5 limit
             + 3.3.6 notify
             + 3.3.7 quit
             + 3.3.8 register
             + 3.3.9 class
             + 3.3.10 attribute
             + 3.3.11 security
             + 3.3.12 soa
             + 3.3.13 status
             + 3.3.14 xfer
             + 3.3.15 X-
   * 4.0 Data Model
        o 4.1 Base Class
        o 4.2 Defining a New Class
             + 4.2.1 Attribute Class
             + 4.2.2 Class Class
        o 4.3 RWhois Standard Schemas
             + 4.3.1 Referral Class
             + 4.3.2 SOA Class
             + 4.3.3 Guardian Class
             + 4.3.4 Status Class
             + 4.3.5 Directive Class
             + 4.3.6 TOC Class
   * 5.0 Search Model
        o 5.1 Query
        o 5.2 Constraints
        o 5.3 Query Reduction
             + 5.3.1 Search Algorithm
             + 5.3.2 Reduction Rules
        o 5.4 Referral
        o 5.5 Other Elements Affecting Query Completion
   * 6.0 Security Model
        o 6.1 Stream Privacy
        o 6.2 Authentication of Reading/Writing of Objects
   * 7.0 Tree Management
   * 8.0 References
   * 9.0 Authors' Addresses
   * Appendix A: Error Codes
   * Appendix B: Capabilities ID
   * Appendix B: General ABNF definitions

Summary Of Changes Between RWhois Spec 1.5 And 2.0

   * Internationalization
        o Character set specification within an object and within a query
        o Encoding specification within an object and within a query
        o Entire protocol _can_ be MIME encoded
   * Query Language
        o Per-attribute constraints
        o Boolean operations
        o Nested operations
   * Revised Data Model
        o More object oriented
        o Start Of Authority (SOA) and Schema objectified
   * Response Formats
   * Display Formats
   * Generic Query Reduction Rules
        o Standardization of reducible fields
        o Reduction token specified by regular expression match
   * Support for Secondarying
        o Complete and partial
   * Authority Area Enforcement
   * Registration
   * Security
        o Enhanced guardian support
        o Per-attribute access control lists

Open Issues

This is an Internet-Draft, which means that more work needs to be done. In
the opinion of the original authors, there are several open issues that need
to addressed before this protocol can move forward; they include the
following.

   * Registration
     Registrations need to be examined for the demands they make on
     implementations with respect to the atomicity of operations. It is the
     authors intention to not require a system that would need to implement
     roll backs within its database. It is also desirable for the protocol
     to be able to support multiple masters so that updates can take place
     at multiple locations.
   * Caching
     Caching should be discussed in relation to schema and how a cache is
     searched locally given so not to have to implement a server's database
     in the client.
   * Security
     As mentioned in Section 6, security will be reworked.
   * Common Indexing Protocol (CIP)
     RWhois 2.0 is intended to work very closely with the CIP. As CIP is
     standardized, RWhois 2.0 should be modified to operate with it. This
     document may need to specify a CIP-index object type.
   * Incremental Updates
     To scale in large application domains, a secondary should be able to be
     updated incrementally. One aspect of this is a 'diff' style update,
     where only the differences between objects are transported.

1.0 Introduction

Originally, the RWhois protocol [RFC1714] was designed primarily around the
data found at the InterNIC and other domain-name and IP registrants such as
Internet Service Providers (ISPs). Versions 1.0 [RFC1714] and 1.5 [RFC2167]
of the protocol illustrated that the system is useful and works well within
certain constraints. During this time, several problems appeared that
require an update to the protocol. First, RWhois will be used as a more
generic directory services tool in the near future, so the protocol must be
able to deal with much more disparately organized data. Some of the data may
be in other character sets, its hierarchy may not be '.' delimited, and the
users may need a richer query language.

Until Version 1.5 of RWhois, RWhois retained the basic functionality of the
whois server and client, making all of the extensions optional. This
requirement changed in Version 1.5, however. This version of the RWhois
protocol is NOT backward compatible with any of the previous versions. The
server MAY respond to a whois or RWhois Version 1.0 or 1.5 client, but it is
not required to do so. The RWhois Version 2.0 client MAY also interact with
whois [RFC954] servers or RWhois Version 1.0 or 1.5 servers, but it is not
required to do so. This is an implementation choice.

RWhois Version 2.0 has been designed as an extensible protocol to ensure
that many uses can be accommodated. Public extensions to the protocol sho=
uld
be documented as RFCs. Private extensions can be used with agreement left up
to the client and server. Since the protocol is MIME oriented, any
extensions should use the x- convention for specifying experimental or
non-standard MIME Content-Types. If extensions are not implemented at the
server in question, an appropriate error message must be sent.

This document uses words such as SHOULD and SHALL with the special meaning
specified in "Key Words For Use In RFCs To Indicate Requirement Levels."
[RFC2119]

1.1 Definitions

Class
     A type of object.
Class Definition/Schema
     Identifies all of the attributes allowed within an object of that
     class.
Attribute
     A variable within a class. (Example: Organization-Name contains the
     value for the name of an organization.)
Object
     An instance of a class that contains data.
SOA - Start Of Authority
     This object contains the administrative variable of an authority area.
Guardian Object
     This object, when linked to another object, specifies the method of
     protection for that object.
Authority Area
     An authority area is an identifier for an RWhois database containing
     data and its schema [1]. It has a hierarchical structure that helps
     identify the position of the database in the global RWhois data
     information tree. This version of the protocol specifically allows for
     hierarchy based on arbitrary and possibly complex criteria. Thus, an
     authority area can be in any character set as well as a complex set of
     data. For example, CIDR blocks have fairly complex ideas of how to
     allocate a given space; this is not easy to specify as a authority
     area.
Primary RWhois Server
     A primary (or master) RWhois server is where data is registered for an
     authority area. It answers authoritatively to queries for data in that
     authority area. There MUST be one and only one primary server for a
     particular authority area, and an RWhois server may be primary for
     multiple authority areas.
Secondary RWhois Server
     A secondary (or slave) RWhois server is where data is replicated from a
     primary server for an authority area. It, like its primary server,
     answers authoritatively to queries for data in that authority area.
     There can be multiple secondary servers for a particular authority
     area. An RWhois server may be secondary for multiple authority areas.

2.0 Connection Model

2.1 Standard Query (TCP)

This document describes how RWhois Version 2.0 would behave using
Transmission Control Protocol (TCP).

2.2 Quick Query (UDP)

The overhead incurred by establishing a TCP connection and interacting with
an RWhois server may be unnecessary if the client only wishes to ask one
question. A separate document will describe the User Datagram Protocol (UDP)
facility for RWhois. Adjustments to the query must be made to make this a
practical option. The only function allowed while utilizing UDP is a single
query.

Unless the client is told that a certain host supports both TCP and UDP the
client should attempt UDP first. If the server has not responded after a
one-second interval, the client should then attempt to connect via TCP. If
the server responds via UDP while the client is connecting/connected via
TCP, the client should remember this and set the UDP timeout to the delay
for the returned packet plus one second.

The SRV DNS record provides for a future method of discovering the existence
of either TCP or UDP services by querying DNS for tcp.rwhois.<domain> and
udp.rwhois.<domain>. RFC2052 states that if a service is not available the
target of the SRV record should be "." (NULL in DNS parlance). Thus, an
RWhois client can discover which services are available.

3.0 Client/Server Interaction Model

For RWhois Version 2.0 to support multiple character sets and encodings
requires that some method be used to identify those encodings and character
sets. Instead of developing yet another encoding scheme, an off-the-shelf
system can be used. MIME is currently being used by several protocols as a
method for encoding objects: therefore, the model for RWhois Version 2.0
will be encoded as a sequence of directives and responses encoded as MIME
objects. Most of the client/server interaction concerns three types of
objects: directives, responses, and results. Section 2.2 outlines these
objects and their relationship to each other. The protocol is the
specification of the interaction between the client and the server with
respect to when and how these objects are exchanged.

However, the protocol may seem 'ugly' or too 'large' on the wire since every
directive is encoded in its own set of MIME headers. Also, it is rare that
one element of a client/server interaction would be in a different character
set/encoding than the previous element. Both considerations are specifically
addressed by two design decisions.

First, while internationalization is a goal, in the near future a majority
of users will still be using the English language represented with US-ASCII.
To optimize for this and to allow some degree of backward interoperability,
the default character set and encoding will be US-ASCII. The default
language will be English.

Second, the client can specify its own default encoding, character set, and
language in its response to the server's banner. This is specified in
Section 3.1.2 as part of the response to the server's banner. For example,
when a client contacts a server that supports multiple character sets, the
server uses US-ASCII by default. When the client connects, it specifies that
it wants to talk Unicode using a UTF-8 encoding for queries in Inuit, the
language used by the native people of northern Canada. From that point, the
default encoding is as specified by the client.

There are four distinct processes involved in the interaction between a
client and a server.

  1. Initial connection and subsequent protocol and capability negotiation.
     This is accomplished with the server sending the Banner and the client
     sending either a directive or a client capability object. When the
     client simply sends a directive and not a client capability object, the
     client implicitly states that it has accepted the servers defaults. See
     Section 2.1 Banner for a detailed description of this process.
  2. Exchange of zero or more MIME objects containing directives and
     responses. These are used to set up the environment and specify the
     query. These objects are listed in Section X.0, Directive and Response
     Objects.
  3. Exchange of zero or more query object. These objects are explained in
     Section X.0, Query Objects, and in Section X.0, The Search Model.
  4. Exchange of zero or more Result objects. Result objects are explained
     in section X.0 Result Objects.
  5. Final disconnect. The final disconnect sequence is explained in Section
     X.0. While the client SHOULD issue a disconnect sequence, server
     developers should handle the very common occurrence of clients simply
     disappearing. It should also be noted that the client can specify a
     disconnect sequence at any time; it does not need to follow the above
     sequence before it can disconnect.

3.1 Banner

Even though this version of the RWhois protocol does not require backward
compatibility with both whois and whois++, there is some desire to allow
older clients to realize that the server they have connected to is of a
later revision. It is also common practice for most Internet protocols to
greet the client with some sort of banner that fits on one line. This banner
must be followed by either a directive from the client or a client
capability object.

While it is not a requirement that server developers support all past
versions of the RWhois protocol, developers should realize that old clients
may (and will) connect to new servers. When a client responds in such a way
that illustrates that it does not understand the banner (i.e., it picked a
protocol version that is not supported by the server) then the server should
respond with an error message the client can understand. For older clients
(versions 1.0 and 1.5), the server should send back the appropriate "%error"
message as specified in RFC 1714.

Defaults for the MIME attributes and headers are as follows.

 MIME header/attribute    Value
 Content-Transfer-Encoding8bit
 Content-Language         en-US
 charset parameter        US-ASCII

The server MUST assume these values if the client does not specify
otherwise. All clients must assume that all RWhois Version 2.0 servers
assume these defaults. It should be considered an error for a client to try
to interact with a server in anything other than these defaults without
first specifying its desire to do so.

3.1.1 From the Server

rwhois-banner =3D "%rwhois" space version-list space host-name=20
   [space implementation] crlf
version-list =3D version *("," version)
version =3D version-number [":" capability-id] / "V-2.0" ":" capability-id
version-number =3D "V-" 1*digit "." 1*digit
capability-id =3D response-id ":" extra-id
response-id =3D 6hex-digit
extra-id =3D 2hex-digit
implementation =3D 1*any-char

Version-list indicates all of the protocol versions that this server
supports. The versions should be listed from oldest to newest so clients do
not need to understand potential future changes to the format of this list.
The client=92s behavior beyond this point depends on which version of the
protocol the client chooses. This document is only concerned with the
ensuing dialogue if the version number is 2.0 or lower.

Capability-id identifies the server's capabilities. Each optional directive
has a bit that is set if the server can understand the directive. Clients
should use this information to determine which of the optional capabilities
can be used. The value information for each directive can be found in the
definition for that directive. All of the capability ids are listed in
Appendix B.

Host-name is the host name of the computer hosting the RWhois server.

Implementation contains information about the server implementation. It is
recommended that the version number of the software be indicated. This
version may differ from the specification version number.

Example of Use:

%rwhois V-1.0:04ffff:0f:0f,V-2.0:04ffff:0f root.rwhois.net (NSI V-1.6)

3.1.2 From the Client

The client=92s response to this banner depends upon which version of the
supported protocol the client picks. As stated earlier, this document is
only concerned with the response for Version 2.0 and lower. If the client
wishes to respond as a Version 1.0 client, then it will issue the
appropriate -RWhois response as specified in RWhois Version 1.0 and 1.5
RFCs. If the client wishes to connect as a Version 2.0 client, it has two
options.

The first option is to simply accept the server=92s defaults and to specify
the directives it wishes to execute. If the response sent from the client is
not a valid MIME object that includes the client capability response, the
server should assume that the client has accepted its defaults and that what
is being sent is a directive of some type.

The second option is for the client to send a valid "rwhois" directive to
the server. See Section 5.X for the definition of the "rwhois" directive.
The server MUST either accept the defaults as specified by this directive or
issue the "504 Specified Defaults Unsupported...Goodbye" message.

3.2 Base MIME Objects

There are two design criteria used to decide on the MIME objects. The first
is that there be as few MIME objects as possible. This reduces the amount of
time spent in the MIME parser and ensures the MIME Content-Type does not
bloat. The second criteria generalizes the specific parts of the protocol so
that developers can re-use large amounts of code for different
directives/responses. Therefore, the following MIME objects will be used for
ALL protocol interactions. As soon as this draft has been finalized these
Content-Types will be registered with the Internet Address and Naming
Authority (IANA).

All MIME objects MUST follow Simple Mail Type Protocol (SMTP)-style body
termination. The data contained in the body is sent octet-for-octet, except
when the pattern ``<cr><lf>.<cr><lf>''occurs. In that case, the period is
repeated, resulting in the following pattern: ``<cr><lf>..<cr><lf>''. When
the data is finished, the octet pattern ``<cr><lf>.<cr><lf>'' is
transmitted. On the receiver's side, the reverse transformation is applied,
and the message read consists of all bytes up to, but not including, the
terminating pattern. This object termination is used whether the default
MIME encoding is used or not. Thus, the following two representations of a
response are valid and MUST be considered equal.

Object given with no header:

XXX Message
=2E

Both terminator and header specified:

Content-Type: application/rwhoisv2-response

XXX Message
=2E

3.2.1 Directives

Directives are used to set up the environment that the client needs and to
specify the query to execute in that environment. The Content-Type is
"application/rwhoisv2-directive". The body of the object contains exactly
one directive. An empty body is an error, and more than one directive in a
body is also an error.

The body follows a format of the directive name being the first space
delimited token on the first line. Arguments on the same line and the format
of subsequent lines are defined by the directive. The directive name will be
encoded in 7-bit ASCII; each directive definition can specify other values
that must be 7-bit ASCII. Arguments that are NOT specified to be 7-bit ASCII
follow the character set/language as specified in the MIME header for that
set of directives.

For example:

Content-Type: application/rwhoisv2-directive;

limit 200
=2E
Content-Type: application/rwhoisv2-directive;
Content-Language: en-UK

query first-name=3D"Winston" and last-name=3D"Churchill"
=2E

MIME headers can be defaulted, and the above two directives can also be
specified like this:

limit 200
=2E
Content-Type: application/rwhoisv2-directive;
Content-Language: en-UK

query first-name=3D"Winston" and last-name=3D"Churchill"
=2E

It should also be noted that the limit and language directives also have
global constraint counterparts as specified in the query directive. Thus,
the previous interaction could be compressed even further to this:

query first-name=3D"Winston" and last-name=3D"Churchill":limit=3D200;language=3Den-UK
=2E

Some may say that there are redundant constraints, directives, and MIME
attributes. However, these enable one to specify attributes at several
levels of granularity within the protocol. While US-ASCII may be the
default, some servers may want to specify the French language for certain
attributes to allow soundex matches. This flexibility is intentional so that
those building fast servers need not be encumbered by a full MIME
implementation. Those wanting a truly robust system, therefore, are not
crippled by the "need for speed".

3.2.2 Responses

Responses are the return codes and other directive output that is not
normally considered to an RWhois data object. The Content-Type is
"application/rwhois-response". The body follows the format of the code and
its textual representation takes up the first line. Subsequent lines are
reserved for each response code to be able to specify its own format.

An application/rwhois-response MUST have one and only one response within
the body. Zero responses must be considered an error. More than one response
must be considered an error.

Content-Type: application/rwhoisv2-response;

 Directive ok
=2E

3.2.3 Results

Results are actual data objects returned from a directive. Only certain
directives return result sets instead of responses in their normal case.
These results can be any MIME-encoded object. The user can request which
Content-Type to return by using the 'display' directive.

When there are multiple, separate objects to be returned, the results will
be encoded in a stream of objects in a multipart/mixed MIME object. When an
object has sub-parts, such as when an image is sent along with the results,
the object must be encoded within a MIME multipart/related object.

Additionally, if a client sets the 'display' directive to
'multipart/related' then no matter how many returned objects or their
complexity, the server MUST return a 'multipart/related'. In this case, the
server should set the root of the multipart/related object to the TOC
Object, which is used to point to the subsequent objects. See Section 4.3.6
for a description of the TOC Object.

When the client does not specify a display type or the data itself does not
specify its own encoding, the default MIME type used will be
'text/directory'. This means that text/directory will be used as the
standard and canonical exchange format for all native RWhois objects. The
text/directory MIME type requires the 'profile' parameter, which is the
'scheme' or class of the body. To alleviate name clashes, the profile
namespace for all native RWhois objects is required to start with "rwhois- -".
The Attribute Class would use the profile "rwhois-attribute", for example.

3.3 Directive and Response Specifications

All directives encoded within the application/rwhois-directive object are
optional with the exception of the rwhois directive that is discussed in
Section 3.1.2. This is the only required directive, and without it the
server would have no idea with what it was communicating. The directives
given here are those that are required to fully cooperate within the RWhois
Tree. It is up to implementers to choose whether or not to fully cooperate.

Responses that are specific to a given directive are detailed with that
corresponding directive. General responses are listed at the end of this
section.

It is also important to note that several directives return objects. Since
all objects can be queried it follows that any directive that returns an
object could have also been specified via a query. For example, the
=91attribute=92 directive returns objects found in the Attribute class. This
directive can also be specified by querying directly against the Attribute
class. In each instance where this is true a query form and a directive form
are given. These two forms MUST be considered identical. Implementers are
STRONGLY encouraged to implement the directive by simply translating it into
the query or vice versa. This cannot be stressed enough. Any deviation
between the two specifications can reek havoc with the protocol.

3.3.1 rwhois

Description

The "rwhois" directive is used by the client to identify itself as an RWhois
client, identify the version of the RWhois protocol that it desires to
speak, and the defaults that the client wants the server to use. It is the
client=92s version of the server's banner.

ABNF

rwhois-dir =3D "rwhois" crlf *(rwhois-av) "." crlf
rwhois-av =3D "Protocol-Version:" space version-val crlf
            "Implementation:" space impl-val crlf
            "Default-Content-Encoding:" space encoding-val crlf
            "Default-charset:" space charset-val crlf
            "Default-Content-Language:" space language-val crlf
            attribute-name ":" attribute-value crlf
version-val =3D version-number
version-number =3D "V-" 1*digit "." 1*digit
response-id =3D 6hex-digit
extra-id =3D 2hex-digit
impl-val =3D 1*any-char
encoding-val =3D 1*any-char
charset-val  =3D 1*any-char
language-val =3D 1*any-char

The version-val is a required argument that identifies the client's protocol
version and capabilities. Each bit represents the optional responses the
client can understand. Servers should use this information to determine
which of the optional capabilities can be used. The value information for
each server response can be found in Section 7.0 of this document. Note that
no list of versions is given as in the server=92s banner. This is because the
onus is on the client to pick which version of the protocol will be spoken.
This is the client's way of saying "I'll take that one."

The impl-val argument is optional and identifies client implementation
information. It is recommended that the implementer maintain a version
number separate from the specification version.

The encoding-val is a required argument that specifies the default MIME
encoding that will be used by the client. The value MUST be the value of the
Content-Transfer-Encoding MIME header as specified in [RFC1521].

The charset-val argument is required and specifies the default character set
that will be used by the client. This value MUST be a valid value for the
'charset' attribute of the text MIME Content Type as specified in [RFC1521].

The language-val is a required argument that specifies the default language
that will be used by the client. This value MUST be a valid value for the
Content-Language header as defined in [RFC822] and extended in [RFC1766].

Errors

 Invalid directive syntax
 Not compatible with version
 Server not capable of using client defaults

Examples

Content-Type: application/rwhois-directive;

rwhois
Protocol-Version: V-2.0
Implementation: InterNIC B.0.9.7
Default-Content-Encoding: 8bit
Default-charset: ISO-8859-1
Default-Content-Language: en-US
=2E
 Directive ok
=2E

3.3.2 directive

Description

The "directive" directive can be used by the client to get information about
the directives that the server supports. The response must contain the name
and description of each specified directive and may be expanded in the
future with additional attributes. When no directive name is given, the
server must return information about all the directives.

As with other directives, the result is an object of the Directive class
and, as such, can also be returned by a standard query against that class.

ABNF

directive-dir =3D "directive" *(space directive-name) crlf
directive-query =3D "query Class-Name=3Ddirective" *(space directive-name) crlf
directive-name =3D 1*id-char

Errors

 Invalid directive syntax
 Directive not available
 Not authorized for directive

Examples

Without parameters:

directive
=2E
Content-Type: multipart/mixed; boundary=3D"foo"

- --foo
Content-Type: text/directory; profile=3Drwhois-directive

directive:query
description:RWhois query directive. Used to retrieve an object.
- --foo
Content-Type: text/directory; profile=3Drwhois-directive

directive:directive
description:RWhois directive directive
- --foo
Content-Type: text/directory; profile=3Drwhois-directive

directive:limit
description:RWhois limit directive used to limit the number of hits.
- --foo--
=2E

With parameters:

directive quit
=2E
Content-Type: text/directory; profile=3Drwhois-directive

directive:quit
description:Quit connection
=2E

3.3.3 display

Description

By default, the server returns a text/directory representation of an object
in a result set. This default format can be changed with the "display"
directive. When no parameter is given, the server must list all the display
formats it supports.

ABNF

display-dir =3D "display" crlf
/ "display" space IMT crlf
display-response =3D *display-record
display-record =3D "name" ":" IMT crlf *display-line crlf crlf
display-line =3D attribute-name ":" attribute-value crlf

Errors

 Invalid directive syntax
 Directive not available
 Not authorized for directive
 Invalid display type

Examples

# Get the available display formats.
display
=2E
name:text/directory

name:text/html

name:text/plain
=2E

# Change the active display format.
display text/plain
=2E
 Directive ok
=2E

3.3.4 forward

Description

The "forward" directive instructs the server to follow all referrals and
return the results to the client. This directive can be used to run an
RWhois server as a proxy server. The default value must be "off". When the
value is set to "on", the server must not return referrals.

ABNF

forward-dir =3D "forward" space on-off crlf

Errors

 Invalid directive syntax
 Directive not available
 Not authorized for directive

Examples

forward on
=2E
 Command ok
=2E

forward off
=2E
 Command ok
=2E

3.3.5 limit

Description

When returning a query result, the server should limit the number of objects
returned to the client. The "limit" directive changes this limit. The
default and maximum limit is server-dependent. The client can get the
current limit by using the "status" directive (see Section 3.3.13).

ABNF

limit-dir =3D "limit" space 1*digit crlf

Errors

 Invalid limit
 Invalid directive syntax
 Directive not available
 Not authorized for directive

Examples

limit 100
=2E
 Command ok
=2E

3.3.6 notify

Description

The "notify" directive performs several functions.

   * If the server returns a referral that results in an error, the client
     can report the bad referral to the server using the "badref" option.
   * When the client follows referrals and goes through the same referral
     twice, that referral is a recursive referral and causes a referral
     loop. The client can report the recursive referral to the server using
     the "recurref" option.
   * When the data in an authority area changes, a master server can use the
     "update" option to notify its slave servers to update the data.
   * The "inssec" option allows an RWhois server to register itself as a
     slave server for an authority area with a master server. The master
     server may reject the request on the basis of its registration policy.
   * The "delsec" option allows a slave server to cancel its registration
     with the master server.

ABNF

notify-dir =3D "notify" space "badref" space referral-url crlf
        / "notify" space "recurref" space referral-url crlf
        / "notify" space "update" space host-port ":" authority-area crlf
        / "notify" space "inssec" space host-port ":" authority-area crlf
        / "notify" space "delsec" space host-port ":" authority-area crlf
referral-url =3D rwhois-url / uri

Errors

 Invalid directive syntax
 Invalid authority area
 Invalid host/port
 Directive not available
 Not authorized for directive

Examples

The client reports a bad referral to rwhois.foobar.com to the server:

notify badref rwhois://rwhois.foobar.com:4321/class=3Ddomain%20 \
    auth-area=3Dfoobar.com
=2E
 Directive ok
=2E

The client reports a recursive referral to rwhois.foobar.com to the server:

notify recurref rwhois://rwhois.foobar.com:4321/class=3Dcontact%20
   auth-area=3Dfoobar.com%20Last-Name=3D"Beeblebrox"
=2E
 Directive ok
=2E

The master server for the foobar.com authority area notifies its slave
servers to update the data:

notify update master.foobar.com:4321:foobar.com
=2E
 Command ok
=2E

The server rwhois2.foobar.com registers as a slave server for the foobar.com
authority area:

notify inssec rwhois2.foobar.com:4321:foobar.com
=2E
 Command ok
=2E

The server rwhois2.foobar.com cancels its registration as a slave server for
the foobar.com authority area:

notify delsec rwhois2.foobar.com:4321:foobar.com
=2E
 Command ok
=2E

3.3.7 quit

Description

The "quit" directive can be used by the client to close the connection.
Before the server closes the connection, it must respond with the "203
Goodbye" response.

ABNF

quit-dir =3D "quit" crlf "." crlf
quit-response =3D response

Errors

No errors.

Examples

quit
=2E
 Goodbye
=2E

3.3.8 register

Description

The "register" directive can be used by the client to add, modify, or delete
objects in the server's database.

The "register" directive is slightly different than most directives in that,
instead of simply receiving one application/rwhois-directive object, the
server receives a multipart/related body whose 'start' parameter points to
the application/rwhois-directive object that contains the "register"
directive. The "register" directive can contain any number of operations and
any combination of those operations. These operations must be considered
atomic with respect to the other operations within the directive. For
example, a "register" directive contains three adds and three mods. If any
one of these operations fails, they ALL fail.

An operation within a register directive can also contain multiple objects
on which the operation must be done. These must also be considered atomic;
if the operation fails for any object, the whole operation fails (and thus
the entire "register" directive fails).

The operations available within a register directive are:

   * The "add" option indicates that the object being sent should be added
     to the server's database. The objects are identified by their
     content-ids.
   * The "mod" option indicates that the object being sent is a modification
     of an object that already resides on the server's database. These
     database objects are identified by their IDs and updated times. The
     objects to replace them are identified by their content-ids.
   * The "del" option indicates that the objects being sent should be
     deleted from the server's database. The database objects are identified
     by their ID and updated times.

After a register operation (add, modify, or delete an object) in an
authority area, the server should update the "Serial-Number" variable in the
SOA information for the authority area. This is useful for data replication,
because a slave server checks the "Serial-Number" variable to detect a data
change at the master server (see Section 3.6.2).

ABNF

register-dir =3D "register" crlf *(register-line crlf)
register-line =3D  "add:" register-add-tuple *( register-add-tuple )
        / "mod:" space register-mod-tuple *( space register-mod-tuple )
        / "del:" space register-del-tuple *( register-del-tuple )
register-add-tuple =3D space cid
register-del-tuple =3D rwhois-id "," rwhois-updated
register-mod-tuple =3D rwhois-id "," rwhois-updated "," cid

register-updated =3D time-stamp
register-response =3D register-response-header crlf  *(register-operation- -result)
register-response-header =3D "241" space register-response-text
register-response-text =3D 1*any-char
register-operation-result =3D "object:" space cid rwhois-id rwhois-updated crlf

   * For the "add" operation, the client must send all required attributes
     for the object, including the Class-Name and Auth-Area attributes.
     However, the client must not send the ID and Updated attributes. These
     attributes are assigned by the server and returned in the response.
   * The rwhois-response contains references only to those objects who were
     added. The cid is used to identify the object to the client. The ID and
     rwhois-updated fields are those that were assigned by the server at the
     moment the object was inserted into the database.

Errors

 Registration deferred
 Register complete
 Invalid attribute
 Invalid attribute syntax
 Required attribute missing
 Object reference not found
 Primary key not unique
 Failed to update outdated object
 Object not found
 Invalid directive syntax
 Invalid authority area
 Invalid class
 Directive not available
 Not authorized for directive

Examples

# Add an object.
Content-Type: multipart/related; type=3Dapplication/rwhois-directive;=20
 start=3Dcid1@foo.com; boundary=3Dexample-1

- --example-1
Content-Type: application/rwhois-directive
Content-ID: <cid1@foo.com

register
Add: <cid2@foo.com>
Mod: 23456789.a.com,19961205124403000,<cid3@foo.com>
Del: 23456789.a.com,19961205224403000
- --example-1
Content-Type: text/directory
Content-ID: <cid2@foo.co>

Class-Name:contact
Auth-Area:a.com
First-Name:Scott
Last-Name:Williamson
Name:Williamson, Scott
Email:scottw@a.com
- --example-1
Content-Type: text/directory
Content-ID: <cid3@foo.com>

Class-Name:contact
Auth-Area:a.com
ID:23456789.a.com
First-Name:Scott
Last-Name:Williamson
Name:Williamson, Scott
Email:sw@a.com
- --example-1--
=2E
 Register complete
Object: <cid2@foo.com> 23456789.a.com 19961205224403000
Object: <cid3@foo.com> 56789.a.com 19961205224404444
=2E

3.3.9 class

Description

The "class" directive is used by the client to get the meta-information for
one or more classes in an authority area. The response is an object of the
type Class. This directive and the Attribute directive work together to
specify other classes.

The version number of each specified class may be expanded in the future
with additional attributes. When no class name is given, the server must
return the meta-information for all of the classes in the authority area.

As with the Attribute directive, this directive can also be handled via a
query of the Class class. Thus, the following two ABNF grammars must be
considered equal:

ABNF

class-dir =3D "class" space authority-area *(space class-name) crlf
class-query =3D "query Class-Name=3DClass auth-area=3D" authority-area
*(space "Name=3D" class-name space "or") crlf

See Section 3.3 for information on directive and query equality. The
response to this directive/query is either an error or a result set of CLASS
objects. See Section 4.2.2 for the definition of a CLASS object.

Errors

 Invalid directive syntax
 Invalid authority area
 Invalid class
 Directive not available
 Not authorized for directive

Examples

class rwhois.net domain host
=2E

or

query Class-Name=3DClass and auth-area=3Drwhois.net and Name=3Ddomain or Name=3Dhost
=2E

3.3.10 attribute

Description

The "attribute" directive can be used by the client to get attribute
definitions. Each definition is complete by itself. It is up to the Class
object to aggregate Attribute objects together to define a new Class. As
with the "class" directive, this directive can be handled via a standard
query of the Attribute class.

ABNF

attribute-dir =3D "attribute" space authority-area
       *(space class-name:attribute-name) crlf
attribute-query =3D "query Class-Name=3Dattribute"
                  (" and auth-area=3D" authority-area)
*(space "and Name=3D" attribute-name) crlf

Errors

 Invalid directive syntax
 Invalid authority area
 Invalid class
 Directive not available
 Not authorized for directive

Examples

attribute map
=2E
Content-Type: multipart/mixed; boundary=3Dexample1

- --example1
Content-Type: text/directory

attribute:Class-Name
description:Type of the object
type:TEXT
format:re:[a-zA-Z0-9-]+
indexed:OFF
required:ON
multi-line:OFF
repeatable:OFF
primary:OFF
hierarchical:OFF
private:OFF
- --example1
Content-Type: text/directory

attribute:ID
description:Globally unique object identifier
type:TEXT
format:re:[0-9]+\.[a-zA-Z0-9\.-]+
indexed:ON
required:ON
multi-line:OFF
repeatable:OFF
primary:ON
hierarchical:OFF
private:OFF
# This is an abbreviated example, more attributes usually follow.
- --example1--
=2E

3.3.11 security

Description

The "security" directive enables either a client request or a server
response to be authenticated and/or encrypted. This directive can be used to
securely access or update any information (meta or data) in an authority
area that is protected by one or more guardian objects.

This is an area that needs further work. The examples below that use
encrypted passwords and Pretty Good Privacy (PGP) are for illustrative
purposes only.

ABNF

security-dir =3D "security" space "on" space direction space security-method=20
  [space security-data] crlf security-payload ["-security" space "off" crlf]
direction =3D "request" / "response"
security-method =3D "password" / "pgp" / 1*id-char
security-data =3D password-data / pgp-data / 1*any-char
password-data =3D 1*any-char
pgp-data =3D "signed" / "encrypt" [space key-id] / "signed-encrypt" [space key-id]
security-payload =3D *(*any-char crlf)
security-response =3D "251" / "252" security-response-text crlf "." crlf
security-response-text =3D 1*any-char

   * The "password" security-method is available in the "request" direction
     only. For password, the security-data is a cleartext password.
   * The "pgp" security-method is available in both the "request" and
     "response" directions. For PGP, the security-data indicates how to
     treat the security-payload: signed, encrypted, or signed and encrypted.
     To encrypt the security-payload in the "response" direction, the
     security-data must include the public key ID with which to encrypt it.

Errors

 Security mode on
 Security mode off
 Invalid directive syntax
 Invalid security method
 Authentication failed
 Encryption failed
 Directive not available
 Not authorized for directive

Examples

# Authenticate a request using password.
security on request password hello!1
=2E
 Security mode on
=2E

# Authenticate a PGP signed request.
security on request pgp signed
=2E
 Security mode on
=2E
Content-Type: multipart/related; type=3Dapplication/rwhois-directive;=20
  start=3D<cid1@foo.com; bounday=3Dexample1

- --example1
Content-Type: application/rwhois-directive
Content-ID: <cid1@foo.com

register
Add: <cid2@foo.com
- --example1
Content-Type: application/rwhois-directive
Content-ID: <cid2@foo.com

- -----BEGIN PGP MESSAGE-----
Version: 2.6.2

owHrZJjKzMpgdP9D9crUhdpBYnwHGRnPbmVhmHlV7Hef9je/n7vyzhmE6589/+Dg
jPpVm59tNz92vPSmrFB/4ankBRz+xgY+7z9OUYjefGahbWSNwzzxbw6TpWZGerU+
uOUg/Cygs33JBdHqjwEc+wyfZPp+N5p2bu+ywoaOu8eLPyn+m2Mt/T9p1UaG68vP
Zd2d9EPw+Ywpio7dco6yh3b/v7zmQxJHcWpyaVFmSSUDEHi6WBkZm5iamVtY6iXq
JefnKnCFFqQklqSmWBlaWpoZGhmYGhqZmBgYGxgYKHA55yQWF+v6JeamWiXn55Uk
JpcocDmWlmToOhalJlpB9cf7uYbHE6kWi/VumUXFJRB9wcn5JUBdPokwgfDMnJzM
xNzi/DwFLjQBHQWoatfcxMwcq+JyB6h5AA=3D=3D
=3Da0sQ
- -----END PGP MESSAGE-----
- --example1--
=2E
 Register complete
Object: <cid2@foo.com 23456789.a.com 19961205224403000
=2E
security off
=2E
 Security mode off
=2E

# Encrypt a response using PGP. 52160EC1 is the public key ID with which
# the response is encrypted.
security on response pgp encrypt 52160EC1
=2E
 Security mode on
=2E
xfer com class=3Ddomain attribute=3DDomain-Name attribute=3DOrganization-Name
=2E
Content-Type: application/pgp-signed-XXX

- -----BEGIN PGP MESSAGE-----
Version: 2.6.2

hIwDqWWhK1IWDsEBBACOXssTzD2CbB7Vjj2cNURScpJc2as2TbUDOQiwkT+8qFgG
ZyRfktpwNNTawRIcGOk1Kcs84z8a3vvTA/oje9vZexHtzfJwBHFdiIZxPuCEpvgv
2ppK7WqlmHGcQKVBJJHYw7Fq83CUkeGJB9P1M3CQiXeW8h8MwAuhxSgbgt23PKYA
AABuhknJrXeh9Owm81+MvyzgLOyM7sjDYmttU9sj/yuOYmAhS9V+34MT/Mwn4wO8
2BCsJqBHXbwOuYKs02p0se4jyKFtZR8MDPWNm9QyAP+oNMTjsufy6ZRa9PegUC6t
HDhXymkiP03mKMMVK1//7X0=3D
=3DvZ2x
- -----END PGP MESSAGE-----
=2E
security off
=2E
 Security mode off
=2E

3.3.12 soa

Description

The "soa" directive can be used by the client to retrieve the SOA
information for one or more authority areas. When no authority area name is
given, the server must return the SOA information for all the authority
areas.

As with the Class and Attribute directives, this directive can also be
handled via a query of the SOA class. Thus, the following two ABNF grammars
must be considered equal:

ABNF

soa-dir =3D "soa" *(space authority-area) crlf
soa-query =3D "query" space "auth-area=3D" authority-area crlf "." crlf

The server must return the following SOA information for an authority are=
a.
This information is also included in Section 4.3.2, which describes the SOA
class.

 attribute-nameattribute-value Comments

 authority     authority-area  This is the name of the
                               authority area.
                               This is the default time-to-live
 ttl           1*digit         for the data in the authority
                               area.
                               This is the serial number of the
 serial        time-stamp      data in the authority area; it
                               changes when the data changes.
                               This is the time interval before
 refresh       1*digit         a slave server checks for
                               complete replication.
                               This is the time interval before
 increment     1*digit         a slave server checks for
                               incremental replication.
                               This is the time interval before
 retry         1*digit         a slave server tries again to
                               connect to a master server that
                               appears to be out-of-service.

 tech-contact  email           This is the contact for the
                               operation of the master server.

 admin-contact email           This is the contact for the data
                               integrity at the master server.
                               This is the contact for sending
 hostmaster    email           update requests at the master
                               server.
                               This is the host name (or IP
 primary       host-port       address) and port number of the
                               master server.

Errors

 Invalid directive syntax
 Invalid authority area
 Directive not available
 Not authorized for directive

Examples

soa org
=2E
Content-Type: text/directory; profile=3D"rwhois-soa"

authority:org
ttl:86400
serial:19961119111535000
refresh:3600
increment:1800
retry:180
tech-contact:tech@internic.net
admin-contact:admin@internic.net
hostmaster:hostmaster@internic.net
primary:rs.internic.net:4321
=2E

3.3.13 status

Description

The "status" directive can be used by the client to retrieve an object
belonging to the Status class, which is used to contain various status flags
for the server. The result must include the number of objects in all of the
authority areas, the current display format, the server contact information,
and the status flags for the state-oriented directives: "limit" and
"forward".

Since the directive returns a result, it can also be handled by a query
against the Status class. Since the client has no way of knowing the values
in advance, the only thing the client can ask for is the Class itself.

ABNF

status-dir =3D "status" crlf
status-query =3D "query Class-Name=3Dstatus"

Errors

 Invalid directive syntax
 Directive not available
 Not authorized for directive

Examples

status
=2E
Content-Type: text/directory; profile=3Drwhois-status
limit: 20
forward: OFF
objects: 12345
display: text/directory
contact: joe@rwhois.net
=2E

3.3.14 xfer

Description

The "xfer" directive can be used by the client (generally, a slave server)
to transfer the data in an authority area. The client can control the amount
of data transferred using one of the following options. NOTE: The "xfer"
directive is identical to the "query" directive. It is included for backward
interoperability.

Updating secondary servers is a work in progress. Specifically, some method
is needed for sending information on what was deleted. Some of these same
issues arose during discussions of incremental updates in CIP and the same
problems developed.

In RWhois 1.5, the "xfer" directive had several options. Below are
descriptions of how these options should be handled:

   * serial-number: In 1.5, the client can transfer all the objects that
     have been added, modified, or deleted since a certain time, specifying
     the serial-number that indicates that time. This option was used for
     incremental replication. In 2.0, this function is handled by querying
     for objects that have an updated time that is after the time specified
     in the serial-number.
   * class: In 1.5, the client could limit the data transfer to one or more
     classes, using the "class=3D<class-name>" option. This is handled simply
     by specifying the class or classes to which the query would apply.
   * attribute: In 1.5, the client could limit the data transfer to one or
     more attributes of a class. In 2.0, this is handled by the INCLUDE
     global constraint.

Implementers are encouraged to implement security surrounding queries that
exhibit security problems. The XFER behavior is one of these.

3.3.15 X-

Description

The "X-" directive is used to specify an additional, non-standard directive.
It can be implemented by executing an external program, by internal
functions, or by other means. It may interact with the client or simply
produce output like one of the standard directives.

ABNF

x-dir =3D "X-" x-directive [space x-arguments] crlf *x-line "." crlf
x-directive =3D 1*id-char
x-arguments =3D *any-char
x-response =3D "X6X" x-response-text *(*any-char crlf) crlf "." crlf
x-response-text =3D 1*any-char
x-line =3D *any-char crlf

Errors

 Invalid directive syntax
 Directive not available
 Not authorized for directive

Examples

The following example uses an implementation that executes an external
program, the UNIX "date" command. The server runs the "date" command and
returns its output to the client.

X-date
=2E
 X-date output
Mon Jan 6 13:21:20 EST 1997
=2E

4.0 Data Model

The RWhois protocol is primarily concerned with directory-services-type
information. Historically, this has been formatted in a series of
colon-delimited attribute/value pairs. Thus, the RWhois protocol's primary
interaction will be via encoded A/V pairs. In addition to these types, it is
also apparent that RWhois will need to deal with objects of different types
such as the image of a particular user, a company=92s logo, or an encoded
representation of a sales pitch. It is also recognized that in the future
other directory services encoding formats that have a richer markup language
may become popular. Astute readers may pay attention to the interaction
between SGML and MIME for future application to the world of directory
services.

The A/V type objects have a specific base class from which all objects are
derived. In addition to the base class, there is the schema object, which is
used to define other objects that inherit from the base class.

4.1 Base Class

While RWhois does not have or advocate using a specific, standardized
schema, it does impose a few requirements. It requires that all defined
classes inherit attributes from a particular base class (or base schema).
The RWhois specification does not require the actual implementation of
inheritance. Instead, all classes must include the attributes defined in the
base class.

The base class has the following attributes.

             This attribute contains the name of the class to which the
Class-Name   object belongs. It is the type of the object itself. It is
             of type TEXT and is required.
             This attribute contains the name of the authority area to
Auth-Area    which the object belongs. It, along with Class-Name,
             definitively defines the type of the object. It is of type
             TEXT and is required.
             This attribute is a universal identifier for the object. It
             is formed by choosing a string that is unique within an
             authority area and appending the authority area to it,
             separating the local string from the authority area name
ID           with a period. The only restrictions on the local string are
             that it must be unique within the authority area and must
             not contain the period character. This attribute is
             hierarchical in nature. It is always generated by the server
             (for example, during a register operation). It is of type
             TEXT and is required.
             This attribute is a time/date stamp that indicates the time
             of last modification of the object. It is both informational
Updated      and a form of record locking. It prevents two clients from
             modifying the same object at the same time. It is of type
             TEXT and is required.
             This attribute is a link to a guardian object (described
Guardian     below). Its value is the ID of a guardian object. It is of
             type ID and is optional. It is repeatable, since an object
             may have multiple guardians.
             This attribute is a true or false flag that indicates
             whether or not an object is private (that is, not publicly
             viewable). It defaults to false. If it is true, only the
Private      clients that satisfy the authentication/encryption
             requirements of one of the object's guardians are able to
             view the object. If the object is publicly viewable, then
             the Private attribute property of each of its attributes
             still applies.
             This attribute is the "time-to-live " of a given object. It
             is included only if an object has a different time-to-live
TTL          than the default given in the Start of Authority
             information. Its value is specified in seconds. It is of
             type TEXT and is optional.

4.2 Defining a New Class

One of the more useful but underutilized aspects of X.500 is the encoding of
a particular attributes=92 definition within the actual protocol. The problem
was that its existence was not discoverable.

In this version of RWhois, this feature is specifically made to be part of
the protocol. Thus, two objects are specified: "Attribute" and "Class".
"Attribute" is used to define objects that describe the characteristics of
an attribute. The "Class" class is used to define a class of objects by
specifying the "Attribute" objects that make up the class.

4.2.1 Attribute Class

Attributes have a number of properties, some mandated by the RWhois protocol
and some that are implementation dependent. These properties are usually a
reflection of the database system used by the server. The following is a
list of the protocol-mandated properties and their descriptions.

Attribute   This is the name of the attribute.
Description This is a natural-language description of the attribute.
            This is a parameter that broadly indicates the use of the
            attribute to the protocol. There are three standard types:
            TEXT, ID, and SEE-ALSO. The default is TEXT, which indicates
            that the value is a text string. ID indicates that the
Type        attribute contains the ID of another RWhois object; this type
            of attribute is used for database normalization. SEE-ALSO
            indicates that the attribute contains a pointer (a Uniform
            Resource Identifier (URI)) to some other kind of external
            data; for example, a World Wide Web page or FTP site.
            This is an interpretable string that describes the acceptance
            format of the value. The server (and optionally the client)
            should match the value to the format string to determine if
Format      the value is acceptable. The format of this property is a
            keyword indicating the syntax of the format string, followed
            by a colon, followed by the format string itself. Currently,
            the only keyword recognized is "re" for POSIX.2 extended
            regular expressions.

Indexed     This is a true or false flag indicating that this attribute
            should be indexed (and therefore able to be searched).

Required    This is a true or false flag indicating that this attribute
            must have a value in an instance of the class.
            This is a true or false flag indicating that there may be
            multiple instances of this attribute in a class and each
Repeatable  instance is to be interpreted as a separate instance (in
            contrast to Multi-Line). This flag is mutually exclusive with
            Multi-Line: if Multi-Line is true, then Repeatable must be
            false and vice versa.
            This is a true or false flag that indicates that this
            attribute is a primary key. If more than one attribute in a
            class is marked as primary, then these attributes together
Primary     form a single primary key. The primary key is intended to be
            used to force uniqueness among class instances. Therefore,
            there can be only one instance of a primary key in a
            database. The Primary flag implies that the attribute is also
            required.
            This is either a regular expression or a URI. If it is a
            regular expression, any value should be matched with the
Hierarchicalregexp to find the character(s) that form the separator
            between each sub-part. If it is a URI, the URI is used to
            uniquely identify a well known rule set that is used to
            define how hierarchy is expressed in a given value.
            This is a true or false flag that indicates whether or not
            this attribute is private (that is, not publicly viewable).
Private     It defaults to false. If it is true, only the clients that
            satisfy the authentication/encryption requirements of a
            guardian (described below) are able to view the
            attribute-value pair.

4.2.2 Class Class

A class is not as difficult to specify as an attribute, since the class is
defined by its attributes. Thus, the only required attribute is the ID of
the attribute objects contained within the class. Additionally, a
description of the class should be included for human discovery and
searching. The following attributes make up the "Class" class.

Description   This is the free-text description of the class that is
              intended for the consumption of the user.
              This is the link-style attribute that points to the
Attribute-NameAttribute object(s) that make up this class by using the ID
              of the object. This attribute is repeatable.

Constructor   This is a URI that identifies an object that acts as the
              Constructor for objects that belong to the defined class.

The constructor is used to create new objects since all of the semantics
associated with creating an object would be nearly impossible to express in
the Attribute definition. For example, an Attribute object might define a
given attribute to be an IP address. A client would know what to do with an
IP address. But the semantics for how to assign an IP address are simply too
complicated to express without some programming language. This is an area
for additional standardization.

4.3 RWhois Standard Schemas

The following RWhois standard schema definitions are required for any RWhois
installation that wishes to participate in the RWhois tree. The RWhois tree
is a mapping of referrals from one RWhois server to another.

Every schema defined below inherits the base result class defined above. The
attributes defined in Base Schema as REQUIRED will still be REQUIRED in
RWhois standard schemas, while the OPTIONAL attributes will still be the
OPTIONAL.

4.3.1 Referral Class

The referral class is defined to hold referral information (typically for
link referrals). It consists of attributes defined as part of the base
class, the protocol-specific attributes described below, and any
installation-specific attributes.

                 This attribute contains the referral itself; it is an
                 RWhois URL. It is of type TEXT and is required. It is
                 repeatable, since more than one server can host a
Referral         Referred-Auth-Area. In RWhois 1.5, the referred
                 authority area was in a separate field. In this version,
                 the authority area MUST be included within the URL
                 contained in this field.

4.3.2 SOA Class

Each authority area has some administrative variables, defined at the master
server, to control data replication. These variables are called the SOA
variables. They are listed below.

                  This is the serial number of the data in an authority
Serial-Number     area. The master server should update this variable
                  whenever the data in the authority area is changed. Its
                  value is a time/date stamp.
                  This is the time interval before a slave server checks
Refresh-Interval  for complete replication. Its value is specified in
                  seconds.
                  This is the time interval before a slave server checks
Increment-Intervalfor incremental replication. Its value is specified in
                  seconds.
                  This is the time interval before a slave server tries
Retry-Interval    again to connect to a master server that appears to be
                  out-of-service. Its value is specified in seconds.
                  This is the default time-to-live for the data in an
Time-To-Live      authority area at a slave server. The slave server
                  should not answer authoritatively to queries for such
                  stale data. Its value is specified in seconds.
                  This is the minimum time interval for which a server
                  will keep information about the deletion of a given
Time-To-Die       object. If a slave server asks for an update after this
                  time has expired, it may not receive information that a
                  given object was deleted.
                  This is the email address of an individual or a role
Admin-Contact     account responsible for the data integrity in an
                  authority area at the master server.
                  This is the email address of an individual or a role
Tech-Contact      account responsible for the operation of the master
                  server for an authority area.
                  This is the email address of an individual or a role
Hostmaster        account to whom email messages to update the data in an
                  authority area at the master server are sent.
                  This is the location of the master server for an
Primary-Server    authority area. Its value must contain both the host
                  name (or IP address) and port number of the master
                  server.

4.3.3 Guardian Class

The guardian class is defined to hold security information. The fundamental
concept behind the guardian class is that an object (or another structure)
is "guarded" by containing a pointer to a guardian object [Guardian]. To
modify, delete, or possibly view the guarded object, the authentication (or
encryption, or both) scheme must be satisfied. Guardians are intended to not
have rank: if an object is guarded by more than one guardian object,
satisfying any one of those guardians is sufficient. A guardian object that
does not have any Guardian attribute linking it to other guardians guards
itself. That is, the authentication scheme in the guardian object itself
must be satisfied to modify, delete, or possibly view it.

Guardian objects are typically linked to actual database objects with the
Guardian attribute found in the base class. However, a guardian may also be
linked to an entire authority area, in which case the guardian becomes
implicitly linked to all of the objects contained within the authority area.

The guardian class consists of the base class, the protocol-specific
attributes described below, and any installation-specific attributes.

            This attribute contains a keyword indicating the
            authentication methodology. Its value must be
Guard-Schemeunderstood by both the client and server, and its
            value dictates the contents of the Guard-Info
            attribute. It is of type TEXT and is required.
            This attribute contains that data that is used by
            the Guard-Scheme to verify the authentication. Its
            actual format is dictated by the Guard-Scheme, for
Guard-Info  example, it could contain a password or PGP public
            key id [RFC 1991]. For security reasons, it should
            not be displayed, and its Private attribute
            property should be set to true. It is of type TEXT
            and is required.

4.3.4 Status Class

This class is used to define objects that are used to store the current
status of the server. As with any object text/directory object, locally
defined attributes can be added to the object that are not defined by that
object=92s class definition. This class will be subject to such treatment, as
certain server implementations will want to return additional implementation
specific information.

It is important to note that querying this class is usually meaningless,
since the client should not know the values in advance. Objects of this type
are usually created as they are returned. See the 'status' directive for how
to ask for an object of this class.

Limit       This is the current hit limit.
Forward     This is the status of the Forward flag.
Objects     This is the current number of objects stored by the server.
Display     This is the current display type.
Contact     This is the email address of the server maintainer.

4.3.5 Directive Class

This class is used to define objects that describe the directives currently
supported by the server in question. See the 'directive' directive for more
information on this class and how to query it.

Directive-NameThis is the name of the directive as it should be entered
              to invoke it.

Description   A natural-language description of what the directive does,
              that is intended for human consumption.

4.3.6 TOC Class

This class is used to =91point=92 to other objects in a multipart/related
result. It is not normally queried and doing so may simply not make sense.
There is only one attribute/value pair which will usually be repeated
several times.

Object      The value for this attribute contains information about each
            object contained within the multipart/related object.

The format of the value follows the following ABNF:

value =3D cid [directory-profile] [rwhois-id] [user-string]

directory-profile =3D 1*any-char

user-string =3D 1*any-char

directory-profile is the value of the profile attribute of the
application/directory object who=92s content-id is contained in cid.

user-string is descriptive text formed from the object itself and is meant
as a summary of the object so that the TOC object can be displayed somewhat
like a menu. How this descriptive string is formed is completely
implementation specific.

5.0 Search Model

The search model is made up of four distinct aspects. There is the query
itself, which is specified by the client. The server then takes that query
and looks in its local database. If it finds an appropriate object, it
returns the results. If it cannot find an appropriate object, the server
uses query reduction to find a referral to a server that may know more about
the object in question. Returned objects can also have a see-also, which
provides a pointer to another object that contains additional information
that may be of use to the client.

5.1 Query

The query is generally the final directive sent to the server. The query is
the question that the client wants the server to answer. It has two primary
parts: the query terms themselves and global constraints that apply to the
entire query and the display of its output. There is a similarity between
this query syntax and the whois++ query syntax, but there are differences.

Format for Use:

query <query terms>:<global constraints>;<global constraints>;...

A query term is defined as one or more terms followed by an optional
semicolon and one or more local constraints. Local constraints are bound
only to the term they follow. All local constraints can be global
constraints, but only some global constraints make sense as local
constraints.

Terms can be separated by the logical operators AND, OR, or NOT. The lack of
an operator between two terms MUST be interpreted as an implicit AND. A term
itself can have several formats.

  1. A value string by itself is considered a search on all attributes.
  2. A term followed by a semicolon and a semicolon-delimited list of local
     constraints.
  3. An attribute specifier or an abbreviated attribute specifier followed
     by an "=3D" and a single value string followed by an optional semicolon
     and a semicolon delimited list of local constraints.

Special characters that need to be quoted are preceded by a backslash (\).
Special characters are space (' '), tab, equal sign (=3D), comma (,), colon
(:), backslash (\), semicolon (;), asterisk (*), period (.), parenthesis
[()], square brackets ([]), dollar sign ($), and circumflex (^).

NOTE: Unlike the whois++ syntax, values may be enclosed within double
quotes. In this case the only values that need to be escaped are '"'.

Example query:

query Name=3D"Scott Williamson";Language=3Den;Charset=3DISO-8859-1 AND \
 Country=3Dus:output=3DMIME

NOTE: The query should be all on one line. In the above example, the query
is continued over two lines for readability only.

5.2 Constraints

Local constraints are generally used to override some global constraint or
default. Any local constraint can be a global constraint.

There are two groups of Global constraints: those that make sense only in
the query and those that are also directives in their own right. For
example, specifying a global query match type of regular expression makes no
sense for other types of client/server interaction. Thus, it only appears in
the query. Setting a language and/or character set, on the other hand, has
value for other functions such as info directives and schema definitions.

Experimental constraints can be constructed by using the "X-" convention
used by many protocols.

 Constraint       Allowed Values         Local or   Equivalent
                                          Global    Directive

SEARCH      { exact-string | regex |   LOCAL/      search
            fuzzy | substring | }      GLOBAL
LIMIT       { 1-<max-allowed> }        GLOBAL      limit

CASE        { ignore | consider }      LOCAL/      case
                                       GLOBAL

INCHARSET   { us-ascii | iso-8859-* }  LOCAL/      rwhois
                                       GLOBAL

LANGUAGE    <As defined in ISO         LOCAL/      language
            639:1988>                  GLOBAL
IGNORE      {attributelist}            GLOBAL      ignore
INCLUDE     {attributelist}            GLOBAL      include

CLASS       {NAME of a valid object    LOCAL/
            type}                      GLOBAL

AUTH_AREA   {NAME of a valid authority LOCAL/
            area}                      GLOBAL

NOTE: IGNORE is used to specify attributes that should specifically be
ignored when searching and displaying a given class of objects. Conversely,
INCLUDE is used to specifically ignore all cases except those specified in
the INCLUDE's values.

5.3 Query Reduction

The critical component of the RWhois server is the ability to reduce the
query to find a server that is closer to the data. One of the fundamental
changes between Version 1.5 of RWhois and this version is that the reduction
rules for a given schema are much more codified. For any given schema
definition, a given A/V pair is denoted as being hierarchical in nature.
Whenever this is noted, a rule must be given in the schema definition that
specifically defines what the separation token for each reducible part is.
The rule is given as either a Posix Extended Regular Expression or URI. The
URI is used both to uniquely identify the rule being used and also to
retrieve that rule if some method for doing so is used in the future.

5.3.1 Search Algorithm

  1. Accept a query.
  2. Find any local matches; display them.
  3. Find any referrals; display them.
  4. If no local or referral hits, reduce the query and go to Step 3.

Here is an example of the query ietf.cnri.reston.va.us:

Query whois for ietf.cnri.reston.va.us.

  1. Search rs.internic.net for information (no hits).
  2. Search referrals for ietf.cnri.reston.va.us (no hits).
  3. Search referrals for cnri.reston.va.us (no hits).
  4. Search referrals for reston.va.us (no hits).
  5. Search referrals for va.us (no hits).
  6. Search referrals for us (referral found)=97referral to isi.edu.

[currently on rs.internic.net:4343 for proof of concept]

5.3.2 Reduction Rules

As specified in the schema definition section, each object type must specify
which of its A/V pairs are hierarchical (e.g., reducible). With that
specification comes a regular expression that states what the token is for
understanding what the separator is between each of the reducible parts. The
default will be "/\./", which matches a period. This default is used for the
majority of the searches, as it is used for domain names and IP addresses. A
good example would be HTTP-based URLs. Its rule would match on "/" and "."
thus giving a way to resolve URLs based on other criteria than simply
hostname and path. Other examples are ISBN numbers and OIDs.

5.4 Referral

The result profile referral instructs the client to query another server,
which could be a Whois, RWhois, LDAP, or Whois++ server. Since the primary
referral field is in the form of a URI, the referral can happen to any
server via any protocol. If this is the case, many of the assertions made
here with respect to up or down referrals are considered meaningless.

Referrals are cumulative, and the first referral received during a session
must replace the default server list. Any subsequent referrals received must
be appended to the end of the server list. The type of a referral can be
determined by the client evaluating the authority area, which is part of the
referral RWhois URI response.

If the authority area received from a referral response is equal to the
original query, then it is a link referral. If the authority area is not
equal to the query, then it is a reduction referral. If no authority area is
sent, then it is a punt referral. Punt means the server is not a root and
cannot answer the query, and is therefore referring the client to a level up
the tree or to a server that can better answer the query. NOTE: The punt
referral may be used to direct a client into a CIP mesh.

The client may receive multiple referrals from a single query. If the SOA
for each of these referrals is the same, then the first referral is the
primary server and all subsequent servers are secondary. Each of the servers
will report the SOA for the authority area in question.

5.5 Other Elements Affecting Query Completion

Earlier versions of RWhois contain the concept of a 'see-also'. This
response was used to direct a client to additional information outside an
RWhois tree. In this version of the protocol, this functionality is handled
by the text/directory MIME type through its use of 'value=3Durl' attribute
parameters. For example, a given record has the attribute Photo that
contains the image of the contact. This image is not returned with the
record. Instead, the client receives a record that has the following
attribute:

Photo;value=3Durl: http://www.foo.com/bla.gif

This means that the actual value for the Photo attribute is located at the
address specified in the URI.

In RWhois 1.5, this concept was also extended to the specific type of
see-also that dealt with objects within the RWhois tree. This type of value
was used to normalize databases and to have records share values. In this
version the text/directory MIME type also handles this simply by using the
RWhois URL as the URL in a value=3Durl attribute parameter. For example:

Admin-contact;value=3Durl: rwhois://rwhois.internic.net/BN123.NET

6.0 Security Model

There are several areas within the protocol where security is needed. There
is the need for the privacy of the stream, authentication of the reading and
writing of objects, and the execution of certain directives. Security in
RWhois is an area that needs further development. The issues discussed below
are a guide for what needs to be done, not how to do it.

6.1 Stream Privacy

There is the need to secure the flow of data between the client and server
to thwart eavesdroppers looking for secure information. There are two
possible solutions: encrypt the protocol stream at the protocol level or at
the stream level. The former would require RWhois to provide some
handshaking. The latter would use existing solutions such as Transport Layer
Security (TLS). The primary issue to be aware of is the desire to not
require the server to buffer an entire answer to encrypt it. In the case of
an Xfer this would be an impossibly large task.

6.2 Authentication of Reading/Writing of Objects

There is a need to authenticate clients who need to create, update, or
delete objects. Currently, the Guardian model handles this to a certain
extent. That model does need to be extended due to its inability to deal
with attribute control lists so that certain values are visible depending on
the viewer.

7.0 Tree Management

Data replication and tree management for RWhois 2.0 currently follows the
same procedures and models as RWhois 1.5. See Section 3.6 of that RFC for
further information.

8.0 References

[RFC-954] Harrenstien, K., Stahl, M., Feinler, E., NICNAME/WHOIS,
RFC 954, SRI, October 1985.

[RFC-1521] Borenstein, N., Freed, N., MIME (Multipurpose Internet Mail
Extensions) Part One: Mechanisms for Specifying and Describing the Format of
Internet Message Bodies, RFC 1521, Bellcore, Innosoft, September 1993.

[RFC2167] Williamson, S., M. Kosters, D. Blacka, J. Singh, K. Zeilstra.
Referral Whois (RWhois) Protocol V1.5. RFC 2167, Network Solutions, June 1997.

[RFC1714] Williamson, S., M. Kosters. Referral Whois Protocol (RWhois).
RFC 1714, InterNIC, November 1994.

9.0 Authors' Addresses

The following employees of Network Solutions were involved in the
discussions used to formulate the ideas expressed in this document. While
specific credit is difficult to express, Scott Williamson and Mark Kosters
are recognized for their original work with the first version of RWhois.

David Blacka     davidb@rwhois.net
Mark Kosters     markk@rwhois.net
Ming Lu          cming@rwhois.net
Leslie Meador    lesliem@rwhois.net
Michael Mealling michaelm@rwhois.net
Greg Pierce      gregp@rwhois.net
Amar Rao         amarr@rwhois.net
Jasdip Singh     jasdips@rwhois.net
Scott Williamson scottw@rwhois.net
Koert Zeilstra   kzeil@rwhois.net


Appendix A: Error Codes

The definitions of the error codes are provided below. The error codes are
descriptive so that the client can group the error messages to determine
group action that must be taken before taking error specific action. Error
codes should remain consistent without variable extensions except for
messages associated with the registration process. If a client receives a
'6' in the second position of the error code and the client does not support
the extended code received, the client must act on the first position code.
(Example: If a client received 561 and the client did not support the
extended error codes for the server currently connected, the client would
exit based on the '5' in the first position of the error code.)

X00

   * 1 - Information only, no action required
   * 2 - Information, action required
   * 3 - Specific directive error, retry that directive or try another
     directive
   * 4 - Serious for current directive, may correct with another directive
   * 5 - Fatal, must disconnect

0X0

   * 0(1) - System wide, no specific directive
   * 2 - Registration error
   * 3(4,5) - Specific directive
   * 6 - Extended message (version specific)

00X

Sequential order

Appendix B: Capabilities ID

The server and client must send their capabilities to each other during the
initial handshaking after connection. The server indicates which optional
directives that it can accept. The client responds with the server responses
that it can understand. Below is the capabilities list.

Directives: (Sent by the server)

  Directive   ID
    load      1h
    limit     2h
   schema     4h
    xfer      8h
    quit     10h
   status    20h
    cache    40h
 holdconnect 80h
   forward   100h
     soa     200h
   notify    400h
  register   800h
   object   1000h
   define   2000h
   private  4000h
     X-     8000h
  directive 10000h
   display  20000h
  language  40000h

Appendix B: General ABNF definitions

These definitions are used to define several widely used tokens.

alpha =3D "a".."z" / "A".."Z"
digit =3D "0".."9"
hex-digit =3D digit / "a".."f" / "A".. "F"
id-char =3D alpha / digit / "_" / "-"
any-char =3D <ASCII 1..255, except LF (linefeed) and CR (carriage return)>
dns-char =3D alpha / digit / "-"
email-char =3D <see [RFC 822]>
space =3D " "
tab =3D <ASCII TAB (tab)>
lf =3D <ASCII LF (linefeed)>
cr =3D <ASCII CR (carriage return)>
crlf =3D cr lf

   Grammar

year =3D 4digit
month =3D 2digit
day =3D 2digit
hour =3D 2digit
minute =3D 2digit
second =3D 2digit
milli-second =3D 3digit
host-name =3D dns-char *(dns-char / ".")
ip-address =3D 1*3digit "." 1*3digit "." 1*3digit "." 1*3digit
authority-area =3D 1*id-char
rwhois-id =3D 1*id-char "." authority-area
email =3D 1*email-char "@" host-name
host-port =3D (host-name / ip-address) ":" 1*5digit
class-name =3D 1*id-char
attribute-name =3D 1*id-char
attribute-value =3D 1*any-char
time-stamp =3D year month day hour minute second millisecond
on-off =3D "on" / "off"

Note that the time-stamp must be in the Greenwich Mean Time (GMT) time zone.