Develop & Integrate
Explore & DesignDevelop & IntegrateEmbedded Wallet GuidesChangelogCommunityStatusRequest Demo

Establishing secure communication between the Co-signer and the Callback Handler

Developers - WIP

📘

Learn more about the architecture of the API Co-Signer Callback Handler here


When configuring the Callback Handler server for an API user that is paired with the Co-signer, you can select one of the following options to secure the communication between the Co-signer (which acts as a client) and the Callback Handler server.


Option 1: Public key authentication

In this option, the Co-signer and the Callback Handler exchange JSON Web Token (JWT) encoded messages, each signed with their respective private keys. The Co-signer's POST request to the Callback Handler server and the Callback Handler's response to the Co-signer are authenticated using their corresponding public keys.


JWT-encoded signed request

  • The Co-signer, acting as a client of the Callback Handler server, sends a POST request and uses its private key to sign the JWT-encoded message.
  • The Callback Handler uses the Co-signer's public key to authenticate the message and ensure it originated from the Co-signer.
  • You can retrieve the Co-signer's public key directly from the Co-signer (see the guides).

Note: The same Co-signer private key is used to sign request messages sent to the Callback Handler server for all API users paired with this Co-signer.


JWT-encoded signed response

  • The Callback Handler responds with a JWT-encoded message signed with its private key.
  • The Co-signer uses the Callback Handler's public key to authenticate the message and ensure it originated from it.
  • You provide the API user's Callback Handler public key to the Co-signer during installation or while configuring the Callback Handler for that API user. This public key corresponds to the private key used by the Callback Handler to sign JWT-encoded response messages.

Follow these steps to generate a private-public key pair for signing JWT-encoded responses. This allows the Co-signer to authenticate your Callback Handler's responses using the corresponding public key:

  1. Generate a private key using the following command:
openssl genrsa -out callback_private.pem 2048

Note: Only RSA 2048 bit keys are supported for public key Callback Handler response authentication.

  1. Export the public key from the previously generated private key using the following command:
openssl rsa -in callback_private.pem -outform PEM -pubout -out callback_public.pem
  1. Use this public key to configure the Co-signer's Callback Handler for the specified API user.
  2. Set up the Callback Handler as an HTTPS server using a certificate signed by a trusted Certificate Authority (CA). Configure the Callback Handler endpoints to include a /v2 prefix in their response URLs:

https://your_callback_base_url/v2/tx_sign_request
or
https://your_callback_base_url/v2/config_change_sign_request


Communication channel security

TLS communication between the Co-signer and the Callback Handler server requires the Callback Handler to operate as an HTTPS server with a certificate signed by a trusted Certificate Authority (CA).



Option 2: Certificate-based communication

In this option, a self-signed certificate or a certificate signed by a trusted Certificate Authority (CA) is used to establish certificate-pinning-based secure communication between the Co-signer and the Callback Handler. TLS certificate authentication occurs during SSL negotiation and is based on the certificate you provide to the Co-signer.

The certificate is provided to the Co-signer during installation or while configuring the Callback Handler for a specific API user. In this setup, both the Co-signer's POST request to the Callback Handler server and the server's response are in JSON format, instead of using signed JWTs.

Create a certificate and sign it yourself or have it signed by a trusted CA, set up an HTTPS server and configure your Callback Handler endpoints to respond to requests that do not include a /v2 prefix:

https://your_callback_base_url/tx_sign_request
or
https://your_callback_base_url/config_change_sign_request



📘

Note:

When adding the Callback Handler URL to the Co-signer, you should pass only the base URL + custom relative path.
The /v2/tx_sign_request or /v2/config_change_sign_request relative paths will be automatically added upon each request made by the Co-signer.

For example if you exposed the Callback Handler URL in the following path:
https://subdomain.example.com/fireblocks/callback_handler/v2/tx_sign_request

You should configure the following URL in the Co-signer:
https://subdomain.example.com/fireblocks/callback_handler