Skip to main content

API Co-Signer setup

  • Updated

Overview

The API Co-Signer is typically used for signing transactions and approving workspace configuration changes initiated from the API. The API Co-Signer signs all transactions and approves all configuration changes 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.

Contents

Before you begin

  1. The API Co-Signer requires a secure server. To configure a compatible cloud or on-premises server, follow this article.
  2. 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:

  1. Enter root mode: 
    sudo -i
  2. Use the steps below to copy a link to the API Co-Signer script file directly from your Fireblocks Console. If you have any issues with these steps, please contact Fireblocks Support. 
      1. Go to Settings > General.
      2. Under the Download co-signer script heading select Copy to copy the script file's URL to your clipboard.
        download_api-co-signer_script.png
  3. Enter the command using the link you just copied:
    curl -o cosigner "<<URL Download Link>>"
  4. Change the script permissions to be executable: 
    chmod +x cosigner
  5. Run the CLI script to start the cosigner setup. This setup installs the required files including docker and docker-compose.
    ./cosigner setup
  6. 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.
      mceclip3.png
  7. Continue without entering a callback URL.
  8. 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.
  9. 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.
  10. Start the API Co-Signer with the following command: 
    ./cosigner start
  11. 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.
  12. 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 using the editor in your Fireblocks Console. The API user associated with the API Co-Signer should be integrated according to your workspace needs. Learn more about building TAP rules.

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.

Note

Each API co-signer must have its own designated callback handler. You can't use the same callback handler for multiple API co-signers.

Part one: setting up the Callback Handler

Set up an HTTPS server for your callback handler. Fireblocks recommends you use a different server for the callback handler than the one used for the API Co-Signer. We do not recommend any specific location.

Note

An SGX server is not required for the callback handler.

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:

  1. Enter root mode: 
    sudo -i
  2. 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.

Option 1: Public key authentication

This option requires an HTTPS server with a certificate signed by a trusted certificate authority (CA), and it 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.

The following steps output a private key used to authenticate your Callback Handler with your API Co-Signer.

  1. 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.

  2. 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
  3. Write your callback logic, which should include checking that the message can be decoded using the API Co-Signer public key. The API Co-Signer public key can be obtained by running the command: 
    ./cosigner print-public-key
  4. Set up an HTTPS server with a certificate signed by a trusted CA. Make sure the server has a "/v2" prefix. Your callback handler endpoints should respond to requests that include a “/v2” prefix: <https://your_callback_base_url/v2/tx_sign_request>
  5. Place a copy of the public key on the API Co-Signer in the same folder as the CLI script. The public key is requested during API Co-Signer installation with Callback Handler in part three below.

The following sections explain how to configure this server as the callback handler for the API co-signer and how to test the callback handler by sending transactions.

Certificate authentication

This option requires an HTTPS server with either a self-signed certificate or a certificate signed by a trusted certificate authority (CA). This option is no longer recommended and does not require generating a public key as described above.

  1. Create a certificate, and sign it yourself or have it signed by a trusted CA.

    Note

    Typically, certificates 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.

  2. Write your callback logic.
  3. Set up an HTTPS server with the certificate from step 1. TLS certificate authentication occurs during SSL negotiation, and the POST request is sent as plain text in JSON format. Your callback handler endpoints should respond to requests that do not include a “/v2” prefix: <https://your_callback_base_url/tx_sign_request>

The following sections explain how to configure this server as the callback handler for the API co-signer and how to test the callback handler by sending test transactions.

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:

  1. Retrieve the Fireblocks API Co-Signer Command Line Interface (CLI) script using the link available in the Fireblocks Console as described above:
    curl -o cosigner "<<URL Download Link>>"
  2. Enter root mode if it is not already active: 
    sudo -i
  3. Change the script permissions to be executable: 
    chmod +x cosigner
  4. 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.
  5. Start the API Co-Signer with the following command:
    ./cosigner setup
  6. 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.
      mceclip0.png
  7. 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)
  8. 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
  9. 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.
  10. 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.
  11. Start the API Co-Signer with the following command: 
    ./cosigner start
  12. 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.
  13. 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 using the editor in your Fireblocks Console if you have not done so already. The API user associated with the API Co-Signer should be integrated according to your workspace needs. Learn more about building TAP rules.

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 transaction signing and configuration approvals in the Developer Portal.

Operating the API Co-Signer

Your API Co-Signer should now be fully operational. Learn more about the API Co-Signer Command Line Interface (CLI), monitoring the API Co-Signer, and pairing additional API users with a single API Co-Signer instance.

Was this article helpful?
1 out of 2 found this helpful

Related Articles