Guides
We are hiring

QSEAL: Signature

Suggest Edits

❗️

This section applies only to Regulated partners.

HTTP Signature

The request must be signed with your QSEAL certificate according to the draft specification https://datatracker.ietf.org/doc/draft-cavage-http-signatures/.

The algorithm used for the signature must be RSA-SHA256

At least the following headers and their content must be signed using your QSEAL

(request-target)
date
psu-ip-address
psu-ip-port
psu-http-method
psu-date psu-user-agent
psu-referer psu-accept
psu-accept-charset
psu-accept-encoding
psu-accept-language

The Signature header must include the signature containing the following fields:

  • keyId (your organization identifier)
  • algorithm (rsa-sha256)
  • headers (list of signed headers)
  • signature
Signature='keyId="PSDFR-ACPR-XXXXX",algorithm="rsa-sha256",headers="(request-target) date psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language",signature="OkLTdS4RUygYG7jIuekxJE1LLRnepTNEOr7UnqbRO2wJhYoSnmvRsnR9/HBOGaWPHADwdErSNi8W/muAtGF+xNpsfylrZl0Q2lZT2Wqgq6gRbcVMf1pRhU8VA4IYLuAwVrujIbdimrhIFBq2KKyPfOHce8v52/Zj/RrbEq2oW0NMPBh5PqNIlMY/zml1ZbBaprK6zxObhNpU6uhp3w2ZdXK5lmkD64bGVFlYTqn3c1FDTw62wgjEUtUGw62qwftOP9nE/bVHhERGqQN33HozdpSl6j+QZgVUgClZZrhKFOUbkUfhO8EosWEcTccnweR49JhMcYebBwJY3uuhVUmXCg=="'

If your request contains a body, you will need to add a signed digest header.
Here is an example to generate a body digest:

const crypto = require('crypto');

/**
Generates a cryptographic digest using the SHA256 algorithm and a private key to sign it in base64 encoding.
@param {string} body
@param {string | Buffer} privateKek
@returns {string} - The signed hash in base64 encoding.
*/
const generateDigest = (body, privateKey) => {
  const sign = crypto.createSign('SHA256');
  sign.write(body);
  sign.end();
  return sign.sign(privateKey, 'base64');
};

When you receive a response from our gateway, you must verify the signature contained in the Authorization header and ensure all the required headers and their content are signed.

You will be able to get our QSEAL certificate at the URI present in the keyId field.

Here is an example how to verify the HTTP signature:

const crypto = require('crypto');

/**
Validates the signature of a cryptographic digest using the SHA256 algorithm and a public key.
@param {string} body
@param {string} signature - The signed hash in base64 encoding.
@param {string | Buffer} publicKey
@returns {boolean} - Whether or not the signature is valid.
*/
const validateSignature = (body, signature, shinePublicKey) => {
  const verify = crypto.createVerify('SHA256');
  verify.write(body);
  verify.end();
  return verify.verify(shinePublicKey, signature, 'base64');
};

Code example

A complete example for connecting to Shine Connect's regulated partners API is provided here: https://github.com/shinetools/shine-connect-example

Updated 2 months ago