8/8/22, 23:14 API Co-Signer Setup – Fireblocks Help Center

ֿ
Anibal Garrido

Fireblocks Help Center

>
Developer Guide
>
API Co-Signer

Search

Articles in this section

API Co-Signer Setup

3 months ago ·
Updated

Follow

Overview
The API Co-Signer automates transaction signing, wallet approvals, and other approvals initiated via
the API. 

The co-signer is deployed on a cloud environment, or on-site at a customer's premises. The co-
signer secures the following inside a secure Intel SGX Enclave: 

1. The set of keys required for signing and approving

2. An MPC key share

The co-signer can be optionally configured to work with a Co-Signer Callback Handler, an HTTPS
server that can approve or reject signing and whitelisting requests based on custom logic
implemented by the customer.

Co-signer transaction flow

The process for generating and signing a Fireblocks transaction using Fireblocks REST API service
and the co-signer is as follows:

https://support.fireblocks.io/hc/en-us/articles/360015865300-API-Co-Signer-Setup 1/10
8/8/22, 23:14 API Co-Signer Setup – Fireblocks Help Center

1. An API transaction request is made to the Fireblocks REST API service. A new transaction is
submitted via this API endpoint. The transaction is generated on the Fireblocks backend and
sent to all co-signers for signing.  
2. The co-signer located in the customer’s secure environment continually polls the Fireblocks
SaaS for transactions to sign. If a transaction is available, Fireblocks responds with transaction
details.
3. If the callback handler is not set up, the transaction is approved and proceeds to step 5. If the
callback handler is set up, the co-signer sends an approval request to the HTTPS server
callback handler. 
4. The callback handler responds, either approving or rejecting the transaction.
5. Upon approval, the API co-signer engages with the other co-signers on Fireblocks to start a
mutual transaction signing process.

Co-signer prerequisites

1. API users: In order to set up the co-signer, you must first hold an API key with signing
permissions. Please follow these instructions to set up your API key. 
2. Callback handler [optional]: The co-signer can be provisioned together with the callback
handler. The callback handler processes POST requests and responds back with an approval
or rejection response.
For details on how to handle the response request and structure, please see the API Signer
Callback.
Note: The HTTPS server for the Callback Handler doesn’t need to reside inside the SGX
enclave. It can run on any cloud provider or on-premises. 

Setup
Step 1: Co-Signer Machine Provisioning

The co-signer machine should be SGX-enabled. For more details on how to provision an SGX-
enabled machine read here.

Make sure the machine meets the following technical and security requirements:

OS - Ubuntu 20.04
Latest Linux kernel version
Latest Intel microcode (BIOS update).  Note that the microcode is automatically updated on
Azure

https://support.fireblocks.io/hc/en-us/articles/360015865300-API-Co-Signer-Setup 2/10
8/8/22, 23:14 API Co-Signer Setup – Fireblocks Help Center

No inbound connections
Outbound - only port 443
Installation phase requires Docker registry, auth port 443 and 5000 for transport

Step 2: Co-Signer Callback Handler Setup

Set up an HTTPS server on your internal IT environment that handles approval requests from the
co-signer by exposing these endpoints. This URL should be accessible to the co-signer machine for
POST requests.

It is required to use HTTPS (not HTTP) To do so, issue a certificate signed by a CA.

Generate a private key using the following command:

openssl genrsa -out private.pem 2048

Export a public key from the previously generated private key using the following command:

openssl rsa -in private.pem -outform PEM -pubout -out public.pem

It is recommended that the callback handler verifies each call it gets from the API Co-Signer. The
API Co-Signer's public key is required for this verification. To extract the API Co-Signer's public key
please use the following command after the API Co-Signer is fully installed:

./cosigner print-public-key

Find an example implementation of a callback handler here.

Step 3: Co-Signer Software Installation

On the co-signer machine:

1. Enter root mode:

sudo -i

2. Download Fireblocks Co-Signer CLI script (the download link will be provided to you
separately by the Fireblocks support team):

curl -o cosigner "<<URL Download Link>>"

https://support.fireblocks.io/hc/en-us/articles/360015865300-API-Co-Signer-Setup 3/10
8/8/22, 23:14 API Co-Signer Setup – Fireblocks Help Center

3. Change the script's permissions to be executable:

chmod +x cosigner

4. If you plan to use an API Co-Signer Callback Handler, place a copy of the Callback Handler's
public key under the same folder as the CLI script. The API Co-Signer will use the public key
on every call made to the callback handler to verify the callback handler is the one
responding.  (See Callback Handler Setup for more details).
5. To verify secure communication (HTTPS) with the Co-Signer Callback Handler you may run
the following command:

openssl s_client -connect <callback_handler_url>:443

6. Run the CLI script to start the cosigner setup:

./cosigner setup

7. The script will request you to enter a pairing token, which is mandatory:

Please enter pairing token from the Fireblocks console

This token can be extracted from the Fireblocks web console admin page. As an admin, log in
to the Fireblocks console, navigate to the “Admin Settings” > "Users" tab, or simply follow this
link. In the status column for the API user there will be a tooltip. Click on the tooltip to view and
copy the pairing token. This token will be available only for API users assigned a Signer or
Admin role that are not paired with a signing device. The pairing token is valid for 1 hour.

8. The script will request you to enter a Callback Handler URL, which is optional:

Please enter callback URL (if using callback URL, else empty) 

Please enter the HTTPS server base URL where the Co-Signer Callback is or will be
available. (See Callback Handler Setup for more details.) If you don't have the callback URL
available at this stage you can provide it at a later stage as a Configuration Update.

https://support.fireblocks.io/hc/en-us/articles/360015865300-API-Co-Signer-Setup 4/10
8/8/22, 23:14 API Co-Signer Setup – Fireblocks Help Center

9. If a callback handler URL was entered, the script will request you to choose an authentication
method:

Please select one of the callback authentication options: (1)-PUBLIC

If you choose PUBLIC KEY you will be requested to paste your public key:

Please paste your callback public key

Paste the key and press return

If you choose a certificate, 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

If you enter "n" to choose no, you will be requested to paste your certificate:

Need certificate for domain <URL domain>, please paste your ce

The CLI script verifies the underlying hardware and installs the drivers that support the correct
version of SGX and the co-signer executable. The installation process includes an attestation flow
that assures that the co-signer executable runs inside a secure Intel SGX enclave.

At the end of the process, the co-signer generates a JSON configuration file that can be used for
future configuration updates.

Please start the co-signer:

./cosigner start

If you are running the co-signer for the first time, an "Add User" request will appear on the
workspace owner's mobile device to approve the co-signer.

Backup & Recovery

There are 3 important locations useful for backup and recovery purposes: 

https://support.fireblocks.io/hc/en-us/articles/360015865300-API-Co-Signer-Setup 5/10
8/8/22, 23:14 API Co-Signer Setup – Fireblocks Help Center

1. /databases/cosigner/db - The Co-Signer's DB folder stores the secrets.db file, the Co-
Signer’s secrets database. This db file is encrypted with a key generated inside a secure SGX
enclave.
2. /databases/cosigner/backup - The backup folder maintained by the Co-Signer stores the
backed-up secrets.db upon any change in the database. The files are in the following format
%Y%m%d%H%M%S.db (e.g. 20200802155950.db) based on when the backup was made.
3. /databases/cosigner/enclave/ra_loader_enclave.signed.so - The enclave loader. For future
seamless migration to a different server, please backup this file.

Recovery on the Same Machine

If you migrated your Azure instance to a different server or you restarted your current server, run the
following command line to initiate the Co-Signer (the assumption here is that all the files under
/databases/cosigner were kept in place):

./cosigner start

Deployment on a New Server

There are 2 migration options:

1. If you backed up secrets.db and ra_loader_enclave.signed.so, please copy these two files

to the following locations on the new server:

/databases/cosigner/db/secrets.db

/databases/cosigner/enclave/ra_loader_enclave.signed.so

After the files above have been copied to the new server, please run:

./cosigner start

2. If you didn't backup either of these files, please contact Fireblocks support and ask to reset
your co-signer keys. Once reset, please follow the steps in the Setup Section.

Configuration Updates
Users can update the callback handler URL (callback_handler_url), by running:

https://support.fireblocks.io/hc/en-us/articles/360015865300-API-Co-Signer-Setup 6/10
8/8/22, 23:14 API Co-Signer Setup – Fireblocks Help Center

./cosigner callback-update [user id]

The "user id" is optional and only needed if there are several API users paired to the same Co-
Signer. When running the command in this instance, please specify which user’s callback handler
URL you would like to update. A complete list of all users can be retrieved by running the following
command:

./cosigner list-users

Please note: When updating the callback URL, responses must be signed with the same private key
of the previous callback URL. 

Adding Additional API Users

The API Co-Signer supports signing for multiple API users, either from the same workspace or
different workspaces.

1. To add another user, please run the following CLI script:

./cosigner add-user

2. The script will request you to enter a pairing token, which is mandatory:

Please enter pairing token from the Fireblocks console

This token can be extracted from the Fireblocks web console admin page. As an admin, log in
to the Fireblocks console, navigate to “Admin Settings” > "Users" tab, or simply follow this link.
On the status column of the API user there will be a tooltip. Click on the tooltip to view and
copy the pairing token. This token will be available only to API Signer or Admin users that are
not paired with a signing device. The pairing token is valid for 1 hour.

https://support.fireblocks.io/hc/en-us/articles/360015865300-API-Co-Signer-Setup 7/10
8/8/22, 23:14 API Co-Signer Setup – Fireblocks Help Center

3. The script will request you to enter a Callback Handler URL, which is optional:

Please enter callback URL (if using callback URL, else empty) 

Please enter the HTTPS server base URL where the Co-Signer Callback is or will be
available. (See Callback Handler Setup for more details.) If you don't have the callback URL
available at this stage you can provide it at a later stage as a Configuration Update.

4. If a callback handler URL was entered, the script will request you to choose an authentication
method:

Please select one of the callback authentication options: (1)-PUBLIC

If you choose PUBLIC KEY you will be requested to paste your public key:

Please paste your callback public key

Paste the key and press return.

If you choose certificate, 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

If you enter "n" to choose no, you will be requested to paste your certificate:

Need certificate for domain <URL domain>, please paste your ce

If you are running the Co-Signer for the first time, an "Add User" request will appear on the
workspace owner's mobile device to approve the Co-Signer.

Software Upgrades
Fireblocks will notify the customer when there is an available software update.

To update, please run the following command:

./cosigner upgrade

https://support.fireblocks.io/hc/en-us/articles/360015865300-API-Co-Signer-Setup 8/10
8/8/22, 23:14 API Co-Signer Setup – Fireblocks Help Center

To check for your current API co-signer version, please run the following command:

head cosigner -n 3 | grep VER

Monitoring
The Co-Signer is docker-based and uses the docker json file driver for logging. The default output of
the driver is standard output but can be configured to support other logging mechanisms.

For retrieving Co-Signer logs, please run the following command:

./cosigner logs

The log file is written to the /databases/cosigner/log directory. 

Was this article helpful?

Yes
No

13 out of 15 found this helpful

Have more questions? Submit a request

Return to top

Fireblocks Help Center

https://support.fireblocks.io/hc/en-us/articles/360015865300-API-Co-Signer-Setup 9/10
8/8/22, 23:14 API Co-Signer Setup – Fireblocks Help Center

https://support.fireblocks.io/hc/en-us/articles/360015865300-API-Co-Signer-Setup 10/10