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


What causes SIG_INVALID messages in SRS?
----------------------------------------

.. code-block:: xml

    <Error ErrorId="SIG_INVALID" Hint="INVALID_REQUEST_ERROR" Severity="err">
        <Description><![CDATA[Signature is invalid]]></Description>
    </Error>


SIG_INVALID errors are generated when SRS is unable to validate the GPG signature you sent with your transaction.

This issue can be caused by a number of situations including:

A) The request included Unicode/UTF-8 characters and these were not processed correctly while handing it off to your GPG libraries for signing. This often results in an invalid signature for your request.
B) The GPG key you signed the request with is not valid in the environment you are trying to use (for example you have separate test/prod keys, and you attempted to use your prod key against the test environment)
C) You're attempting to use your key against the SRS Test system before the Friday refresh process has completed.
D) Your GPG key may have expired.


What causes LOCK_ERROR messages in SRS?
---------------------------------------

.. code-block:: xml

    <Error ErrorId="LOCK_ERROR" Hint="UNKNOWN_ERROR_HINT" Severity="err">
        <Description><![CDATA[An error occured when attempting to gain a lock on the domain.]]></Description>
    </Error>


This is normally the result of duplicate or multiple transactions for the same domain being sent with different action ids in very quick succession (i.e. within the same second).

The lock error is the result of the second transaction at our front-end failing to gain a lock on the records which are already being processed by the first transaction.


What causes INSECURE_UPDATE messages in SRS?
--------------------------------------------

.. code-block:: xml

    <Error ErrorId="INSECURE_UPDATE" Hint="INVALID_REQUEST_ERROR" Severity="err">
        <Description><![CDATA[Transaction requires a secure communication channel]]></Description>
    </Error>

This error is generated when you request non-public data via HTTP instead of HTTPS. Non-public data (data that cannot be retrieved using the public WHOIS system) must use an encrypted HTTP connection (HTTPS) for data security. Only the Whois request may be issued over an unencrypted HTTP connection.


How do you blank out or clear a field in SRS XML? (i.e. removing fax or address2)
---------------------------------------------------------------------------------

If you don't supply the field it does not update the field (as you would expect). For blanking out (clear a field) you need to send empty fields if using XML, or NULL if using the SRSClient.

For example to blank out the fax, the XML input should be:

.. code-block:: xml

    <Fax/>


.. _GeneratePGPKey:

How do I generate a PGP key for use with SRS?
---------------------------------------------

We recommended to use the GnuPG tool to generate a key (https://www.gnupg.org/).

.. note:: Make sure all the following commands are executed as the user that will be running the command line client.

To generate a key, type:

.. code-block:: shell

    gpg --gen-key

Follow the instructions the the gpg application gives you:

* Choose a 'RSA and RSA' type key
* Keysize '4096',
* '0' expiry (unless you have reason to choose non-default settings).

You can create a passphrase if you prefer one. If the key is generated with a passphrase the passphrase needs to be provided as environment variable (see below for more details)

Once the key is generated, you can export it by typing:

.. code-block:: shell

    gpg --export --armour <username>

Username is either the 'Real Name', 'Email Address' or both, that you entered for the key (type: 'gpg --list-keys' to view usernames for your keys). This is also the name you need to pass to the command line client, or the SRS::Client modules. (However, the most recently added secret key is your default secret key, and will be used if you don't specify a username).

The export command will print the armoured key to STOUT. If it's more convenient, you can redirect this to a file:

.. code-block:: shell

    gpg --export --armour <username> > pub.key

If you are using the srs xml client or you want to verify the signatures sent with responses by the registry, then you must import the registy's public key to your keyring. To do this, type:

.. code-block:: shell

    gpg --import reg.key



You will have to specify the path to the key file if you're executing 'gpg' in a directory other than the one containing the key file.

.. note:: The minimum PGP key size we allow on new RSA keys is 2048-bit, and InternetNZ suggests the use of 4096-bit RSA keys.

In order to working with SRS, the key needs to be confirmed by InternetNZ that has been added to SRS. For doing that the key should be exported and sent to registry@internetnz.net.nz


Where can I find the Registry PGP Keys?
---------------------------------------

The registry public keys can be found :ref:`Registry PGP Keys <registrypgpkeys>`.


Can I have Multiple Registrar PGP Keys?
---------------------------------------

We have supported multiple GPG keys in SRS since February 2008.