π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
Creating an ECDSA key pair for accessing our API is a straightforward process that involves just two commands:
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-----
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 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
Unique ID of your key. This is different to your public key itself, and is required to sign your requests
86b59965-6cf1-4633-9148-92848330fd1b
Base64 encoded public key used for signing requests. Requirements for cryptographic algorithms and more details can be found in our documentation
LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUUzTEw1RldmVFgvL3BJaXNEL0xneFVIT2lxdlFTSUVWTgpGekloOTdLZXBlWk1iZVZsUGd1akZ4Yk5MN2x1ZVhRQnBpUWUzNmZLN0xSbXZNNHdEaWZFTkE9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0=
PUT /v1/auth/signing HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 303
{
"signingKeyId": "86b59965-6cf1-4633-9148-92848330fd1b",
"signingKey": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUUzTEw1RldmVFgvL3BJaXNEL0xneFVIT2lxdlFTSUVWTgpGekloOTdLZXBlWk1iZVZsUGd1akZ4Yk5MN2x1ZVhRQnBpUWUzNmZLN0xSbXZNNHdEaWZFTkE9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0="
}
No content
Additionally, previously uploaded keys can be updated using the same endpoint or permanently removed using a DELETE
request to /auth/signing
.
Delete public key used to sign API requests
Unique ID of your key. This is different to your public key itself, and is required to sign your requests
86b59965-6cf1-4633-9148-92848330fd1b
DELETE /v1/auth/signing HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 55
{
"signingKeyId": "86b59965-6cf1-4633-9148-92848330fd1b"
}
No content
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.
Last updated