Advisory: Clarifications to the Registry and Registrar Requirements for WHOIS (port 43) and Web-Based Directory Services

Publication date: 12 September 2014; Updated on 27 April 2015; Further Updated on 25 May 2018

Redline of changes [PDF, 184 KB]

This Advisory is intended to provide clarification for registries and registrars regarding their WHOIS (port 43) and Web-based Directory Service (jointly called Whois in this document) specifications required for compliance with the Registry Agreement and Registrar Accreditation Agreement, respectively.

The clarifications in Section I are applicable to both registries and registrars; Section II applicable only to registries; and Section III applicable only to registrars.

One of the objectives of these clarifications is to retain the ability to easily parse the output. Interested users are encouraged to consider the clarifications below when developing parsers for WHOIS output.

The terms "MAY", "MUST", "MUST NOT", "REQUIRED", "SHOULD NOT" and "SHOULD" are used to indicate the requirement level in accordance with RFC 2119, which is available at http://www.ietf.org/rfc/rfc2119.txt [TXT, 5 KB].

1. The following clarifications apply to both Registry and Registrar Registration Data Directory Services specifications:

   1. For each type of object query (domain name, registrar, name server), this advisory identifies some fields as optional. For optional fields where no data exists in a contracted party's Registration System (SRS), the contracted party MUST implement either of: 1) the key (i.e., the string to the left of the colon) MUST be shown with no information in the value section (i.e., right-hand side of the colon) of the field; or 2) no field MUST be shown. If data exist for a given optional field, the key and the value with the data MUST be shown.

   2. In responses to domain name object queries, the following fields are considered optional and should be treated as described in clarification 1:

      • Updated Date (if the domain name has not been updated since it was created)

      • Registrant/Admin/Tech Organization

      • Registrant/Admin/Tech State/Province

      • Registrant/Admin/Tech Postal Code

      • Registrant/Admin/Tech Phone Ext

      • Registrant/Admin/Tech Fax

      • Registrant/Admin/Tech Fax Ext

      • Name Server

      For example, a query for a domain name without Name Servers (and no DS or DNSKEY records) can generate any of the following two outputs:

      …
      Tech Email: EMAIL@EXAMPLE.TLD
      Name Server:
      DNSSEC: unsigned
      …

      or

      …
      Tech Email: EMAIL@EXAMPLE.TLD
      DNSSEC: unsigned
      …

   3. As described in RFC 3912, the WHOIS protocol (port-43) has not been internationalized. Registries and Registrars are encouraged to only use US-ASCII encoding and character repertoire for WHOIS (port-43) output. If the Registry Operator/Registrar uses characters outside of the US-ASCII repertoire, the output SHOULD be encoded in UTF-8 to maximize the chances of interoperability.

   4. The Whois output MAY show a translation of the name of the key in other languages, however, the first entry in the key MUST be shown as it appears in the agreement and the translation(s) MUST be shown between parenthesis (U+0028 and U+0029) with a space (U+0020) between the key of the field (as specified by the 2013 RAA or the Registry Agreement, as the case may be) and the opening parenthesis (U+0028). Different translations MUST be separated by a solidus (U+002F). The closing parenthesis (U+0029) MUST be immediately before the colon. A space or spaces MUST NOT be shown between the translation of the name of the key and the parenthesis (U+0028 and U+0029). A space or spaces MUST NOT be shown between the solidus (U+002F).

      For example, "Domain Name:" could be shown in Spanish and Portuguese as:

      Domain Name (Nombre de Dominio/Nome de Domínio): foo.example

   5. All domain name labels in the values of any of the fields (e.g., Domain Name, Name Server, email) MUST be shown in ASCII-compatible form (A-Label).

      For example, a name server with an IDN label should be shown as:

      Name Server: ns1.xn--caf-dma.example

   6. If the Domain Name is an IDN, the Registry Operator/Registrar MAY show the IDN in U-Label format using the "Internationalized Domain Name:" key. If shown, the field MUST appear as either an additional field as defined in clarification 1, or immediately following the field "Domain Name". For example:

      Domain Name: xn--caf-dma.example
      Internationalized Domain Name: café.example
      …

      or

      …
      DNSSEC: signedDelegation
      Internationalized Domain Name: café.example

   7. Domain statuses MUST conform to the mappings specified in the EPP RFCs: 5730-5734, and 3915. Per the AWIP (https://www.icann.org/resources/pages/policy-awip-2014-07-02-en), the EPP status MUST be immediately followed by, at least one, and no more than nine spaces (U+0020) then followed by a URL corresponding to the description of the status in the ICANN website. For an example, please see clarification 1.

   8. The date and time shown in the footer ">>> Last update of Whois database: <date and time> <<<" refers to the date and time (in RFC 3339 format) in which the Registration Data Directory Services (RDDS) database was updated from the SRS database. As per the service level requirement described in section 1.4.2 of the 2013 RAA, and Specification 10 of the Base Registry Agreement, the RDDS services must be updated within 60 minutes of any change. In a case where the contracted party is querying its SRS database directly, and therefore, using real-time data, this date and time will show the timestamp of the response to the query.

   9. IP address(es) for name servers SHOULD NOT be shown in the output of Whois queries for domain names. If shown, the IP address(es) MUST appear immediately following the corresponding name server as it is done for name server object responses.

   10. "DNSSEC: signedDelegation" MUST be shown when there is one or more DS or DNSKEY records in the SRS for the domain name being queried. "DNSSEC: unsigned" MUST be shown in all other cases.

   11. If additional data fields are included in the Whois output beyond those required by contract or policy, the additional data fields MUST be placed at the end of the response, except where otherwise described in this Advisory or required by policy or contract.

   12. JavaScript or other client-side script code MUST NOT be added to the output of (port 43) WHOIS, and the data from the objects that could be wrongfully interpreted as markup language MUST be properly escaped in web-based Whois.

   13. The output of web-based Whois MUST follow the same conventions as that of WHOIS (port 43).

   14. Each field (key/value pair) MUST be terminated with ASCII CR and then ASCII LF <U+000D, U+000A>. (See Section 2 of RFC 3912, WHOIS Protocol Specification). This applies to paragraphs used for legal disclaimers or any other lines shown in the Whois output.

   15. Key and values MUST be separated by a colon followed by one space, ": " <U+003A,U+0020>.

       For example, a name should be shown as:

       Name Server: ns1.xn--caf-dma.example

   16. Leading spaces SHOULD NOT appear in the Whois output. If included, no more than 9 leading spaces MUST appear. Trailing spaces MUST NOT be included.

   17. There SHOULD NOT be empty lines between the last data field in the response and the footer ">>> Last update of Whois database: <date and time> <<<". No more than three empty lines MUST appear between the last data field in the response and the "Last update" footer.

   18. WHOIS (port-43) queries for domain name objects SHOULD return only one record per query (i.e., no partial match or other searchability capabilities, only exact match lookup).

   19. All fields are case sensitive. The key (i.e., the string to the left of the colon) is case sensitive and it MUST be shown as specified by contract or policy.

   20. The ASCII CR and/or ASCII LF <U+000D, U+000A> MUST only appear at the end of a field.

   21. Registry Operator and Registrar MUST use fully qualified domain names. Registry Operator SHOULD NOT include the trailing dot when displaying domain names.

   22. Registry Operator and Registrar MAY show the Billing Contact information for the domain name, subject to other contractual and policy requirements. If shown, the contact fields MUST be shown either as additional fields as defined in clarification 1 of this document or, immediately following the technical contact data fields.

   23. Per the Additional Whois Information Policy (AWIP) (https://www.icann.org/resources/pages/policy-awip-2014-07-02-en), Whois output MUST include a footer as follows "For more information on Whois status codes, please visit https://icann.org/epp". The AWIP footer MUST be shown after the last update footer described in clarification 17. At least an empty line and no more than three MUST precede the AWIP footer. The legal disclaimer MUST come after the AWIP footer, preceded by at least an empty line and no more than three. For example:

       Domain Name: foobar.example
       Registry Domain ID: D1234567-example
       …
       DNSSEC: signedDelegation
       URL of the ICANN Whois Inaccuracy Complaint Form: https://www.icann.org/wicf/
       >>> Last update of WHOIS database: 2009-05-29T20:15:00Z <<<

       For more information on Whois status codes, please visit https://icann.org/epp

       Terms of Use: Users of this Whois service …

   24. Fields in Whois output MUST NOT appear multiple times, unless otherwise explicitly specified.

   25. In responses to domain name object queries, the following fields can have multiple values and, therefore, MAY appear multiple times:

       • Domain Status

       • Name Server

       • Registrant/Admin/Tech/Billing Street (i.e., following EPP RFC 5733 usage)

   26. When receiving a query for an object that does not exist in the SRS, the contracted party SHOULD return the key "The queried object does not exist: ", optionally followed by a registry-defined text message (the value) that provides more information about the non-existence of the object. No other fields MUST be shown. The "last update" footer, blank line, and legal disclaimer MUST follow as with other Whois queries.

2. The following clarifications only apply to Registries.

   27. In responses to name server queries, the following fields are considered optional and should be treated as described in clarification 1:

       • Registrar

       • Registrar WHOIS Server

       • Registrar URL

   28. WHOIS (port-43) queries for name server objects SHOULD NOT offer partial match or other searchability capabilities.

   29. A query for a name server object, using either the name server name or IP address as the query string might match more than one object. In such case, the registry SHOULD return the line "Query matched more than one name server:" followed by the matching ROIDs with corresponding name server name between parentheses, one per line. For example, a query for name servers with IP "203.0.113.7" that has three matching objects will return:

       Query matched more than one name server:
       roid1abc-examplerep (ns1.foo.example)
       roid5jkl-examplerep (ns2.example.com)
       roid9mno-examplerep (ns1.example.net)
       >>> Last update of WHOIS database: 2009-05-29T20:15:00Z <<<

   30. A Registry that implements clarification 29 MUST support queries for name server objects using the ROID of a name server object, e.g., queries of the form: whois roid <roid>, where <roid> is the ROID of a nameserver.

   31. A Registry MAY offer partial match capabilities for registrar object queries. When receiving a query for a registrar object that matches more than one object, the Registry MUST return several records. Every registrar object MUST be separated by a blank line, followed by the "Registrar Name: " key that indicates the start of a new record. For example, a query for registrar "Example" that has two matching objects will return (if providing searchability capabilities):

       Registrar: Example Registrar, Inc.
       …
       Registrar URL: http://www.example-registrar.example
       Admin Contact: Joe Registrar
       Phone Number: +1. 5553101213
       Fax Number: +1. 5553101213
       Email: joeregistrar@example-registrar.example
       Admin Contact: Jane Registrar
       Phone Number: +1. 5553101214
       Fax Number: +1. 5553101213
       Email: janeregistrar@example-registrar.example
       Technical Contact: John Geek
       …

       Registrar: Example Registrar Two, Inc.
       …
       Registrar URL: http://www.example-registrar-two.example
       Admin Contact: Joe Registrar Two
       Phone Number: +1. 5553101213
       Fax Number: +1. 5553101213
       Email: joeregistrar@example-registrar-two.example
       Admin Contact: Jane Registrar
       Phone Number: +1. 5553101214
       Fax Number: +1. 5553101213
       Email: janeregistrar@example-registrar-two.example
       Technical Contact: John Geek
       …
       >>> Last update of WHOIS database: 2009-05-29T20:15:00Z <<<

   32. When receiving a query for a name server object that matches more than one object, the Registry MUST return several records if clarification 29 of this document has not been implemented. Every name server object MUST be separated by a blank line, followed by the "Server Name: " key that indicates the start of a new record. For example, a query for name server "203.0.113.7" that has two matching objects will return:

       Server Name: ns1.foo.example
       IP Address: 203.0.113.7
       Registrar: Example Registrar, Inc.
       Registrar WHOIS Server: whois.example-registrar.example
       Registrar URL: http://www.example-registrar.example

       Server Name: ns3.bar.example
       IP Address: 203.0.113.7
       Registrar: Example Registrar 2, Inc.
       Registrar WHOIS Server: whois.example-registrar2.example
       Registrar URL: http://www.example-registrar2.example
       >>> Last update of WHOIS database: 2009-05-29T20:15:00Z <<<

   33. Registry Operator MAY show the Phone Ext and/or Fax Ext elements for the contacts in the Registrar Data. If shown, each field MUST be shown either as additional data field as defined in clarification 1 of this document, or immediately following the respective contact phone or fax field.

   34. Registries SHOULD support queries for registrar objects using the IANA ID of the registrar, e.g., queries of the form: whois registrar-id <IANA ID>.

   35. In responses to name server object queries, the "IP Address" field can have multiple values and therefore, MAY appear multiple times.

   36. In the case of queries for name servers for which there is at least one active domain name that requires glue data in the DNS (please see RFC 1034) and Registries have the data, Registries MUST include in the response data from their SRS (e.g., Server Name, IP Addresses) the related IP address(es) of, at least, the domain name that requires glue data in the DNS. Registries MAY provide a response with data from the SRS in other cases.

       For example, if the domain name "foo.example" is active in the DNS and has the name server "ns.foo.example", then the IP address(es) and related data from SRS for the name server will be shown in the Whois output of a query for the name server "ns.foo.example".

   37. In responses to registrar object queries, the following fields can have multiple values and, therefore, MAY appear multiple times:

       • Admin Contact

       • Technical Contact

       • Email

       • Fax Number

       • Phone Number

       • Phone Ext

       • Fax Ext

       • Street

       When a registrar object query returns multiple admin or technical contacts, the related fields (Email, Fax Number, and Phone Number) MUST follow the contact name (i.e., Admin Contact, or Technical Contact) field. For example, a query for a registrar that has two admin contacts will return:

       Registrar: Example Registrar, Inc.
       …
       Registrar URL: http://www.example-registrar.example
       Admin Contact: Joe Registrar
       Phone Number: +1. 5553101213
       Fax Number: +1. 5553101213
       Email: joeregistrar@example-registrar.example
       Admin Contact: Jane Registrar
       Phone Number: +1. 5553101214
       Fax Number: +1. 5553101213
       Email: janeregistrar@example-registrar.example
       Technical Contact: John Geek
       …
       >>> Last update of WHOIS database: 2009-05-29T20:15:00Z <<<

   38. When receiving an "unqualified query" (e.g., a query string that does not include the "nameserver" or "registrar" parameters) that matches a domain name and a name server object, the registry SHOULD return the information about the domain name object.

   39. In responses to registrar object queries, for the following fields are considered optional and should be treated as described in clarification 1:

       • State/Province

       • Postal Code

       • Fax Number

   40. Responses to registrar object queries SHOULD include at least one admin contact and one technical contact.

   41. Unless otherwise required by policy or contract, the value section (i.e., right-hand side of the colon) of the fields MUST comply with the format specified in the EPP RFCs: 5730-5734, and 3915. The following fields are not specified in the EPP RFCs: 5730-5734, or 3915, and MUST follow the below format specifications:

       1. "Registrar WHOIS Server" value is defined as a hostname (see RFC952 and RFC1123) and MUST show the server name of the (port-43) WHOIS server of the sponsoring/referred Registrar, if said registrar offers (port-43) WHOIS service for the queried object, otherwise it would be considered optional as described in clarification 1;

       2. "Registrar URL" value is defined as a URL (see RFC3986). The value MUST show a website of the sponsoring registrar. The URL MUST either be: the URL of the web-Whois of the queried object, the web-Whois service of the registrar, or the sponsoring registrar main web page;

       3. "Registrar IANA ID" value is defined as a positive decimal integer;

       4. "Registrar" value is defined as token (see Extensible Markup Language 1.1);

       5. Contact object elements for the Registrar object are defined as EPP contact objects elements.

   42. In responses to domain name, registrar, or name server object queries, the following fields are considered optional and should be treated as described in clarification 1:

       • Registrar WHOIS Server (if the sponsoring/referred registrar does not offer (port-43) WHOIS service for the queried object)

3. The following clarifications only apply to Registrars.

   43. A Registrar is only REQUIRED to show Whois information for domain names for which the Registrar is the Sponsoring Registrar.

   44. The field "Registry Domain ID:" refers to the Repository Object Identifier (ROID) for the Domain Name object as specified in RFC 5730 (called Domain ID in Specification 4 of the Registry Agreement). For example, a Registrar could obtain the ROID from the Registry via EPP and cache the information locally after creating or gaining a domain name via a transfer.

   45. The fields "Registry Admin/Tech/Billing/Registrant ID:" refers to the Repository Object Identifier (ROID) for the Contact object as specified in RFC 5733. For example, a Registrar could obtain the ROID from the Registry via EPP and cache the information locally. The RAA 2013 defines that this information MUST be shown if available from the Registry. If this information is not available from the Registry (e.g., a "thin" registry), the string "Not Available From Registry" SHOULD be shown instead.

   46. The "Updated Date:" field MUST reflect the date and time of the latest successful update known to the Registrar. Registrars are not required to constantly refresh this "Updated Date:" from the Registry.

   47. The service level requirement "RDDS update time" described in Section 2.2 of the Registration Data Directory Service (WHOIS) Specification refers only to changes initiated by the registrar.

   48. EPP statuses in the Whois output MUST reflect the latest known set of EPP statuses in the Registry. Registrars are not required to constantly refresh the EPP statuses from the Registry.

   49. Unless otherwise required by policy or contract, the value section (i.e., right-hand side of the colon) of the fields MUST comply with the format specified in the EPP RFCs: 5730-5734, and 3915. The following fields are not specified in the EPP RFCs: 5730-5734, or 3915, and MUST follow the below format specifications:

       1. "Registrar Abuse Contact Email" (as defined in the EPP RFCs for email fields)

       2. "Registrar Abuse Contact Phone" (as defined in the EPP RFCs for phone fields)

       3. "Reseller" is defined as token (see Extensible Markup Language 1.1)

       4. "Registrar WHOIS Server" value is defined as a hostname (see RFC952 and RFC1123) and is the server name of the (port-43) WHOIS server of the sponsoring Registrar

       5. "Registrar URL" value is defined as a URL (see RFC3986) and MUST show the website of the sponsoring registrar, more specifically, the URL of the web-Whois of the queried object, or at least the URL of the web-Whois service of the registrar

       6. "Registrar IANA ID" value is defined as a positive decimal integer.

       7. "Registrar" value is defined as token (see Extensible Markup Language 1.1).

   50. The value section of the "Reseller" field SHOULD be shown, but MAY be left blank or the whole field MAY not be shown at all. If shown, the value of the field MUST be the name of organization, in case the Reseller for the name is a legal entity, or a natural person name otherwise.

   51. The below fields MAY appear immediately before the last field ("URL of the ICANN Whois Inaccuracy Complaint Form") instead of following the "Registrar IANA ID" field:

       • Registrar Abuse Contact Email

       • Registrar Abuse Contact Phone