Skip to main content

Scorechain's Proof Of Authenticity

Overview​

To ensure that responses from our API are genuine and untampered, we implemented a signature based on the RSASSA-PKCS1-v1_5 standard (RFC8017#8.2). This system cryptographically signs API responses, allowing clients to verify their authenticity.

How it works ?​

  • Hashing the Payload: Scorechain's API generates a SHA-256 hash of the response payload and a server timestamp. This ensures the payload remains compact and secure, even for large objects.

  • Signing the Hash: The hash is signed using the API's private RSA key (RSA-SHA256 algorithm). This signature is included in the response header.

  • Public Key Retrieval: The API provides an endpoint for clients to fetch the public RSA key required to verify the signature.

  • Verification: Clients can use the public key to verify the response signature, ensuring it was generated by the API and has not been tampered with.

Response Headers​

Header NameDescription
X-SignatureThe signature containing the hash of the payload the server timestamp both encrypted.
X-Server-TimeThe server's timestamp at the moment the response was signed. Useful for preventing replay attacks.

Verification Process​

To simplify the verification process, we have implemented the necessary validation logic in our SDK. Depending on your use case, you have three options:

  • You already use the SDK

If you are already using the SDK then the proof of authenticity checks will be running without changing anything.

  • You have an API integration without the SDK

Even if you are not using our SDK for your integration, you can still take advantage of the exported verification function.

To get started, install our SDK:

npm install scorechain-sdk

Then, in your code, add the following:

const { proofOfAuthenticityVerifier } = require("scorechain-sdk");

proofOfAuthenticityVerifier(payload, token, publicKey, headerServerTimestamp)

Here’s what each parameter represents:

  • payload: the response body received from our API,
  • token: the signature found in x-signature header,
  • publicKey: the publicKey that can be retrieved from the API,
  • headerServerTimestamp: is the server timestamp found in x-server-time header.

If there is an issue with the verification, the function will throw an error, allowing you to handle it appropriately.

  • Your integration is not developped in JS

If your application is not developed in JavaScript, you will need to implement the verification logic manually. Below is a diagram illustrating the verification process you need to follow:

⚠️ Important Note

If the verification fails, it could be due to a change in our backend private keys. To mitigate this, we strongly recommend periodically checking the /publicKeys endpoint to ensure your local public key is up to date and not deprecated.