API Authentication

Authenticated DNS API calls

API Authentication

The Conexim DNS RESTful API makes use of SHA-256 HMAC (keyed-hash message authentication code) to generate a hashed signature of all parameters passed to the API servers. A shared secret exists between the Client and the Server, but the secret key is never sent with the request, thereby maintaining security. The method in its simplest form is described in RFC 2104.

All requests are sent over an SSL channel using secure ciphers ensuring secrecy of all parameters sent as part of the transaction.

If an SSL session is decrypted, it’s unlikely an API call can be replayed. This is because the current GMT UNIX Time is sent as a separate header (Conexim-Time).

The maximum clock skew between the API server and the client is 5 minutes, so it’s important to ensure that the client’s clock is accurate. A 401 response is returned with the message “Client clock skew is greater than maximum allowed.” if the date sent is not within the bounds of the allowed period.

There are two parts to Conexim DNS Authentication which are both sent as the Authorization HTTP header. A typical HTTP request Authorization header appears as follows:

Authorization: CONEXIM <key>:<sig>

In the above example, represents the ID associated with the key and represents the dynamically generated signature based on the request and its parameters.

The signature is formulated as follows:

sigString = KeyId + “n” +
    UnixTime + “n” +
    Verb + “n” +
    Action + “n” +
    URLencodedParameters

URLencodedParameters are simply any parameters that are sent for a PUT/POST request encoded in a URL-encoded format (e.g. paramA=valA&paramB=valB). Parameters must be pre-sorted to ensure that they’re reconstructed in the same order on the server for verification.

The signature digest is generated by applying a SHA-256 HMAC function against the signature and secret key. The result is converted to Base64 for adding to the header.


The Conexim DNS API Authorization