.. _SRS Protocol:

SRS Protocol
============

The SRS protocol can be used by registrars for interacting with the SRS. Individual parts of the protocol are covered in depth below.

The specification of SRS and a description of the communication protocol used by the system is available in IETF I-D format but has not been accepted as an RFC:

* :download:`System for Managing a Shared Domain Registry (Plain text) - draft-nzrs-srs-03 <draft-nzrs-srs-03.txt>`
* :download:`System for Managing a Shared Domain Registry (PDF) - draft-nzrs-srs-03 <draft-nzrs-srs-03.pdf>`

The protocol schema is available here:

* RELAX NG format :download:`protocol.rnc <protocol.rnc>`
* DTD format :download:`protocol.dtd <protocol.dtd>`

Contents:

.. only:: internal

  .. toctree::
    :glob:
    :maxdepth: 2

    registry

.. toctree::
   :glob:
   :maxdepth: 2

   transactions
   fields
   sxc

Communication
-------------

The SRS protocol works in a connection-oriented fashion with no session state. The registrar sends a SRS XML request document to the SRS containing commands to be executed by the SRS and the result of processing these commands is returned as the response. Each registrar request document receives a response document containing the result of processing all of the requests in a single request document.

All communication with the SRS is performed using XML documents encoded in UTF−8 and sent using HTTP or HTTPS. The request body can contain multiple independent requests to be performed on the SRS. The response will include a response to each request in the XML document, or a single error response. The SRS will process the requests in the order that they are received in the request body.

All SRS XML transactions attempting to modify the data in the SRS or to retrieve data that is not deemed public, needs to be transmitted via HTTPS. If these transactions are sent via HTTP they will get rejected.

Registrars should ensure that:

* Requests in an XML document are ordered logically to prevent errors due to sequencing (for example, attempting to update a domain record before creating it)
* The number of requests per XML document is limited to ensure acceptable processing time and response size

Both request and response messages must be accompanied by a digital signature of the complete XML request body (See SRS Security for further details on signing requests).

The VerMajor and VerMinor attributes are required in the first element of each request and response to allow clients and servers to modify their behaviour dependent on the version of the protocol that they support.

The SRS server will reject any request made with a major version number that is greater than the SRS server's own supported version.


Registrar URLs
~~~~~~~~~~~~~~

======================      =========
Environment                 URL
======================      =========
Production                  https://srs.prod.srs.net.nz/srs/registrar
Test (OTE)                  https://srs.test.srs.net.nz/srs/registrar
RPS                         https://srs.rps.srs.net.nz/srs/registrar
======================      =========

HTTP Request Format
~~~~~~~~~~~~~~~~~~~

Request
^^^^^^^

Requests must include three parameters in the HTTP POST request:

.. csv-table::
    :header: "Parameter", "Description"
    :delim: |

    n | The registry-assigned registrar identifier.
    r | The XML request, encoded in UTF-8.
    s | An OpenPGP-compatible signature of the XML request document, signed with the registrar's private key. Presented in ASCII armoured format and encoded in UTF-8.

Example request prior to encoding:

::

    n=945&r=
    <NZSRSRequest VerMajor="6" VerMinor="7" RegistrarId="945">
       <Whois DomainName="example.org" />
    </NZSRSRequest>&s=-----BEGIN PGP SIGNATURE-----...

Response
^^^^^^^^

Responses include two parameters:

.. csv-table::
    :header: "Parameter", "Description"
    :delim: |

    r | The XML response, encoded in UTF-8.
    s | An OpenPGP-compatible signature of the XML response document, signed with the registry's private key. Presented in ASCII armoured format and encoded in UTF-8.

Example response prior to encoding:

::

    r=<?xml version="1.0" encoding="utf-8"?>
    <NZSRSResponse VerMajor="6" VerMinor="7" RegistrarId="50041">
       <Response Action="Whois" FeId="4" FeSeq="137"
         OrigRegistrarId="50041" RecipientRegistrarId="50041" Rows="1">
           <FeTimeStamp Year="2007" Month="10" Day="19" Hour="14"
              Minute="7" Second="51" TimeZoneOffset="+13:00" />
           <Domain DomainName="example.org">...</Domain>
       </Response>
    </NZSRSResponse>&s=-----BEGIN PGP SIGNATURE-----...

For more information please see: :download:`System for Managing a Shared Domain Registry (Plain text) - draft-nzrs-srs-03 <draft-nzrs-srs-03.txt>`
 
.. _registrypgpkeys:

Registry PGP Keys
-----------------

To verify the response from the SRS you will need the registry's PGP key. There are two keys in use, one for the Production and one for the Test SRS environments. You can download both PGP keys from the links below:

==============    ========================================    ===
Environment        Valid From                                       Key
==============    ========================================    ===
Production        20th of June 2019                           :download:`srs-production-2019.key <registry@prod.srs.net.nz-key.asc.txt>`
Testing (OTE)     20th of May 2019                            :download:`srs-test-2019.key <registry@test.srs.net.nz-key.asc.txt>`
RPS               31st of July 2019                           :download:`srs-rps-2019.key <registry@rps.srs.net.nz-key.asc.txt>`
==============    ========================================    ===


Security
--------

The request and response signature mechanism provides a means of ensuring that messages have not been tampered with in transit. In addition to this, all requests for private data (data that cannot be retrieved using the public WHOIS system) must use an encrypted HTTP connection (HTTPS) for data security. If a request for private data is received via an unencrypted HTTP connection, the SRS server will return an error response.

Only the Whois request may be issued over an unencrypted HTTP connection.

The SRS API currently supports connections via:

* TLSv1.0
* TLSv1.1
* TLSv1.2

SRS uses SSL certificates signed by the :ref:`NZRS Certificate Authority <nzrsca>` chain. To validate connections to SRS you will need to install these in your root CA store.

Authorization
~~~~~~~~~~~~~

The SRS uses a permissions model to restrict the SRS requests that registrars are allowed to access. Action and role types are defined in the protocol definition for this purpose. A request may require more than one permission to be deemed permissible, depending on the type of the request and possibly on certain parameters of the request. If the originating registrar does not possess all of the permissions required to complete a request, the SRS server will reject the transaction.

Transactions sent to the SRS server must identify the registrar making the request. Registrars will not be permitted to perform functions using an effective registrar other than their own. Any such requests received by the SRS will be rejected.

The registry performs SRS functions using an effective registrar value.

Registrants and the public have no direct access to the SRS.

PGP Signatures
~~~~~~~~~~~~~~

Both request and response messages MUST be accompanied by a digital signature of the complete XML request body. The digital signature authentication method follows the specification in section 2.2 of OpenPGP Message Format [RFC4880] and MUST be encoded in ASCII Armour (see section 6.2 of [RFC4880]) for inclusion in the HTTP request. The SRS protocol is a signature−only application of OpenPGP.

You can find a wide range of PGP compatible software at the following sites:

* http://www.gnupg.org
* http://www.pgpi.com
* http://cryptography.org

Please note that it is your responsibility to licence the version you acquire.

More information is available in the following FAQ item: :ref:`GeneratePGPKey`.

XML Format
----------

The SRS protocol uses messages in an XML format for system requests and responses. All data values must be entity-escaped, and the file itself must be UTF-8 encoded.

The protocol is available in DTD, Relax NG and XSD.

Request Format
~~~~~~~~~~~~~~

The SRS XML request document must:

* Begin with an opening <NZSRSRequest> tag and end with a closing </NZSRSRequest> tag.
* Include a VerMajor attribute.
* Include a VerMinor attribute.
* Include a RegistrarId attribute.
* Include one or more request elements (transactions).

Transactions within a request are processed in the same order as they are received. Each transaction will be applied to the database separately and the failure of the one transaction will not directly affect the processing of any of the other transactions.

All transactions will be checked to ensure that:

* All data is supplied in a valid format.
* All update transactions contain a unique Action ID.
* All mandatory fields are supplied.

XML Request Definition
~~~~~~~~~~~~~~~~~~~~~~

====================    ========    ====
Attribute               Required    Note
====================    ========    ====
<NZSRSRequest>          Yes         Encapsulates the file and references the current protocol standard.
VerMajor                Yes         Major version number of the protocol. This number only changes when major changes are made to the system that are not backward compatible with previous versions; for example, client/ server interface changes (changes to the protocol schema).
VerMinor                Yes         Minor version number of the protocol. This number changes for minor updates to the protocol that are backward compatible with previous versions with the same major version number.
RegistrarId             Yes         Registrar's unique identifier provided by InternetNZ
<*requestElements*>     Yes         One or more request elements where <*requestElements*> can be <DomainCreate> <DomainUpdate> <HandleCreate> <HandleUpdate> <HandleDetailsQry> <Whois> <DomainDetailsQry> <ActionDetailsQry> <UDAIValidQry> <RegistrarUpdate> <RegistrarDetailsQry> <RegistrarAccountQry> <GetMessages> <AckMessage>
====================    ========    ====

Example XML Request:

.. code-block:: xml

    <NZSRSRequest RegistrarId="999" VerMajor="5" VerMinor="10">
        <Whois DomainName="internetnz.net.nz" FullResult="1" SourceIP="1.2.3.4"/>
    </NZSRSRequest>

Entity Escaping
~~~~~~~~~~~~~~~

Your SRS file must be UTF-8 encoded. Any data values must use entity escape codes for the characters listed below:

Ampersand::

    &   &amp;

Single Quote::

    '   &apos;

Double Quote::

    "   &quot;

Greater Than::

    >   &gt;

Less Than::

    <   &lt;


Response Format
~~~~~~~~~~~~~~~

The SRS XML response document contains the same attributes as listed for the SRS XML Request above and contains either a transaction response for each transaction in the original request or a single error element if the request as a whole has failed.

The transaction response includes the following:

==========================  ==============================
Attribute                   Note
==========================  ==============================
VerMajor                    The major version number of the SRS system                                                                                                                                                        
VerMinor                    The minor version number of the SRS system                                                                                                                                                        
RegistrarId                 Registrar Identifier                                                                                                                                                                              
Action                      name of the transaction that caused the response. Either actual transaction name, Domain Transfer (to notify 'loosing' registrar about transfer), Unknown Transaction (for various Error responses
ActionId                    The identifier of the transaction that caused the response                                                                                                                                        
MoreRowsAvailable           Only returned if 'triggered'                                                                                                                                                                      
RecipientRegistrarId        The registrar ID to which the response is posted                                                                                                                                                  
FeId                        Identifier of the front end server that services the request                                                                                                                                      
FeSeq                       Identifier of the request instance on the front end server that serviced it                                                                                                                       
FeTimestamp                 Time/date that the request instance was received on the front end server that serviced it                                                                                                         
OrigRegistrarId             Identifier of the registrar that submitted the request                                                                                                                                            
TransId                     Identifier for the transaction if and as submitted by the initiator, either an ActionId or QryId                                                                                                  
==========================  ==============================

.. code-block:: xml

    <NZSRSResponse RegistrarId="90" VerMajor="5" VerMinor="7">
      <Response Action="DomainCreate" FeId="8" FeSeq="20888439" OrigRegistrarId="90" RecipientRegistrarId="90" TransId="Unique Value 1234">
        <FeTimeStamp Day="11" Hour="10" Minute="43" Month="3" Second="40" TimeZoneOffset="+13:00" Year="2011"/>
        <Domain Delegate="1" DomainName="internetnztest.co.nz" RegistrarId="90" Status="Active" Term="1" UDAI="SvmTxPXw">
          <NameServers>
            <Server FQDN="ns1.internetnztest.co.nz" IP4Addr="8.8.8.8"/>
            <Server FQDN="ns2.internetnztest.co.nz" IP4Addr="8.8.4.4"/>
          </NameServers>
          <RegistrantContact Email="test@internetnztest.co.nz" Name="John Smith">
            <PostalAddress Address1="Level 9 Grand Arcade" Address2="Willis Street" City="Wellington" CountryCode="NZ" PostalCode="6001"/>
            <Phone AreaCode="4" CountryCode="64" LocalNumber="1234567"/>
            <Fax AreaCode="4" CountryCode="64" LocalNumber="1234567"/>
          </RegistrantContact>
          <AdminContact Email="test@internetnztest.co.nz" Name="Admin Manager, InternetNZ Inc">
            <PostalAddress Address1="Level 9 Grand Arcade" Address2="Willis Street" City="Wellington" CountryCode="NZ" PostalCode="6001"/>
            <Phone AreaCode="4" CountryCode="64" LocalNumber="1234567"/>
            <Fax AreaCode="4" CountryCode="64" LocalNumber="1234567"/>
          </AdminContact>
          <TechnicalContact Email="test@internetnztest.co.nz" Name="Technical Manager, InternetNZ Inc">
            <PostalAddress Address1="Level 9 Grand Arcade" Address2="Willis Street" City="Wellington" CountryCode="NZ" PostalCode="6001"/>
            <Phone AreaCode="4" CountryCode="64" LocalNumber="1234567"/>
            <Fax AreaCode="4" CountryCode="64" LocalNumber="1234567"/>
          </TechnicalContact>
          <BilledUntil Day="11" Hour="10" Minute="43" Month="3" Second="40" TimeZoneOffset="+13:00" Year="2012"/>
          <RegisteredDate Day="11" Hour="10" Minute="43" Month="3" Second="40" TimeZoneOffset="+13:00" Year="2011"/>
          <AuditDetails ActionId="Unique Value 1234" RegistrarId="1">
            <AuditTime>
              <From Day="11" Hour="10" Minute="43" Month="3" Second="40" TimeZoneOffset="+13:00" Year="2011"/>
            </AuditTime>
            <AuditText><![CDATA[create new domain]]></AuditText>
          </AuditDetails>
        </Domain>
      </Response>
    </NZSRSResponse>


.. _SRSresourceManager:

SRS Resource Manager
--------------------

The Resource Manager component of the SRS is used to protect the SRS and to share the SRS resources equally between registrars. The Resource Manager monitors registrar transactions and if a registrar crosses certain thresholds (in terms of the number of requests they send each second, for example) then the SRS will begin to reject their requests until such time as they reduce the workload they are sending to the SRS.

A simple rate-limit has been imposed on each registrar that they may not send more than 15 requests per second. When the SRS detects that a registrar is sending more than 15 requests per second (as a "rolling average") it will begin to reject their requests. It will then continue to reject all of their requests until the rolling average drops below the threshold.

SRS Resource Manager Headers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To assist registrars with managing their transaction request rates the SRS provides an additional HTTP response header as part of SRS communications. There is no requirement for registrars to use this header, however it does provide information to assist them in tuning their applications to get the best possible throughput from SRS.

The following is an example of the HTTP response header:

::

  HTTP/1.1 200 OK
  Date: Mon, 12 Feb 2007 22:50:31 GMT
  Server: Apache
  X-resource-consent: RegistrarRequestLimit,2,15
  Connection: close
  Content-Type: application/x-www-form-urlencoded

In this example you can see the RegistrarRequestLimit returned and has two values. The first value is the number of requests per second received at the front end and the second value is the current limit. So in this example we have a rate of 2 requests per second for this registrar and the limit is 15 requests per second.

An example of the XML error response returned if the rate is exceeded:

.. code-block:: xml

  <NZSRSResponse VerMajor="1" VerMinor="38">
    <Error ErrorId="CONSENT_ERROR" Hint="INVALID_REQUEST_ERROR" Severity="err">
     <Description><![CDATA[Request denied due to resource limits being exceeded]]></Description>
     <ErrorDetails><![CDATA[RegistrarRequestLimit,17,15]]></ErrorDetails>
   </Error>
  </NZSRSResponse>


In this example you can see the RegistrarRequestLimit returned has a rate of 17 requests per second for this registrar and the limit is 15 requests per second.

.. note:: The rate limit value is rounded down to the nearest whole number.