# 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](https://www.ietf.org/archive/id/draft-ietf-httpbis-message-signatures-19.html). 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](https://pkg.go.dev/github.com/offblocks/httpsig) to support HTTP message signatures as well as contribute to a [Node.js library](https://www.npmjs.com/package/http-message-signatures). 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](https://httpwg.org/http-extensions/draft-ietf-httpbis-message-signatures.html#name-ecdsa-using-curve-p-384-dss) as a signing algorithm.

### Key Generation

{% hint style="info" %}
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
{% endhint %}

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

1. Create a private key.

   ```bash
   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.

   ```bash
   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](https://docs.offblocks.xyz/developer-guides/api-integration/getting-started "mention")) in your Postman workspace before using this endpoint.

{% hint style="warning" %}
Make sure you encode your public key using `base64` encoding before sending through our endpoint, otherwise the request will fail
{% endhint %}

{% openapi src="<https://1545901005-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTToCQFhAYRMgObGgbSjC%2Fuploads%2FV89o79d3urx40FHQswwW%2Foffblocks-api-spec_master_api.yaml?alt=media&token=762e0468-4f4f-407e-9281-df4ee98be768>" path="/auth/signing" method="put" %}
[offblocks-api-spec\_master\_api.yaml](https://1545901005-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTToCQFhAYRMgObGgbSjC%2Fuploads%2FV89o79d3urx40FHQswwW%2Foffblocks-api-spec_master_api.yaml?alt=media\&token=762e0468-4f4f-407e-9281-df4ee98be768)
{% endopenapi %}

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

{% openapi src="<https://1545901005-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTToCQFhAYRMgObGgbSjC%2Fuploads%2FV89o79d3urx40FHQswwW%2Foffblocks-api-spec_master_api.yaml?alt=media&token=762e0468-4f4f-407e-9281-df4ee98be768>" path="/auth/signing" method="delete" %}
[offblocks-api-spec\_master\_api.yaml](https://1545901005-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTToCQFhAYRMgObGgbSjC%2Fuploads%2FV89o79d3urx40FHQswwW%2Foffblocks-api-spec_master_api.yaml?alt=media\&token=762e0468-4f4f-407e-9281-df4ee98be768)
{% endopenapi %}

### 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](https://www.ietf.org/archive/id/draft-ietf-httpbis-digest-headers-13.html), 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.

{% hint style="info" %}
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
{% endhint %}