12/06/96 8:35:55 AM

Network Working Group S. Williamson

INTERNET-DRAFT M. Kosters
Obsoletes: RFC1714 Network
Solutions, Inc.
Expires six months from December 1996
Intended category: Informational

Referral Whois (RWhois) Protocol V1.5

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 document describes Version 1.5 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; it allows for the 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 they may then be indexed into a mesh
structure.

RWhois differs from other directory service protocols in its ability to

reduce the query-narrowing in on a hierarchical server that may be able to
help. It also differs in its integrated awareness of authority areas.

Summary Of Changes Between RWhois Spec 1.0 and 1.5

1. Reorganized the document to make it easier to understand.

2. Changed to Augmented Backus-Naur Form (ABNF) for protocol definition.
3. Refined the use of "object" versus "class" throughout the document.
4. Added the _NEW_ tag in the -register directive.
5. Added capability ID to -RWhois directive and %RWhois response.
6. Removed the requirements for RFC954 Whois compatibility. This is now
OPTIONAL.
7. Added the hierarchical attribute to the schema definition object to
allow for differentiation between hierarchical and non-hierarchical
attributes.
8. Added the VERSION argument to the -schema request to allow schema
version checking.
9. Added the server augment on the -forward directive to indicate the
server to which to forward admin requests.
10. Modified the -private directive to use guardian.
11. Added Base class and Standard class definitions.
1. Introduction

1.1 General Information

Early in ARPANET development, the SRI-NIC established a centralized Whois

database that provided host and network information about the systems
connected to the network and the electronic mail (e-mail) addresses of the
users on those systems. The ARPANET experiment has evolved into a global
network with countless people and hundreds of thousands of end systems. The
sheer size and effort needed to maintain a centralized database necessitate
an alternate, decentralized approach for storing and displaying this
information.

The Internet portions of the DDN NIC have been transitioned to what is now
known as InterNIC Registration Services (RS). The charter for InterNIC RS
has been reduced to maintain information only for IP networks, top-level
domains, Autonomous System Numbers, and the points of contact for each of
these particular entities. In addition, the InterNIC, in its role as an
Internet Registry (IR), has delegated IP block assignment authority to
regional registries-such as the RIPE NCC for Europe and the APNIC for the
Asian Pacific region-while retaining authority for North America and all
non-delegated regions. This has led to a fragmentation of Whois service to
the Internet user.

Various regional IRs proposed and developed several different solutions for
this fragmentation. Two solutions have been worked on extensively: the
Shared Whois Project (SWIP) and X.500. The SWIP project has a common
exchange format that can be parsed by the IRs for input and output. Thus, a
database can be synchronized with information obtained from the other IRs.
This project is showing promise and is now operational. However, this
approach still requires a centralized database for the storage and display
of information.

The InterNIC has also been involved in the use of X.500 for the display of
registration information. Among other things, this included defining schemas
and Directory Information Tree structures for the purpose of distributing
information among the various X.500 Directory Service Agents (DSAs).
Unfortunately, X.500's complexity, resource utilization, and lack of
Internet support has made necessary a search for an alternative solution.

The information that the various IRs maintain is inherently hierarchical in

nature. For example, hammer.nic.ddn.mil is under the nic.ddn.mil domain,
which is under the ddn.mil domain, which is under the .mil domain.
198.41.0.21 is part of network 198.41.0.0/24, which is part of the block
198.41.0.0/16, which is part of the block 198.0.0.0/8. The InterNIC may not
contain the information but will at least be able to reduce the query and
point to, or refer, users closer to the requested information. This is the
basis of the development of Referral Whois (RWhois), and the corresponding
RWhois protocol.

To date, the underlying premise while building this protocol has been to
retain the basic functionality of the Whois server and client, making all of
the extensions optional. The server MAY respond to the original Whois client
that is currently included with many operating systems. The RWhois client
may also interact with RFC954 [RFC-954] whois servers. This is now an
implementation choice. This decision to remove the requirements for RFC954
compatibility will allow RWhois to move forward to the next generation
information/registration system. We believe that the best way to remain
compatible with RFC954 service is to build a Whois-to-RWhois gateway.

RWhois has been designed as an extendible protocol to ensure that many uses
can be accommodated. Public extensions to the protocol should be documented
as RFCs. Private extensions can be used with agreement left up to the client
and server. If extensions are not implemented at the server in question, an
appropriate error message must be sent. The use of extended error message is
outlined in Appendix A: Error Codes.

Throughout this document ABNF notations are used to describe the RWhois
server/client interaction. The following are predefined.

ALPHA = "a".."z" / "A".."Z"

CHAR = 0..127

DNSCHAR = ALPHA / DIGIT / "-"

DIGIT = "0".."9"

HDIGIT= DIGIT / "a".."f"

SPACE = 32

TIMESTAMP = YEAR MONTH DAY HOUR MINUTE SECOND

YEAR = 4*4DIGIT

MONTH = "0".."1" DIGIT

DAY = "0".."7"

HOUR = "0".."2" DIGIT

MINUTE = "0".."5" DIGIT

SECOND = "0".."5" DIGIT

EMAIL = 1*CHAR ["@" 1*CHAR*["." 1*CHAR]

OBJECTID = 1*CHAR*["." 1*CHAR]

SERVER = 1*CHAR *["." 1*CHAR] ":" 1..65535

The words "MAY", "SHOULD", and "MUST" are significant in this document. If
"MAY" is used, the implementer has the option to follow the advice of this
document. If the word "SHOULD" is used, the implementer is strongly
encouraged to follow the advice but may choose not to. If "MUST" is used, it
is a required part of the protocol. Implementations without this
functionality will not be considered RWhois protocol compliant.

1.2 Common Terms

Attribute - A variable within a class. For example, Organization-Name

contains the value for the name of an organization.

Authority Area - A predefined collection of objects based on a hierarchical

point; for example, information for Network Solutions is contained in the
netsol.com authority area. An authority area is an identifier for an RWhois
database containing data and its schema. It has a hierarchical structure
that helps identify the position of the database in the global RWhois data
information tree. It is recommended that an authority area be either a
domain name or an IP address in prefix/prefix length notation. Otherwise, an
authority area SHOULD have a domain-name-like structure of "label-dot" form.
The different examples of an authority area are rwhois.net, 198.41.0/24, and
a.b.

Class - A type of object.

Class Definition (or Schema) - Identifies all of the attributes allowed

within an object of that class.

Directive Response -

Guardian Object - This object, when linked to another object, specifies the
method of protection for that object.

Object - An instance of a class that contains data.

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. An RWhois server may be primary for
multiple authority areas.

Query Result -

Referral Object -

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.

Start Of Authority (SOA) - This object contains the administrative variable

of an authority area.

2. Connection Model

The Connection Model defines

2.1 Standard Query (TCP)

The normal connection style will be via 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.

3. Data Model
The RWhois protocol has a Base class definition. The Base class defines a
set of attributes that MUST be present in every class definition.

3.1 Base Class

The Base class below defines those attributes that must be present in every
class definition for RWhois.

Schema-Name = 1*CHAR

The name of the class to which a particular object belongs. This is

essentially the type of the object. This attribute is REQUIRED.

ID = OBJECTID

This is a globally unique identifier for an object in the RWhois hierarchy.

It has the following format:

<locally unique identifier>.<authority area name>

where <locally unique identifier> can be any string without the period
character that is unique to the local RWhois installation�s database, and
where <authority area name> is the actual name of the authority area
(netsol.com, for example).

A typical way to create the unique identifier is to use a TIMESTAMP format

for the locally unique identifier. This attribute is REQUIRED when updating
an object. However, when adding that object to the RWhois database, it is
not specified by the client.

Auth-Area = 1*CHAR

This is the authority area to which the object belongs. While this
information is encoded in the ID string as well, it is needed for the
-register directive process (see Section 5.2.13 below). This attribute is
required

Updated = TIMESTAMP

This is a time/date stamp used to indicate the last time of modification of

the record. It has the TIMESTAMP format. This attribute is REQUIRED, and
MUST be filled out by the server process.

Guardian = OBJECTID

This contains the ID of a guardian object (see below). The guardian object
pointed to by this attribute describes what security protocol must be
followed in order to modify or delete this object. This attribute is
OPTIONAL. If no Guardian attributes are present in an object, then the
object is considered unguarded and anyone may modify the object.

3.2 Guardian Class

The Guardian class describes a general methodology for implementing privacy

and authentication within RWhois. See Section 6 for more information on the
RWhois security model. In addition to the Base class attributes, the
Guardian class contains the following attributes.

Auth-Scheme = 1*CHAR
This attribute describes the particular authentication/encryption scheme
this guardian uses. There is no restriction on this field, but both the
client and server must understand the semantics of any particular scheme.
This attribute is REQUIRED.

Guard-Info = 1*CHAR

This field contains generic information that is needed by the particular

Guard-Scheme in use. The contents of this attribute depend on the
Guard-Scheme. The attribute is considered optional, but any given
Guard-Scheme may require this field.

3.3 Referral Class

The Referral class describes objects that are used to delegate authority to
a sub-authority area. For example, the netsol.com authority area may have a
referral object delegating authority for the west.netsol.com authority area.
In addition to the Base class, the Referral class contains the following
attributes.

Referral =

This attribute contains the actual delegation information to an RWhois

server. It is usually encoded as a Uniform Resource Locator (URL). See the
�%referral� response below.

Referred-Auth-Area =

This attribute specifies the referred authority area in domain name or

quad-octet prefix/prefix length format.

4. Search Model

The search model is made up of four distinct aspects. The query itself is
specified by the client. The server 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.

4.1 The Query

The query is generally the final message sent to the server. It is not a
directive and therefore does not start with a '-'. 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. The class type to search is the only
qualifier that MAY precede the query. If the first token does not match the
name of an existing class on the server, then that token is considered part
of the query string. Below is the description for query interaction.

ABNF for query:

RWHOIS-QUERY = [CLASS SPACE] QUERY

CLASS = 1*DNSCHAR ;This OPTIONAL pre-query qualifier allows the requester to

limit the class in which the server searches for a specific object.

QUERY = (QSTRING [MATCHMANY] / ATTQUERY) *([AND] / [OR])

AND = "and" QUERY

OR = "or" QUERY

ATTQUERY = ATTNAME "=" QSTRING [MATCHMANY]

ATTNAME = 1*DNSCHAR

QSTRING = RSTCHAR 1*CHAR / QUOTE QUOTESTRING QUOTE

;QSTRING must be quoted if it contains spaces.

RSTCHAR = 0..30 / 32..36 / 38..44 / 46..127

QUOTESTRING = 0..30 / 32..127

MATCHMANY = "*"

Example of use:

netsol.com

domain netsol.com

contact last-name=kosters and first-name=mark

domain-name=netsol.com or organization-name="Network Solutions"

domain organization-name="Network Solutions" and country-code=us

The following error responses may occur following a query.

%error 130 Not authority for answer... TTL good

%error 230 No Records Found

%error 231 Not authority for answer... TTL expired

%error 340 Query too complex

4.2 Query Reduction

The critical component of the RWhois server is its ability to reduce the
query to find a server that is "closer" to the data or to realize that the
data is within an authority area being served by the server. Initially, the
server searches for local matches. If the server cannot find a local match
and the query is non-hierarchical, the server passes the query to a Common
Indexing Protocol (CIP)-type mesh. If the server cannot find a local match
and the query is hierarchical, the server searches within the authority
area. If there is a match in that authority area, the server sends a link
referral. If the server cannot find a match, it sends a punt referral. The
search algorithm of the server is the following.

1. Are there any local matches? If yes, send results.

2. Are there any referrals? If yes, send referral.
 3. Does the query match an authority area within the server? If yes, send
%error 230 No Records Found.
4. If no local data, referral links, or authority area, match then reduce
the query and go to Step 2.

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

1. connect to root.rwhois.net
2. query for ietf.cnri.reston.va.us
3. search for ietf.cnri.reston.va.us (No hit)
4. check for auth area ieft.cnri.reston.va.us (No hit)
5. search referrals for cnri.reston.va.us (No hit)
6. check for auth area cnri.reston.va.us (No hit)
7. search referrals for reston.va.us (No hit)
8. check for auth area reston.va.us (No hit)
9. search referrals for va.us (No hit)
10. check for auth area va.us (No hit)
11. search referrals for us (referral found) - referred to nii.isi.edu port
43.
12. query for ietf.cnri.reston.va.us
13. search for ietf.cnri.reston.va.us (No hit)
14. check for auth area ieft.cnri.reston.va.us (No hit)
15. search referrals for cnri.reston.va.us (No hit)
16. check for auth area cnri.reston.va.us (No hit)
17. search referrals for reston.va.us (No hit)
18. check for auth area reston.va.us (No hit)
19. search referrals for va.us (No hit)
20. check for auth area va.us (No hit)
21. search referrals for us (No hit)
22. check for auth area us - determine to be authority for us - send %error
230 No records found.

4.3 referral

Server Response:

The "%referral" response instructs the client to contact and query another
server. The server SHOULD be an RWhois server. However, if the client is
capable of using other directory access protocols, then there is nothing to
prevent a referral to another server type. For example, an RWhois server
could refer a client to a Whois++ server. Following the first referral
received during a session, the client MUST replace the default server list.
If there is more than one referral the additional servers are considered
secondary. Therefore, if the first server can be contacted, the rest should
be dropped.

Client Behavior:

In the non-URL response format below, the authority area equals the reduced
query. There are three types of referral; the type can be determined by the
client evaluating the authority area, which is part of the "%referral"
response. 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.

Types of Referrals:

If the authority area received from a referral response is equal to the

original query, then it is a link-type referral. Link referrals move down
the tree. If the authority area is not equal to the query, then it is a
reduction-type referral. If no authority area is sent, then it is a
punt-type referral. Punt means the server is not a root and cannot answer
the query, and therefore is referring the client to a level up the tree or
to a server that can better answer the query. (NOTE: the punt-type referral
may be used to direct a client to a CIP server.)

ABNF for use:

Old Style:

"%referral" SPACE server ":" type SPACE autharea /

New Style:

"%referral" SPACE "url:" url

server = SERVER ;This argument identifies the server with which the client
should reconnect.

type = "rwhois" / "whois++" / "whois" / "ldap"

;This argument identifies the server type. This could save wait time for the
client trying to identify a non-RWhois server.

autharea = 1*CHAR ;This argument identifies the authority area that caused
the referral for the query in question. Using this value as the argument for
the "-soa" directive to the referral server should result in a positive
response. If this is not the case, the referral is considered bad.

url = ;This argument defines the URL string that points to the resource
containing the desired information.

Example of use:

%referral nic.ddn.mil:43:rwhois .mil

%referral url:http://www.netsol.com/

4.4 see-also

Capid: {1h}

The "%see-also" response instructs the client to contact another server for
additional information about the current query. If multiple see-alsos are
received from a single query, each subsequent see-also SHOULD be visited in
the order received. One example of use for the see-also response is to
display autonomous system information relating to an IP network number or
router interface information relating to an IP host number.

ABNF for use:

"%see-also" SPACE server [ ":" type ] ":" query /

"%see-also" SPACE "url:" url

server = SERVER ;This argument identifies the server with which the client
should reconnect.
type = "rwhois" / "whois++" / "whois" / "ldap"

;This argument identifies the server type. This could save wait time for the
client trying to identify a non-RWhois server.

query = QUERY ;This argument sets the query that must be sent to the
referred server. The query may be different from the original query sent to
the referring server.

url = URL ;This argument defines the URL string that points to the resource
containing the desired information.

Example of use:

%see-also prmd.merit.edu:43:handle=xxx

%see-also url:http://www.netsol.com/

5. Client/Server Interaction Model

The RWhois client sends directives to the RWhois server. These directives
MUST be prefixed with the '-' character in the first column. The query is
not prefaced with the '-' character; this allows the client to first
ascertain that the server is an RWhois server before sending directives. All
directives MUST be terminated by a new line (NL) character.

Responses are sets of data that servers send in response to a client

directive. Responses from an RWhois server MUST be prefaced with the "%"
character at the start of a line. Responses are divided into two groups:
those that MUST be implemented in order to provide minimal RWhois
interaction and those that SHOULD be implemented to achieve the desired
characteristics of a fully functional distributed system. When a directive
is not available on the server, a server MUST respond with an error message
indicating that a directive is not available on the server, and therefore
the server does not have the required responses.

5.1 Required Directives/Responses

This section details those directives and responses that are necessary for
an RWhois server. They are REQUIRED. The error responses listed in this
section are those general responses that can occur as a result of any
directive.

5.1.1 General

The error responses below are general responses that can occur as a result
of any directive. They SHOULD be implemented. These messages will not be
repeated under each directive. The error codes are explained in Appendix A.

%error 100 Get Peer Name query failed

%error 338 Invalid directive parameter

%error 400 Invalid Server Directive

%error 401 Not authorized for directive

%error 402 Unidentified error... continue

%error 438 Directive not implemented

%error 439 Directive not enabled

%error 500 Memory Allocation Problem

%error 502 Unrecoverable error... goodbye

%error 503 Idle time exceeded... goodbye

The following error responses will only occur following successful

connection to the server's host and start-up of the session.

%error 501 Service not available

%error 503 Idle time exceeded... goodbye

An RWhois server MUST implement the following directives/responses.

5.1.2 ok

The "%ok" response MUST be sent by the RWhois server at the completion of
every task or to positively acknowledge a directive.

ABNF for use:

"%ok"

5.1.3 error

The "%error" response is used to indicate an error condition to the client.

Refer to Appendix A for details on the error reporting scheme. The
implementer MUST include the error number, because it will be used to
determine the client's action. The text message MAY be included and will
only be used to make the error readable by humans connected using telnet or
an old Whois client. The format for these messages is in Appendix A.

ABNF for use:

"%error" SPACE errornum SPACE [textmsg] [SPACE ":" data]

errornum = 3*3DIGIT ;This argument is the error number identified in

Appendix A. The client can use this number to categorize errors.

Textmsg = *ALPHA ;This argument is the text that describes the error
message; it makes the error readable to humans. This message must be
consistent for each error. Messages sent following an error code associated
with the registration process will contain the line number of the attribute
that is incorrect. This is the only case where the message should be
variable.

Data = 1*CHAR ;This argument would contain additional information specific

to

the reported error.

Example of use:
%error 400 Invalid Server Directive

%error 338 Invalid directive parameter

%error 438 Directive not implemented

%error 439 Directive not enabled

5.1.4 RWhois

Directive:

The "-RWhois" directive identifies the client as an RWhois client and allows
the server to operate using the RWhois protocol exclusively. This directive
MUST be sent in response to the %RWhois response from the server if the
client is to be treated as an RWhois client.

ABNF for use:

"-RWhois" SPACE ("V-" specver ":" capid) [SPACE impid]

specver = 1*2DIGIT "." 1*2DIGIT

;This argument identifies the specification version to which the client is

built to conform. Clients that are built in accordance with this document
are V-1.5. This argument will be used by the server to determine if features
introduced in subsequent releases of the protocol document may be used.

capid = responseid ":" displayid ":" ????id

;This argument identifies the client's capabilities. Each optional server

response has a bit that is set if the client can understand the response.
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 Appendix C of this document.

responseid = 6*6HDIGIT

displayid = 2*2HDIGIT

????id = 2*2HDIGIT

impid = *ALPHA ;This argument identifies client implementation information.

The implementers SHOULD maintain a version number separate from the
specification version. The implementers SHOULD also identify the client so
problems can be traced back to the implementation to allow for faster
resolution.

Example of use:

-RWhois V-1.5:001fff:0f:0f [Network Solutions V1.5]

Response:

The "%RWhois" response MUST be sent upon connection in order to identify the
server as an RWhois server. RWhois clients need this response to know it is
an RWhois server and to enable or disable certain optional capabilities.

ABNF for use:

"%RWhois" SPACE ("V-" specver ":" capid) SPACE servername[SPACE impid]

specver = 1*2DIGIT "." 1*2DIGIT

;This response indicates the version number of the RWhois protocol

specification that the software is capable of handling. The version
described in this document is V-1.5.

capid = responseid ":" displayid ":" ????id

;This argument identifies the server's capabilities. Each optional directive

has a bit set if the directive is enabled on the server. 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 Appendix C of
this document.

responseid = 6*6HDIGIT

displayid = 2*2HDIGIT

????id = 2*2HDIGIT

servername = 1*DNSCHAR

;This argument is the host name of the computer hosting the RWhois server.

impid = 1*DNSCHAR ;This argument identifies client implementation

information. The implementers SHOULD maintain a version number separate from
the specification version. The implementers SHOULD also identify the client
so problems can be traced back to the implementation to allow for faster
resolution.

Example of use:

%RWhois V-1.5:04ffff:0f:0f rs.internic.net (Network Solutions V-1.5)

Errors:

%error 300 Not compatible with that version number

%error 338 Invalid directive parameter

%error 438 Directive not implemented

%error 439 Directive not enabled

5.2 Optional Directives/Responses

The following are the optional directives/responses. They SHOULD be

implemented to ensure maximum capability throughout the RWhois tree;
however, a server will still be considered an RWhois server without them.
Directives/Responses that are not implemented should be indicated in the
capid in the %RWhois response.

5.2.1 info

Server Capid: {200h}

The "%info" response is used to give a message to the user of the client.
This response is not initiated by a directive. The information between the
"%info on" and the "%info off" should be presented to the user of the
client. An ideal use of this response is to present a Message of the Day
(MOTD) to the user.

ABNF for use:

"%info" SPACE mode

mode = "on" / "off" ;On: This turns on the passthru mode.

Off: This turns off the passthru mode.

Example of use:

%info on

As of 3/24/1994 at 9:00 EST this server will no longer be in service. If you

have this server in your configuration file we recommend that you change it
to rs.internic.net:4343. You will automatically be redirected there
following this message.

%info off

5.2.2 load

Client Capid: {1h}

Server Capid: {2h}

Directive:

The "-load" directive allows the client to make a quick decision about
presenting the query to the current server. If the client determines that
another server can better serve the query, then control may be transferred
to the server with the lower load and better connection. This directive has
no arguments.

Response:

The "%load" response returns the current and average load of the computer
hosting the RWhois server. The measurement may be different depending on the
implication of the system's load mechanism. This directive/response was
implemented to allow experiments with sorting preferred servers to deliver
better results to the user.

ABNF for use:

"%load" SPACE current SPACE average

current = 1*2DIGIT "." 1*2DIGIT

;This argument delivers the current load on the system hosting the RWhois
server.

average = 1*2DIGIT "." 1*2DIGIT

;This argument delivers the average load on the system hosting the RWhois
server.

Example of use:

%load 5.68 1.32

Error:

%error 335 System's load not available

%error 338 Invalid directive parameter

%error 438 Directive not implemented

%error 439 Directive not enabled

5.2.3 limit

Client Capid: {2h}

The "-limit" directive will allow the client to request that the server
allocate enough space to collect more responses than would currently be
collected by the server.

ABNF for use:

"-limit" SPACE value

Value = 1*DIGIT ;This argument is the hit limit requested by the client. If
the hit limit exceeds the limit set by the server administrator, the client
MUST receive an error message.

Example of use:

-limit 2000

Errors:

%error 330 Exceeded Max Records Limit

%error 331 Invalid Max Records Size

%error 338 Invalid directive parameter

%error 438 Directive not implemented

%error 439 Directive not enabled

5.2.4 schema

Client Capid: {4h}

Server Capid: {20h}

Knowing the class definition (schema) before making a query can increase the
flexibility in building client displays. This knowledge is required if the
client wishes to add an object. A server SHOULD have separate class
definition files for each authority area.
Directive:

The client can request the class definition for all or some classes in an
authority area by using the "-schema" directive. The optional argument
"version" is used to request the version of the schema. A schema version
MUST be the time stamp. The method for doing version SHOULD be agreed upon
with in an RWhois tree.

ABNF for use:

"-schema" SPACE AUTHAREA *[ SPACE classname ] [ SPACE "version"]

AUTHAREA ;

classname = 1*ALPHA ;This optional argument identifies the name of the class
for which the schema is being requested. If this argument is not sent, the
schema for all classes contained in the server for that authority area will
be sent.

"version" ;

Example of use:

-schema internic.net

-schema internic.net domain

-schema internic.net domain version

-schema netsol.com domain contact

Response:

The "%schema" response is used to describe the attributes of a class. This

is in response to the "-schema" directive. If the request was for the
version, the server MUST return only the "version:" tag for the class(es)
requested. If the class was not sent, the version of each of the classes
within the requested authority area MUST be sent. Each attribute MUST be
separated by "%schema" with no arguments.

ABNF for use:

"%schema" [SPACE classname ":" (("version:" vernum) |

("attribute:" attrname) | ("format:" fmtstring)| ("description:"

description) | ( "indexed:" indexed ) | ("required:" required ) |

( "multi-line:" multi-line ) | ("type:" type ) |

( "primary:" primary ) | ( "hierarchical:" hierarchical )]

These arguments are not required if the current response is an attribute

separator.

vernum = TIMESTAMP ;This argument can stand alone if it is in response to a

version number request, for example, -schema user version.

attrname = ;This argument identifies the name of the attribute being

described.
fmtstring = ;This argument describes the allowed format for the attribute.

description = ;This argument describes the attribute's use.

indexed = "on" |"off"

;This argument identifies attributes that are indexed.

required = "on" | "off"

;This argument identifies attributes that are required.

multi-line = "on" | "off"

;This argument indicates whether the attribute can span multiple lines.

type = "text" | "MIME" | "see-also" | "referral"

;This argument identifies the type of the attribute.

primary = "on" |" off"

;This argument indicates whether the attribute is a key alone or in

combination with other keys.

hierarchical = "on" | "off"

;This argument indicates whether the attribute is hierarchical. This value

is used to determine whether or not to send the attributes value out into
the mesh indexing system.

Example of use:

In response to:

-schema internic.net user version

%schema user:version:19960522103000

In response to:

-schema internic.net version

%schema user:version:19960522103000

%schema

%schema domain:version:19960815231500

%schema

%schema contanct:version:19960816093001

%schema

%schema asn:version:19961011062200

%schema
%schema network:version:19961030115300

In response to:

-schema internic.net user

%schema user:attribute:Handle

%schema user:description:Locally Unique Identification

%schema user:indexed:OFF

%schema user:required:OFF

%schema user:mult-line:OFF

%schema user:type:TEXT

%schema user:primary:ON

%schema

%schema user:attribute:Object-Type

%schema user:description:Name of the object

%schema user:indexed:ON

%schema user:required:OFF

%schema user:mult-line:OFF

%schema user:type:TEXT

%schema user:primary:OFF

%schema

%schema user:attribute:Organization-Name

%schema user:description:Name of the organization the user belongs to

%schema user:indexed:ON

%schema user:required:OFF

%schema user:mult-line:OFF

%schema user:type:TEXT

%schema user:primary:OFF

%schema

%schema user:attribute:Organization-Postal

%schema user:description:Work postal address

%schema user:indexed:ON

%schema user:required:OFF

%schema user:mult-line:ON

%schema user:type:TEXT

%schema user:primary:OFF

Errors:

%error 333 Not SOA for requested authority area

%error 338 Invalid directive parameter

%error 438 Directive not implemented

%error 439 Directive not enabled

5.2.5 xfer

Client Capid: {8h}

Server Capid: {10h}

Directive:

The "-xfer" directive is used to request data from a server. This method of
transfer has no limit on the number of records that can be transferred to
the client application. This directive is used primarily by a secondary
server to transfer data contained in an authority area. This directive
SHOULD be restricted to a pre-selected set of hosts.

ABNF for use:

"-xfer" SPACE AUTHAREA *[[SPACE "class=" classname] *[SPACE "attr="

ATTRNAME]][SERIAL]

AUTHAREA = ;This REQUIRED argument identifies the authority area of the

transfer.

CLASSNAME = 1*ALPHA ;This OPTIONAL argument identifies the class to

transfer.

ATTRNAME = 1*ALPHA ;This OPTIONAL argument identifies the attributes of the

specified class to transfer.

SERIAL = *TIMESTAMP ;This OPTIONAL argument notifies the server to send

everything that has been updated since this date.

Example of use:

-xfer netsol.com class=domain

-xfer .com class=domain 19961029141259

-xfer internic.net class=domain attr=organization-name class=contact

attr=last-name attr=first-name
Response:

The "%xfer" response will send requested objects in response to the "-xfer"
directive. The transfer MUST be limited to the authority area identified. If
there are no further arguments, the server MUST send all of the objects in
the database for that authority area. Non-authoritative data MUST not be
transferred using this method. Each object instance is sent with a blank
%xfer response between instances.

ABNF for use:

"%xfer" [SPACE CLASS ":" ATTRIBUTE ":" value]

These arguments are not required if the current response is an object

instance separator.

CLASS = ;This argument represents the name of the class being transferred.

ATTRIBUTE = ;This argument identifies the name of the attribute being

transferred.

value = ;This argument contains the value of the attribute. If blank, the
attribute value is blank.

Example of use:

In response to:

-xfer internic.net class=user attr=last-name attr=first-name

attr=organization-phone

%xfer user:last-name:Kosters

%xfer user:first-name:Mark

%xfer user:organization-phone:703-555-1212

%xfer

%xfer user:last-name:Williamson

%xfer user:first-name:Scott

%xfer user:organization-phone:703-555-1212

%xfer

Errors:

%error 332 Nothing to transfer

%error 333 No SOA for requested authority area

%error 338 Invalid directive parameter

%error 438 Directive not implemented

%error 439 Directive not enabled

5.2.6 quit

Capid: {10h}

The "-quit" directive will inform the server that the client is finished.
The server and client SHOULD close the connection. This directive has no
arguments.

5.2.7 status

Client Capid: {20h}

Server Capid: {8h}

Directive:

The "-status" directive is used to poll the server for its status. The
server MUST send the seven required attributes; however, additional
attributes may be sent in the response. The client SHOULD ignore all unknown
attributes. This directive has no arguments.

Response:

The "%status" response returns the status of several important flags or

values. The response MUST contain the elements below. The implementer MAY
chose to add additional attributes that are deemed necessary.

Limit: Current limit set on the server. This value may be changed using the
"-limit" directive. This is not the maximum limit of the server. The maximum
limit is not disclosed to prevent clients from automatically setting the
highest limit possible, thereby causing degradation in performance of the
server.

Load: This is the current load of the host system.

Cache: This is the current status of the cache flag. (On or Off)

Holdconnect: This is the current status of the holdconnect flag. (On or Off)

Forward: This is the current status of the forward flag. (On or Off)

Authority records: This is the number of authority records in server's

database.

Cached records: This is the number of records in the server's cache

database.

Display: This indicates the types of display modes the server is using.

Contact: This indicates the administrative contact for the server.

ABNF for use:

"%status" SPACE ( ("limit:" currlimit) /

("load:" currload) / ("cache:" cache) /

("holdconnect:" holdconnect) / ("forward:" forward )/

("Authority:" authnum) / "Cached:" cachnum ) /

("Display:" mode ":" type) / ("Contact:" contact)

currlimit = 1*DIGIT

currload = 1*2DIGIT 1*2DIGIT

cache = "on" / "off"

holdconnect = "on" / "off"

forward = "on" / "off"

authnum = 1*DIGIT

cachnum = 1*DIGIT

mode = "single" / "multi"

type = *CHAR

contact = EMAIL

Example of use:

%status limit:1500

%status load:1.23

%status cache:off

%status holdconnect:on

%status forward:off

%status authority:25

%status cached:200

%status display:multi:summary

%status contact:scottw@rwhois.net

5.2.8 cache

Client Capid: {40h}

The RWhois server can hold data that does not fall into one of its authority
areas. If the server sends this data to a requester, it is considered a
non-authoritative response. The holding of this data is called caching. The
original or secondary data for these objects is not contained on the server.
The "-cache" directive instructs the server to send cached data if it has an
answer to the query in cache. The RWhois client and server SHOULD start with
the cache turned off. Details on determining the expiration of cache data
can be found in Section 5.2.11, "%soa" response.

ABNF for use:

"-cache" SPACE mode

mode = "on" / "off" ;On: This turns on caching.

Off: This turns off caching.

Example of use:

-cache on

Error:

%error 232 Cache disabled

%error 338 Invalid directive parameter

%error 438 Directive not implemented

%error 439 Directive not enabled

5.2.9 holdconnect

Client Capid: {80h}

The RWhois server MUST close the connection after the response to a query
has been sent; the query is the final exchange between the client and
server. However, this characteristic can be modified with the"-holdconnect"
directive. If this directive is issued to the RWhois server, it MUST remain
connected until the "-quit" directive is received. Once the "-quit"
directive is received, both the server and the client SHOULD close their
connection.

ABNF for use:

"-holdconnect" SPACE mode

mode = "on" / "off" ;On: This turns on holdconnect.

Off: This turns off holdconnect.

Example of use:

-holdconnect on

5.2.10 forward

Client Capid: {100h}

During normal server operation the server MAY send a "%referral" or

"%see-also" responses to the client, expecting the client to redirect the
query to the server identified in the response. If the client is located
behind a firewall or is poorly connected, having the server itself make the
query may improve query performance or allow a query to be satisfied. The
"-forward" directive will instruct the server to operate as a forwarding
server. This directive SHOULD be configurable to allow its use to be
controlled by the administrator.

ABNF for use:

"-forward" SPACE mode [SPACE server]

mode = "on" / "off" ;On: This turns on forwarding.

Off: This turns off forwarding.

Server = SERVER ;This is the destination server for directive passthru.

Example of use:

-forward on

-forward on slam.internic.net:4321

Error:

%error 338 Invalid directive parameter

%error 431 Not authorized to forward

%error 433 Bad reference on forward

%error 438 Directive not implemented

%error 439 Directive not enabled

5.2.11 soa

Client Capid: {200h}

Server Capid: {4h}

Directive:

The identification of an authority area is an important part of the RWhois

design. The "-soa" directive is used to question the server's authority for
a specific authority area or to determine various administrative parameters
of the authority area. A positive response indicates that the server is
authoritative for the authority area. It will include the administrative
parameters for the authority area as shown below. If the server does not
contain an SOA for the authority area requested, it MUST send an error
message to the client. If the directive is sent with no arguments, then data
for all authority areas on the server MUST be sent.

ABNF for use:

"-soa" *[SPACE autharea]

autharea = 1*CHAR ;This argument identifies the authority area being

requested. If this argument is not sent, information about all authority
areas contained in the server must be sent.

Example of use:

-soa netsol.com

Response:
The "%soa" response delivers information about the authority area in
question. If the server does not contain the authority for the area in
question, it MUST respond with the appropriate error message. The SOA data
MUST never be cached, and SOA records must originate on the server giving
the answer. The increment and refresh attributes are used to provide for
incremental updates of the secondary server. Deleted data SHOULD remain in
the secondary server's cache until the refresh time has been reached. This
will reduce the amount of data transferred and will not require that the
primary server retain deleted data. The following attributes required MUST
be sent in response to an authority area soa request.

authority

ttl

serial

refresh

increment

retry

tech-contact

admin-contact

hostmaster

primary

ABNF for use:

"%soa" SPACE (("authority:" autharea) / ("ttl:" ttl) /

("serial:" serial)/ ("refresh:" refresh) /

("increment:" incremental) / ("retry:" retry ) /

("tech-contact:" tech-contact) /

("admin-contact:" admin-contact) /

("hostmaster:" hostmaster) / ("primary:" primary )

autharea = 1*CHAR ;This is the authority name of the SOA, for example,
internic.net or 198.41.0.0/24. This is REQUIRED.

ttl = 1*DIGIT ;This is the time to live for data within this authority area
that another server may cache. The server caching the data SHOULD consider
the data expired after storage for the number of seconds identified by this
attribute.

serial = TIMESTAMP ;This is the serial number of the data contained in the
authority area. The serial number MUST be incremented every time data in the
authority area has changed. This is REQUIRED.

refresh = 1*DIGIT ;This is the time to completely remove cached data and
transfer all data from the primary server.
increment = 1*DIGIT ;This is the time to wait before checking for
incremental updates from a primary server.

retry = 1*DIGIT ;This is the time to wait before retrying connection to a

server that appears to be out-of-service.

tech-contact = EMAIL

;This is the e-mail address of the person or role account responsible for
the operation of the authority area.

admin-contact = EMAIL

;This gives the e-mail address of the person or role account responsible for
the data contained on the authority area.

hostmaster = EMAIL ;This is the e-mail address to which additions or changes

to the server's data should be sent. An e-mail based data edit tool can
automatically send changes to update the data on the server via e-mail.

primary = SERVER ;This is the primary server for authority area.

Example of use:

%soa authority:netsol.com

%soa ttl:7200

%soa serial:19940606203030

%soa refresh:7200

%soa increment:60

%soa retry:1200

%soa tech-contact:markk@netsol.com

%soa admin-contact:jasdips@netsol.com

%soa hostmaster:hostmaster@netsol.com

%soa primary:netman1.netsol.com:4343

Error:

%error 333 Not SOA for requested authority area

%error 338 Invalid directive parameter

%error 438 Directive not implemented

%error 439 Directive not enabled

5.2.12 notify

Client Capid: {400h)

Server

The "-notify" directive is used to notify a server of a bad or recursive

referral or of a change in a primary server's data.

ABNF for use:

"-notify" SPACE action SPACE information

action = "badref" / "recurref" / "update" / "inssec" / "delsec"

;badref When a client receives a "%referral" response that does not work, it
must report the bad referral to the server that issued the referral. The
referral is bad only if the referred server does not contain the authority
area in question. It is not considered a bad referral if the server does not
have an answer to the query but responds positively to the "-soa autharea"
directive. This merely means that there is not an answer to the query. When
a "-badref" is sent to the referring server, it should log the bad referral
so the administrator of that server can remove the reference if it is no
longer correct. This action should only be taken after receiving a negative
response to the query and the SOA request.

;recurref When a client receives a referral that results in a recursive

action, the referring server must be informed. The "-recurref" directive
must be sent identifying the recursive loop. This directive should only be
sent to the server one level back, even if multiple servers were involved in
the referral.

;update An RWhois primary server must be aware of its secondary servers. If

the data in the primary server changes, the primary server MAY choose to
notify the secondary servers. This allows the secondary servers to quickly
reflect changes in the primary server's data.

;inssec This action will inform the authority server that the server
indicated in the argument will be a secondary for its authority area. The
server receiving this directive MUST determine if the secondary is
acceptable. If it is, the server should be added to the update list so that
it will be informed if data in the authority area changes.

;delsec This action will inform the server that the server indicated in the
subsequent arguments will no longer be a secondary. The server receiving
this action MUST determine if the server is a secondary and, if so, remove
it from the update list.

Information = (if action = "badref" / "recurref" then server ":" query)

/ ( if action = "inssec" / "delsec" / "update" then server ":" autharea )

server = SERVER ;This argument identifies the server that contained the
recursive or bad referral or has data that changed.

query = 1*CHAR ;This argument identifies the query that was sent to the
server that gave a recursive or bad referral.

autharea = 1*CHAR ;This argument identifies the authority area where the
object that changed currently resides.

Example of use:
-notify recurref netman1.netsol.com:4343:scottw@netsol.com

-notify badref nic.ddn.mil:43:abc.af.mil

-notify update netman1.netsol.com:4343:netsol.com

-notify inssec dmeister.internic.net:4343:netsol.com

-notify delsec dmeister.internic.net:4343:netsol.com

Errors:

%error 338 Invalid directive parameter

%error 434 Referral does not exist on this server

%error 438 Directive not implemented

%error 439 Directive not enabled

%error 530 Not authorized as secondary

5.2.13 register

Client Capid: {800h}

Server Capid: ???

This directive is used to add, modify, or delete objects that exist or

should exist in the server's database. The client MUST wait to send the
registration data until the "%ok" response is received from the server.
During a modification or delete operation, the "_NEW_" tag is used to
delineate the end of the original object and the beginning of the
replacement object.

ABNF for use:

"-register" SPACE off / "-register" SPACE "on" SPACE action SPACE maintid

action = "add" / "mod" / "del"

;add: This conditionally required argument indicates that the object being
sent should be added to the server's database.

;mod: This conditionally required argument indicates that the object being
sent is a modification of a object that already resides on the server's
database. The identifying characteristics of the original (unmodified)
object are sent first, then the "_NEW_" separator is used, and then the
entire replacement object is sent.

;del: This conditionally required argument indicates that the object being
sent should be deleted from the server's database.

maintid = EMAIL ;This argument identifies, for maintenance purposes, the

sender of

the registration information. The server SHOULD NOT use the maintid for
authentication purposes.
The "register" directive is essentially used to deliver a payload of
registration data from the client to the server. This payload is
encapsulated between a "-register on �" directive and a "-register off"
directive. The format and necessary elements of the registration data depend
upon the action being performed.

In general, the registration data follows the "tag: value" format, where
"tag" refers to an attribute name (or alias) and "value" is a character
string that is valid for the particular attribute.

For the "add" action, the client MUST send all required attributes for the
object, including the base schema attributes (especially the "Schema-Name"
and "Auth-Area" attributes), except that the client MUST NOT send the "ID"
or "Updated" attributes. These attributes will be assigned by the server.

For the "mod" action, the client MUST send the identifying information for
the object to be changed followed by the "_NEW_" separator and the entire
changed object. The key fields (including the "ID", "Schema-Name", and
"Auth-Area" attributes) MUST match the original object. The identifying
information consists of the "ID", "Updated", "Schema-Name", and "Auth-Area"
attributes. Other attributes MAY be sent, but the server is not obligated to
check them. The purpose of sending the old object data before the new,
changed object is primarily to allow the server to perform record locking.

For the "del" action, the client MUST send the identifying information for
the object to be deleted. The identifying information is the same as for the
"mod" action.

When performing either the "mod" or "del" actions, if the object to be

changed/deleted has any "Guardian" attributes, the action SHOULD be
authenticated according to the guard-schemes present in those objects.

Response:

When adding an object to the server, the server will assign the record an
"ID" attribute and value, and generate a "%register" response. The register
response is "%register attribute: value". Currently, the only attribute that
register reports this way is "ID".

Example of use:

-register off

%register ID: 123456789.a.com

%ok

Example of use:

This example assumes that only "Name" and "Email" are required for the
contact schema, and that "Name" is a key but "Email" is not.

-register on add scottw@netsol.com

Schema-Name: contact

Auth-Area: a.com

First-Name: Scott
Last-Name: Williamson

Name: Williamson, Scott

Email: scottw@a.com

-register off

%register ID: 23456789.a.com

%ok

-register on mod scottw@netsol.com

ID: 23456789.a.com

Updated:

Schema-Name: contact

Auth-Area: a.com

_NEW_

Schema-Name: contact

Auth-Area: a.com

ID: 23456789.a.com

First-Name: Scott

Last-Name: Williamson

Name: Williamson, Scott

Email: sw@a.com

-register off

%ok

-register on del scottw@netsol.com

ID: 23456789.a.com

Updated: 19961205124403

Schema-Name: contact

Auth-Area: a.com

-register off

%ok

Errors:
%error 120 Registration not processed... will process hours:<hours>

%error 320 Invalid attribute line:<line number>

%error 321 Invalid format line:<line number>

%error 322 Required attribute missing name:<attribute name>

%error 323 Required related object missing name:<object name>

%error 324 Primary key not unique

%error 338 Invalid directive parameter

%error 339 Authority Area Not Found

%error 420 Registration not authorized

%error 421 Not authorized to change object:<object name> key:<key>

%error 438 Directive not implemented

%error 439 Directive not enabled

5.2.14 class

Client Capid: {1000h}

Server Capid: {80h}

RWhois data is a collection of classes with defined attributes. The

attributes for a class can be acquired by issuing the "-schema" directive.
Each class must at a minimum define the attribute "schema-name." This
attribute identifies the name of the class that will be displayed in
response to the "-class" directive. This directive can be used by a client
to verify that a server contains the desired class. Another possible use may
be to gather all of the classes contained on a server and display them to
the user in the form of a menu for selection.

ABNF for use:

"-class" SPACE autharea

class = 1*CHAR ;This argument identifies the class requested. If no argument

is

sent, all classes contained in the server will be returned.

Example of use:

-object domain

Response:

All visible classes on an RWhois server must be identified in response to a

"-object" directive. The "%class" response either confirms the existence of
a class or returns a complete list of all classes available to the currently
connected user.
A blank "%class" line serves as a class separator.

ABNF for use:

"%object" SPACE class (":description:" description) /

(":restrict:" restriction)

class = 1*CHAR ;This argument is the name of the class.

description = 1*CHAR ;This argument is a description of the class

identified.

restriction = 1*CHAR ;This argument is a list of words used to restrict a

search to this class.

Example of use:

%object contact:description:user records for entity POC

%object contact:restrict:user

%object user:restrict:person

Error:

%error 336 Class not defined

%error 338 Invalid directive parameter

%error 438 Directive not implemented

%error 439 Directive not enabled

5.2.15 define

Client Capid: {2000h}

Server Capid: {40h}

Directive:

Format strings describing the format of an object's attribute may include

format macros. More information about definitions of format macros can be
found in Appendix B. The "-define" directive allows the client to request
the definition of a format macro.

ABNF for use:

"-define" SPACE name

name = 1*CHAR ;This argument identifies the name of the macro to display. If
no arguments are sent, the server must return the definition of all macros
contained in the server.

Example of use:

-define server
Response:

The "%define" response describes format macros to the client. All format
macros used in the schema format definition string must be available to the
client through the "-define" directive. Format macros may be nested. It is
the client's responsibility to request all format strings that are
unrecognized from a server. If the format strings change on a server, the
serial number of the schemas that use the format must change.

ABNF for use:

"%define" SPACE name ":" "[" fmtstring "]"

NOTE: The brackets around the format string are required to ensure that
spaces contained in the format string are interpreted correctly by the
client.

Example of use:

%define server:[%s:%16Bd]

%define email:[%s@%s]

Error:

%error 338 Invalid directive parameter

%error 435 Macro not defined

%error 438 Directive not implemented

%error 439 Directive not enabled

5.2.16 private

Client Capid: {4000h}

The "-private" directive allows the client to identify the authentication

method to be used.

ABNF for use:

"-private" SPACE mode SPACE direction SPACE [method] SPACE [data]

mode = "on" / "off" ;On: This turns on the reception of secured information.

;Off: This signals the end of the secured information. Specifically, it

cancels the previous -private on.

direction = "request" / "response"

;Request: Client-to-server data will be encrypted or authenticated.

;Response: Server-to-client data will be encrypted or authenticated.

method = 1*CHAR ;This parameter is REQUIRED when the mode is "on". It is not
required for "off". This string is used to indicate what type of
authentication/encryption is used within the block. "PGP" is used for Pretty
Good Privacy (PGP)-style signed or encrypted message; "PW" is used for
standard UNIX-style username:password. The scheme is case insensitive.

data = 1*CHAR ;This is a one or more conditionally needed arguments

providing additional data supporting the method.

For PGP, it is an argument describing how the data has been treated
(signed|encr|signed-encr), and, if necessary, a keyid. For password, it is
the cleartext password itself. The <method> and <data> parameters have been
left fairly open to allow for a number of different security schemes.

Example of use:

-private on request PGP signed

-private on response PGP encr

-private on request PW mypassword

-private off

5.2.17 X-

Client Capid: {8000h}

Server Capid:{800h}

Directive:

This directive is the preface to extended directives, mutually agreed to

between the client and server. The client and server must have knowledge of
which extended directives to use. Extension can accommodate other uses such
as NetHelp, white pages, and many others. If the extensions are public, they
SHOULD be documented in an RFC and available through the "-directive"
directive.

ABNF for use:

"-X-" directive SPACE *[arguments]

directive = 1*CHAR ;This argument identifies the name of the directive being
issued.

arguments = 1*CHAR ;This repeatable argument is dependent upon the required

or optional arguments of the extended directive. There may be multiple
directive arguments.

Example of use:

-X-date

Response:

The "%X-" response represents extended responses. The client must have prior
knowledge of this response.

ABNF for use:

"%X-" response SPACE *[arguments]

response = 1*CHAR ;This argument contains the response name.

arguments = 1*CHAR ;This argument contains the arguments for the extended
directive.

Example of use:

%X-extstatus numusers:500

%X-extstatus avalslots:200

Errors:

%error 338 Invalid directive parameter

%error 438 Directive not implemented

%error 439 Directive not enabled

%error 460 Extended directive not recognized

%error 461 Extended directive not authorized

5.2.18 directive

Client Capid: {10000h}

Server Capid: {100h}

Directives allowed by a server may vary. The client can issue the
"-directive" directive to determine if the server allows a specific
directive or to obtain a list of all acceptable directives for that server.

ABNF for use:

"-directive" SPACE [directive]

directive = 1*CHAR ;This argument identifies the directive being requested.

If no

arguments are sent, all of the directives accepted by the server MUST be
sent.

Example of use:

-directive X-date

Response:

The "%directive" response is used to display directives allowed on the

connected server. The directive name, description, and syntax attributes
MUST be sent for each directive. If information about a single directive is
requested, then only information about that directive MUST be returned. A
"%directive" response with no arguments MUST be sent between directives.

ABNF for use:

"%directive" SPACE [("directive:" directive) / ("description:" description )

/ ("syntax:" format)]
The arguments below are required except when separating directives.

Directive = 1*CHAR ;This argument indicates the name of the directive.

Description = 1*CHAR ;This argument describes the directive.

Format = 1*CHAR ;This argument defines the format of the directive. It MUST
be expressed in human-readable form.

Example of use:

%directive directive:schema

%directive description:displays schema attributes

%directive syntax:schema<SP>[%s]

%directive

%directive directive:xfer

%directive description:transfer all object[authority area]

%directive syntax:xfer<SP>[%s]<SP>[%s]

5.2.19 display

Client Capid: {20000h}

Server Capid: {400h}

Directive:

The "-display" directive is used to set the display mode of the server or to
identify display modes of which the client is capable. If this directive is
sent without arguments, the server will return all available display
methods.

ABNF for use:

"-display" SPACE [action] SPACE [method]

action = "activate" / "capable"

;The 'activate' setting enables a certain display mode, while a 'capable'

setting sends the display mode of which the client is capable.

Method = 1*CHAR ;This argument indicates the display method desired by the
client.

Example of use:

-display mime

The "%display" response is used to inform the client that the data following
this response is using the indicated method. The method selected will
continue to be active until a "%display" response is sent without any
arguments. The server must send an error message to clients that have been
identified as non-RWhois clients. This response allows the use of display
methods such as MIME [RFC 1521] or other special character sets such as
those used in the Japanese language.

ABNF for use:

"%display" SPACE (("extended:" extended) / ("name:" name ) / ("length:"

length) / ("description:" description ) /

( "command-line-option:" mode)

extended ;This argument identifies if the display method is extended, for

example, RWhois specific.

Example of use:

%display extended:mime

MIME-Version:1.0

Content-type: image/gif

Content-Transfer-Encoding: base64

...data...

%display

Error:

%error 338 Invalid directive parameter

%error 436 Display mode not allowed

%error 438 Directive not implemented

%error 439 Directive not enabled

5.2.20 language

Client Capid: {40000h}

Server Capid: {1000h}

The "-language" directive is used to set the language mode of the server or
to identify language modes of which the server is capable. If this directive
is sent without arguments, the server will return all available languages.
The International Standards Organization (ISO) language code is used to
identify the language to be used.

ABNF for use:

"-language" SPACE [language]

language = 1*CHAR ;This argument indicates the language desired by the

client.

Example of use:
-language nl

Response:

The "%language" response is used to inform the client that the data
following this response will be sent in the indicated language. The language
selected will continue to be active until a "%language" response is sent
without any arguments, at which time the server will revert back to English,
the default. The server must send an error message to clients that have been
identified as non-RWhois clients.

ABNF for use:

"%language" SPACE language

Example of use:

%language de

RWhois Deutsche Version: 1.0

%language

Error:

%error 338 Invalid directive parameter

%error 437 Language not supported

%error 438 Directive not implemented

%error 439 Directive not enabled

6. Security Model

6.1 Object Security

Objects security is provided using the Guardian model.

6.2 Authority Area Security

Authority area security is provided by identifying the guardian for the

authority area's SOA object.

6.3 Server-to-Server Security

7. Tree Management

7.1 Determining Authority

Authority areas are a major part of the RWhois protocol. If an authoritative

response is required, turning the cache off is the first step. The client
can also determine if the server connected has authority over the
name/number space of interest by sending the "-soa <authority area>"
directive. If the server has authority for the area requested, it must
return important information about the authority area. The exchange below is
a client determining if the server is an authority for abc.net or no.net.

S wait for connection

C connect to rs.internic.net port 4343

S %RWhois V-1.1: rs.internic.net (Network Solutions, Inc. V-2.0)

C -RWhois V-1.1 (Network Solutions, Inc. V-2.0)

S %ok

C -cache off

S %ok

C -soa abc.net

S %error 333 Not SOA for requested authority area

S %ok

C -soa no.net

S %soa authority: no.net

S %soa ttl: 7500

S %soa serial: 45

S %soa refresh: 3600

S %soa retry: 3600

S %soa tech-contact: markk@no.net

S %soa admin-contact: stanb@no.net

S %soa hostmaster: hostmaster@no.net

S %ok

7.2 Secondary Server Interaction

A server that operates as a secondary will report an authoritative SOA for

the authority area of the data it contains. Below is the interaction between
the primary and secondary server. In reality, the secondary operation would
be performed using a client specifically designed for this purpose.

S wait for connection

C connect to slam.internic.net port 4343

S %RWhois V-1.1 slam.internic.net (Network Solutions Inc. V-2.0)

C -RWhois V-1.1 (Network Solutions Inc. V-2.0)

S %ok

C -soa internic.net

S %soa authority: internic.net

S %soa ttl: 7500

S %soa serial: 45

S %soa refresh: 3600

S %soa retry: 3600

S %soa tech-contact: markk@internic.net

S %soa admin-contact: stanb@internic.net

S %soa hostmaster: hostmaster@rs.internic.net

S %ok

C -xfer internic.net class=domain

S ... all data for domain object in the internic.net authority area
transferred

S%ok

C -notify inssec netman1.netsol.com:4343:internic.net

S %ok

C -quit

S close connection

C close connection

7.3 Out-of-Service

Servers that are being taken out of service should automatically refer the
client back into the tree. Of course, this is not possible if the system
that hosts the server is out of service. In this case, the client's
robustness must be relied upon to return to the referrer and notify that
server that the referral was bad. If the system will still be available on
the Internet, the exchange below is recommended.

S wait for connection

C connect to slam.internic.net port 3636

S %RWhois V-1.1:ff4ff:5:2 slam.internic.net (Network Solutions Inc. V-2.0)

C -RWhois V-1.1 (Network Solutions Inc. V-2.0)

S %info on

S This server will no longer be in service. You should

S change your configuration file to reflect the new root

S server at rs.internic.net:4321. You will automatically be

S referred to the new root.

S %error 200 Service not available referral to follow

S %referral rs.internic.net:4343

S close connection

C close connection

8. 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.

[RFC-1714] Williamson, S., Kosters, M., "Referral Whois Protocol", RFC 1714,
Network Solutions, November 1994.

9. Authors' Addresses

Scott Williamson

505 Huntmar Park Dr.

Herndon, VA 22070

Phone: (703) 742-4820

email: scottw@netsol.com

Mark Kosters

505 Huntmar Park Dr.

Herndon, VA 22070

Phone: (703) 742-4795

email: markk@netsol.com

Appendix A: Error Codes

The error code MUST immediately follow the "%error" response from the RWhois
server. 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. (For example, if a client received "%error 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 command error, retry that command 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

A.1 Error Code List

Below is an ordered list of RWhois error codes. These codes may be extended
with implementation-specific codes. These extended codes will have a '6' in
the second position of the code.

100 Get Peer Name query failed

120 Registration not processed... will process hours:<hours>

121 No handle for record... generated one:<handle>

130 Not authority for answer... TTL good

200 Service not available... Referral to follow

230 No Records Found

231 Not authority for answer... TTL expired

232 Cache disabled

300 Not compatible with that version number

320 Invalid attribute line:<line number>

321 Invalid format line:<line number>

322 Required attribute missing name:<attribute name>

323 Required related object missing name:<object name>

324 Primary key not unique

330 Exceeded Max Records Limit

331 Invalid Max Records Size

332 Nothing to transfer

333 Not SOA for requested authority area

335 System's load not available

336 class not defined

337 class definition not found

338 Invalid directive parameter

339 Authority Area Not Found

340 Query too complex

400 Invalid Server Directive

401 Not authorized for directive

402 Unidentified error... continue

420 Registration not authorized

421 Not authorized to change object:<object name><SP>key:<key>

431 Not authorized to forward

432 Not authorized to transfer

433 Bad reference on forward

434 Referral does not exist on this server

435 Macro not defined

436 Display mode not allowed

437 Language not supported

438 Directive not implemented

439 Directive not enabled

460 Extended directive not recognized

461 Extended directive not authorized

500 Memory Allocation Problem

501 Service not available

502 Unrecoverable error... goodbye

503 Idle time exceeded... goodbye

530 Not authorized as secondary

Appendix B: Attribute Format

The format for all attributes for objects in the RWhois server must be
specified using a format specifier. This definition will allow the client
software to interpret the received data correctly. The RWhois format
specifier closely follows the 'C' language scanf syntax with macro
extensions.

Format specifiers must follow this pattern:

%[alignment][length restriction]<type>[range restriction]

[alignment] '-' = left justified

'.' = right justified

[length restriction] <value> = number of bytes allowed

<value>B = number of bits allowed

<type> This is the only required part of the format specifier. Below are the
allowed format type values. The length of these values are not specified.
These restrictions will be on the left of the [length restriction].

%c Character

%s String

%d Integer

%x Hex Integer

%o Octal Integer

%f Float

%e Scientific

%M Defined Macro

[range restriction] The range restriction will limit the allowed values.
This may specify a number, character, or string range.

Examples: %-3s["ON","OFF"] = Defines a string with 3 characters left aligned

and limited to the strings ON or OFF.

%16Bd[0-50] = 16 bit integer between 0 and 50

%4.2f[0-2500.50] = Defines a floating point number limited to 4 digits

before and 2 after the decimal with a value between 0 and 2500.50.

B.1 Format Specification Macros

Format specifications may be presented as macros. Format specification

macros may be defined using the following format.
%M<macro name>=<format string or earlier macro>

The following macros are pre-defined in this RWhois specification.

Month/Day/Year formats:

%MM=[%-2d[0-12]]

%MD=[%-2d[0-31]]

%MY2=[%-2d[0-99]]

%MY4=[%-4d[0-9999]]

%MMs=[%-3s\ ["JAN","FEB","MAR","APR","MAY","JUN","JUL","AUG","SEP",\

"OCT","NOV","DEC"]]

Date formats:

%Mdate1=[%MM/%MD/%MY2]

%Mdate2=[%MM/%MD/%MY4]

%Mdate3=[%MD-%MMs-%MY2]

%Mdate4=[%MD-%MMs-%MY4]

%Mdate5=[%MY4%MM%MD]

Hour/Minute/Second formats:

%MTH=[%-2d[0-24]]

%MTM=[%-2d[0-59]]

%MTS=[%-2d[0-59]]

Time formats:

%Mtime1=[%MTH:%MTM:%MTS]

%Mtime2=[%MTH%MTM%MTS]

Miscellaneous formats:

%Mserver=[%s:%16Bd]

%Mipnumber=[%8Bd.%8Bd.%8Bd.%8Bd]

%Memail=[%s@%s]

%Mserial=[%Mdate5%Mtime2]

%Mstype=[RWHOIS/WHOIS/WHOIS++/LDAP/OTHER]

%Murl=[%s://%s]
Macro definitions may be obtained by sending the "-define" directive to the
server. For client efficiency, definitions can be remembered. If the
definition of a macro changes, the serial number of all schemas using that
macro must change, allowing the client to reacquire the schema and format
specifier macros.

Appendix C: 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 it can accept. The client responds with the server responses that
it can understand. Below is the capabilities list.

Directives: (Sent by the server)

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

Responses: (Sent by the client)

see-also 1h

load 2h
soa 4h

status 8h

xfer 10h

schema 20h

define 40h

object 80h

directive 100h

info 200h

display 400h

X- 800h

language 1000h

Display (Sent by both server and client)

Mime 1h

URL 2h

Format for use:

<directives>:<display>:<???>{%6x:%2x%2x}

<responses>:<display>:<???>{%6x:%2x%2x}