Overview

The API Co-Signer is typically used for signing transactions initiated from the API. The API Co-Signer signs all transactions it retrieves if the callback handler is not configured. The callback handler is an optional component that can approve or reject signing and connection requests based on custom logic. Read more in the API Callback Handler documentation.

This article covers how to set up the API Co-Signer with or without the optional Callback Handler.

Before you begin
Installing the API Co-Signer without a Callback Handler
- Testing the API Co-Signer
Configuring the API Co-Signer with the Callback Handler

Before you begin

Submit a request to Fireblocks Support to download the API Co-Signer installer.
The API Co-Signer requires a secure server. To configure a compatible cloud or on-premises server, follow this article.
- API Co-Signer machine pre-requisites.
In order to set up the API Co-Signer, first, create a dedicated API user with signing permissions and retrieve the API key. Follow these instructions to learn more.
- You must complete the first five API Co-Signer installation steps within an hour of receiving an API Key to pair the API user identified as the "first user on this machine."

Installing the API Co-Signer software without a Callback Handler

Execute the following commands on your API Co-Signer machine:

Enter root mode:
```
sudo -i
```
Download the Fireblocks API Co-Signer Command Line Interface (CLI) script using the download link provided by the Fireblocks Support team as described above:
```
curl -o cosigner "<<URL Download Link>>"
```
You can also download or copy a link to the API Co-Signer script file directly from your Fireblocks Console:
1. Go to Settings > General.
2. Under the Download co-signer script heading:
  - Select Download to download the script file to your default download destination.
  - Select Copy to copy the script file's URL to your clipboard.
Change the script permissions to be executable:
```
chmod +x cosigner
```
Run the CLI script to start the cosigner setup. This setup installs the required files including docker and docker-compose.
```
./cosigner setup
```
The script requests a mandatory pairing token. There is an option to select "First user on this machine" when creating a new API user, as described in this article. If this checkbox was not selected appropriately, this step will fail.
```
Please enter pairing token from the Fireblocks console
```
This token can be retrieved from the Fireblocks console admin page accordingly:
1. As an Admin, log in to the Fireblocks console, navigate to Settings and select the Users tab.
2. Select the Pending Setup user status.
3. Select Copy Pairing Token from the context menu. This token is only available for API users assigned a Signer or Admin role not paired with a signing device yet. The pairing token is valid for one hour.
Continue without entering a callback URL.
The CLI script verifies the hardware and installs the relevant drivers that support the correct SGX version and the API Co-Signer executable. The installation process includes an attestation flow that assures that the API Co-Signer executable runs inside a secure Intel SGX enclave.
At the end of the process, the API Co-Signer generates a JSON configuration file that can be used for future configuration updates. Learn more about updating your API Co-Signer.
Start the API Co-Signer with the following command:
```
./cosigner start
```
If you are running the API Co-Signer for the first time, the workspace owner must approve a new MPC key share request, similar to approving any other user with signing privileges.
To confirm that setup is successful, confirm that only the API Co-Signer image is running. The following command outputs a list of all running containers:
```
docker ps -a
```

Your API co-signer should now be available for use.

Testing the API Co-Signer

Update your Transaction Authorization Policy by opening a support request. The API user associated with the API Co-Signer should be integrated according to your workspace needs.

Initiate a test transaction that expects a signature from the API Co-Signer. Learn more about creating a new transaction in the Developer Portal API documentation.

Confirm that the transaction is signed and completed as expected.

Configuring the API co-signer with Callback Handler

The following describes an overview of the callback handler setup process. Specific details are dependent on your organization's intended use and best practices.

During initial setup, begin by allowing the callback handler to approve all requests for simplicity.

Install the API Co-Signer with callback handler as described below. Then test the configuration by sending a test transaction.

Integrate your custom logic with the callback handler. Test the implementation according to your organization's best practices and current workspace configuration.

Part one: setting up the Callback Handler

Set up an HTTPS server for your callback handler. To do so, issue a certificate either self-signed or signed by a certification authority (CA). This server does not need to be the same as the API Co-Signer. Fireblocks does not recommend any specific location.

However, for security, the sub-network of the API Co-Signer and the Callback Handler should be restricted and avoid open connections to other places like business servers, unless absolutely necessary. This minimizes any chance of attack vectors from other locations that can compromise your transaction signing logic. The signing process should be as reasonably isolated as possible.

Configure the server to handle approval requests from the API Co-Signer by exposing these endpoints. This URL should be accessible to your API Co-Signer machine for POST requests. POST requests will fail if the Callback Handler does not respond within 30 seconds of receiving it.

Set up your HTTPS server and basic Callback Handler logic to accept all requests. Then continue with the following steps. The following commands should be executed on your API co-signer machine:

Enter root mode:
```
sudo -i
```
To verify secure communication (HTTPS) with the Callback Handler, run the following command:
```
openssl s_client -connect <callback_handler_url>:443
```

Part two: authenticating Callback Handler messages

All callback handler requests should be authenticated. The following two options are available for authentication.

Public key authentication

This option is only available from version 1.1.4 and above. This is recommended for all new and upgraded instances. Read more about API Co-Signer version history.

This method uses a Signed JSON Web Token (JWT) for authentications. The POST request including the public key is sent as a JWT-encoded message.

Your callback handler endpoints should respond to requests that include a “/v2” prefix: <https://your_callback_base_url/v2/tx_sign_request>

The following steps output a private key used to authenticate your Callback Handler with your API Co-Signer. The public key is requested during API Co-Signer with Callback Handler installation in part three below.

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

Fireblocks only supports RSA key 2048 bit for public key callback authentication.
Export the public key from the previously generated private key using the following command:
```
openssl rsa -in private.pem -outform PEM -pubout -out public.pem
```
You'll need to place a copy of the public key on your API Co-Signer server during the installation process below.

Certificate authentication

This option requires either a self-signed or CA-signed certificate. CA-signed certificates typically expire frequently and must be renewed. Renewing certificates includes re-enrolling the associated API user and restarting the API co-signer each time the certificate is renewed. This option is no longer recommended and does not require generating a public key as described above.

TLS certificate authentication takes place during SSL negotiation, and the POST request itself is sent as plain text.

Your callback handler endpoints should respond to requests that do not include a “/v2” prefix: <https://your_callback_base_url/tx_sign_request>

Part three: installing the API Co-Signer with Callback Handler

Make sure to complete all steps from the before you begin section above if you plan to install the API Co-Signer and Callback Handler starting here.

Continue by executing the following commands on your API Co-Signer machine:

Download the Fireblocks API Co-Signer Command Line Interface (CLI) script using the download link provided by the Fireblocks support team as described above:
```
curl -o cosigner "<<URL Download Link>>"
```
Enter root mode if it is not already active:
```
sudo -i
```
Change the script permissions to be executable:
```
chmod +x cosigner
```
Place a copy of the public key under the same folder as the CLI script. The API Co-Signer uses the public key to verify every call and response made with your callback handler. See part one for more details.
Start the API Co-Signer with the following command:
```
./cosigner setup
```
The script will request you to enter a mandatory pairing token. There is an option to select "First user on this machine" when creating a new API user, as described in this article. If this checkbox was not selected appropriately, this step will fail.
```
Please enter pairing token from the Fireblocks console
```
This token can be retrieved from the Fireblocks console admin page accordingly:
1. As an admin, log in to the Fireblocks console, navigate to Settings, and select the Users tab.
2. Select the Pending Activation user status.
3. Select Copy Pairing Token from the context menu. This token is only available for API users with a Signer or Admin role that are not yet paired with a signing device. The pairing token is valid for one hour.
Enter the Callback URL. This is the HTTPS server base URL of the API Co-Signer Callback Handler.
```
Please enter callback URL (if using callback URL, else empty)
```
The script will ask to select an authentication method:
```
Please select one of the callback authentication options: (1)-PUBLIC KEY (2)-certificate
```
- Recommended method: If you choose PUBLIC KEY (see part two), paste your public key and press return:
```
Please paste your callback public key
```
- If you choose a certificate (more information), the script can either fetch the certificate from the Callback Handler URL, or you can paste the certificate.
```
Would you like to try to fetch the certificate for <URL> from the web server(y/n)?
```
  - If you enter "n" to choose no, you will be requested to paste your certificate:
```
Need certificate for domain <URL domain>, please paste your certificate
```
The CLI script verifies the underlying hardware and installs the drivers that support the correct SGX version and the API Co-Signer executable. The installation process includes an attestation flow that assures that the API Co-Signer executable runs inside a secure Intel SGX enclave.
At the end of the process, the API Co-Signer generates a JSON configuration file that can be used for future configuration updates. Learn more about updating your API Co-Signer.
Start the API Co-Signer with the following command:
```
./cosigner start
```
If you are running the API Co-Signer for the first time, the workspace owner must approve a new MPC Key request from the Fireblocks mobile app, similar to approving any other user with signing permission.
To confirm that setup is successful, confirm that only the API Co-Signer image is running. The following command outputs a list of all running containers:
```
docker ps -a
```

Your API Co-Signer and HTTPS Callback Handler should now be available for use.

Part four: testing the API Co-Signer and Callback Handler

Update your Transaction Authorization Policy by opening a Support request if you have not done so already. The API user associated with the API Co-Signer should be integrated according to your workspace needs.

Initiate a test transaction that expects a signature from the API Co-Signer. Learn more about creating a new transaction in the Developer Portal API documentation.

Confirm that the transaction is signed and completed as expected.

Integrating the Callback Handler with the API Co-Signer

Build and implement your callback handler logic and confirm that transactions are approved and rejected as expected. Copy your public key as described below to include in your callback handler integration for the recommended authentication method.

Continue to monitor your callback handler logic for expected behavior after any changes are made.

Part five: authenticating Callback Handler requests from the API Co-Signer

The Callback Handler should authenticate each call it receives from your API Co-Signer to prevent any attempt to sign requests from a malicious source.

Print the public key to include in your Callback Handler integration. This is required for the recommended authentication method as described in part two.

Enter the following command after installing the API Co-Signer to extract the API Co-Signer public key:

./cosigner print-public-key

Learn more about Callback Handler code examples in our API documentation.

API Co-Signer setup

Overview

Contents

Before you begin

Installing the API Co-Signer software without a Callback Handler

Testing the API Co-Signer

Configuring the API co-signer with Callback Handler

Part one: setting up the Callback Handler

Part two: authenticating Callback Handler messages

Public key authentication

Important

Certificate authentication

Part three: installing the API Co-Signer with Callback Handler

Part four: testing the API Co-Signer and Callback Handler

Integrating the Callback Handler with the API Co-Signer

Part five: authenticating Callback Handler requests from the API Co-Signer

Overview

Contents

Before you begin

Installing the API Co-Signer software without a Callback Handler

Testing the API Co-Signer

Configuring the API co-signer with Callback Handler

Part one: setting up the Callback Handler

Part two: authenticating Callback Handler messages

Public key authentication

Important

Certificate authentication

Part three: installing the API Co-Signer with Callback Handler

Part four: testing the API Co-Signer and Callback Handler

Integrating the Callback Handler with the API Co-Signer

Part five: authenticating Callback Handler requests from the API Co-Signer

Related Articles