Abstract

This document specifies the query and response characteristics of the NZ SRS whois service, version 1.0.

Table of Contents

1.  Whois Protocol
2.  Query Format
3.  Response Format
4.  Specific Field Details
4.1  Initial fields
4.1.1  version:
4.1.2  query_datetime:
4.1.3  domain_name:
4.1.4  query_status:
4.1.5  domain_dateregistered:
4.1.6  domain_datebilleduntil:
4.1.7  domain_datelastmodified:
4.1.8  domain_datecancelled:
4.1.9  domain_datelocked:
4.1.10  domain_delegaterequested:
4.2  Contact Fields
4.2.1  *_name:
4.2.2  *_address1:
4.2.3  *_address2:
4.2.4  *_city:
4.2.5  *_province:
4.2.6  *_postalcode:
4.2.7  *_country:
4.2.8  *_phone:
4.2.9  *_fax:
4.2.10  *_email:
4.3  Nameserver fields
5.  Examples
5.1  Query for a domain name which exists
5.2  Query for a domain that is not registered
5.3  Query for a malformed domain name (test+domain.co.nz)
5.4  Query for a domain name under the wrong apex (example.com)
6.  Acknowledgements
§  References
§  Author's Address

1. Whois Protocol

The SRS Whois server is based on the Domainz SRS Whois Server, and the protocol described in RFC 954[1].

The server listens on TCP port 43 for connections. A client makes a TCP/IP connection to the whois server, and transmits the whois query as a single line, encoded in ASCII (7-bit values in 8-bit octects), terminated by a CR LF pair. The format of the query string is described in Query Format.

The whois server then attempts to locate the information requested, and sends a response as a series of UTF-8 encoded lines, each terminated by a CR LF pair. After sending the response the whois server closes the TCP/IP connection. The format of the response is described below.

2. Query Format

The query consists of a single domain name that is under an apex (ie, top point of the hierachy, such as a TLD) managed by the register associated with whois server. (For the New Zealand SRS system this means a domain name ending in "nz".)

No wildcards are permitted; the query string is used literally to match a domain name in the register.

The domain name in the query must be a fully qualified well formed domain name, consisting of letters, numbers, full stops (.), and hyphens (-), as described in RFC 1035[2]. A trailing full stop (.) indicating an absolute domain name (in BIND syntax) may be present or omitted; if it is present it will be silently discarded, as all domains are assumed to be fully qualified.

The query string must not begin with a hyphen (-) (domain names may not begin with a hyphen anyway, as described in RFC 1035[2]). Query strings beginning with a hyphen are reserved for future expansion, to allow passing "command line" flags to the whois server. Currently no flags are defined or permitted.

Query strings that do not match the input format will be rejected with a 4xx query_status: response and associated human readable error description, as described below.

3. Response Format

The response consists of a series of UTF-8 encoded lines, terminated by CR LF pairs. There are two types of lines in the response format:

1. Field: value lines containing a response field on a single line
2. Comment lines.

Comment lines are identified as being preceded by a percentage symbol (%). The comment lines are intended for human consumption and need not be decoded by a program interacting with the whois server. If appropriate they should be displayed to the user initiating the whois query. They will contain, amongst other things, notification of restrictions on the use of information obtained by the whois server.

The following is a list of all possible field: value fields:

version

query_datetime

domain_name

query_status

domain_dateregistered

domain_datebilleduntil

domain_datelastmodified

domain_datecancelled

domain_datelocked

domain_delegaterequested

registrar_name

registrar_address1

registrar_address2

registrar_city

registrar_province

registrar_postalcode

registrar_country

registrar_phone

registrar_fax

registrar_email

registrant_contact_name

registrant_contact_address1

registrant_contact_address2

registrant_contact_city

registrant_contact_province

registrant_contact_postalcode

registrant_contact_country

registrant_contact_phone

registrant_contact_fax

registrant_contact_email

admin_contact_name

admin_contact_address1

admin_contact_address2

admin_contact_city

admin_contact_province

admin_contact_postalcode

admin_contact_country

admin_contact_phone

admin_contact_fax

admin_contact_email

technical_contact_name

technical_contact_address1

technical_contact_address2

technical_contact_city

technical_contact_province

technical_contact_postalcode

technical_contact_country

technical_contact_phone

technical_contact_fax

technical_contact_email

Each of those fields may appear one or may be absent, and if it appears will appear in the order listed above. The fields version:, query_datetime:, domain_name:, and query_status: will always be present.

In addition there is a set of nameserver fields:

ns_name_01

ns_ip4_01

ns_name_02

ns_ip4_02

ns_name_03

ns_ip4_03

...

ns_name_98

ns_name_98

ns_ip4_99

ns_ip4_99

These fields (which hold nameserver details for a domain delegation) will appear for each nameserver recorded in the register for delegation of that domain. For instance if there are three nameservers listed in the register for a domain then these fields will be possible fields:

ns_name_01

ns_ip4_01

ns_name_02

ns_ip4_02

ns_name_03

ns_ip4_03

Any ns_name_NN/ns_ip4_NN fields will appear after the other fields listed above. The nameservers will appear in the order they were listed by the registrar on creating or updating the domain in the register.

(01 to 99 is considered more than sufficient range for the foreseeable future; only a maximum of 13 nameservers will fit in the current DNS responses, and then only with particular choices of nameserver names, hence a figure nearly an order of magnitude higher is expected to be more than sufficient.)

The fields version:, query_datetime:, domain_name:, and query_status: will always be present. All other fields are subject to empty-field removal. If there is no value in the register for the field, then the field will not be included in the output. This includes the ns_name_NN/ns_ip4_NN fields. If there is only a name recorded in the register for a particular nameserver, then the ns_name_NN field will be present, but the ns_ip4_NN field of the same number will not be present.

The SRS Detailed Requirements Specification[8] describes the fields which are expected to be present in the register, and hence are expected to be present in a successful whois query for a domain which is in the register. Due to data conversion from the previous register application some fields may not appear on some imported domains (as shown in Query for a domain name which exists). Robust client applications should handle this situation gracefully.

There is no provision for fields to be wrapped onto a second line; all data associated with a given field will be on the same line. The maximum likely length of a field varies from field to field, but no fields will be longer than 1024 characters (and all are expected to be considerably shorter in practice). (Most fields are held in the register in "text" data types, which expand as required, so it is not practical to place a firmer data length restriction on the field lengths which could appear.)

The fields may be separated by comments, eg, into groups to make them more human readable, but these comments have no effect on the meaning of the fields.

The formatting and possible values of specific fields are discussed further below.

4. Specific Field Details

4.1 Initial fields

4.1.1 version:

The version field contains the version number of the output format of the whois server, consisting of a major and a minor part, separated by a full stop (.). The major number will be incremented when the format has changed in a manner that is not compatible with a program parsing the older format (eg, the addition of new fields, or new formatting for existing fields). The minor number will be incremented for any other change.

When the SRS system first goes live the version field will be:

version: 1.0

(prior to the SRS system going live the major version number will be 0.)

4.1.2 query_datetime:

The date and time that the query was performed, in local time at the location of the whois server. The date and time will be formatted according to RFC 3339[6].

4.1.3 domain_name:

The domain name which was queried (from the query string).

4.1.4 query_status:

The availability status of the domain name which was queried, or a code indicating the error that occured. The field contains a three digit number followed by a space followed by a human readable string explaning the status number (that string may include spaces, and is considered to +run from the space after the three digit number to the end of line). In the case of successful queries, these human readable strings will correspond to the strings used by the SRS XML protocol to indicate domain status.

There are three groups of status codes:

1. 2xx: successful query
2. 4xx: server error (temporary errors)
3. 5xx: client error (permanent errors)

These groupings are chosen to be overall consistent with RFC 2832[5], as it is felt potential registrars (and users of the whois interface) are most likely to be familiar with other registry interfaces and their error codes.

The allocated successful query status codes are:

• 200 Active
• 210 PendingRelease
• 220 Available

Indicating that the domain is active in the register, is no longer active but is in the period prior to being released for general registrations, or that it is not currently registered and hence available for registration.

The allocated server error status codes are:

• 400 Error sending request to backend
• 410 Error receiving response from backend
• 420 Invalid response received from backend
• 430 Error translating response from backend
• 480 Too many requests from this IP recently
• 490 Timeout before response received from backend
• 495 System overloaded; cannot start new request

All errors in this category are temporary in nature, and the requests should be retried at a later stage. Timeouts may be caused by load on the systems, and so it is appropriate to retry, once, after a short delay. The other statuses may require longer to resolve, and it would be appropriate to present the error to the user, and allow them to retry at a later stage.

The allocated client error status codes are:

• 500 Invalid characters in query string
• 510 Domain is not managed by this register

All errors in this category are permanent. The request should not be retried as is. Instead the request should be reviewed to ensure that it is well formed, and appropriate for the whois server.

4.1.5 domain_dateregistered:

For a domain which is listed in this register, the date and time on which it was entered into the register. The date and time will be formatted according to RFC 3339[6].

4.1.6 domain_datebilleduntil:

For a domain which is listed in this register, the date and time on which the current payment for the domain registration ends. The date and time will be formatted according to RFC 3339[6].

4.1.7 domain_datelastmodified:

For a domain which is listed in this register, the date and time on which the registration was last modified. The date and time will be formatted according to RFC 3339[6]. This field may be omitted if no modifications have been made since the domain was first registered.

4.1.8 domain_datecancelled:

For a domain which was listed in this register but has been cancelled, the date and time on which it was cancelled. The date and time will be formatted according to RFC 3339[6].

4.1.9 domain_datelocked:

For a domain which is listed in the register but has been locked (eg by the registry while a dispute is resolved), the date and time on which the domain was locked. The date and time will be formatted according to RFC 3339[6].

4.1.10 domain_delegaterequested:

For a domain which is listed in the register, "yes" or "no", depending on whether the domain is marked for export into the DNS zone as a delegation. If the domain_delegaterequested: is "no", then the domain will not appear in the DNS even if all other information (eg, suitable nameservers) is present to otherwise allow it to do so. If set to "yes", then the domain will appear in the DNS providing the other criteria are satisified.

4.2 Contact Fields

There are four sets of contact fields (registrar_*, registrant_contact_*, admin_contact_*, technical_contact_*) each of which contains the same field information (name, address1, address2, city, province, postalcode, country, phone, fax, email). These fields will report the contact information held in the register for the registrar, registrant, admin contact and technical contact as appropriate.

As with all other fields, fields for which there is no data in the register will be omitted.

The format of individual fields is as follows.

4.2.1 *_name:

Free format name of the registrar, registrant, or admin/technical contact person, as held in the register.

4.2.2 *_address1:

Free format first line of the postal or physical address of the registrar, registrant, or admin/technical contact, as held in the register.

4.2.3 *_address2:

Free format second line of the postal or physical address of the registrar, registrant, or admin/technical contact, as held in the register. This field will be omitted if the postal or physical address is listed entirely in the address1 field in the register.

4.2.4 *_city:

Free format name of city or other locality for the postal or physical address of the registrar, registrant, or admin/technical contact, as held in the register.

4.2.5 *_province:

Free format name of the province or region or state for the postal or physical address of the registrar, registrant, or admin/technical contact, as held in the register. This field will be omitted if the postal or physical address held in the register does not list a province/region/state.

4.2.6 *_postalcode:

Free format postal code for the postal or physical address of the registrar, registrant, or admin/technical contact, as held in the register. This field will be omitted if the postal or physical address held in the register does not include a postal code.

4.2.7 *_country:

Two letter country code of the postal or physical address of the registrar, registrant, or admin/technical contact, followed by the accepted expansion of that country code in parenthesis, as held in the register. For instance:

registrar_country: NZ (New Zealand)

The applicable country codes are taken from two letter country codes in ISO 3166[7].

4.2.8 *_phone:

Contact phone number for the registrar, registrant, or admin/technical contact, as held in the register. The phone number is formatted with a leading plus sign (+), followed by the country code, followed by a space, followed (if held in the register) by an area code, followed by a space, followed by a free format E.164 style phone number.

For example, the following are all (individually) valid examples:

registrar_phone: +64 4 555 5555

registrar_phone: +64 4 555-5555

registrar_phone: +65 555-5555

In the third example there are two spaces (one either side of the non-existant area code) in the output.

4.2.9 *_fax:

Contact fax number for the registrar, registrant, or admin/technical contact, as held in the register. The number is formatted as for the *_phone fields (described above).

4.2.10 *_email:

Contact email address for the registrar, registrant,or admin/technical contact, as held in the register. The email address is formatted as a RFC 2821[4] email address, omitting the opening angle bracket (<) and closing angle bracket (>).

For example:

registrar_email: contact@registrar.example.com

4.3 Nameserver fields

Each delegated domain has two or more nameservers associated with it; however domains may exist in the register with fewer than two nameservers, in which case they will not be present in the DNS (domains may also not be present in the DNS if the domain_delegaterequested: field is "no").

The nameservers are listed sequentially in the order that they are held in the register (and hence the order they were received from the registrar), as _01, _02, and so on. There will not be any gaps in the sequence.

For each nameserver, the ns_name_NN field will list the domain name of the nameserver held in the register, and the ns_ip4_NN field will list the IP (version 4) address of the name server held in the register (if any). If no IP (version 4) address is held in the register for a particular nameserver for that domain, then the ns_ip4_NN field will be omitted.

ns_ip4_NN fields (with IP (version 4) addresses) may appear for out-of-zone delegations if these details are held in the register (ie, were sent by the registrar when creating or updating the registration), and may be absent even for in-zone delegations if the details have not been supplied by the registrar. The whois server reflects what is actually held in the register, even if that is not complete, or contains details that are not required for the DNS delegation. If the details in the register are not complete enough for a DNS delegation, then the domain will not be delegated in the DNS.

The IP (version 4) addresses in the ns_ip_NN fields will be formatted as a dotted quad (eg, NN.NN.NN.NN), without zero padding on any segment. Any well-formed IP (version 4) address may appear: there is no filtering of martians (eg, RFC 1918[3] addresses) performed in the SRS or the whois server -- instead registrars are expected to supply sensible data, but whatever is held in the register will be returned in the whois query.

The register does not currently store IP v6 addresses, and thus these addresses will not currently be returned by the whois server. It is expected that when IP v6 addresses are handled, there will be a ns_ip6_NN fields to contain them.

5. Examples

5.1 Query for a domain name which exists

5.2 Query for a domain that is not registered

5.3 Query for a malformed domain name (test+domain.co.nz)

5.4 Query for a domain name under the wrong apex (example.com)

6. Acknowledgements

The author would like to thank the following groups and individuals for reviewing this specification in draft format and providing very helpful comments.

• The Catalyst SRS Implementation Team
• The InternetNZ SRS Implementation Project Manager
• Joe Abley, Internet Software Consortium, jabley@isc.org
• Don Stokes, Knossos Networks Ltd

References

Author's Address