Network Working Group Bruce Campbell Internet Draft RIPE NCC Expires: May 2002 November 2001 Updates: RFC954 The basic NICNAME/WHOIS protocol draft-campbell-whois-00.txt Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC 2026 [RFC2026]. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. Abstract This memo defines the basic WHOIS protocol as used on the Internet today. Campbell [Page 1 ] draft-campbell-whois-00.txt WHOIS November 2001 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1 History . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2 Aims of this Document . . . . . . . . . . . . . . . . . . 3 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1 Client . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.2 Server . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.2.1 Server Operator . . . . . . . . . . . . . . . . . . . 4 2.3 Registry . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.3.1 Database . . . . . . . . . . . . . . . . . . . . . . 5 2.3.2 Updating the Database . . . . . . . . . . . . . . . . 5 2.3.3 Normal Usage of Data . . . . . . . . . . . . . . . . 5 3. Protocol Definitions . . . . . . . . . . . . . . . . . . . . . 5 3.1 Connection . . . . . . . . . . . . . . . . . . . . . . . . 5 3.1.1 Port . . . . . . . . . . . . . . . . . . . . . . . . 5 3.2 Question . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.2.1 Language and Character Set. . . . . . . . . . . . . . 6 3.2.2 Flags . . . . . . . . . . . . . . . . . . . . . . . . 6 3.2.3 Question . . . . . . . . . . . . . . . . . . . . . . 7 3.2.4 Qualifiers. . . . . . . . . . . . . . . . . . . . . . 7 3.2.5 Question Termination . . . . . . . . . . . . . . . . 7 3.2.6 Help . . . . . . . . . . . . . . . . . . . . . . . . 7 3.3 Answer . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.3.1 Language and Character Set . . . . . . . . . . . . . 8 3.3.2 Output Format . . . . . . . . . . . . . . . . . . . . 8 3.3.3 Banner . . . . . . . . . . . . . . . . . . . . . . . 8 3.3.4 Search Result . . . . . . . . . . . . . . . . . . . . 8 3.3.5 Warning Messages . . . . . . . . . . . . . . . . . . 9 3.3.6 Error Messages . . . . . . . . . . . . . . . . . . . 9 3.3.7 Rejection Messages . . . . . . . . . . . . . . . . . 9 3.4 Termination of Connection . . . . . . . . . . . . . . . . 9 3.4.1 Normal Termination . . . . . . . . . . . . . . . . 10 3.4.2 Inactivity Timeout . . . . . . . . . . . . . . . . 10 3.4.3 Connection Timeout . . . . . . . . . . . . . . . . 10 3.4.4 Abuse of Service . . . . . . . . . . . . . . . . . 10 3.4.5 Other disconnection . . . . . . . . . . . . . . . . 10 4. Considerations . . . . . . . . . . . . . . . . . . . . . . . 10 4.1 IANA Considerations . . . . . . . . . . . . . . . . . . 10 4.1.1 Implementors Note on Assigned Port . . . . . . . . 10 4.2 Security Considerations . . . . . . . . . . . . . . . . 11 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 6. Author's Address . . . . . . . . . . . . . . . . . . . . . . 11 7. Full Copyright Statement . . . . . . . . . . . . . . . . . . 12 Campbell [Page 2 ] draft-campbell-whois-00.txt WHOIS November 2001 1. Introduction 1.1 History The original reference document for WHOIS[RFC954]] specifies two items. The first being a simple server<->client question and answer protocol known as 'WHOIS', running on port 43 of a given machine. The second item specifies a number of requirements for placement of data within the 'SRI-NIC' database. The second item has caused much confusion and quasi-religious debates over the years, especially given that the 'SRI-NIC' database has been superceded several times. 1.2 Aims of this Document This document aims to provide an accurate definition of the basic WHOIS protocol used on the Internet today. It includes observed variations on possible queries and answers. This document does NOT provide definitions of the possibly sensitive subjects as follows: Data that must be registered in any Database Data that must be protected by Privacy Concerns Output Format of Data Question Format (beyond a requirement for 'help') The above definitions are defined by the Registry operating a particular Database, and the Laws of that Registry's Country. 2. Requirements 2.1 Client The 'WHOIS' Client MUST be able to handle the 'WHOIS' Server being unavailable, or for the connection to be closed at any time during the transaction. The user of the client MUST be able to specify alternative 'WHOIS' Servers and alternative ports, and support of these capabilities SHOULD be made clearly known to the user. The 'WHOIS' Client SHOULD use the default 'WHOIS' destination port of '43' [STD2] when connecting to a given 'WHOIS' server, unless an alternative port has been specified by the User. Campbell [Page 3 ] draft-campbell-whois-00.txt WHOIS November 2001 2.2 Server The 'WHOIS' Server MUST be able to handle a 'reasonable' number of simultaneous 'WHOIS' Clients connecting to it. It MUST be able to handle any of these connections being closed at any time during the transaction. It SHOULD be able to issue an appropriate message to each connecting client if the number simultaneous clients exceeds it's 'reasonable' limits. At the time of writing, the RIPE NCC 'WHOIS' server was seeing regular spikes of 33 queries per second [NCC-DB-OP]. A public 'WHOIS' Server SHOULD have as one of its aliases, a hostname of 'whois', eg 'whois.example.com'. Such a Server MUST respond on the common 'WHOIS' port of '43'. [STD2] 2.2.1 Server Operator The Entity or Entities in charge of a given 'WHOIS' Server who is/are responsible for the behaviour and operation of a given Server. The Server Operator MUST report usage, problems (etc) with the 'WHOIS' Server to the Registry responsible for the Database. This implies that the Server MUST log usage of the Server in some fashion. The Server Operator, in addition to abiding by any restrictions set by the Registry, may add extra restrictions to the use of the Server, possibly dynamically in response to Client behaviour. 2.3 Registry The Entity or Entities in charge of a given Database which is accessible via a given 'WHOIS' Database. Normally, the Server Operator(s) and the Registry are the same Entities, however a distinction must be made between the two to reflect operational practice. Where the Registry is the custodian of Data covered by Privacy Restrictions, the Registry MUST enforce these restrictions. The Registry MAY also add extra restrictions to the use of it's Data/Database. Campbell [Page 4 ] draft-campbell-whois-00.txt WHOIS November 2001 2.3.1 Database This document does not specify the back-end database that is to be used by the Registry, or the interface between the Server and Database (which may also by via 'WHOIS'). Various databases have been used over time, ranging from flat file, to high performance SQL servers. It is left up to the implementor to choose an appropriate back-end database, and the replication of the Database to the WHOIS Server(s) serving that Database. The Database may be accessed by methods other or in addition to WHOIS. 2.3.2 Updating the Database The procedure for updating the Database is defined by the Registry. The Registry may require certain information required for the Registry's Operation to be registered within it's Database. The Registry SHOULD NOT impose a fee for required information to be registered within it's database, but MAY impose a fee for other services offered by the Registry. 2.3.3 Normal Usage of Data The exact usage of the Data within a Database is left for the Registry to define, however Data obtained via WHOIS has historically been for Internet Operational Purposes. Users should refer to the usage conditions imposed by a given Registry. 3. Protocol Definitions At it's heart, 'WHOIS' is a very simple format. However, many expectations have been placed on 'WHOIS' since it was first introduced. The following definitions cover all known installed varients. 3.1 Connection The connection is always initiated from the Client end, to the nominated 'WHOIS' Server. 3.1.1 Port Port 43 has been set aside for 'WHOIS'. Please refer to 4.1, IANA Considerations and 4.1.1, Implementors Note on Assigned Ports. TCP is assumed. Campbell [Page 5 ] draft-campbell-whois-00.txt WHOIS November 2001 3.2 Question On connecting to a 'WHOIS' Server, the Client MUST ask a 'Question'. The Client MUST be able to handle text being sent to the Client from the Server before the Question is started or completed, or the connection being closed for any reason. A Question is defined as having the following components: Where is optional, is optional, is required, and is optional. 3.2.1 Language and Character Set The 'WHOIS' Server operator MAY nominate a Language and Character Set to be used for any part of the 'Question'. If a Language or Character Set other than 'English' and 'US-ASCII' is expected from the Client, the Server MAY provide an initial banner message before the Question is asked, specifying the Language and Character set in use. [BCP18] 3.2.2 Flags This section of the 'Question' is OPTIONAL. The 'WHOIS' Server MUST accept any character sequences that the Server Operator has defined to be valid flags for the Server. The Server MUST respond to any invalid flags with an appropriate error message, and an indicator on where to get automated assistance on the valid flags for the Server. Flags, if provided, SHOULD be seperated from the question section by at least one 'whitespace' character, unless a given flag makes this optional. Campbell [Page 6 ] draft-campbell-whois-00.txt WHOIS November 2001 3.2.3 Question This section of the 'Question' is REQUIRED. The 'WHOIS' Server MUST accept any character sequences that the Server Operator has defined to be valid characters for the Server. The question SHOULD consist of printable characters for the Character Set that the Server Operator has nominated (defaulting to 'US-ASCII). Characters outside the nominated Character Set MAY be treated by the Server as an error, or otherwise ignored. The question SHOULD consist of a string which the Server SHOULD then use as a key for retrieving the appropriate data. Questions may be domain names, IP numbers, Person Records or other information which is known to be within the 'WHOIS' Database, eg: example.com 193.0.0.193 BC999-RIPE The Server MUST return an appropriate message if the indicated key is not found, or if the Database is otherwise unavailable. 3.2.4 Qualifiers This section of the 'Question' is OPTIONAL. The 'WHOIS' Server Operator MAY define additional qualifiers to enable the Client to control the output from the 'WHOIS' Server. The Server MUST accept any valid sequences, and MAY treat invalid sequences as an error. A suggested use for an additional qualifier to for the Client to specify the output Language. [JPNIC] 3.2.5 Question Termination A 'Question' must be terminated by the Client by the 'CR/LF' character combination. 3.2.6 Help The Client MAY ask for assistance on using the 'WHOIS' Server. The Server must ignore any other parts of the Question and respond with an appropriate 'Help' message, or a URL to the Usage guide of the 'WHOIS' Server. The Server MUST accept the literal string 'help' in the US-ASCII Character Set as an indicator for the above behaviour. The Server SHOULD also accept variations on 'help' in the Language and Character Set used by the 'WHOIS' Server. Campbell [Page 7 ] draft-campbell-whois-00.txt WHOIS November 2001 3.3 Answer After the Client has finished asking the 'Question' with the CR/LF, the Server MUST supply an Answer. Where the Answer contains more than one of the items listed below, each section SHOULD be seperated from the next by a blank line. 3.3.1 Language and Character Set The Server MUST reply in the Language and Character Set nominated by the Server Operator, or the Language or Character Set requested by the Client by Question Flags or Qualifiers, or in English/US-ASCII if the literal string 'help' in US-ASCII was supplied as the Question. 3.3.2 Output Format The Server MUST reply according to the output format defined by the Server Operator. A method of obtaining the specifications of the output format MUST be obtainable via the Server's 'help' information. 3.3.3 Banner The Server MAY supply a Banner Message at three points during the connection: Immediately after initial connection, Immediately after the termination of the Question by the Client and before the output of the Answer. Immediately after the output of the Answer. To assist readability, the Banner Message SHOULD NOT exceed a polite 4 lines. The Client MUST display any Banner Message to the User without alteration. The usual purpose of a Banner Message is to supply to the Client any Copyrights that may be on the data supplied by the Server, or a URL to the full Copyright information. 3.3.4 Search Result The Server MUST supply the results of a valid question, where that data is within its database and restrictions on publications of that data have been observed. Where multiple data records are matched by the question, the Server MAY supply a summary, OR all of the matched records where appropriate or requested by optional flags or qualifiers. A given result may refer to other records, which the Server MAY also supply in the Answer. Multiple Results SHOULD be seperated from one another by a blank line. Campbell [Page 8 ] draft-campbell-whois-00.txt WHOIS November 2001 3.3.5 Warning Messages The Server MAY supply Warning Messages where part or all of the Question is inappropriate as defined by the Server Operator. Warning Messages should supply accurate and up to date information about the perceived problem with the Question, Connection or Client. A Warning Message SHOULD NOT prohibit the output of any results for the Question. 3.3.6 Error Messages The Server MAY supply Error Messages where part or all of the Question is inappropriate as defined by the Server Operator. Error Messages should supply accurate and up to date information about the perceived problem with the Question, Connection or Client. An Error Message SHOULD prohibit the output of any results for the Question. 3.3.7 Rejection Messages These are a special form of Error Message for 'problem' Clients. They should clearly state why a given Question, Connection or Client has been rejected. Unless a given Client is causing problems with the operation of the Server by inappropriate usage of the Server (as defined by the Server Operator), the Server MUST always accept a Connection attempt from the given Client. Possibly inappropriate usage of a Server or Database by a Client may consist of one or more of: Too high a query rate. Usage of data obtained in violation of the provided Copyright or Usage guides for the Server/Database. Automated or Predictable Query Patterns. 3.4 Termination of Connection Both the Client and the Server MUST handle the Connection being closed at any point through the transaction. The Connection may be closed due to one of the reasons below, or through factors outside the scope of this document. Where possible, the Server MUST issue an Error Message to the Client indicating the reason for the disconnection, before the connection is closed. The Client MUST be provided with appropriate contact information should the Client wish to challenge the disconnection. Campbell [Page 9 ] draft-campbell-whois-00.txt WHOIS November 2001 3.4.1 Normal Termination Unless specified otherwise by flags or qualifiers in the Question, the Server MUST close the connection immediately after outputting the full Answer. The Server does NOT need to supply a reason for this expected disconnection. 3.4.2 Inactivity Timeout The Server Operator MAY impose a time limit on how long a given Connection may be idle before it is closed due to Inactivity. 3.4.3 Connection Timeout The Server Operator MAY impose a time limit on the total time used by a given Connection. 3.4.4 Abuse of Service The Server Operator MAY impose a 'block' on a given Client due to behaviour demonstrated by the Client which transgresses the published Usage Guidelines. 3.4.5 Other disconnection The Server Operator MAY have other reasons to disconnect a given Client. 4. Considerations 4.1 IANA Considerations IANA has already assigned TCP and UDP port 43 to NICNAME/WHOIS. This document does not specify any additional ports. 4.1.1 Implementors Note on Assigned Port Implementors Note: IANA has set aside port 43 TCP and UDP for NICNAME/WHOIS. The Author of this document has not seen any production Clients or Servers that operate using UDP. Where a Server responds on UDP, the Server MUST also respond on TCP, if only to emit a banner indicating the use of UDP. Campbell [Page 10] draft-campbell-whois-00.txt WHOIS November 2001 4.2 Security Considerations Security Considerations of the WHOIS Protocol are not discussed in this document. Security Considerations related to the exposure of Data that may be in a given Database are left to the Registry responsible for that Database. 5. References [BCP18] H. Alvestrand, "IETF Policy on Character Sets and Languages", RFC2277/BCP18, January 1998. [RFC954] K. Harrenstien, M. Stahl, and E. Feinler, "NICNAME/WHOIS", RFC954, October 1985. [RFC2026] S. Bradner "The Internet Standards Process -- Revision 3", RFC2026/BCP9, October 1996. [STD2] J. Reynolds and J. Postel, "Assigned Numbers", RFC1700/STD2, October 1994. [NCC-DB-OP] RIPE NCC Whois Server, Operational Plots http://www.ripe.net/ripencc/pub-services/db/ [JPNIC] JPNIC Whois Database, Specifying '/e' for English Language Output, http://www.nic.ad.jp/ 6. Author's Address Bruce Campbell RIPE NCC Singel 258 Amsterdam 1016AB The Netherlands Phone: +31 20 535 4444 Fax: +31 20 535 4445 EMail: bruce_campbell@ripe.net Campbell [Page 11] draft-campbell-whois-00.txt WHOIS November 2001 7. Full Copyright Statement Copyright (C) The Internet Society (2001). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Campbell [Page 12]