Skip to main content

Signing requests

To ensure request authenticity and protect transaction data from tampering, all transaction creation requests must be signed using the RSA-SHA256 algorithm.

Overview​

Each request must be signed using your RSA private key.

When a request is received, Guardarian verifies the signature using the public key associated with your account:

  • If the signature is valid, the transaction is processed.
  • If the signature validation fails, the request is rejected.

Generate an RSA key pair​

Generate a private key:

openssl genpkey \
  -algorithm RSA \
  -out private_key.pem \
  -pkeyopt rsa_keygen_bits:2048

Generate a public key from the private key:

openssl rsa \
  -pubout \
  -in private_key.pem \
  -out public_key.pem

Verify that the keys match:

openssl rsa -in private_key.pem -pubout -outform DER \
| openssl sha256

# Compare with

openssl rsa -pubin -in public_key.pem -outform DER \
| openssl sha256

The resulting hashes must be identical.

Share the public key​

Send the generated public key to Guardarian using a secure communication channel.

For example:

  • GPG-encrypted message
  • Secure file transfer
  • Any approved secure channel

Keep your private key secure and never share it.

Generate the request signature​

After preparing the final request payload, convert it to a raw JSON string and sign it using your private key.

Node.js example​

import crypto from 'crypto';

function signWithPrivateKey(
  rawBody: string,
  privateKey: string
): string {
  const signer = crypto.createSign('RSA-SHA256');

  signer.update(rawBody);
  signer.end();

  const signature = signer.sign(privateKey);

  return signature.toString('base64');
}

Add the signature header​

After generating the signature, include it in the request headers:

Partner-Signature: <base64_signature>

Example​

Partner-Signature: qweqweqwdqwdqwd

Signing flow​

  1. Build the request body.
  2. Convert it to a JSON string.
const rawBody = JSON.stringify(bodyObject);
  1. Generate the RSA-SHA256 signature using your private key.
  2. Add the generated signature to the Partner-Signature header.
  3. Send the request.

Example​

const rawBody = JSON.stringify(bodyObject);

const signature = signWithPrivateKey(
  rawBody,
  privateKeyPem
);

await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Partner-Signature': signature,
  },
  body: rawBody,
});

Important​

The signature must be calculated from the final request body.

Any modification to the request body after the signature has been generated will invalidate the signature and cause the request to be rejected.

For this reason:

  • Build the complete payload first.
  • Convert it to a raw JSON string.
  • Generate the signature.
  • Send the exact same payload that was signed.

Requirements​

Partners must ensure that:

  1. A unique RSA key pair is generated and maintained securely.
  2. The public key is shared with Guardarian.
  3. Every request is signed using the RSA-SHA256 algorithm.
  4. The signature is generated from the final raw request body.
  5. The generated signature is included in the Partner-Signature header.

Requests with missing or invalid signatures will be rejected.