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: . where can be any string without the period character that is unique to the local RWhois installationís database, and where 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: %error 320 Invalid attribute line: %error 321 Invalid format line: %error 322 Required attribute missing name: %error 323 Required related object missing 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: 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 and 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[%s] %directive %directive directive:xfer %directive description:transfer all object[authority area] %directive syntax:xfer[%s][%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 " 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: 121 No handle for record... generated one: 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: 321 Invalid format line: 322 Required attribute missing name: 323 Required related object missing 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: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][range restriction] [alignment] '-' = left justified '.' = right justified [length restriction] = number of bytes allowed B = number of bits allowed 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= 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: ::{%6x:%2x%2x} ::{%6x:%2x%2x}