Authentication (SDA)

Overview

This page explains how to authenticate with the Solaris Digital Assets (SDA) API.

Solaris Digital Assets requires partners to generate a pair of private & public keys. You must register the public key with the platform and sign every request to the API using your private key.

The SDA API uses the HTTP Message Signatures IETF draft as the base for its authentication mechanism. It uses Ed25519 as the digital signature algorithm for HTTP signatures.

HTTP headers

Each HTTP request to the SDA API must include the following headers in addition to standard ones:

• Digest
• X-Nonce
• Signature

These headers are described in detail below.

Digest Header

The Digest header ensures the integrity of the HTTP request body. You must construct it using the SHA-256 algorithm in accordance with the guidelines of the Instance Digests in HTTP RFC.

Even for GET requests, assuming the request body is an empty string, you must still construct the Digest header.

See also: Additional Hash Algorithms for HTTP Instance Digests RFC

Example digest header:

Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=

X-Nonce Header

The X-Nonce header uniquely identifies the HTTP request and serves to protect against replay/playback attacks. The X-Nonce header value must be a string of up to 32 characters, which must be unique to each request generated using a single API key.

As an example, the X-Nonce header value may be generated as a 16-byte random integer in hexadecimal representation.

Example X-Nonce header:

X-Nonce: 514bdd41b15f6b1a0443f8c673adc9db

Signature Header

The Signature header provides authentication and integrity assurances without the need for shared secrets. It also does not require an additional round-trip in order to authenticate the client and allows the integrity of a message to be verified independently of the transport.

You must include the following parameters in the Signature header:

keyId

A unique ID that is assigned to your API key.

algorithm

The value must be hs2019.

created

The value must be a UTC timestamp from the time at which the HTTP request was constructed.

headers

Identifies how the canonical Signature String is constructed. Its value consists of a list of actual and pseudo-HTTP headers that will form the Signature String (according to the HTTP Signatures draft v11).

The headers parameter must include the following headers:

• (request-target)
• (created)
• digest
• x-nonce

Solaris recommends using the following value for this parameter:

(request-target) (created) digest x-nonce

Example Signature String:

(request-target): get /foo?bar=123\n
(created): 1557855475\n
digest: SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=\n
x-nonce: 7c44d38b63f5e398af62d603b1155f5c

In the above example, \n indicates the ASCII newline character. Note that it is not included on the last line.

signature

The digital signature of the HTTP request produced by your private key.

In order to create the signature parameter:

1. Construct the canonical Signature String according to the value of the headers parameter.
2. Using the private key that corresponds to the provided keyId, generate an Ed25519 signature of the Signature String constructed in the previous step.
3. Base64-encode the Ed25519 signature generated in the previous step.

Examples

POST /foo/bar
Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
X-Nonce: 514bdd41b15f6b1a0443f8c673adc9db
Signature:
keyId="foobar",algorithm="hs2019",created=1557855475,headers="(request-target)
(created) digest
x-nonce",signature="IKGyxGiUFm3luudWGkTzf0TYQD2Fnkb6ed6BTfuXuDq/U9q6gQk6KxBSPx33ME1O2RLlH5HKG2WZnO8PgRGiDA=="

{"hello": "world"}

GET /foo?bar=123
Digest: SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
X-Nonce: 7c44d38b63f5e398af62d603b1155f5c
Signature:
keyId="foobar",algorithm="hs2019",created=1557855475,headers="(request-target)
(created) digest
x-nonce",signature="d0Wzjlpt2Y++DJtxKnD1ipkkwF5eU43jwtybqsy3tFqa5P3kYYIJa4TTQyMUZ62i58jwN7gK6q2MVJBDGQ6tDg=="