🔏Request Signatures

Signing Your Requests

For every authenticated request made to the OffBlocks API, it is essential to sign the request using an HTTP signature following a pending IETF specification. Various open-source libraries are available to facilitate the generation of valid signatures. We are also actively working on publishing our own libraries to assist developers. For more information, please do not hesitate to contact us.

We actively develop a Go library to support HTTP message signatures as well as contribute to a Node.js library. Reach out to us if you're using other technologies on your backend and we'll be happy to assist with any issues integrating HTTP message signatures.

Supported Algorithms

While our API can theoretically accommodate multiple cryptographic algorithms for request signing, for the time being we only support ECDSA with curve P-384 DSS and SHA-384 as a signing algorithm.

Key Generation

In this guide we use openssl as a key generation tool. Feel free to use a tool of your choice, just make sure you generate keys using correct algorithm

Creating an ECDSA key pair for accessing our API is a straightforward process that involves just two commands:

1. Create a private key.

   openssl ecparam -name secp384r1 -genkey -noout -out ec-secp384r1-priv-key.pem

   Sample contents of the ec-secp384r1-priv-key.pem private key in PEM format:

   -----BEGIN EC PRIVATE KEY-----
   MIGkAgEBBDB8VIl4tFsxpD/7QN7LNWqzWhBrksKY1gdbp6aFzN5kBM5+PtDL/C1Y
   nF+ACeMbf7ygBwYFK4EEACKhZANiAAQ1WCxX6Z7z/bbj6PntmWChGqtzfX5mmLLU
   +621jNM55fI2k5sPvPUmd891mU/L7FAPxowiE8Cu48hHXTayYqDaO9CE0m8eWWXg
   T6s+j8ku4qgs66a9GDh3IG3tjelZzVY=
   -----END EC PRIVATE KEY-----

2. Create a public key by extracting it from the private key.

   openssl ec -in ec-secp384r1-priv-key.pem -pubout > ec-secp384r1-pub-key.pem

   Sample contents of the ec-secp384r1-pub-key.pem public key in PEM format:

   -----BEGIN PUBLIC KEY-----
   MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAENVgsV+me8/224+j57ZlgoRqrc31+Zpiy
   1PuttYzTOeXyNpObD7z1JnfPdZlPy+xQD8aMIhPAruPIR102smKg2jvQhNJvHlll
   4E+rPo/JLuKoLOumvRg4dyBt7Y3pWc1W
   -----END PUBLIC KEY-----

Registering your Public Key with the API

To enable our API to recognise your signatures, you need to upload the public key using the /auth/signing PUT endpoint. Please ensure that you set all the required environment variables (see Getting Started) in your Postman workspace before using this endpoint.

Make sure you encode your public key using base64 encoding before sending through our endpoint, otherwise the request will fail

Update signing key

Update public key used to sign API requests. When you upload your public key, a unique key ID is returned in response. This is different to your public key itself, and is required to sign your requests

PUThttps://api.offblocks.xyz/v1/auth/signing

Authorization

bearerAuth

Body

application/json

signingKeyId*string (uuid)

Unique ID of your key. This is different to your public key itself, and is required to sign your requests

signingKey*string (byte)

Base64 encoded public key used for signing requests. Requirements for cryptographic algorithms and more details can be found in our documentation

Response

204400401500

Successful operation

Request

JavaScriptCurl

const response = await fetch('https://api.offblocks.xyz/v1/auth/signing', {
    method: 'PUT',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "signingKeyId": "123e4567-e89b-12d3-a456-426614174000",
      "signingKey": "Ynl0ZXM="
    }),
});
const data = await response.json();

Additionally, previously uploaded keys can be updated using the same endpoint or permanently removed using a DELETE request to /auth/signing.

Delete signing key

Delete public key used to sign API requests

DELETEhttps://api.offblocks.xyz/v1/auth/signing

Authorization

bearerAuth

Body

application/json

signingKeyId*string (uuid)

Unique ID of your key. This is different to your public key itself, and is required to sign your requests

Response

204400401500

Successful operation

Request

JavaScriptCurl

const response = await fetch('https://api.offblocks.xyz/v1/auth/signing', {
    method: 'DELETE',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "signingKeyId": "123e4567-e89b-12d3-a456-426614174000"
    }),
});
const data = await response.json();

Request Content Digest

While it is important to verify signature of the request itself, it is equally important to verify integrity of request body if it is provided. For this purpose we are using content digest header containing hash of request body calculated using pre-defined algorithm. The header is required for all API requests that are expected to have body, either POST or PUT. In line with HTTP Digest Header specification, we are verifying Content-Digest header with request body hash calculated using sha-256 and/or sha-512 algorithms. It is also strongly advised to include Content-Digest header as part of signature verification in order to verify authenticity of the entire request.

While developers are also encouraged to use canonical JSON representation of request bodies to ensure stable hash calculation, we have made a decision to simply verify digest of byte array representation of the body as is. Please, make sure that request body is not transformed in any way after digest has been calculated or otherwise request verification may fail